?????????? ????????? - ??????????????? - /home/agenciai/public_html/cd38d8/site-packages.tar
???????
greenlet-3.2.3.dist-info/INSTALLER 0000644 00000000004 15125143220 0012152 0 ustar 00 pip greenlet-3.2.3.dist-info/WHEEL 0000644 00000000224 15125143220 0011465 0 ustar 00 Wheel-Version: 1.0 Generator: setuptools (80.9.0) Root-Is-Purelib: false Tag: cp39-cp39-manylinux_2_24_x86_64 Tag: cp39-cp39-manylinux_2_28_x86_64 greenlet-3.2.3.dist-info/METADATA 0000644 00000007755 15125143220 0012021 0 ustar 00 Metadata-Version: 2.4 Name: greenlet Version: 3.2.3 Summary: Lightweight in-process concurrent programming Home-page: https://greenlet.readthedocs.io/ Author: Alexey Borzenkov Author-email: snaury@gmail.com Maintainer: Jason Madden Maintainer-email: jason@seecoresoftware.com License: MIT AND Python-2.0 Project-URL: Bug Tracker, https://github.com/python-greenlet/greenlet/issues Project-URL: Source Code, https://github.com/python-greenlet/greenlet/ Project-URL: Documentation, https://greenlet.readthedocs.io/ Project-URL: Changes, https://greenlet.readthedocs.io/en/latest/changes.html Keywords: greenlet coroutine concurrency threads cooperative Platform: any Classifier: Development Status :: 5 - Production/Stable Classifier: Intended Audience :: Developers Classifier: Natural Language :: English Classifier: Programming Language :: C Classifier: Programming Language :: Python Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: 3 :: Only Classifier: Programming Language :: Python :: 3.9 Classifier: Programming Language :: Python :: 3.10 Classifier: Programming Language :: Python :: 3.11 Classifier: Programming Language :: Python :: 3.12 Classifier: Programming Language :: Python :: 3.13 Classifier: Operating System :: OS Independent Classifier: Topic :: Software Development :: Libraries :: Python Modules Requires-Python: >=3.9 Description-Content-Type: text/x-rst License-File: LICENSE License-File: LICENSE.PSF Provides-Extra: docs Requires-Dist: Sphinx; extra == "docs" Requires-Dist: furo; extra == "docs" Provides-Extra: test Requires-Dist: objgraph; extra == "test" Requires-Dist: psutil; extra == "test" Dynamic: author Dynamic: author-email Dynamic: classifier Dynamic: description Dynamic: description-content-type Dynamic: home-page Dynamic: keywords Dynamic: license Dynamic: license-file Dynamic: maintainer Dynamic: maintainer-email Dynamic: platform Dynamic: project-url Dynamic: provides-extra Dynamic: requires-python Dynamic: summary .. This file is included into docs/history.rst Greenlets are lightweight coroutines for in-process concurrent programming. The "greenlet" package is a spin-off of `Stackless`_, a version of CPython that supports micro-threads called "tasklets". Tasklets run pseudo-concurrently (typically in a single or a few OS-level threads) and are synchronized with data exchanges on "channels". A "greenlet", on the other hand, is a still more primitive notion of micro-thread with no implicit scheduling; coroutines, in other words. This is useful when you want to control exactly when your code runs. You can build custom scheduled micro-threads on top of greenlet; however, it seems that greenlets are useful on their own as a way to make advanced control flow structures. For example, we can recreate generators; the difference with Python's own generators is that our generators can call nested functions and the nested functions can yield values too. (Additionally, you don't need a "yield" keyword. See the example in `test_generator.py <https://github.com/python-greenlet/greenlet/blob/adca19bf1f287b3395896a8f41f3f4fd1797fdc7/src/greenlet/tests/test_generator.py#L1>`_). Greenlets are provided as a C extension module for the regular unmodified interpreter. .. _`Stackless`: http://www.stackless.com Who is using Greenlet? ====================== There are several libraries that use Greenlet as a more flexible alternative to Python's built in coroutine support: - `Concurrence`_ - `Eventlet`_ - `Gevent`_ .. _Concurrence: http://opensource.hyves.org/concurrence/ .. _Eventlet: http://eventlet.net/ .. _Gevent: http://www.gevent.org/ Getting Greenlet ================ The easiest way to get Greenlet is to install it with pip:: pip install greenlet Source code archives and binary distributions are available on the python package index at https://pypi.org/project/greenlet The source code repository is hosted on github: https://github.com/python-greenlet/greenlet Documentation is available on readthedocs.org: https://greenlet.readthedocs.io greenlet-3.2.3.dist-info/RECORD 0000644 00000024110 15125143220 0011577 0 ustar 00 ../../../include/python3.9/greenlet/greenlet.h,sha256=sz5pYRSQqedgOt2AMgxLZdTjO-qcr_JMvgiEJR9IAJ8,4755 greenlet-3.2.3.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4 greenlet-3.2.3.dist-info/METADATA,sha256=4LPtpV-ZBD7xpjTg5BKO5apQWLITbBym_tFpzsdSRak,4077 greenlet-3.2.3.dist-info/RECORD,, greenlet-3.2.3.dist-info/WHEEL,sha256=5cnYvxs4RIuZUYa8fXyu_LTBVMr4WHQzLNjLaC72XD8,148 greenlet-3.2.3.dist-info/licenses/LICENSE,sha256=dpgx1uXfrywggC-sz_H6-0wgJd2PYlPfpH_K1Z1NCXk,1434 greenlet-3.2.3.dist-info/licenses/LICENSE.PSF,sha256=5f88I8EQ5JTNfXNsEP2W1GJFe6_soxCEDbZScpjH1Gs,2424 greenlet-3.2.3.dist-info/top_level.txt,sha256=YSnRsCRoO61JGlP57o8iKL6rdLWDWuiyKD8ekpWUsDc,9 greenlet/CObjects.cpp,sha256=OPej1bWBgc4sRrTRQ2aFFML9pzDYKlKhlJSjsI0X_eU,3508 greenlet/PyGreenlet.cpp,sha256=ogWsQ5VhSdItWRLLpWOgSuqYuM3QwQ4cVCxOQIgHx6E,23441 greenlet/PyGreenlet.hpp,sha256=2ZQlOxYNoy7QwD7mppFoOXe_At56NIsJ0eNsE_hoSsw,1463 greenlet/PyGreenletUnswitchable.cpp,sha256=PQE0fSZa_IOyUM44IESHkJoD2KtGW3dkhkmZSYY3WHs,4375 greenlet/PyModule.cpp,sha256=J2TH06dGcNEarioS6NbWXkdME8hJY05XVbdqLrfO5w4,8587 greenlet/TBrokenGreenlet.cpp,sha256=smN26uC7ahAbNYiS10rtWPjCeTG4jevM8siA2sjJiXg,1021 greenlet/TExceptionState.cpp,sha256=U7Ctw9fBdNraS0d174MoQW7bN-ae209Ta0JuiKpcpVI,1359 greenlet/TGreenlet.cpp,sha256=HGYGKpmKYqQ842tASW-QaaV8wua4a5XV_quYKPDsV_Y,25731 greenlet/TGreenlet.hpp,sha256=zMakwTJ30onkLiAq5h1WR7ewEkiJXKM0N9AR6BnXQMI,28141 greenlet/TGreenletGlobals.cpp,sha256=YyEmDjKf1g32bsL-unIUScFLnnA1fzLWf2gOMd-D0Zw,3264 greenlet/TMainGreenlet.cpp,sha256=fvgb8HHB-FVTPEKjR1s_ifCZSpp5D5YQByik0CnIABg,3276 greenlet/TPythonState.cpp,sha256=vBMJT9qScTSIqhnOTVJqsGug3WbKv9dDt0cOqyhUk8w,15779 greenlet/TStackState.cpp,sha256=V444I8Jj9DhQz-9leVW_9dtiSRjaE1NMlgDG02Xxq-Y,7381 greenlet/TThreadState.hpp,sha256=2Jgg7DtGggMYR_x3CLAvAFf1mIdIDtQvSSItcdmX4ZQ,19131 greenlet/TThreadStateCreator.hpp,sha256=uYTexDWooXSSgUc5uh-Mhm5BQi3-kR6CqpizvNynBFQ,2610 greenlet/TThreadStateDestroy.cpp,sha256=36yBCAMq3beXTZd-XnFA7DwaHVSOx2vc28-nf0spysU,8169 greenlet/TUserGreenlet.cpp,sha256=uemg0lwKXtYB0yzmvyYdIIAsKnNkifXM1OJ2OlrFP1A,23553 greenlet/__init__.py,sha256=1zAfqzVVnBnQhxOL6UZ0t9jrNJUNJRgPEFvzW1qss9k,1723 greenlet/__pycache__/__init__.cpython-39.pyc,, greenlet/_greenlet.cpython-39-x86_64-linux-gnu.so,sha256=Tkqu1hNStN9rIaFBoch2i48pwtiyAU74k-NjPi9WiRI,1358296 greenlet/greenlet.cpp,sha256=WdItb1yWL9WNsTqJNf0Iw8ZwDHD49pkDP0rIRGBg2pw,10996 greenlet/greenlet.h,sha256=sz5pYRSQqedgOt2AMgxLZdTjO-qcr_JMvgiEJR9IAJ8,4755 greenlet/greenlet_allocator.hpp,sha256=kxyWW4Qdwlrc7ufgdb5vd6Y7jhauQ699Kod0mqiO1iM,1582 greenlet/greenlet_compiler_compat.hpp,sha256=nRxpLN9iNbnLVyFDeVmOwyeeNm6scQrOed1l7JQYMCM,4346 greenlet/greenlet_cpython_compat.hpp,sha256=XrsoFv8nKavrdxly5_-q9lqGeE8d3wKt1YtldsAHAT8,4068 greenlet/greenlet_exceptions.hpp,sha256=06Bx81DtVaJTa6RtiMcV141b-XHv4ppEgVItkblcLWY,4503 greenlet/greenlet_internal.hpp,sha256=Ajc-_09W4xWzm9XfyXHAeQAFUgKGKsnJwYsTCoNy3ns,2709 greenlet/greenlet_msvc_compat.hpp,sha256=0MyaiyoCE_A6UROXZlMQRxRS17gfyh0d7NUppU3EVFc,2978 greenlet/greenlet_refs.hpp,sha256=OnbA91yZf3QHH6-eJccvoNDAaN-pQBMMrclFU1Ot3J4,34436 greenlet/greenlet_slp_switch.hpp,sha256=kM1QHA2iV-gH4cFyN6lfIagHQxvJZjWOVJdIxRE3TlQ,3198 greenlet/greenlet_thread_support.hpp,sha256=XUJ6ljWjf9OYyuOILiz8e_yHvT3fbaUiHdhiPNQUV4s,867 greenlet/platform/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0 greenlet/platform/__pycache__/__init__.cpython-39.pyc,, greenlet/platform/setup_switch_x64_masm.cmd,sha256=ZpClUJeU0ujEPSTWNSepP0W2f9XiYQKA8QKSoVou8EU,143 greenlet/platform/switch_aarch64_gcc.h,sha256=GKC0yWNXnbK2X--X6aguRCMj2Tg7hDU1Zkl3RljDvC8,4307 greenlet/platform/switch_alpha_unix.h,sha256=Z-SvF8JQV3oxWT8JRbL9RFu4gRFxPdJ7cviM8YayMmw,671 greenlet/platform/switch_amd64_unix.h,sha256=EcSFCBlodEBhqhKjcJqY_5Dn_jn7pKpkJlOvp7gFXLI,2748 greenlet/platform/switch_arm32_gcc.h,sha256=Z3KkHszdgq6uU4YN3BxvKMG2AdDnovwCCNrqGWZ1Lyo,2479 greenlet/platform/switch_arm32_ios.h,sha256=mm5_R9aXB92hyxzFRwB71M60H6AlvHjrpTrc72Pz3l8,1892 greenlet/platform/switch_arm64_masm.asm,sha256=4kpTtfy7rfcr8j1CpJLAK21EtZpGDAJXWRU68HEy5A8,1245 greenlet/platform/switch_arm64_masm.obj,sha256=DmLnIB_icoEHAz1naue_pJPTZgR9ElM7-Nmztr-o9_U,746 greenlet/platform/switch_arm64_msvc.h,sha256=RqK5MHLmXI3Q-FQ7tm32KWnbDNZKnkJdq8CR89cz640,398 greenlet/platform/switch_csky_gcc.h,sha256=kDikyiPpewP71KoBZQO_MukDTXTXBiC7x-hF0_2DL0w,1331 greenlet/platform/switch_loongarch64_linux.h,sha256=7M-Dhc4Q8tRbJCJhalDLwU6S9Mx8MjmN1RbTDgIvQTM,779 greenlet/platform/switch_m68k_gcc.h,sha256=VSa6NpZhvyyvF-Q58CTIWSpEDo4FKygOyTz00whctlw,928 greenlet/platform/switch_mips_unix.h,sha256=E0tYsqc5anDY1BhenU1l8DW-nVHC_BElzLgJw3TGtPk,1426 greenlet/platform/switch_ppc64_aix.h,sha256=_BL0iyRr3ZA5iPlr3uk9SJ5sNRWGYLrXcZ5z-CE9anE,3860 greenlet/platform/switch_ppc64_linux.h,sha256=0rriT5XyxPb0GqsSSn_bP9iQsnjsPbBmu0yqo5goSyQ,3815 greenlet/platform/switch_ppc_aix.h,sha256=pHA4slEjUFP3J3SYm1TAlNPhgb2G_PAtax5cO8BEe1A,2941 greenlet/platform/switch_ppc_linux.h,sha256=YwrlKUzxlXuiKMQqr6MFAV1bPzWnmvk6X1AqJZEpOWU,2759 greenlet/platform/switch_ppc_macosx.h,sha256=Z6KN_ud0n6nC3ltJrNz2qtvER6vnRAVRNH9mdIDpMxY,2624 greenlet/platform/switch_ppc_unix.h,sha256=-ZG7MSSPEA5N4qO9PQChtyEJ-Fm6qInhyZm_ZBHTtMg,2652 greenlet/platform/switch_riscv_unix.h,sha256=606V6ACDf79Fz_WGItnkgbjIJ0pGg_sHmPyDxQYKK58,949 greenlet/platform/switch_s390_unix.h,sha256=RRlGu957ybmq95qNNY4Qw1mcaoT3eBnW5KbVwu48KX8,2763 greenlet/platform/switch_sh_gcc.h,sha256=mcRJBTu-2UBf4kZtX601qofwuDuy-Y-hnxJtrcaB7do,901 greenlet/platform/switch_sparc_sun_gcc.h,sha256=xZish9GsMHBienUbUMsX1-ZZ-as7hs36sVhYIE3ew8Y,2797 greenlet/platform/switch_x32_unix.h,sha256=nM98PKtzTWc1lcM7TRMUZJzskVdR1C69U1UqZRWX0GE,1509 greenlet/platform/switch_x64_masm.asm,sha256=nu6n2sWyXuXfpPx40d9YmLfHXUc1sHgeTvX1kUzuvEM,1841 greenlet/platform/switch_x64_masm.obj,sha256=GNtTNxYdo7idFUYsQv-mrXWgyT5EJ93-9q90lN6svtQ,1078 greenlet/platform/switch_x64_msvc.h,sha256=LIeasyKo_vHzspdMzMHbosRhrBfKI4BkQOh4qcTHyJw,1805 greenlet/platform/switch_x86_msvc.h,sha256=TtGOwinbFfnn6clxMNkCz8i6OmgB6kVRrShoF5iT9to,12838 greenlet/platform/switch_x86_unix.h,sha256=VplW9H0FF0cZHw1DhJdIUs5q6YLS4cwb2nYwjF83R1s,3059 greenlet/slp_platformselect.h,sha256=hTb3GFdcPUYJTuu1MY93js7MZEax1_e5E-gflpi0RzI,3959 greenlet/tests/__init__.py,sha256=sqxm7-dZuGBwmNI0n6xrcQJGoHHjoXUGyUTnvHidcYM,9361 greenlet/tests/__pycache__/__init__.cpython-39.pyc,, greenlet/tests/__pycache__/fail_clearing_run_switches.cpython-39.pyc,, greenlet/tests/__pycache__/fail_cpp_exception.cpython-39.pyc,, greenlet/tests/__pycache__/fail_initialstub_already_started.cpython-39.pyc,, greenlet/tests/__pycache__/fail_slp_switch.cpython-39.pyc,, greenlet/tests/__pycache__/fail_switch_three_greenlets.cpython-39.pyc,, greenlet/tests/__pycache__/fail_switch_three_greenlets2.cpython-39.pyc,, greenlet/tests/__pycache__/fail_switch_two_greenlets.cpython-39.pyc,, greenlet/tests/__pycache__/leakcheck.cpython-39.pyc,, greenlet/tests/__pycache__/test_contextvars.cpython-39.pyc,, greenlet/tests/__pycache__/test_cpp.cpython-39.pyc,, greenlet/tests/__pycache__/test_extension_interface.cpython-39.pyc,, greenlet/tests/__pycache__/test_gc.cpython-39.pyc,, greenlet/tests/__pycache__/test_generator.cpython-39.pyc,, greenlet/tests/__pycache__/test_generator_nested.cpython-39.pyc,, greenlet/tests/__pycache__/test_greenlet.cpython-39.pyc,, greenlet/tests/__pycache__/test_greenlet_trash.cpython-39.pyc,, greenlet/tests/__pycache__/test_leaks.cpython-39.pyc,, greenlet/tests/__pycache__/test_stack_saved.cpython-39.pyc,, greenlet/tests/__pycache__/test_throw.cpython-39.pyc,, greenlet/tests/__pycache__/test_tracing.cpython-39.pyc,, greenlet/tests/__pycache__/test_version.cpython-39.pyc,, greenlet/tests/__pycache__/test_weakref.cpython-39.pyc,, greenlet/tests/_test_extension.c,sha256=vkeGA-6oeJcGILsD7oIrT1qZop2GaTOHXiNT7mcSl-0,5773 greenlet/tests/_test_extension.cpython-39-x86_64-linux-gnu.so,sha256=ikYz6udf-okAdaz2hc_sTxFu0VUXNcfk-kJiMzjuoug,17256 greenlet/tests/_test_extension_cpp.cpp,sha256=e0kVnaB8CCaEhE9yHtNyfqTjevsPDKKx-zgxk7PPK48,6565 greenlet/tests/_test_extension_cpp.cpython-39-x86_64-linux-gnu.so,sha256=374Brn-R2f428CPppTIGPIUS7NWLVqzlUNcKswa65rY,57520 greenlet/tests/fail_clearing_run_switches.py,sha256=o433oA_nUCtOPaMEGc8VEhZIKa71imVHXFw7TsXaP8M,1263 greenlet/tests/fail_cpp_exception.py,sha256=o_ZbipWikok8Bjc-vjiQvcb5FHh2nVW-McGKMLcMzh0,985 greenlet/tests/fail_initialstub_already_started.py,sha256=txENn5IyzGx2p-XR1XB7qXmC8JX_4mKDEA8kYBXUQKc,1961 greenlet/tests/fail_slp_switch.py,sha256=rJBZcZfTWR3e2ERQtPAud6YKShiDsP84PmwOJbp4ey0,524 greenlet/tests/fail_switch_three_greenlets.py,sha256=zSitV7rkNnaoHYVzAGGLnxz-yPtohXJJzaE8ehFDQ0M,956 greenlet/tests/fail_switch_three_greenlets2.py,sha256=FPJensn2EJxoropl03JSTVP3kgP33k04h6aDWWozrOk,1285 greenlet/tests/fail_switch_two_greenlets.py,sha256=1CaI8s3504VbbF1vj1uBYuy-zxBHVzHPIAd1LIc8ONg,817 greenlet/tests/leakcheck.py,sha256=inbfM7_oVzd8jIKGxCgo4JqpFZaDAnWPkSULJ8vIE1s,11964 greenlet/tests/test_contextvars.py,sha256=xutO-qZgKTwKsA9lAqTjIcTBEiQV4RpNKM-vO2_YCVU,10541 greenlet/tests/test_cpp.py,sha256=hpxhFAdKJTpAVZP8CBGs1ZcrKdscI9BaDZk4btkI5d4,2736 greenlet/tests/test_extension_interface.py,sha256=eJ3cwLacdK2WbsrC-4DgeyHdwLRcG4zx7rrkRtqSzC4,3829 greenlet/tests/test_gc.py,sha256=PCOaRpIyjNnNlDogGL3FZU_lrdXuM-pv1rxeE5TP5mc,2923 greenlet/tests/test_generator.py,sha256=tONXiTf98VGm347o1b-810daPiwdla5cbpFg6QI1R1g,1240 greenlet/tests/test_generator_nested.py,sha256=7v4HOYrf1XZP39dk5IUMubdZ8yc3ynwZcqj9GUJyMSA,3718 greenlet/tests/test_greenlet.py,sha256=rYWDvMx7ZpMlQju9KRxsBR61ela7HSJCg98JtR7RPOQ,46251 greenlet/tests/test_greenlet_trash.py,sha256=n2dBlQfOoEO1ODatFi8QdhboH3fB86YtqzcYMYOXxbw,7947 greenlet/tests/test_leaks.py,sha256=Qeso_qH9MCWJOkk2I3VcTh7UhaNvWxrzAmNBta-fUyY,17714 greenlet/tests/test_stack_saved.py,sha256=eyzqNY2VCGuGlxhT_In6TvZ6Okb0AXFZVyBEnK1jDwA,446 greenlet/tests/test_throw.py,sha256=u2TQ_WvvCd6N6JdXWIxVEcXkKu5fepDlz9dktYdmtng,3712 greenlet/tests/test_tracing.py,sha256=VlwzMU0C1noospZhuUMyB7MHw200emIvGCN_6G2p2ZU,8250 greenlet/tests/test_version.py,sha256=O9DpAITsOFgiRcjd4odQ7ejmwx_N9Q1zQENVcbtFHIc,1339 greenlet/tests/test_weakref.py,sha256=F8M23btEF87bIbpptLNBORosbQqNZGiYeKMqYjWrsak,883 greenlet-3.2.3.dist-info/top_level.txt 0000644 00000000011 15125143220 0013422 0 ustar 00 greenlet greenlet-3.2.3.dist-info/licenses/LICENSE 0000644 00000002632 15125143220 0013515 0 ustar 00 The following files are derived from Stackless Python and are subject to the same license as Stackless Python: src/greenlet/slp_platformselect.h files in src/greenlet/platform/ directory See LICENSE.PSF and http://www.stackless.com/ for details. Unless otherwise noted, the files in greenlet have been released under the following MIT license: Copyright (c) Armin Rigo, Christian Tismer and contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. greenlet-3.2.3.dist-info/licenses/LICENSE.PSF 0000644 00000004570 15125143220 0014147 0 ustar 00 PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2 -------------------------------------------- 1. This LICENSE AGREEMENT is between the Python Software Foundation ("PSF"), and the Individual or Organization ("Licensee") accessing and otherwise using this software ("Python") in source or binary form and its associated documentation. 2. Subject to the terms and conditions of this License Agreement, PSF hereby grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use Python alone or in any derivative version, provided, however, that PSF's License Agreement and PSF's notice of copyright, i.e., "Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Python Software Foundation; All Rights Reserved" are retained in Python alone or in any derivative version prepared by Licensee. 3. In the event Licensee prepares a derivative work that is based on or incorporates Python or any part thereof, and wants to make the derivative work available to others as provided herein, then Licensee hereby agrees to include in any such work a brief summary of the changes made to Python. 4. PSF is making Python available to Licensee on an "AS IS" basis. PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON WILL NOT INFRINGE ANY THIRD PARTY RIGHTS. 5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. 6. This License Agreement will automatically terminate upon a material breach of its terms and conditions. 7. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between PSF and Licensee. This License Agreement does not grant permission to use PSF trademarks or trade name in a trademark sense to endorse or promote products or services of Licensee, or any third party. 8. By copying, installing or otherwise using Python, Licensee agrees to be bound by the terms and conditions of this License Agreement. __pycache__/typing_extensions.cpython-39.pyc 0000644 00000342004 15125143220 0015174 0 ustar 00 a ��Jh�e � @ s� d dl Z d dlZd dlZd dlZd dlZd dlZd dlZd dlZd dlZd dl Z d dl Z d dl Z d dl Z d dlZd dlZe jdkr�d dlZg d�ZdZeZe jdkZdejjv ZG dd� d�Ze� Ze jd kr�d d � Z nd d � Z ej Z e� d �Z e� d�Z e� d�Z!ej ddd�Z"ej ddd�Z#e jdk�r:d dlm$Z$ n"G dd� de�Z%G dd� de%d�Z$ej&Z&G dd � d ej'dd �Z(ej)Z)e jdk�r�ej*Z*nd d � Z*d d!� Z+e jd"k�r�ej,Z,nDd#d$� Z-d%d&� Z.G d'd(� d(ej/dd �Z0G d)d*� d*e(dd �Z1e1d+d,�Z,ej2Z2e3ed-��r ej4Z4ej5Z5ej6Z6n,e�7e�8ej7e9��Z:d.d/� Z4d0d-� Z5d1d2� Z6ej;Z;ej<Z<ej=Z=ej>Z>ej?Z?ej@Z@ejAZAejBZBejCZCejDZDejEZEejFZFe jdk�r�d d3lmGZGmHZHmIZImJZJ n�d4d5� ZKG d6d7� d7ejLdd �ZLed�ZMeLej jJd8eMeMfd9�ZJeLej jHd:eMfd9�ZHeLejNd:d;ejOeP fd<�ZIeLejQd:d=ejOeP fd<�ZGg d>�d?d@gdAgdB�ZReSejT�h dC�B ZUdDdE� ZV�d0dHdI�ZWe jdJk�r�ejXZXnT�d1dKdL�ZYdMdN� ZZdOdP� Z[G dQdR� dReejX��Z\e]dSdT� �Z^G dUdV� dVej_e\d�ZXe jdJk�r�ej`Z`ndWdX� Z`e`Zae jdYk�r:ejbZbejcZcejdZdejeZeejfZfejgZgejhZhn�e`G dZd[� d[eX��Zbe`G d\d]� d]eX��Zce`G d^d_� d_eX��Zde`G d`da� daeX��Zee`G dbdc� dceX��Zfe`G ddde� deeXe" ��Zge`G dfdg� dgeXe" ��Zhe3edh��r�e3edi��r�ejiZiejjZjn0e`G djdh� dheXe" ��Zie`G dkdi� dieXe# ��Zje3edl� �p<e3edm� Zkek�rTG dndo� doe�Zle3edl��rhejmZmnG dpdq� dqeld�Znen� Zm[ne3edm��r�ejoZonG drds� dseld�Zpep� Zo[pek�r�[ldtZqeq�r�ejrZrejsZsejtZtntdue�uejv�jwv Zxdvdw� ZyG dxdy� dye�Zse�zesdzd{i �Z{d|d}� Z|G d~d� de(dd �Z}e}d�dz� �ZrejsesfZ~d�d�� Zte3ed���r^ejZnd�d�� Ze3ed���rzej�Z�n0d�d�� Z��d2d�d��Z�ed�ZMd�d�� Z��d3d�d��Z�e jdd:� d k�r�ej�Z�ej�Z�nd�d�� Z�d�d�� Z�e3ed���r�ej�Z�n e(d�d�� �Z�d�d�� Z�d�d�� Z�G d�d�� d��Z�G d�d�� d�e�Z�e�r>d d�lm Z nG d�d�� d�e�d�Z e3ed���rjej�Z�ej�Z�n.G d�d�� d��Z�G d�d�� d�e��Z�G d�d�� d�e��Z�e�r�d d�lm�Z� n2e3ed���r�G d�d�� d�e�d�Z�nG d�d�� d�e�e��Z�e3ed���s"e3ed���s �d4dtd��d�d��Z�nej�Z�G d�d�� d�e��Z�n(ej�Z�e jdk �rJG d�d�� d�ej�dd �Z�G d�d�� d��Z�d�d�� Z�ej�d�d�� �Z�e jdk�r�ej�Z�n e(d�d�� �Z�e3ed���r�ej�Z�n e(d�d�� �Z�e3ed���r�ej�Z�n e(d�d�� �Z�e3ed���r�ej�Z�n G d�d�� d�e(dd �Z�e�d�d�� �Z�G d�d�� d�ej�dd �Z'e3ed��� r,ej�Z�n e'd�d�� �Z�e3edÃ� rLej�Z�n e'd�dÄ �Z�e3edŃ� rlej�Z�n e'd�dń �Z�e3edǃ� r�ej�Z�ej�Z�ne(d�dDŽ �Z�e(d�dʄ �Z�e3ed��� r�ej�Z�n e(d�d�� �Z�d�Z�e jdYk� r�ej�Z�d�d΄ Z�n>G d�dЄ d�e(dd �Z�G d�d҄ d�ej/dd �Z�e�d�dԄ �Z�d�d΄ Z�d�dׄ Z�e� rDd d�lm�Z� n0e3edك� rdG d�dل d�e�d�Z�nG d�dل d�e��Z�e3ed܃� r�ej�Z�ne e dݜd�d܄Z�e3ed߃� r�ej�Z�nd�Z�e3ed�� r�ej�Z�ne�e�d�d�d�Z�e jdYk� r�ej�Z�n^ddtdtdtd{d�ePePePePej�ej�ej;ej$ ej�d�ej$f f d�f ej$ej�e ge f d�d�d�Z�e3ed�� rZej�Z�n*ej d�ej�d�ej$f d�Z�e�e�d�d�d�Z�e jd�k� r�ej�Z�ne� d�Z�G d�d� d�Z�e jd k � r�d�d� Z�nd�d� Z�e3edك� s�efd�d��Z�nd�d�� Z�e� s�e�e_�ePd��d�d��Z�e�e�ed�d�hZ�ePd��d�d��Z�e3ed��� rH�d5d�d��Z�e�e_�nd�d�� Z�e� s\e�e_�e jdJk� rpej�Z�nn�d6�d �d�Z�ej�Z�eSh �d��Z�G �d�d� �de�Z�e�ze��dd{i �Zd�d� Z�ef�d�d�Z�e�e�_�e3ej dA�� r�ej j�Z�n2G �d dA� dAe jƃZ�eŠ�eȡ eŠ�eɡ eŠ�eʡ e3e �d �� r>e j�Z�n �d �d � Z�e jdk� r^ej�Z�nG �d �d � �d �Z�e jdk� r�ej�Z�npe jdYk� r��d�d� Z�n �d�d� Z�e jd k � r�eSh �d��Z�G �d�d� �dej/dd �Z�G �d�d� �d�Z�e3e�d��rej�Z�ej�Z�n2eeP�d��d�d�Z�eej�e� �d��d�d�Z�e3e�d��rZej�Z�nG �d �d� �d�Z�e�e �d d�Z�e�du �r�z d dl�Z�W n eؐy� Y n"0 e�eאd d�Z�e�du�r�eeكZ�e�du�r�e�Z�e�ېd � e jdk�rd �d lm�Z�m�Z� n4G �d �d!� �d!ejރZ�dddte�jߐd"��d#�d$�Z�e3e�d%��rLej�Z�n:dddd�d&��d'�d(�Z�dddddeS� �d)��d*�d%�Z�G �d+�d,� �d,�Z�g �d-�Z�e� ��d.�d/� e�D �� ej_Z_ejZej�Z�dS (7 � N�� � )u�Any�ClassVar� Concatenate�Final� LiteralString� ParamSpec� ParamSpecArgs�ParamSpecKwargs�Self�Type�TypeVar� TypeVarTuple�Unpack� Awaitable� AsyncIterator� AsyncIterable� Coroutine�AsyncGenerator�AsyncContextManager�Buffer�ChainMap�ContextManager�Counter�Deque� DefaultDict� NamedTuple� OrderedDict� TypedDict� SupportsAbs� SupportsBytes�SupportsComplex� SupportsFloat� SupportsIndex� SupportsInt� SupportsRound�Reader�Writer� Annotated� assert_never� assert_type�clear_overloads�dataclass_transform� deprecated�Doc�evaluate_forward_ref� get_overloads�final�Format�get_annotations�get_args� get_origin�get_original_bases�get_protocol_members�get_type_hints�IntVar� is_protocol� is_typeddict�Literal�NewType�overload�override�Protocol�Sentinel� reveal_type�runtime�runtime_checkable�Text� TypeAlias� TypeAliasType�TypeForm� TypeGuard�TypeIs� TYPE_CHECKING�Never�NoReturn�ReadOnly�Required� NotRequired� NoDefault� NoExtraItems� AbstractSet�AnyStr�BinaryIO�Callable� Collection� Container�Dict� ForwardRef� FrozenSet� Generator�Generic�Hashable�IO� ItemsView�Iterable�Iterator�KeysView�List�Mapping� MappingView�Match�MutableMapping�MutableSequence� MutableSet�Optional�Pattern� Reversible�Sequence�Set�Sized�TextIO�Tuple�Union� ValuesView�cast� no_type_check�no_type_check_decoratorT)r � r �beta�__forward_is_class__c @ s e Zd Zdd� ZdS )� _Sentinelc C s dS )Nz <sentinel>� ��selfr~ r~ �F/home/agenciai/.local/lib/python3.9/site-packages/typing_extensions.py�__repr__� s z_Sentinel.__repr__N��__name__� __module__� __qualname__r� r~ r~ r~ r� r} � s r} �r � c C s t | tjtjtjf�S �N)� isinstance�typing� _GenericAlias�_types� GenericAlias� UnionType��tr~ r~ r� � _should_collect_from_parameters� s �r� c C s t | tjtjf�S r� )r� r� r� r� r� r� r~ r~ r� r� � s �T�KT�VT�T_co)� covariant�T_contra)� contravariant�r � )r c s( e Zd Z� fdd�Z� fdd�Z� ZS )�_AnyMetac s | t u rtd��t� �|�S )Nz6typing_extensions.Any cannot be used with isinstance())r � TypeError�super�__instancecheck__�r� �obj�� __class__r~ r� r� � s z_AnyMeta.__instancecheck__c s | t u r dS t� �� S )Nztyping_extensions.Any)r r� r� r r� r~ r� r� � s z_AnyMeta.__repr__)r� r� r� r� r� � __classcell__r~ r~ r� r� r� � s r� c s e Zd ZdZ� fdd�Z� ZS )r aq Special type indicating an unconstrained type. - Any is compatible with every type. - Any assumed to have all methods. - All values assumed to be instances of Any. Note that all the above statements are true from the point of view of static type checkers. At runtime, Any should not be used with instance checks. c s* | t u rtd��t� j| g|�R i |��S )NzAny cannot be instantiated)r r� r� �__new__��cls�args�kwargsr� r~ r� r� � s z Any.__new__)r� r� r� �__doc__r� r� r~ r~ r� r� r � s r )� metaclassc @ s e Zd Zdd� ZdS )�_ExtensionsSpecialFormc C s d| j S �Nztyping_extensions.��_namer r~ r~ r� r� � s z _ExtensionsSpecialForm.__repr__Nr� r~ r~ r~ r� r� � s r� )�_rootc C s& z d| _ W n ttfy Y n0 | S )a� This decorator can be used to indicate to type checkers that the decorated method cannot be overridden, and decorated class cannot be subclassed. For example: class Base: @final def done(self) -> None: ... class Sub(Base): def done(self) -> None: # Error reported by type checker ... @final class Leaf: ... class Other(Leaf): # Error reported by type checker ... There is no runtime checking of these properties. The decorator sets the ``__final__`` attribute to ``True`` on the decorated object to allow runtime introspection. T)� __final__�AttributeErrorr� )�fr~ r~ r� r3 � s r3 c C s t �| �S r� )r� r ��namer~ r~ r� r; s r; )r r� � c C s8 g }| D ]&}t |t�r$|�|j� q|�|� qt|�S )zJAn internal helper for Literal creation: flatten Literals among parameters)r� �_LiteralGenericAlias�extend�__args__�append�tuple)� parameters�params�pr~ r~ r� �_flatten_literal_params s r� c c s | D ]}|t |�fV qd S r� )�type)r� r� r~ r~ r� �_value_and_type_iter s r� c @ s e Zd Zdd� Zdd� ZdS )r� c C s2 t |t�stS tt| j��}tt|j��}||kS r� )r� r� �NotImplemented�setr� r� )r� �otherZthese_args_dedupedZother_args_dedupedr~ r~ r� �__eq__% s z_LiteralGenericAlias.__eq__c C s t tt| j���S r� )�hash� frozensetr� r� r r~ r~ r� �__hash__, s z _LiteralGenericAlias.__hash__N)r� r� r� r� r� r~ r~ r~ r� r� $ s r� c @ s" e Zd Zed�dd�Zdd� ZdS )� _LiteralForm��docc C s d| _ | | _| _d S )Nr> )r� Z_docr� )r� r� r~ r~ r� �__init__0 s z_LiteralForm.__init__c C s� t |t�s|f}t|�}tt|��}z t|�}W n tyB Y nT0 t|�t|�k r�g }|D ]$}||v r\|�|d � |� |� q\|r�J |��t|�}t | |�S �Nr ) r� r� r� �listr� r� r� �lenr� �remover� )r� r� Zval_type_pairsZ deduped_pairsZnew_parameters�pairr~ r~ r� � __getitem__4 s" z_LiteralForm.__getitem__N)r� r� r� �strr� r� r~ r~ r~ r� r� / s r� a� A type that can be used to indicate to type checkers that the corresponding value has a value literally equivalent to the provided parameter. For example: var: Literal[4] = 4 The type checker understands that 'var' is literally equal to the value 4 and no other value. Literal[...] cannot be subclassed. There is no runtime checking verifying that the parameter is actually a value instead of a type.r� r2 c C s@ t | d| �}z | t|j |j |jj< W n ty: Y n0 tS )a� Decorator for overloaded functions/methods. In a stub file, place two or more stub definitions for the same function in a row, each decorated with @overload. For example: @overload def utf8(value: None) -> None: ... @overload def utf8(value: bytes) -> bytes: ... @overload def utf8(value: str) -> bytes: ... In a non-stub file (i.e. a regular .py file), do the same but follow it with an implementation. The implementation should *not* be decorated with @overload. For example: @overload def utf8(value: None) -> None: ... @overload def utf8(value: bytes) -> bytes: ... @overload def utf8(value: str) -> bytes: ... def utf8(value): # implementation goes here The overloads for a function can be retrieved at runtime using the get_overloads() function. �__func__)�getattr�_overload_registryr� r� �__code__�co_firstlinenor� �_overload_dummy)�funcr� r~ r~ r� r@ i s �� r@ c C sD t | d| �}|jtvrg S t|j }|j|vr2g S t||j �� �S )z6Return all defined overloads for *func* as a sequence.r� )r� r� r� r� r� �values)r� r� �mod_dictr~ r~ r� r2 � s c C s t �� dS )z$Clear all overloads in the registry.N)r� �clearr~ r~ r~ r� r- � s r- )r r r r^ c C s | � d�o| �d�S )N�__)� startswith�endswith)�attrr~ r~ r� � _is_dunder� s r� c s< e Zd Zdddd�� fdd� Zdd� Zejd d � �Z� ZS ) �_SpecialGenericAliasTNr~ )�instr� �defaultsc s t � j||||d� || _d S )N)r� r� )r� r� � _defaults)r� �origin�nparamsr� r� r� r� r~ r� r� � s z _SpecialGenericAlias.__init__c C s: h d�}t |�s||v r(t�| ||� nt| j||� d S )N> r� �_nparamsr� �_inst)r� �object� __setattr__�setattr� __origin__)r� r� �valZ allowed_attrsr~ r~ r� r� � s z _SpecialGenericAlias.__setattr__c s� t |t�s|f}d� t� fdd�|D ��}| jrxt|�| jk rxt|�t| j� | jkrxg |�| jt|�| j d � �R }t|�}|| jkr�| jr�d| jt| j� � �}n t| j�}| js�t| � d���td|| jkr�dnd� d | � d |� d |� ���| �|�S ) Nz*Parameters to generic types must be types.c 3 s | ]}t �|� �V qd S r� �r� � _type_check��.0r� ��msgr~ r� � <genexpr>� � z3_SpecialGenericAlias.__getitem__.<locals>.<genexpr>� at least � is not a generic class�Too �many�few� arguments for � ; actual � , expected )r� r� r� r� r� r� r� � copy_with)r� r� Z actual_len�expectedr~ r� r� r� � s8 � ��" ����z _SpecialGenericAlias.__getitem__) r� r� r� r� r� r� � _tp_cacher� r� r~ r~ r� r� r� � s r� r )r� � r )r� r� r ) rX r rc rd r r` rr rZ rY ro r �AbstractContextManager�AbstractAsyncContextManagerr )zcollections.abc� contextlib�typing_extensions> � __non_callable_proto_members__�__protocol_attrs__Z__match_args__r� c C sh t � }| jd d� D ]N}|jdv r$qt|di �}g |j�|�R D ] }|�d�s@|tvr@|�|� q@q|S )N���> rB r_ �__annotations__�_abc_)r� �__mro__r� r� �__dict__r� �_EXCLUDED_ATTRS�add)r� �attrs�base� annotationsr� r~ r~ r� �_get_protocol_attrs s r r� �__main__c C s^ zt �| d �p|W S ty& Y n0 zt �| d �j�d|�W S ttfyX Y n0 d S )Nr� r� )�sysZ_getframemodulenamer� � _getframe� f_globals�get� ValueError)�depth�defaultr~ r~ r� �_caller s r �r rz c C s t | �dv S )z�Allow instance and class checks for special stdlib modules. The abc and functools modules indiscriminately call isinstance() and issubclass() on the whole MRO of a user class, which may contain protocols. > � functools�abcN)r �r r~ r~ r� � _allow_reckless_class_checks$ s r" c O s t | �jrtd��d S )Nz Protocols cannot be instantiated)r� � _is_protocolr� �r� r� r� r~ r~ r� �_no_init+ s r% c C s t | t�std��dS )a� Raise TypeError if `arg` is not an instance of `type` in `issubclass(arg, <protocol>)`. In most cases, this is verified by type.__subclasscheck__. Checking it again unnecessarily would slow down issubclass() checks, so, we don't perform this check unless we absolutely have to. For various error paths, however, we want to ensure that *this* error message is shown to the user where relevant, rather than a typing.py-specific error message. z"issubclass() arg 1 must be a classN)r� r� r� ��argr~ r~ r� � _type_check_issubclass_arg_1/ s r( c @ sB e Zd Zdd� Zdd� Zdd� Zdd� Zd d � Zed �d d �Z dS )� _ProtocolMetac K s� |dkrt |�dk rnZttjht|�@ rp|D ]B}|ttjttjhv s,|jt�|j g �v s,t |�s,t d|����q,t j j| |||fi |��S )NrB r z5Protocols can only inherit from other protocols, got )r� rB r� r� r� r_ r� �_PROTO_ALLOWLISTr r� r< r� r �ABCMetar� )�mclsr� �bases� namespacer� r r~ r~ r� r� I s �����z_ProtocolMeta.__new__c O s4 t jj| g|�R i |�� t| dd�r0t| �| _d S )Nr# F)r r+ r� r� r r r� r~ r~ r� r� Y s z_ProtocolMeta.__init__c C s� | t u rt�| |�S t| dd�r�t� s�t| dd�sBt|� td��| jr�| j� d�t u r�t|� t | j�}tdt |�dd� � d ���t j�| |�S ) Nr# F�_is_runtime_protocol�LInstance and class checks can only be used with @runtime_checkable protocols�__subclasshook__zRProtocols with non-method members don't support issubclass(). Non-method members: r� r �.)rB r� �__subclasscheck__r� r" r( r� r r r � _proto_hook�sortedr� r r+ )r� r� Znon_method_attrsr~ r~ r� r3 ^ s. �� ��� ��z _ProtocolMeta.__subclasscheck__c C s� | t u rt�| |�S t| dd�s.tj�| |�S t| dd�sHt� sHtd��tj�| |�rZdS | jD ]D}zt � ||�}W n t y� Y q�Y n0 |d u r`|| j vr` q�q`dS dS )Nr# Fr/ r0 T) rB r� r� r� r r+ r" r� r �inspect�getattr_staticr� r )r� �instancer� r� r~ r~ r� r� x s( �� z _ProtocolMeta.__instancecheck__c C s( t j�| |�du rdS | tu o&|tju S )NT)r r+ r� rB r� �r� r� r~ r~ r� r� � s z_ProtocolMeta.__eq__��returnc C s t �| �S r� )r� r� �r� r~ r~ r� r� � s z_ProtocolMeta.__hash__N) r� r� r� r� r� r3 r� r� �intr� r~ r~ r~ r� r) B s r) c C s� | j �dd�stS | jD ]n}|jD ]Z}||j v rN|j | d u rJt S qt|di �}t|tjj �r"||v r"t |�r" qq"t S qdS )Nr# Fr T) r r r� r r r� r� � collectionsr rg r< )r� r� r� r r r~ r~ r� r4 � s$ ��� r4 c s0 e Zd ZejjZdZdZdZ� fdd�Z � Z S )rB r~ TFc sb t � j|i |�� | j�dd�s6tdd� | jD ��| _d| jvrFt| _| jr^| j t j u r^t | _ d S )Nr# Fc s s | ]}|t u V qd S r� )rB �r� �br~ r~ r� r� � r� z-Protocol.__init_subclass__.<locals>.<genexpr>r1 ) r� �__init_subclass__r r �any� __bases__r# r4 r1 r� rB r% r� r� r~ r� rA � s zProtocol.__init_subclass__) r� r� r� r� rB r� � __slots__r# r/ rA r� r~ r~ r� r� rB � s rB c C s� t | tj�rt| dd�s&td| ����d| _t| t�s@tj dkr�t � | _ | j D ]`}zt t| |d��}W n6 ty� } z td|�d��|�W Y d}~qNd}~0 0 |sN| j �|� qN| S ) aj Mark a protocol class as a runtime protocol. Such protocol can be used with isinstance() and issubclass(). Raise TypeError if applied to a non-protocol class. This allows a simple-minded structural check very similar to one trick ponies in collections.abc such as Iterable. For example:: @runtime_checkable class Closable(Protocol): def close(self): ... assert isinstance(open('/some/file'), Closable) Warning: this will check only the presence of the required methods, not their type signatures! r# Fz@@runtime_checkable can be only applied to protocol classes, got T)r � r Nz,Failed to determine whether protocol member z is a method member)� issubclassr� r_ r� r� r/ r� r) r � version_infor� r r �callable� Exceptionr )r� r� Z is_callable�er~ r~ r� rF � s& � ��rF �r rE c @ s( e Zd ZdZdZejed�dd��ZdS )r& z(An ABC with one abstract method __int__.r~ r: c C s d S r� r~ r r~ r~ r� �__int__ s zSupportsInt.__int__N) r� r� r� r� rD r �abstractmethodr= rL r~ r~ r~ r� r& s r& c @ s( e Zd ZdZdZejed�dd��ZdS )r$ z*An ABC with one abstract method __float__.r~ r: c C s d S r� r~ r r~ r~ r� � __float__( s zSupportsFloat.__float__N) r� r� r� r� rD r rM �floatrN r~ r~ r~ r� r$ # s r$ c @ s( e Zd ZdZdZejed�dd��ZdS )r# z,An ABC with one abstract method __complex__.r~ r: c C s d S r� r~ r r~ r~ r� � __complex__1 s zSupportsComplex.__complex__N) r� r� r� r� rD r rM �complexrP r~ r~ r~ r� r# , s r# c @ s( e Zd ZdZdZejed�dd��ZdS )r" z*An ABC with one abstract method __bytes__.r~ r: c C s d S r� r~ r r~ r~ r� � __bytes__: s zSupportsBytes.__bytes__N) r� r� r� r� rD r rM �bytesrR r~ r~ r~ r� r" 5 s r" c @ s$ e Zd ZdZejed�dd��ZdS )r% r~ r: c C s d S r� r~ r r~ r~ r� � __index__B s zSupportsIndex.__index__N)r� r� r� rD r rM r= rT r~ r~ r~ r� r% > s r% c @ s( e Zd ZdZdZejed�dd��ZdS )r! z_ An ABC with one abstract method __abs__ that is covariant in its return type. r~ r: c C s d S r� r~ r r~ r~ r� �__abs__M s zSupportsAbs.__abs__N) r� r� r� r� rD r rM r� rU r~ r~ r~ r� r! F s r! c @ s, e Zd ZdZdZejdeed�dd��Z dS ) r' za An ABC with one abstract method __round__ that is covariant in its return type. r~ r )�ndigitsr; c C s d S r� r~ )r� rV r~ r~ r� � __round__X s zSupportsRound.__round__N)r ) r� r� r� r� rD r rM r= r� rW r~ r~ r~ r� r' Q s r' r( r) c @ s, e Zd ZdZdZejdeed�dd��Z dS ) r( zeProtocol for simple I/O reader instances. This protocol only supports blocking I/O. r~ .)�sizer; c C s dS )z�Read data from the input stream and return it. If *size* is specified, at most *size* items (bytes/characters) will be read. Nr~ )r� rX r~ r~ r� �readj s z Reader.readN).) r� r� r� r� rD r rM r= r� rY r~ r~ r~ r� r( a s c @ s* e Zd ZdZdZejeed�dd��Z dS )r) zeProtocol for simple I/O writer instances. This protocol only supports blocking I/O. r~ )�datar; c C s dS )zIWrite *data* to the output stream and return the number of items written.Nr~ )r� rZ r~ r~ r� �write{ s z Writer.writeN) r� r� r� r� rD r rM r� r= r[ r~ r~ r~ r� r) r s rS rT c @ s e Zd Zdd� ZdS )� SingletonMetac C s t d|�d| j����d S )Nz cannot set z attribute of immutable type �r� r� )r� r� �valuer~ r~ r� r� � s �zSingletonMeta.__setattr__N)r� r� r� r� r~ r~ r~ r� r\ � s r\ c @ s, e Zd ZdZdZdd� Zdd� Zdd� Zd S ) � NoDefaultTypez$The type of the NoDefault singleton.r~ c C s t � �d�pt�| �S �NrS ��globalsr r� r� r< r~ r~ r� r� � s zNoDefaultType.__new__c C s dS )Nztyping_extensions.NoDefaultr~ r r~ r~ r� r� � s zNoDefaultType.__repr__c C s dS r` r~ r r~ r~ r� � __reduce__� s zNoDefaultType.__reduce__N�r� r� r� r� rD r� r� rc r~ r~ r~ r� r_ � s r_ c @ s, e Zd ZdZdZdd� Zdd� Zdd� Zd S ) �NoExtraItemsTypez'The type of the NoExtraItems singleton.r~ c C s t � �d�pt�| �S �NrT ra r< r~ r~ r� r� � s zNoExtraItemsType.__new__c C s dS )Nz typing_extensions.NoExtraItemsr~ r r~ r~ r� r� � s zNoExtraItemsType.__repr__c C s dS rf r~ r r~ r~ r� rc � s zNoExtraItemsType.__reduce__Nrd r~ r~ r~ r� re � s re F�modulec c s� t | �}|tu r*t| �}|r||d } qzq|q |tu rDtV t| �\} q |tu r^tV t| �\} q |tu r|tV t| �\} q q|q d S r� )r7 r* r6 rQ rR rP )�annotation_typeZannotation_originZannotation_argsr~ r~ r� �_get_typeddict_qualifiers� s ri c @ s. e Zd Zdded�dd�ZeZdd� ZeZdS )�_TypedDictMetaTN��total�closed� extra_itemsc sZ � D ]"}t |�tur|tjurtd��q|durH|turHtd|�d���tdd� � D ��rdtjf}nd}|�dd�} t �td g |�t �R |��|�_ �j d kr�|�_ t �d �s�� �_ i } d�| dur�| �nTtjd k�rt td �r�t�|��n |�d ���du�rtj�tj�d��ni �ni �d�t�rB��fdd���� D ��n�fdd���� D ��t� } t� } t� } t� }|}� D ]r}|j}tjd k�r�| �|�di �� | �|�dd�� | �|�dd�� | �|�dd�� |�|�dd�� �qx|�rFtjd k �rFd�v �rF��d�}tt|��}t |v �r0td��t |v �rBtd��|}| ��� ��� D ]�\}}tt|��}t |v �r�| � |� n2t |v �r�| � |� n |�r�| � |� n | � |� t |v �r�|� |� | � |� n|� |� | � |� �qXtjd k�r� �����fdd�}|�_!n| �_"t#| ��_$t#| ��_%t#| ��_&t#|��_'|�_(|�_)|�_*�S ) aI Create new typed dict class object. This method is called when TypedDict is subclassed, or when TypedDict is instantiated. This way TypedDict supports all three syntax forms described in its docstring. Subclasses and instances of TypedDict return actual dictionaries. zHcannot inherit from both a TypedDict type and a non-TypedDict base classNzCannot combine closed=z and extra_itemsc s s | ]}t |tj�V qd S r� )rF r� r_ r? r~ r~ r� r� � r� z)_TypedDictMeta.__new__.<locals>.<genexpr>r~ r rB �__orig_bases__r �!get_annotate_from_class_namespace� __annotate__��ownerz?TypedDict('Name', {f0: t0, f1: t1, ...}); each t must be a typec s$ i | ] \}}|t j|� �jd ��qS ��rg �r� r� r� �r� �n�tp�r� �tp_dictr~ r� � <dictcomp> s �z*_TypedDictMeta.__new__.<locals>.<dictcomp>c s i | ]\}}|t �|� ��qS r~ r� rw r� r~ r� r| s ��__required_keys__�__optional_keys__�__readonly_keys__�__mutable_keys__�__extra_items__z5Special key __extra_items__ does not support Requiredz8Special key __extra_items__ does not support NotRequiredc s� i }� D ]8}|t u rq|j}|d u r&qtj|| |d�}|�|� q�d ur~tj�| �d�}| tjkr���fdd�|�� D �}n4| tjkr�t���}n | tj tj fv r��}nt | ��|�|� |S )Nrr c s$ i | ] \}}|t j|� �jd ��qS rt rv rw rz r~ r� r| j s �z@_TypedDictMeta.__new__.<locals>.__annotate__.<locals>.<dictcomp>) r_ rq � annotationlib�call_annotate_function�updater4 �STRING�itemsZannotations_to_string� FORWARDREF�VALUE�NotImplementedError)�formatZannosr Z base_annotateZ base_annosZown�r- r� Z own_annotate�own_annotationsZown_checked_annotationsr{ r~ r� rq [ s4 � � � z,_TypedDictMeta.__new__.<locals>.__annotate__)+r� rj r� r_ r� rT rB �popr� �dictr� r� �hasattrro r rG r� rp r r� r4 r� � _TAKES_MODULEr� r� r r� ri rQ rR r rP �discardrq r r� r} r~ r r� � __total__Z __closed__r� )r� r� r- �nsrl rm rn r Z generic_baseZns_annotationsr � required_keys� optional_keysZ readonly_keysZ mutable_keysZextra_items_typeZ base_dictrh Z qualifiersZannotation_keyrq r~ r� r� r� � s� � � � � � � z_TypedDictMeta.__new__c C s t d��d S )Nz4TypedDict does not support instance and class checks�r� r9 r~ r~ r� r3 � s z _TypedDictMeta.__subclasscheck__) r� r� r� rT r� r� �__call__r3 r� r~ r~ r~ r� rj � s � rj r r~ c K s |t u s|d u r�|t u r d}nd}d| � d| �d�}|� d�| d } tj| tdd � |d urz|d urz|d urz||d < d }|tur�||d < t}|}n |r�td��|r�tjdkr�td��tjdtdd � dt|�i} t |r�dndd�} | d ur�| | d< t | d| |||d�} t f| _ | S )N�2Failing to pass a value for the 'fields' parameter�(Passing `None` as the 'fields' parameter�`z = TypedDict(z, {})`z� is deprecated and will be disallowed in Python 3.15. To create a TypedDict class with 0 fields using the functional syntax, pass an empty dictionary, e.g. r2 r �� stacklevelFTrm rn z@TypedDict takes either a dict or keyword arguments, but not bothr z$TypedDict takes no keyword argumentsz�The kwargs-based syntax for TypedDict definitions is deprecated in Python 3.11, will be removed in Python 3.13, and may not be understood by third-party type checkers.r � r! r� r~ rk ) �_marker�warnings�warn�DeprecationWarningrT r� r rG r� r rj r ro ) �typename�fields�typing_is_inlinerl rm rn r� �deprecated_thing�example�deprecation_msgr� rg �tdr~ r~ r� �_create_typeddict� sL ��� � �r� c @ s* e Zd Zefdded�dd�Zdd� ZdS )�_TypedDictSpecialFormTNrk c K s t ||fd|||d�|��S )NF�r� rl rm rn )r� )r� r� r� rl rm rn r� r~ r~ r� r� � s ���z _TypedDictSpecialForm.__call__c C s t fS r� )� _TypedDict�r� r- r~ r~ r� �__mro_entries__� s z%_TypedDictSpecialForm.__mro_entries__)r� r� r� r� rT r� r� r~ r~ r~ r� r� � s �� r� c C s& t |t�std��td|dddtd�S )aq A simple typed namespace. At runtime it is equivalent to a plain dict. TypedDict creates a dictionary type such that a type checker will expect all instances to have a certain set of keys, where each key is associated with a value of a consistent type. This expectation is not checked at runtime. Usage:: class Point2D(TypedDict): x: int y: int label: str a: Point2D = {'x': 1, 'y': 2, 'label': 'good'} # OK b: Point2D = {'z': 3, 'label': 'bad'} # Fails type check assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first') The type info can be accessed via the Point2D.__annotations__ dict, and the Point2D.__required_keys__ and Point2D.__optional_keys__ frozensets. TypedDict supports an additional equivalent form:: Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str}) By default, all keys must be present in a TypedDict. It is possible to override this by specifying totality:: class Point2D(TypedDict, total=False): x: int y: int This means that a Point2D TypedDict can have any of the keys omitted. A type checker is only expected to support a literal False or True as the value of the total argument. True is the default, and makes all items defined in the class body be required. The Required and NotRequired special forms can also be used to mark individual keys as being required or not required:: class Point2D(TypedDict): x: int # the "x" key must always be present (Required is the default) y: NotRequired[int] # the "y" key can be omitted See PEP 655 for more details on Required and NotRequired. z9TypedDict[...] should be used with a single dict argumentz<inline TypedDict>Tr� )r� r� r� r� rT �r� r� r~ r~ r� r � s 1 ��c C s t | t�S )a Check if an annotation is a TypedDict class For example:: class Film(TypedDict): title: str year: int is_typeddict(Film) # => True is_typeddict(Union[list, str]) # => False )r� �_TYPEDDICT_TYPES�ry r~ r~ r� r= $ s r= r, c C s | S )a� Assert (to the type checker) that the value is of the given type. When the type checker encounters a call to assert_type(), it emits an error if the value is not of the specified type:: def greet(name: str) -> None: assert_type(name, str) # ok assert_type(name, int) # type checker error At runtime this returns the first argument unchanged and otherwise does nothing. r~ )r� �typr~ r~ r� r, 6 s rP c C s t | tj�rt| j�S t| d�r>| jtttfv r>t| j d �S t | tj �rvt dd� | j D ��}|| j krl| S | � |�S tt d�r�t | t j�r�t dd� | j D ��}|| j kr�| S t �| j|�S tt d��rt | t j��rt dd� | j D ��}|| j kr�| S t�tj|�S | S ) z=Strips Annotated, Required and NotRequired from a given type.r� r c s s | ]}t |�V qd S r� �� _strip_extras�r� �ar~ r~ r� r� Q r� z _strip_extras.<locals>.<genexpr>r� c s s | ]}t |�V qd S r� r� r� r~ r~ r� r� V r� r� c s s | ]}t |�V qd S r� r� r� r~ r~ r� r� [ r� )r� r� �_AnnotatedAliasr� r� r� rQ rR rP r� r� r� r r� r� r� r �reduce�operator�or_)r� � stripped_argsr~ r~ r� r� J s( r� c C sD t j| ||dd�}tjdk r*t| |||� |r2|S dd� |�� D �S )a� Return type hints for an object. This is often the same as obj.__annotations__, but it handles forward references encoded as string literals, adds Optional[t] if a default value equal to None is set and recursively replaces all 'Annotated[T, ...]', 'Required[T]' or 'NotRequired[T]' with 'T' (unless 'include_extras=True'). The argument may be a module, class, method, or function. The annotations are returned as a dictionary. For classes, annotations include also inherited members. TypeError is raised if the argument is not of a type that can contain annotations, and an empty dictionary is returned if no annotations are present. BEWARE -- the behavior of globalns and localns is counterintuitive (unless you are familiar with how eval() and exec() work). The search order is locals first, then globals. - If no dict arguments are passed, an attempt is made to use the globals from obj (or the respective module's globals for classes), and these are also used as the locals. If the object does not appear to have globals, an empty dictionary is used. - If one dict argument is passed, it is used for both globals and locals. - If two dict arguments are passed, they specify globals and locals, respectively. T)�globalns�localns�include_extrasr� c S s i | ]\}}|t |��qS r~ r� )r� �kr� r~ r~ r� r| � r� z"get_type_hints.<locals>.<dictcomp>)r� r: r rG �_clean_optionalr� )r� r� r� r� �hintr~ r~ r� r: b s � r: c C s& t | tj�sdS | jd tur"dS dS )z detects Union[..., None] patternFr T)r� r� �_UnionGenericAliasr� � _NoneTyper� r~ r~ r� �_could_be_inserted_optional� s r� c C s, |rt | t�rd S t�| �}|s$d S | j}|�� D ]�\}}t|�r2||vs2|| d urXq2|| }|d u rlt}t |t�r�|d u r�t | t j �r�| j }n"| } t | d�r�| j } q�t| di �}|d u r�|}n |d u r�|}t|t | t j � d�}t�|||�} | |k�s t t d�r2t | t j�r2t |t j�s2| ||< q2d S )N� __wrapped__� __globals__)� is_argumentr� )r� r� r� � _get_defaultsr r� r� r� r� r� � ModuleTyper r� r� r� r\ � _eval_typer� ) r� �hintsr� r� r� Zoriginal_hintsr� r^ �original_value�nsobjZoriginal_evaluatedr~ r~ r� r� � sR � � � � � �r� c C s@ t | tj�rtS t | tjtjttf�r,| j S | tj u r<tj S dS )a6 Get the unsubscripted version of a type. This supports generic types, Callable, Tuple, Union, Literal, Final, ClassVar and Annotated. Return None for unsupported types. Examples:: get_origin(Literal[42]) is Literal get_origin(int) is None get_origin(ClassVar[int]) is ClassVar get_origin(Generic) is Generic get_origin(Generic[T]) is Generic get_origin(Union[T, int]) is Union get_origin(List[Tuple[T, T]][int]) == list get_origin(P.args) is P N) r� r� r� r* �_BaseGenericAliasr� r� r r r� r_ r� r~ r~ r� r7 � s � r7 c C sp t | tj�r | jg| j�R S t | tjtjf�rl| j}t | �t j j u rh|d t urht|dd� �|d f}|S dS )a� Get type arguments with all substitutions performed. For unions, basic simplifications used by Union constructor are performed. Examples:: get_args(Dict[str, int]) == (str, int) get_args(int) == () get_args(Union[int, Union[T, int], str][int]) == (int, str) get_args(Union[int, Tuple[T, int]][str]) == (int, Tuple[str, int]) get_args(Callable[[], T][int]) == ([], int) r Nr r~ )r� r� r� r� � __metadata__r� r� r� r� r7 r> r rX �Ellipsisr� )ry �resr~ r~ r� r6 � s r6 rH c C s t | � d���dS )a& Special marker indicating that an assignment should be recognized as a proper type alias definition by type checkers. For example:: Predicate: TypeAlias = Callable[..., bool] It's invalid when used anywhere except as in the example above. � is not subscriptableNr� �r� r� r~ r~ r� rH s c s � fdd�| _ � | _d S )Nc s � t uS r� )rS r~ �r r~ r� �<lambda> r� z _set_default.<locals>.<lambda>)� has_default� __default__)� type_paramr r~ r� r� � _set_default s r� c C s t dd�}|dkr|| _d S )Nr r! r )r r� )Z typevarlike�def_modr~ r~ r� � _set_module s r� c @ s e Zd ZdZdZeZdS )� _DefaultMixinz Mixin for TypeVarLike defaults.r~ N)r� r� r� r� rD r� r� r~ r~ r~ r� r� s r� c @ s e Zd Zeed�dd�ZdS )�_TypeVarLikeMeta)�_TypeVarLikeMeta__instancer; c C s t || j�S r� )r� �_backported_typevarlike)r� r� r~ r~ r� r� ( s z"_TypeVarLikeMeta.__instancecheck__N)r� r� r� r �boolr� r~ r~ r~ r� r� ' s r� )r c @ s: e Zd ZdZejZdddedd�dd�Zdd�dd �Z dS ) r zType variable.NF)�boundr� r� r �infer_variancec s� t td�r*tj|g|�R ||||d��� n6tj|g|�R |||d��� |rZ|sR|rZtd��|� _t� |� t� � � fdd�}|� _� S )NrI �r� r� r� r� �r� r� r� z1Variance cannot be specified with infer_variance.c s, � � � r(| j�� �t|�kr(|� jf7 }|S r� )r� �__parameters__�indexr� r� )�aliasr� �Ztypevarr~ r� �_tvar_prepare_substG s �� z,TypeVar.__new__.<locals>._tvar_prepare_subst)r� r� r r �__infer_variance__r� r� �__typing_prepare_subst__) r� r� r� r� r� r r� � constraintsr� r~ r� r� r� 5 s � � zTypeVar.__new__r: c C s t dt� d���d S )N�type 'z(.TypeVar' is not an acceptable base typer] r< r~ r~ r� rA R s zTypeVar.__init_subclass__) r� r� r� r� r� r r� rS r� rA r~ r~ r~ r� r 0 s � r r c @ s$ e Zd ZdZdZdd� Zdd� ZdS )� _Immutablez3Mixin to indicate that object should not be copied.r~ c C s | S r� r~ r r~ r~ r� �__copy__` s z_Immutable.__copy__c C s | S r� r~ )r� �memor~ r~ r� � __deepcopy__c s z_Immutable.__deepcopy__N)r� r� r� r� rD r� r� r~ r~ r~ r� r� \ s r� c @ s( e Zd ZdZdd� Zdd� Zdd� ZdS ) r aQ The args for a ParamSpec object. Given a ParamSpec object P, P.args is an instance of ParamSpecArgs. ParamSpecArgs objects have a reference back to their ParamSpec: P.args.__origin__ is P This type is meant for runtime introspection and has no special meaning to static type checkers. c C s || _ d S r� �r� �r� r� r~ r~ r� r� r s zParamSpecArgs.__init__c C s | j j� d�S )Nz.args�r� r� r r~ r~ r� r� u s zParamSpecArgs.__repr__c C s t |t�stS | j|jkS r� )r� r r� r� �r� r� r~ r~ r� r� x s zParamSpecArgs.__eq__N�r� r� r� r� r� r� r� r~ r~ r~ r� r f s c @ s( e Zd ZdZdd� Zdd� Zdd� ZdS ) r a[ The kwargs for a ParamSpec object. Given a ParamSpec object P, P.kwargs is an instance of ParamSpecKwargs. ParamSpecKwargs objects have a reference back to their ParamSpec: P.kwargs.__origin__ is P This type is meant for runtime introspection and has no special meaning to static type checkers. c C s || _ d S r� r� r� r~ r~ r� r� � s zParamSpecKwargs.__init__c C s | j j� d�S )Nz.kwargsr� r r~ r~ r� r� � s zParamSpecKwargs.__repr__c C s t |t�stS | j|jkS r� )r� r r� r� r� r~ r~ r� r� � s zParamSpecKwargs.__eq__Nr� r~ r~ r~ r� r } s r )r r c @ s: e Zd ZdZejZdddded�dd�Zdd�dd �Z dS ) r zParameter specification.NF�r� r� r� r� r c s` t td�r tj|||||d�� ntj||||d�� |� _t� |� t� � � fdd�}|� _� S )NrI r� r� c s� | j }|�� �}|t|�kr2� �� r2g |�� j�}|t|�krLtd| � ���t|�dkrzt�|d �sz|dksrJ �|f}n<t|| t �r�g |d |� �t || ��||d d � �R }|S )N�Too few arguments for r� r ) r� r� r� r� r� r� r� �_is_param_exprr� r� r� )r� r� r� �i�Z paramspecr~ r� �_paramspec_prepare_subst� s .z3ParamSpec.__new__.<locals>._paramspec_prepare_subst)r� r� r r� r� r� r� )r� r� r� r� r� r� r r� r~ r� r� r� � s �� zParamSpec.__new__r: c C s t dt� d���d S )Nr� z*.ParamSpec' is not an acceptable base typer] r< r~ r~ r� rA � s zParamSpec.__init_subclass__) r� r� r� r� r� r r� rS r� rA r~ r~ r~ r� r � s � %c @ sl e Zd ZdZejZedd� �Zedd� �Z dddde d�d d �Z d d � Z d d� Z dd� Zdd� Zdd� ZdS )r a' Parameter specification variable. Usage:: P = ParamSpec('P') Parameter specification variables exist primarily for the benefit of static type checkers. They are used to forward the parameter types of one callable to another callable, a pattern commonly found in higher order functions and decorators. They are only valid when used in ``Concatenate``, or s the first argument to ``Callable``. In Python 3.10 and higher, they are also supported in user-defined Generics at runtime. See class Generic for more information on generic types. An example for annotating a decorator:: T = TypeVar('T') P = ParamSpec('P') def add_logging(f: Callable[P, T]) -> Callable[P, T]: '''A type-safe decorator to add logging to a function.''' def inner(*args: P.args, **kwargs: P.kwargs) -> T: logging.info(f'{f.__name__} was called') return f(*args, **kwargs) return inner @add_logging def add_two(x: float, y: float) -> float: '''Add two numbers together.''' return x + y Parameter specification variables defined with covariant=True or contravariant=True can be used to declare covariant or contravariant generic types. These keyword arguments are valid, but their actual semantics are yet to be decided. See PEP 612 for details. Parameter specification variables can be introspected. e.g.: P.__name__ == 'T' P.__bound__ == None P.__covariant__ == False P.__contravariant__ == False Note that only parameter specification variables defined in global scope can be pickled. c C s t | �S r� )r r r~ r~ r� r� � s zParamSpec.argsc C s t | �S r� )r r r~ r~ r� r� s zParamSpec.kwargsNFr� c C sp t �| | g� || _t|�| _t|�| _t|�| _|rFt�|d�| _ nd | _ t �| |� t � }|dkrl|| _ d S )NzBound must be a type.r ) r� r� r� r� � __covariant__�__contravariant__r� r� r� � __bound__r� r r� )r� r� r� r� r� r� r r� r~ r~ r� r� s zParamSpec.__init__c C s2 | j r d}n | jrd}n| jr$d}nd}|| j S )N� �+�-�~)r� r� r� r� )r� �prefixr~ r~ r� r� s zParamSpec.__repr__c C s t �| �S r� �r� r� r r~ r~ r� r� $ s zParamSpec.__hash__c C s | |u S r� r~ r� r~ r~ r� r� ' s zParamSpec.__eq__c C s | j S r� �r� r r~ r~ r� rc * s zParamSpec.__reduce__c O s d S r� r~ r$ r~ r~ r� r� . s zParamSpec.__call__)r� r� r� r� r� r r� �propertyr� r� rS r� r� r� r� rc r� r~ r~ r~ r� r � s / � r � _type_convert)�allow_special_formsc C sT | du rt d�S t| t�rPtjdkr,t| �S tjdkrBt| |d�S t| ||d�S | S )z=For converting None to type(None), and strings to ForwardRef.N)r � � )r r � ru )rg �is_class)r� r� r� r rG r\ )r' rg r r~ r~ r� r 8 s c sV e Zd ZejZ� fdd�Zdd� Zdd� Zdd� Z e d d � �Z d d � Z d d� Z � ZS )�_ConcatenateGenericAliasc s t � �|� || _|| _d S r� )r� r� r� r� )r� r� r� r� r~ r� r� K s z!_ConcatenateGenericAlias.__init__c s2 t j� � | j�� dd�� fdd�| jD ��� d�S )N�[�, c 3 s | ]}� |�V qd S r� r~ �r� r' �� _type_reprr~ r� r� S r� z4_ConcatenateGenericAlias.__repr__.<locals>.<genexpr>�])r� r r� �joinr� r r~ r r� r� P s �z!_ConcatenateGenericAlias.__repr__c C s t | j| jf�S r� )r� r� r� r r~ r~ r� r� U s z!_ConcatenateGenericAlias.__hash__c O s d S r� r~ r$ r~ r~ r� r� Y s z!_ConcatenateGenericAlias.__call__c C s t dd� | jD ��S )Nc s s" | ]}t |tjtf�r|V qd S r� )r� r� r r )r� ry r~ r~ r� r� ^ s z:_ConcatenateGenericAlias.__parameters__.<locals>.<genexpr>)r� r� r r~ r~ r� r� \ s �z'_ConcatenateGenericAlias.__parameters__c C s� t |d t�r,g |d d� �|d j�R }nNt |d ttf�rXg |d d� �|d �R S |d du szt |d t�sztd��| �| j|�S �Nr .�MThe last parameter to Concatenate should be a ParamSpec variable or ellipsis.) r� r r� r� r� r r� r� r� �r� r� r~ r~ r� r c s �"_ConcatenateGenericAlias.copy_withc s� | j ttfv r td| � ���| js0t| � d���t|t�s@|f}tdd� |D �� }| j}|D ]�}t|dd �}|d ur�|| |�}q\t|t �r\|� |�}|t |�kr�t|dt �t ur�g |�|j �}|t |�kr�td| � ���t |�dk�r t|d ��s |d k�sJ �|f}q\t|| t�r\t|| t�s\g |d |� �t|| ��||d d � �R }q\t |�}t |�}||k�r�td ||k�r�d nd � d | � d|� d|� ���tt| j|��� g }| jD ]�} t| t��r�|�| � �q�t| t��r:� | } t| tj��rt| ��s*ttd��r�t| tj ��r�t| dd��r�t| � d���nPt| ttd��sPtjn tjtj f��r�| j} | �r�t� fdd�| D ��} | | } |�| � �q�| � t|��S )Nz%Cannot subscript already-subscripted r� c s s | ]}t |�V qd S r� )r r� r~ r~ r� r� w r� �7_ConcatenateGenericAlias.__getitem__.<locals>.<genexpr>r� r� r� r� r r� r� r� r� r� r� r� � __unpacked__Fz is not valid as type argumentc 3 s | ]}� | V qd S r� r~ )r� �x��substr~ r� r� � r� ) r� r_ rB r� r� r� r� � _unpack_argsr� r r� r� rS r� r� r� r r� �zipr� r� r� r r� r� � _is_unpackr� r� r� r ) r� r� r� �param�preparer� �alen�plen�new_argsr' � subparams�subargsr~ r r� r� n s� �� � �0 ��� ��� � �� ��$_ConcatenateGenericAlias.__getitem__)r� r� r� r� r� r� r� r� r� r� r r� r r� r� r~ r~ r� r� r F s r c s, e Zd ZdZ� fdd�Z� fdd�Z� ZS )r r� c s� t |d ttf�r,g |d d� �|d �R S t |d tj�rZg |d d� �|d j�R }n"|d du s|t |d t�s|td��ttj| �� |�S r ) r� r� r� r� r r� r r� r� r r r� r~ r� r � s r c sB t � �|�}t|t�r>tdd� |D ��r>ttdd� |D �� �S |S )Nc s s | ]}t |�V qd S r� �r! �r� r� r~ r~ r� r� � r� r c s s | ] }|V qd S r� r~ �r� rx r~ r~ r� r� � r� )r� r� r� r� rB r )r� r� r^ r� r~ r� r� � s r) )r� r� r� r r� r� r~ r~ r� r� r � s c @ s e Zd ZdS )�_EllipsisDummyN)r� r� r� r~ r~ r~ r� r- � r� r- c C s� |d du r,t jdk r,g |d d� �t�R }t jdkrLt| |ttfdd�}n t| |�}|d turf|S tdd� |jD ��|_t jd k r�|S td d� |jD ��|_|S ) Nr .)r r r )r r� r T)Z_typevar_typesZ_paramspec_tvarsc s s | ]}|t ur|nd V qdS ).N�r- r� r~ r~ r� r� � s �z,_create_concatenate_alias.<locals>.<genexpr>r� c s s | ]}|t ur|V qd S r� r. r� r~ r~ r� r� � s �) r rG r- r r r r� r� r� )r� r� Z concatenater~ r~ r� �_create_concatenate_alias� s" � � r/ c sx |dkrt d��t|t�s |f}|d du sBt|d t�sBt d��d� g � fdd�|d d� D ��|d �R }t| |�S ) Nr~ z&Cannot take a Concatenate of no types.r .r z/Concatenate[arg, ...]: each arg must be a type.c 3 s | ]}t �|� �V qd S r� r� r� r� r~ r� r� � r� z'_concatenate_getitem.<locals>.<genexpr>)r� r� r� r r/ r� r~ r� r� �_concatenate_getitem� s �r0 c C s t | |�S )a& Used in conjunction with ``ParamSpec`` and ``Callable`` to represent a higher order function which adds, removes or transforms parameters of a callable. For example:: Callable[Concatenate[int, P], int] See PEP 612 for detailed information. )r0 r� r~ r~ r� r s rK c C s t �|| � d��}t �| |f�S )a Special typing form used to annotate the return type of a user-defined type guard function. ``TypeGuard`` only accepts a single type argument. At runtime, functions marked this way should return a boolean. ``TypeGuard`` aims to benefit *type narrowing* -- a technique used by static type checkers to determine a more precise type of an expression within a program's code flow. Usually type narrowing is done by analyzing conditional code flow and applying the narrowing to a block of code. The conditional expression here is sometimes referred to as a "type guard". Sometimes it would be convenient to use a user-defined boolean function as a type guard. Such a function should use ``TypeGuard[...]`` as its return type to alert static type checkers to this intention. Using ``-> TypeGuard`` tells the static type checker that for a given function: 1. The return value is a boolean. 2. If the return value is ``True``, the type of its argument is the type inside ``TypeGuard``. For example:: def is_str(val: Union[str, float]): # "isinstance" type guard if isinstance(val, str): # Type of ``val`` is narrowed to ``str`` ... else: # Else, type of ``val`` is narrowed to ``float``. ... Strict type narrowing is not enforced -- ``TypeB`` need not be a narrower form of ``TypeA`` (it can even be a wider form) and this may lead to type-unsafe results. The main reason is to allow for things like narrowing ``List[object]`` to ``List[str]`` even though the latter is not a subtype of the former, since ``List`` is invariant. The responsibility of writing type-safe type guards is left to the user. ``TypeGuard`` also works with type variables. For more information, see PEP 647 (User-Defined Type Guards). � accepts only a single type.�r� r� r� �r� r� �itemr~ r~ r� rK s ,rL c C s t �|| � d��}t �| |f�S )aw Special typing form used to annotate the return type of a user-defined type narrower function. ``TypeIs`` only accepts a single type argument. At runtime, functions marked this way should return a boolean. ``TypeIs`` aims to benefit *type narrowing* -- a technique used by static type checkers to determine a more precise type of an expression within a program's code flow. Usually type narrowing is done by analyzing conditional code flow and applying the narrowing to a block of code. The conditional expression here is sometimes referred to as a "type guard". Sometimes it would be convenient to use a user-defined boolean function as a type guard. Such a function should use ``TypeIs[...]`` as its return type to alert static type checkers to this intention. Using ``-> TypeIs`` tells the static type checker that for a given function: 1. The return value is a boolean. 2. If the return value is ``True``, the type of its argument is the intersection of the type inside ``TypeIs`` and the argument's previously known type. For example:: def is_awaitable(val: object) -> TypeIs[Awaitable[Any]]: return hasattr(val, '__await__') def f(val: Union[int, Awaitable[int]]) -> int: if is_awaitable(val): assert_type(val, Awaitable[int]) else: assert_type(val, int) ``TypeIs`` also works with type variables. For more information, see PEP 742 (Narrowing types with TypeIs). r1 r2 r3 r~ r~ r� rL P s &rJ c @ s e Zd Zdd� ZdS )� _TypeFormFormc C s |S r� r~ r� r~ r~ r� r� � s z_TypeFormForm.__call__N)r� r� r� r� r~ r~ r~ r� r5 s r5 c C s t �|| � d��}t �| |f�S )a� A special form representing the value that results from the evaluation of a type expression. This value encodes the information supplied in the type expression, and it represents the type described by that type expression. When used in a type expression, TypeForm describes a set of type form objects. It accepts a single type argument, which must be a valid type expression. ``TypeForm[T]`` describes the set of all type form objects that represent the type T or types that are assignable to T. Usage: def cast[T](typ: TypeForm[T], value: Any) -> T: ... reveal_type(cast(int, "x")) # int See PEP 747 for more information. r1 r2 r3 r~ r~ r� rJ � s c @ sn e Zd ZdZdd� Zdd� Zdd� Zdd � Zd d � Zd d � Z dd� Z dd� Z dd� Z dd� Z ejdd� �ZdS )� _SpecialForm)r� r� �_getitemc C s || _ |j| _|j| _d S r� )r7 r� r� r� �r� �getitemr~ r~ r� r� � s z_SpecialForm.__init__c C s |dv r| j S t|��d S )N> r� r� )r� r� )r� r4 r~ r~ r� � __getattr__� s z_SpecialForm.__getattr__c C s t d| ����d S )NzCannot subclass r� r� r~ r~ r� r� � s z _SpecialForm.__mro_entries__c C s d| j � �S r� r� r r~ r~ r� r� � s z_SpecialForm.__repr__c C s | j S r� r� r r~ r~ r� rc � s z_SpecialForm.__reduce__c O s t d| ����d S )NzCannot instantiate r� �r� r� �kwdsr~ r~ r� r� � s z_SpecialForm.__call__c C s t j| |f S r� �r� ru r� r~ r~ r� �__or__� s z_SpecialForm.__or__c C s t j|| f S r� r= r� r~ r~ r� �__ror__� s z_SpecialForm.__ror__c C s t | � d���d S )Nz! cannot be used with isinstance()r� r� r~ r~ r� r� � s z _SpecialForm.__instancecheck__c C s t | � d���d S )Nz! cannot be used with issubclass()r� )r� r� r~ r~ r� r3 � s z _SpecialForm.__subclasscheck__c C s | � | |�S r� )r7 r� r~ r~ r� r� � s z_SpecialForm.__getitem__N)r� r� r� rD r� r: r� r� rc r� r> r? r� r3 r� r r� r~ r~ r~ r� r6 � s r6 r c C s t | � d���dS )aD Represents an arbitrary literal string. Example:: from typing_extensions import LiteralString def query(sql: LiteralString) -> ...: ... query("SELECT * FROM table") # ok query(f"SELECT * FROM {input()}") # not ok See PEP 675 for details. r� Nr� r r~ r~ r� r � s r c C s t | � d���dS )z�Used to spell the type of "self" in classes. Example:: from typing import Self class ReturnsSelf: def parse(self, data: bytes) -> Self: ... return self r� Nr� r r~ r~ r� r � s rN c C s t | � d���dS )a� The bottom type, a type that has no members. This can be used to define a function that should never be called, or a function that never returns:: from typing_extensions import Never def never_call_me(arg: Never) -> None: pass def int_or_str(arg: int | str) -> None: never_call_me(arg) # type checker error match arg: case int(): print("It's an int") case str(): print("It's a str") case _: never_call_me(arg) # ok, arg is of type Never r� Nr� r r~ r~ r� rN � s rQ c C s" t �|| j� d��}t �| |f�S )a� A special typing construct to mark a key of a total=False TypedDict as required. For example: class Movie(TypedDict, total=False): title: Required[str] year: int m = Movie( title='The Matrix', # typechecker error if key is omitted year=1999, ) There is no runtime checking that a required key is actually provided when instantiating a related TypedDict. r1 �r� r� r� r� r3 r~ r~ r� rQ s c C s" t �|| j� d��}t �| |f�S )a` A special typing construct to mark a key of a TypedDict as potentially missing. For example: class Movie(TypedDict): title: str year: NotRequired[int] m = Movie( title='The Matrix', # typechecker error if key is omitted year=1999, ) r1 r@ r3 r~ r~ r� rR * s rR c C s" t �|| j� d��}t �| |f�S )a� A special typing construct to mark an item of a TypedDict as read-only. For example: class Movie(TypedDict): title: ReadOnly[str] year: int def mutate_movie(m: Movie) -> None: m["year"] = 1992 # allowed m["title"] = "The Matrix" # typechecker error There is no runtime checking for this property. r1 r@ r3 r~ r~ r� rP ? s a� Type unpack operator. The type unpack operator takes the child types from some container type, such as `tuple[int, str]` or a `TypeVarTuple`, and 'pulls them out'. For example: # For some generic class `Foo`: Foo[Unpack[tuple[int, str]]] # Equivalent to Foo[int, str] Ts = TypeVarTuple('Ts') # Specifies that `Bar` is generic in an arbitrary number of types. # (Think of `Ts` as a tuple of an arbitrary number of individual # `TypeVar`s, which the `Unpack` is 'pulling out' directly into the # `Generic[]`.) class Bar(Generic[Unpack[Ts]]): ... Bar[int] # Valid Bar[int, str] # Also valid From Python 3.11, this can also be done using the `*` operator: Foo[*tuple[int, str]] class Bar(Generic[*Ts]): ... The operator can also be used along with a `TypedDict` to annotate `**kwargs` in a function signature. For instance: class Movie(TypedDict): name: str year: int # This function expects two keyword arguments - *name* of type `str` and # *year* of type `int`. def foo(**kwargs: Unpack[Movie]): ... Note that there is only some runtime checking of this operator. Not everything the runtime allows may be accepted by static type checkers. For more information, see PEP 646 and PEP 692. c C s t | �tu S r� )r7 r �r� r~ r~ r� r! � s r! c s e Zd Z� fdd�Z� ZS )�_UnpackSpecialFormc s t � �|� t| _d S r� )r� r� � _UNPACK_DOCr� r8 r� r~ r� r� � s z_UnpackSpecialForm.__init__)r� r� r� r� r� r~ r~ r� r� rB � s rB c sD e Zd Zejdk rejZedd� �Z edd� �Z � fdd�Z � Z S )� _UnpackAliasr� c C sV | j tu sJ �t| j�dks J �| j\}t|tjtjf�rR|j t urLt d��|jS d S )Nr� z*Unpack[...] must be used with a tuple type) r� r r� r� r� r� r� r� r� r� r� )r� r' r~ r~ r� � __typing_unpacked_tuple_args__� s z+_UnpackAlias.__typing_unpacked_tuple_args__c C s0 | j tu sJ �t| j�dks J �t| jd t�S )Nr� r )r� r r� r� r� r r r~ r~ r� �#__typing_is_unpacked_typevartuple__� s z0_UnpackAlias.__typing_is_unpacked_typevartuple__c s | j r |S t� �|�S r� )rF r� r� r� r� r~ r� r� � s z_UnpackAlias.__getitem__) r� r� r� r rG r� r r� r rE rF r� r� r~ r~ r� r� rD � s rD c C s t �|| j� d��}t| |f�S )Nr1 )r� r� r� rD r3 r~ r~ r� r � s r c C s t | t�S r� )r� rD rA r~ r~ r� r! � s c G sL g }| D ]>}t |dd �}|d ur<|r0|d du s<|�|� q|�|� q|S )NrE r .)r� r� r� )r� Znewargsr' r( r~ r~ r� r � s r )r r c @ s, e Zd ZdZejZed�dd�Zdd� Z dS )r zType variable tuple.r� c s2 t �|�� t� |� t� � � fdd�}|� _� S )Nc s� | j }|�� �}||d d � D ] }t|t�r td| � ���q t|�}t|�}|}|| d }d } d } t|�D ]V\} } t| t�snt| dd �} | rnt| �dkrn| d du rn| d ur�td��| } | d } qn| d ur�t || �}t ||| d �}n,|| |k�rtd | � d |� d |d � ���||| k�r<� � � �r<t � j �}n|||| � }g |d |� �| g|| �|�| g|| | | d �||| d � �R S ) Nr� z(More than one TypeVarTuple parameter in rE r r .z6More than one unpacked arbitrary-length tuple argumentr r� r� z, expected at least ) r� r� r� r r� r� � enumerater� r� �minr� r r� )r� r� r� Ztypevartuple_indexr" r$ r% �left�rightZvar_tuple_indexZfillargr� r' r( � replacement�Ztvtr~ r� �_typevartuple_prepare_subst� s\ � � �� � ����z9TypeVarTuple.__new__.<locals>._typevartuple_prepare_subst)r� r r� r� r� )r� r� r rM r~ rL r� r� � s -zTypeVarTuple.__new__c O s t d��d S )N�&Cannot subclass special typing classesr� r; r~ r~ r� rA � s � TypeVarTuple.__init_subclass__N) r� r� r� r� r� r r� rS r� rA r~ r~ r~ r� r � s 5c @ sT e Zd ZdZejZdd� Zed�dd�Z dd� Z d d � Z d d � Z d d� Z dd� ZdS )r a� Type variable tuple. Usage:: Ts = TypeVarTuple('Ts') In the same way that a normal type variable is a stand-in for a single type such as ``int``, a type variable *tuple* is a stand-in for a *tuple* type such as ``Tuple[int, str]``. Type variable tuples can be used in ``Generic`` declarations. Consider the following example:: class Array(Generic[*Ts]): ... The ``Ts`` type variable tuple here behaves like ``tuple[T1, T2]``, where ``T1`` and ``T2`` are type variables. To use these type variables as type parameters of ``Array``, we must *unpack* the type variable tuple using the star operator: ``*Ts``. The signature of ``Array`` then behaves as if we had simply written ``class Array(Generic[T1, T2]): ...``. In contrast to ``Generic[T1, T2]``, however, ``Generic[*Shape]`` allows us to parameterise the class with an *arbitrary* number of type parameters. Type variable tuples can be used anywhere a normal ``TypeVar`` can. This includes class definitions, as shown above, as well as function signatures and variable annotations:: class Array(Generic[*Ts]): def __init__(self, shape: Tuple[*Ts]): self._shape: Tuple[*Ts] = shape def get_shape(self) -> Tuple[*Ts]: return self._shape shape = (Height(480), Width(640)) x: Array[Height, Width] = Array(shape) y = abs(x) # Inferred type is Array[Height, Width] z = x + x # ... is Array[Height, Width] x.get_shape() # ... is tuple[Height, Width] c c s | j V d S r� )r r r~ r~ r� �__iter__+ s zTypeVarTuple.__iter__r� c C s4 || _ t�| |� t� }|dkr&|| _t| | _d S )Nr )r� r� r� r r� r r )r� r� r r� r~ r~ r� r� . s zTypeVarTuple.__init__c C s | j S r� r r r~ r~ r� r� 9 s zTypeVarTuple.__repr__c C s t �| �S r� r r r~ r~ r� r� < s zTypeVarTuple.__hash__c C s | |u S r� r~ r� r~ r~ r� r� ? s zTypeVarTuple.__eq__c C s | j S r� r r r~ r~ r� rc B s zTypeVarTuple.__reduce__c O s d|vrt d��d S )Nr� rN r� r; r~ r~ r� rA E s rO N)r� r� r� r� r� r r� rP rS r� r� r� r� rc rA r~ r~ r~ r� r � s , rD )r� r; c C s t dt| �j��tjd� | S )a� Reveal the inferred type of a variable. When a static type checker encounters a call to ``reveal_type()``, it will emit the inferred type of the argument:: x: int = 1 reveal_type(x) Running a static type checker (e.g., ``mypy``) on this example will produce output similar to 'Revealed type is "builtins.int"'. At runtime, the function prints the runtime type of the argument and returns it unchanged. zRuntime type is )�file)�printr� r� r �stderrrA r~ r~ r� rD M s � _ASSERT_NEVER_REPR_MAX_LENGTH�d r+ �r' r; c C s6 t | �}t|�tkr$|dt� d }td|� ���dS )a1 Assert to the type checker that a line of code is unreachable. Example:: def int_or_str(arg: int | str) -> None: match arg: case int(): print("It's an int") case str(): print("It's a str") case _: assert_never(arg) If a type checker finds that a call to assert_never() is reachable, it will emit an error. At runtime, this throws an exception when called. Nz...z*Expected code to be unreachable, but got: )�reprr� rT �AssertionError)r' r^ r~ r~ r� r+ j s )� eq_default� order_default�kw_only_default�frozen_default�field_specifiers.)rY rZ r[ r\ r] r� r; c s � �����fdd�}|S )a� Decorator that marks a function, class, or metaclass as providing dataclass-like behavior. Example: from typing_extensions import dataclass_transform _T = TypeVar("_T") # Used on a decorator function @dataclass_transform() def create_model(cls: type[_T]) -> type[_T]: ... return cls @create_model class CustomerModel: id: int name: str # Used on a base class @dataclass_transform() class ModelBase: ... class CustomerModel(ModelBase): id: int name: str # Used on a metaclass @dataclass_transform() class ModelMeta(type): ... class ModelBase(metaclass=ModelMeta): ... class CustomerModel(ModelBase): id: int name: str Each of the ``CustomerModel`` classes defined in this example will now behave similarly to a dataclass created with the ``@dataclasses.dataclass`` decorator. For example, the type checker will synthesize an ``__init__`` method. The arguments to this decorator can be used to customize this behavior: - ``eq_default`` indicates whether the ``eq`` parameter is assumed to be True or False if it is omitted by the caller. - ``order_default`` indicates whether the ``order`` parameter is assumed to be True or False if it is omitted by the caller. - ``kw_only_default`` indicates whether the ``kw_only`` parameter is assumed to be True or False if it is omitted by the caller. - ``frozen_default`` indicates whether the ``frozen`` parameter is assumed to be True or False if it is omitted by the caller. - ``field_specifiers`` specifies a static list of supported classes or functions that describe fields, similar to ``dataclasses.field()``. At runtime, this decorator records its arguments in the ``__dataclass_transform__`` attribute on the decorated object. See PEP 681 for details. c s � �����d�| _ | S )N)rY rZ r[ r\ r] r� )Z__dataclass_transform__)Z cls_or_fn�rY r] r\ r[ r� rZ r~ r� � decorator� s �z&dataclass_transform.<locals>.decoratorr~ )rY rZ r[ r\ r] r� r_ r~ r^ r� r. � s I r. rA �_F)r� c C s& z d| _ W n ttfy Y n0 | S )aH Indicate that a method is intended to override a method in a base class. Usage: class Base: def method(self) -> None: pass class Child(Base): @override def method(self) -> None: super().method() When this decorator is applied to a method, the type checker will validate that it overrides a method with the same name on a base class. This helps prevent bugs that may occur when a base class is changed without an equivalent change to a child class. There is no runtime checking of these properties. The decorator sets the ``__override__`` attribute to ``True`` on the decorated object to allow runtime introspection. See PEP 698 for details. T)Z __override__r� r� r& r~ r~ r� rA � s )r rz r �_Tc @ sH e Zd ZdZedd�eejeje e dd�dd�Z e e d�d d �Z dS ) r/ a Indicate that a class, function or overload is deprecated. When this decorator is applied to an object, the type checker will generate a diagnostic on usage of the deprecated object. Usage: @deprecated("Use B instead") class A: pass @deprecated("Use g instead") def f(): pass @overload @deprecated("int support is deprecated") def g(x: int) -> int: ... @overload def g(x: str) -> int: ... The warning specified by *category* will be emitted at runtime on use of deprecated objects. For functions, that happens on calls; for classes, on instantiation and on creation of subclasses. If the *category* is ``None``, no warning is emitted at runtime. The *stacklevel* determines where the warning is emitted. If it is ``1`` (the default), the warning is emitted at the direct caller of the deprecated object; if it is higher, it is emitted further up the stack. Static type checker behavior is not affected by the *category* and *stacklevel* arguments. The deprecation message passed to the decorator is saved in the ``__deprecated__`` attribute on the decorated object. If applied to an overload, the decorator must be after the ``@overload`` decorator for the attribute to exist on the overload as returned by ``get_overloads()``. See PEP 702 for details. r� ��categoryr� N)�messagerc r� r; c C s4 t |t�s tdt|�j����|| _|| _|| _d S )Nz2Expected an object of type str for 'message', not )r� r� r� r� r� rd rc r� )r� rd rc r� r~ r~ r� r� 7 s ��zdeprecated.__init__rV c sv | j �| j�| j��d u r$�� _� S t� t�r�dd l}ddlm} � j �|� ��� ����fdd��}t |�� _ � j �t�|�r��j �|� ������fdd��}t|�� _ n"|� ������fdd��}|� _ � � _|_�|_� S t� ��rddd l}dd l}dd l}|� � �� ���fdd ��}|j�� ��rTtjd k�rJ|�|�}n |jj|_� � _|_|S td � ����d S ) Nr )� MethodTypec sn | � u r t j���d d� �tjur<�| g|�R i |��S | jtju rb|sP|rbt| j� d���n�| �S d S )Nr� rb z() takes no arguments)r� r� r� r� r� r� r� r� )r' rc r� � original_newr� r~ r� r� W s z$deprecated.__call__.<locals>.__new__c s" t j�� �d d� �| i |��S �Nr� rb �r� r� �r� r� �rc r� �original_init_subclassr� r~ r� rA k s z.deprecated.__call__.<locals>.__init_subclass__c s" t j�� �d d� �| i |��S rg rh ri rj r~ r� rA t s c s" t j���d d� � | i |��S rg rh ri )r' rc r� r� r~ r� �wrapper� s z$deprecated.__call__.<locals>.wrapperrK zY@deprecated decorator with non-None category must be applied to a class or callable, not )rd rc r� Z__deprecated__r� r� r �typesre r� �wraps� staticmethodrA r� � classmethodrH Zasyncio.coroutinesr6 � coroutines�iscoroutinefunctionr rG Zmarkcoroutinefunction� _is_coroutiner� ) r� r' r re r� rA �asyncior6 rl r~ )r' rc r� rk rf r� r� r� H sT ��zdeprecated.__call__)r� r� r� r� r� r� r� rm r �Warningr= r� ra r� r~ r~ r~ r� r/ s .�� r/ c C s | du pt | ttttf�S �N.)r� r� r� r r r& r~ r~ r� r� � s �r� c C s | du p t | tttttjf�S rv )r� r� r� r r r� r& r~ r~ r� r� � s ��c C sz t �| �rHt| tj�rHt| j�dkrHt| jd t�rH|rHt |d �sHdS |sZt | � d���|t u r�t | d�rr| js�t | � d���t| j�}t|�}||k�rv|}t | d��r.dd� | jD �}t dd � |D ��}|dkr�||| kr�dS ||k �r.t|| d t�tu�r dS t d d � |D ��}||8 }d |� �}tjd k�r>dnd}t d||k�rTdnd� d|� d| � d|� d|� � ��dS )��Check correct count for parameters of a generic cls (internal helper). This gives a nice error message in case of count mismatch. r� r Nr� r� c S s g | ]}t |�s|�qS r~ r* r� r~ r~ r� � <listcomp>� r� �"_check_generic.<locals>.<listcomp>c s s | ]}t |t�V qd S r� )r� r r� r~ r~ r� r� � r� �!_check_generic.<locals>.<genexpr>r� c s s | ]}t |d t�tuV qdS �r� N�r� rS r� r~ r~ r� r� � s � �r� r� � argumentsr� r� r� r� � z for r� r� )r6 �isclassrF r� r_ r� r� r� r r� r� r� r� �sumr� rS r rG )r� r� �elenr$ � expect_valZ num_tv_tuples�num_default_tvZthingsr~ r~ r� �_check_generic� sV ��� � ��� ���r� c C s� |st | � d���t|�}||kr�|}t| d�r�dd� | jD �}||k r�t|| dt�tur`dS tdd� |D ��}||8 }d |� �}t d ||kr�d nd � d | � d|� d|� ���dS )rw r� r� c S s g | ]}t |�s|�qS r~ r* r� r~ r~ r� rx � r� ry r� Nc s s | ]}t |d t�tuV qdS r{ r| r� r~ r~ r� r� s � �rz r� r� r� r� r� r� r� )r� r� r� r� r� rS r� )r� r� r� r$ r� r� r~ r~ r� r� � s2 ��� ���r: c C sh zt �d�} W n ttfy& Y dS 0 | j�d�dkr<dS | j�d�}|tju pb|t u pb|tj u S d S )Nr Fr� r� r� ) r r r� r r r �f_localsr� r_ rB )�framer� r~ r~ r� �"_has_generic_or_protocol_as_origin s r� c C s< t | �turdS t| �}t|�o:t|�dko:t|d �tv S )NFr� r )r7 r r6 r� r� r� �_TYPEVARTUPLE_TYPES)r r� r~ r~ r� �_is_unpacked_typevartuple$ s ��r� �_collect_type_varsc s� |du rt j}g � t� }d}d}| D ]�}t|�r6d}ndt||�r�t|t�s�|� vr�|r�t|dt�tu}|r||rvtd��d}n|r�td|�d���� � |� t |�r�� � � fdd �|j D �� q$t|t �r$|D ]&}t|g�D ]}|� vrڈ � |� q�q�q$t � �S ) z�Collect all type variable contained in types in order of first appearance (lexicographic order). For example:: _collect_type_vars((T, List[S, T])) == (T, S) NFTr� �2Type parameter with a default follows TypeVarTuple�Type parameter �8 without a default follows type parameter with a defaultc s g | ]}|� vr|�qS r~ r~ r+ ��tvarsr~ r� rx W r� z&_collect_type_vars.<locals>.<listcomp>)r� r r� r� r� rD r� rS r� r� r� r� r� r� r� ) rm Z typevar_types�enforce_default_ordering�default_encountered�type_var_tuple_encounteredr� r� r � collectedr~ r� r� r� 1 s@ ��� c C s� g }t � }d}d}| D ]�}t|t�r&qt|t�r^|D ]&}t|g�D ]}||vrB|�|� qBq4qt|d�r�||vr�|r�t|dt�tu}|r�|r�t d��|r�d}n|r�t d|�d���|�|� qt |�r�d}t|dd �D ]}||vr�|�|� q�qt|�S ) z�Collect all type variables and parameter specifications in args in order of first appearance (lexicographic order). For example:: assert _collect_parameters((T, Callable[P, T])) == (T, P) FZ__typing_subst__r� r� Tr� r� r� r~ ) r� r� r� r� �_collect_parametersr� r� r� rS r� r� ) r� r� r� r� r� r� r r� r� r~ r~ r� r� c s< � r� c C s@ dd� |D �}dd� |D �}t j| |||d�}| |_|j_|S )Nc S s g | ] \}}|�qS r~ r~ �r� rx r� r~ r~ r� rx � r� z!_make_nmtuple.<locals>.<listcomp>c S s& i | ] \}}|t �|d |� d���qS )zfield z annotation must be a typer� r� r~ r~ r� r| � s �z!_make_nmtuple.<locals>.<dictcomp>�r� rg )r> � namedtupler r� )r� rm rg r� r� r �nm_tplr~ r~ r� � _make_nmtuple� s ��r� > r� r� r c @ s e Zd Zdd� ZdS )�_NamedTupleMetac s0 t |v s J �|D ] }|t ur|tjurtd��qtdd� |D ��}d� v rT� d }nd� v rj� d d�}ni }g }|D ]L}|� v r�|�|� qv|rvtd|� dt|�dkr�d nd � d d �|�� ���qvt||� � � fd d�|D �� d d�}||_ tj|v �r*t td��rt tj �|_ntjjj} t | �|_� � � D ]�\} } | tv �rRtd| ��n�| tv�r2| |jv�rxt|| � | � zt| �j} W n t�y� Y nz0 z| | || � W nf t�y } zLdt| �j�d| �d|��}tjdk�r�| �|� � n t |�| �W Y d } ~ n d } ~ 0 0 �q2tj|v �r,|� � |S )Nz3can only inherit from a NamedTuple type and Genericc s s | ]}|t u rtn|V qd S r� )� _NamedTupler� )r� r r~ r~ r� r� � r� z*_NamedTupleMeta.__new__.<locals>.<genexpr>r rq r� z Non-default namedtuple field z cannot follow default field�sr r~ r c s g | ] }� | �qS r~ r~ r, �r� r~ r� rx � r� z+_NamedTupleMeta.__new__.<locals>.<listcomp>r� r� �_generic_class_getitemz&Cannot overwrite NamedTuple attribute z Error calling __set_name__ on z instance z in rK ) r� r� r_ r� r� r� r� r r� r� rC r� rp r� �__class_getitem__r� � _prohibited_namedtuple_fieldsr� �_special_namedtuple_fields�_fieldsr� r� � __set_name__� BaseExceptionr� r rG Zadd_note� RuntimeErrorrA )r� r� r- r� r rm � default_names� field_namer� Z class_getitem�keyr� �set_namerJ r� r~ r� r� r� � sv � �� � ��� $ z_NamedTupleMeta.__new__N)r� r� r� r� r~ r~ r~ r� r� � s r� r c C s t | v s J �tfS r� )r r� )r- r~ r~ r� �_namedtuple_mro_entries� s r� c K s� |t u r:|rd}d}q�d}d| � d| �d�}d| d }nF|d u rt|rPtd ��q�d }d| � d| �d�}d| d }n |r�td ��|t u s�|d u r�tj|j|d d�tdd� |�� }t| |t� d�}t f|_ |S )ao Typed version of namedtuple. Usage:: class Employee(NamedTuple): name: str id: int This is equivalent to:: Employee = collections.namedtuple('Employee', ['name', 'id']) The resulting class has an extra __annotations__ attribute, giving a dict that maps field names to types. (The field names are also in the _fields attribute, which is part of the namedtuple API.) An alternative equivalent functional syntax is also accepted:: Employee = NamedTuple('Employee', [('name', str), ('id', int)]) z3Creating NamedTuple classes using keyword argumentszq{name} is deprecated and will be disallowed in Python {remove}. Use the class-based or functional syntax instead.r� r� z = NamedTuple(z, [])`z�{name} is deprecated and will be disallowed in Python {remove}. To create a NamedTuple class with 0 fields using the functional syntax, pass an empty list, e.g. r2 Nz\Cannot pass `None` as the 'fields' parameter and also specify fields using keyword argumentsr� zIEither list of fields or keywords can be provided to NamedTuple, not bothz3.15)r� r� r r� ru ) r� r� r� r� r� r� r� r� r r ro )r� r� r� r� r� r� �ntr~ r~ r� r � sH ������ �c @ s e Zd ZdZdS )r a� Base class for classes that implement the buffer protocol. The buffer protocol allows Python objects to expose a low-level memory buffer interface. Before Python 3.12, it is not possible to implement the buffer protocol in pure Python code, or even to check whether a class implements the buffer protocol. In Python 3.12 and higher, the ``__buffer__`` method allows access to the buffer protocol from Python code, and the ``collections.abc.Buffer`` ABC allows checking whether a class implements the buffer protocol. To indicate support for the buffer protocol in earlier versions, inherit from this ABC, either in a stub file or at runtime, or use ABC registration. This ABC provides no methods, because there is no Python-accessible methods shared by pre-3.12 buffer classes. It is useful primarily for static checks. N)r� r� r� r� r~ r~ r~ r� r E s r8 c C s@ z| j �d| j�W S ty: tdt| �j���d�Y n0 dS )a Return the class's "original" bases prior to modification by `__mro_entries__`. Examples:: from typing import TypeVar, Generic from typing_extensions import NamedTuple, TypedDict T = TypeVar("T") class Foo(Generic[T]): ... class Bar(Foo[int], float): ... class Baz(list[str]): ... Eggs = NamedTuple("Eggs", [("a", int), ("b", str)]) Spam = TypedDict("Spam", {"a": int, "b": str}) assert get_original_bases(Bar) == (Foo[int], float) assert get_original_bases(Baz) == (list[str],) assert get_original_bases(Eggs) == (NamedTuple,) assert get_original_bases(Spam) == (TypedDict,) assert get_original_bases(int) == (object,) ro z"Expected an instance of type, not N)r r rC r� r� r� r� r< r~ r~ r� r8 c s ��c @ sR e Zd ZdZdd� Zdd� Zdd� Zdd � Zd d � Ze j d krNd d� Z dd� Z dS )r? aL NewType creates simple unique types with almost zero runtime overhead. NewType(name, tp) is considered a subtype of tp by static type checkers. At runtime, NewType(name, tp) returns a dummy callable that simply returns its argument. Usage:: UserId = NewType('UserId', int) def name_by_id(user_id: UserId) -> str: ... UserId('user') # Fails type check name_by_id(42) # Fails type check name_by_id(UserId(42)) # OK num = UserId(5) + 1 # type: int c C s |S r� r~ r� r~ r~ r� r� � s zNewType.__call__c C s@ || _ d|v r |�d�d }|| _|| _t� }|dkr<|| _d S )Nr2 r r )r� � rpartitionr� � __supertype__r r� )r� r� ry r� r~ r~ r� r� � s zNewType.__init__c s | j � G � fdd�d�}|fS )Nc s e Zd Z� fdd�ZdS )z&NewType.__mro_entries__.<locals>.Dummyc s& | j }td|� d|�d� � d���d S )NzGCannot subclass an instance of NewType. Perhaps you were looking for: `z = NewType(r z)`)r� r� )r� Z subcls_name�Z supercls_namer~ r� rA � s ����z8NewType.__mro_entries__.<locals>.Dummy.__init_subclass__N)r� r� r� rA r~ r� r~ r� �Dummy� s r� r )r� r- r� r~ r� r� r� � s zNewType.__mro_entries__c C s | j � d| j� �S )Nr2 )r� r� r r~ r~ r� r� � s zNewType.__repr__c C s | j S r� )r� r r~ r~ r� rc � s zNewType.__reduce__r� c C s t j| |f S r� r= r� r~ r~ r� r> � s zNewType.__or__c C s t j|| f S r� r= r� r~ r~ r� r? � s zNewType.__ror__N) r� r� r� r� r� r� r� r� rc r rG r> r? r~ r~ r~ r� r? � s r? c C s" | du p t | ttjtjtjtf�S �z:Corresponds to is_unionable() in unionobject.c in CPython.N)r� r� r� r� r� r� rI rA r~ r~ r� � _is_unionable� s �r� c C s | du p t | ttjtjtf�S r� )r� r� r� r� r� rI rA r~ r~ r� r� � s �> r� r� r� rE � __reduce_ex__r� r� r� r r� rc rC c @ s e Zd Zdd� ZdS )�_TypeAliasGenericAliasc C s |t v rt�| |�S t| j|�S r� )� _ATTRIBUTE_DELEGATION_EXCLUSIONSr� r: r� r� )r� r� r~ r~ r� r: � s z"_TypeAliasGenericAlias.__getattr__N)r� r� r� r: r~ r~ r~ r� r� � s r� c s� e Zd ZdZdd�ed�dd�Zeedd�� fd d � Zeed �d d �Z eed �dd�Z ed�dd�Z e j dk rxd&dd�Zdd� Zdd� Zdd � Zd d � Zd d � Ze j d!kr�d"d#� Zd$d%� Z� ZS )'rI a� Create named, parameterized type aliases. This provides a backport of the new `type` statement in Python 3.12: type ListOrSet[T] = list[T] | set[T] is equivalent to: T = TypeVar("T") ListOrSet = TypeAliasType("ListOrSet", list[T] | set[T], type_params=(T,)) The name ListOrSet can then be used as an alias for the type it refers to. The type_params argument should contain all the type parameters used in the value of the type alias. If the alias is not generic, this argument is omitted. Static type checkers should only support type aliases declared using TypeAliasType that follow these rules: - The first argument (the name) must be a string literal. - The TypeAliasType instance must be immediately assigned to a variable of the same name. (For example, 'X = TypeAliasType("Y", int)' is invalid, as is 'X, Y = TypeAliasType("X", int), TypeAliasType("Y", int)'). r~ )� type_paramsr� c C s� t |t�std��t |t�s$td��|| _|| _d}g }|D ]z}t |tttf�rXt |�rftd|����t |dt �t u}|r�|s�td|�d���|r�d}t |t�r�|� |� q<|� |� q<t|�| _t� }|d kr�|| _|| _d S ) Nz#TypeAliasType name must be a stringztype_params must be a tupleFzExpected a type param, got r� z non-default type parameter 'z ' follows default type parameterTr )r� r� r� r� � __value__�__type_params__r r r r! r� rS r� r� r� r r� r� ) r� r� r^ r� Zdefault_value_encounteredr� r� r� r� r~ r~ r� r� s8 ��� zTypeAliasType.__init__N)r� r^ r; c s& t | d�r| �|� t� �||� d S )Nr� )r� �_raise_attribute_errorr� r� )r� r� r^ r� r~ r� r� 6 s zTypeAliasType.__setattr__)r� r; c C s | � |� d S r� )r� �r� r� r~ r~ r� � __delattr__; s zTypeAliasType.__delattr__c C s@ |dkrt d��n*|dv r,t d|� d���nt d|� d���d S )Nr� zreadonly attribute> r� r� r� r� z attribute 'z3' of 'typing.TypeAliasType' objects is not writablez0'typing.TypeAliasType' object has no attribute '�')r� r� r~ r~ r� r� > s � �z$TypeAliasType._raise_attribute_errorr: c C s | j S r� r r r~ r~ r� r� L s zTypeAliasType.__repr__r� r c sT |du r dS |d u rd S t |t�r>� dkr>� �fdd�|D �S t�|d�j� d��S )N.r c s g | ]}�� |� d ��qS )r� ��_check_single_paramr �� recursionr� r~ r� rx X s �z5TypeAliasType._check_single_param.<locals>.<listcomp>� Subscripting � requires a type.)r� r� r� r� r� )r� r" r� r~ r� r� r� P s ��z!TypeAliasType._check_single_paramc s6 t jdk r t� fdd�|D ��S t� fdd�|D ��S )Nr� c 3 s | ]}� � |�V qd S r� r� �r� r4 r r~ r� r� ` s �z2TypeAliasType._check_parameters.<locals>.<genexpr>c 3 s$ | ] }t �|d � j� d��V qdS )r� r� N)r� r� r� r� r r~ r� r� d s ��)r rG r� r� r~ r r� �_check_parameters^ s � �z TypeAliasType._check_parametersc C sd | j std��t|t�s |f}tjdkr4t�| |�S t|�}| � |�}t | |�}|j |kr`||_ |S )Nz+Only generic type aliases are subscriptabler� ) r� r� r� r� r rG r� r� r� r� r� r� )r� r� Z type_varsr� r~ r~ r� r� j s zTypeAliasType.__getitem__c C s | j S r� r r r~ r~ r� rc { s zTypeAliasType.__reduce__c O s t d��d S )NzEtype 'typing_extensions.TypeAliasType' is not an acceptable base typer� r� r~ r~ r� rA ~ s �z TypeAliasType.__init_subclass__c C s t d��d S )NzType alias is not callabler� r r~ r~ r� r� � s zTypeAliasType.__call__r� c C s t |�s tS tj| |f S r� �r� r� r� ru )r� rJ r~ r~ r� r> � s zTypeAliasType.__or__c C s t |�s tS tj|| f S r� r� )r� rI r~ r~ r� r? � s zTypeAliasType.__ror__)r )r� r� r� r� r� r� r� r� rN r� r� r� r rG r� r� r� rc rA r� r> r? r� r~ r~ r� r� rI � s % rI r< )ry r; c C s( t | t�o&t| dd�o&| tuo&| tjuS )aZ Return True if the given type is a Protocol. Example:: >>> from typing_extensions import Protocol, is_protocol >>> class P(Protocol): ... def a(self) -> str: ... ... b: int >>> is_protocol(P) True >>> is_protocol(int) False r# F)r� r� r� rB r� r� r~ r~ r� r< � s ���c C s6 t | �st| �d���t| d�r*t| j�S tt| ��S )a� Return the set of members defined in a Protocol. Example:: >>> from typing_extensions import Protocol, get_protocol_members >>> class P(Protocol): ... def a(self) -> str: ... ... b: int >>> get_protocol_members(P) frozenset({'a', 'b'}) Raise a TypeError for arguments that are not Protocols. z is not a Protocolr )r< r� r� r� r r r� r~ r~ r� r9 � s r9 r0 c @ sL e Zd ZdZedd�dd�Zed�dd�Zed�d d �Ze e d �d d �Z dS )r0 af Define the documentation of a type annotation using ``Annotated``, to be used in class attributes, function and method parameters, return values, and variables. The value should be a positional-only string literal to allow static tools like editors and documentation generators to use it. This complements docstrings. The string value passed is available in the attribute ``documentation``. Example:: >>> from typing_extensions import Annotated, Doc >>> def hi(to: Annotated[str, Doc("Who to say hi to")]) -> None: ... N)� documentationr; c C s || _ d S r� �r� )r� r� r~ r~ r� r� � s z Doc.__init__r: c C s d| j �d�S )NzDoc(�)r� r r~ r~ r� r� � s z Doc.__repr__c C s t | j�S r� )r� r� r r~ r~ r� r� � s z Doc.__hash__)r� r; c C s t |t�stS | j|jkS r� )r� r0 r� r� r� r~ r~ r� r� � s z Doc.__eq__) r� r� r� r� r� r� r� r= r� r� r� r� r~ r~ r~ r� r0 � s � CapsuleType�CAPI)r4 r5 c @ s e Zd ZdZdZdZdZdS )r4 r� r r r� N)r� r� r� r� �VALUE_WITH_FAKE_GLOBALSr� r� r~ r~ r~ r� r4 � s r4 )rb �locals�eval_strr� c sN t |�}|t ju rtd��|r0|t jur0td��t| t�r�t| dd�}|rrt|d�rr|�dd�}t|t j �rvd}nd}d}t| dd�}|r�t j �|d�} | r�t| dd�}t t| ��} | } n�t| t j�r�t| dd�}| j}d} d} nZt| ��rt| dd�}t| dd�}d} | } n.t| d��r.| j}d } } } nt| �d ���|du �rJi S t|t ��sdt| �d ���|�sni S |�s�|t ju �r�d d � |�� D �S t |�S | du�r�t| d ��r�| j} �q�t| tj��r�| j} �q��qڐq�t| d��r�| j}� du �r�|� �du �r| �p i �t| df � } �r2dd � | D ��B �� �fdd �|�� D �} | S )a Compute the annotations dict for an object. obj may be a callable, class, or module. Passing in an object of any other type raises TypeError. Returns a dict. get_annotations() returns a new dict every time it's called; calling it twice on the same object will return two different but equivalent dicts. This is a backport of `inspect.get_annotations`, which has been in the standard library since Python 3.10. See the standard library documentation for more: https://docs.python.org/3/library/inspect.html#inspect.get_annotations This backport adds the *format* argument introduced by PEP 649. The three formats supported are: * VALUE: the annotations are returned as-is. This is the default and it is compatible with the behavior on previous Python versions. * FORWARDREF: return annotations as-is if possible, but replace any undefined names with ForwardRef objects. The implementation proposed by PEP 649 relies on language changes that cannot be backported; the typing-extensions implementation simply returns the same result as VALUE. * STRING: return annotations as strings, in a format close to the original source. Again, this behavior cannot be replicated directly in a backport. As an approximation, typing-extensions retrieves the annotations under VALUE semantics and then stringifies them. The purpose of this backport is to allow users who would like to use FORWARDREF or STRING semantics once PEP 649 is implemented, but who also want to support earlier Python versions, to simply write: typing_extensions.get_annotations(obj, format=Format.FORWARDREF) z;The VALUE_WITH_FAKE_GLOBALS format is for internal use onlyz8eval_str=True is only supported with format=Format.VALUEr Nr r r� r� z% is not a module, class, or callable.z+.__annotations__ is neither a dict nor Nonec S s* i | ]"\}}|t |t�r |nt�|��qS r~ )r� r� r� r �r� r� r^ r~ r~ r� r| ` s �z#get_annotations.<locals>.<dictcomp>r� r� c S s i | ] }|j |�qS r~ r )r� r" r~ r~ r� r| { r� c s, i | ]$\}}|t |t�s |n t|� ���qS r~ )r� r� �evalr� �rb r� r~ r� r| } s �)r4 r� r r� r� r� r� r� r r� �GetSetDescriptorTyper �modulesr� �varsr� r rH r r� r� r� r� r �partialr� r� )r� rb r� r� r� Zobj_dict�annZ obj_globals� module_namerg Z obj_locals�unwrapr� Z return_valuer~ r� r� r5 s� % � � �r5 r1 �rs rb r� r� c C sN | j r | jS t| dd �d urLz | jj}W n ty: Y n0 d| _ || _|S |d u r`t| dd �}|d u r�t| dd �d ur�ttj�| j d �dd �}|d u r�t| dd �}|d u �rt |t �r�t|dd �}|r�tj�|d �}|r�t|dd �}n2t |t j ��rt|dd �}nt|��rt|dd �}|d u �r(i }|d u �rPi }t |t ��rP|�t|�� |d u �rp|d u�rpt|dd �}|d u�r�t|�}t|�}|D ]8}|j} t�r�| j�r�| |v�r�||| < |�| d � �q�| j} | �� �r,t�| ��s,| |v �r�|| }n2| |v �r || }n tt| ��r"tt| �S t | ��n| j } t | ||�}d| _ || _|S ) N�__cell__TZ __owner__�__forward_module__r r� r� r� ) �__forward_evaluated__�__forward_value__r� r� � cell_contentsr r r� r r� r� r� r� r� rH r� r� r� r� �_FORWARD_REF_HAS_CLASSr| r� �__forward_arg__� isidentifier�keyword� iskeywordr� �builtins� NameError�__forward_code__r� ) � forward_refrs rb r� r� r^ r� rg r" � param_namer' �coder~ r~ r� �_eval_with_owner� s� ��� ��� r� )rs rb r� r� r� �_recursive_guardc C s$ |t jkr| jS | j|v r | S zt| ||||d�}W n& tyZ |t jkrT| Y S � Y n0 t|t�rnt|�}t|t�r�t |dd�dur�d}t |||||||d�S t j dk r�|r�|r�t |�ni }|D ]}|j|vr�|||j< q�t j dk �rtj||||| jhB d�S tj|||||| jhB d�S dS )a� Evaluate a forward reference as a type hint. This is similar to calling the ForwardRef.evaluate() method, but unlike that method, evaluate_forward_ref() also: * Recursively evaluates forward references nested within the type hint. * Rejects certain objects that are not valid type hints. * Replaces type hints that evaluate to None with types.NoneType. * Supports the *FORWARDREF* and *STRING* formats. *forward_ref* must be an instance of ForwardRef. *owner*, if given, should be the object that holds the annotations that the forward reference derived from, such as a module, class object, or function. It is used to infer the namespaces to use for looking up names. *globals* and *locals* can also be explicitly given to provide the global and local namespaces. *type_params* is a tuple of type parameters that are in scope when evaluating the forward reference. This parameter must be provided (though it may be an empty tuple) if *owner* is not given and the forward reference does not already have an owner set. *format* specifies the format of the annotation and is a member of the annotationlib.Format enum. r� r� TN)rb r� r� rs r� r� )r rE � )�recursive_guard)r4 r� r� r� r� r� r� r� r\ r� r1 r rG r� r� r� r� ) r� rs rb r� r� r� r� r^ Ztvarr~ r~ r� r1 � s^ � � � �c @ sd e Zd ZdZdeeje d�dd�Zdd� Ze j dk r>d d � Z e j d krXd d � Z dd� Z dd� ZdS )rC z�Create a unique sentinel object. *name* should be the name of the variable to which the return value shall be assigned. *repr*, if supplied, will be used for the repr of the sentinel object. If not provided, "<name>" will be used. N)r� rW c C s$ || _ |d ur|n d|� d�| _d S )N�<�>)r� �_repr)r� r� rW r~ r~ r� r� A s zSentinel.__init__c C s | j S r� )r� r r~ r~ r� r� I s zSentinel.__repr__r� c O s t t| �j�d���d S )Nz object is not callable�r� r� r� r$ r~ r~ r� r� O s zSentinel.__call__r� c C s t j| |f S r� r= r� r~ r~ r� r> S s zSentinel.__or__c C s t j|| f S r� r= r� r~ r~ r� r? V s zSentinel.__ror__c C s t dt| �j�d���d S )NzCannot pickle z objectr� r r~ r~ r� � __getstate__Y s zSentinel.__getstate__)N)r� r� r� r� r� r� rm r� r� r rG r� r> r? r� r~ r~ r~ r� rC 8 s �� rC )#rU rV rW rX rY rZ r[ r] r` ra rb rc rd re rf rg rh ri rj rk rl rm rn ro rp rq rr rs rt ru rv rw rx ry r� c C s" i | ]}t t|�r|tt|��qS r~ )r� r� r� )r� r� r~ r~ r� r| � r� r| )r� r )r )NNF)NN)N)N)r~ )�r r� r> �collections.abcr �enumr r6 �ior� r� r rm r� r� r� rG r� �__all__ZPEP_560r� Z GenericMetaZ_PEP_696_IMPLEMENTEDr\ rD r� r} r� r� rO r r� r� r� r� r� r r� r r6 r� r r3 r; r> r� r� r� r� r� r� r� r@ r2 r- � defaultdictr� r� r� r r r r r r r r r r rG rM r r r r^ r� r� r� r rm r� r r* r� �EXCLUDED_ATTRIBUTESr r r rB r" r% r( r) rp r4 r_ rF rE r& r$ r# r" r% r! r' r( r) Z_NEEDS_SINGLETONMETAr\ rS r_ rT re Z_PEP_728_IMPLEMENTEDr rj r= � signaturer� r� r� ri r� r� r� r� r� r, r: r� r� r� r7 r6 rH r� r� r� r� r r r� r r� r r r- r/ r r0 r rK rL rJ r5 �_Finalr r rN rQ rR rP rC r r! rB rD r r rD rT r+ r. rt ru rX rA r` r/ ra r� r� r� r� r� r� r� r� r r� � _prohibitedr� r� r� r� r� r� r �ABC�register� memoryview� bytearrayrS r8 r? rI r� r� r� r< r9 r] r� r0 Z _CapsuleType�_socket� ImportErrorZ_CAPIr� r� r4 r5 �IntEnumr� r1 r� rC Z _typing_namesrb r� r* r~ r~ r~ r� �<module> s@ �( (� � � � � d 5 � (= > ) 6 ' 1f v 0 * + * >N � ��� V % 7" 08 F A < " � �[�Y( '� sqlalchemy/future/__pycache__/engine.cpython-39.pyc 0000644 00000000553 15125143220 0016324 0 ustar 00 a ��Jh� � @ s, d Z ddlmZ ddlmZ ddlmZ dS )zH2.0 API features. this module is legacy as 2.0 APIs are now standard. � )� Connection)� create_engine)�EngineN)�__doc__Zenginer r r � r r �M/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/future/engine.py�<module> s sqlalchemy/future/__pycache__/__init__.cpython-39.pyc 0000644 00000000655 15125143220 0016621 0 ustar 00 a ��Jh � @ s8 d Z ddlmZ ddlmZ ddlmZ ddlmZ dS )zH2.0 API features. this module is legacy as 2.0 APIs are now standard. � )� Connection)� create_engine)�Engine� )�selectN)�__doc__Zenginer r r Z sql._selectable_constructorsr � r r �O/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/future/__init__.py�<module> s sqlalchemy/future/engine.py 0000755 00000000757 15125143220 0012046 0 ustar 00 # future/engine.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """2.0 API features. this module is legacy as 2.0 APIs are now standard. """ from ..engine import Connection as Connection # noqa: F401 from ..engine import create_engine as create_engine # noqa: F401 from ..engine import Engine as Engine # noqa: F401 sqlalchemy/future/__init__.py 0000755 00000001000 15125143220 0012316 0 ustar 00 # future/__init__.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """2.0 API features. this module is legacy as 2.0 APIs are now standard. """ from .engine import Connection as Connection from .engine import create_engine as create_engine from .engine import Engine as Engine from ..sql._selectable_constructors import select as select sqlalchemy/types.py 0000755 00000006140 15125143220 0010423 0 ustar 00 # types.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """Compatibility namespace for sqlalchemy.sql.types. """ from __future__ import annotations from .sql.sqltypes import _Binary as _Binary from .sql.sqltypes import ARRAY as ARRAY from .sql.sqltypes import BIGINT as BIGINT from .sql.sqltypes import BigInteger as BigInteger from .sql.sqltypes import BINARY as BINARY from .sql.sqltypes import BLOB as BLOB from .sql.sqltypes import BOOLEAN as BOOLEAN from .sql.sqltypes import Boolean as Boolean from .sql.sqltypes import CHAR as CHAR from .sql.sqltypes import CLOB as CLOB from .sql.sqltypes import Concatenable as Concatenable from .sql.sqltypes import DATE as DATE from .sql.sqltypes import Date as Date from .sql.sqltypes import DATETIME as DATETIME from .sql.sqltypes import DateTime as DateTime from .sql.sqltypes import DECIMAL as DECIMAL from .sql.sqltypes import DOUBLE as DOUBLE from .sql.sqltypes import Double as Double from .sql.sqltypes import DOUBLE_PRECISION as DOUBLE_PRECISION from .sql.sqltypes import Enum as Enum from .sql.sqltypes import FLOAT as FLOAT from .sql.sqltypes import Float as Float from .sql.sqltypes import Indexable as Indexable from .sql.sqltypes import INT as INT from .sql.sqltypes import INTEGER as INTEGER from .sql.sqltypes import Integer as Integer from .sql.sqltypes import Interval as Interval from .sql.sqltypes import JSON as JSON from .sql.sqltypes import LargeBinary as LargeBinary from .sql.sqltypes import MatchType as MatchType from .sql.sqltypes import NCHAR as NCHAR from .sql.sqltypes import NULLTYPE as NULLTYPE from .sql.sqltypes import NullType as NullType from .sql.sqltypes import NUMERIC as NUMERIC from .sql.sqltypes import Numeric as Numeric from .sql.sqltypes import NVARCHAR as NVARCHAR from .sql.sqltypes import PickleType as PickleType from .sql.sqltypes import REAL as REAL from .sql.sqltypes import SchemaType as SchemaType from .sql.sqltypes import SMALLINT as SMALLINT from .sql.sqltypes import SmallInteger as SmallInteger from .sql.sqltypes import String as String from .sql.sqltypes import STRINGTYPE as STRINGTYPE from .sql.sqltypes import TEXT as TEXT from .sql.sqltypes import Text as Text from .sql.sqltypes import TIME as TIME from .sql.sqltypes import Time as Time from .sql.sqltypes import TIMESTAMP as TIMESTAMP from .sql.sqltypes import TupleType as TupleType from .sql.sqltypes import Unicode as Unicode from .sql.sqltypes import UnicodeText as UnicodeText from .sql.sqltypes import UUID as UUID from .sql.sqltypes import Uuid as Uuid from .sql.sqltypes import VARBINARY as VARBINARY from .sql.sqltypes import VARCHAR as VARCHAR from .sql.type_api import adapt_type as adapt_type from .sql.type_api import ExternalType as ExternalType from .sql.type_api import to_instance as to_instance from .sql.type_api import TypeDecorator as TypeDecorator from .sql.type_api import TypeEngine as TypeEngine from .sql.type_api import UserDefinedType as UserDefinedType from .sql.type_api import Variant as Variant sqlalchemy/__pycache__/schema.cpython-39.pyc 0000644 00000004353 15125143220 0015007 0 ustar 00 a ��Jh� � @ s� d Z ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z dd lm Z dd lm Z dd lm Z dd lm Z dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z dd lm Z dd lm Z dd lm Z dd l m!Z! dd l"m#Z# dd!l"m$Z$ dd"l"m%Z% dd#l"m&Z& dd$l"m'Z' dd%l"m(Z( dd&l"m)Z) dd'l"m*Z* dd(l"m+Z+ dd)l"m,Z, dd*l"m-Z- dd+l"m.Z. dd,l"m/Z/ dd-l"m0Z0 dd.l"m1Z1 dd/l"m2Z2 dd0l"m3Z3 dd1l"m4Z4 dd2l"m5Z5 dd3l"m6Z6 dd4l"m7Z7 dd5l"m8Z8 dd6l"m9Z9 dd7l"m:Z: dd8l"m;Z; dd9l"m<Z< d:S );z@Compatibility namespace for sqlalchemy.sql.schema and related. � )� annotations� )� SchemaVisitor)�_CreateDropBase)� _DropView)� AddConstraint)�BaseDDLElement)� CreateColumn)� CreateIndex)� CreateSchema)�CreateSequence)� CreateTable)�DDL)� DDLElement)�DropColumnComment)�DropConstraint)�DropConstraintComment)� DropIndex)� DropSchema)� DropSequence)� DropTable)�DropTableComment)�ExecutableDDLElement)� InvokeDDLBase)�SetColumnComment)�SetConstraintComment)�SetTableComment)� sort_tables)�sort_tables_and_constraints)�conv)�_get_table_key)� BLANK_SCHEMA)�CheckConstraint)�Column)�ColumnCollectionConstraint)�ColumnCollectionMixin)� ColumnDefault)�Computed)� Constraint)� DefaultClause)�DefaultGenerator)� FetchedValue)� ForeignKey)�ForeignKeyConstraint)�HasConditionalDDL)�Identity)�Index)�insert_sentinel)�MetaData)�PrimaryKeyConstraint)� SchemaConst)� SchemaItem)�SchemaVisitable)�Sequence)�Table)�UniqueConstraintN)=�__doc__� __future__r Zsql.baser Zsql.ddlr r r r r r r r r r r r r r r r r r r r r r r r r r Z sql.namingr Z sql.schemar r! r" r# r$ r% r& r' r( r) r* r+ r, r- r. r/ r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 � r< r< �F/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/schema.py�<module> sn sqlalchemy/__pycache__/inspection.cpython-39.pyc 0000644 00000013204 15125143220 0015715 0 ustar 00 a ��Jh� � @ s� U d Z ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z dd lm Z dd lm Z dd lm Z d d l mZ d dlmZ d dlmZ e ded�Ze dedd�Ze dedef d�Ze ded�Zi Zded< G dd� dee �ZG d d � d ee �ZG d d � d ee �Ze d9d d!dd"�d#d$��Ze d:d%d!dd"�d&d$��Ze d;d'd!dd"�d(d$��Ze d<d)d*d+d"�d,d$��Ze d=d)d!d)d"�d-d$��Zd>d)d!d)d"�d.d$�Zd/d0d1�d2d3�Z e d4d/d�Z d4d4d5�d6d7�Z d8S )?a7 The inspection module provides the :func:`_sa.inspect` function, which delivers runtime information about a wide variety of SQLAlchemy objects, both within the Core as well as the ORM. The :func:`_sa.inspect` function is the entry point to SQLAlchemy's public API for viewing the configuration and construction of in-memory objects. Depending on the type of object passed to :func:`_sa.inspect`, the return value will either be a related object which provides a known interface, or in many cases it will return the object itself. The rationale for :func:`_sa.inspect` is twofold. One is that it replaces the need to be aware of a large variety of "information getting" functions in SQLAlchemy, such as :meth:`_reflection.Inspector.from_engine` (deprecated in 1.4), :func:`.orm.attributes.instance_state`, :func:`_orm.class_mapper`, and others. The other is that the return value of :func:`_sa.inspect` is guaranteed to obey a documented API, thus allowing third party tools which build on top of SQLAlchemy configurations to be constructed in a forwards-compatible way. � )� annotations)�Any)�Callable)�Dict)�Generic)�Optional)�overload)�Type)�TypeVar)�Union� )�exc)�Literal)�Protocol�_T)�bound�_TCovT)r � covariant�_F.�_INz6Dict[type, Union[Literal[True], Callable[[Any], Any]]]� _registrarsc @ s e Zd ZdZdZdS )� Inspectablea8 define a class as inspectable. This allows typing to set up a linkage between an object that can be inspected and the type of inspection it returns. Unfortunately we cannot at the moment get all classes that are returned by inspection to suit this interface as we get into MRO issues. � N)�__name__� __module__� __qualname__�__doc__� __slots__r r r �J/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/inspection.pyr 8 s r c @ s e Zd ZdZdd�dd�ZdS )�_InspectableTypeProtocolzla protocol defining a method that's used when a type (ie the class itself) is passed to inspect(). r ��returnc C s d S �Nr ��selfr r r �_sa_inspect_typeM � z)_InspectableTypeProtocol._sa_inspect_typeN)r r r r r% r r r r r G s r c @ s e Zd ZdZdd�dd�ZdS )�_InspectableProtocolz[a protocol defining a method that's used when an instance is passed to inspect(). r r c C s d S r" r r# r r r �_sa_inspect_instanceV r& z)_InspectableProtocol._sa_inspect_instanceN)r r r r r( r r r r r' P s r' z#Type[_InspectableTypeProtocol[_IN]]�bool)�subject�raiseerrr! c C s d S r" r �r* r+ r r r �inspectY s r- z_InspectableProtocol[_IN]c C s d S r" r r, r r r r- _ s zInspectable[_IN]c C s d S r" r r, r r r r- e s r zLiteral[False]z Optional[Any]c C s d S r" r r, r r r r- i s c C s d S r" r r, r r r r- m s c C s� t | �}|jD ]L}|tv rt�|d�}|du r2qn|du rB| S || �}|dur| S qd }}|r�|du sx|du r�t�d| ��|S )a� Produce an inspection object for the given target. The returned value in some cases may be the same object as the one given, such as if a :class:`_orm.Mapper` object is passed. In other cases, it will be an instance of the registered inspection type for the given object, such as if an :class:`_engine.Engine` is passed, an :class:`_reflection.Inspector` object is returned. :param subject: the subject to be inspected. :param raiseerr: When ``True``, if the given subject does not correspond to a known SQLAlchemy inspected type, :class:`sqlalchemy.exc.NoInspectionAvailable` is raised. If ``False``, ``None`` is returned. NTz7No inspection system is available for object of type %s)�type�__mro__r �getr ZNoInspectionAvailable)r* r+ �type_�cls�reg�retr r r r- q s& ��z Type[Any]zCallable[[_F], _F])�typesr! c s ddd�� fdd� }|S )Nr )� fn_or_clsr! c s* � D ] }|t v r td| ��| t |< q| S )N� Type %s is already registered�r �AssertionError)r6 r1 �r5 r r �decorate� s z_inspects.<locals>.decorater )r5 r; r r: r � _inspects� s r< �_TT)r2 r! c C s | t v rtd| ��dt | < | S )Nr7 Tr8 )r2 r r r �_self_inspects� s r> N)T)T)T).)T)T) r � __future__r �typingr r r r r r r r r � r Z util.typingr r r r r r r �__annotations__r r r' r- r< r= r> r r r r �<module> sJ � �) sqlalchemy/__pycache__/events.cpython-39.pyc 0000644 00000001014 15125143220 0015042 0 ustar 00 a ��Jh � @ s\ d Z ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z ddl m Z dd l m Z d S ) zCore event interfaces.� )� annotations� )�ConnectionEvents)� DialectEvents)�PoolResetState)� PoolEvents)�SchemaEventTarget)� DDLEventsN)�__doc__� __future__r Z engine.eventsr r �poolr Z pool.eventsr Zsql.baser Z sql.eventsr � r r �F/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/events.py�<module> s sqlalchemy/__pycache__/log.cpython-39.pyc 0000644 00000020165 15125143220 0014327 0 ustar 00 a ��Jh�! � @ s� U d Z ddlmZ ddlZddlZddlmZ ddlmZ ddlmZ ddlm Z ddlm Z dd lm Z dd lm Z d d l mZ d d l mZ d dlmZ er�dZer�dnd ZndZdZe ddd�Ze deed f Ze�d�Zejejkr�e�ej � ddd�dd�Z e � Z d e d < d d d �d!d"�Z!d#d#d �d$d%�Z"e ej#d&f Z$G d'd� d�Z%G d(d&� d&�Z&d/dd)dd*�d+d,�Z'G d-d.� d.�Z(dS )0a� Logging control and utilities. Control of logging for SA can be performed from the regular python logging module. The regular dotted module namespace is used, starting at 'sqlalchemy'. For class-level logging, the class name is appended. The "echo" keyword parameter, available on SQLA :class:`_engine.Engine` and :class:`_pool.Pool` objects, corresponds to a logger specific to that instance only. � )� annotationsN)�Any)�Optional)�overload)�Set)�Type)�TypeVar)�Union� )�py311)�py38)�LiteralT� F�_IT� Identified)�bound�debugZ sqlalchemyzlogging.Logger�None)�logger�returnc C s* t �tj�}|�t �d�� | �|� d S )Nz.%(asctime)s %(levelname)s %(name)s %(message)s)�logging� StreamHandler�sys�stdout� setFormatter� Formatter� addHandler)r �handler� r �C/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/log.py�_add_default_handler: s �r zSet[Type[Identified]]�_logged_classes�Type[Identified]�str)�clsr c C s t | dd �p| jd | j S )NZ_sqla_logger_namespace�.)�getattr� __module__�__name__�r$ r r r �_qual_logger_name_for_clsE s �r* z Type[_IT]c s> t �t| ��� � fdd�| _� fdd�| _� | _t�| � | S )Nc s � � tj�S �N)� isEnabledForr �DEBUG��self�r r r �<lambda>N s �z class_logger.<locals>.<lambda>c s � � tj�S r+ )r, r �INFOr. r0 r r r1 Q s �)r � getLoggerr* �_should_log_debug�_should_log_infor r! �addr) r r0 r � class_loggerL s r7 �InstanceLoggerc @ sJ e Zd ZU dZdZded< ded< ded< d d �d d �Zd d �d d�ZdS )r r Nz Optional[str]� logging_name�_IdentifiedLoggerTyper � _EchoFlagType�_echo�bool�r c C s | j �tj�S r+ )r r, r r- r. r r r r4 e s z Identified._should_log_debugc C s | j �tj�S r+ )r r, r r2 r. r r r r5 h s zIdentified._should_log_info)r( r' � __qualname__� __slots__r9 �__annotations__r4 r5 r r r r r \ s c @ s� e Zd ZU dZejejejejd�Zde d< dZ ddd�dd �Z dd d d d �d d�Z dd d d d �dd�Z dd d d d �dd�ZeZdd d d d �dd�Zdd d d d �dd�Zdd d d d �dd�Zddd d d d�dd �Zdd d �d d �Zdd!�d"d#�Zd$S )%r8 a A logger adapter (wrapper) for :class:`.Identified` subclasses. This allows multiple instances (e.g. Engine or Pool instances) to share a logger, but have its verbosity controlled on a per-instance basis. The basic functionality is to return a logging level which is based on an instance's echo setting. Default implementation is: 'debug' -> logging.DEBUG True -> logging.INFO False -> Effective level of underlying logger ( logging.WARNING by default) None -> same as False )NFTr r; r< )�echor r# )rB �namec C s8 || _ t�|�| _| j| tjkr4| jjs4t| j� d S r+ )rB r r3 r � _echo_mapr2 �handlersr )r/ rB rC r r r �__init__� s zInstanceLogger.__init__r r )�msg�args�kwargsr c O s | j tj|g|�R i |�� dS )z/Delegate a debug call to the underlying logger.N)�logr r- �r/ rG rH rI r r r r � s zInstanceLogger.debugc O s | j tj|g|�R i |�� dS )z/Delegate an info call to the underlying logger.N)rJ r r2 rK r r r �info� s zInstanceLogger.infoc O s | j tj|g|�R i |�� dS )z1Delegate a warning call to the underlying logger.N)rJ r �WARNINGrK r r r �warning� s zInstanceLogger.warningc O s | j tj|g|�R i |�� dS )zB Delegate an error call to the underlying logger. N�rJ r �ERRORrK r r r �error� s zInstanceLogger.errorc O s( d|d< | j tj|g|�R i |�� dS )z4Delegate an exception call to the underlying logger.r �exc_infoNrO rK r r r � exception� s zInstanceLogger.exceptionc O s | j tj|g|�R i |�� dS )z2Delegate a critical call to the underlying logger.N)rJ r �CRITICALrK r r r �critical� s zInstanceLogger.critical�int)�levelrG rH rI r c O sn | j jj|krdS | j| j }|tjkr2| j �� }||krjtrR|� dd�t |d< | j j |||fi |�� dS )z�Delegate a log call to the underlying logger. The level here is determined by the echo flag as well as that of the underlying logger, and logger._log() is called directly. N� stacklevelr ) r �manager�disablerD rB r �NOTSET�getEffectiveLevel� STACKLEVEL�get�STACKLEVEL_OFFSET�_log)r/ rW rG rH rI Zselected_levelr r r rJ � s �zInstanceLogger.logr= )rW r c C s | j jj|krdS || �� kS )z)Is this logger enabled for level 'level'?F)r rY rZ r\ �r/ rW r r r r, � s zInstanceLogger.isEnabledForr> c C s$ | j | j }|tjkr | j�� }|S )z+What's the effective level for this logger?)rD rB r r[ r r\ ra r r r r\ � s z InstanceLogger.getEffectiveLevelN)r( r' r? �__doc__r r[ r2 r- rD rA r@ rF r rL rN �warnrQ rS rU rJ r, r\ r r r r r8 l s& � r; )�instance�echoflagr c C sT | j r dt| j�| j f }n t| j�}|| _|dv r@t�|�}n t||�}|| _dS )zEcreate a logger for an instance that implements :class:`.Identified`.z%s.%s)FNN)r9 r* � __class__r< r r3 r8 r )rd re rC r r r r �instance_logger� s � rg c @ s` e Zd ZdZeddd d�dd��Zedddd�d d��Zd dd d�d d�Zddd d�dd�ZdS )� echo_propertya} When ``True``, enable log output for this element. This has the effect of setting the Python logging level for the namespace of this element's class and object reference. A value of boolean ``True`` indicates that the loglevel ``logging.INFO`` will be set for the logger, whereas the string value ``debug`` will set the loglevel to ``logging.DEBUG``. z Literal[None]r" )rd �ownerr c C s d S r+ r �r/ rd ri r r r �__get__ s zecho_property.__get__r r; c C s d S r+ r rj r r r rk s zOptional[Identified]z#Union[echo_property, _EchoFlagType]c C s |d u r | S |j S d S r+ )r< rj r r r rk s r )rd �valuer c C s t ||d� d S )N)re )rg )r/ rd rl r r r �__set__ s zecho_property.__set__N)r( r' r? rb r rk rm r r r r rh s rh )N))rb � __future__r r r �typingr r r r r r r �utilr r Z util.typingr r] r_ r r= r; r3 Z rootloggerrW r[ �setLevel�WARNr �setr! rA r* r7 �Loggerr: r r8 rg rh r r r r �<module> sB y � sqlalchemy/__pycache__/exc.cpython-39.pyc 0000644 00000060047 15125143220 0014330 0 ustar 00 a ��Jh�] � @ s U d Z ddlmZ ddlZddlmZ ddlmZ ddlmZ ddlmZ ddlmZ dd lm Z dd lm Z d d l m Z d d l m Z ejr�d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ ejr�ded< ndZG dd� d�ZG dd� dee�Z G dd� de �Z G dd � d e �Z G d d � d e �Z G d d � d e �Z G d!d"� d"e �Z!G d#d$� d$e �Z"G d%d&� d&e �Z#G d'd(� d(e �Z$G d)d*� d*e �Z%G d+d,� d,e%�Z&G d-d.� d.e �Z'G d/d0� d0e �Z(G d1d2� d2e(�Z)G d3d4� d4e �Z*G d5d6� d6e �Z+G d7d8� d8e+�Z,G d9d:� d:e+�Z-G d;d<� d<e+�Z.G d=d>� d>e+�Z/G d?d@� d@e+e0�Z1G dAdB� dBe+�Z2G dCdD� dDe+�Z3G dEdF� dFe+�Z4G dGdH� dHe+�Z5G dIdJ� dJe+�Z6G dKdL� dLe4�Z7G dMdN� dNe4�Z8G dOdP� dPe+�Z9G dQdR� dRe+�Z:G dSdT� dTe+�Z;G dUdV� dV�Z<G dWdX� dXe �Z=G dYdZ� dZe=�Z>G d[d\� d\e>�Z?G d]d^� d^e>�Z@G d_d`� d`e@�ZAG dadb� dbe@�ZBG dcdd� dde@�ZCG dedf� dfe@�ZDG dgdh� dhe@�ZEG didj� dje@�ZFG dkdl� dleG�ZHG dmdn� dneeI�ZJG dodp� dpeJ�ZKG dqdr� dreK�ZLG dsdt� dteK�ZMG dudv� dveN�ZOG dwdx� dxeeP�ZQdS )yz�Exceptions used with SQLAlchemy. The base exception class is :exc:`.SQLAlchemyError`. Exceptions which are raised as a result of DBAPI exceptions are all subclasses of :exc:`.DBAPIError`. � )� annotationsN)�Any)�List)�Optional)�overload)�Tuple)�Type)�Union� )�compat)� preloaded)�_AnyExecuteParams)�Dialect)�Compiled)� TypeCompiler)� ClauseElement�str�_version_tokenc sZ e Zd ZU dZdZded< ddd�� fdd� Zd Zd d �d d �Zd d �� fdd� Z � Z S )�HasDescriptionCodezDhelper which adds 'code' as an attribute and '_code_str' as a methodN� Optional[str]�coder )�arg�kwc s0 |� dd �}|d ur|| _t� j|i |�� d S )Nr )�popr �super�__init__)�selfr r r �� __class__� �C/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/exc.pyr 0 s zHasDescriptionCode.__init__�errorr ��returnc C s* | j s dS d| j� dt� d| j � d�S d S )N� z(Background on this z at: https://sqlalche.me/e/�/�))r � _what_are_wer �r r r r � _code_str8 s ���z HasDescriptionCode._code_strc s$ t � �� }| jr d|| �� f }|S �Nz%s %s)r �__str__r r) �r �messager r r r+ A s zHasDescriptionCode.__str__) �__name__� __module__� __qualname__�__doc__r �__annotations__r r' r) r+ � __classcell__r r r r r + s r c @ s: e Zd ZdZdd�dd�Zdd�dd�Zdd�dd �Zd S ) �SQLAlchemyErrorzGeneric error class.r r" c C sJ t | j�dkr<| jd }t|t�r0t�|d�}nt|�}|S t| j�S d S )Nr r zutf-8)�len�args� isinstance�bytesr Zdecode_backslashreplacer )r Zarg_text�textr r r �_messageK s zSQLAlchemyError._messagec C s" | � � }| jr d|| �� f }|S r* )r: r r) r, r r r � _sql_messagej s z SQLAlchemyError._sql_messagec C s | � � S �N)r; r( r r r r+ r s zSQLAlchemyError.__str__N)r. r/ r0 r1 r: r; r+ r r r r r4 H s r4 c @ s e Zd ZdZdS )� ArgumentErrorz�Raised when an invalid or conflicting function argument is supplied. This error generally corresponds to construction time state errors. N�r. r/ r0 r1 r r r r r= v s r= c @ s e Zd ZdZdS )�DuplicateColumnErrorz�a Column is being added to a Table that would replace another Column, without appropriate parameters to allow this in place. .. versionadded:: 2.0.0b4 Nr> r r r r r? ~ s r? c s4 e Zd ZdZdd�� fdd� Zdd�dd �Z� ZS ) �ObjectNotExecutableErrorzVRaised when an object is passed to .execute() that can't be executed as SQL. r )�targetc s t � �d| � || _d S )Nz Not an executable object: %r)r r rA )r rA r r r r � s z!ObjectNotExecutableError.__init__�Union[str, Tuple[Any, ...]]r" c C s | j | jffS r< )r rA r( r r r � __reduce__� s z#ObjectNotExecutableError.__reduce__)r. r/ r0 r1 r rC r3 r r r r r@ � s r@ c @ s e Zd ZdZdS )�NoSuchModuleErrorzpRaised when a dynamically-loaded module (usually a database dialect) of a particular name cannot be located.Nr> r r r r rD � s rD c @ s e Zd ZdZdS )�NoForeignKeysErrorzURaised when no foreign keys can be located between two selectables during a join.Nr> r r r r rE � s rE c @ s e Zd ZdZdS )�AmbiguousForeignKeysErrorzhRaised when more than one foreign key matching can be located between two selectables during a join.Nr> r r r r rF � s rF c @ s e Zd ZdZdS )� ConstraintColumnNotFoundErrorz�raised when a constraint refers to a string column name that is not present in the table being constrained. .. versionadded:: 2.0 Nr> r r r r rG � s rG c @ s6 e Zd ZdZd dddddd�dd�Zd d �d d �ZdS )�CircularDependencyErrora Raised by topological sorts when a circular dependency is detected. There are two scenarios where this error occurs: * In a Session flush operation, if two objects are mutually dependent on each other, they can not be inserted or deleted via INSERT or DELETE statements alone; an UPDATE will be needed to post-associate or pre-deassociate one of the foreign key constrained values. The ``post_update`` flag described at :ref:`post_update` can resolve this cycle. * In a :attr:`_schema.MetaData.sorted_tables` operation, two :class:`_schema.ForeignKey` or :class:`_schema.ForeignKeyConstraint` objects mutually refer to each other. Apply the ``use_alter=True`` flag to one or both, see :ref:`use_alter`. Nr r r )r- �cycles�edges�msgr c C sJ |d u r&|dd� dd� |D �� 7 }n|}tj| ||d� || _|| _d S )Nz (%s)z, c s s | ]}t |�V qd S r< )�repr)�.0�sr r r � <genexpr>� � z3CircularDependencyError.__init__.<locals>.<genexpr>�r )�joinr4 r rI rJ )r r- rI rJ rK r r r r r � s z CircularDependencyError.__init__rB r" c C s2 | j d | j| j| jd f| jd ur,d| jini fS )Nr r )r rI rJ r6 r r( r r r rC � s �z"CircularDependencyError.__reduce__)NN�r. r/ r0 r1 r rC r r r r rH � s �rH c @ s e Zd ZdZdS )� CompileErrorz2Raised when an error occurs during SQL compilationNr> r r r r rT � s rT c s> e Zd ZdZdZddddd�� fdd � Zd d �d d �Z� ZS )�UnsupportedCompilationErrorz�Raised when an operation is not supported by the given compiler. .. seealso:: :ref:`faq_sql_expression_string` :ref:`error_l7de` Zl7deNz Union[Compiled, TypeCompiler]zType[ClauseElement]r )�compiler� element_typer- c s8 t � �d|||rd| ndf � || _|| _|| _d S )Nz-Compiler %r can't render element of type %s%sz: %sr$ )r r rV rW r- )r rV rW r- r r r r � s ��z$UnsupportedCompilationError.__init__rB r" c C s | j | j| j| jffS r< )r rV rW r- r( r r r rC � s z&UnsupportedCompilationError.__reduce__)N)r. r/ r0 r1 r r rC r3 r r r r rU � s �rU c @ s e Zd ZdZdS )�IdentifierErrorz;Raised when a schema name is beyond the max character limitNr> r r r r rX � s rX c @ s e Zd ZU dZdZded< dS )�DisconnectionErrora� A disconnect is detected on a raw DB-API connection. This error is raised and consumed internally by a connection pool. It can be raised by the :meth:`_events.PoolEvents.checkout` event so that the host pool forces a retry; the exception will be caught three times in a row before the pool gives up and raises :class:`~sqlalchemy.exc.InvalidRequestError` regarding the connection attempt. F�bool�invalidate_poolN�r. r/ r0 r1 r[ r2 r r r r rY � s rY c @ s e Zd ZU dZdZded< dS )�InvalidatePoolErrora� Raised when the connection pool should invalidate all stale connections. A subclass of :class:`_exc.DisconnectionError` that indicates that the disconnect situation encountered on the connection probably means the entire pool should be invalidated, as the database has been restarted. This exception will be handled otherwise the same way as :class:`_exc.DisconnectionError`, allowing three attempts to reconnect before giving up. .. versionadded:: 1.2 TrZ r[ Nr\ r r r r r] s r] c @ s e Zd ZdZdS )� TimeoutErrorz@Raised when a connection pool times out on getting a connection.Nr> r r r r r^ s r^ c @ s e Zd ZdZdS )�InvalidRequestErrorzvSQLAlchemy was asked to do something it can't do. This error generally corresponds to runtime state errors. Nr> r r r r r_ # s r_ c @ s e Zd ZdZdS )�IllegalStateChangeErrorzrAn object that tracks state encountered an illegal state change of some kind. .. versionadded:: 2.0 Nr> r r r r r` + s r` c @ s e Zd ZdZdS )�NoInspectionAvailablezaA subject passed to :func:`sqlalchemy.inspection.inspect` produced no context for inspection.Nr> r r r r ra 4 s ra c @ s e Zd ZdZdS )�PendingRollbackErrorzlA transaction has failed and needs to be rolled back before continuing. .. versionadded:: 1.4 Nr> r r r r rb 9 s rb c @ s e Zd ZdZdS )�ResourceClosedErrorzcAn operation was requested from a connection, cursor, or other object that's in a closed state.Nr> r r r r rc B s rc c @ s e Zd ZdZdS )�NoSuchColumnErrorz1A nonexistent column is requested from a ``Row``.Nr> r r r r rd G s rd c @ s e Zd ZdZdS )� NoResultFoundz�A database result was required but none was found. .. versionchanged:: 1.4 This exception is now part of the ``sqlalchemy.exc`` module in Core, moved from the ORM. The symbol remains importable from ``sqlalchemy.orm.exc``. Nr> r r r r re K s re c @ s e Zd ZdZdS )�MultipleResultsFounda A single database result was required but more than one were found. .. versionchanged:: 1.4 This exception is now part of the ``sqlalchemy.exc`` module in Core, moved from the ORM. The symbol remains importable from ``sqlalchemy.orm.exc``. Nr> r r r r rf W s rf c @ s e Zd ZU dZded< dS )�NoReferenceErrorzDRaised by ``ForeignKey`` to indicate a reference cannot be resolved.r � table_nameN)r. r/ r0 r1 r2 r r r r rg b s rg c @ s e Zd ZdZdZdS )� AwaitRequiredzjError raised by the async greenlet spawn if no async operation was awaited when it required one. Zxd1rN�r. r/ r0 r1 r r r r r ri h s ri c @ s e Zd ZdZdZdS )�MissingGreenletzkError raised by the async greenlet await\_ if called while not inside the greenlet spawn context. Zxd2sNrj r r r r rk q s rk c @ s. e Zd ZdZddd�dd�Zdd�dd �Zd S ) �NoReferencedTableErrorzQRaised by ``ForeignKey`` when the referred ``Table`` cannot be located. r )r- �tnamec C s t �| |� || _d S r< )rg r rh )r r- rm r r r r � s z NoReferencedTableError.__init__rB r" c C s | j | jd | jffS �Nr )r r6 rh r( r r r rC � s z!NoReferencedTableError.__reduce__NrS r r r r rl z s rl c @ s0 e Zd ZdZdddd�dd�Zdd�dd �Zd S ) �NoReferencedColumnErrorzRRaised by ``ForeignKey`` when the referred ``Column`` cannot be located. r )r- rm �cnamec C s t �| |� || _|| _d S r< )rg r rh � column_name)r r- rm rp r r r r � s z NoReferencedColumnError.__init__rB r" c C s | j | jd | j| jffS rn )r r6 rh rq r( r r r rC � s �z"NoReferencedColumnError.__reduce__NrS r r r r ro � s ro c @ s e Zd ZdZdS )�NoSuchTableErrorz7Table does not exist or is not visible to a connection.Nr> r r r r rr � s rr c @ s e Zd ZdZdS )�UnreflectableTableErrorzUTable exists but can't be reflected for some reason. .. versionadded:: 1.2 Nr> r r r r rs � s rs c @ s e Zd ZdZdS )�UnboundExecutionErrorzASQL was attempted without a database connection to execute it on.Nr> r r r r rt � s rt c @ s e Zd ZdZdS )� DontWrapMixina: A mixin class which, when applied to a user-defined Exception class, will not be wrapped inside of :exc:`.StatementError` if the error is emitted within the process of executing a statement. E.g.:: from sqlalchemy.exc import DontWrapMixin class MyCustomException(Exception, DontWrapMixin): pass class MySpecialType(TypeDecorator): impl = String def process_bind_param(self, value, dialect): if value == "invalid": raise MyCustomException("invalid!") Nr> r r r r ru � s ru c @ s� e Zd ZU dZdZded< dZded< dZded< dZd ed < d Z d ed < d ddddd dd d�dd�Z ddd�dd�Z dd�dd�Z e �d�dd�dd ��ZdS ) �StatementErrorav An error occurred during execution of a SQL statement. :class:`StatementError` wraps the exception raised during execution, and features :attr:`.statement` and :attr:`.params` attributes which supply context regarding the specifics of the statement which had an issue. The wrapped exception object is available in the :attr:`.orig` attribute. Nr � statement�Optional[_AnyExecuteParams]�paramszOptional[BaseException]�orig�Optional[bool]�ismultiFrZ �connection_invalidatedr )r- rw ry rz �hide_parametersr r| c C s8 t j| ||d� || _|| _|| _|| _|| _g | _d S )NrQ )r4 r rw ry rz r| r~ �detail)r r- rw ry rz r~ r r| r r r r � s zStatementError.__init__�None)rK r# c C s | j �|� d S r< )r �append)r rK r r r � add_detail� s zStatementError.add_detailrB r" c C s8 | j | jd | j| j| j| j| j�d�| jfd| j ifS )Nr r r ) r r6 rw ry rz r~ �__dict__�getr| r r( r r r rC � s � �zStatementError.__reduce__zsqlalchemy.sql.utilc C s� t j}| �� g}| jrdd| j }|�|� | jrd| jrB|�d� n"|j| jd| jd�}|�d| � | � � }|rz|�|� d� dd� | j D �| �S ) Nz [SQL: %s]z3[SQL parameters hidden due to hide_parameters=True]� )r| z[parameters: %r]� c S s g | ] }d | �qS )z(%s)r )rM Zdetr r r � <listcomp> rP z/StatementError._sql_message.<locals>.<listcomp>) � _preloadedZsql_utilr: rw r� ry r~ Z _repr_paramsr| r) rR r )r �util�detailsZ stmt_detailZ params_reprZcode_strr r r r; s$ � � zStatementError._sql_message)FNN)r. r/ r0 r1 rw r2 ry rz r| r} r r� rC r� Zpreload_moduler; r r r r rv � s � rv c @ s� e Zd ZdZdZeed ddddd d d d d d � dd���Zeed ddddd d d d dd � dd���Zeed ddddd d d d dd � dd���Zed ddddd d d d dd � dd��Zdd�dd�Zd!dddd d dd d�dd �Z dS )"� DBAPIErrora Raised when the execution of a database operation fails. Wraps exceptions raised by the DB-API underlying the database operation. Driver-specific implementations of the standard DB-API exception types are wrapped by matching sub-types of SQLAlchemy's :class:`DBAPIError` when possible. DB-API's ``Error`` type maps to :class:`DBAPIError` in SQLAlchemy, otherwise the names are identical. Note that there is no guarantee that different DB-API implementations will raise the same exception type for any given error condition. :class:`DBAPIError` features :attr:`~.StatementError.statement` and :attr:`~.StatementError.params` attributes which supply context regarding the specifics of the statement which had an issue, for the typical case when the error was raised within the context of emitting a SQL statement. The wrapped exception object is available in the :attr:`~.StatementError.orig` attribute. Its type and properties are DB-API implementation specific. ZdbapiFNr rx � ExceptionzType[Exception]rZ zOptional[Dialect]r{ rv ) rw ry rz �dbapi_base_errr~ r} �dialectr| r# c C s d S r< r � �clsrw ry rz r� r~ r} r� r| r r r �instance4 s zDBAPIError.instanceru c C s d S r< r r� r r r r� B s � BaseExceptionc C s d S r< r r� r r r r� P s z#Union[BaseException, DontWrapMixin]c C s t |t�rt |t�r t |t�r"|S |d ur�t |t�rh|rhtd|jj|jj|j d f |||||j |d�S t ||�s�|r�td|jj|jj|f |||||d�S t � } |jj D ]>} | j} |r�|j �| | �} | | v r�t| | t�r�| | } q�q�| |||||| j |d�S )N� (%s.%s) %sr )r~ r r| )r~ r| )r} r~ r r| )r7 r� r� ru r4 rv r r/ r. r6 r �globals�__mro__Z dbapi_exception_translation_mapr� � issubclassr� ) r� rw ry rz r� r~ r} r� r| �globZsuper_�namer r r r� ^ sp ��������� ��rB r" c C s4 | j | j| j| j| j| j| j�d�| jfd| j ifS )Nr r ) r rw ry rz r~ r} r� r� r| r r( r r r rC � s � �zDBAPIError.__reduce__)rw ry rz r~ r} r r| c C st z t |�}W n0 ty< } zdt | � }W Y d } ~ n d } ~ 0 0 tj| d|jj|jj|f ||||||d� || _d S )Nz.Error in str() of DB-API-generated exception: r� )r r| )r r� rv r r r/ r. r} ) r rw ry rz r~ r} r r| r9 �er r r r � s" "�� zDBAPIError.__init__)FFNN)FFNN)FFNN)FFNN)FFNN) r. r/ r0 r1 r r � classmethodr� rC r r r r r r� sF �$ �$ �$ �"H �r� c @ s e Zd ZdZdZdS )�InterfaceErrorz Wraps a DB-API InterfaceError.Zrvf5Nrj r r r r r� � s r� c @ s e Zd ZdZdZdS )� DatabaseErrorz Wraps a DB-API DatabaseError.Z4xp6Nrj r r r r r� � s r� c @ s e Zd ZdZdZdS )� DataErrorzWraps a DB-API DataError.Z9h9hNrj r r r r r� � s r� c @ s e Zd ZdZdZdS )�OperationalErrorz Wraps a DB-API OperationalError.Ze3q8Nrj r r r r r� � s r� c @ s e Zd ZdZdZdS )�IntegrityErrorz Wraps a DB-API IntegrityError.ZgkpjNrj r r r r r� � s r� c @ s e Zd ZdZdZdS )� InternalErrorz Wraps a DB-API InternalError.Z2j85Nrj r r r r r� � s r� c @ s e Zd ZdZdZdS )�ProgrammingErrorz Wraps a DB-API ProgrammingError.Zf405Nrj r r r r r� � s r� c @ s e Zd ZdZdZdS )�NotSupportedErrorz!Wraps a DB-API NotSupportedError.Ztw8gNrj r r r r r� � s r� c @ s e Zd ZdZdS )�SATestSuiteWarningz�warning for a condition detected during tests that is non-fatal Currently outside of SAWarning so that we can work around tools like Alembic doing the wrong thing with warnings. Nr> r r r r r� s r� c @ s e Zd ZU dZdZded< dS )�SADeprecationWarningz$Issued for usage of deprecated APIs.Nr �deprecated_since�r. r/ r0 r1 r� r2 r r r r r� s r� c s4 e Zd ZU dZdZded< dd�� fdd� Z� ZS ) �Base20DeprecationWarningz�Issued for usage of APIs specifically deprecated or legacy in SQLAlchemy 2.0. .. seealso:: :ref:`error_b8d9`. :ref:`deprecation_20_mode` z1.4r r� r r" c s t � �� d S )Nz> (Background on SQLAlchemy 2.0 at: https://sqlalche.me/e/b8d9))r r+ r( r r r r+ $ s ��z Base20DeprecationWarning.__str__)r. r/ r0 r1 r� r2 r+ r3 r r r r r� s r� c @ s e Zd ZdZdS )�LegacyAPIWarningzEindicates an API that is in 'legacy' status, a long term deprecation.Nr> r r r r r� + s r� c @ s e Zd ZdZdS )�MovedIn20WarningzASubtype of RemovedIn20Warning to indicate an API that moved only.Nr> r r r r r� / s r� c @ s e Zd ZU dZdZded< dS )�SAPendingDeprecationWarningz}A similar warning as :class:`_exc.SADeprecationWarning`, this warning is not used in modern versions of SQLAlchemy. Nr r� r� r r r r r� 3 s r� c @ s e Zd ZdZdZdS )� SAWarningzIssued at runtime.�warningN)r. r/ r0 r1 r' r r r r r� = s r� )Rr1 � __future__r �typingr r r r r r r r� r r r� � TYPE_CHECKINGZengine.interfacesr r Z sql.compilerr r Z sql.elementsr r2 r r r� r4 r= r? r@ rD rE rF rG rH rT rU rX rY r] r^ r_ r` ra rb rc �KeyErrorrd re rf rg ri rk rl ro rr rs rt ru rv r� r� r� r� r� r� r� r� r� �Warningr� �DeprecationWarningr� r� r� r� �PendingDeprecationWarningr� �RuntimeWarningr� r r r r �<module> s� . + Y 8 sqlalchemy/__pycache__/__init__.cpython-39.pyc 0000644 00000021362 15125143220 0015305 0 ustar 00 a ��Jhs1 � @ s2 d dl mZ d dlmZ ddlmZ ddlmZ ddlm Z ddlm Z ddlm Z dd lm Z dd lm Z dd lmZ dd lmZ dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z ddlm Z ddlm Z dd lm Z dd lm Z dd lm!Z! dd lm"Z" dd lm#Z# dd!lm$Z$ dd"lm%Z% dd#lm&Z& dd$lm'Z' dd%lm(Z( dd&lm)Z) dd'l*m+Z+ dd(l,m-Z- dd)l,m.Z. dd*l,m/Z/ dd+l,m0Z0 dd,l,m1Z1 dd-l,m2Z2 dd.l,m3Z3 dd/l,m4Z4 dd0l,m5Z5 dd1l,m6Z6 dd2l7m8Z8 dd3l7m9Z9 dd4l7m:Z: dd5l7m;Z; dd6l7m<Z< dd7l7m=Z= dd8l7m>Z> dd9l7m?Z? dd:l7m@Z@ dd;l7mAZA dd<l7mBZB dd=l7mCZC dd>l7mDZD dd?l7mEZE dd@l7mFZF ddAl7mGZG ddBl7mHZH ddCl7mIZI ddDl7mJZJ ddEl7mKZK ddFl7mLZL ddGl7mMZM ddHlNmOZO ddIlNmPZP ddJlNmQZQ ddKlNmRZR ddLlSmTZT ddMlSmUZU ddNlSmVZV ddOlSmWZW ddPlSmXZX ddQlSmYZY ddRlSmZZZ ddSlSm[Z[ ddTlSm\Z\ ddUlSm]Z] ddVlSm^Z^ ddWlSm_Z_ ddXlSm`Z` ddYlSmaZa ddZlSmbZb dd[lSmcZc dd\lSmdZd dd]lSmeZe dd^lSmfZf dd_lSmgZg dd`lSmhZh ddalSmiZi ddblSmjZj ddclSmkZk dddlSmlZl ddelSmmZm ddflSmnZn ddglSmoZo ddhlSmpZp ddilSmqZq ddjlSmrZr ddklSmsZs ddllSmtZt ddmlSmuZu ddnlSmvZv ddolSmwZw ddplSmxZx ddqlSmyZy ddrlSmzZz ddslSm{Z{ ddtlSm|Z| ddulSm}Z} ddvlSm~Z~ ddwlSmZ ddxlSm�Z� ddylSm�Z� ddzlSm�Z� dd{lSm�Z� dd|lSm�Z� dd}lSm�Z� dd~lSm�Z� ddlSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�lSm�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�lאm �Z dd�lאm�Z dd�lאm�Z dd�lאm�Z dd�lאm�Z dd�lאm�Z dd�lאm�Z dd�lאm�Z d��Z�d �d�d��d�d��Z �e �e � � �dS ( � )� annotations)�Any� )�util)�AdaptedConnection)�BaseRow)� BindTyping)�ChunkedIteratorResult)�Compiled)� Connection)� create_engine)�create_mock_engine)�create_pool_from_url)�CreateEnginePlugin)� CursorResult)�Dialect)�Engine)�engine_from_config)�ExceptionContext)�ExecutionContext)� FrozenResult)� Inspector)�IteratorResult)�make_url)� MappingResult)� MergedResult)�NestedTransaction)�Result)� result_tuple)� ResultProxy)�RootTransaction)�Row)� RowMapping)� ScalarResult)� Transaction)�TwoPhaseTransaction)� TypeCompiler)�URL)�inspect)� AssertionPool)�AsyncAdaptedQueuePool)� FallbackAsyncAdaptedQueuePool)�NullPool)�Pool)�PoolProxiedConnection)�PoolResetState)� QueuePool)�SingletonThreadPool)� StaticPool)�BaseDDLElement)� BLANK_SCHEMA)�CheckConstraint)�Column)� ColumnDefault)�Computed)� Constraint)�DDL)� DDLElement)� DefaultClause)�ExecutableDDLElement)� FetchedValue)� ForeignKey)�ForeignKeyConstraint)�Identity)�Index)�insert_sentinel)�MetaData)�PrimaryKeyConstraint)�Sequence)�Table)�UniqueConstraint)�ColumnExpressionArgument)� NotNullable)�Nullable)�SelectLabelStyle)�Alias)�alias)�AliasedReturnsRows)�all_)�and_)�any_)�asc)�between)�BinaryExpression)� bindparam)� BindParameter)� bitwise_not)�BooleanClauseList)�CacheKey)�Case)�case)�Cast)�cast)� ClauseElement)� ClauseList)�collate)�CollectionAggregate)�column)� ColumnClause)�ColumnCollection)� ColumnElement)�ColumnOperators)�CompoundSelect)�CTE)�cte)� custom_op)�Delete)�delete)�desc)�distinct)�except_)� except_all)� Executable)�Exists)�exists)�Extract)�extract)�false)�False_)� FromClause)� FromGrouping)�func)� funcfilter)�Function)�FunctionElement)�FunctionFilter)�GenerativeSelect)�Grouping)�HasCTE)� HasPrefixes)� HasSuffixes)�Insert)�insert)� intersect)� intersect_all)�Join)�join)�Label)�label)�LABEL_STYLE_DEFAULT)� LABEL_STYLE_DISAMBIGUATE_ONLY)�LABEL_STYLE_NONE)� LABEL_STYLE_TABLENAME_PLUS_COL)� lambda_stmt)� LambdaElement)�Lateral)�lateral)�literal)�literal_column)�modifier)�not_)�Null)�null)� nulls_first)� nulls_last)� nullsfirst)� nullslast)� Operators)�or_)� outerjoin)�outparam)�Over)�over)� quoted_name)�ReleaseSavepointClause)� ReturnsRows)�RollbackToSavepointClause)�SavepointClause)� ScalarSelect)�Select)�select)� Selectable)� SelectBase)�SQLColumnExpression)�StatementLambdaElement)�Subquery)�table)� TableClause)� TableSample)� tablesample)�TableValuedAlias)�text)� TextAsFrom)� TextClause)� TextualSelect)�true)�True_)�try_cast)�TryCast)�Tuple)�tuple_)� type_coerce)� TypeClause)� TypeCoerce)�UnaryExpression)�union)� union_all)�Update)�update)� UpdateBase)�Values)�values)� ValuesBase)� Visitable)� within_group)� WithinGroup)�ARRAY)�BIGINT)� BigInteger)�BINARY)�BLOB)�BOOLEAN)�Boolean)�CHAR)�CLOB)�DATE)�Date)�DATETIME)�DateTime)�DECIMAL)�DOUBLE)�Double)�DOUBLE_PRECISION)�Enum)�FLOAT)�Float)�INT)�INTEGER)�Integer)�Interval)�JSON)� LargeBinary)�NCHAR)�NUMERIC)�Numeric)�NVARCHAR)� PickleType)�REAL)�SMALLINT)� SmallInteger)�String)�TEXT)�Text)�TIME)�Time)� TIMESTAMP)� TupleType)� TypeDecorator)�Unicode)� UnicodeText)�UUID)�Uuid)� VARBINARY)�VARCHARz2.0.41r �None)�lcls�returnc C s6 t j�d� ddlm} d�t�d�dd� �|_d S )NZ sqlalchemyr )�exc� �.r � ) �_utilZ preloadedZ import_prefixr r r� � __version__�splitZ_version_token)r r � r �H/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/__init__.py�__go s r N( � __future__r �typingr r r r Zenginer r r r r r r r r r r r r r r r r r r r r r r r r r r r! r" r# r$ r% r& r' Z inspectionr( �poolr) r* r+ r, r- r. r/ r0 r1 r2 Zschemar3 r4 r5 r6 r7 r8 r9 r: r; r< r= r> r? r@ rA rB rC rD rE rF rG rH ZsqlrI rJ rK rL Zsql.expressionrM rN rO rP rQ rR rS rT rU rV rW rX rY rZ r[ r\ r] r^ r_ r` ra rb rc rd re rf rg rh ri rj rk rl rm rn ro rp rq rr rs rt ru rv rw rx ry rz r{ r| r} r~ r r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� �typesr� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r r �localsr r r r �<module> s� sqlalchemy/__pycache__/types.cpython-39.pyc 0000644 00000004221 15125143220 0014705 0 ustar 00 a ��Jh` � @ s� d Z ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ dd lm Z dd lm Z dd lm Z dd lm Z dd lm Z ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ dd lm Z dd lm Z dd lm Z dd lm Z dd lm Z dd!lm!Z! dd"lm"Z" dd#lm#Z# dd$lm$Z$ dd%lm%Z% dd&lm&Z& dd'lm'Z' dd(lm(Z( dd)lm)Z) dd*lm*Z* dd+lm+Z+ dd,lm,Z, dd-lm-Z- dd.lm.Z. dd/lm/Z/ dd0lm0Z0 dd1lm1Z1 dd2lm2Z2 dd3lm3Z3 dd4lm4Z4 dd5lm5Z5 dd6lm6Z6 dd7lm7Z7 dd8lm8Z8 dd9lm9Z9 dd:lm:Z: dd;l;m<Z< dd<l;m=Z= dd=l;m>Z> dd>l;m?Z? dd?l;m@Z@ dd@l;mAZA ddAl;mBZB dBS )Cz3Compatibility namespace for sqlalchemy.sql.types. � )� annotations� )�_Binary)�ARRAY)�BIGINT)� BigInteger)�BINARY)�BLOB)�BOOLEAN)�Boolean)�CHAR)�CLOB)� Concatenable)�DATE)�Date)�DATETIME)�DateTime)�DECIMAL)�DOUBLE)�Double)�DOUBLE_PRECISION)�Enum)�FLOAT)�Float)� Indexable)�INT)�INTEGER)�Integer)�Interval)�JSON)� LargeBinary)� MatchType)�NCHAR)�NULLTYPE)�NullType)�NUMERIC)�Numeric)�NVARCHAR)� PickleType)�REAL)� SchemaType)�SMALLINT)� SmallInteger)�String)� STRINGTYPE)�TEXT)�Text)�TIME)�Time)� TIMESTAMP)� TupleType)�Unicode)� UnicodeText)�UUID)�Uuid)� VARBINARY)�VARCHAR)� adapt_type)� ExternalType)� to_instance)� TypeDecorator)� TypeEngine)�UserDefinedType)�VariantN)C�__doc__� __future__r Z sql.sqltypesr r r r r r r r r r r r r r r r r r r r r r r r r r r r r r! r" r# r$ r% r& r' r( r) r* r+ r, r- r. r/ r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 r: Z sql.type_apir; r< r= r> r? r@ rA � rD rD �E/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/types.py�<module> s~ sqlalchemy/dialects/__pycache__/_typing.cpython-39.pyc 0000644 00000001520 15125143220 0017001 0 ustar 00 a ��Jh� � @ s� d dl mZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ ddlm Z dd l m Z dd l m Z dd l mZ dd l mZ eeeed f Zeeee e ee jf Zee j Zeeeeef e eef f Zee j Zd S )� )� annotations)�Any)�Iterable)�Mapping)�Optional)�Union� )�roles)�ColumnCollection)�Column)�ColumnCollectionConstraint)�IndexN)� __future__r �typingr r r r r Zsqlr Zsql.baser Z sql.schemar r r �strZ_OnConflictConstraintTZDDLConstraintColumnRoleZ_OnConflictIndexElementsTZWhereHavingRoleZ_OnConflictIndexWhereTZ_OnConflictSetTZ_OnConflictWhereT� r r �P/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/_typing.py�<module> s& � � sqlalchemy/dialects/__pycache__/__init__.cpython-39.pyc 0000644 00000002523 15125143220 0017073 0 ustar 00 a ��Jh� � @ s� d dl mZ d dlmZ d dlmZ d dlmZ d dlmZ ddlmZ erXddl m Z d Z d d d �d d�Z ej de d�Ze� d�ZdS )� )� annotations)�Callable)�Optional)�Type)� TYPE_CHECKING� )�util)�Dialect)Zmssql�mysql�oracleZ postgresqlZsqlite�strz%Optional[Callable[[], Type[Dialect]]])�name�returnc s� d| v r| � d�\}}n| }d}z@|dkrDtd�jjj� � �|�W S td|f �j� t� |�� W n tyt Y dS 0 t� |�r�t� |�� � fdd�S dS dS ) zedefault dialect importer. plugs into the :class:`.PluginLoader` as a first-hit system. �.�base�mariadbz!sqlalchemy.dialects.mysql.mariadbzsqlalchemy.dialects.%sNc s � j S )N)�dialect� ��moduler �Q/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/__init__.py�<lambda>6 � z_auto_fn.<locals>.<lambda>) �split� __import__Zdialectsr r �loader�getattr� ImportError�hasattr)r r Zdriverr r r �_auto_fn s$ � r zsqlalchemy.dialects)Zauto_fnzsqlalchemy.pluginsN)� __future__r �typingr r r r � r Zengine.interfacesr �__all__r Z PluginLoader�registryZpluginsr r r r �<module> s $ sqlalchemy/dialects/mssql/__pycache__/aioodbc.cpython-39.pyc 0000644 00000004306 15125143220 0020074 0 ustar 00 a ��Jh� � @ s^ d Z ddlmZ ddlmZ ddlmZ ddlmZ G dd � d e�ZG d d � d ee�Z e Z d S ) a� .. dialect:: mssql+aioodbc :name: aioodbc :dbapi: aioodbc :connectstring: mssql+aioodbc://<username>:<password>@<dsnname> :url: https://pypi.org/project/aioodbc/ Support for the SQL Server database in asyncio style, using the aioodbc driver which itself is a thread-wrapper around pyodbc. .. versionadded:: 2.0.23 Added the mssql+aioodbc dialect which builds on top of the pyodbc and general aio* dialect architecture. Using a special asyncio mediation layer, the aioodbc dialect is usable as the backend for the :ref:`SQLAlchemy asyncio <asyncio_toplevel>` extension package. Most behaviors and caveats for this driver are the same as that of the pyodbc dialect used on SQL Server; see :ref:`mssql_pyodbc` for general background. This dialect should normally be used only with the :func:`_asyncio.create_async_engine` engine creation function; connection styles are otherwise equivalent to those documented in the pyodbc section:: from sqlalchemy.ext.asyncio import create_async_engine engine = create_async_engine( "mssql+aioodbc://scott:tiger@mssql2017:1433/test?" "driver=ODBC+Driver+18+for+SQL+Server&TrustServerCertificate=yes" ) � )� annotations� )�MSDialect_pyodbc)�MSExecutionContext_pyodbc� )�aiodbcConnectorc @ s e Zd Zdd� ZdS )�MSExecutionContext_aioodbcc C s | j jdd�S )NT)� server_side)Z_dbapi_connection�cursor)�self� r �V/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mssql/aioodbc.py�create_server_side_cursor3 s z4MSExecutionContext_aioodbc.create_server_side_cursorN)�__name__� __module__� __qualname__r r r r r r 2 s r c @ s e Zd ZdZdZeZdS )�MSDialectAsync_aioodbcZaioodbcTN)r r r ZdriverZsupports_statement_cacher Zexecution_ctx_clsr r r r r 7 s r N) �__doc__� __future__r Zpyodbcr r Zconnectors.aioodbcr r r �dialectr r r r �<module> s # sqlalchemy/dialects/mssql/__pycache__/pymssql.cpython-39.pyc 0000644 00000010617 15125143220 0020206 0 ustar 00 a ��Jh � @ s� d Z ddlZddlmZ ddlmZ ddlmZ ddlmZ dd l m Z G d d � d ej �Z G d d � d e�Z G dd� de�ZeZdS )aq .. dialect:: mssql+pymssql :name: pymssql :dbapi: pymssql :connectstring: mssql+pymssql://<username>:<password>@<freetds_name>/?charset=utf8 pymssql is a Python module that provides a Python DBAPI interface around `FreeTDS <https://www.freetds.org/>`_. .. versionchanged:: 2.0.5 pymssql was restored to SQLAlchemy's continuous integration testing � N� )� MSDialect)�MSIdentifierPreparer� )�types)�util)� processorsc @ s e Zd Zdd� ZdS )�_MSNumeric_pymssqlc C s | j s tjS tj�| ||�S d S �N)Z asdecimalr Zto_float�sqltypes�Numeric�result_processor)�self�dialect�type_� r �V/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mssql/pymssql.pyr # s z#_MSNumeric_pymssql.result_processorN)�__name__� __module__� __qualname__r r r r r r " s r c s e Zd Z� fdd�Z� ZS )� MSIdentifierPreparer_pymssqlc s t � �|� d| _d S )NF)�super�__init__Z_double_percents)r r �� __class__r r r + s z%MSIdentifierPreparer_pymssql.__init__)r r r r � __classcell__r r r r r * s r c s| e Zd ZdZdZdZdZeZe � e j e jee je ji�Z edd� �Zdd� Zdd� Zd d � Z� fd d �Z� fd d�Z� ZS )�MSDialect_pymssqlT�pymssqlc C sJ t d�}tdd� |j�d�D ��}|dk r4dd� |_|dk rFt�d � |S ) Nr c s s | ]}t |�V qd S r ��int��.0�xr r r � <genexpr>C � z1MSDialect_pymssql.import_dbapi.<locals>.<genexpr>�.)� r r c S s t | d�r| S t| �S )N�decode)�hasattr�str)r" r r r �<lambda>F r$ z0MSDialect_pymssql.import_dbapi.<locals>.<lambda>)r zIThe pymssql dialect expects at least the 1.0 series of the pymssql DBAPI.)� __import__�tuple� __version__�split�Binaryr �warn)�cls�moduleZ client_verr r r � import_dbapi? s �z MSDialect_pymssql.import_dbapic C sD |� d��� }t�d|�}|r<tdd� |�dddd�D ��S d S d S ) Nzselect @@versionz*Microsoft .*? - (\d+)\.(\d+)\.(\d+)\.(\d+)c s s | ]}t |�V qd S r r r r r r r# S r$ z=MSDialect_pymssql._get_server_version_info.<locals>.<genexpr>r r& r � )Zexec_driver_sqlZscalar�re�matchr, �group)r � connection�vers�mr r r �_get_server_version_infoO s z*MSDialect_pymssql._get_server_version_infoc C sL |j dd�}|�|j� |�dd �}|rDd|v rDd|d |f |d< g |fS )N�user)�username�port�hostz%s:%s)Ztranslate_connect_args�update�query�pop)r �url�optsr> r r r �create_connect_argsW s z%MSDialect_pymssql.create_connect_argsc C s dD ]}|t |�v r dS qdS )N) z$Adaptive Server connection timed outz-Net-Lib error during Connection reset by peerz message 20003z Error 10054z"Not connected to any MS SQL serverzConnection is closedz message 20006z message 20017z message 20047z+The server failed to resume the transactionTF)r) )r �er8 �cursor�msgr r r � is_disconnect_ s z MSDialect_pymssql.is_disconnectc s t � �|�dg S )N� AUTOCOMMIT)r �get_isolation_level_values)r �dbapi_connectionr r r rK q s �z,MSDialect_pymssql.get_isolation_level_valuesc s0 |dkr|� d� n|� d� t� �||� d S )NrJ TF)Z autocommitr �set_isolation_level)r rL �levelr r r rM v s z%MSDialect_pymssql.set_isolation_level)r r r Zsupports_statement_cacheZsupports_native_decimalZsupports_native_uuidZdriverr �preparerr Z update_copyr Zcolspecsr r r ZFloat� classmethodr3 r; rE rI rK rM r r r r r r 2 s � r )�__doc__r5 �baser r � r r r Zenginer r r r r r r r r r �<module> s L sqlalchemy/dialects/mssql/__pycache__/json.cpython-39.pyc 0000644 00000011114 15125143220 0017440 0 ustar 00 a ��Jh� � @ s\ d dl mZ G dd� dej�ZG dd� d�ZG dd� deejj�ZG dd � d eejj�Zd S ) � )�typesc @ s e Zd ZdZdS )�JSONa� MSSQL JSON type. MSSQL supports JSON-formatted data as of SQL Server 2016. The :class:`_mssql.JSON` datatype at the DDL level will represent the datatype as ``NVARCHAR(max)``, but provides for JSON-level comparison functions as well as Python coercion behavior. :class:`_mssql.JSON` is used automatically whenever the base :class:`_types.JSON` datatype is used against a SQL Server backend. .. seealso:: :class:`_types.JSON` - main documentation for the generic cross-platform JSON datatype. The :class:`_mssql.JSON` type supports persistence of JSON values as well as the core index operations provided by :class:`_types.JSON` datatype, by adapting the operations to render the ``JSON_VALUE`` or ``JSON_QUERY`` functions at the database level. The SQL Server :class:`_mssql.JSON` type necessarily makes use of the ``JSON_QUERY`` and ``JSON_VALUE`` functions when querying for elements of a JSON object. These two functions have a major restriction in that they are **mutually exclusive** based on the type of object to be returned. The ``JSON_QUERY`` function **only** returns a JSON dictionary or list, but not an individual string, numeric, or boolean element; the ``JSON_VALUE`` function **only** returns an individual string, numeric, or boolean element. **both functions either return NULL or raise an error if they are not used against the correct expected value**. To handle this awkward requirement, indexed access rules are as follows: 1. When extracting a sub element from a JSON that is itself a JSON dictionary or list, the :meth:`_types.JSON.Comparator.as_json` accessor should be used:: stmt = select(data_table.c.data["some key"].as_json()).where( data_table.c.data["some key"].as_json() == {"sub": "structure"} ) 2. When extracting a sub element from a JSON that is a plain boolean, string, integer, or float, use the appropriate method among :meth:`_types.JSON.Comparator.as_boolean`, :meth:`_types.JSON.Comparator.as_string`, :meth:`_types.JSON.Comparator.as_integer`, :meth:`_types.JSON.Comparator.as_float`:: stmt = select(data_table.c.data["some key"].as_string()).where( data_table.c.data["some key"].as_string() == "some string" ) .. versionadded:: 1.4 N)�__name__� __module__� __qualname__�__doc__� r r �S/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mssql/json.pyr s r c @ s$ e Zd Zdd� Zdd� Zdd� ZdS )�_FormatTypeMixinc C s t � �d S �N)�NotImplementedError��self�valuer r r � _format_valueU s z _FormatTypeMixin._format_valuec s � � |��� �fdd�}|S )Nc s � � | �} �r�| �} | S r �r �r �r Z super_procr r �process[ s z0_FormatTypeMixin.bind_processor.<locals>.process)Zstring_bind_processor�r �dialectr r r r �bind_processorX s z _FormatTypeMixin.bind_processorc s � � |��� �fdd�}|S )Nc s � � | �} �r�| �} | S r r r r r r r f s z3_FormatTypeMixin.literal_processor.<locals>.process)Zstring_literal_processorr r r r �literal_processorc s z"_FormatTypeMixin.literal_processorN)r r r r r r r r r r r T s r c @ s e Zd Zdd� ZdS )� JSONIndexTypec C s t |t�rd| }nd| }|S )Nz$[%s]z$."%s"�� isinstance�intr r r r r p s zJSONIndexType._format_valueN�r r r r r r r r r o s r c @ s e Zd Zdd� ZdS )� JSONPathTypec C s dd� dd� |D �� S )Nz$%s� c S s& g | ] }t |t�rd | nd| �qS )z[%s]z."%s"r )�.0�elemr r r � <listcomp>| s �z.JSONPathType._format_value.<locals>.<listcomp>)�joinr r r r r y s ���zJSONPathType._format_valueNr r r r r r x s r N)r r Zsqltypesr r r r r r r r �<module> s A sqlalchemy/dialects/mssql/__pycache__/information_schema.cpython-39.pyc 0000644 00000013200 15125143220 0022332 0 ustar 00 a ��Jh� � @ s d dl mZ d dl mZ d dl mZ d dl mZ d dlmZ d dlmZ d dl m Z d dl m Z d d l m Z d d l m Z d d l mZ d d l mZ d d l mZ e� ZG dd� de�ZG dd� dej�Zee�dd� �Zedeededd�ededd�ededd�d d �Zed eed ed d�ed!ed"d�ed#ed$d�ed%ed&d�d d �Zed'eed!ed"d�ed#ed$d�ed(ed)d�ed*e d+d�ed,ed-d�ed.e d/d�ed0e d1d�ed2e d3d�ed4e d5d�ed6e d7d�ed8ed9d�d d �Zed'eed!ed"d�ed#ed$d�ed(ed)d�ed*e d+d�ed,ed-d�ed.e d/d�ed0e d1d�ed2e d3d�ed4e d5d�ed6e d7d�ed8ed9d�d:d �Zed;eed!ed"d�ed#ed$d�ed<ed=d�ed>ed?d�d d �Zed@eed!ed"d�ed#ed$d�ed(ed)d�ed<ed=d�d d �ZedAeed!ed"d�ed#ed$d�ed(ed)d�ed<ed=d�edBedCd�ed.e d/d�d d � Z edDeedEedFd�edBedCd�ed<ed=d�edGedHd�edIedJd�edKedLd�edMedNd�edOedPd�edQedRd�d d � Z edSeed ed d�ed!ed"d�ed#ed$d�edTedUd�edVedWd�edXedYd�d d � Z edZeed[e �ed\e�ed]e �ed^e �ed_e�d`d �Z edaeedbedcd�eddeded�edfedgd�d d �Z G dhdi� die�Z!edjeed[e �ed\e�edke �edle!�edme!�edne!�edoe �d`d � Z"G dpdq� dqe�Z#edreedse �edte�edue �edve �ed\e�edwe#�d`d � Z$dxS )y� )�cast)�Column)�MetaData)�Table)�compiles)� expression)�Boolean)�Integer)�Numeric)�NVARCHAR)�String)� TypeDecorator)�Unicodec @ s e Zd ZeZdZdd� ZdS )� CoerceUnicodeTc C s t |�S �N)� _cast_on_2005��self� bindvalue� r �a/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mssql/information_schema.py�bind_expression s z CoerceUnicode.bind_expressionN)�__name__� __module__� __qualname__r �impl�cache_okr r r r r r s r c @ s e Zd Zdd� ZdS )r c C s || _ d S r )r r r r r �__init__$ s z_cast_on_2005.__init__N)r r r r r r r r r # s r c K sX ddl m} |jjd u s&|jj|jk r:|j| jfi |��S |jt| jt�fi |��S d S )N� )�base) � r �dialectZserver_version_infoZMS_2005_VERSION�processr r r )�element�compiler�kwr r r r �_compile( s � �r& ZSCHEMATAZ CATALOG_NAMEZ catalog_name)�keyZ SCHEMA_NAMEZ schema_nameZ SCHEMA_OWNERZ schema_ownerZINFORMATION_SCHEMA)ZschemaZTABLESZ TABLE_CATALOGZ table_catalogZ TABLE_SCHEMAZ table_schemaZ TABLE_NAMEZ table_nameZ TABLE_TYPEZ table_type�COLUMNSZ COLUMN_NAMEZ column_nameZ IS_NULLABLEZ is_nullableZ DATA_TYPEZ data_typeZORDINAL_POSITIONZordinal_positionZCHARACTER_MAXIMUM_LENGTHZcharacter_maximum_lengthZNUMERIC_PRECISIONZnumeric_precisionZ NUMERIC_SCALEZ numeric_scaleZCOLUMN_DEFAULTZcolumn_defaultZCOLLATION_NAMEZcollation_nameztempdb.INFORMATION_SCHEMAZTABLE_CONSTRAINTSZCONSTRAINT_NAMEZconstraint_nameZCONSTRAINT_TYPEZconstraint_typeZCONSTRAINT_COLUMN_USAGEZKEY_COLUMN_USAGEZCONSTRAINT_SCHEMAZconstraint_schemaZREFERENTIAL_CONSTRAINTSZCONSTRAINT_CATALOGZconstraint_catalogZUNIQUE_CONSTRAINT_CATLOGZunique_constraint_catalogZUNIQUE_CONSTRAINT_SCHEMAZunique_constraint_schemaZUNIQUE_CONSTRAINT_NAMEZunique_constraint_nameZ MATCH_OPTIONZ match_optionZ UPDATE_RULEZ update_ruleZ DELETE_RULEZ delete_ruleZVIEWSZVIEW_DEFINITIONZview_definitionZ CHECK_OPTIONZ check_optionZ IS_UPDATABLEZ is_updatable�computed_columnsZ object_id�nameZ is_computedZ is_persistedZ definition�sysZ SEQUENCESZSEQUENCE_CATALOGZsequence_catalogZSEQUENCE_SCHEMAZsequence_schemaZ SEQUENCE_NAMEZ sequence_namec @ s e Zd ZdZeZdZdd� ZdS )�NumericSqlVariantaN This type casts sql_variant columns in the identity_columns view to numeric. This is required because: * pyodbc does not support sql_variant * pymssql under python 2 return the byte representation of the number, int 1 is returned as "\x01\x00\x00\x00". On python 3 it returns the correct value as string. Tc C s t |tdd��S )N�& � )r r �r Zcolexprr r r �column_expression� s z#NumericSqlVariant.column_expressionN�r r r �__doc__r r r r0 r r r r r, � s r, �identity_columnsZ is_identityZ seed_valueZincrement_value� last_valueZis_not_for_replicationc @ s e Zd ZdZeZdZdd� ZdS )�NVarcharSqlVariantz�This type casts sql_variant columns in the extended_properties view to nvarchar. This is required because pyodbc does not support sql_variant Tc C s t |t�S r )r r r/ r r r r0 � s z$NVarcharSqlVariant.column_expressionNr1 r r r r r5 � s r5 �extended_properties�classZ class_descZmajor_idZminor_id�valueN)%r r r r r Z ext.compilerr Zsqlr �typesr r r r r r r Zischemar Z ColumnElementr r& ZschemataZtables�columnsZmssql_temp_table_columns� constraintsZcolumn_constraintsZkey_constraintsZref_constraintsZviewsr) � sequencesr, r3 r5 r6 r r r r �<module> sb � � � � � � � � � ��� � � � � � � sqlalchemy/dialects/mssql/__pycache__/base.cpython-39.pyc 0000644 00000330553 15125143220 0017414 0 ustar 00 a ��Jh> � @ s� d Z ddlmZ ddlZddlZddlZddlZddlmZ ddlm Z ddl m Z ddl mZ dd lmZ dd lmZ dd lmZ d d l mZ d dl mZ d dl mZ d dl mZ d dl mZ d dl mZ d dl mZ d dl m Z d dl m Z d dl m Z d dl!m"Z" d dlm#Z# d dlm$Z$ d dlm%Z% d dlm&Z& d d lm'Z' d d lm(Z( d d lm)Z) d d lm*Z* d d lm+Z+ d dlmZ, d d!l-m.Z. d d"l/m0Z0 d d#l1m2Z2 d d$l3m4Z4 d d%l3m5Z5 d d&l3m6Z6 d d'l3m7Z7 d d(l3m8Z8 d d)l3m9Z9 d d*l3m:Z: d d+l3m;Z; d d,l3m<Z< d d-l3m=Z= d d.l3m>Z> d d/l3m?Z? d d0l3m@Z@ d d1l3mAZA d d2lmBZB d d3lCmDZD e �r�d d4lEmFZF d d5lGmHZH d6ZId7ZJd8ZKd9ZLd:ZMd;ZNd<ZOh d=�ZPG d>d?� d?e*jQ�ZQG d@dA� dAe*jR�ZRG dBdC� dCe*jS�ZTG dDdE� dEe*jU�ZVG dFdG� dGe*jW�ZWeWZXG dHdI� dIeW�ZYG dJdK� dK�ZZG dLdM� dMeZe*j[�Z\G dNdO� dOeZe*j[�Z]G dPdQ� dQeZe*j[�Z^G dRdS� dSeZe*j[�Z_G dTdU� dU�Z`G dVdW� dWe`e*ja�ZbG dXdY� dYe`e*jc�ZdG dZd[� d[e*je�ZfG d\d]� d]ef�ZgG d^d_� d_e*jc�ZhG d`da� dae*jie*jj�ZiG dbdc� dce*jj�ZkG ddde� dee*jl�ZmG dfdg� dge*jn�ZoG dhdi� die*jp�ZqG djdk� dke*jp�ZrG dldm� dme*js�ZtG dndo� doe*jse*ju �ZvG dpdq� dqe*jp�Zwe\ZxeVZyeQZzeTZ{eWZ|e]Z}e^Z~e_Ze@Z�ehZ�eAZ�e>Z�e6Z�e<Z�e5Z�eiZ�ekZ�eoZ�eqZ�erZ�evZ�ewZ�e;e4e?eTeAe>e6e<e@ehe9e=e:e8e^e_e7eWe]e5eieoeQeRekemefeqerevewdr� Z�G dsdt� dte$j��Z�G dudv� dve j��Z�G dwdx� dxe$j��Z�G dydz� dze��Z�G d{d|� d|e$j��Z�G d}d~� d~e$j��Z�dd�� Z�d�d�� Z�d�d�� Z�d�d�� Z�e��� Z�d�d�� Z�G d�d�� d�e j��Z�dS )�a�� .. dialect:: mssql :name: Microsoft SQL Server :normal_support: 2012+ :best_effort: 2005+ .. _mssql_external_dialects: External Dialects ----------------- In addition to the above DBAPI layers with native SQLAlchemy support, there are third-party dialects for other DBAPI layers that are compatible with SQL Server. See the "External Dialects" list on the :ref:`dialect_toplevel` page. .. _mssql_identity: Auto Increment Behavior / IDENTITY Columns ------------------------------------------ SQL Server provides so-called "auto incrementing" behavior using the ``IDENTITY`` construct, which can be placed on any single integer column in a table. SQLAlchemy considers ``IDENTITY`` within its default "autoincrement" behavior for an integer primary key column, described at :paramref:`_schema.Column.autoincrement`. This means that by default, the first integer primary key column in a :class:`_schema.Table` will be considered to be the identity column - unless it is associated with a :class:`.Sequence` - and will generate DDL as such:: from sqlalchemy import Table, MetaData, Column, Integer m = MetaData() t = Table( "t", m, Column("id", Integer, primary_key=True), Column("x", Integer), ) m.create_all(engine) The above example will generate DDL as: .. sourcecode:: sql CREATE TABLE t ( id INTEGER NOT NULL IDENTITY, x INTEGER NULL, PRIMARY KEY (id) ) For the case where this default generation of ``IDENTITY`` is not desired, specify ``False`` for the :paramref:`_schema.Column.autoincrement` flag, on the first integer primary key column:: m = MetaData() t = Table( "t", m, Column("id", Integer, primary_key=True, autoincrement=False), Column("x", Integer), ) m.create_all(engine) To add the ``IDENTITY`` keyword to a non-primary key column, specify ``True`` for the :paramref:`_schema.Column.autoincrement` flag on the desired :class:`_schema.Column` object, and ensure that :paramref:`_schema.Column.autoincrement` is set to ``False`` on any integer primary key column:: m = MetaData() t = Table( "t", m, Column("id", Integer, primary_key=True, autoincrement=False), Column("x", Integer, autoincrement=True), ) m.create_all(engine) .. versionchanged:: 1.4 Added :class:`_schema.Identity` construct in a :class:`_schema.Column` to specify the start and increment parameters of an IDENTITY. These replace the use of the :class:`.Sequence` object in order to specify these values. .. deprecated:: 1.4 The ``mssql_identity_start`` and ``mssql_identity_increment`` parameters to :class:`_schema.Column` are deprecated and should we replaced by an :class:`_schema.Identity` object. Specifying both ways of configuring an IDENTITY will result in a compile error. These options are also no longer returned as part of the ``dialect_options`` key in :meth:`_reflection.Inspector.get_columns`. Use the information in the ``identity`` key instead. .. deprecated:: 1.3 The use of :class:`.Sequence` to specify IDENTITY characteristics is deprecated and will be removed in a future release. Please use the :class:`_schema.Identity` object parameters :paramref:`_schema.Identity.start` and :paramref:`_schema.Identity.increment`. .. versionchanged:: 1.4 Removed the ability to use a :class:`.Sequence` object to modify IDENTITY characteristics. :class:`.Sequence` objects now only manipulate true T-SQL SEQUENCE types. .. note:: There can only be one IDENTITY column on the table. When using ``autoincrement=True`` to enable the IDENTITY keyword, SQLAlchemy does not guard against multiple columns specifying the option simultaneously. The SQL Server database will instead reject the ``CREATE TABLE`` statement. .. note:: An INSERT statement which attempts to provide a value for a column that is marked with IDENTITY will be rejected by SQL Server. In order for the value to be accepted, a session-level option "SET IDENTITY_INSERT" must be enabled. The SQLAlchemy SQL Server dialect will perform this operation automatically when using a core :class:`_expression.Insert` construct; if the execution specifies a value for the IDENTITY column, the "IDENTITY_INSERT" option will be enabled for the span of that statement's invocation.However, this scenario is not high performing and should not be relied upon for normal use. If a table doesn't actually require IDENTITY behavior in its integer primary key column, the keyword should be disabled when creating the table by ensuring that ``autoincrement=False`` is set. Controlling "Start" and "Increment" ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Specific control over the "start" and "increment" values for the ``IDENTITY`` generator are provided using the :paramref:`_schema.Identity.start` and :paramref:`_schema.Identity.increment` parameters passed to the :class:`_schema.Identity` object:: from sqlalchemy import Table, Integer, Column, Identity test = Table( "test", metadata, Column( "id", Integer, primary_key=True, Identity(start=100, increment=10) ), Column("name", String(20)), ) The CREATE TABLE for the above :class:`_schema.Table` object would be: .. sourcecode:: sql CREATE TABLE test ( id INTEGER NOT NULL IDENTITY(100,10) PRIMARY KEY, name VARCHAR(20) NULL, ) .. note:: The :class:`_schema.Identity` object supports many other parameter in addition to ``start`` and ``increment``. These are not supported by SQL Server and will be ignored when generating the CREATE TABLE ddl. .. versionchanged:: 1.3.19 The :class:`_schema.Identity` object is now used to affect the ``IDENTITY`` generator for a :class:`_schema.Column` under SQL Server. Previously, the :class:`.Sequence` object was used. As SQL Server now supports real sequences as a separate construct, :class:`.Sequence` will be functional in the normal way starting from SQLAlchemy version 1.4. Using IDENTITY with Non-Integer numeric types ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ SQL Server also allows ``IDENTITY`` to be used with ``NUMERIC`` columns. To implement this pattern smoothly in SQLAlchemy, the primary datatype of the column should remain as ``Integer``, however the underlying implementation type deployed to the SQL Server database can be specified as ``Numeric`` using :meth:`.TypeEngine.with_variant`:: from sqlalchemy import Column from sqlalchemy import Integer from sqlalchemy import Numeric from sqlalchemy import String from sqlalchemy.ext.declarative import declarative_base Base = declarative_base() class TestTable(Base): __tablename__ = "test" id = Column( Integer().with_variant(Numeric(10, 0), "mssql"), primary_key=True, autoincrement=True, ) name = Column(String) In the above example, ``Integer().with_variant()`` provides clear usage information that accurately describes the intent of the code. The general restriction that ``autoincrement`` only applies to ``Integer`` is established at the metadata level and not at the per-dialect level. When using the above pattern, the primary key identifier that comes back from the insertion of a row, which is also the value that would be assigned to an ORM object such as ``TestTable`` above, will be an instance of ``Decimal()`` and not ``int`` when using SQL Server. The numeric return type of the :class:`_types.Numeric` type can be changed to return floats by passing False to :paramref:`_types.Numeric.asdecimal`. To normalize the return type of the above ``Numeric(10, 0)`` to return Python ints (which also support "long" integer values in Python 3), use :class:`_types.TypeDecorator` as follows:: from sqlalchemy import TypeDecorator class NumericAsInteger(TypeDecorator): "normalize floating point return values into ints" impl = Numeric(10, 0, asdecimal=False) cache_ok = True def process_result_value(self, value, dialect): if value is not None: value = int(value) return value class TestTable(Base): __tablename__ = "test" id = Column( Integer().with_variant(NumericAsInteger, "mssql"), primary_key=True, autoincrement=True, ) name = Column(String) .. _mssql_insert_behavior: INSERT behavior ^^^^^^^^^^^^^^^^ Handling of the ``IDENTITY`` column at INSERT time involves two key techniques. The most common is being able to fetch the "last inserted value" for a given ``IDENTITY`` column, a process which SQLAlchemy performs implicitly in many cases, most importantly within the ORM. The process for fetching this value has several variants: * In the vast majority of cases, RETURNING is used in conjunction with INSERT statements on SQL Server in order to get newly generated primary key values: .. sourcecode:: sql INSERT INTO t (x) OUTPUT inserted.id VALUES (?) As of SQLAlchemy 2.0, the :ref:`engine_insertmanyvalues` feature is also used by default to optimize many-row INSERT statements; for SQL Server the feature takes place for both RETURNING and-non RETURNING INSERT statements. .. versionchanged:: 2.0.10 The :ref:`engine_insertmanyvalues` feature for SQL Server was temporarily disabled for SQLAlchemy version 2.0.9 due to issues with row ordering. As of 2.0.10 the feature is re-enabled, with special case handling for the unit of work's requirement for RETURNING to be ordered. * When RETURNING is not available or has been disabled via ``implicit_returning=False``, either the ``scope_identity()`` function or the ``@@identity`` variable is used; behavior varies by backend: * when using PyODBC, the phrase ``; select scope_identity()`` will be appended to the end of the INSERT statement; a second result set will be fetched in order to receive the value. Given a table as:: t = Table( "t", metadata, Column("id", Integer, primary_key=True), Column("x", Integer), implicit_returning=False, ) an INSERT will look like: .. sourcecode:: sql INSERT INTO t (x) VALUES (?); select scope_identity() * Other dialects such as pymssql will call upon ``SELECT scope_identity() AS lastrowid`` subsequent to an INSERT statement. If the flag ``use_scope_identity=False`` is passed to :func:`_sa.create_engine`, the statement ``SELECT @@identity AS lastrowid`` is used instead. A table that contains an ``IDENTITY`` column will prohibit an INSERT statement that refers to the identity column explicitly. The SQLAlchemy dialect will detect when an INSERT construct, created using a core :func:`_expression.insert` construct (not a plain string SQL), refers to the identity column, and in this case will emit ``SET IDENTITY_INSERT ON`` prior to the insert statement proceeding, and ``SET IDENTITY_INSERT OFF`` subsequent to the execution. Given this example:: m = MetaData() t = Table( "t", m, Column("id", Integer, primary_key=True), Column("x", Integer) ) m.create_all(engine) with engine.begin() as conn: conn.execute(t.insert(), {"id": 1, "x": 1}, {"id": 2, "x": 2}) The above column will be created with IDENTITY, however the INSERT statement we emit is specifying explicit values. In the echo output we can see how SQLAlchemy handles this: .. sourcecode:: sql CREATE TABLE t ( id INTEGER NOT NULL IDENTITY(1,1), x INTEGER NULL, PRIMARY KEY (id) ) COMMIT SET IDENTITY_INSERT t ON INSERT INTO t (id, x) VALUES (?, ?) ((1, 1), (2, 2)) SET IDENTITY_INSERT t OFF COMMIT This is an auxiliary use case suitable for testing and bulk insert scenarios. SEQUENCE support ---------------- The :class:`.Sequence` object creates "real" sequences, i.e., ``CREATE SEQUENCE``: .. sourcecode:: pycon+sql >>> from sqlalchemy import Sequence >>> from sqlalchemy.schema import CreateSequence >>> from sqlalchemy.dialects import mssql >>> print( ... CreateSequence(Sequence("my_seq", start=1)).compile( ... dialect=mssql.dialect() ... ) ... ) {printsql}CREATE SEQUENCE my_seq START WITH 1 For integer primary key generation, SQL Server's ``IDENTITY`` construct should generally be preferred vs. sequence. .. tip:: The default start value for T-SQL is ``-2**63`` instead of 1 as in most other SQL databases. Users should explicitly set the :paramref:`.Sequence.start` to 1 if that's the expected default:: seq = Sequence("my_sequence", start=1) .. versionadded:: 1.4 added SQL Server support for :class:`.Sequence` .. versionchanged:: 2.0 The SQL Server dialect will no longer implicitly render "START WITH 1" for ``CREATE SEQUENCE``, which was the behavior first implemented in version 1.4. MAX on VARCHAR / NVARCHAR ------------------------- SQL Server supports the special string "MAX" within the :class:`_types.VARCHAR` and :class:`_types.NVARCHAR` datatypes, to indicate "maximum length possible". The dialect currently handles this as a length of "None" in the base type, rather than supplying a dialect-specific version of these types, so that a base type specified such as ``VARCHAR(None)`` can assume "unlengthed" behavior on more than one backend without using dialect-specific types. To build a SQL Server VARCHAR or NVARCHAR with MAX length, use None:: my_table = Table( "my_table", metadata, Column("my_data", VARCHAR(None)), Column("my_n_data", NVARCHAR(None)), ) Collation Support ----------------- Character collations are supported by the base string types, specified by the string argument "collation":: from sqlalchemy import VARCHAR Column("login", VARCHAR(32, collation="Latin1_General_CI_AS")) When such a column is associated with a :class:`_schema.Table`, the CREATE TABLE statement for this column will yield: .. sourcecode:: sql login VARCHAR(32) COLLATE Latin1_General_CI_AS NULL LIMIT/OFFSET Support -------------------- MSSQL has added support for LIMIT / OFFSET as of SQL Server 2012, via the "OFFSET n ROWS" and "FETCH NEXT n ROWS" clauses. SQLAlchemy supports these syntaxes automatically if SQL Server 2012 or greater is detected. .. versionchanged:: 1.4 support added for SQL Server "OFFSET n ROWS" and "FETCH NEXT n ROWS" syntax. For statements that specify only LIMIT and no OFFSET, all versions of SQL Server support the TOP keyword. This syntax is used for all SQL Server versions when no OFFSET clause is present. A statement such as:: select(some_table).limit(5) will render similarly to: .. sourcecode:: sql SELECT TOP 5 col1, col2.. FROM table For versions of SQL Server prior to SQL Server 2012, a statement that uses LIMIT and OFFSET, or just OFFSET alone, will be rendered using the ``ROW_NUMBER()`` window function. A statement such as:: select(some_table).order_by(some_table.c.col3).limit(5).offset(10) will render similarly to: .. sourcecode:: sql SELECT anon_1.col1, anon_1.col2 FROM (SELECT col1, col2, ROW_NUMBER() OVER (ORDER BY col3) AS mssql_rn FROM table WHERE t.x = :x_1) AS anon_1 WHERE mssql_rn > :param_1 AND mssql_rn <= :param_2 + :param_1 Note that when using LIMIT and/or OFFSET, whether using the older or newer SQL Server syntaxes, the statement must have an ORDER BY as well, else a :class:`.CompileError` is raised. .. _mssql_comment_support: DDL Comment Support -------------------- Comment support, which includes DDL rendering for attributes such as :paramref:`_schema.Table.comment` and :paramref:`_schema.Column.comment`, as well as the ability to reflect these comments, is supported assuming a supported version of SQL Server is in use. If a non-supported version such as Azure Synapse is detected at first-connect time (based on the presence of the ``fn_listextendedproperty`` SQL function), comment support including rendering and table-comment reflection is disabled, as both features rely upon SQL Server stored procedures and functions that are not available on all backend types. To force comment support to be on or off, bypassing autodetection, set the parameter ``supports_comments`` within :func:`_sa.create_engine`:: e = create_engine("mssql+pyodbc://u:p@dsn", supports_comments=False) .. versionadded:: 2.0 Added support for table and column comments for the SQL Server dialect, including DDL generation and reflection. .. _mssql_isolation_level: Transaction Isolation Level --------------------------- All SQL Server dialects support setting of transaction isolation level both via a dialect-specific parameter :paramref:`_sa.create_engine.isolation_level` accepted by :func:`_sa.create_engine`, as well as the :paramref:`.Connection.execution_options.isolation_level` argument as passed to :meth:`_engine.Connection.execution_options`. This feature works by issuing the command ``SET TRANSACTION ISOLATION LEVEL <level>`` for each new connection. To set isolation level using :func:`_sa.create_engine`:: engine = create_engine( "mssql+pyodbc://scott:tiger@ms_2008", isolation_level="REPEATABLE READ" ) To set using per-connection execution options:: connection = engine.connect() connection = connection.execution_options(isolation_level="READ COMMITTED") Valid values for ``isolation_level`` include: * ``AUTOCOMMIT`` - pyodbc / pymssql-specific * ``READ COMMITTED`` * ``READ UNCOMMITTED`` * ``REPEATABLE READ`` * ``SERIALIZABLE`` * ``SNAPSHOT`` - specific to SQL Server There are also more options for isolation level configurations, such as "sub-engine" objects linked to a main :class:`_engine.Engine` which each apply different isolation level settings. See the discussion at :ref:`dbapi_autocommit` for background. .. seealso:: :ref:`dbapi_autocommit` .. _mssql_reset_on_return: Temporary Table / Resource Reset for Connection Pooling ------------------------------------------------------- The :class:`.QueuePool` connection pool implementation used by the SQLAlchemy :class:`.Engine` object includes :ref:`reset on return <pool_reset_on_return>` behavior that will invoke the DBAPI ``.rollback()`` method when connections are returned to the pool. While this rollback will clear out the immediate state used by the previous transaction, it does not cover a wider range of session-level state, including temporary tables as well as other server state such as prepared statement handles and statement caches. An undocumented SQL Server procedure known as ``sp_reset_connection`` is known to be a workaround for this issue which will reset most of the session state that builds up on a connection, including temporary tables. To install ``sp_reset_connection`` as the means of performing reset-on-return, the :meth:`.PoolEvents.reset` event hook may be used, as demonstrated in the example below. The :paramref:`_sa.create_engine.pool_reset_on_return` parameter is set to ``None`` so that the custom scheme can replace the default behavior completely. The custom hook implementation calls ``.rollback()`` in any case, as it's usually important that the DBAPI's own tracking of commit/rollback will remain consistent with the state of the transaction:: from sqlalchemy import create_engine from sqlalchemy import event mssql_engine = create_engine( "mssql+pyodbc://scott:tiger^5HHH@mssql2017:1433/test?driver=ODBC+Driver+17+for+SQL+Server", # disable default reset-on-return scheme pool_reset_on_return=None, ) @event.listens_for(mssql_engine, "reset") def _reset_mssql(dbapi_connection, connection_record, reset_state): if not reset_state.terminate_only: dbapi_connection.execute("{call sys.sp_reset_connection}") # so that the DBAPI itself knows that the connection has been # reset dbapi_connection.rollback() .. versionchanged:: 2.0.0b3 Added additional state arguments to the :meth:`.PoolEvents.reset` event and additionally ensured the event is invoked for all "reset" occurrences, so that it's appropriate as a place for custom "reset" handlers. Previous schemes which use the :meth:`.PoolEvents.checkin` handler remain usable as well. .. seealso:: :ref:`pool_reset_on_return` - in the :ref:`pooling_toplevel` documentation Nullability ----------- MSSQL has support for three levels of column nullability. The default nullability allows nulls and is explicit in the CREATE TABLE construct: .. sourcecode:: sql name VARCHAR(20) NULL If ``nullable=None`` is specified then no specification is made. In other words the database's configured default is used. This will render: .. sourcecode:: sql name VARCHAR(20) If ``nullable`` is ``True`` or ``False`` then the column will be ``NULL`` or ``NOT NULL`` respectively. Date / Time Handling -------------------- DATE and TIME are supported. Bind parameters are converted to datetime.datetime() objects as required by most MSSQL drivers, and results are processed from strings if needed. The DATE and TIME types are not available for MSSQL 2005 and previous - if a server version below 2008 is detected, DDL for these types will be issued as DATETIME. .. _mssql_large_type_deprecation: Large Text/Binary Type Deprecation ---------------------------------- Per `SQL Server 2012/2014 Documentation <https://technet.microsoft.com/en-us/library/ms187993.aspx>`_, the ``NTEXT``, ``TEXT`` and ``IMAGE`` datatypes are to be removed from SQL Server in a future release. SQLAlchemy normally relates these types to the :class:`.UnicodeText`, :class:`_expression.TextClause` and :class:`.LargeBinary` datatypes. In order to accommodate this change, a new flag ``deprecate_large_types`` is added to the dialect, which will be automatically set based on detection of the server version in use, if not otherwise set by the user. The behavior of this flag is as follows: * When this flag is ``True``, the :class:`.UnicodeText`, :class:`_expression.TextClause` and :class:`.LargeBinary` datatypes, when used to render DDL, will render the types ``NVARCHAR(max)``, ``VARCHAR(max)``, and ``VARBINARY(max)``, respectively. This is a new behavior as of the addition of this flag. * When this flag is ``False``, the :class:`.UnicodeText`, :class:`_expression.TextClause` and :class:`.LargeBinary` datatypes, when used to render DDL, will render the types ``NTEXT``, ``TEXT``, and ``IMAGE``, respectively. This is the long-standing behavior of these types. * The flag begins with the value ``None``, before a database connection is established. If the dialect is used to render DDL without the flag being set, it is interpreted the same as ``False``. * On first connection, the dialect detects if SQL Server version 2012 or greater is in use; if the flag is still at ``None``, it sets it to ``True`` or ``False`` based on whether 2012 or greater is detected. * The flag can be set to either ``True`` or ``False`` when the dialect is created, typically via :func:`_sa.create_engine`:: eng = create_engine( "mssql+pymssql://user:pass@host/db", deprecate_large_types=True ) * Complete control over whether the "old" or "new" types are rendered is available in all SQLAlchemy versions by using the UPPERCASE type objects instead: :class:`_types.NVARCHAR`, :class:`_types.VARCHAR`, :class:`_types.VARBINARY`, :class:`_types.TEXT`, :class:`_mssql.NTEXT`, :class:`_mssql.IMAGE` will always remain fixed and always output exactly that type. .. _multipart_schema_names: Multipart Schema Names ---------------------- SQL Server schemas sometimes require multiple parts to their "schema" qualifier, that is, including the database name and owner name as separate tokens, such as ``mydatabase.dbo.some_table``. These multipart names can be set at once using the :paramref:`_schema.Table.schema` argument of :class:`_schema.Table`:: Table( "some_table", metadata, Column("q", String(50)), schema="mydatabase.dbo", ) When performing operations such as table or component reflection, a schema argument that contains a dot will be split into separate "database" and "owner" components in order to correctly query the SQL Server information schema tables, as these two values are stored separately. Additionally, when rendering the schema name for DDL or SQL, the two components will be quoted separately for case sensitive names and other special characters. Given an argument as below:: Table( "some_table", metadata, Column("q", String(50)), schema="MyDataBase.dbo", ) The above schema would be rendered as ``[MyDataBase].dbo``, and also in reflection, would be reflected using "dbo" as the owner and "MyDataBase" as the database name. To control how the schema name is broken into database / owner, specify brackets (which in SQL Server are quoting characters) in the name. Below, the "owner" will be considered as ``MyDataBase.dbo`` and the "database" will be None:: Table( "some_table", metadata, Column("q", String(50)), schema="[MyDataBase.dbo]", ) To individually specify both database and owner name with special characters or embedded dots, use two sets of brackets:: Table( "some_table", metadata, Column("q", String(50)), schema="[MyDataBase.Period].[MyOwner.Dot]", ) .. versionchanged:: 1.2 the SQL Server dialect now treats brackets as identifier delimiters splitting the schema into separate database and owner tokens, to allow dots within either name itself. .. _legacy_schema_rendering: Legacy Schema Mode ------------------ Very old versions of the MSSQL dialect introduced the behavior such that a schema-qualified table would be auto-aliased when used in a SELECT statement; given a table:: account_table = Table( "account", metadata, Column("id", Integer, primary_key=True), Column("info", String(100)), schema="customer_schema", ) this legacy mode of rendering would assume that "customer_schema.account" would not be accepted by all parts of the SQL statement, as illustrated below: .. sourcecode:: pycon+sql >>> eng = create_engine("mssql+pymssql://mydsn", legacy_schema_aliasing=True) >>> print(account_table.select().compile(eng)) {printsql}SELECT account_1.id, account_1.info FROM customer_schema.account AS account_1 This mode of behavior is now off by default, as it appears to have served no purpose; however in the case that legacy applications rely upon it, it is available using the ``legacy_schema_aliasing`` argument to :func:`_sa.create_engine` as illustrated above. .. deprecated:: 1.4 The ``legacy_schema_aliasing`` flag is now deprecated and will be removed in a future release. .. _mssql_indexes: Clustered Index Support ----------------------- The MSSQL dialect supports clustered indexes (and primary keys) via the ``mssql_clustered`` option. This option is available to :class:`.Index`, :class:`.UniqueConstraint`. and :class:`.PrimaryKeyConstraint`. For indexes this option can be combined with the ``mssql_columnstore`` one to create a clustered columnstore index. To generate a clustered index:: Index("my_index", table.c.x, mssql_clustered=True) which renders the index as ``CREATE CLUSTERED INDEX my_index ON table (x)``. To generate a clustered primary key use:: Table( "my_table", metadata, Column("x", ...), Column("y", ...), PrimaryKeyConstraint("x", "y", mssql_clustered=True), ) which will render the table, for example, as: .. sourcecode:: sql CREATE TABLE my_table ( x INTEGER NOT NULL, y INTEGER NOT NULL, PRIMARY KEY CLUSTERED (x, y) ) Similarly, we can generate a clustered unique constraint using:: Table( "my_table", metadata, Column("x", ...), Column("y", ...), PrimaryKeyConstraint("x"), UniqueConstraint("y", mssql_clustered=True), ) To explicitly request a non-clustered primary key (for example, when a separate clustered index is desired), use:: Table( "my_table", metadata, Column("x", ...), Column("y", ...), PrimaryKeyConstraint("x", "y", mssql_clustered=False), ) which will render the table, for example, as: .. sourcecode:: sql CREATE TABLE my_table ( x INTEGER NOT NULL, y INTEGER NOT NULL, PRIMARY KEY NONCLUSTERED (x, y) ) Columnstore Index Support ------------------------- The MSSQL dialect supports columnstore indexes via the ``mssql_columnstore`` option. This option is available to :class:`.Index`. It be combined with the ``mssql_clustered`` option to create a clustered columnstore index. To generate a columnstore index:: Index("my_index", table.c.x, mssql_columnstore=True) which renders the index as ``CREATE COLUMNSTORE INDEX my_index ON table (x)``. To generate a clustered columnstore index provide no columns:: idx = Index("my_index", mssql_clustered=True, mssql_columnstore=True) # required to associate the index with the table table.append_constraint(idx) the above renders the index as ``CREATE CLUSTERED COLUMNSTORE INDEX my_index ON table``. .. versionadded:: 2.0.18 MSSQL-Specific Index Options ----------------------------- In addition to clustering, the MSSQL dialect supports other special options for :class:`.Index`. INCLUDE ^^^^^^^ The ``mssql_include`` option renders INCLUDE(colname) for the given string names:: Index("my_index", table.c.x, mssql_include=["y"]) would render the index as ``CREATE INDEX my_index ON table (x) INCLUDE (y)`` .. _mssql_index_where: Filtered Indexes ^^^^^^^^^^^^^^^^ The ``mssql_where`` option renders WHERE(condition) for the given string names:: Index("my_index", table.c.x, mssql_where=table.c.x > 10) would render the index as ``CREATE INDEX my_index ON table (x) WHERE x > 10``. .. versionadded:: 1.3.4 Index ordering ^^^^^^^^^^^^^^ Index ordering is available via functional expressions, such as:: Index("my_index", table.c.x.desc()) would render the index as ``CREATE INDEX my_index ON table (x DESC)`` .. seealso:: :ref:`schema_indexes_functional` Compatibility Levels -------------------- MSSQL supports the notion of setting compatibility levels at the database level. This allows, for instance, to run a database that is compatible with SQL2000 while running on a SQL2005 database server. ``server_version_info`` will always return the database server version information (in this case SQL2005) and not the compatibility level information. Because of this, if running under a backwards compatibility mode SQLAlchemy may attempt to use T-SQL statements that are unable to be parsed by the database server. .. _mssql_triggers: Triggers -------- SQLAlchemy by default uses OUTPUT INSERTED to get at newly generated primary key values via IDENTITY columns or other server side defaults. MS-SQL does not allow the usage of OUTPUT INSERTED on tables that have triggers. To disable the usage of OUTPUT INSERTED on a per-table basis, specify ``implicit_returning=False`` for each :class:`_schema.Table` which has triggers:: Table( "mytable", metadata, Column("id", Integer, primary_key=True), # ..., implicit_returning=False, ) Declarative form:: class MyClass(Base): # ... __table_args__ = {"implicit_returning": False} .. _mssql_rowcount_versioning: Rowcount Support / ORM Versioning --------------------------------- The SQL Server drivers may have limited ability to return the number of rows updated from an UPDATE or DELETE statement. As of this writing, the PyODBC driver is not able to return a rowcount when OUTPUT INSERTED is used. Previous versions of SQLAlchemy therefore had limitations for features such as the "ORM Versioning" feature that relies upon accurate rowcounts in order to match version numbers with matched rows. SQLAlchemy 2.0 now retrieves the "rowcount" manually for these particular use cases based on counting the rows that arrived back within RETURNING; so while the driver still has this limitation, the ORM Versioning feature is no longer impacted by it. As of SQLAlchemy 2.0.5, ORM versioning has been fully re-enabled for the pyodbc driver. .. versionchanged:: 2.0.5 ORM versioning support is restored for the pyodbc driver. Previously, a warning would be emitted during ORM flush that versioning was not supported. Enabling Snapshot Isolation --------------------------- SQL Server has a default transaction isolation mode that locks entire tables, and causes even mildly concurrent applications to have long held locks and frequent deadlocks. Enabling snapshot isolation for the database as a whole is recommended for modern levels of concurrency support. This is accomplished via the following ALTER DATABASE commands executed at the SQL prompt: .. sourcecode:: sql ALTER DATABASE MyDatabase SET ALLOW_SNAPSHOT_ISOLATION ON ALTER DATABASE MyDatabase SET READ_COMMITTED_SNAPSHOT ON Background on SQL Server snapshot isolation is available at https://msdn.microsoft.com/en-us/library/ms175095.aspx. � )� annotationsN)�overload)� TYPE_CHECKING)�UUID� )�information_schema)�JSON)� JSONIndexType)� JSONPathType� )�exc)�Identity)�schema)�Sequence)�sql)�text)�util)�cursor)�default)� reflection)�ReflectionDefaults)� coercions)�compiler)�elements)� expression)�func)� quoted_name)�roles)�sqltypes)�try_cast)�is_sql_compiler)� InsertmanyvaluesSentinelOpts)�TryCast)�BIGINT)�BINARY)�CHAR)�DATE)�DATETIME)�DECIMAL)�FLOAT)�INTEGER)�NCHAR)�NUMERIC)�NVARCHAR)�SMALLINT)�TEXT)�VARCHAR��update_wrapper)�Literal)�DMLState)� TableClause)� )� )� )� )� )� )� >� �union�groupZ current_userZdistinct�update�double�index�setZgrantZ replicationZ session_user�escapeZwaitfor�shutdown�withZfreetext�while�deleteZidentity_insertZdbcc�end�or�is�goto�commitZ rowguidcol�continue�descZ referencesZsetuser�over�checkZforeign�break�null�createZ writetextZhaving�addZ system_user�whereZreadtext�restoreZunpivotZ deallocate�user� checkpoint�view�any�collateZ updatetextZasc�exec�execute�rowcount�joinZ identitycol�to�inner�leftZcompute�functionZdiskZdatabaseZ openrowsetZ procedureZbrowse�columnZbetweenZnullifZthen�offsetsZ tablesampler �dumpZuseZcross�elseZ openquery�asZdeclare�key� precisionZopenxmlZerrlvl�file�full�kill�read�printZtran� statistics�public�backup� clustered�insert� constraint�right�rollbackZ containstable�percentZ current_date�forZ distributed�exitZ intersect�uniqueZalter�return�open�tableZ fillfactor�mergeZvaryingr Zcoalesce�identityZ nonclustered�revertZcurrent_timestamp�begin�linenoZinto�valuesZ freetexttable�fetch�if�proc�trigger�contains�loadZtextsize�when�order�offZpivotZcascade�exceptZexternal�and� authorization�exists�truncate�dropZopendatasourceZofZbulk�from�outerZbyZ raiserror� reconfigureZsomeZrestrict� current_timeZnocheck�convert�currentZruleZholdlockZ securityaudit�onZ transaction�likeZplan�saveZtsequal�selectZprimary�topr Zcase�allZnational�closeZdeny�notZrevoke�in�optionc s e Zd ZdZ� fdd�Z� ZS )�REALz the SQL Server REAL datatype.c s" |� dd� t� jf i |�� d S )Nrj � �� setdefault�super�__init__��self�kw�� __class__� �S/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mssql/base.pyr� � s z REAL.__init__��__name__� __module__� __qualname__�__doc__r� � __classcell__r� r� r� r� r� � s r� c s e Zd ZdZ� fdd�Z� ZS )�DOUBLE_PRECISIONzMthe SQL Server DOUBLE PRECISION datatype. .. versionadded:: 2.0.11 c s" |� dd� t� jf i |�� d S )Nrj �5 r� r� r� r� r� r� � s zDOUBLE_PRECISION.__init__r� r� r� r� r� r� � s r� c @ s e Zd Zd ZdS )�TINYINTN�r� r� r� �__visit_name__r� r� r� r� r� � s r� c @ s& e Zd Zdd� Ze�d�Zdd� ZdS )�_MSDatec C s dd� }|S )Nc S s* t | �tjkr"t�| j| j| j�S | S d S �N��type�datetime�date�year�month�day��valuer� r� r� �process� s z'_MSDate.bind_processor.<locals>.processr� �r� �dialectr� r� r� r� �bind_processor� s z_MSDate.bind_processorz(\d+)-(\d+)-(\d+)c s � fdd�}|S )Nc s\ t | tj�r| �� S t | t�rT� j�| �}|s<td| f ��tjdd� |�� D �� S | S d S )Nz"could not parse %r as a date valuec S s g | ]}t |pd ��qS �r ��int��.0�xr� r� r� � <listcomp> � z=_MSDate.result_processor.<locals>.process.<locals>.<listcomp>)� isinstancer� r� �str�_reg�match� ValueError�groups�r� �m�r� r� r� r� s �z)_MSDate.result_processor.<locals>.processr� �r� r� �coltyper� r� r� r� �result_processor s z_MSDate.result_processorN)r� r� r� r� �re�compiler� r� r� r� r� r� r� � s r� c sF e Zd Zd � fdd� Ze�ddd�Zdd� Ze� d�Z d d � Z � Z S ) �TIMENc s || _ t� �� d S r� )rj r� r� )r� rj �kwargsr� r� r� r� s z TIME.__init__il r c s � fdd�}|S )Nc s: t | tj�r"tj�� j| �� �} nt | tj�r6t| �} | S r� )r� r� �combine�_TIME__zero_date�timer� r� r� r� r� r� s � z$TIME.bind_processor.<locals>.processr� r� r� r� r� r� s zTIME.bind_processorz!(\d+):(\d+):(\d+)(?:\.(\d{0,6}))?c s � fdd�}|S )Nc s\ t | tj�r| �� S t | t�rT� j�| �}|s<td| f ��tjdd� |�� D �� S | S d S )Nz"could not parse %r as a time valuec S s g | ]}t |pd ��qS r� r� r� r� r� r� r� 5 r� z:TIME.result_processor.<locals>.process.<locals>.<listcomp>)r� r� r� r� r� r� r� r� r� r� r� r� r� , s �z&TIME.result_processor.<locals>.processr� r� r� r� r� r� + s zTIME.result_processor)N) r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� s r� c @ s e Zd Zd ZdS )� _BASETIMEIMPLNr� r� r� r� r� r� ? s r� c @ s e Zd Zdd� ZdS )� _DateTimeBasec C s dd� }|S )Nc S s* t | �tjkr"t�| j| j| j�S | S d S r� r� r� r� r� r� r� E s z-_DateTimeBase.bind_processor.<locals>.processr� r� r� r� r� r� D s z _DateTimeBase.bind_processorN)r� r� r� r� r� r� r� r� r� C s r� c @ s e Zd ZdS )� _MSDateTimeN�r� r� r� r� r� r� r� r� N s r� c @ s e Zd Zd ZdS )� SMALLDATETIMENr� r� r� r� r� r� R s r� c s" e Zd Zd Zd� fdd� Z� ZS )� DATETIME2Nc s t � jf i |�� || _d S r� �r� r� rj �r� rj r� r� r� r� r� Y s zDATETIME2.__init__)N�r� r� r� r� r� r� r� r� r� r� r� V s r� c s" e Zd Zd Zd� fdd� Z� ZS )�DATETIMEOFFSETNc s t � jf i |�� || _d S r� r� r� r� r� r� r� a s zDATETIMEOFFSET.__init__)Nr� r� r� r� r� r� ^ s r� c @ s e Zd Zdd� ZdS )�_UnicodeLiteralc s � fdd�}|S )Nc s( | � dd�} � jjr | � dd�} d| S )N�'�''�%z%%zN'%s')�replace�identifier_preparerZ_double_percentsr� �r� r� r� r� h s z2_UnicodeLiteral.literal_processor.<locals>.processr� r� r� r� r� �literal_processorg s z!_UnicodeLiteral.literal_processorN)r� r� r� r� r� r� r� r� r� f s r� c @ s e Zd ZdS )� _MSUnicodeNr� r� r� r� r� r� s s r� c @ s e Zd ZdS )�_MSUnicodeTextNr� r� r� r� r� r� w s r� c s2 e Zd ZdZd ZdZddd�Z� fdd�Z� ZS ) � TIMESTAMPaB Implement the SQL Server TIMESTAMP type. Note this is **completely different** than the SQL Standard TIMESTAMP type, which is not supported by SQL Server. It is a read-only datatype that does not support INSERT of values. .. versionadded:: 1.2 .. seealso:: :class:`_mssql.ROWVERSION` NFc C s || _ dS )z�Construct a TIMESTAMP or ROWVERSION type. :param convert_int: if True, binary integer values will be converted to integers on read. .. versionadded:: 1.2 N)� convert_int)r� r� r� r� r� r� � s zTIMESTAMP.__init__c s, t � �||�� | jr$� fdd�}|S � S d S )Nc s* � r � | �} | d ur&t t�| d�d�} | S )N�hex� )r� �codecs�encoder� ��super_r� r� r� � s z+TIMESTAMP.result_processor.<locals>.process)r� r� r� r� r� r r� r� � s zTIMESTAMP.result_processor)F) r� r� r� r� r� �lengthr� r� r� r� r� r� r� r� { s r� c @ s e Zd ZdZd ZdS )� ROWVERSIONa( Implement the SQL Server ROWVERSION type. The ROWVERSION datatype is a SQL Server synonym for the TIMESTAMP datatype, however current SQL Server documentation suggests using ROWVERSION for new datatypes going forward. The ROWVERSION datatype does **not** reflect (e.g. introspect) from the database as itself; the returned datatype will be :class:`_mssql.TIMESTAMP`. This is a read-only datatype that does not support INSERT of values. .. versionadded:: 1.2 .. seealso:: :class:`_mssql.TIMESTAMP` N�r� r� r� r� r� r� r� r� r� r � s r c @ s e Zd ZdZd ZdS )�NTEXTzMMSSQL NTEXT type, for variable-length unicode text up to 2^30 characters.Nr r� r� r� r� r � s r c s& e Zd ZdZd Zd� fdd� Z� ZS )� VARBINARYaL The MSSQL VARBINARY type. This type adds additional features to the core :class:`_types.VARBINARY` type, including "deprecate_large_types" mode where either ``VARBINARY(max)`` or IMAGE is rendered, as well as the SQL Server ``FILESTREAM`` option. .. seealso:: :ref:`mssql_large_type_deprecation` NFc s. || _ | j r |dvr td��t� j|d� dS )a� Construct a VARBINARY type. :param length: optional, a length for the column for use in DDL statements, for those binary types that accept a length, such as the MySQL BLOB type. :param filestream=False: if True, renders the ``FILESTREAM`` keyword in the table definition. In this case ``length`` must be ``None`` or ``'max'``. .. versionadded:: 1.4.31 )N�maxz4length must be None or 'max' when setting filestream�r N)� filestreamr� r� r� )r� r r r� r� r� r� � s �zVARBINARY.__init__)NF)r� r� r� r� r� r� r� r� r� r� r� r � s r c @ s e Zd Zd ZdS )�IMAGENr� r� r� r� r� r � s r c @ s e Zd ZdZd ZdS )�XMLa MSSQL XML type. This is a placeholder type for reflection purposes that does not include any Python-side datatype support. It also does not currently support additional arguments, such as "CONTENT", "DOCUMENT", "xml_schema_collection". Nr r� r� r� r� r � s r c @ s e Zd ZdZd ZdS )�BITz�MSSQL BIT type. Both pyodbc and pymssql return values from BIT columns as Python <class 'bool'> so just subclass Boolean. Nr r� r� r� r� r s r c @ s e Zd Zd ZdS )�MONEYNr� r� r� r� r� r s r c @ s e Zd Zd ZdS )� SMALLMONEYNr� r� r� r� r� r s r c @ s e Zd Zdd� Zdd� ZdS )�MSUUidc C s, | j r d S | jr dd� }|S dd� }|S d S )Nc S s | d ur| j } | S r� �r� r� r� r� r� r� s z&MSUUid.bind_processor.<locals>.processc S s | d ur | � dd�� dd�} | S )N�-� r� r� �r� r� r� r� r� r� ' s �� native_uuid�as_uuidr� r� r� r� r� s zMSUUid.bind_processorc C s4 | j rdd� }|S | jr$dd� }|S dd� }|S d S )Nc S s dt | ��dd�� d�S )Nr� r� )r� r� r� r� r� r� r� 1 s z)MSUUid.literal_processor.<locals>.processc S s d| j � d�S )Nr� r r� r� r� r� r� 8 s c S s d| � dd�� dd�� d�S )Nr� r r r� r r� r� r� r� r� > s �r r� r� r� r� r� . s zMSUUid.literal_processorN)r� r� r� r� r� r� r� r� r� r s r c @ sL e Zd Zd Zedddd�dd��Zedddd�d d��Zdd d �d d�ZdS )�UNIQUEIDENTIFIER.z UNIQUEIDENTIFIER[_python_UUID]z Literal[True]�r� r c C s d S r� r� r r� r� r� r� I s zUNIQUEIDENTIFIER.__init__zUNIQUEIDENTIFIER[str]zLiteral[False]c C s d S r� r� r r� r� r� r� N s T�bool)r c C s || _ d| _dS )a� Construct a :class:`_mssql.UNIQUEIDENTIFIER` type. :param as_uuid=True: if True, values will be interpreted as Python uuid objects, converting to/from string via the DBAPI. .. versionchanged: 2.0 Added direct "uuid" support to the :class:`_mssql.UNIQUEIDENTIFIER` datatype; uuid interpretation defaults to ``True``. TN)r r r r� r� r� r� S s N).).)T)r� r� r� r� r r� r� r� r� r� r F s � �r c @ s e Zd Zd ZdS )� SQL_VARIANTNr� r� r� r� r� r d s r ) r� ZbigintZsmallintZtinyintZvarcharZnvarchar�charZncharr Zntext�decimal�numeric�floatr� Z datetime2Zdatetimeoffsetr� r� Z smalldatetime�binaryZ varbinary�bit�realzdouble precision�image�xml� timestampZmoneyZ smallmoneyZuniqueidentifierZ sql_variantc s. e Zd ZdHdd�Zdd� Zdd� Zdd � Zd d � Zd d � Zdd� Z dd� Z dd� Z dd� Z dd� Z dd� Zdd� Zd d � Zd d � Zd d!� Zd"d#� Zd$d%� Zd&d'� Zd(d)� Zd*d+� Zd,d-� Zd.d/� Zd0d1� Zd2d3� Zd4d5� Z d6d7� Z d8d9� Z d:d;� Z d<d=� Z d>d?� Z!d@dA� Z"� fdBdC�Z#dDdE� Z$dFdG� Z%� Z&S )I�MSTypeCompilerNc C sN t |dd�rd|j }nd}|s&|j}|r6|d| }d�dd� ||fD ��S )zYExtend a string-type declaration with standard SQL COLLATE annotations. � collationNz COLLATE %s�(%s)� c S s g | ]}|d ur|�qS r� r� �r� �cr� r� r� r� � r� z*MSTypeCompiler._extend.<locals>.<listcomp>)�getattrr& r r_ )r� �spec�type_r r& r� r� r� �_extend� s zMSTypeCompiler._extendc K s | j |fi |��S r� )Zvisit_DOUBLE_PRECISION�r� r- r� r� r� r� � visit_double� s zMSTypeCompiler.visit_doublec K s( t |dd �}|d u rdS dd|i S d S )Nrj r) zFLOAT(%(precision)s)�r+ �r� r- r� rj r� r� r� � visit_FLOAT� s zMSTypeCompiler.visit_FLOATc K s dS )Nr� r� r/ r� r� r� � visit_TINYINT� s z MSTypeCompiler.visit_TINYINTc K s$ t |dd �}|d ur d| S dS d S )Nrj zTIME(%s)r� r1 r2 r� r� r� � visit_TIME� s zMSTypeCompiler.visit_TIMEc K s dS )Nr� r� r/ r� r� r� �visit_TIMESTAMP� s z MSTypeCompiler.visit_TIMESTAMPc K s dS )Nr r� r/ r� r� r� �visit_ROWVERSION� s z MSTypeCompiler.visit_ROWVERSIONc K s. |j r| j|fi |��S | j|fi |��S d S r� )�timezone�visit_DATETIMEOFFSET�visit_DATETIMEr/ r� r� r� �visit_datetime� s z MSTypeCompiler.visit_datetimec K s& t |dd �}|d ur d|j S dS d S )Nrj zDATETIMEOFFSET(%s)r� )r+ rj r2 r� r� r� r9 � s z#MSTypeCompiler.visit_DATETIMEOFFSETc K s$ t |dd �}|d ur d| S dS d S )Nrj z DATETIME2(%s)r� r1 r2 r� r� r� �visit_DATETIME2� s z MSTypeCompiler.visit_DATETIME2c K s dS )Nr� r� r/ r� r� r� �visit_SMALLDATETIME� s z"MSTypeCompiler.visit_SMALLDATETIMEc K s | j |fi |��S r� )�visit_NVARCHARr/ r� r� r� � visit_unicode� s z MSTypeCompiler.visit_unicodec K s0 | j jr| j|fi |��S | j|fi |��S d S r� )r� �deprecate_large_types� visit_VARCHAR� visit_TEXTr/ r� r� r� � visit_text� s zMSTypeCompiler.visit_textc K s0 | j jr| j|fi |��S | j|fi |��S d S r� )r� r@ r> � visit_NTEXTr/ r� r� r� �visit_unicode_text� s z!MSTypeCompiler.visit_unicode_textc K s | � d|�S )Nr �r. r/ r� r� r� rD � s zMSTypeCompiler.visit_NTEXTc K s | � d|�S )Nr/ rF r/ r� r� r� rB � s zMSTypeCompiler.visit_TEXTc K s | j d||jpdd�S )Nr0 r r �r. r r/ r� r� r� rA � s z MSTypeCompiler.visit_VARCHARc K s | � d|�S )Nr% rF r/ r� r� r� � visit_CHAR s zMSTypeCompiler.visit_CHARc K s | � d|�S )Nr+ rF r/ r� r� r� � visit_NCHAR s zMSTypeCompiler.visit_NCHARc K s | j d||jpdd�S �Nr- r r rG r/ r� r� r� r> s z MSTypeCompiler.visit_NVARCHARc K s4 | j jtk r | j|fi |��S | j|fi |��S d S r� )r� �server_version_info�MS_2008_VERSIONr: Z visit_DATEr/ r� r� r� � visit_date s zMSTypeCompiler.visit_datec K s | j |fi |��S r� )� visit_timer/ r� r� r� �visit__BASETIMEIMPL s z"MSTypeCompiler.visit__BASETIMEIMPLc K s4 | j jtk r | j|fi |��S | j|fi |��S d S r� )r� rK rL r: r5 r/ r� r� r� rN s zMSTypeCompiler.visit_timec K s0 | j jr| j|fi |��S | j|fi |��S d S r� )r� r@ �visit_VARBINARY� visit_IMAGEr/ r� r� r� �visit_large_binary s z!MSTypeCompiler.visit_large_binaryc K s dS )Nr r� r/ r� r� r� rQ s zMSTypeCompiler.visit_IMAGEc K s dS )Nr r� r/ r� r� r� � visit_XML! s zMSTypeCompiler.visit_XMLc K s. | j d||jpdd�}t|dd�r*|d7 }|S )Nr r r r Fz FILESTREAM)r. r r+ )r� r- r� r r� r� r� rP $ s z MSTypeCompiler.visit_VARBINARYc K s | � |�S r� )� visit_BITr/ r� r� r� � visit_boolean* s z MSTypeCompiler.visit_booleanc K s dS )Nr r� r/ r� r� r� rT - s zMSTypeCompiler.visit_BITc K s | j d|dd�S rJ rF r/ r� r� r� � visit_JSON0 s zMSTypeCompiler.visit_JSONc K s dS )Nr r� r/ r� r� r� � visit_MONEY5 s zMSTypeCompiler.visit_MONEYc K s dS )Nr r� r/ r� r� r� �visit_SMALLMONEY8 s z MSTypeCompiler.visit_SMALLMONEYc s0 |j r| j|fi |��S t� j|fi |��S d S r� )r �visit_UNIQUEIDENTIFIERr� � visit_uuidr/ r� r� r� rZ ; s zMSTypeCompiler.visit_uuidc K s dS )Nr r� r/ r� r� r� rY A s z%MSTypeCompiler.visit_UNIQUEIDENTIFIERc K s dS )Nr r� r/ r� r� r� �visit_SQL_VARIANTD s z MSTypeCompiler.visit_SQL_VARIANT)N)'r� r� r� r. r0 r3 r4 r5 r6 r7 r; r9 r< r= r? rC rE rD rB rA rH rI r> rM rO rN rR rQ rS rP rU rT rV rW rX rZ rY r[ r� r� r� r� r� r% � sF r% c sb e Zd ZU dZdZdZded< dd� Zdd� Zd d � Z d d � Z d d� Z dd� Z � fdd�Z � ZS )�MSExecutionContextFN� MSDialectr� c C s* | j r&| j jr&| j jj}||| j j�}|S r� )�compiledZschema_translate_map�preparerZ_render_schema_translates)r� Z statementZrstr� r� r� � _opt_encodeO s z MSExecutionContext._opt_encodec C s� | j r�tr>t| j�sJ �t| jjt�s*J �t| jjjt�s>J �| jjj}|j }|dur�t|j t �s�d}| jj }|j | jd v p�|jo�|j |jv | _n d}d| _| jj o�|o�| jj o�| j o�| j | _| jr�| j�| j| �d| j�|� �d| � dS )z#Activate IDENTITY_INSERT if needed.NTr FzSET IDENTITY_INSERT %s ONr� ) �isinsertr r r^ r� � compile_stater4 � dml_tabler5 �_autoincrement_columnr r Zdml_compile_stateri Zcompiled_parametersZ_dict_parametersZ_insert_col_keys�_enable_identity_insert�inline�effective_returningZ executemany�_select_lastrowid�root_connection�_cursor_executer r` r� � format_table)r� ZtblZ id_columnZinsert_has_identityrb r� r� r� �pre_execV sR � �� � ���� ���zMSExecutionContext.pre_execc C s" | j }| js| js| jr"| jj| _| jr|| jj rD|� | jdd| � n|� | jdd| � | j� � d }t |d �| _ tj| _n8| jdur�t| j�r�| jjr�t�| j| jj| j� � �| _| j�r tr�t| j�s�J �t| jjt�s�J �t| jjjt �s�J �|� | j| � d| j � | jjj� �d| � dS )z#Disable IDENTITY_INSERT if enabled.z$SELECT scope_identity() AS lastrowidr� z SELECT @@identity AS lastrowidr N�SET IDENTITY_INSERT %s OFF) ri ra �isupdate�isdeleter r^ Z _rowcountrh r� �use_scope_identityrj Zfetchallr� � _lastrowid�_cursorZ_NO_CURSOR_DMLZcursor_fetch_strategyr^ r rg Z FullyBufferedCursorFetchStrategy� descriptionre r r� rb r4 rc r5 r` r� rk )r� �conn�rowr� r� r� � post_exec� s` � � ����� �����z MSExecutionContext.post_execc C s | j S r� )rq r� r� r� r� � get_lastrowid� s z MSExecutionContext.get_lastrowidc C sF | j rBz(| j�| �d| j�| jjj� �� W n t y@ Y n0 d S )Nrm ) re r r] r` r� rk r^ rb rc � Exception)r� �er� r� r� �handle_dbapi_exception� s ���� z)MSExecutionContext.handle_dbapi_exceptionc C s | � d| j�|� |�S )NzSELECT NEXT VALUE FOR %s)Z_execute_scalarr� �format_sequence)r� �seqr- r� r� r� � fire_sequence� s ��z MSExecutionContext.fire_sequencec s> t |tj�r2||jju r2t |jtj�r2|jjr2d S t� � |�S r� ) r� � sa_schema�Columnr~ rd r r �optionalr� �get_insert_default)r� rd r� r� r� r� � s � � ��z%MSExecutionContext.get_insert_default)r� r� r� re rh rq �__annotations__r` rl rv rw rz r} r� r� r� r� r� r� r\ H s 19 r\ c s� e Zd ZdZe�ejjddddd��Z� fdd�Z � fd d �Z � fd d �Z d d� Z dd� Z dd� Zdd� Zdd� Zdd� Zdd� Zdd � Zd d � Zd d � Z� fd!d"�Zd#d$� Zd%d&� Zd'd(� Zd)d*� Zd+d,� Zd-d.� Z d/d0� Z d1d2� Z d3d4� Z e de� fd6d7� �Z e � fd8d9��Z!e df� fd;d<� �Z"d=d>� Z#d?d@� Z$dAdB� Z%dCdD� Z&� fdEdF�Z'dGdH� Z(dIdJ� Z)� fdKdL�Z*dMdN� Z+dOdP� Z,dQdR� Z-dSdT� Z.dUdV� Z/dWdX� Z0dYdZ� Z1d[d\� Z2d]d^� Z3d_d`� Z4dadb� Z5dcdd� Z6� Z7S )g� MSSQLCompilerTZ dayofyear�weekdayZ millisecond� microsecond)ZdoyZdowZ milliseconds� microsecondsc s i | _ t� j|i |�� d S r� )� tablealiasesr� r� )r� �argsr� r� r� r� r� � s zMSSQLCompiler.__init__c s d|d< t � j|fi |��S )NT�literal_execute)r� �_format_frame_clause)r� Zrange_r� r� r� r� r� � s z"MSSQLCompiler._format_frame_clausec s �� fdd�}|S )Nc sB | j jr �| g|�R i |��S ttt| ��j�}||i |��S d S r� )r� �legacy_schema_aliasingr+ r� r� r� )r� �argr� r )r� �fnr� r� �decorate� s z<MSSQLCompiler._with_legacy_schema_aliasing.<locals>.decorater� )r� r� r� �r� r� � _with_legacy_schema_aliasing� s z*MSSQLCompiler._with_legacy_schema_aliasingc K s dS )NZCURRENT_TIMESTAMPr� �r� r� r� r� r� r� �visit_now_func s z MSSQLCompiler.visit_now_funcc K s dS )Nz GETDATE()r� r� r� r� r� �visit_current_date_func s z%MSSQLCompiler.visit_current_date_funcc K s d| j |fi |�� S �NzLEN%s�Zfunction_argspecr� r� r� r� �visit_length_func s z MSSQLCompiler.visit_length_funcc K s d| j |fi |�� S r� r� r� r� r� r� �visit_char_length_func s z$MSSQLCompiler.visit_char_length_funcc K sN |j j d j| fi |��}d|d< |j j d j| fi |��}d|� d|� d�S )Nr Tr� r z string_agg(�, �))�clauses�_compiler_dispatch)r� r� r� �exprZ delimeterr� r� r� � visit_aggregate_strings_func s z*MSSQLCompiler.visit_aggregate_strings_funcc s d� � �fdd�|D ��S )Nz + c 3 s | ]}�j |fi � ��V qd S r� )r� �r� �elem�r� r� r� r� � <genexpr> r� zFMSSQLCompiler.visit_concat_op_expression_clauselist.<locals>.<genexpr>�r_ )r� Z clauselist�operatorr� r� r� r� �%visit_concat_op_expression_clauselist s z3MSSQLCompiler.visit_concat_op_expression_clauselistc K s, d| j |jfi |��| j |jfi |��f S )Nz%s + %s�r� rb rv �r� r r� r� r� r� r� �visit_concat_op_binary s �z$MSSQLCompiler.visit_concat_op_binaryc K s dS )N�1r� �r� r� r� r� r� r� � visit_true! s zMSSQLCompiler.visit_truec K s dS )N�0r� r� r� r� r� � visit_false$ s zMSSQLCompiler.visit_falsec K s, d| j |jfi |��| j |jfi |��f S )NzCONTAINS (%s, %s)r� r� r� r� r� �visit_match_op_binary' s �z#MSSQLCompiler.visit_match_op_binaryc s~ t � j|fi |��}|jrz| �|�rzd|d< |d| j| �|�fi |�� 7 }|jdurz|jd rh|d7 }|jd rz|d7 }|S ) z+MS-SQL puts TOP, it's version of LIMIT hereTr� zTOP %s Nrx zPERCENT � with_tiesz WITH TIES )r� �get_select_precolumns�_has_row_limiting_clause�_use_topr� �_get_limit_or_fetch� _fetch_clause�_fetch_clause_options)r� r� r� �sr� r� r� r� - s �� z#MSSQLCompiler.get_select_precolumnsc C s |S r� r� �r� r~ r r� r� r� �get_from_hint_textB s z MSSQLCompiler.get_from_hint_textc C s |S r� r� r� r� r� r� �get_crud_hint_textE s z MSSQLCompiler.get_crud_hint_textc C s |j d u r|jS |j S d S r� )r� � _limit_clause�r� r� r� r� r� r� H s z!MSSQLCompiler._get_limit_or_fetchc C s6 |j d u o4|�|j�p4|�|j�o4|jd p4|jd S )Nrx r� )�_offset_clauseZ_simple_int_clauser� r� r� r� r� r� r� r� N s �zMSSQLCompiler._use_topc K s dS �Nr r� )r� �csr� r� r� r� � limit_clause] s zMSSQLCompiler.limit_clausec C s> |j jst�d��|jd ur:|jd s0|jd r:t�d��d S )NzLMSSQL requires an order_by when using an OFFSET or a non-simple LIMIT clauserx r� z^MSSQL needs TOP to use PERCENT and/or WITH TIES. Only simple fetch without offset can be used.)�_order_by_clauser� r � CompileErrorr� r� r� r� r� �_check_can_use_fetch_limit` s � ���z(MSSQLCompiler._check_can_use_fetch_limitc K sB | j jr:| �|�s:| �|� | j|f| �|�dd�|��S dS dS )zdMSSQL 2012 supports OFFSET/FETCH operators Use it instead subquery with row_number T)� fetch_clauseZrequire_offsetr N)r� �_supports_offset_fetchr� r� r� r� �r� r� r� r� r� r� �_row_limit_clauses s ���z MSSQLCompiler._row_limit_clausec K s, d| j |jfi |��| j |jfi |��f S )NzTRY_CAST (%s AS %s))r� ZclauseZ typeclause)r� �elementr� r� r� r� �visit_try_cast� s �z MSSQLCompiler.visit_try_castc K s� |}|j r�| jjs�| �|�s�t|dd�s�| �|� dd� |jjD �}| �|�}|j }|� � }d|_ |� t j�� j|d��d���d��� }t �d�}t jdd� |jD �� }|dur�|�||k�}|dur�|�||| k�}n|�||k�}|S |S dS ) z�Look for ``LIMIT`` and OFFSET in a select statement, and if so tries to wrap it in a subquery with ``row_number()`` criterion. MSSQL 2012 and above are excluded � _mssql_visitNc S s g | ]}t �|��qS r� )�sql_utilZunwrap_label_referencer� r� r� r� r� � s �z<MSSQLCompiler.translate_select_structure.<locals>.<listcomp>T)�order_by�mssql_rnc S s g | ]}|j d kr|�qS )r� )ri r) r� r� r� r� � r� )r� r� r� r� r+ r� r� r� r� r� Z _generater� Z add_columnsr r Z ROW_NUMBERrO �labelr� �aliasrd r� r* rU ) r� Z select_stmtr� r� Z_order_by_clausesr� Z offset_clauser� Z limitselectr� r� r� �translate_select_structure� sP ��� � � ����� � �z(MSSQLCompiler.translate_select_structureFc s` ||u s |r t � j|fi |��S | �|�}|d urH| j|fd|i|��S t � j|fi |��S d S �N� mssql_aliased)r� � visit_table�_schema_aliased_tabler� )r� r~ r� �iscrudr� r� r� r� r� r� � s zMSSQLCompiler.visit_tablec s |j |d< t� j|fi |��S r� )r� r� � visit_alias)r� r� r� r� r� r� r� � s zMSSQLCompiler.visit_aliasNc s� |j d ur| js| jr | �� rx| �|j �}|d urxt�||�}|d urd||j|j||j|jf|j � t � j |fi |��S t � j |fd|i|��S )N�add_to_result_map) r~ rn ro � is_subqueryr� r Z _corresponding_column_or_error�nameri r� r� � visit_column)r� rd r� r� �tZ convertedr� r� r� r� � s4 ���� ����zMSSQLCompiler.visit_columnc C s: t |dd �d ur2|| jvr(|�� | j|< | j| S d S d S )Nr )r+ r� r� )r� r~ r� r� r� r� � s z#MSSQLCompiler._schema_aliased_tablec K s. | j �|j|j�}d|| j|jfi |��f S )NzDATEPART(%s, %s))� extract_map�get�fieldr� r� )r� �extractr� r� r� r� r� � visit_extract� s zMSSQLCompiler.visit_extractc K s d| j �|� S )NzSAVE TRANSACTION %s�r_ Zformat_savepoint�r� Zsavepoint_stmtr� r� r� r� �visit_savepoint� s �z MSSQLCompiler.visit_savepointc K s d| j �|� S )NzROLLBACK TRANSACTION %sr� r� r� r� r� �visit_rollback_to_savepoint� s �z)MSSQLCompiler.visit_rollback_to_savepointc s^ t |jtj�rJ|jtjkrJt |jtj�sJ| jt�|j|j|j�fi |��S t � j |fi |��S )z]Move bind parameters to the right-hand side of an operator, where possible. ) r� rb r Z BindParameterr� �eqrv r� ZBinaryExpressionr� � visit_binary)r� r r� r� r� r� r� s � � � ���zMSSQLCompiler.visit_binaryc s| �j s �jr�j�d�}n �jr.�j�d�}n ds:J d��t�|�� � ����fdd��jdt� |�d�D �}d d � |� S ) NZinsertedZdeletedFz+expected Insert, Update or Delete statementc sD g | ]<\}}}}}�j �� �|��d |fif||||d�����qS )Zresult_map_targets)�fallback_label_nameZcolumn_is_repeatedr� � proxy_name)Z_label_returning_column�traverse)r� r� r� r� rd Zrepeated��adapterr� �populate_result_mapr� �stmtr� r� r� - s& ��� �z2MSSQLCompiler.returning_clause.<locals>.<listcomp>T)�colszOUTPUT r� ) Z is_insertZ is_updater~ r� Z is_deleter� Z ClauseAdapterZ _generate_columns_plus_namesr Z_select_iterablesr_ )r� r� Zreturning_colsr� r� �target�columnsr� r� r� �returning_clause s ��z MSSQLCompiler.returning_clausec C s dS )NZWITHr� )r� � recursiver� r� r� �get_cte_preambleF s z MSSQLCompiler.get_cte_preamblec s* t |tj�r|�d �S t� �|||�S d S r� )r� r ZFunctionr� r� �label_select_column)r� r� rd �asfromr� r� r� r� M s z!MSSQLCompiler.label_select_columnc K s dS r� r� r� r� r� r� �for_update_clauseS s z MSSQLCompiler.for_update_clausec K sP | � � r(| �|�s(|jd u s$| jjs(dS | j|jfi |��}|rHd| S dS d S )Nr z ORDER BY )r� r� �_offsetr� r� r� r� )r� r� r� r� r� r� r� �order_by_clauseX s ���� z MSSQLCompiler.order_by_clausec s& dd� � ��fdd�|g| D �� S )a Render the UPDATE..FROM clause specific to MSSQL. In MSSQL, if the UPDATE statement involves an alias of the table to be updated, then the table itself must be added to the FROM list as well. Otherwise, it is optional. Here, we add it regardless. �FROM r� c 3 s& | ] }|j �fd � d����V qdS �T)r� Z fromhintsN�r� �r� r� �� from_hintsr� r� r� r� r� { s �z3MSSQLCompiler.update_from_clause.<locals>.<genexpr>r� )r� Z update_stmt� from_table� extra_fromsr� r� r� r� r� �update_from_clauseq s �z MSSQLCompiler.update_from_clausec K s& d}|r d}|j | fdd|d�|��S )z=If we have extra froms make sure we render any alias as hint.FT)r� r� �ashintr� )r� � delete_stmtr� r� r� r r� r� r� �delete_table_clause� s ���z!MSSQLCompiler.delete_table_clausec s& dd� � ��fdd�|g| D �� S )zjRender the DELETE .. FROM clause specific to MSSQL. Yes, it has the FROM keyword twice. r� r� c 3 s& | ] }|j �fd � d����V qdS r� r� r� r� r� r� r� � s �z9MSSQLCompiler.delete_extra_from_clause.<locals>.<genexpr>r� )r� r r� r� r� r� r� r� r� �delete_extra_from_clause� s �z&MSSQLCompiler.delete_extra_from_clausec K s dS )NzSELECT 1 WHERE 1!=1r� r/ r� r� r� �visit_empty_set_expr� s z"MSSQLCompiler.visit_empty_set_exprc K s d| � |j�| � |j�f S )Nz*NOT EXISTS (SELECT %s INTERSECT SELECT %s)r� r� r� r� r� � visit_is_distinct_from_binary� s �z+MSSQLCompiler.visit_is_distinct_from_binaryc K s d| � |j�| � |j�f S )Nz&EXISTS (SELECT %s INTERSECT SELECT %s)r� r� r� r� r� �!visit_is_not_distinct_from_binary� s �z/MSSQLCompiler.visit_is_not_distinct_from_binaryc K s� |j jtju r:d| j|jfi |��| j|jfi |��f S d| j|jfi |��| j|jfi |��f }|j jtju r�d| j|jfi |��| j|jfi |��f }n�|j jtju �rd| j|jfi |��| j|jfi |��t |j tj �r�dnd|j j |j j f f }n�|j jtj u �rd}nj|j jtju �rXd| j|jfi |��| j|jfi |��f }n,d | j|jfi |��| j|jfi |��f }|d | d S ) NzJSON_QUERY(%s, %s)z+CASE JSON_VALUE(%s, %s) WHEN NULL THEN NULLz(ELSE CAST(JSON_VALUE(%s, %s) AS INTEGER)z#ELSE CAST(JSON_VALUE(%s, %s) AS %s)r) zNUMERIC(%s, %s)z0WHEN 'true' THEN 1 WHEN 'false' THEN 0 ELSE NULLzELSE JSON_VALUE(%s, %s)zELSE JSON_QUERY(%s, %s)r( z END)r� Z_type_affinityr r r� rb rv �Integer�Numericr� �Floatrj �scale�Boolean�String)r� r r� r� Zcase_expression�type_expressionr� r� r� � _render_json_extract_from_binary� sJ ��� ��� ���z.MSSQLCompiler._render_json_extract_from_binaryc K s | j ||fi |��S r� �r r� r� r� r� � visit_json_getitem_op_binary� s z*MSSQLCompiler.visit_json_getitem_op_binaryc K s | j ||fi |��S r� r r� r� r� r� �!visit_json_path_getitem_op_binary� s z/MSSQLCompiler.visit_json_path_getitem_op_binaryc K s d| j �|� S )NzNEXT VALUE FOR %s)r_ r{ )r� r| r� r� r� r� �visit_sequence� s z MSSQLCompiler.visit_sequence)FF)N)8r� r� r� Zreturning_precedes_valuesr Z update_copyr � SQLCompilerr� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r r r r r r r r r r� r� r� r� r� r� � st �� 4 3 8r� c s4 e Zd ZdZdZdd� Zdd� Z� fdd�Z� ZS ) �MSSQLStrictCompilerz�A subclass of MSSQLCompiler which disables the usage of bind parameters where not allowed natively by MS-SQL. A dialect may use this compiler on a platform where native binds are used. Tc K s4 d|d< d| j |jfi |��| j |jfi |��f S )NTr� z%s IN %sr� r� r� r� r� �visit_in_op_binary� s �z&MSSQLStrictCompiler.visit_in_op_binaryc K s4 d|d< d| j |jfi |��| j |jfi |��f S )NTr� z %s NOT IN %sr� r� r� r� r� �visit_not_in_op_binary� s �z*MSSQLStrictCompiler.visit_not_in_op_binaryc s2 t t|�tj�r dt|� d S t� �||�S dS )a5 For date and datetime values, convert to a string format acceptable to MSSQL. That seems to be the so-called ODBC canonical date format which looks like this: yyyy-mm-dd hh:mi:ss.mmm(24h) For other data types, call the base class implementation. r� N)� issubclassr� r� r� r� r� �render_literal_value)r� r� r- r� r� r� r s z(MSSQLStrictCompiler.render_literal_value) r� r� r� r� Zansi_bind_rulesr r r r� r� r� r� r� r � s r c sv e Zd Zdd� Zddd�Zdd� Zdd � Zd d � Zd d � Zdd� Z dd� Z dd� Z dd� Z � fdd�Z dd� Z� ZS )� MSDDLCompilerc K s� | j �|�}|jd ur,|d| �|j� 7 }n |d| jjj|j|d� 7 }|jd ur�|jr||js|t |j t j �s||j du s||jr�|d7 }n|jd u r�|d7 }|jd u r�t�d��|jd }|d }|d }|d us�|d ur�|jr�t�d ��t�d d � |j�r|| j|jfi |��7 }nj||jju �s.|j du �r^t |j t ��rF|j j�r^|| �t||d ��7 }n | �|�}|d u�r~|d| 7 }|S )Nr( )r Tz NOT NULLz NULLz;mssql requires Table-bound columns in order to generate DDL�mssql�identity_start�identity_incrementzzCannot specify options 'mssql_identity_start' and/or 'mssql_identity_increment' while also using the 'Identity' construct.z|The dialect options 'mssql_identity_start' and 'mssql_identity_increment' are deprecated. Use the 'Identity' object instead.�1.4��start� incrementz DEFAULT )r_ � format_column�computedr� r� Ztype_compiler_instancer� �nullableZ primary_keyr� r r~ r � autoincrementr� r~ r r� �dialect_optionsr �warn_deprecatedrd r� r Zget_column_default_string)r� rd r� ZcolspecZd_optr r r r� r� r� �get_column_specification sf � �� ��� � �� �� �� z&MSDDLCompiler.get_column_specificationFc sT |j � ��� � �j�d}� jr(|d7 }� jd d }|d urT|rL|d7 }n|d7 }� jd d }|rn|d7 }|d �j� |d ���� j�f 7 }t� j �d kr�|d d � �fdd�� j D �� 7 }� jd d �r � fdd�� jd d D �}|dd � �fdd�|D �� 7 }� jd d }|d u�rPt � t j|�}�jj|ddd�} |d| 7 }|S )NzCREATE zUNIQUE r rs � CLUSTERED � NONCLUSTERED � columnstorez COLUMNSTORE zINDEX %s ON %s��include_schemar z (%s)r� c 3 s | ]}� j j|d dd�V qdS )FT�Z include_tableZ literal_bindsN)� sql_compilerr� )r� r� r� r� r� r� o s ��z3MSDDLCompiler.visit_create_index.<locals>.<genexpr>�includec s& g | ] }t |t�r � jj| n|�qS r� )r� r� r~ r* )r� �col)rA r� r� r� x s �z4MSDDLCompiler.visit_create_index.<locals>.<listcomp>z INCLUDE (%s)c s g | ]}� � |j��qS r� )�quoter� r) )r_ r� r� r� ~ r� rU FTr- z WHERE )r� Z_verify_index_tabler_ r{ r% �_prepared_index_namerk r~ �lenZ expressionsr_ r �expectr ZDDLExpressionRoler. r� ) r� rS r, r� r rs r* Z inclusions� whereclauseZwhere_compiledr� )rA r_ r� r� �visit_create_indexS sN �� �� �� z MSDDLCompiler.visit_create_indexc K s$ d| j |jdd�| j�|jj�f S )Nz DROP INDEX %s ON %sFr+ )r2 r� r_ rk r~ )r� r� r� r� r� r� �visit_drop_index� s �z MSDDLCompiler.visit_drop_indexc s� t |�dkrdS d}|jd ur2|d� j�|� 7 }|d7 }|jd d }|d urf|r^|d7 }n|d7 }|d d �� fd d �|D �� 7 }|� �|�7 }|S ) Nr r �CONSTRAINT %s z PRIMARY KEY r rs r( r) r' r� c 3 s | ]}� j �|j�V qd S r� �r_ r1 r� r) r� r� r� r� � s z=MSDDLCompiler.visit_primary_key_constraint.<locals>.<genexpr>)r3 r� r_ �format_constraintr% r_ � define_constraint_deferrability)r� ru r� r rs r� r� r� � visit_primary_key_constraint� s$ � � z*MSDDLCompiler.visit_primary_key_constraintc s� t |�dkrdS d}|jd ur>� j�|�}|d ur>|d| 7 }|d� j|fi |�� 7 }|jd d }|d ur�|r||d7 }n|d7 }|d d �� fd d �|D �� 7 }|� �|�7 }|S ) Nr r r8 z UNIQUE %sr rs r( r) r' r� c 3 s | ]}� j �|j�V qd S r� r9 r) r� r� r� r� � s z8MSDDLCompiler.visit_unique_constraint.<locals>.<genexpr>)r3 r� r_ r: Z!define_unique_constraint_distinctr% r_ r; )r� ru r� r Zformatted_namers r� r� r� �visit_unique_constraint� s, �� � z%MSDDLCompiler.visit_unique_constraintc K s. d| j j|jddd� }|jdu r*|d7 }|S )NzAS (%s)FTr- z PERSISTED)r. r� �sqltext� persisted)r� � generatedr� r r� r� r� �visit_computed_column� s � z#MSDDLCompiler.visit_computed_columnc K sT | j �|j�}|r|n| jj}d�| j�|jjt � � �| j � |�| j j |jdd��S )NzNexecute sp_addextendedproperty 'MS_Description', {}, 'schema', {}, 'table', {}F�Z use_schema) r_ �schema_for_objectr� r� �default_schema_name�formatr. r �commentr r- � quote_schemark �r� rS r� r � schema_namer� r� r� �visit_set_table_comment� s � ��z%MSDDLCompiler.visit_set_table_commentc K s@ | j �|j�}|r|n| jj}d�| j �|�| j j|jdd��S )NzKexecute sp_dropextendedproperty 'MS_Description', 'schema', {}, 'table', {}FrB )r_ rC r� r� rD rE rG rk �r� r� r� r rI r� r� r� �visit_drop_table_comment� s ��z&MSDDLCompiler.visit_drop_table_commentc K sd | j �|jj�}|r|n| jj}d�| j�|jj t � � �| j � |�| j j |jjdd�| j �|j��S )Nz\execute sp_addextendedproperty 'MS_Description', {}, 'schema', {}, 'table', {}, 'column', {}FrB )r_ rC r� r~ r� rD rE r. r rF r r- rG rk r! rH r� r� r� �visit_set_column_comment� s � � ��z&MSDDLCompiler.visit_set_column_commentc K sP | j �|jj�}|r|n| jj}d�| j �|�| j j|jjdd�| j � |j��S )NzYexecute sp_dropextendedproperty 'MS_Description', 'schema', {}, 'table', {}, 'column', {}FrB ) r_ rC r� r~ r� rD rE rG rk r! rK r� r� r� �visit_drop_column_comment� s � ��z'MSDDLCompiler.visit_drop_column_commentc s@ d }|j jd ur(|j j}d| j�|� }t� j|fd|i|��S )Nz AS %s�prefix)r� � data_typeZ type_compilerr� r� �visit_create_sequence)r� rS r� rO rP r� r� r� rQ s z#MSDDLCompiler.visit_create_sequencec K sT d}|j d us|jd urP|j d u r&dn|j }|jd u r:dn|j}|d||f 7 }|S )Nz IDENTITYr z(%s,%s)r )r� r� r� r r r r� r� r� �visit_identity_column s z#MSDDLCompiler.visit_identity_column)F)r� r� r� r' r6 r7 r< r= rA rJ rL rM rN rQ rR r� r� r� r� r� r s ? < r c s: e Zd ZeZ� fdd�Zdd� Zdd� Zd dd �Z� Z S ) �MSIdentifierPreparerc s t � j|dddd� d S )N�[�]F)Z initial_quoteZ final_quoteZ quote_case_sensitive_collations)r� r� )r� r� r� r� r� r� s �z MSIdentifierPreparer.__init__c C s |� dd�S )NrU �]]r �r� r� r� r� r� �_escape_identifier s z'MSIdentifierPreparer._escape_identifierc C s |� dd�S )NrV rU r rW r� r� r� �_unescape_identifier# s z)MSIdentifierPreparer._unescape_identifierNc C sX |durt jddd� t|�\}}|r@d| �|�| �|�f }n|rP| �|�}nd}|S )z'Prepare a quoted table and schema name.Nz�The IdentifierPreparer.quote_schema.force parameter is deprecated and will be removed in a future release. This flag has no effect on the behavior of the IdentifierPreparer.quote method; please refer to quoted_name().z1.3)�versionz%s.%sr )r r& �_schema_elementsr1 )r� r �force�dbname�owner�resultr� r� r� rG & s � z!MSIdentifierPreparer.quote_schema)N) r� r� r� �RESERVED_WORDSZreserved_wordsr� rX rY rG r� r� r� r� r� rS s rS c s d� fdd� }t |� �S )Nc s, t | |�\}}t||� | ||||fi |��S r� ��_owner_plus_db� _switch_db)r� � connectionr r� r] r^ r� r� r� �wrapB s � �z$_db_plus_owner_listing.<locals>.wrap)Nr1 �r� re r� r� r� �_db_plus_owner_listingA s rg c s d� fdd� }t |� �S )Nc s. t | |�\}}t||� | |||||f i |��S r� ra )r� rd � tablenamer r� r] r^ r� r� r� re T s � �z _db_plus_owner.<locals>.wrap)Nr1 rf r� r� r� �_db_plus_ownerS s ri c O s� | r2|� d��� }|| kr2|� d|jj�| � � z6||i |��W | rf|| krf|� d|jj�|� � S n&| r�|| kr�|� d|jj�|� � 0 d S )Nzselect db_name()zuse %s)�exec_driver_sql�scalarr� r� r1 )r] rd r� r� r� Z current_dbr� r� r� rc f s6 � ��� � �� ��rc c C s |sd | j fS t|�S d S r� )rD r[ )r� r r� r� r� rb w s rb c C sb t | t�r| jrd | fS | tv r(t| S | �d�r:d | fS g }d}d}d}t�d| �D ]f}|s`qV|dkrrd}d}qV|dkr�d}qV|s�|dkr�|r�|�d | � n |�|� d}d}qV||7 }qV|r�|�|� t|�d k�r,d� |d d � �|d }}t� d |d d � ��rt|dd�}n|� d�� d�}n"t|��rFd |d }}nd\}}||ft| < ||fS )Nz __[SCHEMA_r Fz (\[|\]|\.)rT TrU �.z[%s]r r ���z .*\].*\[.*�r1 )NN) r� r r1 �_memoized_schema� startswithr� �split�appendr3 r_ r� �lstrip�rstrip)r �push�symbolZbracketZ has_brackets�tokenr] r^ r� r� r� r[ � sJ r[ c s� e Zd ZdZdZdZdZdZdZdZ dZ e Z dZ dZdZdZdZdZdZdZejeejeejeejjeejj e ej e ej e ej!e"e#e#e$e$e%e%e&e&ej'e(i Z)e*j+j,�-de.j/i�Z,e0Z0dZ1dZ2dZ3dZ4dZ5dZ6dZ7dZ8dZ9dZ:e;j<e;j=B e;j>B Z?dZ@dZAdZBdZCd ZDeEZFeGZHeIZJeKZLeMjNd d ifeMjOd d ifeMjPd d d d d �feMjQd d d �fgZRdG� fdd� ZS� fdd�ZTdd� ZU� fdd�ZVh d�ZWdd� ZXdd� ZYdd � ZZ� fd d �Z[d d � Z\d!d"� Z]d#d$� Z^d%d&� Z_e`d'd(� �Zaebjce`d)d*� ��Zdebjceed+d,� ��Zfebjcd-d.� �Zgebjceed/d0� ��Zhebjceed1d2� ��Ziebjcd3d4� �Zjd5d6� Zkebjce`d7d8� ��Zlebjce`d9d:� ��ZmebjcdHd;d<��Znd=d>� Zod?d@� Zpebjce`dAdB� ��Zqebjce`dCdD� ��Zrebjce`dEdF� ��Zs� ZtS )Ir] r TF� �dbor� r i3 r� rs N)rs r/ rU r* )r r c sz t |pd�| _|| _|| _|| _| | _| | _} | d ur>| | _|d urXt� dd� || _ t � j f i | �� || _ || _d S )Nr z[The legacy_schema_aliasing parameter is deprecated and will be removed in a future release.r )r� � query_timeoutrI rp r@ �!ignore_no_transaction_on_rollback� _user_defined_supports_comments�supports_commentsr r& r� r� r� Z_json_serializerZ_json_deserializer) r� rz rp rI r@ r} Zjson_serializerZjson_deserializerr� r{ �optsZudsr� r� r� r� / s$ � �zMSDialect.__init__c s |� d� t� �||� d S )Nz$IF @@TRANCOUNT = 0 BEGIN TRANSACTION)rj r� � do_savepoint�r� rd r� r� r� r� r U s zMSDialect.do_savepointc C s d S r� r� r� r� r� r� �do_release_savepointZ s z MSDialect.do_release_savepointc sb zt � �|� W nL | jjy\ } z0| jrFt�dt|��rFt� d� n� W Y d }~n d }~0 0 d S )Nz .*\b111214\bz|ProgrammingError 111214 'No corresponding transaction found.' has been suppressed via ignore_no_transaction_on_rollback=True) r� � do_rollback�dbapiZProgrammingErrorr{ r� r� r� r �warn)r� �dbapi_connectionry r� r� r� r� ^ s ��zMSDialect.do_rollback> Z SERIALIZABLEzREAD COMMITTED�SNAPSHOTzREAD UNCOMMITTEDzREPEATABLE READc C s t | j�S r� )�list�_isolation_lookup)r� r� r� r� r� �get_isolation_level_valuesv s z$MSDialect.get_isolation_level_valuesc C s4 |� � }|�d|� �� |�� |dkr0|�� d S )Nz SET TRANSACTION ISOLATION LEVEL r� )r r] r� rL )r� r� �levelr r� r� r� �set_isolation_levely s z MSDialect.set_isolation_levelc C s� |� � }d}z�zF|�d�|�� |�� }|s4td��d|d � �}|�d�|�� W n: | jjy� } z td�||��|�W Y d }~n(d }~0 0 |�� }|d �� W |�� S W |�� n |�� 0 d S )Nzsys.system_viewszTSELECT name FROM {} WHERE name IN ('dm_exec_sessions', 'dm_pdw_nodes_exec_sessions')zBCan't fetch isolation level on this particular SQL Server version.zsys.r a� SELECT CASE transaction_isolation_level WHEN 0 THEN NULL WHEN 1 THEN 'READ UNCOMMITTED' WHEN 2 THEN 'READ COMMITTED' WHEN 3 THEN 'REPEATABLE READ' WHEN 4 THEN 'SERIALIZABLE' WHEN 5 THEN 'SNAPSHOT' END AS TRANSACTION_ISOLATION_LEVEL FROM {} where session_id = @@SPID zZCan't fetch isolation level; encountered error {} when attempting to query the "{}" view.) r r] rE Zfetchone�NotImplementedErrorr� �Error�upperr� )r� r� r Z view_nameru �errr� r� r� �get_isolation_level� sB ���� ����� �z MSDialect.get_isolation_levelc s, t � �|� | �� | �|� | �|� d S r� )r� � initialize�_setup_version_attributes� _setup_supports_nvarchar_max�_setup_supports_comments�r� rd r� r� r� r� � s zMSDialect.initializec C s� | j d ttdd��vr8t�dd�dd� | j D �� � | j tkrJd| _nd | _| jd u rf| j t k| _| j ox| j d d k| _ d S ) Nr r< � z[Unrecognized server version info '%s'. Some SQL Server features may not function properly.rl c s s | ]}t |�V qd S r� )r� r� r� r� r� r� � r� z6MSDialect._setup_version_attributes.<locals>.<genexpr>TFr9 ) rK r� �ranger r� r_ rL �supports_multivalues_insertr@ �MS_2012_VERSIONr� r� r� r� r� r� � s �� ��z#MSDialect._setup_version_attributesc C s: z|� t�d�� W n tjy. d| _Y n0 d| _d S )Nz0SELECT CAST('test max support' AS NVARCHAR(max))FT)rk r r r � DBAPIError�_supports_nvarchar_maxr� r� r� r� r� � s � z&MSDialect._setup_supports_nvarchar_maxc C sH | j d urd S z|�t�d�� W n tjy< d| _Y n0 d| _d S )NzdSELECT 1 FROM fn_listextendedproperty(default, default, default, default, default, default, default)FT)r| rk r r r r� r} r� r� r� r� r� � s �� z"MSDialect._setup_supports_commentsc C s2 t �d�}|�|�}|d ur(t|dd�S | jS d S )NzSELECT schema_name()Trn )r r rk r rI )r� rd �queryrD r� r� r� �_get_default_schema_name� s z"MSDialect._get_default_schema_namec K s | � |� | j|||fi |��S r� )Z _ensure_has_table_connection�_internal_has_table)r� rd rh r] r^ r r� r� r� r� � has_table� s zMSDialect.has_tablec K sN t j}t�|jj��|jj|k�}|r8|�|jj|k�}|�|�} | � � d uS r� ) �ischema� sequencesr r� r* � sequence_namerU �sequence_schemar] �first) r� rd Z sequencenamer] r^ r r� r� r� r* r� r� r� � has_sequence� s � zMSDialect.has_sequencec K sB t j}t�|jj�}|r*|�|jj|k�}|�|�}dd� |D �S )Nc S s g | ] }|d �qS r� r� )r� ru r� r� r� r� r� z0MSDialect.get_sequence_names.<locals>.<listcomp>) r� r� r r� r* r� rU r� r] ) r� rd r] r^ r r� r� r� r* r� r� r� �get_sequence_names s z MSDialect.get_sequence_namesc K s4 t �tjjj��tjjj�}dd� |�|�D �}|S )Nc S s g | ] }|d �qS r� r� �r� �rr� r� r� r� r� z.MSDialect.get_schema_names.<locals>.<listcomp>)r r� r� Zschematar* rI r� r] )r� rd r� r� Z schema_namesr� r� r� �get_schema_names s �zMSDialect.get_schema_namesc K sT t j}t�|jj��t�|jj|k|jj dk��� |jj�}dd� |� |�D �}|S )N� BASE TABLEc S s g | ] }|d �qS r� r� r� r� r� r� r� * r� z-MSDialect.get_table_names.<locals>.<listcomp>� r� �tablesr r� r* � table_namerU �and_� table_schema� table_typer� r] ) r� rd r] r^ r r� r� r� Z table_namesr� r� r� �get_table_names s ���� zMSDialect.get_table_namesc K sT t j}t�|jj��t�|jj|k|jj dk��� |jj�}dd� |� |�D �}|S )N�VIEWc S s g | ] }|d �qS r� r� r� r� r� r� r� ; r� z,MSDialect.get_view_names.<locals>.<listcomp>r� ) r� rd r] r^ r r� r� r� Z view_namesr� r� r� �get_view_names- s ���� zMSDialect.get_view_namesc K s� |� d�r*t|�td�dd|� d�i��S tj}t�|jj �� t� t� |jj dk|jj dk�|jj |k��}|r�|� |jj|k�}|�|�}|�� d uS d S )N�#z"SELECT object_id(:table_name, 'U')r� z tempdb.dbo.[rU r� r� )rp r rk r r� r� r r� r* r� rU r� �or_r� r� r] r� )r� rd rh r^ r� r� r� r* r� r� r� r� > s* �� � �� z MSDialect._internal_has_tablec K s4 | j |||fi |��r |� S t�|� d|� ���d S )Nrl )r� r �NoSuchTableError)r� rd rh r^ �methodr� r� r� r� �_default_or_error^ s zMSDialect._default_or_errorc K s | j tkrdnd}|jdd��t�d|� d���t�d|t� � �t�d|t� � ��j t � � d ��}i } |� � D ]�} | d | d d kg g i d � | | d < } | d } | d } | dv r�| d k| d< | dv r�| dk| d< d| d< | d d urn| d | d< qn|jdd��t�d��t�d|t� � �t�d|t� � ��j t � � d ��}|� � D ]�} | d | v�rZ�qD| | d }|d �d�}|d �d�}|�r�|�sD| d �r�|�s�|d �| d � n|d �| d � �qD| �� D ]}|d |d d < �q�| �r�t| �� �S | j|||tjfi |��S d S ) Nzind.filter_definitionzNULL as filter_definitionT�Z future_resultzM select ind.index_id, ind.is_unique, ind.name, ind.type, a+ from sys.indexes as ind join sys.tables as tab on ind.object_id = tab.object_id join sys.schemas as sch on sch.schema_id = tab.schema_id where tab.name = :tabname and sch.name = :schname and ind.is_primary_key = 0 and ind.type != 0 order by ind.name Ztabname�schname)r� r� Z is_uniquer )r� r{ � column_names�include_columnsr% Zindex_idr% r� > r � �mssql_clustered> � � r� Zmssql_columnstore�filter_definitionZ mssql_wherea� select ind_col.index_id, col.name, ind_col.is_included_column from sys.columns as col join sys.tables as tab on tab.object_id = col.object_id join sys.index_columns as ind_col on ind_col.column_id = col.column_id and ind_col.object_id = tab.object_id join sys.schemas as sch on sch.schema_id = tab.schema_id where tab.name = :tabname and sch.name = :schname Zis_included_columnr� r� Z mssql_include)rK rL �execution_optionsr] r r � bindparams� bindparamr� � CoerceUnicoder� r �Unicode�mappingsr� rr r� r� r� r �indexes)r� rd rh r] r^ r r� r� �rpr� ru r� �doZ index_typeZ index_defZ is_colstore� is_clustered� index_infor� r� r� � get_indexese s� �� ����� � ���� � ��zMSDialect.get_indexesc K sX |� t�d��t�d|t�� �t�d|t�� ����� }|r@|S t� |� d|� ���d S )Nz�select mod.definition from sys.sql_modules as mod join sys.views as views on mod.object_id = views.object_id join sys.schemas as sch on views.schema_id = sch.schema_id where views.name=:viewname and sch.name=:schname�viewnamer� rl ) r] r r r� r� r� r� rk r r� )r� rd r� r] r^ r r� Zview_defr� r� r� �get_view_definition� s ��� z MSDialect.get_view_definitionc K s� | j std��|r|n| j}d}|�t�|��t�d|t� � �t�d|t� � ���� � }|rdd|iS | j ||d t j fi |��S d S )Nz=Can't get table comments on current SQL Server version in usez� SELECT cast(com.value as nvarchar(max)) FROM fn_listextendedproperty('MS_Description', 'schema', :schema, 'table', :table, NULL, NULL ) as com; r r~ r )r} r� rD r] r r r� r� r� r� rk r� r Z table_comment)r� rd r� r r� rI Z COMMENT_SQLrF r� r� r� �get_table_comment� s, � ����zMSDialect.get_table_commentc C s ||� d�sdnd S )Nz##z [_][_][_]%r )rp )r� rh r� r� r� � _temp_table_name_like_pattern s �z'MSDialect._temp_table_name_like_patternc C s� z"|� t�d�d| �|�i��� W S tjyX } z t�d| �|�W Y d }~n>d }~0 tjy� } z t� d| �|�W Y d }~n d }~0 0 d S )Nz_select table_schema, table_name from tempdb.information_schema.tables where table_name like :p1�p1z�Found more than one temporary table named '%s' in tempdb at this time. Cannot reliably resolve that name to its internal table name.z6Unable to find a temporary table named '%s' in tempdb.) r] r r r� Zoner ZMultipleResultsFoundZUnreflectableTableErrorZ NoResultFoundr� )r� rd rh �me�ner� r� r� � _get_internal_temp_table_name s. � � ������z'MSDialect._get_internal_temp_table_namec & K s0 |� d�}|r&| �||�\}}tj}ntj}tj} tj} |rnt�|j j |k|j j |k�} |j j d |j j } n|j j |k} |j j } | j r�| j j } nt�| j j td��} t�| �}t�|j j|j j|j j|j j|j j|j j|j j|j j| | j j| j j | j j | j j tj j j �!d���"|�j#| t�| j j|k| j j$|j j�%d�k�d�j#| t�| j j|k| j j$|j j�%d�k�d�j#tj t�tj j d dktj j j&|ktj j j'|j j(ktj j j$d k�d��)| ��*|j j(�}|j+d d ��,|�}g }|�-� D �]"}||j j }||j j }||j j d k}||j j }||j j }||j j }||j j }||j j }|| }|| j j } || j j } || j j } || j j } |tj j j } | j.�/|d �}!i }"|!t0t1t2t3t4t5t6t7t8j9f v �r�|d k�r�d }||"d< |�r�||"d< |!d u �r t:�;d||f � t8j<}!n:t=|!t8j>��r6||"d< t=|!t8j?��s6||"d< |!f i |"��}!||!||| d u| d�}#|d u�r|| d u�r||| d�|#d< | d u�r�| d u �s�| d u �r�i |#d< nVt@|!t8jA��r�tB| �}$tB| �}%n(t@|!t8jC��r�tB| �}$tB| �}%n| }$| }%|$|%d�|#d< |�D|#� �q�|�r|S | jE|||tFjfi |��S d S )Nr� rl i� rF ZDATABASE_DEFAULT)Zonclause�classr ZMS_DescriptionTr� ZYESrm r r& z*Did not recognize type '%s' of column '%s'rj r )r� r� r# r r$ rF )r> r? r" r� r )Grp r� r� Zmssql_temp_table_columnsr� Zcomputed_columnsZidentity_columnsr r� r* r� r� r� � definition�castr- r � object_idr� � column_namerP Z is_nullableZcharacter_maximum_lengthZnumeric_precisionZ numeric_scaleZcolumn_defaultZcollation_name� is_persisted� is_identityZ seed_valueZincrement_valueZextended_propertiesr� r� � select_fromZ outerjoinr� r[ Zmajor_idZminor_id�ordinal_positionrU r� r� r] r� � ischema_namesr� �MSString�MSChar� MSNVarchar�MSNChar�MSText�MSNText�MSBinary� MSVarBinaryr � LargeBinaryr r� ZNULLTYPEr r r r� Z BigIntegerr� r rr r� r )&r� rd rh r] r^ r r� Z is_temp_tabler� Z computed_colsZ identity_colsr5 Z full_nameZcomputed_definitionr� r� r* r� ru r� r- r# ZcharlenZ numericprecZ numericscaler r& r� r� r� r r rF r� r� Zcdictr r r� r� r� � get_columns0 s0 � � � �� ��� ���" � ��+�,��0 � ��� � � ��zMSDialect.get_columnsc K sB g }t j}t j�d�} t�| jj|jj| jj t � t � | jj d | jj �d��d���t�|jj | jj k|jj | jj k| jj|k| jj |k���|jj | jj�} |jdd��| �} d } d } | �� D ]J}d||jjj v r�|�|d � | d u r�|| jj j } | d u r�|d } q�|�r$|| d | id �S | j|||tjfi |��S d S ) N�Crl ZCnstIsClustKeyr� Tr� ZPRIMARYZ COLUMN_NAMEr� )�constrained_columnsr� r% ) r� � constraintsZkey_constraintsr� r r� r* r� Zconstraint_type�constraint_namer Zobjectpropertyr� r� r� rU r� r� r� r� r� r] r� r� rr r� r Z pk_constraint)r� rd rh r] r^ r r� ZpkeysZTCr� r� r* r� r� ru r� r� r� �get_pk_constraint� sb ���� �� �� ���zMSDialect.get_pk_constraintc K sh t d��t�d|t�� �t�d|t�� ��jt�� t�� t�� t�� t�� t�� t�� t�� d�}t � dd� �}|� |�� � D ]�} | \ } } } } } }}} }}|| }| |d< |dkr�||d d < |dkr�||d d < |d �s||d < |d us�|| k�r|�r|d | } | |d< |d |d }}|� | � |� |� q~|�rJt|�� �S | j|||tjfi |��S d S )Na> WITH fk_info AS ( SELECT ischema_ref_con.constraint_schema, ischema_ref_con.constraint_name, ischema_key_col.ordinal_position, ischema_key_col.table_schema, ischema_key_col.table_name, ischema_ref_con.unique_constraint_schema, ischema_ref_con.unique_constraint_name, ischema_ref_con.match_option, ischema_ref_con.update_rule, ischema_ref_con.delete_rule, ischema_key_col.column_name AS constrained_column FROM INFORMATION_SCHEMA.REFERENTIAL_CONSTRAINTS ischema_ref_con INNER JOIN INFORMATION_SCHEMA.KEY_COLUMN_USAGE ischema_key_col ON ischema_key_col.table_schema = ischema_ref_con.constraint_schema AND ischema_key_col.constraint_name = ischema_ref_con.constraint_name WHERE ischema_key_col.table_name = :tablename AND ischema_key_col.table_schema = :owner ), constraint_info AS ( SELECT ischema_key_col.constraint_schema, ischema_key_col.constraint_name, ischema_key_col.ordinal_position, ischema_key_col.table_schema, ischema_key_col.table_name, ischema_key_col.column_name FROM INFORMATION_SCHEMA.KEY_COLUMN_USAGE ischema_key_col ), index_info AS ( SELECT sys.schemas.name AS index_schema, sys.indexes.name AS index_name, sys.index_columns.key_ordinal AS ordinal_position, sys.schemas.name AS table_schema, sys.objects.name AS table_name, sys.columns.name AS column_name FROM sys.indexes INNER JOIN sys.objects ON sys.objects.object_id = sys.indexes.object_id INNER JOIN sys.schemas ON sys.schemas.schema_id = sys.objects.schema_id INNER JOIN sys.index_columns ON sys.index_columns.object_id = sys.objects.object_id AND sys.index_columns.index_id = sys.indexes.index_id INNER JOIN sys.columns ON sys.columns.object_id = sys.indexes.object_id AND sys.columns.column_id = sys.index_columns.column_id ) SELECT fk_info.constraint_schema, fk_info.constraint_name, fk_info.ordinal_position, fk_info.constrained_column, constraint_info.table_schema AS referred_table_schema, constraint_info.table_name AS referred_table_name, constraint_info.column_name AS referred_column, fk_info.match_option, fk_info.update_rule, fk_info.delete_rule FROM fk_info INNER JOIN constraint_info ON constraint_info.constraint_schema = fk_info.unique_constraint_schema AND constraint_info.constraint_name = fk_info.unique_constraint_name AND constraint_info.ordinal_position = fk_info.ordinal_position UNION SELECT fk_info.constraint_schema, fk_info.constraint_name, fk_info.ordinal_position, fk_info.constrained_column, index_info.table_schema AS referred_table_schema, index_info.table_name AS referred_table_name, index_info.column_name AS referred_column, fk_info.match_option, fk_info.update_rule, fk_info.delete_rule FROM fk_info INNER JOIN index_info ON index_info.index_schema = fk_info.unique_constraint_schema AND index_info.index_name = fk_info.unique_constraint_name AND index_info.ordinal_position = fk_info.ordinal_position ORDER BY fk_info.constraint_schema, fk_info.constraint_name, fk_info.ordinal_position rh r^ )Zconstraint_schemar� r� r� Zconstrained_columnZreferred_table_schemaZreferred_table_nameZreferred_columnc S s d g d d g i d�S )N)r� r� �referred_schema�referred_table�referred_columns�optionsr� r� r� r� r� �<lambda>� s �z,MSDialect.get_foreign_keys.<locals>.<lambda>r� z NO ACTIONr� ZonupdateZondeleter� rl r� r� r� )r r� r r� r� r� r� r r� r � defaultdictr] r� rr r� r� r� r Z foreign_keys)r� rd rh r] r^ r r� r� Zfkeysr� �_ZrfknmZscolZrschemaZrtblZrcolZfkupruleZ fkdelruleZrecZ local_colsZ remote_colsr� r� r� �get_foreign_keys sv �f�j��w� � � ��zMSDialect.get_foreign_keys) NTry NNNNNF)N)ur� r� r� r� Zsupports_statement_cacheZsupports_default_valuesZsupports_empty_insertZ favor_returning_over_lastrowidZreturns_native_bytesr} Zsupports_default_metavaluer\ Zexecution_ctx_clsrp Zmax_identifier_lengthrI Zinsert_returningZupdate_returningZdelete_returningZupdate_returning_multifromZdelete_returning_multifromr �DateTimer� �Dater� r r r ZTimer� r� r� � UnicodeTextr� r� r� r� r' �Uuidr Zcolspecsr �DefaultDialectZengine_config_typesr= r Zasboolr� Zsupports_sequencesZsequences_optionalZdefault_sequence_baseZsupports_native_booleanZ#non_native_boolean_check_constraintZsupports_unicode_bindsZpostfetch_lastrowidr� Zuse_insertmanyvaluesZ!use_insertmanyvalues_wo_returningr! Z AUTOINCREMENTZIDENTITYZUSE_INSERT_FROM_SELECTZ"insertmanyvalues_implicit_sentinelZ insertmanyvalues_max_parametersr� r� r� rK r� Zstatement_compilerr Z ddl_compilerr% Ztype_compiler_clsrS r_ r~ ZPrimaryKeyConstraintZUniqueConstraint�Indexr Zconstruct_argumentsr� r r� r� r� r� r� r� r� r� r� r� r� ri r� r �cacher� rg r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r] � s ����� �� �� �& . p 3 7r] )�r� � __future__r r� r� r� r� �typingr r �uuidr Z _python_UUIDr r r� �jsonr r r r r r r~ r r r r Zenginer rr r r Zengine.reflectionr r r r r r r r r r r� Z sql._typingr Z sql.compilerr! Z sql.elementsr" �typesr# r$ r% r& r' r( r) r* r+ r, r- r. r/ r0 r2 Z util.typingr3 Zsql.dmlr4 Zsql.selectabler5 ZMS_2017_VERSIONZMS_2016_VERSIONZMS_2014_VERSIONr� rL ZMS_2005_VERSIONZMS_2000_VERSIONr` r� r� r r� r� r� r� Z_MSTimer� r� r� r� r� r� r� r� r� r� r� r� Z_Binaryr� r r r r� r �Textr r r Z TypeEnginer r r� r Z _UUID_RETURNr r Z MSDateTimeZMSDateZMSRealZ MSTinyIntegerZMSTimeZMSSmallDateTimeZ MSDateTime2ZMSDateTimeOffsetr� r� r� r� r� r� r� r� ZMSImageZMSBitZMSMoneyZ MSSmallMoneyZMSUniqueIdentifierZ MSVariantr� ZGenericTypeCompilerr% ZDefaultExecutionContextr\ r r� r Z DDLCompilerr ZIdentifierPreparerrS rg ri rc rb ZLRUCachero r[ r� r] r� r� r� r� �<module> sZ S 9 * 0( 0 �# & , ,: sqlalchemy/dialects/mssql/__pycache__/__init__.cpython-39.pyc 0000644 00000003022 15125143220 0020225 0 ustar 00 a ��JhX � @ s� d dl mZ d dl mZ d dl mZ d dl mZ d dlmZ d dlmZ d dlmZ d dlmZ d d lm Z d d lm Z d d lm Z d d lm Z d d lm Z d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d d lm Z d d lm Z d d lm Z d d lm Z d d lm Z d d!lm!Z! d d"lm"Z" d d#lm#Z# d d$lm$Z$ d d%lm%Z% d&d'l&m'Z' ej( e_(Z(d(Z)d)S )*� )�aioodbc)�base)�pymssql)�pyodbc)�BIGINT)�BINARY)�BIT)�CHAR)�DATE)�DATETIME)� DATETIME2)�DATETIMEOFFSET)�DECIMAL)�DOUBLE_PRECISION)�FLOAT)�IMAGE)�INTEGER)�JSON)�MONEY)�NCHAR)�NTEXT)�NUMERIC)�NVARCHAR)�REAL)� ROWVERSION)� SMALLDATETIME)�SMALLINT)� SMALLMONEY)� SQL_VARIANT)�TEXT)�TIME)� TIMESTAMP)�TINYINT)�UNIQUEIDENTIFIER)� VARBINARY)�VARCHAR)�XML� )�try_cast)#r r r r r" r% r r r r r r r r r r r r r r r r r$ r r r r! r r r r# r r& �dialectr( N)*� r r r r r r r r r r r r r r r r r r r r r r r r r r r r r r r r! r" r# r$ r% r& Zsqlr( r) �__all__� r, r, �W/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mssql/__init__.py�<module> sN sqlalchemy/dialects/mssql/__pycache__/pyodbc.cpython-39.pyc 0000644 00000062522 15125143220 0017760 0 ustar 00 a ��Jh%j � @ s d Z ddlZddlZddlZddlZddlmZ ddlmZ ddlmZ ddlm Z ddlm Z dd lm Z dd lm Z dd lm Z dd lmZ dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddl m Z G dd� d�Z G dd� de ej �Z!G dd� de ej"�Z#G dd � d �Z$G d d � d �Z%G d d � d e%e�Z&G d!d"� d"e%e �Z'G d#d$� d$e$e �Z(G d%d&� d&e$e �Z)G d'd(� d(ej*�Z+G d)d*� d*e�Z,G d+d,� d,e�Z-G d-d.� d.e�Z.G d/d0� d0e�Z/G d1d2� d2e�Z0G d3d4� d4e �Z1G d5d6� d6ee �Z2e2Z3dS )7a�6 .. dialect:: mssql+pyodbc :name: PyODBC :dbapi: pyodbc :connectstring: mssql+pyodbc://<username>:<password>@<dsnname> :url: https://pypi.org/project/pyodbc/ Connecting to PyODBC -------------------- The URL here is to be translated to PyODBC connection strings, as detailed in `ConnectionStrings <https://code.google.com/p/pyodbc/wiki/ConnectionStrings>`_. DSN Connections ^^^^^^^^^^^^^^^ A DSN connection in ODBC means that a pre-existing ODBC datasource is configured on the client machine. The application then specifies the name of this datasource, which encompasses details such as the specific ODBC driver in use as well as the network address of the database. Assuming a datasource is configured on the client, a basic DSN-based connection looks like:: engine = create_engine("mssql+pyodbc://scott:tiger@some_dsn") Which above, will pass the following connection string to PyODBC: .. sourcecode:: text DSN=some_dsn;UID=scott;PWD=tiger If the username and password are omitted, the DSN form will also add the ``Trusted_Connection=yes`` directive to the ODBC string. Hostname Connections ^^^^^^^^^^^^^^^^^^^^ Hostname-based connections are also supported by pyodbc. These are often easier to use than a DSN and have the additional advantage that the specific database name to connect towards may be specified locally in the URL, rather than it being fixed as part of a datasource configuration. When using a hostname connection, the driver name must also be specified in the query parameters of the URL. As these names usually have spaces in them, the name must be URL encoded which means using plus signs for spaces:: engine = create_engine( "mssql+pyodbc://scott:tiger@myhost:port/databasename?driver=ODBC+Driver+17+for+SQL+Server" ) The ``driver`` keyword is significant to the pyodbc dialect and must be specified in lowercase. Any other names passed in the query string are passed through in the pyodbc connect string, such as ``authentication``, ``TrustServerCertificate``, etc. Multiple keyword arguments must be separated by an ampersand (``&``); these will be translated to semicolons when the pyodbc connect string is generated internally:: e = create_engine( "mssql+pyodbc://scott:tiger@mssql2017:1433/test?" "driver=ODBC+Driver+18+for+SQL+Server&TrustServerCertificate=yes" "&authentication=ActiveDirectoryIntegrated" ) The equivalent URL can be constructed using :class:`_sa.engine.URL`:: from sqlalchemy.engine import URL connection_url = URL.create( "mssql+pyodbc", username="scott", password="tiger", host="mssql2017", port=1433, database="test", query={ "driver": "ODBC Driver 18 for SQL Server", "TrustServerCertificate": "yes", "authentication": "ActiveDirectoryIntegrated", }, ) Pass through exact Pyodbc string ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A PyODBC connection string can also be sent in pyodbc's format directly, as specified in `the PyODBC documentation <https://github.com/mkleehammer/pyodbc/wiki/Connecting-to-databases>`_, using the parameter ``odbc_connect``. A :class:`_sa.engine.URL` object can help make this easier:: from sqlalchemy.engine import URL connection_string = "DRIVER={SQL Server Native Client 10.0};SERVER=dagger;DATABASE=test;UID=user;PWD=password" connection_url = URL.create( "mssql+pyodbc", query={"odbc_connect": connection_string} ) engine = create_engine(connection_url) .. _mssql_pyodbc_access_tokens: Connecting to databases with access tokens ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Some database servers are set up to only accept access tokens for login. For example, SQL Server allows the use of Azure Active Directory tokens to connect to databases. This requires creating a credential object using the ``azure-identity`` library. More information about the authentication step can be found in `Microsoft's documentation <https://docs.microsoft.com/en-us/azure/developer/python/azure-sdk-authenticate?tabs=bash>`_. After getting an engine, the credentials need to be sent to ``pyodbc.connect`` each time a connection is requested. One way to do this is to set up an event listener on the engine that adds the credential token to the dialect's connect call. This is discussed more generally in :ref:`engines_dynamic_tokens`. For SQL Server in particular, this is passed as an ODBC connection attribute with a data structure `described by Microsoft <https://docs.microsoft.com/en-us/sql/connect/odbc/using-azure-active-directory#authenticating-with-an-access-token>`_. The following code snippet will create an engine that connects to an Azure SQL database using Azure credentials:: import struct from sqlalchemy import create_engine, event from sqlalchemy.engine.url import URL from azure import identity # Connection option for access tokens, as defined in msodbcsql.h SQL_COPT_SS_ACCESS_TOKEN = 1256 TOKEN_URL = "https://database.windows.net/" # The token URL for any Azure SQL database connection_string = "mssql+pyodbc://@my-server.database.windows.net/myDb?driver=ODBC+Driver+17+for+SQL+Server" engine = create_engine(connection_string) azure_credentials = identity.DefaultAzureCredential() @event.listens_for(engine, "do_connect") def provide_token(dialect, conn_rec, cargs, cparams): # remove the "Trusted_Connection" parameter that SQLAlchemy adds cargs[0] = cargs[0].replace(";Trusted_Connection=Yes", "") # create token credential raw_token = azure_credentials.get_token(TOKEN_URL).token.encode( "utf-16-le" ) token_struct = struct.pack( f"<I{len(raw_token)}s", len(raw_token), raw_token ) # apply it to keyword arguments cparams["attrs_before"] = {SQL_COPT_SS_ACCESS_TOKEN: token_struct} .. tip:: The ``Trusted_Connection`` token is currently added by the SQLAlchemy pyodbc dialect when no username or password is present. This needs to be removed per Microsoft's `documentation for Azure access tokens <https://docs.microsoft.com/en-us/sql/connect/odbc/using-azure-active-directory#authenticating-with-an-access-token>`_, stating that a connection string when using an access token must not contain ``UID``, ``PWD``, ``Authentication`` or ``Trusted_Connection`` parameters. .. _azure_synapse_ignore_no_transaction_on_rollback: Avoiding transaction-related exceptions on Azure Synapse Analytics ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Azure Synapse Analytics has a significant difference in its transaction handling compared to plain SQL Server; in some cases an error within a Synapse transaction can cause it to be arbitrarily terminated on the server side, which then causes the DBAPI ``.rollback()`` method (as well as ``.commit()``) to fail. The issue prevents the usual DBAPI contract of allowing ``.rollback()`` to pass silently if no transaction is present as the driver does not expect this condition. The symptom of this failure is an exception with a message resembling 'No corresponding transaction found. (111214)' when attempting to emit a ``.rollback()`` after an operation had a failure of some kind. This specific case can be handled by passing ``ignore_no_transaction_on_rollback=True`` to the SQL Server dialect via the :func:`_sa.create_engine` function as follows:: engine = create_engine( connection_url, ignore_no_transaction_on_rollback=True ) Using the above parameter, the dialect will catch ``ProgrammingError`` exceptions raised during ``connection.rollback()`` and emit a warning if the error message contains code ``111214``, however will not raise an exception. .. versionadded:: 1.4.40 Added the ``ignore_no_transaction_on_rollback=True`` parameter. Enable autocommit for Azure SQL Data Warehouse (DW) connections ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Azure SQL Data Warehouse does not support transactions, and that can cause problems with SQLAlchemy's "autobegin" (and implicit commit/rollback) behavior. We can avoid these problems by enabling autocommit at both the pyodbc and engine levels:: connection_url = sa.engine.URL.create( "mssql+pyodbc", username="scott", password="tiger", host="dw.azure.example.com", database="mydb", query={ "driver": "ODBC Driver 17 for SQL Server", "autocommit": "True", }, ) engine = create_engine(connection_url).execution_options( isolation_level="AUTOCOMMIT" ) Avoiding sending large string parameters as TEXT/NTEXT ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ By default, for historical reasons, Microsoft's ODBC drivers for SQL Server send long string parameters (greater than 4000 SBCS characters or 2000 Unicode characters) as TEXT/NTEXT values. TEXT and NTEXT have been deprecated for many years and are starting to cause compatibility issues with newer versions of SQL_Server/Azure. For example, see `this issue <https://github.com/mkleehammer/pyodbc/issues/835>`_. Starting with ODBC Driver 18 for SQL Server we can override the legacy behavior and pass long strings as varchar(max)/nvarchar(max) using the ``LongAsMax=Yes`` connection string parameter:: connection_url = sa.engine.URL.create( "mssql+pyodbc", username="scott", password="tiger", host="mssqlserver.example.com", database="mydb", query={ "driver": "ODBC Driver 18 for SQL Server", "LongAsMax": "Yes", }, ) Pyodbc Pooling / connection close behavior ------------------------------------------ PyODBC uses internal `pooling <https://github.com/mkleehammer/pyodbc/wiki/The-pyodbc-Module#pooling>`_ by default, which means connections will be longer lived than they are within SQLAlchemy itself. As SQLAlchemy has its own pooling behavior, it is often preferable to disable this behavior. This behavior can only be disabled globally at the PyODBC module level, **before** any connections are made:: import pyodbc pyodbc.pooling = False # don't use the engine before pooling is set to False engine = create_engine("mssql+pyodbc://user:pass@dsn") If this variable is left at its default value of ``True``, **the application will continue to maintain active database connections**, even when the SQLAlchemy engine itself fully discards a connection or if the engine is disposed. .. seealso:: `pooling <https://github.com/mkleehammer/pyodbc/wiki/The-pyodbc-Module#pooling>`_ - in the PyODBC documentation. Driver / Unicode Support ------------------------- PyODBC works best with Microsoft ODBC drivers, particularly in the area of Unicode support on both Python 2 and Python 3. Using the FreeTDS ODBC drivers on Linux or OSX with PyODBC is **not** recommended; there have been historically many Unicode-related issues in this area, including before Microsoft offered ODBC drivers for Linux and OSX. Now that Microsoft offers drivers for all platforms, for PyODBC support these are recommended. FreeTDS remains relevant for non-ODBC drivers such as pymssql where it works very well. Rowcount Support ---------------- Previous limitations with the SQLAlchemy ORM's "versioned rows" feature with Pyodbc have been resolved as of SQLAlchemy 2.0.5. See the notes at :ref:`mssql_rowcount_versioning`. .. _mssql_pyodbc_fastexecutemany: Fast Executemany Mode --------------------- The PyODBC driver includes support for a "fast executemany" mode of execution which greatly reduces round trips for a DBAPI ``executemany()`` call when using Microsoft ODBC drivers, for **limited size batches that fit in memory**. The feature is enabled by setting the attribute ``.fast_executemany`` on the DBAPI cursor when an executemany call is to be used. The SQLAlchemy PyODBC SQL Server dialect supports this parameter by passing the ``fast_executemany`` parameter to :func:`_sa.create_engine` , when using the **Microsoft ODBC driver only**:: engine = create_engine( "mssql+pyodbc://scott:tiger@mssql2017:1433/test?driver=ODBC+Driver+17+for+SQL+Server", fast_executemany=True, ) .. versionchanged:: 2.0.9 - the ``fast_executemany`` parameter now has its intended effect of this PyODBC feature taking effect for all INSERT statements that are executed with multiple parameter sets, which don't include RETURNING. Previously, SQLAlchemy 2.0's :term:`insertmanyvalues` feature would cause ``fast_executemany`` to not be used in most cases even if specified. .. versionadded:: 1.3 .. seealso:: `fast executemany <https://github.com/mkleehammer/pyodbc/wiki/Features-beyond-the-DB-API#fast_executemany>`_ - on github .. _mssql_pyodbc_setinputsizes: Setinputsizes Support ----------------------- As of version 2.0, the pyodbc ``cursor.setinputsizes()`` method is used for all statement executions, except for ``cursor.executemany()`` calls when fast_executemany=True where it is not supported (assuming :ref:`insertmanyvalues <engine_insertmanyvalues>` is kept enabled, "fastexecutemany" will not take place for INSERT statements in any case). The use of ``cursor.setinputsizes()`` can be disabled by passing ``use_setinputsizes=False`` to :func:`_sa.create_engine`. When ``use_setinputsizes`` is left at its default of ``True``, the specific per-type symbols passed to ``cursor.setinputsizes()`` can be programmatically customized using the :meth:`.DialectEvents.do_setinputsizes` hook. See that method for usage examples. .. versionchanged:: 2.0 The mssql+pyodbc dialect now defaults to using ``use_setinputsizes=True`` for all statement executions with the exception of cursor.executemany() calls when fast_executemany=True. The behavior can be turned off by passing ``use_setinputsizes=False`` to :func:`_sa.create_engine`. � N� )� _MSDateTime)� _MSUnicode)�_MSUnicodeText)�BINARY)�DATETIMEOFFSET)� MSDialect)�MSExecutionContext)� VARBINARY)�JSON)� JSONIndexType)� JSONPathType� )�exc)�types)�util)�PyODBCConnector)�cursorc s0 e Zd ZdZ� fdd�Zdd� Zdd� Z� ZS )�_ms_numeric_pyodbcz�Turns Decimals with adjusted() < 0 or > 7 into strings. The routines here are needed for older pyodbc versions as well as current mxODBC versions. c s( t � �|��|js�S � �fdd�}|S )Nc sR � j r>t| tj�r>| �� }|dk r,� �| �S |dkr>� �| �S �rJ�| �S | S d S )Nr � )Z asdecimal� isinstance�decimal�Decimal�adjusted�_small_dec_to_string�_large_dec_to_string)�valuer ��selfZ super_process� �U/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mssql/pyodbc.py�process� s z2_ms_numeric_pyodbc.bind_processor.<locals>.process)�super�bind_processor�_need_decimal_fix�r �dialectr! �� __class__r r r# � s z!_ms_numeric_pyodbc.bind_processorc C sB d|dk rdpddt |�� �d d�dd� |�� d D ��f S ) Nz%s0.%s%sr �-� �0r c S s g | ] }t |��qS r ��str)�.0Znintr r r � <listcomp>� � z;_ms_numeric_pyodbc._small_dec_to_string.<locals>.<listcomp>)�absr �join�as_tuple)r r r r r r � s �z'_ms_numeric_pyodbc._small_dec_to_stringc C s |� � d }dt|�v rXd|dk r&dp(dd�dd� |D ��d |�� t|�d f }n�t|�d |�� kr�d |dk rzdp|dd�d d� |D �d|�� d � �d�d d� |D �|�� d d � �f }n8d |dk r�dp�dd�dd� |D �d|�� d � �f }|S )Nr �Ez%s%s%sr r) r* c S s g | ] }t |��qS r r, �r. �sr r r r/ � r0 z;_ms_numeric_pyodbc._large_dec_to_string.<locals>.<listcomp>r+ z%s%s.%sc S s g | ] }t |��qS r r, r5 r r r r/ � r0 c S s g | ] }t |��qS r r, r5 r r r r/ � r0 z%s%sc S s g | ] }t |��qS r r, r5 r r r r/ � r0 )r3 r- r2 r �len)r r �_int�resultr r r r � s$ �""�"�z'_ms_numeric_pyodbc._large_dec_to_string)�__name__� __module__� __qualname__�__doc__r# r r � __classcell__r r r' r r � s r c @ s e Zd ZdS )�_MSNumeric_pyodbcN�r: r; r< r r r r r? � s r? c @ s e Zd ZdS )�_MSFloat_pyodbcNr@ r r r r rA � s rA c @ s e Zd ZdZdd� ZdS )�_ms_binary_pyodbcz�Wraps binary values in dialect-specific Binary wrapper. If the value is null, return a pyodbc-specific BinaryNull object to prevent pyODBC [and FreeTDS] from defaulting binary NULL types to SQLWCHAR and causing implicit conversion errors. c s( �j d u rd S �j j� � �fdd�}|S )Nc s | d ur� | �S �j jS d S �N)�dbapiZ BinaryNull)r �Z DBAPIBinaryr& r r r! � s z1_ms_binary_pyodbc.bind_processor.<locals>.process)rD �Binaryr% r rE r r# � s z _ms_binary_pyodbc.bind_processorN)r: r; r< r= r# r r r r rB � s rB c @ s e Zd ZdZdZdd� ZdS )�_ODBCDateTimeBindProcessorz6Add bind processors to handle datetimeoffset behaviorsFc s � fdd�}|S )Nc sP | d u r d S t | t�r| S | jr,� js0� js0| S | �d�}t�dd|�}|S d S )Nz%Y-%m-%d %H:%M:%S.%f %zz([\+\-]\d{2})([\d\.]+)$z\1:\2)r r- �tzinfo�timezone�has_tz�strftime�re�sub)r Z dto_string�r r r r! � s �z:_ODBCDateTimeBindProcessor.bind_processor.<locals>.processr r% r rN r r# � s z)_ODBCDateTimeBindProcessor.bind_processorN)r: r; r< r= rJ r# r r r r rG � s rG c @ s e Zd ZdS )� _ODBCDateTimeNr@ r r r r rO � s rO c @ s e Zd ZdZdS )�_ODBCDATETIMEOFFSETTN)r: r; r< rJ r r r r rP s rP c @ s e Zd ZdS )�_VARBINARY_pyodbcNr@ r r r r rQ s rQ c @ s e Zd ZdS )�_BINARY_pyodbcNr@ r r r r rR s rR c @ s e Zd Zdd� ZdS )�_String_pyodbcc C s* | j dv s| j dkr |jddfS |jS d S �N)N�maxi� r )�lengthZ SQL_VARCHAR�r rD r r r �get_dbapi_type s z _String_pyodbc.get_dbapi_typeN�r: r; r< rX r r r r rS s rS c @ s e Zd Zdd� ZdS )�_Unicode_pyodbcc C s* | j dv s| j dkr |jddfS |jS d S rT �rV � SQL_WVARCHARrW r r r rX s z _Unicode_pyodbc.get_dbapi_typeNrY r r r r rZ s rZ c @ s e Zd Zdd� ZdS )�_UnicodeText_pyodbcc C s* | j dv s| j dkr |jddfS |jS d S rT r[ rW r r r rX s z"_UnicodeText_pyodbc.get_dbapi_typeNrY r r r r r] s r] c @ s e Zd Zdd� ZdS )� _JSON_pyodbcc C s |j ddfS �Nr �r\ rW r r r rX ' s z_JSON_pyodbc.get_dbapi_typeNrY r r r r r^ & s r^ c @ s e Zd Zdd� ZdS )�_JSONIndexType_pyodbcc C s |j S rC r` rW r r r rX , s z$_JSONIndexType_pyodbc.get_dbapi_typeNrY r r r r ra + s ra c @ s e Zd Zdd� ZdS )�_JSONPathType_pyodbcc C s |j S rC r` rW r r r rX 1 s z#_JSONPathType_pyodbc.get_dbapi_typeNrY r r r r rb 0 s rb c s, e Zd ZdZ� fdd�Z� fdd�Z� ZS )�MSExecutionContext_pyodbcFc s> t � �� | jr:| jjr:t| jd �r:d| _| jd7 _dS )a� where appropriate, issue "select scope_identity()" in the same statement. Background on why "scope_identity()" is preferable to "@@identity": https://msdn.microsoft.com/en-us/library/ms190315.aspx Background on why we attempt to embed "scope_identity()" into the same statement as the INSERT: https://code.google.com/p/pyodbc/wiki/FAQs#How_do_I_retrieve_autogenerated/identity_values? r Tz; select scope_identity()N) r" �pre_execZ_select_lastrowidr& �use_scope_identityr7 � parameters�_embedded_scope_identity� statementrN r' r r rd 8 s �� �z"MSExecutionContext_pyodbc.pre_execc sz | j rlz| j�� }W n" | jjjy6 | j�� Y q0 |sH| j�� q|d }qTqt|d �| _t j | _ n t � � � d S r_ )rg r Zfetchallr& rD �Error�nextset�intZ _lastrowid�_cursorZ_NO_CURSOR_DMLZcursor_fetch_strategyr" � post_exec)r �rows�rowr' r r rm R s z#MSExecutionContext_pyodbc.post_exec)r: r; r< rg rd rm r> r r r' r rc 5 s rc c ! s� e Zd ZdZdZeZe�e j e j e e jeeee jeeeeee jee jee jee je e j e e j e e j j!e"e j j#e$e j%e j%i�Z d� fdd� Z&� fdd�Z'� fdd�Z(d d � Z)d� fd d � Z*� fdd�Z+� Z,S )�MSDialect_pyodbcTFc sZ t � jf d|i|�� | jo.| jo.t| jjd�| _| joB| �� dk | _|| _|rVd| _ d S )N�use_setinputsizesrj )� r � F) r" �__init__re rD �hasattr�CursorZ_dbapi_versionr$ �fast_executemanyZ!use_insertmanyvalues_wo_returning)r rw rq �paramsr' r r rt � s � �zMSDialect_pyodbc.__init__c s� z|� d��� }W n tjy2 t� �|� Y S 0 g }t�d�}|�|�D ]*}z|� t |�� W qL t yt Y qL0 qLt |�S d S )Nz8SELECT CAST(SERVERPROPERTY('ProductVersion') AS VARCHAR)z[.\-]) Zexec_driver_sqlZscalarr Z DBAPIErrorr" �_get_server_version_inforL �compile�split�appendrk � ValueError�tuple)r � connection�raw�version�r�nr' r r ry � s � z)MSDialect_pyodbc._get_server_version_infoc s t � �� �� �fdd�}|S )Nc s �d ur�| � � � | � d S rC )�_setup_timestampoffset_type)�conn�r Zsuper_r r � on_connect� s z/MSDialect_pyodbc.on_connect.<locals>.on_connect)r" r� )r r� r' r� r r� � s zMSDialect_pyodbc.on_connectc C s dd� }d}|� ||� d S )Nc S s\ t �d| �}t�|d |d |d |d |d |d |d d t�tj|d |d d ���S ) Nz<6hI2hr r rr r � � � i� r rs )�hours�minutes)�struct�unpack�datetimerI � timedelta)Z dto_value�tupr r r �_handle_datetimeoffset� s ��zLMSDialect_pyodbc._setup_timestampoffset_type.<locals>._handle_datetimeoffsetie���)Zadd_output_converter)r r r� Zodbc_SQL_SS_TIMESTAMPOFFSETr r r r� � s �z,MSDialect_pyodbc._setup_timestampoffset_typeNc s$ | j r d|_ t� j||||d� d S )NT)�context)rw r" �do_executemany)r r rh rf r� r' r r r� � s z MSDialect_pyodbc.do_executemanyc s4 t || jj�r$|jd }|dv r$dS t� �|||�S )Nr > Z10054ZHY010Z08007Z08S01Z08001Z08S02ZHYT00Z01002Z01000Z08003T)r rD ri �argsr" � is_disconnect)r �er r �coder' r r r� � s z MSDialect_pyodbc.is_disconnect)FT)N)-r: r; r< Zsupports_statement_cacheZ supports_sane_rowcount_returningrc Zexecution_ctx_clsr Z update_copyr Zcolspecs�sqltypes�Numericr? �FloatrA r rR �DateTimerO r rP r rQ Z LargeBinary�StringrS ZUnicoderZ Z UnicodeTextr] r r^ r ra r rb �Enumrt ry r� r� r� r� r> r r r' r rp o s< �� � rp )4r= r� r rL r� �baser r r r r r r r �jsonr Z_MSJsonr Z_MSJsonIndexTyper Z_MSJsonPathTyper* r r r� r Zconnectors.pyodbcr Zenginer rl r r� r? r� rA rB rG rO rP rQ rR r� rS rZ r] r^ ra rb rc rp r& r r r r �<module> sR d > : sqlalchemy/dialects/mssql/__pycache__/provision.cpython-39.pyc 0000644 00000010734 15125143220 0020526 0 ustar 00 a ��Jh� � @ s� d dl mZ d dl mZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z dd lm Z dd lm Z dd l m Z dd l mZ dd l mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ e�d�dd� �Ze�d�dd� �Ze �d�dd� �Ze�d�d d � �Zd d � Ze�d�d d!� �Ze�d�d"d#� �Z e�d�d$d%� �Z e�d�d&d'� �Ze�d�d(d)� �Zd*S )+� )�inspect)�Integer� )� create_engine)�exc)�Column)�DropConstraint)�ForeignKeyConstraint)�MetaData)�Table)� create_db)�"drop_all_schema_objects_pre_tables)�drop_db)�generate_driver_url)�get_temp_table_name)�log)�normalize_sequence)�post_configure_engine)� run_reap_dbs)�temp_table_keyword_argsZmssqlc C s |j dkrd|jj_d S )N�pyodbcF)�driver�dialectZdbapiZpooling)�urlZengineZfollower_ident� r �X/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mssql/provision.pyr s r c C s� | � � }| jd||f d�}|dvr0|jdd�}|dkrF|�ddi�}|rT|�|�}z |�� W n tjyv Y d S 0 |S d S ) Nz%s+%s)Z drivername)r �aioodbc� )�queryr ZMARS_ConnectionZYes)Zget_backend_name�setZupdate_query_dictZupdate_query_string� get_dialectr ZNoSuchModuleError)r r Z query_str�backend�new_urlr r r r $ s r c C s� |� � jdd��\}|�d| � |�d| � |�d| � |�d| � |�d� |�d� W d � n1 sr0 Y d S ) N� AUTOCOMMIT�Zisolation_levelzcreate database %sz1ALTER DATABASE %s SET ALLOW_SNAPSHOT_ISOLATION ONz0ALTER DATABASE %s SET READ_COMMITTED_SNAPSHOT ONzuse %szcreate schema test_schemazcreate schema test_schema_2)�connect�execution_options�exec_driver_sql��cfg�eng�ident�connr r r �_mssql_create_db; s �� r- c C s> |� � jdd��}t||� W d � n1 s00 Y d S )Nr# r$ )r% r& �_mssql_drop_ignorer( r r r �_mssql_drop_dbJ s r/ c C sZ z | � d| � t�d|� W dS tjyT } zt�d|� W Y d }~dS d }~0 0 d S )Nzdrop database %sz Reaped db: %sTzcouldn't drop db: %sF)r' r �infor Z DatabaseError�warning)r, r+ �errr r r r. P s r. c C s� t �d| � t| �}|�� jdd���}t �dd�|�� |�d�}dd� |D �}t� }|D ]}||v rZ|�|� qZd }} t |d �D ]\} } t || �r�|d 7 }q�t �d || � W d � n1 s�0 Y d S ) Nzdb reaper connecting to %rr# r$ zidentifiers in file: %sz, z�select d.name from sys.databases as d where name like 'TEST_%' and not exists (select session_id from sys.dm_exec_sessions where database_id=d.database_id)c S s h | ]\}|� � �qS r )�lower)�.0�dbnamer r r � <setcomp>n � z"_reap_mssql_dbs.<locals>.<setcomp>r � z-Dropped %d out of %d stale databases detected) r r0 r r% r& �joinr' r �add� enumerater. ) r Zidentsr* r, Zto_reapZ all_namesZto_drop�nameZdropped�totalr5 r r r �_reap_mssql_dbsa s& � �r> c C s i S )Nr )r) r* r r r � _mssql_temp_table_keyword_args} s r? c C s d| S )Nz##r )r) r* � base_namer r r �_mssql_get_temp_table_name� s rA c C s� |� � jdd���}t|�}d d| j| jfD ]v}|j|d�D ]d}t|t� tdt �tdt �|d�}t|�j ||d�D ],}|� t t |jjg|jjg|d d��� qpq:q*W d � n1 s�0 Y d S ) Nr# r$ Zdbo)�schema�x�yr< )r< )r% r& r Z test_schemaZ test_schema_2Zget_table_namesr r r r Zget_foreign_keys�executer r �crC rD )r) r* r, Z inspectorrB Ztname�tbZfkr r r r � s& ����r c C s |j d u rd|_ |S )Nr8 )�start)r) �sequencer r r r � s r N) Z sqlalchemyr r r r r rB r r r r r Ztesting.provisionr r r r r r r r r r Zfor_dbr- r/ r. r> r? rA r r r r �<module> sJ sqlalchemy/dialects/mssql/information_schema.py 0000755 00000017624 15125143220 0016064 0 ustar 00 # dialects/mssql/information_schema.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors from ... import cast from ... import Column from ... import MetaData from ... import Table from ...ext.compiler import compiles from ...sql import expression from ...types import Boolean from ...types import Integer from ...types import Numeric from ...types import NVARCHAR from ...types import String from ...types import TypeDecorator from ...types import Unicode ischema = MetaData() class CoerceUnicode(TypeDecorator): impl = Unicode cache_ok = True def bind_expression(self, bindvalue): return _cast_on_2005(bindvalue) class _cast_on_2005(expression.ColumnElement): def __init__(self, bindvalue): self.bindvalue = bindvalue @compiles(_cast_on_2005) def _compile(element, compiler, **kw): from . import base if ( compiler.dialect.server_version_info is None or compiler.dialect.server_version_info < base.MS_2005_VERSION ): return compiler.process(element.bindvalue, **kw) else: return compiler.process(cast(element.bindvalue, Unicode), **kw) schemata = Table( "SCHEMATA", ischema, Column("CATALOG_NAME", CoerceUnicode, key="catalog_name"), Column("SCHEMA_NAME", CoerceUnicode, key="schema_name"), Column("SCHEMA_OWNER", CoerceUnicode, key="schema_owner"), schema="INFORMATION_SCHEMA", ) tables = Table( "TABLES", ischema, Column("TABLE_CATALOG", CoerceUnicode, key="table_catalog"), Column("TABLE_SCHEMA", CoerceUnicode, key="table_schema"), Column("TABLE_NAME", CoerceUnicode, key="table_name"), Column("TABLE_TYPE", CoerceUnicode, key="table_type"), schema="INFORMATION_SCHEMA", ) columns = Table( "COLUMNS", ischema, Column("TABLE_SCHEMA", CoerceUnicode, key="table_schema"), Column("TABLE_NAME", CoerceUnicode, key="table_name"), Column("COLUMN_NAME", CoerceUnicode, key="column_name"), Column("IS_NULLABLE", Integer, key="is_nullable"), Column("DATA_TYPE", String, key="data_type"), Column("ORDINAL_POSITION", Integer, key="ordinal_position"), Column( "CHARACTER_MAXIMUM_LENGTH", Integer, key="character_maximum_length" ), Column("NUMERIC_PRECISION", Integer, key="numeric_precision"), Column("NUMERIC_SCALE", Integer, key="numeric_scale"), Column("COLUMN_DEFAULT", Integer, key="column_default"), Column("COLLATION_NAME", String, key="collation_name"), schema="INFORMATION_SCHEMA", ) mssql_temp_table_columns = Table( "COLUMNS", ischema, Column("TABLE_SCHEMA", CoerceUnicode, key="table_schema"), Column("TABLE_NAME", CoerceUnicode, key="table_name"), Column("COLUMN_NAME", CoerceUnicode, key="column_name"), Column("IS_NULLABLE", Integer, key="is_nullable"), Column("DATA_TYPE", String, key="data_type"), Column("ORDINAL_POSITION", Integer, key="ordinal_position"), Column( "CHARACTER_MAXIMUM_LENGTH", Integer, key="character_maximum_length" ), Column("NUMERIC_PRECISION", Integer, key="numeric_precision"), Column("NUMERIC_SCALE", Integer, key="numeric_scale"), Column("COLUMN_DEFAULT", Integer, key="column_default"), Column("COLLATION_NAME", String, key="collation_name"), schema="tempdb.INFORMATION_SCHEMA", ) constraints = Table( "TABLE_CONSTRAINTS", ischema, Column("TABLE_SCHEMA", CoerceUnicode, key="table_schema"), Column("TABLE_NAME", CoerceUnicode, key="table_name"), Column("CONSTRAINT_NAME", CoerceUnicode, key="constraint_name"), Column("CONSTRAINT_TYPE", CoerceUnicode, key="constraint_type"), schema="INFORMATION_SCHEMA", ) column_constraints = Table( "CONSTRAINT_COLUMN_USAGE", ischema, Column("TABLE_SCHEMA", CoerceUnicode, key="table_schema"), Column("TABLE_NAME", CoerceUnicode, key="table_name"), Column("COLUMN_NAME", CoerceUnicode, key="column_name"), Column("CONSTRAINT_NAME", CoerceUnicode, key="constraint_name"), schema="INFORMATION_SCHEMA", ) key_constraints = Table( "KEY_COLUMN_USAGE", ischema, Column("TABLE_SCHEMA", CoerceUnicode, key="table_schema"), Column("TABLE_NAME", CoerceUnicode, key="table_name"), Column("COLUMN_NAME", CoerceUnicode, key="column_name"), Column("CONSTRAINT_NAME", CoerceUnicode, key="constraint_name"), Column("CONSTRAINT_SCHEMA", CoerceUnicode, key="constraint_schema"), Column("ORDINAL_POSITION", Integer, key="ordinal_position"), schema="INFORMATION_SCHEMA", ) ref_constraints = Table( "REFERENTIAL_CONSTRAINTS", ischema, Column("CONSTRAINT_CATALOG", CoerceUnicode, key="constraint_catalog"), Column("CONSTRAINT_SCHEMA", CoerceUnicode, key="constraint_schema"), Column("CONSTRAINT_NAME", CoerceUnicode, key="constraint_name"), # TODO: is CATLOG misspelled ? Column( "UNIQUE_CONSTRAINT_CATLOG", CoerceUnicode, key="unique_constraint_catalog", ), Column( "UNIQUE_CONSTRAINT_SCHEMA", CoerceUnicode, key="unique_constraint_schema", ), Column( "UNIQUE_CONSTRAINT_NAME", CoerceUnicode, key="unique_constraint_name" ), Column("MATCH_OPTION", String, key="match_option"), Column("UPDATE_RULE", String, key="update_rule"), Column("DELETE_RULE", String, key="delete_rule"), schema="INFORMATION_SCHEMA", ) views = Table( "VIEWS", ischema, Column("TABLE_CATALOG", CoerceUnicode, key="table_catalog"), Column("TABLE_SCHEMA", CoerceUnicode, key="table_schema"), Column("TABLE_NAME", CoerceUnicode, key="table_name"), Column("VIEW_DEFINITION", CoerceUnicode, key="view_definition"), Column("CHECK_OPTION", String, key="check_option"), Column("IS_UPDATABLE", String, key="is_updatable"), schema="INFORMATION_SCHEMA", ) computed_columns = Table( "computed_columns", ischema, Column("object_id", Integer), Column("name", CoerceUnicode), Column("is_computed", Boolean), Column("is_persisted", Boolean), Column("definition", CoerceUnicode), schema="sys", ) sequences = Table( "SEQUENCES", ischema, Column("SEQUENCE_CATALOG", CoerceUnicode, key="sequence_catalog"), Column("SEQUENCE_SCHEMA", CoerceUnicode, key="sequence_schema"), Column("SEQUENCE_NAME", CoerceUnicode, key="sequence_name"), schema="INFORMATION_SCHEMA", ) class NumericSqlVariant(TypeDecorator): r"""This type casts sql_variant columns in the identity_columns view to numeric. This is required because: * pyodbc does not support sql_variant * pymssql under python 2 return the byte representation of the number, int 1 is returned as "\x01\x00\x00\x00". On python 3 it returns the correct value as string. """ impl = Unicode cache_ok = True def column_expression(self, colexpr): return cast(colexpr, Numeric(38, 0)) identity_columns = Table( "identity_columns", ischema, Column("object_id", Integer), Column("name", CoerceUnicode), Column("is_identity", Boolean), Column("seed_value", NumericSqlVariant), Column("increment_value", NumericSqlVariant), Column("last_value", NumericSqlVariant), Column("is_not_for_replication", Boolean), schema="sys", ) class NVarcharSqlVariant(TypeDecorator): """This type casts sql_variant columns in the extended_properties view to nvarchar. This is required because pyodbc does not support sql_variant """ impl = Unicode cache_ok = True def column_expression(self, colexpr): return cast(colexpr, NVARCHAR) extended_properties = Table( "extended_properties", ischema, Column("class", Integer), # TINYINT Column("class_desc", CoerceUnicode), Column("major_id", Integer), Column("minor_id", Integer), Column("name", CoerceUnicode), Column("value", NVarcharSqlVariant), schema="sys", ) sqlalchemy/dialects/mssql/base.py 0000755 00000403076 15125143220 0013131 0 ustar 00 # dialects/mssql/base.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors """ .. dialect:: mssql :name: Microsoft SQL Server :normal_support: 2012+ :best_effort: 2005+ .. _mssql_external_dialects: External Dialects ----------------- In addition to the above DBAPI layers with native SQLAlchemy support, there are third-party dialects for other DBAPI layers that are compatible with SQL Server. See the "External Dialects" list on the :ref:`dialect_toplevel` page. .. _mssql_identity: Auto Increment Behavior / IDENTITY Columns ------------------------------------------ SQL Server provides so-called "auto incrementing" behavior using the ``IDENTITY`` construct, which can be placed on any single integer column in a table. SQLAlchemy considers ``IDENTITY`` within its default "autoincrement" behavior for an integer primary key column, described at :paramref:`_schema.Column.autoincrement`. This means that by default, the first integer primary key column in a :class:`_schema.Table` will be considered to be the identity column - unless it is associated with a :class:`.Sequence` - and will generate DDL as such:: from sqlalchemy import Table, MetaData, Column, Integer m = MetaData() t = Table( "t", m, Column("id", Integer, primary_key=True), Column("x", Integer), ) m.create_all(engine) The above example will generate DDL as: .. sourcecode:: sql CREATE TABLE t ( id INTEGER NOT NULL IDENTITY, x INTEGER NULL, PRIMARY KEY (id) ) For the case where this default generation of ``IDENTITY`` is not desired, specify ``False`` for the :paramref:`_schema.Column.autoincrement` flag, on the first integer primary key column:: m = MetaData() t = Table( "t", m, Column("id", Integer, primary_key=True, autoincrement=False), Column("x", Integer), ) m.create_all(engine) To add the ``IDENTITY`` keyword to a non-primary key column, specify ``True`` for the :paramref:`_schema.Column.autoincrement` flag on the desired :class:`_schema.Column` object, and ensure that :paramref:`_schema.Column.autoincrement` is set to ``False`` on any integer primary key column:: m = MetaData() t = Table( "t", m, Column("id", Integer, primary_key=True, autoincrement=False), Column("x", Integer, autoincrement=True), ) m.create_all(engine) .. versionchanged:: 1.4 Added :class:`_schema.Identity` construct in a :class:`_schema.Column` to specify the start and increment parameters of an IDENTITY. These replace the use of the :class:`.Sequence` object in order to specify these values. .. deprecated:: 1.4 The ``mssql_identity_start`` and ``mssql_identity_increment`` parameters to :class:`_schema.Column` are deprecated and should we replaced by an :class:`_schema.Identity` object. Specifying both ways of configuring an IDENTITY will result in a compile error. These options are also no longer returned as part of the ``dialect_options`` key in :meth:`_reflection.Inspector.get_columns`. Use the information in the ``identity`` key instead. .. deprecated:: 1.3 The use of :class:`.Sequence` to specify IDENTITY characteristics is deprecated and will be removed in a future release. Please use the :class:`_schema.Identity` object parameters :paramref:`_schema.Identity.start` and :paramref:`_schema.Identity.increment`. .. versionchanged:: 1.4 Removed the ability to use a :class:`.Sequence` object to modify IDENTITY characteristics. :class:`.Sequence` objects now only manipulate true T-SQL SEQUENCE types. .. note:: There can only be one IDENTITY column on the table. When using ``autoincrement=True`` to enable the IDENTITY keyword, SQLAlchemy does not guard against multiple columns specifying the option simultaneously. The SQL Server database will instead reject the ``CREATE TABLE`` statement. .. note:: An INSERT statement which attempts to provide a value for a column that is marked with IDENTITY will be rejected by SQL Server. In order for the value to be accepted, a session-level option "SET IDENTITY_INSERT" must be enabled. The SQLAlchemy SQL Server dialect will perform this operation automatically when using a core :class:`_expression.Insert` construct; if the execution specifies a value for the IDENTITY column, the "IDENTITY_INSERT" option will be enabled for the span of that statement's invocation.However, this scenario is not high performing and should not be relied upon for normal use. If a table doesn't actually require IDENTITY behavior in its integer primary key column, the keyword should be disabled when creating the table by ensuring that ``autoincrement=False`` is set. Controlling "Start" and "Increment" ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Specific control over the "start" and "increment" values for the ``IDENTITY`` generator are provided using the :paramref:`_schema.Identity.start` and :paramref:`_schema.Identity.increment` parameters passed to the :class:`_schema.Identity` object:: from sqlalchemy import Table, Integer, Column, Identity test = Table( "test", metadata, Column( "id", Integer, primary_key=True, Identity(start=100, increment=10) ), Column("name", String(20)), ) The CREATE TABLE for the above :class:`_schema.Table` object would be: .. sourcecode:: sql CREATE TABLE test ( id INTEGER NOT NULL IDENTITY(100,10) PRIMARY KEY, name VARCHAR(20) NULL, ) .. note:: The :class:`_schema.Identity` object supports many other parameter in addition to ``start`` and ``increment``. These are not supported by SQL Server and will be ignored when generating the CREATE TABLE ddl. .. versionchanged:: 1.3.19 The :class:`_schema.Identity` object is now used to affect the ``IDENTITY`` generator for a :class:`_schema.Column` under SQL Server. Previously, the :class:`.Sequence` object was used. As SQL Server now supports real sequences as a separate construct, :class:`.Sequence` will be functional in the normal way starting from SQLAlchemy version 1.4. Using IDENTITY with Non-Integer numeric types ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ SQL Server also allows ``IDENTITY`` to be used with ``NUMERIC`` columns. To implement this pattern smoothly in SQLAlchemy, the primary datatype of the column should remain as ``Integer``, however the underlying implementation type deployed to the SQL Server database can be specified as ``Numeric`` using :meth:`.TypeEngine.with_variant`:: from sqlalchemy import Column from sqlalchemy import Integer from sqlalchemy import Numeric from sqlalchemy import String from sqlalchemy.ext.declarative import declarative_base Base = declarative_base() class TestTable(Base): __tablename__ = "test" id = Column( Integer().with_variant(Numeric(10, 0), "mssql"), primary_key=True, autoincrement=True, ) name = Column(String) In the above example, ``Integer().with_variant()`` provides clear usage information that accurately describes the intent of the code. The general restriction that ``autoincrement`` only applies to ``Integer`` is established at the metadata level and not at the per-dialect level. When using the above pattern, the primary key identifier that comes back from the insertion of a row, which is also the value that would be assigned to an ORM object such as ``TestTable`` above, will be an instance of ``Decimal()`` and not ``int`` when using SQL Server. The numeric return type of the :class:`_types.Numeric` type can be changed to return floats by passing False to :paramref:`_types.Numeric.asdecimal`. To normalize the return type of the above ``Numeric(10, 0)`` to return Python ints (which also support "long" integer values in Python 3), use :class:`_types.TypeDecorator` as follows:: from sqlalchemy import TypeDecorator class NumericAsInteger(TypeDecorator): "normalize floating point return values into ints" impl = Numeric(10, 0, asdecimal=False) cache_ok = True def process_result_value(self, value, dialect): if value is not None: value = int(value) return value class TestTable(Base): __tablename__ = "test" id = Column( Integer().with_variant(NumericAsInteger, "mssql"), primary_key=True, autoincrement=True, ) name = Column(String) .. _mssql_insert_behavior: INSERT behavior ^^^^^^^^^^^^^^^^ Handling of the ``IDENTITY`` column at INSERT time involves two key techniques. The most common is being able to fetch the "last inserted value" for a given ``IDENTITY`` column, a process which SQLAlchemy performs implicitly in many cases, most importantly within the ORM. The process for fetching this value has several variants: * In the vast majority of cases, RETURNING is used in conjunction with INSERT statements on SQL Server in order to get newly generated primary key values: .. sourcecode:: sql INSERT INTO t (x) OUTPUT inserted.id VALUES (?) As of SQLAlchemy 2.0, the :ref:`engine_insertmanyvalues` feature is also used by default to optimize many-row INSERT statements; for SQL Server the feature takes place for both RETURNING and-non RETURNING INSERT statements. .. versionchanged:: 2.0.10 The :ref:`engine_insertmanyvalues` feature for SQL Server was temporarily disabled for SQLAlchemy version 2.0.9 due to issues with row ordering. As of 2.0.10 the feature is re-enabled, with special case handling for the unit of work's requirement for RETURNING to be ordered. * When RETURNING is not available or has been disabled via ``implicit_returning=False``, either the ``scope_identity()`` function or the ``@@identity`` variable is used; behavior varies by backend: * when using PyODBC, the phrase ``; select scope_identity()`` will be appended to the end of the INSERT statement; a second result set will be fetched in order to receive the value. Given a table as:: t = Table( "t", metadata, Column("id", Integer, primary_key=True), Column("x", Integer), implicit_returning=False, ) an INSERT will look like: .. sourcecode:: sql INSERT INTO t (x) VALUES (?); select scope_identity() * Other dialects such as pymssql will call upon ``SELECT scope_identity() AS lastrowid`` subsequent to an INSERT statement. If the flag ``use_scope_identity=False`` is passed to :func:`_sa.create_engine`, the statement ``SELECT @@identity AS lastrowid`` is used instead. A table that contains an ``IDENTITY`` column will prohibit an INSERT statement that refers to the identity column explicitly. The SQLAlchemy dialect will detect when an INSERT construct, created using a core :func:`_expression.insert` construct (not a plain string SQL), refers to the identity column, and in this case will emit ``SET IDENTITY_INSERT ON`` prior to the insert statement proceeding, and ``SET IDENTITY_INSERT OFF`` subsequent to the execution. Given this example:: m = MetaData() t = Table( "t", m, Column("id", Integer, primary_key=True), Column("x", Integer) ) m.create_all(engine) with engine.begin() as conn: conn.execute(t.insert(), {"id": 1, "x": 1}, {"id": 2, "x": 2}) The above column will be created with IDENTITY, however the INSERT statement we emit is specifying explicit values. In the echo output we can see how SQLAlchemy handles this: .. sourcecode:: sql CREATE TABLE t ( id INTEGER NOT NULL IDENTITY(1,1), x INTEGER NULL, PRIMARY KEY (id) ) COMMIT SET IDENTITY_INSERT t ON INSERT INTO t (id, x) VALUES (?, ?) ((1, 1), (2, 2)) SET IDENTITY_INSERT t OFF COMMIT This is an auxiliary use case suitable for testing and bulk insert scenarios. SEQUENCE support ---------------- The :class:`.Sequence` object creates "real" sequences, i.e., ``CREATE SEQUENCE``: .. sourcecode:: pycon+sql >>> from sqlalchemy import Sequence >>> from sqlalchemy.schema import CreateSequence >>> from sqlalchemy.dialects import mssql >>> print( ... CreateSequence(Sequence("my_seq", start=1)).compile( ... dialect=mssql.dialect() ... ) ... ) {printsql}CREATE SEQUENCE my_seq START WITH 1 For integer primary key generation, SQL Server's ``IDENTITY`` construct should generally be preferred vs. sequence. .. tip:: The default start value for T-SQL is ``-2**63`` instead of 1 as in most other SQL databases. Users should explicitly set the :paramref:`.Sequence.start` to 1 if that's the expected default:: seq = Sequence("my_sequence", start=1) .. versionadded:: 1.4 added SQL Server support for :class:`.Sequence` .. versionchanged:: 2.0 The SQL Server dialect will no longer implicitly render "START WITH 1" for ``CREATE SEQUENCE``, which was the behavior first implemented in version 1.4. MAX on VARCHAR / NVARCHAR ------------------------- SQL Server supports the special string "MAX" within the :class:`_types.VARCHAR` and :class:`_types.NVARCHAR` datatypes, to indicate "maximum length possible". The dialect currently handles this as a length of "None" in the base type, rather than supplying a dialect-specific version of these types, so that a base type specified such as ``VARCHAR(None)`` can assume "unlengthed" behavior on more than one backend without using dialect-specific types. To build a SQL Server VARCHAR or NVARCHAR with MAX length, use None:: my_table = Table( "my_table", metadata, Column("my_data", VARCHAR(None)), Column("my_n_data", NVARCHAR(None)), ) Collation Support ----------------- Character collations are supported by the base string types, specified by the string argument "collation":: from sqlalchemy import VARCHAR Column("login", VARCHAR(32, collation="Latin1_General_CI_AS")) When such a column is associated with a :class:`_schema.Table`, the CREATE TABLE statement for this column will yield: .. sourcecode:: sql login VARCHAR(32) COLLATE Latin1_General_CI_AS NULL LIMIT/OFFSET Support -------------------- MSSQL has added support for LIMIT / OFFSET as of SQL Server 2012, via the "OFFSET n ROWS" and "FETCH NEXT n ROWS" clauses. SQLAlchemy supports these syntaxes automatically if SQL Server 2012 or greater is detected. .. versionchanged:: 1.4 support added for SQL Server "OFFSET n ROWS" and "FETCH NEXT n ROWS" syntax. For statements that specify only LIMIT and no OFFSET, all versions of SQL Server support the TOP keyword. This syntax is used for all SQL Server versions when no OFFSET clause is present. A statement such as:: select(some_table).limit(5) will render similarly to: .. sourcecode:: sql SELECT TOP 5 col1, col2.. FROM table For versions of SQL Server prior to SQL Server 2012, a statement that uses LIMIT and OFFSET, or just OFFSET alone, will be rendered using the ``ROW_NUMBER()`` window function. A statement such as:: select(some_table).order_by(some_table.c.col3).limit(5).offset(10) will render similarly to: .. sourcecode:: sql SELECT anon_1.col1, anon_1.col2 FROM (SELECT col1, col2, ROW_NUMBER() OVER (ORDER BY col3) AS mssql_rn FROM table WHERE t.x = :x_1) AS anon_1 WHERE mssql_rn > :param_1 AND mssql_rn <= :param_2 + :param_1 Note that when using LIMIT and/or OFFSET, whether using the older or newer SQL Server syntaxes, the statement must have an ORDER BY as well, else a :class:`.CompileError` is raised. .. _mssql_comment_support: DDL Comment Support -------------------- Comment support, which includes DDL rendering for attributes such as :paramref:`_schema.Table.comment` and :paramref:`_schema.Column.comment`, as well as the ability to reflect these comments, is supported assuming a supported version of SQL Server is in use. If a non-supported version such as Azure Synapse is detected at first-connect time (based on the presence of the ``fn_listextendedproperty`` SQL function), comment support including rendering and table-comment reflection is disabled, as both features rely upon SQL Server stored procedures and functions that are not available on all backend types. To force comment support to be on or off, bypassing autodetection, set the parameter ``supports_comments`` within :func:`_sa.create_engine`:: e = create_engine("mssql+pyodbc://u:p@dsn", supports_comments=False) .. versionadded:: 2.0 Added support for table and column comments for the SQL Server dialect, including DDL generation and reflection. .. _mssql_isolation_level: Transaction Isolation Level --------------------------- All SQL Server dialects support setting of transaction isolation level both via a dialect-specific parameter :paramref:`_sa.create_engine.isolation_level` accepted by :func:`_sa.create_engine`, as well as the :paramref:`.Connection.execution_options.isolation_level` argument as passed to :meth:`_engine.Connection.execution_options`. This feature works by issuing the command ``SET TRANSACTION ISOLATION LEVEL <level>`` for each new connection. To set isolation level using :func:`_sa.create_engine`:: engine = create_engine( "mssql+pyodbc://scott:tiger@ms_2008", isolation_level="REPEATABLE READ" ) To set using per-connection execution options:: connection = engine.connect() connection = connection.execution_options(isolation_level="READ COMMITTED") Valid values for ``isolation_level`` include: * ``AUTOCOMMIT`` - pyodbc / pymssql-specific * ``READ COMMITTED`` * ``READ UNCOMMITTED`` * ``REPEATABLE READ`` * ``SERIALIZABLE`` * ``SNAPSHOT`` - specific to SQL Server There are also more options for isolation level configurations, such as "sub-engine" objects linked to a main :class:`_engine.Engine` which each apply different isolation level settings. See the discussion at :ref:`dbapi_autocommit` for background. .. seealso:: :ref:`dbapi_autocommit` .. _mssql_reset_on_return: Temporary Table / Resource Reset for Connection Pooling ------------------------------------------------------- The :class:`.QueuePool` connection pool implementation used by the SQLAlchemy :class:`.Engine` object includes :ref:`reset on return <pool_reset_on_return>` behavior that will invoke the DBAPI ``.rollback()`` method when connections are returned to the pool. While this rollback will clear out the immediate state used by the previous transaction, it does not cover a wider range of session-level state, including temporary tables as well as other server state such as prepared statement handles and statement caches. An undocumented SQL Server procedure known as ``sp_reset_connection`` is known to be a workaround for this issue which will reset most of the session state that builds up on a connection, including temporary tables. To install ``sp_reset_connection`` as the means of performing reset-on-return, the :meth:`.PoolEvents.reset` event hook may be used, as demonstrated in the example below. The :paramref:`_sa.create_engine.pool_reset_on_return` parameter is set to ``None`` so that the custom scheme can replace the default behavior completely. The custom hook implementation calls ``.rollback()`` in any case, as it's usually important that the DBAPI's own tracking of commit/rollback will remain consistent with the state of the transaction:: from sqlalchemy import create_engine from sqlalchemy import event mssql_engine = create_engine( "mssql+pyodbc://scott:tiger^5HHH@mssql2017:1433/test?driver=ODBC+Driver+17+for+SQL+Server", # disable default reset-on-return scheme pool_reset_on_return=None, ) @event.listens_for(mssql_engine, "reset") def _reset_mssql(dbapi_connection, connection_record, reset_state): if not reset_state.terminate_only: dbapi_connection.execute("{call sys.sp_reset_connection}") # so that the DBAPI itself knows that the connection has been # reset dbapi_connection.rollback() .. versionchanged:: 2.0.0b3 Added additional state arguments to the :meth:`.PoolEvents.reset` event and additionally ensured the event is invoked for all "reset" occurrences, so that it's appropriate as a place for custom "reset" handlers. Previous schemes which use the :meth:`.PoolEvents.checkin` handler remain usable as well. .. seealso:: :ref:`pool_reset_on_return` - in the :ref:`pooling_toplevel` documentation Nullability ----------- MSSQL has support for three levels of column nullability. The default nullability allows nulls and is explicit in the CREATE TABLE construct: .. sourcecode:: sql name VARCHAR(20) NULL If ``nullable=None`` is specified then no specification is made. In other words the database's configured default is used. This will render: .. sourcecode:: sql name VARCHAR(20) If ``nullable`` is ``True`` or ``False`` then the column will be ``NULL`` or ``NOT NULL`` respectively. Date / Time Handling -------------------- DATE and TIME are supported. Bind parameters are converted to datetime.datetime() objects as required by most MSSQL drivers, and results are processed from strings if needed. The DATE and TIME types are not available for MSSQL 2005 and previous - if a server version below 2008 is detected, DDL for these types will be issued as DATETIME. .. _mssql_large_type_deprecation: Large Text/Binary Type Deprecation ---------------------------------- Per `SQL Server 2012/2014 Documentation <https://technet.microsoft.com/en-us/library/ms187993.aspx>`_, the ``NTEXT``, ``TEXT`` and ``IMAGE`` datatypes are to be removed from SQL Server in a future release. SQLAlchemy normally relates these types to the :class:`.UnicodeText`, :class:`_expression.TextClause` and :class:`.LargeBinary` datatypes. In order to accommodate this change, a new flag ``deprecate_large_types`` is added to the dialect, which will be automatically set based on detection of the server version in use, if not otherwise set by the user. The behavior of this flag is as follows: * When this flag is ``True``, the :class:`.UnicodeText`, :class:`_expression.TextClause` and :class:`.LargeBinary` datatypes, when used to render DDL, will render the types ``NVARCHAR(max)``, ``VARCHAR(max)``, and ``VARBINARY(max)``, respectively. This is a new behavior as of the addition of this flag. * When this flag is ``False``, the :class:`.UnicodeText`, :class:`_expression.TextClause` and :class:`.LargeBinary` datatypes, when used to render DDL, will render the types ``NTEXT``, ``TEXT``, and ``IMAGE``, respectively. This is the long-standing behavior of these types. * The flag begins with the value ``None``, before a database connection is established. If the dialect is used to render DDL without the flag being set, it is interpreted the same as ``False``. * On first connection, the dialect detects if SQL Server version 2012 or greater is in use; if the flag is still at ``None``, it sets it to ``True`` or ``False`` based on whether 2012 or greater is detected. * The flag can be set to either ``True`` or ``False`` when the dialect is created, typically via :func:`_sa.create_engine`:: eng = create_engine( "mssql+pymssql://user:pass@host/db", deprecate_large_types=True ) * Complete control over whether the "old" or "new" types are rendered is available in all SQLAlchemy versions by using the UPPERCASE type objects instead: :class:`_types.NVARCHAR`, :class:`_types.VARCHAR`, :class:`_types.VARBINARY`, :class:`_types.TEXT`, :class:`_mssql.NTEXT`, :class:`_mssql.IMAGE` will always remain fixed and always output exactly that type. .. _multipart_schema_names: Multipart Schema Names ---------------------- SQL Server schemas sometimes require multiple parts to their "schema" qualifier, that is, including the database name and owner name as separate tokens, such as ``mydatabase.dbo.some_table``. These multipart names can be set at once using the :paramref:`_schema.Table.schema` argument of :class:`_schema.Table`:: Table( "some_table", metadata, Column("q", String(50)), schema="mydatabase.dbo", ) When performing operations such as table or component reflection, a schema argument that contains a dot will be split into separate "database" and "owner" components in order to correctly query the SQL Server information schema tables, as these two values are stored separately. Additionally, when rendering the schema name for DDL or SQL, the two components will be quoted separately for case sensitive names and other special characters. Given an argument as below:: Table( "some_table", metadata, Column("q", String(50)), schema="MyDataBase.dbo", ) The above schema would be rendered as ``[MyDataBase].dbo``, and also in reflection, would be reflected using "dbo" as the owner and "MyDataBase" as the database name. To control how the schema name is broken into database / owner, specify brackets (which in SQL Server are quoting characters) in the name. Below, the "owner" will be considered as ``MyDataBase.dbo`` and the "database" will be None:: Table( "some_table", metadata, Column("q", String(50)), schema="[MyDataBase.dbo]", ) To individually specify both database and owner name with special characters or embedded dots, use two sets of brackets:: Table( "some_table", metadata, Column("q", String(50)), schema="[MyDataBase.Period].[MyOwner.Dot]", ) .. versionchanged:: 1.2 the SQL Server dialect now treats brackets as identifier delimiters splitting the schema into separate database and owner tokens, to allow dots within either name itself. .. _legacy_schema_rendering: Legacy Schema Mode ------------------ Very old versions of the MSSQL dialect introduced the behavior such that a schema-qualified table would be auto-aliased when used in a SELECT statement; given a table:: account_table = Table( "account", metadata, Column("id", Integer, primary_key=True), Column("info", String(100)), schema="customer_schema", ) this legacy mode of rendering would assume that "customer_schema.account" would not be accepted by all parts of the SQL statement, as illustrated below: .. sourcecode:: pycon+sql >>> eng = create_engine("mssql+pymssql://mydsn", legacy_schema_aliasing=True) >>> print(account_table.select().compile(eng)) {printsql}SELECT account_1.id, account_1.info FROM customer_schema.account AS account_1 This mode of behavior is now off by default, as it appears to have served no purpose; however in the case that legacy applications rely upon it, it is available using the ``legacy_schema_aliasing`` argument to :func:`_sa.create_engine` as illustrated above. .. deprecated:: 1.4 The ``legacy_schema_aliasing`` flag is now deprecated and will be removed in a future release. .. _mssql_indexes: Clustered Index Support ----------------------- The MSSQL dialect supports clustered indexes (and primary keys) via the ``mssql_clustered`` option. This option is available to :class:`.Index`, :class:`.UniqueConstraint`. and :class:`.PrimaryKeyConstraint`. For indexes this option can be combined with the ``mssql_columnstore`` one to create a clustered columnstore index. To generate a clustered index:: Index("my_index", table.c.x, mssql_clustered=True) which renders the index as ``CREATE CLUSTERED INDEX my_index ON table (x)``. To generate a clustered primary key use:: Table( "my_table", metadata, Column("x", ...), Column("y", ...), PrimaryKeyConstraint("x", "y", mssql_clustered=True), ) which will render the table, for example, as: .. sourcecode:: sql CREATE TABLE my_table ( x INTEGER NOT NULL, y INTEGER NOT NULL, PRIMARY KEY CLUSTERED (x, y) ) Similarly, we can generate a clustered unique constraint using:: Table( "my_table", metadata, Column("x", ...), Column("y", ...), PrimaryKeyConstraint("x"), UniqueConstraint("y", mssql_clustered=True), ) To explicitly request a non-clustered primary key (for example, when a separate clustered index is desired), use:: Table( "my_table", metadata, Column("x", ...), Column("y", ...), PrimaryKeyConstraint("x", "y", mssql_clustered=False), ) which will render the table, for example, as: .. sourcecode:: sql CREATE TABLE my_table ( x INTEGER NOT NULL, y INTEGER NOT NULL, PRIMARY KEY NONCLUSTERED (x, y) ) Columnstore Index Support ------------------------- The MSSQL dialect supports columnstore indexes via the ``mssql_columnstore`` option. This option is available to :class:`.Index`. It be combined with the ``mssql_clustered`` option to create a clustered columnstore index. To generate a columnstore index:: Index("my_index", table.c.x, mssql_columnstore=True) which renders the index as ``CREATE COLUMNSTORE INDEX my_index ON table (x)``. To generate a clustered columnstore index provide no columns:: idx = Index("my_index", mssql_clustered=True, mssql_columnstore=True) # required to associate the index with the table table.append_constraint(idx) the above renders the index as ``CREATE CLUSTERED COLUMNSTORE INDEX my_index ON table``. .. versionadded:: 2.0.18 MSSQL-Specific Index Options ----------------------------- In addition to clustering, the MSSQL dialect supports other special options for :class:`.Index`. INCLUDE ^^^^^^^ The ``mssql_include`` option renders INCLUDE(colname) for the given string names:: Index("my_index", table.c.x, mssql_include=["y"]) would render the index as ``CREATE INDEX my_index ON table (x) INCLUDE (y)`` .. _mssql_index_where: Filtered Indexes ^^^^^^^^^^^^^^^^ The ``mssql_where`` option renders WHERE(condition) for the given string names:: Index("my_index", table.c.x, mssql_where=table.c.x > 10) would render the index as ``CREATE INDEX my_index ON table (x) WHERE x > 10``. .. versionadded:: 1.3.4 Index ordering ^^^^^^^^^^^^^^ Index ordering is available via functional expressions, such as:: Index("my_index", table.c.x.desc()) would render the index as ``CREATE INDEX my_index ON table (x DESC)`` .. seealso:: :ref:`schema_indexes_functional` Compatibility Levels -------------------- MSSQL supports the notion of setting compatibility levels at the database level. This allows, for instance, to run a database that is compatible with SQL2000 while running on a SQL2005 database server. ``server_version_info`` will always return the database server version information (in this case SQL2005) and not the compatibility level information. Because of this, if running under a backwards compatibility mode SQLAlchemy may attempt to use T-SQL statements that are unable to be parsed by the database server. .. _mssql_triggers: Triggers -------- SQLAlchemy by default uses OUTPUT INSERTED to get at newly generated primary key values via IDENTITY columns or other server side defaults. MS-SQL does not allow the usage of OUTPUT INSERTED on tables that have triggers. To disable the usage of OUTPUT INSERTED on a per-table basis, specify ``implicit_returning=False`` for each :class:`_schema.Table` which has triggers:: Table( "mytable", metadata, Column("id", Integer, primary_key=True), # ..., implicit_returning=False, ) Declarative form:: class MyClass(Base): # ... __table_args__ = {"implicit_returning": False} .. _mssql_rowcount_versioning: Rowcount Support / ORM Versioning --------------------------------- The SQL Server drivers may have limited ability to return the number of rows updated from an UPDATE or DELETE statement. As of this writing, the PyODBC driver is not able to return a rowcount when OUTPUT INSERTED is used. Previous versions of SQLAlchemy therefore had limitations for features such as the "ORM Versioning" feature that relies upon accurate rowcounts in order to match version numbers with matched rows. SQLAlchemy 2.0 now retrieves the "rowcount" manually for these particular use cases based on counting the rows that arrived back within RETURNING; so while the driver still has this limitation, the ORM Versioning feature is no longer impacted by it. As of SQLAlchemy 2.0.5, ORM versioning has been fully re-enabled for the pyodbc driver. .. versionchanged:: 2.0.5 ORM versioning support is restored for the pyodbc driver. Previously, a warning would be emitted during ORM flush that versioning was not supported. Enabling Snapshot Isolation --------------------------- SQL Server has a default transaction isolation mode that locks entire tables, and causes even mildly concurrent applications to have long held locks and frequent deadlocks. Enabling snapshot isolation for the database as a whole is recommended for modern levels of concurrency support. This is accomplished via the following ALTER DATABASE commands executed at the SQL prompt: .. sourcecode:: sql ALTER DATABASE MyDatabase SET ALLOW_SNAPSHOT_ISOLATION ON ALTER DATABASE MyDatabase SET READ_COMMITTED_SNAPSHOT ON Background on SQL Server snapshot isolation is available at https://msdn.microsoft.com/en-us/library/ms175095.aspx. """ # noqa from __future__ import annotations import codecs import datetime import operator import re from typing import overload from typing import TYPE_CHECKING from uuid import UUID as _python_UUID from . import information_schema as ischema from .json import JSON from .json import JSONIndexType from .json import JSONPathType from ... import exc from ... import Identity from ... import schema as sa_schema from ... import Sequence from ... import sql from ... import text from ... import util from ...engine import cursor as _cursor from ...engine import default from ...engine import reflection from ...engine.reflection import ReflectionDefaults from ...sql import coercions from ...sql import compiler from ...sql import elements from ...sql import expression from ...sql import func from ...sql import quoted_name from ...sql import roles from ...sql import sqltypes from ...sql import try_cast as try_cast # noqa: F401 from ...sql import util as sql_util from ...sql._typing import is_sql_compiler from ...sql.compiler import InsertmanyvaluesSentinelOpts from ...sql.elements import TryCast as TryCast # noqa: F401 from ...types import BIGINT from ...types import BINARY from ...types import CHAR from ...types import DATE from ...types import DATETIME from ...types import DECIMAL from ...types import FLOAT from ...types import INTEGER from ...types import NCHAR from ...types import NUMERIC from ...types import NVARCHAR from ...types import SMALLINT from ...types import TEXT from ...types import VARCHAR from ...util import update_wrapper from ...util.typing import Literal if TYPE_CHECKING: from ...sql.dml import DMLState from ...sql.selectable import TableClause # https://sqlserverbuilds.blogspot.com/ MS_2017_VERSION = (14,) MS_2016_VERSION = (13,) MS_2014_VERSION = (12,) MS_2012_VERSION = (11,) MS_2008_VERSION = (10,) MS_2005_VERSION = (9,) MS_2000_VERSION = (8,) RESERVED_WORDS = { "add", "all", "alter", "and", "any", "as", "asc", "authorization", "backup", "begin", "between", "break", "browse", "bulk", "by", "cascade", "case", "check", "checkpoint", "close", "clustered", "coalesce", "collate", "column", "commit", "compute", "constraint", "contains", "containstable", "continue", "convert", "create", "cross", "current", "current_date", "current_time", "current_timestamp", "current_user", "cursor", "database", "dbcc", "deallocate", "declare", "default", "delete", "deny", "desc", "disk", "distinct", "distributed", "double", "drop", "dump", "else", "end", "errlvl", "escape", "except", "exec", "execute", "exists", "exit", "external", "fetch", "file", "fillfactor", "for", "foreign", "freetext", "freetexttable", "from", "full", "function", "goto", "grant", "group", "having", "holdlock", "identity", "identity_insert", "identitycol", "if", "in", "index", "inner", "insert", "intersect", "into", "is", "join", "key", "kill", "left", "like", "lineno", "load", "merge", "national", "nocheck", "nonclustered", "not", "null", "nullif", "of", "off", "offsets", "on", "open", "opendatasource", "openquery", "openrowset", "openxml", "option", "or", "order", "outer", "over", "percent", "pivot", "plan", "precision", "primary", "print", "proc", "procedure", "public", "raiserror", "read", "readtext", "reconfigure", "references", "replication", "restore", "restrict", "return", "revert", "revoke", "right", "rollback", "rowcount", "rowguidcol", "rule", "save", "schema", "securityaudit", "select", "session_user", "set", "setuser", "shutdown", "some", "statistics", "system_user", "table", "tablesample", "textsize", "then", "to", "top", "tran", "transaction", "trigger", "truncate", "tsequal", "union", "unique", "unpivot", "update", "updatetext", "use", "user", "values", "varying", "view", "waitfor", "when", "where", "while", "with", "writetext", } class REAL(sqltypes.REAL): """the SQL Server REAL datatype.""" def __init__(self, **kw): # REAL is a synonym for FLOAT(24) on SQL server. # it is only accepted as the word "REAL" in DDL, the numeric # precision value is not allowed to be present kw.setdefault("precision", 24) super().__init__(**kw) class DOUBLE_PRECISION(sqltypes.DOUBLE_PRECISION): """the SQL Server DOUBLE PRECISION datatype. .. versionadded:: 2.0.11 """ def __init__(self, **kw): # DOUBLE PRECISION is a synonym for FLOAT(53) on SQL server. # it is only accepted as the word "DOUBLE PRECISION" in DDL, # the numeric precision value is not allowed to be present kw.setdefault("precision", 53) super().__init__(**kw) class TINYINT(sqltypes.Integer): __visit_name__ = "TINYINT" # MSSQL DATE/TIME types have varied behavior, sometimes returning # strings. MSDate/TIME check for everything, and always # filter bind parameters into datetime objects (required by pyodbc, # not sure about other dialects). class _MSDate(sqltypes.Date): def bind_processor(self, dialect): def process(value): if type(value) == datetime.date: return datetime.datetime(value.year, value.month, value.day) else: return value return process _reg = re.compile(r"(\d+)-(\d+)-(\d+)") def result_processor(self, dialect, coltype): def process(value): if isinstance(value, datetime.datetime): return value.date() elif isinstance(value, str): m = self._reg.match(value) if not m: raise ValueError( "could not parse %r as a date value" % (value,) ) return datetime.date(*[int(x or 0) for x in m.groups()]) else: return value return process class TIME(sqltypes.TIME): def __init__(self, precision=None, **kwargs): self.precision = precision super().__init__() __zero_date = datetime.date(1900, 1, 1) def bind_processor(self, dialect): def process(value): if isinstance(value, datetime.datetime): value = datetime.datetime.combine( self.__zero_date, value.time() ) elif isinstance(value, datetime.time): """issue #5339 per: https://github.com/mkleehammer/pyodbc/wiki/Tips-and-Tricks-by-Database-Platform#time-columns pass TIME value as string """ # noqa value = str(value) return value return process _reg = re.compile(r"(\d+):(\d+):(\d+)(?:\.(\d{0,6}))?") def result_processor(self, dialect, coltype): def process(value): if isinstance(value, datetime.datetime): return value.time() elif isinstance(value, str): m = self._reg.match(value) if not m: raise ValueError( "could not parse %r as a time value" % (value,) ) return datetime.time(*[int(x or 0) for x in m.groups()]) else: return value return process _MSTime = TIME class _BASETIMEIMPL(TIME): __visit_name__ = "_BASETIMEIMPL" class _DateTimeBase: def bind_processor(self, dialect): def process(value): if type(value) == datetime.date: return datetime.datetime(value.year, value.month, value.day) else: return value return process class _MSDateTime(_DateTimeBase, sqltypes.DateTime): pass class SMALLDATETIME(_DateTimeBase, sqltypes.DateTime): __visit_name__ = "SMALLDATETIME" class DATETIME2(_DateTimeBase, sqltypes.DateTime): __visit_name__ = "DATETIME2" def __init__(self, precision=None, **kw): super().__init__(**kw) self.precision = precision class DATETIMEOFFSET(_DateTimeBase, sqltypes.DateTime): __visit_name__ = "DATETIMEOFFSET" def __init__(self, precision=None, **kw): super().__init__(**kw) self.precision = precision class _UnicodeLiteral: def literal_processor(self, dialect): def process(value): value = value.replace("'", "''") if dialect.identifier_preparer._double_percents: value = value.replace("%", "%%") return "N'%s'" % value return process class _MSUnicode(_UnicodeLiteral, sqltypes.Unicode): pass class _MSUnicodeText(_UnicodeLiteral, sqltypes.UnicodeText): pass class TIMESTAMP(sqltypes._Binary): """Implement the SQL Server TIMESTAMP type. Note this is **completely different** than the SQL Standard TIMESTAMP type, which is not supported by SQL Server. It is a read-only datatype that does not support INSERT of values. .. versionadded:: 1.2 .. seealso:: :class:`_mssql.ROWVERSION` """ __visit_name__ = "TIMESTAMP" # expected by _Binary to be present length = None def __init__(self, convert_int=False): """Construct a TIMESTAMP or ROWVERSION type. :param convert_int: if True, binary integer values will be converted to integers on read. .. versionadded:: 1.2 """ self.convert_int = convert_int def result_processor(self, dialect, coltype): super_ = super().result_processor(dialect, coltype) if self.convert_int: def process(value): if super_: value = super_(value) if value is not None: # https://stackoverflow.com/a/30403242/34549 value = int(codecs.encode(value, "hex"), 16) return value return process else: return super_ class ROWVERSION(TIMESTAMP): """Implement the SQL Server ROWVERSION type. The ROWVERSION datatype is a SQL Server synonym for the TIMESTAMP datatype, however current SQL Server documentation suggests using ROWVERSION for new datatypes going forward. The ROWVERSION datatype does **not** reflect (e.g. introspect) from the database as itself; the returned datatype will be :class:`_mssql.TIMESTAMP`. This is a read-only datatype that does not support INSERT of values. .. versionadded:: 1.2 .. seealso:: :class:`_mssql.TIMESTAMP` """ __visit_name__ = "ROWVERSION" class NTEXT(sqltypes.UnicodeText): """MSSQL NTEXT type, for variable-length unicode text up to 2^30 characters.""" __visit_name__ = "NTEXT" class VARBINARY(sqltypes.VARBINARY, sqltypes.LargeBinary): """The MSSQL VARBINARY type. This type adds additional features to the core :class:`_types.VARBINARY` type, including "deprecate_large_types" mode where either ``VARBINARY(max)`` or IMAGE is rendered, as well as the SQL Server ``FILESTREAM`` option. .. seealso:: :ref:`mssql_large_type_deprecation` """ __visit_name__ = "VARBINARY" def __init__(self, length=None, filestream=False): """ Construct a VARBINARY type. :param length: optional, a length for the column for use in DDL statements, for those binary types that accept a length, such as the MySQL BLOB type. :param filestream=False: if True, renders the ``FILESTREAM`` keyword in the table definition. In this case ``length`` must be ``None`` or ``'max'``. .. versionadded:: 1.4.31 """ self.filestream = filestream if self.filestream and length not in (None, "max"): raise ValueError( "length must be None or 'max' when setting filestream" ) super().__init__(length=length) class IMAGE(sqltypes.LargeBinary): __visit_name__ = "IMAGE" class XML(sqltypes.Text): """MSSQL XML type. This is a placeholder type for reflection purposes that does not include any Python-side datatype support. It also does not currently support additional arguments, such as "CONTENT", "DOCUMENT", "xml_schema_collection". """ __visit_name__ = "XML" class BIT(sqltypes.Boolean): """MSSQL BIT type. Both pyodbc and pymssql return values from BIT columns as Python <class 'bool'> so just subclass Boolean. """ __visit_name__ = "BIT" class MONEY(sqltypes.TypeEngine): __visit_name__ = "MONEY" class SMALLMONEY(sqltypes.TypeEngine): __visit_name__ = "SMALLMONEY" class MSUUid(sqltypes.Uuid): def bind_processor(self, dialect): if self.native_uuid: # this is currently assuming pyodbc; might not work for # some other mssql driver return None else: if self.as_uuid: def process(value): if value is not None: value = value.hex return value return process else: def process(value): if value is not None: value = value.replace("-", "").replace("''", "'") return value return process def literal_processor(self, dialect): if self.native_uuid: def process(value): return f"""'{str(value).replace("''", "'")}'""" return process else: if self.as_uuid: def process(value): return f"""'{value.hex}'""" return process else: def process(value): return f"""'{ value.replace("-", "").replace("'", "''") }'""" return process class UNIQUEIDENTIFIER(sqltypes.Uuid[sqltypes._UUID_RETURN]): __visit_name__ = "UNIQUEIDENTIFIER" @overload def __init__( self: UNIQUEIDENTIFIER[_python_UUID], as_uuid: Literal[True] = ... ): ... @overload def __init__( self: UNIQUEIDENTIFIER[str], as_uuid: Literal[False] = ... ): ... def __init__(self, as_uuid: bool = True): """Construct a :class:`_mssql.UNIQUEIDENTIFIER` type. :param as_uuid=True: if True, values will be interpreted as Python uuid objects, converting to/from string via the DBAPI. .. versionchanged: 2.0 Added direct "uuid" support to the :class:`_mssql.UNIQUEIDENTIFIER` datatype; uuid interpretation defaults to ``True``. """ self.as_uuid = as_uuid self.native_uuid = True class SQL_VARIANT(sqltypes.TypeEngine): __visit_name__ = "SQL_VARIANT" # old names. MSDateTime = _MSDateTime MSDate = _MSDate MSReal = REAL MSTinyInteger = TINYINT MSTime = TIME MSSmallDateTime = SMALLDATETIME MSDateTime2 = DATETIME2 MSDateTimeOffset = DATETIMEOFFSET MSText = TEXT MSNText = NTEXT MSString = VARCHAR MSNVarchar = NVARCHAR MSChar = CHAR MSNChar = NCHAR MSBinary = BINARY MSVarBinary = VARBINARY MSImage = IMAGE MSBit = BIT MSMoney = MONEY MSSmallMoney = SMALLMONEY MSUniqueIdentifier = UNIQUEIDENTIFIER MSVariant = SQL_VARIANT ischema_names = { "int": INTEGER, "bigint": BIGINT, "smallint": SMALLINT, "tinyint": TINYINT, "varchar": VARCHAR, "nvarchar": NVARCHAR, "char": CHAR, "nchar": NCHAR, "text": TEXT, "ntext": NTEXT, "decimal": DECIMAL, "numeric": NUMERIC, "float": FLOAT, "datetime": DATETIME, "datetime2": DATETIME2, "datetimeoffset": DATETIMEOFFSET, "date": DATE, "time": TIME, "smalldatetime": SMALLDATETIME, "binary": BINARY, "varbinary": VARBINARY, "bit": BIT, "real": REAL, "double precision": DOUBLE_PRECISION, "image": IMAGE, "xml": XML, "timestamp": TIMESTAMP, "money": MONEY, "smallmoney": SMALLMONEY, "uniqueidentifier": UNIQUEIDENTIFIER, "sql_variant": SQL_VARIANT, } class MSTypeCompiler(compiler.GenericTypeCompiler): def _extend(self, spec, type_, length=None): """Extend a string-type declaration with standard SQL COLLATE annotations. """ if getattr(type_, "collation", None): collation = "COLLATE %s" % type_.collation else: collation = None if not length: length = type_.length if length: spec = spec + "(%s)" % length return " ".join([c for c in (spec, collation) if c is not None]) def visit_double(self, type_, **kw): return self.visit_DOUBLE_PRECISION(type_, **kw) def visit_FLOAT(self, type_, **kw): precision = getattr(type_, "precision", None) if precision is None: return "FLOAT" else: return "FLOAT(%(precision)s)" % {"precision": precision} def visit_TINYINT(self, type_, **kw): return "TINYINT" def visit_TIME(self, type_, **kw): precision = getattr(type_, "precision", None) if precision is not None: return "TIME(%s)" % precision else: return "TIME" def visit_TIMESTAMP(self, type_, **kw): return "TIMESTAMP" def visit_ROWVERSION(self, type_, **kw): return "ROWVERSION" def visit_datetime(self, type_, **kw): if type_.timezone: return self.visit_DATETIMEOFFSET(type_, **kw) else: return self.visit_DATETIME(type_, **kw) def visit_DATETIMEOFFSET(self, type_, **kw): precision = getattr(type_, "precision", None) if precision is not None: return "DATETIMEOFFSET(%s)" % type_.precision else: return "DATETIMEOFFSET" def visit_DATETIME2(self, type_, **kw): precision = getattr(type_, "precision", None) if precision is not None: return "DATETIME2(%s)" % precision else: return "DATETIME2" def visit_SMALLDATETIME(self, type_, **kw): return "SMALLDATETIME" def visit_unicode(self, type_, **kw): return self.visit_NVARCHAR(type_, **kw) def visit_text(self, type_, **kw): if self.dialect.deprecate_large_types: return self.visit_VARCHAR(type_, **kw) else: return self.visit_TEXT(type_, **kw) def visit_unicode_text(self, type_, **kw): if self.dialect.deprecate_large_types: return self.visit_NVARCHAR(type_, **kw) else: return self.visit_NTEXT(type_, **kw) def visit_NTEXT(self, type_, **kw): return self._extend("NTEXT", type_) def visit_TEXT(self, type_, **kw): return self._extend("TEXT", type_) def visit_VARCHAR(self, type_, **kw): return self._extend("VARCHAR", type_, length=type_.length or "max") def visit_CHAR(self, type_, **kw): return self._extend("CHAR", type_) def visit_NCHAR(self, type_, **kw): return self._extend("NCHAR", type_) def visit_NVARCHAR(self, type_, **kw): return self._extend("NVARCHAR", type_, length=type_.length or "max") def visit_date(self, type_, **kw): if self.dialect.server_version_info < MS_2008_VERSION: return self.visit_DATETIME(type_, **kw) else: return self.visit_DATE(type_, **kw) def visit__BASETIMEIMPL(self, type_, **kw): return self.visit_time(type_, **kw) def visit_time(self, type_, **kw): if self.dialect.server_version_info < MS_2008_VERSION: return self.visit_DATETIME(type_, **kw) else: return self.visit_TIME(type_, **kw) def visit_large_binary(self, type_, **kw): if self.dialect.deprecate_large_types: return self.visit_VARBINARY(type_, **kw) else: return self.visit_IMAGE(type_, **kw) def visit_IMAGE(self, type_, **kw): return "IMAGE" def visit_XML(self, type_, **kw): return "XML" def visit_VARBINARY(self, type_, **kw): text = self._extend("VARBINARY", type_, length=type_.length or "max") if getattr(type_, "filestream", False): text += " FILESTREAM" return text def visit_boolean(self, type_, **kw): return self.visit_BIT(type_) def visit_BIT(self, type_, **kw): return "BIT" def visit_JSON(self, type_, **kw): # this is a bit of a break with SQLAlchemy's convention of # "UPPERCASE name goes to UPPERCASE type name with no modification" return self._extend("NVARCHAR", type_, length="max") def visit_MONEY(self, type_, **kw): return "MONEY" def visit_SMALLMONEY(self, type_, **kw): return "SMALLMONEY" def visit_uuid(self, type_, **kw): if type_.native_uuid: return self.visit_UNIQUEIDENTIFIER(type_, **kw) else: return super().visit_uuid(type_, **kw) def visit_UNIQUEIDENTIFIER(self, type_, **kw): return "UNIQUEIDENTIFIER" def visit_SQL_VARIANT(self, type_, **kw): return "SQL_VARIANT" class MSExecutionContext(default.DefaultExecutionContext): _enable_identity_insert = False _select_lastrowid = False _lastrowid = None dialect: MSDialect def _opt_encode(self, statement): if self.compiled and self.compiled.schema_translate_map: rst = self.compiled.preparer._render_schema_translates statement = rst(statement, self.compiled.schema_translate_map) return statement def pre_exec(self): """Activate IDENTITY_INSERT if needed.""" if self.isinsert: if TYPE_CHECKING: assert is_sql_compiler(self.compiled) assert isinstance(self.compiled.compile_state, DMLState) assert isinstance( self.compiled.compile_state.dml_table, TableClause ) tbl = self.compiled.compile_state.dml_table id_column = tbl._autoincrement_column if id_column is not None and ( not isinstance(id_column.default, Sequence) ): insert_has_identity = True compile_state = self.compiled.dml_compile_state self._enable_identity_insert = ( id_column.key in self.compiled_parameters[0] ) or ( compile_state._dict_parameters and (id_column.key in compile_state._insert_col_keys) ) else: insert_has_identity = False self._enable_identity_insert = False self._select_lastrowid = ( not self.compiled.inline and insert_has_identity and not self.compiled.effective_returning and not self._enable_identity_insert and not self.executemany ) if self._enable_identity_insert: self.root_connection._cursor_execute( self.cursor, self._opt_encode( "SET IDENTITY_INSERT %s ON" % self.identifier_preparer.format_table(tbl) ), (), self, ) def post_exec(self): """Disable IDENTITY_INSERT if enabled.""" conn = self.root_connection if self.isinsert or self.isupdate or self.isdelete: self._rowcount = self.cursor.rowcount if self._select_lastrowid: if self.dialect.use_scope_identity: conn._cursor_execute( self.cursor, "SELECT scope_identity() AS lastrowid", (), self, ) else: conn._cursor_execute( self.cursor, "SELECT @@identity AS lastrowid", (), self ) # fetchall() ensures the cursor is consumed without closing it row = self.cursor.fetchall()[0] self._lastrowid = int(row[0]) self.cursor_fetch_strategy = _cursor._NO_CURSOR_DML elif ( self.compiled is not None and is_sql_compiler(self.compiled) and self.compiled.effective_returning ): self.cursor_fetch_strategy = ( _cursor.FullyBufferedCursorFetchStrategy( self.cursor, self.cursor.description, self.cursor.fetchall(), ) ) if self._enable_identity_insert: if TYPE_CHECKING: assert is_sql_compiler(self.compiled) assert isinstance(self.compiled.compile_state, DMLState) assert isinstance( self.compiled.compile_state.dml_table, TableClause ) conn._cursor_execute( self.cursor, self._opt_encode( "SET IDENTITY_INSERT %s OFF" % self.identifier_preparer.format_table( self.compiled.compile_state.dml_table ) ), (), self, ) def get_lastrowid(self): return self._lastrowid def handle_dbapi_exception(self, e): if self._enable_identity_insert: try: self.cursor.execute( self._opt_encode( "SET IDENTITY_INSERT %s OFF" % self.identifier_preparer.format_table( self.compiled.compile_state.dml_table ) ) ) except Exception: pass def fire_sequence(self, seq, type_): return self._execute_scalar( ( "SELECT NEXT VALUE FOR %s" % self.identifier_preparer.format_sequence(seq) ), type_, ) def get_insert_default(self, column): if ( isinstance(column, sa_schema.Column) and column is column.table._autoincrement_column and isinstance(column.default, sa_schema.Sequence) and column.default.optional ): return None return super().get_insert_default(column) class MSSQLCompiler(compiler.SQLCompiler): returning_precedes_values = True extract_map = util.update_copy( compiler.SQLCompiler.extract_map, { "doy": "dayofyear", "dow": "weekday", "milliseconds": "millisecond", "microseconds": "microsecond", }, ) def __init__(self, *args, **kwargs): self.tablealiases = {} super().__init__(*args, **kwargs) def _format_frame_clause(self, range_, **kw): kw["literal_execute"] = True return super()._format_frame_clause(range_, **kw) def _with_legacy_schema_aliasing(fn): def decorate(self, *arg, **kw): if self.dialect.legacy_schema_aliasing: return fn(self, *arg, **kw) else: super_ = getattr(super(MSSQLCompiler, self), fn.__name__) return super_(*arg, **kw) return decorate def visit_now_func(self, fn, **kw): return "CURRENT_TIMESTAMP" def visit_current_date_func(self, fn, **kw): return "GETDATE()" def visit_length_func(self, fn, **kw): return "LEN%s" % self.function_argspec(fn, **kw) def visit_char_length_func(self, fn, **kw): return "LEN%s" % self.function_argspec(fn, **kw) def visit_aggregate_strings_func(self, fn, **kw): expr = fn.clauses.clauses[0]._compiler_dispatch(self, **kw) kw["literal_execute"] = True delimeter = fn.clauses.clauses[1]._compiler_dispatch(self, **kw) return f"string_agg({expr}, {delimeter})" def visit_concat_op_expression_clauselist( self, clauselist, operator, **kw ): return " + ".join(self.process(elem, **kw) for elem in clauselist) def visit_concat_op_binary(self, binary, operator, **kw): return "%s + %s" % ( self.process(binary.left, **kw), self.process(binary.right, **kw), ) def visit_true(self, expr, **kw): return "1" def visit_false(self, expr, **kw): return "0" def visit_match_op_binary(self, binary, operator, **kw): return "CONTAINS (%s, %s)" % ( self.process(binary.left, **kw), self.process(binary.right, **kw), ) def get_select_precolumns(self, select, **kw): """MS-SQL puts TOP, it's version of LIMIT here""" s = super().get_select_precolumns(select, **kw) if select._has_row_limiting_clause and self._use_top(select): # ODBC drivers and possibly others # don't support bind params in the SELECT clause on SQL Server. # so have to use literal here. kw["literal_execute"] = True s += "TOP %s " % self.process( self._get_limit_or_fetch(select), **kw ) if select._fetch_clause is not None: if select._fetch_clause_options["percent"]: s += "PERCENT " if select._fetch_clause_options["with_ties"]: s += "WITH TIES " return s def get_from_hint_text(self, table, text): return text def get_crud_hint_text(self, table, text): return text def _get_limit_or_fetch(self, select): if select._fetch_clause is None: return select._limit_clause else: return select._fetch_clause def _use_top(self, select): return (select._offset_clause is None) and ( select._simple_int_clause(select._limit_clause) or ( # limit can use TOP with is by itself. fetch only uses TOP # when it needs to because of PERCENT and/or WITH TIES # TODO: Why? shouldn't we use TOP always ? select._simple_int_clause(select._fetch_clause) and ( select._fetch_clause_options["percent"] or select._fetch_clause_options["with_ties"] ) ) ) def limit_clause(self, cs, **kwargs): return "" def _check_can_use_fetch_limit(self, select): # to use ROW_NUMBER(), an ORDER BY is required. # OFFSET are FETCH are options of the ORDER BY clause if not select._order_by_clause.clauses: raise exc.CompileError( "MSSQL requires an order_by when " "using an OFFSET or a non-simple " "LIMIT clause" ) if select._fetch_clause_options is not None and ( select._fetch_clause_options["percent"] or select._fetch_clause_options["with_ties"] ): raise exc.CompileError( "MSSQL needs TOP to use PERCENT and/or WITH TIES. " "Only simple fetch without offset can be used." ) def _row_limit_clause(self, select, **kw): """MSSQL 2012 supports OFFSET/FETCH operators Use it instead subquery with row_number """ if self.dialect._supports_offset_fetch and not self._use_top(select): self._check_can_use_fetch_limit(select) return self.fetch_clause( select, fetch_clause=self._get_limit_or_fetch(select), require_offset=True, **kw, ) else: return "" def visit_try_cast(self, element, **kw): return "TRY_CAST (%s AS %s)" % ( self.process(element.clause, **kw), self.process(element.typeclause, **kw), ) def translate_select_structure(self, select_stmt, **kwargs): """Look for ``LIMIT`` and OFFSET in a select statement, and if so tries to wrap it in a subquery with ``row_number()`` criterion. MSSQL 2012 and above are excluded """ select = select_stmt if ( select._has_row_limiting_clause and not self.dialect._supports_offset_fetch and not self._use_top(select) and not getattr(select, "_mssql_visit", None) ): self._check_can_use_fetch_limit(select) _order_by_clauses = [ sql_util.unwrap_label_reference(elem) for elem in select._order_by_clause.clauses ] limit_clause = self._get_limit_or_fetch(select) offset_clause = select._offset_clause select = select._generate() select._mssql_visit = True select = ( select.add_columns( sql.func.ROW_NUMBER() .over(order_by=_order_by_clauses) .label("mssql_rn") ) .order_by(None) .alias() ) mssql_rn = sql.column("mssql_rn") limitselect = sql.select( *[c for c in select.c if c.key != "mssql_rn"] ) if offset_clause is not None: limitselect = limitselect.where(mssql_rn > offset_clause) if limit_clause is not None: limitselect = limitselect.where( mssql_rn <= (limit_clause + offset_clause) ) else: limitselect = limitselect.where(mssql_rn <= (limit_clause)) return limitselect else: return select @_with_legacy_schema_aliasing def visit_table(self, table, mssql_aliased=False, iscrud=False, **kwargs): if mssql_aliased is table or iscrud: return super().visit_table(table, **kwargs) # alias schema-qualified tables alias = self._schema_aliased_table(table) if alias is not None: return self.process(alias, mssql_aliased=table, **kwargs) else: return super().visit_table(table, **kwargs) @_with_legacy_schema_aliasing def visit_alias(self, alias, **kw): # translate for schema-qualified table aliases kw["mssql_aliased"] = alias.element return super().visit_alias(alias, **kw) @_with_legacy_schema_aliasing def visit_column(self, column, add_to_result_map=None, **kw): if ( column.table is not None and (not self.isupdate and not self.isdelete) or self.is_subquery() ): # translate for schema-qualified table aliases t = self._schema_aliased_table(column.table) if t is not None: converted = elements._corresponding_column_or_error(t, column) if add_to_result_map is not None: add_to_result_map( column.name, column.name, (column, column.name, column.key), column.type, ) return super().visit_column(converted, **kw) return super().visit_column( column, add_to_result_map=add_to_result_map, **kw ) def _schema_aliased_table(self, table): if getattr(table, "schema", None) is not None: if table not in self.tablealiases: self.tablealiases[table] = table.alias() return self.tablealiases[table] else: return None def visit_extract(self, extract, **kw): field = self.extract_map.get(extract.field, extract.field) return "DATEPART(%s, %s)" % (field, self.process(extract.expr, **kw)) def visit_savepoint(self, savepoint_stmt, **kw): return "SAVE TRANSACTION %s" % self.preparer.format_savepoint( savepoint_stmt ) def visit_rollback_to_savepoint(self, savepoint_stmt, **kw): return "ROLLBACK TRANSACTION %s" % self.preparer.format_savepoint( savepoint_stmt ) def visit_binary(self, binary, **kwargs): """Move bind parameters to the right-hand side of an operator, where possible. """ if ( isinstance(binary.left, expression.BindParameter) and binary.operator == operator.eq and not isinstance(binary.right, expression.BindParameter) ): return self.process( expression.BinaryExpression( binary.right, binary.left, binary.operator ), **kwargs, ) return super().visit_binary(binary, **kwargs) def returning_clause( self, stmt, returning_cols, *, populate_result_map, **kw ): # SQL server returning clause requires that the columns refer to # the virtual table names "inserted" or "deleted". Here, we make # a simple alias of our table with that name, and then adapt the # columns we have from the list of RETURNING columns to that new name # so that they render as "inserted.<colname>" / "deleted.<colname>". if stmt.is_insert or stmt.is_update: target = stmt.table.alias("inserted") elif stmt.is_delete: target = stmt.table.alias("deleted") else: assert False, "expected Insert, Update or Delete statement" adapter = sql_util.ClauseAdapter(target) # adapter.traverse() takes a column from our target table and returns # the one that is linked to the "inserted" / "deleted" tables. So in # order to retrieve these values back from the result (e.g. like # row[column]), tell the compiler to also add the original unadapted # column to the result map. Before #4877, these were (unknowingly) # falling back using string name matching in the result set which # necessarily used an expensive KeyError in order to match. columns = [ self._label_returning_column( stmt, adapter.traverse(column), populate_result_map, {"result_map_targets": (column,)}, fallback_label_name=fallback_label_name, column_is_repeated=repeated, name=name, proxy_name=proxy_name, **kw, ) for ( name, proxy_name, fallback_label_name, column, repeated, ) in stmt._generate_columns_plus_names( True, cols=expression._select_iterables(returning_cols) ) ] return "OUTPUT " + ", ".join(columns) def get_cte_preamble(self, recursive): # SQL Server finds it too inconvenient to accept # an entirely optional, SQL standard specified, # "RECURSIVE" word with their "WITH", # so here we go return "WITH" def label_select_column(self, select, column, asfrom): if isinstance(column, expression.Function): return column.label(None) else: return super().label_select_column(select, column, asfrom) def for_update_clause(self, select, **kw): # "FOR UPDATE" is only allowed on "DECLARE CURSOR" which # SQLAlchemy doesn't use return "" def order_by_clause(self, select, **kw): # MSSQL only allows ORDER BY in subqueries if there is a LIMIT: # "The ORDER BY clause is invalid in views, inline functions, # derived tables, subqueries, and common table expressions, # unless TOP, OFFSET or FOR XML is also specified." if ( self.is_subquery() and not self._use_top(select) and ( select._offset is None or not self.dialect._supports_offset_fetch ) ): # avoid processing the order by clause if we won't end up # using it, because we don't want all the bind params tacked # onto the positional list if that is what the dbapi requires return "" order_by = self.process(select._order_by_clause, **kw) if order_by: return " ORDER BY " + order_by else: return "" def update_from_clause( self, update_stmt, from_table, extra_froms, from_hints, **kw ): """Render the UPDATE..FROM clause specific to MSSQL. In MSSQL, if the UPDATE statement involves an alias of the table to be updated, then the table itself must be added to the FROM list as well. Otherwise, it is optional. Here, we add it regardless. """ return "FROM " + ", ".join( t._compiler_dispatch(self, asfrom=True, fromhints=from_hints, **kw) for t in [from_table] + extra_froms ) def delete_table_clause(self, delete_stmt, from_table, extra_froms, **kw): """If we have extra froms make sure we render any alias as hint.""" ashint = False if extra_froms: ashint = True return from_table._compiler_dispatch( self, asfrom=True, iscrud=True, ashint=ashint, **kw ) def delete_extra_from_clause( self, delete_stmt, from_table, extra_froms, from_hints, **kw ): """Render the DELETE .. FROM clause specific to MSSQL. Yes, it has the FROM keyword twice. """ return "FROM " + ", ".join( t._compiler_dispatch(self, asfrom=True, fromhints=from_hints, **kw) for t in [from_table] + extra_froms ) def visit_empty_set_expr(self, type_, **kw): return "SELECT 1 WHERE 1!=1" def visit_is_distinct_from_binary(self, binary, operator, **kw): return "NOT EXISTS (SELECT %s INTERSECT SELECT %s)" % ( self.process(binary.left), self.process(binary.right), ) def visit_is_not_distinct_from_binary(self, binary, operator, **kw): return "EXISTS (SELECT %s INTERSECT SELECT %s)" % ( self.process(binary.left), self.process(binary.right), ) def _render_json_extract_from_binary(self, binary, operator, **kw): # note we are intentionally calling upon the process() calls in the # order in which they appear in the SQL String as this is used # by positional parameter rendering if binary.type._type_affinity is sqltypes.JSON: return "JSON_QUERY(%s, %s)" % ( self.process(binary.left, **kw), self.process(binary.right, **kw), ) # as with other dialects, start with an explicit test for NULL case_expression = "CASE JSON_VALUE(%s, %s) WHEN NULL THEN NULL" % ( self.process(binary.left, **kw), self.process(binary.right, **kw), ) if binary.type._type_affinity is sqltypes.Integer: type_expression = "ELSE CAST(JSON_VALUE(%s, %s) AS INTEGER)" % ( self.process(binary.left, **kw), self.process(binary.right, **kw), ) elif binary.type._type_affinity is sqltypes.Numeric: type_expression = "ELSE CAST(JSON_VALUE(%s, %s) AS %s)" % ( self.process(binary.left, **kw), self.process(binary.right, **kw), ( "FLOAT" if isinstance(binary.type, sqltypes.Float) else "NUMERIC(%s, %s)" % (binary.type.precision, binary.type.scale) ), ) elif binary.type._type_affinity is sqltypes.Boolean: # the NULL handling is particularly weird with boolean, so # explicitly return numeric (BIT) constants type_expression = ( "WHEN 'true' THEN 1 WHEN 'false' THEN 0 ELSE NULL" ) elif binary.type._type_affinity is sqltypes.String: # TODO: does this comment (from mysql) apply to here, too? # this fails with a JSON value that's a four byte unicode # string. SQLite has the same problem at the moment type_expression = "ELSE JSON_VALUE(%s, %s)" % ( self.process(binary.left, **kw), self.process(binary.right, **kw), ) else: # other affinity....this is not expected right now type_expression = "ELSE JSON_QUERY(%s, %s)" % ( self.process(binary.left, **kw), self.process(binary.right, **kw), ) return case_expression + " " + type_expression + " END" def visit_json_getitem_op_binary(self, binary, operator, **kw): return self._render_json_extract_from_binary(binary, operator, **kw) def visit_json_path_getitem_op_binary(self, binary, operator, **kw): return self._render_json_extract_from_binary(binary, operator, **kw) def visit_sequence(self, seq, **kw): return "NEXT VALUE FOR %s" % self.preparer.format_sequence(seq) class MSSQLStrictCompiler(MSSQLCompiler): """A subclass of MSSQLCompiler which disables the usage of bind parameters where not allowed natively by MS-SQL. A dialect may use this compiler on a platform where native binds are used. """ ansi_bind_rules = True def visit_in_op_binary(self, binary, operator, **kw): kw["literal_execute"] = True return "%s IN %s" % ( self.process(binary.left, **kw), self.process(binary.right, **kw), ) def visit_not_in_op_binary(self, binary, operator, **kw): kw["literal_execute"] = True return "%s NOT IN %s" % ( self.process(binary.left, **kw), self.process(binary.right, **kw), ) def render_literal_value(self, value, type_): """ For date and datetime values, convert to a string format acceptable to MSSQL. That seems to be the so-called ODBC canonical date format which looks like this: yyyy-mm-dd hh:mi:ss.mmm(24h) For other data types, call the base class implementation. """ # datetime and date are both subclasses of datetime.date if issubclass(type(value), datetime.date): # SQL Server wants single quotes around the date string. return "'" + str(value) + "'" else: return super().render_literal_value(value, type_) class MSDDLCompiler(compiler.DDLCompiler): def get_column_specification(self, column, **kwargs): colspec = self.preparer.format_column(column) # type is not accepted in a computed column if column.computed is not None: colspec += " " + self.process(column.computed) else: colspec += " " + self.dialect.type_compiler_instance.process( column.type, type_expression=column ) if column.nullable is not None: if ( not column.nullable or column.primary_key or isinstance(column.default, sa_schema.Sequence) or column.autoincrement is True or column.identity ): colspec += " NOT NULL" elif column.computed is None: # don't specify "NULL" for computed columns colspec += " NULL" if column.table is None: raise exc.CompileError( "mssql requires Table-bound columns " "in order to generate DDL" ) d_opt = column.dialect_options["mssql"] start = d_opt["identity_start"] increment = d_opt["identity_increment"] if start is not None or increment is not None: if column.identity: raise exc.CompileError( "Cannot specify options 'mssql_identity_start' and/or " "'mssql_identity_increment' while also using the " "'Identity' construct." ) util.warn_deprecated( "The dialect options 'mssql_identity_start' and " "'mssql_identity_increment' are deprecated. " "Use the 'Identity' object instead.", "1.4", ) if column.identity: colspec += self.process(column.identity, **kwargs) elif ( column is column.table._autoincrement_column or column.autoincrement is True ) and ( not isinstance(column.default, Sequence) or column.default.optional ): colspec += self.process(Identity(start=start, increment=increment)) else: default = self.get_column_default_string(column) if default is not None: colspec += " DEFAULT " + default return colspec def visit_create_index(self, create, include_schema=False, **kw): index = create.element self._verify_index_table(index) preparer = self.preparer text = "CREATE " if index.unique: text += "UNIQUE " # handle clustering option clustered = index.dialect_options["mssql"]["clustered"] if clustered is not None: if clustered: text += "CLUSTERED " else: text += "NONCLUSTERED " # handle columnstore option (has no negative value) columnstore = index.dialect_options["mssql"]["columnstore"] if columnstore: text += "COLUMNSTORE " text += "INDEX %s ON %s" % ( self._prepared_index_name(index, include_schema=include_schema), preparer.format_table(index.table), ) # in some case mssql allows indexes with no columns defined if len(index.expressions) > 0: text += " (%s)" % ", ".join( self.sql_compiler.process( expr, include_table=False, literal_binds=True ) for expr in index.expressions ) # handle other included columns if index.dialect_options["mssql"]["include"]: inclusions = [ index.table.c[col] if isinstance(col, str) else col for col in index.dialect_options["mssql"]["include"] ] text += " INCLUDE (%s)" % ", ".join( [preparer.quote(c.name) for c in inclusions] ) whereclause = index.dialect_options["mssql"]["where"] if whereclause is not None: whereclause = coercions.expect( roles.DDLExpressionRole, whereclause ) where_compiled = self.sql_compiler.process( whereclause, include_table=False, literal_binds=True ) text += " WHERE " + where_compiled return text def visit_drop_index(self, drop, **kw): return "\nDROP INDEX %s ON %s" % ( self._prepared_index_name(drop.element, include_schema=False), self.preparer.format_table(drop.element.table), ) def visit_primary_key_constraint(self, constraint, **kw): if len(constraint) == 0: return "" text = "" if constraint.name is not None: text += "CONSTRAINT %s " % self.preparer.format_constraint( constraint ) text += "PRIMARY KEY " clustered = constraint.dialect_options["mssql"]["clustered"] if clustered is not None: if clustered: text += "CLUSTERED " else: text += "NONCLUSTERED " text += "(%s)" % ", ".join( self.preparer.quote(c.name) for c in constraint ) text += self.define_constraint_deferrability(constraint) return text def visit_unique_constraint(self, constraint, **kw): if len(constraint) == 0: return "" text = "" if constraint.name is not None: formatted_name = self.preparer.format_constraint(constraint) if formatted_name is not None: text += "CONSTRAINT %s " % formatted_name text += "UNIQUE %s" % self.define_unique_constraint_distinct( constraint, **kw ) clustered = constraint.dialect_options["mssql"]["clustered"] if clustered is not None: if clustered: text += "CLUSTERED " else: text += "NONCLUSTERED " text += "(%s)" % ", ".join( self.preparer.quote(c.name) for c in constraint ) text += self.define_constraint_deferrability(constraint) return text def visit_computed_column(self, generated, **kw): text = "AS (%s)" % self.sql_compiler.process( generated.sqltext, include_table=False, literal_binds=True ) # explicitly check for True|False since None means server default if generated.persisted is True: text += " PERSISTED" return text def visit_set_table_comment(self, create, **kw): schema = self.preparer.schema_for_object(create.element) schema_name = schema if schema else self.dialect.default_schema_name return ( "execute sp_addextendedproperty 'MS_Description', " "{}, 'schema', {}, 'table', {}".format( self.sql_compiler.render_literal_value( create.element.comment, sqltypes.NVARCHAR() ), self.preparer.quote_schema(schema_name), self.preparer.format_table(create.element, use_schema=False), ) ) def visit_drop_table_comment(self, drop, **kw): schema = self.preparer.schema_for_object(drop.element) schema_name = schema if schema else self.dialect.default_schema_name return ( "execute sp_dropextendedproperty 'MS_Description', 'schema', " "{}, 'table', {}".format( self.preparer.quote_schema(schema_name), self.preparer.format_table(drop.element, use_schema=False), ) ) def visit_set_column_comment(self, create, **kw): schema = self.preparer.schema_for_object(create.element.table) schema_name = schema if schema else self.dialect.default_schema_name return ( "execute sp_addextendedproperty 'MS_Description', " "{}, 'schema', {}, 'table', {}, 'column', {}".format( self.sql_compiler.render_literal_value( create.element.comment, sqltypes.NVARCHAR() ), self.preparer.quote_schema(schema_name), self.preparer.format_table( create.element.table, use_schema=False ), self.preparer.format_column(create.element), ) ) def visit_drop_column_comment(self, drop, **kw): schema = self.preparer.schema_for_object(drop.element.table) schema_name = schema if schema else self.dialect.default_schema_name return ( "execute sp_dropextendedproperty 'MS_Description', 'schema', " "{}, 'table', {}, 'column', {}".format( self.preparer.quote_schema(schema_name), self.preparer.format_table( drop.element.table, use_schema=False ), self.preparer.format_column(drop.element), ) ) def visit_create_sequence(self, create, **kw): prefix = None if create.element.data_type is not None: data_type = create.element.data_type prefix = " AS %s" % self.type_compiler.process(data_type) return super().visit_create_sequence(create, prefix=prefix, **kw) def visit_identity_column(self, identity, **kw): text = " IDENTITY" if identity.start is not None or identity.increment is not None: start = 1 if identity.start is None else identity.start increment = 1 if identity.increment is None else identity.increment text += "(%s,%s)" % (start, increment) return text class MSIdentifierPreparer(compiler.IdentifierPreparer): reserved_words = RESERVED_WORDS def __init__(self, dialect): super().__init__( dialect, initial_quote="[", final_quote="]", quote_case_sensitive_collations=False, ) def _escape_identifier(self, value): return value.replace("]", "]]") def _unescape_identifier(self, value): return value.replace("]]", "]") def quote_schema(self, schema, force=None): """Prepare a quoted table and schema name.""" # need to re-implement the deprecation warning entirely if force is not None: # not using the util.deprecated_params() decorator in this # case because of the additional function call overhead on this # very performance-critical spot. util.warn_deprecated( "The IdentifierPreparer.quote_schema.force parameter is " "deprecated and will be removed in a future release. This " "flag has no effect on the behavior of the " "IdentifierPreparer.quote method; please refer to " "quoted_name().", version="1.3", ) dbname, owner = _schema_elements(schema) if dbname: result = "%s.%s" % (self.quote(dbname), self.quote(owner)) elif owner: result = self.quote(owner) else: result = "" return result def _db_plus_owner_listing(fn): def wrap(dialect, connection, schema=None, **kw): dbname, owner = _owner_plus_db(dialect, schema) return _switch_db( dbname, connection, fn, dialect, connection, dbname, owner, schema, **kw, ) return update_wrapper(wrap, fn) def _db_plus_owner(fn): def wrap(dialect, connection, tablename, schema=None, **kw): dbname, owner = _owner_plus_db(dialect, schema) return _switch_db( dbname, connection, fn, dialect, connection, tablename, dbname, owner, schema, **kw, ) return update_wrapper(wrap, fn) def _switch_db(dbname, connection, fn, *arg, **kw): if dbname: current_db = connection.exec_driver_sql("select db_name()").scalar() if current_db != dbname: connection.exec_driver_sql( "use %s" % connection.dialect.identifier_preparer.quote(dbname) ) try: return fn(*arg, **kw) finally: if dbname and current_db != dbname: connection.exec_driver_sql( "use %s" % connection.dialect.identifier_preparer.quote(current_db) ) def _owner_plus_db(dialect, schema): if not schema: return None, dialect.default_schema_name else: return _schema_elements(schema) _memoized_schema = util.LRUCache() def _schema_elements(schema): if isinstance(schema, quoted_name) and schema.quote: return None, schema if schema in _memoized_schema: return _memoized_schema[schema] # tests for this function are in: # test/dialect/mssql/test_reflection.py -> # OwnerPlusDBTest.test_owner_database_pairs # test/dialect/mssql/test_compiler.py -> test_force_schema_* # test/dialect/mssql/test_compiler.py -> test_schema_many_tokens_* # if schema.startswith("__[SCHEMA_"): return None, schema push = [] symbol = "" bracket = False has_brackets = False for token in re.split(r"(\[|\]|\.)", schema): if not token: continue if token == "[": bracket = True has_brackets = True elif token == "]": bracket = False elif not bracket and token == ".": if has_brackets: push.append("[%s]" % symbol) else: push.append(symbol) symbol = "" has_brackets = False else: symbol += token if symbol: push.append(symbol) if len(push) > 1: dbname, owner = ".".join(push[0:-1]), push[-1] # test for internal brackets if re.match(r".*\].*\[.*", dbname[1:-1]): dbname = quoted_name(dbname, quote=False) else: dbname = dbname.lstrip("[").rstrip("]") elif len(push): dbname, owner = None, push[0] else: dbname, owner = None, None _memoized_schema[schema] = dbname, owner return dbname, owner class MSDialect(default.DefaultDialect): # will assume it's at least mssql2005 name = "mssql" supports_statement_cache = True supports_default_values = True supports_empty_insert = False favor_returning_over_lastrowid = True returns_native_bytes = True supports_comments = True supports_default_metavalue = False """dialect supports INSERT... VALUES (DEFAULT) syntax - SQL Server **does** support this, but **not** for the IDENTITY column, so we can't turn this on. """ # supports_native_uuid is partial here, so we implement our # own impl type execution_ctx_cls = MSExecutionContext use_scope_identity = True max_identifier_length = 128 schema_name = "dbo" insert_returning = True update_returning = True delete_returning = True update_returning_multifrom = True delete_returning_multifrom = True colspecs = { sqltypes.DateTime: _MSDateTime, sqltypes.Date: _MSDate, sqltypes.JSON: JSON, sqltypes.JSON.JSONIndexType: JSONIndexType, sqltypes.JSON.JSONPathType: JSONPathType, sqltypes.Time: _BASETIMEIMPL, sqltypes.Unicode: _MSUnicode, sqltypes.UnicodeText: _MSUnicodeText, DATETIMEOFFSET: DATETIMEOFFSET, DATETIME2: DATETIME2, SMALLDATETIME: SMALLDATETIME, DATETIME: DATETIME, sqltypes.Uuid: MSUUid, } engine_config_types = default.DefaultDialect.engine_config_types.union( {"legacy_schema_aliasing": util.asbool} ) ischema_names = ischema_names supports_sequences = True sequences_optional = True # This is actually used for autoincrement, where itentity is used that # starts with 1. # for sequences T-SQL's actual default is -9223372036854775808 default_sequence_base = 1 supports_native_boolean = False non_native_boolean_check_constraint = False supports_unicode_binds = True postfetch_lastrowid = True # may be changed at server inspection time for older SQL server versions supports_multivalues_insert = True use_insertmanyvalues = True # note pyodbc will set this to False if fast_executemany is set, # as of SQLAlchemy 2.0.9 use_insertmanyvalues_wo_returning = True insertmanyvalues_implicit_sentinel = ( InsertmanyvaluesSentinelOpts.AUTOINCREMENT | InsertmanyvaluesSentinelOpts.IDENTITY | InsertmanyvaluesSentinelOpts.USE_INSERT_FROM_SELECT ) # "The incoming request has too many parameters. The server supports a " # "maximum of 2100 parameters." # in fact you can have 2099 parameters. insertmanyvalues_max_parameters = 2099 _supports_offset_fetch = False _supports_nvarchar_max = False legacy_schema_aliasing = False server_version_info = () statement_compiler = MSSQLCompiler ddl_compiler = MSDDLCompiler type_compiler_cls = MSTypeCompiler preparer = MSIdentifierPreparer construct_arguments = [ (sa_schema.PrimaryKeyConstraint, {"clustered": None}), (sa_schema.UniqueConstraint, {"clustered": None}), ( sa_schema.Index, { "clustered": None, "include": None, "where": None, "columnstore": None, }, ), ( sa_schema.Column, {"identity_start": None, "identity_increment": None}, ), ] def __init__( self, query_timeout=None, use_scope_identity=True, schema_name="dbo", deprecate_large_types=None, supports_comments=None, json_serializer=None, json_deserializer=None, legacy_schema_aliasing=None, ignore_no_transaction_on_rollback=False, **opts, ): self.query_timeout = int(query_timeout or 0) self.schema_name = schema_name self.use_scope_identity = use_scope_identity self.deprecate_large_types = deprecate_large_types self.ignore_no_transaction_on_rollback = ( ignore_no_transaction_on_rollback ) self._user_defined_supports_comments = uds = supports_comments if uds is not None: self.supports_comments = uds if legacy_schema_aliasing is not None: util.warn_deprecated( "The legacy_schema_aliasing parameter is " "deprecated and will be removed in a future release.", "1.4", ) self.legacy_schema_aliasing = legacy_schema_aliasing super().__init__(**opts) self._json_serializer = json_serializer self._json_deserializer = json_deserializer def do_savepoint(self, connection, name): # give the DBAPI a push connection.exec_driver_sql("IF @@TRANCOUNT = 0 BEGIN TRANSACTION") super().do_savepoint(connection, name) def do_release_savepoint(self, connection, name): # SQL Server does not support RELEASE SAVEPOINT pass def do_rollback(self, dbapi_connection): try: super().do_rollback(dbapi_connection) except self.dbapi.ProgrammingError as e: if self.ignore_no_transaction_on_rollback and re.match( r".*\b111214\b", str(e) ): util.warn( "ProgrammingError 111214 " "'No corresponding transaction found.' " "has been suppressed via " "ignore_no_transaction_on_rollback=True" ) else: raise _isolation_lookup = { "SERIALIZABLE", "READ UNCOMMITTED", "READ COMMITTED", "REPEATABLE READ", "SNAPSHOT", } def get_isolation_level_values(self, dbapi_connection): return list(self._isolation_lookup) def set_isolation_level(self, dbapi_connection, level): cursor = dbapi_connection.cursor() cursor.execute(f"SET TRANSACTION ISOLATION LEVEL {level}") cursor.close() if level == "SNAPSHOT": dbapi_connection.commit() def get_isolation_level(self, dbapi_connection): cursor = dbapi_connection.cursor() view_name = "sys.system_views" try: cursor.execute( ( "SELECT name FROM {} WHERE name IN " "('dm_exec_sessions', 'dm_pdw_nodes_exec_sessions')" ).format(view_name) ) row = cursor.fetchone() if not row: raise NotImplementedError( "Can't fetch isolation level on this particular " "SQL Server version." ) view_name = f"sys.{row[0]}" cursor.execute( """ SELECT CASE transaction_isolation_level WHEN 0 THEN NULL WHEN 1 THEN 'READ UNCOMMITTED' WHEN 2 THEN 'READ COMMITTED' WHEN 3 THEN 'REPEATABLE READ' WHEN 4 THEN 'SERIALIZABLE' WHEN 5 THEN 'SNAPSHOT' END AS TRANSACTION_ISOLATION_LEVEL FROM {} where session_id = @@SPID """.format( view_name ) ) except self.dbapi.Error as err: raise NotImplementedError( "Can't fetch isolation level; encountered error {} when " 'attempting to query the "{}" view.'.format(err, view_name) ) from err else: row = cursor.fetchone() return row[0].upper() finally: cursor.close() def initialize(self, connection): super().initialize(connection) self._setup_version_attributes() self._setup_supports_nvarchar_max(connection) self._setup_supports_comments(connection) def _setup_version_attributes(self): if self.server_version_info[0] not in list(range(8, 17)): util.warn( "Unrecognized server version info '%s'. Some SQL Server " "features may not function properly." % ".".join(str(x) for x in self.server_version_info) ) if self.server_version_info >= MS_2008_VERSION: self.supports_multivalues_insert = True else: self.supports_multivalues_insert = False if self.deprecate_large_types is None: self.deprecate_large_types = ( self.server_version_info >= MS_2012_VERSION ) self._supports_offset_fetch = ( self.server_version_info and self.server_version_info[0] >= 11 ) def _setup_supports_nvarchar_max(self, connection): try: connection.scalar( sql.text("SELECT CAST('test max support' AS NVARCHAR(max))") ) except exc.DBAPIError: self._supports_nvarchar_max = False else: self._supports_nvarchar_max = True def _setup_supports_comments(self, connection): if self._user_defined_supports_comments is not None: return try: connection.scalar( sql.text( "SELECT 1 FROM fn_listextendedproperty" "(default, default, default, default, " "default, default, default)" ) ) except exc.DBAPIError: self.supports_comments = False else: self.supports_comments = True def _get_default_schema_name(self, connection): query = sql.text("SELECT schema_name()") default_schema_name = connection.scalar(query) if default_schema_name is not None: # guard against the case where the default_schema_name is being # fed back into a table reflection function. return quoted_name(default_schema_name, quote=True) else: return self.schema_name @_db_plus_owner def has_table(self, connection, tablename, dbname, owner, schema, **kw): self._ensure_has_table_connection(connection) return self._internal_has_table(connection, tablename, owner, **kw) @reflection.cache @_db_plus_owner def has_sequence( self, connection, sequencename, dbname, owner, schema, **kw ): sequences = ischema.sequences s = sql.select(sequences.c.sequence_name).where( sequences.c.sequence_name == sequencename ) if owner: s = s.where(sequences.c.sequence_schema == owner) c = connection.execute(s) return c.first() is not None @reflection.cache @_db_plus_owner_listing def get_sequence_names(self, connection, dbname, owner, schema, **kw): sequences = ischema.sequences s = sql.select(sequences.c.sequence_name) if owner: s = s.where(sequences.c.sequence_schema == owner) c = connection.execute(s) return [row[0] for row in c] @reflection.cache def get_schema_names(self, connection, **kw): s = sql.select(ischema.schemata.c.schema_name).order_by( ischema.schemata.c.schema_name ) schema_names = [r[0] for r in connection.execute(s)] return schema_names @reflection.cache @_db_plus_owner_listing def get_table_names(self, connection, dbname, owner, schema, **kw): tables = ischema.tables s = ( sql.select(tables.c.table_name) .where( sql.and_( tables.c.table_schema == owner, tables.c.table_type == "BASE TABLE", ) ) .order_by(tables.c.table_name) ) table_names = [r[0] for r in connection.execute(s)] return table_names @reflection.cache @_db_plus_owner_listing def get_view_names(self, connection, dbname, owner, schema, **kw): tables = ischema.tables s = ( sql.select(tables.c.table_name) .where( sql.and_( tables.c.table_schema == owner, tables.c.table_type == "VIEW", ) ) .order_by(tables.c.table_name) ) view_names = [r[0] for r in connection.execute(s)] return view_names @reflection.cache def _internal_has_table(self, connection, tablename, owner, **kw): if tablename.startswith("#"): # temporary table # mssql does not support temporary views # SQL Error [4103] [S0001]: "#v": Temporary views are not allowed return bool( connection.scalar( # U filters on user tables only. text("SELECT object_id(:table_name, 'U')"), {"table_name": f"tempdb.dbo.[{tablename}]"}, ) ) else: tables = ischema.tables s = sql.select(tables.c.table_name).where( sql.and_( sql.or_( tables.c.table_type == "BASE TABLE", tables.c.table_type == "VIEW", ), tables.c.table_name == tablename, ) ) if owner: s = s.where(tables.c.table_schema == owner) c = connection.execute(s) return c.first() is not None def _default_or_error(self, connection, tablename, owner, method, **kw): # TODO: try to avoid having to run a separate query here if self._internal_has_table(connection, tablename, owner, **kw): return method() else: raise exc.NoSuchTableError(f"{owner}.{tablename}") @reflection.cache @_db_plus_owner def get_indexes(self, connection, tablename, dbname, owner, schema, **kw): filter_definition = ( "ind.filter_definition" if self.server_version_info >= MS_2008_VERSION else "NULL as filter_definition" ) rp = connection.execution_options(future_result=True).execute( sql.text( f""" select ind.index_id, ind.is_unique, ind.name, ind.type, {filter_definition} from sys.indexes as ind join sys.tables as tab on ind.object_id = tab.object_id join sys.schemas as sch on sch.schema_id = tab.schema_id where tab.name = :tabname and sch.name = :schname and ind.is_primary_key = 0 and ind.type != 0 order by ind.name """ ) .bindparams( sql.bindparam("tabname", tablename, ischema.CoerceUnicode()), sql.bindparam("schname", owner, ischema.CoerceUnicode()), ) .columns(name=sqltypes.Unicode()) ) indexes = {} for row in rp.mappings(): indexes[row["index_id"]] = current = { "name": row["name"], "unique": row["is_unique"] == 1, "column_names": [], "include_columns": [], "dialect_options": {}, } do = current["dialect_options"] index_type = row["type"] if index_type in {1, 2}: do["mssql_clustered"] = index_type == 1 if index_type in {5, 6}: do["mssql_clustered"] = index_type == 5 do["mssql_columnstore"] = True if row["filter_definition"] is not None: do["mssql_where"] = row["filter_definition"] rp = connection.execution_options(future_result=True).execute( sql.text( """ select ind_col.index_id, col.name, ind_col.is_included_column from sys.columns as col join sys.tables as tab on tab.object_id = col.object_id join sys.index_columns as ind_col on ind_col.column_id = col.column_id and ind_col.object_id = tab.object_id join sys.schemas as sch on sch.schema_id = tab.schema_id where tab.name = :tabname and sch.name = :schname """ ) .bindparams( sql.bindparam("tabname", tablename, ischema.CoerceUnicode()), sql.bindparam("schname", owner, ischema.CoerceUnicode()), ) .columns(name=sqltypes.Unicode()) ) for row in rp.mappings(): if row["index_id"] not in indexes: continue index_def = indexes[row["index_id"]] is_colstore = index_def["dialect_options"].get("mssql_columnstore") is_clustered = index_def["dialect_options"].get("mssql_clustered") if not (is_colstore and is_clustered): # a clustered columnstore index includes all columns but does # not want them in the index definition if row["is_included_column"] and not is_colstore: # a noncludsted columnstore index reports that includes # columns but requires that are listed as normal columns index_def["include_columns"].append(row["name"]) else: index_def["column_names"].append(row["name"]) for index_info in indexes.values(): # NOTE: "root level" include_columns is legacy, now part of # dialect_options (issue #7382) index_info["dialect_options"]["mssql_include"] = index_info[ "include_columns" ] if indexes: return list(indexes.values()) else: return self._default_or_error( connection, tablename, owner, ReflectionDefaults.indexes, **kw ) @reflection.cache @_db_plus_owner def get_view_definition( self, connection, viewname, dbname, owner, schema, **kw ): view_def = connection.execute( sql.text( "select mod.definition " "from sys.sql_modules as mod " "join sys.views as views on mod.object_id = views.object_id " "join sys.schemas as sch on views.schema_id = sch.schema_id " "where views.name=:viewname and sch.name=:schname" ).bindparams( sql.bindparam("viewname", viewname, ischema.CoerceUnicode()), sql.bindparam("schname", owner, ischema.CoerceUnicode()), ) ).scalar() if view_def: return view_def else: raise exc.NoSuchTableError(f"{owner}.{viewname}") @reflection.cache def get_table_comment(self, connection, table_name, schema=None, **kw): if not self.supports_comments: raise NotImplementedError( "Can't get table comments on current SQL Server version in use" ) schema_name = schema if schema else self.default_schema_name COMMENT_SQL = """ SELECT cast(com.value as nvarchar(max)) FROM fn_listextendedproperty('MS_Description', 'schema', :schema, 'table', :table, NULL, NULL ) as com; """ comment = connection.execute( sql.text(COMMENT_SQL).bindparams( sql.bindparam("schema", schema_name, ischema.CoerceUnicode()), sql.bindparam("table", table_name, ischema.CoerceUnicode()), ) ).scalar() if comment: return {"text": comment} else: return self._default_or_error( connection, table_name, None, ReflectionDefaults.table_comment, **kw, ) def _temp_table_name_like_pattern(self, tablename): # LIKE uses '%' to match zero or more characters and '_' to match any # single character. We want to match literal underscores, so T-SQL # requires that we enclose them in square brackets. return tablename + ( ("[_][_][_]%") if not tablename.startswith("##") else "" ) def _get_internal_temp_table_name(self, connection, tablename): # it's likely that schema is always "dbo", but since we can # get it here, let's get it. # see https://stackoverflow.com/questions/8311959/ # specifying-schema-for-temporary-tables try: return connection.execute( sql.text( "select table_schema, table_name " "from tempdb.information_schema.tables " "where table_name like :p1" ), {"p1": self._temp_table_name_like_pattern(tablename)}, ).one() except exc.MultipleResultsFound as me: raise exc.UnreflectableTableError( "Found more than one temporary table named '%s' in tempdb " "at this time. Cannot reliably resolve that name to its " "internal table name." % tablename ) from me except exc.NoResultFound as ne: raise exc.NoSuchTableError( "Unable to find a temporary table named '%s' in tempdb." % tablename ) from ne @reflection.cache @_db_plus_owner def get_columns(self, connection, tablename, dbname, owner, schema, **kw): is_temp_table = tablename.startswith("#") if is_temp_table: owner, tablename = self._get_internal_temp_table_name( connection, tablename ) columns = ischema.mssql_temp_table_columns else: columns = ischema.columns computed_cols = ischema.computed_columns identity_cols = ischema.identity_columns if owner: whereclause = sql.and_( columns.c.table_name == tablename, columns.c.table_schema == owner, ) full_name = columns.c.table_schema + "." + columns.c.table_name else: whereclause = columns.c.table_name == tablename full_name = columns.c.table_name if self._supports_nvarchar_max: computed_definition = computed_cols.c.definition else: # tds_version 4.2 does not support NVARCHAR(MAX) computed_definition = sql.cast( computed_cols.c.definition, NVARCHAR(4000) ) object_id = func.object_id(full_name) s = ( sql.select( columns.c.column_name, columns.c.data_type, columns.c.is_nullable, columns.c.character_maximum_length, columns.c.numeric_precision, columns.c.numeric_scale, columns.c.column_default, columns.c.collation_name, computed_definition, computed_cols.c.is_persisted, identity_cols.c.is_identity, identity_cols.c.seed_value, identity_cols.c.increment_value, ischema.extended_properties.c.value.label("comment"), ) .select_from(columns) .outerjoin( computed_cols, onclause=sql.and_( computed_cols.c.object_id == object_id, computed_cols.c.name == columns.c.column_name.collate("DATABASE_DEFAULT"), ), ) .outerjoin( identity_cols, onclause=sql.and_( identity_cols.c.object_id == object_id, identity_cols.c.name == columns.c.column_name.collate("DATABASE_DEFAULT"), ), ) .outerjoin( ischema.extended_properties, onclause=sql.and_( ischema.extended_properties.c["class"] == 1, ischema.extended_properties.c.major_id == object_id, ischema.extended_properties.c.minor_id == columns.c.ordinal_position, ischema.extended_properties.c.name == "MS_Description", ), ) .where(whereclause) .order_by(columns.c.ordinal_position) ) c = connection.execution_options(future_result=True).execute(s) cols = [] for row in c.mappings(): name = row[columns.c.column_name] type_ = row[columns.c.data_type] nullable = row[columns.c.is_nullable] == "YES" charlen = row[columns.c.character_maximum_length] numericprec = row[columns.c.numeric_precision] numericscale = row[columns.c.numeric_scale] default = row[columns.c.column_default] collation = row[columns.c.collation_name] definition = row[computed_definition] is_persisted = row[computed_cols.c.is_persisted] is_identity = row[identity_cols.c.is_identity] identity_start = row[identity_cols.c.seed_value] identity_increment = row[identity_cols.c.increment_value] comment = row[ischema.extended_properties.c.value] coltype = self.ischema_names.get(type_, None) kwargs = {} if coltype in ( MSString, MSChar, MSNVarchar, MSNChar, MSText, MSNText, MSBinary, MSVarBinary, sqltypes.LargeBinary, ): if charlen == -1: charlen = None kwargs["length"] = charlen if collation: kwargs["collation"] = collation if coltype is None: util.warn( "Did not recognize type '%s' of column '%s'" % (type_, name) ) coltype = sqltypes.NULLTYPE else: if issubclass(coltype, sqltypes.Numeric): kwargs["precision"] = numericprec if not issubclass(coltype, sqltypes.Float): kwargs["scale"] = numericscale coltype = coltype(**kwargs) cdict = { "name": name, "type": coltype, "nullable": nullable, "default": default, "autoincrement": is_identity is not None, "comment": comment, } if definition is not None and is_persisted is not None: cdict["computed"] = { "sqltext": definition, "persisted": is_persisted, } if is_identity is not None: # identity_start and identity_increment are Decimal or None if identity_start is None or identity_increment is None: cdict["identity"] = {} else: if isinstance(coltype, sqltypes.BigInteger): start = int(identity_start) increment = int(identity_increment) elif isinstance(coltype, sqltypes.Integer): start = int(identity_start) increment = int(identity_increment) else: start = identity_start increment = identity_increment cdict["identity"] = { "start": start, "increment": increment, } cols.append(cdict) if cols: return cols else: return self._default_or_error( connection, tablename, owner, ReflectionDefaults.columns, **kw ) @reflection.cache @_db_plus_owner def get_pk_constraint( self, connection, tablename, dbname, owner, schema, **kw ): pkeys = [] TC = ischema.constraints C = ischema.key_constraints.alias("C") # Primary key constraints s = ( sql.select( C.c.column_name, TC.c.constraint_type, C.c.constraint_name, func.objectproperty( func.object_id( C.c.table_schema + "." + C.c.constraint_name ), "CnstIsClustKey", ).label("is_clustered"), ) .where( sql.and_( TC.c.constraint_name == C.c.constraint_name, TC.c.table_schema == C.c.table_schema, C.c.table_name == tablename, C.c.table_schema == owner, ), ) .order_by(TC.c.constraint_name, C.c.ordinal_position) ) c = connection.execution_options(future_result=True).execute(s) constraint_name = None is_clustered = None for row in c.mappings(): if "PRIMARY" in row[TC.c.constraint_type.name]: pkeys.append(row["COLUMN_NAME"]) if constraint_name is None: constraint_name = row[C.c.constraint_name.name] if is_clustered is None: is_clustered = row["is_clustered"] if pkeys: return { "constrained_columns": pkeys, "name": constraint_name, "dialect_options": {"mssql_clustered": is_clustered}, } else: return self._default_or_error( connection, tablename, owner, ReflectionDefaults.pk_constraint, **kw, ) @reflection.cache @_db_plus_owner def get_foreign_keys( self, connection, tablename, dbname, owner, schema, **kw ): # Foreign key constraints s = ( text( """\ WITH fk_info AS ( SELECT ischema_ref_con.constraint_schema, ischema_ref_con.constraint_name, ischema_key_col.ordinal_position, ischema_key_col.table_schema, ischema_key_col.table_name, ischema_ref_con.unique_constraint_schema, ischema_ref_con.unique_constraint_name, ischema_ref_con.match_option, ischema_ref_con.update_rule, ischema_ref_con.delete_rule, ischema_key_col.column_name AS constrained_column FROM INFORMATION_SCHEMA.REFERENTIAL_CONSTRAINTS ischema_ref_con INNER JOIN INFORMATION_SCHEMA.KEY_COLUMN_USAGE ischema_key_col ON ischema_key_col.table_schema = ischema_ref_con.constraint_schema AND ischema_key_col.constraint_name = ischema_ref_con.constraint_name WHERE ischema_key_col.table_name = :tablename AND ischema_key_col.table_schema = :owner ), constraint_info AS ( SELECT ischema_key_col.constraint_schema, ischema_key_col.constraint_name, ischema_key_col.ordinal_position, ischema_key_col.table_schema, ischema_key_col.table_name, ischema_key_col.column_name FROM INFORMATION_SCHEMA.KEY_COLUMN_USAGE ischema_key_col ), index_info AS ( SELECT sys.schemas.name AS index_schema, sys.indexes.name AS index_name, sys.index_columns.key_ordinal AS ordinal_position, sys.schemas.name AS table_schema, sys.objects.name AS table_name, sys.columns.name AS column_name FROM sys.indexes INNER JOIN sys.objects ON sys.objects.object_id = sys.indexes.object_id INNER JOIN sys.schemas ON sys.schemas.schema_id = sys.objects.schema_id INNER JOIN sys.index_columns ON sys.index_columns.object_id = sys.objects.object_id AND sys.index_columns.index_id = sys.indexes.index_id INNER JOIN sys.columns ON sys.columns.object_id = sys.indexes.object_id AND sys.columns.column_id = sys.index_columns.column_id ) SELECT fk_info.constraint_schema, fk_info.constraint_name, fk_info.ordinal_position, fk_info.constrained_column, constraint_info.table_schema AS referred_table_schema, constraint_info.table_name AS referred_table_name, constraint_info.column_name AS referred_column, fk_info.match_option, fk_info.update_rule, fk_info.delete_rule FROM fk_info INNER JOIN constraint_info ON constraint_info.constraint_schema = fk_info.unique_constraint_schema AND constraint_info.constraint_name = fk_info.unique_constraint_name AND constraint_info.ordinal_position = fk_info.ordinal_position UNION SELECT fk_info.constraint_schema, fk_info.constraint_name, fk_info.ordinal_position, fk_info.constrained_column, index_info.table_schema AS referred_table_schema, index_info.table_name AS referred_table_name, index_info.column_name AS referred_column, fk_info.match_option, fk_info.update_rule, fk_info.delete_rule FROM fk_info INNER JOIN index_info ON index_info.index_schema = fk_info.unique_constraint_schema AND index_info.index_name = fk_info.unique_constraint_name AND index_info.ordinal_position = fk_info.ordinal_position ORDER BY fk_info.constraint_schema, fk_info.constraint_name, fk_info.ordinal_position """ ) .bindparams( sql.bindparam("tablename", tablename, ischema.CoerceUnicode()), sql.bindparam("owner", owner, ischema.CoerceUnicode()), ) .columns( constraint_schema=sqltypes.Unicode(), constraint_name=sqltypes.Unicode(), table_schema=sqltypes.Unicode(), table_name=sqltypes.Unicode(), constrained_column=sqltypes.Unicode(), referred_table_schema=sqltypes.Unicode(), referred_table_name=sqltypes.Unicode(), referred_column=sqltypes.Unicode(), ) ) # group rows by constraint ID, to handle multi-column FKs fkeys = util.defaultdict( lambda: { "name": None, "constrained_columns": [], "referred_schema": None, "referred_table": None, "referred_columns": [], "options": {}, } ) for r in connection.execute(s).all(): ( _, # constraint schema rfknm, _, # ordinal position scol, rschema, rtbl, rcol, # TODO: we support match=<keyword> for foreign keys so # we can support this also, PG has match=FULL for example # but this seems to not be a valid value for SQL Server _, # match rule fkuprule, fkdelrule, ) = r rec = fkeys[rfknm] rec["name"] = rfknm if fkuprule != "NO ACTION": rec["options"]["onupdate"] = fkuprule if fkdelrule != "NO ACTION": rec["options"]["ondelete"] = fkdelrule if not rec["referred_table"]: rec["referred_table"] = rtbl if schema is not None or owner != rschema: if dbname: rschema = dbname + "." + rschema rec["referred_schema"] = rschema local_cols, remote_cols = ( rec["constrained_columns"], rec["referred_columns"], ) local_cols.append(scol) remote_cols.append(rcol) if fkeys: return list(fkeys.values()) else: return self._default_or_error( connection, tablename, owner, ReflectionDefaults.foreign_keys, **kw, ) sqlalchemy/dialects/mssql/json.py 0000755 00000011224 15125143220 0013156 0 ustar 00 # dialects/mssql/json.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors from ... import types as sqltypes # technically, all the dialect-specific datatypes that don't have any special # behaviors would be private with names like _MSJson. However, we haven't been # doing this for mysql.JSON or sqlite.JSON which both have JSON / JSONIndexType # / JSONPathType in their json.py files, so keep consistent with that # sub-convention for now. A future change can update them all to be # package-private at once. class JSON(sqltypes.JSON): """MSSQL JSON type. MSSQL supports JSON-formatted data as of SQL Server 2016. The :class:`_mssql.JSON` datatype at the DDL level will represent the datatype as ``NVARCHAR(max)``, but provides for JSON-level comparison functions as well as Python coercion behavior. :class:`_mssql.JSON` is used automatically whenever the base :class:`_types.JSON` datatype is used against a SQL Server backend. .. seealso:: :class:`_types.JSON` - main documentation for the generic cross-platform JSON datatype. The :class:`_mssql.JSON` type supports persistence of JSON values as well as the core index operations provided by :class:`_types.JSON` datatype, by adapting the operations to render the ``JSON_VALUE`` or ``JSON_QUERY`` functions at the database level. The SQL Server :class:`_mssql.JSON` type necessarily makes use of the ``JSON_QUERY`` and ``JSON_VALUE`` functions when querying for elements of a JSON object. These two functions have a major restriction in that they are **mutually exclusive** based on the type of object to be returned. The ``JSON_QUERY`` function **only** returns a JSON dictionary or list, but not an individual string, numeric, or boolean element; the ``JSON_VALUE`` function **only** returns an individual string, numeric, or boolean element. **both functions either return NULL or raise an error if they are not used against the correct expected value**. To handle this awkward requirement, indexed access rules are as follows: 1. When extracting a sub element from a JSON that is itself a JSON dictionary or list, the :meth:`_types.JSON.Comparator.as_json` accessor should be used:: stmt = select(data_table.c.data["some key"].as_json()).where( data_table.c.data["some key"].as_json() == {"sub": "structure"} ) 2. When extracting a sub element from a JSON that is a plain boolean, string, integer, or float, use the appropriate method among :meth:`_types.JSON.Comparator.as_boolean`, :meth:`_types.JSON.Comparator.as_string`, :meth:`_types.JSON.Comparator.as_integer`, :meth:`_types.JSON.Comparator.as_float`:: stmt = select(data_table.c.data["some key"].as_string()).where( data_table.c.data["some key"].as_string() == "some string" ) .. versionadded:: 1.4 """ # note there was a result processor here that was looking for "number", # but none of the tests seem to exercise it. # Note: these objects currently match exactly those of MySQL, however since # these are not generalizable to all JSON implementations, remain separately # implemented for each dialect. class _FormatTypeMixin: def _format_value(self, value): raise NotImplementedError() def bind_processor(self, dialect): super_proc = self.string_bind_processor(dialect) def process(value): value = self._format_value(value) if super_proc: value = super_proc(value) return value return process def literal_processor(self, dialect): super_proc = self.string_literal_processor(dialect) def process(value): value = self._format_value(value) if super_proc: value = super_proc(value) return value return process class JSONIndexType(_FormatTypeMixin, sqltypes.JSON.JSONIndexType): def _format_value(self, value): if isinstance(value, int): value = "$[%s]" % value else: value = '$."%s"' % value return value class JSONPathType(_FormatTypeMixin, sqltypes.JSON.JSONPathType): def _format_value(self, value): return "$%s" % ( "".join( [ "[%s]" % elem if isinstance(elem, int) else '."%s"' % elem for elem in value ] ) ) sqlalchemy/dialects/mssql/provision.py 0000755 00000012731 15125143220 0014241 0 ustar 00 # dialects/mssql/provision.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors from sqlalchemy import inspect from sqlalchemy import Integer from ... import create_engine from ... import exc from ...schema import Column from ...schema import DropConstraint from ...schema import ForeignKeyConstraint from ...schema import MetaData from ...schema import Table from ...testing.provision import create_db from ...testing.provision import drop_all_schema_objects_pre_tables from ...testing.provision import drop_db from ...testing.provision import generate_driver_url from ...testing.provision import get_temp_table_name from ...testing.provision import log from ...testing.provision import normalize_sequence from ...testing.provision import post_configure_engine from ...testing.provision import run_reap_dbs from ...testing.provision import temp_table_keyword_args @post_configure_engine.for_db("mssql") def post_configure_engine(url, engine, follower_ident): if engine.driver == "pyodbc": engine.dialect.dbapi.pooling = False @generate_driver_url.for_db("mssql") def generate_driver_url(url, driver, query_str): backend = url.get_backend_name() new_url = url.set(drivername="%s+%s" % (backend, driver)) if driver not in ("pyodbc", "aioodbc"): new_url = new_url.set(query="") if driver == "aioodbc": new_url = new_url.update_query_dict({"MARS_Connection": "Yes"}) if query_str: new_url = new_url.update_query_string(query_str) try: new_url.get_dialect() except exc.NoSuchModuleError: return None else: return new_url @create_db.for_db("mssql") def _mssql_create_db(cfg, eng, ident): with eng.connect().execution_options(isolation_level="AUTOCOMMIT") as conn: conn.exec_driver_sql("create database %s" % ident) conn.exec_driver_sql( "ALTER DATABASE %s SET ALLOW_SNAPSHOT_ISOLATION ON" % ident ) conn.exec_driver_sql( "ALTER DATABASE %s SET READ_COMMITTED_SNAPSHOT ON" % ident ) conn.exec_driver_sql("use %s" % ident) conn.exec_driver_sql("create schema test_schema") conn.exec_driver_sql("create schema test_schema_2") @drop_db.for_db("mssql") def _mssql_drop_db(cfg, eng, ident): with eng.connect().execution_options(isolation_level="AUTOCOMMIT") as conn: _mssql_drop_ignore(conn, ident) def _mssql_drop_ignore(conn, ident): try: # typically when this happens, we can't KILL the session anyway, # so let the cleanup process drop the DBs # for row in conn.exec_driver_sql( # "select session_id from sys.dm_exec_sessions " # "where database_id=db_id('%s')" % ident): # log.info("killing SQL server session %s", row['session_id']) # conn.exec_driver_sql("kill %s" % row['session_id']) conn.exec_driver_sql("drop database %s" % ident) log.info("Reaped db: %s", ident) return True except exc.DatabaseError as err: log.warning("couldn't drop db: %s", err) return False @run_reap_dbs.for_db("mssql") def _reap_mssql_dbs(url, idents): log.info("db reaper connecting to %r", url) eng = create_engine(url) with eng.connect().execution_options(isolation_level="AUTOCOMMIT") as conn: log.info("identifiers in file: %s", ", ".join(idents)) to_reap = conn.exec_driver_sql( "select d.name from sys.databases as d where name " "like 'TEST_%' and not exists (select session_id " "from sys.dm_exec_sessions " "where database_id=d.database_id)" ) all_names = {dbname.lower() for (dbname,) in to_reap} to_drop = set() for name in all_names: if name in idents: to_drop.add(name) dropped = total = 0 for total, dbname in enumerate(to_drop, 1): if _mssql_drop_ignore(conn, dbname): dropped += 1 log.info( "Dropped %d out of %d stale databases detected", dropped, total ) @temp_table_keyword_args.for_db("mssql") def _mssql_temp_table_keyword_args(cfg, eng): return {} @get_temp_table_name.for_db("mssql") def _mssql_get_temp_table_name(cfg, eng, base_name): return "##" + base_name @drop_all_schema_objects_pre_tables.for_db("mssql") def drop_all_schema_objects_pre_tables(cfg, eng): with eng.connect().execution_options(isolation_level="AUTOCOMMIT") as conn: inspector = inspect(conn) for schema in (None, "dbo", cfg.test_schema, cfg.test_schema_2): for tname in inspector.get_table_names(schema=schema): tb = Table( tname, MetaData(), Column("x", Integer), Column("y", Integer), schema=schema, ) for fk in inspect(conn).get_foreign_keys(tname, schema=schema): conn.execute( DropConstraint( ForeignKeyConstraint( [tb.c.x], [tb.c.y], name=fk["name"] ) ) ) @normalize_sequence.for_db("mssql") def normalize_sequence(cfg, sequence): if sequence.start is None: sequence.start = 1 return sequence sqlalchemy/dialects/mssql/pyodbc.py 0000755 00000065045 15125143220 0013477 0 ustar 00 # dialects/mssql/pyodbc.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors r""" .. dialect:: mssql+pyodbc :name: PyODBC :dbapi: pyodbc :connectstring: mssql+pyodbc://<username>:<password>@<dsnname> :url: https://pypi.org/project/pyodbc/ Connecting to PyODBC -------------------- The URL here is to be translated to PyODBC connection strings, as detailed in `ConnectionStrings <https://code.google.com/p/pyodbc/wiki/ConnectionStrings>`_. DSN Connections ^^^^^^^^^^^^^^^ A DSN connection in ODBC means that a pre-existing ODBC datasource is configured on the client machine. The application then specifies the name of this datasource, which encompasses details such as the specific ODBC driver in use as well as the network address of the database. Assuming a datasource is configured on the client, a basic DSN-based connection looks like:: engine = create_engine("mssql+pyodbc://scott:tiger@some_dsn") Which above, will pass the following connection string to PyODBC: .. sourcecode:: text DSN=some_dsn;UID=scott;PWD=tiger If the username and password are omitted, the DSN form will also add the ``Trusted_Connection=yes`` directive to the ODBC string. Hostname Connections ^^^^^^^^^^^^^^^^^^^^ Hostname-based connections are also supported by pyodbc. These are often easier to use than a DSN and have the additional advantage that the specific database name to connect towards may be specified locally in the URL, rather than it being fixed as part of a datasource configuration. When using a hostname connection, the driver name must also be specified in the query parameters of the URL. As these names usually have spaces in them, the name must be URL encoded which means using plus signs for spaces:: engine = create_engine( "mssql+pyodbc://scott:tiger@myhost:port/databasename?driver=ODBC+Driver+17+for+SQL+Server" ) The ``driver`` keyword is significant to the pyodbc dialect and must be specified in lowercase. Any other names passed in the query string are passed through in the pyodbc connect string, such as ``authentication``, ``TrustServerCertificate``, etc. Multiple keyword arguments must be separated by an ampersand (``&``); these will be translated to semicolons when the pyodbc connect string is generated internally:: e = create_engine( "mssql+pyodbc://scott:tiger@mssql2017:1433/test?" "driver=ODBC+Driver+18+for+SQL+Server&TrustServerCertificate=yes" "&authentication=ActiveDirectoryIntegrated" ) The equivalent URL can be constructed using :class:`_sa.engine.URL`:: from sqlalchemy.engine import URL connection_url = URL.create( "mssql+pyodbc", username="scott", password="tiger", host="mssql2017", port=1433, database="test", query={ "driver": "ODBC Driver 18 for SQL Server", "TrustServerCertificate": "yes", "authentication": "ActiveDirectoryIntegrated", }, ) Pass through exact Pyodbc string ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A PyODBC connection string can also be sent in pyodbc's format directly, as specified in `the PyODBC documentation <https://github.com/mkleehammer/pyodbc/wiki/Connecting-to-databases>`_, using the parameter ``odbc_connect``. A :class:`_sa.engine.URL` object can help make this easier:: from sqlalchemy.engine import URL connection_string = "DRIVER={SQL Server Native Client 10.0};SERVER=dagger;DATABASE=test;UID=user;PWD=password" connection_url = URL.create( "mssql+pyodbc", query={"odbc_connect": connection_string} ) engine = create_engine(connection_url) .. _mssql_pyodbc_access_tokens: Connecting to databases with access tokens ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Some database servers are set up to only accept access tokens for login. For example, SQL Server allows the use of Azure Active Directory tokens to connect to databases. This requires creating a credential object using the ``azure-identity`` library. More information about the authentication step can be found in `Microsoft's documentation <https://docs.microsoft.com/en-us/azure/developer/python/azure-sdk-authenticate?tabs=bash>`_. After getting an engine, the credentials need to be sent to ``pyodbc.connect`` each time a connection is requested. One way to do this is to set up an event listener on the engine that adds the credential token to the dialect's connect call. This is discussed more generally in :ref:`engines_dynamic_tokens`. For SQL Server in particular, this is passed as an ODBC connection attribute with a data structure `described by Microsoft <https://docs.microsoft.com/en-us/sql/connect/odbc/using-azure-active-directory#authenticating-with-an-access-token>`_. The following code snippet will create an engine that connects to an Azure SQL database using Azure credentials:: import struct from sqlalchemy import create_engine, event from sqlalchemy.engine.url import URL from azure import identity # Connection option for access tokens, as defined in msodbcsql.h SQL_COPT_SS_ACCESS_TOKEN = 1256 TOKEN_URL = "https://database.windows.net/" # The token URL for any Azure SQL database connection_string = "mssql+pyodbc://@my-server.database.windows.net/myDb?driver=ODBC+Driver+17+for+SQL+Server" engine = create_engine(connection_string) azure_credentials = identity.DefaultAzureCredential() @event.listens_for(engine, "do_connect") def provide_token(dialect, conn_rec, cargs, cparams): # remove the "Trusted_Connection" parameter that SQLAlchemy adds cargs[0] = cargs[0].replace(";Trusted_Connection=Yes", "") # create token credential raw_token = azure_credentials.get_token(TOKEN_URL).token.encode( "utf-16-le" ) token_struct = struct.pack( f"<I{len(raw_token)}s", len(raw_token), raw_token ) # apply it to keyword arguments cparams["attrs_before"] = {SQL_COPT_SS_ACCESS_TOKEN: token_struct} .. tip:: The ``Trusted_Connection`` token is currently added by the SQLAlchemy pyodbc dialect when no username or password is present. This needs to be removed per Microsoft's `documentation for Azure access tokens <https://docs.microsoft.com/en-us/sql/connect/odbc/using-azure-active-directory#authenticating-with-an-access-token>`_, stating that a connection string when using an access token must not contain ``UID``, ``PWD``, ``Authentication`` or ``Trusted_Connection`` parameters. .. _azure_synapse_ignore_no_transaction_on_rollback: Avoiding transaction-related exceptions on Azure Synapse Analytics ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Azure Synapse Analytics has a significant difference in its transaction handling compared to plain SQL Server; in some cases an error within a Synapse transaction can cause it to be arbitrarily terminated on the server side, which then causes the DBAPI ``.rollback()`` method (as well as ``.commit()``) to fail. The issue prevents the usual DBAPI contract of allowing ``.rollback()`` to pass silently if no transaction is present as the driver does not expect this condition. The symptom of this failure is an exception with a message resembling 'No corresponding transaction found. (111214)' when attempting to emit a ``.rollback()`` after an operation had a failure of some kind. This specific case can be handled by passing ``ignore_no_transaction_on_rollback=True`` to the SQL Server dialect via the :func:`_sa.create_engine` function as follows:: engine = create_engine( connection_url, ignore_no_transaction_on_rollback=True ) Using the above parameter, the dialect will catch ``ProgrammingError`` exceptions raised during ``connection.rollback()`` and emit a warning if the error message contains code ``111214``, however will not raise an exception. .. versionadded:: 1.4.40 Added the ``ignore_no_transaction_on_rollback=True`` parameter. Enable autocommit for Azure SQL Data Warehouse (DW) connections ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Azure SQL Data Warehouse does not support transactions, and that can cause problems with SQLAlchemy's "autobegin" (and implicit commit/rollback) behavior. We can avoid these problems by enabling autocommit at both the pyodbc and engine levels:: connection_url = sa.engine.URL.create( "mssql+pyodbc", username="scott", password="tiger", host="dw.azure.example.com", database="mydb", query={ "driver": "ODBC Driver 17 for SQL Server", "autocommit": "True", }, ) engine = create_engine(connection_url).execution_options( isolation_level="AUTOCOMMIT" ) Avoiding sending large string parameters as TEXT/NTEXT ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ By default, for historical reasons, Microsoft's ODBC drivers for SQL Server send long string parameters (greater than 4000 SBCS characters or 2000 Unicode characters) as TEXT/NTEXT values. TEXT and NTEXT have been deprecated for many years and are starting to cause compatibility issues with newer versions of SQL_Server/Azure. For example, see `this issue <https://github.com/mkleehammer/pyodbc/issues/835>`_. Starting with ODBC Driver 18 for SQL Server we can override the legacy behavior and pass long strings as varchar(max)/nvarchar(max) using the ``LongAsMax=Yes`` connection string parameter:: connection_url = sa.engine.URL.create( "mssql+pyodbc", username="scott", password="tiger", host="mssqlserver.example.com", database="mydb", query={ "driver": "ODBC Driver 18 for SQL Server", "LongAsMax": "Yes", }, ) Pyodbc Pooling / connection close behavior ------------------------------------------ PyODBC uses internal `pooling <https://github.com/mkleehammer/pyodbc/wiki/The-pyodbc-Module#pooling>`_ by default, which means connections will be longer lived than they are within SQLAlchemy itself. As SQLAlchemy has its own pooling behavior, it is often preferable to disable this behavior. This behavior can only be disabled globally at the PyODBC module level, **before** any connections are made:: import pyodbc pyodbc.pooling = False # don't use the engine before pooling is set to False engine = create_engine("mssql+pyodbc://user:pass@dsn") If this variable is left at its default value of ``True``, **the application will continue to maintain active database connections**, even when the SQLAlchemy engine itself fully discards a connection or if the engine is disposed. .. seealso:: `pooling <https://github.com/mkleehammer/pyodbc/wiki/The-pyodbc-Module#pooling>`_ - in the PyODBC documentation. Driver / Unicode Support ------------------------- PyODBC works best with Microsoft ODBC drivers, particularly in the area of Unicode support on both Python 2 and Python 3. Using the FreeTDS ODBC drivers on Linux or OSX with PyODBC is **not** recommended; there have been historically many Unicode-related issues in this area, including before Microsoft offered ODBC drivers for Linux and OSX. Now that Microsoft offers drivers for all platforms, for PyODBC support these are recommended. FreeTDS remains relevant for non-ODBC drivers such as pymssql where it works very well. Rowcount Support ---------------- Previous limitations with the SQLAlchemy ORM's "versioned rows" feature with Pyodbc have been resolved as of SQLAlchemy 2.0.5. See the notes at :ref:`mssql_rowcount_versioning`. .. _mssql_pyodbc_fastexecutemany: Fast Executemany Mode --------------------- The PyODBC driver includes support for a "fast executemany" mode of execution which greatly reduces round trips for a DBAPI ``executemany()`` call when using Microsoft ODBC drivers, for **limited size batches that fit in memory**. The feature is enabled by setting the attribute ``.fast_executemany`` on the DBAPI cursor when an executemany call is to be used. The SQLAlchemy PyODBC SQL Server dialect supports this parameter by passing the ``fast_executemany`` parameter to :func:`_sa.create_engine` , when using the **Microsoft ODBC driver only**:: engine = create_engine( "mssql+pyodbc://scott:tiger@mssql2017:1433/test?driver=ODBC+Driver+17+for+SQL+Server", fast_executemany=True, ) .. versionchanged:: 2.0.9 - the ``fast_executemany`` parameter now has its intended effect of this PyODBC feature taking effect for all INSERT statements that are executed with multiple parameter sets, which don't include RETURNING. Previously, SQLAlchemy 2.0's :term:`insertmanyvalues` feature would cause ``fast_executemany`` to not be used in most cases even if specified. .. versionadded:: 1.3 .. seealso:: `fast executemany <https://github.com/mkleehammer/pyodbc/wiki/Features-beyond-the-DB-API#fast_executemany>`_ - on github .. _mssql_pyodbc_setinputsizes: Setinputsizes Support ----------------------- As of version 2.0, the pyodbc ``cursor.setinputsizes()`` method is used for all statement executions, except for ``cursor.executemany()`` calls when fast_executemany=True where it is not supported (assuming :ref:`insertmanyvalues <engine_insertmanyvalues>` is kept enabled, "fastexecutemany" will not take place for INSERT statements in any case). The use of ``cursor.setinputsizes()`` can be disabled by passing ``use_setinputsizes=False`` to :func:`_sa.create_engine`. When ``use_setinputsizes`` is left at its default of ``True``, the specific per-type symbols passed to ``cursor.setinputsizes()`` can be programmatically customized using the :meth:`.DialectEvents.do_setinputsizes` hook. See that method for usage examples. .. versionchanged:: 2.0 The mssql+pyodbc dialect now defaults to using ``use_setinputsizes=True`` for all statement executions with the exception of cursor.executemany() calls when fast_executemany=True. The behavior can be turned off by passing ``use_setinputsizes=False`` to :func:`_sa.create_engine`. """ # noqa import datetime import decimal import re import struct from .base import _MSDateTime from .base import _MSUnicode from .base import _MSUnicodeText from .base import BINARY from .base import DATETIMEOFFSET from .base import MSDialect from .base import MSExecutionContext from .base import VARBINARY from .json import JSON as _MSJson from .json import JSONIndexType as _MSJsonIndexType from .json import JSONPathType as _MSJsonPathType from ... import exc from ... import types as sqltypes from ... import util from ...connectors.pyodbc import PyODBCConnector from ...engine import cursor as _cursor class _ms_numeric_pyodbc: """Turns Decimals with adjusted() < 0 or > 7 into strings. The routines here are needed for older pyodbc versions as well as current mxODBC versions. """ def bind_processor(self, dialect): super_process = super().bind_processor(dialect) if not dialect._need_decimal_fix: return super_process def process(value): if self.asdecimal and isinstance(value, decimal.Decimal): adjusted = value.adjusted() if adjusted < 0: return self._small_dec_to_string(value) elif adjusted > 7: return self._large_dec_to_string(value) if super_process: return super_process(value) else: return value return process # these routines needed for older versions of pyodbc. # as of 2.1.8 this logic is integrated. def _small_dec_to_string(self, value): return "%s0.%s%s" % ( (value < 0 and "-" or ""), "0" * (abs(value.adjusted()) - 1), "".join([str(nint) for nint in value.as_tuple()[1]]), ) def _large_dec_to_string(self, value): _int = value.as_tuple()[1] if "E" in str(value): result = "%s%s%s" % ( (value < 0 and "-" or ""), "".join([str(s) for s in _int]), "0" * (value.adjusted() - (len(_int) - 1)), ) else: if (len(_int) - 1) > value.adjusted(): result = "%s%s.%s" % ( (value < 0 and "-" or ""), "".join([str(s) for s in _int][0 : value.adjusted() + 1]), "".join([str(s) for s in _int][value.adjusted() + 1 :]), ) else: result = "%s%s" % ( (value < 0 and "-" or ""), "".join([str(s) for s in _int][0 : value.adjusted() + 1]), ) return result class _MSNumeric_pyodbc(_ms_numeric_pyodbc, sqltypes.Numeric): pass class _MSFloat_pyodbc(_ms_numeric_pyodbc, sqltypes.Float): pass class _ms_binary_pyodbc: """Wraps binary values in dialect-specific Binary wrapper. If the value is null, return a pyodbc-specific BinaryNull object to prevent pyODBC [and FreeTDS] from defaulting binary NULL types to SQLWCHAR and causing implicit conversion errors. """ def bind_processor(self, dialect): if dialect.dbapi is None: return None DBAPIBinary = dialect.dbapi.Binary def process(value): if value is not None: return DBAPIBinary(value) else: # pyodbc-specific return dialect.dbapi.BinaryNull return process class _ODBCDateTimeBindProcessor: """Add bind processors to handle datetimeoffset behaviors""" has_tz = False def bind_processor(self, dialect): def process(value): if value is None: return None elif isinstance(value, str): # if a string was passed directly, allow it through return value elif not value.tzinfo or (not self.timezone and not self.has_tz): # for DateTime(timezone=False) return value else: # for DATETIMEOFFSET or DateTime(timezone=True) # # Convert to string format required by T-SQL dto_string = value.strftime("%Y-%m-%d %H:%M:%S.%f %z") # offset needs a colon, e.g., -0700 -> -07:00 # "UTC offset in the form (+-)HHMM[SS[.ffffff]]" # backend currently rejects seconds / fractional seconds dto_string = re.sub( r"([\+\-]\d{2})([\d\.]+)$", r"\1:\2", dto_string ) return dto_string return process class _ODBCDateTime(_ODBCDateTimeBindProcessor, _MSDateTime): pass class _ODBCDATETIMEOFFSET(_ODBCDateTimeBindProcessor, DATETIMEOFFSET): has_tz = True class _VARBINARY_pyodbc(_ms_binary_pyodbc, VARBINARY): pass class _BINARY_pyodbc(_ms_binary_pyodbc, BINARY): pass class _String_pyodbc(sqltypes.String): def get_dbapi_type(self, dbapi): if self.length in (None, "max") or self.length >= 2000: return (dbapi.SQL_VARCHAR, 0, 0) else: return dbapi.SQL_VARCHAR class _Unicode_pyodbc(_MSUnicode): def get_dbapi_type(self, dbapi): if self.length in (None, "max") or self.length >= 2000: return (dbapi.SQL_WVARCHAR, 0, 0) else: return dbapi.SQL_WVARCHAR class _UnicodeText_pyodbc(_MSUnicodeText): def get_dbapi_type(self, dbapi): if self.length in (None, "max") or self.length >= 2000: return (dbapi.SQL_WVARCHAR, 0, 0) else: return dbapi.SQL_WVARCHAR class _JSON_pyodbc(_MSJson): def get_dbapi_type(self, dbapi): return (dbapi.SQL_WVARCHAR, 0, 0) class _JSONIndexType_pyodbc(_MSJsonIndexType): def get_dbapi_type(self, dbapi): return dbapi.SQL_WVARCHAR class _JSONPathType_pyodbc(_MSJsonPathType): def get_dbapi_type(self, dbapi): return dbapi.SQL_WVARCHAR class MSExecutionContext_pyodbc(MSExecutionContext): _embedded_scope_identity = False def pre_exec(self): """where appropriate, issue "select scope_identity()" in the same statement. Background on why "scope_identity()" is preferable to "@@identity": https://msdn.microsoft.com/en-us/library/ms190315.aspx Background on why we attempt to embed "scope_identity()" into the same statement as the INSERT: https://code.google.com/p/pyodbc/wiki/FAQs#How_do_I_retrieve_autogenerated/identity_values? """ super().pre_exec() # don't embed the scope_identity select into an # "INSERT .. DEFAULT VALUES" if ( self._select_lastrowid and self.dialect.use_scope_identity and len(self.parameters[0]) ): self._embedded_scope_identity = True self.statement += "; select scope_identity()" def post_exec(self): if self._embedded_scope_identity: # Fetch the last inserted id from the manipulated statement # We may have to skip over a number of result sets with # no data (due to triggers, etc.) while True: try: # fetchall() ensures the cursor is consumed # without closing it (FreeTDS particularly) rows = self.cursor.fetchall() except self.dialect.dbapi.Error: # no way around this - nextset() consumes the previous set # so we need to just keep flipping self.cursor.nextset() else: if not rows: # async adapter drivers just return None here self.cursor.nextset() continue row = rows[0] break self._lastrowid = int(row[0]) self.cursor_fetch_strategy = _cursor._NO_CURSOR_DML else: super().post_exec() class MSDialect_pyodbc(PyODBCConnector, MSDialect): supports_statement_cache = True # note this parameter is no longer used by the ORM or default dialect # see #9414 supports_sane_rowcount_returning = False execution_ctx_cls = MSExecutionContext_pyodbc colspecs = util.update_copy( MSDialect.colspecs, { sqltypes.Numeric: _MSNumeric_pyodbc, sqltypes.Float: _MSFloat_pyodbc, BINARY: _BINARY_pyodbc, # support DateTime(timezone=True) sqltypes.DateTime: _ODBCDateTime, DATETIMEOFFSET: _ODBCDATETIMEOFFSET, # SQL Server dialect has a VARBINARY that is just to support # "deprecate_large_types" w/ VARBINARY(max), but also we must # handle the usual SQL standard VARBINARY VARBINARY: _VARBINARY_pyodbc, sqltypes.VARBINARY: _VARBINARY_pyodbc, sqltypes.LargeBinary: _VARBINARY_pyodbc, sqltypes.String: _String_pyodbc, sqltypes.Unicode: _Unicode_pyodbc, sqltypes.UnicodeText: _UnicodeText_pyodbc, sqltypes.JSON: _JSON_pyodbc, sqltypes.JSON.JSONIndexType: _JSONIndexType_pyodbc, sqltypes.JSON.JSONPathType: _JSONPathType_pyodbc, # this excludes Enum from the string/VARCHAR thing for now # it looks like Enum's adaptation doesn't really support the # String type itself having a dialect-level impl sqltypes.Enum: sqltypes.Enum, }, ) def __init__( self, fast_executemany=False, use_setinputsizes=True, **params, ): super().__init__(use_setinputsizes=use_setinputsizes, **params) self.use_scope_identity = ( self.use_scope_identity and self.dbapi and hasattr(self.dbapi.Cursor, "nextset") ) self._need_decimal_fix = self.dbapi and self._dbapi_version() < ( 2, 1, 8, ) self.fast_executemany = fast_executemany if fast_executemany: self.use_insertmanyvalues_wo_returning = False def _get_server_version_info(self, connection): try: # "Version of the instance of SQL Server, in the form # of 'major.minor.build.revision'" raw = connection.exec_driver_sql( "SELECT CAST(SERVERPROPERTY('ProductVersion') AS VARCHAR)" ).scalar() except exc.DBAPIError: # SQL Server docs indicate this function isn't present prior to # 2008. Before we had the VARCHAR cast above, pyodbc would also # fail on this query. return super()._get_server_version_info(connection) else: version = [] r = re.compile(r"[.\-]") for n in r.split(raw): try: version.append(int(n)) except ValueError: pass return tuple(version) def on_connect(self): super_ = super().on_connect() def on_connect(conn): if super_ is not None: super_(conn) self._setup_timestampoffset_type(conn) return on_connect def _setup_timestampoffset_type(self, connection): # output converter function for datetimeoffset def _handle_datetimeoffset(dto_value): tup = struct.unpack("<6hI2h", dto_value) return datetime.datetime( tup[0], tup[1], tup[2], tup[3], tup[4], tup[5], tup[6] // 1000, datetime.timezone( datetime.timedelta(hours=tup[7], minutes=tup[8]) ), ) odbc_SQL_SS_TIMESTAMPOFFSET = -155 # as defined in SQLNCLI.h connection.add_output_converter( odbc_SQL_SS_TIMESTAMPOFFSET, _handle_datetimeoffset ) def do_executemany(self, cursor, statement, parameters, context=None): if self.fast_executemany: cursor.fast_executemany = True super().do_executemany(cursor, statement, parameters, context=context) def is_disconnect(self, e, connection, cursor): if isinstance(e, self.dbapi.Error): code = e.args[0] if code in { "08S01", "01000", "01002", "08003", "08007", "08S02", "08001", "HYT00", "HY010", "10054", }: return True return super().is_disconnect(e, connection, cursor) dialect = MSDialect_pyodbc sqlalchemy/dialects/mssql/aioodbc.py 0000755 00000003745 15125143220 0013616 0 ustar 00 # dialects/mssql/aioodbc.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors r""" .. dialect:: mssql+aioodbc :name: aioodbc :dbapi: aioodbc :connectstring: mssql+aioodbc://<username>:<password>@<dsnname> :url: https://pypi.org/project/aioodbc/ Support for the SQL Server database in asyncio style, using the aioodbc driver which itself is a thread-wrapper around pyodbc. .. versionadded:: 2.0.23 Added the mssql+aioodbc dialect which builds on top of the pyodbc and general aio* dialect architecture. Using a special asyncio mediation layer, the aioodbc dialect is usable as the backend for the :ref:`SQLAlchemy asyncio <asyncio_toplevel>` extension package. Most behaviors and caveats for this driver are the same as that of the pyodbc dialect used on SQL Server; see :ref:`mssql_pyodbc` for general background. This dialect should normally be used only with the :func:`_asyncio.create_async_engine` engine creation function; connection styles are otherwise equivalent to those documented in the pyodbc section:: from sqlalchemy.ext.asyncio import create_async_engine engine = create_async_engine( "mssql+aioodbc://scott:tiger@mssql2017:1433/test?" "driver=ODBC+Driver+18+for+SQL+Server&TrustServerCertificate=yes" ) """ from __future__ import annotations from .pyodbc import MSDialect_pyodbc from .pyodbc import MSExecutionContext_pyodbc from ...connectors.aioodbc import aiodbcConnector class MSExecutionContext_aioodbc(MSExecutionContext_pyodbc): def create_server_side_cursor(self): return self._dbapi_connection.cursor(server_side=True) class MSDialectAsync_aioodbc(aiodbcConnector, MSDialect_pyodbc): driver = "aioodbc" supports_statement_cache = True execution_ctx_cls = MSExecutionContext_aioodbc dialect = MSDialectAsync_aioodbc sqlalchemy/dialects/mssql/pymssql.py 0000755 00000010001 15125143220 0013705 0 ustar 00 # dialects/mssql/pymssql.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors """ .. dialect:: mssql+pymssql :name: pymssql :dbapi: pymssql :connectstring: mssql+pymssql://<username>:<password>@<freetds_name>/?charset=utf8 pymssql is a Python module that provides a Python DBAPI interface around `FreeTDS <https://www.freetds.org/>`_. .. versionchanged:: 2.0.5 pymssql was restored to SQLAlchemy's continuous integration testing """ # noqa import re from .base import MSDialect from .base import MSIdentifierPreparer from ... import types as sqltypes from ... import util from ...engine import processors class _MSNumeric_pymssql(sqltypes.Numeric): def result_processor(self, dialect, type_): if not self.asdecimal: return processors.to_float else: return sqltypes.Numeric.result_processor(self, dialect, type_) class MSIdentifierPreparer_pymssql(MSIdentifierPreparer): def __init__(self, dialect): super().__init__(dialect) # pymssql has the very unusual behavior that it uses pyformat # yet does not require that percent signs be doubled self._double_percents = False class MSDialect_pymssql(MSDialect): supports_statement_cache = True supports_native_decimal = True supports_native_uuid = True driver = "pymssql" preparer = MSIdentifierPreparer_pymssql colspecs = util.update_copy( MSDialect.colspecs, {sqltypes.Numeric: _MSNumeric_pymssql, sqltypes.Float: sqltypes.Float}, ) @classmethod def import_dbapi(cls): module = __import__("pymssql") # pymmsql < 2.1.1 doesn't have a Binary method. we use string client_ver = tuple(int(x) for x in module.__version__.split(".")) if client_ver < (2, 1, 1): # TODO: monkeypatching here is less than ideal module.Binary = lambda x: x if hasattr(x, "decode") else str(x) if client_ver < (1,): util.warn( "The pymssql dialect expects at least " "the 1.0 series of the pymssql DBAPI." ) return module def _get_server_version_info(self, connection): vers = connection.exec_driver_sql("select @@version").scalar() m = re.match(r"Microsoft .*? - (\d+)\.(\d+)\.(\d+)\.(\d+)", vers) if m: return tuple(int(x) for x in m.group(1, 2, 3, 4)) else: return None def create_connect_args(self, url): opts = url.translate_connect_args(username="user") opts.update(url.query) port = opts.pop("port", None) if port and "host" in opts: opts["host"] = "%s:%s" % (opts["host"], port) return ([], opts) def is_disconnect(self, e, connection, cursor): for msg in ( "Adaptive Server connection timed out", "Net-Lib error during Connection reset by peer", "message 20003", # connection timeout "Error 10054", "Not connected to any MS SQL server", "Connection is closed", "message 20006", # Write to the server failed "message 20017", # Unexpected EOF from the server "message 20047", # DBPROCESS is dead or not enabled "The server failed to resume the transaction", ): if msg in str(e): return True else: return False def get_isolation_level_values(self, dbapi_connection): return super().get_isolation_level_values(dbapi_connection) + [ "AUTOCOMMIT" ] def set_isolation_level(self, dbapi_connection, level): if level == "AUTOCOMMIT": dbapi_connection.autocommit(True) else: dbapi_connection.autocommit(False) super().set_isolation_level(dbapi_connection, level) dialect = MSDialect_pymssql sqlalchemy/dialects/mssql/__init__.py 0000755 00000003530 15125143220 0013745 0 ustar 00 # dialects/mssql/__init__.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors from . import aioodbc # noqa from . import base # noqa from . import pymssql # noqa from . import pyodbc # noqa from .base import BIGINT from .base import BINARY from .base import BIT from .base import CHAR from .base import DATE from .base import DATETIME from .base import DATETIME2 from .base import DATETIMEOFFSET from .base import DECIMAL from .base import DOUBLE_PRECISION from .base import FLOAT from .base import IMAGE from .base import INTEGER from .base import JSON from .base import MONEY from .base import NCHAR from .base import NTEXT from .base import NUMERIC from .base import NVARCHAR from .base import REAL from .base import ROWVERSION from .base import SMALLDATETIME from .base import SMALLINT from .base import SMALLMONEY from .base import SQL_VARIANT from .base import TEXT from .base import TIME from .base import TIMESTAMP from .base import TINYINT from .base import UNIQUEIDENTIFIER from .base import VARBINARY from .base import VARCHAR from .base import XML from ...sql import try_cast base.dialect = dialect = pyodbc.dialect __all__ = ( "JSON", "INTEGER", "BIGINT", "SMALLINT", "TINYINT", "VARCHAR", "NVARCHAR", "CHAR", "NCHAR", "TEXT", "NTEXT", "DECIMAL", "NUMERIC", "FLOAT", "DATETIME", "DATETIME2", "DATETIMEOFFSET", "DATE", "DOUBLE_PRECISION", "TIME", "SMALLDATETIME", "BINARY", "VARBINARY", "BIT", "REAL", "IMAGE", "TIMESTAMP", "ROWVERSION", "MONEY", "SMALLMONEY", "UNIQUEIDENTIFIER", "SQL_VARIANT", "XML", "dialect", "try_cast", ) sqlalchemy/dialects/_typing.py 0000755 00000001713 15125143220 0012521 0 ustar 00 # dialects/_typing.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php from __future__ import annotations from typing import Any from typing import Iterable from typing import Mapping from typing import Optional from typing import Union from ..sql import roles from ..sql.base import ColumnCollection from ..sql.schema import Column from ..sql.schema import ColumnCollectionConstraint from ..sql.schema import Index _OnConflictConstraintT = Union[str, ColumnCollectionConstraint, Index, None] _OnConflictIndexElementsT = Optional[ Iterable[Union[Column[Any], str, roles.DDLConstraintColumnRole]] ] _OnConflictIndexWhereT = Optional[roles.WhereHavingRole] _OnConflictSetT = Optional[ Union[Mapping[Any, Any], ColumnCollection[Any, Any]] ] _OnConflictWhereT = Optional[roles.WhereHavingRole] sqlalchemy/dialects/postgresql/types.py 0000755 00000016715 15125143220 0014427 0 ustar 00 # dialects/postgresql/types.py # Copyright (C) 2013-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php from __future__ import annotations import datetime as dt from typing import Any from typing import Optional from typing import overload from typing import Type from typing import TYPE_CHECKING from uuid import UUID as _python_UUID from ...sql import sqltypes from ...sql import type_api from ...util.typing import Literal if TYPE_CHECKING: from ...engine.interfaces import Dialect from ...sql.operators import OperatorType from ...sql.type_api import _LiteralProcessorType from ...sql.type_api import TypeEngine _DECIMAL_TYPES = (1231, 1700) _FLOAT_TYPES = (700, 701, 1021, 1022) _INT_TYPES = (20, 21, 23, 26, 1005, 1007, 1016) class PGUuid(sqltypes.UUID[sqltypes._UUID_RETURN]): render_bind_cast = True render_literal_cast = True if TYPE_CHECKING: @overload def __init__( self: PGUuid[_python_UUID], as_uuid: Literal[True] = ... ) -> None: ... @overload def __init__( self: PGUuid[str], as_uuid: Literal[False] = ... ) -> None: ... def __init__(self, as_uuid: bool = True) -> None: ... class BYTEA(sqltypes.LargeBinary): __visit_name__ = "BYTEA" class _NetworkAddressTypeMixin: def coerce_compared_value( self, op: Optional[OperatorType], value: Any ) -> TypeEngine[Any]: if TYPE_CHECKING: assert isinstance(self, TypeEngine) return self class INET(_NetworkAddressTypeMixin, sqltypes.TypeEngine[str]): __visit_name__ = "INET" PGInet = INET class CIDR(_NetworkAddressTypeMixin, sqltypes.TypeEngine[str]): __visit_name__ = "CIDR" PGCidr = CIDR class MACADDR(_NetworkAddressTypeMixin, sqltypes.TypeEngine[str]): __visit_name__ = "MACADDR" PGMacAddr = MACADDR class MACADDR8(_NetworkAddressTypeMixin, sqltypes.TypeEngine[str]): __visit_name__ = "MACADDR8" PGMacAddr8 = MACADDR8 class MONEY(sqltypes.TypeEngine[str]): r"""Provide the PostgreSQL MONEY type. Depending on driver, result rows using this type may return a string value which includes currency symbols. For this reason, it may be preferable to provide conversion to a numerically-based currency datatype using :class:`_types.TypeDecorator`:: import re import decimal from sqlalchemy import Dialect from sqlalchemy import TypeDecorator class NumericMoney(TypeDecorator): impl = MONEY def process_result_value(self, value: Any, dialect: Dialect) -> None: if value is not None: # adjust this for the currency and numeric m = re.match(r"\$([\d.]+)", value) if m: value = decimal.Decimal(m.group(1)) return value Alternatively, the conversion may be applied as a CAST using the :meth:`_types.TypeDecorator.column_expression` method as follows:: import decimal from sqlalchemy import cast from sqlalchemy import TypeDecorator class NumericMoney(TypeDecorator): impl = MONEY def column_expression(self, column: Any): return cast(column, Numeric()) .. versionadded:: 1.2 """ # noqa: E501 __visit_name__ = "MONEY" class OID(sqltypes.TypeEngine[int]): """Provide the PostgreSQL OID type.""" __visit_name__ = "OID" class REGCONFIG(sqltypes.TypeEngine[str]): """Provide the PostgreSQL REGCONFIG type. .. versionadded:: 2.0.0rc1 """ __visit_name__ = "REGCONFIG" class TSQUERY(sqltypes.TypeEngine[str]): """Provide the PostgreSQL TSQUERY type. .. versionadded:: 2.0.0rc1 """ __visit_name__ = "TSQUERY" class REGCLASS(sqltypes.TypeEngine[str]): """Provide the PostgreSQL REGCLASS type. .. versionadded:: 1.2.7 """ __visit_name__ = "REGCLASS" class TIMESTAMP(sqltypes.TIMESTAMP): """Provide the PostgreSQL TIMESTAMP type.""" __visit_name__ = "TIMESTAMP" def __init__( self, timezone: bool = False, precision: Optional[int] = None ) -> None: """Construct a TIMESTAMP. :param timezone: boolean value if timezone present, default False :param precision: optional integer precision value .. versionadded:: 1.4 """ super().__init__(timezone=timezone) self.precision = precision class TIME(sqltypes.TIME): """PostgreSQL TIME type.""" __visit_name__ = "TIME" def __init__( self, timezone: bool = False, precision: Optional[int] = None ) -> None: """Construct a TIME. :param timezone: boolean value if timezone present, default False :param precision: optional integer precision value .. versionadded:: 1.4 """ super().__init__(timezone=timezone) self.precision = precision class INTERVAL(type_api.NativeForEmulated, sqltypes._AbstractInterval): """PostgreSQL INTERVAL type.""" __visit_name__ = "INTERVAL" native = True def __init__( self, precision: Optional[int] = None, fields: Optional[str] = None ) -> None: """Construct an INTERVAL. :param precision: optional integer precision value :param fields: string fields specifier. allows storage of fields to be limited, such as ``"YEAR"``, ``"MONTH"``, ``"DAY TO HOUR"``, etc. .. versionadded:: 1.2 """ self.precision = precision self.fields = fields @classmethod def adapt_emulated_to_native( cls, interval: sqltypes.Interval, **kw: Any # type: ignore[override] ) -> INTERVAL: return INTERVAL(precision=interval.second_precision) @property def _type_affinity(self) -> Type[sqltypes.Interval]: return sqltypes.Interval def as_generic(self, allow_nulltype: bool = False) -> sqltypes.Interval: return sqltypes.Interval(native=True, second_precision=self.precision) @property def python_type(self) -> Type[dt.timedelta]: return dt.timedelta def literal_processor( self, dialect: Dialect ) -> Optional[_LiteralProcessorType[dt.timedelta]]: def process(value: dt.timedelta) -> str: return f"make_interval(secs=>{value.total_seconds()})" return process PGInterval = INTERVAL class BIT(sqltypes.TypeEngine[int]): __visit_name__ = "BIT" def __init__( self, length: Optional[int] = None, varying: bool = False ) -> None: if varying: # BIT VARYING can be unlimited-length, so no default self.length = length else: # BIT without VARYING defaults to length 1 self.length = length or 1 self.varying = varying PGBit = BIT class TSVECTOR(sqltypes.TypeEngine[str]): """The :class:`_postgresql.TSVECTOR` type implements the PostgreSQL text search type TSVECTOR. It can be used to do full text queries on natural language documents. .. seealso:: :ref:`postgresql_match` """ __visit_name__ = "TSVECTOR" class CITEXT(sqltypes.TEXT): """Provide the PostgreSQL CITEXT type. .. versionadded:: 2.0.7 """ __visit_name__ = "CITEXT" def coerce_compared_value( self, op: Optional[OperatorType], value: Any ) -> TypeEngine[Any]: return self sqlalchemy/dialects/postgresql/hstore.py 0000755 00000027236 15125143220 0014567 0 ustar 00 # dialects/postgresql/hstore.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors import re from .array import ARRAY from .operators import CONTAINED_BY from .operators import CONTAINS from .operators import GETITEM from .operators import HAS_ALL from .operators import HAS_ANY from .operators import HAS_KEY from ... import types as sqltypes from ...sql import functions as sqlfunc __all__ = ("HSTORE", "hstore") class HSTORE(sqltypes.Indexable, sqltypes.Concatenable, sqltypes.TypeEngine): """Represent the PostgreSQL HSTORE type. The :class:`.HSTORE` type stores dictionaries containing strings, e.g.:: data_table = Table( "data_table", metadata, Column("id", Integer, primary_key=True), Column("data", HSTORE), ) with engine.connect() as conn: conn.execute( data_table.insert(), data={"key1": "value1", "key2": "value2"} ) :class:`.HSTORE` provides for a wide range of operations, including: * Index operations:: data_table.c.data["some key"] == "some value" * Containment operations:: data_table.c.data.has_key("some key") data_table.c.data.has_all(["one", "two", "three"]) * Concatenation:: data_table.c.data + {"k1": "v1"} For a full list of special methods see :class:`.HSTORE.comparator_factory`. .. container:: topic **Detecting Changes in HSTORE columns when using the ORM** For usage with the SQLAlchemy ORM, it may be desirable to combine the usage of :class:`.HSTORE` with :class:`.MutableDict` dictionary now part of the :mod:`sqlalchemy.ext.mutable` extension. This extension will allow "in-place" changes to the dictionary, e.g. addition of new keys or replacement/removal of existing keys to/from the current dictionary, to produce events which will be detected by the unit of work:: from sqlalchemy.ext.mutable import MutableDict class MyClass(Base): __tablename__ = "data_table" id = Column(Integer, primary_key=True) data = Column(MutableDict.as_mutable(HSTORE)) my_object = session.query(MyClass).one() # in-place mutation, requires Mutable extension # in order for the ORM to detect my_object.data["some_key"] = "some value" session.commit() When the :mod:`sqlalchemy.ext.mutable` extension is not used, the ORM will not be alerted to any changes to the contents of an existing dictionary, unless that dictionary value is re-assigned to the HSTORE-attribute itself, thus generating a change event. .. seealso:: :class:`.hstore` - render the PostgreSQL ``hstore()`` function. """ # noqa: E501 __visit_name__ = "HSTORE" hashable = False text_type = sqltypes.Text() def __init__(self, text_type=None): """Construct a new :class:`.HSTORE`. :param text_type: the type that should be used for indexed values. Defaults to :class:`_types.Text`. """ if text_type is not None: self.text_type = text_type class Comparator( sqltypes.Indexable.Comparator, sqltypes.Concatenable.Comparator ): """Define comparison operations for :class:`.HSTORE`.""" def has_key(self, other): """Boolean expression. Test for presence of a key. Note that the key may be a SQLA expression. """ return self.operate(HAS_KEY, other, result_type=sqltypes.Boolean) def has_all(self, other): """Boolean expression. Test for presence of all keys in jsonb""" return self.operate(HAS_ALL, other, result_type=sqltypes.Boolean) def has_any(self, other): """Boolean expression. Test for presence of any key in jsonb""" return self.operate(HAS_ANY, other, result_type=sqltypes.Boolean) def contains(self, other, **kwargs): """Boolean expression. Test if keys (or array) are a superset of/contained the keys of the argument jsonb expression. kwargs may be ignored by this operator but are required for API conformance. """ return self.operate(CONTAINS, other, result_type=sqltypes.Boolean) def contained_by(self, other): """Boolean expression. Test if keys are a proper subset of the keys of the argument jsonb expression. """ return self.operate( CONTAINED_BY, other, result_type=sqltypes.Boolean ) def _setup_getitem(self, index): return GETITEM, index, self.type.text_type def defined(self, key): """Boolean expression. Test for presence of a non-NULL value for the key. Note that the key may be a SQLA expression. """ return _HStoreDefinedFunction(self.expr, key) def delete(self, key): """HStore expression. Returns the contents of this hstore with the given key deleted. Note that the key may be a SQLA expression. """ if isinstance(key, dict): key = _serialize_hstore(key) return _HStoreDeleteFunction(self.expr, key) def slice(self, array): """HStore expression. Returns a subset of an hstore defined by array of keys. """ return _HStoreSliceFunction(self.expr, array) def keys(self): """Text array expression. Returns array of keys.""" return _HStoreKeysFunction(self.expr) def vals(self): """Text array expression. Returns array of values.""" return _HStoreValsFunction(self.expr) def array(self): """Text array expression. Returns array of alternating keys and values. """ return _HStoreArrayFunction(self.expr) def matrix(self): """Text array expression. Returns array of [key, value] pairs.""" return _HStoreMatrixFunction(self.expr) comparator_factory = Comparator def bind_processor(self, dialect): # note that dialect-specific types like that of psycopg and # psycopg2 will override this method to allow driver-level conversion # instead, see _PsycopgHStore def process(value): if isinstance(value, dict): return _serialize_hstore(value) else: return value return process def result_processor(self, dialect, coltype): # note that dialect-specific types like that of psycopg and # psycopg2 will override this method to allow driver-level conversion # instead, see _PsycopgHStore def process(value): if value is not None: return _parse_hstore(value) else: return value return process class hstore(sqlfunc.GenericFunction): """Construct an hstore value within a SQL expression using the PostgreSQL ``hstore()`` function. The :class:`.hstore` function accepts one or two arguments as described in the PostgreSQL documentation. E.g.:: from sqlalchemy.dialects.postgresql import array, hstore select(hstore("key1", "value1")) select( hstore( array(["key1", "key2", "key3"]), array(["value1", "value2", "value3"]), ) ) .. seealso:: :class:`.HSTORE` - the PostgreSQL ``HSTORE`` datatype. """ type = HSTORE name = "hstore" inherit_cache = True class _HStoreDefinedFunction(sqlfunc.GenericFunction): type = sqltypes.Boolean name = "defined" inherit_cache = True class _HStoreDeleteFunction(sqlfunc.GenericFunction): type = HSTORE name = "delete" inherit_cache = True class _HStoreSliceFunction(sqlfunc.GenericFunction): type = HSTORE name = "slice" inherit_cache = True class _HStoreKeysFunction(sqlfunc.GenericFunction): type = ARRAY(sqltypes.Text) name = "akeys" inherit_cache = True class _HStoreValsFunction(sqlfunc.GenericFunction): type = ARRAY(sqltypes.Text) name = "avals" inherit_cache = True class _HStoreArrayFunction(sqlfunc.GenericFunction): type = ARRAY(sqltypes.Text) name = "hstore_to_array" inherit_cache = True class _HStoreMatrixFunction(sqlfunc.GenericFunction): type = ARRAY(sqltypes.Text) name = "hstore_to_matrix" inherit_cache = True # # parsing. note that none of this is used with the psycopg2 backend, # which provides its own native extensions. # # My best guess at the parsing rules of hstore literals, since no formal # grammar is given. This is mostly reverse engineered from PG's input parser # behavior. HSTORE_PAIR_RE = re.compile( r""" ( "(?P<key> (\\ . | [^"])* )" # Quoted key ) [ ]* => [ ]* # Pair operator, optional adjoining whitespace ( (?P<value_null> NULL ) # NULL value | "(?P<value> (\\ . | [^"])* )" # Quoted value ) """, re.VERBOSE, ) HSTORE_DELIMITER_RE = re.compile( r""" [ ]* , [ ]* """, re.VERBOSE, ) def _parse_error(hstore_str, pos): """format an unmarshalling error.""" ctx = 20 hslen = len(hstore_str) parsed_tail = hstore_str[max(pos - ctx - 1, 0) : min(pos, hslen)] residual = hstore_str[min(pos, hslen) : min(pos + ctx + 1, hslen)] if len(parsed_tail) > ctx: parsed_tail = "[...]" + parsed_tail[1:] if len(residual) > ctx: residual = residual[:-1] + "[...]" return "After %r, could not parse residual at position %d: %r" % ( parsed_tail, pos, residual, ) def _parse_hstore(hstore_str): """Parse an hstore from its literal string representation. Attempts to approximate PG's hstore input parsing rules as closely as possible. Although currently this is not strictly necessary, since the current implementation of hstore's output syntax is stricter than what it accepts as input, the documentation makes no guarantees that will always be the case. """ result = {} pos = 0 pair_match = HSTORE_PAIR_RE.match(hstore_str) while pair_match is not None: key = pair_match.group("key").replace(r"\"", '"').replace("\\\\", "\\") if pair_match.group("value_null"): value = None else: value = ( pair_match.group("value") .replace(r"\"", '"') .replace("\\\\", "\\") ) result[key] = value pos += pair_match.end() delim_match = HSTORE_DELIMITER_RE.match(hstore_str[pos:]) if delim_match is not None: pos += delim_match.end() pair_match = HSTORE_PAIR_RE.match(hstore_str[pos:]) if pos != len(hstore_str): raise ValueError(_parse_error(hstore_str, pos)) return result def _serialize_hstore(val): """Serialize a dictionary into an hstore literal. Keys and values must both be strings (except None for values). """ def esc(s, position): if position == "value" and s is None: return "NULL" elif isinstance(s, str): return '"%s"' % s.replace("\\", "\\\\").replace('"', r"\"") else: raise ValueError( "%r in %s position is not a string." % (s, position) ) return ", ".join( "%s=>%s" % (esc(k, "key"), esc(v, "value")) for k, v in val.items() ) sqlalchemy/dialects/postgresql/array.py 0000755 00000041132 15125143220 0014370 0 ustar 00 # dialects/postgresql/array.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php from __future__ import annotations import re from typing import Any as typing_Any from typing import Iterable from typing import Optional from typing import Sequence from typing import TYPE_CHECKING from typing import TypeVar from typing import Union from .operators import CONTAINED_BY from .operators import CONTAINS from .operators import OVERLAP from ... import types as sqltypes from ... import util from ...sql import expression from ...sql import operators from ...sql.visitors import InternalTraversal if TYPE_CHECKING: from ...engine.interfaces import Dialect from ...sql._typing import _ColumnExpressionArgument from ...sql._typing import _TypeEngineArgument from ...sql.elements import ColumnElement from ...sql.elements import Grouping from ...sql.expression import BindParameter from ...sql.operators import OperatorType from ...sql.selectable import _SelectIterable from ...sql.type_api import _BindProcessorType from ...sql.type_api import _LiteralProcessorType from ...sql.type_api import _ResultProcessorType from ...sql.type_api import TypeEngine from ...sql.visitors import _TraverseInternalsType from ...util.typing import Self _T = TypeVar("_T", bound=typing_Any) def Any( other: typing_Any, arrexpr: _ColumnExpressionArgument[_T], operator: OperatorType = operators.eq, ) -> ColumnElement[bool]: """A synonym for the ARRAY-level :meth:`.ARRAY.Comparator.any` method. See that method for details. """ return arrexpr.any(other, operator) # type: ignore[no-any-return, union-attr] # noqa: E501 def All( other: typing_Any, arrexpr: _ColumnExpressionArgument[_T], operator: OperatorType = operators.eq, ) -> ColumnElement[bool]: """A synonym for the ARRAY-level :meth:`.ARRAY.Comparator.all` method. See that method for details. """ return arrexpr.all(other, operator) # type: ignore[no-any-return, union-attr] # noqa: E501 class array(expression.ExpressionClauseList[_T]): """A PostgreSQL ARRAY literal. This is used to produce ARRAY literals in SQL expressions, e.g.:: from sqlalchemy.dialects.postgresql import array from sqlalchemy.dialects import postgresql from sqlalchemy import select, func stmt = select(array([1, 2]) + array([3, 4, 5])) print(stmt.compile(dialect=postgresql.dialect())) Produces the SQL: .. sourcecode:: sql SELECT ARRAY[%(param_1)s, %(param_2)s] || ARRAY[%(param_3)s, %(param_4)s, %(param_5)s]) AS anon_1 An instance of :class:`.array` will always have the datatype :class:`_types.ARRAY`. The "inner" type of the array is inferred from the values present, unless the :paramref:`_postgresql.array.type_` keyword argument is passed:: array(["foo", "bar"], type_=CHAR) When constructing an empty array, the :paramref:`_postgresql.array.type_` argument is particularly important as PostgreSQL server typically requires a cast to be rendered for the inner type in order to render an empty array. SQLAlchemy's compilation for the empty array will produce this cast so that:: stmt = array([], type_=Integer) print(stmt.compile(dialect=postgresql.dialect())) Produces: .. sourcecode:: sql ARRAY[]::INTEGER[] As required by PostgreSQL for empty arrays. .. versionadded:: 2.0.40 added support to render empty PostgreSQL array literals with a required cast. Multidimensional arrays are produced by nesting :class:`.array` constructs. The dimensionality of the final :class:`_types.ARRAY` type is calculated by recursively adding the dimensions of the inner :class:`_types.ARRAY` type:: stmt = select( array( [array([1, 2]), array([3, 4]), array([column("q"), column("x")])] ) ) print(stmt.compile(dialect=postgresql.dialect())) Produces: .. sourcecode:: sql SELECT ARRAY[ ARRAY[%(param_1)s, %(param_2)s], ARRAY[%(param_3)s, %(param_4)s], ARRAY[q, x] ] AS anon_1 .. versionadded:: 1.3.6 added support for multidimensional array literals .. seealso:: :class:`_postgresql.ARRAY` """ # noqa: E501 __visit_name__ = "array" stringify_dialect = "postgresql" _traverse_internals: _TraverseInternalsType = [ ("clauses", InternalTraversal.dp_clauseelement_tuple), ("type", InternalTraversal.dp_type), ] def __init__( self, clauses: Iterable[_T], *, type_: Optional[_TypeEngineArgument[_T]] = None, **kw: typing_Any, ): r"""Construct an ARRAY literal. :param clauses: iterable, such as a list, containing elements to be rendered in the array :param type\_: optional type. If omitted, the type is inferred from the contents of the array. """ super().__init__(operators.comma_op, *clauses, **kw) main_type = ( type_ if type_ is not None else self.clauses[0].type if self.clauses else sqltypes.NULLTYPE ) if isinstance(main_type, ARRAY): self.type = ARRAY( main_type.item_type, dimensions=( main_type.dimensions + 1 if main_type.dimensions is not None else 2 ), ) # type: ignore[assignment] else: self.type = ARRAY(main_type) # type: ignore[assignment] @property def _select_iterable(self) -> _SelectIterable: return (self,) def _bind_param( self, operator: OperatorType, obj: typing_Any, type_: Optional[TypeEngine[_T]] = None, _assume_scalar: bool = False, ) -> BindParameter[_T]: if _assume_scalar or operator is operators.getitem: return expression.BindParameter( None, obj, _compared_to_operator=operator, type_=type_, _compared_to_type=self.type, unique=True, ) else: return array( [ self._bind_param( operator, o, _assume_scalar=True, type_=type_ ) for o in obj ] ) # type: ignore[return-value] def self_group( self, against: Optional[OperatorType] = None ) -> Union[Self, Grouping[_T]]: if against in (operators.any_op, operators.all_op, operators.getitem): return expression.Grouping(self) else: return self class ARRAY(sqltypes.ARRAY[_T]): """PostgreSQL ARRAY type. The :class:`_postgresql.ARRAY` type is constructed in the same way as the core :class:`_types.ARRAY` type; a member type is required, and a number of dimensions is recommended if the type is to be used for more than one dimension:: from sqlalchemy.dialects import postgresql mytable = Table( "mytable", metadata, Column("data", postgresql.ARRAY(Integer, dimensions=2)), ) The :class:`_postgresql.ARRAY` type provides all operations defined on the core :class:`_types.ARRAY` type, including support for "dimensions", indexed access, and simple matching such as :meth:`.types.ARRAY.Comparator.any` and :meth:`.types.ARRAY.Comparator.all`. :class:`_postgresql.ARRAY` class also provides PostgreSQL-specific methods for containment operations, including :meth:`.postgresql.ARRAY.Comparator.contains` :meth:`.postgresql.ARRAY.Comparator.contained_by`, and :meth:`.postgresql.ARRAY.Comparator.overlap`, e.g.:: mytable.c.data.contains([1, 2]) Indexed access is one-based by default, to match that of PostgreSQL; for zero-based indexed access, set :paramref:`_postgresql.ARRAY.zero_indexes`. Additionally, the :class:`_postgresql.ARRAY` type does not work directly in conjunction with the :class:`.ENUM` type. For a workaround, see the special type at :ref:`postgresql_array_of_enum`. .. container:: topic **Detecting Changes in ARRAY columns when using the ORM** The :class:`_postgresql.ARRAY` type, when used with the SQLAlchemy ORM, does not detect in-place mutations to the array. In order to detect these, the :mod:`sqlalchemy.ext.mutable` extension must be used, using the :class:`.MutableList` class:: from sqlalchemy.dialects.postgresql import ARRAY from sqlalchemy.ext.mutable import MutableList class SomeOrmClass(Base): # ... data = Column(MutableList.as_mutable(ARRAY(Integer))) This extension will allow "in-place" changes such to the array such as ``.append()`` to produce events which will be detected by the unit of work. Note that changes to elements **inside** the array, including subarrays that are mutated in place, are **not** detected. Alternatively, assigning a new array value to an ORM element that replaces the old one will always trigger a change event. .. seealso:: :class:`_types.ARRAY` - base array type :class:`_postgresql.array` - produces a literal array value. """ def __init__( self, item_type: _TypeEngineArgument[_T], as_tuple: bool = False, dimensions: Optional[int] = None, zero_indexes: bool = False, ): """Construct an ARRAY. E.g.:: Column("myarray", ARRAY(Integer)) Arguments are: :param item_type: The data type of items of this array. Note that dimensionality is irrelevant here, so multi-dimensional arrays like ``INTEGER[][]``, are constructed as ``ARRAY(Integer)``, not as ``ARRAY(ARRAY(Integer))`` or such. :param as_tuple=False: Specify whether return results should be converted to tuples from lists. DBAPIs such as psycopg2 return lists by default. When tuples are returned, the results are hashable. :param dimensions: if non-None, the ARRAY will assume a fixed number of dimensions. This will cause the DDL emitted for this ARRAY to include the exact number of bracket clauses ``[]``, and will also optimize the performance of the type overall. Note that PG arrays are always implicitly "non-dimensioned", meaning they can store any number of dimensions no matter how they were declared. :param zero_indexes=False: when True, index values will be converted between Python zero-based and PostgreSQL one-based indexes, e.g. a value of one will be added to all index values before passing to the database. """ if isinstance(item_type, ARRAY): raise ValueError( "Do not nest ARRAY types; ARRAY(basetype) " "handles multi-dimensional arrays of basetype" ) if isinstance(item_type, type): item_type = item_type() self.item_type = item_type self.as_tuple = as_tuple self.dimensions = dimensions self.zero_indexes = zero_indexes class Comparator(sqltypes.ARRAY.Comparator[_T]): """Define comparison operations for :class:`_types.ARRAY`. Note that these operations are in addition to those provided by the base :class:`.types.ARRAY.Comparator` class, including :meth:`.types.ARRAY.Comparator.any` and :meth:`.types.ARRAY.Comparator.all`. """ def contains( self, other: typing_Any, **kwargs: typing_Any ) -> ColumnElement[bool]: """Boolean expression. Test if elements are a superset of the elements of the argument array expression. kwargs may be ignored by this operator but are required for API conformance. """ return self.operate(CONTAINS, other, result_type=sqltypes.Boolean) def contained_by(self, other: typing_Any) -> ColumnElement[bool]: """Boolean expression. Test if elements are a proper subset of the elements of the argument array expression. """ return self.operate( CONTAINED_BY, other, result_type=sqltypes.Boolean ) def overlap(self, other: typing_Any) -> ColumnElement[bool]: """Boolean expression. Test if array has elements in common with an argument array expression. """ return self.operate(OVERLAP, other, result_type=sqltypes.Boolean) comparator_factory = Comparator @util.memoized_property def _against_native_enum(self) -> bool: return ( isinstance(self.item_type, sqltypes.Enum) and self.item_type.native_enum # type: ignore[attr-defined] ) def literal_processor( self, dialect: Dialect ) -> Optional[_LiteralProcessorType[_T]]: item_proc = self.item_type.dialect_impl(dialect).literal_processor( dialect ) if item_proc is None: return None def to_str(elements: Iterable[typing_Any]) -> str: return f"ARRAY[{', '.join(elements)}]" def process(value: Sequence[typing_Any]) -> str: inner = self._apply_item_processor( value, item_proc, self.dimensions, to_str ) return inner return process def bind_processor( self, dialect: Dialect ) -> Optional[_BindProcessorType[Sequence[typing_Any]]]: item_proc = self.item_type.dialect_impl(dialect).bind_processor( dialect ) def process( value: Optional[Sequence[typing_Any]], ) -> Optional[list[typing_Any]]: if value is None: return value else: return self._apply_item_processor( value, item_proc, self.dimensions, list ) return process def result_processor( self, dialect: Dialect, coltype: object ) -> _ResultProcessorType[Sequence[typing_Any]]: item_proc = self.item_type.dialect_impl(dialect).result_processor( dialect, coltype ) def process( value: Sequence[typing_Any], ) -> Optional[Sequence[typing_Any]]: if value is None: return value else: return self._apply_item_processor( value, item_proc, self.dimensions, tuple if self.as_tuple else list, ) if self._against_native_enum: super_rp = process pattern = re.compile(r"^{(.*)}$") def handle_raw_string(value: str) -> list[str]: inner = pattern.match(value).group(1) # type: ignore[union-attr] # noqa: E501 return _split_enum_values(inner) def process( value: Sequence[typing_Any], ) -> Optional[Sequence[typing_Any]]: if value is None: return value # isinstance(value, str) is required to handle # the case where a TypeDecorator for and Array of Enum is # used like was required in sa < 1.3.17 return super_rp( handle_raw_string(value) if isinstance(value, str) else value ) return process def _split_enum_values(array_string: str) -> list[str]: if '"' not in array_string: # no escape char is present so it can just split on the comma return array_string.split(",") if array_string else [] # handles quoted strings from: # r'abc,"quoted","also\\\\quoted", "quoted, comma", "esc \" quot", qpr' # returns # ['abc', 'quoted', 'also\\quoted', 'quoted, comma', 'esc " quot', 'qpr'] text = array_string.replace(r"\"", "_$ESC_QUOTE$_") text = text.replace(r"\\", "\\") result = [] on_quotes = re.split(r'(")', text) in_quotes = False for tok in on_quotes: if tok == '"': in_quotes = not in_quotes elif in_quotes: result.append(tok.replace("_$ESC_QUOTE$_", '"')) else: result.extend(re.findall(r"([^\s,]+),?", tok)) return result sqlalchemy/dialects/postgresql/__pycache__/psycopg.cpython-39.pyc 0000644 00000064136 15125143220 0021233 0 ustar 00 a ��Jh [ � @ s& d Z ddlmZ ddlmZ ddlZddlZddlmZ ddlm Z ddl m Z dd l m Z dd l mZ dd lmZ dd lmZ dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddl mZ ddl mZ ddl m Z ddl m Z ddl m!Z! ddl m"Z" e �r.ddlm#Z# ddl$m%Z% e�&d �Z'G d d � d e j(�Z)G d d � d e�Z*G d!d"� d"e�Z+G d#d$� d$e�Z,G d%d&� d&e jj-�Z.G d'd(� d(e jj/�Z0G d)d*� d*e�Z1G d+d,� d,e�Z2G d-d.� d.e j3�Z4G d/d0� d0e j5�Z6G d1d2� d2e j7�Z8G d3d4� d4e j9�Z:G d5d6� d6e j;�Z<G d7d8� d8e j=�Z>G d9d:� d:e j?�Z@G d;d<� d<e jA�ZBG d=d>� d>e jC�ZDG d?d@� d@e jE�ZFG dAdB� dBe�ZGG dCdD� dDe�ZHG dEdF� dFe�ZIdGdH� ZJG dIdJ� dJe �ZKG dKdL� dL�ZLG dMdN� dNeL�ZMG dOdP� dPe �ZNG dQdR� dReN�ZOG dSdT� dT�ZPG dUdV� dVeK�ZQeKZReQZSdS )Wau .. dialect:: postgresql+psycopg :name: psycopg (a.k.a. psycopg 3) :dbapi: psycopg :connectstring: postgresql+psycopg://user:password@host:port/dbname[?key=value&key=value...] :url: https://pypi.org/project/psycopg/ ``psycopg`` is the package and module name for version 3 of the ``psycopg`` database driver, formerly known as ``psycopg2``. This driver is different enough from its ``psycopg2`` predecessor that SQLAlchemy supports it via a totally separate dialect; support for ``psycopg2`` is expected to remain for as long as that package continues to function for modern Python versions, and also remains the default dialect for the ``postgresql://`` dialect series. The SQLAlchemy ``psycopg`` dialect provides both a sync and an async implementation under the same dialect name. The proper version is selected depending on how the engine is created: * calling :func:`_sa.create_engine` with ``postgresql+psycopg://...`` will automatically select the sync version, e.g.:: from sqlalchemy import create_engine sync_engine = create_engine( "postgresql+psycopg://scott:tiger@localhost/test" ) * calling :func:`_asyncio.create_async_engine` with ``postgresql+psycopg://...`` will automatically select the async version, e.g.:: from sqlalchemy.ext.asyncio import create_async_engine asyncio_engine = create_async_engine( "postgresql+psycopg://scott:tiger@localhost/test" ) The asyncio version of the dialect may also be specified explicitly using the ``psycopg_async`` suffix, as:: from sqlalchemy.ext.asyncio import create_async_engine asyncio_engine = create_async_engine( "postgresql+psycopg_async://scott:tiger@localhost/test" ) .. seealso:: :ref:`postgresql_psycopg2` - The SQLAlchemy ``psycopg`` dialect shares most of its behavior with the ``psycopg2`` dialect. Further documentation is available there. Using a different Cursor class ------------------------------ One of the differences between ``psycopg`` and the older ``psycopg2`` is how bound parameters are handled: ``psycopg2`` would bind them client side, while ``psycopg`` by default will bind them server side. It's possible to configure ``psycopg`` to do client side binding by specifying the ``cursor_factory`` to be ``ClientCursor`` when creating the engine:: from psycopg import ClientCursor client_side_engine = create_engine( "postgresql+psycopg://...", connect_args={"cursor_factory": ClientCursor}, ) Similarly when using an async engine the ``AsyncClientCursor`` can be specified:: from psycopg import AsyncClientCursor client_side_engine = create_async_engine( "postgresql+psycopg://...", connect_args={"cursor_factory": AsyncClientCursor}, ) .. seealso:: `Client-side-binding cursors <https://www.psycopg.org/psycopg3/docs/advanced/cursors.html#client-side-binding-cursors>`_ � )� annotations)�dequeN)�cast)� TYPE_CHECKING� )�ranges)�_PGDialect_common_psycopg)�"_PGExecutionContext_common_psycopg)�INTERVAL)� PGCompiler)�PGIdentifierPreparer)� REGCONFIG)�JSON)�JSONB)� JSONPathType)�CITEXT� )�pool)�util)�AdaptedConnection)�sqltypes)�await_fallback)� await_only)�Iterable)�AsyncConnectionz sqlalchemy.dialects.postgresqlc @ s e Zd ZdZdS )� _PGStringTN��__name__� __module__� __qualname__�render_bind_cast� r! r! �[/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/postgresql/psycopg.pyr � s r c @ s e Zd ZdZdS )� _PGREGCONFIGTNr r! r! r! r" r# � s r# c @ s e Zd Zdd� Zdd� ZdS )�_PGJSONc C s | � d |j�S �N)�_make_bind_processor� _psycopg_Json��self�dialectr! r! r" �bind_processor� s z_PGJSON.bind_processorc C s d S r% r! �r) r* �coltyper! r! r" �result_processor� s z_PGJSON.result_processorN�r r r r+ r. r! r! r! r" r$ � s r$ c @ s e Zd Zdd� Zdd� ZdS )�_PGJSONBc C s | � d |j�S r% )r& �_psycopg_Jsonbr( r! r! r" r+ � s z_PGJSONB.bind_processorc C s d S r% r! r, r! r! r" r. � s z_PGJSONB.result_processorNr/ r! r! r! r" r0 � s r0 c @ s e Zd ZdZdZdS )�_PGJSONIntIndexTypeZjson_int_indexTN�r r r Z__visit_name__r r! r! r! r" r2 � s r2 c @ s e Zd ZdZdZdS )�_PGJSONStrIndexTypeZjson_str_indexTNr3 r! r! r! r" r4 � s r4 c @ s e Zd ZdS )�_PGJSONPathTypeN�r r r r! r! r! r" r5 � s r5 c @ s e Zd ZdZdS )� _PGIntervalTNr r! r! r! r" r7 � s r7 c @ s e Zd ZdZdS )� _PGTimeStampTNr r! r! r! r" r8 � s r8 c @ s e Zd ZdZdS )�_PGDateTNr r! r! r! r" r9 � s r9 c @ s e Zd ZdZdS )�_PGTimeTNr r! r! r! r" r: � s r: c @ s e Zd ZdZdS )� _PGIntegerTNr r! r! r! r" r; � s r; c @ s e Zd ZdZdS )�_PGSmallIntegerTNr r! r! r! r" r< � s r< c @ s e Zd ZdZdS )� _PGNullTypeTNr r! r! r! r" r= � s r= c @ s e Zd ZdZdS )� _PGBigIntegerTNr r! r! r! r" r> � s r> c @ s e Zd ZdZdS )� _PGBooleanTNr r! r! r! r" r? � s r? c @ s e Zd Zdd� Zdd� ZdS )� _PsycopgRangec s t t|�j� � fdd�}|S )Nc s& t | tj�r"� | j| j| j| j�} | S r% )� isinstancer �Range�lower�upper�bounds�empty��value�� psycopg_Ranger! r" �to_range� s �z._PsycopgRange.bind_processor.<locals>.to_range)r �PGDialect_psycopg�_psycopg_Range�r) r* rK r! rI r" r+ � s z _PsycopgRange.bind_processorc C s dd� }|S )Nc S s2 | d ur.t j| j| j| jr | jnd| j d�} | S )N�[)�rE rF �r rB Z_lowerZ_upperZ_boundsrG r! r! r" rK � s �z0_PsycopgRange.result_processor.<locals>.to_ranger! �r) r* r- rK r! r! r" r. � s z _PsycopgRange.result_processorNr/ r! r! r! r" r@ � s r@ c @ s e Zd Zdd� Zdd� ZdS )�_PsycopgMultiRangec s4 t t|�j�t t|�j�td �� � ��fdd�}|S )Nc s0 t | t� �f�r| S ��fdd�td| �D ��S )Nc s" g | ]}� |j |j|j|j��qS r! )rC rD rE rF )�.0�elementrI r! r" � <listcomp>� s ��zG_PsycopgMultiRange.bind_processor.<locals>.to_range.<locals>.<listcomp>zIterable[ranges.Range])rA �strr rG �ZNoneTypeZpsycopg_MultirangerJ r! r" rK � s ��z3_PsycopgMultiRange.bind_processor.<locals>.to_range)r rL rM �_psycopg_Multirange�typerN r! rX r" r+ � s �z!_PsycopgMultiRange.bind_processorc C s dd� }|S )Nc S s$ | d u r d S t �dd� | D ��S d S )Nc s s4 | ],}t j|j|j|jr |jnd |j d�V qdS )rO rP NrQ )rT �elemr! r! r" � <genexpr> s ��zH_PsycopgMultiRange.result_processor.<locals>.to_range.<locals>.<genexpr>)r Z MultiRangerG r! r! r" rK s �z5_PsycopgMultiRange.result_processor.<locals>.to_ranger! rR r! r! r" r. s z#_PsycopgMultiRange.result_processorNr/ r! r! r! r" rS � s rS c @ s e Zd ZdS )�PGExecutionContext_psycopgNr6 r! r! r! r" r] s r] c @ s e Zd ZdS )�PGCompiler_psycopgNr6 r! r! r! r" r^ s r^ c @ s e Zd ZdS )� PGIdentifierPreparer_psycopgNr6 r! r! r! r" r_ s r_ c C s t �d| j| j� d S )Nz%s: %s)�logger�infoZseverityZmessage_primary)Z diagnosticr! r! r" � _log_notices! s rb c ) s� e Zd ZdZdZdZdZdZeZ e Z e Z dZdZdZe�ejejeeeeee e ejee e ejj e ejj!e"ejj#e$ej%e&e'e&ej(e)ej*e+ej,e-ej.e/ej0e1ej2e3e4j5e6e4j7e8i�Z� fdd�Z9� fdd �Z:d d � Z;� fd d �Z<e=dd� �Z>e=dd� �Z?ej@dd� �ZAej@dd� �ZBej@dd� �ZCej@dd� �ZDej@dd� �ZEej@d d � �ZFd d � ZG� fd d!�ZHd"d#� ZId$d%� ZJd&d'� ZKd(d)� ZLd*d+� ZMd5d-d.�ZNd6d/d0�ZOd7d1d2�ZPej@d3d4� �ZQ� ZRS )8rL �psycopgTZpyformat)r r Nc s� t � jf i |�� | jr�t�d| jj�}|rJtdd� |�ddd�D ��| _| jdk r\t d��d d l m } || jj � | _ }| jd u r�d d l}|�d |jjj� |�d |jjj� | jr�d dlm} || j|� | jr�d dlm} || j|� d S )Nz(\d+)\.(\d+)(?:\.(\d+))?c s s | ]}|d urt |�V qd S r% )�int)rT �xr! r! r" r\ T s z-PGDialect_psycopg.__init__.<locals>.<genexpr>r � r )r r rf z,psycopg version 3.0.2 or higher is required.r )� AdaptersMapFZinetZcidr)�set_json_loads)�set_json_dumps)�super�__init__�dbapi�re�match� __version__�tuple�group�psycopg_version� ImportErrorZ psycopg.adaptrg �adapters�_psycopg_adapters_mapZ_native_inet_typesZpsycopg.types.stringZregister_loader�types�stringZ TextLoaderZ_json_deserializerZpsycopg.types.jsonrh Z_json_serializerri )r) �kwargs�mrg Z adapters_maprc rh ri �� __class__r! r" rk N s: � � � � � zPGDialect_psycopg.__init__c s< t � �|�\}}| jr | j|d< | jd ur4| j|d< ||fS )N�context�client_encoding)rj �create_connect_argsru r} )r) �urlZcargsZcparamsrz r! r" r~ w s z%PGDialect_psycopg.create_connect_argsc C s ddl m} |�|jj|�S �Nr )�TypeInfo)� psycopg.typesr� �fetch� connection�driver_connection)r) r� �namer� r! r! r" �_type_info_fetch� s z"PGDialect_psycopg._type_info_fetchc sx t � �|� | jsd| _| jrt| �|d�}|d u| _| jrtddlm} | j sPJ �||| j � |j sfJ �|||j j � d S )NFZhstorer )�register_hstore) rj � initializeZinsert_returningZ insert_executemany_returningZuse_native_hstorer� �_has_native_hstoreZpsycopg.types.hstorer� ru r� r� )r) r� ra r� rz r! r" r� � s z PGDialect_psycopg.initializec C s dd l }|S )Nr )rc )�clsrc r! r! r" � import_dbapi� s z PGDialect_psycopg.import_dbapic C s t S r% )�PGDialectAsync_psycopg)r� r r! r! r" �get_async_dialect_cls� s z'PGDialect_psycopg.get_async_dialect_clsc C s& | j jj| j jj| j jj| j jjd�S )N)zREAD COMMITTEDzREAD UNCOMMITTEDzREPEATABLE READ� SERIALIZABLE)rl ZIsolationLevelZREAD_COMMITTEDZREAD_UNCOMMITTEDZREPEATABLE_READr� �r) r! r! r" �_isolation_lookup� s �z#PGDialect_psycopg._isolation_lookupc C s ddl m} |jS �Nr )�json)r� r� ZJson�r) r� r! r! r" r' � s z PGDialect_psycopg._psycopg_Jsonc C s ddl m} |jS r� )r� r� ZJsonbr� r! r! r" r1 � s z PGDialect_psycopg._psycopg_Jsonbc C s ddl m} |S )Nr )�TransactionStatus)� psycopg.pqr� )r) r� r! r! r" �_psycopg_TransactionStatus� s z,PGDialect_psycopg._psycopg_TransactionStatusc C s ddl m} |S )Nr )rB )Zpsycopg.types.rangerB )r) rB r! r! r" rM � s z PGDialect_psycopg._psycopg_Rangec C s ddl m} |S )Nr )� Multirange)Zpsycopg.types.multiranger� )r) r� r! r! r" rY � s z%PGDialect_psycopg._psycopg_Multirangec C s ||_ ||_d S r% �� autocommit�isolation_level�r) r� r� r� r! r! r" �_do_isolation_level� s z%PGDialect_psycopg._do_isolation_levelc s, |j j}t� �|�}|| jjkr(|�� |S r% )ra �transaction_statusrj �get_isolation_levelr� �IDLE�rollback)r) �dbapi_connectionZ status_beforerH rz r! r" r� � s z%PGDialect_psycopg.get_isolation_levelc C s4 |dkr| j |dd d� n| j |d| j| d� d S )NZ AUTOCOMMITTr� F)r� r� )r) r� �levelr! r! r" �set_isolation_level� s ��z%PGDialect_psycopg.set_isolation_levelc C s ||_ d S r% �Z read_only�r) r� rH r! r! r" � set_readonly� s z PGDialect_psycopg.set_readonlyc C s |j S r% r� �r) r� r! r! r" � get_readonly� s z PGDialect_psycopg.get_readonlyc s> dd� }|g� �j d ur.�fdd�}� �|� � fdd�}|S )Nc S s | � t� d S r% )Zadd_notice_handlerrb ��connr! r! r" �notices� s z-PGDialect_psycopg.on_connect.<locals>.noticesc s � � | � j� d S r% )r� r� r� r� r! r" � on_connect� s z0PGDialect_psycopg.on_connect.<locals>.on_connectc s � D ] }|| � qd S r% r! )r� �fn)�fnsr! r" r� � s )r� �append)r) r� r� r! )r� r) r" r� � s z PGDialect_psycopg.on_connectc C s* t || jj�r&|d ur&|js"|jr&dS dS )NTF)rA rl �Error�closed�broken)r) �er� �cursorr! r! r" � is_disconnect s z PGDialect_psycopg.is_disconnectFc C sp |j j}|s |jj| jjkr$|�� |j}z.|s<| �|d� |� |� W |sl| �||� n|sj| �||� 0 d S )NT) r� r� ra r� r� r� r� r� �_do_autocommit�execute)r) r� �command�recoverZ dbapi_connZbefore_autocommitr! r! r" �_do_prepared_twophase s" ��� �z'PGDialect_psycopg._do_prepared_twophasec C s. |r | j |d|� d�|d� n | �|j� d S )NzROLLBACK PREPARED '�'�r� )r� Z do_rollbackr� �r) r� �xidZ is_preparedr� r! r! r" �do_rollback_twophase s �z&PGDialect_psycopg.do_rollback_twophasec C s. |r | j |d|� d�|d� n | �|j� d S )NzCOMMIT PREPARED 'r� r� )r� Z do_commitr� r� r! r! r" �do_commit_twophase( s �z$PGDialect_psycopg.do_commit_twophasec C s dS )N�;r! r� r! r! r" � _dialect_specific_select_one2 s z.PGDialect_psycopg._dialect_specific_select_one)F)TF)TF)Sr r r Zdriver�supports_statement_cacheZ supports_server_side_cursorsZdefault_paramstyleZ supports_sane_multi_rowcountr] Zexecution_ctx_clsr^ Zstatement_compilerr_ �preparerrr r� ru r Z update_copyr Zcolspecsr �Stringr r r# r r$ r r r0 r r5 �JSONIntIndexTyper2 �JSONStrIndexTyper4 ZIntervalr7 r �Dater9 �DateTimer8 �Timer: �Integerr; � SmallIntegerr< � BigIntegerr> r ZAbstractSingleRanger@ ZAbstractMultiRangerS rk r~ r� r� � classmethodr� r� Zmemoized_propertyr� r' r1 r� rM rY r� r� r� r� r� r� r� r� r� r� r� � __classcell__r! r! rz r" rL % s� �� ) � � rL c @ s� e Zd ZdZdZdd�dd�Zdd� Zed d � �Zej d d � �Zd d � Z ddd�Z dd� Z dd� Z dd� Zddd�Zdd� ZdS ) �AsyncAdapt_psycopg_cursor)�_cursor�await_�_rowsN�None��returnc C s || _ || _t� | _d S r% )r� r� r r� )r) r� r� r! r! r" rk < s z"AsyncAdapt_psycopg_cursor.__init__c C s t | j|�S r% )�getattrr� �r) r� r! r! r" � __getattr__A s z%AsyncAdapt_psycopg_cursor.__getattr__c C s | j jS r% �r� � arraysizer� r! r! r" r� D s z#AsyncAdapt_psycopg_cursor.arraysizec C s || j _d S r% r� �r) rH r! r! r" r� H s c C s | j �� | j�� d S r% )r� �clearr� �_closer� r! r! r" �closeL s z AsyncAdapt_psycopg_cursor.closec K sT | � | jj||fi |���}| jj}|rP|j| jjkrP| � | j�� �}t|�| _ |S r% ) r� r� r� Zpgresult�status�_psycopg_ExecStatusZ TUPLES_OK�fetchallr r� )r) �query�params�kw�result�res�rowsr! r! r" r� Q s z!AsyncAdapt_psycopg_cursor.executec C s | � | j�||��S r% )r� r� � executemany)r) r� Z params_seqr! r! r" r� ] s z%AsyncAdapt_psycopg_cursor.executemanyc c s | j r| j �� V q d S r% �r� �popleftr� r! r! r" �__iter__` s z"AsyncAdapt_psycopg_cursor.__iter__c C s | j r| j �� S d S d S r% r� r� r! r! r" �fetchoned s z"AsyncAdapt_psycopg_cursor.fetchonec s6 |d u r| j j}| j� � fdd�tt|t� ���D �S )Nc s g | ] }� � � �qS r! )r� )rT �_��rrr! r" rV o � z7AsyncAdapt_psycopg_cursor.fetchmany.<locals>.<listcomp>)r� r� r� �range�min�len�r) �sizer! r� r" � fetchmanyj s z#AsyncAdapt_psycopg_cursor.fetchmanyc C s t | j�}| j�� |S r% )�listr� r� )r) �retvalr! r! r" r� q s z"AsyncAdapt_psycopg_cursor.fetchall)N)N)r r r � __slots__r� rk r� �propertyr� �setterr� r� r� r� r� r� r� r! r! r! r" r� 7 s r� c @ s@ e Zd Zddd�Zdd� Zdd� Zdd d �Zd d � Zd d� ZdS )� AsyncAdapt_psycopg_ss_cursorNc K s | � | jj||fi |��� | S r% )r� r� r� )r) r� r� r� r! r! r" r� x s z$AsyncAdapt_psycopg_ss_cursor.executec C s | � | j�� � d S r% )r� r� r� r� r! r! r" r� | s z"AsyncAdapt_psycopg_ss_cursor.closec C s | � | j�� �S r% )r� r� r� r� r! r! r" r� s z%AsyncAdapt_psycopg_ss_cursor.fetchoner c C s | � | j�|��S r% )r� r� r� r� r! r! r" r� � s z&AsyncAdapt_psycopg_ss_cursor.fetchmanyc C s | � | j�� �S r% )r� r� r� r� r! r! r" r� � s z%AsyncAdapt_psycopg_ss_cursor.fetchallc c s< | j �� }z| �|�� �V W q ty4 Y q8Y q 0 q d S r% )r� � __aiter__r� � __anext__�StopAsyncIteration)r) �iteratorr! r! r" r� � s z%AsyncAdapt_psycopg_ss_cursor.__iter__)N)r ) r r r r� r� r� r� r� r� r! r! r! r" r� w s r� c @ s� e Zd ZU ded< dZee�Zdd�dd�Zdd � Z d d d �Z d d� Z dd� Z dd� Z dd� Zedd� �Zejdd� �Zdd� Zdd� Zd d � Zd d � Zd S )!� AsyncAdapt_psycopg_connectionr � _connectionr! r� r� c C s || _ d S r% �r r� r! r! r" rk � s z&AsyncAdapt_psycopg_connection.__init__c C s t | j|�S r% )r� r r� r! r! r" r� � s z)AsyncAdapt_psycopg_connection.__getattr__Nc K s( | � | jj||fi |���}t|| j �S r% )r� r r� r� )r) r� r� r� r� r! r! r" r� � s z%AsyncAdapt_psycopg_connection.executec O s8 | j j|i |��}t|d�r(t|| j�S t|| j�S d S )Nr� )r r� �hasattrr� r� r� )r) �argsr� r� r! r! r" r� � s z$AsyncAdapt_psycopg_connection.cursorc C s | � | j�� � d S r% )r� r �commitr� r! r! r" r � s z$AsyncAdapt_psycopg_connection.commitc C s | � | j�� � d S r% )r� r r� r� r! r! r" r� � s z&AsyncAdapt_psycopg_connection.rollbackc C s | � | j�� � d S r% )r� r r� r� r! r! r" r� � s z#AsyncAdapt_psycopg_connection.closec C s | j jS r% )r r� r� r! r! r" r� � s z(AsyncAdapt_psycopg_connection.autocommitc C s | � |� d S r% ��set_autocommitr� r! r! r" r� � s c C s | � | j�|�� d S r% )r� r r r� r! r! r" r � s z,AsyncAdapt_psycopg_connection.set_autocommitc C s | � | j�|�� d S r% )r� r r� r� r! r! r" r� � s z1AsyncAdapt_psycopg_connection.set_isolation_levelc C s | � | j�|�� d S r% )r� r � set_read_onlyr� r! r! r" r � s z+AsyncAdapt_psycopg_connection.set_read_onlyc C s | � | j�|�� d S r% )r� r �set_deferrabler� r! r! r" r � s z,AsyncAdapt_psycopg_connection.set_deferrable)N)r r r �__annotations__r� � staticmethodr r� rk r� r� r� r r� r� r� r� r� r r� r r r! r! r! r" r � s$ r c @ s e Zd ZdZee�ZdS )�%AsyncAdaptFallback_psycopg_connectionr! N)r r r r� r r r� r! r! r! r" r � s r c @ s" e Zd Zdd�dd�Zdd� ZdS )�PsycopgAdaptDBAPIr� r� c C s2 || _ | j j�� D ]\}}|dkr|| j|< qd S )N�connect)rc �__dict__�items)r) rc �k�vr! r! r" rk � s zPsycopgAdaptDBAPI.__init__c O sX |� dd�}|� d| jjj�}t�|�r>tt||i |����S tt ||i |����S d S )N�async_fallbackFZasync_creator_fn) �poprc r r r �asboolr r r r )r) �argr� r Z creator_fnr! r! r" r � s � ��zPsycopgAdaptDBAPI.connectN)r r r rk r r! r! r! r" r � s r c @ s\ e Zd ZdZdZedd� �Zedd� �Zdd� Zdd � Z d d � Z d d � Z dd� Z dd� Z dS )r� Tc C s" dd l }ddlm} |t_t|�S )Nr )� ExecStatus)rc r� r r� r� r )r� rc r r! r! r" r� � s z#PGDialectAsync_psycopg.import_dbapic C s( |j �dd�}t�|�r tjS tjS d S )Nr F)r� �getr r r Z FallbackAsyncAdaptedQueuePoolZAsyncAdaptedQueuePool)r� r r r! r! r" �get_pool_class� s z%PGDialectAsync_psycopg.get_pool_classc C s& ddl m} |j}|�|�|j|��S r� )r� r� r� r� r� r� )r) r� r� r� Zadaptedr! r! r" r� � s z'PGDialectAsync_psycopg._type_info_fetchc C s |� |� |�|� d S r% )r r� r� r! r! r" r� � s z*PGDialectAsync_psycopg._do_isolation_levelc C s |� |� d S r% r r� r! r! r" r� s z%PGDialectAsync_psycopg._do_autocommitc C s |� |� d S r% )r r� r! r! r" r� s z#PGDialectAsync_psycopg.set_readonlyc C s |� |� d S r% )r r� r! r! r" r s z%PGDialectAsync_psycopg.set_deferrablec C s |j S r% r r� r! r! r" �get_driver_connection s z,PGDialectAsync_psycopg.get_driver_connectionN)r r r �is_asyncr� r� r� r r� r� r� r� r r r! r! r! r" r� � s r� )T�__doc__� __future__r � collectionsr �loggingrm �typingr r � r Z_psycopg_commonr r �baser r r r r� r r r rv r r r Zenginer Zsqlr Zutil.concurrencyr r r rc r � getLoggerr` r� r r# r$ r0 r� r2 r� r4 r5 r7 r� r8 r� r9 r� r: r� r; r� r< ZNullTyper= r� r> �Booleanr? ZAbstractSingleRangeImplr@ ZAbstractMultiRangeImplrS r] r^ r_ rb rL r� r� r r r r� r* Z dialect_asyncr! r! r! r" �<module> sx V - @4- sqlalchemy/dialects/postgresql/__pycache__/asyncpg.cpython-39.pyc 0000644 00000120465 15125143220 0021211 0 ustar 00 a ��JhG� � @ s� d Z ddlmZ ddlmZ ddlZddlZddlZddl Z ddl mZ ddl m Z ddl m Z dd lmZ dd lmZ dd lmZ dd lmZ dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddl m Z ddl m Z ddl m Z ddl m Z ddl m!Z! ddl m"Z" dd l#m$Z$ dd l#m%Z% dd l&m'Z' dd l(m)Z) dd l(m*Z* dd!l(m+Z+ G d"d#� d#e�Z,G d$d%� d%e'j-�Z.G d&d'� d'e�Z/G d(d)� d)e'j0�Z1G d*d+� d+e �Z2G d,d-� d-e �Z3G d.d/� d/e'j4�Z5G d0d1� d1e'j6�Z7G d2d3� d3e'j8�Z9G d4d5� d5e�Z:G d6d7� d7e�Z;G d8d9� d9e'j<�Z=G d:d;� d;e'j>�Z?G d<d=� d=e'j@�ZAG d>d?� d?ejB�ZCG d@dA� dAejD�ZEG dBdC� dCe'jBjF�ZGG dDdE� dEe'jBjH�ZIG dFdG� dGe'jBjJ�ZKG dHdI� dIejL�ZMG dJdK� dKe'jN�ZOG dLdM� dMeOe'jP�ZQG dNdO� dOe�ZRG dPdQ� dQe�ZSG dRdS� dSe'jT�ZUG dTdU� dUe jV�ZWG dVdW� dWe jX�ZYG dXdY� dYe�ZZG dZd[� d[e�Z[G d\d]� d]e�Z\G d^d_� d_�Z]G d`da� dae]�Z^G dbdc� dce$�Z_G ddde� dee_�Z`G dfdg� dg�ZaG dhdi� die�ZbebZcdS )ja� .. dialect:: postgresql+asyncpg :name: asyncpg :dbapi: asyncpg :connectstring: postgresql+asyncpg://user:password@host:port/dbname[?key=value&key=value...] :url: https://magicstack.github.io/asyncpg/ The asyncpg dialect is SQLAlchemy's first Python asyncio dialect. Using a special asyncio mediation layer, the asyncpg dialect is usable as the backend for the :ref:`SQLAlchemy asyncio <asyncio_toplevel>` extension package. This dialect should normally be used only with the :func:`_asyncio.create_async_engine` engine creation function:: from sqlalchemy.ext.asyncio import create_async_engine engine = create_async_engine( "postgresql+asyncpg://user:pass@hostname/dbname" ) .. versionadded:: 1.4 .. note:: By default asyncpg does not decode the ``json`` and ``jsonb`` types and returns them as strings. SQLAlchemy sets default type decoder for ``json`` and ``jsonb`` types using the python builtin ``json.loads`` function. The json implementation used can be changed by setting the attribute ``json_deserializer`` when creating the engine with :func:`create_engine` or :func:`create_async_engine`. .. _asyncpg_multihost: Multihost Connections -------------------------- The asyncpg dialect features support for multiple fallback hosts in the same way as that of the psycopg2 and psycopg dialects. The syntax is the same, using ``host=<host>:<port>`` combinations as additional query string arguments; however, there is no default port, so all hosts must have a complete port number present, otherwise an exception is raised:: engine = create_async_engine( "postgresql+asyncpg://user:password@/dbname?host=HostA:5432&host=HostB:5432&host=HostC:5432" ) For complete background on this syntax, see :ref:`psycopg2_multi_host`. .. versionadded:: 2.0.18 .. seealso:: :ref:`psycopg2_multi_host` .. _asyncpg_prepared_statement_cache: Prepared Statement Cache -------------------------- The asyncpg SQLAlchemy dialect makes use of ``asyncpg.connection.prepare()`` for all statements. The prepared statement objects are cached after construction which appears to grant a 10% or more performance improvement for statement invocation. The cache is on a per-DBAPI connection basis, which means that the primary storage for prepared statements is within DBAPI connections pooled within the connection pool. The size of this cache defaults to 100 statements per DBAPI connection and may be adjusted using the ``prepared_statement_cache_size`` DBAPI argument (note that while this argument is implemented by SQLAlchemy, it is part of the DBAPI emulation portion of the asyncpg dialect, therefore is handled as a DBAPI argument, not a dialect argument):: engine = create_async_engine( "postgresql+asyncpg://user:pass@hostname/dbname?prepared_statement_cache_size=500" ) To disable the prepared statement cache, use a value of zero:: engine = create_async_engine( "postgresql+asyncpg://user:pass@hostname/dbname?prepared_statement_cache_size=0" ) .. versionadded:: 1.4.0b2 Added ``prepared_statement_cache_size`` for asyncpg. .. warning:: The ``asyncpg`` database driver necessarily uses caches for PostgreSQL type OIDs, which become stale when custom PostgreSQL datatypes such as ``ENUM`` objects are changed via DDL operations. Additionally, prepared statements themselves which are optionally cached by SQLAlchemy's driver as described above may also become "stale" when DDL has been emitted to the PostgreSQL database which modifies the tables or other objects involved in a particular prepared statement. The SQLAlchemy asyncpg dialect will invalidate these caches within its local process when statements that represent DDL are emitted on a local connection, but this is only controllable within a single Python process / database engine. If DDL changes are made from other database engines and/or processes, a running application may encounter asyncpg exceptions ``InvalidCachedStatementError`` and/or ``InternalServerError("cache lookup failed for type <oid>")`` if it refers to pooled database connections which operated upon the previous structures. The SQLAlchemy asyncpg dialect will recover from these error cases when the driver raises these exceptions by clearing its internal caches as well as those of the asyncpg driver in response to them, but cannot prevent them from being raised in the first place if the cached prepared statement or asyncpg type caches have gone stale, nor can it retry the statement as the PostgreSQL transaction is invalidated when these errors occur. .. _asyncpg_prepared_statement_name: Prepared Statement Name with PGBouncer -------------------------------------- By default, asyncpg enumerates prepared statements in numeric order, which can lead to errors if a name has already been taken for another prepared statement. This issue can arise if your application uses database proxies such as PgBouncer to handle connections. One possible workaround is to use dynamic prepared statement names, which asyncpg now supports through an optional ``name`` value for the statement name. This allows you to generate your own unique names that won't conflict with existing ones. To achieve this, you can provide a function that will be called every time a prepared statement is prepared:: from uuid import uuid4 engine = create_async_engine( "postgresql+asyncpg://user:pass@somepgbouncer/dbname", poolclass=NullPool, connect_args={ "prepared_statement_name_func": lambda: f"__asyncpg_{uuid4()}__", }, ) .. seealso:: https://github.com/MagicStack/asyncpg/issues/837 https://github.com/sqlalchemy/sqlalchemy/issues/6467 .. warning:: When using PGBouncer, to prevent a buildup of useless prepared statements in your application, it's important to use the :class:`.NullPool` pool class, and to configure PgBouncer to use `DISCARD <https://www.postgresql.org/docs/current/sql-discard.html>`_ when returning connections. The DISCARD command is used to release resources held by the db connection, including prepared statements. Without proper setup, prepared statements can accumulate quickly and cause performance issues. Disabling the PostgreSQL JIT to improve ENUM datatype handling --------------------------------------------------------------- Asyncpg has an `issue <https://github.com/MagicStack/asyncpg/issues/727>`_ when using PostgreSQL ENUM datatypes, where upon the creation of new database connections, an expensive query may be emitted in order to retrieve metadata regarding custom types which has been shown to negatively affect performance. To mitigate this issue, the PostgreSQL "jit" setting may be disabled from the client using this setting passed to :func:`_asyncio.create_async_engine`:: engine = create_async_engine( "postgresql+asyncpg://user:password@localhost/tmp", connect_args={"server_settings": {"jit": "off"}}, ) .. seealso:: https://github.com/MagicStack/asyncpg/issues/727 � )� annotations)�dequeN� )�json)�ranges)�ARRAY)�_DECIMAL_TYPES)� _FLOAT_TYPES)� _INT_TYPES)�ENUM)�INTERVAL)�OID)� PGCompiler)� PGDialect)�PGExecutionContext)�PGIdentifierPreparer)�REGCLASS)� REGCONFIG)�BIT)�BYTEA)�CITEXT� )�exc)�pool)�util)�AdaptedConnection)� processors)�sqltypes)�asyncio)�await_fallback)� await_onlyc @ s e Zd ZdZdS )� AsyncpgARRAYTN��__name__� __module__� __qualname__�render_bind_cast� r' r' �[/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/postgresql/asyncpg.pyr! � s r! c @ s e Zd ZdZdS )� AsyncpgStringTNr" r' r' r' r( r) � s r) c @ s e Zd ZdZdS )�AsyncpgREGCONFIGTNr" r' r' r' r( r* � s r* c @ s e Zd ZdZdS )� AsyncpgTimeTNr" r' r' r' r( r+ � s r+ c @ s e Zd ZdZdS )� AsyncpgBitTNr" r' r' r' r( r, � s r, c @ s e Zd ZdZdS )� AsyncpgByteATNr" r' r' r' r( r- � s r- c @ s e Zd ZdZdS )� AsyncpgDateTNr" r' r' r' r( r. � s r. c @ s e Zd ZdZdS )�AsyncpgDateTimeTNr" r' r' r' r( r/ � s r/ c @ s e Zd ZdZdS )�AsyncpgBooleanTNr" r' r' r' r( r0 � s r0 c @ s e Zd ZdZedd� �ZdS )�AsyncPgIntervalTc K s t |jd�S )N)Z precision)r1 Zsecond_precision)�cls�interval�kwr' r' r( �adapt_emulated_to_native� s z(AsyncPgInterval.adapt_emulated_to_nativeN)r# r$ r% r& � classmethodr5 r' r' r' r( r1 � s r1 c @ s e Zd ZdZdS )� AsyncPgEnumTNr" r' r' r' r( r7 s r7 c @ s e Zd ZdZdS )�AsyncpgIntegerTNr" r' r' r' r( r8 s r8 c @ s e Zd ZdZdS )�AsyncpgSmallIntegerTNr" r' r' r' r( r9 s r9 c @ s e Zd ZdZdS )�AsyncpgBigIntegerTNr" r' r' r' r( r: s r: c @ s e Zd Zdd� ZdS )� AsyncpgJSONc C s d S �Nr' ��self�dialect�coltyper' r' r( �result_processor s z AsyncpgJSON.result_processorN�r# r$ r% rA r' r' r' r( r; s r; c @ s e Zd Zdd� ZdS )� AsyncpgJSONBc C s d S r< r' r= r' r' r( rA s z AsyncpgJSONB.result_processorNrB r' r' r' r( rC s rC c @ s e Zd ZdS )�AsyncpgJSONIndexTypeN�r# r$ r% r' r' r' r( rD s rD c @ s e Zd ZdZdZdS )�AsyncpgJSONIntIndexTypeZjson_int_indexTN�r# r$ r% Z__visit_name__r& r' r' r' r( rF " s rF c @ s e Zd ZdZdZdS )�AsyncpgJSONStrIndexTypeZjson_str_indexTNrG r' r' r' r( rH ( s rH c @ s e Zd Zdd� ZdS )�AsyncpgJSONPathTypec C s dd� }|S )Nc S s, t | t�r| S | r$dd� | D �}|S g S d S )Nc S s g | ] }t |��qS r' )�str��.0�elemr' r' r( � <listcomp>6 � zGAsyncpgJSONPathType.bind_processor.<locals>.process.<locals>.<listcomp>�� isinstancerJ )�value�tokensr' r' r( �process0 s z3AsyncpgJSONPathType.bind_processor.<locals>.processr' )r> r? rT r' r' r( �bind_processor/ s z"AsyncpgJSONPathType.bind_processorN)r# r$ r% rU r' r' r' r( rI . s rI c @ s e Zd ZdZdd� Zdd� ZdS )�AsyncpgNumericTc C s d S r< r' )r> r? r' r' r( rU A s z AsyncpgNumeric.bind_processorc C sv | j rB|tv r t�tj| j�S |tv s.|tv r2d S t � d| ��n0|tv rNd S |tv s^|tv rdtj S t � d| ��d S )NzUnknown PG numeric type: %d) Z asdecimalr r Z to_decimal_processor_factory�decimal�DecimalZ _effective_decimal_return_scaler r r ZInvalidRequestErrorZto_floatr= r' r' r( rA D s" ���z AsyncpgNumeric.result_processorN)r# r$ r% r& rU rA r' r' r' r( rV > s rV c @ s e Zd ZdZdZdS )� AsyncpgFloat�floatTNrG r' r' r' r( rY ] s rY c @ s e Zd ZdZdS )�AsyncpgREGCLASSTNr" r' r' r' r( r[ b s r[ c @ s e Zd ZdZdS )� AsyncpgOIDTNr" r' r' r' r( r\ f s r\ c @ s e Zd ZdZdS )� AsyncpgCHARTNr" r' r' r' r( r] j s r] c @ s e Zd Zdd� Zdd� ZdS )� _AsyncpgRangec s |j jj� � fdd�}|S )Nc s< t | tj�r8� | j| j| jd dk| jd dk| jd�} | S �Nr �[r �])� lower_inc� upper_inc�empty�rQ r �Range�lower�upper�boundsrd �rR �� asyncpg_Ranger' r( �to_ranger s �z._AsyncpgRange.bind_processor.<locals>.to_range)�dbapi�asyncpgrf �r> r? rm r' rk r( rU o s z _AsyncpgRange.bind_processorc C s dd� }|S )Nc S sL | d urH| j }tj| j| j|s$| jr(dnd� |s:| jr:dnd� �|d�} | S �Nr` �(ra �))ri rd �Zisemptyr rf rg rh rb rc )rR rd r' r' r( rm � s ��z0_AsyncpgRange.result_processor.<locals>.to_ranger' )r> r? r@ rm r' r' r( rA s z _AsyncpgRange.result_processorN�r# r$ r% rU rA r' r' r' r( r^ n s r^ c @ s e Zd Zdd� Zdd� ZdS )�_AsyncpgMultiRangec s$ |j jj�td �� � �fdd�}|S )Nc s0 t | t�f�r| S �fdd�� � fdd�| D �S )Nc s< t | tj�r8� | j| j| jd dk| jd dk| jd�} | S r_ re rj rk r' r( rm � s �zE_AsyncpgMultiRange.bind_processor.<locals>.to_range.<locals>.to_rangec s g | ] }� |��qS r' r' )rL �element�rm r' r( rN � rO zG_AsyncpgMultiRange.bind_processor.<locals>.to_range.<locals>.<listcomp>rP rj �ZNoneTyperl rx r( rm � s z3_AsyncpgMultiRange.bind_processor.<locals>.to_range)rn ro rf �typerp r' ry r( rU � s z!_AsyncpgMultiRange.bind_processorc C s dd� }|S )Nc s, dd� � | d ur(t �� fdd�| D ��} | S )Nc S sL | d urH| j }tj| j| j|s$| jr(dnd� |s:| jr:dnd� �|d�} | S rq rt )Zrvaluerd r' r' r( rm � s ��zM_AsyncpgMultiRange.result_processor.<locals>.to_range_array.<locals>.to_rangec 3 s | ]}� |�V qd S r< r' rK rx r' r( � <genexpr>� rO zN_AsyncpgMultiRange.result_processor.<locals>.to_range_array.<locals>.<genexpr>)r Z MultiRangerj r' rx r( �to_range_array� s z;_AsyncpgMultiRange.result_processor.<locals>.to_range_arrayr' )r> r? r@ r| r' r' r( rA � s z#_AsyncpgMultiRange.result_processorNru r' r' r' r( rv � s rv c @ s$ e Zd Zdd� Zdd� Zdd� ZdS )�PGExecutionContext_asyncpgc C s( t || jjj| jjjf�r$| j�� d S r< )rQ r? rn �InvalidCachedStatementError�InternalServerError�_invalidate_schema_cache)r> �er' r' r( �handle_dbapi_exception� s ��z1PGExecutionContext_asyncpg.handle_dbapi_exceptionc C s* | j r| j�� | jj| j_| js&d S d S r< )Zisddlr? r� � _invalidate_schema_cache_asof�cursorZcompiled�r> r' r' r( �pre_exec� s �z#PGExecutionContext_asyncpg.pre_execc C s | j jdd�S )NT)� server_side)Z_dbapi_connectionr� r� r' r' r( �create_server_side_cursor� s z4PGExecutionContext_asyncpg.create_server_side_cursorN)r# r$ r% r� r� r� r' r' r' r( r} � s r} c @ s e Zd ZdS )�PGCompiler_asyncpgNrE r' r' r' r( r� � s r� c @ s e Zd ZdS )� PGIdentifierPreparer_asyncpgNrE r' r' r' r( r� � s r� c @ sx e Zd ZdZdZdd� Zdd� Zdd� Zd d � Zd d � Z d dd�Z dd� Z dd� Z dd� Z dd� Zd dd�Zdd� Zd S ) �AsyncAdapt_asyncpg_cursor)�_adapt_connection� _connection�_rows� description� arraysize�rowcount�_cursorr� Fc C s8 || _ |j| _t� | _d | _d | _d| _d| _d| _d S )Nr ���r ) r� r� r r� r� r� r� r� r� �r> �adapt_connectionr' r' r( �__init__� s z"AsyncAdapt_asyncpg_cursor.__init__c C s | j �� d S r< )r� �clearr� r' r' r( �close� s z AsyncAdapt_asyncpg_cursor.closec C s | j �|� d S r< )r� �_handle_exception�r> �errorr' r' r( r� � s z+AsyncAdapt_asyncpg_cursor._handle_exceptionc � s> | j }|j4 I d H �� |js,|�� I d H |d u r8d}z�|�|| j�I d H \}}|rhdd� |D �| _nd | _| jr�|j|� I d H | _ d| _ nJt |j |� I d H �| _ |�� }t�d|p�d�}|r�t|�d��| _ nd| _ W n0 t�y } z| �|� W Y d }~n d }~0 0 W d �I d H �q:1 I d H �s00 Y d S )Nr' c S s$ g | ] }|j |jjd d d d d f�qS r< )�namerz �oid)rL �attrr' r' r( rN s ��zBAsyncAdapt_asyncpg_cursor._prepare_and_execute.<locals>.<listcomp>r� z)(?:SELECT|UPDATE|DELETE|INSERT \d+) (\d+)� r )r� �_execute_mutex�_started�_start_transaction�_preparer� r� r� r� r� r� r �fetchr� Z get_statusmsg�re�match�int�group� Exceptionr� ) r> � operation� parametersr� � prepared_stmt� attributes�status�regr� r' r' r( �_prepare_and_execute� s: � � � z.AsyncAdapt_asyncpg_cursor._prepare_and_executec � s� | j }d | _|j4 I d H �� |�| j�I d H |jsB|�� I d H z*| j�||�I d H W W d �I d H S t y� } z| � |� W Y d }~n d }~0 0 W d �I d H q�1 I d H s�0 Y d S r< ) r� r� r� � _check_type_cache_invalidationr� r� r� r� � executemanyr� r� )r> r� �seq_of_parametersr� r� r' r' r( � _executemany0 s � � z&AsyncAdapt_asyncpg_cursor._executemanyNc C s | j �| �||�� d S r< )r� �await_r� )r> r� r� r' r' r( �executeC s �z!AsyncAdapt_asyncpg_cursor.executec C s | j �| �||��S r< )r� r� r� �r> r� r� r' r' r( r� H s �z%AsyncAdapt_asyncpg_cursor.executemanyc G s t � �d S r< ��NotImplementedError)r> Z inputsizesr' r' r( � setinputsizesM s z'AsyncAdapt_asyncpg_cursor.setinputsizesc c s | j r| j �� V q d S r< �r� �popleftr� r' r' r( �__iter__P s z"AsyncAdapt_asyncpg_cursor.__iter__c C s | j r| j �� S d S d S r< r� r� r' r' r( �fetchoneT s z"AsyncAdapt_asyncpg_cursor.fetchonec s4 |d u r| j }| j� � fdd�tt|t� ���D �S )Nc s g | ] }� � � �qS r' �r� �rL �_��rrr' r( rN _ rO z7AsyncAdapt_asyncpg_cursor.fetchmany.<locals>.<listcomp>)r� r� �range�min�len)r> �sizer' r� r( � fetchmanyZ s z#AsyncAdapt_asyncpg_cursor.fetchmanyc C s t | j�}| j�� |S r< )�listr� r� )r> �retvalr' r' r( �fetchalla s z"AsyncAdapt_asyncpg_cursor.fetchall)N)N)r# r$ r% � __slots__r� r� r� r� r� r� r� r� r� r� r� r� r� r' r' r' r( r� � s 2 r� c sn e Zd ZdZdZ� fdd�Zdd� Zdd� Zd d � Zd d � Z d d� Z ddd�Z dd� Z dd� Z dd� Z� ZS )� AsyncAdapt_asyncpg_ss_cursorT)� _rowbufferc s t � �|� t� | _d S r< )�superr� r r� r� �� __class__r' r( r� k s z%AsyncAdapt_asyncpg_ss_cursor.__init__c C s d | _ | j�� d S r< )r� r� r� r� r' r' r( r� o s z"AsyncAdapt_asyncpg_ss_cursor.closec C s2 | j d usJ �| j�| j �d��}| j�|� d S )N�2 )r� r� r� r� r� �extend)r> Znew_rowsr' r' r( � _buffer_rowss s z)AsyncAdapt_asyncpg_ss_cursor._buffer_rowsc C s | S r< r' r� r' r' r( � __aiter__x s z&AsyncAdapt_asyncpg_ss_cursor.__aiter__c C s* | j r| j �� V q | �� | j s q&q d S r< )r� r� r� r� r' r' r( � __anext__{ s z&AsyncAdapt_asyncpg_ss_cursor.__anext__c C s" | j s| �� | j sd S | j �� S r< )r� r� r� r� r' r' r( r� � s z%AsyncAdapt_asyncpg_ss_cursor.fetchoneNc s� |d u r| � � S | js | �� | jd us,J �| j� t� �}||kr`� �| j�| j�|| ��� � fdd�t t |t� ���D �S )Nc s g | ] }� � � �qS r' r� r� ��rbr' r( rN � rO z:AsyncAdapt_asyncpg_ss_cursor.fetchmany.<locals>.<listcomp>) r� r� r� r� r� r� r� r� r� r� r� )r> r� Zlbr' r� r( r� � s �z&AsyncAdapt_asyncpg_ss_cursor.fetchmanyc C s. t | j�}|�| j�| �� �� | j�� |S r< )r� r� r� r� r� �_allr� )r> �retr' r' r( r� � s z%AsyncAdapt_asyncpg_ss_cursor.fetchallc � s0 g }| j �d�I d H }|r,|�|� qqq,q|S )Ni� )r� r� r� )r> �rows�batchr' r' r( r� � s z!AsyncAdapt_asyncpg_ss_cursor._allc C s t d��d S )Nz2server side cursor doesn't support executemany yetr� r� r' r' r( r� � s �z(AsyncAdapt_asyncpg_ss_cursor.executemany)N)r# r$ r% r� r� r� r� r� r� r� r� r� r� r� r� � __classcell__r' r' r� r( r� g s r� c @ s� e Zd ZdZee�Zd(dd�Zdd� Zdd � Z d d � Z e d d � �Z e j dd � �Z dd� Zdd� Zdd� Zdd� Zd)dd�Zdd� Zd d � Zd d � Zd d!� Zd"d#� Zd$d%� Zed&d'� �ZdS )*� AsyncAdapt_asyncpg_connection) rn �isolation_level�_isolation_setting�readonly� deferrable� _transactionr� �_prepared_statement_cache� _prepared_statement_name_funcr� r� �d Nc C st || _ || _d | _| _d| _d| _d | _d| _t�� | _ t � � | _ |rVt �|�| _nd | _|rh|| _n| j| _d S �NF)rn r� r� r� r� r� r� r� �timer� r �Lockr� r ZLRUCacher� r� �_default_name_func)r> rn � connection� prepared_statement_cache_size� prepared_statement_name_funcr' r' r( r� � s" �z&AsyncAdapt_asyncpg_connection.__init__c � s$ || j kr | j�� I d H || _ d S r< )r� r� Zreload_schema_state)r> �invalidate_timestampr' r' r( r� � s z<AsyncAdapt_asyncpg_connection._check_type_cache_invalidationc � s� | � |�I d H | j}|d u rH| jj|| �� d�I d H }|�� }||fS ||v rn|| \}}}||krn||fS | jj|| �� d�I d H }|�� }||t�� f||< ||fS )N)r� )r� r� r� �preparer� Zget_attributesr� )r> r� r� �cacher� r� Zcached_timestampr' r' r( r� � s$ � � z&AsyncAdapt_asyncpg_connection._preparec C s� | j �� rd | _d| _t|tj�sz| jj}t |�j D ]>}||v r4|| dt |�|f �}t |dd � |_ |_ ||�q4|�n|�d S )NFz%s: %s�sqlstate)r� � is_closedr� r� rQ �AsyncAdapt_asyncpg_dbapi�Errorrn �_asyncpg_error_translaterz �__mro__�getattrZpgcoder� )r> r� Zexception_mappingZsuper_Ztranslated_errorr' r' r( r� s � � z/AsyncAdapt_asyncpg_connection._handle_exceptionc C s | j dkS �N� autocommit)r� r� r' r' r( r� s z(AsyncAdapt_asyncpg_connection.autocommitc C s |r d| _ n| j| _ d S r� )r� r� �r> rR r' r' r( r� " s c C sF z| � | �� �}W n. ty@ } z| �|� W Y d }~n d }~0 0 d S r< )r� � _async_pingr� r� )r> r� r� r' r' r( �ping) s z"AsyncAdapt_asyncpg_connection.pingc � sz | j d u rd| jdkrd| j�� }|�� I d H z$| j�d�I d H W |�� I d H qv|�� I d H 0 n| j�d�I d H d S )Nr� �;)r� r� r� � transaction�startZfetchrow�rollback)r> �trr' r' r( r� / s "z)AsyncAdapt_asyncpg_connection._async_pingc C s | j r| �� | | _| _d S r< )r� r r� r� )r> �levelr' r' r( �set_isolation_level< s z1AsyncAdapt_asyncpg_connection.set_isolation_levelc � sv | j dkrd S z.| jj| j | j| jd�| _| j�� I d H W n. tyj } z| �|� W Y d }~nd }~0 0 d| _ d S )Nr� )Z isolationr� r� T) r� r� r� r� r� r� r� r� r� r� r� r' r' r( r� A s � z0AsyncAdapt_asyncpg_connection._start_transactionFc C s |r t | �S t| �S d S r< )r� r� )r> r� r' r' r( r� Q s z$AsyncAdapt_asyncpg_connection.cursorc � s4 z | j �� I d H W d | _ d| _nd | _ d| _0 d S r� )r� r r� r� r' r' r( �_rollback_and_discardW s �z3AsyncAdapt_asyncpg_connection._rollback_and_discardc � s4 z | j �� I d H W d | _ d| _nd | _ d| _0 d S r� )r� �commitr� r� r' r' r( �_commit_and_discard` s �z1AsyncAdapt_asyncpg_connection._commit_and_discardc C sX | j rTz | �| �� � d | _d| _ W n. tyR } z| �|� W Y d }~n d }~0 0 d S r� )r� r� r r� r� r� r� r' r' r( r i s z&AsyncAdapt_asyncpg_connection.rollbackc C sX | j rTz | �| �� � d | _d| _ W n. tyR } z| �|� W Y d }~n d }~0 0 d S r� )r� r� r r� r� r� r� r' r' r( r t s z$AsyncAdapt_asyncpg_connection.commitc C s | � � | �| j�� � d S r< )r r� r� r� r� r' r' r( r� s z#AsyncAdapt_asyncpg_connection.closec C sn t j�� rZz | �t�| jjdd��� W qd tjtj t | j j j fyV | j�� Y qd0 n | j�� d| _d S )N� )�timeoutF)r Z concurrencyZ in_greenletr� r �shieldr� r� � TimeoutError�CancelledError�OSErrorrn ro � PostgresError� terminater� r� r' r' r( r � s � z'AsyncAdapt_asyncpg_connection.terminatec C s d S r< r' r' r' r' r( r� � s z0AsyncAdapt_asyncpg_connection._default_name_func)r� N)F)r# r$ r% r� � staticmethodr r� r� r� r� r� �propertyr� �setterr� r� r r� r� r r r r r� r r� r' r' r' r( r� � s2 � r� c @ s e Zd ZdZee�ZdS )�%AsyncAdaptFallback_asyncpg_connectionr' N)r# r$ r% r� r r r� r' r' r' r( r � s r c @ s e Zd Zdd� Zdd� ZG dd� de�ZG dd� de�ZG d d � d e�ZG d d � d e�Z G d d� de �Z G dd� de �Z G dd� de �Z G dd� de �Z G dd� de �ZG dd� de �ZG dd� de �ZG dd � d e�Ze�d �Ze�d �Ze�d �Zejd d!� �Zd"d#� Zd$S )%r� c C s || _ d| _d S )N�numeric_dollar)ro Z paramstyle�r> ro r' r' r( r� � s z!AsyncAdapt_asyncpg_dbapi.__init__c O s~ |� dd�}|� d| jj�}|� dd�}|� dd �}t�|�r\t| t||i |���||d�S t| t||i |���||d�S d S )N�async_fallbackFZasync_creator_fnr� r� r� )r� r� ) �popro �connectr �asboolr r r� r )r> �argr4 r Z creator_fnr� r� r' r' r( r � s* �� ��z AsyncAdapt_asyncpg_dbapi.connectc @ s e Zd ZdS )z AsyncAdapt_asyncpg_dbapi.ErrorNrE r' r' r' r( r� � s r� c @ s e Zd ZdS )z AsyncAdapt_asyncpg_dbapi.WarningNrE r' r' r' r( �Warning� s r c @ s e Zd ZdS )z'AsyncAdapt_asyncpg_dbapi.InterfaceErrorNrE r' r' r' r( �InterfaceError� s r c @ s e Zd ZdS )z&AsyncAdapt_asyncpg_dbapi.DatabaseErrorNrE r' r' r' r( � DatabaseError� s r c @ s e Zd ZdS )z&AsyncAdapt_asyncpg_dbapi.InternalErrorNrE r' r' r' r( � InternalError� s r c @ s e Zd ZdS )z)AsyncAdapt_asyncpg_dbapi.OperationalErrorNrE r' r' r' r( �OperationalError� s r c @ s e Zd ZdS )z)AsyncAdapt_asyncpg_dbapi.ProgrammingErrorNrE r' r' r' r( �ProgrammingError� s r c @ s e Zd ZdS )z'AsyncAdapt_asyncpg_dbapi.IntegrityErrorNrE r' r' r' r( �IntegrityError� s r c @ s e Zd ZdS )z"AsyncAdapt_asyncpg_dbapi.DataErrorNrE r' r' r' r( � DataError� s r! c @ s e Zd ZdS )z*AsyncAdapt_asyncpg_dbapi.NotSupportedErrorNrE r' r' r' r( �NotSupportedError� s r" c @ s e Zd ZdS )z,AsyncAdapt_asyncpg_dbapi.InternalServerErrorNrE r' r' r' r( r � s r c s e Zd Z� fdd�Z� ZS )z4AsyncAdapt_asyncpg_dbapi.InvalidCachedStatementErrorc s t � �|d � d S )Nzc (SQLAlchemy asyncpg dialect will now invalidate all prepared caches in response to this exception))r� r� )r> �messager� r' r( r� � s �z=AsyncAdapt_asyncpg_dbapi.InvalidCachedStatementError.__init__)r# r$ r% r� r� r' r' r� r( r~ � s r~ �STRING�NUMBER�DATETIMEc C sH dd l }|jj| j|jj| j|jj| j|jj| j|jj | j |jj | j iS )Nr ) ro � exceptionsZ!IntegrityConstraintViolationErrorr r r� ZSyntaxOrAccessErrorr r r~ r r r' r' r( r� � s �z1AsyncAdapt_asyncpg_dbapi._asyncpg_error_translatec C s |S r< r' r� r' r' r( �Binary s z AsyncAdapt_asyncpg_dbapi.BinaryN)r# r$ r% r� r r� r� r r r r r r r r! r" r r~ r �symbolr$ r% r& �memoized_propertyr� r( r' r' r' r( r� � s( r� c = s� e Zd ZdZdZdZdZdZdZdZ e Z e Z eZe�ejejeejeeeeee e ej e ej e!ej"e#ej$e%e&e%ej'e(ej)e*ej+e,ej-e.ej/e0ej1e2ej3e4ej5e6e7j8e9ej3j:e;ej3j<e=ej3j>e?ej3j@eAejBeCeDeEeFeGejHeIeJjKeLeJjMeNi �ZdZOdZPdd� ZQejRdd � �ZSeTd d � �ZUejRd d � �ZVdd� ZWdd� ZXdd� ZYdd� ZZdd� Z[dd� Z\dd�d d �Z]d d � Z^d d!� Z_eTd"d#� �Z`d$d%� Zad&d'� Zbd(d)� Zcd*d+� Zd� fd,d-�Zed.d/� Zf� ZgS )0�PGDialect_asyncpgro Tr Fr c C s t � � | _d S r< )r� r� r� r' r' r( r� 9 s z*PGDialect_asyncpg._invalidate_schema_cachec C s8 | j r0t| j d�r0tdd� t�d| j j�D ��S dS d S )N� __version__c S s g | ] }t |��qS r' )r� )rL �xr' r' r( rN @ s �z4PGDialect_asyncpg._dbapi_version.<locals>.<listcomp>z(\d+)(?:[-\.]?|$))�c r. r. )rn �hasattr�tupler� �findallr, r� r' r' r( �_dbapi_version< s ��� z PGDialect_asyncpg._dbapi_versionc C s t td��S )Nro )r� � __import__)r2 r' r' r( � import_dbapiJ s z PGDialect_asyncpg.import_dbapic C s ddddd�S )Nr� Zread_committedZrepeatable_readZ serializable)Z AUTOCOMMITzREAD COMMITTEDzREPEATABLE READZ SERIALIZABLEr' r� r' r' r( �_isolation_lookupN s �z#PGDialect_asyncpg._isolation_lookupc C s t | j�S r< )r� r5 �r> �dbapi_connectionr' r' r( �get_isolation_level_valuesW s z,PGDialect_asyncpg.get_isolation_level_valuesc C s |� | j| � d S r< )r r5 )r> r7 r r' r' r( r Z s z%PGDialect_asyncpg.set_isolation_levelc C s ||_ d S r< �r� �r> r� rR r' r' r( � set_readonly] s z PGDialect_asyncpg.set_readonlyc C s |j S r< r9 �r> r� r' r' r( � get_readonly` s z PGDialect_asyncpg.get_readonlyc C s ||_ d S r< �r� r: r' r' r( �set_deferrablec s z PGDialect_asyncpg.set_deferrablec C s |j S r< r> r< r' r' r( �get_deferrablef s z PGDialect_asyncpg.get_deferrable�None)�returnc C s |� � d S r< )r r6 r' r' r( � do_terminatei s z PGDialect_asyncpg.do_terminatec C s� |j dd�}| �|�\}}|�|j� |r�|s2J �t|�dkrd|d |d< |d d ur�|d |d< q�t|�sxt�d��q�t|�s�t�d��q�t|�|d< t|�|d< nt � |dt � t � |d t � g |fS ) N�user)�usernamer r �host�portzBAll hosts are required to be present for asyncpg multiple host URLzBAll ports are required to be present for asyncpg multiple host URLr� ) Ztranslate_connect_argsZ_split_multihost_from_url�update�queryr� �allr � ArgumentErrorr� r Zcoerce_kw_typer� )r> �url�optsZ multihostsZ multiportsr' r' r( �create_connect_argsl s, �� z%PGDialect_asyncpg.create_connect_argsc C s |� � dS )NT)r� r6 r' r' r( �do_ping� s zPGDialect_asyncpg.do_pingc C s( |j �dd�}t�|�r tjS tjS d S )Nr F)rI �getr r r Z FallbackAsyncAdaptedQueuePoolZAsyncAdaptedQueuePool)r2 rL r r' r' r( �get_pool_class� s z PGDialect_asyncpg.get_pool_classc C s, |r|j �� S t|| jj�o&dt|�v S d S )Nzconnection is closed)r� r� rQ rn r rJ )r> r� r� r� r' r' r( � is_disconnect� s � �z PGDialect_asyncpg.is_disconnectc � s> |j }| jptj� � fdd�}|jdtj|ddd�I dH dS )z�set up JSON codec for asyncpg. This occurs for all new connections and can be overridden by third party dialects. .. versionadded:: 1.4.27 c s � | � � �S r< ��decode�Z bin_value�Z deserializerr' r( � _json_decoder� s zAPGDialect_asyncpg.setup_asyncpg_json_codec.<locals>._json_decoderr � pg_catalog�binary��encoder�decoderZschema�formatN)r� �_json_deserializer�_py_json�loads�set_type_codecrJ �encode)r> �conn�asyncpg_connectionrW r' rV r( �setup_asyncpg_json_codec� s �z*PGDialect_asyncpg.setup_asyncpg_json_codecc � sP |j }| jptj� dd� }| jp$tj� � fdd�}|jd||ddd�I d H d S ) z�set up JSONB codec for asyncpg. This occurs for all new connections and can be overridden by third party dialects. .. versionadded:: 1.4.27 c S s d| � � S )N� )rb )Z str_valuer' r' r( �_jsonb_encoder� s zCPGDialect_asyncpg.setup_asyncpg_jsonb_codec.<locals>._jsonb_encoderc s � | dd � � � �S )Nr rS rU rV r' r( �_jsonb_decoder� s zCPGDialect_asyncpg.setup_asyncpg_jsonb_codec.<locals>._jsonb_decoderZjsonbrX rY rZ N)r� r^ r_ r` ra )r> rc rd rg rh r' rV r( �setup_asyncpg_jsonb_codec� s �z+PGDialect_asyncpg.setup_asyncpg_jsonb_codecc � sN |j }|jddd� dd� ddd�I d H |jdd d� d d� ddd�I d H d S ) NZinetc S s | S r< r' ��sr' r' r( �<lambda>� rO z@PGDialect_asyncpg._disable_asyncpg_inet_codecs.<locals>.<lambda>c S s | S r< r' rj r' r' r( rl � rO rX �textrZ Zcidrc S s | S r< r' rj r' r' r( rl � rO c S s | S r< r' rj r' r' r( rl � rO )r� ra )r> rc rd r' r' r( � _disable_asyncpg_inet_codecs� s � �z.PGDialect_asyncpg._disable_asyncpg_inet_codecsc s t � �� �� �fdd�}|S )z�on_connect for asyncpg A major component of this for asyncpg is to set up type decoders at the asyncpg level. See https://github.com/MagicStack/asyncpg/issues/623 for notes on JSON/JSONB implementation. c sN | � � �| �� | � � �| �� � jdu r:| � � �| �� �d urJ�| � d S r� )r� re ri Z_native_inet_typesrn )rc �r> Z super_connectr' r( r � s z-PGDialect_asyncpg.on_connect.<locals>.connect)r� � on_connect)r> r r� ro r( rp � s z PGDialect_asyncpg.on_connectc C s |j S r< )r� r< r' r' r( �get_driver_connection s z'PGDialect_asyncpg.get_driver_connection)hr# r$ r% ZdriverZsupports_statement_cacheZ supports_server_side_cursorsr& Z has_terminateZdefault_paramstyleZ supports_sane_multi_rowcountr} Zexecution_ctx_clsr� Zstatement_compilerr� �preparerr Z update_copyr Zcolspecsr �Stringr) r r! r r, r r r* �Timer+ �Dater. �DateTimer/ ZIntervalr1 r �Booleanr0 �Integerr8 � SmallIntegerr9 � BigIntegerr: �NumericrV �FloatrY �JSONr; Z LargeBinaryr- r �JSONBrC � JSONPathTyperI � JSONIndexTyperD �JSONIntIndexTyperF �JSONStrIndexTyperH �Enumr7 r r\ r r[ �CHARr] r ZAbstractSingleRanger^ ZAbstractMultiRangerv �is_asyncr� r� r* r2 r6 r4 r5 r8 r r; r= r? r@ rC rN rO rQ rR re ri rn rp rq r� r' r' r� r( r+ s� ��" ! r+ )d�__doc__� __future__r � collectionsr rW r r_ r� r� r� r �arrayr ZPGARRAY�baser r r r r r r r r r r r �typesr r r r r r Zenginer r Zsqlr Zutil.concurrencyr r r r! rs r) r* rt r+ r, r- ru r. rv r/ rw r0 r1 r7 rx r8 ry r9 rz r: r} r; r~ rC r� rD r� rF r� rH r rI r{ rV r| rY r[ r\ r� r] ZAbstractSingleRangeImplr^ ZAbstractMultiRangeImplrv r} r� r� r� r� r� r r� r+ r? r' r' r' r( �<module> s� + !/ O m] sqlalchemy/dialects/postgresql/__pycache__/pg8000.cpython-39.pyc 0000644 00000052165 15125143220 0020464 0 ustar 00 a ��Jh�H � @ s$ d Z ddlZddlZddlmZ ddlmZ ddlm Z ddlm Z ddlm Z dd lm Z dd lm Z dd lmZ dd lmZ dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z ddl m Z ddl m Z ddl!m"Z" G dd � d e j#�Z$G d d � d e j%�Z&G d d � d e&e j'�Z(G d!d"� d"e&�Z)G d#d$� d$e�Z*G d%d&� d&e�Z+G d'd(� d(e jj,�Z-G d)d*� d*e jj.�Z/G d+d,� d,e jj0�Z1G d-d.� d.e�Z2G d/d0� d0e �Z3G d1d2� d2e �Z4G d3d4� d4e j5�Z6G d5d6� d6e j7�Z8G d7d8� d8e j9�Z:G d9d:� d:e j;�Z<G d;d<� d<e j=�Z>G d=d>� d>e j?�Z@G d?d@� d@e jA�ZBG dAdB� dBe jC�ZDG dCdD� dDe�ZEG dEdF� dFee�ZFG dGdH� dHejG�ZHG dIdJ� dJejI�ZJe �K� ZLG dKdL� dLe�ZMG dMdN� dN�ZNG dOdP� dPe�ZOG dQdR� dRe�ZPG dSdT� dTe�ZQeQZRdS )Ua� .. dialect:: postgresql+pg8000 :name: pg8000 :dbapi: pg8000 :connectstring: postgresql+pg8000://user:password@host:port/dbname[?key=value&key=value...] :url: https://pypi.org/project/pg8000/ .. versionchanged:: 1.4 The pg8000 dialect has been updated for version 1.16.6 and higher, and is again part of SQLAlchemy's continuous integration with full feature support. .. _pg8000_unicode: Unicode ------- pg8000 will encode / decode string values between it and the server using the PostgreSQL ``client_encoding`` parameter; by default this is the value in the ``postgresql.conf`` file, which often defaults to ``SQL_ASCII``. Typically, this can be changed to ``utf-8``, as a more useful default:: # client_encoding = sql_ascii # actually, defaults to database encoding client_encoding = utf8 The ``client_encoding`` can be overridden for a session by executing the SQL: .. sourcecode:: sql SET CLIENT_ENCODING TO 'utf8'; SQLAlchemy will execute this SQL on all new connections based on the value passed to :func:`_sa.create_engine` using the ``client_encoding`` parameter:: engine = create_engine( "postgresql+pg8000://user:pass@host/dbname", client_encoding="utf8" ) .. _pg8000_ssl: SSL Connections --------------- pg8000 accepts a Python ``SSLContext`` object which may be specified using the :paramref:`_sa.create_engine.connect_args` dictionary:: import ssl ssl_context = ssl.create_default_context() engine = sa.create_engine( "postgresql+pg8000://scott:tiger@192.168.0.199/test", connect_args={"ssl_context": ssl_context}, ) If the server uses an automatically-generated certificate that is self-signed or does not match the host name (as seen from the client), it may also be necessary to disable hostname checking:: import ssl ssl_context = ssl.create_default_context() ssl_context.check_hostname = False ssl_context.verify_mode = ssl.CERT_NONE engine = sa.create_engine( "postgresql+pg8000://scott:tiger@192.168.0.199/test", connect_args={"ssl_context": ssl_context}, ) .. _pg8000_isolation_level: pg8000 Transaction Isolation Level ------------------------------------- The pg8000 dialect offers the same isolation level settings as that of the :ref:`psycopg2 <psycopg2_isolation_level>` dialect: * ``READ COMMITTED`` * ``READ UNCOMMITTED`` * ``REPEATABLE READ`` * ``SERIALIZABLE`` * ``AUTOCOMMIT`` .. seealso:: :ref:`postgresql_isolation_level` :ref:`psycopg2_isolation_level` � N� )�ranges)�ARRAY)�_DECIMAL_TYPES)� _FLOAT_TYPES)� _INT_TYPES)�ENUM��INTERVAL)� PGCompiler)� PGDialect)�PGExecutionContext)�PGIdentifierPreparer)�JSON)�JSONB)� JSONPathType)� _SpaceVector)� OIDVECTOR)�CITEXT� )�exc)�util)� processors)�sqltypes)� quoted_namec @ s e Zd ZdZdS )� _PGStringTN��__name__� __module__� __qualname__�render_bind_cast� r! r! �Z/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/postgresql/pg8000.pyr } s r c @ s e Zd ZdZdd� ZdS )� _PGNumericTc C sv | j rB|tv r t�tj| j�S |tv s.|tv r2d S t � d| ��n0|tv rNd S |tv s^|tv rdtj S t � d| ��d S )NzUnknown PG numeric type: %d) Z asdecimalr r Z to_decimal_processor_factory�decimal�DecimalZ _effective_decimal_return_scaler r r ZInvalidRequestErrorZto_float��self�dialect�coltyper! r! r" �result_processor� s" ���z_PGNumeric.result_processorN�r r r r r* r! r! r! r" r# � s r# c @ s e Zd ZdZdZdS )�_PGFloat�floatTN�r r r Z__visit_name__r r! r! r! r" r, � s r, c @ s e Zd Zdd� ZdS )�_PGNumericNoBindc C s d S �Nr! )r' r( r! r! r" �bind_processor� s z _PGNumericNoBind.bind_processorN)r r r r1 r! r! r! r" r/ � s r/ c @ s e Zd ZdZdd� ZdS )�_PGJSONTc C s d S r0 r! r& r! r! r" r* � s z_PGJSON.result_processorNr+ r! r! r! r" r2 � s r2 c @ s e Zd ZdZdd� ZdS )�_PGJSONBTc C s d S r0 r! r& r! r! r" r* � s z_PGJSONB.result_processorNr+ r! r! r! r" r3 � s r3 c @ s e Zd Zdd� ZdS )�_PGJSONIndexTypec C s t d��d S )Nzshould not be here)�NotImplementedError�r' �dbapir! r! r" �get_dbapi_type� s z _PGJSONIndexType.get_dbapi_typeN�r r r r8 r! r! r! r" r4 � s r4 c @ s e Zd ZdZdZdS )�_PGJSONIntIndexTypeZjson_int_indexTNr. r! r! r! r" r: � s r: c @ s e Zd ZdZdZdS )�_PGJSONStrIndexTypeZjson_str_indexTNr. r! r! r! r" r; � s r; c @ s e Zd ZdS )�_PGJSONPathTypeN�r r r r! r! r! r" r< � s r< c @ s e Zd Zdd� ZdS )�_PGEnumc C s |j S r0 )�UNKNOWNr6 r! r! r" r8 � s z_PGEnum.get_dbapi_typeNr9 r! r! r! r" r> � s r> c @ s$ e Zd ZdZdd� Zedd� �ZdS )� _PGIntervalTc C s |j S r0 r r6 r! r! r" r8 � s z_PGInterval.get_dbapi_typec K s t |jd�S )N)Z precision)r@ Zsecond_precision)�cls�interval�kwr! r! r" �adapt_emulated_to_native� s z$_PGInterval.adapt_emulated_to_nativeN)r r r r r8 � classmethodrD r! r! r! r" r@ � s r@ c @ s e Zd ZdZdS )� _PGTimeStampTNr r! r! r! r" rF � s rF c @ s e Zd ZdZdS )�_PGDateTNr r! r! r! r" rG � s rG c @ s e Zd ZdZdS )�_PGTimeTNr r! r! r! r" rH � s rH c @ s e Zd ZdZdS )� _PGIntegerTNr r! r! r! r" rI � s rI c @ s e Zd ZdZdS )�_PGSmallIntegerTNr r! r! r! r" rJ � s rJ c @ s e Zd ZdS )� _PGNullTypeNr= r! r! r! r" rK � s rK c @ s e Zd ZdZdS )� _PGBigIntegerTNr r! r! r! r" rL � s rL c @ s e Zd ZdZdS )� _PGBooleanTNr r! r! r! r" rM � s rM c @ s e Zd ZdZdS )�_PGARRAYTNr r! r! r! r" rN � s rN c @ s e Zd ZdS )� _PGOIDVECTORNr= r! r! r! r" rO s rO c @ s e Zd Zdd� Zdd� ZdS )� _Pg8000Rangec s |j j� � fdd�}|S )Nc s& t | tj�r"� | j| j| j| j�} | S r0 )� isinstancer �Range�lower�upper�bounds�empty��value�Z pg8000_Ranger! r" �to_range s �z-_Pg8000Range.bind_processor.<locals>.to_range�r7 rR )r' r( rZ r! rY r" r1 s z_Pg8000Range.bind_processorc C s dd� }|S )Nc S s& | d ur"t j| j| j| j| jd�} | S )N�rU rV �r rR rS rT rU Zis_emptyrW r! r! r" rZ s �z/_Pg8000Range.result_processor.<locals>.to_ranger! )r' r( r) rZ r! r! r" r* s z _Pg8000Range.result_processorN�r r r r1 r* r! r! r! r" rP s rP c @ s e Zd Zdd� Zdd� ZdS )�_Pg8000MultiRangec s |j j� � fdd�}|S )Nc sX t | t�rPg }| D ]8}t |tj�r@|�� |j|j|j|j�� q|�|� q|S | S d S r0 ) rQ �listr rR �appendrS rT rU rV )rX �mr�vrY r! r" � to_multirange# s � z7_Pg8000MultiRange.bind_processor.<locals>.to_multiranger[ )r' r( rd r! rY r" r1 s z _Pg8000MultiRange.bind_processorc C s dd� }|S )Nc S s$ | d u r d S t �dd� | D ��S d S )Nc s s( | ] }t j|j|j|j|jd �V qdS )r\ Nr] )�.0rc r! r! r" � <genexpr>8 s ��zL_Pg8000MultiRange.result_processor.<locals>.to_multirange.<locals>.<genexpr>)r Z MultiRangerW r! r! r" rd 4 s �z9_Pg8000MultiRange.result_processor.<locals>.to_multiranger! )r' r( r) rd r! r! r" r* 3 s z"_Pg8000MultiRange.result_processorNr^ r! r! r! r" r_ s r_ c @ s e Zd Zdd� Zdd� ZdS )�PGExecutionContext_pg8000c C s: dt t| ��dd � t t� �dd � f }t| j�� |�S )Nzc_%s_%s� )�hex�id�_server_side_id�ServerSideCursorZ_dbapi_connection�cursor)r' �identr! r! r" �create_server_side_cursorF s *z3PGExecutionContext_pg8000.create_server_side_cursorc C s | j s d S d S r0 )Zcompiled�r' r! r! r" �pre_execJ s z"PGExecutionContext_pg8000.pre_execN)r r r ro rq r! r! r! r" rg E s rg c @ s� e Zd ZdZdd� Zedd� �Zedd� �Zedd � �Zd d d �Z dd� Z dd� Z d dd�Z dd� Z dd� Zdd� Zd dd�Zd S ) rl Tc C s || _ || _d S r0 )rn rm )r' rm rn r! r! r" �__init__R s zServerSideCursor.__init__c C s | j jS r0 )rm � connectionrp r! r! r" rs V s zServerSideCursor.connectionc C s | j jS r0 )rm �rowcountrp r! r! r" rt Z s zServerSideCursor.rowcountc C s | j jS r0 )rm � descriptionrp r! r! r" ru ^ s z ServerSideCursor.descriptionr! Nc C s( d| j d | }| jj|||d� | S )NzDECLARE z NO SCROLL CURSOR FOR )�stream)rn rm �execute)r' � operation�argsrv �opr! r! r" rw b s zServerSideCursor.executec C s | j �||� | S r0 )rm � executemany)r' rx Z param_setsr! r! r" r{ g s z ServerSideCursor.executemanyc C s | j �d| j � | j �� S )NzFETCH FORWARD 1 FROM )rm rw rn �fetchonerp r! r! r" r| k s zServerSideCursor.fetchonec C s@ |d u r| � � S | j�dtt|�� d | j � | j� � S d S )NzFETCH FORWARD z FROM )�fetchallrm rw �str�intrn )r' �numr! r! r" � fetchmanyo s �zServerSideCursor.fetchmanyc C s | j �d| j � | j �� S )NzFETCH FORWARD ALL FROM )rm rw rn r} rp r! r! r" r} x s zServerSideCursor.fetchallc C s | j �d| j � | j �� d S )NzCLOSE )rm rw rn �closerp r! r! r" r� | s zServerSideCursor.closec G s | j j|� d S r0 )rm � setinputsizes)r' �sizesr! r! r" r� � s z ServerSideCursor.setinputsizesc C s d S r0 r! )r' �size�columnr! r! r" � setoutputsize� s z ServerSideCursor.setoutputsize)r! N)N)N)r r r � server_siderr �propertyrs rt ru rw r{ r| r� r} r� r� r� r! r! r! r" rl O s rl c @ s e Zd Zdd� ZdS )�PGCompiler_pg8000c K s, | j |jfi |��d | j |jfi |�� S )Nz %% )�process�left�right)r' �binary�operatorrC r! r! r" �visit_mod_binary� s ���z"PGCompiler_pg8000.visit_mod_binaryN)r r r r� r! r! r! r" r� � s r� c @ s e Zd Zdd� ZdS )�PGIdentifierPreparer_pg8000c O s" t j| g|�R i |�� d| _d S )NF)r rr Z_double_percents)r' ry �kwargsr! r! r" rr � s z$PGIdentifierPreparer_pg8000.__init__N)r r r rr r! r! r! r" r� � s r� c K @ s� e Zd ZdZdZdZdZdZdZe Z e Z e ZdZdZdZe�ejejeejeeje ej e ej e ej!e"e#e$e%e%ej j&e'ej j(e)ej j*e+ej j,e-ej.e/e0e/ej1e2ej1e2ej3e4ej5e6ej7e8ej9e:ej;e<ej=e>ej?e@eAeBeCjDeEeCjFeEeCjGeEeCjHeEeCjIeEeCjJeEeCjKeLeCjMeLeCjNeLeCjOeLeCjPeLeCjQeLi$�Zd,dd�ZRejSdd� �ZTeUd d � �ZVd d � ZWd d� ZXdd� ZYdd� ZZdd� Z[dd� Z\dd� Z]dd� Z^dd � Z_d d � Z`d d � Zad-d"d#�Zbd.d$d%�Zcd&d'� Zdd(d)� ZeejSd*d+� �ZfdS )/�PGDialect_pg8000�pg8000T�formatNc K s< t j| fi |�� || _| jdk r*td��| jr8td��d S )N)r � � z$pg8000 1.16.6 or greater is requiredznThe pg8000 dialect does not fully implement ipaddress type handling; INET is supported by default, CIDR is not)r rr �client_encoding�_dbapi_versionr5 �_native_inet_types)r' r� r� r! r! r" rr � s �zPGDialect_pg8000.__init__c C s8 | j r0t| j d�r0tdd� t�d| j j�D ��S dS d S )N� __version__c S s g | ] }t |��qS r! )r )re �xr! r! r" � <listcomp>� s �z3PGDialect_pg8000._dbapi_version.<locals>.<listcomp>z(\d+)(?:[-\.]?|$))�c r� r� )r7 �hasattr�tuple�re�findallr� rp r! r! r" r� � s ��� z PGDialect_pg8000._dbapi_versionc C s t d�S )Nr� )� __import__)rA r! r! r" � import_dbapi� s z PGDialect_pg8000.import_dbapic C s8 |j dd�}d|v r$t|d �|d< |�|j� g |fS )N�user)�username�port)Ztranslate_connect_argsr �update�query)r' �url�optsr! r! r" �create_connect_args� s z$PGDialect_pg8000.create_connect_argsc C s* t || jj�r dt|�v r dS dt|�v S )Nz network errorTzconnection is closed)rQ r7 ZInterfaceErrorr~ )r' �ers rm r! r! r" � is_disconnect� s �z PGDialect_pg8000.is_disconnectc C s dS )N)� AUTOCOMMITzREAD COMMITTEDzREAD UNCOMMITTEDzREPEATABLE READZ SERIALIZABLEr! )r' �dbapi_connectionr! r! r" �get_isolation_level_values s z+PGDialect_pg8000.get_isolation_level_valuesc C sP |� dd�}|dkr d|_n0d|_|�� }|�d|� �� |�d� |�� d S )N�_� r� TFz;SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL �COMMIT)�replaceZ autocommitrm rw r� )r' r� �levelrm r! r! r" �set_isolation_level s �� z$PGDialect_pg8000.set_isolation_levelc C sD |� � }z,|�d|rdnd � |�d� W |�� n |�� 0 d S )N�-SET SESSION CHARACTERISTICS AS TRANSACTION %sz READ ONLYz READ WRITEr� �rm rw r� �r' rs rX rm r! r! r" � set_readonly s �� z PGDialect_pg8000.set_readonlyc C s> |� � }z"|�d� |�� d }W |�� n |�� 0 |dkS )Nzshow transaction_read_onlyr �on�rm rw r| r� �r' rs rm �valr! r! r" � get_readonly* s z PGDialect_pg8000.get_readonlyc C sD |� � }z,|�d|rdnd � |�d� W |�� n |�� 0 d S )Nr� Z DEFERRABLEzNOT DEFERRABLEr� r� r� r! r! r" �set_deferrable4 s �� z PGDialect_pg8000.set_deferrablec C s> |� � }z"|�d� |�� d }W |�� n |�� 0 |dkS )Nzshow transaction_deferrabler r� r� r� r! r! r" �get_deferrable? s z PGDialect_pg8000.get_deferrablec C s8 |� � }|�d|�dd�� d�� |�d� |�� d S )NzSET CLIENT_ENCODING TO '�'z''r� )rm rw r� r� )r' r� r� rm r! r! r" �_set_client_encodingI s �� z%PGDialect_pg8000._set_client_encodingc C s |j �d|df� d S �Nr � )rs Z tpc_begin�r' rs �xidr! r! r" �do_begin_twophaseS s z"PGDialect_pg8000.do_begin_twophasec C s |j �� d S r0 )rs Z tpc_preparer� r! r! r" �do_prepare_twophaseV s z$PGDialect_pg8000.do_prepare_twophaseFc C s |j �d|df� d S r� )rs Z tpc_rollback�r' rs r� Z is_preparedZrecoverr! r! r" �do_rollback_twophaseY s z%PGDialect_pg8000.do_rollback_twophasec C s |j �d|df� d S r� )rs Z tpc_commitr� r! r! r" �do_commit_twophase^ s z#PGDialect_pg8000.do_commit_twophasec C s dd� |j �� D �S )Nc S s g | ] }|d �qS )r r! )re �rowr! r! r" r� d � z8PGDialect_pg8000.do_recover_twophase.<locals>.<listcomp>)rs Z tpc_recover)r' rs r! r! r" �do_recover_twophasec s z$PGDialect_pg8000.do_recover_twophasec s� g � dd� }� � |� �jd ur6�fdd�}� � |� �jdu rRdd� }� � |� �jrn�fdd�}� � |� t� �dkr�� fdd�}|S d S d S ) Nc S s | j t | j t< d S r0 )Zpy_typesr~ r ��connr! r! r" � on_connecti s z/PGDialect_pg8000.on_connect.<locals>.on_connectc s � � | � j� d S r0 )r� r� r� rp r! r" r� p s Fc S s$ | � ddd� � | � ddd� � d S )Nie c S s | S r0 r! ��sr! r! r" �<lambda>y r� zAPGDialect_pg8000.on_connect.<locals>.on_connect.<locals>.<lambda>i� c S s | S r0 r! r� r! r! r" r� | r� )�register_in_adapterr� r! r! r" r� w s c s | � d� j� | � d� j� d S )N�r i� )r� �_json_deserializerr� rp r! r" r� � s r c s � D ] }|| � qd S r0 r! )r� �fn)�fnsr! r" r� � s )ra r� r� r� �len)r' r� r! )r� r' r" r� f s zPGDialect_pg8000.on_connectc C s dS )N�;r! rp r! r! r" � _dialect_specific_select_one� s z-PGDialect_pg8000._dialect_specific_select_one)N)TF)TF)gr r r ZdriverZsupports_statement_cacheZsupports_unicode_statementsZsupports_unicode_bindsZdefault_paramstyleZ supports_sane_multi_rowcountrg Zexecution_ctx_clsr� Zstatement_compilerr� �preparerZ supports_server_side_cursorsr Zdescription_encodingr Z update_copyr Zcolspecsr �Stringr �Numericr/ �Floatr, r r2 �BooleanrM �NullTyperK r r3 r r r< � JSONIndexTyper4 �JSONIntIndexTyper: �JSONStrIndexTyper; ZIntervalr@ r �DateTimerF �DaterG �TimerH �IntegerrI � SmallIntegerrJ � BigIntegerrL �Enumr> r rN r rO r Z INT4RANGErP Z INT8RANGEZNUMRANGEZ DATERANGEZTSRANGEZ TSTZRANGEZINT4MULTIRANGEr_ ZINT8MULTIRANGEZ NUMMULTIRANGEZDATEMULTIRANGEZ TSMULTIRANGEZTSTZMULTIRANGErr Zmemoized_propertyr� rE r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r! r! r! r" r� � s� ��* � � /r� )S�__doc__r$ r� r� r �arrayr ZPGARRAY�baser r r r r r r r r �jsonr r r Z pg_catalogr r �typesr r r Zenginer Zsqlr Z sql.elementsr r� r r� r# r� r, r/ r2 r3 r� r4 r� r: r� r; r< r> r@ r� rF r� rG r� rH r� rI r� rJ r� rK r� rL r� rM rN rO ZAbstractSingleRangeImplrP ZAbstractMultiRangeImplr_ �counterrk rg rl r� r� r� r( r! r! r! r" �<module> sr Y # 8 sqlalchemy/dialects/postgresql/__pycache__/ext.cpython-39.pyc 0000644 00000041110 15125143220 0020332 0 ustar 00 a ��Jh�C � @ s� d dl mZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlm Z d d l m Z d d l m Z d d lmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ e�r>d dlm Z d dl m Z d dl m Z d dl m!Z! d dl"m#Z# d dlm$Z$ d d lm%Z% e d ed �Z&G d d � d ej e& �Z'G d!d"� d"e�Z(d#d$� Z)G d%d&� d&ej*e& �Z+G d'd(� d(e+�Z,G d)d*� d*e+�Z-G d+d,� d,e+�Z.G d-d.� d.e+�Z/G d/d0� d0e+�Z0G d1d2� d2e+�Z1d3S )4� )� annotations)�Any)�Iterable)�List)�Optional)�overload)� TYPE_CHECKING)�TypeVar� )�types)�ARRAY� )� coercions)�elements)� expression)� functions)�roles)�schema)�ColumnCollectionConstraint)�TEXT)�InternalTraversal)�_ColumnExpressionArgument)� ClauseElement)� ColumnElement)� OperatorType)� FromClause)�_CloneCallableType)�_TraverseInternalsType�_T)�boundc @ s� e Zd ZU dZd ZdZdejfdejfdejfgZ de d< e dd d �d d ��Z e d d d �dd ��Z d d d �dd �Z d$ddd�dd�Z ddd�dd�Zejfddd d �d d �Zed d!�d"d#��ZdS )%�aggregate_order_bya Represent a PostgreSQL aggregate order by expression. E.g.:: from sqlalchemy.dialects.postgresql import aggregate_order_by expr = func.array_agg(aggregate_order_by(table.c.a, table.c.b.desc())) stmt = select(expr) would represent the expression: .. sourcecode:: sql SELECT array_agg(a ORDER BY b DESC) FROM table; Similarly:: expr = func.string_agg( table.c.a, aggregate_order_by(literal_column("','"), table.c.a) ) stmt = select(expr) Would represent: .. sourcecode:: sql SELECT string_agg(a, ',' ORDER BY a) FROM table; .. versionchanged:: 1.2.13 - the ORDER BY argument may be multiple terms .. seealso:: :class:`_functions.array_agg` � postgresql�target�type�order_byr �_traverse_internalszColumnElement[_T]z _ColumnExpressionArgument[Any]�r" r$ c G s d S �N� ��selfr" r$ r( r( �W/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/postgresql/ext.py�__init__X s zaggregate_order_by.__init__z _ColumnExpressionArgument[_T]c G s d S r' r( r) r( r( r+ r, _ s c G sn t �tj|�| _| jj| _t|�}| |dkr8td��n2|dkrVt �tj|d �| _nt j |dtji�| _d S )Nr z)at least one ORDER BY element is requiredr Z_literal_as_text_role) r �expectr �ExpressionElementRoler" r# �len� TypeErrorr$ r Z ClauseList)r* r" r$ Z_lobr( r( r+ r, f s" � ���NzOptional[OperatorType]r )�against�returnc C s | S r' r( )r* r1 r( r( r+ � self_group} s z aggregate_order_by.self_groupr zIterable[ClauseElement])�kwargsr2 c K s | j | jfS r' r& )r* r4 r( r( r+ � get_children� s z aggregate_order_by.get_childrenr �None)�clone�kwr2 c K s, || j fi |��| _ || jfi |��| _d S r' r& )r* r7 r8 r( r( r+ �_copy_internals� s z"aggregate_order_by._copy_internalszList[FromClause])r2 c C s | j j| jj S r' )r" � _from_objectsr$ �r* r( r( r+ r: � s z aggregate_order_by._from_objects)N)�__name__� __module__� __qualname__�__doc__�__visit_name__Zstringify_dialectr Zdp_clauseelementZdp_typer% �__annotations__r r, r3 r5 r Z_cloner9 �propertyr: r( r( r( r+ r * s& $� ��r c sP e Zd ZdZdZdZdZdZe� ddd�d d � �Z � fd d �Z dd d�Z � Z S )�ExcludeConstraintz�A table-level EXCLUDE constraint. Defines an EXCLUDE constraint as described in the `PostgreSQL documentation`__. __ https://www.postgresql.org/docs/current/static/sql-createtable.html#SQL-CREATETABLE-EXCLUDE Zexclude_constraintNFr! �wherez:class:`.ExcludeConstraint`z$:paramref:`.ExcludeConstraint.where`c O s� g }g }i | _ t|� \}}tt�tj|�|�D ]V\\}}} } } | durP|�| � |dur^|jn| } | durt| | j | < |�|| | f� q.|| _t j | g|�R |� d�|� d�|� d�d�� |� dd�| _ |� d�} | dur�t� tj| �| _|� d i �| _dS ) a� Create an :class:`.ExcludeConstraint` object. E.g.:: const = ExcludeConstraint( (Column("period"), "&&"), (Column("group"), "="), where=(Column("group") != "some group"), ops={"group": "my_operator_class"}, ) The constraint is normally embedded into the :class:`_schema.Table` construct directly, or added later using :meth:`.append_constraint`:: some_table = Table( "some_table", metadata, Column("id", Integer, primary_key=True), Column("period", TSRANGE()), Column("group", String), ) some_table.append_constraint( ExcludeConstraint( (some_table.c.period, "&&"), (some_table.c.group, "="), where=some_table.c.group != "some group", name="some_table_excl_const", ops={"group": "my_operator_class"}, ) ) The exclude constraint defined in this example requires the ``btree_gist`` extension, that can be created using the command ``CREATE EXTENSION btree_gist;``. :param \*elements: A sequence of two tuples of the form ``(column, operator)`` where "column" is either a :class:`_schema.Column` object, or a SQL expression element (e.g. ``func.int8range(table.from, table.to)``) or the name of a column as string, and "operator" is a string containing the operator to use (e.g. `"&&"` or `"="`). In order to specify a column name when a :class:`_schema.Column` object is not available, while ensuring that any necessary quoting rules take effect, an ad-hoc :class:`_schema.Column` or :func:`_expression.column` object should be used. The ``column`` may also be a string SQL expression when passed as :func:`_expression.literal_column` or :func:`_expression.text` :param name: Optional, the in-database name of this constraint. :param deferrable: Optional bool. If set, emit DEFERRABLE or NOT DEFERRABLE when issuing DDL for this constraint. :param initially: Optional string. If set, emit INITIALLY <value> when issuing DDL for this constraint. :param using: Optional string. If set, emit USING <index_method> when issuing DDL for this constraint. Defaults to 'gist'. :param where: Optional SQL expression construct or literal SQL string. If set, emit WHERE <predicate> when issuing DDL for this constraint. :param ops: Optional dictionary. Used to define operator classes for the elements; works the same way as that of the :ref:`postgresql_ops <postgresql_operator_classes>` parameter specified to the :class:`_schema.Index` construct. .. versionadded:: 1.3.21 .. seealso:: :ref:`postgresql_operator_classes` - general description of how PostgreSQL operator classes are specified. N�name� deferrable� initially)rE rF rG �usingZgistrD �ops)� operators�zipr Z expect_col_expression_collectionr ZDDLConstraintColumnRole�appendrE � _render_exprsr r, �getrH r- ZStatementOptionRolerD rI )r* r r8 �columnsZ render_exprsZ expressionsrJ �expr�columnZstrnameZ add_element�operatorrE rD r( r( r+ r, � s> _ �� ��� zExcludeConstraint.__init__c s& t � �� � � fdd�| jD �| _d S )Nc s0 g | ](\}}}t |t�s |n� j| ||f�qS r( )� isinstance�str�c)�.0rP rE rR ��tabler( r+ � <listcomp>* s ��z1ExcludeConstraint._set_parent.<locals>.<listcomp>)�super� _set_parentrM )r* rX r8 �� __class__rW r+ r[ ' s �z ExcludeConstraint._set_parentc sJ � �fdd�� j D �}� j|� j� j� j� j� jd��}|j�� j� |S )Nc s& g | ] \}}}t �|� j��|f�qS r( )r Z_copy_expression�parent)rV rP �_rR �r* � target_tabler( r+ rY 4 s ��z+ExcludeConstraint._copy.<locals>.<listcomp>)rE rF rG rD rH ) rM r] rE rF rG rD rH �dispatch�_update)r* ra r8 r rU r( r` r+ �_copy3 s ��zExcludeConstraint._copy)N)r< r= r> r? r@ rD � inherit_cacheZ create_drop_stringify_dialectr Z_document_text_coercionr, r[ rd � __classcell__r( r( r\ r+ rC � s � rC c O s t |d< tjj| i |��S )z�PostgreSQL-specific form of :class:`_functions.array_agg`, ensures return type is :class:`_postgresql.ARRAY` and not the plain :class:`_types.ARRAY`, unless an explicit ``type_`` is passed. Z_default_array_type)r r �func� array_agg)�argr8 r( r( r+ rh G s rh c s e Zd ZdZ� fdd�Z� ZS )� _regconfig_fnTc sr t |�}t|�dkrBtjtj|�d�t� dd �� tj d�}|g}ng }� fdd�|D �}t � j || i |�� d S )Nr r rE )rE �apply_propagate_attrs�type_c s( g | ] }t jtj|t� d d�� d��qS �rE N)rE rk �r r- r r. �getattr�rV rU r; r( r+ rY c s � �z*_regconfig_fn.__init__.<locals>.<listcomp>) �listr/ r r- r r. �popro r � REGCONFIGrZ r, )r* �argsr4 � initial_arg� addtl_argsr\ r; r+ r, U s � � z_regconfig_fn.__init__)r< r= r> re r, rf r( r( r\ r+ rj R s rj c @ s e Zd ZdZdZejZdS )� to_tsvectora� The PostgreSQL ``to_tsvector`` SQL function. This function applies automatic casting of the REGCONFIG argument to use the :class:`_postgresql.REGCONFIG` datatype automatically, and applies a return type of :class:`_postgresql.TSVECTOR`. Assuming the PostgreSQL dialect has been imported, either by invoking ``from sqlalchemy.dialects import postgresql``, or by creating a PostgreSQL engine using ``create_engine("postgresql...")``, :class:`_postgresql.to_tsvector` will be used automatically when invoking ``sqlalchemy.func.to_tsvector()``, ensuring the correct argument and return type handlers are used at compile and execution time. .. versionadded:: 2.0.0rc1 TN)r< r= r> r? re r ZTSVECTORr# r( r( r( r+ rw o s rw c @ s e Zd ZdZdZejZdS )� to_tsquerya� The PostgreSQL ``to_tsquery`` SQL function. This function applies automatic casting of the REGCONFIG argument to use the :class:`_postgresql.REGCONFIG` datatype automatically, and applies a return type of :class:`_postgresql.TSQUERY`. Assuming the PostgreSQL dialect has been imported, either by invoking ``from sqlalchemy.dialects import postgresql``, or by creating a PostgreSQL engine using ``create_engine("postgresql...")``, :class:`_postgresql.to_tsquery` will be used automatically when invoking ``sqlalchemy.func.to_tsquery()``, ensuring the correct argument and return type handlers are used at compile and execution time. .. versionadded:: 2.0.0rc1 TN�r< r= r> r? re r �TSQUERYr# r( r( r( r+ rx � s rx c @ s e Zd ZdZdZejZdS )�plainto_tsquerya� The PostgreSQL ``plainto_tsquery`` SQL function. This function applies automatic casting of the REGCONFIG argument to use the :class:`_postgresql.REGCONFIG` datatype automatically, and applies a return type of :class:`_postgresql.TSQUERY`. Assuming the PostgreSQL dialect has been imported, either by invoking ``from sqlalchemy.dialects import postgresql``, or by creating a PostgreSQL engine using ``create_engine("postgresql...")``, :class:`_postgresql.plainto_tsquery` will be used automatically when invoking ``sqlalchemy.func.plainto_tsquery()``, ensuring the correct argument and return type handlers are used at compile and execution time. .. versionadded:: 2.0.0rc1 TNry r( r( r( r+ r{ � s r{ c @ s e Zd ZdZdZejZdS )�phraseto_tsquerya� The PostgreSQL ``phraseto_tsquery`` SQL function. This function applies automatic casting of the REGCONFIG argument to use the :class:`_postgresql.REGCONFIG` datatype automatically, and applies a return type of :class:`_postgresql.TSQUERY`. Assuming the PostgreSQL dialect has been imported, either by invoking ``from sqlalchemy.dialects import postgresql``, or by creating a PostgreSQL engine using ``create_engine("postgresql...")``, :class:`_postgresql.phraseto_tsquery` will be used automatically when invoking ``sqlalchemy.func.phraseto_tsquery()``, ensuring the correct argument and return type handlers are used at compile and execution time. .. versionadded:: 2.0.0rc1 TNry r( r( r( r+ r| � s r| c @ s e Zd ZdZdZejZdS )�websearch_to_tsquerya� The PostgreSQL ``websearch_to_tsquery`` SQL function. This function applies automatic casting of the REGCONFIG argument to use the :class:`_postgresql.REGCONFIG` datatype automatically, and applies a return type of :class:`_postgresql.TSQUERY`. Assuming the PostgreSQL dialect has been imported, either by invoking ``from sqlalchemy.dialects import postgresql``, or by creating a PostgreSQL engine using ``create_engine("postgresql...")``, :class:`_postgresql.websearch_to_tsquery` will be used automatically when invoking ``sqlalchemy.func.websearch_to_tsquery()``, ensuring the correct argument and return type handlers are used at compile and execution time. .. versionadded:: 2.0.0rc1 TNry r( r( r( r+ r} � s r} c s( e Zd ZdZdZeZ� fdd�Z� ZS )� ts_headlinea� The PostgreSQL ``ts_headline`` SQL function. This function applies automatic casting of the REGCONFIG argument to use the :class:`_postgresql.REGCONFIG` datatype automatically, and applies a return type of :class:`_types.TEXT`. Assuming the PostgreSQL dialect has been imported, either by invoking ``from sqlalchemy.dialects import postgresql``, or by creating a PostgreSQL engine using ``create_engine("postgresql...")``, :class:`_postgresql.ts_headline` will be used automatically when invoking ``sqlalchemy.func.ts_headline()``, ensuring the correct argument and return type handlers are used at compile and execution time. .. versionadded:: 2.0.0rc1 Tc s� t |�}t|�dk rd}n,t|d tj�rB|d jjtju rBd}nd}|rxt j t j |� d�� t� dd �tjd�}|g}ng }� fdd �|D �}t� j|| i |�� d S ) N� Fr Tr rE )rk rE rl c s( g | ] }t jtj|t� d d�� d��qS rm rn rp r; r( r+ rY s � �z(ts_headline.__init__.<locals>.<listcomp>)rq r/ rS r r r# Z_type_affinityr rz r r- r r. rr ro rs rZ r, )r* rt r4 Z has_regconfigru rv r\ r; r+ r, � s. �� � � zts_headline.__init__) r< r= r> r? re r r# r, rf r( r( r\ r+ r~ � s r~ N)2� __future__r �typingr r r r r r r � r �arrayr Zsqlr r r r r r Z sql.schemar Z sql.sqltypesr Z sql.visitorsr Z sql._typingr Z sql.elementsr r Z sql.operatorsr Zsql.selectabler r r r r rC rh ZGenericFunctionrj rw rx r{ r| r} r~ r( r( r( r+ �<module> sL f 8 sqlalchemy/dialects/postgresql/__pycache__/array.cpython-39.pyc 0000644 00000036473 15125143220 0020670 0 ustar 00 a ��JhZB � @ s� d dl mZ d dlZd dlmZ d dlmZ d dlmZ d dlmZ d dlm Z d dlm Z d d lm Z d d l m Z d d l mZ d d l mZ ddlmZ ddlmZ ddlmZ ddlm Z ddlmZ e �rvddlmZ ddlmZ ddlm Z ddl m Z ddl m Z ddl m!Z! ddl"m#Z# ddl$m%Z% dd l&m'Z' dd l&m(Z( dd l&m)Z) dd l&m*Z* dd lm+Z+ dd!l,m-Z- e d"ed#�Z.e j/fd$d%d&d'd(�d)d*�Ze j/fd$d%d&d'd(�d+d,�Z0G d-d.� d.ej1e. �Z2G d/d0� d0ej3e. �Z3d1d2d3�d4d5�Z4dS )6� )� annotationsN)�Any)�Iterable)�Optional)�Sequence)� TYPE_CHECKING)�TypeVar)�Union� )� CONTAINED_BY)�CONTAINS)�OVERLAP� )�types)�util)� expression)� operators)�InternalTraversal)�Dialect)�_ColumnExpressionArgument)�_TypeEngineArgument)� ColumnElement)�Grouping)� BindParameter)� OperatorType)�_SelectIterable)�_BindProcessorType)�_LiteralProcessorType)�_ResultProcessorType)� TypeEngine)�_TraverseInternalsType)�Self�_T)�bound� typing_Anyz _ColumnExpressionArgument[_T]r �ColumnElement[bool])�other�arrexpr�operator�returnc C s |� | |�S )zjA synonym for the ARRAY-level :meth:`.ARRAY.Comparator.any` method. See that method for details. )�any�r& r' r( � r, �Y/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/postgresql/array.pyr 1 s r c C s |� | |�S )zjA synonym for the ARRAY-level :meth:`.ARRAY.Comparator.all` method. See that method for details. )�allr+ r, r, r- �All> s r/ c s� e Zd ZU dZd ZdZdejfdejfgZ de d< dd�d d d d �� fd d�Z e dd�dd��Z d dd dddd�dd�Zd!dd d �d d �Z� ZS )"�arraya� A PostgreSQL ARRAY literal. This is used to produce ARRAY literals in SQL expressions, e.g.:: from sqlalchemy.dialects.postgresql import array from sqlalchemy.dialects import postgresql from sqlalchemy import select, func stmt = select(array([1, 2]) + array([3, 4, 5])) print(stmt.compile(dialect=postgresql.dialect())) Produces the SQL: .. sourcecode:: sql SELECT ARRAY[%(param_1)s, %(param_2)s] || ARRAY[%(param_3)s, %(param_4)s, %(param_5)s]) AS anon_1 An instance of :class:`.array` will always have the datatype :class:`_types.ARRAY`. The "inner" type of the array is inferred from the values present, unless the :paramref:`_postgresql.array.type_` keyword argument is passed:: array(["foo", "bar"], type_=CHAR) When constructing an empty array, the :paramref:`_postgresql.array.type_` argument is particularly important as PostgreSQL server typically requires a cast to be rendered for the inner type in order to render an empty array. SQLAlchemy's compilation for the empty array will produce this cast so that:: stmt = array([], type_=Integer) print(stmt.compile(dialect=postgresql.dialect())) Produces: .. sourcecode:: sql ARRAY[]::INTEGER[] As required by PostgreSQL for empty arrays. .. versionadded:: 2.0.40 added support to render empty PostgreSQL array literals with a required cast. Multidimensional arrays are produced by nesting :class:`.array` constructs. The dimensionality of the final :class:`_types.ARRAY` type is calculated by recursively adding the dimensions of the inner :class:`_types.ARRAY` type:: stmt = select( array( [array([1, 2]), array([3, 4]), array([column("q"), column("x")])] ) ) print(stmt.compile(dialect=postgresql.dialect())) Produces: .. sourcecode:: sql SELECT ARRAY[ ARRAY[%(param_1)s, %(param_2)s], ARRAY[%(param_3)s, %(param_4)s], ARRAY[q, x] ] AS anon_1 .. versionadded:: 1.3.6 added support for multidimensional array literals .. seealso:: :class:`_postgresql.ARRAY` Z postgresql�clauses�typer �_traverse_internalsN)�type_z Iterable[_T]z!Optional[_TypeEngineArgument[_T]]r$ )r1 r4 �kwc s~ t � jtjg|�R i |�� |dur(|n| jr:| jd jntj}t|t �rpt |j |j durd|j d ndd�| _n t |�| _dS )a Construct an ARRAY literal. :param clauses: iterable, such as a list, containing elements to be rendered in the array :param type\_: optional type. If omitted, the type is inferred from the contents of the array. Nr r � )� dimensions) �super�__init__r Zcomma_opr1 r2 �sqltypesZNULLTYPE� isinstance�ARRAY� item_typer7 )�selfr1 r4 r5 Z main_type�� __class__r, r- r9 � s �� � � zarray.__init__r �r) c C s | fS �Nr, �r> r, r, r- �_select_iterable� s zarray._select_iterableFr zOptional[TypeEngine[_T]]�boolzBindParameter[_T])r( �objr4 �_assume_scalarr) c sD |s� t ju r&tjd |� ��jdd�S t� ��fdd�|D ��S d S )NT)Z_compared_to_operatorr4 Z_compared_to_type�uniquec s g | ]}�j � |d �d��qS )T)rG r4 )� _bind_param)�.0�o�r( r> r4 r, r- � <listcomp>� s ��z%array._bind_param.<locals>.<listcomp>)r �getitemr r r2 r0 )r> r( rF r4 rG r, rL r- rI � s � ��zarray._bind_paramzOptional[OperatorType]zUnion[Self, Grouping[_T]])�againstr) c C s& |t jt jt jfv r t�| �S | S d S rB )r Zany_opZall_oprN r r )r> rO r, r, r- � self_group� s zarray.self_group)NF)N)�__name__� __module__� __qualname__�__doc__Z__visit_name__Zstringify_dialectr Zdp_clauseelement_tupleZdp_typer3 �__annotations__r9 �propertyrD rI rP � __classcell__r, r, r? r- r0 K s M� �# � �r0 c @ s� e Zd ZdZd ddddd�dd �ZG d d � d ejje �ZeZ e j dd �d d��Z ddd�dd�Z ddd�dd�Zdddd�dd�ZdS ) r< an PostgreSQL ARRAY type. The :class:`_postgresql.ARRAY` type is constructed in the same way as the core :class:`_types.ARRAY` type; a member type is required, and a number of dimensions is recommended if the type is to be used for more than one dimension:: from sqlalchemy.dialects import postgresql mytable = Table( "mytable", metadata, Column("data", postgresql.ARRAY(Integer, dimensions=2)), ) The :class:`_postgresql.ARRAY` type provides all operations defined on the core :class:`_types.ARRAY` type, including support for "dimensions", indexed access, and simple matching such as :meth:`.types.ARRAY.Comparator.any` and :meth:`.types.ARRAY.Comparator.all`. :class:`_postgresql.ARRAY` class also provides PostgreSQL-specific methods for containment operations, including :meth:`.postgresql.ARRAY.Comparator.contains` :meth:`.postgresql.ARRAY.Comparator.contained_by`, and :meth:`.postgresql.ARRAY.Comparator.overlap`, e.g.:: mytable.c.data.contains([1, 2]) Indexed access is one-based by default, to match that of PostgreSQL; for zero-based indexed access, set :paramref:`_postgresql.ARRAY.zero_indexes`. Additionally, the :class:`_postgresql.ARRAY` type does not work directly in conjunction with the :class:`.ENUM` type. For a workaround, see the special type at :ref:`postgresql_array_of_enum`. .. container:: topic **Detecting Changes in ARRAY columns when using the ORM** The :class:`_postgresql.ARRAY` type, when used with the SQLAlchemy ORM, does not detect in-place mutations to the array. In order to detect these, the :mod:`sqlalchemy.ext.mutable` extension must be used, using the :class:`.MutableList` class:: from sqlalchemy.dialects.postgresql import ARRAY from sqlalchemy.ext.mutable import MutableList class SomeOrmClass(Base): # ... data = Column(MutableList.as_mutable(ARRAY(Integer))) This extension will allow "in-place" changes such to the array such as ``.append()`` to produce events which will be detected by the unit of work. Note that changes to elements **inside** the array, including subarrays that are mutated in place, are **not** detected. Alternatively, assigning a new array value to an ORM element that replaces the old one will always trigger a change event. .. seealso:: :class:`_types.ARRAY` - base array type :class:`_postgresql.array` - produces a literal array value. FNz_TypeEngineArgument[_T]rE z Optional[int])r= �as_tupler7 � zero_indexesc C s> t |t�rtd��t |t�r"|� }|| _|| _|| _|| _dS )a- Construct an ARRAY. E.g.:: Column("myarray", ARRAY(Integer)) Arguments are: :param item_type: The data type of items of this array. Note that dimensionality is irrelevant here, so multi-dimensional arrays like ``INTEGER[][]``, are constructed as ``ARRAY(Integer)``, not as ``ARRAY(ARRAY(Integer))`` or such. :param as_tuple=False: Specify whether return results should be converted to tuples from lists. DBAPIs such as psycopg2 return lists by default. When tuples are returned, the results are hashable. :param dimensions: if non-None, the ARRAY will assume a fixed number of dimensions. This will cause the DDL emitted for this ARRAY to include the exact number of bracket clauses ``[]``, and will also optimize the performance of the type overall. Note that PG arrays are always implicitly "non-dimensioned", meaning they can store any number of dimensions no matter how they were declared. :param zero_indexes=False: when True, index values will be converted between Python zero-based and PostgreSQL one-based indexes, e.g. a value of one will be added to all index values before passing to the database. zUDo not nest ARRAY types; ARRAY(basetype) handles multi-dimensional arrays of basetypeN)r; r< � ValueErrorr2 r= rX r7 rY )r> r= rX r7 rY r, r, r- r9 5 s ' � zARRAY.__init__c @ sB e Zd ZdZdddd�dd�Zddd�dd �Zddd�d d �Zd S ) zARRAY.Comparatora* Define comparison operations for :class:`_types.ARRAY`. Note that these operations are in addition to those provided by the base :class:`.types.ARRAY.Comparator` class, including :meth:`.types.ARRAY.Comparator.any` and :meth:`.types.ARRAY.Comparator.all`. r$ r% )r& �kwargsr) c K s | j t|tjd�S )z�Boolean expression. Test if elements are a superset of the elements of the argument array expression. kwargs may be ignored by this operator but are required for API conformance. �Z result_type)�operater r: �Boolean)r> r& r[ r, r, r- �containsr s zARRAY.Comparator.contains)r& r) c C s | j t|tjd�S )z�Boolean expression. Test if elements are a proper subset of the elements of the argument array expression. r\ )r] r r: r^ �r> r& r, r, r- � contained_by} s �z ARRAY.Comparator.contained_byc C s | j t|tjd�S )zuBoolean expression. Test if array has elements in common with an argument array expression. r\ )r] r r: r^ r` r, r, r- �overlap� s zARRAY.Comparator.overlapN)rQ rR rS rT r_ ra rb r, r, r, r- � Comparatorh s rc rA c C s t | jtj�o| jjS rB )r; r= r: �EnumZ native_enumrC r, r, r- �_against_native_enum� s �zARRAY._against_native_enumr z#Optional[_LiteralProcessorType[_T]])�dialectr) c sJ �j �|��|�� � d u r d S ddd�dd��ddd�� ��fdd � }|S ) NzIterable[typing_Any]�str)�elementsr) c S s dd� | �� d�S )NzARRAY[z, �])�join)rh r, r, r- �to_str� s z'ARRAY.literal_processor.<locals>.to_str�Sequence[typing_Any]��valuer) c s �� | � �j��}|S rB )�_apply_item_processorr7 �rn �inner�� item_procr> rk r, r- �process� s �z(ARRAY.literal_processor.<locals>.process)r= � dialect_impl�literal_processor�r> rf rt r, rr r- rv � s �zARRAY.literal_processorz2Optional[_BindProcessorType[Sequence[typing_Any]]]c s, �j �|��|�� ddd�� �fdd� }|S )N� Optional[Sequence[typing_Any]]zOptional[list[typing_Any]]rm c s" | d u r | S �� | � �jt�S d S rB )ro r7 �list�rn �rs r> r, r- rt � s �z%ARRAY.bind_processor.<locals>.process)r= ru �bind_processorrw r, r{ r- r| � s � zARRAY.bind_processor�objectz*_ResultProcessorType[Sequence[typing_Any]])rf �coltyper) c sl �j �|��||��ddd���fdd� }�jrh|�t�d��ddd��fd d � � ddd�� �fd d� }|S ) Nrl rx rm c s, | d u r | S �� | � �j�jr"tnt�S d S rB )ro r7 rX �tuplery rz r{ r, r- rt � s �z'ARRAY.result_processor.<locals>.processz^{(.*)}$rg � list[str]c s � � | ��d�}t|�S )Nr )�match�group�_split_enum_valuesrp )�patternr, r- �handle_raw_string� s z1ARRAY.result_processor.<locals>.handle_raw_stringc s& | d u r | S �t | t�r � | �n| �S rB )r; rg rz )r� �super_rpr, r- rt � s � �)r= ru �result_processorre �re�compile)r> rf r~ rt r, )r� rs r� r> r� r- r� � s � zARRAY.result_processor)FNF)rQ rR rS rT r9 r: r< rc r" Zcomparator_factoryr Zmemoized_propertyre rv r| r� r, r, r, r- r< � s J �3#r< rg r� )� array_stringr) c C s� d| vr| r| � d�S g S | �dd�}|�dd�}g }t� d|�}d}|D ]>}|dkr^| }qJ|rv|�|�dd�� qJ|�t�d |�� qJ|S ) N�"�,z\"z _$ESC_QUOTE$_z\\�\z(")Fz ([^\s,]+),?)�split�replacer� �append�extend�findall)r� �text�resultZ on_quotesZ in_quotes�tokr, r, r- r� � s r� )5� __future__r r� �typingr r$ r r r r r r r r r r � r r: r Zsqlr Z sql.visitorsr Zengine.interfacesr Z sql._typingr r Z sql.elementsr r Zsql.expressionr Z sql.operatorsr Zsql.selectabler Z sql.type_apir r r r r Z util.typingr! r" �eqr/ ZExpressionClauseListr0 r< r� r, r, r, r- �<module> sR �� # | sqlalchemy/dialects/postgresql/__pycache__/json.cpython-39.pyc 0000644 00000031261 15125143220 0020511 0 ustar 00 a ��Jh*2 � @ s� d dl mZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ dd l m Z dd l m Z dd l m Z dd l mZ dd l mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddlmZ ddlmZ ddl m Z e�rJddl m Z ddl m!Z! ddl"m#Z# dd l"m$Z$ dd l"m%Z% d Z&G d d � d ej'j(�Z(G d!d"� d"e(�Z)G d#d$� d$ej'�Z'G d%d&� d&e'�Z*d'S )(� )� annotations)�Any)�Callable)�List)�Optional)� TYPE_CHECKING)�Union� )�ARRAY)�array)�ASTEXT)� CONTAINED_BY)�CONTAINS)� DELETE_PATH)�HAS_ALL)�HAS_ANY)�HAS_KEY)�JSONPATH_ASTEXT)� PATH_EXISTS)� PATH_MATCH� )�types)�cast)�_T)�Dialect)� ColumnElement)�_BindProcessorType)�_LiteralProcessorType)� TypeEngine)�JSON�JSONBc @ s> e Zd Zdddd�dd�Zddd�d d �Zdd d�d d �ZdS )� JSONPathTyper z Optional[Callable[[Any], Any]]zCallable[[Any], Any])�dialect� super_proc�returnc s ddd�� fdd� }|S )Nr )�valuer$ c s< t | t�r| S | r(dd�tt| �� } nd} � r8� | �} | S )Nz{%s}z, z{})� isinstance�str�join�map)r% �r# � �X/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/postgresql/json.py�process/ s z(JSONPathType._processor.<locals>.processr+ )�selfr" r# r- r+ r* r, � _processor, s zJSONPathType._processorz_BindProcessorType[Any])r" r$ c C s | � || �|��S �N)r/ Zstring_bind_processor�r. r" r+ r+ r, �bind_processor@ s zJSONPathType.bind_processorz_LiteralProcessorType[Any]c C s | � || �|��S r0 )r/ Zstring_literal_processorr1 r+ r+ r, �literal_processorC s z JSONPathType.literal_processorN)�__name__� __module__� __qualname__r/ r2 r3 r+ r+ r+ r, r! + s r! c @ s e Zd ZdZd ZdS )�JSONPATHad JSON Path Type. This is usually required to cast literal values to json path when using json search like function, such as ``jsonb_path_query_array`` or ``jsonb_path_exists``:: stmt = sa.select( sa.func.jsonb_path_query_array( table.c.jsonb_col, cast("$.address.id", JSONPATH) ) ) N)r4 r5 r6 �__doc__�__visit_name__r+ r+ r+ r, r7 I s r7 c s\ e Zd ZU dZdZe�� Zded< dddd �� fd d � Z G d d � d ej j e �Z e Z � ZS )r a Represent the PostgreSQL JSON type. :class:`_postgresql.JSON` is used automatically whenever the base :class:`_types.JSON` datatype is used against a PostgreSQL backend, however base :class:`_types.JSON` datatype does not provide Python accessors for PostgreSQL-specific comparison methods such as :meth:`_postgresql.JSON.Comparator.astext`; additionally, to use PostgreSQL ``JSONB``, the :class:`_postgresql.JSONB` datatype should be used explicitly. .. seealso:: :class:`_types.JSON` - main documentation for the generic cross-platform JSON datatype. The operators provided by the PostgreSQL version of :class:`_types.JSON` include: * Index operations (the ``->`` operator):: data_table.c.data["some key"] data_table.c.data[5] * Index operations returning text (the ``->>`` operator):: data_table.c.data["some key"].astext == "some value" Note that equivalent functionality is available via the :attr:`.JSON.Comparator.as_string` accessor. * Index operations with CAST (equivalent to ``CAST(col ->> ['some key'] AS <type>)``):: data_table.c.data["some key"].astext.cast(Integer) == 5 Note that equivalent functionality is available via the :attr:`.JSON.Comparator.as_integer` and similar accessors. * Path index operations (the ``#>`` operator):: data_table.c.data[("key_1", "key_2", 5, ..., "key_n")] * Path index operations returning text (the ``#>>`` operator):: data_table.c.data[ ("key_1", "key_2", 5, ..., "key_n") ].astext == "some value" Index operations return an expression object whose type defaults to :class:`_types.JSON` by default, so that further JSON-oriented instructions may be called upon the result type. Custom serializers and deserializers are specified at the dialect level, that is using :func:`_sa.create_engine`. The reason for this is that when using psycopg2, the DBAPI only allows serializers at the per-cursor or per-connection level. E.g.:: engine = create_engine( "postgresql+psycopg2://scott:tiger@localhost/test", json_serializer=my_serialize_fn, json_deserializer=my_deserialize_fn, ) When using the psycopg2 dialect, the json_deserializer is registered against the database using ``psycopg2.extras.register_default_json``. .. seealso:: :class:`_types.JSON` - Core level JSON type :class:`_postgresql.JSONB` TzTypeEngine[str]� astext_typeFN�boolzOptional[TypeEngine[str]])� none_as_nullr: c s t � j|d� |dur || _dS )a� Construct a :class:`_types.JSON` type. :param none_as_null: if True, persist the value ``None`` as a SQL NULL value, not the JSON encoding of ``null``. Note that when this flag is False, the :func:`.null` construct can still be used to persist a NULL value:: from sqlalchemy import null conn.execute(table.insert(), {"data": null()}) .. seealso:: :attr:`_types.JSON.NULL` :param astext_type: the type to use for the :attr:`.JSON.Comparator.astext` accessor on indexed attributes. Defaults to :class:`_types.Text`. )r< N)�super�__init__r: )r. r< r: �� __class__r+ r, r> � s z JSON.__init__c @ s, e Zd ZU dZded< edd�dd��ZdS ) zJSON.Comparator�6Define comparison operations for :class:`_types.JSON`.r �typezColumnElement[str])r$ c C sP t | jjjtjj�r0| jjjt | jj| jj d�S | jjjt | jj| jj d�S dS )a On an indexed expression, use the "astext" (e.g. "->>") conversion when rendered in SQL. E.g.:: select(data_table.c.data["some key"].astext) .. seealso:: :meth:`_expression.ColumnElement.cast` �Z result_typeN) r& �expr�rightrB �sqltypesr r! �left�operater r: r )r. r+ r+ r, �astext� s ��zJSON.Comparator.astextN)r4 r5 r6 r8 �__annotations__�propertyrI r+ r+ r+ r, � Comparator� s rL )FN)r4 r5 r6 r8 Zrender_bind_castrF �Textr: rJ r> r rL r �comparator_factory� __classcell__r+ r+ r? r, r [ s M � r c @ s. e Zd ZdZd ZG dd� deje �ZeZdS )r a Represent the PostgreSQL JSONB type. The :class:`_postgresql.JSONB` type stores arbitrary JSONB format data, e.g.:: data_table = Table( "data_table", metadata, Column("id", Integer, primary_key=True), Column("data", JSONB), ) with engine.connect() as conn: conn.execute( data_table.insert(), data={"key1": "value1", "key2": "value2"} ) The :class:`_postgresql.JSONB` type includes all operations provided by :class:`_types.JSON`, including the same behaviors for indexing operations. It also adds additional operators specific to JSONB, including :meth:`.JSONB.Comparator.has_key`, :meth:`.JSONB.Comparator.has_all`, :meth:`.JSONB.Comparator.has_any`, :meth:`.JSONB.Comparator.contains`, :meth:`.JSONB.Comparator.contained_by`, :meth:`.JSONB.Comparator.delete_path`, :meth:`.JSONB.Comparator.path_exists` and :meth:`.JSONB.Comparator.path_match`. Like the :class:`_types.JSON` type, the :class:`_postgresql.JSONB` type does not detect in-place changes when used with the ORM, unless the :mod:`sqlalchemy.ext.mutable` extension is used. Custom serializers and deserializers are shared with the :class:`_types.JSON` class, using the ``json_serializer`` and ``json_deserializer`` keyword arguments. These must be specified at the dialect level using :func:`_sa.create_engine`. When using psycopg2, the serializers are associated with the jsonb type using ``psycopg2.extras.register_default_jsonb`` on a per-connection basis, in the same way that ``psycopg2.extras.register_default_json`` is used to register these handlers with the json type. .. seealso:: :class:`_types.JSON` c @ s� e Zd ZU dZded< ddd�dd�Zddd�d d �Zddd�d d �Zdddd �dd�Zddd�dd�Z ddd�dd�Z ddd�dd�Z ddd�dd�Z dS ) zJSONB.ComparatorrA r rB r zColumnElement[bool])�otherr$ c C s | j t|tjd�S )z�Boolean expression. Test for presence of a key (equivalent of the ``?`` operator). Note that the key may be a SQLA expression. rC )rH r rF �Boolean�r. rP r+ r+ r, �has_key# s zJSONB.Comparator.has_keyc C s | j t|tjd�S )zxBoolean expression. Test for presence of all keys in jsonb (equivalent of the ``?&`` operator) rC )rH r rF rQ rR r+ r+ r, �has_all) s zJSONB.Comparator.has_allc C s | j t|tjd�S )zwBoolean expression. Test for presence of any key in jsonb (equivalent of the ``?|`` operator) rC )rH r rF rQ rR r+ r+ r, �has_any/ s zJSONB.Comparator.has_any)rP �kwargsr$ c K s | j t|tjd�S )a" Boolean expression. Test if keys (or array) are a superset of/contained the keys of the argument jsonb expression (equivalent of the ``@>`` operator). kwargs may be ignored by this operator but are required for API conformance. rC )rH r rF rQ )r. rP rV r+ r+ r, �contains5 s zJSONB.Comparator.containsc C s | j t|tjd�S )z�Boolean expression. Test if keys are a proper subset of the keys of the argument jsonb expression (equivalent of the ``<@`` operator). rC )rH r rF rQ rR r+ r+ r, � contained_by? s �z JSONB.Comparator.contained_byz Union[List[str], _pg_array[str]]zColumnElement[JSONB])r r$ c C s2 t |t�st|�}t|ttj��}| jt|td�S )a= JSONB expression. Deletes field or array element specified in the argument array (equivalent of the ``#-`` operator). The input may be a list of strings that will be coerced to an ``ARRAY`` or an instance of :meth:`_postgres.array`. .. versionadded:: 2.0 rC ) r& � _pg_arrayr r rF ZTEXTrH r r )r. r Z right_sider+ r+ r, � delete_pathH s z JSONB.Comparator.delete_pathc C s | j t|tjd�S )z�Boolean expression. Test for presence of item given by the argument JSONPath expression (equivalent of the ``@?`` operator). .. versionadded:: 2.0 rC )rH r rF rQ rR r+ r+ r, � path_existsX s �z JSONB.Comparator.path_existsc C s | j t|tjd�S )a Boolean expression. Test if JSONPath predicate given by the argument JSONPath expression matches (equivalent of the ``@@`` operator). Only the first item of the result is taken into account. .. versionadded:: 2.0 rC )rH r rF rQ rR r+ r+ r, � path_matchb s �zJSONB.Comparator.path_matchN) r4 r5 r6 r8 rJ rS rT rU rW rX rZ r[ r\ r+ r+ r+ r, rL s rL N) r4 r5 r6 r8 r9 r rL r rN r+ r+ r+ r, r � s 1Qr N)+� __future__r �typingr r r r r r r r rY � operatorsr r r r r r r r r r � r rF Zsqlr Z sql._typingr Zengine.interfacesr Z sql.elementsr Z sql.type_apir r r �__all__r r! r7 r r+ r+ r+ r, �<module> sB sqlalchemy/dialects/postgresql/__pycache__/operators.cpython-39.pyc 0000644 00000002301 15125143220 0021547 0 ustar 00 a ��Jh� � @ s\ d dl mZ ejej Zejej Zejdeddd�Zejdeddd�Z ejdedddd�Z ejdedddd�Z ejd edddd�Z ejd eddd�Z ejd edddd�Zejd edddd�Zejd edddd�Zejdedddd�Zejdedd�Zejdedd�Zejdedd�Zejdedd�Zejdedd�Zejdedd�Zejdeddd�ZdS )� )� operatorsz->>T)� precedence�natural_self_precedent�eager_groupingz#>>�?)r r r � is_comparisonz?&z?|z#-z@?z@@z@>z<@z&&)r r z<<z>>z&<z&>z-|-z->N)Zsqlr Z _PRECEDENCEZjson_getitem_opZ_getitem_precedence�eqZ_eq_precedenceZ custom_opZASTEXTZJSONPATH_ASTEXTZHAS_KEYZHAS_ALLZHAS_ANYZ DELETE_PATHZ PATH_EXISTSZ PATH_MATCHZCONTAINSZ CONTAINED_BYZOVERLAPZSTRICTLY_LEFT_OFZSTRICTLY_RIGHT_OFZNOT_EXTEND_RIGHT_OFZNOT_EXTEND_LEFT_OFZ ADJACENT_TOZGETITEM� r r �]/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/postgresql/operators.py�<module> s� ����� ��� �� ������� sqlalchemy/dialects/postgresql/__pycache__/ranges.cpython-39.pyc 0000644 00000057326 15125143220 0021031 0 ustar 00 a ��JhҀ � @ s� d dl mZ d dlZd dlmZ d dlmZ d dlmZ d dlmZ d dlm Z d dlm Z d d lm Z d d lm Z d d lm Z d d lmZ d d lmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z ddlm Z d d l m Z d d l!mZ d d l"m#Z# d d l$m%Z% d d!l&m'Z' e�r�d d"l(m)Z) d d#l"m*Z* d d$l"m+Z+ ed%e d&�Z,e'd' Z-e%�r�d(d)iZ.d*d)iZ/ni Z.i Z/ej0f d+d)ie.��G d,d-� d-e e, ��Z1G d.d/� d/e e1e, �Z2G d0d1� d1e j#e, �Z3G d2d3� d3e3e1e, �Z4G d4d5� d5e4e, �Z5G d6d7� d7e3ee1e, �Z6G d8d9� d9e6e, �Z7G d:d;� d;e4e8 �Z9G d<d=� d=e4e8 �Z:G d>d?� d?e4e �Z;G d@dA� dAe4e �Z<G dBdC� dCe4e �Z=G dDdE� dEe4e �Z>G dFdG� dGe6e8 �Z?G dHdI� dIe6e8 �Z@G dJdK� dKe6e �ZAG dLdM� dMe6e �ZBG dNdO� dOe6e �ZCG dPdQ� dQe6e �ZDdRZEdSZFdTdUdV�dWdX�ZGdS )Y� )� annotationsN)�date)�datetime)� timedelta)�Decimal)�Any)�cast)�Generic)�List)�Optional)�overload)�Sequence)�Tuple)�Type)� TYPE_CHECKING)�TypeVar)�Union� )� ADJACENT_TO)� CONTAINED_BY)�CONTAINS)�NOT_EXTEND_LEFT_OF)�NOT_EXTEND_RIGHT_OF)�OVERLAP)�STRICTLY_LEFT_OF)�STRICTLY_RIGHT_OF� )�types)� operators)� TypeEngine)�py310)�Literal)� ColumnElement)�_TE)�TypeEngineMixin�_T)�bound)z()�[)z(]z[]�slotsTZkw_only�frozenc @ s� e Zd ZU dZdZded< dZded< erTej dd�Z ded < ej d d�Z d ed < n8ej f d die ��Z ded < ej f d d ie ��Z d ed < e s�dXdd d�dddd d�dd�Zd d�dd�Zed d�dd��Zed d�dd��Zed d�dd��Zed d�dd ��Zed d�d d ��Zed d�d d ��Zed!d�d"d#��Zd$d d%�d&d'�Zd(d�d)d*�ZdYdd+dd+d d,d-�d.d/�Zd(d d0�d1d2�Zd3d d0�d4d5�Z d6d d%�d7d8�Z e Z d3d d0�d9d:�Z d3d d0�d;d<�Z e Z!d3d d0�d=d>�Z"e"Z#d3d d0�d?d@�Z$d3d d0�dAdB�Z%dd+dd+d dC�dDdE�Z&d3d d0�dFdG�Z'd3d3d0�dHdI�Z(d3d3d0�dJdK�Z)d3d3d0�dLdM�Z*d3d3d0�dNdO�Z+d3d3d0�dPdQ�Z,d3d3d0�dRdS�Z-d+d�dTdU�Z.d+d�dVdW�Z/dS )Z�Rangea_ Represent a PostgreSQL range. E.g.:: r = Range(10, 50, bounds="()") The calling style is similar to that of psycopg and psycopg2, in part to allow easier migration from previous SQLAlchemy versions that used these objects directly. :param lower: Lower bound value, or None :param upper: Upper bound value, or None :param bounds: keyword-only, optional string value that is one of ``"()"``, ``"[)"``, ``"(]"``, ``"[]"``. Defaults to ``"[)"``. :param empty: keyword-only, optional bool indicating this is an "empty" range .. versionadded:: 2.0 Nz Optional[_T]�lower�upperr' )�default� _BoundsType�boundsF�bool�emptyr- )r/ r1 �r+ r, r/ r1 c C s | j �||||d�� d S )Nr2 )�__dict__�update)�selfr+ r, r/ r1 � r6 �Z/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/postgresql/ranges.py�__init__a s ��zRange.__init__��returnc C s | j S �N�r1 �r5 r6 r6 r7 �__bool__s s zRange.__bool__c C s | j S �z$A synonym for the 'empty' attribute.r< r= r6 r6 r7 �isemptyv s z Range.isemptyc C s | j S r? r< r= r6 r6 r7 �is_empty| s zRange.is_emptyc C s | j d dkS )z,Return True if the lower bound is inclusive.r �[�r/ r= r6 r6 r7 � lower_inc� s zRange.lower_incc C s | j o| jdu S )zKReturn True if this range is non-empty and lower bound is infinite.N)r1 r+ r= r6 r6 r7 � lower_inf� s zRange.lower_infc C s | j d dkS )z,Return True if the upper bound is inclusive.r �]rC r= r6 r6 r7 � upper_inc� s zRange.upper_incc C s | j o| jdu S )zOReturn True if this range is non-empty and the upper bound is infinite.N)r1 r, r= r6 r6 r7 � upper_inf� s zRange.upper_infzAbstractSingleRange[_T]c C s t � S r; )�AbstractSingleRanger= r6 r6 r7 �__sa_type_engine__� s zRange.__sa_type_engine__r% ��valuer: c C s� | j r dS | jdu r@| jdu p>| jd dkr6|| jk S || jkS | jdu rl| jd dkrb|| jkS || jkS | jd dkr�|| jkn|| jko�| jd dkr�|| jk S || jkS )z3Return True if this range contains the given value.FNr �)r �()r1 r+ r, r/ �r5 rL r6 r6 r7 �_contains_value� s* � � � � � � � �zRange._contains_valuer c C sb t | jt�st | jt�r dS t | jt�s4t | jt�r8dS t | jt�sPt | jt�rZtdd�S dS dS )uA Determine the “step” for this range, if it is a discrete one.r N)�days)� isinstancer+ �intr, r r r r= r6 r6 r7 �_get_discrete_step� s � zRange._get_discrete_step�strrS )�value1�bound1�value2�bound2� only_valuesr: c C sx |dv }|dv }|| u r$du rBn n||kr4dS |r<dS dS n(|du rV|rRdS dS |du rj|rfdS dS ||kr~||kr~dS |dv }|dv } | � � } | dur�|r�|s�|| 7 }d}n|r�|| 7 }d}|r�| s�|| 7 }d} n| r�|| 7 }d} ||k r�dS ||k�rdS |�rdS |�r | �r dS |�sH| �sH||k�r8dS |�rBdS dS n,|�s\|�rXdS dS | �sp|�rldS dS dS dS ) a Compare two range bounds. Return -1, 0 or 1 respectively when `value1` is less than, equal to or greater than `value2`. When `only_value` is ``True``, do not consider the *inclusivity* of the edges, just their values. > rB rN Nr ���r > rB rF TF)rT ) r5 rV rW rX rY rZ Zvalue1_is_lower_boundZvalue2_is_lower_boundZ value1_incZ value2_inc�stepr6 r6 r7 �_compare_edges� s^ zRange._compare_edges��otherr: c C s� t |t�stS | jr |jr dS | j|jkr.dS | j}| jd }|j}|jd }| j}| jd }|j}|jd } | �||||�dko�| �|||| �dkS )z�Compare this range to the `other` taking into account bounds inclusivity, returning ``True`` if they are equal. TFr r )rR r* �NotImplementedr1 r+ r/ r, r] � r5 r_ �slower�slower_b�olower�olower_b�supper�supper_b�oupper�oupper_br6 r6 r7 �__eq__+ s" �z Range.__eq__z Range[_T]c C s� | j r dS |j rdS | j}| jd }|j}|jd }| �||||�dk rLdS | j}| jd }|j}|jd } | �|||| �dkr�dS dS )z7Determine whether this range is a contained by `other`.TFr r )r1 r+ r/ r] r, ra r6 r6 r7 � contained_byF s" zRange.contained_byzUnion[_T, Range[_T]]c C s" t |t�r|�| �S | �|�S dS )z.Determine whether this range contains `value`.N)rR r* rk rP rO r6 r6 r7 �containsc s zRange.containsc C s� | j s |j rdS | j}| jd }| j}| jd }|j}|jd }|j}|jd } | �||||�dkr|| �|||| �dkr|dS | �||||�dkr�| �||||�dkr�dS dS )z3Determine whether this range overlaps with `other`.Fr r T�r1 r+ r/ r, r] � r5 r_ rb rc rf rg rd re rh ri r6 r6 r7 �overlapsm s* ����zRange.overlapsc C sD | j s |j rdS | j}| jd }|j}|jd }| �||||�dk S )zBDetermine whether this range is completely to the left of `other`.Fr r )r1 r, r/ r+ r] )r5 r_ rf rg rd re r6 r6 r7 �strictly_left_of� s zRange.strictly_left_ofc C sD | j s |j rdS | j}| jd }|j}|jd }| �||||�dkS )zCDetermine whether this range is completely to the right of `other`.Fr r rm )r5 r_ rb rc rh ri r6 r6 r7 �strictly_right_of� s zRange.strictly_right_ofc C sD | j s |j rdS | j}| jd }|j}|jd }| �||||�dkS )z>Determine whether this does not extend to the left of `other`.Fr )r1 r+ r/ r] )r5 r_ rb rc rd re r6 r6 r7 �not_extend_left_of� s zRange.not_extend_left_ofc C sD | j s |j rdS | j}| jd }|j}|jd }| �||||�dkS )z?Determine whether this does not extend to the right of `other`.Fr r )r1 r, r/ r] )r5 r_ rf rg rh ri r6 r6 r7 �not_extend_right_of� s zRange.not_extend_right_of)rV rW rX rY r: c C s� | � ||||d�}|dkrr| �� }|du r.dS |dkrT|dkrJ||| kS ||kS q�|dkrd||kS ||| kS n`|dkr�|dkr�|dks�|dkr�|d kr�| �� }|dur�dS |dkr�|dkp�|dko�|d kS dS dS ) zTDetermine whether an upper bound is immediately successive to a lower bound.Tr[ NFrF rB r rM rN )r] rT )r5 rV rW rX rY �resr\ r6 r6 r7 � _upper_edge_adjacent_to_lower� s> ������z#Range._upper_edge_adjacent_to_lowerc C sp | j s |j rdS | j}| jd }| j}| jd }|j}|jd }|j}|jd } | �||||�pn| �|| ||�S )z8Determine whether this range is adjacent to the `other`.Fr r )r1 r+ r/ r, ru rn r6 r6 r7 � adjacent_to� s" ���zRange.adjacent_toc C s� | j r |S |j r| S | �|�s0| �|�s0td��| j}| jd }| j}| jd }|j}|jd }|j}|jd } | �||||�dk r�|} |} n|} |} | �|||| �dkr�|} |} n|} | } t| | t t | | �d�S )z�Compute the union of this range with the `other`. This raises a ``ValueError`` exception if the two ranges are "disjunct", that is neither adjacent nor overlapping. zAAdding non-overlapping and non-adjacent ranges is not implementedr r rC ) r1 ro rv � ValueErrorr+ r/ r, r] r* r r. �r5 r_ rb rc rf rg rd re rh ri Zrlower�rlower_bZrupper�rupper_br6 r6 r7 �union s: � �z Range.unionc C s | � |�S r; )r{ �r5 r_ r6 r6 r7 �__add__@ s z Range.__add__c C s� | j s |j r| S | j}| jd }| j}| jd }|j}|jd }|j}|jd } | �||||�} | �|||| �} | dk r�| dkr�td��| �|||| �} | �||||�} | dks�| dk r�| S | dkr�| dkr�tdddd�S | dk�rZ| dk�rZ| dk�rZ|dk�rdnd }|dk�rB|d k�rB| �||||�dk�rBtdddd�S t||tt|| �d �S | dk�r�| dk�r�| dk�r�| d k�r�d nd}|dk�r�|d k�r�| �||||�dk�r�tdddd�S t||tt|| �d �S d �s�J d | � d|� ���dS )z�Compute the difference between this range and the `other`. This raises a ``ValueError`` exception if the two ranges are "disjunct", that is neither adjacent nor overlapping. r r z5Subtracting a strictly inner range is not implementedNTr< rB rM rF rC rN FzUnhandled case computing z - ) r1 r+ r/ r, r] rw r* r r. )r5 r_ rb rc rf rg rd re rh ri Zsl_vs_olZsu_vs_ouZsl_vs_ouZsu_vs_olrz ry r6 r6 r7 � differenceC sn � ���� � ���� �zRange.differencec C s | � |�S r; )r~ r| r6 r6 r7 �__sub__� s z Range.__sub__c C s� | j s|j s| �|�s$tdddd�S | j}| jd }| j}| jd }|j}|jd }|j}|jd } | �||||�dk r�|} |} n|} |} | �|||| �dkr�|} | } n|} |} t| | tt| | �d�S )zdCompute the intersection of this range with the `other`. .. versionadded:: 2.0.10 NTr< r r rC ) r1 ro r* r+ r/ r, r] r r. rx r6 r6 r7 � intersection� s2 �zRange.intersectionc C s | � |�S r; )r� r| r6 r6 r7 �__mul__� s z Range.__mul__c C s | � � S r; )� _stringifyr= r6 r6 r7 �__str__� s z Range.__str__c C s^ | j r dS | j| j }}|d u r$dn|}|d u r4dn|}td| j�\}}|� |� d|� |� �S )Nr1 � zTuple[str, str]�,)r1 r+ r, r r/ )r5 �l�rZb0�b1r6 r6 r7 r� � s zRange._stringify)NN)F)0�__name__� __module__� __qualname__�__doc__r+ �__annotations__r, r � dataclasses�fieldr/ r1 � dc_kwonlyr r8 r> �propertyr@ rA rD rE rG rH rJ rP rT r] rj rk rl � __contains__ro rp � __lshift__rq � __rshift__rr rs ru rv r{ r} r~ r r� r� r� r� r6 r6 r6 r7 r* ; sn �� �Y /.L&r* c @ s" e Zd ZdZedd�dd��ZdS )� MultiRangea? Represents a multirange sequence. This list subclass is an utility to allow automatic type inference of the proper multi-range SQL type depending on the single range values. This is useful when operating on literal multi-ranges:: import sqlalchemy as sa from sqlalchemy.dialects.postgresql import MultiRange, Range value = literal(MultiRange([Range(2, 4)])) select(tbl).where(tbl.c.value.op("@")(MultiRange([Range(-3, 7)]))) .. versionadded:: 2.0.26 .. seealso:: - :ref:`postgresql_multirange_list_use`. zAbstractMultiRange[_T]r9 c C s t � S r; )�AbstractMultiRanger= r6 r6 r7 rJ � s z MultiRange.__sa_type_engine__N)r� r� r� r� r� rJ r6 r6 r6 r7 r� � s r� c sx e Zd ZdZdZdZedddd�dd��Zed dd d�d d��Zd dd d�� fd d� ZG dd� dej e e �Z � Z S )� AbstractRangez0Base class for single and multi Range SQL types.Tz Type[_TE]r r# )�cls�kwr: c K s d S r; r6 �r5 r� r� r6 r6 r7 �adapt� s zAbstractRange.adaptzType[TypeEngineMixin]zTypeEngine[Any]c K s d S r; r6 r� r6 r6 r7 r� � s z-Type[Union[TypeEngine[Any], TypeEngineMixin]]c sL t |ttf�r<|| jur<| j}t|� d�|| jfd|i�� S t� �|�S dS )a Dynamically adapt a range type to an abstract impl. For example ``INT4RANGE().adapt(_Psycopg2NumericRange)`` should produce a type that will have ``_Psycopg2NumericRange`` behaviors and also render as ``INT4RANGE`` in SQL and DDL. Z RangeImpl�__visit_name__N)� issubclass�AbstractSingleRangeImpl�AbstractMultiRangeImpl� __class__r� �type�superr� )r5 r� r� Z visit_name�r� r6 r7 r� � s �� �c @ s� e Zd ZdZdddd�dd�Zddd�dd �Zddd�d d �Zddd�d d �ZeZddd�dd�Z e Z ddd�dd�Z ddd�dd�Z ddd�dd�Z ddd�dd�Zddd�dd�Zddd�dd �Zd S ) z AbstractRange.comparator_factoryz-Define comparison operations for range types.r zColumnElement[bool])r_ r� r: c K s | j �t|�S )a Boolean expression. Returns true if the right hand operand, which can be an element or a range, is contained within the column. kwargs may be ignored by this operator but are required for API conformance. )�expr�operater )r5 r_ r� r6 r6 r7 rl s z)AbstractRange.comparator_factory.containsr^ c C s | j �t|�S )zsBoolean expression. Returns true if the column is contained within the right hand operand. )r� r� r r| r6 r6 r7 rk # s z-AbstractRange.comparator_factory.contained_byc C s | j �t|�S )z�Boolean expression. Returns true if the column overlaps (has points in common with) the right hand operand. )r� r� r r| r6 r6 r7 ro ) s z)AbstractRange.comparator_factory.overlapsc C s | j �t|�S )zsBoolean expression. Returns true if the column is strictly left of the right hand operand. )r� r� r r| r6 r6 r7 rp / s z1AbstractRange.comparator_factory.strictly_left_ofc C s | j �t|�S )ztBoolean expression. Returns true if the column is strictly right of the right hand operand. )r� r� r r| r6 r6 r7 rq 7 s z2AbstractRange.comparator_factory.strictly_right_ofc C s | j �t|�S )z�Boolean expression. Returns true if the range in the column does not extend right of the range in the operand. )r� r� r r| r6 r6 r7 rs ? s z4AbstractRange.comparator_factory.not_extend_right_ofc C s | j �t|�S )z�Boolean expression. Returns true if the range in the column does not extend left of the range in the operand. )r� r� r r| r6 r6 r7 rr E s z3AbstractRange.comparator_factory.not_extend_left_ofc C s | j �t|�S )z}Boolean expression. Returns true if the range in the column is adjacent to the range in the operand. )r� r� r r| r6 r6 r7 rv K s z,AbstractRange.comparator_factory.adjacent_toc C s | j �tj|�S �z�Range expression. Returns the union of the two ranges. Will raise an exception if the resulting range is not contiguous. )r� r� r �addr| r6 r6 r7 r{ Q s z&AbstractRange.comparator_factory.unionc C s | j �tj|�S r� )r� r� r �subr| r6 r6 r7 r~ X s z+AbstractRange.comparator_factory.differencezColumnElement[Range[_T]]c C s | j �tj|�S )z�Range expression. Returns the intersection of the two ranges. Will raise an exception if the resulting range is not contiguous. )r� r� r �mulr| r6 r6 r7 r� _ s z-AbstractRange.comparator_factory.intersectionN)r� r� r� r� rl rk ro rp r� rq r� rs rr rv r{ r~ r� r6 r6 r6 r7 �comparator_factory s r� )r� r� r� r� Zrender_bind_cast� __abstract__r r� r Z Comparatorr* r r� � __classcell__r6 r6 r� r7 r� � s "r� c @ s$ e Zd ZdZdZddd�dd�ZdS ) rI z�Base for PostgreSQL RANGE types. These are types that return a single :class:`_postgresql.Range` object. .. seealso:: `PostgreSQL range functions <https://www.postgresql.org/docs/current/static/functions-range.html>`_ Tz Range[Any]r rK c C s� |j d ur|j n|j}t|t�r6t|�r.t� S t� S nFt|ttf�rJt � S t|t �rf|j s`t � S t � S t|t�rvt� S tjS d S r; )r+ r, rR rS � _is_int32� INT4RANGE� INT8RANGEr �float�NUMRANGEr �tzinfo�TSRANGE� TSTZRANGEr � DATERANGE�sqltypes�NULLTYPE)r5 rL �specr6 r6 r7 �_resolve_for_literalt s z(AbstractSingleRange._resolve_for_literalN�r� r� r� r� r� r� r6 r6 r6 r7 rI g s rI c @ s e Zd ZdZdS )r� zQMarker for AbstractSingleRange that will apply a subclass-specific adaptationN�r� r� r� r� r6 r6 r6 r7 r� � s r� c @ s$ e Zd ZdZdZddd�dd�ZdS ) r� z�Base for PostgreSQL MULTIRANGE types. these are types that return a sequence of :class:`_postgresql.Range` objects. TzSequence[Range[Any]]r rK c C s� |s t jS |d }|jd ur"|jn|j}t|t�rRtdd� |D ��rJt� S t� S nFt|t t f�rft � S t|t �r�|j s|t� S t� S t|t�r�t� S t jS d S )Nr c s s | ]}t |�V qd S r; )r� )�.0r� r6 r6 r7 � <genexpr>� � z:AbstractMultiRange._resolve_for_literal.<locals>.<genexpr>)r� r� r+ r, rR rS �all�INT4MULTIRANGE�INT8MULTIRANGEr r� � NUMMULTIRANGEr r� � TSMULTIRANGE�TSTZMULTIRANGEr �DATEMULTIRANGE)r5 rL �firstr� r6 r6 r7 r� � s z'AbstractMultiRange._resolve_for_literalNr� r6 r6 r6 r7 r� � s r� c @ s e Zd ZdZdS )r� zPMarker for AbstractMultiRange that will apply a subclass-specific adaptationNr� r6 r6 r6 r7 r� � s r� c @ s e Zd ZdZd ZdS )r� z(Represent the PostgreSQL INT4RANGE type.N�r� r� r� r� r� r6 r6 r6 r7 r� � s r� c @ s e Zd ZdZd ZdS )r� z(Represent the PostgreSQL INT8RANGE type.Nr� r6 r6 r6 r7 r� � s r� c @ s e Zd ZdZd ZdS )r� z'Represent the PostgreSQL NUMRANGE type.Nr� r6 r6 r6 r7 r� � s r� c @ s e Zd ZdZd ZdS )r� z(Represent the PostgreSQL DATERANGE type.Nr� r6 r6 r6 r7 r� � s r� c @ s e Zd ZdZd ZdS )r� �&Represent the PostgreSQL TSRANGE type.Nr� r6 r6 r6 r7 r� � s r� c @ s e Zd ZdZd ZdS )r� �(Represent the PostgreSQL TSTZRANGE type.Nr� r6 r6 r6 r7 r� � s r� c @ s e Zd ZdZd ZdS )r� z-Represent the PostgreSQL INT4MULTIRANGE type.Nr� r6 r6 r6 r7 r� � s r� c @ s e Zd ZdZd ZdS )r� z-Represent the PostgreSQL INT8MULTIRANGE type.Nr� r6 r6 r6 r7 r� � s r� c @ s e Zd ZdZd ZdS )r� z,Represent the PostgreSQL NUMMULTIRANGE type.Nr� r6 r6 r6 r7 r� � s r� c @ s e Zd ZdZd ZdS )r� z-Represent the PostgreSQL DATEMULTIRANGE type.Nr� r6 r6 r6 r7 r� � s r� c @ s e Zd ZdZd ZdS )r� r� Nr� r6 r6 r6 r7 r� � s r� c @ s e Zd ZdZd ZdS )r� r� Nr� r6 r6 r6 r7 r� � s r� i���i �z Range[int]r0 )r� r: c C sH | j d u s$t| j ko tkn oF| jd u pFt| j koBtkS S r; )r+ � _min_int_32� _max_int_32r, )r� r6 r6 r7 r� s $"�r� )H� __future__r r� r r r �decimalr �typingr r r r r r r r r r r r r r r r r r r r r r� r r� ZsqlZ sql.type_apir �utilr Z util.typingr! Z sql.elementsr" r# r$ r% r. Zdc_slotsr� Z dataclassr* r� r� rI r� r� r� rS r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r6 r6 r6 r7 �<module> s� # $ sqlalchemy/dialects/postgresql/__pycache__/base.cpython-39.pyc 0000644 00000421757 15125143220 0020467 0 ustar 00 a ��Jh�� � 3 @ s� d Z ddlmZ ddlmZ ddlmZ ddlZddlm Z ddlm Z ddlm Z dd lm Z dd lm Z dd lmZ dd lmZ dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddl m Z ddl m Z ddl m Z ddl m!Z! ddl m"Z" ddl m#Z# ddl m$Z$ dd l m%Z% dd l&m'Z' dd l&m(Z( dd l&m)Z) dd l&m*Z* dd!l&m+Z+ dd"l&m,Z, dd#l&m-Z- dd$l&m.Z. dd%l&m/Z/ dd&l&m0Z0 dd'l&m1Z1 dd(l&m2Z2 dd)l&m3Z3 dd*l&m4Z4 dd+l&m5Z5 dd,l&m6Z6 dd-l&m7Z7 dd.l&m8Z8 dd/l&m9Z9 dd0l&m:Z: dd1l&m;Z; dd2l&m<Z< dd3l&m=Z= dd4l&m>Z> dd5l&m?Z? d6d7lm@Z@ d6d8lmAZA d6d9lmBZB d6d:lmCZC d6d;lmDZD d6d<lEmFZF d6d=lEmGZG d6d>lEmHZH d6d?lEmIZI d6d@lEmJZJ d6dAlEmKZK d6dBlEmLZL d6dClMmNZN d6dDlCmOZO d6dElCmPZP d6dFlCmQZQ d6dGlCmRZR d6dHlCmSZS d6dIlCmTZT d6dJlCmUZU d6d;lCmDZV d6dKlWmXZX d6dLlYmZZZ d6dMl&m[Z[ d6dNl&m\Z\ d6dOl&m]Z] d6dPl&m^Z^ d6dQl&m_Z_ d6dRl&m`Z` d6dSl&maZa d6dTl&mbZb d6dUl&mcZc d6dVl&mdZd d6dWl&meZe d6dXl&mfZf d6dYl&mgZg d6dZlhmiZi e�jd[ejk�Zlh d\�ZmeUjnejneUjoe/eUjpe$eUjqjrejseUjqejqeUjte:iZuejne ejqejvejwejxejyejzej{ej|ej}ej~ejej�ej�ej�eae[edege]eUj�eUj�eeebe`ece.e,e-efe*e*e0e1e2e3e;e_e>e>e>e=e=e^e=e+e\e/e?d]�2Z�G d^d_� d_eQj��Z�G d`da� daeQj��Z�G dbdc� dceQj��Z�G ddde� deeQj��Z�G dfdg� dgei�Z�G dhdi� diei�Z�G djdk� dke��Z�G dldm� dme��Z�G dndo� doeKj��Z�G dpdq� dqeGj��Z�G drds� dseFj��Z�G dtdu� dueFj��Z�G dvdw� dweGj��Z�dS )xa� .. dialect:: postgresql :name: PostgreSQL :normal_support: 9.6+ :best_effort: 9+ .. _postgresql_sequences: Sequences/SERIAL/IDENTITY ------------------------- PostgreSQL supports sequences, and SQLAlchemy uses these as the default means of creating new primary key values for integer-based primary key columns. When creating tables, SQLAlchemy will issue the ``SERIAL`` datatype for integer-based primary key columns, which generates a sequence and server side default corresponding to the column. To specify a specific named sequence to be used for primary key generation, use the :func:`~sqlalchemy.schema.Sequence` construct:: Table( "sometable", metadata, Column( "id", Integer, Sequence("some_id_seq", start=1), primary_key=True ), ) When SQLAlchemy issues a single INSERT statement, to fulfill the contract of having the "last insert identifier" available, a RETURNING clause is added to the INSERT statement which specifies the primary key columns should be returned after the statement completes. The RETURNING functionality only takes place if PostgreSQL 8.2 or later is in use. As a fallback approach, the sequence, whether specified explicitly or implicitly via ``SERIAL``, is executed independently beforehand, the returned value to be used in the subsequent insert. Note that when an :func:`~sqlalchemy.sql.expression.insert()` construct is executed using "executemany" semantics, the "last inserted identifier" functionality does not apply; no RETURNING clause is emitted nor is the sequence pre-executed in this case. PostgreSQL 10 and above IDENTITY columns ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PostgreSQL 10 and above have a new IDENTITY feature that supersedes the use of SERIAL. The :class:`_schema.Identity` construct in a :class:`_schema.Column` can be used to control its behavior:: from sqlalchemy import Table, Column, MetaData, Integer, Computed metadata = MetaData() data = Table( "data", metadata, Column( "id", Integer, Identity(start=42, cycle=True), primary_key=True ), Column("data", String), ) The CREATE TABLE for the above :class:`_schema.Table` object would be: .. sourcecode:: sql CREATE TABLE data ( id INTEGER GENERATED BY DEFAULT AS IDENTITY (START WITH 42 CYCLE), data VARCHAR, PRIMARY KEY (id) ) .. versionchanged:: 1.4 Added :class:`_schema.Identity` construct in a :class:`_schema.Column` to specify the option of an autoincrementing column. .. note:: Previous versions of SQLAlchemy did not have built-in support for rendering of IDENTITY, and could use the following compilation hook to replace occurrences of SERIAL with IDENTITY:: from sqlalchemy.schema import CreateColumn from sqlalchemy.ext.compiler import compiles @compiles(CreateColumn, "postgresql") def use_identity(element, compiler, **kw): text = compiler.visit_create_column(element, **kw) text = text.replace("SERIAL", "INT GENERATED BY DEFAULT AS IDENTITY") return text Using the above, a table such as:: t = Table( "t", m, Column("id", Integer, primary_key=True), Column("data", String) ) Will generate on the backing database as: .. sourcecode:: sql CREATE TABLE t ( id INT GENERATED BY DEFAULT AS IDENTITY, data VARCHAR, PRIMARY KEY (id) ) .. _postgresql_ss_cursors: Server Side Cursors ------------------- Server-side cursor support is available for the psycopg2, asyncpg dialects and may also be available in others. Server side cursors are enabled on a per-statement basis by using the :paramref:`.Connection.execution_options.stream_results` connection execution option:: with engine.connect() as conn: result = conn.execution_options(stream_results=True).execute( text("select * from table") ) Note that some kinds of SQL statements may not be supported with server side cursors; generally, only SQL statements that return rows should be used with this option. .. deprecated:: 1.4 The dialect-level server_side_cursors flag is deprecated and will be removed in a future release. Please use the :paramref:`_engine.Connection.stream_results` execution option for unbuffered cursor support. .. seealso:: :ref:`engine_stream_results` .. _postgresql_isolation_level: Transaction Isolation Level --------------------------- Most SQLAlchemy dialects support setting of transaction isolation level using the :paramref:`_sa.create_engine.isolation_level` parameter at the :func:`_sa.create_engine` level, and at the :class:`_engine.Connection` level via the :paramref:`.Connection.execution_options.isolation_level` parameter. For PostgreSQL dialects, this feature works either by making use of the DBAPI-specific features, such as psycopg2's isolation level flags which will embed the isolation level setting inline with the ``"BEGIN"`` statement, or for DBAPIs with no direct support by emitting ``SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL <level>`` ahead of the ``"BEGIN"`` statement emitted by the DBAPI. For the special AUTOCOMMIT isolation level, DBAPI-specific techniques are used which is typically an ``.autocommit`` flag on the DBAPI connection object. To set isolation level using :func:`_sa.create_engine`:: engine = create_engine( "postgresql+pg8000://scott:tiger@localhost/test", isolation_level="REPEATABLE READ", ) To set using per-connection execution options:: with engine.connect() as conn: conn = conn.execution_options(isolation_level="REPEATABLE READ") with conn.begin(): ... # work with transaction There are also more options for isolation level configurations, such as "sub-engine" objects linked to a main :class:`_engine.Engine` which each apply different isolation level settings. See the discussion at :ref:`dbapi_autocommit` for background. Valid values for ``isolation_level`` on most PostgreSQL dialects include: * ``READ COMMITTED`` * ``READ UNCOMMITTED`` * ``REPEATABLE READ`` * ``SERIALIZABLE`` * ``AUTOCOMMIT`` .. seealso:: :ref:`dbapi_autocommit` :ref:`postgresql_readonly_deferrable` :ref:`psycopg2_isolation_level` :ref:`pg8000_isolation_level` .. _postgresql_readonly_deferrable: Setting READ ONLY / DEFERRABLE ------------------------------ Most PostgreSQL dialects support setting the "READ ONLY" and "DEFERRABLE" characteristics of the transaction, which is in addition to the isolation level setting. These two attributes can be established either in conjunction with or independently of the isolation level by passing the ``postgresql_readonly`` and ``postgresql_deferrable`` flags with :meth:`_engine.Connection.execution_options`. The example below illustrates passing the ``"SERIALIZABLE"`` isolation level at the same time as setting "READ ONLY" and "DEFERRABLE":: with engine.connect() as conn: conn = conn.execution_options( isolation_level="SERIALIZABLE", postgresql_readonly=True, postgresql_deferrable=True, ) with conn.begin(): ... # work with transaction Note that some DBAPIs such as asyncpg only support "readonly" with SERIALIZABLE isolation. .. versionadded:: 1.4 added support for the ``postgresql_readonly`` and ``postgresql_deferrable`` execution options. .. _postgresql_reset_on_return: Temporary Table / Resource Reset for Connection Pooling ------------------------------------------------------- The :class:`.QueuePool` connection pool implementation used by the SQLAlchemy :class:`.Engine` object includes :ref:`reset on return <pool_reset_on_return>` behavior that will invoke the DBAPI ``.rollback()`` method when connections are returned to the pool. While this rollback will clear out the immediate state used by the previous transaction, it does not cover a wider range of session-level state, including temporary tables as well as other server state such as prepared statement handles and statement caches. The PostgreSQL database includes a variety of commands which may be used to reset this state, including ``DISCARD``, ``RESET``, ``DEALLOCATE``, and ``UNLISTEN``. To install one or more of these commands as the means of performing reset-on-return, the :meth:`.PoolEvents.reset` event hook may be used, as demonstrated in the example below. The implementation will end transactions in progress as well as discard temporary tables using the ``CLOSE``, ``RESET`` and ``DISCARD`` commands; see the PostgreSQL documentation for background on what each of these statements do. The :paramref:`_sa.create_engine.pool_reset_on_return` parameter is set to ``None`` so that the custom scheme can replace the default behavior completely. The custom hook implementation calls ``.rollback()`` in any case, as it's usually important that the DBAPI's own tracking of commit/rollback will remain consistent with the state of the transaction:: from sqlalchemy import create_engine from sqlalchemy import event postgresql_engine = create_engine( "postgresql+psycopg2://scott:tiger@hostname/dbname", # disable default reset-on-return scheme pool_reset_on_return=None, ) @event.listens_for(postgresql_engine, "reset") def _reset_postgresql(dbapi_connection, connection_record, reset_state): if not reset_state.terminate_only: dbapi_connection.execute("CLOSE ALL") dbapi_connection.execute("RESET ALL") dbapi_connection.execute("DISCARD TEMP") # so that the DBAPI itself knows that the connection has been # reset dbapi_connection.rollback() .. versionchanged:: 2.0.0b3 Added additional state arguments to the :meth:`.PoolEvents.reset` event and additionally ensured the event is invoked for all "reset" occurrences, so that it's appropriate as a place for custom "reset" handlers. Previous schemes which use the :meth:`.PoolEvents.checkin` handler remain usable as well. .. seealso:: :ref:`pool_reset_on_return` - in the :ref:`pooling_toplevel` documentation .. _postgresql_alternate_search_path: Setting Alternate Search Paths on Connect ------------------------------------------ The PostgreSQL ``search_path`` variable refers to the list of schema names that will be implicitly referenced when a particular table or other object is referenced in a SQL statement. As detailed in the next section :ref:`postgresql_schema_reflection`, SQLAlchemy is generally organized around the concept of keeping this variable at its default value of ``public``, however, in order to have it set to any arbitrary name or names when connections are used automatically, the "SET SESSION search_path" command may be invoked for all connections in a pool using the following event handler, as discussed at :ref:`schema_set_default_connections`:: from sqlalchemy import event from sqlalchemy import create_engine engine = create_engine("postgresql+psycopg2://scott:tiger@host/dbname") @event.listens_for(engine, "connect", insert=True) def set_search_path(dbapi_connection, connection_record): existing_autocommit = dbapi_connection.autocommit dbapi_connection.autocommit = True cursor = dbapi_connection.cursor() cursor.execute("SET SESSION search_path='%s'" % schema_name) cursor.close() dbapi_connection.autocommit = existing_autocommit The reason the recipe is complicated by use of the ``.autocommit`` DBAPI attribute is so that when the ``SET SESSION search_path`` directive is invoked, it is invoked outside of the scope of any transaction and therefore will not be reverted when the DBAPI connection has a rollback. .. seealso:: :ref:`schema_set_default_connections` - in the :ref:`metadata_toplevel` documentation .. _postgresql_schema_reflection: Remote-Schema Table Introspection and PostgreSQL search_path ------------------------------------------------------------ .. admonition:: Section Best Practices Summarized keep the ``search_path`` variable set to its default of ``public``, without any other schema names. Ensure the username used to connect **does not** match remote schemas, or ensure the ``"$user"`` token is **removed** from ``search_path``. For other schema names, name these explicitly within :class:`_schema.Table` definitions. Alternatively, the ``postgresql_ignore_search_path`` option will cause all reflected :class:`_schema.Table` objects to have a :attr:`_schema.Table.schema` attribute set up. The PostgreSQL dialect can reflect tables from any schema, as outlined in :ref:`metadata_reflection_schemas`. In all cases, the first thing SQLAlchemy does when reflecting tables is to **determine the default schema for the current database connection**. It does this using the PostgreSQL ``current_schema()`` function, illustated below using a PostgreSQL client session (i.e. using the ``psql`` tool): .. sourcecode:: sql test=> select current_schema(); current_schema ---------------- public (1 row) Above we see that on a plain install of PostgreSQL, the default schema name is the name ``public``. However, if your database username **matches the name of a schema**, PostgreSQL's default is to then **use that name as the default schema**. Below, we log in using the username ``scott``. When we create a schema named ``scott``, **it implicitly changes the default schema**: .. sourcecode:: sql test=> select current_schema(); current_schema ---------------- public (1 row) test=> create schema scott; CREATE SCHEMA test=> select current_schema(); current_schema ---------------- scott (1 row) The behavior of ``current_schema()`` is derived from the `PostgreSQL search path <https://www.postgresql.org/docs/current/static/ddl-schemas.html#DDL-SCHEMAS-PATH>`_ variable ``search_path``, which in modern PostgreSQL versions defaults to this: .. sourcecode:: sql test=> show search_path; search_path ----------------- "$user", public (1 row) Where above, the ``"$user"`` variable will inject the current username as the default schema, if one exists. Otherwise, ``public`` is used. When a :class:`_schema.Table` object is reflected, if it is present in the schema indicated by the ``current_schema()`` function, **the schema name assigned to the ".schema" attribute of the Table is the Python "None" value**. Otherwise, the ".schema" attribute will be assigned the string name of that schema. With regards to tables which these :class:`_schema.Table` objects refer to via foreign key constraint, a decision must be made as to how the ``.schema`` is represented in those remote tables, in the case where that remote schema name is also a member of the current ``search_path``. By default, the PostgreSQL dialect mimics the behavior encouraged by PostgreSQL's own ``pg_get_constraintdef()`` builtin procedure. This function returns a sample definition for a particular foreign key constraint, omitting the referenced schema name from that definition when the name is also in the PostgreSQL schema search path. The interaction below illustrates this behavior: .. sourcecode:: sql test=> CREATE TABLE test_schema.referred(id INTEGER PRIMARY KEY); CREATE TABLE test=> CREATE TABLE referring( test(> id INTEGER PRIMARY KEY, test(> referred_id INTEGER REFERENCES test_schema.referred(id)); CREATE TABLE test=> SET search_path TO public, test_schema; test=> SELECT pg_catalog.pg_get_constraintdef(r.oid, true) FROM test-> pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n test-> ON n.oid = c.relnamespace test-> JOIN pg_catalog.pg_constraint r ON c.oid = r.conrelid test-> WHERE c.relname='referring' AND r.contype = 'f' test-> ; pg_get_constraintdef --------------------------------------------------- FOREIGN KEY (referred_id) REFERENCES referred(id) (1 row) Above, we created a table ``referred`` as a member of the remote schema ``test_schema``, however when we added ``test_schema`` to the PG ``search_path`` and then asked ``pg_get_constraintdef()`` for the ``FOREIGN KEY`` syntax, ``test_schema`` was not included in the output of the function. On the other hand, if we set the search path back to the typical default of ``public``: .. sourcecode:: sql test=> SET search_path TO public; SET The same query against ``pg_get_constraintdef()`` now returns the fully schema-qualified name for us: .. sourcecode:: sql test=> SELECT pg_catalog.pg_get_constraintdef(r.oid, true) FROM test-> pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n test-> ON n.oid = c.relnamespace test-> JOIN pg_catalog.pg_constraint r ON c.oid = r.conrelid test-> WHERE c.relname='referring' AND r.contype = 'f'; pg_get_constraintdef --------------------------------------------------------------- FOREIGN KEY (referred_id) REFERENCES test_schema.referred(id) (1 row) SQLAlchemy will by default use the return value of ``pg_get_constraintdef()`` in order to determine the remote schema name. That is, if our ``search_path`` were set to include ``test_schema``, and we invoked a table reflection process as follows:: >>> from sqlalchemy import Table, MetaData, create_engine, text >>> engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test") >>> with engine.connect() as conn: ... conn.execute(text("SET search_path TO test_schema, public")) ... metadata_obj = MetaData() ... referring = Table("referring", metadata_obj, autoload_with=conn) <sqlalchemy.engine.result.CursorResult object at 0x101612ed0> The above process would deliver to the :attr:`_schema.MetaData.tables` collection ``referred`` table named **without** the schema:: >>> metadata_obj.tables["referred"].schema is None True To alter the behavior of reflection such that the referred schema is maintained regardless of the ``search_path`` setting, use the ``postgresql_ignore_search_path`` option, which can be specified as a dialect-specific argument to both :class:`_schema.Table` as well as :meth:`_schema.MetaData.reflect`:: >>> with engine.connect() as conn: ... conn.execute(text("SET search_path TO test_schema, public")) ... metadata_obj = MetaData() ... referring = Table( ... "referring", ... metadata_obj, ... autoload_with=conn, ... postgresql_ignore_search_path=True, ... ) <sqlalchemy.engine.result.CursorResult object at 0x1016126d0> We will now have ``test_schema.referred`` stored as schema-qualified:: >>> metadata_obj.tables["test_schema.referred"].schema 'test_schema' .. sidebar:: Best Practices for PostgreSQL Schema reflection The description of PostgreSQL schema reflection behavior is complex, and is the product of many years of dealing with widely varied use cases and user preferences. But in fact, there's no need to understand any of it if you just stick to the simplest use pattern: leave the ``search_path`` set to its default of ``public`` only, never refer to the name ``public`` as an explicit schema name otherwise, and refer to all other schema names explicitly when building up a :class:`_schema.Table` object. The options described here are only for those users who can't, or prefer not to, stay within these guidelines. .. seealso:: :ref:`reflection_schema_qualified_interaction` - discussion of the issue from a backend-agnostic perspective `The Schema Search Path <https://www.postgresql.org/docs/current/static/ddl-schemas.html#DDL-SCHEMAS-PATH>`_ - on the PostgreSQL website. INSERT/UPDATE...RETURNING ------------------------- The dialect supports PG 8.2's ``INSERT..RETURNING``, ``UPDATE..RETURNING`` and ``DELETE..RETURNING`` syntaxes. ``INSERT..RETURNING`` is used by default for single-row INSERT statements in order to fetch newly generated primary key identifiers. To specify an explicit ``RETURNING`` clause, use the :meth:`._UpdateBase.returning` method on a per-statement basis:: # INSERT..RETURNING result = ( table.insert().returning(table.c.col1, table.c.col2).values(name="foo") ) print(result.fetchall()) # UPDATE..RETURNING result = ( table.update() .returning(table.c.col1, table.c.col2) .where(table.c.name == "foo") .values(name="bar") ) print(result.fetchall()) # DELETE..RETURNING result = ( table.delete() .returning(table.c.col1, table.c.col2) .where(table.c.name == "foo") ) print(result.fetchall()) .. _postgresql_insert_on_conflict: INSERT...ON CONFLICT (Upsert) ------------------------------ Starting with version 9.5, PostgreSQL allows "upserts" (update or insert) of rows into a table via the ``ON CONFLICT`` clause of the ``INSERT`` statement. A candidate row will only be inserted if that row does not violate any unique constraints. In the case of a unique constraint violation, a secondary action can occur which can be either "DO UPDATE", indicating that the data in the target row should be updated, or "DO NOTHING", which indicates to silently skip this row. Conflicts are determined using existing unique constraints and indexes. These constraints may be identified either using their name as stated in DDL, or they may be inferred by stating the columns and conditions that comprise the indexes. SQLAlchemy provides ``ON CONFLICT`` support via the PostgreSQL-specific :func:`_postgresql.insert()` function, which provides the generative methods :meth:`_postgresql.Insert.on_conflict_do_update` and :meth:`~.postgresql.Insert.on_conflict_do_nothing`: .. sourcecode:: pycon+sql >>> from sqlalchemy.dialects.postgresql import insert >>> insert_stmt = insert(my_table).values( ... id="some_existing_id", data="inserted value" ... ) >>> do_nothing_stmt = insert_stmt.on_conflict_do_nothing(index_elements=["id"]) >>> print(do_nothing_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (%(id)s, %(data)s) ON CONFLICT (id) DO NOTHING {stop} >>> do_update_stmt = insert_stmt.on_conflict_do_update( ... constraint="pk_my_table", set_=dict(data="updated value") ... ) >>> print(do_update_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (%(id)s, %(data)s) ON CONFLICT ON CONSTRAINT pk_my_table DO UPDATE SET data = %(param_1)s .. seealso:: `INSERT .. ON CONFLICT <https://www.postgresql.org/docs/current/static/sql-insert.html#SQL-ON-CONFLICT>`_ - in the PostgreSQL documentation. Specifying the Target ^^^^^^^^^^^^^^^^^^^^^ Both methods supply the "target" of the conflict using either the named constraint or by column inference: * The :paramref:`_postgresql.Insert.on_conflict_do_update.index_elements` argument specifies a sequence containing string column names, :class:`_schema.Column` objects, and/or SQL expression elements, which would identify a unique index: .. sourcecode:: pycon+sql >>> do_update_stmt = insert_stmt.on_conflict_do_update( ... index_elements=["id"], set_=dict(data="updated value") ... ) >>> print(do_update_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (%(id)s, %(data)s) ON CONFLICT (id) DO UPDATE SET data = %(param_1)s {stop} >>> do_update_stmt = insert_stmt.on_conflict_do_update( ... index_elements=[my_table.c.id], set_=dict(data="updated value") ... ) >>> print(do_update_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (%(id)s, %(data)s) ON CONFLICT (id) DO UPDATE SET data = %(param_1)s * When using :paramref:`_postgresql.Insert.on_conflict_do_update.index_elements` to infer an index, a partial index can be inferred by also specifying the use the :paramref:`_postgresql.Insert.on_conflict_do_update.index_where` parameter: .. sourcecode:: pycon+sql >>> stmt = insert(my_table).values(user_email="a@b.com", data="inserted data") >>> stmt = stmt.on_conflict_do_update( ... index_elements=[my_table.c.user_email], ... index_where=my_table.c.user_email.like("%@gmail.com"), ... set_=dict(data=stmt.excluded.data), ... ) >>> print(stmt) {printsql}INSERT INTO my_table (data, user_email) VALUES (%(data)s, %(user_email)s) ON CONFLICT (user_email) WHERE user_email LIKE %(user_email_1)s DO UPDATE SET data = excluded.data * The :paramref:`_postgresql.Insert.on_conflict_do_update.constraint` argument is used to specify an index directly rather than inferring it. This can be the name of a UNIQUE constraint, a PRIMARY KEY constraint, or an INDEX: .. sourcecode:: pycon+sql >>> do_update_stmt = insert_stmt.on_conflict_do_update( ... constraint="my_table_idx_1", set_=dict(data="updated value") ... ) >>> print(do_update_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (%(id)s, %(data)s) ON CONFLICT ON CONSTRAINT my_table_idx_1 DO UPDATE SET data = %(param_1)s {stop} >>> do_update_stmt = insert_stmt.on_conflict_do_update( ... constraint="my_table_pk", set_=dict(data="updated value") ... ) >>> print(do_update_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (%(id)s, %(data)s) ON CONFLICT ON CONSTRAINT my_table_pk DO UPDATE SET data = %(param_1)s {stop} * The :paramref:`_postgresql.Insert.on_conflict_do_update.constraint` argument may also refer to a SQLAlchemy construct representing a constraint, e.g. :class:`.UniqueConstraint`, :class:`.PrimaryKeyConstraint`, :class:`.Index`, or :class:`.ExcludeConstraint`. In this use, if the constraint has a name, it is used directly. Otherwise, if the constraint is unnamed, then inference will be used, where the expressions and optional WHERE clause of the constraint will be spelled out in the construct. This use is especially convenient to refer to the named or unnamed primary key of a :class:`_schema.Table` using the :attr:`_schema.Table.primary_key` attribute: .. sourcecode:: pycon+sql >>> do_update_stmt = insert_stmt.on_conflict_do_update( ... constraint=my_table.primary_key, set_=dict(data="updated value") ... ) >>> print(do_update_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (%(id)s, %(data)s) ON CONFLICT (id) DO UPDATE SET data = %(param_1)s The SET Clause ^^^^^^^^^^^^^^^ ``ON CONFLICT...DO UPDATE`` is used to perform an update of the already existing row, using any combination of new values as well as values from the proposed insertion. These values are specified using the :paramref:`_postgresql.Insert.on_conflict_do_update.set_` parameter. This parameter accepts a dictionary which consists of direct values for UPDATE: .. sourcecode:: pycon+sql >>> stmt = insert(my_table).values(id="some_id", data="inserted value") >>> do_update_stmt = stmt.on_conflict_do_update( ... index_elements=["id"], set_=dict(data="updated value") ... ) >>> print(do_update_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (%(id)s, %(data)s) ON CONFLICT (id) DO UPDATE SET data = %(param_1)s .. warning:: The :meth:`_expression.Insert.on_conflict_do_update` method does **not** take into account Python-side default UPDATE values or generation functions, e.g. those specified using :paramref:`_schema.Column.onupdate`. These values will not be exercised for an ON CONFLICT style of UPDATE, unless they are manually specified in the :paramref:`_postgresql.Insert.on_conflict_do_update.set_` dictionary. Updating using the Excluded INSERT Values ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In order to refer to the proposed insertion row, the special alias :attr:`~.postgresql.Insert.excluded` is available as an attribute on the :class:`_postgresql.Insert` object; this object is a :class:`_expression.ColumnCollection` which alias contains all columns of the target table: .. sourcecode:: pycon+sql >>> stmt = insert(my_table).values( ... id="some_id", data="inserted value", author="jlh" ... ) >>> do_update_stmt = stmt.on_conflict_do_update( ... index_elements=["id"], ... set_=dict(data="updated value", author=stmt.excluded.author), ... ) >>> print(do_update_stmt) {printsql}INSERT INTO my_table (id, data, author) VALUES (%(id)s, %(data)s, %(author)s) ON CONFLICT (id) DO UPDATE SET data = %(param_1)s, author = excluded.author Additional WHERE Criteria ^^^^^^^^^^^^^^^^^^^^^^^^^ The :meth:`_expression.Insert.on_conflict_do_update` method also accepts a WHERE clause using the :paramref:`_postgresql.Insert.on_conflict_do_update.where` parameter, which will limit those rows which receive an UPDATE: .. sourcecode:: pycon+sql >>> stmt = insert(my_table).values( ... id="some_id", data="inserted value", author="jlh" ... ) >>> on_update_stmt = stmt.on_conflict_do_update( ... index_elements=["id"], ... set_=dict(data="updated value", author=stmt.excluded.author), ... where=(my_table.c.status == 2), ... ) >>> print(on_update_stmt) {printsql}INSERT INTO my_table (id, data, author) VALUES (%(id)s, %(data)s, %(author)s) ON CONFLICT (id) DO UPDATE SET data = %(param_1)s, author = excluded.author WHERE my_table.status = %(status_1)s Skipping Rows with DO NOTHING ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``ON CONFLICT`` may be used to skip inserting a row entirely if any conflict with a unique or exclusion constraint occurs; below this is illustrated using the :meth:`~.postgresql.Insert.on_conflict_do_nothing` method: .. sourcecode:: pycon+sql >>> stmt = insert(my_table).values(id="some_id", data="inserted value") >>> stmt = stmt.on_conflict_do_nothing(index_elements=["id"]) >>> print(stmt) {printsql}INSERT INTO my_table (id, data) VALUES (%(id)s, %(data)s) ON CONFLICT (id) DO NOTHING If ``DO NOTHING`` is used without specifying any columns or constraint, it has the effect of skipping the INSERT for any unique or exclusion constraint violation which occurs: .. sourcecode:: pycon+sql >>> stmt = insert(my_table).values(id="some_id", data="inserted value") >>> stmt = stmt.on_conflict_do_nothing() >>> print(stmt) {printsql}INSERT INTO my_table (id, data) VALUES (%(id)s, %(data)s) ON CONFLICT DO NOTHING .. _postgresql_match: Full Text Search ---------------- PostgreSQL's full text search system is available through the use of the :data:`.func` namespace, combined with the use of custom operators via the :meth:`.Operators.bool_op` method. For simple cases with some degree of cross-backend compatibility, the :meth:`.Operators.match` operator may also be used. .. _postgresql_simple_match: Simple plain text matching with ``match()`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The :meth:`.Operators.match` operator provides for cross-compatible simple text matching. For the PostgreSQL backend, it's hardcoded to generate an expression using the ``@@`` operator in conjunction with the ``plainto_tsquery()`` PostgreSQL function. On the PostgreSQL dialect, an expression like the following:: select(sometable.c.text.match("search string")) would emit to the database: .. sourcecode:: sql SELECT text @@ plainto_tsquery('search string') FROM table Above, passing a plain string to :meth:`.Operators.match` will automatically make use of ``plainto_tsquery()`` to specify the type of tsquery. This establishes basic database cross-compatibility for :meth:`.Operators.match` with other backends. .. versionchanged:: 2.0 The default tsquery generation function used by the PostgreSQL dialect with :meth:`.Operators.match` is ``plainto_tsquery()``. To render exactly what was rendered in 1.4, use the following form:: from sqlalchemy import func select(sometable.c.text.bool_op("@@")(func.to_tsquery("search string"))) Which would emit: .. sourcecode:: sql SELECT text @@ to_tsquery('search string') FROM table Using PostgreSQL full text functions and operators directly ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Text search operations beyond the simple use of :meth:`.Operators.match` may make use of the :data:`.func` namespace to generate PostgreSQL full-text functions, in combination with :meth:`.Operators.bool_op` to generate any boolean operator. For example, the query:: select(func.to_tsquery("cat").bool_op("@>")(func.to_tsquery("cat & rat"))) would generate: .. sourcecode:: sql SELECT to_tsquery('cat') @> to_tsquery('cat & rat') The :class:`_postgresql.TSVECTOR` type can provide for explicit CAST:: from sqlalchemy.dialects.postgresql import TSVECTOR from sqlalchemy import select, cast select(cast("some text", TSVECTOR)) produces a statement equivalent to: .. sourcecode:: sql SELECT CAST('some text' AS TSVECTOR) AS anon_1 The ``func`` namespace is augmented by the PostgreSQL dialect to set up correct argument and return types for most full text search functions. These functions are used automatically by the :attr:`_sql.func` namespace assuming the ``sqlalchemy.dialects.postgresql`` package has been imported, or :func:`_sa.create_engine` has been invoked using a ``postgresql`` dialect. These functions are documented at: * :class:`_postgresql.to_tsvector` * :class:`_postgresql.to_tsquery` * :class:`_postgresql.plainto_tsquery` * :class:`_postgresql.phraseto_tsquery` * :class:`_postgresql.websearch_to_tsquery` * :class:`_postgresql.ts_headline` Specifying the "regconfig" with ``match()`` or custom operators ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PostgreSQL's ``plainto_tsquery()`` function accepts an optional "regconfig" argument that is used to instruct PostgreSQL to use a particular pre-computed GIN or GiST index in order to perform the search. When using :meth:`.Operators.match`, this additional parameter may be specified using the ``postgresql_regconfig`` parameter, such as:: select(mytable.c.id).where( mytable.c.title.match("somestring", postgresql_regconfig="english") ) Which would emit: .. sourcecode:: sql SELECT mytable.id FROM mytable WHERE mytable.title @@ plainto_tsquery('english', 'somestring') When using other PostgreSQL search functions with :data:`.func`, the "regconfig" parameter may be passed directly as the initial argument:: select(mytable.c.id).where( func.to_tsvector("english", mytable.c.title).bool_op("@@")( func.to_tsquery("english", "somestring") ) ) produces a statement equivalent to: .. sourcecode:: sql SELECT mytable.id FROM mytable WHERE to_tsvector('english', mytable.title) @@ to_tsquery('english', 'somestring') It is recommended that you use the ``EXPLAIN ANALYZE...`` tool from PostgreSQL to ensure that you are generating queries with SQLAlchemy that take full advantage of any indexes you may have created for full text search. .. seealso:: `Full Text Search <https://www.postgresql.org/docs/current/textsearch-controls.html>`_ - in the PostgreSQL documentation FROM ONLY ... ------------- The dialect supports PostgreSQL's ONLY keyword for targeting only a particular table in an inheritance hierarchy. This can be used to produce the ``SELECT ... FROM ONLY``, ``UPDATE ONLY ...``, and ``DELETE FROM ONLY ...`` syntaxes. It uses SQLAlchemy's hints mechanism:: # SELECT ... FROM ONLY ... result = table.select().with_hint(table, "ONLY", "postgresql") print(result.fetchall()) # UPDATE ONLY ... table.update(values=dict(foo="bar")).with_hint( "ONLY", dialect_name="postgresql" ) # DELETE FROM ONLY ... table.delete().with_hint("ONLY", dialect_name="postgresql") .. _postgresql_indexes: PostgreSQL-Specific Index Options --------------------------------- Several extensions to the :class:`.Index` construct are available, specific to the PostgreSQL dialect. .. _postgresql_covering_indexes: Covering Indexes ^^^^^^^^^^^^^^^^ The ``postgresql_include`` option renders INCLUDE(colname) for the given string names:: Index("my_index", table.c.x, postgresql_include=["y"]) would render the index as ``CREATE INDEX my_index ON table (x) INCLUDE (y)`` Note that this feature requires PostgreSQL 11 or later. .. seealso:: :ref:`postgresql_constraint_options` .. versionadded:: 1.4 .. _postgresql_partial_indexes: Partial Indexes ^^^^^^^^^^^^^^^ Partial indexes add criterion to the index definition so that the index is applied to a subset of rows. These can be specified on :class:`.Index` using the ``postgresql_where`` keyword argument:: Index("my_index", my_table.c.id, postgresql_where=my_table.c.value > 10) .. _postgresql_operator_classes: Operator Classes ^^^^^^^^^^^^^^^^ PostgreSQL allows the specification of an *operator class* for each column of an index (see https://www.postgresql.org/docs/current/interactive/indexes-opclass.html). The :class:`.Index` construct allows these to be specified via the ``postgresql_ops`` keyword argument:: Index( "my_index", my_table.c.id, my_table.c.data, postgresql_ops={"data": "text_pattern_ops", "id": "int4_ops"}, ) Note that the keys in the ``postgresql_ops`` dictionaries are the "key" name of the :class:`_schema.Column`, i.e. the name used to access it from the ``.c`` collection of :class:`_schema.Table`, which can be configured to be different than the actual name of the column as expressed in the database. If ``postgresql_ops`` is to be used against a complex SQL expression such as a function call, then to apply to the column it must be given a label that is identified in the dictionary by name, e.g.:: Index( "my_index", my_table.c.id, func.lower(my_table.c.data).label("data_lower"), postgresql_ops={"data_lower": "text_pattern_ops", "id": "int4_ops"}, ) Operator classes are also supported by the :class:`_postgresql.ExcludeConstraint` construct using the :paramref:`_postgresql.ExcludeConstraint.ops` parameter. See that parameter for details. .. versionadded:: 1.3.21 added support for operator classes with :class:`_postgresql.ExcludeConstraint`. Index Types ^^^^^^^^^^^ PostgreSQL provides several index types: B-Tree, Hash, GiST, and GIN, as well as the ability for users to create their own (see https://www.postgresql.org/docs/current/static/indexes-types.html). These can be specified on :class:`.Index` using the ``postgresql_using`` keyword argument:: Index("my_index", my_table.c.data, postgresql_using="gin") The value passed to the keyword argument will be simply passed through to the underlying CREATE INDEX command, so it *must* be a valid index type for your version of PostgreSQL. .. _postgresql_index_storage: Index Storage Parameters ^^^^^^^^^^^^^^^^^^^^^^^^ PostgreSQL allows storage parameters to be set on indexes. The storage parameters available depend on the index method used by the index. Storage parameters can be specified on :class:`.Index` using the ``postgresql_with`` keyword argument:: Index("my_index", my_table.c.data, postgresql_with={"fillfactor": 50}) PostgreSQL allows to define the tablespace in which to create the index. The tablespace can be specified on :class:`.Index` using the ``postgresql_tablespace`` keyword argument:: Index("my_index", my_table.c.data, postgresql_tablespace="my_tablespace") Note that the same option is available on :class:`_schema.Table` as well. .. _postgresql_index_concurrently: Indexes with CONCURRENTLY ^^^^^^^^^^^^^^^^^^^^^^^^^ The PostgreSQL index option CONCURRENTLY is supported by passing the flag ``postgresql_concurrently`` to the :class:`.Index` construct:: tbl = Table("testtbl", m, Column("data", Integer)) idx1 = Index("test_idx1", tbl.c.data, postgresql_concurrently=True) The above index construct will render DDL for CREATE INDEX, assuming PostgreSQL 8.2 or higher is detected or for a connection-less dialect, as: .. sourcecode:: sql CREATE INDEX CONCURRENTLY test_idx1 ON testtbl (data) For DROP INDEX, assuming PostgreSQL 9.2 or higher is detected or for a connection-less dialect, it will emit: .. sourcecode:: sql DROP INDEX CONCURRENTLY test_idx1 When using CONCURRENTLY, the PostgreSQL database requires that the statement be invoked outside of a transaction block. The Python DBAPI enforces that even for a single statement, a transaction is present, so to use this construct, the DBAPI's "autocommit" mode must be used:: metadata = MetaData() table = Table("foo", metadata, Column("id", String)) index = Index("foo_idx", table.c.id, postgresql_concurrently=True) with engine.connect() as conn: with conn.execution_options(isolation_level="AUTOCOMMIT"): table.create(conn) .. seealso:: :ref:`postgresql_isolation_level` .. _postgresql_index_reflection: PostgreSQL Index Reflection --------------------------- The PostgreSQL database creates a UNIQUE INDEX implicitly whenever the UNIQUE CONSTRAINT construct is used. When inspecting a table using :class:`_reflection.Inspector`, the :meth:`_reflection.Inspector.get_indexes` and the :meth:`_reflection.Inspector.get_unique_constraints` will report on these two constructs distinctly; in the case of the index, the key ``duplicates_constraint`` will be present in the index entry if it is detected as mirroring a constraint. When performing reflection using ``Table(..., autoload_with=engine)``, the UNIQUE INDEX is **not** returned in :attr:`_schema.Table.indexes` when it is detected as mirroring a :class:`.UniqueConstraint` in the :attr:`_schema.Table.constraints` collection . Special Reflection Options -------------------------- The :class:`_reflection.Inspector` used for the PostgreSQL backend is an instance of :class:`.PGInspector`, which offers additional methods:: from sqlalchemy import create_engine, inspect engine = create_engine("postgresql+psycopg2://localhost/test") insp = inspect(engine) # will be a PGInspector print(insp.get_enums()) .. autoclass:: PGInspector :members: .. _postgresql_table_options: PostgreSQL Table Options ------------------------ Several options for CREATE TABLE are supported directly by the PostgreSQL dialect in conjunction with the :class:`_schema.Table` construct: * ``INHERITS``:: Table("some_table", metadata, ..., postgresql_inherits="some_supertable") Table("some_table", metadata, ..., postgresql_inherits=("t1", "t2", ...)) * ``ON COMMIT``:: Table("some_table", metadata, ..., postgresql_on_commit="PRESERVE ROWS") * ``PARTITION BY``:: Table( "some_table", metadata, ..., postgresql_partition_by="LIST (part_column)", ) .. versionadded:: 1.2.6 * ``TABLESPACE``:: Table("some_table", metadata, ..., postgresql_tablespace="some_tablespace") The above option is also available on the :class:`.Index` construct. * ``USING``:: Table("some_table", metadata, ..., postgresql_using="heap") .. versionadded:: 2.0.26 * ``WITH OIDS``:: Table("some_table", metadata, ..., postgresql_with_oids=True) * ``WITHOUT OIDS``:: Table("some_table", metadata, ..., postgresql_with_oids=False) .. seealso:: `PostgreSQL CREATE TABLE options <https://www.postgresql.org/docs/current/static/sql-createtable.html>`_ - in the PostgreSQL documentation. .. _postgresql_constraint_options: PostgreSQL Constraint Options ----------------------------- The following option(s) are supported by the PostgreSQL dialect in conjunction with selected constraint constructs: * ``NOT VALID``: This option applies towards CHECK and FOREIGN KEY constraints when the constraint is being added to an existing table via ALTER TABLE, and has the effect that existing rows are not scanned during the ALTER operation against the constraint being added. When using a SQL migration tool such as `Alembic <https://alembic.sqlalchemy.org>`_ that renders ALTER TABLE constructs, the ``postgresql_not_valid`` argument may be specified as an additional keyword argument within the operation that creates the constraint, as in the following Alembic example:: def update(): op.create_foreign_key( "fk_user_address", "address", "user", ["user_id"], ["id"], postgresql_not_valid=True, ) The keyword is ultimately accepted directly by the :class:`_schema.CheckConstraint`, :class:`_schema.ForeignKeyConstraint` and :class:`_schema.ForeignKey` constructs; when using a tool like Alembic, dialect-specific keyword arguments are passed through to these constructs from the migration operation directives:: CheckConstraint("some_field IS NOT NULL", postgresql_not_valid=True) ForeignKeyConstraint( ["some_id"], ["some_table.some_id"], postgresql_not_valid=True ) .. versionadded:: 1.4.32 .. seealso:: `PostgreSQL ALTER TABLE options <https://www.postgresql.org/docs/current/static/sql-altertable.html>`_ - in the PostgreSQL documentation. * ``INCLUDE``: This option adds one or more columns as a "payload" to the unique index created automatically by PostgreSQL for the constraint. For example, the following table definition:: Table( "mytable", metadata, Column("id", Integer, nullable=False), Column("value", Integer, nullable=False), UniqueConstraint("id", postgresql_include=["value"]), ) would produce the DDL statement .. sourcecode:: sql CREATE TABLE mytable ( id INTEGER NOT NULL, value INTEGER NOT NULL, UNIQUE (id) INCLUDE (value) ) Note that this feature requires PostgreSQL 11 or later. .. versionadded:: 2.0.41 .. seealso:: :ref:`postgresql_covering_indexes` .. seealso:: `PostgreSQL CREATE TABLE options <https://www.postgresql.org/docs/current/static/sql-createtable.html>`_ - in the PostgreSQL documentation. * Column list with foreign key ``ON DELETE SET`` actions: This applies to :class:`.ForeignKey` and :class:`.ForeignKeyConstraint`, the :paramref:`.ForeignKey.ondelete` parameter will accept on the PostgreSQL backend only a string list of column names inside parenthesis, following the ``SET NULL`` or ``SET DEFAULT`` phrases, which will limit the set of columns that are subject to the action:: fktable = Table( "fktable", metadata, Column("tid", Integer), Column("id", Integer), Column("fk_id_del_set_null", Integer), ForeignKeyConstraint( columns=["tid", "fk_id_del_set_null"], refcolumns=[pktable.c.tid, pktable.c.id], ondelete="SET NULL (fk_id_del_set_null)", ), ) .. versionadded:: 2.0.40 .. _postgresql_table_valued_overview: Table values, Table and Column valued functions, Row and Tuple objects ----------------------------------------------------------------------- PostgreSQL makes great use of modern SQL forms such as table-valued functions, tables and rows as values. These constructs are commonly used as part of PostgreSQL's support for complex datatypes such as JSON, ARRAY, and other datatypes. SQLAlchemy's SQL expression language has native support for most table-valued and row-valued forms. .. _postgresql_table_valued: Table-Valued Functions ^^^^^^^^^^^^^^^^^^^^^^^ Many PostgreSQL built-in functions are intended to be used in the FROM clause of a SELECT statement, and are capable of returning table rows or sets of table rows. A large portion of PostgreSQL's JSON functions for example such as ``json_array_elements()``, ``json_object_keys()``, ``json_each_text()``, ``json_each()``, ``json_to_record()``, ``json_populate_recordset()`` use such forms. These classes of SQL function calling forms in SQLAlchemy are available using the :meth:`_functions.FunctionElement.table_valued` method in conjunction with :class:`_functions.Function` objects generated from the :data:`_sql.func` namespace. Examples from PostgreSQL's reference documentation follow below: * ``json_each()``: .. sourcecode:: pycon+sql >>> from sqlalchemy import select, func >>> stmt = select( ... func.json_each('{"a":"foo", "b":"bar"}').table_valued("key", "value") ... ) >>> print(stmt) {printsql}SELECT anon_1.key, anon_1.value FROM json_each(:json_each_1) AS anon_1 * ``json_populate_record()``: .. sourcecode:: pycon+sql >>> from sqlalchemy import select, func, literal_column >>> stmt = select( ... func.json_populate_record( ... literal_column("null::myrowtype"), '{"a":1,"b":2}' ... ).table_valued("a", "b", name="x") ... ) >>> print(stmt) {printsql}SELECT x.a, x.b FROM json_populate_record(null::myrowtype, :json_populate_record_1) AS x * ``json_to_record()`` - this form uses a PostgreSQL specific form of derived columns in the alias, where we may make use of :func:`_sql.column` elements with types to produce them. The :meth:`_functions.FunctionElement.table_valued` method produces a :class:`_sql.TableValuedAlias` construct, and the method :meth:`_sql.TableValuedAlias.render_derived` method sets up the derived columns specification: .. sourcecode:: pycon+sql >>> from sqlalchemy import select, func, column, Integer, Text >>> stmt = select( ... func.json_to_record('{"a":1,"b":[1,2,3],"c":"bar"}') ... .table_valued( ... column("a", Integer), ... column("b", Text), ... column("d", Text), ... ) ... .render_derived(name="x", with_types=True) ... ) >>> print(stmt) {printsql}SELECT x.a, x.b, x.d FROM json_to_record(:json_to_record_1) AS x(a INTEGER, b TEXT, d TEXT) * ``WITH ORDINALITY`` - part of the SQL standard, ``WITH ORDINALITY`` adds an ordinal counter to the output of a function and is accepted by a limited set of PostgreSQL functions including ``unnest()`` and ``generate_series()``. The :meth:`_functions.FunctionElement.table_valued` method accepts a keyword parameter ``with_ordinality`` for this purpose, which accepts the string name that will be applied to the "ordinality" column: .. sourcecode:: pycon+sql >>> from sqlalchemy import select, func >>> stmt = select( ... func.generate_series(4, 1, -1) ... .table_valued("value", with_ordinality="ordinality") ... .render_derived() ... ) >>> print(stmt) {printsql}SELECT anon_1.value, anon_1.ordinality FROM generate_series(:generate_series_1, :generate_series_2, :generate_series_3) WITH ORDINALITY AS anon_1(value, ordinality) .. versionadded:: 1.4.0b2 .. seealso:: :ref:`tutorial_functions_table_valued` - in the :ref:`unified_tutorial` .. _postgresql_column_valued: Column Valued Functions ^^^^^^^^^^^^^^^^^^^^^^^ Similar to the table valued function, a column valued function is present in the FROM clause, but delivers itself to the columns clause as a single scalar value. PostgreSQL functions such as ``json_array_elements()``, ``unnest()`` and ``generate_series()`` may use this form. Column valued functions are available using the :meth:`_functions.FunctionElement.column_valued` method of :class:`_functions.FunctionElement`: * ``json_array_elements()``: .. sourcecode:: pycon+sql >>> from sqlalchemy import select, func >>> stmt = select( ... func.json_array_elements('["one", "two"]').column_valued("x") ... ) >>> print(stmt) {printsql}SELECT x FROM json_array_elements(:json_array_elements_1) AS x * ``unnest()`` - in order to generate a PostgreSQL ARRAY literal, the :func:`_postgresql.array` construct may be used: .. sourcecode:: pycon+sql >>> from sqlalchemy.dialects.postgresql import array >>> from sqlalchemy import select, func >>> stmt = select(func.unnest(array([1, 2])).column_valued()) >>> print(stmt) {printsql}SELECT anon_1 FROM unnest(ARRAY[%(param_1)s, %(param_2)s]) AS anon_1 The function can of course be used against an existing table-bound column that's of type :class:`_types.ARRAY`: .. sourcecode:: pycon+sql >>> from sqlalchemy import table, column, ARRAY, Integer >>> from sqlalchemy import select, func >>> t = table("t", column("value", ARRAY(Integer))) >>> stmt = select(func.unnest(t.c.value).column_valued("unnested_value")) >>> print(stmt) {printsql}SELECT unnested_value FROM unnest(t.value) AS unnested_value .. seealso:: :ref:`tutorial_functions_column_valued` - in the :ref:`unified_tutorial` Row Types ^^^^^^^^^ Built-in support for rendering a ``ROW`` may be approximated using ``func.ROW`` with the :attr:`_sa.func` namespace, or by using the :func:`_sql.tuple_` construct: .. sourcecode:: pycon+sql >>> from sqlalchemy import table, column, func, tuple_ >>> t = table("t", column("id"), column("fk")) >>> stmt = ( ... t.select() ... .where(tuple_(t.c.id, t.c.fk) > (1, 2)) ... .where(func.ROW(t.c.id, t.c.fk) < func.ROW(3, 7)) ... ) >>> print(stmt) {printsql}SELECT t.id, t.fk FROM t WHERE (t.id, t.fk) > (:param_1, :param_2) AND ROW(t.id, t.fk) < ROW(:ROW_1, :ROW_2) .. seealso:: `PostgreSQL Row Constructors <https://www.postgresql.org/docs/current/sql-expressions.html#SQL-SYNTAX-ROW-CONSTRUCTORS>`_ `PostgreSQL Row Constructor Comparison <https://www.postgresql.org/docs/current/functions-comparisons.html#ROW-WISE-COMPARISON>`_ Table Types passed to Functions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PostgreSQL supports passing a table as an argument to a function, which is known as a "record" type. SQLAlchemy :class:`_sql.FromClause` objects such as :class:`_schema.Table` support this special form using the :meth:`_sql.FromClause.table_valued` method, which is comparable to the :meth:`_functions.FunctionElement.table_valued` method except that the collection of columns is already established by that of the :class:`_sql.FromClause` itself: .. sourcecode:: pycon+sql >>> from sqlalchemy import table, column, func, select >>> a = table("a", column("id"), column("x"), column("y")) >>> stmt = select(func.row_to_json(a.table_valued())) >>> print(stmt) {printsql}SELECT row_to_json(a) AS row_to_json_1 FROM a .. versionadded:: 1.4.0b2 � )� annotations)� defaultdict)� lru_cacheN)�Any)�cast)�Dict)�List)�Optional)�Tuple)� TYPE_CHECKING)�Union� )�arraylib)�json)� pg_catalog)�ranges)� _regconfig_fn)�aggregate_order_by)�HSTORE)�CreateDomainType)�CreateEnumType)�DOMAIN)�DropDomainType)� DropEnumType)�ENUM)� NamedType)�_DECIMAL_TYPES)� _FLOAT_TYPES)� _INT_TYPES)�BIT)�BYTEA)�CIDR)�CITEXT)�INET)�INTERVAL)�MACADDR)�MACADDR8)�MONEY)�OID)�PGBit)�PGCidr)�PGInet)� PGInterval)� PGMacAddr)� PGMacAddr8)�PGUuid)�REGCLASS)� REGCONFIG)�TIME)� TIMESTAMP)�TSVECTOR� )�exc)�schema)�select)�sql)�util)�characteristics)�default)� interfaces)� ObjectKind)� ObjectScope)� reflection)�URL)�ReflectionDefaults)� bindparam)� coercions)�compiler)�elements)� expression)�roles)�sqltypes)� InsertmanyvaluesSentinelOpts)�InternalTraversal)�BIGINT)�BOOLEAN)�CHAR)�DATE)�DOUBLE_PRECISION)�FLOAT)�INTEGER)�NUMERIC)�REAL)�SMALLINT)�TEXT)�UUID)�VARCHAR)� TypedDictz ^(?:btree|hash|gist|gin|[\w_]+)$>f �union�oldZanalyzeZ current_userZdistinct�groupZ asymmetricZvariadicZgrantZ session_user�binary�withZcurrent_catalog�do�end�orZlocaltimestamp�is�descZ references� localtimeZover�checkZforeign�null�createZwindowZhaving�where�verbose�user�anyZcollateZanalyseZascZplacing�join�new�to�inner�left�offsetZ current_role�array�columnZbetweenZthenr r< ZilikeZcross�else�as� initially�full�using� constraint�right�overlapsZtrailingZ current_date�for�uniqueZ intersect�tableZcurrent_timestampZinto�fetchZ symmetric�when�order�off� deferrable�exceptZnaturalZ returning�and� authorization�of�true�from�freeze�outerZsome�limit� current_timeZisnull�onZbothZsimilar�leading�like�falser8 Zprimary�onlyZcurrent_schema�case�allZnotnull�not�in)2�_array�hstorer ZjsonbZ int4rangeZ int8rangeZnumrangeZ daterangeZtsrangeZ tstzrangeZint4multirangeZint8multirangeZ nummultirangeZdatemultirangeZ tsmultirangeZtstzmultirange�integerZbigintZsmallintzcharacter varying� characterz"char"�name�text�numeric�float�realZinetZcidrZcitext�uuid�bit� bit varyingZmacaddrZmacaddr8Zmoney�oidZregclass�double precision� timestamp�timestamp with time zone�timestamp without time zone�time with time zone�time without time zone�date�timeZbytea�boolean�intervalZtsvectorc sH e Zd Zdd� Zdd� Zdd� Zdd� Zd d � Zd d � Zd d� Z dd� Z dd� Z dd� Z dd� Z dNdd�ZdOdd�Zd d � Zd d � Zd d!� Zd"d#� Zd$d%� Zd&d'� Zd(d)� Zd*d+� Zd,d-� Zd.d/� Zd0d1� Z� fd2d3�Zd4d5� Z d6d7� Z d8d9� Z d:d;� Z d<d=� Z d>d?� Z!d@dA� Z"dBdC� Z#dDdE� Z$dFdG� Z%dHdI� Z&dJdK� Z'dLdM� Z(� Z)S )P� PGCompilerc K s | j |fi |��S �N��_assert_pg_ts_ext��self�element�kw� r� �X/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/postgresql/base.py�visit_to_tsvector_func s z!PGCompiler.visit_to_tsvector_funcc K s | j |fi |��S r� r� r� r� r� r� �visit_to_tsquery_func s z PGCompiler.visit_to_tsquery_funcc K s | j |fi |��S r� r� r� r� r� r� �visit_plainto_tsquery_func s z%PGCompiler.visit_plainto_tsquery_funcc K s | j |fi |��S r� r� r� r� r� r� �visit_phraseto_tsquery_func s z&PGCompiler.visit_phraseto_tsquery_funcc K s | j |fi |��S r� r� r� r� r� r� � visit_websearch_to_tsquery_func s z*PGCompiler.visit_websearch_to_tsquery_funcc K s | j |fi |��S r� r� r� r� r� r� �visit_ts_headline_func s z!PGCompiler.visit_ts_headline_funcc K sB t |t�s&t�d|j� d|j� d���|j� | j|fi |��� �S )NzCan't compile "z�()" full text search function construct that does not originate from the "sqlalchemy.dialects.postgresql" package. Please ensure "import sqlalchemy.dialects.postgresql" is called before constructing "sqlalchemy.func.zD()" to ensure registration of the correct argument and return types.)� isinstancer r6 � CompileErrorr� �function_argspecr� r� r� r� r� ! s �� z PGCompiler._assert_pg_ts_extc C s6 |j tju r|jrtj}|� d| jjj|| jd�� �S )Nz::)�identifier_preparer) �_type_affinityrI �String�length� STRINGTYPE�dialect�type_compiler_instance�process�preparer)r� �type_Z dbapi_type�sqltextr� r� r� �render_bind_cast6 s ��zPGCompiler.render_bind_castc K s8 |j s"|jjjs"d|j�| j� S d| j|fi |�� S )Nz ARRAY[]::%sz ARRAY[%s])�clauses�type� item_type�_isnull�compiler� Zvisit_clauselistr� r� r� r� � visit_arrayA s zPGCompiler.visit_arrayc K s, d| j |jfi |��| j |jfi |��f S )Nz%s:%s)r� �start�stopr� r� r� r� � visit_sliceF s �zPGCompiler.visit_slicec K s | j |dfi |��S )Nz # )�_generate_generic_binary�r� r] �operatorr� r� r� r� �visit_bitwise_xor_op_binaryL s z&PGCompiler.visit_bitwise_xor_op_binaryFc K sZ |s6|j jtjur6d|d< | jt�||j �fi |��S d|d< | j||sLdndfi |��S )NT� _cast_applied�eager_groupingz -> z ->> �r� r� rI �JSONr� r9 r r� �r� r] r� r� r� r� r� r� � visit_json_getitem_op_binaryO s � � ��z'PGCompiler.visit_json_getitem_op_binaryc K sZ |s6|j jtjur6d|d< | jt�||j �fi |��S d|d< | j||sLdndfi |��S )NTr� r� z #> z #>> r� r� r� r� r� �!visit_json_path_getitem_op_binary_ s � � ��z,PGCompiler.visit_json_path_getitem_op_binaryc K s, d| j |jfi |��| j |jfi |��f S )Nz%s[%s])r� rp rz r� r� r� r� �visit_getitem_binaryn s �z PGCompiler.visit_getitem_binaryc K s, d| j |jfi |��| j |jfi |��f S )Nz%s ORDER BY %s)r� �target�order_byr� r� r� r� �visit_aggregate_order_byt s �z#PGCompiler.visit_aggregate_order_byc K s| d|j v rP| �|j d tj�}|rPd| j|jfi |��|| j|jfi |��f S d| j|jfi |��| j|jfi |��f S )NZpostgresql_regconfigz %s @@ plainto_tsquery(%s, %s)z%s @@ plainto_tsquery(%s))� modifiers�render_literal_valuerI r� r� rp rz )r� r] r� r� Z regconfigr� r� r� �visit_match_op_binaryz s ���z PGCompiler.visit_match_op_binaryc K s |j j| fi |��S r� )r� �_compiler_dispatchr� r� r� r� �$visit_ilike_case_insensitive_operand� s z/PGCompiler.visit_ilike_case_insensitive_operandc K sX |j �dd �}d| j|jfi |��| j|jfi |��f |d urRd| �|tj� nd S )N�escapez %s ILIKE %s� ESCAPE � �r� �getr� rp rz r� rI r� �r� r] r� r� r� r� r� r� �visit_ilike_op_binary� s ���z PGCompiler.visit_ilike_op_binaryc K sX |j �dd �}d| j|jfi |��| j|jfi |��f |d urRd| �|tj� nd S )Nr� z%s NOT ILIKE %sr� r� r� r� r� r� r� �visit_not_ilike_op_binary� s ���z$PGCompiler.visit_not_ilike_op_binaryc C s� |j d }|d u r*| j|d| fi |��S |dkrJ| j|d| fi |��S d| j|jfi |��|| �|tj�| j|jfi |��f S )N�flagsz %s �iz %s* z %s %s CONCAT('(?', %s, ')', %s))r� r� r� rp r� rI r� rz )r� Zbase_opr] r� r� r� r� r� r� � _regexp_match� s& ���� �zPGCompiler._regexp_matchc K s | � d|||�S )N�~�r� r� r� r� r� � visit_regexp_match_op_binary� s z'PGCompiler.visit_regexp_match_op_binaryc K s | � d|||�S )Nz!~r� r� r� r� r� � visit_not_regexp_match_op_binary� s z+PGCompiler.visit_not_regexp_match_op_binaryc K sb | j |jfi |��}| j |jfi |��}|jd }|d u rFd||f S d||| �|tj�f S d S )Nr� zREGEXP_REPLACE(%s, %s)zREGEXP_REPLACE(%s, %s, %s))r� rp rz r� r� rI r� )r� r] r� r� �stringZpattern_replacer� r� r� r� � visit_regexp_replace_op_binary� s � �z)PGCompiler.visit_regexp_replace_op_binaryc s& dd� � fdd�|pt� gD ��f S )NzSELECT %s WHERE 1!=1�, c 3 s, | ]$}d � j j�|jr t� n|� V qdS )zCAST(NULL AS %s)N)r� r� r� r� rR )�.0r� �r� r� r� � <genexpr>� s ���z2PGCompiler.visit_empty_set_expr.<locals>.<genexpr>)rl rR )r� Z element_typesr� r� r� r� �visit_empty_set_expr� s ��z PGCompiler.visit_empty_set_exprc s& t � �||�}| jjr"|�dd�}|S )N�\z\\)�superr� r� �_backslash_escapes�replace)r� �valuer� �� __class__r� r� r� � s z PGCompiler.render_literal_valuec K s d| � |� S )Nz string_agg%s)r� )r� �fnr� r� r� r� � visit_aggregate_strings_func� s z'PGCompiler.visit_aggregate_strings_funcc K s d| j �|� S )Nz nextval('%s'))r� �format_sequence)r� �seqr� r� r� r� �visit_sequence� s zPGCompiler.visit_sequencec K sf d}|j d ur*|d| j|j fi |�� 7 }|jd urb|j d u rF|d7 }|d| j|jfi |�� 7 }|S )Nr� z LIMIT z LIMIT ALLz OFFSET )Z _limit_clauser� �_offset_clause�r� r8 r� r� r� r� r� � limit_clause� s zPGCompiler.limit_clausec C s" |� � dkrt�d| ��d| S )N�ONLYzUnrecognized hint: %rzONLY )�upperr6 r� )r� r� r~ �hintZiscrudr� r� r� �format_from_hint_text� s z PGCompiler.format_from_hint_textc sD |j s |jr<|jr6dd�� �fdd�|jD �� d S dS ndS d S )Nz DISTINCT ON (r� c s g | ]}�j |fi � ���qS r� �r� �r� �col�r� r� r� r� � <listcomp>� s �z4PGCompiler.get_select_precolumns.<locals>.<listcomp>z) z DISTINCT r� )Z _distinctZ _distinct_onrl )r� r8 r� r� r r� �get_select_precolumns� s ����� z PGCompiler.get_select_precolumnsc s� |j jr |j jrd}q.d}n|j jr*d}nd}|j jr�t�� }|j jD ]}|�t�|�� qFt |�� � jddd� |dd � � �fd d �|D �� 7 }|j j r�|d 7 }|j j r�|d 7 }|S )Nz FOR KEY SHAREz FOR SHAREz FOR NO KEY UPDATEz FOR UPDATETF)Zashint� use_schemaz OF r� c 3 s | ]}�j |fi � ��V qd S r� r )r� r~ �Zof_kwr� r� r� r� s z/PGCompiler.for_update_clause.<locals>.<genexpr>z NOWAITz SKIP LOCKED) Z_for_update_arg�readZ key_sharer� r: Z OrderedSet�update�sql_utilZsurface_selectables_only�dictrl ZnowaitZ skip_locked)r� r8 r� �tmpZtables�cr� r r� �for_update_clause s* � z PGCompiler.for_update_clausec K s| | j |jjd fi |��}| j |jjd fi |��}t|jj�dkrl| j |jjd fi |��}d|||f S d||f S d S )Nr r � z SUBSTRING(%s FROM %s FOR %s)zSUBSTRING(%s FROM %s))r� r� �len)r� �funcr� �sr� r� r� r� r� �visit_substring_func& s z PGCompiler.visit_substring_funcc st |j d ur d� j�|j � }nR|jd urldd�� fdd�|jD �� }|jd urp|d� j|jddd� 7 }nd }|S ) NzON CONSTRAINT %s�(%s)r� c 3 s4 | ],}t |t�r � j�|�n� j|d d d�V qdS )F�� include_tabler N)r� �strr� �quoter� �r� r r� r� r� r� = s ��z1PGCompiler._on_conflict_target.<locals>.<genexpr>� WHERE %sFr( r� )Zconstraint_targetr� �#truncate_and_render_constraint_nameZinferred_target_elementsrl Zinferred_target_whereclauser� )r� �clauser� � target_textr� r� r� �_on_conflict_target/ s& ��� � � z PGCompiler._on_conflict_targetc K s& | j |fi |��}|r d| S dS d S )NzON CONFLICT %s DO NOTHINGzON CONFLICT DO NOTHING)r1 )r� � on_conflictr� r0 r� r� r� � visit_on_conflict_do_nothingP s z'PGCompiler.visit_on_conflict_do_nothingc K s� |}| j |fi |��}g }t|j�}| jd d }|jj}|D ]�} | j} | |v r\|�| �} n| |v r>|�| �} nq>t� | �r�t j d | | j d�} n$t | t j �r�| j jr�| �� } | j | _ | j| �� dd�} | j�| j�} |�d| | f � q>|�rzt�d| jjjd�d d � |D ��f � |�� D ]Z\}}t |t��r>| j�|�n | j|dd�} | jt� t j |�dd�} |�d| | f � �q d�|�}|j d u�r�|d | j|j d dd � 7 }d||f S )N���Z selectable�r� F)r �%s = %szFAdditional column names not matching any column keys in table '%s': %sr� c s s | ]}d | V qdS )z'%s'Nr� r, r� r� r� r� � � z9PGCompiler.visit_on_conflict_do_update.<locals>.<genexpr>r- Tr( z ON CONFLICT %s DO UPDATE SET %s) r1 r Zupdate_values_to_set�stackr~ r �key�poprD Z _is_literalrF Z BindParameterr� r� r� Z_cloner� � self_groupr� r+ r� �appendr: �warnZcurrent_executablerl �itemsr* �expectrH ZExpressionElementRoleZupdate_whereclause)r� r2 r� r/ r0 Zaction_set_opsZset_parametersZinsert_statement�colsr Zcol_keyr Z value_textZkey_text�k�vZ action_textr� r� r� �visit_on_conflict_do_updateX s` ������ � � � z&PGCompiler.visit_on_conflict_do_updatec s( d�d< dd� � ��fdd�|D �� S )NT�asfromzFROM r� c 3 s$ | ] }|j �fd � i���V qdS �Z fromhintsN�r� �r� �t�� from_hintsr� r� r� r� r� � s �z0PGCompiler.update_from_clause.<locals>.<genexpr>�rl )r� Z update_stmt� from_table� extra_fromsrJ r� r� rI r� �update_from_clause� s �z PGCompiler.update_from_clausec s( d�d< dd� � ��fdd�|D �� S )z9Render the DELETE .. USING clause specific to PostgreSQL.TrD zUSING r� c 3 s$ | ] }|j �fd � i���V qdS rE rF rG rI r� r� r� � s �z6PGCompiler.delete_extra_from_clause.<locals>.<genexpr>rK )r� Z delete_stmtrL rM rJ r� r� rI r� �delete_extra_from_clause� s �z#PGCompiler.delete_extra_from_clausec K sv d}|j d ur*|d| j|j fi |�� 7 }|jd urr|d| j|jfi |��|jd rXdnd|jd rhdndf 7 }|S ) Nr� z OFFSET (%s) ROWSz FETCH FIRST (%s)%s ROWS %s�percentz PERCENTZ with_tiesz WITH TIESr )r r� Z _fetch_clauseZ_fetch_clause_optionsr r� r� r� � fetch_clause� s �� �� zPGCompiler.fetch_clause)F)F)*�__name__� __module__� __qualname__r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r r r r r r! r& r1 r3 rC rN rO rQ � __classcell__r� r� r r� r� sP � � !E r� c s� e Zd Zdd� Zdd� Zdd� Z� fdd�Z� fd d �Z� fd d �Z� fd d�Z e j dd� �Z dd� Z dd� Zdd� Zdd� Zdd� Zdd � Zd d � Zd d � Zd!d"� Zd#d$� Zd%d&� Z� fd'd(�Zd)d*� Zd+d,� Zd-d.� Z� Z S )/� PGDDLCompilerc K sh | j �|�}|j�| j�}t|tj�r,|j}|j d uo<| jj }|j r�||j j u r�| jjsdt|tj�s�|s�|jd u s�t|jtj�r�|jjr�t|tj�r�|d7 }q�t|tj�r�|d7 }q�|d7 }n>|d| jjj|j|| j d� 7 }| �|�}|d ur�|d| 7 }|jd u�r |d| �|j� 7 }|�r6|d| �|j � 7 }|j�sN|�sN|d7 }n|j�rd|�rd|d7 }|S ) Nz BIGSERIALz SMALLSERIALz SERIAL� )Ztype_expressionr� z DEFAULT z NOT NULLz NULL)r� Z format_columnr� Z dialect_implr� r� rI Z TypeDecorator�impl�identity�supports_identity_columns� primary_keyr~ �_autoincrement_column�supports_smallserialZ SmallIntegerr< r7 �Sequence�optionalZ BigIntegerr� r� Zget_column_default_string�computed�nullable)r� rs �kwargsZcolspecZ impl_typeZ has_identityr< r� r� r� �get_column_specification� sZ �� �� �� � � � � z&PGDDLCompiler.get_column_specificationc C s |j d d }|rdS dS )N� postgresql� not_valid� NOT VALIDr� ��dialect_options)r� ry re r� r� r� �_define_constraint_validity� s z)PGDDLCompiler._define_constraint_validityc sD � j d d }|sdS � fdd�|D �}dd��fdd�|D �� S ) Nrd �includer� c s& g | ] }t |t�r � jj| n|�qS r� )r� r* r~ r r )�objr� r� r s �z1PGDDLCompiler._define_include.<locals>.<listcomp>z INCLUDE (%s)r� c s g | ]}� j �|j��qS r� )r� r+ r� r, r� r� r� r r7 )rh rl )r� rk Z includeclauseZ inclusionsr� )rk r� r� �_define_include s ��z PGDDLCompiler._define_includec s` |j rBt|j�d j}t|tj�rBt|jtj�rB|jj sBt � d��t � � |�}|| �|�7 }|S )Nr z�PostgreSQL dialect cannot produce the CHECK constraint for ARRAY of non-native ENUM; please specify create_constraint=False on this Enum datatype.)Z _type_bound�list�columnsr� r� rI �ARRAYr� �Enum� native_enumr6 r� r �visit_check_constraintri )r� ry r� �typr� r r� r� rr s � ��� z$PGDDLCompiler.visit_check_constraintc s t � �|�}|| �|�7 }|S r� )r � visit_foreign_key_constraintri �r� ry r� r� r r� r� rt s z*PGDDLCompiler.visit_foreign_key_constraintc s t � �|�}|| �|�7 }|S r� )r � visit_primary_key_constraintrl ru r r� r� rv $ s z*PGDDLCompiler.visit_primary_key_constraintc s t � �|�}|| �|�7 }|S r� )r �visit_unique_constraintrl ru r r� r� rw ) s z%PGDDLCompiler.visit_unique_constraintc C s t �dt j�S )NzC^(?:RESTRICT|CASCADE|SET (?:NULL|DEFAULT)(?:\s*\(.+\))?|NO ACTION)$)�rer� �Ir� r� r� r� �_fk_ondelete_pattern. s �z"PGDDLCompiler._fk_ondelete_patternc C s d| j �|j| j� S )Nz ON DELETE %s)r� �validate_sql_phrase�ondeleterz )r� ry r� r� r� �"define_constraint_ondelete_cascade6 s �z0PGDDLCompiler.define_constraint_ondelete_cascadec s0 |j }d� j�|�d�� fdd�|jD ��f S )NzCREATE TYPE %s AS ENUM (%s)r� c 3 s$ | ] }� j jt�|�d d�V qdS )T�� literal_bindsN)� sql_compilerr� r9 �literal)r� �er� r� r� r� @ s �z7PGDDLCompiler.visit_create_enum_type.<locals>.<genexpr>)r� r� � format_typerl �enums)r� rg r� r� r� r� r� �visit_create_enum_type; s ��z$PGDDLCompiler.visit_create_enum_typec K s |j }d| j�|� S )Nz DROP TYPE %s�r� r� r� )r� �dropr� r� r� r� r� �visit_drop_enum_typeF s z"PGDDLCompiler.visit_drop_enum_typec K s� |j }g }|jd ur.|�d| j�|j�� �� |jd urT| �|j�}|�d|� �� |jd ur|| j�|j�}|�d|� �� |j r�|�d� |j d ur�| j j |j ddd�}|�d|� d �� d | j� |�� d | j� |j�� d d �|�� �S ) NzCOLLATE zDEFAULT z CONSTRAINT zNOT NULLFT�r) r zCHECK (�)zCREATE DOMAIN z AS rW )r� � collationr< r� r+ r< Zrender_default_string�constraint_namer. �not_nullre r� r� r� � type_compiler� data_typerl )r� rg r� �domain�optionsr< r� re r� r� r� �visit_create_domain_typeK s2 � � ���z&PGDDLCompiler.visit_create_domain_typec K s |j }d| j�|�� �S )Nz DROP DOMAIN r� )r� r� r� r� r� r� r� �visit_drop_domain_typeg s z$PGDDLCompiler.visit_drop_domain_typec s� �j }|j}��|� d}|jr(|d7 }|d7 }�jjrR|jd d }|rR|d7 }|jr`|d7 }|d�j|d d �|� |j �f 7 }|jd d }|r�|d �j � |t �� � 7 }|jd d � |dd�� �fdd�|jD �� 7 }|��|�7 }|jd d }|du �r|d7 }n|d u �r"|d7 }|jd d } | �rV|dd�dd� | �� D �� 7 }|jd d } | �r||d|�| � 7 }|jd d } | d u�r�t�tj| �} �jj| d dd �} |d | 7 }|S ) NzCREATE zUNIQUE zINDEX rd � concurrently� CONCURRENTLY zIF NOT EXISTS z %s ON %s F�Zinclude_schemarx z USING %s �opsr' r� c sX g | ]P}�j jt|tj�s"|�� n|d dd�t|d�rN|j� v rNd� |j nd �qS )FTr� r9 rW r� )r� r� r� rG Z ColumnClauser; �hasattrr9 )r� �expr�r� r� r� r� r � s � � � ���z4PGDDLCompiler.visit_create_index.<locals>.<listcomp>�nulls_not_distinctTz NULLS NOT DISTINCTz NULLS DISTINCTr^ z WITH (%s)c S s g | ] }d | �qS )r6 r� )r� Zstorage_parameterr� r� r� r � s �� tablespacez TABLESPACE %srh r� z WHERE )r� r� Z_verify_index_tabler} r� �#_supports_create_index_concurrentlyrh Z if_not_exists�_prepared_index_name� format_tabler~ r{ � IDX_USING�lowerrl � expressionsrl r> r+ rD r? rH ZDDLExpressionRoler� r� ) r� rg r� r� �indexr� r� rx r� Z withclause�tablespace_nameZ whereclauseZwhere_compiledr� r� r� �visit_create_indexk s| ��� ���� ��� �� z PGDDLCompiler.visit_create_indexc K s2 |j d d }|du r d}n|du r*d}nd}|S )Nrd r� TzNULLS NOT DISTINCT FzNULLS DISTINCT r� rg )r� ry r� r� Znulls_not_distinct_paramr� r� r� �!define_unique_constraint_distinct� s �z/PGDDLCompiler.define_unique_constraint_distinctc K sP |j }d}| jjr,|jd d }|r,|d7 }|jr:|d7 }|| j|dd�7 }|S )Nz DROP INDEX rd r� r� z IF EXISTS Tr� )r� r� �!_supports_drop_index_concurrentlyrh Z if_existsr� )r� r� r� r� r� r� r� r� r� �visit_drop_index� s z PGDDLCompiler.visit_drop_indexc K s� d}|j d ur"|d| j�|� 7 }g }d|d< d|d< |jD ]Z\}}}| jj|fi |��t|d�r~|j|jv r~d|j|j nd }|� d ||f � q<|d | j� |j t �� � d �|�f 7 }|jd ur�|d | jj|jdd � 7 }|| �|�7 }|S )Nr� zCONSTRAINT %s Fr) Tr r9 rW z %s WITH %szEXCLUDE USING %s (%s)r� z WHERE (%s)r~ )r� r� �format_constraintZ _render_exprsr� r� r� r9 r� r< r{ rx r� r� rl rh Z define_constraint_deferrability) r� ry r� r� rF r� r� �opZexclude_elementr� r� r� �visit_exclude_constraint� s: �� ���� � z&PGDDLCompiler.visit_exclude_constraintc s g }|j d }|�d�}|d urZt|ttf�s4|f}|�dd�� fdd�|D �� d � |d rt|�d |d � |d r�|�d |d � |d d u r�|�d� n|d du r�|�d� |d r�|d �dd��� }|�d| � |d �r|d }|�d� j � |� � d�|�S )Nrd �inheritsz INHERITS ( r� c 3 s | ]}� j �|�V qd S r� )r� r+ )r� r� r� r� r� r� r7 z2PGDDLCompiler.post_create_table.<locals>.<genexpr>z )� partition_byz PARTITION BY %srx z USING %s� with_oidsTz WITH OIDSFz WITHOUT OIDS� on_commit�_rW z ON COMMIT %sr� z TABLESPACE %sr� ) rh r� r� rm �tupler< rl r r r� r+ )r� r~ Z table_optsZpg_optsr� Zon_commit_optionsr� r� r� r� �post_create_table s< ��� �z PGDDLCompiler.post_create_tablec K s, |j du rt�d��d| jj|jddd� S )NFz�PostrgreSQL computed columns do not support 'virtual' persistence; set the 'persisted' flag to None or True for PostgreSQL support.z GENERATED ALWAYS AS (%s) STOREDTr� )� persistedr6 r� r� r� r� )r� � generatedr� r� r� r� �visit_computed_column% s ��z#PGDDLCompiler.visit_computed_columnc s< d }|j jd ur$d| j�|j j� }t� j|fd|i|��S )Nz AS %s�prefix)r� r� r� r� r �visit_create_sequence)r� rg r� r� r r� r� r� 1 s �z#PGDDLCompiler.visit_create_sequencec C sB |j }|jd u r"t�d|�d���|jd u r>t�d|�d���d S )Nz%Can't emit COMMENT ON for constraint z: it has no namez : it has no associated table)r� r� r6 r� r~ )r� Z ddl_instancery r� r� r� �_can_comment_on_constraint: s � �z(PGDDLCompiler._can_comment_on_constraintc K s@ | � |� d| j�|j�| j�|jj�| j�|jjt � � �f S )Nz$COMMENT ON CONSTRAINT %s ON %s IS %s) r� r� r� r� r� r~ r� r� �commentrI r� )r� rg r� r� r� r� � visit_set_constraint_commentG s ��z*PGDDLCompiler.visit_set_constraint_commentc K s, | � |� d| j�|j�| j�|jj�f S )Nz&COMMENT ON CONSTRAINT %s ON %s IS NULL)r� r� r� r� r� r~ )r� r� r� r� r� r� � visit_drop_constraint_commentQ s �z+PGDDLCompiler.visit_drop_constraint_comment) rR rS rT rc ri rl rr rt rv rw r: �memoized_propertyrz r} r� r� r� r� r� r� r� r� r� r� r� r� r� r� rU r� r� r r� rV � s0 6 [ % rV c s� e Zd Zdd� Zdd� Zdd� Zdd� Zd d � Zd d � Zd d� Z dd� Z dd� Z dd� Z dd� Z dd� Zdd� Zdd � Zd d � Zd d � Zd!d"� Zd#d$� Zd%d&� Zd'd(� Zd)d*� Zd+d,� Zd-d.� Zd/d0� Zd1d2� Zd3d4� Z d5d6� Z d7d8� Z d9d:� Z d;d<� Z d=d>� Z!d?d@� Z"� fdAdB�Z#d^dDdE�Z$d_dFdG�Z%dHdI� Z&dJdK� Z'dLdM� Z(dNdO� Z)� fdPdQ�Z*dRdS� Z+dTdU� Z,dVdW� Z-dXdY� Z.dZd[� Z/d\d]� Z0� Z1S )`�PGTypeCompilerc K s dS )Nr4 r� �r� r� r� r� r� r� �visit_TSVECTORZ s z PGTypeCompiler.visit_TSVECTORc K s dS )NZTSQUERYr� r� r� r� r� � visit_TSQUERY] s z PGTypeCompiler.visit_TSQUERYc K s dS )Nr# r� r� r� r� r� � visit_INET` s zPGTypeCompiler.visit_INETc K s dS )Nr! r� r� r� r� r� � visit_CIDRc s zPGTypeCompiler.visit_CIDRc K s dS )Nr" r� r� r� r� r� � visit_CITEXTf s zPGTypeCompiler.visit_CITEXTc K s dS )Nr% r� r� r� r� r� � visit_MACADDRi s z PGTypeCompiler.visit_MACADDRc K s dS )Nr& r� r� r� r� r� �visit_MACADDR8l s z PGTypeCompiler.visit_MACADDR8c K s dS )Nr' r� r� r� r� r� � visit_MONEYo s zPGTypeCompiler.visit_MONEYc K s dS )Nr( r� r� r� r� r� � visit_OIDr s zPGTypeCompiler.visit_OIDc K s dS )Nr1 r� r� r� r� r� �visit_REGCONFIGu s z PGTypeCompiler.visit_REGCONFIGc K s dS )Nr0 r� r� r� r� r� �visit_REGCLASSx s z PGTypeCompiler.visit_REGCLASSc K s |j s dS dd|j i S d S )NrQ zFLOAT(%(precision)s)� precision)r� r� r� r� r� � visit_FLOAT{ s zPGTypeCompiler.visit_FLOATc K s | j tfi |��S r� )Zvisit_DOUBLE_PRECISIONr� r� r� r� r� � visit_double� s zPGTypeCompiler.visit_doublec K s dS )NrL r� r� r� r� r� � visit_BIGINT� s zPGTypeCompiler.visit_BIGINTc K s dS )Nr r� r� r� r� r� � visit_HSTORE� s zPGTypeCompiler.visit_HSTOREc K s dS )Nr� r� r� r� r� r� � visit_JSON� s zPGTypeCompiler.visit_JSONc K s dS )N�JSONBr� r� r� r� r� � visit_JSONB� s zPGTypeCompiler.visit_JSONBc K s dS )N�INT4MULTIRANGEr� r� r� r� r� �visit_INT4MULTIRANGE� s z#PGTypeCompiler.visit_INT4MULTIRANGEc K s dS )N�INT8MULTIRANGEr� r� r� r� r� �visit_INT8MULTIRANGE� s z#PGTypeCompiler.visit_INT8MULTIRANGEc K s dS )N� NUMMULTIRANGEr� r� r� r� r� �visit_NUMMULTIRANGE� s z"PGTypeCompiler.visit_NUMMULTIRANGEc K s dS )N�DATEMULTIRANGEr� r� r� r� r� �visit_DATEMULTIRANGE� s z#PGTypeCompiler.visit_DATEMULTIRANGEc K s dS )N� TSMULTIRANGEr� r� r� r� r� �visit_TSMULTIRANGE� s z!PGTypeCompiler.visit_TSMULTIRANGEc K s dS )N�TSTZMULTIRANGEr� r� r� r� r� �visit_TSTZMULTIRANGE� s z#PGTypeCompiler.visit_TSTZMULTIRANGEc K s dS )N� INT4RANGEr� r� r� r� r� �visit_INT4RANGE� s z PGTypeCompiler.visit_INT4RANGEc K s dS )N� INT8RANGEr� r� r� r� r� �visit_INT8RANGE� s z PGTypeCompiler.visit_INT8RANGEc K s dS )N�NUMRANGEr� r� r� r� r� �visit_NUMRANGE� s z PGTypeCompiler.visit_NUMRANGEc K s dS )N� DATERANGEr� r� r� r� r� �visit_DATERANGE� s z PGTypeCompiler.visit_DATERANGEc K s dS )N�TSRANGEr� r� r� r� r� � visit_TSRANGE� s z PGTypeCompiler.visit_TSRANGEc K s dS )N� TSTZRANGEr� r� r� r� r� �visit_TSTZRANGE� s z PGTypeCompiler.visit_TSTZRANGEc K s dS )N�INTr� r� r� r� r� �visit_json_int_index� s z#PGTypeCompiler.visit_json_int_indexc K s dS )NrV r� r� r� r� r� �visit_json_str_index� s z#PGTypeCompiler.visit_json_str_indexc K s | j |fi |��S r� )�visit_TIMESTAMPr� r� r� r� �visit_datetime� s z PGTypeCompiler.visit_datetimec s8 |j r| jjs"t� j|fi |��S | j|fi |��S d S r� )rq r� �supports_native_enumr � visit_enum� visit_ENUMr� r r� r� r� � s zPGTypeCompiler.visit_enumNc K s |d u r| j j}|�|�S r� �r� r� r� �r� r� r� r� r� r� r� r� � s zPGTypeCompiler.visit_ENUMc K s |d u r| j j}|�|�S r� r� r� r� r� r� � visit_DOMAIN� s zPGTypeCompiler.visit_DOMAINc K s4 dt |dd �d ur d|j nd|jr(dp*dd f S )NzTIMESTAMP%s %sr� �(%d)r� �WITH�WITHOUT� TIME ZONE��getattrr� �timezoner� r� r� r� r� � s � �z PGTypeCompiler.visit_TIMESTAMPc K s4 dt |dd �d ur d|j nd|jr(dp*dd f S )Nz TIME%s %sr� r� r� r� r� r� r� r� r� r� r� � visit_TIME� s � �zPGTypeCompiler.visit_TIMEc K s8 d}|j d ur |d|j 7 }|jd ur4|d|j 7 }|S )Nr$ rW z (%d))�fieldsr� )r� r� r� r� r� r� r� �visit_INTERVAL� s z PGTypeCompiler.visit_INTERVALc K s2 |j r$d}|jd ur.|d|j 7 }n d|j }|S )Nz BIT VARYINGr� zBIT(%d))�varyingr� )r� r� r� Zcompiledr� r� r� � visit_BIT� s zPGTypeCompiler.visit_BITc s0 |j r| j|fi |��S t� j|fi |��S d S r� )Z native_uuid� visit_UUIDr � visit_uuidr� r r� r� r � s zPGTypeCompiler.visit_uuidc K s dS )NrW r� r� r� r� r� r � s zPGTypeCompiler.visit_UUIDc K s | j |fi |��S r� )� visit_BYTEAr� r� r� r� �visit_large_binary� s z!PGTypeCompiler.visit_large_binaryc K s dS )Nr r� r� r� r� r� r � s zPGTypeCompiler.visit_BYTEAc K s> | j |jfi |��}tjddd|jd ur.|jnd |dd�S )Nz((?: COLLATE.*)?)$z%s\1z[]r )�count)r� r� rx �subZ dimensions)r� r� r� ro r� r� r� � visit_ARRAY s ���zPGTypeCompiler.visit_ARRAYc K s | j |fi |��S r� )�visit_JSONPATHr� r� r� r� �visit_json_path s z PGTypeCompiler.visit_json_pathc K s dS )N�JSONPATHr� r� r� r� r� r s z PGTypeCompiler.visit_JSONPATH)N)N)2rR rS rT r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r r r r r r r r rU r� r� r r� r� Y s\ r� c @ s" e Zd ZeZdd� Zddd�ZdS )�PGIdentifierPreparerc C s* |d | j kr&|dd� �| j| j�}|S )Nr r r4 )Z initial_quoter Zescape_to_quoteZ escape_quote)r� r r� r� r� �_unquote_identifier s �z(PGIdentifierPreparer._unquote_identifierTc C s\ |j s t�d|jj� d���| �|j �}| �|�}| jsX|rX|d urX| �|�� d|� �}|S )Nz PostgreSQL z type requires a name.�.) r� r6 r� r rR r+ �schema_for_objectZ omit_schemaZ quote_schema)r� r� r r� �effective_schemar� r� r� r� ! s � ���z PGIdentifierPreparer.format_typeN)T)rR rS rT �RESERVED_WORDSZreserved_wordsr r� r� r� r� r� r s r c @ s* e Zd ZU dZded< ded< ded< dS )�ReflectedNamedTypez"Represents a reflected named type.r* r� r7 �bool�visibleN�rR rS rT �__doc__�__annotations__r� r� r� r� r 3 s r c @ s" e Zd ZU dZded< ded< dS )�ReflectedDomainConstraintz2Represents a reflect check constraint of a domain.r* r� re Nr r� r� r� r� r > s r c @ s: e Zd ZU dZded< ded< ded< ded < ded < d S ) �ReflectedDomain� Represents a reflected enum.r* r� r ra � Optional[str]r< z List[ReflectedDomainConstraint]� constraintsr� Nr r� r� r� r� r G s r c @ s e Zd ZU dZded< dS )� ReflectedEnumr � List[str]�labelsNr r� r� r� r� r Z s r c @ sv e Zd ZU ded< ddddd�dd �Zddd d �d d �Zdddd �dd�Zd ddd �dd�Zd ddddd�dd�ZdS ) � PGInspector� PGDialectr� Nr* r �int)� table_namer7 �returnc C sB | � � �&}| jj|||| jd�W d � S 1 s40 Y dS )aQ Return the OID for the given table name. :param table_name: string name of the table. For special quoting, use :class:`.quoted_name`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. �� info_cacheN)�_operation_contextr� � get_table_oidr% )r� r" r7 �connr� r� r� r' d s �zPGInspector.get_table_oidzList[ReflectedDomain])r7 r# c C s@ | � � �$}| jj||| jd�W d � S 1 s20 Y dS )a� Return a list of DOMAIN objects. Each member is a dictionary containing these fields: * name - name of the domain * schema - the schema name for the domain. * visible - boolean, whether or not this domain is visible in the default search path. * type - the type defined by this domain. * nullable - Indicates if this domain can be ``NULL``. * default - The default value of the domain or ``None`` if the domain has no default. * constraints - A list of dict wit the constraint defined by this domain. Each element constaints two keys: ``name`` of the constraint and ``check`` with the constraint text. :param schema: schema name. If None, the default schema (typically 'public') is used. May also be set to ``'*'`` to indicate load domains for all schemas. .. versionadded:: 2.0 r$ N)r& r� � _load_domainsr% �r� r7 r( r� r� r� � get_domainsw s �zPGInspector.get_domainszList[ReflectedEnum]c C s@ | � � �$}| jj||| jd�W d � S 1 s20 Y dS )a. Return a list of ENUM objects. Each member is a dictionary containing these fields: * name - name of the enum * schema - the schema name for the enum. * visible - boolean, whether or not this enum is visible in the default search path. * labels - a list of string labels that apply to the enum. :param schema: schema name. If None, the default schema (typically 'public') is used. May also be set to ``'*'`` to indicate load enums for all schemas. r$ N)r& r� � _load_enumsr% r* r� r� r� � get_enums� s �zPGInspector.get_enumsr c C s@ | � � �$}| jj||| jd�W d � S 1 s20 Y dS )z�Return a list of FOREIGN TABLE names. Behavior is similar to that of :meth:`_reflection.Inspector.get_table_names`, except that the list is limited to those tables that report a ``relkind`` value of ``f``. r$ N)r& r� �_get_foreign_table_namesr% r* r� r� r� �get_foreign_table_names� s �z#PGInspector.get_foreign_table_namesr r )� type_namer7 r� r# c K sB | � � �&}| jj|||| jd�W d � S 1 s40 Y dS )aJ Return if the database has the specified type in the provided schema. :param type_name: the type to check. :param schema: schema name. If None, the default schema (typically 'public') is used. May also be set to ``'*'`` to check in all schemas. .. versionadded:: 2.0 r$ N)r& r� �has_typer% )r� r0 r7 r� r( r� r� r� r1 � s �zPGInspector.has_type)N)N)N)N)N) rR rS rT r r' r+ r- r/ r1 r� r� r� r� r a s � � � �r c s$ e Zd Zdd� Z� fdd�Z� ZS )�PGExecutionContextc C s | � d| j�|� |�S )Nzselect nextval('%s'))�_execute_scalarr� r )r� r r� r� r� r� � fire_sequence� s ��z PGExecutionContext.fire_sequencec s0 |j �r$||jju �r$|jr:|jjr:| �d|jj |j�S |jd u sX|jj �r$|jj �r$z |j }W nr t y� |jj }|j }|ddtddt|� � � }|ddtddt|� � � }d||f }| |_ }Y n0 |jd ur�| j�|j�}nd }|d u�r d||f }n d|f }| �||j�S t� �|�S )Nz select %sr � z %s_%s_seqzselect nextval('"%s"."%s"')zselect nextval('"%s"'))r[ r~ r\ Zserver_defaultZ has_argumentr3 �argr� r< Z is_sequencer_ Z_postgresql_seq_name�AttributeErrorr� �maxr# � connectionr r �get_insert_default)r� rs Zseq_name�tabr r� r r6 r r� r� r: � s@ � �� � � z%PGExecutionContext.get_insert_default)rR rS rT r4 r: rU r� r� r r� r2 � s r2 c @ s( e Zd ZdZdd� Zdd� Zdd� ZdS ) �"PGReadOnlyConnectionCharacteristicTc C s |� |d� d S �NF�� set_readonly�r� r� � dbapi_connr� r� r� �reset_characteristic s z7PGReadOnlyConnectionCharacteristic.reset_characteristicc C s |� ||� d S r� r> �r� r� rA r r� r� r� �set_characteristic s z5PGReadOnlyConnectionCharacteristic.set_characteristicc C s |� |�S r� )� get_readonlyr@ r� r� r� �get_characteristic s z5PGReadOnlyConnectionCharacteristic.get_characteristicN�rR rS rT Z transactionalrB rD rF r� r� r� r� r< s r< c @ s( e Zd ZdZdd� Zdd� Zdd� ZdS ) �$PGDeferrableConnectionCharacteristicTc C s |� |d� d S r= ��set_deferrabler@ r� r� r� rB s z9PGDeferrableConnectionCharacteristic.reset_characteristicc C s |� ||� d S r� rI rC r� r� r� rD s z7PGDeferrableConnectionCharacteristic.set_characteristicc C s |� |�S r� )�get_deferrabler@ r� r� r� rF s z7PGDeferrableConnectionCharacteristic.get_characteristicNrG r� r� r� r� rH s rH c s� e Zd ZdZdZdZdZdZej j Z dZ dZ dZdZdZdZdZdZdZdZejejB ejB ZdZdZ dZ dZ dZ dZ dZ!dZ"e#Z#e$Z$e%Z&e'Z(e)Z*e+Z,e-Z.e/Z0dZ1dZ2dZ3dZ4dZ5e6j7j8Z8e8�9e:� e;� d��Z8e<j=dddi di ddd�fe<j>dddddddd �fe<j?d dife<j@d dife<jAd dife<jBddd �fgZCd ZDdZEdZFdZGd�dd�ZH� fdd�ZIdd� ZJdd� ZKdd� ZLdd� ZMdd� ZNd d � ZOd d � ZPd d!d"�d#d$�ZQd%d&� ZRd'd(� ZSd�d)d*�ZTd�d+d,�ZUd-d.� ZVd/d0� ZWeXjYd1d2� �ZZd�d3d4�Z[d�d5d6�Z\e]� d7d8� �Z^eXjYd�d9d:��Z_eXjYd�d;d<��Z`eXjYd�d=d>��Zad?d@� ZbeXjYd�dAdB��ZceXjYdCdD� �ZddEdF� ZeeXjYd�dGdH��ZfeXjYdIdJ� �ZgeXjYd�dKdL��ZheXjYd�dMdN��ZieXjYd�dOdP��ZjeXjYd�dQdR��ZkeXjYd�dSdT��ZleXjYd�dUdV��ZmdWdX� ZndYdZ� Zod[d\d]�d^d_�ZpeXjYd�d`da��Zqe]� dbdc� �Zrddde� Zset�udf�Zvet�udg�Zwet�udh�Zxdidjdkdldmdn�dodp�Zydqdr� Zze]� dsdt� �Z{eX�|due}j~fdve}jfdwe}j�fdxe}j�f�dydz� �Z�e�j�d{d|� �Z�d}d~� Z�eXjYd�dd���Z�d�d�� Z�eXjYd�d�d���Z�e]� d�d�� �Z�e�j�d�d�� �Z�d�d�d��Z�eXjYd�d�d���Z�e�j�d�d�� �Z�d�d�� Z�eXjYd�d�d���Z�d�d�� Z�eXjYd�d�d���Z�e]� d�d�� �Z�d�d�� Z�eXjYd�d�d���Z�e]� d�d�� �Z�d�d�� Z�d�d�� Z�e]� d�d�� �Z�eXjYd�d�d���Z�e]� d�d�� �Z�eXjYd�d�d���Z�d�d�� Z�� Z�S )�r rd T�? FZpyformat)Zpostgresql_readonlyZpostgresql_deferrableN)rx rj rh r� r� r^ r� r� )Zignore_search_pathr� r� r� r� r� rx re rj )rj r� )� postgresql_ignore_search_pathc K s* t jj| fi |�� || _|| _|| _d S r� )r< �DefaultDialect�__init__Z_native_inet_typesZ_json_deserializerZ_json_serializer)r� Znative_inet_typesZjson_serializerZjson_deserializerrb r� r� r� rO � s zPGDialect.__init__c s> t � �|� | jdk| _| �|� | jdk| _| jdk| _d S )N)� r" �� )r � initialize�server_version_infor] �_set_backslash_escapesr� rZ �r� r9 r r� r� rS � s zPGDialect.initializec C s dS )N)Z SERIALIZABLEzREAD UNCOMMITTEDzREAD COMMITTEDzREPEATABLE READr� )r� rA r� r� r� �get_isolation_level_values� s z$PGDialect.get_isolation_level_valuesc C s. |� � }|�d|� �� |�d� |�� d S )Nz;SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL ZCOMMIT)�cursor�execute�close)r� �dbapi_connection�levelrX r� r� r� �set_isolation_level� s �� z PGDialect.set_isolation_levelc C s. |� � }|�d� |�� d }|�� |�� S )Nz show transaction isolation levelr )rX rY ZfetchonerZ r )r� r[ rX �valr� r� r� �get_isolation_level� s z PGDialect.get_isolation_levelc C s t � �d S r� ��NotImplementedError�r� r9 r r� r� r� r? � s zPGDialect.set_readonlyc C s t � �d S r� r` rV r� r� r� rE � s zPGDialect.get_readonlyc C s t � �d S r� r` rb r� r� r� rJ � s zPGDialect.set_deferrablec C s t � �d S r� r` rV r� r� r� rK � s zPGDialect.get_deferrablerA zUUnion[Tuple[None, None], Tuple[Tuple[Optional[str], ...], Tuple[Optional[int], ...]]])�urlr# c C s, d }d }d}d|j v r�t|j d ttf�rLd}tdd� |j d D �� \}}n�t|j d t�r�t|j d �d��}d|j vr�t|�dkr�d |d v r�t� d |d �}|r�d}|� dd �\}}t r�t|t�s�J �t|t�s�J �|f}t d |r�|fnd�}d|j v �rX|�rt �d��t|j d ttf��r2|j d }n&t|j d t��rXt|j d �d��}d }|�r�ztdd� |D ��}W n& t�y� t �d|� ��d �Y n0 |�r�|�s�t|�dk�s�|�r�|�r�t|�t|�k�r�t|�dk�s�t|�dk�r�t �d��|d u�r$|d u �r$tdd� |D ��}||fS )NF�hostTc S s& g | ] }d |v r|� d �n|df�qS )�:N��split)r� �tokenr� r� r� r � s �z7PGDialect._split_multihost_from_url.<locals>.<listcomp>�,�portr re r z ^([a-zA-Z0-9\-\.]*)(?:\:(\d*))?$r" zTuple[Optional[str], ...]r� zzCan't mix 'multihost' formats together; use "host=h1,h2,h3&port=p1,p2,p3" or "host=h1:p1&host=h2:p2&host=h3:p3" separatelyc s s | ]}|rt |�nd V qd S r� �r! �r� �xr� r� r� r� r7 z6PGDialect._split_multihost_from_url.<locals>.<genexpr>z%Received non-integer port arguments: z%number of hosts and ports don't matchc s s | ] }d V qd S r� r� )r� r� r� r� r� r� 0 r7 )�queryr� rm r� �zipr* rg r# rx �matchr\ r r r6 � ArgumentError� ValueError) r� rc �hostsZ ports_strZintegrated_multihostZhost_port_match�h�pZportsr� r� r� �_split_multihost_from_url� s� �� � � � �� � ��� ���� � � z#PGDialect._split_multihost_from_urlc C s | � |j� d S r� )Zdo_beginr9 �r� r9 �xidr� r� r� �do_begin_twophase4 s zPGDialect.do_begin_twophasec C s |� d| � d S )NzPREPARE TRANSACTION '%s')�exec_driver_sqlrw r� r� r� �do_prepare_twophase7 s z PGDialect.do_prepare_twophasec C sH |r8|r|� d� |� d| � |� d� | �|j� n | �|j� d S )N�ROLLBACKzROLLBACK PREPARED '%s'�BEGIN)rz � do_rollbackr9 �r� r9 rx Z is_preparedZrecoverr� r� r� �do_rollback_twophase: s z PGDialect.do_rollback_twophasec C sH |r8|r|� d� |� d| � |� d� | �|j� n | �|j� d S )Nr| zCOMMIT PREPARED '%s'r} )rz r~ r9 Z do_commitr r� r� r� �do_commit_twophaseJ s z PGDialect.do_commit_twophasec C s |� t�d���� S )Nz!SELECT gid FROM pg_prepared_xacts)�scalarsr9 r� r� rV r� r� r� �do_recover_twophaseV s �z PGDialect.do_recover_twophasec C s |� d��� S )Nzselect current_schema())rz �scalarrV r� r� r� �_get_default_schema_name[ s z"PGDialect._get_default_schema_namec K s, t tjjj��tjjj|k�}t|�|��S r� )r8 r � pg_namespacer �nspnamerh r r� )r� r9 r7 r� rn r� r� r� � has_schema^ s �zPGDialect.has_schemac C s� |d u rt j}|�t jt jjj|jjk�}|tju rH|� |jj dk�}n |tj u rd|� |jj dk�}|d u r�|� t � |jj�t jjj dk�}n|� t jjj |k�}|S )NrH r )r �pg_classrl r� r r� � relnamespacer? �DEFAULTrh Zrelpersistence� TEMPORARYZpg_table_is_visibler� )r� rn r7 �scope�pg_class_tabler� r� r� � _pg_class_filter_scope_schemae s" � �z'PGDialect._pg_class_filter_scope_schemac C s& |d u rt j}|jjt�t�|��kS r� )r r� r �relkindr9 �any_r� rr )r� �relkindsr� r� r� r� �_pg_class_relkind_condition~ s z%PGDialect._pg_class_relkind_conditionc C s> t tjjj��tjjjtd�k| �tj��}| j ||t j d�S )Nr" �r� ) r8 r r� r �relnamerh rC r� �RELKINDS_ALL_TABLE_LIKEr� r? �ANY)r� r7 rn r� r� r� �_has_table_query� s ���zPGDialect._has_table_queryc K s( | � |� | �|�}t|�|d|i��S )Nr" )Z _ensure_has_table_connectionr� r r� )r� r9 r" r7 r� rn r� r� r� � has_table� s zPGDialect.has_tablec K sJ t tjjj��tjjjdktjjj|k�}| j||tj d�}t |� |��S )N�Sr� ) r8 r r� r r� rh r� r� r? r� r r� )r� r9 Z sequence_namer7 r� rn r� r� r� � has_sequence� s ��zPGDialect.has_sequencec K s� t tjjj��tjtjjjtjjjk�� tjjj|k�}|d u rd|� t� tjjj�tjjj dk�}n |dkr�|� tjjj |k�}t |� |��S �Nr �*)r8 r �pg_typer �typnamerl r� r� � typnamespacerh �pg_type_is_visibler� r r� )r� r9 r0 r7 r� rn r� r� r� r1 � s" �� �� �zPGDialect.has_typec C sF |� d��� }t�d|�}|s*td| ��tdd� |�ddd�D ��S ) Nzselect pg_catalog.version()zQ.*(?:PostgreSQL|EnterpriseDB) (\d+)\.?(\d+)?(?:\.(\d+))?(?:\.\d+)?(?:devel|beta)?z,Could not determine version from string '%s'c S s g | ]}|d urt |��qS r� rk rl r� r� r� r � r7 z6PGDialect._get_server_version_info.<locals>.<listcomp>r r" r5 )rz r� rx rp �AssertionErrorr� r\ )r� r9 rB �mr� r� r� �_get_server_version_info� s ��z"PGDialect._get_server_version_infoc K sl t tjjj��tjjj|k| �tj��}| j ||t j d�}|� |�}|du rht �|rb|� d|� �n|��|S )z$Fetch the oid for schema.table_name.r� Nr )r8 r r� r r� rh r� r� r� r� r? r� r� r6 �NoSuchTableError)r� r9 r" r7 r� rn Z table_oidr� r� r� r' � s ��� �zPGDialect.get_table_oidc K s: t tjjj��tjjj�d���tjjj�}|�|�� � S )Nzpg_%) r8 r r� r r� rh Znot_liker� r� r� )r� r9 r� rn r� r� r� �get_schema_names� s ���zPGDialect.get_schema_namesc C s8 t tjjj��| �|��}| j|||d�}|�|�� � S �Nr� ) r8 r r� r r� rh r� r� r� r� )r� r9 r7 r� r� rn r� r� r� �_get_relnames_for_relkinds� s �z$PGDialect._get_relnames_for_relkindsc K s | j ||tjtjd�S r� )r� r �RELKINDS_TABLE_NO_FOREIGNr? r� �r� r9 r7 r� r� r� r� �get_table_names� s �zPGDialect.get_table_namesc K s | j |d tjtjd�S )N)r7 r� r� )r� r r� r? r� )r� r9 r� r� r� r� �get_temp_table_names� s �z PGDialect.get_temp_table_namesc K s | j ||dtjd�S )N)�f�r� r� �r� r? r� r� r� r� r� r. � s �z"PGDialect._get_foreign_table_namesc K s | j ||tjtjd�S r� )r� r � RELKINDS_VIEWr? r� r� r� r� r� �get_view_names s �zPGDialect.get_view_namesc K s | j ||tjtjd�S r� )r� r �RELKINDS_MAT_VIEWr? r� r� r� r� r� �get_materialized_view_names s �z%PGDialect.get_materialized_view_namesc K s | j ||tjtjd�S r� )r� r r� r? r� r� r� r� r� �get_temp_view_names s �z PGDialect.get_temp_view_namesc K s | j ||dtjd�S )N)r� r� r� r� r� r� r� �get_sequence_names s �z PGDialect.get_sequence_namesc K s� t t�tjjj���tj��tjjj|k| � tj tj ��}| j ||t jd�}|�|�}|d u r~t�|rv|� d|� �n|��n|S d S )Nr� r )r8 r Zpg_get_viewdefr� r r� � select_fromrh r� r� r� r� r� r? r� r� r6 r� )r� r9 Z view_namer7 r� rn �resr� r� r� �get_view_definition# s$ � ��� � �z PGDialect.get_view_definitionc C sH zt |�||f W S tyB t�|r6|� d|� �n|�d �Y n0 d S )Nr )r �KeyErrorr6 r� )r� �datar~ r7 r� r� r� �_value_or_raise: s ��zPGDialect._value_or_raisec C s |rdd|ifS di fS d S )NT� filter_namesFr� )r� r� r� r� r� �_prepare_filter_namesB s z PGDialect._prepare_filter_namesr> zTuple[str, ...])�kindr# c C sT |t ju rtjS d}t j|v r(|tj7 }t j|v r<|tj7 }t j|v rP|tj 7 }|S )Nr� ) r> r� r r� ZTABLEZRELKINDS_TABLEZVIEWr� ZMATERIALIZED_VIEWr� )r� r� r� r� r� r� �_kind_to_relkindsH s zPGDialect._kind_to_relkindsc K s0 | j |f||gtjtjd�|��}| �|||�S �N)r7 r� r� r� )�get_multi_columnsr? r� r> r� �r� r9 r" r7 r� r� r� r� r� � get_columnsT s ���zPGDialect.get_columnsc C s� | j dkrtjjj�d�n t�� �d�}| j dkr�ttj j dtjjj dkdtj jj dtj jjdtj jjd tj jjd tj jjd tj jjt�� d ���tj ��tjjj d ktj jjt�t�t�t�t�tjjjt�t �tjjj �t�t �k�� tj�� � �d�}nt�� �d�}tt�!tj"jj#tj"jj$���tj"��tj"jj$tjjjktj"jj%tjjj&ktjjj'�� tj�� � �d�}| �(|�}ttjjj �d�t�)tjjj*tjjj+��d�|tjjj,�d�tj-jj.�d�tj/jj0�d�||��tj-��1tjt�2tj-jj3tjjjktjjj&dktjjj4 ���1tj/t�2tj/jj5tjjjktj/jj6tjjj&k���| �7|���8tj-jj.tjjj&�} | j9| ||d�} |�r�| �tj-jj.�:t;d���} | S )N)� r� rQ �always�ar� � incrementZminvalueZmaxvalue�cache�cycler5 r� �identity_optionsr< r� r� r� r" r� r r� r� )<rT r � pg_attributer Z attgenerated�labelr9 rf r8 r$ Zjson_build_objectZ attidentityZ pg_sequenceZseqstartZ seqincrementZseqminZseqmaxZseqcacheZseqcyclerI r� r� rh Zseqrelidr Zpg_get_serial_sequence�attrelidr0 rV �attnamer( Z correlateZscalar_subquery� pg_get_exprZ pg_attrdefZadbinZadrelidZadnum�attnumZ atthasdefr� r� ZatttypidZ atttypmodZ attnotnullr� r� �pg_description� description� outerjoin�and_r� Z attisdropped�objoid�objsubidr� r� r� �in_rC ) r� r7 �has_filter_namesr� r� r� rY r< r� rn r� r� r� �_columns_query` s� � � ��� ��� � ���*�,��0��������� ��� �� ������#�%��)�zPGDialect._columns_queryc K s� | � |�\}}| �||||�} |�| |��� } dd� | j|d|�d�d�D �} tdd� | j|d|�d�d�D ��} | �| | | |�} | � � S )Nc S s0 i | ](}|d s |d |d fn|d f|�qS )r r7 r� r� )r� �dr� r� r� � <dictcomp>� s �z/PGDialect.get_multi_columns.<locals>.<dictcomp>r� r% )r7 r% c s s8 | ]0}|d r |d f|fn|d |d f|fV qdS )r r� r7 Nr� )r� Zrecr� r� r� r� � s ��z.PGDialect.get_multi_columns.<locals>.<genexpr>) r� r� rY �mappingsr) r� r r, �_get_columns_infor> )r� r9 r7 r� r� r� r� r� �paramsrn �rows�domainsr� rn r� r� r� r� � s �� �� zPGDialect.get_multi_columnsz\((.*)\)�\s*,\s*z ((?:\[\])*)$r zDict[str, ReflectedDomain]zDict[str, ReflectedEnum]r* zsqltypes.TypeEngine[Any])r� r� r� �type_descriptionr# c C s~ |pd}|du r$t �d| � tjS | j�|�}|rR|�d�rR| j�|�d��}nd}| j �|�}t |�d�ppd�d }| j� d|�} | j � d| �} | j � | �� d�} di } } | dkr�t |�dkr�tt|�\} }| |f} �n\| d kr�d } �nL| d k�r d} �n:| d v �r4d | d< t |�dk�r:t|d �| d< �n| dv �rhd| d< t |�dk�r:t|d �| d< �n�| dk�r�d | d< t |�dk�r:t|d �}|f} �n�| �d��r�t} t�d| �}|�r�|�d�| d< t |�dk�r:t|d �| d< �nJtt �| ��}||v �rDt} || }|d | d< |d �s6|d | d< t|d �} n�||v �r�t} || }| j|d ||d |d d �}|d |f} |d | d < |d | d < |d! | d"< d| d#< |d$ �r�|d$ d }|d | d%< |d& | d&< |d �s:|d | d< nBz$t|d �}|g|dd� �R } W n ttf�y8 |} Y n0 | �sXt �d'| |f � tjS | | i | ��}|dk�rzt � |�}|S )(aB Attempts to reconstruct a column type defined in ischema_names based on the information available in the format_type. If the `format_type` cannot be associated with a known `ischema_names`, it is treated as a reference to a known PostgreSQL named `ENUM` or `DOMAIN` type. z unknown typeNz-PostgreSQL format_type() returned NULL for %sr r� r� r" r� r� )�5 r� )r� r� Tr� r r� )r� r� r� Fr� r� r� z interval (.+)r� r� r r7 r r� z DOMAIN '%s'�r� r� r< ra r� Z create_typer r� re z!Did not recognize type '%s' of %s) r: r= rI ZNULLTYPE�_format_type_args_pattern�searchr\ �_format_type_args_delimrg �_format_array_spec_patternr# r � ischema_namesr� r� �mapr! � startswithr$ rx rp r� Zquoted_token_parserr r � _reflect_typerr � IndexErrorr� ro )r� r� r� r� r� Zattype_args_matchZ attype_argsZmatch_array_dimZ array_dim�attypeZ schema_type�argsrb r� ZscaleZcharlenZ field_matchZenum_or_domain_key�enumr� r� Zcheck_constraintr� r� r� r� s� �� � � �� zPGDialect._reflect_typec C s� t t�}|D �]�}|d d u r4t�� |||d f< q |||d f }| j|d ||d|d d�}|d } |d } |d } |d } t|t�r�| s�|jd ur�|j} | o�|j } |d } | d vr�t | | d v d �}d } nd }d }| d u�rTt � d| �}|d u�rTt |j tj��rd}d|�d�v�rT|d u�rT|�d�d| d |�d� |�d� } | || | |�ph| d u|d d�}|d u�r�||d< | d u�r�| |d< |�|� q |S )Nr� r" r� z column '%s'r� r< r� r� r� )Nr� � )r% � s)r� r� Fz(nextval\(')([^']+)('.*$)Tr r" r z"%s"r5 r� )r� r� ra r< � autoincrementr� r` rY )r rm rB rn r� r� r r< r� r rx r� � issubclassr� rI ZIntegerr\ r< )r� r� r� r� r7 rn �row_dictZ table_colsZcoltyper< r� r� ra rY r` r� rp Z column_infor� r� r� r� � sv � � � ����� � zPGDialect._get_columns_infoc C s^ | � |�}ttjjjtjjj��| �|��}| j |||d�}|rZ|�tjjj� t d���}|S )Nr� r� ) r� r8 r r� r r� r� rh r� r� r� rC )r� r7 r� r� r� r� �oid_qr� r� r� �_table_oids_query� s ���zPGDialect._table_oids_queryr7 r� r� r� c K s2 | � |�\}}| �||||�} |�| |�} | �� S r� )r� r� rY r� ) r� r9 r7 r� r� r� r� r� r� r� �resultr� r� r� �_get_table_oids� s zPGDialect._get_table_oidsc C s | j dkrtjjj}nt�� �d�}| j dkr:tjjj}nt� � �d�}t tj jj tj jj tj�tjjj��d�tj�tjjjd��d�||tjjj��tjtj jjtjjjk��tjtjjjtj jjk��tj jjt d�ktj jj � t d ���� d �}t |jj |jj |jj|jj |jj|jjtj jj!��"tj ��|t�#tj jj$|jj$ktj jj%|jj k���|jj � t d ���� d �}t |jj tj�&t'|jj!�(t)�|jj ���d �|jj tj�*|jj��d �tj�*|jj��d�tj�+|jj��d���,|jj |jj ��-|jj |jj �S )N�� r � indnkeyatts�� �indnullsnotdistinctr� r �ord�contype�oids�con�attrr@ r� ).rT r �pg_indexr r� r9 rf r� r� r� r8 � pg_constraint�conrelid�connamer$ �unnest�indkey�generate_subscriptsr� r� rl �conindid� indexrelidr� r� r� rh r rC r� �subqueryr r� r� r� r� r� r� � array_aggr r rV �minZbool_and�group_byr� )r� r� r� �con_sq�attr_sqr� r� r� �_constraint_query s� ��� ����� ��!� � ����� ����� � ��zPGDialect._constraint_queryc k sX | j |||||fi |��}t|�} |dk} | �rT| dd� } g | dd�< |�| jdd� | D �|d���� } tt�} | D ]}| |d �|� qv| D ]�\}}| �|d�}|�r@|D ]�}|d }|d }|d ur�t|�|kr�||d � }|d |� }ng }|}i }| j d k�r||d < | �r$|d |d< |||d |d |fV q�q�|d d d d fV q�q*d S )N�ur � c S s g | ] }|d �qS �r r� �r� �rr� r� r� r u r7 z1PGDialect._reflect_constraint.<locals>.<listcomp>)r r r r� r@ r� �r� �postgresql_includer� � postgresql_nulls_not_distinctr r� ) r� rm rY r r� r r< r� r# rT )r� r9 r r7 r� r� r� r� � table_oids�batchesZ is_unique�batchr� � result_by_oidr� r� Z tablenameZfor_oid�rowZall_colsr� �inc_colsZcst_cols�optsr� r� r� �_reflect_constrainte sZ �� � � � �� z PGDialect._reflect_constraintc K s0 | j |f||gtjtjd�|��}| �|||�S r� )�get_multi_pk_constraintr? r� r> r� r� r� r� r� �get_pk_constraint� s ���zPGDialect.get_pk_constraintc s@ | j |d�|||fi |��}tj� dd� �� ��fdd�|D �S )Nru c S s || |d�}|r||d< |S )N)�constrained_columnsr� r� rh r� )�pk_namer@ r� r# �infor� r� r� � pk_constraint� s �z8PGDialect.get_multi_pk_constraint.<locals>.pk_constraintc 3 s< | ]4\}}}}}�|f|d ur,�||||�n� � fV qd S r� r� )r� r" r@ r( r� r# �r< r* r7 r� r� r� � s ���z4PGDialect.get_multi_pk_constraint.<locals>.<genexpr>)r$ rB r* )r� r9 r7 r� r� r� r� r� r� r+ r� r% � s �� �z!PGDialect.get_multi_pk_constraintc K s2 | j |f||g|tjtjd�|��}| �|||�S )N)r7 r� rM r� r� )�get_multi_foreign_keysr? r� r> r� )r� r9 r" r7 rM r� r� r� r� r� �get_foreign_keys� s ��� zPGDialect.get_foreign_keysc C s: t j�d�}t j�d�}| �|�}tt jjjt jjj t j t jjj � d �t �t jjj d�fd d�|jjt jjj��t j��t jt �t jjj t jjjkt jjjdk���||jj t jjjk��||jj|jj k��t jt jjjt jjj k��t jjjt jjj ��| � |��}| � |||�}|�r6|�t jjj� t d���}|S )NZcls_refZnsp_refT�Zelse_r� r� ) r r� �aliasr� r� r8 r r� r r r9 r� r� �is_not�pg_get_constraintdefr� r� r� r� r� r� r r Z confrelidr� r� r� rh r� r� r� rC ) r� r7 r� r� r� Z pg_class_refZpg_namespace_refr� rn r� r� r� �_foreing_key_query� sd ��� ��� ��� �#��(�+��.�z PGDialect._foreing_key_queryc C s" d}t �d|� d|� d|� d��S )Nz(?:"[^"]+"|[A-Za-z0-9_]+?)z%FOREIGN KEY \((.*?)\) REFERENCES (?:(z)\.)?(z)\(((?:a (?: *, *)?)+)\)[\s]?(MATCH (FULL|PARTIAL|SIMPLE)+)?[\s]?(ON UPDATE (CASCADE|RESTRICT|NO ACTION|SET NULL|SET DEFAULT)+)?[\s]?(ON DELETE (CASCADE|RESTRICT|NO ACTION|SET (?:NULL|DEFAULT)(?:\s\(.+\))?)+)?[\s]?(DEFERRABLE|NOT DEFERRABLE)?[\s]?(INITIALLY (DEFERRED|IMMEDIATE)+)?)rx r� )r� Zqtokenr� r� r� �_fk_regex_pattern s ����zPGDialect._fk_regex_patternc " s� | j � | �|�\}} | �||||�} |�| | �} | j} tt�} tj}| D �]D\}}}}}|d u rp|� | ||f< qH| ||f }t � | |�� � }|\ }}}}}}}} }} } }} | d ur�| dkr�dnd} � fdd�t � d|�D �}|r�|| j kr�|}n|}n*|�r� �|�}n|d u�r ||k�r |}� �|�}� fdd�t � d|�D �}d d � d | fd | fd | fd| fd|ffD �} |||||| |d�}!|�|!� qH| �� S )NZ DEFERRABLETFc s g | ]}� � |��qS r� �r rl �r� r� r� r [ s �z4PGDialect.get_multi_foreign_keys.<locals>.<listcomp>r� c s g | ]}� � |��qS r� r4 rl r5 r� r� r r s �z\s*,\sc S s& i | ] \}}|d ur|dkr||�qS )Nz NO ACTIONr� )r� rA rB r� r� r� r� v s �z4PGDialect.get_multi_foreign_keys.<locals>.<dictcomp>�onupdater| rv r� rp )r� r' �referred_schema�referred_table�referred_columnsr� r� )r� r� r2 rY r3 r rm rB Z foreign_keysrx r� �groupsrg Zdefault_schema_namer r< r> )"r� r9 r7 r� r� r� rM r� r� r� rn r� ZFK_REGEXZfkeysr< r" r ZcondefZ conschemar� Z table_fksr� r' r7 r8 r9 r� rp r6 r| r� rv r� Zfkey_dr� r5 r� r, , s~ � � ��� � z PGDialect.get_multi_foreign_keysc K s0 | j |f||gtjtjd�|��}| �|||�S r� )�get_multi_indexesr? r� r> r� r� r� r� r� � get_indexes� s ���zPGDialect.get_indexesc C s2 t tjjjtjjjtj�tjjj �� d�tj� tjjj d�� d��� tjjj tjjj�td����d�}t |jj|jj|jjtj|jjdkt�|jj|jjd d�ftjjj�t�d�� d �|jjdk� d ���|��tjt�tjjj|jjktjjj |jjk��� |jj�td����d �}t |jjtj� |jj�tj� t |jj |jj��� d �tj� t |jj!|jj��� d ���"|jj��d�}| j#dk�r�tjjj$}nt�%� � d�}| j#dk�r�tjjj&}nt�'� � d�}t tjjjtj(jj)tjjj*tj+jj,�-d �� d�tjjj.tj(jj/tj0jj1tjtjjj2�-d �t�3tjjj2tjjj�fd d�� d�|||jj4|jj5� �tj�� tjjj�td��tjjj ��6tj(tjjjtj(jj7k��6tj0tj(jj8tj0jj7k��|tjjj|jjk��tj+t�tjjjtj+jj,ktjjjtj+jj9ktj+jj:t�;t<�=d��k���>tjjjtj(jj)�S )Nr� r r r �idxr Tr. r� �is_exprZidx_attrrF �elements_is_exprZidx_colsr� r� r� r� �has_constraint�filter_definition)ru r rm )?r8 r r r r �indrelidr9 r$ r r r� r rh Z indisprimaryr� rC r r r� r� Zpg_get_indexdefr� r� r rV r� r� r� r� r r r r� r> r rT r� rf r� r� r� r� � indisuniquer r r0 � indoption� reloptionsZpg_am�amnameZindpredr� rF r? rl r� Zrelamr r r� r� rr r� )r� Zidx_sqr Zcols_sqr� r� r� r� r� � _index_query� s� ��� � �� �� � � ���� � ��#����� � �� ���� � �� �!�%�)�-�����8��zPGDialect._index_queryc ! K s� | j |||||fi |��}tt�}tj} t|�} | �r�| dd� } g | dd�< |�| jddd� | D �i��� } tt�} | D ]}| |d �|� qz| D �]8\}}|| vr�| � |||f< q�| | D �] }|d }|||f }|d }|d }|d }|d u�rPt |�|k�rP||d � }|d |� }|d |� }t d d � ||d � D ���s\J �n |}|}g }||d d�}t |��r�dd� t ||�D �|d< ||d< n||d< i }t |d �D ]X\} } d} | d@ �r�| d7 } | d@ �s�| d7 } n| d@ �r�| d7 } | �r�| ||| < �q�|�r||d< |d �r(||d< i } |d �rPtd d� |d D ��| d < |d } | d k�rn|d | d!< |d" �r�|d" | d#< | jd$k�r�||d%< || d&< |d' �r�|d' | d(< | �r�| |d)< |�|� q�q�q0|�� S )*Nr r r c S s g | ] }|d �qS r r� r r� r� r� r ; r7 z/PGDialect.get_multi_indexes.<locals>.<listcomp>rB r� rF r? r� c s s | ] }| V qd S r� r� )r� r> r� r� r� r� b s �z.PGDialect.get_multi_indexes.<locals>.<genexpr>rC )r� r} c S s g | ]\}}|rd n|�qS r� r� )r� r� r> r� r� r� r m s �� column_namesr� rD r� r )rc r" )Z nulls_last)Z nulls_firstZcolumn_sortingr@ Zduplicates_constraintrE c S s g | ]}|� d d��qS )�=r rf )r� �optionr� r� r� r � s �Zpostgresql_withrF ZbtreeZpostgresql_usingrA Zpostgresql_wherer Zinclude_columnsr r� r rh )r� r rm rB �indexesrY rG r� r< r# r� rk ro � enumerater rT r> )!r� r9 r7 r� r� r� r� r rK r< r r r� r r� r� r" r! Z index_nameZ table_indexesZ all_elementsZall_elements_is_exprr� r" Z idx_elementsZidx_elements_is_exprr� ZsortingZ col_indexZ col_flagsZ col_sortingrh rF r� r� r� r; * s� �� � � � � � �� �� � �zPGDialect.get_multi_indexesc K s0 | j |f||gtjtjd�|��}| �|||�S r� )� get_multi_unique_constraintsr? r� r> r� r� r� r� r� �get_unique_constraints� s ���z PGDialect.get_unique_constraintsc K s� | j |d||||fi |��}tt�}tj} |D ]P\} } } } }| d u rT| � ||| f< q.| | | d�}|rl||d< ||| f �|� q.|�� S )Nr )rH r� r� rh )r$ r rm rB Zunique_constraintsr< r> )r� r9 r7 r� r� r� r� r� Zuniquesr< r" r@ Zcon_namer� r� Zuc_dictr� r� r� rM � s& ���z&PGDialect.get_multi_unique_constraintsc K s0 | j |||gftjtjd�|��}| �|||�S �N)r� r� )�get_multi_table_commentr? r� r> r� r� r� r� r� �get_table_comment� s ���zPGDialect.get_table_commentc C s� | � |�}ttjjjtjjj��tj�� tjt � tjjj tjjj ktjjjdktjjjt j�dt�k���| �|��}| �|||�}|r�|�tjjj�td���}|S )Nr zpg_catalog.pg_classr� )r� r8 r r� r r� r� r� r� r� r9 r� r� r� r� Zclassoidr$ r r0 rh r� r� r� rC �r� r7 r� r� r� r� rn r� r� r� �_comment_query� s6 ��� ������zPGDialect._comment_queryc sD | � |�\}}| ��|||�} |�| |�} tj� � �fdd�| D �S )Nc 3 s0 | ](\}}�|f|d ur d|in� � fV qd S )Nr� r� )r� r~ r� �r< r7 r� r� r� s ��z4PGDialect.get_multi_table_comment.<locals>.<genexpr>)r� rS rY rB Z table_comment) r� r9 r7 r� r� r� r� r� r� rn r� r� rT r� rP s �z!PGDialect.get_multi_table_commentc K s0 | j |||gftjtjd�|��}| �|||�S rO )�get_multi_check_constraintsr? r� r> r� r� r� r� r� �get_check_constraints s ���z PGDialect.get_check_constraintsc C s� | � |�}ttjjjtjjjtj tjjj � d �t� tjjj d�fd d�tj jj��tj��tjt�tjjj tjjjktjjjdk���tj tj jjtjjj k��tjjjtjjj��| �|��}| �|||�}|r�|�tjjj�td���}|S )NTr. r r� )r� r8 r r� r r� r r r9 r� r� r0 r1 r� r� r� r� r� r r r� r� rh r� r� r� rC rR r� r� r� �_check_constraint_query" sR ��� ��� ���� �"��%�z!PGDialect._check_constraint_queryc K s | � |�\}}| �||||�} |�| |�} tt�} tj} | D ]�\} }}}|d u rh|d u rh| � | || f< q<tjd|tj d�}|s�t � d| � d}n tj dtj d�� d|�d��}|||d�}|r�i }d |�� v r�d |d < d |�� v r�d |d < |r�||d< | || f �|� q<| �� S )Nz,^CHECK *\((.+)\)( NO INHERIT)?( NOT VALID)?$)r� z)Could not parse CHECK constraint text: %rr� z^[\s\n]*\((.+)\)[\s\n]*$z\1r )r� r� r� rf Tre z NO INHERITZ no_inheritrh )r� rW rY r rm rB �check_constraintsrx rp �DOTALLr: r= r� r r\ r: r< r> )r� r9 r7 r� r� r� r� r� r� rn r� rX r< r" Z check_name�srcr� r� r� �entryr_ r� r� r� rU Q sL � �� �� z%PGDialect.get_multi_check_constraintsc C sL |d u r,|� t�tjjj�tjjjdk�}n |dkrH|� tjjj|k�}|S r� )rh r r� r� r r� r� r� )r� rn r7 r� r� r� �_pg_type_filter_schema� s �z PGDialect._pg_type_filter_schemac C s� t tjjjtj�ttjjj � t �tjjj ��� d���tjjj��d�}t tjjj� d�t�tjjj�� d�tjjj� d�|jj� d���tjtjjjtjjjk��|tjjj|jjk��tjjjdk�� tjjjtjjj�}| � ||�S )Nr Zlbl_aggr� r r7 r� ) r8 r Zpg_enumr Z enumtypidr9 r$ r r Z enumlabelr rV Z enumsortorderr� r r r� r� r� r� r� r� r rl r� r� rh �typtyper� r\ )r� r7 Z lbl_agg_sqrn r� r� r� � _enum_query� sJ ���� � ��� � ��� ���zPGDialect._enum_queryc K sT | j s g S |�| �|��}g }|D ],\}}}}|�||||d u rDg n|d�� q"|S )N)r� r7 r r )r� rY r^ r< ) r� r9 r7 r� r� r� r� r r r� r� r� r, � s ��zPGDialect._load_enumsc C sh t tjjjtj�t�tjjj d��� d�tj�tjjj � t ��� d���tjjjdk��tjjj��d�}t tjjj� d�t�tjjjtjjj�� d�tjjj � d�tjjj� d �t�tjjj �� d �tjjj� d �|jj|jj tj jj � � tjtjjj tjjj k��!tj tjjj"tj jj k��!|tjjj |jjk��tjjj#d k��$tjjjtjjj�}| �%||�S ) NT�condefs�connamesr Zdomain_constraintsr� r� ra r< r r7 r� )&r8 r r r Zcontypidr9 r$ r r1 r� r� r r rV rh r r r� r� r� Z typbasetypeZ typtypmodZ typnotnullZ typdefaultr� r� r� r_ r` Z pg_collation�collnamerl r� r� Z typcollationr] r� r\ )r� r7 r rn r� r� r� � _domain_query� sv ������ ������������� � ��$zPGDialect._domain_queryc K s� |� | �|��}g }|�� D ]�}t�d|d ��d�}g }|d r�tt|d |d �dd� d�} | D ]2\} } | �� � d �rd| d d � } |� | | d �� qd|d |d |d ||d |d ||d d�} |� | � q |S )Nz([^\(]+)r� r r` r_ c S s | d S )Nr r� )rH r� r� r� �<lambda> r7 z)PGDialect._load_domains.<locals>.<lambda>)r9 re � r4 )r� re r� r7 r ra r< ra )r� r7 r r� ra r< r r� ) rY rb r� rx r� r\ �sortedro �casefoldr� r< )r� r9 r7 r� r� r� r� r� r Zsorted_constraintsr� Zdef_re Z domain_recr� r� r� r) s2 � � zPGDialect._load_domainsc C s |� d��� }|dk| _d S )Nz show standard_conforming_stringsr� )rz r� r )r� r9 Z std_stringr� r� r� rU 1 s �z PGDialect._set_backslash_escapes)NNN)TF)TF)N)N)N)N)N)N)N)N)N)N)N)N)N)N)N)NF)F)N)N)N)N)N)N)�rR rS rT r� Zsupports_statement_cacheZsupports_alterZmax_identifier_lengthZsupports_sane_rowcountr= Z BindTypingZ RENDER_CASTSZ bind_typingr� Zsupports_native_booleanZsupports_native_uuidr] Zsupports_sequencesZsequences_optionalZ"preexecute_autoincrement_sequencesZpostfetch_lastrowidZuse_insertmanyvaluesZreturns_native_bytesrJ ZANY_AUTOINCREMENTZUSE_INSERT_FROM_SELECTZRENDER_SELECT_COL_CASTSZ"insertmanyvalues_implicit_sentinelZsupports_commentsZ supports_constraint_commentsZsupports_default_valuesZsupports_default_metavalueZsupports_empty_insertZsupports_multivalues_insertrZ Zdefault_paramstyler� �colspecsr� Zstatement_compilerrV Z ddl_compilerr� Ztype_compiler_clsr r� r2 Zexecution_ctx_clsr Z inspectorZupdate_returningZdelete_returningZinsert_returningZupdate_returning_multifromZdelete_returning_multifromr< rN Zconnection_characteristicsrZ r< rH r7 �IndexZTableZCheckConstraintZForeignKeyConstraintZPrimaryKeyConstraintZUniqueConstraintZconstruct_argumentsZreflection_optionsr r� r� rO rS rW r] r_ r? rE rJ rK rv ry r{ r� r� r� r� r@ r� r� r� r� r r� r� r� r1 r� r' r� r� r� r� r. r� r� r� r� r� r� r� r� r� r� r� rx r� r� r� r� r� r� r� Z flexi_cacherK Z dp_stringZdp_string_listZ dp_plain_objr� r: r� r r$ r& r% r- r2 r3 r, r< rG r; rN rM rQ rS rP rV rW rU r\ r^ r, rb r) rU rU r� r� r r� r $ s� ������ ���� ��������3 � T � � � ! S � ^9 ! � 9 � a � " .6 * ; $r )�r � __future__r � collectionsr � functoolsr rx �typingr r r r r r r r r� r r� r �_jsonr r �_ranges�extr r r� r Z named_typesr r r r r r r �typesr r r r r r! r" r# r$ r% r& r' r( r) r* r+ r, r- r. r/ r0 r1 r2 r3 r4 r6 r7 r8 r9 r: Zenginer; r< r= r> r? r@ rA Zengine.reflectionrB rC rD rE rF rG rH rI r Z sql.compilerrJ Z sql.visitorsrK rL rM rN rO rP rQ rR rS rT rU rV rW rX Z util.typingrY r� ry r� r ro ZIntervalrp r� Z JSONPathTyper ZUuidrg r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� Z SQLCompilerr� Z DDLCompilerrV ZGenericTypeCompilerr� ZIdentifierPreparerr r r r r Z Inspectorr ZDefaultExecutionContextr2 ZConnectionCharacteristicr< rH rN r r� r� r� r� �<module> sp k � �6 ; ? n7 � � sqlalchemy/dialects/postgresql/__pycache__/psycopg2.cpython-39.pyc 0000644 00000074311 15125143220 0021311 0 ustar 00 a ��Jh } � @ s� d Z ddlmZ ddlmZ ddlZddlZddlm Z ddl m Z ddl m Z ddl mZ dd lmZ dd lmZ dd lmZ d d l mZ d dl mZ d dlmZ d dlmZ e�d�ZG dd� de�ZG dd� de�Z G dd� de j �Z G dd� de �Z G dd� de �Z G d d � d e �Z!G d d � d e �Z"G d d!� d!e�Z#G d"d#� d#e�Z$G d$d%� d%e�Z%e%j&�'� \Z(Z)G d&d'� d'e �Z*e*Z+dS )(a%J .. dialect:: postgresql+psycopg2 :name: psycopg2 :dbapi: psycopg2 :connectstring: postgresql+psycopg2://user:password@host:port/dbname[?key=value&key=value...] :url: https://pypi.org/project/psycopg2/ .. _psycopg2_toplevel: psycopg2 Connect Arguments -------------------------- Keyword arguments that are specific to the SQLAlchemy psycopg2 dialect may be passed to :func:`_sa.create_engine()`, and include the following: * ``isolation_level``: This option, available for all PostgreSQL dialects, includes the ``AUTOCOMMIT`` isolation level when using the psycopg2 dialect. This option sets the **default** isolation level for the connection that is set immediately upon connection to the database before the connection is pooled. This option is generally superseded by the more modern :paramref:`_engine.Connection.execution_options.isolation_level` execution option, detailed at :ref:`dbapi_autocommit`. .. seealso:: :ref:`psycopg2_isolation_level` :ref:`dbapi_autocommit` * ``client_encoding``: sets the client encoding in a libpq-agnostic way, using psycopg2's ``set_client_encoding()`` method. .. seealso:: :ref:`psycopg2_unicode` * ``executemany_mode``, ``executemany_batch_page_size``, ``executemany_values_page_size``: Allows use of psycopg2 extensions for optimizing "executemany"-style queries. See the referenced section below for details. .. seealso:: :ref:`psycopg2_executemany_mode` .. tip:: The above keyword arguments are **dialect** keyword arguments, meaning that they are passed as explicit keyword arguments to :func:`_sa.create_engine()`:: engine = create_engine( "postgresql+psycopg2://scott:tiger@localhost/test", isolation_level="SERIALIZABLE", ) These should not be confused with **DBAPI** connect arguments, which are passed as part of the :paramref:`_sa.create_engine.connect_args` dictionary and/or are passed in the URL query string, as detailed in the section :ref:`custom_dbapi_args`. .. _psycopg2_ssl: SSL Connections --------------- The psycopg2 module has a connection argument named ``sslmode`` for controlling its behavior regarding secure (SSL) connections. The default is ``sslmode=prefer``; it will attempt an SSL connection and if that fails it will fall back to an unencrypted connection. ``sslmode=require`` may be used to ensure that only secure connections are established. Consult the psycopg2 / libpq documentation for further options that are available. Note that ``sslmode`` is specific to psycopg2 so it is included in the connection URI:: engine = sa.create_engine( "postgresql+psycopg2://scott:tiger@192.168.0.199:5432/test?sslmode=require" ) Unix Domain Connections ------------------------ psycopg2 supports connecting via Unix domain connections. When the ``host`` portion of the URL is omitted, SQLAlchemy passes ``None`` to psycopg2, which specifies Unix-domain communication rather than TCP/IP communication:: create_engine("postgresql+psycopg2://user:password@/dbname") By default, the socket file used is to connect to a Unix-domain socket in ``/tmp``, or whatever socket directory was specified when PostgreSQL was built. This value can be overridden by passing a pathname to psycopg2, using ``host`` as an additional keyword argument:: create_engine( "postgresql+psycopg2://user:password@/dbname?host=/var/lib/postgresql" ) .. warning:: The format accepted here allows for a hostname in the main URL in addition to the "host" query string argument. **When using this URL format, the initial host is silently ignored**. That is, this URL:: engine = create_engine( "postgresql+psycopg2://user:password@myhost1/dbname?host=myhost2" ) Above, the hostname ``myhost1`` is **silently ignored and discarded.** The host which is connected is the ``myhost2`` host. This is to maintain some degree of compatibility with PostgreSQL's own URL format which has been tested to behave the same way and for which tools like PifPaf hardcode two hostnames. .. seealso:: `PQconnectdbParams \ <https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS>`_ .. _psycopg2_multi_host: Specifying multiple fallback hosts ----------------------------------- psycopg2 supports multiple connection points in the connection string. When the ``host`` parameter is used multiple times in the query section of the URL, SQLAlchemy will create a single string of the host and port information provided to make the connections. Tokens may consist of ``host::port`` or just ``host``; in the latter case, the default port is selected by libpq. In the example below, three host connections are specified, for ``HostA::PortA``, ``HostB`` connecting to the default port, and ``HostC::PortC``:: create_engine( "postgresql+psycopg2://user:password@/dbname?host=HostA:PortA&host=HostB&host=HostC:PortC" ) As an alternative, libpq query string format also may be used; this specifies ``host`` and ``port`` as single query string arguments with comma-separated lists - the default port can be chosen by indicating an empty value in the comma separated list:: create_engine( "postgresql+psycopg2://user:password@/dbname?host=HostA,HostB,HostC&port=PortA,,PortC" ) With either URL style, connections to each host is attempted based on a configurable strategy, which may be configured using the libpq ``target_session_attrs`` parameter. Per libpq this defaults to ``any`` which indicates a connection to each host is then attempted until a connection is successful. Other strategies include ``primary``, ``prefer-standby``, etc. The complete list is documented by PostgreSQL at `libpq connection strings <https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING>`_. For example, to indicate two hosts using the ``primary`` strategy:: create_engine( "postgresql+psycopg2://user:password@/dbname?host=HostA:PortA&host=HostB&host=HostC:PortC&target_session_attrs=primary" ) .. versionchanged:: 1.4.40 Port specification in psycopg2 multiple host format is repaired, previously ports were not correctly interpreted in this context. libpq comma-separated format is also now supported. .. versionadded:: 1.3.20 Support for multiple hosts in PostgreSQL connection string. .. seealso:: `libpq connection strings <https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING>`_ - please refer to this section in the libpq documentation for complete background on multiple host support. Empty DSN Connections / Environment Variable Connections --------------------------------------------------------- The psycopg2 DBAPI can connect to PostgreSQL by passing an empty DSN to the libpq client library, which by default indicates to connect to a localhost PostgreSQL database that is open for "trust" connections. This behavior can be further tailored using a particular set of environment variables which are prefixed with ``PG_...``, which are consumed by ``libpq`` to take the place of any or all elements of the connection string. For this form, the URL can be passed without any elements other than the initial scheme:: engine = create_engine("postgresql+psycopg2://") In the above form, a blank "dsn" string is passed to the ``psycopg2.connect()`` function which in turn represents an empty DSN passed to libpq. .. versionadded:: 1.3.2 support for parameter-less connections with psycopg2. .. seealso:: `Environment Variables\ <https://www.postgresql.org/docs/current/libpq-envars.html>`_ - PostgreSQL documentation on how to use ``PG_...`` environment variables for connections. .. _psycopg2_execution_options: Per-Statement/Connection Execution Options ------------------------------------------- The following DBAPI-specific options are respected when used with :meth:`_engine.Connection.execution_options`, :meth:`.Executable.execution_options`, :meth:`_query.Query.execution_options`, in addition to those not specific to DBAPIs: * ``isolation_level`` - Set the transaction isolation level for the lifespan of a :class:`_engine.Connection` (can only be set on a connection, not a statement or query). See :ref:`psycopg2_isolation_level`. * ``stream_results`` - Enable or disable usage of psycopg2 server side cursors - this feature makes use of "named" cursors in combination with special result handling methods so that result rows are not fully buffered. Defaults to False, meaning cursors are buffered by default. * ``max_row_buffer`` - when using ``stream_results``, an integer value that specifies the maximum number of rows to buffer at a time. This is interpreted by the :class:`.BufferedRowCursorResult`, and if omitted the buffer will grow to ultimately store 1000 rows at a time. .. versionchanged:: 1.4 The ``max_row_buffer`` size can now be greater than 1000, and the buffer will grow to that size. .. _psycopg2_batch_mode: .. _psycopg2_executemany_mode: Psycopg2 Fast Execution Helpers ------------------------------- Modern versions of psycopg2 include a feature known as `Fast Execution Helpers \ <https://www.psycopg.org/docs/extras.html#fast-execution-helpers>`_, which have been shown in benchmarking to improve psycopg2's executemany() performance, primarily with INSERT statements, by at least an order of magnitude. SQLAlchemy implements a native form of the "insert many values" handler that will rewrite a single-row INSERT statement to accommodate for many values at once within an extended VALUES clause; this handler is equivalent to psycopg2's ``execute_values()`` handler; an overview of this feature and its configuration are at :ref:`engine_insertmanyvalues`. .. versionadded:: 2.0 Replaced psycopg2's ``execute_values()`` fast execution helper with a native SQLAlchemy mechanism known as :ref:`insertmanyvalues <engine_insertmanyvalues>`. The psycopg2 dialect retains the ability to use the psycopg2-specific ``execute_batch()`` feature, although it is not expected that this is a widely used feature. The use of this extension may be enabled using the ``executemany_mode`` flag which may be passed to :func:`_sa.create_engine`:: engine = create_engine( "postgresql+psycopg2://scott:tiger@host/dbname", executemany_mode="values_plus_batch", ) Possible options for ``executemany_mode`` include: * ``values_only`` - this is the default value. SQLAlchemy's native :ref:`insertmanyvalues <engine_insertmanyvalues>` handler is used for qualifying INSERT statements, assuming :paramref:`_sa.create_engine.use_insertmanyvalues` is left at its default value of ``True``. This handler rewrites simple INSERT statements to include multiple VALUES clauses so that many parameter sets can be inserted with one statement. * ``'values_plus_batch'``- SQLAlchemy's native :ref:`insertmanyvalues <engine_insertmanyvalues>` handler is used for qualifying INSERT statements, assuming :paramref:`_sa.create_engine.use_insertmanyvalues` is left at its default value of ``True``. Then, psycopg2's ``execute_batch()`` handler is used for qualifying UPDATE and DELETE statements when executed with multiple parameter sets. When using this mode, the :attr:`_engine.CursorResult.rowcount` attribute will not contain a value for executemany-style executions against UPDATE and DELETE statements. .. versionchanged:: 2.0 Removed the ``'batch'`` and ``'None'`` options from psycopg2 ``executemany_mode``. Control over batching for INSERT statements is now configured via the :paramref:`_sa.create_engine.use_insertmanyvalues` engine-level parameter. The term "qualifying statements" refers to the statement being executed being a Core :func:`_expression.insert`, :func:`_expression.update` or :func:`_expression.delete` construct, and **not** a plain textual SQL string or one constructed using :func:`_expression.text`. It also may **not** be a special "extension" statement such as an "ON CONFLICT" "upsert" statement. When using the ORM, all insert/update/delete statements used by the ORM flush process are qualifying. The "page size" for the psycopg2 "batch" strategy can be affected by using the ``executemany_batch_page_size`` parameter, which defaults to 100. For the "insertmanyvalues" feature, the page size can be controlled using the :paramref:`_sa.create_engine.insertmanyvalues_page_size` parameter, which defaults to 1000. An example of modifying both parameters is below:: engine = create_engine( "postgresql+psycopg2://scott:tiger@host/dbname", executemany_mode="values_plus_batch", insertmanyvalues_page_size=5000, executemany_batch_page_size=500, ) .. seealso:: :ref:`engine_insertmanyvalues` - background on "insertmanyvalues" :ref:`tutorial_multiple_parameters` - General information on using the :class:`_engine.Connection` object to execute statements in such a way as to make use of the DBAPI ``.executemany()`` method. .. _psycopg2_unicode: Unicode with Psycopg2 ---------------------- The psycopg2 DBAPI driver supports Unicode data transparently. The client character encoding can be controlled for the psycopg2 dialect in the following ways: * For PostgreSQL 9.1 and above, the ``client_encoding`` parameter may be passed in the database URL; this parameter is consumed by the underlying ``libpq`` PostgreSQL client library:: engine = create_engine( "postgresql+psycopg2://user:pass@host/dbname?client_encoding=utf8" ) Alternatively, the above ``client_encoding`` value may be passed using :paramref:`_sa.create_engine.connect_args` for programmatic establishment with ``libpq``:: engine = create_engine( "postgresql+psycopg2://user:pass@host/dbname", connect_args={"client_encoding": "utf8"}, ) * For all PostgreSQL versions, psycopg2 supports a client-side encoding value that will be passed to database connections when they are first established. The SQLAlchemy psycopg2 dialect supports this using the ``client_encoding`` parameter passed to :func:`_sa.create_engine`:: engine = create_engine( "postgresql+psycopg2://user:pass@host/dbname", client_encoding="utf8" ) .. tip:: The above ``client_encoding`` parameter admittedly is very similar in appearance to usage of the parameter within the :paramref:`_sa.create_engine.connect_args` dictionary; the difference above is that the parameter is consumed by psycopg2 and is passed to the database connection using ``SET client_encoding TO 'utf8'``; in the previously mentioned style, the parameter is instead passed through psycopg2 and consumed by the ``libpq`` library. * A common way to set up client encoding with PostgreSQL databases is to ensure it is configured within the server-side postgresql.conf file; this is the recommended way to set encoding for a server that is consistently of one encoding in all databases:: # postgresql.conf file # client_encoding = sql_ascii # actually, defaults to database # encoding client_encoding = utf8 Transactions ------------ The psycopg2 dialect fully supports SAVEPOINT and two-phase commit operations. .. _psycopg2_isolation_level: Psycopg2 Transaction Isolation Level ------------------------------------- As discussed in :ref:`postgresql_isolation_level`, all PostgreSQL dialects support setting of transaction isolation level both via the ``isolation_level`` parameter passed to :func:`_sa.create_engine` , as well as the ``isolation_level`` argument used by :meth:`_engine.Connection.execution_options`. When using the psycopg2 dialect , these options make use of psycopg2's ``set_isolation_level()`` connection method, rather than emitting a PostgreSQL directive; this is because psycopg2's API-level setting is always emitted at the start of each transaction in any case. The psycopg2 dialect supports these constants for isolation level: * ``READ COMMITTED`` * ``READ UNCOMMITTED`` * ``REPEATABLE READ`` * ``SERIALIZABLE`` * ``AUTOCOMMIT`` .. seealso:: :ref:`postgresql_isolation_level` :ref:`pg8000_isolation_level` NOTICE logging --------------- The psycopg2 dialect will log PostgreSQL NOTICE messages via the ``sqlalchemy.dialects.postgresql`` logger. When this logger is set to the ``logging.INFO`` level, notice messages will be logged:: import logging logging.getLogger("sqlalchemy.dialects.postgresql").setLevel(logging.INFO) Above, it is assumed that logging is configured externally. If this is not the case, configuration such as ``logging.basicConfig()`` must be utilized:: import logging logging.basicConfig() # log messages to stdout logging.getLogger("sqlalchemy.dialects.postgresql").setLevel(logging.INFO) .. seealso:: `Logging HOWTO <https://docs.python.org/3/howto/logging.html>`_ - on the python.org website .. _psycopg2_hstore: HSTORE type ------------ The ``psycopg2`` DBAPI includes an extension to natively handle marshalling of the HSTORE type. The SQLAlchemy psycopg2 dialect will enable this extension by default when psycopg2 version 2.4 or greater is used, and it is detected that the target database has the HSTORE type set up for use. In other words, when the dialect makes the first connection, a sequence like the following is performed: 1. Request the available HSTORE oids using ``psycopg2.extras.HstoreAdapter.get_oids()``. If this function returns a list of HSTORE identifiers, we then determine that the ``HSTORE`` extension is present. This function is **skipped** if the version of psycopg2 installed is less than version 2.4. 2. If the ``use_native_hstore`` flag is at its default of ``True``, and we've detected that ``HSTORE`` oids are available, the ``psycopg2.extensions.register_hstore()`` extension is invoked for all connections. The ``register_hstore()`` extension has the effect of **all Python dictionaries being accepted as parameters regardless of the type of target column in SQL**. The dictionaries are converted by this extension into a textual HSTORE expression. If this behavior is not desired, disable the use of the hstore extension by setting ``use_native_hstore`` to ``False`` as follows:: engine = create_engine( "postgresql+psycopg2://scott:tiger@localhost/test", use_native_hstore=False, ) The ``HSTORE`` type is **still supported** when the ``psycopg2.extensions.register_hstore()`` extension is not used. It merely means that the coercion between Python dictionaries and the HSTORE string format, on both the parameter side and the result side, will take place within SQLAlchemy's own marshalling logic, and not that of ``psycopg2`` which may be more performant. � )� annotationsN)�cast� )�ranges)�_PGDialect_common_psycopg)�"_PGExecutionContext_common_psycopg)�PGIdentifierPreparer)�JSON)�JSONB� )�types)�util)� FastIntFlag)� parse_user_argument_for_enumz sqlalchemy.dialects.postgresqlc @ s e Zd Zdd� ZdS )�_PGJSONc C s d S �N� ��self�dialect�coltyper r �\/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/postgresql/psycopg2.py�result_processor s z_PGJSON.result_processorN��__name__� __module__� __qualname__r r r r r r s r c @ s e Zd Zdd� ZdS )�_PGJSONBc C s d S r r r r r r r s z_PGJSONB.result_processorNr r r r r r s r c @ s e Zd ZdZdd� Zdd� ZdS )�_Psycopg2Range�nonec s$ t tt|�j| j�� � fdd�}|S )Nc s& t | tj�r"� | j| j| j| j�} | S r )� isinstancer �Range�lower�upper�bounds�empty��value�Zpsycopg2_Ranger r �to_range s �z/_Psycopg2Range.bind_processor.<locals>.to_range)�getattrr �PGDialect_psycopg2�_psycopg2_extras�_psycopg2_range_cls)r r r) r r( r �bind_processor s � z _Psycopg2Range.bind_processorc C s dd� }|S )Nc S s2 | d ur.t j| j| j| jr | jnd| j d�} | S )Nz[))r$ r% )r r! Z_lowerZ_upperZ_boundsr& r r r r) s �z1_Psycopg2Range.result_processor.<locals>.to_ranger )r r r r) r r r r s z _Psycopg2Range.result_processorN)r r r r- r. r r r r r r s r c @ s e Zd ZdZdS )�_Psycopg2NumericRangeZ NumericRangeN�r r r r- r r r r r/ * s r/ c @ s e Zd ZdZdS )�_Psycopg2DateRangeZ DateRangeNr0 r r r r r1 . s r1 c @ s e Zd ZdZdS )�_Psycopg2DateTimeRangeZ DateTimeRangeNr0 r r r r r2 2 s r2 c @ s e Zd ZdZdS )�_Psycopg2DateTimeTZRangeZDateTimeTZRangeNr0 r r r r r3 6 s r3 c @ s e Zd ZdZdd� Zdd� ZdS )�PGExecutionContext_psycopg2Nc C s | � | j� d S r )� _log_notices�cursor�r r r r � post_exec= s z%PGExecutionContext_psycopg2.post_execc C sL |j jrt|j jtj�s d S |j jD ]}t�|�� � q$g |j jd d �< d S r )� connectionZnoticesr �collections_abc�Iterable�logger�info�rstrip)r r6 �noticer r r r5 @ s � z(PGExecutionContext_psycopg2._log_notices)r r r Z_psycopg2_fetched_rowsr8 r5 r r r r r4 : s r4 c @ s e Zd ZdS )� PGIdentifierPreparer_psycopg2N)r r r r r r r r@ R s r@ c @ s e Zd ZdZdZdS )�ExecutemanyModer r N)r r r �EXECUTEMANY_VALUES� EXECUTEMANY_VALUES_PLUS_BATCHr r r r rA V s rA c sT e Zd ZdZdZdZdZdZeZ e Z dZ dZ dZdZe�ejeeejeeeejeej eej eej e ej e!ej"e#i �Zd3dd �Z$� fd d �Z%e&d d � �Z'ej(dd� �Z)ej(dd� �Z*ej(dd� �Z+dd� Z,dd� Z-dd� Z.dd� Z/d d � Z0d d � Z1d4d!d"�Z2d#d$� Z3d%d&� Z4d5d'd(�Z5d6d)d*�Z6d7d+d,�Z7ej8d-d.� �Z9d/d0� Z:ej(d1d2� �Z;� Z<S )8r+ �psycopg2TZpyformatF)r r � values_only�d c K s� t j| fi |�� | jr td��t|tdgtdgid�| _|| _| j r�t | j d�r�t � d| j j �}|r�tdd� |�d d d �D ��| _| jd k r�td ��d S )Nz�The psycopg2 dialect does not implement ipaddress type handling; native_inet_types cannot be set to ``True`` when using this dialect.rE Zvalues_plus_batch�executemany_mode� __version__z(\d+)\.(\d+)(?:\.(\d+))?c s s | ]}|d urt |�V qd S r )�int)�.0�xr r r � <genexpr>� s z.PGDialect_psycopg2.__init__.<locals>.<genexpr>r � r )rM � z+psycopg2 version 2.7 or higher is required.)r �__init__Z_native_inet_types�NotImplementedErrorr rB rC rG �executemany_batch_page_size�dbapi�hasattr�re�matchrH �tuple�group�psycopg2_version� ImportError)r rG rQ �kwargs�mr r r rO � s. ��� � �zPGDialect_psycopg2.__init__c s6 t � �|� | jo"| �|jj�d u| _| jtu| _ d S r ) �super� initialize�use_native_hstore� _hstore_oidsr9 �dbapi_connection�_has_native_hstorerG rC � supports_sane_multi_rowcount�r r9 �� __class__r r r] � s ���z PGDialect_psycopg2.initializec C s dd l }|S )Nr )rD )�clsrD r r r � import_dbapi� s z PGDialect_psycopg2.import_dbapic C s ddl m} |S )Nr )� extensions)rD rh )rf rh r r r �_psycopg2_extensions� s z'PGDialect_psycopg2._psycopg2_extensionsc C s ddl m} |S )Nr ��extras)rD rk )rf rk r r r r, � s z#PGDialect_psycopg2._psycopg2_extrasc C s | j }|j|j|j|j|jd�S )N)Z AUTOCOMMITzREAD COMMITTEDzREAD UNCOMMITTEDzREPEATABLE READZ SERIALIZABLE)ri ZISOLATION_LEVEL_AUTOCOMMITZ ISOLATION_LEVEL_READ_COMMITTEDZ ISOLATION_LEVEL_READ_UNCOMMITTEDZ ISOLATION_LEVEL_REPEATABLE_READZ ISOLATION_LEVEL_SERIALIZABLE)r rh r r r �_isolation_lookup� s �z$PGDialect_psycopg2._isolation_lookupc C s |� | j| � d S r )�set_isolation_levelrl )r r` �levelr r r rm � s z&PGDialect_psycopg2.set_isolation_levelc C s ||_ d S r ��readonly�r r9 r' r r r � set_readonly� s z PGDialect_psycopg2.set_readonlyc C s |j S r ro rc r r r � get_readonly� s z PGDialect_psycopg2.get_readonlyc C s ||_ d S r �Z deferrablerq r r r �set_deferrable� s z!PGDialect_psycopg2.set_deferrablec C s |j S r rt rc r r r �get_deferrable� s z!PGDialect_psycopg2.get_deferrablec s� �j � g ��jd ur*�fdd�}��|� �jrF� fdd�}��|� �jrj�jrj� �fdd�}��|� �jr��jr�� �fdd�}��|� �r��fdd�}|S d S d S )Nc s | � � j� d S r )Zset_client_encoding�client_encoding�� dbapi_connr7 r r � on_connect� s z1PGDialect_psycopg2.on_connect.<locals>.on_connectc s � � d | � d S r )Z register_uuidrx rj r r rz � s c s@ �� | �}|d ur<|\}}d|i}||d< � j| fi |�� d S )N�oid� array_oid)r_ Zregister_hstore)ry Z hstore_oidsr{ r| �kw�rk r r r rz � s c s$ � j | �jd� � j| �jd� d S )N)�loads)Zregister_default_json�_json_deserializerZregister_default_jsonbrx r~ r r rz s ��c s � D ] }|| � qd S r r )ry �fn)�fnsr r rz s )r, rw �appendrR r^ r� )r rz r )rk r� r r rz � s$ z PGDialect_psycopg2.on_connectNc C sJ | j tu r:| jr d| ji}ni }| jj|||fi |�� n |�||� d S )NZ page_size)rG rC rQ r, Z execute_batchZ executemany)r r6 Z statement� parameters�contextrZ r r r �do_executemany s ��z!PGDialect_psycopg2.do_executemanyc C s |j �|� d S r )r9 Z tpc_begin�r r9 �xidr r r �do_begin_twophase" s z$PGDialect_psycopg2.do_begin_twophasec C s |j �� d S r )r9 Z tpc_preparer� r r r �do_prepare_twophase% s z&PGDialect_psycopg2.do_prepare_twophasec C s. |r$|j | jjkr|�� ||� n|� d S r )�statusri Z STATUS_READY�rollback)r ry Z operationr� �recoverr r r � _do_twophase( s z PGDialect_psycopg2._do_twophasec C s |j j}| j||j||d� d S �N)r� )r9 r` r� Z tpc_rollback�r r9 r� Z is_preparedr� ry r r r �do_rollback_twophase0 s �z'PGDialect_psycopg2.do_rollback_twophasec C s |j j}| j||j||d� d S r� )r9 r` r� Z tpc_commitr� r r r �do_commit_twophase8 s �z%PGDialect_psycopg2.do_commit_twophasec C s6 | j }|j�|�}|d ur.|d r.|dd� S d S d S )Nr rM )r, Z HstoreAdapterZget_oids)r r` rk Zoidsr r r r_ @ s z PGDialect_psycopg2._hstore_oidsc C sh t || jj�rdt|dd�r dS t|��d�d }| jD ],}|�|�}|dkr6d|d |� vr6 dS q6dS )N�closedFT� r �")r rR �Errorr* �str� partition�_is_disconnect_messages�find)r �er9 r6 Zstr_e�msg�idxr r r � is_disconnectI s z PGDialect_psycopg2.is_disconnectc C s dS )N)zterminating connectionzclosed the connectionzconnection not openz"could not receive data from serverz could not send data to serverzconnection already closedzcursor already closedz!losed the connection unexpectedlyz'connection has been closed unexpectedlyz.SSL error: decryption failed or bad record macz&SSL SYSCALL error: Bad file descriptorz SSL SYSCALL error: EOF detectedz&SSL SYSCALL error: Operation timed outz SSL SYSCALL error: Bad addresszSSL SYSCALL error: Successr r7 r r r r� [ s z*PGDialect_psycopg2._is_disconnect_messages)rE rF )N)F)TF)TF)=r r r ZdriverZsupports_statement_cacheZ supports_server_side_cursorsZdefault_paramstylerb r4 Zexecution_ctx_clsr@ �preparerrX Z!use_insertmanyvalues_wo_returningZreturns_native_bytesra r Z update_copyr Zcolspecsr r �sqltypesr r r Z INT4RANGEr/ Z INT8RANGEZNUMRANGEZ DATERANGEr1 ZTSRANGEr2 Z TSTZRANGEr3 rO r] � classmethodrg Zmemoized_propertyri r, rl rm rr rs ru rv rz r� r� r� r� r� r� Zmemoized_instancemethodr_ r� r� � __classcell__r r rd r r+ a sn �� � ( 4 � � r+ ),�__doc__� __future__r �collections.abc�abcr: �loggingrT �typingr � r Z_psycopg_commonr r �baser �jsonr r r r� r r r � getLoggerr< r r ZAbstractSingleRangeImplr r/ r1 r2 r3 r4 r@ rA � __members__�valuesrB rC r+ r r r r r �<module> sJ e � sqlalchemy/dialects/postgresql/__pycache__/_psycopg_common.cpython-39.pyc 0000644 00000013102 15125143220 0022725 0 ustar 00 a ��Jh* � @ sN d dl mZ d dlZddlmZ ddlmZ ddlmZ ddlm Z ddlm Z dd lm Z dd l m Z dd lmZ dd lmZ dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ e�� ZG dd� dej�Z G dd� de �Z G dd� de �Z G dd� de�Z G dd � d ee�Z G d d � d ee�Z!G d d � d e �Z"G d!d"� d"e �Z#dS )#� )� annotationsN� )�ARRAY)�_DECIMAL_TYPES)� _FLOAT_TYPES)� _INT_TYPES)� PGDialect)�PGExecutionContext)�HSTORE)� _SpaceVector)� INT2VECTOR)� OIDVECTOR� )�exc)�types)�util)� processorsc @ s e Zd Zdd� Zdd� ZdS )�_PsycopgNumericc C s d S �N� ��self�dialectr r �c/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/postgresql/_psycopg_common.py�bind_processor s z _PsycopgNumeric.bind_processorc C sv | j rB|tv r t�tj| j�S |tv s.|tv r2d S t � d| ��n0|tv rNd S |tv s^|tv rdtj S t � d| ��d S )NzUnknown PG numeric type: %d) Z asdecimalr r Z to_decimal_processor_factory�decimal�DecimalZ _effective_decimal_return_scaler r r ZInvalidRequestErrorZto_float�r r Zcoltyper r r �result_processor" s" ���z _PsycopgNumeric.result_processorN)�__name__� __module__� __qualname__r r r r r r r s r c @ s e Zd ZdZdS )� _PsycopgFloat�floatN)r r r! Z__visit_name__r r r r r" ; s r" c s( e Zd Z� fdd�Z� fdd�Z� ZS )�_PsycopgHStorec s |j r d S t� �|�S d S r )�_has_native_hstore�superr r �� __class__r r r @ s z _PsycopgHStore.bind_processorc s |j r d S t� �||�S d S r )r% r& r r r' r r r F s z _PsycopgHStore.result_processor)r r r! r r � __classcell__r r r' r r$ ? s r$ c @ s e Zd ZdZdS )� _PsycopgARRAYTN)r r r! Zrender_bind_castr r r r r* M s r* c @ s e Zd ZdS )�_PsycopgINT2VECTORN�r r r! r r r r r+ Q s r+ c @ s e Zd ZdS )�_PsycopgOIDVECTORNr, r r r r r- U s r- c @ s e Zd Zdd� ZdS )�"_PGExecutionContext_common_psycopgc C s6 dt t| ��dd � t t� �dd � f }| j�|�S )Nzc_%s_%s� )�hex�id�_server_side_idZ_dbapi_connection�cursor)r �identr r r �create_server_side_cursorZ s *z<_PGExecutionContext_common_psycopg.create_server_side_cursorN)r r r! r5 r r r r r. Y s r. c @ s� e Zd ZdZdZdZdZe�e j e j e e jeeee jeeeeei�Z ddd�Zdd� Zdd � Zd d � Zd d � Z dd� Z dd� Z dS )�_PGDialect_common_psycopgTZpyformatNc K s, t j| fi |�� |s d| _|| _|| _d S )NF)r �__init__r% �use_native_hstore�client_encoding)r r9 r8 �kwargsr r r r7 x s z"_PGDialect_common_psycopg.__init__c C s� |j ddd�}| �|�\}}|s&|jr�|s.i }d|v rFt|d �|d< |�|j� |r�d�|�|d< d�dd� |D ��}|r�||d< g |fS d g|fS d S ) N�userZdbname)�usernameZdatabase�port�,�hostc s s | ]}|rt |�nd V qdS )� N)�str)�.0�pr r r � <genexpr>� � z@_PGDialect_common_psycopg.create_connect_args.<locals>.<genexpr>r@ )Ztranslate_connect_argsZ_split_multihost_from_url�query�int�update�join)r �url�optsZ multihostsZ multiportsZ comma_portsr r r �create_connect_args� s z-_PGDialect_common_psycopg.create_connect_argsc C s dS )N)Z AUTOCOMMITzREAD COMMITTEDzREAD UNCOMMITTEDzREPEATABLE READZ SERIALIZABLEr )r �dbapi_connectionr r r �get_isolation_level_values� s z4_PGDialect_common_psycopg.get_isolation_level_valuesc C s ||_ d S r �Z deferrable�r � connection�valuer r r �set_deferrable� s z(_PGDialect_common_psycopg.set_deferrablec C s |j S r rO )r rQ r r r �get_deferrable� s z(_PGDialect_common_psycopg.get_deferrablec C s ||_ d S r )� autocommitrP r r r �_do_autocommit� s z(_PGDialect_common_psycopg._do_autocommitc C s` |j }|sd|_ |�� }z(|�| j� W |�� |s\|js\||_ n|�� |sZ|jsZ||_ 0 dS )NT)rU r3 �executeZ _dialect_specific_select_one�close�closed)r rM Zbefore_autocommitr3 r r r �do_ping� s � z!_PGDialect_common_psycopg.do_ping)NT) r r r! Zsupports_statement_cacheZ supports_server_side_cursorsZdefault_paramstyler% r Z update_copyr Zcolspecs�sqltypes�Numericr ZFloatr" r r$ r r* r r+ r r- r7 rL rN rS rT rV rZ r r r r r6 d s. �� � r6 )$� __future__r r �arrayr ZPGARRAY�baser r r r r Zhstorer Z pg_catalogr r r r@ r r r[ r Zenginer �counterr2 r\ r r" r$ r* r+ r- r. r6 r r r r �<module> s0 sqlalchemy/dialects/postgresql/__pycache__/psycopg2cffi.cpython-39.pyc 0000644 00000003453 15125143220 0022140 0 ustar 00 a ��Jh� � @ s4 d Z ddlmZ ddlmZ G dd� de�ZeZdS )a� .. dialect:: postgresql+psycopg2cffi :name: psycopg2cffi :dbapi: psycopg2cffi :connectstring: postgresql+psycopg2cffi://user:password@host:port/dbname[?key=value&key=value...] :url: https://pypi.org/project/psycopg2cffi/ ``psycopg2cffi`` is an adaptation of ``psycopg2``, using CFFI for the C layer. This makes it suitable for use in e.g. PyPy. Documentation is as per ``psycopg2``. .. seealso:: :mod:`sqlalchemy.dialects.postgresql.psycopg2` � )�PGDialect_psycopg2� )�utilc @ sR e Zd ZdZdZdZedddddd�Zedd� �Z e j dd � �Z e j d d � �Z d S ) �PGDialect_psycopg2cffi� psycopg2cffiT)� � r )r � r )Z native_jsonZ native_jsonbZsane_multi_rowcountZ array_oidZhstore_adapterc C s t d�S )Nr )� __import__)�cls� r �`/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/postgresql/psycopg2cffi.py� import_dbapi. s z#PGDialect_psycopg2cffi.import_dbapic C s t ddgd�}|jS )Nr � extensions��fromlist)r r �r �rootr r r �_psycopg2_extensions2 s z+PGDialect_psycopg2cffi._psycopg2_extensionsc C s t ddgd�}|jS )Nr �extrasr )r r r r r r �_psycopg2_extras7 s z'PGDialect_psycopg2cffi._psycopg2_extrasN)�__name__� __module__� __qualname__ZdriverZsupports_unicode_statementsZsupports_statement_cache�dictZFEATURE_VERSION_MAP� classmethodr r Zmemoized_propertyr r r r r r r s � r N)�__doc__Zpsycopg2r � r r �dialectr r r r �<module> s sqlalchemy/dialects/postgresql/__pycache__/dml.cpython-39.pyc 0000644 00000024277 15125143220 0020325 0 ustar 00 a ��Jh^/ � @ s� d dl mZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ ddlm Z d d l m Z d d l m Z d d l m Z d d l mZ d dl mZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddl m Z ddl m Z ddl m!Z! dd l m"Z" dd l m#Z# dd l$m%Z% dd l&m'Z' d Z(d!d"d#�d$d%�Z)G d&d"� d"e �Z G d'd(� d(e �Z*G d)d*� d*e*�Z+G d+d,� d,e*�Z,d-S ).� )� annotations)�Any)�List)�Optional)�Tuple)�Union� )�ext� )�_OnConflictConstraintT)�_OnConflictIndexElementsT)�_OnConflictIndexWhereT)�_OnConflictSetT)�_OnConflictWhereT� )�util)� coercions)�roles)�schema)�_DMLTableArgument)�_exclusive_against)� _generative)�ColumnCollection)�ReadOnlyColumnCollection��Insert)� ClauseElement)� ColumnElement)�KeyedColumnElement)� TextClause)�alias)�Self)r �insertr r )�table�returnc C s t | �S )as Construct a PostgreSQL-specific variant :class:`_postgresql.Insert` construct. .. container:: inherited_member The :func:`sqlalchemy.dialects.postgresql.insert` function creates a :class:`sqlalchemy.dialects.postgresql.Insert`. This class is based on the dialect-agnostic :class:`_sql.Insert` construct which may be constructed using the :func:`_sql.insert` function in SQLAlchemy Core. The :class:`_postgresql.Insert` construct includes additional methods :meth:`_postgresql.Insert.on_conflict_do_update`, :meth:`_postgresql.Insert.on_conflict_do_nothing`. r )r# � r% �W/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/postgresql/dml.pyr" * s r" c @ s| e Zd ZdZdZdZejdd�dd��Ze ddd id �Z e e dd d ddddd�dd���Z e e dd d ddd�dd���Z d S )r z�PostgreSQL-specific implementation of INSERT. Adds methods for PG-specific syntaxes such as ON CONFLICT. The :class:`_postgresql.Insert` object is created using the :func:`sqlalchemy.dialects.postgresql.insert` function. � postgresqlFz6ReadOnlyColumnCollection[str, KeyedColumnElement[Any]])r$ c C s t | jdd�jS )ak Provide the ``excluded`` namespace for an ON CONFLICT statement PG's ON CONFLICT clause allows reference to the row that would be inserted, known as ``excluded``. This attribute provides all columns in this row to be referenceable. .. tip:: The :attr:`_postgresql.Insert.excluded` attribute is an instance of :class:`_expression.ColumnCollection`, which provides an interface the same as that of the :attr:`_schema.Table.c` collection described at :ref:`metadata_tables_and_columns`. With this collection, ordinary names are accessible like attributes (e.g. ``stmt.excluded.some_column``), but special names and dictionary method names should be accessed using indexed access, such as ``stmt.excluded["column name"]`` or ``stmt.excluded["values"]``. See the docstring for :class:`_expression.ColumnCollection` for further examples. .. seealso:: :ref:`postgresql_insert_on_conflict` - example of how to use :attr:`_expression.Insert.excluded` �excluded)�name)r r# �columns)�selfr% r% r& r( K s zInsert.excluded�_post_values_clausezCThis Insert construct already has an ON CONFLICT clause established)ZmsgsNr r r r r r! )� constraint�index_elements� index_where�set_�wherer$ c C s t |||||�| _| S )a$ Specifies a DO UPDATE SET action for ON CONFLICT clause. Either the ``constraint`` or ``index_elements`` argument is required, but only one of these can be specified. :param constraint: The name of a unique or exclusion constraint on the table, or the constraint object itself if it has a .name attribute. :param index_elements: A sequence consisting of string column names, :class:`_schema.Column` objects, or other column expression objects that will be used to infer a target index. :param index_where: Additional WHERE criterion that can be used to infer a conditional target index. :param set\_: A dictionary or other mapping object where the keys are either names of columns in the target table, or :class:`_schema.Column` objects or other ORM-mapped columns matching that of the target table, and expressions or literals as values, specifying the ``SET`` actions to take. .. versionadded:: 1.4 The :paramref:`_postgresql.Insert.on_conflict_do_update.set_` parameter supports :class:`_schema.Column` objects from the target :class:`_schema.Table` as keys. .. warning:: This dictionary does **not** take into account Python-specified default UPDATE values or generation functions, e.g. those specified using :paramref:`_schema.Column.onupdate`. These values will not be exercised for an ON CONFLICT style of UPDATE, unless they are manually specified in the :paramref:`.Insert.on_conflict_do_update.set_` dictionary. :param where: Optional argument. An expression object representing a ``WHERE`` clause that restricts the rows affected by ``DO UPDATE SET``. Rows not meeting the ``WHERE`` condition will not be updated (effectively a ``DO NOTHING`` for those rows). .. seealso:: :ref:`postgresql_insert_on_conflict` )�OnConflictDoUpdater, �r+ r- r. r/ r0 r1 r% r% r& �on_conflict_do_updatep s < �z Insert.on_conflict_do_update)r- r. r/ r$ c C s t |||�| _| S )a Specifies a DO NOTHING action for ON CONFLICT clause. The ``constraint`` and ``index_elements`` arguments are optional, but only one of these can be specified. :param constraint: The name of a unique or exclusion constraint on the table, or the constraint object itself if it has a .name attribute. :param index_elements: A sequence consisting of string column names, :class:`_schema.Column` objects, or other column expression objects that will be used to infer a target index. :param index_where: Additional WHERE criterion that can be used to infer a conditional target index. .. seealso:: :ref:`postgresql_insert_on_conflict` )�OnConflictDoNothingr, �r+ r- r. r/ r% r% r& �on_conflict_do_nothing� s �z Insert.on_conflict_do_nothing)NNNNN)NNN)�__name__� __module__� __qualname__�__doc__�stringify_dialectZ inherit_cacher Zmemoized_propertyr( r Z_on_conflict_exclusiver r4 r7 r% r% r% r& r > s0 �� � ? �c @ s> e Zd ZU dZded< ded< ded< dd d d d �d d�ZdS )�OnConflictClauser' z Optional[str]�constraint_targetz.Optional[List[Union[str, schema.Column[Any]]]]�inferred_target_elementsz/Optional[Union[ColumnElement[Any], TextClause]]�inferred_target_whereclauseNr r r �r- r. r/ c C s. |d ur2t |t�s2t |tjtjf�r2t|d�p0|}|d ur�|d urJtd��t |t�rh|| _d | _ d | _ nTt |tj �r�|j }|j d �d�}n0t |tj�r�|j}|j}n|j}|j d �d�}|d u�rd | _dd� |D �| _ |d u�rt�t |tj�r�tjntj|�nd | _ n |d u �r*d | _ | _ | _ d S )Nr) z8'constraint' and 'index_elements' are mutually exclusiver' r1 c S s g | ]}t �tj|��qS r% )r �expectr ZDDLConstraintColumnRole)�.0�columnr% r% r& � <listcomp> s �z-OnConflictClause.__init__.<locals>.<listcomp>)� isinstance�strr � Constraintr ZExcludeConstraint�getattr� ValueErrorr> r? r@ �IndexZ expressionsZdialect_options�getr* r1 r rB r ZStatementOptionRole�WhereHavingRoler6 r% r% r& �__init__� s\ �� � � �� �� � � �zOnConflictClause.__init__)NNN)r8 r9 r: r< �__annotations__rN r% r% r% r& r= � s �r= c @ s e Zd ZdZdS )r5 r7 N)r8 r9 r: �__visit_name__r% r% r% r& r5 s r5 c sB e Zd ZU dZded< ded< dddd d d d �� fd d� Z� ZS )r2 r4 z0List[Tuple[Union[schema.Column[Any], str], Any]]�update_values_to_setz Optional[ColumnElement[Any]]�update_whereclauseNr r r r r )r- r. r/ r0 r1 c s� t � j|||d� | jd u r.| jd u r.td��t|t�rF|sbtd��n t|t�rZt|�}ntd��dd� |�� D �| _ |d ur�t � t j |�nd | _d S )NrA zVEither constraint or index_elements, but not both, must be specified unless DO NOTHINGz*set parameter dictionary must not be emptyzqset parameter must be a non-empty dictionary or a ColumnCollection such as the `.c.` collection of a Table objectc S s" g | ]\}}t �tj|�|f�qS r% )r rB r Z DMLColumnRole)rC �key�valuer% r% r& rE K s �z/OnConflictDoUpdate.__init__.<locals>.<listcomp>)�superrN r? r> rJ rF �dictr �itemsrQ r rB r rM rR r3 �� __class__r% r& rN ) s6 ���� ����zOnConflictDoUpdate.__init__)NNNNN)r8 r9 r: rP rO rN � __classcell__r% r% rX r& r2 # s �r2 N)-� __future__r �typingr r r r r � r Z_typingr r r r r r Zsqlr r r Z sql._typingr Zsql.baser r r r Zsql.dmlr ZStandardInsertZ sql.elementsr r r r Zsql.expressionr Z util.typingr! �__all__r" r= r5 r2 r% r% r% r& �<module> sD H sqlalchemy/dialects/postgresql/__pycache__/__init__.cpython-39.pyc 0000644 00000006232 15125143220 0021277 0 ustar 00 a ��Jh4 � @ s� d dl mZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z dd lm Z dd lm Z dd lm Z dd lm Z ddlmZ dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddl m Z dd l m Z dd l m Z dd l m!Z! dd l m"Z" dd l m#Z# dd!l m$Z$ dd"l m%Z% dd#l m&Z& dd$l m'Z' dd%l m(Z( dd&l)m*Z* dd'l)m)Z) dd(l+m,Z, dd)l+m-Z- dd*l+m.Z. dd+l/m0Z0 dd,l/m1Z1 dd-l/m2Z2 dd.l/m3Z3 dd/l/m4Z4 dd0l/m5Z5 dd1l6m7Z7 dd2l6m8Z8 dd3l6m9Z9 dd4l6m:Z: dd5l6m;Z; dd6l6m<Z< dd7l6m=Z= dd8l6m>Z> dd9l6m?Z? dd:l6m@Z@ dd;l6mAZA dd<l6mBZB dd=l6mCZC dd>l6mDZD dd?l6mEZE dd@l6mFZF ddAl6mGZG ddBl mHZH ddCl mIZI ddDl mJZJ ddEl mKZK ddFl mLZL ddGl mMZM ddHl mNZN ddIl mOZO ddJl mPZP ddKl mQZQ ddLl mRZR ddMl mSZS ddNl mTZT ddOl mUZU ddPl mVZV ddQl mWZW eXdRefdSejYi�ZZe j[ e_[Z[dTZ\dUS )V� )� ModuleType� )�array)�asyncpg)�base)�pg8000)�psycopg)�psycopg2)� psycopg2cffi)�All)�Any)�ARRAY)�BIGINT)�BOOLEAN)�CHAR)�DATE)�DOMAIN)�DOUBLE_PRECISION)�FLOAT)�INTEGER)�NUMERIC)�REAL)�SMALLINT)�TEXT)�UUID)�VARCHAR)�Insert)�insert)�aggregate_order_by)� array_agg)�ExcludeConstraint)�phraseto_tsquery)�plainto_tsquery)� to_tsquery)� to_tsvector)� ts_headline)�websearch_to_tsquery)�HSTORE)�hstore)�JSON)�JSONB)�JSONPATH)�CreateDomainType)�CreateEnumType)�DropDomainType)� DropEnumType)�ENUM)� NamedType)�AbstractMultiRange)� AbstractRange)�AbstractSingleRange)�DATEMULTIRANGE)� DATERANGE)�INT4MULTIRANGE)� INT4RANGE)�INT8MULTIRANGE)� INT8RANGE)� MultiRange)� NUMMULTIRANGE)�NUMRANGE)�Range)� TSMULTIRANGE)�TSRANGE)�TSTZMULTIRANGE)� TSTZRANGE)�BIT)�BYTEA)�CIDR)�CITEXT)�INET)�INTERVAL)�MACADDR)�MACADDR8)�MONEY)�OID)�REGCLASS)� REGCONFIG)�TIME)� TIMESTAMP)�TSQUERY)�TSVECTOR� psycopg_async�dialect)Ar r r r r r r r r rG rE rF r rC rI rJ rK rL rM rN rQ rR r rP rO r rD r rH r r0 r rT r r' r( r8 r: r= r6 r7 r9 r< r5 rR r@ rB r? rA r) r* r+ r r r/ r. r, r1 r- r r> r r r r N)]�typesr � r Zarraylibr r r r r r r r r r r r r r r r r r r r r r r Zdmlr r �extr r r r! r" r# r$ r% r& r( r' �jsonr) r* r+ Z named_typesr, r- r. r/ r0 r1 �rangesr2 r3 r4 r5 r6 r7 r8 r9 r: r; r< r= r> r? r@ rA rB rC rD rE rF rG rH rI rJ rK rL rM rN rO rP rQ rR �typeZ dialect_asyncrS rT �__all__� r\ r\ �\/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/postgresql/__init__.py�<module> s� � sqlalchemy/dialects/postgresql/__pycache__/pg_catalog.cpython-39.pyc 0000644 00000016130 15125143220 0021636 0 ustar 00 a ��Jh�% � # @ s� d dl mZ d dlmZ d dlmZ d dlmZ d dlmZ ddlmZ ddl m Z dd l m Z d d l m Z d d l mZ d d l mZ d dl mZ d dl mZ d dl mZ d dl mZ d dl mZ d dl mZ d dl mZ d dl mZ d dl mZ d dl mZ e�rd dlmZ d dl m Z G dd� dee �Z G d d � d ee �Z G d d � d eee! �Z"G d d!� d!eee! �Z#G d"d#� d#�Z$e Z%ej&Z'e'j(Z(e'j)Z)e'j*Z*e'j+Z+e'j,Z,e'j-Z-e'j.Z.e'j/Z/e'j0Z0d$Z1e1d% Z2d&Z3d'Z4e2e3 e4 Z5ed(d)�Z6ed*e6e d+e �e d,e �e d-e ��Z7ed.e6e d+e d/d0id1�e d2e �e d3e �e d4e �e d5e �e d6e �e d7e �e d8e �e d9e �e d:e�e d;e�e d<ed/d=id1�e d>e �e d?e�e d@e�e dAed/dBid1�e dCe�e dDe�e dEe�e dFe�e dGe�e dHe�e dIe�e dJed/dKid1�e dLed/d0id1�e dMed/dNid1�e dOed/dPid1�e dQe d/dRid1�e dSee��� Z8edTe6e d+e d/d0id1�e dUe �e dVe �e dWe �e dXe�e dYe�e dZe�e d[e�e d\e�e d]e�e d^e�e d_e �e d`e �e dae �e dbe%�e dce%�e dde%�e dee%�e dfe%�e dge%�e dhe%�e die�e dje�e dke�e dle �e dme�e dne�e doe d/dBid1�e dpe�� Z9edqe6e dre �e dse �e dte�e dued/dRid1�e dve�e dwed/dxid1�e dye�e dzed/dBid1�e d{e�e d|e�e d}e�e d~e�e de�e d�ed/d0id1�e d�e�e d�e"�e d�e#d/dBid1�e d�e#�e d�e"�e d�e �e d�e ��Z:ed�e6e d�e �e d�e �e d�e �e d�e�e d�e�e d�e�e d�e�e d�e�e d�e�e d�e�e d�e�e d�e�e d�e�e d�e�e d�ed/dRid1�e d�ed/dPid1�e d�ed/d�id1�e d�e�e d�e�e d�e�e d�e d/dBid1��Z;ed�e6e d+e �e d�e �e d�e �e d�e�e d�e�e d�e�e d�ed/dBid1�e d�e �e d�e �e d�e �e d�e d/dRid1�e d�e �e d�e�e d�e�e d�e�e d�e�e d�e�e d�ed/d=id1�e d�ee��e d�ee���Z<ed�e6e d�e �e d�e �e d�e�e d�e�e d�e�e d�e�e d�e�e d�e�d/dPid1� Z=ed�e6e d+e d/d0id1�e d�e �e d�e�e d�e ��Z>ed�e6e d�e �e d�e �e d�e�e d�ed�dƍ��Z?ed�e6e d+e d/d0id1�e d�e �e d�e� d/dBid1�e d�e ��Z@ed�e6e d+e d/d0id1�e d�e �e d�e%d/d�id1�e d�ed/d�id1��ZAed�e6e d+e d/d0id1�e d�e �e d�e �e d�e �e d�ed/dPid1�e d�ed/d�id1�e d�e�e d�e�e d�e�e d�e�e d�ed/d�id1�e d�ed/dPid1��ZBd�S )�� )� annotations)�Any)�Optional)�Sequence)� TYPE_CHECKING� )�ARRAY)�OID)�REGCLASS� )�Column)�func)�MetaData)�Table)� BigInteger)�Boolean)�CHAR)�Float)�Integer)� SmallInteger)�String)�Text)� TypeDecorator)�Dialect)�_ResultProcessorTypec @ s e Zd Zeddd�ZdZdS )�NAME�@ �C�Z collationTN)�__name__� __module__� __qualname__r �impl�cache_ok� r$ r$ �^/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/postgresql/pg_catalog.pyr & s r c @ s e Zd Zedd�ZdZdS )� PG_NODE_TREEr r TN)r r r! r r" r# r$ r$ r$ r% r& + s r& c @ s e Zd Zee�ZdZdS )� INT2VECTORTN)r r r! r r r" r# r$ r$ r$ r% r' 0 s r' c @ s e Zd Zee�ZdZdS )� OIDVECTORTN)r r r! r r r" r# r$ r$ r$ r% r( 5 s r( c @ s e Zd Zdddd�dd�ZdS )� _SpaceVectorr �objectz _ResultProcessorType[list[int]])�dialect�coltype�returnc C s ddd�dd�}|S )Nr zOptional[list[int]])�valuer- c S s | d u r | S dd� | � d�D �S )Nc S s g | ] }t |��qS r$ )�int)�.0�pr$ r$ r% � <listcomp>A � zB_SpaceVector.result_processor.<locals>.process.<locals>.<listcomp>� )�split)r. r$ r$ r% �process> s z._SpaceVector.result_processor.<locals>.processr$ )�selfr+ r, r6 r$ r$ r% �result_processor; s z _SpaceVector.result_processorN)r r r! r8 r$ r$ r$ r% r) : s r) )�rr1 )�f)�v)�m� pg_catalog)Zschema� pg_namespace�oidZnspnameZnspowner�pg_classZserver_version)� r )�infoZrelnameZ relnamespaceZreltypeZ reloftypeZrelownerZrelamZ relfilenodeZ reltablespaceZrelpagesZ reltuplesZ relallvisible)rA � Z reltoastrelidZ relhasindexZ relissharedZrelpersistence)rA r ZrelkindZrelnattsZ relchecksZ relhasrulesZrelhastriggersZrelhassubclassZrelrowsecurityZrelforcerowsecurity)rA � ZrelispopulatedZ relreplident)rA � Zrelispartition)� Z relrewrite)� Z reloptions�pg_typeZtypnameZ typnamespaceZtypownerZtyplenZtypbyvalZtyptypeZ typcategoryZtypispreferredZ typisdefinedZtypdelimZtyprelidZtypelemZtyparrayZtypinputZ typoutputZ typreceiveZtypsendZtypmodinZ typmodoutZ typanalyzeZtypalignZ typstorageZ typnotnullZ typbasetypeZ typtypmodZtypndimsZ typcollationZ typdefault�pg_indexZ indexrelidZindrelidZindnattsZ indnkeyattsZ indisuniqueZindnullsnotdistinct)� Z indisprimaryZindisexclusionZ indimmediateZindisclusteredZ indisvalidZ indcheckxminZ indisreadyZ indisliveZindisreplidentZindkeyZ indcollationZindclassZ indoptionZindexprsZindpred� pg_attributeZattrelidZattnameZatttypidZ attstattargetZattlenZattnumZattndimsZ attcacheoffZ atttypmodZattbyvalZ attstorageZattalignZ attnotnullZ atthasdefZ atthasmissingZ attidentityZ attgenerated)� Z attisdroppedZ attislocalZ attinhcountZ attcollation� pg_constraintZconnameZ connamespaceZcontypeZ condeferrableZ condeferredZ convalidatedZconrelidZcontypidZconindidZ conparentidZ confrelidZ confupdtypeZ confdeltypeZ confmatchtypeZ conislocalZ coninhcountZ connoinheritZconkeyZconfkey� pg_sequenceZseqrelidZseqtypidZseqstartZ seqincrementZseqmaxZseqminZseqcacheZseqcycle� pg_attrdefZadrelidZadnumZadbin�pg_descriptionZobjoidZclassoidZobjsubid� descriptionr r �pg_enumZ enumtypidZ enumsortorderZ enumlabel�pg_amZamnameZ amhandler)rA � Zamtype� pg_collationZcollnameZ collnamespaceZ collownerZ collproviderZcollisdeterministicZ collencodingZ collcollateZ collctypeZ colliculocaleZ collicurules)� Z collversionN)C� __future__r �typingr r r r �arrayr �typesr r � r r r r r r r r r r r r r Zengine.interfacesr Z sql.type_apir �strr r& r/ r' r( r) ZREGPROCr= Z_pg_catZ quote_identZpg_table_is_visibleZpg_type_is_visibleZpg_get_viewdefZpg_get_serial_sequenceZ format_typeZ pg_get_exprZpg_get_constraintdefZpg_get_indexdefZRELKINDS_TABLE_NO_FOREIGNZRELKINDS_TABLEZ RELKINDS_VIEWZRELKINDS_MAT_VIEWZRELKINDS_ALL_TABLE_LIKEZpg_catalog_metar> r@ rH rI rK rM rN rO rP rR rS rU r$ r$ r$ r% �<module> s� � �"�"�� ��� � � � � sqlalchemy/dialects/postgresql/__pycache__/hstore.cpython-39.pyc 0000644 00000027656 15125143220 0021061 0 ustar 00 a ��Jh�. � @ sZ d dl Z ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ dd lm Z d d l m Z d d l mZ d ZG dd� de je je j�ZG dd� dej�ZG dd� dej�ZG dd� dej�ZG dd� dej�ZG dd� dej�ZG dd� dej�ZG d d � d ej�Z G d d � d ej�Z e � d e j �Z e � d!e j �Z!d"d#� Z"d$d%� Z#d&d'� Z$dS )(� N� )�ARRAY)� CONTAINED_BY)�CONTAINS)�GETITEM)�HAS_ALL)�HAS_ANY)�HAS_KEY� )�types)� functions)�HSTORE�hstorec @ sX e Zd ZdZd ZdZe�� Zd dd�Z G dd� dej j ej j �Z e Z dd � Zd d � ZdS ) r a/ Represent the PostgreSQL HSTORE type. The :class:`.HSTORE` type stores dictionaries containing strings, e.g.:: data_table = Table( "data_table", metadata, Column("id", Integer, primary_key=True), Column("data", HSTORE), ) with engine.connect() as conn: conn.execute( data_table.insert(), data={"key1": "value1", "key2": "value2"} ) :class:`.HSTORE` provides for a wide range of operations, including: * Index operations:: data_table.c.data["some key"] == "some value" * Containment operations:: data_table.c.data.has_key("some key") data_table.c.data.has_all(["one", "two", "three"]) * Concatenation:: data_table.c.data + {"k1": "v1"} For a full list of special methods see :class:`.HSTORE.comparator_factory`. .. container:: topic **Detecting Changes in HSTORE columns when using the ORM** For usage with the SQLAlchemy ORM, it may be desirable to combine the usage of :class:`.HSTORE` with :class:`.MutableDict` dictionary now part of the :mod:`sqlalchemy.ext.mutable` extension. This extension will allow "in-place" changes to the dictionary, e.g. addition of new keys or replacement/removal of existing keys to/from the current dictionary, to produce events which will be detected by the unit of work:: from sqlalchemy.ext.mutable import MutableDict class MyClass(Base): __tablename__ = "data_table" id = Column(Integer, primary_key=True) data = Column(MutableDict.as_mutable(HSTORE)) my_object = session.query(MyClass).one() # in-place mutation, requires Mutable extension # in order for the ORM to detect my_object.data["some_key"] = "some value" session.commit() When the :mod:`sqlalchemy.ext.mutable` extension is not used, the ORM will not be alerted to any changes to the contents of an existing dictionary, unless that dictionary value is re-assigned to the HSTORE-attribute itself, thus generating a change event. .. seealso:: :class:`.hstore` - render the PostgreSQL ``hstore()`` function. FNc C s |dur|| _ dS )z�Construct a new :class:`.HSTORE`. :param text_type: the type that should be used for indexed values. Defaults to :class:`_types.Text`. N)� text_type)�selfr � r �Z/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/postgresql/hstore.py�__init__l s zHSTORE.__init__c @ sx e Zd ZdZdd� Zdd� Zdd� Zdd � Zd d � Zd d � Z dd� Z dd� Z dd� Z dd� Z dd� Zdd� Zdd� Zd S ) zHSTORE.Comparatorz2Define comparison operations for :class:`.HSTORE`.c C s | j t|tjd�S )zvBoolean expression. Test for presence of a key. Note that the key may be a SQLA expression. �Z result_type)�operater �sqltypes�Boolean�r �otherr r r �has_key{ s zHSTORE.Comparator.has_keyc C s | j t|tjd�S )z;Boolean expression. Test for presence of all keys in jsonbr )r r r r r r r r �has_all� s zHSTORE.Comparator.has_allc C s | j t|tjd�S )z:Boolean expression. Test for presence of any key in jsonbr )r r r r r r r r �has_any� s zHSTORE.Comparator.has_anyc K s | j t|tjd�S )z�Boolean expression. Test if keys (or array) are a superset of/contained the keys of the argument jsonb expression. kwargs may be ignored by this operator but are required for API conformance. r )r r r r )r r �kwargsr r r �contains� s zHSTORE.Comparator.containsc C s | j t|tjd�S )z|Boolean expression. Test if keys are a proper subset of the keys of the argument jsonb expression. r )r r r r r r r r � contained_by� s �z HSTORE.Comparator.contained_byc C s t || jjfS �N)r �typer )r �indexr r r �_setup_getitem� s z HSTORE.Comparator._setup_getitemc C s t | j|�S )z�Boolean expression. Test for presence of a non-NULL value for the key. Note that the key may be a SQLA expression. )�_HStoreDefinedFunction�expr�r �keyr r r �defined� s zHSTORE.Comparator.definedc C s t |t�rt|�}t| j|�S )z�HStore expression. Returns the contents of this hstore with the given key deleted. Note that the key may be a SQLA expression. )� isinstance�dict�_serialize_hstore�_HStoreDeleteFunctionr% r& r r r �delete� s zHSTORE.Comparator.deletec C s t | j|�S )zdHStore expression. Returns a subset of an hstore defined by array of keys. )�_HStoreSliceFunctionr% )r �arrayr r r �slice� s zHSTORE.Comparator.slicec C s t | j�S )z.Text array expression. Returns array of keys.)�_HStoreKeysFunctionr% �r r r r �keys� s zHSTORE.Comparator.keysc C s t | j�S )z0Text array expression. Returns array of values.)�_HStoreValsFunctionr% r2 r r r �vals� s zHSTORE.Comparator.valsc C s t | j�S )z^Text array expression. Returns array of alternating keys and values. )�_HStoreArrayFunctionr% r2 r r r r/ � s zHSTORE.Comparator.arrayc C s t | j�S )z<Text array expression. Returns array of [key, value] pairs.)�_HStoreMatrixFunctionr% r2 r r r �matrix� s zHSTORE.Comparator.matrixN)�__name__� __module__� __qualname__�__doc__r r r r r r# r( r- r0 r3 r5 r/ r8 r r r r � Comparatorv s r= c C s dd� }|S )Nc S s t | t�rt| �S | S d S r )r) r* r+ ��valuer r r �process� s z&HSTORE.bind_processor.<locals>.processr )r �dialectr@ r r r �bind_processor� s zHSTORE.bind_processorc C s dd� }|S )Nc S s | d urt | �S | S d S r )� _parse_hstorer> r r r r@ � s z(HSTORE.result_processor.<locals>.processr )r rA Zcoltyper@ r r r �result_processor� s zHSTORE.result_processor)N)r9 r: r; r< Z__visit_name__Zhashabler �Textr r � Indexabler= � ConcatenableZcomparator_factoryrB rD r r r r r s M �M r c @ s e Zd ZdZeZd ZdZdS )r aH Construct an hstore value within a SQL expression using the PostgreSQL ``hstore()`` function. The :class:`.hstore` function accepts one or two arguments as described in the PostgreSQL documentation. E.g.:: from sqlalchemy.dialects.postgresql import array, hstore select(hstore("key1", "value1")) select( hstore( array(["key1", "key2", "key3"]), array(["value1", "value2", "value3"]), ) ) .. seealso:: :class:`.HSTORE` - the PostgreSQL ``HSTORE`` datatype. TN)r9 r: r; r< r r! �name� inherit_cacher r r r r � s r c @ s e Zd ZejZdZdZdS )r$ r( TN)r9 r: r; r r r! rH rI r r r r r$ � s r$ c @ s e Zd ZeZdZdZdS )r, r- TN�r9 r: r; r r! rH rI r r r r r, s r, c @ s e Zd ZeZdZdZdS )r. r0 TNrJ r r r r r. s r. c @ s e Zd Zeej�ZdZdZdS )r1 ZakeysTN� r9 r: r; r r rE r! rH rI r r r r r1 s r1 c @ s e Zd Zeej�ZdZdZdS )r4 ZavalsTNrK r r r r r4 s r4 c @ s e Zd Zeej�ZdZdZdS )r6 Zhstore_to_arrayTNrK r r r r r6 s r6 c @ s e Zd Zeej�ZdZdZdS )r7 Zhstore_to_matrixTNrK r r r r r7 ! s r7 z� ( "(?P<key> (\\ . | [^"])* )" # Quoted key ) [ ]* => [ ]* # Pair operator, optional adjoining whitespace ( (?P<value_null> NULL ) # NULL value | "(?P<value> (\\ . | [^"])* )" # Quoted value ) z [ ]* , [ ]* c C s� d}t | �}| t|| d d�t||�� }| t||�t|| d |�� }t |�|krhd|dd� }t |�|kr�|dd� d }d|||f S )z format an unmarshalling error.� r r z[...]N���z5After %r, could not parse residual at position %d: %r)�len�max�min)� hstore_str�pos�ctxZhslenZ parsed_tailZresidualr r r � _parse_errorE s �rT c C s� i }d}t �| �}|dur�|�d��dd��dd�}|�d�rDd}n|�d ��dd��dd�}|||< ||�� 7 }t�| |d� �}|dur�||�� 7 }t �| |d� �}q|t| �kr�tt| |���|S ) a� Parse an hstore from its literal string representation. Attempts to approximate PG's hstore input parsing rules as closely as possible. Although currently this is not strictly necessary, since the current implementation of hstore's output syntax is stricter than what it accepts as input, the documentation makes no guarantees that will always be the case. r Nr' �\"�"�\\�\Z value_nullr? ) �HSTORE_PAIR_RE�match�group�replace�end�HSTORE_DELIMITER_RErN � ValueErrorrT )rQ �resultrR Z pair_matchr' r? Z delim_matchr r r rC Z s, ��� rC c s$ dd� � d� � fdd�| �� D ��S )zxSerialize a dictionary into an hstore literal. Keys and values must both be strings (except None for values). c S sJ |dkr| d u rdS t | t�r6d| �dd��dd� S td| |f ��d S ) Nr? ZNULLz"%s"rX rW rV rU z"%r in %s position is not a string.)r) �strr\ r_ )�s�positionr r r �esc� s �z _serialize_hstore.<locals>.escz, c 3 s* | ]"\}}d � |d�� |d�f V qdS )z%s=>%sr' r? Nr )�.0�k�v�rd r r � <genexpr>� s z$_serialize_hstore.<locals>.<genexpr>)�join�items)�valr rh r r+ � s �r+ )%�rer/ r � operatorsr r r r r r � r r Zsqlr Zsqlfunc�__all__rF rG Z TypeEnginer ZGenericFunctionr r$ r, r. r1 r4 r6 r7 �compile�VERBOSErY r^ rT rC r+ r r r r �<module> s> E ��* sqlalchemy/dialects/postgresql/__pycache__/provision.cpython-39.pyc 0000644 00000011423 15125143220 0021566 0 ustar 00 a ��Jh� � @ sf d dl Z ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z dd lm Z dd lm Z dd lm Z dd lm Z dd lmZ ddlmZ ddlmZ ddlmZ e�d�dd� �Ze �d�dd� �Ze�d�dd� �Ze�d�dd� �Ze �d�dd� �Z e �d�d d � �Z e�d�d d � �Ze�d�dd d!�d"d#��Zd$d%gZe �d�d&d'� �ZdS )(� N� )�exc)�inspect)�text)�warn_test_suite)� create_db)�#drop_all_schema_objects_post_tables)�"drop_all_schema_objects_pre_tables)�drop_db)�log)�post_configure_engine)�prepare_for_drop_tables)� set_default_schema_on_connection)�temp_table_keyword_args)�upsert� postgresqlc C s� | j j}|jdd��� ��}|s,|�d��� }d}z|�d||f � W q� tjy� } zF|d7 }|dkrj� dt|�v r�t � d ||j |� t � d � W Y d }~q0d }~0 � Y q00 q�q0W d � n1 s�0 Y d S ) N� AUTOCOMMIT�Zisolation_levelzselect current_database()r z CREATE DATABASE %s TEMPLATE %s� r zaccessed by other userszFWaiting to create %s, URI %r, template DB %s is in use sleeping for .5g �?)�optionsZpostgresql_templatedb�execution_options�begin�exec_driver_sqlZscalarr ZOperationalError�strr �info�url�time�sleep)�cfg�eng�identZ template_db�conn�attempt�err� r$ �]/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/postgresql/provision.py� _pg_create_db s4 � � � r& c C s� |� � jdd��\}|�� �4 |�td�t|d�� |�d| � W d � n1 sT0 Y W d � n1 sr0 Y d S )Nr r z�select pg_terminate_backend(pid) from pg_stat_activity where usename=current_user and pid != pg_backend_pid() and datname=:dname)ZdnamezDROP DATABASE %s)�connectr r �executer �dictr )r r r r! r$ r$ r% � _pg_drop_db> s ��r* c C s ddgiS )N�prefixes� TEMPORARYr$ )r r r$ r$ r% �#_postgresql_temp_table_keyword_argsM s r- c C s4 |j }d|_ |�� }|�d| � |�� ||_ d S )NTz SET SESSION search_path='%s')Z autocommit�cursorr( �close)r Zdbapi_connectionZ schema_nameZexisting_autocommitr. r$ r$ r% �,_postgresql_set_default_schema_on_connectionR s r0 c C sV |� � jdd��2}|�d��� D ]}|�d| � q W d � n1 sH0 Y d S )Nr r z!select gid from pg_prepared_xactszROLLBACK PREPARED '%s')r' r r Zscalars)r r r! �xidr$ r$ r% r ^ s � r c C sr ddl m} t|�}|�� �B}|�d�D ]&}|�|�|j|d |d d��� q(W d � n1 sd0 Y d S )Nr )r �*�name�schema)r3 r4 )Zsqlalchemy.dialectsr r r Z get_enumsr( Z DropEnumTypeZENUM)r r r Z inspectorr! �enumr$ r$ r% r g s ��r c C s6 |� d�}|�� }|r2tdd�dd� |D �� � dS )z;Ensure there are no locks on the current username/database.z�select pid, state, wait_event_type, query from pg_stat_activity where usename=current_user and datname=current_database() and state='idle in transaction' and pid != pg_backend_pid()zHPostgreSQL may not be able to DROP tables due to idle in transaction: %sz; c s s | ]}|j d V qdS )�queryN)�_mapping)�.0�rowr$ r$ r% � <genexpr>� � z*prepare_for_drop_tables.<locals>.<genexpr>N)r �allr �join)�config� connection�result�rowsr$ r$ r% r u s ���r F)� set_lambda�sort_by_parameter_orderc C sV ddl m} ||�}t|�j}|r:|j|j||j�d�}n|�� }|j|d|i�}|S )Nr )�insert)Zindex_elements�set_rC ) Z sqlalchemy.dialects.postgresqlrD r Z selectableZon_conflict_do_updateZ primary_keyZexcludedZon_conflict_do_nothing� returning)r �tablerF rB rC rD �stmtZtable_pkr$ r$ r% �_upsert� s ���rI )Zcitext�� )ZhstorerJ c C sb |� � �F}tD ]0\}}|jj|kr|�td|� ��� |�� qW d � n1 sT0 Y d S )Nz CREATE EXTENSION IF NOT EXISTS )r' � _extensions�dialectZserver_version_infor( r �commit)r ZengineZfollower_identr! � extension� min_versionr$ r$ r% �_create_citext_extension� s �rQ )r � r r r Ztestingr Ztesting.provisionr r r r r r r r r r Zfor_dbr& r* r- r0 rI rL rQ r$ r$ r$ r% �<module> sH " �� sqlalchemy/dialects/postgresql/__pycache__/named_types.cpython-39.pyc 0000644 00000043767 15125143220 0022066 0 ustar 00 a ��JhhG � @ s� d dl mZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlm Z d dlm Z d d l m Z d d l m Z d d lmZ d d lmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ e r�d dlmZ d dlmZ G dd� de j ej �Z G dd� de�Z G dd� de�Z G d d � d e �Z!G d d � d e �Z"G d d!� d!e ej#ej$�Z%G d"d#� d#e �Z&G d$d%� d%e �Z'G d&d'� d'e ej(�Z)G d(d)� d)e j*�Z+G d*d+� d+e j*�Z,G d,d-� d-e j*�Z-G d.d/� d/e j*�Z.d0S )1� )� annotations)� ModuleType)�Any)�Dict)�Optional)�Type)� TYPE_CHECKING)�Union� ��schema)�util)� coercions)�elements)�roles)�sqltypes)�type_api)�_NoArg)�InvokeCreateDDLBase)�InvokeDropDDLBase)�_CreateDropBind)�_TypeEngineArgumentc @ s� e Zd ZU dZdZded< ded< ded< d d dd d d �d d�Zd!d dd d d �dd�Zdddd�dd�Zd"d d dd d d�dd�Z d#d d dd d d�dd�Z d$d d dd d d�dd �Z d%d d dd d d�d d �Z d S )&� NamedTypezBase for named types.TzType[NamedTypeGenerator]� DDLGeneratorzType[NamedTypeDropper]� DDLDropper�bool� create_typer r �None)�bind� checkfirst�kw�returnc K s |j | j| |d� dS )al Emit ``CREATE`` DDL for this type. :param bind: a connectable :class:`_engine.Engine`, :class:`_engine.Connection`, or similar object to emit SQL. :param checkfirst: if ``True``, a query against the PG catalog will be first performed to see if the type does not exist already before creating. �r N)�_run_ddl_visitorr ��selfr r r � r& �_/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/postgresql/named_types.py�create* s zNamedType.createc K s |j | j| |d� dS )aZ Emit ``DROP`` DDL for this type. :param bind: a connectable :class:`_engine.Engine`, :class:`_engine.Connection`, or similar object to emit SQL. :param checkfirst: if ``True``, a query against the PG catalog will be first performed to see if the type actually exists before dropping. r" N)r# r r$ r& r& r' �drop: s zNamedType.dropzDict[str, Any])r r r! c C sz | j s dS d|v rr|d }d| j� �}||jv r<|j| }nt� }|j|< | j| jf|v }|�| j| jf� |S dS dS )a Look in the 'ddl runner' for 'memos', then note our name in that collection. This to ensure a particular named type is operated upon only once within any kind of create/drop sequence without relying upon "checkfirst". TZ _ddl_runnerZpg_FN)r �__visit_name__�memo�setr �name�add)r% r r Z ddl_runner� type_name�existingZpresentr& r& r' �_check_for_name_in_memosI s z"NamedType._check_for_name_in_memosF)�targetr r r r! c K s4 |s| j s0|�dd�s0| �||�s0| j||d� d S �NZ_is_metadata_operationF�r r )�metadata�getr1 r( �r% r2 r r r r& r& r' �_on_table_createc s �� � �zNamedType._on_table_createc K s0 | j s,|�dd�s,| �||�s,| j||d� d S r3 )r5 r6 r1 r) r7 r& r& r' �_on_table_drops s � � �zNamedType._on_table_dropc K s | � ||�s| j||d� d S �Nr4 )r1 r( r7 r& r& r' �_on_metadata_create� s z NamedType._on_metadata_createc K s | � ||�s| j||d� d S r: )r1 r) r7 r& r& r' �_on_metadata_drop� s zNamedType._on_metadata_dropN)T)T)F)F)F)F) �__name__� __module__� __qualname__�__doc__Z __abstract__�__annotations__r( r) r1 r8 r9 r; r< r& r& r& r' r " s$ � � � � � �r c s& e Zd Zd� fdd� Zdd� Z� ZS )�NamedTypeGeneratorFc s t � j|fi |�� || _d S �N��super�__init__r �r% �dialect� connectionr �kwargs�� __class__r& r' rF � s zNamedTypeGenerator.__init__c C s0 | j s dS | j�|�}| jjj| j|j|d� S �NTr �r rI Zschema_for_objectrH Zhas_typer- �r% �type_Zeffective_schemar& r& r' �_can_create_type� s �z#NamedTypeGenerator._can_create_type)F)r= r> r? rF rQ � __classcell__r& r& rK r' rB � s rB c s& e Zd Zd� fdd� Zdd� Z� ZS )�NamedTypeDropperFc s t � j|fi |�� || _d S rC rD rG rK r& r' rF � s zNamedTypeDropper.__init__c C s. | j s dS | j�|�}| jjj| j|j|d�S rM rN rO r& r& r' �_can_drop_type� s �z NamedTypeDropper._can_drop_type)F)r= r> r? rF rT rR r& r& rK r' rS � s rS c @ s e Zd Zdd� ZdS )� EnumGeneratorc C sL | � |�sd S | �|�� | j�t|�� W d � n1 s>0 Y d S rC )rQ �with_ddl_eventsrI �execute�CreateEnumType�r% �enumr& r& r' � visit_enum� s zEnumGenerator.visit_enumN�r= r> r? r[ r& r& r& r' rU � s rU c @ s e Zd Zdd� ZdS )� EnumDropperc C sL | � |�sd S | �|�� | j�t|�� W d � n1 s>0 Y d S rC )rT rV rI rW � DropEnumTyperY r& r& r' r[ � s zEnumDropper.visit_enumNr\ r& r& r& r' r] � s r] c s� e Zd ZdZdZeZeZe j dd�ddd�� fdd�Z � fdd �Z e d d � �Ze d d � �Zddddd�� fdd� Zddddd�� fdd� Zddd�dd�Z� ZS )�ENUMa PostgreSQL ENUM type. This is a subclass of :class:`_types.Enum` which includes support for PG's ``CREATE TYPE`` and ``DROP TYPE``. When the builtin type :class:`_types.Enum` is used and the :paramref:`.Enum.native_enum` flag is left at its default of True, the PostgreSQL backend will use a :class:`_postgresql.ENUM` type as the implementation, so the special create/drop rules will be used. The create/drop behavior of ENUM is necessarily intricate, due to the awkward relationship the ENUM type has in relationship to the parent table, in that it may be "owned" by just a single table, or may be shared among many tables. When using :class:`_types.Enum` or :class:`_postgresql.ENUM` in an "inline" fashion, the ``CREATE TYPE`` and ``DROP TYPE`` is emitted corresponding to when the :meth:`_schema.Table.create` and :meth:`_schema.Table.drop` methods are called:: table = Table( "sometable", metadata, Column("some_enum", ENUM("a", "b", "c", name="myenum")), ) table.create(engine) # will emit CREATE ENUM and CREATE TABLE table.drop(engine) # will emit DROP TABLE and DROP ENUM To use a common enumerated type between multiple tables, the best practice is to declare the :class:`_types.Enum` or :class:`_postgresql.ENUM` independently, and associate it with the :class:`_schema.MetaData` object itself:: my_enum = ENUM("a", "b", "c", name="myenum", metadata=metadata) t1 = Table("sometable_one", metadata, Column("some_enum", myenum)) t2 = Table("sometable_two", metadata, Column("some_enum", myenum)) When this pattern is used, care must still be taken at the level of individual table creates. Emitting CREATE TABLE without also specifying ``checkfirst=True`` will still cause issues:: t1.create(engine) # will fail: no such type 'myenum' If we specify ``checkfirst=True``, the individual table-level create operation will check for the ``ENUM`` and create if not exists:: # will check if enum exists, and emit CREATE TYPE if not t1.create(engine, checkfirst=True) When using a metadata-level ENUM type, the type will always be created and dropped if either the metadata-wide create/drop is called:: metadata.create_all(engine) # will emit CREATE TYPE metadata.drop_all(engine) # will emit DROP TYPE The type can also be created and dropped directly:: my_enum.create(engine) my_enum.drop(engine) T)r- r zUnion[str, _NoArg, None]r c sL |� dd�}|du r t�d� || _|tjur6||d< t� j|i |�� dS )a Construct an :class:`_postgresql.ENUM`. Arguments are the same as that of :class:`_types.Enum`, but also including the following parameters. :param create_type: Defaults to True. Indicates that ``CREATE TYPE`` should be emitted, after optionally checking for the presence of the type, when the parent table is being created; and additionally that ``DROP TYPE`` is called when the table is dropped. When ``False``, no check will be performed and no ``CREATE TYPE`` or ``DROP TYPE`` is emitted, unless :meth:`~.postgresql.ENUM.create` or :meth:`~.postgresql.ENUM.drop` are called directly. Setting to ``False`` is helpful when invoking a creation scheme to a SQL file without access to the actual database - the :meth:`~.postgresql.ENUM.create` and :meth:`~.postgresql.ENUM.drop` methods can be used to emit SQL to a target bind. � native_enumNFz�the native_enum flag does not apply to the sqlalchemy.dialects.postgresql.ENUM datatype; this type always refers to ENUM. Use sqlalchemy.types.Enum for non-native enum.r- )�popr �warnr r �NO_ARGrE rF )r% r- r �enumsr r` rK r& r' rF s ! � z ENUM.__init__c s( t � �||�}|jtjju r | S |S d S rC )rE �coerce_compared_valueZ_type_affinityr Z STRINGTYPE)r% �op�valueZsuper_coerced_typerK r& r' re < s ��zENUM.coerce_compared_valuec C s | dd�S )Nr- )r- r& ��clsr& r& r' � __test_init__F s zENUM.__test_init__c K s� |� d|j� |� d|j� |� d|j� |� d|j� |� d|j� |� dd� |� d|j� |� d |j� |� d |� t� |j �r�|� d |j � | f i |��S ) zbProduce a PostgreSQL native :class:`_postgresql.ENUM` from plain :class:`.Enum`. �validate_stringsr- r �inherit_schemar5 Z_create_eventsF�values_callableZ omit_aliasesZ _adapted_fromr ) � setdefaultrk r- r rl r5 rm Z _omit_aliasesr Z_is_native_for_emulatedrL r )ri �implr r& r& r' �adapt_emulated_to_nativeJ s z ENUM.adapt_emulated_to_nativer r )r r r! c s |j js dS t� j||d� dS )a� Emit ``CREATE TYPE`` for this :class:`_postgresql.ENUM`. If the underlying dialect does not support PostgreSQL CREATE TYPE, no action is taken. :param bind: a connectable :class:`_engine.Engine`, :class:`_engine.Connection`, or similar object to emit SQL. :param checkfirst: if ``True``, a query against the PG catalog will be first performed to see if the type does not exist already before creating. Nr" )rH �supports_native_enumrE r( �r% r r rK r& r' r( ^ s z ENUM.createc s |j js dS t� j||d� dS )a� Emit ``DROP TYPE`` for this :class:`_postgresql.ENUM`. If the underlying dialect does not support PostgreSQL DROP TYPE, no action is taken. :param bind: a connectable :class:`_engine.Engine`, :class:`_engine.Connection`, or similar object to emit SQL. :param checkfirst: if ``True``, a query against the PG catalog will be first performed to see if the type actually exists before dropping. Nr" )rH rq rE r) rr rK r& r' r) s s z ENUM.dropr )�dbapir! c C s dS )zVdont return dbapi.STRING for ENUM in PostgreSQL, since that's a different typeNr& )r% rs r& r& r' �get_dbapi_type� s zENUM.get_dbapi_type)T)T)r= r> r? r@ r` rU r r] r r rc rF re � classmethodrj rp r( r) rt rR r& r& rK r' r_ � s C�. r_ c @ s e Zd Zdd� ZdS )�DomainGeneratorc C sL | � |�sd S | �|�� | j�t|�� W d � n1 s>0 Y d S rC )rQ rV rI rW �CreateDomainType�r% �domainr& r& r' � visit_DOMAIN� s z DomainGenerator.visit_DOMAINN�r= r> r? rz r& r& r& r' rv � s rv c @ s e Zd Zdd� ZdS )� DomainDropperc C sL | � |�sd S | �|�� | j�t|�� W d � n1 s>0 Y d S rC )rT rV rI rW �DropDomainTyperx r& r& r' rz � s zDomainDropper.visit_DOMAINNr{ r& r& r& r' r| � s r| c sj e Zd ZdZeZeZd Zddddddd�dddddd dd d d � � fd d�Z e dd� �Z � fdd�Z � Z S )�DOMAINa4 Represent the DOMAIN PostgreSQL type. A domain is essentially a data type with optional constraints that restrict the allowed set of values. E.g.:: PositiveInt = DOMAIN("pos_int", Integer, check="VALUE > 0", not_null=True) UsPostalCode = DOMAIN( "us_postal_code", Text, check="VALUE ~ '^\d{5}$' OR VALUE ~ '^\d{5}-\d{4}$'", ) See the `PostgreSQL documentation`__ for additional details __ https://www.postgresql.org/docs/current/sql-createdomain.html .. versionadded:: 2.0 NT)� collation�default�constraint_name�not_null�checkr �strz_TypeEngineArgument[Any]z Optional[str]z%Union[elements.TextClause, str, None]zOptional[bool]r r ) r- � data_typer r� r� r� r� r r c sd t �|�| _|| _|| _|| _t|�| _|dur>t� t j |�}|| _ || _ t� jf d|i| �� dS )a� Construct a DOMAIN. :param name: the name of the domain :param data_type: The underlying data type of the domain. This can include array specifiers. :param collation: An optional collation for the domain. If no collation is specified, the underlying data type's default collation is used. The underlying type must be collatable if ``collation`` is specified. :param default: The DEFAULT clause specifies a default value for columns of the domain data type. The default should be a string or a :func:`_expression.text` value. If no default value is specified, then the default value is the null value. :param constraint_name: An optional name for a constraint. If not specified, the backend generates a name. :param not_null: Values of this domain are prevented from being null. By default domain are allowed to be null. If not specified no nullability clause will be emitted. :param check: CHECK clause specify integrity constraint or test which values of the domain must satisfy. A constraint must be an expression producing a Boolean result that can use the key word VALUE to refer to the value being tested. Differently from PostgreSQL, only a single check clause is currently allowed in SQLAlchemy. :param schema: optional schema name :param metadata: optional :class:`_schema.MetaData` object which this :class:`_postgresql.DOMAIN` will be directly associated :param create_type: Defaults to True. Indicates that ``CREATE TYPE`` should be emitted, after optionally checking for the presence of the type, when the parent table is being created; and additionally that ``DROP TYPE`` is called when the table is dropped. Nr- )r Z to_instancer� r� r r� r r� r �expectr ZDDLExpressionRoler� r rE rF ) r% r- r� r r� r� r� r� r r rK r& r' rF � s 1 zDOMAIN.__init__c C s | dt j�S )Nr- )r ZIntegerrh r& r& r' rj � s zDOMAIN.__test_init__c sp | j r| j |d< | jd ur$| j|d< | jr4| j|d< | jd urLt| j�|d< | jr\| j|d< t� j|fi |��S )Nr� r� r� r� r )r� r� r� r� r� r rE �adapt)r% ro r rK r& r' r� � s z DOMAIN.adapt)r= r> r? r@ rv r r| r r* rF ru rj r� rR r& r& rK r' r~ � s �&< r~ c @ s e Zd ZdZdS )rX Zcreate_enum_typeN�r= r> r? r* r& r& r& r' rX s rX c @ s e Zd ZdZdS )r^ Zdrop_enum_typeNr� r& r& r& r' r^ s r^ c @ s e Zd ZdZdZdS )rw z$Represent a CREATE DOMAIN statement.Zcreate_domain_typeN�r= r> r? r@ r* r& r& r& r' rw s rw c @ s e Zd ZdZdZdS )r} z"Represent a DROP DOMAIN statement.Zdrop_domain_typeNr� r& r& r& r' r} s r} N)/� __future__r �typesr �typingr r r r r r � r r Zsqlr r r r r Zsql.baser Zsql.ddlr r Z sql._typingr r ZSchemaVisitableZ TypeEnginer rB rS rU r] ZNativeForEmulated�Enumr_ rv r| Z SchemaTyper~ Z_CreateDropBaserX r^ rw r} r& r& r& r' �<module> sD t I j sqlalchemy/dialects/postgresql/__pycache__/types.cpython-39.pyc 0000644 00000022453 15125143220 0020707 0 ustar 00 a ��Jh� � @ sZ d dl mZ d dlZd dlmZ d dlmZ d dlmZ d dlmZ d dlm Z d dl m Z d d l mZ d d l mZ d d lmZ e r�d d lmZ d dlmZ d dlmZ d dlmZ dZdZdZG dd� dej ej �Z G dd� dej �Z G dd� d�Z G dd� de eje! �Z"e"Z#G d d � d e eje! �Z$e$Z%G d d � d e eje! �Z&e&Z'G d d!� d!e eje! �Z(e(Z)G d"d#� d#eje! �Z*G d$d%� d%eje+ �Z,G d&d'� d'eje! �Z-G d(d)� d)eje! �Z.G d*d+� d+eje! �Z/G d,d-� d-ej0�Z0G d.d/� d/ej1�Z1G d0d1� d1ej2ej3�Z4e4Z5G d2d3� d3eje+ �Z6e6Z7G d4d5� d5eje! �Z8G d6d7� d7ej9�Z:dS )8� )� annotationsN)�Any)�Optional)�overload)�Type)� TYPE_CHECKING)�UUID� )�sqltypes)�type_api)�Literal)�Dialect)� OperatorType)�_LiteralProcessorType)� TypeEngine)i� i� )i� i� i� i� )� � � � i� i� i� c @ sZ e Zd ZdZdZerVeddddd�dd��Zedd d dd�d d��Zdd dd �dd�ZdS )�PGUuidT.zPGUuid[_python_UUID]z Literal[True]�None)�self�as_uuid�returnc C s d S �N� �r r r r �Y/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/postgresql/types.py�__init__& s zPGUuid.__init__z PGUuid[str]zLiteral[False]c C s d S r r r r r r r + s �bool)r r c C s d S r r r r r r r 0 � N).).)T)�__name__� __module__� __qualname__Zrender_bind_castZrender_literal_castr r r r r r r r s � �r c @ s e Zd Zd ZdS )�BYTEAN�r! r" r# �__visit_name__r r r r r$ 3 s r$ c @ s e Zd Zdddd�dd�ZdS )�_NetworkAddressTypeMixin�Optional[OperatorType]r �TypeEngine[Any]��op�valuer c C s t rt| t�sJ �| S r )r � isinstancer �r r+ r, r r r �coerce_compared_value9 s z._NetworkAddressTypeMixin.coerce_compared_valueN)r! r" r# r/ r r r r r' 7 s r' c @ s e Zd Zd ZdS )�INETNr% r r r r r0 A s r0 c @ s e Zd Zd ZdS )�CIDRNr% r r r r r1 H s r1 c @ s e Zd Zd ZdS )�MACADDRNr% r r r r r2 O s r2 c @ s e Zd Zd ZdS )�MACADDR8Nr% r r r r r3 V s r3 c @ s e Zd ZdZd ZdS )�MONEYa Provide the PostgreSQL MONEY type. Depending on driver, result rows using this type may return a string value which includes currency symbols. For this reason, it may be preferable to provide conversion to a numerically-based currency datatype using :class:`_types.TypeDecorator`:: import re import decimal from sqlalchemy import Dialect from sqlalchemy import TypeDecorator class NumericMoney(TypeDecorator): impl = MONEY def process_result_value(self, value: Any, dialect: Dialect) -> None: if value is not None: # adjust this for the currency and numeric m = re.match(r"\$([\d.]+)", value) if m: value = decimal.Decimal(m.group(1)) return value Alternatively, the conversion may be applied as a CAST using the :meth:`_types.TypeDecorator.column_expression` method as follows:: import decimal from sqlalchemy import cast from sqlalchemy import TypeDecorator class NumericMoney(TypeDecorator): impl = MONEY def column_expression(self, column: Any): return cast(column, Numeric()) .. versionadded:: 1.2 N�r! r" r# �__doc__r& r r r r r4 ] s +r4 c @ s e Zd ZdZd ZdS )�OIDz Provide the PostgreSQL OID type.Nr5 r r r r r7 � s r7 c @ s e Zd ZdZd ZdS )� REGCONFIGzLProvide the PostgreSQL REGCONFIG type. .. versionadded:: 2.0.0rc1 Nr5 r r r r r8 � s r8 c @ s e Zd ZdZd ZdS )�TSQUERYzJProvide the PostgreSQL TSQUERY type. .. versionadded:: 2.0.0rc1 Nr5 r r r r r9 � s r9 c @ s e Zd ZdZd ZdS )�REGCLASSzHProvide the PostgreSQL REGCLASS type. .. versionadded:: 1.2.7 Nr5 r r r r r: � s r: c s0 e Zd ZdZd Zd dddd�� fdd � Z� ZS ) � TIMESTAMPz&Provide the PostgreSQL TIMESTAMP type.FNr � Optional[int]r ��timezone� precisionr c s t � j|d� || _dS )z�Construct a TIMESTAMP. :param timezone: boolean value if timezone present, default False :param precision: optional integer precision value .. versionadded:: 1.4 �r> N��superr r? �r r> r? �� __class__r r r � s zTIMESTAMP.__init__)FN�r! r" r# r6 r& r � __classcell__r r rD r r; � s �r; c s0 e Zd ZdZd Zd dddd�� fdd � Z� ZS ) �TIMEzPostgreSQL TIME type.FNr r< r r= c s t � j|d� || _dS )z�Construct a TIME. :param timezone: boolean value if timezone present, default False :param precision: optional integer precision value .. versionadded:: 1.4 r@ NrA rC rD r r r � s z TIME.__init__)FNrF r r rD r rH � s �rH c @ s� e Zd ZdZd ZdZd dddd�dd �Zed d d d �d d��Ze dd�dd��Z d!dd d�dd�Z e dd�dd��Z dd d �d d �Z dS )"�INTERVALzPostgreSQL INTERVAL type.TNr< z Optional[str]r )r? �fieldsr c C s || _ || _dS )a Construct an INTERVAL. :param precision: optional integer precision value :param fields: string fields specifier. allows storage of fields to be limited, such as ``"YEAR"``, ``"MONTH"``, ``"DAY TO HOUR"``, etc. .. versionadded:: 1.2 N)r? rJ )r r? rJ r r r r � s zINTERVAL.__init__zsqltypes.Intervalr )�interval�kwr c K s t |jd�S )N)r? )rI �second_precision)�clsrK rL r r r �adapt_emulated_to_native� s z!INTERVAL.adapt_emulated_to_nativezType[sqltypes.Interval])r c C s t jS r )r �Interval�r r r r �_type_affinity� s zINTERVAL._type_affinityFr )�allow_nulltyper c C s t jd| jd�S )NT)�nativerM )r rP r? )r rS r r r � as_generic� s zINTERVAL.as_genericzType[dt.timedelta]c C s t jS r )�dt� timedeltarQ r r r � python_type� s zINTERVAL.python_typer z-Optional[_LiteralProcessorType[dt.timedelta]])�dialectr c C s ddd�dd�}|S )Nz dt.timedelta�str)r, r c S s d| � � � d�S )Nzmake_interval(secs=>�))� total_seconds)r, r r r �process s z+INTERVAL.literal_processor.<locals>.processr )r rY r] r r r �literal_processor� s zINTERVAL.literal_processor)NN)F)r! r" r# r6 r& rT r � classmethodrO �propertyrR rU rX r^ r r r r rI � s �rI c @ s$ e Zd Zd Zd dddd�dd�ZdS ) �BITNFr< r r )�length�varyingr c C s |r || _ n |pd| _ || _d S )N� )rb rc )r rb rc r r r r s z BIT.__init__)NF)r! r" r# r& r r r r r ra s �ra c @ s e Zd ZdZd ZdS )�TSVECTORz�The :class:`_postgresql.TSVECTOR` type implements the PostgreSQL text search type TSVECTOR. It can be used to do full text queries on natural language documents. .. seealso:: :ref:`postgresql_match` Nr5 r r r r re s re c @ s& e Zd ZdZd Zdddd�dd�ZdS ) �CITEXTzFProvide the PostgreSQL CITEXT type. .. versionadded:: 2.0.7 r( r r) r* c C s | S r r r. r r r r/ 6 s z CITEXT.coerce_compared_valueN)r! r" r# r6 r& r/ r r r r rf - s rf );� __future__r �datetimerV �typingr r r r r �uuidr Z _python_UUIDZsqlr r Z util.typingr Zengine.interfacesr Z sql.operatorsr Z sql.type_apir r Z_DECIMAL_TYPESZ _FLOAT_TYPESZ _INT_TYPESZ _UUID_RETURNr Z LargeBinaryr$ r' rZ r0 ZPGInetr1 ZPGCidrr2 Z PGMacAddrr3 Z PGMacAddr8r4 �intr7 r8 r9 r: r; rH ZNativeForEmulatedZ_AbstractIntervalrI Z PGIntervalra ZPGBitre ZTEXTrf r r r r �<module> sT / 0 sqlalchemy/dialects/postgresql/psycopg2.py 0000755 00000076440 15125143220 0015032 0 ustar 00 # dialects/postgresql/psycopg2.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors r""" .. dialect:: postgresql+psycopg2 :name: psycopg2 :dbapi: psycopg2 :connectstring: postgresql+psycopg2://user:password@host:port/dbname[?key=value&key=value...] :url: https://pypi.org/project/psycopg2/ .. _psycopg2_toplevel: psycopg2 Connect Arguments -------------------------- Keyword arguments that are specific to the SQLAlchemy psycopg2 dialect may be passed to :func:`_sa.create_engine()`, and include the following: * ``isolation_level``: This option, available for all PostgreSQL dialects, includes the ``AUTOCOMMIT`` isolation level when using the psycopg2 dialect. This option sets the **default** isolation level for the connection that is set immediately upon connection to the database before the connection is pooled. This option is generally superseded by the more modern :paramref:`_engine.Connection.execution_options.isolation_level` execution option, detailed at :ref:`dbapi_autocommit`. .. seealso:: :ref:`psycopg2_isolation_level` :ref:`dbapi_autocommit` * ``client_encoding``: sets the client encoding in a libpq-agnostic way, using psycopg2's ``set_client_encoding()`` method. .. seealso:: :ref:`psycopg2_unicode` * ``executemany_mode``, ``executemany_batch_page_size``, ``executemany_values_page_size``: Allows use of psycopg2 extensions for optimizing "executemany"-style queries. See the referenced section below for details. .. seealso:: :ref:`psycopg2_executemany_mode` .. tip:: The above keyword arguments are **dialect** keyword arguments, meaning that they are passed as explicit keyword arguments to :func:`_sa.create_engine()`:: engine = create_engine( "postgresql+psycopg2://scott:tiger@localhost/test", isolation_level="SERIALIZABLE", ) These should not be confused with **DBAPI** connect arguments, which are passed as part of the :paramref:`_sa.create_engine.connect_args` dictionary and/or are passed in the URL query string, as detailed in the section :ref:`custom_dbapi_args`. .. _psycopg2_ssl: SSL Connections --------------- The psycopg2 module has a connection argument named ``sslmode`` for controlling its behavior regarding secure (SSL) connections. The default is ``sslmode=prefer``; it will attempt an SSL connection and if that fails it will fall back to an unencrypted connection. ``sslmode=require`` may be used to ensure that only secure connections are established. Consult the psycopg2 / libpq documentation for further options that are available. Note that ``sslmode`` is specific to psycopg2 so it is included in the connection URI:: engine = sa.create_engine( "postgresql+psycopg2://scott:tiger@192.168.0.199:5432/test?sslmode=require" ) Unix Domain Connections ------------------------ psycopg2 supports connecting via Unix domain connections. When the ``host`` portion of the URL is omitted, SQLAlchemy passes ``None`` to psycopg2, which specifies Unix-domain communication rather than TCP/IP communication:: create_engine("postgresql+psycopg2://user:password@/dbname") By default, the socket file used is to connect to a Unix-domain socket in ``/tmp``, or whatever socket directory was specified when PostgreSQL was built. This value can be overridden by passing a pathname to psycopg2, using ``host`` as an additional keyword argument:: create_engine( "postgresql+psycopg2://user:password@/dbname?host=/var/lib/postgresql" ) .. warning:: The format accepted here allows for a hostname in the main URL in addition to the "host" query string argument. **When using this URL format, the initial host is silently ignored**. That is, this URL:: engine = create_engine( "postgresql+psycopg2://user:password@myhost1/dbname?host=myhost2" ) Above, the hostname ``myhost1`` is **silently ignored and discarded.** The host which is connected is the ``myhost2`` host. This is to maintain some degree of compatibility with PostgreSQL's own URL format which has been tested to behave the same way and for which tools like PifPaf hardcode two hostnames. .. seealso:: `PQconnectdbParams \ <https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS>`_ .. _psycopg2_multi_host: Specifying multiple fallback hosts ----------------------------------- psycopg2 supports multiple connection points in the connection string. When the ``host`` parameter is used multiple times in the query section of the URL, SQLAlchemy will create a single string of the host and port information provided to make the connections. Tokens may consist of ``host::port`` or just ``host``; in the latter case, the default port is selected by libpq. In the example below, three host connections are specified, for ``HostA::PortA``, ``HostB`` connecting to the default port, and ``HostC::PortC``:: create_engine( "postgresql+psycopg2://user:password@/dbname?host=HostA:PortA&host=HostB&host=HostC:PortC" ) As an alternative, libpq query string format also may be used; this specifies ``host`` and ``port`` as single query string arguments with comma-separated lists - the default port can be chosen by indicating an empty value in the comma separated list:: create_engine( "postgresql+psycopg2://user:password@/dbname?host=HostA,HostB,HostC&port=PortA,,PortC" ) With either URL style, connections to each host is attempted based on a configurable strategy, which may be configured using the libpq ``target_session_attrs`` parameter. Per libpq this defaults to ``any`` which indicates a connection to each host is then attempted until a connection is successful. Other strategies include ``primary``, ``prefer-standby``, etc. The complete list is documented by PostgreSQL at `libpq connection strings <https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING>`_. For example, to indicate two hosts using the ``primary`` strategy:: create_engine( "postgresql+psycopg2://user:password@/dbname?host=HostA:PortA&host=HostB&host=HostC:PortC&target_session_attrs=primary" ) .. versionchanged:: 1.4.40 Port specification in psycopg2 multiple host format is repaired, previously ports were not correctly interpreted in this context. libpq comma-separated format is also now supported. .. versionadded:: 1.3.20 Support for multiple hosts in PostgreSQL connection string. .. seealso:: `libpq connection strings <https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING>`_ - please refer to this section in the libpq documentation for complete background on multiple host support. Empty DSN Connections / Environment Variable Connections --------------------------------------------------------- The psycopg2 DBAPI can connect to PostgreSQL by passing an empty DSN to the libpq client library, which by default indicates to connect to a localhost PostgreSQL database that is open for "trust" connections. This behavior can be further tailored using a particular set of environment variables which are prefixed with ``PG_...``, which are consumed by ``libpq`` to take the place of any or all elements of the connection string. For this form, the URL can be passed without any elements other than the initial scheme:: engine = create_engine("postgresql+psycopg2://") In the above form, a blank "dsn" string is passed to the ``psycopg2.connect()`` function which in turn represents an empty DSN passed to libpq. .. versionadded:: 1.3.2 support for parameter-less connections with psycopg2. .. seealso:: `Environment Variables\ <https://www.postgresql.org/docs/current/libpq-envars.html>`_ - PostgreSQL documentation on how to use ``PG_...`` environment variables for connections. .. _psycopg2_execution_options: Per-Statement/Connection Execution Options ------------------------------------------- The following DBAPI-specific options are respected when used with :meth:`_engine.Connection.execution_options`, :meth:`.Executable.execution_options`, :meth:`_query.Query.execution_options`, in addition to those not specific to DBAPIs: * ``isolation_level`` - Set the transaction isolation level for the lifespan of a :class:`_engine.Connection` (can only be set on a connection, not a statement or query). See :ref:`psycopg2_isolation_level`. * ``stream_results`` - Enable or disable usage of psycopg2 server side cursors - this feature makes use of "named" cursors in combination with special result handling methods so that result rows are not fully buffered. Defaults to False, meaning cursors are buffered by default. * ``max_row_buffer`` - when using ``stream_results``, an integer value that specifies the maximum number of rows to buffer at a time. This is interpreted by the :class:`.BufferedRowCursorResult`, and if omitted the buffer will grow to ultimately store 1000 rows at a time. .. versionchanged:: 1.4 The ``max_row_buffer`` size can now be greater than 1000, and the buffer will grow to that size. .. _psycopg2_batch_mode: .. _psycopg2_executemany_mode: Psycopg2 Fast Execution Helpers ------------------------------- Modern versions of psycopg2 include a feature known as `Fast Execution Helpers \ <https://www.psycopg.org/docs/extras.html#fast-execution-helpers>`_, which have been shown in benchmarking to improve psycopg2's executemany() performance, primarily with INSERT statements, by at least an order of magnitude. SQLAlchemy implements a native form of the "insert many values" handler that will rewrite a single-row INSERT statement to accommodate for many values at once within an extended VALUES clause; this handler is equivalent to psycopg2's ``execute_values()`` handler; an overview of this feature and its configuration are at :ref:`engine_insertmanyvalues`. .. versionadded:: 2.0 Replaced psycopg2's ``execute_values()`` fast execution helper with a native SQLAlchemy mechanism known as :ref:`insertmanyvalues <engine_insertmanyvalues>`. The psycopg2 dialect retains the ability to use the psycopg2-specific ``execute_batch()`` feature, although it is not expected that this is a widely used feature. The use of this extension may be enabled using the ``executemany_mode`` flag which may be passed to :func:`_sa.create_engine`:: engine = create_engine( "postgresql+psycopg2://scott:tiger@host/dbname", executemany_mode="values_plus_batch", ) Possible options for ``executemany_mode`` include: * ``values_only`` - this is the default value. SQLAlchemy's native :ref:`insertmanyvalues <engine_insertmanyvalues>` handler is used for qualifying INSERT statements, assuming :paramref:`_sa.create_engine.use_insertmanyvalues` is left at its default value of ``True``. This handler rewrites simple INSERT statements to include multiple VALUES clauses so that many parameter sets can be inserted with one statement. * ``'values_plus_batch'``- SQLAlchemy's native :ref:`insertmanyvalues <engine_insertmanyvalues>` handler is used for qualifying INSERT statements, assuming :paramref:`_sa.create_engine.use_insertmanyvalues` is left at its default value of ``True``. Then, psycopg2's ``execute_batch()`` handler is used for qualifying UPDATE and DELETE statements when executed with multiple parameter sets. When using this mode, the :attr:`_engine.CursorResult.rowcount` attribute will not contain a value for executemany-style executions against UPDATE and DELETE statements. .. versionchanged:: 2.0 Removed the ``'batch'`` and ``'None'`` options from psycopg2 ``executemany_mode``. Control over batching for INSERT statements is now configured via the :paramref:`_sa.create_engine.use_insertmanyvalues` engine-level parameter. The term "qualifying statements" refers to the statement being executed being a Core :func:`_expression.insert`, :func:`_expression.update` or :func:`_expression.delete` construct, and **not** a plain textual SQL string or one constructed using :func:`_expression.text`. It also may **not** be a special "extension" statement such as an "ON CONFLICT" "upsert" statement. When using the ORM, all insert/update/delete statements used by the ORM flush process are qualifying. The "page size" for the psycopg2 "batch" strategy can be affected by using the ``executemany_batch_page_size`` parameter, which defaults to 100. For the "insertmanyvalues" feature, the page size can be controlled using the :paramref:`_sa.create_engine.insertmanyvalues_page_size` parameter, which defaults to 1000. An example of modifying both parameters is below:: engine = create_engine( "postgresql+psycopg2://scott:tiger@host/dbname", executemany_mode="values_plus_batch", insertmanyvalues_page_size=5000, executemany_batch_page_size=500, ) .. seealso:: :ref:`engine_insertmanyvalues` - background on "insertmanyvalues" :ref:`tutorial_multiple_parameters` - General information on using the :class:`_engine.Connection` object to execute statements in such a way as to make use of the DBAPI ``.executemany()`` method. .. _psycopg2_unicode: Unicode with Psycopg2 ---------------------- The psycopg2 DBAPI driver supports Unicode data transparently. The client character encoding can be controlled for the psycopg2 dialect in the following ways: * For PostgreSQL 9.1 and above, the ``client_encoding`` parameter may be passed in the database URL; this parameter is consumed by the underlying ``libpq`` PostgreSQL client library:: engine = create_engine( "postgresql+psycopg2://user:pass@host/dbname?client_encoding=utf8" ) Alternatively, the above ``client_encoding`` value may be passed using :paramref:`_sa.create_engine.connect_args` for programmatic establishment with ``libpq``:: engine = create_engine( "postgresql+psycopg2://user:pass@host/dbname", connect_args={"client_encoding": "utf8"}, ) * For all PostgreSQL versions, psycopg2 supports a client-side encoding value that will be passed to database connections when they are first established. The SQLAlchemy psycopg2 dialect supports this using the ``client_encoding`` parameter passed to :func:`_sa.create_engine`:: engine = create_engine( "postgresql+psycopg2://user:pass@host/dbname", client_encoding="utf8" ) .. tip:: The above ``client_encoding`` parameter admittedly is very similar in appearance to usage of the parameter within the :paramref:`_sa.create_engine.connect_args` dictionary; the difference above is that the parameter is consumed by psycopg2 and is passed to the database connection using ``SET client_encoding TO 'utf8'``; in the previously mentioned style, the parameter is instead passed through psycopg2 and consumed by the ``libpq`` library. * A common way to set up client encoding with PostgreSQL databases is to ensure it is configured within the server-side postgresql.conf file; this is the recommended way to set encoding for a server that is consistently of one encoding in all databases:: # postgresql.conf file # client_encoding = sql_ascii # actually, defaults to database # encoding client_encoding = utf8 Transactions ------------ The psycopg2 dialect fully supports SAVEPOINT and two-phase commit operations. .. _psycopg2_isolation_level: Psycopg2 Transaction Isolation Level ------------------------------------- As discussed in :ref:`postgresql_isolation_level`, all PostgreSQL dialects support setting of transaction isolation level both via the ``isolation_level`` parameter passed to :func:`_sa.create_engine` , as well as the ``isolation_level`` argument used by :meth:`_engine.Connection.execution_options`. When using the psycopg2 dialect , these options make use of psycopg2's ``set_isolation_level()`` connection method, rather than emitting a PostgreSQL directive; this is because psycopg2's API-level setting is always emitted at the start of each transaction in any case. The psycopg2 dialect supports these constants for isolation level: * ``READ COMMITTED`` * ``READ UNCOMMITTED`` * ``REPEATABLE READ`` * ``SERIALIZABLE`` * ``AUTOCOMMIT`` .. seealso:: :ref:`postgresql_isolation_level` :ref:`pg8000_isolation_level` NOTICE logging --------------- The psycopg2 dialect will log PostgreSQL NOTICE messages via the ``sqlalchemy.dialects.postgresql`` logger. When this logger is set to the ``logging.INFO`` level, notice messages will be logged:: import logging logging.getLogger("sqlalchemy.dialects.postgresql").setLevel(logging.INFO) Above, it is assumed that logging is configured externally. If this is not the case, configuration such as ``logging.basicConfig()`` must be utilized:: import logging logging.basicConfig() # log messages to stdout logging.getLogger("sqlalchemy.dialects.postgresql").setLevel(logging.INFO) .. seealso:: `Logging HOWTO <https://docs.python.org/3/howto/logging.html>`_ - on the python.org website .. _psycopg2_hstore: HSTORE type ------------ The ``psycopg2`` DBAPI includes an extension to natively handle marshalling of the HSTORE type. The SQLAlchemy psycopg2 dialect will enable this extension by default when psycopg2 version 2.4 or greater is used, and it is detected that the target database has the HSTORE type set up for use. In other words, when the dialect makes the first connection, a sequence like the following is performed: 1. Request the available HSTORE oids using ``psycopg2.extras.HstoreAdapter.get_oids()``. If this function returns a list of HSTORE identifiers, we then determine that the ``HSTORE`` extension is present. This function is **skipped** if the version of psycopg2 installed is less than version 2.4. 2. If the ``use_native_hstore`` flag is at its default of ``True``, and we've detected that ``HSTORE`` oids are available, the ``psycopg2.extensions.register_hstore()`` extension is invoked for all connections. The ``register_hstore()`` extension has the effect of **all Python dictionaries being accepted as parameters regardless of the type of target column in SQL**. The dictionaries are converted by this extension into a textual HSTORE expression. If this behavior is not desired, disable the use of the hstore extension by setting ``use_native_hstore`` to ``False`` as follows:: engine = create_engine( "postgresql+psycopg2://scott:tiger@localhost/test", use_native_hstore=False, ) The ``HSTORE`` type is **still supported** when the ``psycopg2.extensions.register_hstore()`` extension is not used. It merely means that the coercion between Python dictionaries and the HSTORE string format, on both the parameter side and the result side, will take place within SQLAlchemy's own marshalling logic, and not that of ``psycopg2`` which may be more performant. """ # noqa from __future__ import annotations import collections.abc as collections_abc import logging import re from typing import cast from . import ranges from ._psycopg_common import _PGDialect_common_psycopg from ._psycopg_common import _PGExecutionContext_common_psycopg from .base import PGIdentifierPreparer from .json import JSON from .json import JSONB from ... import types as sqltypes from ... import util from ...util import FastIntFlag from ...util import parse_user_argument_for_enum logger = logging.getLogger("sqlalchemy.dialects.postgresql") class _PGJSON(JSON): def result_processor(self, dialect, coltype): return None class _PGJSONB(JSONB): def result_processor(self, dialect, coltype): return None class _Psycopg2Range(ranges.AbstractSingleRangeImpl): _psycopg2_range_cls = "none" def bind_processor(self, dialect): psycopg2_Range = getattr( cast(PGDialect_psycopg2, dialect)._psycopg2_extras, self._psycopg2_range_cls, ) def to_range(value): if isinstance(value, ranges.Range): value = psycopg2_Range( value.lower, value.upper, value.bounds, value.empty ) return value return to_range def result_processor(self, dialect, coltype): def to_range(value): if value is not None: value = ranges.Range( value._lower, value._upper, bounds=value._bounds if value._bounds else "[)", empty=not value._bounds, ) return value return to_range class _Psycopg2NumericRange(_Psycopg2Range): _psycopg2_range_cls = "NumericRange" class _Psycopg2DateRange(_Psycopg2Range): _psycopg2_range_cls = "DateRange" class _Psycopg2DateTimeRange(_Psycopg2Range): _psycopg2_range_cls = "DateTimeRange" class _Psycopg2DateTimeTZRange(_Psycopg2Range): _psycopg2_range_cls = "DateTimeTZRange" class PGExecutionContext_psycopg2(_PGExecutionContext_common_psycopg): _psycopg2_fetched_rows = None def post_exec(self): self._log_notices(self.cursor) def _log_notices(self, cursor): # check also that notices is an iterable, after it's already # established that we will be iterating through it. This is to get # around test suites such as SQLAlchemy's using a Mock object for # cursor if not cursor.connection.notices or not isinstance( cursor.connection.notices, collections_abc.Iterable ): return for notice in cursor.connection.notices: # NOTICE messages have a # newline character at the end logger.info(notice.rstrip()) cursor.connection.notices[:] = [] class PGIdentifierPreparer_psycopg2(PGIdentifierPreparer): pass class ExecutemanyMode(FastIntFlag): EXECUTEMANY_VALUES = 0 EXECUTEMANY_VALUES_PLUS_BATCH = 1 ( EXECUTEMANY_VALUES, EXECUTEMANY_VALUES_PLUS_BATCH, ) = ExecutemanyMode.__members__.values() class PGDialect_psycopg2(_PGDialect_common_psycopg): driver = "psycopg2" supports_statement_cache = True supports_server_side_cursors = True default_paramstyle = "pyformat" # set to true based on psycopg2 version supports_sane_multi_rowcount = False execution_ctx_cls = PGExecutionContext_psycopg2 preparer = PGIdentifierPreparer_psycopg2 psycopg2_version = (0, 0) use_insertmanyvalues_wo_returning = True returns_native_bytes = False _has_native_hstore = True colspecs = util.update_copy( _PGDialect_common_psycopg.colspecs, { JSON: _PGJSON, sqltypes.JSON: _PGJSON, JSONB: _PGJSONB, ranges.INT4RANGE: _Psycopg2NumericRange, ranges.INT8RANGE: _Psycopg2NumericRange, ranges.NUMRANGE: _Psycopg2NumericRange, ranges.DATERANGE: _Psycopg2DateRange, ranges.TSRANGE: _Psycopg2DateTimeRange, ranges.TSTZRANGE: _Psycopg2DateTimeTZRange, }, ) def __init__( self, executemany_mode="values_only", executemany_batch_page_size=100, **kwargs, ): _PGDialect_common_psycopg.__init__(self, **kwargs) if self._native_inet_types: raise NotImplementedError( "The psycopg2 dialect does not implement " "ipaddress type handling; native_inet_types cannot be set " "to ``True`` when using this dialect." ) # Parse executemany_mode argument, allowing it to be only one of the # symbol names self.executemany_mode = parse_user_argument_for_enum( executemany_mode, { EXECUTEMANY_VALUES: ["values_only"], EXECUTEMANY_VALUES_PLUS_BATCH: ["values_plus_batch"], }, "executemany_mode", ) self.executemany_batch_page_size = executemany_batch_page_size if self.dbapi and hasattr(self.dbapi, "__version__"): m = re.match(r"(\d+)\.(\d+)(?:\.(\d+))?", self.dbapi.__version__) if m: self.psycopg2_version = tuple( int(x) for x in m.group(1, 2, 3) if x is not None ) if self.psycopg2_version < (2, 7): raise ImportError( "psycopg2 version 2.7 or higher is required." ) def initialize(self, connection): super().initialize(connection) self._has_native_hstore = ( self.use_native_hstore and self._hstore_oids(connection.connection.dbapi_connection) is not None ) self.supports_sane_multi_rowcount = ( self.executemany_mode is not EXECUTEMANY_VALUES_PLUS_BATCH ) @classmethod def import_dbapi(cls): import psycopg2 return psycopg2 @util.memoized_property def _psycopg2_extensions(cls): from psycopg2 import extensions return extensions @util.memoized_property def _psycopg2_extras(cls): from psycopg2 import extras return extras @util.memoized_property def _isolation_lookup(self): extensions = self._psycopg2_extensions return { "AUTOCOMMIT": extensions.ISOLATION_LEVEL_AUTOCOMMIT, "READ COMMITTED": extensions.ISOLATION_LEVEL_READ_COMMITTED, "READ UNCOMMITTED": extensions.ISOLATION_LEVEL_READ_UNCOMMITTED, "REPEATABLE READ": extensions.ISOLATION_LEVEL_REPEATABLE_READ, "SERIALIZABLE": extensions.ISOLATION_LEVEL_SERIALIZABLE, } def set_isolation_level(self, dbapi_connection, level): dbapi_connection.set_isolation_level(self._isolation_lookup[level]) def set_readonly(self, connection, value): connection.readonly = value def get_readonly(self, connection): return connection.readonly def set_deferrable(self, connection, value): connection.deferrable = value def get_deferrable(self, connection): return connection.deferrable def on_connect(self): extras = self._psycopg2_extras fns = [] if self.client_encoding is not None: def on_connect(dbapi_conn): dbapi_conn.set_client_encoding(self.client_encoding) fns.append(on_connect) if self.dbapi: def on_connect(dbapi_conn): extras.register_uuid(None, dbapi_conn) fns.append(on_connect) if self.dbapi and self.use_native_hstore: def on_connect(dbapi_conn): hstore_oids = self._hstore_oids(dbapi_conn) if hstore_oids is not None: oid, array_oid = hstore_oids kw = {"oid": oid} kw["array_oid"] = array_oid extras.register_hstore(dbapi_conn, **kw) fns.append(on_connect) if self.dbapi and self._json_deserializer: def on_connect(dbapi_conn): extras.register_default_json( dbapi_conn, loads=self._json_deserializer ) extras.register_default_jsonb( dbapi_conn, loads=self._json_deserializer ) fns.append(on_connect) if fns: def on_connect(dbapi_conn): for fn in fns: fn(dbapi_conn) return on_connect else: return None def do_executemany(self, cursor, statement, parameters, context=None): if self.executemany_mode is EXECUTEMANY_VALUES_PLUS_BATCH: if self.executemany_batch_page_size: kwargs = {"page_size": self.executemany_batch_page_size} else: kwargs = {} self._psycopg2_extras.execute_batch( cursor, statement, parameters, **kwargs ) else: cursor.executemany(statement, parameters) def do_begin_twophase(self, connection, xid): connection.connection.tpc_begin(xid) def do_prepare_twophase(self, connection, xid): connection.connection.tpc_prepare() def _do_twophase(self, dbapi_conn, operation, xid, recover=False): if recover: if dbapi_conn.status != self._psycopg2_extensions.STATUS_READY: dbapi_conn.rollback() operation(xid) else: operation() def do_rollback_twophase( self, connection, xid, is_prepared=True, recover=False ): dbapi_conn = connection.connection.dbapi_connection self._do_twophase( dbapi_conn, dbapi_conn.tpc_rollback, xid, recover=recover ) def do_commit_twophase( self, connection, xid, is_prepared=True, recover=False ): dbapi_conn = connection.connection.dbapi_connection self._do_twophase( dbapi_conn, dbapi_conn.tpc_commit, xid, recover=recover ) @util.memoized_instancemethod def _hstore_oids(self, dbapi_connection): extras = self._psycopg2_extras oids = extras.HstoreAdapter.get_oids(dbapi_connection) if oids is not None and oids[0]: return oids[0:2] else: return None def is_disconnect(self, e, connection, cursor): if isinstance(e, self.dbapi.Error): # check the "closed" flag. this might not be # present on old psycopg2 versions. Also, # this flag doesn't actually help in a lot of disconnect # situations, so don't rely on it. if getattr(connection, "closed", False): return True # checks based on strings. in the case that .closed # didn't cut it, fall back onto these. str_e = str(e).partition("\n")[0] for msg in self._is_disconnect_messages: idx = str_e.find(msg) if idx >= 0 and '"' not in str_e[:idx]: return True return False @util.memoized_property def _is_disconnect_messages(self): return ( # these error messages from libpq: interfaces/libpq/fe-misc.c # and interfaces/libpq/fe-secure.c. "terminating connection", "closed the connection", "connection not open", "could not receive data from server", "could not send data to server", # psycopg2 client errors, psycopg2/connection.h, # psycopg2/cursor.h "connection already closed", "cursor already closed", # not sure where this path is originally from, it may # be obsolete. It really says "losed", not "closed". "losed the connection unexpectedly", # these can occur in newer SSL "connection has been closed unexpectedly", "SSL error: decryption failed or bad record mac", "SSL SYSCALL error: Bad file descriptor", "SSL SYSCALL error: EOF detected", "SSL SYSCALL error: Operation timed out", "SSL SYSCALL error: Bad address", # This can occur in OpenSSL 1 when an unexpected EOF occurs. # https://www.openssl.org/docs/man1.1.1/man3/SSL_get_error.html#BUGS # It may also occur in newer OpenSSL for a non-recoverable I/O # error as a result of a system call that does not set 'errno' # in libc. "SSL SYSCALL error: Success", ) dialect = PGDialect_psycopg2 sqlalchemy/dialects/postgresql/base.py 0000755 00000547322 15125143220 0014200 0 ustar 00 # dialects/postgresql/base.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors r""" .. dialect:: postgresql :name: PostgreSQL :normal_support: 9.6+ :best_effort: 9+ .. _postgresql_sequences: Sequences/SERIAL/IDENTITY ------------------------- PostgreSQL supports sequences, and SQLAlchemy uses these as the default means of creating new primary key values for integer-based primary key columns. When creating tables, SQLAlchemy will issue the ``SERIAL`` datatype for integer-based primary key columns, which generates a sequence and server side default corresponding to the column. To specify a specific named sequence to be used for primary key generation, use the :func:`~sqlalchemy.schema.Sequence` construct:: Table( "sometable", metadata, Column( "id", Integer, Sequence("some_id_seq", start=1), primary_key=True ), ) When SQLAlchemy issues a single INSERT statement, to fulfill the contract of having the "last insert identifier" available, a RETURNING clause is added to the INSERT statement which specifies the primary key columns should be returned after the statement completes. The RETURNING functionality only takes place if PostgreSQL 8.2 or later is in use. As a fallback approach, the sequence, whether specified explicitly or implicitly via ``SERIAL``, is executed independently beforehand, the returned value to be used in the subsequent insert. Note that when an :func:`~sqlalchemy.sql.expression.insert()` construct is executed using "executemany" semantics, the "last inserted identifier" functionality does not apply; no RETURNING clause is emitted nor is the sequence pre-executed in this case. PostgreSQL 10 and above IDENTITY columns ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PostgreSQL 10 and above have a new IDENTITY feature that supersedes the use of SERIAL. The :class:`_schema.Identity` construct in a :class:`_schema.Column` can be used to control its behavior:: from sqlalchemy import Table, Column, MetaData, Integer, Computed metadata = MetaData() data = Table( "data", metadata, Column( "id", Integer, Identity(start=42, cycle=True), primary_key=True ), Column("data", String), ) The CREATE TABLE for the above :class:`_schema.Table` object would be: .. sourcecode:: sql CREATE TABLE data ( id INTEGER GENERATED BY DEFAULT AS IDENTITY (START WITH 42 CYCLE), data VARCHAR, PRIMARY KEY (id) ) .. versionchanged:: 1.4 Added :class:`_schema.Identity` construct in a :class:`_schema.Column` to specify the option of an autoincrementing column. .. note:: Previous versions of SQLAlchemy did not have built-in support for rendering of IDENTITY, and could use the following compilation hook to replace occurrences of SERIAL with IDENTITY:: from sqlalchemy.schema import CreateColumn from sqlalchemy.ext.compiler import compiles @compiles(CreateColumn, "postgresql") def use_identity(element, compiler, **kw): text = compiler.visit_create_column(element, **kw) text = text.replace("SERIAL", "INT GENERATED BY DEFAULT AS IDENTITY") return text Using the above, a table such as:: t = Table( "t", m, Column("id", Integer, primary_key=True), Column("data", String) ) Will generate on the backing database as: .. sourcecode:: sql CREATE TABLE t ( id INT GENERATED BY DEFAULT AS IDENTITY, data VARCHAR, PRIMARY KEY (id) ) .. _postgresql_ss_cursors: Server Side Cursors ------------------- Server-side cursor support is available for the psycopg2, asyncpg dialects and may also be available in others. Server side cursors are enabled on a per-statement basis by using the :paramref:`.Connection.execution_options.stream_results` connection execution option:: with engine.connect() as conn: result = conn.execution_options(stream_results=True).execute( text("select * from table") ) Note that some kinds of SQL statements may not be supported with server side cursors; generally, only SQL statements that return rows should be used with this option. .. deprecated:: 1.4 The dialect-level server_side_cursors flag is deprecated and will be removed in a future release. Please use the :paramref:`_engine.Connection.stream_results` execution option for unbuffered cursor support. .. seealso:: :ref:`engine_stream_results` .. _postgresql_isolation_level: Transaction Isolation Level --------------------------- Most SQLAlchemy dialects support setting of transaction isolation level using the :paramref:`_sa.create_engine.isolation_level` parameter at the :func:`_sa.create_engine` level, and at the :class:`_engine.Connection` level via the :paramref:`.Connection.execution_options.isolation_level` parameter. For PostgreSQL dialects, this feature works either by making use of the DBAPI-specific features, such as psycopg2's isolation level flags which will embed the isolation level setting inline with the ``"BEGIN"`` statement, or for DBAPIs with no direct support by emitting ``SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL <level>`` ahead of the ``"BEGIN"`` statement emitted by the DBAPI. For the special AUTOCOMMIT isolation level, DBAPI-specific techniques are used which is typically an ``.autocommit`` flag on the DBAPI connection object. To set isolation level using :func:`_sa.create_engine`:: engine = create_engine( "postgresql+pg8000://scott:tiger@localhost/test", isolation_level="REPEATABLE READ", ) To set using per-connection execution options:: with engine.connect() as conn: conn = conn.execution_options(isolation_level="REPEATABLE READ") with conn.begin(): ... # work with transaction There are also more options for isolation level configurations, such as "sub-engine" objects linked to a main :class:`_engine.Engine` which each apply different isolation level settings. See the discussion at :ref:`dbapi_autocommit` for background. Valid values for ``isolation_level`` on most PostgreSQL dialects include: * ``READ COMMITTED`` * ``READ UNCOMMITTED`` * ``REPEATABLE READ`` * ``SERIALIZABLE`` * ``AUTOCOMMIT`` .. seealso:: :ref:`dbapi_autocommit` :ref:`postgresql_readonly_deferrable` :ref:`psycopg2_isolation_level` :ref:`pg8000_isolation_level` .. _postgresql_readonly_deferrable: Setting READ ONLY / DEFERRABLE ------------------------------ Most PostgreSQL dialects support setting the "READ ONLY" and "DEFERRABLE" characteristics of the transaction, which is in addition to the isolation level setting. These two attributes can be established either in conjunction with or independently of the isolation level by passing the ``postgresql_readonly`` and ``postgresql_deferrable`` flags with :meth:`_engine.Connection.execution_options`. The example below illustrates passing the ``"SERIALIZABLE"`` isolation level at the same time as setting "READ ONLY" and "DEFERRABLE":: with engine.connect() as conn: conn = conn.execution_options( isolation_level="SERIALIZABLE", postgresql_readonly=True, postgresql_deferrable=True, ) with conn.begin(): ... # work with transaction Note that some DBAPIs such as asyncpg only support "readonly" with SERIALIZABLE isolation. .. versionadded:: 1.4 added support for the ``postgresql_readonly`` and ``postgresql_deferrable`` execution options. .. _postgresql_reset_on_return: Temporary Table / Resource Reset for Connection Pooling ------------------------------------------------------- The :class:`.QueuePool` connection pool implementation used by the SQLAlchemy :class:`.Engine` object includes :ref:`reset on return <pool_reset_on_return>` behavior that will invoke the DBAPI ``.rollback()`` method when connections are returned to the pool. While this rollback will clear out the immediate state used by the previous transaction, it does not cover a wider range of session-level state, including temporary tables as well as other server state such as prepared statement handles and statement caches. The PostgreSQL database includes a variety of commands which may be used to reset this state, including ``DISCARD``, ``RESET``, ``DEALLOCATE``, and ``UNLISTEN``. To install one or more of these commands as the means of performing reset-on-return, the :meth:`.PoolEvents.reset` event hook may be used, as demonstrated in the example below. The implementation will end transactions in progress as well as discard temporary tables using the ``CLOSE``, ``RESET`` and ``DISCARD`` commands; see the PostgreSQL documentation for background on what each of these statements do. The :paramref:`_sa.create_engine.pool_reset_on_return` parameter is set to ``None`` so that the custom scheme can replace the default behavior completely. The custom hook implementation calls ``.rollback()`` in any case, as it's usually important that the DBAPI's own tracking of commit/rollback will remain consistent with the state of the transaction:: from sqlalchemy import create_engine from sqlalchemy import event postgresql_engine = create_engine( "postgresql+psycopg2://scott:tiger@hostname/dbname", # disable default reset-on-return scheme pool_reset_on_return=None, ) @event.listens_for(postgresql_engine, "reset") def _reset_postgresql(dbapi_connection, connection_record, reset_state): if not reset_state.terminate_only: dbapi_connection.execute("CLOSE ALL") dbapi_connection.execute("RESET ALL") dbapi_connection.execute("DISCARD TEMP") # so that the DBAPI itself knows that the connection has been # reset dbapi_connection.rollback() .. versionchanged:: 2.0.0b3 Added additional state arguments to the :meth:`.PoolEvents.reset` event and additionally ensured the event is invoked for all "reset" occurrences, so that it's appropriate as a place for custom "reset" handlers. Previous schemes which use the :meth:`.PoolEvents.checkin` handler remain usable as well. .. seealso:: :ref:`pool_reset_on_return` - in the :ref:`pooling_toplevel` documentation .. _postgresql_alternate_search_path: Setting Alternate Search Paths on Connect ------------------------------------------ The PostgreSQL ``search_path`` variable refers to the list of schema names that will be implicitly referenced when a particular table or other object is referenced in a SQL statement. As detailed in the next section :ref:`postgresql_schema_reflection`, SQLAlchemy is generally organized around the concept of keeping this variable at its default value of ``public``, however, in order to have it set to any arbitrary name or names when connections are used automatically, the "SET SESSION search_path" command may be invoked for all connections in a pool using the following event handler, as discussed at :ref:`schema_set_default_connections`:: from sqlalchemy import event from sqlalchemy import create_engine engine = create_engine("postgresql+psycopg2://scott:tiger@host/dbname") @event.listens_for(engine, "connect", insert=True) def set_search_path(dbapi_connection, connection_record): existing_autocommit = dbapi_connection.autocommit dbapi_connection.autocommit = True cursor = dbapi_connection.cursor() cursor.execute("SET SESSION search_path='%s'" % schema_name) cursor.close() dbapi_connection.autocommit = existing_autocommit The reason the recipe is complicated by use of the ``.autocommit`` DBAPI attribute is so that when the ``SET SESSION search_path`` directive is invoked, it is invoked outside of the scope of any transaction and therefore will not be reverted when the DBAPI connection has a rollback. .. seealso:: :ref:`schema_set_default_connections` - in the :ref:`metadata_toplevel` documentation .. _postgresql_schema_reflection: Remote-Schema Table Introspection and PostgreSQL search_path ------------------------------------------------------------ .. admonition:: Section Best Practices Summarized keep the ``search_path`` variable set to its default of ``public``, without any other schema names. Ensure the username used to connect **does not** match remote schemas, or ensure the ``"$user"`` token is **removed** from ``search_path``. For other schema names, name these explicitly within :class:`_schema.Table` definitions. Alternatively, the ``postgresql_ignore_search_path`` option will cause all reflected :class:`_schema.Table` objects to have a :attr:`_schema.Table.schema` attribute set up. The PostgreSQL dialect can reflect tables from any schema, as outlined in :ref:`metadata_reflection_schemas`. In all cases, the first thing SQLAlchemy does when reflecting tables is to **determine the default schema for the current database connection**. It does this using the PostgreSQL ``current_schema()`` function, illustated below using a PostgreSQL client session (i.e. using the ``psql`` tool): .. sourcecode:: sql test=> select current_schema(); current_schema ---------------- public (1 row) Above we see that on a plain install of PostgreSQL, the default schema name is the name ``public``. However, if your database username **matches the name of a schema**, PostgreSQL's default is to then **use that name as the default schema**. Below, we log in using the username ``scott``. When we create a schema named ``scott``, **it implicitly changes the default schema**: .. sourcecode:: sql test=> select current_schema(); current_schema ---------------- public (1 row) test=> create schema scott; CREATE SCHEMA test=> select current_schema(); current_schema ---------------- scott (1 row) The behavior of ``current_schema()`` is derived from the `PostgreSQL search path <https://www.postgresql.org/docs/current/static/ddl-schemas.html#DDL-SCHEMAS-PATH>`_ variable ``search_path``, which in modern PostgreSQL versions defaults to this: .. sourcecode:: sql test=> show search_path; search_path ----------------- "$user", public (1 row) Where above, the ``"$user"`` variable will inject the current username as the default schema, if one exists. Otherwise, ``public`` is used. When a :class:`_schema.Table` object is reflected, if it is present in the schema indicated by the ``current_schema()`` function, **the schema name assigned to the ".schema" attribute of the Table is the Python "None" value**. Otherwise, the ".schema" attribute will be assigned the string name of that schema. With regards to tables which these :class:`_schema.Table` objects refer to via foreign key constraint, a decision must be made as to how the ``.schema`` is represented in those remote tables, in the case where that remote schema name is also a member of the current ``search_path``. By default, the PostgreSQL dialect mimics the behavior encouraged by PostgreSQL's own ``pg_get_constraintdef()`` builtin procedure. This function returns a sample definition for a particular foreign key constraint, omitting the referenced schema name from that definition when the name is also in the PostgreSQL schema search path. The interaction below illustrates this behavior: .. sourcecode:: sql test=> CREATE TABLE test_schema.referred(id INTEGER PRIMARY KEY); CREATE TABLE test=> CREATE TABLE referring( test(> id INTEGER PRIMARY KEY, test(> referred_id INTEGER REFERENCES test_schema.referred(id)); CREATE TABLE test=> SET search_path TO public, test_schema; test=> SELECT pg_catalog.pg_get_constraintdef(r.oid, true) FROM test-> pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n test-> ON n.oid = c.relnamespace test-> JOIN pg_catalog.pg_constraint r ON c.oid = r.conrelid test-> WHERE c.relname='referring' AND r.contype = 'f' test-> ; pg_get_constraintdef --------------------------------------------------- FOREIGN KEY (referred_id) REFERENCES referred(id) (1 row) Above, we created a table ``referred`` as a member of the remote schema ``test_schema``, however when we added ``test_schema`` to the PG ``search_path`` and then asked ``pg_get_constraintdef()`` for the ``FOREIGN KEY`` syntax, ``test_schema`` was not included in the output of the function. On the other hand, if we set the search path back to the typical default of ``public``: .. sourcecode:: sql test=> SET search_path TO public; SET The same query against ``pg_get_constraintdef()`` now returns the fully schema-qualified name for us: .. sourcecode:: sql test=> SELECT pg_catalog.pg_get_constraintdef(r.oid, true) FROM test-> pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n test-> ON n.oid = c.relnamespace test-> JOIN pg_catalog.pg_constraint r ON c.oid = r.conrelid test-> WHERE c.relname='referring' AND r.contype = 'f'; pg_get_constraintdef --------------------------------------------------------------- FOREIGN KEY (referred_id) REFERENCES test_schema.referred(id) (1 row) SQLAlchemy will by default use the return value of ``pg_get_constraintdef()`` in order to determine the remote schema name. That is, if our ``search_path`` were set to include ``test_schema``, and we invoked a table reflection process as follows:: >>> from sqlalchemy import Table, MetaData, create_engine, text >>> engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test") >>> with engine.connect() as conn: ... conn.execute(text("SET search_path TO test_schema, public")) ... metadata_obj = MetaData() ... referring = Table("referring", metadata_obj, autoload_with=conn) <sqlalchemy.engine.result.CursorResult object at 0x101612ed0> The above process would deliver to the :attr:`_schema.MetaData.tables` collection ``referred`` table named **without** the schema:: >>> metadata_obj.tables["referred"].schema is None True To alter the behavior of reflection such that the referred schema is maintained regardless of the ``search_path`` setting, use the ``postgresql_ignore_search_path`` option, which can be specified as a dialect-specific argument to both :class:`_schema.Table` as well as :meth:`_schema.MetaData.reflect`:: >>> with engine.connect() as conn: ... conn.execute(text("SET search_path TO test_schema, public")) ... metadata_obj = MetaData() ... referring = Table( ... "referring", ... metadata_obj, ... autoload_with=conn, ... postgresql_ignore_search_path=True, ... ) <sqlalchemy.engine.result.CursorResult object at 0x1016126d0> We will now have ``test_schema.referred`` stored as schema-qualified:: >>> metadata_obj.tables["test_schema.referred"].schema 'test_schema' .. sidebar:: Best Practices for PostgreSQL Schema reflection The description of PostgreSQL schema reflection behavior is complex, and is the product of many years of dealing with widely varied use cases and user preferences. But in fact, there's no need to understand any of it if you just stick to the simplest use pattern: leave the ``search_path`` set to its default of ``public`` only, never refer to the name ``public`` as an explicit schema name otherwise, and refer to all other schema names explicitly when building up a :class:`_schema.Table` object. The options described here are only for those users who can't, or prefer not to, stay within these guidelines. .. seealso:: :ref:`reflection_schema_qualified_interaction` - discussion of the issue from a backend-agnostic perspective `The Schema Search Path <https://www.postgresql.org/docs/current/static/ddl-schemas.html#DDL-SCHEMAS-PATH>`_ - on the PostgreSQL website. INSERT/UPDATE...RETURNING ------------------------- The dialect supports PG 8.2's ``INSERT..RETURNING``, ``UPDATE..RETURNING`` and ``DELETE..RETURNING`` syntaxes. ``INSERT..RETURNING`` is used by default for single-row INSERT statements in order to fetch newly generated primary key identifiers. To specify an explicit ``RETURNING`` clause, use the :meth:`._UpdateBase.returning` method on a per-statement basis:: # INSERT..RETURNING result = ( table.insert().returning(table.c.col1, table.c.col2).values(name="foo") ) print(result.fetchall()) # UPDATE..RETURNING result = ( table.update() .returning(table.c.col1, table.c.col2) .where(table.c.name == "foo") .values(name="bar") ) print(result.fetchall()) # DELETE..RETURNING result = ( table.delete() .returning(table.c.col1, table.c.col2) .where(table.c.name == "foo") ) print(result.fetchall()) .. _postgresql_insert_on_conflict: INSERT...ON CONFLICT (Upsert) ------------------------------ Starting with version 9.5, PostgreSQL allows "upserts" (update or insert) of rows into a table via the ``ON CONFLICT`` clause of the ``INSERT`` statement. A candidate row will only be inserted if that row does not violate any unique constraints. In the case of a unique constraint violation, a secondary action can occur which can be either "DO UPDATE", indicating that the data in the target row should be updated, or "DO NOTHING", which indicates to silently skip this row. Conflicts are determined using existing unique constraints and indexes. These constraints may be identified either using their name as stated in DDL, or they may be inferred by stating the columns and conditions that comprise the indexes. SQLAlchemy provides ``ON CONFLICT`` support via the PostgreSQL-specific :func:`_postgresql.insert()` function, which provides the generative methods :meth:`_postgresql.Insert.on_conflict_do_update` and :meth:`~.postgresql.Insert.on_conflict_do_nothing`: .. sourcecode:: pycon+sql >>> from sqlalchemy.dialects.postgresql import insert >>> insert_stmt = insert(my_table).values( ... id="some_existing_id", data="inserted value" ... ) >>> do_nothing_stmt = insert_stmt.on_conflict_do_nothing(index_elements=["id"]) >>> print(do_nothing_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (%(id)s, %(data)s) ON CONFLICT (id) DO NOTHING {stop} >>> do_update_stmt = insert_stmt.on_conflict_do_update( ... constraint="pk_my_table", set_=dict(data="updated value") ... ) >>> print(do_update_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (%(id)s, %(data)s) ON CONFLICT ON CONSTRAINT pk_my_table DO UPDATE SET data = %(param_1)s .. seealso:: `INSERT .. ON CONFLICT <https://www.postgresql.org/docs/current/static/sql-insert.html#SQL-ON-CONFLICT>`_ - in the PostgreSQL documentation. Specifying the Target ^^^^^^^^^^^^^^^^^^^^^ Both methods supply the "target" of the conflict using either the named constraint or by column inference: * The :paramref:`_postgresql.Insert.on_conflict_do_update.index_elements` argument specifies a sequence containing string column names, :class:`_schema.Column` objects, and/or SQL expression elements, which would identify a unique index: .. sourcecode:: pycon+sql >>> do_update_stmt = insert_stmt.on_conflict_do_update( ... index_elements=["id"], set_=dict(data="updated value") ... ) >>> print(do_update_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (%(id)s, %(data)s) ON CONFLICT (id) DO UPDATE SET data = %(param_1)s {stop} >>> do_update_stmt = insert_stmt.on_conflict_do_update( ... index_elements=[my_table.c.id], set_=dict(data="updated value") ... ) >>> print(do_update_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (%(id)s, %(data)s) ON CONFLICT (id) DO UPDATE SET data = %(param_1)s * When using :paramref:`_postgresql.Insert.on_conflict_do_update.index_elements` to infer an index, a partial index can be inferred by also specifying the use the :paramref:`_postgresql.Insert.on_conflict_do_update.index_where` parameter: .. sourcecode:: pycon+sql >>> stmt = insert(my_table).values(user_email="a@b.com", data="inserted data") >>> stmt = stmt.on_conflict_do_update( ... index_elements=[my_table.c.user_email], ... index_where=my_table.c.user_email.like("%@gmail.com"), ... set_=dict(data=stmt.excluded.data), ... ) >>> print(stmt) {printsql}INSERT INTO my_table (data, user_email) VALUES (%(data)s, %(user_email)s) ON CONFLICT (user_email) WHERE user_email LIKE %(user_email_1)s DO UPDATE SET data = excluded.data * The :paramref:`_postgresql.Insert.on_conflict_do_update.constraint` argument is used to specify an index directly rather than inferring it. This can be the name of a UNIQUE constraint, a PRIMARY KEY constraint, or an INDEX: .. sourcecode:: pycon+sql >>> do_update_stmt = insert_stmt.on_conflict_do_update( ... constraint="my_table_idx_1", set_=dict(data="updated value") ... ) >>> print(do_update_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (%(id)s, %(data)s) ON CONFLICT ON CONSTRAINT my_table_idx_1 DO UPDATE SET data = %(param_1)s {stop} >>> do_update_stmt = insert_stmt.on_conflict_do_update( ... constraint="my_table_pk", set_=dict(data="updated value") ... ) >>> print(do_update_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (%(id)s, %(data)s) ON CONFLICT ON CONSTRAINT my_table_pk DO UPDATE SET data = %(param_1)s {stop} * The :paramref:`_postgresql.Insert.on_conflict_do_update.constraint` argument may also refer to a SQLAlchemy construct representing a constraint, e.g. :class:`.UniqueConstraint`, :class:`.PrimaryKeyConstraint`, :class:`.Index`, or :class:`.ExcludeConstraint`. In this use, if the constraint has a name, it is used directly. Otherwise, if the constraint is unnamed, then inference will be used, where the expressions and optional WHERE clause of the constraint will be spelled out in the construct. This use is especially convenient to refer to the named or unnamed primary key of a :class:`_schema.Table` using the :attr:`_schema.Table.primary_key` attribute: .. sourcecode:: pycon+sql >>> do_update_stmt = insert_stmt.on_conflict_do_update( ... constraint=my_table.primary_key, set_=dict(data="updated value") ... ) >>> print(do_update_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (%(id)s, %(data)s) ON CONFLICT (id) DO UPDATE SET data = %(param_1)s The SET Clause ^^^^^^^^^^^^^^^ ``ON CONFLICT...DO UPDATE`` is used to perform an update of the already existing row, using any combination of new values as well as values from the proposed insertion. These values are specified using the :paramref:`_postgresql.Insert.on_conflict_do_update.set_` parameter. This parameter accepts a dictionary which consists of direct values for UPDATE: .. sourcecode:: pycon+sql >>> stmt = insert(my_table).values(id="some_id", data="inserted value") >>> do_update_stmt = stmt.on_conflict_do_update( ... index_elements=["id"], set_=dict(data="updated value") ... ) >>> print(do_update_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (%(id)s, %(data)s) ON CONFLICT (id) DO UPDATE SET data = %(param_1)s .. warning:: The :meth:`_expression.Insert.on_conflict_do_update` method does **not** take into account Python-side default UPDATE values or generation functions, e.g. those specified using :paramref:`_schema.Column.onupdate`. These values will not be exercised for an ON CONFLICT style of UPDATE, unless they are manually specified in the :paramref:`_postgresql.Insert.on_conflict_do_update.set_` dictionary. Updating using the Excluded INSERT Values ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In order to refer to the proposed insertion row, the special alias :attr:`~.postgresql.Insert.excluded` is available as an attribute on the :class:`_postgresql.Insert` object; this object is a :class:`_expression.ColumnCollection` which alias contains all columns of the target table: .. sourcecode:: pycon+sql >>> stmt = insert(my_table).values( ... id="some_id", data="inserted value", author="jlh" ... ) >>> do_update_stmt = stmt.on_conflict_do_update( ... index_elements=["id"], ... set_=dict(data="updated value", author=stmt.excluded.author), ... ) >>> print(do_update_stmt) {printsql}INSERT INTO my_table (id, data, author) VALUES (%(id)s, %(data)s, %(author)s) ON CONFLICT (id) DO UPDATE SET data = %(param_1)s, author = excluded.author Additional WHERE Criteria ^^^^^^^^^^^^^^^^^^^^^^^^^ The :meth:`_expression.Insert.on_conflict_do_update` method also accepts a WHERE clause using the :paramref:`_postgresql.Insert.on_conflict_do_update.where` parameter, which will limit those rows which receive an UPDATE: .. sourcecode:: pycon+sql >>> stmt = insert(my_table).values( ... id="some_id", data="inserted value", author="jlh" ... ) >>> on_update_stmt = stmt.on_conflict_do_update( ... index_elements=["id"], ... set_=dict(data="updated value", author=stmt.excluded.author), ... where=(my_table.c.status == 2), ... ) >>> print(on_update_stmt) {printsql}INSERT INTO my_table (id, data, author) VALUES (%(id)s, %(data)s, %(author)s) ON CONFLICT (id) DO UPDATE SET data = %(param_1)s, author = excluded.author WHERE my_table.status = %(status_1)s Skipping Rows with DO NOTHING ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``ON CONFLICT`` may be used to skip inserting a row entirely if any conflict with a unique or exclusion constraint occurs; below this is illustrated using the :meth:`~.postgresql.Insert.on_conflict_do_nothing` method: .. sourcecode:: pycon+sql >>> stmt = insert(my_table).values(id="some_id", data="inserted value") >>> stmt = stmt.on_conflict_do_nothing(index_elements=["id"]) >>> print(stmt) {printsql}INSERT INTO my_table (id, data) VALUES (%(id)s, %(data)s) ON CONFLICT (id) DO NOTHING If ``DO NOTHING`` is used without specifying any columns or constraint, it has the effect of skipping the INSERT for any unique or exclusion constraint violation which occurs: .. sourcecode:: pycon+sql >>> stmt = insert(my_table).values(id="some_id", data="inserted value") >>> stmt = stmt.on_conflict_do_nothing() >>> print(stmt) {printsql}INSERT INTO my_table (id, data) VALUES (%(id)s, %(data)s) ON CONFLICT DO NOTHING .. _postgresql_match: Full Text Search ---------------- PostgreSQL's full text search system is available through the use of the :data:`.func` namespace, combined with the use of custom operators via the :meth:`.Operators.bool_op` method. For simple cases with some degree of cross-backend compatibility, the :meth:`.Operators.match` operator may also be used. .. _postgresql_simple_match: Simple plain text matching with ``match()`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The :meth:`.Operators.match` operator provides for cross-compatible simple text matching. For the PostgreSQL backend, it's hardcoded to generate an expression using the ``@@`` operator in conjunction with the ``plainto_tsquery()`` PostgreSQL function. On the PostgreSQL dialect, an expression like the following:: select(sometable.c.text.match("search string")) would emit to the database: .. sourcecode:: sql SELECT text @@ plainto_tsquery('search string') FROM table Above, passing a plain string to :meth:`.Operators.match` will automatically make use of ``plainto_tsquery()`` to specify the type of tsquery. This establishes basic database cross-compatibility for :meth:`.Operators.match` with other backends. .. versionchanged:: 2.0 The default tsquery generation function used by the PostgreSQL dialect with :meth:`.Operators.match` is ``plainto_tsquery()``. To render exactly what was rendered in 1.4, use the following form:: from sqlalchemy import func select(sometable.c.text.bool_op("@@")(func.to_tsquery("search string"))) Which would emit: .. sourcecode:: sql SELECT text @@ to_tsquery('search string') FROM table Using PostgreSQL full text functions and operators directly ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Text search operations beyond the simple use of :meth:`.Operators.match` may make use of the :data:`.func` namespace to generate PostgreSQL full-text functions, in combination with :meth:`.Operators.bool_op` to generate any boolean operator. For example, the query:: select(func.to_tsquery("cat").bool_op("@>")(func.to_tsquery("cat & rat"))) would generate: .. sourcecode:: sql SELECT to_tsquery('cat') @> to_tsquery('cat & rat') The :class:`_postgresql.TSVECTOR` type can provide for explicit CAST:: from sqlalchemy.dialects.postgresql import TSVECTOR from sqlalchemy import select, cast select(cast("some text", TSVECTOR)) produces a statement equivalent to: .. sourcecode:: sql SELECT CAST('some text' AS TSVECTOR) AS anon_1 The ``func`` namespace is augmented by the PostgreSQL dialect to set up correct argument and return types for most full text search functions. These functions are used automatically by the :attr:`_sql.func` namespace assuming the ``sqlalchemy.dialects.postgresql`` package has been imported, or :func:`_sa.create_engine` has been invoked using a ``postgresql`` dialect. These functions are documented at: * :class:`_postgresql.to_tsvector` * :class:`_postgresql.to_tsquery` * :class:`_postgresql.plainto_tsquery` * :class:`_postgresql.phraseto_tsquery` * :class:`_postgresql.websearch_to_tsquery` * :class:`_postgresql.ts_headline` Specifying the "regconfig" with ``match()`` or custom operators ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PostgreSQL's ``plainto_tsquery()`` function accepts an optional "regconfig" argument that is used to instruct PostgreSQL to use a particular pre-computed GIN or GiST index in order to perform the search. When using :meth:`.Operators.match`, this additional parameter may be specified using the ``postgresql_regconfig`` parameter, such as:: select(mytable.c.id).where( mytable.c.title.match("somestring", postgresql_regconfig="english") ) Which would emit: .. sourcecode:: sql SELECT mytable.id FROM mytable WHERE mytable.title @@ plainto_tsquery('english', 'somestring') When using other PostgreSQL search functions with :data:`.func`, the "regconfig" parameter may be passed directly as the initial argument:: select(mytable.c.id).where( func.to_tsvector("english", mytable.c.title).bool_op("@@")( func.to_tsquery("english", "somestring") ) ) produces a statement equivalent to: .. sourcecode:: sql SELECT mytable.id FROM mytable WHERE to_tsvector('english', mytable.title) @@ to_tsquery('english', 'somestring') It is recommended that you use the ``EXPLAIN ANALYZE...`` tool from PostgreSQL to ensure that you are generating queries with SQLAlchemy that take full advantage of any indexes you may have created for full text search. .. seealso:: `Full Text Search <https://www.postgresql.org/docs/current/textsearch-controls.html>`_ - in the PostgreSQL documentation FROM ONLY ... ------------- The dialect supports PostgreSQL's ONLY keyword for targeting only a particular table in an inheritance hierarchy. This can be used to produce the ``SELECT ... FROM ONLY``, ``UPDATE ONLY ...``, and ``DELETE FROM ONLY ...`` syntaxes. It uses SQLAlchemy's hints mechanism:: # SELECT ... FROM ONLY ... result = table.select().with_hint(table, "ONLY", "postgresql") print(result.fetchall()) # UPDATE ONLY ... table.update(values=dict(foo="bar")).with_hint( "ONLY", dialect_name="postgresql" ) # DELETE FROM ONLY ... table.delete().with_hint("ONLY", dialect_name="postgresql") .. _postgresql_indexes: PostgreSQL-Specific Index Options --------------------------------- Several extensions to the :class:`.Index` construct are available, specific to the PostgreSQL dialect. .. _postgresql_covering_indexes: Covering Indexes ^^^^^^^^^^^^^^^^ The ``postgresql_include`` option renders INCLUDE(colname) for the given string names:: Index("my_index", table.c.x, postgresql_include=["y"]) would render the index as ``CREATE INDEX my_index ON table (x) INCLUDE (y)`` Note that this feature requires PostgreSQL 11 or later. .. seealso:: :ref:`postgresql_constraint_options` .. versionadded:: 1.4 .. _postgresql_partial_indexes: Partial Indexes ^^^^^^^^^^^^^^^ Partial indexes add criterion to the index definition so that the index is applied to a subset of rows. These can be specified on :class:`.Index` using the ``postgresql_where`` keyword argument:: Index("my_index", my_table.c.id, postgresql_where=my_table.c.value > 10) .. _postgresql_operator_classes: Operator Classes ^^^^^^^^^^^^^^^^ PostgreSQL allows the specification of an *operator class* for each column of an index (see https://www.postgresql.org/docs/current/interactive/indexes-opclass.html). The :class:`.Index` construct allows these to be specified via the ``postgresql_ops`` keyword argument:: Index( "my_index", my_table.c.id, my_table.c.data, postgresql_ops={"data": "text_pattern_ops", "id": "int4_ops"}, ) Note that the keys in the ``postgresql_ops`` dictionaries are the "key" name of the :class:`_schema.Column`, i.e. the name used to access it from the ``.c`` collection of :class:`_schema.Table`, which can be configured to be different than the actual name of the column as expressed in the database. If ``postgresql_ops`` is to be used against a complex SQL expression such as a function call, then to apply to the column it must be given a label that is identified in the dictionary by name, e.g.:: Index( "my_index", my_table.c.id, func.lower(my_table.c.data).label("data_lower"), postgresql_ops={"data_lower": "text_pattern_ops", "id": "int4_ops"}, ) Operator classes are also supported by the :class:`_postgresql.ExcludeConstraint` construct using the :paramref:`_postgresql.ExcludeConstraint.ops` parameter. See that parameter for details. .. versionadded:: 1.3.21 added support for operator classes with :class:`_postgresql.ExcludeConstraint`. Index Types ^^^^^^^^^^^ PostgreSQL provides several index types: B-Tree, Hash, GiST, and GIN, as well as the ability for users to create their own (see https://www.postgresql.org/docs/current/static/indexes-types.html). These can be specified on :class:`.Index` using the ``postgresql_using`` keyword argument:: Index("my_index", my_table.c.data, postgresql_using="gin") The value passed to the keyword argument will be simply passed through to the underlying CREATE INDEX command, so it *must* be a valid index type for your version of PostgreSQL. .. _postgresql_index_storage: Index Storage Parameters ^^^^^^^^^^^^^^^^^^^^^^^^ PostgreSQL allows storage parameters to be set on indexes. The storage parameters available depend on the index method used by the index. Storage parameters can be specified on :class:`.Index` using the ``postgresql_with`` keyword argument:: Index("my_index", my_table.c.data, postgresql_with={"fillfactor": 50}) PostgreSQL allows to define the tablespace in which to create the index. The tablespace can be specified on :class:`.Index` using the ``postgresql_tablespace`` keyword argument:: Index("my_index", my_table.c.data, postgresql_tablespace="my_tablespace") Note that the same option is available on :class:`_schema.Table` as well. .. _postgresql_index_concurrently: Indexes with CONCURRENTLY ^^^^^^^^^^^^^^^^^^^^^^^^^ The PostgreSQL index option CONCURRENTLY is supported by passing the flag ``postgresql_concurrently`` to the :class:`.Index` construct:: tbl = Table("testtbl", m, Column("data", Integer)) idx1 = Index("test_idx1", tbl.c.data, postgresql_concurrently=True) The above index construct will render DDL for CREATE INDEX, assuming PostgreSQL 8.2 or higher is detected or for a connection-less dialect, as: .. sourcecode:: sql CREATE INDEX CONCURRENTLY test_idx1 ON testtbl (data) For DROP INDEX, assuming PostgreSQL 9.2 or higher is detected or for a connection-less dialect, it will emit: .. sourcecode:: sql DROP INDEX CONCURRENTLY test_idx1 When using CONCURRENTLY, the PostgreSQL database requires that the statement be invoked outside of a transaction block. The Python DBAPI enforces that even for a single statement, a transaction is present, so to use this construct, the DBAPI's "autocommit" mode must be used:: metadata = MetaData() table = Table("foo", metadata, Column("id", String)) index = Index("foo_idx", table.c.id, postgresql_concurrently=True) with engine.connect() as conn: with conn.execution_options(isolation_level="AUTOCOMMIT"): table.create(conn) .. seealso:: :ref:`postgresql_isolation_level` .. _postgresql_index_reflection: PostgreSQL Index Reflection --------------------------- The PostgreSQL database creates a UNIQUE INDEX implicitly whenever the UNIQUE CONSTRAINT construct is used. When inspecting a table using :class:`_reflection.Inspector`, the :meth:`_reflection.Inspector.get_indexes` and the :meth:`_reflection.Inspector.get_unique_constraints` will report on these two constructs distinctly; in the case of the index, the key ``duplicates_constraint`` will be present in the index entry if it is detected as mirroring a constraint. When performing reflection using ``Table(..., autoload_with=engine)``, the UNIQUE INDEX is **not** returned in :attr:`_schema.Table.indexes` when it is detected as mirroring a :class:`.UniqueConstraint` in the :attr:`_schema.Table.constraints` collection . Special Reflection Options -------------------------- The :class:`_reflection.Inspector` used for the PostgreSQL backend is an instance of :class:`.PGInspector`, which offers additional methods:: from sqlalchemy import create_engine, inspect engine = create_engine("postgresql+psycopg2://localhost/test") insp = inspect(engine) # will be a PGInspector print(insp.get_enums()) .. autoclass:: PGInspector :members: .. _postgresql_table_options: PostgreSQL Table Options ------------------------ Several options for CREATE TABLE are supported directly by the PostgreSQL dialect in conjunction with the :class:`_schema.Table` construct: * ``INHERITS``:: Table("some_table", metadata, ..., postgresql_inherits="some_supertable") Table("some_table", metadata, ..., postgresql_inherits=("t1", "t2", ...)) * ``ON COMMIT``:: Table("some_table", metadata, ..., postgresql_on_commit="PRESERVE ROWS") * ``PARTITION BY``:: Table( "some_table", metadata, ..., postgresql_partition_by="LIST (part_column)", ) .. versionadded:: 1.2.6 * ``TABLESPACE``:: Table("some_table", metadata, ..., postgresql_tablespace="some_tablespace") The above option is also available on the :class:`.Index` construct. * ``USING``:: Table("some_table", metadata, ..., postgresql_using="heap") .. versionadded:: 2.0.26 * ``WITH OIDS``:: Table("some_table", metadata, ..., postgresql_with_oids=True) * ``WITHOUT OIDS``:: Table("some_table", metadata, ..., postgresql_with_oids=False) .. seealso:: `PostgreSQL CREATE TABLE options <https://www.postgresql.org/docs/current/static/sql-createtable.html>`_ - in the PostgreSQL documentation. .. _postgresql_constraint_options: PostgreSQL Constraint Options ----------------------------- The following option(s) are supported by the PostgreSQL dialect in conjunction with selected constraint constructs: * ``NOT VALID``: This option applies towards CHECK and FOREIGN KEY constraints when the constraint is being added to an existing table via ALTER TABLE, and has the effect that existing rows are not scanned during the ALTER operation against the constraint being added. When using a SQL migration tool such as `Alembic <https://alembic.sqlalchemy.org>`_ that renders ALTER TABLE constructs, the ``postgresql_not_valid`` argument may be specified as an additional keyword argument within the operation that creates the constraint, as in the following Alembic example:: def update(): op.create_foreign_key( "fk_user_address", "address", "user", ["user_id"], ["id"], postgresql_not_valid=True, ) The keyword is ultimately accepted directly by the :class:`_schema.CheckConstraint`, :class:`_schema.ForeignKeyConstraint` and :class:`_schema.ForeignKey` constructs; when using a tool like Alembic, dialect-specific keyword arguments are passed through to these constructs from the migration operation directives:: CheckConstraint("some_field IS NOT NULL", postgresql_not_valid=True) ForeignKeyConstraint( ["some_id"], ["some_table.some_id"], postgresql_not_valid=True ) .. versionadded:: 1.4.32 .. seealso:: `PostgreSQL ALTER TABLE options <https://www.postgresql.org/docs/current/static/sql-altertable.html>`_ - in the PostgreSQL documentation. * ``INCLUDE``: This option adds one or more columns as a "payload" to the unique index created automatically by PostgreSQL for the constraint. For example, the following table definition:: Table( "mytable", metadata, Column("id", Integer, nullable=False), Column("value", Integer, nullable=False), UniqueConstraint("id", postgresql_include=["value"]), ) would produce the DDL statement .. sourcecode:: sql CREATE TABLE mytable ( id INTEGER NOT NULL, value INTEGER NOT NULL, UNIQUE (id) INCLUDE (value) ) Note that this feature requires PostgreSQL 11 or later. .. versionadded:: 2.0.41 .. seealso:: :ref:`postgresql_covering_indexes` .. seealso:: `PostgreSQL CREATE TABLE options <https://www.postgresql.org/docs/current/static/sql-createtable.html>`_ - in the PostgreSQL documentation. * Column list with foreign key ``ON DELETE SET`` actions: This applies to :class:`.ForeignKey` and :class:`.ForeignKeyConstraint`, the :paramref:`.ForeignKey.ondelete` parameter will accept on the PostgreSQL backend only a string list of column names inside parenthesis, following the ``SET NULL`` or ``SET DEFAULT`` phrases, which will limit the set of columns that are subject to the action:: fktable = Table( "fktable", metadata, Column("tid", Integer), Column("id", Integer), Column("fk_id_del_set_null", Integer), ForeignKeyConstraint( columns=["tid", "fk_id_del_set_null"], refcolumns=[pktable.c.tid, pktable.c.id], ondelete="SET NULL (fk_id_del_set_null)", ), ) .. versionadded:: 2.0.40 .. _postgresql_table_valued_overview: Table values, Table and Column valued functions, Row and Tuple objects ----------------------------------------------------------------------- PostgreSQL makes great use of modern SQL forms such as table-valued functions, tables and rows as values. These constructs are commonly used as part of PostgreSQL's support for complex datatypes such as JSON, ARRAY, and other datatypes. SQLAlchemy's SQL expression language has native support for most table-valued and row-valued forms. .. _postgresql_table_valued: Table-Valued Functions ^^^^^^^^^^^^^^^^^^^^^^^ Many PostgreSQL built-in functions are intended to be used in the FROM clause of a SELECT statement, and are capable of returning table rows or sets of table rows. A large portion of PostgreSQL's JSON functions for example such as ``json_array_elements()``, ``json_object_keys()``, ``json_each_text()``, ``json_each()``, ``json_to_record()``, ``json_populate_recordset()`` use such forms. These classes of SQL function calling forms in SQLAlchemy are available using the :meth:`_functions.FunctionElement.table_valued` method in conjunction with :class:`_functions.Function` objects generated from the :data:`_sql.func` namespace. Examples from PostgreSQL's reference documentation follow below: * ``json_each()``: .. sourcecode:: pycon+sql >>> from sqlalchemy import select, func >>> stmt = select( ... func.json_each('{"a":"foo", "b":"bar"}').table_valued("key", "value") ... ) >>> print(stmt) {printsql}SELECT anon_1.key, anon_1.value FROM json_each(:json_each_1) AS anon_1 * ``json_populate_record()``: .. sourcecode:: pycon+sql >>> from sqlalchemy import select, func, literal_column >>> stmt = select( ... func.json_populate_record( ... literal_column("null::myrowtype"), '{"a":1,"b":2}' ... ).table_valued("a", "b", name="x") ... ) >>> print(stmt) {printsql}SELECT x.a, x.b FROM json_populate_record(null::myrowtype, :json_populate_record_1) AS x * ``json_to_record()`` - this form uses a PostgreSQL specific form of derived columns in the alias, where we may make use of :func:`_sql.column` elements with types to produce them. The :meth:`_functions.FunctionElement.table_valued` method produces a :class:`_sql.TableValuedAlias` construct, and the method :meth:`_sql.TableValuedAlias.render_derived` method sets up the derived columns specification: .. sourcecode:: pycon+sql >>> from sqlalchemy import select, func, column, Integer, Text >>> stmt = select( ... func.json_to_record('{"a":1,"b":[1,2,3],"c":"bar"}') ... .table_valued( ... column("a", Integer), ... column("b", Text), ... column("d", Text), ... ) ... .render_derived(name="x", with_types=True) ... ) >>> print(stmt) {printsql}SELECT x.a, x.b, x.d FROM json_to_record(:json_to_record_1) AS x(a INTEGER, b TEXT, d TEXT) * ``WITH ORDINALITY`` - part of the SQL standard, ``WITH ORDINALITY`` adds an ordinal counter to the output of a function and is accepted by a limited set of PostgreSQL functions including ``unnest()`` and ``generate_series()``. The :meth:`_functions.FunctionElement.table_valued` method accepts a keyword parameter ``with_ordinality`` for this purpose, which accepts the string name that will be applied to the "ordinality" column: .. sourcecode:: pycon+sql >>> from sqlalchemy import select, func >>> stmt = select( ... func.generate_series(4, 1, -1) ... .table_valued("value", with_ordinality="ordinality") ... .render_derived() ... ) >>> print(stmt) {printsql}SELECT anon_1.value, anon_1.ordinality FROM generate_series(:generate_series_1, :generate_series_2, :generate_series_3) WITH ORDINALITY AS anon_1(value, ordinality) .. versionadded:: 1.4.0b2 .. seealso:: :ref:`tutorial_functions_table_valued` - in the :ref:`unified_tutorial` .. _postgresql_column_valued: Column Valued Functions ^^^^^^^^^^^^^^^^^^^^^^^ Similar to the table valued function, a column valued function is present in the FROM clause, but delivers itself to the columns clause as a single scalar value. PostgreSQL functions such as ``json_array_elements()``, ``unnest()`` and ``generate_series()`` may use this form. Column valued functions are available using the :meth:`_functions.FunctionElement.column_valued` method of :class:`_functions.FunctionElement`: * ``json_array_elements()``: .. sourcecode:: pycon+sql >>> from sqlalchemy import select, func >>> stmt = select( ... func.json_array_elements('["one", "two"]').column_valued("x") ... ) >>> print(stmt) {printsql}SELECT x FROM json_array_elements(:json_array_elements_1) AS x * ``unnest()`` - in order to generate a PostgreSQL ARRAY literal, the :func:`_postgresql.array` construct may be used: .. sourcecode:: pycon+sql >>> from sqlalchemy.dialects.postgresql import array >>> from sqlalchemy import select, func >>> stmt = select(func.unnest(array([1, 2])).column_valued()) >>> print(stmt) {printsql}SELECT anon_1 FROM unnest(ARRAY[%(param_1)s, %(param_2)s]) AS anon_1 The function can of course be used against an existing table-bound column that's of type :class:`_types.ARRAY`: .. sourcecode:: pycon+sql >>> from sqlalchemy import table, column, ARRAY, Integer >>> from sqlalchemy import select, func >>> t = table("t", column("value", ARRAY(Integer))) >>> stmt = select(func.unnest(t.c.value).column_valued("unnested_value")) >>> print(stmt) {printsql}SELECT unnested_value FROM unnest(t.value) AS unnested_value .. seealso:: :ref:`tutorial_functions_column_valued` - in the :ref:`unified_tutorial` Row Types ^^^^^^^^^ Built-in support for rendering a ``ROW`` may be approximated using ``func.ROW`` with the :attr:`_sa.func` namespace, or by using the :func:`_sql.tuple_` construct: .. sourcecode:: pycon+sql >>> from sqlalchemy import table, column, func, tuple_ >>> t = table("t", column("id"), column("fk")) >>> stmt = ( ... t.select() ... .where(tuple_(t.c.id, t.c.fk) > (1, 2)) ... .where(func.ROW(t.c.id, t.c.fk) < func.ROW(3, 7)) ... ) >>> print(stmt) {printsql}SELECT t.id, t.fk FROM t WHERE (t.id, t.fk) > (:param_1, :param_2) AND ROW(t.id, t.fk) < ROW(:ROW_1, :ROW_2) .. seealso:: `PostgreSQL Row Constructors <https://www.postgresql.org/docs/current/sql-expressions.html#SQL-SYNTAX-ROW-CONSTRUCTORS>`_ `PostgreSQL Row Constructor Comparison <https://www.postgresql.org/docs/current/functions-comparisons.html#ROW-WISE-COMPARISON>`_ Table Types passed to Functions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PostgreSQL supports passing a table as an argument to a function, which is known as a "record" type. SQLAlchemy :class:`_sql.FromClause` objects such as :class:`_schema.Table` support this special form using the :meth:`_sql.FromClause.table_valued` method, which is comparable to the :meth:`_functions.FunctionElement.table_valued` method except that the collection of columns is already established by that of the :class:`_sql.FromClause` itself: .. sourcecode:: pycon+sql >>> from sqlalchemy import table, column, func, select >>> a = table("a", column("id"), column("x"), column("y")) >>> stmt = select(func.row_to_json(a.table_valued())) >>> print(stmt) {printsql}SELECT row_to_json(a) AS row_to_json_1 FROM a .. versionadded:: 1.4.0b2 """ # noqa: E501 from __future__ import annotations from collections import defaultdict from functools import lru_cache import re from typing import Any from typing import cast from typing import Dict from typing import List from typing import Optional from typing import Tuple from typing import TYPE_CHECKING from typing import Union from . import arraylib as _array from . import json as _json from . import pg_catalog from . import ranges as _ranges from .ext import _regconfig_fn from .ext import aggregate_order_by from .hstore import HSTORE from .named_types import CreateDomainType as CreateDomainType # noqa: F401 from .named_types import CreateEnumType as CreateEnumType # noqa: F401 from .named_types import DOMAIN as DOMAIN # noqa: F401 from .named_types import DropDomainType as DropDomainType # noqa: F401 from .named_types import DropEnumType as DropEnumType # noqa: F401 from .named_types import ENUM as ENUM # noqa: F401 from .named_types import NamedType as NamedType # noqa: F401 from .types import _DECIMAL_TYPES # noqa: F401 from .types import _FLOAT_TYPES # noqa: F401 from .types import _INT_TYPES # noqa: F401 from .types import BIT as BIT from .types import BYTEA as BYTEA from .types import CIDR as CIDR from .types import CITEXT as CITEXT from .types import INET as INET from .types import INTERVAL as INTERVAL from .types import MACADDR as MACADDR from .types import MACADDR8 as MACADDR8 from .types import MONEY as MONEY from .types import OID as OID from .types import PGBit as PGBit # noqa: F401 from .types import PGCidr as PGCidr # noqa: F401 from .types import PGInet as PGInet # noqa: F401 from .types import PGInterval as PGInterval # noqa: F401 from .types import PGMacAddr as PGMacAddr # noqa: F401 from .types import PGMacAddr8 as PGMacAddr8 # noqa: F401 from .types import PGUuid as PGUuid from .types import REGCLASS as REGCLASS from .types import REGCONFIG as REGCONFIG # noqa: F401 from .types import TIME as TIME from .types import TIMESTAMP as TIMESTAMP from .types import TSVECTOR as TSVECTOR from ... import exc from ... import schema from ... import select from ... import sql from ... import util from ...engine import characteristics from ...engine import default from ...engine import interfaces from ...engine import ObjectKind from ...engine import ObjectScope from ...engine import reflection from ...engine import URL from ...engine.reflection import ReflectionDefaults from ...sql import bindparam from ...sql import coercions from ...sql import compiler from ...sql import elements from ...sql import expression from ...sql import roles from ...sql import sqltypes from ...sql import util as sql_util from ...sql.compiler import InsertmanyvaluesSentinelOpts from ...sql.visitors import InternalTraversal from ...types import BIGINT from ...types import BOOLEAN from ...types import CHAR from ...types import DATE from ...types import DOUBLE_PRECISION from ...types import FLOAT from ...types import INTEGER from ...types import NUMERIC from ...types import REAL from ...types import SMALLINT from ...types import TEXT from ...types import UUID as UUID from ...types import VARCHAR from ...util.typing import TypedDict IDX_USING = re.compile(r"^(?:btree|hash|gist|gin|[\w_]+)$", re.I) RESERVED_WORDS = { "all", "analyse", "analyze", "and", "any", "array", "as", "asc", "asymmetric", "both", "case", "cast", "check", "collate", "column", "constraint", "create", "current_catalog", "current_date", "current_role", "current_time", "current_timestamp", "current_user", "default", "deferrable", "desc", "distinct", "do", "else", "end", "except", "false", "fetch", "for", "foreign", "from", "grant", "group", "having", "in", "initially", "intersect", "into", "leading", "limit", "localtime", "localtimestamp", "new", "not", "null", "of", "off", "offset", "old", "on", "only", "or", "order", "placing", "primary", "references", "returning", "select", "session_user", "some", "symmetric", "table", "then", "to", "trailing", "true", "union", "unique", "user", "using", "variadic", "when", "where", "window", "with", "authorization", "between", "binary", "cross", "current_schema", "freeze", "full", "ilike", "inner", "is", "isnull", "join", "left", "like", "natural", "notnull", "outer", "over", "overlaps", "right", "similar", "verbose", } colspecs = { sqltypes.ARRAY: _array.ARRAY, sqltypes.Interval: INTERVAL, sqltypes.Enum: ENUM, sqltypes.JSON.JSONPathType: _json.JSONPATH, sqltypes.JSON: _json.JSON, sqltypes.Uuid: PGUuid, } ischema_names = { "_array": _array.ARRAY, "hstore": HSTORE, "json": _json.JSON, "jsonb": _json.JSONB, "int4range": _ranges.INT4RANGE, "int8range": _ranges.INT8RANGE, "numrange": _ranges.NUMRANGE, "daterange": _ranges.DATERANGE, "tsrange": _ranges.TSRANGE, "tstzrange": _ranges.TSTZRANGE, "int4multirange": _ranges.INT4MULTIRANGE, "int8multirange": _ranges.INT8MULTIRANGE, "nummultirange": _ranges.NUMMULTIRANGE, "datemultirange": _ranges.DATEMULTIRANGE, "tsmultirange": _ranges.TSMULTIRANGE, "tstzmultirange": _ranges.TSTZMULTIRANGE, "integer": INTEGER, "bigint": BIGINT, "smallint": SMALLINT, "character varying": VARCHAR, "character": CHAR, '"char"': sqltypes.String, "name": sqltypes.String, "text": TEXT, "numeric": NUMERIC, "float": FLOAT, "real": REAL, "inet": INET, "cidr": CIDR, "citext": CITEXT, "uuid": UUID, "bit": BIT, "bit varying": BIT, "macaddr": MACADDR, "macaddr8": MACADDR8, "money": MONEY, "oid": OID, "regclass": REGCLASS, "double precision": DOUBLE_PRECISION, "timestamp": TIMESTAMP, "timestamp with time zone": TIMESTAMP, "timestamp without time zone": TIMESTAMP, "time with time zone": TIME, "time without time zone": TIME, "date": DATE, "time": TIME, "bytea": BYTEA, "boolean": BOOLEAN, "interval": INTERVAL, "tsvector": TSVECTOR, } class PGCompiler(compiler.SQLCompiler): def visit_to_tsvector_func(self, element, **kw): return self._assert_pg_ts_ext(element, **kw) def visit_to_tsquery_func(self, element, **kw): return self._assert_pg_ts_ext(element, **kw) def visit_plainto_tsquery_func(self, element, **kw): return self._assert_pg_ts_ext(element, **kw) def visit_phraseto_tsquery_func(self, element, **kw): return self._assert_pg_ts_ext(element, **kw) def visit_websearch_to_tsquery_func(self, element, **kw): return self._assert_pg_ts_ext(element, **kw) def visit_ts_headline_func(self, element, **kw): return self._assert_pg_ts_ext(element, **kw) def _assert_pg_ts_ext(self, element, **kw): if not isinstance(element, _regconfig_fn): # other options here include trying to rewrite the function # with the correct types. however, that means we have to # "un-SQL-ize" the first argument, which can't work in a # generalized way. Also, parent compiler class has already added # the incorrect return type to the result map. So let's just # make sure the function we want is used up front. raise exc.CompileError( f'Can\'t compile "{element.name}()" full text search ' f"function construct that does not originate from the " f'"sqlalchemy.dialects.postgresql" package. ' f'Please ensure "import sqlalchemy.dialects.postgresql" is ' f"called before constructing " f'"sqlalchemy.func.{element.name}()" to ensure registration ' f"of the correct argument and return types." ) return f"{element.name}{self.function_argspec(element, **kw)}" def render_bind_cast(self, type_, dbapi_type, sqltext): if dbapi_type._type_affinity is sqltypes.String and dbapi_type.length: # use VARCHAR with no length for VARCHAR cast. # see #9511 dbapi_type = sqltypes.STRINGTYPE return f"""{sqltext}::{ self.dialect.type_compiler_instance.process( dbapi_type, identifier_preparer=self.preparer ) }""" def visit_array(self, element, **kw): if not element.clauses and not element.type.item_type._isnull: return "ARRAY[]::%s" % element.type.compile(self.dialect) return "ARRAY[%s]" % self.visit_clauselist(element, **kw) def visit_slice(self, element, **kw): return "%s:%s" % ( self.process(element.start, **kw), self.process(element.stop, **kw), ) def visit_bitwise_xor_op_binary(self, binary, operator, **kw): return self._generate_generic_binary(binary, " # ", **kw) def visit_json_getitem_op_binary( self, binary, operator, _cast_applied=False, **kw ): if ( not _cast_applied and binary.type._type_affinity is not sqltypes.JSON ): kw["_cast_applied"] = True return self.process(sql.cast(binary, binary.type), **kw) kw["eager_grouping"] = True return self._generate_generic_binary( binary, " -> " if not _cast_applied else " ->> ", **kw ) def visit_json_path_getitem_op_binary( self, binary, operator, _cast_applied=False, **kw ): if ( not _cast_applied and binary.type._type_affinity is not sqltypes.JSON ): kw["_cast_applied"] = True return self.process(sql.cast(binary, binary.type), **kw) kw["eager_grouping"] = True return self._generate_generic_binary( binary, " #> " if not _cast_applied else " #>> ", **kw ) def visit_getitem_binary(self, binary, operator, **kw): return "%s[%s]" % ( self.process(binary.left, **kw), self.process(binary.right, **kw), ) def visit_aggregate_order_by(self, element, **kw): return "%s ORDER BY %s" % ( self.process(element.target, **kw), self.process(element.order_by, **kw), ) def visit_match_op_binary(self, binary, operator, **kw): if "postgresql_regconfig" in binary.modifiers: regconfig = self.render_literal_value( binary.modifiers["postgresql_regconfig"], sqltypes.STRINGTYPE ) if regconfig: return "%s @@ plainto_tsquery(%s, %s)" % ( self.process(binary.left, **kw), regconfig, self.process(binary.right, **kw), ) return "%s @@ plainto_tsquery(%s)" % ( self.process(binary.left, **kw), self.process(binary.right, **kw), ) def visit_ilike_case_insensitive_operand(self, element, **kw): return element.element._compiler_dispatch(self, **kw) def visit_ilike_op_binary(self, binary, operator, **kw): escape = binary.modifiers.get("escape", None) return "%s ILIKE %s" % ( self.process(binary.left, **kw), self.process(binary.right, **kw), ) + ( " ESCAPE " + self.render_literal_value(escape, sqltypes.STRINGTYPE) if escape is not None else "" ) def visit_not_ilike_op_binary(self, binary, operator, **kw): escape = binary.modifiers.get("escape", None) return "%s NOT ILIKE %s" % ( self.process(binary.left, **kw), self.process(binary.right, **kw), ) + ( " ESCAPE " + self.render_literal_value(escape, sqltypes.STRINGTYPE) if escape is not None else "" ) def _regexp_match(self, base_op, binary, operator, kw): flags = binary.modifiers["flags"] if flags is None: return self._generate_generic_binary( binary, " %s " % base_op, **kw ) if flags == "i": return self._generate_generic_binary( binary, " %s* " % base_op, **kw ) return "%s %s CONCAT('(?', %s, ')', %s)" % ( self.process(binary.left, **kw), base_op, self.render_literal_value(flags, sqltypes.STRINGTYPE), self.process(binary.right, **kw), ) def visit_regexp_match_op_binary(self, binary, operator, **kw): return self._regexp_match("~", binary, operator, kw) def visit_not_regexp_match_op_binary(self, binary, operator, **kw): return self._regexp_match("!~", binary, operator, kw) def visit_regexp_replace_op_binary(self, binary, operator, **kw): string = self.process(binary.left, **kw) pattern_replace = self.process(binary.right, **kw) flags = binary.modifiers["flags"] if flags is None: return "REGEXP_REPLACE(%s, %s)" % ( string, pattern_replace, ) else: return "REGEXP_REPLACE(%s, %s, %s)" % ( string, pattern_replace, self.render_literal_value(flags, sqltypes.STRINGTYPE), ) def visit_empty_set_expr(self, element_types, **kw): # cast the empty set to the type we are comparing against. if # we are comparing against the null type, pick an arbitrary # datatype for the empty set return "SELECT %s WHERE 1!=1" % ( ", ".join( "CAST(NULL AS %s)" % self.dialect.type_compiler_instance.process( INTEGER() if type_._isnull else type_ ) for type_ in element_types or [INTEGER()] ), ) def render_literal_value(self, value, type_): value = super().render_literal_value(value, type_) if self.dialect._backslash_escapes: value = value.replace("\\", "\\\\") return value def visit_aggregate_strings_func(self, fn, **kw): return "string_agg%s" % self.function_argspec(fn) def visit_sequence(self, seq, **kw): return "nextval('%s')" % self.preparer.format_sequence(seq) def limit_clause(self, select, **kw): text = "" if select._limit_clause is not None: text += " \n LIMIT " + self.process(select._limit_clause, **kw) if select._offset_clause is not None: if select._limit_clause is None: text += "\n LIMIT ALL" text += " OFFSET " + self.process(select._offset_clause, **kw) return text def format_from_hint_text(self, sqltext, table, hint, iscrud): if hint.upper() != "ONLY": raise exc.CompileError("Unrecognized hint: %r" % hint) return "ONLY " + sqltext def get_select_precolumns(self, select, **kw): # Do not call super().get_select_precolumns because # it will warn/raise when distinct on is present if select._distinct or select._distinct_on: if select._distinct_on: return ( "DISTINCT ON (" + ", ".join( [ self.process(col, **kw) for col in select._distinct_on ] ) + ") " ) else: return "DISTINCT " else: return "" def for_update_clause(self, select, **kw): if select._for_update_arg.read: if select._for_update_arg.key_share: tmp = " FOR KEY SHARE" else: tmp = " FOR SHARE" elif select._for_update_arg.key_share: tmp = " FOR NO KEY UPDATE" else: tmp = " FOR UPDATE" if select._for_update_arg.of: tables = util.OrderedSet() for c in select._for_update_arg.of: tables.update(sql_util.surface_selectables_only(c)) of_kw = dict(kw) of_kw.update(ashint=True, use_schema=False) tmp += " OF " + ", ".join( self.process(table, **of_kw) for table in tables ) if select._for_update_arg.nowait: tmp += " NOWAIT" if select._for_update_arg.skip_locked: tmp += " SKIP LOCKED" return tmp def visit_substring_func(self, func, **kw): s = self.process(func.clauses.clauses[0], **kw) start = self.process(func.clauses.clauses[1], **kw) if len(func.clauses.clauses) > 2: length = self.process(func.clauses.clauses[2], **kw) return "SUBSTRING(%s FROM %s FOR %s)" % (s, start, length) else: return "SUBSTRING(%s FROM %s)" % (s, start) def _on_conflict_target(self, clause, **kw): if clause.constraint_target is not None: # target may be a name of an Index, UniqueConstraint or # ExcludeConstraint. While there is a separate # "max_identifier_length" for indexes, PostgreSQL uses the same # length for all objects so we can use # truncate_and_render_constraint_name target_text = ( "ON CONSTRAINT %s" % self.preparer.truncate_and_render_constraint_name( clause.constraint_target ) ) elif clause.inferred_target_elements is not None: target_text = "(%s)" % ", ".join( ( self.preparer.quote(c) if isinstance(c, str) else self.process(c, include_table=False, use_schema=False) ) for c in clause.inferred_target_elements ) if clause.inferred_target_whereclause is not None: target_text += " WHERE %s" % self.process( clause.inferred_target_whereclause, include_table=False, use_schema=False, ) else: target_text = "" return target_text def visit_on_conflict_do_nothing(self, on_conflict, **kw): target_text = self._on_conflict_target(on_conflict, **kw) if target_text: return "ON CONFLICT %s DO NOTHING" % target_text else: return "ON CONFLICT DO NOTHING" def visit_on_conflict_do_update(self, on_conflict, **kw): clause = on_conflict target_text = self._on_conflict_target(on_conflict, **kw) action_set_ops = [] set_parameters = dict(clause.update_values_to_set) # create a list of column assignment clauses as tuples insert_statement = self.stack[-1]["selectable"] cols = insert_statement.table.c for c in cols: col_key = c.key if col_key in set_parameters: value = set_parameters.pop(col_key) elif c in set_parameters: value = set_parameters.pop(c) else: continue # TODO: this coercion should be up front. we can't cache # SQL constructs with non-bound literals buried in them if coercions._is_literal(value): value = elements.BindParameter(None, value, type_=c.type) else: if ( isinstance(value, elements.BindParameter) and value.type._isnull ): value = value._clone() value.type = c.type value_text = self.process(value.self_group(), use_schema=False) key_text = self.preparer.quote(c.name) action_set_ops.append("%s = %s" % (key_text, value_text)) # check for names that don't match columns if set_parameters: util.warn( "Additional column names not matching " "any column keys in table '%s': %s" % ( self.current_executable.table.name, (", ".join("'%s'" % c for c in set_parameters)), ) ) for k, v in set_parameters.items(): key_text = ( self.preparer.quote(k) if isinstance(k, str) else self.process(k, use_schema=False) ) value_text = self.process( coercions.expect(roles.ExpressionElementRole, v), use_schema=False, ) action_set_ops.append("%s = %s" % (key_text, value_text)) action_text = ", ".join(action_set_ops) if clause.update_whereclause is not None: action_text += " WHERE %s" % self.process( clause.update_whereclause, include_table=True, use_schema=False ) return "ON CONFLICT %s DO UPDATE SET %s" % (target_text, action_text) def update_from_clause( self, update_stmt, from_table, extra_froms, from_hints, **kw ): kw["asfrom"] = True return "FROM " + ", ".join( t._compiler_dispatch(self, fromhints=from_hints, **kw) for t in extra_froms ) def delete_extra_from_clause( self, delete_stmt, from_table, extra_froms, from_hints, **kw ): """Render the DELETE .. USING clause specific to PostgreSQL.""" kw["asfrom"] = True return "USING " + ", ".join( t._compiler_dispatch(self, fromhints=from_hints, **kw) for t in extra_froms ) def fetch_clause(self, select, **kw): # pg requires parens for non literal clauses. It's also required for # bind parameters if a ::type casts is used by the driver (asyncpg), # so it's easiest to just always add it text = "" if select._offset_clause is not None: text += "\n OFFSET (%s) ROWS" % self.process( select._offset_clause, **kw ) if select._fetch_clause is not None: text += "\n FETCH FIRST (%s)%s ROWS %s" % ( self.process(select._fetch_clause, **kw), " PERCENT" if select._fetch_clause_options["percent"] else "", ( "WITH TIES" if select._fetch_clause_options["with_ties"] else "ONLY" ), ) return text class PGDDLCompiler(compiler.DDLCompiler): def get_column_specification(self, column, **kwargs): colspec = self.preparer.format_column(column) impl_type = column.type.dialect_impl(self.dialect) if isinstance(impl_type, sqltypes.TypeDecorator): impl_type = impl_type.impl has_identity = ( column.identity is not None and self.dialect.supports_identity_columns ) if ( column.primary_key and column is column.table._autoincrement_column and ( self.dialect.supports_smallserial or not isinstance(impl_type, sqltypes.SmallInteger) ) and not has_identity and ( column.default is None or ( isinstance(column.default, schema.Sequence) and column.default.optional ) ) ): if isinstance(impl_type, sqltypes.BigInteger): colspec += " BIGSERIAL" elif isinstance(impl_type, sqltypes.SmallInteger): colspec += " SMALLSERIAL" else: colspec += " SERIAL" else: colspec += " " + self.dialect.type_compiler_instance.process( column.type, type_expression=column, identifier_preparer=self.preparer, ) default = self.get_column_default_string(column) if default is not None: colspec += " DEFAULT " + default if column.computed is not None: colspec += " " + self.process(column.computed) if has_identity: colspec += " " + self.process(column.identity) if not column.nullable and not has_identity: colspec += " NOT NULL" elif column.nullable and has_identity: colspec += " NULL" return colspec def _define_constraint_validity(self, constraint): not_valid = constraint.dialect_options["postgresql"]["not_valid"] return " NOT VALID" if not_valid else "" def _define_include(self, obj): includeclause = obj.dialect_options["postgresql"]["include"] if not includeclause: return "" inclusions = [ obj.table.c[col] if isinstance(col, str) else col for col in includeclause ] return " INCLUDE (%s)" % ", ".join( [self.preparer.quote(c.name) for c in inclusions] ) def visit_check_constraint(self, constraint, **kw): if constraint._type_bound: typ = list(constraint.columns)[0].type if ( isinstance(typ, sqltypes.ARRAY) and isinstance(typ.item_type, sqltypes.Enum) and not typ.item_type.native_enum ): raise exc.CompileError( "PostgreSQL dialect cannot produce the CHECK constraint " "for ARRAY of non-native ENUM; please specify " "create_constraint=False on this Enum datatype." ) text = super().visit_check_constraint(constraint) text += self._define_constraint_validity(constraint) return text def visit_foreign_key_constraint(self, constraint, **kw): text = super().visit_foreign_key_constraint(constraint) text += self._define_constraint_validity(constraint) return text def visit_primary_key_constraint(self, constraint, **kw): text = super().visit_primary_key_constraint(constraint) text += self._define_include(constraint) return text def visit_unique_constraint(self, constraint, **kw): text = super().visit_unique_constraint(constraint) text += self._define_include(constraint) return text @util.memoized_property def _fk_ondelete_pattern(self): return re.compile( r"^(?:RESTRICT|CASCADE|SET (?:NULL|DEFAULT)(?:\s*\(.+\))?" r"|NO ACTION)$", re.I, ) def define_constraint_ondelete_cascade(self, constraint): return " ON DELETE %s" % self.preparer.validate_sql_phrase( constraint.ondelete, self._fk_ondelete_pattern ) def visit_create_enum_type(self, create, **kw): type_ = create.element return "CREATE TYPE %s AS ENUM (%s)" % ( self.preparer.format_type(type_), ", ".join( self.sql_compiler.process(sql.literal(e), literal_binds=True) for e in type_.enums ), ) def visit_drop_enum_type(self, drop, **kw): type_ = drop.element return "DROP TYPE %s" % (self.preparer.format_type(type_)) def visit_create_domain_type(self, create, **kw): domain: DOMAIN = create.element options = [] if domain.collation is not None: options.append(f"COLLATE {self.preparer.quote(domain.collation)}") if domain.default is not None: default = self.render_default_string(domain.default) options.append(f"DEFAULT {default}") if domain.constraint_name is not None: name = self.preparer.truncate_and_render_constraint_name( domain.constraint_name ) options.append(f"CONSTRAINT {name}") if domain.not_null: options.append("NOT NULL") if domain.check is not None: check = self.sql_compiler.process( domain.check, include_table=False, literal_binds=True ) options.append(f"CHECK ({check})") return ( f"CREATE DOMAIN {self.preparer.format_type(domain)} AS " f"{self.type_compiler.process(domain.data_type)} " f"{' '.join(options)}" ) def visit_drop_domain_type(self, drop, **kw): domain = drop.element return f"DROP DOMAIN {self.preparer.format_type(domain)}" def visit_create_index(self, create, **kw): preparer = self.preparer index = create.element self._verify_index_table(index) text = "CREATE " if index.unique: text += "UNIQUE " text += "INDEX " if self.dialect._supports_create_index_concurrently: concurrently = index.dialect_options["postgresql"]["concurrently"] if concurrently: text += "CONCURRENTLY " if create.if_not_exists: text += "IF NOT EXISTS " text += "%s ON %s " % ( self._prepared_index_name(index, include_schema=False), preparer.format_table(index.table), ) using = index.dialect_options["postgresql"]["using"] if using: text += ( "USING %s " % self.preparer.validate_sql_phrase(using, IDX_USING).lower() ) ops = index.dialect_options["postgresql"]["ops"] text += "(%s)" % ( ", ".join( [ self.sql_compiler.process( ( expr.self_group() if not isinstance(expr, expression.ColumnClause) else expr ), include_table=False, literal_binds=True, ) + ( (" " + ops[expr.key]) if hasattr(expr, "key") and expr.key in ops else "" ) for expr in index.expressions ] ) ) text += self._define_include(index) nulls_not_distinct = index.dialect_options["postgresql"][ "nulls_not_distinct" ] if nulls_not_distinct is True: text += " NULLS NOT DISTINCT" elif nulls_not_distinct is False: text += " NULLS DISTINCT" withclause = index.dialect_options["postgresql"]["with"] if withclause: text += " WITH (%s)" % ( ", ".join( [ "%s = %s" % storage_parameter for storage_parameter in withclause.items() ] ) ) tablespace_name = index.dialect_options["postgresql"]["tablespace"] if tablespace_name: text += " TABLESPACE %s" % preparer.quote(tablespace_name) whereclause = index.dialect_options["postgresql"]["where"] if whereclause is not None: whereclause = coercions.expect( roles.DDLExpressionRole, whereclause ) where_compiled = self.sql_compiler.process( whereclause, include_table=False, literal_binds=True ) text += " WHERE " + where_compiled return text def define_unique_constraint_distinct(self, constraint, **kw): nulls_not_distinct = constraint.dialect_options["postgresql"][ "nulls_not_distinct" ] if nulls_not_distinct is True: nulls_not_distinct_param = "NULLS NOT DISTINCT " elif nulls_not_distinct is False: nulls_not_distinct_param = "NULLS DISTINCT " else: nulls_not_distinct_param = "" return nulls_not_distinct_param def visit_drop_index(self, drop, **kw): index = drop.element text = "\nDROP INDEX " if self.dialect._supports_drop_index_concurrently: concurrently = index.dialect_options["postgresql"]["concurrently"] if concurrently: text += "CONCURRENTLY " if drop.if_exists: text += "IF EXISTS " text += self._prepared_index_name(index, include_schema=True) return text def visit_exclude_constraint(self, constraint, **kw): text = "" if constraint.name is not None: text += "CONSTRAINT %s " % self.preparer.format_constraint( constraint ) elements = [] kw["include_table"] = False kw["literal_binds"] = True for expr, name, op in constraint._render_exprs: exclude_element = self.sql_compiler.process(expr, **kw) + ( (" " + constraint.ops[expr.key]) if hasattr(expr, "key") and expr.key in constraint.ops else "" ) elements.append("%s WITH %s" % (exclude_element, op)) text += "EXCLUDE USING %s (%s)" % ( self.preparer.validate_sql_phrase( constraint.using, IDX_USING ).lower(), ", ".join(elements), ) if constraint.where is not None: text += " WHERE (%s)" % self.sql_compiler.process( constraint.where, literal_binds=True ) text += self.define_constraint_deferrability(constraint) return text def post_create_table(self, table): table_opts = [] pg_opts = table.dialect_options["postgresql"] inherits = pg_opts.get("inherits") if inherits is not None: if not isinstance(inherits, (list, tuple)): inherits = (inherits,) table_opts.append( "\n INHERITS ( " + ", ".join(self.preparer.quote(name) for name in inherits) + " )" ) if pg_opts["partition_by"]: table_opts.append("\n PARTITION BY %s" % pg_opts["partition_by"]) if pg_opts["using"]: table_opts.append("\n USING %s" % pg_opts["using"]) if pg_opts["with_oids"] is True: table_opts.append("\n WITH OIDS") elif pg_opts["with_oids"] is False: table_opts.append("\n WITHOUT OIDS") if pg_opts["on_commit"]: on_commit_options = pg_opts["on_commit"].replace("_", " ").upper() table_opts.append("\n ON COMMIT %s" % on_commit_options) if pg_opts["tablespace"]: tablespace_name = pg_opts["tablespace"] table_opts.append( "\n TABLESPACE %s" % self.preparer.quote(tablespace_name) ) return "".join(table_opts) def visit_computed_column(self, generated, **kw): if generated.persisted is False: raise exc.CompileError( "PostrgreSQL computed columns do not support 'virtual' " "persistence; set the 'persisted' flag to None or True for " "PostgreSQL support." ) return "GENERATED ALWAYS AS (%s) STORED" % self.sql_compiler.process( generated.sqltext, include_table=False, literal_binds=True ) def visit_create_sequence(self, create, **kw): prefix = None if create.element.data_type is not None: prefix = " AS %s" % self.type_compiler.process( create.element.data_type ) return super().visit_create_sequence(create, prefix=prefix, **kw) def _can_comment_on_constraint(self, ddl_instance): constraint = ddl_instance.element if constraint.name is None: raise exc.CompileError( f"Can't emit COMMENT ON for constraint {constraint!r}: " "it has no name" ) if constraint.table is None: raise exc.CompileError( f"Can't emit COMMENT ON for constraint {constraint!r}: " "it has no associated table" ) def visit_set_constraint_comment(self, create, **kw): self._can_comment_on_constraint(create) return "COMMENT ON CONSTRAINT %s ON %s IS %s" % ( self.preparer.format_constraint(create.element), self.preparer.format_table(create.element.table), self.sql_compiler.render_literal_value( create.element.comment, sqltypes.String() ), ) def visit_drop_constraint_comment(self, drop, **kw): self._can_comment_on_constraint(drop) return "COMMENT ON CONSTRAINT %s ON %s IS NULL" % ( self.preparer.format_constraint(drop.element), self.preparer.format_table(drop.element.table), ) class PGTypeCompiler(compiler.GenericTypeCompiler): def visit_TSVECTOR(self, type_, **kw): return "TSVECTOR" def visit_TSQUERY(self, type_, **kw): return "TSQUERY" def visit_INET(self, type_, **kw): return "INET" def visit_CIDR(self, type_, **kw): return "CIDR" def visit_CITEXT(self, type_, **kw): return "CITEXT" def visit_MACADDR(self, type_, **kw): return "MACADDR" def visit_MACADDR8(self, type_, **kw): return "MACADDR8" def visit_MONEY(self, type_, **kw): return "MONEY" def visit_OID(self, type_, **kw): return "OID" def visit_REGCONFIG(self, type_, **kw): return "REGCONFIG" def visit_REGCLASS(self, type_, **kw): return "REGCLASS" def visit_FLOAT(self, type_, **kw): if not type_.precision: return "FLOAT" else: return "FLOAT(%(precision)s)" % {"precision": type_.precision} def visit_double(self, type_, **kw): return self.visit_DOUBLE_PRECISION(type, **kw) def visit_BIGINT(self, type_, **kw): return "BIGINT" def visit_HSTORE(self, type_, **kw): return "HSTORE" def visit_JSON(self, type_, **kw): return "JSON" def visit_JSONB(self, type_, **kw): return "JSONB" def visit_INT4MULTIRANGE(self, type_, **kw): return "INT4MULTIRANGE" def visit_INT8MULTIRANGE(self, type_, **kw): return "INT8MULTIRANGE" def visit_NUMMULTIRANGE(self, type_, **kw): return "NUMMULTIRANGE" def visit_DATEMULTIRANGE(self, type_, **kw): return "DATEMULTIRANGE" def visit_TSMULTIRANGE(self, type_, **kw): return "TSMULTIRANGE" def visit_TSTZMULTIRANGE(self, type_, **kw): return "TSTZMULTIRANGE" def visit_INT4RANGE(self, type_, **kw): return "INT4RANGE" def visit_INT8RANGE(self, type_, **kw): return "INT8RANGE" def visit_NUMRANGE(self, type_, **kw): return "NUMRANGE" def visit_DATERANGE(self, type_, **kw): return "DATERANGE" def visit_TSRANGE(self, type_, **kw): return "TSRANGE" def visit_TSTZRANGE(self, type_, **kw): return "TSTZRANGE" def visit_json_int_index(self, type_, **kw): return "INT" def visit_json_str_index(self, type_, **kw): return "TEXT" def visit_datetime(self, type_, **kw): return self.visit_TIMESTAMP(type_, **kw) def visit_enum(self, type_, **kw): if not type_.native_enum or not self.dialect.supports_native_enum: return super().visit_enum(type_, **kw) else: return self.visit_ENUM(type_, **kw) def visit_ENUM(self, type_, identifier_preparer=None, **kw): if identifier_preparer is None: identifier_preparer = self.dialect.identifier_preparer return identifier_preparer.format_type(type_) def visit_DOMAIN(self, type_, identifier_preparer=None, **kw): if identifier_preparer is None: identifier_preparer = self.dialect.identifier_preparer return identifier_preparer.format_type(type_) def visit_TIMESTAMP(self, type_, **kw): return "TIMESTAMP%s %s" % ( ( "(%d)" % type_.precision if getattr(type_, "precision", None) is not None else "" ), (type_.timezone and "WITH" or "WITHOUT") + " TIME ZONE", ) def visit_TIME(self, type_, **kw): return "TIME%s %s" % ( ( "(%d)" % type_.precision if getattr(type_, "precision", None) is not None else "" ), (type_.timezone and "WITH" or "WITHOUT") + " TIME ZONE", ) def visit_INTERVAL(self, type_, **kw): text = "INTERVAL" if type_.fields is not None: text += " " + type_.fields if type_.precision is not None: text += " (%d)" % type_.precision return text def visit_BIT(self, type_, **kw): if type_.varying: compiled = "BIT VARYING" if type_.length is not None: compiled += "(%d)" % type_.length else: compiled = "BIT(%d)" % type_.length return compiled def visit_uuid(self, type_, **kw): if type_.native_uuid: return self.visit_UUID(type_, **kw) else: return super().visit_uuid(type_, **kw) def visit_UUID(self, type_, **kw): return "UUID" def visit_large_binary(self, type_, **kw): return self.visit_BYTEA(type_, **kw) def visit_BYTEA(self, type_, **kw): return "BYTEA" def visit_ARRAY(self, type_, **kw): inner = self.process(type_.item_type, **kw) return re.sub( r"((?: COLLATE.*)?)$", ( r"%s\1" % ( "[]" * (type_.dimensions if type_.dimensions is not None else 1) ) ), inner, count=1, ) def visit_json_path(self, type_, **kw): return self.visit_JSONPATH(type_, **kw) def visit_JSONPATH(self, type_, **kw): return "JSONPATH" class PGIdentifierPreparer(compiler.IdentifierPreparer): reserved_words = RESERVED_WORDS def _unquote_identifier(self, value): if value[0] == self.initial_quote: value = value[1:-1].replace( self.escape_to_quote, self.escape_quote ) return value def format_type(self, type_, use_schema=True): if not type_.name: raise exc.CompileError( f"PostgreSQL {type_.__class__.__name__} type requires a name." ) name = self.quote(type_.name) effective_schema = self.schema_for_object(type_) if ( not self.omit_schema and use_schema and effective_schema is not None ): name = f"{self.quote_schema(effective_schema)}.{name}" return name class ReflectedNamedType(TypedDict): """Represents a reflected named type.""" name: str """Name of the type.""" schema: str """The schema of the type.""" visible: bool """Indicates if this type is in the current search path.""" class ReflectedDomainConstraint(TypedDict): """Represents a reflect check constraint of a domain.""" name: str """Name of the constraint.""" check: str """The check constraint text.""" class ReflectedDomain(ReflectedNamedType): """Represents a reflected enum.""" type: str """The string name of the underlying data type of the domain.""" nullable: bool """Indicates if the domain allows null or not.""" default: Optional[str] """The string representation of the default value of this domain or ``None`` if none present. """ constraints: List[ReflectedDomainConstraint] """The constraints defined in the domain, if any. The constraint are in order of evaluation by postgresql. """ collation: Optional[str] """The collation for the domain.""" class ReflectedEnum(ReflectedNamedType): """Represents a reflected enum.""" labels: List[str] """The labels that compose the enum.""" class PGInspector(reflection.Inspector): dialect: PGDialect def get_table_oid( self, table_name: str, schema: Optional[str] = None ) -> int: """Return the OID for the given table name. :param table_name: string name of the table. For special quoting, use :class:`.quoted_name`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. """ with self._operation_context() as conn: return self.dialect.get_table_oid( conn, table_name, schema, info_cache=self.info_cache ) def get_domains( self, schema: Optional[str] = None ) -> List[ReflectedDomain]: """Return a list of DOMAIN objects. Each member is a dictionary containing these fields: * name - name of the domain * schema - the schema name for the domain. * visible - boolean, whether or not this domain is visible in the default search path. * type - the type defined by this domain. * nullable - Indicates if this domain can be ``NULL``. * default - The default value of the domain or ``None`` if the domain has no default. * constraints - A list of dict wit the constraint defined by this domain. Each element constaints two keys: ``name`` of the constraint and ``check`` with the constraint text. :param schema: schema name. If None, the default schema (typically 'public') is used. May also be set to ``'*'`` to indicate load domains for all schemas. .. versionadded:: 2.0 """ with self._operation_context() as conn: return self.dialect._load_domains( conn, schema, info_cache=self.info_cache ) def get_enums(self, schema: Optional[str] = None) -> List[ReflectedEnum]: """Return a list of ENUM objects. Each member is a dictionary containing these fields: * name - name of the enum * schema - the schema name for the enum. * visible - boolean, whether or not this enum is visible in the default search path. * labels - a list of string labels that apply to the enum. :param schema: schema name. If None, the default schema (typically 'public') is used. May also be set to ``'*'`` to indicate load enums for all schemas. """ with self._operation_context() as conn: return self.dialect._load_enums( conn, schema, info_cache=self.info_cache ) def get_foreign_table_names( self, schema: Optional[str] = None ) -> List[str]: """Return a list of FOREIGN TABLE names. Behavior is similar to that of :meth:`_reflection.Inspector.get_table_names`, except that the list is limited to those tables that report a ``relkind`` value of ``f``. """ with self._operation_context() as conn: return self.dialect._get_foreign_table_names( conn, schema, info_cache=self.info_cache ) def has_type( self, type_name: str, schema: Optional[str] = None, **kw: Any ) -> bool: """Return if the database has the specified type in the provided schema. :param type_name: the type to check. :param schema: schema name. If None, the default schema (typically 'public') is used. May also be set to ``'*'`` to check in all schemas. .. versionadded:: 2.0 """ with self._operation_context() as conn: return self.dialect.has_type( conn, type_name, schema, info_cache=self.info_cache ) class PGExecutionContext(default.DefaultExecutionContext): def fire_sequence(self, seq, type_): return self._execute_scalar( ( "select nextval('%s')" % self.identifier_preparer.format_sequence(seq) ), type_, ) def get_insert_default(self, column): if column.primary_key and column is column.table._autoincrement_column: if column.server_default and column.server_default.has_argument: # pre-execute passive defaults on primary key columns return self._execute_scalar( "select %s" % column.server_default.arg, column.type ) elif column.default is None or ( column.default.is_sequence and column.default.optional ): # execute the sequence associated with a SERIAL primary # key column. for non-primary-key SERIAL, the ID just # generates server side. try: seq_name = column._postgresql_seq_name except AttributeError: tab = column.table.name col = column.name tab = tab[0 : 29 + max(0, (29 - len(col)))] col = col[0 : 29 + max(0, (29 - len(tab)))] name = "%s_%s_seq" % (tab, col) column._postgresql_seq_name = seq_name = name if column.table is not None: effective_schema = self.connection.schema_for_object( column.table ) else: effective_schema = None if effective_schema is not None: exc = 'select nextval(\'"%s"."%s"\')' % ( effective_schema, seq_name, ) else: exc = "select nextval('\"%s\"')" % (seq_name,) return self._execute_scalar(exc, column.type) return super().get_insert_default(column) class PGReadOnlyConnectionCharacteristic( characteristics.ConnectionCharacteristic ): transactional = True def reset_characteristic(self, dialect, dbapi_conn): dialect.set_readonly(dbapi_conn, False) def set_characteristic(self, dialect, dbapi_conn, value): dialect.set_readonly(dbapi_conn, value) def get_characteristic(self, dialect, dbapi_conn): return dialect.get_readonly(dbapi_conn) class PGDeferrableConnectionCharacteristic( characteristics.ConnectionCharacteristic ): transactional = True def reset_characteristic(self, dialect, dbapi_conn): dialect.set_deferrable(dbapi_conn, False) def set_characteristic(self, dialect, dbapi_conn, value): dialect.set_deferrable(dbapi_conn, value) def get_characteristic(self, dialect, dbapi_conn): return dialect.get_deferrable(dbapi_conn) class PGDialect(default.DefaultDialect): name = "postgresql" supports_statement_cache = True supports_alter = True max_identifier_length = 63 supports_sane_rowcount = True bind_typing = interfaces.BindTyping.RENDER_CASTS supports_native_enum = True supports_native_boolean = True supports_native_uuid = True supports_smallserial = True supports_sequences = True sequences_optional = True preexecute_autoincrement_sequences = True postfetch_lastrowid = False use_insertmanyvalues = True returns_native_bytes = True insertmanyvalues_implicit_sentinel = ( InsertmanyvaluesSentinelOpts.ANY_AUTOINCREMENT | InsertmanyvaluesSentinelOpts.USE_INSERT_FROM_SELECT | InsertmanyvaluesSentinelOpts.RENDER_SELECT_COL_CASTS ) supports_comments = True supports_constraint_comments = True supports_default_values = True supports_default_metavalue = True supports_empty_insert = False supports_multivalues_insert = True supports_identity_columns = True default_paramstyle = "pyformat" ischema_names = ischema_names colspecs = colspecs statement_compiler = PGCompiler ddl_compiler = PGDDLCompiler type_compiler_cls = PGTypeCompiler preparer = PGIdentifierPreparer execution_ctx_cls = PGExecutionContext inspector = PGInspector update_returning = True delete_returning = True insert_returning = True update_returning_multifrom = True delete_returning_multifrom = True connection_characteristics = ( default.DefaultDialect.connection_characteristics ) connection_characteristics = connection_characteristics.union( { "postgresql_readonly": PGReadOnlyConnectionCharacteristic(), "postgresql_deferrable": PGDeferrableConnectionCharacteristic(), } ) construct_arguments = [ ( schema.Index, { "using": False, "include": None, "where": None, "ops": {}, "concurrently": False, "with": {}, "tablespace": None, "nulls_not_distinct": None, }, ), ( schema.Table, { "ignore_search_path": False, "tablespace": None, "partition_by": None, "with_oids": None, "on_commit": None, "inherits": None, "using": None, }, ), ( schema.CheckConstraint, { "not_valid": False, }, ), ( schema.ForeignKeyConstraint, { "not_valid": False, }, ), ( schema.PrimaryKeyConstraint, {"include": None}, ), ( schema.UniqueConstraint, { "include": None, "nulls_not_distinct": None, }, ), ] reflection_options = ("postgresql_ignore_search_path",) _backslash_escapes = True _supports_create_index_concurrently = True _supports_drop_index_concurrently = True def __init__( self, native_inet_types=None, json_serializer=None, json_deserializer=None, **kwargs, ): default.DefaultDialect.__init__(self, **kwargs) self._native_inet_types = native_inet_types self._json_deserializer = json_deserializer self._json_serializer = json_serializer def initialize(self, connection): super().initialize(connection) # https://www.postgresql.org/docs/9.3/static/release-9-2.html#AEN116689 self.supports_smallserial = self.server_version_info >= (9, 2) self._set_backslash_escapes(connection) self._supports_drop_index_concurrently = self.server_version_info >= ( 9, 2, ) self.supports_identity_columns = self.server_version_info >= (10,) def get_isolation_level_values(self, dbapi_conn): # note the generic dialect doesn't have AUTOCOMMIT, however # all postgresql dialects should include AUTOCOMMIT. return ( "SERIALIZABLE", "READ UNCOMMITTED", "READ COMMITTED", "REPEATABLE READ", ) def set_isolation_level(self, dbapi_connection, level): cursor = dbapi_connection.cursor() cursor.execute( "SET SESSION CHARACTERISTICS AS TRANSACTION " f"ISOLATION LEVEL {level}" ) cursor.execute("COMMIT") cursor.close() def get_isolation_level(self, dbapi_connection): cursor = dbapi_connection.cursor() cursor.execute("show transaction isolation level") val = cursor.fetchone()[0] cursor.close() return val.upper() def set_readonly(self, connection, value): raise NotImplementedError() def get_readonly(self, connection): raise NotImplementedError() def set_deferrable(self, connection, value): raise NotImplementedError() def get_deferrable(self, connection): raise NotImplementedError() def _split_multihost_from_url(self, url: URL) -> Union[ Tuple[None, None], Tuple[Tuple[Optional[str], ...], Tuple[Optional[int], ...]], ]: hosts: Optional[Tuple[Optional[str], ...]] = None ports_str: Union[str, Tuple[Optional[str], ...], None] = None integrated_multihost = False if "host" in url.query: if isinstance(url.query["host"], (list, tuple)): integrated_multihost = True hosts, ports_str = zip( *[ token.split(":") if ":" in token else (token, None) for token in url.query["host"] ] ) elif isinstance(url.query["host"], str): hosts = tuple(url.query["host"].split(",")) if ( "port" not in url.query and len(hosts) == 1 and ":" in hosts[0] ): # internet host is alphanumeric plus dots or hyphens. # this is essentially rfc1123, which refers to rfc952. # https://stackoverflow.com/questions/3523028/ # valid-characters-of-a-hostname host_port_match = re.match( r"^([a-zA-Z0-9\-\.]*)(?:\:(\d*))?$", hosts[0] ) if host_port_match: integrated_multihost = True h, p = host_port_match.group(1, 2) if TYPE_CHECKING: assert isinstance(h, str) assert isinstance(p, str) hosts = (h,) ports_str = cast( "Tuple[Optional[str], ...]", (p,) if p else (None,) ) if "port" in url.query: if integrated_multihost: raise exc.ArgumentError( "Can't mix 'multihost' formats together; use " '"host=h1,h2,h3&port=p1,p2,p3" or ' '"host=h1:p1&host=h2:p2&host=h3:p3" separately' ) if isinstance(url.query["port"], (list, tuple)): ports_str = url.query["port"] elif isinstance(url.query["port"], str): ports_str = tuple(url.query["port"].split(",")) ports: Optional[Tuple[Optional[int], ...]] = None if ports_str: try: ports = tuple(int(x) if x else None for x in ports_str) except ValueError: raise exc.ArgumentError( f"Received non-integer port arguments: {ports_str}" ) from None if ports and ( (not hosts and len(ports) > 1) or ( hosts and ports and len(hosts) != len(ports) and (len(hosts) > 1 or len(ports) > 1) ) ): raise exc.ArgumentError("number of hosts and ports don't match") if hosts is not None: if ports is None: ports = tuple(None for _ in hosts) return hosts, ports # type: ignore def do_begin_twophase(self, connection, xid): self.do_begin(connection.connection) def do_prepare_twophase(self, connection, xid): connection.exec_driver_sql("PREPARE TRANSACTION '%s'" % xid) def do_rollback_twophase( self, connection, xid, is_prepared=True, recover=False ): if is_prepared: if recover: # FIXME: ugly hack to get out of transaction # context when committing recoverable transactions # Must find out a way how to make the dbapi not # open a transaction. connection.exec_driver_sql("ROLLBACK") connection.exec_driver_sql("ROLLBACK PREPARED '%s'" % xid) connection.exec_driver_sql("BEGIN") self.do_rollback(connection.connection) else: self.do_rollback(connection.connection) def do_commit_twophase( self, connection, xid, is_prepared=True, recover=False ): if is_prepared: if recover: connection.exec_driver_sql("ROLLBACK") connection.exec_driver_sql("COMMIT PREPARED '%s'" % xid) connection.exec_driver_sql("BEGIN") self.do_rollback(connection.connection) else: self.do_commit(connection.connection) def do_recover_twophase(self, connection): return connection.scalars( sql.text("SELECT gid FROM pg_prepared_xacts") ).all() def _get_default_schema_name(self, connection): return connection.exec_driver_sql("select current_schema()").scalar() @reflection.cache def has_schema(self, connection, schema, **kw): query = select(pg_catalog.pg_namespace.c.nspname).where( pg_catalog.pg_namespace.c.nspname == schema ) return bool(connection.scalar(query)) def _pg_class_filter_scope_schema( self, query, schema, scope, pg_class_table=None ): if pg_class_table is None: pg_class_table = pg_catalog.pg_class query = query.join( pg_catalog.pg_namespace, pg_catalog.pg_namespace.c.oid == pg_class_table.c.relnamespace, ) if scope is ObjectScope.DEFAULT: query = query.where(pg_class_table.c.relpersistence != "t") elif scope is ObjectScope.TEMPORARY: query = query.where(pg_class_table.c.relpersistence == "t") if schema is None: query = query.where( pg_catalog.pg_table_is_visible(pg_class_table.c.oid), # ignore pg_catalog schema pg_catalog.pg_namespace.c.nspname != "pg_catalog", ) else: query = query.where(pg_catalog.pg_namespace.c.nspname == schema) return query def _pg_class_relkind_condition(self, relkinds, pg_class_table=None): if pg_class_table is None: pg_class_table = pg_catalog.pg_class # uses the any form instead of in otherwise postgresql complaings # that 'IN could not convert type character to "char"' return pg_class_table.c.relkind == sql.any_(_array.array(relkinds)) @lru_cache() def _has_table_query(self, schema): query = select(pg_catalog.pg_class.c.relname).where( pg_catalog.pg_class.c.relname == bindparam("table_name"), self._pg_class_relkind_condition( pg_catalog.RELKINDS_ALL_TABLE_LIKE ), ) return self._pg_class_filter_scope_schema( query, schema, scope=ObjectScope.ANY ) @reflection.cache def has_table(self, connection, table_name, schema=None, **kw): self._ensure_has_table_connection(connection) query = self._has_table_query(schema) return bool(connection.scalar(query, {"table_name": table_name})) @reflection.cache def has_sequence(self, connection, sequence_name, schema=None, **kw): query = select(pg_catalog.pg_class.c.relname).where( pg_catalog.pg_class.c.relkind == "S", pg_catalog.pg_class.c.relname == sequence_name, ) query = self._pg_class_filter_scope_schema( query, schema, scope=ObjectScope.ANY ) return bool(connection.scalar(query)) @reflection.cache def has_type(self, connection, type_name, schema=None, **kw): query = ( select(pg_catalog.pg_type.c.typname) .join( pg_catalog.pg_namespace, pg_catalog.pg_namespace.c.oid == pg_catalog.pg_type.c.typnamespace, ) .where(pg_catalog.pg_type.c.typname == type_name) ) if schema is None: query = query.where( pg_catalog.pg_type_is_visible(pg_catalog.pg_type.c.oid), # ignore pg_catalog schema pg_catalog.pg_namespace.c.nspname != "pg_catalog", ) elif schema != "*": query = query.where(pg_catalog.pg_namespace.c.nspname == schema) return bool(connection.scalar(query)) def _get_server_version_info(self, connection): v = connection.exec_driver_sql("select pg_catalog.version()").scalar() m = re.match( r".*(?:PostgreSQL|EnterpriseDB) " r"(\d+)\.?(\d+)?(?:\.(\d+))?(?:\.\d+)?(?:devel|beta)?", v, ) if not m: raise AssertionError( "Could not determine version from string '%s'" % v ) return tuple([int(x) for x in m.group(1, 2, 3) if x is not None]) @reflection.cache def get_table_oid(self, connection, table_name, schema=None, **kw): """Fetch the oid for schema.table_name.""" query = select(pg_catalog.pg_class.c.oid).where( pg_catalog.pg_class.c.relname == table_name, self._pg_class_relkind_condition( pg_catalog.RELKINDS_ALL_TABLE_LIKE ), ) query = self._pg_class_filter_scope_schema( query, schema, scope=ObjectScope.ANY ) table_oid = connection.scalar(query) if table_oid is None: raise exc.NoSuchTableError( f"{schema}.{table_name}" if schema else table_name ) return table_oid @reflection.cache def get_schema_names(self, connection, **kw): query = ( select(pg_catalog.pg_namespace.c.nspname) .where(pg_catalog.pg_namespace.c.nspname.not_like("pg_%")) .order_by(pg_catalog.pg_namespace.c.nspname) ) return connection.scalars(query).all() def _get_relnames_for_relkinds(self, connection, schema, relkinds, scope): query = select(pg_catalog.pg_class.c.relname).where( self._pg_class_relkind_condition(relkinds) ) query = self._pg_class_filter_scope_schema(query, schema, scope=scope) return connection.scalars(query).all() @reflection.cache def get_table_names(self, connection, schema=None, **kw): return self._get_relnames_for_relkinds( connection, schema, pg_catalog.RELKINDS_TABLE_NO_FOREIGN, scope=ObjectScope.DEFAULT, ) @reflection.cache def get_temp_table_names(self, connection, **kw): return self._get_relnames_for_relkinds( connection, schema=None, relkinds=pg_catalog.RELKINDS_TABLE_NO_FOREIGN, scope=ObjectScope.TEMPORARY, ) @reflection.cache def _get_foreign_table_names(self, connection, schema=None, **kw): return self._get_relnames_for_relkinds( connection, schema, relkinds=("f",), scope=ObjectScope.ANY ) @reflection.cache def get_view_names(self, connection, schema=None, **kw): return self._get_relnames_for_relkinds( connection, schema, pg_catalog.RELKINDS_VIEW, scope=ObjectScope.DEFAULT, ) @reflection.cache def get_materialized_view_names(self, connection, schema=None, **kw): return self._get_relnames_for_relkinds( connection, schema, pg_catalog.RELKINDS_MAT_VIEW, scope=ObjectScope.DEFAULT, ) @reflection.cache def get_temp_view_names(self, connection, schema=None, **kw): return self._get_relnames_for_relkinds( connection, schema, # NOTE: do not include temp materialzied views (that do not # seem to be a thing at least up to version 14) pg_catalog.RELKINDS_VIEW, scope=ObjectScope.TEMPORARY, ) @reflection.cache def get_sequence_names(self, connection, schema=None, **kw): return self._get_relnames_for_relkinds( connection, schema, relkinds=("S",), scope=ObjectScope.ANY ) @reflection.cache def get_view_definition(self, connection, view_name, schema=None, **kw): query = ( select(pg_catalog.pg_get_viewdef(pg_catalog.pg_class.c.oid)) .select_from(pg_catalog.pg_class) .where( pg_catalog.pg_class.c.relname == view_name, self._pg_class_relkind_condition( pg_catalog.RELKINDS_VIEW + pg_catalog.RELKINDS_MAT_VIEW ), ) ) query = self._pg_class_filter_scope_schema( query, schema, scope=ObjectScope.ANY ) res = connection.scalar(query) if res is None: raise exc.NoSuchTableError( f"{schema}.{view_name}" if schema else view_name ) else: return res def _value_or_raise(self, data, table, schema): try: return dict(data)[(schema, table)] except KeyError: raise exc.NoSuchTableError( f"{schema}.{table}" if schema else table ) from None def _prepare_filter_names(self, filter_names): if filter_names: return True, {"filter_names": filter_names} else: return False, {} def _kind_to_relkinds(self, kind: ObjectKind) -> Tuple[str, ...]: if kind is ObjectKind.ANY: return pg_catalog.RELKINDS_ALL_TABLE_LIKE relkinds = () if ObjectKind.TABLE in kind: relkinds += pg_catalog.RELKINDS_TABLE if ObjectKind.VIEW in kind: relkinds += pg_catalog.RELKINDS_VIEW if ObjectKind.MATERIALIZED_VIEW in kind: relkinds += pg_catalog.RELKINDS_MAT_VIEW return relkinds @reflection.cache def get_columns(self, connection, table_name, schema=None, **kw): data = self.get_multi_columns( connection, schema=schema, filter_names=[table_name], scope=ObjectScope.ANY, kind=ObjectKind.ANY, **kw, ) return self._value_or_raise(data, table_name, schema) @lru_cache() def _columns_query(self, schema, has_filter_names, scope, kind): # NOTE: the query with the default and identity options scalar # subquery is faster than trying to use outer joins for them generated = ( pg_catalog.pg_attribute.c.attgenerated.label("generated") if self.server_version_info >= (12,) else sql.null().label("generated") ) if self.server_version_info >= (10,): # join lateral performs worse (~2x slower) than a scalar_subquery identity = ( select( sql.func.json_build_object( "always", pg_catalog.pg_attribute.c.attidentity == "a", "start", pg_catalog.pg_sequence.c.seqstart, "increment", pg_catalog.pg_sequence.c.seqincrement, "minvalue", pg_catalog.pg_sequence.c.seqmin, "maxvalue", pg_catalog.pg_sequence.c.seqmax, "cache", pg_catalog.pg_sequence.c.seqcache, "cycle", pg_catalog.pg_sequence.c.seqcycle, type_=sqltypes.JSON(), ) ) .select_from(pg_catalog.pg_sequence) .where( # attidentity != '' is required or it will reflect also # serial columns as identity. pg_catalog.pg_attribute.c.attidentity != "", pg_catalog.pg_sequence.c.seqrelid == sql.cast( sql.cast( pg_catalog.pg_get_serial_sequence( sql.cast( sql.cast( pg_catalog.pg_attribute.c.attrelid, REGCLASS, ), TEXT, ), pg_catalog.pg_attribute.c.attname, ), REGCLASS, ), OID, ), ) .correlate(pg_catalog.pg_attribute) .scalar_subquery() .label("identity_options") ) else: identity = sql.null().label("identity_options") # join lateral performs the same as scalar_subquery here default = ( select( pg_catalog.pg_get_expr( pg_catalog.pg_attrdef.c.adbin, pg_catalog.pg_attrdef.c.adrelid, ) ) .select_from(pg_catalog.pg_attrdef) .where( pg_catalog.pg_attrdef.c.adrelid == pg_catalog.pg_attribute.c.attrelid, pg_catalog.pg_attrdef.c.adnum == pg_catalog.pg_attribute.c.attnum, pg_catalog.pg_attribute.c.atthasdef, ) .correlate(pg_catalog.pg_attribute) .scalar_subquery() .label("default") ) relkinds = self._kind_to_relkinds(kind) query = ( select( pg_catalog.pg_attribute.c.attname.label("name"), pg_catalog.format_type( pg_catalog.pg_attribute.c.atttypid, pg_catalog.pg_attribute.c.atttypmod, ).label("format_type"), default, pg_catalog.pg_attribute.c.attnotnull.label("not_null"), pg_catalog.pg_class.c.relname.label("table_name"), pg_catalog.pg_description.c.description.label("comment"), generated, identity, ) .select_from(pg_catalog.pg_class) # NOTE: postgresql support table with no user column, meaning # there is no row with pg_attribute.attnum > 0. use a left outer # join to avoid filtering these tables. .outerjoin( pg_catalog.pg_attribute, sql.and_( pg_catalog.pg_class.c.oid == pg_catalog.pg_attribute.c.attrelid, pg_catalog.pg_attribute.c.attnum > 0, ~pg_catalog.pg_attribute.c.attisdropped, ), ) .outerjoin( pg_catalog.pg_description, sql.and_( pg_catalog.pg_description.c.objoid == pg_catalog.pg_attribute.c.attrelid, pg_catalog.pg_description.c.objsubid == pg_catalog.pg_attribute.c.attnum, ), ) .where(self._pg_class_relkind_condition(relkinds)) .order_by( pg_catalog.pg_class.c.relname, pg_catalog.pg_attribute.c.attnum ) ) query = self._pg_class_filter_scope_schema(query, schema, scope=scope) if has_filter_names: query = query.where( pg_catalog.pg_class.c.relname.in_(bindparam("filter_names")) ) return query def get_multi_columns( self, connection, schema, filter_names, scope, kind, **kw ): has_filter_names, params = self._prepare_filter_names(filter_names) query = self._columns_query(schema, has_filter_names, scope, kind) rows = connection.execute(query, params).mappings() # dictionary with (name, ) if default search path or (schema, name) # as keys domains = { ((d["schema"], d["name"]) if not d["visible"] else (d["name"],)): d for d in self._load_domains( connection, schema="*", info_cache=kw.get("info_cache") ) } # dictionary with (name, ) if default search path or (schema, name) # as keys enums = dict( ( ((rec["name"],), rec) if rec["visible"] else ((rec["schema"], rec["name"]), rec) ) for rec in self._load_enums( connection, schema="*", info_cache=kw.get("info_cache") ) ) columns = self._get_columns_info(rows, domains, enums, schema) return columns.items() _format_type_args_pattern = re.compile(r"\((.*)\)") _format_type_args_delim = re.compile(r"\s*,\s*") _format_array_spec_pattern = re.compile(r"((?:\[\])*)$") def _reflect_type( self, format_type: Optional[str], domains: Dict[str, ReflectedDomain], enums: Dict[str, ReflectedEnum], type_description: str, ) -> sqltypes.TypeEngine[Any]: """ Attempts to reconstruct a column type defined in ischema_names based on the information available in the format_type. If the `format_type` cannot be associated with a known `ischema_names`, it is treated as a reference to a known PostgreSQL named `ENUM` or `DOMAIN` type. """ type_description = type_description or "unknown type" if format_type is None: util.warn( "PostgreSQL format_type() returned NULL for %s" % type_description ) return sqltypes.NULLTYPE attype_args_match = self._format_type_args_pattern.search(format_type) if attype_args_match and attype_args_match.group(1): attype_args = self._format_type_args_delim.split( attype_args_match.group(1) ) else: attype_args = () match_array_dim = self._format_array_spec_pattern.search(format_type) # Each "[]" in array specs corresponds to an array dimension array_dim = len(match_array_dim.group(1) or "") // 2 # Remove all parameters and array specs from format_type to obtain an # ischema_name candidate attype = self._format_type_args_pattern.sub("", format_type) attype = self._format_array_spec_pattern.sub("", attype) schema_type = self.ischema_names.get(attype.lower(), None) args, kwargs = (), {} if attype == "numeric": if len(attype_args) == 2: precision, scale = map(int, attype_args) args = (precision, scale) elif attype == "double precision": args = (53,) elif attype == "integer": args = () elif attype in ("timestamp with time zone", "time with time zone"): kwargs["timezone"] = True if len(attype_args) == 1: kwargs["precision"] = int(attype_args[0]) elif attype in ( "timestamp without time zone", "time without time zone", "time", ): kwargs["timezone"] = False if len(attype_args) == 1: kwargs["precision"] = int(attype_args[0]) elif attype == "bit varying": kwargs["varying"] = True if len(attype_args) == 1: charlen = int(attype_args[0]) args = (charlen,) elif attype.startswith("interval"): schema_type = INTERVAL field_match = re.match(r"interval (.+)", attype) if field_match: kwargs["fields"] = field_match.group(1) if len(attype_args) == 1: kwargs["precision"] = int(attype_args[0]) else: enum_or_domain_key = tuple(util.quoted_token_parser(attype)) if enum_or_domain_key in enums: schema_type = ENUM enum = enums[enum_or_domain_key] kwargs["name"] = enum["name"] if not enum["visible"]: kwargs["schema"] = enum["schema"] args = tuple(enum["labels"]) elif enum_or_domain_key in domains: schema_type = DOMAIN domain = domains[enum_or_domain_key] data_type = self._reflect_type( domain["type"], domains, enums, type_description="DOMAIN '%s'" % domain["name"], ) args = (domain["name"], data_type) kwargs["collation"] = domain["collation"] kwargs["default"] = domain["default"] kwargs["not_null"] = not domain["nullable"] kwargs["create_type"] = False if domain["constraints"]: # We only support a single constraint check_constraint = domain["constraints"][0] kwargs["constraint_name"] = check_constraint["name"] kwargs["check"] = check_constraint["check"] if not domain["visible"]: kwargs["schema"] = domain["schema"] else: try: charlen = int(attype_args[0]) args = (charlen, *attype_args[1:]) except (ValueError, IndexError): args = attype_args if not schema_type: util.warn( "Did not recognize type '%s' of %s" % (attype, type_description) ) return sqltypes.NULLTYPE data_type = schema_type(*args, **kwargs) if array_dim >= 1: # postgres does not preserve dimensionality or size of array types. data_type = _array.ARRAY(data_type) return data_type def _get_columns_info(self, rows, domains, enums, schema): columns = defaultdict(list) for row_dict in rows: # ensure that each table has an entry, even if it has no columns if row_dict["name"] is None: columns[(schema, row_dict["table_name"])] = ( ReflectionDefaults.columns() ) continue table_cols = columns[(schema, row_dict["table_name"])] coltype = self._reflect_type( row_dict["format_type"], domains, enums, type_description="column '%s'" % row_dict["name"], ) default = row_dict["default"] name = row_dict["name"] generated = row_dict["generated"] nullable = not row_dict["not_null"] if isinstance(coltype, DOMAIN): if not default: # domain can override the default value but # cant set it to None if coltype.default is not None: default = coltype.default nullable = nullable and not coltype.not_null identity = row_dict["identity_options"] # If a zero byte or blank string depending on driver (is also # absent for older PG versions), then not a generated column. # Otherwise, s = stored. (Other values might be added in the # future.) if generated not in (None, "", b"\x00"): computed = dict( sqltext=default, persisted=generated in ("s", b"s") ) default = None else: computed = None # adjust the default value autoincrement = False if default is not None: match = re.search(r"""(nextval\(')([^']+)('.*$)""", default) if match is not None: if issubclass(coltype._type_affinity, sqltypes.Integer): autoincrement = True # the default is related to a Sequence if "." not in match.group(2) and schema is not None: # unconditionally quote the schema name. this could # later be enhanced to obey quoting rules / # "quote schema" default = ( match.group(1) + ('"%s"' % schema) + "." + match.group(2) + match.group(3) ) column_info = { "name": name, "type": coltype, "nullable": nullable, "default": default, "autoincrement": autoincrement or identity is not None, "comment": row_dict["comment"], } if computed is not None: column_info["computed"] = computed if identity is not None: column_info["identity"] = identity table_cols.append(column_info) return columns @lru_cache() def _table_oids_query(self, schema, has_filter_names, scope, kind): relkinds = self._kind_to_relkinds(kind) oid_q = select( pg_catalog.pg_class.c.oid, pg_catalog.pg_class.c.relname ).where(self._pg_class_relkind_condition(relkinds)) oid_q = self._pg_class_filter_scope_schema(oid_q, schema, scope=scope) if has_filter_names: oid_q = oid_q.where( pg_catalog.pg_class.c.relname.in_(bindparam("filter_names")) ) return oid_q @reflection.flexi_cache( ("schema", InternalTraversal.dp_string), ("filter_names", InternalTraversal.dp_string_list), ("kind", InternalTraversal.dp_plain_obj), ("scope", InternalTraversal.dp_plain_obj), ) def _get_table_oids( self, connection, schema, filter_names, scope, kind, **kw ): has_filter_names, params = self._prepare_filter_names(filter_names) oid_q = self._table_oids_query(schema, has_filter_names, scope, kind) result = connection.execute(oid_q, params) return result.all() @util.memoized_property def _constraint_query(self): if self.server_version_info >= (11, 0): indnkeyatts = pg_catalog.pg_index.c.indnkeyatts else: indnkeyatts = sql.null().label("indnkeyatts") if self.server_version_info >= (15,): indnullsnotdistinct = pg_catalog.pg_index.c.indnullsnotdistinct else: indnullsnotdistinct = sql.false().label("indnullsnotdistinct") con_sq = ( select( pg_catalog.pg_constraint.c.conrelid, pg_catalog.pg_constraint.c.conname, sql.func.unnest(pg_catalog.pg_index.c.indkey).label("attnum"), sql.func.generate_subscripts( pg_catalog.pg_index.c.indkey, 1 ).label("ord"), indnkeyatts, indnullsnotdistinct, pg_catalog.pg_description.c.description, ) .join( pg_catalog.pg_index, pg_catalog.pg_constraint.c.conindid == pg_catalog.pg_index.c.indexrelid, ) .outerjoin( pg_catalog.pg_description, pg_catalog.pg_description.c.objoid == pg_catalog.pg_constraint.c.oid, ) .where( pg_catalog.pg_constraint.c.contype == bindparam("contype"), pg_catalog.pg_constraint.c.conrelid.in_(bindparam("oids")), # NOTE: filtering also on pg_index.indrelid for oids does # not seem to have a performance effect, but it may be an # option if perf problems are reported ) .subquery("con") ) attr_sq = ( select( con_sq.c.conrelid, con_sq.c.conname, con_sq.c.description, con_sq.c.ord, con_sq.c.indnkeyatts, con_sq.c.indnullsnotdistinct, pg_catalog.pg_attribute.c.attname, ) .select_from(pg_catalog.pg_attribute) .join( con_sq, sql.and_( pg_catalog.pg_attribute.c.attnum == con_sq.c.attnum, pg_catalog.pg_attribute.c.attrelid == con_sq.c.conrelid, ), ) .where( # NOTE: restate the condition here, since pg15 otherwise # seems to get confused on pscopg2 sometimes, doing # a sequential scan of pg_attribute. # The condition in the con_sq subquery is not actually needed # in pg15, but it may be needed in older versions. Keeping it # does not seems to have any inpact in any case. con_sq.c.conrelid.in_(bindparam("oids")) ) .subquery("attr") ) return ( select( attr_sq.c.conrelid, sql.func.array_agg( # NOTE: cast since some postgresql derivatives may # not support array_agg on the name type aggregate_order_by( attr_sq.c.attname.cast(TEXT), attr_sq.c.ord ) ).label("cols"), attr_sq.c.conname, sql.func.min(attr_sq.c.description).label("description"), sql.func.min(attr_sq.c.indnkeyatts).label("indnkeyatts"), sql.func.bool_and(attr_sq.c.indnullsnotdistinct).label( "indnullsnotdistinct" ), ) .group_by(attr_sq.c.conrelid, attr_sq.c.conname) .order_by(attr_sq.c.conrelid, attr_sq.c.conname) ) def _reflect_constraint( self, connection, contype, schema, filter_names, scope, kind, **kw ): # used to reflect primary and unique constraint table_oids = self._get_table_oids( connection, schema, filter_names, scope, kind, **kw ) batches = list(table_oids) is_unique = contype == "u" while batches: batch = batches[0:3000] batches[0:3000] = [] result = connection.execute( self._constraint_query, {"oids": [r[0] for r in batch], "contype": contype}, ).mappings() result_by_oid = defaultdict(list) for row_dict in result: result_by_oid[row_dict["conrelid"]].append(row_dict) for oid, tablename in batch: for_oid = result_by_oid.get(oid, ()) if for_oid: for row in for_oid: # See note in get_multi_indexes all_cols = row["cols"] indnkeyatts = row["indnkeyatts"] if ( indnkeyatts is not None and len(all_cols) > indnkeyatts ): inc_cols = all_cols[indnkeyatts:] cst_cols = all_cols[:indnkeyatts] else: inc_cols = [] cst_cols = all_cols opts = {} if self.server_version_info >= (11,): opts["postgresql_include"] = inc_cols if is_unique: opts["postgresql_nulls_not_distinct"] = row[ "indnullsnotdistinct" ] yield ( tablename, cst_cols, row["conname"], row["description"], opts, ) else: yield tablename, None, None, None, None @reflection.cache def get_pk_constraint(self, connection, table_name, schema=None, **kw): data = self.get_multi_pk_constraint( connection, schema=schema, filter_names=[table_name], scope=ObjectScope.ANY, kind=ObjectKind.ANY, **kw, ) return self._value_or_raise(data, table_name, schema) def get_multi_pk_constraint( self, connection, schema, filter_names, scope, kind, **kw ): result = self._reflect_constraint( connection, "p", schema, filter_names, scope, kind, **kw ) # only a single pk can be present for each table. Return an entry # even if a table has no primary key default = ReflectionDefaults.pk_constraint def pk_constraint(pk_name, cols, comment, opts): info = { "constrained_columns": cols, "name": pk_name, "comment": comment, } if opts: info["dialect_options"] = opts return info return ( ( (schema, table_name), ( pk_constraint(pk_name, cols, comment, opts) if pk_name is not None else default() ), ) for table_name, cols, pk_name, comment, opts in result ) @reflection.cache def get_foreign_keys( self, connection, table_name, schema=None, postgresql_ignore_search_path=False, **kw, ): data = self.get_multi_foreign_keys( connection, schema=schema, filter_names=[table_name], postgresql_ignore_search_path=postgresql_ignore_search_path, scope=ObjectScope.ANY, kind=ObjectKind.ANY, **kw, ) return self._value_or_raise(data, table_name, schema) @lru_cache() def _foreing_key_query(self, schema, has_filter_names, scope, kind): pg_class_ref = pg_catalog.pg_class.alias("cls_ref") pg_namespace_ref = pg_catalog.pg_namespace.alias("nsp_ref") relkinds = self._kind_to_relkinds(kind) query = ( select( pg_catalog.pg_class.c.relname, pg_catalog.pg_constraint.c.conname, # NOTE: avoid calling pg_get_constraintdef when not needed # to speed up the query sql.case( ( pg_catalog.pg_constraint.c.oid.is_not(None), pg_catalog.pg_get_constraintdef( pg_catalog.pg_constraint.c.oid, True ), ), else_=None, ), pg_namespace_ref.c.nspname, pg_catalog.pg_description.c.description, ) .select_from(pg_catalog.pg_class) .outerjoin( pg_catalog.pg_constraint, sql.and_( pg_catalog.pg_class.c.oid == pg_catalog.pg_constraint.c.conrelid, pg_catalog.pg_constraint.c.contype == "f", ), ) .outerjoin( pg_class_ref, pg_class_ref.c.oid == pg_catalog.pg_constraint.c.confrelid, ) .outerjoin( pg_namespace_ref, pg_class_ref.c.relnamespace == pg_namespace_ref.c.oid, ) .outerjoin( pg_catalog.pg_description, pg_catalog.pg_description.c.objoid == pg_catalog.pg_constraint.c.oid, ) .order_by( pg_catalog.pg_class.c.relname, pg_catalog.pg_constraint.c.conname, ) .where(self._pg_class_relkind_condition(relkinds)) ) query = self._pg_class_filter_scope_schema(query, schema, scope) if has_filter_names: query = query.where( pg_catalog.pg_class.c.relname.in_(bindparam("filter_names")) ) return query @util.memoized_property def _fk_regex_pattern(self): # optionally quoted token qtoken = '(?:"[^"]+"|[A-Za-z0-9_]+?)' # https://www.postgresql.org/docs/current/static/sql-createtable.html return re.compile( r"FOREIGN KEY \((.*?)\) " rf"REFERENCES (?:({qtoken})\.)?({qtoken})\(((?:{qtoken}(?: *, *)?)+)\)" # noqa: E501 r"[\s]?(MATCH (FULL|PARTIAL|SIMPLE)+)?" r"[\s]?(ON UPDATE " r"(CASCADE|RESTRICT|NO ACTION|SET NULL|SET DEFAULT)+)?" r"[\s]?(ON DELETE " r"(CASCADE|RESTRICT|NO ACTION|" r"SET (?:NULL|DEFAULT)(?:\s\(.+\))?)+)?" r"[\s]?(DEFERRABLE|NOT DEFERRABLE)?" r"[\s]?(INITIALLY (DEFERRED|IMMEDIATE)+)?" ) def get_multi_foreign_keys( self, connection, schema, filter_names, scope, kind, postgresql_ignore_search_path=False, **kw, ): preparer = self.identifier_preparer has_filter_names, params = self._prepare_filter_names(filter_names) query = self._foreing_key_query(schema, has_filter_names, scope, kind) result = connection.execute(query, params) FK_REGEX = self._fk_regex_pattern fkeys = defaultdict(list) default = ReflectionDefaults.foreign_keys for table_name, conname, condef, conschema, comment in result: # ensure that each table has an entry, even if it has # no foreign keys if conname is None: fkeys[(schema, table_name)] = default() continue table_fks = fkeys[(schema, table_name)] m = re.search(FK_REGEX, condef).groups() ( constrained_columns, referred_schema, referred_table, referred_columns, _, match, _, onupdate, _, ondelete, deferrable, _, initially, ) = m if deferrable is not None: deferrable = True if deferrable == "DEFERRABLE" else False constrained_columns = [ preparer._unquote_identifier(x) for x in re.split(r"\s*,\s*", constrained_columns) ] if postgresql_ignore_search_path: # when ignoring search path, we use the actual schema # provided it isn't the "default" schema if conschema != self.default_schema_name: referred_schema = conschema else: referred_schema = schema elif referred_schema: # referred_schema is the schema that we regexp'ed from # pg_get_constraintdef(). If the schema is in the search # path, pg_get_constraintdef() will give us None. referred_schema = preparer._unquote_identifier(referred_schema) elif schema is not None and schema == conschema: # If the actual schema matches the schema of the table # we're reflecting, then we will use that. referred_schema = schema referred_table = preparer._unquote_identifier(referred_table) referred_columns = [ preparer._unquote_identifier(x) for x in re.split(r"\s*,\s", referred_columns) ] options = { k: v for k, v in [ ("onupdate", onupdate), ("ondelete", ondelete), ("initially", initially), ("deferrable", deferrable), ("match", match), ] if v is not None and v != "NO ACTION" } fkey_d = { "name": conname, "constrained_columns": constrained_columns, "referred_schema": referred_schema, "referred_table": referred_table, "referred_columns": referred_columns, "options": options, "comment": comment, } table_fks.append(fkey_d) return fkeys.items() @reflection.cache def get_indexes(self, connection, table_name, schema=None, **kw): data = self.get_multi_indexes( connection, schema=schema, filter_names=[table_name], scope=ObjectScope.ANY, kind=ObjectKind.ANY, **kw, ) return self._value_or_raise(data, table_name, schema) @util.memoized_property def _index_query(self): # NOTE: pg_index is used as from two times to improve performance, # since extraing all the index information from `idx_sq` to avoid # the second pg_index use leads to a worse performing query in # particular when querying for a single table (as of pg 17) # NOTE: repeating oids clause improve query performance # subquery to get the columns idx_sq = ( select( pg_catalog.pg_index.c.indexrelid, pg_catalog.pg_index.c.indrelid, sql.func.unnest(pg_catalog.pg_index.c.indkey).label("attnum"), sql.func.generate_subscripts( pg_catalog.pg_index.c.indkey, 1 ).label("ord"), ) .where( ~pg_catalog.pg_index.c.indisprimary, pg_catalog.pg_index.c.indrelid.in_(bindparam("oids")), ) .subquery("idx") ) attr_sq = ( select( idx_sq.c.indexrelid, idx_sq.c.indrelid, idx_sq.c.ord, # NOTE: always using pg_get_indexdef is too slow so just # invoke when the element is an expression sql.case( ( idx_sq.c.attnum == 0, pg_catalog.pg_get_indexdef( idx_sq.c.indexrelid, idx_sq.c.ord + 1, True ), ), # NOTE: need to cast this since attname is of type "name" # that's limited to 63 bytes, while pg_get_indexdef # returns "text" so its output may get cut else_=pg_catalog.pg_attribute.c.attname.cast(TEXT), ).label("element"), (idx_sq.c.attnum == 0).label("is_expr"), ) .select_from(idx_sq) .outerjoin( # do not remove rows where idx_sq.c.attnum is 0 pg_catalog.pg_attribute, sql.and_( pg_catalog.pg_attribute.c.attnum == idx_sq.c.attnum, pg_catalog.pg_attribute.c.attrelid == idx_sq.c.indrelid, ), ) .where(idx_sq.c.indrelid.in_(bindparam("oids"))) .subquery("idx_attr") ) cols_sq = ( select( attr_sq.c.indexrelid, sql.func.min(attr_sq.c.indrelid), sql.func.array_agg( aggregate_order_by(attr_sq.c.element, attr_sq.c.ord) ).label("elements"), sql.func.array_agg( aggregate_order_by(attr_sq.c.is_expr, attr_sq.c.ord) ).label("elements_is_expr"), ) .group_by(attr_sq.c.indexrelid) .subquery("idx_cols") ) if self.server_version_info >= (11, 0): indnkeyatts = pg_catalog.pg_index.c.indnkeyatts else: indnkeyatts = sql.null().label("indnkeyatts") if self.server_version_info >= (15,): nulls_not_distinct = pg_catalog.pg_index.c.indnullsnotdistinct else: nulls_not_distinct = sql.false().label("indnullsnotdistinct") return ( select( pg_catalog.pg_index.c.indrelid, pg_catalog.pg_class.c.relname, pg_catalog.pg_index.c.indisunique, pg_catalog.pg_constraint.c.conrelid.is_not(None).label( "has_constraint" ), pg_catalog.pg_index.c.indoption, pg_catalog.pg_class.c.reloptions, pg_catalog.pg_am.c.amname, # NOTE: pg_get_expr is very fast so this case has almost no # performance impact sql.case( ( pg_catalog.pg_index.c.indpred.is_not(None), pg_catalog.pg_get_expr( pg_catalog.pg_index.c.indpred, pg_catalog.pg_index.c.indrelid, ), ), else_=None, ).label("filter_definition"), indnkeyatts, nulls_not_distinct, cols_sq.c.elements, cols_sq.c.elements_is_expr, ) .select_from(pg_catalog.pg_index) .where( pg_catalog.pg_index.c.indrelid.in_(bindparam("oids")), ~pg_catalog.pg_index.c.indisprimary, ) .join( pg_catalog.pg_class, pg_catalog.pg_index.c.indexrelid == pg_catalog.pg_class.c.oid, ) .join( pg_catalog.pg_am, pg_catalog.pg_class.c.relam == pg_catalog.pg_am.c.oid, ) .outerjoin( cols_sq, pg_catalog.pg_index.c.indexrelid == cols_sq.c.indexrelid, ) .outerjoin( pg_catalog.pg_constraint, sql.and_( pg_catalog.pg_index.c.indrelid == pg_catalog.pg_constraint.c.conrelid, pg_catalog.pg_index.c.indexrelid == pg_catalog.pg_constraint.c.conindid, pg_catalog.pg_constraint.c.contype == sql.any_(_array.array(("p", "u", "x"))), ), ) .order_by( pg_catalog.pg_index.c.indrelid, pg_catalog.pg_class.c.relname ) ) def get_multi_indexes( self, connection, schema, filter_names, scope, kind, **kw ): table_oids = self._get_table_oids( connection, schema, filter_names, scope, kind, **kw ) indexes = defaultdict(list) default = ReflectionDefaults.indexes batches = list(table_oids) while batches: batch = batches[0:3000] batches[0:3000] = [] result = connection.execute( self._index_query, {"oids": [r[0] for r in batch]} ).mappings() result_by_oid = defaultdict(list) for row_dict in result: result_by_oid[row_dict["indrelid"]].append(row_dict) for oid, table_name in batch: if oid not in result_by_oid: # ensure that each table has an entry, even if reflection # is skipped because not supported indexes[(schema, table_name)] = default() continue for row in result_by_oid[oid]: index_name = row["relname"] table_indexes = indexes[(schema, table_name)] all_elements = row["elements"] all_elements_is_expr = row["elements_is_expr"] indnkeyatts = row["indnkeyatts"] # "The number of key columns in the index, not counting any # included columns, which are merely stored and do not # participate in the index semantics" if ( indnkeyatts is not None and len(all_elements) > indnkeyatts ): # this is a "covering index" which has INCLUDE columns # as well as regular index columns inc_cols = all_elements[indnkeyatts:] idx_elements = all_elements[:indnkeyatts] idx_elements_is_expr = all_elements_is_expr[ :indnkeyatts ] # postgresql does not support expression on included # columns as of v14: "ERROR: expressions are not # supported in included columns". assert all( not is_expr for is_expr in all_elements_is_expr[indnkeyatts:] ) else: idx_elements = all_elements idx_elements_is_expr = all_elements_is_expr inc_cols = [] index = {"name": index_name, "unique": row["indisunique"]} if any(idx_elements_is_expr): index["column_names"] = [ None if is_expr else expr for expr, is_expr in zip( idx_elements, idx_elements_is_expr ) ] index["expressions"] = idx_elements else: index["column_names"] = idx_elements sorting = {} for col_index, col_flags in enumerate(row["indoption"]): col_sorting = () # try to set flags only if they differ from PG # defaults... if col_flags & 0x01: col_sorting += ("desc",) if not (col_flags & 0x02): col_sorting += ("nulls_last",) else: if col_flags & 0x02: col_sorting += ("nulls_first",) if col_sorting: sorting[idx_elements[col_index]] = col_sorting if sorting: index["column_sorting"] = sorting if row["has_constraint"]: index["duplicates_constraint"] = index_name dialect_options = {} if row["reloptions"]: dialect_options["postgresql_with"] = dict( [ option.split("=", 1) for option in row["reloptions"] ] ) # it *might* be nice to include that this is 'btree' in the # reflection info. But we don't want an Index object # to have a ``postgresql_using`` in it that is just the # default, so for the moment leaving this out. amname = row["amname"] if amname != "btree": dialect_options["postgresql_using"] = row["amname"] if row["filter_definition"]: dialect_options["postgresql_where"] = row[ "filter_definition" ] if self.server_version_info >= (11,): # NOTE: this is legacy, this is part of # dialect_options now as of #7382 index["include_columns"] = inc_cols dialect_options["postgresql_include"] = inc_cols if row["indnullsnotdistinct"]: # the default is False, so ignore it. dialect_options["postgresql_nulls_not_distinct"] = row[ "indnullsnotdistinct" ] if dialect_options: index["dialect_options"] = dialect_options table_indexes.append(index) return indexes.items() @reflection.cache def get_unique_constraints( self, connection, table_name, schema=None, **kw ): data = self.get_multi_unique_constraints( connection, schema=schema, filter_names=[table_name], scope=ObjectScope.ANY, kind=ObjectKind.ANY, **kw, ) return self._value_or_raise(data, table_name, schema) def get_multi_unique_constraints( self, connection, schema, filter_names, scope, kind, **kw, ): result = self._reflect_constraint( connection, "u", schema, filter_names, scope, kind, **kw ) # each table can have multiple unique constraints uniques = defaultdict(list) default = ReflectionDefaults.unique_constraints for table_name, cols, con_name, comment, options in result: # ensure a list is created for each table. leave it empty if # the table has no unique cosntraint if con_name is None: uniques[(schema, table_name)] = default() continue uc_dict = { "column_names": cols, "name": con_name, "comment": comment, } if options: uc_dict["dialect_options"] = options uniques[(schema, table_name)].append(uc_dict) return uniques.items() @reflection.cache def get_table_comment(self, connection, table_name, schema=None, **kw): data = self.get_multi_table_comment( connection, schema, [table_name], scope=ObjectScope.ANY, kind=ObjectKind.ANY, **kw, ) return self._value_or_raise(data, table_name, schema) @lru_cache() def _comment_query(self, schema, has_filter_names, scope, kind): relkinds = self._kind_to_relkinds(kind) query = ( select( pg_catalog.pg_class.c.relname, pg_catalog.pg_description.c.description, ) .select_from(pg_catalog.pg_class) .outerjoin( pg_catalog.pg_description, sql.and_( pg_catalog.pg_class.c.oid == pg_catalog.pg_description.c.objoid, pg_catalog.pg_description.c.objsubid == 0, pg_catalog.pg_description.c.classoid == sql.func.cast("pg_catalog.pg_class", REGCLASS), ), ) .where(self._pg_class_relkind_condition(relkinds)) ) query = self._pg_class_filter_scope_schema(query, schema, scope) if has_filter_names: query = query.where( pg_catalog.pg_class.c.relname.in_(bindparam("filter_names")) ) return query def get_multi_table_comment( self, connection, schema, filter_names, scope, kind, **kw ): has_filter_names, params = self._prepare_filter_names(filter_names) query = self._comment_query(schema, has_filter_names, scope, kind) result = connection.execute(query, params) default = ReflectionDefaults.table_comment return ( ( (schema, table), {"text": comment} if comment is not None else default(), ) for table, comment in result ) @reflection.cache def get_check_constraints(self, connection, table_name, schema=None, **kw): data = self.get_multi_check_constraints( connection, schema, [table_name], scope=ObjectScope.ANY, kind=ObjectKind.ANY, **kw, ) return self._value_or_raise(data, table_name, schema) @lru_cache() def _check_constraint_query(self, schema, has_filter_names, scope, kind): relkinds = self._kind_to_relkinds(kind) query = ( select( pg_catalog.pg_class.c.relname, pg_catalog.pg_constraint.c.conname, # NOTE: avoid calling pg_get_constraintdef when not needed # to speed up the query sql.case( ( pg_catalog.pg_constraint.c.oid.is_not(None), pg_catalog.pg_get_constraintdef( pg_catalog.pg_constraint.c.oid, True ), ), else_=None, ), pg_catalog.pg_description.c.description, ) .select_from(pg_catalog.pg_class) .outerjoin( pg_catalog.pg_constraint, sql.and_( pg_catalog.pg_class.c.oid == pg_catalog.pg_constraint.c.conrelid, pg_catalog.pg_constraint.c.contype == "c", ), ) .outerjoin( pg_catalog.pg_description, pg_catalog.pg_description.c.objoid == pg_catalog.pg_constraint.c.oid, ) .order_by( pg_catalog.pg_class.c.relname, pg_catalog.pg_constraint.c.conname, ) .where(self._pg_class_relkind_condition(relkinds)) ) query = self._pg_class_filter_scope_schema(query, schema, scope) if has_filter_names: query = query.where( pg_catalog.pg_class.c.relname.in_(bindparam("filter_names")) ) return query def get_multi_check_constraints( self, connection, schema, filter_names, scope, kind, **kw ): has_filter_names, params = self._prepare_filter_names(filter_names) query = self._check_constraint_query( schema, has_filter_names, scope, kind ) result = connection.execute(query, params) check_constraints = defaultdict(list) default = ReflectionDefaults.check_constraints for table_name, check_name, src, comment in result: # only two cases for check_name and src: both null or both defined if check_name is None and src is None: check_constraints[(schema, table_name)] = default() continue # samples: # "CHECK (((a > 1) AND (a < 5)))" # "CHECK (((a = 1) OR ((a > 2) AND (a < 5))))" # "CHECK (((a > 1) AND (a < 5))) NOT VALID" # "CHECK (some_boolean_function(a))" # "CHECK (((a\n < 1)\n OR\n (a\n >= 5))\n)" # "CHECK (a NOT NULL) NO INHERIT" # "CHECK (a NOT NULL) NO INHERIT NOT VALID" m = re.match( r"^CHECK *\((.+)\)( NO INHERIT)?( NOT VALID)?$", src, flags=re.DOTALL, ) if not m: util.warn("Could not parse CHECK constraint text: %r" % src) sqltext = "" else: sqltext = re.compile( r"^[\s\n]*\((.+)\)[\s\n]*$", flags=re.DOTALL ).sub(r"\1", m.group(1)) entry = { "name": check_name, "sqltext": sqltext, "comment": comment, } if m: do = {} if " NOT VALID" in m.groups(): do["not_valid"] = True if " NO INHERIT" in m.groups(): do["no_inherit"] = True if do: entry["dialect_options"] = do check_constraints[(schema, table_name)].append(entry) return check_constraints.items() def _pg_type_filter_schema(self, query, schema): if schema is None: query = query.where( pg_catalog.pg_type_is_visible(pg_catalog.pg_type.c.oid), # ignore pg_catalog schema pg_catalog.pg_namespace.c.nspname != "pg_catalog", ) elif schema != "*": query = query.where(pg_catalog.pg_namespace.c.nspname == schema) return query @lru_cache() def _enum_query(self, schema): lbl_agg_sq = ( select( pg_catalog.pg_enum.c.enumtypid, sql.func.array_agg( aggregate_order_by( # NOTE: cast since some postgresql derivatives may # not support array_agg on the name type pg_catalog.pg_enum.c.enumlabel.cast(TEXT), pg_catalog.pg_enum.c.enumsortorder, ) ).label("labels"), ) .group_by(pg_catalog.pg_enum.c.enumtypid) .subquery("lbl_agg") ) query = ( select( pg_catalog.pg_type.c.typname.label("name"), pg_catalog.pg_type_is_visible(pg_catalog.pg_type.c.oid).label( "visible" ), pg_catalog.pg_namespace.c.nspname.label("schema"), lbl_agg_sq.c.labels.label("labels"), ) .join( pg_catalog.pg_namespace, pg_catalog.pg_namespace.c.oid == pg_catalog.pg_type.c.typnamespace, ) .outerjoin( lbl_agg_sq, pg_catalog.pg_type.c.oid == lbl_agg_sq.c.enumtypid ) .where(pg_catalog.pg_type.c.typtype == "e") .order_by( pg_catalog.pg_namespace.c.nspname, pg_catalog.pg_type.c.typname ) ) return self._pg_type_filter_schema(query, schema) @reflection.cache def _load_enums(self, connection, schema=None, **kw): if not self.supports_native_enum: return [] result = connection.execute(self._enum_query(schema)) enums = [] for name, visible, schema, labels in result: enums.append( { "name": name, "schema": schema, "visible": visible, "labels": [] if labels is None else labels, } ) return enums @lru_cache() def _domain_query(self, schema): con_sq = ( select( pg_catalog.pg_constraint.c.contypid, sql.func.array_agg( pg_catalog.pg_get_constraintdef( pg_catalog.pg_constraint.c.oid, True ) ).label("condefs"), sql.func.array_agg( # NOTE: cast since some postgresql derivatives may # not support array_agg on the name type pg_catalog.pg_constraint.c.conname.cast(TEXT) ).label("connames"), ) # The domain this constraint is on; zero if not a domain constraint .where(pg_catalog.pg_constraint.c.contypid != 0) .group_by(pg_catalog.pg_constraint.c.contypid) .subquery("domain_constraints") ) query = ( select( pg_catalog.pg_type.c.typname.label("name"), pg_catalog.format_type( pg_catalog.pg_type.c.typbasetype, pg_catalog.pg_type.c.typtypmod, ).label("attype"), (~pg_catalog.pg_type.c.typnotnull).label("nullable"), pg_catalog.pg_type.c.typdefault.label("default"), pg_catalog.pg_type_is_visible(pg_catalog.pg_type.c.oid).label( "visible" ), pg_catalog.pg_namespace.c.nspname.label("schema"), con_sq.c.condefs, con_sq.c.connames, pg_catalog.pg_collation.c.collname, ) .join( pg_catalog.pg_namespace, pg_catalog.pg_namespace.c.oid == pg_catalog.pg_type.c.typnamespace, ) .outerjoin( pg_catalog.pg_collation, pg_catalog.pg_type.c.typcollation == pg_catalog.pg_collation.c.oid, ) .outerjoin( con_sq, pg_catalog.pg_type.c.oid == con_sq.c.contypid, ) .where(pg_catalog.pg_type.c.typtype == "d") .order_by( pg_catalog.pg_namespace.c.nspname, pg_catalog.pg_type.c.typname ) ) return self._pg_type_filter_schema(query, schema) @reflection.cache def _load_domains(self, connection, schema=None, **kw): result = connection.execute(self._domain_query(schema)) domains: List[ReflectedDomain] = [] for domain in result.mappings(): # strip (30) from character varying(30) attype = re.search(r"([^\(]+)", domain["attype"]).group(1) constraints: List[ReflectedDomainConstraint] = [] if domain["connames"]: # When a domain has multiple CHECK constraints, they will # be tested in alphabetical order by name. sorted_constraints = sorted( zip(domain["connames"], domain["condefs"]), key=lambda t: t[0], ) for name, def_ in sorted_constraints: # constraint is in the form "CHECK (expression)" # or "NOT NULL". Ignore the "NOT NULL" and # remove "CHECK (" and the tailing ")". if def_.casefold().startswith("check"): check = def_[7:-1] constraints.append({"name": name, "check": check}) domain_rec: ReflectedDomain = { "name": domain["name"], "schema": domain["schema"], "visible": domain["visible"], "type": attype, "nullable": domain["nullable"], "default": domain["default"], "constraints": constraints, "collation": domain["collname"], } domains.append(domain_rec) return domains def _set_backslash_escapes(self, connection): # this method is provided as an override hook for descendant # dialects (e.g. Redshift), so removing it may break them std_string = connection.exec_driver_sql( "show standard_conforming_strings" ).scalar() self._backslash_escapes = std_string == "off" sqlalchemy/dialects/postgresql/psycopg2cffi.py 0000755 00000003334 15125143220 0015652 0 ustar 00 # dialects/postgresql/psycopg2cffi.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors r""" .. dialect:: postgresql+psycopg2cffi :name: psycopg2cffi :dbapi: psycopg2cffi :connectstring: postgresql+psycopg2cffi://user:password@host:port/dbname[?key=value&key=value...] :url: https://pypi.org/project/psycopg2cffi/ ``psycopg2cffi`` is an adaptation of ``psycopg2``, using CFFI for the C layer. This makes it suitable for use in e.g. PyPy. Documentation is as per ``psycopg2``. .. seealso:: :mod:`sqlalchemy.dialects.postgresql.psycopg2` """ # noqa from .psycopg2 import PGDialect_psycopg2 from ... import util class PGDialect_psycopg2cffi(PGDialect_psycopg2): driver = "psycopg2cffi" supports_unicode_statements = True supports_statement_cache = True # psycopg2cffi's first release is 2.5.0, but reports # __version__ as 2.4.4. Subsequent releases seem to have # fixed this. FEATURE_VERSION_MAP = dict( native_json=(2, 4, 4), native_jsonb=(2, 7, 1), sane_multi_rowcount=(2, 4, 4), array_oid=(2, 4, 4), hstore_adapter=(2, 4, 4), ) @classmethod def import_dbapi(cls): return __import__("psycopg2cffi") @util.memoized_property def _psycopg2_extensions(cls): root = __import__("psycopg2cffi", fromlist=["extensions"]) return root.extensions @util.memoized_property def _psycopg2_extras(cls): root = __import__("psycopg2cffi", fromlist=["extras"]) return root.extras dialect = PGDialect_psycopg2cffi sqlalchemy/dialects/postgresql/json.py 0000755 00000031052 15125143220 0014223 0 ustar 00 # dialects/postgresql/json.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php from __future__ import annotations from typing import Any from typing import Callable from typing import List from typing import Optional from typing import TYPE_CHECKING from typing import Union from .array import ARRAY from .array import array as _pg_array from .operators import ASTEXT from .operators import CONTAINED_BY from .operators import CONTAINS from .operators import DELETE_PATH from .operators import HAS_ALL from .operators import HAS_ANY from .operators import HAS_KEY from .operators import JSONPATH_ASTEXT from .operators import PATH_EXISTS from .operators import PATH_MATCH from ... import types as sqltypes from ...sql import cast from ...sql._typing import _T if TYPE_CHECKING: from ...engine.interfaces import Dialect from ...sql.elements import ColumnElement from ...sql.type_api import _BindProcessorType from ...sql.type_api import _LiteralProcessorType from ...sql.type_api import TypeEngine __all__ = ("JSON", "JSONB") class JSONPathType(sqltypes.JSON.JSONPathType): def _processor( self, dialect: Dialect, super_proc: Optional[Callable[[Any], Any]] ) -> Callable[[Any], Any]: def process(value: Any) -> Any: if isinstance(value, str): # If it's already a string assume that it's in json path # format. This allows using cast with json paths literals return value elif value: # If it's already a string assume that it's in json path # format. This allows using cast with json paths literals value = "{%s}" % (", ".join(map(str, value))) else: value = "{}" if super_proc: value = super_proc(value) return value return process def bind_processor(self, dialect: Dialect) -> _BindProcessorType[Any]: return self._processor(dialect, self.string_bind_processor(dialect)) # type: ignore[return-value] # noqa: E501 def literal_processor( self, dialect: Dialect ) -> _LiteralProcessorType[Any]: return self._processor(dialect, self.string_literal_processor(dialect)) # type: ignore[return-value] # noqa: E501 class JSONPATH(JSONPathType): """JSON Path Type. This is usually required to cast literal values to json path when using json search like function, such as ``jsonb_path_query_array`` or ``jsonb_path_exists``:: stmt = sa.select( sa.func.jsonb_path_query_array( table.c.jsonb_col, cast("$.address.id", JSONPATH) ) ) """ __visit_name__ = "JSONPATH" class JSON(sqltypes.JSON): """Represent the PostgreSQL JSON type. :class:`_postgresql.JSON` is used automatically whenever the base :class:`_types.JSON` datatype is used against a PostgreSQL backend, however base :class:`_types.JSON` datatype does not provide Python accessors for PostgreSQL-specific comparison methods such as :meth:`_postgresql.JSON.Comparator.astext`; additionally, to use PostgreSQL ``JSONB``, the :class:`_postgresql.JSONB` datatype should be used explicitly. .. seealso:: :class:`_types.JSON` - main documentation for the generic cross-platform JSON datatype. The operators provided by the PostgreSQL version of :class:`_types.JSON` include: * Index operations (the ``->`` operator):: data_table.c.data["some key"] data_table.c.data[5] * Index operations returning text (the ``->>`` operator):: data_table.c.data["some key"].astext == "some value" Note that equivalent functionality is available via the :attr:`.JSON.Comparator.as_string` accessor. * Index operations with CAST (equivalent to ``CAST(col ->> ['some key'] AS <type>)``):: data_table.c.data["some key"].astext.cast(Integer) == 5 Note that equivalent functionality is available via the :attr:`.JSON.Comparator.as_integer` and similar accessors. * Path index operations (the ``#>`` operator):: data_table.c.data[("key_1", "key_2", 5, ..., "key_n")] * Path index operations returning text (the ``#>>`` operator):: data_table.c.data[ ("key_1", "key_2", 5, ..., "key_n") ].astext == "some value" Index operations return an expression object whose type defaults to :class:`_types.JSON` by default, so that further JSON-oriented instructions may be called upon the result type. Custom serializers and deserializers are specified at the dialect level, that is using :func:`_sa.create_engine`. The reason for this is that when using psycopg2, the DBAPI only allows serializers at the per-cursor or per-connection level. E.g.:: engine = create_engine( "postgresql+psycopg2://scott:tiger@localhost/test", json_serializer=my_serialize_fn, json_deserializer=my_deserialize_fn, ) When using the psycopg2 dialect, the json_deserializer is registered against the database using ``psycopg2.extras.register_default_json``. .. seealso:: :class:`_types.JSON` - Core level JSON type :class:`_postgresql.JSONB` """ # noqa render_bind_cast = True astext_type: TypeEngine[str] = sqltypes.Text() def __init__( self, none_as_null: bool = False, astext_type: Optional[TypeEngine[str]] = None, ): """Construct a :class:`_types.JSON` type. :param none_as_null: if True, persist the value ``None`` as a SQL NULL value, not the JSON encoding of ``null``. Note that when this flag is False, the :func:`.null` construct can still be used to persist a NULL value:: from sqlalchemy import null conn.execute(table.insert(), {"data": null()}) .. seealso:: :attr:`_types.JSON.NULL` :param astext_type: the type to use for the :attr:`.JSON.Comparator.astext` accessor on indexed attributes. Defaults to :class:`_types.Text`. """ super().__init__(none_as_null=none_as_null) if astext_type is not None: self.astext_type = astext_type class Comparator(sqltypes.JSON.Comparator[_T]): """Define comparison operations for :class:`_types.JSON`.""" type: JSON @property def astext(self) -> ColumnElement[str]: """On an indexed expression, use the "astext" (e.g. "->>") conversion when rendered in SQL. E.g.:: select(data_table.c.data["some key"].astext) .. seealso:: :meth:`_expression.ColumnElement.cast` """ if isinstance(self.expr.right.type, sqltypes.JSON.JSONPathType): return self.expr.left.operate( # type: ignore[no-any-return] JSONPATH_ASTEXT, self.expr.right, result_type=self.type.astext_type, ) else: return self.expr.left.operate( # type: ignore[no-any-return] ASTEXT, self.expr.right, result_type=self.type.astext_type ) comparator_factory = Comparator class JSONB(JSON): """Represent the PostgreSQL JSONB type. The :class:`_postgresql.JSONB` type stores arbitrary JSONB format data, e.g.:: data_table = Table( "data_table", metadata, Column("id", Integer, primary_key=True), Column("data", JSONB), ) with engine.connect() as conn: conn.execute( data_table.insert(), data={"key1": "value1", "key2": "value2"} ) The :class:`_postgresql.JSONB` type includes all operations provided by :class:`_types.JSON`, including the same behaviors for indexing operations. It also adds additional operators specific to JSONB, including :meth:`.JSONB.Comparator.has_key`, :meth:`.JSONB.Comparator.has_all`, :meth:`.JSONB.Comparator.has_any`, :meth:`.JSONB.Comparator.contains`, :meth:`.JSONB.Comparator.contained_by`, :meth:`.JSONB.Comparator.delete_path`, :meth:`.JSONB.Comparator.path_exists` and :meth:`.JSONB.Comparator.path_match`. Like the :class:`_types.JSON` type, the :class:`_postgresql.JSONB` type does not detect in-place changes when used with the ORM, unless the :mod:`sqlalchemy.ext.mutable` extension is used. Custom serializers and deserializers are shared with the :class:`_types.JSON` class, using the ``json_serializer`` and ``json_deserializer`` keyword arguments. These must be specified at the dialect level using :func:`_sa.create_engine`. When using psycopg2, the serializers are associated with the jsonb type using ``psycopg2.extras.register_default_jsonb`` on a per-connection basis, in the same way that ``psycopg2.extras.register_default_json`` is used to register these handlers with the json type. .. seealso:: :class:`_types.JSON` """ __visit_name__ = "JSONB" class Comparator(JSON.Comparator[_T]): """Define comparison operations for :class:`_types.JSON`.""" type: JSONB def has_key(self, other: Any) -> ColumnElement[bool]: """Boolean expression. Test for presence of a key (equivalent of the ``?`` operator). Note that the key may be a SQLA expression. """ return self.operate(HAS_KEY, other, result_type=sqltypes.Boolean) def has_all(self, other: Any) -> ColumnElement[bool]: """Boolean expression. Test for presence of all keys in jsonb (equivalent of the ``?&`` operator) """ return self.operate(HAS_ALL, other, result_type=sqltypes.Boolean) def has_any(self, other: Any) -> ColumnElement[bool]: """Boolean expression. Test for presence of any key in jsonb (equivalent of the ``?|`` operator) """ return self.operate(HAS_ANY, other, result_type=sqltypes.Boolean) def contains(self, other: Any, **kwargs: Any) -> ColumnElement[bool]: """Boolean expression. Test if keys (or array) are a superset of/contained the keys of the argument jsonb expression (equivalent of the ``@>`` operator). kwargs may be ignored by this operator but are required for API conformance. """ return self.operate(CONTAINS, other, result_type=sqltypes.Boolean) def contained_by(self, other: Any) -> ColumnElement[bool]: """Boolean expression. Test if keys are a proper subset of the keys of the argument jsonb expression (equivalent of the ``<@`` operator). """ return self.operate( CONTAINED_BY, other, result_type=sqltypes.Boolean ) def delete_path( self, array: Union[List[str], _pg_array[str]] ) -> ColumnElement[JSONB]: """JSONB expression. Deletes field or array element specified in the argument array (equivalent of the ``#-`` operator). The input may be a list of strings that will be coerced to an ``ARRAY`` or an instance of :meth:`_postgres.array`. .. versionadded:: 2.0 """ if not isinstance(array, _pg_array): array = _pg_array(array) right_side = cast(array, ARRAY(sqltypes.TEXT)) return self.operate(DELETE_PATH, right_side, result_type=JSONB) def path_exists(self, other: Any) -> ColumnElement[bool]: """Boolean expression. Test for presence of item given by the argument JSONPath expression (equivalent of the ``@?`` operator). .. versionadded:: 2.0 """ return self.operate( PATH_EXISTS, other, result_type=sqltypes.Boolean ) def path_match(self, other: Any) -> ColumnElement[bool]: """Boolean expression. Test if JSONPath predicate given by the argument JSONPath expression matches (equivalent of the ``@@`` operator). Only the first item of the result is taken into account. .. versionadded:: 2.0 """ return self.operate( PATH_MATCH, other, result_type=sqltypes.Boolean ) comparator_factory = Comparator sqlalchemy/dialects/postgresql/operators.py 0000755 00000005370 15125143220 0015274 0 ustar 00 # dialects/postgresql/operators.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors from ...sql import operators _getitem_precedence = operators._PRECEDENCE[operators.json_getitem_op] _eq_precedence = operators._PRECEDENCE[operators.eq] # JSON + JSONB ASTEXT = operators.custom_op( "->>", precedence=_getitem_precedence, natural_self_precedent=True, eager_grouping=True, ) JSONPATH_ASTEXT = operators.custom_op( "#>>", precedence=_getitem_precedence, natural_self_precedent=True, eager_grouping=True, ) # JSONB + HSTORE HAS_KEY = operators.custom_op( "?", precedence=_eq_precedence, natural_self_precedent=True, eager_grouping=True, is_comparison=True, ) HAS_ALL = operators.custom_op( "?&", precedence=_eq_precedence, natural_self_precedent=True, eager_grouping=True, is_comparison=True, ) HAS_ANY = operators.custom_op( "?|", precedence=_eq_precedence, natural_self_precedent=True, eager_grouping=True, is_comparison=True, ) # JSONB DELETE_PATH = operators.custom_op( "#-", precedence=_getitem_precedence, natural_self_precedent=True, eager_grouping=True, ) PATH_EXISTS = operators.custom_op( "@?", precedence=_eq_precedence, natural_self_precedent=True, eager_grouping=True, is_comparison=True, ) PATH_MATCH = operators.custom_op( "@@", precedence=_eq_precedence, natural_self_precedent=True, eager_grouping=True, is_comparison=True, ) # JSONB + ARRAY + HSTORE + RANGE CONTAINS = operators.custom_op( "@>", precedence=_eq_precedence, natural_self_precedent=True, eager_grouping=True, is_comparison=True, ) CONTAINED_BY = operators.custom_op( "<@", precedence=_eq_precedence, natural_self_precedent=True, eager_grouping=True, is_comparison=True, ) # ARRAY + RANGE OVERLAP = operators.custom_op( "&&", precedence=_eq_precedence, is_comparison=True, ) # RANGE STRICTLY_LEFT_OF = operators.custom_op( "<<", precedence=_eq_precedence, is_comparison=True ) STRICTLY_RIGHT_OF = operators.custom_op( ">>", precedence=_eq_precedence, is_comparison=True ) NOT_EXTEND_RIGHT_OF = operators.custom_op( "&<", precedence=_eq_precedence, is_comparison=True ) NOT_EXTEND_LEFT_OF = operators.custom_op( "&>", precedence=_eq_precedence, is_comparison=True ) ADJACENT_TO = operators.custom_op( "-|-", precedence=_eq_precedence, is_comparison=True ) # HSTORE GETITEM = operators.custom_op( "->", precedence=_getitem_precedence, natural_self_precedent=True, eager_grouping=True, ) sqlalchemy/dialects/postgresql/provision.py 0000755 00000013212 15125143220 0015300 0 ustar 00 # dialects/postgresql/provision.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors import time from ... import exc from ... import inspect from ... import text from ...testing import warn_test_suite from ...testing.provision import create_db from ...testing.provision import drop_all_schema_objects_post_tables from ...testing.provision import drop_all_schema_objects_pre_tables from ...testing.provision import drop_db from ...testing.provision import log from ...testing.provision import post_configure_engine from ...testing.provision import prepare_for_drop_tables from ...testing.provision import set_default_schema_on_connection from ...testing.provision import temp_table_keyword_args from ...testing.provision import upsert @create_db.for_db("postgresql") def _pg_create_db(cfg, eng, ident): template_db = cfg.options.postgresql_templatedb with eng.execution_options(isolation_level="AUTOCOMMIT").begin() as conn: if not template_db: template_db = conn.exec_driver_sql( "select current_database()" ).scalar() attempt = 0 while True: try: conn.exec_driver_sql( "CREATE DATABASE %s TEMPLATE %s" % (ident, template_db) ) except exc.OperationalError as err: attempt += 1 if attempt >= 3: raise if "accessed by other users" in str(err): log.info( "Waiting to create %s, URI %r, " "template DB %s is in use sleeping for .5", ident, eng.url, template_db, ) time.sleep(0.5) except: raise else: break @drop_db.for_db("postgresql") def _pg_drop_db(cfg, eng, ident): with eng.connect().execution_options(isolation_level="AUTOCOMMIT") as conn: with conn.begin(): conn.execute( text( "select pg_terminate_backend(pid) from pg_stat_activity " "where usename=current_user and pid != pg_backend_pid() " "and datname=:dname" ), dict(dname=ident), ) conn.exec_driver_sql("DROP DATABASE %s" % ident) @temp_table_keyword_args.for_db("postgresql") def _postgresql_temp_table_keyword_args(cfg, eng): return {"prefixes": ["TEMPORARY"]} @set_default_schema_on_connection.for_db("postgresql") def _postgresql_set_default_schema_on_connection( cfg, dbapi_connection, schema_name ): existing_autocommit = dbapi_connection.autocommit dbapi_connection.autocommit = True cursor = dbapi_connection.cursor() cursor.execute("SET SESSION search_path='%s'" % schema_name) cursor.close() dbapi_connection.autocommit = existing_autocommit @drop_all_schema_objects_pre_tables.for_db("postgresql") def drop_all_schema_objects_pre_tables(cfg, eng): with eng.connect().execution_options(isolation_level="AUTOCOMMIT") as conn: for xid in conn.exec_driver_sql( "select gid from pg_prepared_xacts" ).scalars(): conn.exec_driver_sql("ROLLBACK PREPARED '%s'" % xid) @drop_all_schema_objects_post_tables.for_db("postgresql") def drop_all_schema_objects_post_tables(cfg, eng): from sqlalchemy.dialects import postgresql inspector = inspect(eng) with eng.begin() as conn: for enum in inspector.get_enums("*"): conn.execute( postgresql.DropEnumType( postgresql.ENUM(name=enum["name"], schema=enum["schema"]) ) ) @prepare_for_drop_tables.for_db("postgresql") def prepare_for_drop_tables(config, connection): """Ensure there are no locks on the current username/database.""" result = connection.exec_driver_sql( "select pid, state, wait_event_type, query " # "select pg_terminate_backend(pid), state, wait_event_type " "from pg_stat_activity where " "usename=current_user " "and datname=current_database() and state='idle in transaction' " "and pid != pg_backend_pid()" ) rows = result.all() # noqa if rows: warn_test_suite( "PostgreSQL may not be able to DROP tables due to " "idle in transaction: %s" % ("; ".join(row._mapping["query"] for row in rows)) ) @upsert.for_db("postgresql") def _upsert( cfg, table, returning, *, set_lambda=None, sort_by_parameter_order=False ): from sqlalchemy.dialects.postgresql import insert stmt = insert(table) table_pk = inspect(table).selectable if set_lambda: stmt = stmt.on_conflict_do_update( index_elements=table_pk.primary_key, set_=set_lambda(stmt.excluded) ) else: stmt = stmt.on_conflict_do_nothing() stmt = stmt.returning( *returning, sort_by_parameter_order=sort_by_parameter_order ) return stmt _extensions = [ ("citext", (13,)), ("hstore", (13,)), ] @post_configure_engine.for_db("postgresql") def _create_citext_extension(url, engine, follower_ident): with engine.connect() as conn: for extension, min_version in _extensions: if conn.dialect.server_version_info >= min_version: conn.execute( text(f"CREATE EXTENSION IF NOT EXISTS {extension}") ) conn.commit() sqlalchemy/dialects/postgresql/pg_catalog.py 0000755 00000022640 15125143220 0015355 0 ustar 00 # dialects/postgresql/pg_catalog.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php from __future__ import annotations from typing import Any from typing import Optional from typing import Sequence from typing import TYPE_CHECKING from .array import ARRAY from .types import OID from .types import REGCLASS from ... import Column from ... import func from ... import MetaData from ... import Table from ...types import BigInteger from ...types import Boolean from ...types import CHAR from ...types import Float from ...types import Integer from ...types import SmallInteger from ...types import String from ...types import Text from ...types import TypeDecorator if TYPE_CHECKING: from ...engine.interfaces import Dialect from ...sql.type_api import _ResultProcessorType # types class NAME(TypeDecorator[str]): impl = String(64, collation="C") cache_ok = True class PG_NODE_TREE(TypeDecorator[str]): impl = Text(collation="C") cache_ok = True class INT2VECTOR(TypeDecorator[Sequence[int]]): impl = ARRAY(SmallInteger) cache_ok = True class OIDVECTOR(TypeDecorator[Sequence[int]]): impl = ARRAY(OID) cache_ok = True class _SpaceVector: def result_processor( self, dialect: Dialect, coltype: object ) -> _ResultProcessorType[list[int]]: def process(value: Any) -> Optional[list[int]]: if value is None: return value return [int(p) for p in value.split(" ")] return process REGPROC = REGCLASS # seems an alias # functions _pg_cat = func.pg_catalog quote_ident = _pg_cat.quote_ident pg_table_is_visible = _pg_cat.pg_table_is_visible pg_type_is_visible = _pg_cat.pg_type_is_visible pg_get_viewdef = _pg_cat.pg_get_viewdef pg_get_serial_sequence = _pg_cat.pg_get_serial_sequence format_type = _pg_cat.format_type pg_get_expr = _pg_cat.pg_get_expr pg_get_constraintdef = _pg_cat.pg_get_constraintdef pg_get_indexdef = _pg_cat.pg_get_indexdef # constants RELKINDS_TABLE_NO_FOREIGN = ("r", "p") RELKINDS_TABLE = RELKINDS_TABLE_NO_FOREIGN + ("f",) RELKINDS_VIEW = ("v",) RELKINDS_MAT_VIEW = ("m",) RELKINDS_ALL_TABLE_LIKE = RELKINDS_TABLE + RELKINDS_VIEW + RELKINDS_MAT_VIEW # tables pg_catalog_meta = MetaData(schema="pg_catalog") pg_namespace = Table( "pg_namespace", pg_catalog_meta, Column("oid", OID), Column("nspname", NAME), Column("nspowner", OID), ) pg_class = Table( "pg_class", pg_catalog_meta, Column("oid", OID, info={"server_version": (9, 3)}), Column("relname", NAME), Column("relnamespace", OID), Column("reltype", OID), Column("reloftype", OID), Column("relowner", OID), Column("relam", OID), Column("relfilenode", OID), Column("reltablespace", OID), Column("relpages", Integer), Column("reltuples", Float), Column("relallvisible", Integer, info={"server_version": (9, 2)}), Column("reltoastrelid", OID), Column("relhasindex", Boolean), Column("relisshared", Boolean), Column("relpersistence", CHAR, info={"server_version": (9, 1)}), Column("relkind", CHAR), Column("relnatts", SmallInteger), Column("relchecks", SmallInteger), Column("relhasrules", Boolean), Column("relhastriggers", Boolean), Column("relhassubclass", Boolean), Column("relrowsecurity", Boolean), Column("relforcerowsecurity", Boolean, info={"server_version": (9, 5)}), Column("relispopulated", Boolean, info={"server_version": (9, 3)}), Column("relreplident", CHAR, info={"server_version": (9, 4)}), Column("relispartition", Boolean, info={"server_version": (10,)}), Column("relrewrite", OID, info={"server_version": (11,)}), Column("reloptions", ARRAY(Text)), ) pg_type = Table( "pg_type", pg_catalog_meta, Column("oid", OID, info={"server_version": (9, 3)}), Column("typname", NAME), Column("typnamespace", OID), Column("typowner", OID), Column("typlen", SmallInteger), Column("typbyval", Boolean), Column("typtype", CHAR), Column("typcategory", CHAR), Column("typispreferred", Boolean), Column("typisdefined", Boolean), Column("typdelim", CHAR), Column("typrelid", OID), Column("typelem", OID), Column("typarray", OID), Column("typinput", REGPROC), Column("typoutput", REGPROC), Column("typreceive", REGPROC), Column("typsend", REGPROC), Column("typmodin", REGPROC), Column("typmodout", REGPROC), Column("typanalyze", REGPROC), Column("typalign", CHAR), Column("typstorage", CHAR), Column("typnotnull", Boolean), Column("typbasetype", OID), Column("typtypmod", Integer), Column("typndims", Integer), Column("typcollation", OID, info={"server_version": (9, 1)}), Column("typdefault", Text), ) pg_index = Table( "pg_index", pg_catalog_meta, Column("indexrelid", OID), Column("indrelid", OID), Column("indnatts", SmallInteger), Column("indnkeyatts", SmallInteger, info={"server_version": (11,)}), Column("indisunique", Boolean), Column("indnullsnotdistinct", Boolean, info={"server_version": (15,)}), Column("indisprimary", Boolean), Column("indisexclusion", Boolean, info={"server_version": (9, 1)}), Column("indimmediate", Boolean), Column("indisclustered", Boolean), Column("indisvalid", Boolean), Column("indcheckxmin", Boolean), Column("indisready", Boolean), Column("indislive", Boolean, info={"server_version": (9, 3)}), # 9.3 Column("indisreplident", Boolean), Column("indkey", INT2VECTOR), Column("indcollation", OIDVECTOR, info={"server_version": (9, 1)}), # 9.1 Column("indclass", OIDVECTOR), Column("indoption", INT2VECTOR), Column("indexprs", PG_NODE_TREE), Column("indpred", PG_NODE_TREE), ) pg_attribute = Table( "pg_attribute", pg_catalog_meta, Column("attrelid", OID), Column("attname", NAME), Column("atttypid", OID), Column("attstattarget", Integer), Column("attlen", SmallInteger), Column("attnum", SmallInteger), Column("attndims", Integer), Column("attcacheoff", Integer), Column("atttypmod", Integer), Column("attbyval", Boolean), Column("attstorage", CHAR), Column("attalign", CHAR), Column("attnotnull", Boolean), Column("atthasdef", Boolean), Column("atthasmissing", Boolean, info={"server_version": (11,)}), Column("attidentity", CHAR, info={"server_version": (10,)}), Column("attgenerated", CHAR, info={"server_version": (12,)}), Column("attisdropped", Boolean), Column("attislocal", Boolean), Column("attinhcount", Integer), Column("attcollation", OID, info={"server_version": (9, 1)}), ) pg_constraint = Table( "pg_constraint", pg_catalog_meta, Column("oid", OID), # 9.3 Column("conname", NAME), Column("connamespace", OID), Column("contype", CHAR), Column("condeferrable", Boolean), Column("condeferred", Boolean), Column("convalidated", Boolean, info={"server_version": (9, 1)}), Column("conrelid", OID), Column("contypid", OID), Column("conindid", OID), Column("conparentid", OID, info={"server_version": (11,)}), Column("confrelid", OID), Column("confupdtype", CHAR), Column("confdeltype", CHAR), Column("confmatchtype", CHAR), Column("conislocal", Boolean), Column("coninhcount", Integer), Column("connoinherit", Boolean, info={"server_version": (9, 2)}), Column("conkey", ARRAY(SmallInteger)), Column("confkey", ARRAY(SmallInteger)), ) pg_sequence = Table( "pg_sequence", pg_catalog_meta, Column("seqrelid", OID), Column("seqtypid", OID), Column("seqstart", BigInteger), Column("seqincrement", BigInteger), Column("seqmax", BigInteger), Column("seqmin", BigInteger), Column("seqcache", BigInteger), Column("seqcycle", Boolean), info={"server_version": (10,)}, ) pg_attrdef = Table( "pg_attrdef", pg_catalog_meta, Column("oid", OID, info={"server_version": (9, 3)}), Column("adrelid", OID), Column("adnum", SmallInteger), Column("adbin", PG_NODE_TREE), ) pg_description = Table( "pg_description", pg_catalog_meta, Column("objoid", OID), Column("classoid", OID), Column("objsubid", Integer), Column("description", Text(collation="C")), ) pg_enum = Table( "pg_enum", pg_catalog_meta, Column("oid", OID, info={"server_version": (9, 3)}), Column("enumtypid", OID), Column("enumsortorder", Float(), info={"server_version": (9, 1)}), Column("enumlabel", NAME), ) pg_am = Table( "pg_am", pg_catalog_meta, Column("oid", OID, info={"server_version": (9, 3)}), Column("amname", NAME), Column("amhandler", REGPROC, info={"server_version": (9, 6)}), Column("amtype", CHAR, info={"server_version": (9, 6)}), ) pg_collation = Table( "pg_collation", pg_catalog_meta, Column("oid", OID, info={"server_version": (9, 3)}), Column("collname", NAME), Column("collnamespace", OID), Column("collowner", OID), Column("collprovider", CHAR, info={"server_version": (10,)}), Column("collisdeterministic", Boolean, info={"server_version": (12,)}), Column("collencoding", Integer), Column("collcollate", Text), Column("collctype", Text), Column("colliculocale", Text), Column("collicurules", Text, info={"server_version": (16,)}), Column("collversion", Text, info={"server_version": (10,)}), ) sqlalchemy/dialects/postgresql/asyncpg.py 0000755 00000120507 15125143220 0014722 0 ustar 00 # dialects/postgresql/asyncpg.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors <see AUTHORS # file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors r""" .. dialect:: postgresql+asyncpg :name: asyncpg :dbapi: asyncpg :connectstring: postgresql+asyncpg://user:password@host:port/dbname[?key=value&key=value...] :url: https://magicstack.github.io/asyncpg/ The asyncpg dialect is SQLAlchemy's first Python asyncio dialect. Using a special asyncio mediation layer, the asyncpg dialect is usable as the backend for the :ref:`SQLAlchemy asyncio <asyncio_toplevel>` extension package. This dialect should normally be used only with the :func:`_asyncio.create_async_engine` engine creation function:: from sqlalchemy.ext.asyncio import create_async_engine engine = create_async_engine( "postgresql+asyncpg://user:pass@hostname/dbname" ) .. versionadded:: 1.4 .. note:: By default asyncpg does not decode the ``json`` and ``jsonb`` types and returns them as strings. SQLAlchemy sets default type decoder for ``json`` and ``jsonb`` types using the python builtin ``json.loads`` function. The json implementation used can be changed by setting the attribute ``json_deserializer`` when creating the engine with :func:`create_engine` or :func:`create_async_engine`. .. _asyncpg_multihost: Multihost Connections -------------------------- The asyncpg dialect features support for multiple fallback hosts in the same way as that of the psycopg2 and psycopg dialects. The syntax is the same, using ``host=<host>:<port>`` combinations as additional query string arguments; however, there is no default port, so all hosts must have a complete port number present, otherwise an exception is raised:: engine = create_async_engine( "postgresql+asyncpg://user:password@/dbname?host=HostA:5432&host=HostB:5432&host=HostC:5432" ) For complete background on this syntax, see :ref:`psycopg2_multi_host`. .. versionadded:: 2.0.18 .. seealso:: :ref:`psycopg2_multi_host` .. _asyncpg_prepared_statement_cache: Prepared Statement Cache -------------------------- The asyncpg SQLAlchemy dialect makes use of ``asyncpg.connection.prepare()`` for all statements. The prepared statement objects are cached after construction which appears to grant a 10% or more performance improvement for statement invocation. The cache is on a per-DBAPI connection basis, which means that the primary storage for prepared statements is within DBAPI connections pooled within the connection pool. The size of this cache defaults to 100 statements per DBAPI connection and may be adjusted using the ``prepared_statement_cache_size`` DBAPI argument (note that while this argument is implemented by SQLAlchemy, it is part of the DBAPI emulation portion of the asyncpg dialect, therefore is handled as a DBAPI argument, not a dialect argument):: engine = create_async_engine( "postgresql+asyncpg://user:pass@hostname/dbname?prepared_statement_cache_size=500" ) To disable the prepared statement cache, use a value of zero:: engine = create_async_engine( "postgresql+asyncpg://user:pass@hostname/dbname?prepared_statement_cache_size=0" ) .. versionadded:: 1.4.0b2 Added ``prepared_statement_cache_size`` for asyncpg. .. warning:: The ``asyncpg`` database driver necessarily uses caches for PostgreSQL type OIDs, which become stale when custom PostgreSQL datatypes such as ``ENUM`` objects are changed via DDL operations. Additionally, prepared statements themselves which are optionally cached by SQLAlchemy's driver as described above may also become "stale" when DDL has been emitted to the PostgreSQL database which modifies the tables or other objects involved in a particular prepared statement. The SQLAlchemy asyncpg dialect will invalidate these caches within its local process when statements that represent DDL are emitted on a local connection, but this is only controllable within a single Python process / database engine. If DDL changes are made from other database engines and/or processes, a running application may encounter asyncpg exceptions ``InvalidCachedStatementError`` and/or ``InternalServerError("cache lookup failed for type <oid>")`` if it refers to pooled database connections which operated upon the previous structures. The SQLAlchemy asyncpg dialect will recover from these error cases when the driver raises these exceptions by clearing its internal caches as well as those of the asyncpg driver in response to them, but cannot prevent them from being raised in the first place if the cached prepared statement or asyncpg type caches have gone stale, nor can it retry the statement as the PostgreSQL transaction is invalidated when these errors occur. .. _asyncpg_prepared_statement_name: Prepared Statement Name with PGBouncer -------------------------------------- By default, asyncpg enumerates prepared statements in numeric order, which can lead to errors if a name has already been taken for another prepared statement. This issue can arise if your application uses database proxies such as PgBouncer to handle connections. One possible workaround is to use dynamic prepared statement names, which asyncpg now supports through an optional ``name`` value for the statement name. This allows you to generate your own unique names that won't conflict with existing ones. To achieve this, you can provide a function that will be called every time a prepared statement is prepared:: from uuid import uuid4 engine = create_async_engine( "postgresql+asyncpg://user:pass@somepgbouncer/dbname", poolclass=NullPool, connect_args={ "prepared_statement_name_func": lambda: f"__asyncpg_{uuid4()}__", }, ) .. seealso:: https://github.com/MagicStack/asyncpg/issues/837 https://github.com/sqlalchemy/sqlalchemy/issues/6467 .. warning:: When using PGBouncer, to prevent a buildup of useless prepared statements in your application, it's important to use the :class:`.NullPool` pool class, and to configure PgBouncer to use `DISCARD <https://www.postgresql.org/docs/current/sql-discard.html>`_ when returning connections. The DISCARD command is used to release resources held by the db connection, including prepared statements. Without proper setup, prepared statements can accumulate quickly and cause performance issues. Disabling the PostgreSQL JIT to improve ENUM datatype handling --------------------------------------------------------------- Asyncpg has an `issue <https://github.com/MagicStack/asyncpg/issues/727>`_ when using PostgreSQL ENUM datatypes, where upon the creation of new database connections, an expensive query may be emitted in order to retrieve metadata regarding custom types which has been shown to negatively affect performance. To mitigate this issue, the PostgreSQL "jit" setting may be disabled from the client using this setting passed to :func:`_asyncio.create_async_engine`:: engine = create_async_engine( "postgresql+asyncpg://user:password@localhost/tmp", connect_args={"server_settings": {"jit": "off"}}, ) .. seealso:: https://github.com/MagicStack/asyncpg/issues/727 """ # noqa from __future__ import annotations from collections import deque import decimal import json as _py_json import re import time from . import json from . import ranges from .array import ARRAY as PGARRAY from .base import _DECIMAL_TYPES from .base import _FLOAT_TYPES from .base import _INT_TYPES from .base import ENUM from .base import INTERVAL from .base import OID from .base import PGCompiler from .base import PGDialect from .base import PGExecutionContext from .base import PGIdentifierPreparer from .base import REGCLASS from .base import REGCONFIG from .types import BIT from .types import BYTEA from .types import CITEXT from ... import exc from ... import pool from ... import util from ...engine import AdaptedConnection from ...engine import processors from ...sql import sqltypes from ...util.concurrency import asyncio from ...util.concurrency import await_fallback from ...util.concurrency import await_only class AsyncpgARRAY(PGARRAY): render_bind_cast = True class AsyncpgString(sqltypes.String): render_bind_cast = True class AsyncpgREGCONFIG(REGCONFIG): render_bind_cast = True class AsyncpgTime(sqltypes.Time): render_bind_cast = True class AsyncpgBit(BIT): render_bind_cast = True class AsyncpgByteA(BYTEA): render_bind_cast = True class AsyncpgDate(sqltypes.Date): render_bind_cast = True class AsyncpgDateTime(sqltypes.DateTime): render_bind_cast = True class AsyncpgBoolean(sqltypes.Boolean): render_bind_cast = True class AsyncPgInterval(INTERVAL): render_bind_cast = True @classmethod def adapt_emulated_to_native(cls, interval, **kw): return AsyncPgInterval(precision=interval.second_precision) class AsyncPgEnum(ENUM): render_bind_cast = True class AsyncpgInteger(sqltypes.Integer): render_bind_cast = True class AsyncpgSmallInteger(sqltypes.SmallInteger): render_bind_cast = True class AsyncpgBigInteger(sqltypes.BigInteger): render_bind_cast = True class AsyncpgJSON(json.JSON): def result_processor(self, dialect, coltype): return None class AsyncpgJSONB(json.JSONB): def result_processor(self, dialect, coltype): return None class AsyncpgJSONIndexType(sqltypes.JSON.JSONIndexType): pass class AsyncpgJSONIntIndexType(sqltypes.JSON.JSONIntIndexType): __visit_name__ = "json_int_index" render_bind_cast = True class AsyncpgJSONStrIndexType(sqltypes.JSON.JSONStrIndexType): __visit_name__ = "json_str_index" render_bind_cast = True class AsyncpgJSONPathType(json.JSONPathType): def bind_processor(self, dialect): def process(value): if isinstance(value, str): # If it's already a string assume that it's in json path # format. This allows using cast with json paths literals return value elif value: tokens = [str(elem) for elem in value] return tokens else: return [] return process class AsyncpgNumeric(sqltypes.Numeric): render_bind_cast = True def bind_processor(self, dialect): return None def result_processor(self, dialect, coltype): if self.asdecimal: if coltype in _FLOAT_TYPES: return processors.to_decimal_processor_factory( decimal.Decimal, self._effective_decimal_return_scale ) elif coltype in _DECIMAL_TYPES or coltype in _INT_TYPES: # pg8000 returns Decimal natively for 1700 return None else: raise exc.InvalidRequestError( "Unknown PG numeric type: %d" % coltype ) else: if coltype in _FLOAT_TYPES: # pg8000 returns float natively for 701 return None elif coltype in _DECIMAL_TYPES or coltype in _INT_TYPES: return processors.to_float else: raise exc.InvalidRequestError( "Unknown PG numeric type: %d" % coltype ) class AsyncpgFloat(AsyncpgNumeric, sqltypes.Float): __visit_name__ = "float" render_bind_cast = True class AsyncpgREGCLASS(REGCLASS): render_bind_cast = True class AsyncpgOID(OID): render_bind_cast = True class AsyncpgCHAR(sqltypes.CHAR): render_bind_cast = True class _AsyncpgRange(ranges.AbstractSingleRangeImpl): def bind_processor(self, dialect): asyncpg_Range = dialect.dbapi.asyncpg.Range def to_range(value): if isinstance(value, ranges.Range): value = asyncpg_Range( value.lower, value.upper, lower_inc=value.bounds[0] == "[", upper_inc=value.bounds[1] == "]", empty=value.empty, ) return value return to_range def result_processor(self, dialect, coltype): def to_range(value): if value is not None: empty = value.isempty value = ranges.Range( value.lower, value.upper, bounds=f"{'[' if empty or value.lower_inc else '('}" # type: ignore # noqa: E501 f"{']' if not empty and value.upper_inc else ')'}", empty=empty, ) return value return to_range class _AsyncpgMultiRange(ranges.AbstractMultiRangeImpl): def bind_processor(self, dialect): asyncpg_Range = dialect.dbapi.asyncpg.Range NoneType = type(None) def to_range(value): if isinstance(value, (str, NoneType)): return value def to_range(value): if isinstance(value, ranges.Range): value = asyncpg_Range( value.lower, value.upper, lower_inc=value.bounds[0] == "[", upper_inc=value.bounds[1] == "]", empty=value.empty, ) return value return [to_range(element) for element in value] return to_range def result_processor(self, dialect, coltype): def to_range_array(value): def to_range(rvalue): if rvalue is not None: empty = rvalue.isempty rvalue = ranges.Range( rvalue.lower, rvalue.upper, bounds=f"{'[' if empty or rvalue.lower_inc else '('}" # type: ignore # noqa: E501 f"{']' if not empty and rvalue.upper_inc else ')'}", empty=empty, ) return rvalue if value is not None: value = ranges.MultiRange(to_range(elem) for elem in value) return value return to_range_array class PGExecutionContext_asyncpg(PGExecutionContext): def handle_dbapi_exception(self, e): if isinstance( e, ( self.dialect.dbapi.InvalidCachedStatementError, self.dialect.dbapi.InternalServerError, ), ): self.dialect._invalidate_schema_cache() def pre_exec(self): if self.isddl: self.dialect._invalidate_schema_cache() self.cursor._invalidate_schema_cache_asof = ( self.dialect._invalidate_schema_cache_asof ) if not self.compiled: return def create_server_side_cursor(self): return self._dbapi_connection.cursor(server_side=True) class PGCompiler_asyncpg(PGCompiler): pass class PGIdentifierPreparer_asyncpg(PGIdentifierPreparer): pass class AsyncAdapt_asyncpg_cursor: __slots__ = ( "_adapt_connection", "_connection", "_rows", "description", "arraysize", "rowcount", "_cursor", "_invalidate_schema_cache_asof", ) server_side = False def __init__(self, adapt_connection): self._adapt_connection = adapt_connection self._connection = adapt_connection._connection self._rows = deque() self._cursor = None self.description = None self.arraysize = 1 self.rowcount = -1 self._invalidate_schema_cache_asof = 0 def close(self): self._rows.clear() def _handle_exception(self, error): self._adapt_connection._handle_exception(error) async def _prepare_and_execute(self, operation, parameters): adapt_connection = self._adapt_connection async with adapt_connection._execute_mutex: if not adapt_connection._started: await adapt_connection._start_transaction() if parameters is None: parameters = () try: prepared_stmt, attributes = await adapt_connection._prepare( operation, self._invalidate_schema_cache_asof ) if attributes: self.description = [ ( attr.name, attr.type.oid, None, None, None, None, None, ) for attr in attributes ] else: self.description = None if self.server_side: self._cursor = await prepared_stmt.cursor(*parameters) self.rowcount = -1 else: self._rows = deque(await prepared_stmt.fetch(*parameters)) status = prepared_stmt.get_statusmsg() reg = re.match( r"(?:SELECT|UPDATE|DELETE|INSERT \d+) (\d+)", status or "", ) if reg: self.rowcount = int(reg.group(1)) else: self.rowcount = -1 except Exception as error: self._handle_exception(error) async def _executemany(self, operation, seq_of_parameters): adapt_connection = self._adapt_connection self.description = None async with adapt_connection._execute_mutex: await adapt_connection._check_type_cache_invalidation( self._invalidate_schema_cache_asof ) if not adapt_connection._started: await adapt_connection._start_transaction() try: return await self._connection.executemany( operation, seq_of_parameters ) except Exception as error: self._handle_exception(error) def execute(self, operation, parameters=None): self._adapt_connection.await_( self._prepare_and_execute(operation, parameters) ) def executemany(self, operation, seq_of_parameters): return self._adapt_connection.await_( self._executemany(operation, seq_of_parameters) ) def setinputsizes(self, *inputsizes): raise NotImplementedError() def __iter__(self): while self._rows: yield self._rows.popleft() def fetchone(self): if self._rows: return self._rows.popleft() else: return None def fetchmany(self, size=None): if size is None: size = self.arraysize rr = self._rows return [rr.popleft() for _ in range(min(size, len(rr)))] def fetchall(self): retval = list(self._rows) self._rows.clear() return retval class AsyncAdapt_asyncpg_ss_cursor(AsyncAdapt_asyncpg_cursor): server_side = True __slots__ = ("_rowbuffer",) def __init__(self, adapt_connection): super().__init__(adapt_connection) self._rowbuffer = deque() def close(self): self._cursor = None self._rowbuffer.clear() def _buffer_rows(self): assert self._cursor is not None new_rows = self._adapt_connection.await_(self._cursor.fetch(50)) self._rowbuffer.extend(new_rows) def __aiter__(self): return self async def __anext__(self): while True: while self._rowbuffer: yield self._rowbuffer.popleft() self._buffer_rows() if not self._rowbuffer: break def fetchone(self): if not self._rowbuffer: self._buffer_rows() if not self._rowbuffer: return None return self._rowbuffer.popleft() def fetchmany(self, size=None): if size is None: return self.fetchall() if not self._rowbuffer: self._buffer_rows() assert self._cursor is not None rb = self._rowbuffer lb = len(rb) if size > lb: rb.extend( self._adapt_connection.await_(self._cursor.fetch(size - lb)) ) return [rb.popleft() for _ in range(min(size, len(rb)))] def fetchall(self): ret = list(self._rowbuffer) ret.extend(self._adapt_connection.await_(self._all())) self._rowbuffer.clear() return ret async def _all(self): rows = [] # TODO: looks like we have to hand-roll some kind of batching here. # hardcoding for the moment but this should be improved. while True: batch = await self._cursor.fetch(1000) if batch: rows.extend(batch) continue else: break return rows def executemany(self, operation, seq_of_parameters): raise NotImplementedError( "server side cursor doesn't support executemany yet" ) class AsyncAdapt_asyncpg_connection(AdaptedConnection): __slots__ = ( "dbapi", "isolation_level", "_isolation_setting", "readonly", "deferrable", "_transaction", "_started", "_prepared_statement_cache", "_prepared_statement_name_func", "_invalidate_schema_cache_asof", "_execute_mutex", ) await_ = staticmethod(await_only) def __init__( self, dbapi, connection, prepared_statement_cache_size=100, prepared_statement_name_func=None, ): self.dbapi = dbapi self._connection = connection self.isolation_level = self._isolation_setting = None self.readonly = False self.deferrable = False self._transaction = None self._started = False self._invalidate_schema_cache_asof = time.time() self._execute_mutex = asyncio.Lock() if prepared_statement_cache_size: self._prepared_statement_cache = util.LRUCache( prepared_statement_cache_size ) else: self._prepared_statement_cache = None if prepared_statement_name_func: self._prepared_statement_name_func = prepared_statement_name_func else: self._prepared_statement_name_func = self._default_name_func async def _check_type_cache_invalidation(self, invalidate_timestamp): if invalidate_timestamp > self._invalidate_schema_cache_asof: await self._connection.reload_schema_state() self._invalidate_schema_cache_asof = invalidate_timestamp async def _prepare(self, operation, invalidate_timestamp): await self._check_type_cache_invalidation(invalidate_timestamp) cache = self._prepared_statement_cache if cache is None: prepared_stmt = await self._connection.prepare( operation, name=self._prepared_statement_name_func() ) attributes = prepared_stmt.get_attributes() return prepared_stmt, attributes # asyncpg uses a type cache for the "attributes" which seems to go # stale independently of the PreparedStatement itself, so place that # collection in the cache as well. if operation in cache: prepared_stmt, attributes, cached_timestamp = cache[operation] # preparedstatements themselves also go stale for certain DDL # changes such as size of a VARCHAR changing, so there is also # a cross-connection invalidation timestamp if cached_timestamp > invalidate_timestamp: return prepared_stmt, attributes prepared_stmt = await self._connection.prepare( operation, name=self._prepared_statement_name_func() ) attributes = prepared_stmt.get_attributes() cache[operation] = (prepared_stmt, attributes, time.time()) return prepared_stmt, attributes def _handle_exception(self, error): if self._connection.is_closed(): self._transaction = None self._started = False if not isinstance(error, AsyncAdapt_asyncpg_dbapi.Error): exception_mapping = self.dbapi._asyncpg_error_translate for super_ in type(error).__mro__: if super_ in exception_mapping: translated_error = exception_mapping[super_]( "%s: %s" % (type(error), error) ) translated_error.pgcode = translated_error.sqlstate = ( getattr(error, "sqlstate", None) ) raise translated_error from error else: raise error else: raise error @property def autocommit(self): return self.isolation_level == "autocommit" @autocommit.setter def autocommit(self, value): if value: self.isolation_level = "autocommit" else: self.isolation_level = self._isolation_setting def ping(self): try: _ = self.await_(self._async_ping()) except Exception as error: self._handle_exception(error) async def _async_ping(self): if self._transaction is None and self.isolation_level != "autocommit": # create a tranasction explicitly to support pgbouncer # transaction mode. See #10226 tr = self._connection.transaction() await tr.start() try: await self._connection.fetchrow(";") finally: await tr.rollback() else: await self._connection.fetchrow(";") def set_isolation_level(self, level): if self._started: self.rollback() self.isolation_level = self._isolation_setting = level async def _start_transaction(self): if self.isolation_level == "autocommit": return try: self._transaction = self._connection.transaction( isolation=self.isolation_level, readonly=self.readonly, deferrable=self.deferrable, ) await self._transaction.start() except Exception as error: self._handle_exception(error) else: self._started = True def cursor(self, server_side=False): if server_side: return AsyncAdapt_asyncpg_ss_cursor(self) else: return AsyncAdapt_asyncpg_cursor(self) async def _rollback_and_discard(self): try: await self._transaction.rollback() finally: # if asyncpg .rollback() was actually called, then whether or # not it raised or succeeded, the transation is done, discard it self._transaction = None self._started = False async def _commit_and_discard(self): try: await self._transaction.commit() finally: # if asyncpg .commit() was actually called, then whether or # not it raised or succeeded, the transation is done, discard it self._transaction = None self._started = False def rollback(self): if self._started: try: self.await_(self._rollback_and_discard()) self._transaction = None self._started = False except Exception as error: # don't dereference asyncpg transaction if we didn't # actually try to call rollback() on it self._handle_exception(error) def commit(self): if self._started: try: self.await_(self._commit_and_discard()) self._transaction = None self._started = False except Exception as error: # don't dereference asyncpg transaction if we didn't # actually try to call commit() on it self._handle_exception(error) def close(self): self.rollback() self.await_(self._connection.close()) def terminate(self): if util.concurrency.in_greenlet(): # in a greenlet; this is the connection was invalidated # case. try: # try to gracefully close; see #10717 # timeout added in asyncpg 0.14.0 December 2017 self.await_(asyncio.shield(self._connection.close(timeout=2))) except ( asyncio.TimeoutError, asyncio.CancelledError, OSError, self.dbapi.asyncpg.PostgresError, ): # in the case where we are recycling an old connection # that may have already been disconnected, close() will # fail with the above timeout. in this case, terminate # the connection without any further waiting. # see issue #8419 self._connection.terminate() else: # not in a greenlet; this is the gc cleanup case self._connection.terminate() self._started = False @staticmethod def _default_name_func(): return None class AsyncAdaptFallback_asyncpg_connection(AsyncAdapt_asyncpg_connection): __slots__ = () await_ = staticmethod(await_fallback) class AsyncAdapt_asyncpg_dbapi: def __init__(self, asyncpg): self.asyncpg = asyncpg self.paramstyle = "numeric_dollar" def connect(self, *arg, **kw): async_fallback = kw.pop("async_fallback", False) creator_fn = kw.pop("async_creator_fn", self.asyncpg.connect) prepared_statement_cache_size = kw.pop( "prepared_statement_cache_size", 100 ) prepared_statement_name_func = kw.pop( "prepared_statement_name_func", None ) if util.asbool(async_fallback): return AsyncAdaptFallback_asyncpg_connection( self, await_fallback(creator_fn(*arg, **kw)), prepared_statement_cache_size=prepared_statement_cache_size, prepared_statement_name_func=prepared_statement_name_func, ) else: return AsyncAdapt_asyncpg_connection( self, await_only(creator_fn(*arg, **kw)), prepared_statement_cache_size=prepared_statement_cache_size, prepared_statement_name_func=prepared_statement_name_func, ) class Error(Exception): pass class Warning(Exception): # noqa pass class InterfaceError(Error): pass class DatabaseError(Error): pass class InternalError(DatabaseError): pass class OperationalError(DatabaseError): pass class ProgrammingError(DatabaseError): pass class IntegrityError(DatabaseError): pass class DataError(DatabaseError): pass class NotSupportedError(DatabaseError): pass class InternalServerError(InternalError): pass class InvalidCachedStatementError(NotSupportedError): def __init__(self, message): super().__init__( message + " (SQLAlchemy asyncpg dialect will now invalidate " "all prepared caches in response to this exception)", ) # pep-249 datatype placeholders. As of SQLAlchemy 2.0 these aren't # used, however the test suite looks for these in a few cases. STRING = util.symbol("STRING") NUMBER = util.symbol("NUMBER") DATETIME = util.symbol("DATETIME") @util.memoized_property def _asyncpg_error_translate(self): import asyncpg return { asyncpg.exceptions.IntegrityConstraintViolationError: self.IntegrityError, # noqa: E501 asyncpg.exceptions.PostgresError: self.Error, asyncpg.exceptions.SyntaxOrAccessError: self.ProgrammingError, asyncpg.exceptions.InterfaceError: self.InterfaceError, asyncpg.exceptions.InvalidCachedStatementError: self.InvalidCachedStatementError, # noqa: E501 asyncpg.exceptions.InternalServerError: self.InternalServerError, } def Binary(self, value): return value class PGDialect_asyncpg(PGDialect): driver = "asyncpg" supports_statement_cache = True supports_server_side_cursors = True render_bind_cast = True has_terminate = True default_paramstyle = "numeric_dollar" supports_sane_multi_rowcount = False execution_ctx_cls = PGExecutionContext_asyncpg statement_compiler = PGCompiler_asyncpg preparer = PGIdentifierPreparer_asyncpg colspecs = util.update_copy( PGDialect.colspecs, { sqltypes.String: AsyncpgString, sqltypes.ARRAY: AsyncpgARRAY, BIT: AsyncpgBit, CITEXT: CITEXT, REGCONFIG: AsyncpgREGCONFIG, sqltypes.Time: AsyncpgTime, sqltypes.Date: AsyncpgDate, sqltypes.DateTime: AsyncpgDateTime, sqltypes.Interval: AsyncPgInterval, INTERVAL: AsyncPgInterval, sqltypes.Boolean: AsyncpgBoolean, sqltypes.Integer: AsyncpgInteger, sqltypes.SmallInteger: AsyncpgSmallInteger, sqltypes.BigInteger: AsyncpgBigInteger, sqltypes.Numeric: AsyncpgNumeric, sqltypes.Float: AsyncpgFloat, sqltypes.JSON: AsyncpgJSON, sqltypes.LargeBinary: AsyncpgByteA, json.JSONB: AsyncpgJSONB, sqltypes.JSON.JSONPathType: AsyncpgJSONPathType, sqltypes.JSON.JSONIndexType: AsyncpgJSONIndexType, sqltypes.JSON.JSONIntIndexType: AsyncpgJSONIntIndexType, sqltypes.JSON.JSONStrIndexType: AsyncpgJSONStrIndexType, sqltypes.Enum: AsyncPgEnum, OID: AsyncpgOID, REGCLASS: AsyncpgREGCLASS, sqltypes.CHAR: AsyncpgCHAR, ranges.AbstractSingleRange: _AsyncpgRange, ranges.AbstractMultiRange: _AsyncpgMultiRange, }, ) is_async = True _invalidate_schema_cache_asof = 0 def _invalidate_schema_cache(self): self._invalidate_schema_cache_asof = time.time() @util.memoized_property def _dbapi_version(self): if self.dbapi and hasattr(self.dbapi, "__version__"): return tuple( [ int(x) for x in re.findall( r"(\d+)(?:[-\.]?|$)", self.dbapi.__version__ ) ] ) else: return (99, 99, 99) @classmethod def import_dbapi(cls): return AsyncAdapt_asyncpg_dbapi(__import__("asyncpg")) @util.memoized_property def _isolation_lookup(self): return { "AUTOCOMMIT": "autocommit", "READ COMMITTED": "read_committed", "REPEATABLE READ": "repeatable_read", "SERIALIZABLE": "serializable", } def get_isolation_level_values(self, dbapi_connection): return list(self._isolation_lookup) def set_isolation_level(self, dbapi_connection, level): dbapi_connection.set_isolation_level(self._isolation_lookup[level]) def set_readonly(self, connection, value): connection.readonly = value def get_readonly(self, connection): return connection.readonly def set_deferrable(self, connection, value): connection.deferrable = value def get_deferrable(self, connection): return connection.deferrable def do_terminate(self, dbapi_connection) -> None: dbapi_connection.terminate() def create_connect_args(self, url): opts = url.translate_connect_args(username="user") multihosts, multiports = self._split_multihost_from_url(url) opts.update(url.query) if multihosts: assert multiports if len(multihosts) == 1: opts["host"] = multihosts[0] if multiports[0] is not None: opts["port"] = multiports[0] elif not all(multihosts): raise exc.ArgumentError( "All hosts are required to be present" " for asyncpg multiple host URL" ) elif not all(multiports): raise exc.ArgumentError( "All ports are required to be present" " for asyncpg multiple host URL" ) else: opts["host"] = list(multihosts) opts["port"] = list(multiports) else: util.coerce_kw_type(opts, "port", int) util.coerce_kw_type(opts, "prepared_statement_cache_size", int) return ([], opts) def do_ping(self, dbapi_connection): dbapi_connection.ping() return True @classmethod def get_pool_class(cls, url): async_fallback = url.query.get("async_fallback", False) if util.asbool(async_fallback): return pool.FallbackAsyncAdaptedQueuePool else: return pool.AsyncAdaptedQueuePool def is_disconnect(self, e, connection, cursor): if connection: return connection._connection.is_closed() else: return isinstance( e, self.dbapi.InterfaceError ) and "connection is closed" in str(e) async def setup_asyncpg_json_codec(self, conn): """set up JSON codec for asyncpg. This occurs for all new connections and can be overridden by third party dialects. .. versionadded:: 1.4.27 """ asyncpg_connection = conn._connection deserializer = self._json_deserializer or _py_json.loads def _json_decoder(bin_value): return deserializer(bin_value.decode()) await asyncpg_connection.set_type_codec( "json", encoder=str.encode, decoder=_json_decoder, schema="pg_catalog", format="binary", ) async def setup_asyncpg_jsonb_codec(self, conn): """set up JSONB codec for asyncpg. This occurs for all new connections and can be overridden by third party dialects. .. versionadded:: 1.4.27 """ asyncpg_connection = conn._connection deserializer = self._json_deserializer or _py_json.loads def _jsonb_encoder(str_value): # \x01 is the prefix for jsonb used by PostgreSQL. # asyncpg requires it when format='binary' return b"\x01" + str_value.encode() deserializer = self._json_deserializer or _py_json.loads def _jsonb_decoder(bin_value): # the byte is the \x01 prefix for jsonb used by PostgreSQL. # asyncpg returns it when format='binary' return deserializer(bin_value[1:].decode()) await asyncpg_connection.set_type_codec( "jsonb", encoder=_jsonb_encoder, decoder=_jsonb_decoder, schema="pg_catalog", format="binary", ) async def _disable_asyncpg_inet_codecs(self, conn): asyncpg_connection = conn._connection await asyncpg_connection.set_type_codec( "inet", encoder=lambda s: s, decoder=lambda s: s, schema="pg_catalog", format="text", ) await asyncpg_connection.set_type_codec( "cidr", encoder=lambda s: s, decoder=lambda s: s, schema="pg_catalog", format="text", ) def on_connect(self): """on_connect for asyncpg A major component of this for asyncpg is to set up type decoders at the asyncpg level. See https://github.com/MagicStack/asyncpg/issues/623 for notes on JSON/JSONB implementation. """ super_connect = super().on_connect() def connect(conn): conn.await_(self.setup_asyncpg_json_codec(conn)) conn.await_(self.setup_asyncpg_jsonb_codec(conn)) if self._native_inet_types is False: conn.await_(self._disable_asyncpg_inet_codecs(conn)) if super_connect is not None: super_connect(conn) return connect def get_driver_connection(self, connection): return connection._connection dialect = PGDialect_asyncpg sqlalchemy/dialects/postgresql/_psycopg_common.py 0000755 00000013052 15125143220 0016445 0 ustar 00 # dialects/postgresql/_psycopg_common.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors from __future__ import annotations import decimal from .array import ARRAY as PGARRAY from .base import _DECIMAL_TYPES from .base import _FLOAT_TYPES from .base import _INT_TYPES from .base import PGDialect from .base import PGExecutionContext from .hstore import HSTORE from .pg_catalog import _SpaceVector from .pg_catalog import INT2VECTOR from .pg_catalog import OIDVECTOR from ... import exc from ... import types as sqltypes from ... import util from ...engine import processors _server_side_id = util.counter() class _PsycopgNumeric(sqltypes.Numeric): def bind_processor(self, dialect): return None def result_processor(self, dialect, coltype): if self.asdecimal: if coltype in _FLOAT_TYPES: return processors.to_decimal_processor_factory( decimal.Decimal, self._effective_decimal_return_scale ) elif coltype in _DECIMAL_TYPES or coltype in _INT_TYPES: # psycopg returns Decimal natively for 1700 return None else: raise exc.InvalidRequestError( "Unknown PG numeric type: %d" % coltype ) else: if coltype in _FLOAT_TYPES: # psycopg returns float natively for 701 return None elif coltype in _DECIMAL_TYPES or coltype in _INT_TYPES: return processors.to_float else: raise exc.InvalidRequestError( "Unknown PG numeric type: %d" % coltype ) class _PsycopgFloat(_PsycopgNumeric): __visit_name__ = "float" class _PsycopgHStore(HSTORE): def bind_processor(self, dialect): if dialect._has_native_hstore: return None else: return super().bind_processor(dialect) def result_processor(self, dialect, coltype): if dialect._has_native_hstore: return None else: return super().result_processor(dialect, coltype) class _PsycopgARRAY(PGARRAY): render_bind_cast = True class _PsycopgINT2VECTOR(_SpaceVector, INT2VECTOR): pass class _PsycopgOIDVECTOR(_SpaceVector, OIDVECTOR): pass class _PGExecutionContext_common_psycopg(PGExecutionContext): def create_server_side_cursor(self): # use server-side cursors: # psycopg # https://www.psycopg.org/psycopg3/docs/advanced/cursors.html#server-side-cursors # psycopg2 # https://www.psycopg.org/docs/usage.html#server-side-cursors ident = "c_%s_%s" % (hex(id(self))[2:], hex(_server_side_id())[2:]) return self._dbapi_connection.cursor(ident) class _PGDialect_common_psycopg(PGDialect): supports_statement_cache = True supports_server_side_cursors = True default_paramstyle = "pyformat" _has_native_hstore = True colspecs = util.update_copy( PGDialect.colspecs, { sqltypes.Numeric: _PsycopgNumeric, sqltypes.Float: _PsycopgFloat, HSTORE: _PsycopgHStore, sqltypes.ARRAY: _PsycopgARRAY, INT2VECTOR: _PsycopgINT2VECTOR, OIDVECTOR: _PsycopgOIDVECTOR, }, ) def __init__( self, client_encoding=None, use_native_hstore=True, **kwargs, ): PGDialect.__init__(self, **kwargs) if not use_native_hstore: self._has_native_hstore = False self.use_native_hstore = use_native_hstore self.client_encoding = client_encoding def create_connect_args(self, url): opts = url.translate_connect_args(username="user", database="dbname") multihosts, multiports = self._split_multihost_from_url(url) if opts or url.query: if not opts: opts = {} if "port" in opts: opts["port"] = int(opts["port"]) opts.update(url.query) if multihosts: opts["host"] = ",".join(multihosts) comma_ports = ",".join(str(p) if p else "" for p in multiports) if comma_ports: opts["port"] = comma_ports return ([], opts) else: # no connection arguments whatsoever; psycopg2.connect() # requires that "dsn" be present as a blank string. return ([""], opts) def get_isolation_level_values(self, dbapi_connection): return ( "AUTOCOMMIT", "READ COMMITTED", "READ UNCOMMITTED", "REPEATABLE READ", "SERIALIZABLE", ) def set_deferrable(self, connection, value): connection.deferrable = value def get_deferrable(self, connection): return connection.deferrable def _do_autocommit(self, connection, value): connection.autocommit = value def do_ping(self, dbapi_connection): before_autocommit = dbapi_connection.autocommit if not before_autocommit: dbapi_connection.autocommit = True cursor = dbapi_connection.cursor() try: cursor.execute(self._dialect_specific_select_one) finally: cursor.close() if not before_autocommit and not dbapi_connection.closed: dbapi_connection.autocommit = before_autocommit return True sqlalchemy/dialects/postgresql/ranges.py 0000755 00000100322 15125143220 0014526 0 ustar 00 # dialects/postgresql/ranges.py # Copyright (C) 2013-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php from __future__ import annotations import dataclasses from datetime import date from datetime import datetime from datetime import timedelta from decimal import Decimal from typing import Any from typing import cast from typing import Generic from typing import List from typing import Optional from typing import overload from typing import Sequence from typing import Tuple from typing import Type from typing import TYPE_CHECKING from typing import TypeVar from typing import Union from .operators import ADJACENT_TO from .operators import CONTAINED_BY from .operators import CONTAINS from .operators import NOT_EXTEND_LEFT_OF from .operators import NOT_EXTEND_RIGHT_OF from .operators import OVERLAP from .operators import STRICTLY_LEFT_OF from .operators import STRICTLY_RIGHT_OF from ... import types as sqltypes from ...sql import operators from ...sql.type_api import TypeEngine from ...util import py310 from ...util.typing import Literal if TYPE_CHECKING: from ...sql.elements import ColumnElement from ...sql.type_api import _TE from ...sql.type_api import TypeEngineMixin _T = TypeVar("_T", bound=Any) _BoundsType = Literal["()", "[)", "(]", "[]"] if py310: dc_slots = {"slots": True} dc_kwonly = {"kw_only": True} else: dc_slots = {} dc_kwonly = {} @dataclasses.dataclass(frozen=True, **dc_slots) class Range(Generic[_T]): """Represent a PostgreSQL range. E.g.:: r = Range(10, 50, bounds="()") The calling style is similar to that of psycopg and psycopg2, in part to allow easier migration from previous SQLAlchemy versions that used these objects directly. :param lower: Lower bound value, or None :param upper: Upper bound value, or None :param bounds: keyword-only, optional string value that is one of ``"()"``, ``"[)"``, ``"(]"``, ``"[]"``. Defaults to ``"[)"``. :param empty: keyword-only, optional bool indicating this is an "empty" range .. versionadded:: 2.0 """ lower: Optional[_T] = None """the lower bound""" upper: Optional[_T] = None """the upper bound""" if TYPE_CHECKING: bounds: _BoundsType = dataclasses.field(default="[)") empty: bool = dataclasses.field(default=False) else: bounds: _BoundsType = dataclasses.field(default="[)", **dc_kwonly) empty: bool = dataclasses.field(default=False, **dc_kwonly) if not py310: def __init__( self, lower: Optional[_T] = None, upper: Optional[_T] = None, *, bounds: _BoundsType = "[)", empty: bool = False, ): # no __slots__ either so we can update dict self.__dict__.update( { "lower": lower, "upper": upper, "bounds": bounds, "empty": empty, } ) def __bool__(self) -> bool: return not self.empty @property def isempty(self) -> bool: "A synonym for the 'empty' attribute." return self.empty @property def is_empty(self) -> bool: "A synonym for the 'empty' attribute." return self.empty @property def lower_inc(self) -> bool: """Return True if the lower bound is inclusive.""" return self.bounds[0] == "[" @property def lower_inf(self) -> bool: """Return True if this range is non-empty and lower bound is infinite.""" return not self.empty and self.lower is None @property def upper_inc(self) -> bool: """Return True if the upper bound is inclusive.""" return self.bounds[1] == "]" @property def upper_inf(self) -> bool: """Return True if this range is non-empty and the upper bound is infinite.""" return not self.empty and self.upper is None @property def __sa_type_engine__(self) -> AbstractSingleRange[_T]: return AbstractSingleRange() def _contains_value(self, value: _T) -> bool: """Return True if this range contains the given value.""" if self.empty: return False if self.lower is None: return self.upper is None or ( value < self.upper if self.bounds[1] == ")" else value <= self.upper ) if self.upper is None: return ( # type: ignore value > self.lower if self.bounds[0] == "(" else value >= self.lower ) return ( # type: ignore value > self.lower if self.bounds[0] == "(" else value >= self.lower ) and ( value < self.upper if self.bounds[1] == ")" else value <= self.upper ) def _get_discrete_step(self) -> Any: "Determine the “step” for this range, if it is a discrete one." # See # https://www.postgresql.org/docs/current/rangetypes.html#RANGETYPES-DISCRETE # for the rationale if isinstance(self.lower, int) or isinstance(self.upper, int): return 1 elif isinstance(self.lower, datetime) or isinstance( self.upper, datetime ): # This is required, because a `isinstance(datetime.now(), date)` # is True return None elif isinstance(self.lower, date) or isinstance(self.upper, date): return timedelta(days=1) else: return None def _compare_edges( self, value1: Optional[_T], bound1: str, value2: Optional[_T], bound2: str, only_values: bool = False, ) -> int: """Compare two range bounds. Return -1, 0 or 1 respectively when `value1` is less than, equal to or greater than `value2`. When `only_value` is ``True``, do not consider the *inclusivity* of the edges, just their values. """ value1_is_lower_bound = bound1 in {"[", "("} value2_is_lower_bound = bound2 in {"[", "("} # Infinite edges are equal when they are on the same side, # otherwise a lower edge is considered less than the upper end if value1 is value2 is None: if value1_is_lower_bound == value2_is_lower_bound: return 0 else: return -1 if value1_is_lower_bound else 1 elif value1 is None: return -1 if value1_is_lower_bound else 1 elif value2 is None: return 1 if value2_is_lower_bound else -1 # Short path for trivial case if bound1 == bound2 and value1 == value2: return 0 value1_inc = bound1 in {"[", "]"} value2_inc = bound2 in {"[", "]"} step = self._get_discrete_step() if step is not None: # "Normalize" the two edges as '[)', to simplify successive # logic when the range is discrete: otherwise we would need # to handle the comparison between ``(0`` and ``[1`` that # are equal when dealing with integers while for floats the # former is lesser than the latter if value1_is_lower_bound: if not value1_inc: value1 += step value1_inc = True else: if value1_inc: value1 += step value1_inc = False if value2_is_lower_bound: if not value2_inc: value2 += step value2_inc = True else: if value2_inc: value2 += step value2_inc = False if value1 < value2: # type: ignore return -1 elif value1 > value2: # type: ignore return 1 elif only_values: return 0 else: # Neither one is infinite but are equal, so we # need to consider the respective inclusive/exclusive # flag if value1_inc and value2_inc: return 0 elif not value1_inc and not value2_inc: if value1_is_lower_bound == value2_is_lower_bound: return 0 else: return 1 if value1_is_lower_bound else -1 elif not value1_inc: return 1 if value1_is_lower_bound else -1 elif not value2_inc: return -1 if value2_is_lower_bound else 1 else: return 0 def __eq__(self, other: Any) -> bool: """Compare this range to the `other` taking into account bounds inclusivity, returning ``True`` if they are equal. """ if not isinstance(other, Range): return NotImplemented if self.empty and other.empty: return True elif self.empty != other.empty: return False slower = self.lower slower_b = self.bounds[0] olower = other.lower olower_b = other.bounds[0] supper = self.upper supper_b = self.bounds[1] oupper = other.upper oupper_b = other.bounds[1] return ( self._compare_edges(slower, slower_b, olower, olower_b) == 0 and self._compare_edges(supper, supper_b, oupper, oupper_b) == 0 ) def contained_by(self, other: Range[_T]) -> bool: "Determine whether this range is a contained by `other`." # Any range contains the empty one if self.empty: return True # An empty range does not contain any range except the empty one if other.empty: return False slower = self.lower slower_b = self.bounds[0] olower = other.lower olower_b = other.bounds[0] if self._compare_edges(slower, slower_b, olower, olower_b) < 0: return False supper = self.upper supper_b = self.bounds[1] oupper = other.upper oupper_b = other.bounds[1] if self._compare_edges(supper, supper_b, oupper, oupper_b) > 0: return False return True def contains(self, value: Union[_T, Range[_T]]) -> bool: "Determine whether this range contains `value`." if isinstance(value, Range): return value.contained_by(self) else: return self._contains_value(value) __contains__ = contains def overlaps(self, other: Range[_T]) -> bool: "Determine whether this range overlaps with `other`." # Empty ranges never overlap with any other range if self.empty or other.empty: return False slower = self.lower slower_b = self.bounds[0] supper = self.upper supper_b = self.bounds[1] olower = other.lower olower_b = other.bounds[0] oupper = other.upper oupper_b = other.bounds[1] # Check whether this lower bound is contained in the other range if ( self._compare_edges(slower, slower_b, olower, olower_b) >= 0 and self._compare_edges(slower, slower_b, oupper, oupper_b) <= 0 ): return True # Check whether other lower bound is contained in this range if ( self._compare_edges(olower, olower_b, slower, slower_b) >= 0 and self._compare_edges(olower, olower_b, supper, supper_b) <= 0 ): return True return False def strictly_left_of(self, other: Range[_T]) -> bool: "Determine whether this range is completely to the left of `other`." # Empty ranges are neither to left nor to the right of any other range if self.empty or other.empty: return False supper = self.upper supper_b = self.bounds[1] olower = other.lower olower_b = other.bounds[0] # Check whether this upper edge is less than other's lower end return self._compare_edges(supper, supper_b, olower, olower_b) < 0 __lshift__ = strictly_left_of def strictly_right_of(self, other: Range[_T]) -> bool: "Determine whether this range is completely to the right of `other`." # Empty ranges are neither to left nor to the right of any other range if self.empty or other.empty: return False slower = self.lower slower_b = self.bounds[0] oupper = other.upper oupper_b = other.bounds[1] # Check whether this lower edge is greater than other's upper end return self._compare_edges(slower, slower_b, oupper, oupper_b) > 0 __rshift__ = strictly_right_of def not_extend_left_of(self, other: Range[_T]) -> bool: "Determine whether this does not extend to the left of `other`." # Empty ranges are neither to left nor to the right of any other range if self.empty or other.empty: return False slower = self.lower slower_b = self.bounds[0] olower = other.lower olower_b = other.bounds[0] # Check whether this lower edge is not less than other's lower end return self._compare_edges(slower, slower_b, olower, olower_b) >= 0 def not_extend_right_of(self, other: Range[_T]) -> bool: "Determine whether this does not extend to the right of `other`." # Empty ranges are neither to left nor to the right of any other range if self.empty or other.empty: return False supper = self.upper supper_b = self.bounds[1] oupper = other.upper oupper_b = other.bounds[1] # Check whether this upper edge is not greater than other's upper end return self._compare_edges(supper, supper_b, oupper, oupper_b) <= 0 def _upper_edge_adjacent_to_lower( self, value1: Optional[_T], bound1: str, value2: Optional[_T], bound2: str, ) -> bool: """Determine whether an upper bound is immediately successive to a lower bound.""" # Since we need a peculiar way to handle the bounds inclusivity, # just do a comparison by value here res = self._compare_edges(value1, bound1, value2, bound2, True) if res == -1: step = self._get_discrete_step() if step is None: return False if bound1 == "]": if bound2 == "[": return value1 == value2 - step # type: ignore else: return value1 == value2 else: if bound2 == "[": return value1 == value2 else: return value1 == value2 - step # type: ignore elif res == 0: # Cover cases like [0,0] -|- [1,] and [0,2) -|- (1,3] if ( bound1 == "]" and bound2 == "[" or bound1 == ")" and bound2 == "(" ): step = self._get_discrete_step() if step is not None: return True return ( bound1 == ")" and bound2 == "[" or bound1 == "]" and bound2 == "(" ) else: return False def adjacent_to(self, other: Range[_T]) -> bool: "Determine whether this range is adjacent to the `other`." # Empty ranges are not adjacent to any other range if self.empty or other.empty: return False slower = self.lower slower_b = self.bounds[0] supper = self.upper supper_b = self.bounds[1] olower = other.lower olower_b = other.bounds[0] oupper = other.upper oupper_b = other.bounds[1] return self._upper_edge_adjacent_to_lower( supper, supper_b, olower, olower_b ) or self._upper_edge_adjacent_to_lower( oupper, oupper_b, slower, slower_b ) def union(self, other: Range[_T]) -> Range[_T]: """Compute the union of this range with the `other`. This raises a ``ValueError`` exception if the two ranges are "disjunct", that is neither adjacent nor overlapping. """ # Empty ranges are "additive identities" if self.empty: return other if other.empty: return self if not self.overlaps(other) and not self.adjacent_to(other): raise ValueError( "Adding non-overlapping and non-adjacent" " ranges is not implemented" ) slower = self.lower slower_b = self.bounds[0] supper = self.upper supper_b = self.bounds[1] olower = other.lower olower_b = other.bounds[0] oupper = other.upper oupper_b = other.bounds[1] if self._compare_edges(slower, slower_b, olower, olower_b) < 0: rlower = slower rlower_b = slower_b else: rlower = olower rlower_b = olower_b if self._compare_edges(supper, supper_b, oupper, oupper_b) > 0: rupper = supper rupper_b = supper_b else: rupper = oupper rupper_b = oupper_b return Range( rlower, rupper, bounds=cast(_BoundsType, rlower_b + rupper_b) ) def __add__(self, other: Range[_T]) -> Range[_T]: return self.union(other) def difference(self, other: Range[_T]) -> Range[_T]: """Compute the difference between this range and the `other`. This raises a ``ValueError`` exception if the two ranges are "disjunct", that is neither adjacent nor overlapping. """ # Subtracting an empty range is a no-op if self.empty or other.empty: return self slower = self.lower slower_b = self.bounds[0] supper = self.upper supper_b = self.bounds[1] olower = other.lower olower_b = other.bounds[0] oupper = other.upper oupper_b = other.bounds[1] sl_vs_ol = self._compare_edges(slower, slower_b, olower, olower_b) su_vs_ou = self._compare_edges(supper, supper_b, oupper, oupper_b) if sl_vs_ol < 0 and su_vs_ou > 0: raise ValueError( "Subtracting a strictly inner range is not implemented" ) sl_vs_ou = self._compare_edges(slower, slower_b, oupper, oupper_b) su_vs_ol = self._compare_edges(supper, supper_b, olower, olower_b) # If the ranges do not overlap, result is simply the first if sl_vs_ou > 0 or su_vs_ol < 0: return self # If this range is completely contained by the other, result is empty if sl_vs_ol >= 0 and su_vs_ou <= 0: return Range(None, None, empty=True) # If this range extends to the left of the other and ends in its # middle if sl_vs_ol <= 0 and su_vs_ol >= 0 and su_vs_ou <= 0: rupper_b = ")" if olower_b == "[" else "]" if ( slower_b != "[" and rupper_b != "]" and self._compare_edges(slower, slower_b, olower, rupper_b) == 0 ): return Range(None, None, empty=True) else: return Range( slower, olower, bounds=cast(_BoundsType, slower_b + rupper_b), ) # If this range starts in the middle of the other and extends to its # right if sl_vs_ol >= 0 and su_vs_ou >= 0 and sl_vs_ou <= 0: rlower_b = "(" if oupper_b == "]" else "[" if ( rlower_b != "[" and supper_b != "]" and self._compare_edges(oupper, rlower_b, supper, supper_b) == 0 ): return Range(None, None, empty=True) else: return Range( oupper, supper, bounds=cast(_BoundsType, rlower_b + supper_b), ) assert False, f"Unhandled case computing {self} - {other}" def __sub__(self, other: Range[_T]) -> Range[_T]: return self.difference(other) def intersection(self, other: Range[_T]) -> Range[_T]: """Compute the intersection of this range with the `other`. .. versionadded:: 2.0.10 """ if self.empty or other.empty or not self.overlaps(other): return Range(None, None, empty=True) slower = self.lower slower_b = self.bounds[0] supper = self.upper supper_b = self.bounds[1] olower = other.lower olower_b = other.bounds[0] oupper = other.upper oupper_b = other.bounds[1] if self._compare_edges(slower, slower_b, olower, olower_b) < 0: rlower = olower rlower_b = olower_b else: rlower = slower rlower_b = slower_b if self._compare_edges(supper, supper_b, oupper, oupper_b) > 0: rupper = oupper rupper_b = oupper_b else: rupper = supper rupper_b = supper_b return Range( rlower, rupper, bounds=cast(_BoundsType, rlower_b + rupper_b), ) def __mul__(self, other: Range[_T]) -> Range[_T]: return self.intersection(other) def __str__(self) -> str: return self._stringify() def _stringify(self) -> str: if self.empty: return "empty" l, r = self.lower, self.upper l = "" if l is None else l # type: ignore r = "" if r is None else r # type: ignore b0, b1 = cast("Tuple[str, str]", self.bounds) return f"{b0}{l},{r}{b1}" class MultiRange(List[Range[_T]]): """Represents a multirange sequence. This list subclass is an utility to allow automatic type inference of the proper multi-range SQL type depending on the single range values. This is useful when operating on literal multi-ranges:: import sqlalchemy as sa from sqlalchemy.dialects.postgresql import MultiRange, Range value = literal(MultiRange([Range(2, 4)])) select(tbl).where(tbl.c.value.op("@")(MultiRange([Range(-3, 7)]))) .. versionadded:: 2.0.26 .. seealso:: - :ref:`postgresql_multirange_list_use`. """ @property def __sa_type_engine__(self) -> AbstractMultiRange[_T]: return AbstractMultiRange() class AbstractRange(sqltypes.TypeEngine[_T]): """Base class for single and multi Range SQL types.""" render_bind_cast = True __abstract__ = True @overload def adapt(self, cls: Type[_TE], **kw: Any) -> _TE: ... @overload def adapt( self, cls: Type[TypeEngineMixin], **kw: Any ) -> TypeEngine[Any]: ... def adapt( self, cls: Type[Union[TypeEngine[Any], TypeEngineMixin]], **kw: Any, ) -> TypeEngine[Any]: """Dynamically adapt a range type to an abstract impl. For example ``INT4RANGE().adapt(_Psycopg2NumericRange)`` should produce a type that will have ``_Psycopg2NumericRange`` behaviors and also render as ``INT4RANGE`` in SQL and DDL. """ if ( issubclass(cls, (AbstractSingleRangeImpl, AbstractMultiRangeImpl)) and cls is not self.__class__ ): # two ways to do this are: 1. create a new type on the fly # or 2. have AbstractRangeImpl(visit_name) constructor and a # visit_abstract_range_impl() method in the PG compiler. # I'm choosing #1 as the resulting type object # will then make use of the same mechanics # as if we had made all these sub-types explicitly, and will # also look more obvious under pdb etc. # The adapt() operation here is cached per type-class-per-dialect, # so is not much of a performance concern visit_name = self.__visit_name__ return type( # type: ignore f"{visit_name}RangeImpl", (cls, self.__class__), {"__visit_name__": visit_name}, )() else: return super().adapt(cls) class comparator_factory(TypeEngine.Comparator[Range[Any]]): """Define comparison operations for range types.""" def contains(self, other: Any, **kw: Any) -> ColumnElement[bool]: """Boolean expression. Returns true if the right hand operand, which can be an element or a range, is contained within the column. kwargs may be ignored by this operator but are required for API conformance. """ return self.expr.operate(CONTAINS, other) def contained_by(self, other: Any) -> ColumnElement[bool]: """Boolean expression. Returns true if the column is contained within the right hand operand. """ return self.expr.operate(CONTAINED_BY, other) def overlaps(self, other: Any) -> ColumnElement[bool]: """Boolean expression. Returns true if the column overlaps (has points in common with) the right hand operand. """ return self.expr.operate(OVERLAP, other) def strictly_left_of(self, other: Any) -> ColumnElement[bool]: """Boolean expression. Returns true if the column is strictly left of the right hand operand. """ return self.expr.operate(STRICTLY_LEFT_OF, other) __lshift__ = strictly_left_of def strictly_right_of(self, other: Any) -> ColumnElement[bool]: """Boolean expression. Returns true if the column is strictly right of the right hand operand. """ return self.expr.operate(STRICTLY_RIGHT_OF, other) __rshift__ = strictly_right_of def not_extend_right_of(self, other: Any) -> ColumnElement[bool]: """Boolean expression. Returns true if the range in the column does not extend right of the range in the operand. """ return self.expr.operate(NOT_EXTEND_RIGHT_OF, other) def not_extend_left_of(self, other: Any) -> ColumnElement[bool]: """Boolean expression. Returns true if the range in the column does not extend left of the range in the operand. """ return self.expr.operate(NOT_EXTEND_LEFT_OF, other) def adjacent_to(self, other: Any) -> ColumnElement[bool]: """Boolean expression. Returns true if the range in the column is adjacent to the range in the operand. """ return self.expr.operate(ADJACENT_TO, other) def union(self, other: Any) -> ColumnElement[bool]: """Range expression. Returns the union of the two ranges. Will raise an exception if the resulting range is not contiguous. """ return self.expr.operate(operators.add, other) def difference(self, other: Any) -> ColumnElement[bool]: """Range expression. Returns the union of the two ranges. Will raise an exception if the resulting range is not contiguous. """ return self.expr.operate(operators.sub, other) def intersection(self, other: Any) -> ColumnElement[Range[_T]]: """Range expression. Returns the intersection of the two ranges. Will raise an exception if the resulting range is not contiguous. """ return self.expr.operate(operators.mul, other) class AbstractSingleRange(AbstractRange[Range[_T]]): """Base for PostgreSQL RANGE types. These are types that return a single :class:`_postgresql.Range` object. .. seealso:: `PostgreSQL range functions <https://www.postgresql.org/docs/current/static/functions-range.html>`_ """ # noqa: E501 __abstract__ = True def _resolve_for_literal(self, value: Range[Any]) -> Any: spec = value.lower if value.lower is not None else value.upper if isinstance(spec, int): # pg is unreasonably picky here: the query # "select 1::INTEGER <@ '[1, 4)'::INT8RANGE" raises # "operator does not exist: integer <@ int8range" as of pg 16 if _is_int32(value): return INT4RANGE() else: return INT8RANGE() elif isinstance(spec, (Decimal, float)): return NUMRANGE() elif isinstance(spec, datetime): return TSRANGE() if not spec.tzinfo else TSTZRANGE() elif isinstance(spec, date): return DATERANGE() else: # empty Range, SQL datatype can't be determined here return sqltypes.NULLTYPE class AbstractSingleRangeImpl(AbstractSingleRange[_T]): """Marker for AbstractSingleRange that will apply a subclass-specific adaptation""" class AbstractMultiRange(AbstractRange[Sequence[Range[_T]]]): """Base for PostgreSQL MULTIRANGE types. these are types that return a sequence of :class:`_postgresql.Range` objects. """ __abstract__ = True def _resolve_for_literal(self, value: Sequence[Range[Any]]) -> Any: if not value: # empty MultiRange, SQL datatype can't be determined here return sqltypes.NULLTYPE first = value[0] spec = first.lower if first.lower is not None else first.upper if isinstance(spec, int): # pg is unreasonably picky here: the query # "select 1::INTEGER <@ '{[1, 4),[6,19)}'::INT8MULTIRANGE" raises # "operator does not exist: integer <@ int8multirange" as of pg 16 if all(_is_int32(r) for r in value): return INT4MULTIRANGE() else: return INT8MULTIRANGE() elif isinstance(spec, (Decimal, float)): return NUMMULTIRANGE() elif isinstance(spec, datetime): return TSMULTIRANGE() if not spec.tzinfo else TSTZMULTIRANGE() elif isinstance(spec, date): return DATEMULTIRANGE() else: # empty Range, SQL datatype can't be determined here return sqltypes.NULLTYPE class AbstractMultiRangeImpl(AbstractMultiRange[_T]): """Marker for AbstractMultiRange that will apply a subclass-specific adaptation""" class INT4RANGE(AbstractSingleRange[int]): """Represent the PostgreSQL INT4RANGE type.""" __visit_name__ = "INT4RANGE" class INT8RANGE(AbstractSingleRange[int]): """Represent the PostgreSQL INT8RANGE type.""" __visit_name__ = "INT8RANGE" class NUMRANGE(AbstractSingleRange[Decimal]): """Represent the PostgreSQL NUMRANGE type.""" __visit_name__ = "NUMRANGE" class DATERANGE(AbstractSingleRange[date]): """Represent the PostgreSQL DATERANGE type.""" __visit_name__ = "DATERANGE" class TSRANGE(AbstractSingleRange[datetime]): """Represent the PostgreSQL TSRANGE type.""" __visit_name__ = "TSRANGE" class TSTZRANGE(AbstractSingleRange[datetime]): """Represent the PostgreSQL TSTZRANGE type.""" __visit_name__ = "TSTZRANGE" class INT4MULTIRANGE(AbstractMultiRange[int]): """Represent the PostgreSQL INT4MULTIRANGE type.""" __visit_name__ = "INT4MULTIRANGE" class INT8MULTIRANGE(AbstractMultiRange[int]): """Represent the PostgreSQL INT8MULTIRANGE type.""" __visit_name__ = "INT8MULTIRANGE" class NUMMULTIRANGE(AbstractMultiRange[Decimal]): """Represent the PostgreSQL NUMMULTIRANGE type.""" __visit_name__ = "NUMMULTIRANGE" class DATEMULTIRANGE(AbstractMultiRange[date]): """Represent the PostgreSQL DATEMULTIRANGE type.""" __visit_name__ = "DATEMULTIRANGE" class TSMULTIRANGE(AbstractMultiRange[datetime]): """Represent the PostgreSQL TSRANGE type.""" __visit_name__ = "TSMULTIRANGE" class TSTZMULTIRANGE(AbstractMultiRange[datetime]): """Represent the PostgreSQL TSTZRANGE type.""" __visit_name__ = "TSTZMULTIRANGE" _max_int_32 = 2**31 - 1 _min_int_32 = -(2**31) def _is_int32(r: Range[int]) -> bool: return (r.lower is None or _min_int_32 <= r.lower <= _max_int_32) and ( r.upper is None or _min_int_32 <= r.upper <= _max_int_32 ) sqlalchemy/dialects/postgresql/pg8000.py 0000755 00000044316 15125143220 0014177 0 ustar 00 # dialects/postgresql/pg8000.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors <see AUTHORS # file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors r""" .. dialect:: postgresql+pg8000 :name: pg8000 :dbapi: pg8000 :connectstring: postgresql+pg8000://user:password@host:port/dbname[?key=value&key=value...] :url: https://pypi.org/project/pg8000/ .. versionchanged:: 1.4 The pg8000 dialect has been updated for version 1.16.6 and higher, and is again part of SQLAlchemy's continuous integration with full feature support. .. _pg8000_unicode: Unicode ------- pg8000 will encode / decode string values between it and the server using the PostgreSQL ``client_encoding`` parameter; by default this is the value in the ``postgresql.conf`` file, which often defaults to ``SQL_ASCII``. Typically, this can be changed to ``utf-8``, as a more useful default:: # client_encoding = sql_ascii # actually, defaults to database encoding client_encoding = utf8 The ``client_encoding`` can be overridden for a session by executing the SQL: .. sourcecode:: sql SET CLIENT_ENCODING TO 'utf8'; SQLAlchemy will execute this SQL on all new connections based on the value passed to :func:`_sa.create_engine` using the ``client_encoding`` parameter:: engine = create_engine( "postgresql+pg8000://user:pass@host/dbname", client_encoding="utf8" ) .. _pg8000_ssl: SSL Connections --------------- pg8000 accepts a Python ``SSLContext`` object which may be specified using the :paramref:`_sa.create_engine.connect_args` dictionary:: import ssl ssl_context = ssl.create_default_context() engine = sa.create_engine( "postgresql+pg8000://scott:tiger@192.168.0.199/test", connect_args={"ssl_context": ssl_context}, ) If the server uses an automatically-generated certificate that is self-signed or does not match the host name (as seen from the client), it may also be necessary to disable hostname checking:: import ssl ssl_context = ssl.create_default_context() ssl_context.check_hostname = False ssl_context.verify_mode = ssl.CERT_NONE engine = sa.create_engine( "postgresql+pg8000://scott:tiger@192.168.0.199/test", connect_args={"ssl_context": ssl_context}, ) .. _pg8000_isolation_level: pg8000 Transaction Isolation Level ------------------------------------- The pg8000 dialect offers the same isolation level settings as that of the :ref:`psycopg2 <psycopg2_isolation_level>` dialect: * ``READ COMMITTED`` * ``READ UNCOMMITTED`` * ``REPEATABLE READ`` * ``SERIALIZABLE`` * ``AUTOCOMMIT`` .. seealso:: :ref:`postgresql_isolation_level` :ref:`psycopg2_isolation_level` """ # noqa import decimal import re from . import ranges from .array import ARRAY as PGARRAY from .base import _DECIMAL_TYPES from .base import _FLOAT_TYPES from .base import _INT_TYPES from .base import ENUM from .base import INTERVAL from .base import PGCompiler from .base import PGDialect from .base import PGExecutionContext from .base import PGIdentifierPreparer from .json import JSON from .json import JSONB from .json import JSONPathType from .pg_catalog import _SpaceVector from .pg_catalog import OIDVECTOR from .types import CITEXT from ... import exc from ... import util from ...engine import processors from ...sql import sqltypes from ...sql.elements import quoted_name class _PGString(sqltypes.String): render_bind_cast = True class _PGNumeric(sqltypes.Numeric): render_bind_cast = True def result_processor(self, dialect, coltype): if self.asdecimal: if coltype in _FLOAT_TYPES: return processors.to_decimal_processor_factory( decimal.Decimal, self._effective_decimal_return_scale ) elif coltype in _DECIMAL_TYPES or coltype in _INT_TYPES: # pg8000 returns Decimal natively for 1700 return None else: raise exc.InvalidRequestError( "Unknown PG numeric type: %d" % coltype ) else: if coltype in _FLOAT_TYPES: # pg8000 returns float natively for 701 return None elif coltype in _DECIMAL_TYPES or coltype in _INT_TYPES: return processors.to_float else: raise exc.InvalidRequestError( "Unknown PG numeric type: %d" % coltype ) class _PGFloat(_PGNumeric, sqltypes.Float): __visit_name__ = "float" render_bind_cast = True class _PGNumericNoBind(_PGNumeric): def bind_processor(self, dialect): return None class _PGJSON(JSON): render_bind_cast = True def result_processor(self, dialect, coltype): return None class _PGJSONB(JSONB): render_bind_cast = True def result_processor(self, dialect, coltype): return None class _PGJSONIndexType(sqltypes.JSON.JSONIndexType): def get_dbapi_type(self, dbapi): raise NotImplementedError("should not be here") class _PGJSONIntIndexType(sqltypes.JSON.JSONIntIndexType): __visit_name__ = "json_int_index" render_bind_cast = True class _PGJSONStrIndexType(sqltypes.JSON.JSONStrIndexType): __visit_name__ = "json_str_index" render_bind_cast = True class _PGJSONPathType(JSONPathType): pass # DBAPI type 1009 class _PGEnum(ENUM): def get_dbapi_type(self, dbapi): return dbapi.UNKNOWN class _PGInterval(INTERVAL): render_bind_cast = True def get_dbapi_type(self, dbapi): return dbapi.INTERVAL @classmethod def adapt_emulated_to_native(cls, interval, **kw): return _PGInterval(precision=interval.second_precision) class _PGTimeStamp(sqltypes.DateTime): render_bind_cast = True class _PGDate(sqltypes.Date): render_bind_cast = True class _PGTime(sqltypes.Time): render_bind_cast = True class _PGInteger(sqltypes.Integer): render_bind_cast = True class _PGSmallInteger(sqltypes.SmallInteger): render_bind_cast = True class _PGNullType(sqltypes.NullType): pass class _PGBigInteger(sqltypes.BigInteger): render_bind_cast = True class _PGBoolean(sqltypes.Boolean): render_bind_cast = True class _PGARRAY(PGARRAY): render_bind_cast = True class _PGOIDVECTOR(_SpaceVector, OIDVECTOR): pass class _Pg8000Range(ranges.AbstractSingleRangeImpl): def bind_processor(self, dialect): pg8000_Range = dialect.dbapi.Range def to_range(value): if isinstance(value, ranges.Range): value = pg8000_Range( value.lower, value.upper, value.bounds, value.empty ) return value return to_range def result_processor(self, dialect, coltype): def to_range(value): if value is not None: value = ranges.Range( value.lower, value.upper, bounds=value.bounds, empty=value.is_empty, ) return value return to_range class _Pg8000MultiRange(ranges.AbstractMultiRangeImpl): def bind_processor(self, dialect): pg8000_Range = dialect.dbapi.Range def to_multirange(value): if isinstance(value, list): mr = [] for v in value: if isinstance(v, ranges.Range): mr.append( pg8000_Range(v.lower, v.upper, v.bounds, v.empty) ) else: mr.append(v) return mr else: return value return to_multirange def result_processor(self, dialect, coltype): def to_multirange(value): if value is None: return None else: return ranges.MultiRange( ranges.Range( v.lower, v.upper, bounds=v.bounds, empty=v.is_empty ) for v in value ) return to_multirange _server_side_id = util.counter() class PGExecutionContext_pg8000(PGExecutionContext): def create_server_side_cursor(self): ident = "c_%s_%s" % (hex(id(self))[2:], hex(_server_side_id())[2:]) return ServerSideCursor(self._dbapi_connection.cursor(), ident) def pre_exec(self): if not self.compiled: return class ServerSideCursor: server_side = True def __init__(self, cursor, ident): self.ident = ident self.cursor = cursor @property def connection(self): return self.cursor.connection @property def rowcount(self): return self.cursor.rowcount @property def description(self): return self.cursor.description def execute(self, operation, args=(), stream=None): op = "DECLARE " + self.ident + " NO SCROLL CURSOR FOR " + operation self.cursor.execute(op, args, stream=stream) return self def executemany(self, operation, param_sets): self.cursor.executemany(operation, param_sets) return self def fetchone(self): self.cursor.execute("FETCH FORWARD 1 FROM " + self.ident) return self.cursor.fetchone() def fetchmany(self, num=None): if num is None: return self.fetchall() else: self.cursor.execute( "FETCH FORWARD " + str(int(num)) + " FROM " + self.ident ) return self.cursor.fetchall() def fetchall(self): self.cursor.execute("FETCH FORWARD ALL FROM " + self.ident) return self.cursor.fetchall() def close(self): self.cursor.execute("CLOSE " + self.ident) self.cursor.close() def setinputsizes(self, *sizes): self.cursor.setinputsizes(*sizes) def setoutputsize(self, size, column=None): pass class PGCompiler_pg8000(PGCompiler): def visit_mod_binary(self, binary, operator, **kw): return ( self.process(binary.left, **kw) + " %% " + self.process(binary.right, **kw) ) class PGIdentifierPreparer_pg8000(PGIdentifierPreparer): def __init__(self, *args, **kwargs): PGIdentifierPreparer.__init__(self, *args, **kwargs) self._double_percents = False class PGDialect_pg8000(PGDialect): driver = "pg8000" supports_statement_cache = True supports_unicode_statements = True supports_unicode_binds = True default_paramstyle = "format" supports_sane_multi_rowcount = True execution_ctx_cls = PGExecutionContext_pg8000 statement_compiler = PGCompiler_pg8000 preparer = PGIdentifierPreparer_pg8000 supports_server_side_cursors = True render_bind_cast = True # reversed as of pg8000 1.16.6. 1.16.5 and lower # are no longer compatible description_encoding = None # description_encoding = "use_encoding" colspecs = util.update_copy( PGDialect.colspecs, { sqltypes.String: _PGString, sqltypes.Numeric: _PGNumericNoBind, sqltypes.Float: _PGFloat, sqltypes.JSON: _PGJSON, sqltypes.Boolean: _PGBoolean, sqltypes.NullType: _PGNullType, JSONB: _PGJSONB, CITEXT: CITEXT, sqltypes.JSON.JSONPathType: _PGJSONPathType, sqltypes.JSON.JSONIndexType: _PGJSONIndexType, sqltypes.JSON.JSONIntIndexType: _PGJSONIntIndexType, sqltypes.JSON.JSONStrIndexType: _PGJSONStrIndexType, sqltypes.Interval: _PGInterval, INTERVAL: _PGInterval, sqltypes.DateTime: _PGTimeStamp, sqltypes.DateTime: _PGTimeStamp, sqltypes.Date: _PGDate, sqltypes.Time: _PGTime, sqltypes.Integer: _PGInteger, sqltypes.SmallInteger: _PGSmallInteger, sqltypes.BigInteger: _PGBigInteger, sqltypes.Enum: _PGEnum, sqltypes.ARRAY: _PGARRAY, OIDVECTOR: _PGOIDVECTOR, ranges.INT4RANGE: _Pg8000Range, ranges.INT8RANGE: _Pg8000Range, ranges.NUMRANGE: _Pg8000Range, ranges.DATERANGE: _Pg8000Range, ranges.TSRANGE: _Pg8000Range, ranges.TSTZRANGE: _Pg8000Range, ranges.INT4MULTIRANGE: _Pg8000MultiRange, ranges.INT8MULTIRANGE: _Pg8000MultiRange, ranges.NUMMULTIRANGE: _Pg8000MultiRange, ranges.DATEMULTIRANGE: _Pg8000MultiRange, ranges.TSMULTIRANGE: _Pg8000MultiRange, ranges.TSTZMULTIRANGE: _Pg8000MultiRange, }, ) def __init__(self, client_encoding=None, **kwargs): PGDialect.__init__(self, **kwargs) self.client_encoding = client_encoding if self._dbapi_version < (1, 16, 6): raise NotImplementedError("pg8000 1.16.6 or greater is required") if self._native_inet_types: raise NotImplementedError( "The pg8000 dialect does not fully implement " "ipaddress type handling; INET is supported by default, " "CIDR is not" ) @util.memoized_property def _dbapi_version(self): if self.dbapi and hasattr(self.dbapi, "__version__"): return tuple( [ int(x) for x in re.findall( r"(\d+)(?:[-\.]?|$)", self.dbapi.__version__ ) ] ) else: return (99, 99, 99) @classmethod def import_dbapi(cls): return __import__("pg8000") def create_connect_args(self, url): opts = url.translate_connect_args(username="user") if "port" in opts: opts["port"] = int(opts["port"]) opts.update(url.query) return ([], opts) def is_disconnect(self, e, connection, cursor): if isinstance(e, self.dbapi.InterfaceError) and "network error" in str( e ): # new as of pg8000 1.19.0 for broken connections return True # connection was closed normally return "connection is closed" in str(e) def get_isolation_level_values(self, dbapi_connection): return ( "AUTOCOMMIT", "READ COMMITTED", "READ UNCOMMITTED", "REPEATABLE READ", "SERIALIZABLE", ) def set_isolation_level(self, dbapi_connection, level): level = level.replace("_", " ") if level == "AUTOCOMMIT": dbapi_connection.autocommit = True else: dbapi_connection.autocommit = False cursor = dbapi_connection.cursor() cursor.execute( "SET SESSION CHARACTERISTICS AS TRANSACTION " f"ISOLATION LEVEL {level}" ) cursor.execute("COMMIT") cursor.close() def set_readonly(self, connection, value): cursor = connection.cursor() try: cursor.execute( "SET SESSION CHARACTERISTICS AS TRANSACTION %s" % ("READ ONLY" if value else "READ WRITE") ) cursor.execute("COMMIT") finally: cursor.close() def get_readonly(self, connection): cursor = connection.cursor() try: cursor.execute("show transaction_read_only") val = cursor.fetchone()[0] finally: cursor.close() return val == "on" def set_deferrable(self, connection, value): cursor = connection.cursor() try: cursor.execute( "SET SESSION CHARACTERISTICS AS TRANSACTION %s" % ("DEFERRABLE" if value else "NOT DEFERRABLE") ) cursor.execute("COMMIT") finally: cursor.close() def get_deferrable(self, connection): cursor = connection.cursor() try: cursor.execute("show transaction_deferrable") val = cursor.fetchone()[0] finally: cursor.close() return val == "on" def _set_client_encoding(self, dbapi_connection, client_encoding): cursor = dbapi_connection.cursor() cursor.execute( f"""SET CLIENT_ENCODING TO '{ client_encoding.replace("'", "''") }'""" ) cursor.execute("COMMIT") cursor.close() def do_begin_twophase(self, connection, xid): connection.connection.tpc_begin((0, xid, "")) def do_prepare_twophase(self, connection, xid): connection.connection.tpc_prepare() def do_rollback_twophase( self, connection, xid, is_prepared=True, recover=False ): connection.connection.tpc_rollback((0, xid, "")) def do_commit_twophase( self, connection, xid, is_prepared=True, recover=False ): connection.connection.tpc_commit((0, xid, "")) def do_recover_twophase(self, connection): return [row[1] for row in connection.connection.tpc_recover()] def on_connect(self): fns = [] def on_connect(conn): conn.py_types[quoted_name] = conn.py_types[str] fns.append(on_connect) if self.client_encoding is not None: def on_connect(conn): self._set_client_encoding(conn, self.client_encoding) fns.append(on_connect) if self._native_inet_types is False: def on_connect(conn): # inet conn.register_in_adapter(869, lambda s: s) # cidr conn.register_in_adapter(650, lambda s: s) fns.append(on_connect) if self._json_deserializer: def on_connect(conn): # json conn.register_in_adapter(114, self._json_deserializer) # jsonb conn.register_in_adapter(3802, self._json_deserializer) fns.append(on_connect) if len(fns) > 0: def on_connect(conn): for fn in fns: fn(conn) return on_connect else: return None @util.memoized_property def _dialect_specific_select_one(self): return ";" dialect = PGDialect_pg8000 sqlalchemy/dialects/postgresql/psycopg.py 0000755 00000055436 15125143220 0014752 0 ustar 00 # dialects/postgresql/psycopg.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors r""" .. dialect:: postgresql+psycopg :name: psycopg (a.k.a. psycopg 3) :dbapi: psycopg :connectstring: postgresql+psycopg://user:password@host:port/dbname[?key=value&key=value...] :url: https://pypi.org/project/psycopg/ ``psycopg`` is the package and module name for version 3 of the ``psycopg`` database driver, formerly known as ``psycopg2``. This driver is different enough from its ``psycopg2`` predecessor that SQLAlchemy supports it via a totally separate dialect; support for ``psycopg2`` is expected to remain for as long as that package continues to function for modern Python versions, and also remains the default dialect for the ``postgresql://`` dialect series. The SQLAlchemy ``psycopg`` dialect provides both a sync and an async implementation under the same dialect name. The proper version is selected depending on how the engine is created: * calling :func:`_sa.create_engine` with ``postgresql+psycopg://...`` will automatically select the sync version, e.g.:: from sqlalchemy import create_engine sync_engine = create_engine( "postgresql+psycopg://scott:tiger@localhost/test" ) * calling :func:`_asyncio.create_async_engine` with ``postgresql+psycopg://...`` will automatically select the async version, e.g.:: from sqlalchemy.ext.asyncio import create_async_engine asyncio_engine = create_async_engine( "postgresql+psycopg://scott:tiger@localhost/test" ) The asyncio version of the dialect may also be specified explicitly using the ``psycopg_async`` suffix, as:: from sqlalchemy.ext.asyncio import create_async_engine asyncio_engine = create_async_engine( "postgresql+psycopg_async://scott:tiger@localhost/test" ) .. seealso:: :ref:`postgresql_psycopg2` - The SQLAlchemy ``psycopg`` dialect shares most of its behavior with the ``psycopg2`` dialect. Further documentation is available there. Using a different Cursor class ------------------------------ One of the differences between ``psycopg`` and the older ``psycopg2`` is how bound parameters are handled: ``psycopg2`` would bind them client side, while ``psycopg`` by default will bind them server side. It's possible to configure ``psycopg`` to do client side binding by specifying the ``cursor_factory`` to be ``ClientCursor`` when creating the engine:: from psycopg import ClientCursor client_side_engine = create_engine( "postgresql+psycopg://...", connect_args={"cursor_factory": ClientCursor}, ) Similarly when using an async engine the ``AsyncClientCursor`` can be specified:: from psycopg import AsyncClientCursor client_side_engine = create_async_engine( "postgresql+psycopg://...", connect_args={"cursor_factory": AsyncClientCursor}, ) .. seealso:: `Client-side-binding cursors <https://www.psycopg.org/psycopg3/docs/advanced/cursors.html#client-side-binding-cursors>`_ """ # noqa from __future__ import annotations from collections import deque import logging import re from typing import cast from typing import TYPE_CHECKING from . import ranges from ._psycopg_common import _PGDialect_common_psycopg from ._psycopg_common import _PGExecutionContext_common_psycopg from .base import INTERVAL from .base import PGCompiler from .base import PGIdentifierPreparer from .base import REGCONFIG from .json import JSON from .json import JSONB from .json import JSONPathType from .types import CITEXT from ... import pool from ... import util from ...engine import AdaptedConnection from ...sql import sqltypes from ...util.concurrency import await_fallback from ...util.concurrency import await_only if TYPE_CHECKING: from typing import Iterable from psycopg import AsyncConnection logger = logging.getLogger("sqlalchemy.dialects.postgresql") class _PGString(sqltypes.String): render_bind_cast = True class _PGREGCONFIG(REGCONFIG): render_bind_cast = True class _PGJSON(JSON): def bind_processor(self, dialect): return self._make_bind_processor(None, dialect._psycopg_Json) def result_processor(self, dialect, coltype): return None class _PGJSONB(JSONB): def bind_processor(self, dialect): return self._make_bind_processor(None, dialect._psycopg_Jsonb) def result_processor(self, dialect, coltype): return None class _PGJSONIntIndexType(sqltypes.JSON.JSONIntIndexType): __visit_name__ = "json_int_index" render_bind_cast = True class _PGJSONStrIndexType(sqltypes.JSON.JSONStrIndexType): __visit_name__ = "json_str_index" render_bind_cast = True class _PGJSONPathType(JSONPathType): pass class _PGInterval(INTERVAL): render_bind_cast = True class _PGTimeStamp(sqltypes.DateTime): render_bind_cast = True class _PGDate(sqltypes.Date): render_bind_cast = True class _PGTime(sqltypes.Time): render_bind_cast = True class _PGInteger(sqltypes.Integer): render_bind_cast = True class _PGSmallInteger(sqltypes.SmallInteger): render_bind_cast = True class _PGNullType(sqltypes.NullType): render_bind_cast = True class _PGBigInteger(sqltypes.BigInteger): render_bind_cast = True class _PGBoolean(sqltypes.Boolean): render_bind_cast = True class _PsycopgRange(ranges.AbstractSingleRangeImpl): def bind_processor(self, dialect): psycopg_Range = cast(PGDialect_psycopg, dialect)._psycopg_Range def to_range(value): if isinstance(value, ranges.Range): value = psycopg_Range( value.lower, value.upper, value.bounds, value.empty ) return value return to_range def result_processor(self, dialect, coltype): def to_range(value): if value is not None: value = ranges.Range( value._lower, value._upper, bounds=value._bounds if value._bounds else "[)", empty=not value._bounds, ) return value return to_range class _PsycopgMultiRange(ranges.AbstractMultiRangeImpl): def bind_processor(self, dialect): psycopg_Range = cast(PGDialect_psycopg, dialect)._psycopg_Range psycopg_Multirange = cast( PGDialect_psycopg, dialect )._psycopg_Multirange NoneType = type(None) def to_range(value): if isinstance(value, (str, NoneType, psycopg_Multirange)): return value return psycopg_Multirange( [ psycopg_Range( element.lower, element.upper, element.bounds, element.empty, ) for element in cast("Iterable[ranges.Range]", value) ] ) return to_range def result_processor(self, dialect, coltype): def to_range(value): if value is None: return None else: return ranges.MultiRange( ranges.Range( elem._lower, elem._upper, bounds=elem._bounds if elem._bounds else "[)", empty=not elem._bounds, ) for elem in value ) return to_range class PGExecutionContext_psycopg(_PGExecutionContext_common_psycopg): pass class PGCompiler_psycopg(PGCompiler): pass class PGIdentifierPreparer_psycopg(PGIdentifierPreparer): pass def _log_notices(diagnostic): logger.info("%s: %s", diagnostic.severity, diagnostic.message_primary) class PGDialect_psycopg(_PGDialect_common_psycopg): driver = "psycopg" supports_statement_cache = True supports_server_side_cursors = True default_paramstyle = "pyformat" supports_sane_multi_rowcount = True execution_ctx_cls = PGExecutionContext_psycopg statement_compiler = PGCompiler_psycopg preparer = PGIdentifierPreparer_psycopg psycopg_version = (0, 0) _has_native_hstore = True _psycopg_adapters_map = None colspecs = util.update_copy( _PGDialect_common_psycopg.colspecs, { sqltypes.String: _PGString, REGCONFIG: _PGREGCONFIG, JSON: _PGJSON, CITEXT: CITEXT, sqltypes.JSON: _PGJSON, JSONB: _PGJSONB, sqltypes.JSON.JSONPathType: _PGJSONPathType, sqltypes.JSON.JSONIntIndexType: _PGJSONIntIndexType, sqltypes.JSON.JSONStrIndexType: _PGJSONStrIndexType, sqltypes.Interval: _PGInterval, INTERVAL: _PGInterval, sqltypes.Date: _PGDate, sqltypes.DateTime: _PGTimeStamp, sqltypes.Time: _PGTime, sqltypes.Integer: _PGInteger, sqltypes.SmallInteger: _PGSmallInteger, sqltypes.BigInteger: _PGBigInteger, ranges.AbstractSingleRange: _PsycopgRange, ranges.AbstractMultiRange: _PsycopgMultiRange, }, ) def __init__(self, **kwargs): super().__init__(**kwargs) if self.dbapi: m = re.match(r"(\d+)\.(\d+)(?:\.(\d+))?", self.dbapi.__version__) if m: self.psycopg_version = tuple( int(x) for x in m.group(1, 2, 3) if x is not None ) if self.psycopg_version < (3, 0, 2): raise ImportError( "psycopg version 3.0.2 or higher is required." ) from psycopg.adapt import AdaptersMap self._psycopg_adapters_map = adapters_map = AdaptersMap( self.dbapi.adapters ) if self._native_inet_types is False: import psycopg.types.string adapters_map.register_loader( "inet", psycopg.types.string.TextLoader ) adapters_map.register_loader( "cidr", psycopg.types.string.TextLoader ) if self._json_deserializer: from psycopg.types.json import set_json_loads set_json_loads(self._json_deserializer, adapters_map) if self._json_serializer: from psycopg.types.json import set_json_dumps set_json_dumps(self._json_serializer, adapters_map) def create_connect_args(self, url): # see https://github.com/psycopg/psycopg/issues/83 cargs, cparams = super().create_connect_args(url) if self._psycopg_adapters_map: cparams["context"] = self._psycopg_adapters_map if self.client_encoding is not None: cparams["client_encoding"] = self.client_encoding return cargs, cparams def _type_info_fetch(self, connection, name): from psycopg.types import TypeInfo return TypeInfo.fetch(connection.connection.driver_connection, name) def initialize(self, connection): super().initialize(connection) # PGDialect.initialize() checks server version for <= 8.2 and sets # this flag to False if so if not self.insert_returning: self.insert_executemany_returning = False # HSTORE can't be registered until we have a connection so that # we can look up its OID, so we set up this adapter in # initialize() if self.use_native_hstore: info = self._type_info_fetch(connection, "hstore") self._has_native_hstore = info is not None if self._has_native_hstore: from psycopg.types.hstore import register_hstore # register the adapter for connections made subsequent to # this one assert self._psycopg_adapters_map register_hstore(info, self._psycopg_adapters_map) # register the adapter for this connection assert connection.connection register_hstore(info, connection.connection.driver_connection) @classmethod def import_dbapi(cls): import psycopg return psycopg @classmethod def get_async_dialect_cls(cls, url): return PGDialectAsync_psycopg @util.memoized_property def _isolation_lookup(self): return { "READ COMMITTED": self.dbapi.IsolationLevel.READ_COMMITTED, "READ UNCOMMITTED": self.dbapi.IsolationLevel.READ_UNCOMMITTED, "REPEATABLE READ": self.dbapi.IsolationLevel.REPEATABLE_READ, "SERIALIZABLE": self.dbapi.IsolationLevel.SERIALIZABLE, } @util.memoized_property def _psycopg_Json(self): from psycopg.types import json return json.Json @util.memoized_property def _psycopg_Jsonb(self): from psycopg.types import json return json.Jsonb @util.memoized_property def _psycopg_TransactionStatus(self): from psycopg.pq import TransactionStatus return TransactionStatus @util.memoized_property def _psycopg_Range(self): from psycopg.types.range import Range return Range @util.memoized_property def _psycopg_Multirange(self): from psycopg.types.multirange import Multirange return Multirange def _do_isolation_level(self, connection, autocommit, isolation_level): connection.autocommit = autocommit connection.isolation_level = isolation_level def get_isolation_level(self, dbapi_connection): status_before = dbapi_connection.info.transaction_status value = super().get_isolation_level(dbapi_connection) # don't rely on psycopg providing enum symbols, compare with # eq/ne if status_before == self._psycopg_TransactionStatus.IDLE: dbapi_connection.rollback() return value def set_isolation_level(self, dbapi_connection, level): if level == "AUTOCOMMIT": self._do_isolation_level( dbapi_connection, autocommit=True, isolation_level=None ) else: self._do_isolation_level( dbapi_connection, autocommit=False, isolation_level=self._isolation_lookup[level], ) def set_readonly(self, connection, value): connection.read_only = value def get_readonly(self, connection): return connection.read_only def on_connect(self): def notices(conn): conn.add_notice_handler(_log_notices) fns = [notices] if self.isolation_level is not None: def on_connect(conn): self.set_isolation_level(conn, self.isolation_level) fns.append(on_connect) # fns always has the notices function def on_connect(conn): for fn in fns: fn(conn) return on_connect def is_disconnect(self, e, connection, cursor): if isinstance(e, self.dbapi.Error) and connection is not None: if connection.closed or connection.broken: return True return False def _do_prepared_twophase(self, connection, command, recover=False): dbapi_conn = connection.connection.dbapi_connection if ( recover # don't rely on psycopg providing enum symbols, compare with # eq/ne or dbapi_conn.info.transaction_status != self._psycopg_TransactionStatus.IDLE ): dbapi_conn.rollback() before_autocommit = dbapi_conn.autocommit try: if not before_autocommit: self._do_autocommit(dbapi_conn, True) dbapi_conn.execute(command) finally: if not before_autocommit: self._do_autocommit(dbapi_conn, before_autocommit) def do_rollback_twophase( self, connection, xid, is_prepared=True, recover=False ): if is_prepared: self._do_prepared_twophase( connection, f"ROLLBACK PREPARED '{xid}'", recover=recover ) else: self.do_rollback(connection.connection) def do_commit_twophase( self, connection, xid, is_prepared=True, recover=False ): if is_prepared: self._do_prepared_twophase( connection, f"COMMIT PREPARED '{xid}'", recover=recover ) else: self.do_commit(connection.connection) @util.memoized_property def _dialect_specific_select_one(self): return ";" class AsyncAdapt_psycopg_cursor: __slots__ = ("_cursor", "await_", "_rows") _psycopg_ExecStatus = None def __init__(self, cursor, await_) -> None: self._cursor = cursor self.await_ = await_ self._rows = deque() def __getattr__(self, name): return getattr(self._cursor, name) @property def arraysize(self): return self._cursor.arraysize @arraysize.setter def arraysize(self, value): self._cursor.arraysize = value def close(self): self._rows.clear() # Normal cursor just call _close() in a non-sync way. self._cursor._close() def execute(self, query, params=None, **kw): result = self.await_(self._cursor.execute(query, params, **kw)) # sqlalchemy result is not async, so need to pull all rows here res = self._cursor.pgresult # don't rely on psycopg providing enum symbols, compare with # eq/ne if res and res.status == self._psycopg_ExecStatus.TUPLES_OK: rows = self.await_(self._cursor.fetchall()) self._rows = deque(rows) return result def executemany(self, query, params_seq): return self.await_(self._cursor.executemany(query, params_seq)) def __iter__(self): while self._rows: yield self._rows.popleft() def fetchone(self): if self._rows: return self._rows.popleft() else: return None def fetchmany(self, size=None): if size is None: size = self._cursor.arraysize rr = self._rows return [rr.popleft() for _ in range(min(size, len(rr)))] def fetchall(self): retval = list(self._rows) self._rows.clear() return retval class AsyncAdapt_psycopg_ss_cursor(AsyncAdapt_psycopg_cursor): def execute(self, query, params=None, **kw): self.await_(self._cursor.execute(query, params, **kw)) return self def close(self): self.await_(self._cursor.close()) def fetchone(self): return self.await_(self._cursor.fetchone()) def fetchmany(self, size=0): return self.await_(self._cursor.fetchmany(size)) def fetchall(self): return self.await_(self._cursor.fetchall()) def __iter__(self): iterator = self._cursor.__aiter__() while True: try: yield self.await_(iterator.__anext__()) except StopAsyncIteration: break class AsyncAdapt_psycopg_connection(AdaptedConnection): _connection: AsyncConnection __slots__ = () await_ = staticmethod(await_only) def __init__(self, connection) -> None: self._connection = connection def __getattr__(self, name): return getattr(self._connection, name) def execute(self, query, params=None, **kw): cursor = self.await_(self._connection.execute(query, params, **kw)) return AsyncAdapt_psycopg_cursor(cursor, self.await_) def cursor(self, *args, **kw): cursor = self._connection.cursor(*args, **kw) if hasattr(cursor, "name"): return AsyncAdapt_psycopg_ss_cursor(cursor, self.await_) else: return AsyncAdapt_psycopg_cursor(cursor, self.await_) def commit(self): self.await_(self._connection.commit()) def rollback(self): self.await_(self._connection.rollback()) def close(self): self.await_(self._connection.close()) @property def autocommit(self): return self._connection.autocommit @autocommit.setter def autocommit(self, value): self.set_autocommit(value) def set_autocommit(self, value): self.await_(self._connection.set_autocommit(value)) def set_isolation_level(self, value): self.await_(self._connection.set_isolation_level(value)) def set_read_only(self, value): self.await_(self._connection.set_read_only(value)) def set_deferrable(self, value): self.await_(self._connection.set_deferrable(value)) class AsyncAdaptFallback_psycopg_connection(AsyncAdapt_psycopg_connection): __slots__ = () await_ = staticmethod(await_fallback) class PsycopgAdaptDBAPI: def __init__(self, psycopg) -> None: self.psycopg = psycopg for k, v in self.psycopg.__dict__.items(): if k != "connect": self.__dict__[k] = v def connect(self, *arg, **kw): async_fallback = kw.pop("async_fallback", False) creator_fn = kw.pop( "async_creator_fn", self.psycopg.AsyncConnection.connect ) if util.asbool(async_fallback): return AsyncAdaptFallback_psycopg_connection( await_fallback(creator_fn(*arg, **kw)) ) else: return AsyncAdapt_psycopg_connection( await_only(creator_fn(*arg, **kw)) ) class PGDialectAsync_psycopg(PGDialect_psycopg): is_async = True supports_statement_cache = True @classmethod def import_dbapi(cls): import psycopg from psycopg.pq import ExecStatus AsyncAdapt_psycopg_cursor._psycopg_ExecStatus = ExecStatus return PsycopgAdaptDBAPI(psycopg) @classmethod def get_pool_class(cls, url): async_fallback = url.query.get("async_fallback", False) if util.asbool(async_fallback): return pool.FallbackAsyncAdaptedQueuePool else: return pool.AsyncAdaptedQueuePool def _type_info_fetch(self, connection, name): from psycopg.types import TypeInfo adapted = connection.connection return adapted.await_(TypeInfo.fetch(adapted.driver_connection, name)) def _do_isolation_level(self, connection, autocommit, isolation_level): connection.set_autocommit(autocommit) connection.set_isolation_level(isolation_level) def _do_autocommit(self, connection, value): connection.set_autocommit(value) def set_readonly(self, connection, value): connection.set_read_only(value) def set_deferrable(self, connection, value): connection.set_deferrable(value) def get_driver_connection(self, connection): return connection._connection dialect = PGDialect_psycopg dialect_async = PGDialectAsync_psycopg sqlalchemy/dialects/postgresql/ext.py 0000755 00000041703 15125143220 0014056 0 ustar 00 # dialects/postgresql/ext.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors from __future__ import annotations from typing import Any from typing import Iterable from typing import List from typing import Optional from typing import overload from typing import TYPE_CHECKING from typing import TypeVar from . import types from .array import ARRAY from ...sql import coercions from ...sql import elements from ...sql import expression from ...sql import functions from ...sql import roles from ...sql import schema from ...sql.schema import ColumnCollectionConstraint from ...sql.sqltypes import TEXT from ...sql.visitors import InternalTraversal if TYPE_CHECKING: from ...sql._typing import _ColumnExpressionArgument from ...sql.elements import ClauseElement from ...sql.elements import ColumnElement from ...sql.operators import OperatorType from ...sql.selectable import FromClause from ...sql.visitors import _CloneCallableType from ...sql.visitors import _TraverseInternalsType _T = TypeVar("_T", bound=Any) class aggregate_order_by(expression.ColumnElement[_T]): """Represent a PostgreSQL aggregate order by expression. E.g.:: from sqlalchemy.dialects.postgresql import aggregate_order_by expr = func.array_agg(aggregate_order_by(table.c.a, table.c.b.desc())) stmt = select(expr) would represent the expression: .. sourcecode:: sql SELECT array_agg(a ORDER BY b DESC) FROM table; Similarly:: expr = func.string_agg( table.c.a, aggregate_order_by(literal_column("','"), table.c.a) ) stmt = select(expr) Would represent: .. sourcecode:: sql SELECT string_agg(a, ',' ORDER BY a) FROM table; .. versionchanged:: 1.2.13 - the ORDER BY argument may be multiple terms .. seealso:: :class:`_functions.array_agg` """ __visit_name__ = "aggregate_order_by" stringify_dialect = "postgresql" _traverse_internals: _TraverseInternalsType = [ ("target", InternalTraversal.dp_clauseelement), ("type", InternalTraversal.dp_type), ("order_by", InternalTraversal.dp_clauseelement), ] @overload def __init__( self, target: ColumnElement[_T], *order_by: _ColumnExpressionArgument[Any], ): ... @overload def __init__( self, target: _ColumnExpressionArgument[_T], *order_by: _ColumnExpressionArgument[Any], ): ... def __init__( self, target: _ColumnExpressionArgument[_T], *order_by: _ColumnExpressionArgument[Any], ): self.target: ClauseElement = coercions.expect( roles.ExpressionElementRole, target ) self.type = self.target.type _lob = len(order_by) self.order_by: ClauseElement if _lob == 0: raise TypeError("at least one ORDER BY element is required") elif _lob == 1: self.order_by = coercions.expect( roles.ExpressionElementRole, order_by[0] ) else: self.order_by = elements.ClauseList( *order_by, _literal_as_text_role=roles.ExpressionElementRole ) def self_group( self, against: Optional[OperatorType] = None ) -> ClauseElement: return self def get_children(self, **kwargs: Any) -> Iterable[ClauseElement]: return self.target, self.order_by def _copy_internals( self, clone: _CloneCallableType = elements._clone, **kw: Any ) -> None: self.target = clone(self.target, **kw) self.order_by = clone(self.order_by, **kw) @property def _from_objects(self) -> List[FromClause]: return self.target._from_objects + self.order_by._from_objects class ExcludeConstraint(ColumnCollectionConstraint): """A table-level EXCLUDE constraint. Defines an EXCLUDE constraint as described in the `PostgreSQL documentation`__. __ https://www.postgresql.org/docs/current/static/sql-createtable.html#SQL-CREATETABLE-EXCLUDE """ # noqa __visit_name__ = "exclude_constraint" where = None inherit_cache = False create_drop_stringify_dialect = "postgresql" @elements._document_text_coercion( "where", ":class:`.ExcludeConstraint`", ":paramref:`.ExcludeConstraint.where`", ) def __init__(self, *elements, **kw): r""" Create an :class:`.ExcludeConstraint` object. E.g.:: const = ExcludeConstraint( (Column("period"), "&&"), (Column("group"), "="), where=(Column("group") != "some group"), ops={"group": "my_operator_class"}, ) The constraint is normally embedded into the :class:`_schema.Table` construct directly, or added later using :meth:`.append_constraint`:: some_table = Table( "some_table", metadata, Column("id", Integer, primary_key=True), Column("period", TSRANGE()), Column("group", String), ) some_table.append_constraint( ExcludeConstraint( (some_table.c.period, "&&"), (some_table.c.group, "="), where=some_table.c.group != "some group", name="some_table_excl_const", ops={"group": "my_operator_class"}, ) ) The exclude constraint defined in this example requires the ``btree_gist`` extension, that can be created using the command ``CREATE EXTENSION btree_gist;``. :param \*elements: A sequence of two tuples of the form ``(column, operator)`` where "column" is either a :class:`_schema.Column` object, or a SQL expression element (e.g. ``func.int8range(table.from, table.to)``) or the name of a column as string, and "operator" is a string containing the operator to use (e.g. `"&&"` or `"="`). In order to specify a column name when a :class:`_schema.Column` object is not available, while ensuring that any necessary quoting rules take effect, an ad-hoc :class:`_schema.Column` or :func:`_expression.column` object should be used. The ``column`` may also be a string SQL expression when passed as :func:`_expression.literal_column` or :func:`_expression.text` :param name: Optional, the in-database name of this constraint. :param deferrable: Optional bool. If set, emit DEFERRABLE or NOT DEFERRABLE when issuing DDL for this constraint. :param initially: Optional string. If set, emit INITIALLY <value> when issuing DDL for this constraint. :param using: Optional string. If set, emit USING <index_method> when issuing DDL for this constraint. Defaults to 'gist'. :param where: Optional SQL expression construct or literal SQL string. If set, emit WHERE <predicate> when issuing DDL for this constraint. :param ops: Optional dictionary. Used to define operator classes for the elements; works the same way as that of the :ref:`postgresql_ops <postgresql_operator_classes>` parameter specified to the :class:`_schema.Index` construct. .. versionadded:: 1.3.21 .. seealso:: :ref:`postgresql_operator_classes` - general description of how PostgreSQL operator classes are specified. """ columns = [] render_exprs = [] self.operators = {} expressions, operators = zip(*elements) for (expr, column, strname, add_element), operator in zip( coercions.expect_col_expression_collection( roles.DDLConstraintColumnRole, expressions ), operators, ): if add_element is not None: columns.append(add_element) name = column.name if column is not None else strname if name is not None: # backwards compat self.operators[name] = operator render_exprs.append((expr, name, operator)) self._render_exprs = render_exprs ColumnCollectionConstraint.__init__( self, *columns, name=kw.get("name"), deferrable=kw.get("deferrable"), initially=kw.get("initially"), ) self.using = kw.get("using", "gist") where = kw.get("where") if where is not None: self.where = coercions.expect(roles.StatementOptionRole, where) self.ops = kw.get("ops", {}) def _set_parent(self, table, **kw): super()._set_parent(table) self._render_exprs = [ ( expr if not isinstance(expr, str) else table.c[expr], name, operator, ) for expr, name, operator in (self._render_exprs) ] def _copy(self, target_table=None, **kw): elements = [ ( schema._copy_expression(expr, self.parent, target_table), operator, ) for expr, _, operator in self._render_exprs ] c = self.__class__( *elements, name=self.name, deferrable=self.deferrable, initially=self.initially, where=self.where, using=self.using, ) c.dispatch._update(self.dispatch) return c def array_agg(*arg, **kw): """PostgreSQL-specific form of :class:`_functions.array_agg`, ensures return type is :class:`_postgresql.ARRAY` and not the plain :class:`_types.ARRAY`, unless an explicit ``type_`` is passed. """ kw["_default_array_type"] = ARRAY return functions.func.array_agg(*arg, **kw) class _regconfig_fn(functions.GenericFunction[_T]): inherit_cache = True def __init__(self, *args, **kwargs): args = list(args) if len(args) > 1: initial_arg = coercions.expect( roles.ExpressionElementRole, args.pop(0), name=getattr(self, "name", None), apply_propagate_attrs=self, type_=types.REGCONFIG, ) initial_arg = [initial_arg] else: initial_arg = [] addtl_args = [ coercions.expect( roles.ExpressionElementRole, c, name=getattr(self, "name", None), apply_propagate_attrs=self, ) for c in args ] super().__init__(*(initial_arg + addtl_args), **kwargs) class to_tsvector(_regconfig_fn): """The PostgreSQL ``to_tsvector`` SQL function. This function applies automatic casting of the REGCONFIG argument to use the :class:`_postgresql.REGCONFIG` datatype automatically, and applies a return type of :class:`_postgresql.TSVECTOR`. Assuming the PostgreSQL dialect has been imported, either by invoking ``from sqlalchemy.dialects import postgresql``, or by creating a PostgreSQL engine using ``create_engine("postgresql...")``, :class:`_postgresql.to_tsvector` will be used automatically when invoking ``sqlalchemy.func.to_tsvector()``, ensuring the correct argument and return type handlers are used at compile and execution time. .. versionadded:: 2.0.0rc1 """ inherit_cache = True type = types.TSVECTOR class to_tsquery(_regconfig_fn): """The PostgreSQL ``to_tsquery`` SQL function. This function applies automatic casting of the REGCONFIG argument to use the :class:`_postgresql.REGCONFIG` datatype automatically, and applies a return type of :class:`_postgresql.TSQUERY`. Assuming the PostgreSQL dialect has been imported, either by invoking ``from sqlalchemy.dialects import postgresql``, or by creating a PostgreSQL engine using ``create_engine("postgresql...")``, :class:`_postgresql.to_tsquery` will be used automatically when invoking ``sqlalchemy.func.to_tsquery()``, ensuring the correct argument and return type handlers are used at compile and execution time. .. versionadded:: 2.0.0rc1 """ inherit_cache = True type = types.TSQUERY class plainto_tsquery(_regconfig_fn): """The PostgreSQL ``plainto_tsquery`` SQL function. This function applies automatic casting of the REGCONFIG argument to use the :class:`_postgresql.REGCONFIG` datatype automatically, and applies a return type of :class:`_postgresql.TSQUERY`. Assuming the PostgreSQL dialect has been imported, either by invoking ``from sqlalchemy.dialects import postgresql``, or by creating a PostgreSQL engine using ``create_engine("postgresql...")``, :class:`_postgresql.plainto_tsquery` will be used automatically when invoking ``sqlalchemy.func.plainto_tsquery()``, ensuring the correct argument and return type handlers are used at compile and execution time. .. versionadded:: 2.0.0rc1 """ inherit_cache = True type = types.TSQUERY class phraseto_tsquery(_regconfig_fn): """The PostgreSQL ``phraseto_tsquery`` SQL function. This function applies automatic casting of the REGCONFIG argument to use the :class:`_postgresql.REGCONFIG` datatype automatically, and applies a return type of :class:`_postgresql.TSQUERY`. Assuming the PostgreSQL dialect has been imported, either by invoking ``from sqlalchemy.dialects import postgresql``, or by creating a PostgreSQL engine using ``create_engine("postgresql...")``, :class:`_postgresql.phraseto_tsquery` will be used automatically when invoking ``sqlalchemy.func.phraseto_tsquery()``, ensuring the correct argument and return type handlers are used at compile and execution time. .. versionadded:: 2.0.0rc1 """ inherit_cache = True type = types.TSQUERY class websearch_to_tsquery(_regconfig_fn): """The PostgreSQL ``websearch_to_tsquery`` SQL function. This function applies automatic casting of the REGCONFIG argument to use the :class:`_postgresql.REGCONFIG` datatype automatically, and applies a return type of :class:`_postgresql.TSQUERY`. Assuming the PostgreSQL dialect has been imported, either by invoking ``from sqlalchemy.dialects import postgresql``, or by creating a PostgreSQL engine using ``create_engine("postgresql...")``, :class:`_postgresql.websearch_to_tsquery` will be used automatically when invoking ``sqlalchemy.func.websearch_to_tsquery()``, ensuring the correct argument and return type handlers are used at compile and execution time. .. versionadded:: 2.0.0rc1 """ inherit_cache = True type = types.TSQUERY class ts_headline(_regconfig_fn): """The PostgreSQL ``ts_headline`` SQL function. This function applies automatic casting of the REGCONFIG argument to use the :class:`_postgresql.REGCONFIG` datatype automatically, and applies a return type of :class:`_types.TEXT`. Assuming the PostgreSQL dialect has been imported, either by invoking ``from sqlalchemy.dialects import postgresql``, or by creating a PostgreSQL engine using ``create_engine("postgresql...")``, :class:`_postgresql.ts_headline` will be used automatically when invoking ``sqlalchemy.func.ts_headline()``, ensuring the correct argument and return type handlers are used at compile and execution time. .. versionadded:: 2.0.0rc1 """ inherit_cache = True type = TEXT def __init__(self, *args, **kwargs): args = list(args) # parse types according to # https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-HEADLINE if len(args) < 2: # invalid args; don't do anything has_regconfig = False elif ( isinstance(args[1], elements.ColumnElement) and args[1].type._type_affinity is types.TSQUERY ): # tsquery is second argument, no regconfig argument has_regconfig = False else: has_regconfig = True if has_regconfig: initial_arg = coercions.expect( roles.ExpressionElementRole, args.pop(0), apply_propagate_attrs=self, name=getattr(self, "name", None), type_=types.REGCONFIG, ) initial_arg = [initial_arg] else: initial_arg = [] addtl_args = [ coercions.expect( roles.ExpressionElementRole, c, name=getattr(self, "name", None), apply_propagate_attrs=self, ) for c in args ] super().__init__(*(initial_arg + addtl_args), **kwargs) sqlalchemy/dialects/postgresql/dml.py 0000755 00000027536 15125143220 0014042 0 ustar 00 # dialects/postgresql/dml.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php from __future__ import annotations from typing import Any from typing import List from typing import Optional from typing import Tuple from typing import Union from . import ext from .._typing import _OnConflictConstraintT from .._typing import _OnConflictIndexElementsT from .._typing import _OnConflictIndexWhereT from .._typing import _OnConflictSetT from .._typing import _OnConflictWhereT from ... import util from ...sql import coercions from ...sql import roles from ...sql import schema from ...sql._typing import _DMLTableArgument from ...sql.base import _exclusive_against from ...sql.base import _generative from ...sql.base import ColumnCollection from ...sql.base import ReadOnlyColumnCollection from ...sql.dml import Insert as StandardInsert from ...sql.elements import ClauseElement from ...sql.elements import ColumnElement from ...sql.elements import KeyedColumnElement from ...sql.elements import TextClause from ...sql.expression import alias from ...util.typing import Self __all__ = ("Insert", "insert") def insert(table: _DMLTableArgument) -> Insert: """Construct a PostgreSQL-specific variant :class:`_postgresql.Insert` construct. .. container:: inherited_member The :func:`sqlalchemy.dialects.postgresql.insert` function creates a :class:`sqlalchemy.dialects.postgresql.Insert`. This class is based on the dialect-agnostic :class:`_sql.Insert` construct which may be constructed using the :func:`_sql.insert` function in SQLAlchemy Core. The :class:`_postgresql.Insert` construct includes additional methods :meth:`_postgresql.Insert.on_conflict_do_update`, :meth:`_postgresql.Insert.on_conflict_do_nothing`. """ return Insert(table) class Insert(StandardInsert): """PostgreSQL-specific implementation of INSERT. Adds methods for PG-specific syntaxes such as ON CONFLICT. The :class:`_postgresql.Insert` object is created using the :func:`sqlalchemy.dialects.postgresql.insert` function. """ stringify_dialect = "postgresql" inherit_cache = False @util.memoized_property def excluded( self, ) -> ReadOnlyColumnCollection[str, KeyedColumnElement[Any]]: """Provide the ``excluded`` namespace for an ON CONFLICT statement PG's ON CONFLICT clause allows reference to the row that would be inserted, known as ``excluded``. This attribute provides all columns in this row to be referenceable. .. tip:: The :attr:`_postgresql.Insert.excluded` attribute is an instance of :class:`_expression.ColumnCollection`, which provides an interface the same as that of the :attr:`_schema.Table.c` collection described at :ref:`metadata_tables_and_columns`. With this collection, ordinary names are accessible like attributes (e.g. ``stmt.excluded.some_column``), but special names and dictionary method names should be accessed using indexed access, such as ``stmt.excluded["column name"]`` or ``stmt.excluded["values"]``. See the docstring for :class:`_expression.ColumnCollection` for further examples. .. seealso:: :ref:`postgresql_insert_on_conflict` - example of how to use :attr:`_expression.Insert.excluded` """ return alias(self.table, name="excluded").columns _on_conflict_exclusive = _exclusive_against( "_post_values_clause", msgs={ "_post_values_clause": "This Insert construct already has " "an ON CONFLICT clause established" }, ) @_generative @_on_conflict_exclusive def on_conflict_do_update( self, constraint: _OnConflictConstraintT = None, index_elements: _OnConflictIndexElementsT = None, index_where: _OnConflictIndexWhereT = None, set_: _OnConflictSetT = None, where: _OnConflictWhereT = None, ) -> Self: r""" Specifies a DO UPDATE SET action for ON CONFLICT clause. Either the ``constraint`` or ``index_elements`` argument is required, but only one of these can be specified. :param constraint: The name of a unique or exclusion constraint on the table, or the constraint object itself if it has a .name attribute. :param index_elements: A sequence consisting of string column names, :class:`_schema.Column` objects, or other column expression objects that will be used to infer a target index. :param index_where: Additional WHERE criterion that can be used to infer a conditional target index. :param set\_: A dictionary or other mapping object where the keys are either names of columns in the target table, or :class:`_schema.Column` objects or other ORM-mapped columns matching that of the target table, and expressions or literals as values, specifying the ``SET`` actions to take. .. versionadded:: 1.4 The :paramref:`_postgresql.Insert.on_conflict_do_update.set_` parameter supports :class:`_schema.Column` objects from the target :class:`_schema.Table` as keys. .. warning:: This dictionary does **not** take into account Python-specified default UPDATE values or generation functions, e.g. those specified using :paramref:`_schema.Column.onupdate`. These values will not be exercised for an ON CONFLICT style of UPDATE, unless they are manually specified in the :paramref:`.Insert.on_conflict_do_update.set_` dictionary. :param where: Optional argument. An expression object representing a ``WHERE`` clause that restricts the rows affected by ``DO UPDATE SET``. Rows not meeting the ``WHERE`` condition will not be updated (effectively a ``DO NOTHING`` for those rows). .. seealso:: :ref:`postgresql_insert_on_conflict` """ self._post_values_clause = OnConflictDoUpdate( constraint, index_elements, index_where, set_, where ) return self @_generative @_on_conflict_exclusive def on_conflict_do_nothing( self, constraint: _OnConflictConstraintT = None, index_elements: _OnConflictIndexElementsT = None, index_where: _OnConflictIndexWhereT = None, ) -> Self: """ Specifies a DO NOTHING action for ON CONFLICT clause. The ``constraint`` and ``index_elements`` arguments are optional, but only one of these can be specified. :param constraint: The name of a unique or exclusion constraint on the table, or the constraint object itself if it has a .name attribute. :param index_elements: A sequence consisting of string column names, :class:`_schema.Column` objects, or other column expression objects that will be used to infer a target index. :param index_where: Additional WHERE criterion that can be used to infer a conditional target index. .. seealso:: :ref:`postgresql_insert_on_conflict` """ self._post_values_clause = OnConflictDoNothing( constraint, index_elements, index_where ) return self class OnConflictClause(ClauseElement): stringify_dialect = "postgresql" constraint_target: Optional[str] inferred_target_elements: Optional[List[Union[str, schema.Column[Any]]]] inferred_target_whereclause: Optional[ Union[ColumnElement[Any], TextClause] ] def __init__( self, constraint: _OnConflictConstraintT = None, index_elements: _OnConflictIndexElementsT = None, index_where: _OnConflictIndexWhereT = None, ): if constraint is not None: if not isinstance(constraint, str) and isinstance( constraint, (schema.Constraint, ext.ExcludeConstraint), ): constraint = getattr(constraint, "name") or constraint if constraint is not None: if index_elements is not None: raise ValueError( "'constraint' and 'index_elements' are mutually exclusive" ) if isinstance(constraint, str): self.constraint_target = constraint self.inferred_target_elements = None self.inferred_target_whereclause = None elif isinstance(constraint, schema.Index): index_elements = constraint.expressions index_where = constraint.dialect_options["postgresql"].get( "where" ) elif isinstance(constraint, ext.ExcludeConstraint): index_elements = constraint.columns index_where = constraint.where else: index_elements = constraint.columns index_where = constraint.dialect_options["postgresql"].get( "where" ) if index_elements is not None: self.constraint_target = None self.inferred_target_elements = [ coercions.expect(roles.DDLConstraintColumnRole, column) for column in index_elements ] self.inferred_target_whereclause = ( coercions.expect( ( roles.StatementOptionRole if isinstance(constraint, ext.ExcludeConstraint) else roles.WhereHavingRole ), index_where, ) if index_where is not None else None ) elif constraint is None: self.constraint_target = self.inferred_target_elements = ( self.inferred_target_whereclause ) = None class OnConflictDoNothing(OnConflictClause): __visit_name__ = "on_conflict_do_nothing" class OnConflictDoUpdate(OnConflictClause): __visit_name__ = "on_conflict_do_update" update_values_to_set: List[Tuple[Union[schema.Column[Any], str], Any]] update_whereclause: Optional[ColumnElement[Any]] def __init__( self, constraint: _OnConflictConstraintT = None, index_elements: _OnConflictIndexElementsT = None, index_where: _OnConflictIndexWhereT = None, set_: _OnConflictSetT = None, where: _OnConflictWhereT = None, ): super().__init__( constraint=constraint, index_elements=index_elements, index_where=index_where, ) if ( self.inferred_target_elements is None and self.constraint_target is None ): raise ValueError( "Either constraint or index_elements, " "but not both, must be specified unless DO NOTHING" ) if isinstance(set_, dict): if not set_: raise ValueError("set parameter dictionary must not be empty") elif isinstance(set_, ColumnCollection): set_ = dict(set_) else: raise ValueError( "set parameter must be a non-empty dictionary " "or a ColumnCollection such as the `.c.` collection " "of a Table object" ) self.update_values_to_set = [ (coercions.expect(roles.DMLColumnRole, key), value) for key, value in set_.items() ] self.update_whereclause = ( coercions.expect(roles.WhereHavingRole, where) if where is not None else None ) sqlalchemy/dialects/postgresql/named_types.py 0000755 00000043550 15125143220 0015570 0 ustar 00 # dialects/postgresql/named_types.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors from __future__ import annotations from types import ModuleType from typing import Any from typing import Dict from typing import Optional from typing import Type from typing import TYPE_CHECKING from typing import Union from ... import schema from ... import util from ...sql import coercions from ...sql import elements from ...sql import roles from ...sql import sqltypes from ...sql import type_api from ...sql.base import _NoArg from ...sql.ddl import InvokeCreateDDLBase from ...sql.ddl import InvokeDropDDLBase if TYPE_CHECKING: from ...sql._typing import _CreateDropBind from ...sql._typing import _TypeEngineArgument class NamedType(schema.SchemaVisitable, sqltypes.TypeEngine): """Base for named types.""" __abstract__ = True DDLGenerator: Type[NamedTypeGenerator] DDLDropper: Type[NamedTypeDropper] create_type: bool def create( self, bind: _CreateDropBind, checkfirst: bool = True, **kw: Any ) -> None: """Emit ``CREATE`` DDL for this type. :param bind: a connectable :class:`_engine.Engine`, :class:`_engine.Connection`, or similar object to emit SQL. :param checkfirst: if ``True``, a query against the PG catalog will be first performed to see if the type does not exist already before creating. """ bind._run_ddl_visitor(self.DDLGenerator, self, checkfirst=checkfirst) def drop( self, bind: _CreateDropBind, checkfirst: bool = True, **kw: Any ) -> None: """Emit ``DROP`` DDL for this type. :param bind: a connectable :class:`_engine.Engine`, :class:`_engine.Connection`, or similar object to emit SQL. :param checkfirst: if ``True``, a query against the PG catalog will be first performed to see if the type actually exists before dropping. """ bind._run_ddl_visitor(self.DDLDropper, self, checkfirst=checkfirst) def _check_for_name_in_memos( self, checkfirst: bool, kw: Dict[str, Any] ) -> bool: """Look in the 'ddl runner' for 'memos', then note our name in that collection. This to ensure a particular named type is operated upon only once within any kind of create/drop sequence without relying upon "checkfirst". """ if not self.create_type: return True if "_ddl_runner" in kw: ddl_runner = kw["_ddl_runner"] type_name = f"pg_{self.__visit_name__}" if type_name in ddl_runner.memo: existing = ddl_runner.memo[type_name] else: existing = ddl_runner.memo[type_name] = set() present = (self.schema, self.name) in existing existing.add((self.schema, self.name)) return present else: return False def _on_table_create( self, target: Any, bind: _CreateDropBind, checkfirst: bool = False, **kw: Any, ) -> None: if ( checkfirst or ( not self.metadata and not kw.get("_is_metadata_operation", False) ) ) and not self._check_for_name_in_memos(checkfirst, kw): self.create(bind=bind, checkfirst=checkfirst) def _on_table_drop( self, target: Any, bind: _CreateDropBind, checkfirst: bool = False, **kw: Any, ) -> None: if ( not self.metadata and not kw.get("_is_metadata_operation", False) and not self._check_for_name_in_memos(checkfirst, kw) ): self.drop(bind=bind, checkfirst=checkfirst) def _on_metadata_create( self, target: Any, bind: _CreateDropBind, checkfirst: bool = False, **kw: Any, ) -> None: if not self._check_for_name_in_memos(checkfirst, kw): self.create(bind=bind, checkfirst=checkfirst) def _on_metadata_drop( self, target: Any, bind: _CreateDropBind, checkfirst: bool = False, **kw: Any, ) -> None: if not self._check_for_name_in_memos(checkfirst, kw): self.drop(bind=bind, checkfirst=checkfirst) class NamedTypeGenerator(InvokeCreateDDLBase): def __init__(self, dialect, connection, checkfirst=False, **kwargs): super().__init__(connection, **kwargs) self.checkfirst = checkfirst def _can_create_type(self, type_): if not self.checkfirst: return True effective_schema = self.connection.schema_for_object(type_) return not self.connection.dialect.has_type( self.connection, type_.name, schema=effective_schema ) class NamedTypeDropper(InvokeDropDDLBase): def __init__(self, dialect, connection, checkfirst=False, **kwargs): super().__init__(connection, **kwargs) self.checkfirst = checkfirst def _can_drop_type(self, type_): if not self.checkfirst: return True effective_schema = self.connection.schema_for_object(type_) return self.connection.dialect.has_type( self.connection, type_.name, schema=effective_schema ) class EnumGenerator(NamedTypeGenerator): def visit_enum(self, enum): if not self._can_create_type(enum): return with self.with_ddl_events(enum): self.connection.execute(CreateEnumType(enum)) class EnumDropper(NamedTypeDropper): def visit_enum(self, enum): if not self._can_drop_type(enum): return with self.with_ddl_events(enum): self.connection.execute(DropEnumType(enum)) class ENUM(NamedType, type_api.NativeForEmulated, sqltypes.Enum): """PostgreSQL ENUM type. This is a subclass of :class:`_types.Enum` which includes support for PG's ``CREATE TYPE`` and ``DROP TYPE``. When the builtin type :class:`_types.Enum` is used and the :paramref:`.Enum.native_enum` flag is left at its default of True, the PostgreSQL backend will use a :class:`_postgresql.ENUM` type as the implementation, so the special create/drop rules will be used. The create/drop behavior of ENUM is necessarily intricate, due to the awkward relationship the ENUM type has in relationship to the parent table, in that it may be "owned" by just a single table, or may be shared among many tables. When using :class:`_types.Enum` or :class:`_postgresql.ENUM` in an "inline" fashion, the ``CREATE TYPE`` and ``DROP TYPE`` is emitted corresponding to when the :meth:`_schema.Table.create` and :meth:`_schema.Table.drop` methods are called:: table = Table( "sometable", metadata, Column("some_enum", ENUM("a", "b", "c", name="myenum")), ) table.create(engine) # will emit CREATE ENUM and CREATE TABLE table.drop(engine) # will emit DROP TABLE and DROP ENUM To use a common enumerated type between multiple tables, the best practice is to declare the :class:`_types.Enum` or :class:`_postgresql.ENUM` independently, and associate it with the :class:`_schema.MetaData` object itself:: my_enum = ENUM("a", "b", "c", name="myenum", metadata=metadata) t1 = Table("sometable_one", metadata, Column("some_enum", myenum)) t2 = Table("sometable_two", metadata, Column("some_enum", myenum)) When this pattern is used, care must still be taken at the level of individual table creates. Emitting CREATE TABLE without also specifying ``checkfirst=True`` will still cause issues:: t1.create(engine) # will fail: no such type 'myenum' If we specify ``checkfirst=True``, the individual table-level create operation will check for the ``ENUM`` and create if not exists:: # will check if enum exists, and emit CREATE TYPE if not t1.create(engine, checkfirst=True) When using a metadata-level ENUM type, the type will always be created and dropped if either the metadata-wide create/drop is called:: metadata.create_all(engine) # will emit CREATE TYPE metadata.drop_all(engine) # will emit DROP TYPE The type can also be created and dropped directly:: my_enum.create(engine) my_enum.drop(engine) """ native_enum = True DDLGenerator = EnumGenerator DDLDropper = EnumDropper def __init__( self, *enums, name: Union[str, _NoArg, None] = _NoArg.NO_ARG, create_type: bool = True, **kw, ): """Construct an :class:`_postgresql.ENUM`. Arguments are the same as that of :class:`_types.Enum`, but also including the following parameters. :param create_type: Defaults to True. Indicates that ``CREATE TYPE`` should be emitted, after optionally checking for the presence of the type, when the parent table is being created; and additionally that ``DROP TYPE`` is called when the table is dropped. When ``False``, no check will be performed and no ``CREATE TYPE`` or ``DROP TYPE`` is emitted, unless :meth:`~.postgresql.ENUM.create` or :meth:`~.postgresql.ENUM.drop` are called directly. Setting to ``False`` is helpful when invoking a creation scheme to a SQL file without access to the actual database - the :meth:`~.postgresql.ENUM.create` and :meth:`~.postgresql.ENUM.drop` methods can be used to emit SQL to a target bind. """ native_enum = kw.pop("native_enum", None) if native_enum is False: util.warn( "the native_enum flag does not apply to the " "sqlalchemy.dialects.postgresql.ENUM datatype; this type " "always refers to ENUM. Use sqlalchemy.types.Enum for " "non-native enum." ) self.create_type = create_type if name is not _NoArg.NO_ARG: kw["name"] = name super().__init__(*enums, **kw) def coerce_compared_value(self, op, value): super_coerced_type = super().coerce_compared_value(op, value) if ( super_coerced_type._type_affinity is type_api.STRINGTYPE._type_affinity ): return self else: return super_coerced_type @classmethod def __test_init__(cls): return cls(name="name") @classmethod def adapt_emulated_to_native(cls, impl, **kw): """Produce a PostgreSQL native :class:`_postgresql.ENUM` from plain :class:`.Enum`. """ kw.setdefault("validate_strings", impl.validate_strings) kw.setdefault("name", impl.name) kw.setdefault("schema", impl.schema) kw.setdefault("inherit_schema", impl.inherit_schema) kw.setdefault("metadata", impl.metadata) kw.setdefault("_create_events", False) kw.setdefault("values_callable", impl.values_callable) kw.setdefault("omit_aliases", impl._omit_aliases) kw.setdefault("_adapted_from", impl) if type_api._is_native_for_emulated(impl.__class__): kw.setdefault("create_type", impl.create_type) return cls(**kw) def create(self, bind: _CreateDropBind, checkfirst: bool = True) -> None: """Emit ``CREATE TYPE`` for this :class:`_postgresql.ENUM`. If the underlying dialect does not support PostgreSQL CREATE TYPE, no action is taken. :param bind: a connectable :class:`_engine.Engine`, :class:`_engine.Connection`, or similar object to emit SQL. :param checkfirst: if ``True``, a query against the PG catalog will be first performed to see if the type does not exist already before creating. """ if not bind.dialect.supports_native_enum: return super().create(bind, checkfirst=checkfirst) def drop(self, bind: _CreateDropBind, checkfirst: bool = True) -> None: """Emit ``DROP TYPE`` for this :class:`_postgresql.ENUM`. If the underlying dialect does not support PostgreSQL DROP TYPE, no action is taken. :param bind: a connectable :class:`_engine.Engine`, :class:`_engine.Connection`, or similar object to emit SQL. :param checkfirst: if ``True``, a query against the PG catalog will be first performed to see if the type actually exists before dropping. """ if not bind.dialect.supports_native_enum: return super().drop(bind, checkfirst=checkfirst) def get_dbapi_type(self, dbapi: ModuleType) -> None: """dont return dbapi.STRING for ENUM in PostgreSQL, since that's a different type""" return None class DomainGenerator(NamedTypeGenerator): def visit_DOMAIN(self, domain): if not self._can_create_type(domain): return with self.with_ddl_events(domain): self.connection.execute(CreateDomainType(domain)) class DomainDropper(NamedTypeDropper): def visit_DOMAIN(self, domain): if not self._can_drop_type(domain): return with self.with_ddl_events(domain): self.connection.execute(DropDomainType(domain)) class DOMAIN(NamedType, sqltypes.SchemaType): r"""Represent the DOMAIN PostgreSQL type. A domain is essentially a data type with optional constraints that restrict the allowed set of values. E.g.:: PositiveInt = DOMAIN("pos_int", Integer, check="VALUE > 0", not_null=True) UsPostalCode = DOMAIN( "us_postal_code", Text, check="VALUE ~ '^\d{5}$' OR VALUE ~ '^\d{5}-\d{4}$'", ) See the `PostgreSQL documentation`__ for additional details __ https://www.postgresql.org/docs/current/sql-createdomain.html .. versionadded:: 2.0 """ # noqa: E501 DDLGenerator = DomainGenerator DDLDropper = DomainDropper __visit_name__ = "DOMAIN" def __init__( self, name: str, data_type: _TypeEngineArgument[Any], *, collation: Optional[str] = None, default: Union[elements.TextClause, str, None] = None, constraint_name: Optional[str] = None, not_null: Optional[bool] = None, check: Union[elements.TextClause, str, None] = None, create_type: bool = True, **kw: Any, ): """ Construct a DOMAIN. :param name: the name of the domain :param data_type: The underlying data type of the domain. This can include array specifiers. :param collation: An optional collation for the domain. If no collation is specified, the underlying data type's default collation is used. The underlying type must be collatable if ``collation`` is specified. :param default: The DEFAULT clause specifies a default value for columns of the domain data type. The default should be a string or a :func:`_expression.text` value. If no default value is specified, then the default value is the null value. :param constraint_name: An optional name for a constraint. If not specified, the backend generates a name. :param not_null: Values of this domain are prevented from being null. By default domain are allowed to be null. If not specified no nullability clause will be emitted. :param check: CHECK clause specify integrity constraint or test which values of the domain must satisfy. A constraint must be an expression producing a Boolean result that can use the key word VALUE to refer to the value being tested. Differently from PostgreSQL, only a single check clause is currently allowed in SQLAlchemy. :param schema: optional schema name :param metadata: optional :class:`_schema.MetaData` object which this :class:`_postgresql.DOMAIN` will be directly associated :param create_type: Defaults to True. Indicates that ``CREATE TYPE`` should be emitted, after optionally checking for the presence of the type, when the parent table is being created; and additionally that ``DROP TYPE`` is called when the table is dropped. """ self.data_type = type_api.to_instance(data_type) self.default = default self.collation = collation self.constraint_name = constraint_name self.not_null = bool(not_null) if check is not None: check = coercions.expect(roles.DDLExpressionRole, check) self.check = check self.create_type = create_type super().__init__(name=name, **kw) @classmethod def __test_init__(cls): return cls("name", sqltypes.Integer) def adapt(self, impl, **kw): if self.default: kw["default"] = self.default if self.constraint_name is not None: kw["constraint_name"] = self.constraint_name if self.not_null: kw["not_null"] = self.not_null if self.check is not None: kw["check"] = str(self.check) if self.create_type: kw["create_type"] = self.create_type return super().adapt(impl, **kw) class CreateEnumType(schema._CreateDropBase): __visit_name__ = "create_enum_type" class DropEnumType(schema._CreateDropBase): __visit_name__ = "drop_enum_type" class CreateDomainType(schema._CreateDropBase): """Represent a CREATE DOMAIN statement.""" __visit_name__ = "create_domain_type" class DropDomainType(schema._CreateDropBase): """Represent a DROP DOMAIN statement.""" __visit_name__ = "drop_domain_type" sqlalchemy/dialects/postgresql/__init__.py 0000755 00000007464 15125143220 0015023 0 ustar 00 # dialects/postgresql/__init__.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors from types import ModuleType from . import array as arraylib # noqa # keep above base and other dialects from . import asyncpg # noqa from . import base from . import pg8000 # noqa from . import psycopg # noqa from . import psycopg2 # noqa from . import psycopg2cffi # noqa from .array import All from .array import Any from .array import ARRAY from .array import array from .base import BIGINT from .base import BOOLEAN from .base import CHAR from .base import DATE from .base import DOMAIN from .base import DOUBLE_PRECISION from .base import FLOAT from .base import INTEGER from .base import NUMERIC from .base import REAL from .base import SMALLINT from .base import TEXT from .base import UUID from .base import VARCHAR from .dml import Insert from .dml import insert from .ext import aggregate_order_by from .ext import array_agg from .ext import ExcludeConstraint from .ext import phraseto_tsquery from .ext import plainto_tsquery from .ext import to_tsquery from .ext import to_tsvector from .ext import ts_headline from .ext import websearch_to_tsquery from .hstore import HSTORE from .hstore import hstore from .json import JSON from .json import JSONB from .json import JSONPATH from .named_types import CreateDomainType from .named_types import CreateEnumType from .named_types import DropDomainType from .named_types import DropEnumType from .named_types import ENUM from .named_types import NamedType from .ranges import AbstractMultiRange from .ranges import AbstractRange from .ranges import AbstractSingleRange from .ranges import DATEMULTIRANGE from .ranges import DATERANGE from .ranges import INT4MULTIRANGE from .ranges import INT4RANGE from .ranges import INT8MULTIRANGE from .ranges import INT8RANGE from .ranges import MultiRange from .ranges import NUMMULTIRANGE from .ranges import NUMRANGE from .ranges import Range from .ranges import TSMULTIRANGE from .ranges import TSRANGE from .ranges import TSTZMULTIRANGE from .ranges import TSTZRANGE from .types import BIT from .types import BYTEA from .types import CIDR from .types import CITEXT from .types import INET from .types import INTERVAL from .types import MACADDR from .types import MACADDR8 from .types import MONEY from .types import OID from .types import REGCLASS from .types import REGCONFIG from .types import TIME from .types import TIMESTAMP from .types import TSQUERY from .types import TSVECTOR # Alias psycopg also as psycopg_async psycopg_async = type( "psycopg_async", (ModuleType,), {"dialect": psycopg.dialect_async} ) base.dialect = dialect = psycopg2.dialect __all__ = ( "INTEGER", "BIGINT", "SMALLINT", "VARCHAR", "CHAR", "TEXT", "NUMERIC", "FLOAT", "REAL", "INET", "CIDR", "CITEXT", "UUID", "BIT", "MACADDR", "MACADDR8", "MONEY", "OID", "REGCLASS", "REGCONFIG", "TSQUERY", "TSVECTOR", "DOUBLE_PRECISION", "TIMESTAMP", "TIME", "DATE", "BYTEA", "BOOLEAN", "INTERVAL", "ARRAY", "ENUM", "DOMAIN", "dialect", "array", "HSTORE", "hstore", "INT4RANGE", "INT8RANGE", "NUMRANGE", "DATERANGE", "INT4MULTIRANGE", "INT8MULTIRANGE", "NUMMULTIRANGE", "DATEMULTIRANGE", "TSVECTOR", "TSRANGE", "TSTZRANGE", "TSMULTIRANGE", "TSTZMULTIRANGE", "JSON", "JSONB", "JSONPATH", "Any", "All", "DropEnumType", "DropDomainType", "CreateDomainType", "NamedType", "CreateEnumType", "ExcludeConstraint", "Range", "aggregate_order_by", "array_agg", "insert", "Insert", ) sqlalchemy/dialects/oracle/types.py 0000755 00000021542 15125143220 0013463 0 ustar 00 # dialects/oracle/types.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors from __future__ import annotations import datetime as dt from typing import Optional from typing import Type from typing import TYPE_CHECKING from ... import exc from ...sql import sqltypes from ...types import NVARCHAR from ...types import VARCHAR if TYPE_CHECKING: from ...engine.interfaces import Dialect from ...sql.type_api import _LiteralProcessorType class RAW(sqltypes._Binary): __visit_name__ = "RAW" OracleRaw = RAW class NCLOB(sqltypes.Text): __visit_name__ = "NCLOB" class VARCHAR2(VARCHAR): __visit_name__ = "VARCHAR2" NVARCHAR2 = NVARCHAR class NUMBER(sqltypes.Numeric, sqltypes.Integer): __visit_name__ = "NUMBER" def __init__(self, precision=None, scale=None, asdecimal=None): if asdecimal is None: asdecimal = bool(scale and scale > 0) super().__init__(precision=precision, scale=scale, asdecimal=asdecimal) def adapt(self, impltype): ret = super().adapt(impltype) # leave a hint for the DBAPI handler ret._is_oracle_number = True return ret @property def _type_affinity(self): if bool(self.scale and self.scale > 0): return sqltypes.Numeric else: return sqltypes.Integer class FLOAT(sqltypes.FLOAT): """Oracle Database FLOAT. This is the same as :class:`_sqltypes.FLOAT` except that an Oracle Database -specific :paramref:`_oracle.FLOAT.binary_precision` parameter is accepted, and the :paramref:`_sqltypes.Float.precision` parameter is not accepted. Oracle Database FLOAT types indicate precision in terms of "binary precision", which defaults to 126. For a REAL type, the value is 63. This parameter does not cleanly map to a specific number of decimal places but is roughly equivalent to the desired number of decimal places divided by 0.3103. .. versionadded:: 2.0 """ __visit_name__ = "FLOAT" def __init__( self, binary_precision=None, asdecimal=False, decimal_return_scale=None, ): r""" Construct a FLOAT :param binary_precision: Oracle Database binary precision value to be rendered in DDL. This may be approximated to the number of decimal characters using the formula "decimal precision = 0.30103 * binary precision". The default value used by Oracle Database for FLOAT / DOUBLE PRECISION is 126. :param asdecimal: See :paramref:`_sqltypes.Float.asdecimal` :param decimal_return_scale: See :paramref:`_sqltypes.Float.decimal_return_scale` """ super().__init__( asdecimal=asdecimal, decimal_return_scale=decimal_return_scale ) self.binary_precision = binary_precision class BINARY_DOUBLE(sqltypes.Double): """Implement the Oracle ``BINARY_DOUBLE`` datatype. This datatype differs from the Oracle ``DOUBLE`` datatype in that it delivers a true 8-byte FP value. The datatype may be combined with a generic :class:`.Double` datatype using :meth:`.TypeEngine.with_variant`. .. seealso:: :ref:`oracle_float_support` """ __visit_name__ = "BINARY_DOUBLE" class BINARY_FLOAT(sqltypes.Float): """Implement the Oracle ``BINARY_FLOAT`` datatype. This datatype differs from the Oracle ``FLOAT`` datatype in that it delivers a true 4-byte FP value. The datatype may be combined with a generic :class:`.Float` datatype using :meth:`.TypeEngine.with_variant`. .. seealso:: :ref:`oracle_float_support` """ __visit_name__ = "BINARY_FLOAT" class BFILE(sqltypes.LargeBinary): __visit_name__ = "BFILE" class LONG(sqltypes.Text): __visit_name__ = "LONG" class _OracleDateLiteralRender: def _literal_processor_datetime(self, dialect): def process(value): if getattr(value, "microsecond", None): value = ( f"""TO_TIMESTAMP""" f"""('{value.isoformat().replace("T", " ")}', """ """'YYYY-MM-DD HH24:MI:SS.FF')""" ) else: value = ( f"""TO_DATE""" f"""('{value.isoformat().replace("T", " ")}', """ """'YYYY-MM-DD HH24:MI:SS')""" ) return value return process def _literal_processor_date(self, dialect): def process(value): if getattr(value, "microsecond", None): value = ( f"""TO_TIMESTAMP""" f"""('{value.isoformat().split("T")[0]}', """ """'YYYY-MM-DD')""" ) else: value = ( f"""TO_DATE""" f"""('{value.isoformat().split("T")[0]}', """ """'YYYY-MM-DD')""" ) return value return process class DATE(_OracleDateLiteralRender, sqltypes.DateTime): """Provide the Oracle Database DATE type. This type has no special Python behavior, except that it subclasses :class:`_types.DateTime`; this is to suit the fact that the Oracle Database ``DATE`` type supports a time value. """ __visit_name__ = "DATE" def literal_processor(self, dialect): return self._literal_processor_datetime(dialect) def _compare_type_affinity(self, other): return other._type_affinity in (sqltypes.DateTime, sqltypes.Date) class _OracleDate(_OracleDateLiteralRender, sqltypes.Date): def literal_processor(self, dialect): return self._literal_processor_date(dialect) class INTERVAL(sqltypes.NativeForEmulated, sqltypes._AbstractInterval): __visit_name__ = "INTERVAL" def __init__(self, day_precision=None, second_precision=None): """Construct an INTERVAL. Note that only DAY TO SECOND intervals are currently supported. This is due to a lack of support for YEAR TO MONTH intervals within available DBAPIs. :param day_precision: the day precision value. this is the number of digits to store for the day field. Defaults to "2" :param second_precision: the second precision value. this is the number of digits to store for the fractional seconds field. Defaults to "6". """ self.day_precision = day_precision self.second_precision = second_precision @classmethod def _adapt_from_generic_interval(cls, interval): return INTERVAL( day_precision=interval.day_precision, second_precision=interval.second_precision, ) @classmethod def adapt_emulated_to_native( cls, interval: sqltypes.Interval, **kw # type: ignore[override] ): return INTERVAL( day_precision=interval.day_precision, second_precision=interval.second_precision, ) @property def _type_affinity(self): return sqltypes.Interval def as_generic(self, allow_nulltype=False): return sqltypes.Interval( native=True, second_precision=self.second_precision, day_precision=self.day_precision, ) @property def python_type(self) -> Type[dt.timedelta]: return dt.timedelta def literal_processor( self, dialect: Dialect ) -> Optional[_LiteralProcessorType[dt.timedelta]]: def process(value: dt.timedelta) -> str: return f"NUMTODSINTERVAL({value.total_seconds()}, 'SECOND')" return process class TIMESTAMP(sqltypes.TIMESTAMP): """Oracle Database implementation of ``TIMESTAMP``, which supports additional Oracle Database-specific modes .. versionadded:: 2.0 """ def __init__(self, timezone: bool = False, local_timezone: bool = False): """Construct a new :class:`_oracle.TIMESTAMP`. :param timezone: boolean. Indicates that the TIMESTAMP type should use Oracle Database's ``TIMESTAMP WITH TIME ZONE`` datatype. :param local_timezone: boolean. Indicates that the TIMESTAMP type should use Oracle Database's ``TIMESTAMP WITH LOCAL TIME ZONE`` datatype. """ if timezone and local_timezone: raise exc.ArgumentError( "timezone and local_timezone are mutually exclusive" ) super().__init__(timezone=timezone) self.local_timezone = local_timezone class ROWID(sqltypes.TypeEngine): """Oracle Database ROWID type. When used in a cast() or similar, generates ROWID. """ __visit_name__ = "ROWID" class _OracleBoolean(sqltypes.Boolean): def get_dbapi_type(self, dbapi): return dbapi.NUMBER sqlalchemy/dialects/oracle/__pycache__/dictionary.cpython-39.pyc 0000644 00000025676 15125143220 0020764 0 ustar 00 a ��Jh?L � \ @ s d dl mZ d dl mZ d dl mZ d dl mZ d dl mZ ddlmZ ddlmZ dd lm Z dd lm Z dd l m Z d Z e d �Ze� Ze de eeded�dd�eded�dd�eded��eded��eded��eded��ede�ede�ed e�ed e�ed e�ed e�ed e�ed!e�ed"e�ed#e�ed$e�ed%ed��ed&ed ��ed'e�ed(e�ed)e�ed*e�ed+e�ed,e�ed-e�ed.e�ed/ed0��ed1ed0��ed2ed3��ed4ed��ed5e�ed6e�ed7ed��ed8ed9��ed:ed ��ed;ed ��ed<ed��ed=ed>��ed?ed>��ed@ed>��edAed��edBed��edCed��edDedE��edFed��edGed��edHed��edIed��edJed��edKed��edLed��edMed��edNed��edOed>��edPed��edQedR��edSedT��edUed��edVed��edWed��edXed��edYedE��edZed[��ed\ed]��ed^ed_��ed`ed ��edaed ��edbed ��edced ��edded��edeed��edfedg��edhed��edied��edjed��edked��edled9��edmedn��edoed��edped��edqed��edred��edsed��edted��edued���X�dv�Ze dwe eeded�dd�edxed�dd�edye�edze�ed{ed|��ed}e�ed~ed|��ede�ed�ed|��ed�ed��ed�ed��ed�ed��ed�ed ��edMed ��edVed ��ed�ed9��ed�ed���ed^ed_��edhed��edied��edjed��edked��edred��edsed��ed�ed����d��Ze d�e eed�ed�dd�ed�ed�dd�ed�e�ed�e�ed�edd�ed�ed ��ed�ed ��ed�edd�ed�edd�ed�ed ��ed�ed ��ed�ed ��ed�ed ��ed�ed ����d��Ze d�e eed�ed�dd�ed�edd�ed�edd�ed�ed��ed�ed ��ed�ed��ed^ed_��ed�ed��ed�ed��ed�ed��� �d��Ze d�e eeded�dd�ed�ed�dd�ed�ed�dd�ed�e�ed�ed���ed�ed ��ed�ed��ed�ed��ed�ed��ed�ed ��ed�ed���ed�ed���ed�ed��ed�ed���ed�ed���ed�ed��ed�e�ed�e�ed�ed���ed�ed���ed�ed ��ed�ed ��ed�ed ��ed�ed ��ed�ed ��ed�ed ��ed�ed���ed�ed ��ed�e�ed�e�ed�e�ed�e�edNed��ed�ed��ed�ed��ed�ed��ed^ed_��ed�ed ��ed�ed���)�dϡZe d�e eeded�dd�eded�dd�ed�ed�dd�ed�ed0��ed�ed�dd�ed�edԃ���dաZe d�e eeded�dd�eded�dd�ed�ed�dd�ed�ed��ed�ed��ed�ed��ed�edd�ed�e�ed�e�ed�ed ��ed�e�ed�e�ed�e�ed�e�ed�edn��ed�edn��ed�e�ed�e�ed�e�ed6e�ed5e�ed�ed��ed�e�edBed��edCed��ed�e�ed�e�ed�ed ��ed�ed��ed�ed��ed�ed��ed�ed��ed�e�ed�edd�ed�edE��ed�ed|��ed�ed��ed�ed��ed�ed��ed�ed��ed�ed��ed�ed��ed�ed_��ed�e��.�d��Ze d�e eeded�dd�eded�dd�ed�ed���ed�ed|��ed�e���d��Ze �d e eeded�dd�eded�dd�ed�ed�dd�ed�ed|��ed�e����d�Ze �de eeded�dd�ed�ed�dd�ed�ed|�����d�Ze �de ee�ded�dd�e�ded�dd�e�ded�dd�eded�dd�ed�ed|��e�dedd�e�d edd�ed�e�e�d e�d ��ed�e�� ��d �Ze �d e eeded�dd�e�ded�dd�e�de�d��e�ded�dd�eded�dd�ed�e d���e�ded���edJed]��e�de�eded��ed e�ed e�ed e�ed e�ed e�ed!e�ed"e�e�de�e�de�ed#e�ed$e�ede�ed%ed��e�de�e�de�e�de�e�de�e�de�e�de�eded��ed'e�ed5e�ed6e�ed/e�d��ed1e�d��ed7ed��ed:ed ��e�ded ��ed;ed ��ed=ed>��ed?ed>��ed@ed>��edCed��edDedE��e�d e�e�d ed��e�d ed��e�d edn��edBed��e�d ed9��e�d!ed���e�d"ed��e�d#ed��e�d$ed��edLed��e�d%ed���e�d&e�d'��edNed��e�d(ed��e�d)ed>��ed�ed���?��d*�Z e �d+e ee�ded�dd�e�ded�dd�e�ded�dd�eded�dd�e�d,e�e�dedd����d-�Z e �d.e eeded��e�d/ed��e�d0ed ��eded��e�d1e�e�d2ed|��e�d3ed��e�d4ed��e�d5ed���eded��e�d6e�d'��e�d7ed���e�d8ed]��e�de�d'��e�d9ed��e�d:e�d ��e�d;e�e�ded��e�ded��e�d<ed>��e�d=e�d'��ed�ed������d>�Z e �d?e eeded�dd�e�d/ed�dd�eded�dd�ed�ed|��e�d@e����dA�Z e �dBe eeded�dd�e�dCed�dd�ed�ed��e�dDe�dE��ed�edd�e�dFed��e�dGed��e�dHed��e�dIed��� ��dJ�Z e �dKe eeded��e�dLed��e�ded��eded��e�dCed��ed�ed������dM�Z!e �dNe eeded�dd�e�dOed�dd�e�dPed��e�dQedd�e�dRe�e�dSedR��ed�edd�e�dTedd�e�dUed���eded>��ed:ed ��e�ded ��ed;ed ��e�dVedd�e�dWed��e�dXed]��e�dYed ��ed�ed ��e�dZed ��ed^ed_��ed`ed ��edaed ��e�d[e�e�d\e�e�d]e�e�d^e�� ��d_�Z"�d`S (a � )�DATE)�LONG)�NUMBER)�RAW)�VARCHAR2� )�Column)�MetaData)�Table)�table)�CHARz__$sa_dblink$__�dual� all_tables�owner� F)�nullableZ table_nameZtablespace_name� Z cluster_nameZiot_name�status� Zpct_freeZpct_usedZ ini_transZ max_transZinitial_extentZ next_extentZ min_extentsZ max_extentsZ pct_increaseZ freelistsZfreelist_groups�loggingZ backed_upZnum_rows�blocksZ empty_blocksZ avg_spaceZ chain_cntZ avg_row_lenZavg_space_freelist_blocksZnum_freelist_blocksZdegree� Z instances�cache� Z table_lockZ sample_sizeZ last_analyzedZ partitionedZiot_type� � temporaryZ secondary�nestedZ buffer_pool� Z flash_cacheZcell_flash_cacheZ row_movementZ global_statsZ user_stats�duration� Z skip_corruptZ monitoringZ cluster_owner� dependencies� compressionZ compress_forZdroppedZ read_onlyZsegment_createdZ result_cacheZ clusteringZactivity_tracking� Z dml_timestamp� Z has_identityZcontainer_dataZinmemoryZinmemory_priorityZinmemory_distributeZinmemory_compression� Zinmemory_duplicate� Zdefault_collation�d Z duplicatedZshardedZexternally_shardedZexternally_duplicatedZexternalZhybridZ cellmemory� Zcontainers_defaultZ container_mapZextended_data_linkZextended_data_link_mapZinmemory_serviceZinmemory_service_namei� Zcontainer_map_objectZmemoptimize_readZmemoptimize_writeZhas_sensitive_columnZ admit_nullZdata_link_dml_enabledZlogical_replicationZa_tables� all_viewsZ view_nameZ text_length�textZtext_vci� Ztype_text_lengthZ type_textZoid_text_lengthZoid_textZview_type_ownerZ view_typeZsuperview_nameZeditioning_viewZbequeathZ origin_con_id� Zpdb_local_onlyZa_views� all_sequencesZsequence_ownerZ sequence_nameZ min_valueZ max_valueZ increment_byZ cycle_flagZ order_flagZ cache_sizeZ last_numberZ scale_flagZ extend_flagZ sharded_flagZ session_flagZ keep_valueZ a_sequences� all_users�usernameZuser_id�created�commonZoracle_maintainedZ inheritedZimplicitZ all_shardZexternal_shardZa_users� all_mviewsZ mview_nameZcontainer_name�queryZ query_len�& Z updatableZ update_logZmaster_rollback_segZ master_linkZrewrite_enabledZrewrite_capability� Z refresh_mode� Zrefresh_methodZ build_modeZfast_refreshable� Zlast_refresh_typeZlast_refresh_dateZlast_refresh_end_timeZ staleness� Zafter_fast_refreshZunknown_prebuiltZunknown_plsql_funcZunknown_external_tableZunknown_consider_freshZunknown_importZunknown_trusted_fdZ compile_stateZ use_no_indexZ stale_sinceZnum_pct_tablesZnum_fresh_pct_regionsZnum_stale_pct_regionsZevaluation_editionZunusable_beforeZunusable_beginningZon_query_computation�autoZa_mviews�all_tab_identity_colsZ column_nameZgeneration_typeZidentity_optionsi* Za_tab_identity_cols� all_tab_colsZ data_typeZ data_type_modZdata_type_ownerZ data_lengthZdata_precisionZ data_scaler Z column_idZdefault_lengthZ data_defaultZ num_distinctZ low_valueZ high_valueZdensityZ num_nullsZ num_bucketsZcharacter_set_name�, Zchar_col_decl_lengthZ avg_col_lenZ char_lengthZ char_usedZ v80_fmt_imageZ data_upgradedZ hidden_columnZvirtual_columnZsegment_column_idZinternal_column_idZ histogramZqualified_col_nameZuser_generatedZdefault_on_nullZidentity_columnZ collationZcollated_column_idZ a_tab_cols�all_tab_commentsZ table_type� �commentsZa_tab_comments�all_col_commentsZa_col_comments�all_mview_commentsZa_mview_comments�all_ind_columnsZ index_ownerZ index_nameZ table_ownerZcolumn_positionZ column_lengthZdescend� Z a_ind_columns� all_indexesZ index_type� Z uniquenessZ prefix_lengthZ pct_thresholdZinclude_columnZblevelZ leaf_blocksZ distinct_keysZavg_leaf_blocks_per_keyZavg_data_blocks_per_keyZclustering_factor�( � generatedZpct_direct_accessZ ityp_ownerZ ityp_name� parametersZ domidx_statusZdomidx_opstatusZfuncidx_statusZ join_indexZiot_redundant_pkey_elimZ visibilityZdomidx_management� Zorphaned_entriesZindexingZ a_indexes�all_ind_expressionsZcolumn_expressionZa_ind_expressions�all_constraintsZconstraint_nameZconstraint_typeZsearch_conditionZsearch_condition_vcZr_ownerZr_constraint_nameZ delete_ruleZ deferrable�deferredZ validated�badZrelyZ last_change�invalidZ view_relatedZ a_constraints�all_cons_columns�positionZa_cons_columns� all_db_linksZdb_link�hosti� �hiddenZshard_internalZvalidZ intra_cdbZ a_db_links� all_synonymsZ synonym_nameZ a_synonyms� all_objectsZ object_nameZsubobject_nameZ object_idZdata_object_idZ object_typeZ last_ddl_time� timestamp� namespaceZ edition_nameZsharingZ editionableZ applicationZ created_appidZ created_vsnidZmodified_appidZmodified_vsnidZ a_objectsN)#�typesr r r r r � r r r r Z sql.sqltypesr ZDB_LINK_PLACEHOLDERr Zdictionary_meta�aliasr r( r+ r, r0 r8 r9 r; r> r? r@ rB rH rI rM rO rR rS � rY rY �Z/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/oracle/dictionary.py�<module> s� �Y�[ � � �� � � �*�, � � �/�1 �� �� �� � � �@�B � � �� �� � � � � � � sqlalchemy/dialects/oracle/__pycache__/oracledb.cpython-39.pyc 0000644 00000105663 15125143220 0020365 0 ustar 00 a ��Jh� � @ sz d Z ddlmZ ddlZddlZddlmZ ddlmZ ddlm Z dd lm Z dd lm Z dd l mZ dd l mZ dd l mZ ddl mZ ddlmZ ddlmZ ddlmZ ddlmZ er�ddlmZ ddlmZ G dd� de j�Z G dd� de j �Z G dd� de�Z G dd � d ee �Z G d d � d e�Z!G d d � d ee!�Z"G d!d"� d"�Z#G d#d$� d$e �Z$G d%d&� d&e �Z%e Z&e%Z'dS )'a�Y .. dialect:: oracle+oracledb :name: python-oracledb :dbapi: oracledb :connectstring: oracle+oracledb://user:pass@hostname:port[/dbname][?service_name=<service>[&key=value&key=value...]] :url: https://oracle.github.io/python-oracledb/ Description ----------- Python-oracledb is the Oracle Database driver for Python. It features a default "thin" client mode that requires no dependencies, and an optional "thick" mode that uses Oracle Client libraries. It supports SQLAlchemy features including two phase transactions and Asyncio. Python-oracle is the renamed, updated cx_Oracle driver. Oracle is no longer doing any releases in the cx_Oracle namespace. The SQLAlchemy ``oracledb`` dialect provides both a sync and an async implementation under the same dialect name. The proper version is selected depending on how the engine is created: * calling :func:`_sa.create_engine` with ``oracle+oracledb://...`` will automatically select the sync version:: from sqlalchemy import create_engine sync_engine = create_engine( "oracle+oracledb://scott:tiger@localhost?service_name=FREEPDB1" ) * calling :func:`_asyncio.create_async_engine` with ``oracle+oracledb://...`` will automatically select the async version:: from sqlalchemy.ext.asyncio import create_async_engine asyncio_engine = create_async_engine( "oracle+oracledb://scott:tiger@localhost?service_name=FREEPDB1" ) The asyncio version of the dialect may also be specified explicitly using the ``oracledb_async`` suffix:: from sqlalchemy.ext.asyncio import create_async_engine asyncio_engine = create_async_engine( "oracle+oracledb_async://scott:tiger@localhost?service_name=FREEPDB1" ) .. versionadded:: 2.0.25 added support for the async version of oracledb. Thick mode support ------------------ By default, the python-oracledb driver runs in a "thin" mode that does not require Oracle Client libraries to be installed. The driver also supports a "thick" mode that uses Oracle Client libraries to get functionality such as Oracle Application Continuity. To enable thick mode, call `oracledb.init_oracle_client() <https://python-oracledb.readthedocs.io/en/latest/api_manual/module.html#oracledb.init_oracle_client>`_ explicitly, or pass the parameter ``thick_mode=True`` to :func:`_sa.create_engine`. To pass custom arguments to ``init_oracle_client()``, like the ``lib_dir`` path, a dict may be passed, for example:: engine = sa.create_engine( "oracle+oracledb://...", thick_mode={ "lib_dir": "/path/to/oracle/client/lib", "config_dir": "/path/to/network_config_file_directory", "driver_name": "my-app : 1.0.0", }, ) Note that passing a ``lib_dir`` path should only be done on macOS or Windows. On Linux it does not behave as you might expect. .. seealso:: python-oracledb documentation `Enabling python-oracledb Thick mode <https://python-oracledb.readthedocs.io/en/latest/user_guide/initialization.html#enabling-python-oracledb-thick-mode>`_ Connecting to Oracle Database ----------------------------- python-oracledb provides several methods of indicating the target database. The dialect translates from a series of different URL forms. Given the hostname, port and service name of the target database, you can connect in SQLAlchemy using the ``service_name`` query string parameter:: engine = create_engine( "oracle+oracledb://scott:tiger@hostname:port?service_name=myservice" ) Connecting with Easy Connect strings ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ You can pass any valid python-oracledb connection string as the ``dsn`` key value in a :paramref:`_sa.create_engine.connect_args` dictionary. See python-oracledb documentation `Oracle Net Services Connection Strings <https://python-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#oracle-net-services-connection-strings>`_. For example to use an `Easy Connect string <https://download.oracle.com/ocomdocs/global/Oracle-Net-Easy-Connect-Plus.pdf>`_ with a timeout to prevent connection establishment from hanging if the network transport to the database cannot be establishd in 30 seconds, and also setting a keep-alive time of 60 seconds to stop idle network connections from being terminated by a firewall:: e = create_engine( "oracle+oracledb://@", connect_args={ "user": "scott", "password": "tiger", "dsn": "hostname:port/myservice?transport_connect_timeout=30&expire_time=60", }, ) The Easy Connect syntax has been enhanced during the life of Oracle Database. Review the documentation for your database version. The current documentation is at `Understanding the Easy Connect Naming Method <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-B0437826-43C1-49EC-A94D-B650B6A4A6EE>`_. The general syntax is similar to: .. sourcecode:: text [[protocol:]//]host[:port][/[service_name]][?parameter_name=value{¶meter_name=value}] Note that although the SQLAlchemy URL syntax ``hostname:port/dbname`` looks like Oracle's Easy Connect syntax, it is different. SQLAlchemy's URL requires a system identifier (SID) for the ``dbname`` component:: engine = create_engine("oracle+oracledb://scott:tiger@hostname:port/sid") Easy Connect syntax does not support SIDs. It uses services names, which are the preferred choice for connecting to Oracle Database. Passing python-oracledb connect arguments ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Other python-oracledb driver `connection options <https://python-oracledb.readthedocs.io/en/latest/api_manual/module.html#oracledb.connect>`_ can be passed in ``connect_args``. For example:: e = create_engine( "oracle+oracledb://@", connect_args={ "user": "scott", "password": "tiger", "dsn": "hostname:port/myservice", "events": True, "mode": oracledb.AUTH_MODE_SYSDBA, }, ) Connecting with tnsnames.ora TNS aliases ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If no port, database name, or service name is provided, the dialect will use an Oracle Database DSN "connection string". This takes the "hostname" portion of the URL as the data source name. For example, if the ``tnsnames.ora`` file contains a `TNS Alias <https://python-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#tns-aliases-for-connection-strings>`_ of ``myalias`` as below: .. sourcecode:: text myalias = (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = mymachine.example.com)(PORT = 1521)) (CONNECT_DATA = (SERVER = DEDICATED) (SERVICE_NAME = orclpdb1) ) ) The python-oracledb dialect connects to this database service when ``myalias`` is the hostname portion of the URL, without specifying a port, database name or ``service_name``:: engine = create_engine("oracle+oracledb://scott:tiger@myalias") Connecting to Oracle Autonomous Database ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Users of Oracle Autonomous Database should use either use the TNS Alias URL shown above, or pass the TNS Alias as the ``dsn`` key value in a :paramref:`_sa.create_engine.connect_args` dictionary. If Oracle Autonomous Database is configured for mutual TLS ("mTLS") connections, then additional configuration is required as shown in `Connecting to Oracle Cloud Autonomous Databases <https://python-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#connecting-to-oracle-cloud-autonomous-databases>`_. In summary, Thick mode users should configure file locations and set the wallet path in ``sqlnet.ora`` appropriately:: e = create_engine( "oracle+oracledb://@", thick_mode={ # directory containing tnsnames.ora and cwallet.so "config_dir": "/opt/oracle/wallet_dir", }, connect_args={ "user": "scott", "password": "tiger", "dsn": "mydb_high", }, ) Thin mode users of mTLS should pass the appropriate directories and PEM wallet password when creating the engine, similar to:: e = create_engine( "oracle+oracledb://@", connect_args={ "user": "scott", "password": "tiger", "dsn": "mydb_high", "config_dir": "/opt/oracle/wallet_dir", # directory containing tnsnames.ora "wallet_location": "/opt/oracle/wallet_dir", # directory containing ewallet.pem "wallet_password": "top secret", # password for the PEM file }, ) Typically ``config_dir`` and ``wallet_location`` are the same directory, which is where the Oracle Autonomous Database wallet zip file was extracted. Note this directory should be protected. Connection Pooling ------------------ Applications with multiple concurrent users should use connection pooling. A minimal sized connection pool is also beneficial for long-running, single-user applications that do not frequently use a connection. The python-oracledb driver provides its own connection pool implementation that may be used in place of SQLAlchemy's pooling functionality. The driver pool gives support for high availability features such as dead connection detection, connection draining for planned database downtime, support for Oracle Application Continuity and Transparent Application Continuity, and gives support for `Database Resident Connection Pooling (DRCP) <https://python-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#database-resident-connection-pooling-drcp>`_. To take advantage of python-oracledb's pool, use the :paramref:`_sa.create_engine.creator` parameter to provide a function that returns a new connection, along with setting :paramref:`_sa.create_engine.pool_class` to ``NullPool`` to disable SQLAlchemy's pooling:: import oracledb from sqlalchemy import create_engine from sqlalchemy import text from sqlalchemy.pool import NullPool # Uncomment to use the optional python-oracledb Thick mode. # Review the python-oracledb doc for the appropriate parameters # oracledb.init_oracle_client(<your parameters>) pool = oracledb.create_pool( user="scott", password="tiger", dsn="localhost:1521/freepdb1", min=1, max=4, increment=1, ) engine = create_engine( "oracle+oracledb://", creator=pool.acquire, poolclass=NullPool ) The above engine may then be used normally. Internally, python-oracledb handles connection pooling:: with engine.connect() as conn: print(conn.scalar(text("select 1 from dual"))) Refer to the python-oracledb documentation for `oracledb.create_pool() <https://python-oracledb.readthedocs.io/en/latest/api_manual/module.html#oracledb.create_pool>`_ for the arguments that can be used when creating a connection pool. .. _drcp: Using Oracle Database Resident Connection Pooling (DRCP) -------------------------------------------------------- When using Oracle Database's Database Resident Connection Pooling (DRCP), the best practice is to specify a connection class and "purity". Refer to the `python-oracledb documentation on DRCP <https://python-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#database-resident-connection-pooling-drcp>`_. For example:: import oracledb from sqlalchemy import create_engine from sqlalchemy import text from sqlalchemy.pool import NullPool # Uncomment to use the optional python-oracledb Thick mode. # Review the python-oracledb doc for the appropriate parameters # oracledb.init_oracle_client(<your parameters>) pool = oracledb.create_pool( user="scott", password="tiger", dsn="localhost:1521/freepdb1", min=1, max=4, increment=1, cclass="MYCLASS", purity=oracledb.PURITY_SELF, ) engine = create_engine( "oracle+oracledb://", creator=pool.acquire, poolclass=NullPool ) The above engine may then be used normally where python-oracledb handles application connection pooling and Oracle Database additionally uses DRCP:: with engine.connect() as conn: print(conn.scalar(text("select 1 from dual"))) If you wish to use different connection classes or purities for different connections, then wrap ``pool.acquire()``:: import oracledb from sqlalchemy import create_engine from sqlalchemy import text from sqlalchemy.pool import NullPool # Uncomment to use python-oracledb Thick mode. # Review the python-oracledb doc for the appropriate parameters # oracledb.init_oracle_client(<your parameters>) pool = oracledb.create_pool( user="scott", password="tiger", dsn="localhost:1521/freepdb1", min=1, max=4, increment=1, cclass="MYCLASS", purity=oracledb.PURITY_SELF, ) def creator(): return pool.acquire(cclass="MYOTHERCLASS", purity=oracledb.PURITY_NEW) engine = create_engine( "oracle+oracledb://", creator=creator, poolclass=NullPool ) Engine Options consumed by the SQLAlchemy oracledb dialect outside of the driver -------------------------------------------------------------------------------- There are also options that are consumed by the SQLAlchemy oracledb dialect itself. These options are always passed directly to :func:`_sa.create_engine`, such as:: e = create_engine("oracle+oracledb://user:pass@tnsalias", arraysize=500) The parameters accepted by the oracledb dialect are as follows: * ``arraysize`` - set the driver cursor.arraysize value. It defaults to ``None``, indicating that the driver default value of 100 should be used. This setting controls how many rows are buffered when fetching rows, and can have a significant effect on performance if increased for queries that return large numbers of rows. .. versionchanged:: 2.0.26 - changed the default value from 50 to None, to use the default value of the driver itself. * ``auto_convert_lobs`` - defaults to True; See :ref:`oracledb_lob`. * ``coerce_to_decimal`` - see :ref:`oracledb_numeric` for detail. * ``encoding_errors`` - see :ref:`oracledb_unicode_encoding_errors` for detail. .. _oracledb_unicode: Unicode ------- As is the case for all DBAPIs under Python 3, all strings are inherently Unicode strings. Ensuring the Correct Client Encoding ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In python-oracledb, the encoding used for all character data is "UTF-8". Unicode-specific Column datatypes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The Core expression language handles unicode data by use of the :class:`.Unicode` and :class:`.UnicodeText` datatypes. These types correspond to the VARCHAR2 and CLOB Oracle Database datatypes by default. When using these datatypes with Unicode data, it is expected that the database is configured with a Unicode-aware character set so that the VARCHAR2 and CLOB datatypes can accommodate the data. In the case that Oracle Database is not configured with a Unicode character set, the two options are to use the :class:`_types.NCHAR` and :class:`_oracle.NCLOB` datatypes explicitly, or to pass the flag ``use_nchar_for_unicode=True`` to :func:`_sa.create_engine`, which will cause the SQLAlchemy dialect to use NCHAR/NCLOB for the :class:`.Unicode` / :class:`.UnicodeText` datatypes instead of VARCHAR/CLOB. .. versionchanged:: 1.3 The :class:`.Unicode` and :class:`.UnicodeText` datatypes now correspond to the ``VARCHAR2`` and ``CLOB`` Oracle Database datatypes unless the ``use_nchar_for_unicode=True`` is passed to the dialect when :func:`_sa.create_engine` is called. .. _oracledb_unicode_encoding_errors: Encoding Errors ^^^^^^^^^^^^^^^ For the unusual case that data in Oracle Database is present with a broken encoding, the dialect accepts a parameter ``encoding_errors`` which will be passed to Unicode decoding functions in order to affect how decoding errors are handled. The value is ultimately consumed by the Python `decode <https://docs.python.org/3/library/stdtypes.html#bytes.decode>`_ function, and is passed both via python-oracledb's ``encodingErrors`` parameter consumed by ``Cursor.var()``, as well as SQLAlchemy's own decoding function, as the python-oracledb dialect makes use of both under different circumstances. .. versionadded:: 1.3.11 .. _oracledb_setinputsizes: Fine grained control over python-oracledb data binding with setinputsizes ------------------------------------------------------------------------- The python-oracle DBAPI has a deep and fundamental reliance upon the usage of the DBAPI ``setinputsizes()`` call. The purpose of this call is to establish the datatypes that are bound to a SQL statement for Python values being passed as parameters. While virtually no other DBAPI assigns any use to the ``setinputsizes()`` call, the python-oracledb DBAPI relies upon it heavily in its interactions with the Oracle Database, and in some scenarios it is not possible for SQLAlchemy to know exactly how data should be bound, as some settings can cause profoundly different performance characteristics, while altering the type coercion behavior at the same time. Users of the oracledb dialect are **strongly encouraged** to read through python-oracledb's list of built-in datatype symbols at `Database Types <https://python-oracledb.readthedocs.io/en/latest/api_manual/module.html#database-types>`_ Note that in some cases, significant performance degradation can occur when using these types vs. not. On the SQLAlchemy side, the :meth:`.DialectEvents.do_setinputsizes` event can be used both for runtime visibility (e.g. logging) of the setinputsizes step as well as to fully control how ``setinputsizes()`` is used on a per-statement basis. .. versionadded:: 1.2.9 Added :meth:`.DialectEvents.setinputsizes` Example 1 - logging all setinputsizes calls ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The following example illustrates how to log the intermediary values from a SQLAlchemy perspective before they are converted to the raw ``setinputsizes()`` parameter dictionary. The keys of the dictionary are :class:`.BindParameter` objects which have a ``.key`` and a ``.type`` attribute:: from sqlalchemy import create_engine, event engine = create_engine( "oracle+oracledb://scott:tiger@localhost:1521?service_name=freepdb1" ) @event.listens_for(engine, "do_setinputsizes") def _log_setinputsizes(inputsizes, cursor, statement, parameters, context): for bindparam, dbapitype in inputsizes.items(): log.info( "Bound parameter name: %s SQLAlchemy type: %r DBAPI object: %s", bindparam.key, bindparam.type, dbapitype, ) Example 2 - remove all bindings to CLOB ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For performance, fetching LOB datatypes from Oracle Database is set by default for the ``Text`` type within SQLAlchemy. This setting can be modified as follows:: from sqlalchemy import create_engine, event from oracledb import CLOB engine = create_engine( "oracle+oracledb://scott:tiger@localhost:1521?service_name=freepdb1" ) @event.listens_for(engine, "do_setinputsizes") def _remove_clob(inputsizes, cursor, statement, parameters, context): for bindparam, dbapitype in list(inputsizes.items()): if dbapitype is CLOB: del inputsizes[bindparam] .. _oracledb_lob: LOB Datatypes -------------- LOB datatypes refer to the "large object" datatypes such as CLOB, NCLOB and BLOB. Oracle Database can efficiently return these datatypes as a single buffer. SQLAlchemy makes use of type handlers to do this by default. To disable the use of the type handlers and deliver LOB objects as classic buffered objects with a ``read()`` method, the parameter ``auto_convert_lobs=False`` may be passed to :func:`_sa.create_engine`. .. _oracledb_returning: RETURNING Support ----------------- The oracledb dialect implements RETURNING using OUT parameters. The dialect supports RETURNING fully. Two Phase Transaction Support ----------------------------- Two phase transactions are fully supported with python-oracledb. (Thin mode requires python-oracledb 2.3). APIs for two phase transactions are provided at the Core level via :meth:`_engine.Connection.begin_twophase` and :paramref:`_orm.Session.twophase` for transparent ORM use. .. versionchanged:: 2.0.32 added support for two phase transactions .. _oracledb_numeric: Precision Numerics ------------------ SQLAlchemy's numeric types can handle receiving and returning values as Python ``Decimal`` objects or float objects. When a :class:`.Numeric` object, or a subclass such as :class:`.Float`, :class:`_oracle.DOUBLE_PRECISION` etc. is in use, the :paramref:`.Numeric.asdecimal` flag determines if values should be coerced to ``Decimal`` upon return, or returned as float objects. To make matters more complicated under Oracle Database, the ``NUMBER`` type can also represent integer values if the "scale" is zero, so the Oracle Database-specific :class:`_oracle.NUMBER` type takes this into account as well. The oracledb dialect makes extensive use of connection- and cursor-level "outputtypehandler" callables in order to coerce numeric values as requested. These callables are specific to the specific flavor of :class:`.Numeric` in use, as well as if no SQLAlchemy typing objects are present. There are observed scenarios where Oracle Database may send incomplete or ambiguous information about the numeric types being returned, such as a query where the numeric types are buried under multiple levels of subquery. The type handlers do their best to make the right decision in all cases, deferring to the underlying python-oracledb DBAPI for all those cases where the driver can make the best decision. When no typing objects are present, as when executing plain SQL strings, a default "outputtypehandler" is present which will generally return numeric values which specify precision and scale as Python ``Decimal`` objects. To disable this coercion to decimal for performance reasons, pass the flag ``coerce_to_decimal=False`` to :func:`_sa.create_engine`:: engine = create_engine( "oracle+oracledb://scott:tiger@tnsalias", coerce_to_decimal=False ) The ``coerce_to_decimal`` flag only impacts the results of plain string SQL statements that are not otherwise associated with a :class:`.Numeric` SQLAlchemy type (or a subclass of such). .. versionchanged:: 1.2 The numeric handling system for the oracle dialects has been reworked to take advantage of newer driver features as well as better integration of outputtypehandlers. .. versionadded:: 2.0.0 added support for the python-oracledb driver. � )� annotationsN)�Any)� TYPE_CHECKING� )� cx_oracle� )�exc)�pool)�AsyncAdapt_dbapi_connection)�AsyncAdapt_dbapi_cursor)�AsyncAdapt_dbapi_ss_cursor)�#AsyncAdaptFallback_dbapi_connection)�default)�asbool)�await_fallback)� await_only)�AsyncConnection)� AsyncCursorc @ s e Zd ZdS )� OracleExecutionContext_oracledbN)�__name__� __module__� __qualname__� r r �X/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/oracle/oracledb.pyr k s r c s� e Zd ZdZeZdZdZd � fdd� Ze dd� �Z e d d � �Z e d d � �Z d d� Z dd� Zdd� Zd dd�Zd dd�Zdd� Z� fdd�Z� ZS ) �OracleDialect_oracledbT�oracledb)r Nc sZ t � j||||fi |�� | jd urV|s2t|t�rVt|t�r@|ni }| jjf i |�� d S �N)�super�__init__Zdbapi� isinstance�dictZinit_oracle_client)�selfZauto_convert_lobsZcoerce_to_decimal� arraysizeZencoding_errorsZ thick_mode�kwargs�kw�� __class__r r r x s �� ��z OracleDialect_oracledb.__init__c C s dd l }|S �Nr )r ��clsr r r r � import_dbapi� s z#OracleDialect_oracledb.import_dbapic C s |j jjS r )� connectionZdbapi_connection�thin)r) r+ r r r � is_thin_mode� s z#OracleDialect_oracledb.is_thin_modec C s t S r )�OracleDialectAsync_oracledb)r) �urlr r r �get_async_dialect_cls� s z,OracleDialect_oracledb.get_async_dialect_clsc C sn d}|d ur:t �d|j�}|r:tdd� |�ddd�D ��}|| _| jdkrj| j| jk rjt�d| j� d ���d S ) N)r r r z(\d+)\.(\d+)(?:\.(\d+))?c s s | ]}|d urt |�V qd S r )�int)�.0�xr r r � <genexpr>� s z7OracleDialect_oracledb._load_version.<locals>.<genexpr>r � r zoracledb version z and above are supported) �re�match�version�tuple�group� oracledb_ver� _min_versionr ZInvalidRequestError)r! Z dbapi_moduler8 �mr r r � _load_version� s �� � �z$OracleDialect_oracledb._load_versionc C s( |j j|� }|j �|� ||j jd< d S )NZ oracledb_xid)r+ �xid� tpc_begin�info)r! r+ r? Zconn_xisr r r �do_begin_twophase� s z(OracleDialect_oracledb.do_begin_twophasec C s |j �� }||jd< d S )N�oracledb_should_commit)r+ � tpc_preparerA )r! r+ r? � should_commitr r r �do_prepare_twophase� s z*OracleDialect_oracledb.do_prepare_twophaseFc C s& |r|j j|� }nd }|j �|� d S r )r+ r? � tpc_rollback)r! r+ r? � is_prepared�recover�conn_xidr r r �do_rollback_twophase� s z+OracleDialect_oracledb.do_rollback_twophasec C sH d }|s|j �� }n |r*|j j|� }d}n |jd }|rD|j �|� d S )NTrC )r+ rD r? rA � tpc_commit)r! r+ r? rH rI rJ rE r r r �do_commit_twophase� s z)OracleDialect_oracledb.do_commit_twophasec C s dd� |j �� D �S )Nc S s@ g | ]8\}}}|t |t�r"|�� n|t |t�r6|�� n|f�qS r )r �bytes�decode)r2 �fiZgti�bqr r r � <listcomp>� s ��z>OracleDialect_oracledb.do_recover_twophase.<locals>.<listcomp>)r+ � tpc_recover�r! r+ r r r �do_recover_twophase� s �z*OracleDialect_oracledb.do_recover_twophasec s* | j dkr |jj}|d ur |S t� �|�S )N)r5 � )r; r+ �max_identifier_lengthr � _check_max_identifier_length)r! r+ �max_lenr% r r rX � s z3OracleDialect_oracledb._check_max_identifier_length)TTNNN)TF)TF)r r r �supports_statement_cacher �execution_ctx_clsZdriverr< r � classmethodr* r- r0 r> rB rF rK rM rU rX � __classcell__r r r% r r q s2 � � � r c @ s� e Zd ZU ded< dZedd� �Zejdd� �Zdd� Zd d � Z d d d d �d d�Z ddd�dd�Z dd� Z dd� Z dd� Zd d d dd�dd�Zd S ) �AsyncAdapt_oracledb_cursorr �_cursorr c C s | j jS r �r_ �outputtypehandler�r! r r r ra � s z,AsyncAdapt_oracledb_cursor.outputtypehandlerc C s || j _d S r r` �r! �valuer r r ra � s c O s | j j|i |��S r )r_ �var�r! �argsr# r r r re � s z AsyncAdapt_oracledb_cursor.varc C s | j �� | j�� d S r )�_rows�clearr_ �closerb r r r rj � s z AsyncAdapt_oracledb_cursor.closer �rg r# �returnc O s | j j|i |��S r )r_ � setinputsizesrf r r r rm � s z(AsyncAdapt_oracledb_cursor.setinputsizes)�cursorrl c C s@ z |� � W S ty: } z| j�|� W Y d }~n d }~0 0 d S r )� __enter__� ExceptionZ_adapt_connectionZ_handle_exception)r! rn �errorr r r �_aenter_cursor� s z)AsyncAdapt_oracledb_cursor._aenter_cursorc � sZ |d u r | j �|�I d H }n| j �||�I d H }| j jrV| jsVt�| j �� I d H �| _|S r )r_ �execute� description� server_side� collections�dequeZfetchallrh )r! � operation� parameters�resultr r r �_execute_async� s z)AsyncAdapt_oracledb_cursor._execute_asyncc � s | j �||�I d H S r )r_ Z executemany)r! rx Zseq_of_parametersr r r �_executemany_async s z-AsyncAdapt_oracledb_cursor._executemany_asyncc C s | S r r rb r r r ro s z$AsyncAdapt_oracledb_cursor.__enter__�None)�type_rd � tracebackrl c C s | � � d S r )rj )r! r~ rd r r r r �__exit__ s z#AsyncAdapt_oracledb_cursor.__exit__N)r r r �__annotations__� __slots__�propertyra �setterre rj rm rr r{ r| ro r� r r r r r^ � s r^ c @ s e Zd ZdZdd�dd�ZdS )� AsyncAdapt_oracledb_ss_cursorr r} �rl c C s | j d ur| j �� d | _ d S r )r_ rj rb r r r rj s z#AsyncAdapt_oracledb_ss_cursor.closeN)r r r r� rj r r r r r� s r� c @ s e Zd ZU ded< dZdZeZdZe dd� �Z e j dd� �Z e d d � �Z e j d d � �Z e d d � �Z e dd� �Zej dd� �Ze dd� �Zdd� Zdd� Zdddd�dd�Zdddd�dd �Zdddd�d d �Zdddd�d d �Zdddd�d!d"�Zdddd�d#d$�ZdS )%� AsyncAdapt_oracledb_connectionr � _connectionr TNc C s | j jS r �r� � autocommitrb r r r r� , s z)AsyncAdapt_oracledb_connection.autocommitc C s || j _d S r r� rc r r r r� 0 s c C s | j jS r �r� ra rb r r r ra 4 s z0AsyncAdapt_oracledb_connection.outputtypehandlerc C s || j _d S r r� rc r r r ra 8 s c C s | j jS r )r� r8 rb r r r r8 < s z&AsyncAdapt_oracledb_connection.versionc C s | j jS r �r� � stmtcachesizerb r r r r� @ s z,AsyncAdapt_oracledb_connection.stmtcachesizec C s || j _d S r r� rc r r r r� D s c C s | j jS r )r� rW rb r r r rW H s z4AsyncAdapt_oracledb_connection.max_identifier_lengthc C s t | �S r )r^ rb r r r rn L s z%AsyncAdapt_oracledb_connection.cursorc C s t | �S r )r� rb r r r � ss_cursorO s z(AsyncAdapt_oracledb_connection.ss_cursorr rk c O s | j j|i |��S r )r� r? rf r r r r? R s z"AsyncAdapt_oracledb_connection.xidc O s | � | jj|i |���S r )�await_r� r@ rf r r r r@ U s z(AsyncAdapt_oracledb_connection.tpc_beginc O s | � | jj|i |���S r )r� r� rL rf r r r rL X s z)AsyncAdapt_oracledb_connection.tpc_commitc O s | � | jj|i |���S r )r� r� rD rf r r r rD [ s z*AsyncAdapt_oracledb_connection.tpc_preparec O s | � | jj|i |���S r )r� r� rS rf r r r rS ^ s z*AsyncAdapt_oracledb_connection.tpc_recoverc O s | � | jj|i |���S r )r� r� rG rf r r r rG a s z+AsyncAdapt_oracledb_connection.tpc_rollback)r r r r� r� r, r^ Z _cursor_clsZ_ss_cursor_clsr� r� r� ra r8 r� rW rn r� r? r@ rL rD rS rG r r r r r� # s: r� c @ s e Zd ZdZdS )�&AsyncAdaptFallback_oracledb_connectionr N)r r r r� r r r r r� e s r� c @ s" e Zd Zdd�dd�Zdd� ZdS )�OracledbAdaptDBAPIr} r� c C s2 || _ | j j�� D ]\}}|dkr|| j|< qd S )N�connect)r �__dict__�items)r! r �k�vr r r r l s zOracledbAdaptDBAPI.__init__c O sX |� dd�}|� d| jj�}t|�r<t| t||i |����S t| t||i |����S d S )N�async_fallbackFZasync_creator_fn)�popr Z connect_asyncr r� r r� r )r! �argr$ r� Z creator_fnr r r r� s s ��zOracledbAdaptDBAPI.connectN)r r r r r� r r r r r� k s r� c @ s$ e Zd ZejjZdd� Zdd� ZdS )�$OracleExecutionContextAsync_oracledbc C s | j �� }| jjr | jj|_|S r )�_dbapi_connectionrn �dialectr" �r! �cr r r �create_default_cursor� s z:OracleExecutionContextAsync_oracledb.create_default_cursorc C s | j �� }| jjr | jj|_|S r )r� r� r� r" r� r r r �create_server_side_cursor� s z>OracleExecutionContextAsync_oracledb.create_server_side_cursorN)r r r r ZDefaultExecutionContextZ create_cursorr� r� r r r r r� � s r� c @ s@ e Zd ZdZdZdZeZdZe dd� �Z e dd� �Z dd� Z d S ) r. T)r5 c C s dd l }t|�S r' )r r� r( r r r r* � s z(OracleDialectAsync_oracledb.import_dbapic C s& |j �dd�}t|�r tjS tjS d S )Nr� F)�query�getr r Z FallbackAsyncAdaptedQueuePoolZAsyncAdaptedQueuePool)r) r/ r� r r r �get_pool_class� s z*OracleDialectAsync_oracledb.get_pool_classc C s |j S r )r� rT r r r �get_driver_connection� s z1OracleDialectAsync_oracledb.get_driver_connectionN) r r r �is_asyncZ supports_server_side_cursorsrZ r� r[ r< r\ r* r� r� r r r r r. � s r. )(�__doc__� __future__r rv r6 �typingr r � r Z _cx_oracler r Zconnectors.asyncior r r r Zenginer �utilr r r r r r Z OracleExecutionContext_cx_oracler ZOracleDialect_cx_oracler r^ r� r� r� r� r� r. r� Z dialect_asyncr r r r �<module> sP N �p7 � B � sqlalchemy/dialects/oracle/__pycache__/vector.cpython-39.pyc 0000644 00000016562 15125143220 0020113 0 ustar 00 a ��Jh� � @ s� d dl mZ d dlZd dlmZ d dlmZ d dlmZ d dl m Z d dl m Z G dd� de�Z G d d � d e�Z G d d � d e�ZeG d d� d��ZG dd� de j�ZdS )� )� annotationsN)� dataclass)�Enum)�Optional)�Floatc @ s e Zd ZdZdZdZdS )�VectorIndexTypez�Enum representing different types of VECTOR index structures. See :ref:`oracle_vector_datatype` for background. .. versionadded:: 2.0.41 �HNSW�IVFN)�__name__� __module__� __qualname__�__doc__r r � r r �V/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/oracle/vector.pyr s r c @ s e Zd ZdZdZdZdZdZdS )�VectorDistanceTypez�Enum representing different types of vector distance metrics. See :ref:`oracle_vector_datatype` for background. .. versionadded:: 2.0.41 � EUCLIDEAN�DOT�COSINE� MANHATTANN)r r r r r r r r r r r r r ( s r c @ s e Zd ZdZdZdZdZdZdS )�VectorStorageFormatz�Enum representing the data format used to store vector components. See :ref:`oracle_vector_datatype` for background. .. versionadded:: 2.0.41 �INT8�BINARY�FLOAT32�FLOAT64N)r r r r r r r r r r r r r G s r c @ s� e Zd ZU dZejZded< dZded< dZ ded< dZ ded < dZ ded < dZ ded < dZ ded < dZded < dZded< dd� ZdS )�VectorIndexConfiga� Define the configuration for Oracle VECTOR Index. See :ref:`oracle_vector_datatype` for background. .. versionadded:: 2.0.41 :param index_type: Enum value from :class:`.VectorIndexType` Specifies the indexing method. For HNSW, this must be :attr:`.VectorIndexType.HNSW`. :param distance: Enum value from :class:`.VectorDistanceType` specifies the metric for calculating distance between VECTORS. :param accuracy: interger. Should be in the range 0 to 100 Specifies the accuracy of the nearest neighbor search during query execution. :param parallel: integer. Specifies degree of parallelism. :param hnsw_neighbors: interger. Should be in the range 0 to 2048. Specifies the number of nearest neighbors considered during the search. The attribute :attr:`.VectorIndexConfig.hnsw_neighbors` is HNSW index specific. :param hnsw_efconstruction: integer. Should be in the range 0 to 65535. Controls the trade-off between indexing speed and recall quality during index construction. The attribute :attr:`.VectorIndexConfig.hnsw_efconstruction` is HNSW index specific. :param ivf_neighbor_partitions: integer. Should be in the range 0 to 10,000,000. Specifies the number of partitions used to divide the dataset. The attribute :attr:`.VectorIndexConfig.ivf_neighbor_partitions` is IVF index specific. :param ivf_sample_per_partition: integer. Should be between 1 and ``num_vectors / neighbor partitions``. Specifies the number of samples used per partition. The attribute :attr:`.VectorIndexConfig.ivf_sample_per_partition` is IVF index specific. :param ivf_min_vectors_per_partition: integer. From 0 (no trimming) to the total number of vectors (results in 1 partition). Specifies the minimum number of vectors per partition. The attribute :attr:`.VectorIndexConfig.ivf_min_vectors_per_partition` is IVF index specific. r � index_typeNz Optional[VectorDistanceType]�distancez Optional[int]�accuracy�hnsw_neighbors�hnsw_efconstruction�ivf_neighbor_partitions�ivf_sample_per_partition� ivf_min_vectors_per_partition�parallelc C sN t | j�| _dD ]8}t| |�}|d urt|t�st|� dt|�j� ���qd S )N)r r r r! r" r# r z$ must be an integer ifprovided, got )r r �getattr� isinstance�int� TypeError�typer )�self�field�valuer r r � __post_init__� s ��z VectorIndexConfig.__post_init__)r r r r r r r �__annotations__r r r r r r! r" r# r, r r r r r b s 2 r c @ sj e Zd ZdZdZd Zejdejdej dej diZ ddd �Z d d � Z d d � Zdd� ZG dd� dejj�ZdS )�VECTORz�Oracle VECTOR datatype. For complete background on using this type, see :ref:`oracle_vector_datatype`. .. versionadded:: 2.0.41 T�b�B�f�dNc C sD |durt |t�std��|dur4t |t�s4td��|| _|| _dS )aP Construct a VECTOR. :param dim: integer. The dimension of the VECTOR datatype. This should be an integer value. :param storage_format: VectorStorageFormat. The VECTOR storage type format. This may be Enum values form :class:`.VectorStorageFormat` INT8, BINARY, FLOAT32, or FLOAT64. Nzdim must be an intergerz:storage_format must be an enum of type VectorStorageFormat)r% r& r' r �dim�storage_format)r) r3 r4 r r r �__init__� s ��zVECTOR.__init__c s � fdd�}|S )zT Convert a list to a array.array before binding it to the database. c sJ | d u st | tj�r| S t | t�r>� �� j�}t�|| �} | S td��d S )Nz$VECTOR accepts list or array.array())r% �array�list�_array_typecoder4 r' )r+ �typecode�r) r r �process� s z.VECTOR._cached_bind_processor.<locals>.processr )r) �dialectr; r r: r �_cached_bind_processor� s z VECTOR._cached_bind_processorc C s dd� }|S )zR Convert a array.array to list before binding it to the database. c S s t | tj�rt| �S d S )N)r% r6 r7 )r+ r r r r; � s z0VECTOR._cached_result_processor.<locals>.processr )r) r< Zcoltyper; r r r �_cached_result_processor� s z VECTOR._cached_result_processorc C s | j �|d�S )z7 Map storage format to array typecode. r2 )� _typecode_map�get)r) r9 r r r r8 � s zVECTOR._array_typecodec @ s$ e Zd Zdd� Zdd� Zdd� ZdS )zVECTOR.comparator_factoryc C s | j dtd�|�S )Nz<->�� return_type��opr �r) �otherr r r � l2_distance s z%VECTOR.comparator_factory.l2_distancec C s | j dtd�|�S )Nz<#>rA rC rE r r r � inner_product s z'VECTOR.comparator_factory.inner_productc C s | j dtd�|�S )Nz<=>rA rC rE r r r �cosine_distance s z)VECTOR.comparator_factory.cosine_distanceN)r r r rG rH rI r r r r �comparator_factory s rJ )NN)r r r r Zcache_okZ__visit_name__r r r r r r? r5 r= r> r8 �types� TypeEngineZ ComparatorrJ r r r r r. � s � r. )� __future__r r6 Z dataclassesr �enumr �typingr Zsqlalchemy.typesrK r r r r r rL r. r r r r �<module> s P sqlalchemy/dialects/oracle/__pycache__/base.cpython-39.pyc 0000644 00000303370 15125143220 0017517 0 ustar 00 a ��Jha � @ s� d Z ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z ddl Z dd l m Z dd l mZ dd l mZ dd l mZ dd l mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl m Z ddl m Z ddl m Z ddl m Z dd l m!Z! dd l m"Z" d d l m#Z# d d l m$Z$ d d!l m%Z& d d"l m'Z' d d#l m(Z( d d$l)m*Z* d d%l)m+Z+ d d&l)m,Z, d d'l)m-Z- d d(l.m/Z/ d d)l'm0Z0 d d*l'm1Z1 d d+l'm2Z2 d d,l'm3Z3 d d-l'm4Z4 d d.l'm5Z5 d d/l'm6Z6 d d0l'm7Z7 d d1l'm8Z9 d d2l'm:Z: d d#l'm(Z; d d3l'm<Z< d d4l=m>Z> d d5l m?Z? d d6l m@Z@ d d7l mAZA d d8l mBZB d d9l mCZC d d:l mDZD d d;l mEZE d d<l mFZF d d=l mGZG eHd>�I� �ZJeHd?�I� �ZKe:jLee:jMee:jNee:jOeiZPeGeEe@eDeee?eeAee e e eeeeBeFeeee e d@�ZQG dAdB� dBe2jR�ZSG dCdD� dDe2jT�ZUG dEdF� dFe2jV�ZWG dGdH� dHe2jX�ZYG dIdJ� dJe*jZ�Z[G dKdL� dLe*j\�Z]G dMdN� dNe'j^�Z_dS )Oa�� .. dialect:: oracle :name: Oracle Database :normal_support: 11+ :best_effort: 9+ Auto Increment Behavior ----------------------- SQLAlchemy Table objects which include integer primary keys are usually assumed to have "autoincrementing" behavior, meaning they can generate their own primary key values upon INSERT. For use within Oracle Database, two options are available, which are the use of IDENTITY columns (Oracle Database 12 and above only) or the association of a SEQUENCE with the column. Specifying GENERATED AS IDENTITY (Oracle Database 12 and above) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Starting from version 12, Oracle Database can make use of identity columns using the :class:`_sql.Identity` to specify the autoincrementing behavior:: t = Table( "mytable", metadata, Column("id", Integer, Identity(start=3), primary_key=True), Column(...), ..., ) The CREATE TABLE for the above :class:`_schema.Table` object would be: .. sourcecode:: sql CREATE TABLE mytable ( id INTEGER GENERATED BY DEFAULT AS IDENTITY (START WITH 3), ..., PRIMARY KEY (id) ) The :class:`_schema.Identity` object support many options to control the "autoincrementing" behavior of the column, like the starting value, the incrementing value, etc. In addition to the standard options, Oracle Database supports setting :paramref:`_schema.Identity.always` to ``None`` to use the default generated mode, rendering GENERATED AS IDENTITY in the DDL. It also supports setting :paramref:`_schema.Identity.on_null` to ``True`` to specify ON NULL in conjunction with a 'BY DEFAULT' identity column. Using a SEQUENCE (all Oracle Database versions) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Older version of Oracle Database had no "autoincrement" feature: SQLAlchemy relies upon sequences to produce these values. With the older Oracle Database versions, *a sequence must always be explicitly specified to enable autoincrement*. This is divergent with the majority of documentation examples which assume the usage of an autoincrement-capable database. To specify sequences, use the sqlalchemy.schema.Sequence object which is passed to a Column construct:: t = Table( "mytable", metadata, Column("id", Integer, Sequence("id_seq", start=1), primary_key=True), Column(...), ..., ) This step is also required when using table reflection, i.e. autoload_with=engine:: t = Table( "mytable", metadata, Column("id", Integer, Sequence("id_seq", start=1), primary_key=True), autoload_with=engine, ) .. versionchanged:: 1.4 Added :class:`_schema.Identity` construct in a :class:`_schema.Column` to specify the option of an autoincrementing column. .. _oracle_isolation_level: Transaction Isolation Level / Autocommit ---------------------------------------- Oracle Database supports "READ COMMITTED" and "SERIALIZABLE" modes of isolation. The AUTOCOMMIT isolation level is also supported by the python-oracledb and cx_Oracle dialects. To set using per-connection execution options:: connection = engine.connect() connection = connection.execution_options(isolation_level="AUTOCOMMIT") For ``READ COMMITTED`` and ``SERIALIZABLE``, the Oracle Database dialects sets the level at the session level using ``ALTER SESSION``, which is reverted back to its default setting when the connection is returned to the connection pool. Valid values for ``isolation_level`` include: * ``READ COMMITTED`` * ``AUTOCOMMIT`` * ``SERIALIZABLE`` .. note:: The implementation for the :meth:`_engine.Connection.get_isolation_level` method as implemented by the Oracle Database dialects necessarily force the start of a transaction using the Oracle Database DBMS_TRANSACTION.LOCAL_TRANSACTION_ID function; otherwise no level is normally readable. Additionally, the :meth:`_engine.Connection.get_isolation_level` method will raise an exception if the ``v$transaction`` view is not available due to permissions or other reasons, which is a common occurrence in Oracle Database installations. The python-oracledb and cx_Oracle dialects attempt to call the :meth:`_engine.Connection.get_isolation_level` method when the dialect makes its first connection to the database in order to acquire the "default"isolation level. This default level is necessary so that the level can be reset on a connection after it has been temporarily modified using :meth:`_engine.Connection.execution_options` method. In the common event that the :meth:`_engine.Connection.get_isolation_level` method raises an exception due to ``v$transaction`` not being readable as well as any other database-related failure, the level is assumed to be "READ COMMITTED". No warning is emitted for this initial first-connect condition as it is expected to be a common restriction on Oracle databases. .. versionadded:: 1.3.16 added support for AUTOCOMMIT to the cx_Oracle dialect as well as the notion of a default isolation level .. versionadded:: 1.3.21 Added support for SERIALIZABLE as well as live reading of the isolation level. .. versionchanged:: 1.3.22 In the event that the default isolation level cannot be read due to permissions on the v$transaction view as is common in Oracle installations, the default isolation level is hardcoded to "READ COMMITTED" which was the behavior prior to 1.3.21. .. seealso:: :ref:`dbapi_autocommit` Identifier Casing ----------------- In Oracle Database, the data dictionary represents all case insensitive identifier names using UPPERCASE text. This is in contradiction to the expectations of SQLAlchemy, which assume a case insensitive name is represented as lowercase text. As an example of case insensitive identifier names, consider the following table: .. sourcecode:: sql CREATE TABLE MyTable (Identifier INTEGER PRIMARY KEY) If you were to ask Oracle Database for information about this table, the table name would be reported as ``MYTABLE`` and the column name would be reported as ``IDENTIFIER``. Compare to most other databases such as PostgreSQL and MySQL which would report these names as ``mytable`` and ``identifier``. The names are **not quoted, therefore are case insensitive**. The special casing of ``MyTable`` and ``Identifier`` would only be maintained if they were quoted in the table definition: .. sourcecode:: sql CREATE TABLE "MyTable" ("Identifier" INTEGER PRIMARY KEY) When constructing a SQLAlchemy :class:`.Table` object, **an all lowercase name is considered to be case insensitive**. So the following table assumes case insensitive names:: Table("mytable", metadata, Column("identifier", Integer, primary_key=True)) Whereas when mixed case or UPPERCASE names are used, case sensitivity is assumed:: Table("MyTable", metadata, Column("Identifier", Integer, primary_key=True)) A similar situation occurs at the database driver level when emitting a textual SQL SELECT statement and looking at column names in the DBAPI ``cursor.description`` attribute. A database like PostgreSQL will normalize case insensitive names to be lowercase:: >>> pg_engine = create_engine("postgresql://scott:tiger@localhost/test") >>> pg_connection = pg_engine.connect() >>> result = pg_connection.exec_driver_sql("SELECT 1 AS SomeName") >>> result.cursor.description (Column(name='somename', type_code=23),) Whereas Oracle normalizes them to UPPERCASE:: >>> oracle_engine = create_engine("oracle+oracledb://scott:tiger@oracle18c/xe") >>> oracle_connection = oracle_engine.connect() >>> result = oracle_connection.exec_driver_sql( ... "SELECT 1 AS SomeName FROM DUAL" ... ) >>> result.cursor.description [('SOMENAME', <DbType DB_TYPE_NUMBER>, 127, None, 0, -127, True)] In order to achieve cross-database parity for the two cases of a. table reflection and b. textual-only SQL statement round trips, SQLAlchemy performs a step called **name normalization** when using the Oracle dialect. This process may also apply to other third party dialects that have similar UPPERCASE handling of case insensitive names. When using name normalization, SQLAlchemy attempts to detect if a name is case insensitive by checking if all characters are UPPERCASE letters only; if so, then it assumes this is a case insensitive name and is delivered as a lowercase name. For table reflection, a tablename that is seen represented as all UPPERCASE in Oracle Database's catalog tables will be assumed to have a case insensitive name. This is what allows the ``Table`` definition to use lower case names and be equally compatible from a reflection point of view on Oracle Database and all other databases such as PostgreSQL and MySQL:: # matches a table created with CREATE TABLE mytable Table("mytable", metadata, autoload_with=some_engine) Above, the all lowercase name ``"mytable"`` is case insensitive; it will match a table reported by PostgreSQL as ``"mytable"`` and a table reported by Oracle as ``"MYTABLE"``. If name normalization were not present, it would not be possible for the above :class:`.Table` definition to be introspectable in a cross-database way, since we are dealing with a case insensitive name that is not reported by each database in the same way. Case sensitivity can be forced on in this case, such as if we wanted to represent the quoted tablename ``"MYTABLE"`` with that exact casing, most simply by using that casing directly, which will be seen as a case sensitive name:: # matches a table created with CREATE TABLE "MYTABLE" Table("MYTABLE", metadata, autoload_with=some_engine) For the unusual case of a quoted all-lowercase name, the :class:`.quoted_name` construct may be used:: from sqlalchemy import quoted_name # matches a table created with CREATE TABLE "mytable" Table( quoted_name("mytable", quote=True), metadata, autoload_with=some_engine ) Name normalization also takes place when handling result sets from **purely textual SQL strings**, that have no other :class:`.Table` or :class:`.Column` metadata associated with them. This includes SQL strings executed using :meth:`.Connection.exec_driver_sql` and SQL strings executed using the :func:`.text` construct which do not include :class:`.Column` metadata. Returning to the Oracle Database SELECT statement, we see that even though ``cursor.description`` reports the column name as ``SOMENAME``, SQLAlchemy name normalizes this to ``somename``:: >>> oracle_engine = create_engine("oracle+oracledb://scott:tiger@oracle18c/xe") >>> oracle_connection = oracle_engine.connect() >>> result = oracle_connection.exec_driver_sql( ... "SELECT 1 AS SomeName FROM DUAL" ... ) >>> result.cursor.description [('SOMENAME', <DbType DB_TYPE_NUMBER>, 127, None, 0, -127, True)] >>> result.keys() RMKeyView(['somename']) The single scenario where the above behavior produces inaccurate results is when using an all-uppercase, quoted name. SQLAlchemy has no way to determine that a particular name in ``cursor.description`` was quoted, and is therefore case sensitive, or was not quoted, and should be name normalized:: >>> result = oracle_connection.exec_driver_sql( ... 'SELECT 1 AS "SOMENAME" FROM DUAL' ... ) >>> result.cursor.description [('SOMENAME', <DbType DB_TYPE_NUMBER>, 127, None, 0, -127, True)] >>> result.keys() RMKeyView(['somename']) For this case, a new feature will be available in SQLAlchemy 2.1 to disable the name normalization behavior in specific cases. .. _oracle_max_identifier_lengths: Maximum Identifier Lengths -------------------------- SQLAlchemy is sensitive to the maximum identifier length supported by Oracle Database. This affects generated SQL label names as well as the generation of constraint names, particularly in the case where the constraint naming convention feature described at :ref:`constraint_naming_conventions` is being used. Oracle Database 12.2 increased the default maximum identifier length from 30 to 128. As of SQLAlchemy 1.4, the default maximum identifier length for the Oracle dialects is 128 characters. Upon first connection, the maximum length actually supported by the database is obtained. In all cases, setting the :paramref:`_sa.create_engine.max_identifier_length` parameter will bypass this change and the value given will be used as is:: engine = create_engine( "oracle+oracledb://scott:tiger@localhost:1521?service_name=freepdb1", max_identifier_length=30, ) If :paramref:`_sa.create_engine.max_identifier_length` is not set, the oracledb dialect internally uses the ``max_identifier_length`` attribute available on driver connections since python-oracledb version 2.5. When using an older driver version, or using the cx_Oracle dialect, SQLAlchemy will instead attempt to use the query ``SELECT value FROM v$parameter WHERE name = 'compatible'`` upon first connect in order to determine the effective compatibility version of the database. The "compatibility" version is a version number that is independent of the actual database version. It is used to assist database migration. It is configured by an Oracle Database initialization parameter. The compatibility version then determines the maximum allowed identifier length for the database. If the V$ view is not available, the database version information is used instead. The maximum identifier length comes into play both when generating anonymized SQL labels in SELECT statements, but more crucially when generating constraint names from a naming convention. It is this area that has created the need for SQLAlchemy to change this default conservatively. For example, the following naming convention produces two very different constraint names based on the identifier length:: from sqlalchemy import Column from sqlalchemy import Index from sqlalchemy import Integer from sqlalchemy import MetaData from sqlalchemy import Table from sqlalchemy.dialects import oracle from sqlalchemy.schema import CreateIndex m = MetaData(naming_convention={"ix": "ix_%(column_0N_name)s"}) t = Table( "t", m, Column("some_column_name_1", Integer), Column("some_column_name_2", Integer), Column("some_column_name_3", Integer), ) ix = Index( None, t.c.some_column_name_1, t.c.some_column_name_2, t.c.some_column_name_3, ) oracle_dialect = oracle.dialect(max_identifier_length=30) print(CreateIndex(ix).compile(dialect=oracle_dialect)) With an identifier length of 30, the above CREATE INDEX looks like: .. sourcecode:: sql CREATE INDEX ix_some_column_name_1s_70cd ON t (some_column_name_1, some_column_name_2, some_column_name_3) However with length of 128, it becomes:: .. sourcecode:: sql CREATE INDEX ix_some_column_name_1some_column_name_2some_column_name_3 ON t (some_column_name_1, some_column_name_2, some_column_name_3) Applications which have run versions of SQLAlchemy prior to 1.4 on Oracle Database version 12.2 or greater are therefore subject to the scenario of a database migration that wishes to "DROP CONSTRAINT" on a name that was previously generated with the shorter length. This migration will fail when the identifier length is changed without the name of the index or constraint first being adjusted. Such applications are strongly advised to make use of :paramref:`_sa.create_engine.max_identifier_length` in order to maintain control of the generation of truncated names, and to fully review and test all database migrations in a staging environment when changing this value to ensure that the impact of this change has been mitigated. .. versionchanged:: 1.4 the default max_identifier_length for Oracle Database is 128 characters, which is adjusted down to 30 upon first connect if the Oracle Database, or its compatibility setting, are lower than version 12.2. LIMIT/OFFSET/FETCH Support -------------------------- Methods like :meth:`_sql.Select.limit` and :meth:`_sql.Select.offset` make use of ``FETCH FIRST N ROW / OFFSET N ROWS`` syntax assuming Oracle Database 12c or above, and assuming the SELECT statement is not embedded within a compound statement like UNION. This syntax is also available directly by using the :meth:`_sql.Select.fetch` method. .. versionchanged:: 2.0 the Oracle Database dialects now use ``FETCH FIRST N ROW / OFFSET N ROWS`` for all :meth:`_sql.Select.limit` and :meth:`_sql.Select.offset` usage including within the ORM and legacy :class:`_orm.Query`. To force the legacy behavior using window functions, specify the ``enable_offset_fetch=False`` dialect parameter to :func:`_sa.create_engine`. The use of ``FETCH FIRST / OFFSET`` may be disabled on any Oracle Database version by passing ``enable_offset_fetch=False`` to :func:`_sa.create_engine`, which will force the use of "legacy" mode that makes use of window functions. This mode is also selected automatically when using a version of Oracle Database prior to 12c. When using legacy mode, or when a :class:`.Select` statement with limit/offset is embedded in a compound statement, an emulated approach for LIMIT / OFFSET based on window functions is used, which involves creation of a subquery using ``ROW_NUMBER`` that is prone to performance issues as well as SQL construction issues for complex statements. However, this approach is supported by all Oracle Database versions. See notes below. Notes on LIMIT / OFFSET emulation (when fetch() method cannot be used) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If using :meth:`_sql.Select.limit` and :meth:`_sql.Select.offset`, or with the ORM the :meth:`_orm.Query.limit` and :meth:`_orm.Query.offset` methods on an Oracle Database version prior to 12c, the following notes apply: * SQLAlchemy currently makes use of ROWNUM to achieve LIMIT/OFFSET; the exact methodology is taken from https://blogs.oracle.com/oraclemagazine/on-rownum-and-limiting-results . * the "FIRST_ROWS()" optimization keyword is not used by default. To enable the usage of this optimization directive, specify ``optimize_limits=True`` to :func:`_sa.create_engine`. .. versionchanged:: 1.4 The Oracle Database dialect renders limit/offset integer values using a "post compile" scheme which renders the integer directly before passing the statement to the cursor for execution. The ``use_binds_for_limits`` flag no longer has an effect. .. seealso:: :ref:`change_4808`. .. _oracle_returning: RETURNING Support ----------------- Oracle Database supports RETURNING fully for INSERT, UPDATE and DELETE statements that are invoked with a single collection of bound parameters (that is, a ``cursor.execute()`` style statement; SQLAlchemy does not generally support RETURNING with :term:`executemany` statements). Multiple rows may be returned as well. .. versionchanged:: 2.0 the Oracle Database backend has full support for RETURNING on parity with other backends. ON UPDATE CASCADE ----------------- Oracle Database doesn't have native ON UPDATE CASCADE functionality. A trigger based solution is available at https://web.archive.org/web/20090317041251/https://asktom.oracle.com/tkyte/update_cascade/index.html When using the SQLAlchemy ORM, the ORM has limited ability to manually issue cascading updates - specify ForeignKey objects using the "deferrable=True, initially='deferred'" keyword arguments, and specify "passive_updates=False" on each relationship(). Oracle Database 8 Compatibility ------------------------------- .. warning:: The status of Oracle Database 8 compatibility is not known for SQLAlchemy 2.0. When Oracle Database 8 is detected, the dialect internally configures itself to the following behaviors: * the use_ansi flag is set to False. This has the effect of converting all JOIN phrases into the WHERE clause, and in the case of LEFT OUTER JOIN makes use of Oracle's (+) operator. * the NVARCHAR2 and NCLOB datatypes are no longer generated as DDL when the :class:`~sqlalchemy.types.Unicode` is used - VARCHAR2 and CLOB are issued instead. This because these types don't seem to work correctly on Oracle 8 even though they are available. The :class:`~sqlalchemy.types.NVARCHAR` and :class:`~sqlalchemy.dialects.oracle.NCLOB` types will always generate NVARCHAR2 and NCLOB. Synonym/DBLINK Reflection ------------------------- When using reflection with Table objects, the dialect can optionally search for tables indicated by synonyms, either in local or remote schemas or accessed over DBLINK, by passing the flag ``oracle_resolve_synonyms=True`` as a keyword argument to the :class:`_schema.Table` construct:: some_table = Table( "some_table", autoload_with=some_engine, oracle_resolve_synonyms=True ) When this flag is set, the given name (such as ``some_table`` above) will be searched not just in the ``ALL_TABLES`` view, but also within the ``ALL_SYNONYMS`` view to see if this name is actually a synonym to another name. If the synonym is located and refers to a DBLINK, the Oracle Database dialects know how to locate the table's information using DBLINK syntax(e.g. ``@dblink``). ``oracle_resolve_synonyms`` is accepted wherever reflection arguments are accepted, including methods such as :meth:`_schema.MetaData.reflect` and :meth:`_reflection.Inspector.get_columns`. If synonyms are not in use, this flag should be left disabled. .. _oracle_constraint_reflection: Constraint Reflection --------------------- The Oracle Database dialects can return information about foreign key, unique, and CHECK constraints, as well as indexes on tables. Raw information regarding these constraints can be acquired using :meth:`_reflection.Inspector.get_foreign_keys`, :meth:`_reflection.Inspector.get_unique_constraints`, :meth:`_reflection.Inspector.get_check_constraints`, and :meth:`_reflection.Inspector.get_indexes`. .. versionchanged:: 1.2 The Oracle Database dialect can now reflect UNIQUE and CHECK constraints. When using reflection at the :class:`_schema.Table` level, the :class:`_schema.Table` will also include these constraints. Note the following caveats: * When using the :meth:`_reflection.Inspector.get_check_constraints` method, Oracle Database builds a special "IS NOT NULL" constraint for columns that specify "NOT NULL". This constraint is **not** returned by default; to include the "IS NOT NULL" constraints, pass the flag ``include_all=True``:: from sqlalchemy import create_engine, inspect engine = create_engine( "oracle+oracledb://scott:tiger@localhost:1521?service_name=freepdb1" ) inspector = inspect(engine) all_check_constraints = inspector.get_check_constraints( "some_table", include_all=True ) * in most cases, when reflecting a :class:`_schema.Table`, a UNIQUE constraint will **not** be available as a :class:`.UniqueConstraint` object, as Oracle Database mirrors unique constraints with a UNIQUE index in most cases (the exception seems to be when two or more unique constraints represent the same columns); the :class:`_schema.Table` will instead represent these using :class:`.Index` with the ``unique=True`` flag set. * Oracle Database creates an implicit index for the primary key of a table; this index is **excluded** from all index results. * the list of columns reflected for an index will not include column names that start with SYS_NC. Table names with SYSTEM/SYSAUX tablespaces ------------------------------------------- The :meth:`_reflection.Inspector.get_table_names` and :meth:`_reflection.Inspector.get_temp_table_names` methods each return a list of table names for the current engine. These methods are also part of the reflection which occurs within an operation such as :meth:`_schema.MetaData.reflect`. By default, these operations exclude the ``SYSTEM`` and ``SYSAUX`` tablespaces from the operation. In order to change this, the default list of tablespaces excluded can be changed at the engine level using the ``exclude_tablespaces`` parameter:: # exclude SYSAUX and SOME_TABLESPACE, but not SYSTEM e = create_engine( "oracle+oracledb://scott:tiger@localhost:1521/?service_name=freepdb1", exclude_tablespaces=["SYSAUX", "SOME_TABLESPACE"], ) .. _oracle_float_support: FLOAT / DOUBLE Support and Behaviors ------------------------------------ The SQLAlchemy :class:`.Float` and :class:`.Double` datatypes are generic datatypes that resolve to the "least surprising" datatype for a given backend. For Oracle Database, this means they resolve to the ``FLOAT`` and ``DOUBLE`` types:: >>> from sqlalchemy import cast, literal, Float >>> from sqlalchemy.dialects import oracle >>> float_datatype = Float() >>> print(cast(literal(5.0), float_datatype).compile(dialect=oracle.dialect())) CAST(:param_1 AS FLOAT) Oracle's ``FLOAT`` / ``DOUBLE`` datatypes are aliases for ``NUMBER``. Oracle Database stores ``NUMBER`` values with full precision, not floating point precision, which means that ``FLOAT`` / ``DOUBLE`` do not actually behave like native FP values. Oracle Database instead offers special datatypes ``BINARY_FLOAT`` and ``BINARY_DOUBLE`` to deliver real 4- and 8- byte FP values. SQLAlchemy supports these datatypes directly using :class:`.BINARY_FLOAT` and :class:`.BINARY_DOUBLE`. To use the :class:`.Float` or :class:`.Double` datatypes in a database agnostic way, while allowing Oracle backends to utilize one of these types, use the :meth:`.TypeEngine.with_variant` method to set up a variant:: >>> from sqlalchemy import cast, literal, Float >>> from sqlalchemy.dialects import oracle >>> float_datatype = Float().with_variant(oracle.BINARY_FLOAT(), "oracle") >>> print(cast(literal(5.0), float_datatype).compile(dialect=oracle.dialect())) CAST(:param_1 AS BINARY_FLOAT) E.g. to use this datatype in a :class:`.Table` definition:: my_table = Table( "my_table", metadata, Column( "fp_data", Float().with_variant(oracle.BINARY_FLOAT(), "oracle") ), ) DateTime Compatibility ---------------------- Oracle Database has no datatype known as ``DATETIME``, it instead has only ``DATE``, which can actually store a date and time value. For this reason, the Oracle Database dialects provide a type :class:`_oracle.DATE` which is a subclass of :class:`.DateTime`. This type has no special behavior, and is only present as a "marker" for this type; additionally, when a database column is reflected and the type is reported as ``DATE``, the time-supporting :class:`_oracle.DATE` type is used. .. _oracle_table_options: Oracle Database Table Options ----------------------------- The CREATE TABLE phrase supports the following options with Oracle Database dialects in conjunction with the :class:`_schema.Table` construct: * ``ON COMMIT``:: Table( "some_table", metadata, ..., prefixes=["GLOBAL TEMPORARY"], oracle_on_commit="PRESERVE ROWS", ) * ``COMPRESS``:: Table( "mytable", metadata, Column("data", String(32)), oracle_compress=True ) Table("mytable", metadata, Column("data", String(32)), oracle_compress=6) The ``oracle_compress`` parameter accepts either an integer compression level, or ``True`` to use the default compression level. * ``TABLESPACE``:: Table("mytable", metadata, ..., oracle_tablespace="EXAMPLE_TABLESPACE") The ``oracle_tablespace`` parameter specifies the tablespace in which the table is to be created. This is useful when you want to create a table in a tablespace other than the default tablespace of the user. .. versionadded:: 2.0.37 .. _oracle_index_options: Oracle Database Specific Index Options -------------------------------------- Bitmap Indexes ~~~~~~~~~~~~~~ You can specify the ``oracle_bitmap`` parameter to create a bitmap index instead of a B-tree index:: Index("my_index", my_table.c.data, oracle_bitmap=True) Bitmap indexes cannot be unique and cannot be compressed. SQLAlchemy will not check for such limitations, only the database will. Index compression ~~~~~~~~~~~~~~~~~ Oracle Database has a more efficient storage mode for indexes containing lots of repeated values. Use the ``oracle_compress`` parameter to turn on key compression:: Index("my_index", my_table.c.data, oracle_compress=True) Index( "my_index", my_table.c.data1, my_table.c.data2, unique=True, oracle_compress=1, ) The ``oracle_compress`` parameter accepts either an integer specifying the number of prefix columns to compress, or ``True`` to use the default (all columns for non-unique indexes, all but the last column for unique indexes). .. _oracle_vector_datatype: VECTOR Datatype --------------- Oracle Database 23ai introduced a new VECTOR datatype for artificial intelligence and machine learning search operations. The VECTOR datatype is a homogeneous array of 8-bit signed integers, 8-bit unsigned integers (binary), 32-bit floating-point numbers, or 64-bit floating-point numbers. .. seealso:: `Using VECTOR Data <https://python-oracledb.readthedocs.io/en/latest/user_guide/vector_data_type.html>`_ - in the documentation for the :ref:`oracledb` driver. .. versionadded:: 2.0.41 CREATE TABLE support for VECTOR ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ With the :class:`.VECTOR` datatype, you can specify the dimension for the data and the storage format. Valid values for storage format are enum values from :class:`.VectorStorageFormat`. To create a table that includes a :class:`.VECTOR` column:: from sqlalchemy.dialects.oracle import VECTOR, VectorStorageFormat t = Table( "t1", metadata, Column("id", Integer, primary_key=True), Column( "embedding", VECTOR(dim=3, storage_format=VectorStorageFormat.FLOAT32), ), Column(...), ..., ) Vectors can also be defined with an arbitrary number of dimensions and formats. This allows you to specify vectors of different dimensions with the various storage formats mentioned above. **Examples** * In this case, the storage format is flexible, allowing any vector type data to be inserted, such as INT8 or BINARY etc:: vector_col: Mapped[array.array] = mapped_column(VECTOR(dim=3)) * The dimension is flexible in this case, meaning that any dimension vector can be used:: vector_col: Mapped[array.array] = mapped_column( VECTOR(storage_format=VectorStorageType.INT8) ) * Both the dimensions and the storage format are flexible:: vector_col: Mapped[array.array] = mapped_column(VECTOR) Python Datatypes for VECTOR ~~~~~~~~~~~~~~~~~~~~~~~~~~~ VECTOR data can be inserted using Python list or Python ``array.array()`` objects. Python arrays of type FLOAT (32-bit), DOUBLE (64-bit), or INT (8-bit signed integer) are used as bind values when inserting VECTOR columns:: from sqlalchemy import insert, select with engine.begin() as conn: conn.execute( insert(t1), {"id": 1, "embedding": [1, 2, 3]}, ) VECTOR Indexes ~~~~~~~~~~~~~~ The VECTOR feature supports an Oracle-specific parameter ``oracle_vector`` on the :class:`.Index` construct, which allows the construction of VECTOR indexes. To utilize VECTOR indexing, set the ``oracle_vector`` parameter to True to use the default values provided by Oracle. HNSW is the default indexing method:: from sqlalchemy import Index Index( "vector_index", t1.c.embedding, oracle_vector=True, ) The full range of parameters for vector indexes are available by using the :class:`.VectorIndexConfig` dataclass in place of a boolean; this dataclass allows full configuration of the index:: Index( "hnsw_vector_index", t1.c.embedding, oracle_vector=VectorIndexConfig( index_type=VectorIndexType.HNSW, distance=VectorDistanceType.COSINE, accuracy=90, hnsw_neighbors=5, hnsw_efconstruction=20, parallel=10, ), ) Index( "ivf_vector_index", t1.c.embedding, oracle_vector=VectorIndexConfig( index_type=VectorIndexType.IVF, distance=VectorDistanceType.DOT, accuracy=90, ivf_neighbor_partitions=5, ), ) For complete explanation of these parameters, see the Oracle documentation linked below. .. seealso:: `CREATE VECTOR INDEX <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-B396C369-54BB-4098-A0DD-7C54B3A0D66F>`_ - in the Oracle documentation Similarity Searching ~~~~~~~~~~~~~~~~~~~~ When using the :class:`_oracle.VECTOR` datatype with a :class:`.Column` or similar ORM mapped construct, additional comparison functions are available, including: * ``l2_distance`` * ``cosine_distance`` * ``inner_product`` Example Usage:: result_vector = connection.scalars( select(t1).order_by(t1.embedding.l2_distance([2, 3, 4])).limit(3) ) for user in vector: print(user.id, user.embedding) FETCH APPROXIMATE support ~~~~~~~~~~~~~~~~~~~~~~~~~ Approximate vector search can only be performed when all syntax and semantic rules are satisfied, the corresponding vector index is available, and the query optimizer determines to perform it. If any of these conditions are unmet, then an approximate search is not performed. In this case the query returns exact results. To enable approximate searching during similarity searches on VECTORS, the ``oracle_fetch_approximate`` parameter may be used with the :meth:`.Select.fetch` clause to add ``FETCH APPROX`` to the SELECT statement:: select(users_table).fetch(5, oracle_fetch_approximate=True) � )� annotations)� defaultdict)�fields)� lru_cache��wrapsN� )� dictionary)�_OracleBoolean)� _OracleDate)�BFILE)� BINARY_DOUBLE)� BINARY_FLOAT)�DATE)�FLOAT)�INTERVAL)�LONG)�NCLOB)�NUMBER)� NVARCHAR2)� OracleRaw)�RAW)�ROWID)� TIMESTAMP)�VARCHAR2)�VECTOR)�VectorIndexConfig)�VectorIndexType� )�Computed)�exc)�schema)�sql)�util)�default)� ObjectKind)� ObjectScope)� reflection)�ReflectionDefaults)�and_�� bindparam)�compiler)� expression)�func)�null)�or_)�select)� selectable)�sqltypes)�visitors)�InternalTraversal)�BLOB)�CHAR)�CLOB)�DOUBLE_PRECISION)�INTEGER)�NCHAR)�NVARCHAR)�REAL)�VARCHARa SHARE RAW DROP BETWEEN FROM DESC OPTION PRIOR LONG THEN DEFAULT ALTER IS INTO MINUS INTEGER NUMBER GRANT IDENTIFIED ALL TO ORDER ON FLOAT DATE HAVING CLUSTER NOWAIT RESOURCE ANY TABLE INDEX FOR UPDATE WHERE CHECK SMALLINT WITH DELETE BY ASC REVOKE LIKE SIZE RENAME NOCOMPRESS NULL GROUP VALUES AS IN VIEW EXCLUSIVE COMPRESS SYNONYM SELECT INSERT EXISTS NOT TRIGGER ELSE CREATE INTERSECT PCTFREE DISTINCT USER CONNECT SET MODE OF UNIQUE VARCHAR2 VARCHAR LOCK OR CHAR DECIMAL UNION PUBLIC AND START UID COMMENT CURRENT LEVELz<UID CURRENT_DATE SYSDATE USER CURRENT_TIME CURRENT_TIMESTAMP)r r r7 r; r r r6 r r8 r r �TIMESTAMP WITH TIME ZONE� TIMESTAMP WITH LOCAL TIME ZONEzINTERVAL DAY TO SECONDr r �DOUBLE PRECISIONr= r r r r r c @ s� e Zd Zdd� Zdd� Zdd� Zdd� Zd d � Zd d � Zd d� Z dd� Z dd� Z dd� Z dd� Z dd� Zd7dd �Zd d � Zd d � Zd!d"� ZeZd#d$� Zd%d&� Zd'd(� Zd)d*� Zd+d,� Zd-d.� Zd/d0� Zd1d2� Zd3d4� Z d5d6� Z dS )8�OracleTypeCompilerc K s | j |fi |��S �N)Z visit_DATE��self�type_�kw� rH �T/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/oracle/base.py�visit_datetime� s z!OracleTypeCompiler.visit_datetimec K s | j |fi |��S rC )� visit_FLOATrD rH rH rI � visit_float� s z OracleTypeCompiler.visit_floatc K s | j |fi |��S rC )�visit_DOUBLE_PRECISIONrD rH rH rI � visit_double� s z OracleTypeCompiler.visit_doublec K s0 | j jr| j|fi |��S | j|fi |��S d S rC )�dialect�_use_nchar_for_unicode�visit_NVARCHAR2�visit_VARCHAR2rD rH rH rI � visit_unicode� s z OracleTypeCompiler.visit_unicodec K s4 d|j d urd|j pd|jd ur,d|j p.df S )NzINTERVAL DAY%s TO SECOND%sz(%d)� )Z day_precisionZsecond_precisionrD rH rH rI �visit_INTERVAL s � ��z!OracleTypeCompiler.visit_INTERVALc K s dS )Nr rH rD rH rH rI � visit_LONG s z OracleTypeCompiler.visit_LONGc K s" t |dd�rdS |jrdS dS d S )N�local_timezoneFr@ r? r )�getattr�timezonerD rH rH rI �visit_TIMESTAMP s z"OracleTypeCompiler.visit_TIMESTAMPc K s | j |dfi |��S )NrA ��_generate_numericrD rH rH rI rM s z)OracleTypeCompiler.visit_DOUBLE_PRECISIONc K s | j |dfi |��S )Nr r[ rD rH rH rI �visit_BINARY_DOUBLE s z&OracleTypeCompiler.visit_BINARY_DOUBLEc K s | j |dfi |��S )Nr r[ rD rH rH rI �visit_BINARY_FLOAT s z%OracleTypeCompiler.visit_BINARY_FLOATc K s d|d< | j |dfi |��S )NT�_requires_binary_precisionr r[ rD rH rH rI rK s z OracleTypeCompiler.visit_FLOATc K s | j |dfi |��S )Nr r[ rD rH rH rI � visit_NUMBER$ s z OracleTypeCompiler.visit_NUMBERNFc K s� |d u rt |dd �}|rdt |dd �}|r`|d u r`t|d �}t�d|jj� d|� d|� d���n|}|d u rxt |dd �}|d u r�|S |d u r�d } | ||d � S d } | |||d � S d S ) N� precision�binary_precisiong2ZGUD�?z�Oracle Database FLOAT types use 'binary precision', which does not convert cleanly from decimal 'precision'. Please specify this type with a separate Oracle Database variant, such as z (precision=z-).with_variant(oracle.FLOAT(binary_precision=zb), 'oracle'), so that the Oracle Database specific 'binary_precision' may be specified accurately.�scalez%(name)s(%(precision)s))�namera z"%(name)s(%(precision)s, %(scale)s))rd ra rc )rX �intr � ArgumentError� __class__�__name__) rE rF rd ra rc r_ rG rb Zestimated_binary_precision�nrH rH rI r\ ' s2 ���� z$OracleTypeCompiler._generate_numericc K s | j |fi |��S rC )rR rD rH rH rI � visit_stringT s z OracleTypeCompiler.visit_stringc K s | � |dd�S )NrT �2��_visit_varcharrD rH rH rI rR W s z!OracleTypeCompiler.visit_VARCHAR2c K s | � |dd�S )N�Nrk rl rD rH rH rI rQ Z s z"OracleTypeCompiler.visit_NVARCHAR2c K s | � |dd�S �NrT rl rD rH rH rI � visit_VARCHAR_ s z OracleTypeCompiler.visit_VARCHARc C sN |j sd||d� S |s4| jjr4d}||j |d� S d}||j ||d� S d S )Nz%(n)sVARCHAR%(two)s)�twori z VARCHAR%(two)s(%(length)s CHAR))�lengthrq z %(n)sVARCHAR%(two)s(%(length)s))rr rq ri )rr rO �_supports_char_length)rE rF ri �numZvarcharrH rH rI rm b s z!OracleTypeCompiler._visit_varcharc K s | j |fi |��S rC )� visit_CLOBrD rH rH rI � visit_textl s z OracleTypeCompiler.visit_textc K s0 | j jr| j|fi |��S | j|fi |��S d S rC )rO rP Z visit_NCLOBru rD rH rH rI �visit_unicode_texto s z%OracleTypeCompiler.visit_unicode_textc K s | j |fi |��S rC )Z visit_BLOBrD rH rH rI �visit_large_binaryu s z%OracleTypeCompiler.visit_large_binaryc K s | j |fddi|��S )Nra � )r` rD rH rH rI �visit_big_integerx s z$OracleTypeCompiler.visit_big_integerc K s | j |fi |��S rC )Zvisit_SMALLINTrD rH rH rI � visit_boolean{ s z OracleTypeCompiler.visit_booleanc K s |j rdd|j i S dS d S )NzRAW(%(length)s)rr r )rr rD rH rH rI � visit_RAW~ s z OracleTypeCompiler.visit_RAWc K s dS )Nr rH rD rH rH rI � visit_ROWID� s z OracleTypeCompiler.visit_ROWIDc K sf |j d u r|jd u rdS |jd u r0d|j � d�S |j d u rJd|jj� d�S d|j � d|jj� d�S d S )Nz VECTOR(*,*)zVECTOR(z,*)z VECTOR(*,�)�,)ZdimZstorage_format�valuerD rH rH rI � visit_VECTOR� s z OracleTypeCompiler.visit_VECTOR)NNF) rh � __module__� __qualname__rJ rL rN rS rU rV rZ rM r] r^ rK r` r\ rj rR rQ Zvisit_NVARCHARrp rm rv rw rx rz r{ r| r} r� rH rH rH rI rB � s< � - rB c s~ e Zd ZdZe�ejje j j di�Z� fdd�Z dd� Z dd� Zd d � Zd d � Zd d� Zdd� Zdd� Zdd� Zdd� Z� fdd�Z� fdd�Zdd � ZdSd d �Zd d!� Zd"d#� Zd$d%� Z d&d'� Z d(d)� Z � fd*d+�Z d,d-� Z dT� fd/d0� Z!d1d2� Z"d3d4� Z#d5d6� Z$d7d8� Z%d9d:� Z&d;d<� Z'd=d>� Z(d?d@� Z)dAdB� Z*dCdD� Z+dUdEdF�Z,dGdH� Z-dIdJ� Z.dKdL� Z/dMdN� Z0dOdP� Z1dQdR� Z2� Z3S )V�OracleCompilerz�Oracle compiler modifies the lexical structure of Select statements to work under non-ANSI configured Oracle databases, if the use_ansi flag is False. �MINUSc s i | _ t� j|i |�� d S rC )Z_OracleCompiler__wheres�super�__init__�rE �args�kwargs�rg rH rI r� � s zOracleCompiler.__init__c K s, d| j |jfi |��| j |jfi |��f S )Nz mod(%s, %s)��process�left�right�rE �binary�operatorrG rH rH rI �visit_mod_binary� s �z OracleCompiler.visit_mod_binaryc K s dS )NZCURRENT_TIMESTAMPrH �rE �fnrG rH rH rI �visit_now_func� s z OracleCompiler.visit_now_funcc K s d| j |fi |�� S )NZLENGTH��function_argspecr� rH rH rI �visit_char_length_func� s z%OracleCompiler.visit_char_length_funcc K s d| � |j�| � |j�f S )NzCONTAINS (%s, %s)r� r� rH rH rI �visit_match_op_binary� s �z$OracleCompiler.visit_match_op_binaryc K s dS )N�1rH �rE �exprrG rH rH rI � visit_true� s zOracleCompiler.visit_truec K s dS )N�0rH r� rH rH rI � visit_false� s zOracleCompiler.visit_falsec C s dS )NZWITHrH )rE � recursiverH rH rI �get_cte_preamble� s z OracleCompiler.get_cte_preamblec C s d� dd� |�� D ��S )N� c s s | ]\}}d | V qdS )z /*+ %s */NrH )�.0�table�textrH rH rI � <genexpr>� � z6OracleCompiler.get_select_hint_text.<locals>.<genexpr>)�join�items)rE ZbyfromsrH rH rI �get_select_hint_text� s z#OracleCompiler.get_select_hint_textc K s: t |j�dks |j�� tvr2tjj| |fi |��S dS d S )Nr rT )�len�clausesrd �upper� NO_ARG_FNSr, � SQLCompilerr� r� rH rH rI r� � s z OracleCompiler.function_argspecc s: t � j|fi |��}|�dd�r6|j�� dkr6d| }|S )N�asfromFr� z TABLE (%s))r� �visit_function�getrd �lower)rE r. rG r� r� rH rI r� � s z OracleCompiler.visit_functionc s t � j|fi |��}|d }|S )Nz .COLUMN_VALUE)r� �visit_table_valued_column)rE �elementrG r� r� rH rI r� � s z(OracleCompiler.visit_table_valued_columnc C s dS )z�Called when a ``SELECT`` statement has no froms, and no ``FROM`` clause is to be appended. The Oracle compiler tacks a "FROM DUAL" to the statement. z FROM DUALrH �rE rH rH rI � default_from� s zOracleCompiler.default_fromNc K s� | j jr"tjj| |fd|i|��S |r:|j�|j|jf� d|d< t |jt j �rZ|jj }n|j}| j |jfd|i|��d | j |fd|i|�� S d S )N� from_linterTr� �, )rO �use_ansir, r� � visit_join�edges�addr� r� � isinstancer- � FromGroupingr� r� )rE r� r� r� r� rH rH rI r� � s( ��� ���zOracleCompiler.visit_joinc sF g � � �fdd��|D ]}t |tj�r�|� q� s8d S tj� � S d S )Nc s| � j r.� fdd�}��t�� ji d|i�� n ��� j� � j� jfD ]0}t|tj �r`�|� qFt|tj �rF�|j � qFd S )Nc sZ t | jtj�r,� j�| jj�r,t| j�| _n*t | jtj�rV� j�| jj�rVt| j�| _d S rC )r� r� r- Z ColumnClauser� Zis_derived_fromr� �_OuterJoinColumn)r� �r� rH rI � visit_binary� s ����zVOracleCompiler._get_nonansi_join_whereclause.<locals>.visit_join.<locals>.visit_binaryr� ) Zisouter�appendr4 �cloned_traverseZonclauser� r� r� r- �Joinr� r� )r� r� �j�r� r� r� rI r� � s �� z@OracleCompiler._get_nonansi_join_whereclause.<locals>.visit_join)r� r- r� r" r) )rE �froms�frH r� rI � _get_nonansi_join_whereclause� s z,OracleCompiler._get_nonansi_join_whereclausec K s | j |jfi |��d S )Nz(+))r� �column)rE ZvcrG rH rH rI �visit_outer_join_column s z&OracleCompiler.visit_outer_join_columnc K s | j �|�d S )Nz.nextval)�preparer�format_sequence)rE �seqrG rH rH rI �visit_sequence s z OracleCompiler.visit_sequencec C s d| S )z+Oracle doesn't like ``FROM table AS alias``r� rH )rE Zalias_name_textrH rH rI �get_render_as_alias_suffix s z)OracleCompiler.get_render_as_alias_suffixc K s& g }g }t t�|��D ]�\}}| jrNt|tj�rNt|jt�rN| j j sNt � d� |j jrd|j �|�} n|} tjd| |j d�} | | j| j< |�| �| �| ��� | jr�t�d��d| _|�| j| dd�� |r| � t | d| j �t | d| j �|t |dd �t |d d �f|j � qd d � |� d d � |� S ) Na} Computed columns don't work with Oracle Database UPDATE statements that use RETURNING; the value of the column *before* the UPDATE takes place is returned. It is advised to not use RETURNING with an Oracle Database computed column. Consider setting implicit_returning to False on the Table object in order to avoid implicit RETURNING clauses from being generated for this Table.zret_%d)rF z�Using explicit outparam() objects with UpdateBase.returning() in the same Core DML statement is not supported in the Oracle Database dialects.TF)Zwithin_columns_clauserd �keyz RETURNING r� z INTO ) � enumerater- Z_select_iterablesZisupdater� � sa_schemaZColumnZserver_defaultr rO �(_supports_update_returning_computed_colsr# �warn�typeZ_has_column_expression�column_expressionr" �outparam�bindsr� r� Zbindparam_stringZ_truncate_bindparamZhas_out_parametersr ZInvalidRequestErrorZ_oracle_returningr� Z_add_to_result_maprX Z_anon_name_labelr� ) rE �stmtZreturning_colsZpopulate_result_maprG �columnsr� �ir� Zcol_exprr� rH rH rI �returning_clause" sR � � � ��� � � �� z OracleCompiler.returning_clausec sL |j dus| jjs*t� j|fddi|��S | j|f| �|�dd�|��S dS )zmOracle Database 12c supports OFFSET/FETCH operators Use it instead subquery with row_number N�"use_literal_execute_for_simple_intT)� fetch_clauser� )� _fetch_clauserO �_supports_offset_fetchr� �_row_limit_clauser� �_get_limit_or_fetch�rE r1 rG r� rH rI r� d s& ��������z OracleCompiler._row_limit_clausec C s |j d u r|jS |j S d S rC )r� � _limit_clause)rE r1 rH rH rI r� y s z"OracleCompiler._get_limit_or_fetchFc s< t � j|f|||d�|��}|jd d r8t�dd|�}|S )N)r� �require_offsetr� �oracle�fetch_approximatez FETCH FIRSTzFETCH APPROX FIRST)r� r� �dialect_options�re�sub)rE r1 r� r� r� rG r� r� rH rI r� s ��� zOracleCompiler.fetch_clausec s |}t |dd ��s| jjsP| �||�dd��}| �|�}|d urP|�|�}d|_|j�r| jj �s|j d u �r|j }|j }|� |�r�|�� }|� |�r�|�� }|�|�� }d|_|j}|d ur�|jr�|�� }|�� |jD ]} |j�| �s�|�| �}q�|�� } tj�fdd�| jD �� } |d u�rZ| jj�rZ|� |��rZ| � t � d| j |fi |�� ��} d| _d| _ |d u�r�|j�r�t!�"| �� � fdd�|jD �|_|d u�r|� |��r�|d u �s�|� |��r�|} |d u�r�| | } n|} |d u�r�| | } | �t�#d �| k�} |d u �r || _| }n�| �t�#d ��$d ��} d| _d| _ |d u�r~|j�r~| j} |jD ] } | �%| �d u �r\| �| �} �q\| �� }�j�tj�fd d�|jD �� }d|_d|_ |d u�r�|j�r�t!�"|�� � fd d�|jD �|_|�t�#d �|k�}||_|}|S ) N� _oracle_visitr� FTc s g | ]}� j �|�d ur|�qS rC )�selected_columns�corresponding_column�r� �c)� orig_selectrH rI � <listcomp>� s ��z=OracleCompiler.translate_select_structure.<locals>.<listcomp>z/*+ FIRST_ROWS(%s) */c s g | ]}� � |��qS rH ��traverse�r� �elem��adapterrH rI r� � s ZROWNUMZora_rnc s g | ]}� � |�d ur|�qS rC )r� r� )�origselect_colsrH rI r� s ��c s g | ]}� � |��qS rH r� r� r� rH rI r� s )&rX rO r� Z_display_froms_for_selectr� r� �wherer� Z_has_row_limiting_clauser� r� r� Z_offset_clauseZ_simple_int_clauseZrender_literal_executeZ _generate�_for_update_arg�ofZ_cloneZ_copy_internalsr� Zcontains_columnZ add_columns�aliasr" r1 r� �optimize_limitsZ prefix_withr- r� r� � _is_wrapper�sql_utilZ ClauseAdapterZliteral_column�labelr� )rE Z select_stmtr� r1 r� Z whereclause� limit_clauseZ offset_clauseZ for_updater� Zinner_subqueryZ limitselectZmax_rowZlimitselect_colsZlimit_subqueryZ offsetselectrH )r� r� r� rI �translate_select_structure� s� � ��� �� ������ � �� � � �� �� � �z)OracleCompiler.translate_select_structurec K s dS ro rH r� rH rH rI r * s zOracleCompiler.limit_clausec K s dS )Nz SELECT 1 FROM DUAL WHERE 1!=1rH rD rH rH rI �visit_empty_set_expr- s z#OracleCompiler.visit_empty_set_exprc sb �� � r dS d}|jjr>|dd�� �fdd�|jjD �� 7 }|jjrN|d7 }|jjr^|d7 }|S ) NrT z FOR UPDATEz OF r� c 3 s | ]}�j |fi � ��V qd S rC )r� r� �rG rE rH rI r� 7 s z3OracleCompiler.for_update_clause.<locals>.<genexpr>z NOWAITz SKIP LOCKED)Z is_subqueryr� r� r� ZnowaitZ skip_locked)rE r1 rG �tmprH r rI �for_update_clause0 s � z OracleCompiler.for_update_clausec K s d| � |j�| � |j�f S )NzDECODE(%s, %s, 0, 1) = 1r� r� rH rH rI � visit_is_distinct_from_binaryB s �z,OracleCompiler.visit_is_distinct_from_binaryc K s d| � |j�| � |j�f S )NzDECODE(%s, %s, 0, 1) = 0r� r� rH rH rI �!visit_is_not_distinct_from_binaryH s �z0OracleCompiler.visit_is_not_distinct_from_binaryc K sb | j |jfi |��}| j |jfi |��}|jd }|d u rFd||f S d||| �|tj�f S d S )N�flagszREGEXP_LIKE(%s, %s)zREGEXP_LIKE(%s, %s, %s)�r� r� r� � modifiersZrender_literal_valuer3 Z STRINGTYPE)rE r� r� rG �string�patternr rH rH rI � visit_regexp_match_op_binaryN s �z+OracleCompiler.visit_regexp_match_op_binaryc K s d| j ||fi |�� S )NzNOT %s)r r� rH rH rI � visit_not_regexp_match_op_binary[ s ��z/OracleCompiler.visit_not_regexp_match_op_binaryc K sb | j |jfi |��}| j |jfi |��}|jd }|d u rFd||f S d||| �|tj�f S d S )Nr zREGEXP_REPLACE(%s, %s)zREGEXP_REPLACE(%s, %s, %s)r )rE r� r� rG r Zpattern_replacer rH rH rI � visit_regexp_replace_op_binary` s � �z-OracleCompiler.visit_regexp_replace_op_binaryc K s d| j |fi |�� S )Nz LISTAGG%sr� r� rH rH rI � visit_aggregate_strings_funcp s z+OracleCompiler.visit_aggregate_strings_funcc K sJ | j |jfi |��}| j |d ur$|n|jfi |��}|� d|� d|� d�S )N�(r� r~ r� )rE r� �fn_nameZ custom_rightrG r� r� rH rH rI �_visit_bitwises s ��z OracleCompiler._visit_bitwisec K s | j |dfi |��S )NZBITXOR�r r� rH rH rI �visit_bitwise_xor_op_binaryz s z*OracleCompiler.visit_bitwise_xor_op_binaryc K s | j |dfi |��S )NZBITORr r� rH rH rI �visit_bitwise_or_op_binary} s z)OracleCompiler.visit_bitwise_or_op_binaryc K s | j |dfi |��S )NZBITANDr r� rH rH rI �visit_bitwise_and_op_binary� s z*OracleCompiler.visit_bitwise_and_op_binaryc K s t �d��d S )Nz'Cannot compile bitwise_rshift in oracle�r � CompileErrorr� rH rH rI � visit_bitwise_rshift_op_binary� s z-OracleCompiler.visit_bitwise_rshift_op_binaryc K s t �d��d S )Nz'Cannot compile bitwise_lshift in oracler r� rH rH rI � visit_bitwise_lshift_op_binary� s z-OracleCompiler.visit_bitwise_lshift_op_binaryc K s t �d��d S )Nz$Cannot compile bitwise_not in oracler )rE r� r� rG rH rH rI �#visit_bitwise_not_op_unary_operator� s z2OracleCompiler.visit_bitwise_not_op_unary_operator)N)NFF)N)4rh r� r� �__doc__r# Z update_copyr, r� Zcompound_keywordsr- �CompoundSelectZEXCEPTr� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r r r r r r r r r r r r r r r r r � __classcell__rH rH r� rI r� � s` � *B � r� c s\ e Zd Zddd�dd�Zdd� Zdd � Zd d � Zd d � Z� fdd�Zdd� Z dd� Z � Z S )�OracleDDLCompilerr �str)�vector_index_config�returnc C s. g }dddddd�}|j tjkr,|�d� n|j tjkrB|�d� |jd ur`|�d |jj� �� |jd ur||�d |j� �� d |j j� �g}|j j� � d }t |�D ]D}|j� |�r�|� |j�}t ||j�}|d ur�|�|� d |� �� q�d�|�}|�d|� d�� |jd u�r$|�d|j� �� d �|�S )NZ neighborsZefconstructionzneighbor partitionsZsample_per_partitionZmin_vectors_per_partition)Zhnsw_neighborsZhnsw_efconstructionZivf_neighbor_partitionsZivf_sample_per_partitionZ ivf_min_vectors_per_partitionz$ORGANIZATION INMEMORY NEIGHBOR GRAPHz ORGANIZATION NEIGHBOR PARTITIONSz DISTANCE zWITH TARGET ACCURACY ztype �_r� r� z PARAMETERS (r~ z PARALLEL )� index_typer ZHNSWr� ZIVFZdistancer� Zaccuracyrd r� r � startswithr� rX r� �parallel) rE r& �partsZsql_param_nameZparameters_str�prefix�fieldr� r� rH rH rI �_build_vector_index_config� s< � � z,OracleDDLCompiler._build_vector_index_configc C s4 d}|j d ur |d|j 7 }|jd ur0t�d� |S )NrT z ON DELETE %sz�Oracle Database does not contain native UPDATE CASCADE functionality - onupdates will not be rendered for foreign keys. Consider using deferrable=True, initially='deferred' or triggers.)�ondeleteZonupdater# r� )rE � constraintr� rH rH rI �define_constraint_cascades� s �z,OracleDDLCompiler.define_constraint_cascadesc K s d| j �|j� S )NzCOMMENT ON TABLE %s IS '')r� � format_tabler� )rE ZdroprG rH rH rI �visit_drop_table_comment� s �z*OracleDDLCompiler.visit_drop_table_commentc s |j }� �|� � j}d}|jr(|d7 }|jd d r>|d7 }|jd d }|rX|d7 }|d� j|d d �|j|jd d �d �� fd d�|j D ��f 7 }|jd d dur�|jd d d u r�|d7 }n|d|jd d 7 }|r�|d u r�t � }|d� � |� 7 }|S )NzCREATE zUNIQUE r� �bitmapzBITMAP �vectorzVECTOR zINDEX %s ON %s (%s)T)Zinclude_schema)Z use_schemar� c 3 s | ]}� j j|d dd�V qdS )FT�Z include_tableZ literal_bindsN)� sql_compilerr� )r� r� r� rH rI r� � s ��z7OracleDDLCompiler.visit_create_index.<locals>.<genexpr>�compressFz COMPRESSz COMPRESS %dr� ) r� Z_verify_index_tabler� �uniquer� Z_prepared_index_namer3 r� r� � expressionsr r/ )rE �createrG �indexr� r� Zvector_optionsrH r� rI �visit_create_index� s: �� �z$OracleDDLCompiler.visit_create_indexc C s� g }|j d }|d r8|d �dd��� }|�d| � |d rj|d du rX|�d� n|�d |d � |d r�|�d | j�|d � � d �|�S ) Nr� � on_commitr( r� z ON COMMIT %sr9 Tz COMPRESSz COMPRESS FOR %s� tablespacez TABLESPACE %srT )r� �replacer� r� r� �quoter� )rE r� Z table_opts�optsZon_commit_optionsrH rH rI �post_create_table� s �z#OracleDDLCompiler.post_create_tablec sT t � �|�}|�dd�}|�dd�}|�dd�}|jd urL||jrFdnd7 }|�� S ) Nz NO MINVALUEZ NOMINVALUEz NO MAXVALUEZ NOMAXVALUEzNO CYCLEZNOCYCLEz ORDERz NOORDER)r� �get_identity_optionsrA �order�strip)rE �identity_optionsr� r� rH rI rE s z&OracleDDLCompiler.get_identity_optionsc K sD d| j j|jddd� }|jdu r.t�d��n|jdu r@|d7 }|S )NzGENERATED ALWAYS AS (%s)FTr7 z�Oracle Database computed columns do not support 'stored' persistence; set the 'persisted' flag to None or False for Oracle Database support.z VIRTUAL)r8 r� �sqltextZ persistedr r )rE � generatedrG r� rH rH rI �visit_computed_column s � � z'OracleDDLCompiler.visit_computed_columnc K sZ |j d u rd}n|j rdnd}d| }|jr4|d7 }|d7 }| �|�}|rV|d| 7 }|S )NrT �ALWAYSz BY DEFAULTz GENERATED %sz ON NULLz AS IDENTITYz (%s))�always�on_nullrE )rE �identityrG �kindr� �optionsrH rH rI �visit_identity_column s z'OracleDDLCompiler.visit_identity_column) rh r� r� r/ r2 r4 r> rD rE rK rR r# rH rH r� rI r$ � s )$ r$ c sP e Zd Zdd� eD �Zdd� edd�D ��ddg�Zdd � Z� fd d �Z � Z S ) �OracleIdentifierPreparerc C s h | ] }|� � �qS rH )r� �r� �xrH rH rI � <setcomp>- r� z"OracleIdentifierPreparer.<setcomp>c C s h | ] }t |��qS rH )r% )r� �digrH rH rI rV . r� r � r( �$c C s2 |� � }|| jv p0|d | jv p0| j�t|�� S )z5Return True if the given identifier requires quoting.r )r� �reserved_words�illegal_initial_charactersZlegal_characters�matchr% )rE r� Zlc_valuerH rH rI �_bindparam_requires_quotes2 s ��z3OracleIdentifierPreparer._bindparam_requires_quotesc s |j �d�}t� �||�S )Nr( )�ident�lstripr� �format_savepoint)rE Z savepointrd r� rH rI r` ; s z)OracleIdentifierPreparer.format_savepoint) rh r� r� �RESERVED_WORDSrZ �range�unionr[ r] r` r# rH rH r� rI rS , s � rS c @ s e Zd Zdd� Zdd� ZdS )�OracleExecutionContextc C s | � d| j�|� d |�S )NzSELECT z.nextval FROM DUAL)Z_execute_scalarZidentifier_preparerr� )rE r� rF rH rH rI � fire_sequenceA s ���z$OracleExecutionContext.fire_sequencec C s, | j r(d| jv r(| j �tj| jd �| _ d S )N�_oracle_dblink)Z statement�execution_optionsrA r ZDB_LINK_PLACEHOLDERr� rH rH rI �pre_execI s �z OracleExecutionContext.pre_execN)rh r� r� re rh rH rH rH rI rd @ s rd c sh e Zd ZdZdZdZdZdZdZdZ dZ dZ dZ dZ dZdZdZdZdZeZeZdZdZdZdZdZdZeZ e Z e Z e!Z"e#Z$dZ%dZ&e'j(ddddd�fe'j)dddd �fe*j+d dife*j,d difgZ-e.j/d d �d�dd��Z0� fdd�Z1dd� Z2e3dd� �Z4e3dd� �Z5e3dd� �Z6e3dd� �Z7e3d d � �Z8e3d d � �Z9d d!� Z:d"d#� Z;d$d%� Z<d&d'� Z=d�d(d)�Z>e.j?d*d+� �Z@eAjBd�d,d-��ZCeAjBd�d.d/��ZDd0d1� ZE� fd2d3�ZFeA�Gd4eHjIfd5eHjJfd6eHjIf�d7d8� �ZKeL� d9d:� �ZMeA�Gd4eHjIfd;eHjNfd<eHjNfd5eHjJfd6eHjIf�d=d>� �ZOd?d@� ZPdAdB� ZQeAjBd�dCdD��ZReAjBd�dEdF��ZSeAjBd�dGdH��ZTeAjBd�dIdJ��ZUeAjBd�dKdL��ZVeAjBd�dMdN��ZWdOdP� ZXdQdR� ZYeAjBd�dSdT��ZZeL� dUdV� �Z[ePddW�dXdY��Z\eAjBd�dZd[��Z]d\d]� Z^eL� d^d_� �Z_ePddW�d`da��Z`dbdc� ZaeAjBd�ddde��ZbeL� dfdg� �ZcePddW�dhdi��ZdeAjBd�djdk��ZeeL� dldm� �ZfeA�Gd4eHjIfd6eHjIfdneHjJf�dodp� �ZgePddW�dqdr��ZheAjBd�dsdt��ZieL� dudv� �ZjeA�Gd4eHjIfd6eHjIfdneHjJf�dwdx� �ZkePddW�dydz��ZleAjBd�d{d|��ZmePddW�d}d~��ZneAjBd�dd���ZoePddW�d�d���ZpeAjBd�d�d���ZqeAjBd�d�d���ZrePddd��d�d���Zsd�d�d��Zt� ZuS )�� OracleDialectr� T� F�named)�oracle_resolve_synonymsN)�resolve_synonymsr? r9 r@ )r5 r9 r6 r� )z1.4a The ``use_binds_for_limits`` Oracle Database dialect parameter is deprecated. The dialect now renders LIMIT / OFFSET integers inline in all cases using a post-compilation hook, so that the value is still represented by a 'bound parameter' on the Core Expression side.)�use_binds_for_limits�ZSYSTEMZSYSAUXc K s< t jj| fi |�� || _|| _|| _|| _| | _| _d S rC ) r$ �DefaultDialectr� rP r� r �exclude_tablespaces�enable_offset_fetchr� )rE r� r rn Zuse_nchar_for_unicoderq rr r� rH rH rI r� � s �zOracleDialect.__init__c sT t � �|� | jr2| j�� | _| j�tj� d| _| j dk| _ | j oL| j dk| _ d S )NF�� ) r� � initialize� _is_oracle_8�colspecs�copy�popr3 �Intervalr� �server_version_info�supports_identity_columnsrr r� �rE � connectionr� rH rI ru � s �zOracleDialect.initializec C sz | j dk r| j S z|�d��� }W n tjy: d }Y n0 |rpztdd� |�d�D ��W S | j Y S 0 n| j S d S )N�rt � z7SELECT value FROM v$parameter WHERE name = 'compatible'c s s | ]}t |�V qd S rC )re rT rH rH rI r� � r� zJOracleDialect._get_effective_compat_server_version_info.<locals>.<genexpr>�.)r{ �exec_driver_sql�scalarr Z DBAPIError�tuple�split)rE r~ �compatrH rH rI �)_get_effective_compat_server_version_info� s � z7OracleDialect._get_effective_compat_server_version_infoc C s | j o| j dk S )N)� �r{ r� rH rH rI rv � s zOracleDialect._is_oracle_8c C s | j o| j dkS )N)rX r r� r� rH rH rI �_supports_table_compression� s z)OracleDialect._supports_table_compressionc C s | j o| j dkS )N)� r� r� rH rH rI � _supports_table_compress_for� s z*OracleDialect._supports_table_compress_forc C s | j S rC )rv r� rH rH rI rs � s z#OracleDialect._supports_char_lengthc C s | j o| j dkS )N)� r� r� rH rH rI r� � s z6OracleDialect._supports_update_returning_computed_colsc C s | j o| j dkS )N)� r� r� rH rH rI �_supports_except_all� s z"OracleDialect._supports_except_allc C s d S rC rH )rE r~ rd rH rH rI �do_release_savepoint� s z"OracleDialect.do_release_savepointc C s | � |�dk rdS d S d S )Nr � )r� r} rH rH rI � _check_max_identifier_length� s z*OracleDialect._check_max_identifier_lengthc C s ddgS )N�READ COMMITTEDZ SERIALIZABLErH )rE Zdbapi_connectionrH rH rI �get_isolation_level_values s z(OracleDialect.get_isolation_level_valuesc C s2 z | � |�W S ty � Y n Y dS 0 d S )Nr� )Zget_isolation_level�NotImplementedError)rE Z dbapi_connrH rH rI �get_default_isolation_level s z)OracleDialect.get_default_isolation_levelc C sX |r|� d�sd|� �}|p dd d�}|rH|rHdd� }t�|i d|i�}|j|||d�S )N�@rT )rf Zschema_translate_mapc S s d| _ d S )NT)Zliteral_executer* rH rH rI �visit_bindparam s z:OracleDialect._execute_reflection.<locals>.visit_bindparamr+ )rg )r* r4 r� �execute)rE r~ �query�dblink� returns_long�paramsrg r� rH rH rI �_execute_reflection s � ��z!OracleDialect._execute_reflectionc C sj t tjjjtjjj��t tjjj� d�tjjj��� d�}t |jj�� |jjt d�k|jjt d�k�}|S )N� table_name�tables_and_views�owner) r1 r � all_tablesr� r� r� � union_all� all_views� view_namer �subqueryr� r+ )rE �tablesr� rH rH rI �_has_table_query' s" ��� �� �z OracleDialect._has_table_queryc K sL | � |� |s| j}| �|�| �|�d�}| j|| j|d|d�}t|�� �S )�@Supported kw arguments are: ``dblink`` to reflect via a db link.)r� r� F�r� r� )Z _ensure_has_table_connection�default_schema_name�denormalize_name�denormalize_schema_namer� r� �boolr� )rE r~ r� r! r� rG r� �cursorrH rH rI � has_table> s ��zOracleDialect.has_tablec K s^ |s | j }ttjjj��tjjj| �|�ktjjj| �|�k�}| j |||dd�}t |� � �S )r� F�r� ) r� r1 r � all_sequencesr� � sequence_namer� r� �sequence_ownerr� r� r� )rE r~ r� r! r� rG r� r� rH rH rI � has_sequenceU s ����zOracleDialect.has_sequencec C s | � |�d��� �S )Nz;select sys_context( 'userenv', 'current_schema' ) from dual)�normalize_namer� r� r} rH rH rI �_get_default_schema_namei s ��z&OracleDialect._get_default_schema_namec s, t |dd �}|d u r |dkr dS t� �|�S )NrB �publicZPUBLIC)rX r� r� )rE rd �forcer� rH rI r� p s z%OracleDialect.denormalize_schema_namer! � filter_namesr� c K s� | � |p | j�}| �|�\}}ttjjjtjjjtjjj tjjj �� tjjj |k�} |rr| � tjjj� |d ��} | j|| |dd��� } | �� S )Nr� Fr� )r� r� �_prepare_filter_namesr1 r � all_synonymsr� � synonym_namer� � table_owner�db_linkr� r� �in_r� �mappings�all) rE r~ r! r� r� rG r� �has_filter_namesr� r� �resultrH rH rI � _get_synonymsx s, �� � ��� zOracleDialect._get_synonymsc C s4 t tjjj��tj��tjjj|k�}|tj u rH|�tjjj � d��}n�g }tj |v r`|� d� tj|v r~tj|vr~|� d� tj|v r�|� d� |r�tj|vr�|�tjjj�td���}|�tjjj � |��}|tju r�|�tjjjdk�}n |tju �r|�tjjjdk�}|�r0|�tjjj� td���}|S ) N)�TABLE�VIEWr� zMATERIALIZED VIEWr� � mat_viewsrn �Yr� )r1 r � all_objectsr� � object_name� select_fromr� r� r% �ANY� object_typer� r� r� �MATERIALIZED_VIEWr� �not_inr+ r& �DEFAULT� temporary� TEMPORARY)rE r� �scoperP r� � has_mat_viewsr� r� rH rH rI �_all_objects_query� sP � �� � �� ��� ��z OracleDialect._all_objects_queryr� rP c K s� | � |p | j�}| �|�\} } d} tj|v r`tj|vr`| j|||fddi|��} | r`| | d< d} | �|||| | �} | j|| |d| d�� � }|� � S )NF� _normalizer� Tr� ) r� r� r� r% r� r� �get_materialized_view_namesr� r� �scalarsr� )rE r~ r! r� rP r� r� rG r� r� r� r� r� r� r� rH rH rI �_get_all_objects� s4 ������ � � z OracleDialect._get_all_objectsc s t � �� fdd��}|S )Nc s | j � g|�R i |��S rC )�_handle_synonymsr� �r� rH rI �wrapper� s z9OracleDialect._handle_synonyms_decorator.<locals>.wrapperr )r� r� rH r� rI �_handle_synonyms_decorator� s z(OracleDialect._handle_synonyms_decoratorc O sF |� dd�s$|| |g|�R i |��S |�� }|�dd �}| j|||�dd �|�dd �|� dd �d�}tt�}|D ]2} | d | d f} | �| d �} | d || | < qp|s�|| |g|�R i |��S i } |�� D ]p\\} }}i |�|| �| �|�� d ��}|| |g|�R i |��}|D ](\\}} }| �|| �}|| ||f< �qq�| �� S ) Nrl Fr! r� r� � info_cache)r! r� r� r� r� r� r� r� )r! r� r� ) r� rx ry r� r �dictr� r� �keys)rE r� r~ r� r� Z original_kwr! r� Zdblinks_owners�rowr� �tn�datar� r� �mappingZcall_kwZ call_resultr( r� r� rH rH rI r� � s@ ���z OracleDialect._handle_synonymsc sB t tjjj��tjjj�}� j|||dd��� }� fdd�|D �S )r� Fr� c s g | ]}� � |��qS rH �r� �r� r� r� rH rI r� - r� z2OracleDialect.get_schema_names.<locals>.<listcomp>)r1 r Z all_usersr� �username�order_byr� r� )rE r~ r� rG r� r� rH r� rI �get_schema_names$ s �� z OracleDialect.get_schema_namesc s� |du r� j }� �|�}|�dd�r�ttjjjtjjjtjjj tjjj tjjj �� ttj jj�d�tj jjtjjj tjjj tjjj ��tj��tj ttjjjtj jjktjjjt�tj jjtj jj�k����d�}ntj}t|jj�}� j�r|�t�|jj d��� j��}|�|jj|k|jj �t� �|jj �t� ��}ttj jj �d���tj jj|k�}� j �rr|� |�n|� |�}� j!|||dd��"� } � fdd �| D �S ) r� Nrl Fr� Zavailable_tables� no tablespacer� c s g | ]}� � |��qS rH r� r� r� rH rI r� x r� z1OracleDialect.get_table_names.<locals>.<listcomp>)#r� r� r� r1 r r� r� r� r� �iot_name�duration�tablespace_namer� r� r� r r� r� r) r. �coalescer� r� rq r� r� �is_r/ � all_mviews� mview_namer� Z except_allZexcept_r� r� ) rE r~ r! r� rG Z den_schemar� r� Z mat_queryr� rH r� rI �get_table_names/ s� � �� � ������ ��# ��� �� ���� z OracleDialect.get_table_namesc s� � � � j�}ttjjj�}� jr@|�t � tjjj d�� � j��}|�tjjj |ktjjj�t� �tjjj�t� ��}� j|||dd��� }� fdd�|D �S )r� r� Fr� c s g | ]}� � |��qS rH r� r� r� rH rI r� � r� z6OracleDialect.get_temp_table_names.<locals>.<listcomp>)r� r� r1 r r� r� r� rq r� r. r� r� r� r� r� r� r/ r� �is_notr� r� )rE r~ r� rG r! r� r� rH r� rI �get_temp_table_namesz s& ��� �� z"OracleDialect.get_temp_table_namesc sf |s � j }ttjjj��tjjj� �|�k�}� j |||dd�� � }|rZ� fdd�|D �S |� � S dS )r� Fr� c s g | ]}� � |��qS rH r� r� r� rH rI r� � r� z=OracleDialect.get_materialized_view_names.<locals>.<listcomp>N) r� r1 r r� r� r� r� r� r� r� r� r� )rE r~ r! r� r� rG r� r� rH r� rI r� � s ��� z)OracleDialect.get_materialized_view_namesc sV |s � j }ttjjj��tjjj� �|�k�}� j |||dd�� � }� fdd�|D �S )r� Fr� c s g | ]}� � |��qS rH r� r� r� rH rI r� � r� z0OracleDialect.get_view_names.<locals>.<listcomp>) r� r1 r r� r� r� r� r� r� r� r� �rE r~ r! r� rG r� r� rH r� rI �get_view_names� s ��� z OracleDialect.get_view_namesc sV |s � j }ttjjj��tjjj� �|�k�}� j |||dd�� � }� fdd�|D �S )r� Fr� c s g | ]}� � |��qS rH r� r� r� rH rI r� � r� z4OracleDialect.get_sequence_names.<locals>.<listcomp>) r� r1 r r� r� r� r� r� r� r� r� r� rH r� rI �get_sequence_names� s ��� z OracleDialect.get_sequence_namesc C sV | � t|��}zt|�||f W S tyP t�|rD|� d|� �n|�d �Y n0 d S )Nr� )r� r% r� �KeyErrorr �NoSuchTableError)rE r� r� r! rH rH rI �_value_or_raise� s ��z OracleDialect._value_or_raisec s. |r"� fdd�|D �}dd|ifS di fS d S )Nc s g | ]}� � |��qS rH �r� )r� rd r� rH rI r� � r� z7OracleDialect._prepare_filter_names.<locals>.<listcomp>Tr� FrH )rE r� r� rH r� rI r� � s z#OracleDialect._prepare_filter_namesc K s0 | j |f||gtjtjd�|��}| �|||�S ���Supported kw arguments are: ``dblink`` to reflect via a db link; ``oracle_resolve_synonyms`` to resolve names to synonyms )r! r� r� rP )�get_multi_table_optionsr& r� r% r� �rE r~ r� r! rG r� rH rH rI �get_table_options� s ���z OracleDialect.get_table_optionsc C s, t tjjj| jrtjjjn t�� � d�| j r6tjjj n t�� � d�tjjj �� tjjj|k�}|r||� tjjj�td���}|tju r�|� tjjj�t� ��}n"|tju r�|� tjjj�t� ��}|r�tj|v r�tj|vr�|� tjjj�td���}n2tj|v�r(tj|v �r(|� tjjj�td���}|S )N� compression� compress_forr� r� )r1 r r� r� r� r� r r" r/ r r� r r� r� r� r� r+ r& r� r� r� r� r� r% r� r� r� )rE r� r� rP r� r� r� rH rH rI �_table_options_query� sV � � � � �� ���� �����z"OracleDialect._table_options_query)r� c K s� | � |p | j�}| �|�\} } d} tj|v rbtj|vrb| j|||fddi|��} | r�| | d< d} n6tj|vr�tj|v r�| j|||fddi|��} | | d< i } tj}tj|v s�tj|v �r(| � |||| | �}| j |||d| d�}|D ]D\}}}}|� }|dk�r||d< |�r||d< || || � |�f< q�tj |v �r|t j|v �r|| j|||fi |��D ]$}|�rj||v �rV|� | ||f< �qV| �� S ) r� Fr� r� Tr� �ENABLED�oracle_compressZoracle_tablespace)r� r� r� r% r� r� r� r( Z table_optionsr r� r� r� r& r� r� r� )rE r~ r! r� r� rP r� rG r� r� r� r� r� rQ r$ r� r� r� r r r@ r� �viewrH rH rI r� sh ����������� � � z%OracleDialect.get_multi_table_optionsc K s0 | j |f||gtjtjd�|��}| �|||�S r� )�get_multi_columnsr& r� r% r� r rH rH rI � get_columns] s ���zOracleDialect.get_columnsc c sd d}t |�}|r`|d|� } g |d|�< | j||||d| id�} |rT| �� E d H q | E d H q d S )Ni� r r� r� )�listr� r� ) rE r~ r� r� r� r� r� Z each_batchZbatches�batchr� rH rH rI � _run_batchesm s �zOracleDialect._run_batchesc C s� t j}t j}t j}| jdkr`|jjtj|jj � d �t� � f|jj d |jj d��d�f}d}n t� � �d�t� � �d�f}d}t|jj |jj|jj|jj|jj|jj|jj|jj|jj|jjg |�R � �|��|t|jj |jj k|jj|jjk|jj |jj k��}|�rB|�|t|jj |jj k|jj|jjk|jj |jj k��}|� |jj � t d��|jj d k|jj |k��!|jj |jj"�}|S ) Nrs r )Zelse_rH T�default_on_nullFr� �NO)#r Z all_tab_colsZall_col_commentsZall_tab_identity_colsr{ r� r r" Zcaser� r� r/ Zgeneration_typerH r r1 � column_name� data_type� char_length�data_precision� data_scale�nullable� data_default�comments�virtual_columnr� � outerjoinr) r� r� r� r+ Z hidden_columnr� Z column_id)rE r� Zall_colsZ all_commentsZall_idsZadd_colsZjoin_identity_colsr� rH rH rI � _column_query� s| ����� � � � ������ � �zOracleDialect._column_queryc s� � � |p � j�}� �|�} |rF|tju rF|tju rF� fdd�|D �} n � j||||||fi |��} tt�} � j || |dd| d�} dd� } t � d�}| D �]}� � |d �}|d }� � |�}|d }| |d �}|d k�r | |d �}|du r�|dkr�t � }n t||�}n�|dk�rD|dk�r&t� }n |dk�r8t� }n t|d�}n�|dv �rl| |d �}� j�|�|�}nvd|v �r�tdd�}n`d|v �r�tdd�}nJt �|d|�}z� j| }W n, t�y� t�d||f � tj}Y n0 |d }|d d k�rt|d �}d}nd}|d }|du�r4� � ||d! �}d}nd}|||d" d#k||d$ d%�}|� � |k�rjd|d&< |du�r|||d'< |du�r�||d(< | ||f � |� q�| � � S ))r� c s g | ]}� � |��qS rH r� )r� ri r� rH rI r� � r� z3OracleDialect.get_multi_columns.<locals>.<listcomp>T�r� r� r� c S s" t | t�r| �� rt| �S | S d S rC )r� �float� is_integerre )r� rH rH rI � maybe_int� s z2OracleDialect.get_multi_columns.<locals>.maybe_intz\(\d+\)r� r r r r r Nr r �~ �? )rb )r r r7 r; r zWITH TIME ZONE)rY zWITH LOCAL TIME ZONE)rW rT z*Did not recognize type '%s' of column '%s'r r �YES)rI rH r r r� r )rd r� r r$ �commentrB �computedrO ) r� r� r r% r� r& r� r r r r� �compiler� r: r r9 r= r � ischema_namesr� r r� r� r# r� r3 ZNULLTYPEr� �_parse_identity_optionsr� r� r� ) rE r~ r! r� r� rP r� rG r� r� r� r� r� r Z remove_size�row_dictr� Z orig_colnameZcolnameZcoltypera rc r r$ r" rH rO ZcdictrH r� rI r � s� � ��� ��� �� � � z OracleDialect.get_multi_columnsc C s� dd� |� d�D �}|d dk|dkd�}|dd � D ]�}|� d �\}}|�� }d |v rft|�|d < q6d |v r|t|�|d < q6d|v r�t|�|d< q6d|v r�t|�|d< q6d|v r�|dk|d< q6d|v r�t|�|d< q6d|v r6|dk|d< q6|S )Nc S s g | ] }|� � �qS rH )rG )r� �prH rH rI r� Y r� z9OracleDialect._parse_identity_options.<locals>.<listcomp>r r rL r )rM rN r �:z START WITH�startz INCREMENT BY� incrementZ MAX_VALUEZmaxvalueZ MIN_VALUEZminvalueZ CYCLE_FLAGr� �cycleZ CACHE_SIZE�cacheZ ORDER_FLAGrF )r� rG re )rE rH r r, rO �part�optionr� rH rH rI r% S s, �z%OracleDialect._parse_identity_optionsc K s0 | j |f||gtjtjd�|��}| �|||�S r� )�get_multi_table_commentr& r� r% r� r rH rH rI �get_table_comments s ���z OracleDialect.get_table_commentc C s� g }t j|v st j|v r�ttjjjtjjj�� tjjj |ktjjj� d��}t j|vrl|� tjjj dk�}n t j|vr�|� tjjj dk�}|� |� t j|v r�ttjjj�d�tjjj�� tjjj |ktjjj� d��}|� |� t|�dkr�|d }n"tj|� �d�} t| jj| jj�}|jj} |tjtjfv �r�|tju �rDdnd } |�� �tj t tj jj |ktj jj | ktj jj | k��}|�r�|� | � t!d ���}|S ) NzBIN$%r� r� r� r r r� r� rn r� )"r% r� r� r1 r Zall_tab_commentsr� r� r r� r� Znot_likeZ table_typer� r� Zall_mview_commentsr� r r� r" r� r� r� r& r� r� Zdistinctr� r� r) r� r� r� r+ ) rE r� r� rP r� ZqueriesZtbl_viewZmat_viewr� rc Zname_col�temprH rH rI �_comment_query� sZ � � � � � � ��z OracleDialect._comment_queryc sd �� �p �j�}��|�\} } ��|||| �} �j|| |d| d�} tj� d�� ���fdd�| D �S )r� Fr� z snapshot table for snapshot c 3 s@ | ]8\}}��� |�f|d ur0|���s0d|in� � fV qd S )Nr� )r� r* )r� r� r! �r$ Zignore_mat_viewr! rE rH rI r� � s � �� �z8OracleDialect.get_multi_table_comment.<locals>.<genexpr>)r� r� r� r2 r� r( Z table_comment) rE r~ r! r� r� rP r� rG r� r� r� r� r� rH r3 rI r/ � s � � �z%OracleDialect.get_multi_table_commentc K s0 | j |f||gtjtjd�|��}| �|||�S r� )�get_multi_indexesr& r� r% r� r rH rH rI � get_indexes� s ���zOracleDialect.get_indexesc C s t tjjjtjjjtjjjtjjjtjjj tjjj tjjj tjjj tj jj� �tj��tjt�tjjjtjjjktjjjtjjjk���tj t�tj jjtjjjktj jjtjjjktj jjtjjjk���tjjj|ktjjj�td����tjjjtjjj�S )Nr� ) r1 r Zall_ind_columnsr� r� � index_namer Z all_indexesr) � uniquenessr � prefix_length�descendZall_ind_expressionsr� r� r� r" r) Z index_ownerr� r Zcolumn_positionr� r� r� r+ r� )rE r� rH rH rI � _index_query� sZ � � ���� �����' ��-��zOracleDialect._index_queryr� c sd | � |p | j�}| �|�}dd� | j||||fi |��D �� | j|||dd|d�}� fdd�|D �S )Nc S s h | ]}|d dkr|d �qS )�constraint_type�P�constraint_namerH �r� r& rH rH rI rV 3 s �z2OracleDialect._get_indexes_rows.<locals>.<setcomp>Tr c s g | ]}|d � vr|�qS �r6 rH r> �ZpksrH rI r� E s �z3OracleDialect._get_indexes_rows.<locals>.<listcomp>)r� r� r: �_get_all_constraint_rowsr ) rE r~ r! r� r� rG r� r� r� rH r@ rI �_get_indexes_rows' s, � ��� � �z OracleDialect._get_indexes_rowsc s �j |�||||fi |��}ddd�} ddd�} ddh} tt���j|�||fi |��D �]z} ��| d �} ��| d �}��|f }| |vr�| g i | �| d d�d � || < }|d }| d | v r�d|d < | �| d d�r�| d |d< n|| }| d }|du�r�|d �d� d|v �r,|d �|� n"|d dd� |d< |d �|� | d �� dk�r�| d �� dk�svJ �|�di �}d||< qX| d �� dk�s�J ���| d �}|d �|� d|v rX|d �|� qXt j � � �fd d ���fd d �|D �D �S ) r� FT)Z NONUNIQUEZUNIQUE)ZDISABLEDr ZBITMAPzFUNCTION-BASED BITMAPr6 r� r7 )rd � column_namesr� r: r� r) Z oracle_bitmapr r8 r r� NrC r; ���r9 Zasc�descZcolumn_sorting)rE r c 3 s0 | ](}||�v r t �| �� �n� � fV qd S rC �r �values�r� r� )r$ �indexesrH rI r� � s �z2OracleDialect.get_multi_indexes.<locals>.<genexpr>c 3 s | ]}� �� |�fV qd S rC r� �r� Zobj_name�r! rE rH rI r� � s �) r� r r� rB r� r� r� r� � setdefaultr( rI )rE r~ r! r� r� rP r� rG r� r7 �enabledZ is_bitmapr& r6 r� Z table_indexesZ index_dict�dor� �csZcnrH )r$ rI r! rE rI r4 K sf �� �� � ��z OracleDialect.get_multi_indexesc K s0 | j |f||gtjtjd�|��}| �|||�S r� )�get_multi_pk_constraintr& r� r% r� r rH rH rI �get_pk_constraint� s ���z OracleDialect.get_pk_constraintc C s6 t j�d�}t j�d�}tt jjjt jjjt jjj|jj � d�|jj� d�|jj � d�|jj � d�t jjj t jjj � �t j��|t|jj t jjj kt jjj|jjk���|tt jjj|jj kt jjj|jjkt|jj�t�� �|jj|jjk����t jjj |kt jjj�td��t jjj�d��� t jjj|jj�S ) N�local�remote� local_column� remote_table� remote_column� remote_ownerr� )�Rr< �U�C) r Zall_cons_columnsr� r1 Zall_constraintsr� r� r; r= r r r� �search_condition� delete_ruler� r� r) r Zr_ownerZr_constraint_namer0 �positionr� r" r/ r� r� r+ r� )rE r� rR rS rH rH rI �_constraint_query� s\ � � �������! � ��*��z OracleDialect._constraint_queryc K s8 | � |p | j�}| �|�}t| j|||dd|d��}|S )NFTr )r� r� r^ r r ) rE r~ r! r� r� rG r� r� rG rH rH rI rA � s � �� z&OracleDialect._get_all_constraint_rowsc s� �j |�||||fi |��}tt��tj� �j|�||fi |��D ]n} | d dkrTqB��| d �} ��| d �} ��| d �} ��| f } | s�| | d< | g| d< qB| d �| � qB� �fdd ���fd d �|D �D �S ) r� r; r< r� r= rT rd �constrained_columnsc 3 s( | ] }||�v r�| n� � fV qd S rC rH rH )r$ � primary_keysrH rI r� s �z8OracleDialect.get_multi_pk_constraint.<locals>.<genexpr>c 3 s | ]}� �� |�fV qd S rC r� rJ rK rH rI r� s �)r� r r� r( Z pk_constraintrA r� r� )rE r~ r� r! r� rP r� rG r� r& r� r= r Ztable_pkrH )r$ r` r! rE rI rP � s6 ���� ��z%OracleDialect.get_multi_pk_constraintc K s0 | j |f||gtjtjd�|��}| �|||�S r� )�get_multi_foreign_keysr& r� r% r� r rH rH rI �get_foreign_keys# s ���z OracleDialect.get_foreign_keysc " s �j |�||||fi |��}|�dd�} ���p4�j�} t� } tt���j|�||fi |��D �]f} | d dkrrq^��| d �} ��| d �}��| f }|dus�J ���| d �}��| d �}��| d �}| d }��|�}|dur�| � |� |du �r4|�r|� d ��sd |� �}t � d |�p(d� d�� q^||v�r�|g d|g i d� ||< }| �rf||d< �du�sz|| k�r�||d< | d }|dk�r�||d d< n|| }|d � |� |d � |� q^| �r�| �r�ttjjjtjjjtjjjtjjj��tjjj�| ��}�j|||dd��� }i }|D ]:}��|d �}��|d �} |d |d f||| f< �q*d } ��� D ]�} | �� D ]p}|�d�|d f} |�| | �\}} | �r~��| �} | |d < �du�s�|| k�r��|�}!|!|d< nd|d< �q~�qrt j � � �fd d ���fd!d �|D �D �S )"r� rl Fr; rX r� r= NrT rU rV rW r� z6Got 'None' querying 'table_name' from all_cons_columnsrT z1 - does the user have proper rights to the table?)rd r_ �referred_schema�referred_table�referred_columnsrQ Z _ref_schemarc r\ z NO ACTIONrQ r0 r_ re r� r� r� r� )NNrd c 3 s0 | ](}||�v r t �| �� �n� � fV qd S rC rF rH )r$ �fkeysrH rI r� � s �z7OracleDialect.get_multi_foreign_keys.<locals>.<genexpr>c 3 s | ]}� �� |�fV qd S rC r� rJ rK rH rI r� � s �) r� r� r� r� �setr r� rA r� r� r* r# r� r� r1 r r� r� r� r� r� r� r� r� r� r� rG ry r( Z foreign_keys)"rE r~ r� r! r� rP r� rG r� rm r� Zall_remote_ownersr& r� r= Z table_fkeyrT rU rV Zremote_owner_origrW Zfkeyr\ r� r� Zremote_owners_lutr� Z synonym_owner�emptyZ table_fkeysr� Zsyn_nameZsn�rorH )r$ rf r! rE rI ra 8 s� �� ��� �� � ��� � � ��z$OracleDialect.get_multi_foreign_keysc K s0 | j |f||gtjtjd�|��}| �|||�S r� )� get_multi_unique_constraintsr& r� r% r� r rH rH rI �get_unique_constraints� s ���z$OracleDialect.get_unique_constraintsc s" �j |�||||fi |��}tt��dd� �j|�||fi |��D �} �j|�||fi |��D ]�} | d dkrpq^��| d �} | d } ��| �} ��| d �}��| f }| dus�J �| |vr�| g | | v r�| ndd � || < }n|| }|d �|� q^tj� � �fd d ���fd d �|D �D �S )r� c S s h | ] }|d �qS r? rH r> rH rH rI rV � s �z=OracleDialect.get_multi_unique_constraints.<locals>.<setcomp>r; rY r� r= rT N)rd rC Zduplicates_indexrC c 3 s0 | ](}||�v r t �| �� �n� � fV qd S rC rF rH )r$ � unique_consrH rI r� s ���z=OracleDialect.get_multi_unique_constraints.<locals>.<genexpr>c 3 s | ]}� �� |�fV qd S rC r� rJ rK rH rI r� s �) r� r r� rB rA r� r� r( Zunique_constraints)rE r~ r� r! r� rP r� rG r� Z index_namesr& r� Zconstraint_name_origr= r Ztable_ucZucrH )r$ r! rE rl rI rj � sR ������� �� ��z*OracleDialect.get_multi_unique_constraintsc K s |� dd�rZ| j|||g|d�}|rZt|�dks4J �|d }| �|d �}|d }|d }| �|�}| �|pp| j�} ttj j j �� tj j j |ktj j j| k��ttjj j�� tjj j|ktjj j| k��} | j|| |dd ��� } | d u �r t�|�r|� d |� �n|��n| S d S ) r� rl F)r� r� r r r� r� r� r� Nr� )r� r� r� r� r� r� r� r1 r r� r� r� r� r� r� r� r� r� r� r� r� r r� ) rE r~ r� r! r� rG Zsynonymsr& rd r� r� �rprH rH rI �get_view_definition s@ � � � ���� �z!OracleDialect.get_view_definitionc K s2 | j |f||gtj|tjd�|��}| �|||�S )r� )r! r� r� � include_allrP )�get_multi_check_constraintsr& r� r% r� )rE r~ r� r! ro rG r� rH rH rI �get_check_constraintsK s ��� z#OracleDialect.get_check_constraints)r� ro c s� �j |�||||fi |��} t�d�} tt�� �j|�|| fi |��D ]h} | d dkrXqF��| d �} ��| d �} | d }� �| f }| durF|s�| �|�sF|�| |d�� qFt j �� �fd d ���fd d �| D �D �S ) r� z..+?. IS NOT NULL$r; rZ r� r= r[ N)rd rI c 3 s( | ] }||� v r� | n�� fV qd S rC rH rH )�check_constraintsr$ rH rI r� � s �� �z<OracleDialect.get_multi_check_constraints.<locals>.<genexpr>c 3 s | ]}� �� |�fV qd S rC r� rJ rK rH rI r� � s �) r� r� r# r r rA r� r\ r� r( rr )rE r~ r! r� r� r� rP ro rG r� Znot_nullr& r� r= r[ Z table_checksrH )rr r$ r! rE rI rp ] s@ �� �� ��� ��z)OracleDialect.get_multi_check_constraintsc s6 t tjjj�}� j|||dd��� }� fdd�|D �S )NFr� c s g | ]}� � |��qS rH r� )r� �linkr� rH rI r� � r� z/OracleDialect._list_dblinks.<locals>.<listcomp>)r1 r Z all_db_linksr� r� r� r� )rE r~ r� r� �linksrH r� rI � _list_dblinks� s � zOracleDialect._list_dblinks)TFNFro T)N)NN)NN)N)NN)N)NNT)NN)NN)N)N)N)N)N)N)N)NN)NF)N)vrh r� r� rd Zsupports_statement_cacheZsupports_alterZmax_identifier_lengthr� Zinsert_returningZupdate_returningZdelete_returningZdiv_is_floordivZ supports_simple_order_by_labelZcte_follows_insertZreturns_native_bytesZsupports_sequencesZsequences_optionalZpostfetch_lastrowidZdefault_paramstylerw r$ Zrequires_name_normalizeZsupports_commentsZsupports_default_valuesZsupports_default_metavalueZsupports_empty_insertr| r� Zstatement_compilerr$ Z ddl_compilerrB Ztype_compiler_clsrS r� rd Zexecution_ctx_clsZreflection_optionsrP r� ZTable�Index� sa_selectableZSelectr" Zconstruct_argumentsr# Zdeprecated_paramsr� ru r� �propertyrv r� r� rs r� r� r� r� r� r� r� Zmemoized_propertyr� r' r, r� r� r� r� Z flexi_cacher5 Z dp_stringZdp_string_listr� r r� Z dp_plain_objr� r� r� r� r� r� r� r� r� r� r� r r r� r r r r r% r0 r2 r/ r5 r: rB r4 rQ r^ rA rP rb ra rk rj rn rq rp ru r# rH rH r� rI ri Q s� �� �� �� � � � � � <� & J � 6 �C H � 7 �( 4� �M 2� �- � � � �H � 2 � �9ri c @ s e Zd ZdZdd� ZdS )r� Zouter_join_columnc C s || _ d S rC )r� )rE r� rH rH rI r� � s z_OuterJoinColumn.__init__N)rh r� r� Z__visit_name__r� rH rH rH rI r� � s r� )`r! � __future__r � collectionsr Z dataclassesr � functoolsr r r� rT r �typesr r r r r r r r r r r r r r r r r r6 r r r r r r! r� r" r# Zenginer$ r% r& r' Zengine.reflectionr( r) r+ r, r- r. r/ r0 r1 r2 rw r3 r r4 Z sql.visitorsr5 r6 r7 r8 r9 r: r; r< r= r> rg r� ra r� �Booleanrz �DateTime�Daterw r$ ZGenericTypeCompilerrB r� r� Z DDLCompilerr$ ZIdentifierPreparerrS ZDefaultExecutionContextrd rp ri Z ClauseElementr� rH rH rH rI �<module> s� x � ��� & ~ \ sqlalchemy/dialects/oracle/__pycache__/__init__.cpython-39.pyc 0000644 00000002615 15125143220 0020342 0 ustar 00 a ��Jh� � @ s� d dl mZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ dd lm Z dd lm Z dd lm Z dd lm Z dd lm Z ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ dd lm Z dd lm Z dd lm Z dd l m Z dd l m!Z! e"d!efd"ej#i�Z$ej% e_%Z%d#Z&d$S )%� )� ModuleType� )�base)� cx_oracle)�oracledb)�BFILE)� BINARY_DOUBLE)� BINARY_FLOAT)�BLOB)�CHAR)�CLOB)�DATE)�DOUBLE_PRECISION)�FLOAT)�INTERVAL)�LONG)�NCHAR)�NCLOB)�NUMBER)�NVARCHAR)� NVARCHAR2)�RAW)�REAL)�ROWID)� TIMESTAMP)�VARCHAR)�VARCHAR2)�VECTOR)�VectorIndexConfig)�VectorIndexType)�VectorDistanceType)�VectorStorageFormat�oracledb_async�dialect) r r r r r r r r r r r r r r r r r r# r r r r r r r r r r! N)'�typesr � r r r r r r r r r r r r r r r r r r r r r r r r r r r r Zvectorr r! �typeZ dialect_asyncr" r# �__all__� r( r( �X/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/oracle/__init__.py�<module> sF � sqlalchemy/dialects/oracle/__pycache__/cx_oracle.cpython-39.pyc 0000644 00000133577 15125143220 0020556 0 ustar 00 a ��Jh$� � @ s� d Z ddlmZ ddlZddlZddlZddlmZ ddlm Z ddlm Z ddlm Z dd l m Z d d lmZ d d lmZ d d lmZ d dlmZ d dlmZ d dlmZ d dlmZ dZG dd� dej�ZG dd� dej �Z G dd� dej �Z G dd� de �Z G dd � d e ej!�Z"G d d � d e ej#�Z$G d d � d e �Z%G d!d"� d"ej&�Z'G d#d$� d$e ej(�Z)G d%d&� d&�Z*G d'd(� d(ej+�Z,G d)d*� d*ej-�Z.G d+d,� d,ej/�Z0G d-d.� d.ej1�Z2G d/d0� d0e*ej3�Z4G d1d2� d2e*ej5�Z6G d3d4� d4e*ej7�Z8G d5d6� d6e*ej9�Z:G d7d8� d8ej;�Z<G d9d:� d:ej=�Z>G d;d<� d<e*ej?�Z@G d=d>� d>ejA�ZBG d?d@� d@ejC�ZDG dAdB� dBejE�ZFG dCdD� dDe �ZGG dEdF� dFe �ZHG dGdH� dHe �ZIeIZJdS )IuTJ .. dialect:: oracle+cx_oracle :name: cx-Oracle :dbapi: cx_oracle :connectstring: oracle+cx_oracle://user:pass@hostname:port[/dbname][?service_name=<service>[&key=value&key=value...]] :url: https://oracle.github.io/python-cx_Oracle/ Description ----------- cx_Oracle was the original driver for Oracle Database. It was superseded by python-oracledb which should be used instead. DSN vs. Hostname connections ----------------------------- cx_Oracle provides several methods of indicating the target database. The dialect translates from a series of different URL forms. Hostname Connections with Easy Connect Syntax ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Given a hostname, port and service name of the target database, for example from Oracle Database's Easy Connect syntax then connect in SQLAlchemy using the ``service_name`` query string parameter:: engine = create_engine( "oracle+cx_oracle://scott:tiger@hostname:port?service_name=myservice&encoding=UTF-8&nencoding=UTF-8" ) Note that the default driver value for encoding and nencoding was changed to “UTF-8” in cx_Oracle 8.0 so these parameters can be omitted when using that version, or later. To use a full Easy Connect string, pass it as the ``dsn`` key value in a :paramref:`_sa.create_engine.connect_args` dictionary:: import cx_Oracle e = create_engine( "oracle+cx_oracle://@", connect_args={ "user": "scott", "password": "tiger", "dsn": "hostname:port/myservice?transport_connect_timeout=30&expire_time=60", }, ) Connections with tnsnames.ora or to Oracle Autonomous Database ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Alternatively, if no port, database name, or service name is provided, the dialect will use an Oracle Database DSN "connection string". This takes the "hostname" portion of the URL as the data source name. For example, if the ``tnsnames.ora`` file contains a TNS Alias of ``myalias`` as below: .. sourcecode:: text myalias = (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = mymachine.example.com)(PORT = 1521)) (CONNECT_DATA = (SERVER = DEDICATED) (SERVICE_NAME = orclpdb1) ) ) The cx_Oracle dialect connects to this database service when ``myalias`` is the hostname portion of the URL, without specifying a port, database name or ``service_name``:: engine = create_engine("oracle+cx_oracle://scott:tiger@myalias") Users of Oracle Autonomous Database should use this syntax. If the database is configured for mutural TLS ("mTLS"), then you must also configure the cloud wallet as shown in cx_Oracle documentation `Connecting to Autononmous Databases <https://cx-oracle.readthedocs.io/en/latest/user_guide/connection_handling.html#autonomousdb>`_. SID Connections ^^^^^^^^^^^^^^^ To use Oracle Database's obsolete System Identifier connection syntax, the SID can be passed in a "database name" portion of the URL:: engine = create_engine( "oracle+cx_oracle://scott:tiger@hostname:port/dbname" ) Above, the DSN passed to cx_Oracle is created by ``cx_Oracle.makedsn()`` as follows:: >>> import cx_Oracle >>> cx_Oracle.makedsn("hostname", 1521, sid="dbname") '(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=hostname)(PORT=1521))(CONNECT_DATA=(SID=dbname)))' Note that although the SQLAlchemy syntax ``hostname:port/dbname`` looks like Oracle's Easy Connect syntax it is different. It uses a SID in place of the service name required by Easy Connect. The Easy Connect syntax does not support SIDs. Passing cx_Oracle connect arguments ----------------------------------- Additional connection arguments can usually be passed via the URL query string; particular symbols like ``SYSDBA`` are intercepted and converted to the correct symbol:: e = create_engine( "oracle+cx_oracle://user:pass@dsn?encoding=UTF-8&nencoding=UTF-8&mode=SYSDBA&events=true" ) .. versionchanged:: 1.3 the cx_Oracle dialect now accepts all argument names within the URL string itself, to be passed to the cx_Oracle DBAPI. As was the case earlier but not correctly documented, the :paramref:`_sa.create_engine.connect_args` parameter also accepts all cx_Oracle DBAPI connect arguments. To pass arguments directly to ``.connect()`` without using the query string, use the :paramref:`_sa.create_engine.connect_args` dictionary. Any cx_Oracle parameter value and/or constant may be passed, such as:: import cx_Oracle e = create_engine( "oracle+cx_oracle://user:pass@dsn", connect_args={ "encoding": "UTF-8", "nencoding": "UTF-8", "mode": cx_Oracle.SYSDBA, "events": True, }, ) Note that the default driver value for ``encoding`` and ``nencoding`` was changed to "UTF-8" in cx_Oracle 8.0 so these parameters can be omitted when using that version, or later. Options consumed by the SQLAlchemy cx_Oracle dialect outside of the driver -------------------------------------------------------------------------- There are also options that are consumed by the SQLAlchemy cx_oracle dialect itself. These options are always passed directly to :func:`_sa.create_engine` , such as:: e = create_engine( "oracle+cx_oracle://user:pass@dsn", coerce_to_decimal=False ) The parameters accepted by the cx_oracle dialect are as follows: * ``arraysize`` - set the cx_oracle.arraysize value on cursors; defaults to ``None``, indicating that the driver default should be used (typically the value is 100). This setting controls how many rows are buffered when fetching rows, and can have a significant effect on performance when modified. .. versionchanged:: 2.0.26 - changed the default value from 50 to None, to use the default value of the driver itself. * ``auto_convert_lobs`` - defaults to True; See :ref:`cx_oracle_lob`. * ``coerce_to_decimal`` - see :ref:`cx_oracle_numeric` for detail. * ``encoding_errors`` - see :ref:`cx_oracle_unicode_encoding_errors` for detail. .. _cx_oracle_sessionpool: Using cx_Oracle SessionPool --------------------------- The cx_Oracle driver provides its own connection pool implementation that may be used in place of SQLAlchemy's pooling functionality. The driver pool supports Oracle Database features such dead connection detection, connection draining for planned database downtime, support for Oracle Application Continuity and Transparent Application Continuity, and gives support for Database Resident Connection Pooling (DRCP). Using the driver pool can be achieved by using the :paramref:`_sa.create_engine.creator` parameter to provide a function that returns a new connection, along with setting :paramref:`_sa.create_engine.pool_class` to ``NullPool`` to disable SQLAlchemy's pooling:: import cx_Oracle from sqlalchemy import create_engine from sqlalchemy.pool import NullPool pool = cx_Oracle.SessionPool( user="scott", password="tiger", dsn="orclpdb", min=1, max=4, increment=1, threaded=True, encoding="UTF-8", nencoding="UTF-8", ) engine = create_engine( "oracle+cx_oracle://", creator=pool.acquire, poolclass=NullPool ) The above engine may then be used normally where cx_Oracle's pool handles connection pooling:: with engine.connect() as conn: print(conn.scalar("select 1 from dual")) As well as providing a scalable solution for multi-user applications, the cx_Oracle session pool supports some Oracle features such as DRCP and `Application Continuity <https://cx-oracle.readthedocs.io/en/latest/user_guide/ha.html#application-continuity-ac>`_. Note that the pool creation parameters ``threaded``, ``encoding`` and ``nencoding`` were deprecated in later cx_Oracle releases. Using Oracle Database Resident Connection Pooling (DRCP) -------------------------------------------------------- When using Oracle Database's DRCP, the best practice is to pass a connection class and "purity" when acquiring a connection from the SessionPool. Refer to the `cx_Oracle DRCP documentation <https://cx-oracle.readthedocs.io/en/latest/user_guide/connection_handling.html#database-resident-connection-pooling-drcp>`_. This can be achieved by wrapping ``pool.acquire()``:: import cx_Oracle from sqlalchemy import create_engine from sqlalchemy.pool import NullPool pool = cx_Oracle.SessionPool( user="scott", password="tiger", dsn="orclpdb", min=2, max=5, increment=1, threaded=True, encoding="UTF-8", nencoding="UTF-8", ) def creator(): return pool.acquire( cclass="MYCLASS", purity=cx_Oracle.ATTR_PURITY_SELF ) engine = create_engine( "oracle+cx_oracle://", creator=creator, poolclass=NullPool ) The above engine may then be used normally where cx_Oracle handles session pooling and Oracle Database additionally uses DRCP:: with engine.connect() as conn: print(conn.scalar("select 1 from dual")) .. _cx_oracle_unicode: Unicode ------- As is the case for all DBAPIs under Python 3, all strings are inherently Unicode strings. In all cases however, the driver requires an explicit encoding configuration. Ensuring the Correct Client Encoding ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The long accepted standard for establishing client encoding for nearly all Oracle Database related software is via the `NLS_LANG <https://www.oracle.com/database/technologies/faq-nls-lang.html>`_ environment variable. Older versions of cx_Oracle use this environment variable as the source of its encoding configuration. The format of this variable is Territory_Country.CharacterSet; a typical value would be ``AMERICAN_AMERICA.AL32UTF8``. cx_Oracle version 8 and later use the character set "UTF-8" by default, and ignore the character set component of NLS_LANG. The cx_Oracle driver also supported a programmatic alternative which is to pass the ``encoding`` and ``nencoding`` parameters directly to its ``.connect()`` function. These can be present in the URL as follows:: engine = create_engine( "oracle+cx_oracle://scott:tiger@tnsalias?encoding=UTF-8&nencoding=UTF-8" ) For the meaning of the ``encoding`` and ``nencoding`` parameters, please consult `Characters Sets and National Language Support (NLS) <https://cx-oracle.readthedocs.io/en/latest/user_guide/globalization.html#globalization>`_. .. seealso:: `Characters Sets and National Language Support (NLS) <https://cx-oracle.readthedocs.io/en/latest/user_guide/globalization.html#globalization>`_ - in the cx_Oracle documentation. Unicode-specific Column datatypes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The Core expression language handles unicode data by use of the :class:`.Unicode` and :class:`.UnicodeText` datatypes. These types correspond to the VARCHAR2 and CLOB Oracle Database datatypes by default. When using these datatypes with Unicode data, it is expected that the database is configured with a Unicode-aware character set, as well as that the ``NLS_LANG`` environment variable is set appropriately (this applies to older versions of cx_Oracle), so that the VARCHAR2 and CLOB datatypes can accommodate the data. In the case that Oracle Database is not configured with a Unicode character set, the two options are to use the :class:`_types.NCHAR` and :class:`_oracle.NCLOB` datatypes explicitly, or to pass the flag ``use_nchar_for_unicode=True`` to :func:`_sa.create_engine`, which will cause the SQLAlchemy dialect to use NCHAR/NCLOB for the :class:`.Unicode` / :class:`.UnicodeText` datatypes instead of VARCHAR/CLOB. .. versionchanged:: 1.3 The :class:`.Unicode` and :class:`.UnicodeText` datatypes now correspond to the ``VARCHAR2`` and ``CLOB`` Oracle Database datatypes unless the ``use_nchar_for_unicode=True`` is passed to the dialect when :func:`_sa.create_engine` is called. .. _cx_oracle_unicode_encoding_errors: Encoding Errors ^^^^^^^^^^^^^^^ For the unusual case that data in Oracle Database is present with a broken encoding, the dialect accepts a parameter ``encoding_errors`` which will be passed to Unicode decoding functions in order to affect how decoding errors are handled. The value is ultimately consumed by the Python `decode <https://docs.python.org/3/library/stdtypes.html#bytes.decode>`_ function, and is passed both via cx_Oracle's ``encodingErrors`` parameter consumed by ``Cursor.var()``, as well as SQLAlchemy's own decoding function, as the cx_Oracle dialect makes use of both under different circumstances. .. versionadded:: 1.3.11 .. _cx_oracle_setinputsizes: Fine grained control over cx_Oracle data binding performance with setinputsizes ------------------------------------------------------------------------------- The cx_Oracle DBAPI has a deep and fundamental reliance upon the usage of the DBAPI ``setinputsizes()`` call. The purpose of this call is to establish the datatypes that are bound to a SQL statement for Python values being passed as parameters. While virtually no other DBAPI assigns any use to the ``setinputsizes()`` call, the cx_Oracle DBAPI relies upon it heavily in its interactions with the Oracle Database client interface, and in some scenarios it is not possible for SQLAlchemy to know exactly how data should be bound, as some settings can cause profoundly different performance characteristics, while altering the type coercion behavior at the same time. Users of the cx_Oracle dialect are **strongly encouraged** to read through cx_Oracle's list of built-in datatype symbols at https://cx-oracle.readthedocs.io/en/latest/api_manual/module.html#database-types. Note that in some cases, significant performance degradation can occur when using these types vs. not, in particular when specifying ``cx_Oracle.CLOB``. On the SQLAlchemy side, the :meth:`.DialectEvents.do_setinputsizes` event can be used both for runtime visibility (e.g. logging) of the setinputsizes step as well as to fully control how ``setinputsizes()`` is used on a per-statement basis. .. versionadded:: 1.2.9 Added :meth:`.DialectEvents.setinputsizes` Example 1 - logging all setinputsizes calls ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The following example illustrates how to log the intermediary values from a SQLAlchemy perspective before they are converted to the raw ``setinputsizes()`` parameter dictionary. The keys of the dictionary are :class:`.BindParameter` objects which have a ``.key`` and a ``.type`` attribute:: from sqlalchemy import create_engine, event engine = create_engine("oracle+cx_oracle://scott:tiger@host/xe") @event.listens_for(engine, "do_setinputsizes") def _log_setinputsizes(inputsizes, cursor, statement, parameters, context): for bindparam, dbapitype in inputsizes.items(): log.info( "Bound parameter name: %s SQLAlchemy type: %r DBAPI object: %s", bindparam.key, bindparam.type, dbapitype, ) Example 2 - remove all bindings to CLOB ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``CLOB`` datatype in cx_Oracle incurs a significant performance overhead, however is set by default for the ``Text`` type within the SQLAlchemy 1.2 series. This setting can be modified as follows:: from sqlalchemy import create_engine, event from cx_Oracle import CLOB engine = create_engine("oracle+cx_oracle://scott:tiger@host/xe") @event.listens_for(engine, "do_setinputsizes") def _remove_clob(inputsizes, cursor, statement, parameters, context): for bindparam, dbapitype in list(inputsizes.items()): if dbapitype is CLOB: del inputsizes[bindparam] .. _cx_oracle_lob: LOB Datatypes -------------- LOB datatypes refer to the "large object" datatypes such as CLOB, NCLOB and BLOB. Modern versions of cx_Oracle is optimized for these datatypes to be delivered as a single buffer. As such, SQLAlchemy makes use of these newer type handlers by default. To disable the use of newer type handlers and deliver LOB objects as classic buffered objects with a ``read()`` method, the parameter ``auto_convert_lobs=False`` may be passed to :func:`_sa.create_engine`, which takes place only engine-wide. .. _cx_oracle_returning: RETURNING Support ----------------- The cx_Oracle dialect implements RETURNING using OUT parameters. The dialect supports RETURNING fully. Two Phase Transactions Not Supported ------------------------------------ Two phase transactions are **not supported** under cx_Oracle due to poor driver support. The newer :ref:`oracledb` dialect however **does** support two phase transactions. .. _cx_oracle_numeric: Precision Numerics ------------------ SQLAlchemy's numeric types can handle receiving and returning values as Python ``Decimal`` objects or float objects. When a :class:`.Numeric` object, or a subclass such as :class:`.Float`, :class:`_oracle.DOUBLE_PRECISION` etc. is in use, the :paramref:`.Numeric.asdecimal` flag determines if values should be coerced to ``Decimal`` upon return, or returned as float objects. To make matters more complicated under Oracle Database, the ``NUMBER`` type can also represent integer values if the "scale" is zero, so the Oracle Database-specific :class:`_oracle.NUMBER` type takes this into account as well. The cx_Oracle dialect makes extensive use of connection- and cursor-level "outputtypehandler" callables in order to coerce numeric values as requested. These callables are specific to the specific flavor of :class:`.Numeric` in use, as well as if no SQLAlchemy typing objects are present. There are observed scenarios where Oracle Database may send incomplete or ambiguous information about the numeric types being returned, such as a query where the numeric types are buried under multiple levels of subquery. The type handlers do their best to make the right decision in all cases, deferring to the underlying cx_Oracle DBAPI for all those cases where the driver can make the best decision. When no typing objects are present, as when executing plain SQL strings, a default "outputtypehandler" is present which will generally return numeric values which specify precision and scale as Python ``Decimal`` objects. To disable this coercion to decimal for performance reasons, pass the flag ``coerce_to_decimal=False`` to :func:`_sa.create_engine`:: engine = create_engine("oracle+cx_oracle://dsn", coerce_to_decimal=False) The ``coerce_to_decimal`` flag only impacts the results of plain string SQL statements that are not otherwise associated with a :class:`.Numeric` SQLAlchemy type (or a subclass of such). .. versionchanged:: 1.2 The numeric handling system for cx_Oracle has been reworked to take advantage of newer cx_Oracle features as well as better integration of outputtypehandlers. � )� annotationsN� )�base)�OracleCompiler)� OracleDialect)�OracleExecutionContext)�_OracleDateLiteralRender� )�exc)�util)�cursor)� interfaces)� processors)�sqltypes)�is_sql_compileri c @ s& e Zd Zdd� Zddd�Zdd� ZdS ) �_OracleIntegerc C s t S �N��int��self�dbapi� r �Y/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/oracle/cx_oracle.py�get_dbapi_type s z _OracleInteger.get_dbapi_typeNc C s( |j }|j|jd|d ur |n|jtd�S )N� �� arraysize� outconverter)r �var�STRINGr r )r �dialectr r � cx_Oracler r r �_cx_oracle_var s �z _OracleInteger._cx_oracle_varc s � �fdd�}|S )Nc s �� � | �S r )r# �r �name� default_type�size� precision�scale�r! r r r �handler s z<_OracleInteger._cx_oracle_outputtypehandler.<locals>.handlerr �r r! r+ r r* r � _cx_oracle_outputtypehandler s z+_OracleInteger._cx_oracle_outputtypehandler)N)�__name__� __module__� __qualname__r r# r- r r r r r s r c @ s( e Zd ZdZdd� Zdd� Zdd� ZdS ) �_OracleNumericFc s> | j dkrd S | jr4t�tj| j�� � fdd�}|S tjS d S )Nr c s6 t | ttf�r� | �S | d ur.| �� r.t| �S | S d S r )� isinstancer �float� is_infinite��value�� processorr r �process% s z._OracleNumeric.bind_processor.<locals>.process)r) � asdecimalr Z to_decimal_processor_factory�decimal�DecimalZ _effective_decimal_return_scaleZto_float�r r! r9 r r7 r �bind_processor s � z _OracleNumeric.bind_processorc C s d S r r �r r! �coltyper r r �result_processor1 s z _OracleNumeric.result_processorc s |j � � �fdd�}|S )Nc s� d }|rF�j r,|� jkr$|}tj}qDtj}q��jr>|dkr>d S � j}n<�j rj|� jkrb|}tj}q�tj}n�jr||dkr|d S � j}| j|d| j|d�S )Nr r r )r: � NATIVE_FLOATr; r< � is_numberr r )r r% r& r' r( r) r �type_�r" r r r r+ 7 s0 �z<_OracleNumeric._cx_oracle_outputtypehandler.<locals>.handler)r r, r rE r r- 4 s ,z+_OracleNumeric._cx_oracle_outputtypehandlerN)r. r/ r0 rC r> rA r- r r r r r1 s r1 c @ s e Zd Zdd� ZdS )� _OracleUUIDc C s |j S r )r r r r r r g s z_OracleUUID.get_dbapi_typeN�r. r/ r0 r r r r r rF f s rF c @ s e Zd Zdd� ZdS )�_OracleBinaryFloatc C s |j S r )rB r r r r r l s z!_OracleBinaryFloat.get_dbapi_typeNrG r r r r rH k s rH c @ s e Zd ZdS )�_OracleBINARY_FLOATN�r. r/ r0 r r r r rI p s rI c @ s e Zd ZdS )�_OracleBINARY_DOUBLENrJ r r r r rK t s rK c @ s e Zd ZdZdS )� _OracleNUMBERTN)r. r/ r0 rC r r r r rL x s rL c @ s e Zd Zdd� Zdd� ZdS )� _CXOracleDatec C s d S r r �r r! r r r r> } s z _CXOracleDate.bind_processorc C s dd� }|S )Nc S s | d ur| � � S | S d S r )�dater5 r r r r9 � s z/_CXOracleDate.result_processor.<locals>.processr )r r! r@ r9 r r r rA � s z _CXOracleDate.result_processorN)r. r/ r0 r> rA r r r r rM | s rM c @ s e Zd Zdd� ZdS )�_CXOracleTIMESTAMPc C s | � |�S r )Z_literal_processor_datetimerN r r r �literal_processor� s z$_CXOracleTIMESTAMP.literal_processorN)r. r/ r0 rQ r r r r rP � s rP c @ s e Zd ZdS )� _LOBDataTypeNrJ r r r r rR � s rR c @ s e Zd Zdd� ZdS )� _OracleCharc C s |j S r )� FIXED_CHARr r r r r � s z_OracleChar.get_dbapi_typeNrG r r r r rS � s rS c @ s e Zd Zdd� ZdS )� _OracleNCharc C s |j S r )� FIXED_NCHARr r r r r � s z_OracleNChar.get_dbapi_typeNrG r r r r rU � s rU c @ s e Zd Zdd� ZdS )�_OracleUnicodeStringNCHARc C s |j S r )�NCHARr r r r r � s z(_OracleUnicodeStringNCHAR.get_dbapi_typeNrG r r r r rW � s rW c @ s e Zd Zdd� ZdS )�_OracleUnicodeStringCHARc C s |j S r �Z LONG_STRINGr r r r r � s z'_OracleUnicodeStringCHAR.get_dbapi_typeNrG r r r r rY � s rY c @ s e Zd Zdd� ZdS )�_OracleUnicodeTextNCLOBc C s |j S r ��DB_TYPE_NVARCHARr r r r r � s z&_OracleUnicodeTextNCLOB.get_dbapi_typeNrG r r r r r[ � s r[ c @ s e Zd Zdd� ZdS )�_OracleUnicodeTextCLOBc C s |j S r r\ r r r r r � s z%_OracleUnicodeTextCLOB.get_dbapi_typeNrG r r r r r^ � s r^ c @ s e Zd Zdd� ZdS )� _OracleTextc C s |j S r r\ r r r r r � s z_OracleText.get_dbapi_typeNrG r r r r r_ � s r_ c @ s e Zd Zdd� ZdS )� _OracleLongc C s |j S r rZ r r r r r � s z_OracleLong.get_dbapi_typeNrG r r r r r` � s r` c @ s e Zd ZdS )� _OracleStringNrJ r r r r ra � s ra c @ s e Zd Zdd� ZdS )� _OracleEnumc s t j�| |�� � fdd�}|S )Nc s � | �}|S r r )r6 Zraw_str�Z enum_procr r r9 � s z+_OracleEnum.bind_processor.<locals>.process)r �Enumr> r= r rc r r> � s z_OracleEnum.bind_processorN)r. r/ r0 r> r r r r rb � s rb c s, e Zd Zdd� Zdd� Z� fdd�Z� ZS )� _OracleBinaryc C s |j S r )� DB_TYPE_RAWr r r r r � s z _OracleBinary.get_dbapi_typec C s d S r r rN r r r r> � s z _OracleBinary.bind_processorc s |j s d S t� �||�S d S r )�auto_convert_lobs�superrA r? �� __class__r r rA � s z _OracleBinary.result_processor)r. r/ r0 r r> rA � __classcell__r r ri r re � s re c @ s e Zd Zdd� ZdS )�_OracleIntervalc C s |j S r )�INTERVALr r r r r � s z _OracleInterval.get_dbapi_typeNrG r r r r rl � s rl c @ s e Zd ZdS )� _OracleRawNrJ r r r r rn � s rn c @ s e Zd Zdd� ZdS )� _OracleRowidc C s |j S r )�ROWIDr r r r r � s z_OracleRowid.get_dbapi_typeNrG r r r r ro � s ro c @ s> e Zd ZdZdZe�dddddddddddd� �Zdd � Zd S ) �OracleCompiler_cx_oracleTF�P�A�Z�C) �%�(�)�:�.�[�]� �\�/�?c s� t |dd �}|du s4|dur\� j�|�r\|�dd�s\d| }||d< |}tj� |fi |��S |�dd �}|s� j�|�r�� j�� fdd�|�}|d � � s�|d d kr�d | }||d< |}n,|d � � s�|d d kr�d | }||d< |}tj� |fi |��S ) N�quoteTFZ post_compilez"%s"� escaped_fromc s � j | �d� S �Nr )Z_bind_translate_chars�group)�m�r r r �<lambda>, � z;OracleCompiler_cx_oracle.bindparam_string.<locals>.<lambda>r �_�D) �getattr�preparerZ_bindparam_requires_quotes�getr �bindparam_stringZ_bind_translate_re�search�sub�isdigit)r r% �kwr� Z quoted_namer� �new_namer r� r r� s: �� � � �z)OracleCompiler_cx_oracle.bindparam_stringN) r. r/ r0 �_oracle_cx_sql_compiler�_oracle_returningr � immutabledictZbindname_escape_charactersr� r r r r rq � s" ��rq c s^ e Zd ZdZdd� Zdd� Zdd� Z� fdd �Zd d � Zd d � Z dd�dd�Z dd� Z � Z S )� OracleExecutionContext_cx_oracleNc C s~ | j js| j j�rz| j}|d us$J �t| j�}| j j}| j j�� D �]4}|j rB| j j | }|j � | j �}t|d�r�|j| j | j|d�||< n�|�| j j�}| j j}|d us�J �|d u r�t�d|j|j f ��t|t��r||jkr�|j}n||jkr�|j}| jj |dd� |d�||< n@t|t ��rB|j �rB| jj t j |d�||< n| jj ||d�||< | jD ]} || | |�!||�< �q\qBd S )Nr# �r zXCannot create out parameter for parameter %r - its type %r is not supported by cx_oraclec S s | � � S r )�readr5 r r r r� w r� zOOracleExecutionContext_cx_oracle._generate_out_parameter_vars.<locals>.<lambda>�r r )"�compiledZhas_out_parametersr� �out_parameters�len� parametersZescaped_bind_namesZbinds�valuesZ isoutparamZ bind_names�typeZ dialect_implr! �hasattrr# r r r r �InvalidRequestError�keyr2 rR r] �NCLOBrf �BLOBr r1 r: r; r< r� ) r r� Z len_paramsZquoted_bind_namesZ bindparamr% Z type_impl�dbtyper" �paramr r r � _generate_out_parameter_vars> s\ � �� � ��� � �z=OracleExecutionContext_cx_oracle._generate_out_parameter_varsc sj i �| j jD ]6\}}}}|�| jd| j�}|r | j�|�}|�|< q �rf| jj� � �fdd�}|| j_d S )NZcx_oracle_outputtypehandlerc s4 |�v r �| | |||||�S � | |||||�S d S r r r$ �Zdefault_handlerZoutput_handlersr r �output_type_handler� s � �zaOracleExecutionContext_cx_oracle._generate_cursor_outputtype_handler.<locals>.output_type_handler) r� �_result_columnsZ_cached_custom_processorr! �_get_cx_oracle_type_handlerZdenormalize_name�_dbapi_connection�outputtypehandlerr )r �keynamer% ZobjectsrD r+ Zdenormalized_namer� r r� r �#_generate_cursor_outputtype_handler� s � zDOracleExecutionContext_cx_oracle._generate_cursor_outputtype_handlerc C s t |d�r|�| j�S d S d S )Nr- )r� r- r! )r �implr r r r� � s z<OracleExecutionContext_cx_oracle._get_cx_oracle_type_handlerc s6 t � �� t| jdd�s d S i | _| �� | �� d S )Nr� F)rh �pre_execr� r� r� r� r� r� ri r r r� � s z)OracleExecutionContext_cx_oracle.pre_execc C sR | j rNt| j �rN| j jrN| j| jdd�}tj| jdd� | j jD �|d�}|| _d S )NT�� _internalc S s g | ]}|j d f�qS r )r� )�.0�entryr r r � <listcomp>� s �z>OracleExecutionContext_cx_oracle.post_exec.<locals>.<listcomp>)�initial_buffer) r� r r� �fetchall_for_returningr �_cursorZ FullyBufferedCursorFetchStrategyr� Zcursor_fetch_strategy)r r� Zfetch_strategyr r r � post_exec� s" ������ z*OracleExecutionContext_cx_oracle.post_execc C s | j �� }| jjr | jj|_|S r )r� r r! r )r �cr r r � create_cursor� s z.OracleExecutionContext_cx_oracle.create_cursorFr� c sP � j }|s|d u s t|�r |js(td��t� j�}tt� fdd�t|�D �� �S )Nz7execution context was not prepared for Oracle RETURNINGc s( g | ] }d d� � j d|� � jD ��qS )c S s g | ]}|pd D ]}|�qqS )r r )r� Z stmt_result�valr r r r� � s �zVOracleExecutionContext_cx_oracle.fetchall_for_returning.<locals>.<listcomp>.<listcomp>Zret_)r� r� )r� �jr� r r r� � s ���zKOracleExecutionContext_cx_oracle.fetchall_for_returning.<locals>.<listcomp>) r� r r� �NotImplementedErrorr� r� �list�zip�range)r r r� r� Znumcolsr r� r r� � s( ����� ���z7OracleExecutionContext_cx_oracle.fetchall_for_returningc s � j jr J �� fdd�|D �S )Nc s g | ]}� j �� j| ��qS r )r! � _paramvalr� )r� r% r� r r r� s �zMOracleExecutionContext_cx_oracle.get_out_parameter_values.<locals>.<listcomp>)r� Z returning)r Zout_param_namesr r� r �get_out_parameter_values� s �z9OracleExecutionContext_cx_oracle.get_out_parameter_values) r. r/ r0 r� r� r� r� r� r� r� r� r� rk r r ri r r� ; s O %r� c 5 s� e Zd ZdZeZeZdZdZ dZ dZ dZ dZ ejjZdZe�ejejeejeej ee j e e j e!ej"e#e j$e%ej&e'ej(e)ej*e j+ej,e-e j.e-ej/e0ej1e2ej3e4ej5e6ej7e8ej9e:e j;e<e j=e>ej?e@ejAeBejCeDe jEeFe jGeHi�ZeIZJdZKe�L� ZMejNdd�d3dd��ZOdd � ZPeQd d � �ZR� fd d �ZSdd� ZT� fdd�ZUdd� ZVdd� ZWdd� ZXeYjZZ[dd� Z\dd� Z]d d � Z^d d � Z_d d!� Z`d"d#� Zad4d$d%�Zbd&d'� Zcd(d)� Zdd5d+d,�Zed6d-d.�Zfd/d0� Zgd1d2� Zh� ZiS )7�OracleDialect_cx_oracleTZ cx_oracleN)�1.3aA The 'threaded' parameter to the cx_oracle/oracledb dialect is deprecated as a dialect-level argument, and will be removed in a future release. As of version 1.3, it defaults to False rather than True. The 'threaded' option can be passed to cx_Oracle directly in the URL query string passed to :func:`_sa.create_engine`.)�threadedc K s� t j| fi |�� || _|| _|r,d|i| _|d ur:|| _|| _|| _| jrp| j � � | _ t | j t j < t| j t j< | j}| �|� |d ur�|j|j|j|j|j|j|j|j|j|j|j t |j h | _ dd� | _ d S )NZencodingErrorsc S s | � � S r )�getvaluer5 r r r r� ~ r� z2OracleDialect_cx_oracle.__init__.<locals>.<lambda>)!r �__init__r �encoding_errors�_cursor_var_unicode_kwargs�_cx_oracle_threadedrg �coerce_to_decimalZ_use_nchar_for_unicode�colspecs�copyrW r �Unicoder[ � UnicodeTextr � _load_versionZDATETIMEr] rf r� �CLOBZLOBr� rX rV rT � TIMESTAMPr rB Zinclude_set_input_sizesr� )r rg r� r r� r� �kwargs� dbapi_moduler r r r� @ s@ � �z OracleDialect_cx_oracle.__init__c C sb d}|d ur:t �d|j�}|r:tdd� |�ddd�D ��}|| _| jdk r^| jdkr^t�d ��d S ) N)r r r z(\d+)\.(\d+)(?:\.(\d+))?c s s | ]}|d urt |�V qd S r r �r� �xr r r � <genexpr>� s z8OracleDialect_cx_oracle._load_version.<locals>.<genexpr>r � r )� z+cx_Oracle version 8 and above are supported)�re�match�version�tupler� Z cx_oracle_verr r� )r r� r� r� r r r r� � s ��z%OracleDialect_cx_oracle._load_versionc C s dd l }|S r� )r" )�clsr" r r r � import_dbapi� s z$OracleDialect_cx_oracle.import_dbapic s t � �|� | �|� d S r )rh � initialize�_detect_decimal_char�r � connectionri r r r� � s z"OracleDialect_cx_oracle.initializec C s� |� � �z}|�t�}|�dd|i� |�� }|�dd�\}}}|�d|||d�� |�� }|d u rlt�d��|d } W d � n1 s�0 Y | S ) Nz� begin :trans_id := dbms_transaction.local_transaction_id( TRUE ); end; �trans_idrz r� z�SELECT CASE BITAND(t.flag, POWER(2, 28)) WHEN 0 THEN 'READ COMMITTED' ELSE 'SERIALIZABLE' END AS isolation_level FROM v$transaction t WHERE (t.xidusn, t.xidslot, t.xidsqn) = ((:xidusn, :xidslot, :xidsqn)))�xidusn�xidslot�xidsqnz"could not retrieve isolation levelr ) r r �str�executer� �split�fetchoner r� ) r �dbapi_connectionr Zoutvalr� r� r� r� �row�resultr r r �get_isolation_level� s& � � �&z+OracleDialect_cx_oracle.get_isolation_levelc s t � �|�dg S )N� AUTOCOMMIT)rh �get_isolation_level_values)r r� ri r r r� � s �z2OracleDialect_cx_oracle.get_isolation_level_valuesc C sZ |dkrd|_ nFd|_ |�� |�� � }|�d|� �� W d � n1 sL0 Y d S )Nr� TFz"ALTER SESSION SET ISOLATION_LEVEL=)Z autocommit�rollbackr r� )r r� �levelr r r r �set_isolation_level� s z+OracleDialect_cx_oracle.set_isolation_levelc s� |j }|�� �V}�fdd�}||_|�d� |�� d }|�d�d }|d �� rVJ �W d � n1 sj0 Y |�_�jdkr��j� �j �� �fdd ��_��fd d ��_ d S ) Nc s | j � jjd| jd�S )Nr r� )r r r r )r r% Z defaultTyper' r( r) r� r r r� � s �zIOracleDialect_cx_oracle._detect_decimal_char.<locals>.output_type_handlerzSELECT 1.1 FROM DUALr �0r rz c s � | � �jd��S �Nrz ��replace� _decimal_charr5 )�_detect_decimalr r r r� � s �z>OracleDialect_cx_oracle._detect_decimal_char.<locals>.<lambda>c s � | � �jd��S r� r� r5 )� _to_decimalr r r r� � s �) r� r r� r� r� �lstripr� r� r� r� )r r� r� r r� r6 Z decimal_charr )r� r� r r r� � s . z,OracleDialect_cx_oracle._detect_decimal_charc C s d|v r| � |�S t|�S d S r� )r� r )r r6 r r r r� s z'OracleDialect_cx_oracle._detect_decimalc s@ | ��j � tdd�����tdd������ ���fdd�}|S )z^establish the default outputtypehandler established at the connection level. T)r: Fc s2 |� j krx|� jurx�js d S |dkrF|dv rF| j� jd�j| jd�S |rd|dkrd�| |||||�S �| |||||�S n��jr�|� j� jfv r�|� j ur�|� j ur�| jt || jfi �j��S �j �r|� j � j fv �r|� j u r� j n� j}| j|t| jfi �j��S �j �r.|� jfv �r.| �� jt| j�S d S )Nr )r i����r r� )�NUMBERrB r� r r r� r r� rT r� r� r� rg ZDB_TYPE_VARCHARr] �_CX_ORACLE_MAGIC_LOB_SIZEr� rf )r r% r& r' r( r) �typ�r" r! Z float_handlerZnumber_handlerr r r� s| ��� � ������� �� ����� ��z\OracleDialect_cx_oracle._generate_connection_outputtype_handler.<locals>.output_type_handler)r rL r- )r r� r r r �'_generate_connection_outputtype_handler s ����Gz?OracleDialect_cx_oracle._generate_connection_outputtype_handlerc s | � � � � fdd�}|S )Nc s � | _ d S r )r� )�conn�r� r r � on_connectf s z6OracleDialect_cx_oracle.on_connect.<locals>.on_connect)r )r r r r r r c s z"OracleDialect_cx_oracle.on_connectc st t |j�}dD ]H}||v rtj� j� d|�d�dd� t�||t� t� ||�|�� q|j }|�dd �}|sr|r�|j }|r�t |�}nd}|r�|r�t � d��|r�d |i}|r�d|i}� jj|j|fi |��}n|j}|d ur�||d < |jd ur�|j|d < |jd u�r|j|d < � jd u�r(|�d � j� � fdd�} t�|d| � t�|d t� t�|dt� t�|d| � g |fS )N)Zuse_ansirg z dialect option zK should only be passed to create_engine directly, not within the URL stringr� )r� � service_namei� zI"service_name" option shouldn't be used with a "database" part of the urlZsid�dsn�password�userr� c sL t | t�rDz t| �}W n& ty< | �� } t� j| � Y S 0 |S n| S d S r )r2 r� r � ValueError�upperr� r )r6 Zint_valr� r r �convert_cx_oracle_constant� s zOOracleDialect_cx_oracle.create_connect_args.<locals>.convert_cx_oracle_constant�mode�eventsZpurity)�dict�queryr Zwarn_deprecated�driverZcoerce_kw_type�bool�setattr�pop�database�portr r r� r Zmakedsn�hostr �usernamer� � setdefault) r �url�opts�optr r r Zmakedsn_kwargsr r r r� r �create_connect_argsk sP � � z+OracleDialect_cx_oracle.create_connect_argsc C s t dd� |jj�d�D ��S )Nc s s | ]}t |�V qd S r r r� r r r r� � r� zCOracleDialect_cx_oracle._get_server_version_info.<locals>.<genexpr>rz )r� r� r� r� r� r r r �_get_server_version_info� s z0OracleDialect_cx_oracle._get_server_version_infoc C s^ |j \}t|| jj| jjf�r.dt|�v r.dS t|d�rF|jdv rFdS t� dt|��rZdS dS )Nz not connectedT�code> i) i* i � i\ i? z(^(?:DPI-1010|DPI-1080|DPY-1001|DPY-4011)F) �argsr2 r ZInterfaceErrorZ DatabaseErrorr� r� r! r� r� )r �er� r �errorr r r � is_disconnect� s � �z%OracleDialect_cx_oracle.is_disconnectc C s" t �ddd �}dd| dd fS )Nr r� � i4 z%032x� )�random�randint)r Zid_r r r � create_xid� s z"OracleDialect_cx_oracle.create_xidc C s" t |t�rt|�}|�||� d S r )r2 r� r� Z executemany)r r Z statementr� �contextr r r �do_executemany� s z&OracleDialect_cx_oracle.do_executemanyc C s |j j|� ||j jd< d S )NZ cx_oracle_xid)r� �begin�info)r r� �xidr r r �do_begin_twophase� s z)OracleDialect_cx_oracle.do_begin_twophasec C s |j �� }||jd< d S )N�cx_oracle_prepared)r� �preparer/ )r r� r0 r� r r r �do_prepare_twophase� s z+OracleDialect_cx_oracle.do_prepare_twophaseFc C s | � |j� d S r )Z do_rollbackr� )r r� r0 � is_prepared�recoverr r r �do_rollback_twophase� s z,OracleDialect_cx_oracle.do_rollback_twophasec C s< |s| � |j� n&|r td��|jd }|r8| � |j� d S )Nz*2pc recovery not implemented for cx_Oracler2 )Z do_commitr� r� r/ )r r� r0 r5 r6 Z oci_preparedr r r �do_commit_twophase� s � z*OracleDialect_cx_oracle.do_commit_twophasec C sH | j r |jdd� |D �� n(dd� |D �}|jf i dd� |D ��� d S )Nc S s g | ]\}}}|�qS r r �r� r� r� Zsqltyper r r r� � r� z>OracleDialect_cx_oracle.do_set_input_sizes.<locals>.<listcomp>c s s | ]\}}}|r||fV qd S r r r9 r r r r� s �z=OracleDialect_cx_oracle.do_set_input_sizes.<locals>.<genexpr>c S s i | ]\}}||�qS r r )r� r� r� r r r � <dictcomp> r� z>OracleDialect_cx_oracle.do_set_input_sizes.<locals>.<dictcomp>)� positionalZ setinputsizes)r r Zlist_of_tuplesr, Z collectionr r r �do_set_input_sizes� s ��z*OracleDialect_cx_oracle.do_set_input_sizesc C s t d��d S )Nz5recover two phase query for cx_Oracle not implemented)r� r� r r r �do_recover_twophase s �z+OracleDialect_cx_oracle.do_recover_twophase)TTNNN)N)TF)TF)jr. r/ r0 Zsupports_statement_cacher� Zexecution_ctx_clsrq Zstatement_compilerZsupports_sane_rowcountZ supports_sane_multi_rowcountZ insert_executemany_returningZ4insert_executemany_returning_sort_by_parameter_orderZ update_executemany_returningZ delete_executemany_returningr Z BindTypingZ SETINPUTSIZESZ bind_typingr r Z update_copyr r� r r� rP �Numericr1 ZFloat�oracle� BINARY_FLOATrI � BINARY_DOUBLErK �Integerr r rL �DaterM � LargeBinaryre �BooleanZ_OracleBooleanZIntervalrl rm �Textr_ �Stringra r� r^ �CHARrS rX rU rd rb �LONGr` �RAWrn r� rY ZNVARCHARrW �UuidrF r� r[ rp ro r� Zexecute_sequence_formatr� r� r� Zdeprecated_paramsr� r� � classmethodr� r� r� r� r� r� r� r; r< r� r r r r r& r+ r- r1 r4 r7 r8 r< r= rk r r ri r r� s� �� � � 5 / -YC# � � r� )K�__doc__� __future__r r; r) r� � r r? r r r �typesr r r Zenginer r� r r Zsqlr Z sql._typingr r rB r r> r1 rK rF rH r@ rI rA rK rL Z _OracleDaterM r� rP rR rH rS rX rU Z NVARCHAR2rW r� rY r� r[ r� r^ rF r_ rI r` rG ra rd rb rD re rm rl rJ rn rp ro rq r� r� r! r r r r �<module> sj e L G P sqlalchemy/dialects/oracle/__pycache__/provision.cpython-39.pyc 0000644 00000014765 15125143220 0020644 0 ustar 00 a ��Jhy � @ s� d dl mZ d dl mZ d dl mZ d dlmZ d dlmZ d dlm Z d dlm Z d dlm Z d d lm Z d d lm Z d d lmZ d d lmZ d d lmZ d dlmZ d dlmZ d dlmZ d dlmZ e �d�dd� �Ze�d�dd� �Zdd� Ze �d�dd� �Ze �d�dd � �Ze �d�d d � �Ze�d�d d � �Z d0d"d#�Z e � Z e�d�d$d%� �Z e�d�d&d'� �Z!e �d�d(d)� �Z"e�d�d*d+� �Z#e�d�d,d-� �Z$e�d�d.d/� �Z%d!S )1� )� create_engine)�exc)�inspect)�url)�configure_follower)� create_db)�#drop_all_schema_objects_post_tables)�"drop_all_schema_objects_pre_tables)�drop_db)�follower_url_from_main)�log)�post_configure_engine)� run_reap_dbs)� set_default_schema_on_connection)� stop_test_class_outside_fixtures)�temp_table_keyword_args)�update_db_opts�oraclec C s� |� � ��}|�d| � |�d| � |�d| � |�d|f � |�d| � |�d| � |�d| � |�d| � |�d | � |�d | � W d � n1 s�0 Y d S ) Nz create user %s identified by xez#create user %s_ts1 identified by xez#create user %s_ts2 identified by xezgrant dba to %sz grant unlimited tablespace to %sz$grant unlimited tablespace to %s_ts1z$grant unlimited tablespace to %s_ts2zgrant create table to %sz grant create table to %s_ts1z grant create table to %s_ts2)�begin�exec_driver_sql��cfg�eng�ident�conn� r �Y/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/oracle/provision.py�_oracle_create_db s r c C s d| | _ d| | _d S �N�%s_ts1�%s_ts2)� test_schemaZ test_schema_2)�configr r r r �_oracle_configure_follower/ s r# c C sZ z | � d| � t�d|� W dS tjyT } zt�d|� W Y d }~dS d }~0 0 d S )Nzdrop user %s cascadez Reaped db: %sTzcouldn't drop db: %sF)r r �infor � DatabaseError�warning)r Zdbname�errr r r �_ora_drop_ignore5 s r( c C s t |� t || j� d S �N)�_purge_recyclebinr! �r r r r r �'_ora_drop_all_schema_objects_pre_tables? s r, c C s� |� � ��}|j�|d d d �D ]}|�d|d � �� q |j�|| jd d �D ] }|�d| j� d|d � �� qJt|��� D ]}|�d|� �� qxW d � n1 s�0 Y d S )Nz drop synonym Z synonym_name�.z drop table )r �dialectZ _get_synonymsr r! r Zget_temp_table_names)r r r ZsynZ tmp_tabler r r �(_ora_drop_all_schema_objects_post_tablesE s ��r/ c C sR |� � �6}t||� t|d| � t|d| � W d � n1 sD0 Y d S r )r r( r r r r �_oracle_drop_dbV s r0 c C s� z t |� W n2 tjy> } zt�d|� W Y d }~n d }~0 0 tD ]4}z |j}W n |jjj yj Y qD0 d|_||_qDt� � d S )Nz#purge recyclebin command failed: %s� ) r* r r% r r& � _all_connsZ stmtcachesizer. ZdbapiZInterfaceError�clear)r" �db�clsr' Zcx_oracle_connZscr r r �%_ora_stop_test_class_outside_fixturesc s " r6 Nc C s� | � � �j}|d u r |�d� nF|�dd|j�|�i��� D ](\}}}|�d|� d|� d|� d�� q:W d � n1 sx0 Y d S )Nzpurge recyclebinzWselect owner, object_name,type from dba_recyclebin where owner=:schema and type='TABLE'�schemazpurge � z."�")r r r. Zdenormalize_name�all)r r7 r �ownerZ object_name�type_r r r r* y s �r* c C s8 ddl m} |�|d�dd� �}|�|d�dd� �}d S ) Nr1 )�event�checkoutc S s t �| � d S r) )r2 �add)Z dbapi_conZ con_recordZ con_proxyr r r r> � s z/_oracle_post_configure_engine.<locals>.checkout�checkinc S s d|j v r|�� d S )NZ cx_oracle_xid)r$ Z invalidate)�dbapi_connectionZconnection_recordr r r r@ � s z._oracle_post_configure_engine.<locals>.checkin)Z sqlalchemyr= Z listens_for)r �engineZfollower_identr= r> r@ r r r � _oracle_post_configure_engine� s rC c C s t �d| � t| �}|�� ��}t �dd�|�� |�d�}dd� |D �}t� }|D ]b}|�d�sR|�d�rnqRqR||v rR|�|� d | |v r�|�d | � d | |v rR|�d | � qRd }} t |d �D ]\} } t || �r�|d 7 }q�t �d || � W d � n1 �s0 Y d S )Nzdb reaper connecting to %rzidentifiers in file: %sz, z�select u.username from all_users u where username like 'TEST_%' and not exists (select username from v$session where username=u.username)c S s h | ]\}|� � �qS r )�lower)�.0�usernamer r r � <setcomp>� � z#_reap_oracle_dbs.<locals>.<setcomp>Z_ts1Z_ts2r r r1 � z-Dropped %d out of %d stale databases detected) r r$ r r �joinr �set�endswithr? � enumerater( ) r Zidentsr r Zto_reapZ all_namesZto_drop�nameZdropped�totalrF r r r �_reap_oracle_dbs� s2 � �rP c C s t �| �} | j|dd�S )NZxe)rF �password)�sa_url�make_urlrK )r r r r r � _oracle_follower_url_from_main� s rT c C s dgdd�S )NzGLOBAL TEMPORARYz PRESERVE ROWS)�prefixesZoracle_on_commitr r+ r r r � _oracle_temp_table_keyword_args� s �rV c C s" |� � }|�d| � |�� d S )Nz#ALTER SESSION SET CURRENT_SCHEMA=%s)�cursor�execute�close)r rA Z schema_namerW r r r �(_oracle_set_default_schema_on_connection� s rZ c C s$ |j r t�| ��� dkr d|d< dS )zCSet database options (db_opts) for a test database that we created.ZoracledbTZ thick_modeN)Zoracledb_thick_moderR rS Zget_driver_name)Zdb_urlZdb_opts�optionsr r r �_update_db_opts� s ��r\ )N)&� r r r rB r rR Ztesting.provisionr r r r r r r r r r r r r Zfor_dbr r# r( r, r/ r0 r6 r* rK r2 rC rP rT rV rZ r\ r r r r �<module> sV sqlalchemy/dialects/oracle/__pycache__/types.cpython-39.pyc 0000644 00000024746 15125143220 0017760 0 ustar 00 a ��Jhb# � @ s� d dl mZ d dlZd dlmZ d dlmZ d dlmZ ddlm Z ddl m Z dd l m Z dd l mZ er�dd lmZ dd lmZ G d d� de j�ZeZG dd� de j�ZG dd� de�Ze ZG dd� de je j�Z G dd� de j �Z G dd� de j �Z G dd� de j �Z!G dd � d e j"�Z#G d d � d e j�Z$G d d � d �Z%G d!d"� d"e%e j&�Z'G d#d$� d$e%e j(�Z)G d%d&� d&e j*e j+�Z,G d'd(� d(e j-�Z-G d)d*� d*e j.�Z/G d+d,� d,e j0�Z1dS )-� )� annotationsN)�Optional)�Type)� TYPE_CHECKING� )�exc)�sqltypes)�NVARCHAR)�VARCHAR)�Dialect)�_LiteralProcessorTypec @ s e Zd Zd ZdS )�RAWN��__name__� __module__� __qualname__�__visit_name__� r r �U/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/oracle/types.pyr s r c @ s e Zd Zd ZdS )�NCLOBNr r r r r r s r c @ s e Zd Zd ZdS )�VARCHAR2Nr r r r r r $ s r c s: e Zd Zd Zd� fdd� Z� fdd�Zedd� �Z� ZS ) �NUMBERNc s. |d u rt |o|dk�}t� j|||d� d S )Nr )� precision�scale� asdecimal)�bool�super�__init__)�selfr r r �� __class__r r r . s zNUMBER.__init__c s t � �|�}d|_|S )NT)r �adaptZ_is_oracle_number)r Zimpltype�retr r r r! 4 s z NUMBER.adaptc C s$ t | jo| jdk�rtjS tjS d S )Nr )r r r �Numeric�Integer�r r r r �_type_affinity: s zNUMBER._type_affinity)NNN) r r r r r r! �propertyr& � __classcell__r r r r r + s r c s& e Zd ZdZd Zd� fdd� Z� ZS )�FLOATaf Oracle Database FLOAT. This is the same as :class:`_sqltypes.FLOAT` except that an Oracle Database -specific :paramref:`_oracle.FLOAT.binary_precision` parameter is accepted, and the :paramref:`_sqltypes.Float.precision` parameter is not accepted. Oracle Database FLOAT types indicate precision in terms of "binary precision", which defaults to 126. For a REAL type, the value is 63. This parameter does not cleanly map to a specific number of decimal places but is roughly equivalent to the desired number of decimal places divided by 0.3103. .. versionadded:: 2.0 NFc s t � j||d� || _dS )a" Construct a FLOAT :param binary_precision: Oracle Database binary precision value to be rendered in DDL. This may be approximated to the number of decimal characters using the formula "decimal precision = 0.30103 * binary precision". The default value used by Oracle Database for FLOAT / DOUBLE PRECISION is 126. :param asdecimal: See :paramref:`_sqltypes.Float.asdecimal` :param decimal_return_scale: See :paramref:`_sqltypes.Float.decimal_return_scale` )r �decimal_return_scaleN)r r �binary_precision)r r+ r r* r r r r V s �zFLOAT.__init__)NFN)r r r �__doc__r r r( r r r r r) B s �r) c @ s e Zd ZdZd ZdS )� BINARY_DOUBLEaQ Implement the Oracle ``BINARY_DOUBLE`` datatype. This datatype differs from the Oracle ``DOUBLE`` datatype in that it delivers a true 8-byte FP value. The datatype may be combined with a generic :class:`.Double` datatype using :meth:`.TypeEngine.with_variant`. .. seealso:: :ref:`oracle_float_support` N�r r r r, r r r r r r- q s r- c @ s e Zd ZdZd ZdS )� BINARY_FLOATaN Implement the Oracle ``BINARY_FLOAT`` datatype. This datatype differs from the Oracle ``FLOAT`` datatype in that it delivers a true 4-byte FP value. The datatype may be combined with a generic :class:`.Float` datatype using :meth:`.TypeEngine.with_variant`. .. seealso:: :ref:`oracle_float_support` Nr. r r r r r/ � s r/ c @ s e Zd Zd ZdS )�BFILENr r r r r r0 � s r0 c @ s e Zd Zd ZdS )�LONGNr r r r r r1 � s r1 c @ s e Zd Zdd� Zdd� ZdS )�_OracleDateLiteralRenderc C s dd� }|S )Nc S sB t | dd �r&d| �� �dd�� d�} nd| �� �dd�� d�} | S )N� microsecond�TO_TIMESTAMP('�T� z ', 'YYYY-MM-DD HH24:MI:SS.FF')� TO_DATE('z', 'YYYY-MM-DD HH24:MI:SS'))�getattr� isoformat�replace��valuer r r �process� s ����zE_OracleDateLiteralRender._literal_processor_datetime.<locals>.processr �r �dialectr= r r r �_literal_processor_datetime� s z4_OracleDateLiteralRender._literal_processor_datetimec C s dd� }|S )Nc S sF t | dd �r(d| �� �d�d � d�} nd| �� �d�d � d�} | S )Nr3 r4 r5 r z', 'YYYY-MM-DD')r7 )r8 r9 �splitr; r r r r= � s ����zA_OracleDateLiteralRender._literal_processor_date.<locals>.processr r> r r r �_literal_processor_date� s z0_OracleDateLiteralRender._literal_processor_dateN)r r r r@ rB r r r r r2 � s r2 c @ s$ e Zd ZdZd Zdd� Zdd� ZdS )�DATEz�Provide the Oracle Database DATE type. This type has no special Python behavior, except that it subclasses :class:`_types.DateTime`; this is to suit the fact that the Oracle Database ``DATE`` type supports a time value. c C s | � |�S �N)r@ �r r? r r r �literal_processor� s zDATE.literal_processorc C s |j tjtjfv S rD )r& r �DateTime�Date)r �otherr r r �_compare_type_affinity� s zDATE._compare_type_affinityN)r r r r, r rF rJ r r r r rC � s rC c @ s e Zd Zdd� ZdS )� _OracleDatec C s | � |�S rD )rB rE r r r rF � s z _OracleDate.literal_processorN)r r r rF r r r r rK � s rK c @ sp e Zd Zd Zddd�Zedd� �Zedd�dd ��Zed d � �Z dd d�Z edd�dd��Z ddd�dd�Z dS )�INTERVALNc C s || _ || _dS )a Construct an INTERVAL. Note that only DAY TO SECOND intervals are currently supported. This is due to a lack of support for YEAR TO MONTH intervals within available DBAPIs. :param day_precision: the day precision value. this is the number of digits to store for the day field. Defaults to "2" :param second_precision: the second precision value. this is the number of digits to store for the fractional seconds field. Defaults to "6". N�� day_precision�second_precision)r rN rO r r r r � s zINTERVAL.__init__c C s t |j|jd�S �NrM �rL rN rO )�cls�intervalr r r � _adapt_from_generic_interval� s �z%INTERVAL._adapt_from_generic_intervalzsqltypes.Interval)rS c K s t |j|jd�S rP rQ )rR rS �kwr r r �adapt_emulated_to_native� s �z!INTERVAL.adapt_emulated_to_nativec C s t jS rD )r �Intervalr% r r r r& � s zINTERVAL._type_affinityFc C s t jd| j| jd�S )NT)ZnativerO rN )r rW rO rN )r Zallow_nulltyper r r � as_generic s �zINTERVAL.as_genericzType[dt.timedelta])�returnc C s t jS rD )�dt� timedeltar% r r r � python_type s zINTERVAL.python_typer z-Optional[_LiteralProcessorType[dt.timedelta]])r? rY c C s ddd�dd�}|S )Nz dt.timedelta�str)r< rY c S s d| � � � d�S )NzNUMTODSINTERVAL(z , 'SECOND'))� total_secondsr; r r r r= s z+INTERVAL.literal_processor.<locals>.processr r> r r r rF s zINTERVAL.literal_processor)NN)F) r r r r r � classmethodrT rV r' r& rX r\ rF r r r r rL � s rL c s* e Zd ZdZdddd�� fdd� Z� ZS )� TIMESTAMPz�Oracle Database implementation of ``TIMESTAMP``, which supports additional Oracle Database-specific modes .. versionadded:: 2.0 Fr )�timezone�local_timezonec s* |r|rt �d��t� j|d� || _dS )aq Construct a new :class:`_oracle.TIMESTAMP`. :param timezone: boolean. Indicates that the TIMESTAMP type should use Oracle Database's ``TIMESTAMP WITH TIME ZONE`` datatype. :param local_timezone: boolean. Indicates that the TIMESTAMP type should use Oracle Database's ``TIMESTAMP WITH LOCAL TIME ZONE`` datatype. z2timezone and local_timezone are mutually exclusive)ra N)r � ArgumentErrorr r rb )r ra rb r r r r s �zTIMESTAMP.__init__)FF)r r r r, r r( r r r r r` s r` c @ s e Zd ZdZd ZdS )�ROWIDzYOracle Database ROWID type. When used in a cast() or similar, generates ROWID. Nr. r r r r rd 0 s rd c @ s e Zd Zdd� ZdS )�_OracleBooleanc C s |j S rD )r )r Zdbapir r r �get_dbapi_type; s z _OracleBoolean.get_dbapi_typeN)r r r rf r r r r re : s re )2� __future__r �datetimerZ �typingr r r � r Zsqlr �typesr r Zengine.interfacesr Z sql.type_apir Z_Binaryr Z OracleRaw�Textr r Z NVARCHAR2r# r$ r r) �Doubler- ZFloatr/ Z LargeBinaryr0 r1 r2 rG rC rH rK ZNativeForEmulatedZ_AbstractIntervalrL r` Z TypeEnginerd �Booleanre r r r r �<module> s: /&< sqlalchemy/dialects/oracle/base.py 0000755 00000413541 15125143220 0013235 0 ustar 00 # dialects/oracle/base.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors r""" .. dialect:: oracle :name: Oracle Database :normal_support: 11+ :best_effort: 9+ Auto Increment Behavior ----------------------- SQLAlchemy Table objects which include integer primary keys are usually assumed to have "autoincrementing" behavior, meaning they can generate their own primary key values upon INSERT. For use within Oracle Database, two options are available, which are the use of IDENTITY columns (Oracle Database 12 and above only) or the association of a SEQUENCE with the column. Specifying GENERATED AS IDENTITY (Oracle Database 12 and above) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Starting from version 12, Oracle Database can make use of identity columns using the :class:`_sql.Identity` to specify the autoincrementing behavior:: t = Table( "mytable", metadata, Column("id", Integer, Identity(start=3), primary_key=True), Column(...), ..., ) The CREATE TABLE for the above :class:`_schema.Table` object would be: .. sourcecode:: sql CREATE TABLE mytable ( id INTEGER GENERATED BY DEFAULT AS IDENTITY (START WITH 3), ..., PRIMARY KEY (id) ) The :class:`_schema.Identity` object support many options to control the "autoincrementing" behavior of the column, like the starting value, the incrementing value, etc. In addition to the standard options, Oracle Database supports setting :paramref:`_schema.Identity.always` to ``None`` to use the default generated mode, rendering GENERATED AS IDENTITY in the DDL. It also supports setting :paramref:`_schema.Identity.on_null` to ``True`` to specify ON NULL in conjunction with a 'BY DEFAULT' identity column. Using a SEQUENCE (all Oracle Database versions) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Older version of Oracle Database had no "autoincrement" feature: SQLAlchemy relies upon sequences to produce these values. With the older Oracle Database versions, *a sequence must always be explicitly specified to enable autoincrement*. This is divergent with the majority of documentation examples which assume the usage of an autoincrement-capable database. To specify sequences, use the sqlalchemy.schema.Sequence object which is passed to a Column construct:: t = Table( "mytable", metadata, Column("id", Integer, Sequence("id_seq", start=1), primary_key=True), Column(...), ..., ) This step is also required when using table reflection, i.e. autoload_with=engine:: t = Table( "mytable", metadata, Column("id", Integer, Sequence("id_seq", start=1), primary_key=True), autoload_with=engine, ) .. versionchanged:: 1.4 Added :class:`_schema.Identity` construct in a :class:`_schema.Column` to specify the option of an autoincrementing column. .. _oracle_isolation_level: Transaction Isolation Level / Autocommit ---------------------------------------- Oracle Database supports "READ COMMITTED" and "SERIALIZABLE" modes of isolation. The AUTOCOMMIT isolation level is also supported by the python-oracledb and cx_Oracle dialects. To set using per-connection execution options:: connection = engine.connect() connection = connection.execution_options(isolation_level="AUTOCOMMIT") For ``READ COMMITTED`` and ``SERIALIZABLE``, the Oracle Database dialects sets the level at the session level using ``ALTER SESSION``, which is reverted back to its default setting when the connection is returned to the connection pool. Valid values for ``isolation_level`` include: * ``READ COMMITTED`` * ``AUTOCOMMIT`` * ``SERIALIZABLE`` .. note:: The implementation for the :meth:`_engine.Connection.get_isolation_level` method as implemented by the Oracle Database dialects necessarily force the start of a transaction using the Oracle Database DBMS_TRANSACTION.LOCAL_TRANSACTION_ID function; otherwise no level is normally readable. Additionally, the :meth:`_engine.Connection.get_isolation_level` method will raise an exception if the ``v$transaction`` view is not available due to permissions or other reasons, which is a common occurrence in Oracle Database installations. The python-oracledb and cx_Oracle dialects attempt to call the :meth:`_engine.Connection.get_isolation_level` method when the dialect makes its first connection to the database in order to acquire the "default"isolation level. This default level is necessary so that the level can be reset on a connection after it has been temporarily modified using :meth:`_engine.Connection.execution_options` method. In the common event that the :meth:`_engine.Connection.get_isolation_level` method raises an exception due to ``v$transaction`` not being readable as well as any other database-related failure, the level is assumed to be "READ COMMITTED". No warning is emitted for this initial first-connect condition as it is expected to be a common restriction on Oracle databases. .. versionadded:: 1.3.16 added support for AUTOCOMMIT to the cx_Oracle dialect as well as the notion of a default isolation level .. versionadded:: 1.3.21 Added support for SERIALIZABLE as well as live reading of the isolation level. .. versionchanged:: 1.3.22 In the event that the default isolation level cannot be read due to permissions on the v$transaction view as is common in Oracle installations, the default isolation level is hardcoded to "READ COMMITTED" which was the behavior prior to 1.3.21. .. seealso:: :ref:`dbapi_autocommit` Identifier Casing ----------------- In Oracle Database, the data dictionary represents all case insensitive identifier names using UPPERCASE text. This is in contradiction to the expectations of SQLAlchemy, which assume a case insensitive name is represented as lowercase text. As an example of case insensitive identifier names, consider the following table: .. sourcecode:: sql CREATE TABLE MyTable (Identifier INTEGER PRIMARY KEY) If you were to ask Oracle Database for information about this table, the table name would be reported as ``MYTABLE`` and the column name would be reported as ``IDENTIFIER``. Compare to most other databases such as PostgreSQL and MySQL which would report these names as ``mytable`` and ``identifier``. The names are **not quoted, therefore are case insensitive**. The special casing of ``MyTable`` and ``Identifier`` would only be maintained if they were quoted in the table definition: .. sourcecode:: sql CREATE TABLE "MyTable" ("Identifier" INTEGER PRIMARY KEY) When constructing a SQLAlchemy :class:`.Table` object, **an all lowercase name is considered to be case insensitive**. So the following table assumes case insensitive names:: Table("mytable", metadata, Column("identifier", Integer, primary_key=True)) Whereas when mixed case or UPPERCASE names are used, case sensitivity is assumed:: Table("MyTable", metadata, Column("Identifier", Integer, primary_key=True)) A similar situation occurs at the database driver level when emitting a textual SQL SELECT statement and looking at column names in the DBAPI ``cursor.description`` attribute. A database like PostgreSQL will normalize case insensitive names to be lowercase:: >>> pg_engine = create_engine("postgresql://scott:tiger@localhost/test") >>> pg_connection = pg_engine.connect() >>> result = pg_connection.exec_driver_sql("SELECT 1 AS SomeName") >>> result.cursor.description (Column(name='somename', type_code=23),) Whereas Oracle normalizes them to UPPERCASE:: >>> oracle_engine = create_engine("oracle+oracledb://scott:tiger@oracle18c/xe") >>> oracle_connection = oracle_engine.connect() >>> result = oracle_connection.exec_driver_sql( ... "SELECT 1 AS SomeName FROM DUAL" ... ) >>> result.cursor.description [('SOMENAME', <DbType DB_TYPE_NUMBER>, 127, None, 0, -127, True)] In order to achieve cross-database parity for the two cases of a. table reflection and b. textual-only SQL statement round trips, SQLAlchemy performs a step called **name normalization** when using the Oracle dialect. This process may also apply to other third party dialects that have similar UPPERCASE handling of case insensitive names. When using name normalization, SQLAlchemy attempts to detect if a name is case insensitive by checking if all characters are UPPERCASE letters only; if so, then it assumes this is a case insensitive name and is delivered as a lowercase name. For table reflection, a tablename that is seen represented as all UPPERCASE in Oracle Database's catalog tables will be assumed to have a case insensitive name. This is what allows the ``Table`` definition to use lower case names and be equally compatible from a reflection point of view on Oracle Database and all other databases such as PostgreSQL and MySQL:: # matches a table created with CREATE TABLE mytable Table("mytable", metadata, autoload_with=some_engine) Above, the all lowercase name ``"mytable"`` is case insensitive; it will match a table reported by PostgreSQL as ``"mytable"`` and a table reported by Oracle as ``"MYTABLE"``. If name normalization were not present, it would not be possible for the above :class:`.Table` definition to be introspectable in a cross-database way, since we are dealing with a case insensitive name that is not reported by each database in the same way. Case sensitivity can be forced on in this case, such as if we wanted to represent the quoted tablename ``"MYTABLE"`` with that exact casing, most simply by using that casing directly, which will be seen as a case sensitive name:: # matches a table created with CREATE TABLE "MYTABLE" Table("MYTABLE", metadata, autoload_with=some_engine) For the unusual case of a quoted all-lowercase name, the :class:`.quoted_name` construct may be used:: from sqlalchemy import quoted_name # matches a table created with CREATE TABLE "mytable" Table( quoted_name("mytable", quote=True), metadata, autoload_with=some_engine ) Name normalization also takes place when handling result sets from **purely textual SQL strings**, that have no other :class:`.Table` or :class:`.Column` metadata associated with them. This includes SQL strings executed using :meth:`.Connection.exec_driver_sql` and SQL strings executed using the :func:`.text` construct which do not include :class:`.Column` metadata. Returning to the Oracle Database SELECT statement, we see that even though ``cursor.description`` reports the column name as ``SOMENAME``, SQLAlchemy name normalizes this to ``somename``:: >>> oracle_engine = create_engine("oracle+oracledb://scott:tiger@oracle18c/xe") >>> oracle_connection = oracle_engine.connect() >>> result = oracle_connection.exec_driver_sql( ... "SELECT 1 AS SomeName FROM DUAL" ... ) >>> result.cursor.description [('SOMENAME', <DbType DB_TYPE_NUMBER>, 127, None, 0, -127, True)] >>> result.keys() RMKeyView(['somename']) The single scenario where the above behavior produces inaccurate results is when using an all-uppercase, quoted name. SQLAlchemy has no way to determine that a particular name in ``cursor.description`` was quoted, and is therefore case sensitive, or was not quoted, and should be name normalized:: >>> result = oracle_connection.exec_driver_sql( ... 'SELECT 1 AS "SOMENAME" FROM DUAL' ... ) >>> result.cursor.description [('SOMENAME', <DbType DB_TYPE_NUMBER>, 127, None, 0, -127, True)] >>> result.keys() RMKeyView(['somename']) For this case, a new feature will be available in SQLAlchemy 2.1 to disable the name normalization behavior in specific cases. .. _oracle_max_identifier_lengths: Maximum Identifier Lengths -------------------------- SQLAlchemy is sensitive to the maximum identifier length supported by Oracle Database. This affects generated SQL label names as well as the generation of constraint names, particularly in the case where the constraint naming convention feature described at :ref:`constraint_naming_conventions` is being used. Oracle Database 12.2 increased the default maximum identifier length from 30 to 128. As of SQLAlchemy 1.4, the default maximum identifier length for the Oracle dialects is 128 characters. Upon first connection, the maximum length actually supported by the database is obtained. In all cases, setting the :paramref:`_sa.create_engine.max_identifier_length` parameter will bypass this change and the value given will be used as is:: engine = create_engine( "oracle+oracledb://scott:tiger@localhost:1521?service_name=freepdb1", max_identifier_length=30, ) If :paramref:`_sa.create_engine.max_identifier_length` is not set, the oracledb dialect internally uses the ``max_identifier_length`` attribute available on driver connections since python-oracledb version 2.5. When using an older driver version, or using the cx_Oracle dialect, SQLAlchemy will instead attempt to use the query ``SELECT value FROM v$parameter WHERE name = 'compatible'`` upon first connect in order to determine the effective compatibility version of the database. The "compatibility" version is a version number that is independent of the actual database version. It is used to assist database migration. It is configured by an Oracle Database initialization parameter. The compatibility version then determines the maximum allowed identifier length for the database. If the V$ view is not available, the database version information is used instead. The maximum identifier length comes into play both when generating anonymized SQL labels in SELECT statements, but more crucially when generating constraint names from a naming convention. It is this area that has created the need for SQLAlchemy to change this default conservatively. For example, the following naming convention produces two very different constraint names based on the identifier length:: from sqlalchemy import Column from sqlalchemy import Index from sqlalchemy import Integer from sqlalchemy import MetaData from sqlalchemy import Table from sqlalchemy.dialects import oracle from sqlalchemy.schema import CreateIndex m = MetaData(naming_convention={"ix": "ix_%(column_0N_name)s"}) t = Table( "t", m, Column("some_column_name_1", Integer), Column("some_column_name_2", Integer), Column("some_column_name_3", Integer), ) ix = Index( None, t.c.some_column_name_1, t.c.some_column_name_2, t.c.some_column_name_3, ) oracle_dialect = oracle.dialect(max_identifier_length=30) print(CreateIndex(ix).compile(dialect=oracle_dialect)) With an identifier length of 30, the above CREATE INDEX looks like: .. sourcecode:: sql CREATE INDEX ix_some_column_name_1s_70cd ON t (some_column_name_1, some_column_name_2, some_column_name_3) However with length of 128, it becomes:: .. sourcecode:: sql CREATE INDEX ix_some_column_name_1some_column_name_2some_column_name_3 ON t (some_column_name_1, some_column_name_2, some_column_name_3) Applications which have run versions of SQLAlchemy prior to 1.4 on Oracle Database version 12.2 or greater are therefore subject to the scenario of a database migration that wishes to "DROP CONSTRAINT" on a name that was previously generated with the shorter length. This migration will fail when the identifier length is changed without the name of the index or constraint first being adjusted. Such applications are strongly advised to make use of :paramref:`_sa.create_engine.max_identifier_length` in order to maintain control of the generation of truncated names, and to fully review and test all database migrations in a staging environment when changing this value to ensure that the impact of this change has been mitigated. .. versionchanged:: 1.4 the default max_identifier_length for Oracle Database is 128 characters, which is adjusted down to 30 upon first connect if the Oracle Database, or its compatibility setting, are lower than version 12.2. LIMIT/OFFSET/FETCH Support -------------------------- Methods like :meth:`_sql.Select.limit` and :meth:`_sql.Select.offset` make use of ``FETCH FIRST N ROW / OFFSET N ROWS`` syntax assuming Oracle Database 12c or above, and assuming the SELECT statement is not embedded within a compound statement like UNION. This syntax is also available directly by using the :meth:`_sql.Select.fetch` method. .. versionchanged:: 2.0 the Oracle Database dialects now use ``FETCH FIRST N ROW / OFFSET N ROWS`` for all :meth:`_sql.Select.limit` and :meth:`_sql.Select.offset` usage including within the ORM and legacy :class:`_orm.Query`. To force the legacy behavior using window functions, specify the ``enable_offset_fetch=False`` dialect parameter to :func:`_sa.create_engine`. The use of ``FETCH FIRST / OFFSET`` may be disabled on any Oracle Database version by passing ``enable_offset_fetch=False`` to :func:`_sa.create_engine`, which will force the use of "legacy" mode that makes use of window functions. This mode is also selected automatically when using a version of Oracle Database prior to 12c. When using legacy mode, or when a :class:`.Select` statement with limit/offset is embedded in a compound statement, an emulated approach for LIMIT / OFFSET based on window functions is used, which involves creation of a subquery using ``ROW_NUMBER`` that is prone to performance issues as well as SQL construction issues for complex statements. However, this approach is supported by all Oracle Database versions. See notes below. Notes on LIMIT / OFFSET emulation (when fetch() method cannot be used) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If using :meth:`_sql.Select.limit` and :meth:`_sql.Select.offset`, or with the ORM the :meth:`_orm.Query.limit` and :meth:`_orm.Query.offset` methods on an Oracle Database version prior to 12c, the following notes apply: * SQLAlchemy currently makes use of ROWNUM to achieve LIMIT/OFFSET; the exact methodology is taken from https://blogs.oracle.com/oraclemagazine/on-rownum-and-limiting-results . * the "FIRST_ROWS()" optimization keyword is not used by default. To enable the usage of this optimization directive, specify ``optimize_limits=True`` to :func:`_sa.create_engine`. .. versionchanged:: 1.4 The Oracle Database dialect renders limit/offset integer values using a "post compile" scheme which renders the integer directly before passing the statement to the cursor for execution. The ``use_binds_for_limits`` flag no longer has an effect. .. seealso:: :ref:`change_4808`. .. _oracle_returning: RETURNING Support ----------------- Oracle Database supports RETURNING fully for INSERT, UPDATE and DELETE statements that are invoked with a single collection of bound parameters (that is, a ``cursor.execute()`` style statement; SQLAlchemy does not generally support RETURNING with :term:`executemany` statements). Multiple rows may be returned as well. .. versionchanged:: 2.0 the Oracle Database backend has full support for RETURNING on parity with other backends. ON UPDATE CASCADE ----------------- Oracle Database doesn't have native ON UPDATE CASCADE functionality. A trigger based solution is available at https://web.archive.org/web/20090317041251/https://asktom.oracle.com/tkyte/update_cascade/index.html When using the SQLAlchemy ORM, the ORM has limited ability to manually issue cascading updates - specify ForeignKey objects using the "deferrable=True, initially='deferred'" keyword arguments, and specify "passive_updates=False" on each relationship(). Oracle Database 8 Compatibility ------------------------------- .. warning:: The status of Oracle Database 8 compatibility is not known for SQLAlchemy 2.0. When Oracle Database 8 is detected, the dialect internally configures itself to the following behaviors: * the use_ansi flag is set to False. This has the effect of converting all JOIN phrases into the WHERE clause, and in the case of LEFT OUTER JOIN makes use of Oracle's (+) operator. * the NVARCHAR2 and NCLOB datatypes are no longer generated as DDL when the :class:`~sqlalchemy.types.Unicode` is used - VARCHAR2 and CLOB are issued instead. This because these types don't seem to work correctly on Oracle 8 even though they are available. The :class:`~sqlalchemy.types.NVARCHAR` and :class:`~sqlalchemy.dialects.oracle.NCLOB` types will always generate NVARCHAR2 and NCLOB. Synonym/DBLINK Reflection ------------------------- When using reflection with Table objects, the dialect can optionally search for tables indicated by synonyms, either in local or remote schemas or accessed over DBLINK, by passing the flag ``oracle_resolve_synonyms=True`` as a keyword argument to the :class:`_schema.Table` construct:: some_table = Table( "some_table", autoload_with=some_engine, oracle_resolve_synonyms=True ) When this flag is set, the given name (such as ``some_table`` above) will be searched not just in the ``ALL_TABLES`` view, but also within the ``ALL_SYNONYMS`` view to see if this name is actually a synonym to another name. If the synonym is located and refers to a DBLINK, the Oracle Database dialects know how to locate the table's information using DBLINK syntax(e.g. ``@dblink``). ``oracle_resolve_synonyms`` is accepted wherever reflection arguments are accepted, including methods such as :meth:`_schema.MetaData.reflect` and :meth:`_reflection.Inspector.get_columns`. If synonyms are not in use, this flag should be left disabled. .. _oracle_constraint_reflection: Constraint Reflection --------------------- The Oracle Database dialects can return information about foreign key, unique, and CHECK constraints, as well as indexes on tables. Raw information regarding these constraints can be acquired using :meth:`_reflection.Inspector.get_foreign_keys`, :meth:`_reflection.Inspector.get_unique_constraints`, :meth:`_reflection.Inspector.get_check_constraints`, and :meth:`_reflection.Inspector.get_indexes`. .. versionchanged:: 1.2 The Oracle Database dialect can now reflect UNIQUE and CHECK constraints. When using reflection at the :class:`_schema.Table` level, the :class:`_schema.Table` will also include these constraints. Note the following caveats: * When using the :meth:`_reflection.Inspector.get_check_constraints` method, Oracle Database builds a special "IS NOT NULL" constraint for columns that specify "NOT NULL". This constraint is **not** returned by default; to include the "IS NOT NULL" constraints, pass the flag ``include_all=True``:: from sqlalchemy import create_engine, inspect engine = create_engine( "oracle+oracledb://scott:tiger@localhost:1521?service_name=freepdb1" ) inspector = inspect(engine) all_check_constraints = inspector.get_check_constraints( "some_table", include_all=True ) * in most cases, when reflecting a :class:`_schema.Table`, a UNIQUE constraint will **not** be available as a :class:`.UniqueConstraint` object, as Oracle Database mirrors unique constraints with a UNIQUE index in most cases (the exception seems to be when two or more unique constraints represent the same columns); the :class:`_schema.Table` will instead represent these using :class:`.Index` with the ``unique=True`` flag set. * Oracle Database creates an implicit index for the primary key of a table; this index is **excluded** from all index results. * the list of columns reflected for an index will not include column names that start with SYS_NC. Table names with SYSTEM/SYSAUX tablespaces ------------------------------------------- The :meth:`_reflection.Inspector.get_table_names` and :meth:`_reflection.Inspector.get_temp_table_names` methods each return a list of table names for the current engine. These methods are also part of the reflection which occurs within an operation such as :meth:`_schema.MetaData.reflect`. By default, these operations exclude the ``SYSTEM`` and ``SYSAUX`` tablespaces from the operation. In order to change this, the default list of tablespaces excluded can be changed at the engine level using the ``exclude_tablespaces`` parameter:: # exclude SYSAUX and SOME_TABLESPACE, but not SYSTEM e = create_engine( "oracle+oracledb://scott:tiger@localhost:1521/?service_name=freepdb1", exclude_tablespaces=["SYSAUX", "SOME_TABLESPACE"], ) .. _oracle_float_support: FLOAT / DOUBLE Support and Behaviors ------------------------------------ The SQLAlchemy :class:`.Float` and :class:`.Double` datatypes are generic datatypes that resolve to the "least surprising" datatype for a given backend. For Oracle Database, this means they resolve to the ``FLOAT`` and ``DOUBLE`` types:: >>> from sqlalchemy import cast, literal, Float >>> from sqlalchemy.dialects import oracle >>> float_datatype = Float() >>> print(cast(literal(5.0), float_datatype).compile(dialect=oracle.dialect())) CAST(:param_1 AS FLOAT) Oracle's ``FLOAT`` / ``DOUBLE`` datatypes are aliases for ``NUMBER``. Oracle Database stores ``NUMBER`` values with full precision, not floating point precision, which means that ``FLOAT`` / ``DOUBLE`` do not actually behave like native FP values. Oracle Database instead offers special datatypes ``BINARY_FLOAT`` and ``BINARY_DOUBLE`` to deliver real 4- and 8- byte FP values. SQLAlchemy supports these datatypes directly using :class:`.BINARY_FLOAT` and :class:`.BINARY_DOUBLE`. To use the :class:`.Float` or :class:`.Double` datatypes in a database agnostic way, while allowing Oracle backends to utilize one of these types, use the :meth:`.TypeEngine.with_variant` method to set up a variant:: >>> from sqlalchemy import cast, literal, Float >>> from sqlalchemy.dialects import oracle >>> float_datatype = Float().with_variant(oracle.BINARY_FLOAT(), "oracle") >>> print(cast(literal(5.0), float_datatype).compile(dialect=oracle.dialect())) CAST(:param_1 AS BINARY_FLOAT) E.g. to use this datatype in a :class:`.Table` definition:: my_table = Table( "my_table", metadata, Column( "fp_data", Float().with_variant(oracle.BINARY_FLOAT(), "oracle") ), ) DateTime Compatibility ---------------------- Oracle Database has no datatype known as ``DATETIME``, it instead has only ``DATE``, which can actually store a date and time value. For this reason, the Oracle Database dialects provide a type :class:`_oracle.DATE` which is a subclass of :class:`.DateTime`. This type has no special behavior, and is only present as a "marker" for this type; additionally, when a database column is reflected and the type is reported as ``DATE``, the time-supporting :class:`_oracle.DATE` type is used. .. _oracle_table_options: Oracle Database Table Options ----------------------------- The CREATE TABLE phrase supports the following options with Oracle Database dialects in conjunction with the :class:`_schema.Table` construct: * ``ON COMMIT``:: Table( "some_table", metadata, ..., prefixes=["GLOBAL TEMPORARY"], oracle_on_commit="PRESERVE ROWS", ) * ``COMPRESS``:: Table( "mytable", metadata, Column("data", String(32)), oracle_compress=True ) Table("mytable", metadata, Column("data", String(32)), oracle_compress=6) The ``oracle_compress`` parameter accepts either an integer compression level, or ``True`` to use the default compression level. * ``TABLESPACE``:: Table("mytable", metadata, ..., oracle_tablespace="EXAMPLE_TABLESPACE") The ``oracle_tablespace`` parameter specifies the tablespace in which the table is to be created. This is useful when you want to create a table in a tablespace other than the default tablespace of the user. .. versionadded:: 2.0.37 .. _oracle_index_options: Oracle Database Specific Index Options -------------------------------------- Bitmap Indexes ~~~~~~~~~~~~~~ You can specify the ``oracle_bitmap`` parameter to create a bitmap index instead of a B-tree index:: Index("my_index", my_table.c.data, oracle_bitmap=True) Bitmap indexes cannot be unique and cannot be compressed. SQLAlchemy will not check for such limitations, only the database will. Index compression ~~~~~~~~~~~~~~~~~ Oracle Database has a more efficient storage mode for indexes containing lots of repeated values. Use the ``oracle_compress`` parameter to turn on key compression:: Index("my_index", my_table.c.data, oracle_compress=True) Index( "my_index", my_table.c.data1, my_table.c.data2, unique=True, oracle_compress=1, ) The ``oracle_compress`` parameter accepts either an integer specifying the number of prefix columns to compress, or ``True`` to use the default (all columns for non-unique indexes, all but the last column for unique indexes). .. _oracle_vector_datatype: VECTOR Datatype --------------- Oracle Database 23ai introduced a new VECTOR datatype for artificial intelligence and machine learning search operations. The VECTOR datatype is a homogeneous array of 8-bit signed integers, 8-bit unsigned integers (binary), 32-bit floating-point numbers, or 64-bit floating-point numbers. .. seealso:: `Using VECTOR Data <https://python-oracledb.readthedocs.io/en/latest/user_guide/vector_data_type.html>`_ - in the documentation for the :ref:`oracledb` driver. .. versionadded:: 2.0.41 CREATE TABLE support for VECTOR ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ With the :class:`.VECTOR` datatype, you can specify the dimension for the data and the storage format. Valid values for storage format are enum values from :class:`.VectorStorageFormat`. To create a table that includes a :class:`.VECTOR` column:: from sqlalchemy.dialects.oracle import VECTOR, VectorStorageFormat t = Table( "t1", metadata, Column("id", Integer, primary_key=True), Column( "embedding", VECTOR(dim=3, storage_format=VectorStorageFormat.FLOAT32), ), Column(...), ..., ) Vectors can also be defined with an arbitrary number of dimensions and formats. This allows you to specify vectors of different dimensions with the various storage formats mentioned above. **Examples** * In this case, the storage format is flexible, allowing any vector type data to be inserted, such as INT8 or BINARY etc:: vector_col: Mapped[array.array] = mapped_column(VECTOR(dim=3)) * The dimension is flexible in this case, meaning that any dimension vector can be used:: vector_col: Mapped[array.array] = mapped_column( VECTOR(storage_format=VectorStorageType.INT8) ) * Both the dimensions and the storage format are flexible:: vector_col: Mapped[array.array] = mapped_column(VECTOR) Python Datatypes for VECTOR ~~~~~~~~~~~~~~~~~~~~~~~~~~~ VECTOR data can be inserted using Python list or Python ``array.array()`` objects. Python arrays of type FLOAT (32-bit), DOUBLE (64-bit), or INT (8-bit signed integer) are used as bind values when inserting VECTOR columns:: from sqlalchemy import insert, select with engine.begin() as conn: conn.execute( insert(t1), {"id": 1, "embedding": [1, 2, 3]}, ) VECTOR Indexes ~~~~~~~~~~~~~~ The VECTOR feature supports an Oracle-specific parameter ``oracle_vector`` on the :class:`.Index` construct, which allows the construction of VECTOR indexes. To utilize VECTOR indexing, set the ``oracle_vector`` parameter to True to use the default values provided by Oracle. HNSW is the default indexing method:: from sqlalchemy import Index Index( "vector_index", t1.c.embedding, oracle_vector=True, ) The full range of parameters for vector indexes are available by using the :class:`.VectorIndexConfig` dataclass in place of a boolean; this dataclass allows full configuration of the index:: Index( "hnsw_vector_index", t1.c.embedding, oracle_vector=VectorIndexConfig( index_type=VectorIndexType.HNSW, distance=VectorDistanceType.COSINE, accuracy=90, hnsw_neighbors=5, hnsw_efconstruction=20, parallel=10, ), ) Index( "ivf_vector_index", t1.c.embedding, oracle_vector=VectorIndexConfig( index_type=VectorIndexType.IVF, distance=VectorDistanceType.DOT, accuracy=90, ivf_neighbor_partitions=5, ), ) For complete explanation of these parameters, see the Oracle documentation linked below. .. seealso:: `CREATE VECTOR INDEX <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-B396C369-54BB-4098-A0DD-7C54B3A0D66F>`_ - in the Oracle documentation Similarity Searching ~~~~~~~~~~~~~~~~~~~~ When using the :class:`_oracle.VECTOR` datatype with a :class:`.Column` or similar ORM mapped construct, additional comparison functions are available, including: * ``l2_distance`` * ``cosine_distance`` * ``inner_product`` Example Usage:: result_vector = connection.scalars( select(t1).order_by(t1.embedding.l2_distance([2, 3, 4])).limit(3) ) for user in vector: print(user.id, user.embedding) FETCH APPROXIMATE support ~~~~~~~~~~~~~~~~~~~~~~~~~ Approximate vector search can only be performed when all syntax and semantic rules are satisfied, the corresponding vector index is available, and the query optimizer determines to perform it. If any of these conditions are unmet, then an approximate search is not performed. In this case the query returns exact results. To enable approximate searching during similarity searches on VECTORS, the ``oracle_fetch_approximate`` parameter may be used with the :meth:`.Select.fetch` clause to add ``FETCH APPROX`` to the SELECT statement:: select(users_table).fetch(5, oracle_fetch_approximate=True) """ # noqa from __future__ import annotations from collections import defaultdict from dataclasses import fields from functools import lru_cache from functools import wraps import re from . import dictionary from .types import _OracleBoolean from .types import _OracleDate from .types import BFILE from .types import BINARY_DOUBLE from .types import BINARY_FLOAT from .types import DATE from .types import FLOAT from .types import INTERVAL from .types import LONG from .types import NCLOB from .types import NUMBER from .types import NVARCHAR2 # noqa from .types import OracleRaw # noqa from .types import RAW from .types import ROWID # noqa from .types import TIMESTAMP from .types import VARCHAR2 # noqa from .vector import VECTOR from .vector import VectorIndexConfig from .vector import VectorIndexType from ... import Computed from ... import exc from ... import schema as sa_schema from ... import sql from ... import util from ...engine import default from ...engine import ObjectKind from ...engine import ObjectScope from ...engine import reflection from ...engine.reflection import ReflectionDefaults from ...sql import and_ from ...sql import bindparam from ...sql import compiler from ...sql import expression from ...sql import func from ...sql import null from ...sql import or_ from ...sql import select from ...sql import selectable as sa_selectable from ...sql import sqltypes from ...sql import util as sql_util from ...sql import visitors from ...sql.visitors import InternalTraversal from ...types import BLOB from ...types import CHAR from ...types import CLOB from ...types import DOUBLE_PRECISION from ...types import INTEGER from ...types import NCHAR from ...types import NVARCHAR from ...types import REAL from ...types import VARCHAR RESERVED_WORDS = set( "SHARE RAW DROP BETWEEN FROM DESC OPTION PRIOR LONG THEN " "DEFAULT ALTER IS INTO MINUS INTEGER NUMBER GRANT IDENTIFIED " "ALL TO ORDER ON FLOAT DATE HAVING CLUSTER NOWAIT RESOURCE " "ANY TABLE INDEX FOR UPDATE WHERE CHECK SMALLINT WITH DELETE " "BY ASC REVOKE LIKE SIZE RENAME NOCOMPRESS NULL GROUP VALUES " "AS IN VIEW EXCLUSIVE COMPRESS SYNONYM SELECT INSERT EXISTS " "NOT TRIGGER ELSE CREATE INTERSECT PCTFREE DISTINCT USER " "CONNECT SET MODE OF UNIQUE VARCHAR2 VARCHAR LOCK OR CHAR " "DECIMAL UNION PUBLIC AND START UID COMMENT CURRENT LEVEL".split() ) NO_ARG_FNS = set( "UID CURRENT_DATE SYSDATE USER CURRENT_TIME CURRENT_TIMESTAMP".split() ) colspecs = { sqltypes.Boolean: _OracleBoolean, sqltypes.Interval: INTERVAL, sqltypes.DateTime: DATE, sqltypes.Date: _OracleDate, } ischema_names = { "VARCHAR2": VARCHAR, "NVARCHAR2": NVARCHAR, "CHAR": CHAR, "NCHAR": NCHAR, "DATE": DATE, "NUMBER": NUMBER, "BLOB": BLOB, "BFILE": BFILE, "CLOB": CLOB, "NCLOB": NCLOB, "TIMESTAMP": TIMESTAMP, "TIMESTAMP WITH TIME ZONE": TIMESTAMP, "TIMESTAMP WITH LOCAL TIME ZONE": TIMESTAMP, "INTERVAL DAY TO SECOND": INTERVAL, "RAW": RAW, "FLOAT": FLOAT, "DOUBLE PRECISION": DOUBLE_PRECISION, "REAL": REAL, "LONG": LONG, "BINARY_DOUBLE": BINARY_DOUBLE, "BINARY_FLOAT": BINARY_FLOAT, "ROWID": ROWID, "VECTOR": VECTOR, } class OracleTypeCompiler(compiler.GenericTypeCompiler): # Note: # Oracle DATE == DATETIME # Oracle does not allow milliseconds in DATE # Oracle does not support TIME columns def visit_datetime(self, type_, **kw): return self.visit_DATE(type_, **kw) def visit_float(self, type_, **kw): return self.visit_FLOAT(type_, **kw) def visit_double(self, type_, **kw): return self.visit_DOUBLE_PRECISION(type_, **kw) def visit_unicode(self, type_, **kw): if self.dialect._use_nchar_for_unicode: return self.visit_NVARCHAR2(type_, **kw) else: return self.visit_VARCHAR2(type_, **kw) def visit_INTERVAL(self, type_, **kw): return "INTERVAL DAY%s TO SECOND%s" % ( type_.day_precision is not None and "(%d)" % type_.day_precision or "", type_.second_precision is not None and "(%d)" % type_.second_precision or "", ) def visit_LONG(self, type_, **kw): return "LONG" def visit_TIMESTAMP(self, type_, **kw): if getattr(type_, "local_timezone", False): return "TIMESTAMP WITH LOCAL TIME ZONE" elif type_.timezone: return "TIMESTAMP WITH TIME ZONE" else: return "TIMESTAMP" def visit_DOUBLE_PRECISION(self, type_, **kw): return self._generate_numeric(type_, "DOUBLE PRECISION", **kw) def visit_BINARY_DOUBLE(self, type_, **kw): return self._generate_numeric(type_, "BINARY_DOUBLE", **kw) def visit_BINARY_FLOAT(self, type_, **kw): return self._generate_numeric(type_, "BINARY_FLOAT", **kw) def visit_FLOAT(self, type_, **kw): kw["_requires_binary_precision"] = True return self._generate_numeric(type_, "FLOAT", **kw) def visit_NUMBER(self, type_, **kw): return self._generate_numeric(type_, "NUMBER", **kw) def _generate_numeric( self, type_, name, precision=None, scale=None, _requires_binary_precision=False, **kw, ): if precision is None: precision = getattr(type_, "precision", None) if _requires_binary_precision: binary_precision = getattr(type_, "binary_precision", None) if precision and binary_precision is None: # https://www.oracletutorial.com/oracle-basics/oracle-float/ estimated_binary_precision = int(precision / 0.30103) raise exc.ArgumentError( "Oracle Database FLOAT types use 'binary precision', " "which does not convert cleanly from decimal " "'precision'. Please specify " "this type with a separate Oracle Database variant, such " f"as {type_.__class__.__name__}(precision={precision})." f"with_variant(oracle.FLOAT" f"(binary_precision=" f"{estimated_binary_precision}), 'oracle'), so that the " "Oracle Database specific 'binary_precision' may be " "specified accurately." ) else: precision = binary_precision if scale is None: scale = getattr(type_, "scale", None) if precision is None: return name elif scale is None: n = "%(name)s(%(precision)s)" return n % {"name": name, "precision": precision} else: n = "%(name)s(%(precision)s, %(scale)s)" return n % {"name": name, "precision": precision, "scale": scale} def visit_string(self, type_, **kw): return self.visit_VARCHAR2(type_, **kw) def visit_VARCHAR2(self, type_, **kw): return self._visit_varchar(type_, "", "2") def visit_NVARCHAR2(self, type_, **kw): return self._visit_varchar(type_, "N", "2") visit_NVARCHAR = visit_NVARCHAR2 def visit_VARCHAR(self, type_, **kw): return self._visit_varchar(type_, "", "") def _visit_varchar(self, type_, n, num): if not type_.length: return "%(n)sVARCHAR%(two)s" % {"two": num, "n": n} elif not n and self.dialect._supports_char_length: varchar = "VARCHAR%(two)s(%(length)s CHAR)" return varchar % {"length": type_.length, "two": num} else: varchar = "%(n)sVARCHAR%(two)s(%(length)s)" return varchar % {"length": type_.length, "two": num, "n": n} def visit_text(self, type_, **kw): return self.visit_CLOB(type_, **kw) def visit_unicode_text(self, type_, **kw): if self.dialect._use_nchar_for_unicode: return self.visit_NCLOB(type_, **kw) else: return self.visit_CLOB(type_, **kw) def visit_large_binary(self, type_, **kw): return self.visit_BLOB(type_, **kw) def visit_big_integer(self, type_, **kw): return self.visit_NUMBER(type_, precision=19, **kw) def visit_boolean(self, type_, **kw): return self.visit_SMALLINT(type_, **kw) def visit_RAW(self, type_, **kw): if type_.length: return "RAW(%(length)s)" % {"length": type_.length} else: return "RAW" def visit_ROWID(self, type_, **kw): return "ROWID" def visit_VECTOR(self, type_, **kw): if type_.dim is None and type_.storage_format is None: return "VECTOR(*,*)" elif type_.storage_format is None: return f"VECTOR({type_.dim},*)" elif type_.dim is None: return f"VECTOR(*,{type_.storage_format.value})" else: return f"VECTOR({type_.dim},{type_.storage_format.value})" class OracleCompiler(compiler.SQLCompiler): """Oracle compiler modifies the lexical structure of Select statements to work under non-ANSI configured Oracle databases, if the use_ansi flag is False. """ compound_keywords = util.update_copy( compiler.SQLCompiler.compound_keywords, {expression.CompoundSelect.EXCEPT: "MINUS"}, ) def __init__(self, *args, **kwargs): self.__wheres = {} super().__init__(*args, **kwargs) def visit_mod_binary(self, binary, operator, **kw): return "mod(%s, %s)" % ( self.process(binary.left, **kw), self.process(binary.right, **kw), ) def visit_now_func(self, fn, **kw): return "CURRENT_TIMESTAMP" def visit_char_length_func(self, fn, **kw): return "LENGTH" + self.function_argspec(fn, **kw) def visit_match_op_binary(self, binary, operator, **kw): return "CONTAINS (%s, %s)" % ( self.process(binary.left), self.process(binary.right), ) def visit_true(self, expr, **kw): return "1" def visit_false(self, expr, **kw): return "0" def get_cte_preamble(self, recursive): return "WITH" def get_select_hint_text(self, byfroms): return " ".join("/*+ %s */" % text for table, text in byfroms.items()) def function_argspec(self, fn, **kw): if len(fn.clauses) > 0 or fn.name.upper() not in NO_ARG_FNS: return compiler.SQLCompiler.function_argspec(self, fn, **kw) else: return "" def visit_function(self, func, **kw): text = super().visit_function(func, **kw) if kw.get("asfrom", False) and func.name.lower() != "table": text = "TABLE (%s)" % text return text def visit_table_valued_column(self, element, **kw): text = super().visit_table_valued_column(element, **kw) text = text + ".COLUMN_VALUE" return text def default_from(self): """Called when a ``SELECT`` statement has no froms, and no ``FROM`` clause is to be appended. The Oracle compiler tacks a "FROM DUAL" to the statement. """ return " FROM DUAL" def visit_join(self, join, from_linter=None, **kwargs): if self.dialect.use_ansi: return compiler.SQLCompiler.visit_join( self, join, from_linter=from_linter, **kwargs ) else: if from_linter: from_linter.edges.add((join.left, join.right)) kwargs["asfrom"] = True if isinstance(join.right, expression.FromGrouping): right = join.right.element else: right = join.right return ( self.process(join.left, from_linter=from_linter, **kwargs) + ", " + self.process(right, from_linter=from_linter, **kwargs) ) def _get_nonansi_join_whereclause(self, froms): clauses = [] def visit_join(join): if join.isouter: # https://docs.oracle.com/database/121/SQLRF/queries006.htm#SQLRF52354 # "apply the outer join operator (+) to all columns of B in # the join condition in the WHERE clause" - that is, # unconditionally regardless of operator or the other side def visit_binary(binary): if isinstance( binary.left, expression.ColumnClause ) and join.right.is_derived_from(binary.left.table): binary.left = _OuterJoinColumn(binary.left) elif isinstance( binary.right, expression.ColumnClause ) and join.right.is_derived_from(binary.right.table): binary.right = _OuterJoinColumn(binary.right) clauses.append( visitors.cloned_traverse( join.onclause, {}, {"binary": visit_binary} ) ) else: clauses.append(join.onclause) for j in join.left, join.right: if isinstance(j, expression.Join): visit_join(j) elif isinstance(j, expression.FromGrouping): visit_join(j.element) for f in froms: if isinstance(f, expression.Join): visit_join(f) if not clauses: return None else: return sql.and_(*clauses) def visit_outer_join_column(self, vc, **kw): return self.process(vc.column, **kw) + "(+)" def visit_sequence(self, seq, **kw): return self.preparer.format_sequence(seq) + ".nextval" def get_render_as_alias_suffix(self, alias_name_text): """Oracle doesn't like ``FROM table AS alias``""" return " " + alias_name_text def returning_clause( self, stmt, returning_cols, *, populate_result_map, **kw ): columns = [] binds = [] for i, column in enumerate( expression._select_iterables(returning_cols) ): if ( self.isupdate and isinstance(column, sa_schema.Column) and isinstance(column.server_default, Computed) and not self.dialect._supports_update_returning_computed_cols ): util.warn( "Computed columns don't work with Oracle Database UPDATE " "statements that use RETURNING; the value of the column " "*before* the UPDATE takes place is returned. It is " "advised to not use RETURNING with an Oracle Database " "computed column. Consider setting implicit_returning " "to False on the Table object in order to avoid implicit " "RETURNING clauses from being generated for this Table." ) if column.type._has_column_expression: col_expr = column.type.column_expression(column) else: col_expr = column outparam = sql.outparam("ret_%d" % i, type_=column.type) self.binds[outparam.key] = outparam binds.append( self.bindparam_string(self._truncate_bindparam(outparam)) ) # has_out_parameters would in a normal case be set to True # as a result of the compiler visiting an outparam() object. # in this case, the above outparam() objects are not being # visited. Ensure the statement itself didn't have other # outparam() objects independently. # technically, this could be supported, but as it would be # a very strange use case without a clear rationale, disallow it if self.has_out_parameters: raise exc.InvalidRequestError( "Using explicit outparam() objects with " "UpdateBase.returning() in the same Core DML statement " "is not supported in the Oracle Database dialects." ) self._oracle_returning = True columns.append(self.process(col_expr, within_columns_clause=False)) if populate_result_map: self._add_to_result_map( getattr(col_expr, "name", col_expr._anon_name_label), getattr(col_expr, "name", col_expr._anon_name_label), ( column, getattr(column, "name", None), getattr(column, "key", None), ), column.type, ) return "RETURNING " + ", ".join(columns) + " INTO " + ", ".join(binds) def _row_limit_clause(self, select, **kw): """Oracle Database 12c supports OFFSET/FETCH operators Use it instead subquery with row_number """ if ( select._fetch_clause is not None or not self.dialect._supports_offset_fetch ): return super()._row_limit_clause( select, use_literal_execute_for_simple_int=True, **kw ) else: return self.fetch_clause( select, fetch_clause=self._get_limit_or_fetch(select), use_literal_execute_for_simple_int=True, **kw, ) def _get_limit_or_fetch(self, select): if select._fetch_clause is None: return select._limit_clause else: return select._fetch_clause def fetch_clause( self, select, fetch_clause=None, require_offset=False, use_literal_execute_for_simple_int=False, **kw, ): text = super().fetch_clause( select, fetch_clause=fetch_clause, require_offset=require_offset, use_literal_execute_for_simple_int=( use_literal_execute_for_simple_int ), **kw, ) if select.dialect_options["oracle"]["fetch_approximate"]: text = re.sub("FETCH FIRST", "FETCH APPROX FIRST", text) return text def translate_select_structure(self, select_stmt, **kwargs): select = select_stmt if not getattr(select, "_oracle_visit", None): if not self.dialect.use_ansi: froms = self._display_froms_for_select( select, kwargs.get("asfrom", False) ) whereclause = self._get_nonansi_join_whereclause(froms) if whereclause is not None: select = select.where(whereclause) select._oracle_visit = True # if fetch is used this is not needed if ( select._has_row_limiting_clause and not self.dialect._supports_offset_fetch and select._fetch_clause is None ): limit_clause = select._limit_clause offset_clause = select._offset_clause if select._simple_int_clause(limit_clause): limit_clause = limit_clause.render_literal_execute() if select._simple_int_clause(offset_clause): offset_clause = offset_clause.render_literal_execute() # currently using form at: # https://blogs.oracle.com/oraclemagazine/\ # on-rownum-and-limiting-results orig_select = select select = select._generate() select._oracle_visit = True # add expressions to accommodate FOR UPDATE OF for_update = select._for_update_arg if for_update is not None and for_update.of: for_update = for_update._clone() for_update._copy_internals() for elem in for_update.of: if not select.selected_columns.contains_column(elem): select = select.add_columns(elem) # Wrap the middle select and add the hint inner_subquery = select.alias() limitselect = sql.select( *[ c for c in inner_subquery.c if orig_select.selected_columns.corresponding_column(c) is not None ] ) if ( limit_clause is not None and self.dialect.optimize_limits and select._simple_int_clause(limit_clause) ): limitselect = limitselect.prefix_with( expression.text( "/*+ FIRST_ROWS(%s) */" % self.process(limit_clause, **kwargs) ) ) limitselect._oracle_visit = True limitselect._is_wrapper = True # add expressions to accommodate FOR UPDATE OF if for_update is not None and for_update.of: adapter = sql_util.ClauseAdapter(inner_subquery) for_update.of = [ adapter.traverse(elem) for elem in for_update.of ] # If needed, add the limiting clause if limit_clause is not None: if select._simple_int_clause(limit_clause) and ( offset_clause is None or select._simple_int_clause(offset_clause) ): max_row = limit_clause if offset_clause is not None: max_row = max_row + offset_clause else: max_row = limit_clause if offset_clause is not None: max_row = max_row + offset_clause limitselect = limitselect.where( sql.literal_column("ROWNUM") <= max_row ) # If needed, add the ora_rn, and wrap again with offset. if offset_clause is None: limitselect._for_update_arg = for_update select = limitselect else: limitselect = limitselect.add_columns( sql.literal_column("ROWNUM").label("ora_rn") ) limitselect._oracle_visit = True limitselect._is_wrapper = True if for_update is not None and for_update.of: limitselect_cols = limitselect.selected_columns for elem in for_update.of: if ( limitselect_cols.corresponding_column(elem) is None ): limitselect = limitselect.add_columns(elem) limit_subquery = limitselect.alias() origselect_cols = orig_select.selected_columns offsetselect = sql.select( *[ c for c in limit_subquery.c if origselect_cols.corresponding_column(c) is not None ] ) offsetselect._oracle_visit = True offsetselect._is_wrapper = True if for_update is not None and for_update.of: adapter = sql_util.ClauseAdapter(limit_subquery) for_update.of = [ adapter.traverse(elem) for elem in for_update.of ] offsetselect = offsetselect.where( sql.literal_column("ora_rn") > offset_clause ) offsetselect._for_update_arg = for_update select = offsetselect return select def limit_clause(self, select, **kw): return "" def visit_empty_set_expr(self, type_, **kw): return "SELECT 1 FROM DUAL WHERE 1!=1" def for_update_clause(self, select, **kw): if self.is_subquery(): return "" tmp = " FOR UPDATE" if select._for_update_arg.of: tmp += " OF " + ", ".join( self.process(elem, **kw) for elem in select._for_update_arg.of ) if select._for_update_arg.nowait: tmp += " NOWAIT" if select._for_update_arg.skip_locked: tmp += " SKIP LOCKED" return tmp def visit_is_distinct_from_binary(self, binary, operator, **kw): return "DECODE(%s, %s, 0, 1) = 1" % ( self.process(binary.left), self.process(binary.right), ) def visit_is_not_distinct_from_binary(self, binary, operator, **kw): return "DECODE(%s, %s, 0, 1) = 0" % ( self.process(binary.left), self.process(binary.right), ) def visit_regexp_match_op_binary(self, binary, operator, **kw): string = self.process(binary.left, **kw) pattern = self.process(binary.right, **kw) flags = binary.modifiers["flags"] if flags is None: return "REGEXP_LIKE(%s, %s)" % (string, pattern) else: return "REGEXP_LIKE(%s, %s, %s)" % ( string, pattern, self.render_literal_value(flags, sqltypes.STRINGTYPE), ) def visit_not_regexp_match_op_binary(self, binary, operator, **kw): return "NOT %s" % self.visit_regexp_match_op_binary( binary, operator, **kw ) def visit_regexp_replace_op_binary(self, binary, operator, **kw): string = self.process(binary.left, **kw) pattern_replace = self.process(binary.right, **kw) flags = binary.modifiers["flags"] if flags is None: return "REGEXP_REPLACE(%s, %s)" % ( string, pattern_replace, ) else: return "REGEXP_REPLACE(%s, %s, %s)" % ( string, pattern_replace, self.render_literal_value(flags, sqltypes.STRINGTYPE), ) def visit_aggregate_strings_func(self, fn, **kw): return "LISTAGG%s" % self.function_argspec(fn, **kw) def _visit_bitwise(self, binary, fn_name, custom_right=None, **kw): left = self.process(binary.left, **kw) right = self.process( custom_right if custom_right is not None else binary.right, **kw ) return f"{fn_name}({left}, {right})" def visit_bitwise_xor_op_binary(self, binary, operator, **kw): return self._visit_bitwise(binary, "BITXOR", **kw) def visit_bitwise_or_op_binary(self, binary, operator, **kw): return self._visit_bitwise(binary, "BITOR", **kw) def visit_bitwise_and_op_binary(self, binary, operator, **kw): return self._visit_bitwise(binary, "BITAND", **kw) def visit_bitwise_rshift_op_binary(self, binary, operator, **kw): raise exc.CompileError("Cannot compile bitwise_rshift in oracle") def visit_bitwise_lshift_op_binary(self, binary, operator, **kw): raise exc.CompileError("Cannot compile bitwise_lshift in oracle") def visit_bitwise_not_op_unary_operator(self, element, operator, **kw): raise exc.CompileError("Cannot compile bitwise_not in oracle") class OracleDDLCompiler(compiler.DDLCompiler): def _build_vector_index_config( self, vector_index_config: VectorIndexConfig ) -> str: parts = [] sql_param_name = { "hnsw_neighbors": "neighbors", "hnsw_efconstruction": "efconstruction", "ivf_neighbor_partitions": "neighbor partitions", "ivf_sample_per_partition": "sample_per_partition", "ivf_min_vectors_per_partition": "min_vectors_per_partition", } if vector_index_config.index_type == VectorIndexType.HNSW: parts.append("ORGANIZATION INMEMORY NEIGHBOR GRAPH") elif vector_index_config.index_type == VectorIndexType.IVF: parts.append("ORGANIZATION NEIGHBOR PARTITIONS") if vector_index_config.distance is not None: parts.append(f"DISTANCE {vector_index_config.distance.value}") if vector_index_config.accuracy is not None: parts.append( f"WITH TARGET ACCURACY {vector_index_config.accuracy}" ) parameters_str = [f"type {vector_index_config.index_type.name}"] prefix = vector_index_config.index_type.name.lower() + "_" for field in fields(vector_index_config): if field.name.startswith(prefix): key = sql_param_name.get(field.name) value = getattr(vector_index_config, field.name) if value is not None: parameters_str.append(f"{key} {value}") parameters_str = ", ".join(parameters_str) parts.append(f"PARAMETERS ({parameters_str})") if vector_index_config.parallel is not None: parts.append(f"PARALLEL {vector_index_config.parallel}") return " ".join(parts) def define_constraint_cascades(self, constraint): text = "" if constraint.ondelete is not None: text += " ON DELETE %s" % constraint.ondelete # oracle has no ON UPDATE CASCADE - # its only available via triggers # https://web.archive.org/web/20090317041251/https://asktom.oracle.com/tkyte/update_cascade/index.html if constraint.onupdate is not None: util.warn( "Oracle Database does not contain native UPDATE CASCADE " "functionality - onupdates will not be rendered for foreign " "keys. Consider using deferrable=True, initially='deferred' " "or triggers." ) return text def visit_drop_table_comment(self, drop, **kw): return "COMMENT ON TABLE %s IS ''" % self.preparer.format_table( drop.element ) def visit_create_index(self, create, **kw): index = create.element self._verify_index_table(index) preparer = self.preparer text = "CREATE " if index.unique: text += "UNIQUE " if index.dialect_options["oracle"]["bitmap"]: text += "BITMAP " vector_options = index.dialect_options["oracle"]["vector"] if vector_options: text += "VECTOR " text += "INDEX %s ON %s (%s)" % ( self._prepared_index_name(index, include_schema=True), preparer.format_table(index.table, use_schema=True), ", ".join( self.sql_compiler.process( expr, include_table=False, literal_binds=True ) for expr in index.expressions ), ) if index.dialect_options["oracle"]["compress"] is not False: if index.dialect_options["oracle"]["compress"] is True: text += " COMPRESS" else: text += " COMPRESS %d" % ( index.dialect_options["oracle"]["compress"] ) if vector_options: if vector_options is True: vector_options = VectorIndexConfig() text += " " + self._build_vector_index_config(vector_options) return text def post_create_table(self, table): table_opts = [] opts = table.dialect_options["oracle"] if opts["on_commit"]: on_commit_options = opts["on_commit"].replace("_", " ").upper() table_opts.append("\n ON COMMIT %s" % on_commit_options) if opts["compress"]: if opts["compress"] is True: table_opts.append("\n COMPRESS") else: table_opts.append("\n COMPRESS FOR %s" % (opts["compress"])) if opts["tablespace"]: table_opts.append( "\n TABLESPACE %s" % self.preparer.quote(opts["tablespace"]) ) return "".join(table_opts) def get_identity_options(self, identity_options): text = super().get_identity_options(identity_options) text = text.replace("NO MINVALUE", "NOMINVALUE") text = text.replace("NO MAXVALUE", "NOMAXVALUE") text = text.replace("NO CYCLE", "NOCYCLE") if identity_options.order is not None: text += " ORDER" if identity_options.order else " NOORDER" return text.strip() def visit_computed_column(self, generated, **kw): text = "GENERATED ALWAYS AS (%s)" % self.sql_compiler.process( generated.sqltext, include_table=False, literal_binds=True ) if generated.persisted is True: raise exc.CompileError( "Oracle Database computed columns do not support 'stored' " "persistence; set the 'persisted' flag to None or False for " "Oracle Database support." ) elif generated.persisted is False: text += " VIRTUAL" return text def visit_identity_column(self, identity, **kw): if identity.always is None: kind = "" else: kind = "ALWAYS" if identity.always else "BY DEFAULT" text = "GENERATED %s" % kind if identity.on_null: text += " ON NULL" text += " AS IDENTITY" options = self.get_identity_options(identity) if options: text += " (%s)" % options return text class OracleIdentifierPreparer(compiler.IdentifierPreparer): reserved_words = {x.lower() for x in RESERVED_WORDS} illegal_initial_characters = {str(dig) for dig in range(0, 10)}.union( ["_", "$"] ) def _bindparam_requires_quotes(self, value): """Return True if the given identifier requires quoting.""" lc_value = value.lower() return ( lc_value in self.reserved_words or value[0] in self.illegal_initial_characters or not self.legal_characters.match(str(value)) ) def format_savepoint(self, savepoint): name = savepoint.ident.lstrip("_") return super().format_savepoint(savepoint, name) class OracleExecutionContext(default.DefaultExecutionContext): def fire_sequence(self, seq, type_): return self._execute_scalar( "SELECT " + self.identifier_preparer.format_sequence(seq) + ".nextval FROM DUAL", type_, ) def pre_exec(self): if self.statement and "_oracle_dblink" in self.execution_options: self.statement = self.statement.replace( dictionary.DB_LINK_PLACEHOLDER, self.execution_options["_oracle_dblink"], ) class OracleDialect(default.DefaultDialect): name = "oracle" supports_statement_cache = True supports_alter = True max_identifier_length = 128 _supports_offset_fetch = True insert_returning = True update_returning = True delete_returning = True div_is_floordiv = False supports_simple_order_by_label = False cte_follows_insert = True returns_native_bytes = True supports_sequences = True sequences_optional = False postfetch_lastrowid = False default_paramstyle = "named" colspecs = colspecs ischema_names = ischema_names requires_name_normalize = True supports_comments = True supports_default_values = False supports_default_metavalue = True supports_empty_insert = False supports_identity_columns = True statement_compiler = OracleCompiler ddl_compiler = OracleDDLCompiler type_compiler_cls = OracleTypeCompiler preparer = OracleIdentifierPreparer execution_ctx_cls = OracleExecutionContext reflection_options = ("oracle_resolve_synonyms",) _use_nchar_for_unicode = False construct_arguments = [ ( sa_schema.Table, { "resolve_synonyms": False, "on_commit": None, "compress": False, "tablespace": None, }, ), ( sa_schema.Index, { "bitmap": False, "compress": False, "vector": False, }, ), (sa_selectable.Select, {"fetch_approximate": False}), (sa_selectable.CompoundSelect, {"fetch_approximate": False}), ] @util.deprecated_params( use_binds_for_limits=( "1.4", "The ``use_binds_for_limits`` Oracle Database dialect parameter " "is deprecated. The dialect now renders LIMIT / OFFSET integers " "inline in all cases using a post-compilation hook, so that the " "value is still represented by a 'bound parameter' on the Core " "Expression side.", ) ) def __init__( self, use_ansi=True, optimize_limits=False, use_binds_for_limits=None, use_nchar_for_unicode=False, exclude_tablespaces=("SYSTEM", "SYSAUX"), enable_offset_fetch=True, **kwargs, ): default.DefaultDialect.__init__(self, **kwargs) self._use_nchar_for_unicode = use_nchar_for_unicode self.use_ansi = use_ansi self.optimize_limits = optimize_limits self.exclude_tablespaces = exclude_tablespaces self.enable_offset_fetch = self._supports_offset_fetch = ( enable_offset_fetch ) def initialize(self, connection): super().initialize(connection) # Oracle 8i has RETURNING: # https://docs.oracle.com/cd/A87860_01/doc/index.htm # so does Oracle8: # https://docs.oracle.com/cd/A64702_01/doc/index.htm if self._is_oracle_8: self.colspecs = self.colspecs.copy() self.colspecs.pop(sqltypes.Interval) self.use_ansi = False self.supports_identity_columns = self.server_version_info >= (12,) self._supports_offset_fetch = ( self.enable_offset_fetch and self.server_version_info >= (12,) ) def _get_effective_compat_server_version_info(self, connection): # dialect does not need compat levels below 12.2, so don't query # in those cases if self.server_version_info < (12, 2): return self.server_version_info try: compat = connection.exec_driver_sql( "SELECT value FROM v$parameter WHERE name = 'compatible'" ).scalar() except exc.DBAPIError: compat = None if compat: try: return tuple(int(x) for x in compat.split(".")) except: return self.server_version_info else: return self.server_version_info @property def _is_oracle_8(self): return self.server_version_info and self.server_version_info < (9,) @property def _supports_table_compression(self): return self.server_version_info and self.server_version_info >= (10, 1) @property def _supports_table_compress_for(self): return self.server_version_info and self.server_version_info >= (11,) @property def _supports_char_length(self): return not self._is_oracle_8 @property def _supports_update_returning_computed_cols(self): # on version 18 this error is no longet present while it happens on 11 # it may work also on versions before the 18 return self.server_version_info and self.server_version_info >= (18,) @property def _supports_except_all(self): return self.server_version_info and self.server_version_info >= (21,) def do_release_savepoint(self, connection, name): # Oracle does not support RELEASE SAVEPOINT pass def _check_max_identifier_length(self, connection): if self._get_effective_compat_server_version_info(connection) < ( 12, 2, ): return 30 else: # use the default return None def get_isolation_level_values(self, dbapi_connection): return ["READ COMMITTED", "SERIALIZABLE"] def get_default_isolation_level(self, dbapi_conn): try: return self.get_isolation_level(dbapi_conn) except NotImplementedError: raise except: return "READ COMMITTED" def _execute_reflection( self, connection, query, dblink, returns_long, params=None ): if dblink and not dblink.startswith("@"): dblink = f"@{dblink}" execution_options = { # handle db links "_oracle_dblink": dblink or "", # override any schema translate map "schema_translate_map": None, } if dblink and returns_long: # Oracle seems to error with # "ORA-00997: illegal use of LONG datatype" when returning # LONG columns via a dblink in a query with bind params # This type seems to be very hard to cast into something else # so it seems easier to just use bind param in this case def visit_bindparam(bindparam): bindparam.literal_execute = True query = visitors.cloned_traverse( query, {}, {"bindparam": visit_bindparam} ) return connection.execute( query, params, execution_options=execution_options ) @util.memoized_property def _has_table_query(self): # materialized views are returned by all_tables tables = ( select( dictionary.all_tables.c.table_name, dictionary.all_tables.c.owner, ) .union_all( select( dictionary.all_views.c.view_name.label("table_name"), dictionary.all_views.c.owner, ) ) .subquery("tables_and_views") ) query = select(tables.c.table_name).where( tables.c.table_name == bindparam("table_name"), tables.c.owner == bindparam("owner"), ) return query @reflection.cache def has_table( self, connection, table_name, schema=None, dblink=None, **kw ): """Supported kw arguments are: ``dblink`` to reflect via a db link.""" self._ensure_has_table_connection(connection) if not schema: schema = self.default_schema_name params = { "table_name": self.denormalize_name(table_name), "owner": self.denormalize_schema_name(schema), } cursor = self._execute_reflection( connection, self._has_table_query, dblink, returns_long=False, params=params, ) return bool(cursor.scalar()) @reflection.cache def has_sequence( self, connection, sequence_name, schema=None, dblink=None, **kw ): """Supported kw arguments are: ``dblink`` to reflect via a db link.""" if not schema: schema = self.default_schema_name query = select(dictionary.all_sequences.c.sequence_name).where( dictionary.all_sequences.c.sequence_name == self.denormalize_schema_name(sequence_name), dictionary.all_sequences.c.sequence_owner == self.denormalize_schema_name(schema), ) cursor = self._execute_reflection( connection, query, dblink, returns_long=False ) return bool(cursor.scalar()) def _get_default_schema_name(self, connection): return self.normalize_name( connection.exec_driver_sql( "select sys_context( 'userenv', 'current_schema' ) from dual" ).scalar() ) def denormalize_schema_name(self, name): # look for quoted_name force = getattr(name, "quote", None) if force is None and name == "public": # look for case insensitive, no quoting specified, "public" return "PUBLIC" return super().denormalize_name(name) @reflection.flexi_cache( ("schema", InternalTraversal.dp_string), ("filter_names", InternalTraversal.dp_string_list), ("dblink", InternalTraversal.dp_string), ) def _get_synonyms(self, connection, schema, filter_names, dblink, **kw): owner = self.denormalize_schema_name( schema or self.default_schema_name ) has_filter_names, params = self._prepare_filter_names(filter_names) query = select( dictionary.all_synonyms.c.synonym_name, dictionary.all_synonyms.c.table_name, dictionary.all_synonyms.c.table_owner, dictionary.all_synonyms.c.db_link, ).where(dictionary.all_synonyms.c.owner == owner) if has_filter_names: query = query.where( dictionary.all_synonyms.c.synonym_name.in_( params["filter_names"] ) ) result = self._execute_reflection( connection, query, dblink, returns_long=False ).mappings() return result.all() @lru_cache() def _all_objects_query( self, owner, scope, kind, has_filter_names, has_mat_views ): query = ( select(dictionary.all_objects.c.object_name) .select_from(dictionary.all_objects) .where(dictionary.all_objects.c.owner == owner) ) # NOTE: materialized views are listed in all_objects twice; # once as MATERIALIZE VIEW and once as TABLE if kind is ObjectKind.ANY: # materilaized view are listed also as tables so there is no # need to add them to the in_. query = query.where( dictionary.all_objects.c.object_type.in_(("TABLE", "VIEW")) ) else: object_type = [] if ObjectKind.VIEW in kind: object_type.append("VIEW") if ( ObjectKind.MATERIALIZED_VIEW in kind and ObjectKind.TABLE not in kind ): # materilaized view are listed also as tables so there is no # need to add them to the in_ if also selecting tables. object_type.append("MATERIALIZED VIEW") if ObjectKind.TABLE in kind: object_type.append("TABLE") if has_mat_views and ObjectKind.MATERIALIZED_VIEW not in kind: # materialized view are listed also as tables, # so they need to be filtered out # EXCEPT ALL / MINUS profiles as faster than using # NOT EXISTS or NOT IN with a subquery, but it's in # general faster to get the mat view names and exclude # them only when needed query = query.where( dictionary.all_objects.c.object_name.not_in( bindparam("mat_views") ) ) query = query.where( dictionary.all_objects.c.object_type.in_(object_type) ) # handles scope if scope is ObjectScope.DEFAULT: query = query.where(dictionary.all_objects.c.temporary == "N") elif scope is ObjectScope.TEMPORARY: query = query.where(dictionary.all_objects.c.temporary == "Y") if has_filter_names: query = query.where( dictionary.all_objects.c.object_name.in_( bindparam("filter_names") ) ) return query @reflection.flexi_cache( ("schema", InternalTraversal.dp_string), ("scope", InternalTraversal.dp_plain_obj), ("kind", InternalTraversal.dp_plain_obj), ("filter_names", InternalTraversal.dp_string_list), ("dblink", InternalTraversal.dp_string), ) def _get_all_objects( self, connection, schema, scope, kind, filter_names, dblink, **kw ): owner = self.denormalize_schema_name( schema or self.default_schema_name ) has_filter_names, params = self._prepare_filter_names(filter_names) has_mat_views = False if ( ObjectKind.TABLE in kind and ObjectKind.MATERIALIZED_VIEW not in kind ): # see note in _all_objects_query mat_views = self.get_materialized_view_names( connection, schema, dblink, _normalize=False, **kw ) if mat_views: params["mat_views"] = mat_views has_mat_views = True query = self._all_objects_query( owner, scope, kind, has_filter_names, has_mat_views ) result = self._execute_reflection( connection, query, dblink, returns_long=False, params=params ).scalars() return result.all() def _handle_synonyms_decorator(fn): @wraps(fn) def wrapper(self, *args, **kwargs): return self._handle_synonyms(fn, *args, **kwargs) return wrapper def _handle_synonyms(self, fn, connection, *args, **kwargs): if not kwargs.get("oracle_resolve_synonyms", False): return fn(self, connection, *args, **kwargs) original_kw = kwargs.copy() schema = kwargs.pop("schema", None) result = self._get_synonyms( connection, schema=schema, filter_names=kwargs.pop("filter_names", None), dblink=kwargs.pop("dblink", None), info_cache=kwargs.get("info_cache", None), ) dblinks_owners = defaultdict(dict) for row in result: key = row["db_link"], row["table_owner"] tn = self.normalize_name(row["table_name"]) dblinks_owners[key][tn] = row["synonym_name"] if not dblinks_owners: # No synonym, do the plain thing return fn(self, connection, *args, **original_kw) data = {} for (dblink, table_owner), mapping in dblinks_owners.items(): call_kw = { **original_kw, "schema": table_owner, "dblink": self.normalize_name(dblink), "filter_names": mapping.keys(), } call_result = fn(self, connection, *args, **call_kw) for (_, tn), value in call_result: synonym_name = self.normalize_name(mapping[tn]) data[(schema, synonym_name)] = value return data.items() @reflection.cache def get_schema_names(self, connection, dblink=None, **kw): """Supported kw arguments are: ``dblink`` to reflect via a db link.""" query = select(dictionary.all_users.c.username).order_by( dictionary.all_users.c.username ) result = self._execute_reflection( connection, query, dblink, returns_long=False ).scalars() return [self.normalize_name(row) for row in result] @reflection.cache def get_table_names(self, connection, schema=None, dblink=None, **kw): """Supported kw arguments are: ``dblink`` to reflect via a db link.""" # note that table_names() isn't loading DBLINKed or synonym'ed tables if schema is None: schema = self.default_schema_name den_schema = self.denormalize_schema_name(schema) if kw.get("oracle_resolve_synonyms", False): tables = ( select( dictionary.all_tables.c.table_name, dictionary.all_tables.c.owner, dictionary.all_tables.c.iot_name, dictionary.all_tables.c.duration, dictionary.all_tables.c.tablespace_name, ) .union_all( select( dictionary.all_synonyms.c.synonym_name.label( "table_name" ), dictionary.all_synonyms.c.owner, dictionary.all_tables.c.iot_name, dictionary.all_tables.c.duration, dictionary.all_tables.c.tablespace_name, ) .select_from(dictionary.all_tables) .join( dictionary.all_synonyms, and_( dictionary.all_tables.c.table_name == dictionary.all_synonyms.c.table_name, dictionary.all_tables.c.owner == func.coalesce( dictionary.all_synonyms.c.table_owner, dictionary.all_synonyms.c.owner, ), ), ) ) .subquery("available_tables") ) else: tables = dictionary.all_tables query = select(tables.c.table_name) if self.exclude_tablespaces: query = query.where( func.coalesce( tables.c.tablespace_name, "no tablespace" ).not_in(self.exclude_tablespaces) ) query = query.where( tables.c.owner == den_schema, tables.c.iot_name.is_(null()), tables.c.duration.is_(null()), ) # remove materialized views mat_query = select( dictionary.all_mviews.c.mview_name.label("table_name") ).where(dictionary.all_mviews.c.owner == den_schema) query = ( query.except_all(mat_query) if self._supports_except_all else query.except_(mat_query) ) result = self._execute_reflection( connection, query, dblink, returns_long=False ).scalars() return [self.normalize_name(row) for row in result] @reflection.cache def get_temp_table_names(self, connection, dblink=None, **kw): """Supported kw arguments are: ``dblink`` to reflect via a db link.""" schema = self.denormalize_schema_name(self.default_schema_name) query = select(dictionary.all_tables.c.table_name) if self.exclude_tablespaces: query = query.where( func.coalesce( dictionary.all_tables.c.tablespace_name, "no tablespace" ).not_in(self.exclude_tablespaces) ) query = query.where( dictionary.all_tables.c.owner == schema, dictionary.all_tables.c.iot_name.is_(null()), dictionary.all_tables.c.duration.is_not(null()), ) result = self._execute_reflection( connection, query, dblink, returns_long=False ).scalars() return [self.normalize_name(row) for row in result] @reflection.cache def get_materialized_view_names( self, connection, schema=None, dblink=None, _normalize=True, **kw ): """Supported kw arguments are: ``dblink`` to reflect via a db link.""" if not schema: schema = self.default_schema_name query = select(dictionary.all_mviews.c.mview_name).where( dictionary.all_mviews.c.owner == self.denormalize_schema_name(schema) ) result = self._execute_reflection( connection, query, dblink, returns_long=False ).scalars() if _normalize: return [self.normalize_name(row) for row in result] else: return result.all() @reflection.cache def get_view_names(self, connection, schema=None, dblink=None, **kw): """Supported kw arguments are: ``dblink`` to reflect via a db link.""" if not schema: schema = self.default_schema_name query = select(dictionary.all_views.c.view_name).where( dictionary.all_views.c.owner == self.denormalize_schema_name(schema) ) result = self._execute_reflection( connection, query, dblink, returns_long=False ).scalars() return [self.normalize_name(row) for row in result] @reflection.cache def get_sequence_names(self, connection, schema=None, dblink=None, **kw): """Supported kw arguments are: ``dblink`` to reflect via a db link.""" if not schema: schema = self.default_schema_name query = select(dictionary.all_sequences.c.sequence_name).where( dictionary.all_sequences.c.sequence_owner == self.denormalize_schema_name(schema) ) result = self._execute_reflection( connection, query, dblink, returns_long=False ).scalars() return [self.normalize_name(row) for row in result] def _value_or_raise(self, data, table, schema): table = self.normalize_name(str(table)) try: return dict(data)[(schema, table)] except KeyError: raise exc.NoSuchTableError( f"{schema}.{table}" if schema else table ) from None def _prepare_filter_names(self, filter_names): if filter_names: fn = [self.denormalize_name(name) for name in filter_names] return True, {"filter_names": fn} else: return False, {} @reflection.cache def get_table_options(self, connection, table_name, schema=None, **kw): """Supported kw arguments are: ``dblink`` to reflect via a db link; ``oracle_resolve_synonyms`` to resolve names to synonyms """ data = self.get_multi_table_options( connection, schema=schema, filter_names=[table_name], scope=ObjectScope.ANY, kind=ObjectKind.ANY, **kw, ) return self._value_or_raise(data, table_name, schema) @lru_cache() def _table_options_query( self, owner, scope, kind, has_filter_names, has_mat_views ): query = select( dictionary.all_tables.c.table_name, ( dictionary.all_tables.c.compression if self._supports_table_compression else sql.null().label("compression") ), ( dictionary.all_tables.c.compress_for if self._supports_table_compress_for else sql.null().label("compress_for") ), dictionary.all_tables.c.tablespace_name, ).where(dictionary.all_tables.c.owner == owner) if has_filter_names: query = query.where( dictionary.all_tables.c.table_name.in_( bindparam("filter_names") ) ) if scope is ObjectScope.DEFAULT: query = query.where(dictionary.all_tables.c.duration.is_(null())) elif scope is ObjectScope.TEMPORARY: query = query.where( dictionary.all_tables.c.duration.is_not(null()) ) if ( has_mat_views and ObjectKind.TABLE in kind and ObjectKind.MATERIALIZED_VIEW not in kind ): # cant use EXCEPT ALL / MINUS here because we don't have an # excludable row vs. the query above # outerjoin + where null works better on oracle 21 but 11 does # not like it at all. this is the next best thing query = query.where( dictionary.all_tables.c.table_name.not_in( bindparam("mat_views") ) ) elif ( ObjectKind.TABLE not in kind and ObjectKind.MATERIALIZED_VIEW in kind ): query = query.where( dictionary.all_tables.c.table_name.in_(bindparam("mat_views")) ) return query @_handle_synonyms_decorator def get_multi_table_options( self, connection, *, schema, filter_names, scope, kind, dblink=None, **kw, ): """Supported kw arguments are: ``dblink`` to reflect via a db link; ``oracle_resolve_synonyms`` to resolve names to synonyms """ owner = self.denormalize_schema_name( schema or self.default_schema_name ) has_filter_names, params = self._prepare_filter_names(filter_names) has_mat_views = False if ( ObjectKind.TABLE in kind and ObjectKind.MATERIALIZED_VIEW not in kind ): # see note in _table_options_query mat_views = self.get_materialized_view_names( connection, schema, dblink, _normalize=False, **kw ) if mat_views: params["mat_views"] = mat_views has_mat_views = True elif ( ObjectKind.TABLE not in kind and ObjectKind.MATERIALIZED_VIEW in kind ): mat_views = self.get_materialized_view_names( connection, schema, dblink, _normalize=False, **kw ) params["mat_views"] = mat_views options = {} default = ReflectionDefaults.table_options if ObjectKind.TABLE in kind or ObjectKind.MATERIALIZED_VIEW in kind: query = self._table_options_query( owner, scope, kind, has_filter_names, has_mat_views ) result = self._execute_reflection( connection, query, dblink, returns_long=False, params=params ) for table, compression, compress_for, tablespace in result: data = default() if compression == "ENABLED": data["oracle_compress"] = compress_for if tablespace: data["oracle_tablespace"] = tablespace options[(schema, self.normalize_name(table))] = data if ObjectKind.VIEW in kind and ObjectScope.DEFAULT in scope: # add the views (no temporary views) for view in self.get_view_names(connection, schema, dblink, **kw): if not filter_names or view in filter_names: options[(schema, view)] = default() return options.items() @reflection.cache def get_columns(self, connection, table_name, schema=None, **kw): """Supported kw arguments are: ``dblink`` to reflect via a db link; ``oracle_resolve_synonyms`` to resolve names to synonyms """ data = self.get_multi_columns( connection, schema=schema, filter_names=[table_name], scope=ObjectScope.ANY, kind=ObjectKind.ANY, **kw, ) return self._value_or_raise(data, table_name, schema) def _run_batches( self, connection, query, dblink, returns_long, mappings, all_objects ): each_batch = 500 batches = list(all_objects) while batches: batch = batches[0:each_batch] batches[0:each_batch] = [] result = self._execute_reflection( connection, query, dblink, returns_long=returns_long, params={"all_objects": batch}, ) if mappings: yield from result.mappings() else: yield from result @lru_cache() def _column_query(self, owner): all_cols = dictionary.all_tab_cols all_comments = dictionary.all_col_comments all_ids = dictionary.all_tab_identity_cols if self.server_version_info >= (12,): add_cols = ( all_cols.c.default_on_null, sql.case( (all_ids.c.table_name.is_(None), sql.null()), else_=all_ids.c.generation_type + "," + all_ids.c.identity_options, ).label("identity_options"), ) join_identity_cols = True else: add_cols = ( sql.null().label("default_on_null"), sql.null().label("identity_options"), ) join_identity_cols = False # NOTE: on oracle cannot create tables/views without columns and # a table cannot have all column hidden: # ORA-54039: table must have at least one column that is not invisible # all_tab_cols returns data for tables/views/mat-views. # all_tab_cols does not return recycled tables query = ( select( all_cols.c.table_name, all_cols.c.column_name, all_cols.c.data_type, all_cols.c.char_length, all_cols.c.data_precision, all_cols.c.data_scale, all_cols.c.nullable, all_cols.c.data_default, all_comments.c.comments, all_cols.c.virtual_column, *add_cols, ).select_from(all_cols) # NOTE: all_col_comments has a row for each column even if no # comment is present, so a join could be performed, but there # seems to be no difference compared to an outer join .outerjoin( all_comments, and_( all_cols.c.table_name == all_comments.c.table_name, all_cols.c.column_name == all_comments.c.column_name, all_cols.c.owner == all_comments.c.owner, ), ) ) if join_identity_cols: query = query.outerjoin( all_ids, and_( all_cols.c.table_name == all_ids.c.table_name, all_cols.c.column_name == all_ids.c.column_name, all_cols.c.owner == all_ids.c.owner, ), ) query = query.where( all_cols.c.table_name.in_(bindparam("all_objects")), all_cols.c.hidden_column == "NO", all_cols.c.owner == owner, ).order_by(all_cols.c.table_name, all_cols.c.column_id) return query @_handle_synonyms_decorator def get_multi_columns( self, connection, *, schema, filter_names, scope, kind, dblink=None, **kw, ): """Supported kw arguments are: ``dblink`` to reflect via a db link; ``oracle_resolve_synonyms`` to resolve names to synonyms """ owner = self.denormalize_schema_name( schema or self.default_schema_name ) query = self._column_query(owner) if ( filter_names and kind is ObjectKind.ANY and scope is ObjectScope.ANY ): all_objects = [self.denormalize_name(n) for n in filter_names] else: all_objects = self._get_all_objects( connection, schema, scope, kind, filter_names, dblink, **kw ) columns = defaultdict(list) # all_tab_cols.data_default is LONG result = self._run_batches( connection, query, dblink, returns_long=True, mappings=True, all_objects=all_objects, ) def maybe_int(value): if isinstance(value, float) and value.is_integer(): return int(value) else: return value remove_size = re.compile(r"\(\d+\)") for row_dict in result: table_name = self.normalize_name(row_dict["table_name"]) orig_colname = row_dict["column_name"] colname = self.normalize_name(orig_colname) coltype = row_dict["data_type"] precision = maybe_int(row_dict["data_precision"]) if coltype == "NUMBER": scale = maybe_int(row_dict["data_scale"]) if precision is None and scale == 0: coltype = INTEGER() else: coltype = NUMBER(precision, scale) elif coltype == "FLOAT": # https://docs.oracle.com/cd/B14117_01/server.101/b10758/sqlqr06.htm if precision == 126: # The DOUBLE PRECISION datatype is a floating-point # number with binary precision 126. coltype = DOUBLE_PRECISION() elif precision == 63: # The REAL datatype is a floating-point number with a # binary precision of 63, or 18 decimal. coltype = REAL() else: # non standard precision coltype = FLOAT(binary_precision=precision) elif coltype in ("VARCHAR2", "NVARCHAR2", "CHAR", "NCHAR"): char_length = maybe_int(row_dict["char_length"]) coltype = self.ischema_names.get(coltype)(char_length) elif "WITH TIME ZONE" in coltype: coltype = TIMESTAMP(timezone=True) elif "WITH LOCAL TIME ZONE" in coltype: coltype = TIMESTAMP(local_timezone=True) else: coltype = re.sub(remove_size, "", coltype) try: coltype = self.ischema_names[coltype] except KeyError: util.warn( "Did not recognize type '%s' of column '%s'" % (coltype, colname) ) coltype = sqltypes.NULLTYPE default = row_dict["data_default"] if row_dict["virtual_column"] == "YES": computed = dict(sqltext=default) default = None else: computed = None identity_options = row_dict["identity_options"] if identity_options is not None: identity = self._parse_identity_options( identity_options, row_dict["default_on_null"] ) default = None else: identity = None cdict = { "name": colname, "type": coltype, "nullable": row_dict["nullable"] == "Y", "default": default, "comment": row_dict["comments"], } if orig_colname.lower() == orig_colname: cdict["quote"] = True if computed is not None: cdict["computed"] = computed if identity is not None: cdict["identity"] = identity columns[(schema, table_name)].append(cdict) # NOTE: default not needed since all tables have columns # default = ReflectionDefaults.columns # return ( # (key, value if value else default()) # for key, value in columns.items() # ) return columns.items() def _parse_identity_options(self, identity_options, default_on_null): # identity_options is a string that starts with 'ALWAYS,' or # 'BY DEFAULT,' and continues with # START WITH: 1, INCREMENT BY: 1, MAX_VALUE: 123, MIN_VALUE: 1, # CYCLE_FLAG: N, CACHE_SIZE: 1, ORDER_FLAG: N, SCALE_FLAG: N, # EXTEND_FLAG: N, SESSION_FLAG: N, KEEP_VALUE: N parts = [p.strip() for p in identity_options.split(",")] identity = { "always": parts[0] == "ALWAYS", "on_null": default_on_null == "YES", } for part in parts[1:]: option, value = part.split(":") value = value.strip() if "START WITH" in option: identity["start"] = int(value) elif "INCREMENT BY" in option: identity["increment"] = int(value) elif "MAX_VALUE" in option: identity["maxvalue"] = int(value) elif "MIN_VALUE" in option: identity["minvalue"] = int(value) elif "CYCLE_FLAG" in option: identity["cycle"] = value == "Y" elif "CACHE_SIZE" in option: identity["cache"] = int(value) elif "ORDER_FLAG" in option: identity["order"] = value == "Y" return identity @reflection.cache def get_table_comment(self, connection, table_name, schema=None, **kw): """Supported kw arguments are: ``dblink`` to reflect via a db link; ``oracle_resolve_synonyms`` to resolve names to synonyms """ data = self.get_multi_table_comment( connection, schema=schema, filter_names=[table_name], scope=ObjectScope.ANY, kind=ObjectKind.ANY, **kw, ) return self._value_or_raise(data, table_name, schema) @lru_cache() def _comment_query(self, owner, scope, kind, has_filter_names): # NOTE: all_tab_comments / all_mview_comments have a row for all # object even if they don't have comments queries = [] if ObjectKind.TABLE in kind or ObjectKind.VIEW in kind: # all_tab_comments returns also plain views tbl_view = select( dictionary.all_tab_comments.c.table_name, dictionary.all_tab_comments.c.comments, ).where( dictionary.all_tab_comments.c.owner == owner, dictionary.all_tab_comments.c.table_name.not_like("BIN$%"), ) if ObjectKind.VIEW not in kind: tbl_view = tbl_view.where( dictionary.all_tab_comments.c.table_type == "TABLE" ) elif ObjectKind.TABLE not in kind: tbl_view = tbl_view.where( dictionary.all_tab_comments.c.table_type == "VIEW" ) queries.append(tbl_view) if ObjectKind.MATERIALIZED_VIEW in kind: mat_view = select( dictionary.all_mview_comments.c.mview_name.label("table_name"), dictionary.all_mview_comments.c.comments, ).where( dictionary.all_mview_comments.c.owner == owner, dictionary.all_mview_comments.c.mview_name.not_like("BIN$%"), ) queries.append(mat_view) if len(queries) == 1: query = queries[0] else: union = sql.union_all(*queries).subquery("tables_and_views") query = select(union.c.table_name, union.c.comments) name_col = query.selected_columns.table_name if scope in (ObjectScope.DEFAULT, ObjectScope.TEMPORARY): temp = "Y" if scope is ObjectScope.TEMPORARY else "N" # need distinct since materialized view are listed also # as tables in all_objects query = query.distinct().join( dictionary.all_objects, and_( dictionary.all_objects.c.owner == owner, dictionary.all_objects.c.object_name == name_col, dictionary.all_objects.c.temporary == temp, ), ) if has_filter_names: query = query.where(name_col.in_(bindparam("filter_names"))) return query @_handle_synonyms_decorator def get_multi_table_comment( self, connection, *, schema, filter_names, scope, kind, dblink=None, **kw, ): """Supported kw arguments are: ``dblink`` to reflect via a db link; ``oracle_resolve_synonyms`` to resolve names to synonyms """ owner = self.denormalize_schema_name( schema or self.default_schema_name ) has_filter_names, params = self._prepare_filter_names(filter_names) query = self._comment_query(owner, scope, kind, has_filter_names) result = self._execute_reflection( connection, query, dblink, returns_long=False, params=params ) default = ReflectionDefaults.table_comment # materialized views by default seem to have a comment like # "snapshot table for snapshot owner.mat_view_name" ignore_mat_view = "snapshot table for snapshot " return ( ( (schema, self.normalize_name(table)), ( {"text": comment} if comment is not None and not comment.startswith(ignore_mat_view) else default() ), ) for table, comment in result ) @reflection.cache def get_indexes(self, connection, table_name, schema=None, **kw): """Supported kw arguments are: ``dblink`` to reflect via a db link; ``oracle_resolve_synonyms`` to resolve names to synonyms """ data = self.get_multi_indexes( connection, schema=schema, filter_names=[table_name], scope=ObjectScope.ANY, kind=ObjectKind.ANY, **kw, ) return self._value_or_raise(data, table_name, schema) @lru_cache() def _index_query(self, owner): return ( select( dictionary.all_ind_columns.c.table_name, dictionary.all_ind_columns.c.index_name, dictionary.all_ind_columns.c.column_name, dictionary.all_indexes.c.index_type, dictionary.all_indexes.c.uniqueness, dictionary.all_indexes.c.compression, dictionary.all_indexes.c.prefix_length, dictionary.all_ind_columns.c.descend, dictionary.all_ind_expressions.c.column_expression, ) .select_from(dictionary.all_ind_columns) .join( dictionary.all_indexes, sql.and_( dictionary.all_ind_columns.c.index_name == dictionary.all_indexes.c.index_name, dictionary.all_ind_columns.c.index_owner == dictionary.all_indexes.c.owner, ), ) .outerjoin( # NOTE: this adds about 20% to the query time. Using a # case expression with a scalar subquery only when needed # with the assumption that most indexes are not expression # would be faster but oracle does not like that with # LONG datatype. It errors with: # ORA-00997: illegal use of LONG datatype dictionary.all_ind_expressions, sql.and_( dictionary.all_ind_expressions.c.index_name == dictionary.all_ind_columns.c.index_name, dictionary.all_ind_expressions.c.index_owner == dictionary.all_ind_columns.c.index_owner, dictionary.all_ind_expressions.c.column_position == dictionary.all_ind_columns.c.column_position, ), ) .where( dictionary.all_indexes.c.table_owner == owner, dictionary.all_indexes.c.table_name.in_( bindparam("all_objects") ), ) .order_by( dictionary.all_ind_columns.c.index_name, dictionary.all_ind_columns.c.column_position, ) ) @reflection.flexi_cache( ("schema", InternalTraversal.dp_string), ("dblink", InternalTraversal.dp_string), ("all_objects", InternalTraversal.dp_string_list), ) def _get_indexes_rows(self, connection, schema, dblink, all_objects, **kw): owner = self.denormalize_schema_name( schema or self.default_schema_name ) query = self._index_query(owner) pks = { row_dict["constraint_name"] for row_dict in self._get_all_constraint_rows( connection, schema, dblink, all_objects, **kw ) if row_dict["constraint_type"] == "P" } # all_ind_expressions.column_expression is LONG result = self._run_batches( connection, query, dblink, returns_long=True, mappings=True, all_objects=all_objects, ) return [ row_dict for row_dict in result if row_dict["index_name"] not in pks ] @_handle_synonyms_decorator def get_multi_indexes( self, connection, *, schema, filter_names, scope, kind, dblink=None, **kw, ): """Supported kw arguments are: ``dblink`` to reflect via a db link; ``oracle_resolve_synonyms`` to resolve names to synonyms """ all_objects = self._get_all_objects( connection, schema, scope, kind, filter_names, dblink, **kw ) uniqueness = {"NONUNIQUE": False, "UNIQUE": True} enabled = {"DISABLED": False, "ENABLED": True} is_bitmap = {"BITMAP", "FUNCTION-BASED BITMAP"} indexes = defaultdict(dict) for row_dict in self._get_indexes_rows( connection, schema, dblink, all_objects, **kw ): index_name = self.normalize_name(row_dict["index_name"]) table_name = self.normalize_name(row_dict["table_name"]) table_indexes = indexes[(schema, table_name)] if index_name not in table_indexes: table_indexes[index_name] = index_dict = { "name": index_name, "column_names": [], "dialect_options": {}, "unique": uniqueness.get(row_dict["uniqueness"], False), } do = index_dict["dialect_options"] if row_dict["index_type"] in is_bitmap: do["oracle_bitmap"] = True if enabled.get(row_dict["compression"], False): do["oracle_compress"] = row_dict["prefix_length"] else: index_dict = table_indexes[index_name] expr = row_dict["column_expression"] if expr is not None: index_dict["column_names"].append(None) if "expressions" in index_dict: index_dict["expressions"].append(expr) else: index_dict["expressions"] = index_dict["column_names"][:-1] index_dict["expressions"].append(expr) if row_dict["descend"].lower() != "asc": assert row_dict["descend"].lower() == "desc" cs = index_dict.setdefault("column_sorting", {}) cs[expr] = ("desc",) else: assert row_dict["descend"].lower() == "asc" cn = self.normalize_name(row_dict["column_name"]) index_dict["column_names"].append(cn) if "expressions" in index_dict: index_dict["expressions"].append(cn) default = ReflectionDefaults.indexes return ( (key, list(indexes[key].values()) if key in indexes else default()) for key in ( (schema, self.normalize_name(obj_name)) for obj_name in all_objects ) ) @reflection.cache def get_pk_constraint(self, connection, table_name, schema=None, **kw): """Supported kw arguments are: ``dblink`` to reflect via a db link; ``oracle_resolve_synonyms`` to resolve names to synonyms """ data = self.get_multi_pk_constraint( connection, schema=schema, filter_names=[table_name], scope=ObjectScope.ANY, kind=ObjectKind.ANY, **kw, ) return self._value_or_raise(data, table_name, schema) @lru_cache() def _constraint_query(self, owner): local = dictionary.all_cons_columns.alias("local") remote = dictionary.all_cons_columns.alias("remote") return ( select( dictionary.all_constraints.c.table_name, dictionary.all_constraints.c.constraint_type, dictionary.all_constraints.c.constraint_name, local.c.column_name.label("local_column"), remote.c.table_name.label("remote_table"), remote.c.column_name.label("remote_column"), remote.c.owner.label("remote_owner"), dictionary.all_constraints.c.search_condition, dictionary.all_constraints.c.delete_rule, ) .select_from(dictionary.all_constraints) .join( local, and_( local.c.owner == dictionary.all_constraints.c.owner, dictionary.all_constraints.c.constraint_name == local.c.constraint_name, ), ) .outerjoin( remote, and_( dictionary.all_constraints.c.r_owner == remote.c.owner, dictionary.all_constraints.c.r_constraint_name == remote.c.constraint_name, or_( remote.c.position.is_(sql.null()), local.c.position == remote.c.position, ), ), ) .where( dictionary.all_constraints.c.owner == owner, dictionary.all_constraints.c.table_name.in_( bindparam("all_objects") ), dictionary.all_constraints.c.constraint_type.in_( ("R", "P", "U", "C") ), ) .order_by( dictionary.all_constraints.c.constraint_name, local.c.position ) ) @reflection.flexi_cache( ("schema", InternalTraversal.dp_string), ("dblink", InternalTraversal.dp_string), ("all_objects", InternalTraversal.dp_string_list), ) def _get_all_constraint_rows( self, connection, schema, dblink, all_objects, **kw ): owner = self.denormalize_schema_name( schema or self.default_schema_name ) query = self._constraint_query(owner) # since the result is cached a list must be created values = list( self._run_batches( connection, query, dblink, returns_long=False, mappings=True, all_objects=all_objects, ) ) return values @_handle_synonyms_decorator def get_multi_pk_constraint( self, connection, *, scope, schema, filter_names, kind, dblink=None, **kw, ): """Supported kw arguments are: ``dblink`` to reflect via a db link; ``oracle_resolve_synonyms`` to resolve names to synonyms """ all_objects = self._get_all_objects( connection, schema, scope, kind, filter_names, dblink, **kw ) primary_keys = defaultdict(dict) default = ReflectionDefaults.pk_constraint for row_dict in self._get_all_constraint_rows( connection, schema, dblink, all_objects, **kw ): if row_dict["constraint_type"] != "P": continue table_name = self.normalize_name(row_dict["table_name"]) constraint_name = self.normalize_name(row_dict["constraint_name"]) column_name = self.normalize_name(row_dict["local_column"]) table_pk = primary_keys[(schema, table_name)] if not table_pk: table_pk["name"] = constraint_name table_pk["constrained_columns"] = [column_name] else: table_pk["constrained_columns"].append(column_name) return ( (key, primary_keys[key] if key in primary_keys else default()) for key in ( (schema, self.normalize_name(obj_name)) for obj_name in all_objects ) ) @reflection.cache def get_foreign_keys( self, connection, table_name, schema=None, **kw, ): """Supported kw arguments are: ``dblink`` to reflect via a db link; ``oracle_resolve_synonyms`` to resolve names to synonyms """ data = self.get_multi_foreign_keys( connection, schema=schema, filter_names=[table_name], scope=ObjectScope.ANY, kind=ObjectKind.ANY, **kw, ) return self._value_or_raise(data, table_name, schema) @_handle_synonyms_decorator def get_multi_foreign_keys( self, connection, *, scope, schema, filter_names, kind, dblink=None, **kw, ): """Supported kw arguments are: ``dblink`` to reflect via a db link; ``oracle_resolve_synonyms`` to resolve names to synonyms """ all_objects = self._get_all_objects( connection, schema, scope, kind, filter_names, dblink, **kw ) resolve_synonyms = kw.get("oracle_resolve_synonyms", False) owner = self.denormalize_schema_name( schema or self.default_schema_name ) all_remote_owners = set() fkeys = defaultdict(dict) for row_dict in self._get_all_constraint_rows( connection, schema, dblink, all_objects, **kw ): if row_dict["constraint_type"] != "R": continue table_name = self.normalize_name(row_dict["table_name"]) constraint_name = self.normalize_name(row_dict["constraint_name"]) table_fkey = fkeys[(schema, table_name)] assert constraint_name is not None local_column = self.normalize_name(row_dict["local_column"]) remote_table = self.normalize_name(row_dict["remote_table"]) remote_column = self.normalize_name(row_dict["remote_column"]) remote_owner_orig = row_dict["remote_owner"] remote_owner = self.normalize_name(remote_owner_orig) if remote_owner_orig is not None: all_remote_owners.add(remote_owner_orig) if remote_table is None: # ticket 363 if dblink and not dblink.startswith("@"): dblink = f"@{dblink}" util.warn( "Got 'None' querying 'table_name' from " f"all_cons_columns{dblink or ''} - does the user have " "proper rights to the table?" ) continue if constraint_name not in table_fkey: table_fkey[constraint_name] = fkey = { "name": constraint_name, "constrained_columns": [], "referred_schema": None, "referred_table": remote_table, "referred_columns": [], "options": {}, } if resolve_synonyms: # will be removed below fkey["_ref_schema"] = remote_owner if schema is not None or remote_owner_orig != owner: fkey["referred_schema"] = remote_owner delete_rule = row_dict["delete_rule"] if delete_rule != "NO ACTION": fkey["options"]["ondelete"] = delete_rule else: fkey = table_fkey[constraint_name] fkey["constrained_columns"].append(local_column) fkey["referred_columns"].append(remote_column) if resolve_synonyms and all_remote_owners: query = select( dictionary.all_synonyms.c.owner, dictionary.all_synonyms.c.table_name, dictionary.all_synonyms.c.table_owner, dictionary.all_synonyms.c.synonym_name, ).where(dictionary.all_synonyms.c.owner.in_(all_remote_owners)) result = self._execute_reflection( connection, query, dblink, returns_long=False ).mappings() remote_owners_lut = {} for row in result: synonym_owner = self.normalize_name(row["owner"]) table_name = self.normalize_name(row["table_name"]) remote_owners_lut[(synonym_owner, table_name)] = ( row["table_owner"], row["synonym_name"], ) empty = (None, None) for table_fkeys in fkeys.values(): for table_fkey in table_fkeys.values(): key = ( table_fkey.pop("_ref_schema"), table_fkey["referred_table"], ) remote_owner, syn_name = remote_owners_lut.get(key, empty) if syn_name: sn = self.normalize_name(syn_name) table_fkey["referred_table"] = sn if schema is not None or remote_owner != owner: ro = self.normalize_name(remote_owner) table_fkey["referred_schema"] = ro else: table_fkey["referred_schema"] = None default = ReflectionDefaults.foreign_keys return ( (key, list(fkeys[key].values()) if key in fkeys else default()) for key in ( (schema, self.normalize_name(obj_name)) for obj_name in all_objects ) ) @reflection.cache def get_unique_constraints( self, connection, table_name, schema=None, **kw ): """Supported kw arguments are: ``dblink`` to reflect via a db link; ``oracle_resolve_synonyms`` to resolve names to synonyms """ data = self.get_multi_unique_constraints( connection, schema=schema, filter_names=[table_name], scope=ObjectScope.ANY, kind=ObjectKind.ANY, **kw, ) return self._value_or_raise(data, table_name, schema) @_handle_synonyms_decorator def get_multi_unique_constraints( self, connection, *, scope, schema, filter_names, kind, dblink=None, **kw, ): """Supported kw arguments are: ``dblink`` to reflect via a db link; ``oracle_resolve_synonyms`` to resolve names to synonyms """ all_objects = self._get_all_objects( connection, schema, scope, kind, filter_names, dblink, **kw ) unique_cons = defaultdict(dict) index_names = { row_dict["index_name"] for row_dict in self._get_indexes_rows( connection, schema, dblink, all_objects, **kw ) } for row_dict in self._get_all_constraint_rows( connection, schema, dblink, all_objects, **kw ): if row_dict["constraint_type"] != "U": continue table_name = self.normalize_name(row_dict["table_name"]) constraint_name_orig = row_dict["constraint_name"] constraint_name = self.normalize_name(constraint_name_orig) column_name = self.normalize_name(row_dict["local_column"]) table_uc = unique_cons[(schema, table_name)] assert constraint_name is not None if constraint_name not in table_uc: table_uc[constraint_name] = uc = { "name": constraint_name, "column_names": [], "duplicates_index": ( constraint_name if constraint_name_orig in index_names else None ), } else: uc = table_uc[constraint_name] uc["column_names"].append(column_name) default = ReflectionDefaults.unique_constraints return ( ( key, ( list(unique_cons[key].values()) if key in unique_cons else default() ), ) for key in ( (schema, self.normalize_name(obj_name)) for obj_name in all_objects ) ) @reflection.cache def get_view_definition( self, connection, view_name, schema=None, dblink=None, **kw, ): """Supported kw arguments are: ``dblink`` to reflect via a db link; ``oracle_resolve_synonyms`` to resolve names to synonyms """ if kw.get("oracle_resolve_synonyms", False): synonyms = self._get_synonyms( connection, schema, filter_names=[view_name], dblink=dblink ) if synonyms: assert len(synonyms) == 1 row_dict = synonyms[0] dblink = self.normalize_name(row_dict["db_link"]) schema = row_dict["table_owner"] view_name = row_dict["table_name"] name = self.denormalize_name(view_name) owner = self.denormalize_schema_name( schema or self.default_schema_name ) query = ( select(dictionary.all_views.c.text) .where( dictionary.all_views.c.view_name == name, dictionary.all_views.c.owner == owner, ) .union_all( select(dictionary.all_mviews.c.query).where( dictionary.all_mviews.c.mview_name == name, dictionary.all_mviews.c.owner == owner, ) ) ) rp = self._execute_reflection( connection, query, dblink, returns_long=False ).scalar() if rp is None: raise exc.NoSuchTableError( f"{schema}.{view_name}" if schema else view_name ) else: return rp @reflection.cache def get_check_constraints( self, connection, table_name, schema=None, include_all=False, **kw ): """Supported kw arguments are: ``dblink`` to reflect via a db link; ``oracle_resolve_synonyms`` to resolve names to synonyms """ data = self.get_multi_check_constraints( connection, schema=schema, filter_names=[table_name], scope=ObjectScope.ANY, include_all=include_all, kind=ObjectKind.ANY, **kw, ) return self._value_or_raise(data, table_name, schema) @_handle_synonyms_decorator def get_multi_check_constraints( self, connection, *, schema, filter_names, dblink=None, scope, kind, include_all=False, **kw, ): """Supported kw arguments are: ``dblink`` to reflect via a db link; ``oracle_resolve_synonyms`` to resolve names to synonyms """ all_objects = self._get_all_objects( connection, schema, scope, kind, filter_names, dblink, **kw ) not_null = re.compile(r"..+?. IS NOT NULL$") check_constraints = defaultdict(list) for row_dict in self._get_all_constraint_rows( connection, schema, dblink, all_objects, **kw ): if row_dict["constraint_type"] != "C": continue table_name = self.normalize_name(row_dict["table_name"]) constraint_name = self.normalize_name(row_dict["constraint_name"]) search_condition = row_dict["search_condition"] table_checks = check_constraints[(schema, table_name)] if constraint_name is not None and ( include_all or not not_null.match(search_condition) ): table_checks.append( {"name": constraint_name, "sqltext": search_condition} ) default = ReflectionDefaults.check_constraints return ( ( key, ( check_constraints[key] if key in check_constraints else default() ), ) for key in ( (schema, self.normalize_name(obj_name)) for obj_name in all_objects ) ) def _list_dblinks(self, connection, dblink=None): query = select(dictionary.all_db_links.c.db_link) links = self._execute_reflection( connection, query, dblink, returns_long=False ).scalars() return [self.normalize_name(link) for link in links] class _OuterJoinColumn(sql.ClauseElement): __visit_name__ = "outer_join_column" def __init__(self, column): self.column = column sqlalchemy/dialects/oracle/cx_oracle.py 0000755 00000156444 15125143220 0014270 0 ustar 00 # dialects/oracle/cx_oracle.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors r""".. dialect:: oracle+cx_oracle :name: cx-Oracle :dbapi: cx_oracle :connectstring: oracle+cx_oracle://user:pass@hostname:port[/dbname][?service_name=<service>[&key=value&key=value...]] :url: https://oracle.github.io/python-cx_Oracle/ Description ----------- cx_Oracle was the original driver for Oracle Database. It was superseded by python-oracledb which should be used instead. DSN vs. Hostname connections ----------------------------- cx_Oracle provides several methods of indicating the target database. The dialect translates from a series of different URL forms. Hostname Connections with Easy Connect Syntax ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Given a hostname, port and service name of the target database, for example from Oracle Database's Easy Connect syntax then connect in SQLAlchemy using the ``service_name`` query string parameter:: engine = create_engine( "oracle+cx_oracle://scott:tiger@hostname:port?service_name=myservice&encoding=UTF-8&nencoding=UTF-8" ) Note that the default driver value for encoding and nencoding was changed to “UTF-8” in cx_Oracle 8.0 so these parameters can be omitted when using that version, or later. To use a full Easy Connect string, pass it as the ``dsn`` key value in a :paramref:`_sa.create_engine.connect_args` dictionary:: import cx_Oracle e = create_engine( "oracle+cx_oracle://@", connect_args={ "user": "scott", "password": "tiger", "dsn": "hostname:port/myservice?transport_connect_timeout=30&expire_time=60", }, ) Connections with tnsnames.ora or to Oracle Autonomous Database ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Alternatively, if no port, database name, or service name is provided, the dialect will use an Oracle Database DSN "connection string". This takes the "hostname" portion of the URL as the data source name. For example, if the ``tnsnames.ora`` file contains a TNS Alias of ``myalias`` as below: .. sourcecode:: text myalias = (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = mymachine.example.com)(PORT = 1521)) (CONNECT_DATA = (SERVER = DEDICATED) (SERVICE_NAME = orclpdb1) ) ) The cx_Oracle dialect connects to this database service when ``myalias`` is the hostname portion of the URL, without specifying a port, database name or ``service_name``:: engine = create_engine("oracle+cx_oracle://scott:tiger@myalias") Users of Oracle Autonomous Database should use this syntax. If the database is configured for mutural TLS ("mTLS"), then you must also configure the cloud wallet as shown in cx_Oracle documentation `Connecting to Autononmous Databases <https://cx-oracle.readthedocs.io/en/latest/user_guide/connection_handling.html#autonomousdb>`_. SID Connections ^^^^^^^^^^^^^^^ To use Oracle Database's obsolete System Identifier connection syntax, the SID can be passed in a "database name" portion of the URL:: engine = create_engine( "oracle+cx_oracle://scott:tiger@hostname:port/dbname" ) Above, the DSN passed to cx_Oracle is created by ``cx_Oracle.makedsn()`` as follows:: >>> import cx_Oracle >>> cx_Oracle.makedsn("hostname", 1521, sid="dbname") '(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=hostname)(PORT=1521))(CONNECT_DATA=(SID=dbname)))' Note that although the SQLAlchemy syntax ``hostname:port/dbname`` looks like Oracle's Easy Connect syntax it is different. It uses a SID in place of the service name required by Easy Connect. The Easy Connect syntax does not support SIDs. Passing cx_Oracle connect arguments ----------------------------------- Additional connection arguments can usually be passed via the URL query string; particular symbols like ``SYSDBA`` are intercepted and converted to the correct symbol:: e = create_engine( "oracle+cx_oracle://user:pass@dsn?encoding=UTF-8&nencoding=UTF-8&mode=SYSDBA&events=true" ) .. versionchanged:: 1.3 the cx_Oracle dialect now accepts all argument names within the URL string itself, to be passed to the cx_Oracle DBAPI. As was the case earlier but not correctly documented, the :paramref:`_sa.create_engine.connect_args` parameter also accepts all cx_Oracle DBAPI connect arguments. To pass arguments directly to ``.connect()`` without using the query string, use the :paramref:`_sa.create_engine.connect_args` dictionary. Any cx_Oracle parameter value and/or constant may be passed, such as:: import cx_Oracle e = create_engine( "oracle+cx_oracle://user:pass@dsn", connect_args={ "encoding": "UTF-8", "nencoding": "UTF-8", "mode": cx_Oracle.SYSDBA, "events": True, }, ) Note that the default driver value for ``encoding`` and ``nencoding`` was changed to "UTF-8" in cx_Oracle 8.0 so these parameters can be omitted when using that version, or later. Options consumed by the SQLAlchemy cx_Oracle dialect outside of the driver -------------------------------------------------------------------------- There are also options that are consumed by the SQLAlchemy cx_oracle dialect itself. These options are always passed directly to :func:`_sa.create_engine` , such as:: e = create_engine( "oracle+cx_oracle://user:pass@dsn", coerce_to_decimal=False ) The parameters accepted by the cx_oracle dialect are as follows: * ``arraysize`` - set the cx_oracle.arraysize value on cursors; defaults to ``None``, indicating that the driver default should be used (typically the value is 100). This setting controls how many rows are buffered when fetching rows, and can have a significant effect on performance when modified. .. versionchanged:: 2.0.26 - changed the default value from 50 to None, to use the default value of the driver itself. * ``auto_convert_lobs`` - defaults to True; See :ref:`cx_oracle_lob`. * ``coerce_to_decimal`` - see :ref:`cx_oracle_numeric` for detail. * ``encoding_errors`` - see :ref:`cx_oracle_unicode_encoding_errors` for detail. .. _cx_oracle_sessionpool: Using cx_Oracle SessionPool --------------------------- The cx_Oracle driver provides its own connection pool implementation that may be used in place of SQLAlchemy's pooling functionality. The driver pool supports Oracle Database features such dead connection detection, connection draining for planned database downtime, support for Oracle Application Continuity and Transparent Application Continuity, and gives support for Database Resident Connection Pooling (DRCP). Using the driver pool can be achieved by using the :paramref:`_sa.create_engine.creator` parameter to provide a function that returns a new connection, along with setting :paramref:`_sa.create_engine.pool_class` to ``NullPool`` to disable SQLAlchemy's pooling:: import cx_Oracle from sqlalchemy import create_engine from sqlalchemy.pool import NullPool pool = cx_Oracle.SessionPool( user="scott", password="tiger", dsn="orclpdb", min=1, max=4, increment=1, threaded=True, encoding="UTF-8", nencoding="UTF-8", ) engine = create_engine( "oracle+cx_oracle://", creator=pool.acquire, poolclass=NullPool ) The above engine may then be used normally where cx_Oracle's pool handles connection pooling:: with engine.connect() as conn: print(conn.scalar("select 1 from dual")) As well as providing a scalable solution for multi-user applications, the cx_Oracle session pool supports some Oracle features such as DRCP and `Application Continuity <https://cx-oracle.readthedocs.io/en/latest/user_guide/ha.html#application-continuity-ac>`_. Note that the pool creation parameters ``threaded``, ``encoding`` and ``nencoding`` were deprecated in later cx_Oracle releases. Using Oracle Database Resident Connection Pooling (DRCP) -------------------------------------------------------- When using Oracle Database's DRCP, the best practice is to pass a connection class and "purity" when acquiring a connection from the SessionPool. Refer to the `cx_Oracle DRCP documentation <https://cx-oracle.readthedocs.io/en/latest/user_guide/connection_handling.html#database-resident-connection-pooling-drcp>`_. This can be achieved by wrapping ``pool.acquire()``:: import cx_Oracle from sqlalchemy import create_engine from sqlalchemy.pool import NullPool pool = cx_Oracle.SessionPool( user="scott", password="tiger", dsn="orclpdb", min=2, max=5, increment=1, threaded=True, encoding="UTF-8", nencoding="UTF-8", ) def creator(): return pool.acquire( cclass="MYCLASS", purity=cx_Oracle.ATTR_PURITY_SELF ) engine = create_engine( "oracle+cx_oracle://", creator=creator, poolclass=NullPool ) The above engine may then be used normally where cx_Oracle handles session pooling and Oracle Database additionally uses DRCP:: with engine.connect() as conn: print(conn.scalar("select 1 from dual")) .. _cx_oracle_unicode: Unicode ------- As is the case for all DBAPIs under Python 3, all strings are inherently Unicode strings. In all cases however, the driver requires an explicit encoding configuration. Ensuring the Correct Client Encoding ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The long accepted standard for establishing client encoding for nearly all Oracle Database related software is via the `NLS_LANG <https://www.oracle.com/database/technologies/faq-nls-lang.html>`_ environment variable. Older versions of cx_Oracle use this environment variable as the source of its encoding configuration. The format of this variable is Territory_Country.CharacterSet; a typical value would be ``AMERICAN_AMERICA.AL32UTF8``. cx_Oracle version 8 and later use the character set "UTF-8" by default, and ignore the character set component of NLS_LANG. The cx_Oracle driver also supported a programmatic alternative which is to pass the ``encoding`` and ``nencoding`` parameters directly to its ``.connect()`` function. These can be present in the URL as follows:: engine = create_engine( "oracle+cx_oracle://scott:tiger@tnsalias?encoding=UTF-8&nencoding=UTF-8" ) For the meaning of the ``encoding`` and ``nencoding`` parameters, please consult `Characters Sets and National Language Support (NLS) <https://cx-oracle.readthedocs.io/en/latest/user_guide/globalization.html#globalization>`_. .. seealso:: `Characters Sets and National Language Support (NLS) <https://cx-oracle.readthedocs.io/en/latest/user_guide/globalization.html#globalization>`_ - in the cx_Oracle documentation. Unicode-specific Column datatypes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The Core expression language handles unicode data by use of the :class:`.Unicode` and :class:`.UnicodeText` datatypes. These types correspond to the VARCHAR2 and CLOB Oracle Database datatypes by default. When using these datatypes with Unicode data, it is expected that the database is configured with a Unicode-aware character set, as well as that the ``NLS_LANG`` environment variable is set appropriately (this applies to older versions of cx_Oracle), so that the VARCHAR2 and CLOB datatypes can accommodate the data. In the case that Oracle Database is not configured with a Unicode character set, the two options are to use the :class:`_types.NCHAR` and :class:`_oracle.NCLOB` datatypes explicitly, or to pass the flag ``use_nchar_for_unicode=True`` to :func:`_sa.create_engine`, which will cause the SQLAlchemy dialect to use NCHAR/NCLOB for the :class:`.Unicode` / :class:`.UnicodeText` datatypes instead of VARCHAR/CLOB. .. versionchanged:: 1.3 The :class:`.Unicode` and :class:`.UnicodeText` datatypes now correspond to the ``VARCHAR2`` and ``CLOB`` Oracle Database datatypes unless the ``use_nchar_for_unicode=True`` is passed to the dialect when :func:`_sa.create_engine` is called. .. _cx_oracle_unicode_encoding_errors: Encoding Errors ^^^^^^^^^^^^^^^ For the unusual case that data in Oracle Database is present with a broken encoding, the dialect accepts a parameter ``encoding_errors`` which will be passed to Unicode decoding functions in order to affect how decoding errors are handled. The value is ultimately consumed by the Python `decode <https://docs.python.org/3/library/stdtypes.html#bytes.decode>`_ function, and is passed both via cx_Oracle's ``encodingErrors`` parameter consumed by ``Cursor.var()``, as well as SQLAlchemy's own decoding function, as the cx_Oracle dialect makes use of both under different circumstances. .. versionadded:: 1.3.11 .. _cx_oracle_setinputsizes: Fine grained control over cx_Oracle data binding performance with setinputsizes ------------------------------------------------------------------------------- The cx_Oracle DBAPI has a deep and fundamental reliance upon the usage of the DBAPI ``setinputsizes()`` call. The purpose of this call is to establish the datatypes that are bound to a SQL statement for Python values being passed as parameters. While virtually no other DBAPI assigns any use to the ``setinputsizes()`` call, the cx_Oracle DBAPI relies upon it heavily in its interactions with the Oracle Database client interface, and in some scenarios it is not possible for SQLAlchemy to know exactly how data should be bound, as some settings can cause profoundly different performance characteristics, while altering the type coercion behavior at the same time. Users of the cx_Oracle dialect are **strongly encouraged** to read through cx_Oracle's list of built-in datatype symbols at https://cx-oracle.readthedocs.io/en/latest/api_manual/module.html#database-types. Note that in some cases, significant performance degradation can occur when using these types vs. not, in particular when specifying ``cx_Oracle.CLOB``. On the SQLAlchemy side, the :meth:`.DialectEvents.do_setinputsizes` event can be used both for runtime visibility (e.g. logging) of the setinputsizes step as well as to fully control how ``setinputsizes()`` is used on a per-statement basis. .. versionadded:: 1.2.9 Added :meth:`.DialectEvents.setinputsizes` Example 1 - logging all setinputsizes calls ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The following example illustrates how to log the intermediary values from a SQLAlchemy perspective before they are converted to the raw ``setinputsizes()`` parameter dictionary. The keys of the dictionary are :class:`.BindParameter` objects which have a ``.key`` and a ``.type`` attribute:: from sqlalchemy import create_engine, event engine = create_engine("oracle+cx_oracle://scott:tiger@host/xe") @event.listens_for(engine, "do_setinputsizes") def _log_setinputsizes(inputsizes, cursor, statement, parameters, context): for bindparam, dbapitype in inputsizes.items(): log.info( "Bound parameter name: %s SQLAlchemy type: %r DBAPI object: %s", bindparam.key, bindparam.type, dbapitype, ) Example 2 - remove all bindings to CLOB ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``CLOB`` datatype in cx_Oracle incurs a significant performance overhead, however is set by default for the ``Text`` type within the SQLAlchemy 1.2 series. This setting can be modified as follows:: from sqlalchemy import create_engine, event from cx_Oracle import CLOB engine = create_engine("oracle+cx_oracle://scott:tiger@host/xe") @event.listens_for(engine, "do_setinputsizes") def _remove_clob(inputsizes, cursor, statement, parameters, context): for bindparam, dbapitype in list(inputsizes.items()): if dbapitype is CLOB: del inputsizes[bindparam] .. _cx_oracle_lob: LOB Datatypes -------------- LOB datatypes refer to the "large object" datatypes such as CLOB, NCLOB and BLOB. Modern versions of cx_Oracle is optimized for these datatypes to be delivered as a single buffer. As such, SQLAlchemy makes use of these newer type handlers by default. To disable the use of newer type handlers and deliver LOB objects as classic buffered objects with a ``read()`` method, the parameter ``auto_convert_lobs=False`` may be passed to :func:`_sa.create_engine`, which takes place only engine-wide. .. _cx_oracle_returning: RETURNING Support ----------------- The cx_Oracle dialect implements RETURNING using OUT parameters. The dialect supports RETURNING fully. Two Phase Transactions Not Supported ------------------------------------ Two phase transactions are **not supported** under cx_Oracle due to poor driver support. The newer :ref:`oracledb` dialect however **does** support two phase transactions. .. _cx_oracle_numeric: Precision Numerics ------------------ SQLAlchemy's numeric types can handle receiving and returning values as Python ``Decimal`` objects or float objects. When a :class:`.Numeric` object, or a subclass such as :class:`.Float`, :class:`_oracle.DOUBLE_PRECISION` etc. is in use, the :paramref:`.Numeric.asdecimal` flag determines if values should be coerced to ``Decimal`` upon return, or returned as float objects. To make matters more complicated under Oracle Database, the ``NUMBER`` type can also represent integer values if the "scale" is zero, so the Oracle Database-specific :class:`_oracle.NUMBER` type takes this into account as well. The cx_Oracle dialect makes extensive use of connection- and cursor-level "outputtypehandler" callables in order to coerce numeric values as requested. These callables are specific to the specific flavor of :class:`.Numeric` in use, as well as if no SQLAlchemy typing objects are present. There are observed scenarios where Oracle Database may send incomplete or ambiguous information about the numeric types being returned, such as a query where the numeric types are buried under multiple levels of subquery. The type handlers do their best to make the right decision in all cases, deferring to the underlying cx_Oracle DBAPI for all those cases where the driver can make the best decision. When no typing objects are present, as when executing plain SQL strings, a default "outputtypehandler" is present which will generally return numeric values which specify precision and scale as Python ``Decimal`` objects. To disable this coercion to decimal for performance reasons, pass the flag ``coerce_to_decimal=False`` to :func:`_sa.create_engine`:: engine = create_engine("oracle+cx_oracle://dsn", coerce_to_decimal=False) The ``coerce_to_decimal`` flag only impacts the results of plain string SQL statements that are not otherwise associated with a :class:`.Numeric` SQLAlchemy type (or a subclass of such). .. versionchanged:: 1.2 The numeric handling system for cx_Oracle has been reworked to take advantage of newer cx_Oracle features as well as better integration of outputtypehandlers. """ # noqa from __future__ import annotations import decimal import random import re from . import base as oracle from .base import OracleCompiler from .base import OracleDialect from .base import OracleExecutionContext from .types import _OracleDateLiteralRender from ... import exc from ... import util from ...engine import cursor as _cursor from ...engine import interfaces from ...engine import processors from ...sql import sqltypes from ...sql._typing import is_sql_compiler # source: # https://github.com/oracle/python-cx_Oracle/issues/596#issuecomment-999243649 _CX_ORACLE_MAGIC_LOB_SIZE = 131072 class _OracleInteger(sqltypes.Integer): def get_dbapi_type(self, dbapi): # see https://github.com/oracle/python-cx_Oracle/issues/ # 208#issuecomment-409715955 return int def _cx_oracle_var(self, dialect, cursor, arraysize=None): cx_Oracle = dialect.dbapi return cursor.var( cx_Oracle.STRING, 255, arraysize=arraysize if arraysize is not None else cursor.arraysize, outconverter=int, ) def _cx_oracle_outputtypehandler(self, dialect): def handler(cursor, name, default_type, size, precision, scale): return self._cx_oracle_var(dialect, cursor) return handler class _OracleNumeric(sqltypes.Numeric): is_number = False def bind_processor(self, dialect): if self.scale == 0: return None elif self.asdecimal: processor = processors.to_decimal_processor_factory( decimal.Decimal, self._effective_decimal_return_scale ) def process(value): if isinstance(value, (int, float)): return processor(value) elif value is not None and value.is_infinite(): return float(value) else: return value return process else: return processors.to_float def result_processor(self, dialect, coltype): return None def _cx_oracle_outputtypehandler(self, dialect): cx_Oracle = dialect.dbapi def handler(cursor, name, default_type, size, precision, scale): outconverter = None if precision: if self.asdecimal: if default_type == cx_Oracle.NATIVE_FLOAT: # receiving float and doing Decimal after the fact # allows for float("inf") to be handled type_ = default_type outconverter = decimal.Decimal else: type_ = decimal.Decimal else: if self.is_number and scale == 0: # integer. cx_Oracle is observed to handle the widest # variety of ints when no directives are passed, # from 5.2 to 7.0. See [ticket:4457] return None else: type_ = cx_Oracle.NATIVE_FLOAT else: if self.asdecimal: if default_type == cx_Oracle.NATIVE_FLOAT: type_ = default_type outconverter = decimal.Decimal else: type_ = decimal.Decimal else: if self.is_number and scale == 0: # integer. cx_Oracle is observed to handle the widest # variety of ints when no directives are passed, # from 5.2 to 7.0. See [ticket:4457] return None else: type_ = cx_Oracle.NATIVE_FLOAT return cursor.var( type_, 255, arraysize=cursor.arraysize, outconverter=outconverter, ) return handler class _OracleUUID(sqltypes.Uuid): def get_dbapi_type(self, dbapi): return dbapi.STRING class _OracleBinaryFloat(_OracleNumeric): def get_dbapi_type(self, dbapi): return dbapi.NATIVE_FLOAT class _OracleBINARY_FLOAT(_OracleBinaryFloat, oracle.BINARY_FLOAT): pass class _OracleBINARY_DOUBLE(_OracleBinaryFloat, oracle.BINARY_DOUBLE): pass class _OracleNUMBER(_OracleNumeric): is_number = True class _CXOracleDate(oracle._OracleDate): def bind_processor(self, dialect): return None def result_processor(self, dialect, coltype): def process(value): if value is not None: return value.date() else: return value return process class _CXOracleTIMESTAMP(_OracleDateLiteralRender, sqltypes.TIMESTAMP): def literal_processor(self, dialect): return self._literal_processor_datetime(dialect) class _LOBDataType: pass # TODO: the names used across CHAR / VARCHAR / NCHAR / NVARCHAR # here are inconsistent and not very good class _OracleChar(sqltypes.CHAR): def get_dbapi_type(self, dbapi): return dbapi.FIXED_CHAR class _OracleNChar(sqltypes.NCHAR): def get_dbapi_type(self, dbapi): return dbapi.FIXED_NCHAR class _OracleUnicodeStringNCHAR(oracle.NVARCHAR2): def get_dbapi_type(self, dbapi): return dbapi.NCHAR class _OracleUnicodeStringCHAR(sqltypes.Unicode): def get_dbapi_type(self, dbapi): return dbapi.LONG_STRING class _OracleUnicodeTextNCLOB(_LOBDataType, oracle.NCLOB): def get_dbapi_type(self, dbapi): # previously, this was dbapi.NCLOB. # DB_TYPE_NVARCHAR will instead be passed to setinputsizes() # when this datatype is used. return dbapi.DB_TYPE_NVARCHAR class _OracleUnicodeTextCLOB(_LOBDataType, sqltypes.UnicodeText): def get_dbapi_type(self, dbapi): # previously, this was dbapi.CLOB. # DB_TYPE_NVARCHAR will instead be passed to setinputsizes() # when this datatype is used. return dbapi.DB_TYPE_NVARCHAR class _OracleText(_LOBDataType, sqltypes.Text): def get_dbapi_type(self, dbapi): # previously, this was dbapi.CLOB. # DB_TYPE_NVARCHAR will instead be passed to setinputsizes() # when this datatype is used. return dbapi.DB_TYPE_NVARCHAR class _OracleLong(_LOBDataType, oracle.LONG): def get_dbapi_type(self, dbapi): return dbapi.LONG_STRING class _OracleString(sqltypes.String): pass class _OracleEnum(sqltypes.Enum): def bind_processor(self, dialect): enum_proc = sqltypes.Enum.bind_processor(self, dialect) def process(value): raw_str = enum_proc(value) return raw_str return process class _OracleBinary(_LOBDataType, sqltypes.LargeBinary): def get_dbapi_type(self, dbapi): # previously, this was dbapi.BLOB. # DB_TYPE_RAW will instead be passed to setinputsizes() # when this datatype is used. return dbapi.DB_TYPE_RAW def bind_processor(self, dialect): return None def result_processor(self, dialect, coltype): if not dialect.auto_convert_lobs: return None else: return super().result_processor(dialect, coltype) class _OracleInterval(oracle.INTERVAL): def get_dbapi_type(self, dbapi): return dbapi.INTERVAL class _OracleRaw(oracle.RAW): pass class _OracleRowid(oracle.ROWID): def get_dbapi_type(self, dbapi): return dbapi.ROWID class OracleCompiler_cx_oracle(OracleCompiler): _oracle_cx_sql_compiler = True _oracle_returning = False # Oracle bind names can't start with digits or underscores. # currently we rely upon Oracle-specific quoting of bind names in most # cases. however for expanding params, the escape chars are used. # see #8708 bindname_escape_characters = util.immutabledict( { "%": "P", "(": "A", ")": "Z", ":": "C", ".": "C", "[": "C", "]": "C", " ": "C", "\\": "C", "/": "C", "?": "C", } ) def bindparam_string(self, name, **kw): quote = getattr(name, "quote", None) if ( quote is True or quote is not False and self.preparer._bindparam_requires_quotes(name) # bind param quoting for Oracle doesn't work with post_compile # params. For those, the default bindparam_string will escape # special chars, and the appending of a number "_1" etc. will # take care of reserved words and not kw.get("post_compile", False) ): # interesting to note about expanding parameters - since the # new parameters take the form <paramname>_<int>, at least if # they are originally formed from reserved words, they no longer # need quoting :). names that include illegal characters # won't work however. quoted_name = '"%s"' % name kw["escaped_from"] = name name = quoted_name return OracleCompiler.bindparam_string(self, name, **kw) # TODO: we could likely do away with quoting altogether for # Oracle parameters and use the custom escaping here escaped_from = kw.get("escaped_from", None) if not escaped_from: if self._bind_translate_re.search(name): # not quite the translate use case as we want to # also get a quick boolean if we even found # unusual characters in the name new_name = self._bind_translate_re.sub( lambda m: self._bind_translate_chars[m.group(0)], name, ) if new_name[0].isdigit() or new_name[0] == "_": new_name = "D" + new_name kw["escaped_from"] = name name = new_name elif name[0].isdigit() or name[0] == "_": new_name = "D" + name kw["escaped_from"] = name name = new_name return OracleCompiler.bindparam_string(self, name, **kw) class OracleExecutionContext_cx_oracle(OracleExecutionContext): out_parameters = None def _generate_out_parameter_vars(self): # check for has_out_parameters or RETURNING, create cx_Oracle.var # objects if so if self.compiled.has_out_parameters or self.compiled._oracle_returning: out_parameters = self.out_parameters assert out_parameters is not None len_params = len(self.parameters) quoted_bind_names = self.compiled.escaped_bind_names for bindparam in self.compiled.binds.values(): if bindparam.isoutparam: name = self.compiled.bind_names[bindparam] type_impl = bindparam.type.dialect_impl(self.dialect) if hasattr(type_impl, "_cx_oracle_var"): out_parameters[name] = type_impl._cx_oracle_var( self.dialect, self.cursor, arraysize=len_params ) else: dbtype = type_impl.get_dbapi_type(self.dialect.dbapi) cx_Oracle = self.dialect.dbapi assert cx_Oracle is not None if dbtype is None: raise exc.InvalidRequestError( "Cannot create out parameter for " "parameter " "%r - its type %r is not supported by" " cx_oracle" % (bindparam.key, bindparam.type) ) # note this is an OUT parameter. Using # non-LOB datavalues with large unicode-holding # values causes the failure (both cx_Oracle and # oracledb): # ORA-22835: Buffer too small for CLOB to CHAR or # BLOB to RAW conversion (actual: 16507, # maximum: 4000) # [SQL: INSERT INTO long_text (x, y, z) VALUES # (:x, :y, :z) RETURNING long_text.x, long_text.y, # long_text.z INTO :ret_0, :ret_1, :ret_2] # so even for DB_TYPE_NVARCHAR we convert to a LOB if isinstance(type_impl, _LOBDataType): if dbtype == cx_Oracle.DB_TYPE_NVARCHAR: dbtype = cx_Oracle.NCLOB elif dbtype == cx_Oracle.DB_TYPE_RAW: dbtype = cx_Oracle.BLOB # other LOB types go in directly out_parameters[name] = self.cursor.var( dbtype, # this is fine also in oracledb_async since # the driver will await the read coroutine outconverter=lambda value: value.read(), arraysize=len_params, ) elif ( isinstance(type_impl, _OracleNumeric) and type_impl.asdecimal ): out_parameters[name] = self.cursor.var( decimal.Decimal, arraysize=len_params, ) else: out_parameters[name] = self.cursor.var( dbtype, arraysize=len_params ) for param in self.parameters: param[quoted_bind_names.get(name, name)] = ( out_parameters[name] ) def _generate_cursor_outputtype_handler(self): output_handlers = {} for keyname, name, objects, type_ in self.compiled._result_columns: handler = type_._cached_custom_processor( self.dialect, "cx_oracle_outputtypehandler", self._get_cx_oracle_type_handler, ) if handler: denormalized_name = self.dialect.denormalize_name(keyname) output_handlers[denormalized_name] = handler if output_handlers: default_handler = self._dbapi_connection.outputtypehandler def output_type_handler( cursor, name, default_type, size, precision, scale ): if name in output_handlers: return output_handlers[name]( cursor, name, default_type, size, precision, scale ) else: return default_handler( cursor, name, default_type, size, precision, scale ) self.cursor.outputtypehandler = output_type_handler def _get_cx_oracle_type_handler(self, impl): if hasattr(impl, "_cx_oracle_outputtypehandler"): return impl._cx_oracle_outputtypehandler(self.dialect) else: return None def pre_exec(self): super().pre_exec() if not getattr(self.compiled, "_oracle_cx_sql_compiler", False): return self.out_parameters = {} self._generate_out_parameter_vars() self._generate_cursor_outputtype_handler() def post_exec(self): if ( self.compiled and is_sql_compiler(self.compiled) and self.compiled._oracle_returning ): initial_buffer = self.fetchall_for_returning( self.cursor, _internal=True ) fetch_strategy = _cursor.FullyBufferedCursorFetchStrategy( self.cursor, [ (entry.keyname, None) for entry in self.compiled._result_columns ], initial_buffer=initial_buffer, ) self.cursor_fetch_strategy = fetch_strategy def create_cursor(self): c = self._dbapi_connection.cursor() if self.dialect.arraysize: c.arraysize = self.dialect.arraysize return c def fetchall_for_returning(self, cursor, *, _internal=False): compiled = self.compiled if ( not _internal and compiled is None or not is_sql_compiler(compiled) or not compiled._oracle_returning ): raise NotImplementedError( "execution context was not prepared for Oracle RETURNING" ) # create a fake cursor result from the out parameters. unlike # get_out_parameter_values(), the result-row handlers here will be # applied at the Result level numcols = len(self.out_parameters) # [stmt_result for stmt_result in outparam.values] == each # statement in executemany # [val for val in stmt_result] == each row for a particular # statement return list( zip( *[ [ val for stmt_result in self.out_parameters[ f"ret_{j}" ].values for val in (stmt_result or ()) ] for j in range(numcols) ] ) ) def get_out_parameter_values(self, out_param_names): # this method should not be called when the compiler has # RETURNING as we've turned the has_out_parameters flag set to # False. assert not self.compiled.returning return [ self.dialect._paramval(self.out_parameters[name]) for name in out_param_names ] class OracleDialect_cx_oracle(OracleDialect): supports_statement_cache = True execution_ctx_cls = OracleExecutionContext_cx_oracle statement_compiler = OracleCompiler_cx_oracle supports_sane_rowcount = True supports_sane_multi_rowcount = True insert_executemany_returning = True insert_executemany_returning_sort_by_parameter_order = True update_executemany_returning = True delete_executemany_returning = True bind_typing = interfaces.BindTyping.SETINPUTSIZES driver = "cx_oracle" colspecs = util.update_copy( OracleDialect.colspecs, { sqltypes.TIMESTAMP: _CXOracleTIMESTAMP, sqltypes.Numeric: _OracleNumeric, sqltypes.Float: _OracleNumeric, oracle.BINARY_FLOAT: _OracleBINARY_FLOAT, oracle.BINARY_DOUBLE: _OracleBINARY_DOUBLE, sqltypes.Integer: _OracleInteger, oracle.NUMBER: _OracleNUMBER, sqltypes.Date: _CXOracleDate, sqltypes.LargeBinary: _OracleBinary, sqltypes.Boolean: oracle._OracleBoolean, sqltypes.Interval: _OracleInterval, oracle.INTERVAL: _OracleInterval, sqltypes.Text: _OracleText, sqltypes.String: _OracleString, sqltypes.UnicodeText: _OracleUnicodeTextCLOB, sqltypes.CHAR: _OracleChar, sqltypes.NCHAR: _OracleNChar, sqltypes.Enum: _OracleEnum, oracle.LONG: _OracleLong, oracle.RAW: _OracleRaw, sqltypes.Unicode: _OracleUnicodeStringCHAR, sqltypes.NVARCHAR: _OracleUnicodeStringNCHAR, sqltypes.Uuid: _OracleUUID, oracle.NCLOB: _OracleUnicodeTextNCLOB, oracle.ROWID: _OracleRowid, }, ) execute_sequence_format = list _cx_oracle_threaded = None _cursor_var_unicode_kwargs = util.immutabledict() @util.deprecated_params( threaded=( "1.3", "The 'threaded' parameter to the cx_oracle/oracledb dialect " "is deprecated as a dialect-level argument, and will be removed " "in a future release. As of version 1.3, it defaults to False " "rather than True. The 'threaded' option can be passed to " "cx_Oracle directly in the URL query string passed to " ":func:`_sa.create_engine`.", ) ) def __init__( self, auto_convert_lobs=True, coerce_to_decimal=True, arraysize=None, encoding_errors=None, threaded=None, **kwargs, ): OracleDialect.__init__(self, **kwargs) self.arraysize = arraysize self.encoding_errors = encoding_errors if encoding_errors: self._cursor_var_unicode_kwargs = { "encodingErrors": encoding_errors } if threaded is not None: self._cx_oracle_threaded = threaded self.auto_convert_lobs = auto_convert_lobs self.coerce_to_decimal = coerce_to_decimal if self._use_nchar_for_unicode: self.colspecs = self.colspecs.copy() self.colspecs[sqltypes.Unicode] = _OracleUnicodeStringNCHAR self.colspecs[sqltypes.UnicodeText] = _OracleUnicodeTextNCLOB dbapi_module = self.dbapi self._load_version(dbapi_module) if dbapi_module is not None: # these constants will first be seen in SQLAlchemy datatypes # coming from the get_dbapi_type() method. We then # will place the following types into setinputsizes() calls # on each statement. Oracle constants that are not in this # list will not be put into setinputsizes(). self.include_set_input_sizes = { dbapi_module.DATETIME, dbapi_module.DB_TYPE_NVARCHAR, # used for CLOB, NCLOB dbapi_module.DB_TYPE_RAW, # used for BLOB dbapi_module.NCLOB, # not currently used except for OUT param dbapi_module.CLOB, # not currently used except for OUT param dbapi_module.LOB, # not currently used dbapi_module.BLOB, # not currently used except for OUT param dbapi_module.NCHAR, dbapi_module.FIXED_NCHAR, dbapi_module.FIXED_CHAR, dbapi_module.TIMESTAMP, int, # _OracleInteger, # _OracleBINARY_FLOAT, _OracleBINARY_DOUBLE, dbapi_module.NATIVE_FLOAT, } self._paramval = lambda value: value.getvalue() def _load_version(self, dbapi_module): version = (0, 0, 0) if dbapi_module is not None: m = re.match(r"(\d+)\.(\d+)(?:\.(\d+))?", dbapi_module.version) if m: version = tuple( int(x) for x in m.group(1, 2, 3) if x is not None ) self.cx_oracle_ver = version if self.cx_oracle_ver < (8,) and self.cx_oracle_ver > (0, 0, 0): raise exc.InvalidRequestError( "cx_Oracle version 8 and above are supported" ) @classmethod def import_dbapi(cls): import cx_Oracle return cx_Oracle def initialize(self, connection): super().initialize(connection) self._detect_decimal_char(connection) def get_isolation_level(self, dbapi_connection): # sources: # general idea of transaction id, have to start one, etc. # https://stackoverflow.com/questions/10711204/how-to-check-isoloation-level # how to decode xid cols from v$transaction to match # https://asktom.oracle.com/pls/apex/f?p=100:11:0::::P11_QUESTION_ID:9532779900346079444 # Oracle tuple comparison without using IN: # https://www.sql-workbench.eu/comparison/tuple_comparison.html with dbapi_connection.cursor() as cursor: # this is the only way to ensure a transaction is started without # actually running DML. There's no way to see the configured # isolation level without getting it from v$transaction which # means transaction has to be started. outval = cursor.var(str) cursor.execute( """ begin :trans_id := dbms_transaction.local_transaction_id( TRUE ); end; """, {"trans_id": outval}, ) trans_id = outval.getvalue() xidusn, xidslot, xidsqn = trans_id.split(".", 2) cursor.execute( "SELECT CASE BITAND(t.flag, POWER(2, 28)) " "WHEN 0 THEN 'READ COMMITTED' " "ELSE 'SERIALIZABLE' END AS isolation_level " "FROM v$transaction t WHERE " "(t.xidusn, t.xidslot, t.xidsqn) = " "((:xidusn, :xidslot, :xidsqn))", {"xidusn": xidusn, "xidslot": xidslot, "xidsqn": xidsqn}, ) row = cursor.fetchone() if row is None: raise exc.InvalidRequestError( "could not retrieve isolation level" ) result = row[0] return result def get_isolation_level_values(self, dbapi_connection): return super().get_isolation_level_values(dbapi_connection) + [ "AUTOCOMMIT" ] def set_isolation_level(self, dbapi_connection, level): if level == "AUTOCOMMIT": dbapi_connection.autocommit = True else: dbapi_connection.autocommit = False dbapi_connection.rollback() with dbapi_connection.cursor() as cursor: cursor.execute(f"ALTER SESSION SET ISOLATION_LEVEL={level}") def _detect_decimal_char(self, connection): # we have the option to change this setting upon connect, # or just look at what it is upon connect and convert. # to minimize the chance of interference with changes to # NLS_TERRITORY or formatting behavior of the DB, we opt # to just look at it dbapi_connection = connection.connection with dbapi_connection.cursor() as cursor: # issue #8744 # nls_session_parameters is not available in some Oracle # modes like "mount mode". But then, v$nls_parameters is not # available if the connection doesn't have SYSDBA priv. # # simplify the whole thing and just use the method that we were # doing in the test suite already, selecting a number def output_type_handler( cursor, name, defaultType, size, precision, scale ): return cursor.var( self.dbapi.STRING, 255, arraysize=cursor.arraysize ) cursor.outputtypehandler = output_type_handler cursor.execute("SELECT 1.1 FROM DUAL") value = cursor.fetchone()[0] decimal_char = value.lstrip("0")[1] assert not decimal_char[0].isdigit() self._decimal_char = decimal_char if self._decimal_char != ".": _detect_decimal = self._detect_decimal _to_decimal = self._to_decimal self._detect_decimal = lambda value: _detect_decimal( value.replace(self._decimal_char, ".") ) self._to_decimal = lambda value: _to_decimal( value.replace(self._decimal_char, ".") ) def _detect_decimal(self, value): if "." in value: return self._to_decimal(value) else: return int(value) _to_decimal = decimal.Decimal def _generate_connection_outputtype_handler(self): """establish the default outputtypehandler established at the connection level. """ dialect = self cx_Oracle = dialect.dbapi number_handler = _OracleNUMBER( asdecimal=True )._cx_oracle_outputtypehandler(dialect) float_handler = _OracleNUMBER( asdecimal=False )._cx_oracle_outputtypehandler(dialect) def output_type_handler( cursor, name, default_type, size, precision, scale ): if ( default_type == cx_Oracle.NUMBER and default_type is not cx_Oracle.NATIVE_FLOAT ): if not dialect.coerce_to_decimal: return None elif precision == 0 and scale in (0, -127): # ambiguous type, this occurs when selecting # numbers from deep subqueries return cursor.var( cx_Oracle.STRING, 255, outconverter=dialect._detect_decimal, arraysize=cursor.arraysize, ) elif precision and scale > 0: return number_handler( cursor, name, default_type, size, precision, scale ) else: return float_handler( cursor, name, default_type, size, precision, scale ) # if unicode options were specified, add a decoder, otherwise # cx_Oracle should return Unicode elif ( dialect._cursor_var_unicode_kwargs and default_type in ( cx_Oracle.STRING, cx_Oracle.FIXED_CHAR, ) and default_type is not cx_Oracle.CLOB and default_type is not cx_Oracle.NCLOB ): return cursor.var( str, size, cursor.arraysize, **dialect._cursor_var_unicode_kwargs, ) elif dialect.auto_convert_lobs and default_type in ( cx_Oracle.CLOB, cx_Oracle.NCLOB, ): typ = ( cx_Oracle.DB_TYPE_VARCHAR if default_type is cx_Oracle.CLOB else cx_Oracle.DB_TYPE_NVARCHAR ) return cursor.var( typ, _CX_ORACLE_MAGIC_LOB_SIZE, cursor.arraysize, **dialect._cursor_var_unicode_kwargs, ) elif dialect.auto_convert_lobs and default_type in ( cx_Oracle.BLOB, ): return cursor.var( cx_Oracle.DB_TYPE_RAW, _CX_ORACLE_MAGIC_LOB_SIZE, cursor.arraysize, ) return output_type_handler def on_connect(self): output_type_handler = self._generate_connection_outputtype_handler() def on_connect(conn): conn.outputtypehandler = output_type_handler return on_connect def create_connect_args(self, url): opts = dict(url.query) for opt in ("use_ansi", "auto_convert_lobs"): if opt in opts: util.warn_deprecated( f"{self.driver} dialect option {opt!r} should only be " "passed to create_engine directly, not within the URL " "string", version="1.3", ) util.coerce_kw_type(opts, opt, bool) setattr(self, opt, opts.pop(opt)) database = url.database service_name = opts.pop("service_name", None) if database or service_name: # if we have a database, then we have a remote host port = url.port if port: port = int(port) else: port = 1521 if database and service_name: raise exc.InvalidRequestError( '"service_name" option shouldn\'t ' 'be used with a "database" part of the url' ) if database: makedsn_kwargs = {"sid": database} if service_name: makedsn_kwargs = {"service_name": service_name} dsn = self.dbapi.makedsn(url.host, port, **makedsn_kwargs) else: # we have a local tnsname dsn = url.host if dsn is not None: opts["dsn"] = dsn if url.password is not None: opts["password"] = url.password if url.username is not None: opts["user"] = url.username if self._cx_oracle_threaded is not None: opts.setdefault("threaded", self._cx_oracle_threaded) def convert_cx_oracle_constant(value): if isinstance(value, str): try: int_val = int(value) except ValueError: value = value.upper() return getattr(self.dbapi, value) else: return int_val else: return value util.coerce_kw_type(opts, "mode", convert_cx_oracle_constant) util.coerce_kw_type(opts, "threaded", bool) util.coerce_kw_type(opts, "events", bool) util.coerce_kw_type(opts, "purity", convert_cx_oracle_constant) return ([], opts) def _get_server_version_info(self, connection): return tuple(int(x) for x in connection.connection.version.split(".")) def is_disconnect(self, e, connection, cursor): (error,) = e.args if isinstance( e, (self.dbapi.InterfaceError, self.dbapi.DatabaseError) ) and "not connected" in str(e): return True if hasattr(error, "code") and error.code in { 28, 3114, 3113, 3135, 1033, 2396, }: # ORA-00028: your session has been killed # ORA-03114: not connected to ORACLE # ORA-03113: end-of-file on communication channel # ORA-03135: connection lost contact # ORA-01033: ORACLE initialization or shutdown in progress # ORA-02396: exceeded maximum idle time, please connect again # TODO: Others ? return True if re.match(r"^(?:DPI-1010|DPI-1080|DPY-1001|DPY-4011)", str(e)): # DPI-1010: not connected # DPI-1080: connection was closed by ORA-3113 # python-oracledb's DPY-1001: not connected to database # python-oracledb's DPY-4011: the database or network closed the # connection # TODO: others? return True return False def create_xid(self): id_ = random.randint(0, 2**128) return (0x1234, "%032x" % id_, "%032x" % 9) def do_executemany(self, cursor, statement, parameters, context=None): if isinstance(parameters, tuple): parameters = list(parameters) cursor.executemany(statement, parameters) def do_begin_twophase(self, connection, xid): connection.connection.begin(*xid) connection.connection.info["cx_oracle_xid"] = xid def do_prepare_twophase(self, connection, xid): result = connection.connection.prepare() connection.info["cx_oracle_prepared"] = result def do_rollback_twophase( self, connection, xid, is_prepared=True, recover=False ): self.do_rollback(connection.connection) # TODO: need to end XA state here def do_commit_twophase( self, connection, xid, is_prepared=True, recover=False ): if not is_prepared: self.do_commit(connection.connection) else: if recover: raise NotImplementedError( "2pc recovery not implemented for cx_Oracle" ) oci_prepared = connection.info["cx_oracle_prepared"] if oci_prepared: self.do_commit(connection.connection) # TODO: need to end XA state here def do_set_input_sizes(self, cursor, list_of_tuples, context): if self.positional: # not usually used, here to support if someone is modifying # the dialect to use positional style cursor.setinputsizes( *[dbtype for key, dbtype, sqltype in list_of_tuples] ) else: collection = ( (key, dbtype) for key, dbtype, sqltype in list_of_tuples if dbtype ) cursor.setinputsizes(**{key: dbtype for key, dbtype in collection}) def do_recover_twophase(self, connection): raise NotImplementedError( "recover two phase query for cx_Oracle not implemented" ) dialect = OracleDialect_cx_oracle sqlalchemy/dialects/oracle/provision.py 0000755 00000020171 15125143220 0014344 0 ustar 00 # dialects/oracle/provision.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors from ... import create_engine from ... import exc from ... import inspect from ...engine import url as sa_url from ...testing.provision import configure_follower from ...testing.provision import create_db from ...testing.provision import drop_all_schema_objects_post_tables from ...testing.provision import drop_all_schema_objects_pre_tables from ...testing.provision import drop_db from ...testing.provision import follower_url_from_main from ...testing.provision import log from ...testing.provision import post_configure_engine from ...testing.provision import run_reap_dbs from ...testing.provision import set_default_schema_on_connection from ...testing.provision import stop_test_class_outside_fixtures from ...testing.provision import temp_table_keyword_args from ...testing.provision import update_db_opts @create_db.for_db("oracle") def _oracle_create_db(cfg, eng, ident): # NOTE: make sure you've run "ALTER DATABASE default tablespace users" or # similar, so that the default tablespace is not "system"; reflection will # fail otherwise with eng.begin() as conn: conn.exec_driver_sql("create user %s identified by xe" % ident) conn.exec_driver_sql("create user %s_ts1 identified by xe" % ident) conn.exec_driver_sql("create user %s_ts2 identified by xe" % ident) conn.exec_driver_sql("grant dba to %s" % (ident,)) conn.exec_driver_sql("grant unlimited tablespace to %s" % ident) conn.exec_driver_sql("grant unlimited tablespace to %s_ts1" % ident) conn.exec_driver_sql("grant unlimited tablespace to %s_ts2" % ident) # these are needed to create materialized views conn.exec_driver_sql("grant create table to %s" % ident) conn.exec_driver_sql("grant create table to %s_ts1" % ident) conn.exec_driver_sql("grant create table to %s_ts2" % ident) @configure_follower.for_db("oracle") def _oracle_configure_follower(config, ident): config.test_schema = "%s_ts1" % ident config.test_schema_2 = "%s_ts2" % ident def _ora_drop_ignore(conn, dbname): try: conn.exec_driver_sql("drop user %s cascade" % dbname) log.info("Reaped db: %s", dbname) return True except exc.DatabaseError as err: log.warning("couldn't drop db: %s", err) return False @drop_all_schema_objects_pre_tables.for_db("oracle") def _ora_drop_all_schema_objects_pre_tables(cfg, eng): _purge_recyclebin(eng) _purge_recyclebin(eng, cfg.test_schema) @drop_all_schema_objects_post_tables.for_db("oracle") def _ora_drop_all_schema_objects_post_tables(cfg, eng): with eng.begin() as conn: for syn in conn.dialect._get_synonyms(conn, None, None, None): conn.exec_driver_sql(f"drop synonym {syn['synonym_name']}") for syn in conn.dialect._get_synonyms( conn, cfg.test_schema, None, None ): conn.exec_driver_sql( f"drop synonym {cfg.test_schema}.{syn['synonym_name']}" ) for tmp_table in inspect(conn).get_temp_table_names(): conn.exec_driver_sql(f"drop table {tmp_table}") @drop_db.for_db("oracle") def _oracle_drop_db(cfg, eng, ident): with eng.begin() as conn: # cx_Oracle seems to occasionally leak open connections when a large # suite it run, even if we confirm we have zero references to # connection objects. # while there is a "kill session" command in Oracle Database, # it unfortunately does not release the connection sufficiently. _ora_drop_ignore(conn, ident) _ora_drop_ignore(conn, "%s_ts1" % ident) _ora_drop_ignore(conn, "%s_ts2" % ident) @stop_test_class_outside_fixtures.for_db("oracle") def _ora_stop_test_class_outside_fixtures(config, db, cls): try: _purge_recyclebin(db) except exc.DatabaseError as err: log.warning("purge recyclebin command failed: %s", err) # clear statement cache on all connections that were used # https://github.com/oracle/python-cx_Oracle/issues/519 for cx_oracle_conn in _all_conns: try: sc = cx_oracle_conn.stmtcachesize except db.dialect.dbapi.InterfaceError: # connection closed pass else: cx_oracle_conn.stmtcachesize = 0 cx_oracle_conn.stmtcachesize = sc _all_conns.clear() def _purge_recyclebin(eng, schema=None): with eng.begin() as conn: if schema is None: # run magic command to get rid of identity sequences # https://floo.bar/2019/11/29/drop-the-underlying-sequence-of-an-identity-column/ # noqa: E501 conn.exec_driver_sql("purge recyclebin") else: # per user: https://community.oracle.com/tech/developers/discussion/2255402/how-to-clear-dba-recyclebin-for-a-particular-user # noqa: E501 for owner, object_name, type_ in conn.exec_driver_sql( "select owner, object_name,type from " "dba_recyclebin where owner=:schema and type='TABLE'", {"schema": conn.dialect.denormalize_name(schema)}, ).all(): conn.exec_driver_sql(f'purge {type_} {owner}."{object_name}"') _all_conns = set() @post_configure_engine.for_db("oracle") def _oracle_post_configure_engine(url, engine, follower_ident): from sqlalchemy import event @event.listens_for(engine, "checkout") def checkout(dbapi_con, con_record, con_proxy): _all_conns.add(dbapi_con) @event.listens_for(engine, "checkin") def checkin(dbapi_connection, connection_record): # work around cx_Oracle issue: # https://github.com/oracle/python-cx_Oracle/issues/530 # invalidate oracle connections that had 2pc set up if "cx_oracle_xid" in connection_record.info: connection_record.invalidate() @run_reap_dbs.for_db("oracle") def _reap_oracle_dbs(url, idents): log.info("db reaper connecting to %r", url) eng = create_engine(url) with eng.begin() as conn: log.info("identifiers in file: %s", ", ".join(idents)) to_reap = conn.exec_driver_sql( "select u.username from all_users u where username " "like 'TEST_%' and not exists (select username " "from v$session where username=u.username)" ) all_names = {username.lower() for (username,) in to_reap} to_drop = set() for name in all_names: if name.endswith("_ts1") or name.endswith("_ts2"): continue elif name in idents: to_drop.add(name) if "%s_ts1" % name in all_names: to_drop.add("%s_ts1" % name) if "%s_ts2" % name in all_names: to_drop.add("%s_ts2" % name) dropped = total = 0 for total, username in enumerate(to_drop, 1): if _ora_drop_ignore(conn, username): dropped += 1 log.info( "Dropped %d out of %d stale databases detected", dropped, total ) @follower_url_from_main.for_db("oracle") def _oracle_follower_url_from_main(url, ident): url = sa_url.make_url(url) return url.set(username=ident, password="xe") @temp_table_keyword_args.for_db("oracle") def _oracle_temp_table_keyword_args(cfg, eng): return { "prefixes": ["GLOBAL TEMPORARY"], "oracle_on_commit": "PRESERVE ROWS", } @set_default_schema_on_connection.for_db("oracle") def _oracle_set_default_schema_on_connection( cfg, dbapi_connection, schema_name ): cursor = dbapi_connection.cursor() cursor.execute("ALTER SESSION SET CURRENT_SCHEMA=%s" % schema_name) cursor.close() @update_db_opts.for_db("oracle") def _update_db_opts(db_url, db_opts, options): """Set database options (db_opts) for a test database that we created.""" if ( options.oracledb_thick_mode and sa_url.make_url(db_url).get_driver_name() == "oracledb" ): db_opts["thick_mode"] = True sqlalchemy/dialects/oracle/oracledb.py 0000755 00000101753 15125143220 0014075 0 ustar 00 # dialects/oracle/oracledb.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors r""".. dialect:: oracle+oracledb :name: python-oracledb :dbapi: oracledb :connectstring: oracle+oracledb://user:pass@hostname:port[/dbname][?service_name=<service>[&key=value&key=value...]] :url: https://oracle.github.io/python-oracledb/ Description ----------- Python-oracledb is the Oracle Database driver for Python. It features a default "thin" client mode that requires no dependencies, and an optional "thick" mode that uses Oracle Client libraries. It supports SQLAlchemy features including two phase transactions and Asyncio. Python-oracle is the renamed, updated cx_Oracle driver. Oracle is no longer doing any releases in the cx_Oracle namespace. The SQLAlchemy ``oracledb`` dialect provides both a sync and an async implementation under the same dialect name. The proper version is selected depending on how the engine is created: * calling :func:`_sa.create_engine` with ``oracle+oracledb://...`` will automatically select the sync version:: from sqlalchemy import create_engine sync_engine = create_engine( "oracle+oracledb://scott:tiger@localhost?service_name=FREEPDB1" ) * calling :func:`_asyncio.create_async_engine` with ``oracle+oracledb://...`` will automatically select the async version:: from sqlalchemy.ext.asyncio import create_async_engine asyncio_engine = create_async_engine( "oracle+oracledb://scott:tiger@localhost?service_name=FREEPDB1" ) The asyncio version of the dialect may also be specified explicitly using the ``oracledb_async`` suffix:: from sqlalchemy.ext.asyncio import create_async_engine asyncio_engine = create_async_engine( "oracle+oracledb_async://scott:tiger@localhost?service_name=FREEPDB1" ) .. versionadded:: 2.0.25 added support for the async version of oracledb. Thick mode support ------------------ By default, the python-oracledb driver runs in a "thin" mode that does not require Oracle Client libraries to be installed. The driver also supports a "thick" mode that uses Oracle Client libraries to get functionality such as Oracle Application Continuity. To enable thick mode, call `oracledb.init_oracle_client() <https://python-oracledb.readthedocs.io/en/latest/api_manual/module.html#oracledb.init_oracle_client>`_ explicitly, or pass the parameter ``thick_mode=True`` to :func:`_sa.create_engine`. To pass custom arguments to ``init_oracle_client()``, like the ``lib_dir`` path, a dict may be passed, for example:: engine = sa.create_engine( "oracle+oracledb://...", thick_mode={ "lib_dir": "/path/to/oracle/client/lib", "config_dir": "/path/to/network_config_file_directory", "driver_name": "my-app : 1.0.0", }, ) Note that passing a ``lib_dir`` path should only be done on macOS or Windows. On Linux it does not behave as you might expect. .. seealso:: python-oracledb documentation `Enabling python-oracledb Thick mode <https://python-oracledb.readthedocs.io/en/latest/user_guide/initialization.html#enabling-python-oracledb-thick-mode>`_ Connecting to Oracle Database ----------------------------- python-oracledb provides several methods of indicating the target database. The dialect translates from a series of different URL forms. Given the hostname, port and service name of the target database, you can connect in SQLAlchemy using the ``service_name`` query string parameter:: engine = create_engine( "oracle+oracledb://scott:tiger@hostname:port?service_name=myservice" ) Connecting with Easy Connect strings ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ You can pass any valid python-oracledb connection string as the ``dsn`` key value in a :paramref:`_sa.create_engine.connect_args` dictionary. See python-oracledb documentation `Oracle Net Services Connection Strings <https://python-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#oracle-net-services-connection-strings>`_. For example to use an `Easy Connect string <https://download.oracle.com/ocomdocs/global/Oracle-Net-Easy-Connect-Plus.pdf>`_ with a timeout to prevent connection establishment from hanging if the network transport to the database cannot be establishd in 30 seconds, and also setting a keep-alive time of 60 seconds to stop idle network connections from being terminated by a firewall:: e = create_engine( "oracle+oracledb://@", connect_args={ "user": "scott", "password": "tiger", "dsn": "hostname:port/myservice?transport_connect_timeout=30&expire_time=60", }, ) The Easy Connect syntax has been enhanced during the life of Oracle Database. Review the documentation for your database version. The current documentation is at `Understanding the Easy Connect Naming Method <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-B0437826-43C1-49EC-A94D-B650B6A4A6EE>`_. The general syntax is similar to: .. sourcecode:: text [[protocol:]//]host[:port][/[service_name]][?parameter_name=value{¶meter_name=value}] Note that although the SQLAlchemy URL syntax ``hostname:port/dbname`` looks like Oracle's Easy Connect syntax, it is different. SQLAlchemy's URL requires a system identifier (SID) for the ``dbname`` component:: engine = create_engine("oracle+oracledb://scott:tiger@hostname:port/sid") Easy Connect syntax does not support SIDs. It uses services names, which are the preferred choice for connecting to Oracle Database. Passing python-oracledb connect arguments ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Other python-oracledb driver `connection options <https://python-oracledb.readthedocs.io/en/latest/api_manual/module.html#oracledb.connect>`_ can be passed in ``connect_args``. For example:: e = create_engine( "oracle+oracledb://@", connect_args={ "user": "scott", "password": "tiger", "dsn": "hostname:port/myservice", "events": True, "mode": oracledb.AUTH_MODE_SYSDBA, }, ) Connecting with tnsnames.ora TNS aliases ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If no port, database name, or service name is provided, the dialect will use an Oracle Database DSN "connection string". This takes the "hostname" portion of the URL as the data source name. For example, if the ``tnsnames.ora`` file contains a `TNS Alias <https://python-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#tns-aliases-for-connection-strings>`_ of ``myalias`` as below: .. sourcecode:: text myalias = (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = mymachine.example.com)(PORT = 1521)) (CONNECT_DATA = (SERVER = DEDICATED) (SERVICE_NAME = orclpdb1) ) ) The python-oracledb dialect connects to this database service when ``myalias`` is the hostname portion of the URL, without specifying a port, database name or ``service_name``:: engine = create_engine("oracle+oracledb://scott:tiger@myalias") Connecting to Oracle Autonomous Database ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Users of Oracle Autonomous Database should use either use the TNS Alias URL shown above, or pass the TNS Alias as the ``dsn`` key value in a :paramref:`_sa.create_engine.connect_args` dictionary. If Oracle Autonomous Database is configured for mutual TLS ("mTLS") connections, then additional configuration is required as shown in `Connecting to Oracle Cloud Autonomous Databases <https://python-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#connecting-to-oracle-cloud-autonomous-databases>`_. In summary, Thick mode users should configure file locations and set the wallet path in ``sqlnet.ora`` appropriately:: e = create_engine( "oracle+oracledb://@", thick_mode={ # directory containing tnsnames.ora and cwallet.so "config_dir": "/opt/oracle/wallet_dir", }, connect_args={ "user": "scott", "password": "tiger", "dsn": "mydb_high", }, ) Thin mode users of mTLS should pass the appropriate directories and PEM wallet password when creating the engine, similar to:: e = create_engine( "oracle+oracledb://@", connect_args={ "user": "scott", "password": "tiger", "dsn": "mydb_high", "config_dir": "/opt/oracle/wallet_dir", # directory containing tnsnames.ora "wallet_location": "/opt/oracle/wallet_dir", # directory containing ewallet.pem "wallet_password": "top secret", # password for the PEM file }, ) Typically ``config_dir`` and ``wallet_location`` are the same directory, which is where the Oracle Autonomous Database wallet zip file was extracted. Note this directory should be protected. Connection Pooling ------------------ Applications with multiple concurrent users should use connection pooling. A minimal sized connection pool is also beneficial for long-running, single-user applications that do not frequently use a connection. The python-oracledb driver provides its own connection pool implementation that may be used in place of SQLAlchemy's pooling functionality. The driver pool gives support for high availability features such as dead connection detection, connection draining for planned database downtime, support for Oracle Application Continuity and Transparent Application Continuity, and gives support for `Database Resident Connection Pooling (DRCP) <https://python-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#database-resident-connection-pooling-drcp>`_. To take advantage of python-oracledb's pool, use the :paramref:`_sa.create_engine.creator` parameter to provide a function that returns a new connection, along with setting :paramref:`_sa.create_engine.pool_class` to ``NullPool`` to disable SQLAlchemy's pooling:: import oracledb from sqlalchemy import create_engine from sqlalchemy import text from sqlalchemy.pool import NullPool # Uncomment to use the optional python-oracledb Thick mode. # Review the python-oracledb doc for the appropriate parameters # oracledb.init_oracle_client(<your parameters>) pool = oracledb.create_pool( user="scott", password="tiger", dsn="localhost:1521/freepdb1", min=1, max=4, increment=1, ) engine = create_engine( "oracle+oracledb://", creator=pool.acquire, poolclass=NullPool ) The above engine may then be used normally. Internally, python-oracledb handles connection pooling:: with engine.connect() as conn: print(conn.scalar(text("select 1 from dual"))) Refer to the python-oracledb documentation for `oracledb.create_pool() <https://python-oracledb.readthedocs.io/en/latest/api_manual/module.html#oracledb.create_pool>`_ for the arguments that can be used when creating a connection pool. .. _drcp: Using Oracle Database Resident Connection Pooling (DRCP) -------------------------------------------------------- When using Oracle Database's Database Resident Connection Pooling (DRCP), the best practice is to specify a connection class and "purity". Refer to the `python-oracledb documentation on DRCP <https://python-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#database-resident-connection-pooling-drcp>`_. For example:: import oracledb from sqlalchemy import create_engine from sqlalchemy import text from sqlalchemy.pool import NullPool # Uncomment to use the optional python-oracledb Thick mode. # Review the python-oracledb doc for the appropriate parameters # oracledb.init_oracle_client(<your parameters>) pool = oracledb.create_pool( user="scott", password="tiger", dsn="localhost:1521/freepdb1", min=1, max=4, increment=1, cclass="MYCLASS", purity=oracledb.PURITY_SELF, ) engine = create_engine( "oracle+oracledb://", creator=pool.acquire, poolclass=NullPool ) The above engine may then be used normally where python-oracledb handles application connection pooling and Oracle Database additionally uses DRCP:: with engine.connect() as conn: print(conn.scalar(text("select 1 from dual"))) If you wish to use different connection classes or purities for different connections, then wrap ``pool.acquire()``:: import oracledb from sqlalchemy import create_engine from sqlalchemy import text from sqlalchemy.pool import NullPool # Uncomment to use python-oracledb Thick mode. # Review the python-oracledb doc for the appropriate parameters # oracledb.init_oracle_client(<your parameters>) pool = oracledb.create_pool( user="scott", password="tiger", dsn="localhost:1521/freepdb1", min=1, max=4, increment=1, cclass="MYCLASS", purity=oracledb.PURITY_SELF, ) def creator(): return pool.acquire(cclass="MYOTHERCLASS", purity=oracledb.PURITY_NEW) engine = create_engine( "oracle+oracledb://", creator=creator, poolclass=NullPool ) Engine Options consumed by the SQLAlchemy oracledb dialect outside of the driver -------------------------------------------------------------------------------- There are also options that are consumed by the SQLAlchemy oracledb dialect itself. These options are always passed directly to :func:`_sa.create_engine`, such as:: e = create_engine("oracle+oracledb://user:pass@tnsalias", arraysize=500) The parameters accepted by the oracledb dialect are as follows: * ``arraysize`` - set the driver cursor.arraysize value. It defaults to ``None``, indicating that the driver default value of 100 should be used. This setting controls how many rows are buffered when fetching rows, and can have a significant effect on performance if increased for queries that return large numbers of rows. .. versionchanged:: 2.0.26 - changed the default value from 50 to None, to use the default value of the driver itself. * ``auto_convert_lobs`` - defaults to True; See :ref:`oracledb_lob`. * ``coerce_to_decimal`` - see :ref:`oracledb_numeric` for detail. * ``encoding_errors`` - see :ref:`oracledb_unicode_encoding_errors` for detail. .. _oracledb_unicode: Unicode ------- As is the case for all DBAPIs under Python 3, all strings are inherently Unicode strings. Ensuring the Correct Client Encoding ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In python-oracledb, the encoding used for all character data is "UTF-8". Unicode-specific Column datatypes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The Core expression language handles unicode data by use of the :class:`.Unicode` and :class:`.UnicodeText` datatypes. These types correspond to the VARCHAR2 and CLOB Oracle Database datatypes by default. When using these datatypes with Unicode data, it is expected that the database is configured with a Unicode-aware character set so that the VARCHAR2 and CLOB datatypes can accommodate the data. In the case that Oracle Database is not configured with a Unicode character set, the two options are to use the :class:`_types.NCHAR` and :class:`_oracle.NCLOB` datatypes explicitly, or to pass the flag ``use_nchar_for_unicode=True`` to :func:`_sa.create_engine`, which will cause the SQLAlchemy dialect to use NCHAR/NCLOB for the :class:`.Unicode` / :class:`.UnicodeText` datatypes instead of VARCHAR/CLOB. .. versionchanged:: 1.3 The :class:`.Unicode` and :class:`.UnicodeText` datatypes now correspond to the ``VARCHAR2`` and ``CLOB`` Oracle Database datatypes unless the ``use_nchar_for_unicode=True`` is passed to the dialect when :func:`_sa.create_engine` is called. .. _oracledb_unicode_encoding_errors: Encoding Errors ^^^^^^^^^^^^^^^ For the unusual case that data in Oracle Database is present with a broken encoding, the dialect accepts a parameter ``encoding_errors`` which will be passed to Unicode decoding functions in order to affect how decoding errors are handled. The value is ultimately consumed by the Python `decode <https://docs.python.org/3/library/stdtypes.html#bytes.decode>`_ function, and is passed both via python-oracledb's ``encodingErrors`` parameter consumed by ``Cursor.var()``, as well as SQLAlchemy's own decoding function, as the python-oracledb dialect makes use of both under different circumstances. .. versionadded:: 1.3.11 .. _oracledb_setinputsizes: Fine grained control over python-oracledb data binding with setinputsizes ------------------------------------------------------------------------- The python-oracle DBAPI has a deep and fundamental reliance upon the usage of the DBAPI ``setinputsizes()`` call. The purpose of this call is to establish the datatypes that are bound to a SQL statement for Python values being passed as parameters. While virtually no other DBAPI assigns any use to the ``setinputsizes()`` call, the python-oracledb DBAPI relies upon it heavily in its interactions with the Oracle Database, and in some scenarios it is not possible for SQLAlchemy to know exactly how data should be bound, as some settings can cause profoundly different performance characteristics, while altering the type coercion behavior at the same time. Users of the oracledb dialect are **strongly encouraged** to read through python-oracledb's list of built-in datatype symbols at `Database Types <https://python-oracledb.readthedocs.io/en/latest/api_manual/module.html#database-types>`_ Note that in some cases, significant performance degradation can occur when using these types vs. not. On the SQLAlchemy side, the :meth:`.DialectEvents.do_setinputsizes` event can be used both for runtime visibility (e.g. logging) of the setinputsizes step as well as to fully control how ``setinputsizes()`` is used on a per-statement basis. .. versionadded:: 1.2.9 Added :meth:`.DialectEvents.setinputsizes` Example 1 - logging all setinputsizes calls ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The following example illustrates how to log the intermediary values from a SQLAlchemy perspective before they are converted to the raw ``setinputsizes()`` parameter dictionary. The keys of the dictionary are :class:`.BindParameter` objects which have a ``.key`` and a ``.type`` attribute:: from sqlalchemy import create_engine, event engine = create_engine( "oracle+oracledb://scott:tiger@localhost:1521?service_name=freepdb1" ) @event.listens_for(engine, "do_setinputsizes") def _log_setinputsizes(inputsizes, cursor, statement, parameters, context): for bindparam, dbapitype in inputsizes.items(): log.info( "Bound parameter name: %s SQLAlchemy type: %r DBAPI object: %s", bindparam.key, bindparam.type, dbapitype, ) Example 2 - remove all bindings to CLOB ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For performance, fetching LOB datatypes from Oracle Database is set by default for the ``Text`` type within SQLAlchemy. This setting can be modified as follows:: from sqlalchemy import create_engine, event from oracledb import CLOB engine = create_engine( "oracle+oracledb://scott:tiger@localhost:1521?service_name=freepdb1" ) @event.listens_for(engine, "do_setinputsizes") def _remove_clob(inputsizes, cursor, statement, parameters, context): for bindparam, dbapitype in list(inputsizes.items()): if dbapitype is CLOB: del inputsizes[bindparam] .. _oracledb_lob: LOB Datatypes -------------- LOB datatypes refer to the "large object" datatypes such as CLOB, NCLOB and BLOB. Oracle Database can efficiently return these datatypes as a single buffer. SQLAlchemy makes use of type handlers to do this by default. To disable the use of the type handlers and deliver LOB objects as classic buffered objects with a ``read()`` method, the parameter ``auto_convert_lobs=False`` may be passed to :func:`_sa.create_engine`. .. _oracledb_returning: RETURNING Support ----------------- The oracledb dialect implements RETURNING using OUT parameters. The dialect supports RETURNING fully. Two Phase Transaction Support ----------------------------- Two phase transactions are fully supported with python-oracledb. (Thin mode requires python-oracledb 2.3). APIs for two phase transactions are provided at the Core level via :meth:`_engine.Connection.begin_twophase` and :paramref:`_orm.Session.twophase` for transparent ORM use. .. versionchanged:: 2.0.32 added support for two phase transactions .. _oracledb_numeric: Precision Numerics ------------------ SQLAlchemy's numeric types can handle receiving and returning values as Python ``Decimal`` objects or float objects. When a :class:`.Numeric` object, or a subclass such as :class:`.Float`, :class:`_oracle.DOUBLE_PRECISION` etc. is in use, the :paramref:`.Numeric.asdecimal` flag determines if values should be coerced to ``Decimal`` upon return, or returned as float objects. To make matters more complicated under Oracle Database, the ``NUMBER`` type can also represent integer values if the "scale" is zero, so the Oracle Database-specific :class:`_oracle.NUMBER` type takes this into account as well. The oracledb dialect makes extensive use of connection- and cursor-level "outputtypehandler" callables in order to coerce numeric values as requested. These callables are specific to the specific flavor of :class:`.Numeric` in use, as well as if no SQLAlchemy typing objects are present. There are observed scenarios where Oracle Database may send incomplete or ambiguous information about the numeric types being returned, such as a query where the numeric types are buried under multiple levels of subquery. The type handlers do their best to make the right decision in all cases, deferring to the underlying python-oracledb DBAPI for all those cases where the driver can make the best decision. When no typing objects are present, as when executing plain SQL strings, a default "outputtypehandler" is present which will generally return numeric values which specify precision and scale as Python ``Decimal`` objects. To disable this coercion to decimal for performance reasons, pass the flag ``coerce_to_decimal=False`` to :func:`_sa.create_engine`:: engine = create_engine( "oracle+oracledb://scott:tiger@tnsalias", coerce_to_decimal=False ) The ``coerce_to_decimal`` flag only impacts the results of plain string SQL statements that are not otherwise associated with a :class:`.Numeric` SQLAlchemy type (or a subclass of such). .. versionchanged:: 1.2 The numeric handling system for the oracle dialects has been reworked to take advantage of newer driver features as well as better integration of outputtypehandlers. .. versionadded:: 2.0.0 added support for the python-oracledb driver. """ # noqa from __future__ import annotations import collections import re from typing import Any from typing import TYPE_CHECKING from . import cx_oracle as _cx_oracle from ... import exc from ... import pool from ...connectors.asyncio import AsyncAdapt_dbapi_connection from ...connectors.asyncio import AsyncAdapt_dbapi_cursor from ...connectors.asyncio import AsyncAdapt_dbapi_ss_cursor from ...connectors.asyncio import AsyncAdaptFallback_dbapi_connection from ...engine import default from ...util import asbool from ...util import await_fallback from ...util import await_only if TYPE_CHECKING: from oracledb import AsyncConnection from oracledb import AsyncCursor class OracleExecutionContext_oracledb( _cx_oracle.OracleExecutionContext_cx_oracle ): pass class OracleDialect_oracledb(_cx_oracle.OracleDialect_cx_oracle): supports_statement_cache = True execution_ctx_cls = OracleExecutionContext_oracledb driver = "oracledb" _min_version = (1,) def __init__( self, auto_convert_lobs=True, coerce_to_decimal=True, arraysize=None, encoding_errors=None, thick_mode=None, **kwargs, ): super().__init__( auto_convert_lobs, coerce_to_decimal, arraysize, encoding_errors, **kwargs, ) if self.dbapi is not None and ( thick_mode or isinstance(thick_mode, dict) ): kw = thick_mode if isinstance(thick_mode, dict) else {} self.dbapi.init_oracle_client(**kw) @classmethod def import_dbapi(cls): import oracledb return oracledb @classmethod def is_thin_mode(cls, connection): return connection.connection.dbapi_connection.thin @classmethod def get_async_dialect_cls(cls, url): return OracleDialectAsync_oracledb def _load_version(self, dbapi_module): version = (0, 0, 0) if dbapi_module is not None: m = re.match(r"(\d+)\.(\d+)(?:\.(\d+))?", dbapi_module.version) if m: version = tuple( int(x) for x in m.group(1, 2, 3) if x is not None ) self.oracledb_ver = version if ( self.oracledb_ver > (0, 0, 0) and self.oracledb_ver < self._min_version ): raise exc.InvalidRequestError( f"oracledb version {self._min_version} and above are supported" ) def do_begin_twophase(self, connection, xid): conn_xis = connection.connection.xid(*xid) connection.connection.tpc_begin(conn_xis) connection.connection.info["oracledb_xid"] = conn_xis def do_prepare_twophase(self, connection, xid): should_commit = connection.connection.tpc_prepare() connection.info["oracledb_should_commit"] = should_commit def do_rollback_twophase( self, connection, xid, is_prepared=True, recover=False ): if recover: conn_xid = connection.connection.xid(*xid) else: conn_xid = None connection.connection.tpc_rollback(conn_xid) def do_commit_twophase( self, connection, xid, is_prepared=True, recover=False ): conn_xid = None if not is_prepared: should_commit = connection.connection.tpc_prepare() elif recover: conn_xid = connection.connection.xid(*xid) should_commit = True else: should_commit = connection.info["oracledb_should_commit"] if should_commit: connection.connection.tpc_commit(conn_xid) def do_recover_twophase(self, connection): return [ # oracledb seems to return bytes ( fi, gti.decode() if isinstance(gti, bytes) else gti, bq.decode() if isinstance(bq, bytes) else bq, ) for fi, gti, bq in connection.connection.tpc_recover() ] def _check_max_identifier_length(self, connection): if self.oracledb_ver >= (2, 5): max_len = connection.connection.max_identifier_length if max_len is not None: return max_len return super()._check_max_identifier_length(connection) class AsyncAdapt_oracledb_cursor(AsyncAdapt_dbapi_cursor): _cursor: AsyncCursor __slots__ = () @property def outputtypehandler(self): return self._cursor.outputtypehandler @outputtypehandler.setter def outputtypehandler(self, value): self._cursor.outputtypehandler = value def var(self, *args, **kwargs): return self._cursor.var(*args, **kwargs) def close(self): self._rows.clear() self._cursor.close() def setinputsizes(self, *args: Any, **kwargs: Any) -> Any: return self._cursor.setinputsizes(*args, **kwargs) def _aenter_cursor(self, cursor: AsyncCursor) -> AsyncCursor: try: return cursor.__enter__() except Exception as error: self._adapt_connection._handle_exception(error) async def _execute_async(self, operation, parameters): # override to not use mutex, oracledb already has a mutex if parameters is None: result = await self._cursor.execute(operation) else: result = await self._cursor.execute(operation, parameters) if self._cursor.description and not self.server_side: self._rows = collections.deque(await self._cursor.fetchall()) return result async def _executemany_async( self, operation, seq_of_parameters, ): # override to not use mutex, oracledb already has a mutex return await self._cursor.executemany(operation, seq_of_parameters) def __enter__(self): return self def __exit__(self, type_: Any, value: Any, traceback: Any) -> None: self.close() class AsyncAdapt_oracledb_ss_cursor( AsyncAdapt_dbapi_ss_cursor, AsyncAdapt_oracledb_cursor ): __slots__ = () def close(self) -> None: if self._cursor is not None: self._cursor.close() self._cursor = None # type: ignore class AsyncAdapt_oracledb_connection(AsyncAdapt_dbapi_connection): _connection: AsyncConnection __slots__ = () thin = True _cursor_cls = AsyncAdapt_oracledb_cursor _ss_cursor_cls = None @property def autocommit(self): return self._connection.autocommit @autocommit.setter def autocommit(self, value): self._connection.autocommit = value @property def outputtypehandler(self): return self._connection.outputtypehandler @outputtypehandler.setter def outputtypehandler(self, value): self._connection.outputtypehandler = value @property def version(self): return self._connection.version @property def stmtcachesize(self): return self._connection.stmtcachesize @stmtcachesize.setter def stmtcachesize(self, value): self._connection.stmtcachesize = value @property def max_identifier_length(self): return self._connection.max_identifier_length def cursor(self): return AsyncAdapt_oracledb_cursor(self) def ss_cursor(self): return AsyncAdapt_oracledb_ss_cursor(self) def xid(self, *args: Any, **kwargs: Any) -> Any: return self._connection.xid(*args, **kwargs) def tpc_begin(self, *args: Any, **kwargs: Any) -> Any: return self.await_(self._connection.tpc_begin(*args, **kwargs)) def tpc_commit(self, *args: Any, **kwargs: Any) -> Any: return self.await_(self._connection.tpc_commit(*args, **kwargs)) def tpc_prepare(self, *args: Any, **kwargs: Any) -> Any: return self.await_(self._connection.tpc_prepare(*args, **kwargs)) def tpc_recover(self, *args: Any, **kwargs: Any) -> Any: return self.await_(self._connection.tpc_recover(*args, **kwargs)) def tpc_rollback(self, *args: Any, **kwargs: Any) -> Any: return self.await_(self._connection.tpc_rollback(*args, **kwargs)) class AsyncAdaptFallback_oracledb_connection( AsyncAdaptFallback_dbapi_connection, AsyncAdapt_oracledb_connection ): __slots__ = () class OracledbAdaptDBAPI: def __init__(self, oracledb) -> None: self.oracledb = oracledb for k, v in self.oracledb.__dict__.items(): if k != "connect": self.__dict__[k] = v def connect(self, *arg, **kw): async_fallback = kw.pop("async_fallback", False) creator_fn = kw.pop("async_creator_fn", self.oracledb.connect_async) if asbool(async_fallback): return AsyncAdaptFallback_oracledb_connection( self, await_fallback(creator_fn(*arg, **kw)) ) else: return AsyncAdapt_oracledb_connection( self, await_only(creator_fn(*arg, **kw)) ) class OracleExecutionContextAsync_oracledb(OracleExecutionContext_oracledb): # restore default create cursor create_cursor = default.DefaultExecutionContext.create_cursor def create_default_cursor(self): # copy of OracleExecutionContext_cx_oracle.create_cursor c = self._dbapi_connection.cursor() if self.dialect.arraysize: c.arraysize = self.dialect.arraysize return c def create_server_side_cursor(self): c = self._dbapi_connection.ss_cursor() if self.dialect.arraysize: c.arraysize = self.dialect.arraysize return c class OracleDialectAsync_oracledb(OracleDialect_oracledb): is_async = True supports_server_side_cursors = True supports_statement_cache = True execution_ctx_cls = OracleExecutionContextAsync_oracledb _min_version = (2,) # thick_mode mode is not supported by asyncio, oracledb will raise @classmethod def import_dbapi(cls): import oracledb return OracledbAdaptDBAPI(oracledb) @classmethod def get_pool_class(cls, url): async_fallback = url.query.get("async_fallback", False) if asbool(async_fallback): return pool.FallbackAsyncAdaptedQueuePool else: return pool.AsyncAdaptedQueuePool def get_driver_connection(self, connection): return connection._connection dialect = OracleDialect_oracledb dialect_async = OracleDialectAsync_oracledb sqlalchemy/dialects/oracle/dictionary.py 0000755 00000046077 15125143220 0014476 0 ustar 00 # dialects/oracle/dictionary.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors from .types import DATE from .types import LONG from .types import NUMBER from .types import RAW from .types import VARCHAR2 from ... import Column from ... import MetaData from ... import Table from ... import table from ...sql.sqltypes import CHAR # constants DB_LINK_PLACEHOLDER = "__$sa_dblink$__" # tables dual = table("dual") dictionary_meta = MetaData() # NOTE: all the dictionary_meta are aliases because oracle does not like # using the full table@dblink for every column in query, and complains with # ORA-00960: ambiguous column naming in select list all_tables = Table( "all_tables" + DB_LINK_PLACEHOLDER, dictionary_meta, Column("owner", VARCHAR2(128), nullable=False), Column("table_name", VARCHAR2(128), nullable=False), Column("tablespace_name", VARCHAR2(30)), Column("cluster_name", VARCHAR2(128)), Column("iot_name", VARCHAR2(128)), Column("status", VARCHAR2(8)), Column("pct_free", NUMBER), Column("pct_used", NUMBER), Column("ini_trans", NUMBER), Column("max_trans", NUMBER), Column("initial_extent", NUMBER), Column("next_extent", NUMBER), Column("min_extents", NUMBER), Column("max_extents", NUMBER), Column("pct_increase", NUMBER), Column("freelists", NUMBER), Column("freelist_groups", NUMBER), Column("logging", VARCHAR2(3)), Column("backed_up", VARCHAR2(1)), Column("num_rows", NUMBER), Column("blocks", NUMBER), Column("empty_blocks", NUMBER), Column("avg_space", NUMBER), Column("chain_cnt", NUMBER), Column("avg_row_len", NUMBER), Column("avg_space_freelist_blocks", NUMBER), Column("num_freelist_blocks", NUMBER), Column("degree", VARCHAR2(10)), Column("instances", VARCHAR2(10)), Column("cache", VARCHAR2(5)), Column("table_lock", VARCHAR2(8)), Column("sample_size", NUMBER), Column("last_analyzed", DATE), Column("partitioned", VARCHAR2(3)), Column("iot_type", VARCHAR2(12)), Column("temporary", VARCHAR2(1)), Column("secondary", VARCHAR2(1)), Column("nested", VARCHAR2(3)), Column("buffer_pool", VARCHAR2(7)), Column("flash_cache", VARCHAR2(7)), Column("cell_flash_cache", VARCHAR2(7)), Column("row_movement", VARCHAR2(8)), Column("global_stats", VARCHAR2(3)), Column("user_stats", VARCHAR2(3)), Column("duration", VARCHAR2(15)), Column("skip_corrupt", VARCHAR2(8)), Column("monitoring", VARCHAR2(3)), Column("cluster_owner", VARCHAR2(128)), Column("dependencies", VARCHAR2(8)), Column("compression", VARCHAR2(8)), Column("compress_for", VARCHAR2(30)), Column("dropped", VARCHAR2(3)), Column("read_only", VARCHAR2(3)), Column("segment_created", VARCHAR2(3)), Column("result_cache", VARCHAR2(7)), Column("clustering", VARCHAR2(3)), Column("activity_tracking", VARCHAR2(23)), Column("dml_timestamp", VARCHAR2(25)), Column("has_identity", VARCHAR2(3)), Column("container_data", VARCHAR2(3)), Column("inmemory", VARCHAR2(8)), Column("inmemory_priority", VARCHAR2(8)), Column("inmemory_distribute", VARCHAR2(15)), Column("inmemory_compression", VARCHAR2(17)), Column("inmemory_duplicate", VARCHAR2(13)), Column("default_collation", VARCHAR2(100)), Column("duplicated", VARCHAR2(1)), Column("sharded", VARCHAR2(1)), Column("externally_sharded", VARCHAR2(1)), Column("externally_duplicated", VARCHAR2(1)), Column("external", VARCHAR2(3)), Column("hybrid", VARCHAR2(3)), Column("cellmemory", VARCHAR2(24)), Column("containers_default", VARCHAR2(3)), Column("container_map", VARCHAR2(3)), Column("extended_data_link", VARCHAR2(3)), Column("extended_data_link_map", VARCHAR2(3)), Column("inmemory_service", VARCHAR2(12)), Column("inmemory_service_name", VARCHAR2(1000)), Column("container_map_object", VARCHAR2(3)), Column("memoptimize_read", VARCHAR2(8)), Column("memoptimize_write", VARCHAR2(8)), Column("has_sensitive_column", VARCHAR2(3)), Column("admit_null", VARCHAR2(3)), Column("data_link_dml_enabled", VARCHAR2(3)), Column("logical_replication", VARCHAR2(8)), ).alias("a_tables") all_views = Table( "all_views" + DB_LINK_PLACEHOLDER, dictionary_meta, Column("owner", VARCHAR2(128), nullable=False), Column("view_name", VARCHAR2(128), nullable=False), Column("text_length", NUMBER), Column("text", LONG), Column("text_vc", VARCHAR2(4000)), Column("type_text_length", NUMBER), Column("type_text", VARCHAR2(4000)), Column("oid_text_length", NUMBER), Column("oid_text", VARCHAR2(4000)), Column("view_type_owner", VARCHAR2(128)), Column("view_type", VARCHAR2(128)), Column("superview_name", VARCHAR2(128)), Column("editioning_view", VARCHAR2(1)), Column("read_only", VARCHAR2(1)), Column("container_data", VARCHAR2(1)), Column("bequeath", VARCHAR2(12)), Column("origin_con_id", VARCHAR2(256)), Column("default_collation", VARCHAR2(100)), Column("containers_default", VARCHAR2(3)), Column("container_map", VARCHAR2(3)), Column("extended_data_link", VARCHAR2(3)), Column("extended_data_link_map", VARCHAR2(3)), Column("has_sensitive_column", VARCHAR2(3)), Column("admit_null", VARCHAR2(3)), Column("pdb_local_only", VARCHAR2(3)), ).alias("a_views") all_sequences = Table( "all_sequences" + DB_LINK_PLACEHOLDER, dictionary_meta, Column("sequence_owner", VARCHAR2(128), nullable=False), Column("sequence_name", VARCHAR2(128), nullable=False), Column("min_value", NUMBER), Column("max_value", NUMBER), Column("increment_by", NUMBER, nullable=False), Column("cycle_flag", VARCHAR2(1)), Column("order_flag", VARCHAR2(1)), Column("cache_size", NUMBER, nullable=False), Column("last_number", NUMBER, nullable=False), Column("scale_flag", VARCHAR2(1)), Column("extend_flag", VARCHAR2(1)), Column("sharded_flag", VARCHAR2(1)), Column("session_flag", VARCHAR2(1)), Column("keep_value", VARCHAR2(1)), ).alias("a_sequences") all_users = Table( "all_users" + DB_LINK_PLACEHOLDER, dictionary_meta, Column("username", VARCHAR2(128), nullable=False), Column("user_id", NUMBER, nullable=False), Column("created", DATE, nullable=False), Column("common", VARCHAR2(3)), Column("oracle_maintained", VARCHAR2(1)), Column("inherited", VARCHAR2(3)), Column("default_collation", VARCHAR2(100)), Column("implicit", VARCHAR2(3)), Column("all_shard", VARCHAR2(3)), Column("external_shard", VARCHAR2(3)), ).alias("a_users") all_mviews = Table( "all_mviews" + DB_LINK_PLACEHOLDER, dictionary_meta, Column("owner", VARCHAR2(128), nullable=False), Column("mview_name", VARCHAR2(128), nullable=False), Column("container_name", VARCHAR2(128), nullable=False), Column("query", LONG), Column("query_len", NUMBER(38)), Column("updatable", VARCHAR2(1)), Column("update_log", VARCHAR2(128)), Column("master_rollback_seg", VARCHAR2(128)), Column("master_link", VARCHAR2(128)), Column("rewrite_enabled", VARCHAR2(1)), Column("rewrite_capability", VARCHAR2(9)), Column("refresh_mode", VARCHAR2(6)), Column("refresh_method", VARCHAR2(8)), Column("build_mode", VARCHAR2(9)), Column("fast_refreshable", VARCHAR2(18)), Column("last_refresh_type", VARCHAR2(8)), Column("last_refresh_date", DATE), Column("last_refresh_end_time", DATE), Column("staleness", VARCHAR2(19)), Column("after_fast_refresh", VARCHAR2(19)), Column("unknown_prebuilt", VARCHAR2(1)), Column("unknown_plsql_func", VARCHAR2(1)), Column("unknown_external_table", VARCHAR2(1)), Column("unknown_consider_fresh", VARCHAR2(1)), Column("unknown_import", VARCHAR2(1)), Column("unknown_trusted_fd", VARCHAR2(1)), Column("compile_state", VARCHAR2(19)), Column("use_no_index", VARCHAR2(1)), Column("stale_since", DATE), Column("num_pct_tables", NUMBER), Column("num_fresh_pct_regions", NUMBER), Column("num_stale_pct_regions", NUMBER), Column("segment_created", VARCHAR2(3)), Column("evaluation_edition", VARCHAR2(128)), Column("unusable_before", VARCHAR2(128)), Column("unusable_beginning", VARCHAR2(128)), Column("default_collation", VARCHAR2(100)), Column("on_query_computation", VARCHAR2(1)), Column("auto", VARCHAR2(3)), ).alias("a_mviews") all_tab_identity_cols = Table( "all_tab_identity_cols" + DB_LINK_PLACEHOLDER, dictionary_meta, Column("owner", VARCHAR2(128), nullable=False), Column("table_name", VARCHAR2(128), nullable=False), Column("column_name", VARCHAR2(128), nullable=False), Column("generation_type", VARCHAR2(10)), Column("sequence_name", VARCHAR2(128), nullable=False), Column("identity_options", VARCHAR2(298)), ).alias("a_tab_identity_cols") all_tab_cols = Table( "all_tab_cols" + DB_LINK_PLACEHOLDER, dictionary_meta, Column("owner", VARCHAR2(128), nullable=False), Column("table_name", VARCHAR2(128), nullable=False), Column("column_name", VARCHAR2(128), nullable=False), Column("data_type", VARCHAR2(128)), Column("data_type_mod", VARCHAR2(3)), Column("data_type_owner", VARCHAR2(128)), Column("data_length", NUMBER, nullable=False), Column("data_precision", NUMBER), Column("data_scale", NUMBER), Column("nullable", VARCHAR2(1)), Column("column_id", NUMBER), Column("default_length", NUMBER), Column("data_default", LONG), Column("num_distinct", NUMBER), Column("low_value", RAW(1000)), Column("high_value", RAW(1000)), Column("density", NUMBER), Column("num_nulls", NUMBER), Column("num_buckets", NUMBER), Column("last_analyzed", DATE), Column("sample_size", NUMBER), Column("character_set_name", VARCHAR2(44)), Column("char_col_decl_length", NUMBER), Column("global_stats", VARCHAR2(3)), Column("user_stats", VARCHAR2(3)), Column("avg_col_len", NUMBER), Column("char_length", NUMBER), Column("char_used", VARCHAR2(1)), Column("v80_fmt_image", VARCHAR2(3)), Column("data_upgraded", VARCHAR2(3)), Column("hidden_column", VARCHAR2(3)), Column("virtual_column", VARCHAR2(3)), Column("segment_column_id", NUMBER), Column("internal_column_id", NUMBER, nullable=False), Column("histogram", VARCHAR2(15)), Column("qualified_col_name", VARCHAR2(4000)), Column("user_generated", VARCHAR2(3)), Column("default_on_null", VARCHAR2(3)), Column("identity_column", VARCHAR2(3)), Column("evaluation_edition", VARCHAR2(128)), Column("unusable_before", VARCHAR2(128)), Column("unusable_beginning", VARCHAR2(128)), Column("collation", VARCHAR2(100)), Column("collated_column_id", NUMBER), ).alias("a_tab_cols") all_tab_comments = Table( "all_tab_comments" + DB_LINK_PLACEHOLDER, dictionary_meta, Column("owner", VARCHAR2(128), nullable=False), Column("table_name", VARCHAR2(128), nullable=False), Column("table_type", VARCHAR2(11)), Column("comments", VARCHAR2(4000)), Column("origin_con_id", NUMBER), ).alias("a_tab_comments") all_col_comments = Table( "all_col_comments" + DB_LINK_PLACEHOLDER, dictionary_meta, Column("owner", VARCHAR2(128), nullable=False), Column("table_name", VARCHAR2(128), nullable=False), Column("column_name", VARCHAR2(128), nullable=False), Column("comments", VARCHAR2(4000)), Column("origin_con_id", NUMBER), ).alias("a_col_comments") all_mview_comments = Table( "all_mview_comments" + DB_LINK_PLACEHOLDER, dictionary_meta, Column("owner", VARCHAR2(128), nullable=False), Column("mview_name", VARCHAR2(128), nullable=False), Column("comments", VARCHAR2(4000)), ).alias("a_mview_comments") all_ind_columns = Table( "all_ind_columns" + DB_LINK_PLACEHOLDER, dictionary_meta, Column("index_owner", VARCHAR2(128), nullable=False), Column("index_name", VARCHAR2(128), nullable=False), Column("table_owner", VARCHAR2(128), nullable=False), Column("table_name", VARCHAR2(128), nullable=False), Column("column_name", VARCHAR2(4000)), Column("column_position", NUMBER, nullable=False), Column("column_length", NUMBER, nullable=False), Column("char_length", NUMBER), Column("descend", VARCHAR2(4)), Column("collated_column_id", NUMBER), ).alias("a_ind_columns") all_indexes = Table( "all_indexes" + DB_LINK_PLACEHOLDER, dictionary_meta, Column("owner", VARCHAR2(128), nullable=False), Column("index_name", VARCHAR2(128), nullable=False), Column("index_type", VARCHAR2(27)), Column("table_owner", VARCHAR2(128), nullable=False), Column("table_name", VARCHAR2(128), nullable=False), Column("table_type", CHAR(11)), Column("uniqueness", VARCHAR2(9)), Column("compression", VARCHAR2(13)), Column("prefix_length", NUMBER), Column("tablespace_name", VARCHAR2(30)), Column("ini_trans", NUMBER), Column("max_trans", NUMBER), Column("initial_extent", NUMBER), Column("next_extent", NUMBER), Column("min_extents", NUMBER), Column("max_extents", NUMBER), Column("pct_increase", NUMBER), Column("pct_threshold", NUMBER), Column("include_column", NUMBER), Column("freelists", NUMBER), Column("freelist_groups", NUMBER), Column("pct_free", NUMBER), Column("logging", VARCHAR2(3)), Column("blevel", NUMBER), Column("leaf_blocks", NUMBER), Column("distinct_keys", NUMBER), Column("avg_leaf_blocks_per_key", NUMBER), Column("avg_data_blocks_per_key", NUMBER), Column("clustering_factor", NUMBER), Column("status", VARCHAR2(8)), Column("num_rows", NUMBER), Column("sample_size", NUMBER), Column("last_analyzed", DATE), Column("degree", VARCHAR2(40)), Column("instances", VARCHAR2(40)), Column("partitioned", VARCHAR2(3)), Column("temporary", VARCHAR2(1)), Column("generated", VARCHAR2(1)), Column("secondary", VARCHAR2(1)), Column("buffer_pool", VARCHAR2(7)), Column("flash_cache", VARCHAR2(7)), Column("cell_flash_cache", VARCHAR2(7)), Column("user_stats", VARCHAR2(3)), Column("duration", VARCHAR2(15)), Column("pct_direct_access", NUMBER), Column("ityp_owner", VARCHAR2(128)), Column("ityp_name", VARCHAR2(128)), Column("parameters", VARCHAR2(1000)), Column("global_stats", VARCHAR2(3)), Column("domidx_status", VARCHAR2(12)), Column("domidx_opstatus", VARCHAR2(6)), Column("funcidx_status", VARCHAR2(8)), Column("join_index", VARCHAR2(3)), Column("iot_redundant_pkey_elim", VARCHAR2(3)), Column("dropped", VARCHAR2(3)), Column("visibility", VARCHAR2(9)), Column("domidx_management", VARCHAR2(14)), Column("segment_created", VARCHAR2(3)), Column("orphaned_entries", VARCHAR2(3)), Column("indexing", VARCHAR2(7)), Column("auto", VARCHAR2(3)), ).alias("a_indexes") all_ind_expressions = Table( "all_ind_expressions" + DB_LINK_PLACEHOLDER, dictionary_meta, Column("index_owner", VARCHAR2(128), nullable=False), Column("index_name", VARCHAR2(128), nullable=False), Column("table_owner", VARCHAR2(128), nullable=False), Column("table_name", VARCHAR2(128), nullable=False), Column("column_expression", LONG), Column("column_position", NUMBER, nullable=False), ).alias("a_ind_expressions") all_constraints = Table( "all_constraints" + DB_LINK_PLACEHOLDER, dictionary_meta, Column("owner", VARCHAR2(128)), Column("constraint_name", VARCHAR2(128)), Column("constraint_type", VARCHAR2(1)), Column("table_name", VARCHAR2(128)), Column("search_condition", LONG), Column("search_condition_vc", VARCHAR2(4000)), Column("r_owner", VARCHAR2(128)), Column("r_constraint_name", VARCHAR2(128)), Column("delete_rule", VARCHAR2(9)), Column("status", VARCHAR2(8)), Column("deferrable", VARCHAR2(14)), Column("deferred", VARCHAR2(9)), Column("validated", VARCHAR2(13)), Column("generated", VARCHAR2(14)), Column("bad", VARCHAR2(3)), Column("rely", VARCHAR2(4)), Column("last_change", DATE), Column("index_owner", VARCHAR2(128)), Column("index_name", VARCHAR2(128)), Column("invalid", VARCHAR2(7)), Column("view_related", VARCHAR2(14)), Column("origin_con_id", VARCHAR2(256)), ).alias("a_constraints") all_cons_columns = Table( "all_cons_columns" + DB_LINK_PLACEHOLDER, dictionary_meta, Column("owner", VARCHAR2(128), nullable=False), Column("constraint_name", VARCHAR2(128), nullable=False), Column("table_name", VARCHAR2(128), nullable=False), Column("column_name", VARCHAR2(4000)), Column("position", NUMBER), ).alias("a_cons_columns") # TODO figure out if it's still relevant, since there is no mention from here # https://docs.oracle.com/en/database/oracle/oracle-database/21/refrn/ALL_DB_LINKS.html # original note: # using user_db_links here since all_db_links appears # to have more restricted permissions. # https://docs.oracle.com/cd/B28359_01/server.111/b28310/ds_admin005.htm # will need to hear from more users if we are doing # the right thing here. See [ticket:2619] all_db_links = Table( "all_db_links" + DB_LINK_PLACEHOLDER, dictionary_meta, Column("owner", VARCHAR2(128), nullable=False), Column("db_link", VARCHAR2(128), nullable=False), Column("username", VARCHAR2(128)), Column("host", VARCHAR2(2000)), Column("created", DATE, nullable=False), Column("hidden", VARCHAR2(3)), Column("shard_internal", VARCHAR2(3)), Column("valid", VARCHAR2(3)), Column("intra_cdb", VARCHAR2(3)), ).alias("a_db_links") all_synonyms = Table( "all_synonyms" + DB_LINK_PLACEHOLDER, dictionary_meta, Column("owner", VARCHAR2(128)), Column("synonym_name", VARCHAR2(128)), Column("table_owner", VARCHAR2(128)), Column("table_name", VARCHAR2(128)), Column("db_link", VARCHAR2(128)), Column("origin_con_id", VARCHAR2(256)), ).alias("a_synonyms") all_objects = Table( "all_objects" + DB_LINK_PLACEHOLDER, dictionary_meta, Column("owner", VARCHAR2(128), nullable=False), Column("object_name", VARCHAR2(128), nullable=False), Column("subobject_name", VARCHAR2(128)), Column("object_id", NUMBER, nullable=False), Column("data_object_id", NUMBER), Column("object_type", VARCHAR2(23)), Column("created", DATE, nullable=False), Column("last_ddl_time", DATE, nullable=False), Column("timestamp", VARCHAR2(19)), Column("status", VARCHAR2(7)), Column("temporary", VARCHAR2(1)), Column("generated", VARCHAR2(1)), Column("secondary", VARCHAR2(1)), Column("namespace", NUMBER, nullable=False), Column("edition_name", VARCHAR2(128)), Column("sharing", VARCHAR2(13)), Column("editionable", VARCHAR2(1)), Column("oracle_maintained", VARCHAR2(1)), Column("application", VARCHAR2(1)), Column("default_collation", VARCHAR2(100)), Column("duplicated", VARCHAR2(1)), Column("sharded", VARCHAR2(1)), Column("created_appid", NUMBER), Column("created_vsnid", NUMBER), Column("modified_appid", NUMBER), Column("modified_vsnid", NUMBER), ).alias("a_objects") sqlalchemy/dialects/oracle/vector.py 0000755 00000017265 15125143220 0013630 0 ustar 00 # dialects/oracle/vector.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors from __future__ import annotations import array from dataclasses import dataclass from enum import Enum from typing import Optional import sqlalchemy.types as types from sqlalchemy.types import Float class VectorIndexType(Enum): """Enum representing different types of VECTOR index structures. See :ref:`oracle_vector_datatype` for background. .. versionadded:: 2.0.41 """ HNSW = "HNSW" """ The HNSW (Hierarchical Navigable Small World) index type. """ IVF = "IVF" """ The IVF (Inverted File Index) index type """ class VectorDistanceType(Enum): """Enum representing different types of vector distance metrics. See :ref:`oracle_vector_datatype` for background. .. versionadded:: 2.0.41 """ EUCLIDEAN = "EUCLIDEAN" """Euclidean distance (L2 norm). Measures the straight-line distance between two vectors in space. """ DOT = "DOT" """Dot product similarity. Measures the algebraic similarity between two vectors. """ COSINE = "COSINE" """Cosine similarity. Measures the cosine of the angle between two vectors. """ MANHATTAN = "MANHATTAN" """Manhattan distance (L1 norm). Calculates the sum of absolute differences across dimensions. """ class VectorStorageFormat(Enum): """Enum representing the data format used to store vector components. See :ref:`oracle_vector_datatype` for background. .. versionadded:: 2.0.41 """ INT8 = "INT8" """ 8-bit integer format. """ BINARY = "BINARY" """ Binary format. """ FLOAT32 = "FLOAT32" """ 32-bit floating-point format. """ FLOAT64 = "FLOAT64" """ 64-bit floating-point format. """ @dataclass class VectorIndexConfig: """Define the configuration for Oracle VECTOR Index. See :ref:`oracle_vector_datatype` for background. .. versionadded:: 2.0.41 :param index_type: Enum value from :class:`.VectorIndexType` Specifies the indexing method. For HNSW, this must be :attr:`.VectorIndexType.HNSW`. :param distance: Enum value from :class:`.VectorDistanceType` specifies the metric for calculating distance between VECTORS. :param accuracy: interger. Should be in the range 0 to 100 Specifies the accuracy of the nearest neighbor search during query execution. :param parallel: integer. Specifies degree of parallelism. :param hnsw_neighbors: interger. Should be in the range 0 to 2048. Specifies the number of nearest neighbors considered during the search. The attribute :attr:`.VectorIndexConfig.hnsw_neighbors` is HNSW index specific. :param hnsw_efconstruction: integer. Should be in the range 0 to 65535. Controls the trade-off between indexing speed and recall quality during index construction. The attribute :attr:`.VectorIndexConfig.hnsw_efconstruction` is HNSW index specific. :param ivf_neighbor_partitions: integer. Should be in the range 0 to 10,000,000. Specifies the number of partitions used to divide the dataset. The attribute :attr:`.VectorIndexConfig.ivf_neighbor_partitions` is IVF index specific. :param ivf_sample_per_partition: integer. Should be between 1 and ``num_vectors / neighbor partitions``. Specifies the number of samples used per partition. The attribute :attr:`.VectorIndexConfig.ivf_sample_per_partition` is IVF index specific. :param ivf_min_vectors_per_partition: integer. From 0 (no trimming) to the total number of vectors (results in 1 partition). Specifies the minimum number of vectors per partition. The attribute :attr:`.VectorIndexConfig.ivf_min_vectors_per_partition` is IVF index specific. """ index_type: VectorIndexType = VectorIndexType.HNSW distance: Optional[VectorDistanceType] = None accuracy: Optional[int] = None hnsw_neighbors: Optional[int] = None hnsw_efconstruction: Optional[int] = None ivf_neighbor_partitions: Optional[int] = None ivf_sample_per_partition: Optional[int] = None ivf_min_vectors_per_partition: Optional[int] = None parallel: Optional[int] = None def __post_init__(self): self.index_type = VectorIndexType(self.index_type) for field in [ "hnsw_neighbors", "hnsw_efconstruction", "ivf_neighbor_partitions", "ivf_sample_per_partition", "ivf_min_vectors_per_partition", "parallel", "accuracy", ]: value = getattr(self, field) if value is not None and not isinstance(value, int): raise TypeError( f"{field} must be an integer if" f"provided, got {type(value).__name__}" ) class VECTOR(types.TypeEngine): """Oracle VECTOR datatype. For complete background on using this type, see :ref:`oracle_vector_datatype`. .. versionadded:: 2.0.41 """ cache_ok = True __visit_name__ = "VECTOR" _typecode_map = { VectorStorageFormat.INT8: "b", # Signed int VectorStorageFormat.BINARY: "B", # Unsigned int VectorStorageFormat.FLOAT32: "f", # Float VectorStorageFormat.FLOAT64: "d", # Double } def __init__(self, dim=None, storage_format=None): """Construct a VECTOR. :param dim: integer. The dimension of the VECTOR datatype. This should be an integer value. :param storage_format: VectorStorageFormat. The VECTOR storage type format. This may be Enum values form :class:`.VectorStorageFormat` INT8, BINARY, FLOAT32, or FLOAT64. """ if dim is not None and not isinstance(dim, int): raise TypeError("dim must be an interger") if storage_format is not None and not isinstance( storage_format, VectorStorageFormat ): raise TypeError( "storage_format must be an enum of type VectorStorageFormat" ) self.dim = dim self.storage_format = storage_format def _cached_bind_processor(self, dialect): """ Convert a list to a array.array before binding it to the database. """ def process(value): if value is None or isinstance(value, array.array): return value # Convert list to a array.array elif isinstance(value, list): typecode = self._array_typecode(self.storage_format) value = array.array(typecode, value) return value else: raise TypeError("VECTOR accepts list or array.array()") return process def _cached_result_processor(self, dialect, coltype): """ Convert a array.array to list before binding it to the database. """ def process(value): if isinstance(value, array.array): return list(value) return process def _array_typecode(self, typecode): """ Map storage format to array typecode. """ return self._typecode_map.get(typecode, "d") class comparator_factory(types.TypeEngine.Comparator): def l2_distance(self, other): return self.op("<->", return_type=Float)(other) def inner_product(self, other): return self.op("<#>", return_type=Float)(other) def cosine_distance(self, other): return self.op("<=>", return_type=Float)(other) sqlalchemy/dialects/oracle/__init__.py 0000755 00000003366 15125143220 0014062 0 ustar 00 # dialects/oracle/__init__.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors from types import ModuleType from . import base # noqa from . import cx_oracle # noqa from . import oracledb # noqa from .base import BFILE from .base import BINARY_DOUBLE from .base import BINARY_FLOAT from .base import BLOB from .base import CHAR from .base import CLOB from .base import DATE from .base import DOUBLE_PRECISION from .base import FLOAT from .base import INTERVAL from .base import LONG from .base import NCHAR from .base import NCLOB from .base import NUMBER from .base import NVARCHAR from .base import NVARCHAR2 from .base import RAW from .base import REAL from .base import ROWID from .base import TIMESTAMP from .base import VARCHAR from .base import VARCHAR2 from .base import VECTOR from .base import VectorIndexConfig from .base import VectorIndexType from .vector import VectorDistanceType from .vector import VectorStorageFormat # Alias oracledb also as oracledb_async oracledb_async = type( "oracledb_async", (ModuleType,), {"dialect": oracledb.dialect_async} ) base.dialect = dialect = cx_oracle.dialect __all__ = ( "VARCHAR", "NVARCHAR", "CHAR", "NCHAR", "DATE", "NUMBER", "BLOB", "BFILE", "CLOB", "NCLOB", "TIMESTAMP", "RAW", "FLOAT", "DOUBLE_PRECISION", "BINARY_DOUBLE", "BINARY_FLOAT", "LONG", "dialect", "INTERVAL", "VARCHAR2", "NVARCHAR2", "ROWID", "REAL", "VECTOR", "VectorDistanceType", "VectorIndexType", "VectorIndexConfig", "VectorStorageFormat", ) sqlalchemy/dialects/type_migration_guidelines.txt 0000644 00000020057 15125143220 0016500 0 ustar 00 Rules for Migrating TypeEngine classes to 0.6 --------------------------------------------- 1. the TypeEngine classes are used for: a. Specifying behavior which needs to occur for bind parameters or result row columns. b. Specifying types that are entirely specific to the database in use and have no analogue in the sqlalchemy.types package. c. Specifying types where there is an analogue in sqlalchemy.types, but the database in use takes vendor-specific flags for those types. d. If a TypeEngine class doesn't provide any of this, it should be *removed* from the dialect. 2. the TypeEngine classes are *no longer* used for generating DDL. Dialects now have a TypeCompiler subclass which uses the same visit_XXX model as other compilers. 3. the "ischema_names" and "colspecs" dictionaries are now required members on the Dialect class. 4. The names of types within dialects are now important. If a dialect-specific type is a subclass of an existing generic type and is only provided for bind/result behavior, the current mixed case naming can remain, i.e. _PGNumeric for Numeric - in this case, end users would never need to use _PGNumeric directly. However, if a dialect-specific type is specifying a type *or* arguments that are not present generically, it should match the real name of the type on that backend, in uppercase. E.g. postgresql.INET, mysql.ENUM, postgresql.ARRAY. Or follow this handy flowchart: is the type meant to provide bind/result is the type the same name as an behavior to a generic type (i.e. MixedCase) ---- no ---> UPPERCASE type in types.py ? type in types.py ? | | | no yes yes | | | | does your type need special | +<--- yes --- behavior or arguments ? | | | | | no name the type using | | _MixedCase, i.e. v V _OracleBoolean. it name the type don't make a stays private to the dialect identically as that type, make sure the dialect's and is invoked *only* via within the DB, base.py imports the types.py the colspecs dict. using UPPERCASE UPPERCASE name into its namespace | (i.e. BIT, NCHAR, INTERVAL). | Users can import it. | | v v subclass the closest is the name of this type MixedCase type types.py, identical to an UPPERCASE i.e. <--- no ------- name in types.py ? class _DateTime(types.DateTime), class DATETIME2(types.DateTime), | class BIT(types.TypeEngine). yes | v the type should subclass the UPPERCASE type in types.py (i.e. class BLOB(types.BLOB)) Example 1. pysqlite needs bind/result processing for the DateTime type in types.py, which applies to all DateTimes and subclasses. It's named _SLDateTime and subclasses types.DateTime. Example 2. MS-SQL has a TIME type which takes a non-standard "precision" argument that is rendered within DDL. So it's named TIME in the MS-SQL dialect's base.py, and subclasses types.TIME. Users can then say mssql.TIME(precision=10). Example 3. MS-SQL dialects also need special bind/result processing for date But its DATE type doesn't render DDL differently than that of a plain DATE, i.e. it takes no special arguments. Therefore we are just adding behavior to types.Date, so it's named _MSDate in the MS-SQL dialect's base.py, and subclasses types.Date. Example 4. MySQL has a SET type, there's no analogue for this in types.py. So MySQL names it SET in the dialect's base.py, and it subclasses types.String, since it ultimately deals with strings. Example 5. PostgreSQL has a DATETIME type. The DBAPIs handle dates correctly, and no special arguments are used in PG's DDL beyond what types.py provides. PostgreSQL dialect therefore imports types.DATETIME into its base.py. Ideally one should be able to specify a schema using names imported completely from a dialect, all matching the real name on that backend: from sqlalchemy.dialects.postgresql import base as pg t = Table('mytable', metadata, Column('id', pg.INTEGER, primary_key=True), Column('name', pg.VARCHAR(300)), Column('inetaddr', pg.INET) ) where above, the INTEGER and VARCHAR types are ultimately from sqlalchemy.types, but the PG dialect makes them available in its own namespace. 5. "colspecs" now is a dictionary of generic or uppercased types from sqlalchemy.types linked to types specified in the dialect. Again, if a type in the dialect does not specify any special behavior for bind_processor() or result_processor() and does not indicate a special type only available in this database, it must be *removed* from the module and from this dictionary. 6. "ischema_names" indicates string descriptions of types as returned from the database linked to TypeEngine classes. a. The string name should be matched to the most specific type possible within sqlalchemy.types, unless there is no matching type within sqlalchemy.types in which case it points to a dialect type. *It doesn't matter* if the dialect has its own subclass of that type with special bind/result behavior - reflect to the types.py UPPERCASE type as much as possible. With very few exceptions, all types should reflect to an UPPERCASE type. b. If the dialect contains a matching dialect-specific type that takes extra arguments which the generic one does not, then point to the dialect-specific type. E.g. mssql.VARCHAR takes a "collation" parameter which should be preserved. 5. DDL, or what was formerly issued by "get_col_spec()", is now handled exclusively by a subclass of compiler.GenericTypeCompiler. a. your TypeCompiler class will receive generic and uppercase types from sqlalchemy.types. Do not assume the presence of dialect-specific attributes on these types. b. the visit_UPPERCASE methods on GenericTypeCompiler should *not* be overridden with methods that produce a different DDL name. Uppercase types don't do any kind of "guessing" - if visit_TIMESTAMP is called, the DDL should render as TIMESTAMP in all cases, regardless of whether or not that type is legal on the backend database. c. the visit_UPPERCASE methods *should* be overridden with methods that add additional arguments and flags to those types. d. the visit_lowercase methods are overridden to provide an interpretation of a generic type. E.g. visit_large_binary() might be overridden to say "return self.visit_BIT(type_)". e. visit_lowercase methods should *never* render strings directly - it should always be via calling a visit_UPPERCASE() method. sqlalchemy/dialects/mysql/cymysql.py 0000755 00000004374 15125143220 0013724 0 ustar 00 # dialects/mysql/cymysql.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors r""" .. dialect:: mysql+cymysql :name: CyMySQL :dbapi: cymysql :connectstring: mysql+cymysql://<username>:<password>@<host>/<dbname>[?<options>] :url: https://github.com/nakagami/CyMySQL .. note:: The CyMySQL dialect is **not tested as part of SQLAlchemy's continuous integration** and may have unresolved issues. The recommended MySQL dialects are mysqlclient and PyMySQL. """ # noqa from .base import BIT from .base import MySQLDialect from .mysqldb import MySQLDialect_mysqldb from ... import util class _cymysqlBIT(BIT): def result_processor(self, dialect, coltype): """Convert MySQL's 64 bit, variable length binary string to a long.""" def process(value): if value is not None: v = 0 for i in iter(value): v = v << 8 | i return v return value return process class MySQLDialect_cymysql(MySQLDialect_mysqldb): driver = "cymysql" supports_statement_cache = True description_encoding = None supports_sane_rowcount = True supports_sane_multi_rowcount = False supports_unicode_statements = True colspecs = util.update_copy(MySQLDialect.colspecs, {BIT: _cymysqlBIT}) @classmethod def import_dbapi(cls): return __import__("cymysql") def _detect_charset(self, connection): return connection.connection.charset def _extract_error_code(self, exception): return exception.errno def is_disconnect(self, e, connection, cursor): if isinstance(e, self.dbapi.OperationalError): return self._extract_error_code(e) in ( 2006, 2013, 2014, 2045, 2055, ) elif isinstance(e, self.dbapi.InterfaceError): # if underlying connection is closed, # this is the error you get return True else: return False dialect = MySQLDialect_cymysql sqlalchemy/dialects/mysql/types.py 0000755 00000057277 15125143220 0013401 0 ustar 00 # dialects/mysql/types.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors import datetime from ... import exc from ... import util from ...sql import sqltypes class _NumericType: """Base for MySQL numeric types. This is the base both for NUMERIC as well as INTEGER, hence it's a mixin. """ def __init__(self, unsigned=False, zerofill=False, **kw): self.unsigned = unsigned self.zerofill = zerofill super().__init__(**kw) def __repr__(self): return util.generic_repr( self, to_inspect=[_NumericType, sqltypes.Numeric] ) class _FloatType(_NumericType, sqltypes.Float): def __init__(self, precision=None, scale=None, asdecimal=True, **kw): if isinstance(self, (REAL, DOUBLE)) and ( (precision is None and scale is not None) or (precision is not None and scale is None) ): raise exc.ArgumentError( "You must specify both precision and scale or omit " "both altogether." ) super().__init__(precision=precision, asdecimal=asdecimal, **kw) self.scale = scale def __repr__(self): return util.generic_repr( self, to_inspect=[_FloatType, _NumericType, sqltypes.Float] ) class _IntegerType(_NumericType, sqltypes.Integer): def __init__(self, display_width=None, **kw): self.display_width = display_width super().__init__(**kw) def __repr__(self): return util.generic_repr( self, to_inspect=[_IntegerType, _NumericType, sqltypes.Integer] ) class _StringType(sqltypes.String): """Base for MySQL string types.""" def __init__( self, charset=None, collation=None, ascii=False, # noqa binary=False, unicode=False, national=False, **kw, ): self.charset = charset # allow collate= or collation= kw.setdefault("collation", kw.pop("collate", collation)) self.ascii = ascii self.unicode = unicode self.binary = binary self.national = national super().__init__(**kw) def __repr__(self): return util.generic_repr( self, to_inspect=[_StringType, sqltypes.String] ) class _MatchType(sqltypes.Float, sqltypes.MatchType): def __init__(self, **kw): # TODO: float arguments? sqltypes.Float.__init__(self) sqltypes.MatchType.__init__(self) class NUMERIC(_NumericType, sqltypes.NUMERIC): """MySQL NUMERIC type.""" __visit_name__ = "NUMERIC" def __init__(self, precision=None, scale=None, asdecimal=True, **kw): """Construct a NUMERIC. :param precision: Total digits in this number. If scale and precision are both None, values are stored to limits allowed by the server. :param scale: The number of digits after the decimal point. :param unsigned: a boolean, optional. :param zerofill: Optional. If true, values will be stored as strings left-padded with zeros. Note that this does not effect the values returned by the underlying database API, which continue to be numeric. """ super().__init__( precision=precision, scale=scale, asdecimal=asdecimal, **kw ) class DECIMAL(_NumericType, sqltypes.DECIMAL): """MySQL DECIMAL type.""" __visit_name__ = "DECIMAL" def __init__(self, precision=None, scale=None, asdecimal=True, **kw): """Construct a DECIMAL. :param precision: Total digits in this number. If scale and precision are both None, values are stored to limits allowed by the server. :param scale: The number of digits after the decimal point. :param unsigned: a boolean, optional. :param zerofill: Optional. If true, values will be stored as strings left-padded with zeros. Note that this does not effect the values returned by the underlying database API, which continue to be numeric. """ super().__init__( precision=precision, scale=scale, asdecimal=asdecimal, **kw ) class DOUBLE(_FloatType, sqltypes.DOUBLE): """MySQL DOUBLE type.""" __visit_name__ = "DOUBLE" def __init__(self, precision=None, scale=None, asdecimal=True, **kw): """Construct a DOUBLE. .. note:: The :class:`.DOUBLE` type by default converts from float to Decimal, using a truncation that defaults to 10 digits. Specify either ``scale=n`` or ``decimal_return_scale=n`` in order to change this scale, or ``asdecimal=False`` to return values directly as Python floating points. :param precision: Total digits in this number. If scale and precision are both None, values are stored to limits allowed by the server. :param scale: The number of digits after the decimal point. :param unsigned: a boolean, optional. :param zerofill: Optional. If true, values will be stored as strings left-padded with zeros. Note that this does not effect the values returned by the underlying database API, which continue to be numeric. """ super().__init__( precision=precision, scale=scale, asdecimal=asdecimal, **kw ) class REAL(_FloatType, sqltypes.REAL): """MySQL REAL type.""" __visit_name__ = "REAL" def __init__(self, precision=None, scale=None, asdecimal=True, **kw): """Construct a REAL. .. note:: The :class:`.REAL` type by default converts from float to Decimal, using a truncation that defaults to 10 digits. Specify either ``scale=n`` or ``decimal_return_scale=n`` in order to change this scale, or ``asdecimal=False`` to return values directly as Python floating points. :param precision: Total digits in this number. If scale and precision are both None, values are stored to limits allowed by the server. :param scale: The number of digits after the decimal point. :param unsigned: a boolean, optional. :param zerofill: Optional. If true, values will be stored as strings left-padded with zeros. Note that this does not effect the values returned by the underlying database API, which continue to be numeric. """ super().__init__( precision=precision, scale=scale, asdecimal=asdecimal, **kw ) class FLOAT(_FloatType, sqltypes.FLOAT): """MySQL FLOAT type.""" __visit_name__ = "FLOAT" def __init__(self, precision=None, scale=None, asdecimal=False, **kw): """Construct a FLOAT. :param precision: Total digits in this number. If scale and precision are both None, values are stored to limits allowed by the server. :param scale: The number of digits after the decimal point. :param unsigned: a boolean, optional. :param zerofill: Optional. If true, values will be stored as strings left-padded with zeros. Note that this does not effect the values returned by the underlying database API, which continue to be numeric. """ super().__init__( precision=precision, scale=scale, asdecimal=asdecimal, **kw ) def bind_processor(self, dialect): return None class INTEGER(_IntegerType, sqltypes.INTEGER): """MySQL INTEGER type.""" __visit_name__ = "INTEGER" def __init__(self, display_width=None, **kw): """Construct an INTEGER. :param display_width: Optional, maximum display width for this number. :param unsigned: a boolean, optional. :param zerofill: Optional. If true, values will be stored as strings left-padded with zeros. Note that this does not effect the values returned by the underlying database API, which continue to be numeric. """ super().__init__(display_width=display_width, **kw) class BIGINT(_IntegerType, sqltypes.BIGINT): """MySQL BIGINTEGER type.""" __visit_name__ = "BIGINT" def __init__(self, display_width=None, **kw): """Construct a BIGINTEGER. :param display_width: Optional, maximum display width for this number. :param unsigned: a boolean, optional. :param zerofill: Optional. If true, values will be stored as strings left-padded with zeros. Note that this does not effect the values returned by the underlying database API, which continue to be numeric. """ super().__init__(display_width=display_width, **kw) class MEDIUMINT(_IntegerType): """MySQL MEDIUMINTEGER type.""" __visit_name__ = "MEDIUMINT" def __init__(self, display_width=None, **kw): """Construct a MEDIUMINTEGER :param display_width: Optional, maximum display width for this number. :param unsigned: a boolean, optional. :param zerofill: Optional. If true, values will be stored as strings left-padded with zeros. Note that this does not effect the values returned by the underlying database API, which continue to be numeric. """ super().__init__(display_width=display_width, **kw) class TINYINT(_IntegerType): """MySQL TINYINT type.""" __visit_name__ = "TINYINT" def __init__(self, display_width=None, **kw): """Construct a TINYINT. :param display_width: Optional, maximum display width for this number. :param unsigned: a boolean, optional. :param zerofill: Optional. If true, values will be stored as strings left-padded with zeros. Note that this does not effect the values returned by the underlying database API, which continue to be numeric. """ super().__init__(display_width=display_width, **kw) class SMALLINT(_IntegerType, sqltypes.SMALLINT): """MySQL SMALLINTEGER type.""" __visit_name__ = "SMALLINT" def __init__(self, display_width=None, **kw): """Construct a SMALLINTEGER. :param display_width: Optional, maximum display width for this number. :param unsigned: a boolean, optional. :param zerofill: Optional. If true, values will be stored as strings left-padded with zeros. Note that this does not effect the values returned by the underlying database API, which continue to be numeric. """ super().__init__(display_width=display_width, **kw) class BIT(sqltypes.TypeEngine): """MySQL BIT type. This type is for MySQL 5.0.3 or greater for MyISAM, and 5.0.5 or greater for MyISAM, MEMORY, InnoDB and BDB. For older versions, use a MSTinyInteger() type. """ __visit_name__ = "BIT" def __init__(self, length=None): """Construct a BIT. :param length: Optional, number of bits. """ self.length = length def result_processor(self, dialect, coltype): """Convert a MySQL's 64 bit, variable length binary string to a long.""" if dialect.supports_native_bit: return None def process(value): if value is not None: v = 0 for i in value: if not isinstance(i, int): i = ord(i) # convert byte to int on Python 2 v = v << 8 | i return v return value return process class TIME(sqltypes.TIME): """MySQL TIME type.""" __visit_name__ = "TIME" def __init__(self, timezone=False, fsp=None): """Construct a MySQL TIME type. :param timezone: not used by the MySQL dialect. :param fsp: fractional seconds precision value. MySQL 5.6 supports storage of fractional seconds; this parameter will be used when emitting DDL for the TIME type. .. note:: DBAPI driver support for fractional seconds may be limited; current support includes MySQL Connector/Python. """ super().__init__(timezone=timezone) self.fsp = fsp def result_processor(self, dialect, coltype): time = datetime.time def process(value): # convert from a timedelta value if value is not None: microseconds = value.microseconds seconds = value.seconds minutes = seconds // 60 return time( minutes // 60, minutes % 60, seconds - minutes * 60, microsecond=microseconds, ) else: return None return process class TIMESTAMP(sqltypes.TIMESTAMP): """MySQL TIMESTAMP type.""" __visit_name__ = "TIMESTAMP" def __init__(self, timezone=False, fsp=None): """Construct a MySQL TIMESTAMP type. :param timezone: not used by the MySQL dialect. :param fsp: fractional seconds precision value. MySQL 5.6.4 supports storage of fractional seconds; this parameter will be used when emitting DDL for the TIMESTAMP type. .. note:: DBAPI driver support for fractional seconds may be limited; current support includes MySQL Connector/Python. """ super().__init__(timezone=timezone) self.fsp = fsp class DATETIME(sqltypes.DATETIME): """MySQL DATETIME type.""" __visit_name__ = "DATETIME" def __init__(self, timezone=False, fsp=None): """Construct a MySQL DATETIME type. :param timezone: not used by the MySQL dialect. :param fsp: fractional seconds precision value. MySQL 5.6.4 supports storage of fractional seconds; this parameter will be used when emitting DDL for the DATETIME type. .. note:: DBAPI driver support for fractional seconds may be limited; current support includes MySQL Connector/Python. """ super().__init__(timezone=timezone) self.fsp = fsp class YEAR(sqltypes.TypeEngine): """MySQL YEAR type, for single byte storage of years 1901-2155.""" __visit_name__ = "YEAR" def __init__(self, display_width=None): self.display_width = display_width class TEXT(_StringType, sqltypes.TEXT): """MySQL TEXT type, for character storage encoded up to 2^16 bytes.""" __visit_name__ = "TEXT" def __init__(self, length=None, **kw): """Construct a TEXT. :param length: Optional, if provided the server may optimize storage by substituting the smallest TEXT type sufficient to store ``length`` bytes of characters. :param charset: Optional, a column-level character set for this string value. Takes precedence to 'ascii' or 'unicode' short-hand. :param collation: Optional, a column-level collation for this string value. Takes precedence to 'binary' short-hand. :param ascii: Defaults to False: short-hand for the ``latin1`` character set, generates ASCII in schema. :param unicode: Defaults to False: short-hand for the ``ucs2`` character set, generates UNICODE in schema. :param national: Optional. If true, use the server's configured national character set. :param binary: Defaults to False: short-hand, pick the binary collation type that matches the column's character set. Generates BINARY in schema. This does not affect the type of data stored, only the collation of character data. """ super().__init__(length=length, **kw) class TINYTEXT(_StringType): """MySQL TINYTEXT type, for character storage encoded up to 2^8 bytes.""" __visit_name__ = "TINYTEXT" def __init__(self, **kwargs): """Construct a TINYTEXT. :param charset: Optional, a column-level character set for this string value. Takes precedence to 'ascii' or 'unicode' short-hand. :param collation: Optional, a column-level collation for this string value. Takes precedence to 'binary' short-hand. :param ascii: Defaults to False: short-hand for the ``latin1`` character set, generates ASCII in schema. :param unicode: Defaults to False: short-hand for the ``ucs2`` character set, generates UNICODE in schema. :param national: Optional. If true, use the server's configured national character set. :param binary: Defaults to False: short-hand, pick the binary collation type that matches the column's character set. Generates BINARY in schema. This does not affect the type of data stored, only the collation of character data. """ super().__init__(**kwargs) class MEDIUMTEXT(_StringType): """MySQL MEDIUMTEXT type, for character storage encoded up to 2^24 bytes.""" __visit_name__ = "MEDIUMTEXT" def __init__(self, **kwargs): """Construct a MEDIUMTEXT. :param charset: Optional, a column-level character set for this string value. Takes precedence to 'ascii' or 'unicode' short-hand. :param collation: Optional, a column-level collation for this string value. Takes precedence to 'binary' short-hand. :param ascii: Defaults to False: short-hand for the ``latin1`` character set, generates ASCII in schema. :param unicode: Defaults to False: short-hand for the ``ucs2`` character set, generates UNICODE in schema. :param national: Optional. If true, use the server's configured national character set. :param binary: Defaults to False: short-hand, pick the binary collation type that matches the column's character set. Generates BINARY in schema. This does not affect the type of data stored, only the collation of character data. """ super().__init__(**kwargs) class LONGTEXT(_StringType): """MySQL LONGTEXT type, for character storage encoded up to 2^32 bytes.""" __visit_name__ = "LONGTEXT" def __init__(self, **kwargs): """Construct a LONGTEXT. :param charset: Optional, a column-level character set for this string value. Takes precedence to 'ascii' or 'unicode' short-hand. :param collation: Optional, a column-level collation for this string value. Takes precedence to 'binary' short-hand. :param ascii: Defaults to False: short-hand for the ``latin1`` character set, generates ASCII in schema. :param unicode: Defaults to False: short-hand for the ``ucs2`` character set, generates UNICODE in schema. :param national: Optional. If true, use the server's configured national character set. :param binary: Defaults to False: short-hand, pick the binary collation type that matches the column's character set. Generates BINARY in schema. This does not affect the type of data stored, only the collation of character data. """ super().__init__(**kwargs) class VARCHAR(_StringType, sqltypes.VARCHAR): """MySQL VARCHAR type, for variable-length character data.""" __visit_name__ = "VARCHAR" def __init__(self, length=None, **kwargs): """Construct a VARCHAR. :param charset: Optional, a column-level character set for this string value. Takes precedence to 'ascii' or 'unicode' short-hand. :param collation: Optional, a column-level collation for this string value. Takes precedence to 'binary' short-hand. :param ascii: Defaults to False: short-hand for the ``latin1`` character set, generates ASCII in schema. :param unicode: Defaults to False: short-hand for the ``ucs2`` character set, generates UNICODE in schema. :param national: Optional. If true, use the server's configured national character set. :param binary: Defaults to False: short-hand, pick the binary collation type that matches the column's character set. Generates BINARY in schema. This does not affect the type of data stored, only the collation of character data. """ super().__init__(length=length, **kwargs) class CHAR(_StringType, sqltypes.CHAR): """MySQL CHAR type, for fixed-length character data.""" __visit_name__ = "CHAR" def __init__(self, length=None, **kwargs): """Construct a CHAR. :param length: Maximum data length, in characters. :param binary: Optional, use the default binary collation for the national character set. This does not affect the type of data stored, use a BINARY type for binary data. :param collation: Optional, request a particular collation. Must be compatible with the national character set. """ super().__init__(length=length, **kwargs) @classmethod def _adapt_string_for_cast(cls, type_): # copy the given string type into a CHAR # for the purposes of rendering a CAST expression type_ = sqltypes.to_instance(type_) if isinstance(type_, sqltypes.CHAR): return type_ elif isinstance(type_, _StringType): return CHAR( length=type_.length, charset=type_.charset, collation=type_.collation, ascii=type_.ascii, binary=type_.binary, unicode=type_.unicode, national=False, # not supported in CAST ) else: return CHAR(length=type_.length) class NVARCHAR(_StringType, sqltypes.NVARCHAR): """MySQL NVARCHAR type. For variable-length character data in the server's configured national character set. """ __visit_name__ = "NVARCHAR" def __init__(self, length=None, **kwargs): """Construct an NVARCHAR. :param length: Maximum data length, in characters. :param binary: Optional, use the default binary collation for the national character set. This does not affect the type of data stored, use a BINARY type for binary data. :param collation: Optional, request a particular collation. Must be compatible with the national character set. """ kwargs["national"] = True super().__init__(length=length, **kwargs) class NCHAR(_StringType, sqltypes.NCHAR): """MySQL NCHAR type. For fixed-length character data in the server's configured national character set. """ __visit_name__ = "NCHAR" def __init__(self, length=None, **kwargs): """Construct an NCHAR. :param length: Maximum data length, in characters. :param binary: Optional, use the default binary collation for the national character set. This does not affect the type of data stored, use a BINARY type for binary data. :param collation: Optional, request a particular collation. Must be compatible with the national character set. """ kwargs["national"] = True super().__init__(length=length, **kwargs) class TINYBLOB(sqltypes._Binary): """MySQL TINYBLOB type, for binary data up to 2^8 bytes.""" __visit_name__ = "TINYBLOB" class MEDIUMBLOB(sqltypes._Binary): """MySQL MEDIUMBLOB type, for binary data up to 2^24 bytes.""" __visit_name__ = "MEDIUMBLOB" class LONGBLOB(sqltypes._Binary): """MySQL LONGBLOB type, for binary data up to 2^32 bytes.""" __visit_name__ = "LONGBLOB" sqlalchemy/dialects/mysql/__pycache__/mariadb.cpython-39.pyc 0000644 00000003633 15125143220 0020103 0 ustar 00 a ��Jhp � @ s� d dl mZ d dl mZ d dl mZ ddlmZ G dd� deje �ZG dd � d eje �Z G d d � d e�Z G d d � d e�Z dd� Z dS )� )�MariaDBIdentifierPreparer)� MySQLDialect)�MySQLTypeCompiler� )�sqltypesc @ s e Zd ZdZd ZdS )�INET4z@INET4 column type for MariaDB .. versionadded:: 2.0.37 N��__name__� __module__� __qualname__�__doc__Z__visit_name__� r r �V/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mysql/mariadb.pyr s r c @ s e Zd ZdZd ZdS )�INET6z@INET6 column type for MariaDB .. versionadded:: 2.0.37 Nr r r r r r s r c @ s( e Zd Zed�dd�Zed�dd�ZdS )�MariaDBTypeCompiler)�returnc K s dS )Nr r ��self�type_�kwargsr r r � visit_INET4! s z MariaDBTypeCompiler.visit_INET4c K s dS )Nr r r r r r � visit_INET6$ s z MariaDBTypeCompiler.visit_INET6N)r r r �strr r r r r r r s r c @ s e Zd ZdZdZdZeZeZ dS )�MariaDBDialectTZmariadbN) r r r Z is_mariadb�supports_statement_cache�namer �preparerr Ztype_compiler_clsr r r r r ( s r c C sP t d| �jj}t|| �}t|d�r.|j}|S |j}td| t|fddi�S d S )Nz sqlalchemy.dialects.mysql.%s�mariadb_dialectzMariaDBDialect_%sr T) � __import__ZdialectsZmysql�getattr�hasattrr �dialect�typer )ZdriverZ dialect_modZ driver_modZ driver_clsr r r �loader0 s � ��r# N) �baser r r Zsqlr Z TypeEnginer r r r r r# r r r r �<module> s sqlalchemy/dialects/mysql/__pycache__/pymysql.cpython-39.pyc 0000644 00000010027 15125143220 0020215 0 ustar 00 a ��Jh� � @ s4 d Z ddlmZ ddlmZ G dd� de�ZeZdS )a� .. dialect:: mysql+pymysql :name: PyMySQL :dbapi: pymysql :connectstring: mysql+pymysql://<username>:<password>@<host>/<dbname>[?<options>] :url: https://pymysql.readthedocs.io/ Unicode ------- Please see :ref:`mysql_unicode` for current recommendations on unicode handling. .. _pymysql_ssl: SSL Connections ------------------ The PyMySQL DBAPI accepts the same SSL arguments as that of MySQLdb, described at :ref:`mysqldb_ssl`. See that section for additional examples. If the server uses an automatically-generated certificate that is self-signed or does not match the host name (as seen from the client), it may also be necessary to indicate ``ssl_check_hostname=false`` in PyMySQL:: connection_uri = ( "mysql+pymysql://scott:tiger@192.168.0.134/test" "?ssl_ca=/home/gord/client-ssl/ca.pem" "&ssl_cert=/home/gord/client-ssl/client-cert.pem" "&ssl_key=/home/gord/client-ssl/client-key.pem" "&ssl_check_hostname=false" ) MySQL-Python Compatibility -------------------------- The pymysql DBAPI is a pure Python port of the MySQL-python (MySQLdb) driver, and targets 100% compatibility. Most behavioral notes for MySQL-python apply to the pymysql driver as well. � )�MySQLDialect_mysqldb� )� langhelpersc sn e Zd ZdZdZdZejdd� �Ze dd� �Z ejdd � �Z d d � Z d� fd d � Z � fdd�Zdd� Z� ZS )�MySQLDialect_pymysql�pymysqlTNc C s6 zt d�j}|j| _W dS ttfy0 Y dS 0 d S )Nzpymysql.cursorsTF)� __import__�cursorsZSSCursorZ _sscursor� ImportError�AttributeError)�selfr � r �V/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mysql/pymysql.py� supports_server_side_cursors? s z1MySQLDialect_pymysql.supports_server_side_cursorsc C s t d�S )Nr )r )�clsr r r � import_dbapiH s z!MySQLDialect_pymysql.import_dbapic C s| zt d�jj}W n ttfy( Y dS 0 t�|j�}z|jd }W n t yX Y dS 0 |dkov|j pv|j d duS dS )a determine if pymysql has deprecated, changed the default of, or removed the 'reconnect' argument of connection.ping(). See #10492 and https://github.com/PyMySQL/mysqlclient/discussions/651#discussioncomment-7308971 for background. zpymysql.connectionsTr FZ reconnect� N) r � connections� Connectionr r r Zget_callable_argspec�ping�args� IndexError�defaults)r r ZinspZ reconnect_argr r r �_send_false_to_pingL s � �z(MySQLDialect_pymysql._send_false_to_pingc C s | j r|�d� n|�� dS )NFT)r r )r Zdbapi_connectionr r r �do_pingh s z MySQLDialect_pymysql.do_pingc s" |d u rt dd�}t� j||d�S )N�user)�username)�_translate_args)�dict�super�create_connect_args)r �urlr �� __class__r r r p s �z(MySQLDialect_pymysql.create_connect_argsc sF t � �|||�rdS t|| jj�r>t|��� }d|v p<d|v S dS d S )NTzalready closedzconnection was killedF)r � is_disconnect� isinstanceZdbapi�Error�str�lower)r �e� connection�cursorZstr_er! r r r# w s �z"MySQLDialect_pymysql.is_disconnectc C s$ t |jd t�r|jd }|jd S )Nr )r$ r � Exception)r � exceptionr r r �_extract_error_code� s z(MySQLDialect_pymysql._extract_error_code)N)�__name__� __module__� __qualname__ZdriverZsupports_statement_cacheZdescription_encodingr Zmemoized_propertyr � classmethodr r r r r# r- � __classcell__r r r! r r 9 s r N)�__doc__Zmysqldbr �utilr r �dialectr r r r �<module> s + O sqlalchemy/dialects/mysql/__pycache__/reflection.cpython-39.pyc 0000644 00000036341 15125143220 0020640 0 ustar 00 a ��Jh:Y � @ s� d dl Z ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ dd lm Z dd lmZ dd lm Z G d d � d �Z e j G dd� d��ZdZd'dd�Zdd� Zdd� Zeed�dd�Zddd d d d d d!d"d#� Ze �d$�d%d&� eD ���ZdS )(� N� )�ENUM)�SET)�DATETIME)�TIME)� TIMESTAMP� )�log)�types)�utilc @ s e Zd ZdZdd� ZdS )�ReflectedStatez;Stores raw information about a SHOW CREATE TABLE statement.c C s( g | _ i | _d | _g | _g | _g | _d S �N)�columns� table_options� table_name�keys�fk_constraints�ck_constraints)�self� r �Y/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mysql/reflection.py�__init__ s zReflectedState.__init__N)�__name__� __module__� __qualname__�__doc__r r r r r r s r c @ s� e Zd ZdZdd� Zdd� Zeed�dd�Zd d � Z d d � Z d d� Z dd� Z dd� Z dd� Zdd� Zdd� ZdZdd� Zd d � Zd d � Zd d!� Zd"S )#�MySQLTableDefinitionParserz4Parses the results of a SHOW CREATE TABLE statement.c C s || _ || _| �� d S r )�dialect�preparer� _prep_regexes)r r r r r r r & s z#MySQLTableDefinitionParser.__init__c C s t � }||_t�d|�D ]�}|�d| jj �r<| �||� q|�d�rT| �||� q|dkr^q|�d�rv| � ||� qd|v r�| � ||� q|s�q| � |�\}}|d u r�t � d| � q|dkr�|j�|� q|d kr�|j�|� q|d kr|j�|� qq|S ) Nz\r?\nz z) �)zCREATE � PARTITIONzUnknown schema content: %r�key� fk_constraint� ck_constraint)r �charset�re�split� startswithr � initial_quote� _parse_column�_parse_table_options�_parse_table_name�_parse_partition_options�_parse_constraintsr �warnr �appendr r )r Z show_creater% �state�line�type_�specr r r �parse+ s4 z MySQLTableDefinitionParser.parse)�sql�returnc C s t | j�|��S r )�bool� _re_is_view�match)r r6 r r r � _check_viewM s z&MySQLTableDefinitionParser._check_viewc C s: | j �|�}|r�|�� }| �|d �|d< |d rb| j�|d �}|rb|�� d rb|�� d |d< |d r�| j�|d �d |d< d|fS | j�|�}|r�|�� }| j�|d �|d< dd� | �|d �D �|d < d d� | �|d �D �|d < d |fS | j�|�}|�r|�� }d |fS | j �|�}|�r2d|fS d|fS )zaParse a KEY or CONSTRAINT line. :param line: A line of SHOW CREATE TABLE output r Z version_sql�parserr r" �tablec S s g | ] }|d �qS �r r ��.0�cr r r � <listcomp>m � zAMySQLTableDefinitionParser._parse_constraints.<locals>.<listcomp>�localc S s g | ] }|d �qS r> r r? r r r rB n s Zforeignr# r$ � partitionN) �_re_keyr: � groupdict�_parse_keyexprs�_re_key_version_sqlr Zunformat_identifiers�_re_fk_constraint�_re_ck_constraint� _re_partition)r r2 �mr4 �m2r r r r. P s@ �� � z-MySQLTableDefinitionParser._parse_constraintsc C s, | j \}}|�|�}|r(||�d��|_dS )zZExtract the table name. :param line: The first line of SHOW CREATE TABLE �nameN)�_pr_namer: �groupr )r r2 r1 �regex�cleanuprM r r r r, � s z,MySQLTableDefinitionParser._parse_table_namec C s� i }|rn|dkrn|}| j D ]R\}}|�|�}|s2q|�d�|�d� }} |rT|| �} | ||�� < |�d|�}qdD ]} |�| d� qr|�� D ] \} } | |jd| jj | f < q�dS )z�Build a dictionary of all reflected table-level options. :param line: The final line of SHOW CREATE TABLE output. r � directive�val� )�auto_incrementzdata directoryzindex directoryN�%s_%s) � _pr_options�searchrQ �lower�sub�pop�itemsr r rO ) r r2 r1 �optionsZ rest_of_linerR rS rM rT �valueZnope�optrU r r r r+ � s z/MySQLTableDefinitionParser._parse_table_optionsc C s� i }|d d � }|� d�s$|� d�r2|dd � }q| jD �]\}}|�|�}|r8d|jvr\q8|�d�}|�� }|dk} |dks�| �r |�dd �}|�d d �}| r�|�d �r�|d d � }| jj d kr�|�d �r�d|v s�d|v s�d|v r�|d d � }d| jj |f } ||| < n,|�dd�}|�d�} |�r.|| �} | ||< �q>q8|� � D ]~\} } d| jj }d| jj }| |k�sz| |k�r�| |j v�r�| |j | < nd|j | | f |j | < n| |j d| jj | f < �qFd S )N�(� r r! rT Z subpartitionrE z) */rV �,r ���ZmariadbZMAXVALUEZMINVALUE�ENGINEz%s_%s_definitions�_rU z%s_partition_definitionsz%s_subpartition_definitionsz%s, %srX ) r( rY rZ �patternrQ r[ �replace�endswithr rO r^ r )r r2 r1 r_ �new_linerR rS rM rT Zis_subpartitionZdefsr` ra rU Zpart_defZ subpart_defr r r r- � sV ��� �z3MySQLTableDefinitionParser._parse_partition_optionsc C s� d}| j �|�}|r&|�� }d|d< n | j�|�}|rF|�� }d|d< |s\t�d| � dS |d srt�d| � |d |d |d }}}z| jj| }W n* ty� t�d ||f � t j }Y n0 |du s�|d kr�g } n@|d d k�r |d d k�r | j � |�} ndd� | j � |�D �} i } t|tttf��rJ| �rJ| �d �| d< dD ] } |�| d��rNd| | < �qNdD ] } |�| d��rp|| | | < �qpt|ttf��r�t| �} t|t��r�d | v �r�d| d< || i | ��} i } d| d< |�dd�dk�r�d| d< |�dd�dk�rd| d< |�dd��r.d| d< nt|t j��rDd| d< |�dd�}|d k�r^d}|�d d�}|du�r|t|�}|�d �}|du�r�t|d �}|�d �}|du�r�|d!k|d"< || d#< t|| ||d$�}|�| � |j� |� dS )%z�Extract column details. Falls back to a 'minimal support' variant if full parse fails. :param line: Any column-bearing line from SHOW CREATE TABLE NT�fullFz Unknown column definition %rz-Incomplete reflection of column definition %rrO Zcoltype�argz*Did not recognize type '%s' of column '%s'rV r �'re c S s g | ] }t |��qS r ��int)r@ �vr r r rB rC z<MySQLTableDefinitionParser._parse_column.<locals>.<listcomp>Zfsp)ZunsignedZzerofill)r% ZcollateZretrieve_as_bitwise�nullableZnotnull�NOT NULLZnotnull_generatedZautoincrZ autoincrement�default�NULL�comment� generated)�sqltextZ persistenceZSTORED� persisted�computed)rO �typert rv ) � _re_columnr: rG �_re_column_looser r/ r Z ischema_names�KeyError�sqltypesZNullType� _re_csv_str�findall� _re_csv_int� issubclassr r r r] �getr r � _strip_valuesZInteger� cleanup_text�dict�updater r0 )r r2 r1 r4 rM rO r3 �args�col_typeZ type_argsZtype_kw�kwZ type_instanceZcol_kwrt rv rx rz ry Zcol_dr r r r* � s� � � z(MySQLTableDefinitionParser._parse_columnc s g }|D ]� � fdd�dD �\}}}}}dg} | � | j�|�� | � |� |sX| � d� |r�d|v rfnh|�d�r�|�d�r�| � d � | � |� n>|d kr�| � d � | � |� n | � d � | � d |�d d � � |r�| � |� |� d�| �� qd�d| j�|� d�|�dg�S )a� Re-format DESCRIBE output as a SHOW CREATE TABLE string. DESCRIBE is a much simpler reflection and is sufficient for reflecting views for runtime use. This method formats DDL for columns only- keys are omitted. :param columns: A sequence of DESCRIBE or SHOW COLUMNS 6-tuples. SHOW FULL COLUMNS FROM rows must be rearranged for use with this function. c 3 s | ]}� | V qd S r r )r@ �i��rowr r � <genexpr>W s zAMySQLTableDefinitionParser._describe_to_create.<locals>.<genexpr>)r r � � � rc rs rW � timestamp�C�DEFAULTru z'%s'rn �''rV zCREATE TABLE %s ( z, z ) )r0 r Zquote_identifierr( ri �join) r r r �bufferrO r� rr rt �extrar2 r r� r �_describe_to_createI sD � � ���z.MySQLTableDefinitionParser._describe_to_createc C s dd� | j �|�D �S )z8Unpack '"col"(2),"col" ASC'-ish strings into components.c S s( g | ] \}}}||r t |�nd |f�qS r ro )r@ Zcolname�length� modifiersr r r rB � s �z>MySQLTableDefinitionParser._parse_keyexprs.<locals>.<listcomp>)� _re_keyexprsr� )r Z identifiersr r r rH ~ s ��z*MySQLTableDefinitionParser._parse_keyexprsc C sP g | _ g | _| jj}ttddd� | jj|| j�|�fD ���}td| | jj �| _ t d�| _ t d| �| _ t d�| _t d�| _t d | �| _t d | �| _t d | �| _t d �| _|�� }d |d< t d| �| _t d| �| _t d�| _tD ]}| �|� q�dD ]}| �|� �q dD ]}| �|� �q| � dd� | � dd� | � dd� dS )z Pre-compile regular expressions.)ZiqZfqZesc_fqc S s g | ]}t �|��qS r �r& �escape)r@ �sr r r rB � s �z<MySQLTableDefinitionParser._prep_regexes.<locals>.<listcomp>zM^CREATE (?:\w+ +)?TABLE +%(iq)s(?P<name>(?:%(esc_fq)s|[^%(fq)s])+)%(fq)s +\($z ^CREATE(?! TABLE)(\s.*)?\sVIEWzW(?:(?:%(iq)s((?:%(esc_fq)s|[^%(fq)s])+)%(fq)s)(?:\((\d+)\))?(?: +(ASC|DESC))?(?=\,|$))+z \x27(?:\x27\x27|[^\x27])*\x27z\d+a� %(iq)s(?P<name>(?:%(esc_fq)s|[^%(fq)s])+)%(fq)s +(?P<coltype>\w+)(?:\((?P<arg>(?:\d+|\d+,\d+|(?:'(?:''|[^'])*',?)+))\))?(?: +(?P<unsigned>UNSIGNED))?(?: +(?P<zerofill>ZEROFILL))?(?: +CHARACTER SET +(?P<charset>[\w_]+))?(?: +COLLATE +(?P<collate>[\w_]+))?(?: +(?P<notnull>(?:NOT )?NULL))?(?: +DEFAULT +(?P<default>(?:NULL|'(?:''|[^'])*'|\(.+?\)|[\-\w\.\(\)]+(?: +ON UPDATE [\-\w\.\(\)]+)?)))?(?: +(?:GENERATED ALWAYS)? ?AS +(?P<generated>\(.*\))? ?(?P<persistence>VIRTUAL|STORED)?(?: +(?P<notnull_generated>(?:NOT )?NULL))?)?(?: +(?P<autoincr>AUTO_INCREMENT))?(?: +COMMENT +'(?P<comment>(?:''|[^'])*)')?(?: +COLUMN_FORMAT +(?P<colfmt>\w+))?(?: +STORAGE +(?P<storage>\w+))?(?: +(?P<extra>.*))?,?$z� %(iq)s(?P<name>(?:%(esc_fq)s|[^%(fq)s])+)%(fq)s +(?P<coltype>\w+)(?:\((?P<arg>(?:\d+|\d+,\d+|\x27(?:\x27\x27|[^\x27])+\x27))\))?.*?(?P<notnull>(?:NOT )NULL)?aX (?:(?P<type>\S+) )?KEY(?: +%(iq)s(?P<name>(?:%(esc_fq)s|[^%(fq)s])+)%(fq)s)?(?: +USING +(?P<using_pre>\S+))? +\((?P<columns>.+?)\)(?: +USING +(?P<using_post>\S+))?(?: +KEY_BLOCK_SIZE *[ =]? *(?P<keyblock>\S+))?(?: +WITH PARSER +(?P<parser>\S+))?(?: +COMMENT +(?P<comment>(\x27\x27|\x27([^\x27])*?\x27)+))?(?: +/\*(?P<version_sql>.+)\*/ *)?,?$z+\!\d+ (?: *WITH PARSER +(?P<parser>\S+) *)?z/RESTRICT|CASCADE|SET NULL|NO ACTION|SET DEFAULT�onaJ CONSTRAINT +%(iq)s(?P<name>(?:%(esc_fq)s|[^%(fq)s])+)%(fq)s +FOREIGN KEY +\((?P<local>[^\)]+?)\) REFERENCES +(?P<table>%(iq)s[^%(fq)s]+%(fq)s(?:\.%(iq)s[^%(fq)s]+%(fq)s)?) +\((?P<foreign>(?:%(iq)s[^%(fq)s]+%(fq)s(?: *, *)?)+)\)(?: +(?P<match>MATCH \w+))?(?: +ON DELETE (?P<ondelete>%(on)s))?(?: +ON UPDATE (?P<onupdate>%(on)s))?z[ CONSTRAINT +%(iq)s(?P<name>(?:%(esc_fq)s|[^%(fq)s])+)%(fq)s +CHECK +\((?P<sqltext>.+)\),?z (?:.*)(?:SUB)?PARTITION(?:.*))rf ZTYPEZAUTO_INCREMENTZAVG_ROW_LENGTHz CHARACTER SETzDEFAULT CHARSETZCHECKSUMZCOLLATEZDELAY_KEY_WRITEZ INSERT_METHODZMAX_ROWSZMIN_ROWSZ PACK_KEYSZ ROW_FORMATZKEY_BLOCK_SIZEZSTATS_SAMPLE_PAGES)� PARTITION BY�SUBPARTITION BY� PARTITIONS� SUBPARTITIONSr! Z SUBPARTITIONZUNIONz \([^\)]+\)Z TABLESPACEz.*? STORAGE DISKZ RAID_TYPEz4\w+\s+RAID_CHUNKS\s*\=\s*\w+RAID_CHUNKSIZE\s*=\s*\w+N) Z _re_columnsrY r Z final_quoter� �zipr) Z_escape_identifier� _pr_compileZ_unescape_identifierrP � _re_compiler9 r� r� r� r| r} rF rI �copyrJ rK rL �_options_of_type_string�_add_option_string�_add_option_word�_add_partition_option_word�_add_option_regex)r Z_final�quotesr� �optionr r r r � s� ������ �� �� �� ��� ���� �z(MySQLTableDefinitionParser._prep_regexesz(?:\s*(?:=\s*)|\s+)c C s* dt �|�| jf }| j�t|t�� d S )Nz0(?P<directive>%s)%s'(?P<val>(?:[^']|'')*?)'(?!'))r& r� �_optional_equalsrY r0 r� r� �r rT rR r r r r� I s �z-MySQLTableDefinitionParser._add_option_stringc C s( dt �|�| jf }| j�t|�� d S )Nz (?P<directive>%s)%s(?P<val>\w+)�r& r� r� rY r0 r� r� r r r r� P s �z+MySQLTableDefinitionParser._add_option_wordc C sp |dks|dkr&dt �|�| jf }n6|dks6|dkrLdt �|�| jf }ndt �|�f }| j�t|�� d S )Nr� r� z((?<!\S)(?P<directive>%s)%s(?P<val>\w+.*)r� r� z&(?<!\S)(?P<directive>%s)%s(?P<val>\d+)z (?<!\S)(?P<directive>%s)(?!\S)r� r� r r r r� W s ��z5MySQLTableDefinitionParser._add_partition_option_wordc C s* dt �|�| j|f }| j�t|�� d S )Nz (?P<directive>%s)%s(?P<val>%s)r� r� r r r r� f s �z,MySQLTableDefinitionParser._add_option_regexN)r r r r r r5 �strr8 r; r. r, r+ r- r* r� rH r r� r� r� r� r� r r r r r " s$ "2 8j5 @r )�COMMENTzDATA DIRECTORYzINDEX DIRECTORYZPASSWORDZ CONNECTIONc C s t | �|fS )z1Prepare a 2-tuple of compiled regex and callable.)r� )rR rS r r r r� x s r� c C s t �| t jt jB �S )z)Compile a string to regex, I and UNICODE.)r& �compile�I�UNICODE)rR r r r r� ~ s r� c C s\ g }| D ]N}|dd� dks,|dd� dkrL|dd� � |d d |d �}|�|� q|S )z Strip reflected values quotesr r �"rn re r� )ri r0 )�valuesZ strip_values�ar r r r� � s r� )�raw_textr7 c C s& d| v rt �tdd� | �} | �dd�S )N�\c S s t | d S )Nr )�_control_char_map)r� r r r �<lambda>� rC z cleanup_text.<locals>.<lambda>r� rn )r& r\ �_control_char_regexpri )r� r r r r� � s �r� r� � ��� � � � � ) z\\z\0z\az\bz\tz\nz\vz\fz\r�|c c s | ]}t �|�V qd S r r� )r@ �kr r r r� � rC r� )N)r& Z enumeratedr r r r r r rV r r r r Z class_loggerr r� r� r� r� r� r� r� r� r� r� r r r r �<module> sB P � � sqlalchemy/dialects/mysql/__pycache__/cymysql.cpython-39.pyc 0000644 00000005021 15125143220 0020176 0 ustar 00 a ��Jh� � @ s\ d Z ddlmZ ddlmZ ddlmZ ddlmZ G dd� de�ZG d d � d e�Z e Z d S ) a� .. dialect:: mysql+cymysql :name: CyMySQL :dbapi: cymysql :connectstring: mysql+cymysql://<username>:<password>@<host>/<dbname>[?<options>] :url: https://github.com/nakagami/CyMySQL .. note:: The CyMySQL dialect is **not tested as part of SQLAlchemy's continuous integration** and may have unresolved issues. The recommended MySQL dialects are mysqlclient and PyMySQL. � )�BIT)� MySQLDialect)�MySQLDialect_mysqldb� )�utilc @ s e Zd Zdd� ZdS )� _cymysqlBITc C s dd� }|S )z@Convert MySQL's 64 bit, variable length binary string to a long.c S s. | d ur*d}t | �D ]}|d> |B }q|S | S )N� � )�iter)�value�v�i� r �V/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mysql/cymysql.py�process# s z-_cymysqlBIT.result_processor.<locals>.processr )�self�dialectZcoltyper r r r �result_processor s z _cymysqlBIT.result_processorN)�__name__� __module__� __qualname__r r r r r r s r c @ sZ e Zd ZdZdZdZdZdZdZe � e j e ei�Z edd� �Zdd� Zd d � Zd d � ZdS ) �MySQLDialect_cymysql�cymysqlTNFc C s t d�S )Nr )� __import__)�clsr r r � import_dbapi9 s z!MySQLDialect_cymysql.import_dbapic C s |j jS �N)� connection�charset)r r r r r �_detect_charset= s z$MySQLDialect_cymysql._detect_charsetc C s |j S r )�errno)r � exceptionr r r �_extract_error_code@ s z(MySQLDialect_cymysql._extract_error_codec C s6 t || jj�r | �|�dv S t || jj�r.dS dS d S )N)i� i� i� i� i TF)� isinstanceZdbapiZOperationalErrorr" ZInterfaceError)r �er �cursorr r r � is_disconnectC s z"MySQLDialect_cymysql.is_disconnect)r r r ZdriverZsupports_statement_cacheZdescription_encodingZsupports_sane_rowcountZ supports_sane_multi_rowcountZsupports_unicode_statementsr Z update_copyr Zcolspecsr r � classmethodr r r" r& r r r r r . s r N) �__doc__�baser r Zmysqldbr � r r r r r r r r �<module> s & sqlalchemy/dialects/mysql/__pycache__/asyncmy.cpython-39.pyc 0000644 00000026734 15125143220 0020176 0 ustar 00 a ��Jha' � @ s� d Z ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z dd l m Z dd l m Z dd l mZ dd l mZ G d d� d�ZG dd� de�ZG dd� de �ZG dd� de�Zdd� ZG dd� d�ZG dd� de�ZeZdS ) a� .. dialect:: mysql+asyncmy :name: asyncmy :dbapi: asyncmy :connectstring: mysql+asyncmy://user:password@host:port/dbname[?key=value&key=value...] :url: https://github.com/long2ice/asyncmy Using a special asyncio mediation layer, the asyncmy dialect is usable as the backend for the :ref:`SQLAlchemy asyncio <asyncio_toplevel>` extension package. This dialect should normally be used only with the :func:`_asyncio.create_async_engine` engine creation function:: from sqlalchemy.ext.asyncio import create_async_engine engine = create_async_engine( "mysql+asyncmy://user:pass@hostname/dbname?charset=utf8mb4" ) � )�deque)�asynccontextmanager� )�MySQLDialect_pymysql� )�pool)�util)�AdaptedConnection)�asyncio)�await_fallback)� await_onlyc @ s� e Zd ZdZdZdd� Zedd� �Zedd� �Zed d � �Z e j d d � �Z ed d � �Z dd� Z d#dd�Z dd� Zdd� Zdd� Zdd� Zdd � Zd d � Zd$d d �Zd!d"� ZdS )%�AsyncAdapt_asyncmy_cursorF)�_adapt_connection� _connection�await_�_cursor�_rowsc C s< || _ |j| _|j| _| j�� }| �|�� �| _t� | _d S �N)r r r �cursor� __aenter__r r r ��selfZadapt_connectionr � r �V/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mysql/asyncmy.py�__init__6 s z"AsyncAdapt_asyncmy_cursor.__init__c C s | j jS r )r � description�r r r r r @ s z%AsyncAdapt_asyncmy_cursor.descriptionc C s | j jS r )r �rowcountr r r r r D s z"AsyncAdapt_asyncmy_cursor.rowcountc C s | j jS r �r � arraysizer r r r r H s z#AsyncAdapt_asyncmy_cursor.arraysizec C s || j _d S r r �r �valuer r r r L s c C s | j jS r )r � lastrowidr r r r r" P s z#AsyncAdapt_asyncmy_cursor.lastrowidc C s | j �� d S r )r �clearr r r r �closeT s z AsyncAdapt_asyncmy_cursor.closeNc C s | � | �||��S r )r �_execute_async)r � operation� parametersr r r �execute^ s z!AsyncAdapt_asyncmy_cursor.executec C s | � | �||��S r )r �_executemany_async�r r& Zseq_of_parametersr r r � executemanya s �z%AsyncAdapt_asyncmy_cursor.executemanyc � s� | j �� 4 I d H �f |d u r0| j�|�I d H }n| j�||�I d H }| js`t| j�� I d H �| _|W d �I d H S 1 I d H s�0 Y d S r )r �_mutex_and_adapt_errorsr r( � server_sider �fetchallr )r r& r' �resultr r r r% f s z(AsyncAdapt_asyncmy_cursor._execute_asyncc � sV | j �� 4 I d H �* | j�||�I d H W d �I d H S 1 I d H sH0 Y d S r )r r, r r+ r* r r r r) u s z,AsyncAdapt_asyncmy_cursor._executemany_asyncc G s d S r r )r Z inputsizesr r r � setinputsizesy s z'AsyncAdapt_asyncmy_cursor.setinputsizesc c s | j r| j �� V q d S r �r �popleftr r r r �__iter__| s z"AsyncAdapt_asyncmy_cursor.__iter__c C s | j r| j �� S d S d S r r1 r r r r �fetchone� s z"AsyncAdapt_asyncmy_cursor.fetchonec s4 |d u r| j }| j� � fdd�tt|t� ���D �S )Nc s g | ] }� � � �qS r )r2 )�.0�_��rrr r � <listcomp>� � z7AsyncAdapt_asyncmy_cursor.fetchmany.<locals>.<listcomp>)r r �range�min�len�r �sizer r7 r � fetchmany� s z#AsyncAdapt_asyncmy_cursor.fetchmanyc C s t | j�}| j�� |S r )�listr r# )r �retvalr r r r. � s z"AsyncAdapt_asyncmy_cursor.fetchall)N)N)�__name__� __module__� __qualname__r- � __slots__r �propertyr r r �setterr" r$ r( r+ r% r) r0 r3 r4 r@ r. r r r r r * s. r c @ s> e Zd ZdZdZdd� Zdd� Zdd� Zdd d �Zd d � Z d S )� AsyncAdapt_asyncmy_ss_cursorr Tc C s> || _ |j| _|j| _| j�|jjjj�}| �|�� �| _ d S r ) r r r r �dbapi�asyncmyZcursorsZSSCursorr r r r r r r � s �z%AsyncAdapt_asyncmy_ss_cursor.__init__c C s$ | j d ur | �| j �� � d | _ d S r )r r r$ r r r r r$ � s z"AsyncAdapt_asyncmy_ss_cursor.closec C s | � | j�� �S r )r r r4 r r r r r4 � s z%AsyncAdapt_asyncmy_ss_cursor.fetchoneNc C s | � | jj|d��S )N)r? )r r r@ r> r r r r@ � s z&AsyncAdapt_asyncmy_ss_cursor.fetchmanyc C s | � | j�� �S r )r r r. r r r r r. � s z%AsyncAdapt_asyncmy_ss_cursor.fetchall)N) rC rD rE rF r- r r$ r4 r@ r. r r r r rI � s rI c @ s| e Zd Zee�ZdZdd� Zedd� �Z dd� Z dd � Z d d � Z d d � Z ddd�Zdd� Zdd� Zdd� Zdd�dd�ZdS ) � AsyncAdapt_asyncmy_connection)rJ �_execute_mutexc C s || _ || _t�� | _d S r )rJ r r �LockrM )r rJ � connectionr r r r � s z&AsyncAdapt_asyncmy_connection.__init__c C sh | j 4 I d H �@ z d V W n ty8 | j�d��Y n0 W d �I d H qd1 I d H sZ0 Y d S )Nz7network operation failed due to asyncmy attribute error)rM �AttributeErrorrJ � InternalErrorr r r r r, � s �z5AsyncAdapt_asyncmy_connection._mutex_and_adapt_errorsc C s |rJ �| � | �� �S r )r �_do_ping)r Z reconnectr r r �ping� s z"AsyncAdapt_asyncmy_connection.pingc � sR | � � 4 I d H �( | j�d�I d H W d �I d H S 1 I d H sD0 Y d S )NF)r, r rS r r r r rR � s z&AsyncAdapt_asyncmy_connection._do_pingc C s | j �� S r )r �character_set_namer r r r rT � s z0AsyncAdapt_asyncmy_connection.character_set_namec C s | � | j�|�� d S r )r r � autocommitr r r r rU � s z(AsyncAdapt_asyncmy_connection.autocommitFc C s |r t | �S t| �S d S r )rI r )r r- r r r r � s z$AsyncAdapt_asyncmy_connection.cursorc C s | � | j�� � d S r )r r �rollbackr r r r rV � s z&AsyncAdapt_asyncmy_connection.rollbackc C s | � | j�� � d S r )r r �commitr r r r rW � s z$AsyncAdapt_asyncmy_connection.commitc C s | j �� d S r )r r$ r r r r � terminate� s z'AsyncAdapt_asyncmy_connection.terminateN��returnc C s | � | j�� � d S r )r r Z ensure_closedr r r r r$ � s z#AsyncAdapt_asyncmy_connection.close)F)rC rD rE � staticmethodr r rF r r r, rS rR rT rU r rV rW rX r$ r r r r rL � s rL c @ s e Zd ZdZee�ZdS )�%AsyncAdaptFallback_asyncmy_connectionr N)rC rD rE rF r[ r r r r r r r\ � s r\ c C s t | �S )zReturn x as a binary type.)�bytes)�xr r r �_Binary� s r_ c @ s^ e Zd Zdd� Zdd� Ze�d�Ze�d�Ze�d�Z e�d�Z e�d �Z e e �Zd d � Zd S ) �AsyncAdapt_asyncmy_dbapic C s || _ d| _| �� d S )N�format)rK Z paramstyle�_init_dbapi_attributes)r rK r r r r � s z!AsyncAdapt_asyncmy_dbapi.__init__c C s$ dD ]}t | |t| jj|�� qd S )N) �Warning�Error�InterfaceErrorZ DataErrorZ DatabaseErrorZOperationalErrorre ZIntegrityErrorZProgrammingErrorrQ ZNotSupportedError)�setattr�getattrrK �errors)r �namer r r rb � s z/AsyncAdapt_asyncmy_dbapi._init_dbapi_attributes�STRING�NUMBER�BINARY�DATETIME� TIMESTAMPc O sZ |� dd�}|� d| jj�}t�|�r>t| t||i |����S t| t||i |����S d S )N�async_fallbackFZasync_creator_fn) �poprK �connectr �asboolr\ r rL r )r �arg�kwro Z creator_fnr r r rq s ��z AsyncAdapt_asyncmy_dbapi.connectN)rC rD rE r rb r �symbolrj rk rl rm rn r[ r_ �Binaryrq r r r r r` � s r` c sv e Zd ZdZdZdZeZdZdZ e dd� �Z e dd� �Z dd�d d �Z � fd d �Z� fd d�Zdd� Zdd� Z� ZS )�MySQLDialect_asyncmyrK Tc C s t td��S )NrK )r` � __import__)�clsr r r � import_dbapi, s z!MySQLDialect_asyncmy.import_dbapic C s( |j �dd�}t�|�r tjS tjS d S )Nro F)�query�getr rr r Z FallbackAsyncAdaptedQueuePoolZAsyncAdaptedQueuePool)ry �urlro r r r �get_pool_class0 s z#MySQLDialect_asyncmy.get_pool_classNrY c C s |� � d S r )rX )r Zdbapi_connectionr r r � do_terminate9 s z!MySQLDialect_asyncmy.do_terminatec s t � j|tddd�d�S )N�user�db)�usernameZdatabase)Z_translate_args)�super�create_connect_args�dict)r r} �� __class__r r r� < s �z(MySQLDialect_asyncmy.create_connect_argsc s4 t � �|||�rdS t|��� }d|v p.d|v S d S )NTz not connectedznetwork operation failed)r� � is_disconnect�str�lower)r �erO r Zstr_er� r r r� A s �z"MySQLDialect_asyncmy.is_disconnectc C s ddl m} |jS )Nr )�CLIENT)Zasyncmy.constantsr� Z FOUND_ROWS)r r� r r r �_found_rows_client_flagJ s z,MySQLDialect_asyncmy._found_rows_client_flagc C s |j S r )r )r rO r r r �get_driver_connectionO s z*MySQLDialect_asyncmy.get_driver_connection)rC rD rE ZdriverZsupports_statement_cacheZ supports_server_side_cursorsrI Z _sscursor�is_asyncZ has_terminate� classmethodrz r~ r r� r� r� r� � __classcell__r r r� r rw " s rw N)�__doc__� collectionsr � contextlibr Zpymysqlr � r r Zenginer Zutil.concurrencyr r r r rI rL r\ r_ r` rw �dialectr r r r �<module> s" i 7-1 sqlalchemy/dialects/mysql/__pycache__/mysqlconnector.cpython-39.pyc 0000644 00000021407 15125143220 0021563 0 ustar 00 a ��Jh� � @ s� d Z ddlZddlmZ ddlmZ ddlmZ ddlmZ ddlmZ dd lmZ dd l m Z d d l m Z G d d� de�Z G dd� de�ZG dd� d�ZG dd� dee�ZG dd� dee�ZG dd� de�ZG dd� de�ZG dd � d e e�ZeZeZdS ) a, .. dialect:: mysql+mysqlconnector :name: MySQL Connector/Python :dbapi: myconnpy :connectstring: mysql+mysqlconnector://<user>:<password>@<host>[:<port>]/<dbname> :url: https://pypi.org/project/mysql-connector-python/ Driver Status ------------- MySQL Connector/Python is supported as of SQLAlchemy 2.0.39 to the degree which the driver is functional. There are still ongoing issues with features such as server side cursors which remain disabled until upstream issues are repaired. .. warning:: The MySQL Connector/Python driver published by Oracle is subject to frequent, major regressions of essential functionality such as being able to correctly persist simple binary strings which indicate it is not well tested. The SQLAlchemy project is not able to maintain this dialect fully as regressions in the driver prevent it from being included in continuous integration. .. versionchanged:: 2.0.39 The MySQL Connector/Python dialect has been updated to support the latest version of this DBAPI. Previously, MySQL Connector/Python was not fully supported. However, support remains limited due to ongoing regressions introduced in this driver. Connecting to MariaDB with MySQL Connector/Python -------------------------------------------------- MySQL Connector/Python may attempt to pass an incompatible collation to the database when connecting to MariaDB. Experimentation has shown that using ``?charset=utf8mb4&collation=utfmb4_general_ci`` or similar MariaDB-compatible charset/collation will allow connectivity. � N� )�BIT)�MariaDBIdentifierPreparer)� MySQLCompiler)� MySQLDialect)�MySQLExecutionContext)�MySQLIdentifierPreparer)�MariaDBDialect� )�utilc @ s e Zd Zdd� Zdd� ZdS )�$MySQLExecutionContext_mysqlconnectorc C s | j jdd�S )NF��buffered�Z_dbapi_connection�cursor��self� r �]/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mysql/mysqlconnector.py�create_server_side_cursor? s z>MySQLExecutionContext_mysqlconnector.create_server_side_cursorc C s | j jdd�S )NTr r r r r r �create_default_cursorB s z:MySQLExecutionContext_mysqlconnector.create_default_cursorN)�__name__� __module__� __qualname__r r r r r r r > s r c @ s e Zd Zdd� ZdS )� MySQLCompiler_mysqlconnectorc K s, | j |jfi |��d | j |jfi |�� S )Nz % )�process�left�right)r �binary�operator�kwr r r �visit_mod_binaryG s ���z-MySQLCompiler_mysqlconnector.visit_mod_binaryN)r r r r! r r r r r F s r c @ s. e Zd Zedd� �Zejdd� �Zdd� ZdS )�'IdentifierPreparerCommon_mysqlconnectorc C s dS )NFr r r r r �_double_percentsP s z8IdentifierPreparerCommon_mysqlconnector._double_percentsc C s d S �Nr �r �valuer r r r# T s c C s |� | j| j�}|S r$ )�replaceZ escape_quoteZescape_to_quoter% r r r �_escape_identifierX s z:IdentifierPreparerCommon_mysqlconnector._escape_identifierN)r r r �propertyr# �setterr( r r r r r" O s r" c @ s e Zd ZdS )�&MySQLIdentifierPreparer_mysqlconnectorN�r r r r r r r r+ ] s r+ c @ s e Zd ZdS )�(MariaDBIdentifierPreparer_mysqlconnectorNr, r r r r r- c s r- c @ s e Zd Zdd� ZdS )� _myconnpyBITc C s dS )z0MySQL-connector already converts mysql bits, so.Nr )r �dialectZcoltyper r r �result_processorj s z _myconnpyBIT.result_processorN)r r r r0 r r r r r. i s r. c s� e Zd ZdZdZdZdZdZdZdZ dZ e Z e ZeZe�ejeei�Zedd� �Zdd� Zd d � Zejd d � �Z d d� Z dd� Z dd� Z d dd�Z d dd�Z!dd� Z"� fdd�Z#� Z$S ) �MySQLDialect_mysqlconnectorZmysqlconnectorTF�formatc C s ddl m} |S )Nr )� connector)Zmysqlr3 )�clsr3 r r r � import_dbapi� s z(MySQLDialect_mysqlconnector.import_dbapic C s |� d� dS )NFT)Zping�r Zdbapi_connectionr r r �do_ping� s z#MySQLDialect_mysqlconnector.do_pingc C sj |j dd�}|�|j� t�|dt� t�|dt� t�|dt� t�|dt� t�|dt� t�|dt� t�|d t� t�|d t� t�|d t� t�|d t� t�|d t� t�|dt� t�|dt� t�|dt� t�|dt� t�|dt� t�|dt� d|d< | jd u�rbz2ddlm } |� d|� � �}||j O }||d< W n t �y` Y n0 g |gS )N�user)�usernameZallow_local_infile� autocommitr Z client_flag�compressZconnection_timeout�connect_timeoutZconsume_resultsZ force_ipv6Z get_warningsZpool_reset_sessionZ pool_sizeZraise_on_warnings�rawZssl_verify_certZuse_pureZ use_unicodeTr )� ClientFlag� client_flags)Ztranslate_connect_args�update�queryr Zcoerce_kw_type�bool�int�dbapiZmysql.connector.constantsr> �get� get_defaultZ FOUND_ROWS� Exception)r �url�optsr> r? r r r �create_connect_args� s> � z/MySQLDialect_mysqlconnector.create_connect_argsc C sF | j rBt| j d�rBt�d| j j�}|rBtdd� |�ddd�D ��S d S )N� __version__z(\d+)\.(\d+)(?:\.(\d+))?c s s | ]}|d urt |�V qd S r$ )rC )�.0�xr r r � <genexpr>� � zKMySQLDialect_mysqlconnector._mysqlconnector_version_info.<locals>.<genexpr>r � r )rD �hasattr�re�matchrK �tuple�group)r �mr r r � _mysqlconnector_version_info� s z8MySQLDialect_mysqlconnector._mysqlconnector_version_infoc C s |j jS r$ )� connection�charset)r rX r r r �_detect_charset� s z+MySQLDialect_mysqlconnector._detect_charsetc C s |j S r$ )�errno)r � exceptionr r r �_extract_error_code� s z/MySQLDialect_mysqlconnector._extract_error_codec C sN d}| j j| j j| j jf}t||�rF|j|v pDdt|�v pDdt|�v S dS d S )N)i� i� i� i� i i z MySQL Connection not available.z$Connection to MySQL is not availableF)rD ZOperationalErrorZInterfaceErrorZProgrammingError� isinstancer[ �str)r �erX r Zerrnos� exceptionsr r r � is_disconnect� s � � �z)MySQLDialect_mysqlconnector.is_disconnectNc C s |� � S r$ )Zfetchall�r �rprY r r r �_compat_fetchall� s z,MySQLDialect_mysqlconnector._compat_fetchallc C s |� � S r$ )Zfetchonerc r r r �_compat_fetchone� s z,MySQLDialect_mysqlconnector._compat_fetchonec C s dS )N)Z SERIALIZABLEzREAD UNCOMMITTEDzREAD COMMITTEDzREPEATABLE READ� AUTOCOMMITr r6 r r r �get_isolation_level_values� s z6MySQLDialect_mysqlconnector.get_isolation_level_valuesc s( |dkrd|_ nd|_ t� �||� d S )Nrg TF)r: �super�set_isolation_level)r rX �level�� __class__r r rj � s z/MySQLDialect_mysqlconnector.set_isolation_level)N)N)%r r r Zdriver�supports_statement_cacheZsupports_sane_rowcountZ supports_sane_multi_rowcountZsupports_native_decimalZsupports_native_bitZ supports_server_side_cursorsZdefault_paramstyler Zstatement_compilerr Zexecution_ctx_clsr+ �preparerr Z update_copyr Zcolspecsr r. � classmethodr5 r7 rJ Zmemoized_propertyrW rZ r] rb re rf rh rj � __classcell__r r rl r r1 p s2 / r1 c @ s e Zd ZdZdZeZdS )� MariaDBDialect_mysqlconnectorTFN)r r r rn Z_allows_uuid_bindsr- ro r r r r rr � s rr )�__doc__rR �baser r r r r r Zmariadbr � r r r r" r+ r- r. r1 rr r/ Zmariadb_dialectr r r r �<module> s4 ( � � � sqlalchemy/dialects/mysql/__pycache__/aiomysql.cpython-39.pyc 0000644 00000027203 15125143220 0020341 0 ustar 00 a ��Jh ' � @ s� d Z ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z dd l m Z dd l m Z dd l m Z G d d � d �ZG dd� de�ZG dd� de �ZG dd� de�ZG dd� d�ZG dd� de�ZeZdS )a� .. dialect:: mysql+aiomysql :name: aiomysql :dbapi: aiomysql :connectstring: mysql+aiomysql://user:password@host:port/dbname[?key=value&key=value...] :url: https://github.com/aio-libs/aiomysql The aiomysql dialect is SQLAlchemy's second Python asyncio dialect. Using a special asyncio mediation layer, the aiomysql dialect is usable as the backend for the :ref:`SQLAlchemy asyncio <asyncio_toplevel>` extension package. This dialect should normally be used only with the :func:`_asyncio.create_async_engine` engine creation function:: from sqlalchemy.ext.asyncio import create_async_engine engine = create_async_engine( "mysql+aiomysql://user:pass@hostname/dbname?charset=utf8mb4" ) � )�deque� )�MySQLDialect_pymysql� )�pool)�util)�AdaptedConnection)�asyncio)�await_fallback)� await_onlyc @ s� e Zd ZdZdZdd� Zedd� �Zedd� �Zed d � �Z e j d d � �Z ed d � �Z dd� Z d#dd�Z dd� Zdd� Zdd� Zdd� Zdd � Zd d � Zd$d d �Zd!d"� ZdS )%�AsyncAdapt_aiomysql_cursorF)�_adapt_connection� _connection�await_�_cursor�_rowsc C sB || _ |j| _|j| _| j�|jj�}| �|�� �| _t� | _ d S �N) r r r �cursor�dbapi�Cursor� __aenter__r r r ��selfZadapt_connectionr � r �W/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mysql/aiomysql.py�__init__7 s z#AsyncAdapt_aiomysql_cursor.__init__c C s | j jS r )r � description�r r r r r B s z&AsyncAdapt_aiomysql_cursor.descriptionc C s | j jS r )r �rowcountr r r r r F s z#AsyncAdapt_aiomysql_cursor.rowcountc C s | j jS r �r � arraysizer r r r r J s z$AsyncAdapt_aiomysql_cursor.arraysizec C s || j _d S r r �r �valuer r r r N s c C s | j jS r )r � lastrowidr r r r r# R s z$AsyncAdapt_aiomysql_cursor.lastrowidc C s | j �� d S r )r �clearr r r r �closeV s z AsyncAdapt_aiomysql_cursor.closeNc C s | � | �||��S r )r �_execute_async)r � operation� parametersr r r �execute` s z"AsyncAdapt_aiomysql_cursor.executec C s | � | �||��S r )r �_executemany_async�r r' Zseq_of_parametersr r r � executemanyc s �z&AsyncAdapt_aiomysql_cursor.executemanyc � st | j j4 I d H �J | j�||�I d H }| jsBt| j�� I d H �| _|W d �I d H S 1 I d H sf0 Y d S r )r �_execute_mutexr r) � server_sider �fetchallr )r r' r( �resultr r r r& h s z)AsyncAdapt_aiomysql_cursor._execute_asyncc � sT | j j4 I d H �* | j�||�I d H W d �I d H S 1 I d H sF0 Y d S r )r r- r r, r+ r r r r* t s z-AsyncAdapt_aiomysql_cursor._executemany_asyncc G s d S r r )r Z inputsizesr r r � setinputsizesx s z(AsyncAdapt_aiomysql_cursor.setinputsizesc c s | j r| j �� V q d S r �r �popleftr r r r �__iter__{ s z#AsyncAdapt_aiomysql_cursor.__iter__c C s | j r| j �� S d S d S r r2 r r r r �fetchone s z#AsyncAdapt_aiomysql_cursor.fetchonec s4 |d u r| j }| j� � fdd�tt|t� ���D �S )Nc s g | ] }� � � �qS r )r3 )�.0�_��rrr r � <listcomp>� � z8AsyncAdapt_aiomysql_cursor.fetchmany.<locals>.<listcomp>)r r �range�min�len�r �sizer r8 r � fetchmany� s z$AsyncAdapt_aiomysql_cursor.fetchmanyc C s t | j�}| j�� |S r )�listr r$ )r �retvalr r r r/ � s z#AsyncAdapt_aiomysql_cursor.fetchall)N)N)�__name__� __module__� __qualname__r. � __slots__r �propertyr r r �setterr# r% r) r, r& r* r1 r4 r5 rA r/ r r r r r + s. r c @ s> e Zd ZdZdZdd� Zdd� Zdd� Zdd d �Zd d � Z d S )� AsyncAdapt_aiomysql_ss_cursorr Tc C s: || _ |j| _|j| _| j�|jj�}| �|�� �| _d S r )r r r r r �SSCursorr r r r r r r � s z&AsyncAdapt_aiomysql_ss_cursor.__init__c C s$ | j d ur | �| j �� � d | _ d S r )r r r% r r r r r% � s z#AsyncAdapt_aiomysql_ss_cursor.closec C s | � | j�� �S r )r r r5 r r r r r5 � s z&AsyncAdapt_aiomysql_ss_cursor.fetchoneNc C s | � | jj|d��S )N)r@ )r r rA r? r r r rA � s z'AsyncAdapt_aiomysql_ss_cursor.fetchmanyc C s | � | j�� �S r )r r r/ r r r r r/ � s z&AsyncAdapt_aiomysql_ss_cursor.fetchall)N) rD rE rF rG r. r r% r5 rA r/ r r r r rJ � s rJ c @ sh e Zd Zee�ZdZdd� Zdd� Zdd� Z dd � Z dd d �Z d d� Z dd� Z dd� Zdd�dd�ZdS )� AsyncAdapt_aiomysql_connection)r r- c C s || _ || _t�� | _d S r )r r r �Lockr- )r r � connectionr r r r � s z'AsyncAdapt_aiomysql_connection.__init__c C s | � | j�|��S r )r r �ping)r Z reconnectr r r rO � s z#AsyncAdapt_aiomysql_connection.pingc C s | j �� S r )r �character_set_namer r r r rP � s z1AsyncAdapt_aiomysql_connection.character_set_namec C s | � | j�|�� d S r )r r � autocommitr! r r r rQ � s z)AsyncAdapt_aiomysql_connection.autocommitFc C s |r t | �S t| �S d S r )rJ r )r r. r r r r � s z%AsyncAdapt_aiomysql_connection.cursorc C s | � | j�� � d S r )r r �rollbackr r r r rR � s z'AsyncAdapt_aiomysql_connection.rollbackc C s | � | j�� � d S r )r r �commitr r r r rS � s z%AsyncAdapt_aiomysql_connection.commitc C s | j �� d S r )r r% r r r r � terminate� s z(AsyncAdapt_aiomysql_connection.terminateN��returnc C s | � | j�� � d S r )r r Z ensure_closedr r r r r% � s z$AsyncAdapt_aiomysql_connection.close)F)rD rE rF � staticmethodr r rG r rO rP rQ r rR rS rT r% r r r r rL � s rL c @ s e Zd ZdZee�ZdS )�&AsyncAdaptFallback_aiomysql_connectionr N)rD rE rF rG rW r r r r r r rX � s rX c @ s, e Zd Zdd� Zdd� Zdd� Zdd� Zd S ) �AsyncAdapt_aiomysql_dbapic C s. || _ || _d| _| �� | �� \| _| _d S )N�format)�aiomysql�pymysqlZ paramstyle�_init_dbapi_attributes�_init_cursors_subclassesr rK )r r[ r\ r r r r � s z"AsyncAdapt_aiomysql_dbapi.__init__c C s@ dD ]}t | |t| j|�� qdD ]}t | |t| j|�� q"d S )N) �Warning�Error�InterfaceErrorZ DataErrorZ DatabaseErrorZOperationalErrorra ZIntegrityErrorZProgrammingErrorZ InternalErrorZNotSupportedError)�NUMBER�STRINGZDATETIMEZBINARY� TIMESTAMP�Binary)�setattr�getattrr[ r\ )r �namer r r r] � s z0AsyncAdapt_aiomysql_dbapi._init_dbapi_attributesc O sZ |� dd�}|� d| jj�}t�|�r>t| t||i |����S t| t||i |����S d S )N�async_fallbackFZasync_creator_fn) �popr[ �connectr �asboolrX r rL r )r �arg�kwri Z creator_fnr r r rk s ��z!AsyncAdapt_aiomysql_dbapi.connectc C s0 G dd� d| j j�}G dd� d| j j�}||fS )Nc @ s e Zd Zdd� ZdS )zBAsyncAdapt_aiomysql_dbapi._init_cursors_subclasses.<locals>.Cursorc � s d S r r �r �connr r r �_show_warnings s zQAsyncAdapt_aiomysql_dbapi._init_cursors_subclasses.<locals>.Cursor._show_warningsN�rD rE rF rq r r r r r s r c @ s e Zd Zdd� ZdS )zDAsyncAdapt_aiomysql_dbapi._init_cursors_subclasses.<locals>.SSCursorc � s d S r r ro r r r rq s zSAsyncAdapt_aiomysql_dbapi._init_cursors_subclasses.<locals>.SSCursor._show_warningsNrr r r r r rK s rK )r[ r rK )r r rK r r r r^ s z2AsyncAdapt_aiomysql_dbapi._init_cursors_subclassesN)rD rE rF r r] rk r^ r r r r rY � s rY c sv e Zd ZdZdZdZeZdZdZ e dd� �Z e dd� �Z dd�d d �Z � fd d �Z� fd d�Zdd� Zdd� Z� ZS )�MySQLDialect_aiomysqlr[ Tc C s t td�td��S )Nr[ r\ )rY � __import__)�clsr r r � import_dbapi( s �z"MySQLDialect_aiomysql.import_dbapic C s( |j �dd�}t�|�r tjS tjS d S )Nri F)�query�getr rl r Z FallbackAsyncAdaptedQueuePoolZAsyncAdaptedQueuePool)ru �urlri r r r �get_pool_class. s z$MySQLDialect_aiomysql.get_pool_classNrU c C s |� � d S r )rT )r Zdbapi_connectionr r r � do_terminate7 s z"MySQLDialect_aiomysql.do_terminatec s t � j|tddd�d�S )N�user�db)�usernameZdatabase)Z_translate_args)�super�create_connect_args�dict)r ry �� __class__r r r� : s �z)MySQLDialect_aiomysql.create_connect_argsc s, t � �|||�rdS t|��� }d|v S d S )NTz not connected)r � is_disconnect�str�lower)r �erN r Zstr_er� r r r� ? s z#MySQLDialect_aiomysql.is_disconnectc C s ddl m} |jS )Nr )�CLIENT)Zpymysql.constantsr� Z FOUND_ROWS)r r� r r r �_found_rows_client_flagF s z-MySQLDialect_aiomysql._found_rows_client_flagc C s |j S r )r )r rN r r r �get_driver_connectionK s z+MySQLDialect_aiomysql.get_driver_connection)rD rE rF ZdriverZsupports_statement_cacheZ supports_server_side_cursorsrJ Z _sscursor�is_asyncZ has_terminate� classmethodrv rz r{ r� r� r� r� � __classcell__r r r� r rs s rs N)�__doc__� collectionsr r\ r � r r Zenginer Zutil.concurrencyr r r r rJ rL rX rY rs �dialectr r r r �<module> s g (>1 sqlalchemy/dialects/mysql/__pycache__/expression.cpython-39.pyc 0000644 00000007554 15125143220 0020711 0 ustar 00 a ��Jh � @ s� d dl mZ d dl mZ d dlmZ d dlmZ d dlmZ d dlmZ d dlm Z d dlm Z d d l m Z G d d � d e ej �Zd S ) � )�exc)�util)� coercions)�elements)� operators)�roles)� _generative)� Generative)�Selfc s^ e Zd ZdZdZdZ� fdd�Zeed�dd��Z eed�d d ��Z eed�d d ��Z � Z S ) �matchas Produce a ``MATCH (X, Y) AGAINST ('TEXT')`` clause. E.g.:: from sqlalchemy import desc from sqlalchemy.dialects.mysql import match match_expr = match( users_table.c.firstname, users_table.c.lastname, against="Firstname Lastname", ) stmt = ( select(users_table) .where(match_expr.in_boolean_mode()) .order_by(desc(match_expr)) ) Would produce SQL resembling: .. sourcecode:: sql SELECT id, firstname, lastname FROM user WHERE MATCH(firstname, lastname) AGAINST (:param_1 IN BOOLEAN MODE) ORDER BY MATCH(firstname, lastname) AGAINST (:param_2) DESC The :func:`_mysql.match` function is a standalone version of the :meth:`_sql.ColumnElement.match` method available on all SQL expressions, as when :meth:`_expression.ColumnElement.match` is used, but allows to pass multiple columns :param cols: column expressions to match against :param against: expression to be compared towards :param in_boolean_mode: boolean, set "boolean mode" to true :param in_natural_language_mode: boolean , set "natural language" to true :param with_query_expansion: boolean, set "query expansion" to true .. versionadded:: 1.4.19 .. seealso:: :meth:`_expression.ColumnElement.match` Z mysql_matchTc s� |st �d��|�dd �}|d u r,t �d��t�tj|�}tjj t j |d�}d|_ t �|�dd�|�dd�|�dd�d ��}|r�t �d d �|� ��t� j||t j|d � d S ) Nzcolumns are required�againstzagainst is required)ZclausesF�in_boolean_mode�in_natural_language_mode�with_query_expansion)�mysql_boolean_mode�mysql_natural_language�mysql_query_expansionzunknown arguments: %sz, )� modifiers)r � ArgumentError�popr �expectr ZExpressionElementRoler ZBooleanClauseListZ_construct_rawr Zcomma_op�groupr Z immutabledict�join�super�__init__Zmatch_op)�self�cols�kwr �left�flags�� __class__� �Y/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mysql/expression.pyr M s2 �� � �� zmatch.__init__)�returnc C s | j �ddi�| _ | S )z�Apply the "IN BOOLEAN MODE" modifier to the MATCH expression. :return: a new :class:`_mysql.match` instance with modifications applied. r T�r �union�r r" r" r# r o s zmatch.in_boolean_modec C s | j �ddi�| _ | S )z�Apply the "IN NATURAL LANGUAGE MODE" modifier to the MATCH expression. :return: a new :class:`_mysql.match` instance with modifications applied. r Tr% r' r" r" r# r z s z match.in_natural_language_modec C s | j �ddi�| _ | S )z�Apply the "WITH QUERY EXPANSION" modifier to the MATCH expression. :return: a new :class:`_mysql.match` instance with modifications applied. r Tr% r' r" r" r# r � s zmatch.with_query_expansion) �__name__� __module__� __qualname__�__doc__Z__visit_name__Z inherit_cacher r r r r r � __classcell__r" r" r r# r s 3 " r N)� r r Zsqlr r r r Zsql.baser r Z util.typingr ZBinaryExpressionr r" r" r" r# �<module> s sqlalchemy/dialects/mysql/__pycache__/mysqldb.cpython-39.pyc 0000644 00000021051 15125143220 0020151 0 ustar 00 a ��Jh6% � @ s� d Z ddlZddlmZ ddlmZ ddlmZ ddlmZ ddlmZ d d lm Z d d lm Z G d d � d e�Z G dd� de�Z G dd� de�Z e ZdS )a� .. dialect:: mysql+mysqldb :name: mysqlclient (maintained fork of MySQL-Python) :dbapi: mysqldb :connectstring: mysql+mysqldb://<user>:<password>@<host>[:<port>]/<dbname> :url: https://pypi.org/project/mysqlclient/ Driver Status ------------- The mysqlclient DBAPI is a maintained fork of the `MySQL-Python <https://sourceforge.net/projects/mysql-python>`_ DBAPI that is no longer maintained. `mysqlclient`_ supports Python 2 and Python 3 and is very stable. .. _mysqlclient: https://github.com/PyMySQL/mysqlclient-python .. _mysqldb_unicode: Unicode ------- Please see :ref:`mysql_unicode` for current recommendations on unicode handling. .. _mysqldb_ssl: SSL Connections ---------------- The mysqlclient and PyMySQL DBAPIs accept an additional dictionary under the key "ssl", which may be specified using the :paramref:`_sa.create_engine.connect_args` dictionary:: engine = create_engine( "mysql+mysqldb://scott:tiger@192.168.0.134/test", connect_args={ "ssl": { "ca": "/home/gord/client-ssl/ca.pem", "cert": "/home/gord/client-ssl/client-cert.pem", "key": "/home/gord/client-ssl/client-key.pem", } }, ) For convenience, the following keys may also be specified inline within the URL where they will be interpreted into the "ssl" dictionary automatically: "ssl_ca", "ssl_cert", "ssl_key", "ssl_capath", "ssl_cipher", "ssl_check_hostname". An example is as follows:: connection_uri = ( "mysql+mysqldb://scott:tiger@192.168.0.134/test" "?ssl_ca=/home/gord/client-ssl/ca.pem" "&ssl_cert=/home/gord/client-ssl/client-cert.pem" "&ssl_key=/home/gord/client-ssl/client-key.pem" ) .. seealso:: :ref:`pymysql_ssl` in the PyMySQL dialect Using MySQLdb with Google Cloud SQL ----------------------------------- Google Cloud SQL now recommends use of the MySQLdb dialect. Connect using a URL like the following: .. sourcecode:: text mysql+mysqldb://root@/<dbname>?unix_socket=/cloudsql/<projectid>:<instancename> Server Side Cursors ------------------- The mysqldb dialect supports server-side cursors. See :ref:`mysql_ss_cursors`. � N� )� MySQLCompiler)� MySQLDialect)�MySQLExecutionContext)�MySQLIdentifierPreparer)�TEXT� )�sql)�utilc @ s e Zd ZdS )� MySQLExecutionContext_mysqldbN��__name__� __module__� __qualname__� r r �V/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mysql/mysqldb.pyr e s r c @ s e Zd ZdS )�MySQLCompiler_mysqldbNr r r r r r i s r c s� e Zd ZdZdZdZdZdZdZdZ e Z e Z eZ� fdd�Zdd� Zejjdd � �Zed d � �Z� fd d �Zdd� Zd!dd�Z� fdd�Zd"dd�Z dd� Z dd� Z dd � Z d d � Z � fd d �Z!� Z"S )#�MySQLDialect_mysqldbZmysqldbT�formatc s@ t � jf i |�� | jd ur6t| jd�r6| �| jj�nd| _d S )N� __version__�r r r )�super�__init__�dbapi�hasattr�_parse_dbapi_versionr Z_mysql_dbapi_version)�self�kwargs�� __class__r r r { s � ��z MySQLDialect_mysqldb.__init__c C s4 t �d|�}|r,tdd� |�ddd�D ��S dS d S )Nz(\d+)\.(\d+)(?:\.(\d+))?c s s | ]}|d urt |�V qd S �N)�int)�.0�xr r r � <genexpr>� � z<MySQLDialect_mysqldb._parse_dbapi_version.<locals>.<genexpr>r � r r )�re�match�tuple�group)r �version�mr r r r � s z)MySQLDialect_mysqldb._parse_dbapi_versionc C s6 zt d�j}|j| _W dS ttfy0 Y dS 0 d S )NzMySQLdb.cursorsTF)� __import__�cursorsZSSCursorZ _sscursor� ImportError�AttributeError)r r. r r r � supports_server_side_cursors� s z1MySQLDialect_mysqldb.supports_server_side_cursorsc C s t d�S )NZMySQLdb)r- )�clsr r r � import_dbapi� s z!MySQLDialect_mysqldb.import_dbapic s t � �� � � fdd�}|S )Nc sB � d ur� | � | � � }|d ur>| �� }|�d| � |�� d S )Nz SET NAMES %s)�character_set_name�cursor�execute�close)�conn� charset_namer5 �Zsuper_r r � on_connect� s z3MySQLDialect_mysqldb.on_connect.<locals>.on_connect)r r; )r r; r r: r r; � s z MySQLDialect_mysqldb.on_connectc C s |� � dS )NT)Zping�r �dbapi_connectionr r r �do_ping� s z MySQLDialect_mysqldb.do_pingNc C s |� ||�}|d ur||_d S r )Z executemanyZ _rowcount)r r5 Z statement� parameters�contextZrowcountr r r �do_executemany� s z#MySQLDialect_mysqldb.do_executemanyc sn |� d| j�d�| j�d�f ��� }| jdko2|}|r\t�t�t�d�t dd��d�g}ng }t � � ||�S ) Nz:show collation where %s = 'utf8mb4' and %s = 'utf8mb4_bin'�CharsetZ Collation)� z'test collated returns'Zutf8mb4)�charsetZ utf8mb4_bin) Zexec_driver_sqlZidentifier_preparer�quoteZscalarZserver_version_infor Zcollate�castZliteral_columnr r �_check_unicode_returns)r � connectionZ collationZhas_utf8mb4_binZadditional_testsr r r rG � s& ������ z+MySQLDialect_mysqldb._check_unicode_returnsc C sX |d u rt dddd�}|jf i |��}|�|j� t�|dt� t�|dt� t�|dt� t�|dt� t�|d t� t�|d t� t�|d t� t�|d t� i }d tfdtfdtfdtfdtfdtfg}|D ]@\}}||v r�|| ||dd � < t�||dd � |� ||= q�|�r"||d< |� d d�}| � � } | d u�rP|| O }||d < g |gS )N�db�user�passwd)Zdatabase�username�password�compress�connect_timeout� read_timeoutZ write_timeout� client_flagZ local_infileZ use_unicoderD Zssl_caZssl_keyZssl_certZ ssl_capathZ ssl_cipherZssl_check_hostname� �sslr ) �dictZtranslate_connect_args�update�queryr Zcoerce_kw_type�boolr! �str�get�_found_rows_client_flag) r �urlZ_translate_args�optsrS �keys�keyZkw_typerQ Zclient_flag_found_rowsr r r �create_connect_args� sF � � z(MySQLDialect_mysqldb.create_connect_argsc C sL | j d urDzt| j jd �jj}W n ttfy: Y d S 0 |jS nd S d S )Nz.constants.CLIENT)r r- r � constantsZCLIENTr0 r/ Z FOUND_ROWS)r Z CLIENT_FLAGSr r r rZ � s � z,MySQLDialect_mysqldb._found_rows_client_flagc C s |j d S )Nr )�args)r � exceptionr r r �_extract_error_code s z(MySQLDialect_mysqldb._extract_error_codec C s6 z |j j}W n ty* t�d� Y dS 0 |� S dS )z:Sniff out the character set in use for connection results.z�No 'character_set_name' can be detected with this MySQL-Python version; please upgrade to a recent version of MySQL-Python. Assuming latin1.�latin1N)rH r4 r0 r �warn)r rH Z cset_namer r r �_detect_charset s �z$MySQLDialect_mysqldb._detect_charsetc C s dS )N)Z SERIALIZABLEzREAD UNCOMMITTEDzREAD COMMITTEDzREPEATABLE READ� AUTOCOMMITr r< r r r �get_isolation_level_values s z/MySQLDialect_mysqldb.get_isolation_level_valuesc s0 |dkr|� d� n|� d� t� �||� d S )Nrg TF)Z autocommitr �set_isolation_level)r r= �levelr r r ri ) s z(MySQLDialect_mysqldb.set_isolation_level)N)N)#r r r ZdriverZsupports_statement_cacheZsupports_unicode_statementsZsupports_sane_rowcountZ supports_sane_multi_rowcountZsupports_native_decimalZdefault_paramstyler Zexecution_ctx_clsr Zstatement_compilerr �preparerr r r Z langhelpersZmemoized_propertyr1 � classmethodr3 r; r> rA rG r_ rZ rc rf rh ri � __classcell__r r r r r m s4 3 r )�__doc__r' �baser r r r r � r r r r r �dialectr r r r �<module> s P E sqlalchemy/dialects/mysql/__pycache__/reserved_words.cpython-39.pyc 0000644 00000010342 15125143220 0021534 0 ustar 00 a ��Jh*$ � @ s h d �� h d��Zh d�ZdS )>� � day_second� straight_join�releaseZparse_vcol_exprZ page_checksum�loop� high_priority�ignore_server_ids�float4�analyze� current_user�call�distinct�group� deterministic�int8�rename�div�sql_calc_found_rows�starting�ignore� low_priority�double�update�index�longblob�set�day_microsecond�grant�sqlstate� utc_timestamp�binary�change�keys�with�maxvalue�while�float8�delete�int2�range�or�localtimestamp�is�enclosed� master_ssl_verify_server_cert� varbinary�specific� sqlexception�continue�desc� references� localtime� insensitive�over�undo�check�foreign�null�create�window�having�hour_microsecond�add�where�write�usage�decimal�iterate� hour_second�outfile�collate�sql_big_result�asc�resignalZignore_domain_ids� character�join�position� sqlwarning� terminated�to�innerZstats_sample_pages�left�zerofill�offsetZ current_role�bigintZ do_domain_ids�optimize� condition�database� procedure�union�column�reads�between�schemas�then�mod� hour_minute�default�use�cross�show�else�force�interval�tinytext�as�declare�key� precision� partition�read�kill�using� mediumblob�char� mediumint�smallint�leave� recursive�insert� constraint�xor�right�delayed�unlock�lock�varchar�fulltext�trailing�match� current_date�for�exit� intersect�replace�unique�slow�utc_time�alterZ ref_system_id�linear�return�rlike�ssl�table�unsigned�long�varying�cursor�master_heartbeat_period�blob�current_timestamp�second_microsecond�lines�into� asensitive�utc_date�values� mediumtext�fetch�if�numeric�tinyint�float�trigger�load�when�order�int3�int1�cascade�day_hour�except�naturalZ returning�int4�and�dec�describe�existsZstats_persistent�drop� minute_second�out�true�each�from� optionally�by�outer�int� row_number�sql_small_result� year_month� middleint�restrict�require� distinctrow�purge�limit�rows�sqlZstats_auto_recalc�explain�inout�minute_microsecond� current_time�regexp� read_write�tinyblob�convert�no_write_to_binlog�infile�on�real�both�leading�like�modifies�false�general�select� varcharacter�primary�longtext�repeat� databases�schema�case�all�signal�escaped� sensitive�elseif�before�integer� accessible�not�dual�revoke�spatial�in� day_minute� separator�option> �bodyZothers�historyZwithout�package�gotoZelsifZperiod�raiseZrowtypeZ system_time�systemZ versioning> Z first_valueZ master_bind�grouping�groupsZrankr r r rY r r r r r r r r r r r Z json_tabler r r Z cume_distr r r r r r r r r r �getr r r r Z nth_valuer r! r" r# r$ r% r& r' r( r) r* r+ r, r- r. Zget_master_public_keyr/ r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 r: r; r< �parallelr= r> r? Zsql_after_gtidsr@ rA rB Zio_after_gtidsrC ZlateralrD rF rE rG rH rI rJ rK rM rN rO rP rR rQ rT �arrayrU �functionrV rW rX ZqualifyrZ r[ r\ r] r^ r_ r` ra rb rc Zpersistre rf rg Zlagrd ri rj rk rl rm rn ro rp rq rr rs rt ru rv rw rx Zoptimizer_costsry rz r{ Z percent_rankr| r} � last_valuer~ Zio_before_gtidsr r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� �roler� Zsql_before_gtidsr� r� r� �rowr� r� r� r� r� r� Z dense_rankr� r� Z persist_onlyr� r� r� r� Zntiler� r� r� Zparse_gcol_exprr� r� r� r� Zleadr� r� r� r� r� r� r� Zcuber� r� r� �memberr� r� rh r� Zofr� r� r� r� r� r� �emptyr� r� r� r� Zadminr� r� r� r� r� r� r� r� r� r� r� r� � generatedr� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� Zvirtualr� r� r� r� r� r� r� r� r� r� r� Zstoredr� r� r� r� r� N)rY ZRESERVED_WORDS_MARIADBZRESERVED_WORDS_MYSQL� r r �]/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mysql/reserved_words.py�<module> s }� � sqlalchemy/dialects/mysql/__pycache__/json.cpython-39.pyc 0000644 00000005530 15125143220 0017453 0 ustar 00 a ��Jh� � @ s\ d dl mZ G dd� dej�ZG dd� d�ZG dd� deejj�ZG dd � d eejj�Zd S ) � )�typesc @ s e Zd ZdZdS )�JSONa� MySQL JSON type. MySQL supports JSON as of version 5.7. MariaDB supports JSON (as an alias for LONGTEXT) as of version 10.2. :class:`_mysql.JSON` is used automatically whenever the base :class:`_types.JSON` datatype is used against a MySQL or MariaDB backend. .. seealso:: :class:`_types.JSON` - main documentation for the generic cross-platform JSON datatype. The :class:`.mysql.JSON` type supports persistence of JSON values as well as the core index operations provided by :class:`_types.JSON` datatype, by adapting the operations to render the ``JSON_EXTRACT`` function at the database level. N)�__name__� __module__� __qualname__�__doc__� r r �S/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mysql/json.pyr s r c @ s$ e Zd Zdd� Zdd� Zdd� ZdS )�_FormatTypeMixinc C s t � �d S �N)�NotImplementedError��self�valuer r r � _format_value% s z _FormatTypeMixin._format_valuec s � � |��� �fdd�}|S )Nc s � � | �} �r�| �} | S r �r �r �r Z super_procr r �process+ s z0_FormatTypeMixin.bind_processor.<locals>.process)Zstring_bind_processor�r �dialectr r r r �bind_processor( s z _FormatTypeMixin.bind_processorc s � � |��� �fdd�}|S )Nc s � � | �} �r�| �} | S r r r r r r r 6 s z3_FormatTypeMixin.literal_processor.<locals>.process)Zstring_literal_processorr r r r �literal_processor3 s z"_FormatTypeMixin.literal_processorN)r r r r r r r r r r r $ s r c @ s e Zd Zdd� ZdS )� JSONIndexTypec C s t |t�rd| }nd| }|S )Nz$[%s]z$."%s"�� isinstance�intr r r r r @ s zJSONIndexType._format_valueN�r r r r r r r r r ? s r c @ s e Zd Zdd� ZdS )� JSONPathTypec C s dd� dd� |D �� S )Nz$%s� c S s& g | ] }t |t�rd | nd| �qS )z[%s]z."%s"r )�.0�elemr r r � <listcomp>L s �z.JSONPathType._format_value.<locals>.<listcomp>)�joinr r r r r I s ���zJSONPathType._format_valueNr r r r r r H s r N)r r Zsqltypesr r r r r r r r �<module> s sqlalchemy/dialects/mysql/__pycache__/enumerated.cpython-39.pyc 0000644 00000017414 15125143220 0020637 0 ustar 00 a ��Jh� � @ sp d dl Z ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ G d d � d ejej e�Z G d d � d e�Z dS ) � N� )� _StringType� )�exc)�sql)�util)�sqltypesc sD e Zd ZdZd ZdZdd� Zedd� �Z� fdd�Z d d � Z � Z S ) �ENUMzMySQL ENUM type.Tc O s4 |� dd� | �||� tj| fd| ji|�� dS )a� Construct an ENUM. E.g.:: Column("myenum", ENUM("foo", "bar", "baz")) :param enums: The range of valid values for this ENUM. Values in enums are not quoted, they will be escaped and surrounded by single quotes when generating the schema. This object may also be a PEP-435-compliant enumerated type. .. versionadded: 1.1 added support for PEP-435-compliant enumerated types. :param strict: This flag has no effect. .. versionchanged:: The MySQL ENUM type as well as the base Enum type now validates all Python data values. :param charset: Optional, a column-level character set for this string value. Takes precedence to 'ascii' or 'unicode' short-hand. :param collation: Optional, a column-level collation for this string value. Takes precedence to 'binary' short-hand. :param ascii: Defaults to False: short-hand for the ``latin1`` character set, generates ASCII in schema. :param unicode: Defaults to False: short-hand for the ``ucs2`` character set, generates UNICODE in schema. :param binary: Defaults to False: short-hand, pick the binary collation type that matches the column's character set. Generates BINARY in schema. This does not affect the type of data stored, only the collation of character data. �strictN�length)�popZ _enum_initr �__init__r )�self�enums�kw� r �Y/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mysql/enumerated.pyr s & z ENUM.__init__c K s8 |� d|j� |� d|j� |� d|j� | f i |��S )zXProduce a MySQL native :class:`.mysql.ENUM` from plain :class:`.Enum`. �validate_strings�values_callableZ omit_aliases)� setdefaultr r Z _omit_aliases)�cls�implr r r r �adapt_emulated_to_nativeD s z ENUM.adapt_emulated_to_nativec s |dkr |S t � �|�S d S )N� )�super�_object_value_for_elem)r �elem�� __class__r r r O s zENUM._object_value_for_elemc C s t j| tttjgd�S )N)� to_inspect)r � generic_reprr r r �Enum�r r r r �__repr__Y s �z ENUM.__repr__) �__name__� __module__� __qualname__�__doc__�__visit_name__Z native_enumr � classmethodr r r# � __classcell__r r r r r s * r c sT e Zd ZdZd Z� fdd�Zdd� Z� fdd�Z� fdd �Zd d � Z d d � Z � Z S )�SETzMySQL SET type.c s� |� dd�| _t|�| _| js0d|v r0t�d��| jrhdd� t| j�D �| _| j�dd� t| j�D �� t d d � |D �d g �}|� d |� t � j f i |�� d S )a Construct a SET. E.g.:: Column("myset", SET("foo", "bar", "baz")) The list of potential values is required in the case that this set will be used to generate DDL for a table, or if the :paramref:`.SET.retrieve_as_bitwise` flag is set to True. :param values: The range of valid values for this SET. The values are not quoted, they will be escaped and surrounded by single quotes when generating the schema. :param convert_unicode: Same flag as that of :paramref:`.String.convert_unicode`. :param collation: same as that of :paramref:`.String.collation` :param charset: same as that of :paramref:`.VARCHAR.charset`. :param ascii: same as that of :paramref:`.VARCHAR.ascii`. :param unicode: same as that of :paramref:`.VARCHAR.unicode`. :param binary: same as that of :paramref:`.VARCHAR.binary`. :param retrieve_as_bitwise: if True, the data for the set type will be persisted and selected using an integer value, where a set is coerced into a bitwise mask for persistence. MySQL allows this mode which has the advantage of being able to store values unambiguously, such as the blank string ``''``. The datatype will appear as the expression ``col + 0`` in a SELECT statement, so that the value is coerced into an integer value in result sets. This flag is required if one wishes to persist a set that can store the blank string ``''`` as a value. .. warning:: When using :paramref:`.mysql.SET.retrieve_as_bitwise`, it is essential that the list of set values is expressed in the **exact same order** as exists on the MySQL database. �retrieve_as_bitwiseFr zNCan't use the blank value '' in a SET without setting retrieve_as_bitwise=Truec S s i | ]\}}|d | �qS )� r ��.0�idx�valuer r r � <dictcomp>� s z SET.__init__.<locals>.<dictcomp>c s s | ]\}}d | |fV qdS )r- Nr r. r r r � <genexpr>� s z SET.__init__.<locals>.<genexpr>c S s g | ] }t |��qS r )�len)r/ �vr r r � <listcomp>� � z SET.__init__.<locals>.<listcomp>r r N) r r, �tuple�valuesr � ArgumentError� enumerate�_bitmap�update�maxr r r )r r9 r r r r r r d s - �� � z SET.__init__c C s( | j r t�t�|tj�d | �S |S d S �Nr )r, r Z type_coercer ZInteger)r Zcolexprr r r �column_expression� s �zSET.column_expressionc s2 � j r� fdd�}nt� �||���fdd�}|S )Nc s, | d ur$t | �} tt�� jj| ��S d S d S )N)�int�setr Zmap_bitsr< � __getitem__�r1 r" r r �process� s z%SET.result_processor.<locals>.processc s@ t | t�r&� r� | �} tt�d| ��S | d ur8| �d� | S d S )Nz[^,]+r )� isinstance�strrB �re�findall�discardrD �� super_convertr r rE � s )r, r �result_processor)r �dialectZcoltyperE r �r rL r rM � s zSET.result_processorc s2 t � �|��� jr"� �fdd�}n �fdd�}|S )Nc sP | d u r d S t | ttf�r,�r&�| �S | S n d}| D ]}|� j| O }q4|S d S r? )rF rA rG r< )r1 Z int_valuer5 rO r r rE � s z#SET.bind_processor.<locals>.processc s4 | d ur t | ttf�s d�| �} � r,� | �S | S d S )N�,)rF rA rG �joinrD rK r r rE � s )r �bind_processorr, )r rN rE r rO r rR � s zSET.bind_processorc K s& | j |d< tj| |g| j�R i |��S )Nr, )r, r Zconstructor_copyr9 )r Zimpltyper r r r �adapt� s z SET.adaptc C s t j| ttgdgd�S )N)r, F)r Z additional_kw)r r r+ r r" r r r r# � s ��z SET.__repr__) r$ r% r& r' r( r r@ rM rR rS r# r* r r r r r+ _ s ? r+ ) rH �typesr r r r r r ZNativeForEmulatedr! r r+ r r r r �<module> s L sqlalchemy/dialects/mysql/__pycache__/base.cpython-39.pyc 0000644 00000313617 15125143220 0017424 0 ustar 00 a ��Jhh� � % @ sh d Z ddlmZ ddlmZ ddlmZ ddlmZ ddl Z ddl m Z dd l m Z dd lmZ dd lmZ dd lmZ dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z ddlm Z ddlm Z ddlm Z ddlm Z ddlm!Z! ddlm"Z" ddlm#Z# ddlm$Z$ dd lm%Z% dd lm&Z& dd lm'Z' dd lm(Z( dd lm)Z) dd!lm*Z* dd"lm+Z+ dd#lm,Z, dd$lm-Z- dd%lm.Z. dd&lm/Z/ dd'lm0Z0 dd(lm1Z1 dd)lm2Z2 dd*lm3Z3 dd+lm4Z4 dd,lm5Z5 dd-lm6Z6 dd.lm7Z7 dd/lm8Z8 d0d1l m9Z9 d0d2l m:Z: d0d3l m;Z; d0d4l m<Z= d0d5l m>Z> d0d6l m?Z? d0d7l@mAZB d0d8l@mCZC d0d l@m Z d0d9lDmEZE d0d:l>mFZF d0d;l>mGZG d0d<l>mHZH d0d=l>mIZI d0d>l>mJZJ d0d?l>mKZK d0d@l>mLZL d0d6l>m?ZM d0dAl>mNZN d0dBlOmPZP d0dClOmQZQ d0dDlRmSZS d0dElmTZT d0dFlmUZU d0dGlmVZV d0dHlmWZW d0dIlmXZX d0dJlmYZY d0dKl?mZZZ e �[dLe j\e j]B �Z^e2Z_eZ`eZae'Zbe)Zce4ZdeUZeeTZfeYZge,Zhe.Zie!Zje7Zke(Zle+Zme6Zne1Zoe8Zpe3Zqe Zre0Zse5Zte*Zue Zve-Zwe#Zxe$Zye/Zze%Z{e&Z|eee e eeeLj}e-eLj~e%eLje$eLj�e2eLj�eeLj�e eLjeeLjjeeLjjei Z�e eTe eUeVe!eWe"e#e$ee#e%e&e&ee'e(e)e*e+e,e.e-ee0e1e2e3e4e5e6eXeYe7e8dM�$Z�G dNdO� dOeCj��Z�G dPdQ� dQeGjQ�Z�G dRdS� dSeGj��Z�G dTdU� dUeGj��Z�G dVdW� dWeGj��Z�G dXdY� dYe��Z�e;j�G dZd[� d[eCj���Z�G d\d]� d]�Z�e>j�d^e>��d_e7d`��e>��dae7d`��e>��dbe7d`��dcd4�Z�dS )daߕ .. dialect:: mysql :name: MySQL / MariaDB :normal_support: 5.6+ / 10+ :best_effort: 5.0.2+ / 5.0.2+ Supported Versions and Features ------------------------------- SQLAlchemy supports MySQL starting with version 5.0.2 through modern releases, as well as all modern versions of MariaDB. See the official MySQL documentation for detailed information about features supported in any given server release. .. versionchanged:: 1.4 minimum MySQL version supported is now 5.0.2. MariaDB Support ~~~~~~~~~~~~~~~ The MariaDB variant of MySQL retains fundamental compatibility with MySQL's protocols however the development of these two products continues to diverge. Within the realm of SQLAlchemy, the two databases have a small number of syntactical and behavioral differences that SQLAlchemy accommodates automatically. To connect to a MariaDB database, no changes to the database URL are required:: engine = create_engine( "mysql+pymysql://user:pass@some_mariadb/dbname?charset=utf8mb4" ) Upon first connect, the SQLAlchemy dialect employs a server version detection scheme that determines if the backing database reports as MariaDB. Based on this flag, the dialect can make different choices in those of areas where its behavior must be different. .. _mysql_mariadb_only_mode: MariaDB-Only Mode ~~~~~~~~~~~~~~~~~ The dialect also supports an **optional** "MariaDB-only" mode of connection, which may be useful for the case where an application makes use of MariaDB-specific features and is not compatible with a MySQL database. To use this mode of operation, replace the "mysql" token in the above URL with "mariadb":: engine = create_engine( "mariadb+pymysql://user:pass@some_mariadb/dbname?charset=utf8mb4" ) The above engine, upon first connect, will raise an error if the server version detection detects that the backing database is not MariaDB. When using an engine with ``"mariadb"`` as the dialect name, **all mysql-specific options that include the name "mysql" in them are now named with "mariadb"**. This means options like ``mysql_engine`` should be named ``mariadb_engine``, etc. Both "mysql" and "mariadb" options can be used simultaneously for applications that use URLs with both "mysql" and "mariadb" dialects:: my_table = Table( "mytable", metadata, Column("id", Integer, primary_key=True), Column("textdata", String(50)), mariadb_engine="InnoDB", mysql_engine="InnoDB", ) Index( "textdata_ix", my_table.c.textdata, mysql_prefix="FULLTEXT", mariadb_prefix="FULLTEXT", ) Similar behavior will occur when the above structures are reflected, i.e. the "mariadb" prefix will be present in the option names when the database URL is based on the "mariadb" name. .. versionadded:: 1.4 Added "mariadb" dialect name supporting "MariaDB-only mode" for the MySQL dialect. .. _mysql_connection_timeouts: Connection Timeouts and Disconnects ----------------------------------- MySQL / MariaDB feature an automatic connection close behavior, for connections that have been idle for a fixed period of time, defaulting to eight hours. To circumvent having this issue, use the :paramref:`_sa.create_engine.pool_recycle` option which ensures that a connection will be discarded and replaced with a new one if it has been present in the pool for a fixed number of seconds:: engine = create_engine("mysql+mysqldb://...", pool_recycle=3600) For more comprehensive disconnect detection of pooled connections, including accommodation of server restarts and network issues, a pre-ping approach may be employed. See :ref:`pool_disconnects` for current approaches. .. seealso:: :ref:`pool_disconnects` - Background on several techniques for dealing with timed out connections as well as database restarts. .. _mysql_storage_engines: CREATE TABLE arguments including Storage Engines ------------------------------------------------ Both MySQL's and MariaDB's CREATE TABLE syntax includes a wide array of special options, including ``ENGINE``, ``CHARSET``, ``MAX_ROWS``, ``ROW_FORMAT``, ``INSERT_METHOD``, and many more. To accommodate the rendering of these arguments, specify the form ``mysql_argument_name="value"``. For example, to specify a table with ``ENGINE`` of ``InnoDB``, ``CHARSET`` of ``utf8mb4``, and ``KEY_BLOCK_SIZE`` of ``1024``:: Table( "mytable", metadata, Column("data", String(32)), mysql_engine="InnoDB", mysql_charset="utf8mb4", mysql_key_block_size="1024", ) When supporting :ref:`mysql_mariadb_only_mode` mode, similar keys against the "mariadb" prefix must be included as well. The values can of course vary independently so that different settings on MySQL vs. MariaDB may be maintained:: # support both "mysql" and "mariadb-only" engine URLs Table( "mytable", metadata, Column("data", String(32)), mysql_engine="InnoDB", mariadb_engine="InnoDB", mysql_charset="utf8mb4", mariadb_charset="utf8", mysql_key_block_size="1024", mariadb_key_block_size="1024", ) The MySQL / MariaDB dialects will normally transfer any keyword specified as ``mysql_keyword_name`` to be rendered as ``KEYWORD_NAME`` in the ``CREATE TABLE`` statement. A handful of these names will render with a space instead of an underscore; to support this, the MySQL dialect has awareness of these particular names, which include ``DATA DIRECTORY`` (e.g. ``mysql_data_directory``), ``CHARACTER SET`` (e.g. ``mysql_character_set``) and ``INDEX DIRECTORY`` (e.g. ``mysql_index_directory``). The most common argument is ``mysql_engine``, which refers to the storage engine for the table. Historically, MySQL server installations would default to ``MyISAM`` for this value, although newer versions may be defaulting to ``InnoDB``. The ``InnoDB`` engine is typically preferred for its support of transactions and foreign keys. A :class:`_schema.Table` that is created in a MySQL / MariaDB database with a storage engine of ``MyISAM`` will be essentially non-transactional, meaning any INSERT/UPDATE/DELETE statement referring to this table will be invoked as autocommit. It also will have no support for foreign key constraints; while the ``CREATE TABLE`` statement accepts foreign key options, when using the ``MyISAM`` storage engine these arguments are discarded. Reflecting such a table will also produce no foreign key constraint information. For fully atomic transactions as well as support for foreign key constraints, all participating ``CREATE TABLE`` statements must specify a transactional engine, which in the vast majority of cases is ``InnoDB``. Partitioning can similarly be specified using similar options. In the example below the create table will specify ``PARTITION_BY``, ``PARTITIONS``, ``SUBPARTITIONS`` and ``SUBPARTITION_BY``:: # can also use mariadb_* prefix Table( "testtable", MetaData(), Column("id", Integer(), primary_key=True, autoincrement=True), Column("other_id", Integer(), primary_key=True, autoincrement=False), mysql_partitions="2", mysql_partition_by="KEY(other_id)", mysql_subpartition_by="HASH(some_expr)", mysql_subpartitions="2", ) This will render: .. sourcecode:: sql CREATE TABLE testtable ( id INTEGER NOT NULL AUTO_INCREMENT, other_id INTEGER NOT NULL, PRIMARY KEY (id, other_id) )PARTITION BY KEY(other_id) PARTITIONS 2 SUBPARTITION BY HASH(some_expr) SUBPARTITIONS 2 Case Sensitivity and Table Reflection ------------------------------------- Both MySQL and MariaDB have inconsistent support for case-sensitive identifier names, basing support on specific details of the underlying operating system. However, it has been observed that no matter what case sensitivity behavior is present, the names of tables in foreign key declarations are *always* received from the database as all-lower case, making it impossible to accurately reflect a schema where inter-related tables use mixed-case identifier names. Therefore it is strongly advised that table names be declared as all lower case both within SQLAlchemy as well as on the MySQL / MariaDB database itself, especially if database reflection features are to be used. .. _mysql_isolation_level: Transaction Isolation Level --------------------------- All MySQL / MariaDB dialects support setting of transaction isolation level both via a dialect-specific parameter :paramref:`_sa.create_engine.isolation_level` accepted by :func:`_sa.create_engine`, as well as the :paramref:`.Connection.execution_options.isolation_level` argument as passed to :meth:`_engine.Connection.execution_options`. This feature works by issuing the command ``SET SESSION TRANSACTION ISOLATION LEVEL <level>`` for each new connection. For the special AUTOCOMMIT isolation level, DBAPI-specific techniques are used. To set isolation level using :func:`_sa.create_engine`:: engine = create_engine( "mysql+mysqldb://scott:tiger@localhost/test", isolation_level="READ UNCOMMITTED", ) To set using per-connection execution options:: connection = engine.connect() connection = connection.execution_options(isolation_level="READ COMMITTED") Valid values for ``isolation_level`` include: * ``READ COMMITTED`` * ``READ UNCOMMITTED`` * ``REPEATABLE READ`` * ``SERIALIZABLE`` * ``AUTOCOMMIT`` The special ``AUTOCOMMIT`` value makes use of the various "autocommit" attributes provided by specific DBAPIs, and is currently supported by MySQLdb, MySQL-Client, MySQL-Connector Python, and PyMySQL. Using it, the database connection will return true for the value of ``SELECT @@autocommit;``. There are also more options for isolation level configurations, such as "sub-engine" objects linked to a main :class:`_engine.Engine` which each apply different isolation level settings. See the discussion at :ref:`dbapi_autocommit` for background. .. seealso:: :ref:`dbapi_autocommit` AUTO_INCREMENT Behavior ----------------------- When creating tables, SQLAlchemy will automatically set ``AUTO_INCREMENT`` on the first :class:`.Integer` primary key column which is not marked as a foreign key:: >>> t = Table( ... "mytable", metadata, Column("mytable_id", Integer, primary_key=True) ... ) >>> t.create() CREATE TABLE mytable ( id INTEGER NOT NULL AUTO_INCREMENT, PRIMARY KEY (id) ) You can disable this behavior by passing ``False`` to the :paramref:`_schema.Column.autoincrement` argument of :class:`_schema.Column`. This flag can also be used to enable auto-increment on a secondary column in a multi-column key for some storage engines:: Table( "mytable", metadata, Column("gid", Integer, primary_key=True, autoincrement=False), Column("id", Integer, primary_key=True), ) .. _mysql_ss_cursors: Server Side Cursors ------------------- Server-side cursor support is available for the mysqlclient, PyMySQL, mariadbconnector dialects and may also be available in others. This makes use of either the "buffered=True/False" flag if available or by using a class such as ``MySQLdb.cursors.SSCursor`` or ``pymysql.cursors.SSCursor`` internally. Server side cursors are enabled on a per-statement basis by using the :paramref:`.Connection.execution_options.stream_results` connection execution option:: with engine.connect() as conn: result = conn.execution_options(stream_results=True).execute( text("select * from table") ) Note that some kinds of SQL statements may not be supported with server side cursors; generally, only SQL statements that return rows should be used with this option. .. deprecated:: 1.4 The dialect-level server_side_cursors flag is deprecated and will be removed in a future release. Please use the :paramref:`_engine.Connection.stream_results` execution option for unbuffered cursor support. .. seealso:: :ref:`engine_stream_results` .. _mysql_unicode: Unicode ------- Charset Selection ~~~~~~~~~~~~~~~~~ Most MySQL / MariaDB DBAPIs offer the option to set the client character set for a connection. This is typically delivered using the ``charset`` parameter in the URL, such as:: e = create_engine( "mysql+pymysql://scott:tiger@localhost/test?charset=utf8mb4" ) This charset is the **client character set** for the connection. Some MySQL DBAPIs will default this to a value such as ``latin1``, and some will make use of the ``default-character-set`` setting in the ``my.cnf`` file as well. Documentation for the DBAPI in use should be consulted for specific behavior. The encoding used for Unicode has traditionally been ``'utf8'``. However, for MySQL versions 5.5.3 and MariaDB 5.5 on forward, a new MySQL-specific encoding ``'utf8mb4'`` has been introduced, and as of MySQL 8.0 a warning is emitted by the server if plain ``utf8`` is specified within any server-side directives, replaced with ``utf8mb3``. The rationale for this new encoding is due to the fact that MySQL's legacy utf-8 encoding only supports codepoints up to three bytes instead of four. Therefore, when communicating with a MySQL or MariaDB database that includes codepoints more than three bytes in size, this new charset is preferred, if supported by both the database as well as the client DBAPI, as in:: e = create_engine( "mysql+pymysql://scott:tiger@localhost/test?charset=utf8mb4" ) All modern DBAPIs should support the ``utf8mb4`` charset. In order to use ``utf8mb4`` encoding for a schema that was created with legacy ``utf8``, changes to the MySQL/MariaDB schema and/or server configuration may be required. .. seealso:: `The utf8mb4 Character Set \ <https://dev.mysql.com/doc/refman/5.5/en/charset-unicode-utf8mb4.html>`_ - \ in the MySQL documentation .. _mysql_binary_introducer: Dealing with Binary Data Warnings and Unicode ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ MySQL versions 5.6, 5.7 and later (not MariaDB at the time of this writing) now emit a warning when attempting to pass binary data to the database, while a character set encoding is also in place, when the binary data itself is not valid for that encoding: .. sourcecode:: text default.py:509: Warning: (1300, "Invalid utf8mb4 character string: 'F9876A'") cursor.execute(statement, parameters) This warning is due to the fact that the MySQL client library is attempting to interpret the binary string as a unicode object even if a datatype such as :class:`.LargeBinary` is in use. To resolve this, the SQL statement requires a binary "character set introducer" be present before any non-NULL value that renders like this: .. sourcecode:: sql INSERT INTO table (data) VALUES (_binary %s) These character set introducers are provided by the DBAPI driver, assuming the use of mysqlclient or PyMySQL (both of which are recommended). Add the query string parameter ``binary_prefix=true`` to the URL to repair this warning:: # mysqlclient engine = create_engine( "mysql+mysqldb://scott:tiger@localhost/test?charset=utf8mb4&binary_prefix=true" ) # PyMySQL engine = create_engine( "mysql+pymysql://scott:tiger@localhost/test?charset=utf8mb4&binary_prefix=true" ) The ``binary_prefix`` flag may or may not be supported by other MySQL drivers. SQLAlchemy itself cannot render this ``_binary`` prefix reliably, as it does not work with the NULL value, which is valid to be sent as a bound parameter. As the MySQL driver renders parameters directly into the SQL string, it's the most efficient place for this additional keyword to be passed. .. seealso:: `Character set introducers <https://dev.mysql.com/doc/refman/5.7/en/charset-introducer.html>`_ - on the MySQL website ANSI Quoting Style ------------------ MySQL / MariaDB feature two varieties of identifier "quoting style", one using backticks and the other using quotes, e.g. ```some_identifier``` vs. ``"some_identifier"``. All MySQL dialects detect which version is in use by checking the value of :ref:`sql_mode<mysql_sql_mode>` when a connection is first established with a particular :class:`_engine.Engine`. This quoting style comes into play when rendering table and column names as well as when reflecting existing database structures. The detection is entirely automatic and no special configuration is needed to use either quoting style. .. _mysql_sql_mode: Changing the sql_mode --------------------- MySQL supports operating in multiple `Server SQL Modes <https://dev.mysql.com/doc/refman/8.0/en/sql-mode.html>`_ for both Servers and Clients. To change the ``sql_mode`` for a given application, a developer can leverage SQLAlchemy's Events system. In the following example, the event system is used to set the ``sql_mode`` on the ``first_connect`` and ``connect`` events:: from sqlalchemy import create_engine, event eng = create_engine( "mysql+mysqldb://scott:tiger@localhost/test", echo="debug" ) # `insert=True` will ensure this is the very first listener to run @event.listens_for(eng, "connect", insert=True) def connect(dbapi_connection, connection_record): cursor = dbapi_connection.cursor() cursor.execute("SET sql_mode = 'STRICT_ALL_TABLES'") conn = eng.connect() In the example illustrated above, the "connect" event will invoke the "SET" statement on the connection at the moment a particular DBAPI connection is first created for a given Pool, before the connection is made available to the connection pool. Additionally, because the function was registered with ``insert=True``, it will be prepended to the internal list of registered functions. MySQL / MariaDB SQL Extensions ------------------------------ Many of the MySQL / MariaDB SQL extensions are handled through SQLAlchemy's generic function and operator support:: table.select(table.c.password == func.md5("plaintext")) table.select(table.c.username.op("regexp")("^[a-d]")) And of course any valid SQL statement can be executed as a string as well. Some limited direct support for MySQL / MariaDB extensions to SQL is currently available. * INSERT..ON DUPLICATE KEY UPDATE: See :ref:`mysql_insert_on_duplicate_key_update` * SELECT pragma, use :meth:`_expression.Select.prefix_with` and :meth:`_query.Query.prefix_with`:: select(...).prefix_with(["HIGH_PRIORITY", "SQL_SMALL_RESULT"]) * UPDATE with LIMIT:: update(...).with_dialect_options(mysql_limit=10, mariadb_limit=10) * DELETE with LIMIT:: delete(...).with_dialect_options(mysql_limit=10, mariadb_limit=10) .. versionadded:: 2.0.37 Added delete with limit * optimizer hints, use :meth:`_expression.Select.prefix_with` and :meth:`_query.Query.prefix_with`:: select(...).prefix_with("/*+ NO_RANGE_OPTIMIZATION(t4 PRIMARY) */") * index hints, use :meth:`_expression.Select.with_hint` and :meth:`_query.Query.with_hint`:: select(...).with_hint(some_table, "USE INDEX xyz") * MATCH operator support:: from sqlalchemy.dialects.mysql import match select(...).where(match(col1, col2, against="some expr").in_boolean_mode()) .. seealso:: :class:`_mysql.match` INSERT/DELETE...RETURNING ------------------------- The MariaDB dialect supports 10.5+'s ``INSERT..RETURNING`` and ``DELETE..RETURNING`` (10.0+) syntaxes. ``INSERT..RETURNING`` may be used automatically in some cases in order to fetch newly generated identifiers in place of the traditional approach of using ``cursor.lastrowid``, however ``cursor.lastrowid`` is currently still preferred for simple single-statement cases for its better performance. To specify an explicit ``RETURNING`` clause, use the :meth:`._UpdateBase.returning` method on a per-statement basis:: # INSERT..RETURNING result = connection.execute( table.insert().values(name="foo").returning(table.c.col1, table.c.col2) ) print(result.all()) # DELETE..RETURNING result = connection.execute( table.delete() .where(table.c.name == "foo") .returning(table.c.col1, table.c.col2) ) print(result.all()) .. versionadded:: 2.0 Added support for MariaDB RETURNING .. _mysql_insert_on_duplicate_key_update: INSERT...ON DUPLICATE KEY UPDATE (Upsert) ------------------------------------------ MySQL / MariaDB allow "upserts" (update or insert) of rows into a table via the ``ON DUPLICATE KEY UPDATE`` clause of the ``INSERT`` statement. A candidate row will only be inserted if that row does not match an existing primary or unique key in the table; otherwise, an UPDATE will be performed. The statement allows for separate specification of the values to INSERT versus the values for UPDATE. SQLAlchemy provides ``ON DUPLICATE KEY UPDATE`` support via the MySQL-specific :func:`.mysql.insert()` function, which provides the generative method :meth:`~.mysql.Insert.on_duplicate_key_update`: .. sourcecode:: pycon+sql >>> from sqlalchemy.dialects.mysql import insert >>> insert_stmt = insert(my_table).values( ... id="some_existing_id", data="inserted value" ... ) >>> on_duplicate_key_stmt = insert_stmt.on_duplicate_key_update( ... data=insert_stmt.inserted.data, status="U" ... ) >>> print(on_duplicate_key_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (%s, %s) ON DUPLICATE KEY UPDATE data = VALUES(data), status = %s Unlike PostgreSQL's "ON CONFLICT" phrase, the "ON DUPLICATE KEY UPDATE" phrase will always match on any primary key or unique key, and will always perform an UPDATE if there's a match; there are no options for it to raise an error or to skip performing an UPDATE. ``ON DUPLICATE KEY UPDATE`` is used to perform an update of the already existing row, using any combination of new values as well as values from the proposed insertion. These values are normally specified using keyword arguments passed to the :meth:`_mysql.Insert.on_duplicate_key_update` given column key values (usually the name of the column, unless it specifies :paramref:`_schema.Column.key` ) as keys and literal or SQL expressions as values: .. sourcecode:: pycon+sql >>> insert_stmt = insert(my_table).values( ... id="some_existing_id", data="inserted value" ... ) >>> on_duplicate_key_stmt = insert_stmt.on_duplicate_key_update( ... data="some data", ... updated_at=func.current_timestamp(), ... ) >>> print(on_duplicate_key_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (%s, %s) ON DUPLICATE KEY UPDATE data = %s, updated_at = CURRENT_TIMESTAMP In a manner similar to that of :meth:`.UpdateBase.values`, other parameter forms are accepted, including a single dictionary: .. sourcecode:: pycon+sql >>> on_duplicate_key_stmt = insert_stmt.on_duplicate_key_update( ... {"data": "some data", "updated_at": func.current_timestamp()}, ... ) as well as a list of 2-tuples, which will automatically provide a parameter-ordered UPDATE statement in a manner similar to that described at :ref:`tutorial_parameter_ordered_updates`. Unlike the :class:`_expression.Update` object, no special flag is needed to specify the intent since the argument form is this context is unambiguous: .. sourcecode:: pycon+sql >>> on_duplicate_key_stmt = insert_stmt.on_duplicate_key_update( ... [ ... ("data", "some data"), ... ("updated_at", func.current_timestamp()), ... ] ... ) >>> print(on_duplicate_key_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (%s, %s) ON DUPLICATE KEY UPDATE data = %s, updated_at = CURRENT_TIMESTAMP .. versionchanged:: 1.3 support for parameter-ordered UPDATE clause within MySQL ON DUPLICATE KEY UPDATE .. warning:: The :meth:`_mysql.Insert.on_duplicate_key_update` method does **not** take into account Python-side default UPDATE values or generation functions, e.g. e.g. those specified using :paramref:`_schema.Column.onupdate`. These values will not be exercised for an ON DUPLICATE KEY style of UPDATE, unless they are manually specified explicitly in the parameters. In order to refer to the proposed insertion row, the special alias :attr:`_mysql.Insert.inserted` is available as an attribute on the :class:`_mysql.Insert` object; this object is a :class:`_expression.ColumnCollection` which contains all columns of the target table: .. sourcecode:: pycon+sql >>> stmt = insert(my_table).values( ... id="some_id", data="inserted value", author="jlh" ... ) >>> do_update_stmt = stmt.on_duplicate_key_update( ... data="updated value", author=stmt.inserted.author ... ) >>> print(do_update_stmt) {printsql}INSERT INTO my_table (id, data, author) VALUES (%s, %s, %s) ON DUPLICATE KEY UPDATE data = %s, author = VALUES(author) When rendered, the "inserted" namespace will produce the expression ``VALUES(<columnname>)``. .. versionadded:: 1.2 Added support for MySQL ON DUPLICATE KEY UPDATE clause rowcount Support ---------------- SQLAlchemy standardizes the DBAPI ``cursor.rowcount`` attribute to be the usual definition of "number of rows matched by an UPDATE or DELETE" statement. This is in contradiction to the default setting on most MySQL DBAPI drivers, which is "number of rows actually modified/deleted". For this reason, the SQLAlchemy MySQL dialects always add the ``constants.CLIENT.FOUND_ROWS`` flag, or whatever is equivalent for the target dialect, upon connection. This setting is currently hardcoded. .. seealso:: :attr:`_engine.CursorResult.rowcount` .. _mysql_indexes: MySQL / MariaDB- Specific Index Options ----------------------------------------- MySQL and MariaDB-specific extensions to the :class:`.Index` construct are available. Index Length ~~~~~~~~~~~~~ MySQL and MariaDB both provide an option to create index entries with a certain length, where "length" refers to the number of characters or bytes in each value which will become part of the index. SQLAlchemy provides this feature via the ``mysql_length`` and/or ``mariadb_length`` parameters:: Index("my_index", my_table.c.data, mysql_length=10, mariadb_length=10) Index("a_b_idx", my_table.c.a, my_table.c.b, mysql_length={"a": 4, "b": 9}) Index( "a_b_idx", my_table.c.a, my_table.c.b, mariadb_length={"a": 4, "b": 9} ) Prefix lengths are given in characters for nonbinary string types and in bytes for binary string types. The value passed to the keyword argument *must* be either an integer (and, thus, specify the same prefix length value for all columns of the index) or a dict in which keys are column names and values are prefix length values for corresponding columns. MySQL and MariaDB only allow a length for a column of an index if it is for a CHAR, VARCHAR, TEXT, BINARY, VARBINARY and BLOB. Index Prefixes ~~~~~~~~~~~~~~ MySQL storage engines permit you to specify an index prefix when creating an index. SQLAlchemy provides this feature via the ``mysql_prefix`` parameter on :class:`.Index`:: Index("my_index", my_table.c.data, mysql_prefix="FULLTEXT") The value passed to the keyword argument will be simply passed through to the underlying CREATE INDEX, so it *must* be a valid index prefix for your MySQL storage engine. .. seealso:: `CREATE INDEX <https://dev.mysql.com/doc/refman/5.0/en/create-index.html>`_ - MySQL documentation Index Types ~~~~~~~~~~~~~ Some MySQL storage engines permit you to specify an index type when creating an index or primary key constraint. SQLAlchemy provides this feature via the ``mysql_using`` parameter on :class:`.Index`:: Index( "my_index", my_table.c.data, mysql_using="hash", mariadb_using="hash" ) As well as the ``mysql_using`` parameter on :class:`.PrimaryKeyConstraint`:: PrimaryKeyConstraint("data", mysql_using="hash", mariadb_using="hash") The value passed to the keyword argument will be simply passed through to the underlying CREATE INDEX or PRIMARY KEY clause, so it *must* be a valid index type for your MySQL storage engine. More information can be found at: https://dev.mysql.com/doc/refman/5.0/en/create-index.html https://dev.mysql.com/doc/refman/5.0/en/create-table.html Index Parsers ~~~~~~~~~~~~~ CREATE FULLTEXT INDEX in MySQL also supports a "WITH PARSER" option. This is available using the keyword argument ``mysql_with_parser``:: Index( "my_index", my_table.c.data, mysql_prefix="FULLTEXT", mysql_with_parser="ngram", mariadb_prefix="FULLTEXT", mariadb_with_parser="ngram", ) .. versionadded:: 1.3 .. _mysql_foreign_keys: MySQL / MariaDB Foreign Keys ----------------------------- MySQL and MariaDB's behavior regarding foreign keys has some important caveats. Foreign Key Arguments to Avoid ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Neither MySQL nor MariaDB support the foreign key arguments "DEFERRABLE", "INITIALLY", or "MATCH". Using the ``deferrable`` or ``initially`` keyword argument with :class:`_schema.ForeignKeyConstraint` or :class:`_schema.ForeignKey` will have the effect of these keywords being rendered in a DDL expression, which will then raise an error on MySQL or MariaDB. In order to use these keywords on a foreign key while having them ignored on a MySQL / MariaDB backend, use a custom compile rule:: from sqlalchemy.ext.compiler import compiles from sqlalchemy.schema import ForeignKeyConstraint @compiles(ForeignKeyConstraint, "mysql", "mariadb") def process(element, compiler, **kw): element.deferrable = element.initially = None return compiler.visit_foreign_key_constraint(element, **kw) The "MATCH" keyword is in fact more insidious, and is explicitly disallowed by SQLAlchemy in conjunction with the MySQL or MariaDB backends. This argument is silently ignored by MySQL / MariaDB, but in addition has the effect of ON UPDATE and ON DELETE options also being ignored by the backend. Therefore MATCH should never be used with the MySQL / MariaDB backends; as is the case with DEFERRABLE and INITIALLY, custom compilation rules can be used to correct a ForeignKeyConstraint at DDL definition time. Reflection of Foreign Key Constraints ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Not all MySQL / MariaDB storage engines support foreign keys. When using the very common ``MyISAM`` MySQL storage engine, the information loaded by table reflection will not include foreign keys. For these tables, you may supply a :class:`~sqlalchemy.ForeignKeyConstraint` at reflection time:: Table( "mytable", metadata, ForeignKeyConstraint(["other_id"], ["othertable.other_id"]), autoload_with=engine, ) .. seealso:: :ref:`mysql_storage_engines` .. _mysql_unique_constraints: MySQL / MariaDB Unique Constraints and Reflection ---------------------------------------------------- SQLAlchemy supports both the :class:`.Index` construct with the flag ``unique=True``, indicating a UNIQUE index, as well as the :class:`.UniqueConstraint` construct, representing a UNIQUE constraint. Both objects/syntaxes are supported by MySQL / MariaDB when emitting DDL to create these constraints. However, MySQL / MariaDB does not have a unique constraint construct that is separate from a unique index; that is, the "UNIQUE" constraint on MySQL / MariaDB is equivalent to creating a "UNIQUE INDEX". When reflecting these constructs, the :meth:`_reflection.Inspector.get_indexes` and the :meth:`_reflection.Inspector.get_unique_constraints` methods will **both** return an entry for a UNIQUE index in MySQL / MariaDB. However, when performing full table reflection using ``Table(..., autoload_with=engine)``, the :class:`.UniqueConstraint` construct is **not** part of the fully reflected :class:`_schema.Table` construct under any circumstances; this construct is always represented by a :class:`.Index` with the ``unique=True`` setting present in the :attr:`_schema.Table.indexes` collection. TIMESTAMP / DATETIME issues --------------------------- .. _mysql_timestamp_onupdate: Rendering ON UPDATE CURRENT TIMESTAMP for MySQL / MariaDB's explicit_defaults_for_timestamp ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ MySQL / MariaDB have historically expanded the DDL for the :class:`_types.TIMESTAMP` datatype into the phrase "TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP", which includes non-standard SQL that automatically updates the column with the current timestamp when an UPDATE occurs, eliminating the usual need to use a trigger in such a case where server-side update changes are desired. MySQL 5.6 introduced a new flag `explicit_defaults_for_timestamp <https://dev.mysql.com/doc/refman/5.6/en/server-system-variables.html #sysvar_explicit_defaults_for_timestamp>`_ which disables the above behavior, and in MySQL 8 this flag defaults to true, meaning in order to get a MySQL "on update timestamp" without changing this flag, the above DDL must be rendered explicitly. Additionally, the same DDL is valid for use of the ``DATETIME`` datatype as well. SQLAlchemy's MySQL dialect does not yet have an option to generate MySQL's "ON UPDATE CURRENT_TIMESTAMP" clause, noting that this is not a general purpose "ON UPDATE" as there is no such syntax in standard SQL. SQLAlchemy's :paramref:`_schema.Column.server_onupdate` parameter is currently not related to this special MySQL behavior. To generate this DDL, make use of the :paramref:`_schema.Column.server_default` parameter and pass a textual clause that also includes the ON UPDATE clause:: from sqlalchemy import Table, MetaData, Column, Integer, String, TIMESTAMP from sqlalchemy import text metadata = MetaData() mytable = Table( "mytable", metadata, Column("id", Integer, primary_key=True), Column("data", String(50)), Column( "last_updated", TIMESTAMP, server_default=text( "CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP" ), ), ) The same instructions apply to use of the :class:`_types.DateTime` and :class:`_types.DATETIME` datatypes:: from sqlalchemy import DateTime mytable = Table( "mytable", metadata, Column("id", Integer, primary_key=True), Column("data", String(50)), Column( "last_updated", DateTime, server_default=text( "CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP" ), ), ) Even though the :paramref:`_schema.Column.server_onupdate` feature does not generate this DDL, it still may be desirable to signal to the ORM that this updated value should be fetched. This syntax looks like the following:: from sqlalchemy.schema import FetchedValue class MyClass(Base): __tablename__ = "mytable" id = Column(Integer, primary_key=True) data = Column(String(50)) last_updated = Column( TIMESTAMP, server_default=text( "CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP" ), server_onupdate=FetchedValue(), ) .. _mysql_timestamp_null: TIMESTAMP Columns and NULL ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ MySQL historically enforces that a column which specifies the TIMESTAMP datatype implicitly includes a default value of CURRENT_TIMESTAMP, even though this is not stated, and additionally sets the column as NOT NULL, the opposite behavior vs. that of all other datatypes: .. sourcecode:: text mysql> CREATE TABLE ts_test ( -> a INTEGER, -> b INTEGER NOT NULL, -> c TIMESTAMP, -> d TIMESTAMP DEFAULT CURRENT_TIMESTAMP, -> e TIMESTAMP NULL); Query OK, 0 rows affected (0.03 sec) mysql> SHOW CREATE TABLE ts_test; +---------+----------------------------------------------------- | Table | Create Table +---------+----------------------------------------------------- | ts_test | CREATE TABLE `ts_test` ( `a` int(11) DEFAULT NULL, `b` int(11) NOT NULL, `c` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, `d` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP, `e` timestamp NULL DEFAULT NULL ) ENGINE=MyISAM DEFAULT CHARSET=latin1 Above, we see that an INTEGER column defaults to NULL, unless it is specified with NOT NULL. But when the column is of type TIMESTAMP, an implicit default of CURRENT_TIMESTAMP is generated which also coerces the column to be a NOT NULL, even though we did not specify it as such. This behavior of MySQL can be changed on the MySQL side using the `explicit_defaults_for_timestamp <https://dev.mysql.com/doc/refman/5.6/en/server-system-variables.html #sysvar_explicit_defaults_for_timestamp>`_ configuration flag introduced in MySQL 5.6. With this server setting enabled, TIMESTAMP columns behave like any other datatype on the MySQL side with regards to defaults and nullability. However, to accommodate the vast majority of MySQL databases that do not specify this new flag, SQLAlchemy emits the "NULL" specifier explicitly with any TIMESTAMP column that does not specify ``nullable=False``. In order to accommodate newer databases that specify ``explicit_defaults_for_timestamp``, SQLAlchemy also emits NOT NULL for TIMESTAMP columns that do specify ``nullable=False``. The following example illustrates:: from sqlalchemy import MetaData, Integer, Table, Column, text from sqlalchemy.dialects.mysql import TIMESTAMP m = MetaData() t = Table( "ts_test", m, Column("a", Integer), Column("b", Integer, nullable=False), Column("c", TIMESTAMP), Column("d", TIMESTAMP, nullable=False), ) from sqlalchemy import create_engine e = create_engine("mysql+mysqldb://scott:tiger@localhost/test", echo=True) m.create_all(e) output: .. sourcecode:: sql CREATE TABLE ts_test ( a INTEGER, b INTEGER NOT NULL, c TIMESTAMP NULL, d TIMESTAMP NOT NULL ) � )� annotations)�array)� defaultdict)�compressN)�cast� )� reflection)�ENUM)�SET)�JSON)� JSONIndexType)� JSONPathType)�RESERVED_WORDS_MARIADB)�RESERVED_WORDS_MYSQL)� _FloatType)� _IntegerType)� _MatchType)� _NumericType)� _StringType)�BIGINT)�BIT)�CHAR)�DATETIME)�DECIMAL)�DOUBLE)�FLOAT)�INTEGER)�LONGBLOB)�LONGTEXT)� MEDIUMBLOB)� MEDIUMINT)� MEDIUMTEXT)�NCHAR)�NUMERIC)�NVARCHAR)�REAL)�SMALLINT)�TEXT)�TIME)� TIMESTAMP)�TINYBLOB)�TINYINT)�TINYTEXT)�VARCHAR)�YEAR� )�exc)�literal_column)�log)�schema)�sql)�util)�cursor)�default)�ReflectionDefaults)� coercions)�compiler)�elements)� functions)� operators)�roles)�sqltypes)�visitors)� InsertmanyvaluesSentinelOpts)� SQLCompiler)� SchemaConst)�BINARY)�BLOB)�BOOLEAN)�DATE)�UUID)� VARBINARY)� topologicalz%\s*SET\s+(?:(?:GLOBAL|SESSION)\s+)?\w)$Zbigint�binary�bitZblob�boolean�char�date�datetime�decimal�double�enum�fixed�float�int�integer�jsonZlongblobZlongtextZ mediumblobZ mediumintZ mediumtextZncharZnvarchar�numeric�setZsmallint�text�time� timestampZtinyblobZtinyintZtinytext�uuidZ varbinaryZvarchar�yearc @ s$ e Zd Zdd� Zdd� Zdd� ZdS )�MySQLExecutionContextc C sF | j rBtt| j�jrB| jjsBt�| jdd� tt| j�j D �g �| _ d S )Nc S s g | ]}|j d f�qS �N)Zkeyname)�.0�entry� rd �S/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mysql/base.py� <listcomp>� s �z3MySQLExecutionContext.post_exec.<locals>.<listcomp>) Zisdeleter rB ZcompiledZeffective_returningr6 � description�_cursorZ FullyBufferedCursorFetchStrategyZ_result_columnsZcursor_fetch_strategy��selfrd rd re � post_exec� s � �� ����z MySQLExecutionContext.post_execc C s" | j jr| j�| j j�S t� �d S ra )�dialectZ supports_server_side_cursorsZ_dbapi_connectionr6 Z _sscursor�NotImplementedErrorri rd rd re �create_server_side_cursor� s z/MySQLExecutionContext.create_server_side_cursorc C s | � d| j�|� |�S )Nzselect nextval(%s))Z_execute_scalar�identifier_preparer�format_sequence)rj �seq�type_rd rd re � fire_sequence� s ��z#MySQLExecutionContext.fire_sequenceN)�__name__� __module__� __qualname__rk rn rs rd rd rd re r` � s r` c sv e Zd ZdZejj�� Ze�ddi� dd� Z dd� Z dd � Z d d � Z d d � Z dd� Zdd� Zdd� Zdd� Zdd� Zdd� Zdd� Zed �Zd Zd d � Zd d!� Zd"d#� ZdTd%d&�Zd'd(� Z � fd)d*�Z d+d,� Z d-d.� Z � fd/d0�Z dUd2d3�Z!d4d5� Z"d6d7� Z#d8d9� Z$d:d;� Z%d<d=� Z&d>d?� Z'd@dA� Z(dBdC� Z)dDdE� Z*dFdG� Z+dHdI� Z,dJdK� Z-dLdM� Z.dNdO� Z/dPdQ� Z0dRdS� Z1� Z2S )V� MySQLCompilerTZ millisecondsZ millisecondc C s" | j r | j d d }|jr dS dS )zlCalled when a ``SELECT`` statement has no froms, and no ``FROM`` clause is to be appended. ���Z selectablez FROM DUAL� )�stackZ_where_criteria)rj �stmtrd rd re � default_from s zMySQLCompiler.default_fromc K s d| � |� S )Nzrand%s)Zfunction_argspec�rj �fn�kwrd rd re �visit_random_func s z MySQLCompiler.visit_random_funcc s& d� � �fdd�|jD ��}|� d�S )N�, c 3 s | ]}|j �fi � ��V qd S ra �Z_compiler_dispatch�rb �elem�r rj rd re � <genexpr> s z2MySQLCompiler.visit_rollup_func.<locals>.<genexpr>z WITH ROLLUP��join�clauses)rj r~ r �clauserd r� re �visit_rollup_func s �z MySQLCompiler.visit_rollup_funcc s, � �fdd�|j D �\}}d|� d|� d�S )Nc 3 s | ]}|j �fi � ��V qd S ra r� r� r� rd re r� s z=MySQLCompiler.visit_aggregate_strings_func.<locals>.<genexpr>z group_concat(z SEPARATOR �))r� )rj r~ r �exprZ delimeterrd r� re � visit_aggregate_strings_func s � z*MySQLCompiler.visit_aggregate_strings_funcc K s d| j �|� S )Nz nextval(%s))�preparerrp )rj rq r rd rd re �visit_sequence" s z MySQLCompiler.visit_sequencec K s dS )Nz SYSDATE()rd r} rd rd re �visit_sysdate_func% s z MySQLCompiler.visit_sysdate_funcc K s� |j jtju r:d| j|jfi |��| j|jfi |��f S d| j|jfi |��| j|jfi |��f }|j jtju r�d| j|jfi |��| j|jfi |��f }�n|j jtju �r8|j j d u�r |j j d u�r d| j|jfi |��| j|jfi |��|j j |j j f }n,d| j|jfi |��| j|jfi |��f }n�|j jtj u �rNd}nj|j jtj u �r�d| j|jfi |��| j|jfi |��f }n,d| j|jfi |��| j|jfi |��f }|d | d S ) NzJSON_EXTRACT(%s, %s)z/CASE JSON_EXTRACT(%s, %s) WHEN 'null' THEN NULLz1ELSE CAST(JSON_EXTRACT(%s, %s) AS SIGNED INTEGER)z2ELSE CAST(JSON_EXTRACT(%s, %s) AS DECIMAL(%s, %s))z2ELSE JSON_EXTRACT(%s, %s)+0.0000000000000000000000z WHEN true THEN true ELSE falsez'ELSE JSON_UNQUOTE(JSON_EXTRACT(%s, %s))zELSE JSON_EXTRACT(%s, %s)� z END) �typeZ_type_affinityr? r �process�left�right�Integer�Numeric�scale� precision�Boolean�String)rj rK �operatorr Zcase_expression�type_expressionrd rd re � _render_json_extract_from_binary( s^ ����� � ���� �����z.MySQLCompiler._render_json_extract_from_binaryc K s | j ||fi |��S ra �r� �rj rK r� r rd rd re � visit_json_getitem_op_binaryp s z*MySQLCompiler.visit_json_getitem_op_binaryc K s | j ||fi |��S ra r� r� rd rd re �!visit_json_path_getitem_op_binarys s z/MySQLCompiler.visit_json_path_getitem_op_binaryc s� �j ��jrNdd� �jD �}t|���fdd�|D ��fdd��jjD � }n�jj}g }�jd u oj�jj��r��jj� � dkr�d� nd� dd� �j � � D ���fd d �|D �D ]����j }t �|�r�tjd |�jd �}�j|�� d d �}n4� ����fdd�}t�|i |�}�j|�� d d �}�j��j�} |�d| |f � q�t��dd� |D � } | �r�t�d�jjjd� dd � | D ��f � ��r�d� � dd� |�� �S dd� |�� �S d S )Nc S s g | ]}t �tj|��qS rd )r9 �expectr> � DMLColumnRole�rb �keyrd rd re rf z s �z?MySQLCompiler.visit_on_duplicate_key_update.<locals>.<listcomp>c s$ g | ] }|� j jv r� j j| �qS rd )�table�cr� )� statementrd re rf s �c s g | ]}|j � vr|�qS rd �r� �rb r� )� ordered_keysrd re rf � � �newZnew_1c S s i | ]\}}t �tj|�|�qS rd )r9 Z expect_as_keyr> r� )rb r� �valuerd rd re � <dictcomp>� s �z?MySQLCompiler.visit_on_duplicate_key_update.<locals>.<dictcomp>c 3 s | ]}|j � v r|V qd S ra r� �rb �col)�on_duplicate_updaterd re r� � r� z>MySQLCompiler.visit_on_duplicate_key_update.<locals>.<genexpr>)rr F)� use_schemac s� t | tj�r(| jjr(| �� } �j| _| S t | tj�r|| j�ju r|�r^� � d�j � | j �� �}nd�j � | j �� d�}t |�S d S d S )N�.zVALUES(r� ) � isinstancer; � BindParameterr� Z_isnullZ_cloneZ ColumnClauser� Zinserted_aliasr� �quote�namer1 )�objZcolumn_literal_clause)�_on_dup_alias_name�column� on_duplicate�requires_mysql8_aliasrj rd re �replace� s( �� � � ���z<MySQLCompiler.visit_on_duplicate_key_update.<locals>.replacez%s = %sc S s h | ] }|j �qS rd r� r� rd rd re � <setcomp>� r� z>MySQLCompiler.visit_on_duplicate_key_update.<locals>.<setcomp>zFAdditional column names not matching any column keys in table '%s': %sr� c s s | ]}d | V qdS )�'%s'Nrd r� rd rd re r� � r� zAS z ON DUPLICATE KEY UPDATE zON DUPLICATE KEY UPDATE ) Zcurrent_executableZ_parameter_orderingrZ r� r� �selectrl �$_requires_alias_for_on_duplicate_keyr� �lower�update�itemsr� r9 Z _is_literalr; r� r� r� � self_groupr@ Zreplacement_traverser� r� �appendr5 �warnr� r� ) rj r� r Zparameter_ordering�colsr� �valZ value_textr� Z name_textZ non_matchingrd )r� r� r� r� r� r� rj r� re � visit_on_duplicate_key_updatev s` � �� �� ��� ��z+MySQLCompiler.visit_on_duplicate_key_updatec s dd� � �fdd�|jD �� S )Nz concat(%s)r� c 3 s | ]}�j |fi � ��V qd S ra �r� r� r� rd re r� � r� zFMySQLCompiler.visit_concat_op_expression_clauselist.<locals>.<genexpr>r� )rj Z clauselistr� r rd r� re �%visit_concat_op_expression_clauselist� s �z3MySQLCompiler.visit_concat_op_expression_clauselistc K s, d| j |jfi |��| j |jfi |��f S )Nzconcat(%s, %s)�r� r� r� r� rd rd re �visit_concat_op_binary� s �z$MySQLCompiler.visit_concat_op_binary))FFF)TFF)FTF)FFT)FTT)zIN BOOLEAN MODEzIN NATURAL LANGUAGE MODEzWITH QUERY EXPANSIONc K s | j ||jfi |��S ra )�visit_match_op_binaryr� �rj �elementr rd rd re �visit_mysql_match� s z MySQLCompiler.visit_mysql_matchc K s� |j }|�dd�}|�dd�}|�dd�}|||f}|| jvrld| d| d| f} d �| �} t�d | ��|j} | j| fi |��} | j|jfi |��} t |�r�t | j |�} | g} | � | � d �| �} d | | f S ) zp Note that `mysql_boolean_mode` is enabled by default because of backward compatibility Zmysql_boolean_modeTZmysql_natural_languageFZmysql_query_expansionzin_boolean_mode=%szin_natural_language_mode=%szwith_query_expansion=%sr� z Invalid MySQL match flags: %sr� zMATCH (%s) AGAINST (%s)) � modifiers�get� _match_valid_flag_combinationsr� r0 � CompileErrorr� r� r� �anyr �_match_flag_expressions�extend) rj rK r� r r� Z boolean_modeZnatural_languageZquery_expansionZflag_combination�flagsZ match_clauseZagainst_clauseZflag_expressionsrd rd re r� � s0 � � z#MySQLCompiler.visit_match_op_binaryc C s |S ra rd )rj r� r[ rd rd re �get_from_hint_text! s z MySQLCompiler.get_from_hint_textNc K s6 |d u r|j �| j�}t|tj�r8| j||jfi |��S t|tj�rZt |dd�rTdS dS n�t|tj �rjdS t|tj tj tj tjf�r�| jj�|�S t|tj�r�t|ttf�s�t�|�}| jj�|�S t|tj�r�dS t|tj�r�dS t|tj��r| jj�|��dd �S t|tj��r.| jj�r.| jj�|�S d S d S ) N�unsignedFzUNSIGNED INTEGERzSIGNED INTEGERr rD r r# r ) r� Z dialect_implrl r� r? Z TypeDecorator�visit_typeclause�implr� �getattrr) r �DateTime�Date�Time�type_compiler_instancer� r� r r r Z_adapt_string_for_castZ_Binaryr r# r� �Float�_support_float_cast)rj � typeclauserr r Zadaptedrd rd re r� $ sL �� � � ��z MySQLCompiler.visit_typeclausec K sd | � |j�}|d u rHt�d| jj� |jj� � | j |j�� fi |��S d| j |jfi |��|f S )NzMDatatype %s does not support CAST on MySQL/MariaDb; the CAST will be skipped.zCAST(%s AS %s)) r� r� r5 r� rl r� r� r� r� )rj r r rr rd rd re � visit_castO s ���zMySQLCompiler.visit_castc s& t � �||�}| jjr"|�dd�}|S )N�\z\\)�super�render_literal_valuerl �_backslash_escapesr� )rj r� rr �� __class__rd re r� ] s z"MySQLCompiler.render_literal_valuec K s dS )N�truerd r� rd rd re � visit_truee s zMySQLCompiler.visit_truec K s dS )N�falserd r� rd rd re � visit_falseh s zMySQLCompiler.visit_falsec s< t |jt�r(tjddd� |j�� d S t� j|fi |��S )z�Add special MySQL keywords in place of DISTINCT. .. deprecated:: 1.4 This usage is deprecated. :meth:`_expression.Select.prefix_with` should be used for special keywords at the start of a SELECT. z�Sending string values for 'distinct' is deprecated in the MySQL dialect and will be removed in a future release. Please use :meth:`.Select.prefix_with` for special keywords at the start of a SELECT statementz1.4)�versionr� )r� Z _distinct�strr5 Zwarn_deprecated�upperr� �get_select_precolumns)rj r� r r� rd re r� k s �z#MySQLCompiler.get_select_precolumnsFc K s� |r|j �|j|jf� |jr$d}n|jr0d}nd}d�| j|jfd|d�|��|| j|jfd|d�|��d| j|jfd|i|��f�S ) Nz FULL OUTER JOIN z LEFT OUTER JOIN z INNER JOIN ry T)�asfrom� from_linterz ON r� ) �edges�addr� r� �fullZisouterr� r� Zonclause)rj r� r� r� �kwargsZ join_typerd rd re � visit_join s6 ��������zMySQLCompiler.visit_joinc s� |j jrd}nd}|j jrj�jjrjt�� }|j jD ]}|�t� |�� q2|dd� � �fdd�|D �� 7 }|j j rz|d7 }|j j r�|d7 }|S ) Nz LOCK IN SHARE MODEz FOR UPDATEz OF r� c 3 s& | ] }�j |fd dd�� ��V qdS )TF)�ashintr� Nr� )rb r� r� rd re r� � s �z2MySQLCompiler.for_update_clause.<locals>.<genexpr>z NOWAITz SKIP LOCKED) Z_for_update_arg�readZofrl �supports_for_update_ofr5 Z OrderedSetr� �sql_utilZsurface_selectables_onlyr� ZnowaitZ skip_locked)rj r� r �tmp�tablesr� rd r� re �for_update_clause� s � z MySQLCompiler.for_update_clausec K s� |j |j }}|d u r"|d u r"dS |d urv|d u rLd| j|fi |��df S d| j|fi |��| j|fi |��f S nd| j|fi |��f S d S )Nry z LIMIT %s, %sZ18446744073709551615z LIMIT %s)Z _limit_clauseZ_offset_clauser� )rj r� r � limit_clauseZ offset_clauserd rd re r � s ���zMySQLCompiler.limit_clausec C s4 |j �d| jj d �}|d ur,dt|�� �S d S d S �Nz%s_limitzLIMIT �r� r� rl r� rV )rj � update_stmt�limitrd rd re �update_limit_clause� s z!MySQLCompiler.update_limit_clausec C s4 |j �d| jj d �}|d ur,dt|�� �S d S d S r r )rj � delete_stmtr rd rd re �delete_limit_clause� s z!MySQLCompiler.delete_limit_clausec s, d� d< d� � �fdd�|gt|� D ��S )NTr� r� c 3 s | ]}|j �fi � ��V qd S ra r� �rb �tr� rd re r� � s �z5MySQLCompiler.update_tables_clause.<locals>.<genexpr>)r� �list)rj r � from_table� extra_fromsr rd r� re �update_tables_clause� s �z"MySQLCompiler.update_tables_clausec K s d S ra rd )rj r r r � from_hintsr rd rd re �update_from_clause� s z MySQLCompiler.update_from_clausec K s& d}|r d}|j | fdd|d�|��S )z=If we have extra froms make sure we render any alias as hint.FT)r� Ziscrudr r� )rj r r r r r rd rd re �delete_table_clause� s ���z!MySQLCompiler.delete_table_clausec s. d�d< dd� � ��fdd�|g| D �� S )z4Render the DELETE .. USING clause specific to MySQL.Tr� zUSING r� c 3 s$ | ] }|j �fd � i���V qdS )Z fromhintsNr� r �r r rj rd re r� � s �z9MySQLCompiler.delete_extra_from_clause.<locals>.<genexpr>)r� )rj r r r r r rd r re �delete_extra_from_clause� s �z&MySQLCompiler.delete_extra_from_clausec K s6 dd� dd� t|�D ��d� dd� t|�D ��d� S )NzASELECT %(outer)s FROM (SELECT %(inner)s) as _empty_set WHERE 1!=1r� c s s | ]\}}d | V qdS )z 1 AS _in_%sNrd �rb �idxrr rd rd re r� s �z5MySQLCompiler.visit_empty_set_expr.<locals>.<genexpr>c s s | ]\}}d | V qdS )z_in_%sNrd r rd rd re r� s )�inner�outer)r� � enumerate)rj Z element_typesr rd rd re �visit_empty_set_expr s � ����z"MySQLCompiler.visit_empty_set_exprc K s d| � |j�| � |j�f S )NzNOT (%s <=> %s)r� r� rd rd re � visit_is_distinct_from_binary s �z+MySQLCompiler.visit_is_distinct_from_binaryc K s d| � |j�| � |j�f S )Nz %s <=> %sr� r� rd rd re �!visit_is_not_distinct_from_binary s �z/MySQLCompiler.visit_is_not_distinct_from_binaryc K s$ d| � |tj�| j|fi |��f S )NzCONCAT('(?', %s, ')', %s))r� r? � STRINGTYPEr� )rj r� �patternr rd rd re �_mariadb_regexp_flags s �z#MySQLCompiler._mariadb_regexp_flagsc K s� |j d }|d u r&| j||fi |��S | jjrVd| j|jfi |��|| �||j�f S d| j|jfi |��| j|jfi |��| �|t j �f }|dkr�d| S |S d S )Nr� z%s%s%szREGEXP_LIKE(%s, %s, %s)� NOT REGEXP zNOT %s) r� Z_generate_generic_binaryrl � is_mariadbr� r� r$ r� r� r? r" )rj Z op_stringrK r� r r� r[ rd rd re � _regexp_match% s" � �zMySQLCompiler._regexp_matchc K s | j d||fi |��S )Nz REGEXP �r' r� rd rd re � visit_regexp_match_op_binary: s z*MySQLCompiler.visit_regexp_match_op_binaryc K s | j d||fi |��S )Nr% r( r� rd rd re � visit_not_regexp_match_op_binary= s z.MySQLCompiler.visit_not_regexp_match_op_binaryc K s� |j d }|d u r>d| j|jfi |��| j|jfi |��f S | jjr�d| j|jfi |��| �||jjd �| j|jjd fi |��f S d| j|jfi |��| j|jfi |��| �|t j �f S d S )Nr� zREGEXP_REPLACE(%s, %s)zREGEXP_REPLACE(%s, %s, %s)r r ) r� r� r� r� rl r& r$ r� r� r? r" )rj rK r� r r� rd rd re � visit_regexp_replace_op_binary@ s" �� �z,MySQLCompiler.visit_regexp_replace_op_binary)N)FN)3rt ru rv Z'render_table_with_column_in_update_fromr: rB Z extract_map�copyr� r| r� r� r� r� r� r� r� r� r� r� r� � frozensetr� r� r� r� r� r� r� r� r� r� r� r� r r r r r r r r r r r! r$ r' r) r* r+ � __classcell__rd rd r� re rw sZ H`� * + ' rw c sd e Zd Zdd� Zdd� Zdd� Z� fdd�Zd d � Zd d � Zd d� Z dd� Z dd� Z dd� Z � Z S )�MySQLDDLCompilerc K s� | j jdu r(|jdur(|jtju r(d|_| j�|�| j j j |j |d�g}|jdurd|� | � |j�� t |j �| j �tj�}|js�|� d� n|jr�|r�|� d� |j}|dur�| j�|t�� �}|� d| � |jdu�r4||jju �r4|jdu �st |jtj��r4| j j�r(t |jtj ��r(|jj �r4|� d� nn| � |�}|du�r�| j j �r�t �!d|��s�t �"d |t j#��s�t �!d |��r�|� d |� d �� n|� d | � d�$|�S )zBuilds column DDL.TN)r� zNOT NULLZNULLzCOMMENT ZAUTO_INCREMENTz ^\s*[\'\"\(]z ON +UPDATEz.*\W.*z DEFAULT (r� zDEFAULT r� )%rl r& ZcomputedZ_user_defined_nullablerC ZNULL_UNSPECIFIEDZnullabler� � format_columnr� r� r� r� r� Z_unwrapped_dialect_implr? r) �comment� sql_compilerr� r� r� Z_autoincrement_columnZserver_default� sa_schemaZIdentity�supports_sequencesr7 �Sequence�optionalZget_column_default_string�_support_default_function�re�match�search�Ir� )rj r� r ZcolspecZ is_timestampr1 �literalr7 rd rd re �get_column_specificationV sp �� � �� � �� �� �� � � � �� �z)MySQLDDLCompiler.get_column_specificationc s. g }� fdd�|j �� D �}|jdur0|j|d< g d�}t|��|�}t|��|�}t�g d�|�D ]`}|| }|tj v r�� j � |t � � �}|dv r�|�dd �}d } |d v r�d } |�| �||f�� qdt�g d �|�D ]L}|| }|tj v r�� j � |t � � �}|�dd �}d } |�| �||f�� q�d �|�S ) z9Build table-level CREATE options like ENGINE and COLLATE.c s@ i | ]8\}}|� d � jj �r|t� jj�d d� �� |�qS )z%s_r N)� startswithrl r� �lenr� )rb �k�vri rd re r� � s �z6MySQLDDLCompiler.post_create_table.<locals>.<dictcomp>N�COMMENT)� PARTITION_BY� PARTITIONS� SUBPARTITIONS�SUBPARTITION_BY))�DEFAULT_CHARSET�COLLATE)�DEFAULT_CHARACTER_SETrH )�CHARSETrH )� CHARACTER_SETrH )ZDATA_DIRECTORYZINDEX_DIRECTORYrI rK rG ZDEFAULT_COLLATE�_r� �=)Z TABLESPACEzDEFAULT CHARACTER SETz CHARACTER SETrH ))rC rD )rC rF )rC rE )rD rE )rD rF )rF rE )r� r� r1 rZ � difference� intersectionrJ �sort� _reflectionZ_options_of_type_stringr2 r� r? r� r� r� r� ) rj r� Z table_opts�optsZpartition_optionsZnonpart_optionsZ part_options�opt�argZjoinerrd ri re �post_create_table� sJ � � � � � z"MySQLDDLCompiler.post_create_tablec sh |j }��|� �j}|�|j�}�fdd�|jD �}��|�}d}|jrR|d7 }|j� d�j j d �} | rx|| d 7 }|d7 }|j r�|d7 }|d ||f 7 }|j �j j d � � d ur�t� t�r�d �� fd d �t|j|�D ��}nd �� fdd �|D ��}n d �|�}|d| 7 }|j d d } | d u�r:|d| f 7 }|j d d } | d u�rd|d|�| � 7 }|S )Nc s^ g | ]V}� j jt|tj�sDt|tj�r8|jtjtj fvsDt|t j �rNt� |�n|d dd��qS )FT)Z include_tableZ literal_binds) r2 r� r� r; ZBinaryExpressionZUnaryExpression�modifierr= Zdesc_opZasc_opr< ZFunctionElementZGrouping)rb r� ri rd re rf � s � � � �� � �z7MySQLDDLCompiler.visit_create_index.<locals>.<listcomp>zCREATE zUNIQUE � %s_prefixr� �INDEX zIF NOT EXISTS z %s ON %s �lengthr� c 3 sN | ]F\}}|j � v r&d |� |j f n |� v r>d |� | f nd| V qdS )�%s(%d)z%sN�r� )rb r� r� �rY rd re r� s ���z6MySQLDDLCompiler.visit_create_index.<locals>.<genexpr>c 3 s | ]}d |� f V qdS )rZ Nrd r� r\ rd re r� + s z(%s)�mysql� with_parserz WITH PARSER %s�using� USING %s)r� Z_verify_index_tabler� � format_tabler� Z expressions�_prepared_index_name�uniquer� r� rl r� Z if_not_exists�dialect_optionsr� �dictr� �zipr� ) rj �creater �indexr� r� �columnsr� r[ Z index_prefix�parserr_ rd )rY rj re �visit_create_index� sH � � � z#MySQLDDLCompiler.visit_create_indexc s6 t � �|�}|jd d }|r2|d| j�|� 7 }|S )Nr] r_ r` )r� � visit_primary_key_constraintrd r� r� )rj � constraintr r[ r_ r� rd re rl < s z-MySQLDDLCompiler.visit_primary_key_constraintc K s< |j }d}|jr|d7 }|d| j|dd�| j�|j�f S )Nz DROP INDEX z IF EXISTS z%s ON %sF)Zinclude_schema)r� Z if_existsrb r� ra r� )rj �dropr rh r[ rd rd re �visit_drop_indexC s �z!MySQLDDLCompiler.visit_drop_indexc K s� |j }t|tj�r$d}| j�|�}npt|tj�r:d}d}nZt|tj�rXd}| j�|�}n<t|tj�r�| j j rrd}nd}| j�|�}nd}| j�|�}d| j� |j �||f S )Nz FOREIGN KEY z PRIMARY KEY ry rX z CONSTRAINT zCHECK zALTER TABLE %s DROP %s%s) r� r� r3 ZForeignKeyConstraintr� Zformat_constraint�PrimaryKeyConstraintZUniqueConstraintZCheckConstraintrl r& ra r� )rj rn r rm Zqual�constrd rd re �visit_drop_constraintN s, �z&MySQLDDLCompiler.visit_drop_constraintc C s |j d urt�d��dS )NzjMySQL ignores the 'MATCH' keyword while at the same time causes ON UPDATE/ON DELETE clauses to be ignored.ry )r9 r0 r� )rj rm rd rd re �define_constraint_matchh s �z(MySQLDDLCompiler.define_constraint_matchc K s( d| j �|j�| j�|jjt�� �f S )NzALTER TABLE %s COMMENT %s)r� ra r� r2 r� r1 r? r� �rj rg r rd rd re �visit_set_table_commentp s ��z(MySQLDDLCompiler.visit_set_table_commentc K s d| j �|j� S )NzALTER TABLE %s COMMENT '')r� ra r� rt rd rd re �visit_drop_table_commentx s �z)MySQLDDLCompiler.visit_drop_table_commentc K s, d| j �|jj�| j �|j�| �|j�f S )NzALTER TABLE %s CHANGE %s %s)r� ra r� r� r0 r= rt rd rd re �visit_set_column_comment} s �z)MySQLDDLCompiler.visit_set_column_comment)rt ru rv r= rU rk rl ro rr rs ru rv rw r. rd rd r� re r/ U s BTP r/ c sT e Zd Zdd� Zdd� Zdd� Zdd� Zd d � Zd d � Zd d� Z dd� Z dd� Z dd� Z dd� Z dd� Zdd� Zdd � Zd d � Zd d � Zd!d"� Zd#d$� Zd%d&� Zd'd(� Zd)d*� Zd+d,� Zd-d.� Zd/d0� Zd1d2� Zd3d4� Z d5d6� Z d7d8� Z d9d:� Z d;d<� Z d=d>� Z!� fd?d@�Z"dAdB� Z#dCdD� Z$dEdF� Z%dGdH� Z&dIdJ� Z'dKdL� Z(dMdN� Z)dOdP� Z*� Z+S )Q�MySQLTypeCompilerc C s. | � |�s|S |jr |d7 }|jr*|d7 }|S )zAExtend a numeric-type declaration with MySQL specific extensions.z UNSIGNEDz ZEROFILL)� _mysql_typer� Zzerofill)rj rr �specrd rd re �_extend_numeric� s z!MySQLTypeCompiler._extend_numericc s� � �fdd�}|d�r$d|d� }n |d�r2d}n|d�r@d}nd }|d �rXd �j }n|d �rfd }nd }|d�r�d�dd� d||fD ��S d�dd� |||fD ��S )z�Extend a string-type declaration with standard SQL CHARACTER SET / COLLATE annotations and MySQL specific extensions. c s t �| � �| ��S ra )r� r� r[ ��defaultsrr rd re �attr� s z.MySQLTypeCompiler._extend_string.<locals>.attr�charsetzCHARACTER SET %s�ascii�ASCII�unicode�UNICODEN� collationz COLLATE %srK rD �nationalr� c S s g | ]}|d ur|�qS ra rd r� rd rd re rf � r� z4MySQLTypeCompiler._extend_string.<locals>.<listcomp>ZNATIONALc S s g | ]}|d ur|�qS ra rd r� rd rd re rf � r� )r� r� )rj rr r} rz r~ r r� rd r| re �_extend_string� s( ��z MySQLTypeCompiler._extend_stringc C s t |ttf�S ra )r� r r )rj rr rd rd re ry � s z MySQLTypeCompiler._mysql_typec K sT |j d u r| �|d�S |jd u r6| �|dd|j i �S | �|d|j |jd� �S d S )Nr# zNUMERIC(%(precision)s)r� z!NUMERIC(%(precision)s, %(scale)s)�r� r� �r� r{ r� �rj rr r rd rd re � visit_NUMERIC� s � ��z MySQLTypeCompiler.visit_NUMERICc K sT |j d u r| �|d�S |jd u r6| �|dd|j i �S | �|d|j |jd� �S d S )Nr zDECIMAL(%(precision)s)r� z!DECIMAL(%(precision)s, %(scale)s)r� r� r� rd rd re � visit_DECIMAL� s � ��z MySQLTypeCompiler.visit_DECIMALc K s> |j d ur.|jd ur.| �|d|j |jd� �S | �|d�S d S )Nz DOUBLE(%(precision)s, %(scale)s)r� r �r� r� r{ r� rd rd re � visit_DOUBLE� s ��z MySQLTypeCompiler.visit_DOUBLEc K s> |j d ur.|jd ur.| �|d|j |jd� �S | �|d�S d S )Nz REAL(%(precision)s, %(scale)s)r� r% r� r� rd rd re � visit_REAL� s ��z MySQLTypeCompiler.visit_REALc K sd | � |�r6|jd ur6|jd ur6| �|d|j|jf �S |jd urT| �|d|jf �S | �|d�S d S )Nz FLOAT(%s, %s)z FLOAT(%s)r )ry r� r� r{ r� rd rd re � visit_FLOAT� s ���� �z MySQLTypeCompiler.visit_FLOATc K s: | � |�r*|jd ur*| �|dd|ji �S | �|d�S d S )NzINTEGER(%(display_width)s)� display_widthr �ry r� r{ r� rd rd re � visit_INTEGER� s ��z MySQLTypeCompiler.visit_INTEGERc K s: | � |�r*|jd ur*| �|dd|ji �S | �|d�S d S )NzBIGINT(%(display_width)s)r� r r� r� rd rd re � visit_BIGINT s ��z MySQLTypeCompiler.visit_BIGINTc K s: | � |�r*|jd ur*| �|dd|ji �S | �|d�S d S )Nz MEDIUMINT(%(display_width)s)r� r r� r� rd rd re �visit_MEDIUMINT s ��z!MySQLTypeCompiler.visit_MEDIUMINTc K s6 | � |�r&|jd ur&| �|d|j �S | �|d�S d S )Nz TINYINT(%s)r+ r� r� rd rd re � visit_TINYINT s �z MySQLTypeCompiler.visit_TINYINTc K s: | � |�r*|jd ur*| �|dd|ji �S | �|d�S d S )NzSMALLINT(%(display_width)s)r� r& r� r� rd rd re �visit_SMALLINT s ��z MySQLTypeCompiler.visit_SMALLINTc K s |j d urd|j S dS d S )NzBIT(%s)r r\ r� rd rd re � visit_BIT) s zMySQLTypeCompiler.visit_BITc K s t |dd �rd|j S dS d S )N�fspz DATETIME(%d)r �r� r� r� rd rd re �visit_DATETIME/ s z MySQLTypeCompiler.visit_DATETIMEc K s dS )NrG rd r� rd rd re � visit_DATE5 s z MySQLTypeCompiler.visit_DATEc K s t |dd �rd|j S dS d S )Nr� zTIME(%d)r( r� r� rd rd re � visit_TIME8 s z MySQLTypeCompiler.visit_TIMEc K s t |dd �rd|j S dS d S )Nr� z TIMESTAMP(%d)r) r� r� rd rd re �visit_TIMESTAMP> s z!MySQLTypeCompiler.visit_TIMESTAMPc K s |j d u rdS d|j S d S )Nr. zYEAR(%s))r� r� rd rd re � visit_YEARD s z MySQLTypeCompiler.visit_YEARc K s0 |j d ur | �|i d|j �S | �|i d�S d S )NzTEXT(%d)r' �rY r� r� rd rd re � visit_TEXTJ s z MySQLTypeCompiler.visit_TEXTc K s | � |i d�S )Nr, �r� r� rd rd re �visit_TINYTEXTP s z MySQLTypeCompiler.visit_TINYTEXTc K s | � |i d�S )Nr! r� r� rd rd re �visit_MEDIUMTEXTS s z"MySQLTypeCompiler.visit_MEDIUMTEXTc K s | � |i d�S )Nr r� r� rd rd re �visit_LONGTEXTV s z MySQLTypeCompiler.visit_LONGTEXTc K s4 |j d ur | �|i d|j �S t�d| jj ��d S )Nz VARCHAR(%d)z'VARCHAR requires a length on dialect %s�rY r� r0 r� rl r� r� rd rd re � visit_VARCHARY s �z MySQLTypeCompiler.visit_VARCHARc K s4 |j d ur"| �|i dd|j i �S | �|i d�S d S )N�CHAR(%(length)s)rY r r� r� rd rd re � visit_CHARa s �z MySQLTypeCompiler.visit_CHARc K s< |j d ur&| �|ddidd|j i �S t�d| jj ��d S )Nr� TzVARCHAR(%(length)s)rY z(NVARCHAR requires a length on dialect %sr� r� rd rd re �visit_NVARCHARi s � �z MySQLTypeCompiler.visit_NVARCHARc K s< |j d ur&| �|ddidd|j i �S | �|ddid�S d S )Nr� Tr� rY r r� r� rd rd re � visit_NCHARw s �z MySQLTypeCompiler.visit_NCHARc K s dS )NrH rd r� rd rd re � visit_UUID� s z MySQLTypeCompiler.visit_UUIDc K s d|j S )Nz VARBINARY(%d)r\ r� rd rd re �visit_VARBINARY� s z!MySQLTypeCompiler.visit_VARBINARYc K s dS )Nr rd r� rd rd re � visit_JSON� s z MySQLTypeCompiler.visit_JSONc K s | � |�S ra )� visit_BLOBr� rd rd re �visit_large_binary� s z$MySQLTypeCompiler.visit_large_binaryc s& |j st� �|�S | �d||j�S d S �Nr )Z native_enumr� � visit_enum�_visit_enumerated_values�enumsr� r� rd re r� � s z MySQLTypeCompiler.visit_enumc K s |j d urd|j S dS d S )NzBLOB(%d)rE r\ r� rd rd re r� � s z MySQLTypeCompiler.visit_BLOBc K s dS )Nr* rd r� rd rd re �visit_TINYBLOB� s z MySQLTypeCompiler.visit_TINYBLOBc K s dS )Nr rd r� rd rd re �visit_MEDIUMBLOB� s z"MySQLTypeCompiler.visit_MEDIUMBLOBc K s dS )Nr rd r� rd rd re �visit_LONGBLOB� s z MySQLTypeCompiler.visit_LONGBLOBc C sV g }|D ]0}| j jjr"|�dd�}|�d|�dd� � q| �|i d|d�|�f �S )N�%z%%r� �'z''z%s(%s)�,)rl ro Z_double_percentsr� r� r� r� )rj r� rr Zenumerated_valuesZ quoted_enums�erd rd re r� � s �z*MySQLTypeCompiler._visit_enumerated_valuesc K s | � d||j�S r� )r� r� r� rd rd re � visit_ENUM� s z MySQLTypeCompiler.visit_ENUMc K s | � d||j�S )Nr )r� �valuesr� rd rd re � visit_SET� s zMySQLTypeCompiler.visit_SETc K s dS )NZBOOLrd r� rd rd re � visit_BOOLEAN� s z MySQLTypeCompiler.visit_BOOLEAN),rt ru rv r{ r� ry r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r. rd rd r� re rx � sP " rx c s* e Zd ZeZd� fdd� Zdd� Z� ZS )�MySQLIdentifierPreparerFc s$ |s d}nd}t � j|||d� d S )N�`�")Z initial_quoteZ escape_quote)r� �__init__)rj rl �server_ansiquotesr r� r� rd re r� � s z MySQLIdentifierPreparer.__init__c s t � fdd�|D ��S )z4Unilaterally identifier-quote any number of strings.c s g | ]}|d ur� � |��qS ra )�quote_identifier)rb �iri rd re rf � r� zCMySQLIdentifierPreparer._quote_free_identifiers.<locals>.<listcomp>)�tuple)rj �idsrd ri re �_quote_free_identifiers� s z/MySQLIdentifierPreparer._quote_free_identifiers)F)rt ru rv r �reserved_wordsr� r� r. rd rd r� re r� � s r� c @ s e Zd ZeZdS )�MariaDBIdentifierPreparerN)rt ru rv r r� rd rd rd re r� � s r� c @ sT e Zd ZU dZdZdZdZdZdZdZ dZ dZ dZ dZ dZdZdZdZdZdZdZdZded< ejZdZdZdZ dZ dZ dZ d Z e!Z!dZ"e#Z$e%Z&e'Z(e)Z)e*Z+dZ,d Z-dZ.dZ/e0j1d d ife2j3d d ife2j4d d ife0j5d d ife0j6d d d d d�fgZ7d{dd�Z8dd� Z9dd� Z:dd� Z;e<dd� �Z=dd� Z>dd � Z?d d � Z@d d � ZAd!d"� ZBd|d#d$�ZCd}d%d&�ZDd'd(� ZEd)d*� ZFd~d+d,�ZGdd-d.�ZHd�d/d0�ZId1d2� ZJd3d4� ZKeLjMd�d5d6��ZNeLjMd�d7d8��ZOd9d:� ZPeLjMd�d;d<��ZQd=d>� ZRd?d@� ZSeTdAdB� �ZUeTdCdD� �ZVeTdEdF� �ZWeTdGdH� �ZXeTdIdJ� �ZYeLjMdKdL� �ZZeLjMd�dMdN��Z[eLjMd�dOdP��Z\eLjMd�dQdR��Z]eLjMd�dSdT��Z^eLjMd�dUdV��Z_eLjMd�dWdX��Z`dYdZ� ZaeLjMd�d[d\��ZbeLjMd�d]d^��ZceLjMd�d_d`��ZdeLjMd�dadb��ZeeLjMd�dcdd��Zfd�dedf�Zgehjidgdh� �ZjeLjMd�didj��Zkdkdl� Zldmdn� Zmdodp� Zndqdr� Zodsdt� Zpdudv� Zqd�dwdx�Zrd�dydz�Zsd S )�� MySQLDialectzMDetails of the MySQL dialect. Not used directly in application code. r] TF� �@ �bool�use_insertmanyvalues�formatN�*r r_ )r_ rY �prefixr^ c K s< |� dd � tjj| fi |�� || _|| _| �|d � d S )NZuse_ansiquotes)�popr7 �DefaultDialectr� Z_json_serializerZ_json_deserializer� _set_mariadb)rj Zjson_serializerZjson_deserializerr& r� rd rd re r� + s zMySQLDialect.__init__c C s dS )N)Z SERIALIZABLEzREAD UNCOMMITTEDzREAD COMMITTEDzREPEATABLE READrd )rj Z dbapi_connrd rd re �get_isolation_level_values8 s z'MySQLDialect.get_isolation_level_valuesc C s. |� � }|�d|� �� |�d� |�� d S )Nz(SET SESSION TRANSACTION ISOLATION LEVEL ZCOMMIT)r6 �execute�close)rj �dbapi_connection�levelr6 rd rd re �set_isolation_level@ s z MySQLDialect.set_isolation_levelc C s� |� � }| jr$| jdkr$|�d� n |�d� |�� }|d u rNt�d� t� �|d }|�� t |t �rp|� � }|� � � dd�S )N)� � � z SELECT @@transaction_isolationzSELECT @@tx_isolationzDCould not retrieve transaction isolation level for MySQL connection.r �-r� )r6 � _is_mysql�server_version_infor� �fetchoner5 r� rm r� r� �bytes�decoder� r� )rj r� r6 �rowr� rd rd re �get_isolation_levelF s � z MySQLDialect.get_isolation_levelc C s� | � � }| |d�}|�|�\}}|j|i |��}zPz"|�� }|�d� |�� d }W n � Y n0 t|�W |�� S W |�� n |�� 0 d S )N)�dbapiz!SELECT VERSION() LIKE '%MariaDB%'r )Z import_dbapiZcreate_connect_args�connectr6 r� r� r� r� ) �cls�urlr� rl ZcargsZcparams�connr6 r� rd rd re �_is_mariadb_from_urlY s �z!MySQLDialect._is_mariadb_from_urlc C sH |j }|�� }|�d� |�� d }|�� t|t�r>|�� }| �|�S )NzSELECT VERSION()r ) � connectionr6 r� r� r� r� r� r� �_parse_server_version)rj r� Z dbapi_conr6 r� rd rd re �_get_server_version_infok s z%MySQLDialect._get_server_version_infoc C s� g }d}t �d�}|�|�}|D ]R}t �d|�}|s8q q |�d�rZt|dd � �| _d}q t|�d��}|�|� q t|�} | � | o�|| � |s�| | _| dk r�t d ��| | _ | S ) NFz[.\-+]z"^(?:(\d+)(?:a|b|c)?|(MariaDB\w*))$� ���Tr )r� r r� zGthe MySQL/MariaDB dialect supports server version info 5.0.2 and above.) r8 �compile�splitr9 �groupr� � _mariadb_normalized_version_inforV r� r� rm r� ) rj r� r� r& �r�tokens�tokenZ parsed_token�digitr� rd rd re r� y s6 � ��z"MySQLDialect._parse_server_versionc C sj |d u r d S |s2| j r2t�dd�tt|��f ��|r`t| jt�sTt| _| �| �| _ d| _ d| _ || _ d S )Nz*MySQL version %s is not a MariaDB variant.r� T) r& r0 ZInvalidRequestErrorr� �mapr� � issubclassr� r� ro �delete_returning�insert_returning)rj r& r� rd rd re r� � s �� zMySQLDialect._set_mariadbc C s |� t�d�t|d�� d S )Nz XA BEGIN :xid��xid�r� r4 r[ re �rj r� r� rd rd re �do_begin_twophase� s z MySQLDialect.do_begin_twophasec C s4 |� t�d�t|d�� |� t�d�t|d�� d S )N� XA END :xidr� zXA PREPARE :xidr r rd rd re �do_prepare_twophase� s z MySQLDialect.do_prepare_twophasec C s8 |s |� t�d�t|d�� |� t�d�t|d�� d S )Nr r� zXA ROLLBACK :xidr �rj r� r� Z is_preparedZrecoverrd rd re �do_rollback_twophase� s z!MySQLDialect.do_rollback_twophasec C s, |s| � ||� |�t�d�t|d�� d S )NzXA COMMIT :xidr� )r r� r4 r[ re r rd rd re �do_commit_twophase� s z MySQLDialect.do_commit_twophasec C s |� d�}dd� |D �S )Nz XA RECOVERc S s g | ]}|d d|d � �qS )�datar Z gtrid_lengthrd �rb r� rd rd re rf � r� z4MySQLDialect.do_recover_twophase.<locals>.<listcomp>��exec_driver_sql)rj r� Z resultsetrd rd re �do_recover_twophase� s z MySQLDialect.do_recover_twophasec C sX t || jj| jj| jjf�r.| �|�dv r.dS t || jj| jjf�rPdt|�v S dS d S )N)i� i� i� i� i� i i� Tz(0, '')F)r� r� ZOperationalErrorZProgrammingErrorZInterfaceError�_extract_error_codeZ InternalErrorr� )rj r� r� r6 rd rd re � is_disconnect� s �� �� zMySQLDialect.is_disconnectc s � fdd�|� � D �S )zMProxy result rows to smooth over MySQL-Python driver inconsistencies.c s g | ]}t |� ��qS rd )� _DecodingRowr �r rd re rf � r� z1MySQLDialect._compat_fetchall.<locals>.<listcomp>)Zfetchall)rj �rpr rd r re �_compat_fetchall� s z MySQLDialect._compat_fetchallc C s |� � }|rt||�S dS dS �zNProxy a result row to smooth over MySQL-Python driver inconsistencies.N)r� r �rj r r r� rd rd re �_compat_fetchone� s z MySQLDialect._compat_fetchonec C s |� � }|rt||�S dS dS r )�firstr r rd rd re � _compat_first� s zMySQLDialect._compat_firstc C s t � �d S ra �rm )rj � exceptionrd rd re r s z MySQLDialect._extract_error_codec C s |� d��� S )NzSELECT DATABASE())r Zscalar�rj r� rd rd re �_get_default_schema_name s z%MySQLDialect._get_default_schema_namec K s� | � |� |d u r| j}|d us$J �d�| j�||��}zJ|jd|� �ddid�� }|�� d uW d � W S 1 sv0 Y W nF tjy� } z,| � |j �dv r�W Y d }~dS � W Y d }~n d }~0 0 d S )Nr� z DESCRIBE �skip_user_error_eventsT)�execution_options)�z i i F) Z _ensure_has_table_connection�default_schema_namer� ro r� r r� r0 � DBAPIErrorr �orig)rj r� � table_namer3 r � full_name�rsr� rd rd re � has_table s( �� �0zMySQLDialect.has_tablec K sF | j s| �� |s| j}|�t�d�tt|�t|�d��}|�� d uS )NzSELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_TYPE='SEQUENCE' and TABLE_NAME=:name AND TABLE_SCHEMA=:schema_name)r� � schema_name) r4 �_sequences_not_supportedr r� r4 r[ re r� r )rj r� Z sequence_namer3 r r6 rd rd re � has_sequence9 s ��� zMySQLDialect.has_sequencec C s t d��d S )NzBSequences are supported only by the MariaDB series 10.3 or greaterr ri rd rd re r' N s �z%MySQLDialect._sequences_not_supportedc K sJ | j s| �� |s| j}|�t�d�t|d��}dd� | j|| jd�D �S )NzjSELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_TYPE='SEQUENCE' and TABLE_SCHEMA=:schema_name)r& c S s g | ] }|d �qS �r rd r rd rd re rf b s �z3MySQLDialect.get_sequence_names.<locals>.<listcomp>r ) r4 r' r r� r4 r[ re r �_connection_charset)rj r� r3 r r6 rd rd re �get_sequence_namesT s ����z MySQLDialect.get_sequence_namesc C s� | � |�| _tj�| |� | �|� | �|� | �|� | jrP| j | | jd�| _ | j o^| j dk| _ | jop| j dk| _| j o�| j dk| _| j o�| j dk| _| j o�| j dk| _| jo�| j dk| _| �� d S )N)r� )� r/ )� )r, r r� )r, r� )r- r r� )�_detect_charsetr* r7 r� � initialize�_detect_sql_mode�_detect_ansiquotes�_detect_casing�_server_ansiquotesr� ro r& r� r4 r� r � _needs_correct_for_88718_96365r� r� r� �_warn_for_known_db_issuesr rd rd re r/ i s, �������zMySQLDialect.initializec C s0 | j r,| j}|dkr,|dk r,t�d|f � d S )N�r, r� )r, r� � a` MariaDB %r before 10.2.9 has known issues regarding CHECK constraints, which impact handling of NULL values with SQLAlchemy's boolean datatype (MDEV-13596). An additional issue prevents proper migrations of columns with CHECK constraints (MDEV-11114). Please upgrade to MariaDB 10.2.9 or greater, or use the MariaDB 10.1 series, to avoid these issues.)r& r� r5 r� )rj Z mdb_versionrd rd re r5 � s ��z&MySQLDialect._warn_for_known_db_issuesc C s( | j s dS | jr| j dkS | j dkS d S )NF)r, � r� )r- r � �r� r& ri rd rd re r� � s z MySQLDialect._support_float_castc C s( | j s dS | jr| j dkS | j dkS d S )NF)r, r� r )r- r � r: ri rd rd re r7 � s z&MySQLDialect._support_default_functionc C s | j S ra �r& ri rd rd re � _is_mariadb� s zMySQLDialect._is_mariadbc C s | j S ra r< ri rd rd re r� � s zMySQLDialect._is_mysqlc C s | j o| jdkS )Nr6 )r& r� ri rd rd re �_is_mariadb_102� s z MySQLDialect._is_mariadb_102c K s |� d�}dd� |D �S )Nz SHOW schemasc S s g | ] }|d �qS r) rd )rb r� rd rd re rf � r� z1MySQLDialect.get_schema_names.<locals>.<listcomp>r )rj r� r r rd rd re �get_schema_names� s z MySQLDialect.get_schema_namesc K sH |dur|}n| j }| j}|�d| j�|� �}dd� | j||d�D �S )z1Return a Unicode SHOW TABLES from a given schema.N�SHOW FULL TABLES FROM %sc S s g | ]}|d dkr|d �qS )r z BASE TABLEr rd r rd rd re rf � s �z0MySQLDialect.get_table_names.<locals>.<listcomp>r �r r* r ro r� r )rj r� r3 r Zcurrent_schemar r rd rd re �get_table_names� s �� �z MySQLDialect.get_table_namesc K sB |d u r| j }| j}|�d| j�|� �}dd� | j||d�D �S )Nr@ c S s g | ]}|d dv r|d �qS )r )ZVIEWz SYSTEM VIEWr rd r rd rd re rf � s �z/MySQLDialect.get_view_names.<locals>.<listcomp>r rA )rj r� r3 r r r rd rd re �get_view_names� s �� �zMySQLDialect.get_view_namesc K s. | j |||fi |��}|jr"|jS t�� S d S ra )�_parsed_state_or_create� table_optionsr8 �rj r� r" r3 r � parsed_staterd rd re �get_table_options� s ��z MySQLDialect.get_table_optionsc K s. | j |||fi |��}|jr"|jS t�� S d S ra )rD ri r8 rF rd rd re � get_columns� s ��zMySQLDialect.get_columnsc K sV | j |||fi |��}|jD ]0}|d dkr dd� |d D �}|d d� S q t�� S )Nr� �PRIMARYc S s g | ] }|d �qS r) rd �rb �srd rd re rf r� z2MySQLDialect.get_pk_constraint.<locals>.<listcomp>ri )�constrained_columnsr� )rD �keysr8 Z pk_constraint)rj r� r" r3 r rG r� r� rd rd re �get_pk_constraint s �� z MySQLDialect.get_pk_constraintc K s� | j |||fi |��}d }g }|jD ]�}|d d } t|d �dkrP|d d pR|} | st|d u rh|jj}||krt|} |d } |d } i } dD ] }|�|d�d vr�|| | |< q�|d | | | | | d �}|�|� q$| jr�| �||� |r�|S t � � S ) Nr� rx r ����localZforeign)ZonupdateZondeleteF)z NO ACTIONNr� )r� rM �referred_schema�referred_table�referred_columns�options) rD Zfk_constraintsr? rl r r� r� r4 �#_correct_for_mysql_bugs_88718_96365r8 Z foreign_keys)rj r� r" r3 r rG Zdefault_schema�fkeysrz �ref_nameZ ref_schemaZ loc_namesZ ref_namesZcon_kwrS Zfkey_drd rd re �get_foreign_keys s@ �� � z MySQLDialect.get_foreign_keysc s� | j dv rdd� }ndd� }|jj}tdd� �}|D ]@� |� d pD|�}|� d �}� d D ]}|| | �|� q\q4|�r�tjd d � |�� D �� } t�t j j t j j t j j ��| �} |�| �} tt�} | D ]V\} }}| | || �||�f d < || || �||�f d < || || �||�f |�� < q�|D ]h}| ||d �p:|�||d �f � � d |d< |d d u�rr� d |d< � fdd�|d D �|d < �q&d S )N)r r� c S s | � � S ra �r� �rL rd rd re r� N s z?MySQLDialect._correct_for_mysql_bugs_88718_96365.<locals>.lowerc S s | S ra rd r[ rd rd re r� U s c S s t t�S ra )r r rd rd rd re �<lambda>] r� zBMySQLDialect._correct_for_mysql_bugs_88718_96365.<locals>.<lambda>rR rS rT c s s: | ]2\}}t �tjj|kt jd d� |�� D �� �V qdS )c s s8 | ]0\}}t �tjj|kt j�tjj��|��V qd S ra ) r4 �and_� _info_columnsr� r" �funcr� � column_nameZin_)rb r� ri rd rd re r� k s � ���zMMySQLDialect._correct_for_mysql_bugs_88718_96365.<locals>.<genexpr>.<genexpr>N)r4 r] r^ r� � table_schema�or_r� )rb r3 r rd rd re r� g s � ���zCMySQLDialect._correct_for_mysql_bugs_88718_96365.<locals>.<genexpr>Z SCHEMANAMEZ TABLENAMEc s g | ]}� |� � �qS rd rZ r� �Zrecrd re rf � s zDMySQLDialect._correct_for_mysql_bugs_88718_96365.<locals>.<listcomp>)�_casingrl r r r� r4 rb r� r� r^ r� ra r" r` �wherer� re r� )rj rW r� r� r Zschema_by_table_by_columnZschZtblZcol_name� conditionr� Zcorrect_for_wrong_fk_case�dr3 Ztname�cnameZfkeyrd rc re rV > sR ���� �� �z0MySQLDialect._correct_for_mysql_bugs_88718_96365c K sF | j |||fi |��}dd� |jD �}|jdd� d� |r>|S t�� S )Nc S s g | ]}|d |d d��qS )r� �sqltext)r� ri rd )rb rz rd rd re rf � s �z6MySQLDialect.get_check_constraints.<locals>.<listcomp>c S s | d p dS �Nr� �~rd �rg rd rd re r\ � r� z4MySQLDialect.get_check_constraints.<locals>.<lambda>r� )rD Zck_constraintsrP r8 Zcheck_constraints)rj r� r" r3 r rG Zcksrd rd re �get_check_constraints� s ���z"MySQLDialect.get_check_constraintsc K sH | j |||fi |��}|j�| j� d�d �}|d ur<d|iS t�� S d S )N�_commentr[ )rD rE r� r� r8 Z table_comment)rj r� r" r3 r rG r1 rd rd re �get_table_comment� s ��z MySQLDialect.get_table_commentc K s0 | j |||fi |��}g }|jD ]�}i }d} |d } | dkr>q | dkrLd} n0| dv rd| |d| j < n| d u rnn| j�d| � |d r�|d |d | j < i } |d | d < d d � |d D �| d< dd� |d D �} | r�| |d| j < | | d< | r�| | d< |�r|| d< |�| � q |jdd� d� |�r(|S t�� S )NFr� rJ �UNIQUET)ZFULLTEXTZSPATIALrW z-Converting unknown KEY type %s to a plain KEYrj z%s_with_parserr� c S s g | ] }|d �qS r) rd rK rd rd re rf � r� z,MySQLDialect.get_indexes.<locals>.<listcomp>ri � column_namesc S s& i | ] }|d dur|d |d �qS )r Nr rd rK rd rd re r� � s z,MySQLDialect.get_indexes.<locals>.<dictcomp>z %s_lengthrc rd c S s | d p dS rj rd rl rd rd re r\ � r� z*MySQLDialect.get_indexes.<locals>.<lambda>r� ) rD rN r� �logger�infor� rP r8 �indexes) rj r� r" r3 r rG rt rz rd rc ZflavorZindex_dZ mysql_lengthrd rd re � get_indexes� sR �� �� � zMySQLDialect.get_indexesc K sJ | j |||fi |��}dd� |jD �}|jdd� d� |r>|S t�� S d S )Nc S s: g | ]2}|d dkr|d dd� |d D �|d d��qS )r� rp r� c S s g | ] }|d �qS r) rd r� rd rd re rf � r� zBMySQLDialect.get_unique_constraints.<locals>.<listcomp>.<listcomp>ri )r� rq Zduplicates_indexrd r� rd rd re rf � s ��z7MySQLDialect.get_unique_constraints.<locals>.<listcomp>c S s | d p dS rj rd rl rd rd re r\ � r� z5MySQLDialect.get_unique_constraints.<locals>.<lambda>r� )rD rN rP r8 Zunique_constraints)rj r� r" r3 r rG Zucsrd rd re �get_unique_constraints� s ��� z#MySQLDialect.get_unique_constraintsc K sH | j }d�| j�||��}| j|d ||d�}|�� �d�rDt�|��|S )Nr� �r# z CREATE TABLE) r* r� ro r� �_show_create_tabler� r> r0 �NoSuchTableError)rj r� Z view_namer3 r r r# r4 rd rd re �get_view_definition s �� z MySQLDialect.get_view_definitionc K s | j ||||�dd �d�S )N� info_cache)r{ )� _setup_parserr� )rj r� r" r3 r rd rd re rD s �z$MySQLDialect._parsed_state_or_createc C s | j }t�| |�S )z�return the MySQLTableDefinitionParser, generate if needed. The deferred creation ensures that the dialect has retrieved server version information first. )ro rQ ZMySQLTableDefinitionParser)rj r� rd rd re �_tabledef_parser s z MySQLDialect._tabledef_parserc K sf | j }| j}d�| j�||��}| j|d ||d�}|�|�rZ| j|d ||d�} |�|| �}|� ||�S )Nr� rw ) r* r} r� ro r� rx Z _check_view�_describe_tableZ_describe_to_create�parse) rj r� r" r3 r r rj r# r4 ri rd rd re r| ( s ��� � zMySQLDialect._setup_parserc C s\ | j }| jr$| jdk r$d| }d}n d| }d}|�|�}| j||d�}|sPd S || S d S )N)r� � zSHOW VARIABLES LIKE '%s'r z SELECT @@%sr r )r* r� r r )rj r� Z setting_namer r4 Z fetch_colZshow_varr� rd rd re �_fetch_setting< s zMySQLDialect._fetch_settingc C s t � �d S ra r r rd rd re r. M s z MySQLDialect._detect_charsetc C sH | � |d�}|du rd}n$|dkr(d}n|dkr6d}nt|�}|| _|S )z�Sniff out identifier case sensitivity. Cached per-connection. This value can not change without a server restart. Zlower_case_table_namesNr ZOFF�ONr )r� rV rd )rj r� �setting�csrd rd re r2 P s zMySQLDialect._detect_casingc C s: i }| j }|�d�}| �||�D ]}|d ||d < q |S )zYPull the active COLLATIONS list from the server. Cached per-connection. zSHOW COLLATIONr r )r* r r )rj r� Z collationsr r$ r� rd rd re �_detect_collationsh s z MySQLDialect._detect_collationsc C s4 | � |d�}|d u r&t�d� d| _n |p,d| _d S )NZsql_modez[Could not retrieve SQL_MODE; please ensure the MySQL user has permissions to SHOW VARIABLESry )r� r5 r� � _sql_mode)rj r� r� rd rd re r0 u s �z MySQLDialect._detect_sql_modec C sL | j }|sd}n$|�� r4t|�}|dB |kr0dp2d}d|v | _d|v| _dS )z/Detect and adjust for the ANSI_QUOTES sql mode.ry r8 Z ANSI_QUOTESZNO_BACKSLASH_ESCAPESN)r� �isdigitrV r3 r� )rj r� �modeZmode_nord rd re r1 � s z MySQLDialect._detect_ansiquotesc C s� |du r| j �|�}d| }z|jdd��|�}W nF tjyx } z,| �|j�dkrbt�|�|�n� W Y d}~n d}~0 0 | j ||d�}|s�t�|��|d � � S )z&Run SHOW CREATE TABLE for a ``Table``.NzSHOW CREATE TABLE %sT�r r r r ) ro ra r r r0 r r r! ry r �strip) rj r� r� r r# �str r� r� rd rd re rx � s" �� z MySQLDialect._show_create_tablec C s� |du r| j �|�}d| }d\}}z�z|jdd��|�}W nh tjy� } zN| �|j�} | dkrpt�|�|�n | dkr�t� d||f �|�n� W Y d}~n d}~0 0 | j ||d �}W |r�|� � n|r�|� � 0 |S ) z7Run DESCRIBE for a ``Table`` and return processed rows.Nz DESCRIBE %s)NNTr� r iL z1Table or view named %s could not be reflected: %sr ) ro ra r r r0 r r r! ry ZUnreflectableTableErrorr r� ) rj r� r� r r# r� r �rowsr� �coderd rd re r~ � s< �� ��� � z MySQLDialect._describe_table)NNN)TF)TF)N)N)N)N)N)N)N)N)N)N)N)N)N)N)N)N)N)N)N)NN)NN)trt ru rv �__doc__r� Zsupports_statement_cacheZsupports_alterZsupports_native_booleanZsupports_native_bitZmax_identifier_lengthZmax_index_name_lengthZmax_constraint_name_lengthZdiv_is_floordivZsupports_native_enumZreturns_native_bytesr4 Zsequences_optionalr r� Zsupports_default_valuesZsupports_default_metavaluer� �__annotations__rA ZANY_AUTOINCREMENTZ"insertmanyvalues_implicit_sentinelZsupports_sane_rowcountZ supports_sane_multi_rowcountZsupports_multivalues_insertZ#insert_null_pk_still_autoincrementsZsupports_commentsZinline_commentsZdefault_paramstyle�colspecsZcte_follows_insertrw Zstatement_compilerr/ Z ddl_compilerrx Ztype_compiler_cls� ischema_namesr� r� r& r� r� r3 r3 ZTabler4 ZUpdate�Deleterp �IndexZconstruct_argumentsr� r� r� r� � classmethodr� r� r� r� r r r r r r r r r r r r �cacher% r( r' r+ r/ r5 �propertyr� r7 r= r� r> r? rB rC rH rI rO rY rV rm ro ru rv rz rD r5 Zmemoized_propertyr} r| r� r. r2 r� r0 r1 rx r~ rd rd rd re r� � s � ��� � & � � - / )d 3 � � � r� c @ s: e Zd ZdZddddddd�Zdd � Zd d � Zd d � ZdS )r z�Return unicode-decoded values based on type inspection. Smooth over data type issues (esp. with alpha driver versions) and normalize strings as Unicode regardless of user-configured driver encoding settings. �koi8_r�koi8_uz utf-16-be�utf8�ujis)Zkoi8rZkoi8u�utf16Zutf8mb4Zutf8mb3Zeucjpmsc C s || _ | j�||�| _d S ra )�rowproxy�_encoding_compatr� r )rj r� r rd rd re r� � s z_DecodingRow.__init__c C s@ | j | }t|t�r |�� }| jr8t|t�r8|�| j�S |S d S ra )r� r� �_array�tostringr r� r� )rj rh �itemrd rd re � __getitem__� s z_DecodingRow.__getitem__c C sB t | j|�}t|t�r |�� }| jr:t|t�r:|�| j�S |S d S ra )r� r� r� r� r� r r� r� )rj r~ r� rd rd re � __getattr__� s z_DecodingRow.__getattr__N)rt ru rv r� r� r� r� r� rd rd rd re r � s � r ri ra r� r" r` Zinformation_schema)�r� � __future__r r r� � collectionsr � itertoolsr r8 �typingr ry r rQ Z enumeratedr r rX r r r r� r r �typesr r r r r r r r r r r r r r r r r r! r" r# r$ r% r& r' r( r) r* r+ r, r- r. r0 r1 r2 r3 r3 r4 r5 Zenginer6 rh r7 Zengine.reflectionr8 r9 r: r; r< r= r> r? r r@ Z sql.compilerrA rB Z sql.schemarC rD rE rF rG rH rI rJ r� r; r� ZSET_REZMSTimeZMSSetZMSEnumZ MSLongBlobZ MSMediumBlobZ MSTinyBlobZMSBlobZMSBinaryZ MSVarBinaryZMSNCharZ MSNVarCharZMSCharZMSStringZ MSLongTextZ MSMediumTextZ MSTinyTextZMSTextZMSYearZ MSTimeStampZMSBitZMSSmallIntegerZ MSTinyIntegerZMSMediumIntegerZ MSBigIntegerZ MSNumericZ MSDecimalZMSDoubleZMSRealZMSFloatZ MSIntegerr� r� �Doubler� �EnumZ MatchTyper� r� ZDefaultExecutionContextr` rw Z DDLCompilerr/ ZGenericTypeCompilerrx ZIdentifierPreparerr� r� Z class_loggerr� r� r r� r� r^ rd rd rd re �<module> s� ) ���(+ Y 2 5 /� sqlalchemy/dialects/mysql/__pycache__/dml.cpython-39.pyc 0000644 00000016452 15125143220 0017263 0 ustar 00 a ��JhX � @ s^ d dl mZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlm Z d d l m Z d d l m Z d d l mZ d d lmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dl m Z d dl m Z dZ ddd�dd �Z!G d d� de�ZG d d � d e�Z"e eeef eee#ef eeef f Z$d S )!� )� annotations)�Any)�Dict)�List)�Mapping)�Optional)�Tuple)�Union� )�exc)�util)�_DMLTableArgument)�_exclusive_against)� _generative)�ColumnCollection)�ReadOnlyColumnCollection��Insert)� ClauseElement)�KeyedColumnElement)�alias)�NamedFromClause)�Self)r �insertr r )�table�returnc C s t | �S )a( Construct a MySQL/MariaDB-specific variant :class:`_mysql.Insert` construct. .. container:: inherited_member The :func:`sqlalchemy.dialects.mysql.insert` function creates a :class:`sqlalchemy.dialects.mysql.Insert`. This class is based on the dialect-agnostic :class:`_sql.Insert` construct which may be constructed using the :func:`_sql.insert` function in SQLAlchemy Core. The :class:`_mysql.Insert` construct includes additional methods :meth:`_mysql.Insert.on_duplicate_key_update`. r )r � r �R/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mysql/dml.pyr # s r c @ sd e Zd ZdZdZdZedd�dd��Zej dd�d d ��Z e e d d d id �dddd�dd���Z dS )r a MySQL-specific implementation of INSERT. Adds methods for MySQL-specific syntaxes such as ON DUPLICATE KEY UPDATE. The :class:`~.mysql.Insert` object is created using the :func:`sqlalchemy.dialects.mysql.insert` function. .. versionadded:: 1.2 �mysqlFz6ReadOnlyColumnCollection[str, KeyedColumnElement[Any]])r c C s | j jS )a� Provide the "inserted" namespace for an ON DUPLICATE KEY UPDATE statement MySQL's ON DUPLICATE KEY UPDATE clause allows reference to the row that would be inserted, via a special function called ``VALUES()``. This attribute provides all columns in this row to be referenceable such that they will render within a ``VALUES()`` function inside the ON DUPLICATE KEY UPDATE clause. The attribute is named ``.inserted`` so as not to conflict with the existing :meth:`_expression.Insert.values` method. .. tip:: The :attr:`_mysql.Insert.inserted` attribute is an instance of :class:`_expression.ColumnCollection`, which provides an interface the same as that of the :attr:`_schema.Table.c` collection described at :ref:`metadata_tables_and_columns`. With this collection, ordinary names are accessible like attributes (e.g. ``stmt.inserted.some_column``), but special names and dictionary method names should be accessed using indexed access, such as ``stmt.inserted["column name"]`` or ``stmt.inserted["values"]``. See the docstring for :class:`_expression.ColumnCollection` for further examples. .. seealso:: :ref:`mysql_insert_on_duplicate_key_update` - example of how to use :attr:`_expression.Insert.inserted` )�inserted_alias�columns��selfr r r �insertedE s zInsert.insertedr c C s t | jdd�S )Nr# )�name)r r r! r r r r g s zInsert.inserted_alias�_post_values_clausezDThis Insert construct already has an ON DUPLICATE KEY clause present)Zmsgs� _UpdateArgr r )�args�kwr c O sL |r|rt �d��|r6t|�dkr,t �d��|d }n|}t| j|�| _| S )a� Specifies the ON DUPLICATE KEY UPDATE clause. :param \**kw: Column keys linked to UPDATE values. The values may be any SQL expression or supported literal Python values. .. warning:: This dictionary does **not** take into account Python-specified default UPDATE values or generation functions, e.g. those specified using :paramref:`_schema.Column.onupdate`. These values will not be exercised for an ON DUPLICATE KEY UPDATE style of UPDATE, unless values are manually specified here. :param \*args: As an alternative to passing key/value parameters, a dictionary or list of 2-tuples can be passed as a single positional argument. Passing a single dictionary is equivalent to the keyword argument form:: insert().on_duplicate_key_update({"name": "some name"}) Passing a list of 2-tuples indicates that the parameter assignments in the UPDATE clause should be ordered as sent, in a manner similar to that described for the :class:`_expression.Update` construct overall in :ref:`tutorial_parameter_ordered_updates`:: insert().on_duplicate_key_update( [ ("name", "some name"), ("value", "some value"), ] ) .. versionchanged:: 1.3 parameters can be specified as a dictionary or list of 2-tuples; the latter form provides for parameter ordering. .. versionadded:: 1.2 .. seealso:: :ref:`mysql_insert_on_duplicate_key_update` z9Can't pass kwargs and positional arguments simultaneously� zDOnly a single dictionary or list of tuples is accepted positionally.r )r � ArgumentError�len�OnDuplicateClauser r% )r" r' r( �valuesr r r �on_duplicate_key_updatek s 8� � �z Insert.on_duplicate_key_updateN)�__name__� __module__� __qualname__�__doc__�stringify_dialectZ inherit_cache�propertyr# r Zmemoized_propertyr r r r. r r r r r 6 s !��c @ s< e Zd ZU dZdZded< ded< dZdd d d �d d �ZdS )r, r. NzOptional[List[str]]�_parameter_orderingzDict[str, Any]�updater r r& �None)r r6 r c C sx || _ t|t�r:|r:t|d t�r:dd� |D �| _t|�}t|t�rR|sntd��n t|t�rft|�}ntd��|| _d S )Nr c S s g | ] \}}|�qS r r )�.0�key�valuer r r � <listcomp>� � z.OnDuplicateClause.__init__.<locals>.<listcomp>z-update parameter dictionary must not be emptyztupdate parameter must be a non-empty dictionary or a ColumnCollection such as the `.c.` collection of a Table object) r � isinstance�list�tupler5 �dict� ValueErrorr r6 )r" r r6 r r r �__init__� s& � � � �zOnDuplicateClause.__init__)r/ r0 r1 Z__visit_name__r5 �__annotations__r3 rB r r r r r, � s r, N)%� __future__r �typingr r r r r r r � r r Z sql._typingr Zsql.baser r r r Zsql.dmlr ZStandardInsertZ sql.elementsr r Zsql.expressionr Zsql.selectabler Z util.typingr �__all__r r, �strr& r r r r �<module> s8 '$� sqlalchemy/dialects/mysql/__pycache__/__init__.cpython-39.pyc 0000644 00000003521 15125143220 0020237 0 ustar 00 a ��Jh� � @ sT d dl mZ d dl mZ d dl mZ d dl mZ d dl mZ d dl mZ d dl mZ d dl mZ d d l m Z d d lm Z d d lm Z d d lm Z d d lm Z d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d d lm Z d d lm Z d d lm Z d d lm Z d d lm Z d d!lm!Z! d d"lm"Z" d d#lm#Z# d d$lm$Z$ d d%lm%Z% d d&lm&Z& d d'lm'Z' d d(lm(Z( d d)lm)Z) d d*lm*Z* d d+lm+Z+ d d,l,m-Z- d d-l,m.Z. d d.l/m0Z0 d d/l1m2Z2 d d0l1m3Z3 ej4 e_4Z4d1Z5d2S )3� )�aiomysql)�asyncmy)�base)�cymysql)�mariadbconnector)�mysqlconnector)�mysqldb)�pymysql)�pyodbc)�BIGINT)�BINARY)�BIT)�BLOB)�BOOLEAN)�CHAR)�DATE)�DATETIME)�DECIMAL)�DOUBLE)�ENUM)�FLOAT)�INTEGER)�JSON)�LONGBLOB)�LONGTEXT)� MEDIUMBLOB)� MEDIUMINT)� MEDIUMTEXT)�NCHAR)�NUMERIC)�NVARCHAR)�REAL)�SET)�SMALLINT)�TEXT)�TIME)� TIMESTAMP)�TINYBLOB)�TINYINT)�TINYTEXT)� VARBINARY)�VARCHAR)�YEAR)�Insert)�insert)�match)�INET4)�INET6))r r r r r r r r r r r r r0 r1 r r r r r r r r r r r r" r# r! r$ r% r& r' r( r) r* r+ r, �dialectr. r- r/ N)6� r r r r r r r r r r r r r r r r r r r r r r r r r r r r r r r r! r" r# r$ r% r& r' r( r) r* r+ r, Zdmlr- r. Z expressionr/ Zmariadbr0 r1 r2 �__all__� r5 r5 �W/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mysql/__init__.py�<module> sb sqlalchemy/dialects/mysql/__pycache__/pyodbc.cpython-39.pyc 0000644 00000010263 15125143220 0017761 0 ustar 00 a ��Jh� � @ s� d Z ddlZddlmZ ddlmZ ddlmZ ddlmZ dd lm Z dd l m Z dd l m Z G d d � d e�ZG dd� de�ZG dd� de e�ZeZdS )aI .. dialect:: mysql+pyodbc :name: PyODBC :dbapi: pyodbc :connectstring: mysql+pyodbc://<username>:<password>@<dsnname> :url: https://pypi.org/project/pyodbc/ .. note:: The PyODBC for MySQL dialect is **not tested as part of SQLAlchemy's continuous integration**. The recommended MySQL dialects are mysqlclient and PyMySQL. However, if you want to use the mysql+pyodbc dialect and require full support for ``utf8mb4`` characters (including supplementary characters like emoji) be sure to use a current release of MySQL Connector/ODBC and specify the "ANSI" (**not** "Unicode") version of the driver in your DSN or connection string. Pass through exact pyodbc connection string:: import urllib connection_string = ( "DRIVER=MySQL ODBC 8.0 ANSI Driver;" "SERVER=localhost;" "PORT=3307;" "DATABASE=mydb;" "UID=root;" "PWD=(whatever);" "charset=utf8mb4;" ) params = urllib.parse.quote_plus(connection_string) connection_uri = "mysql+pyodbc:///?odbc_connect=%s" % params � N� )� MySQLDialect)�MySQLExecutionContext)�TIME� )�exc)�util)�PyODBCConnector)�Timec @ s e Zd Zdd� ZdS )� _pyodbcTIMEc C s dd� }|S )Nc S s | S �N� )�valuer r �U/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mysql/pyodbc.py�process= s z-_pyodbcTIME.result_processor.<locals>.processr )�self�dialectZcoltyper r r r �result_processor< s z _pyodbcTIME.result_processorN)�__name__� __module__� __qualname__r r r r r r ; s r c @ s e Zd Zdd� ZdS )� MySQLExecutionContext_pyodbcc C s* | � � }|�d� |�� d }|�� |S )NzSELECT LAST_INSERT_ID()r )Z create_cursor�executeZfetchone�close)r �cursorZ lastrowidr r r � get_lastrowidE s z*MySQLExecutionContext_pyodbc.get_lastrowidN)r r r r r r r r r D s r c sV e Zd ZdZe�ejee i�ZdZ e Z dZ dd� Zdd� Zdd� Z� fd d �Z� ZS ) �MySQLDialect_pyodbcTZMySQLc C sD d| _ z| �|d�}|r |W S W n tjy4 Y n0 t�d� dS )z:Sniff out the character set in use for connection results.NZcharacter_set_clientz@Could not detect the connection character set. Assuming latin1.�latin1)Z_connection_charsetZ_fetch_settingr Z DBAPIErrorr �warn)r � connectionr r r r �_detect_charsetU s �z#MySQLDialect_pyodbc._detect_charsetc C s t �| |�S r )r �_get_server_version_info)r r r r r r! n s z,MySQLDialect_pyodbc._get_server_version_infoc C s4 t �d��t|j��}|�d�}|r,t|�S d S d S )Nz \((\d+)\)r )�re�compile�search�str�args�group�int)r � exception�m�cr r r �_extract_error_codeq s z'MySQLDialect_pyodbc._extract_error_codec s t � �� � � fdd�}|S )Nc sD � d ur� | � d}d}| j |dd� | j |dd� | jdd� d S )Nr i����zutf-8)�encoding)Z setdecodingZ setencoding)�connZpyodbc_SQL_CHARZpyodbc_SQL_WCHAR�Zsuper_r r � on_connect| s z2MySQLDialect_pyodbc.on_connect.<locals>.on_connect)�superr0 )r r0 �� __class__r/ r r0 y s z MySQLDialect_pyodbc.on_connect)r r r Zsupports_statement_cacher Z update_copyr Zcolspecsr r Zsupports_unicode_statementsr Zexecution_ctx_clsZpyodbc_driver_namer r! r, r0 � __classcell__r r r2 r r M s r )�__doc__r" �baser r �typesr � r r Zconnectors.pyodbcr Z sql.sqltypesr r r r r r r r r �<module> s & > sqlalchemy/dialects/mysql/__pycache__/provision.cpython-39.pyc 0000644 00000005235 15125143220 0020534 0 ustar 00 a ��Jh� � @ s� d dl mZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ e� dd �d d � �Ze� dd �d d � �Z e� dd �dd� �Z e� dd �dd� �Z e� dd �dd� �Z e� d �ddd�dd��ZdS )� )�exc)�configure_follower)� create_db)�drop_db)�generate_driver_url)�temp_table_keyword_args)�upsert�mysql�mariadbc C s� | � � }|dkr&| �� }|�| �r&d}| jd||f d��|�}|dkrV|�dg�}n|dkrj|�dg�}z |�� W n tjy� Y d S 0 |S d S ) Nr r z%s+%s)Z drivernameZmariadbconnector�charsetZmysqlconnector)Z collationZutf8mb4_general_ci) Zget_backend_name� get_dialectZ_is_mariadb_from_url�setZupdate_query_stringZdifference_update_queryZupdate_query_pairsr ZNoSuchModuleError)�urlZdriverZ query_str�backendZ dialect_cls�new_url� r �X/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mysql/provision.pyr s* ��� r c C s� |� � �4}zt| ||� W n ty, Y n0 W d � n1 sB0 Y |� � �:}|�d| � |�d| � |�d| � W d � n1 s�0 Y d S )Nz(CREATE DATABASE %s CHARACTER SET utf8mb4z4CREATE DATABASE %s_test_schema CHARACTER SET utf8mb4z6CREATE DATABASE %s_test_schema_2 CHARACTER SET utf8mb4)�begin�_mysql_drop_db� Exception�exec_driver_sql��cfg�eng�ident�connr r r �_mysql_create_db: s $ ���r c C s d| | _ d| | _d S )Nz%s_test_schemaz%s_test_schema_2)Z test_schemaZ test_schema_2)�configr r r r �_mysql_configure_followerN s r c C sV |� � �:}|�d| � |�d| � |�d| � W d � n1 sH0 Y d S )Nz DROP DATABASE %s_test_schemaz DROP DATABASE %s_test_schema_2zDROP DATABASE %s)r r r r r r r T s r c C s ddgiS )N�prefixes� TEMPORARYr )r r r r r � _mysql_temp_table_keyword_args\ s r! NF)� set_lambda�sort_by_parameter_orderc C s` ddl m} ||�}|r0|jf i ||j���}n |jjd }|�|j|i�}|j|d|i�}|S )N� )�insertr# )Zsqlalchemy.dialects.mysqlr% Zon_duplicate_key_updateZinsertedZ primary_key�c�key� returning)r �tabler( r" r# r% �stmtZpk1r r r �_upserta s ��r+ )� r Ztesting.provisionr r r r r r Zfor_dbr r r r! r+ r r r r �<module> s& ' � sqlalchemy/dialects/mysql/__pycache__/mariadbconnector.cpython-39.pyc 0000644 00000020205 15125143220 0022010 0 ustar 00 a ��Jh�! � @ s� d Z ddlZddlmZ ddlmZ ddlmZ ddlmZ dd l m Z dd l m Z dd l m Z d Z G d d� de je j �ZG dd� de�ZG dd� de�ZG dd� de�ZeZdS )a� .. dialect:: mysql+mariadbconnector :name: MariaDB Connector/Python :dbapi: mariadb :connectstring: mariadb+mariadbconnector://<user>:<password>@<host>[:<port>]/<dbname> :url: https://pypi.org/project/mariadb/ Driver Status ------------- MariaDB Connector/Python enables Python programs to access MariaDB and MySQL databases using an API which is compliant with the Python DB API 2.0 (PEP-249). It is written in C and uses MariaDB Connector/C client library for client server communication. Note that the default driver for a ``mariadb://`` connection URI continues to be ``mysqldb``. ``mariadb+mariadbconnector://`` is required to use this driver. .. mariadb: https://github.com/mariadb-corporation/mariadb-connector-python � N)�UUID� )� MySQLCompiler)� MySQLDialect)�MySQLExecutionContext� )�sql)�util)�sqltypes)r r r c @ s e Zd Zdd� ZdS )� _MariaDBUUIDc C s" | j rdd� }|S dd� }|S d S )Nc S s( | d ur$t | d�r | �d�} t| �} | S �N�decode�ascii)�hasattrr � _python_UUID��value� r �_/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mysql/mariadbconnector.py�process5 s z._MariaDBUUID.result_processor.<locals>.processc S s, | d ur(t | d�r | �d�} tt| ��} | S r )r r �strr r r r r r ? s )Zas_uuid)�self�dialectZcoltyper r r r �result_processor2 s z _MariaDBUUID.result_processorN)�__name__� __module__� __qualname__r r r r r r . s r c s8 e Zd ZdZdd� Zdd� Z� fdd�Zdd � Z� ZS ) �&MySQLExecutionContext_mariadbconnectorNc C s | j jdd�S )NF�Zbuffered�Z_dbapi_connection�cursor�r r r r �create_server_side_cursorL s z@MySQLExecutionContext_mariadbconnector.create_server_side_cursorc C s | j jdd�S )NTr r r! r r r �create_default_cursorO s z<MySQLExecutionContext_mariadbconnector.create_default_cursorc s0 t � �� | jj| _| jr,| jjr,| jj| _ d S �N) �super� post_execr ZrowcountZ _rowcountZisinsertZcompiledZpostfetch_lastrowidZ lastrowid� _lastrowidr! �� __class__r r r& R s z0MySQLExecutionContext_mariadbconnector.post_execc C s | j S r$ )r' r! r r r � get_lastrowidZ s z4MySQLExecutionContext_mariadbconnector.get_lastrowid) r r r r' r" r# r& r* � __classcell__r r r( r r I s r c @ s e Zd ZdS )� MySQLCompiler_mariadbconnectorN)r r r r r r r r, ^ s r, c s� e Zd ZdZdZdZdZdZdZdZ dZ dZ e Z eZdZe�ejejei�Zejdd� �Z� fdd�Zed d � �Z � fd d �Z d d� Z dd� Z dd� Z dd� Z!� fdd�Z"dd� Z#dd� Z$d d d �Z%d!d d �Z&� Z'S )"� MySQLDialect_mariadbconnectorZmariadbconnectorT�utf8mb4�qmarkc C s8 | j r0t| j d�r0tdd� t�d| j j�D ��S dS d S )N� __version__c S s g | ] }t |��qS r )�int��.0�xr r r � <listcomp>� s �z@MySQLDialect_mariadbconnector._dbapi_version.<locals>.<listcomp>z(\d+)(?:[-\.]?|$))�c r6 r6 )�dbapir �tuple�re�findallr0 r! r r r �_dbapi_version� s ��� z,MySQLDialect_mariadbconnector._dbapi_versionc sL t � jf i |�� d| _| jd urH| jtk rHtdd�dd� tD �� ��d S )Nr/ z?The minimum required version for MariaDB Connector/Python is %s�.c s s | ]}t |�V qd S r$ )r r2 r r r � <genexpr>� � z9MySQLDialect_mariadbconnector.__init__.<locals>.<genexpr>)r% �__init__Z paramstyler7 r; �mariadb_cpy_minimum_version�NotImplementedError�join)r �kwargsr( r r r? � s ��z&MySQLDialect_mariadbconnector.__init__c C s t d�S )NZmariadb)� __import__)�clsr r r � import_dbapi� s z*MySQLDialect_mariadbconnector.import_dbapic sF t � �|||�rdS t|| jj�r>t|��� }d|v p<d|v S dS d S )NTz not connectedz isn't validF)r% � is_disconnect� isinstancer7 �Errorr �lower)r �e� connectionr Zstr_er( r r rG � s z+MySQLDialect_mariadbconnector.is_disconnectc C s� |� � }|�|j� g d�}g d�}|D ]}t�||t� q(|D ]}t�||t� q@|�dd�}| jd ur�z"t | jj d �j j }||j O }W n ttfy� d| _Y n0 ||d< g |gS )N)�connect_timeout� read_timeoutZ write_timeout� client_flag�portZ pool_size)Z local_infileZssl_verify_cert�sslZpool_reset_connection�compressrO r z.constants.CLIENTF)Ztranslate_connect_args�update�queryr Zcoerce_kw_typer1 �bool�getr7 rD r � constantsZCLIENTZ FOUND_ROWS�AttributeError� ImportError�supports_sane_rowcount)r �url�optsZ int_paramsZ bool_params�keyrO Z CLIENT_FLAGSr r r �create_connect_args� s& � z1MySQLDialect_mariadbconnector.create_connect_argsc C s z |j }W n d}Y n0 |S )N���)�errno)r � exception�rcr r r �_extract_error_code� s z1MySQLDialect_mariadbconnector._extract_error_codec C s dS )Nr. r )r rL r r r �_detect_charset� s z-MySQLDialect_mariadbconnector._detect_charsetc C s dS )N)Z SERIALIZABLEzREAD UNCOMMITTEDzREAD COMMITTEDzREPEATABLE READ� AUTOCOMMITr )r Zdbapi_connectionr r r �get_isolation_level_values� s z8MySQLDialect_mariadbconnector.get_isolation_level_valuesc s( |dkrd|_ nd|_ t� �||� d S )Nre TF)Z autocommitr% �set_isolation_level)r rL �levelr( r r rg � s z1MySQLDialect_mariadbconnector.set_isolation_levelc C s& |� t�d��tjd|dd��� d S )Nz XA BEGIN :xid�xidT�Zliteral_execute��executer �text� bindparams� bindparam�r rL ri r r r �do_begin_twophase� s ��z/MySQLDialect_mariadbconnector.do_begin_twophasec C sH |� t�d��tjd|dd��� |� t�d��tjd|dd��� d S )N� XA END :xidri Trj zXA PREPARE :xidrk rp r r r �do_prepare_twophase� s �� ��z1MySQLDialect_mariadbconnector.do_prepare_twophaseFc C sL |s&|� t�d��tjd|dd��� |� t�d��tjd|dd��� d S )Nrr ri Trj zXA ROLLBACK :xidrk �r rL ri Z is_preparedZrecoverr r r �do_rollback_twophase� s �� ��z2MySQLDialect_mariadbconnector.do_rollback_twophasec C s6 |s| � ||� |�t�d��tjd|dd��� d S )NzXA COMMIT :xidri Trj )rs rl r rm rn ro rt r r r �do_commit_twophase s ��z0MySQLDialect_mariadbconnector.do_commit_twophase)TF)TF)(r r r ZdriverZsupports_statement_cacheZsupports_unicode_statements�encodingZconvert_unicoderZ Z supports_sane_multi_rowcountZsupports_native_decimalZdefault_paramstyler Zexecution_ctx_clsr, Zstatement_compilerZ supports_server_side_cursorsr Z update_copyr Zcolspecsr ZUuidr Zmemoized_propertyr; r? � classmethodrF rG r^ rc rd rf rg rq rs ru rv r+ r r r( r r- b s@ � ' � �r- )�__doc__r9 �uuidr r �baser r r � r r r r@ Z _UUID_RETURNr r r, r- r r r r r �<module> s 4 sqlalchemy/dialects/mysql/__pycache__/types.cpython-39.pyc 0000644 00000063474 15125143220 0017661 0 ustar 00 a ��Jh�^ � @ sr d dl Z ddlmZ ddlmZ ddlmZ G dd� d�ZG dd � d eej�ZG d d � d eej �Z G d d � d ej �Z G dd� dejej �ZG dd� deej�ZG dd� deej�ZG dd� deej�ZG dd� deej�ZG dd� deej�ZG dd� de ej�ZG d d � d e ej�ZG d d � d e �ZG d d!� d!e �ZG d"d#� d#e ej�ZG d$d%� d%ej�ZG d&d'� d'ej�ZG d(d)� d)ej �Z G d*d+� d+ej �Z G d,d-� d-ej�Z G d.d/� d/e ej �Z G d0d1� d1e �Z G d2d3� d3e �Z!G d4d5� d5e �Z"G d6d7� d7e ej#�Z#G d8d9� d9e ej$�Z$G d:d;� d;e ej%�Z%G d<d=� d=e ej&�Z&G d>d?� d?ej'�Z(G d@dA� dAej'�Z)G dBdC� dCej'�Z*dS )D� N� )�exc)�util)�sqltypesc s* e Zd ZdZd� fdd� Zdd� Z� ZS )� _NumericTypezvBase for MySQL numeric types. This is the base both for NUMERIC as well as INTEGER, hence it's a mixin. Fc s" || _ || _t� jf i |�� d S �N)�unsigned�zerofill�super�__init__)�selfr r �kw�� __class__� �T/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/mysql/types.pyr s z_NumericType.__init__c C s t j| ttjgd�S �N)Z to_inspect)r � generic_reprr r ZNumeric�r r r r �__repr__ s �z_NumericType.__repr__)FF��__name__� __module__� __qualname__�__doc__r r � __classcell__r r r r r s r c s& e Zd Zd� fdd� Zdd� Z� ZS )� _FloatTypeNTc sZ t | ttf�r8|d u r |d us.|d ur8|d u r8t�d��t� jf ||d�|�� || _d S )NzBYou must specify both precision and scale or omit both altogether.)� precision� asdecimal)� isinstance�REAL�DOUBLEr � ArgumentErrorr r �scale�r r r# r r r r r r % s �����z_FloatType.__init__c C s t j| tttjgd�S r )r r r r r �Floatr r r r r 1 s �z_FloatType.__repr__)NNT�r r r r r r r r r r r $ s r c s& e Zd Zd� fdd� Zdd� Z� ZS )� _IntegerTypeNc s || _ t� jf i |�� d S r )� display_widthr r �r r( r r r r r 8 s z_IntegerType.__init__c C s t j| tttjgd�S r )r r r' r r �Integerr r r r r < s �z_IntegerType.__repr__)Nr& r r r r r' 7 s r' c s* e Zd ZdZd� fdd� Zdd� Z� ZS ) � _StringTypez Base for MySQL string types.NFc sH || _ |�d|�d|�� || _|| _|| _|| _t� jf i |�� d S )N� collationZcollate) �charset� setdefault�pop�ascii�unicode�binary�nationalr r )r r- r, r0 r2 r1 r3 r r r r r E s z_StringType.__init__c C s t j| ttjgd�S r )r r r+ r �Stringr r r r r Z s �z_StringType.__repr__)NNFFFFr r r r r r+ B s �r+ c @ s e Zd Zdd� ZdS )� _MatchTypec K s t j�| � t j�| � d S r )r r% r � MatchType)r r r r r r a s z_MatchType.__init__N)r r r r r r r r r5 ` s r5 c s& e Zd ZdZd Zd� fdd� Z� ZS )�NUMERICzMySQL NUMERIC type.NTc s t � jf |||d�|�� dS )a# Construct a NUMERIC. :param precision: Total digits in this number. If scale and precision are both None, values are stored to limits allowed by the server. :param scale: The number of digits after the decimal point. :param unsigned: a boolean, optional. :param zerofill: Optional. If true, values will be stored as strings left-padded with zeros. Note that this does not effect the values returned by the underlying database API, which continue to be numeric. �r r# r N�r r r$ r r r r l s ��zNUMERIC.__init__)NNT�r r r r �__visit_name__r r r r r r r7 g s r7 c s& e Zd ZdZd Zd� fdd� Z� ZS )�DECIMALzMySQL DECIMAL type.NTc s t � jf |||d�|�� dS )a# Construct a DECIMAL. :param precision: Total digits in this number. If scale and precision are both None, values are stored to limits allowed by the server. :param scale: The number of digits after the decimal point. :param unsigned: a boolean, optional. :param zerofill: Optional. If true, values will be stored as strings left-padded with zeros. Note that this does not effect the values returned by the underlying database API, which continue to be numeric. r8 Nr9 r$ r r r r � s ��zDECIMAL.__init__)NNTr: r r r r r< � s r< c s& e Zd ZdZd Zd� fdd� Z� ZS )r! zMySQL DOUBLE type.NTc s t � jf |||d�|�� dS )a� Construct a DOUBLE. .. note:: The :class:`.DOUBLE` type by default converts from float to Decimal, using a truncation that defaults to 10 digits. Specify either ``scale=n`` or ``decimal_return_scale=n`` in order to change this scale, or ``asdecimal=False`` to return values directly as Python floating points. :param precision: Total digits in this number. If scale and precision are both None, values are stored to limits allowed by the server. :param scale: The number of digits after the decimal point. :param unsigned: a boolean, optional. :param zerofill: Optional. If true, values will be stored as strings left-padded with zeros. Note that this does not effect the values returned by the underlying database API, which continue to be numeric. r8 Nr9 r$ r r r r � s ��zDOUBLE.__init__)NNTr: r r r r r! � s r! c s& e Zd ZdZd Zd� fdd� Z� ZS )r zMySQL REAL type.NTc s t � jf |||d�|�� dS )a� Construct a REAL. .. note:: The :class:`.REAL` type by default converts from float to Decimal, using a truncation that defaults to 10 digits. Specify either ``scale=n`` or ``decimal_return_scale=n`` in order to change this scale, or ``asdecimal=False`` to return values directly as Python floating points. :param precision: Total digits in this number. If scale and precision are both None, values are stored to limits allowed by the server. :param scale: The number of digits after the decimal point. :param unsigned: a boolean, optional. :param zerofill: Optional. If true, values will be stored as strings left-padded with zeros. Note that this does not effect the values returned by the underlying database API, which continue to be numeric. r8 Nr9 r$ r r r r � s ��z REAL.__init__)NNTr: r r r r r � s r c s. e Zd ZdZd Zd� fdd� Zdd� Z� ZS ) �FLOATzMySQL FLOAT type.NFc s t � jf |||d�|�� dS )a! Construct a FLOAT. :param precision: Total digits in this number. If scale and precision are both None, values are stored to limits allowed by the server. :param scale: The number of digits after the decimal point. :param unsigned: a boolean, optional. :param zerofill: Optional. If true, values will be stored as strings left-padded with zeros. Note that this does not effect the values returned by the underlying database API, which continue to be numeric. r8 Nr9 r$ r r r r � s ��zFLOAT.__init__c C s d S r r )r �dialectr r r �bind_processor� s zFLOAT.bind_processor)NNF)r r r r r; r r? r r r r r r= � s r= c s& e Zd ZdZd Zd� fdd� Z� ZS )�INTEGERzMySQL INTEGER type.Nc s t � jf d|i|�� dS )a� Construct an INTEGER. :param display_width: Optional, maximum display width for this number. :param unsigned: a boolean, optional. :param zerofill: Optional. If true, values will be stored as strings left-padded with zeros. Note that this does not effect the values returned by the underlying database API, which continue to be numeric. r( Nr9 r) r r r r s zINTEGER.__init__)Nr: r r r r r@ � s r@ c s& e Zd ZdZd Zd� fdd� Z� ZS )�BIGINTzMySQL BIGINTEGER type.Nc s t � jf d|i|�� dS )a� Construct a BIGINTEGER. :param display_width: Optional, maximum display width for this number. :param unsigned: a boolean, optional. :param zerofill: Optional. If true, values will be stored as strings left-padded with zeros. Note that this does not effect the values returned by the underlying database API, which continue to be numeric. r( Nr9 r) r r r r s zBIGINT.__init__)Nr: r r r r rA s rA c s& e Zd ZdZd Zd� fdd� Z� ZS )� MEDIUMINTzMySQL MEDIUMINTEGER type.Nc s t � jf d|i|�� dS )a� Construct a MEDIUMINTEGER :param display_width: Optional, maximum display width for this number. :param unsigned: a boolean, optional. :param zerofill: Optional. If true, values will be stored as strings left-padded with zeros. Note that this does not effect the values returned by the underlying database API, which continue to be numeric. r( Nr9 r) r r r r + s zMEDIUMINT.__init__)Nr: r r r r rB & s rB c s& e Zd ZdZd Zd� fdd� Z� ZS )�TINYINTzMySQL TINYINT type.Nc s t � jf d|i|�� dS )a� Construct a TINYINT. :param display_width: Optional, maximum display width for this number. :param unsigned: a boolean, optional. :param zerofill: Optional. If true, values will be stored as strings left-padded with zeros. Note that this does not effect the values returned by the underlying database API, which continue to be numeric. r( Nr9 r) r r r r @ s zTINYINT.__init__)Nr: r r r r rC ; s rC c s& e Zd ZdZd Zd� fdd� Z� ZS )�SMALLINTzMySQL SMALLINTEGER type.Nc s t � jf d|i|�� dS )a� Construct a SMALLINTEGER. :param display_width: Optional, maximum display width for this number. :param unsigned: a boolean, optional. :param zerofill: Optional. If true, values will be stored as strings left-padded with zeros. Note that this does not effect the values returned by the underlying database API, which continue to be numeric. r( Nr9 r) r r r r U s zSMALLINT.__init__)Nr: r r r r rD P s rD c @ s& e Zd ZdZd Zddd�Zdd� ZdS )�BITz�MySQL BIT type. This type is for MySQL 5.0.3 or greater for MyISAM, and 5.0.5 or greater for MyISAM, MEMORY, InnoDB and BDB. For older versions, use a MSTinyInteger() type. Nc C s || _ dS )zLConstruct a BIT. :param length: Optional, number of bits. N��length)r rG r r r r p s z BIT.__init__c C s |j r dS dd� }|S )zJConvert a MySQL's 64 bit, variable length binary string to a long.Nc S s< | d ur8d}| D ]"}t |t�s&t|�}|d> |B }q|S | S )Nr � )r �int�ord)�value�v�ir r r �process s z%BIT.result_processor.<locals>.process)Zsupports_native_bit�r r> ZcoltyperN r r r �result_processorx s zBIT.result_processor)N)r r r r r; r rP r r r r rE e s rE c s. e Zd ZdZd Zd� fdd� Zdd� Z� ZS ) �TIMEzMySQL TIME type.FNc s t � j|d� || _dS )a� Construct a MySQL TIME type. :param timezone: not used by the MySQL dialect. :param fsp: fractional seconds precision value. MySQL 5.6 supports storage of fractional seconds; this parameter will be used when emitting DDL for the TIME type. .. note:: DBAPI driver support for fractional seconds may be limited; current support includes MySQL Connector/Python. ��timezoneN�r r �fsp�r rS rU r r r r � s z TIME.__init__c s t j� � fdd�}|S )Nc sD | d ur<| j }| j}|d }� |d |d ||d |d�S d S d S )N�< )� microsecond)� microseconds�seconds)rK rY rZ �minutes��timer r rN � s �z&TIME.result_processor.<locals>.process)�datetimer] rO r r\ r rP � s zTIME.result_processor)FN)r r r r r; r rP r r r r r rQ � s rQ c s& e Zd ZdZd Zd� fdd� Z� ZS )� TIMESTAMPzMySQL TIMESTAMP type.FNc s t � j|d� || _dS )a� Construct a MySQL TIMESTAMP type. :param timezone: not used by the MySQL dialect. :param fsp: fractional seconds precision value. MySQL 5.6.4 supports storage of fractional seconds; this parameter will be used when emitting DDL for the TIMESTAMP type. .. note:: DBAPI driver support for fractional seconds may be limited; current support includes MySQL Connector/Python. rR NrT rV r r r r � s zTIMESTAMP.__init__)FNr: r r r r r_ � s r_ c s& e Zd ZdZd Zd� fdd� Z� ZS )�DATETIMEzMySQL DATETIME type.FNc s t � j|d� || _dS )a� Construct a MySQL DATETIME type. :param timezone: not used by the MySQL dialect. :param fsp: fractional seconds precision value. MySQL 5.6.4 supports storage of fractional seconds; this parameter will be used when emitting DDL for the DATETIME type. .. note:: DBAPI driver support for fractional seconds may be limited; current support includes MySQL Connector/Python. rR NrT rV r r r r � s zDATETIME.__init__)FNr: r r r r r` � s r` c @ s e Zd ZdZd Zddd�ZdS )�YEARz<MySQL YEAR type, for single byte storage of years 1901-2155.Nc C s || _ d S r )r( )r r( r r r r � s z YEAR.__init__)N)r r r r r; r r r r r ra � s ra c s& e Zd ZdZd Zd� fdd� Z� ZS )�TEXTz@MySQL TEXT type, for character storage encoded up to 2^16 bytes.Nc s t � jf d|i|�� dS )al Construct a TEXT. :param length: Optional, if provided the server may optimize storage by substituting the smallest TEXT type sufficient to store ``length`` bytes of characters. :param charset: Optional, a column-level character set for this string value. Takes precedence to 'ascii' or 'unicode' short-hand. :param collation: Optional, a column-level collation for this string value. Takes precedence to 'binary' short-hand. :param ascii: Defaults to False: short-hand for the ``latin1`` character set, generates ASCII in schema. :param unicode: Defaults to False: short-hand for the ``ucs2`` character set, generates UNICODE in schema. :param national: Optional. If true, use the server's configured national character set. :param binary: Defaults to False: short-hand, pick the binary collation type that matches the column's character set. Generates BINARY in schema. This does not affect the type of data stored, only the collation of character data. rG Nr9 )r rG r r r r r � s z TEXT.__init__)Nr: r r r r rb � s rb c s$ e Zd ZdZd Z� fdd�Z� ZS )�TINYTEXTzCMySQL TINYTEXT type, for character storage encoded up to 2^8 bytes.c s t � jf i |�� dS )a� Construct a TINYTEXT. :param charset: Optional, a column-level character set for this string value. Takes precedence to 'ascii' or 'unicode' short-hand. :param collation: Optional, a column-level collation for this string value. Takes precedence to 'binary' short-hand. :param ascii: Defaults to False: short-hand for the ``latin1`` character set, generates ASCII in schema. :param unicode: Defaults to False: short-hand for the ``ucs2`` character set, generates UNICODE in schema. :param national: Optional. If true, use the server's configured national character set. :param binary: Defaults to False: short-hand, pick the binary collation type that matches the column's character set. Generates BINARY in schema. This does not affect the type of data stored, only the collation of character data. Nr9 �r �kwargsr r r r s zTINYTEXT.__init__r: r r r r rc s rc c s$ e Zd ZdZd Z� fdd�Z� ZS )� MEDIUMTEXTzJMySQL MEDIUMTEXT type, for character storage encoded up to 2^24 bytes.c s t � jf i |�� dS )a� Construct a MEDIUMTEXT. :param charset: Optional, a column-level character set for this string value. Takes precedence to 'ascii' or 'unicode' short-hand. :param collation: Optional, a column-level collation for this string value. Takes precedence to 'binary' short-hand. :param ascii: Defaults to False: short-hand for the ``latin1`` character set, generates ASCII in schema. :param unicode: Defaults to False: short-hand for the ``ucs2`` character set, generates UNICODE in schema. :param national: Optional. If true, use the server's configured national character set. :param binary: Defaults to False: short-hand, pick the binary collation type that matches the column's character set. Generates BINARY in schema. This does not affect the type of data stored, only the collation of character data. Nr9 rd r r r r > s zMEDIUMTEXT.__init__r: r r r r rf 8 s rf c s$ e Zd ZdZd Z� fdd�Z� ZS )�LONGTEXTzDMySQL LONGTEXT type, for character storage encoded up to 2^32 bytes.c s t � jf i |�� dS )a� Construct a LONGTEXT. :param charset: Optional, a column-level character set for this string value. Takes precedence to 'ascii' or 'unicode' short-hand. :param collation: Optional, a column-level collation for this string value. Takes precedence to 'binary' short-hand. :param ascii: Defaults to False: short-hand for the ``latin1`` character set, generates ASCII in schema. :param unicode: Defaults to False: short-hand for the ``ucs2`` character set, generates UNICODE in schema. :param national: Optional. If true, use the server's configured national character set. :param binary: Defaults to False: short-hand, pick the binary collation type that matches the column's character set. Generates BINARY in schema. This does not affect the type of data stored, only the collation of character data. Nr9 rd r r r r ^ s zLONGTEXT.__init__r: r r r r rg Y s rg c s& e Zd ZdZd Zd� fdd� Z� ZS )�VARCHARz7MySQL VARCHAR type, for variable-length character data.Nc s t � jf d|i|�� dS )a� Construct a VARCHAR. :param charset: Optional, a column-level character set for this string value. Takes precedence to 'ascii' or 'unicode' short-hand. :param collation: Optional, a column-level collation for this string value. Takes precedence to 'binary' short-hand. :param ascii: Defaults to False: short-hand for the ``latin1`` character set, generates ASCII in schema. :param unicode: Defaults to False: short-hand for the ``ucs2`` character set, generates UNICODE in schema. :param national: Optional. If true, use the server's configured national character set. :param binary: Defaults to False: short-hand, pick the binary collation type that matches the column's character set. Generates BINARY in schema. This does not affect the type of data stored, only the collation of character data. rG Nr9 �r rG re r r r r ~ s zVARCHAR.__init__)Nr: r r r r rh y s rh c s2 e Zd ZdZd Zd� fdd� Zedd� �Z� ZS )�CHARz1MySQL CHAR type, for fixed-length character data.Nc s t � jf d|i|�� dS )a� Construct a CHAR. :param length: Maximum data length, in characters. :param binary: Optional, use the default binary collation for the national character set. This does not affect the type of data stored, use a BINARY type for binary data. :param collation: Optional, request a particular collation. Must be compatible with the national character set. rG Nr9 ri r r r r � s z CHAR.__init__c C sV t �|�}t|t j�r|S t|t�rFt|j|j|j|j|j |j dd�S t|jd�S d S )NF)rG r- r, r0 r2 r1 r3 rF ) r Z to_instancer rj r+ rG r- r, r0 r2 r1 )�cls�type_r r r �_adapt_string_for_cast� s � zCHAR._adapt_string_for_cast)N) r r r r r; r � classmethodrm r r r r r rj � s rj c s& e Zd ZdZd Zd� fdd� Z� ZS )�NVARCHARzxMySQL NVARCHAR type. For variable-length character data in the server's configured national character set. Nc s" d|d< t � jf d|i|�� dS )a� Construct an NVARCHAR. :param length: Maximum data length, in characters. :param binary: Optional, use the default binary collation for the national character set. This does not affect the type of data stored, use a BINARY type for binary data. :param collation: Optional, request a particular collation. Must be compatible with the national character set. Tr3 rG Nr9 ri r r r r � s zNVARCHAR.__init__)Nr: r r r r ro � s ro c s& e Zd ZdZd Zd� fdd� Z� ZS )�NCHARzrMySQL NCHAR type. For fixed-length character data in the server's configured national character set. Nc s" d|d< t � jf d|i|�� dS )a� Construct an NCHAR. :param length: Maximum data length, in characters. :param binary: Optional, use the default binary collation for the national character set. This does not affect the type of data stored, use a BINARY type for binary data. :param collation: Optional, request a particular collation. Must be compatible with the national character set. Tr3 rG Nr9 ri r r r r � s zNCHAR.__init__)Nr: r r r r rp � s rp c @ s e Zd ZdZd ZdS )�TINYBLOBz5MySQL TINYBLOB type, for binary data up to 2^8 bytes.N�r r r r r; r r r r rq � s rq c @ s e Zd ZdZd ZdS )� MEDIUMBLOBz8MySQL MEDIUMBLOB type, for binary data up to 2^24 bytes.Nrr r r r r rs � s rs c @ s e Zd ZdZd ZdS )�LONGBLOBz6MySQL LONGBLOB type, for binary data up to 2^32 bytes.Nrr r r r r rt s rt )+r^ � r r Zsqlr r r% r r* r' r4 r+ r6 r5 r7 r< r! r r= r@ rA rB rC rD Z TypeEnginerE rQ r_ r` ra rb rc rf rg rh rj ro rp Z_Binaryrq rs rt r r r r �<module> sD "" '- $ ! ) sqlalchemy/dialects/mysql/expression.py 0000755 00000010031 15125143220 0014405 0 ustar 00 # dialects/mysql/expression.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors from ... import exc from ... import util from ...sql import coercions from ...sql import elements from ...sql import operators from ...sql import roles from ...sql.base import _generative from ...sql.base import Generative from ...util.typing import Self class match(Generative, elements.BinaryExpression): """Produce a ``MATCH (X, Y) AGAINST ('TEXT')`` clause. E.g.:: from sqlalchemy import desc from sqlalchemy.dialects.mysql import match match_expr = match( users_table.c.firstname, users_table.c.lastname, against="Firstname Lastname", ) stmt = ( select(users_table) .where(match_expr.in_boolean_mode()) .order_by(desc(match_expr)) ) Would produce SQL resembling: .. sourcecode:: sql SELECT id, firstname, lastname FROM user WHERE MATCH(firstname, lastname) AGAINST (:param_1 IN BOOLEAN MODE) ORDER BY MATCH(firstname, lastname) AGAINST (:param_2) DESC The :func:`_mysql.match` function is a standalone version of the :meth:`_sql.ColumnElement.match` method available on all SQL expressions, as when :meth:`_expression.ColumnElement.match` is used, but allows to pass multiple columns :param cols: column expressions to match against :param against: expression to be compared towards :param in_boolean_mode: boolean, set "boolean mode" to true :param in_natural_language_mode: boolean , set "natural language" to true :param with_query_expansion: boolean, set "query expansion" to true .. versionadded:: 1.4.19 .. seealso:: :meth:`_expression.ColumnElement.match` """ __visit_name__ = "mysql_match" inherit_cache = True def __init__(self, *cols, **kw): if not cols: raise exc.ArgumentError("columns are required") against = kw.pop("against", None) if against is None: raise exc.ArgumentError("against is required") against = coercions.expect( roles.ExpressionElementRole, against, ) left = elements.BooleanClauseList._construct_raw( operators.comma_op, clauses=cols, ) left.group = False flags = util.immutabledict( { "mysql_boolean_mode": kw.pop("in_boolean_mode", False), "mysql_natural_language": kw.pop( "in_natural_language_mode", False ), "mysql_query_expansion": kw.pop("with_query_expansion", False), } ) if kw: raise exc.ArgumentError("unknown arguments: %s" % (", ".join(kw))) super().__init__(left, against, operators.match_op, modifiers=flags) @_generative def in_boolean_mode(self) -> Self: """Apply the "IN BOOLEAN MODE" modifier to the MATCH expression. :return: a new :class:`_mysql.match` instance with modifications applied. """ self.modifiers = self.modifiers.union({"mysql_boolean_mode": True}) return self @_generative def in_natural_language_mode(self) -> Self: """Apply the "IN NATURAL LANGUAGE MODE" modifier to the MATCH expression. :return: a new :class:`_mysql.match` instance with modifications applied. """ self.modifiers = self.modifiers.union({"mysql_natural_language": True}) return self @_generative def with_query_expansion(self) -> Self: """Apply the "WITH QUERY EXPANSION" modifier to the MATCH expression. :return: a new :class:`_mysql.match` instance with modifications applied. """ self.modifiers = self.modifiers.union({"mysql_query_expansion": True}) return self sqlalchemy/dialects/mysql/reflection.py 0000755 00000054472 15125143220 0014361 0 ustar 00 # dialects/mysql/reflection.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors import re from .enumerated import ENUM from .enumerated import SET from .types import DATETIME from .types import TIME from .types import TIMESTAMP from ... import log from ... import types as sqltypes from ... import util class ReflectedState: """Stores raw information about a SHOW CREATE TABLE statement.""" def __init__(self): self.columns = [] self.table_options = {} self.table_name = None self.keys = [] self.fk_constraints = [] self.ck_constraints = [] @log.class_logger class MySQLTableDefinitionParser: """Parses the results of a SHOW CREATE TABLE statement.""" def __init__(self, dialect, preparer): self.dialect = dialect self.preparer = preparer self._prep_regexes() def parse(self, show_create, charset): state = ReflectedState() state.charset = charset for line in re.split(r"\r?\n", show_create): if line.startswith(" " + self.preparer.initial_quote): self._parse_column(line, state) # a regular table options line elif line.startswith(") "): self._parse_table_options(line, state) # an ANSI-mode table options line elif line == ")": pass elif line.startswith("CREATE "): self._parse_table_name(line, state) elif "PARTITION" in line: self._parse_partition_options(line, state) # Not present in real reflection, but may be if # loading from a file. elif not line: pass else: type_, spec = self._parse_constraints(line) if type_ is None: util.warn("Unknown schema content: %r" % line) elif type_ == "key": state.keys.append(spec) elif type_ == "fk_constraint": state.fk_constraints.append(spec) elif type_ == "ck_constraint": state.ck_constraints.append(spec) else: pass return state def _check_view(self, sql: str) -> bool: return bool(self._re_is_view.match(sql)) def _parse_constraints(self, line): """Parse a KEY or CONSTRAINT line. :param line: A line of SHOW CREATE TABLE output """ # KEY m = self._re_key.match(line) if m: spec = m.groupdict() # convert columns into name, length pairs # NOTE: we may want to consider SHOW INDEX as the # format of indexes in MySQL becomes more complex spec["columns"] = self._parse_keyexprs(spec["columns"]) if spec["version_sql"]: m2 = self._re_key_version_sql.match(spec["version_sql"]) if m2 and m2.groupdict()["parser"]: spec["parser"] = m2.groupdict()["parser"] if spec["parser"]: spec["parser"] = self.preparer.unformat_identifiers( spec["parser"] )[0] return "key", spec # FOREIGN KEY CONSTRAINT m = self._re_fk_constraint.match(line) if m: spec = m.groupdict() spec["table"] = self.preparer.unformat_identifiers(spec["table"]) spec["local"] = [c[0] for c in self._parse_keyexprs(spec["local"])] spec["foreign"] = [ c[0] for c in self._parse_keyexprs(spec["foreign"]) ] return "fk_constraint", spec # CHECK constraint m = self._re_ck_constraint.match(line) if m: spec = m.groupdict() return "ck_constraint", spec # PARTITION and SUBPARTITION m = self._re_partition.match(line) if m: # Punt! return "partition", line # No match. return (None, line) def _parse_table_name(self, line, state): """Extract the table name. :param line: The first line of SHOW CREATE TABLE """ regex, cleanup = self._pr_name m = regex.match(line) if m: state.table_name = cleanup(m.group("name")) def _parse_table_options(self, line, state): """Build a dictionary of all reflected table-level options. :param line: The final line of SHOW CREATE TABLE output. """ options = {} if line and line != ")": rest_of_line = line for regex, cleanup in self._pr_options: m = regex.search(rest_of_line) if not m: continue directive, value = m.group("directive"), m.group("val") if cleanup: value = cleanup(value) options[directive.lower()] = value rest_of_line = regex.sub("", rest_of_line) for nope in ("auto_increment", "data directory", "index directory"): options.pop(nope, None) for opt, val in options.items(): state.table_options["%s_%s" % (self.dialect.name, opt)] = val def _parse_partition_options(self, line, state): options = {} new_line = line[:] while new_line.startswith("(") or new_line.startswith(" "): new_line = new_line[1:] for regex, cleanup in self._pr_options: m = regex.search(new_line) if not m or "PARTITION" not in regex.pattern: continue directive = m.group("directive") directive = directive.lower() is_subpartition = directive == "subpartition" if directive == "partition" or is_subpartition: new_line = new_line.replace(") */", "") new_line = new_line.replace(",", "") if is_subpartition and new_line.endswith(")"): new_line = new_line[:-1] if self.dialect.name == "mariadb" and new_line.endswith(")"): if ( "MAXVALUE" in new_line or "MINVALUE" in new_line or "ENGINE" in new_line ): # final line of MariaDB partition endswith ")" new_line = new_line[:-1] defs = "%s_%s_definitions" % (self.dialect.name, directive) options[defs] = new_line else: directive = directive.replace(" ", "_") value = m.group("val") if cleanup: value = cleanup(value) options[directive] = value break for opt, val in options.items(): part_def = "%s_partition_definitions" % (self.dialect.name) subpart_def = "%s_subpartition_definitions" % (self.dialect.name) if opt == part_def or opt == subpart_def: # builds a string of definitions if opt not in state.table_options: state.table_options[opt] = val else: state.table_options[opt] = "%s, %s" % ( state.table_options[opt], val, ) else: state.table_options["%s_%s" % (self.dialect.name, opt)] = val def _parse_column(self, line, state): """Extract column details. Falls back to a 'minimal support' variant if full parse fails. :param line: Any column-bearing line from SHOW CREATE TABLE """ spec = None m = self._re_column.match(line) if m: spec = m.groupdict() spec["full"] = True else: m = self._re_column_loose.match(line) if m: spec = m.groupdict() spec["full"] = False if not spec: util.warn("Unknown column definition %r" % line) return if not spec["full"]: util.warn("Incomplete reflection of column definition %r" % line) name, type_, args = spec["name"], spec["coltype"], spec["arg"] try: col_type = self.dialect.ischema_names[type_] except KeyError: util.warn( "Did not recognize type '%s' of column '%s'" % (type_, name) ) col_type = sqltypes.NullType # Column type positional arguments eg. varchar(32) if args is None or args == "": type_args = [] elif args[0] == "'" and args[-1] == "'": type_args = self._re_csv_str.findall(args) else: type_args = [int(v) for v in self._re_csv_int.findall(args)] # Column type keyword options type_kw = {} if issubclass(col_type, (DATETIME, TIME, TIMESTAMP)): if type_args: type_kw["fsp"] = type_args.pop(0) for kw in ("unsigned", "zerofill"): if spec.get(kw, False): type_kw[kw] = True for kw in ("charset", "collate"): if spec.get(kw, False): type_kw[kw] = spec[kw] if issubclass(col_type, (ENUM, SET)): type_args = _strip_values(type_args) if issubclass(col_type, SET) and "" in type_args: type_kw["retrieve_as_bitwise"] = True type_instance = col_type(*type_args, **type_kw) col_kw = {} # NOT NULL col_kw["nullable"] = True # this can be "NULL" in the case of TIMESTAMP if spec.get("notnull", False) == "NOT NULL": col_kw["nullable"] = False # For generated columns, the nullability is marked in a different place if spec.get("notnull_generated", False) == "NOT NULL": col_kw["nullable"] = False # AUTO_INCREMENT if spec.get("autoincr", False): col_kw["autoincrement"] = True elif issubclass(col_type, sqltypes.Integer): col_kw["autoincrement"] = False # DEFAULT default = spec.get("default", None) if default == "NULL": # eliminates the need to deal with this later. default = None comment = spec.get("comment", None) if comment is not None: comment = cleanup_text(comment) sqltext = spec.get("generated") if sqltext is not None: computed = dict(sqltext=sqltext) persisted = spec.get("persistence") if persisted is not None: computed["persisted"] = persisted == "STORED" col_kw["computed"] = computed col_d = dict( name=name, type=type_instance, default=default, comment=comment ) col_d.update(col_kw) state.columns.append(col_d) def _describe_to_create(self, table_name, columns): """Re-format DESCRIBE output as a SHOW CREATE TABLE string. DESCRIBE is a much simpler reflection and is sufficient for reflecting views for runtime use. This method formats DDL for columns only- keys are omitted. :param columns: A sequence of DESCRIBE or SHOW COLUMNS 6-tuples. SHOW FULL COLUMNS FROM rows must be rearranged for use with this function. """ buffer = [] for row in columns: (name, col_type, nullable, default, extra) = ( row[i] for i in (0, 1, 2, 4, 5) ) line = [" "] line.append(self.preparer.quote_identifier(name)) line.append(col_type) if not nullable: line.append("NOT NULL") if default: if "auto_increment" in default: pass elif col_type.startswith("timestamp") and default.startswith( "C" ): line.append("DEFAULT") line.append(default) elif default == "NULL": line.append("DEFAULT") line.append(default) else: line.append("DEFAULT") line.append("'%s'" % default.replace("'", "''")) if extra: line.append(extra) buffer.append(" ".join(line)) return "".join( [ ( "CREATE TABLE %s (\n" % self.preparer.quote_identifier(table_name) ), ",\n".join(buffer), "\n) ", ] ) def _parse_keyexprs(self, identifiers): """Unpack '"col"(2),"col" ASC'-ish strings into components.""" return [ (colname, int(length) if length else None, modifiers) for colname, length, modifiers in self._re_keyexprs.findall( identifiers ) ] def _prep_regexes(self): """Pre-compile regular expressions.""" self._re_columns = [] self._pr_options = [] _final = self.preparer.final_quote quotes = dict( zip( ("iq", "fq", "esc_fq"), [ re.escape(s) for s in ( self.preparer.initial_quote, _final, self.preparer._escape_identifier(_final), ) ], ) ) self._pr_name = _pr_compile( r"^CREATE (?:\w+ +)?TABLE +" r"%(iq)s(?P<name>(?:%(esc_fq)s|[^%(fq)s])+)%(fq)s +\($" % quotes, self.preparer._unescape_identifier, ) self._re_is_view = _re_compile(r"^CREATE(?! TABLE)(\s.*)?\sVIEW") # `col`,`col2`(32),`col3`(15) DESC # self._re_keyexprs = _re_compile( r"(?:" r"(?:%(iq)s((?:%(esc_fq)s|[^%(fq)s])+)%(fq)s)" r"(?:\((\d+)\))?(?: +(ASC|DESC))?(?=\,|$))+" % quotes ) # 'foo' or 'foo','bar' or 'fo,o','ba''a''r' self._re_csv_str = _re_compile(r"\x27(?:\x27\x27|[^\x27])*\x27") # 123 or 123,456 self._re_csv_int = _re_compile(r"\d+") # `colname` <type> [type opts] # (NOT NULL | NULL) # DEFAULT ('value' | CURRENT_TIMESTAMP...) # COMMENT 'comment' # COLUMN_FORMAT (FIXED|DYNAMIC|DEFAULT) # STORAGE (DISK|MEMORY) self._re_column = _re_compile( r" " r"%(iq)s(?P<name>(?:%(esc_fq)s|[^%(fq)s])+)%(fq)s +" r"(?P<coltype>\w+)" r"(?:\((?P<arg>(?:\d+|\d+,\d+|" r"(?:'(?:''|[^'])*',?)+))\))?" r"(?: +(?P<unsigned>UNSIGNED))?" r"(?: +(?P<zerofill>ZEROFILL))?" r"(?: +CHARACTER SET +(?P<charset>[\w_]+))?" r"(?: +COLLATE +(?P<collate>[\w_]+))?" r"(?: +(?P<notnull>(?:NOT )?NULL))?" r"(?: +DEFAULT +(?P<default>" r"(?:NULL|'(?:''|[^'])*'|\(.+?\)|[\-\w\.\(\)]+" r"(?: +ON UPDATE [\-\w\.\(\)]+)?)" r"))?" r"(?: +(?:GENERATED ALWAYS)? ?AS +(?P<generated>\(" r".*\))? ?(?P<persistence>VIRTUAL|STORED)?" r"(?: +(?P<notnull_generated>(?:NOT )?NULL))?" r")?" r"(?: +(?P<autoincr>AUTO_INCREMENT))?" r"(?: +COMMENT +'(?P<comment>(?:''|[^'])*)')?" r"(?: +COLUMN_FORMAT +(?P<colfmt>\w+))?" r"(?: +STORAGE +(?P<storage>\w+))?" r"(?: +(?P<extra>.*))?" r",?$" % quotes ) # Fallback, try to parse as little as possible self._re_column_loose = _re_compile( r" " r"%(iq)s(?P<name>(?:%(esc_fq)s|[^%(fq)s])+)%(fq)s +" r"(?P<coltype>\w+)" r"(?:\((?P<arg>(?:\d+|\d+,\d+|\x27(?:\x27\x27|[^\x27])+\x27))\))?" r".*?(?P<notnull>(?:NOT )NULL)?" % quotes ) # (PRIMARY|UNIQUE|FULLTEXT|SPATIAL) INDEX `name` (USING (BTREE|HASH))? # (`col` (ASC|DESC)?, `col` (ASC|DESC)?) # KEY_BLOCK_SIZE size | WITH PARSER name /*!50100 WITH PARSER name */ self._re_key = _re_compile( r" " r"(?:(?P<type>\S+) )?KEY" r"(?: +%(iq)s(?P<name>(?:%(esc_fq)s|[^%(fq)s])+)%(fq)s)?" r"(?: +USING +(?P<using_pre>\S+))?" r" +\((?P<columns>.+?)\)" r"(?: +USING +(?P<using_post>\S+))?" r"(?: +KEY_BLOCK_SIZE *[ =]? *(?P<keyblock>\S+))?" r"(?: +WITH PARSER +(?P<parser>\S+))?" r"(?: +COMMENT +(?P<comment>(\x27\x27|\x27([^\x27])*?\x27)+))?" r"(?: +/\*(?P<version_sql>.+)\*/ *)?" r",?$" % quotes ) # https://forums.mysql.com/read.php?20,567102,567111#msg-567111 # It means if the MySQL version >= \d+, execute what's in the comment self._re_key_version_sql = _re_compile( r"\!\d+ " r"(?: *WITH PARSER +(?P<parser>\S+) *)?" ) # CONSTRAINT `name` FOREIGN KEY (`local_col`) # REFERENCES `remote` (`remote_col`) # MATCH FULL | MATCH PARTIAL | MATCH SIMPLE # ON DELETE CASCADE ON UPDATE RESTRICT # # unique constraints come back as KEYs kw = quotes.copy() kw["on"] = "RESTRICT|CASCADE|SET NULL|NO ACTION|SET DEFAULT" self._re_fk_constraint = _re_compile( r" " r"CONSTRAINT +" r"%(iq)s(?P<name>(?:%(esc_fq)s|[^%(fq)s])+)%(fq)s +" r"FOREIGN KEY +" r"\((?P<local>[^\)]+?)\) REFERENCES +" r"(?P<table>%(iq)s[^%(fq)s]+%(fq)s" r"(?:\.%(iq)s[^%(fq)s]+%(fq)s)?) +" r"\((?P<foreign>(?:%(iq)s[^%(fq)s]+%(fq)s(?: *, *)?)+)\)" r"(?: +(?P<match>MATCH \w+))?" r"(?: +ON DELETE (?P<ondelete>%(on)s))?" r"(?: +ON UPDATE (?P<onupdate>%(on)s))?" % kw ) # CONSTRAINT `CONSTRAINT_1` CHECK (`x` > 5)' # testing on MariaDB 10.2 shows that the CHECK constraint # is returned on a line by itself, so to match without worrying # about parenthesis in the expression we go to the end of the line self._re_ck_constraint = _re_compile( r" " r"CONSTRAINT +" r"%(iq)s(?P<name>(?:%(esc_fq)s|[^%(fq)s])+)%(fq)s +" r"CHECK +" r"\((?P<sqltext>.+)\),?" % kw ) # PARTITION # # punt! self._re_partition = _re_compile(r"(?:.*)(?:SUB)?PARTITION(?:.*)") # Table-level options (COLLATE, ENGINE, etc.) # Do the string options first, since they have quoted # strings we need to get rid of. for option in _options_of_type_string: self._add_option_string(option) for option in ( "ENGINE", "TYPE", "AUTO_INCREMENT", "AVG_ROW_LENGTH", "CHARACTER SET", "DEFAULT CHARSET", "CHECKSUM", "COLLATE", "DELAY_KEY_WRITE", "INSERT_METHOD", "MAX_ROWS", "MIN_ROWS", "PACK_KEYS", "ROW_FORMAT", "KEY_BLOCK_SIZE", "STATS_SAMPLE_PAGES", ): self._add_option_word(option) for option in ( "PARTITION BY", "SUBPARTITION BY", "PARTITIONS", "SUBPARTITIONS", "PARTITION", "SUBPARTITION", ): self._add_partition_option_word(option) self._add_option_regex("UNION", r"\([^\)]+\)") self._add_option_regex("TABLESPACE", r".*? STORAGE DISK") self._add_option_regex( "RAID_TYPE", r"\w+\s+RAID_CHUNKS\s*\=\s*\w+RAID_CHUNKSIZE\s*=\s*\w+", ) _optional_equals = r"(?:\s*(?:=\s*)|\s+)" def _add_option_string(self, directive): regex = r"(?P<directive>%s)%s" r"'(?P<val>(?:[^']|'')*?)'(?!')" % ( re.escape(directive), self._optional_equals, ) self._pr_options.append(_pr_compile(regex, cleanup_text)) def _add_option_word(self, directive): regex = r"(?P<directive>%s)%s" r"(?P<val>\w+)" % ( re.escape(directive), self._optional_equals, ) self._pr_options.append(_pr_compile(regex)) def _add_partition_option_word(self, directive): if directive == "PARTITION BY" or directive == "SUBPARTITION BY": regex = r"(?<!\S)(?P<directive>%s)%s" r"(?P<val>\w+.*)" % ( re.escape(directive), self._optional_equals, ) elif directive == "SUBPARTITIONS" or directive == "PARTITIONS": regex = r"(?<!\S)(?P<directive>%s)%s" r"(?P<val>\d+)" % ( re.escape(directive), self._optional_equals, ) else: regex = r"(?<!\S)(?P<directive>%s)(?!\S)" % (re.escape(directive),) self._pr_options.append(_pr_compile(regex)) def _add_option_regex(self, directive, regex): regex = r"(?P<directive>%s)%s" r"(?P<val>%s)" % ( re.escape(directive), self._optional_equals, regex, ) self._pr_options.append(_pr_compile(regex)) _options_of_type_string = ( "COMMENT", "DATA DIRECTORY", "INDEX DIRECTORY", "PASSWORD", "CONNECTION", ) def _pr_compile(regex, cleanup=None): """Prepare a 2-tuple of compiled regex and callable.""" return (_re_compile(regex), cleanup) def _re_compile(regex): """Compile a string to regex, I and UNICODE.""" return re.compile(regex, re.I | re.UNICODE) def _strip_values(values): "Strip reflected values quotes" strip_values = [] for a in values: if a[0:1] == '"' or a[0:1] == "'": # strip enclosing quotes and unquote interior a = a[1:-1].replace(a[0] * 2, a[0]) strip_values.append(a) return strip_values def cleanup_text(raw_text: str) -> str: if "\\" in raw_text: raw_text = re.sub( _control_char_regexp, lambda s: _control_char_map[s[0]], raw_text ) return raw_text.replace("''", "'") _control_char_map = { "\\\\": "\\", "\\0": "\0", "\\a": "\a", "\\b": "\b", "\\t": "\t", "\\n": "\n", "\\v": "\v", "\\f": "\f", "\\r": "\r", # '\\e':'\e', } _control_char_regexp = re.compile( "|".join(re.escape(k) for k in _control_char_map) ) sqlalchemy/dialects/mysql/base.py 0000755 00000363550 15125143220 0013141 0 ustar 00 # dialects/mysql/base.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors r""" .. dialect:: mysql :name: MySQL / MariaDB :normal_support: 5.6+ / 10+ :best_effort: 5.0.2+ / 5.0.2+ Supported Versions and Features ------------------------------- SQLAlchemy supports MySQL starting with version 5.0.2 through modern releases, as well as all modern versions of MariaDB. See the official MySQL documentation for detailed information about features supported in any given server release. .. versionchanged:: 1.4 minimum MySQL version supported is now 5.0.2. MariaDB Support ~~~~~~~~~~~~~~~ The MariaDB variant of MySQL retains fundamental compatibility with MySQL's protocols however the development of these two products continues to diverge. Within the realm of SQLAlchemy, the two databases have a small number of syntactical and behavioral differences that SQLAlchemy accommodates automatically. To connect to a MariaDB database, no changes to the database URL are required:: engine = create_engine( "mysql+pymysql://user:pass@some_mariadb/dbname?charset=utf8mb4" ) Upon first connect, the SQLAlchemy dialect employs a server version detection scheme that determines if the backing database reports as MariaDB. Based on this flag, the dialect can make different choices in those of areas where its behavior must be different. .. _mysql_mariadb_only_mode: MariaDB-Only Mode ~~~~~~~~~~~~~~~~~ The dialect also supports an **optional** "MariaDB-only" mode of connection, which may be useful for the case where an application makes use of MariaDB-specific features and is not compatible with a MySQL database. To use this mode of operation, replace the "mysql" token in the above URL with "mariadb":: engine = create_engine( "mariadb+pymysql://user:pass@some_mariadb/dbname?charset=utf8mb4" ) The above engine, upon first connect, will raise an error if the server version detection detects that the backing database is not MariaDB. When using an engine with ``"mariadb"`` as the dialect name, **all mysql-specific options that include the name "mysql" in them are now named with "mariadb"**. This means options like ``mysql_engine`` should be named ``mariadb_engine``, etc. Both "mysql" and "mariadb" options can be used simultaneously for applications that use URLs with both "mysql" and "mariadb" dialects:: my_table = Table( "mytable", metadata, Column("id", Integer, primary_key=True), Column("textdata", String(50)), mariadb_engine="InnoDB", mysql_engine="InnoDB", ) Index( "textdata_ix", my_table.c.textdata, mysql_prefix="FULLTEXT", mariadb_prefix="FULLTEXT", ) Similar behavior will occur when the above structures are reflected, i.e. the "mariadb" prefix will be present in the option names when the database URL is based on the "mariadb" name. .. versionadded:: 1.4 Added "mariadb" dialect name supporting "MariaDB-only mode" for the MySQL dialect. .. _mysql_connection_timeouts: Connection Timeouts and Disconnects ----------------------------------- MySQL / MariaDB feature an automatic connection close behavior, for connections that have been idle for a fixed period of time, defaulting to eight hours. To circumvent having this issue, use the :paramref:`_sa.create_engine.pool_recycle` option which ensures that a connection will be discarded and replaced with a new one if it has been present in the pool for a fixed number of seconds:: engine = create_engine("mysql+mysqldb://...", pool_recycle=3600) For more comprehensive disconnect detection of pooled connections, including accommodation of server restarts and network issues, a pre-ping approach may be employed. See :ref:`pool_disconnects` for current approaches. .. seealso:: :ref:`pool_disconnects` - Background on several techniques for dealing with timed out connections as well as database restarts. .. _mysql_storage_engines: CREATE TABLE arguments including Storage Engines ------------------------------------------------ Both MySQL's and MariaDB's CREATE TABLE syntax includes a wide array of special options, including ``ENGINE``, ``CHARSET``, ``MAX_ROWS``, ``ROW_FORMAT``, ``INSERT_METHOD``, and many more. To accommodate the rendering of these arguments, specify the form ``mysql_argument_name="value"``. For example, to specify a table with ``ENGINE`` of ``InnoDB``, ``CHARSET`` of ``utf8mb4``, and ``KEY_BLOCK_SIZE`` of ``1024``:: Table( "mytable", metadata, Column("data", String(32)), mysql_engine="InnoDB", mysql_charset="utf8mb4", mysql_key_block_size="1024", ) When supporting :ref:`mysql_mariadb_only_mode` mode, similar keys against the "mariadb" prefix must be included as well. The values can of course vary independently so that different settings on MySQL vs. MariaDB may be maintained:: # support both "mysql" and "mariadb-only" engine URLs Table( "mytable", metadata, Column("data", String(32)), mysql_engine="InnoDB", mariadb_engine="InnoDB", mysql_charset="utf8mb4", mariadb_charset="utf8", mysql_key_block_size="1024", mariadb_key_block_size="1024", ) The MySQL / MariaDB dialects will normally transfer any keyword specified as ``mysql_keyword_name`` to be rendered as ``KEYWORD_NAME`` in the ``CREATE TABLE`` statement. A handful of these names will render with a space instead of an underscore; to support this, the MySQL dialect has awareness of these particular names, which include ``DATA DIRECTORY`` (e.g. ``mysql_data_directory``), ``CHARACTER SET`` (e.g. ``mysql_character_set``) and ``INDEX DIRECTORY`` (e.g. ``mysql_index_directory``). The most common argument is ``mysql_engine``, which refers to the storage engine for the table. Historically, MySQL server installations would default to ``MyISAM`` for this value, although newer versions may be defaulting to ``InnoDB``. The ``InnoDB`` engine is typically preferred for its support of transactions and foreign keys. A :class:`_schema.Table` that is created in a MySQL / MariaDB database with a storage engine of ``MyISAM`` will be essentially non-transactional, meaning any INSERT/UPDATE/DELETE statement referring to this table will be invoked as autocommit. It also will have no support for foreign key constraints; while the ``CREATE TABLE`` statement accepts foreign key options, when using the ``MyISAM`` storage engine these arguments are discarded. Reflecting such a table will also produce no foreign key constraint information. For fully atomic transactions as well as support for foreign key constraints, all participating ``CREATE TABLE`` statements must specify a transactional engine, which in the vast majority of cases is ``InnoDB``. Partitioning can similarly be specified using similar options. In the example below the create table will specify ``PARTITION_BY``, ``PARTITIONS``, ``SUBPARTITIONS`` and ``SUBPARTITION_BY``:: # can also use mariadb_* prefix Table( "testtable", MetaData(), Column("id", Integer(), primary_key=True, autoincrement=True), Column("other_id", Integer(), primary_key=True, autoincrement=False), mysql_partitions="2", mysql_partition_by="KEY(other_id)", mysql_subpartition_by="HASH(some_expr)", mysql_subpartitions="2", ) This will render: .. sourcecode:: sql CREATE TABLE testtable ( id INTEGER NOT NULL AUTO_INCREMENT, other_id INTEGER NOT NULL, PRIMARY KEY (id, other_id) )PARTITION BY KEY(other_id) PARTITIONS 2 SUBPARTITION BY HASH(some_expr) SUBPARTITIONS 2 Case Sensitivity and Table Reflection ------------------------------------- Both MySQL and MariaDB have inconsistent support for case-sensitive identifier names, basing support on specific details of the underlying operating system. However, it has been observed that no matter what case sensitivity behavior is present, the names of tables in foreign key declarations are *always* received from the database as all-lower case, making it impossible to accurately reflect a schema where inter-related tables use mixed-case identifier names. Therefore it is strongly advised that table names be declared as all lower case both within SQLAlchemy as well as on the MySQL / MariaDB database itself, especially if database reflection features are to be used. .. _mysql_isolation_level: Transaction Isolation Level --------------------------- All MySQL / MariaDB dialects support setting of transaction isolation level both via a dialect-specific parameter :paramref:`_sa.create_engine.isolation_level` accepted by :func:`_sa.create_engine`, as well as the :paramref:`.Connection.execution_options.isolation_level` argument as passed to :meth:`_engine.Connection.execution_options`. This feature works by issuing the command ``SET SESSION TRANSACTION ISOLATION LEVEL <level>`` for each new connection. For the special AUTOCOMMIT isolation level, DBAPI-specific techniques are used. To set isolation level using :func:`_sa.create_engine`:: engine = create_engine( "mysql+mysqldb://scott:tiger@localhost/test", isolation_level="READ UNCOMMITTED", ) To set using per-connection execution options:: connection = engine.connect() connection = connection.execution_options(isolation_level="READ COMMITTED") Valid values for ``isolation_level`` include: * ``READ COMMITTED`` * ``READ UNCOMMITTED`` * ``REPEATABLE READ`` * ``SERIALIZABLE`` * ``AUTOCOMMIT`` The special ``AUTOCOMMIT`` value makes use of the various "autocommit" attributes provided by specific DBAPIs, and is currently supported by MySQLdb, MySQL-Client, MySQL-Connector Python, and PyMySQL. Using it, the database connection will return true for the value of ``SELECT @@autocommit;``. There are also more options for isolation level configurations, such as "sub-engine" objects linked to a main :class:`_engine.Engine` which each apply different isolation level settings. See the discussion at :ref:`dbapi_autocommit` for background. .. seealso:: :ref:`dbapi_autocommit` AUTO_INCREMENT Behavior ----------------------- When creating tables, SQLAlchemy will automatically set ``AUTO_INCREMENT`` on the first :class:`.Integer` primary key column which is not marked as a foreign key:: >>> t = Table( ... "mytable", metadata, Column("mytable_id", Integer, primary_key=True) ... ) >>> t.create() CREATE TABLE mytable ( id INTEGER NOT NULL AUTO_INCREMENT, PRIMARY KEY (id) ) You can disable this behavior by passing ``False`` to the :paramref:`_schema.Column.autoincrement` argument of :class:`_schema.Column`. This flag can also be used to enable auto-increment on a secondary column in a multi-column key for some storage engines:: Table( "mytable", metadata, Column("gid", Integer, primary_key=True, autoincrement=False), Column("id", Integer, primary_key=True), ) .. _mysql_ss_cursors: Server Side Cursors ------------------- Server-side cursor support is available for the mysqlclient, PyMySQL, mariadbconnector dialects and may also be available in others. This makes use of either the "buffered=True/False" flag if available or by using a class such as ``MySQLdb.cursors.SSCursor`` or ``pymysql.cursors.SSCursor`` internally. Server side cursors are enabled on a per-statement basis by using the :paramref:`.Connection.execution_options.stream_results` connection execution option:: with engine.connect() as conn: result = conn.execution_options(stream_results=True).execute( text("select * from table") ) Note that some kinds of SQL statements may not be supported with server side cursors; generally, only SQL statements that return rows should be used with this option. .. deprecated:: 1.4 The dialect-level server_side_cursors flag is deprecated and will be removed in a future release. Please use the :paramref:`_engine.Connection.stream_results` execution option for unbuffered cursor support. .. seealso:: :ref:`engine_stream_results` .. _mysql_unicode: Unicode ------- Charset Selection ~~~~~~~~~~~~~~~~~ Most MySQL / MariaDB DBAPIs offer the option to set the client character set for a connection. This is typically delivered using the ``charset`` parameter in the URL, such as:: e = create_engine( "mysql+pymysql://scott:tiger@localhost/test?charset=utf8mb4" ) This charset is the **client character set** for the connection. Some MySQL DBAPIs will default this to a value such as ``latin1``, and some will make use of the ``default-character-set`` setting in the ``my.cnf`` file as well. Documentation for the DBAPI in use should be consulted for specific behavior. The encoding used for Unicode has traditionally been ``'utf8'``. However, for MySQL versions 5.5.3 and MariaDB 5.5 on forward, a new MySQL-specific encoding ``'utf8mb4'`` has been introduced, and as of MySQL 8.0 a warning is emitted by the server if plain ``utf8`` is specified within any server-side directives, replaced with ``utf8mb3``. The rationale for this new encoding is due to the fact that MySQL's legacy utf-8 encoding only supports codepoints up to three bytes instead of four. Therefore, when communicating with a MySQL or MariaDB database that includes codepoints more than three bytes in size, this new charset is preferred, if supported by both the database as well as the client DBAPI, as in:: e = create_engine( "mysql+pymysql://scott:tiger@localhost/test?charset=utf8mb4" ) All modern DBAPIs should support the ``utf8mb4`` charset. In order to use ``utf8mb4`` encoding for a schema that was created with legacy ``utf8``, changes to the MySQL/MariaDB schema and/or server configuration may be required. .. seealso:: `The utf8mb4 Character Set \ <https://dev.mysql.com/doc/refman/5.5/en/charset-unicode-utf8mb4.html>`_ - \ in the MySQL documentation .. _mysql_binary_introducer: Dealing with Binary Data Warnings and Unicode ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ MySQL versions 5.6, 5.7 and later (not MariaDB at the time of this writing) now emit a warning when attempting to pass binary data to the database, while a character set encoding is also in place, when the binary data itself is not valid for that encoding: .. sourcecode:: text default.py:509: Warning: (1300, "Invalid utf8mb4 character string: 'F9876A'") cursor.execute(statement, parameters) This warning is due to the fact that the MySQL client library is attempting to interpret the binary string as a unicode object even if a datatype such as :class:`.LargeBinary` is in use. To resolve this, the SQL statement requires a binary "character set introducer" be present before any non-NULL value that renders like this: .. sourcecode:: sql INSERT INTO table (data) VALUES (_binary %s) These character set introducers are provided by the DBAPI driver, assuming the use of mysqlclient or PyMySQL (both of which are recommended). Add the query string parameter ``binary_prefix=true`` to the URL to repair this warning:: # mysqlclient engine = create_engine( "mysql+mysqldb://scott:tiger@localhost/test?charset=utf8mb4&binary_prefix=true" ) # PyMySQL engine = create_engine( "mysql+pymysql://scott:tiger@localhost/test?charset=utf8mb4&binary_prefix=true" ) The ``binary_prefix`` flag may or may not be supported by other MySQL drivers. SQLAlchemy itself cannot render this ``_binary`` prefix reliably, as it does not work with the NULL value, which is valid to be sent as a bound parameter. As the MySQL driver renders parameters directly into the SQL string, it's the most efficient place for this additional keyword to be passed. .. seealso:: `Character set introducers <https://dev.mysql.com/doc/refman/5.7/en/charset-introducer.html>`_ - on the MySQL website ANSI Quoting Style ------------------ MySQL / MariaDB feature two varieties of identifier "quoting style", one using backticks and the other using quotes, e.g. ```some_identifier``` vs. ``"some_identifier"``. All MySQL dialects detect which version is in use by checking the value of :ref:`sql_mode<mysql_sql_mode>` when a connection is first established with a particular :class:`_engine.Engine`. This quoting style comes into play when rendering table and column names as well as when reflecting existing database structures. The detection is entirely automatic and no special configuration is needed to use either quoting style. .. _mysql_sql_mode: Changing the sql_mode --------------------- MySQL supports operating in multiple `Server SQL Modes <https://dev.mysql.com/doc/refman/8.0/en/sql-mode.html>`_ for both Servers and Clients. To change the ``sql_mode`` for a given application, a developer can leverage SQLAlchemy's Events system. In the following example, the event system is used to set the ``sql_mode`` on the ``first_connect`` and ``connect`` events:: from sqlalchemy import create_engine, event eng = create_engine( "mysql+mysqldb://scott:tiger@localhost/test", echo="debug" ) # `insert=True` will ensure this is the very first listener to run @event.listens_for(eng, "connect", insert=True) def connect(dbapi_connection, connection_record): cursor = dbapi_connection.cursor() cursor.execute("SET sql_mode = 'STRICT_ALL_TABLES'") conn = eng.connect() In the example illustrated above, the "connect" event will invoke the "SET" statement on the connection at the moment a particular DBAPI connection is first created for a given Pool, before the connection is made available to the connection pool. Additionally, because the function was registered with ``insert=True``, it will be prepended to the internal list of registered functions. MySQL / MariaDB SQL Extensions ------------------------------ Many of the MySQL / MariaDB SQL extensions are handled through SQLAlchemy's generic function and operator support:: table.select(table.c.password == func.md5("plaintext")) table.select(table.c.username.op("regexp")("^[a-d]")) And of course any valid SQL statement can be executed as a string as well. Some limited direct support for MySQL / MariaDB extensions to SQL is currently available. * INSERT..ON DUPLICATE KEY UPDATE: See :ref:`mysql_insert_on_duplicate_key_update` * SELECT pragma, use :meth:`_expression.Select.prefix_with` and :meth:`_query.Query.prefix_with`:: select(...).prefix_with(["HIGH_PRIORITY", "SQL_SMALL_RESULT"]) * UPDATE with LIMIT:: update(...).with_dialect_options(mysql_limit=10, mariadb_limit=10) * DELETE with LIMIT:: delete(...).with_dialect_options(mysql_limit=10, mariadb_limit=10) .. versionadded:: 2.0.37 Added delete with limit * optimizer hints, use :meth:`_expression.Select.prefix_with` and :meth:`_query.Query.prefix_with`:: select(...).prefix_with("/*+ NO_RANGE_OPTIMIZATION(t4 PRIMARY) */") * index hints, use :meth:`_expression.Select.with_hint` and :meth:`_query.Query.with_hint`:: select(...).with_hint(some_table, "USE INDEX xyz") * MATCH operator support:: from sqlalchemy.dialects.mysql import match select(...).where(match(col1, col2, against="some expr").in_boolean_mode()) .. seealso:: :class:`_mysql.match` INSERT/DELETE...RETURNING ------------------------- The MariaDB dialect supports 10.5+'s ``INSERT..RETURNING`` and ``DELETE..RETURNING`` (10.0+) syntaxes. ``INSERT..RETURNING`` may be used automatically in some cases in order to fetch newly generated identifiers in place of the traditional approach of using ``cursor.lastrowid``, however ``cursor.lastrowid`` is currently still preferred for simple single-statement cases for its better performance. To specify an explicit ``RETURNING`` clause, use the :meth:`._UpdateBase.returning` method on a per-statement basis:: # INSERT..RETURNING result = connection.execute( table.insert().values(name="foo").returning(table.c.col1, table.c.col2) ) print(result.all()) # DELETE..RETURNING result = connection.execute( table.delete() .where(table.c.name == "foo") .returning(table.c.col1, table.c.col2) ) print(result.all()) .. versionadded:: 2.0 Added support for MariaDB RETURNING .. _mysql_insert_on_duplicate_key_update: INSERT...ON DUPLICATE KEY UPDATE (Upsert) ------------------------------------------ MySQL / MariaDB allow "upserts" (update or insert) of rows into a table via the ``ON DUPLICATE KEY UPDATE`` clause of the ``INSERT`` statement. A candidate row will only be inserted if that row does not match an existing primary or unique key in the table; otherwise, an UPDATE will be performed. The statement allows for separate specification of the values to INSERT versus the values for UPDATE. SQLAlchemy provides ``ON DUPLICATE KEY UPDATE`` support via the MySQL-specific :func:`.mysql.insert()` function, which provides the generative method :meth:`~.mysql.Insert.on_duplicate_key_update`: .. sourcecode:: pycon+sql >>> from sqlalchemy.dialects.mysql import insert >>> insert_stmt = insert(my_table).values( ... id="some_existing_id", data="inserted value" ... ) >>> on_duplicate_key_stmt = insert_stmt.on_duplicate_key_update( ... data=insert_stmt.inserted.data, status="U" ... ) >>> print(on_duplicate_key_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (%s, %s) ON DUPLICATE KEY UPDATE data = VALUES(data), status = %s Unlike PostgreSQL's "ON CONFLICT" phrase, the "ON DUPLICATE KEY UPDATE" phrase will always match on any primary key or unique key, and will always perform an UPDATE if there's a match; there are no options for it to raise an error or to skip performing an UPDATE. ``ON DUPLICATE KEY UPDATE`` is used to perform an update of the already existing row, using any combination of new values as well as values from the proposed insertion. These values are normally specified using keyword arguments passed to the :meth:`_mysql.Insert.on_duplicate_key_update` given column key values (usually the name of the column, unless it specifies :paramref:`_schema.Column.key` ) as keys and literal or SQL expressions as values: .. sourcecode:: pycon+sql >>> insert_stmt = insert(my_table).values( ... id="some_existing_id", data="inserted value" ... ) >>> on_duplicate_key_stmt = insert_stmt.on_duplicate_key_update( ... data="some data", ... updated_at=func.current_timestamp(), ... ) >>> print(on_duplicate_key_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (%s, %s) ON DUPLICATE KEY UPDATE data = %s, updated_at = CURRENT_TIMESTAMP In a manner similar to that of :meth:`.UpdateBase.values`, other parameter forms are accepted, including a single dictionary: .. sourcecode:: pycon+sql >>> on_duplicate_key_stmt = insert_stmt.on_duplicate_key_update( ... {"data": "some data", "updated_at": func.current_timestamp()}, ... ) as well as a list of 2-tuples, which will automatically provide a parameter-ordered UPDATE statement in a manner similar to that described at :ref:`tutorial_parameter_ordered_updates`. Unlike the :class:`_expression.Update` object, no special flag is needed to specify the intent since the argument form is this context is unambiguous: .. sourcecode:: pycon+sql >>> on_duplicate_key_stmt = insert_stmt.on_duplicate_key_update( ... [ ... ("data", "some data"), ... ("updated_at", func.current_timestamp()), ... ] ... ) >>> print(on_duplicate_key_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (%s, %s) ON DUPLICATE KEY UPDATE data = %s, updated_at = CURRENT_TIMESTAMP .. versionchanged:: 1.3 support for parameter-ordered UPDATE clause within MySQL ON DUPLICATE KEY UPDATE .. warning:: The :meth:`_mysql.Insert.on_duplicate_key_update` method does **not** take into account Python-side default UPDATE values or generation functions, e.g. e.g. those specified using :paramref:`_schema.Column.onupdate`. These values will not be exercised for an ON DUPLICATE KEY style of UPDATE, unless they are manually specified explicitly in the parameters. In order to refer to the proposed insertion row, the special alias :attr:`_mysql.Insert.inserted` is available as an attribute on the :class:`_mysql.Insert` object; this object is a :class:`_expression.ColumnCollection` which contains all columns of the target table: .. sourcecode:: pycon+sql >>> stmt = insert(my_table).values( ... id="some_id", data="inserted value", author="jlh" ... ) >>> do_update_stmt = stmt.on_duplicate_key_update( ... data="updated value", author=stmt.inserted.author ... ) >>> print(do_update_stmt) {printsql}INSERT INTO my_table (id, data, author) VALUES (%s, %s, %s) ON DUPLICATE KEY UPDATE data = %s, author = VALUES(author) When rendered, the "inserted" namespace will produce the expression ``VALUES(<columnname>)``. .. versionadded:: 1.2 Added support for MySQL ON DUPLICATE KEY UPDATE clause rowcount Support ---------------- SQLAlchemy standardizes the DBAPI ``cursor.rowcount`` attribute to be the usual definition of "number of rows matched by an UPDATE or DELETE" statement. This is in contradiction to the default setting on most MySQL DBAPI drivers, which is "number of rows actually modified/deleted". For this reason, the SQLAlchemy MySQL dialects always add the ``constants.CLIENT.FOUND_ROWS`` flag, or whatever is equivalent for the target dialect, upon connection. This setting is currently hardcoded. .. seealso:: :attr:`_engine.CursorResult.rowcount` .. _mysql_indexes: MySQL / MariaDB- Specific Index Options ----------------------------------------- MySQL and MariaDB-specific extensions to the :class:`.Index` construct are available. Index Length ~~~~~~~~~~~~~ MySQL and MariaDB both provide an option to create index entries with a certain length, where "length" refers to the number of characters or bytes in each value which will become part of the index. SQLAlchemy provides this feature via the ``mysql_length`` and/or ``mariadb_length`` parameters:: Index("my_index", my_table.c.data, mysql_length=10, mariadb_length=10) Index("a_b_idx", my_table.c.a, my_table.c.b, mysql_length={"a": 4, "b": 9}) Index( "a_b_idx", my_table.c.a, my_table.c.b, mariadb_length={"a": 4, "b": 9} ) Prefix lengths are given in characters for nonbinary string types and in bytes for binary string types. The value passed to the keyword argument *must* be either an integer (and, thus, specify the same prefix length value for all columns of the index) or a dict in which keys are column names and values are prefix length values for corresponding columns. MySQL and MariaDB only allow a length for a column of an index if it is for a CHAR, VARCHAR, TEXT, BINARY, VARBINARY and BLOB. Index Prefixes ~~~~~~~~~~~~~~ MySQL storage engines permit you to specify an index prefix when creating an index. SQLAlchemy provides this feature via the ``mysql_prefix`` parameter on :class:`.Index`:: Index("my_index", my_table.c.data, mysql_prefix="FULLTEXT") The value passed to the keyword argument will be simply passed through to the underlying CREATE INDEX, so it *must* be a valid index prefix for your MySQL storage engine. .. seealso:: `CREATE INDEX <https://dev.mysql.com/doc/refman/5.0/en/create-index.html>`_ - MySQL documentation Index Types ~~~~~~~~~~~~~ Some MySQL storage engines permit you to specify an index type when creating an index or primary key constraint. SQLAlchemy provides this feature via the ``mysql_using`` parameter on :class:`.Index`:: Index( "my_index", my_table.c.data, mysql_using="hash", mariadb_using="hash" ) As well as the ``mysql_using`` parameter on :class:`.PrimaryKeyConstraint`:: PrimaryKeyConstraint("data", mysql_using="hash", mariadb_using="hash") The value passed to the keyword argument will be simply passed through to the underlying CREATE INDEX or PRIMARY KEY clause, so it *must* be a valid index type for your MySQL storage engine. More information can be found at: https://dev.mysql.com/doc/refman/5.0/en/create-index.html https://dev.mysql.com/doc/refman/5.0/en/create-table.html Index Parsers ~~~~~~~~~~~~~ CREATE FULLTEXT INDEX in MySQL also supports a "WITH PARSER" option. This is available using the keyword argument ``mysql_with_parser``:: Index( "my_index", my_table.c.data, mysql_prefix="FULLTEXT", mysql_with_parser="ngram", mariadb_prefix="FULLTEXT", mariadb_with_parser="ngram", ) .. versionadded:: 1.3 .. _mysql_foreign_keys: MySQL / MariaDB Foreign Keys ----------------------------- MySQL and MariaDB's behavior regarding foreign keys has some important caveats. Foreign Key Arguments to Avoid ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Neither MySQL nor MariaDB support the foreign key arguments "DEFERRABLE", "INITIALLY", or "MATCH". Using the ``deferrable`` or ``initially`` keyword argument with :class:`_schema.ForeignKeyConstraint` or :class:`_schema.ForeignKey` will have the effect of these keywords being rendered in a DDL expression, which will then raise an error on MySQL or MariaDB. In order to use these keywords on a foreign key while having them ignored on a MySQL / MariaDB backend, use a custom compile rule:: from sqlalchemy.ext.compiler import compiles from sqlalchemy.schema import ForeignKeyConstraint @compiles(ForeignKeyConstraint, "mysql", "mariadb") def process(element, compiler, **kw): element.deferrable = element.initially = None return compiler.visit_foreign_key_constraint(element, **kw) The "MATCH" keyword is in fact more insidious, and is explicitly disallowed by SQLAlchemy in conjunction with the MySQL or MariaDB backends. This argument is silently ignored by MySQL / MariaDB, but in addition has the effect of ON UPDATE and ON DELETE options also being ignored by the backend. Therefore MATCH should never be used with the MySQL / MariaDB backends; as is the case with DEFERRABLE and INITIALLY, custom compilation rules can be used to correct a ForeignKeyConstraint at DDL definition time. Reflection of Foreign Key Constraints ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Not all MySQL / MariaDB storage engines support foreign keys. When using the very common ``MyISAM`` MySQL storage engine, the information loaded by table reflection will not include foreign keys. For these tables, you may supply a :class:`~sqlalchemy.ForeignKeyConstraint` at reflection time:: Table( "mytable", metadata, ForeignKeyConstraint(["other_id"], ["othertable.other_id"]), autoload_with=engine, ) .. seealso:: :ref:`mysql_storage_engines` .. _mysql_unique_constraints: MySQL / MariaDB Unique Constraints and Reflection ---------------------------------------------------- SQLAlchemy supports both the :class:`.Index` construct with the flag ``unique=True``, indicating a UNIQUE index, as well as the :class:`.UniqueConstraint` construct, representing a UNIQUE constraint. Both objects/syntaxes are supported by MySQL / MariaDB when emitting DDL to create these constraints. However, MySQL / MariaDB does not have a unique constraint construct that is separate from a unique index; that is, the "UNIQUE" constraint on MySQL / MariaDB is equivalent to creating a "UNIQUE INDEX". When reflecting these constructs, the :meth:`_reflection.Inspector.get_indexes` and the :meth:`_reflection.Inspector.get_unique_constraints` methods will **both** return an entry for a UNIQUE index in MySQL / MariaDB. However, when performing full table reflection using ``Table(..., autoload_with=engine)``, the :class:`.UniqueConstraint` construct is **not** part of the fully reflected :class:`_schema.Table` construct under any circumstances; this construct is always represented by a :class:`.Index` with the ``unique=True`` setting present in the :attr:`_schema.Table.indexes` collection. TIMESTAMP / DATETIME issues --------------------------- .. _mysql_timestamp_onupdate: Rendering ON UPDATE CURRENT TIMESTAMP for MySQL / MariaDB's explicit_defaults_for_timestamp ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ MySQL / MariaDB have historically expanded the DDL for the :class:`_types.TIMESTAMP` datatype into the phrase "TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP", which includes non-standard SQL that automatically updates the column with the current timestamp when an UPDATE occurs, eliminating the usual need to use a trigger in such a case where server-side update changes are desired. MySQL 5.6 introduced a new flag `explicit_defaults_for_timestamp <https://dev.mysql.com/doc/refman/5.6/en/server-system-variables.html #sysvar_explicit_defaults_for_timestamp>`_ which disables the above behavior, and in MySQL 8 this flag defaults to true, meaning in order to get a MySQL "on update timestamp" without changing this flag, the above DDL must be rendered explicitly. Additionally, the same DDL is valid for use of the ``DATETIME`` datatype as well. SQLAlchemy's MySQL dialect does not yet have an option to generate MySQL's "ON UPDATE CURRENT_TIMESTAMP" clause, noting that this is not a general purpose "ON UPDATE" as there is no such syntax in standard SQL. SQLAlchemy's :paramref:`_schema.Column.server_onupdate` parameter is currently not related to this special MySQL behavior. To generate this DDL, make use of the :paramref:`_schema.Column.server_default` parameter and pass a textual clause that also includes the ON UPDATE clause:: from sqlalchemy import Table, MetaData, Column, Integer, String, TIMESTAMP from sqlalchemy import text metadata = MetaData() mytable = Table( "mytable", metadata, Column("id", Integer, primary_key=True), Column("data", String(50)), Column( "last_updated", TIMESTAMP, server_default=text( "CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP" ), ), ) The same instructions apply to use of the :class:`_types.DateTime` and :class:`_types.DATETIME` datatypes:: from sqlalchemy import DateTime mytable = Table( "mytable", metadata, Column("id", Integer, primary_key=True), Column("data", String(50)), Column( "last_updated", DateTime, server_default=text( "CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP" ), ), ) Even though the :paramref:`_schema.Column.server_onupdate` feature does not generate this DDL, it still may be desirable to signal to the ORM that this updated value should be fetched. This syntax looks like the following:: from sqlalchemy.schema import FetchedValue class MyClass(Base): __tablename__ = "mytable" id = Column(Integer, primary_key=True) data = Column(String(50)) last_updated = Column( TIMESTAMP, server_default=text( "CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP" ), server_onupdate=FetchedValue(), ) .. _mysql_timestamp_null: TIMESTAMP Columns and NULL ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ MySQL historically enforces that a column which specifies the TIMESTAMP datatype implicitly includes a default value of CURRENT_TIMESTAMP, even though this is not stated, and additionally sets the column as NOT NULL, the opposite behavior vs. that of all other datatypes: .. sourcecode:: text mysql> CREATE TABLE ts_test ( -> a INTEGER, -> b INTEGER NOT NULL, -> c TIMESTAMP, -> d TIMESTAMP DEFAULT CURRENT_TIMESTAMP, -> e TIMESTAMP NULL); Query OK, 0 rows affected (0.03 sec) mysql> SHOW CREATE TABLE ts_test; +---------+----------------------------------------------------- | Table | Create Table +---------+----------------------------------------------------- | ts_test | CREATE TABLE `ts_test` ( `a` int(11) DEFAULT NULL, `b` int(11) NOT NULL, `c` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, `d` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP, `e` timestamp NULL DEFAULT NULL ) ENGINE=MyISAM DEFAULT CHARSET=latin1 Above, we see that an INTEGER column defaults to NULL, unless it is specified with NOT NULL. But when the column is of type TIMESTAMP, an implicit default of CURRENT_TIMESTAMP is generated which also coerces the column to be a NOT NULL, even though we did not specify it as such. This behavior of MySQL can be changed on the MySQL side using the `explicit_defaults_for_timestamp <https://dev.mysql.com/doc/refman/5.6/en/server-system-variables.html #sysvar_explicit_defaults_for_timestamp>`_ configuration flag introduced in MySQL 5.6. With this server setting enabled, TIMESTAMP columns behave like any other datatype on the MySQL side with regards to defaults and nullability. However, to accommodate the vast majority of MySQL databases that do not specify this new flag, SQLAlchemy emits the "NULL" specifier explicitly with any TIMESTAMP column that does not specify ``nullable=False``. In order to accommodate newer databases that specify ``explicit_defaults_for_timestamp``, SQLAlchemy also emits NOT NULL for TIMESTAMP columns that do specify ``nullable=False``. The following example illustrates:: from sqlalchemy import MetaData, Integer, Table, Column, text from sqlalchemy.dialects.mysql import TIMESTAMP m = MetaData() t = Table( "ts_test", m, Column("a", Integer), Column("b", Integer, nullable=False), Column("c", TIMESTAMP), Column("d", TIMESTAMP, nullable=False), ) from sqlalchemy import create_engine e = create_engine("mysql+mysqldb://scott:tiger@localhost/test", echo=True) m.create_all(e) output: .. sourcecode:: sql CREATE TABLE ts_test ( a INTEGER, b INTEGER NOT NULL, c TIMESTAMP NULL, d TIMESTAMP NOT NULL ) """ # noqa from __future__ import annotations from array import array as _array from collections import defaultdict from itertools import compress import re from typing import cast from . import reflection as _reflection from .enumerated import ENUM from .enumerated import SET from .json import JSON from .json import JSONIndexType from .json import JSONPathType from .reserved_words import RESERVED_WORDS_MARIADB from .reserved_words import RESERVED_WORDS_MYSQL from .types import _FloatType from .types import _IntegerType from .types import _MatchType from .types import _NumericType from .types import _StringType from .types import BIGINT from .types import BIT from .types import CHAR from .types import DATETIME from .types import DECIMAL from .types import DOUBLE from .types import FLOAT from .types import INTEGER from .types import LONGBLOB from .types import LONGTEXT from .types import MEDIUMBLOB from .types import MEDIUMINT from .types import MEDIUMTEXT from .types import NCHAR from .types import NUMERIC from .types import NVARCHAR from .types import REAL from .types import SMALLINT from .types import TEXT from .types import TIME from .types import TIMESTAMP from .types import TINYBLOB from .types import TINYINT from .types import TINYTEXT from .types import VARCHAR from .types import YEAR from ... import exc from ... import literal_column from ... import log from ... import schema as sa_schema from ... import sql from ... import util from ...engine import cursor as _cursor from ...engine import default from ...engine import reflection from ...engine.reflection import ReflectionDefaults from ...sql import coercions from ...sql import compiler from ...sql import elements from ...sql import functions from ...sql import operators from ...sql import roles from ...sql import sqltypes from ...sql import util as sql_util from ...sql import visitors from ...sql.compiler import InsertmanyvaluesSentinelOpts from ...sql.compiler import SQLCompiler from ...sql.schema import SchemaConst from ...types import BINARY from ...types import BLOB from ...types import BOOLEAN from ...types import DATE from ...types import UUID from ...types import VARBINARY from ...util import topological SET_RE = re.compile( r"\s*SET\s+(?:(?:GLOBAL|SESSION)\s+)?\w", re.I | re.UNICODE ) # old names MSTime = TIME MSSet = SET MSEnum = ENUM MSLongBlob = LONGBLOB MSMediumBlob = MEDIUMBLOB MSTinyBlob = TINYBLOB MSBlob = BLOB MSBinary = BINARY MSVarBinary = VARBINARY MSNChar = NCHAR MSNVarChar = NVARCHAR MSChar = CHAR MSString = VARCHAR MSLongText = LONGTEXT MSMediumText = MEDIUMTEXT MSTinyText = TINYTEXT MSText = TEXT MSYear = YEAR MSTimeStamp = TIMESTAMP MSBit = BIT MSSmallInteger = SMALLINT MSTinyInteger = TINYINT MSMediumInteger = MEDIUMINT MSBigInteger = BIGINT MSNumeric = NUMERIC MSDecimal = DECIMAL MSDouble = DOUBLE MSReal = REAL MSFloat = FLOAT MSInteger = INTEGER colspecs = { _IntegerType: _IntegerType, _NumericType: _NumericType, _FloatType: _FloatType, sqltypes.Numeric: NUMERIC, sqltypes.Float: FLOAT, sqltypes.Double: DOUBLE, sqltypes.Time: TIME, sqltypes.Enum: ENUM, sqltypes.MatchType: _MatchType, sqltypes.JSON: JSON, sqltypes.JSON.JSONIndexType: JSONIndexType, sqltypes.JSON.JSONPathType: JSONPathType, } # Everything 3.23 through 5.1 excepting OpenGIS types. ischema_names = { "bigint": BIGINT, "binary": BINARY, "bit": BIT, "blob": BLOB, "boolean": BOOLEAN, "char": CHAR, "date": DATE, "datetime": DATETIME, "decimal": DECIMAL, "double": DOUBLE, "enum": ENUM, "fixed": DECIMAL, "float": FLOAT, "int": INTEGER, "integer": INTEGER, "json": JSON, "longblob": LONGBLOB, "longtext": LONGTEXT, "mediumblob": MEDIUMBLOB, "mediumint": MEDIUMINT, "mediumtext": MEDIUMTEXT, "nchar": NCHAR, "nvarchar": NVARCHAR, "numeric": NUMERIC, "set": SET, "smallint": SMALLINT, "text": TEXT, "time": TIME, "timestamp": TIMESTAMP, "tinyblob": TINYBLOB, "tinyint": TINYINT, "tinytext": TINYTEXT, "uuid": UUID, "varbinary": VARBINARY, "varchar": VARCHAR, "year": YEAR, } class MySQLExecutionContext(default.DefaultExecutionContext): def post_exec(self): if ( self.isdelete and cast(SQLCompiler, self.compiled).effective_returning and not self.cursor.description ): # All MySQL/mariadb drivers appear to not include # cursor.description for DELETE..RETURNING with no rows if the # WHERE criteria is a straight "false" condition such as our EMPTY # IN condition. manufacture an empty result in this case (issue # #10505) # # taken from cx_Oracle implementation self.cursor_fetch_strategy = ( _cursor.FullyBufferedCursorFetchStrategy( self.cursor, [ (entry.keyname, None) for entry in cast( SQLCompiler, self.compiled )._result_columns ], [], ) ) def create_server_side_cursor(self): if self.dialect.supports_server_side_cursors: return self._dbapi_connection.cursor(self.dialect._sscursor) else: raise NotImplementedError() def fire_sequence(self, seq, type_): return self._execute_scalar( ( "select nextval(%s)" % self.identifier_preparer.format_sequence(seq) ), type_, ) class MySQLCompiler(compiler.SQLCompiler): render_table_with_column_in_update_from = True """Overridden from base SQLCompiler value""" extract_map = compiler.SQLCompiler.extract_map.copy() extract_map.update({"milliseconds": "millisecond"}) def default_from(self): """Called when a ``SELECT`` statement has no froms, and no ``FROM`` clause is to be appended. """ if self.stack: stmt = self.stack[-1]["selectable"] if stmt._where_criteria: return " FROM DUAL" return "" def visit_random_func(self, fn, **kw): return "rand%s" % self.function_argspec(fn) def visit_rollup_func(self, fn, **kw): clause = ", ".join( elem._compiler_dispatch(self, **kw) for elem in fn.clauses ) return f"{clause} WITH ROLLUP" def visit_aggregate_strings_func(self, fn, **kw): expr, delimeter = ( elem._compiler_dispatch(self, **kw) for elem in fn.clauses ) return f"group_concat({expr} SEPARATOR {delimeter})" def visit_sequence(self, seq, **kw): return "nextval(%s)" % self.preparer.format_sequence(seq) def visit_sysdate_func(self, fn, **kw): return "SYSDATE()" def _render_json_extract_from_binary(self, binary, operator, **kw): # note we are intentionally calling upon the process() calls in the # order in which they appear in the SQL String as this is used # by positional parameter rendering if binary.type._type_affinity is sqltypes.JSON: return "JSON_EXTRACT(%s, %s)" % ( self.process(binary.left, **kw), self.process(binary.right, **kw), ) # for non-JSON, MySQL doesn't handle JSON null at all so it has to # be explicit case_expression = "CASE JSON_EXTRACT(%s, %s) WHEN 'null' THEN NULL" % ( self.process(binary.left, **kw), self.process(binary.right, **kw), ) if binary.type._type_affinity is sqltypes.Integer: type_expression = ( "ELSE CAST(JSON_EXTRACT(%s, %s) AS SIGNED INTEGER)" % ( self.process(binary.left, **kw), self.process(binary.right, **kw), ) ) elif binary.type._type_affinity is sqltypes.Numeric: if ( binary.type.scale is not None and binary.type.precision is not None ): # using DECIMAL here because MySQL does not recognize NUMERIC type_expression = ( "ELSE CAST(JSON_EXTRACT(%s, %s) AS DECIMAL(%s, %s))" % ( self.process(binary.left, **kw), self.process(binary.right, **kw), binary.type.precision, binary.type.scale, ) ) else: # FLOAT / REAL not added in MySQL til 8.0.17 type_expression = ( "ELSE JSON_EXTRACT(%s, %s)+0.0000000000000000000000" % ( self.process(binary.left, **kw), self.process(binary.right, **kw), ) ) elif binary.type._type_affinity is sqltypes.Boolean: # the NULL handling is particularly weird with boolean, so # explicitly return true/false constants type_expression = "WHEN true THEN true ELSE false" elif binary.type._type_affinity is sqltypes.String: # (gord): this fails with a JSON value that's a four byte unicode # string. SQLite has the same problem at the moment # (zzzeek): I'm not really sure. let's take a look at a test case # that hits each backend and maybe make a requires rule for it? type_expression = "ELSE JSON_UNQUOTE(JSON_EXTRACT(%s, %s))" % ( self.process(binary.left, **kw), self.process(binary.right, **kw), ) else: # other affinity....this is not expected right now type_expression = "ELSE JSON_EXTRACT(%s, %s)" % ( self.process(binary.left, **kw), self.process(binary.right, **kw), ) return case_expression + " " + type_expression + " END" def visit_json_getitem_op_binary(self, binary, operator, **kw): return self._render_json_extract_from_binary(binary, operator, **kw) def visit_json_path_getitem_op_binary(self, binary, operator, **kw): return self._render_json_extract_from_binary(binary, operator, **kw) def visit_on_duplicate_key_update(self, on_duplicate, **kw): statement = self.current_executable if on_duplicate._parameter_ordering: parameter_ordering = [ coercions.expect(roles.DMLColumnRole, key) for key in on_duplicate._parameter_ordering ] ordered_keys = set(parameter_ordering) cols = [ statement.table.c[key] for key in parameter_ordering if key in statement.table.c ] + [c for c in statement.table.c if c.key not in ordered_keys] else: cols = statement.table.c clauses = [] requires_mysql8_alias = statement.select is None and ( self.dialect._requires_alias_for_on_duplicate_key ) if requires_mysql8_alias: if statement.table.name.lower() == "new": _on_dup_alias_name = "new_1" else: _on_dup_alias_name = "new" on_duplicate_update = { coercions.expect_as_key(roles.DMLColumnRole, key): value for key, value in on_duplicate.update.items() } # traverses through all table columns to preserve table column order for column in (col for col in cols if col.key in on_duplicate_update): val = on_duplicate_update[column.key] # TODO: this coercion should be up front. we can't cache # SQL constructs with non-bound literals buried in them if coercions._is_literal(val): val = elements.BindParameter(None, val, type_=column.type) value_text = self.process(val.self_group(), use_schema=False) else: def replace(obj): if ( isinstance(obj, elements.BindParameter) and obj.type._isnull ): obj = obj._clone() obj.type = column.type return obj elif ( isinstance(obj, elements.ColumnClause) and obj.table is on_duplicate.inserted_alias ): if requires_mysql8_alias: column_literal_clause = ( f"{_on_dup_alias_name}." f"{self.preparer.quote(obj.name)}" ) else: column_literal_clause = ( f"VALUES({self.preparer.quote(obj.name)})" ) return literal_column(column_literal_clause) else: # element is not replaced return None val = visitors.replacement_traverse(val, {}, replace) value_text = self.process(val.self_group(), use_schema=False) name_text = self.preparer.quote(column.name) clauses.append("%s = %s" % (name_text, value_text)) non_matching = set(on_duplicate_update) - {c.key for c in cols} if non_matching: util.warn( "Additional column names not matching " "any column keys in table '%s': %s" % ( self.statement.table.name, (", ".join("'%s'" % c for c in non_matching)), ) ) if requires_mysql8_alias: return ( f"AS {_on_dup_alias_name} " f"ON DUPLICATE KEY UPDATE {', '.join(clauses)}" ) else: return f"ON DUPLICATE KEY UPDATE {', '.join(clauses)}" def visit_concat_op_expression_clauselist( self, clauselist, operator, **kw ): return "concat(%s)" % ( ", ".join(self.process(elem, **kw) for elem in clauselist.clauses) ) def visit_concat_op_binary(self, binary, operator, **kw): return "concat(%s, %s)" % ( self.process(binary.left, **kw), self.process(binary.right, **kw), ) _match_valid_flag_combinations = frozenset( ( # (boolean_mode, natural_language, query_expansion) (False, False, False), (True, False, False), (False, True, False), (False, False, True), (False, True, True), ) ) _match_flag_expressions = ( "IN BOOLEAN MODE", "IN NATURAL LANGUAGE MODE", "WITH QUERY EXPANSION", ) def visit_mysql_match(self, element, **kw): return self.visit_match_op_binary(element, element.operator, **kw) def visit_match_op_binary(self, binary, operator, **kw): """ Note that `mysql_boolean_mode` is enabled by default because of backward compatibility """ modifiers = binary.modifiers boolean_mode = modifiers.get("mysql_boolean_mode", True) natural_language = modifiers.get("mysql_natural_language", False) query_expansion = modifiers.get("mysql_query_expansion", False) flag_combination = (boolean_mode, natural_language, query_expansion) if flag_combination not in self._match_valid_flag_combinations: flags = ( "in_boolean_mode=%s" % boolean_mode, "in_natural_language_mode=%s" % natural_language, "with_query_expansion=%s" % query_expansion, ) flags = ", ".join(flags) raise exc.CompileError("Invalid MySQL match flags: %s" % flags) match_clause = binary.left match_clause = self.process(match_clause, **kw) against_clause = self.process(binary.right, **kw) if any(flag_combination): flag_expressions = compress( self._match_flag_expressions, flag_combination, ) against_clause = [against_clause] against_clause.extend(flag_expressions) against_clause = " ".join(against_clause) return "MATCH (%s) AGAINST (%s)" % (match_clause, against_clause) def get_from_hint_text(self, table, text): return text def visit_typeclause(self, typeclause, type_=None, **kw): if type_ is None: type_ = typeclause.type.dialect_impl(self.dialect) if isinstance(type_, sqltypes.TypeDecorator): return self.visit_typeclause(typeclause, type_.impl, **kw) elif isinstance(type_, sqltypes.Integer): if getattr(type_, "unsigned", False): return "UNSIGNED INTEGER" else: return "SIGNED INTEGER" elif isinstance(type_, sqltypes.TIMESTAMP): return "DATETIME" elif isinstance( type_, ( sqltypes.DECIMAL, sqltypes.DateTime, sqltypes.Date, sqltypes.Time, ), ): return self.dialect.type_compiler_instance.process(type_) elif isinstance(type_, sqltypes.String) and not isinstance( type_, (ENUM, SET) ): adapted = CHAR._adapt_string_for_cast(type_) return self.dialect.type_compiler_instance.process(adapted) elif isinstance(type_, sqltypes._Binary): return "BINARY" elif isinstance(type_, sqltypes.JSON): return "JSON" elif isinstance(type_, sqltypes.NUMERIC): return self.dialect.type_compiler_instance.process(type_).replace( "NUMERIC", "DECIMAL" ) elif ( isinstance(type_, sqltypes.Float) and self.dialect._support_float_cast ): return self.dialect.type_compiler_instance.process(type_) else: return None def visit_cast(self, cast, **kw): type_ = self.process(cast.typeclause) if type_ is None: util.warn( "Datatype %s does not support CAST on MySQL/MariaDb; " "the CAST will be skipped." % self.dialect.type_compiler_instance.process( cast.typeclause.type ) ) return self.process(cast.clause.self_group(), **kw) return "CAST(%s AS %s)" % (self.process(cast.clause, **kw), type_) def render_literal_value(self, value, type_): value = super().render_literal_value(value, type_) if self.dialect._backslash_escapes: value = value.replace("\\", "\\\\") return value # override native_boolean=False behavior here, as # MySQL still supports native boolean def visit_true(self, element, **kw): return "true" def visit_false(self, element, **kw): return "false" def get_select_precolumns(self, select, **kw): """Add special MySQL keywords in place of DISTINCT. .. deprecated:: 1.4 This usage is deprecated. :meth:`_expression.Select.prefix_with` should be used for special keywords at the start of a SELECT. """ if isinstance(select._distinct, str): util.warn_deprecated( "Sending string values for 'distinct' is deprecated in the " "MySQL dialect and will be removed in a future release. " "Please use :meth:`.Select.prefix_with` for special keywords " "at the start of a SELECT statement", version="1.4", ) return select._distinct.upper() + " " return super().get_select_precolumns(select, **kw) def visit_join(self, join, asfrom=False, from_linter=None, **kwargs): if from_linter: from_linter.edges.add((join.left, join.right)) if join.full: join_type = " FULL OUTER JOIN " elif join.isouter: join_type = " LEFT OUTER JOIN " else: join_type = " INNER JOIN " return "".join( ( self.process( join.left, asfrom=True, from_linter=from_linter, **kwargs ), join_type, self.process( join.right, asfrom=True, from_linter=from_linter, **kwargs ), " ON ", self.process(join.onclause, from_linter=from_linter, **kwargs), ) ) def for_update_clause(self, select, **kw): if select._for_update_arg.read: tmp = " LOCK IN SHARE MODE" else: tmp = " FOR UPDATE" if select._for_update_arg.of and self.dialect.supports_for_update_of: tables = util.OrderedSet() for c in select._for_update_arg.of: tables.update(sql_util.surface_selectables_only(c)) tmp += " OF " + ", ".join( self.process(table, ashint=True, use_schema=False, **kw) for table in tables ) if select._for_update_arg.nowait: tmp += " NOWAIT" if select._for_update_arg.skip_locked: tmp += " SKIP LOCKED" return tmp def limit_clause(self, select, **kw): # MySQL supports: # LIMIT <limit> # LIMIT <offset>, <limit> # and in server versions > 3.3: # LIMIT <limit> OFFSET <offset> # The latter is more readable for offsets but we're stuck with the # former until we can refine dialects by server revision. limit_clause, offset_clause = ( select._limit_clause, select._offset_clause, ) if limit_clause is None and offset_clause is None: return "" elif offset_clause is not None: # As suggested by the MySQL docs, need to apply an # artificial limit if one wasn't provided # https://dev.mysql.com/doc/refman/5.0/en/select.html if limit_clause is None: # TODO: remove ?? # hardwire the upper limit. Currently # needed consistent with the usage of the upper # bound as part of MySQL's "syntax" for OFFSET with # no LIMIT. return " \n LIMIT %s, %s" % ( self.process(offset_clause, **kw), "18446744073709551615", ) else: return " \n LIMIT %s, %s" % ( self.process(offset_clause, **kw), self.process(limit_clause, **kw), ) else: # No offset provided, so just use the limit return " \n LIMIT %s" % (self.process(limit_clause, **kw),) def update_limit_clause(self, update_stmt): limit = update_stmt.kwargs.get("%s_limit" % self.dialect.name, None) if limit is not None: return f"LIMIT {int(limit)}" else: return None def delete_limit_clause(self, delete_stmt): limit = delete_stmt.kwargs.get("%s_limit" % self.dialect.name, None) if limit is not None: return f"LIMIT {int(limit)}" else: return None def update_tables_clause(self, update_stmt, from_table, extra_froms, **kw): kw["asfrom"] = True return ", ".join( t._compiler_dispatch(self, **kw) for t in [from_table] + list(extra_froms) ) def update_from_clause( self, update_stmt, from_table, extra_froms, from_hints, **kw ): return None def delete_table_clause(self, delete_stmt, from_table, extra_froms, **kw): """If we have extra froms make sure we render any alias as hint.""" ashint = False if extra_froms: ashint = True return from_table._compiler_dispatch( self, asfrom=True, iscrud=True, ashint=ashint, **kw ) def delete_extra_from_clause( self, delete_stmt, from_table, extra_froms, from_hints, **kw ): """Render the DELETE .. USING clause specific to MySQL.""" kw["asfrom"] = True return "USING " + ", ".join( t._compiler_dispatch(self, fromhints=from_hints, **kw) for t in [from_table] + extra_froms ) def visit_empty_set_expr(self, element_types, **kw): return ( "SELECT %(outer)s FROM (SELECT %(inner)s) " "as _empty_set WHERE 1!=1" % { "inner": ", ".join( "1 AS _in_%s" % idx for idx, type_ in enumerate(element_types) ), "outer": ", ".join( "_in_%s" % idx for idx, type_ in enumerate(element_types) ), } ) def visit_is_distinct_from_binary(self, binary, operator, **kw): return "NOT (%s <=> %s)" % ( self.process(binary.left), self.process(binary.right), ) def visit_is_not_distinct_from_binary(self, binary, operator, **kw): return "%s <=> %s" % ( self.process(binary.left), self.process(binary.right), ) def _mariadb_regexp_flags(self, flags, pattern, **kw): return "CONCAT('(?', %s, ')', %s)" % ( self.render_literal_value(flags, sqltypes.STRINGTYPE), self.process(pattern, **kw), ) def _regexp_match(self, op_string, binary, operator, **kw): flags = binary.modifiers["flags"] if flags is None: return self._generate_generic_binary(binary, op_string, **kw) elif self.dialect.is_mariadb: return "%s%s%s" % ( self.process(binary.left, **kw), op_string, self._mariadb_regexp_flags(flags, binary.right), ) else: text = "REGEXP_LIKE(%s, %s, %s)" % ( self.process(binary.left, **kw), self.process(binary.right, **kw), self.render_literal_value(flags, sqltypes.STRINGTYPE), ) if op_string == " NOT REGEXP ": return "NOT %s" % text else: return text def visit_regexp_match_op_binary(self, binary, operator, **kw): return self._regexp_match(" REGEXP ", binary, operator, **kw) def visit_not_regexp_match_op_binary(self, binary, operator, **kw): return self._regexp_match(" NOT REGEXP ", binary, operator, **kw) def visit_regexp_replace_op_binary(self, binary, operator, **kw): flags = binary.modifiers["flags"] if flags is None: return "REGEXP_REPLACE(%s, %s)" % ( self.process(binary.left, **kw), self.process(binary.right, **kw), ) elif self.dialect.is_mariadb: return "REGEXP_REPLACE(%s, %s, %s)" % ( self.process(binary.left, **kw), self._mariadb_regexp_flags(flags, binary.right.clauses[0]), self.process(binary.right.clauses[1], **kw), ) else: return "REGEXP_REPLACE(%s, %s, %s)" % ( self.process(binary.left, **kw), self.process(binary.right, **kw), self.render_literal_value(flags, sqltypes.STRINGTYPE), ) class MySQLDDLCompiler(compiler.DDLCompiler): def get_column_specification(self, column, **kw): """Builds column DDL.""" if ( self.dialect.is_mariadb is True and column.computed is not None and column._user_defined_nullable is SchemaConst.NULL_UNSPECIFIED ): column.nullable = True colspec = [ self.preparer.format_column(column), self.dialect.type_compiler_instance.process( column.type, type_expression=column ), ] if column.computed is not None: colspec.append(self.process(column.computed)) is_timestamp = isinstance( column.type._unwrapped_dialect_impl(self.dialect), sqltypes.TIMESTAMP, ) if not column.nullable: colspec.append("NOT NULL") # see: https://docs.sqlalchemy.org/en/latest/dialects/mysql.html#mysql_timestamp_null # noqa elif column.nullable and is_timestamp: colspec.append("NULL") comment = column.comment if comment is not None: literal = self.sql_compiler.render_literal_value( comment, sqltypes.String() ) colspec.append("COMMENT " + literal) if ( column.table is not None and column is column.table._autoincrement_column and ( column.server_default is None or isinstance(column.server_default, sa_schema.Identity) ) and not ( self.dialect.supports_sequences and isinstance(column.default, sa_schema.Sequence) and not column.default.optional ) ): colspec.append("AUTO_INCREMENT") else: default = self.get_column_default_string(column) if default is not None: if ( self.dialect._support_default_function and not re.match(r"^\s*[\'\"\(]", default) and not re.search(r"ON +UPDATE", default, re.I) and re.match(r".*\W.*", default) ): colspec.append(f"DEFAULT ({default})") else: colspec.append("DEFAULT " + default) return " ".join(colspec) def post_create_table(self, table): """Build table-level CREATE options like ENGINE and COLLATE.""" table_opts = [] opts = { k[len(self.dialect.name) + 1 :].upper(): v for k, v in table.kwargs.items() if k.startswith("%s_" % self.dialect.name) } if table.comment is not None: opts["COMMENT"] = table.comment partition_options = [ "PARTITION_BY", "PARTITIONS", "SUBPARTITIONS", "SUBPARTITION_BY", ] nonpart_options = set(opts).difference(partition_options) part_options = set(opts).intersection(partition_options) for opt in topological.sort( [ ("DEFAULT_CHARSET", "COLLATE"), ("DEFAULT_CHARACTER_SET", "COLLATE"), ("CHARSET", "COLLATE"), ("CHARACTER_SET", "COLLATE"), ], nonpart_options, ): arg = opts[opt] if opt in _reflection._options_of_type_string: arg = self.sql_compiler.render_literal_value( arg, sqltypes.String() ) if opt in ( "DATA_DIRECTORY", "INDEX_DIRECTORY", "DEFAULT_CHARACTER_SET", "CHARACTER_SET", "DEFAULT_CHARSET", "DEFAULT_COLLATE", ): opt = opt.replace("_", " ") joiner = "=" if opt in ( "TABLESPACE", "DEFAULT CHARACTER SET", "CHARACTER SET", "COLLATE", ): joiner = " " table_opts.append(joiner.join((opt, arg))) for opt in topological.sort( [ ("PARTITION_BY", "PARTITIONS"), ("PARTITION_BY", "SUBPARTITION_BY"), ("PARTITION_BY", "SUBPARTITIONS"), ("PARTITIONS", "SUBPARTITIONS"), ("PARTITIONS", "SUBPARTITION_BY"), ("SUBPARTITION_BY", "SUBPARTITIONS"), ], part_options, ): arg = opts[opt] if opt in _reflection._options_of_type_string: arg = self.sql_compiler.render_literal_value( arg, sqltypes.String() ) opt = opt.replace("_", " ") joiner = " " table_opts.append(joiner.join((opt, arg))) return " ".join(table_opts) def visit_create_index(self, create, **kw): index = create.element self._verify_index_table(index) preparer = self.preparer table = preparer.format_table(index.table) columns = [ self.sql_compiler.process( ( elements.Grouping(expr) if ( isinstance(expr, elements.BinaryExpression) or ( isinstance(expr, elements.UnaryExpression) and expr.modifier not in (operators.desc_op, operators.asc_op) ) or isinstance(expr, functions.FunctionElement) ) else expr ), include_table=False, literal_binds=True, ) for expr in index.expressions ] name = self._prepared_index_name(index) text = "CREATE " if index.unique: text += "UNIQUE " index_prefix = index.kwargs.get("%s_prefix" % self.dialect.name, None) if index_prefix: text += index_prefix + " " text += "INDEX " if create.if_not_exists: text += "IF NOT EXISTS " text += "%s ON %s " % (name, table) length = index.dialect_options[self.dialect.name]["length"] if length is not None: if isinstance(length, dict): # length value can be a (column_name --> integer value) # mapping specifying the prefix length for each column of the # index columns = ", ".join( ( "%s(%d)" % (expr, length[col.name]) if col.name in length else ( "%s(%d)" % (expr, length[expr]) if expr in length else "%s" % expr ) ) for col, expr in zip(index.expressions, columns) ) else: # or can be an integer value specifying the same # prefix length for all columns of the index columns = ", ".join( "%s(%d)" % (col, length) for col in columns ) else: columns = ", ".join(columns) text += "(%s)" % columns parser = index.dialect_options["mysql"]["with_parser"] if parser is not None: text += " WITH PARSER %s" % (parser,) using = index.dialect_options["mysql"]["using"] if using is not None: text += " USING %s" % (preparer.quote(using)) return text def visit_primary_key_constraint(self, constraint, **kw): text = super().visit_primary_key_constraint(constraint) using = constraint.dialect_options["mysql"]["using"] if using: text += " USING %s" % (self.preparer.quote(using)) return text def visit_drop_index(self, drop, **kw): index = drop.element text = "\nDROP INDEX " if drop.if_exists: text += "IF EXISTS " return text + "%s ON %s" % ( self._prepared_index_name(index, include_schema=False), self.preparer.format_table(index.table), ) def visit_drop_constraint(self, drop, **kw): constraint = drop.element if isinstance(constraint, sa_schema.ForeignKeyConstraint): qual = "FOREIGN KEY " const = self.preparer.format_constraint(constraint) elif isinstance(constraint, sa_schema.PrimaryKeyConstraint): qual = "PRIMARY KEY " const = "" elif isinstance(constraint, sa_schema.UniqueConstraint): qual = "INDEX " const = self.preparer.format_constraint(constraint) elif isinstance(constraint, sa_schema.CheckConstraint): if self.dialect.is_mariadb: qual = "CONSTRAINT " else: qual = "CHECK " const = self.preparer.format_constraint(constraint) else: qual = "" const = self.preparer.format_constraint(constraint) return "ALTER TABLE %s DROP %s%s" % ( self.preparer.format_table(constraint.table), qual, const, ) def define_constraint_match(self, constraint): if constraint.match is not None: raise exc.CompileError( "MySQL ignores the 'MATCH' keyword while at the same time " "causes ON UPDATE/ON DELETE clauses to be ignored." ) return "" def visit_set_table_comment(self, create, **kw): return "ALTER TABLE %s COMMENT %s" % ( self.preparer.format_table(create.element), self.sql_compiler.render_literal_value( create.element.comment, sqltypes.String() ), ) def visit_drop_table_comment(self, create, **kw): return "ALTER TABLE %s COMMENT ''" % ( self.preparer.format_table(create.element) ) def visit_set_column_comment(self, create, **kw): return "ALTER TABLE %s CHANGE %s %s" % ( self.preparer.format_table(create.element.table), self.preparer.format_column(create.element), self.get_column_specification(create.element), ) class MySQLTypeCompiler(compiler.GenericTypeCompiler): def _extend_numeric(self, type_, spec): "Extend a numeric-type declaration with MySQL specific extensions." if not self._mysql_type(type_): return spec if type_.unsigned: spec += " UNSIGNED" if type_.zerofill: spec += " ZEROFILL" return spec def _extend_string(self, type_, defaults, spec): """Extend a string-type declaration with standard SQL CHARACTER SET / COLLATE annotations and MySQL specific extensions. """ def attr(name): return getattr(type_, name, defaults.get(name)) if attr("charset"): charset = "CHARACTER SET %s" % attr("charset") elif attr("ascii"): charset = "ASCII" elif attr("unicode"): charset = "UNICODE" else: charset = None if attr("collation"): collation = "COLLATE %s" % type_.collation elif attr("binary"): collation = "BINARY" else: collation = None if attr("national"): # NATIONAL (aka NCHAR/NVARCHAR) trumps charsets. return " ".join( [c for c in ("NATIONAL", spec, collation) if c is not None] ) return " ".join( [c for c in (spec, charset, collation) if c is not None] ) def _mysql_type(self, type_): return isinstance(type_, (_StringType, _NumericType)) def visit_NUMERIC(self, type_, **kw): if type_.precision is None: return self._extend_numeric(type_, "NUMERIC") elif type_.scale is None: return self._extend_numeric( type_, "NUMERIC(%(precision)s)" % {"precision": type_.precision}, ) else: return self._extend_numeric( type_, "NUMERIC(%(precision)s, %(scale)s)" % {"precision": type_.precision, "scale": type_.scale}, ) def visit_DECIMAL(self, type_, **kw): if type_.precision is None: return self._extend_numeric(type_, "DECIMAL") elif type_.scale is None: return self._extend_numeric( type_, "DECIMAL(%(precision)s)" % {"precision": type_.precision}, ) else: return self._extend_numeric( type_, "DECIMAL(%(precision)s, %(scale)s)" % {"precision": type_.precision, "scale": type_.scale}, ) def visit_DOUBLE(self, type_, **kw): if type_.precision is not None and type_.scale is not None: return self._extend_numeric( type_, "DOUBLE(%(precision)s, %(scale)s)" % {"precision": type_.precision, "scale": type_.scale}, ) else: return self._extend_numeric(type_, "DOUBLE") def visit_REAL(self, type_, **kw): if type_.precision is not None and type_.scale is not None: return self._extend_numeric( type_, "REAL(%(precision)s, %(scale)s)" % {"precision": type_.precision, "scale": type_.scale}, ) else: return self._extend_numeric(type_, "REAL") def visit_FLOAT(self, type_, **kw): if ( self._mysql_type(type_) and type_.scale is not None and type_.precision is not None ): return self._extend_numeric( type_, "FLOAT(%s, %s)" % (type_.precision, type_.scale) ) elif type_.precision is not None: return self._extend_numeric( type_, "FLOAT(%s)" % (type_.precision,) ) else: return self._extend_numeric(type_, "FLOAT") def visit_INTEGER(self, type_, **kw): if self._mysql_type(type_) and type_.display_width is not None: return self._extend_numeric( type_, "INTEGER(%(display_width)s)" % {"display_width": type_.display_width}, ) else: return self._extend_numeric(type_, "INTEGER") def visit_BIGINT(self, type_, **kw): if self._mysql_type(type_) and type_.display_width is not None: return self._extend_numeric( type_, "BIGINT(%(display_width)s)" % {"display_width": type_.display_width}, ) else: return self._extend_numeric(type_, "BIGINT") def visit_MEDIUMINT(self, type_, **kw): if self._mysql_type(type_) and type_.display_width is not None: return self._extend_numeric( type_, "MEDIUMINT(%(display_width)s)" % {"display_width": type_.display_width}, ) else: return self._extend_numeric(type_, "MEDIUMINT") def visit_TINYINT(self, type_, **kw): if self._mysql_type(type_) and type_.display_width is not None: return self._extend_numeric( type_, "TINYINT(%s)" % type_.display_width ) else: return self._extend_numeric(type_, "TINYINT") def visit_SMALLINT(self, type_, **kw): if self._mysql_type(type_) and type_.display_width is not None: return self._extend_numeric( type_, "SMALLINT(%(display_width)s)" % {"display_width": type_.display_width}, ) else: return self._extend_numeric(type_, "SMALLINT") def visit_BIT(self, type_, **kw): if type_.length is not None: return "BIT(%s)" % type_.length else: return "BIT" def visit_DATETIME(self, type_, **kw): if getattr(type_, "fsp", None): return "DATETIME(%d)" % type_.fsp else: return "DATETIME" def visit_DATE(self, type_, **kw): return "DATE" def visit_TIME(self, type_, **kw): if getattr(type_, "fsp", None): return "TIME(%d)" % type_.fsp else: return "TIME" def visit_TIMESTAMP(self, type_, **kw): if getattr(type_, "fsp", None): return "TIMESTAMP(%d)" % type_.fsp else: return "TIMESTAMP" def visit_YEAR(self, type_, **kw): if type_.display_width is None: return "YEAR" else: return "YEAR(%s)" % type_.display_width def visit_TEXT(self, type_, **kw): if type_.length is not None: return self._extend_string(type_, {}, "TEXT(%d)" % type_.length) else: return self._extend_string(type_, {}, "TEXT") def visit_TINYTEXT(self, type_, **kw): return self._extend_string(type_, {}, "TINYTEXT") def visit_MEDIUMTEXT(self, type_, **kw): return self._extend_string(type_, {}, "MEDIUMTEXT") def visit_LONGTEXT(self, type_, **kw): return self._extend_string(type_, {}, "LONGTEXT") def visit_VARCHAR(self, type_, **kw): if type_.length is not None: return self._extend_string(type_, {}, "VARCHAR(%d)" % type_.length) else: raise exc.CompileError( "VARCHAR requires a length on dialect %s" % self.dialect.name ) def visit_CHAR(self, type_, **kw): if type_.length is not None: return self._extend_string( type_, {}, "CHAR(%(length)s)" % {"length": type_.length} ) else: return self._extend_string(type_, {}, "CHAR") def visit_NVARCHAR(self, type_, **kw): # We'll actually generate the equiv. "NATIONAL VARCHAR" instead # of "NVARCHAR". if type_.length is not None: return self._extend_string( type_, {"national": True}, "VARCHAR(%(length)s)" % {"length": type_.length}, ) else: raise exc.CompileError( "NVARCHAR requires a length on dialect %s" % self.dialect.name ) def visit_NCHAR(self, type_, **kw): # We'll actually generate the equiv. # "NATIONAL CHAR" instead of "NCHAR". if type_.length is not None: return self._extend_string( type_, {"national": True}, "CHAR(%(length)s)" % {"length": type_.length}, ) else: return self._extend_string(type_, {"national": True}, "CHAR") def visit_UUID(self, type_, **kw): return "UUID" def visit_VARBINARY(self, type_, **kw): return "VARBINARY(%d)" % type_.length def visit_JSON(self, type_, **kw): return "JSON" def visit_large_binary(self, type_, **kw): return self.visit_BLOB(type_) def visit_enum(self, type_, **kw): if not type_.native_enum: return super().visit_enum(type_) else: return self._visit_enumerated_values("ENUM", type_, type_.enums) def visit_BLOB(self, type_, **kw): if type_.length is not None: return "BLOB(%d)" % type_.length else: return "BLOB" def visit_TINYBLOB(self, type_, **kw): return "TINYBLOB" def visit_MEDIUMBLOB(self, type_, **kw): return "MEDIUMBLOB" def visit_LONGBLOB(self, type_, **kw): return "LONGBLOB" def _visit_enumerated_values(self, name, type_, enumerated_values): quoted_enums = [] for e in enumerated_values: if self.dialect.identifier_preparer._double_percents: e = e.replace("%", "%%") quoted_enums.append("'%s'" % e.replace("'", "''")) return self._extend_string( type_, {}, "%s(%s)" % (name, ",".join(quoted_enums)) ) def visit_ENUM(self, type_, **kw): return self._visit_enumerated_values("ENUM", type_, type_.enums) def visit_SET(self, type_, **kw): return self._visit_enumerated_values("SET", type_, type_.values) def visit_BOOLEAN(self, type_, **kw): return "BOOL" class MySQLIdentifierPreparer(compiler.IdentifierPreparer): reserved_words = RESERVED_WORDS_MYSQL def __init__(self, dialect, server_ansiquotes=False, **kw): if not server_ansiquotes: quote = "`" else: quote = '"' super().__init__(dialect, initial_quote=quote, escape_quote=quote) def _quote_free_identifiers(self, *ids): """Unilaterally identifier-quote any number of strings.""" return tuple([self.quote_identifier(i) for i in ids if i is not None]) class MariaDBIdentifierPreparer(MySQLIdentifierPreparer): reserved_words = RESERVED_WORDS_MARIADB @log.class_logger class MySQLDialect(default.DefaultDialect): """Details of the MySQL dialect. Not used directly in application code. """ name = "mysql" supports_statement_cache = True supports_alter = True # MySQL has no true "boolean" type; we # allow for the "true" and "false" keywords, however supports_native_boolean = False # support for BIT type; mysqlconnector coerces result values automatically, # all other MySQL DBAPIs require a conversion routine supports_native_bit = False # identifiers are 64, however aliases can be 255... max_identifier_length = 255 max_index_name_length = 64 max_constraint_name_length = 64 div_is_floordiv = False supports_native_enum = True returns_native_bytes = True supports_sequences = False # default for MySQL ... # ... may be updated to True for MariaDB 10.3+ in initialize() sequences_optional = False supports_for_update_of = False # default for MySQL ... # ... may be updated to True for MySQL 8+ in initialize() _requires_alias_for_on_duplicate_key = False # Only available ... # ... in MySQL 8+ # MySQL doesn't support "DEFAULT VALUES" but *does* support # "VALUES (DEFAULT)" supports_default_values = False supports_default_metavalue = True use_insertmanyvalues: bool = True insertmanyvalues_implicit_sentinel = ( InsertmanyvaluesSentinelOpts.ANY_AUTOINCREMENT ) supports_sane_rowcount = True supports_sane_multi_rowcount = False supports_multivalues_insert = True insert_null_pk_still_autoincrements = True supports_comments = True inline_comments = True default_paramstyle = "format" colspecs = colspecs cte_follows_insert = True statement_compiler = MySQLCompiler ddl_compiler = MySQLDDLCompiler type_compiler_cls = MySQLTypeCompiler ischema_names = ischema_names preparer = MySQLIdentifierPreparer is_mariadb = False _mariadb_normalized_version_info = None # default SQL compilation settings - # these are modified upon initialize(), # i.e. first connect _backslash_escapes = True _server_ansiquotes = False construct_arguments = [ (sa_schema.Table, {"*": None}), (sql.Update, {"limit": None}), (sql.Delete, {"limit": None}), (sa_schema.PrimaryKeyConstraint, {"using": None}), ( sa_schema.Index, { "using": None, "length": None, "prefix": None, "with_parser": None, }, ), ] def __init__( self, json_serializer=None, json_deserializer=None, is_mariadb=None, **kwargs, ): kwargs.pop("use_ansiquotes", None) # legacy default.DefaultDialect.__init__(self, **kwargs) self._json_serializer = json_serializer self._json_deserializer = json_deserializer self._set_mariadb(is_mariadb, None) def get_isolation_level_values(self, dbapi_conn): return ( "SERIALIZABLE", "READ UNCOMMITTED", "READ COMMITTED", "REPEATABLE READ", ) def set_isolation_level(self, dbapi_connection, level): cursor = dbapi_connection.cursor() cursor.execute(f"SET SESSION TRANSACTION ISOLATION LEVEL {level}") cursor.execute("COMMIT") cursor.close() def get_isolation_level(self, dbapi_connection): cursor = dbapi_connection.cursor() if self._is_mysql and self.server_version_info >= (5, 7, 20): cursor.execute("SELECT @@transaction_isolation") else: cursor.execute("SELECT @@tx_isolation") row = cursor.fetchone() if row is None: util.warn( "Could not retrieve transaction isolation level for MySQL " "connection." ) raise NotImplementedError() val = row[0] cursor.close() if isinstance(val, bytes): val = val.decode() return val.upper().replace("-", " ") @classmethod def _is_mariadb_from_url(cls, url): dbapi = cls.import_dbapi() dialect = cls(dbapi=dbapi) cargs, cparams = dialect.create_connect_args(url) conn = dialect.connect(*cargs, **cparams) try: cursor = conn.cursor() cursor.execute("SELECT VERSION() LIKE '%MariaDB%'") val = cursor.fetchone()[0] except: raise else: return bool(val) finally: conn.close() def _get_server_version_info(self, connection): # get database server version info explicitly over the wire # to avoid proxy servers like MaxScale getting in the # way with their own values, see #4205 dbapi_con = connection.connection cursor = dbapi_con.cursor() cursor.execute("SELECT VERSION()") val = cursor.fetchone()[0] cursor.close() if isinstance(val, bytes): val = val.decode() return self._parse_server_version(val) def _parse_server_version(self, val): version = [] is_mariadb = False r = re.compile(r"[.\-+]") tokens = r.split(val) for token in tokens: parsed_token = re.match( r"^(?:(\d+)(?:a|b|c)?|(MariaDB\w*))$", token ) if not parsed_token: continue elif parsed_token.group(2): self._mariadb_normalized_version_info = tuple(version[-3:]) is_mariadb = True else: digit = int(parsed_token.group(1)) version.append(digit) server_version_info = tuple(version) self._set_mariadb( server_version_info and is_mariadb, server_version_info ) if not is_mariadb: self._mariadb_normalized_version_info = server_version_info if server_version_info < (5, 0, 2): raise NotImplementedError( "the MySQL/MariaDB dialect supports server " "version info 5.0.2 and above." ) # setting it here to help w the test suite self.server_version_info = server_version_info return server_version_info def _set_mariadb(self, is_mariadb, server_version_info): if is_mariadb is None: return if not is_mariadb and self.is_mariadb: raise exc.InvalidRequestError( "MySQL version %s is not a MariaDB variant." % (".".join(map(str, server_version_info)),) ) if is_mariadb: if not issubclass(self.preparer, MariaDBIdentifierPreparer): self.preparer = MariaDBIdentifierPreparer # this would have been set by the default dialect already, # so set it again self.identifier_preparer = self.preparer(self) # this will be updated on first connect in initialize() # if using older mariadb version self.delete_returning = True self.insert_returning = True self.is_mariadb = is_mariadb def do_begin_twophase(self, connection, xid): connection.execute(sql.text("XA BEGIN :xid"), dict(xid=xid)) def do_prepare_twophase(self, connection, xid): connection.execute(sql.text("XA END :xid"), dict(xid=xid)) connection.execute(sql.text("XA PREPARE :xid"), dict(xid=xid)) def do_rollback_twophase( self, connection, xid, is_prepared=True, recover=False ): if not is_prepared: connection.execute(sql.text("XA END :xid"), dict(xid=xid)) connection.execute(sql.text("XA ROLLBACK :xid"), dict(xid=xid)) def do_commit_twophase( self, connection, xid, is_prepared=True, recover=False ): if not is_prepared: self.do_prepare_twophase(connection, xid) connection.execute(sql.text("XA COMMIT :xid"), dict(xid=xid)) def do_recover_twophase(self, connection): resultset = connection.exec_driver_sql("XA RECOVER") return [row["data"][0 : row["gtrid_length"]] for row in resultset] def is_disconnect(self, e, connection, cursor): if isinstance( e, ( self.dbapi.OperationalError, self.dbapi.ProgrammingError, self.dbapi.InterfaceError, ), ) and self._extract_error_code(e) in ( 1927, 2006, 2013, 2014, 2045, 2055, 4031, ): return True elif isinstance( e, (self.dbapi.InterfaceError, self.dbapi.InternalError) ): # if underlying connection is closed, # this is the error you get return "(0, '')" in str(e) else: return False def _compat_fetchall(self, rp, charset=None): """Proxy result rows to smooth over MySQL-Python driver inconsistencies.""" return [_DecodingRow(row, charset) for row in rp.fetchall()] def _compat_fetchone(self, rp, charset=None): """Proxy a result row to smooth over MySQL-Python driver inconsistencies.""" row = rp.fetchone() if row: return _DecodingRow(row, charset) else: return None def _compat_first(self, rp, charset=None): """Proxy a result row to smooth over MySQL-Python driver inconsistencies.""" row = rp.first() if row: return _DecodingRow(row, charset) else: return None def _extract_error_code(self, exception): raise NotImplementedError() def _get_default_schema_name(self, connection): return connection.exec_driver_sql("SELECT DATABASE()").scalar() @reflection.cache def has_table(self, connection, table_name, schema=None, **kw): self._ensure_has_table_connection(connection) if schema is None: schema = self.default_schema_name assert schema is not None full_name = ".".join( self.identifier_preparer._quote_free_identifiers( schema, table_name ) ) # DESCRIBE *must* be used because there is no information schema # table that returns information on temp tables that is consistently # available on MariaDB / MySQL / engine-agnostic etc. # therefore we have no choice but to use DESCRIBE and an error catch # to detect "False". See issue #9058 try: with connection.exec_driver_sql( f"DESCRIBE {full_name}", execution_options={"skip_user_error_events": True}, ) as rs: return rs.fetchone() is not None except exc.DBAPIError as e: # https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html # noqa: E501 # there are a lot of codes that *may* pop up here at some point # but we continue to be fairly conservative. We include: # 1146: Table '%s.%s' doesn't exist - what every MySQL has emitted # for decades # # mysql 8 suddenly started emitting: # 1049: Unknown database '%s' - for nonexistent schema # # also added: # 1051: Unknown table '%s' - not known to emit # # there's more "doesn't exist" kinds of messages but they are # less clear if mysql 8 would suddenly start using one of those if self._extract_error_code(e.orig) in (1146, 1049, 1051): return False raise @reflection.cache def has_sequence(self, connection, sequence_name, schema=None, **kw): if not self.supports_sequences: self._sequences_not_supported() if not schema: schema = self.default_schema_name # MariaDB implements sequences as a special type of table # cursor = connection.execute( sql.text( "SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES " "WHERE TABLE_TYPE='SEQUENCE' and TABLE_NAME=:name AND " "TABLE_SCHEMA=:schema_name" ), dict( name=str(sequence_name), schema_name=str(schema), ), ) return cursor.first() is not None def _sequences_not_supported(self): raise NotImplementedError( "Sequences are supported only by the " "MariaDB series 10.3 or greater" ) @reflection.cache def get_sequence_names(self, connection, schema=None, **kw): if not self.supports_sequences: self._sequences_not_supported() if not schema: schema = self.default_schema_name # MariaDB implements sequences as a special type of table cursor = connection.execute( sql.text( "SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES " "WHERE TABLE_TYPE='SEQUENCE' and TABLE_SCHEMA=:schema_name" ), dict(schema_name=schema), ) return [ row[0] for row in self._compat_fetchall( cursor, charset=self._connection_charset ) ] def initialize(self, connection): # this is driver-based, does not need server version info # and is fairly critical for even basic SQL operations self._connection_charset = self._detect_charset(connection) # call super().initialize() because we need to have # server_version_info set up. in 1.4 under python 2 only this does the # "check unicode returns" thing, which is the one area that some # SQL gets compiled within initialize() currently default.DefaultDialect.initialize(self, connection) self._detect_sql_mode(connection) self._detect_ansiquotes(connection) # depends on sql mode self._detect_casing(connection) if self._server_ansiquotes: # if ansiquotes == True, build a new IdentifierPreparer # with the new setting self.identifier_preparer = self.preparer( self, server_ansiquotes=self._server_ansiquotes ) self.supports_sequences = ( self.is_mariadb and self.server_version_info >= (10, 3) ) self.supports_for_update_of = ( self._is_mysql and self.server_version_info >= (8,) ) self._needs_correct_for_88718_96365 = ( not self.is_mariadb and self.server_version_info >= (8,) ) self.delete_returning = ( self.is_mariadb and self.server_version_info >= (10, 0, 5) ) self.insert_returning = ( self.is_mariadb and self.server_version_info >= (10, 5) ) self._requires_alias_for_on_duplicate_key = ( self._is_mysql and self.server_version_info >= (8, 0, 20) ) self._warn_for_known_db_issues() def _warn_for_known_db_issues(self): if self.is_mariadb: mdb_version = self._mariadb_normalized_version_info if mdb_version > (10, 2) and mdb_version < (10, 2, 9): util.warn( "MariaDB %r before 10.2.9 has known issues regarding " "CHECK constraints, which impact handling of NULL values " "with SQLAlchemy's boolean datatype (MDEV-13596). An " "additional issue prevents proper migrations of columns " "with CHECK constraints (MDEV-11114). Please upgrade to " "MariaDB 10.2.9 or greater, or use the MariaDB 10.1 " "series, to avoid these issues." % (mdb_version,) ) @property def _support_float_cast(self): if not self.server_version_info: return False elif self.is_mariadb: # ref https://mariadb.com/kb/en/mariadb-1045-release-notes/ return self.server_version_info >= (10, 4, 5) else: # ref https://dev.mysql.com/doc/relnotes/mysql/8.0/en/news-8-0-17.html#mysqld-8-0-17-feature # noqa return self.server_version_info >= (8, 0, 17) @property def _support_default_function(self): if not self.server_version_info: return False elif self.is_mariadb: # ref https://mariadb.com/kb/en/mariadb-1021-release-notes/ return self.server_version_info >= (10, 2, 1) else: # ref https://dev.mysql.com/doc/refman/8.0/en/data-type-defaults.html # noqa return self.server_version_info >= (8, 0, 13) @property def _is_mariadb(self): return self.is_mariadb @property def _is_mysql(self): return not self.is_mariadb @property def _is_mariadb_102(self): return self.is_mariadb and self._mariadb_normalized_version_info > ( 10, 2, ) @reflection.cache def get_schema_names(self, connection, **kw): rp = connection.exec_driver_sql("SHOW schemas") return [r[0] for r in rp] @reflection.cache def get_table_names(self, connection, schema=None, **kw): """Return a Unicode SHOW TABLES from a given schema.""" if schema is not None: current_schema = schema else: current_schema = self.default_schema_name charset = self._connection_charset rp = connection.exec_driver_sql( "SHOW FULL TABLES FROM %s" % self.identifier_preparer.quote_identifier(current_schema) ) return [ row[0] for row in self._compat_fetchall(rp, charset=charset) if row[1] == "BASE TABLE" ] @reflection.cache def get_view_names(self, connection, schema=None, **kw): if schema is None: schema = self.default_schema_name charset = self._connection_charset rp = connection.exec_driver_sql( "SHOW FULL TABLES FROM %s" % self.identifier_preparer.quote_identifier(schema) ) return [ row[0] for row in self._compat_fetchall(rp, charset=charset) if row[1] in ("VIEW", "SYSTEM VIEW") ] @reflection.cache def get_table_options(self, connection, table_name, schema=None, **kw): parsed_state = self._parsed_state_or_create( connection, table_name, schema, **kw ) if parsed_state.table_options: return parsed_state.table_options else: return ReflectionDefaults.table_options() @reflection.cache def get_columns(self, connection, table_name, schema=None, **kw): parsed_state = self._parsed_state_or_create( connection, table_name, schema, **kw ) if parsed_state.columns: return parsed_state.columns else: return ReflectionDefaults.columns() @reflection.cache def get_pk_constraint(self, connection, table_name, schema=None, **kw): parsed_state = self._parsed_state_or_create( connection, table_name, schema, **kw ) for key in parsed_state.keys: if key["type"] == "PRIMARY": # There can be only one. cols = [s[0] for s in key["columns"]] return {"constrained_columns": cols, "name": None} return ReflectionDefaults.pk_constraint() @reflection.cache def get_foreign_keys(self, connection, table_name, schema=None, **kw): parsed_state = self._parsed_state_or_create( connection, table_name, schema, **kw ) default_schema = None fkeys = [] for spec in parsed_state.fk_constraints: ref_name = spec["table"][-1] ref_schema = len(spec["table"]) > 1 and spec["table"][-2] or schema if not ref_schema: if default_schema is None: default_schema = connection.dialect.default_schema_name if schema == default_schema: ref_schema = schema loc_names = spec["local"] ref_names = spec["foreign"] con_kw = {} for opt in ("onupdate", "ondelete"): if spec.get(opt, False) not in ("NO ACTION", None): con_kw[opt] = spec[opt] fkey_d = { "name": spec["name"], "constrained_columns": loc_names, "referred_schema": ref_schema, "referred_table": ref_name, "referred_columns": ref_names, "options": con_kw, } fkeys.append(fkey_d) if self._needs_correct_for_88718_96365: self._correct_for_mysql_bugs_88718_96365(fkeys, connection) return fkeys if fkeys else ReflectionDefaults.foreign_keys() def _correct_for_mysql_bugs_88718_96365(self, fkeys, connection): # Foreign key is always in lower case (MySQL 8.0) # https://bugs.mysql.com/bug.php?id=88718 # issue #4344 for SQLAlchemy # table name also for MySQL 8.0 # https://bugs.mysql.com/bug.php?id=96365 # issue #4751 for SQLAlchemy # for lower_case_table_names=2, information_schema.columns # preserves the original table/schema casing, but SHOW CREATE # TABLE does not. this problem is not in lower_case_table_names=1, # but use case-insensitive matching for these two modes in any case. if self._casing in (1, 2): def lower(s): return s.lower() else: # if on case sensitive, there can be two tables referenced # with the same name different casing, so we need to use # case-sensitive matching. def lower(s): return s default_schema_name = connection.dialect.default_schema_name # NOTE: using (table_schema, table_name, lower(column_name)) in (...) # is very slow since mysql does not seem able to properly use indexse. # Unpack the where condition instead. schema_by_table_by_column = defaultdict(lambda: defaultdict(list)) for rec in fkeys: sch = lower(rec["referred_schema"] or default_schema_name) tbl = lower(rec["referred_table"]) for col_name in rec["referred_columns"]: schema_by_table_by_column[sch][tbl].append(col_name) if schema_by_table_by_column: condition = sql.or_( *( sql.and_( _info_columns.c.table_schema == schema, sql.or_( *( sql.and_( _info_columns.c.table_name == table, sql.func.lower( _info_columns.c.column_name ).in_(columns), ) for table, columns in tables.items() ) ), ) for schema, tables in schema_by_table_by_column.items() ) ) select = sql.select( _info_columns.c.table_schema, _info_columns.c.table_name, _info_columns.c.column_name, ).where(condition) correct_for_wrong_fk_case = connection.execute(select) # in casing=0, table name and schema name come back in their # exact case. # in casing=1, table name and schema name come back in lower # case. # in casing=2, table name and schema name come back from the # information_schema.columns view in the case # that was used in CREATE DATABASE and CREATE TABLE, but # SHOW CREATE TABLE converts them to *lower case*, therefore # not matching. So for this case, case-insensitive lookup # is necessary d = defaultdict(dict) for schema, tname, cname in correct_for_wrong_fk_case: d[(lower(schema), lower(tname))]["SCHEMANAME"] = schema d[(lower(schema), lower(tname))]["TABLENAME"] = tname d[(lower(schema), lower(tname))][cname.lower()] = cname for fkey in fkeys: rec = d[ ( lower(fkey["referred_schema"] or default_schema_name), lower(fkey["referred_table"]), ) ] fkey["referred_table"] = rec["TABLENAME"] if fkey["referred_schema"] is not None: fkey["referred_schema"] = rec["SCHEMANAME"] fkey["referred_columns"] = [ rec[col.lower()] for col in fkey["referred_columns"] ] @reflection.cache def get_check_constraints(self, connection, table_name, schema=None, **kw): parsed_state = self._parsed_state_or_create( connection, table_name, schema, **kw ) cks = [ {"name": spec["name"], "sqltext": spec["sqltext"]} for spec in parsed_state.ck_constraints ] cks.sort(key=lambda d: d["name"] or "~") # sort None as last return cks if cks else ReflectionDefaults.check_constraints() @reflection.cache def get_table_comment(self, connection, table_name, schema=None, **kw): parsed_state = self._parsed_state_or_create( connection, table_name, schema, **kw ) comment = parsed_state.table_options.get(f"{self.name}_comment", None) if comment is not None: return {"text": comment} else: return ReflectionDefaults.table_comment() @reflection.cache def get_indexes(self, connection, table_name, schema=None, **kw): parsed_state = self._parsed_state_or_create( connection, table_name, schema, **kw ) indexes = [] for spec in parsed_state.keys: dialect_options = {} unique = False flavor = spec["type"] if flavor == "PRIMARY": continue if flavor == "UNIQUE": unique = True elif flavor in ("FULLTEXT", "SPATIAL"): dialect_options["%s_prefix" % self.name] = flavor elif flavor is None: pass else: self.logger.info( "Converting unknown KEY type %s to a plain KEY", flavor ) pass if spec["parser"]: dialect_options["%s_with_parser" % (self.name)] = spec[ "parser" ] index_d = {} index_d["name"] = spec["name"] index_d["column_names"] = [s[0] for s in spec["columns"]] mysql_length = { s[0]: s[1] for s in spec["columns"] if s[1] is not None } if mysql_length: dialect_options["%s_length" % self.name] = mysql_length index_d["unique"] = unique if flavor: index_d["type"] = flavor if dialect_options: index_d["dialect_options"] = dialect_options indexes.append(index_d) indexes.sort(key=lambda d: d["name"] or "~") # sort None as last return indexes if indexes else ReflectionDefaults.indexes() @reflection.cache def get_unique_constraints( self, connection, table_name, schema=None, **kw ): parsed_state = self._parsed_state_or_create( connection, table_name, schema, **kw ) ucs = [ { "name": key["name"], "column_names": [col[0] for col in key["columns"]], "duplicates_index": key["name"], } for key in parsed_state.keys if key["type"] == "UNIQUE" ] ucs.sort(key=lambda d: d["name"] or "~") # sort None as last if ucs: return ucs else: return ReflectionDefaults.unique_constraints() @reflection.cache def get_view_definition(self, connection, view_name, schema=None, **kw): charset = self._connection_charset full_name = ".".join( self.identifier_preparer._quote_free_identifiers(schema, view_name) ) sql = self._show_create_table( connection, None, charset, full_name=full_name ) if sql.upper().startswith("CREATE TABLE"): # it's a table, not a view raise exc.NoSuchTableError(full_name) return sql def _parsed_state_or_create( self, connection, table_name, schema=None, **kw ): return self._setup_parser( connection, table_name, schema, info_cache=kw.get("info_cache", None), ) @util.memoized_property def _tabledef_parser(self): """return the MySQLTableDefinitionParser, generate if needed. The deferred creation ensures that the dialect has retrieved server version information first. """ preparer = self.identifier_preparer return _reflection.MySQLTableDefinitionParser(self, preparer) @reflection.cache def _setup_parser(self, connection, table_name, schema=None, **kw): charset = self._connection_charset parser = self._tabledef_parser full_name = ".".join( self.identifier_preparer._quote_free_identifiers( schema, table_name ) ) sql = self._show_create_table( connection, None, charset, full_name=full_name ) if parser._check_view(sql): # Adapt views to something table-like. columns = self._describe_table( connection, None, charset, full_name=full_name ) sql = parser._describe_to_create(table_name, columns) return parser.parse(sql, charset) def _fetch_setting(self, connection, setting_name): charset = self._connection_charset if self.server_version_info and self.server_version_info < (5, 6): sql = "SHOW VARIABLES LIKE '%s'" % setting_name fetch_col = 1 else: sql = "SELECT @@%s" % setting_name fetch_col = 0 show_var = connection.exec_driver_sql(sql) row = self._compat_first(show_var, charset=charset) if not row: return None else: return row[fetch_col] def _detect_charset(self, connection): raise NotImplementedError() def _detect_casing(self, connection): """Sniff out identifier case sensitivity. Cached per-connection. This value can not change without a server restart. """ # https://dev.mysql.com/doc/refman/en/identifier-case-sensitivity.html setting = self._fetch_setting(connection, "lower_case_table_names") if setting is None: cs = 0 else: # 4.0.15 returns OFF or ON according to [ticket:489] # 3.23 doesn't, 4.0.27 doesn't.. if setting == "OFF": cs = 0 elif setting == "ON": cs = 1 else: cs = int(setting) self._casing = cs return cs def _detect_collations(self, connection): """Pull the active COLLATIONS list from the server. Cached per-connection. """ collations = {} charset = self._connection_charset rs = connection.exec_driver_sql("SHOW COLLATION") for row in self._compat_fetchall(rs, charset): collations[row[0]] = row[1] return collations def _detect_sql_mode(self, connection): setting = self._fetch_setting(connection, "sql_mode") if setting is None: util.warn( "Could not retrieve SQL_MODE; please ensure the " "MySQL user has permissions to SHOW VARIABLES" ) self._sql_mode = "" else: self._sql_mode = setting or "" def _detect_ansiquotes(self, connection): """Detect and adjust for the ANSI_QUOTES sql mode.""" mode = self._sql_mode if not mode: mode = "" elif mode.isdigit(): mode_no = int(mode) mode = (mode_no | 4 == mode_no) and "ANSI_QUOTES" or "" self._server_ansiquotes = "ANSI_QUOTES" in mode # as of MySQL 5.0.1 self._backslash_escapes = "NO_BACKSLASH_ESCAPES" not in mode def _show_create_table( self, connection, table, charset=None, full_name=None ): """Run SHOW CREATE TABLE for a ``Table``.""" if full_name is None: full_name = self.identifier_preparer.format_table(table) st = "SHOW CREATE TABLE %s" % full_name try: rp = connection.execution_options( skip_user_error_events=True ).exec_driver_sql(st) except exc.DBAPIError as e: if self._extract_error_code(e.orig) == 1146: raise exc.NoSuchTableError(full_name) from e else: raise row = self._compat_first(rp, charset=charset) if not row: raise exc.NoSuchTableError(full_name) return row[1].strip() def _describe_table(self, connection, table, charset=None, full_name=None): """Run DESCRIBE for a ``Table`` and return processed rows.""" if full_name is None: full_name = self.identifier_preparer.format_table(table) st = "DESCRIBE %s" % full_name rp, rows = None, None try: try: rp = connection.execution_options( skip_user_error_events=True ).exec_driver_sql(st) except exc.DBAPIError as e: code = self._extract_error_code(e.orig) if code == 1146: raise exc.NoSuchTableError(full_name) from e elif code == 1356: raise exc.UnreflectableTableError( "Table or view named %s could not be " "reflected: %s" % (full_name, e) ) from e else: raise rows = self._compat_fetchall(rp, charset=charset) finally: if rp: rp.close() return rows class _DecodingRow: """Return unicode-decoded values based on type inspection. Smooth over data type issues (esp. with alpha driver versions) and normalize strings as Unicode regardless of user-configured driver encoding settings. """ # Some MySQL-python versions can return some columns as # sets.Set(['value']) (seriously) but thankfully that doesn't # seem to come up in DDL queries. _encoding_compat = { "koi8r": "koi8_r", "koi8u": "koi8_u", "utf16": "utf-16-be", # MySQL's uft16 is always bigendian "utf8mb4": "utf8", # real utf8 "utf8mb3": "utf8", # real utf8; saw this happen on CI but I cannot # reproduce, possibly mariadb10.6 related "eucjpms": "ujis", } def __init__(self, rowproxy, charset): self.rowproxy = rowproxy self.charset = self._encoding_compat.get(charset, charset) def __getitem__(self, index): item = self.rowproxy[index] if isinstance(item, _array): item = item.tostring() if self.charset and isinstance(item, bytes): return item.decode(self.charset) else: return item def __getattr__(self, attr): item = getattr(self.rowproxy, attr) if isinstance(item, _array): item = item.tostring() if self.charset and isinstance(item, bytes): return item.decode(self.charset) else: return item _info_columns = sql.table( "columns", sql.column("table_schema", VARCHAR(64)), sql.column("table_name", VARCHAR(64)), sql.column("column_name", VARCHAR(64)), schema="information_schema", ) sqlalchemy/dialects/mysql/enumerated.py 0000755 00000020377 15125143220 0014355 0 ustar 00 # dialects/mysql/enumerated.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors import re from .types import _StringType from ... import exc from ... import sql from ... import util from ...sql import sqltypes class ENUM(sqltypes.NativeForEmulated, sqltypes.Enum, _StringType): """MySQL ENUM type.""" __visit_name__ = "ENUM" native_enum = True def __init__(self, *enums, **kw): """Construct an ENUM. E.g.:: Column("myenum", ENUM("foo", "bar", "baz")) :param enums: The range of valid values for this ENUM. Values in enums are not quoted, they will be escaped and surrounded by single quotes when generating the schema. This object may also be a PEP-435-compliant enumerated type. .. versionadded: 1.1 added support for PEP-435-compliant enumerated types. :param strict: This flag has no effect. .. versionchanged:: The MySQL ENUM type as well as the base Enum type now validates all Python data values. :param charset: Optional, a column-level character set for this string value. Takes precedence to 'ascii' or 'unicode' short-hand. :param collation: Optional, a column-level collation for this string value. Takes precedence to 'binary' short-hand. :param ascii: Defaults to False: short-hand for the ``latin1`` character set, generates ASCII in schema. :param unicode: Defaults to False: short-hand for the ``ucs2`` character set, generates UNICODE in schema. :param binary: Defaults to False: short-hand, pick the binary collation type that matches the column's character set. Generates BINARY in schema. This does not affect the type of data stored, only the collation of character data. """ kw.pop("strict", None) self._enum_init(enums, kw) _StringType.__init__(self, length=self.length, **kw) @classmethod def adapt_emulated_to_native(cls, impl, **kw): """Produce a MySQL native :class:`.mysql.ENUM` from plain :class:`.Enum`. """ kw.setdefault("validate_strings", impl.validate_strings) kw.setdefault("values_callable", impl.values_callable) kw.setdefault("omit_aliases", impl._omit_aliases) return cls(**kw) def _object_value_for_elem(self, elem): # mysql sends back a blank string for any value that # was persisted that was not in the enums; that is, it does no # validation on the incoming data, it "truncates" it to be # the blank string. Return it straight. if elem == "": return elem else: return super()._object_value_for_elem(elem) def __repr__(self): return util.generic_repr( self, to_inspect=[ENUM, _StringType, sqltypes.Enum] ) class SET(_StringType): """MySQL SET type.""" __visit_name__ = "SET" def __init__(self, *values, **kw): """Construct a SET. E.g.:: Column("myset", SET("foo", "bar", "baz")) The list of potential values is required in the case that this set will be used to generate DDL for a table, or if the :paramref:`.SET.retrieve_as_bitwise` flag is set to True. :param values: The range of valid values for this SET. The values are not quoted, they will be escaped and surrounded by single quotes when generating the schema. :param convert_unicode: Same flag as that of :paramref:`.String.convert_unicode`. :param collation: same as that of :paramref:`.String.collation` :param charset: same as that of :paramref:`.VARCHAR.charset`. :param ascii: same as that of :paramref:`.VARCHAR.ascii`. :param unicode: same as that of :paramref:`.VARCHAR.unicode`. :param binary: same as that of :paramref:`.VARCHAR.binary`. :param retrieve_as_bitwise: if True, the data for the set type will be persisted and selected using an integer value, where a set is coerced into a bitwise mask for persistence. MySQL allows this mode which has the advantage of being able to store values unambiguously, such as the blank string ``''``. The datatype will appear as the expression ``col + 0`` in a SELECT statement, so that the value is coerced into an integer value in result sets. This flag is required if one wishes to persist a set that can store the blank string ``''`` as a value. .. warning:: When using :paramref:`.mysql.SET.retrieve_as_bitwise`, it is essential that the list of set values is expressed in the **exact same order** as exists on the MySQL database. """ self.retrieve_as_bitwise = kw.pop("retrieve_as_bitwise", False) self.values = tuple(values) if not self.retrieve_as_bitwise and "" in values: raise exc.ArgumentError( "Can't use the blank value '' in a SET without " "setting retrieve_as_bitwise=True" ) if self.retrieve_as_bitwise: self._bitmap = { value: 2**idx for idx, value in enumerate(self.values) } self._bitmap.update( (2**idx, value) for idx, value in enumerate(self.values) ) length = max([len(v) for v in values] + [0]) kw.setdefault("length", length) super().__init__(**kw) def column_expression(self, colexpr): if self.retrieve_as_bitwise: return sql.type_coerce( sql.type_coerce(colexpr, sqltypes.Integer) + 0, self ) else: return colexpr def result_processor(self, dialect, coltype): if self.retrieve_as_bitwise: def process(value): if value is not None: value = int(value) return set(util.map_bits(self._bitmap.__getitem__, value)) else: return None else: super_convert = super().result_processor(dialect, coltype) def process(value): if isinstance(value, str): # MySQLdb returns a string, let's parse if super_convert: value = super_convert(value) return set(re.findall(r"[^,]+", value)) else: # mysql-connector-python does a naive # split(",") which throws in an empty string if value is not None: value.discard("") return value return process def bind_processor(self, dialect): super_convert = super().bind_processor(dialect) if self.retrieve_as_bitwise: def process(value): if value is None: return None elif isinstance(value, (int, str)): if super_convert: return super_convert(value) else: return value else: int_value = 0 for v in value: int_value |= self._bitmap[v] return int_value else: def process(value): # accept strings and int (actually bitflag) values directly if value is not None and not isinstance(value, (int, str)): value = ",".join(value) if super_convert: return super_convert(value) else: return value return process def adapt(self, impltype, **kw): kw["retrieve_as_bitwise"] = self.retrieve_as_bitwise return util.constructor_copy(self, impltype, *self.values, **kw) def __repr__(self): return util.generic_repr( self, to_inspect=[SET, _StringType], additional_kw=[ ("retrieve_as_bitwise", False), ], ) sqlalchemy/dialects/mysql/mysqldb.py 0000755 00000022466 15125143220 0013700 0 ustar 00 # dialects/mysql/mysqldb.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors """ .. dialect:: mysql+mysqldb :name: mysqlclient (maintained fork of MySQL-Python) :dbapi: mysqldb :connectstring: mysql+mysqldb://<user>:<password>@<host>[:<port>]/<dbname> :url: https://pypi.org/project/mysqlclient/ Driver Status ------------- The mysqlclient DBAPI is a maintained fork of the `MySQL-Python <https://sourceforge.net/projects/mysql-python>`_ DBAPI that is no longer maintained. `mysqlclient`_ supports Python 2 and Python 3 and is very stable. .. _mysqlclient: https://github.com/PyMySQL/mysqlclient-python .. _mysqldb_unicode: Unicode ------- Please see :ref:`mysql_unicode` for current recommendations on unicode handling. .. _mysqldb_ssl: SSL Connections ---------------- The mysqlclient and PyMySQL DBAPIs accept an additional dictionary under the key "ssl", which may be specified using the :paramref:`_sa.create_engine.connect_args` dictionary:: engine = create_engine( "mysql+mysqldb://scott:tiger@192.168.0.134/test", connect_args={ "ssl": { "ca": "/home/gord/client-ssl/ca.pem", "cert": "/home/gord/client-ssl/client-cert.pem", "key": "/home/gord/client-ssl/client-key.pem", } }, ) For convenience, the following keys may also be specified inline within the URL where they will be interpreted into the "ssl" dictionary automatically: "ssl_ca", "ssl_cert", "ssl_key", "ssl_capath", "ssl_cipher", "ssl_check_hostname". An example is as follows:: connection_uri = ( "mysql+mysqldb://scott:tiger@192.168.0.134/test" "?ssl_ca=/home/gord/client-ssl/ca.pem" "&ssl_cert=/home/gord/client-ssl/client-cert.pem" "&ssl_key=/home/gord/client-ssl/client-key.pem" ) .. seealso:: :ref:`pymysql_ssl` in the PyMySQL dialect Using MySQLdb with Google Cloud SQL ----------------------------------- Google Cloud SQL now recommends use of the MySQLdb dialect. Connect using a URL like the following: .. sourcecode:: text mysql+mysqldb://root@/<dbname>?unix_socket=/cloudsql/<projectid>:<instancename> Server Side Cursors ------------------- The mysqldb dialect supports server-side cursors. See :ref:`mysql_ss_cursors`. """ import re from .base import MySQLCompiler from .base import MySQLDialect from .base import MySQLExecutionContext from .base import MySQLIdentifierPreparer from .base import TEXT from ... import sql from ... import util class MySQLExecutionContext_mysqldb(MySQLExecutionContext): pass class MySQLCompiler_mysqldb(MySQLCompiler): pass class MySQLDialect_mysqldb(MySQLDialect): driver = "mysqldb" supports_statement_cache = True supports_unicode_statements = True supports_sane_rowcount = True supports_sane_multi_rowcount = True supports_native_decimal = True default_paramstyle = "format" execution_ctx_cls = MySQLExecutionContext_mysqldb statement_compiler = MySQLCompiler_mysqldb preparer = MySQLIdentifierPreparer def __init__(self, **kwargs): super().__init__(**kwargs) self._mysql_dbapi_version = ( self._parse_dbapi_version(self.dbapi.__version__) if self.dbapi is not None and hasattr(self.dbapi, "__version__") else (0, 0, 0) ) def _parse_dbapi_version(self, version): m = re.match(r"(\d+)\.(\d+)(?:\.(\d+))?", version) if m: return tuple(int(x) for x in m.group(1, 2, 3) if x is not None) else: return (0, 0, 0) @util.langhelpers.memoized_property def supports_server_side_cursors(self): try: cursors = __import__("MySQLdb.cursors").cursors self._sscursor = cursors.SSCursor return True except (ImportError, AttributeError): return False @classmethod def import_dbapi(cls): return __import__("MySQLdb") def on_connect(self): super_ = super().on_connect() def on_connect(conn): if super_ is not None: super_(conn) charset_name = conn.character_set_name() if charset_name is not None: cursor = conn.cursor() cursor.execute("SET NAMES %s" % charset_name) cursor.close() return on_connect def do_ping(self, dbapi_connection): dbapi_connection.ping() return True def do_executemany(self, cursor, statement, parameters, context=None): rowcount = cursor.executemany(statement, parameters) if context is not None: context._rowcount = rowcount def _check_unicode_returns(self, connection): # work around issue fixed in # https://github.com/farcepest/MySQLdb1/commit/cd44524fef63bd3fcb71947392326e9742d520e8 # specific issue w/ the utf8mb4_bin collation and unicode returns collation = connection.exec_driver_sql( "show collation where %s = 'utf8mb4' and %s = 'utf8mb4_bin'" % ( self.identifier_preparer.quote("Charset"), self.identifier_preparer.quote("Collation"), ) ).scalar() has_utf8mb4_bin = self.server_version_info > (5,) and collation if has_utf8mb4_bin: additional_tests = [ sql.collate( sql.cast( sql.literal_column("'test collated returns'"), TEXT(charset="utf8mb4"), ), "utf8mb4_bin", ) ] else: additional_tests = [] return super()._check_unicode_returns(connection, additional_tests) def create_connect_args(self, url, _translate_args=None): if _translate_args is None: _translate_args = dict( database="db", username="user", password="passwd" ) opts = url.translate_connect_args(**_translate_args) opts.update(url.query) util.coerce_kw_type(opts, "compress", bool) util.coerce_kw_type(opts, "connect_timeout", int) util.coerce_kw_type(opts, "read_timeout", int) util.coerce_kw_type(opts, "write_timeout", int) util.coerce_kw_type(opts, "client_flag", int) util.coerce_kw_type(opts, "local_infile", bool) # Note: using either of the below will cause all strings to be # returned as Unicode, both in raw SQL operations and with column # types like String and MSString. util.coerce_kw_type(opts, "use_unicode", bool) util.coerce_kw_type(opts, "charset", str) # Rich values 'cursorclass' and 'conv' are not supported via # query string. ssl = {} keys = [ ("ssl_ca", str), ("ssl_key", str), ("ssl_cert", str), ("ssl_capath", str), ("ssl_cipher", str), ("ssl_check_hostname", bool), ] for key, kw_type in keys: if key in opts: ssl[key[4:]] = opts[key] util.coerce_kw_type(ssl, key[4:], kw_type) del opts[key] if ssl: opts["ssl"] = ssl # FOUND_ROWS must be set in CLIENT_FLAGS to enable # supports_sane_rowcount. client_flag = opts.get("client_flag", 0) client_flag_found_rows = self._found_rows_client_flag() if client_flag_found_rows is not None: client_flag |= client_flag_found_rows opts["client_flag"] = client_flag return [[], opts] def _found_rows_client_flag(self): if self.dbapi is not None: try: CLIENT_FLAGS = __import__( self.dbapi.__name__ + ".constants.CLIENT" ).constants.CLIENT except (AttributeError, ImportError): return None else: return CLIENT_FLAGS.FOUND_ROWS else: return None def _extract_error_code(self, exception): return exception.args[0] def _detect_charset(self, connection): """Sniff out the character set in use for connection results.""" try: # note: the SQL here would be # "SHOW VARIABLES LIKE 'character_set%%'" cset_name = connection.connection.character_set_name except AttributeError: util.warn( "No 'character_set_name' can be detected with " "this MySQL-Python version; " "please upgrade to a recent version of MySQL-Python. " "Assuming latin1." ) return "latin1" else: return cset_name() def get_isolation_level_values(self, dbapi_connection): return ( "SERIALIZABLE", "READ UNCOMMITTED", "READ COMMITTED", "REPEATABLE READ", "AUTOCOMMIT", ) def set_isolation_level(self, dbapi_connection, level): if level == "AUTOCOMMIT": dbapi_connection.autocommit(True) else: dbapi_connection.autocommit(False) super().set_isolation_level(dbapi_connection, level) dialect = MySQLDialect_mysqldb sqlalchemy/dialects/mysql/json.py 0000755 00000004335 15125143220 0013171 0 ustar 00 # dialects/mysql/json.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors from ... import types as sqltypes class JSON(sqltypes.JSON): """MySQL JSON type. MySQL supports JSON as of version 5.7. MariaDB supports JSON (as an alias for LONGTEXT) as of version 10.2. :class:`_mysql.JSON` is used automatically whenever the base :class:`_types.JSON` datatype is used against a MySQL or MariaDB backend. .. seealso:: :class:`_types.JSON` - main documentation for the generic cross-platform JSON datatype. The :class:`.mysql.JSON` type supports persistence of JSON values as well as the core index operations provided by :class:`_types.JSON` datatype, by adapting the operations to render the ``JSON_EXTRACT`` function at the database level. """ pass class _FormatTypeMixin: def _format_value(self, value): raise NotImplementedError() def bind_processor(self, dialect): super_proc = self.string_bind_processor(dialect) def process(value): value = self._format_value(value) if super_proc: value = super_proc(value) return value return process def literal_processor(self, dialect): super_proc = self.string_literal_processor(dialect) def process(value): value = self._format_value(value) if super_proc: value = super_proc(value) return value return process class JSONIndexType(_FormatTypeMixin, sqltypes.JSON.JSONIndexType): def _format_value(self, value): if isinstance(value, int): value = "$[%s]" % value else: value = '$."%s"' % value return value class JSONPathType(_FormatTypeMixin, sqltypes.JSON.JSONPathType): def _format_value(self, value): return "$%s" % ( "".join( [ "[%s]" % elem if isinstance(elem, int) else '."%s"' % elem for elem in value ] ) ) sqlalchemy/dialects/mysql/provision.py 0000755 00000007206 15125143220 0014250 0 ustar 00 # dialects/mysql/provision.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors from ... import exc from ...testing.provision import configure_follower from ...testing.provision import create_db from ...testing.provision import drop_db from ...testing.provision import generate_driver_url from ...testing.provision import temp_table_keyword_args from ...testing.provision import upsert @generate_driver_url.for_db("mysql", "mariadb") def generate_driver_url(url, driver, query_str): backend = url.get_backend_name() # NOTE: at the moment, tests are running mariadbconnector # against both mariadb and mysql backends. if we want this to be # limited, do the decision making here to reject a "mysql+mariadbconnector" # URL. Optionally also re-enable the module level # MySQLDialect_mariadbconnector.is_mysql flag as well, which must include # a unit and/or functional test. # all the Jenkins tests have been running mysqlclient Python library # built against mariadb client drivers for years against all MySQL / # MariaDB versions going back to MySQL 5.6, currently they can talk # to MySQL databases without problems. if backend == "mysql": dialect_cls = url.get_dialect() if dialect_cls._is_mariadb_from_url(url): backend = "mariadb" new_url = url.set( drivername="%s+%s" % (backend, driver) ).update_query_string(query_str) if driver == "mariadbconnector": new_url = new_url.difference_update_query(["charset"]) elif driver == "mysqlconnector": new_url = new_url.update_query_pairs( [("collation", "utf8mb4_general_ci")] ) try: new_url.get_dialect() except exc.NoSuchModuleError: return None else: return new_url @create_db.for_db("mysql", "mariadb") def _mysql_create_db(cfg, eng, ident): with eng.begin() as conn: try: _mysql_drop_db(cfg, conn, ident) except Exception: pass with eng.begin() as conn: conn.exec_driver_sql( "CREATE DATABASE %s CHARACTER SET utf8mb4" % ident ) conn.exec_driver_sql( "CREATE DATABASE %s_test_schema CHARACTER SET utf8mb4" % ident ) conn.exec_driver_sql( "CREATE DATABASE %s_test_schema_2 CHARACTER SET utf8mb4" % ident ) @configure_follower.for_db("mysql", "mariadb") def _mysql_configure_follower(config, ident): config.test_schema = "%s_test_schema" % ident config.test_schema_2 = "%s_test_schema_2" % ident @drop_db.for_db("mysql", "mariadb") def _mysql_drop_db(cfg, eng, ident): with eng.begin() as conn: conn.exec_driver_sql("DROP DATABASE %s_test_schema" % ident) conn.exec_driver_sql("DROP DATABASE %s_test_schema_2" % ident) conn.exec_driver_sql("DROP DATABASE %s" % ident) @temp_table_keyword_args.for_db("mysql", "mariadb") def _mysql_temp_table_keyword_args(cfg, eng): return {"prefixes": ["TEMPORARY"]} @upsert.for_db("mariadb") def _upsert( cfg, table, returning, *, set_lambda=None, sort_by_parameter_order=False ): from sqlalchemy.dialects.mysql import insert stmt = insert(table) if set_lambda: stmt = stmt.on_duplicate_key_update(**set_lambda(stmt.inserted)) else: pk1 = table.primary_key.c[0] stmt = stmt.on_duplicate_key_update({pk1.key: pk1}) stmt = stmt.returning( *returning, sort_by_parameter_order=sort_by_parameter_order ) return stmt sqlalchemy/dialects/mysql/pymysql.py 0000755 00000007762 15125143220 0013745 0 ustar 00 # dialects/mysql/pymysql.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors r""" .. dialect:: mysql+pymysql :name: PyMySQL :dbapi: pymysql :connectstring: mysql+pymysql://<username>:<password>@<host>/<dbname>[?<options>] :url: https://pymysql.readthedocs.io/ Unicode ------- Please see :ref:`mysql_unicode` for current recommendations on unicode handling. .. _pymysql_ssl: SSL Connections ------------------ The PyMySQL DBAPI accepts the same SSL arguments as that of MySQLdb, described at :ref:`mysqldb_ssl`. See that section for additional examples. If the server uses an automatically-generated certificate that is self-signed or does not match the host name (as seen from the client), it may also be necessary to indicate ``ssl_check_hostname=false`` in PyMySQL:: connection_uri = ( "mysql+pymysql://scott:tiger@192.168.0.134/test" "?ssl_ca=/home/gord/client-ssl/ca.pem" "&ssl_cert=/home/gord/client-ssl/client-cert.pem" "&ssl_key=/home/gord/client-ssl/client-key.pem" "&ssl_check_hostname=false" ) MySQL-Python Compatibility -------------------------- The pymysql DBAPI is a pure Python port of the MySQL-python (MySQLdb) driver, and targets 100% compatibility. Most behavioral notes for MySQL-python apply to the pymysql driver as well. """ # noqa from .mysqldb import MySQLDialect_mysqldb from ...util import langhelpers class MySQLDialect_pymysql(MySQLDialect_mysqldb): driver = "pymysql" supports_statement_cache = True description_encoding = None @langhelpers.memoized_property def supports_server_side_cursors(self): try: cursors = __import__("pymysql.cursors").cursors self._sscursor = cursors.SSCursor return True except (ImportError, AttributeError): return False @classmethod def import_dbapi(cls): return __import__("pymysql") @langhelpers.memoized_property def _send_false_to_ping(self): """determine if pymysql has deprecated, changed the default of, or removed the 'reconnect' argument of connection.ping(). See #10492 and https://github.com/PyMySQL/mysqlclient/discussions/651#discussioncomment-7308971 for background. """ # noqa: E501 try: Connection = __import__( "pymysql.connections" ).connections.Connection except (ImportError, AttributeError): return True else: insp = langhelpers.get_callable_argspec(Connection.ping) try: reconnect_arg = insp.args[1] except IndexError: return False else: return reconnect_arg == "reconnect" and ( not insp.defaults or insp.defaults[0] is not False ) def do_ping(self, dbapi_connection): if self._send_false_to_ping: dbapi_connection.ping(False) else: dbapi_connection.ping() return True def create_connect_args(self, url, _translate_args=None): if _translate_args is None: _translate_args = dict(username="user") return super().create_connect_args( url, _translate_args=_translate_args ) def is_disconnect(self, e, connection, cursor): if super().is_disconnect(e, connection, cursor): return True elif isinstance(e, self.dbapi.Error): str_e = str(e).lower() return ( "already closed" in str_e or "connection was killed" in str_e ) else: return False def _extract_error_code(self, exception): if isinstance(exception.args[0], Exception): exception = exception.args[0] return exception.args[0] dialect = MySQLDialect_pymysql sqlalchemy/dialects/mysql/mariadbconnector.py 0000755 00000020657 15125143220 0015537 0 ustar 00 # dialects/mysql/mariadbconnector.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors """ .. dialect:: mysql+mariadbconnector :name: MariaDB Connector/Python :dbapi: mariadb :connectstring: mariadb+mariadbconnector://<user>:<password>@<host>[:<port>]/<dbname> :url: https://pypi.org/project/mariadb/ Driver Status ------------- MariaDB Connector/Python enables Python programs to access MariaDB and MySQL databases using an API which is compliant with the Python DB API 2.0 (PEP-249). It is written in C and uses MariaDB Connector/C client library for client server communication. Note that the default driver for a ``mariadb://`` connection URI continues to be ``mysqldb``. ``mariadb+mariadbconnector://`` is required to use this driver. .. mariadb: https://github.com/mariadb-corporation/mariadb-connector-python """ # noqa import re from uuid import UUID as _python_UUID from .base import MySQLCompiler from .base import MySQLDialect from .base import MySQLExecutionContext from ... import sql from ... import util from ...sql import sqltypes mariadb_cpy_minimum_version = (1, 0, 1) class _MariaDBUUID(sqltypes.UUID[sqltypes._UUID_RETURN]): # work around JIRA issue # https://jira.mariadb.org/browse/CONPY-270. When that issue is fixed, # this type can be removed. def result_processor(self, dialect, coltype): if self.as_uuid: def process(value): if value is not None: if hasattr(value, "decode"): value = value.decode("ascii") value = _python_UUID(value) return value return process else: def process(value): if value is not None: if hasattr(value, "decode"): value = value.decode("ascii") value = str(_python_UUID(value)) return value return process class MySQLExecutionContext_mariadbconnector(MySQLExecutionContext): _lastrowid = None def create_server_side_cursor(self): return self._dbapi_connection.cursor(buffered=False) def create_default_cursor(self): return self._dbapi_connection.cursor(buffered=True) def post_exec(self): super().post_exec() self._rowcount = self.cursor.rowcount if self.isinsert and self.compiled.postfetch_lastrowid: self._lastrowid = self.cursor.lastrowid def get_lastrowid(self): return self._lastrowid class MySQLCompiler_mariadbconnector(MySQLCompiler): pass class MySQLDialect_mariadbconnector(MySQLDialect): driver = "mariadbconnector" supports_statement_cache = True # set this to True at the module level to prevent the driver from running # against a backend that server detects as MySQL. currently this appears to # be unnecessary as MariaDB client libraries have always worked against # MySQL databases. However, if this changes at some point, this can be # adjusted, but PLEASE ADD A TEST in test/dialect/mysql/test_dialect.py if # this change is made at some point to ensure the correct exception # is raised at the correct point when running the driver against # a MySQL backend. # is_mariadb = True supports_unicode_statements = True encoding = "utf8mb4" convert_unicode = True supports_sane_rowcount = True supports_sane_multi_rowcount = True supports_native_decimal = True default_paramstyle = "qmark" execution_ctx_cls = MySQLExecutionContext_mariadbconnector statement_compiler = MySQLCompiler_mariadbconnector supports_server_side_cursors = True colspecs = util.update_copy( MySQLDialect.colspecs, {sqltypes.Uuid: _MariaDBUUID} ) @util.memoized_property def _dbapi_version(self): if self.dbapi and hasattr(self.dbapi, "__version__"): return tuple( [ int(x) for x in re.findall( r"(\d+)(?:[-\.]?|$)", self.dbapi.__version__ ) ] ) else: return (99, 99, 99) def __init__(self, **kwargs): super().__init__(**kwargs) self.paramstyle = "qmark" if self.dbapi is not None: if self._dbapi_version < mariadb_cpy_minimum_version: raise NotImplementedError( "The minimum required version for MariaDB " "Connector/Python is %s" % ".".join(str(x) for x in mariadb_cpy_minimum_version) ) @classmethod def import_dbapi(cls): return __import__("mariadb") def is_disconnect(self, e, connection, cursor): if super().is_disconnect(e, connection, cursor): return True elif isinstance(e, self.dbapi.Error): str_e = str(e).lower() return "not connected" in str_e or "isn't valid" in str_e else: return False def create_connect_args(self, url): opts = url.translate_connect_args() opts.update(url.query) int_params = [ "connect_timeout", "read_timeout", "write_timeout", "client_flag", "port", "pool_size", ] bool_params = [ "local_infile", "ssl_verify_cert", "ssl", "pool_reset_connection", "compress", ] for key in int_params: util.coerce_kw_type(opts, key, int) for key in bool_params: util.coerce_kw_type(opts, key, bool) # FOUND_ROWS must be set in CLIENT_FLAGS to enable # supports_sane_rowcount. client_flag = opts.get("client_flag", 0) if self.dbapi is not None: try: CLIENT_FLAGS = __import__( self.dbapi.__name__ + ".constants.CLIENT" ).constants.CLIENT client_flag |= CLIENT_FLAGS.FOUND_ROWS except (AttributeError, ImportError): self.supports_sane_rowcount = False opts["client_flag"] = client_flag return [[], opts] def _extract_error_code(self, exception): try: rc = exception.errno except: rc = -1 return rc def _detect_charset(self, connection): return "utf8mb4" def get_isolation_level_values(self, dbapi_connection): return ( "SERIALIZABLE", "READ UNCOMMITTED", "READ COMMITTED", "REPEATABLE READ", "AUTOCOMMIT", ) def set_isolation_level(self, connection, level): if level == "AUTOCOMMIT": connection.autocommit = True else: connection.autocommit = False super().set_isolation_level(connection, level) def do_begin_twophase(self, connection, xid): connection.execute( sql.text("XA BEGIN :xid").bindparams( sql.bindparam("xid", xid, literal_execute=True) ) ) def do_prepare_twophase(self, connection, xid): connection.execute( sql.text("XA END :xid").bindparams( sql.bindparam("xid", xid, literal_execute=True) ) ) connection.execute( sql.text("XA PREPARE :xid").bindparams( sql.bindparam("xid", xid, literal_execute=True) ) ) def do_rollback_twophase( self, connection, xid, is_prepared=True, recover=False ): if not is_prepared: connection.execute( sql.text("XA END :xid").bindparams( sql.bindparam("xid", xid, literal_execute=True) ) ) connection.execute( sql.text("XA ROLLBACK :xid").bindparams( sql.bindparam("xid", xid, literal_execute=True) ) ) def do_commit_twophase( self, connection, xid, is_prepared=True, recover=False ): if not is_prepared: self.do_prepare_twophase(connection, xid) connection.execute( sql.text("XA COMMIT :xid").bindparams( sql.bindparam("xid", xid, literal_execute=True) ) ) dialect = MySQLDialect_mariadbconnector sqlalchemy/dialects/mysql/aiomysql.py 0000755 00000023435 15125143220 0014060 0 ustar 00 # dialects/mysql/aiomysql.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors <see AUTHORS # file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors r""" .. dialect:: mysql+aiomysql :name: aiomysql :dbapi: aiomysql :connectstring: mysql+aiomysql://user:password@host:port/dbname[?key=value&key=value...] :url: https://github.com/aio-libs/aiomysql The aiomysql dialect is SQLAlchemy's second Python asyncio dialect. Using a special asyncio mediation layer, the aiomysql dialect is usable as the backend for the :ref:`SQLAlchemy asyncio <asyncio_toplevel>` extension package. This dialect should normally be used only with the :func:`_asyncio.create_async_engine` engine creation function:: from sqlalchemy.ext.asyncio import create_async_engine engine = create_async_engine( "mysql+aiomysql://user:pass@hostname/dbname?charset=utf8mb4" ) """ # noqa from collections import deque from .pymysql import MySQLDialect_pymysql from ... import pool from ... import util from ...engine import AdaptedConnection from ...util.concurrency import asyncio from ...util.concurrency import await_fallback from ...util.concurrency import await_only class AsyncAdapt_aiomysql_cursor: # TODO: base on connectors/asyncio.py # see #10415 server_side = False __slots__ = ( "_adapt_connection", "_connection", "await_", "_cursor", "_rows", ) def __init__(self, adapt_connection): self._adapt_connection = adapt_connection self._connection = adapt_connection._connection self.await_ = adapt_connection.await_ cursor = self._connection.cursor(adapt_connection.dbapi.Cursor) # see https://github.com/aio-libs/aiomysql/issues/543 self._cursor = self.await_(cursor.__aenter__()) self._rows = deque() @property def description(self): return self._cursor.description @property def rowcount(self): return self._cursor.rowcount @property def arraysize(self): return self._cursor.arraysize @arraysize.setter def arraysize(self, value): self._cursor.arraysize = value @property def lastrowid(self): return self._cursor.lastrowid def close(self): # note we aren't actually closing the cursor here, # we are just letting GC do it. to allow this to be async # we would need the Result to change how it does "Safe close cursor". # MySQL "cursors" don't actually have state to be "closed" besides # exhausting rows, which we already have done for sync cursor. # another option would be to emulate aiosqlite dialect and assign # cursor only if we are doing server side cursor operation. self._rows.clear() def execute(self, operation, parameters=None): return self.await_(self._execute_async(operation, parameters)) def executemany(self, operation, seq_of_parameters): return self.await_( self._executemany_async(operation, seq_of_parameters) ) async def _execute_async(self, operation, parameters): async with self._adapt_connection._execute_mutex: result = await self._cursor.execute(operation, parameters) if not self.server_side: # aiomysql has a "fake" async result, so we have to pull it out # of that here since our default result is not async. # we could just as easily grab "_rows" here and be done with it # but this is safer. self._rows = deque(await self._cursor.fetchall()) return result async def _executemany_async(self, operation, seq_of_parameters): async with self._adapt_connection._execute_mutex: return await self._cursor.executemany(operation, seq_of_parameters) def setinputsizes(self, *inputsizes): pass def __iter__(self): while self._rows: yield self._rows.popleft() def fetchone(self): if self._rows: return self._rows.popleft() else: return None def fetchmany(self, size=None): if size is None: size = self.arraysize rr = self._rows return [rr.popleft() for _ in range(min(size, len(rr)))] def fetchall(self): retval = list(self._rows) self._rows.clear() return retval class AsyncAdapt_aiomysql_ss_cursor(AsyncAdapt_aiomysql_cursor): # TODO: base on connectors/asyncio.py # see #10415 __slots__ = () server_side = True def __init__(self, adapt_connection): self._adapt_connection = adapt_connection self._connection = adapt_connection._connection self.await_ = adapt_connection.await_ cursor = self._connection.cursor(adapt_connection.dbapi.SSCursor) self._cursor = self.await_(cursor.__aenter__()) def close(self): if self._cursor is not None: self.await_(self._cursor.close()) self._cursor = None def fetchone(self): return self.await_(self._cursor.fetchone()) def fetchmany(self, size=None): return self.await_(self._cursor.fetchmany(size=size)) def fetchall(self): return self.await_(self._cursor.fetchall()) class AsyncAdapt_aiomysql_connection(AdaptedConnection): # TODO: base on connectors/asyncio.py # see #10415 await_ = staticmethod(await_only) __slots__ = ("dbapi", "_execute_mutex") def __init__(self, dbapi, connection): self.dbapi = dbapi self._connection = connection self._execute_mutex = asyncio.Lock() def ping(self, reconnect): return self.await_(self._connection.ping(reconnect)) def character_set_name(self): return self._connection.character_set_name() def autocommit(self, value): self.await_(self._connection.autocommit(value)) def cursor(self, server_side=False): if server_side: return AsyncAdapt_aiomysql_ss_cursor(self) else: return AsyncAdapt_aiomysql_cursor(self) def rollback(self): self.await_(self._connection.rollback()) def commit(self): self.await_(self._connection.commit()) def terminate(self): # it's not awaitable. self._connection.close() def close(self) -> None: self.await_(self._connection.ensure_closed()) class AsyncAdaptFallback_aiomysql_connection(AsyncAdapt_aiomysql_connection): # TODO: base on connectors/asyncio.py # see #10415 __slots__ = () await_ = staticmethod(await_fallback) class AsyncAdapt_aiomysql_dbapi: def __init__(self, aiomysql, pymysql): self.aiomysql = aiomysql self.pymysql = pymysql self.paramstyle = "format" self._init_dbapi_attributes() self.Cursor, self.SSCursor = self._init_cursors_subclasses() def _init_dbapi_attributes(self): for name in ( "Warning", "Error", "InterfaceError", "DataError", "DatabaseError", "OperationalError", "InterfaceError", "IntegrityError", "ProgrammingError", "InternalError", "NotSupportedError", ): setattr(self, name, getattr(self.aiomysql, name)) for name in ( "NUMBER", "STRING", "DATETIME", "BINARY", "TIMESTAMP", "Binary", ): setattr(self, name, getattr(self.pymysql, name)) def connect(self, *arg, **kw): async_fallback = kw.pop("async_fallback", False) creator_fn = kw.pop("async_creator_fn", self.aiomysql.connect) if util.asbool(async_fallback): return AsyncAdaptFallback_aiomysql_connection( self, await_fallback(creator_fn(*arg, **kw)), ) else: return AsyncAdapt_aiomysql_connection( self, await_only(creator_fn(*arg, **kw)), ) def _init_cursors_subclasses(self): # suppress unconditional warning emitted by aiomysql class Cursor(self.aiomysql.Cursor): async def _show_warnings(self, conn): pass class SSCursor(self.aiomysql.SSCursor): async def _show_warnings(self, conn): pass return Cursor, SSCursor class MySQLDialect_aiomysql(MySQLDialect_pymysql): driver = "aiomysql" supports_statement_cache = True supports_server_side_cursors = True _sscursor = AsyncAdapt_aiomysql_ss_cursor is_async = True has_terminate = True @classmethod def import_dbapi(cls): return AsyncAdapt_aiomysql_dbapi( __import__("aiomysql"), __import__("pymysql") ) @classmethod def get_pool_class(cls, url): async_fallback = url.query.get("async_fallback", False) if util.asbool(async_fallback): return pool.FallbackAsyncAdaptedQueuePool else: return pool.AsyncAdaptedQueuePool def do_terminate(self, dbapi_connection) -> None: dbapi_connection.terminate() def create_connect_args(self, url): return super().create_connect_args( url, _translate_args=dict(username="user", database="db") ) def is_disconnect(self, e, connection, cursor): if super().is_disconnect(e, connection, cursor): return True else: str_e = str(e).lower() return "not connected" in str_e def _found_rows_client_flag(self): from pymysql.constants import CLIENT return CLIENT.FOUND_ROWS def get_driver_connection(self, connection): return connection._connection dialect = MySQLDialect_aiomysql sqlalchemy/dialects/mysql/mariadb.py 0000755 00000003160 15125143220 0013612 0 ustar 00 # dialects/mysql/mariadb.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors from .base import MariaDBIdentifierPreparer from .base import MySQLDialect from .base import MySQLTypeCompiler from ...sql import sqltypes class INET4(sqltypes.TypeEngine[str]): """INET4 column type for MariaDB .. versionadded:: 2.0.37 """ __visit_name__ = "INET4" class INET6(sqltypes.TypeEngine[str]): """INET6 column type for MariaDB .. versionadded:: 2.0.37 """ __visit_name__ = "INET6" class MariaDBTypeCompiler(MySQLTypeCompiler): def visit_INET4(self, type_, **kwargs) -> str: return "INET4" def visit_INET6(self, type_, **kwargs) -> str: return "INET6" class MariaDBDialect(MySQLDialect): is_mariadb = True supports_statement_cache = True name = "mariadb" preparer = MariaDBIdentifierPreparer type_compiler_cls = MariaDBTypeCompiler def loader(driver): dialect_mod = __import__( "sqlalchemy.dialects.mysql.%s" % driver ).dialects.mysql driver_mod = getattr(dialect_mod, driver) if hasattr(driver_mod, "mariadb_dialect"): driver_cls = driver_mod.mariadb_dialect return driver_cls else: driver_cls = driver_mod.dialect return type( "MariaDBDialect_%s" % driver, ( MariaDBDialect, driver_cls, ), {"supports_statement_cache": True}, ) sqlalchemy/dialects/mysql/mysqlconnector.py 0000755 00000017772 15125143220 0015311 0 ustar 00 # dialects/mysql/mysqlconnector.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors r""" .. dialect:: mysql+mysqlconnector :name: MySQL Connector/Python :dbapi: myconnpy :connectstring: mysql+mysqlconnector://<user>:<password>@<host>[:<port>]/<dbname> :url: https://pypi.org/project/mysql-connector-python/ Driver Status ------------- MySQL Connector/Python is supported as of SQLAlchemy 2.0.39 to the degree which the driver is functional. There are still ongoing issues with features such as server side cursors which remain disabled until upstream issues are repaired. .. warning:: The MySQL Connector/Python driver published by Oracle is subject to frequent, major regressions of essential functionality such as being able to correctly persist simple binary strings which indicate it is not well tested. The SQLAlchemy project is not able to maintain this dialect fully as regressions in the driver prevent it from being included in continuous integration. .. versionchanged:: 2.0.39 The MySQL Connector/Python dialect has been updated to support the latest version of this DBAPI. Previously, MySQL Connector/Python was not fully supported. However, support remains limited due to ongoing regressions introduced in this driver. Connecting to MariaDB with MySQL Connector/Python -------------------------------------------------- MySQL Connector/Python may attempt to pass an incompatible collation to the database when connecting to MariaDB. Experimentation has shown that using ``?charset=utf8mb4&collation=utfmb4_general_ci`` or similar MariaDB-compatible charset/collation will allow connectivity. """ # noqa import re from .base import BIT from .base import MariaDBIdentifierPreparer from .base import MySQLCompiler from .base import MySQLDialect from .base import MySQLExecutionContext from .base import MySQLIdentifierPreparer from .mariadb import MariaDBDialect from ... import util class MySQLExecutionContext_mysqlconnector(MySQLExecutionContext): def create_server_side_cursor(self): return self._dbapi_connection.cursor(buffered=False) def create_default_cursor(self): return self._dbapi_connection.cursor(buffered=True) class MySQLCompiler_mysqlconnector(MySQLCompiler): def visit_mod_binary(self, binary, operator, **kw): return ( self.process(binary.left, **kw) + " % " + self.process(binary.right, **kw) ) class IdentifierPreparerCommon_mysqlconnector: @property def _double_percents(self): return False @_double_percents.setter def _double_percents(self, value): pass def _escape_identifier(self, value): value = value.replace(self.escape_quote, self.escape_to_quote) return value class MySQLIdentifierPreparer_mysqlconnector( IdentifierPreparerCommon_mysqlconnector, MySQLIdentifierPreparer ): pass class MariaDBIdentifierPreparer_mysqlconnector( IdentifierPreparerCommon_mysqlconnector, MariaDBIdentifierPreparer ): pass class _myconnpyBIT(BIT): def result_processor(self, dialect, coltype): """MySQL-connector already converts mysql bits, so.""" return None class MySQLDialect_mysqlconnector(MySQLDialect): driver = "mysqlconnector" supports_statement_cache = True supports_sane_rowcount = True supports_sane_multi_rowcount = True supports_native_decimal = True supports_native_bit = True # not until https://bugs.mysql.com/bug.php?id=117548 supports_server_side_cursors = False default_paramstyle = "format" statement_compiler = MySQLCompiler_mysqlconnector execution_ctx_cls = MySQLExecutionContext_mysqlconnector preparer = MySQLIdentifierPreparer_mysqlconnector colspecs = util.update_copy(MySQLDialect.colspecs, {BIT: _myconnpyBIT}) @classmethod def import_dbapi(cls): from mysql import connector return connector def do_ping(self, dbapi_connection): dbapi_connection.ping(False) return True def create_connect_args(self, url): opts = url.translate_connect_args(username="user") opts.update(url.query) util.coerce_kw_type(opts, "allow_local_infile", bool) util.coerce_kw_type(opts, "autocommit", bool) util.coerce_kw_type(opts, "buffered", bool) util.coerce_kw_type(opts, "client_flag", int) util.coerce_kw_type(opts, "compress", bool) util.coerce_kw_type(opts, "connection_timeout", int) util.coerce_kw_type(opts, "connect_timeout", int) util.coerce_kw_type(opts, "consume_results", bool) util.coerce_kw_type(opts, "force_ipv6", bool) util.coerce_kw_type(opts, "get_warnings", bool) util.coerce_kw_type(opts, "pool_reset_session", bool) util.coerce_kw_type(opts, "pool_size", int) util.coerce_kw_type(opts, "raise_on_warnings", bool) util.coerce_kw_type(opts, "raw", bool) util.coerce_kw_type(opts, "ssl_verify_cert", bool) util.coerce_kw_type(opts, "use_pure", bool) util.coerce_kw_type(opts, "use_unicode", bool) # note that "buffered" is set to False by default in MySQL/connector # python. If you set it to True, then there is no way to get a server # side cursor because the logic is written to disallow that. # leaving this at True until # https://bugs.mysql.com/bug.php?id=117548 can be fixed opts["buffered"] = True # FOUND_ROWS must be set in ClientFlag to enable # supports_sane_rowcount. if self.dbapi is not None: try: from mysql.connector.constants import ClientFlag client_flags = opts.get( "client_flags", ClientFlag.get_default() ) client_flags |= ClientFlag.FOUND_ROWS opts["client_flags"] = client_flags except Exception: pass return [[], opts] @util.memoized_property def _mysqlconnector_version_info(self): if self.dbapi and hasattr(self.dbapi, "__version__"): m = re.match(r"(\d+)\.(\d+)(?:\.(\d+))?", self.dbapi.__version__) if m: return tuple(int(x) for x in m.group(1, 2, 3) if x is not None) def _detect_charset(self, connection): return connection.connection.charset def _extract_error_code(self, exception): return exception.errno def is_disconnect(self, e, connection, cursor): errnos = (2006, 2013, 2014, 2045, 2055, 2048) exceptions = ( self.dbapi.OperationalError, self.dbapi.InterfaceError, self.dbapi.ProgrammingError, ) if isinstance(e, exceptions): return ( e.errno in errnos or "MySQL Connection not available." in str(e) or "Connection to MySQL is not available" in str(e) ) else: return False def _compat_fetchall(self, rp, charset=None): return rp.fetchall() def _compat_fetchone(self, rp, charset=None): return rp.fetchone() def get_isolation_level_values(self, dbapi_connection): return ( "SERIALIZABLE", "READ UNCOMMITTED", "READ COMMITTED", "REPEATABLE READ", "AUTOCOMMIT", ) def set_isolation_level(self, connection, level): if level == "AUTOCOMMIT": connection.autocommit = True else: connection.autocommit = False super().set_isolation_level(connection, level) class MariaDBDialect_mysqlconnector( MariaDBDialect, MySQLDialect_mysqlconnector ): supports_statement_cache = True _allows_uuid_binds = False preparer = MariaDBIdentifierPreparer_mysqlconnector dialect = MySQLDialect_mysqlconnector mariadb_dialect = MariaDBDialect_mysqlconnector sqlalchemy/dialects/mysql/pyodbc.py 0000755 00000010312 15125143220 0013470 0 ustar 00 # dialects/mysql/pyodbc.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors r""" .. dialect:: mysql+pyodbc :name: PyODBC :dbapi: pyodbc :connectstring: mysql+pyodbc://<username>:<password>@<dsnname> :url: https://pypi.org/project/pyodbc/ .. note:: The PyODBC for MySQL dialect is **not tested as part of SQLAlchemy's continuous integration**. The recommended MySQL dialects are mysqlclient and PyMySQL. However, if you want to use the mysql+pyodbc dialect and require full support for ``utf8mb4`` characters (including supplementary characters like emoji) be sure to use a current release of MySQL Connector/ODBC and specify the "ANSI" (**not** "Unicode") version of the driver in your DSN or connection string. Pass through exact pyodbc connection string:: import urllib connection_string = ( "DRIVER=MySQL ODBC 8.0 ANSI Driver;" "SERVER=localhost;" "PORT=3307;" "DATABASE=mydb;" "UID=root;" "PWD=(whatever);" "charset=utf8mb4;" ) params = urllib.parse.quote_plus(connection_string) connection_uri = "mysql+pyodbc:///?odbc_connect=%s" % params """ # noqa import re from .base import MySQLDialect from .base import MySQLExecutionContext from .types import TIME from ... import exc from ... import util from ...connectors.pyodbc import PyODBCConnector from ...sql.sqltypes import Time class _pyodbcTIME(TIME): def result_processor(self, dialect, coltype): def process(value): # pyodbc returns a datetime.time object; no need to convert return value return process class MySQLExecutionContext_pyodbc(MySQLExecutionContext): def get_lastrowid(self): cursor = self.create_cursor() cursor.execute("SELECT LAST_INSERT_ID()") lastrowid = cursor.fetchone()[0] cursor.close() return lastrowid class MySQLDialect_pyodbc(PyODBCConnector, MySQLDialect): supports_statement_cache = True colspecs = util.update_copy(MySQLDialect.colspecs, {Time: _pyodbcTIME}) supports_unicode_statements = True execution_ctx_cls = MySQLExecutionContext_pyodbc pyodbc_driver_name = "MySQL" def _detect_charset(self, connection): """Sniff out the character set in use for connection results.""" # Prefer 'character_set_results' for the current connection over the # value in the driver. SET NAMES or individual variable SETs will # change the charset without updating the driver's view of the world. # # If it's decided that issuing that sort of SQL leaves you SOL, then # this can prefer the driver value. # set this to None as _fetch_setting attempts to use it (None is OK) self._connection_charset = None try: value = self._fetch_setting(connection, "character_set_client") if value: return value except exc.DBAPIError: pass util.warn( "Could not detect the connection character set. " "Assuming latin1." ) return "latin1" def _get_server_version_info(self, connection): return MySQLDialect._get_server_version_info(self, connection) def _extract_error_code(self, exception): m = re.compile(r"\((\d+)\)").search(str(exception.args)) c = m.group(1) if c: return int(c) else: return None def on_connect(self): super_ = super().on_connect() def on_connect(conn): if super_ is not None: super_(conn) # declare Unicode encoding for pyodbc as per # https://github.com/mkleehammer/pyodbc/wiki/Unicode pyodbc_SQL_CHAR = 1 # pyodbc.SQL_CHAR pyodbc_SQL_WCHAR = -8 # pyodbc.SQL_WCHAR conn.setdecoding(pyodbc_SQL_CHAR, encoding="utf-8") conn.setdecoding(pyodbc_SQL_WCHAR, encoding="utf-8") conn.setencoding(encoding="utf-8") return on_connect dialect = MySQLDialect_pyodbc sqlalchemy/dialects/mysql/asyncmy.py 0000755 00000023541 15125143220 0013703 0 ustar 00 # dialects/mysql/asyncmy.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors <see AUTHORS # file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors r""" .. dialect:: mysql+asyncmy :name: asyncmy :dbapi: asyncmy :connectstring: mysql+asyncmy://user:password@host:port/dbname[?key=value&key=value...] :url: https://github.com/long2ice/asyncmy Using a special asyncio mediation layer, the asyncmy dialect is usable as the backend for the :ref:`SQLAlchemy asyncio <asyncio_toplevel>` extension package. This dialect should normally be used only with the :func:`_asyncio.create_async_engine` engine creation function:: from sqlalchemy.ext.asyncio import create_async_engine engine = create_async_engine( "mysql+asyncmy://user:pass@hostname/dbname?charset=utf8mb4" ) """ # noqa from collections import deque from contextlib import asynccontextmanager from .pymysql import MySQLDialect_pymysql from ... import pool from ... import util from ...engine import AdaptedConnection from ...util.concurrency import asyncio from ...util.concurrency import await_fallback from ...util.concurrency import await_only class AsyncAdapt_asyncmy_cursor: # TODO: base on connectors/asyncio.py # see #10415 server_side = False __slots__ = ( "_adapt_connection", "_connection", "await_", "_cursor", "_rows", ) def __init__(self, adapt_connection): self._adapt_connection = adapt_connection self._connection = adapt_connection._connection self.await_ = adapt_connection.await_ cursor = self._connection.cursor() self._cursor = self.await_(cursor.__aenter__()) self._rows = deque() @property def description(self): return self._cursor.description @property def rowcount(self): return self._cursor.rowcount @property def arraysize(self): return self._cursor.arraysize @arraysize.setter def arraysize(self, value): self._cursor.arraysize = value @property def lastrowid(self): return self._cursor.lastrowid def close(self): # note we aren't actually closing the cursor here, # we are just letting GC do it. to allow this to be async # we would need the Result to change how it does "Safe close cursor". # MySQL "cursors" don't actually have state to be "closed" besides # exhausting rows, which we already have done for sync cursor. # another option would be to emulate aiosqlite dialect and assign # cursor only if we are doing server side cursor operation. self._rows.clear() def execute(self, operation, parameters=None): return self.await_(self._execute_async(operation, parameters)) def executemany(self, operation, seq_of_parameters): return self.await_( self._executemany_async(operation, seq_of_parameters) ) async def _execute_async(self, operation, parameters): async with self._adapt_connection._mutex_and_adapt_errors(): if parameters is None: result = await self._cursor.execute(operation) else: result = await self._cursor.execute(operation, parameters) if not self.server_side: # asyncmy has a "fake" async result, so we have to pull it out # of that here since our default result is not async. # we could just as easily grab "_rows" here and be done with it # but this is safer. self._rows = deque(await self._cursor.fetchall()) return result async def _executemany_async(self, operation, seq_of_parameters): async with self._adapt_connection._mutex_and_adapt_errors(): return await self._cursor.executemany(operation, seq_of_parameters) def setinputsizes(self, *inputsizes): pass def __iter__(self): while self._rows: yield self._rows.popleft() def fetchone(self): if self._rows: return self._rows.popleft() else: return None def fetchmany(self, size=None): if size is None: size = self.arraysize rr = self._rows return [rr.popleft() for _ in range(min(size, len(rr)))] def fetchall(self): retval = list(self._rows) self._rows.clear() return retval class AsyncAdapt_asyncmy_ss_cursor(AsyncAdapt_asyncmy_cursor): # TODO: base on connectors/asyncio.py # see #10415 __slots__ = () server_side = True def __init__(self, adapt_connection): self._adapt_connection = adapt_connection self._connection = adapt_connection._connection self.await_ = adapt_connection.await_ cursor = self._connection.cursor( adapt_connection.dbapi.asyncmy.cursors.SSCursor ) self._cursor = self.await_(cursor.__aenter__()) def close(self): if self._cursor is not None: self.await_(self._cursor.close()) self._cursor = None def fetchone(self): return self.await_(self._cursor.fetchone()) def fetchmany(self, size=None): return self.await_(self._cursor.fetchmany(size=size)) def fetchall(self): return self.await_(self._cursor.fetchall()) class AsyncAdapt_asyncmy_connection(AdaptedConnection): # TODO: base on connectors/asyncio.py # see #10415 await_ = staticmethod(await_only) __slots__ = ("dbapi", "_execute_mutex") def __init__(self, dbapi, connection): self.dbapi = dbapi self._connection = connection self._execute_mutex = asyncio.Lock() @asynccontextmanager async def _mutex_and_adapt_errors(self): async with self._execute_mutex: try: yield except AttributeError: raise self.dbapi.InternalError( "network operation failed due to asyncmy attribute error" ) def ping(self, reconnect): assert not reconnect return self.await_(self._do_ping()) async def _do_ping(self): async with self._mutex_and_adapt_errors(): return await self._connection.ping(False) def character_set_name(self): return self._connection.character_set_name() def autocommit(self, value): self.await_(self._connection.autocommit(value)) def cursor(self, server_side=False): if server_side: return AsyncAdapt_asyncmy_ss_cursor(self) else: return AsyncAdapt_asyncmy_cursor(self) def rollback(self): self.await_(self._connection.rollback()) def commit(self): self.await_(self._connection.commit()) def terminate(self): # it's not awaitable. self._connection.close() def close(self) -> None: self.await_(self._connection.ensure_closed()) class AsyncAdaptFallback_asyncmy_connection(AsyncAdapt_asyncmy_connection): __slots__ = () await_ = staticmethod(await_fallback) def _Binary(x): """Return x as a binary type.""" return bytes(x) class AsyncAdapt_asyncmy_dbapi: def __init__(self, asyncmy): self.asyncmy = asyncmy self.paramstyle = "format" self._init_dbapi_attributes() def _init_dbapi_attributes(self): for name in ( "Warning", "Error", "InterfaceError", "DataError", "DatabaseError", "OperationalError", "InterfaceError", "IntegrityError", "ProgrammingError", "InternalError", "NotSupportedError", ): setattr(self, name, getattr(self.asyncmy.errors, name)) STRING = util.symbol("STRING") NUMBER = util.symbol("NUMBER") BINARY = util.symbol("BINARY") DATETIME = util.symbol("DATETIME") TIMESTAMP = util.symbol("TIMESTAMP") Binary = staticmethod(_Binary) def connect(self, *arg, **kw): async_fallback = kw.pop("async_fallback", False) creator_fn = kw.pop("async_creator_fn", self.asyncmy.connect) if util.asbool(async_fallback): return AsyncAdaptFallback_asyncmy_connection( self, await_fallback(creator_fn(*arg, **kw)), ) else: return AsyncAdapt_asyncmy_connection( self, await_only(creator_fn(*arg, **kw)), ) class MySQLDialect_asyncmy(MySQLDialect_pymysql): driver = "asyncmy" supports_statement_cache = True supports_server_side_cursors = True _sscursor = AsyncAdapt_asyncmy_ss_cursor is_async = True has_terminate = True @classmethod def import_dbapi(cls): return AsyncAdapt_asyncmy_dbapi(__import__("asyncmy")) @classmethod def get_pool_class(cls, url): async_fallback = url.query.get("async_fallback", False) if util.asbool(async_fallback): return pool.FallbackAsyncAdaptedQueuePool else: return pool.AsyncAdaptedQueuePool def do_terminate(self, dbapi_connection) -> None: dbapi_connection.terminate() def create_connect_args(self, url): return super().create_connect_args( url, _translate_args=dict(username="user", database="db") ) def is_disconnect(self, e, connection, cursor): if super().is_disconnect(e, connection, cursor): return True else: str_e = str(e).lower() return ( "not connected" in str_e or "network operation failed" in str_e ) def _found_rows_client_flag(self): from asyncmy.constants import CLIENT return CLIENT.FOUND_ROWS def get_driver_connection(self, connection): return connection._connection dialect = MySQLDialect_asyncmy sqlalchemy/dialects/mysql/dml.py 0000755 00000017130 15125143220 0012771 0 ustar 00 # dialects/mysql/dml.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php from __future__ import annotations from typing import Any from typing import Dict from typing import List from typing import Mapping from typing import Optional from typing import Tuple from typing import Union from ... import exc from ... import util from ...sql._typing import _DMLTableArgument from ...sql.base import _exclusive_against from ...sql.base import _generative from ...sql.base import ColumnCollection from ...sql.base import ReadOnlyColumnCollection from ...sql.dml import Insert as StandardInsert from ...sql.elements import ClauseElement from ...sql.elements import KeyedColumnElement from ...sql.expression import alias from ...sql.selectable import NamedFromClause from ...util.typing import Self __all__ = ("Insert", "insert") def insert(table: _DMLTableArgument) -> Insert: """Construct a MySQL/MariaDB-specific variant :class:`_mysql.Insert` construct. .. container:: inherited_member The :func:`sqlalchemy.dialects.mysql.insert` function creates a :class:`sqlalchemy.dialects.mysql.Insert`. This class is based on the dialect-agnostic :class:`_sql.Insert` construct which may be constructed using the :func:`_sql.insert` function in SQLAlchemy Core. The :class:`_mysql.Insert` construct includes additional methods :meth:`_mysql.Insert.on_duplicate_key_update`. """ return Insert(table) class Insert(StandardInsert): """MySQL-specific implementation of INSERT. Adds methods for MySQL-specific syntaxes such as ON DUPLICATE KEY UPDATE. The :class:`~.mysql.Insert` object is created using the :func:`sqlalchemy.dialects.mysql.insert` function. .. versionadded:: 1.2 """ stringify_dialect = "mysql" inherit_cache = False @property def inserted( self, ) -> ReadOnlyColumnCollection[str, KeyedColumnElement[Any]]: """Provide the "inserted" namespace for an ON DUPLICATE KEY UPDATE statement MySQL's ON DUPLICATE KEY UPDATE clause allows reference to the row that would be inserted, via a special function called ``VALUES()``. This attribute provides all columns in this row to be referenceable such that they will render within a ``VALUES()`` function inside the ON DUPLICATE KEY UPDATE clause. The attribute is named ``.inserted`` so as not to conflict with the existing :meth:`_expression.Insert.values` method. .. tip:: The :attr:`_mysql.Insert.inserted` attribute is an instance of :class:`_expression.ColumnCollection`, which provides an interface the same as that of the :attr:`_schema.Table.c` collection described at :ref:`metadata_tables_and_columns`. With this collection, ordinary names are accessible like attributes (e.g. ``stmt.inserted.some_column``), but special names and dictionary method names should be accessed using indexed access, such as ``stmt.inserted["column name"]`` or ``stmt.inserted["values"]``. See the docstring for :class:`_expression.ColumnCollection` for further examples. .. seealso:: :ref:`mysql_insert_on_duplicate_key_update` - example of how to use :attr:`_expression.Insert.inserted` """ return self.inserted_alias.columns @util.memoized_property def inserted_alias(self) -> NamedFromClause: return alias(self.table, name="inserted") @_generative @_exclusive_against( "_post_values_clause", msgs={ "_post_values_clause": "This Insert construct already " "has an ON DUPLICATE KEY clause present" }, ) def on_duplicate_key_update(self, *args: _UpdateArg, **kw: Any) -> Self: r""" Specifies the ON DUPLICATE KEY UPDATE clause. :param \**kw: Column keys linked to UPDATE values. The values may be any SQL expression or supported literal Python values. .. warning:: This dictionary does **not** take into account Python-specified default UPDATE values or generation functions, e.g. those specified using :paramref:`_schema.Column.onupdate`. These values will not be exercised for an ON DUPLICATE KEY UPDATE style of UPDATE, unless values are manually specified here. :param \*args: As an alternative to passing key/value parameters, a dictionary or list of 2-tuples can be passed as a single positional argument. Passing a single dictionary is equivalent to the keyword argument form:: insert().on_duplicate_key_update({"name": "some name"}) Passing a list of 2-tuples indicates that the parameter assignments in the UPDATE clause should be ordered as sent, in a manner similar to that described for the :class:`_expression.Update` construct overall in :ref:`tutorial_parameter_ordered_updates`:: insert().on_duplicate_key_update( [ ("name", "some name"), ("value", "some value"), ] ) .. versionchanged:: 1.3 parameters can be specified as a dictionary or list of 2-tuples; the latter form provides for parameter ordering. .. versionadded:: 1.2 .. seealso:: :ref:`mysql_insert_on_duplicate_key_update` """ if args and kw: raise exc.ArgumentError( "Can't pass kwargs and positional arguments simultaneously" ) if args: if len(args) > 1: raise exc.ArgumentError( "Only a single dictionary or list of tuples " "is accepted positionally." ) values = args[0] else: values = kw self._post_values_clause = OnDuplicateClause( self.inserted_alias, values ) return self class OnDuplicateClause(ClauseElement): __visit_name__ = "on_duplicate_key_update" _parameter_ordering: Optional[List[str]] = None update: Dict[str, Any] stringify_dialect = "mysql" def __init__( self, inserted_alias: NamedFromClause, update: _UpdateArg ) -> None: self.inserted_alias = inserted_alias # auto-detect that parameters should be ordered. This is copied from # Update._proces_colparams(), however we don't look for a special flag # in this case since we are not disambiguating from other use cases as # we are in Update.values(). if isinstance(update, list) and ( update and isinstance(update[0], tuple) ): self._parameter_ordering = [key for key, value in update] update = dict(update) if isinstance(update, dict): if not update: raise ValueError( "update parameter dictionary must not be empty" ) elif isinstance(update, ColumnCollection): update = dict(update) else: raise ValueError( "update parameter must be a non-empty dictionary " "or a ColumnCollection such as the `.c.` collection " "of a Table object" ) self.update = update _UpdateArg = Union[ Mapping[Any, Any], List[Tuple[str, Any]], ColumnCollection[Any, Any] ] sqlalchemy/dialects/mysql/__init__.py 0000755 00000004236 15125143220 0013757 0 ustar 00 # dialects/mysql/__init__.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors from . import aiomysql # noqa from . import asyncmy # noqa from . import base # noqa from . import cymysql # noqa from . import mariadbconnector # noqa from . import mysqlconnector # noqa from . import mysqldb # noqa from . import pymysql # noqa from . import pyodbc # noqa from .base import BIGINT from .base import BINARY from .base import BIT from .base import BLOB from .base import BOOLEAN from .base import CHAR from .base import DATE from .base import DATETIME from .base import DECIMAL from .base import DOUBLE from .base import ENUM from .base import FLOAT from .base import INTEGER from .base import JSON from .base import LONGBLOB from .base import LONGTEXT from .base import MEDIUMBLOB from .base import MEDIUMINT from .base import MEDIUMTEXT from .base import NCHAR from .base import NUMERIC from .base import NVARCHAR from .base import REAL from .base import SET from .base import SMALLINT from .base import TEXT from .base import TIME from .base import TIMESTAMP from .base import TINYBLOB from .base import TINYINT from .base import TINYTEXT from .base import VARBINARY from .base import VARCHAR from .base import YEAR from .dml import Insert from .dml import insert from .expression import match from .mariadb import INET4 from .mariadb import INET6 # default dialect base.dialect = dialect = mysqldb.dialect __all__ = ( "BIGINT", "BINARY", "BIT", "BLOB", "BOOLEAN", "CHAR", "DATE", "DATETIME", "DECIMAL", "DOUBLE", "ENUM", "FLOAT", "INET4", "INET6", "INTEGER", "INTEGER", "JSON", "LONGBLOB", "LONGTEXT", "MEDIUMBLOB", "MEDIUMINT", "MEDIUMTEXT", "NCHAR", "NVARCHAR", "NUMERIC", "SET", "SMALLINT", "REAL", "TEXT", "TIME", "TIMESTAMP", "TINYBLOB", "TINYINT", "TINYTEXT", "VARBINARY", "VARCHAR", "YEAR", "dialect", "insert", "Insert", "match", ) sqlalchemy/dialects/mysql/reserved_words.py 0000755 00000022052 15125143220 0015251 0 ustar 00 # dialects/mysql/reserved_words.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # generated using: # https://gist.github.com/kkirsche/4f31f2153ed7a3248be1ec44ca6ddbc9 # # https://mariadb.com/kb/en/reserved-words/ # includes: Reserved Words, Oracle Mode (separate set unioned) # excludes: Exceptions, Function Names # mypy: ignore-errors RESERVED_WORDS_MARIADB = { "accessible", "add", "all", "alter", "analyze", "and", "as", "asc", "asensitive", "before", "between", "bigint", "binary", "blob", "both", "by", "call", "cascade", "case", "change", "char", "character", "check", "collate", "column", "condition", "constraint", "continue", "convert", "create", "cross", "current_date", "current_role", "current_time", "current_timestamp", "current_user", "cursor", "database", "databases", "day_hour", "day_microsecond", "day_minute", "day_second", "dec", "decimal", "declare", "default", "delayed", "delete", "desc", "describe", "deterministic", "distinct", "distinctrow", "div", "do_domain_ids", "double", "drop", "dual", "each", "else", "elseif", "enclosed", "escaped", "except", "exists", "exit", "explain", "false", "fetch", "float", "float4", "float8", "for", "force", "foreign", "from", "fulltext", "general", "grant", "group", "having", "high_priority", "hour_microsecond", "hour_minute", "hour_second", "if", "ignore", "ignore_domain_ids", "ignore_server_ids", "in", "index", "infile", "inner", "inout", "insensitive", "insert", "int", "int1", "int2", "int3", "int4", "int8", "integer", "intersect", "interval", "into", "is", "iterate", "join", "key", "keys", "kill", "leading", "leave", "left", "like", "limit", "linear", "lines", "load", "localtime", "localtimestamp", "lock", "long", "longblob", "longtext", "loop", "low_priority", "master_heartbeat_period", "master_ssl_verify_server_cert", "match", "maxvalue", "mediumblob", "mediumint", "mediumtext", "middleint", "minute_microsecond", "minute_second", "mod", "modifies", "natural", "no_write_to_binlog", "not", "null", "numeric", "offset", "on", "optimize", "option", "optionally", "or", "order", "out", "outer", "outfile", "over", "page_checksum", "parse_vcol_expr", "partition", "position", "precision", "primary", "procedure", "purge", "range", "read", "read_write", "reads", "real", "recursive", "ref_system_id", "references", "regexp", "release", "rename", "repeat", "replace", "require", "resignal", "restrict", "return", "returning", "revoke", "right", "rlike", "rows", "row_number", "schema", "schemas", "second_microsecond", "select", "sensitive", "separator", "set", "show", "signal", "slow", "smallint", "spatial", "specific", "sql", "sql_big_result", "sql_calc_found_rows", "sql_small_result", "sqlexception", "sqlstate", "sqlwarning", "ssl", "starting", "stats_auto_recalc", "stats_persistent", "stats_sample_pages", "straight_join", "table", "terminated", "then", "tinyblob", "tinyint", "tinytext", "to", "trailing", "trigger", "true", "undo", "union", "unique", "unlock", "unsigned", "update", "usage", "use", "using", "utc_date", "utc_time", "utc_timestamp", "values", "varbinary", "varchar", "varcharacter", "varying", "when", "where", "while", "window", "with", "write", "xor", "year_month", "zerofill", }.union( { "body", "elsif", "goto", "history", "others", "package", "period", "raise", "rowtype", "system", "system_time", "versioning", "without", } ) # https://dev.mysql.com/doc/refman/8.3/en/keywords.html # https://dev.mysql.com/doc/refman/8.0/en/keywords.html # https://dev.mysql.com/doc/refman/5.7/en/keywords.html # https://dev.mysql.com/doc/refman/5.6/en/keywords.html # includes: MySQL x.0 Keywords and Reserved Words # excludes: MySQL x.0 New Keywords and Reserved Words, # MySQL x.0 Removed Keywords and Reserved Words RESERVED_WORDS_MYSQL = { "accessible", "add", "admin", "all", "alter", "analyze", "and", "array", "as", "asc", "asensitive", "before", "between", "bigint", "binary", "blob", "both", "by", "call", "cascade", "case", "change", "char", "character", "check", "collate", "column", "condition", "constraint", "continue", "convert", "create", "cross", "cube", "cume_dist", "current_date", "current_time", "current_timestamp", "current_user", "cursor", "database", "databases", "day_hour", "day_microsecond", "day_minute", "day_second", "dec", "decimal", "declare", "default", "delayed", "delete", "dense_rank", "desc", "describe", "deterministic", "distinct", "distinctrow", "div", "double", "drop", "dual", "each", "else", "elseif", "empty", "enclosed", "escaped", "except", "exists", "exit", "explain", "false", "fetch", "first_value", "float", "float4", "float8", "for", "force", "foreign", "from", "fulltext", "function", "general", "generated", "get", "get_master_public_key", "grant", "group", "grouping", "groups", "having", "high_priority", "hour_microsecond", "hour_minute", "hour_second", "if", "ignore", "ignore_server_ids", "in", "index", "infile", "inner", "inout", "insensitive", "insert", "int", "int1", "int2", "int3", "int4", "int8", "integer", "intersect", "interval", "into", "io_after_gtids", "io_before_gtids", "is", "iterate", "join", "json_table", "key", "keys", "kill", "lag", "last_value", "lateral", "lead", "leading", "leave", "left", "like", "limit", "linear", "lines", "load", "localtime", "localtimestamp", "lock", "long", "longblob", "longtext", "loop", "low_priority", "master_bind", "master_heartbeat_period", "master_ssl_verify_server_cert", "match", "maxvalue", "mediumblob", "mediumint", "mediumtext", "member", "middleint", "minute_microsecond", "minute_second", "mod", "modifies", "natural", "no_write_to_binlog", "not", "nth_value", "ntile", "null", "numeric", "of", "on", "optimize", "optimizer_costs", "option", "optionally", "or", "order", "out", "outer", "outfile", "over", "parse_gcol_expr", "parallel", "partition", "percent_rank", "persist", "persist_only", "precision", "primary", "procedure", "purge", "qualify", "range", "rank", "read", "read_write", "reads", "real", "recursive", "references", "regexp", "release", "rename", "repeat", "replace", "require", "resignal", "restrict", "return", "revoke", "right", "rlike", "role", "row", "row_number", "rows", "schema", "schemas", "second_microsecond", "select", "sensitive", "separator", "set", "show", "signal", "slow", "smallint", "spatial", "specific", "sql", "sql_after_gtids", "sql_before_gtids", "sql_big_result", "sql_calc_found_rows", "sql_small_result", "sqlexception", "sqlstate", "sqlwarning", "ssl", "starting", "stored", "straight_join", "system", "table", "terminated", "then", "tinyblob", "tinyint", "tinytext", "to", "trailing", "trigger", "true", "undo", "union", "unique", "unlock", "unsigned", "update", "usage", "use", "using", "utc_date", "utc_time", "utc_timestamp", "values", "varbinary", "varchar", "varcharacter", "varying", "virtual", "when", "where", "while", "window", "with", "write", "xor", "year_month", "zerofill", } sqlalchemy/dialects/sqlite/__pycache__/pysqlcipher.cpython-39.pyc 0000644 00000012501 15125143220 0021175 0 ustar 00 a ��Jh� � @ s4 d Z ddlmZ ddlmZ G dd� de�ZeZdS )a` .. dialect:: sqlite+pysqlcipher :name: pysqlcipher :dbapi: sqlcipher 3 or pysqlcipher :connectstring: sqlite+pysqlcipher://:passphrase@/file_path[?kdf_iter=<iter>] Dialect for support of DBAPIs that make use of the `SQLCipher <https://www.zetetic.net/sqlcipher>`_ backend. Driver ------ Current dialect selection logic is: * If the :paramref:`_sa.create_engine.module` parameter supplies a DBAPI module, that module is used. * Otherwise for Python 3, choose https://pypi.org/project/sqlcipher3/ * If not available, fall back to https://pypi.org/project/pysqlcipher3/ * For Python 2, https://pypi.org/project/pysqlcipher/ is used. .. warning:: The ``pysqlcipher3`` and ``pysqlcipher`` DBAPI drivers are no longer maintained; the ``sqlcipher3`` driver as of this writing appears to be current. For future compatibility, any pysqlcipher-compatible DBAPI may be used as follows:: import sqlcipher_compatible_driver from sqlalchemy import create_engine e = create_engine( "sqlite+pysqlcipher://:password@/dbname.db", module=sqlcipher_compatible_driver, ) These drivers make use of the SQLCipher engine. This system essentially introduces new PRAGMA commands to SQLite which allows the setting of a passphrase and other encryption parameters, allowing the database file to be encrypted. Connect Strings --------------- The format of the connect string is in every way the same as that of the :mod:`~sqlalchemy.dialects.sqlite.pysqlite` driver, except that the "password" field is now accepted, which should contain a passphrase:: e = create_engine("sqlite+pysqlcipher://:testing@/foo.db") For an absolute file path, two leading slashes should be used for the database name:: e = create_engine("sqlite+pysqlcipher://:testing@//path/to/foo.db") A selection of additional encryption-related pragmas supported by SQLCipher as documented at https://www.zetetic.net/sqlcipher/sqlcipher-api/ can be passed in the query string, and will result in that PRAGMA being called for each new connection. Currently, ``cipher``, ``kdf_iter`` ``cipher_page_size`` and ``cipher_use_hmac`` are supported:: e = create_engine( "sqlite+pysqlcipher://:testing@/foo.db?cipher=aes-256-cfb&kdf_iter=64000" ) .. warning:: Previous versions of sqlalchemy did not take into consideration the encryption-related pragmas passed in the url string, that were silently ignored. This may cause errors when opening files saved by a previous sqlalchemy version if the encryption options do not match. Pooling Behavior ---------------- The driver makes a change to the default pool behavior of pysqlite as described in :ref:`pysqlite_threading_pooling`. The pysqlcipher driver has been observed to be significantly slower on connection than the pysqlite driver, most likely due to the encryption overhead, so the dialect here defaults to using the :class:`.SingletonThreadPool` implementation, instead of the :class:`.NullPool` pool used by pysqlite. As always, the pool implementation is entirely configurable using the :paramref:`_sa.create_engine.poolclass` parameter; the :class:`. StaticPool` may be more feasible for single-threaded use, or :class:`.NullPool` may be used to prevent unencrypted connections from being held open for long periods of time, at the expense of slower startup time for new connections. � )�SQLiteDialect_pysqlite� )�poolc sL e Zd ZdZdZdZedd� �Zedd� �Z� fdd �Z � fd d �Z � Z S ) �SQLiteDialect_pysqlcipherZ pysqlcipherT)Zkdf_iter�cipherZcipher_page_sizeZcipher_use_hmacc C s4 z dd l }W n ty Y n0 |S ddlm} |S )N� )�dbapi2)Z sqlcipher3� ImportErrorZ pysqlcipher3r )�clsZ sqlcipher� r �[/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/sqlite/pysqlcipher.py� import_dbapio s z&SQLiteDialect_pysqlcipher.import_dbapic C s t jS )N)r ZSingletonThreadPool)r �urlr r r �get_pool_class| s z(SQLiteDialect_pysqlcipher.get_pool_classc s6 t � �|��|jpd� t|j��� ���fdd�}|S )N� c s` | � � }|�d� � �jD ]*}��|d �}|d ur |�d||f � q |�� �r\�| � d S )Nzpragma key="%s"zpragma %s="%s")�cursor�execute�pragmas�get�close)�connr Zprag�value�Z passphrase�selfZsuper_on_connectZ url_queryr r � on_connect� s z<SQLiteDialect_pysqlcipher.on_connect_url.<locals>.on_connect)�super�on_connect_url�password�dict�query)r r r �� __class__r r r � s z(SQLiteDialect_pysqlcipher.on_connect_urlc s$ |j d d�}|�| j�}t� �|�S )N)r )�_replaceZdifference_update_queryr r �create_connect_args)r r Z plain_urlr r r r# � s z-SQLiteDialect_pysqlcipher.create_connect_args) �__name__� __module__� __qualname__ZdriverZsupports_statement_cacher � classmethodr r r r# � __classcell__r r r r r i s r N)�__doc__Zpysqliter r r r �dialectr r r r �<module> s [ 4 sqlalchemy/dialects/sqlite/__pycache__/pysqlite.cpython-39.pyc 0000644 00000062017 15125143220 0020513 0 ustar 00 a ��Jh�b � @ s� d Z ddlZddlZddlZddlmZ ddlmZ ddlmZ ddlm Z dd lm Z dd lm Z dd lm Z G d d � d e�ZG dd� de�ZG dd� de�ZeZG dd� de�ZG dd� de�ZdS )az: .. dialect:: sqlite+pysqlite :name: pysqlite :dbapi: sqlite3 :connectstring: sqlite+pysqlite:///file_path :url: https://docs.python.org/library/sqlite3.html Note that ``pysqlite`` is the same driver as the ``sqlite3`` module included with the Python distribution. Driver ------ The ``sqlite3`` Python DBAPI is standard on all modern Python versions; for cPython and Pypy, no additional installation is necessary. Connect Strings --------------- The file specification for the SQLite database is taken as the "database" portion of the URL. Note that the format of a SQLAlchemy url is: .. sourcecode:: text driver://user:pass@host/database This means that the actual filename to be used starts with the characters to the **right** of the third slash. So connecting to a relative filepath looks like:: # relative path e = create_engine("sqlite:///path/to/database.db") An absolute path, which is denoted by starting with a slash, means you need **four** slashes:: # absolute path e = create_engine("sqlite:////path/to/database.db") To use a Windows path, regular drive specifications and backslashes can be used. Double backslashes are probably needed:: # absolute path on Windows e = create_engine("sqlite:///C:\\path\\to\\database.db") To use sqlite ``:memory:`` database specify it as the filename using ``sqlite:///:memory:``. It's also the default if no filepath is present, specifying only ``sqlite://`` and nothing else:: # in-memory database (note three slashes) e = create_engine("sqlite:///:memory:") # also in-memory database e2 = create_engine("sqlite://") .. _pysqlite_uri_connections: URI Connections ^^^^^^^^^^^^^^^ Modern versions of SQLite support an alternative system of connecting using a `driver level URI <https://www.sqlite.org/uri.html>`_, which has the advantage that additional driver-level arguments can be passed including options such as "read only". The Python sqlite3 driver supports this mode under modern Python 3 versions. The SQLAlchemy pysqlite driver supports this mode of use by specifying "uri=true" in the URL query string. The SQLite-level "URI" is kept as the "database" portion of the SQLAlchemy url (that is, following a slash):: e = create_engine("sqlite:///file:path/to/database?mode=ro&uri=true") .. note:: The "uri=true" parameter must appear in the **query string** of the URL. It will not currently work as expected if it is only present in the :paramref:`_sa.create_engine.connect_args` parameter dictionary. The logic reconciles the simultaneous presence of SQLAlchemy's query string and SQLite's query string by separating out the parameters that belong to the Python sqlite3 driver vs. those that belong to the SQLite URI. This is achieved through the use of a fixed list of parameters known to be accepted by the Python side of the driver. For example, to include a URL that indicates the Python sqlite3 "timeout" and "check_same_thread" parameters, along with the SQLite "mode" and "nolock" parameters, they can all be passed together on the query string:: e = create_engine( "sqlite:///file:path/to/database?" "check_same_thread=true&timeout=10&mode=ro&nolock=1&uri=true" ) Above, the pysqlite / sqlite3 DBAPI would be passed arguments as:: sqlite3.connect( "file:path/to/database?mode=ro&nolock=1", check_same_thread=True, timeout=10, uri=True, ) Regarding future parameters added to either the Python or native drivers. new parameter names added to the SQLite URI scheme should be automatically accommodated by this scheme. New parameter names added to the Python driver side can be accommodated by specifying them in the :paramref:`_sa.create_engine.connect_args` dictionary, until dialect support is added by SQLAlchemy. For the less likely case that the native SQLite driver adds a new parameter name that overlaps with one of the existing, known Python driver parameters (such as "timeout" perhaps), SQLAlchemy's dialect would require adjustment for the URL scheme to continue to support this. As is always the case for all SQLAlchemy dialects, the entire "URL" process can be bypassed in :func:`_sa.create_engine` through the use of the :paramref:`_sa.create_engine.creator` parameter which allows for a custom callable that creates a Python sqlite3 driver level connection directly. .. versionadded:: 1.3.9 .. seealso:: `Uniform Resource Identifiers <https://www.sqlite.org/uri.html>`_ - in the SQLite documentation .. _pysqlite_regexp: Regular Expression Support --------------------------- .. versionadded:: 1.4 Support for the :meth:`_sql.ColumnOperators.regexp_match` operator is provided using Python's re.search_ function. SQLite itself does not include a working regular expression operator; instead, it includes a non-implemented placeholder operator ``REGEXP`` that calls a user-defined function that must be provided. SQLAlchemy's implementation makes use of the pysqlite create_function_ hook as follows:: def regexp(a, b): return re.search(a, b) is not None sqlite_connection.create_function( "regexp", 2, regexp, ) There is currently no support for regular expression flags as a separate argument, as these are not supported by SQLite's REGEXP operator, however these may be included inline within the regular expression string. See `Python regular expressions`_ for details. .. seealso:: `Python regular expressions`_: Documentation for Python's regular expression syntax. .. _create_function: https://docs.python.org/3/library/sqlite3.html#sqlite3.Connection.create_function .. _re.search: https://docs.python.org/3/library/re.html#re.search .. _Python regular expressions: https://docs.python.org/3/library/re.html#re.search Compatibility with sqlite3 "native" date and datetime types ----------------------------------------------------------- The pysqlite driver includes the sqlite3.PARSE_DECLTYPES and sqlite3.PARSE_COLNAMES options, which have the effect of any column or expression explicitly cast as "date" or "timestamp" will be converted to a Python date or datetime object. The date and datetime types provided with the pysqlite dialect are not currently compatible with these options, since they render the ISO date/datetime including microseconds, which pysqlite's driver does not. Additionally, SQLAlchemy does not at this time automatically render the "cast" syntax required for the freestanding functions "current_timestamp" and "current_date" to return datetime/date types natively. Unfortunately, pysqlite does not provide the standard DBAPI types in ``cursor.description``, leaving SQLAlchemy with no way to detect these types on the fly without expensive per-row type checks. Keeping in mind that pysqlite's parsing option is not recommended, nor should be necessary, for use with SQLAlchemy, usage of PARSE_DECLTYPES can be forced if one configures "native_datetime=True" on create_engine():: engine = create_engine( "sqlite://", connect_args={ "detect_types": sqlite3.PARSE_DECLTYPES | sqlite3.PARSE_COLNAMES }, native_datetime=True, ) With this flag enabled, the DATE and TIMESTAMP types (but note - not the DATETIME or TIME types...confused yet ?) will not perform any bind parameter or result processing. Execution of "func.current_date()" will return a string. "func.current_timestamp()" is registered as returning a DATETIME type in SQLAlchemy, so this function still receives SQLAlchemy-level result processing. .. _pysqlite_threading_pooling: Threading/Pooling Behavior --------------------------- The ``sqlite3`` DBAPI by default prohibits the use of a particular connection in a thread which is not the one in which it was created. As SQLite has matured, it's behavior under multiple threads has improved, and even includes options for memory only databases to be used in multiple threads. The thread prohibition is known as "check same thread" and may be controlled using the ``sqlite3`` parameter ``check_same_thread``, which will disable or enable this check. SQLAlchemy's default behavior here is to set ``check_same_thread`` to ``False`` automatically whenever a file-based database is in use, to establish compatibility with the default pool class :class:`.QueuePool`. The SQLAlchemy ``pysqlite`` DBAPI establishes the connection pool differently based on the kind of SQLite database that's requested: * When a ``:memory:`` SQLite database is specified, the dialect by default will use :class:`.SingletonThreadPool`. This pool maintains a single connection per thread, so that all access to the engine within the current thread use the same ``:memory:`` database - other threads would access a different ``:memory:`` database. The ``check_same_thread`` parameter defaults to ``True``. * When a file-based database is specified, the dialect will use :class:`.QueuePool` as the source of connections. at the same time, the ``check_same_thread`` flag is set to False by default unless overridden. .. versionchanged:: 2.0 SQLite file database engines now use :class:`.QueuePool` by default. Previously, :class:`.NullPool` were used. The :class:`.NullPool` class may be used by specifying it via the :paramref:`_sa.create_engine.poolclass` parameter. Disabling Connection Pooling for File Databases ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Pooling may be disabled for a file based database by specifying the :class:`.NullPool` implementation for the :func:`_sa.create_engine.poolclass` parameter:: from sqlalchemy import NullPool engine = create_engine("sqlite:///myfile.db", poolclass=NullPool) It's been observed that the :class:`.NullPool` implementation incurs an extremely small performance overhead for repeated checkouts due to the lack of connection re-use implemented by :class:`.QueuePool`. However, it still may be beneficial to use this class if the application is experiencing issues with files being locked. Using a Memory Database in Multiple Threads ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To use a ``:memory:`` database in a multithreaded scenario, the same connection object must be shared among threads, since the database exists only within the scope of that connection. The :class:`.StaticPool` implementation will maintain a single connection globally, and the ``check_same_thread`` flag can be passed to Pysqlite as ``False``:: from sqlalchemy.pool import StaticPool engine = create_engine( "sqlite://", connect_args={"check_same_thread": False}, poolclass=StaticPool, ) Note that using a ``:memory:`` database in multiple threads requires a recent version of SQLite. Using Temporary Tables with SQLite ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Due to the way SQLite deals with temporary tables, if you wish to use a temporary table in a file-based SQLite database across multiple checkouts from the connection pool, such as when using an ORM :class:`.Session` where the temporary table should continue to remain after :meth:`.Session.commit` or :meth:`.Session.rollback` is called, a pool which maintains a single connection must be used. Use :class:`.SingletonThreadPool` if the scope is only needed within the current thread, or :class:`.StaticPool` is scope is needed within multiple threads for this case:: # maintain the same connection per thread from sqlalchemy.pool import SingletonThreadPool engine = create_engine("sqlite:///mydb.db", poolclass=SingletonThreadPool) # maintain the same connection across all threads from sqlalchemy.pool import StaticPool engine = create_engine("sqlite:///mydb.db", poolclass=StaticPool) Note that :class:`.SingletonThreadPool` should be configured for the number of threads that are to be used; beyond that number, connections will be closed out in a non deterministic way. Dealing with Mixed String / Binary Columns ------------------------------------------------------ The SQLite database is weakly typed, and as such it is possible when using binary values, which in Python are represented as ``b'some string'``, that a particular SQLite database can have data values within different rows where some of them will be returned as a ``b''`` value by the Pysqlite driver, and others will be returned as Python strings, e.g. ``''`` values. This situation is not known to occur if the SQLAlchemy :class:`.LargeBinary` datatype is used consistently, however if a particular SQLite database has data that was inserted using the Pysqlite driver directly, or when using the SQLAlchemy :class:`.String` type which was later changed to :class:`.LargeBinary`, the table will not be consistently readable because SQLAlchemy's :class:`.LargeBinary` datatype does not handle strings so it has no way of "encoding" a value that is in string format. To deal with a SQLite table that has mixed string / binary data in the same column, use a custom type that will check each row individually:: from sqlalchemy import String from sqlalchemy import TypeDecorator class MixedBinary(TypeDecorator): impl = String cache_ok = True def process_result_value(self, value, dialect): if isinstance(value, str): value = bytes(value, "utf-8") elif value is not None: value = bytes(value) return value Then use the above ``MixedBinary`` datatype in the place where :class:`.LargeBinary` would normally be used. .. _pysqlite_serializable: Serializable isolation / Savepoints / Transactional DDL ------------------------------------------------------- A newly revised version of this important section is now available at the top level of the SQLAlchemy SQLite documentation, in the section :ref:`sqlite_transactions`. .. _pysqlite_udfs: User-Defined Functions ---------------------- pysqlite supports a `create_function() <https://docs.python.org/3/library/sqlite3.html#sqlite3.Connection.create_function>`_ method that allows us to create our own user-defined functions (UDFs) in Python and use them directly in SQLite queries. These functions are registered with a specific DBAPI Connection. SQLAlchemy uses connection pooling with file-based SQLite databases, so we need to ensure that the UDF is attached to the connection when it is created. That is accomplished with an event listener:: from sqlalchemy import create_engine from sqlalchemy import event from sqlalchemy import text def udf(): return "udf-ok" engine = create_engine("sqlite:///./db_file") @event.listens_for(engine, "connect") def connect(conn, rec): conn.create_function("udf", 0, udf) for i in range(5): with engine.connect() as conn: print(conn.scalar(text("SELECT UDF()"))) � N� )�DATE)�DATETIME)� SQLiteDialect� )�exc)�pool)�types)�utilc @ s e Zd Zdd� Zdd� ZdS )�_SQLite_pysqliteTimeStampc C s |j r d S t�| |�S d S �N)�native_datetimer �bind_processor��self�dialect� r �X/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/sqlite/pysqlite.pyr � s z(_SQLite_pysqliteTimeStamp.bind_processorc C s |j r d S t�| ||�S d S r )r r �result_processor�r r Zcoltyper r r r � s z*_SQLite_pysqliteTimeStamp.result_processorN��__name__� __module__� __qualname__r r r r r r r � s r c @ s e Zd Zdd� Zdd� ZdS )�_SQLite_pysqliteDatec C s |j r d S t�| |�S d S r )r r r r r r r r � s z#_SQLite_pysqliteDate.bind_processorc C s |j r d S t�| ||�S d S r )r r r r r r r r � s z%_SQLite_pysqliteDate.result_processorNr r r r r r � s r c s� e Zd ZdZdZdZe�ej e j e e j ei�Z dZdZedd� �Zedd� �Zed d � �Zd d � Zej�d di�Z� fdd�Zdd� Zdd� Zdd� Z� Z S )�SQLiteDialect_pysqliteZqmarkTNZpysqlitec C s ddl m} |S )Nr )�dbapi2)�sqlite3r )�clsZsqliter r r � import_dbapi� s z#SQLiteDialect_pysqlite.import_dbapic C s. |j r&|j dkr&|j�dd �dkr&dS dS d S )N�:memory:�modeZmemoryTF)�database�query�get�r �urlr r r �_is_url_file_db� s �z&SQLiteDialect_pysqlite._is_url_file_dbc C s | � |�rtjS tjS d S r )r' r Z QueuePoolZSingletonThreadPoolr% r r r �get_pool_class� s z%SQLiteDialect_pysqlite.get_pool_classc C s | j jS r )�dbapiZsqlite_version_info)r � connectionr r r �_get_server_version_info� s z/SQLiteDialect_pysqlite._get_server_version_info� AUTOCOMMITc s( |dkrd |_ nd|_ t� �||�S d S )Nr, � )�isolation_level�super�set_isolation_level)r �dbapi_connection�level�� __class__r r r0 � s z*SQLiteDialect_pysqlite.set_isolation_levelc s\ dd� �t jr&| �d �dkr&ddi� ni � � �fdd�}� fdd �}||g��fd d �}|S ) Nc S s |d u r d S t �| |�d uS r )�re�search)�a�br r r �regexp� s z1SQLiteDialect_pysqlite.on_connect.<locals>.regexp)r � Z deterministicTc s | j dd�fi � �� d S )Nr9 � )�create_function�r1 )�create_func_kwr9 r r � set_regexp� s ��z5SQLiteDialect_pysqlite.on_connect.<locals>.set_regexpc s | j ddtjfi � �� d S )N�floorr )r< �mathr@ r= )r> r r � floor_func s ��z5SQLiteDialect_pysqlite.on_connect.<locals>.floor_funcc s � D ] }|| � qd S r r )�conn�fn)�fnsr r �connect s z2SQLiteDialect_pysqlite.on_connect.<locals>.connect)r Zpy38r+ )r r? rB rF r )r> rE r9 r � on_connect� s z!SQLiteDialect_pysqlite.on_connectc s |j s|js|js|jr(t�d|f ��dtfdtfdtfdt fdtfdt fg}|j }i }|D ]\}}t j ||||d� q^|� dd �r�t|�� |D ]\}}� �|d � q�|j}� r�|d d �� fd d �t� �D �� 7 }n |jp�d}|dkr�tj�|�}|�d| �|� � |g|fS )Nz�Invalid SQLite URL: %s Valid SQLite URL forms are: sqlite:///:memory: (or, sqlite://) sqlite:///relative/path/to/file.db sqlite:////absolute/path/to/file.db�uri�timeoutr. Z detect_typesZcheck_same_threadZcached_statements)�destF�?�&c 3 s | ]}d |� | f V qdS )z%s=%sNr )�.0�key�Zuri_optsr r � <genexpr>@ s �z=SQLiteDialect_pysqlite.create_connect_args.<locals>.<genexpr>r )�username�password�host�portr � ArgumentError�bool�float�str�intr# r Zcoerce_kw_typer$ �dict�popr" �join�sorted�os�path�abspath� setdefaultr' )r r& Z pysqlite_args�optsZ pysqlite_optsrN �type_�filenamer rO r �create_connect_args sF ��� �� �z*SQLiteDialect_pysqlite.create_connect_argsc C s t || jj�odt|�v S )Nz$Cannot operate on a closed database.)� isinstancer) ZProgrammingErrorrX )r �er* �cursorr r r � is_disconnectP s � �z$SQLiteDialect_pysqlite.is_disconnect) r r r �default_paramstyle�supports_statement_cacheZreturns_native_bytesr Z update_copyr Zcolspecs�sqltypes�Dater � TIMESTAMPr Zdescription_encoding�driver� classmethodr r' r( r+ Z_isolation_lookup�unionr0 rG re ri � __classcell__r r r3 r r � s4 �� �� %>r c sH e Zd ZdZdZdZdZdZdZ� fdd�Z � fd d �Z d d � Z � Z S ) � _SQLiteDialect_pysqlite_numericz�numeric dialect for testing only internal use only. This dialect is **NOT** supported by SQLAlchemy and may change at any time. T�numericZpysqlite_numericz:1Nc s" |� dd� t� j|i |�� d S )N� paramstylert �ra r/ �__init__�r �arg�kwr3 r r rw h s z(_SQLiteDialect_pysqlite_numeric.__init__c s$ t � �|�\}}| �� |d< ||fS )N�factory)r/ re �_fix_sqlite_issue_99953)r r& ry rb r3 r r re l s z3_SQLiteDialect_pysqlite_numeric.create_connect_argsc sr dd l }| j�| jr(| j��fdd��ndd� �dd� �G ���fdd�d|j�� G � ���fd d �d |j�}|S ) Nr c s( � � | �}|r$J d� j�d| ����d S )NzFound z in )r6 �pattern)�sql�m)�nisr r � _test_sqlx s zJ_SQLiteDialect_pysqlite_numeric._fix_sqlite_issue_99953.<locals>._test_sqlc S s d S r r )r~ r r r r� ~ s c S s. | r&t | t�sJ �dd� t| d�D �S dS d S )Nc S s i | ]\}}t |�|�qS r )rX )rM �idx�valuer r r � <dictcomp>� s zk_SQLiteDialect_pysqlite_numeric._fix_sqlite_issue_99953.<locals>._numeric_param_as_dict.<locals>.<dictcomp>r r )rf �tuple� enumerate)� parametersr r r �_numeric_param_as_dict� s �zW_SQLiteDialect_pysqlite_numeric._fix_sqlite_issue_99953.<locals>._numeric_param_as_dictc s6 e Zd Zd� ���fdd� Z� ���fdd�Z� ZS )zU_SQLiteDialect_pysqlite_numeric._fix_sqlite_issue_99953.<locals>.SQLiteFix99953Cursorr c s& �|� �|v r�|�}t � �||�S r �r/ �execute�r r~ r� �r4 r� r� � first_bindr r r� � s z]_SQLiteDialect_pysqlite_numeric._fix_sqlite_issue_99953.<locals>.SQLiteFix99953Cursor.executec s0 �|� �|v r"�fdd�|D �}t � �||�S )Nc s g | ] }� |��qS r r �rM �p�r� r r � <listcomp>� s zu_SQLiteDialect_pysqlite_numeric._fix_sqlite_issue_99953.<locals>.SQLiteFix99953Cursor.executemany.<locals>.<listcomp>�r/ � executemanyr� r� r r r� � s �za_SQLiteDialect_pysqlite_numeric._fix_sqlite_issue_99953.<locals>.SQLiteFix99953Cursor.executemany)r )r r r r� r� rr r )r� r� r� r3 r �SQLiteFix99953Cursor� s r� c sF e Zd Zd �� fdd� Zd � ���fdd� Z� ���fdd�Z� ZS ) zY_SQLiteDialect_pysqlite_numeric._fix_sqlite_issue_99953.<locals>.SQLiteFix99953ConnectionNc s |d u r � }t � j|d�S )N)r{ )r/ rh )r r{ )r� r4 r r rh � s z`_SQLiteDialect_pysqlite_numeric._fix_sqlite_issue_99953.<locals>.SQLiteFix99953Connection.cursorr c s& �|� �|v r�|�}t � �||�S r r� r� r� r r r� � s za_SQLiteDialect_pysqlite_numeric._fix_sqlite_issue_99953.<locals>.SQLiteFix99953Connection.executec s0 �|� �|v r"�fdd�|D �}t � �||�S )Nc s g | ] }� |��qS r r r� r� r r r� � s zy_SQLiteDialect_pysqlite_numeric._fix_sqlite_issue_99953.<locals>.SQLiteFix99953Connection.executemany.<locals>.<listcomp>r� r� r� r r r� � s �ze_SQLiteDialect_pysqlite_numeric._fix_sqlite_issue_99953.<locals>.SQLiteFix99953Connection.executemany)N)r )r r r rh r� r� rr r )r� r� r� r� r3 r �SQLiteFix99953Connection� s r� )r � _first_bind�_not_in_statement_regexp�Cursor� Connection)r r r� r )r� r� r� r� r� r r| q s z7_SQLiteDialect_pysqlite_numeric._fix_sqlite_issue_99953) r r r �__doc__rk rj ro r� r� rw re r| rr r r r3 r rs Y s rs c s: e Zd ZdZdZdZdZdZe� d�Z � fdd�Z � Z S ) � _SQLiteDialect_pysqlite_dollarz�numeric dialect that uses $ for testing only internal use only. This dialect is **NOT** supported by SQLAlchemy and may change at any time. T�numeric_dollarZpysqlite_dollarz$1z [^\d]:\d+c s" |� dd� t� j|i |�� d S )Nru r� rv rx r3 r r rw � s z'_SQLiteDialect_pysqlite_dollar.__init__) r r r r� rk rj ro r� r5 �compiler� rw rr r r r3 r r� � s r� )r� rA r^ r5 �baser r r r- r r r rl r r r r r rs r� r r r r �<module> s( !W sqlalchemy/dialects/sqlite/__pycache__/json.cpython-39.pyc 0000644 00000006243 15125143220 0017611 0 ustar 00 a ��Jh� � @ s\ d dl mZ G dd� dej�ZG dd� d�ZG dd� deejj�ZG dd � d eejj�Zd S ) � )�typesc @ s e Zd ZdZdS )�JSONa� SQLite JSON type. SQLite supports JSON as of version 3.9 through its JSON1_ extension. Note that JSON1_ is a `loadable extension <https://www.sqlite.org/loadext.html>`_ and as such may not be available, or may require run-time loading. :class:`_sqlite.JSON` is used automatically whenever the base :class:`_types.JSON` datatype is used against a SQLite backend. .. seealso:: :class:`_types.JSON` - main documentation for the generic cross-platform JSON datatype. The :class:`_sqlite.JSON` type supports persistence of JSON values as well as the core index operations provided by :class:`_types.JSON` datatype, by adapting the operations to render the ``JSON_EXTRACT`` function wrapped in the ``JSON_QUOTE`` function at the database level. Extracted values are quoted in order to ensure that the results are always JSON string values. .. versionadded:: 1.3 .. _JSON1: https://www.sqlite.org/json1.html N)�__name__� __module__� __qualname__�__doc__� r r �T/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/sqlite/json.pyr s r c @ s$ e Zd Zdd� Zdd� Zdd� ZdS )�_FormatTypeMixinc C s t � �d S �N)�NotImplementedError��self�valuer r r � _format_value0 s z _FormatTypeMixin._format_valuec s � � |��� �fdd�}|S )Nc s � � | �} �r�| �} | S r �r �r �r Z super_procr r �process6 s z0_FormatTypeMixin.bind_processor.<locals>.process)Zstring_bind_processor�r �dialectr r r r �bind_processor3 s z _FormatTypeMixin.bind_processorc s � � |��� �fdd�}|S )Nc s � � | �} �r�| �} | S r r r r r r r A s z3_FormatTypeMixin.literal_processor.<locals>.process)Zstring_literal_processorr r r r �literal_processor> s z"_FormatTypeMixin.literal_processorN)r r r r r r r r r r r / s r c @ s e Zd Zdd� ZdS )� JSONIndexTypec C s t |t�rd| }nd| }|S )Nz$[%s]z$."%s"�� isinstance�intr r r r r K s zJSONIndexType._format_valueN�r r r r r r r r r J s r c @ s e Zd Zdd� ZdS )� JSONPathTypec C s dd� dd� |D �� S )Nz$%s� c S s& g | ] }t |t�rd | nd| �qS )z[%s]z."%s"r )�.0�elemr r r � <listcomp>W s �z.JSONPathType._format_value.<locals>.<listcomp>)�joinr r r r r T s ���zJSONPathType._format_valueNr r r r r r S s r N)r r Zsqltypesr r r r r r r r �<module> s # sqlalchemy/dialects/sqlite/__pycache__/base.cpython-39.pyc 0000644 00000241127 15125143220 0017554 0 ustar 00 a ��Jh�� � @ s� d Z ddlmZ ddlZddlZddlZddlmZ ddlm Z ddlm Z ddlm Z d d l m Z d d l mZ d d l mZ d d l mZ d dl mZ d dl mZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlm Z d dlm Z d dlm Z d d lmZ d dlm Z d dlm Z d dlm!Z! d dlm"Z" d d lm#Z# d d lm$Z$ d d lm%Z% d d lm&Z& d d lm'Z' d d!lm(Z( d d"lm)Z) d d#lm*Z* G d$d%� d%e �Z+G d&d'� d'�Z,G d(d)� d)e,ej-�Z.G d*d+� d+e,ej/�Z0G d,d-� d-e,ej1�Z2ej/e0ej-e.ej e+ej j e ej j e ej1e2iZ3ej4ej ej ej ej!ej0ej0ej.ej.ej5ej"ej#ej$ej$e ej%ej&ej'ej(ej2ej2ej)ej*ej6ej7d.�Z8G d/d0� d0e j9�Z:G d1d2� d2e j;�Z<G d3d4� d4e j=�Z>G d5d6� d6e j?�Z@G d7d8� d8ejA�ZBG d9d:� d:ejC�ZDdS );a�� .. dialect:: sqlite :name: SQLite :normal_support: 3.12+ :best_effort: 3.7.16+ .. _sqlite_datetime: Date and Time Types ------------------- SQLite does not have built-in DATE, TIME, or DATETIME types, and pysqlite does not provide out of the box functionality for translating values between Python `datetime` objects and a SQLite-supported format. SQLAlchemy's own :class:`~sqlalchemy.types.DateTime` and related types provide date formatting and parsing functionality when SQLite is used. The implementation classes are :class:`_sqlite.DATETIME`, :class:`_sqlite.DATE` and :class:`_sqlite.TIME`. These types represent dates and times as ISO formatted strings, which also nicely support ordering. There's no reliance on typical "libc" internals for these functions so historical dates are fully supported. Ensuring Text affinity ^^^^^^^^^^^^^^^^^^^^^^ The DDL rendered for these types is the standard ``DATE``, ``TIME`` and ``DATETIME`` indicators. However, custom storage formats can also be applied to these types. When the storage format is detected as containing no alpha characters, the DDL for these types is rendered as ``DATE_CHAR``, ``TIME_CHAR``, and ``DATETIME_CHAR``, so that the column continues to have textual affinity. .. seealso:: `Type Affinity <https://www.sqlite.org/datatype3.html#affinity>`_ - in the SQLite documentation .. _sqlite_autoincrement: SQLite Auto Incrementing Behavior ---------------------------------- Background on SQLite's autoincrement is at: https://sqlite.org/autoinc.html Key concepts: * SQLite has an implicit "auto increment" feature that takes place for any non-composite primary-key column that is specifically created using "INTEGER PRIMARY KEY" for the type + primary key. * SQLite also has an explicit "AUTOINCREMENT" keyword, that is **not** equivalent to the implicit autoincrement feature; this keyword is not recommended for general use. SQLAlchemy does not render this keyword unless a special SQLite-specific directive is used (see below). However, it still requires that the column's type is named "INTEGER". Using the AUTOINCREMENT Keyword ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To specifically render the AUTOINCREMENT keyword on the primary key column when rendering DDL, add the flag ``sqlite_autoincrement=True`` to the Table construct:: Table( "sometable", metadata, Column("id", Integer, primary_key=True), sqlite_autoincrement=True, ) Allowing autoincrement behavior SQLAlchemy types other than Integer/INTEGER ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ SQLite's typing model is based on naming conventions. Among other things, this means that any type name which contains the substring ``"INT"`` will be determined to be of "integer affinity". A type named ``"BIGINT"``, ``"SPECIAL_INT"`` or even ``"XYZINTQPR"``, will be considered by SQLite to be of "integer" affinity. However, **the SQLite autoincrement feature, whether implicitly or explicitly enabled, requires that the name of the column's type is exactly the string "INTEGER"**. Therefore, if an application uses a type like :class:`.BigInteger` for a primary key, on SQLite this type will need to be rendered as the name ``"INTEGER"`` when emitting the initial ``CREATE TABLE`` statement in order for the autoincrement behavior to be available. One approach to achieve this is to use :class:`.Integer` on SQLite only using :meth:`.TypeEngine.with_variant`:: table = Table( "my_table", metadata, Column( "id", BigInteger().with_variant(Integer, "sqlite"), primary_key=True, ), ) Another is to use a subclass of :class:`.BigInteger` that overrides its DDL name to be ``INTEGER`` when compiled against SQLite:: from sqlalchemy import BigInteger from sqlalchemy.ext.compiler import compiles class SLBigInteger(BigInteger): pass @compiles(SLBigInteger, "sqlite") def bi_c(element, compiler, **kw): return "INTEGER" @compiles(SLBigInteger) def bi_c(element, compiler, **kw): return compiler.visit_BIGINT(element, **kw) table = Table( "my_table", metadata, Column("id", SLBigInteger(), primary_key=True) ) .. seealso:: :meth:`.TypeEngine.with_variant` :ref:`sqlalchemy.ext.compiler_toplevel` `Datatypes In SQLite Version 3 <https://sqlite.org/datatype3.html>`_ .. _sqlite_transactions: Transactions with SQLite and the sqlite3 driver ----------------------------------------------- As a file-based database, SQLite's approach to transactions differs from traditional databases in many ways. Additionally, the ``sqlite3`` driver standard with Python (as well as the async version ``aiosqlite`` which builds on top of it) has several quirks, workarounds, and API features in the area of transaction control, all of which generally need to be addressed when constructing a SQLAlchemy application that uses SQLite. Legacy Transaction Mode with the sqlite3 driver ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The most important aspect of transaction handling with the sqlite3 driver is that it defaults (which will continue through Python 3.15 before being removed in Python 3.16) to legacy transactional behavior which does not strictly follow :pep:`249`. The way in which the driver diverges from the PEP is that it does not "begin" a transaction automatically as dictated by :pep:`249` except in the case of DML statements, e.g. INSERT, UPDATE, and DELETE. Normally, :pep:`249` dictates that a BEGIN must be emitted upon the first SQL statement of any kind, so that all subsequent operations will be established within a transaction until ``connection.commit()`` has been called. The ``sqlite3`` driver, in an effort to be easier to use in highly concurrent environments, skips this step for DQL (e.g. SELECT) statements, and also skips it for DDL (e.g. CREATE TABLE etc.) statements for more legacy reasons. Statements such as SAVEPOINT are also skipped. In modern versions of the ``sqlite3`` driver as of Python 3.12, this legacy mode of operation is referred to as `"legacy transaction control" <https://docs.python.org/3/library/sqlite3.html#sqlite3-transaction-control-isolation-level>`_, and is in effect by default due to the ``Connection.autocommit`` parameter being set to the constant ``sqlite3.LEGACY_TRANSACTION_CONTROL``. Prior to Python 3.12, the ``Connection.autocommit`` attribute did not exist. The implications of legacy transaction mode include: * **Incorrect support for transactional DDL** - statements like CREATE TABLE, ALTER TABLE, CREATE INDEX etc. will not automatically BEGIN a transaction if one were not started already, leading to the changes by each statement being "autocommitted" immediately unless BEGIN were otherwise emitted first. Very old (pre Python 3.6) versions of SQLite would also force a COMMIT for these operations even if a transaction were present, however this is no longer the case. * **SERIALIZABLE behavior not fully functional** - SQLite's transaction isolation behavior is normally consistent with SERIALIZABLE isolation, as it is a file- based system that locks the database file entirely for write operations, preventing COMMIT until all reader transactions (and associated file locks) have completed. However, sqlite3's legacy transaction mode fails to emit BEGIN for SELECT statements, which causes these SELECT statements to no longer be "repeatable", failing one of the consistency guarantees of SERIALIZABLE. * **Incorrect behavior for SAVEPOINT** - as the SAVEPOINT statement does not imply a BEGIN, a new SAVEPOINT emitted before a BEGIN will function on its own but fails to participate in the enclosing transaction, meaning a ROLLBACK of the transaction will not rollback elements that were part of a released savepoint. Legacy transaction mode first existed in order to faciliate working around SQLite's file locks. Because SQLite relies upon whole-file locks, it is easy to get "database is locked" errors, particularly when newer features like "write ahead logging" are disabled. This is a key reason why ``sqlite3``'s legacy transaction mode is still the default mode of operation; disabling it will produce behavior that is more susceptible to locked database errors. However note that **legacy transaction mode will no longer be the default** in a future Python version (3.16 as of this writing). .. _sqlite_enabling_transactions: Enabling Non-Legacy SQLite Transactional Modes with the sqlite3 or aiosqlite driver ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Current SQLAlchemy support allows either for setting the ``.Connection.autocommit`` attribute, most directly by using a :func:`._sa.create_engine` parameter, or if on an older version of Python where the attribute is not available, using event hooks to control the behavior of BEGIN. * **Enabling modern sqlite3 transaction control via the autocommit connect parameter** (Python 3.12 and above) To use SQLite in the mode described at `Transaction control via the autocommit attribute <https://docs.python.org/3/library/sqlite3.html#transaction-control-via-the-autocommit-attribute>`_, the most straightforward approach is to set the attribute to its recommended value of ``False`` at the connect level using :paramref:`_sa.create_engine.connect_args``:: from sqlalchemy import create_engine engine = create_engine( "sqlite:///myfile.db", connect_args={"autocommit": False} ) This parameter is also passed through when using the aiosqlite driver:: from sqlalchemy.ext.asyncio import create_async_engine engine = create_async_engine( "sqlite+aiosqlite:///myfile.db", connect_args={"autocommit": False} ) The parameter can also be set at the attribute level using the :meth:`.PoolEvents.connect` event hook, however this will only work for sqlite3, as aiosqlite does not yet expose this attribute on its ``Connection`` object:: from sqlalchemy import create_engine, event engine = create_engine("sqlite:///myfile.db") @event.listens_for(engine, "connect") def do_connect(dbapi_connection, connection_record): # enable autocommit=False mode dbapi_connection.autocommit = False * **Using SQLAlchemy to emit BEGIN in lieu of SQLite's transaction control** (all Python versions, sqlite3 and aiosqlite) For older versions of ``sqlite3`` or for cross-compatiblity with older and newer versions, SQLAlchemy can also take over the job of transaction control. This is achieved by using the :meth:`.ConnectionEvents.begin` hook to emit the "BEGIN" command directly, while also disabling SQLite's control of this command using the :meth:`.PoolEvents.connect` event hook to set the ``Connection.isolation_level`` attribute to ``None``:: from sqlalchemy import create_engine, event engine = create_engine("sqlite:///myfile.db") @event.listens_for(engine, "connect") def do_connect(dbapi_connection, connection_record): # disable sqlite3's emitting of the BEGIN statement entirely. dbapi_connection.isolation_level = None @event.listens_for(engine, "begin") def do_begin(conn): # emit our own BEGIN. sqlite3 still emits COMMIT/ROLLBACK correctly conn.exec_driver_sql("BEGIN") When using the asyncio variant ``aiosqlite``, refer to ``engine.sync_engine`` as in the example below:: from sqlalchemy import create_engine, event from sqlalchemy.ext.asyncio import create_async_engine engine = create_async_engine("sqlite+aiosqlite:///myfile.db") @event.listens_for(engine.sync_engine, "connect") def do_connect(dbapi_connection, connection_record): # disable aiosqlite's emitting of the BEGIN statement entirely. dbapi_connection.isolation_level = None @event.listens_for(engine.sync_engine, "begin") def do_begin(conn): # emit our own BEGIN. aiosqlite still emits COMMIT/ROLLBACK correctly conn.exec_driver_sql("BEGIN") .. _sqlite_isolation_level: Using SQLAlchemy's Driver Level AUTOCOMMIT Feature with SQLite ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ SQLAlchemy has a comprehensive database isolation feature with optional autocommit support that is introduced in the section :ref:`dbapi_autocommit`. For the ``sqlite3`` and ``aiosqlite`` drivers, SQLAlchemy only includes built-in support for "AUTOCOMMIT". Note that this mode is currently incompatible with the non-legacy isolation mode hooks documented in the previous section at :ref:`sqlite_enabling_transactions`. To use the ``sqlite3`` driver with SQLAlchemy driver-level autocommit, create an engine setting the :paramref:`_sa.create_engine.isolation_level` parameter to "AUTOCOMMIT":: eng = create_engine("sqlite:///myfile.db", isolation_level="AUTOCOMMIT") When using the above mode, any event hooks that set the sqlite3 ``Connection.autocommit`` parameter away from its default of ``sqlite3.LEGACY_TRANSACTION_CONTROL`` as well as hooks that emit ``BEGIN`` should be disabled. Additional Reading for SQLite / sqlite3 transaction control ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Links with important information on SQLite, the sqlite3 driver, as well as long historical conversations on how things got to their current state: * `Isolation in SQLite <https://www.sqlite.org/isolation.html>`_ - on the SQLite website * `Transaction control <https://docs.python.org/3/library/sqlite3.html#transaction-control>`_ - describes the sqlite3 autocommit attribute as well as the legacy isolation_level attribute. * `sqlite3 SELECT does not BEGIN a transaction, but should according to spec <https://github.com/python/cpython/issues/54133>`_ - imported Python standard library issue on github * `sqlite3 module breaks transactions and potentially corrupts data <https://github.com/python/cpython/issues/54949>`_ - imported Python standard library issue on github INSERT/UPDATE/DELETE...RETURNING --------------------------------- The SQLite dialect supports SQLite 3.35's ``INSERT|UPDATE|DELETE..RETURNING`` syntax. ``INSERT..RETURNING`` may be used automatically in some cases in order to fetch newly generated identifiers in place of the traditional approach of using ``cursor.lastrowid``, however ``cursor.lastrowid`` is currently still preferred for simple single-statement cases for its better performance. To specify an explicit ``RETURNING`` clause, use the :meth:`._UpdateBase.returning` method on a per-statement basis:: # INSERT..RETURNING result = connection.execute( table.insert().values(name="foo").returning(table.c.col1, table.c.col2) ) print(result.all()) # UPDATE..RETURNING result = connection.execute( table.update() .where(table.c.name == "foo") .values(name="bar") .returning(table.c.col1, table.c.col2) ) print(result.all()) # DELETE..RETURNING result = connection.execute( table.delete() .where(table.c.name == "foo") .returning(table.c.col1, table.c.col2) ) print(result.all()) .. versionadded:: 2.0 Added support for SQLite RETURNING .. _sqlite_foreign_keys: Foreign Key Support ------------------- SQLite supports FOREIGN KEY syntax when emitting CREATE statements for tables, however by default these constraints have no effect on the operation of the table. Constraint checking on SQLite has three prerequisites: * At least version 3.6.19 of SQLite must be in use * The SQLite library must be compiled *without* the SQLITE_OMIT_FOREIGN_KEY or SQLITE_OMIT_TRIGGER symbols enabled. * The ``PRAGMA foreign_keys = ON`` statement must be emitted on all connections before use -- including the initial call to :meth:`sqlalchemy.schema.MetaData.create_all`. SQLAlchemy allows for the ``PRAGMA`` statement to be emitted automatically for new connections through the usage of events:: from sqlalchemy.engine import Engine from sqlalchemy import event @event.listens_for(Engine, "connect") def set_sqlite_pragma(dbapi_connection, connection_record): cursor = dbapi_connection.cursor() cursor.execute("PRAGMA foreign_keys=ON") cursor.close() .. warning:: When SQLite foreign keys are enabled, it is **not possible** to emit CREATE or DROP statements for tables that contain mutually-dependent foreign key constraints; to emit the DDL for these tables requires that ALTER TABLE be used to create or drop these constraints separately, for which SQLite has no support. .. seealso:: `SQLite Foreign Key Support <https://www.sqlite.org/foreignkeys.html>`_ - on the SQLite web site. :ref:`event_toplevel` - SQLAlchemy event API. :ref:`use_alter` - more information on SQLAlchemy's facilities for handling mutually-dependent foreign key constraints. .. _sqlite_on_conflict_ddl: ON CONFLICT support for constraints ----------------------------------- .. seealso:: This section describes the :term:`DDL` version of "ON CONFLICT" for SQLite, which occurs within a CREATE TABLE statement. For "ON CONFLICT" as applied to an INSERT statement, see :ref:`sqlite_on_conflict_insert`. SQLite supports a non-standard DDL clause known as ON CONFLICT which can be applied to primary key, unique, check, and not null constraints. In DDL, it is rendered either within the "CONSTRAINT" clause or within the column definition itself depending on the location of the target constraint. To render this clause within DDL, the extension parameter ``sqlite_on_conflict`` can be specified with a string conflict resolution algorithm within the :class:`.PrimaryKeyConstraint`, :class:`.UniqueConstraint`, :class:`.CheckConstraint` objects. Within the :class:`_schema.Column` object, there are individual parameters ``sqlite_on_conflict_not_null``, ``sqlite_on_conflict_primary_key``, ``sqlite_on_conflict_unique`` which each correspond to the three types of relevant constraint types that can be indicated from a :class:`_schema.Column` object. .. seealso:: `ON CONFLICT <https://www.sqlite.org/lang_conflict.html>`_ - in the SQLite documentation .. versionadded:: 1.3 The ``sqlite_on_conflict`` parameters accept a string argument which is just the resolution name to be chosen, which on SQLite can be one of ROLLBACK, ABORT, FAIL, IGNORE, and REPLACE. For example, to add a UNIQUE constraint that specifies the IGNORE algorithm:: some_table = Table( "some_table", metadata, Column("id", Integer, primary_key=True), Column("data", Integer), UniqueConstraint("id", "data", sqlite_on_conflict="IGNORE"), ) The above renders CREATE TABLE DDL as: .. sourcecode:: sql CREATE TABLE some_table ( id INTEGER NOT NULL, data INTEGER, PRIMARY KEY (id), UNIQUE (id, data) ON CONFLICT IGNORE ) When using the :paramref:`_schema.Column.unique` flag to add a UNIQUE constraint to a single column, the ``sqlite_on_conflict_unique`` parameter can be added to the :class:`_schema.Column` as well, which will be added to the UNIQUE constraint in the DDL:: some_table = Table( "some_table", metadata, Column("id", Integer, primary_key=True), Column( "data", Integer, unique=True, sqlite_on_conflict_unique="IGNORE" ), ) rendering: .. sourcecode:: sql CREATE TABLE some_table ( id INTEGER NOT NULL, data INTEGER, PRIMARY KEY (id), UNIQUE (data) ON CONFLICT IGNORE ) To apply the FAIL algorithm for a NOT NULL constraint, ``sqlite_on_conflict_not_null`` is used:: some_table = Table( "some_table", metadata, Column("id", Integer, primary_key=True), Column( "data", Integer, nullable=False, sqlite_on_conflict_not_null="FAIL" ), ) this renders the column inline ON CONFLICT phrase: .. sourcecode:: sql CREATE TABLE some_table ( id INTEGER NOT NULL, data INTEGER NOT NULL ON CONFLICT FAIL, PRIMARY KEY (id) ) Similarly, for an inline primary key, use ``sqlite_on_conflict_primary_key``:: some_table = Table( "some_table", metadata, Column( "id", Integer, primary_key=True, sqlite_on_conflict_primary_key="FAIL", ), ) SQLAlchemy renders the PRIMARY KEY constraint separately, so the conflict resolution algorithm is applied to the constraint itself: .. sourcecode:: sql CREATE TABLE some_table ( id INTEGER NOT NULL, PRIMARY KEY (id) ON CONFLICT FAIL ) .. _sqlite_on_conflict_insert: INSERT...ON CONFLICT (Upsert) ----------------------------- .. seealso:: This section describes the :term:`DML` version of "ON CONFLICT" for SQLite, which occurs within an INSERT statement. For "ON CONFLICT" as applied to a CREATE TABLE statement, see :ref:`sqlite_on_conflict_ddl`. From version 3.24.0 onwards, SQLite supports "upserts" (update or insert) of rows into a table via the ``ON CONFLICT`` clause of the ``INSERT`` statement. A candidate row will only be inserted if that row does not violate any unique or primary key constraints. In the case of a unique constraint violation, a secondary action can occur which can be either "DO UPDATE", indicating that the data in the target row should be updated, or "DO NOTHING", which indicates to silently skip this row. Conflicts are determined using columns that are part of existing unique constraints and indexes. These constraints are identified by stating the columns and conditions that comprise the indexes. SQLAlchemy provides ``ON CONFLICT`` support via the SQLite-specific :func:`_sqlite.insert()` function, which provides the generative methods :meth:`_sqlite.Insert.on_conflict_do_update` and :meth:`_sqlite.Insert.on_conflict_do_nothing`: .. sourcecode:: pycon+sql >>> from sqlalchemy.dialects.sqlite import insert >>> insert_stmt = insert(my_table).values( ... id="some_existing_id", data="inserted value" ... ) >>> do_update_stmt = insert_stmt.on_conflict_do_update( ... index_elements=["id"], set_=dict(data="updated value") ... ) >>> print(do_update_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (?, ?) ON CONFLICT (id) DO UPDATE SET data = ?{stop} >>> do_nothing_stmt = insert_stmt.on_conflict_do_nothing(index_elements=["id"]) >>> print(do_nothing_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (?, ?) ON CONFLICT (id) DO NOTHING .. versionadded:: 1.4 .. seealso:: `Upsert <https://sqlite.org/lang_UPSERT.html>`_ - in the SQLite documentation. Specifying the Target ^^^^^^^^^^^^^^^^^^^^^ Both methods supply the "target" of the conflict using column inference: * The :paramref:`_sqlite.Insert.on_conflict_do_update.index_elements` argument specifies a sequence containing string column names, :class:`_schema.Column` objects, and/or SQL expression elements, which would identify a unique index or unique constraint. * When using :paramref:`_sqlite.Insert.on_conflict_do_update.index_elements` to infer an index, a partial index can be inferred by also specifying the :paramref:`_sqlite.Insert.on_conflict_do_update.index_where` parameter: .. sourcecode:: pycon+sql >>> stmt = insert(my_table).values(user_email="a@b.com", data="inserted data") >>> do_update_stmt = stmt.on_conflict_do_update( ... index_elements=[my_table.c.user_email], ... index_where=my_table.c.user_email.like("%@gmail.com"), ... set_=dict(data=stmt.excluded.data), ... ) >>> print(do_update_stmt) {printsql}INSERT INTO my_table (data, user_email) VALUES (?, ?) ON CONFLICT (user_email) WHERE user_email LIKE '%@gmail.com' DO UPDATE SET data = excluded.data The SET Clause ^^^^^^^^^^^^^^^ ``ON CONFLICT...DO UPDATE`` is used to perform an update of the already existing row, using any combination of new values as well as values from the proposed insertion. These values are specified using the :paramref:`_sqlite.Insert.on_conflict_do_update.set_` parameter. This parameter accepts a dictionary which consists of direct values for UPDATE: .. sourcecode:: pycon+sql >>> stmt = insert(my_table).values(id="some_id", data="inserted value") >>> do_update_stmt = stmt.on_conflict_do_update( ... index_elements=["id"], set_=dict(data="updated value") ... ) >>> print(do_update_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (?, ?) ON CONFLICT (id) DO UPDATE SET data = ? .. warning:: The :meth:`_sqlite.Insert.on_conflict_do_update` method does **not** take into account Python-side default UPDATE values or generation functions, e.g. those specified using :paramref:`_schema.Column.onupdate`. These values will not be exercised for an ON CONFLICT style of UPDATE, unless they are manually specified in the :paramref:`_sqlite.Insert.on_conflict_do_update.set_` dictionary. Updating using the Excluded INSERT Values ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In order to refer to the proposed insertion row, the special alias :attr:`~.sqlite.Insert.excluded` is available as an attribute on the :class:`_sqlite.Insert` object; this object creates an "excluded." prefix on a column, that informs the DO UPDATE to update the row with the value that would have been inserted had the constraint not failed: .. sourcecode:: pycon+sql >>> stmt = insert(my_table).values( ... id="some_id", data="inserted value", author="jlh" ... ) >>> do_update_stmt = stmt.on_conflict_do_update( ... index_elements=["id"], ... set_=dict(data="updated value", author=stmt.excluded.author), ... ) >>> print(do_update_stmt) {printsql}INSERT INTO my_table (id, data, author) VALUES (?, ?, ?) ON CONFLICT (id) DO UPDATE SET data = ?, author = excluded.author Additional WHERE Criteria ^^^^^^^^^^^^^^^^^^^^^^^^^ The :meth:`_sqlite.Insert.on_conflict_do_update` method also accepts a WHERE clause using the :paramref:`_sqlite.Insert.on_conflict_do_update.where` parameter, which will limit those rows which receive an UPDATE: .. sourcecode:: pycon+sql >>> stmt = insert(my_table).values( ... id="some_id", data="inserted value", author="jlh" ... ) >>> on_update_stmt = stmt.on_conflict_do_update( ... index_elements=["id"], ... set_=dict(data="updated value", author=stmt.excluded.author), ... where=(my_table.c.status == 2), ... ) >>> print(on_update_stmt) {printsql}INSERT INTO my_table (id, data, author) VALUES (?, ?, ?) ON CONFLICT (id) DO UPDATE SET data = ?, author = excluded.author WHERE my_table.status = ? Skipping Rows with DO NOTHING ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``ON CONFLICT`` may be used to skip inserting a row entirely if any conflict with a unique constraint occurs; below this is illustrated using the :meth:`_sqlite.Insert.on_conflict_do_nothing` method: .. sourcecode:: pycon+sql >>> stmt = insert(my_table).values(id="some_id", data="inserted value") >>> stmt = stmt.on_conflict_do_nothing(index_elements=["id"]) >>> print(stmt) {printsql}INSERT INTO my_table (id, data) VALUES (?, ?) ON CONFLICT (id) DO NOTHING If ``DO NOTHING`` is used without specifying any columns or constraint, it has the effect of skipping the INSERT for any unique violation which occurs: .. sourcecode:: pycon+sql >>> stmt = insert(my_table).values(id="some_id", data="inserted value") >>> stmt = stmt.on_conflict_do_nothing() >>> print(stmt) {printsql}INSERT INTO my_table (id, data) VALUES (?, ?) ON CONFLICT DO NOTHING .. _sqlite_type_reflection: Type Reflection --------------- SQLite types are unlike those of most other database backends, in that the string name of the type usually does not correspond to a "type" in a one-to-one fashion. Instead, SQLite links per-column typing behavior to one of five so-called "type affinities" based on a string matching pattern for the type. SQLAlchemy's reflection process, when inspecting types, uses a simple lookup table to link the keywords returned to provided SQLAlchemy types. This lookup table is present within the SQLite dialect as it is for all other dialects. However, the SQLite dialect has a different "fallback" routine for when a particular type name is not located in the lookup map; it instead implements the SQLite "type affinity" scheme located at https://www.sqlite.org/datatype3.html section 2.1. The provided typemap will make direct associations from an exact string name match for the following types: :class:`_types.BIGINT`, :class:`_types.BLOB`, :class:`_types.BOOLEAN`, :class:`_types.BOOLEAN`, :class:`_types.CHAR`, :class:`_types.DATE`, :class:`_types.DATETIME`, :class:`_types.FLOAT`, :class:`_types.DECIMAL`, :class:`_types.FLOAT`, :class:`_types.INTEGER`, :class:`_types.INTEGER`, :class:`_types.NUMERIC`, :class:`_types.REAL`, :class:`_types.SMALLINT`, :class:`_types.TEXT`, :class:`_types.TIME`, :class:`_types.TIMESTAMP`, :class:`_types.VARCHAR`, :class:`_types.NVARCHAR`, :class:`_types.NCHAR` When a type name does not match one of the above types, the "type affinity" lookup is used instead: * :class:`_types.INTEGER` is returned if the type name includes the string ``INT`` * :class:`_types.TEXT` is returned if the type name includes the string ``CHAR``, ``CLOB`` or ``TEXT`` * :class:`_types.NullType` is returned if the type name includes the string ``BLOB`` * :class:`_types.REAL` is returned if the type name includes the string ``REAL``, ``FLOA`` or ``DOUB``. * Otherwise, the :class:`_types.NUMERIC` type is used. .. _sqlite_partial_index: Partial Indexes --------------- A partial index, e.g. one which uses a WHERE clause, can be specified with the DDL system using the argument ``sqlite_where``:: tbl = Table("testtbl", m, Column("data", Integer)) idx = Index( "test_idx1", tbl.c.data, sqlite_where=and_(tbl.c.data > 5, tbl.c.data < 10), ) The index will be rendered at create time as: .. sourcecode:: sql CREATE INDEX test_idx1 ON testtbl (data) WHERE data > 5 AND data < 10 .. _sqlite_dotted_column_names: Dotted Column Names ------------------- Using table or column names that explicitly have periods in them is **not recommended**. While this is generally a bad idea for relational databases in general, as the dot is a syntactically significant character, the SQLite driver up until version **3.10.0** of SQLite has a bug which requires that SQLAlchemy filter out these dots in result sets. The bug, entirely outside of SQLAlchemy, can be illustrated thusly:: import sqlite3 assert sqlite3.sqlite_version_info < ( 3, 10, 0, ), "bug is fixed in this version" conn = sqlite3.connect(":memory:") cursor = conn.cursor() cursor.execute("create table x (a integer, b integer)") cursor.execute("insert into x (a, b) values (1, 1)") cursor.execute("insert into x (a, b) values (2, 2)") cursor.execute("select x.a, x.b from x") assert [c[0] for c in cursor.description] == ["a", "b"] cursor.execute( """ select x.a, x.b from x where a=1 union select x.a, x.b from x where a=2 """ ) assert [c[0] for c in cursor.description] == ["a", "b"], [ c[0] for c in cursor.description ] The second assertion fails: .. sourcecode:: text Traceback (most recent call last): File "test.py", line 19, in <module> [c[0] for c in cursor.description] AssertionError: ['x.a', 'x.b'] Where above, the driver incorrectly reports the names of the columns including the name of the table, which is entirely inconsistent vs. when the UNION is not present. SQLAlchemy relies upon column names being predictable in how they match to the original statement, so the SQLAlchemy dialect has no choice but to filter these out:: from sqlalchemy import create_engine eng = create_engine("sqlite://") conn = eng.connect() conn.exec_driver_sql("create table x (a integer, b integer)") conn.exec_driver_sql("insert into x (a, b) values (1, 1)") conn.exec_driver_sql("insert into x (a, b) values (2, 2)") result = conn.exec_driver_sql("select x.a, x.b from x") assert result.keys() == ["a", "b"] result = conn.exec_driver_sql( """ select x.a, x.b from x where a=1 union select x.a, x.b from x where a=2 """ ) assert result.keys() == ["a", "b"] Note that above, even though SQLAlchemy filters out the dots, *both names are still addressable*:: >>> row = result.first() >>> row["a"] 1 >>> row["x.a"] 1 >>> row["b"] 1 >>> row["x.b"] 1 Therefore, the workaround applied by SQLAlchemy only impacts :meth:`_engine.CursorResult.keys` and :meth:`.Row.keys()` in the public API. In the very specific case where an application is forced to use column names that contain dots, and the functionality of :meth:`_engine.CursorResult.keys` and :meth:`.Row.keys()` is required to return these dotted names unmodified, the ``sqlite_raw_colnames`` execution option may be provided, either on a per-:class:`_engine.Connection` basis:: result = conn.execution_options(sqlite_raw_colnames=True).exec_driver_sql( """ select x.a, x.b from x where a=1 union select x.a, x.b from x where a=2 """ ) assert result.keys() == ["x.a", "x.b"] or on a per-:class:`_engine.Engine` basis:: engine = create_engine( "sqlite://", execution_options={"sqlite_raw_colnames": True} ) When using the per-:class:`_engine.Engine` execution option, note that **Core and ORM queries that use UNION may not function properly**. SQLite-specific table options ----------------------------- One option for CREATE TABLE is supported directly by the SQLite dialect in conjunction with the :class:`_schema.Table` construct: * ``WITHOUT ROWID``:: Table("some_table", metadata, ..., sqlite_with_rowid=False) * ``STRICT``:: Table("some_table", metadata, ..., sqlite_strict=True) .. versionadded:: 2.0.37 .. seealso:: `SQLite CREATE TABLE options <https://www.sqlite.org/lang_createtable.html>`_ .. _sqlite_include_internal: Reflecting internal schema tables ---------------------------------- Reflection methods that return lists of tables will omit so-called "SQLite internal schema object" names, which are considered by SQLite as any object name that is prefixed with ``sqlite_``. An example of such an object is the ``sqlite_sequence`` table that's generated when the ``AUTOINCREMENT`` column parameter is used. In order to return these objects, the parameter ``sqlite_include_internal=True`` may be passed to methods such as :meth:`_schema.MetaData.reflect` or :meth:`.Inspector.get_table_names`. .. versionadded:: 2.0 Added the ``sqlite_include_internal=True`` parameter. Previously, these tables were not ignored by SQLAlchemy reflection methods. .. note:: The ``sqlite_include_internal`` parameter does not refer to the "system" tables that are present in schemas such as ``sqlite_master``. .. seealso:: `SQLite Internal Schema Objects <https://www.sqlite.org/fileformat2.html#intschema>`_ - in the SQLite documentation. � )� annotationsN)�Optional� )�JSON)� JSONIndexType)� JSONPathType� )�exc��schema)�sql)�text)�types)�util)�default)� processors)� reflection)�ReflectionDefaults)� coercions)�compiler)�elements)�roles)�BLOB)�BOOLEAN)�CHAR)�DECIMAL)�FLOAT)�INTEGER)�NUMERIC)�REAL)�SMALLINT)�TEXT)� TIMESTAMP)�VARCHARc s e Zd Z� fdd�Z� ZS )� _SQliteJsonc s t � �||�� � fdd�}|S )Nc s8 z � | �W S t y2 t| tj�r,| Y S � Y n0 d S �N)� TypeError� isinstance�numbers�Number��value�Zdefault_processor� �T/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/sqlite/base.py�process s z-_SQliteJson.result_processor.<locals>.process)�super�result_processor)�self�dialect�coltyper/ �� __class__r, r. r1 � s z _SQliteJson.result_processor)�__name__� __module__� __qualname__r1 � __classcell__r- r- r5 r. r$ � s r$ c sF e Zd ZdZdZd � fdd� Zedd� �Z� fdd�Zdd � Z � Z S ) �_DateTimeMixinNc s8 t � jf i |�� |d ur&t�|�| _|d ur4|| _d S r% )r0 �__init__�re�compile�_reg�_storage_format)r2 �storage_format�regexp�kwr5 r- r. r< s z_DateTimeMixin.__init__c C s* | j dddddddd� }tt�d|��S )a? return True if the storage format will automatically imply a TEXT affinity. If the storage format contains no non-numeric characters, it will imply a NUMERIC storage format on SQLite; in this case, the type will generate its DDL as DATE_CHAR, DATETIME_CHAR, TIME_CHAR. r ��year�month�day�hour�minute�second� microsecondz[^0-9])r@ �boolr= �search)r2 �specr- r- r. �format_is_text_affinity s � z&_DateTimeMixin.format_is_text_affinityc s> t |t�r*| jr| j|d< | jr*| j|d< t� j|fi |��S )NrA rB )� issubclassr; r@ r? r0 �adapt)r2 �clsrC r5 r- r. rQ . s z_DateTimeMixin.adaptc s | � |�� � fdd�}|S )Nc s d� | � S )N�'%s'r- r* �Zbpr- r. r/ 9 s z1_DateTimeMixin.literal_processor.<locals>.process)�bind_processor�r2 r3 r/ r- rT r. �literal_processor6 s z _DateTimeMixin.literal_processor)NN) r7 r8 r9 r? r@ r< �propertyrO rQ rW r: r- r- r5 r. r; s r; c s4 e Zd ZdZdZ� fdd�Zdd� Zdd� Z� ZS ) �DATETIMEa� Represent a Python datetime object in SQLite using a string. The default string storage format is:: "%(year)04d-%(month)02d-%(day)02d %(hour)02d:%(minute)02d:%(second)02d.%(microsecond)06d" e.g.: .. sourcecode:: text 2021-03-15 12:05:57.105542 The incoming storage format is by default parsed using the Python ``datetime.fromisoformat()`` function. .. versionchanged:: 2.0 ``datetime.fromisoformat()`` is used for default datetime string parsing. The storage format can be customized to some degree using the ``storage_format`` and ``regexp`` parameters, such as:: import re from sqlalchemy.dialects.sqlite import DATETIME dt = DATETIME( storage_format=( "%(year)04d/%(month)02d/%(day)02d %(hour)02d:%(minute)02d:%(second)02d" ), regexp=r"(\d+)/(\d+)/(\d+) (\d+)-(\d+)-(\d+)", ) :param truncate_microseconds: when ``True`` microseconds will be truncated from the datetime. Can't be specified together with ``storage_format`` or ``regexp``. :param storage_format: format string which will be applied to the dict with keys year, month, day, hour, minute, second, and microsecond. :param regexp: regular expression which will be applied to incoming result rows, replacing the use of ``datetime.fromisoformat()`` to parse incoming strings. If the regexp contains named groups, the resulting match dict is applied to the Python datetime() constructor as keyword arguments. Otherwise, if positional groups are used, the datetime() constructor is called with positional arguments via ``*map(int, match_obj.groups(0))``. zW%(year)04d-%(month)02d-%(day)02d %(hour)02d:%(minute)02d:%(second)02d.%(microsecond)06dc sL |� dd�}t� j|i |�� |rHd|vs2J d��d|vsBJ d��d| _d S )N�truncate_microsecondsFrA �DYou can specify only one of truncate_microseconds or storage_format.rB �<You can specify only one of truncate_microseconds or regexp.zE%(year)04d-%(month)02d-%(day)02d %(hour)02d:%(minute)02d:%(second)02d��popr0 r< r@ �r2 �args�kwargsrZ r5 r- r. r< u s � ��zDATETIME.__init__c s& t j �t j� | j�� ��fdd�}|S )Nc sp | d u r d S t | ��r<�| j| j| j| j| j| j| jd� S t | � �rd�| j| j| jddddd� S td��d S )NrD r zLSQLite DateTime type only accepts Python datetime and date objects as input.) r' rE rF rG rH rI rJ rK r& r* �� datetime_dateZdatetime_datetime�format_r- r. r/ � s2 � � �z(DATETIME.bind_processor.<locals>.process��datetime�dater@ rV r- rb r. rU � s zDATETIME.bind_processorc C s | j rt�| j tj�S tjS d S r% )r? r �!str_to_datetime_processor_factoryrf Zstr_to_datetime�r2 r3 r4 r- r- r. r1 � s �zDATETIME.result_processor� r7 r8 r9 �__doc__r@ r< rU r1 r: r- r- r5 r. rY ? s 1� $rY c @ s$ e Zd ZdZdZdd� Zdd� ZdS )�DATEaN Represent a Python date object in SQLite using a string. The default string storage format is:: "%(year)04d-%(month)02d-%(day)02d" e.g.: .. sourcecode:: text 2011-03-15 The incoming storage format is by default parsed using the Python ``date.fromisoformat()`` function. .. versionchanged:: 2.0 ``date.fromisoformat()`` is used for default date string parsing. The storage format can be customized to some degree using the ``storage_format`` and ``regexp`` parameters, such as:: import re from sqlalchemy.dialects.sqlite import DATE d = DATE( storage_format="%(month)02d/%(day)02d/%(year)04d", regexp=re.compile("(?P<month>\d+)/(?P<day>\d+)/(?P<year>\d+)"), ) :param storage_format: format string which will be applied to the dict with keys year, month, and day. :param regexp: regular expression which will be applied to incoming result rows, replacing the use of ``date.fromisoformat()`` to parse incoming strings. If the regexp contains named groups, the resulting match dict is applied to the Python date() constructor as keyword arguments. Otherwise, if positional groups are used, the date() constructor is called with positional arguments via ``*map(int, match_obj.groups(0))``. z %(year)04d-%(month)02d-%(day)02dc s t j� | j�� �fdd�}|S )Nc s8 | d u r d S t | � �r,�| j| j| jd� S td��d S )N)rE rF rG z;SQLite Date type only accepts Python date objects as input.)r' rE rF rG r& r* �rc rd r- r. r/ � s ��z$DATE.bind_processor.<locals>.processre rV r- rm r. rU � s zDATE.bind_processorc C s | j rt�| j tj�S tjS d S r% )r? r rh rf rg Z str_to_dateri r- r- r. r1 � s �zDATE.result_processorN)r7 r8 r9 rk r@ rU r1 r- r- r- r. rl � s +rl c s4 e Zd ZdZdZ� fdd�Zdd� Zdd� Z� ZS ) �TIMEa- Represent a Python time object in SQLite using a string. The default string storage format is:: "%(hour)02d:%(minute)02d:%(second)02d.%(microsecond)06d" e.g.: .. sourcecode:: text 12:05:57.10558 The incoming storage format is by default parsed using the Python ``time.fromisoformat()`` function. .. versionchanged:: 2.0 ``time.fromisoformat()`` is used for default time string parsing. The storage format can be customized to some degree using the ``storage_format`` and ``regexp`` parameters, such as:: import re from sqlalchemy.dialects.sqlite import TIME t = TIME( storage_format="%(hour)02d-%(minute)02d-%(second)02d-%(microsecond)06d", regexp=re.compile("(\d+)-(\d+)-(\d+)-(?:-(\d+))?"), ) :param truncate_microseconds: when ``True`` microseconds will be truncated from the time. Can't be specified together with ``storage_format`` or ``regexp``. :param storage_format: format string which will be applied to the dict with keys hour, minute, second, and microsecond. :param regexp: regular expression which will be applied to incoming result rows, replacing the use of ``datetime.fromisoformat()`` to parse incoming strings. If the regexp contains named groups, the resulting match dict is applied to the Python time() constructor as keyword arguments. Otherwise, if positional groups are used, the time() constructor is called with positional arguments via ``*map(int, match_obj.groups(0))``. z6%(hour)02d:%(minute)02d:%(second)02d.%(microsecond)06dc sL |� dd�}t� j|i |�� |rHd|vs2J d��d|vsBJ d��d| _d S )NrZ FrA r[ rB r\ z$%(hour)02d:%(minute)02d:%(second)02dr] r_ r5 r- r. r< / s � �z TIME.__init__c s t j� | j�� �fdd�}|S )Nc s< | d u r d S t | � �r0�| j| j| j| jd� S td��d S )N)rH rI rJ rK z;SQLite Time type only accepts Python time objects as input.)r' rH rI rJ rK r& r* �Z datetime_timerd r- r. r/ A s ��z$TIME.bind_processor.<locals>.process)rf �timer@ rV r- ro r. rU = s zTIME.bind_processorc C s | j rt�| j tj�S tjS d S r% )r? r rh rf rp Z str_to_timeri r- r- r. r1 S s �zTIME.result_processorrj r- r- r5 r. rn � s - rn )�BIGINTr ZBOOLr r rl � DATE_CHARrY � DATETIME_CHAR�DOUBLEr r �INTr r r r r r! rn � TIME_CHARr" r# �NVARCHAR�NCHARc s e Zd Ze�ejjddddddddd d d � �Zd d � Zdd� Z dd� Z dd� Z dd� Z dd� Z dd� Z� fdd�Zd d � Z� fd d �Zd d!� Zd"d#� Zd$d%� Zd&d'� Zd(d)� Zd*d+� Zd,d-� Zd.d/� Zd0d1� Zd2d3� Zd4d5� Z d6d7� Z d8d9� Z d:d;� Z d<d=� Z � Z!S )>�SQLiteCompilerz%mz%dz%Yz%Sz%Hz%jz%Mz%sz%wz%W) rF rG rE rJ rH ZdoyrI �epochZdow�weekc K s0 | j |jfi |��d d| j |jfi |�� S )Nz / z (%s + 0.0)�r/ �left�right�r2 �binary�operatorrC r- r- r. �visit_truediv_binary� s ���z#SQLiteCompiler.visit_truediv_binaryc K s dS )NZCURRENT_TIMESTAMPr- �r2 �fnrC r- r- r. �visit_now_func� s z SQLiteCompiler.visit_now_funcc K s dS )Nz(DATETIME(CURRENT_TIMESTAMP, 'localtime')r- )r2 �funcrC r- r- r. �visit_localtimestamp_func� s z(SQLiteCompiler.visit_localtimestamp_funcc K s dS )N�1r- �r2 �exprrC r- r- r. � visit_true� s zSQLiteCompiler.visit_truec K s dS )N�0r- r� r- r- r. � visit_false� s zSQLiteCompiler.visit_falsec K s d| � |� S )Nzlength%s�Zfunction_argspecr� r- r- r. �visit_char_length_func� s z%SQLiteCompiler.visit_char_length_funcc K s d| � |� S )Nzgroup_concat%sr� r� r- r- r. � visit_aggregate_strings_func� s z+SQLiteCompiler.visit_aggregate_strings_funcc s4 | j jr t� j|fi |��S | j|jfi |��S d S r% )r3 � supports_castr0 � visit_castr/ �clause)r2 �castra r5 r- r. r� � s zSQLiteCompiler.visit_castc K sb z&d| j |j | j|jfi |��f W S ty\ } z t�d|j �|�W Y d }~n d }~0 0 d S )Nz#CAST(STRFTIME('%s', %s) AS INTEGER)z#%s is not a valid extract argument.)� extract_map�fieldr/ r� �KeyErrorr � CompileError)r2 �extractrC �errr- r- r. � visit_extract� s ���z SQLiteCompiler.visit_extractc s" d|d< t � j||fd|i|��S )NF� include_table�populate_result_map)r0 �returning_clause)r2 �stmtZreturning_colsr� rC r5 r- r. r� � s ���z SQLiteCompiler.returning_clausec K s� d}|j d ur*|d| j|j fi |�� 7 }|jd urt|j d u rV|d| �t�d�� 7 }|d| j|jfi |�� 7 }n |d| jt�d�fi |�� 7 }|S )N� z LIMIT ���z OFFSET r )Z _limit_clauser/ Z_offset_clauser �literal)r2 �selectrC r r- r- r. � limit_clause� s zSQLiteCompiler.limit_clausec K s dS )Nr� r- )r2 r� rC r- r- r. �for_update_clause� s z SQLiteCompiler.for_update_clausec s( d�d< dd� � ��fdd�|D �� S )NTZasfromzFROM �, c 3 s$ | ] }|j �fd � i���V qdS )Z fromhintsN)Z_compiler_dispatch)�.0�t�� from_hintsrC r2 r- r. � <genexpr>� s �z4SQLiteCompiler.update_from_clause.<locals>.<genexpr>)�join)r2 Z update_stmtZ from_tableZ extra_fromsr� rC r- r� r. �update_from_clause� s �z!SQLiteCompiler.update_from_clausec K s d| � |j�| � |j�f S )Nz %s IS NOT %sr| r r- r- r. � visit_is_distinct_from_binary� s �z,SQLiteCompiler.visit_is_distinct_from_binaryc K s d| � |j�| � |j�f S )Nz%s IS %sr| r r- r- r. �!visit_is_not_distinct_from_binary� s �z0SQLiteCompiler.visit_is_not_distinct_from_binaryc K sD |j jtju rd}nd}|| j|jfi |��| j|jfi |��f S �Nz JSON_QUOTE(JSON_EXTRACT(%s, %s))zJSON_EXTRACT(%s, %s)��type�_type_affinity�sqltypesr r/ r} r~ �r2 r� r� rC r� r- r- r. � visit_json_getitem_op_binary� s �z+SQLiteCompiler.visit_json_getitem_op_binaryc K sD |j jtju rd}nd}|| j|jfi |��| j|jfi |��f S r� r� r� r- r- r. �!visit_json_path_getitem_op_binary� s �z0SQLiteCompiler.visit_json_path_getitem_op_binaryc K s | � |�S r% )�visit_empty_set_expr)r2 �type_Z expand_oprC r- r- r. �visit_empty_set_op_expr s z&SQLiteCompiler.visit_empty_set_op_exprc K s< dd� dd� |pt� gD ��d� dd� |p0t� gD ��f S )Nz%SELECT %s FROM (SELECT %s) WHERE 1!=1r� c s s | ] }d V qdS �r� Nr- �r� r� r- r- r. r� � z6SQLiteCompiler.visit_empty_set_expr.<locals>.<genexpr>c s s | ] }d V qdS r� r- r� r- r- r. r� r� )r� r )r2 Z element_typesrC r- r- r. r� s �z#SQLiteCompiler.visit_empty_set_exprc K s | j |dfi |��S )Nz REGEXP �Z_generate_generic_binaryr r- r- r. � visit_regexp_match_op_binary s z+SQLiteCompiler.visit_regexp_match_op_binaryc K s | j |dfi |��S )Nz NOT REGEXP r� r r- r- r. � visit_not_regexp_match_op_binary s z/SQLiteCompiler.visit_not_regexp_match_op_binaryc sX |j d urPdd�� fdd�|j D �� }|jd urT|d� j|jdddd� 7 }nd }|S ) Nz(%s)r� c 3 s4 | ],}t |t�r � j�|�n� j|d d d�V qdS )F�r� � use_schemaN)r' �str�preparer�quoter/ �r� �c�r2 r- r. r� s ��z5SQLiteCompiler._on_conflict_target.<locals>.<genexpr>� WHERE %sFT)r� r� Zliteral_executer� )Zinferred_target_elementsr� Zinferred_target_whereclauser/ )r2 r� rC � target_textr- r� r. �_on_conflict_target s � � z"SQLiteCompiler._on_conflict_targetc K s& | j |fi |��}|r d| S dS d S )NzON CONFLICT %s DO NOTHINGzON CONFLICT DO NOTHING)r� )r2 � on_conflictrC r� r- r- r. � visit_on_conflict_do_nothing- s z+SQLiteCompiler.visit_on_conflict_do_nothingc K s� |}| j |fi |��}g }t|j�}| jd d }|jj}|D ]�} | j} | |v r\|�| �} n| |v r>|�| �} nq>t� | �r�t j d | | j d�} n$t | t j �r�| j jr�| �� } | j | _ | j| �� dd�} | j�| j�} |�d| | f � q>|�rzt�d| jjjd�d d � |D ��f � |�� D ]Z\}}t |t��r>| j�|�n | j|dd�} | jt� t j |�dd�} |�d| | f � �q d�|�}|j d u�r�|d | j|j d dd � 7 }d||f S )Nr� Z selectable)r� F�r� z%s = %szFAdditional column names not matching any column keys in table '%s': %sr� c s s | ]}d | V qdS )rS Nr- r� r- r- r. r� a r� z=SQLiteCompiler.visit_on_conflict_do_update.<locals>.<genexpr>r� Tr� z ON CONFLICT %s DO UPDATE SET %s) r� �dictZupdate_values_to_set�stack�tabler� �keyr^ r Z _is_literalr Z BindParameterr� r' Z_isnullZ_cloner/ Z self_groupr� r� �name�appendr �warnZcurrent_executabler� �itemsr� �expectr ZExpressionElementRoleZupdate_whereclause)r2 r� rC r� r� Zaction_set_opsZset_parametersZinsert_statement�colsr� Zcol_keyr+ Z value_textZkey_text�k�vZ action_textr- r- r. �visit_on_conflict_do_update5 s` ������ � � � z*SQLiteCompiler.visit_on_conflict_do_updatec K sB d|d< | j |dfi |��}| j |dfi |��}d|� d|� d�S )NTZeager_groupingz | z & �(z - �)r� )r2 r� r� rC �or_�and_r- r- r. �visit_bitwise_xor_op_binaryx s z*SQLiteCompiler.visit_bitwise_xor_op_binary)"r7 r8 r9 r Z update_copyr � SQLCompilerr� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r: r- r- r5 r. ry � sN �� Cry c sn e Zd Zdd� Z� fdd�Z� fdd�Z� fdd�Z� fd d �Z� fd d �Zd d� Z ddd�Z dd� Z � Z S )�SQLiteDDLCompilerc K sh | j jj|j|d�}| j�|�d | }| �|�}|d urrt�d|�sdt�d|�rd|d|� d�7 }n|d|� �7 }|j s�|d7 }|j d d }|d ur�|d | 7 }|j �rD|j d u r�t |jj j�d kr�t�d��|jj d d �rDt |jj j�d k�rDt|jjtj��rD|j�sD|d7 }|j d d }|d u�r<|d | 7 }|d7 }|jd u�rd|d| �|j� 7 }|S )N)Ztype_expression� z ^\s*[\'\"\(]z.*\W.*z DEFAULT (r� z DEFAULT z NOT NULL�sqlite�on_conflict_not_null� ON CONFLICT Tr z@SQLite does not support autoincrement for composite primary keys� autoincrementz PRIMARY KEY�on_conflict_primary_keyz AUTOINCREMENT)r3 Ztype_compiler_instancer/ r� r� Z format_columnZget_column_default_stringr= �match�nullable�dialect_options� primary_keyr� �lenr� �columnsr r� rP r� r� �Integer� foreign_keys�computed)r2 �columnra r4 �colspecr �on_conflict_clauser- r- r. �get_column_specification� sX � �� �������� z*SQLiteDDLCompiler.get_column_specificationc s� t |j�dkrJt|�d }|jrJ|jjd d rJt|jjt j �rJ|j sJd S t � � |�}|jd d }|d u r�t |j�dkr�t|�d jd d }|d ur�|d| 7 }|S )Nr r r� r� r� r� r� )r� r� �listr� r� r� rP r� r� r� r� r� r0 � visit_primary_key_constraint)r2 � constraintrC r� r r� r5 r- r. r� � s, ���� �� z.SQLiteDDLCompiler.visit_primary_key_constraintc sv t � �|�}|jd d }|d u r^t|j�dkr^t|�d }t|tj�r^t|�d jd d }|d urr|d| 7 }|S )Nr� r� r r �on_conflict_uniquer� ) r0 �visit_unique_constraintr� r� r� r� r' r Z SchemaItem)r2 r� rC r r� Zcol1r5 r- r. r� � s � �� z)SQLiteDDLCompiler.visit_unique_constraintc s2 t � �|�}|jd d }|d ur.|d| 7 }|S )Nr� r� r� )r0 �visit_check_constraintr� )r2 r� rC r r� r5 r- r. r� � s � z(SQLiteDDLCompiler.visit_check_constraintc s, t � �|�}|jd d d ur(t�d��|S )Nr� r� zFSQLite does not support on conflict clause for column check constraint)r0 � visit_column_check_constraintr� r r� )r2 r� rC r r5 r- r. r� � s �z/SQLiteDDLCompiler.visit_column_check_constraintc s< |j d jj}|j d jj}|j|jkr,d S t� �|�S d S )Nr )r �parentr� r� r r0 � visit_foreign_key_constraint)r2 r� rC Z local_tableZ remote_tabler5 r- r. r� � s z.SQLiteDDLCompiler.visit_foreign_key_constraintc C s |j |dd�S )z=Format the remote table clause of a CREATE CONSTRAINT clause.Fr� )� format_table)r2 r� r� r� r- r- r. � define_constraint_remote_table s z0SQLiteDDLCompiler.define_constraint_remote_tableFTc s� |j }� �|� � j}d}|jr(|d7 }|d7 }|jr>|d7 }|d� j|dd�|j|jdd �d �� fd d �|j D ��f 7 }|j d d }|d ur�� j j |ddd�} |d| 7 }|S )NzCREATE zUNIQUE zINDEX zIF NOT EXISTS z %s ON %s (%s)T)�include_schemaFr� r� c 3 s | ]}� j j|d dd�V qdS )FT�r� Z literal_bindsN)� sql_compilerr/ )r� r� r� r- r. r� s ��z7SQLiteDDLCompiler.visit_create_index.<locals>.<genexpr>r� �wherer z WHERE ) �elementZ_verify_index_tabler� �uniqueZ if_not_existsZ_prepared_index_namer� r� r� Z expressionsr� r r/ ) r2 �creater Zinclude_table_schemarC �indexr� r Z whereclauseZwhere_compiledr- r� r. �visit_create_index s. �� � z$SQLiteDDLCompiler.visit_create_indexc C sN g }|j d d s |�d� |j d d r4|�d� |rFdd�|� S dS d S ) Nr� � with_rowidz WITHOUT ROWID�strictZSTRICTz z, r� )r� r� r� )r2 r� Z table_optionsr- r- r. �post_create_table/ s z#SQLiteDDLCompiler.post_create_table)FT) r7 r8 r9 r� r� r� r� r� r� r r r r: r- r- r5 r. r� � s 7 � #r� c sD e Zd Zdd� Z� fdd�Z� fdd�Z� fdd�Zd d � Z� ZS ) �SQLiteTypeCompilerc K s | � |�S r% )Z visit_BLOB�r2 r� rC r- r- r. �visit_large_binary? s z%SQLiteTypeCompiler.visit_large_binaryc s$ t |t�r|jr t� �|�S dS d S )Nrs )r' r; rO r0 �visit_DATETIMEr r5 r- r. r B s �� z!SQLiteTypeCompiler.visit_DATETIMEc s$ t |t�r|jr t� �|�S dS d S )Nrr )r' r; rO r0 � visit_DATEr r5 r- r. r K s �� z SQLiteTypeCompiler.visit_DATEc s$ t |t�r|jr t� �|�S dS d S )Nrv )r' r; rO r0 � visit_TIMEr r5 r- r. r T s �� z SQLiteTypeCompiler.visit_TIMEc K s dS )Nr r- r r- r- r. � visit_JSON] s z SQLiteTypeCompiler.visit_JSON) r7 r8 r9 r r r r r r: r- r- r5 r. r > s r c @ s e Zd Zh d�ZdS )�SQLiteIdentifierPreparer>u �union�groupZanalyzeZdistinct�rename�deferred�ignore�updater �set�escape�raise�delete�query�end�or�is�commit�descZ references�check�detachZforeign�nullr Zhaving�addr �viewZcollateZascr� �to�innerr} �offsetZdatabaser� ZbetweenZthenr� r Zcross�else�asr� � initially�fullZusing�insertr� r~ �rollbackr� �conflictZ current_date�forZ intersect�replacer ZalterZvacuumZindexedr� �rowZcurrent_timestamp�beginZinto�glob�values�if�after�triggerZreindex�temp�when�order� deferrableZnaturalZcascade�exceptZvirtual�andr� �existsZdropZof�trueZeach�from�outerZbyZrestrict�attach�limit�explain� current_timeZisnullZ exclusive�onZinsteadZ transaction�likeZplan�falser� ZprimaryZ immediate� temporaryZcaseZfail�all�pragmaZnotnull�before�not�inN)r7 r8 r9 Zreserved_wordsr- r- r- r. r d s r c @ s" e Zd Zejdd� �Zdd� ZdS )�SQLiteExecutionContextc C s | j j p| j�dd�S )NZsqlite_raw_colnamesF)r3 �_broken_dotted_colnamesZexecution_options�getr� r- r- r. �_preserve_raw_colnames� s �z-SQLiteExecutionContext._preserve_raw_colnamesc C s, | j s d|v r |�d�d |fS |d fS d S )N�.r� )rW �split)r2 Zcolnamer- r- r. �_translate_colname� s z)SQLiteExecutionContext._translate_colnameN)r7 r8 r9 r Zmemoized_propertyrW rZ r- r- r- r. rT � s rT c @ s( e Zd ZdZdZdZdZdZdZdZ dZ dZ dZ dZ dZdZdZdZdZdZdZdZdZeZeZeZeZ e Z e Z e Z e!j"dddd�fe!j#ddife!j$dddd �fe!j%d difgZ&dZ'dZ(e)j*d d d �dIdd��Z+e)�,ddd��Z-dd� Z.dd� Z/dd� Z0e1j2dd� �Z3dd � Z4d d d d d �d!d"�Z5e1j2dJd#d$��Z6e1j2dKd%d&��Z7e1j2dLd'd(��Z8e1j2dMd)d*��Z9d+d,� Z:e1j2dNd-d.��Z;e1j2dOd/d0��Z<e1j2dPd1d2��Z=d3d4� Z>d5d6� Z?e1j2dQd7d8��Z@e1j2dRd9d:��ZAd;d<� ZBe1j2dSd=d>��ZCe1j2dTd?d@��ZDe1j2dUdAdB��ZEdCdD� ZFe1j2dVdEdF��ZGdWdGdH�ZHdS )X� SQLiteDialectr� FTZNULLZqmark)r� r r r N)r� r� r� r� )�1.3.7z�The _json_serializer argument to the SQLite dialect has been renamed to the correct name of json_serializer. The old argument name will be removed in a future release.)r\ z�The _json_deserializer argument to the SQLite dialect has been renamed to the correct name of json_deserializer. The old argument name will be removed in a future release.)�_json_serializer�_json_deserializerc K s� t jj| fi |�� |r |}|r$|}|| _|| _|| _| jd ur�| jjdk r`t� d| jjf � | jjdk | _ | jjdk| _ | jjdk| _ | jjdk| _ | jjdk | _| jjdk s�tjr�d | _ | _| _| jjd k r�d | _d S ) N)r � � z�SQLite version %s is older than 3.7.16, and will not support right nested joins, as are sometimes used in more complex ORM scenarios. SQLAlchemy 1.4 and above no longer tries to rewrite these joins.)r � r )r r � )r � r )r r_ � )r � � )r �# F)r � r i� )r �DefaultDialectr< r] r^ �native_datetimeZdbapiZsqlite_version_infor r� rU �supports_default_valuesr� �supports_multivalues_insert�_broken_fk_pragma_quotes�pypy�update_returning�delete_returning�insert_returningZ insertmanyvalues_max_parameters)r2 rj Zjson_serializerZjson_deserializerr] r^ ra r- r- r. r< 8 s: �� ��� zSQLiteDialect.__init__r r )�READ UNCOMMITTED� SERIALIZABLEc C s t | j�S r% )r� �_isolation_lookup)r2 �dbapi_connectionr- r- r. �get_isolation_level_values� s z(SQLiteDialect.get_isolation_level_valuesc C s. | j | }|�� }|�d|� �� |�� d S )NzPRAGMA read_uncommitted = )rt �cursor�execute�close)r2 ru �levelZisolation_levelrw r- r- r. �set_isolation_level� s z!SQLiteDialect.set_isolation_levelc C s` |� � }|�d� |�� }|r(|d }nd}|�� |dkr@dS |dkrLdS ds\J d| ��d S )NzPRAGMA read_uncommittedr rs r rr FzUnknown isolation level %s)rw rx Zfetchonery )r2 ru rw �resr+ r- r- r. �get_isolation_level� s z!SQLiteDialect.get_isolation_levelc K s d}|� |�}dd� |D �S )NzPRAGMA database_listc S s g | ]}|d dkr|d �qS )r r= r- )r� �dbr- r- r. � <listcomp>� r� z2SQLiteDialect.get_schema_names.<locals>.<listcomp>)�exec_driver_sql)r2 � connectionrC �s�dlr- r- r. �get_schema_names� s z SQLiteDialect.get_schema_namesc C s, |d ur$| j �|�}|� d|� �}n|}|S )NrX )�identifier_preparer�quote_identifier)r2 r � table_name�qschemar� r- r- r. �_format_schema� s z SQLiteDialect._format_schemar� z Optional[str]rL )r� r� r �sqlite_include_internalc C s6 | � ||�}|sd}nd}d|� d|� d|� d�}|S )Nz) AND name NOT LIKE 'sqlite~_%' ESCAPE '~'r� zSELECT name FROM z WHERE type='�'z ORDER BY name)r� )r2 r� r� r r� �mainZ filter_tabler r- r- r. �_sqlite_main_query� s ���z SQLiteDialect._sqlite_main_queryc K s& | � dd||�}|�|��� �� }|S )N� sqlite_masterr� �r� r� ZscalarsrO �r2 r� r r� rC r �namesr- r- r. �get_table_names� s �z SQLiteDialect.get_table_namesc K s& | � ddd |�}|�|��� �� }|S )N�sqlite_temp_masterr� r� �r2 r� r� rC r r� r- r- r. �get_temp_table_names� s �z"SQLiteDialect.get_temp_table_namesc K s& | � ddd |�}|�|��� �� }|S )Nr� r) r� r� r- r- r. �get_temp_view_names� s �z!SQLiteDialect.get_temp_view_namesc K sF | � |� |d ur,|| j|fi |��vr,dS | j|d||d�}t|�S )NF� table_infor )Z _ensure_has_table_connectionr� �_get_table_pragmarL )r2 r� r� r rC �infor- r- r. � has_table� s ���zSQLiteDialect.has_tablec C s dS )Nr� r- )r2 r� r- r- r. �_get_default_schema_name� s z&SQLiteDialect._get_default_schema_namec K s& | � dd||�}|�|��� �� }|S )Nr� r) r� r� r- r- r. �get_view_names s �z SQLiteDialect.get_view_namesc K s� |d ur8| j �|�}|� d�}d|f }|�||f�}n>zd}|�||f�}W n& tjyt d}|�||f�}Y n0 |�� } | r�| d jS t�|r�|� d|� �n|��d S )Nz.sqlite_masterz1SELECT sql FROM %s WHERE name = ? AND type='view'zzSELECT sql FROM (SELECT * FROM sqlite_master UNION ALL SELECT * FROM sqlite_temp_master) WHERE name = ? AND type='view'z<SELECT sql FROM sqlite_master WHERE name = ? AND type='view'r rX )r� r� r� r � DBAPIError�fetchallr �NoSuchTableError) r2 r� Z view_namer rC r� Zmasterr� �rs�resultr- r- r. �get_view_definition s* ��� �z!SQLiteDialect.get_view_definitionc K sR d}| j dkrd}| j||||d�}g }d }|D ]�} | d } | d �� } | d } | d } | d }|dkrr| d nd }|dkr�q0t|�}|dk}|d u r�|r�| j|||fi |��}t�d |�� tjtj B �}|s�J d |� ���|� d��� }|� | � | | | | ||||�� q0|�r|S | � |||��sFt�|�r>|� d|� �n|��nt�� S d S )Nr� )r � Z table_xinfor r rc r � � re r zcreate table .*?\((.*)\)$zcreate table not found in rX )Zserver_version_infor� �upperrL �_get_table_sqlr= r� �strip�DOTALL� IGNORECASEr r� �_get_column_infor� r r� r r� )r2 r� r� r rC rP r� r� �tablesqlr6 r� r� r� r r� �hidden� generated� persistedr� r- r- r. � get_columns, sf � �� ��� �zSQLiteDialect.get_columnsc C s� |r0t jdd|t jd�}t jdd|t jd��� }| �|�} |d urJt|�}|| |||d�} |r�d} |r�d} t �t �|�| |t j�} | r�| �d�} | |d�| d < | S ) Nr� r� )�flags�always)r� r� r� r r� z@[^,]*\s+GENERATED\s+ALWAYS\s+AS\s+\((.*)\)\s*(?:virtual|stored)?r )�sqltextr� r� ) r= �subr� r� �_resolve_type_affinityr� rM r r )r2 r� r� r� r r� r� r� r� r4 r� r� �patternr� r- r- r. r� j s0 ��� z SQLiteDialect._get_column_infoc C s t �d|�}|r&|�d�}|�d�}nd}d}|| jv rD| j| }njd|v rTtj}nZd|v sld|v sld|v rttj}n:d |v s�|s�tj}n&d |v s�d |v s�d |v r�tj}ntj }|d u�r t � d|�}z|dd� |D �� }W n, t �y t � d||f � |� }Y n0 n|� }|S )aZ Return a data type from a reflected column, using affinity rules. SQLite's goal for universal compatibility introduces some complexity during reflection, as a column's defined type might not actually be a type that SQLite understands - or indeed, my not be defined *at all*. Internally, SQLite handles this with a 'data type affinity' for each column definition, mapping to one of 'TEXT', 'NUMERIC', 'INTEGER', 'REAL', or 'NONE' (raw bits). The algorithm that determines this is listed in https://www.sqlite.org/datatype3.html section 2.1. This method allows SQLAlchemy to support that algorithm, while still providing access to smarter reflection utilities by recognizing column definitions that SQLite only supports through affinity (like DATE and DOUBLE). z([\w ]+)(\(.*?\))?r rc r� ru r ZCLOBr! r r ZFLOAZDOUBNz(\d+)c S s g | ] }t |��qS r- )�int)r� �ar- r- r. r � r� z8SQLiteDialect._resolve_type_affinity.<locals>.<listcomp>zNCould not instantiate type %s with reflected arguments %s; using no arguments.)r= r� r � ischema_namesr� r r! ZNullTyper r �findallr& r r� )r2 r� r� r4 r` r- r- r. r� � s< ��z$SQLiteDialect._resolve_type_affinityc K s� d }| j |||d�}|r>d}t�||tj�}|r:|�d�nd }| j|||fi |��} dd� | D �} | jdd� d� d d� | D �} | r�| |d �S t�� S d S ) Nr z CONSTRAINT (\w+) PRIMARY KEYr c S s g | ]}|� d d�dkr|�qS )r� r �rV �r� �colr- r- r. r � r� z3SQLiteDialect.get_pk_constraint.<locals>.<listcomp>c S s | � d�S )Nr� r� )r� r- r- r. �<lambda>� r� z1SQLiteDialect.get_pk_constraint.<locals>.<lambda>�r� c S s g | ] }|d �qS )r� r- r� r- r- r. r � r� )�constrained_columnsr� ) r� r= rM �Ir r� �sortr Z pk_constraint) r2 r� r� r rC �constraint_name� table_dataZ PK_PATTERNr� r� Zpkeysr- r- r. �get_pk_constraint� s z SQLiteDialect.get_pk_constraintc s� �j |d||d�}i }|D ]�}|d |d |d |d f\}} } } | s�z$�j|| fd|i|��} | d } W q� tjy� g } Y q�0 ng } �jr�t�d d | �} ||v r�|| }n"d g || | i d � }||< |||< |d �| � | r|d �| � qd d� � � fdd�|�� D �}�j |||d����fdd�}g }|� D ]`\}}}} }� ||| �}||v�rtt � d||f � �q:|� |�}||d< ||d< |�|� �q:|� |�� � |�r�|S t�� S d S )NZforeign_key_listr r rc r r� r r� z^[\"\[`\']|[\"\]`\']$r� )r� r� Zreferred_schema�referred_table�referred_columns�optionsr� c S s t | �|f t |� S r% )�tuple�r� r� r� r- r- r. �fk_sig s ���z.SQLiteDialect.get_foreign_keys.<locals>.fk_sigc s& i | ] }� |d |d |d �|�qS r� r- )r� �fk)r� r- r. � <dictcomp>! s ��z2SQLiteDialect.get_foreign_keys.<locals>.<dictcomp>c 3 s2 �d u r d S d} t �| �t j�D �] }|�dddddddd �\}}}}}}}} t� �|��}|sf|}nt� �|��}|pz|}i } t �d |�� �D ]b} | �d �r�| dd � � � } | r�| d kr�| | d < q�| �d�r�| dd � � � } | r�| d kr�| | d< q�|�r d|�� v| d< | �r | �� | d< ||||| fV q d S )Na (?:CONSTRAINT (\w+) +)?FOREIGN KEY *\( *(.+?) *\) +REFERENCES +(?:(?:"(.+?)")|([a-z0-9_]+)) *\( *((?:(?:"[^"]+"|[a-z0-9_]+) *(?:, *)?)+)\) *((?:ON (?:DELETE|UPDATE) (?:SET NULL|SET DEFAULT|CASCADE|RESTRICT|NO ACTION) *)*)((?:NOT +)?DEFERRABLE)?(?: +INITIALLY +(DEFERRED|IMMEDIATE))?r rc r r� r� re r_ rb z *\bON\b *�DELETEz NO ACTION�ondeleteZUPDATE�onupdate�NOTr@ r/ ) r= �finditerr� r r� �_find_cols_in_sigrY r� � startswithr� )Z FK_PATTERNr� r� r� Zreferred_quoted_name� referred_namer� Zonupdatedeleter@ r/ r� �tokenr� r� �r2 r� r- r. � parse_fks, sX � ��� �z1SQLiteDialect.get_foreign_keys.<locals>.parse_fkszhWARNING: SQL-parsed foreign key constraint '%s' could not be located in PRAGMA foreign_keys for table %sr� r� )r� r� r r� rm r= r� r� r9 r� r r� r^ �extendr r� )r2 r� r� r rC Z pragma_fksZfksr6 Z numerical_idZrtblZlcolZrcolZ referred_pkr� r� Zkeys_by_signaturer� Zfkeysr� r� r� r� �sigr� r- )r� r2 r� r. �get_foreign_keys� s� �$��� � � A� �� z SQLiteDialect.get_foreign_keysc c s0 t �d|t j�D ]}|�d�p&|�d�V qd S )Nz(?:"(.+?)")|([a-z0-9_]+)r rc )r= r� r� r )r2 r� r� r- r- r. r� � s z SQLiteDialect._find_cols_in_sigc s� i }� j ||f|dd�|��D ](}|d �d�s2q t|d �}|||< q � j||fd|i|���g }� �fdd�} | � D ]6\} } t| �}||v rx|�|� | | d �} |�| � qx|r�|S t�� S d S ) NT)r �include_auto_indexesr� �sqlite_autoindex� column_namesr c 3 s� �d u r d S d} d}t �| �t j�D ](}|�dd�\}}|t� �|��fV q$t �|�t j�D ],}t� �|�d�pz|�d���}d |fV q^d S )Nz,(?:CONSTRAINT "?(.+?)"? +)?UNIQUE *\((.+?)\)zJ(?:(".+?")|(?:[\[`])?([a-z0-9_]+)(?:[\]`])?)[\t ]+[a-z0-9_ ]+?[\t ]+UNIQUEr rc )r= r� r� r r� r� )ZUNIQUE_PATTERNZINLINE_UNIQUE_PATTERNr� r� r� r� r- r. � parse_uqs� s ��z7SQLiteDialect.get_unique_constraints.<locals>.parse_uqs)r� r� )� get_indexesr� r� r� r^ r� r �unique_constraints) r2 r� r� r rC Zauto_index_by_sig�idxr� r� r� r� r� Zparsed_constraintr- r� r. �get_unique_constraints� s@ ��� ��� z$SQLiteDialect.get_unique_constraintsc K s� | j ||fd|i|��}d}g }t�||p,dtj�D ]6}|�d�} | rTt�dd| �} |�|�d�| d�� q4|jdd � d � |r�|S t� � S d S ) Nr z-(?:CONSTRAINT (.+) +)?CHECK *\( *(.+) *\),? *r� r z^"|"$rc )r� r� c S s | d p dS �Nr� �~r- ��dr- r- r. r� � r� z5SQLiteDialect.get_check_constraints.<locals>.<lambda>r� ) r� r= r� r� r r� r� r� r Zcheck_constraints) r2 r� r� r rC r� Z CHECK_PATTERNZcksr� r� r- r- r. �get_check_constraints� s$ ��� z#SQLiteDialect.get_check_constraintsc K s� | j |d||d�}g }t�dtj�}|r:d| j�|� }nd}|�dd�} |D ]�} | sf| d �d �rfqN|�t | d g | d i d �� t | �d krN| d rNdd|i } |� | | d f�} | � � } |� | �}|d u r�t�d| d � qN|�d�}t|�|d d d< qNt|�D ]l}| j |d|d |d�}|D ]J} | d d u �r`t�d|d � |�|� �q n|d �| d � �q*�q |jdd� d� |�r�|S | �|||��s�t�|�r�|� d|� �n|��nt�� S d S ) NZ index_listr z\)\s+where\s+(.+)�%s.r� r� Fr r� rc )r� r� r r� r� r� zISELECT sql FROM %(schema)ssqlite_master WHERE name = ? AND type = 'index'r z6Failed to look up filter predicate of partial index %sr� r� Z sqlite_where� index_infor� z;Skipped unsupported reflection of expression-based index %sr� c S s | d p dS r� r- r� r- r- r. r� 9 r� z+SQLiteDialect.get_indexes.<locals>.<lambda>r� rX )r� r= r> r� r� r� r^ r� r� r� r� r� �scalarrM r r� r r r� �remover� r� r r� r �indexes)r2 r� r� r rC Zpragma_indexesr� Zpartial_pred_re� schema_exprr� r6 r� r� Z index_sqlZpredicate_match� predicater� Z pragma_indexr- r- r. r� � s� �� ��� �� �� � ��� �zSQLiteDialect.get_indexesc C s |dv S )N> Zsqlite_temp_schemar� Z sqlite_schemar� r- )r2 r� r- r- r. � _is_sys_tableC s zSQLiteDialect._is_sys_tablec K s� |rd| j �|� }nd}z dd|i }|�||f�}W n. tjyf dd|i }|�||f�}Y n0 |�� }|d u r�| �|�s�t�|� |� ���|S )Nr� r� z�SELECT sql FROM (SELECT * FROM %(schema)ssqlite_master UNION ALL SELECT * FROM %(schema)ssqlite_temp_master) WHERE name = ? AND type in ('table', 'view')r zTSELECT sql FROM %(schema)ssqlite_master WHERE name = ? AND type in ('table', 'view'))r� r� r� r r� r� r� r� ) r2 r� r� r rC r� r� r� r+ r- r- r. r� K s* �����z SQLiteDialect._get_table_sqlc C s� | j j}|d ur$d||�� d�g}nddg}||�}|D ]B}|� |� d|� d�}|�|�} | jsj| �� } ng } | r8| S q8g S )NzPRAGMA rX z PRAGMA main.z PRAGMA temp.r� r� )r� r� r� Z _soft_closedr� ) r2 r� rP r� r r� Z statementsZqtableZ statementrw r� r- r- r. r� h s z SQLiteDialect._get_table_pragma)FNNNN)NF)F)F)N)NF)N)N)N)N)N)N)N)N)N)Ir7 r8 r9 r� Zsupports_alterrk Zsupports_default_metavalueZ supports_sane_rowcount_returningZsupports_empty_insertr� rl Zuse_insertmanyvaluesZtuple_in_valuesZsupports_statement_cacheZ#insert_null_pk_still_autoincrementsrq ro Zupdate_returning_multifromrp Zdefault_metavalue_tokenZdefault_paramstylerT Zexecution_ctx_clsry Zstatement_compilerr� Z ddl_compilerr Ztype_compiler_clsr r� r� �colspecs� sa_schemaZTable�IndexZColumn� ConstraintZconstruct_argumentsrm rU r Zdeprecated_paramsr< Z immutabledictrt rv r{ r} r �cacher� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r- r- r- r. r[ � s� �� �� �� � E� � � � � ! =,6 * � 8 Y r[ )Erk � __future__r rf r( r= �typingr �jsonr r r r� r r r� r r r r� r Zenginer r r Zengine.reflectionr r r r r r r r r r r r r r r! r" r# r$ r; �DateTimerY �Daterl ZTimern r� rq rt rw rx r� r� ry Z DDLCompilerr� ZGenericTypeCompilerr ZIdentifierPreparerr ZDefaultExecutionContextrT ri r[ r- r- r- r. �<module> s� S 2tL^� � ?&z sqlalchemy/dialects/sqlite/__pycache__/aiosqlite.cpython-39.pyc 0000644 00000030601 15125143220 0020625 0 ustar 00 a ��Jh�/ � @ s� d Z ddlZddlmZ ddlmZ ddlmZ ddlm Z dd l m Z dd l m Z dd l mZ dd lmZ dd lmZ G dd� d�ZG dd� de�ZG dd� de�ZG dd� de�ZG dd� d�ZG dd� de�ZG dd� de �ZeZdS ) a� .. dialect:: sqlite+aiosqlite :name: aiosqlite :dbapi: aiosqlite :connectstring: sqlite+aiosqlite:///file_path :url: https://pypi.org/project/aiosqlite/ The aiosqlite dialect provides support for the SQLAlchemy asyncio interface running on top of pysqlite. aiosqlite is a wrapper around pysqlite that uses a background thread for each connection. It does not actually use non-blocking IO, as SQLite databases are not socket-based. However it does provide a working asyncio interface that's useful for testing and prototyping purposes. Using a special asyncio mediation layer, the aiosqlite dialect is usable as the backend for the :ref:`SQLAlchemy asyncio <asyncio_toplevel>` extension package. This dialect should normally be used only with the :func:`_asyncio.create_async_engine` engine creation function:: from sqlalchemy.ext.asyncio import create_async_engine engine = create_async_engine("sqlite+aiosqlite:///filename") The URL passes through all arguments to the ``pysqlite`` driver, so all connection arguments are the same as they are for that of :ref:`pysqlite`. .. _aiosqlite_udfs: User-Defined Functions ---------------------- aiosqlite extends pysqlite to support async, so we can create our own user-defined functions (UDFs) in Python and use them directly in SQLite queries as described here: :ref:`pysqlite_udfs`. .. _aiosqlite_serializable: Serializable isolation / Savepoints / Transactional DDL (asyncio version) ------------------------------------------------------------------------- A newly revised version of this important section is now available at the top level of the SQLAlchemy SQLite documentation, in the section :ref:`sqlite_transactions`. .. _aiosqlite_pooling: Pooling Behavior ---------------- The SQLAlchemy ``aiosqlite`` DBAPI establishes the connection pool differently based on the kind of SQLite database that's requested: * When a ``:memory:`` SQLite database is specified, the dialect by default will use :class:`.StaticPool`. This pool maintains a single connection, so that all access to the engine use the same ``:memory:`` database. * When a file-based database is specified, the dialect will use :class:`.AsyncAdaptedQueuePool` as the source of connections. .. versionchanged:: 2.0.38 SQLite file database engines now use :class:`.AsyncAdaptedQueuePool` by default. Previously, :class:`.NullPool` were used. The :class:`.NullPool` class may be used by specifying it via the :paramref:`_sa.create_engine.poolclass` parameter. � N)�deque)�partial� )�SQLiteExecutionContext)�SQLiteDialect_pysqlite� )�pool)�util)�AdaptedConnection)�await_fallback)� await_onlyc @ s` e Zd ZdZdZdd� Zdd� Zddd �Zd d � Zd d � Z dd� Z dd� Z ddd�Z dd� Z dS )�AsyncAdapt_aiosqlite_cursor)�_adapt_connection� _connection� description�await_�_rows� arraysize�rowcount� lastrowidFc C s4 || _ |j| _|j| _d| _d| _d | _t� | _d S )Nr ���)r r r r r r r r )�selfZadapt_connection� r �Y/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/sqlite/aiosqlite.py�__init__p s z$AsyncAdapt_aiosqlite_cursor.__init__c C s | j �� d S �N)r �clear�r r r r �closey s z!AsyncAdapt_aiosqlite_cursor.closeNc C s� z�| � | j�� �}|d u r,| � |�|�� n| � |�||�� |jrt|j| _d | _| _| js�t| � |� � ��| _ nd | _|j| _|j| _| js�| � |� � � n|| _ W n0 t y� } z| j�|� W Y d }~n d }~0 0 d S )Nr )r r �cursor�executer r r � server_sider �fetchallr r �_cursor� Exceptionr �_handle_exception)r � operation� parametersr# �errorr r r r | s$ z#AsyncAdapt_aiosqlite_cursor.executec C s� zJ| � | j�� �}| � |�||�� d | _|j| _|j| _| � |�� � W n0 tyz } z| j � |� W Y d }~n d }~0 0 d S r ) r r r � executemanyr r r r r$ r r% )r r& Zseq_of_parametersr# r( r r r r) � s z'AsyncAdapt_aiosqlite_cursor.executemanyc G s d S r r )r Z inputsizesr r r � setinputsizes� s z)AsyncAdapt_aiosqlite_cursor.setinputsizesc c s | j r| j �� V q d S r �r �popleftr r r r �__iter__� s z$AsyncAdapt_aiosqlite_cursor.__iter__c C s | j r| j �� S d S d S r r+ r r r r �fetchone� s z$AsyncAdapt_aiosqlite_cursor.fetchonec s4 |d u r| j }| j� � fdd�tt|t� ���D �S )Nc s g | ] }� � � �qS r )r, )�.0�_��rrr r � <listcomp>� � z9AsyncAdapt_aiosqlite_cursor.fetchmany.<locals>.<listcomp>)r r �range�min�len�r �sizer r1 r � fetchmany� s z%AsyncAdapt_aiosqlite_cursor.fetchmanyc C s t | j�}| j�� |S r )�listr r )r �retvalr r r r" � s z$AsyncAdapt_aiosqlite_cursor.fetchall)N)N)�__name__� __module__� __qualname__� __slots__r! r r r r) r* r- r. r: r" r r r r r _ s r c sF e Zd ZdZdZ� fdd�Zdd� Zdd� Zdd d �Zd d � Z � Z S )� AsyncAdapt_aiosqlite_ss_cursorr# Tc s t � j|i |�� d | _d S r )�superr r# )r �arg�kw�� __class__r r r � s z'AsyncAdapt_aiosqlite_ss_cursor.__init__c C s$ | j d ur | �| j �� � d | _ d S r )r# r r r r r r r � s z$AsyncAdapt_aiosqlite_ss_cursor.closec C s | � | j�� �S r )r r# r. r r r r r. � s z'AsyncAdapt_aiosqlite_ss_cursor.fetchoneNc C s" |d u r| j }| �| jj|d��S )N)r9 )r r r# r: r8 r r r r: � s z(AsyncAdapt_aiosqlite_ss_cursor.fetchmanyc C s | � | j�� �S r )r r# r" r r r r r" � s z'AsyncAdapt_aiosqlite_ss_cursor.fetchall)N) r= r> r? r@ r! r r r. r: r" � __classcell__r r rE r rA � s rA c @ st e Zd Zee�ZdZdd� Zedd� �Z e j dd� �Z dd� Z dd d �Z d d � Z dd� Zdd� Zdd� Zdd� ZdS )� AsyncAdapt_aiosqlite_connection)�dbapic C s || _ || _d S r )rI r )r rI � connectionr r r r � s z(AsyncAdapt_aiosqlite_connection.__init__c C s | j jS r )r �isolation_levelr r r r rK � s z/AsyncAdapt_aiosqlite_connection.isolation_levelc C sv dd� }t || jj|�}t�� �� }| jj�||f� z | �|�W S t yp } z| � |� W Y d }~n d }~0 0 d S )Nc S s || _ d S r )rK )rJ �valuer r r �set_iso� s z@AsyncAdapt_aiosqlite_connection.isolation_level.<locals>.set_iso) r r Z_conn�asyncio�get_event_loop� create_futureZ_tx� put_nowaitr r$ r% )r rL rM �function�futurer( r r r rK � s c O sP z | � | jj|i |��� W n. tyJ } z| �|� W Y d }~n d }~0 0 d S r )r r �create_functionr$ r% )r �argsrD r( r r r rT � s z/AsyncAdapt_aiosqlite_connection.create_functionFc C s |r t | �S t| �S d S r )rA r )r r! r r r r � s z&AsyncAdapt_aiosqlite_connection.cursorc O s | � | jj|i |���S r )r r r )r rU rD r r r r s z'AsyncAdapt_aiosqlite_connection.executec C sH z| � | j�� � W n. tyB } z| �|� W Y d }~n d }~0 0 d S r )r r �rollbackr$ r% �r r( r r r rV s z(AsyncAdapt_aiosqlite_connection.rollbackc C sH z| � | j�� � W n. tyB } z| �|� W Y d }~n d }~0 0 d S r )r r �commitr$ r% rW r r r rX s z&AsyncAdapt_aiosqlite_connection.commitc C sX z| � | j�� � W n> ty& Y n. tyR } z| �|� W Y d }~n d }~0 0 d S r )r r r � ValueErrorr$ r% rW r r r r s z%AsyncAdapt_aiosqlite_connection.closec C s2 t |t�r*|jd dkr*| jj�d�|�n|�d S )Nr �no active connection)� isinstancerY rU rI �sqlite�OperationalErrorrW r r r r% # s � ���z1AsyncAdapt_aiosqlite_connection._handle_exceptionN)F)r= r> r? � staticmethodr r r@ r �propertyrK �setterrT r r rV rX r r% r r r r rH � s rH c @ s e Zd ZdZee�ZdS )�'AsyncAdaptFallback_aiosqlite_connectionr N)r= r> r? r@ r^ r r r r r r ra / s ra c @ s$ e Zd Zdd� Zdd� Zdd� ZdS )�AsyncAdapt_aiosqlite_dbapic C s || _ || _d| _| �� d S )NZqmark)� aiosqliter\ Z paramstyle�_init_dbapi_attributes)r rc r\ r r r r 6 s z#AsyncAdapt_aiosqlite_dbapi.__init__c C s^ dD ]}t | |t| j|�� qdD ]}t | |t| j|�� q"dD ]}t | |t| j|�� q@d S )N)Z DatabaseError�ErrorZIntegrityErrorZNotSupportedErrorr] ZProgrammingErrorZsqlite_versionZsqlite_version_info)ZPARSE_COLNAMESZPARSE_DECLTYPES)�Binary)�setattr�getattrrc r\ )r �namer r r rd < s z1AsyncAdapt_aiosqlite_dbapi._init_dbapi_attributesc O sn |� dd�}|� dd �}|r,||i |��}n| jj|i |��}d|_t�|�r\t| t|��S t| t |��S d S )N�async_fallbackFZasync_creator_fnT) �poprc �connect�daemonr Zasboolra r rH r )r rC rD rj Z creator_fnrJ r r r rl O s ��z"AsyncAdapt_aiosqlite_dbapi.connectN)r= r> r? r rd rl r r r r rb 5 s rb c @ s e Zd Zdd� ZdS )� SQLiteExecutionContext_aiosqlitec C s | j jdd�S )NT)r! )Z_dbapi_connectionr r r r r �create_server_side_cursorg s z:SQLiteExecutionContext_aiosqlite.create_server_side_cursorN)r= r> r? ro r r r r rn f s rn c sP e Zd ZdZdZdZdZeZe dd� �Z e dd� �Z � fdd�Z d d � Z � ZS ) �SQLiteDialect_aiosqliterc Tc C s t td�td��S )Nrc Zsqlite3)rb � __import__)�clsr r r � import_dbapiu s �z$SQLiteDialect_aiosqlite.import_dbapic C s | � |�rtjS tjS d S r )Z_is_url_file_dbr ZAsyncAdaptedQueuePoolZ StaticPool)rr �urlr r r �get_pool_class{ s z&SQLiteDialect_aiosqlite.get_pool_classc s. t || jj�r dt|�v r dS t� �|||�S )NrZ T)r[ rI r] �strrB � is_disconnect)r �erJ r rE r r rw � s � �z%SQLiteDialect_aiosqlite.is_disconnectc C s |j S r )r )r rJ r r r �get_driver_connection� s z-SQLiteDialect_aiosqlite.get_driver_connection)r= r> r? ZdriverZsupports_statement_cache�is_asyncZ supports_server_side_cursorsrn Zexecution_ctx_cls� classmethodrs ru rw ry rG r r rE r rp k s rp )�__doc__rN � collectionsr � functoolsr �baser Zpysqliter � r r Zenginer Zutil.concurrencyr r r rA rH ra rb rn rp �dialectr r r r �<module> s$ H ] W1# sqlalchemy/dialects/sqlite/__pycache__/dml.cpython-39.pyc 0000644 00000021131 15125143220 0017405 0 ustar 00 a ��Jh�# � @ s� d dl mZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ ddlm Z dd lm Z dd lm Z dd lm Z d d l mZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dl m Z d dl m Z d dl m Z d dl m!Z! d dl"m#Z# d d l$m%Z% d Z&d d d �d!d"�Z'G d#d � d e �ZG d$d%� d%e �Z(G d&d'� d'e(�Z)G d(d)� d)e(�Z*d*S )+� )� annotations)�Any)�List)�Optional)�Tuple)�Union� )�_OnConflictIndexElementsT)�_OnConflictIndexWhereT)�_OnConflictSetT)�_OnConflictWhereT� )�util)� coercions)�roles)�schema)�_DMLTableArgument)�_exclusive_against)� _generative)�ColumnCollection)�ReadOnlyColumnCollection��Insert)� ClauseElement)� ColumnElement)�KeyedColumnElement)� TextClause)�alias)�Self)r �insertr r )�table�returnc C s t | �S )aW Construct a sqlite-specific variant :class:`_sqlite.Insert` construct. .. container:: inherited_member The :func:`sqlalchemy.dialects.sqlite.insert` function creates a :class:`sqlalchemy.dialects.sqlite.Insert`. This class is based on the dialect-agnostic :class:`_sql.Insert` construct which may be constructed using the :func:`_sql.insert` function in SQLAlchemy Core. The :class:`_sqlite.Insert` construct includes additional methods :meth:`_sqlite.Insert.on_conflict_do_update`, :meth:`_sqlite.Insert.on_conflict_do_nothing`. r )r � r" �S/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/sqlite/dml.pyr ' s r c @ sx e Zd ZdZdZdZejdd�dd��Ze ddd id �Z e e dd d dddd�dd���Z e e dd d dd�dd���Z d S )r a? SQLite-specific implementation of INSERT. Adds methods for SQLite-specific syntaxes such as ON CONFLICT. The :class:`_sqlite.Insert` object is created using the :func:`sqlalchemy.dialects.sqlite.insert` function. .. versionadded:: 1.4 .. seealso:: :ref:`sqlite_on_conflict_insert` �sqliteFz6ReadOnlyColumnCollection[str, KeyedColumnElement[Any]])r! c C s t | jdd�jS )a� Provide the ``excluded`` namespace for an ON CONFLICT statement SQLite's ON CONFLICT clause allows reference to the row that would be inserted, known as ``excluded``. This attribute provides all columns in this row to be referenceable. .. tip:: The :attr:`_sqlite.Insert.excluded` attribute is an instance of :class:`_expression.ColumnCollection`, which provides an interface the same as that of the :attr:`_schema.Table.c` collection described at :ref:`metadata_tables_and_columns`. With this collection, ordinary names are accessible like attributes (e.g. ``stmt.excluded.some_column``), but special names and dictionary method names should be accessed using indexed access, such as ``stmt.excluded["column name"]`` or ``stmt.excluded["values"]``. See the docstring for :class:`_expression.ColumnCollection` for further examples. �excluded)�name)r r �columns)�selfr" r" r# r% N s zInsert.excluded�_post_values_clausezCThis Insert construct already has an ON CONFLICT clause established)ZmsgsNr r r r r )�index_elements� index_where�set_�wherer! c C s t ||||�| _| S )a� Specifies a DO UPDATE SET action for ON CONFLICT clause. :param index_elements: A sequence consisting of string column names, :class:`_schema.Column` objects, or other column expression objects that will be used to infer a target index or unique constraint. :param index_where: Additional WHERE criterion that can be used to infer a conditional target index. :param set\_: A dictionary or other mapping object where the keys are either names of columns in the target table, or :class:`_schema.Column` objects or other ORM-mapped columns matching that of the target table, and expressions or literals as values, specifying the ``SET`` actions to take. .. versionadded:: 1.4 The :paramref:`_sqlite.Insert.on_conflict_do_update.set_` parameter supports :class:`_schema.Column` objects from the target :class:`_schema.Table` as keys. .. warning:: This dictionary does **not** take into account Python-specified default UPDATE values or generation functions, e.g. those specified using :paramref:`_schema.Column.onupdate`. These values will not be exercised for an ON CONFLICT style of UPDATE, unless they are manually specified in the :paramref:`.Insert.on_conflict_do_update.set_` dictionary. :param where: Optional argument. An expression object representing a ``WHERE`` clause that restricts the rows affected by ``DO UPDATE SET``. Rows not meeting the ``WHERE`` condition will not be updated (effectively a ``DO NOTHING`` for those rows). )�OnConflictDoUpdater) �r( r* r+ r, r- r" r" r# �on_conflict_do_updaten s 0�z Insert.on_conflict_do_update)r* r+ r! c C s t ||�| _| S )a� Specifies a DO NOTHING action for ON CONFLICT clause. :param index_elements: A sequence consisting of string column names, :class:`_schema.Column` objects, or other column expression objects that will be used to infer a target index or unique constraint. :param index_where: Additional WHERE criterion that can be used to infer a conditional target index. )�OnConflictDoNothingr) �r( r* r+ r" r" r# �on_conflict_do_nothing� s �z Insert.on_conflict_do_nothing)NNNN)NN)�__name__� __module__� __qualname__�__doc__�stringify_dialectZ inherit_cacher Zmemoized_propertyr% r Z_on_conflict_exclusiver r0 r3 r" r" r" r# r ; s, �� � 3 �c @ s4 e Zd ZU dZded< ded< d ddd �d d �ZdS ) �OnConflictClauser$ z.Optional[List[Union[str, schema.Column[Any]]]]�inferred_target_elementsz/Optional[Union[ColumnElement[Any], TextClause]]�inferred_target_whereclauseNr r �r* r+ c C sF |d ur6dd� |D �| _ |d ur.t�tj|�nd | _n d | _ | _d S )Nc S s g | ]}t �tj|��qS r" )r �expectr ZDDLConstraintColumnRole)�.0�columnr" r" r# � <listcomp>� s �z-OnConflictClause.__init__.<locals>.<listcomp>)r: r r= r �WhereHavingRoler; r2 r" r" r# �__init__� s � ��� ��zOnConflictClause.__init__)NN)r4 r5 r6 r8 �__annotations__rB r" r" r" r# r9 � s �r9 c @ s e Zd ZdZdS )r1 r3 N)r4 r5 r6 �__visit_name__r" r" r" r# r1 � s r1 c s@ e Zd ZU dZded< ded< dddd d d �� fd d � Z� ZS )r. r0 z0List[Tuple[Union[schema.Column[Any], str], Any]]�update_values_to_setz Optional[ColumnElement[Any]]�update_whereclauseNr r r r )r* r+ r, r- c sx t � j||d� t|t�r(|sDtd��n t|t�r<t|�}ntd��dd� |�� D �| _|d urnt� t j |�nd | _ d S )Nr< z*set parameter dictionary must not be emptyzqset parameter must be a non-empty dictionary or a ColumnCollection such as the `.c.` collection of a Table objectc S s" g | ]\}}t �tj|�|f�qS r" )r r= r Z DMLColumnRole)r> �key�valuer" r" r# r@ � s �z/OnConflictDoUpdate.__init__.<locals>.<listcomp>) �superrB � isinstance�dict� ValueErrorr �itemsrE r r= r rA rF r/ �� __class__r" r# rB � s& � ����zOnConflictDoUpdate.__init__)NNNN)r4 r5 r6 rD rC rB � __classcell__r" r" rN r# r. � s �r. N)+� __future__r �typingr r r r r Z_typingr r r r � r Zsqlr r r Z sql._typingr Zsql.baser r r r Zsql.dmlr ZStandardInsertZ sql.elementsr r r r Zsql.expressionr Z util.typingr �__all__r r9 r1 r. r" r" r" r# �<module> s@ sqlalchemy/dialects/sqlite/__pycache__/__init__.cpython-39.pyc 0000644 00000001704 15125143220 0020374 0 ustar 00 a ��Jh� � @ s d dl mZ d dl mZ d dl mZ d dl mZ d dlmZ d dlmZ d dlmZ d dlmZ d d lm Z d d lm Z d d lm Z d d lm Z d d lm Z d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ ej e_ZdZdS )� )� aiosqlite)�base)� pysqlcipher)�pysqlite)�BLOB)�BOOLEAN)�CHAR)�DATE)�DATETIME)�DECIMAL)�FLOAT)�INTEGER)�JSON)�NUMERIC)�REAL)�SMALLINT)�TEXT)�TIME)� TIMESTAMP)�VARCHAR)�Insert)�insert)r r r r r r r r r r r r r r r r r r �dialectN)� r r r r r r r r r r r r r r r r r r r r Zdmlr r r �__all__� r r �X/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/sqlite/__init__.py�<module> s. sqlalchemy/dialects/sqlite/__pycache__/provision.cpython-39.pyc 0000644 00000011125 15125143220 0020663 0 ustar 00 a ��Jh� � @ sf d dl Z d dlZddlmZ ddlmZ ddlmZ ddlm Z ddlm Z ddlm Z dd lm Z dd lm Z dd lmZ dd lmZ dd lmZ ddlmZ h d�Zdd� Ze �d�dd� �Z e �d�dd� �Ze �d�dd� �Ze�d�dd� �Ze �d�dd � �Zd d � Ze�d�d d � �Ze�d�d!d"� �Ze�d�d#d$� �Ze�d�dd%d&�d'd(��Z dS ))� N� )�exc)�url)� create_db)�drop_db)�follower_url_from_main)�generate_driver_url)�log)�post_configure_engine)� run_reap_dbs)� stop_test_class_outside_fixtures)�temp_table_keyword_args)�upsert> Z aiosqliteZpysqliteZpysqlite_numeric� pysqlcipherZpysqlite_dollarc C s t �| �} |du r| �� }| j}|dk}d}|r�|dkr�d|vsDJ �t�d|�}|D ]:}|tv rp|du rT|}qTqT|dv r|qTqT|du rT|�d�}qT|s�J d| j� ���|� d|� �}|r�|d|� �7 }|d 7 }|r�|d 7 }| j|d �} |r�| jd d �} | jd|f d�} | S )zUgiven a sqlite url + desired driver + ident, make a canonical URL out of it Nr �:memory:Z test_schemaz[_\.])�db�enc�_z#sqlite filename has no name token: �.dbz.enc)�database�test)�passwordz sqlite+%s)� drivername) �sa_url�make_urlZget_driver_namer �re�split� _drivernames�strip�set) r �driver�ident�filenameZ needs_encZ name_token�tokens�tokenZ new_filename� r% �Y/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/dialects/sqlite/provision.py� _format_url$ s< r' Zsqlitec C s8 t | |d �} z | �� W n tjy. Y d S 0 | S d S �N)r' � get_dialectr ZNoSuchModuleError)r r Z query_strr% r% r& r S s r c C s t | d |�S r( )r' )r r! r% r% r& � _sqlite_follower_url_from_main_ s r* c sd ddl m} |r$|� d|j� d�� n |j� d�� |�|d�� fdd��}|�|d�� fd d ��}d S ) Nr )�eventr z_test_schema.db�connectc s | � d� � d�� d S )NzATTACH DATABASE "z" AS test_schema)�execute)Zdbapi_connectionZconnection_record�Z attach_pathr% r& r, m s �z._sqlite_post_configure_engine.<locals>.connectZengine_disposedc sD t j�� �rt �� � | jj}|r@|dkr@t j�|�r@t �|� dS )z�most databases should be dropped using stop_test_class_outside_fixtures however a few tests like AttachedDBTest might not get triggered on that main hook r N)�os�path�exists�remover r )�enginer" r. r% r& �dispose{ s z._sqlite_post_configure_engine.<locals>.dispose)Z sqlalchemyr+ r Z listens_for)r r3 Zfollower_identr+ r, r4 r% r. r& � _sqlite_post_configure_engined s r5 c C s d S r( r% ��cfg�engr! r% r% r& �_sqlite_create_db� s r9 c C s t |jj|j|� d S r( )�_drop_dbs_w_identr r r r6 r% r% r& �_sqlite_drop_db� s r; c C sJ t �d�D ]:}t j�|�\}}||v r |dv r t�d|� t �|� q d S )N�.)r z.db.encz!deleting SQLite database file: %s)r/ �listdirr0 r r �infor2 )Z databasenamer r! r0 �fname�extr% r% r& r: � s r: c C s |� � d S r( )r4 )�configr �clsr% r% r& r � s r c C s ddgiS )N�prefixes� TEMPORARYr% )r7 r8 r% r% r& � _sqlite_temp_table_keyword_args� s rE c C sN t �d| � t �dd�|�� t�| �} |D ] }tD ]}t| j||� q4q,d S )Nzdb reaper connecting to %rzidentifiers in file: %sz, )r r> �joinr r r r: r )r Zidentsr! r r% r% r& �_reap_sqlite_dbs� s rG F)� set_lambda�sort_by_parameter_orderc C sH ddl m} ||�}|r,|j||j�d�}n|�� }|j|d|i�}|S )Nr )�insert)�set_rI )Zsqlalchemy.dialects.sqliterJ Zon_conflict_do_updateZexcludedZon_conflict_do_nothing� returning)r7 �tablerL rH rI rJ �stmtr% r% r& �_upsert� s ��rO ) r/ r � r r3 r r Ztesting.provisionr r r r r r r r r r r r' Zfor_dbr* r5 r9 r; r: rE rG rO r% r% r% r& �<module> sF / ) � sqlalchemy/dialects/sqlite/base.py 0000755 00000310251 15125143220 0013263 0 ustar 00 # dialects/sqlite/base.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors r''' .. dialect:: sqlite :name: SQLite :normal_support: 3.12+ :best_effort: 3.7.16+ .. _sqlite_datetime: Date and Time Types ------------------- SQLite does not have built-in DATE, TIME, or DATETIME types, and pysqlite does not provide out of the box functionality for translating values between Python `datetime` objects and a SQLite-supported format. SQLAlchemy's own :class:`~sqlalchemy.types.DateTime` and related types provide date formatting and parsing functionality when SQLite is used. The implementation classes are :class:`_sqlite.DATETIME`, :class:`_sqlite.DATE` and :class:`_sqlite.TIME`. These types represent dates and times as ISO formatted strings, which also nicely support ordering. There's no reliance on typical "libc" internals for these functions so historical dates are fully supported. Ensuring Text affinity ^^^^^^^^^^^^^^^^^^^^^^ The DDL rendered for these types is the standard ``DATE``, ``TIME`` and ``DATETIME`` indicators. However, custom storage formats can also be applied to these types. When the storage format is detected as containing no alpha characters, the DDL for these types is rendered as ``DATE_CHAR``, ``TIME_CHAR``, and ``DATETIME_CHAR``, so that the column continues to have textual affinity. .. seealso:: `Type Affinity <https://www.sqlite.org/datatype3.html#affinity>`_ - in the SQLite documentation .. _sqlite_autoincrement: SQLite Auto Incrementing Behavior ---------------------------------- Background on SQLite's autoincrement is at: https://sqlite.org/autoinc.html Key concepts: * SQLite has an implicit "auto increment" feature that takes place for any non-composite primary-key column that is specifically created using "INTEGER PRIMARY KEY" for the type + primary key. * SQLite also has an explicit "AUTOINCREMENT" keyword, that is **not** equivalent to the implicit autoincrement feature; this keyword is not recommended for general use. SQLAlchemy does not render this keyword unless a special SQLite-specific directive is used (see below). However, it still requires that the column's type is named "INTEGER". Using the AUTOINCREMENT Keyword ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To specifically render the AUTOINCREMENT keyword on the primary key column when rendering DDL, add the flag ``sqlite_autoincrement=True`` to the Table construct:: Table( "sometable", metadata, Column("id", Integer, primary_key=True), sqlite_autoincrement=True, ) Allowing autoincrement behavior SQLAlchemy types other than Integer/INTEGER ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ SQLite's typing model is based on naming conventions. Among other things, this means that any type name which contains the substring ``"INT"`` will be determined to be of "integer affinity". A type named ``"BIGINT"``, ``"SPECIAL_INT"`` or even ``"XYZINTQPR"``, will be considered by SQLite to be of "integer" affinity. However, **the SQLite autoincrement feature, whether implicitly or explicitly enabled, requires that the name of the column's type is exactly the string "INTEGER"**. Therefore, if an application uses a type like :class:`.BigInteger` for a primary key, on SQLite this type will need to be rendered as the name ``"INTEGER"`` when emitting the initial ``CREATE TABLE`` statement in order for the autoincrement behavior to be available. One approach to achieve this is to use :class:`.Integer` on SQLite only using :meth:`.TypeEngine.with_variant`:: table = Table( "my_table", metadata, Column( "id", BigInteger().with_variant(Integer, "sqlite"), primary_key=True, ), ) Another is to use a subclass of :class:`.BigInteger` that overrides its DDL name to be ``INTEGER`` when compiled against SQLite:: from sqlalchemy import BigInteger from sqlalchemy.ext.compiler import compiles class SLBigInteger(BigInteger): pass @compiles(SLBigInteger, "sqlite") def bi_c(element, compiler, **kw): return "INTEGER" @compiles(SLBigInteger) def bi_c(element, compiler, **kw): return compiler.visit_BIGINT(element, **kw) table = Table( "my_table", metadata, Column("id", SLBigInteger(), primary_key=True) ) .. seealso:: :meth:`.TypeEngine.with_variant` :ref:`sqlalchemy.ext.compiler_toplevel` `Datatypes In SQLite Version 3 <https://sqlite.org/datatype3.html>`_ .. _sqlite_transactions: Transactions with SQLite and the sqlite3 driver ----------------------------------------------- As a file-based database, SQLite's approach to transactions differs from traditional databases in many ways. Additionally, the ``sqlite3`` driver standard with Python (as well as the async version ``aiosqlite`` which builds on top of it) has several quirks, workarounds, and API features in the area of transaction control, all of which generally need to be addressed when constructing a SQLAlchemy application that uses SQLite. Legacy Transaction Mode with the sqlite3 driver ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The most important aspect of transaction handling with the sqlite3 driver is that it defaults (which will continue through Python 3.15 before being removed in Python 3.16) to legacy transactional behavior which does not strictly follow :pep:`249`. The way in which the driver diverges from the PEP is that it does not "begin" a transaction automatically as dictated by :pep:`249` except in the case of DML statements, e.g. INSERT, UPDATE, and DELETE. Normally, :pep:`249` dictates that a BEGIN must be emitted upon the first SQL statement of any kind, so that all subsequent operations will be established within a transaction until ``connection.commit()`` has been called. The ``sqlite3`` driver, in an effort to be easier to use in highly concurrent environments, skips this step for DQL (e.g. SELECT) statements, and also skips it for DDL (e.g. CREATE TABLE etc.) statements for more legacy reasons. Statements such as SAVEPOINT are also skipped. In modern versions of the ``sqlite3`` driver as of Python 3.12, this legacy mode of operation is referred to as `"legacy transaction control" <https://docs.python.org/3/library/sqlite3.html#sqlite3-transaction-control-isolation-level>`_, and is in effect by default due to the ``Connection.autocommit`` parameter being set to the constant ``sqlite3.LEGACY_TRANSACTION_CONTROL``. Prior to Python 3.12, the ``Connection.autocommit`` attribute did not exist. The implications of legacy transaction mode include: * **Incorrect support for transactional DDL** - statements like CREATE TABLE, ALTER TABLE, CREATE INDEX etc. will not automatically BEGIN a transaction if one were not started already, leading to the changes by each statement being "autocommitted" immediately unless BEGIN were otherwise emitted first. Very old (pre Python 3.6) versions of SQLite would also force a COMMIT for these operations even if a transaction were present, however this is no longer the case. * **SERIALIZABLE behavior not fully functional** - SQLite's transaction isolation behavior is normally consistent with SERIALIZABLE isolation, as it is a file- based system that locks the database file entirely for write operations, preventing COMMIT until all reader transactions (and associated file locks) have completed. However, sqlite3's legacy transaction mode fails to emit BEGIN for SELECT statements, which causes these SELECT statements to no longer be "repeatable", failing one of the consistency guarantees of SERIALIZABLE. * **Incorrect behavior for SAVEPOINT** - as the SAVEPOINT statement does not imply a BEGIN, a new SAVEPOINT emitted before a BEGIN will function on its own but fails to participate in the enclosing transaction, meaning a ROLLBACK of the transaction will not rollback elements that were part of a released savepoint. Legacy transaction mode first existed in order to faciliate working around SQLite's file locks. Because SQLite relies upon whole-file locks, it is easy to get "database is locked" errors, particularly when newer features like "write ahead logging" are disabled. This is a key reason why ``sqlite3``'s legacy transaction mode is still the default mode of operation; disabling it will produce behavior that is more susceptible to locked database errors. However note that **legacy transaction mode will no longer be the default** in a future Python version (3.16 as of this writing). .. _sqlite_enabling_transactions: Enabling Non-Legacy SQLite Transactional Modes with the sqlite3 or aiosqlite driver ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Current SQLAlchemy support allows either for setting the ``.Connection.autocommit`` attribute, most directly by using a :func:`._sa.create_engine` parameter, or if on an older version of Python where the attribute is not available, using event hooks to control the behavior of BEGIN. * **Enabling modern sqlite3 transaction control via the autocommit connect parameter** (Python 3.12 and above) To use SQLite in the mode described at `Transaction control via the autocommit attribute <https://docs.python.org/3/library/sqlite3.html#transaction-control-via-the-autocommit-attribute>`_, the most straightforward approach is to set the attribute to its recommended value of ``False`` at the connect level using :paramref:`_sa.create_engine.connect_args``:: from sqlalchemy import create_engine engine = create_engine( "sqlite:///myfile.db", connect_args={"autocommit": False} ) This parameter is also passed through when using the aiosqlite driver:: from sqlalchemy.ext.asyncio import create_async_engine engine = create_async_engine( "sqlite+aiosqlite:///myfile.db", connect_args={"autocommit": False} ) The parameter can also be set at the attribute level using the :meth:`.PoolEvents.connect` event hook, however this will only work for sqlite3, as aiosqlite does not yet expose this attribute on its ``Connection`` object:: from sqlalchemy import create_engine, event engine = create_engine("sqlite:///myfile.db") @event.listens_for(engine, "connect") def do_connect(dbapi_connection, connection_record): # enable autocommit=False mode dbapi_connection.autocommit = False * **Using SQLAlchemy to emit BEGIN in lieu of SQLite's transaction control** (all Python versions, sqlite3 and aiosqlite) For older versions of ``sqlite3`` or for cross-compatiblity with older and newer versions, SQLAlchemy can also take over the job of transaction control. This is achieved by using the :meth:`.ConnectionEvents.begin` hook to emit the "BEGIN" command directly, while also disabling SQLite's control of this command using the :meth:`.PoolEvents.connect` event hook to set the ``Connection.isolation_level`` attribute to ``None``:: from sqlalchemy import create_engine, event engine = create_engine("sqlite:///myfile.db") @event.listens_for(engine, "connect") def do_connect(dbapi_connection, connection_record): # disable sqlite3's emitting of the BEGIN statement entirely. dbapi_connection.isolation_level = None @event.listens_for(engine, "begin") def do_begin(conn): # emit our own BEGIN. sqlite3 still emits COMMIT/ROLLBACK correctly conn.exec_driver_sql("BEGIN") When using the asyncio variant ``aiosqlite``, refer to ``engine.sync_engine`` as in the example below:: from sqlalchemy import create_engine, event from sqlalchemy.ext.asyncio import create_async_engine engine = create_async_engine("sqlite+aiosqlite:///myfile.db") @event.listens_for(engine.sync_engine, "connect") def do_connect(dbapi_connection, connection_record): # disable aiosqlite's emitting of the BEGIN statement entirely. dbapi_connection.isolation_level = None @event.listens_for(engine.sync_engine, "begin") def do_begin(conn): # emit our own BEGIN. aiosqlite still emits COMMIT/ROLLBACK correctly conn.exec_driver_sql("BEGIN") .. _sqlite_isolation_level: Using SQLAlchemy's Driver Level AUTOCOMMIT Feature with SQLite ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ SQLAlchemy has a comprehensive database isolation feature with optional autocommit support that is introduced in the section :ref:`dbapi_autocommit`. For the ``sqlite3`` and ``aiosqlite`` drivers, SQLAlchemy only includes built-in support for "AUTOCOMMIT". Note that this mode is currently incompatible with the non-legacy isolation mode hooks documented in the previous section at :ref:`sqlite_enabling_transactions`. To use the ``sqlite3`` driver with SQLAlchemy driver-level autocommit, create an engine setting the :paramref:`_sa.create_engine.isolation_level` parameter to "AUTOCOMMIT":: eng = create_engine("sqlite:///myfile.db", isolation_level="AUTOCOMMIT") When using the above mode, any event hooks that set the sqlite3 ``Connection.autocommit`` parameter away from its default of ``sqlite3.LEGACY_TRANSACTION_CONTROL`` as well as hooks that emit ``BEGIN`` should be disabled. Additional Reading for SQLite / sqlite3 transaction control ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Links with important information on SQLite, the sqlite3 driver, as well as long historical conversations on how things got to their current state: * `Isolation in SQLite <https://www.sqlite.org/isolation.html>`_ - on the SQLite website * `Transaction control <https://docs.python.org/3/library/sqlite3.html#transaction-control>`_ - describes the sqlite3 autocommit attribute as well as the legacy isolation_level attribute. * `sqlite3 SELECT does not BEGIN a transaction, but should according to spec <https://github.com/python/cpython/issues/54133>`_ - imported Python standard library issue on github * `sqlite3 module breaks transactions and potentially corrupts data <https://github.com/python/cpython/issues/54949>`_ - imported Python standard library issue on github INSERT/UPDATE/DELETE...RETURNING --------------------------------- The SQLite dialect supports SQLite 3.35's ``INSERT|UPDATE|DELETE..RETURNING`` syntax. ``INSERT..RETURNING`` may be used automatically in some cases in order to fetch newly generated identifiers in place of the traditional approach of using ``cursor.lastrowid``, however ``cursor.lastrowid`` is currently still preferred for simple single-statement cases for its better performance. To specify an explicit ``RETURNING`` clause, use the :meth:`._UpdateBase.returning` method on a per-statement basis:: # INSERT..RETURNING result = connection.execute( table.insert().values(name="foo").returning(table.c.col1, table.c.col2) ) print(result.all()) # UPDATE..RETURNING result = connection.execute( table.update() .where(table.c.name == "foo") .values(name="bar") .returning(table.c.col1, table.c.col2) ) print(result.all()) # DELETE..RETURNING result = connection.execute( table.delete() .where(table.c.name == "foo") .returning(table.c.col1, table.c.col2) ) print(result.all()) .. versionadded:: 2.0 Added support for SQLite RETURNING .. _sqlite_foreign_keys: Foreign Key Support ------------------- SQLite supports FOREIGN KEY syntax when emitting CREATE statements for tables, however by default these constraints have no effect on the operation of the table. Constraint checking on SQLite has three prerequisites: * At least version 3.6.19 of SQLite must be in use * The SQLite library must be compiled *without* the SQLITE_OMIT_FOREIGN_KEY or SQLITE_OMIT_TRIGGER symbols enabled. * The ``PRAGMA foreign_keys = ON`` statement must be emitted on all connections before use -- including the initial call to :meth:`sqlalchemy.schema.MetaData.create_all`. SQLAlchemy allows for the ``PRAGMA`` statement to be emitted automatically for new connections through the usage of events:: from sqlalchemy.engine import Engine from sqlalchemy import event @event.listens_for(Engine, "connect") def set_sqlite_pragma(dbapi_connection, connection_record): cursor = dbapi_connection.cursor() cursor.execute("PRAGMA foreign_keys=ON") cursor.close() .. warning:: When SQLite foreign keys are enabled, it is **not possible** to emit CREATE or DROP statements for tables that contain mutually-dependent foreign key constraints; to emit the DDL for these tables requires that ALTER TABLE be used to create or drop these constraints separately, for which SQLite has no support. .. seealso:: `SQLite Foreign Key Support <https://www.sqlite.org/foreignkeys.html>`_ - on the SQLite web site. :ref:`event_toplevel` - SQLAlchemy event API. :ref:`use_alter` - more information on SQLAlchemy's facilities for handling mutually-dependent foreign key constraints. .. _sqlite_on_conflict_ddl: ON CONFLICT support for constraints ----------------------------------- .. seealso:: This section describes the :term:`DDL` version of "ON CONFLICT" for SQLite, which occurs within a CREATE TABLE statement. For "ON CONFLICT" as applied to an INSERT statement, see :ref:`sqlite_on_conflict_insert`. SQLite supports a non-standard DDL clause known as ON CONFLICT which can be applied to primary key, unique, check, and not null constraints. In DDL, it is rendered either within the "CONSTRAINT" clause or within the column definition itself depending on the location of the target constraint. To render this clause within DDL, the extension parameter ``sqlite_on_conflict`` can be specified with a string conflict resolution algorithm within the :class:`.PrimaryKeyConstraint`, :class:`.UniqueConstraint`, :class:`.CheckConstraint` objects. Within the :class:`_schema.Column` object, there are individual parameters ``sqlite_on_conflict_not_null``, ``sqlite_on_conflict_primary_key``, ``sqlite_on_conflict_unique`` which each correspond to the three types of relevant constraint types that can be indicated from a :class:`_schema.Column` object. .. seealso:: `ON CONFLICT <https://www.sqlite.org/lang_conflict.html>`_ - in the SQLite documentation .. versionadded:: 1.3 The ``sqlite_on_conflict`` parameters accept a string argument which is just the resolution name to be chosen, which on SQLite can be one of ROLLBACK, ABORT, FAIL, IGNORE, and REPLACE. For example, to add a UNIQUE constraint that specifies the IGNORE algorithm:: some_table = Table( "some_table", metadata, Column("id", Integer, primary_key=True), Column("data", Integer), UniqueConstraint("id", "data", sqlite_on_conflict="IGNORE"), ) The above renders CREATE TABLE DDL as: .. sourcecode:: sql CREATE TABLE some_table ( id INTEGER NOT NULL, data INTEGER, PRIMARY KEY (id), UNIQUE (id, data) ON CONFLICT IGNORE ) When using the :paramref:`_schema.Column.unique` flag to add a UNIQUE constraint to a single column, the ``sqlite_on_conflict_unique`` parameter can be added to the :class:`_schema.Column` as well, which will be added to the UNIQUE constraint in the DDL:: some_table = Table( "some_table", metadata, Column("id", Integer, primary_key=True), Column( "data", Integer, unique=True, sqlite_on_conflict_unique="IGNORE" ), ) rendering: .. sourcecode:: sql CREATE TABLE some_table ( id INTEGER NOT NULL, data INTEGER, PRIMARY KEY (id), UNIQUE (data) ON CONFLICT IGNORE ) To apply the FAIL algorithm for a NOT NULL constraint, ``sqlite_on_conflict_not_null`` is used:: some_table = Table( "some_table", metadata, Column("id", Integer, primary_key=True), Column( "data", Integer, nullable=False, sqlite_on_conflict_not_null="FAIL" ), ) this renders the column inline ON CONFLICT phrase: .. sourcecode:: sql CREATE TABLE some_table ( id INTEGER NOT NULL, data INTEGER NOT NULL ON CONFLICT FAIL, PRIMARY KEY (id) ) Similarly, for an inline primary key, use ``sqlite_on_conflict_primary_key``:: some_table = Table( "some_table", metadata, Column( "id", Integer, primary_key=True, sqlite_on_conflict_primary_key="FAIL", ), ) SQLAlchemy renders the PRIMARY KEY constraint separately, so the conflict resolution algorithm is applied to the constraint itself: .. sourcecode:: sql CREATE TABLE some_table ( id INTEGER NOT NULL, PRIMARY KEY (id) ON CONFLICT FAIL ) .. _sqlite_on_conflict_insert: INSERT...ON CONFLICT (Upsert) ----------------------------- .. seealso:: This section describes the :term:`DML` version of "ON CONFLICT" for SQLite, which occurs within an INSERT statement. For "ON CONFLICT" as applied to a CREATE TABLE statement, see :ref:`sqlite_on_conflict_ddl`. From version 3.24.0 onwards, SQLite supports "upserts" (update or insert) of rows into a table via the ``ON CONFLICT`` clause of the ``INSERT`` statement. A candidate row will only be inserted if that row does not violate any unique or primary key constraints. In the case of a unique constraint violation, a secondary action can occur which can be either "DO UPDATE", indicating that the data in the target row should be updated, or "DO NOTHING", which indicates to silently skip this row. Conflicts are determined using columns that are part of existing unique constraints and indexes. These constraints are identified by stating the columns and conditions that comprise the indexes. SQLAlchemy provides ``ON CONFLICT`` support via the SQLite-specific :func:`_sqlite.insert()` function, which provides the generative methods :meth:`_sqlite.Insert.on_conflict_do_update` and :meth:`_sqlite.Insert.on_conflict_do_nothing`: .. sourcecode:: pycon+sql >>> from sqlalchemy.dialects.sqlite import insert >>> insert_stmt = insert(my_table).values( ... id="some_existing_id", data="inserted value" ... ) >>> do_update_stmt = insert_stmt.on_conflict_do_update( ... index_elements=["id"], set_=dict(data="updated value") ... ) >>> print(do_update_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (?, ?) ON CONFLICT (id) DO UPDATE SET data = ?{stop} >>> do_nothing_stmt = insert_stmt.on_conflict_do_nothing(index_elements=["id"]) >>> print(do_nothing_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (?, ?) ON CONFLICT (id) DO NOTHING .. versionadded:: 1.4 .. seealso:: `Upsert <https://sqlite.org/lang_UPSERT.html>`_ - in the SQLite documentation. Specifying the Target ^^^^^^^^^^^^^^^^^^^^^ Both methods supply the "target" of the conflict using column inference: * The :paramref:`_sqlite.Insert.on_conflict_do_update.index_elements` argument specifies a sequence containing string column names, :class:`_schema.Column` objects, and/or SQL expression elements, which would identify a unique index or unique constraint. * When using :paramref:`_sqlite.Insert.on_conflict_do_update.index_elements` to infer an index, a partial index can be inferred by also specifying the :paramref:`_sqlite.Insert.on_conflict_do_update.index_where` parameter: .. sourcecode:: pycon+sql >>> stmt = insert(my_table).values(user_email="a@b.com", data="inserted data") >>> do_update_stmt = stmt.on_conflict_do_update( ... index_elements=[my_table.c.user_email], ... index_where=my_table.c.user_email.like("%@gmail.com"), ... set_=dict(data=stmt.excluded.data), ... ) >>> print(do_update_stmt) {printsql}INSERT INTO my_table (data, user_email) VALUES (?, ?) ON CONFLICT (user_email) WHERE user_email LIKE '%@gmail.com' DO UPDATE SET data = excluded.data The SET Clause ^^^^^^^^^^^^^^^ ``ON CONFLICT...DO UPDATE`` is used to perform an update of the already existing row, using any combination of new values as well as values from the proposed insertion. These values are specified using the :paramref:`_sqlite.Insert.on_conflict_do_update.set_` parameter. This parameter accepts a dictionary which consists of direct values for UPDATE: .. sourcecode:: pycon+sql >>> stmt = insert(my_table).values(id="some_id", data="inserted value") >>> do_update_stmt = stmt.on_conflict_do_update( ... index_elements=["id"], set_=dict(data="updated value") ... ) >>> print(do_update_stmt) {printsql}INSERT INTO my_table (id, data) VALUES (?, ?) ON CONFLICT (id) DO UPDATE SET data = ? .. warning:: The :meth:`_sqlite.Insert.on_conflict_do_update` method does **not** take into account Python-side default UPDATE values or generation functions, e.g. those specified using :paramref:`_schema.Column.onupdate`. These values will not be exercised for an ON CONFLICT style of UPDATE, unless they are manually specified in the :paramref:`_sqlite.Insert.on_conflict_do_update.set_` dictionary. Updating using the Excluded INSERT Values ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In order to refer to the proposed insertion row, the special alias :attr:`~.sqlite.Insert.excluded` is available as an attribute on the :class:`_sqlite.Insert` object; this object creates an "excluded." prefix on a column, that informs the DO UPDATE to update the row with the value that would have been inserted had the constraint not failed: .. sourcecode:: pycon+sql >>> stmt = insert(my_table).values( ... id="some_id", data="inserted value", author="jlh" ... ) >>> do_update_stmt = stmt.on_conflict_do_update( ... index_elements=["id"], ... set_=dict(data="updated value", author=stmt.excluded.author), ... ) >>> print(do_update_stmt) {printsql}INSERT INTO my_table (id, data, author) VALUES (?, ?, ?) ON CONFLICT (id) DO UPDATE SET data = ?, author = excluded.author Additional WHERE Criteria ^^^^^^^^^^^^^^^^^^^^^^^^^ The :meth:`_sqlite.Insert.on_conflict_do_update` method also accepts a WHERE clause using the :paramref:`_sqlite.Insert.on_conflict_do_update.where` parameter, which will limit those rows which receive an UPDATE: .. sourcecode:: pycon+sql >>> stmt = insert(my_table).values( ... id="some_id", data="inserted value", author="jlh" ... ) >>> on_update_stmt = stmt.on_conflict_do_update( ... index_elements=["id"], ... set_=dict(data="updated value", author=stmt.excluded.author), ... where=(my_table.c.status == 2), ... ) >>> print(on_update_stmt) {printsql}INSERT INTO my_table (id, data, author) VALUES (?, ?, ?) ON CONFLICT (id) DO UPDATE SET data = ?, author = excluded.author WHERE my_table.status = ? Skipping Rows with DO NOTHING ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``ON CONFLICT`` may be used to skip inserting a row entirely if any conflict with a unique constraint occurs; below this is illustrated using the :meth:`_sqlite.Insert.on_conflict_do_nothing` method: .. sourcecode:: pycon+sql >>> stmt = insert(my_table).values(id="some_id", data="inserted value") >>> stmt = stmt.on_conflict_do_nothing(index_elements=["id"]) >>> print(stmt) {printsql}INSERT INTO my_table (id, data) VALUES (?, ?) ON CONFLICT (id) DO NOTHING If ``DO NOTHING`` is used without specifying any columns or constraint, it has the effect of skipping the INSERT for any unique violation which occurs: .. sourcecode:: pycon+sql >>> stmt = insert(my_table).values(id="some_id", data="inserted value") >>> stmt = stmt.on_conflict_do_nothing() >>> print(stmt) {printsql}INSERT INTO my_table (id, data) VALUES (?, ?) ON CONFLICT DO NOTHING .. _sqlite_type_reflection: Type Reflection --------------- SQLite types are unlike those of most other database backends, in that the string name of the type usually does not correspond to a "type" in a one-to-one fashion. Instead, SQLite links per-column typing behavior to one of five so-called "type affinities" based on a string matching pattern for the type. SQLAlchemy's reflection process, when inspecting types, uses a simple lookup table to link the keywords returned to provided SQLAlchemy types. This lookup table is present within the SQLite dialect as it is for all other dialects. However, the SQLite dialect has a different "fallback" routine for when a particular type name is not located in the lookup map; it instead implements the SQLite "type affinity" scheme located at https://www.sqlite.org/datatype3.html section 2.1. The provided typemap will make direct associations from an exact string name match for the following types: :class:`_types.BIGINT`, :class:`_types.BLOB`, :class:`_types.BOOLEAN`, :class:`_types.BOOLEAN`, :class:`_types.CHAR`, :class:`_types.DATE`, :class:`_types.DATETIME`, :class:`_types.FLOAT`, :class:`_types.DECIMAL`, :class:`_types.FLOAT`, :class:`_types.INTEGER`, :class:`_types.INTEGER`, :class:`_types.NUMERIC`, :class:`_types.REAL`, :class:`_types.SMALLINT`, :class:`_types.TEXT`, :class:`_types.TIME`, :class:`_types.TIMESTAMP`, :class:`_types.VARCHAR`, :class:`_types.NVARCHAR`, :class:`_types.NCHAR` When a type name does not match one of the above types, the "type affinity" lookup is used instead: * :class:`_types.INTEGER` is returned if the type name includes the string ``INT`` * :class:`_types.TEXT` is returned if the type name includes the string ``CHAR``, ``CLOB`` or ``TEXT`` * :class:`_types.NullType` is returned if the type name includes the string ``BLOB`` * :class:`_types.REAL` is returned if the type name includes the string ``REAL``, ``FLOA`` or ``DOUB``. * Otherwise, the :class:`_types.NUMERIC` type is used. .. _sqlite_partial_index: Partial Indexes --------------- A partial index, e.g. one which uses a WHERE clause, can be specified with the DDL system using the argument ``sqlite_where``:: tbl = Table("testtbl", m, Column("data", Integer)) idx = Index( "test_idx1", tbl.c.data, sqlite_where=and_(tbl.c.data > 5, tbl.c.data < 10), ) The index will be rendered at create time as: .. sourcecode:: sql CREATE INDEX test_idx1 ON testtbl (data) WHERE data > 5 AND data < 10 .. _sqlite_dotted_column_names: Dotted Column Names ------------------- Using table or column names that explicitly have periods in them is **not recommended**. While this is generally a bad idea for relational databases in general, as the dot is a syntactically significant character, the SQLite driver up until version **3.10.0** of SQLite has a bug which requires that SQLAlchemy filter out these dots in result sets. The bug, entirely outside of SQLAlchemy, can be illustrated thusly:: import sqlite3 assert sqlite3.sqlite_version_info < ( 3, 10, 0, ), "bug is fixed in this version" conn = sqlite3.connect(":memory:") cursor = conn.cursor() cursor.execute("create table x (a integer, b integer)") cursor.execute("insert into x (a, b) values (1, 1)") cursor.execute("insert into x (a, b) values (2, 2)") cursor.execute("select x.a, x.b from x") assert [c[0] for c in cursor.description] == ["a", "b"] cursor.execute( """ select x.a, x.b from x where a=1 union select x.a, x.b from x where a=2 """ ) assert [c[0] for c in cursor.description] == ["a", "b"], [ c[0] for c in cursor.description ] The second assertion fails: .. sourcecode:: text Traceback (most recent call last): File "test.py", line 19, in <module> [c[0] for c in cursor.description] AssertionError: ['x.a', 'x.b'] Where above, the driver incorrectly reports the names of the columns including the name of the table, which is entirely inconsistent vs. when the UNION is not present. SQLAlchemy relies upon column names being predictable in how they match to the original statement, so the SQLAlchemy dialect has no choice but to filter these out:: from sqlalchemy import create_engine eng = create_engine("sqlite://") conn = eng.connect() conn.exec_driver_sql("create table x (a integer, b integer)") conn.exec_driver_sql("insert into x (a, b) values (1, 1)") conn.exec_driver_sql("insert into x (a, b) values (2, 2)") result = conn.exec_driver_sql("select x.a, x.b from x") assert result.keys() == ["a", "b"] result = conn.exec_driver_sql( """ select x.a, x.b from x where a=1 union select x.a, x.b from x where a=2 """ ) assert result.keys() == ["a", "b"] Note that above, even though SQLAlchemy filters out the dots, *both names are still addressable*:: >>> row = result.first() >>> row["a"] 1 >>> row["x.a"] 1 >>> row["b"] 1 >>> row["x.b"] 1 Therefore, the workaround applied by SQLAlchemy only impacts :meth:`_engine.CursorResult.keys` and :meth:`.Row.keys()` in the public API. In the very specific case where an application is forced to use column names that contain dots, and the functionality of :meth:`_engine.CursorResult.keys` and :meth:`.Row.keys()` is required to return these dotted names unmodified, the ``sqlite_raw_colnames`` execution option may be provided, either on a per-:class:`_engine.Connection` basis:: result = conn.execution_options(sqlite_raw_colnames=True).exec_driver_sql( """ select x.a, x.b from x where a=1 union select x.a, x.b from x where a=2 """ ) assert result.keys() == ["x.a", "x.b"] or on a per-:class:`_engine.Engine` basis:: engine = create_engine( "sqlite://", execution_options={"sqlite_raw_colnames": True} ) When using the per-:class:`_engine.Engine` execution option, note that **Core and ORM queries that use UNION may not function properly**. SQLite-specific table options ----------------------------- One option for CREATE TABLE is supported directly by the SQLite dialect in conjunction with the :class:`_schema.Table` construct: * ``WITHOUT ROWID``:: Table("some_table", metadata, ..., sqlite_with_rowid=False) * ``STRICT``:: Table("some_table", metadata, ..., sqlite_strict=True) .. versionadded:: 2.0.37 .. seealso:: `SQLite CREATE TABLE options <https://www.sqlite.org/lang_createtable.html>`_ .. _sqlite_include_internal: Reflecting internal schema tables ---------------------------------- Reflection methods that return lists of tables will omit so-called "SQLite internal schema object" names, which are considered by SQLite as any object name that is prefixed with ``sqlite_``. An example of such an object is the ``sqlite_sequence`` table that's generated when the ``AUTOINCREMENT`` column parameter is used. In order to return these objects, the parameter ``sqlite_include_internal=True`` may be passed to methods such as :meth:`_schema.MetaData.reflect` or :meth:`.Inspector.get_table_names`. .. versionadded:: 2.0 Added the ``sqlite_include_internal=True`` parameter. Previously, these tables were not ignored by SQLAlchemy reflection methods. .. note:: The ``sqlite_include_internal`` parameter does not refer to the "system" tables that are present in schemas such as ``sqlite_master``. .. seealso:: `SQLite Internal Schema Objects <https://www.sqlite.org/fileformat2.html#intschema>`_ - in the SQLite documentation. ''' # noqa from __future__ import annotations import datetime import numbers import re from typing import Optional from .json import JSON from .json import JSONIndexType from .json import JSONPathType from ... import exc from ... import schema as sa_schema from ... import sql from ... import text from ... import types as sqltypes from ... import util from ...engine import default from ...engine import processors from ...engine import reflection from ...engine.reflection import ReflectionDefaults from ...sql import coercions from ...sql import compiler from ...sql import elements from ...sql import roles from ...sql import schema from ...types import BLOB # noqa from ...types import BOOLEAN # noqa from ...types import CHAR # noqa from ...types import DECIMAL # noqa from ...types import FLOAT # noqa from ...types import INTEGER # noqa from ...types import NUMERIC # noqa from ...types import REAL # noqa from ...types import SMALLINT # noqa from ...types import TEXT # noqa from ...types import TIMESTAMP # noqa from ...types import VARCHAR # noqa class _SQliteJson(JSON): def result_processor(self, dialect, coltype): default_processor = super().result_processor(dialect, coltype) def process(value): try: return default_processor(value) except TypeError: if isinstance(value, numbers.Number): return value else: raise return process class _DateTimeMixin: _reg = None _storage_format = None def __init__(self, storage_format=None, regexp=None, **kw): super().__init__(**kw) if regexp is not None: self._reg = re.compile(regexp) if storage_format is not None: self._storage_format = storage_format @property def format_is_text_affinity(self): """return True if the storage format will automatically imply a TEXT affinity. If the storage format contains no non-numeric characters, it will imply a NUMERIC storage format on SQLite; in this case, the type will generate its DDL as DATE_CHAR, DATETIME_CHAR, TIME_CHAR. """ spec = self._storage_format % { "year": 0, "month": 0, "day": 0, "hour": 0, "minute": 0, "second": 0, "microsecond": 0, } return bool(re.search(r"[^0-9]", spec)) def adapt(self, cls, **kw): if issubclass(cls, _DateTimeMixin): if self._storage_format: kw["storage_format"] = self._storage_format if self._reg: kw["regexp"] = self._reg return super().adapt(cls, **kw) def literal_processor(self, dialect): bp = self.bind_processor(dialect) def process(value): return "'%s'" % bp(value) return process class DATETIME(_DateTimeMixin, sqltypes.DateTime): r"""Represent a Python datetime object in SQLite using a string. The default string storage format is:: "%(year)04d-%(month)02d-%(day)02d %(hour)02d:%(minute)02d:%(second)02d.%(microsecond)06d" e.g.: .. sourcecode:: text 2021-03-15 12:05:57.105542 The incoming storage format is by default parsed using the Python ``datetime.fromisoformat()`` function. .. versionchanged:: 2.0 ``datetime.fromisoformat()`` is used for default datetime string parsing. The storage format can be customized to some degree using the ``storage_format`` and ``regexp`` parameters, such as:: import re from sqlalchemy.dialects.sqlite import DATETIME dt = DATETIME( storage_format=( "%(year)04d/%(month)02d/%(day)02d %(hour)02d:%(minute)02d:%(second)02d" ), regexp=r"(\d+)/(\d+)/(\d+) (\d+)-(\d+)-(\d+)", ) :param truncate_microseconds: when ``True`` microseconds will be truncated from the datetime. Can't be specified together with ``storage_format`` or ``regexp``. :param storage_format: format string which will be applied to the dict with keys year, month, day, hour, minute, second, and microsecond. :param regexp: regular expression which will be applied to incoming result rows, replacing the use of ``datetime.fromisoformat()`` to parse incoming strings. If the regexp contains named groups, the resulting match dict is applied to the Python datetime() constructor as keyword arguments. Otherwise, if positional groups are used, the datetime() constructor is called with positional arguments via ``*map(int, match_obj.groups(0))``. """ # noqa _storage_format = ( "%(year)04d-%(month)02d-%(day)02d " "%(hour)02d:%(minute)02d:%(second)02d.%(microsecond)06d" ) def __init__(self, *args, **kwargs): truncate_microseconds = kwargs.pop("truncate_microseconds", False) super().__init__(*args, **kwargs) if truncate_microseconds: assert "storage_format" not in kwargs, ( "You can specify only " "one of truncate_microseconds or storage_format." ) assert "regexp" not in kwargs, ( "You can specify only one of " "truncate_microseconds or regexp." ) self._storage_format = ( "%(year)04d-%(month)02d-%(day)02d " "%(hour)02d:%(minute)02d:%(second)02d" ) def bind_processor(self, dialect): datetime_datetime = datetime.datetime datetime_date = datetime.date format_ = self._storage_format def process(value): if value is None: return None elif isinstance(value, datetime_datetime): return format_ % { "year": value.year, "month": value.month, "day": value.day, "hour": value.hour, "minute": value.minute, "second": value.second, "microsecond": value.microsecond, } elif isinstance(value, datetime_date): return format_ % { "year": value.year, "month": value.month, "day": value.day, "hour": 0, "minute": 0, "second": 0, "microsecond": 0, } else: raise TypeError( "SQLite DateTime type only accepts Python " "datetime and date objects as input." ) return process def result_processor(self, dialect, coltype): if self._reg: return processors.str_to_datetime_processor_factory( self._reg, datetime.datetime ) else: return processors.str_to_datetime class DATE(_DateTimeMixin, sqltypes.Date): r"""Represent a Python date object in SQLite using a string. The default string storage format is:: "%(year)04d-%(month)02d-%(day)02d" e.g.: .. sourcecode:: text 2011-03-15 The incoming storage format is by default parsed using the Python ``date.fromisoformat()`` function. .. versionchanged:: 2.0 ``date.fromisoformat()`` is used for default date string parsing. The storage format can be customized to some degree using the ``storage_format`` and ``regexp`` parameters, such as:: import re from sqlalchemy.dialects.sqlite import DATE d = DATE( storage_format="%(month)02d/%(day)02d/%(year)04d", regexp=re.compile("(?P<month>\d+)/(?P<day>\d+)/(?P<year>\d+)"), ) :param storage_format: format string which will be applied to the dict with keys year, month, and day. :param regexp: regular expression which will be applied to incoming result rows, replacing the use of ``date.fromisoformat()`` to parse incoming strings. If the regexp contains named groups, the resulting match dict is applied to the Python date() constructor as keyword arguments. Otherwise, if positional groups are used, the date() constructor is called with positional arguments via ``*map(int, match_obj.groups(0))``. """ _storage_format = "%(year)04d-%(month)02d-%(day)02d" def bind_processor(self, dialect): datetime_date = datetime.date format_ = self._storage_format def process(value): if value is None: return None elif isinstance(value, datetime_date): return format_ % { "year": value.year, "month": value.month, "day": value.day, } else: raise TypeError( "SQLite Date type only accepts Python " "date objects as input." ) return process def result_processor(self, dialect, coltype): if self._reg: return processors.str_to_datetime_processor_factory( self._reg, datetime.date ) else: return processors.str_to_date class TIME(_DateTimeMixin, sqltypes.Time): r"""Represent a Python time object in SQLite using a string. The default string storage format is:: "%(hour)02d:%(minute)02d:%(second)02d.%(microsecond)06d" e.g.: .. sourcecode:: text 12:05:57.10558 The incoming storage format is by default parsed using the Python ``time.fromisoformat()`` function. .. versionchanged:: 2.0 ``time.fromisoformat()`` is used for default time string parsing. The storage format can be customized to some degree using the ``storage_format`` and ``regexp`` parameters, such as:: import re from sqlalchemy.dialects.sqlite import TIME t = TIME( storage_format="%(hour)02d-%(minute)02d-%(second)02d-%(microsecond)06d", regexp=re.compile("(\d+)-(\d+)-(\d+)-(?:-(\d+))?"), ) :param truncate_microseconds: when ``True`` microseconds will be truncated from the time. Can't be specified together with ``storage_format`` or ``regexp``. :param storage_format: format string which will be applied to the dict with keys hour, minute, second, and microsecond. :param regexp: regular expression which will be applied to incoming result rows, replacing the use of ``datetime.fromisoformat()`` to parse incoming strings. If the regexp contains named groups, the resulting match dict is applied to the Python time() constructor as keyword arguments. Otherwise, if positional groups are used, the time() constructor is called with positional arguments via ``*map(int, match_obj.groups(0))``. """ _storage_format = "%(hour)02d:%(minute)02d:%(second)02d.%(microsecond)06d" def __init__(self, *args, **kwargs): truncate_microseconds = kwargs.pop("truncate_microseconds", False) super().__init__(*args, **kwargs) if truncate_microseconds: assert "storage_format" not in kwargs, ( "You can specify only " "one of truncate_microseconds or storage_format." ) assert "regexp" not in kwargs, ( "You can specify only one of " "truncate_microseconds or regexp." ) self._storage_format = "%(hour)02d:%(minute)02d:%(second)02d" def bind_processor(self, dialect): datetime_time = datetime.time format_ = self._storage_format def process(value): if value is None: return None elif isinstance(value, datetime_time): return format_ % { "hour": value.hour, "minute": value.minute, "second": value.second, "microsecond": value.microsecond, } else: raise TypeError( "SQLite Time type only accepts Python " "time objects as input." ) return process def result_processor(self, dialect, coltype): if self._reg: return processors.str_to_datetime_processor_factory( self._reg, datetime.time ) else: return processors.str_to_time colspecs = { sqltypes.Date: DATE, sqltypes.DateTime: DATETIME, sqltypes.JSON: _SQliteJson, sqltypes.JSON.JSONIndexType: JSONIndexType, sqltypes.JSON.JSONPathType: JSONPathType, sqltypes.Time: TIME, } ischema_names = { "BIGINT": sqltypes.BIGINT, "BLOB": sqltypes.BLOB, "BOOL": sqltypes.BOOLEAN, "BOOLEAN": sqltypes.BOOLEAN, "CHAR": sqltypes.CHAR, "DATE": sqltypes.DATE, "DATE_CHAR": sqltypes.DATE, "DATETIME": sqltypes.DATETIME, "DATETIME_CHAR": sqltypes.DATETIME, "DOUBLE": sqltypes.DOUBLE, "DECIMAL": sqltypes.DECIMAL, "FLOAT": sqltypes.FLOAT, "INT": sqltypes.INTEGER, "INTEGER": sqltypes.INTEGER, "JSON": JSON, "NUMERIC": sqltypes.NUMERIC, "REAL": sqltypes.REAL, "SMALLINT": sqltypes.SMALLINT, "TEXT": sqltypes.TEXT, "TIME": sqltypes.TIME, "TIME_CHAR": sqltypes.TIME, "TIMESTAMP": sqltypes.TIMESTAMP, "VARCHAR": sqltypes.VARCHAR, "NVARCHAR": sqltypes.NVARCHAR, "NCHAR": sqltypes.NCHAR, } class SQLiteCompiler(compiler.SQLCompiler): extract_map = util.update_copy( compiler.SQLCompiler.extract_map, { "month": "%m", "day": "%d", "year": "%Y", "second": "%S", "hour": "%H", "doy": "%j", "minute": "%M", "epoch": "%s", "dow": "%w", "week": "%W", }, ) def visit_truediv_binary(self, binary, operator, **kw): return ( self.process(binary.left, **kw) + " / " + "(%s + 0.0)" % self.process(binary.right, **kw) ) def visit_now_func(self, fn, **kw): return "CURRENT_TIMESTAMP" def visit_localtimestamp_func(self, func, **kw): return "DATETIME(CURRENT_TIMESTAMP, 'localtime')" def visit_true(self, expr, **kw): return "1" def visit_false(self, expr, **kw): return "0" def visit_char_length_func(self, fn, **kw): return "length%s" % self.function_argspec(fn) def visit_aggregate_strings_func(self, fn, **kw): return "group_concat%s" % self.function_argspec(fn) def visit_cast(self, cast, **kwargs): if self.dialect.supports_cast: return super().visit_cast(cast, **kwargs) else: return self.process(cast.clause, **kwargs) def visit_extract(self, extract, **kw): try: return "CAST(STRFTIME('%s', %s) AS INTEGER)" % ( self.extract_map[extract.field], self.process(extract.expr, **kw), ) except KeyError as err: raise exc.CompileError( "%s is not a valid extract argument." % extract.field ) from err def returning_clause( self, stmt, returning_cols, *, populate_result_map, **kw, ): kw["include_table"] = False return super().returning_clause( stmt, returning_cols, populate_result_map=populate_result_map, **kw ) def limit_clause(self, select, **kw): text = "" if select._limit_clause is not None: text += "\n LIMIT " + self.process(select._limit_clause, **kw) if select._offset_clause is not None: if select._limit_clause is None: text += "\n LIMIT " + self.process(sql.literal(-1)) text += " OFFSET " + self.process(select._offset_clause, **kw) else: text += " OFFSET " + self.process(sql.literal(0), **kw) return text def for_update_clause(self, select, **kw): # sqlite has no "FOR UPDATE" AFAICT return "" def update_from_clause( self, update_stmt, from_table, extra_froms, from_hints, **kw ): kw["asfrom"] = True return "FROM " + ", ".join( t._compiler_dispatch(self, fromhints=from_hints, **kw) for t in extra_froms ) def visit_is_distinct_from_binary(self, binary, operator, **kw): return "%s IS NOT %s" % ( self.process(binary.left), self.process(binary.right), ) def visit_is_not_distinct_from_binary(self, binary, operator, **kw): return "%s IS %s" % ( self.process(binary.left), self.process(binary.right), ) def visit_json_getitem_op_binary(self, binary, operator, **kw): if binary.type._type_affinity is sqltypes.JSON: expr = "JSON_QUOTE(JSON_EXTRACT(%s, %s))" else: expr = "JSON_EXTRACT(%s, %s)" return expr % ( self.process(binary.left, **kw), self.process(binary.right, **kw), ) def visit_json_path_getitem_op_binary(self, binary, operator, **kw): if binary.type._type_affinity is sqltypes.JSON: expr = "JSON_QUOTE(JSON_EXTRACT(%s, %s))" else: expr = "JSON_EXTRACT(%s, %s)" return expr % ( self.process(binary.left, **kw), self.process(binary.right, **kw), ) def visit_empty_set_op_expr(self, type_, expand_op, **kw): # slightly old SQLite versions don't seem to be able to handle # the empty set impl return self.visit_empty_set_expr(type_) def visit_empty_set_expr(self, element_types, **kw): return "SELECT %s FROM (SELECT %s) WHERE 1!=1" % ( ", ".join("1" for type_ in element_types or [INTEGER()]), ", ".join("1" for type_ in element_types or [INTEGER()]), ) def visit_regexp_match_op_binary(self, binary, operator, **kw): return self._generate_generic_binary(binary, " REGEXP ", **kw) def visit_not_regexp_match_op_binary(self, binary, operator, **kw): return self._generate_generic_binary(binary, " NOT REGEXP ", **kw) def _on_conflict_target(self, clause, **kw): if clause.inferred_target_elements is not None: target_text = "(%s)" % ", ".join( ( self.preparer.quote(c) if isinstance(c, str) else self.process(c, include_table=False, use_schema=False) ) for c in clause.inferred_target_elements ) if clause.inferred_target_whereclause is not None: target_text += " WHERE %s" % self.process( clause.inferred_target_whereclause, include_table=False, use_schema=False, literal_execute=True, ) else: target_text = "" return target_text def visit_on_conflict_do_nothing(self, on_conflict, **kw): target_text = self._on_conflict_target(on_conflict, **kw) if target_text: return "ON CONFLICT %s DO NOTHING" % target_text else: return "ON CONFLICT DO NOTHING" def visit_on_conflict_do_update(self, on_conflict, **kw): clause = on_conflict target_text = self._on_conflict_target(on_conflict, **kw) action_set_ops = [] set_parameters = dict(clause.update_values_to_set) # create a list of column assignment clauses as tuples insert_statement = self.stack[-1]["selectable"] cols = insert_statement.table.c for c in cols: col_key = c.key if col_key in set_parameters: value = set_parameters.pop(col_key) elif c in set_parameters: value = set_parameters.pop(c) else: continue if coercions._is_literal(value): value = elements.BindParameter(None, value, type_=c.type) else: if ( isinstance(value, elements.BindParameter) and value.type._isnull ): value = value._clone() value.type = c.type value_text = self.process(value.self_group(), use_schema=False) key_text = self.preparer.quote(c.name) action_set_ops.append("%s = %s" % (key_text, value_text)) # check for names that don't match columns if set_parameters: util.warn( "Additional column names not matching " "any column keys in table '%s': %s" % ( self.current_executable.table.name, (", ".join("'%s'" % c for c in set_parameters)), ) ) for k, v in set_parameters.items(): key_text = ( self.preparer.quote(k) if isinstance(k, str) else self.process(k, use_schema=False) ) value_text = self.process( coercions.expect(roles.ExpressionElementRole, v), use_schema=False, ) action_set_ops.append("%s = %s" % (key_text, value_text)) action_text = ", ".join(action_set_ops) if clause.update_whereclause is not None: action_text += " WHERE %s" % self.process( clause.update_whereclause, include_table=True, use_schema=False ) return "ON CONFLICT %s DO UPDATE SET %s" % (target_text, action_text) def visit_bitwise_xor_op_binary(self, binary, operator, **kw): # sqlite has no xor. Use "a XOR b" = "(a | b) - (a & b)". kw["eager_grouping"] = True or_ = self._generate_generic_binary(binary, " | ", **kw) and_ = self._generate_generic_binary(binary, " & ", **kw) return f"({or_} - {and_})" class SQLiteDDLCompiler(compiler.DDLCompiler): def get_column_specification(self, column, **kwargs): coltype = self.dialect.type_compiler_instance.process( column.type, type_expression=column ) colspec = self.preparer.format_column(column) + " " + coltype default = self.get_column_default_string(column) if default is not None: if not re.match(r"""^\s*[\'\"\(]""", default) and re.match( r".*\W.*", default ): colspec += f" DEFAULT ({default})" else: colspec += f" DEFAULT {default}" if not column.nullable: colspec += " NOT NULL" on_conflict_clause = column.dialect_options["sqlite"][ "on_conflict_not_null" ] if on_conflict_clause is not None: colspec += " ON CONFLICT " + on_conflict_clause if column.primary_key: if ( column.autoincrement is True and len(column.table.primary_key.columns) != 1 ): raise exc.CompileError( "SQLite does not support autoincrement for " "composite primary keys" ) if ( column.table.dialect_options["sqlite"]["autoincrement"] and len(column.table.primary_key.columns) == 1 and issubclass(column.type._type_affinity, sqltypes.Integer) and not column.foreign_keys ): colspec += " PRIMARY KEY" on_conflict_clause = column.dialect_options["sqlite"][ "on_conflict_primary_key" ] if on_conflict_clause is not None: colspec += " ON CONFLICT " + on_conflict_clause colspec += " AUTOINCREMENT" if column.computed is not None: colspec += " " + self.process(column.computed) return colspec def visit_primary_key_constraint(self, constraint, **kw): # for columns with sqlite_autoincrement=True, # the PRIMARY KEY constraint can only be inline # with the column itself. if len(constraint.columns) == 1: c = list(constraint)[0] if ( c.primary_key and c.table.dialect_options["sqlite"]["autoincrement"] and issubclass(c.type._type_affinity, sqltypes.Integer) and not c.foreign_keys ): return None text = super().visit_primary_key_constraint(constraint) on_conflict_clause = constraint.dialect_options["sqlite"][ "on_conflict" ] if on_conflict_clause is None and len(constraint.columns) == 1: on_conflict_clause = list(constraint)[0].dialect_options["sqlite"][ "on_conflict_primary_key" ] if on_conflict_clause is not None: text += " ON CONFLICT " + on_conflict_clause return text def visit_unique_constraint(self, constraint, **kw): text = super().visit_unique_constraint(constraint) on_conflict_clause = constraint.dialect_options["sqlite"][ "on_conflict" ] if on_conflict_clause is None and len(constraint.columns) == 1: col1 = list(constraint)[0] if isinstance(col1, schema.SchemaItem): on_conflict_clause = list(constraint)[0].dialect_options[ "sqlite" ]["on_conflict_unique"] if on_conflict_clause is not None: text += " ON CONFLICT " + on_conflict_clause return text def visit_check_constraint(self, constraint, **kw): text = super().visit_check_constraint(constraint) on_conflict_clause = constraint.dialect_options["sqlite"][ "on_conflict" ] if on_conflict_clause is not None: text += " ON CONFLICT " + on_conflict_clause return text def visit_column_check_constraint(self, constraint, **kw): text = super().visit_column_check_constraint(constraint) if constraint.dialect_options["sqlite"]["on_conflict"] is not None: raise exc.CompileError( "SQLite does not support on conflict clause for " "column check constraint" ) return text def visit_foreign_key_constraint(self, constraint, **kw): local_table = constraint.elements[0].parent.table remote_table = constraint.elements[0].column.table if local_table.schema != remote_table.schema: return None else: return super().visit_foreign_key_constraint(constraint) def define_constraint_remote_table(self, constraint, table, preparer): """Format the remote table clause of a CREATE CONSTRAINT clause.""" return preparer.format_table(table, use_schema=False) def visit_create_index( self, create, include_schema=False, include_table_schema=True, **kw ): index = create.element self._verify_index_table(index) preparer = self.preparer text = "CREATE " if index.unique: text += "UNIQUE " text += "INDEX " if create.if_not_exists: text += "IF NOT EXISTS " text += "%s ON %s (%s)" % ( self._prepared_index_name(index, include_schema=True), preparer.format_table(index.table, use_schema=False), ", ".join( self.sql_compiler.process( expr, include_table=False, literal_binds=True ) for expr in index.expressions ), ) whereclause = index.dialect_options["sqlite"]["where"] if whereclause is not None: where_compiled = self.sql_compiler.process( whereclause, include_table=False, literal_binds=True ) text += " WHERE " + where_compiled return text def post_create_table(self, table): table_options = [] if not table.dialect_options["sqlite"]["with_rowid"]: table_options.append("WITHOUT ROWID") if table.dialect_options["sqlite"]["strict"]: table_options.append("STRICT") if table_options: return "\n " + ",\n ".join(table_options) else: return "" class SQLiteTypeCompiler(compiler.GenericTypeCompiler): def visit_large_binary(self, type_, **kw): return self.visit_BLOB(type_) def visit_DATETIME(self, type_, **kw): if ( not isinstance(type_, _DateTimeMixin) or type_.format_is_text_affinity ): return super().visit_DATETIME(type_) else: return "DATETIME_CHAR" def visit_DATE(self, type_, **kw): if ( not isinstance(type_, _DateTimeMixin) or type_.format_is_text_affinity ): return super().visit_DATE(type_) else: return "DATE_CHAR" def visit_TIME(self, type_, **kw): if ( not isinstance(type_, _DateTimeMixin) or type_.format_is_text_affinity ): return super().visit_TIME(type_) else: return "TIME_CHAR" def visit_JSON(self, type_, **kw): # note this name provides NUMERIC affinity, not TEXT. # should not be an issue unless the JSON value consists of a single # numeric value. JSONTEXT can be used if this case is required. return "JSON" class SQLiteIdentifierPreparer(compiler.IdentifierPreparer): reserved_words = { "add", "after", "all", "alter", "analyze", "and", "as", "asc", "attach", "autoincrement", "before", "begin", "between", "by", "cascade", "case", "cast", "check", "collate", "column", "commit", "conflict", "constraint", "create", "cross", "current_date", "current_time", "current_timestamp", "database", "default", "deferrable", "deferred", "delete", "desc", "detach", "distinct", "drop", "each", "else", "end", "escape", "except", "exclusive", "exists", "explain", "false", "fail", "for", "foreign", "from", "full", "glob", "group", "having", "if", "ignore", "immediate", "in", "index", "indexed", "initially", "inner", "insert", "instead", "intersect", "into", "is", "isnull", "join", "key", "left", "like", "limit", "match", "natural", "not", "notnull", "null", "of", "offset", "on", "or", "order", "outer", "plan", "pragma", "primary", "query", "raise", "references", "reindex", "rename", "replace", "restrict", "right", "rollback", "row", "select", "set", "table", "temp", "temporary", "then", "to", "transaction", "trigger", "true", "union", "unique", "update", "using", "vacuum", "values", "view", "virtual", "when", "where", } class SQLiteExecutionContext(default.DefaultExecutionContext): @util.memoized_property def _preserve_raw_colnames(self): return ( not self.dialect._broken_dotted_colnames or self.execution_options.get("sqlite_raw_colnames", False) ) def _translate_colname(self, colname): # TODO: detect SQLite version 3.10.0 or greater; # see [ticket:3633] # adjust for dotted column names. SQLite # in the case of UNION may store col names as # "tablename.colname", or if using an attached database, # "database.tablename.colname", in cursor.description if not self._preserve_raw_colnames and "." in colname: return colname.split(".")[-1], colname else: return colname, None class SQLiteDialect(default.DefaultDialect): name = "sqlite" supports_alter = False # SQlite supports "DEFAULT VALUES" but *does not* support # "VALUES (DEFAULT)" supports_default_values = True supports_default_metavalue = False # sqlite issue: # https://github.com/python/cpython/issues/93421 # note this parameter is no longer used by the ORM or default dialect # see #9414 supports_sane_rowcount_returning = False supports_empty_insert = False supports_cast = True supports_multivalues_insert = True use_insertmanyvalues = True tuple_in_values = True supports_statement_cache = True insert_null_pk_still_autoincrements = True insert_returning = True update_returning = True update_returning_multifrom = True delete_returning = True update_returning_multifrom = True supports_default_metavalue = True """dialect supports INSERT... VALUES (DEFAULT) syntax""" default_metavalue_token = "NULL" """for INSERT... VALUES (DEFAULT) syntax, the token to put in the parenthesis.""" default_paramstyle = "qmark" execution_ctx_cls = SQLiteExecutionContext statement_compiler = SQLiteCompiler ddl_compiler = SQLiteDDLCompiler type_compiler_cls = SQLiteTypeCompiler preparer = SQLiteIdentifierPreparer ischema_names = ischema_names colspecs = colspecs construct_arguments = [ ( sa_schema.Table, { "autoincrement": False, "with_rowid": True, "strict": False, }, ), (sa_schema.Index, {"where": None}), ( sa_schema.Column, { "on_conflict_primary_key": None, "on_conflict_not_null": None, "on_conflict_unique": None, }, ), (sa_schema.Constraint, {"on_conflict": None}), ] _broken_fk_pragma_quotes = False _broken_dotted_colnames = False @util.deprecated_params( _json_serializer=( "1.3.7", "The _json_serializer argument to the SQLite dialect has " "been renamed to the correct name of json_serializer. The old " "argument name will be removed in a future release.", ), _json_deserializer=( "1.3.7", "The _json_deserializer argument to the SQLite dialect has " "been renamed to the correct name of json_deserializer. The old " "argument name will be removed in a future release.", ), ) def __init__( self, native_datetime=False, json_serializer=None, json_deserializer=None, _json_serializer=None, _json_deserializer=None, **kwargs, ): default.DefaultDialect.__init__(self, **kwargs) if _json_serializer: json_serializer = _json_serializer if _json_deserializer: json_deserializer = _json_deserializer self._json_serializer = json_serializer self._json_deserializer = json_deserializer # this flag used by pysqlite dialect, and perhaps others in the # future, to indicate the driver is handling date/timestamp # conversions (and perhaps datetime/time as well on some hypothetical # driver ?) self.native_datetime = native_datetime if self.dbapi is not None: if self.dbapi.sqlite_version_info < (3, 7, 16): util.warn( "SQLite version %s is older than 3.7.16, and will not " "support right nested joins, as are sometimes used in " "more complex ORM scenarios. SQLAlchemy 1.4 and above " "no longer tries to rewrite these joins." % (self.dbapi.sqlite_version_info,) ) # NOTE: python 3.7 on fedora for me has SQLite 3.34.1. These # version checks are getting very stale. self._broken_dotted_colnames = self.dbapi.sqlite_version_info < ( 3, 10, 0, ) self.supports_default_values = self.dbapi.sqlite_version_info >= ( 3, 3, 8, ) self.supports_cast = self.dbapi.sqlite_version_info >= (3, 2, 3) self.supports_multivalues_insert = ( # https://www.sqlite.org/releaselog/3_7_11.html self.dbapi.sqlite_version_info >= (3, 7, 11) ) # see https://www.sqlalchemy.org/trac/ticket/2568 # as well as https://www.sqlite.org/src/info/600482d161 self._broken_fk_pragma_quotes = self.dbapi.sqlite_version_info < ( 3, 6, 14, ) if self.dbapi.sqlite_version_info < (3, 35) or util.pypy: self.update_returning = self.delete_returning = ( self.insert_returning ) = False if self.dbapi.sqlite_version_info < (3, 32, 0): # https://www.sqlite.org/limits.html self.insertmanyvalues_max_parameters = 999 _isolation_lookup = util.immutabledict( {"READ UNCOMMITTED": 1, "SERIALIZABLE": 0} ) def get_isolation_level_values(self, dbapi_connection): return list(self._isolation_lookup) def set_isolation_level(self, dbapi_connection, level): isolation_level = self._isolation_lookup[level] cursor = dbapi_connection.cursor() cursor.execute(f"PRAGMA read_uncommitted = {isolation_level}") cursor.close() def get_isolation_level(self, dbapi_connection): cursor = dbapi_connection.cursor() cursor.execute("PRAGMA read_uncommitted") res = cursor.fetchone() if res: value = res[0] else: # https://www.sqlite.org/changes.html#version_3_3_3 # "Optional READ UNCOMMITTED isolation (instead of the # default isolation level of SERIALIZABLE) and # table level locking when database connections # share a common cache."" # pre-SQLite 3.3.0 default to 0 value = 0 cursor.close() if value == 0: return "SERIALIZABLE" elif value == 1: return "READ UNCOMMITTED" else: assert False, "Unknown isolation level %s" % value @reflection.cache def get_schema_names(self, connection, **kw): s = "PRAGMA database_list" dl = connection.exec_driver_sql(s) return [db[1] for db in dl if db[1] != "temp"] def _format_schema(self, schema, table_name): if schema is not None: qschema = self.identifier_preparer.quote_identifier(schema) name = f"{qschema}.{table_name}" else: name = table_name return name def _sqlite_main_query( self, table: str, type_: str, schema: Optional[str], sqlite_include_internal: bool, ): main = self._format_schema(schema, table) if not sqlite_include_internal: filter_table = " AND name NOT LIKE 'sqlite~_%' ESCAPE '~'" else: filter_table = "" query = ( f"SELECT name FROM {main} " f"WHERE type='{type_}'{filter_table} " "ORDER BY name" ) return query @reflection.cache def get_table_names( self, connection, schema=None, sqlite_include_internal=False, **kw ): query = self._sqlite_main_query( "sqlite_master", "table", schema, sqlite_include_internal ) names = connection.exec_driver_sql(query).scalars().all() return names @reflection.cache def get_temp_table_names( self, connection, sqlite_include_internal=False, **kw ): query = self._sqlite_main_query( "sqlite_temp_master", "table", None, sqlite_include_internal ) names = connection.exec_driver_sql(query).scalars().all() return names @reflection.cache def get_temp_view_names( self, connection, sqlite_include_internal=False, **kw ): query = self._sqlite_main_query( "sqlite_temp_master", "view", None, sqlite_include_internal ) names = connection.exec_driver_sql(query).scalars().all() return names @reflection.cache def has_table(self, connection, table_name, schema=None, **kw): self._ensure_has_table_connection(connection) if schema is not None and schema not in self.get_schema_names( connection, **kw ): return False info = self._get_table_pragma( connection, "table_info", table_name, schema=schema ) return bool(info) def _get_default_schema_name(self, connection): return "main" @reflection.cache def get_view_names( self, connection, schema=None, sqlite_include_internal=False, **kw ): query = self._sqlite_main_query( "sqlite_master", "view", schema, sqlite_include_internal ) names = connection.exec_driver_sql(query).scalars().all() return names @reflection.cache def get_view_definition(self, connection, view_name, schema=None, **kw): if schema is not None: qschema = self.identifier_preparer.quote_identifier(schema) master = f"{qschema}.sqlite_master" s = ("SELECT sql FROM %s WHERE name = ? AND type='view'") % ( master, ) rs = connection.exec_driver_sql(s, (view_name,)) else: try: s = ( "SELECT sql FROM " " (SELECT * FROM sqlite_master UNION ALL " " SELECT * FROM sqlite_temp_master) " "WHERE name = ? " "AND type='view'" ) rs = connection.exec_driver_sql(s, (view_name,)) except exc.DBAPIError: s = ( "SELECT sql FROM sqlite_master WHERE name = ? " "AND type='view'" ) rs = connection.exec_driver_sql(s, (view_name,)) result = rs.fetchall() if result: return result[0].sql else: raise exc.NoSuchTableError( f"{schema}.{view_name}" if schema else view_name ) @reflection.cache def get_columns(self, connection, table_name, schema=None, **kw): pragma = "table_info" # computed columns are threaded as hidden, they require table_xinfo if self.server_version_info >= (3, 31): pragma = "table_xinfo" info = self._get_table_pragma( connection, pragma, table_name, schema=schema ) columns = [] tablesql = None for row in info: name = row[1] type_ = row[2].upper() nullable = not row[3] default = row[4] primary_key = row[5] hidden = row[6] if pragma == "table_xinfo" else 0 # hidden has value 0 for normal columns, 1 for hidden columns, # 2 for computed virtual columns and 3 for computed stored columns # https://www.sqlite.org/src/info/069351b85f9a706f60d3e98fbc8aaf40c374356b967c0464aede30ead3d9d18b if hidden == 1: continue generated = bool(hidden) persisted = hidden == 3 if tablesql is None and generated: tablesql = self._get_table_sql( connection, table_name, schema, **kw ) # remove create table match = re.match( r"create table .*?\((.*)\)$", tablesql.strip(), re.DOTALL | re.IGNORECASE, ) assert match, f"create table not found in {tablesql}" tablesql = match.group(1).strip() columns.append( self._get_column_info( name, type_, nullable, default, primary_key, generated, persisted, tablesql, ) ) if columns: return columns elif not self.has_table(connection, table_name, schema): raise exc.NoSuchTableError( f"{schema}.{table_name}" if schema else table_name ) else: return ReflectionDefaults.columns() def _get_column_info( self, name, type_, nullable, default, primary_key, generated, persisted, tablesql, ): if generated: # the type of a column "cc INTEGER GENERATED ALWAYS AS (1 + 42)" # somehow is "INTEGER GENERATED ALWAYS" type_ = re.sub("generated", "", type_, flags=re.IGNORECASE) type_ = re.sub("always", "", type_, flags=re.IGNORECASE).strip() coltype = self._resolve_type_affinity(type_) if default is not None: default = str(default) colspec = { "name": name, "type": coltype, "nullable": nullable, "default": default, "primary_key": primary_key, } if generated: sqltext = "" if tablesql: pattern = ( r"[^,]*\s+GENERATED\s+ALWAYS\s+AS" r"\s+\((.*)\)\s*(?:virtual|stored)?" ) match = re.search( re.escape(name) + pattern, tablesql, re.IGNORECASE ) if match: sqltext = match.group(1) colspec["computed"] = {"sqltext": sqltext, "persisted": persisted} return colspec def _resolve_type_affinity(self, type_): """Return a data type from a reflected column, using affinity rules. SQLite's goal for universal compatibility introduces some complexity during reflection, as a column's defined type might not actually be a type that SQLite understands - or indeed, my not be defined *at all*. Internally, SQLite handles this with a 'data type affinity' for each column definition, mapping to one of 'TEXT', 'NUMERIC', 'INTEGER', 'REAL', or 'NONE' (raw bits). The algorithm that determines this is listed in https://www.sqlite.org/datatype3.html section 2.1. This method allows SQLAlchemy to support that algorithm, while still providing access to smarter reflection utilities by recognizing column definitions that SQLite only supports through affinity (like DATE and DOUBLE). """ match = re.match(r"([\w ]+)(\(.*?\))?", type_) if match: coltype = match.group(1) args = match.group(2) else: coltype = "" args = "" if coltype in self.ischema_names: coltype = self.ischema_names[coltype] elif "INT" in coltype: coltype = sqltypes.INTEGER elif "CHAR" in coltype or "CLOB" in coltype or "TEXT" in coltype: coltype = sqltypes.TEXT elif "BLOB" in coltype or not coltype: coltype = sqltypes.NullType elif "REAL" in coltype or "FLOA" in coltype or "DOUB" in coltype: coltype = sqltypes.REAL else: coltype = sqltypes.NUMERIC if args is not None: args = re.findall(r"(\d+)", args) try: coltype = coltype(*[int(a) for a in args]) except TypeError: util.warn( "Could not instantiate type %s with " "reflected arguments %s; using no arguments." % (coltype, args) ) coltype = coltype() else: coltype = coltype() return coltype @reflection.cache def get_pk_constraint(self, connection, table_name, schema=None, **kw): constraint_name = None table_data = self._get_table_sql(connection, table_name, schema=schema) if table_data: PK_PATTERN = r"CONSTRAINT (\w+) PRIMARY KEY" result = re.search(PK_PATTERN, table_data, re.I) constraint_name = result.group(1) if result else None cols = self.get_columns(connection, table_name, schema, **kw) # consider only pk columns. This also avoids sorting the cached # value returned by get_columns cols = [col for col in cols if col.get("primary_key", 0) > 0] cols.sort(key=lambda col: col.get("primary_key")) pkeys = [col["name"] for col in cols] if pkeys: return {"constrained_columns": pkeys, "name": constraint_name} else: return ReflectionDefaults.pk_constraint() @reflection.cache def get_foreign_keys(self, connection, table_name, schema=None, **kw): # sqlite makes this *extremely difficult*. # First, use the pragma to get the actual FKs. pragma_fks = self._get_table_pragma( connection, "foreign_key_list", table_name, schema=schema ) fks = {} for row in pragma_fks: (numerical_id, rtbl, lcol, rcol) = (row[0], row[2], row[3], row[4]) if not rcol: # no referred column, which means it was not named in the # original DDL. The referred columns of the foreign key # constraint are therefore the primary key of the referred # table. try: referred_pk = self.get_pk_constraint( connection, rtbl, schema=schema, **kw ) referred_columns = referred_pk["constrained_columns"] except exc.NoSuchTableError: # ignore not existing parents referred_columns = [] else: # note we use this list only if this is the first column # in the constraint. for subsequent columns we ignore the # list and append "rcol" if present. referred_columns = [] if self._broken_fk_pragma_quotes: rtbl = re.sub(r"^[\"\[`\']|[\"\]`\']$", "", rtbl) if numerical_id in fks: fk = fks[numerical_id] else: fk = fks[numerical_id] = { "name": None, "constrained_columns": [], "referred_schema": schema, "referred_table": rtbl, "referred_columns": referred_columns, "options": {}, } fks[numerical_id] = fk fk["constrained_columns"].append(lcol) if rcol: fk["referred_columns"].append(rcol) def fk_sig(constrained_columns, referred_table, referred_columns): return ( tuple(constrained_columns) + (referred_table,) + tuple(referred_columns) ) # then, parse the actual SQL and attempt to find DDL that matches # the names as well. SQLite saves the DDL in whatever format # it was typed in as, so need to be liberal here. keys_by_signature = { fk_sig( fk["constrained_columns"], fk["referred_table"], fk["referred_columns"], ): fk for fk in fks.values() } table_data = self._get_table_sql(connection, table_name, schema=schema) def parse_fks(): if table_data is None: # system tables, etc. return # note that we already have the FKs from PRAGMA above. This whole # regexp thing is trying to locate additional detail about the # FKs, namely the name of the constraint and other options. # so parsing the columns is really about matching it up to what # we already have. FK_PATTERN = ( r"(?:CONSTRAINT (\w+) +)?" r"FOREIGN KEY *\( *(.+?) *\) +" r'REFERENCES +(?:(?:"(.+?)")|([a-z0-9_]+)) *\( *((?:(?:"[^"]+"|[a-z0-9_]+) *(?:, *)?)+)\) *' # noqa: E501 r"((?:ON (?:DELETE|UPDATE) " r"(?:SET NULL|SET DEFAULT|CASCADE|RESTRICT|NO ACTION) *)*)" r"((?:NOT +)?DEFERRABLE)?" r"(?: +INITIALLY +(DEFERRED|IMMEDIATE))?" ) for match in re.finditer(FK_PATTERN, table_data, re.I): ( constraint_name, constrained_columns, referred_quoted_name, referred_name, referred_columns, onupdatedelete, deferrable, initially, ) = match.group(1, 2, 3, 4, 5, 6, 7, 8) constrained_columns = list( self._find_cols_in_sig(constrained_columns) ) if not referred_columns: referred_columns = constrained_columns else: referred_columns = list( self._find_cols_in_sig(referred_columns) ) referred_name = referred_quoted_name or referred_name options = {} for token in re.split(r" *\bON\b *", onupdatedelete.upper()): if token.startswith("DELETE"): ondelete = token[6:].strip() if ondelete and ondelete != "NO ACTION": options["ondelete"] = ondelete elif token.startswith("UPDATE"): onupdate = token[6:].strip() if onupdate and onupdate != "NO ACTION": options["onupdate"] = onupdate if deferrable: options["deferrable"] = "NOT" not in deferrable.upper() if initially: options["initially"] = initially.upper() yield ( constraint_name, constrained_columns, referred_name, referred_columns, options, ) fkeys = [] for ( constraint_name, constrained_columns, referred_name, referred_columns, options, ) in parse_fks(): sig = fk_sig(constrained_columns, referred_name, referred_columns) if sig not in keys_by_signature: util.warn( "WARNING: SQL-parsed foreign key constraint " "'%s' could not be located in PRAGMA " "foreign_keys for table %s" % (sig, table_name) ) continue key = keys_by_signature.pop(sig) key["name"] = constraint_name key["options"] = options fkeys.append(key) # assume the remainders are the unnamed, inline constraints, just # use them as is as it's extremely difficult to parse inline # constraints fkeys.extend(keys_by_signature.values()) if fkeys: return fkeys else: return ReflectionDefaults.foreign_keys() def _find_cols_in_sig(self, sig): for match in re.finditer(r'(?:"(.+?)")|([a-z0-9_]+)', sig, re.I): yield match.group(1) or match.group(2) @reflection.cache def get_unique_constraints( self, connection, table_name, schema=None, **kw ): auto_index_by_sig = {} for idx in self.get_indexes( connection, table_name, schema=schema, include_auto_indexes=True, **kw, ): if not idx["name"].startswith("sqlite_autoindex"): continue sig = tuple(idx["column_names"]) auto_index_by_sig[sig] = idx table_data = self._get_table_sql( connection, table_name, schema=schema, **kw ) unique_constraints = [] def parse_uqs(): if table_data is None: return UNIQUE_PATTERN = r'(?:CONSTRAINT "?(.+?)"? +)?UNIQUE *\((.+?)\)' INLINE_UNIQUE_PATTERN = ( r'(?:(".+?")|(?:[\[`])?([a-z0-9_]+)(?:[\]`])?)[\t ]' r"+[a-z0-9_ ]+?[\t ]+UNIQUE" ) for match in re.finditer(UNIQUE_PATTERN, table_data, re.I): name, cols = match.group(1, 2) yield name, list(self._find_cols_in_sig(cols)) # we need to match inlines as well, as we seek to differentiate # a UNIQUE constraint from a UNIQUE INDEX, even though these # are kind of the same thing :) for match in re.finditer(INLINE_UNIQUE_PATTERN, table_data, re.I): cols = list( self._find_cols_in_sig(match.group(1) or match.group(2)) ) yield None, cols for name, cols in parse_uqs(): sig = tuple(cols) if sig in auto_index_by_sig: auto_index_by_sig.pop(sig) parsed_constraint = {"name": name, "column_names": cols} unique_constraints.append(parsed_constraint) # NOTE: auto_index_by_sig might not be empty here, # the PRIMARY KEY may have an entry. if unique_constraints: return unique_constraints else: return ReflectionDefaults.unique_constraints() @reflection.cache def get_check_constraints(self, connection, table_name, schema=None, **kw): table_data = self._get_table_sql( connection, table_name, schema=schema, **kw ) # NOTE NOTE NOTE # DO NOT CHANGE THIS REGULAR EXPRESSION. There is no known way # to parse CHECK constraints that contain newlines themselves using # regular expressions, and the approach here relies upon each # individual # CHECK constraint being on a single line by itself. This # necessarily makes assumptions as to how the CREATE TABLE # was emitted. A more comprehensive DDL parsing solution would be # needed to improve upon the current situation. See #11840 for # background CHECK_PATTERN = r"(?:CONSTRAINT (.+) +)?CHECK *\( *(.+) *\),? *" cks = [] for match in re.finditer(CHECK_PATTERN, table_data or "", re.I): name = match.group(1) if name: name = re.sub(r'^"|"$', "", name) cks.append({"sqltext": match.group(2), "name": name}) cks.sort(key=lambda d: d["name"] or "~") # sort None as last if cks: return cks else: return ReflectionDefaults.check_constraints() @reflection.cache def get_indexes(self, connection, table_name, schema=None, **kw): pragma_indexes = self._get_table_pragma( connection, "index_list", table_name, schema=schema ) indexes = [] # regular expression to extract the filter predicate of a partial # index. this could fail to extract the predicate correctly on # indexes created like # CREATE INDEX i ON t (col || ') where') WHERE col <> '' # but as this function does not support expression-based indexes # this case does not occur. partial_pred_re = re.compile(r"\)\s+where\s+(.+)", re.IGNORECASE) if schema: schema_expr = "%s." % self.identifier_preparer.quote_identifier( schema ) else: schema_expr = "" include_auto_indexes = kw.pop("include_auto_indexes", False) for row in pragma_indexes: # ignore implicit primary key index. # https://www.mail-archive.com/sqlite-users@sqlite.org/msg30517.html if not include_auto_indexes and row[1].startswith( "sqlite_autoindex" ): continue indexes.append( dict( name=row[1], column_names=[], unique=row[2], dialect_options={}, ) ) # check partial indexes if len(row) >= 5 and row[4]: s = ( "SELECT sql FROM %(schema)ssqlite_master " "WHERE name = ? " "AND type = 'index'" % {"schema": schema_expr} ) rs = connection.exec_driver_sql(s, (row[1],)) index_sql = rs.scalar() predicate_match = partial_pred_re.search(index_sql) if predicate_match is None: # unless the regex is broken this case shouldn't happen # because we know this is a partial index, so the # definition sql should match the regex util.warn( "Failed to look up filter predicate of " "partial index %s" % row[1] ) else: predicate = predicate_match.group(1) indexes[-1]["dialect_options"]["sqlite_where"] = text( predicate ) # loop thru unique indexes to get the column names. for idx in list(indexes): pragma_index = self._get_table_pragma( connection, "index_info", idx["name"], schema=schema ) for row in pragma_index: if row[2] is None: util.warn( "Skipped unsupported reflection of " "expression-based index %s" % idx["name"] ) indexes.remove(idx) break else: idx["column_names"].append(row[2]) indexes.sort(key=lambda d: d["name"] or "~") # sort None as last if indexes: return indexes elif not self.has_table(connection, table_name, schema): raise exc.NoSuchTableError( f"{schema}.{table_name}" if schema else table_name ) else: return ReflectionDefaults.indexes() def _is_sys_table(self, table_name): return table_name in { "sqlite_schema", "sqlite_master", "sqlite_temp_schema", "sqlite_temp_master", } @reflection.cache def _get_table_sql(self, connection, table_name, schema=None, **kw): if schema: schema_expr = "%s." % ( self.identifier_preparer.quote_identifier(schema) ) else: schema_expr = "" try: s = ( "SELECT sql FROM " " (SELECT * FROM %(schema)ssqlite_master UNION ALL " " SELECT * FROM %(schema)ssqlite_temp_master) " "WHERE name = ? " "AND type in ('table', 'view')" % {"schema": schema_expr} ) rs = connection.exec_driver_sql(s, (table_name,)) except exc.DBAPIError: s = ( "SELECT sql FROM %(schema)ssqlite_master " "WHERE name = ? " "AND type in ('table', 'view')" % {"schema": schema_expr} ) rs = connection.exec_driver_sql(s, (table_name,)) value = rs.scalar() if value is None and not self._is_sys_table(table_name): raise exc.NoSuchTableError(f"{schema_expr}{table_name}") return value def _get_table_pragma(self, connection, pragma, table_name, schema=None): quote = self.identifier_preparer.quote_identifier if schema is not None: statements = [f"PRAGMA {quote(schema)}."] else: # because PRAGMA looks in all attached databases if no schema # given, need to specify "main" schema, however since we want # 'temp' tables in the same namespace as 'main', need to run # the PRAGMA twice statements = ["PRAGMA main.", "PRAGMA temp."] qtable = quote(table_name) for statement in statements: statement = f"{statement}{pragma}({qtable})" cursor = connection.exec_driver_sql(statement) if not cursor._soft_closed: # work around SQLite issue whereby cursor.description # is blank when PRAGMA returns no rows: # https://www.sqlite.org/cvstrac/tktview?tn=1884 result = cursor.fetchall() else: result = [] if result: return result else: return [] sqlalchemy/dialects/sqlite/json.py 0000755 00000005331 15125143220 0013322 0 ustar 00 # dialects/sqlite/json.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors from ... import types as sqltypes class JSON(sqltypes.JSON): """SQLite JSON type. SQLite supports JSON as of version 3.9 through its JSON1_ extension. Note that JSON1_ is a `loadable extension <https://www.sqlite.org/loadext.html>`_ and as such may not be available, or may require run-time loading. :class:`_sqlite.JSON` is used automatically whenever the base :class:`_types.JSON` datatype is used against a SQLite backend. .. seealso:: :class:`_types.JSON` - main documentation for the generic cross-platform JSON datatype. The :class:`_sqlite.JSON` type supports persistence of JSON values as well as the core index operations provided by :class:`_types.JSON` datatype, by adapting the operations to render the ``JSON_EXTRACT`` function wrapped in the ``JSON_QUOTE`` function at the database level. Extracted values are quoted in order to ensure that the results are always JSON string values. .. versionadded:: 1.3 .. _JSON1: https://www.sqlite.org/json1.html """ # Note: these objects currently match exactly those of MySQL, however since # these are not generalizable to all JSON implementations, remain separately # implemented for each dialect. class _FormatTypeMixin: def _format_value(self, value): raise NotImplementedError() def bind_processor(self, dialect): super_proc = self.string_bind_processor(dialect) def process(value): value = self._format_value(value) if super_proc: value = super_proc(value) return value return process def literal_processor(self, dialect): super_proc = self.string_literal_processor(dialect) def process(value): value = self._format_value(value) if super_proc: value = super_proc(value) return value return process class JSONIndexType(_FormatTypeMixin, sqltypes.JSON.JSONIndexType): def _format_value(self, value): if isinstance(value, int): value = "$[%s]" % value else: value = '$."%s"' % value return value class JSONPathType(_FormatTypeMixin, sqltypes.JSON.JSONPathType): def _format_value(self, value): return "$%s" % ( "".join( [ "[%s]" % elem if isinstance(elem, int) else '."%s"' % elem for elem in value ] ) ) sqlalchemy/dialects/sqlite/provision.py 0000755 00000012734 15125143220 0014406 0 ustar 00 # dialects/sqlite/provision.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors import os import re from ... import exc from ...engine import url as sa_url from ...testing.provision import create_db from ...testing.provision import drop_db from ...testing.provision import follower_url_from_main from ...testing.provision import generate_driver_url from ...testing.provision import log from ...testing.provision import post_configure_engine from ...testing.provision import run_reap_dbs from ...testing.provision import stop_test_class_outside_fixtures from ...testing.provision import temp_table_keyword_args from ...testing.provision import upsert # TODO: I can't get this to build dynamically with pytest-xdist procs _drivernames = { "pysqlite", "aiosqlite", "pysqlcipher", "pysqlite_numeric", "pysqlite_dollar", } def _format_url(url, driver, ident): """given a sqlite url + desired driver + ident, make a canonical URL out of it """ url = sa_url.make_url(url) if driver is None: driver = url.get_driver_name() filename = url.database needs_enc = driver == "pysqlcipher" name_token = None if filename and filename != ":memory:": assert "test_schema" not in filename tokens = re.split(r"[_\.]", filename) for token in tokens: if token in _drivernames: if driver is None: driver = token continue elif token in ("db", "enc"): continue elif name_token is None: name_token = token.strip("_") assert name_token, f"sqlite filename has no name token: {url.database}" new_filename = f"{name_token}_{driver}" if ident: new_filename += f"_{ident}" new_filename += ".db" if needs_enc: new_filename += ".enc" url = url.set(database=new_filename) if needs_enc: url = url.set(password="test") url = url.set(drivername="sqlite+%s" % (driver,)) return url @generate_driver_url.for_db("sqlite") def generate_driver_url(url, driver, query_str): url = _format_url(url, driver, None) try: url.get_dialect() except exc.NoSuchModuleError: return None else: return url @follower_url_from_main.for_db("sqlite") def _sqlite_follower_url_from_main(url, ident): return _format_url(url, None, ident) @post_configure_engine.for_db("sqlite") def _sqlite_post_configure_engine(url, engine, follower_ident): from sqlalchemy import event if follower_ident: attach_path = f"{follower_ident}_{engine.driver}_test_schema.db" else: attach_path = f"{engine.driver}_test_schema.db" @event.listens_for(engine, "connect") def connect(dbapi_connection, connection_record): # use file DBs in all cases, memory acts kind of strangely # as an attached # NOTE! this has to be done *per connection*. New sqlite connection, # as we get with say, QueuePool, the attaches are gone. # so schemes to delete those attached files have to be done at the # filesystem level and not rely upon what attachments are in a # particular SQLite connection dbapi_connection.execute( f'ATTACH DATABASE "{attach_path}" AS test_schema' ) @event.listens_for(engine, "engine_disposed") def dispose(engine): """most databases should be dropped using stop_test_class_outside_fixtures however a few tests like AttachedDBTest might not get triggered on that main hook """ if os.path.exists(attach_path): os.remove(attach_path) filename = engine.url.database if filename and filename != ":memory:" and os.path.exists(filename): os.remove(filename) @create_db.for_db("sqlite") def _sqlite_create_db(cfg, eng, ident): pass @drop_db.for_db("sqlite") def _sqlite_drop_db(cfg, eng, ident): _drop_dbs_w_ident(eng.url.database, eng.driver, ident) def _drop_dbs_w_ident(databasename, driver, ident): for path in os.listdir("."): fname, ext = os.path.split(path) if ident in fname and ext in [".db", ".db.enc"]: log.info("deleting SQLite database file: %s", path) os.remove(path) @stop_test_class_outside_fixtures.for_db("sqlite") def stop_test_class_outside_fixtures(config, db, cls): db.dispose() @temp_table_keyword_args.for_db("sqlite") def _sqlite_temp_table_keyword_args(cfg, eng): return {"prefixes": ["TEMPORARY"]} @run_reap_dbs.for_db("sqlite") def _reap_sqlite_dbs(url, idents): log.info("db reaper connecting to %r", url) log.info("identifiers in file: %s", ", ".join(idents)) url = sa_url.make_url(url) for ident in idents: for drivername in _drivernames: _drop_dbs_w_ident(url.database, drivername, ident) @upsert.for_db("sqlite") def _upsert( cfg, table, returning, *, set_lambda=None, sort_by_parameter_order=False ): from sqlalchemy.dialects.sqlite import insert stmt = insert(table) if set_lambda: stmt = stmt.on_conflict_do_update(set_=set_lambda(stmt.excluded)) else: stmt = stmt.on_conflict_do_nothing() stmt = stmt.returning( *returning, sort_by_parameter_order=sort_by_parameter_order ) return stmt sqlalchemy/dialects/sqlite/pysqlite.py 0000755 00000061277 15125143220 0014236 0 ustar 00 # dialects/sqlite/pysqlite.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors r""" .. dialect:: sqlite+pysqlite :name: pysqlite :dbapi: sqlite3 :connectstring: sqlite+pysqlite:///file_path :url: https://docs.python.org/library/sqlite3.html Note that ``pysqlite`` is the same driver as the ``sqlite3`` module included with the Python distribution. Driver ------ The ``sqlite3`` Python DBAPI is standard on all modern Python versions; for cPython and Pypy, no additional installation is necessary. Connect Strings --------------- The file specification for the SQLite database is taken as the "database" portion of the URL. Note that the format of a SQLAlchemy url is: .. sourcecode:: text driver://user:pass@host/database This means that the actual filename to be used starts with the characters to the **right** of the third slash. So connecting to a relative filepath looks like:: # relative path e = create_engine("sqlite:///path/to/database.db") An absolute path, which is denoted by starting with a slash, means you need **four** slashes:: # absolute path e = create_engine("sqlite:////path/to/database.db") To use a Windows path, regular drive specifications and backslashes can be used. Double backslashes are probably needed:: # absolute path on Windows e = create_engine("sqlite:///C:\\path\\to\\database.db") To use sqlite ``:memory:`` database specify it as the filename using ``sqlite:///:memory:``. It's also the default if no filepath is present, specifying only ``sqlite://`` and nothing else:: # in-memory database (note three slashes) e = create_engine("sqlite:///:memory:") # also in-memory database e2 = create_engine("sqlite://") .. _pysqlite_uri_connections: URI Connections ^^^^^^^^^^^^^^^ Modern versions of SQLite support an alternative system of connecting using a `driver level URI <https://www.sqlite.org/uri.html>`_, which has the advantage that additional driver-level arguments can be passed including options such as "read only". The Python sqlite3 driver supports this mode under modern Python 3 versions. The SQLAlchemy pysqlite driver supports this mode of use by specifying "uri=true" in the URL query string. The SQLite-level "URI" is kept as the "database" portion of the SQLAlchemy url (that is, following a slash):: e = create_engine("sqlite:///file:path/to/database?mode=ro&uri=true") .. note:: The "uri=true" parameter must appear in the **query string** of the URL. It will not currently work as expected if it is only present in the :paramref:`_sa.create_engine.connect_args` parameter dictionary. The logic reconciles the simultaneous presence of SQLAlchemy's query string and SQLite's query string by separating out the parameters that belong to the Python sqlite3 driver vs. those that belong to the SQLite URI. This is achieved through the use of a fixed list of parameters known to be accepted by the Python side of the driver. For example, to include a URL that indicates the Python sqlite3 "timeout" and "check_same_thread" parameters, along with the SQLite "mode" and "nolock" parameters, they can all be passed together on the query string:: e = create_engine( "sqlite:///file:path/to/database?" "check_same_thread=true&timeout=10&mode=ro&nolock=1&uri=true" ) Above, the pysqlite / sqlite3 DBAPI would be passed arguments as:: sqlite3.connect( "file:path/to/database?mode=ro&nolock=1", check_same_thread=True, timeout=10, uri=True, ) Regarding future parameters added to either the Python or native drivers. new parameter names added to the SQLite URI scheme should be automatically accommodated by this scheme. New parameter names added to the Python driver side can be accommodated by specifying them in the :paramref:`_sa.create_engine.connect_args` dictionary, until dialect support is added by SQLAlchemy. For the less likely case that the native SQLite driver adds a new parameter name that overlaps with one of the existing, known Python driver parameters (such as "timeout" perhaps), SQLAlchemy's dialect would require adjustment for the URL scheme to continue to support this. As is always the case for all SQLAlchemy dialects, the entire "URL" process can be bypassed in :func:`_sa.create_engine` through the use of the :paramref:`_sa.create_engine.creator` parameter which allows for a custom callable that creates a Python sqlite3 driver level connection directly. .. versionadded:: 1.3.9 .. seealso:: `Uniform Resource Identifiers <https://www.sqlite.org/uri.html>`_ - in the SQLite documentation .. _pysqlite_regexp: Regular Expression Support --------------------------- .. versionadded:: 1.4 Support for the :meth:`_sql.ColumnOperators.regexp_match` operator is provided using Python's re.search_ function. SQLite itself does not include a working regular expression operator; instead, it includes a non-implemented placeholder operator ``REGEXP`` that calls a user-defined function that must be provided. SQLAlchemy's implementation makes use of the pysqlite create_function_ hook as follows:: def regexp(a, b): return re.search(a, b) is not None sqlite_connection.create_function( "regexp", 2, regexp, ) There is currently no support for regular expression flags as a separate argument, as these are not supported by SQLite's REGEXP operator, however these may be included inline within the regular expression string. See `Python regular expressions`_ for details. .. seealso:: `Python regular expressions`_: Documentation for Python's regular expression syntax. .. _create_function: https://docs.python.org/3/library/sqlite3.html#sqlite3.Connection.create_function .. _re.search: https://docs.python.org/3/library/re.html#re.search .. _Python regular expressions: https://docs.python.org/3/library/re.html#re.search Compatibility with sqlite3 "native" date and datetime types ----------------------------------------------------------- The pysqlite driver includes the sqlite3.PARSE_DECLTYPES and sqlite3.PARSE_COLNAMES options, which have the effect of any column or expression explicitly cast as "date" or "timestamp" will be converted to a Python date or datetime object. The date and datetime types provided with the pysqlite dialect are not currently compatible with these options, since they render the ISO date/datetime including microseconds, which pysqlite's driver does not. Additionally, SQLAlchemy does not at this time automatically render the "cast" syntax required for the freestanding functions "current_timestamp" and "current_date" to return datetime/date types natively. Unfortunately, pysqlite does not provide the standard DBAPI types in ``cursor.description``, leaving SQLAlchemy with no way to detect these types on the fly without expensive per-row type checks. Keeping in mind that pysqlite's parsing option is not recommended, nor should be necessary, for use with SQLAlchemy, usage of PARSE_DECLTYPES can be forced if one configures "native_datetime=True" on create_engine():: engine = create_engine( "sqlite://", connect_args={ "detect_types": sqlite3.PARSE_DECLTYPES | sqlite3.PARSE_COLNAMES }, native_datetime=True, ) With this flag enabled, the DATE and TIMESTAMP types (but note - not the DATETIME or TIME types...confused yet ?) will not perform any bind parameter or result processing. Execution of "func.current_date()" will return a string. "func.current_timestamp()" is registered as returning a DATETIME type in SQLAlchemy, so this function still receives SQLAlchemy-level result processing. .. _pysqlite_threading_pooling: Threading/Pooling Behavior --------------------------- The ``sqlite3`` DBAPI by default prohibits the use of a particular connection in a thread which is not the one in which it was created. As SQLite has matured, it's behavior under multiple threads has improved, and even includes options for memory only databases to be used in multiple threads. The thread prohibition is known as "check same thread" and may be controlled using the ``sqlite3`` parameter ``check_same_thread``, which will disable or enable this check. SQLAlchemy's default behavior here is to set ``check_same_thread`` to ``False`` automatically whenever a file-based database is in use, to establish compatibility with the default pool class :class:`.QueuePool`. The SQLAlchemy ``pysqlite`` DBAPI establishes the connection pool differently based on the kind of SQLite database that's requested: * When a ``:memory:`` SQLite database is specified, the dialect by default will use :class:`.SingletonThreadPool`. This pool maintains a single connection per thread, so that all access to the engine within the current thread use the same ``:memory:`` database - other threads would access a different ``:memory:`` database. The ``check_same_thread`` parameter defaults to ``True``. * When a file-based database is specified, the dialect will use :class:`.QueuePool` as the source of connections. at the same time, the ``check_same_thread`` flag is set to False by default unless overridden. .. versionchanged:: 2.0 SQLite file database engines now use :class:`.QueuePool` by default. Previously, :class:`.NullPool` were used. The :class:`.NullPool` class may be used by specifying it via the :paramref:`_sa.create_engine.poolclass` parameter. Disabling Connection Pooling for File Databases ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Pooling may be disabled for a file based database by specifying the :class:`.NullPool` implementation for the :func:`_sa.create_engine.poolclass` parameter:: from sqlalchemy import NullPool engine = create_engine("sqlite:///myfile.db", poolclass=NullPool) It's been observed that the :class:`.NullPool` implementation incurs an extremely small performance overhead for repeated checkouts due to the lack of connection re-use implemented by :class:`.QueuePool`. However, it still may be beneficial to use this class if the application is experiencing issues with files being locked. Using a Memory Database in Multiple Threads ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To use a ``:memory:`` database in a multithreaded scenario, the same connection object must be shared among threads, since the database exists only within the scope of that connection. The :class:`.StaticPool` implementation will maintain a single connection globally, and the ``check_same_thread`` flag can be passed to Pysqlite as ``False``:: from sqlalchemy.pool import StaticPool engine = create_engine( "sqlite://", connect_args={"check_same_thread": False}, poolclass=StaticPool, ) Note that using a ``:memory:`` database in multiple threads requires a recent version of SQLite. Using Temporary Tables with SQLite ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Due to the way SQLite deals with temporary tables, if you wish to use a temporary table in a file-based SQLite database across multiple checkouts from the connection pool, such as when using an ORM :class:`.Session` where the temporary table should continue to remain after :meth:`.Session.commit` or :meth:`.Session.rollback` is called, a pool which maintains a single connection must be used. Use :class:`.SingletonThreadPool` if the scope is only needed within the current thread, or :class:`.StaticPool` is scope is needed within multiple threads for this case:: # maintain the same connection per thread from sqlalchemy.pool import SingletonThreadPool engine = create_engine("sqlite:///mydb.db", poolclass=SingletonThreadPool) # maintain the same connection across all threads from sqlalchemy.pool import StaticPool engine = create_engine("sqlite:///mydb.db", poolclass=StaticPool) Note that :class:`.SingletonThreadPool` should be configured for the number of threads that are to be used; beyond that number, connections will be closed out in a non deterministic way. Dealing with Mixed String / Binary Columns ------------------------------------------------------ The SQLite database is weakly typed, and as such it is possible when using binary values, which in Python are represented as ``b'some string'``, that a particular SQLite database can have data values within different rows where some of them will be returned as a ``b''`` value by the Pysqlite driver, and others will be returned as Python strings, e.g. ``''`` values. This situation is not known to occur if the SQLAlchemy :class:`.LargeBinary` datatype is used consistently, however if a particular SQLite database has data that was inserted using the Pysqlite driver directly, or when using the SQLAlchemy :class:`.String` type which was later changed to :class:`.LargeBinary`, the table will not be consistently readable because SQLAlchemy's :class:`.LargeBinary` datatype does not handle strings so it has no way of "encoding" a value that is in string format. To deal with a SQLite table that has mixed string / binary data in the same column, use a custom type that will check each row individually:: from sqlalchemy import String from sqlalchemy import TypeDecorator class MixedBinary(TypeDecorator): impl = String cache_ok = True def process_result_value(self, value, dialect): if isinstance(value, str): value = bytes(value, "utf-8") elif value is not None: value = bytes(value) return value Then use the above ``MixedBinary`` datatype in the place where :class:`.LargeBinary` would normally be used. .. _pysqlite_serializable: Serializable isolation / Savepoints / Transactional DDL ------------------------------------------------------- A newly revised version of this important section is now available at the top level of the SQLAlchemy SQLite documentation, in the section :ref:`sqlite_transactions`. .. _pysqlite_udfs: User-Defined Functions ---------------------- pysqlite supports a `create_function() <https://docs.python.org/3/library/sqlite3.html#sqlite3.Connection.create_function>`_ method that allows us to create our own user-defined functions (UDFs) in Python and use them directly in SQLite queries. These functions are registered with a specific DBAPI Connection. SQLAlchemy uses connection pooling with file-based SQLite databases, so we need to ensure that the UDF is attached to the connection when it is created. That is accomplished with an event listener:: from sqlalchemy import create_engine from sqlalchemy import event from sqlalchemy import text def udf(): return "udf-ok" engine = create_engine("sqlite:///./db_file") @event.listens_for(engine, "connect") def connect(conn, rec): conn.create_function("udf", 0, udf) for i in range(5): with engine.connect() as conn: print(conn.scalar(text("SELECT UDF()"))) """ # noqa import math import os import re from .base import DATE from .base import DATETIME from .base import SQLiteDialect from ... import exc from ... import pool from ... import types as sqltypes from ... import util class _SQLite_pysqliteTimeStamp(DATETIME): def bind_processor(self, dialect): if dialect.native_datetime: return None else: return DATETIME.bind_processor(self, dialect) def result_processor(self, dialect, coltype): if dialect.native_datetime: return None else: return DATETIME.result_processor(self, dialect, coltype) class _SQLite_pysqliteDate(DATE): def bind_processor(self, dialect): if dialect.native_datetime: return None else: return DATE.bind_processor(self, dialect) def result_processor(self, dialect, coltype): if dialect.native_datetime: return None else: return DATE.result_processor(self, dialect, coltype) class SQLiteDialect_pysqlite(SQLiteDialect): default_paramstyle = "qmark" supports_statement_cache = True returns_native_bytes = True colspecs = util.update_copy( SQLiteDialect.colspecs, { sqltypes.Date: _SQLite_pysqliteDate, sqltypes.TIMESTAMP: _SQLite_pysqliteTimeStamp, }, ) description_encoding = None driver = "pysqlite" @classmethod def import_dbapi(cls): from sqlite3 import dbapi2 as sqlite return sqlite @classmethod def _is_url_file_db(cls, url): if (url.database and url.database != ":memory:") and ( url.query.get("mode", None) != "memory" ): return True else: return False @classmethod def get_pool_class(cls, url): if cls._is_url_file_db(url): return pool.QueuePool else: return pool.SingletonThreadPool def _get_server_version_info(self, connection): return self.dbapi.sqlite_version_info _isolation_lookup = SQLiteDialect._isolation_lookup.union( { "AUTOCOMMIT": None, } ) def set_isolation_level(self, dbapi_connection, level): if level == "AUTOCOMMIT": dbapi_connection.isolation_level = None else: dbapi_connection.isolation_level = "" return super().set_isolation_level(dbapi_connection, level) def on_connect(self): def regexp(a, b): if b is None: return None return re.search(a, b) is not None if util.py38 and self._get_server_version_info(None) >= (3, 9): # sqlite must be greater than 3.8.3 for deterministic=True # https://docs.python.org/3/library/sqlite3.html#sqlite3.Connection.create_function # the check is more conservative since there were still issues # with following 3.8 sqlite versions create_func_kw = {"deterministic": True} else: create_func_kw = {} def set_regexp(dbapi_connection): dbapi_connection.create_function( "regexp", 2, regexp, **create_func_kw ) def floor_func(dbapi_connection): # NOTE: floor is optionally present in sqlite 3.35+ , however # as it is normally non-present we deliver floor() unconditionally # for now. # https://www.sqlite.org/lang_mathfunc.html dbapi_connection.create_function( "floor", 1, math.floor, **create_func_kw ) fns = [set_regexp, floor_func] def connect(conn): for fn in fns: fn(conn) return connect def create_connect_args(self, url): if url.username or url.password or url.host or url.port: raise exc.ArgumentError( "Invalid SQLite URL: %s\n" "Valid SQLite URL forms are:\n" " sqlite:///:memory: (or, sqlite://)\n" " sqlite:///relative/path/to/file.db\n" " sqlite:////absolute/path/to/file.db" % (url,) ) # theoretically, this list can be augmented, at least as far as # parameter names accepted by sqlite3/pysqlite, using # inspect.getfullargspec(). for the moment this seems like overkill # as these parameters don't change very often, and as always, # parameters passed to connect_args will always go to the # sqlite3/pysqlite driver. pysqlite_args = [ ("uri", bool), ("timeout", float), ("isolation_level", str), ("detect_types", int), ("check_same_thread", bool), ("cached_statements", int), ] opts = url.query pysqlite_opts = {} for key, type_ in pysqlite_args: util.coerce_kw_type(opts, key, type_, dest=pysqlite_opts) if pysqlite_opts.get("uri", False): uri_opts = dict(opts) # here, we are actually separating the parameters that go to # sqlite3/pysqlite vs. those that go the SQLite URI. What if # two names conflict? again, this seems to be not the case right # now, and in the case that new names are added to # either side which overlap, again the sqlite3/pysqlite parameters # can be passed through connect_args instead of in the URL. # If SQLite native URIs add a parameter like "timeout" that # we already have listed here for the python driver, then we need # to adjust for that here. for key, type_ in pysqlite_args: uri_opts.pop(key, None) filename = url.database if uri_opts: # sorting of keys is for unit test support filename += "?" + ( "&".join( "%s=%s" % (key, uri_opts[key]) for key in sorted(uri_opts) ) ) else: filename = url.database or ":memory:" if filename != ":memory:": filename = os.path.abspath(filename) pysqlite_opts.setdefault( "check_same_thread", not self._is_url_file_db(url) ) return ([filename], pysqlite_opts) def is_disconnect(self, e, connection, cursor): return isinstance( e, self.dbapi.ProgrammingError ) and "Cannot operate on a closed database." in str(e) dialect = SQLiteDialect_pysqlite class _SQLiteDialect_pysqlite_numeric(SQLiteDialect_pysqlite): """numeric dialect for testing only internal use only. This dialect is **NOT** supported by SQLAlchemy and may change at any time. """ supports_statement_cache = True default_paramstyle = "numeric" driver = "pysqlite_numeric" _first_bind = ":1" _not_in_statement_regexp = None def __init__(self, *arg, **kw): kw.setdefault("paramstyle", "numeric") super().__init__(*arg, **kw) def create_connect_args(self, url): arg, opts = super().create_connect_args(url) opts["factory"] = self._fix_sqlite_issue_99953() return arg, opts def _fix_sqlite_issue_99953(self): import sqlite3 first_bind = self._first_bind if self._not_in_statement_regexp: nis = self._not_in_statement_regexp def _test_sql(sql): m = nis.search(sql) assert not m, f"Found {nis.pattern!r} in {sql!r}" else: def _test_sql(sql): pass def _numeric_param_as_dict(parameters): if parameters: assert isinstance(parameters, tuple) return { str(idx): value for idx, value in enumerate(parameters, 1) } else: return () class SQLiteFix99953Cursor(sqlite3.Cursor): def execute(self, sql, parameters=()): _test_sql(sql) if first_bind in sql: parameters = _numeric_param_as_dict(parameters) return super().execute(sql, parameters) def executemany(self, sql, parameters): _test_sql(sql) if first_bind in sql: parameters = [ _numeric_param_as_dict(p) for p in parameters ] return super().executemany(sql, parameters) class SQLiteFix99953Connection(sqlite3.Connection): def cursor(self, factory=None): if factory is None: factory = SQLiteFix99953Cursor return super().cursor(factory=factory) def execute(self, sql, parameters=()): _test_sql(sql) if first_bind in sql: parameters = _numeric_param_as_dict(parameters) return super().execute(sql, parameters) def executemany(self, sql, parameters): _test_sql(sql) if first_bind in sql: parameters = [ _numeric_param_as_dict(p) for p in parameters ] return super().executemany(sql, parameters) return SQLiteFix99953Connection class _SQLiteDialect_pysqlite_dollar(_SQLiteDialect_pysqlite_numeric): """numeric dialect that uses $ for testing only internal use only. This dialect is **NOT** supported by SQLAlchemy and may change at any time. """ supports_statement_cache = True default_paramstyle = "numeric_dollar" driver = "pysqlite_dollar" _first_bind = "$1" _not_in_statement_regexp = re.compile(r"[^\d]:\d+") def __init__(self, *arg, **kw): kw.setdefault("paramstyle", "numeric_dollar") super().__init__(*arg, **kw) sqlalchemy/dialects/sqlite/aiosqlite.py 0000755 00000027742 15125143220 0014355 0 ustar 00 # dialects/sqlite/aiosqlite.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors r""" .. dialect:: sqlite+aiosqlite :name: aiosqlite :dbapi: aiosqlite :connectstring: sqlite+aiosqlite:///file_path :url: https://pypi.org/project/aiosqlite/ The aiosqlite dialect provides support for the SQLAlchemy asyncio interface running on top of pysqlite. aiosqlite is a wrapper around pysqlite that uses a background thread for each connection. It does not actually use non-blocking IO, as SQLite databases are not socket-based. However it does provide a working asyncio interface that's useful for testing and prototyping purposes. Using a special asyncio mediation layer, the aiosqlite dialect is usable as the backend for the :ref:`SQLAlchemy asyncio <asyncio_toplevel>` extension package. This dialect should normally be used only with the :func:`_asyncio.create_async_engine` engine creation function:: from sqlalchemy.ext.asyncio import create_async_engine engine = create_async_engine("sqlite+aiosqlite:///filename") The URL passes through all arguments to the ``pysqlite`` driver, so all connection arguments are the same as they are for that of :ref:`pysqlite`. .. _aiosqlite_udfs: User-Defined Functions ---------------------- aiosqlite extends pysqlite to support async, so we can create our own user-defined functions (UDFs) in Python and use them directly in SQLite queries as described here: :ref:`pysqlite_udfs`. .. _aiosqlite_serializable: Serializable isolation / Savepoints / Transactional DDL (asyncio version) ------------------------------------------------------------------------- A newly revised version of this important section is now available at the top level of the SQLAlchemy SQLite documentation, in the section :ref:`sqlite_transactions`. .. _aiosqlite_pooling: Pooling Behavior ---------------- The SQLAlchemy ``aiosqlite`` DBAPI establishes the connection pool differently based on the kind of SQLite database that's requested: * When a ``:memory:`` SQLite database is specified, the dialect by default will use :class:`.StaticPool`. This pool maintains a single connection, so that all access to the engine use the same ``:memory:`` database. * When a file-based database is specified, the dialect will use :class:`.AsyncAdaptedQueuePool` as the source of connections. .. versionchanged:: 2.0.38 SQLite file database engines now use :class:`.AsyncAdaptedQueuePool` by default. Previously, :class:`.NullPool` were used. The :class:`.NullPool` class may be used by specifying it via the :paramref:`_sa.create_engine.poolclass` parameter. """ # noqa import asyncio from collections import deque from functools import partial from .base import SQLiteExecutionContext from .pysqlite import SQLiteDialect_pysqlite from ... import pool from ... import util from ...engine import AdaptedConnection from ...util.concurrency import await_fallback from ...util.concurrency import await_only class AsyncAdapt_aiosqlite_cursor: # TODO: base on connectors/asyncio.py # see #10415 __slots__ = ( "_adapt_connection", "_connection", "description", "await_", "_rows", "arraysize", "rowcount", "lastrowid", ) server_side = False def __init__(self, adapt_connection): self._adapt_connection = adapt_connection self._connection = adapt_connection._connection self.await_ = adapt_connection.await_ self.arraysize = 1 self.rowcount = -1 self.description = None self._rows = deque() def close(self): self._rows.clear() def execute(self, operation, parameters=None): try: _cursor = self.await_(self._connection.cursor()) if parameters is None: self.await_(_cursor.execute(operation)) else: self.await_(_cursor.execute(operation, parameters)) if _cursor.description: self.description = _cursor.description self.lastrowid = self.rowcount = -1 if not self.server_side: self._rows = deque(self.await_(_cursor.fetchall())) else: self.description = None self.lastrowid = _cursor.lastrowid self.rowcount = _cursor.rowcount if not self.server_side: self.await_(_cursor.close()) else: self._cursor = _cursor except Exception as error: self._adapt_connection._handle_exception(error) def executemany(self, operation, seq_of_parameters): try: _cursor = self.await_(self._connection.cursor()) self.await_(_cursor.executemany(operation, seq_of_parameters)) self.description = None self.lastrowid = _cursor.lastrowid self.rowcount = _cursor.rowcount self.await_(_cursor.close()) except Exception as error: self._adapt_connection._handle_exception(error) def setinputsizes(self, *inputsizes): pass def __iter__(self): while self._rows: yield self._rows.popleft() def fetchone(self): if self._rows: return self._rows.popleft() else: return None def fetchmany(self, size=None): if size is None: size = self.arraysize rr = self._rows return [rr.popleft() for _ in range(min(size, len(rr)))] def fetchall(self): retval = list(self._rows) self._rows.clear() return retval class AsyncAdapt_aiosqlite_ss_cursor(AsyncAdapt_aiosqlite_cursor): # TODO: base on connectors/asyncio.py # see #10415 __slots__ = "_cursor" server_side = True def __init__(self, *arg, **kw): super().__init__(*arg, **kw) self._cursor = None def close(self): if self._cursor is not None: self.await_(self._cursor.close()) self._cursor = None def fetchone(self): return self.await_(self._cursor.fetchone()) def fetchmany(self, size=None): if size is None: size = self.arraysize return self.await_(self._cursor.fetchmany(size=size)) def fetchall(self): return self.await_(self._cursor.fetchall()) class AsyncAdapt_aiosqlite_connection(AdaptedConnection): await_ = staticmethod(await_only) __slots__ = ("dbapi",) def __init__(self, dbapi, connection): self.dbapi = dbapi self._connection = connection @property def isolation_level(self): return self._connection.isolation_level @isolation_level.setter def isolation_level(self, value): # aiosqlite's isolation_level setter works outside the Thread # that it's supposed to, necessitating setting check_same_thread=False. # for improved stability, we instead invent our own awaitable version # using aiosqlite's async queue directly. def set_iso(connection, value): connection.isolation_level = value function = partial(set_iso, self._connection._conn, value) future = asyncio.get_event_loop().create_future() self._connection._tx.put_nowait((future, function)) try: return self.await_(future) except Exception as error: self._handle_exception(error) def create_function(self, *args, **kw): try: self.await_(self._connection.create_function(*args, **kw)) except Exception as error: self._handle_exception(error) def cursor(self, server_side=False): if server_side: return AsyncAdapt_aiosqlite_ss_cursor(self) else: return AsyncAdapt_aiosqlite_cursor(self) def execute(self, *args, **kw): return self.await_(self._connection.execute(*args, **kw)) def rollback(self): try: self.await_(self._connection.rollback()) except Exception as error: self._handle_exception(error) def commit(self): try: self.await_(self._connection.commit()) except Exception as error: self._handle_exception(error) def close(self): try: self.await_(self._connection.close()) except ValueError: # this is undocumented for aiosqlite, that ValueError # was raised if .close() was called more than once, which is # both not customary for DBAPI and is also not a DBAPI.Error # exception. This is now fixed in aiosqlite via my PR # https://github.com/omnilib/aiosqlite/pull/238, so we can be # assured this will not become some other kind of exception, # since it doesn't raise anymore. pass except Exception as error: self._handle_exception(error) def _handle_exception(self, error): if ( isinstance(error, ValueError) and error.args[0] == "no active connection" ): raise self.dbapi.sqlite.OperationalError( "no active connection" ) from error else: raise error class AsyncAdaptFallback_aiosqlite_connection(AsyncAdapt_aiosqlite_connection): __slots__ = () await_ = staticmethod(await_fallback) class AsyncAdapt_aiosqlite_dbapi: def __init__(self, aiosqlite, sqlite): self.aiosqlite = aiosqlite self.sqlite = sqlite self.paramstyle = "qmark" self._init_dbapi_attributes() def _init_dbapi_attributes(self): for name in ( "DatabaseError", "Error", "IntegrityError", "NotSupportedError", "OperationalError", "ProgrammingError", "sqlite_version", "sqlite_version_info", ): setattr(self, name, getattr(self.aiosqlite, name)) for name in ("PARSE_COLNAMES", "PARSE_DECLTYPES"): setattr(self, name, getattr(self.sqlite, name)) for name in ("Binary",): setattr(self, name, getattr(self.sqlite, name)) def connect(self, *arg, **kw): async_fallback = kw.pop("async_fallback", False) creator_fn = kw.pop("async_creator_fn", None) if creator_fn: connection = creator_fn(*arg, **kw) else: connection = self.aiosqlite.connect(*arg, **kw) # it's a Thread. you'll thank us later connection.daemon = True if util.asbool(async_fallback): return AsyncAdaptFallback_aiosqlite_connection( self, await_fallback(connection), ) else: return AsyncAdapt_aiosqlite_connection( self, await_only(connection), ) class SQLiteExecutionContext_aiosqlite(SQLiteExecutionContext): def create_server_side_cursor(self): return self._dbapi_connection.cursor(server_side=True) class SQLiteDialect_aiosqlite(SQLiteDialect_pysqlite): driver = "aiosqlite" supports_statement_cache = True is_async = True supports_server_side_cursors = True execution_ctx_cls = SQLiteExecutionContext_aiosqlite @classmethod def import_dbapi(cls): return AsyncAdapt_aiosqlite_dbapi( __import__("aiosqlite"), __import__("sqlite3") ) @classmethod def get_pool_class(cls, url): if cls._is_url_file_db(url): return pool.AsyncAdaptedQueuePool else: return pool.StaticPool def is_disconnect(self, e, connection, cursor): if isinstance( e, self.dbapi.OperationalError ) and "no active connection" in str(e): return True return super().is_disconnect(e, connection, cursor) def get_driver_connection(self, connection): return connection._connection dialect = SQLiteDialect_aiosqlite sqlalchemy/dialects/sqlite/pysqlcipher.py 0000755 00000012373 15125143220 0014720 0 ustar 00 # dialects/sqlite/pysqlcipher.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors """ .. dialect:: sqlite+pysqlcipher :name: pysqlcipher :dbapi: sqlcipher 3 or pysqlcipher :connectstring: sqlite+pysqlcipher://:passphrase@/file_path[?kdf_iter=<iter>] Dialect for support of DBAPIs that make use of the `SQLCipher <https://www.zetetic.net/sqlcipher>`_ backend. Driver ------ Current dialect selection logic is: * If the :paramref:`_sa.create_engine.module` parameter supplies a DBAPI module, that module is used. * Otherwise for Python 3, choose https://pypi.org/project/sqlcipher3/ * If not available, fall back to https://pypi.org/project/pysqlcipher3/ * For Python 2, https://pypi.org/project/pysqlcipher/ is used. .. warning:: The ``pysqlcipher3`` and ``pysqlcipher`` DBAPI drivers are no longer maintained; the ``sqlcipher3`` driver as of this writing appears to be current. For future compatibility, any pysqlcipher-compatible DBAPI may be used as follows:: import sqlcipher_compatible_driver from sqlalchemy import create_engine e = create_engine( "sqlite+pysqlcipher://:password@/dbname.db", module=sqlcipher_compatible_driver, ) These drivers make use of the SQLCipher engine. This system essentially introduces new PRAGMA commands to SQLite which allows the setting of a passphrase and other encryption parameters, allowing the database file to be encrypted. Connect Strings --------------- The format of the connect string is in every way the same as that of the :mod:`~sqlalchemy.dialects.sqlite.pysqlite` driver, except that the "password" field is now accepted, which should contain a passphrase:: e = create_engine("sqlite+pysqlcipher://:testing@/foo.db") For an absolute file path, two leading slashes should be used for the database name:: e = create_engine("sqlite+pysqlcipher://:testing@//path/to/foo.db") A selection of additional encryption-related pragmas supported by SQLCipher as documented at https://www.zetetic.net/sqlcipher/sqlcipher-api/ can be passed in the query string, and will result in that PRAGMA being called for each new connection. Currently, ``cipher``, ``kdf_iter`` ``cipher_page_size`` and ``cipher_use_hmac`` are supported:: e = create_engine( "sqlite+pysqlcipher://:testing@/foo.db?cipher=aes-256-cfb&kdf_iter=64000" ) .. warning:: Previous versions of sqlalchemy did not take into consideration the encryption-related pragmas passed in the url string, that were silently ignored. This may cause errors when opening files saved by a previous sqlalchemy version if the encryption options do not match. Pooling Behavior ---------------- The driver makes a change to the default pool behavior of pysqlite as described in :ref:`pysqlite_threading_pooling`. The pysqlcipher driver has been observed to be significantly slower on connection than the pysqlite driver, most likely due to the encryption overhead, so the dialect here defaults to using the :class:`.SingletonThreadPool` implementation, instead of the :class:`.NullPool` pool used by pysqlite. As always, the pool implementation is entirely configurable using the :paramref:`_sa.create_engine.poolclass` parameter; the :class:`. StaticPool` may be more feasible for single-threaded use, or :class:`.NullPool` may be used to prevent unencrypted connections from being held open for long periods of time, at the expense of slower startup time for new connections. """ # noqa from .pysqlite import SQLiteDialect_pysqlite from ... import pool class SQLiteDialect_pysqlcipher(SQLiteDialect_pysqlite): driver = "pysqlcipher" supports_statement_cache = True pragmas = ("kdf_iter", "cipher", "cipher_page_size", "cipher_use_hmac") @classmethod def import_dbapi(cls): try: import sqlcipher3 as sqlcipher except ImportError: pass else: return sqlcipher from pysqlcipher3 import dbapi2 as sqlcipher return sqlcipher @classmethod def get_pool_class(cls, url): return pool.SingletonThreadPool def on_connect_url(self, url): super_on_connect = super().on_connect_url(url) # pull the info we need from the URL early. Even though URL # is immutable, we don't want any in-place changes to the URL # to affect things passphrase = url.password or "" url_query = dict(url.query) def on_connect(conn): cursor = conn.cursor() cursor.execute('pragma key="%s"' % passphrase) for prag in self.pragmas: value = url_query.get(prag, None) if value is not None: cursor.execute('pragma %s="%s"' % (prag, value)) cursor.close() if super_on_connect: super_on_connect(conn) return on_connect def create_connect_args(self, url): plain_url = url._replace(password=None) plain_url = plain_url.difference_update_query(self.pragmas) return super().create_connect_args(plain_url) dialect = SQLiteDialect_pysqlcipher sqlalchemy/dialects/sqlite/dml.py 0000755 00000021662 15125143220 0013132 0 ustar 00 # dialects/sqlite/dml.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php from __future__ import annotations from typing import Any from typing import List from typing import Optional from typing import Tuple from typing import Union from .._typing import _OnConflictIndexElementsT from .._typing import _OnConflictIndexWhereT from .._typing import _OnConflictSetT from .._typing import _OnConflictWhereT from ... import util from ...sql import coercions from ...sql import roles from ...sql import schema from ...sql._typing import _DMLTableArgument from ...sql.base import _exclusive_against from ...sql.base import _generative from ...sql.base import ColumnCollection from ...sql.base import ReadOnlyColumnCollection from ...sql.dml import Insert as StandardInsert from ...sql.elements import ClauseElement from ...sql.elements import ColumnElement from ...sql.elements import KeyedColumnElement from ...sql.elements import TextClause from ...sql.expression import alias from ...util.typing import Self __all__ = ("Insert", "insert") def insert(table: _DMLTableArgument) -> Insert: """Construct a sqlite-specific variant :class:`_sqlite.Insert` construct. .. container:: inherited_member The :func:`sqlalchemy.dialects.sqlite.insert` function creates a :class:`sqlalchemy.dialects.sqlite.Insert`. This class is based on the dialect-agnostic :class:`_sql.Insert` construct which may be constructed using the :func:`_sql.insert` function in SQLAlchemy Core. The :class:`_sqlite.Insert` construct includes additional methods :meth:`_sqlite.Insert.on_conflict_do_update`, :meth:`_sqlite.Insert.on_conflict_do_nothing`. """ return Insert(table) class Insert(StandardInsert): """SQLite-specific implementation of INSERT. Adds methods for SQLite-specific syntaxes such as ON CONFLICT. The :class:`_sqlite.Insert` object is created using the :func:`sqlalchemy.dialects.sqlite.insert` function. .. versionadded:: 1.4 .. seealso:: :ref:`sqlite_on_conflict_insert` """ stringify_dialect = "sqlite" inherit_cache = False @util.memoized_property def excluded( self, ) -> ReadOnlyColumnCollection[str, KeyedColumnElement[Any]]: """Provide the ``excluded`` namespace for an ON CONFLICT statement SQLite's ON CONFLICT clause allows reference to the row that would be inserted, known as ``excluded``. This attribute provides all columns in this row to be referenceable. .. tip:: The :attr:`_sqlite.Insert.excluded` attribute is an instance of :class:`_expression.ColumnCollection`, which provides an interface the same as that of the :attr:`_schema.Table.c` collection described at :ref:`metadata_tables_and_columns`. With this collection, ordinary names are accessible like attributes (e.g. ``stmt.excluded.some_column``), but special names and dictionary method names should be accessed using indexed access, such as ``stmt.excluded["column name"]`` or ``stmt.excluded["values"]``. See the docstring for :class:`_expression.ColumnCollection` for further examples. """ return alias(self.table, name="excluded").columns _on_conflict_exclusive = _exclusive_against( "_post_values_clause", msgs={ "_post_values_clause": "This Insert construct already has " "an ON CONFLICT clause established" }, ) @_generative @_on_conflict_exclusive def on_conflict_do_update( self, index_elements: _OnConflictIndexElementsT = None, index_where: _OnConflictIndexWhereT = None, set_: _OnConflictSetT = None, where: _OnConflictWhereT = None, ) -> Self: r""" Specifies a DO UPDATE SET action for ON CONFLICT clause. :param index_elements: A sequence consisting of string column names, :class:`_schema.Column` objects, or other column expression objects that will be used to infer a target index or unique constraint. :param index_where: Additional WHERE criterion that can be used to infer a conditional target index. :param set\_: A dictionary or other mapping object where the keys are either names of columns in the target table, or :class:`_schema.Column` objects or other ORM-mapped columns matching that of the target table, and expressions or literals as values, specifying the ``SET`` actions to take. .. versionadded:: 1.4 The :paramref:`_sqlite.Insert.on_conflict_do_update.set_` parameter supports :class:`_schema.Column` objects from the target :class:`_schema.Table` as keys. .. warning:: This dictionary does **not** take into account Python-specified default UPDATE values or generation functions, e.g. those specified using :paramref:`_schema.Column.onupdate`. These values will not be exercised for an ON CONFLICT style of UPDATE, unless they are manually specified in the :paramref:`.Insert.on_conflict_do_update.set_` dictionary. :param where: Optional argument. An expression object representing a ``WHERE`` clause that restricts the rows affected by ``DO UPDATE SET``. Rows not meeting the ``WHERE`` condition will not be updated (effectively a ``DO NOTHING`` for those rows). """ self._post_values_clause = OnConflictDoUpdate( index_elements, index_where, set_, where ) return self @_generative @_on_conflict_exclusive def on_conflict_do_nothing( self, index_elements: _OnConflictIndexElementsT = None, index_where: _OnConflictIndexWhereT = None, ) -> Self: """ Specifies a DO NOTHING action for ON CONFLICT clause. :param index_elements: A sequence consisting of string column names, :class:`_schema.Column` objects, or other column expression objects that will be used to infer a target index or unique constraint. :param index_where: Additional WHERE criterion that can be used to infer a conditional target index. """ self._post_values_clause = OnConflictDoNothing( index_elements, index_where ) return self class OnConflictClause(ClauseElement): stringify_dialect = "sqlite" inferred_target_elements: Optional[List[Union[str, schema.Column[Any]]]] inferred_target_whereclause: Optional[ Union[ColumnElement[Any], TextClause] ] def __init__( self, index_elements: _OnConflictIndexElementsT = None, index_where: _OnConflictIndexWhereT = None, ): if index_elements is not None: self.inferred_target_elements = [ coercions.expect(roles.DDLConstraintColumnRole, column) for column in index_elements ] self.inferred_target_whereclause = ( coercions.expect( roles.WhereHavingRole, index_where, ) if index_where is not None else None ) else: self.inferred_target_elements = ( self.inferred_target_whereclause ) = None class OnConflictDoNothing(OnConflictClause): __visit_name__ = "on_conflict_do_nothing" class OnConflictDoUpdate(OnConflictClause): __visit_name__ = "on_conflict_do_update" update_values_to_set: List[Tuple[Union[schema.Column[Any], str], Any]] update_whereclause: Optional[ColumnElement[Any]] def __init__( self, index_elements: _OnConflictIndexElementsT = None, index_where: _OnConflictIndexWhereT = None, set_: _OnConflictSetT = None, where: _OnConflictWhereT = None, ): super().__init__( index_elements=index_elements, index_where=index_where, ) if isinstance(set_, dict): if not set_: raise ValueError("set parameter dictionary must not be empty") elif isinstance(set_, ColumnCollection): set_ = dict(set_) else: raise ValueError( "set parameter must be a non-empty dictionary " "or a ColumnCollection such as the `.c.` collection " "of a Table object" ) self.update_values_to_set = [ (coercions.expect(roles.DMLColumnRole, key), value) for key, value in set_.items() ] self.update_whereclause = ( coercions.expect(roles.WhereHavingRole, where) if where is not None else None ) sqlalchemy/dialects/sqlite/__init__.py 0000755 00000002236 15125143220 0014111 0 ustar 00 # dialects/sqlite/__init__.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors from . import aiosqlite # noqa from . import base # noqa from . import pysqlcipher # noqa from . import pysqlite # noqa from .base import BLOB from .base import BOOLEAN from .base import CHAR from .base import DATE from .base import DATETIME from .base import DECIMAL from .base import FLOAT from .base import INTEGER from .base import JSON from .base import NUMERIC from .base import REAL from .base import SMALLINT from .base import TEXT from .base import TIME from .base import TIMESTAMP from .base import VARCHAR from .dml import Insert from .dml import insert # default dialect base.dialect = dialect = pysqlite.dialect __all__ = ( "BLOB", "BOOLEAN", "CHAR", "DATE", "DATETIME", "DECIMAL", "FLOAT", "INTEGER", "JSON", "NUMERIC", "SMALLINT", "TEXT", "TIME", "TIMESTAMP", "VARCHAR", "REAL", "Insert", "insert", "dialect", ) sqlalchemy/dialects/__init__.py 0000755 00000003352 15125143220 0012610 0 ustar 00 # dialects/__init__.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php from __future__ import annotations from typing import Callable from typing import Optional from typing import Type from typing import TYPE_CHECKING from .. import util if TYPE_CHECKING: from ..engine.interfaces import Dialect __all__ = ("mssql", "mysql", "oracle", "postgresql", "sqlite") def _auto_fn(name: str) -> Optional[Callable[[], Type[Dialect]]]: """default dialect importer. plugs into the :class:`.PluginLoader` as a first-hit system. """ if "." in name: dialect, driver = name.split(".") else: dialect = name driver = "base" try: if dialect == "mariadb": # it's "OK" for us to hardcode here since _auto_fn is already # hardcoded. if mysql / mariadb etc were third party dialects # they would just publish all the entrypoints, which would actually # look much nicer. module = __import__( "sqlalchemy.dialects.mysql.mariadb" ).dialects.mysql.mariadb return module.loader(driver) # type: ignore else: module = __import__("sqlalchemy.dialects.%s" % (dialect,)).dialects module = getattr(module, dialect) except ImportError: return None if hasattr(module, driver): module = getattr(module, driver) return lambda: module.dialect else: return None registry = util.PluginLoader("sqlalchemy.dialects", auto_fn=_auto_fn) plugins = util.PluginLoader("sqlalchemy.plugins") sqlalchemy/py.typed 0000644 00000000000 15125143220 0010366 0 ustar 00 sqlalchemy/events.py 0000755 00000001015 15125143220 0010557 0 ustar 00 # events.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """Core event interfaces.""" from __future__ import annotations from .engine.events import ConnectionEvents from .engine.events import DialectEvents from .pool import PoolResetState from .pool.events import PoolEvents from .sql.base import SchemaEventTarget from .sql.events import DDLEvents sqlalchemy/log.py 0000755 00000020637 15125143220 0010047 0 ustar 00 # log.py # Copyright (C) 2006-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # Includes alterations by Vinay Sajip vinay_sajip@yahoo.co.uk # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """Logging control and utilities. Control of logging for SA can be performed from the regular python logging module. The regular dotted module namespace is used, starting at 'sqlalchemy'. For class-level logging, the class name is appended. The "echo" keyword parameter, available on SQLA :class:`_engine.Engine` and :class:`_pool.Pool` objects, corresponds to a logger specific to that instance only. """ from __future__ import annotations import logging import sys from typing import Any from typing import Optional from typing import overload from typing import Set from typing import Type from typing import TypeVar from typing import Union from .util import py311 from .util import py38 from .util.typing import Literal if py38: STACKLEVEL = True # needed as of py3.11.0b1 # #8019 STACKLEVEL_OFFSET = 2 if py311 else 1 else: STACKLEVEL = False STACKLEVEL_OFFSET = 0 _IT = TypeVar("_IT", bound="Identified") _EchoFlagType = Union[None, bool, Literal["debug"]] # set initial level to WARN. This so that # log statements don't occur in the absence of explicit # logging being enabled for 'sqlalchemy'. rootlogger = logging.getLogger("sqlalchemy") if rootlogger.level == logging.NOTSET: rootlogger.setLevel(logging.WARN) def _add_default_handler(logger: logging.Logger) -> None: handler = logging.StreamHandler(sys.stdout) handler.setFormatter( logging.Formatter("%(asctime)s %(levelname)s %(name)s %(message)s") ) logger.addHandler(handler) _logged_classes: Set[Type[Identified]] = set() def _qual_logger_name_for_cls(cls: Type[Identified]) -> str: return ( getattr(cls, "_sqla_logger_namespace", None) or cls.__module__ + "." + cls.__name__ ) def class_logger(cls: Type[_IT]) -> Type[_IT]: logger = logging.getLogger(_qual_logger_name_for_cls(cls)) cls._should_log_debug = lambda self: logger.isEnabledFor( # type: ignore[method-assign] # noqa: E501 logging.DEBUG ) cls._should_log_info = lambda self: logger.isEnabledFor( # type: ignore[method-assign] # noqa: E501 logging.INFO ) cls.logger = logger _logged_classes.add(cls) return cls _IdentifiedLoggerType = Union[logging.Logger, "InstanceLogger"] class Identified: __slots__ = () logging_name: Optional[str] = None logger: _IdentifiedLoggerType _echo: _EchoFlagType def _should_log_debug(self) -> bool: return self.logger.isEnabledFor(logging.DEBUG) def _should_log_info(self) -> bool: return self.logger.isEnabledFor(logging.INFO) class InstanceLogger: """A logger adapter (wrapper) for :class:`.Identified` subclasses. This allows multiple instances (e.g. Engine or Pool instances) to share a logger, but have its verbosity controlled on a per-instance basis. The basic functionality is to return a logging level which is based on an instance's echo setting. Default implementation is: 'debug' -> logging.DEBUG True -> logging.INFO False -> Effective level of underlying logger ( logging.WARNING by default) None -> same as False """ # Map echo settings to logger levels _echo_map = { None: logging.NOTSET, False: logging.NOTSET, True: logging.INFO, "debug": logging.DEBUG, } _echo: _EchoFlagType __slots__ = ("echo", "logger") def __init__(self, echo: _EchoFlagType, name: str): self.echo = echo self.logger = logging.getLogger(name) # if echo flag is enabled and no handlers, # add a handler to the list if self._echo_map[echo] <= logging.INFO and not self.logger.handlers: _add_default_handler(self.logger) # # Boilerplate convenience methods # def debug(self, msg: str, *args: Any, **kwargs: Any) -> None: """Delegate a debug call to the underlying logger.""" self.log(logging.DEBUG, msg, *args, **kwargs) def info(self, msg: str, *args: Any, **kwargs: Any) -> None: """Delegate an info call to the underlying logger.""" self.log(logging.INFO, msg, *args, **kwargs) def warning(self, msg: str, *args: Any, **kwargs: Any) -> None: """Delegate a warning call to the underlying logger.""" self.log(logging.WARNING, msg, *args, **kwargs) warn = warning def error(self, msg: str, *args: Any, **kwargs: Any) -> None: """ Delegate an error call to the underlying logger. """ self.log(logging.ERROR, msg, *args, **kwargs) def exception(self, msg: str, *args: Any, **kwargs: Any) -> None: """Delegate an exception call to the underlying logger.""" kwargs["exc_info"] = 1 self.log(logging.ERROR, msg, *args, **kwargs) def critical(self, msg: str, *args: Any, **kwargs: Any) -> None: """Delegate a critical call to the underlying logger.""" self.log(logging.CRITICAL, msg, *args, **kwargs) def log(self, level: int, msg: str, *args: Any, **kwargs: Any) -> None: """Delegate a log call to the underlying logger. The level here is determined by the echo flag as well as that of the underlying logger, and logger._log() is called directly. """ # inline the logic from isEnabledFor(), # getEffectiveLevel(), to avoid overhead. if self.logger.manager.disable >= level: return selected_level = self._echo_map[self.echo] if selected_level == logging.NOTSET: selected_level = self.logger.getEffectiveLevel() if level >= selected_level: if STACKLEVEL: kwargs["stacklevel"] = ( kwargs.get("stacklevel", 1) + STACKLEVEL_OFFSET ) self.logger._log(level, msg, args, **kwargs) def isEnabledFor(self, level: int) -> bool: """Is this logger enabled for level 'level'?""" if self.logger.manager.disable >= level: return False return level >= self.getEffectiveLevel() def getEffectiveLevel(self) -> int: """What's the effective level for this logger?""" level = self._echo_map[self.echo] if level == logging.NOTSET: level = self.logger.getEffectiveLevel() return level def instance_logger( instance: Identified, echoflag: _EchoFlagType = None ) -> None: """create a logger for an instance that implements :class:`.Identified`.""" if instance.logging_name: name = "%s.%s" % ( _qual_logger_name_for_cls(instance.__class__), instance.logging_name, ) else: name = _qual_logger_name_for_cls(instance.__class__) instance._echo = echoflag # type: ignore logger: Union[logging.Logger, InstanceLogger] if echoflag in (False, None): # if no echo setting or False, return a Logger directly, # avoiding overhead of filtering logger = logging.getLogger(name) else: # if a specified echo flag, return an EchoLogger, # which checks the flag, overrides normal log # levels by calling logger._log() logger = InstanceLogger(echoflag, name) instance.logger = logger # type: ignore class echo_property: __doc__ = """\ When ``True``, enable log output for this element. This has the effect of setting the Python logging level for the namespace of this element's class and object reference. A value of boolean ``True`` indicates that the loglevel ``logging.INFO`` will be set for the logger, whereas the string value ``debug`` will set the loglevel to ``logging.DEBUG``. """ @overload def __get__( self, instance: Literal[None], owner: Type[Identified] ) -> echo_property: ... @overload def __get__( self, instance: Identified, owner: Type[Identified] ) -> _EchoFlagType: ... def __get__( self, instance: Optional[Identified], owner: Type[Identified] ) -> Union[echo_property, _EchoFlagType]: if instance is None: return self else: return instance._echo def __set__(self, instance: Identified, value: _EchoFlagType) -> None: instance_logger(instance, echoflag=value) sqlalchemy/orm/query.py 0000755 00000347704 15125143220 0011237 0 ustar 00 # orm/query.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """The Query class and support. Defines the :class:`_query.Query` class, the central construct used by the ORM to construct database queries. The :class:`_query.Query` class should not be confused with the :class:`_expression.Select` class, which defines database SELECT operations at the SQL (non-ORM) level. ``Query`` differs from ``Select`` in that it returns ORM-mapped objects and interacts with an ORM session, whereas the ``Select`` construct interacts directly with the database to return iterable result sets. """ from __future__ import annotations import collections.abc as collections_abc import operator from typing import Any from typing import Callable from typing import cast from typing import Dict from typing import Generic from typing import Iterable from typing import Iterator from typing import List from typing import Mapping from typing import Optional from typing import overload from typing import Sequence from typing import Tuple from typing import Type from typing import TYPE_CHECKING from typing import TypeVar from typing import Union from . import attributes from . import interfaces from . import loading from . import util as orm_util from ._typing import _O from .base import _assertions from .context import _column_descriptions from .context import _determine_last_joined_entity from .context import _legacy_filter_by_entity_zero from .context import FromStatement from .context import ORMCompileState from .context import QueryContext from .interfaces import ORMColumnDescription from .interfaces import ORMColumnsClauseRole from .util import AliasedClass from .util import object_mapper from .util import with_parent from .. import exc as sa_exc from .. import inspect from .. import inspection from .. import log from .. import sql from .. import util from ..engine import Result from ..engine import Row from ..event import dispatcher from ..event import EventTarget from ..sql import coercions from ..sql import expression from ..sql import roles from ..sql import Select from ..sql import util as sql_util from ..sql import visitors from ..sql._typing import _FromClauseArgument from ..sql._typing import _TP from ..sql.annotation import SupportsCloneAnnotations from ..sql.base import _entity_namespace_key from ..sql.base import _generative from ..sql.base import _NoArg from ..sql.base import Executable from ..sql.base import Generative from ..sql.elements import BooleanClauseList from ..sql.expression import Exists from ..sql.selectable import _MemoizedSelectEntities from ..sql.selectable import _SelectFromElements from ..sql.selectable import ForUpdateArg from ..sql.selectable import HasHints from ..sql.selectable import HasPrefixes from ..sql.selectable import HasSuffixes from ..sql.selectable import LABEL_STYLE_TABLENAME_PLUS_COL from ..sql.selectable import SelectLabelStyle from ..util.typing import Literal from ..util.typing import Self if TYPE_CHECKING: from ._typing import _EntityType from ._typing import _ExternalEntityType from ._typing import _InternalEntityType from ._typing import SynchronizeSessionArgument from .mapper import Mapper from .path_registry import PathRegistry from .session import _PKIdentityArgument from .session import Session from .state import InstanceState from ..engine.cursor import CursorResult from ..engine.interfaces import _ImmutableExecuteOptions from ..engine.interfaces import CompiledCacheType from ..engine.interfaces import IsolationLevel from ..engine.interfaces import SchemaTranslateMapType from ..engine.result import FrozenResult from ..engine.result import ScalarResult from ..sql._typing import _ColumnExpressionArgument from ..sql._typing import _ColumnExpressionOrStrLabelArgument from ..sql._typing import _ColumnsClauseArgument from ..sql._typing import _DMLColumnArgument from ..sql._typing import _JoinTargetArgument from ..sql._typing import _LimitOffsetType from ..sql._typing import _MAYBE_ENTITY from ..sql._typing import _no_kw from ..sql._typing import _NOT_ENTITY from ..sql._typing import _OnClauseArgument from ..sql._typing import _PropagateAttrsType from ..sql._typing import _T0 from ..sql._typing import _T1 from ..sql._typing import _T2 from ..sql._typing import _T3 from ..sql._typing import _T4 from ..sql._typing import _T5 from ..sql._typing import _T6 from ..sql._typing import _T7 from ..sql._typing import _TypedColumnClauseArgument as _TCCA from ..sql.base import CacheableOptions from ..sql.base import ExecutableOption from ..sql.dml import UpdateBase from ..sql.elements import ColumnElement from ..sql.elements import Label from ..sql.selectable import _ForUpdateOfArgument from ..sql.selectable import _JoinTargetElement from ..sql.selectable import _SetupJoinsElement from ..sql.selectable import Alias from ..sql.selectable import CTE from ..sql.selectable import ExecutableReturnsRows from ..sql.selectable import FromClause from ..sql.selectable import ScalarSelect from ..sql.selectable import Subquery __all__ = ["Query", "QueryContext"] _T = TypeVar("_T", bound=Any) @inspection._self_inspects @log.class_logger class Query( _SelectFromElements, SupportsCloneAnnotations, HasPrefixes, HasSuffixes, HasHints, EventTarget, log.Identified, Generative, Executable, Generic[_T], ): """ORM-level SQL construction object. .. legacy:: The ORM :class:`.Query` object is a legacy construct as of SQLAlchemy 2.0. See the notes at the top of :ref:`query_api_toplevel` for an overview, including links to migration documentation. :class:`_query.Query` objects are normally initially generated using the :meth:`~.Session.query` method of :class:`.Session`, and in less common cases by instantiating the :class:`_query.Query` directly and associating with a :class:`.Session` using the :meth:`_query.Query.with_session` method. """ # elements that are in Core and can be cached in the same way _where_criteria: Tuple[ColumnElement[Any], ...] = () _having_criteria: Tuple[ColumnElement[Any], ...] = () _order_by_clauses: Tuple[ColumnElement[Any], ...] = () _group_by_clauses: Tuple[ColumnElement[Any], ...] = () _limit_clause: Optional[ColumnElement[Any]] = None _offset_clause: Optional[ColumnElement[Any]] = None _distinct: bool = False _distinct_on: Tuple[ColumnElement[Any], ...] = () _for_update_arg: Optional[ForUpdateArg] = None _correlate: Tuple[FromClause, ...] = () _auto_correlate: bool = True _from_obj: Tuple[FromClause, ...] = () _setup_joins: Tuple[_SetupJoinsElement, ...] = () _label_style: SelectLabelStyle = SelectLabelStyle.LABEL_STYLE_LEGACY_ORM _memoized_select_entities = () _compile_options: Union[Type[CacheableOptions], CacheableOptions] = ( ORMCompileState.default_compile_options ) _with_options: Tuple[ExecutableOption, ...] load_options = QueryContext.default_load_options + { "_legacy_uniquing": True } _params: util.immutabledict[str, Any] = util.EMPTY_DICT # local Query builder state, not needed for # compilation or execution _enable_assertions = True _statement: Optional[ExecutableReturnsRows] = None session: Session dispatch: dispatcher[Query[_T]] # mirrors that of ClauseElement, used to propagate the "orm" # plugin as well as the "subject" of the plugin, e.g. the mapper # we are querying against. @util.memoized_property def _propagate_attrs(self) -> _PropagateAttrsType: return util.EMPTY_DICT def __init__( self, entities: Union[ _ColumnsClauseArgument[Any], Sequence[_ColumnsClauseArgument[Any]] ], session: Optional[Session] = None, ): """Construct a :class:`_query.Query` directly. E.g.:: q = Query([User, Address], session=some_session) The above is equivalent to:: q = some_session.query(User, Address) :param entities: a sequence of entities and/or SQL expressions. :param session: a :class:`.Session` with which the :class:`_query.Query` will be associated. Optional; a :class:`_query.Query` can be associated with a :class:`.Session` generatively via the :meth:`_query.Query.with_session` method as well. .. seealso:: :meth:`.Session.query` :meth:`_query.Query.with_session` """ # session is usually present. There's one case in subqueryloader # where it stores a Query without a Session and also there are tests # for the query(Entity).with_session(session) API which is likely in # some old recipes, however these are legacy as select() can now be # used. self.session = session # type: ignore self._set_entities(entities) def _set_propagate_attrs(self, values: Mapping[str, Any]) -> Self: self._propagate_attrs = util.immutabledict(values) return self def _set_entities( self, entities: Union[ _ColumnsClauseArgument[Any], Iterable[_ColumnsClauseArgument[Any]] ], ) -> None: self._raw_columns = [ coercions.expect( roles.ColumnsClauseRole, ent, apply_propagate_attrs=self, post_inspect=True, ) for ent in util.to_list(entities) ] def tuples(self: Query[_O]) -> Query[Tuple[_O]]: """return a tuple-typed form of this :class:`.Query`. This method invokes the :meth:`.Query.only_return_tuples` method with a value of ``True``, which by itself ensures that this :class:`.Query` will always return :class:`.Row` objects, even if the query is made against a single entity. It then also at the typing level will return a "typed" query, if possible, that will type result rows as ``Tuple`` objects with typed elements. This method can be compared to the :meth:`.Result.tuples` method, which returns "self", but from a typing perspective returns an object that will yield typed ``Tuple`` objects for results. Typing takes effect only if this :class:`.Query` object is a typed query object already. .. versionadded:: 2.0 .. seealso:: :meth:`.Result.tuples` - v2 equivalent method. """ return self.only_return_tuples(True) # type: ignore def _entity_from_pre_ent_zero(self) -> Optional[_InternalEntityType[Any]]: if not self._raw_columns: return None ent = self._raw_columns[0] if "parententity" in ent._annotations: return ent._annotations["parententity"] # type: ignore elif "bundle" in ent._annotations: return ent._annotations["bundle"] # type: ignore else: # label, other SQL expression for element in visitors.iterate(ent): if "parententity" in element._annotations: return element._annotations["parententity"] # type: ignore # noqa: E501 else: return None def _only_full_mapper_zero(self, methname: str) -> Mapper[Any]: if ( len(self._raw_columns) != 1 or "parententity" not in self._raw_columns[0]._annotations or not self._raw_columns[0].is_selectable ): raise sa_exc.InvalidRequestError( "%s() can only be used against " "a single mapped class." % methname ) return self._raw_columns[0]._annotations["parententity"] # type: ignore # noqa: E501 def _set_select_from( self, obj: Iterable[_FromClauseArgument], set_base_alias: bool ) -> None: fa = [ coercions.expect( roles.StrictFromClauseRole, elem, allow_select=True, apply_propagate_attrs=self, ) for elem in obj ] self._compile_options += {"_set_base_alias": set_base_alias} self._from_obj = tuple(fa) @_generative def _set_lazyload_from(self, state: InstanceState[Any]) -> Self: self.load_options += {"_lazy_loaded_from": state} return self def _get_condition(self) -> None: """used by legacy BakedQuery""" self._no_criterion_condition("get", order_by=False, distinct=False) def _get_existing_condition(self) -> None: self._no_criterion_assertion("get", order_by=False, distinct=False) def _no_criterion_assertion( self, meth: str, order_by: bool = True, distinct: bool = True ) -> None: if not self._enable_assertions: return if ( self._where_criteria or self._statement is not None or self._from_obj or self._setup_joins or self._limit_clause is not None or self._offset_clause is not None or self._group_by_clauses or (order_by and self._order_by_clauses) or (distinct and self._distinct) ): raise sa_exc.InvalidRequestError( "Query.%s() being called on a " "Query with existing criterion. " % meth ) def _no_criterion_condition( self, meth: str, order_by: bool = True, distinct: bool = True ) -> None: self._no_criterion_assertion(meth, order_by, distinct) self._from_obj = self._setup_joins = () if self._statement is not None: self._compile_options += {"_statement": None} self._where_criteria = () self._distinct = False self._order_by_clauses = self._group_by_clauses = () def _no_clauseelement_condition(self, meth: str) -> None: if not self._enable_assertions: return if self._order_by_clauses: raise sa_exc.InvalidRequestError( "Query.%s() being called on a " "Query with existing criterion. " % meth ) self._no_criterion_condition(meth) def _no_statement_condition(self, meth: str) -> None: if not self._enable_assertions: return if self._statement is not None: raise sa_exc.InvalidRequestError( ( "Query.%s() being called on a Query with an existing full " "statement - can't apply criterion." ) % meth ) def _no_limit_offset(self, meth: str) -> None: if not self._enable_assertions: return if self._limit_clause is not None or self._offset_clause is not None: raise sa_exc.InvalidRequestError( "Query.%s() being called on a Query which already has LIMIT " "or OFFSET applied. Call %s() before limit() or offset() " "are applied." % (meth, meth) ) @property def _has_row_limiting_clause(self) -> bool: return ( self._limit_clause is not None or self._offset_clause is not None ) def _get_options( self, populate_existing: Optional[bool] = None, version_check: Optional[bool] = None, only_load_props: Optional[Sequence[str]] = None, refresh_state: Optional[InstanceState[Any]] = None, identity_token: Optional[Any] = None, ) -> Self: load_options: Dict[str, Any] = {} compile_options: Dict[str, Any] = {} if version_check: load_options["_version_check"] = version_check if populate_existing: load_options["_populate_existing"] = populate_existing if refresh_state: load_options["_refresh_state"] = refresh_state compile_options["_for_refresh_state"] = True if only_load_props: compile_options["_only_load_props"] = frozenset(only_load_props) if identity_token: load_options["_identity_token"] = identity_token if load_options: self.load_options += load_options if compile_options: self._compile_options += compile_options return self def _clone(self, **kw: Any) -> Self: return self._generate() def _get_select_statement_only(self) -> Select[_T]: if self._statement is not None: raise sa_exc.InvalidRequestError( "Can't call this method on a Query that uses from_statement()" ) return cast("Select[_T]", self.statement) @property def statement(self) -> Union[Select[_T], FromStatement[_T], UpdateBase]: """The full SELECT statement represented by this Query. The statement by default will not have disambiguating labels applied to the construct unless with_labels(True) is called first. """ # .statement can return the direct future.Select() construct here, as # long as we are not using subsequent adaption features that # are made against raw entities, e.g. from_self(), with_polymorphic(), # select_entity_from(). If these features are being used, then # the Select() we return will not have the correct .selected_columns # collection and will not embed in subsequent queries correctly. # We could find a way to make this collection "correct", however # this would not be too different from doing the full compile as # we are doing in any case, the Select() would still not have the # proper state for other attributes like whereclause, order_by, # and these features are all deprecated in any case. # # for these reasons, Query is not a Select, it remains an ORM # object for which __clause_element__() must be called in order for # it to provide a real expression object. # # from there, it starts to look much like Query itself won't be # passed into the execute process and won't generate its own cache # key; this will all occur in terms of the ORM-enabled Select. stmt: Union[Select[_T], FromStatement[_T], UpdateBase] if not self._compile_options._set_base_alias: # if we don't have legacy top level aliasing features in use # then convert to a future select() directly stmt = self._statement_20(for_statement=True) else: stmt = self._compile_state(for_statement=True).statement if self._params: stmt = stmt.params(self._params) return stmt def _final_statement(self, legacy_query_style: bool = True) -> Select[Any]: """Return the 'final' SELECT statement for this :class:`.Query`. This is used by the testing suite only and is fairly inefficient. This is the Core-only select() that will be rendered by a complete compilation of this query, and is what .statement used to return in 1.3. """ q = self._clone() return q._compile_state( use_legacy_query_style=legacy_query_style ).statement # type: ignore def _statement_20( self, for_statement: bool = False, use_legacy_query_style: bool = True ) -> Union[Select[_T], FromStatement[_T]]: # TODO: this event needs to be deprecated, as it currently applies # only to ORM query and occurs at this spot that is now more # or less an artificial spot if self.dispatch.before_compile: for fn in self.dispatch.before_compile: new_query = fn(self) if new_query is not None and new_query is not self: self = new_query if not fn._bake_ok: # type: ignore self._compile_options += {"_bake_ok": False} compile_options = self._compile_options compile_options += { "_for_statement": for_statement, "_use_legacy_query_style": use_legacy_query_style, } stmt: Union[Select[_T], FromStatement[_T]] if self._statement is not None: stmt = FromStatement(self._raw_columns, self._statement) stmt.__dict__.update( _with_options=self._with_options, _with_context_options=self._with_context_options, _compile_options=compile_options, _execution_options=self._execution_options, _propagate_attrs=self._propagate_attrs, ) else: # Query / select() internal attributes are 99% cross-compatible stmt = Select._create_raw_select(**self.__dict__) stmt.__dict__.update( _label_style=self._label_style, _compile_options=compile_options, _propagate_attrs=self._propagate_attrs, ) stmt.__dict__.pop("session", None) # ensure the ORM context is used to compile the statement, even # if it has no ORM entities. This is so ORM-only things like # _legacy_joins are picked up that wouldn't be picked up by the # Core statement context if "compile_state_plugin" not in stmt._propagate_attrs: stmt._propagate_attrs = stmt._propagate_attrs.union( {"compile_state_plugin": "orm", "plugin_subject": None} ) return stmt def subquery( self, name: Optional[str] = None, with_labels: bool = False, reduce_columns: bool = False, ) -> Subquery: """Return the full SELECT statement represented by this :class:`_query.Query`, embedded within an :class:`_expression.Alias`. Eager JOIN generation within the query is disabled. .. seealso:: :meth:`_sql.Select.subquery` - v2 comparable method. :param name: string name to be assigned as the alias; this is passed through to :meth:`_expression.FromClause.alias`. If ``None``, a name will be deterministically generated at compile time. :param with_labels: if True, :meth:`.with_labels` will be called on the :class:`_query.Query` first to apply table-qualified labels to all columns. :param reduce_columns: if True, :meth:`_expression.Select.reduce_columns` will be called on the resulting :func:`_expression.select` construct, to remove same-named columns where one also refers to the other via foreign key or WHERE clause equivalence. """ q = self.enable_eagerloads(False) if with_labels: q = q.set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL) stmt = q._get_select_statement_only() if TYPE_CHECKING: assert isinstance(stmt, Select) if reduce_columns: stmt = stmt.reduce_columns() return stmt.subquery(name=name) def cte( self, name: Optional[str] = None, recursive: bool = False, nesting: bool = False, ) -> CTE: r"""Return the full SELECT statement represented by this :class:`_query.Query` represented as a common table expression (CTE). Parameters and usage are the same as those of the :meth:`_expression.SelectBase.cte` method; see that method for further details. Here is the `PostgreSQL WITH RECURSIVE example <https://www.postgresql.org/docs/current/static/queries-with.html>`_. Note that, in this example, the ``included_parts`` cte and the ``incl_alias`` alias of it are Core selectables, which means the columns are accessed via the ``.c.`` attribute. The ``parts_alias`` object is an :func:`_orm.aliased` instance of the ``Part`` entity, so column-mapped attributes are available directly:: from sqlalchemy.orm import aliased class Part(Base): __tablename__ = "part" part = Column(String, primary_key=True) sub_part = Column(String, primary_key=True) quantity = Column(Integer) included_parts = ( session.query(Part.sub_part, Part.part, Part.quantity) .filter(Part.part == "our part") .cte(name="included_parts", recursive=True) ) incl_alias = aliased(included_parts, name="pr") parts_alias = aliased(Part, name="p") included_parts = included_parts.union_all( session.query( parts_alias.sub_part, parts_alias.part, parts_alias.quantity ).filter(parts_alias.part == incl_alias.c.sub_part) ) q = session.query( included_parts.c.sub_part, func.sum(included_parts.c.quantity).label("total_quantity"), ).group_by(included_parts.c.sub_part) .. seealso:: :meth:`_sql.Select.cte` - v2 equivalent method. """ # noqa: E501 return ( self.enable_eagerloads(False) ._get_select_statement_only() .cte(name=name, recursive=recursive, nesting=nesting) ) def label(self, name: Optional[str]) -> Label[Any]: """Return the full SELECT statement represented by this :class:`_query.Query`, converted to a scalar subquery with a label of the given name. .. seealso:: :meth:`_sql.Select.label` - v2 comparable method. """ return ( self.enable_eagerloads(False) ._get_select_statement_only() .label(name) ) @overload def as_scalar( # type: ignore[overload-overlap] self: Query[Tuple[_MAYBE_ENTITY]], ) -> ScalarSelect[_MAYBE_ENTITY]: ... @overload def as_scalar( self: Query[Tuple[_NOT_ENTITY]], ) -> ScalarSelect[_NOT_ENTITY]: ... @overload def as_scalar(self) -> ScalarSelect[Any]: ... @util.deprecated( "1.4", "The :meth:`_query.Query.as_scalar` method is deprecated and will be " "removed in a future release. Please refer to " ":meth:`_query.Query.scalar_subquery`.", ) def as_scalar(self) -> ScalarSelect[Any]: """Return the full SELECT statement represented by this :class:`_query.Query`, converted to a scalar subquery. """ return self.scalar_subquery() @overload def scalar_subquery( self: Query[Tuple[_MAYBE_ENTITY]], ) -> ScalarSelect[Any]: ... @overload def scalar_subquery( self: Query[Tuple[_NOT_ENTITY]], ) -> ScalarSelect[_NOT_ENTITY]: ... @overload def scalar_subquery(self) -> ScalarSelect[Any]: ... def scalar_subquery(self) -> ScalarSelect[Any]: """Return the full SELECT statement represented by this :class:`_query.Query`, converted to a scalar subquery. Analogous to :meth:`sqlalchemy.sql.expression.SelectBase.scalar_subquery`. .. versionchanged:: 1.4 The :meth:`_query.Query.scalar_subquery` method replaces the :meth:`_query.Query.as_scalar` method. .. seealso:: :meth:`_sql.Select.scalar_subquery` - v2 comparable method. """ return ( self.enable_eagerloads(False) ._get_select_statement_only() .scalar_subquery() ) @property def selectable(self) -> Union[Select[_T], FromStatement[_T], UpdateBase]: """Return the :class:`_expression.Select` object emitted by this :class:`_query.Query`. Used for :func:`_sa.inspect` compatibility, this is equivalent to:: query.enable_eagerloads(False).with_labels().statement """ return self.__clause_element__() def __clause_element__( self, ) -> Union[Select[_T], FromStatement[_T], UpdateBase]: return ( self._with_compile_options( _enable_eagerloads=False, _render_for_subquery=True ) .set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL) .statement ) @overload def only_return_tuples( self: Query[_O], value: Literal[True] ) -> RowReturningQuery[Tuple[_O]]: ... @overload def only_return_tuples( self: Query[_O], value: Literal[False] ) -> Query[_O]: ... @_generative def only_return_tuples(self, value: bool) -> Query[Any]: """When set to True, the query results will always be a :class:`.Row` object. This can change a query that normally returns a single entity as a scalar to return a :class:`.Row` result in all cases. .. seealso:: :meth:`.Query.tuples` - returns tuples, but also at the typing level will type results as ``Tuple``. :meth:`_query.Query.is_single_entity` :meth:`_engine.Result.tuples` - v2 comparable method. """ self.load_options += dict(_only_return_tuples=value) return self @property def is_single_entity(self) -> bool: """Indicates if this :class:`_query.Query` returns tuples or single entities. Returns True if this query returns a single entity for each instance in its result list, and False if this query returns a tuple of entities for each result. .. versionadded:: 1.3.11 .. seealso:: :meth:`_query.Query.only_return_tuples` """ return ( not self.load_options._only_return_tuples and len(self._raw_columns) == 1 and "parententity" in self._raw_columns[0]._annotations and isinstance( self._raw_columns[0]._annotations["parententity"], ORMColumnsClauseRole, ) ) @_generative def enable_eagerloads(self, value: bool) -> Self: """Control whether or not eager joins and subqueries are rendered. When set to False, the returned Query will not render eager joins regardless of :func:`~sqlalchemy.orm.joinedload`, :func:`~sqlalchemy.orm.subqueryload` options or mapper-level ``lazy='joined'``/``lazy='subquery'`` configurations. This is used primarily when nesting the Query's statement into a subquery or other selectable, or when using :meth:`_query.Query.yield_per`. """ self._compile_options += {"_enable_eagerloads": value} return self @_generative def _with_compile_options(self, **opt: Any) -> Self: self._compile_options += opt return self @util.became_legacy_20( ":meth:`_orm.Query.with_labels` and :meth:`_orm.Query.apply_labels`", alternative="Use set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL) " "instead.", ) def with_labels(self) -> Self: return self.set_label_style( SelectLabelStyle.LABEL_STYLE_TABLENAME_PLUS_COL ) apply_labels = with_labels @property def get_label_style(self) -> SelectLabelStyle: """ Retrieve the current label style. .. versionadded:: 1.4 .. seealso:: :meth:`_sql.Select.get_label_style` - v2 equivalent method. """ return self._label_style def set_label_style(self, style: SelectLabelStyle) -> Self: """Apply column labels to the return value of Query.statement. Indicates that this Query's `statement` accessor should return a SELECT statement that applies labels to all columns in the form <tablename>_<columnname>; this is commonly used to disambiguate columns from multiple tables which have the same name. When the `Query` actually issues SQL to load rows, it always uses column labeling. .. note:: The :meth:`_query.Query.set_label_style` method *only* applies the output of :attr:`_query.Query.statement`, and *not* to any of the result-row invoking systems of :class:`_query.Query` itself, e.g. :meth:`_query.Query.first`, :meth:`_query.Query.all`, etc. To execute a query using :meth:`_query.Query.set_label_style`, invoke the :attr:`_query.Query.statement` using :meth:`.Session.execute`:: result = session.execute( query.set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL).statement ) .. versionadded:: 1.4 .. seealso:: :meth:`_sql.Select.set_label_style` - v2 equivalent method. """ # noqa if self._label_style is not style: self = self._generate() self._label_style = style return self @_generative def enable_assertions(self, value: bool) -> Self: """Control whether assertions are generated. When set to False, the returned Query will not assert its state before certain operations, including that LIMIT/OFFSET has not been applied when filter() is called, no criterion exists when get() is called, and no "from_statement()" exists when filter()/order_by()/group_by() etc. is called. This more permissive mode is used by custom Query subclasses to specify criterion or other modifiers outside of the usual usage patterns. Care should be taken to ensure that the usage pattern is even possible. A statement applied by from_statement() will override any criterion set by filter() or order_by(), for example. """ self._enable_assertions = value return self @property def whereclause(self) -> Optional[ColumnElement[bool]]: """A readonly attribute which returns the current WHERE criterion for this Query. This returned value is a SQL expression construct, or ``None`` if no criterion has been established. .. seealso:: :attr:`_sql.Select.whereclause` - v2 equivalent property. """ return BooleanClauseList._construct_for_whereclause( self._where_criteria ) @_generative def _with_current_path(self, path: PathRegistry) -> Self: """indicate that this query applies to objects loaded within a certain path. Used by deferred loaders (see strategies.py) which transfer query options from an originating query to a newly generated query intended for the deferred load. """ self._compile_options += {"_current_path": path} return self @_generative def yield_per(self, count: int) -> Self: r"""Yield only ``count`` rows at a time. The purpose of this method is when fetching very large result sets (> 10K rows), to batch results in sub-collections and yield them out partially, so that the Python interpreter doesn't need to declare very large areas of memory which is both time consuming and leads to excessive memory use. The performance from fetching hundreds of thousands of rows can often double when a suitable yield-per setting (e.g. approximately 1000) is used, even with DBAPIs that buffer rows (which are most). As of SQLAlchemy 1.4, the :meth:`_orm.Query.yield_per` method is equivalent to using the ``yield_per`` execution option at the ORM level. See the section :ref:`orm_queryguide_yield_per` for further background on this option. .. seealso:: :ref:`orm_queryguide_yield_per` """ self.load_options += {"_yield_per": count} return self @util.became_legacy_20( ":meth:`_orm.Query.get`", alternative="The method is now available as :meth:`_orm.Session.get`", ) def get(self, ident: _PKIdentityArgument) -> Optional[Any]: """Return an instance based on the given primary key identifier, or ``None`` if not found. E.g.:: my_user = session.query(User).get(5) some_object = session.query(VersionedFoo).get((5, 10)) some_object = session.query(VersionedFoo).get({"id": 5, "version_id": 10}) :meth:`_query.Query.get` is special in that it provides direct access to the identity map of the owning :class:`.Session`. If the given primary key identifier is present in the local identity map, the object is returned directly from this collection and no SQL is emitted, unless the object has been marked fully expired. If not present, a SELECT is performed in order to locate the object. :meth:`_query.Query.get` also will perform a check if the object is present in the identity map and marked as expired - a SELECT is emitted to refresh the object as well as to ensure that the row is still present. If not, :class:`~sqlalchemy.orm.exc.ObjectDeletedError` is raised. :meth:`_query.Query.get` is only used to return a single mapped instance, not multiple instances or individual column constructs, and strictly on a single primary key value. The originating :class:`_query.Query` must be constructed in this way, i.e. against a single mapped entity, with no additional filtering criterion. Loading options via :meth:`_query.Query.options` may be applied however, and will be used if the object is not yet locally present. :param ident: A scalar, tuple, or dictionary representing the primary key. For a composite (e.g. multiple column) primary key, a tuple or dictionary should be passed. For a single-column primary key, the scalar calling form is typically the most expedient. If the primary key of a row is the value "5", the call looks like:: my_object = query.get(5) The tuple form contains primary key values typically in the order in which they correspond to the mapped :class:`_schema.Table` object's primary key columns, or if the :paramref:`_orm.Mapper.primary_key` configuration parameter were used, in the order used for that parameter. For example, if the primary key of a row is represented by the integer digits "5, 10" the call would look like:: my_object = query.get((5, 10)) The dictionary form should include as keys the mapped attribute names corresponding to each element of the primary key. If the mapped class has the attributes ``id``, ``version_id`` as the attributes which store the object's primary key value, the call would look like:: my_object = query.get({"id": 5, "version_id": 10}) .. versionadded:: 1.3 the :meth:`_query.Query.get` method now optionally accepts a dictionary of attribute names to values in order to indicate a primary key identifier. :return: The object instance, or ``None``. """ # noqa: E501 self._no_criterion_assertion("get", order_by=False, distinct=False) # we still implement _get_impl() so that baked query can override # it return self._get_impl(ident, loading.load_on_pk_identity) def _get_impl( self, primary_key_identity: _PKIdentityArgument, db_load_fn: Callable[..., Any], identity_token: Optional[Any] = None, ) -> Optional[Any]: mapper = self._only_full_mapper_zero("get") return self.session._get_impl( mapper, primary_key_identity, db_load_fn, populate_existing=self.load_options._populate_existing, with_for_update=self._for_update_arg, options=self._with_options, identity_token=identity_token, execution_options=self._execution_options, ) @property def lazy_loaded_from(self) -> Optional[InstanceState[Any]]: """An :class:`.InstanceState` that is using this :class:`_query.Query` for a lazy load operation. .. deprecated:: 1.4 This attribute should be viewed via the :attr:`.ORMExecuteState.lazy_loaded_from` attribute, within the context of the :meth:`.SessionEvents.do_orm_execute` event. .. seealso:: :attr:`.ORMExecuteState.lazy_loaded_from` """ return self.load_options._lazy_loaded_from # type: ignore @property def _current_path(self) -> PathRegistry: return self._compile_options._current_path # type: ignore @_generative def correlate( self, *fromclauses: Union[Literal[None, False], _FromClauseArgument], ) -> Self: """Return a :class:`.Query` construct which will correlate the given FROM clauses to that of an enclosing :class:`.Query` or :func:`~.expression.select`. The method here accepts mapped classes, :func:`.aliased` constructs, and :class:`_orm.Mapper` constructs as arguments, which are resolved into expression constructs, in addition to appropriate expression constructs. The correlation arguments are ultimately passed to :meth:`_expression.Select.correlate` after coercion to expression constructs. The correlation arguments take effect in such cases as when :meth:`_query.Query.from_self` is used, or when a subquery as returned by :meth:`_query.Query.subquery` is embedded in another :func:`_expression.select` construct. .. seealso:: :meth:`_sql.Select.correlate` - v2 equivalent method. """ self._auto_correlate = False if fromclauses and fromclauses[0] in {None, False}: self._correlate = () else: self._correlate = self._correlate + tuple( coercions.expect(roles.FromClauseRole, f) for f in fromclauses ) return self @_generative def autoflush(self, setting: bool) -> Self: """Return a Query with a specific 'autoflush' setting. As of SQLAlchemy 1.4, the :meth:`_orm.Query.autoflush` method is equivalent to using the ``autoflush`` execution option at the ORM level. See the section :ref:`orm_queryguide_autoflush` for further background on this option. """ self.load_options += {"_autoflush": setting} return self @_generative def populate_existing(self) -> Self: """Return a :class:`_query.Query` that will expire and refresh all instances as they are loaded, or reused from the current :class:`.Session`. As of SQLAlchemy 1.4, the :meth:`_orm.Query.populate_existing` method is equivalent to using the ``populate_existing`` execution option at the ORM level. See the section :ref:`orm_queryguide_populate_existing` for further background on this option. """ self.load_options += {"_populate_existing": True} return self @_generative def _with_invoke_all_eagers(self, value: bool) -> Self: """Set the 'invoke all eagers' flag which causes joined- and subquery loaders to traverse into already-loaded related objects and collections. Default is that of :attr:`_query.Query._invoke_all_eagers`. """ self.load_options += {"_invoke_all_eagers": value} return self @util.became_legacy_20( ":meth:`_orm.Query.with_parent`", alternative="Use the :func:`_orm.with_parent` standalone construct.", ) @util.preload_module("sqlalchemy.orm.relationships") def with_parent( self, instance: object, property: Optional[ # noqa: A002 attributes.QueryableAttribute[Any] ] = None, from_entity: Optional[_ExternalEntityType[Any]] = None, ) -> Self: """Add filtering criterion that relates the given instance to a child object or collection, using its attribute state as well as an established :func:`_orm.relationship()` configuration. The method uses the :func:`.with_parent` function to generate the clause, the result of which is passed to :meth:`_query.Query.filter`. Parameters are the same as :func:`.with_parent`, with the exception that the given property can be None, in which case a search is performed against this :class:`_query.Query` object's target mapper. :param instance: An instance which has some :func:`_orm.relationship`. :param property: Class bound attribute which indicates what relationship from the instance should be used to reconcile the parent/child relationship. :param from_entity: Entity in which to consider as the left side. This defaults to the "zero" entity of the :class:`_query.Query` itself. """ relationships = util.preloaded.orm_relationships if from_entity: entity_zero = inspect(from_entity) else: entity_zero = _legacy_filter_by_entity_zero(self) if property is None: # TODO: deprecate, property has to be supplied mapper = object_mapper(instance) for prop in mapper.iterate_properties: if ( isinstance(prop, relationships.RelationshipProperty) and prop.mapper is entity_zero.mapper # type: ignore ): property = prop # type: ignore # noqa: A001 break else: raise sa_exc.InvalidRequestError( "Could not locate a property which relates instances " "of class '%s' to instances of class '%s'" % ( entity_zero.mapper.class_.__name__, # type: ignore instance.__class__.__name__, ) ) return self.filter( with_parent( instance, property, # type: ignore entity_zero.entity, # type: ignore ) ) @_generative def add_entity( self, entity: _EntityType[Any], alias: Optional[Union[Alias, Subquery]] = None, ) -> Query[Any]: """add a mapped entity to the list of result columns to be returned. .. seealso:: :meth:`_sql.Select.add_columns` - v2 comparable method. """ if alias is not None: # TODO: deprecate entity = AliasedClass(entity, alias) self._raw_columns = list(self._raw_columns) self._raw_columns.append( coercions.expect( roles.ColumnsClauseRole, entity, apply_propagate_attrs=self ) ) return self @_generative def with_session(self, session: Session) -> Self: """Return a :class:`_query.Query` that will use the given :class:`.Session`. While the :class:`_query.Query` object is normally instantiated using the :meth:`.Session.query` method, it is legal to build the :class:`_query.Query` directly without necessarily using a :class:`.Session`. Such a :class:`_query.Query` object, or any :class:`_query.Query` already associated with a different :class:`.Session`, can produce a new :class:`_query.Query` object associated with a target session using this method:: from sqlalchemy.orm import Query query = Query([MyClass]).filter(MyClass.id == 5) result = query.with_session(my_session).one() """ self.session = session return self def _legacy_from_self( self, *entities: _ColumnsClauseArgument[Any] ) -> Self: # used for query.count() as well as for the same # function in BakedQuery, as well as some old tests in test_baked.py. fromclause = ( self.set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL) .correlate(None) .subquery() ._anonymous_fromclause() ) q = self._from_selectable(fromclause) if entities: q._set_entities(entities) return q @_generative def _set_enable_single_crit(self, val: bool) -> Self: self._compile_options += {"_enable_single_crit": val} return self @_generative def _from_selectable( self, fromclause: FromClause, set_entity_from: bool = True ) -> Self: for attr in ( "_where_criteria", "_order_by_clauses", "_group_by_clauses", "_limit_clause", "_offset_clause", "_last_joined_entity", "_setup_joins", "_memoized_select_entities", "_distinct", "_distinct_on", "_having_criteria", "_prefixes", "_suffixes", ): self.__dict__.pop(attr, None) self._set_select_from([fromclause], set_entity_from) self._compile_options += { "_enable_single_crit": False, } return self @util.deprecated( "1.4", ":meth:`_query.Query.values` " "is deprecated and will be removed in a " "future release. Please use :meth:`_query.Query.with_entities`", ) def values(self, *columns: _ColumnsClauseArgument[Any]) -> Iterable[Any]: """Return an iterator yielding result tuples corresponding to the given list of columns """ return self._values_no_warn(*columns) _values = values def _values_no_warn( self, *columns: _ColumnsClauseArgument[Any] ) -> Iterable[Any]: if not columns: return iter(()) q = self._clone().enable_eagerloads(False) q._set_entities(columns) if not q.load_options._yield_per: q.load_options += {"_yield_per": 10} return iter(q) @util.deprecated( "1.4", ":meth:`_query.Query.value` " "is deprecated and will be removed in a " "future release. Please use :meth:`_query.Query.with_entities` " "in combination with :meth:`_query.Query.scalar`", ) def value(self, column: _ColumnExpressionArgument[Any]) -> Any: """Return a scalar result corresponding to the given column expression. """ try: return next(self._values_no_warn(column))[0] # type: ignore except StopIteration: return None @overload def with_entities(self, _entity: _EntityType[_O]) -> Query[_O]: ... @overload def with_entities( self, _colexpr: roles.TypedColumnsClauseRole[_T], ) -> RowReturningQuery[Tuple[_T]]: ... # START OVERLOADED FUNCTIONS self.with_entities RowReturningQuery 2-8 # code within this block is **programmatically, # statically generated** by tools/generate_tuple_map_overloads.py @overload def with_entities( self, __ent0: _TCCA[_T0], __ent1: _TCCA[_T1] ) -> RowReturningQuery[Tuple[_T0, _T1]]: ... @overload def with_entities( self, __ent0: _TCCA[_T0], __ent1: _TCCA[_T1], __ent2: _TCCA[_T2] ) -> RowReturningQuery[Tuple[_T0, _T1, _T2]]: ... @overload def with_entities( self, __ent0: _TCCA[_T0], __ent1: _TCCA[_T1], __ent2: _TCCA[_T2], __ent3: _TCCA[_T3], ) -> RowReturningQuery[Tuple[_T0, _T1, _T2, _T3]]: ... @overload def with_entities( self, __ent0: _TCCA[_T0], __ent1: _TCCA[_T1], __ent2: _TCCA[_T2], __ent3: _TCCA[_T3], __ent4: _TCCA[_T4], ) -> RowReturningQuery[Tuple[_T0, _T1, _T2, _T3, _T4]]: ... @overload def with_entities( self, __ent0: _TCCA[_T0], __ent1: _TCCA[_T1], __ent2: _TCCA[_T2], __ent3: _TCCA[_T3], __ent4: _TCCA[_T4], __ent5: _TCCA[_T5], ) -> RowReturningQuery[Tuple[_T0, _T1, _T2, _T3, _T4, _T5]]: ... @overload def with_entities( self, __ent0: _TCCA[_T0], __ent1: _TCCA[_T1], __ent2: _TCCA[_T2], __ent3: _TCCA[_T3], __ent4: _TCCA[_T4], __ent5: _TCCA[_T5], __ent6: _TCCA[_T6], ) -> RowReturningQuery[Tuple[_T0, _T1, _T2, _T3, _T4, _T5, _T6]]: ... @overload def with_entities( self, __ent0: _TCCA[_T0], __ent1: _TCCA[_T1], __ent2: _TCCA[_T2], __ent3: _TCCA[_T3], __ent4: _TCCA[_T4], __ent5: _TCCA[_T5], __ent6: _TCCA[_T6], __ent7: _TCCA[_T7], ) -> RowReturningQuery[Tuple[_T0, _T1, _T2, _T3, _T4, _T5, _T6, _T7]]: ... # END OVERLOADED FUNCTIONS self.with_entities @overload def with_entities( self, *entities: _ColumnsClauseArgument[Any] ) -> Query[Any]: ... @_generative def with_entities( self, *entities: _ColumnsClauseArgument[Any], **__kw: Any ) -> Query[Any]: r"""Return a new :class:`_query.Query` replacing the SELECT list with the given entities. e.g.:: # Users, filtered on some arbitrary criterion # and then ordered by related email address q = ( session.query(User) .join(User.address) .filter(User.name.like("%ed%")) .order_by(Address.email) ) # given *only* User.id==5, Address.email, and 'q', what # would the *next* User in the result be ? subq = ( q.with_entities(Address.email) .order_by(None) .filter(User.id == 5) .subquery() ) q = q.join((subq, subq.c.email < Address.email)).limit(1) .. seealso:: :meth:`_sql.Select.with_only_columns` - v2 comparable method. """ if __kw: raise _no_kw() # Query has all the same fields as Select for this operation # this could in theory be based on a protocol but not sure if it's # worth it _MemoizedSelectEntities._generate_for_statement(self) # type: ignore self._set_entities(entities) return self @_generative def add_columns( self, *column: _ColumnExpressionArgument[Any] ) -> Query[Any]: """Add one or more column expressions to the list of result columns to be returned. .. seealso:: :meth:`_sql.Select.add_columns` - v2 comparable method. """ self._raw_columns = list(self._raw_columns) self._raw_columns.extend( coercions.expect( roles.ColumnsClauseRole, c, apply_propagate_attrs=self, post_inspect=True, ) for c in column ) return self @util.deprecated( "1.4", ":meth:`_query.Query.add_column` " "is deprecated and will be removed in a " "future release. Please use :meth:`_query.Query.add_columns`", ) def add_column(self, column: _ColumnExpressionArgument[Any]) -> Query[Any]: """Add a column expression to the list of result columns to be returned. """ return self.add_columns(column) @_generative def options(self, *args: ExecutableOption) -> Self: """Return a new :class:`_query.Query` object, applying the given list of mapper options. Most supplied options regard changing how column- and relationship-mapped attributes are loaded. .. seealso:: :ref:`loading_columns` :ref:`relationship_loader_options` """ opts = tuple(util.flatten_iterator(args)) if self._compile_options._current_path: # opting for lower method overhead for the checks for opt in opts: if not opt._is_core and opt._is_legacy_option: # type: ignore opt.process_query_conditionally(self) # type: ignore else: for opt in opts: if not opt._is_core and opt._is_legacy_option: # type: ignore opt.process_query(self) # type: ignore self._with_options += opts return self def with_transformation( self, fn: Callable[[Query[Any]], Query[Any]] ) -> Query[Any]: """Return a new :class:`_query.Query` object transformed by the given function. E.g.:: def filter_something(criterion): def transform(q): return q.filter(criterion) return transform q = q.with_transformation(filter_something(x == 5)) This allows ad-hoc recipes to be created for :class:`_query.Query` objects. """ return fn(self) def get_execution_options(self) -> _ImmutableExecuteOptions: """Get the non-SQL options which will take effect during execution. .. versionadded:: 1.3 .. seealso:: :meth:`_query.Query.execution_options` :meth:`_sql.Select.get_execution_options` - v2 comparable method. """ return self._execution_options @overload def execution_options( self, *, compiled_cache: Optional[CompiledCacheType] = ..., logging_token: str = ..., isolation_level: IsolationLevel = ..., no_parameters: bool = False, stream_results: bool = False, max_row_buffer: int = ..., yield_per: int = ..., insertmanyvalues_page_size: int = ..., schema_translate_map: Optional[SchemaTranslateMapType] = ..., populate_existing: bool = False, autoflush: bool = False, preserve_rowcount: bool = False, **opt: Any, ) -> Self: ... @overload def execution_options(self, **opt: Any) -> Self: ... @_generative def execution_options(self, **kwargs: Any) -> Self: """Set non-SQL options which take effect during execution. Options allowed here include all of those accepted by :meth:`_engine.Connection.execution_options`, as well as a series of ORM specific options: ``populate_existing=True`` - equivalent to using :meth:`_orm.Query.populate_existing` ``autoflush=True|False`` - equivalent to using :meth:`_orm.Query.autoflush` ``yield_per=<value>`` - equivalent to using :meth:`_orm.Query.yield_per` Note that the ``stream_results`` execution option is enabled automatically if the :meth:`~sqlalchemy.orm.query.Query.yield_per()` method or execution option is used. .. versionadded:: 1.4 - added ORM options to :meth:`_orm.Query.execution_options` The execution options may also be specified on a per execution basis when using :term:`2.0 style` queries via the :paramref:`_orm.Session.execution_options` parameter. .. warning:: The :paramref:`_engine.Connection.execution_options.stream_results` parameter should not be used at the level of individual ORM statement executions, as the :class:`_orm.Session` will not track objects from different schema translate maps within a single session. For multiple schema translate maps within the scope of a single :class:`_orm.Session`, see :ref:`examples_sharding`. .. seealso:: :ref:`engine_stream_results` :meth:`_query.Query.get_execution_options` :meth:`_sql.Select.execution_options` - v2 equivalent method. """ self._execution_options = self._execution_options.union(kwargs) return self @_generative def with_for_update( self, *, nowait: bool = False, read: bool = False, of: Optional[_ForUpdateOfArgument] = None, skip_locked: bool = False, key_share: bool = False, ) -> Self: """return a new :class:`_query.Query` with the specified options for the ``FOR UPDATE`` clause. The behavior of this method is identical to that of :meth:`_expression.GenerativeSelect.with_for_update`. When called with no arguments, the resulting ``SELECT`` statement will have a ``FOR UPDATE`` clause appended. When additional arguments are specified, backend-specific options such as ``FOR UPDATE NOWAIT`` or ``LOCK IN SHARE MODE`` can take effect. E.g.:: q = ( sess.query(User) .populate_existing() .with_for_update(nowait=True, of=User) ) The above query on a PostgreSQL backend will render like: .. sourcecode:: sql SELECT users.id AS users_id FROM users FOR UPDATE OF users NOWAIT .. warning:: Using ``with_for_update`` in the context of eager loading relationships is not officially supported or recommended by SQLAlchemy and may not work with certain queries on various database backends. When ``with_for_update`` is successfully used with a query that involves :func:`_orm.joinedload`, SQLAlchemy will attempt to emit SQL that locks all involved tables. .. note:: It is generally a good idea to combine the use of the :meth:`_orm.Query.populate_existing` method when using the :meth:`_orm.Query.with_for_update` method. The purpose of :meth:`_orm.Query.populate_existing` is to force all the data read from the SELECT to be populated into the ORM objects returned, even if these objects are already in the :term:`identity map`. .. seealso:: :meth:`_expression.GenerativeSelect.with_for_update` - Core level method with full argument and behavioral description. :meth:`_orm.Query.populate_existing` - overwrites attributes of objects already loaded in the identity map. """ # noqa: E501 self._for_update_arg = ForUpdateArg( read=read, nowait=nowait, of=of, skip_locked=skip_locked, key_share=key_share, ) return self @_generative def params( self, __params: Optional[Dict[str, Any]] = None, **kw: Any ) -> Self: r"""Add values for bind parameters which may have been specified in filter(). Parameters may be specified using \**kwargs, or optionally a single dictionary as the first positional argument. The reason for both is that \**kwargs is convenient, however some parameter dictionaries contain unicode keys in which case \**kwargs cannot be used. """ if __params: kw.update(__params) self._params = self._params.union(kw) return self def where(self, *criterion: _ColumnExpressionArgument[bool]) -> Self: """A synonym for :meth:`.Query.filter`. .. versionadded:: 1.4 .. seealso:: :meth:`_sql.Select.where` - v2 equivalent method. """ return self.filter(*criterion) @_generative @_assertions(_no_statement_condition, _no_limit_offset) def filter(self, *criterion: _ColumnExpressionArgument[bool]) -> Self: r"""Apply the given filtering criterion to a copy of this :class:`_query.Query`, using SQL expressions. e.g.:: session.query(MyClass).filter(MyClass.name == "some name") Multiple criteria may be specified as comma separated; the effect is that they will be joined together using the :func:`.and_` function:: session.query(MyClass).filter(MyClass.name == "some name", MyClass.id > 5) The criterion is any SQL expression object applicable to the WHERE clause of a select. String expressions are coerced into SQL expression constructs via the :func:`_expression.text` construct. .. seealso:: :meth:`_query.Query.filter_by` - filter on keyword expressions. :meth:`_sql.Select.where` - v2 equivalent method. """ # noqa: E501 for crit in list(criterion): crit = coercions.expect( roles.WhereHavingRole, crit, apply_propagate_attrs=self ) self._where_criteria += (crit,) return self @util.memoized_property def _last_joined_entity( self, ) -> Optional[Union[_InternalEntityType[Any], _JoinTargetElement]]: if self._setup_joins: return _determine_last_joined_entity( self._setup_joins, ) else: return None def _filter_by_zero(self) -> Any: """for the filter_by() method, return the target entity for which we will attempt to derive an expression from based on string name. """ if self._setup_joins: _last_joined_entity = self._last_joined_entity if _last_joined_entity is not None: return _last_joined_entity # discussion related to #7239 # special check determines if we should try to derive attributes # for filter_by() from the "from object", i.e., if the user # called query.select_from(some selectable).filter_by(some_attr=value). # We don't want to do that in the case that methods like # from_self(), select_entity_from(), or a set op like union() were # called; while these methods also place a # selectable in the _from_obj collection, they also set up # the _set_base_alias boolean which turns on the whole "adapt the # entity to this selectable" thing, meaning the query still continues # to construct itself in terms of the lead entity that was passed # to query(), e.g. query(User).from_self() is still in terms of User, # and not the subquery that from_self() created. This feature of # "implicitly adapt all occurrences of entity X to some arbitrary # subquery" is the main thing I am trying to do away with in 2.0 as # users should now used aliased() for that, but I can't entirely get # rid of it due to query.union() and other set ops relying upon it. # # compare this to the base Select()._filter_by_zero() which can # just return self._from_obj[0] if present, because there is no # "_set_base_alias" feature. # # IOW, this conditional essentially detects if # "select_from(some_selectable)" has been called, as opposed to # "select_entity_from()", "from_self()" # or "union() / some_set_op()". if self._from_obj and not self._compile_options._set_base_alias: return self._from_obj[0] return self._raw_columns[0] def filter_by(self, **kwargs: Any) -> Self: r"""Apply the given filtering criterion to a copy of this :class:`_query.Query`, using keyword expressions. e.g.:: session.query(MyClass).filter_by(name="some name") Multiple criteria may be specified as comma separated; the effect is that they will be joined together using the :func:`.and_` function:: session.query(MyClass).filter_by(name="some name", id=5) The keyword expressions are extracted from the primary entity of the query, or the last entity that was the target of a call to :meth:`_query.Query.join`. .. seealso:: :meth:`_query.Query.filter` - filter on SQL expressions. :meth:`_sql.Select.filter_by` - v2 comparable method. """ from_entity = self._filter_by_zero() clauses = [ _entity_namespace_key(from_entity, key) == value for key, value in kwargs.items() ] return self.filter(*clauses) @_generative def order_by( self, __first: Union[ Literal[None, False, _NoArg.NO_ARG], _ColumnExpressionOrStrLabelArgument[Any], ] = _NoArg.NO_ARG, *clauses: _ColumnExpressionOrStrLabelArgument[Any], ) -> Self: """Apply one or more ORDER BY criteria to the query and return the newly resulting :class:`_query.Query`. e.g.:: q = session.query(Entity).order_by(Entity.id, Entity.name) Calling this method multiple times is equivalent to calling it once with all the clauses concatenated. All existing ORDER BY criteria may be cancelled by passing ``None`` by itself. New ORDER BY criteria may then be added by invoking :meth:`_orm.Query.order_by` again, e.g.:: # will erase all ORDER BY and ORDER BY new_col alone q = q.order_by(None).order_by(new_col) .. seealso:: These sections describe ORDER BY in terms of :term:`2.0 style` invocation but apply to :class:`_orm.Query` as well: :ref:`tutorial_order_by` - in the :ref:`unified_tutorial` :ref:`tutorial_order_by_label` - in the :ref:`unified_tutorial` :meth:`_sql.Select.order_by` - v2 equivalent method. """ for assertion in (self._no_statement_condition, self._no_limit_offset): assertion("order_by") if not clauses and (__first is None or __first is False): self._order_by_clauses = () elif __first is not _NoArg.NO_ARG: criterion = tuple( coercions.expect(roles.OrderByRole, clause) for clause in (__first,) + clauses ) self._order_by_clauses += criterion return self @_generative def group_by( self, __first: Union[ Literal[None, False, _NoArg.NO_ARG], _ColumnExpressionOrStrLabelArgument[Any], ] = _NoArg.NO_ARG, *clauses: _ColumnExpressionOrStrLabelArgument[Any], ) -> Self: """Apply one or more GROUP BY criterion to the query and return the newly resulting :class:`_query.Query`. All existing GROUP BY settings can be suppressed by passing ``None`` - this will suppress any GROUP BY configured on mappers as well. .. seealso:: These sections describe GROUP BY in terms of :term:`2.0 style` invocation but apply to :class:`_orm.Query` as well: :ref:`tutorial_group_by_w_aggregates` - in the :ref:`unified_tutorial` :ref:`tutorial_order_by_label` - in the :ref:`unified_tutorial` :meth:`_sql.Select.group_by` - v2 equivalent method. """ for assertion in (self._no_statement_condition, self._no_limit_offset): assertion("group_by") if not clauses and (__first is None or __first is False): self._group_by_clauses = () elif __first is not _NoArg.NO_ARG: criterion = tuple( coercions.expect(roles.GroupByRole, clause) for clause in (__first,) + clauses ) self._group_by_clauses += criterion return self @_generative @_assertions(_no_statement_condition, _no_limit_offset) def having(self, *having: _ColumnExpressionArgument[bool]) -> Self: r"""Apply a HAVING criterion to the query and return the newly resulting :class:`_query.Query`. :meth:`_query.Query.having` is used in conjunction with :meth:`_query.Query.group_by`. HAVING criterion makes it possible to use filters on aggregate functions like COUNT, SUM, AVG, MAX, and MIN, eg.:: q = ( session.query(User.id) .join(User.addresses) .group_by(User.id) .having(func.count(Address.id) > 2) ) .. seealso:: :meth:`_sql.Select.having` - v2 equivalent method. """ for criterion in having: having_criteria = coercions.expect( roles.WhereHavingRole, criterion ) self._having_criteria += (having_criteria,) return self def _set_op(self, expr_fn: Any, *q: Query[Any]) -> Self: list_of_queries = (self,) + q return self._from_selectable(expr_fn(*(list_of_queries)).subquery()) def union(self, *q: Query[Any]) -> Self: """Produce a UNION of this Query against one or more queries. e.g.:: q1 = sess.query(SomeClass).filter(SomeClass.foo == "bar") q2 = sess.query(SomeClass).filter(SomeClass.bar == "foo") q3 = q1.union(q2) The method accepts multiple Query objects so as to control the level of nesting. A series of ``union()`` calls such as:: x.union(y).union(z).all() will nest on each ``union()``, and produces: .. sourcecode:: sql SELECT * FROM (SELECT * FROM (SELECT * FROM X UNION SELECT * FROM y) UNION SELECT * FROM Z) Whereas:: x.union(y, z).all() produces: .. sourcecode:: sql SELECT * FROM (SELECT * FROM X UNION SELECT * FROM y UNION SELECT * FROM Z) Note that many database backends do not allow ORDER BY to be rendered on a query called within UNION, EXCEPT, etc. To disable all ORDER BY clauses including those configured on mappers, issue ``query.order_by(None)`` - the resulting :class:`_query.Query` object will not render ORDER BY within its SELECT statement. .. seealso:: :meth:`_sql.Select.union` - v2 equivalent method. """ return self._set_op(expression.union, *q) def union_all(self, *q: Query[Any]) -> Self: """Produce a UNION ALL of this Query against one or more queries. Works the same way as :meth:`~sqlalchemy.orm.query.Query.union`. See that method for usage examples. .. seealso:: :meth:`_sql.Select.union_all` - v2 equivalent method. """ return self._set_op(expression.union_all, *q) def intersect(self, *q: Query[Any]) -> Self: """Produce an INTERSECT of this Query against one or more queries. Works the same way as :meth:`~sqlalchemy.orm.query.Query.union`. See that method for usage examples. .. seealso:: :meth:`_sql.Select.intersect` - v2 equivalent method. """ return self._set_op(expression.intersect, *q) def intersect_all(self, *q: Query[Any]) -> Self: """Produce an INTERSECT ALL of this Query against one or more queries. Works the same way as :meth:`~sqlalchemy.orm.query.Query.union`. See that method for usage examples. .. seealso:: :meth:`_sql.Select.intersect_all` - v2 equivalent method. """ return self._set_op(expression.intersect_all, *q) def except_(self, *q: Query[Any]) -> Self: """Produce an EXCEPT of this Query against one or more queries. Works the same way as :meth:`~sqlalchemy.orm.query.Query.union`. See that method for usage examples. .. seealso:: :meth:`_sql.Select.except_` - v2 equivalent method. """ return self._set_op(expression.except_, *q) def except_all(self, *q: Query[Any]) -> Self: """Produce an EXCEPT ALL of this Query against one or more queries. Works the same way as :meth:`~sqlalchemy.orm.query.Query.union`. See that method for usage examples. .. seealso:: :meth:`_sql.Select.except_all` - v2 equivalent method. """ return self._set_op(expression.except_all, *q) @_generative @_assertions(_no_statement_condition, _no_limit_offset) def join( self, target: _JoinTargetArgument, onclause: Optional[_OnClauseArgument] = None, *, isouter: bool = False, full: bool = False, ) -> Self: r"""Create a SQL JOIN against this :class:`_query.Query` object's criterion and apply generatively, returning the newly resulting :class:`_query.Query`. **Simple Relationship Joins** Consider a mapping between two classes ``User`` and ``Address``, with a relationship ``User.addresses`` representing a collection of ``Address`` objects associated with each ``User``. The most common usage of :meth:`_query.Query.join` is to create a JOIN along this relationship, using the ``User.addresses`` attribute as an indicator for how this should occur:: q = session.query(User).join(User.addresses) Where above, the call to :meth:`_query.Query.join` along ``User.addresses`` will result in SQL approximately equivalent to: .. sourcecode:: sql SELECT user.id, user.name FROM user JOIN address ON user.id = address.user_id In the above example we refer to ``User.addresses`` as passed to :meth:`_query.Query.join` as the "on clause", that is, it indicates how the "ON" portion of the JOIN should be constructed. To construct a chain of joins, multiple :meth:`_query.Query.join` calls may be used. The relationship-bound attribute implies both the left and right side of the join at once:: q = ( session.query(User) .join(User.orders) .join(Order.items) .join(Item.keywords) ) .. note:: as seen in the above example, **the order in which each call to the join() method occurs is important**. Query would not, for example, know how to join correctly if we were to specify ``User``, then ``Item``, then ``Order``, in our chain of joins; in such a case, depending on the arguments passed, it may raise an error that it doesn't know how to join, or it may produce invalid SQL in which case the database will raise an error. In correct practice, the :meth:`_query.Query.join` method is invoked in such a way that lines up with how we would want the JOIN clauses in SQL to be rendered, and each call should represent a clear link from what precedes it. **Joins to a Target Entity or Selectable** A second form of :meth:`_query.Query.join` allows any mapped entity or core selectable construct as a target. In this usage, :meth:`_query.Query.join` will attempt to create a JOIN along the natural foreign key relationship between two entities:: q = session.query(User).join(Address) In the above calling form, :meth:`_query.Query.join` is called upon to create the "on clause" automatically for us. This calling form will ultimately raise an error if either there are no foreign keys between the two entities, or if there are multiple foreign key linkages between the target entity and the entity or entities already present on the left side such that creating a join requires more information. Note that when indicating a join to a target without any ON clause, ORM configured relationships are not taken into account. **Joins to a Target with an ON Clause** The third calling form allows both the target entity as well as the ON clause to be passed explicitly. A example that includes a SQL expression as the ON clause is as follows:: q = session.query(User).join(Address, User.id == Address.user_id) The above form may also use a relationship-bound attribute as the ON clause as well:: q = session.query(User).join(Address, User.addresses) The above syntax can be useful for the case where we wish to join to an alias of a particular target entity. If we wanted to join to ``Address`` twice, it could be achieved using two aliases set up using the :func:`~sqlalchemy.orm.aliased` function:: a1 = aliased(Address) a2 = aliased(Address) q = ( session.query(User) .join(a1, User.addresses) .join(a2, User.addresses) .filter(a1.email_address == "ed@foo.com") .filter(a2.email_address == "ed@bar.com") ) The relationship-bound calling form can also specify a target entity using the :meth:`_orm.PropComparator.of_type` method; a query equivalent to the one above would be:: a1 = aliased(Address) a2 = aliased(Address) q = ( session.query(User) .join(User.addresses.of_type(a1)) .join(User.addresses.of_type(a2)) .filter(a1.email_address == "ed@foo.com") .filter(a2.email_address == "ed@bar.com") ) **Augmenting Built-in ON Clauses** As a substitute for providing a full custom ON condition for an existing relationship, the :meth:`_orm.PropComparator.and_` function may be applied to a relationship attribute to augment additional criteria into the ON clause; the additional criteria will be combined with the default criteria using AND:: q = session.query(User).join( User.addresses.and_(Address.email_address != "foo@bar.com") ) .. versionadded:: 1.4 **Joining to Tables and Subqueries** The target of a join may also be any table or SELECT statement, which may be related to a target entity or not. Use the appropriate ``.subquery()`` method in order to make a subquery out of a query:: subq = ( session.query(Address) .filter(Address.email_address == "ed@foo.com") .subquery() ) q = session.query(User).join(subq, User.id == subq.c.user_id) Joining to a subquery in terms of a specific relationship and/or target entity may be achieved by linking the subquery to the entity using :func:`_orm.aliased`:: subq = ( session.query(Address) .filter(Address.email_address == "ed@foo.com") .subquery() ) address_subq = aliased(Address, subq) q = session.query(User).join(User.addresses.of_type(address_subq)) **Controlling what to Join From** In cases where the left side of the current state of :class:`_query.Query` is not in line with what we want to join from, the :meth:`_query.Query.select_from` method may be used:: q = ( session.query(Address) .select_from(User) .join(User.addresses) .filter(User.name == "ed") ) Which will produce SQL similar to: .. sourcecode:: sql SELECT address.* FROM user JOIN address ON user.id=address.user_id WHERE user.name = :name_1 .. seealso:: :meth:`_sql.Select.join` - v2 equivalent method. :param \*props: Incoming arguments for :meth:`_query.Query.join`, the props collection in modern use should be considered to be a one or two argument form, either as a single "target" entity or ORM attribute-bound relationship, or as a target entity plus an "on clause" which may be a SQL expression or ORM attribute-bound relationship. :param isouter=False: If True, the join used will be a left outer join, just as if the :meth:`_query.Query.outerjoin` method were called. :param full=False: render FULL OUTER JOIN; implies ``isouter``. """ join_target = coercions.expect( roles.JoinTargetRole, target, apply_propagate_attrs=self, legacy=True, ) if onclause is not None: onclause_element = coercions.expect( roles.OnClauseRole, onclause, legacy=True ) else: onclause_element = None self._setup_joins += ( ( join_target, onclause_element, None, { "isouter": isouter, "full": full, }, ), ) self.__dict__.pop("_last_joined_entity", None) return self def outerjoin( self, target: _JoinTargetArgument, onclause: Optional[_OnClauseArgument] = None, *, full: bool = False, ) -> Self: """Create a left outer join against this ``Query`` object's criterion and apply generatively, returning the newly resulting ``Query``. Usage is the same as the ``join()`` method. .. seealso:: :meth:`_sql.Select.outerjoin` - v2 equivalent method. """ return self.join(target, onclause=onclause, isouter=True, full=full) @_generative @_assertions(_no_statement_condition) def reset_joinpoint(self) -> Self: """Return a new :class:`.Query`, where the "join point" has been reset back to the base FROM entities of the query. This method is usually used in conjunction with the ``aliased=True`` feature of the :meth:`~.Query.join` method. See the example in :meth:`~.Query.join` for how this is used. """ self._last_joined_entity = None return self @_generative @_assertions(_no_clauseelement_condition) def select_from(self, *from_obj: _FromClauseArgument) -> Self: r"""Set the FROM clause of this :class:`.Query` explicitly. :meth:`.Query.select_from` is often used in conjunction with :meth:`.Query.join` in order to control which entity is selected from on the "left" side of the join. The entity or selectable object here effectively replaces the "left edge" of any calls to :meth:`~.Query.join`, when no joinpoint is otherwise established - usually, the default "join point" is the leftmost entity in the :class:`~.Query` object's list of entities to be selected. A typical example:: q = ( session.query(Address) .select_from(User) .join(User.addresses) .filter(User.name == "ed") ) Which produces SQL equivalent to: .. sourcecode:: sql SELECT address.* FROM user JOIN address ON user.id=address.user_id WHERE user.name = :name_1 :param \*from_obj: collection of one or more entities to apply to the FROM clause. Entities can be mapped classes, :class:`.AliasedClass` objects, :class:`.Mapper` objects as well as core :class:`.FromClause` elements like subqueries. .. seealso:: :meth:`~.Query.join` :meth:`.Query.select_entity_from` :meth:`_sql.Select.select_from` - v2 equivalent method. """ self._set_select_from(from_obj, False) return self def __getitem__(self, item: Any) -> Any: return orm_util._getitem( self, item, ) @_generative @_assertions(_no_statement_condition) def slice( self, start: int, stop: int, ) -> Self: """Computes the "slice" of the :class:`_query.Query` represented by the given indices and returns the resulting :class:`_query.Query`. The start and stop indices behave like the argument to Python's built-in :func:`range` function. This method provides an alternative to using ``LIMIT``/``OFFSET`` to get a slice of the query. For example, :: session.query(User).order_by(User.id).slice(1, 3) renders as .. sourcecode:: sql SELECT users.id AS users_id, users.name AS users_name FROM users ORDER BY users.id LIMIT ? OFFSET ? (2, 1) .. seealso:: :meth:`_query.Query.limit` :meth:`_query.Query.offset` :meth:`_sql.Select.slice` - v2 equivalent method. """ self._limit_clause, self._offset_clause = sql_util._make_slice( self._limit_clause, self._offset_clause, start, stop ) return self @_generative @_assertions(_no_statement_condition) def limit(self, limit: _LimitOffsetType) -> Self: """Apply a ``LIMIT`` to the query and return the newly resulting ``Query``. .. seealso:: :meth:`_sql.Select.limit` - v2 equivalent method. """ self._limit_clause = sql_util._offset_or_limit_clause(limit) return self @_generative @_assertions(_no_statement_condition) def offset(self, offset: _LimitOffsetType) -> Self: """Apply an ``OFFSET`` to the query and return the newly resulting ``Query``. .. seealso:: :meth:`_sql.Select.offset` - v2 equivalent method. """ self._offset_clause = sql_util._offset_or_limit_clause(offset) return self @_generative @_assertions(_no_statement_condition) def distinct(self, *expr: _ColumnExpressionArgument[Any]) -> Self: r"""Apply a ``DISTINCT`` to the query and return the newly resulting ``Query``. .. note:: The ORM-level :meth:`.distinct` call includes logic that will automatically add columns from the ORDER BY of the query to the columns clause of the SELECT statement, to satisfy the common need of the database backend that ORDER BY columns be part of the SELECT list when DISTINCT is used. These columns *are not* added to the list of columns actually fetched by the :class:`_query.Query`, however, so would not affect results. The columns are passed through when using the :attr:`_query.Query.statement` accessor, however. .. deprecated:: 2.0 This logic is deprecated and will be removed in SQLAlchemy 2.0. See :ref:`migration_20_query_distinct` for a description of this use case in 2.0. .. seealso:: :meth:`_sql.Select.distinct` - v2 equivalent method. :param \*expr: optional column expressions. When present, the PostgreSQL dialect will render a ``DISTINCT ON (<expressions>)`` construct. .. deprecated:: 1.4 Using \*expr in other dialects is deprecated and will raise :class:`_exc.CompileError` in a future version. """ if expr: self._distinct = True self._distinct_on = self._distinct_on + tuple( coercions.expect(roles.ByOfRole, e) for e in expr ) else: self._distinct = True return self def all(self) -> List[_T]: """Return the results represented by this :class:`_query.Query` as a list. This results in an execution of the underlying SQL statement. .. warning:: The :class:`_query.Query` object, when asked to return either a sequence or iterator that consists of full ORM-mapped entities, will **deduplicate entries based on primary key**. See the FAQ for more details. .. seealso:: :ref:`faq_query_deduplicating` .. seealso:: :meth:`_engine.Result.all` - v2 comparable method. :meth:`_engine.Result.scalars` - v2 comparable method. """ return self._iter().all() # type: ignore @_generative @_assertions(_no_clauseelement_condition) def from_statement(self, statement: ExecutableReturnsRows) -> Self: """Execute the given SELECT statement and return results. This method bypasses all internal statement compilation, and the statement is executed without modification. The statement is typically either a :func:`_expression.text` or :func:`_expression.select` construct, and should return the set of columns appropriate to the entity class represented by this :class:`_query.Query`. .. seealso:: :meth:`_sql.Select.from_statement` - v2 comparable method. """ statement = coercions.expect( roles.SelectStatementRole, statement, apply_propagate_attrs=self ) self._statement = statement return self def first(self) -> Optional[_T]: """Return the first result of this ``Query`` or None if the result doesn't contain any row. first() applies a limit of one within the generated SQL, so that only one primary entity row is generated on the server side (note this may consist of multiple result rows if join-loaded collections are present). Calling :meth:`_query.Query.first` results in an execution of the underlying query. .. seealso:: :meth:`_query.Query.one` :meth:`_query.Query.one_or_none` :meth:`_engine.Result.first` - v2 comparable method. :meth:`_engine.Result.scalars` - v2 comparable method. """ # replicates limit(1) behavior if self._statement is not None: return self._iter().first() # type: ignore else: return self.limit(1)._iter().first() # type: ignore def one_or_none(self) -> Optional[_T]: """Return at most one result or raise an exception. Returns ``None`` if the query selects no rows. Raises ``sqlalchemy.orm.exc.MultipleResultsFound`` if multiple object identities are returned, or if multiple rows are returned for a query that returns only scalar values as opposed to full identity-mapped entities. Calling :meth:`_query.Query.one_or_none` results in an execution of the underlying query. .. seealso:: :meth:`_query.Query.first` :meth:`_query.Query.one` :meth:`_engine.Result.one_or_none` - v2 comparable method. :meth:`_engine.Result.scalar_one_or_none` - v2 comparable method. """ return self._iter().one_or_none() # type: ignore def one(self) -> _T: """Return exactly one result or raise an exception. Raises :class:`_exc.NoResultFound` if the query selects no rows. Raises :class:`_exc.MultipleResultsFound` if multiple object identities are returned, or if multiple rows are returned for a query that returns only scalar values as opposed to full identity-mapped entities. Calling :meth:`.one` results in an execution of the underlying query. .. seealso:: :meth:`_query.Query.first` :meth:`_query.Query.one_or_none` :meth:`_engine.Result.one` - v2 comparable method. :meth:`_engine.Result.scalar_one` - v2 comparable method. """ return self._iter().one() # type: ignore def scalar(self) -> Any: """Return the first element of the first result or None if no rows present. If multiple rows are returned, raises :class:`_exc.MultipleResultsFound`. >>> session.query(Item).scalar() <Item> >>> session.query(Item.id).scalar() 1 >>> session.query(Item.id).filter(Item.id < 0).scalar() None >>> session.query(Item.id, Item.name).scalar() 1 >>> session.query(func.count(Parent.id)).scalar() 20 This results in an execution of the underlying query. .. seealso:: :meth:`_engine.Result.scalar` - v2 comparable method. """ # TODO: not sure why we can't use result.scalar() here try: ret = self.one() if not isinstance(ret, collections_abc.Sequence): return ret return ret[0] except sa_exc.NoResultFound: return None def __iter__(self) -> Iterator[_T]: result = self._iter() try: yield from result # type: ignore except GeneratorExit: # issue #8710 - direct iteration is not re-usable after # an iterable block is broken, so close the result result._soft_close() raise def _iter(self) -> Union[ScalarResult[_T], Result[_T]]: # new style execution. params = self._params statement = self._statement_20() result: Union[ScalarResult[_T], Result[_T]] = self.session.execute( statement, params, execution_options={"_sa_orm_load_options": self.load_options}, ) # legacy: automatically set scalars, unique if result._attributes.get("is_single_entity", False): result = cast("Result[_T]", result).scalars() if ( result._attributes.get("filtered", False) and not self.load_options._yield_per ): result = result.unique() return result def __str__(self) -> str: statement = self._statement_20() try: bind = ( self._get_bind_args(statement, self.session.get_bind) if self.session else None ) except sa_exc.UnboundExecutionError: bind = None return str(statement.compile(bind)) def _get_bind_args(self, statement: Any, fn: Any, **kw: Any) -> Any: return fn(clause=statement, **kw) @property def column_descriptions(self) -> List[ORMColumnDescription]: """Return metadata about the columns which would be returned by this :class:`_query.Query`. Format is a list of dictionaries:: user_alias = aliased(User, name="user2") q = sess.query(User, User.id, user_alias) # this expression: q.column_descriptions # would return: [ { "name": "User", "type": User, "aliased": False, "expr": User, "entity": User, }, { "name": "id", "type": Integer(), "aliased": False, "expr": User.id, "entity": User, }, { "name": "user2", "type": User, "aliased": True, "expr": user_alias, "entity": user_alias, }, ] .. seealso:: This API is available using :term:`2.0 style` queries as well, documented at: * :ref:`queryguide_inspection` * :attr:`.Select.column_descriptions` """ return _column_descriptions(self, legacy=True) @util.deprecated( "2.0", "The :meth:`_orm.Query.instances` method is deprecated and will " "be removed in a future release. " "Use the Select.from_statement() method or aliased() construct in " "conjunction with Session.execute() instead.", ) def instances( self, result_proxy: CursorResult[Any], context: Optional[QueryContext] = None, ) -> Any: """Return an ORM result given a :class:`_engine.CursorResult` and :class:`.QueryContext`. """ if context is None: util.warn_deprecated( "Using the Query.instances() method without a context " "is deprecated and will be disallowed in a future release. " "Please make use of :meth:`_query.Query.from_statement` " "for linking ORM results to arbitrary select constructs.", version="1.4", ) compile_state = self._compile_state(for_statement=False) context = QueryContext( compile_state, compile_state.statement, compile_state.statement, self._params, self.session, self.load_options, ) result = loading.instances(result_proxy, context) # legacy: automatically set scalars, unique if result._attributes.get("is_single_entity", False): result = result.scalars() # type: ignore if result._attributes.get("filtered", False): result = result.unique() # TODO: isn't this supposed to be a list? return result @util.became_legacy_20( ":meth:`_orm.Query.merge_result`", alternative="The method is superseded by the " ":func:`_orm.merge_frozen_result` function.", enable_warnings=False, # warnings occur via loading.merge_result ) def merge_result( self, iterator: Union[ FrozenResult[Any], Iterable[Sequence[Any]], Iterable[object] ], load: bool = True, ) -> Union[FrozenResult[Any], Iterable[Any]]: """Merge a result into this :class:`_query.Query` object's Session. Given an iterator returned by a :class:`_query.Query` of the same structure as this one, return an identical iterator of results, with all mapped instances merged into the session using :meth:`.Session.merge`. This is an optimized method which will merge all mapped instances, preserving the structure of the result rows and unmapped columns with less method overhead than that of calling :meth:`.Session.merge` explicitly for each value. The structure of the results is determined based on the column list of this :class:`_query.Query` - if these do not correspond, unchecked errors will occur. The 'load' argument is the same as that of :meth:`.Session.merge`. For an example of how :meth:`_query.Query.merge_result` is used, see the source code for the example :ref:`examples_caching`, where :meth:`_query.Query.merge_result` is used to efficiently restore state from a cache back into a target :class:`.Session`. """ return loading.merge_result(self, iterator, load) def exists(self) -> Exists: """A convenience method that turns a query into an EXISTS subquery of the form EXISTS (SELECT 1 FROM ... WHERE ...). e.g.:: q = session.query(User).filter(User.name == "fred") session.query(q.exists()) Producing SQL similar to: .. sourcecode:: sql SELECT EXISTS ( SELECT 1 FROM users WHERE users.name = :name_1 ) AS anon_1 The EXISTS construct is usually used in the WHERE clause:: session.query(User.id).filter(q.exists()).scalar() Note that some databases such as SQL Server don't allow an EXISTS expression to be present in the columns clause of a SELECT. To select a simple boolean value based on the exists as a WHERE, use :func:`.literal`:: from sqlalchemy import literal session.query(literal(True)).filter(q.exists()).scalar() .. seealso:: :meth:`_sql.Select.exists` - v2 comparable method. """ # .add_columns() for the case that we are a query().select_from(X), # so that ".statement" can be produced (#2995) but also without # omitting the FROM clause from a query(X) (#2818); # .with_only_columns() after we have a core select() so that # we get just "SELECT 1" without any entities. inner = ( self.enable_eagerloads(False) .add_columns(sql.literal_column("1")) .set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL) ._get_select_statement_only() .with_only_columns(1) ) ezero = self._entity_from_pre_ent_zero() if ezero is not None: inner = inner.select_from(ezero) return sql.exists(inner) def count(self) -> int: r"""Return a count of rows this the SQL formed by this :class:`Query` would return. This generates the SQL for this Query as follows: .. sourcecode:: sql SELECT count(1) AS count_1 FROM ( SELECT <rest of query follows...> ) AS anon_1 The above SQL returns a single row, which is the aggregate value of the count function; the :meth:`_query.Query.count` method then returns that single integer value. .. warning:: It is important to note that the value returned by count() is **not the same as the number of ORM objects that this Query would return from a method such as the .all() method**. The :class:`_query.Query` object, when asked to return full entities, will **deduplicate entries based on primary key**, meaning if the same primary key value would appear in the results more than once, only one object of that primary key would be present. This does not apply to a query that is against individual columns. .. seealso:: :ref:`faq_query_deduplicating` For fine grained control over specific columns to count, to skip the usage of a subquery or otherwise control of the FROM clause, or to use other aggregate functions, use :attr:`~sqlalchemy.sql.expression.func` expressions in conjunction with :meth:`~.Session.query`, i.e.:: from sqlalchemy import func # count User records, without # using a subquery. session.query(func.count(User.id)) # return count of user "id" grouped # by "name" session.query(func.count(User.id)).group_by(User.name) from sqlalchemy import distinct # count distinct "name" values session.query(func.count(distinct(User.name))) .. seealso:: :ref:`migration_20_query_usage` """ col = sql.func.count(sql.literal_column("*")) return ( # type: ignore self._legacy_from_self(col).enable_eagerloads(False).scalar() ) def delete( self, synchronize_session: SynchronizeSessionArgument = "auto", delete_args: Optional[Dict[Any, Any]] = None, ) -> int: r"""Perform a DELETE with an arbitrary WHERE clause. Deletes rows matched by this query from the database. E.g.:: sess.query(User).filter(User.age == 25).delete(synchronize_session=False) sess.query(User).filter(User.age == 25).delete( synchronize_session="evaluate" ) .. warning:: See the section :ref:`orm_expression_update_delete` for important caveats and warnings, including limitations when using bulk UPDATE and DELETE with mapper inheritance configurations. :param synchronize_session: chooses the strategy to update the attributes on objects in the session. See the section :ref:`orm_expression_update_delete` for a discussion of these strategies. :param delete_args: Optional dictionary, if present will be passed to the underlying :func:`_expression.delete` construct as the ``**kw`` for the object. May be used to pass dialect-specific arguments such as ``mysql_limit``. .. versionadded:: 2.0.37 :return: the count of rows matched as returned by the database's "row count" feature. .. seealso:: :ref:`orm_expression_update_delete` """ # noqa: E501 bulk_del = BulkDelete(self, delete_args) if self.dispatch.before_compile_delete: for fn in self.dispatch.before_compile_delete: new_query = fn(bulk_del.query, bulk_del) if new_query is not None: bulk_del.query = new_query self = bulk_del.query delete_ = sql.delete(*self._raw_columns) # type: ignore if delete_args: delete_ = delete_.with_dialect_options(**delete_args) delete_._where_criteria = self._where_criteria result: CursorResult[Any] = self.session.execute( delete_, self._params, execution_options=self._execution_options.union( {"synchronize_session": synchronize_session} ), ) bulk_del.result = result # type: ignore self.session.dispatch.after_bulk_delete(bulk_del) result.close() return result.rowcount def update( self, values: Dict[_DMLColumnArgument, Any], synchronize_session: SynchronizeSessionArgument = "auto", update_args: Optional[Dict[Any, Any]] = None, ) -> int: r"""Perform an UPDATE with an arbitrary WHERE clause. Updates rows matched by this query in the database. E.g.:: sess.query(User).filter(User.age == 25).update( {User.age: User.age - 10}, synchronize_session=False ) sess.query(User).filter(User.age == 25).update( {"age": User.age - 10}, synchronize_session="evaluate" ) .. warning:: See the section :ref:`orm_expression_update_delete` for important caveats and warnings, including limitations when using arbitrary UPDATE and DELETE with mapper inheritance configurations. :param values: a dictionary with attributes names, or alternatively mapped attributes or SQL expressions, as keys, and literal values or sql expressions as values. If :ref:`parameter-ordered mode <tutorial_parameter_ordered_updates>` is desired, the values can be passed as a list of 2-tuples; this requires that the :paramref:`~sqlalchemy.sql.expression.update.preserve_parameter_order` flag is passed to the :paramref:`.Query.update.update_args` dictionary as well. :param synchronize_session: chooses the strategy to update the attributes on objects in the session. See the section :ref:`orm_expression_update_delete` for a discussion of these strategies. :param update_args: Optional dictionary, if present will be passed to the underlying :func:`_expression.update` construct as the ``**kw`` for the object. May be used to pass dialect-specific arguments such as ``mysql_limit``, as well as other special arguments such as :paramref:`~sqlalchemy.sql.expression.update.preserve_parameter_order`. :return: the count of rows matched as returned by the database's "row count" feature. .. seealso:: :ref:`orm_expression_update_delete` """ update_args = update_args or {} bulk_ud = BulkUpdate(self, values, update_args) if self.dispatch.before_compile_update: for fn in self.dispatch.before_compile_update: new_query = fn(bulk_ud.query, bulk_ud) if new_query is not None: bulk_ud.query = new_query self = bulk_ud.query upd = sql.update(*self._raw_columns) # type: ignore ppo = update_args.pop("preserve_parameter_order", False) if ppo: upd = upd.ordered_values(*values) # type: ignore else: upd = upd.values(values) if update_args: upd = upd.with_dialect_options(**update_args) upd._where_criteria = self._where_criteria result: CursorResult[Any] = self.session.execute( upd, self._params, execution_options=self._execution_options.union( {"synchronize_session": synchronize_session} ), ) bulk_ud.result = result # type: ignore self.session.dispatch.after_bulk_update(bulk_ud) result.close() return result.rowcount def _compile_state( self, for_statement: bool = False, **kw: Any ) -> ORMCompileState: """Create an out-of-compiler ORMCompileState object. The ORMCompileState object is normally created directly as a result of the SQLCompiler.process() method being handed a Select() or FromStatement() object that uses the "orm" plugin. This method provides a means of creating this ORMCompileState object directly without using the compiler. This method is used only for deprecated cases, which include the .from_self() method for a Query that has multiple levels of .from_self() in use, as well as the instances() method. It is also used within the test suite to generate ORMCompileState objects for test purposes. """ stmt = self._statement_20(for_statement=for_statement, **kw) assert for_statement == stmt._compile_options._for_statement # this chooses between ORMFromStatementCompileState and # ORMSelectCompileState. We could also base this on # query._statement is not None as we have the ORM Query here # however this is the more general path. compile_state_cls = cast( ORMCompileState, ORMCompileState._get_plugin_class_for_plugin(stmt, "orm"), ) return compile_state_cls._create_orm_context( stmt, toplevel=True, compiler=None ) def _compile_context(self, for_statement: bool = False) -> QueryContext: compile_state = self._compile_state(for_statement=for_statement) context = QueryContext( compile_state, compile_state.statement, compile_state.statement, self._params, self.session, self.load_options, ) return context class AliasOption(interfaces.LoaderOption): inherit_cache = False @util.deprecated( "1.4", "The :class:`.AliasOption` object is not necessary " "for entities to be matched up to a query that is established " "via :meth:`.Query.from_statement` and now does nothing.", ) def __init__(self, alias: Union[Alias, Subquery]): r"""Return a :class:`.MapperOption` that will indicate to the :class:`_query.Query` that the main table has been aliased. """ def process_compile_state(self, compile_state: ORMCompileState) -> None: pass class BulkUD: """State used for the orm.Query version of update() / delete(). This object is now specific to Query only. """ def __init__(self, query: Query[Any]): self.query = query.enable_eagerloads(False) self._validate_query_state() self.mapper = self.query._entity_from_pre_ent_zero() def _validate_query_state(self) -> None: for attr, methname, notset, op in ( ("_limit_clause", "limit()", None, operator.is_), ("_offset_clause", "offset()", None, operator.is_), ("_order_by_clauses", "order_by()", (), operator.eq), ("_group_by_clauses", "group_by()", (), operator.eq), ("_distinct", "distinct()", False, operator.is_), ( "_from_obj", "join(), outerjoin(), select_from(), or from_self()", (), operator.eq, ), ( "_setup_joins", "join(), outerjoin(), select_from(), or from_self()", (), operator.eq, ), ): if not op(getattr(self.query, attr), notset): raise sa_exc.InvalidRequestError( "Can't call Query.update() or Query.delete() " "when %s has been called" % (methname,) ) @property def session(self) -> Session: return self.query.session class BulkUpdate(BulkUD): """BulkUD which handles UPDATEs.""" def __init__( self, query: Query[Any], values: Dict[_DMLColumnArgument, Any], update_kwargs: Optional[Dict[Any, Any]], ): super().__init__(query) self.values = values self.update_kwargs = update_kwargs class BulkDelete(BulkUD): """BulkUD which handles DELETEs.""" def __init__( self, query: Query[Any], delete_kwargs: Optional[Dict[Any, Any]], ): super().__init__(query) self.delete_kwargs = delete_kwargs class RowReturningQuery(Query[Row[_TP]]): if TYPE_CHECKING: def tuples(self) -> Query[_TP]: # type: ignore ... sqlalchemy/orm/__pycache__/instrumentation.cpython-39.pyc 0000644 00000053267 15125143220 0017617 0 ustar 00 a ��Jh_ � @ s� d Z ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z dd lm Z dd lm Z dd lm Z dd lm Z dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlZddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddl m Z dd lm Z dd l m Z dd l m!Z! dd l"m#Z# dd l"m$Z$ e�r�dd!lm%Z% dd"l m&Z& dd#l m'Z' dd$lm(Z( dd%lm)Z) dd&l*m+Z+ dd'l,m-Z- dd(l.m/Z/ dd)lm0Z0 dd*l m1Z1 ed+ed,�Z2e �3d-�Z4G d.d/� d/e$�Z5G d0d1� d1e$�Z6G d2d3� d3e!ee7d4f e e e �Z8G d5d6� d6�Z9G d7d8� d8e �Z:e:� Z;ej< Z<Z=ej> Z>Z?ej@ Z@ZAejB ZBZCdKd:d;d<d=d>d?d@dAdB�dCdD�ZDdEdF� ZEdGdH� ZFdIdJ� ZGdS )La� Defines SQLAlchemy's system of class instrumentation. This module is usually not directly visible to user applications, but defines a large part of the ORM's interactivity. instrumentation.py deals with registration of end-user classes for state tracking. It interacts closely with state.py and attributes.py which establish per-instance and per-class-attribute instrumentation, respectively. The class instrumentation system can be customized on a per-class or global basis using the :mod:`sqlalchemy.ext.instrumentation` module, which provides the means to build and specify alternate instrumentation forms. .. versionchanged: 0.8 The instrumentation extension system was moved out of the ORM and into the external :mod:`sqlalchemy.ext.instrumentation` package. When that package is imported, it installs itself within sqlalchemy.orm so that its more comprehensive resolution mechanics take effect. � )� annotations)�Any)�Callable)�cast)� Collection)�Dict)�Generic)�Iterable)�List)�Optional)�Set)�Tuple)�Type)� TYPE_CHECKING)�TypeVar)�UnionN� )�base)� collections)�exc)� interfaces)�state)�_O)� _is_collection_attribute_impl� )�util)� EventTarget)� HasMemoized)�Literal)�Protocol)� _RegistryType)� AttributeImpl)�QueryableAttribute)�_AdaptedCollectionProtocol)�_CollectionFactoryType)� _MapperConfig)�InstanceEvents)�Mapper)� InstanceState)� dispatcher�_T)�bound�DEL_ATTRc @ s e Zd Zddddd�dd�ZdS ) � _ExpiredAttributeLoaderProto�state.InstanceState[Any]zSet[str]zbase.PassiveFlag�None)r �toload�passive�returnc C s d S �N� )�selfr r0 r1 r4 r4 �S/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/instrumentation.py�__call__S s z%_ExpiredAttributeLoaderProto.__call__N��__name__� __module__� __qualname__r7 r4 r4 r4 r6 r- R s r- c @ s e Zd Zddd�dd�ZdS )�_ManagerFactory�Type[_O]�ClassManager[_O]��class_r2 c C s d S r3 r4 �r5 r@ r4 r4 r6 r7 \ � z_ManagerFactory.__call__Nr8 r4 r4 r4 r6 r< [ s r< c @ sb e Zd ZU dZded< ejZejZ e e � e ��Z ded< ded< dZded < d ed < dZd ed < ded< espdZded< ded< ee jddd�dd� ��Zeje jddd�dd� ��Zdd� Zd�d d d d d!dd"d#�d$d%�Zd"d&�d'd(�Zd)d&�d*d+�Zd,d d-�d.d/�Zed d&�d0d1��Ze j d2d3� �Z e j d4d5� �Z e j d6d7� �Z e j d8d9� �Z!e j"d:d&�d;d<��Z#d�d=d>�Z$d�d?d@�Z%dAd dB�dCdD�Z&dEdFdG�dHdI�Z'dJdK� Z(e j"dLd&�dMdN��Z)dOdP� Z*e j+dQdR� �Z,e j+dSdT� �Z-e j+dUdV� �Z.d�dAdWd d"dX�dYdZ�Z/d[d\� Z0d]d^� Z1d�d_d`�Z2d"d&�dadb�Z3dAdWd"dc�ddde�Z4dAd"dB�dfdg�Z5dAd,d"dh�didj�Z6dAd"dB�dkdl�Z7dAdmdndo�dpdq�Z8dAdrdndsdt�dudv�Z9d�dAd d dw�dxdy�Z:dAdzdB�d{d|�Z;ed}d&�d~d��Z<d�d�d�d��d�d��Z=d�d�d�d"d��d�d��Z>d�d"d��d�d��Z?drd�d�d��d�d��Z@d�d�d��d�d��ZAd�d d��d�d��ZBd�drdAd d d��d�d��ZCd d&�d�d��ZDdAd&�d�d��ZEdS )�� ClassManagerz,Tracks state information at the class level.z dispatcher[ClassManager[_O]]�dispatchr- �expired_attribute_loader� Optional[Callable[..., None]]� init_methodN� original_initzOptional[_ManagerFactory]�factoryz$Optional[weakref.ref[_MapperConfig]]�declarative_scanr �registryr= r@ zList[ClassManager[Any]]�_basesz1.4zWThe ClassManager.deferred_scalar_loader attribute is now named expired_attribute_loader)�messagec C s | j S r3 �rE �r5 r4 r4 r6 �deferred_scalar_loader� s z#ClassManager.deferred_scalar_loaderc C s || _ d S r3 rN )r5 �objr4 r4 r6 rP � s c C s� || _ i | _d | _i | _i | _d| _d | _d | _dd� tddd� | j j D ��D �| _ | j D ]}| � |� qZtd| j j ��|| � |jD ]"}t|�}|d ur�| j �|j � q�| �� d|jv r�t�d| � d S ) NFc S s g | ]}|d ur|�qS r3 r4 )�.0�mgrr4 r4 r6 � <listcomp>� s �z)ClassManager.__init__.<locals>.<listcomp>z!List[Optional[ClassManager[Any]]]c S s g | ]}t |t�rt|��qS r4 )� isinstance�type�opt_manager_of_class)rR r r4 r4 r6 rT � s �r& �__del__z�__del__() method on class %s will cause unreachable cycles and memory leaks, as SQLAlchemy instrumentation often creates reference cycles. Please remove this method.)r@ �info�new_init� local_attrs� originals� _finalizedrI rG r � __bases__rL �updaterD Z_eventsZ_new_classmanager_instance�__mro__rW �_update�manage�__dict__r �warn)r5 r@ Zbase_ZbaseclsrS r4 r4 r6 �__init__� sD ��� �� ��zClassManager.__init__F�bool�Optional[Mapper[_O]]�Optional[_RegistryType]�Optional[_MapperConfig]�&Optional[_ExpiredAttributeLoaderProto]r/ )�finalize�mapperrK rJ rE rG r2 c C s� |r || _ |r|�| � |r(t�|�| _|r2|| _|rN| jrHJ d| ��|| _| js|| jd urr| jj t j u rr| jn| jj | _ |r�| js�| � � d S )Nz>class is already instrumented, init_method %s can't be applied) rl Z _add_manager�weakref�refrJ rE r] rG r@ re �objectrH � _finalize)r5 rk rl rK rJ rE rG r4 r4 r6 � _update_state� s0 ��� �� zClassManager._update_state)r2 c C s* | j r d S d| _ | �� tj�| j� d S �NT)r] �_instrument_init�_instrumentation_factoryrD Zclass_instrumentr@ rO r4 r4 r6 rp � s zClassManager._finalize�intc C s t | �S r3 )�idrO r4 r4 r6 �__hash__� s zClassManager.__hash__r )�otherr2 c C s || u S r3 r4 )r5 rx r4 r4 r6 �__eq__� s zClassManager.__eq__c C s d| j v S )Nrl )rc rO r4 r4 r6 � is_mapped� s zClassManager.is_mappedc C s t | �S r3 )� frozensetrO r4 r4 r6 � _all_key_set� s zClassManager._all_key_setc C s t dd� | �� D ��S )Nc S s g | ]}|j jr|j�qS r4 )�implZ collection�key�rR �attrr4 r4 r6 rT rB z6ClassManager._collection_impl_keys.<locals>.<listcomp>�r{ �valuesrO r4 r4 r6 �_collection_impl_keys� s �z"ClassManager._collection_impl_keysc C s t dd� | �� D ��S )Nc S s g | ]}|j jr|j �qS r4 )r} Zaccepts_scalar_loaderr r4 r4 r6 rT s �z5ClassManager._scalar_loader_impls.<locals>.<listcomp>r� rO r4 r4 r6 �_scalar_loader_impls s ��z!ClassManager._scalar_loader_implsc C s t dd� | �� D ��S )Nc S s g | ] }|j �qS r4 �r} r r4 r4 r6 rT rB z.ClassManager._loader_impls.<locals>.<listcomp>r� rO r4 r4 r6 � _loader_impls s zClassManager._loader_implsz Mapper[_O]c C s t �| j��d S r3 )r ZUnmappedClassErrorr@ rO r4 r4 r6 rl s zClassManager.mapperc c sv i }| j jdd� D ]\}|jd }|jD ]F}|�||� ||jv rDq(|| j| }t|tj�r(|jr(||fV q(qdS )a return an iterator of all classbound attributes that are implement :class:`.InspectionAttr`. This includes :class:`.QueryableAttribute` as well as extension types such as :class:`.hybrid_property` and :class:`.AssociationProxy`. r ���r N)r@ r` rc � setdefaultrU r ZInspectionAttrZ is_attribute)r5 �exclude�found�superclsZinheritsr~ �valr4 r4 r6 �_all_sqla_attributes s ��z!ClassManager._all_sqla_attributesc C s* | j jD ] }||jv r|j| S q|S )z5return an attribute on the class without tripping it.N)r@ r` rc )r5 r~ �defaultr� r4 r4 r6 �_get_class_attr_mro8 s z ClassManager._get_class_attr_mro�str)r~ r2 c C s || v o| | j duS )z\Return True if the given attribute is fully initialized. i.e. has an impl. Nr� �r5 r~ r4 r4 r6 �_attr_has_implA s zClassManager._attr_has_implzType[_T]zClassManager[_T])�clsr2 c C s t |dd�S )a� Create a new ClassManager for a subclass of this ClassManager's class. This is called automatically when attributes are instrumented so that the attributes can be propagated to subclasses against their own class-local manager, without the need for mappers etc. to have already pre-configured managers for the full class hierarchy. Mappers can post-configure the auto-generated ClassManager when needed. F)rk )�register_class)r5 r� r4 r4 r6 �_subclass_managerI s z ClassManager._subclass_managerc C s$ t | j| | j�| _| �d| j� d S )Nre )�_generate_initr@ rH rZ �install_memberrO r4 r4 r6 rs V s z ClassManager._instrument_initz Type[state.InstanceState[_O]]c C s | j �| | j� tjS r3 )rD Z first_initr@ r r( rO r4 r4 r6 �_state_constructorZ s z ClassManager._state_constructorc C s t | j| j| � dS )z0Mark this instance as the manager for its class.N)�setattrr@ � MANAGER_ATTRrO r4 r4 r6 rb _ s zClassManager.managec C s t S r3 )�_default_manager_getterrO r4 r4 r6 �manager_getterd s zClassManager.manager_getterc C s t S )z�Return a (instance) -> InstanceState callable. "state getter" callables should raise either KeyError or AttributeError if no InstanceState could be found for the instance. )�_default_state_getterrO r4 r4 r6 � state_getterh s zClassManager.state_getterc C s t S r3 )�_default_dict_getterrO r4 r4 r6 � dict_getters s zClassManager.dict_getter�QueryableAttribute[Any])r~ �inst� propagatedr2 c C sf |r|| j v r*d S n|| j |< | �||� | �� || |< | j�� D ] }| �|�}|�||d� qDd S rr )r[ �install_descriptor�_reset_memoizationsr@ �__subclasses__r� �instrument_attribute)r5 r~ r� r� r� �managerr4 r4 r6 r� w s z!ClassManager.instrument_attributec c sF | j �� D ]6}t|�}|d ur || ur |V |r |�d�E d H q d S rr )r@ r� rW �subclass_managers)r5 � recursiver� rS r4 r4 r6 r� � s z ClassManager.subclass_managersc C s t j�| j|| | � d S r3 )rt rD Zattribute_instrumentr@ r� r4 r4 r6 �post_configure_attribute� s �z%ClassManager.post_configure_attributec C sl || vr d S |r || j v r2d S n| j |= | �|� | �� | |= | j�� D ] }t|�}|rJ|�|d� qJd S rr )r[ �uninstall_descriptorr� r@ r� rW �uninstrument_attribute)r5 r~ r� r� r� r4 r4 r6 r� � s z#ClassManager.uninstrument_attributec C sx t | j�D ]}| �|� q d| _d| _d| _| j�� t | �D ]}|| jv r>| � |� q>| j | j j v rtt | j | j � dS )z<remove all instrumentation established by this ClassManager.N)�listr\ �uninstall_memberrl rD rZ rY �clearr[ r� r� r@ rc �delattrr� r4 r4 r6 � unregister� s zClassManager.unregister)r~ r� r2 c C s. || j | jfv r td| ��t| j||� d S �NzW%r: requested attribute name conflicts with instrumentation attribute of the same name.)� STATE_ATTRr� �KeyErrorr� r@ )r5 r~ r� r4 r4 r6 r� � s ��z ClassManager.install_descriptorc C s t | j|� d S r3 )r� r@ r� r4 r4 r6 r� � s z!ClassManager.uninstall_descriptor)r~ �implementationr2 c C sH || j | jfv r td| ��| j�|| jj�|t�� t | j||� d S r� ) r� r� r� r\ r� r@ rc �getr, r� )r5 r~ r� r4 r4 r6 r� � s ��zClassManager.install_memberc C s6 | j �|d �}|tur&t| j||� n t| j|� d S r3 )r\ �popr, r� r@ r� )r5 r~ �originalr4 r4 r6 r� � s z ClassManager.uninstall_memberzType[Collection[Any]]r$ )r~ �collection_classr2 c C s t �|�S r3 )r Zprepare_instrumentation)r5 r~ r� r4 r4 r6 �instrument_collection_class� s z(ClassManager.instrument_collection_classzInstanceState[_O]z@Tuple[collections.CollectionAdapter, _AdaptedCollectionProtocol])r~ r rI r2 c C s2 |� }| � |�}t|�s J �t�|||�}||fS r3 )�get_implr r ZCollectionAdapter)r5 r~ r rI � user_datar} �adapterr4 r4 r6 �initialize_collection� s z"ClassManager.initialize_collection)r~ �searchr2 c C s |r || v S || j v S d S r3 )r[ )r5 r~ r� r4 r4 r6 �is_instrumented� s z ClassManager.is_instrumentedr! c C s | | j S r3 r� r� r4 r4 r6 r� � s zClassManager.get_implz Iterable[Any]c C s t | �� �S r3 )�iterr� rO r4 r4 r6 � attributes� s zClassManager.attributeszOptional[InstanceState[_O]]r )r r2 c C s2 | j �| j �}|d u r"| �|| �}| �||� |S r3 )r@ �__new__r� � _state_setter)r5 r �instancer4 r4 r6 � new_instance� s zClassManager.new_instance)r� r r2 c C s$ |d u r| � || �}| �||� d S r3 )r� r� �r5 r� r r4 r4 r6 �setup_instance s zClassManager.setup_instance)r� r2 c C s t || j� d S r3 )r� r� �r5 r� r4 r4 r6 �teardown_instance s z ClassManager.teardown_instance�Dict[str, Any]�_SerializeManager)r � state_dictr2 c C s t ||�S r3 )r� )r5 r r� r4 r4 r6 � _serialize s zClassManager._serializez(Union[Literal[False], InstanceState[_O]]c C sT t || j�rdS | j|jur4| jr4| �|j��|�S | �|| �}| �||� |S dS )z�Install a default InstanceState if none is present. A private convenience method used by the __init__ decorator. FN) �hasattrr� r@ � __class__rz r� �_new_state_if_noner� r� r� r4 r4 r6 r� s �� z ClassManager._new_state_if_nonec C s t || j�S r3 )r� r� r� r4 r4 r6 � has_state( s zClassManager.has_state)r r~ � optimisticr2 c C s | � |�j||d�S )ZTODO)r� )r� Z hasparent)r5 r r~ r� r4 r4 r6 � has_parent+ s zClassManager.has_parentc C s dS )z=All ClassManagers are non-zero regardless of attribute state.Tr4 rO r4 r4 r6 �__bool__1 s zClassManager.__bool__c C s d| j j| jt| �f S )Nz<%s of %r at %x>)r� r9 r@ rv rO r4 r4 r6 �__repr__5 s �zClassManager.__repr__)FNNNNN)N)N)F)F)F)N)N)F)Fr9 r: r; �__doc__�__annotations__r ZDEFAULT_MANAGER_ATTRr� ZDEFAULT_STATE_ATTRr� � staticmethodr Z attrsetterr� rH rJ r rK �property� deprecatedrP �setterre rq rp rw ry rz r Zmemoized_attributer| r� r� r� Zmemoized_propertyrl r� r� r� r� rs r� rb Z hybridmethodr� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r4 r4 r4 r6 rC _ s� � � / � & ! � � �rC r� c @ s( e Zd ZdZddd�dd�Zdd� Zd S ) r� z�Provide serialization of a :class:`.ClassManager`. The :class:`.InstanceState` uses ``__init__()`` on serialize and ``__call__()`` on deserialize. r. r� )r �dc C s |j | _ |j}|j�||� d S r3 )r@ r� rD �pickle)r5 r r� r� r4 r4 r6 re E s z_SerializeManager.__init__c C sj t | j� |_}|d u r,t�|d| j ��n|jrD|jjsD|j�� |d urX|� ||� |j � ||� d S )NzxCannot deserialize object of type %r - no mapper() has been configured for this class within the current Python process!) rW r@ r� r ZUnmappedInstanceErrorrz rl Z configuredZ_check_configurer� rD Zunpickle)r5 r r� r� r� r4 r4 r6 r7 J s �� z_SerializeManager.__call__N)r9 r: r; r� re r7 r4 r4 r4 r6 r� = s r� c @ s\ e Zd ZU dZded< ddd�dd�Zdd d�d d �Zdd d d�dd�Zdd d�dd�ZdS )�InstrumentationFactoryz'Factory for new ClassManager instances.z"dispatcher[InstrumentationFactory]rD r= r> r? c C sb |d us J �t |�d u s J �| �|�\}}|d u r@t}t|�}n |d usLJ �| �||� ||_|S r3 )rW �_locate_extended_factoryrC �_check_conflictsrI )r5 r@ r� rI r4 r4 r6 �create_manager_for_clsd s z-InstrumentationFactory.create_manager_for_clsz<Tuple[Optional[ClassManager[_O]], Optional[_ManagerFactory]]c C s dS )z2Overridden by a subclass to do an extended lookup.)NNr4 rA r4 r4 r6 r� x s z/InstrumentationFactory._locate_extended_factoryz&Callable[[Type[_O]], ClassManager[_O]]r/ )r@ rI r2 c C s dS )z;Overridden by a subclass to test for conflicting factories.Nr4 )r5 r@ rI r4 r4 r6 r� ~ s z'InstrumentationFactory._check_conflictsc C s t |�}|�� | j�|� d S r3 )�manager_of_classr� rD Zclass_uninstrument)r5 r@ r� r4 r4 r6 r� � s z!InstrumentationFactory.unregisterN) r9 r: r; r� r� r� r� r� r� r4 r4 r4 r6 r� _ s r� Tr= rf rg rh ri rj rF r> )r@ rk rl rK rJ rE rG r2 c C s4 t | �}|du rt�| �}|j||||||d� |S )z_Register class instrumentation. Returns the existing or newly created class manager. N)rl rK rJ rE rG rk )rW rt r� rq )r@ rk rl rK rJ rE rG r� r4 r4 r6 r� � s � r� c C s t �| � dS )z!Unregister class instrumentation.N)rt r� )r@ r4 r4 r6 �unregister_class� s r� c C s t | j�j|dd�S )z�Return True if the given attribute on the given instance is instrumented by the attributes package. This function may be used regardless of instrumentation applied directly to the class, i.e. no descriptors are required. T)r� )r� r� r� )r� r~ r4 r4 r6 r� � s �r� c C s� |du r| j }d}tj|dd�}|| }t|dd�}t|dd�}t� �� }t|d< t||� |d } |j| _|| _ |r||| _ |r�|| _ | S ) z>Build an __init__ decorator that triggers ClassManager events.Nz�def __init__(%(apply_pos)s): new_state = class_manager._new_state_if_none(%(self_arg)s) if new_state: return new_state._initialize_instance(%(apply_kw)s) else: return original_init(%(apply_kw)s) F)Zgrouped� __defaults__�__kwdefaults__r9 re ) re r Zformat_argspec_init�getattr�locals�copyr9 �execr� Z_sa_original_initr� r� ) r@ Z class_managerrH Z func_bodyZ func_varsZ func_textZ func_defaultsZfunc_kw_defaults�envre r4 r4 r6 r� � s$ r� )TNNNNN)Hr� � __future__r �typingr r r r r r r r r r r r r r r rm � r r r r r Z_typingr r� r r �eventr r Z util.typingr r r r! r" r# r$ Z decl_baser% �eventsr& rl r' r( r) r* �symbolr, r- r< r� rC r� r� rt Zinstance_stater� � instance_dictr� r� r� rW Z_default_opt_manager_getterr� r� r� r� r4 r4 r4 r6 �<module> s� � a", � sqlalchemy/orm/__pycache__/scoping.cpython-39.pyc 0000644 00000222226 15125143220 0016007 0 ustar 00 a ��Jh3 � @ s| d dl mZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlm Z d d lm Z d d lm Z d d lm Z d d lm Z d d lmZ d dlmZ d dlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z ddl m Z e�rdd l m Z dd l m!Z! dd l m"Z" dd l#m$Z$ dd l%m&Z& dd!l'm(Z( dd"l)m*Z* dd#l)m+Z+ dd$lm,Z, dd%lm-Z- dd&lm.Z. dd'lm/Z/ dd(lm0Z0 dd)lm1Z1 dd*l2m3Z3 dd+l2m4Z4 dd,l2m5Z5 dd-l2m6Z6 dd.l2m7Z7 dd/l2m8Z8 dd0l9m:Z: dd1l9m;Z; dd2l9m<Z< dd3l=m>Z> dd4l?m@Z@ dd5l?mAZA dd6l?mBZB dd7l?mCZC dd8l?mDZD dd9l?mEZE dd:l?mFZF dd;l?mGZG dd<l?mHZH dd=l?mIZJ dd>lKmLZL dd?lMmNZN dd@lOmPZP ddAlQmRZR ddBlSmTZT ddClSmUZU edDedE�ZVG dFdG� dGe �ZWedHeXdE�ZYdIgZZeedJdKg dL�g dM�g dN�dO�G dPdI� dIee ��Z[e[Z\dQS )R� )� annotations)�Any)�Callable)�Dict)�Generic)�Iterable)�Iterator)�Optional)�overload)�Sequence)�Tuple)�Type)� TYPE_CHECKING)�TypeVar)�Union� )�_S)�Session� )�exc)�util)�create_proxy_methods)�ScopedRegistry)�ThreadLocalRegistry)�warn)�warn_deprecated)�Protocol)� _EntityType)�_IdentityKeyType)�OrmExecuteOptionsParameter)� IdentityMap)� ORMOption)�Mapper)�Query)�RowReturningQuery)�_BindArguments)�_EntityBindKey)�_PKIdentityArgument)� _SessionBind)� sessionmaker)�SessionTransaction)� Connection)� CursorResult)�Engine)�Result)�Row)� RowMapping)�_CoreAnyExecuteParams)�_CoreSingleExecuteParams)�CoreExecuteOptionsParameter)� ScalarResult)�_ColumnsClauseArgument)�_T0)�_T1)�_T2)�_T3)�_T4)�_T5)�_T6)�_T7)�_TypedColumnClauseArgument)� Executable)� UpdateBase)� ClauseElement)�TypedColumnsClauseRole)�ForUpdateParameter)�TypedReturnsRows�_T)�boundc @ s" e Zd ZdZdddd�dd�ZdS ) �QueryPropertyDescriptorz�Describes the type applied to a class-level :meth:`_orm.scoped_session.query_property` attribute. .. versionadded:: 2.0.5 r zType[_T]z Query[_T]��instance�owner�returnc C s d S �N� )�selfrI rJ rM rM �K/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/scoping.py�__get__Y � z QueryPropertyDescriptor.__get__N)�__name__� __module__� __qualname__�__doc__rP rM rM rM rO rG Q s rG �_O�scoped_sessionz:class:`_orm.Session`z$:class:`_orm.scoping.scoped_session`)� close_all�object_session� identity_key) � __contains__�__iter__�add�add_all�begin� begin_nested�close�reset�commit� connection�delete�execute�expire� expire_all�expunge� expunge_all�flush�get�get_one�get_bind� is_modified�bulk_save_objects�bulk_insert_mappings�bulk_update_mappings�merge�query�refresh�rollback�scalar�scalars) �bind�dirty�deleted�new� identity_map� is_active� autoflush� no_autoflush�info)Z classmethods�methods� attributesc @ s� e Zd ZU dZdZded< ded< ded< d�dd d �d d �Zedd�dd��Zddd�dd�Z ddd�dd�Z dd�dd�Z d�d d d �d d �Z d!dd"�d#d$�Z d%d�d&d'�Zd�d!ddd)�d*d+�Zd,dd-�d.d/�Zd�dd0d1�d2d3�Zd0d�d4d5�Zdd�d6d7�Zdd�d8d9�Zdd�d:d;�Zd�d<d=d>d?�d@dA�Zd!dd"�dBdC�Zed�ejd d d dD�dEdFdGd<dHdHdIdJ�dKdL��Zed�ejd d d dD�dMdFdGd<dHdHdNdJ�dOdL��Zed�ejd d d dD�dPdFdGd<dHdHdQdJ�dRdL��Zd�ejd d d dD�dPdFdGd<dHdHdQdJ�dSdL�Zd�d!dTddU�dVdW�Z dd�dXdY�Z d!dd"�dZd[�Z dd�d\d]�Z d�d^dd_�d`da�Z d dd d ejd db�dcdddeddfdHdGd<dgdh� didj�Z!d dd d ejd db�dcdddeddfdHdGd<dkdh� dldm�Z"d�d d d ddn�dodpdqdrdddsdt�dudv�Z#d�d!dddw�dxdy�Z$d�d,dddddz�d{d|�Z%d�d}d~dddd�d�d��Z&d}d~dd��d�d��Z'd(d d��dkddedkd��d�d��Z(ed�d�d��d�d���Z)ed�d�d��d�d���Z)ed�d�d�d��d�d���Z)ed�d�d�d�d��d�d���Z)ed�d�d�d�d�d��d�d���Z)ed�d�d�d�d�d�d��d�d���Z)ed�d�d�d�d�d�d�d��d�d���Z)ed�d�d�d�d�d�d�d�d��d�d���Z)ed�d�d�d�d�d�d�d�d�d�� d�d���Z)ed�dd�d��d�d���Z)d�dd�d��d�d��Z)d�d!dTdfdd��d�d��Z*dd�d�d��Z+ed�ejd d��d�d�dGd<dd�d��d�d���Z,ed�ejd d��dPd�dGd<ddd��d�d���Z,d�ejd d��dPd�dGd<ddd��d�d��Z,e�d ejd d��d�dFdGd<dd�d��d�dĄ�Z-e�dejd d��dPdFdGd<dd�d��d�dĄ�Z-�dejd d��dPdFdGd<dd�d��d�dĄZ-ed�d�d�dʄ�Z.e.j/d�dd˜d�dʄ�Z.edd�d�d΄�Z0edd�d�dЄ�Z1edd�d�d҄�Z2ed�d�d�dՄ�Z3e3j/d�dd˜d�dՄ�Z3edd�d�d�Z4edd�d�dڄ�Z5e5j/ddd˜d�dڄ�Z5edd�d�d݄�Z6edd�d�d߄�Z7e8dd�d�d��Z9e8d!d�d"�d�d��Z:e8�dd d d d�d�d�dHd�dHd�d�d�d��Z;d S ( rW a4 Provides scoped management of :class:`.Session` objects. See :ref:`unitofwork_contextual` for a tutorial. .. note:: When using :ref:`asyncio_toplevel`, the async-compatible :class:`_asyncio.async_scoped_session` class should be used in place of :class:`.scoped_session`. F�bool�_support_asynczsessionmaker[_S]�session_factoryzScopedRegistry[_S]�registryNzOptional[Callable[[], Any]])r� � scopefuncc C s& || _ |rt||�| _n t|�| _dS )a� Construct a new :class:`.scoped_session`. :param session_factory: a factory to create new :class:`.Session` instances. This is usually, but not necessarily, an instance of :class:`.sessionmaker`. :param scopefunc: optional function which defines the current scope. If not passed, the :class:`.scoped_session` object assumes "thread-local" scope, and will use a Python ``threading.local()`` in order to maintain the current :class:`.Session`. If passed, the function should return a hashable token; this token will be used as the key in a dictionary in order to store and retrieve the current :class:`.Session`. N)r� r r� r )rN r� r� rM rM rO �__init__� s zscoped_session.__init__r )rK c C s | � � S rL )r� �rN rM rM rO �_proxied� s zscoped_session._proxiedr )�kwrK c K sZ |r8| j �� rt�d��q@| jf i |��}| j �|� n| � � }| jsV|jrVtdd� |S )a� Return the current :class:`.Session`, creating it using the :attr:`.scoped_session.session_factory` if not present. :param \**kw: Keyword arguments will be passed to the :attr:`.scoped_session.session_factory` callable, if an existing :class:`.Session` is not present. If the :class:`.Session` is present and keyword arguments have been passed, :exc:`~sqlalchemy.exc.InvalidRequestError` is raised. zEScoped session is already present; no new arguments may be specified.z�Using `scoped_session` with asyncio is deprecated and will raise an error in a future version. Please use `async_scoped_session` instead.z1.4.23) r� �has�sa_excZInvalidRequestErrorr� �setr� Z _is_asyncior )rN r� �sessrM rM rO �__call__� s � �zscoped_session.__call__�None)�kwargsrK c K s( | j �� rtd� | jjf i |�� dS )z�reconfigure the :class:`.sessionmaker` used by this :class:`.scoped_session`. See :meth:`.sessionmaker.configure`. ztAt least one scoped session is already present. configure() can not affect sessions that have already been created.N)r� r� r r� � configure)rN r� rM rM rO r� � s �zscoped_session.configurec C s$ | j �� r| � � �� | j �� dS )a� Dispose of the current :class:`.Session`, if present. This will first call :meth:`.Session.close` method on the current :class:`.Session`, which releases any existing transactional/connection resources still being held; transactions specifically are rolled back. The :class:`.Session` is then discarded. Upon next usage within the same scope, the :class:`.scoped_session` will produce a new :class:`.Session` object. N)r� r� ra �clearr� rM rM rO �remove� s zscoped_session.removezOptional[Type[Query[_T]]]rG )� query_clsrK c s G � �fdd�d�}|� S )a� return a class property which produces a legacy :class:`_query.Query` object against the class and the current :class:`.Session` when called. .. legacy:: The :meth:`_orm.scoped_session.query_property` accessor is specific to the legacy :class:`.Query` object and is not considered to be part of :term:`2.0-style` ORM use. e.g.:: from sqlalchemy.orm import QueryPropertyDescriptor from sqlalchemy.orm import scoped_session from sqlalchemy.orm import sessionmaker Session = scoped_session(sessionmaker()) class MyClass: query: QueryPropertyDescriptor = Session.query_property() # after mappers are defined result = MyClass.query.filter(MyClass.name == "foo").all() Produces instances of the session's configured query class by default. To override and use a custom implementation, provide a ``query_cls`` callable. The callable will be invoked with the class's mapper as a positional argument and a session keyword argument. There is no limit to the number of query properties placed on a class. c s$ e Zd Zdddd�� �fdd� ZdS )z,scoped_session.query_property.<locals>.queryr zType[_O]� Query[_O]rH c s& � r� |�� � d�S �� � �|�S d S )N)�session)r� rt )�srI rJ �r� rN rM rO rP / s z4scoped_session.query_property.<locals>.query.__get__N)rR rS rT rP rM r� rM rO rt . s rt rM )rN r� rt rM r� rO �query_property s & z scoped_session.query_property�object)rI rK c C s | j �|�S )aQ Return True if the instance is associated with this session. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. The instance may be pending or persistent within the Session for a result of True. )r� r[ �rN rI rM rM rO r[ > s zscoped_session.__contains__zIterator[object]c C s | j �� S )z�Iterate over all pending or persistent instances within this Session. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. )r� r\ r� rM rM rO r\ N s zscoped_session.__iter__T)rI �_warnrK c C s | j j||d�S )a@ Place an object into this :class:`_orm.Session`. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. Objects that are in the :term:`transient` state when passed to the :meth:`_orm.Session.add` method will move to the :term:`pending` state, until the next flush, at which point they will move to the :term:`persistent` state. Objects that are in the :term:`detached` state when passed to the :meth:`_orm.Session.add` method will move to the :term:`persistent` state directly. If the transaction used by the :class:`_orm.Session` is rolled back, objects which were transient when they were passed to :meth:`_orm.Session.add` will be moved back to the :term:`transient` state, and will no longer be present within this :class:`_orm.Session`. .. seealso:: :meth:`_orm.Session.add_all` :ref:`session_adding` - at :ref:`session_basics` )r� )r� r] )rN rI r� rM rM rO r] \ s zscoped_session.addzIterable[object])� instancesrK c C s | j �|�S )a� Add the given collection of instances to this :class:`_orm.Session`. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. See the documentation for :meth:`_orm.Session.add` for a general behavioral description. .. seealso:: :meth:`_orm.Session.add` :ref:`session_adding` - at :ref:`session_basics` )r� r^ )rN r� rM rM rO r^ ~ s zscoped_session.add_allr* )�nestedrK c C s | j j|d�S )ap Begin a transaction, or nested transaction, on this :class:`.Session`, if one is not already begun. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. The :class:`_orm.Session` object features **autobegin** behavior, so that normally it is not necessary to call the :meth:`_orm.Session.begin` method explicitly. However, it may be used in order to control the scope of when the transactional state is begun. When used to begin the outermost transaction, an error is raised if this :class:`.Session` is already inside of a transaction. :param nested: if True, begins a SAVEPOINT transaction and is equivalent to calling :meth:`~.Session.begin_nested`. For documentation on SAVEPOINT transactions, please see :ref:`session_begin_nested`. :return: the :class:`.SessionTransaction` object. Note that :class:`.SessionTransaction` acts as a Python context manager, allowing :meth:`.Session.begin` to be used in a "with" block. See :ref:`session_explicit_begin` for an example. .. seealso:: :ref:`session_autobegin` :ref:`unitofwork_transaction` :meth:`.Session.begin_nested` )r� )r� r_ )rN r� rM rM rO r_ � s )zscoped_session.beginc C s | j �� S )a Begin a "nested" transaction on this Session, e.g. SAVEPOINT. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. The target database(s) and associated drivers must support SQL SAVEPOINT for this method to function correctly. For documentation on SAVEPOINT transactions, please see :ref:`session_begin_nested`. :return: the :class:`.SessionTransaction` object. Note that :class:`.SessionTransaction` acts as a context manager, allowing :meth:`.Session.begin_nested` to be used in a "with" block. See :ref:`session_begin_nested` for a usage example. .. seealso:: :ref:`session_begin_nested` :ref:`pysqlite_serializable` - special workarounds required with the SQLite driver in order for SAVEPOINT to work correctly. For asyncio use cases, see the section :ref:`aiosqlite_serializable`. )r� r` r� rM rM rO r` � s zscoped_session.begin_nestedc C s | j �� S )a� Close out the transactional resources and ORM objects used by this :class:`_orm.Session`. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. This expunges all ORM objects associated with this :class:`_orm.Session`, ends any transaction in progress and :term:`releases` any :class:`_engine.Connection` objects which this :class:`_orm.Session` itself has checked out from associated :class:`_engine.Engine` objects. The operation then leaves the :class:`_orm.Session` in a state which it may be used again. .. tip:: In the default running mode the :meth:`_orm.Session.close` method **does not prevent the Session from being used again**. The :class:`_orm.Session` itself does not actually have a distinct "closed" state; it merely means the :class:`_orm.Session` will release all database connections and ORM objects. Setting the parameter :paramref:`_orm.Session.close_resets_only` to ``False`` will instead make the ``close`` final, meaning that any further action on the session will be forbidden. .. versionchanged:: 1.4 The :meth:`.Session.close` method does not immediately create a new :class:`.SessionTransaction` object; instead, the new :class:`.SessionTransaction` is created only if the :class:`.Session` is used again for a database operation. .. seealso:: :ref:`session_closing` - detail on the semantics of :meth:`_orm.Session.close` and :meth:`_orm.Session.reset`. :meth:`_orm.Session.reset` - a similar method that behaves like ``close()`` with the parameter :paramref:`_orm.Session.close_resets_only` set to ``True``. )r� ra r� rM rM rO ra � s .zscoped_session.closec C s | j �� S )a� Close out the transactional resources and ORM objects used by this :class:`_orm.Session`, resetting the session to its initial state. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. This method provides for same "reset-only" behavior that the :meth:`_orm.Session.close` method has provided historically, where the state of the :class:`_orm.Session` is reset as though the object were brand new, and ready to be used again. This method may then be useful for :class:`_orm.Session` objects which set :paramref:`_orm.Session.close_resets_only` to ``False``, so that "reset only" behavior is still available. .. versionadded:: 2.0.22 .. seealso:: :ref:`session_closing` - detail on the semantics of :meth:`_orm.Session.close` and :meth:`_orm.Session.reset`. :meth:`_orm.Session.close` - a similar method will additionally prevent re-use of the Session when the parameter :paramref:`_orm.Session.close_resets_only` is set to ``False``. )r� rb r� rM rM rO rb s zscoped_session.resetc C s | j �� S )a Flush pending changes and commit the current transaction. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. When the COMMIT operation is complete, all objects are fully :term:`expired`, erasing their internal contents, which will be automatically re-loaded when the objects are next accessed. In the interim, these objects are in an expired state and will not function if they are :term:`detached` from the :class:`.Session`. Additionally, this re-load operation is not supported when using asyncio-oriented APIs. The :paramref:`.Session.expire_on_commit` parameter may be used to disable this behavior. When there is no transaction in place for the :class:`.Session`, indicating that no operations were invoked on this :class:`.Session` since the previous call to :meth:`.Session.commit`, the method will begin and commit an internal-only "logical" transaction, that does not normally affect the database unless pending flush changes were detected, but will still invoke event handlers and object expiration rules. The outermost database transaction is committed unconditionally, automatically releasing any SAVEPOINTs in effect. .. seealso:: :ref:`session_committing` :ref:`unitofwork_transaction` :ref:`asyncio_orm_avoid_lazyloads` )r� rc r� rM rM rO rc 0 s 'zscoped_session.commitzOptional[_BindArguments]z%Optional[CoreExecuteOptionsParameter]r+ )�bind_arguments�execution_optionsrK c C s | j j||d�S )a� Return a :class:`_engine.Connection` object corresponding to this :class:`.Session` object's transactional state. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. Either the :class:`_engine.Connection` corresponding to the current transaction is returned, or if no transaction is in progress, a new one is begun and the :class:`_engine.Connection` returned (note that no transactional state is established with the DBAPI until the first SQL statement is emitted). Ambiguity in multi-bind or unbound :class:`.Session` objects can be resolved through any of the optional keyword arguments. This ultimately makes usage of the :meth:`.get_bind` method for resolution. :param bind_arguments: dictionary of bind arguments. May include "mapper", "bind", "clause", other custom arguments that are passed to :meth:`.Session.get_bind`. :param execution_options: a dictionary of execution options that will be passed to :meth:`_engine.Connection.execution_options`, **when the connection is first procured only**. If the connection is already present within the :class:`.Session`, a warning is emitted and the arguments are ignored. .. seealso:: :ref:`session_transaction_isolation` )r� r� )r� rd )rN r� r� rM rM rO rd Y s )�zscoped_session.connectionc C s | j �|�S )a� Mark an instance as deleted. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. The object is assumed to be either :term:`persistent` or :term:`detached` when passed; after the method is called, the object will remain in the :term:`persistent` state until the next flush proceeds. During this time, the object will also be a member of the :attr:`_orm.Session.deleted` collection. When the next flush proceeds, the object will move to the :term:`deleted` state, indicating a ``DELETE`` statement was emitted for its row within the current transaction. When the transaction is successfully committed, the deleted object is moved to the :term:`detached` state and is no longer present within this :class:`_orm.Session`. .. seealso:: :ref:`session_deleting` - at :ref:`session_basics` )r� re r� rM rM rO re � s zscoped_session.delete)r� r� �_parent_execute_state� _add_eventzTypedReturnsRows[_T]z Optional[_CoreAnyExecuteParams]r z Optional[Any]z Result[_T])� statement�paramsr� r� r� r� rK c C s d S rL rM �rN r� r� r� r� r� r� rM rM rO rf � s zscoped_session.executer@ zCursorResult[Any]c C s d S rL rM r� rM rM rO rf � s r? z Result[Any]c C s d S rL rM r� rM rM rO rf � s c C s | j j||||||d�S )ac Execute a SQL expression construct. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. Returns a :class:`_engine.Result` object representing results of the statement execution. E.g.:: from sqlalchemy import select result = session.execute(select(User).where(User.id == 5)) The API contract of :meth:`_orm.Session.execute` is similar to that of :meth:`_engine.Connection.execute`, the :term:`2.0 style` version of :class:`_engine.Connection`. .. versionchanged:: 1.4 the :meth:`_orm.Session.execute` method is now the primary point of ORM statement execution when using :term:`2.0 style` ORM usage. :param statement: An executable statement (i.e. an :class:`.Executable` expression such as :func:`_expression.select`). :param params: Optional dictionary, or list of dictionaries, containing bound parameter values. If a single dictionary, single-row execution occurs; if a list of dictionaries, an "executemany" will be invoked. The keys in each dictionary must correspond to parameter names present in the statement. :param execution_options: optional dictionary of execution options, which will be associated with the statement execution. This dictionary can provide a subset of the options that are accepted by :meth:`_engine.Connection.execution_options`, and may also provide additional options understood only in an ORM context. .. seealso:: :ref:`orm_queryguide_execution_options` - ORM-specific execution options :param bind_arguments: dictionary of additional arguments to determine the bind. May include "mapper", "bind", or other custom arguments. Contents of this dictionary are passed to the :meth:`.Session.get_bind` method. :return: a :class:`_engine.Result` object. )r� r� r� r� r� )r� rf r� rM rM rO rf � s C�zOptional[Iterable[str]])rI �attribute_namesrK c C s | j j||d�S )ag Expire the attributes on an instance. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. Marks the attributes of an instance as out of date. When an expired attribute is next accessed, a query will be issued to the :class:`.Session` object's current transactional context in order to load all expired attributes for the given instance. Note that a highly isolated transaction will return the same values as were previously read in that same transaction, regardless of changes in database state outside of that transaction. To expire all objects in the :class:`.Session` simultaneously, use :meth:`Session.expire_all`. The :class:`.Session` object's default behavior is to expire all state whenever the :meth:`Session.rollback` or :meth:`Session.commit` methods are called, so that new state can be loaded for the new transaction. For this reason, calling :meth:`Session.expire` only makes sense for the specific case that a non-ORM SQL statement was emitted in the current transaction. :param instance: The instance to be refreshed. :param attribute_names: optional list of string attribute names indicating a subset of attributes to be expired. .. seealso:: :ref:`session_expire` - introductory material :meth:`.Session.expire` :meth:`.Session.refresh` :meth:`_orm.Query.populate_existing` )r� )r� rg )rN rI r� rM rM rO rg s .zscoped_session.expirec C s | j �� S )aq Expires all persistent instances within this Session. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. When any attributes on a persistent instance is next accessed, a query will be issued using the :class:`.Session` object's current transactional context in order to load all expired attributes for the given instance. Note that a highly isolated transaction will return the same values as were previously read in that same transaction, regardless of changes in database state outside of that transaction. To expire individual objects and individual attributes on those objects, use :meth:`Session.expire`. The :class:`.Session` object's default behavior is to expire all state whenever the :meth:`Session.rollback` or :meth:`Session.commit` methods are called, so that new state can be loaded for the new transaction. For this reason, calling :meth:`Session.expire_all` is not usually needed, assuming the transaction is isolated. .. seealso:: :ref:`session_expire` - introductory material :meth:`.Session.expire` :meth:`.Session.refresh` :meth:`_orm.Query.populate_existing` )r� rh r� rM rM rO rh D s 'zscoped_session.expire_allc C s | j �|�S )aj Remove the `instance` from this ``Session``. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. This will free all internal references to the instance. Cascading will be applied according to the *expunge* cascade rule. )r� ri r� rM rM rO ri m s zscoped_session.expungec C s | j �� S )aG Remove all object instances from this ``Session``. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. This is equivalent to calling ``expunge(obj)`` on all objects in this ``Session``. )r� rj r� rM rM rO rj } s zscoped_session.expunge_allzOptional[Sequence[Any]])�objectsrK c C s | j j|d�S )a� Flush all the object changes to the database. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. Writes out all pending object creations, deletions and modifications to the database as INSERTs, DELETEs, UPDATEs, etc. Operations are automatically ordered by the Session's unit of work dependency solver. Database operations will be issued in the current transactional context and do not affect the state of the transaction, unless an error occurs, in which case the entire transaction is rolled back. You may flush() as often as you like within a transaction to move changes from Python to the database's transaction buffer. :param objects: Optional; restricts the flush operation to operate only on elements that are in the given collection. This feature is for an extremely narrow set of use cases where particular objects may need to be operated upon before the full flush() occurs. It is not intended for general use. )r� )r� rk )rN r� rM rM rO rk � s zscoped_session.flush��options�populate_existing�with_for_update�identity_tokenr� r� z_EntityBindKey[_O]r' z Optional[Sequence[ORMOption]]rC z Optional[_O]) �entity�identr� r� r� r� r� r� rK c C s | j j||||||||d�S )at Return an instance based on the given primary key identifier, or ``None`` if not found. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. E.g.:: my_user = session.get(User, 5) some_object = session.get(VersionedFoo, (5, 10)) some_object = session.get(VersionedFoo, {"id": 5, "version_id": 10}) .. versionadded:: 1.4 Added :meth:`_orm.Session.get`, which is moved from the now legacy :meth:`_orm.Query.get` method. :meth:`_orm.Session.get` is special in that it provides direct access to the identity map of the :class:`.Session`. If the given primary key identifier is present in the local identity map, the object is returned directly from this collection and no SQL is emitted, unless the object has been marked fully expired. If not present, a SELECT is performed in order to locate the object. :meth:`_orm.Session.get` also will perform a check if the object is present in the identity map and marked as expired - a SELECT is emitted to refresh the object as well as to ensure that the row is still present. If not, :class:`~sqlalchemy.orm.exc.ObjectDeletedError` is raised. :param entity: a mapped class or :class:`.Mapper` indicating the type of entity to be loaded. :param ident: A scalar, tuple, or dictionary representing the primary key. For a composite (e.g. multiple column) primary key, a tuple or dictionary should be passed. For a single-column primary key, the scalar calling form is typically the most expedient. If the primary key of a row is the value "5", the call looks like:: my_object = session.get(SomeClass, 5) The tuple form contains primary key values typically in the order in which they correspond to the mapped :class:`_schema.Table` object's primary key columns, or if the :paramref:`_orm.Mapper.primary_key` configuration parameter were used, in the order used for that parameter. For example, if the primary key of a row is represented by the integer digits "5, 10" the call would look like:: my_object = session.get(SomeClass, (5, 10)) The dictionary form should include as keys the mapped attribute names corresponding to each element of the primary key. If the mapped class has the attributes ``id``, ``version_id`` as the attributes which store the object's primary key value, the call would look like:: my_object = session.get(SomeClass, {"id": 5, "version_id": 10}) :param options: optional sequence of loader options which will be applied to the query, if one is emitted. :param populate_existing: causes the method to unconditionally emit a SQL query and refresh the object with the newly loaded data, regardless of whether or not the object is already present. :param with_for_update: optional boolean ``True`` indicating FOR UPDATE should be used, or may be a dictionary containing flags to indicate a more specific set of FOR UPDATE flags for the SELECT; flags should match the parameters of :meth:`_query.Query.with_for_update`. Supersedes the :paramref:`.Session.refresh.lockmode` parameter. :param execution_options: optional dictionary of execution options, which will be associated with the query execution if one is emitted. This dictionary can provide a subset of the options that are accepted by :meth:`_engine.Connection.execution_options`, and may also provide additional options understood only in an ORM context. .. versionadded:: 1.4.29 .. seealso:: :ref:`orm_queryguide_execution_options` - ORM-specific execution options :param bind_arguments: dictionary of additional arguments to determine the bind. May include "mapper", "bind", or other custom arguments. Contents of this dictionary are passed to the :meth:`.Session.get_bind` method. .. versionadded: 2.0.0rc1 :return: The object instance, or ``None``. r� )r� rl � rN r� r� r� r� r� r� r� r� rM rM rO rl � s v�zscoped_session.getrV c C s | j j||||||||d�S )a� Return exactly one instance based on the given primary key identifier, or raise an exception if not found. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. Raises :class:`_exc.NoResultFound` if the query selects no rows. For a detailed documentation of the arguments see the method :meth:`.Session.get`. .. versionadded:: 2.0.22 :return: The object instance. .. seealso:: :meth:`.Session.get` - equivalent method that instead returns ``None`` if no row was found with the provided primary key r� )r� rm r� rM rM rO rm - s &�zscoped_session.get_one)�clausery �_sa_skip_events� _sa_skip_for_implicit_returningz Optional[_EntityBindKey[_O]]zOptional[ClauseElement]zOptional[_SessionBind]zOptional[bool]zUnion[Engine, Connection])�mapperr� ry r� r� r� rK c K s | j jf |||||d�|��S )a� Return a "bind" to which this :class:`.Session` is bound. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. The "bind" is usually an instance of :class:`_engine.Engine`, except in the case where the :class:`.Session` has been explicitly bound directly to a :class:`_engine.Connection`. For a multiply-bound or unbound :class:`.Session`, the ``mapper`` or ``clause`` arguments are used to determine the appropriate bind to return. Note that the "mapper" argument is usually present when :meth:`.Session.get_bind` is called via an ORM operation such as a :meth:`.Session.query`, each individual INSERT/UPDATE/DELETE operation within a :meth:`.Session.flush`, call, etc. The order of resolution is: 1. if mapper given and :paramref:`.Session.binds` is present, locate a bind based first on the mapper in use, then on the mapped class in use, then on any base classes that are present in the ``__mro__`` of the mapped class, from more specific superclasses to more general. 2. if clause given and ``Session.binds`` is present, locate a bind based on :class:`_schema.Table` objects found in the given clause present in ``Session.binds``. 3. if ``Session.binds`` is present, return that. 4. if clause given, attempt to return a bind linked to the :class:`_schema.MetaData` ultimately associated with the clause. 5. if mapper given, attempt to return a bind linked to the :class:`_schema.MetaData` ultimately associated with the :class:`_schema.Table` or other selectable to which the mapper is mapped. 6. No bind can be found, :exc:`~sqlalchemy.exc.UnboundExecutionError` is raised. Note that the :meth:`.Session.get_bind` method can be overridden on a user-defined subclass of :class:`.Session` to provide any kind of bind resolution scheme. See the example at :ref:`session_custom_partitioning`. :param mapper: Optional mapped class or corresponding :class:`_orm.Mapper` instance. The bind can be derived from a :class:`_orm.Mapper` first by consulting the "binds" map associated with this :class:`.Session`, and secondly by consulting the :class:`_schema.MetaData` associated with the :class:`_schema.Table` to which the :class:`_orm.Mapper` is mapped for a bind. :param clause: A :class:`_expression.ClauseElement` (i.e. :func:`_expression.select`, :func:`_expression.text`, etc.). If the ``mapper`` argument is not present or could not produce a bind, the given expression construct will be searched for a bound element, typically a :class:`_schema.Table` associated with bound :class:`_schema.MetaData`. .. seealso:: :ref:`session_partitioning` :paramref:`.Session.binds` :meth:`.Session.bind_mapper` :meth:`.Session.bind_table` )r� r� ry r� r� )r� rn )rN r� r� ry r� r� r� rM rM rO rn ^ s X��zscoped_session.get_bind)rI �include_collectionsrK c C s | j j||d�S )a� Return ``True`` if the given instance has locally modified attributes. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. This method retrieves the history for each instrumented attribute on the instance and performs a comparison of the current value to its previously flushed or committed value, if any. It is in effect a more expensive and accurate version of checking for the given instance in the :attr:`.Session.dirty` collection; a full test for each attribute's net "dirty" status is performed. E.g.:: return session.is_modified(someobject) A few caveats to this method apply: * Instances present in the :attr:`.Session.dirty` collection may report ``False`` when tested with this method. This is because the object may have received change events via attribute mutation, thus placing it in :attr:`.Session.dirty`, but ultimately the state is the same as that loaded from the database, resulting in no net change here. * Scalar attributes may not have recorded the previously set value when a new value was applied, if the attribute was not loaded, or was expired, at the time the new value was received - in these cases, the attribute is assumed to have a change, even if there is ultimately no net change against its database value. SQLAlchemy in most cases does not need the "old" value when a set event occurs, so it skips the expense of a SQL call if the old value isn't present, based on the assumption that an UPDATE of the scalar value is usually needed, and in those few cases where it isn't, is less expensive on average than issuing a defensive SELECT. The "old" value is fetched unconditionally upon set only if the attribute container has the ``active_history`` flag set to ``True``. This flag is set typically for primary key attributes and scalar object references that are not a simple many-to-one. To set this flag for any arbitrary mapped column, use the ``active_history`` argument with :func:`.column_property`. :param instance: mapped instance to be tested for pending changes. :param include_collections: Indicates if multivalued collections should be included in the operation. Setting this to ``False`` is a way to detect only local-column based properties (i.e. scalar columns or many-to-one foreign keys) that would result in an UPDATE for this instance upon flush. )r� )r� ro )rN rI r� rM rM rO ro � s <�zscoped_session.is_modified)r� �return_defaults�update_changed_only�preserve_orderrK c C s | j j||||d�S )a3 Perform a bulk save of the given list of objects. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. .. legacy:: This method is a legacy feature as of the 2.0 series of SQLAlchemy. For modern bulk INSERT and UPDATE, see the sections :ref:`orm_queryguide_bulk_insert` and :ref:`orm_queryguide_bulk_update`. For general INSERT and UPDATE of existing ORM mapped objects, prefer standard :term:`unit of work` data management patterns, introduced in the :ref:`unified_tutorial` at :ref:`tutorial_orm_data_manipulation`. SQLAlchemy 2.0 now uses :ref:`engine_insertmanyvalues` with modern dialects which solves previous issues of bulk INSERT slowness. :param objects: a sequence of mapped object instances. The mapped objects are persisted as is, and are **not** associated with the :class:`.Session` afterwards. For each object, whether the object is sent as an INSERT or an UPDATE is dependent on the same rules used by the :class:`.Session` in traditional operation; if the object has the :attr:`.InstanceState.key` attribute set, then the object is assumed to be "detached" and will result in an UPDATE. Otherwise, an INSERT is used. In the case of an UPDATE, statements are grouped based on which attributes have changed, and are thus to be the subject of each SET clause. If ``update_changed_only`` is False, then all attributes present within each object are applied to the UPDATE statement, which may help in allowing the statements to be grouped together into a larger executemany(), and will also reduce the overhead of checking history on attributes. :param return_defaults: when True, rows that are missing values which generate defaults, namely integer primary key defaults and sequences, will be inserted **one at a time**, so that the primary key value is available. In particular this will allow joined-inheritance and other multi-table mappings to insert correctly without the need to provide primary key values ahead of time; however, :paramref:`.Session.bulk_save_objects.return_defaults` **greatly reduces the performance gains** of the method overall. It is strongly advised to please use the standard :meth:`_orm.Session.add_all` approach. :param update_changed_only: when True, UPDATE statements are rendered based on those attributes in each state that have logged changes. When False, all attributes present are rendered into the SET clause with the exception of primary key attributes. :param preserve_order: when True, the order of inserts and updates matches exactly the order in which the objects are given. When False, common types of objects are grouped into inserts and updates, to allow for more batching opportunities. .. seealso:: :doc:`queryguide/dml` :meth:`.Session.bulk_insert_mappings` :meth:`.Session.bulk_update_mappings` )r� r� r� )r� rp )rN r� r� r� r� rM rM rO rp � s O�z scoped_session.bulk_save_objectsz Mapper[Any]zIterable[Dict[str, Any]])r� �mappingsr� � render_nullsrK c C s | j j||||d�S )a� Perform a bulk insert of the given list of mapping dictionaries. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. .. legacy:: This method is a legacy feature as of the 2.0 series of SQLAlchemy. For modern bulk INSERT and UPDATE, see the sections :ref:`orm_queryguide_bulk_insert` and :ref:`orm_queryguide_bulk_update`. The 2.0 API shares implementation details with this method and adds new features as well. :param mapper: a mapped class, or the actual :class:`_orm.Mapper` object, representing the single kind of object represented within the mapping list. :param mappings: a sequence of dictionaries, each one containing the state of the mapped row to be inserted, in terms of the attribute names on the mapped class. If the mapping refers to multiple tables, such as a joined-inheritance mapping, each dictionary must contain all keys to be populated into all tables. :param return_defaults: when True, the INSERT process will be altered to ensure that newly generated primary key values will be fetched. The rationale for this parameter is typically to enable :ref:`Joined Table Inheritance <joined_inheritance>` mappings to be bulk inserted. .. note:: for backends that don't support RETURNING, the :paramref:`_orm.Session.bulk_insert_mappings.return_defaults` parameter can significantly decrease performance as INSERT statements can no longer be batched. See :ref:`engine_insertmanyvalues` for background on which backends are affected. :param render_nulls: When True, a value of ``None`` will result in a NULL value being included in the INSERT statement, rather than the column being omitted from the INSERT. This allows all the rows being INSERTed to have the identical set of columns which allows the full set of rows to be batched to the DBAPI. Normally, each column-set that contains a different combination of NULL values than the previous row must omit a different series of columns from the rendered INSERT statement, which means it must be emitted as a separate statement. By passing this flag, the full set of rows are guaranteed to be batchable into one batch; the cost however is that server-side defaults which are invoked by an omitted column will be skipped, so care must be taken to ensure that these are not necessary. .. warning:: When this flag is set, **server side default SQL values will not be invoked** for those columns that are inserted as NULL; the NULL value will be sent explicitly. Care must be taken to ensure that no server-side default functions need to be invoked for the operation as a whole. .. seealso:: :doc:`queryguide/dml` :meth:`.Session.bulk_save_objects` :meth:`.Session.bulk_update_mappings` )r� r� )r� rq )rN r� r� r� r� rM rM rO rq U s P�z#scoped_session.bulk_insert_mappings)r� r� rK c C s | j �||�S )a Perform a bulk update of the given list of mapping dictionaries. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. .. legacy:: This method is a legacy feature as of the 2.0 series of SQLAlchemy. For modern bulk INSERT and UPDATE, see the sections :ref:`orm_queryguide_bulk_insert` and :ref:`orm_queryguide_bulk_update`. The 2.0 API shares implementation details with this method and adds new features as well. :param mapper: a mapped class, or the actual :class:`_orm.Mapper` object, representing the single kind of object represented within the mapping list. :param mappings: a sequence of dictionaries, each one containing the state of the mapped row to be updated, in terms of the attribute names on the mapped class. If the mapping refers to multiple tables, such as a joined-inheritance mapping, each dictionary may contain keys corresponding to all tables. All those keys which are present and are not part of the primary key are applied to the SET clause of the UPDATE statement; the primary key values, which are required, are applied to the WHERE clause. .. seealso:: :doc:`queryguide/dml` :meth:`.Session.bulk_insert_mappings` :meth:`.Session.bulk_save_objects` )r� rr )rN r� r� rM rM rO rr � s -z#scoped_session.bulk_update_mappings��loadr� )rI r� r� rK c C s | j j|||d�S )a� Copy the state of a given instance into a corresponding instance within this :class:`.Session`. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. :meth:`.Session.merge` examines the primary key attributes of the source instance, and attempts to reconcile it with an instance of the same primary key in the session. If not found locally, it attempts to load the object from the database based on primary key, and if none can be located, creates a new instance. The state of each attribute on the source instance is then copied to the target instance. The resulting target instance is then returned by the method; the original source instance is left unmodified, and un-associated with the :class:`.Session` if not already. This operation cascades to associated instances if the association is mapped with ``cascade="merge"``. See :ref:`unitofwork_merging` for a detailed discussion of merging. :param instance: Instance to be merged. :param load: Boolean, when False, :meth:`.merge` switches into a "high performance" mode which causes it to forego emitting history events as well as all database access. This flag is used for cases such as transferring graphs of objects into a :class:`.Session` from a second level cache, or to transfer just-loaded objects into the :class:`.Session` owned by a worker thread or process without re-querying the database. The ``load=False`` use case adds the caveat that the given object has to be in a "clean" state, that is, has no pending changes to be flushed - even if the incoming object is detached from any :class:`.Session`. This is so that when the merge operation populates local attributes and cascades to related objects and collections, the values can be "stamped" onto the target object as is, without generating any history or attribute events, and without the need to reconcile the incoming data with any existing related objects or collections that might not be loaded. The resulting objects from ``load=False`` are always produced as "clean", so it is only appropriate that the given objects should be "clean" as well, else this suggests a mis-use of the method. :param options: optional sequence of loader options which will be applied to the :meth:`_orm.Session.get` method when the merge operation loads the existing version of the object from the database. .. versionadded:: 1.4.24 .. seealso:: :func:`.make_transient_to_detached` - provides for an alternative means of "merging" a single object into the :class:`.Session` r� )r� rs )rN rI r� r� rM rM rO rs � s Dzscoped_session.mergez_EntityType[_O]r� )�_entityrK c C s d S rL rM )rN r� rM rM rO rt ! s zscoped_session.queryzTypedColumnsClauseRole[_T]z RowReturningQuery[Tuple[_T]])�_colexprrK c C s d S rL rM )rN r� rM rM rO rt $ s z _TCCA[_T0]z _TCCA[_T1]z"RowReturningQuery[Tuple[_T0, _T1]])�_scoped_session__ent0�_scoped_session__ent1rK c C s d S rL rM )rN r� r� rM rM rO rt . s z _TCCA[_T2]z'RowReturningQuery[Tuple[_T0, _T1, _T2]])r� r� �_scoped_session__ent2rK c C s d S rL rM )rN r� r� r� rM rM rO rt 3 s z _TCCA[_T3]z,RowReturningQuery[Tuple[_T0, _T1, _T2, _T3]])r� r� r� �_scoped_session__ent3rK c C s d S rL rM )rN r� r� r� r� rM rM rO rt 8 s z _TCCA[_T4]z1RowReturningQuery[Tuple[_T0, _T1, _T2, _T3, _T4]])r� r� r� r� �_scoped_session__ent4rK c C s d S rL rM )rN r� r� r� r� r� rM rM rO rt A s z _TCCA[_T5]z6RowReturningQuery[Tuple[_T0, _T1, _T2, _T3, _T4, _T5]])r� r� r� r� r� �_scoped_session__ent5rK c C s d S rL rM )rN r� r� r� r� r� r� rM rM rO rt K s z _TCCA[_T6]z;RowReturningQuery[Tuple[_T0, _T1, _T2, _T3, _T4, _T5, _T6]])r� r� r� r� r� r� �_scoped_session__ent6rK c C s d S rL rM )rN r� r� r� r� r� r� r� rM rM rO rt V s z _TCCA[_T7]z@RowReturningQuery[Tuple[_T0, _T1, _T2, _T3, _T4, _T5, _T6, _T7]]) r� r� r� r� r� r� r� �_scoped_session__ent7rK c C s d S rL rM ) rN r� r� r� r� r� r� r� r� rM rM rO rt b s z_ColumnsClauseArgument[Any]z Query[Any])�entitiesr� rK c O s d S rL rM �rN r� r� rM rM rO rt q s c O s | j j|i |��S )aV Return a new :class:`_query.Query` object corresponding to this :class:`_orm.Session`. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. Note that the :class:`_query.Query` object is legacy as of SQLAlchemy 2.0; the :func:`_sql.select` construct is now used to construct ORM queries. .. seealso:: :ref:`unified_tutorial` :ref:`queryguide_toplevel` :ref:`query_api_toplevel` - legacy API doc )r� rt r� rM rM rO rt v s )rI r� r� rK c C s | j j|||d�S )a� Expire and refresh attributes on the given instance. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. The selected attributes will first be expired as they would when using :meth:`_orm.Session.expire`; then a SELECT statement will be issued to the database to refresh column-oriented attributes with the current value available in the current transaction. :func:`_orm.relationship` oriented attributes will also be immediately loaded if they were already eagerly loaded on the object, using the same eager loading strategy that they were loaded with originally. .. versionadded:: 1.4 - the :meth:`_orm.Session.refresh` method can also refresh eagerly loaded attributes. :func:`_orm.relationship` oriented attributes that would normally load using the ``select`` (or "lazy") loader strategy will also load **if they are named explicitly in the attribute_names collection**, emitting a SELECT statement for the attribute using the ``immediate`` loader strategy. If lazy-loaded relationships are not named in :paramref:`_orm.Session.refresh.attribute_names`, then they remain as "lazy loaded" attributes and are not implicitly refreshed. .. versionchanged:: 2.0.4 The :meth:`_orm.Session.refresh` method will now refresh lazy-loaded :func:`_orm.relationship` oriented attributes for those which are named explicitly in the :paramref:`_orm.Session.refresh.attribute_names` collection. .. tip:: While the :meth:`_orm.Session.refresh` method is capable of refreshing both column and relationship oriented attributes, its primary focus is on refreshing of local column-oriented attributes on a single instance. For more open ended "refresh" functionality, including the ability to refresh the attributes on many objects at once while having explicit control over relationship loader strategies, use the :ref:`populate existing <orm_queryguide_populate_existing>` feature instead. Note that a highly isolated transaction will return the same values as were previously read in that same transaction, regardless of changes in database state outside of that transaction. Refreshing attributes usually only makes sense at the start of a transaction where database rows have not yet been accessed. :param attribute_names: optional. An iterable collection of string attribute names indicating a subset of attributes to be refreshed. :param with_for_update: optional boolean ``True`` indicating FOR UPDATE should be used, or may be a dictionary containing flags to indicate a more specific set of FOR UPDATE flags for the SELECT; flags should match the parameters of :meth:`_query.Query.with_for_update`. Supersedes the :paramref:`.Session.refresh.lockmode` parameter. .. seealso:: :ref:`session_expire` - introductory material :meth:`.Session.expire` :meth:`.Session.expire_all` :ref:`orm_queryguide_populate_existing` - allows any ORM query to refresh objects as they would be loaded normally. )r� r� )r� ru )rN rI r� r� rM rM rO ru � s R�zscoped_session.refreshc C s | j �� S )a" Rollback the current transaction in progress. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. If no transaction is in progress, this method is a pass-through. The method always rolls back the topmost database transaction, discarding any nested transactions that may be in progress. .. seealso:: :ref:`session_rollback` :ref:`unitofwork_transaction` )r� rv r� rM rM rO rv � s zscoped_session.rollback)r� r� zTypedReturnsRows[Tuple[_T]]z"Optional[_CoreSingleExecuteParams]z Optional[_T])r� r� r� r� r� rK c K s d S rL rM �rN r� r� r� r� r� rM rM rO rw s zscoped_session.scalarc K s d S rL rM r� rM rM rO rw s c K s | j j|f|||d�|��S )ap Execute a statement and return a scalar result. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. Usage and parameters are the same as that of :meth:`_orm.Session.execute`; the return result is a scalar Python value. �r� r� r� )r� rw r� rM rM rO rw s ���zScalarResult[_T]c K s d S rL rM r� rM rM rO rx 8 s zscoped_session.scalarszScalarResult[Any]c K s d S rL rM r� rM rM rO rx C s c K s | j j|f|||d�|��S )a_ Execute a statement and return the results as scalars. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. Usage and parameters are the same as that of :meth:`_orm.Session.execute`; the return result is a :class:`_result.ScalarResult` filtering object which will return single elements rather than :class:`_row.Row` objects. :return: a :class:`_result.ScalarResult` object .. versionadded:: 1.4.24 Added :meth:`_orm.Session.scalars` .. versionadded:: 1.4.26 Added :meth:`_orm.scoped_session.scalars` .. seealso:: :ref:`orm_queryguide_select_orm_entities` - contrasts the behavior of :meth:`_orm.Session.execute` to :meth:`_orm.Session.scalars` r� )r� rx r� rM rM rO rx N s #���z#Optional[Union[Engine, Connection]]c C s | j jS )z�Proxy for the :attr:`_orm.Session.bind` attribute on behalf of the :class:`_orm.scoping.scoped_session` class. �r� ry r� rM rM rO ry y s zscoped_session.bind)�attrrK c C s || j _d S rL r� �rN r� rM rM rO ry � s c C s | j jS )a The set of all persistent instances considered dirty. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. E.g.:: some_mapped_object in session.dirty Instances are considered dirty when they were modified but not deleted. Note that this 'dirty' calculation is 'optimistic'; most attribute-setting or collection modification operations will mark an instance as 'dirty' and place it in this set, even if there is no net change to the attribute's value. At flush time, the value of each attribute is compared to its previously saved value, and if there's no net change, no SQL operation will occur (this is a more expensive operation so it's only done at flush time). To check if an instance has actionable net changes to its attributes, use the :meth:`.Session.is_modified` method. )r� rz r� rM rM rO rz � s zscoped_session.dirtyc C s | j jS )z�The set of all instances marked as 'deleted' within this ``Session`` .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. )r� r{ r� rM rM rO r{ � s zscoped_session.deletedc C s | j jS )z�The set of all instances marked as 'new' within this ``Session``. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. )r� r| r� rM rM rO r| � s zscoped_session.newr c C s | j jS )z�Proxy for the :attr:`_orm.Session.identity_map` attribute on behalf of the :class:`_orm.scoping.scoped_session` class. �r� r} r� rM rM rO r} � s zscoped_session.identity_mapc C s || j _d S rL r� r� rM rM rO r} � s c C s | j jS )a� True if this :class:`.Session` not in "partial rollback" state. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. .. versionchanged:: 1.4 The :class:`_orm.Session` no longer begins a new transaction immediately, so this attribute will be False when the :class:`_orm.Session` is first instantiated. "partial rollback" state typically indicates that the flush process of the :class:`_orm.Session` has failed, and that the :meth:`_orm.Session.rollback` method must be emitted in order to fully roll back the transaction. If this :class:`_orm.Session` is not in a transaction at all, the :class:`_orm.Session` will autobegin when it is first used, so in this case :attr:`_orm.Session.is_active` will return True. Otherwise, if this :class:`_orm.Session` is within a transaction, and that transaction has not been rolled back internally, the :attr:`_orm.Session.is_active` will also return True. .. seealso:: :ref:`faq_session_rollback` :meth:`_orm.Session.in_transaction` )r� r~ r� rM rM rO r~ � s #zscoped_session.is_activec C s | j jS )z�Proxy for the :attr:`_orm.Session.autoflush` attribute on behalf of the :class:`_orm.scoping.scoped_session` class. �r� r r� rM rM rO r � s zscoped_session.autoflushc C s || j _d S rL r� r� rM rM rO r � s c C s | j jS )a Return a context manager that disables autoflush. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. e.g.:: with session.no_autoflush: some_object = SomeClass() session.add(some_object) # won't autoflush some_object.related_thing = session.query(SomeRelated).first() Operations that proceed within the ``with:`` block will not be subject to flushes occurring upon query access. This is useful when initializing a series of objects which involve existing database queries, where the uncompleted object should not yet be flushed. )r� r� r� rM rM rO r� s zscoped_session.no_autoflushc C s | j jS )a1 A user-modifiable dictionary. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. The initial value of this dictionary can be populated using the ``info`` argument to the :class:`.Session` constructor or :class:`.sessionmaker` constructor or factory methods. The dictionary here is always local to this :class:`.Session` and can be modified independently of all other :class:`.Session` objects. )r� r� r� rM rM rO r� s zscoped_session.infoc C s t �� S )a Close *all* sessions in memory. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. .. deprecated:: 1.3 The :meth:`.Session.close_all` method is deprecated and will be removed in a future release. Please refer to :func:`.session.close_all_sessions`. )r rX )�clsrM rM rO rX 1 s zscoped_session.close_allzOptional[Session]c C s t �|�S )a Return the :class:`.Session` to which an object belongs. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. This is an alias of :func:`.object_session`. )r rY )r� rI rM rM rO rY @ s z scoped_session.object_session)rI �rowr� zOptional[Type[Any]]zUnion[Any, Tuple[Any, ...]]z%Optional[Union[Row[Any], RowMapping]]z_IdentityKeyType[Any])�class_r� rI r� r� rK c C s t j|||||d�S )a Return an identity key. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. This is an alias of :func:`.util.identity_key`. )r� r� rI r� r� )r rZ )r� r� r� rI r� r� rM rM rO rZ P s �zscoped_session.identity_key)N)N)T)F)NN)N)N)N)N)N)N)N)T)FTT)FF)NN)N)N)N)N)N)N)NN)<rR rS rT rU r� �__annotations__r� �propertyr� r� r� r� r� r[ r\ r] r^ r_ r` ra rb rc rd re r r � EMPTY_DICTrf rg rh ri rj rk rl rm rn ro rp rq rr rs rt ru rv rw rx ry �setterrz r{ r| r} r~ r r� r� � classmethodrX rY rZ rM rM rM rO rW a s� 2 � �6"+!0 + �- �� �� �� �� M �0)$�" �"3 �� b �C �Z �W3�F �X �� �� �� �� �� �� + $ ��N)]� __future__r �typingr r r r r r r r r r r r r r r� r r � r r� r r r r r r Z util.typingr Z_typingr r r �identityr Z interfacesr! r� r" rt r# r$ r% r& r' r( r) r* Zenginer+ r, r- r. r/ r0 Zengine.interfacesr1 r2 r3 Z engine.resultr4 Z sql._typingr5 r6 r7 r8 r9 r: r; r< r= r> Z_TCCAZsql.baser? Zsql.dmlr@ Z sql.elementsrA Z sql.rolesrB Zsql.selectablerC rD rE rG r� rV �__all__rW Z ScopedSessionrM rM rM rO �<module> s� �1 n sqlalchemy/orm/__pycache__/strategy_options.cpython-39.pyc 0000644 00000174766 15125143220 0020001 0 ustar 00 a ��Jh L � @ s< U d Z ddlmZ ddlZddlmZ ddlmZ ddlmZ ddlmZ ddlmZ dd lm Z dd lm Z dd lm Z dd lm Z dd lm Z ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddl m Z ddl m Z ddl m Z ddl m!Z! dd l m"Z" dd l m#Z# dd l m$Z$ dd l m%Z% dd lm&Z& dd!lm'Z' d"d#lm(Z) d"d$lm*Z* d"dlmZ d"d%l+m,Z, d"d&l+m-Z- d"d'l+m.Z. d"d(l+m/Z/ d"d)l+m0Z0 d"d*l+m1Z1 d"d+l2m3Z3 d"d,l4m5Z5 d"d-l4m6Z6 d"d.l4m7Z7 d/Z8d0e9d1< d2Z:d3e9d4< ed5d6d7�Z;ej<�r�dd8lm=Z= dd9lm>Z> dd:l?m@Z@ dd;l?mAZA dd<l?mBZB dd=l mCZC dd>l mDZD dd?l mEZE dd@lFmGZG ddAl mHZH d"dBlImJZJ d"dClImKZK d"dDlLmMZM d"dElLmNZN ee6dF dGf ZOe6dH ZPeeQef ZReeQef ZSe eOdIf ZTG dJdK� dKe0jUe �ZVG dLdM� dMeV�ZWG dNdO� dOeV�ZXG dPdQ� dQe-jYe0jZe1j[�Z\G dRdS� dSe\�Z]G dTdU� dUe\�Z^G dVdW� dWe\�Z_dXdYdZd[dKd\�d]d^�Z`d_d`da�dbdc�Zad5d5dd�dedf�Zbebd_d[dKdg�dhdi��Zcebdjdk�d_dZdKdl�dmdn��Zdebd_d[dKdg�dodp��Zeebd_dKdq�drds��Zfebddt�d_dudKdv�dwdx��Zgebd_dKdq�dydz��Zhebddt�d_dudKdv�d{d|��Ziebd_dKdq�d}d~��Zjebd_d[dKdg�dd���Zkebd_dKdq�d�d���Zlebdjdk�d_d_dZdKd��d�d���Zmebd_d_dKd��d�d���Znebd�dKd��d�d���Zoebd_d�dKd��d�d���Zpebd�d�dKd��d�d���Zqd�d�� ZrdS )�z � )� annotationsN)�Any)�Callable)�cast)�Dict)�Iterable)�Optional)�overload)�Sequence)�Tuple)�Type)�TypeVar)�Union� )�util)�insp_is_aliased_class)�insp_is_attribute)�insp_is_mapper)�insp_is_mapper_property)�QueryableAttribute)�InspectionAttr)� LoaderOption)�_DEFAULT_TOKEN)� _StrPathToken)�_WILDCARD_TOKEN)�AbstractEntityRegistry)�path_is_property)� PathRegistry)� TokenRegistry)�_orm_full_deannotate)� AliasedInsp� )�exc��inspect)�and_)� cache_key)� coercions)�roles)� traversals)�visitors)� _generative)�Final)�Literal)�Self� relationshipz Final[Literal['relationship']]�_RELATIONSHIP_TOKEN�columnzFinal[Literal['column']]� _COLUMN_TOKEN�_FNzCallable[..., Any])�bound)� _EntityType)�_InternalEntityType)� _MapperEntity)�ORMCompileState)� QueryContext)� _StrategyKey)�MapperProperty)� ORMOption)�Mapper)�_PathRepresentation)�_ColumnExpressionArgument)�_FromClauseArgument)�_CacheKeyTraversalType)�CacheKey�*zQueryableAttribute[Any])r/ r1 .c @ sf e Zd ZU dZdZded< drddddd d �d d �Zdd �ddd d�dd�Zdsddd d�dd�Zdd d�dd�Z dtddd d�dd�Z dd d�d d �Z duddd d�d d �Z dd d�d d!�Z dvddd d"�d#d$�Zdd d�d%d&�Zdwddd d'�d(d)�Zdd d*�d+d,�Zd-d d.�d/d0�Zdd1d d2�d3d4�Zd5d d6�d7d8�Zed9d:d;�d<d=��Zed>d?d;�d@d=��ZdAdBd;�dCd=�ZedxddAddDdd dE�dFdG��ZedydHdAdDdId dJ�dKdL��ZedzdHd9dd dM�dNdO��Zed9dPd dQ�dRdS��ZdTd?dU�dVdW�Z d d dX�dYdZ�Z d{d[dBd\dDd]dddId d^� d_d`�Z dadbd?dc�ddde�Z dad?df�dgdh�Z dadbdd?di�djdk�Z!e"d|dldmddndo�dpdq��Z#dS )}� _AbstractLoad)�propagate_to_loadersT�boolrE NF� _AttrTypez Optional[_FromClauseArgument]r. )�attr�alias� _is_chain�_propagate_to_loaders�returnc C s� |dur6t |t�s"t�tj|�}qrtjddd� |}n<t|dd�rnt |t �sPJ �t |j �}|dusfJ �|j }nd}| j |ddi|d|i|r�d ndd �}|S ) a Indicate that the given attribute should be eagerly loaded from columns stated manually in the query. This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. The option is used in conjunction with an explicit join that loads the desired rows, i.e.:: sess.query(Order).join(Order.user).options(contains_eager(Order.user)) The above query would join from the ``Order`` entity to its related ``User`` entity, and the returned ``Order`` objects would have the ``Order.user`` attribute pre-populated. It may also be used for customizing the entries in an eagerly loaded collection; queries will normally want to use the :ref:`orm_queryguide_populate_existing` execution option assuming the primary collection of parent objects may already have been loaded:: sess.query(User).join(User.addresses).filter( Address.email_address.like("%@aol.com") ).options(contains_eager(User.addresses)).populate_existing() See the section :ref:`contains_eager` for complete usage details. .. seealso:: :ref:`loading_toplevel` :ref:`contains_eager` Nz�Passing a string name for the 'alias' argument to 'contains_eager()` is deprecated, and will not work in a future release. Please use a sqlalchemy.alias() or sqlalchemy.orm.aliased() construct.�1.4��version�_of_type�lazy�joinedZeager_from_aliasT)rE �opts�_reconcile_to_other)� isinstance�strr' �expectr( ZFromClauseRoler �warn_deprecated�getattrr r$ rP Z selectable�_set_relationship_strategy)�selfrH rI rJ rK Z coerced_aliasZot�cloned� r] �T/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/strategy_options.py�contains_eager` s, ( � �z _AbstractLoad.contains_eager�� raiseload��attrsra rL c G s8 | � |ddd��}ddd�}|r(d|d< |� d|�}|S )a� Indicate that for a particular entity, only the given list of column-based attribute names should be loaded; all others will be deferred. This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. Example - given a class ``User``, load only the ``name`` and ``fullname`` attributes:: session.query(User).options(load_only(User.name, User.fullname)) Example - given a relationship ``User.addresses -> Address``, specify subquery loading for the ``User.addresses`` collection, but on each ``Address`` object load only the ``email_address`` attribute:: session.query(User).options( subqueryload(User.addresses).load_only(Address.email_address) ) For a statement that has multiple entities, the lead entity can be specifically referred to using the :class:`_orm.Load` constructor:: stmt = ( select(User, Address) .join(User.addresses) .options( Load(User).load_only(User.name, User.fullname), Load(Address).load_only(Address.email_address), ) ) When used together with the :ref:`populate_existing <orm_queryguide_populate_existing>` execution option only the attributes listed will be refreshed. :param \*attrs: Attributes to be loaded, all others will be deferred. :param raiseload: raise :class:`.InvalidRequestError` rather than lazy loading a value when a deferred attribute is accessed. Used to prevent unwanted SQL from being emitted. .. versionadded:: 2.0 .. seealso:: :ref:`orm_queryguide_column_deferral` - in the :ref:`queryguide_toplevel` :param \*attrs: Attributes to be loaded, all others will be deferred. :param raiseload: raise :class:`.InvalidRequestError` rather than lazy loading a value when a deferred attribute is accessed. Used to prevent unwanted SQL from being emitted. .. versionadded:: 2.0 FT��deferredZ instrumentra )rC ��_set_column_strategy)r[ ra rc r\ Zwildcard_strategyr] r] r^ � load_only� s <� �z_AbstractLoad.load_only�Optional[bool])rH � innerjoinrL c C s* | j |ddi|dur d|intjd�}|S )a� Indicate that the given attribute should be loaded using joined eager loading. This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. examples:: # joined-load the "orders" collection on "User" select(User).options(joinedload(User.orders)) # joined-load Order.items and then Item.keywords select(Order).options(joinedload(Order.items).joinedload(Item.keywords)) # lazily load Order.items, but when Items are loaded, # joined-load the keywords collection select(Order).options(lazyload(Order.items).joinedload(Item.keywords)) :param innerjoin: if ``True``, indicates that the joined eager load should use an inner join instead of the default of left outer join:: select(Order).options(joinedload(Order.user, innerjoin=True)) In order to chain multiple eager joins together where some may be OUTER and others INNER, right-nested joins are used to link them:: select(A).options( joinedload(A.bs, innerjoin=False).joinedload(B.cs, innerjoin=True) ) The above query, linking A.bs via "outer" join and B.cs via "inner" join would render the joins as "a LEFT OUTER JOIN (b JOIN c)". When using older versions of SQLite (< 3.7.16), this form of JOIN is translated to use full subqueries as this syntax is otherwise not directly supported. The ``innerjoin`` flag can also be stated with the term ``"unnested"``. This indicates that an INNER JOIN should be used, *unless* the join is linked to a LEFT OUTER JOIN to the left, in which case it will render as LEFT OUTER JOIN. For example, supposing ``A.bs`` is an outerjoin:: select(A).options(joinedload(A.bs).joinedload(B.cs, innerjoin="unnested")) The above join will render as "a LEFT OUTER JOIN b LEFT OUTER JOIN c", rather than as "a LEFT OUTER JOIN (b JOIN c)". .. note:: The "unnested" flag does **not** affect the JOIN rendered from a many-to-many association table, e.g. a table configured as :paramref:`_orm.relationship.secondary`, to the target table; for correctness of results, these joins are always INNER and are therefore right-nested if linked to an OUTER join. .. note:: The joins produced by :func:`_orm.joinedload` are **anonymously aliased**. The criteria by which the join proceeds cannot be modified, nor can the ORM-enabled :class:`_sql.Select` or legacy :class:`_query.Query` refer to these joins in any way, including ordering. See :ref:`zen_of_eager_loading` for further detail. To produce a specific SQL JOIN which is explicitly available, use :meth:`_sql.Select.join` and :meth:`_query.Query.join`. To combine explicit JOINs with eager loading of collections, use :func:`_orm.contains_eager`; see :ref:`contains_eager`. .. seealso:: :ref:`loading_toplevel` :ref:`joined_eager_loading` rQ rR Nrj �rS )rZ r � EMPTY_DICT)r[ rH rj �loaderr] r] r^ � joinedload� s N� � z_AbstractLoad.joinedload�rH rL c C s | � |ddi�S )a` Indicate that the given attribute should be loaded using subquery eager loading. This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. examples:: # subquery-load the "orders" collection on "User" select(User).options(subqueryload(User.orders)) # subquery-load Order.items and then Item.keywords select(Order).options( subqueryload(Order.items).subqueryload(Item.keywords) ) # lazily load Order.items, but when Items are loaded, # subquery-load the keywords collection select(Order).options(lazyload(Order.items).subqueryload(Item.keywords)) .. seealso:: :ref:`loading_toplevel` :ref:`subquery_eager_loading` rQ Zsubquery�rZ �r[ rH r] r] r^ � subqueryloadJ s z_AbstractLoad.subqueryload� Optional[int])rH �recursion_depthrL c C s | j |ddid|id�S )a� Indicate that the given attribute should be loaded using SELECT IN eager loading. This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. examples:: # selectin-load the "orders" collection on "User" select(User).options(selectinload(User.orders)) # selectin-load Order.items and then Item.keywords select(Order).options( selectinload(Order.items).selectinload(Item.keywords) ) # lazily load Order.items, but when Items are loaded, # selectin-load the keywords collection select(Order).options(lazyload(Order.items).selectinload(Item.keywords)) :param recursion_depth: optional int; when set to a positive integer in conjunction with a self-referential relationship, indicates "selectin" loading will continue that many levels deep automatically until no items are found. .. note:: The :paramref:`_orm.selectinload.recursion_depth` option currently supports only self-referential relationships. There is not yet an option to automatically traverse recursive structures with more than one relationship involved. Additionally, the :paramref:`_orm.selectinload.recursion_depth` parameter is new and experimental and should be treated as "alpha" status for the 2.0 series. .. versionadded:: 2.0 added :paramref:`_orm.selectinload.recursion_depth` .. seealso:: :ref:`loading_toplevel` :ref:`selectin_eager_loading` rQ Zselectinrt rk rp )r[ rH rt r] r] r^ � selectinloadh s 2�z_AbstractLoad.selectinloadc C s | � |ddi�S )a< Indicate that the given attribute should be loaded using "lazy" loading. This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. .. seealso:: :ref:`loading_toplevel` :ref:`lazy_loading` rQ �selectrp rq r] r] r^ �lazyload� s z_AbstractLoad.lazyloadc C s | j |ddid|id�}|S )a� Indicate that the given attribute should be loaded using an immediate load with a per-attribute SELECT statement. The load is achieved using the "lazyloader" strategy and does not fire off any additional eager loaders. The :func:`.immediateload` option is superseded in general by the :func:`.selectinload` option, which performs the same task more efficiently by emitting a SELECT for all loaded objects. This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. :param recursion_depth: optional int; when set to a positive integer in conjunction with a self-referential relationship, indicates "selectin" loading will continue that many levels deep automatically until no items are found. .. note:: The :paramref:`_orm.immediateload.recursion_depth` option currently supports only self-referential relationships. There is not yet an option to automatically traverse recursive structures with more than one relationship involved. .. warning:: This parameter is new and experimental and should be treated as "alpha" status .. versionadded:: 2.0 added :paramref:`_orm.immediateload.recursion_depth` .. seealso:: :ref:`loading_toplevel` :ref:`selectin_eager_loading` rQ Z immediatert rk rp )r[ rH rt rm r] r] r^ � immediateload� s *�z_AbstractLoad.immediateloadc C s | � |ddi�S )a Indicate that the given relationship attribute should remain unloaded. The relationship attribute will return ``None`` when accessed without producing any loading effect. This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. :func:`_orm.noload` applies to :func:`_orm.relationship` attributes only. .. legacy:: The :func:`_orm.noload` option is **legacy**. As it forces collections to be empty, which invariably leads to non-intuitive and difficult to predict results. There are no legitimate uses for this option in modern SQLAlchemy. .. seealso:: :ref:`loading_toplevel` rQ �noloadrp rq r] r] r^ ry � s z_AbstractLoad.noload)rH �sql_onlyrL c C s | � |d|rdndi�S )a� Indicate that the given attribute should raise an error if accessed. A relationship attribute configured with :func:`_orm.raiseload` will raise an :exc:`~sqlalchemy.exc.InvalidRequestError` upon access. The typical way this is useful is when an application is attempting to ensure that all relationship attributes that are accessed in a particular context would have been already loaded via eager loading. Instead of having to read through SQL logs to ensure lazy loads aren't occurring, this strategy will cause them to raise immediately. :func:`_orm.raiseload` applies to :func:`_orm.relationship` attributes only. In order to apply raise-on-SQL behavior to a column-based attribute, use the :paramref:`.orm.defer.raiseload` parameter on the :func:`.defer` loader option. :param sql_only: if True, raise only if the lazy load would emit SQL, but not if it is only checking the identity map, or determining that the related value should just be None due to missing keys. When False, the strategy will raise for all varieties of relationship loading. This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. .. seealso:: :ref:`loading_toplevel` :ref:`prevent_lazy_with_raiseload` :ref:`orm_queryguide_deferred_raiseload` rQ Z raise_on_sql�raiserp )r[ rH rz r] r] r^ ra � s "�z_AbstractLoad.raiseloadc C s | � |d�S )a Indicate an attribute should load using its predefined loader style. The behavior of this loading option is to not change the current loading style of the attribute, meaning that the previously configured one is used or, if no previous style was selected, the default loading will be used. This method is used to link to other loader options further into a chain of attributes without altering the loader style of the links along the chain. For example, to set joined eager loading for an element of an element:: session.query(MyClass).options( defaultload(MyClass.someattribute).joinedload( MyOtherClass.someotherattribute ) ) :func:`.defaultload` is also useful for setting column-level options on a related class, namely that of :func:`.defer` and :func:`.undefer`:: session.scalars( select(MyClass).options( defaultload(MyClass.someattribute) .defer("some_column") .undefer("some_other_column") ) ) .. seealso:: :ref:`orm_queryguide_relationship_sub_options` :meth:`_orm.Load.options` Nrp rq r] r] r^ � defaultload! s %z_AbstractLoad.defaultload)�keyra rL c C s$ ddd�}|rd|d< | � |f|�S )a� Indicate that the given column-oriented attribute should be deferred, e.g. not loaded until accessed. This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. e.g.:: from sqlalchemy.orm import defer session.query(MyClass).options( defer(MyClass.attribute_one), defer(MyClass.attribute_two) ) To specify a deferred load of an attribute on a related class, the path can be specified one token at a time, specifying the loading style for each link along the chain. To leave the loading style for a link unchanged, use :func:`_orm.defaultload`:: session.query(MyClass).options( defaultload(MyClass.someattr).defer(RelatedClass.some_column) ) Multiple deferral options related to a relationship can be bundled at once using :meth:`_orm.Load.options`:: select(MyClass).options( defaultload(MyClass.someattr).options( defer(RelatedClass.some_column), defer(RelatedClass.some_other_column), defer(RelatedClass.another_column), ) ) :param key: Attribute to be deferred. :param raiseload: raise :class:`.InvalidRequestError` rather than lazy loading a value when the deferred attribute is accessed. Used to prevent unwanted SQL from being emitted. .. versionadded:: 1.4 .. seealso:: :ref:`orm_queryguide_column_deferral` - in the :ref:`queryguide_toplevel` :func:`_orm.load_only` :func:`_orm.undefer` Trd ra rf )r[ r} ra �strategyr] r] r^ �deferH s 6 z_AbstractLoad.defer)r} rL c C s | � |fddd��S )aj Indicate that the given column-oriented attribute should be undeferred, e.g. specified within the SELECT statement of the entity as a whole. The column being undeferred is typically set up on the mapping as a :func:`.deferred` attribute. This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. Examples:: # undefer two columns session.query(MyClass).options( undefer(MyClass.col1), undefer(MyClass.col2) ) # undefer all columns specific to a single class using Load + * session.query(MyClass, MyOtherClass).options(Load(MyClass).undefer("*")) # undefer a column on a related object select(MyClass).options(defaultload(MyClass.items).undefer(MyClass.text)) :param key: Attribute to be undeferred. .. seealso:: :ref:`orm_queryguide_column_deferral` - in the :ref:`queryguide_toplevel` :func:`_orm.defer` :func:`_orm.undefer_group` FTrd rf )r[ r} r] r] r^ �undefer� s $ �z_AbstractLoad.undeferrV ��namerL c C s | � tfdd|� �di�S )a$ Indicate that columns within the given deferred group name should be undeferred. The columns being undeferred are set up on the mapping as :func:`.deferred` attributes and include a "group" name. E.g:: session.query(MyClass).options(undefer_group("large_attrs")) To undefer a group of attributes on a related entity, the path can be spelled out using relationship loader options, such as :func:`_orm.defaultload`:: select(MyClass).options( defaultload("someattr").undefer_group("large_attrs") ) .. seealso:: :ref:`orm_queryguide_column_deferral` - in the :ref:`queryguide_toplevel` :func:`_orm.defer` :func:`_orm.undefer` NZundefer_group_T)rg r )r[ r� r] r] r^ � undefer_group� s �z_AbstractLoad.undefer_group� _ColumnExpressionArgument[Any]�r} � expressionrL c C s* t t�tj|��}| j|fddi|fd�S )a� Apply an ad-hoc SQL expression to a "deferred expression" attribute. This option is used in conjunction with the :func:`_orm.query_expression` mapper-level construct that indicates an attribute which should be the target of an ad-hoc SQL expression. E.g.:: stmt = select(SomeClass).options( with_expression(SomeClass.x_y_expr, SomeClass.x + SomeClass.y) ) .. versionadded:: 1.2 :param key: Attribute to be populated :param expr: SQL expression to be applied to the attribute. .. seealso:: :ref:`orm_queryguide_with_expression` - background and usage examples Zquery_expressionT)�extra_criteria)r r' rW r( ZLabeledColumnExprRolerg )r[ r} r� r] r] r^ �with_expression� s ��z _AbstractLoad.with_expression�Iterable[Type[Any]])�classesrL c C s0 | j ddidttdd� |D �td��id�} | S )a� Indicate an eager load should take place for all attributes specific to a subclass. This uses an additional SELECT with IN against all matched primary key values, and is the per-query analogue to the ``"selectin"`` setting on the :paramref:`.mapper.polymorphic_load` parameter. .. versionadded:: 1.2 .. seealso:: :ref:`polymorphic_selectin` Zselectinload_polymorphicT�entitiesc s s | ]}t |�V qd S �Nr# )�.0�clsr] r] r^ � <genexpr> � z5_AbstractLoad.selectin_polymorphic.<locals>.<genexpr>)r} rk )�_set_class_strategy�tuple�sorted�id)r[ r� r] r] r^ �selectin_polymorphic� s ���z"_AbstractLoad.selectin_polymorphic� _StrategySpecr: )r~ rL c C s d S r� r] �r[ r~ r] r] r^ � _coerce_strat s z_AbstractLoad._coerce_stratz Literal[None]�Nonec C s d S r� r] r� r] r] r^ r� s zOptional[_StrategySpec]�Optional[_StrategyKey]c C s" |d urt t|�� ��}nd }|S r� )r� r� �items)r[ r~ � strategy_keyr] r] r^ r� s �Optional[_OptsType])rH r~ rE rS rT rL c C s& | � |�}| j|f|t|||d� | S )N)rS rE �reconcile_to_other)r� �_clone_for_bind_strategyr0 )r[ rH r~ rE rS rT r� r] r] r^ rZ s �z(_AbstractLoad._set_relationship_strategy�Tuple[_AttrType, ...]�Optional[Tuple[Any, ...]])rc r~ rS r� rL c C s$ | � |�}| j||t|||d� | S )N)rS � attr_groupr� )r� r� r2 )r[ rc r~ rS r� r� r] r] r^ rg 0 s �z"_AbstractLoad._set_column_strategy)rc r~ rT rL c C s" | � |�}| j||d d|d� | S )NT)rE r� �r� r� )r[ rc r~ rT r� r] r] r^ �_set_generic_strategyD s �z#_AbstractLoad._set_generic_strategy� _OptsType)r~ rS rL c C s | � |�}| jd |d |d� | S )Nrk r� )r[ r~ rS r� r] r] r^ r� U s z!_AbstractLoad._set_class_strategy�Load��parentrL c C s t � �dS )z�apply this :class:`_orm._AbstractLoad` object as a sub-option o a :class:`_orm.Load` object. Implementation is provided by subclasses. N��NotImplementedError�r[ r� r] r] r^ �_apply_to_parent^ s z _AbstractLoad._apply_to_parent�rS rL c G s t � �dS )z�Apply a series of options as sub-options to this :class:`_orm._AbstractLoad` object. Implementation is provided by subclasses. Nr� �r[ rS r] r] r^ �optionsg s z_AbstractLoad.options� Optional[Tuple[_AttrType, ...]]�Optional[_WildcardKeyType]�Optional[_AttrGroupType]� rc r~ � wildcard_keyrS r� rE r� r� rL c C s t � �d S r� r� ) r[ rc r~ r� rS r� rE r� r� r] r] r^ r� p s z&_AbstractLoad._clone_for_bind_strategyr8 �Sequence[_MapperEntity])� compile_state�mapper_entitiesrL c C s& |j js d S | �||t|j� � d S r� )�compile_options�_enable_eagerloads�_processrF � current_path)r[ r� r� r] r] r^ �'process_compile_state_replaced_entities} s �z5_AbstractLoad.process_compile_state_replaced_entities)r� rL c C s2 |j js d S | �||jt|j� o*|j j � d S r� )r� r� r� Z_lead_mapper_entitiesrF r� �_for_refresh_state)r[ r� r] r] r^ �process_compile_state� s �z#_AbstractLoad.process_compile_state�r� r� �raiseerrrL c C s t � �dS )zimplemented by subclassesNr� )r[ r� r� r� r] r] r^ r� � s z_AbstractLoad._processr> r z Optional[_PathRepresentation])�to_chop�path�debugrL c C s� d}t t||j��D ]�\}\}}t|t�r||dkrZ|�dt� ��sR|�dt� ��rZ| S |t� dt� �kr|||j kr| d S ||u r�qqt|t �r�t |�r�t |�r�|� |�r�qq d S q||d d � S )N���r �:r ) � enumerate�zip� natural_pathrU rV �endswithr r r0 r} r r Zisa)r� r� r� r� �iZc_tokenZp_tokenr] r] r^ � _chop_path� s: � ��������z_AbstractLoad._chop_path)NFF)N)N)N)F)F)TNN)NN)N)NNTNN)F)$�__name__� __module__� __qualname__� __slots__Z_is_strategy_option�__annotations__r_ rh rn rr ru rw rx ry ra r| r r� r� r� r� r r� r+ rZ rg r� r� r� r� r� r� r� r� � classmethodr� r] r] r] r^ rD Z sr �FN �Y! �8 �1&';(!' � � � � �rD c @ s0 e Zd ZU dZdZdejjfdejj fdejj fdejj fgZ dZ de d< d e d< d e d< d d �d d�Zdd�dd�Zedd d�dd��Zdddd�dd�Zdd d�d d �Zdd d �d d �Zd!d"� Zd#d$d%d&d'�d(d)�Zd d&d*�d+d,�Zed-d.d/�d0d1��ZdAd3d4d5d6d7d%d8d9d.d:� d;d<�Zd=d>� Zd?d@� Z dS )Br� a� Represents loader options which modify the state of a ORM-enabled :class:`_sql.Select` or a legacy :class:`_query.Query` in order to affect how various mapped attributes are loaded. The :class:`_orm.Load` object is in most cases used implicitly behind the scenes when one makes use of a query option like :func:`_orm.joinedload`, :func:`_orm.defer`, or similar. It typically is not instantiated directly except for in some very specific cases. .. seealso:: :ref:`orm_queryguide_relationship_per_entity_wildcard` - illustrates an example where direct use of :class:`_orm.Load` may be useful )r� �context�additional_source_entitiesr� r� rE r� Nr zTuple[_LoadElement, ...]z$Tuple[_InternalEntityType[Any], ...]�_EntityType[Any])�entityc C s2 t dt|��}|j |j| _d| _d| _d| _d S )Nz$Union[Mapper[Any], AliasedInsp[Any]]r] F)r r$ Z _post_inspect�_path_registryr� r� rE r� )r[ r� �inspr] r] r^ �__init__� s z Load.__init__rV �rL c C s d| j d � d�S )N�Load(r �)�r� �r[ r] r] r^ �__str__� s z Load.__str__r �r� rL c C s& | � | �}||_d|_d|_d|_|S )Nr] F)�__new__r� r� rE r� )r� r� �loadr] r] r^ � _construct_for_existing_path� s z!Load._construct_for_existing_pathr9 r< )r� � uncached_optrL c C s || u r | S | � |�S r� )�_adjust_for_extra_criteria)r[ r� r� r] r] r^ �'_adapt_cached_option_to_uncached_option s z,Load._adapt_cached_option_to_uncached_optionc s& | � � }t� fdd�| jD ��|_|S )Nc 3 s | ]}|� � �V qd S r� )� _prepend_path)r� �elementr� r] r^ r� s z%Load._prepend_path.<locals>.<genexpr>)�_cloner� r� �r[ r� r\ r] r� r^ r� s � zLoad._prepend_path)r� rL c s� | j D ]}|jr qq| S |j�� ��du r0| S |jj}|�� � � dusLJ �ddddd�dd��| �� }t� ��fdd�| j D ��|_ |S ) z�Apply the current bound parameters in a QueryContext to all occurrences "extra_criteria" stored within this ``Load`` object, returning a new instance of this ``Load`` object. N� _LoadElementrB )�opt�replacement_cache_key�orig_cache_keyrL c s( | � � }t� �fdd�|jD ��|_|S )Nc 3 s | ]}�� � |�V qd S r� )�_apply_params_to_element)r� �crit�r� r� r] r^ r� 7 s ��zCLoad._adjust_for_extra_criteria.<locals>.process.<locals>.<genexpr>)r� r� �_extra_criteria)r� r� r� Z cloned_optr] r� r^ �process0 s � z0Load._adjust_for_extra_criteria.<locals>.processc 3 s$ | ] }|j r�|�� �n|V qd S r� )r� �r� �value�r� r� r� r] r^ r� A s ��z2Load._adjust_for_extra_criteria.<locals>.<genexpr>)r� r� Zuser_passed_query�_generate_cache_keyr� �select_statementr� r� )r[ r� r� � orig_queryr\ r] r� r^ r� s � z Load._adjust_for_extra_criteriac C s< | j }|D ],}|j}|r t�|td|d ��r | S q dS )zocalled at process time to allow adjustment of the root entity inside of _LoadElement objects. z_InternalEntityType[Any]r N)r� � entity_zero�orm_util�_entity_corresponds_tor )r[ r� r� r� �ent�ezeror] r] r^ �!_reconcile_query_entities_with_usK s � z&Load._reconcile_query_entities_with_usr8 r� rF r� r� c C sF | � ||�}t|jj�}| jD ]"}|r.|js.q |�| ||||� q d S r� )r� rF r� Z _current_pathr� rE r� )r[ r� r� r� �reconciled_lead_entityZhas_current_pathrm r] r] r^ r� ^ s � �z Load._processr� c s� | � � � � j| jksJ �t� fdd��j�d�f�j D ��s�t� j�dkrb� jd }� jd }n� jd }� jd }t�j||� t� �jdd� � jdd� �� _| j r�t �fdd�| j D ��� _ � j r� j � j 7 _ � j� j7 _dS )z�apply this :class:`_orm.Load` object as a sub-option of another :class:`_orm.Load` object. This method is used by the :meth:`_orm.Load.options` method. c 3 s" | ]}t �|� j�d ��V qdS �r N�r� �$_entity_corresponds_to_use_path_implr� � odd_element�r� �elem)r\ r] r^ r� � s � �z(Load._apply_to_parent.<locals>.<genexpr>r� r r Nc 3 s | ]}|� � �V qd S r� )�_prepend_path_fromr� )r� r] r^ r� � s ) Z _generaterE �anyr� r r� �len�_raise_for_does_not_linkr �coercer� r� )r[ r� �attrname� parent_entityr] )r\ r� r^ r� ~ s. �� $ � �zLoad._apply_to_parentrD r. r� c G sd |D ]Z}z|� | � W q ty\ } z.t|t�sFt�d|� d��|�n� W Y d}~qd}~0 0 q| S )a� Apply a series of options as sub-options to this :class:`_orm.Load` object. E.g.:: query = session.query(Author) query = query.options( joinedload(Author.book).options( load_only(Book.summary, Book.excerpt), joinedload(Book.citations).options(joinedload(Citation.author)), ) ) :param \*opts: A series of loader option objects (ultimately :class:`_orm.Load` objects) which should be applied to the path specified by this :class:`_orm.Load` object. .. versionadded:: 1.3.6 .. seealso:: :func:`.defaultload` :ref:`orm_queryguide_relationship_sub_options` zLoader option z2 is not compatible with the Load.options() method.N)r� �AttributeErrorrU rD �sa_exc� ArgumentError)r[ rS r� Zaer] r] r^ r� � s ��z Load.optionsTr� r� r� r� r� ri r� r� c C s^ |r d| _ | jjr t�d��n>t| j�r\|rF| jj�| jj|d � nt�d| jj� d���|d u r�tj | jd |||||||d� } | r�| j | f7 _ |d us�J �| j t d|d �7 _ n�|D ]�} t | t�r�tj | j| |||||||d� } n tj | j| |||||||d� } | r�|tu �r"| j| _| j | f7 _ | j�d d �r�| �� } | j | f7 _ q�| S ) NT�3Wildcard token cannot be followed by another entityr zMapped attribute 'z#' does not refer to a mapped entity)r� r� r� z Tuple[_InternalEntityType[Any]]r� rt F)rE r� �is_tokenr r r �propZ_strategy_lookup�_ClassStrategyLoad�creater� r� r rU rV �_TokenStrategyLoad�_AttributeStrategyLoadr0 � local_opts�get�_recurse) r[ rc r~ r� rS r� rE r� r� � load_elementrH Zr1r] r] r^ r� � s| � �� � � � z Load._clone_for_bind_strategyc C s | � � }| j�� |d< |S �Nr� ��_shallow_to_dictr� � serialize�r[ �dr] r] r^ � __getstate__/ s zLoad.__getstate__c C s t �|d �|d< | �|� d S r �r � deserialize�_shallow_from_dict�r[ �stater] r] r^ � __setstate__4 s zLoad.__setstate__)NNTNN) r� r� r� �__doc__r� r* �ExtendedInternalTraversal�dp_has_cache_key�InternalTraversalZdp_has_cache_key_listZ dp_boolean�_traverse_internals�_cache_key_traversalr� r� r� r� r� r� r� r� r� r� r� r+ r� r� r! r' r] r] r] r^ r� � sF � �� 4 '. � `r� c @ s� e Zd ZU dZdZdejjfdejjfdejjfgZ dZ de d< d e d< d e d< d e d< d Z d d�dd�Z d,dd�Zddd�dd�Zdd d�dd �Zd d � Zd d d!d"d#�d$d%�Zd&d�d'd(�Zd&d d)�d*d+�ZdS )-� _WildcardLoadz)represent a standalone '*' load operation)r~ r� r r~ r� r NrA �cache_key_traversalr� r� z Union[Tuple[()], Tuple[str]]Fr� r� c C s d| _ d | _tj| _d S )Nr] )r� r~ r rl r r� r] r] r^ r� M s z_WildcardLoad.__init__Tc C sn |d us J �|d } |r.t | t�r.| ttfv s2J �|� d| � �} || _| f| _|r^t�|�| _|d u sjJ �d S )Nr r� ) rU rV r r r~ r� r � immutabledictr ) r[ rc r~ r� rS r� rE r� r� rH r] r] r^ r� R s �� � z&_WildcardLoad._clone_for_bind_strategyrD r. r� c G s t d��d S )Nz(Star option does not support sub-optionsr� r� r] r] r^ r� n s z_WildcardLoad.optionsr� r� c C s� | j s J �| j d }|�t�r6|�d�d � dt� �}tt|j ��|�}|jsRJ �t � |d| j d| j | j �}| j|f7 _dS )aP apply this :class:`_orm._WildcardLoad` object as a sub-option of a :class:`_orm.Load` object. This method is used by the :meth:`_orm.Load.options` method. Note that :class:`_orm.WildcardLoad` itself can't have sub-options, but it may be used as the sub-option of a :class:`_orm.Load` object. r r� N)r� r� r �splitr r r �tokenr r r r~ r rE r� )r[ r� rH �effective_pathrm r] r] r^ r� q s � z _WildcardLoad._apply_to_parentc C s� |j j}|r| jsd S dd� |D �}|j}| j}|rX| �||�}|d u rLd S ||ksXJ �|rht|�dkslJ �|d } t| t�s�J �| � || |�} | s�d S | } t| t�s�J �t j | j | | j d | j| j|d�} | s�d S | jjs�J �| �| ||d |� | S )Nc S s g | ] }|j �qS r] )r� �r� r� r] r] r^ � <listcomp>� r� z*_WildcardLoad._process.<locals>.<listcomp>r r )r� )r� r� rE r� r� r� r rU rV �_find_entity_basestringr r r� r~ r r r� ) r[ r� r� r� � is_refreshr� r� � start_path�new_pathr2 r� Z path_elementrm r] r] r^ r� � sF � �z_WildcardLoad._processz"Iterable[_InternalEntityType[Any]]rV rF z"Optional[_InternalEntityType[Any]])r� r2 r� rL c C s� |� dt� ��r^tt|��dkrl|rlt�dd�dd� |D ��� dd�dd� |D ��� d ���n|� t�rld }|D ] }| S |r�t�d |� d ���nd S d S ) Nr� r zMCan't apply wildcard ('*') or load_only() loader option to multiple entities �, c s s | ]}t |�V qd S r� )rV r4 r] r] r^ r� � r� z8_WildcardLoad._find_entity_basestring.<locals>.<genexpr>z?. Specify loader options for each entity individually, such as c s s | ]}d |� d�V qdS )r� z).some_option('*')Nr] r4 r] r] r^ r� � s ��.FzFQuery has only expression-based entities - can't find property named "�".)r� r r �listr r �joinr )r[ r� r2 r� r� r] r] r^ r6 � s. � ��� ��z%_WildcardLoad._find_entity_basestring�Dict[str, Any]c C s | � � }|S r� )r r r] r] r^ r! � s z_WildcardLoad.__getstate__�r& rL c C s | � |� d S r� )r$ r% r] r] r^ r' � s z_WildcardLoad.__setstate__)NNTNN)r� r� r� r( r� r* r) � dp_plain_obj�dp_string_multi_dictr, r/ r� rE r� r� r� r� r� r6 r! r' r] r] r] r^ r. 9 s4 �� � =&r. c @ s� e Zd ZU dZdZdZdejjfdejj fdejj fdej j fdej j fd ej j fgZ d Zd ed< d ed < d ed< ded< ded< ded< ded< ded< dd�dd�Zdd� Zedd�dd��Zdd d �d d �Zdd d �d d �Zd!d�d"d#�Zd!d$d%�d&d'�Zd(d)� Zddd*d+�d,d-�Zd.d/� Zd0d1� Zd2d3� Z e dKdd5d d6d7ddd8d d9d d:� d;d<��Z d$d�d=d>�Z d d�d?d@�Z dAd dB�dCdD�Z!dd dE�dFdG�Z"e#d d d dH�dIdJ��Z$d S )Lr� aA represents strategy information to select for a LoaderStrategy and pass options to it. :class:`._LoadElement` objects provide the inner datastructure stored by a :class:`_orm.Load` object and are also the object passed to methods like :meth:`.LoaderStrategy.setup_query`. .. versionadded:: 2.0 )r� r~ rE r r� rT r r� r~ r r� rE rT NzTuple[Any, ...]ri r� r rF z util.immutabledict[str, Any]�is_token_strategy�is_class_strategy�intr� c C s t | �S r� )r� r� r] r] r^ �__hash__* s z_LoadElement.__hash__c C s t �| |�S r� )r) �compare)r[ �otherr] r] r^ �__eq__- s z_LoadElement.__eq__c C s t | jo| jd u �S r� )rF r r~ r� r] r] r^ � is_opts_only0 s z_LoadElement.is_opts_onlyr )�kwrL c K s | j }|�|�}| �|� |S r� )� __class__r� Z_shallow_copy_to)r[ rK r� �sr] r] r^ r� 4 s z_LoadElement._clonec K s | � � }|j�|�|_|S r� )r� r �union)r[ rK �newr] r] r^ � _update_opts; s z_LoadElement._update_optsr? c C s | � � }| j�� |d< |S r r r r] r] r^ r! @ s z_LoadElement.__getstate__r� r@ c C s t �|d �|d< | �|� d S r r" r% r] r] r^ r' E s z_LoadElement.__setstate__c C sr |j }d}|D ]}|j}|rd} q&q|sBt�d|d � d���n,t�d|d � dd�d d � |D ��� d ���d S ) NFTzGQuery has only expression-based entities; attribute loader options for r z can't be applied here.z Mapped class z@ does not apply to any of the root entities in this query, e.g. r: c s s | ]}|j rt|j �V qd S r� )r� rV )r� �xr] r] r^ r� ^ s �z3_LoadElement._raise_for_no_match.<locals>.<genexpr>zV. Please specify the full path from one of the root entities to the target attribute. )r� r� r r r> )r[ � parent_loaderr� r� Zfound_entitiesr� r� r] r] r^ �_raise_for_no_matchI s( �� ���z _LoadElement._raise_for_no_match�Optional[PathRegistry])r3 r� rL c C sL t �|j|�}|sdS t|�t|� }| j| }t�|f|dd� �}|S )a4 receives the 'current_path' entry from an :class:`.ORMCompileState` instance, which is set during lazy loads and secondary loader strategy loads, and adjusts the given path to be relative to the current_path. E.g. given a loader path and current path: .. sourcecode:: text lp: User -> orders -> Order -> items -> Item -> keywords -> Keyword cp: User -> orders -> Order -> items The adjusted path would be: .. sourcecode:: text Item -> keywords -> Keyword Nr )r� r� r� r r� r r )r[ r3 r� Zchopped_start_pathZ tokens_removed_from_start_pathZloader_lead_path_elementr] r] r^ �'_adjust_effective_path_for_current_pathg s �� �z4_LoadElement._adjust_effective_path_for_current_pathc C s t � �dS )z�Apply ORM attributes and/or wildcard to an existing path, producing a new path. This method is used within the :meth:`.create` method to initialize a :class:`._LoadElement` object. Nr� �r[ r� rH r� r� r� r� r] r] r^ � _init_path� s z_LoadElement._init_pathc C s t � �dS )zimplemented by subclasses.Nr� )r[ rR r� r� r� r� r] r] r^ �_prepare_for_compile_state� s z'_LoadElement._prepare_for_compile_statec C sN | � |||||�}|D ]2}||jv r>t�| |j| �|j|< q| |j|< qdS )z^populate ORMCompileState.attributes with loader state for this _LoadElement. N)rX � attributesr� � _reconcile)r[ rR r� r� r� r� �keysr} r] r] r^ r� � s � � z"_LoadElement.process_compile_stateTz%Union[_AttrType, _StrPathToken, None]r� r� r� r� ) r� rH r~ r� r rE r� r� r� r� rL c C s� | � | �} || _|| _|| _|r*t�|�ntj| _d| _| durH| | _ n|du r\|s\d| _ nd| _ | � |||||| �}|s~dS | j |j ks�J �|| _| S )z+Create a new :class:`._LoadElement` object.r] NT) r� r� r~ rE r r0 rl r r� rT rW rC r ) r� r� rH r~ r� r rE r� r� r� r� r� r] r] r^ r � s( � �z_LoadElement.createc C s t � �d S r� r� r� r] r] r^ r� � s z_LoadElement.__init__c C s0 | � � }t�| jd d � | jdd � �|_|S )N���)r� r r r� )r[ r\ r] r] r^ r � s $z_LoadElement._recurser� r� c sV t � fdd�|j�d�f|j D ��sJt�d� jd � d|jd � d���� �|j�S )a% adjust the path of this :class:`._LoadElement` to be a subpath of that of the given parent :class:`_orm.Load` object's path. This is used by the :meth:`_orm.Load._apply_to_parent` method, which is in turn part of the :meth:`_orm.Load.options` method. c 3 s" | ]}t �|� j�d ��V qdS r r r r� r] r^ r� s � �z2_LoadElement._prepend_path_from.<locals>.<genexpr>r� z Attribute "r z " does not link from element "r< )r r� r r� r r r� r� r] r� r^ r � s ����z _LoadElement._prepend_path_fromr� c C s^ | � � }|j| jksJ �|j| jks(J �|j| jks8J �t�|dd� |jd d � �|_|S )Nr r� )r� r~ r rD r r r� r� r] r] r^ r� s "z_LoadElement._prepend_path)� replacement�existingrL c C s� | j r |S | j du r| S |j r"| S |j du r0|S || u r<| S |j| jkrX|j| jkrX| S | jr�|�� }|j�| j�|_| j| j7 _|S |jr�| �� } | j�|j�| _| j|j7 _| S | jjr�| S t � d| j� d���dS )a define behavior for when two Load objects are to be put into the context.attributes under the same key. :param replacement: ``_LoadElement`` that seeks to replace the existing one :param existing: ``_LoadElement`` that is already present. FzLoader strategies for z conflictN) rT r~ r rJ r� rN r� r� r r ZInvalidRequestError)r] r^ r] r] r^ rZ sD � ��� �z_LoadElement._reconcile)TNNN)%r� r� r� r( r� �__visit_name__r* r) r* rA rB r+ Zdp_clauseelement_listr, r- r� rF rI �propertyrJ r� rP r! r' rS rU rW rX r� r� r r� r r r� � staticmethodrZ r] r] r] r^ r� � s\ � � * �&+ r� c s� e Zd ZU dZdZdZejdej j fdej j fg Zde d< de d< dZ dZd d � Zd d � Zd d� Zdd� Z� fdd�Z� fdd�Z� ZS )r z�Loader strategies against specific relationship or column paths. e.g.:: joinedload(User.addresses) defer(Order.name) selectinload(User.orders).lazyload(Order.items) )rP �_path_with_polymorphic_pathZ attribute_strategy_load_elementrP rb z*Union[Mapper[Any], AliasedInsp[Any], None]rT Fc C s |d us J �d | _ d | _t|�\}}} |jrH|} || }|jrD|j}|S |jsVdsVJ �t�|d |j �s�|r�|r�||d ur�t � d��q�t |t |�|j � nd S |r�|jr�J �|| _n|j| _t|dd �r�|j } t| �} | | _ |j| | _|| | }n|| }|j�r|j}|S )NFr� r z�Can't apply wildcard ('*') or load_only() loader option to multiple entities in the same option. Use separate options per entity.rP )rP rb �_parse_attr_argumentZ is_property� has_entityZ entity_pathZ is_attributer� r r� r r r rV r� rY r$ ) r[ r� rH r� r� r� r� r� �_r �acZext_infor] r] r^ rW s sH �� z!_AttributeStrategyLoad._init_pathc C s> | j sJ d��|jj}|j}|�� }|�� }|�|t| j � �S )a� Apply the current bound parameters in a QueryContext to the immediate "extra_criteria" stored with this Load object. Load objects are typically pulled from the cached version of the statement from a QueryContext. The statement currently being executed will have new values (and keys) for bound parameters in the extra criteria which need to be applied by loader strategies when they handle this criteria for a result set. z8this should only be called if _extra_criteria is present)r� r� r� �queryr� r� r% )r[ r� r� Z current_queryZk1Zk2r] r] r^ �_generate_extra_criteria� s ��z/_AttributeStrategyLoad._generate_extra_criteriac C s� | j s J �| j}|sJ �|js>ttjj|jj|jfddd��}| j }|rd| � ||�}|d u r`d S |}d|j f}||v r�|| }|}|� |�} | ||< n|||< d S )NT)�aliasedZ_use_mapper_pathZpath_with_polymorphic) rb rP �is_aliased_classr$ r� r Z_with_polymorphic_factory�mapperZ base_mapperrU r� Z _merge_with) r[ r� r� Zpwpir8 r9 r} Zexisting_aliased_inspZthis_aliased_inspZnew_aliased_inspr] r] r^ �_set_of_type_info� s: ��� � z(_AttributeStrategyLoad._set_of_type_infoc C s� |j }|jj}| jjrJ �|r(| js(g S | jr<| �|j|� | j sL| j sLg S |r`|s`| � ||� | jj rr| jj }n| j}|r�|d us�J �| �||�}|d u r�g S dtt|�jfgS �Nrm )r� r� r� r� r rE rP rl rY r~ r rS rd r� rU r r r� ) r[ rR r� r� r� r� r� r7 r3 r] r] r^ rX s, �z1_AttributeStrategyLoad._prepare_for_compile_statec sd t � �� }d|d< | jr&| j�� |d< | jr`| jjr>d |d< n"| jjrT| jj|d< n ds`J d��|S )Nr] r� rb rP Fz unexpected object for _of_type)�superr! rb r rP rj Z is_mapper�class_r �rL r] r^ r! - s � z#_AttributeStrategyLoad.__getstate__c sV t � �|� |�dd �r*t�|d �| _nd | _|�dd �rLt|d �| _nd | _d S )Nrb rP )rn r' r r r# rb r$ rP r% rp r] r^ r' E s � z#_AttributeStrategyLoad.__setstate__)r� r� r� r( r� r_ r� r, r* r) Zdp_multir* r� rD rC rW rh rl rX r! r' � __classcell__r] r] rp r^ r V s& ��G%", r c @ s0 e Zd ZdZdZdZdZdZdd� Zdd� Z d S ) r a Loader strategies against wildcard attributes e.g.:: raiseload("*") Load(User).lazyload("*") defer("*") load_only(User.name, User.email) # will create a defer('*') joinedload(User.addresses).raiseload("*") Ztoken_strategy_load_elementTFc C sN |d urJ|� t�}|� t�s |r@|r2|� d|� �}|�|�}|S t�d��|S )Nr� �kStrings are not accepted for attribute names in loader options; please use class-bound attributes directly.)r� r r r2 r r )r[ r� rH r� r� r� r� Z default_tokenr] r] r^ rW h s �z _TokenStrategyLoad._init_pathc C s� |j }|jj}| jjsJ �|r(| js(g S | js8| js8g S | j}|r\t� |f|jdd � �}|r|| � ||�} | d u rxg S | }dd� t t |�� � D �S )Nr c S s g | ] }d |f�qS )rm r] )r� r� r] r] r^ r5 � s �zA_TokenStrategyLoad._prepare_for_compile_state.<locals>.<listcomp>)r� r� r� r� r rE r~ r r r rU r r Z"_generate_natural_for_superclasses� r[ rR r� r� r� r� r� r7 r3 Znew_effective_pathr] r] r^ rX { s0 ����z-_TokenStrategyLoad._prepare_for_compile_stateN) r� r� r� r( r_ � inherit_cacherD rC rW rX r] r] r] r^ r U s r c @ s0 e Zd ZdZdZdZdZdZdd� Zdd� Z d S ) r z�Loader strategies that deals with a class as a target, not an attribute path e.g.:: q = s.query(Person).options( selectin_polymorphic(Person, [Engineer, Manager]) ) TFZclass_strategy_load_elementc C s |S r� r] rV r] r] r^ rW � s z _ClassStrategyLoad._init_pathc C s^ |j }|jj}|r | js g S | js,| js,g S | j}|rR| �||�} | d u rNg S | }d|jfgS rm ) r� r� r� rE r~ r r� rU r� rs r] r] r^ rX � s �z-_ClassStrategyLoad._prepare_for_compile_stateN) r� r� r� r( rt rD rC r_ rW rX r] r] r] r^ r � s r z Callable[..., _AbstractLoad]r� rF r )�methr[ �chainedrK rL c C s d }d|dd� fd|dd � ffD ]�\}}|D ]�}t |t�r�|�dt �rftjddd� |d d � }|tkr�|r|t�d ��|d u r�t� }| |t fi |��}n t�d ��q0|d u r�t |�\}} }t | �}|r�|s�|� |�}n| ||fd di|��}q0| ||fi |��}q0q$|�sJ �|S ) NTr r� Fr; z�The undocumented `.{WILDCARD}` format is deprecated and will be removed in a future version as it is believed to be unused. If you have been using this functionality, please comment on Issue #4390 on the SQLAlchemy project tracker.rM rN r r rr rJ ) rU rV � startswithr r rX r r r. r rc r� r| ) ru r[ rv rK � lead_elementZ is_default�_keysrH re � lead_entityr] r] r^ �_generate_from_keys� sJ ( � �� ��� r{ rG zDTuple[InspectionAttr, _InternalEntityType[Any], MapperProperty[Any]]ro c C s~ z t | �}W n2 tjy> } zt�d�|�W Y d}~n d}~0 0 t|�rT|j}|}n t|�rj|j}|j}n t�d��|||fS )a parse an attribute or wildcard argument to produce an :class:`._AbstractLoad` instance. This is used by the standalone loader strategy functions like ``joinedload()``, ``defer()``, etc. to produce :class:`_orm.Load` or :class:`._WildcardLoad` objects. z:expected ORM mapped attribute for loader strategy argumentN)r$ r ZNoInspectionAvailabler r r� r r )rH r� �errrz r r] r] r^ rc & s$ ���rc )�fnrL c C s4 t t| j�}|j}d| j� d| j� d�|_|| _| S )z�decorator that applies docstrings between standalone loader functions and the loader methods on :class:`._AbstractLoad`. z=Produce a new :class:`_orm.Load` object with the :func:`_orm.z#` option applied. See :func:`_orm.z` for usage examples. )rY rD r� r( )r} Zbound_fnZfn_docr] r] r^ �loader_unbound_fnK s �� r~ )r[ rK rL c O s t tj| d|�S )NT)r{ r� r_ �r[ rK r] r] r^ r_ a s r_ Fr` rb c G s& t |d �\}}}t|�j|d| i�S )Nr ra )rc r� rh )ra rc re rx r] r] r^ rh f s rh c O s t tj| d|�S �NF)r{ r� rn r r] r] r^ rn n s rn )r[ rL c G s t tj| di �S r� )r{ r� rr �r[ r] r] r^ rr s s rr )rt rs )r[ rt rL c G s t tj|dd| i�S �NFrt )r{ r� ru �rt r[ r] r] r^ ru x s �ru c G s t tj| di �S r� )r{ r� rw r� r] r] r^ rw � s rw c G s t tj|dd| i�S r� )r{ r� rx r� r] r] r^ rx � s �rx c G s t tj| di �S r� )r{ r� ry r� r] r] r^ ry � s ry c O s t tj| d|�S r� )r{ r� ra r r] r] r^ ra � s ra c G s t tj| di �S r� )r{ r� r| r� r] r] r^ r| � s r| )r} � addl_attrsra rL c G s: |rt jddd� |r d|i}ni }ttj| f| d|�S )Nz}The *addl_attrs on orm.defer is deprecated. Please use method chaining in conjunction with defaultload() to indicate a path.�1.3rN ra F)r rX r{ r� r )r} ra r� rK r] r] r^ r � s � r )r} r� rL c G s( |rt jddd� ttj| f| di �S )NzThe *addl_attrs on orm.undefer is deprecated. Please use method chaining in conjunction with defaultload() to indicate a path.r� rN F)r rX r{ r� r� )r} r� r] r] r^ r� � s �r� rV r� c C s t � }|�| �S r� )r. r� )r� r� r] r] r^ r� � s r� r� r� c C s t tj| fdd|i�S )NFr� )r{ r� r� )r} r� r] r] r^ r� � s �r� r� r� )�base_clsr� rL c C s t | �}|�|�S r� )r� r� )r� r� �ulr] r] r^ r� � s r� c C s� t | �dkr�| d j| d jju}t|�r4t|�}n|jj}t�d|� d| d � d�|rhd| d � d�nd |s�| d j s�t � | jt |�j�r�d | d � d|� d | d jjj� d |� d � nd f ��n t�d|� d| d � d���d S )Nr r� r\ z ORM mapped entity or attribute "z#" does not link from relationship "z%s".%sz .of_type(r� � z Did you mean to use "z,)" or "loadopt.options(selectin_polymorphic(z, [z ]), ...)" ?zORM mapped attribute "z " does not link mapped class "�") r r� rk ro r rV r� r r rj r� r� r$ )r� r r Zpath_is_of_typeZparent_entity_strr] r] r^ r � sF ��� ���� �� �����r )sr( � __future__r �typingr r r r r r r r r r r r r� r r� Z_typingr r r r rY r �baser Z interfacesr Z path_registryr r r r r r r r r r" r r$ Zsqlr% r& r' r( r) r* Zsql.baser+ Z util.typingr, r- r. r0 r� r2 r3 � TYPE_CHECKINGr5 r6 r� r7 r8 r9 r: r; r< rk r= r> Z sql._typingr? r@ Z sql.cache_keyrA rB rG Z_WildcardKeyTyperV r� r� Z_AttrGroupTypeZGenerativeOnTraversalrD r� r. Z HasCacheKeyZHasShallowCopyZ Traversibler� r r r r{ rc r~ r_ rh rn rr ru rw rx ry ra r| r r� r� r� r� r r] r] r] r^ �<module> s� u r A � _ Y8@%��� sqlalchemy/orm/__pycache__/mapper.cpython-39.pyc 0000644 00000350230 15125143220 0015626 0 ustar 00 a ��Jh�� � @ s& U d Z ddlmZ ddlmZ ddlmZ ddlmZ ddl Z ddl Z ddl m Z ddl m Z dd l mZ dd l mZ dd l mZ dd l mZ dd l mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl m Z ddl m Z ddl m Z ddl m Z ddl Z dd l!m"Z" dd l!m#Z$ dd l!m%Z% dd l!m&Z& dd l!m'Z' dd!l!m(Z) dd"l*m+Z+ dd#l,m-Z- dd$l,m.Z. dd%l,m/Z/ dd&l,m0Z0 dd'l,m1Z1 dd(l2m3Z3 dd)l2m4Z4 dd*l2m5Z5 dd+l2m6Z6 dd,l2m7Z7 dd-l2m8Z8 dd.l2m9Z9 dd/l:m;Z; d0d1l!m<Z< d0d l!m#Z= d0d2l!m>Z> d0d3l!m?Z? d0d4l!m@Z@ d0d5l!mAZA d0d!l!m(Z( d0d6l<mBZB d0d7l<mCZC d0d8lAm,ZD d0d9lAmEZE d0d:lAmFZF d0d;lAmGZG d0d<lAmHZH d0d=lAmIZI d0d!lAm(ZJ d0d>lAmKZK d0d?lLmMZM d0d@lNmOZO d0dAlPmQZQ d0dBlPmRZR d0dClSmTZT d0dDl(mUZU d0dEl(mVZV d0dFlWmXZX e �r�ddGl*mYZY ddHl*mZZZ ddIl*m[Z[ ddJl*m\Z\ ddKl]m^Z^ ddLl_m`Z` ddMlambZb ddNlamcZc ddOldmeZe ddPl%mfZf ddQl:mgZg ddRl'mhZh ddSlimjZj ddTlkmlZl ddUl(mmZm d0dVlnmoZo d0dWlnmpZp d0dXlqmrZr d0dYlqmsZs d0dZltmuZu d0d[lNmvZv d0d\lNmwZw d0d]lSmxZx d0d^l(myZy e d_e d`�Zze dadbd`�Z{e dcddd`�Z|e eXde ee eXde ee dfe e f f edg f ee dfe e f f Z}e �~� Zdhe�di< djdk�dldm�Z�dndk�dodp�Z�dqa�e(��dr�Z�e ��� Z�e>j�e?j�G dsdt� dte8e7e+ eMe5e?j�e>j�du eCee+ � ��Z�G dvdw� dwe��Z�dxdk�dydz�Z�d{d|dxd}�d~d�Z�e(��d��d{d|dxd}�d�d���Z�e(��d��d{d|dxd}�d�d���Z�dcdcd��d�d��Z�dqd�d��d�d|d|d�d��d�d��Z�d�d�� Z�d�d�� Z�G d�d�� d�ed� �Z�dS )�a5 Logic to map Python classes to and from selectables. Defines the :class:`~sqlalchemy.orm.mapper.Mapper` class, the central configurational unit which associates a class with a database table. This is a semi-private module; the main configurational API of the ORM is available in :class:`~sqlalchemy.orm.`. � )� annotations)�deque)�reduce)�chainN)�Any)�Callable)�cast)� Collection)�Deque)�Dict)� FrozenSet)�Generic)�Iterable)�Iterator)�List)�Mapping)�Optional)�Sequence)�Set)�Tuple)�Type)� TYPE_CHECKING)�TypeVar)�Union� )� attributes)�exc)�instrumentation)�loading)� properties)�util)�_O)�_class_to_mapper)�_parse_mapper_argument)� _state_mapper)� PassiveFlag)� state_str)�_MappedAttribute)�EXT_SKIP)�InspectionAttr)�MapperProperty)�ORMEntityColumnsClauseRole)�ORMFromClauseRole)�StrategizedProperty)� PathRegistry� )�event)� inspection)�log)�schema)�sql)� dispatcher)� EventTarget)�base)� coercions)� expression)� operators)�roles)� TableClause)�visitors)�MemoizedHasCacheKey)�KeyedColumnElement)�Column)�Table)� LABEL_STYLE_TABLENAME_PLUS_COL)� HasMemoized)�!HasMemoized_ro_memoized_attribute)�Literal)�_IdentityKeyType)� _InstanceDict)�_ORMColumnExprArgument)� _RegistryType)�registry)�DependencyProcessor)�CompositeProperty)�SynonymProperty)� MapperEvents)� ClassManager)�CachingEntityRegistry)�ColumnProperty)�RelationshipProperty)� InstanceState)� ORMAdapter)�Row)� RowMapping)�_ColumnExpressionArgument)�_EquivalentColumnMap)�ReadOnlyColumnCollection)� ColumnClause)� ColumnElement)� FromClause)� OrderedSet�_T)�bound�_MP�MapperProperty[Any]�_FnzCallable[..., Any]�*� Mapper[Any]r\ z.weakref.WeakKeyDictionary[_RegistryType, bool]�_mapper_registriesz Set[registry]��returnc C s0 t � tt�W d � S 1 s"0 Y d S �N)�_CONFIGURE_MUTEX�setre � rk rk �J/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/mapper.py�_all_registries� s rm �Iterator[Mapper[Any]]c c s t � D ]} | �� E d H qd S rh )rm �_mappers_to_configure)�regrk rk rl �_unconfigured_mappers� s rq F� NO_ATTRIBUTEc @ s� e Zd ZU dZded< dZdZded< dZej dd��d�d dddddddddddddddddddd d d dddd dd d � d!d"��Z d#d$� Z d%d&� Z d Z dZd'ed(< ed)d*�d+d,��Zed-d.� �Zd ed/< d ed0< d1ed2< d3ed4< d5ed6< d7ed8< d9ed:< d ed;< d<ed=< d>ed?< d@edA< dBedC< dDedE< dFedG< dHedI< dJedK< dLedM< dedN< dedO< dPedQ< dRedS< dedT< dUedV< dUedW< dXedY< dZed[< dZded\< ded]< d^ed_< d`eda< dedb< dedc< ddede< dfedg< dedh< diedj< dkedl< dkedm< eje�dndo�dpdq� ��Zejdrd*�dsdt��Zdudv� Zddwdx�dydz�Zd{d|� Zd}d~� Zdd�� Z d�d�� Z dwd*�d�d��Z d�d�d�d��d�d��Z dwd*�d�d��Z dwd*�d�d��Z!�d�d�d��Z"d Z#e$j%d�d�� �Z&e$j%d�d�� �Z'e$j%d�d�� �Z(e�)d��d�d�� �Z*e�)d��d d dd��d�d�dddd�d��d�d���Z+d�d�d�d��d�d��Z,�d�d�d�dd�ddd�d��d�d��Z-e�)d��d�d�d�d��d�d���Z.ej/�0d�e1j2�dwd*�d�d���Z3dwd*�d�d��Z4d�d�� Z5d�d�dwd��d�d��Z6dwd*�d�d��Z7ed�d*�d�d���Z8d�ddwd��d�d��Z9d�ddwd��d�d��Z:d�d*�d�d��Z;d�d*�d�dZ<d�ddĜd�dƄZ=d�ddǜd�dɄZ>�d�d�dd�dʜd�d̄Z?d�d�dϜd�dфZ@ed�dӄ �ZAddd�d՜d�dׄZBd�ddUdٜd�dۄZCe$j%dd*�d�d݄�ZDe$j%d�d߄ �ZEe$j%d�d� �ZFe$j%d�d� �ZGe$j%d�d*�d�d��ZHe$j%d�d� �ZIeJdUd*�d�d��ZKeHZLeJd�d� �ZMe$j%d�d� �ZNe$j%d�d� �ZOe$j%d�d� �ZPe$j%d�d� �ZQe$j%d�d*�d�d���ZRe$j%d�d*�d�d���ZSe$j%d�d*�d�d���ZTe$j%d�d*�d�d���ZUe$j%d�d*�d��d ��ZVe$jW�d�d� �ZXej�d�d� �ZYedUd*��d�d��ZZ�d�d�dd�d�d ��d �d �Z[e$j%�d �d � �Z\e�d�d� �Z]�d��d�d�Z^e$j%�dd*��d�d��Z_�d��d�d�Z`e$j%�dd*��d�d��Zae$j%�dd*��d �d ��Zbe$j%e�)d���d d*��d �d ���Zce$j%e�)d���d!d*��d"�d#���Zde�d$�d%� �Zee$j%�d&d*��d'�d(��Zfe$j%e�)�d)��d*d*��d+�d,���Zge$j%e�)d���d-d*��d.�d/���Zh�d0�d1�d2��d3�d4�Zie$j%�d5�d6� �Zje$j%�d7d*��d8�d9��Zkd�dd�d:��d;�d<�Zle$j%�d=�d>� �Zm�d?�d@� Zndid�dA��dB�dC�Zodid�dA��dD�dE�Zp�dFdd�dG��dH�dI�Zqdid�dA��dJ�dK�Zr�dLd*��dM�dN�Zse$j%d�d*��dO�dP��Zt�dLd*��dQ�dR�Zudid*��dS�dT�Zvedid*��dU�dV��Zw�d��dW�dX�Zx�d��dYd�dZ�d[�d\��d]�d^�Zy�d��d_d�d[�d`��da�db�Zz�dc�d[�dd��de�df�Z{e|j}fdÐdg�d[�dh��di�dj�Z~�dc�d_�dd��dk�dl�Ze$j%�dm�dn� �Z�e$j%�do�dp� �Z�e$j%�dq�dr� �Z�e$j%�ds�dt� �Z�e$j%�du�dv� �Z�e|j}fdÐdw�dx�dgd�dy��dz�d{�Z��d|�d}� Z��d~�d� Z��d��d�� Z�e|j}f�d��d��Z��d��d�� Z��d��d�� Z�e$j%�d��d�� �Z��d��d�� Z��d��d�� Z�e�)�d���d��d�� �Z�e$j%�d��d�� �Z��d�d�dÐd��d��d���d��d��Z�e$j%�d��d�� �Z�e$j%�d��d�� �Z�e$j%�d��d�� �Z�d�d��d��d���d��d��Z�ej�d��d�� �Z�d S (� �Mappera� Defines an association between a Python class and a database table or other relational structure, so that ORM operations against the class may proceed. The :class:`_orm.Mapper` object is instantiated using mapping methods present on the :class:`_orm.registry` object. For information about instantiating new :class:`_orm.Mapper` objects, see :ref:`orm_mapping_classes_toplevel`. zdispatcher[Mapper[_O]]�dispatchFr �_configure_failed)�1.3a The :paramref:`.mapper.non_primary` parameter is deprecated, and will be removed in a future release. The functionality of non primary mappers is now better suited using the :class:`.AliasedClass` construct, which can also be used as the target of a :func:`_orm.relationship` in 1.3.)� non_primaryNT�auto�d zType[_O]zOptional[FromClause]z+Optional[Mapping[str, MapperProperty[Any]]]z/Optional[Iterable[_ORMColumnExprArgument[Any]]]�boolz'Optional[Union[Mapper[Any], Type[Any]]]z)Optional[_ColumnExpressionArgument[bool]]z/Optional[Sequence[_ORMColumnExprArgument[Any]]]z%Optional[_ORMColumnExprArgument[Any]]z5Optional[Union[Literal[False], Callable[[Any], Any]]]zFOptional[Union[_ORMColumnExprArgument[Any], str, MapperProperty[Any]]]z Optional[Dict[Any, Mapper[Any]]]z Optional[Any]z Optional[_WithPolymorphicArg]z'Optional[Literal['selectin', 'inline']]z Optional[str]zOptional[Sequence[str]]z Literal[True, False, 'auto']�int) �class_� local_tabler � primary_keyrw �inherits�inherit_condition�inherit_foreign_keys�always_refresh�version_id_col�version_id_generator�polymorphic_on�_polymorphic_map�polymorphic_identity�concrete�with_polymorphic�polymorphic_abstract�polymorphic_load�allow_partial_pks�batch� column_prefix�include_properties�exclude_properties�passive_updates�passive_deletes�confirm_deleted_rows�eager_defaults�legacy_is_orphan�_compiled_cache_sizec C s� t �|td�| _d| jj| jjf | _t �|�| _|| _ | | _ t | t �rV| | _ d| _n | durptjtj| dd�nd| _| du r�d| _n| du r�dd� | _n| | _|| _d| _|dur�t|�| _nd| _|dur�tjtj|d d d �| _n.| jr�| jj| _d | _nt�d | jj� d ���|du�r0t�tj |�| _ nd| _ || _ |�rJt |�ni | _ g | _!|| _"|| _#|| _$| du�r�tjtj| dd�nd| _%|| _&g | _'t j(| _)|| _*|| _+| | _,d| _-d| _.d| _/i | _0| | _1d| _2|| _3| j�r�| j�s�d| _4n|| _4| �5|� || _6|| _7| du �r i | _8n| | _8|du�r>t �9|�| _:nd| _:|�rXt �9|�| _;nd| _;t<�l t=d| j>j?��@|| � | �A� | �B� | �C� | �D� | �E� | jF�G| � | �Hd� | �I� W d � n1 �s�0 Y | j>�J| | j� dS )abY Direct constructor for a new :class:`_orm.Mapper` object. The :class:`_orm.Mapper` constructor is not called directly, and is normally invoked through the use of the :class:`_orm.registry` object through either the :ref:`Declarative <orm_declarative_mapping>` or :ref:`Imperative <orm_imperative_mapping>` mapping styles. .. versionchanged:: 2.0 The public facing ``mapper()`` function is removed; for a classical mapping configuration, use the :meth:`_orm.registry.map_imperatively` method. Parameters documented below may be passed to either the :meth:`_orm.registry.map_imperatively` method, or may be passed in the ``__mapper_args__`` declarative class attribute described at :ref:`orm_declarative_mapper_options`. :param class\_: The class to be mapped. When using Declarative, this argument is automatically passed as the declared class itself. :param local_table: The :class:`_schema.Table` or other :class:`_sql.FromClause` (i.e. selectable) to which the class is mapped. May be ``None`` if this mapper inherits from another mapper using single-table inheritance. When using Declarative, this argument is automatically passed by the extension, based on what is configured via the :attr:`_orm.DeclarativeBase.__table__` attribute or via the :class:`_schema.Table` produced as a result of the :attr:`_orm.DeclarativeBase.__tablename__` attribute being present. :param polymorphic_abstract: Indicates this class will be mapped in a polymorphic hierarchy, but not directly instantiated. The class is mapped normally, except that it has no requirement for a :paramref:`_orm.Mapper.polymorphic_identity` within an inheritance hierarchy. The class however must be part of a polymorphic inheritance scheme which uses :paramref:`_orm.Mapper.polymorphic_on` at the base. .. versionadded:: 2.0 .. seealso:: :ref:`orm_inheritance_abstract_poly` :param always_refresh: If True, all query operations for this mapped class will overwrite all data within object instances that already exist within the session, erasing any in-memory changes with whatever information was loaded from the database. Usage of this flag is highly discouraged; as an alternative, see the method :meth:`_query.Query.populate_existing`. :param allow_partial_pks: Defaults to True. Indicates that a composite primary key with some NULL values should be considered as possibly existing within the database. This affects whether a mapper will assign an incoming row to an existing identity, as well as if :meth:`.Session.merge` will check the database first for a particular primary key value. A "partial primary key" can occur if one has mapped to an OUTER JOIN, for example. The :paramref:`.orm.Mapper.allow_partial_pks` parameter also indicates to the ORM relationship lazy loader, when loading a many-to-one related object, if a composite primary key that has partial NULL values should result in an attempt to load from the database, or if a load attempt is not necessary. .. versionadded:: 2.0.36 :paramref:`.orm.Mapper.allow_partial_pks` is consulted by the relationship lazy loader strategy, such that when set to False, a SELECT for a composite primary key that has partial NULL values will not be emitted. :param batch: Defaults to ``True``, indicating that save operations of multiple entities can be batched together for efficiency. Setting to False indicates that an instance will be fully saved before saving the next instance. This is used in the extremely rare case that a :class:`.MapperEvents` listener requires being called in between individual row persistence operations. :param column_prefix: A string which will be prepended to the mapped attribute name when :class:`_schema.Column` objects are automatically assigned as attributes to the mapped class. Does not affect :class:`.Column` objects that are mapped explicitly in the :paramref:`.Mapper.properties` dictionary. This parameter is typically useful with imperative mappings that keep the :class:`.Table` object separate. Below, assuming the ``user_table`` :class:`.Table` object has columns named ``user_id``, ``user_name``, and ``password``:: class User(Base): __table__ = user_table __mapper_args__ = {"column_prefix": "_"} The above mapping will assign the ``user_id``, ``user_name``, and ``password`` columns to attributes named ``_user_id``, ``_user_name``, and ``_password`` on the mapped ``User`` class. The :paramref:`.Mapper.column_prefix` parameter is uncommon in modern use. For dealing with reflected tables, a more flexible approach to automating a naming scheme is to intercept the :class:`.Column` objects as they are reflected; see the section :ref:`mapper_automated_reflection_schemes` for notes on this usage pattern. :param concrete: If True, indicates this mapper should use concrete table inheritance with its parent mapper. See the section :ref:`concrete_inheritance` for an example. :param confirm_deleted_rows: defaults to True; when a DELETE occurs of one more rows based on specific primary keys, a warning is emitted when the number of rows matched does not equal the number of rows expected. This parameter may be set to False to handle the case where database ON DELETE CASCADE rules may be deleting some of those rows automatically. The warning may be changed to an exception in a future release. :param eager_defaults: if True, the ORM will immediately fetch the value of server-generated default values after an INSERT or UPDATE, rather than leaving them as expired to be fetched on next access. This can be used for event schemes where the server-generated values are needed immediately before the flush completes. The fetch of values occurs either by using ``RETURNING`` inline with the ``INSERT`` or ``UPDATE`` statement, or by adding an additional ``SELECT`` statement subsequent to the ``INSERT`` or ``UPDATE``, if the backend does not support ``RETURNING``. The use of ``RETURNING`` is extremely performant in particular for ``INSERT`` statements where SQLAlchemy can take advantage of :ref:`insertmanyvalues <engine_insertmanyvalues>`, whereas the use of an additional ``SELECT`` is relatively poor performing, adding additional SQL round trips which would be unnecessary if these new attributes are not to be accessed in any case. For this reason, :paramref:`.Mapper.eager_defaults` defaults to the string value ``"auto"``, which indicates that server defaults for INSERT should be fetched using ``RETURNING`` if the backing database supports it and if the dialect in use supports "insertmanyreturning" for an INSERT statement. If the backing database does not support ``RETURNING`` or "insertmanyreturning" is not available, server defaults will not be fetched. .. versionchanged:: 2.0.0rc1 added the "auto" option for :paramref:`.Mapper.eager_defaults` .. seealso:: :ref:`orm_server_defaults` .. versionchanged:: 2.0.0 RETURNING now works with multiple rows INSERTed at once using the :ref:`insertmanyvalues <engine_insertmanyvalues>` feature, which among other things allows the :paramref:`.Mapper.eager_defaults` feature to be very performant on supporting backends. :param exclude_properties: A list or set of string column names to be excluded from mapping. .. seealso:: :ref:`include_exclude_cols` :param include_properties: An inclusive list or set of string column names to map. .. seealso:: :ref:`include_exclude_cols` :param inherits: A mapped class or the corresponding :class:`_orm.Mapper` of one indicating a superclass to which this :class:`_orm.Mapper` should *inherit* from. The mapped class here must be a subclass of the other mapper's class. When using Declarative, this argument is passed automatically as a result of the natural class hierarchy of the declared classes. .. seealso:: :ref:`inheritance_toplevel` :param inherit_condition: For joined table inheritance, a SQL expression which will define how the two tables are joined; defaults to a natural join between the two tables. :param inherit_foreign_keys: When ``inherit_condition`` is used and the columns present are missing a :class:`_schema.ForeignKey` configuration, this parameter can be used to specify which columns are "foreign". In most cases can be left as ``None``. :param legacy_is_orphan: Boolean, defaults to ``False``. When ``True``, specifies that "legacy" orphan consideration is to be applied to objects mapped by this mapper, which means that a pending (that is, not persistent) object is auto-expunged from an owning :class:`.Session` only when it is de-associated from *all* parents that specify a ``delete-orphan`` cascade towards this mapper. The new default behavior is that the object is auto-expunged when it is de-associated with *any* of its parents that specify ``delete-orphan`` cascade. This behavior is more consistent with that of a persistent object, and allows behavior to be consistent in more scenarios independently of whether or not an orphan object has been flushed yet or not. See the change note and example at :ref:`legacy_is_orphan_addition` for more detail on this change. :param non_primary: Specify that this :class:`_orm.Mapper` is in addition to the "primary" mapper, that is, the one used for persistence. The :class:`_orm.Mapper` created here may be used for ad-hoc mapping of the class to an alternate selectable, for loading only. .. seealso:: :ref:`relationship_aliased_class` - the new pattern that removes the need for the :paramref:`_orm.Mapper.non_primary` flag. :param passive_deletes: Indicates DELETE behavior of foreign key columns when a joined-table inheritance entity is being deleted. Defaults to ``False`` for a base mapper; for an inheriting mapper, defaults to ``False`` unless the value is set to ``True`` on the superclass mapper. When ``True``, it is assumed that ON DELETE CASCADE is configured on the foreign key relationships that link this mapper's table to its superclass table, so that when the unit of work attempts to delete the entity, it need only emit a DELETE statement for the superclass table, and not this table. When ``False``, a DELETE statement is emitted for this mapper's table individually. If the primary key attributes local to this table are unloaded, then a SELECT must be emitted in order to validate these attributes; note that the primary key columns of a joined-table subclass are not part of the "primary key" of the object as a whole. Note that a value of ``True`` is **always** forced onto the subclass mappers; that is, it's not possible for a superclass to specify passive_deletes without this taking effect for all subclass mappers. .. seealso:: :ref:`passive_deletes` - description of similar feature as used with :func:`_orm.relationship` :paramref:`.mapper.passive_updates` - supporting ON UPDATE CASCADE for joined-table inheritance mappers :param passive_updates: Indicates UPDATE behavior of foreign key columns when a primary key column changes on a joined-table inheritance mapping. Defaults to ``True``. When True, it is assumed that ON UPDATE CASCADE is configured on the foreign key in the database, and that the database will handle propagation of an UPDATE from a source column to dependent columns on joined-table rows. When False, it is assumed that the database does not enforce referential integrity and will not be issuing its own CASCADE operation for an update. The unit of work process will emit an UPDATE statement for the dependent columns during a primary key change. .. seealso:: :ref:`passive_updates` - description of a similar feature as used with :func:`_orm.relationship` :paramref:`.mapper.passive_deletes` - supporting ON DELETE CASCADE for joined-table inheritance mappers :param polymorphic_load: Specifies "polymorphic loading" behavior for a subclass in an inheritance hierarchy (joined and single table inheritance only). Valid values are: * "'inline'" - specifies this class should be part of the "with_polymorphic" mappers, e.g. its columns will be included in a SELECT query against the base. * "'selectin'" - specifies that when instances of this class are loaded, an additional SELECT will be emitted to retrieve the columns specific to this subclass. The SELECT uses IN to fetch multiple subclasses at once. .. versionadded:: 1.2 .. seealso:: :ref:`with_polymorphic_mapper_config` :ref:`polymorphic_selectin` :param polymorphic_on: Specifies the column, attribute, or SQL expression used to determine the target class for an incoming row, when inheriting classes are present. May be specified as a string attribute name, or as a SQL expression such as a :class:`_schema.Column` or in a Declarative mapping a :func:`_orm.mapped_column` object. It is typically expected that the SQL expression corresponds to a column in the base-most mapped :class:`.Table`:: class Employee(Base): __tablename__ = "employee" id: Mapped[int] = mapped_column(primary_key=True) discriminator: Mapped[str] = mapped_column(String(50)) __mapper_args__ = { "polymorphic_on": discriminator, "polymorphic_identity": "employee", } It may also be specified as a SQL expression, as in this example where we use the :func:`.case` construct to provide a conditional approach:: class Employee(Base): __tablename__ = "employee" id: Mapped[int] = mapped_column(primary_key=True) discriminator: Mapped[str] = mapped_column(String(50)) __mapper_args__ = { "polymorphic_on": case( (discriminator == "EN", "engineer"), (discriminator == "MA", "manager"), else_="employee", ), "polymorphic_identity": "employee", } It may also refer to any attribute using its string name, which is of particular use when using annotated column configurations:: class Employee(Base): __tablename__ = "employee" id: Mapped[int] = mapped_column(primary_key=True) discriminator: Mapped[str] __mapper_args__ = { "polymorphic_on": "discriminator", "polymorphic_identity": "employee", } When setting ``polymorphic_on`` to reference an attribute or expression that's not present in the locally mapped :class:`_schema.Table`, yet the value of the discriminator should be persisted to the database, the value of the discriminator is not automatically set on new instances; this must be handled by the user, either through manual means or via event listeners. A typical approach to establishing such a listener looks like:: from sqlalchemy import event from sqlalchemy.orm import object_mapper @event.listens_for(Employee, "init", propagate=True) def set_identity(instance, *arg, **kw): mapper = object_mapper(instance) instance.discriminator = mapper.polymorphic_identity Where above, we assign the value of ``polymorphic_identity`` for the mapped class to the ``discriminator`` attribute, thus persisting the value to the ``discriminator`` column in the database. .. warning:: Currently, **only one discriminator column may be set**, typically on the base-most class in the hierarchy. "Cascading" polymorphic columns are not yet supported. .. seealso:: :ref:`inheritance_toplevel` :param polymorphic_identity: Specifies the value which identifies this particular class as returned by the column expression referred to by the :paramref:`_orm.Mapper.polymorphic_on` setting. As rows are received, the value corresponding to the :paramref:`_orm.Mapper.polymorphic_on` column expression is compared to this value, indicating which subclass should be used for the newly reconstructed object. .. seealso:: :ref:`inheritance_toplevel` :param properties: A dictionary mapping the string names of object attributes to :class:`.MapperProperty` instances, which define the persistence behavior of that attribute. Note that :class:`_schema.Column` objects present in the mapped :class:`_schema.Table` are automatically placed into ``ColumnProperty`` instances upon mapping, unless overridden. When using Declarative, this argument is passed automatically, based on all those :class:`.MapperProperty` instances declared in the declared class body. .. seealso:: :ref:`orm_mapping_properties` - in the :ref:`orm_mapping_classes_toplevel` :param primary_key: A list of :class:`_schema.Column` objects, or alternatively string names of attribute names which refer to :class:`_schema.Column`, which define the primary key to be used against this mapper's selectable unit. This is normally simply the primary key of the ``local_table``, but can be overridden here. .. versionchanged:: 2.0.2 :paramref:`_orm.Mapper.primary_key` arguments may be indicated as string attribute names as well. .. seealso:: :ref:`mapper_primary_key` - background and example use :param version_id_col: A :class:`_schema.Column` that will be used to keep a running version id of rows in the table. This is used to detect concurrent updates or the presence of stale data in a flush. The methodology is to detect if an UPDATE statement does not match the last known version id, a :class:`~sqlalchemy.orm.exc.StaleDataError` exception is thrown. By default, the column must be of :class:`.Integer` type, unless ``version_id_generator`` specifies an alternative version generator. .. seealso:: :ref:`mapper_version_counter` - discussion of version counting and rationale. :param version_id_generator: Define how new version ids should be generated. Defaults to ``None``, which indicates that a simple integer counting scheme be employed. To provide a custom versioning scheme, provide a callable function of the form:: def generate_version(version): return next_version Alternatively, server-side versioning functions such as triggers, or programmatic versioning schemes outside of the version id generator may be used, by specifying the value ``False``. Please see :ref:`server_side_version_counter` for a discussion of important points when using this option. .. seealso:: :ref:`custom_version_counter` :ref:`server_side_version_counter` :param with_polymorphic: A tuple in the form ``(<classes>, <selectable>)`` indicating the default style of "polymorphic" loading, that is, which tables are queried at once. <classes> is any single or list of mappers and/or classes indicating the inherited classes that should be loaded at once. The special value ``'*'`` may be used to indicate all descending classes should be loaded immediately. The second tuple argument <selectable> indicates a selectable that will be used to query for multiple classes. The :paramref:`_orm.Mapper.polymorphic_load` parameter may be preferable over the use of :paramref:`_orm.Mapper.with_polymorphic` in modern mappings to indicate a per-subclass technique of indicating polymorphic loading styles. .. seealso:: :ref:`with_polymorphic_mapper_config` r| z%s.%sNr� ��argnameFc S s | pdd S )Nr r rk )�xrk rk rl �<lambda>� � z!Mapper.__init__.<locals>.<lambda>Tr} )Zdisable_inspectionr� zMapper[zM(None)] has None for a primary table argument and does not specify 'inherits'r� rN Z constructed)Kr Zassert_arg_type�typer| � __module__�__name__� _sort_key�to_list�_primary_key_argumentrw r� � isinstancer* Zversion_id_propr� r8 �expectr; ZColumnArgumentOrKeyRoler� r� �singler# r �StrictFromClauseRoler} �sa_exc� ArgumentErrorZ OnClauseRoler� r� �dict�_init_properties�_delete_orphansr� r� r� r� r� �_dependency_processors� EMPTY_DICT� validatorsr� r� r� Z_clause_adapter�_requires_row_aliasing�_inherits_equated_pairs�_memoized_valuesr� �_reconstructorr� r� �_set_with_polymorphicr� r� �polymorphic_map�to_setr� r� ri r rt Z_eventsZ_new_mapper_instance�_configure_inheritance� _configure_class_instrumentation�_configure_properties� _configure_polymorphic_setter�_configure_pksrJ Z_flag_new_mapper�_log�_expire_memoizationsZafter_mapper_constructed) �selfr| r} r r~ rw r r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� rk rk rl �__init__� s� � ��� � � � ��� � (zMapper.__init__c C s. | j dkr$|jsdS || jv o"|jS | j S d S )Nrx F)r� Zimplicit_returning�_server_default_col_keysZ insert_executemany_returning)r� �dialect�tablerk rk rl �_prefer_eager_defaultsi s �z Mapper._prefer_eager_defaultsc C s | fS rh rk )r� Zanon_mapZ bindparamsrk rk rl �_gen_cache_keyu s zMapper._gen_cache_keyrI rJ � Mapper[_O]rf c C s | S )z<Part of the inspection API. Returns self. rk �r� rk rk rl �mapper� s z Mapper.mapperc C s | j S )zDPart of the inspection API. Returns self.class\_. �r| r� rk rk rl �entity� s z Mapper.entityr| �_identity_classzList[Tuple[str, Type[Any]]]r� zList[DependencyProcessor]r� z Dict[Any, Callable[[], Any]]r� z util.WeakSequence[Mapper[Any]]�_inheriting_mapperszSet[TableClause]� _all_tables�_polymorphic_attr_keyz/Dict[FromClause, OrderedSet[ColumnClause[Any]]]� _pks_by_tablez0Dict[FromClause, OrderedSet[ColumnElement[Any]]]�_cols_by_tablez*util.OrderedDict[str, MapperProperty[Any]]�_propsz Dict[str, MapperProperty[Any]]r� �_ColumnMapping�_columntopropertyz-Optional[Callable[[InstanceState[_O]], None]]�_set_polymorphic_identityzHOptional[Callable[[Mapper[_O], InstanceState[_O], _InstanceDict], None]]� _validate_polymorphic_identityzSequence[TableClause]�tablesz3util.immutabledict[str, Tuple[str, Dict[str, Any]]]r� r� r� z Optional[ColumnElement[Any]]r� zcOptional[Tuple[Union[Literal['*'], Sequence[Union[Mapper[Any], Type[Any]]]], Optional[FromClause]]]r� r� r\ r} �persist_selectablezOptional[Mapper[Any]]r z Optional[ColumnElement[bool]]r� � configuredr� zTuple[Column[Any], ...]r~ zClassManager[_O]� class_managerr� rw z!Optional[KeyedColumnElement[Any]]r� zDict[Any, Mapper[Any]]r� r� rd � base_mapperz*ReadOnlyColumnCollection[str, Column[Any]]�columns�crv zUse .persist_selectablec C s | j S rh )r� r� rk rk rl � mapped_table� s zMapper.mapped_tablerP c C s t �| �S rh )r. Z per_mapperr� rk rk rl �_path_registry� s zMapper._path_registryc C s@ t �� | _| j�r�t| j| jj�s>t�d| jj| jjjf ��| j � | jj � | j | jj kr�| j rhdpjd}t�d|| jj|f ��| j r�| jj | _ �n�| j| jju�r| jr�| j| _ | �� D ]}|jdur�d|_q��q | jdu �r�zt�| jj| j�| _W n� tj�yd } zL| jjdu�s"J �| jdu�s2J �t�d| jjj| jjf �|�W Y d}~npd}~0 tj�y� } zL| jjdu�s�J �| jdu�s�J �t�d| jjj| jjf �|�W Y d}~n d}~0 0 | jj du�s�J �t�| jj | j| j�| _ t �| j �}tj | j j |d �| _ n| j| _ | j du �rj| j| _!| j"�s�| jj#jdu�r�t �$| � d | jj#j� d �� n | j�r|| j| _!n | jj!| _!| j%du �r�| jj%| _%| jj&| _&n:| jj%du�r�| j%| jj%u�r�t �$d | j%j| jj%jf � | jj'| _'| jj(| _(| jj�)| � | jj#| _#| jj*| _*| jj+�p&| j+| _+| jj,| _,| j du�r|| j | j'v �rpt �$d | j | j'| j | | j f � | | j'| j < | j-�r�| j�r�t�d��| j-dk�r�| j�.| � n*| j-dk�r�n | j-du�r"t�d| j- ��nFt/� | _,| | _#| jdu�s�J �| j| _ | j du�r| | j'| j < | j| _!| j du �r<t�d| ��dS )zXConfigure settings related to inheriting and/or inherited mappers being present.z%Class '%s' does not inherit from '%s'Zprimaryz non-primaryzHInheritance of %s mapper for class '%s' is only allowed from a %s mapperNTa7 Can't determine the inherit condition between inherited table '%s' and inheriting table '%s'; tables have no foreign key relationships established. Please ensure the inheriting table has a foreign key relationship to the inherited table, or provide an 'on clause' using the 'inherit_condition' mapper argument.z�Can't determine the inherit condition between inherited table '%s' and inheriting table '%s'; tables have more than one foreign key relationship established. Please specify the 'on clause' using the 'inherit_condition' mapper argument.)Zconsider_as_foreign_keysz| does not indicate a 'polymorphic_identity', yet is part of an inheritance hierarchy that has a 'polymorphic_on' column of 'a' '. If this is an intermediary class that should not be instantiated, the class may either be left unmapped, or may include the 'polymorphic_abstract=True' parameter in its Mapper arguments. To leave the class unmapped when using Declarative, set the '__abstract__ = True' attribute on the class.z�Inheriting version_id_col '%s' does not match inherited version_id_col '%s' and will not automatically populate the inherited versioning column. version_id_col should only be specified on the base-most mapper that includes versioning.z�Reassigning polymorphic association for identity %r from %r to %r: Check for duplicate use of %r as value for polymorphic_identity.zKpolymorphic_load is not currently supported with concrete table inheritance�inline�selectinz)unknown argument for polymorphic_load: %rz9Mapper '%s' does not have a persist_selectable specified.)0r � WeakSequencer� r � issubclassr| r� r� r� rt �_updaterw r� r� r} r� �iterate_to_rootr� r� r� �sql_utilZjoin_conditionZNoForeignKeysError� descriptionZAmbiguousForeignKeysErrorr4 �joinr� r� Zcriterion_as_pairsZonclauser� r� r� r� r� �warnr� r� r� r� �appendr� r� r� r� � _add_with_polymorphic_subclassrj )r� �npr� ZnfeZafeZfksrk rk rl r� � s �� �� � ������� � � � � ��� � ���� � ��� � �� ��z Mapper._configure_inheritance�None)r� rg c C s� |dkrd| _ n\t|ttf�rLt|d tttf�r@td|�| _ ql|d f| _ n |d urft�d|����nd | _ | j r�| j d d ur�| j d tj t j | j d dd�f| _ | j r�| � � d S ) Nrc )rc Nr z�Tuple[ Union[ Literal["*"], Sequence[Union["Mapper[Any]", Type[Any]]], ], Optional["FromClause"], ]z&Invalid setting for with_polymorphic: r T�Z allow_select)r� r� �tuple�list�strr r� r� r8 r� r; r� r� r� )r� r� rk rk rl r� m s0 � ��� z Mapper._set_with_polymorphicc C sd |j }| jd u r | �|f� nB| jd dkr`t| jd t�s@J �| �| jd |f | jd f� d S )Nr rc r )r| r� r� r� r� )r� r� Zsubclrk rk rl r� � s �z%Mapper._add_with_polymorphic_subclassc C s� | j s J �| jrJ �t|t�s"J �|| _| jj�| j� | jj| _| �� D ]}|jdurJd|_qJ| jj | _ | j D ]}| jj |_ qp| jj � | � | jj| _| jj| _|j�� D ]2\}}|| jvr�| j||ddd�s�| �||d� q�dS )z�Set the given :class:`_orm.Mapper` as the 'inherits' for this :class:`_orm.Mapper`, assuming this :class:`_orm.Mapper` is concrete and does not already have an inherits.NTF��local�column)r� r r� rs r� �updater� r� r� r� �self_and_descendantsr� r� r� r� r� r� �items�_should_exclude�_adapt_inherited_property)r� r� �mp�key�proprk rk rl �_set_concrete_base� s( �zMapper._set_concrete_basec C s || _ | �d� d S )NT)r� r� )r� r� rk rk rl �_set_polymorphic_on� s zMapper._set_polymorphic_onc C s� t �| j�}| jrb|r |js,t�d| j ��|| _|jdus@J �|j| _|j j | _ |j� | � dS |du sp|jszt�d��| j � | | j� tj| j| t�tj| �dd�}|| _|jdus�J �|j| _|j du r�dS tj|dtdd� t�| j�D ]�\}}|dk�r&t|d ��r&|j}t|d ��r&|j}t|�r�t|d ��rT|| _ tj|d t dd� q�t|d �r�|j }|j D ]:}|| j v �r�t�d|| f ��| j �!|||fi�| _ �qjq�dS )a� If this mapper is to be a primary mapper (i.e. the non_primary flag is not set), associate this Mapper with the given class and entity name. Subsequent calls to ``class_mapper()`` for the ``class_`` / ``entity`` name combination will return this mapper. Also decorate the `__init__` method on the mapped class to include optional auto-session attachment logic. ztClass %s has no primary mapper configured. Configure a primary mapper first before setting up a non primary Mapper.Nz�The _mapper() function and Mapper() constructor may not be invoked directly outside of a declarative registry. Please use the sqlalchemy.orm.registry.map_imperatively() function for a classical mapping.T)r� Zexpired_attribute_loader�finalize�init)�rawr� �_sa_original_init�__func__�__sa_reconstructor__�load�__sa_validators__zJA validation function for mapped attribute %r on mapper %s already exists.)"r Zopt_manager_of_classr| rw Z is_mappedr� �InvalidRequestErrorr� rJ r� r� Z_add_non_primary_mapperrt �instrument_classr Zregister_classr �partialr Zload_scalar_attributesr0 �listen�_event_on_initZiterate_attributes�hasattrr� r� �callabler� �_event_on_load�__sa_validation_opts__r r� �union)r� �managerr� �methodZvalidation_opts�namerk rk rl r� � sl �� ��� �� �z'Mapper._configure_class_instrumentationc C s$ d| _ d| _d| _| j�dd � d S )NTru )r� �_ready_for_configure�_dispose_called�__dict__�popr� rk rk rl �_set_dispose_flags s zMapper._set_dispose_flagsr� z Column[Any])r� r� rg c C s� z| j | }W n> tyL } z&t�d|� d|� d��|�W Y d }~n d }~0 0 z |j}W n> ty� } z&t�d|� d|� d��|�W Y d }~n d }~0 0 t|t�s�t�d|� d|� d���|S )NzCan't determine z column 'z(' - no attribute is mapped to this name.z4'; property does not refer to a single mapped Column)r� �KeyErrorr� r� r9 �AttributeErrorr� r@ )r� r� r� r� �err�exprZaerk rk rl �_str_arg_to_mapped_col! s* �� �� �z Mapper._str_arg_to_mapped_colc sF t �� j�� _� j�dd� � jD �� i � _i � _t� t dd� � j D �� �}t� dd� |D ��}t � j�� � jg�D ]F}|jr�|�|j�r�t�|j��|�� j|< t�|j��|�� j|< qt� jr� fdd�dd� � jD �D �}nd }|�r(|D ]4}|j� jv�rt�� � j|j< � j|j �|� q�nl� j� jv�sLt� j� j �dk�rdt�d � � jjf ��n0� j� jv�r�t � jt j ��r�t� d � jj � � j �r�� j!�s�� j�s�� j j� _nt|�r�d d� � fd d�|D �D �}nt j"� j� j d d�}t|�dk�rt�d � � jjf ��t#|�� _� �$d|� � fdd�� j D �� _%d S )Nc s s | ] }|V qd S rh rk )�.0�trk rk rl � <genexpr>; r� z(Mapper._configure_pks.<locals>.<genexpr>c S s g | ] }|j �qS rk �� proxy_set�r �colrk rk rl � <listcomp>A r� z)Mapper._configure_pks.<locals>.<listcomp>c s s | ]}|j r|V qd S rh �r~ �r r� rk rk rl r D r� c s& g | ] }t |t�r � �d |�n|�qS r" )r� r� r r# r� rk rl r! U s ��c s s | ]}t jtj|d d�V qdS )r~ r� N)r8 r� r; ZDDLConstraintColumnRole)r Z coerce_pkrk rk rl r [ s ��r zJMapper %s could not assemble any primary key columns for mapped table '%s'zlCould not assemble any primary keys for locally mapped table '%s' - no rows will be persisted in this Table.c S s g | ]\}}|d ur|n|�qS rh rk )r �ccr� rk rk rl r! � s �c 3 s | ]}� j �|�|fV qd S rh )r� �corresponding_columnr# r� rk rl r � s �T)Zignore_nonexistent_tablesz"Identified primary key columns: %sc s< h | ]4}� j | � jvrt|d �r.|j� jvr� j | �qS �r� )r� �_identity_key_propsr r� r� r r� rk rl � <setcomp>� s �z(Mapper._configure_pks.<locals>.<setcomp>)&r� � find_tablesr� r� r� r� r� r� r Z column_setr r� rj r r~ � issupersetZordered_column_set� intersectionr� r� r� r] �add�lenr� r� r� r} r� r3 rA r� r r� Zreduce_columnsr� r� �_readonly_props)r� Zall_cols�pk_colsZfcZcoerced_pk_arg�kr~ rk r� rl r� 8 s� ��� � �� �� �������� �� � �� �zMapper._configure_pksc C s t �� | _| _t�� | _t| �| _i }i }| j r�| j � � D ]z\}}t |t �s\| � ||�}n|}d}t |tj�r�|jD ]*}| jj�|�rvd}|||< ||f||< qv|r<| j||dd� q<| j�rH| jj� � D ]z\}}| j||dd d�r�q�|�|�} | �r.| j||d| d�} | ||< | jD ]} || f|| < �qq�|| jvr�| �||d� q�| jjD ]�} | |v �r�|| \}} | j|| dd� �qPn| | jv �r��qP| j�p�d| j }| j| j|| jj�| �| d��rƐqP| �� D ] }| |jv �r�|j| j}�q�| j|| ddd� �qPd S )NTF)r� r� )� warn_only� incoming_prop� �r� � setparent) �sql_baseZColumnCollectionr� r� r � OrderedDictr� r� r� r� r� r� r* �_make_prop_from_columnr rQ r} Zcontains_column�_configure_propertyr r� �get�%_reconcile_prop_with_incoming_columnsr� r� r� r� r� )r� Z explicit_col_props_by_columnZexplicit_col_props_by_keyr� �prop_argZpossible_col_propZ_map_as_property_nowZ given_colZinherited_propr2 �new_propZinc_colr� r� Z column_keyr� rk rk rl r� � s� � � � � � � � �z Mapper._configure_propertiesc s� d}d� | j du�r�d}t| j t�rnz| j| j | _ W n6 tyl } z t�d| j �|�W Y d}~n d}~0 0 | j | jv r�| j| j }�nt| j t�r�t| j t j �s�t�d��| j }n�| j � | j �}|du �r.d}d}| j }t|t j��r2| jdu �s | jd du �s | jd � |�du �r2t�d|j ��nd}t|dd�}|�rf| �||d|��r|t�d | ��n|�d � | _ }|j}t j ||d �}| j|||dd � |jd | _ |j� n|| �� D ]r}|j du�r�| j |j u �r�|j | _ n| j � |j �| _ | j du�r|j| _|j| _|j| _n d| _d| _ dS �q�| j �rJ| j du �rJt�d��|�r|� fdd�} � | _� fdd�} | | _| | _n d| _d| _dS )a� Configure an attribute on the mapper representing the 'polymorphic_on' column, if applicable, and not already generated by _configure_properties (which is typical). Also create a setter function which will assign this attribute to the value of the 'polymorphic_identity' upon instance construction, also if applicable. This routine will run when an instance is created. FNTzPCan't determine polymorphic_on value '%s' - no attribute is mapped to this name.zUOnly direct column-mapped property or SQL expression can be passed for polymorphic_onr zkCould not map polymorphic_on column '%s' to the mapped table - polymorphic loads will not function properlyr� z6Cannot exclude or override the discriminator column %rZ_sa_polymorphic_on)Z _instrumentr4 r z�The Mapper.polymorphic_abstract parameter may only be used on a mapper hierarchy which includes the Mapper.polymorphic_on parameter at the base of the hierarchy.c sR | j }| jjj}|d u r8| jjjr8t�d| jj� d���| �� ��| ||d � d S )Nz Can't instantiate class for z,; mapper is marked polymorphic_abstract=True) r� r r� r� r� r� r Zget_implrj )�state�dict_r� �Zpolymorphic_keyrk rl r� � s ���� �zGMapper._configure_polymorphic_setter.<locals>._set_polymorphic_identityc s2 � |v r.|� | j vr.t�dt|�|� f� d S )NznFlushing object %s with incompatible polymorphic identity %r; the object may not refresh and/or load correctly)�"_acceptable_polymorphic_identitiesr Z warn_limitedr& )r� r> r? r@ rk rl r� � s ����zLMapper._configure_polymorphic_setter.<locals>._validate_polymorphic_identity) r� r� r� r� r r� r� r� r* r rQ r� r% r3 r@ r� r r� �getattrr� �labelr� r9 r� r� r� r� r� r� ) r� r� �setterr r� r Z instrumentr� r� r� r� rk r@ rl r� + s� ��� ��� � ����� �� �� ��� � �z$Mapper._configure_polymorphic_setterc C s | j d ur| j| j S d S d S rh )r� r� r� rk rk rl �_version_id_prop� s zMapper._version_id_propc C sF t � }t| g�}|rB|�� }|j| ju r|�|j� |�|j� q|S rh )rj r �popleftr� r, r� �extendr� )r� Z identities�stack�itemrk rk rl rA � s z)Mapper._acceptable_polymorphic_identitiesc C s t | j�� �S rh )� frozensetr� �valuesr� rk rk rl � _prop_set s zMapper._prop_setz sqlalchemy.orm.descriptor_propsc C st t jj}| js"| j||ddd� nN|| jvrp| j�||�}||u sZt|t j �rp|j |j u rp| j||� � |dd� d S )NFr4 T)r � preloaded�orm_descriptor_propsr� r9 r� r� �_get_class_attr_mror� r ZInstrumentedAttributeZ _parententity�parent�ConcreteInheritedProperty)r� r� r� r� �descriptor_propsZimplementing_attributerk rk rl r� s( ��� ��z Mapper._adapt_inherited_property)r� r5 �warn_for_existingz3Union[KeyedColumnElement[Any], MapperProperty[Any]]ra )r� r< r� r5 rS rg c C s� t jj}| �d||jj� t|t�s2| �||�}n|}t|t j ��r�| j � |j d �}|d u r�| jr�| g} | j�� D ]T} | j� |j d �}|d ur�| D ]} | j �|� q�| j � |j d �} q�| �| � qt|d u �r|j d }t| d��rPt|d��r|j| jv�rP| j�|� n>t| d��rP|j| jv �rP|| j|j v�rP| j|j �|� t|d��sz|| ju �pv|j d | ju |_t|tj��r�| |_ |_ | j �||� |j D ] }|j D ]} || j | < �q��q�t |d|�|k�rt �!d| j"j� d |j � d |�d |j �d |j �d � � ||_ |�r&|�#| |� || j$v �rht | j$| d d��rh| j$| j%} t&�'d| ||| f ��|| j$v �r�t| j$| |j(��s�t||j)��s�|�r�t �*d| j"j� d |� d| � d�d� | j$| }| j+�,|d � nf|�r@| j"j-�.|d �d u�r@t||j)��s@t| j$�.|d �|j(��s@t �*d| j"j� d |� d| � d�d� || j$|< | j/�s\|�0| � | j1D ]}|�2|||� �qb|�r�|�3� |�4| � | j5�r�| �6� |S )Nz_configure_property(%s, %s)r r. r� r� � _is_polymorphic_discriminatorr� zORM mapped property �.z being assigned to attribute z& is already associated with attribute z+. The attribute will be de-associated from �_mapped_by_synonymFzpCan't call map_column=True for synonym %r=%r, a ColumnProperty already exists keyed to the name %r for column %rzUser-placed attribute z on z� is replacing an existing ORM-mapped attribute. Behavior is not fully defined in this case. This use is deprecated and will raise an error in a future releasez2.0z� is replacing an existing class-bound attribute of the same name. Behavior is not fully defined in this case. This use is deprecated and will raise an error in a future release)7r rM rN r� � __class__r� r� r* �_property_from_columnr rQ r� r% r� r r� r} �_refresh_for_new_columnr� r r� r� r. r, r� rT r9 ZLabelr� Z _tq_key_labelr r� rB r� r| Z set_parentr� rV r� r� rQ rM Zwarn_deprecatedr� r r r: rw r r� r� r� �post_instrument_classr� r� )r� r� r< r� r5 rS rR r� r �path�m�m2Z proxy_col�synZoldpropr� rk rk rl r9 ( s� � �� � �� �� � ���� � �� � �� ��� �� � �� �� zMapper._configure_propertyzAUnion[Sequence[KeyedColumnElement[Any]], KeyedColumnElement[Any]]zColumnProperty[Any])r� r� rg c C s� t �|�}g }|D ]j}| j�|�}|d u rr| j�|�}|d urJ| j�|� | j�|�}|d u rrt�d|| |f ��|�|� qt j |� S )Nz�When configuring property '%s' on %s, column '%s' is not represented in the mapper's table. Use the `column_property()` function to force this column to be mapped as a read-only attribute.) r r� r� r% r} rY r� r� r� r rQ )r� r� r� r� Z mapped_columnr� Zmcrk rk rl r8 � s" �� z Mapper._make_prop_from_columnz Optional[ColumnProperty[Any]])r� � existing_propr1 r2 � single_columnrg c C s |r| j st|tj�s|S |jd }|r6||jv r6|S |d u r^|d usJJ �|}|jd |f}n$|d u sjJ �|jd }||jd f}| jr�|| jvr�|�|�s�|| jur�|| jur�d|jd ||f } |r�t� | � n t � | ��|� � } | j� d|� | �d|� | S )Nr z�Implicitly combining column %s with column %s under attribute '%s'. Please configure one or more attributes for these same-named columns explicitly.���zAinserting column to existing list in properties.ColumnProperty %s)r� r� r rQ r� r� Zshares_lineager� r r� r� r �copy�insertr� ) r� r� r_ r1 r2 r` Zexisting_columnZincoming_columnZequated_pair_key�msgr= rk rk rl r; � sV � � ����� ��� �z,Mapper._reconcile_prop_with_incoming_columnszKeyedColumnElement[Any]c C st t jj}| j�|�}t|tj�r8| j||||j | ud�S |du sLt||j �rX| � ||�S t � d|| |j|f ��dS )zrgenerate/update a :class:`.ColumnProperty` given a :class:`_schema.Column` or other SQL expression object.)r` r1 Na� WARNING: when configuring property '%s' on %s, column '%s' conflicts with property '%r'. To resolve this, map the column to the class under a different name in the 'properties' dictionary. Or, to remove all awareness of the column entirely (including its availability as a foreign key), use the 'include_properties' or 'exclude_properties' mapper arguments to control specifically which table columns get mapped.)r rM rN r� r: r� r rQ r; rP rQ r8 r� r� r� )r� r� r� rR r� rk rk rl rX 4 s$ � � ��z Mapper._property_from_columnz�This warning originated from the `configure_mappers()` process, which was invoked automatically in response to a user-initiated operation.c C s | j jrt| j hdd� d S )NT��cascade)rJ � _new_mappers�_configure_registriesr� rk rk rl �_check_configureY s zMapper._check_configurec C st | � d� dd� | j�� D �}|D ]<\}}| � d|� |j| u rN|jsN|�� |jr"|�| � q"| � d� d| _dS )z�Call the ``init()`` method on all ``MapperProperties`` attached to this mapper. This is a deferred configuration step which is intended to execute once all mappers have been constructed. z$_post_configure_properties() startedc S s g | ]\}}||f�qS rk rk )r r� r� rk rk rl r! m r� z5Mapper._post_configure_properties.<locals>.<listcomp>zinitialize prop %sz%_post_configure_properties() completeTN) r� r� r� rP Z_configure_startedr� Z_configure_finishedrZ r� )r� �lr� r� rk rk rl �_post_configure_propertiesc s z!Mapper._post_configure_propertiesc C s" |� � D ]\}}| �||� qdS )z^Add the given dictionary of properties to this mapper, using `add_property`. N)r� � add_property)r� Zdict_of_propertiesr� �valuerk rk rl �add_propertiesz s zMapper.add_propertiesz'Union[Column[Any], MapperProperty[Any]])r� r� rg c C s0 | j ||| jdd�}t|t�s"J �|| j|< dS )aA Add an individual MapperProperty to this mapper. If the mapper has not been configured yet, just adds the property to the initial properties dictionary sent to the constructor. If this Mapper has already been configured, then the given MapperProperty is configured immediately. T)r� rS N)r9 r� r� r* r� )r� r� r� rk rk rl rl � s �zMapper.add_propertyc C s | � � D ] }|�� qd S rh )r� Z_reset_memoizations�r� r� rk rk rl r� � s zMapper._expire_memoizationsc C s> d| j j d | jd ur | jjp(t| j� | jr4dp6d d S )N�(�|z |non-primaryr3 �))r| r� r} r� r� rw r� rk rk rl � _log_desc� s �� �� � ��zMapper._log_desc)rd �argsrg c G s$ | j jd| g| jf| �R � d S �Nz%s )�logger�infors �r� rd rt rk rk rl r� � s z Mapper._logc G s$ | j jd| g| jf| �R � d S ru )rv �debugrs rx rk rk rl � _log_debug� s zMapper._log_debugc C s dt | �| jjf S )Nz<Mapper at 0x%x; %s>)�idr| r� r� rk rk rl �__repr__� s zMapper.__repr__c C s2 d| j j| jrdpd| jd ur&| jjn| jjf S )NzMapper[%s%s(%s)]z (non-primary)r3 )r| r� rw r} r� r� r� rk rk rl �__str__� s � �zMapper.__str__zInstanceState[_O])r> rg c C st d}| � � D ]T}|jD ]H\}}d}t�|�j|||jd�}| jrL|rL dS | js|s dS qq | jrl|S dS d S )NFT)Z optimistic)r� r� r Zmanager_of_class� has_parentZ has_identityr� )r� r> Zorphan_possibler� r� �clsr~ rk rk rl � _is_orphan� s � zMapper._is_orphan)r� rg c C s || j v S rh )r� �r� r� rk rk rl � has_property� s zMapper.has_property)r� �_configure_mappersrg c C s\ |r | � � z | j| W S tyV } z&t�d| � d|� d��|�W Y d}~n d}~0 0 dS )z6return a MapperProperty associated with the given key.zMapper 'z' has no property 'zw'. If this property was indicated from other mappers or configure events, ensure registry.configure() has been called.N)ri r� r r� r )r� r� r� r rk rk rl � get_property� s ��zMapper.get_propertyzColumnElement[_T]zMapperProperty[_T])r� rg c C s | j | S )zkGiven a :class:`_schema.Column` object, return the :class:`.MapperProperty` which maps this column.�r� )r� r� rk rk rl �get_property_by_column� s z Mapper.get_property_by_columnc C s t | j�� �S )z1return an iterator of all MapperProperty objects.)�iterr� rK r� rk rk rl �iterate_properties� s zMapper.iterate_propertieszSequence[Mapper[Any]])�spec� selectablerg c s� |dkrt | j�}nz|r�t� � t�|�D ]J}t|�}|�| �sPt�d|| f ��|du rh� � |� � � q(� � |� q(� fdd�| jD �}ng }|dur�tt j |dd����fdd�|D �}|S ) z�given a with_polymorphic() argument, return the set of mappers it represents. Trims the list of mappers to just those represented within the given selectable, if present. This helps some more legacy-ish mappings. rc z%r does not inherit from %rNc s g | ]}|� v r|�qS rk rk �r r\ )� mapper_setrk rl r! r� z-Mapper._mappers_from_spec.<locals>.<listcomp>T)Zinclude_aliasesc s g | ]}|j � v r|�qS rk )r} r� )r� rk rl r! r� )r� r� rj r r� r" �isar� r r� r� r, r� r) )r� r� r� �mappersr\ rk )r� r� rl �_mappers_from_spec� s* � �zMapper._mappers_from_speczIterable[Mapper[Any]])r� � innerjoinrg c C s\ | j }|D ]L}|| u rq |jr*t�d��q |js |rF|�|j|j�}q |�|j|j�}q |S )z�given a list of mappers (assumed to be within this mapper's inheritance hierarchy), construct an outerjoin amongst those mapper's mapped tables. z^'with_polymorphic()' requires 'selectable' argument when concrete-inheriting mappers are used.) r� r� r� r r� r� r} r� Z outerjoin)r� r� r� Zfrom_objr\ rk rk rl �_selectable_from_mappers s" ���z Mapper._selectable_from_mappersc C sL | j }|d u rdS t|t�s dS |jd upF|jd uoF|jj oF|jj S d S )NFT)r� r� r@ �server_default�defaultZ is_scalarZ is_callable)r� Zvid_colrk rk rl �!_version_id_has_server_side_value1 s �z(Mapper._version_id_has_server_side_valuec C sB | j r:| jr:| jd ur:| j�| | d���dd� | jD ��S d S d S )N)� parententity� parentmapperc S s g | ]}|j s|j�qS rk )r� r� r� rk rk rl r! I s �z2Mapper._single_table_criterion.<locals>.<listcomp>)r� r r� � _annotate�in_r� r� rk rk rl �_single_table_criterionC s ��� z Mapper._single_table_criterionc C s | j ot| j d tj�S )z�return True if with_polymorphic[1] is an aliased fromclause, like a subquery. As of #8168, polymorphic adaption with ORMAdapter is used only if this is present. r )r� r� r9 ZAliasedReturnsRowsr� rk rk rl �#_has_aliased_polymorphic_fromclauseR s �z*Mapper._has_aliased_polymorphic_fromclausec C s | j p| jp| jj p| jjS )a; determine if _MapperEntity or _ORMColumnEntity will need to use polymorphic adaption when setting up a SELECT as well as fetching rows for mapped classes and subclasses against this Mapper. moved here from context.py for #8456 to generalize the ruleset for this condition. )r� r� r� r� rk rk rl � _should_select_with_poly_adapter` s +���z'Mapper._should_select_with_poly_adapterc C s | � � | jsg S | j| j� S rh )ri r� r� r� rk rk rl �_with_polymorphic_mappers� s z Mapper._with_polymorphic_mappersc C s | � � dS )z�This hook is invoked by attribute inspection. E.g. when Query calls: coercions.expect(roles.ColumnsClauseRole, ent, keep_inspect=True) This allows the inspection process run a configure mappers hook. N)ri r� rk rk rl � _post_inspect� s zMapper._post_inspectc C s: | j s | jS | j \}}|d ur"|S | �| �||�d�S d S �NF)r� r� r� r� )r� r� r� rk rk rl � _with_polymorphic_selectable� s �z#Mapper._with_polymorphic_selectablec C s dd� | j �� D �S )Nc S s$ i | ] \}}|t d d� |D ���qS )c s s | ]}|j jr|V qd S rh )r� �should_evaluate_noner rk rk rl r � s zAMapper._insert_cols_evaluating_none.<locals>.<dictcomp>.<genexpr>�rJ �r r� r� rk rk rl � <dictcomp>� s � �z7Mapper._insert_cols_evaluating_none.<locals>.<dictcomp>�r� r� r� rk rk rl � _insert_cols_evaluating_none� s �z#Mapper._insert_cols_evaluating_nonec C s dd� | j �� D �S )Nc S s$ i | ] \}}|t d d� |D ���qS )c s s. | ]&}|j s|js|js|jjs|jV qd S rh )r~ r� r� r� r� r� r rk rk rl r � s �z9Mapper._insert_cols_as_none.<locals>.<dictcomp>.<genexpr>r� r� rk rk rl r� � s � �z/Mapper._insert_cols_as_none.<locals>.<dictcomp>r� r� rk rk rl �_insert_cols_as_none� s �zMapper._insert_cols_as_nonec s � fdd�� j �� D �S )Nc s$ i | ] \}}|� fd d�|D ��qS )c s i | ]}� j | j|�qS rk �r� r� r r� rk rl r� � r� z5Mapper._propkey_to_col.<locals>.<dictcomp>.<dictcomp>rk r� r� rk rl r� � s �z*Mapper._propkey_to_col.<locals>.<dictcomp>r� r� rk r� rl �_propkey_to_col� s �zMapper._propkey_to_colc C s dd� | j �� D �S )Nc S s$ i | ] \}}|t d d� |D ���qS )c S s g | ] }|j �qS rk �r� r rk rk rl r! � r� z7Mapper._pk_keys_by_table.<locals>.<dictcomp>.<listcomp>r� �r r� Zpksrk rk rl r� � s �z,Mapper._pk_keys_by_table.<locals>.<dictcomp>�r� r� r� rk rk rl �_pk_keys_by_table� s �zMapper._pk_keys_by_tablec s � fdd�� j �� D �S )Nc s( i | ] \}}|t � fd d�|D ���qS )c s g | ]}� j | j�qS rk r� r r� rk rl r! � r� z<Mapper._pk_attr_keys_by_table.<locals>.<dictcomp>.<listcomp>r� r� r� rk rl r� � s �z1Mapper._pk_attr_keys_by_table.<locals>.<dictcomp>r� r� rk r� rl �_pk_attr_keys_by_table� s �z Mapper._pk_attr_keys_by_tablez+Mapping[FromClause, FrozenSet[Column[Any]]]c C s dd� | j �� D �S )Nc S s* i | ]"\}}|t d d� td|�D ���qS )c S s, g | ]$}|j d us$|jd ur|jjr|�qS rh )r� r� �is_clause_elementr rk rk rl r! � s �z:Mapper._server_default_cols.<locals>.<dictcomp>.<listcomp>�Iterable[Column[Any]]�rJ r r� rk rk rl r� � s ���z/Mapper._server_default_cols.<locals>.<dictcomp>r� r� rk rk rl �_server_default_cols� s �zMapper._server_default_colsc C s dd� | j �� D �S )Nc S s* i | ]"\}}|t d d� td|�D ���qS )c S s, g | ]$}|j d us$|jd ur|jjr|�qS rh )Zserver_onupdateZonupdater� r rk rk rl r! � s �zCMapper._server_onupdate_default_cols.<locals>.<dictcomp>.<listcomp>r� r� r� rk rk rl r� � s ���z8Mapper._server_onupdate_default_cols.<locals>.<dictcomp>r� r� rk rk rl � _server_onupdate_default_cols� s �z$Mapper._server_onupdate_default_colsz#Mapping[FromClause, FrozenSet[str]]c C s dd� | j �� D �S )Nc S s$ i | ] \}}|t d d� |D ���qS )c s s | ]}|j d ur|j V qd S rh r� r rk rk rl r r� z=Mapper._server_default_col_keys.<locals>.<dictcomp>.<genexpr>r� �r r� �colsrk rk rl r� s �z3Mapper._server_default_col_keys.<locals>.<dictcomp>)r� r� r� rk rk rl r� s �z Mapper._server_default_col_keysc C s dd� | j �� D �S )Nc S s$ i | ] \}}|t d d� |D ���qS )c s s | ]}|j d ur|j V qd S rh r� r rk rk rl r r� zFMapper._server_onupdate_default_col_keys.<locals>.<dictcomp>.<genexpr>r� r� rk rk rl r� s �z<Mapper._server_onupdate_default_col_keys.<locals>.<dictcomp>)r� r� r� rk rk rl �!_server_onupdate_default_col_keys s �z(Mapper._server_onupdate_default_col_keyszSet[str]c st t � }| j� | j�� D ]&\}}|�� fdd�|�� �D �� q| j�� D ]&\}}|�� fdd�|�� �D �� qH|S )Nc 3 s | ]}� | j V qd S rh r� r �Zcol_to_propertyrk rl r ! s �z@Mapper._server_default_plus_onupdate_propkeys.<locals>.<genexpr>c 3 s | ]}� | j V qd S rh r� r r� rk rl r & s �)rj r� r� r� r� r+ r� )r� �resultr� r� rk r� rl �&_server_default_plus_onupdate_propkeys s � � z-Mapper._server_default_plus_onupdate_propkeysc C sT | | | d�}| j | jur<| j�| | | d���d| d��|d< | j�|��d| d��S )N)�entity_namespacer� r� �orm�Zcompile_state_pluginZplugin_subjectZ dml_table)r� r} r� �_set_propagate_attrsr� )r� r rk rk rl �__clause_element__, s � ��� �zMapper.__clause_element__c C s$ t �� �| | | dd���d| d��S )NT)r� r� r� �identity_tokenr� r� )r9 �nullr� r� r� rk rk rl �select_identity_tokenD s �� ��z Mapper.select_identity_tokenc C s | j S )a4 The :class:`_schema.FromClause` construct this :class:`_orm.Mapper` selects from by default. Normally, this is equivalent to :attr:`.persist_selectable`, unless the ``with_polymorphic`` feature is in use, in which case the full "polymorphic" selectable is returned. )r� r� rk rk rl r� U s zMapper.selectablez'Union[Literal[False, None], FromClause]z(Tuple[Sequence[Mapper[Any]], FromClause])r� r� r� rg c C s~ |dvrt jtj|dd�}| jrB|s.| jd }|du rN| jd }n |du rNd }| �||�}|d urj||fS || �||�fS d S )Nr� Tr� r Fr )r8 r� r; r� r� r� r� )r� r� r� r� r� rk rk rl �_with_polymorphic_argsa s � z Mapper._with_polymorphic_argsc C s t | �| j��S rh )r� � _iterate_polymorphic_propertiesr� r� rk rk rl �_polymorphic_propertiesy s ��z Mapper._polymorphic_propertiesc s | j }| j� � fdd�|D �S )Nc s< g | ]4}t |tj�r|jr|jD ]}� r2� j| n|�q qS rk )r� r rQ Z_renders_in_subqueriesr� )r r� r� ��adapterrk rl r! � s �z2Mapper._all_column_expressions.<locals>.<listcomp>)r� �_polymorphic_adapter)r� �poly_propertiesrk r� rl �_all_column_expressions� s �z Mapper._all_column_expressionsrk c C s$ |r| � |�}n| j}dd� |D �S )Nc S s( g | ] }t |tj�r|j|jd f�qS )r )r� r rQ r� r� �r r� rk rk rl r! � s �z-Mapper._columns_plus_keys.<locals>.<listcomp>)r� r� )r� Zpolymorphic_mappersr� rk rk rl �_columns_plus_keys� s ��zMapper._columns_plus_keysz Optional[orm_util.ORMAdapter]c C s* | j r"tjtjj| | j| jdd�S d S d S )NF)r� Z equivalentsZlimit_on_entity)r� �orm_utilrT Z_TraceAdaptRoleZMAPPER_POLYMORPHIC_ADAPTERr� �_equivalent_columnsr� rk rk rl r� � s �zMapper._polymorphic_adapterc c s| |du r| j }|s&| jD ] }|V qnRt�tdd� | g| D �� �D ]2}t|dd�rp| jdu sD|jd | jurpqD|V qDdS )zUReturn an iterator of MapperProperty objects which will render into a SELECT.Nc S s g | ]}t |j��qS rk )r� r� )r r� rk rk rl r! � s �z:Mapper._iterate_polymorphic_properties.<locals>.<listcomp>rT Fr )r� r� r Z unique_listr rB r� r� )r� r� r� rk rk rl r� � s& ��� ��z&Mapper._iterate_polymorphic_propertiesz,util.ReadOnlyProperties[MapperProperty[Any]]c C s | � � t�| j�S )ai A namespace of all :class:`.MapperProperty` objects associated this mapper. This is an object that provides each property based on its key name. For instance, the mapper for a ``User`` class which has ``User.name`` attribute would provide ``mapper.attrs.name``, which would be the :class:`.ColumnProperty` representing the ``name`` column. The namespace object can also be iterated, which would yield each :class:`.MapperProperty`. :class:`_orm.Mapper` has several pre-filtered views of this attribute which limit the types of properties returned, including :attr:`.synonyms`, :attr:`.column_attrs`, :attr:`.relationships`, and :attr:`.composites`. .. warning:: The :attr:`_orm.Mapper.attrs` accessor namespace is an instance of :class:`.OrderedProperties`. This is a dictionary-like object which includes a small number of named methods such as :meth:`.OrderedProperties.items` and :meth:`.OrderedProperties.values`. When accessing attributes dynamically, favor using the dict-access scheme, e.g. ``mapper.attrs[somename]`` over ``getattr(mapper.attrs, somename)`` to avoid name collisions. .. seealso:: :attr:`_orm.Mapper.all_orm_descriptors` )ri r �ReadOnlyPropertiesr� r� rk rk rl �attrs� s #z Mapper.attrsz'util.ReadOnlyProperties[InspectionAttr]c C s t �t| j�� ��S )ay A namespace of all :class:`.InspectionAttr` attributes associated with the mapped class. These attributes are in all cases Python :term:`descriptors` associated with the mapped class or its superclasses. This namespace includes attributes that are mapped to the class as well as attributes declared by extension modules. It includes any Python descriptor type that inherits from :class:`.InspectionAttr`. This includes :class:`.QueryableAttribute`, as well as extension types such as :class:`.hybrid_property`, :class:`.hybrid_method` and :class:`.AssociationProxy`. To distinguish between mapped attributes and extension attributes, the attribute :attr:`.InspectionAttr.extension_type` will refer to a constant that distinguishes between different extension types. The sorting of the attributes is based on the following rules: 1. Iterate through the class and its superclasses in order from subclass to superclass (i.e. iterate through ``cls.__mro__``) 2. For each class, yield the attributes in the order in which they appear in ``__dict__``, with the exception of those in step 3 below. In Python 3.6 and above this ordering will be the same as that of the class' construction, with the exception of attributes that were added after the fact by the application or the mapper. 3. If a certain attribute key is also in the superclass ``__dict__``, then it's included in the iteration for that class, and not the class in which it first appeared. The above process produces an ordering that is deterministic in terms of the order in which attributes were assigned to the class. .. versionchanged:: 1.3.19 ensured deterministic ordering for :meth:`_orm.Mapper.all_orm_descriptors`. When dealing with a :class:`.QueryableAttribute`, the :attr:`.QueryableAttribute.property` attribute refers to the :class:`.MapperProperty` property, which is what you get when referring to the collection of mapped properties via :attr:`_orm.Mapper.attrs`. .. warning:: The :attr:`_orm.Mapper.all_orm_descriptors` accessor namespace is an instance of :class:`.OrderedProperties`. This is a dictionary-like object which includes a small number of named methods such as :meth:`.OrderedProperties.items` and :meth:`.OrderedProperties.values`. When accessing attributes dynamically, favor using the dict-access scheme, e.g. ``mapper.all_orm_descriptors[somename]`` over ``getattr(mapper.all_orm_descriptors, somename)`` to avoid name collisions. .. seealso:: :attr:`_orm.Mapper.attrs` )r r� r� r� Z_all_sqla_attributesr� rk rk rl �all_orm_descriptors� s B �zMapper.all_orm_descriptorszDict[str, str]c s2 t jj� dd� | jD ��� �fdd�| j�� D �S )z~return a dictionary of {syn_attribute_name: pk_attr_name} for all synonyms that refer to primary key columns c S s h | ] }|j �qS rk r� r� rk rk rl r( : r� z&Mapper._pk_synonyms.<locals>.<setcomp>c s0 i | ](\}}t |� j�r|j�v r|j|j�qS rk )r� rM r r� )r r0 r^ �rR Zpk_keysrk rl r� < s �z'Mapper._pk_synonyms.<locals>.<dictcomp>)r rM rN r' r� r� r� rk r� rl � _pk_synonyms1 s �zMapper._pk_synonymsz-util.ReadOnlyProperties[SynonymProperty[Any]]c C s t jj}| �|j�S )z�Return a namespace of all :class:`.Synonym` properties maintained by this :class:`_orm.Mapper`. .. seealso:: :attr:`_orm.Mapper.attrs` - namespace of all :class:`.MapperProperty` objects. )r rM rN �_filter_propertiesrM )r� rR rk rk rl �synonymsC s zMapper.synonymsc C s | j S rh r� r� rk rk rl r� T s zMapper.entity_namespacez,util.ReadOnlyProperties[ColumnProperty[Any]]c C s | � tj�S )a Return a namespace of all :class:`.ColumnProperty` properties maintained by this :class:`_orm.Mapper`. .. seealso:: :attr:`_orm.Mapper.attrs` - namespace of all :class:`.MapperProperty` objects. )r� r rQ r� rk rk rl � column_attrsX s zMapper.column_attrsz sqlalchemy.orm.relationshipsz2util.ReadOnlyProperties[RelationshipProperty[Any]]c C s | � tjjj�S )aD A namespace of all :class:`.Relationship` properties maintained by this :class:`_orm.Mapper`. .. warning:: the :attr:`_orm.Mapper.relationships` accessor namespace is an instance of :class:`.OrderedProperties`. This is a dictionary-like object which includes a small number of named methods such as :meth:`.OrderedProperties.items` and :meth:`.OrderedProperties.values`. When accessing attributes dynamically, favor using the dict-access scheme, e.g. ``mapper.relationships[somename]`` over ``getattr(mapper.relationships, somename)`` to avoid name collisions. .. seealso:: :attr:`_orm.Mapper.attrs` - namespace of all :class:`.MapperProperty` objects. )r� r rM Zorm_relationshipsrR r� rk rk rl � relationshipsf s �zMapper.relationshipsz/util.ReadOnlyProperties[CompositeProperty[Any]]c C s | � tjjj�S )z�Return a namespace of all :class:`.Composite` properties maintained by this :class:`_orm.Mapper`. .. seealso:: :attr:`_orm.Mapper.attrs` - namespace of all :class:`.MapperProperty` objects. )r� r rM rN rL r� rk rk rl � composites� s �zMapper.compositesz Type[_MP]z util.ReadOnlyProperties[_MP])�type_rg c s, | � � t�t�� fdd�| j�� D ���S )Nc 3 s$ | ] \}}t |� �r||fV qd S rh )r� �r r0 �v�r� rk rl r � s z,Mapper._filter_properties.<locals>.<genexpr>)ri r r� r7 r� r� )r� r� rk r� rl r� � s ��zMapper._filter_propertiesc C s4 dd� t | jd�D �}tjdd� |D �� t�|�fS )z�create a "get clause" based on the primary key. this is used by query.get() and many-to-one lazyloads to load this item by primary key. c S s( g | ] \}}|t jd | |jd�f�qS )zpk_%dr� )r4 � bindparamr� )r �idxr~ rk rk rl r! � s ��z&Mapper._get_clause.<locals>.<listcomp>r c S s g | ]\}}||k�qS rk rk r� rk rk rl r! � r� )� enumerater~ r4 �and_r Z column_dict)r� �paramsrk rk rl � _get_clause� s ��zMapper._get_clauserX c s@ i � � fdd�}| j jD ]"}|jdurt�|ji d|i� q� S )aS Create a map of all equivalent columns, based on the determination of column pairs that are equated to one another based on inherit condition. This is designed to work with the queries that util.polymorphic_union comes up with, which often don't include the columns from the base table directly (including the subclass table columns only). The resulting structure is a dictionary of columns mapped to lists of equivalent columns, e.g.:: {tablea.col1: {tableb.col1, tablec.col1}, tablea.col2: {tabled.col2}} c sh | j tjkrd| j� v r*� | j �| j� n| jh� | j< | j� v rV� | j �| j� n| jh� | j< d S rh )�operatorr: �eq�leftr, �right)�binary�r� rk rl � visit_binary� s z0Mapper._equivalent_columns.<locals>.visit_binaryNr� )r� r� r� r= �traverse)r� r� r� rk r� rl r� � s �zMapper._equivalent_columns)� assigned_name�objrg c C s& t |ttjtjf�rdS || jvS d S r� )r� r' r rO r9 r[ �_dataclass_fields)r� r� r� rk rk rl �_is_userland_descriptor� s ��z Mapper._is_userland_descriptorc C s dd� t �| j�D �S )Nc S s g | ] }|j �qS rk )r )r �frk rk rl r! � r� z,Mapper._dataclass_fields.<locals>.<listcomp>)r Zdataclass_fieldsr| r� rk rk rl r� � s zMapper._dataclass_fieldsc C s� |durt �|�rdS |rH| jj�|d�durn| �|| jj| �rndS n&| j�|d�}|durn| �||�rndS | jdur�|| jvr�|du s�|| jvr�| � d| � dS | j dur�|| j v s�|dur�|| j v r�| � d| � dS dS )z�determine whether a particular property should be implicitly present on the class. This occurs when properties are propagated from an inherited class, or are applied from the columns present in the mapped table. NTznot including property %szexcluding property %sF) r6 Z_never_select_columnr| r r: r� r� rO r� r� r� )r� r r� r� r� �attrrk rk rl r� � sL �� �� ����� ���zMapper._should_exclude)�otherrg c C s | j |j u S )zXReturn true if the given mapper shares a common inherited parent as this mapper.)r� �r� r� rk rk rl � common_parent s zMapper.common_parentc C s$ | j |j u o"| �|� o"|�| � S )z{return true if the other mapper is an inheriting sibling to this one. common parent but different branch )r� r� r� rk rk rl � is_sibling s � �zMapper.is_siblingzInstanceState[Any])r> �allow_subtypesrg c C s4 | � � }| jd us|r$t|��|�S t|�|u S d S rh )�primary_mapperr� r$ r� )r� r> r� �srk rk rl �_canload( s zMapper._canloadc C s | }|r||ur|j }qt|�S )z>Return True if the this mapper inherits from the given mapper.)r rz )r� r� r\ rk rk rl r� 1 s z Mapper.isarn c c s | }|r|V |j }qd S rh )r )r� r\ rk rk rl r� 9 s zMapper.iterate_to_rootc C s< g }t | g�}|r2|�� }|�|� |�|j� qt�|�S )z�The collection including this mapper and all descendant mappers. This includes not just the immediately inheriting mappers but all their inheriting mappers as well. )r rF r� rG r� r r� )r� Z descendantsrH rI rk rk rl r� ? s zMapper.self_and_descendantsc C s t | j�S )aC Iterate through the collection including this mapper and all descendant mappers. This includes not just the immediately inheriting mappers but all their inheriting mappers as well. To iterate through an entire hierarchy, use ``mapper.base_mapper.polymorphic_iterator()``. )r� r� r� rk rk rl �polymorphic_iteratorO s zMapper.polymorphic_iteratorc C s | j jS )zSReturn the primary mapper corresponding to this mapper's class key (class).)r� r� r� rk rk rl r� \ s zMapper.primary_mapperc C s | j jjS rh )r� r� r� r� rk rk rl �primary_base_mapperb s zMapper.primary_base_mapperc s@ | j }� r � fdd�|D �}|�� }|D ]}||vr( dS q(dS )Nc s g | ]}� j | �qS rk �r� r# r� rk rl r! i r� z3Mapper._result_has_identity_key.<locals>.<listcomp>FT)r~ �keys)r� r� r� r/ Zrkr rk r� rl �_result_has_identity_keyf s z Mapper._result_has_identity_keyzUnion[Row[Any], RowMapping]zOptional[ORMAdapter]z_IdentityKeyType[_O])�rowr� r� rg c sP | j }� r � fdd�|D �}t|d�r.|j�n|�| jt�fdd�|D ��|fS )a� Return an identity-map key for use in storing/retrieving an item from the identity map. :param row: A :class:`.Row` or :class:`.RowMapping` produced from a result set that selected from the ORM mapped primary key columns. .. versionchanged:: 2.0 :class:`.Row` or :class:`.RowMapping` are accepted for the "row" argument c s g | ]}� j | �qS rk r� r# r� rk rl r! � r� z0Mapper.identity_key_from_row.<locals>.<listcomp>�_mappingc 3 s | ]}� | V qd S rh rk )r r� )�mappingrk rl r � r� z/Mapper.identity_key_from_row.<locals>.<genexpr>)r~ r r� r� r� )r� r� r� r� r/ rk )r� r� rl �identity_key_from_rowq s �z Mapper.identity_key_from_rowzTuple[Any, ...])r~ r� rg c C s | j t|�|fS )z�Return an identity-map key for use in storing/retrieving an item from an identity map. :param primary_key: A list of values indicating the identifier. )r� r� )r� r~ r� rk rk rl � identity_key_from_primary_key� s �z$Mapper.identity_key_from_primary_keyr! )�instancerg c C s t �|�}| �|tj�S )a� Return the identity key for the given instance, based on its primary key attributes. If the instance's state is expired, calling this method will result in a database check to see if the object has been deleted. If the row no longer exists, :class:`~sqlalchemy.orm.exc.ObjectDeletedError` is raised. This value is typically also found on the instance state under the attribute name `key`. �r �instance_state�_identity_key_from_stater% � PASSIVE_OFF)r� r r> rk rk rl �identity_key_from_instance� s z!Mapper.identity_key_from_instancer% )r> �passiverg c s4 �j � �j�| jt� ���fdd�| jD ���jfS )Nc s" g | ]}�|j j��� ���qS rk )r� �implr: r� �r? r r r> rk rl r! � s �z3Mapper._identity_key_from_state.<locals>.<listcomp>)r� r r� r� r' r� )r� r> r rk r rl r � s ���z Mapper._identity_key_from_statec C s t �|�}| �|tj�}|d S )aG Return the list of primary key values for the given instance. If the instance's state is expired, calling this method will result in a database check to see if the object has been deleted. If the row no longer exists, :class:`~sqlalchemy.orm.exc.ObjectDeletedError` is raised. r r )r� r r> Z identity_keyrk rk rl �primary_key_from_instance� s �z Mapper.primary_key_from_instancec s: dd� | j D �� t� ��d g�r.� fdd�}ndd� }|S )Nc S s g | ] }|j j�qS rk )r� Zsort_key_functionr rk rk rl r! � r� z1Mapper._persistent_sortkey_fn.<locals>.<listcomp>c s t dd� t� | jd �D ��S )Nc s s& | ] \}}|d ur||�n|V qd S rh rk )r Zkey_fn�valrk rk rl r � s �z=Mapper._persistent_sortkey_fn.<locals>.key.<locals>.<genexpr>r )r� �zipr� �r> �Zkey_fnsrk rl r� � s �z*Mapper._persistent_sortkey_fn.<locals>.keyc S s | j d S �Nr r� r rk rk rl r� � s )r~ rj � differencer� rk r rl �_persistent_sortkey_fn� s z Mapper._persistent_sortkey_fnc s � fdd�� j D �S )Nc s g | ]}� j | �qS rk r� r r� rk rl r! � r� z.Mapper._identity_key_props.<locals>.<listcomp>r" r� rk r� rl r' � s zMapper._identity_key_propsc C s& t � }| jD ]}|�| j| � q |S rh )rj r� r� r� )r� Z collectionr� rk rk rl � _all_pk_cols� s zMapper._all_pk_colsc C s$ t | j�}| jd ur |�| j� |S rh )rj r~ r� r, )r� r� rk rk rl �_should_undefer_in_wildcard� s z"Mapper._should_undefer_in_wildcardc s � fdd�� j D �S )Nc s h | ]}� j | j�qS rk r� r r� rk rl r( � r� z/Mapper._primary_key_propkeys.<locals>.<setcomp>)r r� rk r� rl �_primary_key_propkeys� s z Mapper._primary_key_propkeysrG �ColumnElement[Any])r> r? r� r rg c C s$ | j | }|j|j jj|||d�S �N�r )r� r r� r r: �r� r> r? r� r r� rk rk rl �_get_state_attr_by_column� s z Mapper._get_state_attr_by_columnc C s& | j | }|j|j j�|||� d S rh )r� r r� r Zset_committed_value�r� r> r? r� rm r� rk rk rl �#_set_committed_state_attr_by_column s z*Mapper._set_committed_state_attr_by_columnc C s( | j | }|j|j j�|||d � d S rh )r� r r� r rj r rk rk rl �_set_state_attr_by_column s z Mapper._set_state_attr_by_columnc C s( t �|�}t �|�}| j|||tjd�S r )r r � instance_dict�#_get_committed_state_attr_by_columnr% r )r� r� r� r> r? rk rk rl � _get_committed_attr_by_column s �z$Mapper._get_committed_attr_by_columnc C s$ | j | }|j|j jj|||d�S r )r� r r� r Zget_committed_valuer rk rk rl r s �z*Mapper._get_committed_state_attr_by_columnc sV �j � t|���jj�� �}tt� fdd�|D �� ���jj�v rFdS ���fdd�}g }d}t t �� � ��D ]l}|j�v r�d}nt |jt j�s� dS |rn|jsn|js�J �|jr�J �|jdus�J �|�|j� ��|j� qnzt�|d i d |i�}W n t�y Y dS 0 ||d< tj|� } g } |D ]} | �� | j� �q(tj | � � | �� t �S ) al assemble a WHERE clause which retrieves a given state by primary key, using a minimized set of tables. Applies to a joined-table inheritance mapper where the requested attribute names are only present on joined tables, not the base table. The WHERE clause attempts to include only those tables to minimize joins. c s* g | ]"}� | j D ]}tj|d d��qqS )T)Z check_columns)r� r� r) )r r� r� )�propsrk rl r! 0 s �z3Mapper._optimized_get_statement.<locals>.<listcomp>Nc s� | j }| j}|d u s |d u r d S |j�vrh� j��j|tjd�}|tjv rPt � �t j d || jj d�| _ nF|j�vr�� j��j|tjd�}|tjv r�t � �t j d || jj d�| _d S )Nr r� ) r� r� r� r r� r% ZPASSIVE_NO_INITIALIZEr� Z _none_set�_OptGetColumnsNotAvailabler4 r� r� )r� ZleftcolZrightcolZleftvalZrightval)r� r> r� rk rl r� ; s8 � � � �z5Mapper._optimized_get_statement.<locals>.visit_binaryFTr r� ) r� rj r+ r� r� r� r r� r} �reversedr� r� r� r9 r< r� r r� r� r� r, r= Zcloned_traverser! r4 r� rG r� �select�where�set_label_stylerB ) r� r> Zattribute_namesZcol_attribute_namesr� Zallconds�startr� Z _traversedZcondr� r� rk )r r� r> r� rl �_optimized_get_statement sX � ��� � ���z Mapper._optimized_get_statementc c sL | � |�rH| }| �� D ]0}|V ||ur6||jvr6 qH|}||u r qHqd S rh )r� r� r� )r� r� �prevr\ rk rk rl �_iterate_to_target_viawpoly� s z"Mapper._iterate_to_target_viawpolyc C s i S rh rk r� rk rk rl �&_would_selectinload_combinations_cache� s z-Mapper._would_selectinload_combinations_cachec C sl | j }z || W S ty" Y n0 | �|�s2J �|}| �|�D ]}|jdkr@||u } q`q@d}|||< |S )a� return True if this mapper would "selectin" polymorphic load based on the given super mapper, and not from a setting from a subclass. given:: class A: ... class B(A): __mapper_args__ = {"polymorphic_load": "selectin"} class C(B): ... class D(B): __mapper_args__ = {"polymorphic_load": "selectin"} ``inspect(C)._would_selectin_load_only_from_given_mapper(inspect(B))`` returns True, because C does selectin loading because of B's setting. OTOH, ``inspect(D) ._would_selectin_load_only_from_given_mapper(inspect(B))`` returns False, because D does selectin loading because of its own setting; when we are doing a selectin poly load from B, we want to filter out D because it would already have its own selectin poly load set up separately. Added as part of #9373. r� F)r* r r� r) r� )r� Z super_mapper�cacher� r\ �retvalrk rk rl �+_would_selectin_load_only_from_given_mapper� s z2Mapper._would_selectin_load_only_from_given_mapperc C s� |s,|}| � |�D ]}|jdkr| S qndt|�}dd� |D �}|�|g�D ]@}|j}| � |�D ]*}|jdksx||v rb|�||� S qbqNd S )Nr� c S s i | ] }|j |�qS rk �r� )r �erk rk rl r� � r� z0Mapper._should_selectin_load.<locals>.<dictcomp>)r) r� rj r r� r: )r� Zenabled_via_opt�polymorphic_fromr� r\ Zenabled_via_opt_mappersr� rk rk rl �_should_selectin_load� s ��z Mapper._should_selectin_loadz sqlalchemy.orm.strategy_optionsc s� t jj}| jsJ �| jdur:| j| j }t|g| j �}n t| j�}|�� �}|�� �}| h}| j} | dur�| |ur�| j dkr�|� | � | j} qd| j | j D ]t} | j | jvr�q�| j|v s�| |v r�t| t�s�q�|jt� j| j �ft| j�dd�}q�|jt� j| j �fddidd�}q�dd� | jD �} t| �d k�r<tj| � } n| d } � j�r�� j | u �s\J �t� � �� t �} � j �!| �} � fd d�| D �} | �"| �#tj$d dd ���j%| � } n0t� | �� t �} | �"| �#tj$d dd ���j%| � } | ||fS )zbAssemble a that can load the columns local to this subclass as a SELECT with IN. Nr� T)Z_reconcile_to_otherZ do_nothingFc S s g | ]}t �|d di��qS )Z _orm_adaptT)r� Z_deep_annotate)r �pkrk rk rl r! $ s �z0Mapper._subclass_load_via_in.<locals>.<listcomp>r r c s g | ]}� j �|��qS rk )�_adapterr� )r r0 �r� rk rl r! 8 r� Z primary_keys)Z expanding)&r rM Zorm_strategy_optionsr r� r� rj r' �Loadr� r, r� r� r� r� rP r� r- Z_set_generic_strategyrB r� r� Z strategy_keyr~ r- r4 �tuple_Zis_aliased_classr� r# r% rB r3 r� r$ r� r� Zorder_by)r� r� r0 Zstrategy_optionsZpolymorphic_propZ keep_propsZ disable_optZ enable_optZclasses_to_includer\ r� r~ Zin_expr�qrk r4 rl �_subclass_load_via_in� sz ��� � � � � �� ���z Mapper._subclass_load_via_inc C s | � | | j�S rh )r8 r� r� rk rk rl � _subclass_load_via_in_mapperF s z#Mapper._subclass_load_via_in_mapperz.Optional[Callable[[InstanceState[Any]], bool]]zGIterator[Tuple[object, Mapper[Any], InstanceState[Any], _InstanceDict]])r� r> �halt_onrg c c s t � }t� t� }}|j�| �s$J �tt|jj�� �|||jfg�}|�r|d \}} } } |sh|�� qD| |u r�|� � } | j rD|| j vr�qD| dus�J �| dus�J �t| � || | ||��} | r�|� | |ddf� qD| |u rD|� � \}}}}||||fV |� t|j�� �|||f� qDdS )a. Iterate each element and its mapper in an object graph, for all relationships that meet the given cascade rule. :param type\_: The name of the cascade rule (i.e. ``"save-update"``, ``"delete"``, etc.). .. note:: the ``"all"`` cascade is not accepted here. For a generic object traversal function, see :ref:`faq_walk_objects`. :param state: The lead InstanceState. child items will be processed per the relationships defined for this object's mapper. :return: the method yields individual object instances. .. seealso:: :ref:`unitofwork_cascades` :ref:`faq_walk_objects` - illustrates a generic function to traverse all objects without relying on cascades. ra N) rj �objectr� r� r r� rK r� r rF rf �cascade_iteratorr� )r� r� r> r: Zvisited_statesZprpZmppZ visitables�iteratorZ item_typeZ parent_stateZ parent_dictr� �queuer Zinstance_mapperZcorresponding_stateZcorresponding_dictrk rk rl r< K s^ � �� �� ��zMapper.cascade_iteratorc C s t �| j�S rh )r ZLRUCacher� r� rk rk rl �_compiled_cache� s zMapper._compiled_cachec C s t | j�dkS r )r- r� r� rk rk rl � _multiple_persistence_tables� s z#Mapper._multiple_persistence_tablesc s� i �| j jD ] }|jD ]}��||� qq g }��� D ],\� }|j}|r6|�� fdd�|jD �� q6�fdd�}tj�||d�}t � � }|D ]}�| ||< q�|S )Nc s g | ] }|� f�qS rk rk )r Z super_tabler& rk rl r! � r� z)Mapper._sorted_tables.<locals>.<listcomp>c s� � � | jj�}� � | jj�}|d ur�|d ur�||ur�|jd ur�tt�|j��}|jd ur~|�t�|j��}| j|vo|| j|vS | j|vS dS r� ) r: rP r� r� r� rj r� Z _find_columnsr )ZfkrP �depr� )�table_to_mapperrk rl �skip� s$ ���� � z#Mapper._sorted_tables.<locals>.skip)Zskip_fn�extra_dependencies) r� r� r� � setdefaultr� r rG r� Z sort_tablesr r7 )r� r� r rD Zsuper_rC Zsorted_�retrk )r� rB rl �_sorted_tables� s* � �zMapper._sorted_tableszCallable[[], _T]r^ )r� � callable_rg c C s2 || j v rtt| j | �S |� | j |< }|S d S rh )r� r r^ )r� r� rH rm rk rk rl �_memo� s z Mapper._memoc C sp t �t�}dd� }| jD ]R}t|j�}| �� D ]:}|jr.|�t |dd� |jD ���r.|| � ||jf� q.q|S )zgmemoized map of tables to collections of columns to be synchronized upwards to the base mapper.c S s | � |�S rh )r )r� �yrk rk rl � set_union� s z+Mapper._table_to_equated.<locals>.set_unionc S s g | ]\}}|j �qS rk r )r rj �rrk rk rl r! r� z,Mapper._table_to_equated.<locals>.<listcomp>) r � defaultdictr� rG rj r� r� r� r+ r r� )r� r� rK r� r� r\ rk rk rl �_table_to_equated� s � ��zMapper._table_to_equated) NNNFNNNFNNNNNFNFNTTNNNTFTrx Fry )F)NN)F)NFF)rk )N)N)NN)N)N)�r� r� � __qualname__�__doc__�__annotations__r ru r r Zdeprecated_paramsr� r� r� Z is_mapperZrepresents_outer_join�propertyr� r� r� Znon_memoized_property� deprecatedr� Zmemoized_propertyr� r� r� r� r� r� r� r r r� r� r� r� rC Zmemoized_attributerE rA rL �preload_moduler� r9 r8 r; rX Z langhelpersZtag_method_for_warningsr� Z SAWarningri rk rn rl r� rs r� rz r| r} r� r� r� r� r� r� r� r� r� r� r� r� r� rD r� Zwith_polymorphic_mappersr� r� r� r� r� r� r� r� r� r� Zmemoized_instancemethodr� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r r r% ZPASSIVE_RETURN_NO_VALUEr r r r' r r r r r r r r r' r) r* r- r1 r8 r9 r< r? r@ rG rI rN rk rk rk rl rs � sJ � �J % @' ]t G � +$ �B$� � $ 0 � %E $ . �"$� � �$ � f 8 a� a2 rs r� c @ s e Zd ZdS )r! N)r� r� rO rk rk rk rl r! s r! r� c C s t t� dd� dS )a� Initialize the inter-mapper relationships of all mappers that have been constructed thus far across all :class:`_orm.registry` collections. The configure step is used to reconcile and initialize the :func:`_orm.relationship` linkages between mapped classes, as well as to invoke configuration events such as the :meth:`_orm.MapperEvents.before_configured` and :meth:`_orm.MapperEvents.after_configured`, which may be used by ORM extensions or user-defined extension hooks. Mapper configuration is normally invoked automatically, the first time mappings from a particular :class:`_orm.registry` are used, as well as whenever mappings are used and additional not-yet-configured mappers have been constructed. The automatic configuration process however is local only to the :class:`_orm.registry` involving the target mapper and any related :class:`_orm.registry` objects which it may depend on; this is equivalent to invoking the :meth:`_orm.registry.configure` method on a particular :class:`_orm.registry`. By contrast, the :func:`_orm.configure_mappers` function will invoke the configuration process on all :class:`_orm.registry` objects that exist in memory, and may be useful for scenarios where many individual :class:`_orm.registry` objects that are nonetheless interrelated are in use. .. versionchanged:: 1.4 As of SQLAlchemy 1.4.0b2, this function works on a per-:class:`_orm.registry` basis, locating all :class:`_orm.registry` objects present and invoking the :meth:`_orm.registry.configure` method on each. The :meth:`_orm.registry.configure` method may be preferred to limit the configuration of mappers to those local to a particular :class:`_orm.registry` and/or declarative base class. Points at which automatic configuration is invoked include when a mapped class is instantiated into an instance, as well as when ORM queries are emitted using :meth:`.Session.query` or :meth:`_orm.Session.execute` with an ORM-enabled statement. The mapper configure process, whether invoked by :func:`_orm.configure_mappers` or from :meth:`_orm.registry.configure`, provides several event hooks that can be used to augment the mapper configuration step. These hooks include: * :meth:`.MapperEvents.before_configured` - called once before :func:`.configure_mappers` or :meth:`_orm.registry.configure` does any work; this can be used to establish additional options, properties, or related mappings before the operation proceeds. * :meth:`.MapperEvents.mapper_configured` - called as each individual :class:`_orm.Mapper` is configured within the process; will include all mapper state except for backrefs set up by other mappers that are still to be configured. * :meth:`.MapperEvents.after_configured` - called once after :func:`.configure_mappers` or :meth:`_orm.registry.configure` is complete; at this stage, all :class:`_orm.Mapper` objects that fall within the scope of the configuration operation will be fully configured. Note that the calling application may still have other mappings that haven't been produced yet, such as if they are in modules as yet unimported, and may also have mappings that are still to be configured, if they are in other :class:`_orm.registry` collections not part of the current scope of configuration. Tre N)rh rm rk rk rk rl �configure_mappers s DrU zSet[_RegistryType]rz )� registriesrf rg c C s� | D ]}|j r qqd S t�| tr2W d � d S dazL| D ]}|j r< qbq<W daW d � d S tj�t��� t| |� W danda0 W d � n1 s�0 Y tj�t��� d S )NTF) rg ri �_already_compilingrs rt Z _for_classZbefore_configured�_do_configure_registriesZafter_configured)rV rf rp rk rk rl rh Z s& � *rh zsqlalchemy.orm.decl_apic C s t jjj}t| �}|�| �D ]�}d}|�� D ]�}d }|jjD ] }|||j �}|t u r<d} q^q<|t u rhq,t |dd�r�t � d||jf �} |j| _| �|js,z$|�� |�� |j�||j � W q, ty� t�� d } t| d�s�| |_� Y q,0 q,|s�d|_|s |j�|�r t � d��q d S )NFTru z�One or more mappers failed to initialize - can't proceed with initialization of other mappers. Triggering mapper: '%s'. Original exception was: %sr zHconfigure was called with cascade=False but additional registries remain)r rM � orm_decl_apirJ rj Z_recurse_with_dependenciesro rt Zbefore_mapper_configuredr| r( rB r� r ru r� rk r� Zmapper_configured� Exception�sys�exc_infor rg � _dependenciesr ) rV rf rJ �origrp Zhas_skipr� Z run_configure�fnr/ r rk rk rl rX | sJ �� �rX c C s� t jjj}t| �}|�| �D ]�}|s:|j�|�r:t� d��|j rrz|j � � \}}W n t yd Y q:0 |� |� q:|j�� |j�� |jD ]}|j�|� q�|j�� d|_q d S )Nz^Registry has dependent registries that are not disposed; pass cascade=True to clear these alsoF)r rM rY rJ rj Z_recurse_with_dependentsZ _dependentsr r� r Z _managers�popitemr Z_dispose_manager_and_mapperZ_non_primary_mappers�clearr] �discardrg )rV rf rJ r^ rp r �_rA rk rk rl �_dispose_registries� s& � rd �r_ rg c C s d| _ | S )a� Decorate a method as the 'reconstructor' hook. Designates a single method as the "reconstructor", an ``__init__``-like method that will be called by the ORM after the instance has been loaded from the database or otherwise reconstituted. .. tip:: The :func:`_orm.reconstructor` decorator makes use of the :meth:`_orm.InstanceEvents.load` event hook, which can be used directly. The reconstructor will be invoked with no arguments. Scalar (non-collection) database-mapped attributes of the instance will be available for use within the function. Eagerly-loaded collections are generally not yet available and will usually only contain the first element. ORM state changes made to objects at this stage will not be recorded for the next flush() operation, so the activity within a reconstructor should be conservative. .. seealso:: :meth:`.InstanceEvents.load` T)r �r_ rk rk rl � reconstructor� s rg T��include_removes�include_backrefsr� zCallable[[_Fn], _Fn])�namesri rj rg c s ddd�� ��fdd� }|S )a� Decorate a method as a 'validator' for one or more named properties. Designates a method as a validator, a method which receives the name of the attribute as well as a value to be assigned, or in the case of a collection, the value to be added to the collection. The function can then raise validation exceptions to halt the process from continuing (where Python's built-in ``ValueError`` and ``AssertionError`` exceptions are reasonable choices), or can modify or replace the value before proceeding. The function should otherwise return the given value. Note that a validator for a collection **cannot** issue a load of that collection within the validation routine - this usage raises an assertion to avoid recursion overflows. This is a reentrant condition which is not supported. :param \*names: list of attribute names to be validated. :param include_removes: if True, "remove" events will be sent as well - the validation function must accept an additional argument "is_remove" which will be a boolean. :param include_backrefs: defaults to ``True``; if ``False``, the validation function will not emit if the originator is an attribute event related via a backref. This can be used for bi-directional :func:`.validates` usage where only one validator should emit per attribute operation. .. versionchanged:: 2.0.16 This paramter inadvertently defaulted to ``False`` for releases 2.0.0 through 2.0.15. Its correct default of ``True`` is restored in 2.0.16. .. seealso:: :ref:`simple_validators` - usage examples for :func:`.validates` rb re c s �| _ �� d�| _| S )Nrh )r r rf �rj ri rk rk rl �wrap s �zvalidates.<locals>.wraprk )ri rj rk rm rk rl rl � validates� s (rn c C s | j j}|jr |�| �� � d S rh )r r� r� r� )r> �ctx�instrumenting_mapperrk rk rl r $ s r c C s( | j j}|r$|�� |jr$|�| � dS )z�Run init_instance hooks. This also includes mapper compilation, normally not needed here but helps with some piecemeal configuration scenarios (such as in the ORM tutorial). N)r r� ri r� )r> rt �kwargsrp rk rk rl r + s r c @ s$ e Zd ZdZdZdd� Zdd� ZdS )r� z4Error reporting helper for mapper._columntoproperty.r. c C s || _ d S rh r. ro rk rk rl r� @ s z_ColumnMapping.__init__c C sH | j j�|�}|r0t�d|jj|j|j|f ��t�d|| j f ��d S )NzDColumn '%s.%s' is not available, due to conflicting property '%s':%rz*No column %s is configured on mapper %s...)r� r� r: �orm_excZUnmappedColumnErrorr� r r� )r� r� r� rk rk rl � __missing__D s ����z_ColumnMapping.__missing__N)r� r� rO rP � __slots__r� rs rk rk rk rl r� ; s r� )r ra )�rP � __future__r � collectionsr � functoolsr � itertoolsr r[ � threading�typingr r r r r r r r r r r r r r r r r r r r �weakrefr3 r r rr r r r r r� Z_typingr! r7 r" r# r$ r% r& Z interfacesr' r( r) r* r+ r, r- Z path_registryr. r0 r� r1 r2 r3 r4 r5 r6 r6 r8 r9 r: r; r< r� r= Z sql.cache_keyr> Z sql.elementsr? Z sql.schemar@ rA Zsql.selectablerB rC rD Z util.typingrE rF rG rH rI Zdecl_apirJ � dependencyrK rR rL rM �eventsrN rO rP rQ r� rR r> rS rT ZenginerU rV Z sql._typingrW rX Zsql.baserY rZ r[ r\ r] r^ r` rb Z_WithPolymorphicArg�WeakKeyDictionaryre rQ rm rq rW �symbolrr �RLockri Z_self_inspectsZ class_loggerZ IdentifiedZ Inspectablers rZ r! rU rh rT rX rd rg rn r r r� rk rk rk rl �<module> sZ ���� � � G"4! �3 sqlalchemy/orm/__pycache__/strategies.cpython-39.pyc 0000644 00000166304 15125143220 0016523 0 ustar 00 a ��Jh�� � @ s� d Z ddlmZ ddlZddlZddlmZ ddlmZ ddlmZ ddlm Z ddlm Z dd lm Z d d l m Z d d l mZ d d l mZ d dl mZ d dl mZ d dl mZ d dl mZ d dl mZ d dl mZ d dl mZ d dlmZ d dlmZ d dlm Z d dlm Z d dlm Z d dlm Z d dlm Z d d l!m"Z" d d l!m#Z# d d l!m$Z$ d d l!m%Z% d d lm&Z& d d!lm'Z' d d"l(m)Z) d d#l*m+Z+ d d$l,m-Z- d d%lm.Z. d d&lm/Z/ d'd(l m0Z0 d'd l mZ1 d'd)l m2Z2 d'd*l m3Z3 d'd+l m4Z4 d'dl mZ d'dl4mZ5 d'd,l4m6Z6 d'd-l7m8Z8 d'd.l7m9Z9 d'd/l:m;Z; e �rfd d0l<m=Z= d d1lm>Z> d'd2l?m@Z@ dfd4d5�ZAejBjCd3d3d6�G d7d8� d8e&��ZDe3jEejBjCd9d3d6�G d:d;� d;e&���ZFe3jEejBjCd9d<�G d=d>� d>eF���ZGe3jEejBjCd9d9d?�ejBjCd9d9d9d@�ejBjCd9dA�G dBdC� dCe&�����ZHG dDdE� dE�ZIG dFdG� dGe&�ZJe3jEej>jCd9dA�G dHdI� dIe&���ZKe3jEej>jCdJdK�ej>jCddK�G dLdM� dMeJ����ZLe3jEej>jCd9dK�ej>jCdNdK�ej>jCdOdK�ej>jCdPdK�ej>jCdQdK�G dRdS� dSeJejMe3jN�������ZOG dTdU� dU�ZPG dVdW� dWeJ�ZQej>jCdXdK�G dYdZ� dZeQ��ZRe3jEej>jCd[dK�G d\d]� d]eQ���ZSe3jEej>jCd^dK�ej>jCd3dK�G d_d`� d`eJ����ZTe3jEej>jCdadK�G dbdc� dceQejM���ZUddde� ZVdS )gzWsqlalchemy.orm.interfaces.LoaderStrategy implementations, and related MapperOptions.� )� annotationsN)�Any)�Dict)�Optional)�Tuple)� TYPE_CHECKING)�Union� )� attributes)�exc)� interfaces)�loading)� path_registry)� properties)�query)� relationships)� unitofwork)�util)�_DEFER_FOR_STATE)�_RAISE_FOR_STATE)�_SET_DEFERRED_EXPIRED)� ATTR_WAS_SET)�LoaderCallableStatus)� PASSIVE_OFF)� PassiveFlag)�_column_descriptions)�ORMCompileState)�ORMSelectCompileState)� QueryContext)�LoaderStrategy)�StrategizedProperty)�_state_session)� InstanceState)�Load)�_none_only_set)� AliasedClass� )�event)�inspect)�log)�sql)�visitors)� LABEL_STYLE_TABLENAME_PLUS_COL)�Select)�Literal)�Mapper)�RelationshipProperty)� ColumnElementFc s" g } |o | j �|r"| jr"| �t� | j| jjv rV| jj| j \��| ���fdd�� |rf| �tj� |r�| j � � r�| j r�| �� �fdd�� |j D ]�} | | j � | j�u r�| j�| j�s�tj| j| jf| �|||o�| jp�| jtju ||||| p�| j | jd� | ��} | D ]} | | | � �q q�d S )Nc s t j| |j� fi ���S �N)�orm_utilZ_validator_events�key��desc�prop)�fn�opts� �N/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/strategies.py�<lambda>\ s ��z%_register_attribute.<locals>.<lambda>c s t �| � ��S r2 )r Zbackref_listenersr5 )�backref�uselistr: r; r< j s �) Z parent_tokenr> �compare_function� useobjectZ trackparent� typecallable� callable_�active_history� impl_classZsend_modified_events�doc)r> Z single_parent�append�single_parent_validatorr4 �parentZ validatorsr Ztrack_cascade_eventsZback_populatesZ_effective_sync_backrefZself_and_descendants�_props�get� class_managerZ_attr_has_implr Zregister_attribute_impl�class_� directionr Z ONETOMANYZviewonlyrE )r7 �mapperr@ r? rA rB Zproxy_propertyrC rD �kwZ listen_hooks�mr6 �hookr: )r= r8 r9 r> r; �_register_attributeF sZ � � � �� ��rR )� instrument�deferredc s6 e Zd ZdZdZ� fdd�Zd dd�Zdd � Z� ZS ) �UninstrumentedColumnLoaderz�Represent a non-instrumented MapperProperty. The polymorphic_on argument of mapper() often results in this, if the argument is against the with_polymorphic selectable. ��columnsc s t � �||� | jj| _d S r2 )�super�__init__�parent_propertyrW ��selfrH � strategy_key�� __class__r: r; rY � s z#UninstrumentedColumnLoader.__init__Nc K s* | j D ] }|r|j | }|�||� qd S r2 )rW � _append_dedupe_col_collection) r\ � compile_state� query_entity�path�loadopt�adapter�column_collection�kwargs�cr: r: r; � setup_query� s z&UninstrumentedColumnLoader.setup_queryc C s d S r2 r: � r\ �contextrb rc rd rN �resultre � populatorsr: r: r; �create_row_processor� s z/UninstrumentedColumnLoader.create_row_processor)N) �__name__� __module__� __qualname__�__doc__� __slots__rY ri rn � __classcell__r: r: r^ r; rU � s � rU Tc s> e Zd ZdZdZ� fdd�Zd dd�Zdd � Zd d � Z� Z S ) � ColumnLoaderz8Provide loading behavior for a :class:`.ColumnProperty`.)rW � is_compositec s* t � �||� | jj| _t| jd�| _d S )N�composite_class)rX rY rZ rW �hasattrrv r[ r^ r: r; rY � s zColumnLoader.__init__Fc K sv | j D ]<} |r6|r,|�| �} | d u r6 d S n |j | } |�| |� q| j d } |rh|j | } | d u rhd S | || j< d S �Nr )rW Zadapt_check_presentr` rZ ) r\ ra rb rc rd re rf �memoized_populatorsZcheck_for_adaptrg rh �fetchr: r: r; ri � s zColumnLoader.setup_queryc C s` d| _ | jd j}| jjpD| jd jpD|jd uoD|j�|jd �| ju }t | j|d|j |d� d S )NTr F)r@ r? rC ) �is_class_levelrW �typerZ rC � primary_keyZversion_id_col�_columntopropertyrJ rR �compare_values)r\ rN ZcoltyperC r: r: r; �init_class_attribute� s" � �� �z!ColumnLoader.init_class_attributec C sZ | j D ]:} |r|j | } |�| d�} | r|d �| j| f� qVq|d �| jdf� d S �NFZquick�expireT)rW �_getterrF r4 ) r\ rk rb rc rd rN rl re rm �col�getterr: r: r; rn s z!ColumnLoader.create_row_processor)F) ro rp rq rr rs rY ri r� rn rt r: r: r^ r; ru � s � !ru )Zquery_expressionc s4 e Zd Z� fdd�Zdd� Zdd� Zdd� Z� ZS ) �ExpressionColumnLoaderc s< t � �||� t�� �d �� t� fdd�| jjD ��| _d S )Nc 3 s | ]}|� � � V qd S r2 )�compare��.0rh ��nullr: r; � <genexpr>) s z2ExpressionColumnLoader.__init__.<locals>.<genexpr>) rX rY r* r� �label�anyrZ rW �_have_default_expressionr[ r^ r� r; rY " s �z ExpressionColumnLoader.__init__c K s� d } |r|j r|j } n| jr$| jj} | d u r0d S | D ] } |rF|j| } |�| |� q4| d } |rv|j| } | d u rvd S | || j< d S ry )�_extra_criteriar� rZ rW r` ) r\ ra rb rc rd re rf rz rg rW rh r{ r: r: r; ri - s" z"ExpressionColumnLoader.setup_queryc C sh |rd|j rd|j } | D ]:} |r&|j| } |�| d�} | r|d �| j| f� qdq|d �| jdf� d S r� )r� rW r� rF r4 ) r\ rk rb rc rd rN rl re rm rW r� r� r: r: r; rn R s z+ExpressionColumnLoader.create_row_processorc C s( d| _ t| j|d| jd jjdd� d S )NTFr )r@ r? Zaccepts_scalar_loader)r| rR rZ rW r} r� �r\ rN r: r: r; r� l s �z+ExpressionColumnLoader.init_class_attribute)ro rp rq rY ri rn r� rt r: r: r^ r; r� s %r� )rT rS )rT rS � raiseload)Z do_nothingc sN e Zd ZdZdZ� fdd�Zdd� Zdd� Zdd d �Zd d � Z dd� Z � Z S )�DeferredColumnLoaderzAProvide loading behavior for a deferred :class:`.ColumnProperty`.)rW �groupr� c sJ t � �||� t| jd�r"td��| j�dd�| _| jj| _| jj | _ d S )Nrw z8Deferred loading for composite types not implemented yetr� F) rX rY rx rZ �NotImplementedError� strategy_optsrJ r� rW r� r[ r^ r: r; rY � s � z DeferredColumnLoader.__init__c C s� |j rB|jjjrB| j|jjjv rB| j�d��||||||||� nH| jsv| j rX| jj } n| jj } |d � | j| f� n|d � | jdf� d S )N�)rT F�rS T�newr� F) � refresh_stater �_compile_options�_only_load_propsr4 rZ � _get_strategyrn r| r� Z_raise_column_loaderZ_deferred_column_loaderrF ) r\ rk rb rc rd rN rl re rm Z set_deferred_for_local_stater: r: r; rn � s4 ����� ��z)DeferredColumnLoader.create_row_processorc C s, d| _ t| j|d| jd jj| jdd� d S )NTFr )r@ r? rB Zload_on_unexpire)r| rR rZ rW r} r� �_load_for_stater� r: r: r; r� � s �z)DeferredColumnLoader.init_class_attributeNc K s� |j jr| jjsT|r(t| j��| jj�sT|rF| j rF|j � d| j d�sT|r|| j |v r|| j� d�j|||||||fi | �� n.| jr�t|| j< n | js�t|| j< n t|| j< d S )Nzundefer_group_%sFr� )�compile_optionsZ_render_for_subqueryrZ Z_renders_in_subqueries�setrW � intersectionrH Z_should_undefer_in_wildcardr� � local_optsrJ r4 r� ri r| r r� r r ) r\ ra rb rc rd re rf rz Zonly_load_propsrO r: r: r; ri � sP ��� �� � � ������ � z DeferredColumnLoader.setup_queryc s� �j s tjS |tj@ s tjS �jj}� jr@� fdd�|j D �}n� j g}�fdd�|D �}t ��}|d u r�t � dt ���� j f ��� jr�� ��|d� t��j�t|�t� tjS )Nc s4 g | ],}t |t�rt |jt�r|j� jkr|j�qS r: )� isinstancer �strategyr� r� r4 )r� �p�r\ r: r; � <listcomp> s �z8DeferredColumnLoader._load_for_state.<locals>.<listcomp>c s g | ]}|� j v r|�qS r: )Z unmodified)r� �k)�stater: r; r� � zfParent instance %s is not bound to a Session; deferred load operation of attribute '%s' cannot proceed�raise)r4 r � ATTR_EMPTYr �SQL_OK�PASSIVE_NO_RESULT�managerrN r� Ziterate_propertiesr! �orm_exc�DetachedInstanceErrorr3 � state_strr� �_invoke_raise_loadr Zload_scalar_attributesr� r r )r\ r� �passive� localparentZtoloadr� �sessionr: )r\ r� r; r� � s0 ����z$DeferredColumnLoader._load_for_statec C s t �d| f ��d S )Nz+'%s' is not available due to raiseload=True��sa_exc�InvalidRequestError�r\ r� r� �lazyr: r: r; r� ' s �z'DeferredColumnLoader._invoke_raise_load)N) ro rp rq rr rs rY rn r� ri r� r� rt r: r: r^ r; r� x s 3 � 3(r� c @ s0 e Zd ZdZd ddd�dd�Zejfdd �Zd S ) �LoadDeferredColumnsz7serializable loader object used by DeferredColumnLoaderF�str�bool�r4 r� c C s || _ || _d S r2 r� )r\ r4 r� r: r: r; rY 0 s z LoadDeferredColumns.__init__c C s> | j }|jj}|j| }| jr$d}nd}|�|�}|�||�S )N)�rT Tr� )r� T)r� r� )r4 r� rN rI r� r� r� )r\ r� r� r4 r� r7 r] r� r: r: r; �__call__4 s z LoadDeferredColumns.__call__N)F)ro rp rq rr rY r r r� r: r: r: r; r� - s r� c s, e Zd ZdZdZ� fdd�Zdd� Z� ZS )�AbstractRelationshipLoaderz0LoaderStratgies which deal with related objects.)rN �targetr> �entityc s: t � �||� | jj| _| jj| _| jj| _| jj| _d S r2 )rX rY rZ rN r� r� r> r[ r^ r: r; rY J s z#AbstractRelationshipLoader.__init__c C s | j �d��||||||||�S )N))r� � immediate)rZ r� rn rj r: r: r; �#_immediateload_create_row_processorQ s ��z>AbstractRelationshipLoader._immediateload_create_row_processor)ro rp rq rr rs rY r� rt r: r: r^ r; r� E s r� c @ s e Zd ZdZdS )�DoNothingLoaderz�Relationship loader that makes no change to the object's state. Compared to NoLoader, this loader does not initialize the collection/attribute to empty/none; the usual default LazyLoader will take effect. N)ro rp rq rr r: r: r: r; r� j s r� Znoload)r� c @ s$ e Zd ZdZdZdd� Zdd� ZdS )�NoLoaderzQProvide loading behavior for a :class:`.Relationship` with "lazy=None". r: c C s d| _ t| j|d| jjd� d S )NT)r@ rA )r| rR rZ �collection_classr� r: r: r; r� � s �z NoLoader.init_class_attributec s$ � fdd�} |d � � j| f� d S )Nc s& � j rt�| |� j� n d |� j< d S r2 )r> r �init_state_collectionr4 �r� �dict_�rowr� r: r; �invoke_no_load� s z5NoLoader.create_row_processor.<locals>.invoke_no_loadr� )rF r4 ) r\ rk rb rc rd rN rl re rm r� r: r� r; rn � s z NoLoader.create_row_processorN)ro rp rq rr rs r� rn r: r: r: r; r� v s r� �selectr� � raise_on_sqlZ baked_selectc s� e Zd ZU dZdZded< ded< ded< ded< d ed < d d d �� fd d� Zdd� Zdd� Zdd� Z dd� Z dddde j fdd�Z dd � Ze �d �d d � �Zd d!� Z� ZS )"� LazyLoaderztProvide loading behavior for a :class:`.Relationship` with "lazy=True", that is loads when first accessed. ) � _lazywhere�_rev_lazywhereZ_lazyload_reverse_option� _order_by�use_get�is_aliased_class� _bind_to_col�_equated_columns�_rev_bind_to_col�_rev_equated_columns�_simple_lazy_clause� _raise_always� _raise_on_sqlzColumnElement[bool]r� z Dict[str, ColumnElement[Any]]r� r� r� zRelationshipProperty[Any]rZ zTuple[Any, ...])rH r] c s8 t � �||� | jd dk| _| jd dk| _t| j�j| _| jj }|� � \| _ | _ | _ |j dd�\| _| _| _| jjr�dd� t�| jj�D �| _nd | _| j�d| | j � | j o�| j o�| jjd j| j dd | jjd �| _ | j �r4t | j �D ]4}|| jjv r�| jj| D ]}| j | | j |< �q q�| j�d | � d S ) Nr� r� r� T)Zreverse_directionc S s g | ]}t �|d di��qS )� _orm_adaptT)�sql_util�_deep_annotate�r� �elemr: r: r; r� � s �z'LazyLoader.__init__.<locals>.<listcomp>z%s lazy loading clause %sr F�Z use_proxiesZ compare_keys� equivalentsz4%s will use Session.get() to optimize instance loads) rX rY r� r� r� r( r� r� rZ �_join_conditionZcreate_lazy_clauser� r� r� r� r� r� �order_byr �to_listr� �logger�infor> � _get_clauser� rN �_equivalent_columnsr� �list)r\ rH r] Zjoin_conditionr� rh r^ r: r; rY � sN � � � � �� �zLazyLoader.__init__c C sv d| _ | jj}| jjr d}d}n4| jjtjus4| jsL|rBd}d}qTd}d}nd }}t| j|d| j | jj ||d� d S )NTF)r@ rB rA rC �_deferred_history) r| rZ � _legacy_inactive_history_stylerC rM r � MANYTOONEr� rR r� r� )r\ rN r� rC r� r: r: r; r� s2 � ���z LazyLoader.init_class_attributec sd t �| jddi�}|| j }� g �dd� }t�|i d|i� � �fdd�}t�|i d|i�}|�fS )Nr� Tc S s d| _ d S )NF)�unique�� bindparamr: r: r; �visit_bindparam+ s zFLazyLoader._memoized_attr__simple_lazy_clause.<locals>.visit_bindparamr� c sF | j � v r$��| j� | j d f� n | jd u rB��| jd | jf� d S r2 )Z_identifying_keyrF r4 �callable�valuer� �Z bind_to_col�paramsr: r; r� 0 s �� )r� r� r� r� r+ �traverseZcloned_traverse)r\ Z lazywhere� criterionr� r: r� r; �"_memoized_attr__simple_lazy_clause" s � �z-LazyLoader._memoized_attr__simple_lazy_clausec C s� | j \}}|d u r(t�|dd� |D ��S | jj}|�� }t�|�}|tj @ rV|tj N }i }|D ]J\} } } | d ur�|r�|tj @ r�|� ||| |�} n|� ||| |�} | || < q^||fS )Nc S s g | ]\}}}|�qS r: r: )r� r4 �identr� r: r: r; r� G r� z4LazyLoader._generate_lazy_clause.<locals>.<listcomp>) r� r� Zadapt_criterion_to_nullrZ rH �objr � instance_dictr ZINIT_OK�LOAD_AGAINST_COMMITTED�#_get_committed_state_attr_by_column�_get_state_attr_by_column) r\ r� r� r� Z param_keysrN �or� r� r4 r� r� r: r: r; �_generate_lazy_clauseB s, � �� z LazyLoader._generate_lazy_clausec C s t �d| |f ��d S )Nz&'%s' is not available due to lazy='%s'r� r� r: r: r; r� b s �z LazyLoader._invoke_raise_loadNr: c C s� |j s | jjs|jr|js tjS |j }d } | jo>| p>|j } |t j @ sN| r\|t j @ sb|rbtj S | jr�|t j@ s�| r�|t j@ r�| �||d� t|�} | s�|t j@ r�tj S t�dt�|�| j f ��| �r�| �| ||�} tj | v r�tj S tj| v r�tjS | jj�st� | ��r$d S nt� | ��r$d S | j |j v �rD|t j @ �sDtj S | j!| j"| ||d�} | d u�rx| tj#u �rrd S | S n |t j @ �r�|t j@ �s�tj S | �$| || ||||||� S )Nr� zbParent instance %s is not bound to a Session; lazy load operation of attribute '%s' cannot proceed)r� Zlazy_loaded_from)%r4 rZ Zload_on_pendingZ _load_pendingZ session_idr r� r� r� r r� r ZNON_PERSISTENT_OKr� r� �NO_RAISEZRELATED_OBJECT_OKr� r! r� r� r3 r� �_get_ident_for_use_getZ NEVER_SETrN Zallow_partial_pksr$ r� � issuperset�dict�DEFERRED_HISTORY_LOADr Z_identity_lookupr� ZPASSIVE_CLASS_MISMATCH�_emit_lazyload) r\ r� r� rd �extra_criteria� extra_options�alternate_effective_path�execution_options�pending�primary_key_identityr� r� �instancer: r: r; r� g s� ������� � � ��� ��� ���zLazyLoader._load_for_statec sD �j j}�tj@ r|j�n|j��j� � ����fdd��jjD �S )Nc s" g | ]}��� �j | �d ��qS )�r� �r� �r� �pk�r� Zget_attrr� r\ r� r: r; r� � s �z5LazyLoader._get_ident_for_use_get.<locals>.<listcomp>)r� rN r r� r r r r~ )r\ r� r� r� �instance_mapperr: r r; r � s �z!LazyLoader._get_ident_for_use_getz sqlalchemy.orm.strategy_optionsc s� t jj�� j�� } tj| g| jtt j d�} t j } | d|d�7 } � j jd ur\| �� j� j j�} |j } | sr|tj@ r�t �ddi�| _� j}|js�|r�|jr�|d u r�|j� j }n |� j }|j}|r�|jr�d}|t�� j|�f7 }|| _ n$|d u �r|jj � j }n |� j }|�r | j |7 _ | j d|i7 _ |�rn� j �rZ|t j!@ �sZ� �"||d� t#j$|| || | d�S � j%�r~� j%| _&� �fdd �}| j'|� j ff7 _'� �(||�\}}| �r�t j)�*| d | i�} nd | i} � j|j+v �r�|t j,@ �s�t-j.S | �rt �/tj0|�1� ��r,d S nt �/tj2|�1� ��r,d S � j �rN|t j!@ �sN� �"||d� |f| _3|j4| || d �}|�5� �6� �7� }� j8�r�|S t9|�}|�r�|d k�r�t �:d � j � |d S d S d S )N)� _raw_columns�_propagate_attrs� _label_styler� F)Z_invoke_all_eagers�_lazy_loaded_fromZ autoflush� _current_pathr� )� load_optionsr c sR � j jD ]D}|jtju r|jrt|jt�s�j � | j j |j ��|��| � qd S r2 )rZ Z_reverse_propertyrM r r� Z_use_getr� r� r� r# Z _construct_for_existing_pathr� r rH ZlazyloadZprocess_compile_state)�compile_context�rev�r\ �strategy_optionsr: r; �_lazyload_reverseB s �� �����z4LazyLoader._emit_lazyload.<locals>._lazyload_reverseZ_sa_orm_load_options)r r zKMultiple rows returned with uselist=False for lazily-loaded attribute '%s' r );r Z preloadedZorm_strategy_optionsr� �__clause_element__r- �_create_raw_selectr r, r �default_compile_optionsr Zdefault_load_optionsrZ Z secondary� select_fromrN r4 r Z NO_AUTOFLUSH� immutabledict�_execution_optionsr� r r� Z load_pathr3 �LoaderCriteriaOption� _with_options�_path_registryr� r� r r r� r Zload_on_pk_identityr� �_order_by_clausesZ_with_context_optionsr � EMPTY_DICT� merge_withr r r r Zhas_intersectionZ _none_set�valuesZ _never_setZ_where_criteria�executer� Zscalars�allr> �len�warn)r\ r� r� r r� rd r r r r Z clauseelement�stmtr r r� �effective_pathr9 r! Z lazy_clauser� rl �lr: r r; r � s� �� � � ����� ��� ��zLazyLoader._emit_lazyloadc s� | j � |jjr@|jjjr@| j |jjjv r@| �||||||||�S | jrP|r�|jr�t � |j t � | ||jrp|� |�nd �� �} |d �| j | f� n,|js�|jr�� fdd�} |d �| j | f� d S )Nr� c s | � |� � d S r2 )Z_resetr� �r4 r: r; �reset_for_lazy_callable� s z@LazyLoader.create_row_processor.<locals>.reset_for_lazy_callable)r4 r Z_is_user_refreshr r� r� r� r| r� r" Z"_instance_level_callable_processorrK �LoadLazyAttribute�_generate_extra_criteriarF �populate_existingZalways_refresh) r\ rk rb rc rd rN rl re rm Zset_lazy_callabler7 r: r6 r; rn � sF ���� �� � � z LazyLoader.create_row_processor)ro rp rq rr rs �__annotations__rY r� r� r r� r r, r� r Zpreload_moduler rn rt r: r: r^ r; r� � s. <" � w r� c @ s. e Zd ZdZdd� Zdd� Zejfdd�ZdS ) r8 a� semi-serializable loader object used by LazyLoader Historically, this object would be carried along with instances that needed to run lazyloaders, so it had to be serializable to support cached instances. this is no longer a general requirement, and the case where this object is used is exactly the case where we can't really serialize easily, which is when extra criteria in the loader option is present. We can't reliably serialize that as it refers to mapped entities and AliasedClass objects that are local to the current process, which would need to be matched up on deserialize e.g. the sqlalchemy.ext.serializer approach. c C s || _ |j| _|| _|| _d S r2 �r4 r] rd r )r\ r4 Zinitiating_strategyrd r r: r: r; rY � s zLoadLazyAttribute.__init__c C s( | j d urt�d� | j| j| jdd�S )NzvCan't reliably serialize a lazyload() option that contains additional criteria; please use eager loading for this caser: r< )r r r2 r4 r] rd r� r: r: r; � __getstate__� s ��z LoadLazyAttribute.__getstate__c C s: | j }|jj}|j| }|j| j }|j||| j| jd�S )N)rd r ) r4 r� rN rI Z _strategiesr] r� rd r )r\ r� r� r4 r r7 r� r: r: r; r� � s �zLoadLazyAttribute.__call__N) ro rp rq rr rY r= r r r� r: r: r: r; r8 � s r8 c @ s e Zd ZdZdZddd�ZdS )� PostLoaderz;A relationship loader that emits a second SELECT statement.r: Nc C sN |j jptjj| }|�� }t�d|i�}|rF|j� dd �}|dk} nd }d} |d ur�| j j srt � d| j � d���|j� dt| �� �|�}| s�|dk r�|d||fS | s�|�dt| �� �|d i�}tj�||| j �r�|d||fS || j } || j } | �|jd ��sB|�r(| jd |k�rB|d||fS n| �| j��rB|d||fS |d ||fS ) NZsa_top_level_orm_context�recursion_depth���Fz'recursion_depth option on relationship z0 not valid for non-self-referential relationshipZ_recursion_depth_r r �loaderr& T)ra � current_pathr3 � PathRegistry�rootZ_get_top_level_contextr r& r� rJ rZ Z_is_self_referentialr� r� r �id�unionr �PostLoadZ path_exists�containsr �length�contains_mapperrN ) r\ rk rc rd � join_depthr4 Ztop_level_contextr r? Zunlimited_recursion� path_w_propZeffective_path_w_propr: r: r; �_setup_for_recursion sl �� ��� ���� ��z PostLoader._setup_for_recursion)N)ro rp rq rr rs rM r: r: r: r; r> s r> r� c s8 e Zd ZdZ� fdd�Zdd� Zdd� Zdd � Z� ZS ) �ImmediateLoader�rK c s t � �||� | jj| _d S r2 �rX rY rZ rK r[ r^ r: r; rY W s zImmediateLoader.__init__c C s | j �d��|� d S �N�)r� r� �rZ r� r� r� r: r: r; r� [ s ��z$ImmediateLoader.init_class_attributec C sl |j jjsd S | �|||| j�\} } } } | s:tjtjB } n tj tjB } t j � || | j | j| j|| | | � d S r2 )ra r� �_enable_eagerloadsrM rK r ZPASSIVE_NO_FETCH_RELATEDr r r r rG �callable_for_pathrH rZ �_load_for_path)r\ rk rb rc rd rN rl re rm r4 � run_loaderr r? �flagsr: r: r; rn ` s, � �z$ImmediateLoader.create_row_processorc C s� |r.t |jj�} ||�� f| _|�� } | f} n|} d} | j} | j�d�} |D ]P\}}|j }|sf| |vrL| j ||| | |d�}|t t j fvrL|�| ��|||� qLd S )Nr: rR )r r r )r# rc r� Z_recurserk �_truncate_recursiver4 rZ r� r r� r r r� �get_impl�set_committed_value)r\ rk rc �states� load_onlyrd rX r? r Znew_optr r r4 � lazyloaderr� � overwriter� r� r: r: r; rV � s8 � �� �z ImmediateLoader._load_for_path) ro rp rq rs rY r� rn rV rt r: r: r^ r; rN S s *rN �subqueryc s� e Zd ZdZ� fdd�Zdd� Zdd� Zdd � Zd d � Zd d � Z dd� Z dd� Z G dd� d�Z dd� Z dd� Zdd� Zdd� Z� ZS ) �SubqueryLoaderrO c s t � �||� | jj| _d S r2 rP r[ r^ r: r; rY � s zSubqueryLoader.__init__c C s | j �d��|� d S rQ rS r� r: r: r; r� � s ��z#SubqueryLoader.init_class_attributec s� |}|j }t�|d �}| j�|�rB| j|d u rB| j| j � }n||d � }|r�|j| jj| �t |�t �� }|r��t j � || d � �7 �n|�|j } � �fdd�| D �} � | |�fS )Nr r c s& g | ] }t �jd j� j| j��qS �r )�getattrrc r� r r4 r� ��leftmost_mapperZ new_subq_pathr: r; r� � s � �z0SubqueryLoader._get_leftmost.<locals>.<listcomp>)rc r3 Z_class_to_mapperrH �isarZ � _entities� entity_zeror* r1 r rC Zcoerce� local_columns) r\ �orig_query_entity_index� subq_pathZcurrent_compile_state�is_rootZgiven_subq_pathZ subq_mapperZ leftmost_prop� additionalZ leftmost_cols� leftmost_attrr: rd r; � _get_leftmost� s4 � ��� � �z SubqueryLoader._get_leftmostc C s0 |� � �d �}tj�tj�}|j�|j� |}|js`d|_|j j |gdd� t ||d�D ��R � |� dd� |D �|� � �} | |_|j} | du r�d|_n6| d u r�dd� | D �D ] } t| ��| j�s�d|_ q�q�|js�d |_|jdu �r|j�rt�| |j�} | �r|�| | � |�t��� } t j || dd �}|S ) NFc S s h | ]}|d dur|d �qS )r� Nr: )r� �entr: r: r; � <setcomp> s �z?SubqueryLoader._generate_from_original_query.<locals>.<setcomp>)ra c S s g | ]}t j�t jj|��qS r: )r* Z coercions�expectZrolesZColumnsClauseRole)r� r r: r: r; r� / s �z@SubqueryLoader._generate_from_original_query.<locals>.<listcomp>Tc S s h | ] }|j �qS r: )�tabler� r: r: r; rq > r� r: ��use_mapper_path) Z_cloneZ correlater �Query�__new__�__dict__�updateZ _from_objZ_enable_assertionsr% Znon_generativer Z_adapt_col_listZ_get_current_adapterr �distinct_target_keyZ _distinctr� r r~ Z_has_row_limiting_clauser+ r� Z expand_column_list_from_order_byZ _set_entitiesZset_label_styler, r` r3 r% )r\ �orig_compile_state� orig_queryre rn �leftmost_relationshipZ orig_entity�qZq2Z target_colsrz �tZto_addZembed_q� left_aliasr: r: r; � _generate_from_original_query� sV ��������z,SubqueryLoader._generate_from_original_queryc s� g }t |�� �}t|�D ]N\}\}}|dkrR||d d j}|�|�rL|n|} n|} |�| |jf� qt|�dk rz|� n.t|d d �} | j r�| j � nt j | j dd�� �j j} � �fdd�| D �} || � fS ) Nr r r& r@ Trt c s g | ]}t � �jj| j��qS r: )rc rH r r4 r� �� parent_aliasr\ r: r; r� � s �z2SubqueryLoader._prep_for_joins.<locals>.<listcomp>)r� �pairs� enumeraterN rf rF r4 r1 r( r� r� r3 r% rZ ri ) r\ r� rk �to_joinr� �irN r7 Z prev_mapperZ to_appendr� � local_cols� local_attrr: r� r; �_prep_for_joinsZ s* � �z SubqueryLoader._prep_for_joinsc C s0 t |�}|dkr,t||d d ��|�g}n�|dkrft||d d ��|�t||d d ��|�g}n�|dk�rdd� |dd� D �}g }|r�|�d�} t| d | d �} |r�| �|d d �} n | �|�} |�| � q�t||d d ��|d j�g| t||d d ��|�g }|D ]} |�| �}�q|S )Nr r r& r@ c S s: g | ]2}t |d �js$t�|d �n|d j|d f�qS )r r )r( r� r3 r% r� )r� �itemr: r: r; r� � s � ��z/SubqueryLoader._apply_joins.<locals>.<listcomp>)r1 rc �of_type�poprF rH �join) r\ r~ r� r� r� �effective_entityZltjZmiddle�innerr� �attrr: r: r; � _apply_joins� sD ��� � ����� zSubqueryLoader._apply_joinsc C sB |j }|r*|jr*|t�| j|�|��f7 }|�|�}|j|� }|S r2 )r) r� r3 r( r� r9 Z_with_current_path�options) r\ rk r~ rk �rewritten_pathr| r� rd � new_optionsr: r: r; �_setup_options� s �� z SubqueryLoader._setup_optionsc s& � j jr"� fdd�}|�|� j �}|S )Nc s | j tt�� jj��7 _ d S r2 ��eager_order_by�tupler r� rZ r� �r r� r: r; �_setup_outermost_orderby� s �zISubqueryLoader._setup_outermost_orderby.<locals>._setup_outermost_orderby)rZ r� �_add_context_option)r\ r~ r� r: r� r; r� � s �z'SubqueryLoader._setup_outermost_orderbyc @ s4 e Zd ZdZdZdd� Zdd� Zdd� Zd d � Zd S ) z SubqueryLoader._SubqCollectionsz�Given a :class:`_query.Query` used to emit the "subquery load", provide a load interface that executes the query at the first moment a value is needed. �r� r r r� �subq�_datac C s4 |j | _ |j| _|j| _|jp i | _|| _d | _d S r2 r� )r\ rk r� r: r: r; rY � s z(SubqueryLoader._SubqCollections.__init__c C s | j d u r| �� | j �||�S r2 )r� �_loadrJ )r\ r4 �defaultr: r: r; rJ s z#SubqueryLoader._SubqCollections.getc C s� t �t�| _| j}|jd u s J �|�| j�}| jjr<|� � }t|� | j ��}t � |dd� �D ]"\}}| j| � dd� |D �� q\d S )Nc S s | dd � S )Nr r: ��xr: r: r; r< r� z7SubqueryLoader._SubqCollections._load.<locals>.<lambda>c s s | ]}|d V qdS )r Nr: �r� �vvr: r: r; r� r� z8SubqueryLoader._SubqCollections._load.<locals>.<genexpr>)� collections� defaultdictr� r� r� r� Z with_sessionr Z_populate_existingr: r� � itertools�groupby�extend)r\ r~ �rowsr� �vr: r: r; r� s z%SubqueryLoader._SubqCollections._loadc C s | j d u r| �� d S r2 )r� r� )r\ r� r� r� r: r: r; rA s z&SubqueryLoader._SubqCollections.loaderN) ro rp rq rr rs rY rJ r� rA r: r: r: r; �_SubqCollections� s r� c C s� |j }|jjr|jjrd S |j�|�}d|_|| j }|�|j dd �} | d urT| } n| j } |j j �dt jjt jjf�\} } | t jju } | | } | | } |j j �dtf|j �}t�|d�}|jr�|jjd u r�t�d| |f � |j}|j|dd�}| �|| || �\}}}} | �||||||�}t � | �}|j j � |j dtf|d| | fi�|_ |� d�}| � || �\}}}|j!|� }| �"||||| �}| �#||| | || |�}| �$|�}|S ) NT�path_with_polymorphic)Zsubquery_pathsNr| �ormz�subqueryloader for "%s" must invoke lambda callable at %r in order to produce a new query, decreasing the efficiency of caching for this statement. Consider using selectinload() for more effective full-lambda cachingF)�legacy)%ra r� rT Z_for_refresh_staterg �indexZloaders_require_bufferingrZ rJ r r� r r' r3 rC rD ra r Z _get_plugin_class_for_pluginZ_is_lambda_elementr r r r2 Z _resolvedZ_create_entities_collectionro r� rv r- r Z_set_enable_single_critr� Z add_columnsr� r� r� )r\ rk rb rc r� rd re ra rj �with_poly_entityr� rk r� rl r| Zcompile_state_clsr{ re rn r} r� r~ r� r� r� r: r: r; �_setup_query_from_rowproc# s� �� �� �� ��� �� � �� � �� z(SubqueryLoader._setup_query_from_rowprocc s� |r&|j jd ur&|j jjr&t�dd� |jrD| �||||||� |�S | �|||| j�\} } } } | sfd S t |j t �svd S | j j | j jjs�t�d| ��t|�dkr�t�|j| j �s�d S nt�|d | j �s�d S | �||||d |� �} | d u r�d S | jd u �sJ �|| j }| jj} |�|jd�} | d u �rH| � || �} |� |jd| � � �r`� fdd�| D �} | j �r|| � ||| | |� n| � ||| | |� d S ) Nz�The subqueryload loader option is not compatible with DML statements such as INSERT, UPDATE. Only SELECT may be used.This warning will become an exception in a future release.�2.0�J'%s' does not support object population - eager loading cannot be applied.r r@ r� c s g | ]}� j | �qS r: rV r� �re r: r; r� r� z7SubqueryLoader.create_row_processor.<locals>.<listcomp>)!ra � statement�is_dmlr �warn_deprecatedr� r� rM rK r� r rH rK r4 �impl�supports_populationr� r� r1 r3 � _entity_isarh r� r� rZ ri rJ r r� r� r> �_create_collection_loader�_create_scalar_loader)r\ rk rb rc rd rN rl re rm �_rW r� r� r� r: r� r; rn � s� � ���� � �� � � �z#SubqueryLoader.create_row_processorc sp |� |��� ��fdd����fdd�}|d ��j�f� |d ��j|f� |jrl|d ��j� jf� d S )Nc s* � � �|�d�}| ��j��| ||� d S )Nr: )rJ rZ r4 r[ )r� r� r� � collection�r� r\ � tuple_getterr: r; �load_collection_from_subq s �zKSubqueryLoader._create_collection_loader.<locals>.load_collection_from_subqc s �j |vr� | ||� d S r2 r6 r� )r� r\ r: r; �&load_collection_from_subq_existing_row s zXSubqueryLoader._create_collection_loader.<locals>.load_collection_from_subq_existing_rowr� �existing�eager�Z _tuple_getterrF r4 �invoke_all_eagersrA )r\ rk rl r� r� rm r� r: )r� r� r\ r� r; r� s �z(SubqueryLoader._create_collection_loaderc sp |� |��� ��fdd����fdd�}|d ��j�f� |d ��j|f� |jrl|d ��j� jf� d S )Nc sL � � �|�d�}t|�dkr*t�d� � |d }| ��j��| ||� d S )Nr2 r �LMultiple rows returned with uselist=False for eagerly-loaded attribute '%s' r )rJ r1 r r2 rZ r4 r[ )r� r� r� r� Zscalarr� r: r; �load_scalar_from_subq, s ��zCSubqueryLoader._create_scalar_loader.<locals>.load_scalar_from_subqc s �j |vr� | ||� d S r2 r6 r� )r� r\ r: r; �"load_scalar_from_subq_existing_row7 s zPSubqueryLoader._create_scalar_loader.<locals>.load_scalar_from_subq_existing_rowr� r� r� r� )r\ rk rl r� r� rm r� r: )r� r� r\ r� r; r� ' s �z$SubqueryLoader._create_scalar_loader)ro rp rq rs rY r� ro r� r� r� r� r� r� r� rn r� r� rt r: r: r^ r; ra � s 1d/6"4 era Zjoinedc s� e Zd ZdZdZ� fdd�Zdd� Zd d d �Zd d � Zd d� Z dd� Z dd� Z d!ddd�dd�Z dd� Z dd� Zd d � Zd d � Z� ZS )"� JoinedLoaderz[Provide loading behavior for a :class:`.Relationship` using joined eager loading. rK c s t � �||� | jj| _d S r2 rP r[ r^ r: r; rY N s zJoinedLoader.__init__c C s | j �d��|� d S rQ rS r� r: r: r; r� R s ��z!JoinedLoader.init_class_attributeNFc K st |j js dS |r0|jdur0|jjr0t�dd� n | jr<d|_|| j }|rZ| � |||j �nd} | dur�| � ||||| �\} }} n`|� |j d�s�| j r�|jd | j kr�dS n|�| j�r�dS | �||||||||�\} }} }d|_|�|j dd�} | du�rt| �j}nd}|| j }tj|| j||| | || j|d � tj�|j�}|�rp| du�r^t � d ��nd d � |jD �|_dS ) z@Add a left outer join to the statement that's being constructed.Nz�The joinedload loader option is not compatible with DML statements such as INSERT, UPDATE. Only SELECT may be used.This warning will become an exception in a future release.r� TFrA r& r� )�with_polymorphic� parentmapper�chained_from_outerjoinz�Detected unaliased columns when generating joined load. Make sure to use aliased=True or flat=True when using joined loading with with_polymorphic().c S s g | ]}|d ur|�qS r2 r: r� r: r: r; r� � s z,JoinedLoader.setup_query.<locals>.<listcomp>) r� rT r� r� r r� r> �multi_row_eager_loadersrZ � _init_user_defined_eager_procr �$_setup_query_on_user_defined_adapterrH rK rI rJ rN �_generate_row_adapterZeager_adding_joinsrJ r( Zwith_polymorphic_mappersr� r Z_setup_entity_queryZNONE_SETr� �secondary_columnsr� r� )r\ ra rb rc rd re rf r� r� rg �user_defined_adapter�clauses�add_to_collectionr� r� Z has_nonesr: r: r; ri W s� ���� ������ ��� � � ��zJoinedLoader.setup_queryc C s� d|j vrdS |jj}|�|jdd�}|dur2|S |j d }|dd � \}}|d ur�t|t�rj|j�|�}t j t j j |j ||j jdd�}nF|�|jd�r�|�|jd�} t j t j j| |j jd�}n|j�|j d �}|�|d|� |S )NZeager_from_aliasF� user_defined_eager_row_processor���)� selectabler� Zlimit_on_entityr� )r� )r� rc rH rJ r r� r� r� �aliasr3 � ORMAdapter�_TraceAdaptRoleZ JOINEDLOAD_USER_DEFINED_ALIASrN r� rH Z JOINEDLOAD_PATH_WITH_POLYMORPHICZ_polymorphic_adaptersr� ) r\ rd ra Ztarget_attributesrc re r� Z root_mapperr7 r� r: r: r; r� � sP � ������z*JoinedLoader._init_user_defined_eager_procc C sV |� |�}|r.|r.|�|�}|�|jd|� n|rF|}|�|jd|� |j}|||fS )Nr� )Z_get_entity_clauses�wrapr� r �primary_columns)r\ rk r� rc re r� r� r: r: r; r� s" ��z1JoinedLoader._setup_query_on_user_defined_adapterc C s |� |jdd �} | r| } nDt| j�} | jr2| j} nd } tj| j| d urR| j dd�nd ddd�} t| �} | j d| ftj tj j | | jjdddd�}|js�J �|d ur�|j� d| jj�n| jj}|s�d}|j�| j||||||||r�|jnd f � |j}|�|jd |� ||||fS ) Nr� T)�flat)r� r� ru Zjoinedloader_ormadapterF)r� Zadapt_requiredZallow_label_resolveZanonymize_labels� innerjoinr: �eager_row_processor)rJ r r( r� r� r� r3 r% rN Z_anonymous_fromclauseZ_memor� r� ZJOINEDLOAD_MEMOIZED_ADAPTERr� r� rZ r� Zcreate_eager_joinsrF �_create_eager_joinr� r� r� )r\ ra r� rc rd re rf r� r� r� Zto_adaptZinspZalt_selectableZ to_adapt_inspr� r� r� r: r: r; r� ) sd � �� � �� ��z"JoinedLoader._generate_row_adapterc sb |d u r|j } n|} |jo |j} d } ||jvr~| s~|jr~t�|j|j�} t| �dkr^t � d��| r~|j| d }| d | } }| d u r�||j } }|j� | |�}|�rt |dd�r�|j �| �� j�r�| n� j�}t |j� j� j�}n t tj� j|jdd�� j� j�}n� j}|j�sJ �| �p8| �p8|dk�p8|jj}| }|j�d � j fd �}|�rr|t� fd d �|D ��7 }|�r�tj ||j || �p�|jj�p�|�o�t |t j �� j|� j |d �}n� � ||d ||||�}||j| < |j|_!|�s0t�"� jj#�D ]4}| j$j%�&|��r�|�r |j'| }|�(||j)� �q�� jj*�r^| j+t|j,�-t.�/� jj*���7 _+d S )Nr z�Can't identify which query entity in which to joined eager load from. Please use an exact match when specifying the join path.r r� FTrt Zunnested�additional_entity_criteriar: c 3 s | ]}|j r|�� j�V qd S r2 )Zpropagate_to_loadersZ_resolve_where_criteriarN )r� Zaer� r: r; r� � s �z2JoinedLoader._create_eager_join.<locals>.<genexpr>��isouter� _left_memo� _right_memor� r� )0rN r� Z_should_nest_selectableZ eager_joinsZ from_clausesr� Z#find_left_clause_that_matches_givenr� r1 r� r� � setdefaultrc � aliased_inspZ_entity_for_mapperrf rH r� r4 rZ r3 r% r� rh Zrepresents_outer_joinZglobal_attributesrJ r� �_ORMJoinr� r* ZJoin�_splice_nested_inner_joinZstop_onZ _find_columnsZ primaryjoinZpersist_selectablerh Zcontains_columnrW r` r� r� r� �_target_adapterZcopy_and_processr r� )r\ ra rb rc re r� r� r� r� r r� Zshould_nest_selectableZquery_entity_keyZindexesZclauseZdefault_towrapZtowrapZefm�onclauseZattach_on_outsideZextra_join_criteriar� � eagerjoinr� r: r� r; r� x s� ����� ��� �� �� ��� �� �� � � � ��z JoinedLoader._create_eager_joinz#Union[Mapper, None, Literal[False]]z$Optional[path_registry.PathRegistry]�� entity_inside_join_structure�detected_existing_pathc C s� ||d u sJ �|du r(t |tj�s(J �t |tjj�rN| �|||j||||�S t |tj��rB|j} | j|||j |||| d ur�| d j nd d�} | d ur�|j s�| j s�|� | �} n tj|j | |j|j |jd�} | j| _| S | j|||j ||||j| d�} | d u�r&tj| |j |j|j |jd�} | j| _| S |du �r>d�s>J d��d S |�|��sRd S |�r�t|�d k�r�|d |u �sxJ �|d d� |jd d� k�r�d S tj||j|d|||d j |d �S ) Nr� Fr@ )r� )r� r� r� )r� r� z9assertion failed attempting to produce joined eager loadsr& ���r r� )r� r3 r� r* r� Z FromGroupingr� �elementr� �rightrN r� Z_splice_into_center�leftr� r� r� rf r1 rc r� ) r\ rc Z entity_we_want_to_splice_ontoZjoin_objr� r� r r� r� Zjoin_right_pathZ target_joinr� r: r: r; r� s� � � � �� � �� $ �z&JoinedLoader._splice_nested_inner_joinc C s� |j }|r| �|||j�nd}|durP|}|jrB|rB|�|j�}qj|jrj|j}n|�|jd�}|d u rjdS | j�||�r||S dS d S )NFr� )ra r� r Zcompound_eager_adapterr� rJ rN Z_result_has_identity_key) r\ rk rl re rc rd ra r� � decoratorr: r: r; �_create_eager_adapter� s. ��� ��z"JoinedLoader._create_eager_adapterc C s� |j jjsd S | jj| j jjs.t� d| ��| j r:d|_ || j } | � |||| |�} | dur�| j} t�|| j||| | j | �} | j s�| �|| | |� q�| �|| | |� n | j �d��||||||||� d S )Nr� TFrR )ra r� rT rH rK r4 r� r� r� r� r> Zloaders_require_uniquingrZ r� r Z_instance_processorrN r� r� r� r� rn ) r\ rk rb rc rd rN rl re rm Zour_pathZ eager_adapterr4 � _instancer: r: r; rn � sR �� �� ���z!JoinedLoader.create_row_processorc sr � ��fdd�}� ��fdd�}� fdd�}|d � | j|f� |d � | j|f� �jrn|d � | j|f� d S ) Nc sF t �| |��}t�|d�}|�j | �f< � |�}|d urB|�|� d S �NZappend_without_event�r r� r ZUniqueAppenderrF )r� r� r� r� � result_list�inst�r� rk r4 r: r; �#load_collection_from_joined_new_row' s �zSJoinedLoader._create_collection_loader.<locals>.load_collection_from_joined_new_rowc sd | �f�j v r �j | �f }n(t �| |��}t�|d�}|�j | �f< � |�}|d ur`|�|� d S r� r� )r� r� r� r� r� r� r� r: r; �(load_collection_from_joined_existing_row4 s ��zXJoinedLoader._create_collection_loader.<locals>.load_collection_from_joined_existing_rowc s � |� d S r2 r: r� �r� r: r; � load_collection_from_joined_execG s zPJoinedLoader._create_collection_loader.<locals>.load_collection_from_joined_execr� r� r� �rF r4 r� )r\ rk r4 r� rm r� r r r: r� r; r� & s ���z&JoinedLoader._create_collection_loaderc sp � �fdd�}� ��fdd�}� fdd�}|d � �j|f� |d � �j|f� |jrl|d � �j|f� d S ) Nc s � |�|�< d S r2 r: r� )r� r4 r: r; � load_scalar_from_joined_new_rowV s zKJoinedLoader._create_scalar_loader.<locals>.load_scalar_from_joined_new_rowc s8 � |�}�|v r,||� ur4t �d� � n||�< d S )Nr� )r r2 )r� r� r� r� �r� r4 r\ r: r; �$load_scalar_from_joined_existing_row[ s �� zPJoinedLoader._create_scalar_loader.<locals>.load_scalar_from_joined_existing_rowc s � |� d S r2 r: r� r r: r; � load_scalar_from_joined_execn s zHJoinedLoader._create_scalar_loader.<locals>.load_scalar_from_joined_execr� r� r� r )r\ rk r4 r� rm r r r r: r r; r� U s ��z"JoinedLoader._create_scalar_loader)NNF)FN)ro rp rq rr rs rY r� ri r� r� r� r� r� r� rn r� r� rt r: r: r^ r; r� C s, � 9O * � .$>/r� Zselectinc st e Zd ZdZe�dg d��ZdZ� fdd�Zdd� Z d d � Z d d � Z d d� Z dd� Z dd� Zdd� Zdd� Z� ZS )�SelectInLoader)rK � omit_join� _parent_alias� _query_info�_fallback_query_infoZ queryinfo)�load_only_child�load_with_join�in_expr�pk_cols�zero_idx�child_lookup_colsi� c s� t � �||� | jj| _| jjtju }| jjd ur>| jj| _n<| j�d�}|rX|j | _n"| j j d j |j dd| j jd�| _| jr�|r�| �� | _| �� | _q�| �� | _n | �� | _d S )NrR r TFr� )rX rY rZ rK rM r r� r r� r� rH r� r� r� r� �_init_for_omit_join_m2or �_init_for_joinr �_init_for_omit_join)r\ rH r] Zis_m2or^ r^ r: r; rY � s, � � zSelectInLoader.__init__c s� t �jjj�� � �� �fdd�t� �D �� � fdd��jjD � }}t|�dkrbt j |� }d}n |d }d}�� dd|||d �S ) Nc 3 s0 | ](}�j j�|d �D ]}|� | fV qqdS )r: N)rH r� rJ )r� r� �equiv��pk_to_fkr\ r: r; r� � s �z5SelectInLoader._init_for_omit_join.<locals>.<genexpr>c s g | ]}|� v r� | �qS r: r: �r� r� )r r: r; r� � s z6SelectInLoader._init_for_omit_join.<locals>.<listcomp>r Fr T) r rZ r� Zlocal_remote_pairsry r� rH r~ r1 r* �tuple_� query_info)r\ r Zfk_colsr r r: r r; r � s �� � z"SelectInLoader._init_for_omit_joinc sb | j j}t|�dkr$tj|� }d}n |d }d}| j�d�� � fdd�|D �}| �dd||||�S )Nr Fr TrR c s g | ]}� j | �qS r: r r �r^ r: r; r� � r� z:SelectInLoader._init_for_omit_join_m2o.<locals>.<listcomp>)rN r~ r1 r* r rZ r� r )r\ r r r Z lookup_colsr: r r; r � s �z&SelectInLoader._init_for_omit_join_m2oc sj t | jj�| _t| j�� � fdd�| jjD �}t|�dkrJtj|� }d}n |d }d}| � dd|||d �S )Nc s g | ]}� � |��qS r: ��_adapt_elementr �Zpa_inspr: r; r� � s z1SelectInLoader._init_for_join.<locals>.<listcomp>r Fr T) r% rH rL r r( r~ r1 r* r r )r\ r r r r: r r; r � s � z SelectInLoader._init_for_joinc C s | j �d��|� d S rQ rS r� r: r: r; r� � s ��z#SelectInLoader.init_class_attributec C s |j r | �||||||||�S | j|||| jd�\} } } } | sBd S |jjjsPd S | jj| j j j spt � d| ��t|�dkr�t�|j| j�s�d S nt�|d | j�s�d S | } || j }|�|jdd �}|d ur�t|�}n| j}tj�|| | j| j| j||| | � d S )NrO r� r r@ r� )r� r� rM rK ra r� rT rH rK r4 r� r� r� r� r1 r3 r� rh rZ rJ r r( r� r rG rU rV )r\ rk rb rc rd rN rl re rm r4 rW r r? Z selectin_pathrL r� r� r: r: r; rn � sj � �� �� � �z#SelectInLoader.create_row_processorc s� |r�j |vrd S �j} | jr�t�t�} g } �j�|D ]l\�} �j�t���fdd�| j D ��} t j | v rt�j } q�d | vr�| | � ��| f� q6| � ��| f� q6| js�dd� |D �} | j}| j}| js�jr�fdd�|D �}��|�}tjdg|�R � }|�� }��� }tj||gttjd�d�d �}| j�s@|���}n$|��j �� t �j �j j �� ���}|�!|�"t#�$d ���}� j%j&}|�j }|� j'u �r�|j(}n&|j(}� j'j(}� fd d�t)||�D �}|�r�|j*�r�|t�+�|�,� ��f7 }|d u�r�|�-� }|j.|� }|�/d |i�}� j0�r*|j1d d�}�j j2�r�| j�sj�j j2}�j�r^�fdd�|D �}|j2|� }n�fdd�}|�3|�j �}| j�r���4| | | |� |� n��5| | |� |� d S )Nc 3 s" | ]}� j ��|tjd �V qdS )r N)r r ZPASSIVE_NO_FETCH)r� Zlk)rN r� � state_dictr: r; r� S s ��z0SelectInLoader._load_for_path.<locals>.<genexpr>c S s$ g | ] \}}|j d ||j|f�qS )r )r4 r )r� r� r_ r: r: r; r� p s �z1SelectInLoader._load_for_path.<locals>.<listcomp>c s g | ]}� � |��qS r: r r �r� r: r; r� � s r r� )Zcompile_state_pluginZplugin_subject)r r r� r � primary_keysc s g | ]\}}|� � |��qS r: )Z'_adapt_cached_option_to_uncached_option)r� Zorig_optZ uncached_opt)rk r: r; r� � s ��r T)r: c s g | ]}� � |��qS r: r r� r! r: r; r� � s �c s | j tt�� jj��7 _ d S r2 r� r� r� r: r; r� � s �z?SelectInLoader._load_for_path.<locals>._setup_outermost_orderby)6r4 r r r� r� r� rH r r� r r r� r rF r r r r� r r3 ZBundler" r- r# r, r r$ r% r r� rc rZ r� �filterZin_r* r� ra Zselect_statementZuser_passed_queryr) �zipr� r( r9 rY r� Z_update_compile_optionsr: r r� r� �_load_via_child�_load_via_parent)r\ rk rc r\ r] r� rd r? r r � our_states� none_statesr_ Z related_identr r Z bundle_entZ bundle_sqlZ entity_sqlr~ r| r4 r� Zcached_optionsZuncached_optionsr� r� r: )rk r� rN r\ r� r r; rV ; s� � �� � �� �� �� �� � �� �z SelectInLoader._load_for_pathc s� | j }t|�}|r�|d| j� } || jd � }dd� |jj|d� fdd�| D �i|d��� D �} | D ]T} | �| d �} || D ]:\} }}|s�| j|v r�q|| �| j�� | ||s�| n| g� q|qdq|D ]0\} }}|s�| j|v r�q�| �| j�� | |d � q�d S )Nr c S s i | ]\}}||�qS r: r: )r� r� r� r: r: r; � <dictcomp> s �z2SelectInLoader._load_via_child.<locals>.<dictcomp>r" c s g | ]}� j r|d n|�qS rb �r )r� r4 �r r: r; r� # s �z2SelectInLoader._load_via_child.<locals>.<listcomp>�r� r ) r> �sorted� _chunksizer� r/ r� rJ r4 rZ r[ )r\ r' r( r r~ rk r r> Zour_keys�chunk�datar4 Z related_objr� r� r_ r: r+ r; r% s: ���� � z SelectInLoader._load_via_childc s$ | j }|rdnd }|�r |d| j� }|| jd � }� fdd�|D �} t�t�} t�|jj|d| i|d�� � dd� �D ] \} } | | � d d � | D �� qv|D ]�\} }}}|s�| j |v r�q�| � | |�}|�s|�rt |�d kr�t�d | � |�| j ��|||d � q�|�| j ��|||� q�qd S ) Nr: r c s& g | ] \}}}}� j r |d n|�qS rb r* )r� r4 r� r r_ r+ r: r; r� O s �z3SelectInLoader._load_via_parent.<locals>.<listcomp>r" r, c S s | d S ry r: r� r: r: r; r< [ r� z1SelectInLoader._load_via_parent.<locals>.<lambda>c s s | ]}|d V qdS )r Nr: r� r: r: r; r� ] r� z2SelectInLoader._load_via_parent.<locals>.<genexpr>r r� )r> r. r� r� r� r� r� r� r/ r� r� r4 rJ r1 r r2 rZ r[ )r\ r' r r~ rk r r> Z _empty_resultr/ r" r0 r� r� r4 r� r r_ r� r: r+ r; r& E sF � �� �� � �z SelectInLoader._load_via_parent)ro rp rq rs r� � namedtupler r. rY r r r r� rn rV r% r& rt r: r: r^ r; r { s � P T7r c sT �fdd�� � fdd�}� fdd�}t j| d|dddd � t j| d |dddd � d S ) Nc sT |d urP|j � j krP|�t�|��}|rP||urPtjdt�|�| j� f dd��|S )NzsInstance %s is already associated with an instance of %s via its %s attribute, and is only allowed a single parent.Zbbf1)�code) r4 � hasparentr Zinstance_stater� r� r3 Z instance_strrL )r� r� �oldvalue� initiatorr3 )r7 r: r; � _do_checkx s ��z*single_parent_validator.<locals>._do_checkc s � | |d |�S r2 r: )r� r� r5 �r6 r: r; rF � s z'single_parent_validator.<locals>.appendc s � | |||�S r2 r: )r� r� r4 r5 r7 r: r; �set_� s z%single_parent_validator.<locals>.set_rF T)�raw�retvalrC r� )r' �listen)r6 r7 rF r8 r: )r6 r7 r; rG w s �rG )NNNNFN)Wrr � __future__r r� r� �typingr r r r r r � r r r� r r r r r r r r r3 �baser r r r r r r rk r r r r r r r� r! r� r" r r# r$ r% r' r� r( r) r* r� r+ Zsql.selectabler, r- Z util.typingr. rN r/ r0 Z sql.elementsr1 rR ZColumnPropertyZ strategy_forrU Z class_loggerru r� r� r� r� r� r� Z MemoizedSlotsZ Identifiedr� r8 r> rN ra r� r rG r: r: r: r; �<module> s� � Q+Z W� 0% & � 24L c ; } sqlalchemy/orm/__pycache__/mapped_collection.cpython-39.pyc 0000644 00000043051 15125143220 0020023 0 ustar 00 a ��Jh�L � @ s2 d dl mZ d dlZd dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlm Z d d lm Z d d lm Z d d lm Z d d lm Z d d lmZ d dlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddl m Z ddl m Z ddl m Z e �r^dd lm!Z! dd lm"Z" dd lm#Z# dd l$m%Z% ed ed!�Z&ed"ed!�Z'G d#d$� d$ee& �Z(G d%d&� d&e(e& �Z)d'd(�d)d*d+d,�d-d.�Z*G d/d0� d0�Z+d'd(�d1d*d2d3�d4d5�Z,d'd(�d6d*d7d8�d9d:�Z-G d;d<� d<ee&e'f �Z.d6d*d+d8�d=d>�Z/e.Z0e-Z1e,Z2e*Z3dS )?� )� annotationsN)�Any)�Callable)�Dict)�Generic)�List)�Optional)�Sequence)�Tuple)�Type)� TYPE_CHECKING)�TypeVar)�Union� )�base)� collection)�collection_adapter� )�exc)�util)� coercions)� expression)�roles)�Missing)� MissingOr)�Literal)�AttributeEventToken)�Mapper)�CollectionAdapter)� ColumnElement�_KT)�bound�_VTc @ sR e Zd ZdZdZddd�dd�Zdd �d d �Zd dd �dd�Zddd�dd�ZdS )�_PlainColumnGetterz�Plain column getter, stores collection of Column objects directly. Serializes to a :class:`._SerializableColumnGetterV2` which has more expensive __call__() performance and some rare caveats. )�cols� composite� Sequence[ColumnElement[_KT]]�None�r$ �returnc C s || _ t|�dk| _d S �Nr )r$ �lenr% )�selfr$ � r- �U/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/mapped_collection.py�__init__: s z_PlainColumnGetter.__init__�cTuple[Type[_SerializableColumnGetterV2[_KT]], Tuple[Sequence[Tuple[Optional[str], Optional[str]]]]]�r) c C s t �| j�S �N)�_SerializableColumnGetterV2�_reduce_from_colsr$ �r, r- r- r. � __reduce__> s z _PlainColumnGetter.__reduce__� Mapper[_KT]��mapperr) c C s | j S r2 )r$ )r, r9 r- r- r. �_colsF s z_PlainColumnGetter._colsr z&MissingOr[Union[_KT, Tuple[_KT, ...]]])�valuer) c sX t �|��t ���� � �fdd�| �� �D �}| jr<t|�S |d }|d u rPtS |S d S )Nc s g | ]}� � ��j|��qS r- )Z_get_state_attr_by_column�dict)�.0�col��m�stater- r. � <listcomp>M s �z/_PlainColumnGetter.__call__.<locals>.<listcomp>r )r �instance_stateZ _state_mapperr: r% �tupler )r, r; �key�objr- r? r. �__call__I s �z_PlainColumnGetter.__call__N) �__name__� __module__� __qualname__�__doc__� __slots__r/ r6 r: rG r- r- r- r. r# . s r# c @ sV e Zd ZdZdZddd�dd�Zdd �d d �Zed dd �dd��Zdd d�dd�Z dS )r3 a< Updated serializable getter which deals with multi-table mapped classes. Two extremely unusual cases are not supported. Mappings which have tables across multiple metadata objects, or which are mapped to non-Table selectables linked across inheriting mappers may fail to function here. )�colkeysz-Sequence[Tuple[Optional[str], Optional[str]]]r' )rM r) c C s || _ t|�dk| _d S r* )rM r+ r% )r, rM r- r- r. r/ i s z$_SerializableColumnGetterV2.__init__r0 r1 c C s | j | jffS r2 )� __class__rM r5 r- r- r. r6 o s z&_SerializableColumnGetterV2.__reduce__r& r( c s, ddd�dd�� � fdd�|D �}t |ffS )NzColumnElement[_KT]z Optional[str])�cr) c S s t | jtj�sd S | jjS d S r2 )� isinstance�tabler Z TableClauserE )rO r- r- r. � _table_key| s zA_SerializableColumnGetterV2._reduce_from_cols.<locals>._table_keyc s g | ]}|j � |�f�qS r- )rE )r= rO �rR r- r. rB � � zA_SerializableColumnGetterV2._reduce_from_cols.<locals>.<listcomp>)r3 )�clsr$ rM r- rS r. r4 w s z-_SerializableColumnGetterV2._reduce_from_colsr7 r8 c C sh g }t |jdd �}| jD ]J\}}|d u s8|d u s8||vrL|�|jj| � q|�|j| j| � q|S )N�metadata)�getattrZ local_tablerM �appendrO Ztables)r, r9 r$ rV ZckeyZtkeyr- r- r. r: � s z!_SerializableColumnGetterV2._colsN) rH rI rJ rK rL r/ r6 � classmethodr4 r: r- r- r- r. r3 [ s r3 F�� ignore_unpopulated_attributez&Union[Type[_KT], Callable[[_KT], _VT]]�boolzType[KeyFuncDict[_KT, _KT]])� mapping_specr[ r) c C s( dd� t �| �D �}t|�}t||d�S )a� A dictionary-based collection type with column-based keying. .. versionchanged:: 2.0 Renamed :data:`.column_mapped_collection` to :class:`.column_keyed_dict`. Returns a :class:`.KeyFuncDict` factory which will produce new dictionary keys based on the value of a particular :class:`.Column`-mapped attribute on ORM mapped instances to be added to the dictionary. .. note:: the value of the target attribute must be assigned with its value at the time that the object is being added to the dictionary collection. Additionally, changes to the key attribute are **not tracked**, which means the key in the dictionary is not automatically synchronized with the key value on the target object itself. See :ref:`key_collections_mutations` for further details. .. seealso:: :ref:`orm_dictionary_collection` - background on use :param mapping_spec: a :class:`_schema.Column` object that is expected to be mapped by the target mapper to a particular attribute on the mapped class, the value of which on a particular instance is to be used as the key for a new dictionary entry for that instance. :param ignore_unpopulated_attribute: if True, and the mapped attribute indicated by the given :class:`_schema.Column` target attribute on an object is not populated at all, the operation will be silently skipped. By default, an error is raised. .. versionadded:: 2.0 an error is raised by default if the attribute being used for the dictionary key is determined that it was never populated with any value. The :paramref:`_orm.column_keyed_dict.ignore_unpopulated_attribute` parameter may be set which will instead indicate that this condition should be ignored, and the append operation silently skipped. This is in contrast to the behavior of the 1.x series which would erroneously populate the value in the dictionary with an arbitrary key value of ``None``. c S s g | ]}t jtj|d d��qS )r] )�argname)r �expectr ZColumnArgumentRole)r= �qr- r- r. rB � s �z%column_keyed_dict.<locals>.<listcomp>rZ )r Zto_listr# �_mapped_collection_cls)r] r[ r$ �keyfuncr- r- r. �column_keyed_dict� s .��rc c @ s< e Zd ZdZdd�dd�Zddd�dd �Zd d �d d �ZdS )� _AttrGetter)� attr_name�getter�str)re c C s || _ t�|�| _d S r2 )re �operator� attrgetterrf )r, re r- r- r. r/ � s z_AttrGetter.__init__r )� mapped_objectr) c C sZ | � |�}|d u rVt�|�}|j}| j|jv rR|j}|�| jtj�}|d u rVt S nt S |S r2 ) rf r rC r9 re �attrsr< �get�NO_VALUEr )r, rj rF rA �mpZdict_r- r- r. rG � s z_AttrGetter.__call__z$Tuple[Type[_AttrGetter], Tuple[str]]r1 c C s t | jffS r2 )rd re r5 r- r- r. r6 � s z_AttrGetter.__reduce__N)rH rI rJ rL r/ rG r6 r- r- r- r. rd � s rd rg zType[KeyFuncDict[Any, Any]])re r[ r) c C s t t| �|d�S )ad A dictionary-based collection type with attribute-based keying. .. versionchanged:: 2.0 Renamed :data:`.attribute_mapped_collection` to :func:`.attribute_keyed_dict`. Returns a :class:`.KeyFuncDict` factory which will produce new dictionary keys based on the value of a particular named attribute on ORM mapped instances to be added to the dictionary. .. note:: the value of the target attribute must be assigned with its value at the time that the object is being added to the dictionary collection. Additionally, changes to the key attribute are **not tracked**, which means the key in the dictionary is not automatically synchronized with the key value on the target object itself. See :ref:`key_collections_mutations` for further details. .. seealso:: :ref:`orm_dictionary_collection` - background on use :param attr_name: string name of an ORM-mapped attribute on the mapped class, the value of which on a particular instance is to be used as the key for a new dictionary entry for that instance. :param ignore_unpopulated_attribute: if True, and the target attribute on an object is not populated at all, the operation will be silently skipped. By default, an error is raised. .. versionadded:: 2.0 an error is raised by default if the attribute being used for the dictionary key is determined that it was never populated with any value. The :paramref:`_orm.attribute_keyed_dict.ignore_unpopulated_attribute` parameter may be set which will instead indicate that this condition should be ignored, and the append operation silently skipped. This is in contrast to the behavior of the 1.x series which would erroneously populate the value in the dictionary with an arbitrary key value of ``None``. rZ )ra rd )re r[ r- r- r. �attribute_keyed_dict� s +�ro �Callable[[Any], Any]zType[KeyFuncDict[_KT, Any]])rb r[ r) c C s t | |d�S )a� A dictionary-based collection type with arbitrary keying. .. versionchanged:: 2.0 Renamed :data:`.mapped_collection` to :func:`.keyfunc_mapping`. Returns a :class:`.KeyFuncDict` factory with a keying function generated from keyfunc, a callable that takes an entity and returns a key value. .. note:: the given keyfunc is called only once at the time that the target object is being added to the collection. Changes to the effective value returned by the function are not tracked. .. seealso:: :ref:`orm_dictionary_collection` - background on use :param keyfunc: a callable that will be passed the ORM-mapped instance which should then generate a new key to use in the dictionary. If the value returned is :attr:`.LoaderCallableStatus.NO_VALUE`, an error is raised. :param ignore_unpopulated_attribute: if True, and the callable returns :attr:`.LoaderCallableStatus.NO_VALUE` for a particular instance, the operation will be silently skipped. By default, an error is raised. .. versionadded:: 2.0 an error is raised by default if the callable being used for the dictionary key returns :attr:`.LoaderCallableStatus.NO_VALUE`, which in an ORM attribute context indicates an attribute that was never populated with any value. The :paramref:`_orm.mapped_collection.ignore_unpopulated_attribute` parameter may be set which will instead indicate that this condition should be ignored, and the append operation silently skipped. This is in contrast to the behavior of the 1.x series which would erroneously populate the value in the dictionary with an arbitrary key value of ``None``. rZ )ra )rb r[ r- r- r. �keyfunc_mapping s ,�rq c s� e Zd ZdZdd�ddddd�� fd d �Zed!dd d dd�dd��Zdd�dd�Ze� d�d"ddddd�dd��Z e j e j d#dddd �d d ���Ze je j d$dddd �d d ���Z� ZS )%� KeyFuncDicta� Base for ORM mapped dictionary classes. Extends the ``dict`` type with additional methods needed by SQLAlchemy ORM collection classes. Use of :class:`_orm.KeyFuncDict` is most directly by using the :func:`.attribute_keyed_dict` or :func:`.column_keyed_dict` class factories. :class:`_orm.KeyFuncDict` may also serve as the base for user-defined custom dictionary classes. .. versionchanged:: 2.0 Renamed :class:`.MappedCollection` to :class:`.KeyFuncDict`. .. seealso:: :func:`_orm.attribute_keyed_dict` :func:`_orm.column_keyed_dict` :ref:`orm_dictionary_collection` :ref:`orm_custom_collection` FrZ rp r r\ r' )rb � dict_argsr[ r) c s || _ || _t� j|� dS )ah Create a new collection with keying provided by keyfunc. keyfunc may be any callable that takes an object and returns an object for use as a dictionary key. The keyfunc will be called every time the ORM needs to add a member by value-only (such as when loading instances from the database) or remove a member. The usual cautions about dictionary keying apply- ``keyfunc(object)`` should return the same output for the life of the collection. Keying based on mutable properties can result in unreachable instances "lost" in the collection. N)rb r[ �superr/ )r, rb r[ rs �rN r- r. r/ _ s zKeyFuncDict.__init__NzDict[_KT, _KT]zOptional[CollectionAdapter]z'KeyFuncDict[_KT, _KT]')rb �values�adapterr) c C s t |�}|�|� |S r2 )rr �update)rU rb rv rw rn r- r- r. � _unreducev s zKeyFuncDict._unreducezxTuple[Callable[[_KT, _KT], KeyFuncDict[_KT, _KT]], Tuple[Any, Union[Dict[_KT, _KT], Dict[_KT, _KT]], CollectionAdapter]]r1 c C s t j| jt| �t| �ffS r2 )rr ry rb r< r r5 r- r- r. r6 � s ��zKeyFuncDict.__reduce__zsqlalchemy.orm.attributesr z0Union[AttributeEventToken, Literal[None, False]])r; � initiator� warn_onlyr) c C s� t �|�j}tjj}t||j�s&d}n"|j|j v rB|j |j � }n|j}|r`t� d|� d�� n0t � d|� dt � |�� dt � |�� d|� d� ��d S ) Nzunknown relationshipz0Attribute keyed dictionary value for attribute 'z�' was None; this will raise in a future release. To skip this assignment entirely, Set the "ignore_unpopulated_attribute=True" parameter on the mapped collection factory.z1In event triggered from population of attribute 'za' (potentially from a backref), can't populate value in KeyFuncDict; dictionary key derived from z= is not populated. Ensure appropriate state is set up on the z object before assigning to the z� attribute. To skip this assignment entirely, Set the "ignore_unpopulated_attribute=True" parameter on the mapped collection factory.)r rC r9 r Z preloadedZorm_attributesrP r rE rk �warn�sa_exc�InvalidRequestErrorZ instance_str)r, r; rz r{ r9 � attributesZ relationshipr- r- r. �_raise_for_unpopulated� s0 �� �����z"KeyFuncDict._raise_for_unpopulated)r; � _sa_initiatorr) c C sl | � |�}|tju r2| js,| j||dd� qZdS n(|tu rZ| jsV| j||dd� d}ndS | �|||� dS )z9Add an item by value, consulting the keyfunc for the key.F�r{ NT)rb r rm r[ r� r � __setitem__�r, r; r� rE r- r- r. �set� s ��zKeyFuncDict.setc C s� | � |�}|tju r.| js*| j||dd� dS |tu rV| jsR| j||dd� d}ndS | | |krzt�d|| | |f ��| �||� dS )z<Remove an item by value, consulting the keyfunc for the key.Fr� NTz�Can not remove '%s': collection holds '%s' for key '%s'. Possible cause: is the KeyFuncDict key function based on mutable properties or properties that only obtain values after flush?) rb r rm r[ r� r r} r~ � __delitem__r� r- r- r. �remove� s* �� ��zKeyFuncDict.remove)N)N)N)N)rH rI rJ rK r/ rY ry r6 r Zpreload_moduler� r ZappenderZinternally_instrumentedr� Zremoverr� � __classcell__r- r- ru r. rr E s$ � � �+ � �rr c s" G � �fdd�dt ttf �}|S )Nc s( e Zd Zddd�� ��fdd� Z� ZS )z/_mapped_collection_cls.<locals>._MKeyfuncMappedr r' )rs r) c s t � j�g|�R d�i� d S )Nr[ )rt r/ )r, rs )rN r[ rb r- r. r/ s ���z8_mapped_collection_cls.<locals>._MKeyfuncMapped.__init__)rH rI rJ r/ r� r- �r[ rb ru r. �_MKeyfuncMapped s r� )rr r )rb r[ r� r- r� r. ra s ra )4� __future__r rh �typingr r r r r r r r r r r r � r � collectionsr r r r} r Zsqlr r r Zutil.langhelpersr r Z util.typingr r r r Z sql.elementsr r r" r# r3 rc rd ro rq rr ra ZMappedCollectionZmapped_collectionZattribute_mapped_collectionZcolumn_mapped_collectionr- r- r- r. �<module> s` -8�9�4�1 = sqlalchemy/orm/__pycache__/path_registry.cpython-39.pyc 0000644 00000052132 15125143220 0017226 0 ustar 00 a ��Jh<e � @ s U d Z ddlmZ ddlmZ ddlmZ ddlZddlZddl m Z ddl m Z ddl m Z dd l m Z dd l mZ dd l mZ dd l mZ dd l mZ ddl mZ ddl mZ ddl mZ ddlmZ ddlmZ ddlmZ ddlmZ ddl m Z ddl m Z e�r�ddlm Z ddl!m"Z" ddl#m$Z$ dd l%m&Z& dd lm'Z' dd l m(Z( dd l)m*Z* dd l+m,Z, dd!l-m.Z. dd"l-m/Z/ d#d$d%�d&d'�Z0d#d(d%�d)d*�Z1ne�2d'�Z0e�2d*�Z1ee Z3e4Z5ee5d+d,f Z6ee6d-f Z7ed+ Z8eed,e4f Z9e�:e;�Z<d.d#d%�d/d0�Z=d1Z>d2e?d3< d4Z@G d5d#� d#e �ZAG d6d7� d7eA�ZBG d8d9� d9eB�ZCeC� eA_DG d:d;� d;ejEe e4�ZFG d<d=� d=eA�ZGG d>d?� d?eA�ZHG d@dA� dAeB�ZIG dBdC� dCeI�ZJG dDdE� dEe e e f �ZKG dFdG� dGeI�ZLe�r d#d(d%�dHdI�ZMd#dJd%�dKdL�ZNne�2d*�ZMe�2dM�ZNdS )Nz@Path tracking utilities, representing mapper graph traversals. � )� annotations)�reduce)�chainN)�Any)�cast)�Dict)�Iterator)�List)�Optional)�overload)�Sequence)�Tuple)� TYPE_CHECKING)�Union� )�base)�insp_is_mapper_property� )�exc)�util)�visitors)� HasCacheKey)�_InternalEntityType)�StrategizedProperty)�Mapper)�RelationshipProperty)� AliasedInsp)�_CacheKeyTraversalType)� BindParameter)�anon_map)� _LiteralStar)� TypeGuard� PathRegistryzTypeGuard[RootRegistry]��path�returnc C s d S �N� �r$ r' r' �Q/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/path_registry.py�is_root0 � r* z!TypeGuard[AbstractEntityRegistry]c C s d S r& r' r( r' r' r) � is_entity2 r+ r, �_InternalEntityType[Any]�StrategizedProperty[Any].�_SerializedPathc C s t �| �S r& )r" � deserializer( r' r' r) �_unreduce_pathP s r1 �*r �_WILDCARD_TOKENZ _sa_defaultc @ s� e Zd ZU dZdZdZdZdZdZdZ de d< de d< de d< d e d < d e d < de j j fgZd e d< ddd�dd�Zddd�dd�Zedd�dd��Zddd�d d �Zd ddd d �d!d"�Zd ddd d �d#d$�Zdgd dd&dd �d'd(�Zdd�d)d*�Zdd�d+d,�Zed-d.d/�d0d1��Zedd2d/�d3d1��Zed4dd/�d5d1��Zedd6d/�d7d1��Zed8d9d/�d:d1��Zd;d<d/�d=d1�Zedd�d>d?��Zd@d�dAdB�Z dCddD�dEdF�Z d dddG�dHdI�Z dd�dJdK�Z e ddLdM�dNdO��Z!e dLddM�dPdQ��Z"dLd�dRdS�Z#e dLd dM�dTdU��Z$ee dCdVdD�dWdX���Z%ee dYdZdD�d[dX���Z%e dd6dD�d\dX��Z%e dd d]�d^d_��Z&d d d�d`da�Z'dbd�dcdd�Z(dbd�dedf�Z)d%S )hr" a� Represent query load paths and registry functions. Basically represents structures like: (<User mapper>, "orders", <Order mapper>, "items", <Item mapper>) These structures are generated by things like query options (joinedload(), subqueryload(), etc.) and are used to compose keys stored in the query._attributes dictionary for various options. They are then re-composed at query compile/result row time as the query is formed and as rows are fetched, where they again serve to compose keys to look up options in the context.attributes dictionary, which is copied from query._attributes. The path structure has a limited amount of caching, where each "root" ultimately pulls from a fixed registry associated with the first mapper, that also contains elements for each of its property keys. However paths longer than two elements, which are the exception rather than the rule, are generated on an as-needed basis. r' F�bool� is_unnatural�_PathRepresentationr$ � natural_pathzOptional[PathRegistry]�parent� RootRegistry�rootr �_cache_key_traversalr )�otherr% c C sB z|d uo| j |jkW S ty< t�dt|� � Y dS 0 d S )N�1Comparison of PathRegistry to %r is not supportedF�r$ �_path_for_compare�AttributeErrorr �warn�type��selfr< r' r' r) �__eq__� s ��zPathRegistry.__eq__c C sB z|d u p| j |jkW S ty< t�dt|� � Y dS 0 d S )Nr= Tr> rC r' r' r) �__ne__� s ��zPathRegistry.__ne__� Optional[_PathRepresentation]�r% c C s | j S r& r( �rD r' r' r) r? � s z PathRegistry._path_for_compare�intr- )�indexr% c C s | j | S r& r( )rD rK r' r' r) � odd_element� s zPathRegistry.odd_elementzDict[Any, Any]�None)� attributes�key�valuer% c C s" t �d|| |� |||| jf< d S )Nz set '%s' on path '%s' to '%s')�log�debugr7 �rD rN rO rP r' r' r) �set� s zPathRegistry.setc C s& t �d|| |� |�|| jf|� d S )Nz$setdefault '%s' on path '%s' to '%s')rQ rR � setdefaultr7 rS r' r' r) rU � s zPathRegistry.setdefaultNz Optional[Any]c C s" || j f}||v r|| S |S d S r& )r7 rS r' r' r) �get� s zPathRegistry.getc C s t | j�S r& ��lenr$ rI r' r' r) �__len__� s zPathRegistry.__len__c C s t | �S r& )�idrI r' r' r) �__hash__� s zPathRegistry.__hash__� _StrPathToken� TokenRegistry��entityr% c C s d S r& r' �rD r_ r' r' r) � __getitem__� s zPathRegistry.__getitem__�_PathElementTypec C s d S r& r' r` r' r' r) ra � s �slicec C s d S r& r' r` r' r' r) ra � s �AbstractEntityRegistryc C s d S r& r' r` r' r' r) ra � s r. � PropRegistryc C s d S r& r' r` r' r' r) ra � s zTUnion[_StrPathToken, int, slice, _InternalEntityType[Any], StrategizedProperty[Any]]zaUnion[TokenRegistry, _PathElementType, _PathRepresentation, PropRegistry, AbstractEntityRegistry]c C s t � �d S r& )�NotImplementedErrorr` r' r' r) ra � s c C s t | j�S r& rW rI r' r' r) �length� s zPathRegistry.lengthzOIterator[Tuple[_InternalEntityType[Any], Union[str, StrategizedProperty[Any]]]]c c sF t t| j�}t t|�}tdt|�d�D ]}|| ||d fV q&d S )Nr r r )r �_OddPathRepresentationr$ �_EvenPathRepresentation�rangerX )rD Zodd_pathZ even_path�ir' r' r) �pairs� s zPathRegistry.pairs� Mapper[Any])�mapperr% c sF t t| j�� � fdd�tdt� �d�D �D ]}|j�|�r* dS q*dS )Nc s g | ] }� | �qS r' r' ��.0rk ��_m_pathr' r) � <listcomp>� r+ z0PathRegistry.contains_mapper.<locals>.<listcomp>r r TF)r rh r$ rj rX rn �isa)rD rn Z path_mapperr' rq r) �contains_mapper� s " z PathRegistry.contains_mapper)rN rO r% c C s || j f|v S r& r( )rD rN rO r' r' r) �contains� s zPathRegistry.containsc C s t | �� ffS r& )r1 � serializerI r' r' r) � __reduce__� s zPathRegistry.__reduce__r/ r# c sv t t|�� t t|��tttdd� � fdd�tdt� �d�D �D ��tdd� �fdd�td t��d�D �D ��d ��S ) Nc s s( | ] }|j s|jr|jnt|�V qd S r& )� is_mapper�is_aliased_class�class_�str)rp �mr' r' r) � <genexpr> s �z/PathRegistry._serialize_path.<locals>.<genexpr>c s g | ] }� | �qS r' r' ro rq r' r) rs r+ z0PathRegistry._serialize_path.<locals>.<listcomp>r r c s s$ | ] }t |�r|jnt|�V qd S r& )r rO r| )rp �pr' r' r) r~ s �c s g | ] }� | �qS r' r' ro )�_p_pathr' r) rs r+ r r& )r rh ri �list�zip�tuplerj rX )�clsr$ r' )rr r� r) �_serialize_path� s � ����z PathRegistry._serialize_pathc s^ ddd�dd��dddd�dd�� t t� �fdd �|D �� �}|rZ|d d u rZ|d d � }|S ) Nr )�mclsr% c S s" | t jvrtj| dd�S t j| S �NT)� configure)� PathToken�_intern�orm_base�_inspect_mapped_class)r� r' r' r) �_deserialize_mapper_token s ��zAPathRegistry._deserialize_path.<locals>._deserialize_mapper_token)r� rO r% c S sH |d u r d S |t jv r t j| S tj| dd�}|d us:J �|j| S d S r� )r� r� r� r� �attrs)r� rO �mpr' r' r) �_deserialize_key_token s z>PathRegistry._deserialize_path.<locals>._deserialize_key_tokenc s" g | ]\}}�|�� ||�f�qS r' r' )rp r� rO �r� r� r' r) rs % s ��z2PathRegistry._deserialize_path.<locals>.<listcomp>���r )r� r �r� r$ r r' r� r) �_deserialize_path s ��� z PathRegistry._deserialize_pathc C s | j }| �|�S r& )r$ r� )rD r$ r' r' r) rw 2 s zPathRegistry.serializec C s |d us J �| � |�}| �|�S r& )r� �coercer� r' r' r) r0 6 s zPathRegistry.deserialize�CachingEntityRegistryc C s d S r& r' �r� rn r' r' r) � per_mapper< s zPathRegistry.per_mapper�AliasedInsp[Any]�SlotsEntityRegistryc C s d S r& r' r� r' r' r) r� @ s c C s" |j rt| j|�S t| j|�S d S r& )ry r� r: r� r� r' r' r) r� D s )�rawr% c C s dddd�dd�}t ||| j�S )Nr" rb ��prev�next_r% c S s | | S r& r' �r� r� r' r' r) �_redO s z!PathRegistry.coerce.<locals>._red)r r: )r� r� r� r' r' r) r� M s zPathRegistry.coercec C s dddd�dd�}t ||j| �S )Nr" rb r� c S s | | S r& r' r� r' r' r) r� V s z"PathRegistry.__add__.<locals>._red)r r$ )rD r< r� r' r' r) �__add__U s zPathRegistry.__add__r| c C s dd� dd� | jD ��� d�S )Nz ORM Path[z -> c s s | ]}t |�V qd S r& �r| )rp �elemr' r' r) r~ \ r+ z'PathRegistry.__str__.<locals>.<genexpr>�])�joinr$ rI r' r' r) �__str__[ s zPathRegistry.__str__c C s | j j� d| j�d�S )N�(�))� __class__�__name__r$ rI r' r' r) �__repr__^ s zPathRegistry.__repr__)N)*r� � __module__� __qualname__�__doc__� __slots__�is_tokenr* � has_entity� is_propertyr, �__annotations__r ZExtendedInternalTraversalZdp_has_cache_key_listr; rE rF �propertyr? rL rT rU rV rY r[ r ra rg rl ru rv rx � classmethodr� r� rw r0 r� r� r� r� r� r' r' r' r) r" X s| � � #c @ s2 e Zd ZU dZded< ded< ddd�dd �Zd S ) � CreatesTokenr' r4 rz r* r\ r] )�tokenr% c C sJ |� dt� ��rt| |�S |� dt� ��r6t| j|�S t�d|� ���d S )N�:zinvalid token: )�endswithr3 r] �_DEFAULT_TOKENr: r � ArgumentError)rD r� r' r' r) r� h s zCreatesToken.tokenN)r� r� r� r� r� r� r' r' r' r) r� b s r� c @ sV e Zd ZdZdZdZd ZZdZdZ dZ dZ ddd�dd �Z d d �d d �Z esRe Zd S )r9 zXRoot registry, defers to mappers so that paths are maintained per-root-mapper. r' TFr z,Union[TokenRegistry, AbstractEntityRegistry]r^ c C sZ |t jv r,tr t|t�s J �t| t j| �S z|jW S tyT td|� ���Y n0 d S )Nz/invalid argument for RootRegistry.__getitem__: ) r� r� r � isinstancer\ r] Z_path_registryr@ � IndexErrorr` r' r' r) �_getitem� s �zRootRegistry._getitemrH c C s | S r& r' rI r' r' r) �_truncate_recursive� s z RootRegistry._truncate_recursiveN)r� r� r� r� r� � inherit_cacher$ r7 r� rz r* r5 r� r� r ra r' r' r' r) r9 q s r9 c @ sV e Zd ZU dZi Zded< dddd�dd �Zed d �d d ��Ze dd d�dd��Z dS )r� zcacheable string tokenzDict[str, PathToken]r� r zList[BindParameter[Any]]zTuple[Any, ...])r � bindparamsr% c C s t | �fS r& r� )rD r r� r' r' r) �_gen_cache_key� s zPathToken._gen_cache_keyrG rH c C s d S r& r' rI r' r' r) r? � s zPathToken._path_for_comparer| )�strvaluer% c C s. || j v r| j | S t|� | j |< }|S d S r& )r� r� )r� r� �resultr' r' r) �intern� s zPathToken.internN) r� r� r� r� r� r� r� r� r? r� r� r' r' r' r) r� � s r� c @ sr e Zd ZU dZdZded< ded< ddd�dd �Zd ZdZd d �d d�Z dd �dd�Z ddd�dd�Z e sne Z dS )r] )r� r8 r$ r7 Tr\ r� r� r8 )r8 r� c C s6 t �|�}|| _|| _|j|f | _|j|f | _d S r& )r� r� r� r8 r$ r7 )rD r8 r� r' r' r) �__init__� s zTokenRegistry.__init__FzIterator[PathRegistry]rH c c s� | j }t|�r| V d S tr*t|t�s*J �|jsV|j�� D ]}t|j | | j �V q:nJ|jr�t d|j �j r�| V t d|j �j D ]}t|j | | j �V q~n| V d S �Nr� )r8 r* r r� rd rz rn �iterate_to_rootr] r� r r_ �_is_with_polymorphic�_with_polymorphic_entities�rD r8 Zmp_ent�entr' r' r) �generate_for_superclasses� s, ���� z'TokenRegistry.generate_for_superclassesz Iterator[_PathRepresentation]c c s� | j }t|�r| jV d S tr,t|t�s,J �|j�� D ]}t|j | | j �jV q6|j r�t d|j �j r�| jV t d|j �jD ]}t|j | | j �jV q|n| jV d S r� )r8 r* r7 r r� rd rn r� r] r� rz r r_ r� r� r� r' r' r) �"_generate_natural_for_superclasses� s, ���� �z0TokenRegistry._generate_natural_for_superclassesr r^ c C sB z | j | W S ty< } zt|� �|�W Y d }~n d }~0 0 d S r& )r$ � TypeErrorr� )rD r_ �errr' r' r) r� � s zTokenRegistry._getitemN)r� r� r� r� r� r� r� r� r� r� r� r� r ra r' r' r' r) r] � s r] c @ sz e Zd ZU dZdZdZded< ded< ded< d dd �d d �Zd d �dd�Ze d d �dd��Z ddd�dd�Z e sve Z dS )re ) �propr8 r$ r7 r� r_ rn �_wildcard_path_loader_key�_default_path_loader_key� _loader_keyr5 Tr. r� zOptional[Mapper[Any]]rn z"Optional[_InternalEntityType[Any]]r_ rd )r8 r� c C sd t d|d �}|}|jjp$t|jj�| _|jr4|jrF|j|j }}n�|jr�|jr�|j|jv r�|d � |j�}|j| }|jr�|j|j }d| _q�|}n2|jr�|jr�|j|jur�|j� |j�r�|j|j }|| _ || _|j |f | _ |j |f | _ |j| _|j�r*t�rt|t��sJ �|j| _|j| _n d | _d | _d|j | j j f| _| j j| _d| j f| _d S )Nr- r� T�loader)r r8 r5 r4 rn Zinheritsrz Z_use_mapper_pathZwith_polymorphic_mappersZ_entity_for_mapperrt r� r$ r7 Z_links_to_entityr� Z_is_relationshipr r� r r_ Z_wildcard_tokenr� r� r� )rD r8 r� ZinspZnatural_parentZsubclass_entityr' r' r) r� s^ � �� � ���� � � zPropRegistry.__init__rH c C s\ d }t t| jd d� ��D ]\}}|| ju r|}q|d u r>| S | �| jd|d � �S d S )Nr� r r )� enumerate�reversedr$ r� r� )rD Zearliestrk r� r' r' r) r� v s z PropRegistry._truncate_recursivec C s | j d usJ �| | j S r& )r_ rI r' r' r) � entity_path� s zPropRegistry.entity_pathz+Union[int, slice, _InternalEntityType[Any]]zDUnion[AbstractEntityRegistry, _PathElementType, _PathRepresentation]r^ c C s& t |ttf�r| j| S t| |�S d S r& )r� rJ rc r$ r� r` r' r' r) r� � s zPropRegistry._getitemN)r� r� r� r� r� r� r� r� r� r� r� r� r ra r' r' r' r) re s Z re c @ s� e Zd ZU dZdZdZded< ded< ded< ded < ddd �d d �Zd d �dd�Ze dd �dd��Z e dd �dd��Z e dd �dd��Z dd �dd�Z ddd �d d �Zes�eZd S ) rd )rO r8 rz r$ r_ r7 T�!Union[RootRegistry, PropRegistry]r8 r- rO r_ r4 rz �r8 r_ c C s� || _ || _|j| _|| _|j|f | _|jrx| js:|jrx|j�|jd j�r`|j|jf | _q�|j|jd jf | _n| j| _d S )Nr� ) rO r8 rz r_ r$ r5 rn rt r7 �rD r8 r_ r' r' r) r� � s � z AbstractEntityRegistry.__init__rH c C s | j �� | j S r& )r8 r� r_ rI r' r' r) r� � s z*AbstractEntityRegistry._truncate_recursivec C s | � d�S )Nr )rL rI r' r' r) � root_entity� s z"AbstractEntityRegistry.root_entityr" c C s | S r& r' rI r' r' r) r� � s z"AbstractEntityRegistry.entity_pathrm c C s | j jS r& )r_ rn rI r' r' r) rn � s z AbstractEntityRegistry.mapperc C s dS )NTr' rI r' r' r) �__bool__� s z AbstractEntityRegistry.__bool__r z:Union[_PathElementType, _PathRepresentation, PathRegistry]r^ c C s@ t |ttf�r| j| S |tjv r2t| tj| �S t| |�S d S r& )r� rJ rc r$ r� r� r] re r` r' r' r) r� � s z AbstractEntityRegistry._getitemN)r� r� r� r� r� r, r� r� r� r� r� r� rn r� r� r ra r' r' r' r) rd � s& . rd c @ s e Zd ZdZdS )r� TN)r� r� r� r� r' r' r' r) r� � s r� c @ s* e Zd Zdd�dd�Zddd�dd �Zd S ) �_ERDictr� ��registryc C s || _ d S r& r� )rD r� r' r' r) r� � s z_ERDict.__init__r re )rO r% c C s t | j|� | |< }|S r& )re r� )rD rO �itemr' r' r) � __missing__� s z_ERDict.__missing__N)r� r� r� r� r� r' r' r' r) r� � s r� c sV e Zd ZdZdZddd�� fdd� Zdddd �d d �Zddd �d d�ZesNeZ � Z S )r� )�_cacheTr� r- r� c s t � �||� t| �| _d S r& )�superr� r� r� r� �r� r' r) r� s z CachingEntityRegistry.__init__r )rO �defaultr% c C s | j �||�S r& )r� �pop)rD rO r� r' r' r) r� s zCachingEntityRegistry.popr^ c C s: t |ttf�r| j| S t |t�r,t| |�S | j| S d S r& )r� rJ rc r$ r� r] r� r` r' r' r) r� s z CachingEntityRegistry._getitem) r� r� r� r� r� r� r� r� r ra � __classcell__r' r' r� r) r� s r� c C s d S r& r' r( r' r' r) �path_is_entity# s r� zTypeGuard[PropRegistry]c C s d S r& r' r( r' r' r) �path_is_property' r+ r� r� )Or� � __future__r � functoolsr � itertoolsr �logging�operator�typingr r r r r r r r r r r � r r� Z_typingr r r Zsqlr Z sql.cache_keyr r Z interfacesr rn r Z relationshipsr r r Z sql.elementsr Z sql.visitorsr Z util.typingr r! r* r, � attrgetterr/ r| r\ rb r6 rh ri � getLoggerr� rQ r1 r3 r� r� r" r� r9 r: ZInspectionAttrr� r] re rd r� r� r� r� r� r' r' r' r) �<module> s� � &V ` sqlalchemy/orm/__pycache__/interfaces.cpython-39.pyc 0000644 00000130505 15125143220 0016466 0 ustar 00 a ��Jh�� � @ s� d Z ddlmZ ddlZddlZddlZddlmZ ddlmZ ddlmZ ddlm Z ddlm Z dd lm Z dd lm Z dd lm Z dd lmZ dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddl m Z ddl m Z ddl m Z dd l m Z dd l m!Z! dd l m"Z" dd l m#Z# dd l m$Z$ dd!l m%Z% dd"l m&Z& dd#l m'Z' dd$l m(Z( dd%l m)Z) dd&l m*Z* d'd(lm+Z+ d'dlmZ, d'd)lm-Z- d'd*lm.Z. d'd+l/m0Z0 d'd,l/m1Z1 d'd-l/m2Z2 d'd.l3m4Z4 d'd/l3m5Z5 d'd0l6m7Z7 d'd1l8m9Z9 d'd2l:m;Z; d'd3l<m=Z= d'd4l.m>Z> d'd5l?m@Z@ d'd6l?mAZA ej�r�dd7lBmCZC dd8lBmDZD dd9lBmEZE dd:lBmFZF dd;lBmGZG dd<lHmIZI dd=l mJZJ dd>lKmLZL dd?lKmMZM dd@lKmNZN ddAlOmPZP ddBlQmRZR ddClSmTZT ddDlUmVZV ddElmWZW ddFlXmYZY ddGlZm[Z[ ddHl\m]Z] ddIl^m_Z_ ddJl.m`Z` ddKl.maZa d'dLlbmcZc d'dMldmeZe d'dNldmfZf d'dOldmgZg d'dPldmhZh d'dQl8miZi d'dRljmkZk d'dSl?mlZl eedTf ZmedUedV�ZnedWedXdY�ZoedZd[dV�ZpG d\d]� d]e1jq�ZrG d^d_� d_e1jse1jten �ZuG d`da� daeuen �ZvG dbdc� dce1jw�ZxG ddde� deeA�ZyG dfdg� dg�ZzG dhdi� die�Z{e{e4j|e4j|e4j|e4j|e4j|e4j|e4j|�Z}e{dje4j|e4j|e4j|e4j|e4j|e4j|�Z~G dkdl� dl�ZG dmdn� dnee en �Z�e-j�G dodp� dpe7ee en e"e.j���Z�e-j�G dqdr� dre*eo e eo e9��Z�G dsdt� dte�en �Z�G dudv� dve5�Z�G dwdx� dxe7e��Z�G dydz� dze��Z�G d{d|� d|e��Z�G d}d~� d~e��Z�e.j�dd�dd��G d�d�� d�e���Z�G d�d�� d��Z�dS )�z� Contains various base classes used throughout the ORM. Defines some key base classes prominent within the internals. This module and the classes within are mostly private, though some attributes are exposed when inspecting mappings. � )� annotationsN)�Any)�Callable)�cast)�ClassVar)�Dict)�Generic)�Iterator)�List)� NamedTuple)�NoReturn)�Optional)�Sequence)�Set)�Tuple)�Type)� TYPE_CHECKING)�TypeVar)�Union� )�exc)� path_registry)�_MappedAttribute)� EXT_CONTINUE)�EXT_SKIP)�EXT_STOP)�InspectionAttr)�InspectionAttrInfo)� MANYTOMANY)� MANYTOONE)�NO_KEY)�NO_VALUE)� NotExtension)� ONETOMANY)�RelationshipDirection)�SQLORMOperations� )� ColumnElement)� inspection)�util)� operators)�roles)�visitors)�_NoArg)�ExecutableOption)� HasCacheKey)�ColumnOperators)�Column)� TypeEngine)�warn_deprecated)�RODescriptorReference)� TypedDict)� _EntityType)�_IdentityKeyType)� _InstanceDict)�_InternalEntityType)�_ORMAdapterProto)�InstrumentedAttribute)�Mapped)� _MapperEntity)�ORMCompileState)� QueryContext)� RegistryType)�_ClassScanMapperConfig)�_PopulatorDict)�Mapper)�AbstractEntityRegistry)�Query)�Session)� InstanceState)� _LoadElement)� AliasedInsp)� ORMAdapter)�Result)�_ColumnExpressionArgument)�_ColumnsClauseArgument)�_DMLColumnArgument)� _InfoType)� OperatorType)�_TraverseInternalsType)�_AnnotationScanType.�_T)�bound�_T_coT)rT � covariant�_TLS�Type[LoaderStrategy]c @ s e Zd ZdZdZdS )�ORMStatementRole� z?Executable SQL or text() construct, including ORM aware objectsN��__name__� __module__� __qualname__� __slots__Z _role_namerZ rZ rZ �N/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/interfaces.pyrY s s �rY c @ s e Zd ZdZdZdS )�ORMColumnsClauseRolerZ z7ORM mapped entity, aliased entity, or Column expressionNr[ rZ rZ rZ r` ra z s ra c @ s e Zd ZdZdZdS )�ORMEntityColumnsClauseRolerZ z ORM mapped or aliased entityNr[ rZ rZ rZ r` rb � s rb c @ s e Zd ZdZdZdS )�ORMFromClauseRolerZ z5ORM mapped entity, aliased entity, or FROM expressionNr[ rZ rZ rZ r` rc � s rc c @ s6 e Zd ZU ded< ded< ded< ded< d ed < d S ) �ORMColumnDescription�str�namez!Union[Type[Any], TypeEngine[Any]]�type�bool�aliasedz_ColumnsClauseArgument[Any]�exprz%Optional[_ColumnsClauseArgument[Any]]�entityN)r\ r] r^ �__annotations__rZ rZ rZ r` rd � s rd c @ sb e Zd ZdZedd�dd��Zdd�dd�Zd d d d dd ddddd� dd�Zdd dd�dd�ZdS )�_IntrospectsAnnotationsrZ re ��returnc C s | j S �N)r\ )�clsrZ rZ r` �_mapper_property_name� s z-_IntrospectsAnnotations._mapper_property_namer c C s t d| �� �d���dS )zrreturn a copy of this object to use in declarative when the object is found inside of an Annotated object.z Use of the z> construct inside of an Annotated object is not yet supported.N)�NotImplementedErrorrr ��selfrZ rZ r` �found_in_pep593_annotated� s �z1_IntrospectsAnnotations.found_in_pep593_annotatedrA r@ z Type[Any]� Optional[str]zOptional[Type[Mapped[Any]]]z Optional[_AnnotationScanType]rh �None) � decl_scan�registryrq �originating_module�key�mapped_container� annotation�extracted_mapped_annotation�is_dataclass_fieldro c C s dS )zyPerform class-specific initializaton at early declarative scanning time. .. versionadded:: 2.0 NrZ ) ru ry rz rq r{ r| r} r~ r r� rZ rZ r` �declarative_scan� s z(_IntrospectsAnnotations.declarative_scanr )r| rq ro c C s( t �d|j� d|� d| �� � d���d S )Nz4Python typing annotation is required for attribute "�.z " when primary argument(s) for "z#" construct are None or not present)�sa_exc� ArgumentErrorr\ rr )ru r| rq rZ rZ r` �_raise_for_required� s ����z+_IntrospectsAnnotations._raise_for_requiredN) r\ r] r^ r_ � classmethodrr rv r� r� rZ rZ rZ r` rm � s rm c @ st e Zd ZU dZded< ded< ded< ded< ded < ded < d ed < d dd�dd�Zed ddddd�dd��ZdS )�_AttributeOptionsz�define Python-local attribute behavior options common to all :class:`.MapperProperty` objects. Currently this includes dataclass-generation arguments. .. versionadded:: 2.0 zUnion[_NoArg, bool]�dataclasses_init�dataclasses_reprzUnion[_NoArg, Any]�dataclasses_defaultz Union[_NoArg, Callable[[], Any]]�dataclasses_default_factory�dataclasses_compare�dataclasses_kw_onlyzUnion[_NoArg, bool, None]�dataclasses_hashre r �r| ro c s$ i }| j tjur| j |d< | jtjur0| j|d< | jtjurF| j|d< | jtjur\| j|d< | jtjurr| j|d< | jtjur�| j|d< | jtjur�| j|d< d|v r�t |d �r�t d|�d �d � d|v �r|d �sd|v �rt |d ��sd|v�r|� d�� � fd d �|d< t j f i |��S ) z<Return a ``dataclasses.Field`` object given these arguments.�default_factory�default�init�repr�compareZkw_only�hashzBCallable object passed to the ``default`` parameter for attribute a� in a ORM-mapped Dataclasses context is ambiguous, and this use will raise an error in a future release. If this callable is intended to produce Core level INSERT default values for an underlying ``Column``, use the ``mapped_column.insert_default`` parameter instead. To establish this callable as providing a default value for instances of the dataclass itself, use the ``default_factory`` dataclasses parameter.z2.0c s � S rp rZ rZ �r� rZ r` �<lambda> � z7_AttributeOptions._as_dataclass_field.<locals>.<lambda>)r� r- �NO_ARGr� r� r� r� r� r� �callabler3 �pop� dataclasses�field)ru r| �kwrZ r� r` �_as_dataclass_field� sF � ���� �� z%_AttributeOptions._as_dataclass_fieldrR � Optional[Any]rS z_Union[Tuple[str, _AnnotationScanType], Tuple[str, _AnnotationScanType, dataclasses.Field[Any]]])r| r~ r} �elemro c C sV t |t�r |j�|�}|||fS |tjur4|||fS |durJdsRJ d��n||fS dS )z�given attribute key, annotation, and value from a class, return the argument tuple we would pass to dataclasses.make_dataclass() for this attribute. NFz/Mapped[] received without a mapping declaration)� isinstance�_DCAttributeOptions�_attribute_optionsr� r- r� )rq r| r~ r} r� Zdc_fieldrZ rZ r` �!_get_arguments_for_make_dataclass s z3_AttributeOptions._get_arguments_for_make_dataclassN)r\ r] r^ �__doc__rl r� r� r� rZ rZ rZ r` r� � s 1r� Fc @ s& e Zd ZU dZdZded< ded< dS )r� aw mixin for descriptors or configurational objects that include dataclass field options. This includes :class:`.MapperProperty`, :class:`._MapsColumn` within the ORM, but also includes :class:`.AssociationProxy` within ext. Can in theory be used for other descriptors that serve a similar role as association proxy. (*maybe* hybrids, not sure yet.) rZ r� r� rh �_has_dataclass_argumentsN)r\ r] r^ r� r_ rl rZ rZ rZ r` r� B s r� c @ s8 e Zd ZdZdZedd�dd��Zedd�dd ��Zd S ) � _MapsColumnsz�interface for declarative-capable construct that delivers one or more Column objects to the declarative process to be part of a Table. rZ z Optional[MapperProperty[_T]]rn c C s t � �dS )zAreturn a MapperProperty to be assigned to the declarative mappingN�rs rt rZ rZ r` �mapper_property_to_assign` s z&_MapsColumns.mapper_property_to_assignz List[Tuple[Column[_T], int]]c C s t � �dS )zfA list of Column objects that should be declaratively added to the new Table object. Nr� rt rZ rZ r` �columns_to_assigne s z _MapsColumns.columns_to_assignN)r\ r] r^ r� r_ �propertyr� r� rZ rZ rZ r` r� Y s r� c @ sr e Zd ZU dZdZdejjfdejjfgZ de d< e s:dZ dZ d e d < d e d< d e d< d Zde d< de d< de d< dd�dd�Zdddddd d �d d �Zdddd d dd!d d"�d#d$�ZdHd d%d&d'd(d)d*�d+d,�Zd dd d-�d.d/�Zd d d0�d1d2�ZdId3dd d4�d5d6�Zd d�d7d8�Zed9d�d:d;��Zd d�d<d=�Zd d d0�d>d?�Zd@d%d&d%d&ddAdBd dC� dDdE�Zd d�dFdG�Z dS )J�MapperPropertya� Represent a particular class attribute mapped by :class:`_orm.Mapper`. The most common occurrences of :class:`.MapperProperty` are the mapped :class:`_schema.Column`, which is represented in a mapping as an instance of :class:`.ColumnProperty`, and a reference to another class produced by :func:`_orm.relationship`, represented in the mapping as an instance of :class:`.Relationship`. )�_configure_started�_configure_finishedr� r� �parentr| �info�docr� r| rQ �_cache_key_traversalNTzPropComparator[_T]� comparatorre � Mapper[Any]Frh Z_links_to_entityrw r� rO r� rn c C s i S )a� Info dictionary associated with the object, allowing user-defined data to be associated with this :class:`.InspectionAttr`. The dictionary is generated when first accessed. Alternatively, it can be specified as a constructor argument to the :func:`.column_property`, :func:`_orm.relationship`, or :func:`.composite` functions. .. seealso:: :attr:`.QueryableAttribute.info` :attr:`.SchemaItem.info` rZ rt rZ rZ r` �_memoized_attr_info� s z"MapperProperty._memoized_attr_infor> r= rD �Optional[ORMAdapter]r rx ��context� query_entity�path�adapter�kwargsro c K s dS )a Called by Query for the purposes of constructing a SQL statement. Each MapperProperty associated with the target mapper processes the statement referenced by the query context, adding columns and/or criterion as appropriate. NrZ )ru r� r� r� r� r� rZ rZ r` �setup� s zMapperProperty.setup� Result[Any]rB �r� r� r� �mapper�resultr� � populatorsro c C s dS )zcProduce row processing functions and append to the given set of populators lists. NrZ )ru r� r� r� r� r� r� r� rZ rZ r` �create_row_processor� s z#MapperProperty.create_row_processorzInstanceState[Any]r8 zSet[InstanceState[Any]]z.Optional[Callable[[InstanceState[Any]], bool]]zGIterator[Tuple[object, Mapper[Any], InstanceState[Any], _InstanceDict]])�type_�state�dict_�visited_states�halt_onro c C s t d�S )a� Iterate through instances related to the given instance for a particular 'cascade', starting with this MapperProperty. Return an iterator3-tuples (instance, mapper, state). Note that the 'cascade' collection on this MapperProperty is checked first for the given type before cascade_iterator is called. This method typically only applies to Relationship. rZ )�iter)ru r� r� r� r� r� rZ rZ r` �cascade_iterator� s z MapperProperty.cascade_iterator)r� r� ro c C s || _ dS )z�Set the parent mapper that references this MapperProperty. This method is overridden by some subclasses to perform extra setup when the mapper is first known. N)r� )ru r� r� rZ rZ r` � set_parent s zMapperProperty.set_parent�r� ro c C s dS )aI Hook called by the Mapper to the property to initiate instrumentation of the class attribute managed by this MapperProperty. The MapperProperty here will typically call out to the attributes module to set up an InstrumentedAttribute. This step is the first of two steps to set up an InstrumentedAttribute, and is called early in the mapper setup process. The second step is typically the init_class_attribute step, called from StrategizedProperty via the post_instrument_class() hook. This step assigns additional state to the InstrumentedAttribute (specifically the "impl") which has been determined after the MapperProperty has determined what kind of persistence management it needs to do (e.g. scalar, object, collection, etc). NrZ �ru r� rZ rZ r` �instrument_class s z MapperProperty.instrument_classzOptional[_AttributeOptions])�attribute_options� _assume_readonly_dc_attributesro c C sD d| _ d| _|rt}nt}|r4||kr4d| _|| _n d| _|| _d S )NFT)r� r� �#_DEFAULT_READONLY_ATTRIBUTE_OPTIONS�_DEFAULT_ATTRIBUTE_OPTIONSr� r� )ru r� r� Z default_attrsrZ rZ r` �__init__1 s zMapperProperty.__init__c C s d| _ | �� d| _dS )z�Called after all mappers are created to assemble relationships between mappers and perform other post-mapper-creation initialization steps. TN)r� �do_initr� rt rZ rZ r` r� E s zMapperProperty.initzInstrumentedAttribute[_T]c C s t | jj| j�S )a� Return the class-bound descriptor corresponding to this :class:`.MapperProperty`. This is basically a ``getattr()`` call:: return getattr(self.parent.class_, self.key) I.e. if this :class:`.MapperProperty` were named ``addresses``, and the class to which it is mapped is ``User``, this sequence is possible:: >>> from sqlalchemy import inspect >>> mapper = inspect(User) >>> addresses_property = mapper.attrs.addresses >>> addresses_property.class_attribute is User.addresses True >>> User.addresses.property is addresses_property True )�getattrr� �class_r| rt rZ rZ r` �class_attributeP s z MapperProperty.class_attributec C s dS )z�Perform subclass-specific initialization post-mapper-creation steps. This is a template method called by the ``MapperProperty`` object's init() method. NrZ rt rZ rZ r` r� j s zMapperProperty.do_initc C s dS )a Perform instrumentation adjustments that need to occur after init() has completed. The given Mapper is the Mapper invoking the operation, which may not be the same Mapper as self.parent in an inheritance scenario; however, Mapper will always at least be a sub-mapper of self.parent. This method is typically used by StrategizedProperty, which delegates it to LoaderStrategy.init_class_attribute() to perform final setup on the class-bound InstrumentedAttribute. NrZ r� rZ rZ r` �post_instrument_classs s z$MapperProperty.post_instrument_classrF zDict[Any, object]z#Dict[_IdentityKeyType[Any], object]) �session� source_state� source_dict� dest_state� dest_dict�load� _recursive�_resolve_conflict_mapro c C s dS )zoMerge the attribute represented by this ``MapperProperty`` from source to destination object. NrZ ) ru r� r� r� r� r� r� r� r� rZ rZ r` �merge� s zMapperProperty.mergec C s d| j jt| �t| dd�f S )Nz<%s at 0x%x; %s>r| zno key)� __class__r\ �idr� rt rZ rZ r` �__repr__� s �zMapperProperty.__repr__)N)NF) r\ r] r^ r� r_ r, ZExtendedInternalTraversalZdp_has_cache_keyZ dp_stringr� rl r ZcascadeZ is_propertyZ_is_relationshipr� r� r� r� r� r� r� r� r� r� r� r� r� r� rZ rZ rZ r` r� w s@ � � � r� c @ s� e Zd ZU dZdZdZded< ded< ded < dKd ddd �d d�Zej dd�dd��Z dd�dd�Z ddd�dd�Z dd d �d d �Z ejd d�d!d"��ZdLd#dd$d%�d&d'�Zejd(d�d)d*��Zejd+d�d,d-��Zeddddd.�d/d0��Zeddddd1�d2d3��Zedddd4�d5d6��Zeeje�Zeeje�Zeeje�Z e j �rnd7ddd$d8�d9d:�Z d7ddd$d8�d;d<�Z d=d d>�d?d@�Z!dAdBdC�dDdE�Z"dMd#ddFd%�dGdH�Z#dNd#ddFd%�dIdJ�Z$d S )O�PropComparatora& Defines SQL operations for ORM mapped attributes. SQLAlchemy allows for operators to be redefined at both the Core and ORM level. :class:`.PropComparator` is the base class of operator redefinition for ORM-level operations, including those of :class:`.ColumnProperty`, :class:`.Relationship`, and :class:`.Composite`. User-defined subclasses of :class:`.PropComparator` may be created. The built-in Python comparison and math operator methods, such as :meth:`.operators.ColumnOperators.__eq__`, :meth:`.operators.ColumnOperators.__lt__`, and :meth:`.operators.ColumnOperators.__add__`, can be overridden to provide new operator behavior. The custom :class:`.PropComparator` is passed to the :class:`.MapperProperty` instance via the ``comparator_factory`` argument. In each case, the appropriate subclass of :class:`.PropComparator` should be used:: # definition of custom PropComparator subclasses from sqlalchemy.orm.properties import ( ColumnProperty, Composite, Relationship, ) class MyColumnComparator(ColumnProperty.Comparator): def __eq__(self, other): return self.__clause_element__() == other class MyRelationshipComparator(Relationship.Comparator): def any(self, expression): "define the 'any' operation" # ... class MyCompositeComparator(Composite.Comparator): def __gt__(self, other): "redefine the 'greater than' operation" return sql.and_( *[ a > b for a, b in zip( self.__clause_element__().clauses, other.__composite_values__(), ) ] ) # application of custom PropComparator subclasses from sqlalchemy.orm import column_property, relationship, composite from sqlalchemy import Column, String class SomeMappedClass(Base): some_column = column_property( Column("some_column", String), comparator_factory=MyColumnComparator, ) some_relationship = relationship( SomeOtherClass, comparator_factory=MyRelationshipComparator ) some_composite = composite( Column("a", String), Column("b", String), comparator_factory=MyCompositeComparator, ) Note that for column-level operator redefinition, it's usually simpler to define the operators at the Core level, using the :attr:`.TypeEngine.comparator_factory` attribute. See :ref:`types_operators` for more detail. .. seealso:: :class:`.ColumnProperty.Comparator` :class:`.Relationship.Comparator` :class:`.Composite.Comparator` :class:`.ColumnOperators` :ref:`types_operators` :attr:`.TypeEngine.comparator_factory` ��prop� _parententity�_adapt_to_entityZorm_prop_comparatorz_InternalEntityType[Any]r� zOptional[AliasedInsp[Any]]r� z,RODescriptorReference[MapperProperty[_T_co]]r� NzMapperProperty[_T])r� � parentmapper�adapt_to_entityc C s || _ |p || _|| _d S rp r� )ru r� r� r� rZ rZ r` r� s zPropComparator.__init__zMapperProperty[_T_co]rn c C s | j S )z�Return the :class:`.MapperProperty` associated with this :class:`.PropComparator`. Return values here will commonly be instances of :class:`.ColumnProperty` or :class:`.Relationship`. )r� rt rZ rZ r` r� s zPropComparator.propertyzroles.ColumnsClauseRolec C s t d| ��d S )Nz%rr� rt rZ rZ r` �__clause_element__ s z!PropComparator.__clause_element__r z(Sequence[Tuple[_DMLColumnArgument, Any]])�valuero c C s t d| �� �|fgS )z�Receive a SQL expression that represents a value in the SET clause of an UPDATE statement. Return a tuple that can be passed to a :class:`_expression.Update` construct. rN )r r� )ru r� rZ rZ r` �_bulk_update_tuples s z"PropComparator._bulk_update_tupleszAliasedInsp[Any]zPropComparator[_T_co])r� ro c C s | � | j| j|�S )z�Return a copy of this PropComparator which will use the given :class:`.AliasedInsp` to produce corresponding expressions. )r� r� r� )ru r� rZ rZ r` r� + s z PropComparator.adapt_to_entityr� c C s | j jS )zZlegacy; this is renamed to _parententity to be compatible with QueryableAttribute.)r� r� rt rZ rZ r` � _parentmapper3 s z PropComparator._parentmapperz)Optional[_ColumnExpressionArgument[bool]]zColumnElement[Any])� criterionr� ro c K s | j jj|fi |��S rp )r� r� �_criterion_exists�ru r� r� rZ rZ r` r� 9 s z PropComparator._criterion_existszOptional[_ORMAdapterProto]c C s | j du rdS | j jS dS )zrProduce a callable that adapts column expressions to suit an aliased version of this comparator. N)r� Z_orm_adapt_elementrt rZ rZ r` r� @ s zPropComparator.adapterrO c C s | j jS rp )r� r� rt rZ rZ r` r� K s zPropComparator.info)�a�br� ro c K s | j |fi |��S rp )�any)r� r� r� rZ rZ r` �_any_opO s zPropComparator._any_op)�left�otherr� ro c K s | j |fi |��S rp )�has)r� r� r� rZ rZ r` �_has_opS s zPropComparator._has_op)r� r� ro c C s | � |�S rp )�of_type)r� r� rZ rZ r` � _of_type_opW s zPropComparator._of_type_oprP )�opr� r� ro c O s d S rp rZ �ru r� r� r� rZ rZ r` �operatea s zPropComparator.operatec K s d S rp rZ r� rZ rZ r` �reverse_operatee s z PropComparator.reverse_operatez_EntityType[Any])r� ro c C s | � tj|�S )a� Redefine this object in terms of a polymorphic subclass, :func:`_orm.with_polymorphic` construct, or :func:`_orm.aliased` construct. Returns a new PropComparator from which further criterion can be evaluated. e.g.:: query.join(Company.employees.of_type(Engineer)).filter( Engineer.name == "foo" ) :param \class_: a class or mapper indicating that criterion will be against this specific subclass. .. seealso:: :ref:`orm_queryguide_joining_relationships_aliased` - in the :ref:`queryguide_toplevel` :ref:`inheritance_of_type` )r r� � of_type_op)ru r� rZ rZ r` r� i s zPropComparator.of_typez _ColumnExpressionArgument[bool]zPropComparator[bool])�criteriaro c G s | j tjg|�R � S )a? Add additional criteria to the ON clause that's represented by this relationship attribute. E.g.:: stmt = select(User).join( User.addresses.and_(Address.email_address != "foo") ) stmt = select(User).options( joinedload(User.addresses.and_(Address.email_address != "foo")) ) .. versionadded:: 1.4 .. seealso:: :ref:`orm_queryguide_join_on_augmented` :ref:`loader_option_criteria` :func:`.with_loader_criteria` )r r* �and_)ru r rZ rZ r` r � s zPropComparator.and_zColumnElement[bool]c K s | j tj|fi |��S )a Return a SQL expression representing true if this element references a member which meets the given criterion. The usual implementation of ``any()`` is :meth:`.Relationship.Comparator.any`. :param criterion: an optional ClauseElement formulated against the member class' table or attributes. :param \**kwargs: key/value pairs corresponding to member class attribute names which will be compared via equality to the corresponding values. )r r� �any_opr� rZ rZ r` r� � s zPropComparator.anyc K s | j tj|fi |��S )a Return a SQL expression representing true if this element references a member which meets the given criterion. The usual implementation of ``has()`` is :meth:`.Relationship.Comparator.has`. :param criterion: an optional ClauseElement formulated against the member class' table or attributes. :param \**kwargs: key/value pairs corresponding to member class attribute names which will be compared via equality to the corresponding values. )r r� �has_opr� rZ rZ r` r� � s zPropComparator.has)N)N)N)N)%r\ r] r^ r� r_ Z__visit_name__rl r� r) Znon_memoized_propertyr� r� r� r� Zro_non_memoized_propertyr� r� r� r� � staticmethodr� r� r� r r* rP r r r �typingr r r r� r r� r� rZ rZ rZ r` r� � sN ` � � � �r� c @ s� e Zd ZU dZdZdZded< ded< ded < d d �d d �Zdd �dd�Zdddd�dd�Z ddd�dd�Z dddd d d d �d d!�Z dddd"d#d d$d d%�d&d'�Z d d �d(d)�Z d"d d*�d+d,�Ze�e�Zd-ed.< ed d/d0�d1d2��Zed3d d4d5�d6d7��Zd8S )9�StrategizedPropertya� A MapperProperty which uses selectable strategies to affect loading behavior. There is a single strategy selected by default. Alternate strategies can be selected at Query time through the usage of ``StrategizedOption`` objects via the Query.options() method. The mechanics of StrategizedProperty are used for every Query invocation for every mapped attribute participating in that Query, to determine first how the attribute will be rendered in SQL and secondly how the attribute will retrieve a value from a result row and apply it to a mapped object. The routines here are very performance-critical. )� _strategies�strategyZ_wildcard_token�_default_path_loader_key� strategy_keyTz ClassVar[str]�strategy_wildcard_key� _StrategyKeyr z"Dict[_StrategyKey, LoaderStrategy]r z Tuple[str]rn c C s | j � dtj� �fS )N�:)r r Z_WILDCARD_TOKENrt rZ rZ r` � _memoized_attr__wildcard_token� s �z2StrategizedProperty._memoized_attr__wildcard_tokenzTuple[str, Tuple[str]]c C s d| j � dtj� �ffS )N�loaderr )r r Z_DEFAULT_TOKENrt rZ rZ r` �'_memoized_attr__default_path_loader_key� s �z;StrategizedProperty._memoized_attr__default_path_loader_keyr> rD �Optional[_LoadElement])r� r� ro c C s> d }|| }|j |j|jfD ] }||jv r |j| } q:q |S rp )Z _loader_keyZ_wildcard_path_loader_keyr � attributes)ru r� r� r� � search_pathZpath_keyrZ rZ r` �_get_context_loader� s � z'StrategizedProperty._get_context_loader�LoaderStrategyr� c C sJ z | j | W S ty Y n0 | j| g|�R � }|| |� | j |< }|S rp )r �KeyError�_strategy_lookup)ru r| rq r rZ rZ r` � _get_strategy s z!StrategizedProperty._get_strategyr= r� r rx r� c K sH | � ||�}|r$|jr$| �|j�}n| j}|j|||||fi |�� d S rp )r r r � setup_query)ru r� r� r� r� r� r �stratrZ rZ r` r� % s ��zStrategizedProperty.setupr� r� rB r� c C sF | � ||�}|r$|jr$| �|j�} n| j} | �||||||||� d S rp )r r r r� ) ru r� r� r� r� r� r� r� r r rZ rZ r` r� 6 s �z(StrategizedProperty.create_row_processorc C s i | _ | �| j�| _d S rp )r r r r rt rZ rZ r` r� P s zStrategizedProperty.do_initr� c C s& | j js"|j�| j�s"| j�|� d S rp )r� Z non_primaryZ class_managerZ_attr_has_implr| r �init_class_attributer� rZ rZ r` r� T s � �z)StrategizedProperty.post_instrument_classz\collections.defaultdict[Type[MapperProperty[Any]], Dict[_StrategyKey, Type[LoaderStrategy]]]�_all_strategieszCallable[[_TLS], _TLS])r� ro c s ddd�� �fdd� }|S )NrW )�dec_clsro c s> d| j vrg | _tt��� ��}| � j� |< | j�|� | S )N�_strategy_keys)�__dict__r! �tuple�sorted�itemsr �append)r r| �rq r� rZ r` �decoratea s z2StrategizedProperty.strategy_for.<locals>.decoraterZ )rq r� r( rZ r' r` � strategy_for_ s z StrategizedProperty.strategy_for�MapperProperty[Any]rX )�requesting_propertyr| ro c G s� |j j | jD ]L}|| jv rtr.t|t�s.J �| j| }z|| W S tyX Y q0 q| j�� D ] \}}||v rf|}|| } q�qfd }d }t � | ||||��d S rp ) r� Z_with_polymorphic_mappers�__mro__r r � issubclassr� r r% �orm_excZLoaderStrategyException) rq r+ r| Zprop_cls� strategiesZ property_typeZstratsZintended_property_typeZactual_strategyrZ rZ r` r m s0 �z$StrategizedProperty._strategy_lookupN)r\ r] r^ r� r_ Z inherit_cacherl r r r r r� r� r� r� � collections� defaultdict�dictr r� r) r rZ rZ rZ r` r � s( � r c @ sB e Zd ZdZdZdZdZdZdZdZ dZ dZ dd d d�dd�Z dS ) � ORMOptiona� Base class for option objects that are passed to ORM queries. These options may be consumed by :meth:`.Query.options`, :meth:`.Select.options`, or in a more general sense by any :meth:`.Executable.options` method. They are interpreted at statement compile time or execution time in modern use. The deprecated :class:`.MapperOption` is consumed at ORM query construction time. .. versionadded:: 1.4 rZ Fr? )r� � uncached_optro c C s |dur |S | S dS )a� adapt this option to the "uncached" version of itself in a loader strategy context. given "self" which is an option from a cached query, as well as the corresponding option from the uncached version of the same query, return the option we should use in a new query, in the context of a loader strategy being asked to load related rows on behalf of that cached query, which is assumed to be building a new query based on entities passed to us from the cached query. Currently this routine chooses between "self" and "uncached" without manufacturing anything new. If the option is itself a loader strategy option which has a path, that path needs to match to the entities being passed to us by the cached query, so the :class:`_orm.Load` subclass overrides this to return "self". For all other options, we return the uncached form which may have changing state, such as a with_loader_criteria() option which will very often have new state. This routine could in the future involve generating a new option based on both inputs if use cases arise, such as if with_loader_criteria() needed to match up to ``AliasedClass`` instances given in the parent query. However, longer term it might be better to restructure things such that ``AliasedClass`` entities are always matched up on their cache key, instead of identity, in things like paths and such, so that this whole issue of "the uncached option does not match the entities" goes away. However this would make ``PathRegistry`` more complicated and difficult to debug as well as potentially less performant in that it would be hashing enormous cache keys rather than a simple AliasedInsp. UNLESS, we could get cache keys overall to be reliably hashed into something like an md5 key. .. versionadded:: 1.4.41 NrZ )ru r� r4 rZ rZ r` �'_adapt_cached_option_to_uncached_option� s 'z1ORMOption._adapt_cached_option_to_uncached_optionN) r\ r] r^ r� r_ �_is_legacy_option�propagate_to_loadersZ_is_core�_is_user_defined�_is_compile_state�_is_criteria_optionZ_is_strategy_optionr5 rZ rZ rZ r` r3 � s r3 c @ s: e Zd ZdZdZdZddd�dd�Zdd dd �d d �Zd S )�CompileStateOptiona� base for :class:`.ORMOption` classes that affect the compilation of a SQL query and therefore need to be part of the cache key. .. note:: :class:`.CompileStateOption` is generally non-public and should not be used as a base class for user-defined options; instead, use :class:`.UserDefinedOption`, which is easier to use as it does not interact with ORM compilation internals or caching. :class:`.CompileStateOption` defines an internal attribute ``_is_compile_state=True`` which has the effect of the ORM compilation routines for SELECT and other statements will call upon these options when a SQL string is being compiled. As such, these classes implement :class:`.HasCacheKey` and need to provide robust ``_cache_key_traversal`` structures. The :class:`.CompileStateOption` class is used to implement the ORM :class:`.LoaderOption` and :class:`.CriteriaOption` classes. .. versionadded:: 1.4.28 rZ Tr> rx )� compile_statero c C s dS )z�Apply a modification to a given :class:`.ORMCompileState`. This method is part of the implementation of a particular :class:`.CompileStateOption` and is only invoked internally when an ORM query is compiled. NrZ )ru r< rZ rZ r` �process_compile_state� s z(CompileStateOption.process_compile_state�Sequence[_MapperEntity]�r< �mapper_entitiesro c C s dS )aq Apply a modification to a given :class:`.ORMCompileState`, given entities that were replaced by with_only_columns() or with_entities(). This method is part of the implementation of a particular :class:`.CompileStateOption` and is only invoked internally when an ORM query is compiled. .. versionadded:: 1.4.19 NrZ �ru r< r@ rZ rZ r` �'process_compile_state_replaced_entities s z:CompileStateOption.process_compile_state_replaced_entitiesN)r\ r] r^ r� r_ r9 r= rB rZ rZ rZ r` r; � s r; c @ s& e Zd ZdZdZdddd�dd�Zd S ) � LoaderOptionzhDescribe a loader modification to an ORM statement at compilation time. .. versionadded:: 1.4 rZ r> r> rx r? c C s | � |� d S rp )r= rA rZ rZ r` rB s z4LoaderOption.process_compile_state_replaced_entitiesN)r\ r] r^ r� r_ rB rZ rZ rZ r` rC s rC c @ s( e Zd ZdZdZdZddd�dd�Zd S ) �CriteriaOptionztDescribe a WHERE criteria modification to an ORM statement at compilation time. .. versionadded:: 1.4 rZ TzDict[str, Any]rx )r ro c C s dS )z_update additional entity criteria options in the given attributes dictionary. NrZ )ru r rZ rZ r` �get_global_criteria3 s z"CriteriaOption.get_global_criteriaN)r\ r] r^ r� r_ r: rE rZ rZ rZ r` rD ' s rD c @ s0 e Zd ZdZdZdZdZdZd dd�dd�ZdS ) �UserDefinedOptionz~Base class for a user-defined option that can be consumed from the :meth:`.SessionEvents.do_orm_execute` event hook. ��payloadFTNr� c C s || _ d S rp rG )ru rH rZ rZ r` r� M s zUserDefinedOption.__init__)N) r\ r] r^ r� r_ r6 r8 r7 r� rZ rZ rZ r` rF : s rF z1.4aK The :class:`.MapperOption class is deprecated and will be removed in a future release. For modifications to queries on a per-execution basis, use the :class:`.UserDefinedOption` class to establish state within a :class:`.Query` or other Core statement, then use the :meth:`.SessionEvents.before_orm_execute` hook to consume them.)� constructorc @ s< e Zd ZdZdZdZdZddd�dd �Zddd�d d �Zd S ) � MapperOptionz"Describe a modification to a QueryrZ TFz Query[Any]rx )�queryro c C s dS )z8Apply a modification to the given :class:`_query.Query`.NrZ �ru rK rZ rZ r` � process_queryi s zMapperOption.process_queryc C s | � |� dS )ao same as process_query(), except that this option may not apply to the given query. This is typically applied during a lazy load or scalar refresh operation to propagate options stated in the original Query to the new Query being used for the load. It occurs for those options that specify propagate_to_loaders=True. N)rM rL rZ rZ r` �process_query_conditionallyl s z(MapperOption.process_query_conditionallyN) r\ r] r^ r� r_ r6 r7 rM rN rZ rZ rZ r` rJ Q s rJ c @ s� e Zd ZU dZdZded< ddd�dd �Zd d d �d d�Zddddddd d�dd�Zddddd dddd d� dd �Z d d �d d �Z d!S )"r a� Describe the loading behavior of a StrategizedProperty object. The ``LoaderStrategy`` interacts with the querying process in three ways: * it controls the configuration of the ``InstrumentedAttribute`` placed on a class to handle the behavior of the attribute. this may involve setting up class-level callable functions to fire off a select operation when the attribute is first accessed (i.e. a lazy load) * it processes the ``QueryContext`` at statement construction time, where it can modify the SQL statement that is being produced. For example, simple column attributes will add their represented column to the list of selected columns, a joined eager loader may establish join clauses to add to the statement. * It produces "row processor" functions at result fetching time. These "row processor" functions populate a particular attribute on a particular mapped instance. )�parent_property�is_class_levelr� r| r � strategy_optsz ClassVar[List[_StrategyKey]]r! r* r )r� r c C s4 || _ d| _| j j| _| j j| _|| _t|�| _d S )NF)rO rP r� r| r r2 rQ )ru r� r rZ rZ r` r� � s zLoaderStrategy.__init__r� rx r� c C s d S rp rZ r� rZ rZ r` r � s z#LoaderStrategy.init_class_attributer> r= rD r r� r )r< r� r� �loadoptr� r� ro c K s dS )z�Establish column and other state for a given QueryContext. This method fulfills the contract specified by MapperProperty.setup(). StrategizedProperty delegates its setup() method directly to this method. NrZ )ru r< r� r� rR r� r� rZ rZ r` r � s zLoaderStrategy.setup_queryr� rB ) r� r� r� rR r� r� r� r� ro c C s dS )a Establish row processing functions for a given QueryContext. This method fulfills the contract specified by MapperProperty.create_row_processor(). StrategizedProperty delegates its create_row_processor() method directly to this method. NrZ ) ru r� r� r� rR r� r� r� r� rZ rZ r` r� � s z#LoaderStrategy.create_row_processorre rn c C s t | j�S rp )re rO rt rZ rZ r` �__str__� s zLoaderStrategy.__str__N) r\ r] r^ r� r_ rl r� r r r� rS rZ rZ rZ r` r z s r )�r� � __future__r r0 r� r r r r r r r r r r r r r r r r r r r � r r. r �baser r r r r r r r r r! r" r# r$ r% r' r� r( r) Zsqlr* r+ r, Zsql.baser- r. Z sql.cache_keyr/ Z sql.operatorsr0 Z sql.schemar1 Z sql.type_apir2 r3 Z util.typingr4 r5 Z_typingr6 r7 r8 r9 r: r r; r< r� r= r> r? Zdecl_apir@ Z decl_baserA ZloadingrB r� rC rD rK rE r� rF r� rG Zstrategy_optionsrH rI rJ Z engine.resultrK Z sql._typingrL rM rN rO rP Z sql.visitorsrQ rR r rS rU rW Z StatementRolerY ZColumnsClauseRoleZTypedColumnsClauseRolera rb ZStrictFromClauseRolerc rd rm r� r� r� r� r� r� Z_self_inspectsZ MemoizedSlotsr� r� r r3 r; rC rD rF Zdeprecated_clsrJ r rZ rZ rZ r` �<module> s" � ,l� � � $ 7 @P7� sqlalchemy/orm/__pycache__/state.cpython-39.pyc 0000644 00000100213 15125143220 0015454 0 ustar 00 a ��Jh&� � @ s� U d Z ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z dd lm Z dd lm Z dd lm Z dd lm Z dd lZddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z ddlm Z ddlm Z dd lm Z dd l m!Z! d dlmZ" d d lm#Z# d d lm$Z$ d d!l%m&Z& d d"l%m'Z' e �r<dd#lm(Z( dd$lm)Z) dd%lm*Z* dd&l+m,Z, dd'l+m-Z- dd(lm.Z. dd)l/m0Z0 dd*l1m2Z2 dd+l3m4Z4 dd,lm5Z5 dd-l6m7Z7 dd.l8m9Z9 d d/l:m;Z; d d0l<m=Z> d d1l<m?Z? e �rLd2e@d3< nd ZAe �sZd Z>G d4d5� d5e'�ZBG d6d7� d7e'e �ZCe#jDG d8d9� d9ejEee ��ZFG d:d;� d;�ZGG d<d=� d=�ZHd S )>z�Defines instrumentation of instances. This module is usually not directly visible to user applications, but defines a large part of the ORM's interactivity. � )� annotations)�Any)�Callable)�Dict)�Generic)�Iterable)�Optional)�Set)�Tuple)� TYPE_CHECKING)�UnionN� )�base)�exc)� interfaces)�_O)�is_collection_impl)� ATTR_WAS_SET)�INIT_OK)�LoaderCallableStatus)� NEVER_SET)�NO_VALUE)�PASSIVE_NO_INITIALIZE)�PASSIVE_NO_RESULT)� PASSIVE_OFF)�SQL_OK)� PathRegistry� )� inspection)�util)�Literal)�Protocol)�_IdentityKeyType)� _InstanceDict)�_LoaderCallable)� AttributeImpl)�History)� PassiveFlag)�_AdaptedCollectionProtocol)� IdentityMap)� ClassManager)� ORMOption)�Mapper)�Session)�Row)� async_session)� AsyncSessionz)weakref.WeakValueDictionary[int, Session]� _sessionsc @ s e Zd Zdd�dd�ZdS )�_InstanceDictProto�Optional[IdentityMap]��returnc C s d S �N� ��selfr7 r7 �I/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/state.py�__call__Q � z_InstanceDictProto.__call__N)�__name__� __module__� __qualname__r; r7 r7 r7 r: r2 P s r2 c @ s$ e Zd ZdZddddd�dd�Zd S ) �_InstallLoaderCallableProtoa used at result loading time to install a _LoaderCallable callable upon a specific InstanceState, which will be used to populate an attribute when that attribute is accessed. Concrete examples are per-instance deferred column loaders and relationship lazy loaders. �InstanceState[_O]r# �Row[Any]�None��state�dict_�rowr5 c C s d S r6 r7 )r9 rE rF rG r7 r7 r: r; ^ s z$_InstallLoaderCallableProto.__call__N)r= r> r? �__doc__r; r7 r7 r7 r: r@ T s r@ c @ s| e Zd ZU dZdZded< dZded< dZded < dZded < d Z d ed < e j Z ded< dZ ded< dZded< ded< ded< dZded< dZded< dZded< dZded < dZded < d Zded < dZd ed!< dZd"ed#< d$ed%< es�d&d'� Zd(ed)< d*ed+< e�sejZd,dd-�d.d/�Z ej d0d1�d2d3��Z e dd1�d4d5��Z e dd1�d6d7��Z!e dd1�d8d9��Z"e dd1�d:d;��Z#e dd1�d<d=��Z$e dd1�d>d?��Z%ej&e�'d@�dd1�dAdB���Z(dCdDdE�dFdG�Z)e dHd1�dIdJ��Z*e dKd1�dLdM��Z+e dNd1�dOdP��Z,e dQd1�dRdS��Z-e dd1�dTdU��Z.ej dVd1�dWdX��Z/ej dYd1�dZd[��Z0ej d\d1�d]d^��Z1ej d_d1�d`da��Z2e dd1�dbdc��Z3e4d�dddeddDdf�dgdh��Z5d�dHdDdi�djdk�Z6dDd1�dldm�Z7ddDdn�dodp�Z8e dqd1�drds��Z9dtdtdDdu�dvdw�Z:dCdxdydz�d{d|�Z;dCd}dE�d~d�Z<dCd�dE�d�d��Z=dd1�d�d��Z>ddDd��d�d��Z?dqdCdDd��d�d��Z@d�dDd��d�d��ZAe4dd�dtd�d��d�d���ZBdqd�dDd��d�d��ZCd�dqd�ddDd��d�d��ZDd�dxd�d��d�d��ZEe d(d1�d�d���ZFd�d(d��d�d��ZGe d(d1�d�d���ZHe e�Id�d��d(d1�d�d����ZJe d(d1�d�d���ZKd�dqd�dtdddDd��d�d��ZLdqd�dDd��d�d��ZMd�dqd�dDd��d�d��ZNe4d�d�d�dDd��d�d���ZOdS )�� InstanceStatea Tracks state information at the instance level. The :class:`.InstanceState` is a key object used by the SQLAlchemy ORM in order to track the state of an object; it is created the moment an object is instantiated, typically as a result of :term:`instrumentation` which SQLAlchemy applies to the ``__init__()`` method of the class. :class:`.InstanceState` is also a semi-public object, available for runtime inspection as to the state of a mapped instance, including information such as its current status within a particular :class:`.Session` and details about data on individual attributes. The public API in order to acquire a :class:`.InstanceState` object is to use the :func:`_sa.inspect` system:: >>> from sqlalchemy import inspect >>> insp = inspect(some_mapped_object) >>> insp.attrs.nickname.history History(added=['new nickname'], unchanged=(), deleted=['nickname']) .. seealso:: :ref:`orm_mapper_inspection_instancestate` )�__dict__� __weakref__�class_�manager�obj�committed_state�expired_attributeszClassManager[_O]rM Nz Optional[int]� session_idz Optional[_IdentityKeyType[_O]]�key�runidr7 zTuple[ORMOption, ...]� load_optionsr � load_path� insert_orderzOptional[object]� _strong_objzweakref.ref[_O]rN zDict[str, Any]rO F�bool�modified�expired�_deleted� _load_pending� _orphaned_outside_of_sessionT� is_instance�object�identity_tokenzOptional[Dict[str, Any]]�_last_known_valuesr2 �_instance_dictc C s dS )z+default 'weak reference' for _instance_dictNr7 r8 r7 r7 r: rb � s z InstanceState._instance_dictzSet[str]rP z:Dict[str, Callable[[InstanceState[_O], PassiveFlag], Any]]� callablesr )rN rM c C s0 |j | _|| _t�|| j�| _i | _t� | _ d S r6 ) � __class__rL rM �weakref�ref�_cleanuprN rO �setrP )r9 rN rM r7 r7 r: �__init__� s zInstanceState.__init__z'util.ReadOnlyProperties[AttributeState]r4 c s t �� fdd�� jD ��S )aa Return a namespace representing each attribute on the mapped object, including its current value and history. The returned object is an instance of :class:`.AttributeState`. This object allows inspection of the current data within an attribute as well as attribute history since the last flush. c s i | ]}|t � |��qS r7 )�AttributeState)�.0rR r8 r7 r: � <dictcomp>� r< z'InstanceState.attrs.<locals>.<dictcomp>)r ZReadOnlyPropertiesrM r8 r7 r8 r: �attrs� s �zInstanceState.attrsc C s | j du o| j S )z}Return ``True`` if the object is :term:`transient`. .. seealso:: :ref:`session_object_states` N�rR � _attachedr8 r7 r7 r: � transient� s zInstanceState.transientc C s | j du o| jS )z{Return ``True`` if the object is :term:`pending`. .. seealso:: :ref:`session_object_states` Nrn r8 r7 r7 r: �pending� s zInstanceState.pendingc C s | j duo| jo| jS )a� Return ``True`` if the object is :term:`deleted`. An object that is in the deleted state is guaranteed to not be within the :attr:`.Session.identity_map` of its parent :class:`.Session`; however if the session's transaction is rolled back, the object will be restored to the persistent state and the identity map. .. note:: The :attr:`.InstanceState.deleted` attribute refers to a specific state of the object that occurs between the "persistent" and "detached" states; once the object is :term:`detached`, the :attr:`.InstanceState.deleted` attribute **no longer returns True**; in order to detect that a state was deleted, regardless of whether or not the object is associated with a :class:`.Session`, use the :attr:`.InstanceState.was_deleted` accessor. .. versionadded: 1.1 .. seealso:: :ref:`session_object_states` N�rR ro r[ r8 r7 r7 r: �deleted� s zInstanceState.deletedc C s | j S )aN Return True if this object is or was previously in the "deleted" state and has not been reverted to persistent. This flag returns True once the object was deleted in flush. When the object is expunged from the session either explicitly or via transaction commit and enters the "detached" state, this flag will continue to report True. .. seealso:: :attr:`.InstanceState.deleted` - refers to the "deleted" state :func:`.orm.util.was_deleted` - standalone function :ref:`session_object_states` )r[ r8 r7 r7 r: � was_deleted s zInstanceState.was_deletedc C s | j duo| jo| j S )a Return ``True`` if the object is :term:`persistent`. An object that is in the persistent state is guaranteed to be within the :attr:`.Session.identity_map` of its parent :class:`.Session`. .. seealso:: :ref:`session_object_states` Nrr r8 r7 r7 r: � persistent) s zInstanceState.persistentc C s | j duo| j S )z|Return ``True`` if the object is :term:`detached`. .. seealso:: :ref:`session_object_states` Nrn r8 r7 r7 r: �detached8 s zInstanceState.detachedzsqlalchemy.orm.sessionc C s | j d uo| j tjjjv S r6 )rQ r Z preloadedZ orm_sessionr1 r8 r7 r7 r: ro C s �zInstanceState._attached�strrC )rR r5 c C s, | j }|du ri | _ }||vr(t||< dS )z|Track the last known value of a particular key after expiration operations. .. versionadded:: 1.3 N)ra r )r9 rR �lkvr7 r7 r: �_track_last_known_valueK s z%InstanceState._track_last_known_valuezOptional[Session]c C s* | j r&z t| j W S ty$ Y n0 dS )aL Return the owning :class:`.Session` for this instance, or ``None`` if none available. Note that the result here can in some cases be *different* from that of ``obj in session``; an object that's been deleted will report as not ``in session``, however if the transaction is still in progress, this attribute will still refer to that session. Only when the transaction is completed does the object become fully detached under normal circumstances. .. seealso:: :attr:`_orm.InstanceState.async_session` N)rQ r1 �KeyErrorr8 r7 r7 r: �sessionY s zInstanceState.sessionzOptional[AsyncSession]c C s* t du r dS | j}|dur"t |�S dS dS )aG Return the owning :class:`_asyncio.AsyncSession` for this instance, or ``None`` if none available. This attribute is only non-None when the :mod:`sqlalchemy.ext.asyncio` API is in use for this ORM object. The returned :class:`_asyncio.AsyncSession` object will be a proxy for the :class:`_orm.Session` object that would be returned from the :attr:`_orm.InstanceState.session` attribute for this :class:`_orm.InstanceState`. .. versionadded:: 1.4.18 .. seealso:: :ref:`asyncio_toplevel` N)�_async_providerr{ )r9 �sessr7 r7 r: r/ q s zInstanceState.async_sessionz Optional[_O]c C s | � � S )z�Return the mapped object represented by this :class:`.InstanceState`. Returns None if the object has been garbage collected )rN r8 r7 r7 r: r_ � s zInstanceState.objectzOptional[Tuple[Any, ...]]c C s | j du rdS | j d S dS )a� Return the mapped identity of the mapped object. This is the primary key identity as persisted by the ORM which can always be passed directly to :meth:`_query.Query.get`. Returns ``None`` if the object has no primary key identity. .. note:: An object which is :term:`transient` or :term:`pending` does **not** have a mapped identity until it is flushed, even if its attributes include primary key values. Nr �rR r8 r7 r7 r: �identity� s zInstanceState.identityc C s | j S )z�Return the identity key for the mapped object. This is the key used to locate the object within the :attr:`.Session.identity_map` mapping. It contains the identity as returned by :attr:`.identity` within it. r~ r8 r7 r7 r: � identity_key� s zInstanceState.identity_keyz4Dict[int, Union[Literal[False], InstanceState[Any]]]c C s i S r6 r7 r8 r7 r7 r: �parents� s zInstanceState.parentsz Dict[str, PendingCollection]c C s i S r6 r7 r8 r7 r7 r: �_pending_mutations� s z InstanceState._pending_mutationsz%Dict[str, _AdaptedCollectionProtocol]c C s i S r6 r7 r8 r7 r7 r: �_empty_collections� s z InstanceState._empty_collectionsz Mapper[_O]c C s | j jS )z<Return the :class:`_orm.Mapper` used for this mapped object.)rM �mapperr8 r7 r7 r: r� � s zInstanceState.mapperc C s t | j�S )z�Return ``True`` if this object has an identity key. This should always have the same value as the expression ``state.persistent`` or ``state.detached``. )rX rR r8 r7 r7 r: � has_identity� s zInstanceState.has_identityzIterable[InstanceState[_O]]r- )�statesr{ � to_transientr5 c C s� |j jp d }|j jpd }|j jp"d }|j jp.d }|D ]�}|j} |jd u } | oR| } d |_|rh|jrh|`| r�|r�|d ur�|||� q�|d ur�|||� n.| r�|d ur�|||� n| r�|d ur�|||� d |_q4d S r6 ) �dispatch�persistent_to_detached�deleted_to_detached�pending_to_transient�persistent_to_transientr[ rR rQ rW ) r9 r� r{ r� r� r� r� r� rE rs rq ru r7 r7 r: �_detach_states� s0 � � z InstanceState._detach_states)r{ r5 c C s$ |rt �| g|� n d | _| _d S r6 )rI r� rQ rW )r9 r{ r7 r7 r: �_detach� s zInstanceState._detachc C s | � � d S r6 )r� r8 r7 r7 r: �_dispose� s zInstanceState._dispose)rf r5 c C s: t du r dS | �� }|dur*|�| � | `d | _| _dS )z�Weakref callback cleanup. This callable cleans out the state when it is being garbage collected. this _cleanup **assumes** that there are no strong refs to us! Will not work otherwise! N)�dictrb Z _fast_discardrQ rW )r9 rf � instance_dictr7 r7 r: rg s zInstanceState._cleanupr# c C s" | � � }|durt�|�S i S dS )a Return the instance dict used by the object. Under normal circumstances, this is always synonymous with the ``__dict__`` attribute of the mapped object, unless an alternative instrumentation system has been configured. In the case that the actual object has been garbage collected, this accessor returns a blank dictionary. N)rN r r� )r9 �or7 r7 r: r� s zInstanceState.dictr )�mixed�kwargsr5 c O s� | d | d | dd � }}}|j }|j�|||� z |j| dd � i |�� W nD t�� � |j�|||� W d � n1 s�0 Y Y n0 d S )Nr r r )rM r� �initZ original_initr Z safe_reraiseZ init_failure)r� r� r9 �instance�argsrM r7 r7 r: �_initialize_instance2 s z"InstanceState._initialize_instancer' r& )rR �passiver5 c C s | j | j�| | j|�S r6 )rM �impl� get_historyr� )r9 rR r� r7 r7 r: r� > s zInstanceState.get_historyr% c C s | j | jS r6 )rM r� �r9 rR r7 r7 r: �get_implA s zInstanceState.get_impl�PendingCollectionc C s || j vrt� | j |< | j | S r6 )r� r� r� r7 r7 r: �_get_pending_mutationD s z#InstanceState._get_pending_mutationc sZ � � � � j� j� jd�}|�� fdd�dD �� � jrD� j�� |d< � j�� |�|d< |S )N)r� rL rO rP c 3 s& | ] }|� j v r|� j | fV qd S r6 )rJ �rk �kr8 r7 r: � <genexpr>P s �z-InstanceState.__getstate__.<locals>.<genexpr>) r� rY rZ rc rR r� rT rL rP �inforU rM ) rN rL rO rP �updaterU � serializerM � _serialize)r9 � state_dictr7 r8 r: � __getstate__I s ��zInstanceState.__getstate__)r� r5 c s2 � d }|d ur*t �|| j�| _|j| _ndd� | _� d | _� �di �| _� �di �| _� �di �| _ � �dd �| _ � �d d �| _ d � v r�| j � � d � d � v r�� d | _� d | _n d � v rΈ d | _nt� | _| j� � fdd�dD �� | j�r| jd | _d� v �r t�� d �| _� d | |� � d S )Nr� c S s d S r6 r7 r7 r7 r7 r: �<lambda>m r< z,InstanceState.__setstate__.<locals>.<lambda>rL rO r� r� rY FrZ r� rc rP c s g | ]}|� v r|� | f�qS r7 r7 r� �r� r7 r: � <listcomp>� s �z.InstanceState.__setstate__.<locals>.<listcomp>)rR rT r rU rM )re rf rg rN rd rL �getrO r� r� rY rZ r� r� rc rP rh rJ rR r` r Z deserializerU )r9 r� �instr7 r� r: � __setstate__g s: �� zInstanceState.__setstate__)rF rR r5 c C sV |� |d�}| j| j}|dur2t|�r2|�|� | j�|� | jrR| j� |d� dS )zHRemove the given attribute and any callables associated with it.N)�poprM r� r �_invalidate_collectionrP �discardrc )r9 rF rR �oldZ manager_implr7 r7 r: �_reset� s zInstanceState._reset�InstanceState[Any])�from_r5 c C s d|j v rt|j�| _d S �Nrc )rJ r� rc )r9 r� r7 r7 r: �_copy_callables� s z InstanceState._copy_callablesr$ z _InstallLoaderCallableProto[_O])rM �fnrR r5 c sR |� j }t|�r4|� ddddd�� ��fdd� }nddddd���fdd� }|S ) NrA r# rB rC rD c s< d| j vri | _|��d �}|d ur.� �|� �| j�< d S r� )rJ rc r� r� )rE rF rG r� �Z fixed_implr� rR r7 r: � _set_callable� s zGInstanceState._instance_level_callable_processor.<locals>._set_callablec s d| j vri | _� | j�< d S r� )rJ rc )rE rF rG )r� rR r7 r: r� � s )r� r )�clsrM r� rR r� r� r7 r� r: �"_instance_level_callable_processor� s z0InstanceState._instance_level_callable_processorzSet[InstanceState[Any]])rF � modified_setr5 c s d| _ | jr&|�| � | j�� d| _d | _d| jv r>| jd= d| jv rP| jd= | j�dd� | j j D �� | j r�| j� | j �D ] }| j |= q~| j j � � �D ]}� �|�}d|j_q�| jr�| j�� fdd�| jD �� | j j� � �D ] }� |= q�| j j�| d � d S ) NTFr� r� c S s g | ] }|j �qS r7 r~ )rk r� r7 r7 r: r� � r< z)InstanceState._expire.<locals>.<listcomp>c s i | ]}|� v r|� | �qS r7 r7 r� �rF r7 r: rl � r< z)InstanceState._expire.<locals>.<dictcomp>)rZ rY r� rO �clearrW rJ rP r� rM Z _loader_implsrc � intersectionZ_collection_impl_keysr� Z _sa_adapterZ invalidatedra Z _all_key_setr� �expire)r9 rF r� r� � collectionrR r7 r� r: �_expire� s4 � �zInstanceState._expirez Iterable[str])rF �attribute_names� no_loaderr5 c C s� | j �dd �}| j}|D ]�}| j| j}|jr`|rB|js||v rBq| j�|� |r`||v r`||= |� |t �}t |�r�|t ur�|� |� | j } | d ur�|| v r�|t ur�|| |< | j� |d � |r|� |d � q| jj�| |� d S )Nr� )rJ r� rc rM r� �accepts_scalar_loaderZ callable_rP �addr� r r r� ra rO r� r� ) r9 rF r� r� rq rc rR r� r� rx r7 r7 r: �_expire_attributes� s( z InstanceState._expire_attributesrA r )rE r� r5 c sP |t @ s tS � j�� j�}|�� fdd�|D ��}� j�� ||� � j�� t S )z�__call__ allows the InstanceState to act as a deferred callable for loading expired attributes, which is also serializable (picklable). c 3 s | ]}� j | jjs|V qd S r6 )rM r� Zload_on_unexpire�rk �attrr8 r7 r: r� s �z.InstanceState._load_expired.<locals>.<genexpr>) r r rP r� � unmodified� differencerM Zexpired_attribute_loaderr� r )r9 rE r� Ztoloadr7 r8 r: � _load_expired s � zInstanceState._load_expiredc C s t | j��| j�S )z8Return the set of keys which have no uncommitted changes)rh rM r� rO r8 r7 r7 r: r� - s zInstanceState.unmodified)�keysr5 c C s t |��| j��| j�S )z*Return self.unmodified.intersection(keys).)rh r� rM r� rO )r9 r� r7 r7 r: �unmodified_intersection3 s ���z%InstanceState.unmodified_intersectionc C s t | j��| j��| j�S )z�Return the set of keys which do not have a loaded value. This includes expired attributes and any other attribute that was never populated or modified. )rh rM r� rO r� r8 r7 r7 r: �unloaded< s ���zInstanceState.unloadedz2.0zsThe :attr:`.InstanceState.unloaded_expirable` attribute is deprecated. Please use :attr:`.InstanceState.unloaded`.c C s | j S )z�Synonymous with :attr:`.InstanceState.unloaded`. This attribute was added as an implementation-specific detail at some point and should be considered to be private. )r� r8 r7 r7 r: �unloaded_expirableJ s z InstanceState.unloaded_expirablec s � j �� fdd�� jD ��S )Nc 3 s | ]}� j | jjr|V qd S r6 )rM r� r� r� r8 r7 r: r� [ s �z5InstanceState._unloaded_non_object.<locals>.<genexpr>)r� r� rM r8 r7 r8 r: �_unloaded_non_objectY s �z"InstanceState._unloaded_non_objectzOptional[AttributeImpl])rF r� �previousr� � is_userlandr5 c C s� |r�|j sd S |r,|j|vr,t�d|j ��|j| jvs<|r�|r�trPt|�sPJ �|tu rl|j|v rl||j }|d ttfvr�|� |�}|| j|j< | j }|d ur�|j|v r�t||j< | j r�| j d u s�| j �s|d| _ | �� }|r�t|j�}|j�| � nd}| �� } | j �rL| | _ |�sLzt| j } W n t�y6 Y n0 | jd u �rL| �� | d u �r||�r|t�d| j|j t�| �f ��d S )NzHCan't flag attribute '%s' modified; it's not present in the object stateTFzaCan't emit change event for attribute '%s' - parent object of type %s has been garbage collected.) Zsend_modified_eventsrR �sa_excZInvalidRequestErrorrO r r r r �copyra rQ rW rY rb rX � _modifiedr� rN r1 rz Z _transactionZ _autobegin_t�orm_excZObjectDereferencedErrorrM r Zstate_class_str) r9 rF r� r� r� r� rx r� Z has_modifiedr� r{ r7 r7 r: �_modified_eventa sZ �� ��z InstanceState._modified_event)rF r� r5 c C sb |D ]}| j �|d� qd| _| j�t|��|�� | jr^t| j��|��|�D ] }| j|= qPdS )a8 Commit attributes. This is used by a partial-attribute load operation to mark committed those attributes which were refreshed from the database. Attributes marked as "expired" can potentially remain "expired" after this step if a value was not populated in state.dict. NF)rO r� rZ rP �difference_updaterh r� rc )r9 rF r� rR r7 r7 r: �_commit� s ��zInstanceState._commitr3 )rF r� r5 c C s | � | |fg|� dS )aS commit all attributes unconditionally. This is used after a flush() or a full load/refresh to remove all pending state from the instance. - all attributes are marked as "committed" - the "strong dirty reference" is removed - the "modified" flag is set to False - any "expired" markers for scalar attributes loaded are removed. - lazy load callables for objects / collections *stay* Attributes marked as "expired" can potentially remain "expired" after this step if a value was not populated in state.dict. N)�_commit_all_states)r9 rF r� r7 r7 r: � _commit_all� s zInstanceState._commit_allz2Iterable[Tuple[InstanceState[Any], _InstanceDict]])�iter_r� r5 c C sd |D ]Z\}}|j }|j�� d|v r*|d= |j�|� |rL|jrL|j�|� d |_|_d|_ qdS )z.Mass / highly inlined version of commit_all().r� FN) rJ rO r� rP r� rY r� r� rZ rW )r9 r� r� rE rF r� r7 r7 r: r� � s z InstanceState._commit_all_states)F)N)F)FF)N)N)Pr= r> r? rH � __slots__�__annotations__rQ rR rS rT r �rootrU rV rW rY rZ r[ r\ r] r^ r` ra r rb r � EMPTY_DICTrc ri Zmemoized_propertyrm �propertyrp rq rs rt ru rv Znon_memoized_propertyZpreload_modulero ry r{ r/ r_ r r� r� r� r� r� r� � classmethodr� r� r� rg r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� � deprecatedr� r� r� r� r� r� r7 r7 r7 r: rI c s� �% ) 6 �! � �H � �rI c @ sz e Zd ZU dZdZded< ded< ddd�dd�Zed d �d d ��Zed d �d d��Z edd �dd��Z dd �dd�Z dS )rj a� Provide an inspection interface corresponding to a particular attribute on a particular mapped object. The :class:`.AttributeState` object is accessed via the :attr:`.InstanceState.attrs` collection of a particular :class:`.InstanceState`:: from sqlalchemy import inspect insp = inspect(some_mapped_object) attr_state = insp.attrs.some_attribute �rE rR r� rE rw rR c C s || _ || _d S r6 r� )r9 rE rR r7 r7 r: ri s zAttributeState.__init__r r4 c C s | j j�| jt�S )z�The current value of this attribute as loaded from the database. If the value has not been loaded, or is otherwise not present in the object's dictionary, returns NO_VALUE. )rE r� r� rR r r8 r7 r7 r: � loaded_value s zAttributeState.loaded_valuec C s | j j| j �| j �� | j j�S )z�Return the value of this attribute. This operation is equivalent to accessing the object's attribute directly or via ``getattr()``, and will fire off any pending loader callables if needed. )rE rM rR �__get__rN rL r8 r7 r7 r: �value s �zAttributeState.valuer& c C s | j �| jt�S )ai Return the current **pre-flush** change history for this attribute, via the :class:`.History` interface. This method will **not** emit loader callables if the value of the attribute is unloaded. .. note:: The attribute history system tracks changes on a **per flush basis**. Each time the :class:`.Session` is flushed, the history of each attribute is reset to empty. The :class:`.Session` by default autoflushes each time a :class:`_query.Query` is invoked. For options on how to control this, see :ref:`session_flushing`. .. seealso:: :meth:`.AttributeState.load_history` - retrieve history using loader callables if the value is not locally present. :func:`.attributes.get_history` - underlying function )rE r� rR r r8 r7 r7 r: �history" s zAttributeState.historyc C s | j �| jttA �S )a Return the current **pre-flush** change history for this attribute, via the :class:`.History` interface. This method **will** emit loader callables if the value of the attribute is unloaded. .. note:: The attribute history system tracks changes on a **per flush basis**. Each time the :class:`.Session` is flushed, the history of each attribute is reset to empty. The :class:`.Session` by default autoflushes each time a :class:`_query.Query` is invoked. For options on how to control this, see :ref:`session_flushing`. .. seealso:: :attr:`.AttributeState.history` :func:`.attributes.get_history` - underlying function )rE r� rR r r r8 r7 r7 r: � load_history> s zAttributeState.load_historyN) r= r> r? rH r� r� ri r� r� r� r� r� r7 r7 r7 r: rj � s rj c @ sd e Zd ZU dZdZded< ded< dd�d d �Zd d d �d d�Zddd�dd�Zddd�dd�Z dS )r� a A writable placeholder for an unloaded collection. Stores items appended to and removed from a collection that has not yet been loaded. When the collection is loaded, the changes stored in PendingCollection are applied to it to produce the final result. )� deleted_items� added_itemszutil.IdentitySetr� zutil.OrderedIdentitySetr� rC r4 c C s t �� | _t �� | _d S r6 )r Z IdentitySetr� ZOrderedIdentitySetr� r8 r7 r7 r: ri f s zPendingCollection.__init__r& )r� r5 c C s |� | j| j�S r6 )�_merger� r� )r9 r� r7 r7 r: �merge_with_historyj s z$PendingCollection.merge_with_historyr )r� r5 c C s( || j v r| j �|� n | j�|� d S r6 )r� �remover� r� �r9 r� r7 r7 r: �appendm s zPendingCollection.appendc C s( || j v r| j �|� n | j�|� d S r6 )r� r� r� r� r� r7 r7 r: r� s s zPendingCollection.removeN) r= r> r? rH r� r� ri r� r� r� r7 r7 r7 r: r� X s r� )IrH � __future__r �typingr r r r r r r r r r re � r r r� r Z_typingr r r r r r r r r r r Z path_registryr r� r r Z util.typingr r! r" r# r$ � attributesr% r& r' � collectionsr( r r) Zinstrumentationr* r+ r� r, r{ r- Zenginer. Zext.asyncio.sessionr/ r| r0 r� r1 r2 r@ Z_self_inspectsZInspectionAttrInforI rj r� r7 r7 r7 r: �<module> s� e sqlalchemy/orm/__pycache__/sync.cpython-39.pyc 0000644 00000007540 15125143220 0015321 0 ustar 00 a ��Jh� � @ sp d Z ddlmZ ddlmZ ddlmZ ddlmZ dd� Z d d � Z d d � Z d d� Z dd� Z dd� Zdd� ZdS )zgprivate module containing functions used for copying data between instances based on join conditions. � )� annotations� )�exc)�util)� PassiveFlagc C s | j }|j }|D ]�\} } z(|j| } | j| j j�| |tj�} W n8 tj yx } z t d|| || | � W Y d } ~ n d } ~ 0 0 z(|j| } |j| j j� ||| d � W n8 tj y� } z t d|| || | � W Y d } ~ n d } ~ 0 0 |r| j r| j r| � | �rd|jd|| f< qd S )NFTZ pk_cascaded)�dict�_columntoproperty�manager�key�impl�getr � PASSIVE_OFFr �UnmappedColumnError�_raise_col_to_prop�set� primary_keyZ references� attributes)�source� source_mapper�dest� dest_mapper�synchronize_pairs� uowcommitZflag_cascaded_pks� source_dictZ dest_dict�l�r�prop�value�err� r �H/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/sync.py�populate s0 �( (����r! c C s� |D ]�\}}z|j | }| |j }W n8 tjy\ } z td|||||� W Y d }~n d }~0 0 z|j | }|| |j< W q tjy� } z td|||||� W Y d }~qd }~0 0 qd S )NFT)r r r r r )r r r r r r r r r r r �bulk_populate_inherit_keysA s ( r" c C s� |D ]�\}}|j rJ|�| | j|�tjvrJtd|� d|� dt�| �� d���z|�| | j|d � W q tj y� } z t dd ||||� W Y d }~qd }~0 0 qd S )NzDependency rule on column 'z)' tried to blank-out primary key column 'z' on instance '�'T) r �_get_state_attr_by_columnr �orm_utilZ _none_set�AssertionError� state_strZ_set_state_attr_by_columnr r r )r r r r r r r r r �clearQ s$ ������r( c C s� |D ]�\}}z*|� | �� |�}|j| | j|tjd�}W n8 tjyn } z td||d || � W Y d } ~ n d } ~ 0 0 |||j < ||||j < qd S �N)ZpassiveF) Z _get_committed_attr_by_column�objr$ r r r r r r r ) r r r Z old_prefixr r r Zoldvaluer r r r r �updatec s � � ( r+ c C sp |D ]f\}}z|j | | j|tjd�}W n8 tjy^ } z td||d ||� W Y d }~n d }~0 0 |||j< qd S r) )r$ r r r r r r r )r r Zdict_r r r r r r r r � populate_dictr s � (r, c C s| |D ]r\}}z|j | }W n8 tjyR } z td||d||� W Y d}~n d}~0 0 | �||jtj�}t|j �r dS qdS )zpreturn true if the source object has changes from an old to a new value on the given synchronize pairs FNT) r r r r Zget_attribute_historyr r ZPASSIVE_NO_INITIALIZE�boolZdeleted) r r r r r r r r �historyr r r �source_modified~ s ( � r/ c C s4 | rt �d||f �|�nt �d|||f �|�d S )Nz�Can't execute sync rule for destination column '%s'; mapper '%s' does not map this column. Try using an explicit `foreign_keys` collection which does not include this column (or use a viewonly=True relation).z�Can't execute sync rule for source column '%s'; mapper '%s' does not map this column. Try using an explicit `foreign_keys` collection which does not include destination column '%s' (or use a viewonly=True relation).)r r )Zisdestr Z source_columnr Z dest_columnr r r r r � s ������r N)�__doc__� __future__r � r r r% �baser r! r" r( r+ r, r/ r r r r r �<module> s + sqlalchemy/orm/__pycache__/_orm_constructors.cpython-39.pyc 0000644 00000274264 15125143220 0020142 0 ustar 00 a ��Jhʔ � * @ s� d dl mZ d dlZd dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d d lm Z d d lm Z d d lm Z d d lm Z d dl mZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlm Z d dlm Z d dlm Z d dlm Z d dl m!Z! d dl"m#Z# d d l"m$Z$ d d l"m%Z% d d l"m&Z& d d l m'Z' d d!l m"Z" d d"l(m)Z) d d#l*m+Z+ d d$l,m-Z- d d%l,m.Z. d d&l/m0Z0 d d'l/m1Z1 d d(l2m3Z3 d d)l4m5Z5 d d*l4m6Z6 e �rd d+lm7Z7 d d,lm8Z8 d d-lm9Z9 d d.lm:Z: d d/lm;Z; d d0l<m=Z= d d1lm>Z> d d2lm?Z? d d3lm@Z@ d d4lmAZA d d5lmBZB d d6lmCZC d d7l mDZD d d8l*mEZE d d9l*mFZF d d:l*mGZG d d;l*mHZH d d<l*mIZI d d=l*mJZJ d d>lKmLZL d d?l/mMZM d d@l/mNZN d dAl2mOZO d dBl2mPZP e�QdC�ZRe"jSdDdEdFdG�dHdIdJ�dKdL��ZTd�e-jUe-jUe-jUe-jUe-jUe-jUe-jUe1jVdFe-jUdddFdddMdddddde-jUdddFddFde-jUdN� dOdPdQdRdRdSdTdRdRdUdVdWdRdXdWdYdXdZd[dXdXdWdWd\dSdSd]d^dYdWdYdXd_d`dadb�#dcdd�ZWd�ddedf�dXdZdSdYdadg�dhdi�ZXe"jYf i djdk� dlD ���ddFdFde-jUe-jUe-jUe-jUe-jUe-jUe-jUdFdedddm�dndodXdYdYdpdRdRdSdTdRdRdUdYdYd\dXdqdr�dsdt��ZZe ddFdFddFe-jUe-jUe-jUe-jUe-jUe-jUe-jUdddu�dvdvdXdYdYdwdYdRdRdSdTdRdRdUd\dXd`dxdy�dzd{��Z[e ddFdFddFe-jUe-jUe-jUe-jUe-jUe-jUe-jUdddu�d|dvdXdYdYdwdYdRdRdSdTdRdRdUd\dXd`d}dy�d~d{��Z[e ddFdFddFe-jUe-jUe-jUe-jUe-jUe-jUe-jUdddu�ddvdXdYdYdwdYdRdRdSdTdRdRdUd\dXd`d}dy�d�d{��Z[d�ddFdFddFe-jUe-jUe-jUe-jUe-jUe-jUe-jUdddu�d�dvdXdYdYdwdYdRdRdSdTdRdRdUd\dXd`dxdy�d�d{�Z[d�d�d�dYdYdYdYd�d��d�d��Z\d�ddddddFdddFd�dFe-jUe-jUe-jUe-jUe-jUe-jUe-jUd�dFdedFdedddddFdFddFddddd��#d�d�dWd�d�d�dXd�d�dXdYd�dYdRdRd�dTdRdRdUd�d�dYdYdYd�d�d�d�dYdYdWdYd�d\d�dWd`d�d��'d�d��Z]ddde-jUe-jUe-jUe-jUe-jUe-jUe-jUddd�� d�dWdSdpdRdRd�dTdRdRdUd\dXd�d��d�d��Z^d�d�d`d�d��d�d��Z_d`d`d�d��d�d��Z`d�d�d`d�d��d�d��Zad�d`d�d��d�d��ZbddFde-jUe-jUe-jUe-jUe-jUe-jUe-jUdFdeddd��dndodXdYdpdRdRdSdTdRdRdUdYdYd\dXdqd��d�d��Zce'�d� fe-jUe-jUdeddd��dndRdRdYd\dXdqd��d�d��Zed�d��d�d��Zfe5e e d�f Zge d�d�d�dXdYdYd�dŜd�d���Zhe d�d�d�dXdYdYd�dŜd�d���Zhe d�d�d�dXdYdYd�dŜd�d���Zhd�d�d�dXdYdYd�dŜd�d��Zhd�d�d�d�dYd�dYdYdYdXdYd�dӜ d�dՄZid�d�d�d�dYdYd�dٜd�dۄZjd�d�d�d�dYd�dܜd�dބZkdS )�� )� annotationsN)�Any)�Callable)� Collection)�Iterable)�NoReturn)�Optional)�overload)�Type)� TYPE_CHECKING)�Union� )� mapperlib)�_O)� Composite)�Synonym)�_AttributeOptions)� MappedColumn)�MappedSQLExpression�� AliasOption)�_RelationshipArgumentType)�_RelationshipDeclared)� _RelationshipSecondaryArgument)�RelationshipProperty)�Session��_ORMJoin)� AliasedClass)� AliasedInsp��LoaderCriteriaOption� )�sql)�util��InvalidRequestError)�_no_kw)�_NoArg)�SchemaEventTarget)� _InsertSentinelColumnDefault)� SchemaConst)� FromClause)� Annotated)�Literal)� _EntityType)�_ORMColumnExprArgument)�_CC)�_CompositeAttrType)�PropComparator)�Mapper)�Query)�_LazyLoadArgumentType)�_ORMColCollectionArgument)�_ORMOrderByArgument)�"_RelationshipJoinConditionArgument)�ORMBackrefArgument)� _SessionBind)�_AutoIncrementType)�_ColumnExpressionArgument)�_FromClauseArgument)� _InfoType)�_OnClauseArgument)�_TypeEngineArgument)� ColumnElement)�_ServerDefaultArgument)�_ServerOnUpdateArgument)�Alias)�Subquery�_Tz1.4z�The :class:`.AliasOption` object is not necessary for entities to be matched up to a query that is established via :meth:`.Query.from_statement` and now does nothing.F)Zenable_warningszUnion[Alias, Subquery]r )�alias�returnc C s t | �S )z�Return a :class:`.MapperOption` that will indicate to the :class:`_query.Query` that the main table has been aliased. r )rH � rJ �U/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/_orm_constructors.py�contains_aliasQ s rL �auto) �init�repr�default�default_factory�compare�kw_only�hash�nullable� primary_key�deferred�deferred_group�deferred_raiseload�use_existing_column�name�type_� autoincrement�doc�key�index�unique�info�onupdate�insert_default�server_default�server_onupdate�active_history�quote�system�comment� sort_orderzAOptional[Union[str, _TypeEngineArgument[Any], SchemaEventTarget]]z<Optional[Union[_TypeEngineArgument[Any], SchemaEventTarget]]r) zUnion[_NoArg, bool]z Optional[Any]z Union[_NoArg, Callable[[], _T]]zUnion[_NoArg, bool, None]z<Optional[Union[bool, Literal[SchemaConst.NULL_UNSPECIFIED]]]zOptional[bool]z Optional[str]�boolz"Optional[_TypeEngineArgument[Any]]r< zOptional[_InfoType]z Optional[_ServerDefaultArgument]z!Optional[_ServerOnUpdateArgument]zUnion[_NoArg, int]r zMappedColumn[Any])#� __name_pos� __type_pos�argsrN rO rP rQ rR rS rT rU rV rW rX rY rZ r[ r\ r] r^ r_ r` ra rb rc rd re rf rg rh ri rj rk �kwrI c " O sZ t | |g| �R ||||t|||||||�||||||| || |||| | | | | | | d�|!��S )a�$ declare a new ORM-mapped :class:`_schema.Column` construct for use within :ref:`Declarative Table <orm_declarative_table>` configuration. The :func:`_orm.mapped_column` function provides an ORM-aware and Python-typing-compatible construct which is used with :ref:`declarative <orm_declarative_mapping>` mappings to indicate an attribute that's mapped to a Core :class:`_schema.Column` object. It provides the equivalent feature as mapping an attribute to a :class:`_schema.Column` object directly when using Declarative, specifically when using :ref:`Declarative Table <orm_declarative_table>` configuration. .. versionadded:: 2.0 :func:`_orm.mapped_column` is normally used with explicit typing along with the :class:`_orm.Mapped` annotation type, where it can derive the SQL type and nullability for the column based on what's present within the :class:`_orm.Mapped` annotation. It also may be used without annotations as a drop-in replacement for how :class:`_schema.Column` is used in Declarative mappings in SQLAlchemy 1.x style. For usage examples of :func:`_orm.mapped_column`, see the documentation at :ref:`orm_declarative_table`. .. seealso:: :ref:`orm_declarative_table` - complete documentation :ref:`whatsnew_20_orm_declarative_typing` - migration notes for Declarative mappings using 1.x style mappings :param __name: String name to give to the :class:`_schema.Column`. This is an optional, positional only argument that if present must be the first positional argument passed. If omitted, the attribute name to which the :func:`_orm.mapped_column` is mapped will be used as the SQL column name. :param __type: :class:`_types.TypeEngine` type or instance which will indicate the datatype to be associated with the :class:`_schema.Column`. This is an optional, positional-only argument that if present must immediately follow the ``__name`` parameter if present also, or otherwise be the first positional parameter. If omitted, the ultimate type for the column may be derived either from the annotated type, or if a :class:`_schema.ForeignKey` is present, from the datatype of the referenced column. :param \*args: Additional positional arguments include constructs such as :class:`_schema.ForeignKey`, :class:`_schema.CheckConstraint`, and :class:`_schema.Identity`, which are passed through to the constructed :class:`_schema.Column`. :param nullable: Optional bool, whether the column should be "NULL" or "NOT NULL". If omitted, the nullability is derived from the type annotation based on whether or not ``typing.Optional`` is present. ``nullable`` defaults to ``True`` otherwise for non-primary key columns, and ``False`` for primary key columns. :param primary_key: optional bool, indicates the :class:`_schema.Column` would be part of the table's primary key or not. :param deferred: Optional bool - this keyword argument is consumed by the ORM declarative process, and is not part of the :class:`_schema.Column` itself; instead, it indicates that this column should be "deferred" for loading as though mapped by :func:`_orm.deferred`. .. seealso:: :ref:`orm_queryguide_deferred_declarative` :param deferred_group: Implies :paramref:`_orm.mapped_column.deferred` to ``True``, and set the :paramref:`_orm.deferred.group` parameter. .. seealso:: :ref:`orm_queryguide_deferred_group` :param deferred_raiseload: Implies :paramref:`_orm.mapped_column.deferred` to ``True``, and set the :paramref:`_orm.deferred.raiseload` parameter. .. seealso:: :ref:`orm_queryguide_deferred_raiseload` :param use_existing_column: if True, will attempt to locate the given column name on an inherited superclass (typically single inheriting superclass), and if present, will not produce a new column, mapping to the superclass column as though it were omitted from this class. This is used for mixins that add new columns to an inherited superclass. .. seealso:: :ref:`orm_inheritance_column_conflicts` .. versionadded:: 2.0.0b4 :param default: Passed directly to the :paramref:`_schema.Column.default` parameter if the :paramref:`_orm.mapped_column.insert_default` parameter is not present. Additionally, when used with :ref:`orm_declarative_native_dataclasses`, indicates a default Python value that should be applied to the keyword constructor within the generated ``__init__()`` method. Note that in the case of dataclass generation when :paramref:`_orm.mapped_column.insert_default` is not present, this means the :paramref:`_orm.mapped_column.default` value is used in **two** places, both the ``__init__()`` method as well as the :paramref:`_schema.Column.default` parameter. While this behavior may change in a future release, for the moment this tends to "work out"; a default of ``None`` will mean that the :class:`_schema.Column` gets no default generator, whereas a default that refers to a non-``None`` Python or SQL expression value will be assigned up front on the object when ``__init__()`` is called, which is the same value that the Core :class:`_sql.Insert` construct would use in any case, leading to the same end result. .. note:: When using Core level column defaults that are callables to be interpreted by the underlying :class:`_schema.Column` in conjunction with :ref:`ORM-mapped dataclasses <orm_declarative_native_dataclasses>`, especially those that are :ref:`context-aware default functions <context_default_functions>`, **the** :paramref:`_orm.mapped_column.insert_default` **parameter must be used instead**. This is necessary to disambiguate the callable from being interpreted as a dataclass level default. .. seealso:: :ref:`defaults_default_factory_insert_default` :paramref:`_orm.mapped_column.insert_default` :paramref:`_orm.mapped_column.default_factory` :param insert_default: Passed directly to the :paramref:`_schema.Column.default` parameter; will supersede the value of :paramref:`_orm.mapped_column.default` when present, however :paramref:`_orm.mapped_column.default` will always apply to the constructor default for a dataclasses mapping. .. seealso:: :ref:`defaults_default_factory_insert_default` :paramref:`_orm.mapped_column.default` :paramref:`_orm.mapped_column.default_factory` :param sort_order: An integer that indicates how this mapped column should be sorted compared to the others when the ORM is creating a :class:`_schema.Table`. Among mapped columns that have the same value the default ordering is used, placing first the mapped columns defined in the main class, then the ones in the super classes. Defaults to 0. The sort is ascending. .. versionadded:: 2.0.4 :param active_history=False: When ``True``, indicates that the "previous" value for a scalar attribute should be loaded when replaced, if not already loaded. Normally, history tracking logic for simple non-primary-key scalar values only needs to be aware of the "new" value in order to perform a flush. This flag is available for applications that make use of :func:`.attributes.get_history` or :meth:`.Session.is_modified` which also need to know the "previous" value of the attribute. .. versionadded:: 2.0.10 :param init: Specific to :ref:`orm_declarative_native_dataclasses`, specifies if the mapped attribute should be part of the ``__init__()`` method as generated by the dataclass process. :param repr: Specific to :ref:`orm_declarative_native_dataclasses`, specifies if the mapped attribute should be part of the ``__repr__()`` method as generated by the dataclass process. :param default_factory: Specific to :ref:`orm_declarative_native_dataclasses`, specifies a default-value generation function that will take place as part of the ``__init__()`` method as generated by the dataclass process. .. seealso:: :ref:`defaults_default_factory_insert_default` :paramref:`_orm.mapped_column.default` :paramref:`_orm.mapped_column.insert_default` :param compare: Specific to :ref:`orm_declarative_native_dataclasses`, indicates if this field should be included in comparison operations when generating the ``__eq__()`` and ``__ne__()`` methods for the mapped class. .. versionadded:: 2.0.0b4 :param kw_only: Specific to :ref:`orm_declarative_native_dataclasses`, indicates if this field should be marked as keyword-only when generating the ``__init__()``. :param hash: Specific to :ref:`orm_declarative_native_dataclasses`, controls if this field is included when generating the ``__hash__()`` method for the mapped class. .. versionadded:: 2.0.36 :param \**kw: All remaining keyword arguments are passed through to the constructor for the :class:`_schema.Column`. )r[ r\ r] rd �attribute_optionsr^ r_ r` ra rb rg rU rc rV re rf rZ rh rj ri rW rX rY rk )r r )"rm rn rN rO rP rQ rR rS rT rU rV rW rX rY rZ r[ r\ r] r^ r_ r` ra rb rc rd re rf rg rh ri rj rk ro rp rJ rJ rK � mapped_columna sH {���� �rr T)rP �omit_from_statements)r[ r\ rP rs rI c C s" t | |dur|nt� |dddd�S )a Provides a surrogate :func:`_orm.mapped_column` that generates a so-called :term:`sentinel` column, allowing efficient bulk inserts with deterministic RETURNING sorting for tables that don't otherwise have qualifying primary key configurations. Use of :func:`_orm.orm_insert_sentinel` is analogous to the use of the :func:`_schema.insert_sentinel` construct within a Core :class:`_schema.Table` construct. Guidelines for adding this construct to a Declarative mapped class are the same as that of the :func:`_schema.insert_sentinel` construct; the database table itself also needs to have a column with this name present. For background on how this object is used, see the section :ref:`engine_insertmanyvalues_sentinel_columns` as part of the section :ref:`engine_insertmanyvalues`. .. seealso:: :func:`_schema.insert_sentinel` :ref:`engine_insertmanyvalues` :ref:`engine_insertmanyvalues_sentinel_columns` .. versionadded:: 2.0.10 NT)r[ rP Z_omit_from_statementsZinsert_sentinelrZ rU )rr r* )r[ r\ rP rs rJ rJ rK �orm_insert_sentinel} s &�rt c C s i | ]}|d d|� d�f�qS )z2.0z$The :paramref:`_orm.column_property.z�` parameter is deprecated for :func:`_orm.column_property`. This parameter applies to a writeable-attribute in a Declarative Dataclasses configuration only, and :func:`_orm.column_property` is treated as a read-only attribute in this context.rJ )�.0�argrJ rJ rK � <dictcomp>� s � �rw )rN rS rP rQ )�grouprW � raiseload�comparator_factoryrN rO rP rQ rR rS rT rg �expire_on_flushrb r^ z_ORMColumnExprArgument[_T]z_ORMColumnExprArgument[Any]z"Optional[Type[PropComparator[_T]]]zMappedSQLExpression[_T])�column�additional_columnsrx rW ry rz rN rO rP rQ rR rS rT rg r{ rb r^ rI c G sF t | g|�R t|tju r dn||||| | | �||||| | ||dd� �S )a� Provide a column-level property for use with a mapping. With Declarative mappings, :func:`_orm.column_property` is used to map read-only SQL expressions to a mapped class. When using Imperative mappings, :func:`_orm.column_property` also takes on the role of mapping table columns with additional features. When using fully Declarative mappings, the :func:`_orm.mapped_column` construct should be used for this purpose. With Declarative Dataclass mappings, :func:`_orm.column_property` is considered to be **read only**, and will not be included in the Dataclass ``__init__()`` constructor. The :func:`_orm.column_property` function returns an instance of :class:`.ColumnProperty`. .. seealso:: :ref:`mapper_column_property_sql_expressions` - general use of :func:`_orm.column_property` to map SQL expressions :ref:`orm_imperative_table_column_options` - usage of :func:`_orm.column_property` with Imperative Table mappings to apply additional options to a plain :class:`_schema.Column` object :param \*cols: list of Column objects to be mapped. :param active_history=False: Used only for Imperative Table mappings, or legacy-style Declarative mappings (i.e. which have not been upgraded to :func:`_orm.mapped_column`), for column-based attributes that are expected to be writeable; use :func:`_orm.mapped_column` with :paramref:`_orm.mapped_column.active_history` for Declarative mappings. See that parameter for functional details. :param comparator_factory: a class which extends :class:`.ColumnProperty.Comparator` which provides custom SQL clause generation for comparison operations. :param group: a group name for this property when marked as deferred. :param deferred: when True, the column property is "deferred", meaning that it does not load immediately, and is instead loaded when the attribute is first accessed on an instance. See also :func:`~sqlalchemy.orm.deferred`. :param doc: optional string that will be applied as the doc on the class-bound descriptor. :param expire_on_flush=True: Disable expiry on flush. A column_property() which refers to a SQL expression (and not a single table-bound column) is considered to be a "read only" property; populating it has no effect on the state of data, and it can only return database state. For this reason a column_property()'s value is expired whenever the parent object is involved in a flush, that is, has any kind of "dirty" state within a flush. Setting this parameter to ``False`` will have the effect of leaving any existing value present after the flush proceeds. Note that the :class:`.Session` with default expiration settings still expires all attributes after a :meth:`.Session.commit` call, however. :param info: Optional data dictionary which will be populated into the :attr:`.MapperProperty.info` attribute of this object. :param raiseload: if True, indicates the column should raise an error when undeferred, rather than loading the value. This can be altered at query time by using the :func:`.deferred` option with raiseload=False. .. versionadded:: 1.4 .. seealso:: :ref:`orm_queryguide_deferred_raiseload` :param init: Specific to :ref:`orm_declarative_native_dataclasses`, specifies if the mapped attribute should be part of the ``__init__()`` method as generated by the dataclass process. :param repr: Specific to :ref:`orm_declarative_native_dataclasses`, specifies if the mapped attribute should be part of the ``__repr__()`` method as generated by the dataclass process. :param default_factory: Specific to :ref:`orm_declarative_native_dataclasses`, specifies a default-value generation function that will take place as part of the ``__init__()`` method as generated by the dataclass process. .. seealso:: :ref:`defaults_default_factory_insert_default` :paramref:`_orm.mapped_column.default` :paramref:`_orm.mapped_column.insert_default` :param compare: Specific to :ref:`orm_declarative_native_dataclasses`, indicates if this field should be included in comparison operations when generating the ``__eq__()`` and ``__ne__()`` methods for the mapped class. .. versionadded:: 2.0.0b4 :param kw_only: Specific to :ref:`orm_declarative_native_dataclasses`, indicates if this field should be marked as keyword-only when generating the ``__init__()``. :param hash: Specific to :ref:`orm_declarative_native_dataclasses`, controls if this field is included when generating the ``__hash__()`` method for the mapped class. .. versionadded:: 2.0.36 FT) rq rx rW ry rz rg r{ rb r^ � _assume_readonly_dc_attributes)r r r( �NO_ARG)r| rx rW ry rz rN rO rP rQ rR rS rT rg r{ rb r^ r} rJ rJ rK �column_property� s2 ��� �r� )rx rW ry rz rg rN rO rP rQ rR rS rT rb r^ z_CompositeAttrType[Any]z(Optional[Type[Composite.Comparator[_T]]]zComposite[Any])�_class_or_attr�attrsrx rW ry rz rg rN rO rP rQ rR rS rT rb r^ �__kwrI c O s d S �NrJ �r� rx rW ry rz rg rN rO rP rQ rR rS rT rb r^ r� r� rJ rJ rK � compositea s r� z Type[_CC]zComposite[_CC]c O s d S r� rJ r� rJ rJ rK r� w s zCallable[..., _CC]c O s d S r� rJ r� rJ rJ rK r� � s zCUnion[None, Type[_CC], Callable[..., _CC], _CompositeAttrType[Any]]c O s> |r t � �t| g|�R t|||| | | | �|||||| |d��S )a4 Return a composite column-based property for use with a Mapper. See the mapping documentation section :ref:`mapper_composite` for a full usage example. The :class:`.MapperProperty` returned by :func:`.composite` is the :class:`.Composite`. :param class\_: The "composite type" class, or any classmethod or callable which will produce a new instance of the composite object given the column values in order. :param \*attrs: List of elements to be mapped, which may include: * :class:`_schema.Column` objects * :func:`_orm.mapped_column` constructs * string names of other attributes on the mapped class, which may be any other SQL or object-mapped attribute. This can for example allow a composite that refers to a many-to-one relationship :param active_history=False: When ``True``, indicates that the "previous" value for a scalar attribute should be loaded when replaced, if not already loaded. See the same flag on :func:`.column_property`. :param group: A group name for this property when marked as deferred. :param deferred: When True, the column property is "deferred", meaning that it does not load immediately, and is instead loaded when the attribute is first accessed on an instance. See also :func:`~sqlalchemy.orm.deferred`. :param comparator_factory: a class which extends :class:`.Composite.Comparator` which provides custom SQL clause generation for comparison operations. :param doc: optional string that will be applied as the doc on the class-bound descriptor. :param info: Optional data dictionary which will be populated into the :attr:`.MapperProperty.info` attribute of this object. :param init: Specific to :ref:`orm_declarative_native_dataclasses`, specifies if the mapped attribute should be part of the ``__init__()`` method as generated by the dataclass process. :param repr: Specific to :ref:`orm_declarative_native_dataclasses`, specifies if the mapped attribute should be part of the ``__repr__()`` method as generated by the dataclass process. :param default_factory: Specific to :ref:`orm_declarative_native_dataclasses`, specifies a default-value generation function that will take place as part of the ``__init__()`` method as generated by the dataclass process. :param compare: Specific to :ref:`orm_declarative_native_dataclasses`, indicates if this field should be included in comparison operations when generating the ``__eq__()`` and ``__ne__()`` methods for the mapped class. .. versionadded:: 2.0.0b4 :param kw_only: Specific to :ref:`orm_declarative_native_dataclasses`, indicates if this field should be marked as keyword-only when generating the ``__init__()``. :param hash: Specific to :ref:`orm_declarative_native_dataclasses`, controls if this field is included when generating the ``__hash__()`` method for the mapped class. .. versionadded:: 2.0.36 )rq rx rW ry rz rg rb r^ )r' r r r� rJ rJ rK r� � s$ b����z_EntityType[Any]zXUnion[_ColumnExpressionArgument[bool], Callable[[Any], _ColumnExpressionArgument[bool]]]r! )�entity_or_base�where_criteria� loader_only�include_aliases�propagate_to_loaders�track_closure_variablesrI c C s t | |||||�S )a� Add additional WHERE criteria to the load for all occurrences of a particular entity. .. versionadded:: 1.4 The :func:`_orm.with_loader_criteria` option is intended to add limiting criteria to a particular kind of entity in a query, **globally**, meaning it will apply to the entity as it appears in the SELECT query as well as within any subqueries, join conditions, and relationship loads, including both eager and lazy loaders, without the need for it to be specified in any particular part of the query. The rendering logic uses the same system used by single table inheritance to ensure a certain discriminator is applied to a table. E.g., using :term:`2.0-style` queries, we can limit the way the ``User.addresses`` collection is loaded, regardless of the kind of loading used:: from sqlalchemy.orm import with_loader_criteria stmt = select(User).options( selectinload(User.addresses), with_loader_criteria(Address, Address.email_address != "foo"), ) Above, the "selectinload" for ``User.addresses`` will apply the given filtering criteria to the WHERE clause. Another example, where the filtering will be applied to the ON clause of the join, in this example using :term:`1.x style` queries:: q = ( session.query(User) .outerjoin(User.addresses) .options(with_loader_criteria(Address, Address.email_address != "foo")) ) The primary purpose of :func:`_orm.with_loader_criteria` is to use it in the :meth:`_orm.SessionEvents.do_orm_execute` event handler to ensure that all occurrences of a particular entity are filtered in a certain way, such as filtering for access control roles. It also can be used to apply criteria to relationship loads. In the example below, we can apply a certain set of rules to all queries emitted by a particular :class:`_orm.Session`:: session = Session(bind=engine) @event.listens_for("do_orm_execute", session) def _add_filtering_criteria(execute_state): if ( execute_state.is_select and not execute_state.is_column_load and not execute_state.is_relationship_load ): execute_state.statement = execute_state.statement.options( with_loader_criteria( SecurityRole, lambda cls: cls.role.in_(["some_role"]), include_aliases=True, ) ) In the above example, the :meth:`_orm.SessionEvents.do_orm_execute` event will intercept all queries emitted using the :class:`_orm.Session`. For those queries which are SELECT statements and are not attribute or relationship loads a custom :func:`_orm.with_loader_criteria` option is added to the query. The :func:`_orm.with_loader_criteria` option will be used in the given statement and will also be automatically propagated to all relationship loads that descend from this query. The criteria argument given is a ``lambda`` that accepts a ``cls`` argument. The given class will expand to include all mapped subclass and need not itself be a mapped class. .. tip:: When using :func:`_orm.with_loader_criteria` option in conjunction with the :func:`_orm.contains_eager` loader option, it's important to note that :func:`_orm.with_loader_criteria` only affects the part of the query that determines what SQL is rendered in terms of the WHERE and FROM clauses. The :func:`_orm.contains_eager` option does not affect the rendering of the SELECT statement outside of the columns clause, so does not have any interaction with the :func:`_orm.with_loader_criteria` option. However, the way things "work" is that :func:`_orm.contains_eager` is meant to be used with a query that is already selecting from the additional entities in some way, where :func:`_orm.with_loader_criteria` can apply it's additional criteria. In the example below, assuming a mapping relationship as ``A -> A.bs -> B``, the given :func:`_orm.with_loader_criteria` option will affect the way in which the JOIN is rendered:: stmt = ( select(A) .join(A.bs) .options(contains_eager(A.bs), with_loader_criteria(B, B.flag == 1)) ) Above, the given :func:`_orm.with_loader_criteria` option will affect the ON clause of the JOIN that is specified by ``.join(A.bs)``, so is applied as expected. The :func:`_orm.contains_eager` option has the effect that columns from ``B`` are added to the columns clause: .. sourcecode:: sql SELECT b.id, b.a_id, b.data, b.flag, a.id AS id_1, a.data AS data_1 FROM a JOIN b ON a.id = b.a_id AND b.flag = :flag_1 The use of the :func:`_orm.contains_eager` option within the above statement has no effect on the behavior of the :func:`_orm.with_loader_criteria` option. If the :func:`_orm.contains_eager` option were omitted, the SQL would be the same as regards the FROM and WHERE clauses, where :func:`_orm.with_loader_criteria` continues to add its criteria to the ON clause of the JOIN. The addition of :func:`_orm.contains_eager` only affects the columns clause, in that additional columns against ``b`` are added which are then consumed by the ORM to produce ``B`` instances. .. warning:: The use of a lambda inside of the call to :func:`_orm.with_loader_criteria` is only invoked **once per unique class**. Custom functions should not be invoked within this lambda. See :ref:`engine_lambda_caching` for an overview of the "lambda SQL" feature, which is for advanced use only. :param entity_or_base: a mapped class, or a class that is a super class of a particular set of mapped classes, to which the rule will apply. :param where_criteria: a Core SQL expression that applies limiting criteria. This may also be a "lambda:" or Python function that accepts a target class as an argument, when the given class is a base with many different mapped subclasses. .. note:: To support pickling, use a module-level Python function to produce the SQL expression instead of a lambda or a fixed SQL expression, which tend to not be picklable. :param include_aliases: if True, apply the rule to :func:`_orm.aliased` constructs as well. :param propagate_to_loaders: defaults to True, apply to relationship loaders such as lazy loaders. This indicates that the option object itself including SQL expression is carried along with each loaded instance. Set to ``False`` to prevent the object from being assigned to individual instances. .. seealso:: :ref:`examples_session_orm_events` - includes examples of using :func:`_orm.with_loader_criteria`. :ref:`do_orm_execute_global_criteria` - basic example on how to combine :func:`_orm.with_loader_criteria` with the :meth:`_orm.SessionEvents.do_orm_execute` event. :param track_closure_variables: when False, closure variables inside of a lambda expression will not be used as part of any cache key. This allows more complex expressions to be used inside of a lambda expression but requires that the lambda ensures it returns the identical SQL every time given a particular class. .. versionadded:: 1.4.0b2 r )r� r� r� r� r� r� rJ rJ rK �with_loader_criteria s >�r� zsave-update, merge�select)#�uselist�collection_class� primaryjoin� secondaryjoin�back_populates�order_by�backref�overlaps� post_update�cascade�viewonlyrN rO rP rQ rR rS rT �lazy�passive_deletes�passive_updatesrg �enable_typechecks� foreign_keys� remote_side� join_depthrz � single_parent� innerjoin�distinct_target_key�load_on_pending� query_classrb � omit_join� sync_backrefz(Optional[_RelationshipArgumentType[Any]]z(Optional[_RelationshipSecondaryArgument]zEOptional[Union[Type[Collection[Any]], Callable[[], Collection[Any]]]]z,Optional[_RelationshipJoinConditionArgument]r8 z Optional[ORMBackrefArgument]�strzUnion[_NoArg, _T]r6 zUnion[Literal['all'], bool]z#Optional[_ORMColCollectionArgument]z Optional[int]z4Optional[Type[RelationshipProperty.Comparator[Any]]]zOptional[Type[Query[Any]]]zLiteral[None, False]z_RelationshipDeclared[Any])'�argument� secondaryr� r� r� r� r� r� r� r� r� r� r� rN rO rP rQ rR rS rT r� r� r� rg r� r� r� r� rz r� r� r� r� r� rb r� r� rp rI c # & ! K s^ t | f||||||||| | | | t| ||||||�||||||||| | | | | |!|"|#|$d� |%��S )a�� Provide a relationship between two mapped classes. This corresponds to a parent-child or associative table relationship. The constructed class is an instance of :class:`.Relationship`. .. seealso:: :ref:`tutorial_orm_related_objects` - tutorial introduction to :func:`_orm.relationship` in the :ref:`unified_tutorial` :ref:`relationship_config_toplevel` - narrative documentation :param argument: This parameter refers to the class that is to be related. It accepts several forms, including a direct reference to the target class itself, the :class:`_orm.Mapper` instance for the target class, a Python callable / lambda that will return a reference to the class or :class:`_orm.Mapper` when called, and finally a string name for the class, which will be resolved from the :class:`_orm.registry` in use in order to locate the class, e.g.:: class SomeClass(Base): # ... related = relationship("RelatedClass") The :paramref:`_orm.relationship.argument` may also be omitted from the :func:`_orm.relationship` construct entirely, and instead placed inside a :class:`_orm.Mapped` annotation on the left side, which should include a Python collection type if the relationship is expected to be a collection, such as:: class SomeClass(Base): # ... related_items: Mapped[List["RelatedItem"]] = relationship() Or for a many-to-one or one-to-one relationship:: class SomeClass(Base): # ... related_item: Mapped["RelatedItem"] = relationship() .. seealso:: :ref:`orm_declarative_properties` - further detail on relationship configuration when using Declarative. :param secondary: For a many-to-many relationship, specifies the intermediary table, and is typically an instance of :class:`_schema.Table`. In less common circumstances, the argument may also be specified as an :class:`_expression.Alias` construct, or even a :class:`_expression.Join` construct. :paramref:`_orm.relationship.secondary` may also be passed as a callable function which is evaluated at mapper initialization time. When using Declarative, it may also be a string argument noting the name of a :class:`_schema.Table` that is present in the :class:`_schema.MetaData` collection associated with the parent-mapped :class:`_schema.Table`. .. warning:: When passed as a Python-evaluable string, the argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on declarative evaluation of :func:`_orm.relationship` arguments. The :paramref:`_orm.relationship.secondary` keyword argument is typically applied in the case where the intermediary :class:`_schema.Table` is not otherwise expressed in any direct class mapping. If the "secondary" table is also explicitly mapped elsewhere (e.g. as in :ref:`association_pattern`), one should consider applying the :paramref:`_orm.relationship.viewonly` flag so that this :func:`_orm.relationship` is not used for persistence operations which may conflict with those of the association object pattern. .. seealso:: :ref:`relationships_many_to_many` - Reference example of "many to many". :ref:`self_referential_many_to_many` - Specifics on using many-to-many in a self-referential case. :ref:`declarative_many_to_many` - Additional options when using Declarative. :ref:`association_pattern` - an alternative to :paramref:`_orm.relationship.secondary` when composing association table relationships, allowing additional attributes to be specified on the association table. :ref:`composite_secondary_join` - a lesser-used pattern which in some cases can enable complex :func:`_orm.relationship` SQL conditions to be used. :param active_history=False: When ``True``, indicates that the "previous" value for a many-to-one reference should be loaded when replaced, if not already loaded. Normally, history tracking logic for simple many-to-ones only needs to be aware of the "new" value in order to perform a flush. This flag is available for applications that make use of :func:`.attributes.get_history` which also need to know the "previous" value of the attribute. :param backref: A reference to a string relationship name, or a :func:`_orm.backref` construct, which will be used to automatically generate a new :func:`_orm.relationship` on the related class, which then refers to this one using a bi-directional :paramref:`_orm.relationship.back_populates` configuration. In modern Python, explicit use of :func:`_orm.relationship` with :paramref:`_orm.relationship.back_populates` should be preferred, as it is more robust in terms of mapper configuration as well as more conceptually straightforward. It also integrates with new :pep:`484` typing features introduced in SQLAlchemy 2.0 which is not possible with dynamically generated attributes. .. seealso:: :ref:`relationships_backref` - notes on using :paramref:`_orm.relationship.backref` :ref:`tutorial_orm_related_objects` - in the :ref:`unified_tutorial`, presents an overview of bi-directional relationship configuration and behaviors using :paramref:`_orm.relationship.back_populates` :func:`.backref` - allows control over :func:`_orm.relationship` configuration when using :paramref:`_orm.relationship.backref`. :param back_populates: Indicates the name of a :func:`_orm.relationship` on the related class that will be synchronized with this one. It is usually expected that the :func:`_orm.relationship` on the related class also refer to this one. This allows objects on both sides of each :func:`_orm.relationship` to synchronize in-Python state changes and also provides directives to the :term:`unit of work` flush process how changes along these relationships should be persisted. .. seealso:: :ref:`tutorial_orm_related_objects` - in the :ref:`unified_tutorial`, presents an overview of bi-directional relationship configuration and behaviors. :ref:`relationship_patterns` - includes many examples of :paramref:`_orm.relationship.back_populates`. :paramref:`_orm.relationship.backref` - legacy form which allows more succinct configuration, but does not support explicit typing :param overlaps: A string name or comma-delimited set of names of other relationships on either this mapper, a descendant mapper, or a target mapper with which this relationship may write to the same foreign keys upon persistence. The only effect this has is to eliminate the warning that this relationship will conflict with another upon persistence. This is used for such relationships that are truly capable of conflicting with each other on write, but the application will ensure that no such conflicts occur. .. versionadded:: 1.4 .. seealso:: :ref:`error_qzyx` - usage example :param cascade: A comma-separated list of cascade rules which determines how Session operations should be "cascaded" from parent to child. This defaults to ``False``, which means the default cascade should be used - this default cascade is ``"save-update, merge"``. The available cascades are ``save-update``, ``merge``, ``expunge``, ``delete``, ``delete-orphan``, and ``refresh-expire``. An additional option, ``all`` indicates shorthand for ``"save-update, merge, refresh-expire, expunge, delete"``, and is often used as in ``"all, delete-orphan"`` to indicate that related objects should follow along with the parent object in all cases, and be deleted when de-associated. .. seealso:: :ref:`unitofwork_cascades` - Full detail on each of the available cascade options. :param cascade_backrefs=False: Legacy; this flag is always False. .. versionchanged:: 2.0 "cascade_backrefs" functionality has been removed. :param collection_class: A class or callable that returns a new list-holding object. will be used in place of a plain list for storing elements. .. seealso:: :ref:`custom_collections` - Introductory documentation and examples. :param comparator_factory: A class which extends :class:`.Relationship.Comparator` which provides custom SQL clause generation for comparison operations. .. seealso:: :class:`.PropComparator` - some detail on redefining comparators at this level. :ref:`custom_comparators` - Brief intro to this feature. :param distinct_target_key=None: Indicate if a "subquery" eager load should apply the DISTINCT keyword to the innermost SELECT statement. When left as ``None``, the DISTINCT keyword will be applied in those cases when the target columns do not comprise the full primary key of the target table. When set to ``True``, the DISTINCT keyword is applied to the innermost SELECT unconditionally. It may be desirable to set this flag to False when the DISTINCT is reducing performance of the innermost subquery beyond that of what duplicate innermost rows may be causing. .. seealso:: :ref:`loading_toplevel` - includes an introduction to subquery eager loading. :param doc: Docstring which will be applied to the resulting descriptor. :param foreign_keys: A list of columns which are to be used as "foreign key" columns, or columns which refer to the value in a remote column, within the context of this :func:`_orm.relationship` object's :paramref:`_orm.relationship.primaryjoin` condition. That is, if the :paramref:`_orm.relationship.primaryjoin` condition of this :func:`_orm.relationship` is ``a.id == b.a_id``, and the values in ``b.a_id`` are required to be present in ``a.id``, then the "foreign key" column of this :func:`_orm.relationship` is ``b.a_id``. In normal cases, the :paramref:`_orm.relationship.foreign_keys` parameter is **not required.** :func:`_orm.relationship` will automatically determine which columns in the :paramref:`_orm.relationship.primaryjoin` condition are to be considered "foreign key" columns based on those :class:`_schema.Column` objects that specify :class:`_schema.ForeignKey`, or are otherwise listed as referencing columns in a :class:`_schema.ForeignKeyConstraint` construct. :paramref:`_orm.relationship.foreign_keys` is only needed when: 1. There is more than one way to construct a join from the local table to the remote table, as there are multiple foreign key references present. Setting ``foreign_keys`` will limit the :func:`_orm.relationship` to consider just those columns specified here as "foreign". 2. The :class:`_schema.Table` being mapped does not actually have :class:`_schema.ForeignKey` or :class:`_schema.ForeignKeyConstraint` constructs present, often because the table was reflected from a database that does not support foreign key reflection (MySQL MyISAM). 3. The :paramref:`_orm.relationship.primaryjoin` argument is used to construct a non-standard join condition, which makes use of columns or expressions that do not normally refer to their "parent" column, such as a join condition expressed by a complex comparison using a SQL function. The :func:`_orm.relationship` construct will raise informative error messages that suggest the use of the :paramref:`_orm.relationship.foreign_keys` parameter when presented with an ambiguous condition. In typical cases, if :func:`_orm.relationship` doesn't raise any exceptions, the :paramref:`_orm.relationship.foreign_keys` parameter is usually not needed. :paramref:`_orm.relationship.foreign_keys` may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. .. warning:: When passed as a Python-evaluable string, the argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on declarative evaluation of :func:`_orm.relationship` arguments. .. seealso:: :ref:`relationship_foreign_keys` :ref:`relationship_custom_foreign` :func:`.foreign` - allows direct annotation of the "foreign" columns within a :paramref:`_orm.relationship.primaryjoin` condition. :param info: Optional data dictionary which will be populated into the :attr:`.MapperProperty.info` attribute of this object. :param innerjoin=False: When ``True``, joined eager loads will use an inner join to join against related tables instead of an outer join. The purpose of this option is generally one of performance, as inner joins generally perform better than outer joins. This flag can be set to ``True`` when the relationship references an object via many-to-one using local foreign keys that are not nullable, or when the reference is one-to-one or a collection that is guaranteed to have one or at least one entry. The option supports the same "nested" and "unnested" options as that of :paramref:`_orm.joinedload.innerjoin`. See that flag for details on nested / unnested behaviors. .. seealso:: :paramref:`_orm.joinedload.innerjoin` - the option as specified by loader option, including detail on nesting behavior. :ref:`what_kind_of_loading` - Discussion of some details of various loader options. :param join_depth: When non-``None``, an integer value indicating how many levels deep "eager" loaders should join on a self-referring or cyclical relationship. The number counts how many times the same Mapper shall be present in the loading condition along a particular join branch. When left at its default of ``None``, eager loaders will stop chaining when they encounter a the same target mapper which is already higher up in the chain. This option applies both to joined- and subquery- eager loaders. .. seealso:: :ref:`self_referential_eager_loading` - Introductory documentation and examples. :param lazy='select': specifies How the related items should be loaded. Default value is ``select``. Values include: * ``select`` - items should be loaded lazily when the property is first accessed, using a separate SELECT statement, or identity map fetch for simple many-to-one references. * ``immediate`` - items should be loaded as the parents are loaded, using a separate SELECT statement, or identity map fetch for simple many-to-one references. * ``joined`` - items should be loaded "eagerly" in the same query as that of the parent, using a JOIN or LEFT OUTER JOIN. Whether the join is "outer" or not is determined by the :paramref:`_orm.relationship.innerjoin` parameter. * ``subquery`` - items should be loaded "eagerly" as the parents are loaded, using one additional SQL statement, which issues a JOIN to a subquery of the original statement, for each collection requested. * ``selectin`` - items should be loaded "eagerly" as the parents are loaded, using one or more additional SQL statements, which issues a JOIN to the immediate parent object, specifying primary key identifiers using an IN clause. * ``noload`` - no loading should occur at any time. The related collection will remain empty. The ``noload`` strategy is not recommended for general use. For a general use "never load" approach, see :ref:`write_only_relationship` * ``raise`` - lazy loading is disallowed; accessing the attribute, if its value were not already loaded via eager loading, will raise an :exc:`~sqlalchemy.exc.InvalidRequestError`. This strategy can be used when objects are to be detached from their attached :class:`.Session` after they are loaded. * ``raise_on_sql`` - lazy loading that emits SQL is disallowed; accessing the attribute, if its value were not already loaded via eager loading, will raise an :exc:`~sqlalchemy.exc.InvalidRequestError`, **if the lazy load needs to emit SQL**. If the lazy load can pull the related value from the identity map or determine that it should be None, the value is loaded. This strategy can be used when objects will remain associated with the attached :class:`.Session`, however additional SELECT statements should be blocked. * ``write_only`` - the attribute will be configured with a special "virtual collection" that may receive :meth:`_orm.WriteOnlyCollection.add` and :meth:`_orm.WriteOnlyCollection.remove` commands to add or remove individual objects, but will not under any circumstances load or iterate the full set of objects from the database directly. Instead, methods such as :meth:`_orm.WriteOnlyCollection.select`, :meth:`_orm.WriteOnlyCollection.insert`, :meth:`_orm.WriteOnlyCollection.update` and :meth:`_orm.WriteOnlyCollection.delete` are provided which generate SQL constructs that may be used to load and modify rows in bulk. Used for large collections that are never appropriate to load at once into memory. The ``write_only`` loader style is configured automatically when the :class:`_orm.WriteOnlyMapped` annotation is provided on the left hand side within a Declarative mapping. See the section :ref:`write_only_relationship` for examples. .. versionadded:: 2.0 .. seealso:: :ref:`write_only_relationship` - in the :ref:`queryguide_toplevel` * ``dynamic`` - the attribute will return a pre-configured :class:`_query.Query` object for all read operations, onto which further filtering operations can be applied before iterating the results. The ``dynamic`` loader style is configured automatically when the :class:`_orm.DynamicMapped` annotation is provided on the left hand side within a Declarative mapping. See the section :ref:`dynamic_relationship` for examples. .. legacy:: The "dynamic" lazy loader strategy is the legacy form of what is now the "write_only" strategy described in the section :ref:`write_only_relationship`. .. seealso:: :ref:`dynamic_relationship` - in the :ref:`queryguide_toplevel` :ref:`write_only_relationship` - more generally useful approach for large collections that should not fully load into memory * True - a synonym for 'select' * False - a synonym for 'joined' * None - a synonym for 'noload' .. seealso:: :ref:`orm_queryguide_relationship_loaders` - Full documentation on relationship loader configuration in the :ref:`queryguide_toplevel`. :param load_on_pending=False: Indicates loading behavior for transient or pending parent objects. When set to ``True``, causes the lazy-loader to issue a query for a parent object that is not persistent, meaning it has never been flushed. This may take effect for a pending object when autoflush is disabled, or for a transient object that has been "attached" to a :class:`.Session` but is not part of its pending collection. The :paramref:`_orm.relationship.load_on_pending` flag does not improve behavior when the ORM is used normally - object references should be constructed at the object level, not at the foreign key level, so that they are present in an ordinary way before a flush proceeds. This flag is not not intended for general use. .. seealso:: :meth:`.Session.enable_relationship_loading` - this method establishes "load on pending" behavior for the whole object, and also allows loading on objects that remain transient or detached. :param order_by: Indicates the ordering that should be applied when loading these items. :paramref:`_orm.relationship.order_by` is expected to refer to one of the :class:`_schema.Column` objects to which the target class is mapped, or the attribute itself bound to the target class which refers to the column. :paramref:`_orm.relationship.order_by` may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. .. warning:: When passed as a Python-evaluable string, the argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on declarative evaluation of :func:`_orm.relationship` arguments. :param passive_deletes=False: Indicates loading behavior during delete operations. A value of True indicates that unloaded child items should not be loaded during a delete operation on the parent. Normally, when a parent item is deleted, all child items are loaded so that they can either be marked as deleted, or have their foreign key to the parent set to NULL. Marking this flag as True usually implies an ON DELETE <CASCADE|SET NULL> rule is in place which will handle updating/deleting child rows on the database side. Additionally, setting the flag to the string value 'all' will disable the "nulling out" of the child foreign keys, when the parent object is deleted and there is no delete or delete-orphan cascade enabled. This is typically used when a triggering or error raise scenario is in place on the database side. Note that the foreign key attributes on in-session child objects will not be changed after a flush occurs so this is a very special use-case setting. Additionally, the "nulling out" will still occur if the child object is de-associated with the parent. .. seealso:: :ref:`passive_deletes` - Introductory documentation and examples. :param passive_updates=True: Indicates the persistence behavior to take when a referenced primary key value changes in place, indicating that the referencing foreign key columns will also need their value changed. When True, it is assumed that ``ON UPDATE CASCADE`` is configured on the foreign key in the database, and that the database will handle propagation of an UPDATE from a source column to dependent rows. When False, the SQLAlchemy :func:`_orm.relationship` construct will attempt to emit its own UPDATE statements to modify related targets. However note that SQLAlchemy **cannot** emit an UPDATE for more than one level of cascade. Also, setting this flag to False is not compatible in the case where the database is in fact enforcing referential integrity, unless those constraints are explicitly "deferred", if the target backend supports it. It is highly advised that an application which is employing mutable primary keys keeps ``passive_updates`` set to True, and instead uses the referential integrity features of the database itself in order to handle the change efficiently and fully. .. seealso:: :ref:`passive_updates` - Introductory documentation and examples. :paramref:`.mapper.passive_updates` - a similar flag which takes effect for joined-table inheritance mappings. :param post_update: This indicates that the relationship should be handled by a second UPDATE statement after an INSERT or before a DELETE. This flag is used to handle saving bi-directional dependencies between two individual rows (i.e. each row references the other), where it would otherwise be impossible to INSERT or DELETE both rows fully since one row exists before the other. Use this flag when a particular mapping arrangement will incur two rows that are dependent on each other, such as a table that has a one-to-many relationship to a set of child rows, and also has a column that references a single child row within that list (i.e. both tables contain a foreign key to each other). If a flush operation returns an error that a "cyclical dependency" was detected, this is a cue that you might want to use :paramref:`_orm.relationship.post_update` to "break" the cycle. .. seealso:: :ref:`post_update` - Introductory documentation and examples. :param primaryjoin: A SQL expression that will be used as the primary join of the child object against the parent object, or in a many-to-many relationship the join of the parent object to the association table. By default, this value is computed based on the foreign key relationships of the parent and child tables (or association table). :paramref:`_orm.relationship.primaryjoin` may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. .. warning:: When passed as a Python-evaluable string, the argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on declarative evaluation of :func:`_orm.relationship` arguments. .. seealso:: :ref:`relationship_primaryjoin` :param remote_side: Used for self-referential relationships, indicates the column or list of columns that form the "remote side" of the relationship. :paramref:`_orm.relationship.remote_side` may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. .. warning:: When passed as a Python-evaluable string, the argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on declarative evaluation of :func:`_orm.relationship` arguments. .. seealso:: :ref:`self_referential` - in-depth explanation of how :paramref:`_orm.relationship.remote_side` is used to configure self-referential relationships. :func:`.remote` - an annotation function that accomplishes the same purpose as :paramref:`_orm.relationship.remote_side`, typically when a custom :paramref:`_orm.relationship.primaryjoin` condition is used. :param query_class: A :class:`_query.Query` subclass that will be used internally by the ``AppenderQuery`` returned by a "dynamic" relationship, that is, a relationship that specifies ``lazy="dynamic"`` or was otherwise constructed using the :func:`_orm.dynamic_loader` function. .. seealso:: :ref:`dynamic_relationship` - Introduction to "dynamic" relationship loaders. :param secondaryjoin: A SQL expression that will be used as the join of an association table to the child object. By default, this value is computed based on the foreign key relationships of the association and child tables. :paramref:`_orm.relationship.secondaryjoin` may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. .. warning:: When passed as a Python-evaluable string, the argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on declarative evaluation of :func:`_orm.relationship` arguments. .. seealso:: :ref:`relationship_primaryjoin` :param single_parent: When True, installs a validator which will prevent objects from being associated with more than one parent at a time. This is used for many-to-one or many-to-many relationships that should be treated either as one-to-one or one-to-many. Its usage is optional, except for :func:`_orm.relationship` constructs which are many-to-one or many-to-many and also specify the ``delete-orphan`` cascade option. The :func:`_orm.relationship` construct itself will raise an error instructing when this option is required. .. seealso:: :ref:`unitofwork_cascades` - includes detail on when the :paramref:`_orm.relationship.single_parent` flag may be appropriate. :param uselist: A boolean that indicates if this property should be loaded as a list or a scalar. In most cases, this value is determined automatically by :func:`_orm.relationship` at mapper configuration time. When using explicit :class:`_orm.Mapped` annotations, :paramref:`_orm.relationship.uselist` may be derived from the whether or not the annotation within :class:`_orm.Mapped` contains a collection class. Otherwise, :paramref:`_orm.relationship.uselist` may be derived from the type and direction of the relationship - one to many forms a list, many to one forms a scalar, many to many is a list. If a scalar is desired where normally a list would be present, such as a bi-directional one-to-one relationship, use an appropriate :class:`_orm.Mapped` annotation or set :paramref:`_orm.relationship.uselist` to False. The :paramref:`_orm.relationship.uselist` flag is also available on an existing :func:`_orm.relationship` construct as a read-only attribute, which can be used to determine if this :func:`_orm.relationship` deals with collections or scalar attributes:: >>> User.addresses.property.uselist True .. seealso:: :ref:`relationships_one_to_one` - Introduction to the "one to one" relationship pattern, which is typically when an alternate setting for :paramref:`_orm.relationship.uselist` is involved. :param viewonly=False: When set to ``True``, the relationship is used only for loading objects, and not for any persistence operation. A :func:`_orm.relationship` which specifies :paramref:`_orm.relationship.viewonly` can work with a wider range of SQL operations within the :paramref:`_orm.relationship.primaryjoin` condition, including operations that feature the use of a variety of comparison operators as well as SQL functions such as :func:`_expression.cast`. The :paramref:`_orm.relationship.viewonly` flag is also of general use when defining any kind of :func:`_orm.relationship` that doesn't represent the full set of related objects, to prevent modifications of the collection from resulting in persistence operations. .. seealso:: :ref:`relationship_viewonly_notes` - more details on best practices when using :paramref:`_orm.relationship.viewonly`. :param sync_backref: A boolean that enables the events used to synchronize the in-Python attributes when this relationship is target of either :paramref:`_orm.relationship.backref` or :paramref:`_orm.relationship.back_populates`. Defaults to ``None``, which indicates that an automatic value should be selected based on the value of the :paramref:`_orm.relationship.viewonly` flag. When left at its default, changes in state will be back-populated only if neither sides of a relationship is viewonly. .. versionadded:: 1.3.17 .. versionchanged:: 1.4 - A relationship that specifies :paramref:`_orm.relationship.viewonly` automatically implies that :paramref:`_orm.relationship.sync_backref` is ``False``. .. seealso:: :paramref:`_orm.relationship.viewonly` :param omit_join: Allows manual control over the "selectin" automatic join optimization. Set to ``False`` to disable the "omit join" feature added in SQLAlchemy 1.3; or leave as ``None`` to leave automatic optimization in place. .. note:: This flag may only be set to ``False``. It is not necessary to set it to ``True`` as the "omit_join" optimization is automatically detected; if it is not detected, then the optimization is not supported. .. versionchanged:: 1.3.11 setting ``omit_join`` to True will now emit a warning as this was not the intended use of this flag. .. versionadded:: 1.3 :param init: Specific to :ref:`orm_declarative_native_dataclasses`, specifies if the mapped attribute should be part of the ``__init__()`` method as generated by the dataclass process. :param repr: Specific to :ref:`orm_declarative_native_dataclasses`, specifies if the mapped attribute should be part of the ``__repr__()`` method as generated by the dataclass process. :param default_factory: Specific to :ref:`orm_declarative_native_dataclasses`, specifies a default-value generation function that will take place as part of the ``__init__()`` method as generated by the dataclass process. :param compare: Specific to :ref:`orm_declarative_native_dataclasses`, indicates if this field should be included in comparison operations when generating the ``__eq__()`` and ``__ne__()`` methods for the mapped class. .. versionadded:: 2.0.0b4 :param kw_only: Specific to :ref:`orm_declarative_native_dataclasses`, indicates if this field should be marked as keyword-only when generating the ``__init__()``. :param hash: Specific to :ref:`orm_declarative_native_dataclasses`, controls if this field is included when generating the ``__hash__()`` method for the mapped class. .. versionadded:: 2.0.36 ) r� r� r� r� r� r� r� r� r� r� r� r� rq r� r� r� rg r� r� r� r� rz r� r� r� r� r� rb r� r� )r r )&r� r� r� r� r� r� r� r� r� r� r� r� r� rN rO rP rQ rR rS rT r� r� r� rg r� r� r� r� rz r� r� r� r� r� rb r� r� rp rJ rJ rK � relationship� sX ]���"�r� ) � map_column� descriptorrz rN rO rP rQ rR rS rT rb r^ z Synonym[Any])r[ r� r� rz rN rO rP rQ rR rS rT rb r^ rI c C s& t | |||t|||||| | �| | d�S )a� Denote an attribute name as a synonym to a mapped property, in that the attribute will mirror the value and expression behavior of another attribute. e.g.:: class MyClass(Base): __tablename__ = "my_table" id = Column(Integer, primary_key=True) job_status = Column(String(50)) status = synonym("job_status") :param name: the name of the existing mapped property. This can refer to the string name ORM-mapped attribute configured on the class, including column-bound attributes and relationships. :param descriptor: a Python :term:`descriptor` that will be used as a getter (and potentially a setter) when this attribute is accessed at the instance level. :param map_column: **For classical mappings and mappings against an existing Table object only**. if ``True``, the :func:`.synonym` construct will locate the :class:`_schema.Column` object upon the mapped table that would normally be associated with the attribute name of this synonym, and produce a new :class:`.ColumnProperty` that instead maps this :class:`_schema.Column` to the alternate name given as the "name" argument of the synonym; in this way, the usual step of redefining the mapping of the :class:`_schema.Column` to be under a different name is unnecessary. This is usually intended to be used when a :class:`_schema.Column` is to be replaced with an attribute that also uses a descriptor, that is, in conjunction with the :paramref:`.synonym.descriptor` parameter:: my_table = Table( "my_table", metadata, Column("id", Integer, primary_key=True), Column("job_status", String(50)), ) class MyClass: @property def _job_status_descriptor(self): return "Status: %s" % self._job_status mapper( MyClass, my_table, properties={ "job_status": synonym( "_job_status", map_column=True, descriptor=MyClass._job_status_descriptor, ) }, ) Above, the attribute named ``_job_status`` is automatically mapped to the ``job_status`` column:: >>> j1 = MyClass() >>> j1._job_status = "employed" >>> j1.job_status Status: employed When using Declarative, in order to provide a descriptor in conjunction with a synonym, use the :func:`sqlalchemy.ext.declarative.synonym_for` helper. However, note that the :ref:`hybrid properties <mapper_hybrids>` feature should usually be preferred, particularly when redefining attribute behavior. :param info: Optional data dictionary which will be populated into the :attr:`.InspectionAttr.info` attribute of this object. :param comparator_factory: A subclass of :class:`.PropComparator` that will provide custom comparison behavior at the SQL expression level. .. note:: For the use case of providing an attribute which redefines both Python-level and SQL-expression level behavior of an attribute, please refer to the Hybrid attribute introduced at :ref:`mapper_hybrids` for a more effective technique. .. seealso:: :ref:`synonyms` - Overview of synonyms :func:`.synonym_for` - a helper oriented towards Declarative :ref:`mapper_hybrids` - The Hybrid Attribute extension provides an updated approach to augmenting attribute behavior more flexibly than can be achieved with synonyms. )r� r� rz rq r^ rb )r r ) r[ r� r� rz rN rO rP rQ rR rS rT rb r^ rJ rJ rK �synonym\ s z��r� zOptional[_SessionBind]r )�bind�kwargsrI c K s* |� dd� |� dd� tf d| i|��S )az Create a new :class:`.Session` with no automation enabled by default. This function is used primarily for testing. The usual route to :class:`.Session` creation is via its constructor or the :func:`.sessionmaker` function. :param bind: optional, a single Connectable to use for all database access in the created :class:`~sqlalchemy.orm.session.Session`. :param \*\*kwargs: optional, passed through to the :class:`.Session` constructor. :returns: an :class:`~sqlalchemy.orm.session.Session` instance The defaults of create_session() are the opposite of that of :func:`sessionmaker`; ``autoflush`` and ``expire_on_commit`` are False. Usage:: >>> from sqlalchemy.orm import create_session >>> session = create_session() It is recommended to use :func:`sessionmaker` instead of create_session(). Z autoflushFZexpire_on_commitr� )� setdefaultr )r� r� rJ rJ rK �create_session� s ! r� r )rv rp rI c O s t d��dS )a� Placeholder for the now-removed ``mapper()`` function. Classical mappings should be performed using the :meth:`_orm.registry.map_imperatively` method. This symbol remains in SQLAlchemy 2.0 to suit the deprecated use case of using the ``mapper()`` function as a target for ORM event listeners, which failed to be marked as deprecated in the 1.4 series. Global ORM mapper listeners should instead use the :class:`_orm.Mapper` class as the target. .. versionchanged:: 2.0 The ``mapper()`` function was removed; the symbol remains temporarily as a placeholder for the event listening use case. z�The 'sqlalchemy.orm.mapper()' function is removed as of SQLAlchemy 2.0. Use the 'sqlalchemy.orm.registry.map_imperatively()` method of the ``sqlalchemy.orm.registry`` class to perform classical mapping.Nr% )rv rp rJ rJ rK � _mapper_fn s �r� zRelationshipProperty[Any])r� rp rI c K s d|d< t | fi |��S )ai Construct a dynamically-loading mapper property. This is essentially the same as using the ``lazy='dynamic'`` argument with :func:`relationship`:: dynamic_loader(SomeClass) # is the same as relationship(SomeClass, lazy="dynamic") See the section :ref:`dynamic_relationship` for more details on dynamic loading. Zdynamicr� )r� )r� rp rJ rJ rK �dynamic_loader$ s r� r: )r[ r� rI c K s | |fS )a~ When using the :paramref:`_orm.relationship.backref` parameter, provides specific parameters to be used when the new :func:`_orm.relationship` is generated. E.g.:: "items": relationship(SomeItem, backref=backref("parent", lazy="subquery")) The :paramref:`_orm.relationship.backref` parameter is generally considered to be legacy; for modern applications, using explicit :func:`_orm.relationship` constructs linked together using the :paramref:`_orm.relationship.back_populates` parameter should be preferred. .. seealso:: :ref:`relationships_backref` - background on backrefs rJ )r[ r� rJ rJ rK r� : s r� )rx ry rz rN rO rP rQ rR rS rT rg r{ rb r^ )r| r} rx ry rz rN rO rP rQ rR rS rT rg r{ rb r^ rI c G s6 t | g|�R t|||||| | �|d||| | | |d� �S )a3 Indicate a column-based mapped attribute that by default will not load unless accessed. When using :func:`_orm.mapped_column`, the same functionality as that of :func:`_orm.deferred` construct is provided by using the :paramref:`_orm.mapped_column.deferred` parameter. :param \*columns: columns to be mapped. This is typically a single :class:`_schema.Column` object, however a collection is supported in order to support multiple columns mapped under the same attribute. :param raiseload: boolean, if True, indicates an exception should be raised if the load operation is to take place. .. versionadded:: 1.4 Additional arguments are the same as that of :func:`_orm.column_property`. .. seealso:: :ref:`orm_queryguide_deferred_imperative` T) rq rx rW ry rz rg r{ rb r^ )r r )r| rx ry rz rN rO rP rQ rR rS rT rg r{ rb r^ r} rJ rJ rK rW R s" +����rW )rO rR r{ rb r^ )� default_exprrO rR r{ rb r^ rI c C s6 t | td|tjtj|tjtj�|||dd�}d|_|S )aa Indicate an attribute that populates from a query-time SQL expression. :param default_expr: Optional SQL expression object that will be used in all cases if not assigned later with :func:`_orm.with_expression`. .. versionadded:: 1.2 .. seealso:: :ref:`orm_queryguide_with_expression` - background and usage examples FT)rq r{ rb r^ r~ ))�query_expressionT)r r r( r Z strategy_key)r� rO rR r{ rb r^ �proprJ rJ rK r� � s$ � �r� �None)rI c C s t �t �� d� dS )a� Remove all mappers from all classes. .. versionchanged:: 1.4 This function now locates all :class:`_orm.registry` objects and calls upon the :meth:`_orm.registry.dispose` method of each. This function removes all instrumentation from classes and disposes of their associated mappers. Once called, the classes are unmapped and can be later re-mapped with new mappers. :func:`.clear_mappers` is *not* for normal use, as there is literally no valid usage for it outside of very specific testing scenarios. Normally, mappers are permanent structural components of user-defined classes, and are never discarded independently of their class. If a mapped class itself is garbage collected, its mapper is automatically disposed of as well. As such, :func:`.clear_mappers` is only for usage in test suites that re-use the same classes with different mappings, which is itself an extremely rare use case - the only such use case is in fact SQLAlchemy's own test suite, and possibly the test suites of other ORM extension libraries which intend to test various combinations of mapper construction upon a fixed set of classes. FN)r Z_dispose_registriesZ_all_registriesrJ rJ rJ rK � clear_mappers� s r� �aliasedzType[_O]zOptional[FromClause]zAliasedType[_O])�elementrH r[ �flat�adapt_on_namesrI c C s d S r� rJ �r� rH r[ r� r� rJ rJ rK r� � s z4Union[AliasedClass[_O], Mapper[_O], AliasedInsp[_O]]zAliasedClass[_O]c C s d S r� rJ r� rJ rJ rK r� � s r, c C s d S r� rJ r� rJ rJ rK r� � s z"Union[_EntityType[_O], FromClause]z4Union[AliasedClass[_O], FromClause, AliasedType[_O]]c C s t j| ||||d�S )a Produce an alias of the given element, usually an :class:`.AliasedClass` instance. E.g.:: my_alias = aliased(MyClass) stmt = select(MyClass, my_alias).filter(MyClass.id > my_alias.id) result = session.execute(stmt) The :func:`.aliased` function is used to create an ad-hoc mapping of a mapped class to a new selectable. By default, a selectable is generated from the normally mapped selectable (typically a :class:`_schema.Table` ) using the :meth:`_expression.FromClause.alias` method. However, :func:`.aliased` can also be used to link the class to a new :func:`_expression.select` statement. Also, the :func:`.with_polymorphic` function is a variant of :func:`.aliased` that is intended to specify a so-called "polymorphic selectable", that corresponds to the union of several joined-inheritance subclasses at once. For convenience, the :func:`.aliased` function also accepts plain :class:`_expression.FromClause` constructs, such as a :class:`_schema.Table` or :func:`_expression.select` construct. In those cases, the :meth:`_expression.FromClause.alias` method is called on the object and the new :class:`_expression.Alias` object returned. The returned :class:`_expression.Alias` is not ORM-mapped in this case. .. seealso:: :ref:`tutorial_orm_entity_aliases` - in the :ref:`unified_tutorial` :ref:`orm_queryguide_orm_aliases` - in the :ref:`queryguide_toplevel` :param element: element to be aliased. Is normally a mapped class, but for convenience can also be a :class:`_expression.FromClause` element. :param alias: Optional selectable unit to map the element to. This is usually used to link the object to a subquery, and should be an aliased select construct as one would produce from the :meth:`_query.Query.subquery` method or the :meth:`_expression.Select.subquery` or :meth:`_expression.Select.alias` methods of the :func:`_expression.select` construct. :param name: optional string name to use for the alias, if not specified by the ``alias`` parameter. The name, among other things, forms the attribute name that will be accessible via tuples returned by a :class:`_query.Query` object. Not supported when creating aliases of :class:`_sql.Join` objects. :param flat: Boolean, will be passed through to the :meth:`_expression.FromClause.alias` call so that aliases of :class:`_expression.Join` objects will alias the individual tables inside the join, rather than creating a subquery. This is generally supported by all modern databases with regards to right-nested joins and generally produces more efficient queries. When :paramref:`_orm.aliased.flat` is combined with :paramref:`_orm.aliased.name`, the resulting joins will alias individual tables using a naming scheme similar to ``<prefix>_<tablename>``. This naming scheme is for visibility / debugging purposes only and the specific scheme is subject to change without notice. .. versionadded:: 2.0.32 added support for combining :paramref:`_orm.aliased.name` with :paramref:`_orm.aliased.flat`. Previously, this would raise ``NotImplementedError``. :param adapt_on_names: if True, more liberal "matching" will be used when mapping the mapped columns of the ORM entity to those of the given selectable - a name-based match will be performed if the given selectable doesn't otherwise have a column that corresponds to one on the entity. The use case for this is when associating an entity with some derived selectable such as one that uses aggregate functions:: class UnitPrice(Base): __tablename__ = "unit_price" ... unit_id = Column(Integer) price = Column(Numeric) aggregated_unit_price = ( Session.query(func.sum(UnitPrice.price).label("price")) .group_by(UnitPrice.unit_id) .subquery() ) aggregated_unit_price = aliased( UnitPrice, alias=aggregated_unit_price, adapt_on_names=True ) Above, functions on ``aggregated_unit_price`` which refer to ``.price`` will return the ``func.sum(UnitPrice.price).label('price')`` column, as it is matched on the name "price". Ordinarily, the "price" function wouldn't have any "column correspondence" to the actual ``UnitPrice.price`` column as it is not a proxy of the original. )rH r[ r� r� )r Z_alias_factoryr� rJ rJ rK r� � s q�zUnion[Type[_O], Mapper[_O]]z(Union[Literal['*'], Iterable[Type[Any]]]z'Union[Literal[False, None], FromClause]z Optional[ColumnElement[Any]]) �base�classes� selectabler� �polymorphic_onr� r� r� r[ �_use_mapper_pathrI c C s t j| ||||||||| d� S )a� Produce an :class:`.AliasedClass` construct which specifies columns for descendant mappers of the given base. Using this method will ensure that each descendant mapper's tables are included in the FROM clause, and will allow filter() criterion to be used against those tables. The resulting instances will also have those columns already loaded so that no "post fetch" of those columns will be required. .. seealso:: :ref:`with_polymorphic` - full discussion of :func:`_orm.with_polymorphic`. :param base: Base class to be aliased. :param classes: a single class or mapper, or list of class/mappers, which inherit from the base class. Alternatively, it may also be the string ``'*'``, in which case all descending mapped classes will be added to the FROM clause. :param aliased: when True, the selectable will be aliased. For a JOIN, this means the JOIN will be SELECTed from inside of a subquery unless the :paramref:`_orm.with_polymorphic.flat` flag is set to True, which is recommended for simpler use cases. :param flat: Boolean, will be passed through to the :meth:`_expression.FromClause.alias` call so that aliases of :class:`_expression.Join` objects will alias the individual tables inside the join, rather than creating a subquery. This is generally supported by all modern databases with regards to right-nested joins and generally produces more efficient queries. Setting this flag is recommended as long as the resulting SQL is functional. :param selectable: a table or subquery that will be used in place of the generated FROM clause. This argument is required if any of the desired classes use concrete table inheritance, since SQLAlchemy currently cannot generate UNIONs among tables automatically. If used, the ``selectable`` argument must represent the full set of tables and columns mapped by every mapped class. Otherwise, the unaccounted mapped columns will result in their table being appended directly to the FROM clause which will usually lead to incorrect results. When left at its default value of ``False``, the polymorphic selectable assigned to the base mapper is used for selecting rows. However, it may also be passed as ``None``, which will bypass the configured polymorphic selectable and instead construct an ad-hoc selectable for the target classes given; for joined table inheritance this will be a join that includes all target mappers and their subclasses. :param polymorphic_on: a column to be used as the "discriminator" column for the given selectable. If not given, the polymorphic_on attribute of the base classes' mapper will be used, if any. This is useful for mappings that don't have polymorphic loading behavior by default. :param innerjoin: if True, an INNER JOIN will be used. This should only be specified if querying for one specific subtype only :param adapt_on_names: Passes through the :paramref:`_orm.aliased.adapt_on_names` parameter to the aliased object. This may be useful in situations where the given selectable is not directly related to the existing mapped selectable. .. versionadded:: 1.4.33 :param name: Name given to the generated :class:`.AliasedClass`. .. versionadded:: 2.0.31 )r� r� r� r� r� r� r[ r� )r Z_with_polymorphic_factory) r� r� r� r� r� r� r� r� r[ r� rJ rJ rK �with_polymorphics s V�r� r> zOptional[_OnClauseArgument]r )�left�right�onclause�isouter�fullrI c C s t | ||||�S )a, Produce an inner join between left and right clauses. :func:`_orm.join` is an extension to the core join interface provided by :func:`_expression.join()`, where the left and right selectable may be not only core selectable objects such as :class:`_schema.Table`, but also mapped classes or :class:`.AliasedClass` instances. The "on" clause can be a SQL expression or an ORM mapped attribute referencing a configured :func:`_orm.relationship`. :func:`_orm.join` is not commonly needed in modern usage, as its functionality is encapsulated within that of the :meth:`_sql.Select.join` and :meth:`_query.Query.join` methods. which feature a significant amount of automation beyond :func:`_orm.join` by itself. Explicit use of :func:`_orm.join` with ORM-enabled SELECT statements involves use of the :meth:`_sql.Select.select_from` method, as in:: from sqlalchemy.orm import join stmt = ( select(User) .select_from(join(User, Address, User.addresses)) .filter(Address.email_address == "foo@bar.com") ) In modern SQLAlchemy the above join can be written more succinctly as:: stmt = ( select(User) .join(User.addresses) .filter(Address.email_address == "foo@bar.com") ) .. warning:: using :func:`_orm.join` directly may not work properly with modern ORM options such as :func:`_orm.with_loader_criteria`. It is strongly recommended to use the idiomatic join patterns provided by methods such as :meth:`.Select.join` and :meth:`.Select.join_from` when creating ORM joins. .. seealso:: :ref:`orm_queryguide_joins` - in the :ref:`queryguide_toplevel` for background on idiomatic ORM join patterns r )r� r� r� r� r� rJ rJ rK �join� s 7r� )r� r� r� r� rI c C s t | ||d|�S )a Produce a left outer join between left and right clauses. This is the "outer join" version of the :func:`_orm.join` function, featuring the same behavior except that an OUTER JOIN is generated. See that function's documentation for other usage details. Tr )r� r� r� r� rJ rJ rK � outerjoin s r� )NN)NN)N)FFTT)NN)N)N)NNFF)NNFF)NNFF)NNFF)FFNFFFNF)NFF)NF)l� __future__r �typingr r r r r r r r r r � r Z_typingr Zdescriptor_propsr r Z interfacesr Z propertiesr r �queryr Z relationshipsr r r r �sessionr r$ r r r r! r# �excr& Z sql._typingr' Zsql.baser( r) Z sql.schemar* r+ Zsql.selectabler, Z util.typingr- r. r/ r0 r1 r2 r3 Zmapperr4 r5 r6 r7 r8 r9 r: r; r< r= r> r? r@ rA Z sql.elementsrB rC rD rE rF �TypeVarrG � deprecatedrL r ZNULL_UNSPECIFIEDrr rt Zdeprecated_paramsr� r� r� r� r� r� r� r� r� rW �nullr� r� Z AliasedTyper� r� r� r� rJ rJ rJ rK �<module> s� � ��V ��2 ���6 &�6�6�6 ��4{ � I ��^ �, �& ��2=�� * � � � �} �$g �= � sqlalchemy/orm/__pycache__/query.cpython-39.pyc 0000644 00000316347 15125143220 0015522 0 ustar 00 a ��Jh�� � @ sn d Z ddlmZ ddlmZ ddlZddlmZ ddlm Z ddlm Z ddlm Z ddlm Z dd lm Z dd lmZ dd lmZ dd lmZ dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z ddlm Z ddl m Z ddl!m"Z" dd l#m$Z$ dd l#m%Z% dd l#m&Z& dd l#m'Z' dd l#m(Z( dd!l#m)Z) dd"lm*Z* dd#lm+Z+ dd$l m,Z, dd%l m-Z- dd&l m.Z. d'd(lm/Z0 d'd)lm1Z1 d'd*lm2Z2 d'd+lm3Z3 d'd,lm4Z4 d'dlm Z d'd-l5m6Z6 d'd.l5m7Z7 d'd/l8m9Z9 d'd0l8m:Z: d'd1l4m;Z; d'd2l4m<Z< d'd3l4m=Z= d'd4l4m>Z> d'dl4m Z? d'd5l4m@Z@ d'd6lAmBZB d'd7lAmCZC d'd8lDmEZE d'd9lFmGZG d'd:lFmHZH d'd;lFmIZI d'd<lFmJZJ d'd=lFmKZK d'd>lLmMZM d'd?lNmOZO d'd@lPmQZQ d'dAlPmRZR d'dBlPmSZS d'dClPmTZT d'dDlPmUZU d'dElPmVZV d'dFlPmWZW d'dGlPmXZX d'dHlYmZZZ d'dIlYm[Z[ e�r�ddJl m\Z\ ddKl m]Z] ddLl m^Z^ ddMl m_Z_ ddNl`maZa ddOlbmcZc ddPldmeZe ddQldmfZf ddRlgmhZh d'dSlimjZj d'dTlkmlZl d'dUlkmmZm d'dVlkmnZn d'dWlkmoZo d'dXlpmqZq d'dYlpmrZr d'dZlAmsZs d'd[lAmtZt d'd\lAmuZu d'd]lAmvZv d'd^lAmwZw d'd_lAmxZx d'd`lAmyZy d'dalAmzZz d'dblAm{Z{ d'dclAm|Z| d'ddlAm}Z} d'delAm~Z~ d'dflAmZ d'dglAm�Z� d'dhlAm�Z� d'dilAm�Z� d'djlAm�Z� d'dklAm�Z� d'dllAm�Z� d'dmlAm�Z� d'dnlFm�Z� d'dolFm�Z� d'dpl�m�Z� d'dqlLm�Z� d'drlLm�Z� d'dslPm�Z� d'dtlPm�Z� d'dulPm�Z� d'dvlPm�Z� d'dwlPm�Z� d'dxlPm�Z� d'dylPm�Z� d'dzlPm�Z� d'd{lPm�Z� d|d}gZ�ed~ed�Z�e2j�e3j�G d�d|� d|eReEeUeVeTe:e3j�eKeJe e� � ��Z�G d�d�� d�ej��Z�G d�d�� d��Z�G d�d�� d�e��Z�G d�d�� d�e��Z�G d�d�� d�e�e7eC �Z�dS )�a The Query class and support. Defines the :class:`_query.Query` class, the central construct used by the ORM to construct database queries. The :class:`_query.Query` class should not be confused with the :class:`_expression.Select` class, which defines database SELECT operations at the SQL (non-ORM) level. ``Query`` differs from ``Select`` in that it returns ORM-mapped objects and interacts with an ORM session, whereas the ``Select`` construct interacts directly with the database to return iterable result sets. � )� annotationsN)�Any)�Callable)�cast)�Dict)�Generic)�Iterable)�Iterator)�List)�Mapping)�Optional)�overload)�Sequence)�Tuple)�Type)� TYPE_CHECKING)�TypeVar)�Union� )� attributes)� interfaces)�loading)�util)�_O)� _assertions��_column_descriptions)� _determine_last_joined_entity)� _legacy_filter_by_entity_zero)� FromStatement)�ORMCompileState)� QueryContext)�ORMColumnDescription)�ORMColumnsClauseRole)� AliasedClass)� object_mapper)� with_parent� )�exc)�inspect)� inspection)�log)�sql)�Result)�Row)� dispatcher)� EventTarget)� coercions)� expression)�roles)�Select)�visitors)�_FromClauseArgument)�_TP)�SupportsCloneAnnotations��_entity_namespace_key)� _generative)�_NoArg)� Executable)� Generative)�BooleanClauseList)�Exists)�_MemoizedSelectEntities)�_SelectFromElements)� ForUpdateArg)�HasHints)� HasPrefixes)� HasSuffixes)� LABEL_STYLE_TABLENAME_PLUS_COL)�SelectLabelStyle)�Literal)�Self)� _EntityType)�_ExternalEntityType)�_InternalEntityType)�SynchronizeSessionArgument)�Mapper)� PathRegistry)�_PKIdentityArgument)�Session)� InstanceState)� CursorResult)�_ImmutableExecuteOptions)�CompiledCacheType)�IsolationLevel)�SchemaTranslateMapType)� FrozenResult)� ScalarResult)�_ColumnExpressionArgument)�#_ColumnExpressionOrStrLabelArgument)�_ColumnsClauseArgument)�_DMLColumnArgument)�_JoinTargetArgument)�_LimitOffsetType)� _MAYBE_ENTITY)�_no_kw)� _NOT_ENTITY)�_OnClauseArgument)�_PropagateAttrsType)�_T0)�_T1)�_T2)�_T3)�_T4)�_T5)�_T6)�_T7)�_TypedColumnClauseArgument)�CacheableOptions)�ExecutableOption)� UpdateBase)� ColumnElement)�Label)�_ForUpdateOfArgument)�_JoinTargetElement)�_SetupJoinsElement)�Alias)�CTE)�ExecutableReturnsRows)� FromClause)� ScalarSelect)�Subquery�Queryr! �_T)�boundc @ sP e Zd ZU dZdZded< dZded< dZded< dZded< dZ d ed < dZ d ed < d Z d ed< dZ ded< dZ ded< dZded< dZd ed< dZded< dZded< ejZded< dZejZded < d ed < ejd di Ze j Z d ed!< dZ dZ d"ed#< d$ed%< d&ed'< e j!d(d)�d*d+��Z"�d�d,d-d.�d/d0�Z#d1d2d3�d4d5�Z$d6d7d8�d9d:�Z%d;d<d=�d>d?�Z&d@d)�dAdB�Z'dCdDdE�dFdG�Z(dHd d7dI�dJdK�Z)e*dLd2dM�dNdO��Z+d7d)�dPdQ�Z,d7d)�dRdS�Z-�d�dCd d d7dT�dUdV�Z.�d�dCd d d7dT�dWdX�Z/dCd7dY�dZd[�Z0dCd7dY�d\d]�Z1dCd7dY�d^d_�Z2e3d d)�d`da��Z4�d�dbdbdcddded2df�dgdh�Z5did2dj�dkdl�Z6dmd)�dndo�Z7e3dpd)�dqdr��Z8�d�d dsdt�dudv�Z9�d�d d dwdx�dydz�Z:�d�d{d d d|d}�d~d�Z;�d�d{d d d�d��d�d��Z<d{d�d��d�d��Z=e>d�d�d=�d�d���Z?e>d�d�d=�d�d���Z?e>d�d)�d�d���Z?e �@d�d��d�d)�d�d���Z?e>d�d�d=�d�d���ZAe>d�d�d=�d�d���ZAe>d�d)�d�d���ZAd�d)�d�d��ZAe3dpd)�d�d���ZBdpd)�d�d��ZCe>d;d�d�d��d�d���ZDe>d;d�d;d��d�d���ZDe*d d�d��d�d���ZDe3d d)�d�d���ZEe*d d2d��d�d���ZFe*did2d��d�d���ZGe jHd�d�d��d2d)�d�d���ZIeIZJe3dd)�d�d���ZKdd2d��d�d��ZLe*d d2d��d�d���ZMe3d�d)�d�d���ZNe*d�d2d��d�d���ZOe*d�d2dd�dĄ�ZPe jHd�d�d��d�dedȜd�dʄ�ZQ�d�d�d�deded̜d�d΄ZRe3ddd)�d�dЄ�ZSe3d�d)�d�d҄�ZTe*d�d2dԜd�dք�ZUe*d d2dלd�dل�ZVe*d2d)�d�dۄ�ZWe*d d2d��d�d݄�ZXe jHd�d�d��e �Yd��d�d�d�d�d2d�d�d���ZZe*�d�d�d�d�d�d�d��Z[e*d$d2d�d�d��Z\d�d2d8�d�d�Z]e*d d2d�d�d��Z^e*�d�d�d d2d��d�d���Z_e �@d�d��d�d�d��d�d���Z`e`Zad�d�d��d�d��Zbe �@d��d ��ddi�d��d�d��Zce>�dd;�d��d�d��Zde>�d �d �d ��d �d��Zde>�d �d�d�d��d�d��Zde>�d �d�d�d�d��d�d��Zde>�d �d�d�d�d�d��d�d��Zde>�d �d�d�d�d�d�d ��d �d��Zde>�d �d�d�d�d�d �d �d ��d!�d��Zde>�d �d�d�d�d�d �d"�d#�d$��d%�d��Zde>�d �d�d�d�d�d �d"�d&�d'�d(� �d)�d��Zde>d�d�d8��d*�d��Zde*d�did��d+��d,�d��Zde*�dd��d��d-�d.��Zee �@d��d/��dd��d��d0�d1��Zfe*�d2d2�d3��d4�d5��Zg�d6d��d7��d8�d9�Zh�d:d)��d;�d<�Zie>�d=�d=�d=d d �d=�d=�d=�d=d d d �d>� �d?dC�d@d d d�d�d��dAd d d did2�dB��dC�dD��Zje>did2d���dE�dD��Zje*did2�dF��dG�dD��Zje*d d dd d �dH�d d �dId d d2�dJ��dK�dL��Zke*�d�dMdid2�dN��dO�dP��Zl�dQd2�dR��dS�dT�Zme*ene1e2��dQd2�dR��dU�dV���Zoe j!�dWd)��dX�dY��Zpdid)��dZ�d[�Zqdid2�dF��d\�d]�Zre*esjtf�d^�d_d2�d`��da�db��Zue*esjtf�d^�d_d2�d`��dc�dd��Zve*ene1e2��dQd2�de��df�dg���Zwdid�d2�dh��di�dj�Zxd�d2�dk��dl�dm�Zyd�d2�dk��dn�do�Zzd�d2�dk��dp�dq�Z{d�d2�dk��dr�ds�Z|d�d2�dk��dt�du�Z}d�d2�dk��dv�dw�Z~e*ene1e2��d�d d �dx��dy�dzd d d2�d{��d|�d}���Z�d�d �d~��dy�dzd d2�d��d��d��Z�e*ene1�d2d)��d��d����Z�e*ene0��d�d2�d���d��d����Z�didi�d���d��d��Z�e*ene1�d�d�d2�d���d��d����Z�e*ene1��d�d2�d���d��d����Z�e*ene1��d�d2�d���d��d����Z�e*ene1��dd2�d���d��d����Z��d�d)��d��d��Z�e*ene0��d�d2�d���d��d����Z��d�d)��d��d��Z��d�d)��d��d��Z��d�d)��d��d��Z�did)��d��d��Z��d�d)��d��d��Z��d�d)��d��d��Z�dCd)��d��d��Z�didididi�d���d��d��Z�e3�d�d)��d��d���Z�e �@�d��d���d�d��d�di�d���d��d���Z�e jH�d��d�d �d���d�d�d �ddÜ�dĐdń�Z��d�d)��dǐdȄZ�d�d)��dɐdʄZ��d�d̐d�d��dΜ�dϐdЄZ��d�dѐd̐d�d��dҜ�dӐdԄZ��d�d di�dՐd֜�dאdZ��d�d �dِdڜ�dېd܄Z�dS (� r} aO ORM-level SQL construction object. .. legacy:: The ORM :class:`.Query` object is a legacy construct as of SQLAlchemy 2.0. See the notes at the top of :ref:`query_api_toplevel` for an overview, including links to migration documentation. :class:`_query.Query` objects are normally initially generated using the :meth:`~.Session.query` method of :class:`.Session`, and in less common cases by instantiating the :class:`_query.Query` directly and associating with a :class:`.Session` using the :meth:`_query.Query.with_session` method. � z Tuple[ColumnElement[Any], ...]�_where_criteria�_having_criteria�_order_by_clauses�_group_by_clausesNz Optional[ColumnElement[Any]]� _limit_clause�_offset_clauseF�bool� _distinct� _distinct_onzOptional[ForUpdateArg]�_for_update_argzTuple[FromClause, ...]� _correlateT�_auto_correlate� _from_objz Tuple[_SetupJoinsElement, ...]� _setup_joinsrH � _label_stylez/Union[Type[CacheableOptions], CacheableOptions]�_compile_optionsz Tuple[ExecutableOption, ...]� _with_optionsZ_legacy_uniquingz util.immutabledict[str, Any]�_paramsz Optional[ExecutableReturnsRows]� _statementrR �sessionzdispatcher[Query[_T]]�dispatchre ��returnc C s t jS �N)r � EMPTY_DICT��selfr� r� �I/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/query.py�_propagate_attrs� s zQuery._propagate_attrszIUnion[_ColumnsClauseArgument[Any], Sequence[_ColumnsClauseArgument[Any]]]zOptional[Session])�entitiesr� c C s || _ | �|� dS )a� Construct a :class:`_query.Query` directly. E.g.:: q = Query([User, Address], session=some_session) The above is equivalent to:: q = some_session.query(User, Address) :param entities: a sequence of entities and/or SQL expressions. :param session: a :class:`.Session` with which the :class:`_query.Query` will be associated. Optional; a :class:`_query.Query` can be associated with a :class:`.Session` generatively via the :meth:`_query.Query.with_session` method as well. .. seealso:: :meth:`.Session.query` :meth:`_query.Query.with_session` N)r� � _set_entities)r� r� r� r� r� r� �__init__� s 'zQuery.__init__zMapping[str, Any]rJ )�valuesr� c C s t �|�| _| S r� )r Z immutabledictr� )r� r� r� r� r� �_set_propagate_attrs s zQuery._set_propagate_attrszIUnion[_ColumnsClauseArgument[Any], Iterable[_ColumnsClauseArgument[Any]]]�None)r� r� c s � fdd�t �|�D �� _d S )Nc s g | ]}t jtj|� d d��qS )T��apply_propagate_attrsZ post_inspect�r1 �expectr3 �ColumnsClauseRole)�.0�entr� r� r� � <listcomp> s ��z'Query._set_entities.<locals>.<listcomp>)r Zto_list� _raw_columns�r� r� r� r� r� r� s �zQuery._set_entitiesz Query[_O]zQuery[Tuple[_O]])r� r� c C s | � d�S )a� return a tuple-typed form of this :class:`.Query`. This method invokes the :meth:`.Query.only_return_tuples` method with a value of ``True``, which by itself ensures that this :class:`.Query` will always return :class:`.Row` objects, even if the query is made against a single entity. It then also at the typing level will return a "typed" query, if possible, that will type result rows as ``Tuple`` objects with typed elements. This method can be compared to the :meth:`.Result.tuples` method, which returns "self", but from a typing perspective returns an object that will yield typed ``Tuple`` objects for results. Typing takes effect only if this :class:`.Query` object is a typed query object already. .. versionadded:: 2.0 .. seealso:: :meth:`.Result.tuples` - v2 equivalent method. T)�only_return_tuplesr� r� r� r� �tuples* s z Query.tuplesz"Optional[_InternalEntityType[Any]]c C sl | j s d S | j d }d|jv r(|jd S d|jv r<|jd S t�|�D ] }d|jv rF|jd S qFd S d S )Nr � parententityZbundle)r� � _annotationsr5 Ziterate)r� r� �elementr� r� r� �_entity_from_pre_ent_zeroD s z Query._entity_from_pre_ent_zero�strz Mapper[Any])�methnamer� c C sH t | j�dks*d| jd jvs*| jd js8t�d| ��| jd jd S )Nr r� r z4%s() can only be used against a single mapped class.)�lenr� r� Z is_selectable�sa_exc�InvalidRequestError)r� r� r� r� r� �_only_full_mapper_zeroV s �� ���z Query._only_full_mapper_zeroz Iterable[_FromClauseArgument])�obj�set_base_aliasr� c s2 � fdd�|D �}� j d|i7 _ t|�� _d S )Nc s g | ]}t jtj|d � d��qS )T)Z allow_selectr� )r1 r� r3 ZStrictFromClauseRole)r� �elemr� r� r� r� f s ��z*Query._set_select_from.<locals>.<listcomp>�_set_base_alias)r� �tupler� )r� r� r� �far� r� r� �_set_select_fromc s � zQuery._set_select_fromzInstanceState[Any])�stater� c C s | j d|i7 _ | S )N�_lazy_loaded_from�� load_options)r� r� r� r� r� �_set_lazyload_froms s zQuery._set_lazyload_fromc C s | j dddd� dS )zused by legacy BakedQuery�getF��order_by�distinctN)�_no_criterion_conditionr� r� r� r� �_get_conditionx s zQuery._get_conditionc C s | j dddd� d S )Nr� Fr� )�_no_criterion_assertionr� r� r� r� �_get_existing_condition| s z Query._get_existing_condition)�methr� r� r� c C sf | j s d S | jsT| jd usT| jsT| jsT| jd usT| jd usT| jsT|rJ| jsT|rb| j rbt � d| ��d S �Nz<Query.%s() being called on a Query with existing criterion. ) �_enable_assertionsr� r� r� r� r� r� r� r� r� r� r� �r� r� r� r� r� r� r� r� s: ��������� � � ��z Query._no_criterion_assertionc C sR | � |||� d | _| _| jd ur6| jdd i7 _d| _d| _d | _| _d S )Nr� r� F) r� r� r� r� r� r� r� r� r� r� r� r� r� r� � s z Query._no_criterion_condition)r� r� c C s, | j s d S | jr t�d| ��| �|� d S r� )r� r� r� r� r� �r� r� r� r� r� �_no_clauseelement_condition� s ��z!Query._no_clauseelement_conditionc C s& | j s d S | jd ur"t�d| ��d S )Nz[Query.%s() being called on a Query with an existing full statement - can't apply criterion.)r� r� r� r� r� r� r� r� �_no_statement_condition� s ��z Query._no_statement_conditionc C s4 | j s d S | jd us | jd ur0t�d||f ��d S )Nz�Query.%s() being called on a Query which already has LIMIT or OFFSET applied. Call %s() before limit() or offset() are applied.)r� r� r� r� r� r� r� r� r� �_no_limit_offset� s ��zQuery._no_limit_offsetc C s | j d up| jd uS r� )r� r� r� r� r� r� �_has_row_limiting_clause� s �z Query._has_row_limiting_clausezOptional[bool]zOptional[Sequence[str]]z Optional[InstanceState[Any]]z Optional[Any])�populate_existing� version_check�only_load_props� refresh_state�identity_tokenr� c C sx i }i }|r||d< |r ||d< |r4||d< d|d< |rDt |�|d< |rP||d< |rb| j|7 _|rt| j|7 _| S )NZ_version_check�_populate_existingZ_refresh_stateTZ_for_refresh_stateZ_only_load_propsZ_identity_token)� frozensetr� r� )r� r� r� r� r� r� r� �compile_optionsr� r� r� � _get_options� s$ zQuery._get_optionsr )�kwr� c K s | � � S r� )� _generate)r� r� r� r� r� �_clone� s z Query._clone� Select[_T]c C s | j d urt�d��td| j�S )Nz<Can't call this method on a Query that uses from_statement()r� )r� r� r� r � statementr� r� r� r� �_get_select_statement_only� s �z Query._get_select_statement_onlyz0Union[Select[_T], FromStatement[_T], UpdateBase]c C s: | j js| jdd�}n| jdd�j}| jr6|�| j�}|S )z�The full SELECT statement represented by this Query. The statement by default will not have disambiguating labels applied to the construct unless with_labels(True) is called first. T�� for_statement)r� r� � _statement_20�_compile_stater� r� �params)r� �stmtr� r� r� r� � s zQuery.statementz Select[Any])�legacy_query_styler� c C s | � � }|j|d�jS )a8 Return the 'final' SELECT statement for this :class:`.Query`. This is used by the testing suite only and is fairly inefficient. This is the Core-only select() that will be rendered by a complete compilation of this query, and is what .statement used to return in 1.3. )�use_legacy_query_style)r� r� r� )r� r� �qr� r� r� �_final_statement s �zQuery._final_statementz$Union[Select[_T], FromStatement[_T]])r� r� r� c C s� | j jrJ| j jD ]8}|| �}|d ur|| ur|} |js| jddi7 _q| j}|||d�7 }| jd ur�t| j| j�}|jj| j | j || j | j d� n6t jf i | j��}|jj| j|| j d� |j�dd � d|j vr�|j �dd d ��|_ |S ) N�_bake_okF)�_for_statementZ_use_legacy_query_style)r� �_with_context_optionsr� �_execution_optionsr� )r� r� r� r� �compile_state_plugin�orm)r� Zplugin_subject)r� Zbefore_compiler� r� r� r r� �__dict__�updater� r� r� r� r4 Z_create_raw_selectr� �pop�union)r� r� r� �fn� new_queryr� r� r� r� r� r� , sB � � � �zQuery._statement_20z Optional[str]r| )�name� with_labels�reduce_columnsr� c C sJ | � d�}|r|�t�}|�� }tr2t|t�s2J �|r>|�� }|j|d�S )a� Return the full SELECT statement represented by this :class:`_query.Query`, embedded within an :class:`_expression.Alias`. Eager JOIN generation within the query is disabled. .. seealso:: :meth:`_sql.Select.subquery` - v2 comparable method. :param name: string name to be assigned as the alias; this is passed through to :meth:`_expression.FromClause.alias`. If ``None``, a name will be deterministically generated at compile time. :param with_labels: if True, :meth:`.with_labels` will be called on the :class:`_query.Query` first to apply table-qualified labels to all columns. :param reduce_columns: if True, :meth:`_expression.Select.reduce_columns` will be called on the resulting :func:`_expression.select` construct, to remove same-named columns where one also refers to the other via foreign key or WHERE clause equivalence. F)r� ) �enable_eagerloads�set_label_stylerG r� r � isinstancer4 r� �subquery)r� r� r� r� r� r� r� r� r� r ` s zQuery.subqueryrx )r� � recursive�nestingr� c C s | � d��� j|||d�S )a� Return the full SELECT statement represented by this :class:`_query.Query` represented as a common table expression (CTE). Parameters and usage are the same as those of the :meth:`_expression.SelectBase.cte` method; see that method for further details. Here is the `PostgreSQL WITH RECURSIVE example <https://www.postgresql.org/docs/current/static/queries-with.html>`_. Note that, in this example, the ``included_parts`` cte and the ``incl_alias`` alias of it are Core selectables, which means the columns are accessed via the ``.c.`` attribute. The ``parts_alias`` object is an :func:`_orm.aliased` instance of the ``Part`` entity, so column-mapped attributes are available directly:: from sqlalchemy.orm import aliased class Part(Base): __tablename__ = "part" part = Column(String, primary_key=True) sub_part = Column(String, primary_key=True) quantity = Column(Integer) included_parts = ( session.query(Part.sub_part, Part.part, Part.quantity) .filter(Part.part == "our part") .cte(name="included_parts", recursive=True) ) incl_alias = aliased(included_parts, name="pr") parts_alias = aliased(Part, name="p") included_parts = included_parts.union_all( session.query( parts_alias.sub_part, parts_alias.part, parts_alias.quantity ).filter(parts_alias.part == incl_alias.c.sub_part) ) q = session.query( included_parts.c.sub_part, func.sum(included_parts.c.quantity).label("total_quantity"), ).group_by(included_parts.c.sub_part) .. seealso:: :meth:`_sql.Select.cte` - v2 equivalent method. F)r� r r )r� r� �cte)r� r� r r r� r� r� r � s :��z Query.ctez Label[Any])r� r� c C s | � d��� �|�S )z�Return the full SELECT statement represented by this :class:`_query.Query`, converted to a scalar subquery with a label of the given name. .. seealso:: :meth:`_sql.Select.label` - v2 comparable method. F)r� r� �label)r� r� r� r� r� r � s ��z Query.labelzQuery[Tuple[_MAYBE_ENTITY]]zScalarSelect[_MAYBE_ENTITY]c C s d S r� r� r� r� r� r� � as_scalar� s zQuery.as_scalarzQuery[Tuple[_NOT_ENTITY]]zScalarSelect[_NOT_ENTITY]c C s d S r� r� r� r� r� r� r � s zScalarSelect[Any]c C s d S r� r� r� r� r� r� r � s �1.4z�The :meth:`_query.Query.as_scalar` method is deprecated and will be removed in a future release. Please refer to :meth:`_query.Query.scalar_subquery`.c C s | � � S )z}Return the full SELECT statement represented by this :class:`_query.Query`, converted to a scalar subquery. )�scalar_subqueryr� r� r� r� r � s c C s d S r� r� r� r� r� r� r � s zQuery.scalar_subqueryc C s d S r� r� r� r� r� r� r � s c C s d S r� r� r� r� r� r� r s c C s | � d��� �� S )a� Return the full SELECT statement represented by this :class:`_query.Query`, converted to a scalar subquery. Analogous to :meth:`sqlalchemy.sql.expression.SelectBase.scalar_subquery`. .. versionchanged:: 1.4 The :meth:`_query.Query.scalar_subquery` method replaces the :meth:`_query.Query.as_scalar` method. .. seealso:: :meth:`_sql.Select.scalar_subquery` - v2 comparable method. F)r� r� r r� r� r� r� r s �c C s | � � S )z�Return the :class:`_expression.Select` object emitted by this :class:`_query.Query`. Used for :func:`_sa.inspect` compatibility, this is equivalent to:: query.enable_eagerloads(False).with_labels().statement )�__clause_element__r� r� r� r� � selectable s zQuery.selectablec C s | j ddd��t�jS )NFT)�_enable_eagerloadsZ_render_for_subquery)�_with_compile_optionsr rG r� r� r� r� r� r & s ���zQuery.__clause_element__z Literal[True]z RowReturningQuery[Tuple[_O]])r� �valuer� c C s d S r� r� �r� r r� r� r� r� 1 s zQuery.only_return_tupleszLiteral[False]c C s d S r� r� r r� r� r� r� 6 s � Query[Any])r r� c C s | j t|d�7 _ | S )a� When set to True, the query results will always be a :class:`.Row` object. This can change a query that normally returns a single entity as a scalar to return a :class:`.Row` result in all cases. .. seealso:: :meth:`.Query.tuples` - returns tuples, but also at the typing level will type results as ``Tuple``. :meth:`_query.Query.is_single_entity` :meth:`_engine.Result.tuples` - v2 comparable method. )�_only_return_tuples)r� �dictr r� r� r� r� ; s c C s> | j j o<t| j�dko<d| jd jv o<t| jd jd t�S )a� Indicates if this :class:`_query.Query` returns tuples or single entities. Returns True if this query returns a single entity for each instance in its result list, and False if this query returns a tuple of entities for each result. .. versionadded:: 1.3.11 .. seealso:: :meth:`_query.Query.only_return_tuples` r r� r )r� r r� r� r� r r# r� r� r� r� �is_single_entityP s ����zQuery.is_single_entityc C s | j d|i7 _ | S )a Control whether or not eager joins and subqueries are rendered. When set to False, the returned Query will not render eager joins regardless of :func:`~sqlalchemy.orm.joinedload`, :func:`~sqlalchemy.orm.subqueryload` options or mapper-level ``lazy='joined'``/``lazy='subquery'`` configurations. This is used primarily when nesting the Query's statement into a subquery or other selectable, or when using :meth:`_query.Query.yield_per`. r �r� r r� r� r� r� j s zQuery.enable_eagerloads)�optr� c K s | j |7 _ | S r� r �r� r r� r� r� r } s zQuery._with_compile_optionszB:meth:`_orm.Query.with_labels` and :meth:`_orm.Query.apply_labels`z<Use set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL) instead.)� alternativec C s | � tj�S r� )r rH rG r� r� r� r� r� � s �zQuery.with_labelsc C s | j S )z� Retrieve the current label style. .. versionadded:: 1.4 .. seealso:: :meth:`_sql.Select.get_label_style` - v2 equivalent method. )r� r� r� r� r� �get_label_style� s zQuery.get_label_style)�styler� c C s | j |ur| �� } || _ | S )a� Apply column labels to the return value of Query.statement. Indicates that this Query's `statement` accessor should return a SELECT statement that applies labels to all columns in the form <tablename>_<columnname>; this is commonly used to disambiguate columns from multiple tables which have the same name. When the `Query` actually issues SQL to load rows, it always uses column labeling. .. note:: The :meth:`_query.Query.set_label_style` method *only* applies the output of :attr:`_query.Query.statement`, and *not* to any of the result-row invoking systems of :class:`_query.Query` itself, e.g. :meth:`_query.Query.first`, :meth:`_query.Query.all`, etc. To execute a query using :meth:`_query.Query.set_label_style`, invoke the :attr:`_query.Query.statement` using :meth:`.Session.execute`:: result = session.execute( query.set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL).statement ) .. versionadded:: 1.4 .. seealso:: :meth:`_sql.Select.set_label_style` - v2 equivalent method. )r� r� )r� r r� r� r� r � s ! zQuery.set_label_stylec C s || _ | S )a Control whether assertions are generated. When set to False, the returned Query will not assert its state before certain operations, including that LIMIT/OFFSET has not been applied when filter() is called, no criterion exists when get() is called, and no "from_statement()" exists when filter()/order_by()/group_by() etc. is called. This more permissive mode is used by custom Query subclasses to specify criterion or other modifiers outside of the usual usage patterns. Care should be taken to ensure that the usage pattern is even possible. A statement applied by from_statement() will override any criterion set by filter() or order_by(), for example. )r� r r� r� r� �enable_assertions� s zQuery.enable_assertionsz Optional[ColumnElement[bool]]c C s t �| j�S )a3 A readonly attribute which returns the current WHERE criterion for this Query. This returned value is a SQL expression construct, or ``None`` if no criterion has been established. .. seealso:: :attr:`_sql.Select.whereclause` - v2 equivalent property. )r? Z_construct_for_whereclauser� r� r� r� r� � whereclause� s �zQuery.whereclauserP )�pathr� c C s | j d|i7 _ | S )a indicate that this query applies to objects loaded within a certain path. Used by deferred loaders (see strategies.py) which transfer query options from an originating query to a newly generated query intended for the deferred load. � _current_pathr )r� r r� r� r� �_with_current_path� s zQuery._with_current_path�int)�countr� c C s | j d|i7 _ | S )a� Yield only ``count`` rows at a time. The purpose of this method is when fetching very large result sets (> 10K rows), to batch results in sub-collections and yield them out partially, so that the Python interpreter doesn't need to declare very large areas of memory which is both time consuming and leads to excessive memory use. The performance from fetching hundreds of thousands of rows can often double when a suitable yield-per setting (e.g. approximately 1000) is used, even with DBAPIs that buffer rows (which are most). As of SQLAlchemy 1.4, the :meth:`_orm.Query.yield_per` method is equivalent to using the ``yield_per`` execution option at the ORM level. See the section :ref:`orm_queryguide_yield_per` for further background on this option. .. seealso:: :ref:`orm_queryguide_yield_per` � _yield_perr� )r� r r� r� r� � yield_per� s zQuery.yield_perz:meth:`_orm.Query.get`z7The method is now available as :meth:`_orm.Session.get`rQ )�identr� c C s | j dddd� | �|tj�S )a� Return an instance based on the given primary key identifier, or ``None`` if not found. E.g.:: my_user = session.query(User).get(5) some_object = session.query(VersionedFoo).get((5, 10)) some_object = session.query(VersionedFoo).get({"id": 5, "version_id": 10}) :meth:`_query.Query.get` is special in that it provides direct access to the identity map of the owning :class:`.Session`. If the given primary key identifier is present in the local identity map, the object is returned directly from this collection and no SQL is emitted, unless the object has been marked fully expired. If not present, a SELECT is performed in order to locate the object. :meth:`_query.Query.get` also will perform a check if the object is present in the identity map and marked as expired - a SELECT is emitted to refresh the object as well as to ensure that the row is still present. If not, :class:`~sqlalchemy.orm.exc.ObjectDeletedError` is raised. :meth:`_query.Query.get` is only used to return a single mapped instance, not multiple instances or individual column constructs, and strictly on a single primary key value. The originating :class:`_query.Query` must be constructed in this way, i.e. against a single mapped entity, with no additional filtering criterion. Loading options via :meth:`_query.Query.options` may be applied however, and will be used if the object is not yet locally present. :param ident: A scalar, tuple, or dictionary representing the primary key. For a composite (e.g. multiple column) primary key, a tuple or dictionary should be passed. For a single-column primary key, the scalar calling form is typically the most expedient. If the primary key of a row is the value "5", the call looks like:: my_object = query.get(5) The tuple form contains primary key values typically in the order in which they correspond to the mapped :class:`_schema.Table` object's primary key columns, or if the :paramref:`_orm.Mapper.primary_key` configuration parameter were used, in the order used for that parameter. For example, if the primary key of a row is represented by the integer digits "5, 10" the call would look like:: my_object = query.get((5, 10)) The dictionary form should include as keys the mapped attribute names corresponding to each element of the primary key. If the mapped class has the attributes ``id``, ``version_id`` as the attributes which store the object's primary key value, the call would look like:: my_object = query.get({"id": 5, "version_id": 10}) .. versionadded:: 1.3 the :meth:`_query.Query.get` method now optionally accepts a dictionary of attribute names to values in order to indicate a primary key identifier. :return: The object instance, or ``None``. r� Fr� )r� � _get_implr Zload_on_pk_identity)r� r# r� r� r� r� s Qz Query.getzCallable[..., Any])�primary_key_identity� db_load_fnr� r� c C s0 | � d�}| jj|||| jj| j| j|| jd�S )Nr� )r� �with_for_update�optionsr� �execution_options)r� r� r$ r� r� r� r� r� )r� r% r& r� �mapperr� r� r� r$ h s �zQuery._get_implc C s | j jS )a� An :class:`.InstanceState` that is using this :class:`_query.Query` for a lazy load operation. .. deprecated:: 1.4 This attribute should be viewed via the :attr:`.ORMExecuteState.lazy_loaded_from` attribute, within the context of the :meth:`.SessionEvents.do_orm_execute` event. .. seealso:: :attr:`.ORMExecuteState.lazy_loaded_from` )r� r� r� r� r� r� �lazy_loaded_fromz s zQuery.lazy_loaded_fromc C s | j jS r� )r� r r� r� r� r� r � s zQuery._current_pathz0Union[Literal[None, False], _FromClauseArgument])� fromclausesr� c G s< d| _ |r |d dv r d| _n| jtdd� |D �� | _| S )a� Return a :class:`.Query` construct which will correlate the given FROM clauses to that of an enclosing :class:`.Query` or :func:`~.expression.select`. The method here accepts mapped classes, :func:`.aliased` constructs, and :class:`_orm.Mapper` constructs as arguments, which are resolved into expression constructs, in addition to appropriate expression constructs. The correlation arguments are ultimately passed to :meth:`_expression.Select.correlate` after coercion to expression constructs. The correlation arguments take effect in such cases as when :meth:`_query.Query.from_self` is used, or when a subquery as returned by :meth:`_query.Query.subquery` is embedded in another :func:`_expression.select` construct. .. seealso:: :meth:`_sql.Select.correlate` - v2 equivalent method. Fr > FNr� c s s | ]}t �tj|�V qd S r� )r1 r� r3 ZFromClauseRole)r� �fr� r� r� � <genexpr>� s z"Query.correlate.<locals>.<genexpr>)r� r� r� )r� r, r� r� r� � correlate� s � zQuery.correlate)�settingr� c C s | j d|i7 _ | S )a? Return a Query with a specific 'autoflush' setting. As of SQLAlchemy 1.4, the :meth:`_orm.Query.autoflush` method is equivalent to using the ``autoflush`` execution option at the ORM level. See the section :ref:`orm_queryguide_autoflush` for further background on this option. Z _autoflushr� )r� r0 r� r� r� � autoflush� s zQuery.autoflushc C s | j ddi7 _ | S )a� Return a :class:`_query.Query` that will expire and refresh all instances as they are loaded, or reused from the current :class:`.Session`. As of SQLAlchemy 1.4, the :meth:`_orm.Query.populate_existing` method is equivalent to using the ``populate_existing`` execution option at the ORM level. See the section :ref:`orm_queryguide_populate_existing` for further background on this option. r� Tr� r� r� r� r� r� � s zQuery.populate_existingc C s | j d|i7 _ | S )z�Set the 'invoke all eagers' flag which causes joined- and subquery loaders to traverse into already-loaded related objects and collections. Default is that of :attr:`_query.Query._invoke_all_eagers`. Z_invoke_all_eagersr� r r� r� r� �_with_invoke_all_eagers� s z Query._with_invoke_all_eagersz :meth:`_orm.Query.with_parent`z6Use the :func:`_orm.with_parent` standalone construct.z sqlalchemy.orm.relationships�objectz,Optional[attributes.QueryableAttribute[Any]]z"Optional[_ExternalEntityType[Any]])�instance�property� from_entityr� c C s� t jj}|rt|�}nt| �}|du rvt|�}|jD ]$}t||j�r4|j |j u r4|} qvq4t � d|j j j |jj f ��| �t|||j��S )a Add filtering criterion that relates the given instance to a child object or collection, using its attribute state as well as an established :func:`_orm.relationship()` configuration. The method uses the :func:`.with_parent` function to generate the clause, the result of which is passed to :meth:`_query.Query.filter`. Parameters are the same as :func:`.with_parent`, with the exception that the given property can be None, in which case a search is performed against this :class:`_query.Query` object's target mapper. :param instance: An instance which has some :func:`_orm.relationship`. :param property: Class bound attribute which indicates what relationship from the instance should be used to reconcile the parent/child relationship. :param from_entity: Entity in which to consider as the left side. This defaults to the "zero" entity of the :class:`_query.Query` itself. Nz\Could not locate a property which relates instances of class '%s' to instances of class '%s')r Z preloadedZorm_relationshipsr) r r% Ziterate_propertiesr ZRelationshipPropertyr* r� r� �class_�__name__� __class__�filterr& �entity)r� r4 r5 r6 Z relationshipsZ entity_zeror* �propr� r� r� r& � s6 ' � ���� ��zQuery.with_parentz_EntityType[Any]z Optional[Union[Alias, Subquery]])r; �aliasr� c C s< |durt ||�}t| j�| _| j�tjtj|| d�� | S )z�add a mapped entity to the list of result columns to be returned. .. seealso:: :meth:`_sql.Select.add_columns` - v2 comparable method. N�r� )r$ �listr� �appendr1 r� r3 r� )r� r; r= r� r� r� � add_entity' s ��zQuery.add_entity)r� r� c C s || _ | S )a Return a :class:`_query.Query` that will use the given :class:`.Session`. While the :class:`_query.Query` object is normally instantiated using the :meth:`.Session.query` method, it is legal to build the :class:`_query.Query` directly without necessarily using a :class:`.Session`. Such a :class:`_query.Query` object, or any :class:`_query.Query` already associated with a different :class:`.Session`, can produce a new :class:`_query.Query` object associated with a target session using this method:: from sqlalchemy.orm import Query query = Query([MyClass]).filter(MyClass.id == 5) result = query.with_session(my_session).one() )r� )r� r� r� r� r� � with_sessionB s zQuery.with_sessionz_ColumnsClauseArgument[Any]c G s4 | � t��d ��� �� }| �|�}|r0|�|� |S r� )r rG r/ r Z_anonymous_fromclause�_from_selectabler� )r� r� � fromclauser� r� r� r� �_legacy_from_self] s � � zQuery._legacy_from_self)�valr� c C s | j d|i7 _ | S )N�_enable_single_critr )r� rF r� r� r� �_set_enable_single_critp s z Query._set_enable_single_critrz )rD �set_entity_fromr� c C s< dD ]}| j �|d � q| �|g|� | jddi7 _| S )N) r� r� r� r� r� �_last_joined_entityr� �_memoized_select_entitiesr� r� r� � _prefixesZ _suffixesrG F)r� r� r� r� )r� rD rI �attrr� r� r� rC u s �zQuery._from_selectablez�:meth:`_query.Query.values` is deprecated and will be removed in a future release. Please use :meth:`_query.Query.with_entities`z Iterable[Any])�columnsr� c G s | j |� S )zfReturn an iterator yielding result tuples corresponding to the given list of columns )�_values_no_warn)r� rN r� r� r� r� � s z Query.valuesc G sF |s t d�S | �� �d�}|�|� |jjs>| jddi7 _t |�S )Nr� Fr! � )�iterr� r� r� r� r! )r� rN r� r� r� r� rO � s zQuery._values_no_warnz�:meth:`_query.Query.value` is deprecated and will be removed in a future release. Please use :meth:`_query.Query.with_entities` in combination with :meth:`_query.Query.scalar`z _ColumnExpressionArgument[Any])�columnr� c C s. zt | �|��d W S ty( Y dS 0 dS )zVReturn a scalar result corresponding to the given column expression. r N)�nextrO � StopIteration�r� rR r� r� r� r � s z Query.valuez_EntityType[_O])�_entityr� c C s d S r� r� )r� rV r� r� r� � with_entities� s zQuery.with_entitiesz roles.TypedColumnsClauseRole[_T]z RowReturningQuery[Tuple[_T]])�_colexprr� c C s d S r� r� )r� rX r� r� r� rW � s z _TCCA[_T0]z _TCCA[_T1]z"RowReturningQuery[Tuple[_T0, _T1]])� _Query__ent0� _Query__ent1r� c C s d S r� r� )r� rY rZ r� r� r� rW � s z _TCCA[_T2]z'RowReturningQuery[Tuple[_T0, _T1, _T2]])rY rZ � _Query__ent2r� c C s d S r� r� )r� rY rZ r[ r� r� r� rW � s z _TCCA[_T3]z,RowReturningQuery[Tuple[_T0, _T1, _T2, _T3]])rY rZ r[ � _Query__ent3r� c C s d S r� r� )r� rY rZ r[ r\ r� r� r� rW � s z _TCCA[_T4]z1RowReturningQuery[Tuple[_T0, _T1, _T2, _T3, _T4]])rY rZ r[ r\ � _Query__ent4r� c C s d S r� r� )r� rY rZ r[ r\ r] r� r� r� rW � s z _TCCA[_T5]z6RowReturningQuery[Tuple[_T0, _T1, _T2, _T3, _T4, _T5]])rY rZ r[ r\ r] � _Query__ent5r� c C s d S r� r� )r� rY rZ r[ r\ r] r^ r� r� r� rW � s z _TCCA[_T6]z;RowReturningQuery[Tuple[_T0, _T1, _T2, _T3, _T4, _T5, _T6]])rY rZ r[ r\ r] r^ � _Query__ent6r� c C s d S r� r� )r� rY rZ r[ r\ r] r^ r_ r� r� r� rW � s z _TCCA[_T7]z@RowReturningQuery[Tuple[_T0, _T1, _T2, _T3, _T4, _T5, _T6, _T7]]) rY rZ r[ r\ r] r^ r_ � _Query__ent7r� c C s d S r� r� ) r� rY rZ r[ r\ r] r^ r_ r` r� r� r� rW � s c G s d S r� r� r� r� r� r� rW s )r� � _Query__kwr� c O s" |r t � �t�| � | �|� | S )a� Return a new :class:`_query.Query` replacing the SELECT list with the given entities. e.g.:: # Users, filtered on some arbitrary criterion # and then ordered by related email address q = ( session.query(User) .join(User.address) .filter(User.name.like("%ed%")) .order_by(Address.email) ) # given *only* User.id==5, Address.email, and 'q', what # would the *next* User in the result be ? subq = ( q.with_entities(Address.email) .order_by(None) .filter(User.id == 5) .subquery() ) q = q.join((subq, subq.c.email < Address.email)).limit(1) .. seealso:: :meth:`_sql.Select.with_only_columns` - v2 comparable method. )rb rA Z_generate_for_statementr� )r� r� ra r� r� r� rW s ! c s* t � j�� _� j�� fdd�|D �� � S )z�Add one or more column expressions to the list of result columns to be returned. .. seealso:: :meth:`_sql.Select.add_columns` - v2 comparable method. c 3 s" | ]}t jtj|� d d�V qdS )Tr� Nr� )r� �cr� r� r� r. J s ��z$Query.add_columns.<locals>.<genexpr>)r? r� �extendrU r� r� r� � add_columns< s � zQuery.add_columnsz�:meth:`_query.Query.add_column` is deprecated and will be removed in a future release. Please use :meth:`_query.Query.add_columns`c C s | � |�S )zWAdd a column expression to the list of result columns to be returned. )rd rU r� r� r� � add_columnU s zQuery.add_columnrp )�argsr� c G sj t t�|��}| jjr8|D ]}|js|jr|�| � qn |D ]}|js<|jr<|�| � q<| j |7 _ | S )aK Return a new :class:`_query.Query` object, applying the given list of mapper options. Most supplied options regard changing how column- and relationship-mapped attributes are loaded. .. seealso:: :ref:`loading_columns` :ref:`relationship_loader_options` ) r� r Zflatten_iteratorr� r Z_is_coreZ_is_legacy_optionZprocess_query_conditionallyZ process_queryr� )r� rf �optsr r� r� r� r( b s z Query.optionsz"Callable[[Query[Any]], Query[Any]])r� r� c C s || �S )a� Return a new :class:`_query.Query` object transformed by the given function. E.g.:: def filter_something(criterion): def transform(q): return q.filter(criterion) return transform q = q.with_transformation(filter_something(x == 5)) This allows ad-hoc recipes to be created for :class:`_query.Query` objects. r� )r� r� r� r� r� �with_transformation� s zQuery.with_transformationrU c C s | j S )a Get the non-SQL options which will take effect during execution. .. versionadded:: 1.3 .. seealso:: :meth:`_query.Query.execution_options` :meth:`_sql.Select.get_execution_options` - v2 comparable method. )r� r� r� r� r� �get_execution_options� s zQuery.get_execution_options.) �compiled_cache� logging_token�isolation_level� no_parameters�stream_results�max_row_bufferr" �insertmanyvalues_page_size�schema_translate_mapr� r1 �preserve_rowcountzOptional[CompiledCacheType]rW z Optional[SchemaTranslateMapType])rj rk rl rm rn ro r" rp rq r� r1 rr r r� c K s d S r� r� )r� rj rk rl rm rn ro r" rp rq r� r1 rr r r� r� r� r) � s zQuery.execution_optionsc K s d S r� r� r r� r� r� r) � s )�kwargsr� c K s | j �|�| _ | S )a� Set non-SQL options which take effect during execution. Options allowed here include all of those accepted by :meth:`_engine.Connection.execution_options`, as well as a series of ORM specific options: ``populate_existing=True`` - equivalent to using :meth:`_orm.Query.populate_existing` ``autoflush=True|False`` - equivalent to using :meth:`_orm.Query.autoflush` ``yield_per=<value>`` - equivalent to using :meth:`_orm.Query.yield_per` Note that the ``stream_results`` execution option is enabled automatically if the :meth:`~sqlalchemy.orm.query.Query.yield_per()` method or execution option is used. .. versionadded:: 1.4 - added ORM options to :meth:`_orm.Query.execution_options` The execution options may also be specified on a per execution basis when using :term:`2.0 style` queries via the :paramref:`_orm.Session.execution_options` parameter. .. warning:: The :paramref:`_engine.Connection.execution_options.stream_results` parameter should not be used at the level of individual ORM statement executions, as the :class:`_orm.Session` will not track objects from different schema translate maps within a single session. For multiple schema translate maps within the scope of a single :class:`_orm.Session`, see :ref:`examples_sharding`. .. seealso:: :ref:`engine_stream_results` :meth:`_query.Query.get_execution_options` :meth:`_sql.Select.execution_options` - v2 equivalent method. )r� r� )r� rs r� r� r� r) � s .)�nowait�read�of� skip_locked� key_sharez Optional[_ForUpdateOfArgument])rt ru rv rw rx r� c C s t |||||d�| _| S )a, return a new :class:`_query.Query` with the specified options for the ``FOR UPDATE`` clause. The behavior of this method is identical to that of :meth:`_expression.GenerativeSelect.with_for_update`. When called with no arguments, the resulting ``SELECT`` statement will have a ``FOR UPDATE`` clause appended. When additional arguments are specified, backend-specific options such as ``FOR UPDATE NOWAIT`` or ``LOCK IN SHARE MODE`` can take effect. E.g.:: q = ( sess.query(User) .populate_existing() .with_for_update(nowait=True, of=User) ) The above query on a PostgreSQL backend will render like: .. sourcecode:: sql SELECT users.id AS users_id FROM users FOR UPDATE OF users NOWAIT .. warning:: Using ``with_for_update`` in the context of eager loading relationships is not officially supported or recommended by SQLAlchemy and may not work with certain queries on various database backends. When ``with_for_update`` is successfully used with a query that involves :func:`_orm.joinedload`, SQLAlchemy will attempt to emit SQL that locks all involved tables. .. note:: It is generally a good idea to combine the use of the :meth:`_orm.Query.populate_existing` method when using the :meth:`_orm.Query.with_for_update` method. The purpose of :meth:`_orm.Query.populate_existing` is to force all the data read from the SELECT to be populated into the ORM objects returned, even if these objects are already in the :term:`identity map`. .. seealso:: :meth:`_expression.GenerativeSelect.with_for_update` - Core level method with full argument and behavioral description. :meth:`_orm.Query.populate_existing` - overwrites attributes of objects already loaded in the identity map. )ru rt rv rw rx )rC r� )r� rt ru rv rw rx r� r� r� r' � s ?�zQuery.with_for_updatezOptional[Dict[str, Any]])�_Query__paramsr� r� c K s |r|� |� | j�|�| _| S )a� Add values for bind parameters which may have been specified in filter(). Parameters may be specified using \**kwargs, or optionally a single dictionary as the first positional argument. The reason for both is that \**kwargs is convenient, however some parameter dictionaries contain unicode keys in which case \**kwargs cannot be used. )r� r� r� )r� ry r� r� r� r� r� 5 s z Query.paramsz _ColumnExpressionArgument[bool])� criterionr� c G s | j |� S )z�A synonym for :meth:`.Query.filter`. .. versionadded:: 1.4 .. seealso:: :meth:`_sql.Select.where` - v2 equivalent method. )r: )r� rz r� r� r� �whereG s z Query.wherec G s4 t |�D ]&}tjtj|| d�}| j|f7 _q| S )aN Apply the given filtering criterion to a copy of this :class:`_query.Query`, using SQL expressions. e.g.:: session.query(MyClass).filter(MyClass.name == "some name") Multiple criteria may be specified as comma separated; the effect is that they will be joined together using the :func:`.and_` function:: session.query(MyClass).filter(MyClass.name == "some name", MyClass.id > 5) The criterion is any SQL expression object applicable to the WHERE clause of a select. String expressions are coerced into SQL expression constructs via the :func:`_expression.text` construct. .. seealso:: :meth:`_query.Query.filter_by` - filter on keyword expressions. :meth:`_sql.Select.where` - v2 equivalent method. r> )r? r1 r� r3 �WhereHavingRoler� )r� rz �critr� r� r� r: S s �z Query.filterz=Optional[Union[_InternalEntityType[Any], _JoinTargetElement]]c C s | j rt| j �S d S d S r� )r� r r� r� r� r� rJ w s �zQuery._last_joined_entityc C s: | j r| j}|dur|S | jr0| jjs0| jd S | jd S )z�for the filter_by() method, return the target entity for which we will attempt to derive an expression from based on string name. Nr )r� rJ r� r� r� r� )r� rJ r� r� r� �_filter_by_zero� s zQuery._filter_by_zeroc s( | � � � � fdd�|�� D �}| j|� S )a Apply the given filtering criterion to a copy of this :class:`_query.Query`, using keyword expressions. e.g.:: session.query(MyClass).filter_by(name="some name") Multiple criteria may be specified as comma separated; the effect is that they will be joined together using the :func:`.and_` function:: session.query(MyClass).filter_by(name="some name", id=5) The keyword expressions are extracted from the primary entity of the query, or the last entity that was the target of a call to :meth:`_query.Query.join`. .. seealso:: :meth:`_query.Query.filter` - filter on SQL expressions. :meth:`_sql.Select.filter_by` - v2 comparable method. c s g | ]\}}t � |�|k�qS r� r9 )r� �keyr �r6 r� r� r� � s �z#Query.filter_by.<locals>.<listcomp>)r~ �itemsr: )r� rs �clausesr� r� r� � filter_by� s �zQuery.filter_byzTUnion[Literal[None, False, _NoArg.NO_ARG], _ColumnExpressionOrStrLabelArgument[Any]]z(_ColumnExpressionOrStrLabelArgument[Any])� _Query__firstr� r� c G sj | j | jfD ] }|d� q |s6|du s.|du r6d| _n0|tjurftdd� |f| D ��}| j|7 _| S )a� Apply one or more ORDER BY criteria to the query and return the newly resulting :class:`_query.Query`. e.g.:: q = session.query(Entity).order_by(Entity.id, Entity.name) Calling this method multiple times is equivalent to calling it once with all the clauses concatenated. All existing ORDER BY criteria may be cancelled by passing ``None`` by itself. New ORDER BY criteria may then be added by invoking :meth:`_orm.Query.order_by` again, e.g.:: # will erase all ORDER BY and ORDER BY new_col alone q = q.order_by(None).order_by(new_col) .. seealso:: These sections describe ORDER BY in terms of :term:`2.0 style` invocation but apply to :class:`_orm.Query` as well: :ref:`tutorial_order_by` - in the :ref:`unified_tutorial` :ref:`tutorial_order_by_label` - in the :ref:`unified_tutorial` :meth:`_sql.Select.order_by` - v2 equivalent method. r� NFr� c s s | ]}t �tj|�V qd S r� )r1 r� r3 Z OrderByRole�r� �clauser� r� r� r. � s �z!Query.order_by.<locals>.<genexpr>)r� r� r� r< �NO_ARGr� �r� r� r� Z assertionrz r� r� r� r� � s % �zQuery.order_byc G sj | j | jfD ] }|d� q |s6|du s.|du r6d| _n0|tjurftdd� |f| D ��}| j|7 _| S )a� Apply one or more GROUP BY criterion to the query and return the newly resulting :class:`_query.Query`. All existing GROUP BY settings can be suppressed by passing ``None`` - this will suppress any GROUP BY configured on mappers as well. .. seealso:: These sections describe GROUP BY in terms of :term:`2.0 style` invocation but apply to :class:`_orm.Query` as well: :ref:`tutorial_group_by_w_aggregates` - in the :ref:`unified_tutorial` :ref:`tutorial_order_by_label` - in the :ref:`unified_tutorial` :meth:`_sql.Select.group_by` - v2 equivalent method. �group_byNFr� c s s | ]}t �tj|�V qd S r� )r1 r� r3 Z GroupByRoler� r� r� r� r. $ s �z!Query.group_by.<locals>.<genexpr>)r� r� r� r< r� r� r� r� r� r� r� s �zQuery.group_by)�havingr� c G s, |D ]"}t �tj|�}| j|f7 _q| S )at Apply a HAVING criterion to the query and return the newly resulting :class:`_query.Query`. :meth:`_query.Query.having` is used in conjunction with :meth:`_query.Query.group_by`. HAVING criterion makes it possible to use filters on aggregate functions like COUNT, SUM, AVG, MAX, and MIN, eg.:: q = ( session.query(User.id) .join(User.addresses) .group_by(User.id) .having(func.count(Address.id) > 2) ) .. seealso:: :meth:`_sql.Select.having` - v2 equivalent method. )r1 r� r3 r| r� )r� r� rz Zhaving_criteriar� r� r� r� + s �z Query.having)�expr_fnr� r� c G s | f| }| � ||� �� �S r� )rC r )r� r� r� Zlist_of_queriesr� r� r� �_set_opK s z Query._set_op)r� r� c G s | j tjg|�R � S )a% Produce a UNION of this Query against one or more queries. e.g.:: q1 = sess.query(SomeClass).filter(SomeClass.foo == "bar") q2 = sess.query(SomeClass).filter(SomeClass.bar == "foo") q3 = q1.union(q2) The method accepts multiple Query objects so as to control the level of nesting. A series of ``union()`` calls such as:: x.union(y).union(z).all() will nest on each ``union()``, and produces: .. sourcecode:: sql SELECT * FROM (SELECT * FROM (SELECT * FROM X UNION SELECT * FROM y) UNION SELECT * FROM Z) Whereas:: x.union(y, z).all() produces: .. sourcecode:: sql SELECT * FROM (SELECT * FROM X UNION SELECT * FROM y UNION SELECT * FROM Z) Note that many database backends do not allow ORDER BY to be rendered on a query called within UNION, EXCEPT, etc. To disable all ORDER BY clauses including those configured on mappers, issue ``query.order_by(None)`` - the resulting :class:`_query.Query` object will not render ORDER BY within its SELECT statement. .. seealso:: :meth:`_sql.Select.union` - v2 equivalent method. )r� r2 r� �r� r� r� r� r� r� O s -z Query.unionc G s | j tjg|�R � S )a Produce a UNION ALL of this Query against one or more queries. Works the same way as :meth:`~sqlalchemy.orm.query.Query.union`. See that method for usage examples. .. seealso:: :meth:`_sql.Select.union_all` - v2 equivalent method. )r� r2 � union_allr� r� r� r� r� ~ s zQuery.union_allc G s | j tjg|�R � S )a Produce an INTERSECT of this Query against one or more queries. Works the same way as :meth:`~sqlalchemy.orm.query.Query.union`. See that method for usage examples. .. seealso:: :meth:`_sql.Select.intersect` - v2 equivalent method. )r� r2 � intersectr� r� r� r� r� � s zQuery.intersectc G s | j tjg|�R � S )a Produce an INTERSECT ALL of this Query against one or more queries. Works the same way as :meth:`~sqlalchemy.orm.query.Query.union`. See that method for usage examples. .. seealso:: :meth:`_sql.Select.intersect_all` - v2 equivalent method. )r� r2 � intersect_allr� r� r� r� r� � s zQuery.intersect_allc G s | j tjg|�R � S )a Produce an EXCEPT of this Query against one or more queries. Works the same way as :meth:`~sqlalchemy.orm.query.Query.union`. See that method for usage examples. .. seealso:: :meth:`_sql.Select.except_` - v2 equivalent method. )r� r2 �except_r� r� r� r� r� � s z Query.except_c G s | j tjg|�R � S )a Produce an EXCEPT ALL of this Query against one or more queries. Works the same way as :meth:`~sqlalchemy.orm.query.Query.union`. See that method for usage examples. .. seealso:: :meth:`_sql.Select.except_all` - v2 equivalent method. )r� r2 � except_allr� r� r� r� r� � s zQuery.except_all��isouter�fullr_ zOptional[_OnClauseArgument])�target�onclauser� r� r� c C sd t jtj|| dd�}|dur0t jtj|dd�}nd}| j||d||d�ff7 _| j�dd� | S )a Create a SQL JOIN against this :class:`_query.Query` object's criterion and apply generatively, returning the newly resulting :class:`_query.Query`. **Simple Relationship Joins** Consider a mapping between two classes ``User`` and ``Address``, with a relationship ``User.addresses`` representing a collection of ``Address`` objects associated with each ``User``. The most common usage of :meth:`_query.Query.join` is to create a JOIN along this relationship, using the ``User.addresses`` attribute as an indicator for how this should occur:: q = session.query(User).join(User.addresses) Where above, the call to :meth:`_query.Query.join` along ``User.addresses`` will result in SQL approximately equivalent to: .. sourcecode:: sql SELECT user.id, user.name FROM user JOIN address ON user.id = address.user_id In the above example we refer to ``User.addresses`` as passed to :meth:`_query.Query.join` as the "on clause", that is, it indicates how the "ON" portion of the JOIN should be constructed. To construct a chain of joins, multiple :meth:`_query.Query.join` calls may be used. The relationship-bound attribute implies both the left and right side of the join at once:: q = ( session.query(User) .join(User.orders) .join(Order.items) .join(Item.keywords) ) .. note:: as seen in the above example, **the order in which each call to the join() method occurs is important**. Query would not, for example, know how to join correctly if we were to specify ``User``, then ``Item``, then ``Order``, in our chain of joins; in such a case, depending on the arguments passed, it may raise an error that it doesn't know how to join, or it may produce invalid SQL in which case the database will raise an error. In correct practice, the :meth:`_query.Query.join` method is invoked in such a way that lines up with how we would want the JOIN clauses in SQL to be rendered, and each call should represent a clear link from what precedes it. **Joins to a Target Entity or Selectable** A second form of :meth:`_query.Query.join` allows any mapped entity or core selectable construct as a target. In this usage, :meth:`_query.Query.join` will attempt to create a JOIN along the natural foreign key relationship between two entities:: q = session.query(User).join(Address) In the above calling form, :meth:`_query.Query.join` is called upon to create the "on clause" automatically for us. This calling form will ultimately raise an error if either there are no foreign keys between the two entities, or if there are multiple foreign key linkages between the target entity and the entity or entities already present on the left side such that creating a join requires more information. Note that when indicating a join to a target without any ON clause, ORM configured relationships are not taken into account. **Joins to a Target with an ON Clause** The third calling form allows both the target entity as well as the ON clause to be passed explicitly. A example that includes a SQL expression as the ON clause is as follows:: q = session.query(User).join(Address, User.id == Address.user_id) The above form may also use a relationship-bound attribute as the ON clause as well:: q = session.query(User).join(Address, User.addresses) The above syntax can be useful for the case where we wish to join to an alias of a particular target entity. If we wanted to join to ``Address`` twice, it could be achieved using two aliases set up using the :func:`~sqlalchemy.orm.aliased` function:: a1 = aliased(Address) a2 = aliased(Address) q = ( session.query(User) .join(a1, User.addresses) .join(a2, User.addresses) .filter(a1.email_address == "ed@foo.com") .filter(a2.email_address == "ed@bar.com") ) The relationship-bound calling form can also specify a target entity using the :meth:`_orm.PropComparator.of_type` method; a query equivalent to the one above would be:: a1 = aliased(Address) a2 = aliased(Address) q = ( session.query(User) .join(User.addresses.of_type(a1)) .join(User.addresses.of_type(a2)) .filter(a1.email_address == "ed@foo.com") .filter(a2.email_address == "ed@bar.com") ) **Augmenting Built-in ON Clauses** As a substitute for providing a full custom ON condition for an existing relationship, the :meth:`_orm.PropComparator.and_` function may be applied to a relationship attribute to augment additional criteria into the ON clause; the additional criteria will be combined with the default criteria using AND:: q = session.query(User).join( User.addresses.and_(Address.email_address != "foo@bar.com") ) .. versionadded:: 1.4 **Joining to Tables and Subqueries** The target of a join may also be any table or SELECT statement, which may be related to a target entity or not. Use the appropriate ``.subquery()`` method in order to make a subquery out of a query:: subq = ( session.query(Address) .filter(Address.email_address == "ed@foo.com") .subquery() ) q = session.query(User).join(subq, User.id == subq.c.user_id) Joining to a subquery in terms of a specific relationship and/or target entity may be achieved by linking the subquery to the entity using :func:`_orm.aliased`:: subq = ( session.query(Address) .filter(Address.email_address == "ed@foo.com") .subquery() ) address_subq = aliased(Address, subq) q = session.query(User).join(User.addresses.of_type(address_subq)) **Controlling what to Join From** In cases where the left side of the current state of :class:`_query.Query` is not in line with what we want to join from, the :meth:`_query.Query.select_from` method may be used:: q = ( session.query(Address) .select_from(User) .join(User.addresses) .filter(User.name == "ed") ) Which will produce SQL similar to: .. sourcecode:: sql SELECT address.* FROM user JOIN address ON user.id=address.user_id WHERE user.name = :name_1 .. seealso:: :meth:`_sql.Select.join` - v2 equivalent method. :param \*props: Incoming arguments for :meth:`_query.Query.join`, the props collection in modern use should be considered to be a one or two argument form, either as a single "target" entity or ORM attribute-bound relationship, or as a target entity plus an "on clause" which may be a SQL expression or ORM attribute-bound relationship. :param isouter=False: If True, the join used will be a left outer join, just as if the :meth:`_query.Query.outerjoin` method were called. :param full=False: render FULL OUTER JOIN; implies ``isouter``. T)r� �legacyN�r� r� rJ )r1 r� r3 ZJoinTargetRoleZ OnClauseRoler� r� r� )r� r� r� r� r� Z join_targetZonclause_elementr� r� r� �join� s. R����� z Query.join)r� )r� r� r� r� c C s | j ||d|d�S )a# Create a left outer join against this ``Query`` object's criterion and apply generatively, returning the newly resulting ``Query``. Usage is the same as the ``join()`` method. .. seealso:: :meth:`_sql.Select.outerjoin` - v2 equivalent method. T)r� r� r� )r� )r� r� r� r� r� r� r� � outerjoin� s zQuery.outerjoinc C s d| _ | S )aS Return a new :class:`.Query`, where the "join point" has been reset back to the base FROM entities of the query. This method is usually used in conjunction with the ``aliased=True`` feature of the :meth:`~.Query.join` method. See the example in :meth:`~.Query.join` for how this is used. N)rJ r� r� r� r� �reset_joinpoint� s zQuery.reset_joinpointr6 )�from_objr� c G s | � |d� | S )a� Set the FROM clause of this :class:`.Query` explicitly. :meth:`.Query.select_from` is often used in conjunction with :meth:`.Query.join` in order to control which entity is selected from on the "left" side of the join. The entity or selectable object here effectively replaces the "left edge" of any calls to :meth:`~.Query.join`, when no joinpoint is otherwise established - usually, the default "join point" is the leftmost entity in the :class:`~.Query` object's list of entities to be selected. A typical example:: q = ( session.query(Address) .select_from(User) .join(User.addresses) .filter(User.name == "ed") ) Which produces SQL equivalent to: .. sourcecode:: sql SELECT address.* FROM user JOIN address ON user.id=address.user_id WHERE user.name = :name_1 :param \*from_obj: collection of one or more entities to apply to the FROM clause. Entities can be mapped classes, :class:`.AliasedClass` objects, :class:`.Mapper` objects as well as core :class:`.FromClause` elements like subqueries. .. seealso:: :meth:`~.Query.join` :meth:`.Query.select_entity_from` :meth:`_sql.Select.select_from` - v2 equivalent method. F)r� )r� r� r� r� r� � select_from� s / zQuery.select_from)�itemr� c C s t �| |�S r� )�orm_util�_getitem)r� r� r� r� r� � __getitem__ s �zQuery.__getitem__)�start�stopr� c C s t �| j| j||�\| _| _| S )aL Computes the "slice" of the :class:`_query.Query` represented by the given indices and returns the resulting :class:`_query.Query`. The start and stop indices behave like the argument to Python's built-in :func:`range` function. This method provides an alternative to using ``LIMIT``/``OFFSET`` to get a slice of the query. For example, :: session.query(User).order_by(User.id).slice(1, 3) renders as .. sourcecode:: sql SELECT users.id AS users_id, users.name AS users_name FROM users ORDER BY users.id LIMIT ? OFFSET ? (2, 1) .. seealso:: :meth:`_query.Query.limit` :meth:`_query.Query.offset` :meth:`_sql.Select.slice` - v2 equivalent method. )�sql_utilZ _make_slicer� r� )r� r� r� r� r� r� �slice s ' � z Query.slicer` )�limitr� c C s t �|�| _| S )z�Apply a ``LIMIT`` to the query and return the newly resulting ``Query``. .. seealso:: :meth:`_sql.Select.limit` - v2 equivalent method. )r� �_offset_or_limit_clauser� )r� r� r� r� r� r� 3 s z Query.limit)�offsetr� c C s t �|�| _| S )z�Apply an ``OFFSET`` to the query and return the newly resulting ``Query``. .. seealso:: :meth:`_sql.Select.offset` - v2 equivalent method. )r� r� r� )r� r� r� r� r� r� A s z Query.offset)�exprr� c G s0 |r&d| _ | jtdd� |D �� | _nd| _ | S )aU Apply a ``DISTINCT`` to the query and return the newly resulting ``Query``. .. note:: The ORM-level :meth:`.distinct` call includes logic that will automatically add columns from the ORDER BY of the query to the columns clause of the SELECT statement, to satisfy the common need of the database backend that ORDER BY columns be part of the SELECT list when DISTINCT is used. These columns *are not* added to the list of columns actually fetched by the :class:`_query.Query`, however, so would not affect results. The columns are passed through when using the :attr:`_query.Query.statement` accessor, however. .. deprecated:: 2.0 This logic is deprecated and will be removed in SQLAlchemy 2.0. See :ref:`migration_20_query_distinct` for a description of this use case in 2.0. .. seealso:: :meth:`_sql.Select.distinct` - v2 equivalent method. :param \*expr: optional column expressions. When present, the PostgreSQL dialect will render a ``DISTINCT ON (<expressions>)`` construct. .. deprecated:: 1.4 Using \*expr in other dialects is deprecated and will raise :class:`_exc.CompileError` in a future version. Tc s s | ]}t �tj|�V qd S r� )r1 r� r3 ZByOfRole)r� �er� r� r� r. s s z!Query.distinct.<locals>.<genexpr>)r� r� r� )r� r� r� r� r� r� N s # �zQuery.distinctzList[_T]c C s | � � �� S )a� Return the results represented by this :class:`_query.Query` as a list. This results in an execution of the underlying SQL statement. .. warning:: The :class:`_query.Query` object, when asked to return either a sequence or iterator that consists of full ORM-mapped entities, will **deduplicate entries based on primary key**. See the FAQ for more details. .. seealso:: :ref:`faq_query_deduplicating` .. seealso:: :meth:`_engine.Result.all` - v2 comparable method. :meth:`_engine.Result.scalars` - v2 comparable method. )�_iter�allr� r� r� r� r� z s z Query.allry )r� r� c C s t jtj|| d�}|| _| S )a Execute the given SELECT statement and return results. This method bypasses all internal statement compilation, and the statement is executed without modification. The statement is typically either a :func:`_expression.text` or :func:`_expression.select` construct, and should return the set of columns appropriate to the entity class represented by this :class:`_query.Query`. .. seealso:: :meth:`_sql.Select.from_statement` - v2 comparable method. r> )r1 r� r3 ZSelectStatementRoler� )r� r� r� r� r� �from_statement� s �zQuery.from_statementz Optional[_T]c C s, | j dur| �� �� S | �d��� �� S dS )a� Return the first result of this ``Query`` or None if the result doesn't contain any row. first() applies a limit of one within the generated SQL, so that only one primary entity row is generated on the server side (note this may consist of multiple result rows if join-loaded collections are present). Calling :meth:`_query.Query.first` results in an execution of the underlying query. .. seealso:: :meth:`_query.Query.one` :meth:`_query.Query.one_or_none` :meth:`_engine.Result.first` - v2 comparable method. :meth:`_engine.Result.scalars` - v2 comparable method. Nr )r� r� �firstr� r� r� r� r� r� � s z Query.firstc C s | � � �� S )a� Return at most one result or raise an exception. Returns ``None`` if the query selects no rows. Raises ``sqlalchemy.orm.exc.MultipleResultsFound`` if multiple object identities are returned, or if multiple rows are returned for a query that returns only scalar values as opposed to full identity-mapped entities. Calling :meth:`_query.Query.one_or_none` results in an execution of the underlying query. .. seealso:: :meth:`_query.Query.first` :meth:`_query.Query.one` :meth:`_engine.Result.one_or_none` - v2 comparable method. :meth:`_engine.Result.scalar_one_or_none` - v2 comparable method. )r� � one_or_noner� r� r� r� r� � s zQuery.one_or_noner~ c C s | � � �� S )a� Return exactly one result or raise an exception. Raises :class:`_exc.NoResultFound` if the query selects no rows. Raises :class:`_exc.MultipleResultsFound` if multiple object identities are returned, or if multiple rows are returned for a query that returns only scalar values as opposed to full identity-mapped entities. Calling :meth:`.one` results in an execution of the underlying query. .. seealso:: :meth:`_query.Query.first` :meth:`_query.Query.one_or_none` :meth:`_engine.Result.one` - v2 comparable method. :meth:`_engine.Result.scalar_one` - v2 comparable method. )r� �oner� r� r� r� r� � s z Query.onec C s@ z$| � � }t|tj�s |W S |d W S tjy: Y dS 0 dS )a� Return the first element of the first result or None if no rows present. If multiple rows are returned, raises :class:`_exc.MultipleResultsFound`. >>> session.query(Item).scalar() <Item> >>> session.query(Item.id).scalar() 1 >>> session.query(Item.id).filter(Item.id < 0).scalar() None >>> session.query(Item.id, Item.name).scalar() 1 >>> session.query(func.count(Parent.id)).scalar() 20 This results in an execution of the underlying query. .. seealso:: :meth:`_engine.Result.scalar` - v2 comparable method. r N)r� r �collections_abcr r� Z NoResultFound)r� �retr� r� r� �scalar� s z Query.scalarz Iterator[_T]c c s8 | � � }z|E d H W n ty2 |�� � Y n0 d S r� )r� � GeneratorExitZ _soft_close)r� �resultr� r� r� �__iter__ s zQuery.__iter__z#Union[ScalarResult[_T], Result[_T]]c C sd | j }| �� }| jj||d| jid�}|j�dd�rBtd|��� }|j�dd�r`| jj s`|� � }|S )NZ_sa_orm_load_options�r) r Fz Result[_T]�filtered) r� r� r� �executer� � _attributesr� r �scalarsr! �unique)r� r� r� r� r� r� r� r� $ s � ��z Query._iterc C sN | � � }z | jr | �|| jj�nd }W n tjy> d }Y n0 t|�|��S r� )r� r� �_get_bind_argsZget_bindr� ZUnboundExecutionErrorr� �compile)r� r� �bindr� r� r� �__str__; s �� z Query.__str__)r� r� r� r� c K s |f d|i|��S )Nr� r� )r� r� r� r� r� r� r� r� I s zQuery._get_bind_argszList[ORMColumnDescription]c C s t | dd�S )a� Return metadata about the columns which would be returned by this :class:`_query.Query`. Format is a list of dictionaries:: user_alias = aliased(User, name="user2") q = sess.query(User, User.id, user_alias) # this expression: q.column_descriptions # would return: [ { "name": "User", "type": User, "aliased": False, "expr": User, "entity": User, }, { "name": "id", "type": Integer(), "aliased": False, "expr": User.id, "entity": User, }, { "name": "user2", "type": User, "aliased": True, "expr": user_alias, "entity": user_alias, }, ] .. seealso:: This API is available using :term:`2.0 style` queries as well, documented at: * :ref:`queryguide_inspection` * :attr:`.Select.column_descriptions` Tr� r r� r� r� r� �column_descriptionsL s 1zQuery.column_descriptionsz2.0z�The :meth:`_orm.Query.instances` method is deprecated and will be removed in a future release. Use the Select.from_statement() method or aliased() construct in conjunction with Session.execute() instead.zCursorResult[Any]zOptional[QueryContext])� result_proxy�contextr� c C sz |du r>t jddd� | jdd�}t||j|j| j| j| j�}t� ||�}|j � dd�r`|� � }|j � dd�rv|� � }|S ) zhReturn an ORM result given a :class:`_engine.CursorResult` and :class:`.QueryContext`. Nz�Using the Query.instances() method without a context is deprecated and will be disallowed in a future release. Please make use of :meth:`_query.Query.from_statement` for linking ORM results to arbitrary select constructs.r )�versionFr� r r� )r Zwarn_deprecatedr� r! r� r� r� r� r � instancesr� r� r� r� )r� r� r� � compile_stater� r� r� r� r� s( � � zQuery.instancesz :meth:`_orm.Query.merge_result`zJThe method is superseded by the :func:`_orm.merge_frozen_result` function.)r Zenable_warningszCUnion[FrozenResult[Any], Iterable[Sequence[Any]], Iterable[object]]z'Union[FrozenResult[Any], Iterable[Any]])�iterator�loadr� c C s t �| ||�S )ak Merge a result into this :class:`_query.Query` object's Session. Given an iterator returned by a :class:`_query.Query` of the same structure as this one, return an identical iterator of results, with all mapped instances merged into the session using :meth:`.Session.merge`. This is an optimized method which will merge all mapped instances, preserving the structure of the result rows and unmapped columns with less method overhead than that of calling :meth:`.Session.merge` explicitly for each value. The structure of the results is determined based on the column list of this :class:`_query.Query` - if these do not correspond, unchecked errors will occur. The 'load' argument is the same as that of :meth:`.Session.merge`. For an example of how :meth:`_query.Query.merge_result` is used, see the source code for the example :ref:`examples_caching`, where :meth:`_query.Query.merge_result` is used to efficiently restore state from a cache back into a target :class:`.Session`. )r � merge_result)r� r� r� r� r� r� r� � s &zQuery.merge_resultr@ c C sJ | � d��t�d���t��� �d�}| �� }|dur@|� |�}t� |�S )a� A convenience method that turns a query into an EXISTS subquery of the form EXISTS (SELECT 1 FROM ... WHERE ...). e.g.:: q = session.query(User).filter(User.name == "fred") session.query(q.exists()) Producing SQL similar to: .. sourcecode:: sql SELECT EXISTS ( SELECT 1 FROM users WHERE users.name = :name_1 ) AS anon_1 The EXISTS construct is usually used in the WHERE clause:: session.query(User.id).filter(q.exists()).scalar() Note that some databases such as SQL Server don't allow an EXISTS expression to be present in the columns clause of a SELECT. To select a simple boolean value based on the exists as a WHERE, use :func:`.literal`:: from sqlalchemy import literal session.query(literal(True)).filter(q.exists()).scalar() .. seealso:: :meth:`_sql.Select.exists` - v2 comparable method. F�1r N) r� rd r, �literal_columnr rG r� Zwith_only_columnsr� r� �exists)r� �innerZezeror� r� r� r� � s + ���� z Query.existsc C s& t j�t �d��}| �|��d��� S )a� Return a count of rows this the SQL formed by this :class:`Query` would return. This generates the SQL for this Query as follows: .. sourcecode:: sql SELECT count(1) AS count_1 FROM ( SELECT <rest of query follows...> ) AS anon_1 The above SQL returns a single row, which is the aggregate value of the count function; the :meth:`_query.Query.count` method then returns that single integer value. .. warning:: It is important to note that the value returned by count() is **not the same as the number of ORM objects that this Query would return from a method such as the .all() method**. The :class:`_query.Query` object, when asked to return full entities, will **deduplicate entries based on primary key**, meaning if the same primary key value would appear in the results more than once, only one object of that primary key would be present. This does not apply to a query that is against individual columns. .. seealso:: :ref:`faq_query_deduplicating` For fine grained control over specific columns to count, to skip the usage of a subquery or otherwise control of the FROM clause, or to use other aggregate functions, use :attr:`~sqlalchemy.sql.expression.func` expressions in conjunction with :meth:`~.Session.query`, i.e.:: from sqlalchemy import func # count User records, without # using a subquery. session.query(func.count(User.id)) # return count of user "id" grouped # by "name" session.query(func.count(User.id)).group_by(User.name) from sqlalchemy import distinct # count distinct "name" values session.query(func.count(distinct(User.name))) .. seealso:: :ref:`migration_20_query_usage` �*F)r, �funcr r� rE r� r� )r� �colr� r� r� r s :�z Query.count�autorN �Optional[Dict[Any, Any]])�synchronize_session� delete_argsr� c C s� t | |�}| jjr@| jjD ]$}||j|�}|dur8||_|j} qtj| j� }|r`|jf i |��}| j|_| j j || j | j � d|i�d�}||_| j j�|� |�� |jS )a Perform a DELETE with an arbitrary WHERE clause. Deletes rows matched by this query from the database. E.g.:: sess.query(User).filter(User.age == 25).delete(synchronize_session=False) sess.query(User).filter(User.age == 25).delete( synchronize_session="evaluate" ) .. warning:: See the section :ref:`orm_expression_update_delete` for important caveats and warnings, including limitations when using bulk UPDATE and DELETE with mapper inheritance configurations. :param synchronize_session: chooses the strategy to update the attributes on objects in the session. See the section :ref:`orm_expression_update_delete` for a discussion of these strategies. :param delete_args: Optional dictionary, if present will be passed to the underlying :func:`_expression.delete` construct as the ``**kw`` for the object. May be used to pass dialect-specific arguments such as ``mysql_limit``. .. versionadded:: 2.0.37 :return: the count of rows matched as returned by the database's "row count" feature. .. seealso:: :ref:`orm_expression_update_delete` Nr� r� )� BulkDeleter� Zbefore_compile_delete�queryr, �deleter� �with_dialect_optionsr� r� r� r� r� r� r� Zafter_bulk_delete�close�rowcount)r� r� r� Zbulk_delr� r� Zdelete_r� r� r� r� r� M s, , ��z Query.delete� Dict[_DMLColumnArgument, Any])r� r� � update_argsr� c C s� |pi }t | ||�}| jjrJ| jjD ] }||j|�}|dur$||_q$|j} tj| j� }|�dd�}|rr|j|� }n |� |�}|r�|j f i |��}| j |_ | j j || j| j�d|i�d�} | |_| j j�|� | �� | jS )a� Perform an UPDATE with an arbitrary WHERE clause. Updates rows matched by this query in the database. E.g.:: sess.query(User).filter(User.age == 25).update( {User.age: User.age - 10}, synchronize_session=False ) sess.query(User).filter(User.age == 25).update( {"age": User.age - 10}, synchronize_session="evaluate" ) .. warning:: See the section :ref:`orm_expression_update_delete` for important caveats and warnings, including limitations when using arbitrary UPDATE and DELETE with mapper inheritance configurations. :param values: a dictionary with attributes names, or alternatively mapped attributes or SQL expressions, as keys, and literal values or sql expressions as values. If :ref:`parameter-ordered mode <tutorial_parameter_ordered_updates>` is desired, the values can be passed as a list of 2-tuples; this requires that the :paramref:`~sqlalchemy.sql.expression.update.preserve_parameter_order` flag is passed to the :paramref:`.Query.update.update_args` dictionary as well. :param synchronize_session: chooses the strategy to update the attributes on objects in the session. See the section :ref:`orm_expression_update_delete` for a discussion of these strategies. :param update_args: Optional dictionary, if present will be passed to the underlying :func:`_expression.update` construct as the ``**kw`` for the object. May be used to pass dialect-specific arguments such as ``mysql_limit``, as well as other special arguments such as :paramref:`~sqlalchemy.sql.expression.update.preserve_parameter_order`. :return: the count of rows matched as returned by the database's "row count" feature. .. seealso:: :ref:`orm_expression_update_delete` NZpreserve_parameter_orderFr� r� )� BulkUpdater� Zbefore_compile_updater� r, r� r� r� Zordered_valuesr� r� r� r� r� r� r� r� r� Zafter_bulk_updater� r� ) r� r� r� r� Zbulk_udr� r� ZupdZppor� r� r� r� r� � s6 8 ��z Query.updater )r� r� r� c K sF | j f d|i|��}||jjks$J �ttt�|d��}|j|ddd�S )a� Create an out-of-compiler ORMCompileState object. The ORMCompileState object is normally created directly as a result of the SQLCompiler.process() method being handed a Select() or FromStatement() object that uses the "orm" plugin. This method provides a means of creating this ORMCompileState object directly without using the compiler. This method is used only for deprecated cases, which include the .from_self() method for a Query that has multiple levels of .from_self() in use, as well as the instances() method. It is also used within the test suite to generate ORMCompileState objects for test purposes. r� r� TN)�toplevel�compiler)r� r� r� r r Z _get_plugin_class_for_pluginZ_create_orm_context)r� r� r� r� Zcompile_state_clsr� r� r� r� � s ��zQuery._compile_stater! )r� r� c C s, | j |d�}t||j|j| j| j| j�}|S )Nr� )r� r! r� r� r� r� )r� r� r� r� r� r� r� �_compile_context s � zQuery._compile_context)N)TT)TT)NNNNN)T)FT)NFF)NFF)N)NN)N)T)N)N)N)N)T)r� N)r� N)F)F)�r8 � __module__� __qualname__�__doc__r� �__annotations__r� r� r� r� r� r� r� r� r� r� r� r� rH ZLABEL_STYLE_LEGACY_ORMr� rK r Zdefault_compile_optionsr� r! Zdefault_load_optionsr� r r� r� r� r� Zmemoized_propertyr� r� r� r� r� r� r� r� r; r� r� r� r� r� r� r� r� r5 r� r� r� r� r� r� r� r r r r r � deprecatedr r r r� r r� r Zbecame_legacy_20r� Z apply_labelsr r r r r r" r� r$ r+ r r/ r1 r� r2 Zpreload_moduler& rA rB rE rH rC r� Z_valuesrO r rW rd re r( rh ri r) r' r� r{ r r: rJ r~ r� r< r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r r� r� r� r� r� r� r� r� r} � s� � � �* �� � *�6 �/ �?� � & �W�% � �E��� � $(, 0 4 8*� �<0�(G� " *!� 2� * / ��* o��$ 0 * * 2� � (� � "8A � K �"[� #c @ s: e Zd ZdZe�dd�dd�dd��Zdd d �d d �Zd S )� AliasOptionFr z�The :class:`.AliasOption` object is not necessary for entities to be matched up to a query that is established via :meth:`.Query.from_statement` and now does nothing.zUnion[Alias, Subquery])r= c C s dS )z�Return a :class:`.MapperOption` that will indicate to the :class:`_query.Query` that the main table has been aliased. Nr� )r� r= r� r� r� r� # s zAliasOption.__init__r r� )r� r� c C s d S r� r� )r� r� r� r� r� �process_compile_state0 s z!AliasOption.process_compile_stateN)r8 r� r� Z inherit_cacher r� r� r� r� r� r� r� r� s �r� c @ s> e Zd ZdZdd�dd�Zdd�dd �Zed d�d d ��Zd S )�BulkUDzrState used for the orm.Query version of update() / delete(). This object is now specific to Query only. r )r� c C s$ |� d�| _| �� | j�� | _d S )NF)r� r� �_validate_query_stater� r* )r� r� r� r� r� r� ; s zBulkUD.__init__r� r� c C s� ddd t jfddd t jfdddt jfdd dt jfd d d t jfd ddt jfdddt jffD ].\}}}}|t| j|�|�sXt�d|f ��qXd S )Nr� zlimit()r� zoffset()r� z order_by()r� r� z group_by()r� z distinct()Fr� z2join(), outerjoin(), select_from(), or from_self()r� zCCan't call Query.update() or Query.delete() when %s has been called)�operator�is_�eq�getattrr� r� r� )r� rM r� Znotset�opr� r� r� r� @ s, �����z BulkUD._validate_query_staterR c C s | j jS r� )r� r� r� r� r� r� r� Z s zBulkUD.sessionN)r8 r� r� r� r� r� r5 r� r� r� r� r� r� 4 s r� c s* e Zd ZdZdddd�� fdd� Z� ZS )r� z BulkUD which handles UPDATEs.r r� r� )r� r� � update_kwargsc s t � �|� || _|| _d S r� )�superr� r� r� )r� r� r� r� �r9 r� r� r� b s zBulkUpdate.__init__�r8 r� r� r� r� � __classcell__r� r� r� r� r� _ s r� c s( e Zd ZdZddd�� fdd� Z� ZS )r� z BulkUD which handles DELETEs.r r� )r� � delete_kwargsc s t � �|� || _d S r� )r� r� r� )r� r� r� r� r� r� r� p s zBulkDelete.__init__r� r� r� r� r� r� m s r� c @ s e Zd Zerdd�dd�ZdS )�RowReturningQueryz Query[_TP]r� c C s d S r� r� r� r� r� r� r� | s zRowReturningQuery.tuplesN)r8 r� r� r r� r� r� r� r� r� y s r� )�r� � __future__r �collections.abc�abcr� r� �typingr r r r r r r r r r r r r r r r r � r r r r r� Z_typingr �baser r� r r r r r r! r" r# r$ r% r& r( r� r) r* r+ r, Zenginer- r. �eventr/ r0 r1 r2 r3 r4 r� r5 Z sql._typingr6 r7 Zsql.annotationr8 Zsql.baser: r; r< r= r> Z sql.elementsr? Zsql.expressionr@ Zsql.selectablerA rB rC rD rE rF rG rH Z util.typingrI rJ rK rL rM rN r* rO Z path_registryrP r� rQ rR r� rS Z engine.cursorrT Zengine.interfacesrU rV rW rX Z engine.resultrY rZ r[ r\ r] r^ r_ r` ra rb rc rd re rf rg rh ri rj rk rl rm rn Z_TCCAro rp Zsql.dmlrq rr rs rt ru rv rw rx ry rz r{ r| �__all__r~ Z_self_inspectsZ class_loggerZ Identifiedr} Z LoaderOptionr� r� r� r� r� r� r� r� r� �<module> sT � + sqlalchemy/orm/__pycache__/loading.cpython-39.pyc 0000644 00000071554 15125143220 0015770 0 ustar 00 a ��Jh�� � @ s� d Z ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z dd lm Z dd lm Z dd lm Z dd lm Z dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z ddl m Z ddl m Z ddlmZ dd lm Z dd l!m"Z" dd l#m$Z$ dd l#m%Z% dd l#m&Z& dd!l'm(Z( dd l'm Z) dd"l*m+Z+ dd#l*m,Z, dd$l*m-Z- dd%l m.Z. e �r>dd&l/m0Z0 dd'lm1Z1 dd(l2m3Z3 dd)l4m5Z5 dd*l6m7Z7 dd+l8m9Z9 dd,l:m;Z; dd-l<m=Z= dd.l>m?Z? dd/l#m@Z@ dd0l'mAZA e d1ed2�ZBe d3eCd2�ZDe �E� ZFeeGee eGef f ZHd4d5d6d7�d8d9�ZIe �Jd:�dzd<d=��ZKe jLd>d?d@�e �Jd:�d{dAdBdCdDdE�dFdG���ZMdHdIdJdKdLdM�dNdO�ZNdPdPdPdPdQe j.e j.dQdQdR� dHdSdTdUdVdWdXdCdYdZdCdCd[� d\d]�ZOdPdPdPdPdPdQe j.e j.dQdQd^� dHdSd_dUdVdWdXd`dCdYdZdCdCda� dbdc�ZPd|ddde�ZQd}dfdg�ZRdhdi� ZSd~djdk�ZTdldm� ZUdndo� ZVdpdq� ZWdrds� ZXdtdu� ZYG dvdw� dw�ZZdxdy� Z[dPS )z�private module containing functions used to convert database rows into object instances and associated state. the functions here are called primarily by Query, Mapper, as well as some of the attribute loading strategies. � )� annotations)�Any)�Dict)�Iterable)�List)�Mapping)�Optional)�Sequence)�Tuple)� TYPE_CHECKING)�TypeVar)�Union� )� attributes)�exc)� path_registry)�_DEFER_FOR_STATE)�_RAISE_FOR_STATE)�_SET_DEFERRED_EXPIRED)� PassiveFlag)� FromStatement)�ORMCompileState)� QueryContext)� _none_set)� state_str� )�util)� result_tuple)�ChunkedIteratorResult)� FrozenResult)�SimpleResultMetaData)�select)� ForUpdateArg)� LABEL_STYLE_TABLENAME_PLUS_COL)� SelectState)� EMPTY_DICT)�_IdentityKeyType)�LoaderCallableStatus)� ORMOption)�Mapper)�Query)�Session)� InstanceState)� CursorResult)�_ExecuteOptions)�Result)�Select�_T)�bound�_OzCursorResult[Any]r z Result[Any])�cursor�context�returnc s� t � �_�jr d��jj�_n d�i �_�j}|j}�jj oVt|j �dkoV|j d j �zFt t ��fdd��jj D �� �\�}}�j r��js��jr�t�d��W nB ty� t�� � ��� W d � n1 s�0 Y Y n0 d d � � ddd �d d ��� ��fdd��jj D �}t|||d�}�����fdd�}�j�dd��r^t |d����fdd�}t||���jjd�} | j � t |�d��| _ �jj �r�dd� } d| f| _ �j �r�| � �j � | S )a� Return a :class:`.Result` given an ORM query context. :param cursor: a :class:`.CursorResult`, generated by a statement which came from :class:`.ORMCompileState` :param context: a :class:`.QueryContext` object :return: a :class:`.Result` object representing ORM results .. versionchanged:: 1.4 The instances() function now uses :class:`.Result` objects and has an all new interface. FTr r c s g | ]}|� � ���qS � )Z row_processor)�.0� query_entity)r5 r4 r7 �K/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/loading.py� <listcomp>q s �z instances.<locals>.<listcomp>z�Can't use yield_per with eager loaders that require uniquing or row buffering, e.g. joinedload() against collections or subqueryload(). Consider the selectinload() strategy for better flexibility in loading objects.Nc S s t �d��d S )Nz@Can't use the ORM yield_per feature in conjunction with unique()��sa_exc�InvalidRequestError)�entryr7 r7 r: � _no_unique� s �z instances.<locals>._no_unique��legacy� uncertainc s6 |s��fdd�}|S �s t S d� � fdd�}|S d S )Nc s@ �r z t | �W S Y n0 t�d� �d�r0dnd� d���d S )Nz=Can't apply uniqueness to row tuple containing value of type z; z the values returned appear to bezthis datatype producesz non-hashable values)�hashr= r> ��obj)�datatyperC r7 r: �go� s ����z,instances.<locals>._not_hashable.<locals>.goFc s( � s z t | �W S Y n0 d� t| �S )NT)rD �idrE )�_use_idr7 r: rH � s )rI )rG rB rC rH r7 )rJ rG rC r: � _not_hashable� s z instances.<locals>._not_hashablec sN g | ]F}�j r� n6|js<|js$|jr<�|jj�jj|jd �n |jrFtnd�qS )rA N) � yield_perZuse_id_for_hashZ_non_hashable_valueZ_null_column_type�column�type� load_optionsZ_legacy_uniquingrI �r8 �ent)r@ rK r5 r7 r: r; � s �� ���� )Z_unique_filtersc 3 s� | }i �_ |r ��|�}|s(q�n��� }�rH�d � � fdd�|D �}n�fdd�|D �}�r�|rpt�j�� �}�jr�t�j�� �}�j�� |D ]\}}|��|� q�qp|rĈj�� �j�|� |V |s q�q d S )Nr c s g | ] }� |��qS r7 r7 )r8 �row��procr7 r: r; � � z-instances.<locals>.chunks.<locals>.<listcomp>c s" g | ]� t � fd d��D ���qS )c s g | ] }|� ��qS r7 r7 )r8 rT �rR r7 r: r; � rU z8instances.<locals>.chunks.<locals>.<listcomp>.<listcomp>)�tuple)r8 )�processrV r: r; � s ) �partialsZ fetchmanyZ _raw_all_rows�list�post_load_paths�items�clear�invoke�update)�sizerL �fetch�rowsZtop_level_post_loadsZ post_loads�path� post_load)r5 r4 � is_top_levelrX � single_entityrS r: �chunks� s: � � zinstances.<locals>.chunksZprebuffer_rowsc s t � �S �N)�iter)r` )� _prebufferedr7 r: rg s )Zsource_supports_scalars�rawZdynamic_yield_per)�filteredZis_single_entityc S s t �d��d S )Nz~The unique() method must be invoked on this Result, as it contains results that include joined eager loads against collectionsr< rE r7 r7 r: �require_unique s �z!instances.<locals>.require_unique)!� _new_runid�runidZtop_level_contextr[ � compile_stateZ_has_mapper_entitiesrO Z_only_return_tuples�len� _entitiesZsupports_single_entityrZ �ziprL Zloaders_require_bufferingZloaders_require_uniquingr= r> � Exceptionr Z safe_reraise�closer �execution_options�getr r5 Z_is_server_side� _attributes�union�dictZmulti_row_eager_loadersZ_unique_filter_state) r4 r5 rp rl �labels�extraZunique_filtersZ row_metadatarg �resultrm r7 )r@ rK rj r5 r4 re rX rf r: � instancesN sx � � ��� ��� ,+��2 � � r~ zsqlalchemy.orm.contextTc s� t jj� |r| �� � jj|dd�}| j}z�d| _� fdd�t|j�D �}dd� |jD �}t |dd� |jD ��}g } |� � D ]T} |D ]<} | | dur�| j t � | | �t �| | �|i i d�| | < q�| �|| �� q||�| �W || _S || _0 dS ) az Merge a :class:`_engine.FrozenResult` back into a :class:`_orm.Session`, returning a new :class:`_engine.Result` object with :term:`persistent` objects. See the section :ref:`do_orm_execute_re_executing` for an example. .. seealso:: :ref:`do_orm_execute_re_executing` :meth:`_engine.Result.freeze` :class:`_engine.FrozenResult` F�rB c s g | ]\}}t |� j�r|�qS r7 �� isinstance� _MapperEntity�r8 �i�e�� querycontextr7 r: r; I s �z'merge_frozen_result.<locals>.<listcomp>c S s g | ] }|j �qS r7 �Z _label_namerP r7 r7 r: r; N rU c S s g | ] }|j �qS r7 �Z_extra_entitiesrP r7 r7 r: r; Q rU N��load� _recursiveZ_resolve_conflict_map)r � preloaded� orm_context� _autoflush�ORMSelectCompileState�_create_entities_collection� autoflush� enumeraterr r Z rewrite_rows�_merger �instance_state� instance_dict�append� with_new_rows) �session� statement� frozen_resultr� �ctxr� �mapped_entities�keys� keyed_tupler} �newrowr� r7 r� r: �merge_frozen_result+ s@ � �� � �r� z:func:`_orm.merge_result`zyThe function as well as the method on :class:`_orm.Query` is superseded by the :func:`_orm.merge_frozen_result` function.)� alternativez Query[Any]z>Union[FrozenResult, Iterable[Sequence[Any]], Iterable[object]]�boolz"Union[FrozenResult, Iterable[Any]])�query�iteratorr� r6 c s� t jj�| j�� r��� t|t�r4|}t|j�}nd}�j j | dd�}�j }�z&d�_ | ojt |j �dk}|r�t|j d �j�r�� �fdd�|D �}nt|�}n��fd d�t|j �D �}g }d d� |j D �} t| d d� |j D ��} |D ]\} t| �} |D ]<} | | dur��jt�| | �t�| | �� i i d �| | < q�|�| | �� q�|�r^|�|�W |�_ S t|�W |�_ S W |�_ n|�_ 0 dS ) z�Merge a result into the given :class:`.Query` object's Session. See :meth:`_orm.Query.merge_result` for top-level documentation on this function. NTr Fr r c s, g | ]$}�j t�|�t�|�� i i d ��qS )r� )r� r r� r� )r8 �instance)r� r� r7 r: r; � s ��z merge_result.<locals>.<listcomp>c s g | ]\}}t |� j�r|�qS r7 r� r� r� r7 r: r; � s �c S s g | ] }|j �qS r7 r� rP r7 r7 r: r; � rU c S s g | ] }|j �qS r7 r� rP r7 r7 r: r; � rU r� )r r� r� r� r� r� r ri �datar� r� r� rq rr r� rZ r� r r� r r� r� r� r� )r� r� r� r� r� r� rf r} r� r� r� rR r� r� r7 )r� r� r� r: � merge_resultg sb � � �� � ��r� r+ z Mapper[_O]z_IdentityKeyType[_O]r z)Union[LoaderCallableStatus, Optional[_O]])r� �mapper�key�passiver6 c C s� | j �|�}|dur�t�|�}|jr6|j�|�s6tjS |jr�|tj @ sLtj S |tj @ sZ|S z|� ||� W n" t jy� | �|g� Y dS 0 |S dS dS )zqLook up the given key in the given session's identity map, check the object for expired state if found. N)� identity_maprw r r� �inheritsr� �isaZPASSIVE_CLASS_MISMATCHZexpiredZSQL_OKZPASSIVE_NO_RESULTZRELATED_OBJECT_OKZ _load_expired�orm_exc�ObjectDeletedErrorZ_remove_newly_deleted)r� r� r� r� r� �stater7 r7 r: �get_from_identity� s" r� NF) rO � refresh_state�with_for_update�only_load_props� no_autoflush�bind_argumentsrv �require_pk_cols�is_user_refreshz Union[Select, FromStatement]zOptional[_IdentityKeyType]z Optional[Sequence[ORMOption]]z Optional[InstanceState[Any]]zOptional[ForUpdateArg]zOptional[Iterable[str]]zMapping[str, Any]r. ) r� r� r� rO r� r� r� r� r� rv r� r� c C sD |dur|d } |d } nd } } t | || ||||| ||| | | d� S )z.Load the given identity key from the database.Nr r � rO r� r� r� �identity_tokenr� r� rv r� r� )�load_on_pk_identity)r� r� r� rO r� r� r� r� r� rv r� r� �identr� r7 r7 r: � load_on_ident� s& �r� r� zOptional[Tuple[Any, ...]]z Optional[Any]) r� r� �primary_key_identityrO r� r� r� r� r� r� rv r� r� c sJ |} | � � }|jrJ �|du r$tj}|jtju r8tj}n|j}|dur�| j d }|j \}� d|v r�� fdd�t |j |�D �}t �||�}t|�t|�kr�t�d� t �|ddi�f|_� fdd �t ||j �D �}nd}|dur�d}||_n | jdu�rd}| j|_nd }| �r�|�r���s$t�d ���jj}�fd d�|�|�D �}|�rdt�d |� d�j� d����jj}|D ]"}|| j �rp|� |�} �q��qp��r��j �r�|d�j j i7 }|j!�j � }t"||||�|| d�\}}||_d|_#|�r�|dd i7 }tj$�%| d|i�} | j&||| | d��'� �(� }z |�)� W S t*j+�yD Y dS 0 dS )z6Load the given primary key identity from the database.NZplugin_subjectc s" h | ]\}}|d u r� | j �qS rh �r� )r8 �col�value�� _get_paramsr7 r: � <setcomp>8 s �z&load_on_pk_identity.<locals>.<setcomp>zofully NULL primary key identity cannot load any object. This condition may raise an error in a future release.Z _orm_adaptTc s i | ]\}}� | j |�qS r7 r� )r8 Zid_val� primary_keyr� r7 r: � <dictcomp>K s �z'load_on_pk_identity.<locals>.<dictcomp>Fz9refresh_state is required when require_pk_cols is presentc s h | ]}� j | j�� r|�qS r7 )�attrs�history� has_changes)r8 r� )r� r7 r: r� d s �z7Please flush pending primary key changes on attributes z for mapper z! before proceeding with a refresh� _current_path)� version_checkr� r� r� r� r� Z_sa_orm_load_options)�paramsrv r� ),Z_cloneZ_is_lambda_elementr Zdefault_load_options�_compile_optionsr$ Z default_select_compile_optionsr �default_compile_optionsZ_propagate_attrs� _get_clausers r� �sql_utilZadapt_criterion_to_nullrq r �warnZ_deep_annotateZ_where_criteriaZ_for_update_argr= � ArgumentErrorr� Z_primary_key_propkeys� differencer> �_propsZ_is_relationshipry rO � load_path�parent�options�_set_get_optionsZ _order_byr% Z merge_with�execute�unique�scalarsZoner� Z NoResultFound)r� r� r� rO r� r� r� r� r� r� rv r� r� r� �q�compile_optionsr� r� Znonesr� r� Zrefresh_state_prokeysr� �mp�pZnew_compile_optionsr} r7 )r� r� r: r� s� �� � �� �� � � ���" � �� � r� c C s| i }i } |r|| d< |r || d< |r4|| d< d|d< |rDt |�|d< |rP|| d< |r\|| d< | rh|| 7 }|rt| |7 } | |fS ) NZ_version_checkZ_populate_existingZ_refresh_stateTZ_for_refresh_stateZ_only_load_propsZ_identity_tokenZ_is_user_refresh)� frozenset) Z compile_optZload_opt�populate_existingr� r� r� r� r� r� rO r7 r7 r: r� � s( r� c K s� |r|� |�} n|j} i } |�| jd| � |oBt|�dkoB|d j} | D ]6} |r\| j|vr\qH| j| |||f||| | d�| �� qH|d ur�||jur�|r�|j | }n|}|� |� d S )N�memoized_setupsr ���)r� �column_collectionZmemoized_populators�check_for_adapt) Z _iterate_polymorphic_propertiesZ_polymorphic_properties�setr rq �is_aliased_classr� �setup�polymorphic_on�columnsr� )rp r� r9 rc �adapterr� Zwith_polymorphicr� �polymorphic_discriminator�kwZpoly_properties�quick_populatorsr� r� �pdr7 r7 r: �_setup_entity_query� s@ ��� � �� r� c C s t �dt| �f � d S )Nam Loading context for %s has changed within a load/refresh handler, suggesting a row refresh operation took place. If this event handler is expected to be emitting row refresh operations within an existing load or refresh operation, set restore_load_context=True when establishing the listener to ensure the context remains unchanged when the event handler completes.)r r� r )r� r7 r7 r: �_warn_for_runid_changed s ��r� c s� � j ��j} d� f} |�| j| d�} | du �r j} � durT| �� fdd�� D ��} |��jdt�}g }g g g g g g d�}�du r�� j}� r�� fdd�|D �}|�|��nd�||�d �} | D ]�}||v �r�|| }|t u r�|d � |j |j f� n�|t u �r|d � |j d f� n�|tu �r6|d � |j |jf� nnd}� �r`� j| }|du�r`|�|d �}|�sr|�|d �}|�r�|d � |j |f� n|��| |� |� |� q�|� |� q�|�| j| | � | d }dd� |�� D ��| d D ] }|��| |� |� �� �q�j��jjj�r �jj| n|��jj��j�p8� j� t � j j j ��t � j j j ��t �jj j!�� � �rt�jj j!� tj"�tj#��jj$��j%��j&��j'���rЈ j(}|du�r̈ �r�� j| }|�|��nd���s�| du�r�d|jf}|�jv �r�j| j)dk�r�j| j*d }nd}� �+|| �}|�r�|| u�rʈ du �sHJ �|j,�r~g }|}|�r�|| u�r�|� |� |j-}�qXn|g}|D ]@} t.�/��| ��r��q�t0�|| | |�} t.�1��| j2| | | � �q�t.�3��� ����r��j ��du �r� �4���n d�| d �� j5�rt6j7�nt6j���������� � � � � ������������fdd�} � j8�r�| �s���s�����fdd�} t9| �| � |||� | � } | S )z]Produce a mapper level row processor callable which processes rows into mapped instances.�gettersNc 3 s | ]}� j | V qd S rh )r� )r8 �k�r� r7 r: � <genexpr>U s z&_instance_processor.<locals>.<genexpr>r� )�new�quick�deferred�expire�existing�eagerc s g | ]}� j | �qS r7 )r� )r8 �c)r� r7 r: r; l rU z'_instance_processor.<locals>.<listcomp>)�cached_populators�todo�primary_key_getterr� r� Fr� r� c S s i | ]\}}|t |��qS r7 )rZ )r8 r� r� r7 r7 r: r� � rU z'_instance_processor.<locals>.<dictcomp>r� �loader))Zselectinload_polymorphicT�entitiesr c s� �r,�}|� � }�|�}|j�k}d}d}n���| ��f}��|�}|d ur��|�}�|�}|j�k}| }d}�r�r�|s�t� ||| �� nT�|d �r�d S d}d}d}� j�� }�|�}�|�}||_�|_�|_�� ||� � }�|u r�d}|s�|�r |�r��s|�s�|_ �|_ t � | |||�||� � |�r�|j} |�r���rn|j j�|� � |j| k�rnt|� � �r� j|� |j| k�r�t|� n,��r�|j j�|� � � |j�k�r�t|� |�s�|j�r���r� �r�|�|� � n |�|�� ��r���|d� n�|j} |� jv}|�r0| �s0� d �r�t� | |||�| � �} |�r���r~|j} |j j�|� | � |j| k�r~t|� |�|| � ��r�� j�r���|d� |S )NTFr r� )rF ro rw �_validate_version_id� class_managerZ new_instancer� r� � session_idZ_add_unpresentrO r� �_populate_full�manager�dispatchr� r� r� �refresh�modifiedZ_commitZ _commit_all� add_state�unloadedrY �_populate_partialZinvoke_all_eagers) rR r� r� �dict_�isnewZ currentload�loaded_instance� identitykeyZeffective_populate_existingZexisting_runidr �to_load)r5 �identity_classr� r� r� �is_not_primary_key�load_evtr� �loaded_as_persistentr� r� �persistent_evtr� � populatorsrd r �propagated_loader_options� refresh_evt�refresh_identity_keyr� ro r �session_identity_mapr� �version_id_getterr7 r: � _instance+ s� � � ��� � � z&_instance_processor.<locals>._instancec s& � �| ��f}�|d �s |S d S d S )Nr r7 )rR r )r r� r r r7 r: � ensure_no_pk� s � z)_instance_processor.<locals>.ensure_no_pk):Z_identity_classrp rw r Z _prop_set� intersectionr% r� Z _tuple_getterr r� r� Z_deferred_column_loaderr r Z_raise_column_loaderr� �_getterZcreate_row_processorr� r\ r � current_pathrc r� r� r� Zalways_refreshr� r r r� r r r� r� Zhash_keyro r� r� �version_id_colZstrategyZ local_optsZ_should_selectin_loadZ is_mapperr� �PostLoad� path_exists�_load_subclass_via_in�callable_for_pathr� � for_context�_identity_key_from_state�allow_partial_pksr � issuperset�polymorphic_map� _decorate_polymorphic_switch) r9 r� r5 r} rc r� r� r� r� �_polymorphic_fromrp Z getter_keyr� �propsr� r� r� Zpk_cols�propr� �getterZ adapted_colr# r� �option_entitiesZselectin_load_viaZ _load_supersZ_endmost_mapperZ_selectinload_entityZ callable_r r r7 )r� r5 r r� r� r� r r r� r r� r� r r� r rd r r r r r� ro r r r� r r: �_instance_processor+ sH ��� � � � � ��� ��� ��� �< ! � r3 c sj |j �|j }|jd u}t�jj�dk�|js0|rD��||�\��� n �j\��� � �����fdd�}|S )Nr c s� �s �fdd�|D �}|s d S | j }|jr@��|�}� �|�}n�}� }|f|j |f }�j|� } | jj| _| jd|ji7 _| jr�| j dd�} | j � | t �fdd�|D �d��� � �� �� d S )Nc s$ g | ] \}}|j �� �r||f�qS r7 )r� Z+_would_selectin_load_only_from_given_mapper)r8 �s�vr� r7 r: r; s �z:_load_subclass_via_in.<locals>.do_load.<locals>.<listcomp>r� T)r� c s, g | ]$\}}� r |j d d n|j d �qS )r r r� )r8 r� Z load_attrs)�zero_idxr7 r: r; # s �)Z primary_keys)r� r� Z _prepend_pathZ _with_optionsr� rp r� r� r� rv r� r� rz r� r� �all) r5 rc �states� load_onlyZeffective_entityZ orig_queryZenable_opt_lclZdisable_opt_lclr� Zq2�Z disable_optZ enable_optr� r2 r� r6 r7 r: �do_load� s6 � � ���z&_load_subclass_via_in.<locals>.do_load)r� r� rq Z base_mapperr� r� Z_subclass_load_via_inZ _subclass_load_via_in_mapper)r5 rc �entityZpolymorphic_fromr2 Zpolymorphic_from_mapperZnot_against_basemostr; r7 r: r: r& � s � .r& c C s |r�| j |_ |d D ]\} } | |�|| < q|r^|d D ]$\} } |�| d � | r6|j�| � q6n"|d D ]\} } | rf|j�| � qf|d D ]\} } | |||� q�nt||jkr�||_|d D ] \} } | |vr�| |�|| < q�|d D ]\} } | |||� q�n |d D ]\} } | |||� q�d S )Nr� r� r� r� )ro �pop�expired_attributes�addr� ) r5 rR r� r r r� r r� r r� r1 � set_callable� populatorr7 r7 r: r - s. r c C s |s`|r.|d D ] \}} ||v r| |�||< q| j | } |d D ] \}} || v r@| |||� q@n�|} | | j |< |d D ] \}} || v rv| |�||< qv|d D ],\}} || v r�|�|d � | r�|j�|� q�|d D ] \}} || v r�| |||� q�|d D ] \}} ||vr�| |||� q�| S )Nr� r� r� r� r� )rY r= r> r? ) r5 rR r� r r r� r r r� r1 r rA r@ r7 r7 r: r f s4 r c C sD | � ||| j�||�kr@t�dt|�| � ||| j�||�f ��d S )NzWInstance '%s' has version id '%s' which does not match database-loaded version id '%s'.)Z_get_state_attr_by_columnr# r� ZStaleDataErrorr )r� r� r rR r1 r7 r7 r: r � s ������r c sr |d ur|�n�j ��d u r �S � r.� j� �� ���� � fdd�} t�| ��� ����������fdd�} | S )Nc sb z�j | }W n ty, td| ��Y n20 |�u r:d S |���sHdS t�|���� �d�S d S )Nz*No such polymorphic_identity %r is definedF)r. )r, �KeyError�AssertionErrorr� r3 )� discriminatorZ sub_mapper)r� r5 r� rc r9 r} r7 r: �configure_subclass_mapper� s& � �z?_decorate_polymorphic_switch.<locals>.configure_subclass_mapperc s� �| �}|d urf�| }|r$|| �S |du r\� | �}|rVt �d|��j| �f ��qdd S q��| �S n$� | �}|r�t �d|�f ��nd S d S )NFz�Row with identity key %s can't be loaded into an object; the polymorphic discriminator column '%s' refers to %s, which is not a sub-mapper of the requested %szjRow with identity key %s can't be loaded into an object; the polymorphic discriminator column '%s' is NULL)r= r> r, )rR rD r r )r r1 � instance_fnr� �polymorphic_instancesr� r7 r: �polymorphic_instance� s6 ��� ��z:_decorate_polymorphic_switch.<locals>.polymorphic_instance)r� r� r Z PopulateDictr! ) rF r5 r9 r� r} rc r� r� r rE rH r7 ) r� r5 r r1 rF r� rc rG r� r9 r} r: r- � s &r- c @ sP e Zd ZdZdZdd� Zdd� Zdd� Zed d � �Z ed d � �Z ed d� �Z dS )r$ z4Track loaders and states for "post load" operations.)�loadersr8 � load_keysc C s i | _ t�� | _d | _d S rh )rI r � OrderedDictr8 rJ )�selfr7 r7 r: �__init__� s zPostLoad.__init__c C s || j |< d S rh )r8 )rL r� � overwriter7 r7 r: r � s zPostLoad.add_statec sz | j s d S tj�|�}| j�� D ]J\}}� }}}� fdd�| j �� D �}|r ||||| jg|�R i |�� q | j �� d S )Nc s& g | ] \}}|j j�� �r||f�qS r7 )r r� r� )r8 r� rN ��limit_to_mapperr7 r: r; s �z#PostLoad.invoke.<locals>.<listcomp>) r8 r Z PathRegistryZcoercerI �valuesr\ rJ r] ) rL r5 rc Zeffective_context�tokenr �argr� r8 r7 rO r: r^ s. � � ���zPostLoad.invokec C s$ |j �|j�}|d ur |r ||_|S rh )r[ rw rc rJ )�clsr5 rc r� �plr7 r7 r: r( s zPostLoad.for_contextc C s |j |jv o ||j|j jv S rh )rc r[ rI )rL r5 rc r� r7 r7 r: r% $ s �zPostLoad.path_existsc O sF |j |jv r|j|j }nt� }|j|j < ||||||f|j|< d S rh )rc r[ r$ rI ) rT r5 rc rP rR Zloader_callablerS r� rU r7 r7 r: r' + s �zPostLoad.callable_for_pathN) �__name__� __module__� __qualname__�__doc__� __slots__rM r r^ � classmethodr( r% r' r7 r7 r7 r: r$ � s r$ c s8 |j }|s t�dt|� ��t|tj@ �}|r>|�� j� � �}� j r|� j s|� � ||�}|dur|t � |�}t||d|||d�S t|j�}|r�|j} n<� fdd�� jD �} |j�| �r�t�dt|� ��� �|�} t�| �rވ jr�t�| �r�t�dt|�� dS t|t� �� t �| |||d�} |�r4| du �r4t� |��dS ) z4initiate a column-based attribute refresh operation.zQInstance %s is not bound to a Session; attribute refresh operation cannot proceedN)r� r� r� c s g | ]}� j | j�qS r7 )Z_columntopropertyr� )r8 r� r� r7 r: r; p s z*load_scalar_attributes.<locals>.<listcomp>z_Instance %s cannot be refreshed - it's not persistent and does not contain a full primary key.zwInstance %s to be refreshed doesn't contain a full primary key - can't be refreshed (and shouldn't be expired, either).)r� r� r� ) r� r� ZDetachedInstanceErrorr r� r Z NO_AUTOFLUSHr r� r� r� ZconcreteZ_optimized_get_statementr r� r� r� r> r= r> r) r �issubsetr* r+ r Z warn_limitedr! Zset_label_styler# r� ) r� r� Zattribute_namesr� r� r� r� �stmtZhas_keyZ identity_keyZpk_attrsr} r7 r� r: �load_scalar_attributes= sp �� � � �� ���� � r^ )T)T)NNNNNN)NNN)NNNN)\rY � __future__r �typingr r r r r r r r r r r � r r r� r �baser r r r r5 r r r r r r r= Zenginer Z engine.resultr r r Zsqlr! r� Zsql.selectabler" r# r$ r% Z_typingr& r' Z interfacesr( r� r) r� r* r� r+ r� r, Z engine.cursorr- Zengine.interfacesr. r/ r0 r1 �objectr3 �counterrn �strZ_PopulatorDictr~ Zpreload_moduler� Zbecame_legacy_20r� r� r� r� r� r� r� r3 r& r r r r- r$ r^ r7 r7 r7 r: �<module> s� ^ ;� �T+�(,�* < � ) � 7 � @E9%YH sqlalchemy/orm/__pycache__/properties.cpython-39.pyc 0000644 00000052441 15125143220 0016541 0 ustar 00 a ��Jh=s � @ s� d Z ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z dd lm Z dd lm Z dd lm Z dd lm Z dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddl m Z ddl m Z ddl m Z ddl m Z dd l m!Z! dd l m"Z" dd l m#Z# dd l$m%Z% dd l&m'Z' d!dlmZ( d!d"lm)Z) d!d#lm*Z* d!d$lm&Z& d!d%l+m,Z, d!d&l+m-Z- d!d'l.m/Z/ d!d(l0m1Z1 d!d)l0m2Z2 d!d*l3m4Z4 d!d+l5m6Z6 d!d,l5m7Z7 d!d-l5m8Z8 d!d.l5m9Z9 d!d/l5m:Z: d!d0l5m;Z; d!d1l5m<Z< d!d2l5m=Z= e �r dd3l>m?Z? dd4l>m@Z@ dd5l>mAZA dd6l>mBZB dd7lmCZC dd8lDmEZE dd9lFmGZG dd:lHmIZI dd;lJmKZK dd<lJmLZL d!d=lMmNZN d!d>lOmPZP d!d?lOmQZQ d!d@lRmSZS d!dAl5mTZT d!dBl5mUZU edCedD�ZVedEedD�ZWedFdGdD�ZXg dH�ZYe*jZG dIdJ� dJe eV e#eV e e*j[��Z\G dKdL� dLe\eV eeV �Z]G dMdN� dNe e eV eeV �Z^dOS )Pz|MapperProperty implementations. This is a private module which defines the behavior of individual ORM- mapped attributes. � )� annotations)�Any)�cast)�Dict)�List)�Optional)�Sequence)�Set)�Tuple)�Type)� TYPE_CHECKING)�TypeVar)�Union� )� attributes)�exc)�strategy_options)�_DeclarativeMapped)� class_mapper)�CompositeProperty)�ConcreteInheritedProperty)�SynonymProperty)�_AttributeOptions)�_DEFAULT_ATTRIBUTE_OPTIONS)�_IntrospectsAnnotations)� _MapsColumns)�MapperProperty)�PropComparator)�StrategizedProperty)�RelationshipProperty)�de_stringify_annotation� )� ForeignKey)�log)�util)� coercions)�roles)�_NoArg)�Column)� SchemaConst)� TypeEngine)�de_optionalize_union_types)�get_args)� includes_none)� is_a_type)� is_fwd_ref)� is_pep593)� is_pep695)�Self)�_IdentityKeyType)� _InstanceDict)�_ORMColumnExprArgument)� _RegistryType)�Mapped)�_ClassScanMapperConfig)�Mapper)�Session)�_InstallLoaderCallableProto)� InstanceState)� _InfoType)� ColumnElement)� NamedColumn)� OperatorType)�_AnnotationScanType)�RODescriptorReference�_T)�bound�_PT�_NCzNamedColumn[Any])�ColumnPropertyr r r r c s� e Zd ZU dZejZdZdZde d< de d< de d < d e d < d Z d d ddd ddd d ddd� dddddddddddddd� � fdd�Z ddddddd d dd d � d d �Z e d!d"�d#d$��Ze d%d"�d&d'��Zdd"�d(d)�Ze�d*d+�d,d"�d-d.��Ze�d*d+�d,d"�d/d0��Zd1d"�d2d3�Ze d1d"�d4d5��Zd6d d7�d8d9�Zd d"�� fd:d;� Zd<d"�d=d>�Zd?d@dAd@dAddBdCd dD� dEdF�ZG dGdH� dHeje e �Z dd"�dIdJ�Z � Z S )KrG z�Describes an object attribute that corresponds to a table column or other column expression. Public constructor is the :func:`_orm.column_property` function. TFzList[NamedColumn[Any]]�columns�bool� _is_polymorphic_discriminator� Optional[str]�_mapped_by_synonymzType[PropComparator[_T]]�comparator_factory)rH �group�deferred� instrumentrM �active_history�expire_on_flush�_creation_orderrJ rL Z_deferred_column_loaderZ_raise_column_loaderZ_renders_in_subqueries� raiseloadN) �attribute_optionsrN rO rT rM rQ rR �info�doc� _instrument� _assume_readonly_dc_attributesz_ORMColumnExprArgument[_T]z_ORMColumnExprArgument[Any]zOptional[_AttributeOptions]z"Optional[Type[PropComparator[_T]]]zOptional[_InfoType]) �column�additional_columnsrU rN rO rT rM rQ rR rV rW rX rY c s� t � j|| d� |f| }dd� |D �| _|| _|| _|| _| | _|d urN|n| jj| _ || _ || _ | d urx| j � | � | d ur�| | _n4t| j�D ]"}t|dd �} | d ur�| | _ q�q�d | _t�| � d| jfd| jff| _| jr�| jd7 _d S )N)rU rY c S s g | ]}t �tj|��qS � )r% �expectr& ZLabeledColumnExprRole��.0�cr\ r\ �N/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/properties.py� <listcomp>� s z+ColumnProperty.__init__.<locals>.<listcomp>rW rO rP ))rT T)�super�__init__rH rN rO rT rP � __class__� ComparatorrM rQ rR rV �updaterW �reversed�getattrr$ �set_creation_order� strategy_key)�selfrZ rU rN rO rT rM rQ rR rV rW rX rY r[ rH �col�re r\ ra rd � sD � ��� �zColumnProperty.__init__r8 r6 � Type[Any]�str�Optional[Type[Mapped[Any]]]� Optional[_AnnotationScanType]�None� � decl_scan�registry�cls�originating_module�key�mapped_container� annotation�extracted_mapped_annotation�is_dataclass_field�returnc C s. | j d } | jd u r|| _| jd u r*|| _d S �Nr )rH ry �name) rl ru rv rw rx ry rz r{ r| r} rZ r\ r\ ra �declarative_scan� s z ColumnProperty.declarative_scan� Optional[MapperProperty[_T]]�r~ c C s | S �Nr\ �rl r\ r\ ra �mapper_property_to_assign� s z(ColumnProperty.mapper_property_to_assign� List[Tuple[Column[Any], int]]c C s dd� | j D �S )Nc S s( g | ] }t |t�r|jd u r|df�qS r )� isinstancer( �tabler^ r\ r\ ra rb � s �z4ColumnProperty.columns_to_assign.<locals>.<listcomp>�rH r� r\ r\ ra �columns_to_assign� s �z ColumnProperty.columns_to_assignc C s( d| j v r| jjS d| j vp&| | jjvS )N)Zquery_expressionT)rO T)rk ZstrategyZ_have_default_expression�parentZ_readonly_propsr� r\ r\ ra �%_memoized_attr__renders_in_subqueries� s �z4ColumnProperty._memoized_attr__renders_in_subquerieszsqlalchemy.orm.statezsqlalchemy.orm.strategiesz _InstallLoaderCallableProto[Any]c C s. t jj}t jj}|j�| jj|�| j �| j �S r� � r$ � preloadedZ orm_stateZorm_strategiesr< Z"_instance_level_callable_processorr� Z class_managerZLoadDeferredColumnsry �rl �state� strategiesr\ r\ ra �&_memoized_attr__deferred_column_loader� s �z5ColumnProperty._memoized_attr__deferred_column_loaderc C s0 t jj}t jj}|j�| jj|�| j d�| j �S )NTr� r� r\ r\ ra �#_memoized_attr__raise_column_loader� s �z2ColumnProperty._memoized_attr__raise_column_loaderzroles.ColumnsClauseRolec C s | j S )zsAllow the ColumnProperty to work in expression before it is turned into an instrumented attribute. )� expressionr� r\ r\ ra �__clause_element__ s z!ColumnProperty.__clause_element__c C s | j d S )a� Return the primary column or expression for this ColumnProperty. E.g.:: class File(Base): # ... name = Column(String(64)) extension = Column(String(8)) filename = column_property(name + "." + extension) path = column_property("C:/" + filename.expression) .. seealso:: :ref:`mapper_column_property_sql_expressions_composed` r r� r� r\ r\ ra r� s zColumnProperty.expressionz Mapper[Any])�mapperr~ c C s0 | j s d S tj|j| j| �| |�|| jd� d S )N)Z comparator� parententityrW )rP r Zregister_descriptor�class_ry rM rW )rl r� r\ r\ ra �instrument_class% s �z ColumnProperty.instrument_classc sV t � �� t| j�dkrRt| jj��| j�rRt� d| j| jd | jd | j f � d S )Nr z�On mapper %s, primary key column '%s' is being combined with distinct primary key column '%s' in attribute '%s'. Use explicit properties to give each column its own mapped attribute name.r ) rc �do_init�lenrH �setr� Z primary_key� issupersetr$ �warnry r� rn r\ ra r� 1 s ���zColumnProperty.do_initzColumnProperty[_T]c C s t | j| j| j| jd��S )N)rO rN rQ )rG rH rO rN rQ r� r\ r\ ra �copyA s �zColumnProperty.copyr: zInstanceState[Any]r4 zDict[Any, object]z#Dict[_IdentityKeyType[Any], object]) �session� source_state� source_dict� dest_state� dest_dict�load� _recursive�_resolve_conflict_mapr~ c C st | j s d S | j|v rL|| j } |s.| || j< qp|�| j�} | �||| d � n$|jrp| j|vrp|j|| jgdd� d S )NT)Z no_loader)rP ry Zget_implr� Z has_identityZ_expire_attributes) rl r� r� r� r� r� r� r� r� �value�implr\ r\ ra �mergeI s �zColumnProperty.mergec @ s� e Zd ZU dZesdZded< ded< ddd�d d �ZerHd d �d d�Zd d �dd�Z dd �dd�Z dd �dd�Z ddd�dd�Z dddd d �d d �Z dddd d �d d!�Zd"S )#zColumnProperty.Comparatora� Produce boolean, comparison, and other operators for :class:`.ColumnProperty` attributes. See the documentation for :class:`.PropComparator` for a brief overview. .. seealso:: :class:`.PropComparator` :class:`.ColumnOperators` :ref:`types_operators` :attr:`.TypeEngine.comparator_factory` )r� rV � expressionsz*RODescriptorReference[ColumnProperty[_PT]]�propzSequence[NamedColumn[Any]]r� rF )rZ r~ c C sT | j }|||| jjd�}|}| jjr>|}| jj�|�}||d< |�|��d|d��S )a� annotate and possibly adapt a column to be returned as the mapped-attribute exposed version of the column. The column in this context needs to act as much like the column in an ORM mapped context as possible, so includes annotations to give hints to various ORM functions as to the source entity of this column. It also adapts it to the mapper's with_polymorphic selectable if one is present. )Zentity_namespacer� Z parentmapper� proxy_keyZ adapt_columnZorm)Zcompile_state_pluginZplugin_subject)Z _parententityr� ry Z _parentmapperZ_polymorphic_adapter�traverseZ _annotateZ_set_propagate_attrs)rl rZ �per rm Zmapper_local_colr\ r\ ra �_orm_annotate_column� s � �z.ColumnProperty.Comparator._orm_annotate_columnzNamedColumn[_PT]r� c C s d S r� r\ r� r\ r\ ra r� � � z,ColumnProperty.Comparator.__clause_element__c C s4 | j r | � | jjd | jj�S | �| jjd �S d S r )�adapterr� rH ry r� r� r\ r\ ra �#_memoized_method___clause_element__� s z=ColumnProperty.Comparator._memoized_method___clause_element__r= c C s0 | � � }z|jW S ty* | jj Y S 0 dS )z(The .info dictionary for this attribute.N)r� rV �AttributeErrorr� )rl Zcer\ r\ ra �_memoized_attr_info� s z-ColumnProperty.Comparator._memoized_attr_infoc s6 � j r � fdd�� jjD �S � fdd�� jjD �S dS )z�The full sequence of columns referenced by this attribute, adjusted for any aliasing in progress. .. versionadded:: 1.3.17 c s g | ]}� � |� jj��qS r\ )r� r� ry �r_ rm r� r\ ra rb � s �zHColumnProperty.Comparator._memoized_attr_expressions.<locals>.<listcomp>c s g | ]}� � |��qS r\ )r� r� r� r\ ra rb � s N)r� r� rH r� r\ r� ra �_memoized_attr_expressions� s � �z4ColumnProperty.Comparator._memoized_attr_expressionsrp r )ry r~ c C s t | �� |�S )z�proxy attribute access down to the mapped column. this allows user-defined comparison methods to be accessed. )ri r� )rl ry r\ r\ ra �_fallback_getattr� s z+ColumnProperty.Comparator._fallback_getattrr@ �ColumnElement[Any]��op�other�kwargsr~ c O s || � � g|�R i |��S r� �r� �rl r� r� r� r\ r\ ra �operate� s z!ColumnProperty.Comparator.operatec K s" | � � }||�||�|fi |��S r� �r� Z _bind_param�rl r� r� r� rm r\ r\ ra �reverse_operate� s z)ColumnProperty.Comparator.reverse_operateN)�__name__� __module__� __qualname__�__doc__r � __slots__�__annotations__r� r� r� r� r� r� r� r� r\ r\ r\ ra rf c s ( rf c C s. | j r | jst�| �S t| j jj�d | j S )N�.)r� ry �object�__repr__rp r� r� r� r\ r\ ra �__str__� s zColumnProperty.__str__)!r� r� r� r� r Z _COLUMN_TOKENZstrategy_wildcard_key� inherit_cacheZ_links_to_entityr� r� rd r� �propertyr� r� r� r$ �preload_moduler� r� r� r� r� r� r� r� Z MemoizedSlotsr rE rf r� � __classcell__r\ r\ rn ra rG a sR �.; rG c @ s e Zd ZdZdZdS )�MappedSQLExpressionaN Declarative front-end for the :class:`.ColumnProperty` class. Public constructor is the :func:`_orm.column_property` function. .. versionchanged:: 2.0 Added :class:`_orm.MappedSQLExpression` as a Declarative compatible subclass for :class:`_orm.ColumnProperty`. .. seealso:: :class:`.MappedColumn` TN)r� r� r� r� r� r\ r\ r\ ra r� � s r� c @ s: e Zd ZU dZdZded< ded< ded< d ed < d ed < d ed< ddd�dd�Zddd�dd�Zedd�dd��Z edd�d d ��Z ed d�d d ��Z d d�d!d"�Z d#ddd$d%�d&d'�Z d#ddd$d%�d(d)�Zdd�d*d+�Zd,d-d.ddd/d0d0dd1d2� d3d4�Ze�d5�d-d.dddd6d1d7�d8d9��Zd.d-d6dd1d:�d;d<�Zd=S )>� MappedColumna_ Maps a single :class:`_schema.Column` on a class. :class:`_orm.MappedColumn` is a specialization of the :class:`_orm.ColumnProperty` class and is oriented towards declarative configuration. To construct :class:`_orm.MappedColumn` objects, use the :func:`_orm.mapped_column` constructor function. .. versionadded:: 2.0 ) rZ rS � _sort_order� foreign_keys� _has_nullable�_has_insert_defaultrO �deferred_group�deferred_raiseloadrQ �_attribute_options�_has_dataclass_arguments�_use_existing_columnzUnion[_NoArg, bool]rO rI r� rK r� � Column[_T]rZ zOptional[Set[ForeignKey]]r� r r� r )�arg�kwc s& |� dt� | _� |� dd�| _� d uoJ� tkoJt� fdd�t� j�D ��| _|� dtj �}|tj u| _ | j rx||d< n� j tj ur�� j |d< |� dd �| _ |� d d �| _ |� d tj �| _|� d d�| _|� d tj �| _td t|i |���| _| jj| _d|v �o|�d�d tjfv| _t�| � d S )NrU Zuse_existing_columnFc 3 s( | ] \}}|d kr� | t juV qdS )�dataclasses_defaultN)r' �NO_ARG)r_ �i�attr�Z attr_optsr\ ra � <genexpr>4 s �z(MappedColumn.__init__.<locals>.<genexpr>�insert_default�defaultr� r� rO rQ Z sort_orderr� �nullable)�popr r� r� �any� enumerate�_fieldsr� r' r� r� r� r� r� rO rQ r� r r( rZ r� �getr) ZNULL_UNSPECIFIEDr� r$ rj )rl r� r� r� r\ r� ra rd * s: � � �� �zMappedColumn.__init__r2 )r� r~ c K s� | j �| j �}| jjf i |��|_| j|_| j|_| j|_|jj|_| j|_| j |_ | j |_ | j |_ | j |_ | j |_ | j|_t�|� |S r� )re �__new__rZ �_copyrO r� r� r� rQ r� r� r� r� r� r� r$ rj )rl r� �newr\ r\ ra r� Q s zMappedColumn._copyrp r� c C s | j jS r� )rZ r� r� r\ r\ ra r� b s zMappedColumn.namer� c C sP | j }|tju r t| jp | j�}|s*| jrHt| j|| j| j| j | jd�S d S d S )N)rO rN rT rU rQ ) rO r' r� rI r� r� rQ rG rZ r� )rl Zeffective_deferredr\ r\ ra r� f s � � z&MappedColumn.mapper_property_to_assignr� c C s | j | jtjur| jndfgS r )rZ r� r' r� r� r\ r\ ra r� z s ���z MappedColumn.columns_to_assignc C s | j S r� )rZ r� r\ r\ ra r� � s z MappedColumn.__clause_element__r@ r� r� c O s || � � g|�R i |��S r� r� r� r\ r\ ra r� � s zMappedColumn.operatec K s" | � � }||�||�|fi |��S r� r� r� r\ r\ ra r� � s z MappedColumn.reverse_operatec C s t � S r� )r� r� r\ r\ ra �found_in_pep593_annotated� s z&MappedColumn.found_in_pep593_annotatedr8 r6 ro rq rr rs rt c C s� | j } | jr^|jr^|jr^|jr(t�d��t|jd�} | jd urD| jn|} | j j � | | � } | _ | j d u rn|| _ | jd u r~|| _| j } |d u r�| jr�| j js�| �||� nd S | �||||� d S )Nz3Can't use use_existing_column with deferred mappersF)rZ r� Zinherits�singleZ is_deferred�sa_exc� ArgumentErrorr r� Z local_tabler` r� ry �type�_isnullr� Z_raise_for_required�_init_column_for_annotation)rl ru rv rw rx ry rz r{ r| r} rZ Zsupercls_mapperZcolname�sqltyper\ r\ ra r� � s> ���� � �z MappedColumn.declarative_scanzsqlalchemy.orm.decl_baserA )rv rw rx ry � param_name�param_annotationr~ c C s* t jj}|�|| j� | �||||� d S r� )r$ r� Z orm_decl_baseZ_undefer_column_namerZ r� )rl rv rw rx ry r� r� � decl_baser\ r\ ra � declarative_scan_for_composite� s �z+MappedColumn.declarative_scan_for_composite)rw rv �argumentrx r~ c C s | j j}t|ddd�r2|d us"J �t|||dd�}t|�}| jsH|| j _t|�}d}d} d } t|�r�d} t |�} | d } |r�t| �} | dd � }n$t |�r�t|j �r�t |j �dd � }|D ]} t | t �r�| } q�q�d } | d u�r6| js�| j jd ur�d | j _| j �| j � | j j}| jtju�r4| jtju �r4| j| _| jd u�rT| jd u �rT| j| _| jd u�rt| jd u �rt| j| _| j�r�| j�s�d| _| j�r�| j| _| jd u�r�| jtju �r�| j| _| j jd u�s�| j jd u�r�t� dd � | j �r6t | j j �D ]<\}}| j | tju�r�|�!d d �}t� d |� d �d � �q�|j"�r| j j#�s| �rX|| g}n|g}|D ] }|�$|�}|d u�rb �q �qbt |t%��s�t |t��r�t&|t%��r�t'�(d| j j�d|� d���nDt)|��r�t'�(d|� d| j j�d���n t'�(d| j j�d|�d���| j �*|� d S )NT)Z check_genericZcheck_for_plain_string)Zinclude_genericr\ Fr r z_Can't use the 'key' or 'name' arguments in Annotated with mapped_column(); this will be ignoredz2.0.22Z dataclasses_� z Argument 'zp' is a dataclass argument and cannot be specified within a mapped_column() bundled inside of an Annotated objectz The type provided inside the z4 attribute Mapped annotation is the SQLAlchemy type z . Expected a Python type insteadz6Could not locate SQLAlchemy Core type for Python type z inside the z attribute Mapped annotationz The object provided inside the zC attribute Mapped annotation is not a Python type, it's the object z. Expected a Python type.)+rZ r� r/ r r- r� r� r+ r0 r, r1 Z __value__r� r� r� r� �_mergerO r' r� r� r� r� rQ r� ry r� r$ Zwarn_deprecatedr� r� r� r� �replacer� r� Z _resolve_typer* � issubclass�orm_excZMappedAnnotationErrorr. Z _set_type)rl rw rv r� rx r� r� Zour_typeZfind_mapped_inZour_type_is_pep593Zraw_pep_593_typeZpep_593_components�elemZ use_args_from�idxr� ZchecksZ check_typeZ new_sqltyper\ r\ ra r� � s� � � � � � �������� � � ��� �� � �� �� ��� ��z(MappedColumn._init_column_for_annotationN)r� r� r� r� r� r� rd r� r� r� r� r� r� r� r� r� r� r$ r� r� r� r\ r\ r\ ra r� � s0 ' 2 r� N)_r� � __future__r �typingr r r r r r r r r r r r r� r r r r �baser r Zdescriptor_propsr r r Z interfacesr r r r r r r Z relationshipsr r$ r r� r" r# Zsqlr% r& Zsql.baser' Z sql.schemar( r) Z sql.type_apir* Z util.typingr+ r, r- r. r/ r0 r1 r2 Z_typingr3 r4 r5 r6 r7 r� r8 r� r9 r� r: r� r; r< Z sql._typingr= Z sql.elementsr> r? Z sql.operatorsr@ rA rB rC rE rF �__all__Z class_loggerZ IdentifiedrG r� r� r\ r\ r\ ra �<module> s� � � sqlalchemy/orm/__pycache__/decl_base.cpython-39.pyc 0000644 00000126744 15125143220 0016256 0 ustar 00 a ��Jh/E � @ s d Z ddlmZ ddlZddlZddlZddlmZ ddlmZ ddlm Z ddlm Z ddlm Z dd lm Z dd lm Z dd lmZ dd lmZ dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlZddlmZ ddlmZ ddlmZ ddlm Z ddlm Z ddl m Z ddl m!Z! dd lm"Z" dd lm#Z# dd l$m%Z% dd l$m&Z& dd l'm(Z( dd!l'm)Z) dd"l*m+Z+ dd#l*m,Z, dd$l*m-Z- dd%l*m.Z. dd&l*m/Z/ dd'l*m0Z0 dd(l1m2Z2 dd)l3m4Z4 dd*l3m5Z5 dd+l6m7Z7 dd,l6m8Z8 dd-l6m9Z9 dd.l6m:Z: d/d0lm;Z; d/dlmZ d/d1lm6Z6 d/d2l<m=Z= d/d3l>m?Z? d/d4l@mAZA d/d5l@mBZB d/d6l6mCZC d/d7lDmEZE d/d8lDmFZF d/d9lDmGZG d/d:lDmHZH d/d;lDmIZI d/d<lDmJZJ e�r6dd=l mKZK dd>l mLZL dd?l$mMZM dd@lNmOZO ddAl mPZP d/dBlQmRZR d/dCl@mSZS d/dDlTmUZU edEedF�ZVe eWef ZXeeedGf e eWef f ZYG dHdI� dIeIe �ZZG dJdK� dKeZe eI�Z[G dLdM� dMeJ�Z\dNdOdP�dQdR�Z]dNdSdP�dTdU�Z^dNdVdP�dWdX�Z_d�dNdZdSd[d\�d]d^�Z`d_d`dP�dadb�ZadcdNdddedf�dgdh�Zbdcd_didjdkdl�dmdn�Zce6�ddo�dpdSdq�drds��ZedpdZd_dSdt�dudv�ZfG dwdx� dx�ZgG dydz� dzeg�ZhG d{d|� d|e�ZiG d}d~� d~eg�Zje6�ddo�ddZdpd��d�d���ZkG d�d�� d�ej�ZldNdZd�d�d��d�d��ZmdNdZd�d��d�d��Zndpdpd�d��d�d��Zod�eo_pdZd�d�d��d�d��ZqdS )�z(Internal implementation for declarative.� )� annotationsN)�Any)�Callable)�cast)�Dict)�Iterable)�List)�Mapping)� NamedTuple)�NoReturn)�Optional)�Sequence)�Tuple)�Type)� TYPE_CHECKING)�TypeVar)�Union� )� attributes)� clsregistry)�exc)�instrumentation)� mapperlib)�_O)�attr_is_internal_proxy)�InstrumentedAttribute)�QueryableAttribute)�_is_mapped_class)�InspectionAttr)�CompositeProperty)�SynonymProperty)�_AttributeOptions)�_DCAttributeOptions)�_IntrospectsAnnotations)�_MappedAttribute)� _MapsColumns)�MapperProperty)�Mapper)�ColumnProperty)� MappedColumn)�_extract_mapped_subtype)�_is_mapped_annotation)� class_mapper)�de_stringify_annotation� )�event)�util)� expression)�_NoArg)�Column)�Table)� topological)�_AnnotationScanType)�get_args)� is_fwd_ref)� is_literal)�Protocol)� TypedDict)� _ClassDict)� _RegistryType)�Mapped)� declared_attr)� ClassManager)� NamedColumn)�MetaData)� FromClause�_T)�bound.c @ s: e Zd ZU dZded< ded< ded< dd d �d d �Zd S )�MappedClassProtocolz�A protocol representing a SQLAlchemy mapped class. The protocol is generic on the type of class, use ``MappedClassProtocol[Any]`` to allow any mapped class. �str�__name__� Mapper[_O]� __mapper__rC � __table__r r )�kw�returnc K s d S �N� )�selfrL rO rO �M/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/decl_base.py�__call__e � z MappedClassProtocol.__call__N)rH � __module__� __qualname__�__doc__�__annotations__rR rO rO rO rQ rF Z s rF c @ sV e Zd ZU dZded< ded< ded< ded < d ed < d d �dd�Zd d �dd�ZdS )�_DeclMappedClassProtocolz:Internal more detailed version of ``MappedClassProtocol``.rB �metadatarG � __tablename__� _MapperKwArgs�__mapper_args__�Optional[_TableArgsType]�__table_args__� Optional[_DataclassArguments]�_sa_apply_dc_transforms�None�rM c C s d S rN rO �rP rO rO rQ �__declare_first__q rS z*_DeclMappedClassProtocol.__declare_first__c C s d S rN rO rc rO rO rQ �__declare_last__s rS z)_DeclMappedClassProtocol.__declare_last__N)rH rT rU rV rW rd re rO rO rO rQ rX h s rX c @ sN e Zd ZU ded< ded< ded< ded< ded< ded< ded< d ed < d S ) �_DataclassArgumentszUnion[_NoArg, bool]�init�repr�eq�order� unsafe_hash� match_args�kw_onlyz'Union[_NoArg, Callable[..., Type[Any]]]�dataclass_callableN�rH rT rU rW rO rO rO rQ rf v s rf � Type[Any]z3Optional[Union[_DeferredMapperConfig, Mapper[Any]]]��clsrM c C s0 t �| �rt �| �S t| �r(t| dd�S d S d S )NF)� configure)�_DeferredMapperConfig�has_cls�config_for_clsr r, �rr rO rO rQ �_declared_mapping_info� s rx �boolc C s. t �| �rt| ddd� S t| �r&dS dS dS )a� return True if this class will be used as a superclass to set in 'inherits'. This includes deferred mapper configs that aren't mapped yet, however does not include classes with _sa_decl_prepare_nocascade (e.g. ``AbstractConcreteBase``); these concrete-only classes are not set up as "inherits" until after mappers are configured using mapper._set_concrete_base() �_sa_decl_prepare_nocascadeT��strictFN)rt ru �_get_immediate_cls_attrr rw rO rO rQ �_is_supercls_for_inherits� s �r~ �Optional[Type[Any]]c C s\ | t u r d S | j�dd�rB| jD ] }t|�}|d ur | S q d S t| �}|rT|jS | S d S )N� __abstract__F)�object�__dict__�get� __bases__�"_resolve_for_abstract_or_classical�_dive_for_cls_manager�class_)rr �base_�supZ clsmanagerrO rO rQ r� � s r� FrG z Optional[Any])rr �attrnamer| rM c C s� |dks J �t | t�sdS || jv r.t| |�S | jdd� D ]D}t|�du}||jv r<|| u sr|rn|| jv r<n |s<t||� S q<dS )a� return an attribute of the class that is either present directly on the class, e.g. not on a superclass, or is from a superclass but this superclass is a non-mapped mixin, that is, not a descendant of the declarative base and is also not classically mapped. This is used to detect attributes that indicate something about a mapped class independently from any mapped classes that it may inherit from. r� Nr T)� issubclassr� r� �getattr�__mro__r� r� )rr r� r| �baseZ_is_classical_inheritsrO rO rQ r} � s( ��� � �r} �Type[_O]zOptional[ClassManager[_O]]c C s& | j D ]}t�|�}|r| S qd S rN )r� r �opt_manager_of_class)rr r� �managerrO rO rQ r� � s � r� r= r< �Optional[_MapperConfig])�registryrr �dict_rM c C s t �| ||d i �S rN )� _MapperConfig� setup_mapping)r� rr r� rO rO rQ �_as_declarative� s r� �Optional[FromClause]r[ rI )r� rr �table� mapper_kwrM c C s t | |||� td|�jS )NzMappedClassProtocol[_O])�_ImperativeMapperConfigr rJ )r� rr r� r� rO rO rQ �_mapper� s r� zsqlalchemy.orm.decl_apir )�objrM c C s t jjj}t| |t jf�S rN )r0 � preloaded� orm_decl_api�_declared_attr_common� isinstanceZ classproperty)r� r� rO rO rQ �_is_declarative_props s r� )r� �namerr rM c C s2 t | �r*t| dd�r&t�d||f � dS dS d S )N� _cascadingFz~@declared_attr.cascading is not supported on the %s attribute on class %s. This attribute invokes for subclasses in any case.T)r� r� r0 �warn)r� r� rr rO rO rQ � _check_declared_props_nocascade s ��r� c @ s� e Zd ZU dZded< ded< ded< ded < ed d d d ddd�dd��Zd ddd�dd�Zdddd�dd�Zd#ddd �d d �Z dd d �d d!�Z d"S )$r� )rr � classname� properties�declared_attr_reg� __weakref__rp rr rG r� z_util.OrderedDict[str, Union[Sequence[NamedColumn[Any]], NamedColumn[Any], MapperProperty[Any]]]r� z Dict[declared_attr[Any], Any]r� r= r� r< r� r[ r� )r� �cls_r� r� r� rM c C s| t �| �}|r*|j|u r*t�d| �d���|j�dd�r<d S t|ddd�pRt|d�}|rht |||||�S t |||||�S d S ) N�Class z, already has been instrumented declarativelyr� Frz Tr{ Z_sa_decl_prepare) r r� r� r �InvalidRequestErrorr� r� r} �hasattrrt �_ClassScanMapperConfig)rr r� r� r� r� r� r� Z defer_maprO rO rQ r� * s& ��� � �z_MapperConfig.setup_mapping)r� r� r� c C sx t �|td�| _|j| _t �� | _i | _|� dd�sNt j | jd|| |j d� n&t �| j�}|rd|jstt�d| j ��d S )Nr� � non_primaryF)�finalizer� �declarative_scanZ init_methodztClass %s has no primary mapper configured. Configure a primary mapper first before setting up a non primary Mapper.)r0 Zassert_arg_type�typerr rH r� � OrderedDictr� r� r� r Zregister_class� constructorr r� � is_mappedr r� )rP r� r� r� r� rO rO rQ �__init__I s& � ��z_MapperConfig.__init__rD )r� �valuerM c C s t �| j�}|�||� |S rN )r �manager_of_classrr Zinstall_member)rP r� r� r� rO rO rQ �set_cls_attributee s z _MapperConfig.set_cls_attribute.� Mapper[Any]�r� rM c C s t � �d S rN )�NotImplementedError�rP r� rO rO rQ �mapj s z_MapperConfig.mapra c C s | � |� d S rN )r� r� rO rO rQ �_early_mappingm s z _MapperConfig._early_mappingN).) rH rT rU � __slots__rW � classmethodr� r� r� r� r� rO rO rO rQ r� s r� c sR e Zd ZdZddddd�� fdd� Zejfdd d �d d �Zdd d �dd�Z� Z S )r� )� local_table�inheritsr= r� r� r[ )r� r� r� r� c s| t � �|||� | �d|�| _tj�D |�dd�sFt�| j | j |j � | � |� | � |� W d � n1 sn0 Y d S )NrK r� F)�superr� r� r� r �_CONFIGURE_MUTEXr� r � add_classr� rr �_class_registry�_setup_inheritancer� )rP r� r� r� r� �� __class__rO rQ r� t s � z _ImperativeMapperConfig.__init__r� r� c C s" t }| �d|| j| jfi |���S )NrJ )r' r� rr r� �rP r� Z mapper_clsrO rO rQ r� � s �z_ImperativeMapperConfig.mapra c C s� | j }|�dd �}|d u r�g }|jD ]0}t|�}|d u r:q$t|�r$||vr$|�|� q$|r�t|�dkrxt�d||f ��|d }nt |t �r�|j }|| _ d S )Nr� r �&Class %s has multiple mapped bases: %rr ) rr r� r� r� r~ �append�lenr r� r� r' r� r� )rP r� rr r� �inherits_searchr� �crO rO rQ r� � s* �� z*_ImperativeMapperConfig._setup_inheritance) rH rT rU r� r� r0 � EMPTY_DICTr� r� � __classcell__rO rO r� rQ r� q s r� c @ sF e Zd ZU ded< ded< ded< ded< d ed < d ed < d ed< dS )�_CollectedAnnotationr6 �raw_annotationzOptional[Type[Mapped[Any]]]�mapped_containerz Union[_AnnotationScanType, str]�extracted_mapped_annotationry � is_dataclassr � attr_valuerG �originating_modulerp �originating_classNro rO rO rO rQ r� � s r� c s. e Zd ZU dZdZded< ded< ded< d ed < d ed < d ed < ded< ded< ded< ded< ded< ded< ded< d ed < d ed < d ed < d ed!< d"ed#< d ed$< dd%dd d&d'�� fd(d)� Zd*d+�d,d-�Zd%d.d/�d0d1�Zh d2�Z e � d3�Z d4d5d/�d6d7�Z d*d+�d8d9�Zd*d+�d:d;�Zed%d<d=�d>d?��Zed@d%d<d*dA�dBdC��Zed@d*dD�dEdF��ZdGdHd4dIdJdKdL�dMdN�Zd4dGdJd*dO�dPdQ�Zd5d.d d4dRdS�dTdU�Zd*d+�dVdW�Zd*d+�dXdY�Zdmd d*d[�d\d]�Zd^d_d`�dadb�Zd&d*dc�ddde�Zd&d*dc�dfdg�Z d&d*dc�dhdi�Z e j fd&djdc�dkdl�Z � Z!S )nr� )r� � clsdict_view�collected_attributes�collected_annotationsr� �persist_selectable�declared_columns�column_ordering� column_copies� table_args� tablename� mapper_args�mapper_args_fn�table_fnr� �single�allow_dataclass_fields�dataclass_setup_arguments� is_dataclass_prior_to_mapping�allow_unmapped_annotationsFr= r� r< r� z Dict[str, _CollectedAnnotation]r� �Dict[str, Any]r� r� r� r� z util.OrderedSet[Column[Any]]r� zDict[Column[Any], int]r� zRDict[Union[MappedColumn[Any], Column[Any]], Union[MappedColumn[Any], Column[Any]]]r� z Optional[str]r� �Mapping[str, Any]r� r] r� z&Optional[Callable[[], Dict[str, Any]]]r� r r� ry r� r� r� r_ r� r� r� r[ )r� r� r� r� r� c sV |rt �|�nt j| _t� �|||� || _d | _i | _i | _ t � � | _ i | _ i | _ d| _t| jdd � | _}t| jdd�p�t| j�| _t�|� | _}t|d�}|r�|r�|r�t�d��t|o�|�| _| �� | � � | � � t j �\ t �!| j"| j|j#� | �$|� | �%� | �&� | �'|� | �(|� | �)|� W d � n1 �sH0 Y d S )NFr` Z__allow_unmapped__� __sa_dataclass_metadata_key__z�SQLAlchemy mapped dataclasses can't consume mapping information from dataclass.Field() objects if the immediate class is not already a dataclass.)*r0 Z immutabledictr� r� r� r� r� r� r� r� Z OrderedSetr� r� r� r� r� rr r� ry r� � dataclassesr� r� r} r r� r� �_setup_declared_events�_scan_attributes� _setup_dataclasses_transformsr r� r r� r� r� �_setup_inheriting_mapper� _extract_mappable_attributes�_extract_declared_columns� _setup_table�_setup_inheriting_columnsr� ) rP r� r� r� r� r� ZdcaZcldZsdkr� rO rQ r� � sR � � ��� � � z _ClassScanMapperConfig.__init__ra rb c sX t � jd�r*t�td�dd�� fdd� �}t � jd�rTt�td�dd�� fd d � �}d S ) Nre �after_configuredra rb c s t d� j��� d S �N� _DeclMappedClassProtocol[Any])r rr re rO rc rO rQ r� I s �zG_ClassScanMapperConfig._setup_declared_events.<locals>.after_configuredrd �before_configuredc s t d� j��� d S r� )r rr rd rO rc rO rQ r� Q s �zH_ClassScanMapperConfig._setup_declared_events.<locals>.before_configured)r} rr r/ Z listens_forr' )rP r� r� rO rc rQ r� F s z-_ClassScanMapperConfig._setup_declared_eventszCallable[[str, Any], bool]rq c s� | j rt�d��nd��s2dddd��fdd� }nR�fd d �t���D ���fd d �t���D ��t� � dddd�� ���fd d� }|S ) z�Produce a function that checks if a class has overridden an attribute, taking SQLAlchemy-enabled dataclass fields into account. r� NrG r ry )�keyr� rM c s t � | |�|uS rN )r� )r� r� rw rO rQ �attribute_is_overriddenh s zR_ClassScanMapperConfig._cls_attr_override_checker.<locals>.attribute_is_overriddenc s$ i | ] }� |j v r|j|j � �qS rO �rY r� ��.0�f��sa_dataclass_metadata_keyrO rQ � <dictcomp>l s �zE_ClassScanMapperConfig._cls_attr_override_checker.<locals>.<dictcomp>c s$ i | ] }� |j v r|j|j � �qS rO r� r r rO rQ r q s �c s� t |�r|j}��| � �}t |�r(|j}||u r4dS |� ur@dS ��| � �}t�| |�}||u rddS |� urzt|t�rzdS ||u r�dS |� ur�dS dS )NFT)r� �fgetr� r� r� r )r� r� �retZ all_field)�absent�all_datacls_fieldsrr �local_datacls_fieldsrO rQ r� y s, �)r� r} r0 �dataclass_fields�local_dataclass_fieldsr� )rP rr r� rO )r r rr r r rQ �_cls_attr_override_checkerW s � � � (z1_ClassScanMapperConfig._cls_attr_override_checker> rZ rK r^ r\ z ^(?:_sa_|__)rp z2Callable[[], Iterable[Tuple[str, Any, Any, bool]]]c s� t �|��t|��| j� | j�� �fdd�t �t��t���D ��| jrTt|d��nd��stdd����fdd� }n4d d � t � |�D ����dd�������fd d� }|S ) z�produce a function to iterate the "attributes" of a class which we want to consider for mapping, adjusting for SQLAlchemy fields embedded in dataclass fields. c s" g | ]}�� |�r|� v r|�qS rO )�match)r �n)�_include_dunders�_match_exclude_dundersrO rQ � <listcomp>� s �z=_ClassScanMapperConfig._cls_attr_resolver.<locals>.<listcomp>r� Nz$Iterable[Tuple[str, Any, Any, bool]]rb c s � �fdd��D �S )Nc 3 s& | ] }|�� |�� � |�d fV qdS )FN�r� )r r� )�cls_annotations�cls_varsrO rQ � <genexpr>� s ��z`_ClassScanMapperConfig._cls_attr_resolver.<locals>.local_attributes_for_class.<locals>.<genexpr>rO rO )r r �namesrO rQ �local_attributes_for_class� s �zM_ClassScanMapperConfig._cls_attr_resolver.<locals>.local_attributes_for_classc S s i | ] }|j |�qS rO )r� )r �fieldrO rO rQ r � s z=_ClassScanMapperConfig._cls_attr_resolver.<locals>.<dictcomp>c 3 sd �D ]Z} �� | d �}|rD�|jv rD|jt|j��� � |j�dfV q| �� | �� � | �dfV qd S )NTF)r� rY r� �_as_dc_declaredattr)r� r )r r r � fixed_sa_dataclass_metadata_keyr r rO rQ r � s � ���) r0 �get_annotations�varsr r Zmerge_lists_w_ordering�listr� r} r )rP rr r rO )r r r r r r r r rQ �_cls_attr_resolver� s, ���� z)_ClassScanMapperConfig._cls_attr_resolverc s� | j }td|�� | j}| j}| j}| j}d }d }}d } d } d|v } | �| j �} g } |jD ]R}||uolt|�}| � |�}|s�||ur�| � || | |�}ni }| � ||||f� qZ| D �]�\}}}}|� |� |� D �]�\}}}}||v �r�|dk�r(t |||�}|�s�|�r|�r�dd�� fdd� }|}n�|dk�rXt |||�}| �s�|�rP|�r�� j} n�|dk�r�t |||�}|�r�| �s�d d�� fd d � }|} nh|d k�r�t |||�}|�s�|�r�|�r�� j}t|tttd �f��s�t�d ��||u�r�d}n d�s�J �q�|�r,t|�r�|js�t�d|j|||f � q�q�||u�r�t|tt f��rLqАq�t|t ��rft� d���q�t|��rt|d u�s~J �|j �r�||v �r�t�d||f � |� ||� ||< ||< }t!|||� nl|�r�t"||d �}t|t#��s�|�$� }n t"||�}t|t#��r(t%|��r(t|j&t ��s(|j'}| ||< ||< t|tt f��r\|j(d u �r\|j)|_(| �*||�+� |d|� n:t,|||��r�| s�||v s�| |d �s�J �q�n| �-|||� q�|�r ||v�s�|| |u�r | ||��r�J �t|��r�|�$� }|||< | �*|||d|� q�| �*|||d |�}|d u�o0|j.d u}|d u�rB|j/n|} |d u �rv| �sv|�rv| d u�rj| nt � ||< q�||v r�|||< q�q�|�r�| �s�d }|| _0| | _1|| _2| | _3d S )Nr� rK r\ r� rb c s t � j�S rN )�dictr\ rO �� cls_as_DeclrO rQ �_mapper_args_fnA s z@_ClassScanMapperConfig._scan_attributes.<locals>._mapper_args_fnrZ rC c s � j S rN )rK rO r! rO rQ � _table_fnW s z:_ClassScanMapperConfig._scan_attributes.<locals>._table_fnr^ z3__table_args__ value must be a tuple, dict, or NoneTFz�Regular (i.e. not __special__) attribute '%s.%s' uses @declared_attr, but owning class %s is mapped - not applying to subclass %s.z�Mapper properties (i.e. deferred,column_property(), relationship(), etc.) must be declared as @declared_attr callables on declarative mixin classes. For dataclass field() objects, use a lambda:zXAttribute '%s' on class %s cannot be processed due to @declared_attr.cascading; skipping)4rr r r� r� r� r r r� r~ r �_produce_column_copiesr� �updater� rZ r^ r� �tupler r� r � ArgumentErrorr� Z_quietr0 r� rH r3 r) r& r� r� �__get__�setattrr� r r r Zoriginal_propertyZ descriptor�docrV �_collect_annotationZ_collect_return_annotationr+ �_warn_for_decl_attributesr� r� r� r� r� r� ) rP rr r� r� r� r r� r� Zinherited_table_argsr� r� � fixed_tabler� �basesr� Z class_mappedr Zlocally_collected_columnsr� r� � annotation�is_dataclass_fieldZ check_declr# r$ r �collected_annotationr� Z generated_objrO r! rQ r� � sn ���� � ��� � � ��� �� � �� � ����� ������ � � � �� ��� z'_ClassScanMapperConfig._scan_attributesc s� �j }|sd S d�jjv r.t�d�j� d���d�jjv rNt�d�j� d���t�t��dddd ���fd d � � t� �j�}|d us�J ��fd d �� �fdd��j � � D �D �}�r��� � D ]>\}}t j d�j� dd�dd� |D ��� d|� d�ddd� q�i }i }|D ]R}t|�dk�r$|\} } n,t|�dk�rF|\} } } | || < n d�sPJ �| || < �q|� � D ]\} } t�j| | � �qd��|�j|� d S ) N�__dataclass_fields__r� z� is already a dataclass; ensure that base classes / decorator styles of establishing dataclasses are not being mixed. This can happen if a class that inherits from 'MappedAsDataclass', even indirectly, is been mapped with '@registry.mapped_as_dataclass'rK zk already defines a '__table__'. ORM Annotated Dataclasses do not support a pre-existing '__table__' elementrG rp ry )r� r� rM c s& |� j ur"d|jvr"�| �| � dS )Nr3 T)rr r� r� )r� r� )rP �warn_for_non_dc_attrsrO rQ �_allow_dataclass_field: s ��zT_ClassScanMapperConfig._setup_dataclasses_transforms.<locals>._allow_dataclass_fieldc s. g | ]&\}}}t �|||� j�|tj���qS rO )r! Z!_get_arguments_for_make_dataclassr� r� r2 �NO_ARG)r r� �annor� rc rO rQ r H s ��zH_ClassScanMapperConfig._setup_dataclasses_transforms.<locals>.<listcomp>c 3 sV | ]N\}\}}}}}}}� ||�r|�j vs<t�j | t�s||rF|n||fV qd S rN )r� r� r ) r r� Zraw_annor� Z mapped_annoZis_dcr� r� r� )r5 rP rO rQ r O s" �� �zG_ClassScanMapperConfig._setup_dataclasses_transforms.<locals>.<genexpr>zWhen transforming z to a dataclass, attribute(s) �, c s s | ]}t |�V qd S rN �rh )r r� rO rO rQ r w rS z originates from superclass a , which is not a dataclass. This usage is deprecated and will raise an error in SQLAlchemy 2.1. When declaring SQLAlchemy Declarative Dataclasses, ensure that all mixin classes and other superclasses which include attributes are also a subclass of MappedAsDataclass.z2.0Zdcmx��coder. � F)r� rr r� r r� � collections� defaultdictr r r� r� �itemsr0 Zwarn_deprecated�joinr� r* � _apply_dataclasses_to_any_class)rP r� r� Z field_listr� Z non_dc_attrsr �defaults�itemr� �tp�spec�k�vrO )r5 rP r4 rQ r� sb � � ��'� �� � �z4_ClassScanMapperConfig._setup_dataclasses_transformsz!Mapping[str, _AnnotationScanType])�klassrM c C sl t �|�}i }|�� D ]P\}}t|||�r^t|||j|td �dddd�}|rf|\}}|||< q|||< q|S )NF��requiredr1 � expect_mapped)r0 r r? r+ r* rT r� ) rr rH r Znew_annor� r0 � extracted�inner�_rO rO rQ �(_update_annotations_for_non_mapped_class� s& � z?_ClassScanMapperConfig._update_annotations_for_non_mapped_classrf )r� rH �use_annotationsrM c C s� | � |� |d }|tju r"tj}|r@t|dd �}td|�|_nd }z�z"||fi dd� |�� D ��� W nH t t fy� } z,t j d|j �d|�d�d d �|�W Y d }~n d }~0 0 W |r�|d u r�|`q�||_n|r�|d u r�|`n||_0 d S ) Nrn rW r� c S s( i | ] \}}|t jur|d kr||�qS )rn )r2 r6 )r rF rG rO rO rQ r � s �zJ_ClassScanMapperConfig._apply_dataclasses_to_any_class.<locals>.<dictcomp>zAPython dataclasses error encountered when creating dataclass for z: zN. Please refer to Python dataclasses documentation for additional information.Zdcter: )�_assert_dc_argumentsr2 r6 r� Z dataclassr� r rW r? � TypeError� ValueErrorr r� rH )rr r� rH rP rn Zrestored�exrO rO rQ rA � sF ��� ���� �z6_ClassScanMapperConfig._apply_dataclasses_to_any_class)� argumentsrM c C sH h d�}t |��|�}|rDd�dd� t|�D ��}t�d|� d���d S )N> rm rl rk rn rg rj ri rh r8 c s s | ] }|�V qd S rN rO )r �argrO rO rQ r � rS z>_ClassScanMapperConfig._assert_dc_arguments.<locals>.<genexpr>zDataclass argument(s) z are not accepted)�set� differencer@ �sortedr r( )rr rU �allowedZdisallowed_args�msgrO rO rQ rQ � s �z+_ClassScanMapperConfig._assert_dc_argumentsrG r6 zOptional[bool]r z Optional[_CollectedAnnotation])r� r� r� rK r� rM c C s || j v r| j | S |d u r d S | j}| j}|d u r^t|tj�}| o\| o\|d u p\t|t�}d}t|| j|j |t |�d||o�| d�} | d u r�d S | \} } |d u r�t | �s�t | �D ]8} t | ddd�r�t| j| |j dd�} t| t�r�| �� }q�t|| | |||j |� | j |< } | S )NFrI T)Z check_genericZcheck_for_plain_string)Zinclude_generic)r� r� r� r� r� �Fieldr$ r* rr rT r� r9 r7 r8 r- r# Zfound_in_pep593_annotatedr� )rP r� r� r� rK r� r� Zallow_unmappedr1 rL r� r� �elem�carO rO rQ r, � sf �� � �� � z*_ClassScanMapperConfig._collect_annotation)rr r� r� rM c C s( t |tj�r$t�d|� d|� d�� d S )N� Attribute '� ' on class z� appears to be a non-schema SQLAlchemy expression object; this won't be part of the declarative mapping. To map arbitrary expressions, use ``column_property()`` or a similar function such as ``deferred()``, ``query_expression()`` etc. )r� r1 � ColumnElementr0 r� )rP rr r� r� rO rO rQ r- @ s �z0_ClassScanMapperConfig._warn_for_decl_attributesz0Dict[str, Union[Column[Any], MappedColumn[Any]]])�attributes_for_classr� r. r� rM c C sd | j }| j}i }| j}|� D �]@\} } } } |s�| d u r�t| ||�r�|| | �rNq | �| | |d| �} | d urn| jn| } | d u r�t� } | || < t|| | � q t| t tf�r || | �r�q | �| | |d| �} | d ur�| jn| } | |vr d|v �r t | dd �p�| |d j v s | j �r:| j D ]*}|j d u�r|j jd u �rt�d���q| �� || < }||| < t|| |� q |S )NTrK r� z�Columns with foreign keys to non-table-bound columns must be declared as @declared_attr callables on declarative mixin classes. For dataclass field() objects, use a lambda:.)rr r� r� r+ r, r� r) r* r� r3 r� r� Z foreign_keysZ _table_columnr� r r� Z_copy)rP rb r� r. r� rr r� Z locally_collected_attributesr� r� r� r0 r� r2 ZfkZcopy_rO rO rQ r% M sl �� � ��� ������ � �� z-_ClassScanMapperConfig._produce_column_copiesc s� | j }| j}| j}| j}t|ddd�}| j}|p4| j}t| j�}t |�D �]�} | |v rXqH|| � t � �r�� j r~t � d| j � t|| �� n4t� t�r�� j|ur�� j| kr�t� j�� t|| � � t� t�r�t� �dkr�t� d ttf�r�t � d| � qH�n�|�rt� tj��rqH�n�t� ttf��sR|� | � | � || � � |sHt|| � � qH�n�| dv �rrt � d | � d ����nrt� t��r�t | | j!�"� � �� �nNt� t#��r@| j$�"| d �\} } } } }}}| d u�s�| d u �s�|�r6z � �%| | j&||| | | | | � W n: t'�y2 } z t(�)d | � d ��|�W Y d }~n d }~0 0 n |�s@J �t� t��r� j*�r�|�s�t� t+��rpg d�}ng d�}� fdd�|D �}t �,d| � d|� dd�-t.dd� |D ���� d���t� t+t/f��s�|� | � t|| � � qH� || < qHd S )Nrz Tr{ z�Use of @declared_attr.cascading only applies to Declarative 'mixin' and 'abstract' classes. Currently, this flag is ignored on mapped class %sr r z�Ignoring declarative-like tuple value of attribute '%s': possibly a copy-and-paste error with a comma accidentally placed at the end of the line?)rY zAttribute name 'z-' is reserved when using the Declarative API.)NNNFNNNz7Could not resolve all types within mapped annotation: "zU". Ensure all types are written correctly and are imported within the module in use.)rg �default_factoryrh �default)rg rc rh c s( h | ] }t � jd |� ��tjur|�qS )Z dataclasses_)r� Z_attribute_optionsr2 r6 �r �a�r� rO rQ � <setcomp>F s ���zF_ClassScanMapperConfig._extract_mappable_attributes.<locals>.<setcomp>r_ r` z# includes dataclasses argument(s): r8 c s s | ]}t |�V qd S rN r9 re rO rO rQ r R rS zF_ClassScanMapperConfig._extract_mappable_attributes.<locals>.<genexpr>zF but class does not specify SQLAlchemy native dataclass configuration.)0rr r� r� r r} r� r� ry r� r r� r� r0 r� r� r� r r� r� r r* r' r� r3 r$ r� r\ r" �popr- r r� �_undefer_column_namer� r� r# r� r� r� � NameError�orm_excZMappedAnnotationErrorZ_has_dataclass_argumentsr& r( r@ rY r% )rP rr r� � our_stuffr Z late_mappedr� Z expect_annotations_wo_mappedZlook_for_dataclass_thingsrF r0 r� r� r� r� r� r� �ne�argnames�argsrO rg rQ r� � s� �� �� ��� � ����� � � �� ��� � ��� �� � �� z3_ClassScanMapperConfig._extract_mappable_attributesc C s2 | j }| j}| j}t�t�}t|�� �D ]�\}}t|t �r�|j }|rN|||< n||= |j D ]N\}} t|t �s|||j �|� |�|� | ||< |d u rZ||jkrZ|||< qZq(t|t�r(|j d us�J �||j �|� |�|� ||jkr(||= q(|�� D ]4\} } t| �dkr�t�d| j| d�t| ��f � q�d S )Nr zzOn class %r, Column object %r named directly multiple times, only one will be used: %s. Consider using orm.synonym insteadr8 )r� r� r� r= r> rW r r? r� r% �mapper_property_to_assign�columns_to_assignr r� �addr� r3 r� r0 r� r� r@ rY ) rP rm r� r� Zname_to_prop_keyr� r� Z mp_to_assign�colZ sort_orderr� �keysrO rO rQ r� l s< ��z0_ClassScanMapperConfig._extract_declared_columnsN)r� rM c s� | j }td|�}| j}| j}| j}| j}| j� t�|�}| j d u �rFd|v�rF|d u �rFt |d�rztt t t �|j��} nt } |d u�r�d} i } |r�t|t�r�|} n4t|t�r�t|d t�r�|dd� |d } } n|} |�d�} | r�| | d< |�d �} | �rd | d < t|� fd d �d�}| �d| || �|�g|�| �R i | ���}nZ|d u �rp| j �rj| �d| � � �}n|j}|�r�|D ]$}|j�|��szt�d|j ���qz|| _ d S )N�MappedClassProtocol[Any]rK � __table_cls__rO ���r Z__autoload_with__� autoload_withZ __autoload__T�autoloadc s � � | d�S )Nr r )r� �r� rO rQ �<lambda>� rS z5_ClassScanMapperConfig._setup_table.<locals>.<lambda>�r� z8Can't add additional column %r when specifying __table__) rr r r� r� r� r� r� r r� r� r� r r4 r0 �unbound_method_to_callablerw r� r r' r� rY r� �_metadata_for_clsrK r� Zcontains_columnr r( r� r� )rP r� rr r" r� r� r� r� r� Z table_clsrp Ztable_kwry rz Zsorted_columnsr� rO r{ rQ r� � s� ��� � ������ ���z#_ClassScanMapperConfig._setup_tablezClassManager[Any]rB )r� rM c C s& t | jdd �}|d ur|S |jjS d S )NrY )r� rr r� rY )rP r� �metarO rO rQ r � s z(_ClassScanMapperConfig._metadata_for_clsr� c C s� | j }|�dd �}|d u r�g }|jD ]0}t|�}|d u r:q$t|�r$||vr$|�|� q$|r�t|�dkrxt�d||f ��|d }nt |t �r�|j }|| _ | j }d|vr�| jd u r�d| _d S )Nr� r r� r rK T)rr r� r� r� r~ r� r� r r� r� r' r� r� r� r� r� )rP r� rr r� r� r� r� r� rO rO rQ r� � s0 �� z/_ClassScanMapperConfig._setup_inheriting_mapperc C s` | j }| j}| j}| j}|d u rF| jd u rFt|d�sFt�d| ���n| j�r\t| j�}|d usdJ �|j }|j }|d u �r\|r�t� d��|r�t |t �s�t� d| j� d| j� d���|D ]�} |d us�J �| j |jv �r|j| j | u r�q�t� d| � d|j� d |j| j � d ���| j�r t� d ��t�r6t |t ��s6J �|�| � |d ur�||ur�|�| � q�d S ) NZ __no_table__zwClass %r does not have a __table__ or __tablename__ specified and does not inherit from an existing table-mapped class.z?Can't place __table_args__ on an inherited class with no table.z9Can't declare columns on single-table-inherited subclass z ; superclass z is not mapped to a TablezColumn 'r` z! conflicts with existing column 'zs'. If using Declarative, consider using the use_existing_column parameter of mapped_column() to resolve conflicts.zDCan't place primary key columns on an inherited class with no table.)r� rr r� r� r� r} r r� rx r� r( r� r4 r� r� rH � primary_keyr � append_columnZ_refresh_for_new_column) rP r� r� rr r� r� Zinherited_mapper_or_config�inherited_tableZ inherited_persist_selectablert rO rO rQ r� st ����� � ���� ��� ���z0_ClassScanMapperConfig._setup_inheriting_columnsc s� �j }�jr��� }ni }|r(|�|� d|v rFt|�}|�|d � dD ]&}||v rJ|| }�j�||�||< qJd|v r��fdd�t�|d �D �|d< d|v r�|d }t|t �r�|j }|�j ur�t � d|d ���j r�j |d< �j �r�|�dd ��s�t�j d �� � j}d |v�rX� fd d �|jD ��� j�p6d � |d < }|�dd� �jD �� t|�� �D ]N\}} t| tj��s~�qd|� jv �rd� j| } t| t��rd| g| j ||< �qd|� � } || d< | �_ d S )Nr� )Zversion_id_colZpolymorphic_onr� c s g | ]}� j �||��qS rO )r� r� )r rG rc rO rQ r | s �zD_ClassScanMapperConfig._prepare_mapper_arguments.<locals>.<listcomp>r� z:mapper inherits argument given for non-inheriting class %sZconcreteF�exclude_propertiesc s h | ]}|� j vr|j�qS rO )Z_columntopropertyr� �r r� )�inherited_mapperrO rQ rh � s �zC_ClassScanMapperConfig._prepare_mapper_arguments.<locals>.<setcomp>rO c S s g | ] }|j �qS rO r} r� rO rO rQ r � rS ) r� r� r& r r� r� r0 Zto_listr� r' r� r� r r� r, r� r� �unionr� �difference_updater� r r? r1 ra Z_propsr( �columns�copyr� ) rP r� r� r� rF rG Z inherits_argr� r� rt �pZresult_mapper_argsrO )r� rP rQ �_prepare_mapper_argumentse sf � �� � � � z0_ClassScanMapperConfig._prepare_mapper_argumentsr� c C sP | � |� t| jd�r,tdt�| jj��}nt}| �d|| j| j fi | j ���S )N�__mapper_cls__zType[Mapper[Any]]rJ ) r� r� rr r r0 r~ r� r' r� r� r� r� rO rO rQ r� � s ���z_ClassScanMapperConfig.map)N)"rH rT rU r� � is_deferredrW r� r� r r �re�compiler r r� r� r� rO rA rQ r, r- r% r� r� r� r r� r� r� r0 r� r� r� rO rO r� rQ r� � sb ML D 0x4H Z F;N!HQr� r� )�field_metadatar rM c C s6 t jj}| | }t|�r.t||j�s.|�|�S |S d S rN )r0 r� r� �callabler� r? )r� r �decl_apir� rO rO rQ r � s r c s� e Zd ZU ded< dZe�� Zded< ddd�d d �Ze d d �d d��Z e j d dd�dd��Z e ddd�dd��Z e d dd�dd��Ze d dd�dd��Ze d d d�dd��Ze d#d dd d �d d ��Zejfdd d�� fd!d"� Z� ZS )$rt zweakref.ref[Type[Any]]�_clsTz?util.OrderedDict[weakref.ref[Type[Any]], _DeferredMapperConfig]�_configsr[ ra r� c C s d S rN rO r� rO rO rQ r� � s z$_DeferredMapperConfig._early_mappingrp rb c C s | � � S rN )r� rc rO rO rQ rr � s z_DeferredMapperConfig.cls)r� rM c C s t �|| j�| _| | j| j< d S rN )�weakref�ref�_remove_config_clsr� r� )rP r� rO rO rQ rr � s )r� rM c C s | j �|d � d S rN )r� ri )rr r� rO rO rQ r� � s z(_DeferredMapperConfig._remove_config_clsry c C s t |t�ot�|�| jv S rN )r� r� r� r� r� �rr r� rO rO rQ ru � s z _DeferredMapperConfig.has_clsr c C s2 t |d�r|�� tj|dt�|�� d�d��d S )N�_sa_raise_deferred_configr� zG has a deferred mapping on it. It is not yet usable as a mapped class.)r[ )r� r� rl ZUnmappedClassErrorZ_safe_cls_namer� rO rO rQ �raise_unmapped_for_cls� s �z,_DeferredMapperConfig.raise_unmapped_for_clsc C s | j t�|� S rN )r� r� r� r� rO rO rQ rv s z$_DeferredMapperConfig.config_for_clszList[_DeferredMapperConfig])�base_cls�sortrM c sr �fdd�dd� | j �� D �D �}|s*|S dd� |D �� g }� D ] �|�� �fdd��jD �� q@tt�||��S )Nc s& g | ] \}}|d urt |� �r|�qS rN )r� )r �mr� )r� rO rQ r s �z:_DeferredMapperConfig.classes_for_base.<locals>.<listcomp>c S s g | ]}||j f�qS rO rw �r r� rO rO rQ r rS c S s i | ] }|j |�qS rO rw r� rO rO rQ r rS z:_DeferredMapperConfig.classes_for_base.<locals>.<dictcomp>c 3 s& | ] }|� v r� | � � fV qd S rN rO )r r� )� all_m_by_cls�m_clsrO rQ r s �z9_DeferredMapperConfig.classes_for_base.<locals>.<genexpr>)r� �values�extendr� r r5 r� )rr r� r� �classes_for_baseZtuplesrO )r� r� r� rQ r� s �� z&_DeferredMapperConfig.classes_for_baser� c s | j �| jd � t� �|�S rN )r� ri r� r� r� r� r� rO rQ r� s z_DeferredMapperConfig.map)T)rH rT rU rW r� r0 r� r� r� �propertyrr �setterr� r� ru r� rv r� r� r� r� rO rO r� rQ rt � s* � �rt zMapperProperty[Any]ra )rr r� r� rM c C s6 d| j v �r$td| �}ddd�dd�}t|t�r\t||� ||�j|dd� |j�||� n�t|t�r�|j }|j D ]6\}}t||� ||�j|dd� |sr|j�||� qr|r�|j�||� ndt|t �r�|j�||� nJt|t ��r |j |k�r t|j �}|j�||� nt�| ||� |j�� nt�| ||� d S ) z�add an attribute to an existing declarative class. This runs through the logic to determine MapperProperty, adds it to the Mapper, adds a column to the mapped Table, etc. rJ rv r4 )�mcrM c S s* t | jt�r| jS t�d| j�d���d S )Nz+Cannot add a new attribute to mapped class z) because it's not mapped against a table.)r� rK r4 r r� rH )r� rO rO rQ �_table_or_raise1 s �z'_add_attribute.<locals>._table_or_raiseT)Zreplace_existingN)r� r r� r3 rj r� rJ Z add_propertyr% rq rr r& r r� r r� � __setattr__�_expire_memoizations)rr r� r� Z mapped_clsr� �mprt rN rO rO rQ �_add_attribute$ s8 � � r� )rr r� rM c C sv d| j v rf|| j v rftd| �jjsf| j | }t|ttttf�rHt d��qrt � | |� td| �j� � n t � | |� d S )NrJ rv z<Can't un-map individual mapped attributes on a mapped class.) r� r rJ Z_dispose_calledr� r3 r% r& r r� r� � __delattr__r� )rr r� r� rO rO rQ �_del_attributeX s( ���� �� � r� )rP �kwargsrM c K sB t | �}|D ]0}t||�s,td||jf ��t| ||| � q dS )a= A simple constructor that allows initialization from kwargs. Sets attributes on the constructed instance using the names and values in ``kwargs``. Only keys that are present as attributes of the instance's class are allowed. These could be, for example, any mapped columns or relationships. z(%r is an invalid keyword argument for %sN)r� r� rR rH r* )rP r� r� rF rO rO rQ �_declarative_constructorp s �r� r� z Column[Any])r� �columnrM c C s$ |j d u r| |_ |jd u r | |_d S rN )r� r� )r� r� rO rO rQ rj � s rj )F)rrV � __future__r r= r� r� �typingr r r r r r r r r r r r r r r r r� � r r r rl r r Z_typingr r r r r� r r Zdescriptor_propsr r Z interfacesr! r" r# r$ r% r& Zmapperr' r� r( r) r0 r* r+ r, r- r/ Zsqlr1 Zsql.baser2 Z sql.schemar3 r4 r5 Z util.typingr6 r7 r8 r9 r: r; r< r= r> r� r? r@ Z sql.elementsrA rB Zsql.selectablerC rD rG r[ Z_TableArgsTyperF rX rf rx r~ r� r} r� r� r� Zpreload_moduler� r� r� r� r� r� r rt r� r� r� rH rj rO rO rO rQ �<module> s� �' Z> M4 sqlalchemy/orm/__pycache__/dynamic.cpython-39.pyc 0000644 00000022123 15125143220 0015763 0 ustar 00 a ��JhX& � @ s d Z ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z dd lm Z dd lm Z dd lm Z dd lm Z d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlm Z d dlm Z d dlm Z d dlm Z ddlmZ ddl m!Z! e �r�d dlm"Z" d d l#m$Z$ d d lm%Z% d d lm&Z& d d l'm(Z( d d lm)Z) dd!l*m+Z+ dd"l,m-Z- e d#ed$�Z.G d%d&� d&e e. �Z/G d'd(� d(e �Z0ej1j2d)d*�G d+d,� d,e ��Z3G d-d.� d.e e. �Z4G d/d0� d0e4e. ee. �Z5d1d2d3�d4d5�Z6d6S )7z�Dynamic collection API. Dynamic collections act like Query() objects for read operations and support basic add/delete mutation. .. legacy:: the "dynamic" loader is a legacy feature, superseded by the "write_only" loader. � )� annotations)�Any)�Iterable)�Iterator)�List)�Optional)�Tuple)�Type)� TYPE_CHECKING)�TypeVar)�Union� )� attributes)�exc)� relationships)�util)� PassiveFlag)�Query)�object_session)�AbstractCollectionWriter)�WriteOnlyAttributeImpl)�WriteOnlyHistory)�WriteOnlyLoader� )�result)�QueryableAttribute)�Mapper)�_RelationshipOrderByArg)�Session)� InstanceState)� AliasedClass)� _Dispatch)� ColumnElement�_T)�boundc @ s$ e Zd Zd dddddd�dd �ZdS ) �DynamicCollectionHistoryN�DynamicAttributeImpl�InstanceState[_T]r z&Optional[DynamicCollectionHistory[_T]]�None)�attr�state�passive�apply_to�returnc C s` |r8t ||��d�}t�|�| _|j| _|j| _d| _n$t�� | _t�� | _t�� | _d| _d S )NFT)� AppenderQuery� autoflushr ZOrderedIdentitySetZunchanged_items� added_itemsZ deleted_itemsZ_reconcile_collection)�selfr) r* r+ r, Zcoll� r2 �K/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/dynamic.py�__init__> s z!DynamicCollectionHistory.__init__)N)�__name__� __module__� __qualname__r4 r2 r2 r2 r3 r% = s �r% c @ s@ e Zd ZU dZee Zded< dddddd d d d d �dd�ZdS )r& TzType[AppenderMixin[Any]]� query_classNz#Union[Type[Any], AliasedClass[Any]]�strz"_Dispatch[QueryableAttribute[Any]]z Mapper[_T]r z!Optional[Type[AppenderMixin[_T]]]r r( )�class_�key�dispatch� target_mapper�order_byr8 �kwr- c K s^ t jj| ||d |fi |�� || _|r0t|�| _|s<t| _n t|� � v rP|| _n t |�| _d S �N) r Z AttributeImplr4 r= �tupler> r. r8 � AppenderMixin�mro�mixin_user_query)r1 r: r; r< r= r> r8 r? r2 r2 r3 r4 W s �� z DynamicAttributeImpl.__init__)N) r5 r6 r7 Z_supports_dynamic_iterationr% r Zcollection_history_cls�__annotations__r4 r2 r2 r2 r3 r& R s �r& Zdynamic)Zlazyc @ s e Zd ZeZdS )� DynaLoaderN)r5 r6 r7 r& Z impl_classr2 r2 r2 r3 rF o s rF c s e Zd ZU dZdZded< ded< ddd d �� fd d � Zed d�dd��Zej dd d�dd��Zdd�dd�Z e r�dd�dd�Z ddd �d d �Z d d�d d!�Zd4d d"d#�d$d%�Zd&d d'�d(d)�Zd*d d+�d,d-�Zd&d d'�d.d/�Zd*d d+�d0d1�Zd*d d+�d2d3�Z� ZS )5rB zTA mixin that expects to be mixing in a Query class with AbstractAppender. NzOptional[Type[Query[_T]]]r8 z Tuple[ColumnElement[Any], ...]�_order_by_clausesr& r' r( )r) r* r- c s" t �| |jd � t� �||� d S r@ )r r4 r= �super)r1 r) r* �� __class__r2 r3 r4 ~ s �zAppenderMixin.__init__zOptional[Session])r- c C sB t | j�}|d ur*|jr*| j|v r*|�� t�| j�s:d S |S d S r@ )r �instancer/ �flush�orm_utilZ has_identity�r1 �sessr2 r2 r3 �session� s zAppenderMixin.sessionr )rP r- c C s || _ d S r@ )rO )r1 rP r2 r2 r3 rP � s z1Union[result.ScalarResult[_T], result.Result[_T]]c C s� | j }|d u rpt�| j�}|jr4t�dt�|� � t j t � | j j jg�t| j �t�| j�tj�j�dd��� S | �|��� S d S )Nz�Instance %s is detached, dynamic relationship cannot return a correct result. This warning will become a DetachedInstanceError in a future release.T)Z_source_supports_scalars)rP r �instance_staterK Zdetachedr �warnrM � state_strr ZIteratorResultZSimpleResultMetaDatar) r: r5 �iter�_get_collection_historyr �PASSIVE_NO_INITIALIZEr0 Zscalars� _generate�_iter)r1 rO r* r2 r2 r3 rX � s( �� ��� zAppenderMixin._iterz Iterator[_T]c C s d S r@ r2 )r1 r2 r2 r3 �__iter__� � zAppenderMixin.__iter__r zUnion[_T, List[_T]])�indexr- c C s@ | j }|d u r,| j�t�| j�tj��|�S | � |�� |�S d S r@ ) rP r) rU r rQ rK r rV ZindexedrW � __getitem__)r1 r[ rO r2 r2 r3 r\ � s ��zAppenderMixin.__getitem__�intc C s> | j }|d u r,t| j�t�| j�tj�j �S | � |�� � S d S r@ ) rP �lenr) rU r rQ rK r rV r0 rW �countrN r2 r2 r3 r_ � s ��zAppenderMixin.countz Query[_T])rO r- c C s~ | j }|d u r:t|�}|d u r:t�dt�|�| jjf ��| jrT| j| jj |d�}n|� | jj �}| j |_ | j |_ | j |_ |S )Nz�Parent instance %s is not bound to a Session, and no contextual session is established; lazy load operation of attribute '%s' cannot proceed)rP )rK r �orm_excZDetachedInstanceErrorrM Z instance_strr) r; r8 r= �queryZ_where_criteriaZ _from_objrG )r1 rO rK ra r2 r2 r3 rW � s ��zAppenderMixin._generatez Iterable[_T])�iteratorr- c C s | � |� dS )a~ Add an iterable of items to this :class:`_orm.AppenderQuery`. The given items will be persisted to the database in terms of the parent instance's collection on the next flush. This method is provided to assist in delivering forwards-compatibility with the :class:`_orm.WriteOnlyCollection` collection class. .. versionadded:: 2.0 N�Z _add_all_impl�r1 rb r2 r2 r3 �add_all� s zAppenderMixin.add_allr# )�itemr- c C s | � |g� dS )ap Add an item to this :class:`_orm.AppenderQuery`. The given item will be persisted to the database in terms of the parent instance's collection on the next flush. This method is provided to assist in delivering forwards-compatibility with the :class:`_orm.WriteOnlyCollection` collection class. .. versionadded:: 2.0 Nrc �r1 rf r2 r2 r3 �add� s zAppenderMixin.addc C s | � |� dS )z�Add an iterable of items to this :class:`_orm.AppenderQuery`. The given items will be persisted to the database in terms of the parent instance's collection on the next flush. Nrc rd r2 r2 r3 �extend s zAppenderMixin.extendc C s | � |g� dS )z�Append an item to this :class:`_orm.AppenderQuery`. The given item will be persisted to the database in terms of the parent instance's collection on the next flush. Nrc rg r2 r2 r3 �append s zAppenderMixin.appendc C s | � |� dS )z�Remove an item from this :class:`_orm.AppenderQuery`. The given item will be removed from the parent instance's collection on the next flush. N)Z _remove_implrg r2 r2 r3 �remove s zAppenderMixin.remove)N)r5 r6 r7 �__doc__r8 rE r4 �propertyrP �setterrX r rY r\ r_ rW re rh ri rj rk � __classcell__r2 r2 rI r3 rB t s( � rB c @ s e Zd ZdZdS )r. z�A dynamic query that supports basic collection storage operations. Methods on :class:`.AppenderQuery` include all methods of :class:`_orm.Query`, plus additional methods used for collection persistence. N)r5 r6 r7 rl r2 r2 r2 r3 r. s r. r ztype[AppenderMixin[Any]])�clsr- c C s d| j }t|t| fd| i�S )zAReturn a new class with AppenderQuery functionality layered over.ZAppenderr8 )r5 �typerB )rp �namer2 r2 r3 rD ) s rD N)7rl � __future__r �typingr r r r r r r r r r � r r r` r r rM �baser ra r rP r Z writeonlyr r r r Zenginer r Zmapperr r r r* r r �eventr! Z sql.elementsr" r# r% r& ZRelationshipPropertyZ strategy_forrF rB r. rD r2 r2 r2 r3 �<module> sT + sqlalchemy/orm/__pycache__/persistence.cpython-39.pyc 0000644 00000066157 15125143220 0016702 0 ustar 00 a ��Jh� � @ s� d Z ddlmZ ddlmZ ddlmZ ddlmZ ddlZddlm Z dd lm Z dd lm Z dd lm Z dd lmZ d d lm Z d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ dDdd�Z dd� Z dd� Z d d � Z d d � Z d d!� Z!dddd"d#�d$d%�Z"ddd"d&�d'd(�Z#d)d*� Z$d+d,� Z%d-dd-d.�d/d0�Z&d-ddd1�d2d3�Z'd4d5� Z(d6d7� Z)d8d9� Z*d:d;� Z+d<d=� Z,d>d?� Z-d@dA� Z.dBdC� Z/dS )Ez�private module containing functions used to emit INSERT, UPDATE and DELETE statements on behalf of a :class:`_orm.Mapper` and its descending mappers. The functions here are called only by the unit of work functions in unitofwork.py. � )� annotations)�chain)�groupby)� zip_longestN� )� attributes)�exc)�loading)�sync)� state_str� )�future)�sql)�util)�cursor)� operators)�BooleanClauseList)� LABEL_STYLE_TABLENAME_PLUS_COLFc C s |s0| j s0t| |�D ]}t| |g|dd� qdS g }g }t| ||�D ]B\}}}} } } } | s^| rt|�|||| | f� qD|�|||| f� qD| j�� D ]J\} }| |jvr�q�t| |�}t || |�}t | ||| |� t | ||| |� q�t | |t dd� |D �dd� |D ��� dS )a; Issue ``INSERT`` and/or ``UPDATE`` statements for a list of objects. This is called within the context of a UOWTransaction during a flush operation, given a list of states to be flushed. The base mapper in an inheritance hierarchy handles the inserts/ updates for all descendant mappers. T)�singleNc s s$ | ] \}}}}||||d fV qdS )FN� )�.0�state� state_dict�mapper� connectionr r �O/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/persistence.py� <genexpr>i s �zsave_obj.<locals>.<genexpr>c s s& | ] \}}}}}||||d fV qdS )TNr )r r r r r �update_version_idr r r r m s �)�batch� _sort_states�save_obj�_organize_states_for_save�append�_sorted_tables�items� _pks_by_table�_collect_insert_commands�_collect_update_commands�_emit_update_statements�_emit_insert_statements� _finalize_insert_update_commandsr )� base_mapper�states�uowtransactionr r �states_to_update�states_to_insert�dict_r r � has_identity� row_switchr �table�insert�updater r r r ( sj � � �������r c sh t t| ||��}| j�� D ]H\�� �� jvr.q� �fdd�|D �}t| |�||�}t| |� �|� qdS )z\Issue UPDATE statements on behalf of a relationship() which specifies post_update. c 3 sH | ]@\}}}}�|j v r||||� jd ur:� �||� j�nd fV qd S �N)r% �version_id_col�#_get_committed_state_attr_by_column)r r r Z sub_mapperr �r r3 r r r � s ����z post_update.<locals>.<genexpr>N)�list� _organize_states_for_post_updater# r$ r% � _collect_post_update_commands� _emit_post_update_statements)r+ r, r- �post_update_colsr. r5 r r9 r � post_update{ s& � � ��r? c C s� t t| ||��}| j}tt |�� ��D ]F}|| }||jvr@q&n|jrN|jrNq&t| |||�}t | ||||� q&|D ] \}} }} } |j � || |� qrdS )z�Issue ``DELETE`` statements for a list of objects. This is called within the context of a UOWTransaction during a flush operation. N) r: �_organize_states_for_deleter# �reversed�keysr% ZinheritsZpassive_deletes�_collect_delete_commands�_emit_delete_statements�dispatchZ after_delete) r+ r, r- �states_to_deleteZtable_to_mapperr3 r �deleter r r r r r r � delete_obj� s8 � ���rH c c sJ t | ||�D �]6\}}}}t|j�}|jp2|�|�}d } } |sR|j�|||� n|j�|||� |jrv|�|||� |s�||jj v r�|jj | } t � | �} |� | �s�|� | �s�t�dt|�|t| �f � n&| �d|t|�t| �� |�| � | } |s�| �r0|jdu�r0|�| �r| n|| �r&| jn||j�} |||||| | fV q dS )aT Make an initial pass across a set of states for INSERT or UPDATE. This includes splitting out into distinct lists for each, calling before_insert/before_update, obtaining key information for each state including its dictionary, mapper, the connection to use for the execution per state, and the identity flag. NzJNew instance %s with identity key %s conflicts with persistent instance %szPdetected row switch for identity %s. will update %s, remove %s from transaction)�_connections_for_states�bool�key�_identity_key_from_staterE Z before_insertZ before_updateZ _validate_polymorphic_identity�sessionZ identity_mapr Zinstance_stateZwas_already_deleted� is_deletedr �warnr Z _log_debugZremove_state_actionsr7 r8 �dict) r+ r, r- r r0 r r r1 Z instance_keyr2 r �instance�existingr r r r! � s\ � � � ��� ��r! c C s t | ||�S )z�Make an initial pass across a set of states for UPDATE corresponding to post_update. This includes obtaining key information for each state including its dictionary, mapper, the connection to use for the execution per state. )rI )r+ r, r- r r r r; # s r; c c s^ t | ||�D ]L\}}}}|j�|||� |jdurD|�|||j�}nd}|||||fV q dS )z�Make an initial pass across a set of states for DELETE. This includes calling out before_delete and obtaining key information for each state including its dictionary, mapper, the connection to use for the execution per state. N)rI rE Z before_deleter7 r8 )r+ r, r- r r0 r r r r r r r@ / s � �r@ r )�bulk�return_defaults� render_nulls�include_bulk_keysc # s� |D �]�\}� }}| |j vr qi } i } |j| } |j| } t| ��� �D ]l} � | }| | }|du rt|| vrt|stqHqH|s�t|d�s�t|tj�r�t|d�r�|� � n|| |< qH|| |j < qH|s�|j | � | �� dd� | D ��D ] }d| |< q�|r�|�r,|j | �| �}|j�|j| ��r&|j| �| �}nd}nd }}|jdu�rp|jdu�rp|j|j| v �rp|�d�| |jj < |�r�|j�r�| �|j|j� |�r�| �� fdd�|D �� |� | ||| ||fV qdS ) zSIdentify sets of values to use in INSERT statements for a list of states. N�__clause_element__c S s g | ] }|j �qS r �rK �r �cr r r � <listcomp>y � z,_collect_insert_commands.<locals>.<listcomp>TFc 3 s | ]}|� | fV qd S r6 r �r �k�r r r r � r\ z+_collect_insert_commands.<locals>.<genexpr>)r% �_propkey_to_colZ _insert_cols_evaluating_none�set� intersection�hasattr� isinstancer � ClauseElementrW rK Z_insert_cols_as_none� differenceZ_pk_keys_by_table�issubsetr+ �_prefer_eager_defaults�dialectZ_server_default_col_keys�version_id_generatorr7 �_cols_by_tableZ_set_polymorphic_identity� setdefaultZ_polymorphic_attr_keyZpolymorphic_identityr5 )r3 r/ rS rT rU rV r r r �params� value_params�propkey_to_colZ eval_none�propkey�value�colZcolkey� has_all_pks�has_all_defaultsr r_ r r& F s� � �� � � �� ������� ��r& )rS �use_orm_update_stmtrV c # s� |D �]�\}�}}} ||j vr q|j | } |dur:|j} ni } |j| �|r|��fdd�t������|j| �D �} d} n�i } t���|j�D ]n}�| }�| }t|d�s�t |t j �r�t|d�r�|� � n|| |< q�|j | j�||j| �dur�|| |j< q�|jjdu �r |j| �| �} nd} | du�r�|j|j| v �r�|�s�| �s�| �s�|j�� D ].}|j |j j�|�tj�}|j �r\ �q��q\q|j}| �o�| }| | |j < |�s�|j| v�r�|j du�r�|� | �}|| |j< n |j du �r |�r | | |j< n| �s | �s qd}d}|�r|��fdd�t���|j| �D �� t j �� �� ��rHt!j"dd �#� fd d �| D ��� d �d d��n�i � | D ]�}|j| j}|j | j�|�tj$�}|j �r|j%�r�d||f| jv �r�d}|j d � |j < | �&|jd� n |j%d � |j < || v �r"d}n|j'd � |j < � |j du �r�t(�)d||f ���q�|�rf| �*�fdd �|D �� | �sr| �r�| �*� � |�| ||| | |fV q|r|j+| D ]"\}}t,�-|||||| |j.� �q�qdS )at Identify sets of values to use in UPDATE statements for a list of states. This function works intricately with the history system to determine exactly what values should be updated as well as how the row should be matched within an UPDATE statement. Includes some tricky scenarios where the primary key of an object might have been changed. Nc s i | ]}� | j �| �qS r rX �r rp �ro r r r � <dictcomp>� s �z,_collect_update_commands.<locals>.<dictcomp>TrW Fc s i | ]}� | j ��|��qS r )�_label�getrv rw r r rx ) s �z,No primary key value supplied for column(s) z, c 3 s$ | ] }� |j d u rt|�V qd S r6 )ry �strrY )� pk_paramsr r r 3 s z+_collect_update_commands.<locals>.<genexpr>zY; per-row ORM Bulk UPDATE by Primary Key requires that records contain primary key valuesZbupq)�codeZ pk_cascadedr zCCan't update table %s using NULL for primary key value on column %sc 3 s | ]}|� | fV qd S r6 r r] r_ r r r \ r\ )/r% Z_valuesr` ra rb rf Z_pk_attr_keys_by_table�committed_staterc rd r re rW �manager�implZis_equalrK r+ �eager_defaultsZ!_server_onupdate_default_col_keysrg r7 rk �_columntoproperty�values� get_historyr �PASSIVE_NO_INITIALIZE�addedry rj r ZNONE_SET�sa_exc�InvalidRequestError�join� PASSIVE_OFFZdeleted�popZ unchanged�orm_exc� FlushErrorr5 �_table_to_equatedr �populate�passive_updates)r- r3 r. rS ru rV r r r r �pksrn rm rt rp rq rr �prop�historyZ no_params�valrs Zexpect_pk_cascaded�m� equated_pairsr )r| ro r r r' � s � ���� �� � ��� ����� ��� ����� ���� �� � �r' c c s, |D �] \}}}}} |j | } i } d} |j| D ]|} | | v rX|j||| tjd�| | j< q0| |v sj| jdur0|j| }|j|j j � ||tj �}|j r0|j d }|| | j < d} q0| r| du�r|j|j| v �r|j} | | | j< t|j ��r| j | v�r|jdu�r|�| �}|| | j < ||||| fV qdS )zrIdentify sets of values to use in UPDATE statements for a list of states within a post_update operation. F)ZpassiveNr T)r% rk Z_get_state_attr_by_columnr r� ry Zonupdater� r rK r� r� r� r� r7 rJ rj )r+ r- r3 r. r> r r r r r r� rm Zhasdatarr r� r� rq r� r r r r< | sP � � � �� ��� r< c c s� |D ]�\}}}}}||j vr qi } |j | D ]6} |�||| � | | j< } | du r,t�d|| f ��q,|dur�|j|j| v r�|| |jj< | |fV qdS )zSIdentify values to use in DELETE statements for a list of states to be deleted.NzHCan't delete from table %s using NULL for primary key value on column %s)r% r8 rK r� r� r7 rk ) r+ r- r3 rF r r r r r rm rr rq r r r rC � s6 � �� ���� rC T)� bookkeepingru �enable_check_rowcountc s � j duo� j � j� v �d| ji}d� ��fdd� } |durH| |�} n| �d�f| �} t|dd� �D �]�\\} } } }}}d}t|�}| }|dur�|��� d ��}d }|s�|j� j� � }d }|r�|s� j j d u r�j r�| j j r�|j� j� � }d }� j�r |�� j �}d }| j j}|�o | j j}| �o.� }| �r�|D ]j\}}}� } }}}| j|�|�||d �}|�r�t� |�||||jjd |d |j� ||j7 }|�o�|} �q:�n |�s |�o�|} |D ]Z\}}}� } }}}| j|||d �}|�r t� |�||||jjd |d |j� ||j7 }�q�n�d d� |D �} |�oF|�pF|�oFt| �dk} | j|| |d �}||j7 }|D ]N\}}}� } }}}|�rft� |�||||jjd |d |jj�s�|jnd� �qf| �r�|t|�k�r�t� d�j t|�|f ��qf�rft � d|j j � qfdS )z`Emit UPDATE statements corresponding to value lists collected by _collect_update_commands().N�compiled_cachec s� t �tj�}� j� D ] }|�|tj|j|j d�k� q�r^|�� j tj� j j� j j d�k� | d urr| � |�}n�� � � |�}|S �N)�type_) r �_construct_rawr �and_r% �_append_inplacer � bindparamry �typer7 �wherer5 )Z existing_stmt�clausesrr �stmt�r �needs_version_idr3 r r � update_stmt� s$ ���� z,_emit_update_statements.<locals>.update_stmtr5 c S s* | d t | d �t| d �| d | d fS �N� r � � � �ra rJ ��recr r r �<lambda> s �z)_emit_update_statements.<locals>.<lambda>r )Z_emit_update_tableZ_emit_update_mapperFT��execution_optionsc S s g | ] }|d �qS �r r �r r� r r r r[ � r\ z+_emit_update_statements.<locals>.<listcomp>r �MUPDATE statement on table '%s' expected to update %d row(s); %d were matched.�MDialect %s does not support updated rowcount - versioning cannot be verified.)N)!r7 rk �_compiled_cache�_memor r: � _annotaterT r% r+ r� �implicit_returningri Zupdate_returningZ _server_onupdate_default_cols�!_version_id_has_server_side_value�supports_sane_rowcount� supports_sane_multi_rowcount�executer� � _postfetch�context�compiled_parameters�returned_defaults�rowcount�len� executemanyr� �StaleDataError� descriptionr rO �dialect_description) r+ r- r r3 r5 r� ru r� r� r� � cached_stmtr Z paramkeys�hasvaluert rs �records�rows� statementrT �assert_singlerow�assert_multirow�allow_executemanyr r rm rn rZ �check_rowcount� multiparamsr r� r r( � s: � �� ���� ��� � � �� � �� � �� � � �����r( )r� �use_orm_insert_stmtr� c % C s� |dur,|}t j} t|j�} | r&|jp(|} n$d} |} | �d|f|j�}d| ji} |rdt j�| |�}n| }d} t |dd� �D �]\\} }}}}}|}|dur�|� ||d��}|r�|s�| � | j |�r�|j r�| j j�sx| �sx|�rx|�sxt|�}dd � |D �}| j|||d �}|�r�t||jj�D ]X\\}}}}}}}}} |�rft||||||| |d|jj�s^|jnd� n t|||� �q qzt|�}| �s�|j �r|�st|�d k�r| �r�| j j�s�| �s�| j j�r�d } n8| �r�| �r�d } nd} t� d| j j � d| � d���nd} nd} |du �r<|�s<| � | j |��r<|j |j | d|i�}|j du�rZ|j |j |d�}n| �rr|j |j!d|i�}| �r�dd � |D �}| j|||d �}|du�r�| du �r�|} n | �"|�} |�r�t#||jj|j$|j%�p�d�D ]�\\}}}}}}}}} } } | du �rt&�'d| ��t| |j(| �D ]0\}!}"|j)|" }#|�*|#j+�du �r |!||#j+< �q |�rtt||||||| |d| � n t|||� �q�qz| �r�J �|D ]�\}}}}} }}}|�r�| j|�,|�||d �}n| j|||d �}|j-}$|$du �r�t&�'d|f ��t|$|j(| �D ]:\}!}"|j)|" }#|"|v �s4|�*|#j+�du �r|!||#j+< �q|�r�|�r�t|||||||jjd |d|jj�sz|jnd� n t|||� �q�qz|du�r�| du �r�t.�/� S | S dS )z`Emit INSERT statements corresponding to value lists collected by _collect_insert_commands().NFr4 r� c S s* | d t | d �t| d �| d | d fS r� r� r� r r r r� � s �z)_emit_insert_statements.<locals>.<lambda>)Z_emit_insert_tableZ_emit_insert_mapperc S s g | ] }|d �qS r� r r� r r r r[ r\ z+_emit_insert_statements.<locals>.<listcomp>r� r Tz+ with RETURNING and sort by parameter orderz with RETURNINGz<Can't use explicit RETURNING for bulk INSERT operation with z backend; executemanyz! is not enabled for this dialect.�sort_by_parameter_order)r� c S s g | ] }|d �qS r� r r� r r r r[ u r\ r z�Multi-row INSERT statement for %s did not produce the correct number of INSERTed rows for RETURNING. Ensure there are no triggers or special driver issues preventing INSERT from functioning properly.z�Single-row INSERT statement for %s did not produce a new primary key result being invoked. Ensure there are no triggers or special driver issues preventing INSERT from functioning properly.r )0r � EMPTY_DICTrJ Z _returningZ_sort_by_parameter_orderr� r4 r� Z merge_withr r� rh ri r� Zinsert_returningr: r� �zipr� r� r� r� r� �_postfetch_bulk_saver� Z4insert_executemany_returning_sort_by_parameter_orderZ insert_executemany_returningr� r� r� rT Z_server_default_colsr7 � primary_keyZsplice_verticallyr Zinserted_primary_key_rowsZreturned_defaults_rowsr� r� r% r� rz rK r� �inserted_primary_key�_cursorZnull_dml_result)%r+ r- r r3 r4 r� r� r� r� Zexec_optZ returning_is_required_anywayZdeterministic_results_reqdZ return_resultr �_r� rs rt r� r� r� �resultr r rm � mapper_rec�connrn Zlast_inserted_paramsZdo_executemany�dtr� r� �pkrr r� r� r r r r) � s� �� ��� �� ����� � � ��� �� ��� �������� ����� ���� �� �� � � ��� �� � �� � � r) c s� d| j i}� jduo"� j� j� v �� ��fdd�}| �d�f|�}� jrV|�� j�}t|dd� �D �]F\}} d} t| �} |d } | jj } | o�| jj } � p�| }|s�| }| D ]D\}}}} }| j |||d �}t ||�||||j jd � | |j7 } q�nrd d � | D �}| �p| �ot|�d k}| j |||d �}| |j7 } | D ],\}}}} }t ||�||||j jd � �q8|�r�| t| �k�r�t�d �jt| �| f ��qd�rdt�d|jj � qddS )zeEmit UPDATE statements corresponding to value lists collected by _collect_post_update_commands().r� Nc sp t �tj�} � j� D ] }| �|tj|j|j d�k� q�r^| �� j tj� j j� j j d�k� �� � � | �}|S r� ) r r� r r� r% r� r r� ry r� r7 r5 r� )r� rr r� r� r r r� s ����z1_emit_post_update_statements.<locals>.update_stmtr? c S s | d t | d �fS )N� r� )ra r� r r r r� 3 r\ z._emit_post_update_statements.<locals>.<lambda>r r� c S s g | ]\}}}}}|�qS r r )r r r r� r� rm r r r r[ S s �z0_emit_post_update_statements.<locals>.<listcomp>r r� r� )r� r7 rk r� r� rT r r: ri r� r� r� �_postfetch_post_updater� r� r� r� r� r� r� r rO r� )r+ r- r r3 r5 r� r� r� rK r� r� r r� r� r� r� r r r� rm rZ r� r r� r r= s� � �� � � ��� � ����r= c s` � j duo� j � j� v �� ��fdd�}| �d�f|�}t|dd� �D �]\}}dd� |D �} d | ji} t| �} d } d } �r�|jjs�|jjr�d } | D ] }|j ||| d �}| |j 7 } q�q�t � d|jj � |j || | d � n |j || | d �}�s�d} |j } | jrH| d krH| | krH|jj�s&t| �dkrH| �rDt � d�j| | f � qHt�d�j| | f ��qHdS )z`Emit DELETE statements corresponding to value lists collected by _collect_delete_commands().Nc sl t �tj�} � j� D ] }| �|tj|j|j d�k� q�r^| �� j tj� j j� j j d�k� �� � � | �S r� ) r r� r r� r% r� r r� rK r� r7 rG r� )r� rr �r Zneed_version_idr3 r r � delete_stmt� s � ���z,_emit_delete_statements.<locals>.delete_stmtrG c S s | d S )Nr r r� r r r r� � r\ z)_emit_delete_statements.<locals>.<lambda>c S s g | ] \}}|�qS r r )r rm r r r r r[ � r\ z+_emit_delete_statements.<locals>.<listcomp>r� ���Fr r� zMDialect %s does not support deleted rowcount - versioning cannot be verified.Tr z�DELETE statement on table '%s' expected to delete %d row(s); %d were matched. Please set confirm_deleted_rows=False within the mapper configuration to prevent this warning.)r7 rk r� r r� r� ri r� r� r� r� r rO r� Zconfirm_deleted_rowsr� r� r� )r+ r- r r3 rG r� r� r ZrecsZ del_objectsr� �expectedZ rows_matchedZ only_warnrm rZ r r� r rD | sr � ����������� � �� ��rD c s, |D �] \� }}}}|j rF� �� fdd�|j D ��}|rF� �� j|� g }| jdu rh|�� j�|j�� |j dur�|j du r�|j j � j v r�|�|j j g� |r�| �� �� _ t�|��t�} tj|j| � j � |d� |s�|j�||� � n|j�||� � |j du r|j dur||j j du rt�d��qdS )zzfinalize state on states that have been inserted or updated, including calling after_insert/after_update events. c sB g | ]:}|j r |jr8|j� jv s8|j s|js|j� jvr|j�qS r )Zexpire_on_flush�deferredrK rP )r �p�r r r r[ � s �z4_finalize_insert_update_commands.<locals>.<listcomp>TNF)Z refresh_stateZonly_load_propsz2Instance does not contain a non-NULL version value)Z_readonly_propsZunmodified_intersection�_expire_attributesrP r� �extendZ_unloaded_non_objectrb Z&_server_default_plus_onupdate_propkeysr7 rj Z_version_id_proprK ZunloadedrL r �selectZset_label_styler r Z load_on_identrM rE Z after_insertZ after_updater� r� ) r+ r- r, r r r r1 �readonlyZ toload_nowr� r r� r r* � sZ �� ���� �� ���r* c s� � j d uo� j � j| v }|�|�s:|jjj}|jjj} n|rHd }} nd S |r`t|�� j g }t� j j j �} | rvg } |D ]D} | j |v rz| � j v rz|| j |� j | j < | rz| �� j | j � qz| r�| rڈ j j � ||| � | r�|�|j� fdd�| D �� d S )Nr c s" g | ]}|� j v r� j | j�qS r �r� rK rY �r r r r[ T s �z*_postfetch_post_update.<locals>.<listcomp>)r7 rk rN r� �compiled�prefetch� postfetchr: rJ � class_managerrE � refresh_flushrK r� r" r� rP ) r r- r3 r r0 r� rm r� � prefetch_cols�postfetch_colsr� �load_evt_attrsrZ r r� r r� * s< � � ��r� c s� |j jj} |j jj} |j jj�� jdurH� j� j| v rHt| �� jg } t� j j j �} | r^g } �r�| }|dur�t |��D ]B\}}|j r�|j jr�qx� j�|�}|rx|||j< | rx| �|j� qx| D ]N}|j|v r�|� jv r�� j| j}||j ||< |j�|d� | r�| �|� q�| �r.| �r.� j j � ||| � |�rR|�rR| ��fdd�|D �� | �rt|�|j� fdd�| D �� � j| D ]"\}}t�||||||� j� �q~dS )z�Expire attributes in need of newly persisted database state, after an INSERT or UPDATE statement has proceeded for that state.Nc s g | ]}|j r|� vr|�qS r )r� )r rr )�returning_colsr r r[ � s �z _postfetch.<locals>.<listcomp>c s" g | ]}|� j v r� j | j�qS r r� rY r� r r r[ � s �) r� r� r� r� Zeffective_returningr7 rk r: rJ r� rE r� r� r� Zisinsertr� rz rK r" r~ r� r� r� rP r� r r� r� )r r- r3 r r0 r� rm rn Zisupdater� r� r� r� r� �rowZ row_valuerr r� rZ �pkeyr� r� r )r r� r r� \ sp �� � �� �� �r� c C s& | j | D ]\}}t�|||� q d S r6 )r� r Zbulk_populate_inherit_keys)r r0 r3 r� r� r r r r� � s r� c c s` |j jr|j j}n|j�| �}d}t| |�D ].}|rB|| |�� �}|jj}||j||fV q,dS )z�Return an iterator of (state, state.dict, mapper, connection). The states are sorted according to _sort_states, then paired with the connection they should be using for the given unit of work transaction. N) rM �connection_callableZ transactionr r �objr r rP )r+ r- r, r� r r r r r r rI � s rI c C s~ t |�}dd� |D �}|�|� zt|| jd�}W n4 tyf } z t�d| �|�W Y d }~n d }~0 0 t|t�d�d�| S )Nc S s h | ]}|j d ur|�qS r6 rX )r �sr r r � <setcomp>� r\ z _sort_states.<locals>.<setcomp>rX z^Could not sort objects by primary key; primary key values must be sortable in Python (was: %s)Z insert_order) ra �difference_update�sortedZ_persistent_sortkey_fn� TypeErrorr� r� �operator� attrgetter)r r, �pending� persistentZpersistent_sorted�errr r r r � s& � �����r )F)0�__doc__� __future__r � itertoolsr r r r � r r r� r r �baser r� r r r Zenginer r� r Z sql.elementsr Zsql.selectabler r r? rH r! r; r@ r& r' r< rC r( r) r= rD r* r� r� r� rI r r r r r �<module> sn S-+P � j� R6-� r� FvcK2j sqlalchemy/orm/__pycache__/context.cpython-39.pyc 0000644 00000174063 15125143220 0016036 0 ustar 00 a ��Jh�� � @ s� d dl mZ d dlZd dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlm Z d d lm Z d d lm Z d d lm Z d d lm Z d d lmZ d dlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z ddlm Z ddlm Z ddlm Z dd lm Z dd lm!Z! d d lm"Z# d d lm$Z$ d d!lm%Z% d d"lm&Z& d d#lmZ d d$l&m'Z' d d%l&m(Z( d d&l&m)Z) d d#l&mZ* d d'l&m+Z+ d d(l,m-Z- d d)l,m.Z. d d*l,m/Z/ d d+l,m0Z0 d d,l1m2Z2 d d-l1m3Z3 d d.l1m4Z4 d d/l1m5Z5 d d0l1m6Z6 d d1l1m7Z7 d d2l8m9Z9 d d3l:m;Z; d d4l:m<Z< d d5l=m>Z> d d6l=m?Z? d d7l=m@Z@ d d8l=mAZA d d9l=mBZB d d:l=mCZC d d;l=mDZD d d<l=mEZE d d=lFmGZG e �r�dd>lHmIZI dd?lHmJZJ dd@lmKZK ddAlLmMZM ddBlNmOZO ddClPmQZQ ddDlPmRZR d dElSmTZT d dFlUmVZV d dGl,mWZW d dHlXmYZY d dIl8mZZZ d dJl:m[Z[ d dKl=m\Z\ d dLl=m]Z] d dMl=m^Z^ d dNl=m_Z_ d dOl=m`Z` d dPlambZb edQedR�ZcejdZee�f� ZgeCjhZhG dSdT� dT�Zie�fdUdVi�ZjG dWdX� dXe4�ZkG dYdZ� dZek�ZlG d[d\� d\ek�ZmG d]d^� d^�ZnG d_d`� d`en�ZoG dadb� dben�Zpe&jj4�qdcdd�G dedf� dfem��ZrG dgdh� dhe;e6eEe- �Zse&jj4�qdcdi�G djdk� dkele>��Zte&jj4�qdcdl�G dmdn� dnemeD��Zud�dpdqdrdsdt�dudv�Zvdwdxdy�dzd{�Zwdwdxdy�d|d}�Zxd�d~dxdd��d�d��ZyG d�d�� d��ZzG d�d�� d�ez�Z{G d�d�� d�ez�Z|G d�d�� d�ez�Z}G d�d�� d�e}�Z~G d�d�� d�e}�ZG d�d�� d�e�Z�dS )�� )� annotationsN)�Any)�cast)�Dict)�Iterable)�List)�Optional)�Set)�Tuple)�Type)� TYPE_CHECKING)�TypeVar)�Union� )� attributes)� interfaces)�loading)�_is_aliased_class)�ORMColumnDescription)�ORMColumnsClauseRole)� PathRegistry)�_entity_corresponds_to)�_ORMJoin)�_TraceAdaptRole)� AliasedClass)�Bundle)� ORMAdapter)�ORMStatementAdapter� )�exc)�future)�inspect)�sql)�util)� coercions)� expression)�roles)�visitors)�_TP)�is_dml)�is_insert_update)�is_select_base)�_select_iterables)�CacheableOptions)� CompileState)� Executable)� Generative)�Options)� UpdateBase)�GroupedElement)� TextClause)�CompoundSelectState)� LABEL_STYLE_DISAMBIGUATE_ONLY)�LABEL_STYLE_NONE)� LABEL_STYLE_TABLENAME_PLUS_COL)�Select)�SelectLabelStyle)� SelectState)�TypedReturnsRows)�InternalTraversal)�_InternalEntityType)�OrmExecuteOptionsParameter)�PostLoad)�Mapper)�Query)�_BindArguments)�Session)�Result)�_CoreSingleExecuteParams)�_ColumnsClauseArgument)� SQLCompiler)�_DMLTableElement)� ColumnElement)�_JoinTargetElement)�_LabelConventionCallable)�_SetupJoinsElement)�ExecutableReturnsRows)� SelectBase)� TypeEngine�_T)�boundc @ sf e Zd ZU dZded< ded< ded< G dd � d e�Zdd d d d ddddd�dd�Zd d�dd�Zd S )� QueryContext)�top_level_context� compile_state�query�user_passed_query�params� load_options�bind_arguments�execution_options�session� autoflush�populate_existing�invoke_all_eagers� version_check� refresh_state�create_eager_joins�propagated_loader_optionsr �runidZpartials�post_load_paths�identity_token� yield_per�loaders_require_buffering�loaders_require_uniquing�intrd z Dict[PathRegistry, PostLoad]re �ORMCompileStaterU c @ s< e Zd ZdZdZdZdZdZdZdZ dZ dZ dZ dZ dZdS )z!QueryContext.default_load_optionsFTN)�__name__� __module__� __qualname__Z_only_return_tuples�_populate_existing�_version_check�_invoke_all_eagers� _autoflush�_identity_token� _yield_per�_refresh_stateZ_lazy_loaded_fromZ_legacy_uniquing�_sa_top_level_orm_contextZ_is_user_refresh� rw rw �K/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/context.py�default_load_options� s ry Nr. �2Union[Select[Any], FromStatement[Any], UpdateBase]rF rD zQUnion[Type[QueryContext.default_load_options], QueryContext.default_load_options]z$Optional[OrmExecuteOptionsParameter]zOptional[_BindArguments])rU � statementrW rX r\ rY r[ rZ c s� |� _ |p t� _|pt� _|� _|� _|� _|� _d� _d� _ |� _ |j � _ |j j} |j} t� fdd�t| | �D ��� _t|j�� _|j� _|j� _|j� _|j� _|j � _ |j � _ |j � _!d S )NFc 3 s$ | ] \}}|j r|�� |�V qd S �N)Zpropagate_to_loadersZ'_adapt_cached_option_to_uncached_option)�.0�optZ uncached_opt��selfrw rx � <genexpr>� s �z(QueryContext.__init__.<locals>.<genexpr>)"rY � _EMPTY_DICTr[ rZ rU rV rW r\ rh ri rX rv rT �select_statement� _with_options�tuple�ziprc �dictr rr r] ro r^ rq r_ rp r` ru ra rt rg rs rf ) r� rU r{ rW rX r\ rY r[ rZ Zcached_optionsZuncached_optionsrw r rx �__init__� s0 � zQueryContext.__init__��returnc C s | j p| S r| )rT r rw rw rx �_get_top_level_context� s z#QueryContext._get_top_level_context)NN) rl rm rn � __slots__�__annotations__r1 ry r� r� rw rw rw rx rS f s � BrS Z _result_disable_adapt_to_contextTc sb e Zd ZdZdd� Zeddddd�� fd d � �Zed d � �Zed d�dd��Zedd� �Z � Z S )�AbstractORMCompileStateFc C s� i | _ |d u r i | _|s J �d S |j | _}|r\d|d< |rX|jD ]}|jrB|�| � qBd S |�dd�rld S |jd }z |d }W n ty� Y n$0 |jD ]}|j r�|jr�|�| � q�d|d< d S )NTZ toplevel_ormFr � selectable) r �global_attributesZ_global_attributesr� Z_is_criteria_option�process_compile_state�get�stack�KeyError�_is_compile_state) r� r{ �compiler�toplevel� process_criteria_for_toplevel�gar~ Zstack_0Z toplevel_stmtrw rw rx �_init_global_attributes� s0 z/AbstractORMCompileState._init_global_attributesr/ rH r r. �r{ r� �kwr� c s t � j||fi |��S )a� Create a context for a statement given a :class:`.Compiler`. This method is always invoked in the context of SQLCompiler.process(). For a Select object, this would be invoked from SQLCompiler.visit_select(). For the special FromStatement object used by Query to indicate "Query.from_statement()", this is called by FromStatement._compiler_dispatch() that would be called by SQLCompiler.process(). )�super�create_for_statement��clsr{ r� r� �� __class__rw rx r� s z,AbstractORMCompileState.create_for_statementc C s t � �d S r| ��NotImplementedError)r� r\ r{ rX r[ rZ � is_pre_eventrw rw rx �orm_pre_session_exec s z,AbstractORMCompileState.orm_pre_session_execrE r� c C s( |j ||p i |d�}| �||||||�S )N)r[ )�execute�orm_setup_cursor_result)r� r\ r{ rX r[ rZ �conn�resultrw rw rx �orm_execute_statement( s ��z-AbstractORMCompileState.orm_execute_statementc C s t � �d S r| r� �r� r\ r{ rX r[ rZ r� rw rw rx r� > s z/AbstractORMCompileState.orm_setup_cursor_result) rl rm rn �is_dml_returningr� � classmethodr� r� r� r� � __classcell__rw rw r� rx r� � s ' r� c @ s( e Zd ZdZedd� �Zedd� �ZdS )� AutoflushOnlyORMCompileStatez>ORM compile state that is a passthrough, except for autoflush.c C s4 t j�ddh||j�\}}|s,|jr,|�� ||fS )N�_sa_orm_load_optionsr] )rS ry �from_execution_options�_execution_optionsrr )r� r\ r{ rX r[ rZ r� rY rw rw rx r� N s ��� z1AutoflushOnlyORMCompileState.orm_pre_session_execc C s |S r| rw r� rw rw rx r� k s z4AutoflushOnlyORMCompileState.orm_setup_cursor_resultN)rl rm rn �__doc__r� r� r� rw rw rw rx r� K s r� c @ sB e Zd ZU G dd� de�Zded< ded< ded< ded< d ed < d ed < d ed< ded< ded< ded< ded< ded< ded< ded< eZd ed < d Zd d � Z e d!d"d#d d$�d%d&��Z e d'dd(d#d d)�d*d+��Z d,d-� Z e d.ddd/�d0d1��Ze d2d3� �Ze d4d5� �Ze d6d7� �Zed8d9� �Zd:d;� Zd<d=� Ze d>d?� �Zd@S )Ark c @ s� e Zd Zdejfdejfdejfdejfdejfdejfdejfdejfd ejfd ejfd ejfg Zd Zd Z d Z e Z d Z d ZdZd Zd Zd Zd ZdS )z'ORMCompileState.default_compile_options�_use_legacy_query_style�_for_statement�_bake_ok� _current_path�_enable_single_crit�_enable_eagerloads�_only_load_props�_set_base_alias�_for_refresh_state�_render_for_subquery�_is_starFTN)rl rm rn r= Z dp_boolean�dp_has_cache_keyZ dp_plain_obj�_cache_key_traversalr� r� r� �_path_registryr� r� r� r� r� r� r� r� rw rw rw rx �default_compile_optionsy s. �r� zDict[Any, Any]r r� rz r{ r� �List[_QueryEntity]� _entitiesz%Dict[_InternalEntityType, ORMAdapter]�_polymorphic_adaptersz=Union[Type[default_compile_options], default_compile_options]�compile_optionszOptional[_QueryEntity]�_primary_entity�bool�use_legacy_query_stylerL �_label_conventionzList[ColumnElement[Any]]�primary_columns�secondary_columnszSet[ColumnElement[Any]]�dedupe_columnszList[Tuple[Any, ...]]rb r � current_pathFc O s t � �d S r| r� )r� �argr� rw rw rx r� � s zORMCompileState.__init__r/ rH r r� c K s" | j td|�f|j |d�|��S )N� Union[Select, FromStatement])r� r� )�_create_orm_contextr r� r� rw rw rx r� � s ���z$ORMCompileState.create_for_statementr� �Optional[SQLCompiler]�r{ r� r� r� r� c K s t � �d S r| r� )r� r{ r� r� r� rw rw rx r� � s z#ORMCompileState._create_orm_contextc C s& | j }||vr"|�|� |�|� d S r| )r� �add�append)r� �objZcol_collectionZdeduperw rw rx � _append_dedupe_col_collection� s z-ORMCompileState._append_dedupe_col_collectionr: )� label_style�legacyr� c C s |rddd�}|S t �|�S d S )Nc S s |r|S t | d�S d S )N�key)�getattr)�col�col_namerw rw rx �name� s z7ORMCompileState._column_naming_convention.<locals>.name)N)r; �_column_naming_convention)r� r� r� r� rw rw rx r� � s z)ORMCompileState._column_naming_conventionc C s t |�S r| )�_column_descriptions�r� r{ rw rw rx �get_column_descriptions� s z'ORMCompileState.get_column_descriptionsc C s t j�dh d�||j�\}}d|v r>|d }|jj�|j|�}|sHt}n |�t�}|j rh|�d|j i�}t |j dd �r�t |j j �dkr�|�dd�d ur�|�d d d ��}||d < z|jd } W n ty� d s�J d��Y n0 | r�| j|d< |s�|jr�|�� ||fS )Nr� > �sa_top_level_orm_contextr] r^ rg rf r� rg r� � �compiled_cacheTz#excess depth for ORM loader options)r� Z_cache_disable_reason�clause�plugin_subjectFz0statement had 'orm' plugin but no plugin_subject�mapper)rS ry r� r� rV Z merge_withr[ �_orm_load_exec_options�unionrt r� �_compile_options�lenr� r� �_propagate_attrsr� r� rr ) r� r\ r{ rX r[ rZ r� rY �ctxr� rw rw rx r� � sV ��� � ������ z$ORMCompileState.orm_pre_session_execc C sJ |j }|jj}|�dtj�} |jjr(|S t|||||| ||�} t� || �S )Nr� ) �contextZcompiledrU r� rS ry r� r� r Z instances) r� r\ r{ rX r[ rZ r� Zexecution_contextrU rY Z querycontextrw rw rx r� E s$ �� z'ORMCompileState.orm_setup_cursor_resultc C s dd� | j D �S )z�return all _MapperEntity objects in the lead entities collection. Does **not** include entities that have been replaced by with_entities(), with_only_columns() c S s g | ]}t |t�r|�qS rw �� isinstance� _MapperEntity�r} �entrw rw rx � <listcomp>r s z9ORMCompileState._lead_mapper_entities.<locals>.<listcomp>)r� r rw rw rx �_lead_mapper_entitiesj s �z%ORMCompileState._lead_mapper_entitiesc C sD |j s@|jj| jvr@|j�� D ] }| �|ttj||j |d�� q dS )a5 given MapperEntity or ORMColumnEntity, setup polymorphic loading if called for by the Mapper. As of #8168 in 2.0.0rc1, polymorphic adapters, which greatly increase the complexity of the query creation process, are not used at all except in the quasi-legacy cases of with_polymorphic referring to an alias and/or subquery. This would apply to concrete polymorphic loading, and joined inheritance where a subquery is passed to with_polymorphic (which is completely unnecessary in modern use). )� equivalentsr� N) �is_aliased_classr� �persist_selectabler� �iterate_to_root�"_mapper_loads_polymorphically_withr r ZWITH_POLYMORPHIC_ADAPTER�_equivalent_columns)r� �ext_infor� �mprw rw rx � _create_with_polymorphic_adapterv s �����z0ORMCompileState._create_with_polymorphic_adapterc C s: |j p |gD ](}|| j|< |�� D ]}|| j|j< q"q d S r| )�_with_polymorphic_mappersr� r� � local_table)r� r� �adapter�m2�mrw rw rx r� � s z2ORMCompileState._mapper_loads_polymorphically_withc C s t d��d S )Nz0this method only works for ORMSelectCompileStater� )r� rV r� rw rw rx �_create_entities_collection� s �z+ORMCompileState._create_entities_collectionN)rl rm rn r- r� r� r� r� �_has_mapper_entitiesr� r� r� r� r� r� r� r� r� �propertyr� r r� r rw rw rw rx rk x sJ % Y $ rk c @ s, e Zd ZdZdZdd� Zdd� Zdd� Zd S ) �_DMLReturningColFilterz�a base for an adapter used for the DML RETURNING cases Has a subset of the interface used by :class:`.ORMAdapter` and is used for :class:`._QueryEntity` instances to set up their columns as used in RETURNING for a DML statement. )r� �columns� __weakref__c C s: |d ur |j |j ur || _n|| _t�| j� | _| _d S r| )r r� r# ZWeakPopulateDict�adapt_check_presentr )r� � target_mapperZimmediate_dml_mapperrw rw rx r� � s ����z _DMLReturningColFilter.__init__c C s. t �|�D ] }| �|�}|d ur | S q d S r| )�sql_utilZ _find_columnsr )r� r� � as_filter�cc�c2rw rw rx �__call__� s z _DMLReturningColFilter.__call__c C s t � �d S r| r� )r� r� rw rw rx r � s z*_DMLReturningColFilter.adapt_check_presentN)rl rm rn r� r� r� r r rw rw rw rx r � s r c @ s e Zd ZdZdd� ZdS )� _DMLBulkInsertReturningColFiltera[ an adapter used for the DML RETURNING case specifically for ORM bulk insert (or any hypothetical DML that is splitting out a class hierarchy among multiple DML statements....ORM bulk insert is the only example right now) its main job is to limit the columns in a RETURNING to only a specific mapped table in a hierarchy. c C s. | j }|j�|d �}|d u r d S |jj�|�S r| )r� �_columntopropertyr� r �c�corresponding_column�r� r� r� �proprw rw rx r � s z4_DMLBulkInsertReturningColFilter.adapt_check_presentN�rl rm rn r� r rw rw rw rx r � s r c @ s e Zd ZdZdd� ZdS )�"_DMLUpdateDeleteReturningColFiltera_ an adapter used for the DML RETURNING case specifically for ORM enabled UPDATE/DELETE its main job is to limit the columns in a RETURNING to include only direct persisted columns from the immediate selectable, not expressions like column_property(), or to also allow columns from other mappers for the UPDATE..FROM use case. c C s. | j }|j�|d �}|d ur*|jj�|�S |S r| )r� r r� r� r r r rw rw rx r � s z6_DMLUpdateDeleteReturningColFilter.adapt_check_presentNr rw rw rw rx r � s r Zorm�orm_from_statementc @ s| e Zd ZU dZdZded< ded< dZded< dZdZdZ dZ e Z e Z ed d d d d d �dd��Zdd� Zdd� Zdd� ZdS )� ORMFromStatementCompileStateNF� FromStatement�statement_containerz)Union[SelectBase, TextClause, UpdateBase]�requested_statementzOptional[_DMLTableElement]� dml_tabler� r� r� r r� c K s |}t |t�sJ �|d ur*|jr*t�d��| �| �}d |_|jj|_ | |_ |_ |j |_ }|jrp|j|_d|_g |_i |_|j|_|j r�t |tj�r�|js�|js�|jtu r�|�t�|_ n||_ |� |js�|js�|jnt|j �|_ t j ||j!|jdd� |jj"|_#|j$||ddd� |j%�r<|j%D ]}|j&�r"|�'|� �q"|j(�r^|j(D ]\}} ||� �qJg |_)g |_*t+� |_,g |_-g |_.d |_/t |j tj0��r�i |_1|jD ]} | �2|� �q�d |_3|_4d|_5|j)D ]} |j6| d|j7d� �q�nt8t9j:|j |j;d�|_<|S )Nz�The ORM FromStatement construct only supports being invoked as the topmost statement, as it is only intended to define how result rows should be returned.T��is_current_entitiesF)r� r� )Zwithin_columns_clauseZadd_to_result_map)Zadapt_on_names)=r� r r� �sa_exc� CompileError�__new__r� r� r� r� r r� �elementr r) �tabler r� r� r� r� r% rO Z _is_textual� _label_styler7 Zset_label_styler8 r{ r� r� � _QueryEntity�to_compile_state� _raw_columnsr� r� r� r� r� r� �_with_context_optionsr� r� �setr� rb �_fallback_from_clauses�order_byr4 �extra_criteria_entities�setup_compile_stateZ_ordered_columnsZ_textual_ordered_columnsZ_loose_column_name_matching�processZ_add_to_result_mapr r ZADAPT_FROM_STATEMENT�_adapt_on_names�_from_obj_alias) r� r{ r� r� r� r r� r~ �fnr� �entityr rw rw rx r� s� � � � �������� � � � � �z0ORMFromStatementCompileState._create_orm_contextc C s |S r| rw �r� �cols�current_adapterrw rw rx �_adapt_col_list� s z,ORMFromStatementCompileState._adapt_col_listc C s d S r| rw r rw rw rx �_get_current_adapter� s z1ORMFromStatementCompileState._get_current_adapterc C s� | j j�dd�}| j jr$t||�}n | j js4| j jr@t||�}nd}| jj rdt | j �dkrdt � d��| j D ]}|�| |� qjdS )zused by BulkORMInsert, Update, Delete to set up a handler for RETURNING to return ORM objects and expressions r� Nr �sCan't generate ORM query that includes multiple expressions at the same time as '*'; query for '*' alone if present)r{ r� r� � is_insertr � is_update� is_deleter r� r� r� r� r# r$ �!setup_dml_returning_compile_state)r� Z dml_mapperr r r6 rw rw rx r@ � s$ ���� z>ORMFromStatementCompileState.setup_dml_returning_compile_state)rl rm rn r4 r r� r �_has_orm_entities�multi_row_eager_loaders�eager_adding_joins�compound_eager_adapterr� r0 � eager_joinsr� r� r: r; r@ rw rw rw rx r � s" r c s� e Zd ZU dZdZejZejZ dZ de d< de d< de j fde jfgej Zed e jfg Zd Zd d ddd �d d�Zdd� Zedd� �Zdd� Z� fdd�Zedd� �Zedd� �Z edd � �Z ed d � �Z � Z S ) r a* Core construct that represents a load of ORM objects from various :class:`.ReturnsRows` and other classes including: :class:`.Select`, :class:`.TextClause`, :class:`.TextualSelect`, :class:`.CompoundSelect`, :class`.Insert`, :class:`.Update`, and in theory, :class:`.Delete`. r Nz(Union[ExecutableReturnsRows, TextClause]r& r� r3 r+ r� Tz%Iterable[_ColumnsClauseArgument[Any]])�entitiesr& r3 c sf � fdd�t �|�D �� _|� _|j� _|j� _|j� _|j� _|j� _t |�rV|j nd � _ |� _ d S )Nc s g | ]}t jtj|� d d��qS )T)�apply_propagate_attrsZ post_inspect)r$ �expectr& ZColumnsClauseRoler� r rw rx r� � s ��z*FromStatement.__init__.<locals>.<listcomp>) r# Zto_listr+ r& r) Z is_selectr? r= r> r+ r( r3 )r� rF r& r3 rw r rx r� � s � �zFromStatement.__init__c K s: | j | |fi |��}|j }|r&||_|j|jfi |��S )z�provide a fixed _compiler_dispatch method. This is roughly similar to using the sqlalchemy.ext.compiler ``@compiles`` extension. )�_compile_state_factoryr� rU r2 r{ )r� r� r� rU r� rw rw rx �_compiler_dispatch� s z FromStatement._compiler_dispatchc C s t tt�| ��j}|| �S )a@ Return a :term:`plugin-enabled` 'column descriptions' structure referring to the columns which are SELECTed by this statement. See the section :ref:`queryguide_inspection` for an overview of this feature. .. seealso:: :ref:`queryguide_inspection` - ORM background )r �ORMSelectCompileStater; Zget_plugin_classr� )r� �methrw rw rx �column_descriptions� s �z!FromStatement.column_descriptionsc C s | S r| rw r rw rw rx �_ensure_disambiguated_names s z)FromStatement._ensure_disambiguated_namesc + s: t j�dd� | jD ��E d H t� jf i |��E d H d S )Nc s s | ] }|j V qd S r| )� _from_objects�r} r& rw rw rx r� s z-FromStatement.get_children.<locals>.<genexpr>)� itertools�chain� from_iterabler+ r� � get_children)r� r� r� rw rx rT s �zFromStatement.get_childrenc C s | j jS r| )r& �_all_selected_columnsr rw rw rx rU s z#FromStatement._all_selected_columnsc C s t | j�r| jjS d S r| )r) r& �_return_defaultsr rw rw rx rV s z FromStatement._return_defaultsc C s t | j�r| jjS d S r| )r) r& � _returningr rw rw rx rW s zFromStatement._returningc C s t | j�r| jjS d S r| )r* r& �_inliner rw rw rx rX ! s zFromStatement._inline)T) rl rm rn r� Z__visit_name__r r� r� r� rI �_for_update_argr� r= Zdp_clauseelement_listZdp_clauseelementr/ Z _executable_traverse_internalsZ_traverse_internalsr� r� Zis_from_statementr� rJ r rM rN rT rU rV rW rX r� rw rw r� rx r � s> ��� � r Zcompound_selectc @ s e Zd ZdS )�CompoundSelectCompileStateN)rl rm rn rw rw rw rx rZ & s rZ �selectc @ s\ e Zd ZdZeZdZdZdZdZ dZ dZ dZ dZ dZdZeddddd d�d d ��Zd d � Zd d� Zedd� �Zedd� �Zedd� �Zedd� �Zedd� �Zdd� Zdd � Zd d � Zd d � Z d!d"� Z dEd#d$�Z d%d&� Z d'd(� Z d)d*� Z!d+d,� Z"d-d.� Z#d/d0� Z$d1d2� Z%d3d4� Z&d5d6� Z'd7d8� Z(d9d:� Z)d;d<� Z*e+d=d>� �Z,e+d?d@� �Z-dAdB� Z.dCdD� Z/dS )FrK rw NFr� r� r� r r� c s" | � | �� |}| j�|j�|_|jr<|�� � _t�� � j_n|� _|jj � _ |jj � _ g � _ d � _i � _|j� _|s�� jddd�7 _� j r�� jjtu r�� j s�t� _q�t� _n � jj� _|jrև fdd�|jD �� _� �|j� j �� _tj� |j � j dd� |jj � _ d� _ � j |||dd� |�r�|j!�s6|j�r�|jD ]8}|j!D ]*}|j"�rF|�#� d d � � j| D �� �qF�q<� jj!D ]}|j"�r~|�$� � �q~|j%�r�|j%D ]\}} |� � �q�g � _&g � _'t(� � _)i � _*i � _+g � _,g � _-� �.d d � |j/D ��� _0� �1� t2j3� � j4|fi |�� � S ) NFT)r� r� c s" i | ]}|t j� |jg d d��qS )Fr! )r) r* r+ )r} �memoized_entitiesr rw rx � <dictcomp>� s ��z=ORMSelectCompileState._create_orm_context.<locals>.<dictcomp>r! rw )r� r� c S s g | ]}t |t�r|�qS rw r� r� rw rw rx r� � s �z=ORMSelectCompileState._create_orm_context.<locals>.<listcomp>c s s | ] }|j V qd S r| )r� )r} �inforw rw rx r� � s z<ORMSelectCompileState._create_orm_context.<locals>.<genexpr>)5r% r� Z safe_merger� r� Z_cloner� r# � immutabledictr� � for_statementr� r� r� r� r� r� r( �LABEL_STYLE_LEGACY_ORMr8 r� r6 �_memoized_select_entities�_memoized_entitiesr� r� r) r* r+ r� r� �eager_order_byr� r� r� Z'process_compile_state_replaced_entitiesr� r, r� r� r- r� rE r0 rb r. �_normalize_froms� _from_obj� from_clauses�_setup_for_generater; r� r{ ) r� r{ r� r� r� r� r\ r~ r5 r� rw r rx r� @ s� � �� � � ��� ���� ��� � z)ORMSelectCompileState._create_orm_contextc C s� t d� t d| j� �� | jD ]�}t|t�r||d dkr|t dt�|d �� �� t d| j| � �� t d| j| j� �� q t|t�r |d dkr t d t�|d �� �� t d| j| � �� q d S ) Nz5 --------------------------------------------------- zcurrent path: r �loaderz Loader: r z Zpath_with_polymorphicz With Polymorphic: )�printr� r r� r� r Zcoerce�__dict__)r� r� rw rw rx �_dump_option_struct� s z)ORMSelectCompileState._dump_option_structc s� | j }d | _d| _| jjr"| �� |jD ] }|jr(| �|j| j | � q(|jr^| �|j| j � | � � � |j r�|j | _ � r�t � fdd�| j D ��| _ � r�|jdvr�| �|j� �n|j| _|jr�t � fdd�|jD ��| _� r�|jdvr�| �t�|j�� �n |j�pd | _| j�r(| jd j}|�| j�| _|j�rB| �|j� �| _nd| _|j | _ |j �rvt t�dd� |j D ���| _ n8|j d u�r�t t�dd� |j D ���| _!n|j"�s�d | _ |j#| _#| jj$�r�t%| j �d k�r�t&�'d ��| j D ]}|�(| � �q�| j)D ]&}|d }|| g|d d � �R � �q�| jj*�r2| �+� | j,�s\| jj-�rRd �sRJ d ��t&�.d��| j�spt/| j0�| _| jd u �r�d | _| j1�r�| j2�r�| j3�r�| �4� | _n | �5� | _| j6�r�| �7� }|d u�r�| j�8d|i�| _d S )Nrw c 3 s | ]}� |d �V qdS �TNrw �r} �crit�r9 rw rx r� s �z<ORMSelectCompileState._setup_for_generate.<locals>.<genexpr>�NFc 3 s | ]}� r� |d �n|V qdS rm rw rn rp rw rx r� s �r c s s$ | ] }|d urt �|�nd V qd S r| �r Zsurface_selectables�r} �srw rw rx r� 7 s �c s s$ | ] }|d urt �|�nd V qd S r| rr rs rw rw rx r� > s �r| r r< Fz,no columns were included in _only_load_propsz4Query contains no columns with which to SELECT from.Z deepentity)9r� r{ �_join_entitiesr� r� �_set_select_from_aliasrb � _setup_joins�_joinrc r� r; �_where_criteriar� �_order_by_clausesr: r/ �_having_criteria�_group_by_clausesr# Zflatten_iterator�group_byrd rg Z_target_adapter�copy_and_processZ _distinct_on� distinct_onZ _distinct�distinctZ _correlate� correlateZ_correlate_except�correlate_exceptZ_auto_correlaterY r� r� r# r$ r1 rb r� �_adjust_for_extra_criteriar� r� �InvalidRequestError�listr. rB rC �_should_nest_selectable�_compound_eager_statement�_simple_statementr` � _mapper_zeroZ _annotate)r� rV r\ r r6 ZrecZstrategy�ezerorw rp rx rh � s� � � ��� � �� � � � �� ��� � ��� �z)ORMSelectCompileState._setup_for_generatec C sF | � | �}g |_d|_i |_|�|j|�|_tj||j |jdd� |S )a Creates a partial ORMSelectCompileState that includes the full collection of _MapperEntity and other _QueryEntity objects. Supports a few remaining use cases that are pre-compilation but still need to gather some of the column / adaption information. NTr! ) r% r� r� r� r� r( r� r) r* r+ )r� rV r� r� rw rw rx r | s � �z1ORMSelectCompileState._create_entities_collectionc C s |j }t|d �S r| )rw � _determine_last_joined_entity)r� r{ � setup_joinsrw rw rx � determine_last_joined_entity� s z2ORMSelectCompileState.determine_last_joined_entityc c sj |j D ]^}|jrTd|jv rT|jd }|jsB|jsBt|g�E d H qdt|j�E d H qt|g�E d H qd S )NZentity_namespace)r+ � is_selectable� _annotationsZ is_mapperr� r, Z_all_column_expressions)r� r{ r& Zensrw rw rx �all_selected_columns� s �� z*ORMSelectCompileState.all_selected_columnsc C s | � tj�dd� |jD ���S )Nc s s. | ]&}d |j vr|jn|j d �� gV qdS )� parententityN)r� rO �__clause_element__rP rw rw rx r� � s ����zAORMSelectCompileState.get_columns_clause_froms.<locals>.<genexpr>)re rQ rR rS r+ r� rw rw rx �get_columns_clause_froms� s ��z.ORMSelectCompileState.get_columns_clause_fromsc C s> t jtj||d�}t|j|�}|jj|j|j |j |j d� |S )N)rG )r� r, r� r� ) r$ rH r& ZReturnsRowsRoler r+ rk �updater� r, r� r� )r� r{ �from_statement�stmtrw rw rx r� � s � �z$ORMSelectCompileState.from_statementc C sT | j }| jjsJ �t|j�dks$J �| �|jd �}|rP| jddi7 _|| _dS )� used only for legacy Query casesr r r� FN)r� r� r� r� rf � _get_select_from_alias_from_objr4 )r� rV r rw rw rx rv � s z,ORMSelectCompileState._set_select_from_aliasc C s| |}d|j v r|j d }t|d�r<|js4t�d��qx|jS n<t|jtjj �rt| � � }||ju sbJ �t t j |j|d�S dS dS )r� r� r� zPA selectable (FromClause) instance is expected when the base alias is being set.�r� N)r� �hasattrr� r# � ArgumentError�_adapterr� r� r" ZAliasedReturnsRows� _all_equivsr r ZLEGACY_SELECT_FROM_ALIAS)r� �from_objr^ �equivsrw rw rx r� � s$ ��z5ORMSelectCompileState._get_select_from_alias_from_objc C s | j d jS )z8return the Mapper associated with the first QueryEntity.r )r� r� r rw rw rx r� � s z"ORMSelectCompileState._mapper_zeroc C sD | j D ] }d|jv r|jd S q| jD ]}|jr*|j S q*dS )z�Return the 'entity' (mapper or AliasedClass) associated with the first QueryEntity, or alternatively the 'select from' entity if specified.r� N)rg r� r� � entity_zero)r� r� Zqentrw rw rx � _entity_zero� s z"ORMSelectCompileState._entity_zeroc C s$ | j | jgkr t�d| ��| jjS )Nz4%s() can only be used against a single mapped class.)r� r� r# r� r� )r� Zmethnamerw rw rx �_only_full_mapper_zero s ��z,ORMSelectCompileState._only_full_mapper_zeroc C s$ t | j�dkr t�|pd��| �� S )Nr z8This operation requires a Query against a single mapper.)r� r� r# r� r� )r� Z rationalerw rw rx �_only_entity_zero s �z'ORMSelectCompileState._only_entity_zeroc C s^ i }| j �� D ]&}dd� |D �D ]}|�|jj� q qdd� | jD �D ]}|�|jj� qF|S )Nc S s g | ]}t |t�r|�qS rw r� r� rw rw rx r� s �z5ORMSelectCompileState._all_equivs.<locals>.<listcomp>c S s g | ]}t |t�r|�qS rw r� r� rw rw rx r� % s )rc �valuesr� r� r� r� )r� r� r\ r� rw rw rx r� s � � z!ORMSelectCompileState._all_equivsc sL � j r&dd� � j D �}t�� j|�}ng }d }� j� j� fdd�|D � � j� j� j� j� j f� j � j j � j j � j � jd�� j��}|�� }� �� }ttj||d�� _tj|g� j � }� j|_� j d urވ j jd u rވ j |_ |}� j� � D ]}t� |||j �}q�|j � ||� |�r2|j j |g� j�!|��R � |j j |g� j"�R � |S )Nc S s$ g | ] }t |tjj�r |jn|�qS rw )r� r" �elementsZ_label_referencer& )r} �elemrw rw rx r� 7 s � �zCORMSelectCompileState._compound_eager_statement.<locals>.<listcomp>c s g | ]}|� j vr|�qS rw )r� )r} r r rw rx r� K � �� for_update�hints�statement_hintsr� r� r� )#r/ r Z expand_column_list_from_order_byr� �_select_statementrg ry r{ r� rY r� �_hints�_statement_hintsr� r� � _select_args�aliasr� r r ZCOMPOUND_EAGER_STATEMENTrD r r[ r� r( ZofrE r� Z splice_joinsZstop_on� select_from�non_generativer~ rd )r� Zunwrapped_order_byZorder_by_col_expr�innerr� r{ Z from_clauseZ eager_joinrw r rx r� + sr � ���� �� �� �����z/ORMSelectCompileState._compound_eager_statementc C s| | j | j| j t| j�t| j�� � | j| j| j | j f| j | j j | j j| j| jd�| j��}| jrx|j j|g| j�R � |S )Nr� )r� r� r� r� rg rE r� ry r{ r� r/ rY r� r� r� r� r� r� rd r� )r� r{ rw rw rx r� � s& �� �z'ORMSelectCompileState._simple_statementc C s t j|||d�}|r||_|r$||_|r:| jt|�7 _|rT|jj|g|�R � n|rd|j�|� |rz| jt|�7 _| |_ | |_ ||_ ||_ ||_ ||_|r�||_|r�||_||_|r�||_| r�| |_| r�|jj|g| �R � | d u�r|jj|g| �R � |S )N)r+ rf r( )r9 Z_create_raw_selectry r{ rz r� r� r� r| � _limit_clause�_offset_clause� _fetch_clause�_fetch_clause_options�_independent_ctes�_independent_ctes_opts� _prefixes� _suffixesrY r� r� r� r� )r� Z raw_columnsr� Zwhere_criteriaZhaving_criteriar� r/ r� r� r� r� r� � limit_clause� offset_clause� fetch_clause�fetch_clause_optionsr� r �prefixes�suffixesr} �independent_ctes�independent_ctes_optsr{ rw rw rx r� � sR � ��z'ORMSelectCompileState._select_statementc C sx d|j v r0|j d }| j�|d �}|r0|�|�S t|tj�rB|}nt|d�rT|j}nd S | j�|d �}|rt|�|�S d S )Nr� r' ) r� r� r� Z adapt_clauser� r% Z FromClauser� r' )r� r& �searchr� rw rw rx �_adapt_polymorphic_element� s z0ORMSelectCompileState._adapt_polymorphic_elementc s � r� fdd�|D �S |S d S )Nc s g | ]}� |d ��qS )Trw )r} �orp rw rx r� � r� z9ORMSelectCompileState._adapt_col_list.<locals>.<listcomp>rw r7 rw rp rx r: � s z%ORMSelectCompileState._adapt_col_listc sJ g � | j r � �d| j jf� | jr2� �d| jf� � s:d S � fdd�}|S )NTFc s � fdd�}t �| i |�S )Nc sF d| j v pd| j v }� D ](\}}|s(|r|| �}|d ur| S qd S )N� _orm_adaptr� )r� )r� Z is_orm_adaptZ always_adaptr �e��adaptersrw rx �replace s � zRORMSelectCompileState._get_current_adapter.<locals>._adapt_clause.<locals>.replace)r' Zreplacement_traverse)r� r r� r� rw rx � _adapt_clause s zAORMSelectCompileState._get_current_adapter.<locals>._adapt_clause)r4 r� r� r� r� )r� r� rw r� rx r; � s �� z*ORMSelectCompileState._get_current_adapterc C s� |D �]�\}}}}|d }|d }t |�}|d ur:t |�}t|tj�rb|d urXt�d��|}d }nd|jv rv|jd }|d u r�|js�t|d�s�t� d��t|tj��r�t |dd �} |d u �r| r�| }nH|j }z |j }W n6 t �y } z t� d| �| �W Y d } ~ n d } ~ 0 0 |j} |j } t|tj��s,| }| || jf| jv �rBq|d u�r�|| u�r�|j�dd �| u�r�t�d |j�d|�|f ��n |d u�r�d } |} nd } } | �|| ||| ||� qd S ) N�isouter�fullzUNo 'on clause' argument may be passed when joining to a relationship path as a targetr� r� z9Expected mapped entity or selectable/table as join targetZ_of_typez0Join target %s does not refer to a mapped entityzMexplicit from clause %s does not match left side of relationship attribute %s)r! r� r �PropComparatorr# r� r� r� r� r� r� r r6 �AttributeErrorZ _parententityr �QueryableAttributer� �_already_joined_edgesr� �_join_left_to_right) r� �args�entities_collection�right�onclause�from_�flagsr� r� Zof_type�err�leftr rw rw rx rx / s� � � ��� � �� ��� �zORMSelectCompileState._joinc C s |du r,|du sJ �| � ||||�\}}} n| �||�\}} ||u rVt�d||f ��| �||||�\} }}| js~| �| �} nd} |dur�| j| } | jd|� t| ||||| d�g | j|d d� | _nH| dur�t || t �s�J �|| j } n|} | jt| | |||| d�g | _dS )z�given raw "left", "right", "onclause" parameters consumed from a particular key within _join(), add a real ORMJoin object to our _from_obj list (or augment an existing one) Nz>Can't construct a join from %s to %s, they are the same entityrw )r� r� Z_extra_criteriar ) �"_join_determine_implicit_left_side� _join_place_explicit_left_sider# r� � _join_check_and_adapt_right_sider� �_get_extra_criteriarg r r� r� r� ) r� r� r� r� r� r Z outerjoinr� �replace_from_obj_index�use_entity_index�r_infoZextra_criteriaZ left_clauserw rw rx r� � st ��� ���� ��� ��� ��z)ORMSelectCompileState._join_left_to_rightc C sX t |�}d }}| jrrt�| j|j|�}t|�dkrH|d }| j| }n(t|�dkr`t�d��nt�d|f ��n�|�rDi } t|�D ]R\} } | j } | du r�q�t | �} | |u r�q�t | t �r�| | f| | j< q�d| f| | j< q�t | � � �}t�||j|�}t|�dk�r| ||d \}}n*t|�dk�r2t�d��nt�d|f ��n t�d��|||fS )z�When join conditions don't express the left side explicitly, determine if an existing FROM or entity in this query can serve as the left hand side. Nr r a Can't determine which FROM clause to join from, there are multiple FROMS which can join to this entity. Please use the .select_from() method to establish an explicit left side, as well as providing an explicit ON clause if not present already to help resolve the ambiguity.z�Don't know how to join to %r. Please use the .select_from() method to establish an explicit left side, as well as providing an explicit ON clause if not present already to help resolve the ambiguity.zgNo entities to join from; please use select_from() to establish the left entity/selectable of this join)r! rg r Z find_left_clause_to_join_fromr� r� r# r� � enumerate�entity_zero_or_selectabler� r� r� �keys)r� r� r� r� r� r� r� r� �indexesZ potentialZ entity_indexr� r6 Zent_infoZ all_clausesrw rw rx r� � sb � � �� �� ���z8ORMSelectCompileState._join_determine_implicit_left_sidec C s� d }}t |�}| jrHt�| j|j�}t|�dkr<t�d��|rH|d }|du r�|r�t|d�r�t |�D ]$\}}t |t �rf|� |�rf|} q�qf||fS )z�When join conditions express a left side explicitly, determine where in our existing list of FROM clauses we should join towards, or if we need to make a new join, and if so is it from one of our existing entities. Nr zrCan't identify which entity in which to assign the left side of this join. Please use a more specific ON clause.r r� ) r! rg r Z#find_left_clause_that_matches_givenr� r� r# r� r� r� r� r� �corresponds_to) r� r� r� r� r� �l_infor� �idxr� rw rw rx r� Y s. � � ���z4ORMSelectCompileState._join_place_explicit_left_sidec C s� t |�}t |�}d}t|dd�}|rp|js8t|jtj�rp| jpD|jgD ](} t � |j| �rFt � | |j�rFd} qpqF|r�|j|ju r�t � d|j ��t|dd�|jt|dd� }} } |r�|r�|� |j�s�t � d||f ��t|d�r�| j|f7 _d} |j�r�|�r |j}| j�r0| �� } | du�r�| |d�}nj|�r�| �|j��s\t � d| j|jjf ��t| tj��r|t�tj| �} d} t|| �}t j d | d d d � |�o�| �o�|}| �s�|�r�t|dd �}d} t j d| dd � | �r|�s�J �t t j!t |�|j"d�}| �#||� n4|j�sB| �sB|j$�rB| �#|t t j%||j|j"d�� t|tj&��rh| �� } | �rh| |d�}|�r�| j'|||j(ff7 _'t |�||fS )z�transform the "right" side of the join as well as the onclause according to polymorphic mapping translations, aliasing on the query or on the join, special cases where the right and left side have overlapping tables. Fr� NTz*Can't join table/selectable '%s' to itselfr� zIJoin target %s does not correspond to the right side of join condition %sz(Selectable '%s' is not derived from '%s'z�An alias is being generated automatically against joined entity %s for raw clauseelement, which is deprecated and will be removed in a later release. Use the aliased() construct explicitly, see the linked example.z1.4Zxaj1)�code)Zflatz�An alias is being generated automatically against joined entity %s due to overlapping tables. This is a legacy pattern which may be deprecated in a later release. Use the aliased(<entity>, flat=True) construct explicitly, see the linked example.Zxaj2r� )r� r� ))r! r� �with_polymorphicr� r� r% ZJoinrg r� r Zselectables_overlapr# r� � common_parentr� r� ru �is_clause_elementZ _is_lateralr; Zis_derived_from� descriptionrO r$ rH r& ZFromClauseRoler r# Zwarn_deprecated�warnr r Z DEPRECATED_JOIN_ADAPT_RIGHT_SIDEr� r� Z#_has_aliased_polymorphic_fromclauseZ#WITH_POLYMORPHIC_ADAPTER_RIGHT_JOINZ ClauseElementr� r� )r� r� r� r� r r� r� �overlapZ right_mapperr� Zright_selectableZright_is_aliasedZ need_adapterr9 Zaliased_entityr rw rw rx r� � s� � ������ � �� ��� ���� � �� �� � ����� z6ORMSelectCompileState._join_check_and_adapt_right_sidec C sF | j j| j j| j| j| j j| j j| jp(d | j j| j j | j j | j j d� S )N) r� r� r� r r� r� r} r� r� r� r� ) r� r� r� r� r r� r� r} r� r� r� r� r rw rw rx r� X s �z"ORMSelectCompileState._select_argsc C sF | j }|�d�d upD|�d�d upD|�dd�pD|�dd�pD|�dd�S )Nr� r� r� Fr rw r} )r� r� )r� �kwargsrw rw rx r� l s � � � �z-ORMSelectCompileState._should_nest_selectablec s< d� j f�jv r4t� �fdd��jd� j f D ��S dS d S )N�additional_entity_criteriac 3 s2 | ]*}|j s|j� u r|���r|�� �V qd S r| )Zinclude_aliasesr6 Z_should_includeZ_resolve_where_criteria)r} Zae�r� r� rw rx r� | s �z<ORMSelectCompileState._get_extra_criteria.<locals>.<genexpr>rw )r� r� r� )r� r� rw r� rx r� w s ���� z)ORMSelectCompileState._get_extra_criteriac C s | j D ]V}|j�dd�}|r|jjdus8d|jf| jv r|| jvr||jrP|jndf| j|< qt | j� � �}|D ]�\}}|| j v r�qp|jj}| j j r�g }n | �|�}|dur�||f7 }| �� }|D ]@}|r�|�|�}|r�t�|ddi�}||d�}| j|f7 _q�qpdS )a� Apply extra criteria filtering. For all distinct single-table-inheritance mappers represented in the columns clause of this query, as well as the "select from entity", add criterion to the WHERE clause of the given QueryContext such that only the appropriate subtypes are selected from the total results. Additionally, add WHERE criteria originating from LoaderCriteriaOptions associated with the global context. r� Nr� r� TF)rg r� r� r� �_single_table_criterionr� r0 r� r� r- r� ru r� r� r� r; �traverser Z_deep_annotatery ) r� Z fromclauser� r� r Z single_critr� r9 ro rw rw rx r� � sB � ���� � z0ORMSelectCompileState._adjust_for_extra_criteria)N)0rl rm rn r� r� rc r4 r rA rB rC rD r� r� ry r{ r� r� rl rh r r� r� r� r� rv r� r� r� r� r� r� r� r� r� r� r: r; rx r� r� r� r� r r� r� r� r� rw rw rw rx rK - sj # [M0]cjB > rK Fz#Union[Query, Select, FromStatement]z Optional[ORMSelectCompileState]r� zList[ORMColumnDescription])�query_or_select_stmtrU r� r� c C s8 |d u rt j| |d�}|}dd� dd� |jD �D �}|S )N)r� c S sJ g | ]B\}}|j |jt|d d�|j|jdur>|js>t|dd�ndd��qS )r� FNr6 )r� �type�aliased�exprr6 )� _label_namer� r� r� r� r� )r} r� Zinsp_entrw rw rx r� � s � ���z(_column_descriptions.<locals>.<listcomp>c S s g | ]}||j f�qS rw �r� )r} Z_entrw rw rx r� � s )rK r r� )r� rU r� r� �drw rw rx r� � s � ��r� z Union[Query[Any], Select[Any]]z"Optional[_InternalEntityType[Any]])�query_or_augmented_selectr� c C sJ | }|j r |j}|d ur |S |jrBd|jd jv rB|jd jd S t|�S )Nr� r )rw �_last_joined_entityrf r� �_entity_from_pre_ent_zero)r� r� r� rw rw rx � _legacy_filter_by_entity_zero� s r c C sX | }|j sd S |j d }d|jv r,|jd S t|t�r<|jS d|jv rP|jd S |S d S )Nr r� �bundle)r+ r� r� r r6 )r� r� r� rw rw rx r� � s r� z Tuple[_SetupJoinsElement, ...]z=Optional[Union[_InternalEntityType[Any], _JoinTargetElement]])r� r� r� c C s2 | sd S | d \}}}}t |tj�r*|jS |S d S )N���)r� r r� r6 )r� r� �targetr� r� r� rw rw rx r� s �r� c @ s� e Zd ZU dZdZded< dZdZdZded< ded < d ed < d ed < ddd�dd�Z dddd�dd�Z dd� Z e dd� �Z dS ) r) z:represent an entity column returned within a Query result.rw r� �supports_single_entityFz Optional[str]r� z!Union[Type[Any], TypeEngine[Any]]r� z.Union[_InternalEntityType, ColumnElement[Any]]r� z Optional[_InternalEntityType]r� rk �None)rU r� c C s t � �d S r| r� �r� rU rw rw rx r1 # s z _QueryEntity.setup_compile_state� Optional[_DMLReturningColFilter]�rU r r� c C s t � �d S r| r� �r� rU r rw rw rx r@ & s z._QueryEntity.setup_dml_returning_compile_statec C s t � �d S r| r� )r� r� r� rw rw rx � row_processor- s z_QueryEntity.row_processorc C s� t |�D ]�\}}|jr8|jr2| �||j||� qn|j}|jr�|jrtd|jv r^t||||� q�t � ||j |||� q�|j� dd�r�t ||||� q�|jr�t � ||j |||� q�t � ||g|||� q|jrt |||� q|S )Nr� r F)r� Z_is_lambda_elementZ _is_sequencer* Z _resolvedr� r� r� r� � _ColumnEntity� _for_columnsZ_select_iterabler� � _BundleEntityZ_is_clause_listZ is_bundle)r� rU rF r� r" r� r6 rw rw rx r* 0 sh � �����z _QueryEntity.to_compile_stateN)rl rm rn r� r� r� �_non_hashable_value�_null_column_type�use_id_for_hashr1 r@ r r� r* rw rw rw rx r) s r) c @ s� e Zd ZU dZdZded< ded< ded< ded < d ed < d ed < dd� ZdZdZdZ e dd� �Z e dd� �Z dd� Z dd� Zdd� Zdd d d �d d �Zd!d"� Zd#S )$r� z mapper/class/AliasedClass entity) r� r� r� r� �path�_extra_entitiesr� r r� �_polymorphic_discriminatorr> r� z Mapper[Any]r� r� r� r� r r �strr� c C s� |� | � |r*|jd u r | |_d|_d|_|jd }|j | }| _|j}|| _|j | _ }| jf| _ |j rv|j | _ n |jj| _ |j | _ |j| _|j| _|j| _|j| _|jr�|�|| j� d S )NTr� )r� r� r rA r� � _post_inspectr� r6 r� r� r r� r� r� �class_rl r� r r� Zwith_polymorphic_mappersr Zpolymorphic_onr � _should_select_with_poly_adapterr )r� rU r6 r� r" r� r� rw rw rx r� � s2 �z_MapperEntity.__init__Tc C s | j jS r| )r� r r rw rw rx r� � s z_MapperEntity.typec C s | j S r| r� r rw rw rx r� � s z'_MapperEntity.entity_zero_or_selectablec C s t | j|�S r| )r r� �r� r6 rw rw rx r� � s z _MapperEntity.corresponds_toc C sR d }| j s"|jr*|j�| jd �}n| jj}|rH|jrB|�|j�}qN|}n|j}|S r| )r� r� r� r� r� r� r4 �wrap)r� rU r �retrw rw rx �_get_entity_clauses� s �z!_MapperEntity._get_entity_clausesc C s� |j }| �|�}|jr(|r(|�|j�}n |s2|j}|j| u rL|jj}|j}nd }}tj | | j ||| j |||| j d� }|| j | jfS )N)�only_load_propsra �polymorphic_discriminator)rU r rD r r� r� r� ra r Z_instance_processorr� r r r� r )r� r� r� rU r r ra Z _instancerw rw rx r � s, � z_MapperEntity.row_processorrk r r r c C s. t j|| j| | j||j| j|jj| jd� d S )N�r� r r ) r �_setup_entity_queryr� r r� r r� r� r r rw rw rx r@ � s �z/_MapperEntity.setup_dml_returning_compile_statec C s� | � |�}| jj}|d us*d| jf|jv rJ| j}||jr>|jnd f|j|< tj || j| | j ||j | j |j j| jd� |j�| j� d S )Nr� r )r r� r� r� r� r� r� r0 r r r r� r r� r� r r. r� r� )r� rU r �single_table_critr� rw rw rx r1 s0 ���� � z!_MapperEntity.setup_compile_stateN)rl rm rn r� r� r� r� r r r r r� r� r� r r r@ r1 rw rw rw rx r� r s* % r� c @ s� e Zd ZU dZdZded< ded< ded< d ed < d ed < ded < d$dd�Zedd� �Zedd� �Z dd� Z edd� �Z dd� Z d d d d �d d!�Z d"d#� ZdS )%r rw )r r� r� r� r� r r� r� r r z Type[Any]r� r r� r� r r� TNc C s� d|_ |jd }|r"|j�| � n |�| � t|tjtjf�rH|� � }n|}| | _ | _ t |�| _ |j | _g | _|r�|jD ]X}d|jv r�t||||| d� qzt|t�r�t||||| d� qztj||g|d || d� qz| j j| _d S )NTr �� parent_bundle)rA r� r� r� r� r r� r r� r� r r� r� r� r� �exprsr r �_ORMColumnEntityr Z single_entityr )r� rU r� r� r" Zsetup_entitiesr" r rw rw rx r� 1 sR � � �� z_BundleEntity.__init__c C s | j }|d ur|jS d S d S r| )r� r� )r� r� rw rw rx r� l s z_BundleEntity.mapperc C s& | j D ]}|j}|d ur| S qd S r| )r� r� �r� r� r� rw rw rx r� t s z_BundleEntity.entity_zeroc C s dS rq rw r rw rw rx r� } s z _BundleEntity.corresponds_toc C s& | j D ]}|j}|d ur| S qd S r| )r� r� r% rw rw rx r� � s z'_BundleEntity.entity_zero_or_selectablec C s | j D ]}|�|� qd S r| )r� r1 )r� rU r� rw rw rx r1 � s z!_BundleEntity.setup_compile_staterk r r r c C s | � |�S r| �r1 r rw rw rx r@ � s z/_BundleEntity.setup_dml_returning_compile_statec s@ t � �fdd�| jD �� \}}}| j�� j||�}|| j| jfS )Nc s g | ]}|� � ���qS rw )r r� �r� r� rw rx r� � r� z/_BundleEntity.row_processor.<locals>.<listcomp>)r� r� r Zcreate_row_processorrV r� r )r� r� r� Zprocs�labels�extra�procrw r' rx r � s � z_BundleEntity.row_processor)TN)rl rm rn r r� r� r� r r� r� r� r� r1 r@ r rw rw rw rx r s* � ; r c @ sJ e Zd ZdZed dd��Zedd� �Zedd� �Zed d � �Z d d � Z dS )r )� _fetch_column�_row_processor�raw_column_index�translate_raw_columnNc C s� |D ]z}|j }d|v r |d } n t�|d�} | rjd|j v rRt|||| |||d� q~t|||| |||d� qt||||||d� qd S )Nr� rf r! )r� r Z extract_first_column_annotation�_IdentityTokenEntityr$ �_RawColumnEntity) r� rU r r� r- r" r" �columnr �_entityrw rw rx r � sF � � � �z_ColumnEntity._for_columnsc C s | j jS r| )r1 r� r rw rw rx r� � s z_ColumnEntity.typec C s | j jj S r| )r1 r� Zhashabler rw rw rx r � s z!_ColumnEntity._non_hashable_valuec C s | j jjS r| )r1 r� Z_isnullr rw rw rx r � s z _ColumnEntity._null_column_typec C s� |j }| jd ur@| j\}}}| jr6||jj| j f7 }|||fS | jd urR| j}n&| j}|jrj|jj | }|j rx|� � }|j r�|j j | }|� |�}|| j| jf}|| _| jr�| j|jj| j f }|| j|fS |S d S r| )rU r, r. rV r+ r- r+ r1 r4 r r� � _deannotaterD �_getterr� r ) r� r� r� rU �getterZ label_nameZextra_entitiesr1 r rw rw rx r � s4 � � z_ColumnEntity.row_processor)N) rl rm rn r� r� r r r� r r r rw rw rw rx r � s � 1 r c @ sH e Zd ZdZdZdZdZddd�Zdd� Zdd d d �d d �Z dd� Z dS )r0 NF)r� r1 r� r� r c C s� || _ || _|d u| _|jr.| jddi7 _|r8|jr@d | _n|rN|j| _n |�|�| _|rl|j � | � n |� | � || _ | j j r�| j j d nd | _ | j | j f| _d | _| _d S )Nr� Tr )r� r- r. r� r� Z_is_text_clauser� � _proxy_keyr� r� r� r1 rO r� r r+ r, )r� rU r1 r� r- r" r" rw rw rx r� & s$ �z_RawColumnEntity.__init__c C s dS rq rw r rw rw rx r� J s z _RawColumnEntity.corresponds_tork r r r c C s | � |�S r| r& r rw rw rx r@ M s z2_RawColumnEntity.setup_dml_returning_compile_statec C s\ |� � }|r&|| jd�}|d u r,d S n| j}|jr:|�� }|j�|� |j�|� || _d S rq ) r; r1 r� r3 r� r� r� r� r+ )r� rU r9 r1 rw rw rx r1 T s z$_RawColumnEntity.setup_compile_state)N) rl rm rn r� r� r r� r� r� r@ r1 rw rw rw rx r0 s � $r0 c @ sD e Zd ZdZdZdZddd�Zdd� Zd d d d �d d�Zdd� Z dS )r$ z Column/expression based entity.F)r� r� r1 r� r� r� r Nc C s |j }|} |�dd �} |�d| �} | r<t| j| �| _d| _n|| _|d u| _|| _|r~|rl| rb| n|j| _q�|j || d�| _nd | _| j | | _ | _ } | j | _ } |r�|j�| � n |�| � d|_|| _d | _| _| j| jf| _| jr�|�| | j� d S )N� proxy_key� proxy_ownerF)r� T)r� r� r� r6 r� r. r- r6 r� r� r r� r� r� r� r� rA r1 r+ r, r r r r� )r� rU r1 r� r� r- r" r" r r2 Zorm_keyr8 r� r� rw rw rx r� v s> � �z_ORMColumnEntity.__init__c C s. t |�r|| ju S t | j� o(|�| j�S d S r| )r r� r� r rw rw rx r� � s � �z _ORMColumnEntity.corresponds_tork r r r c C s> | j | _}|r||d�}|d ur:|j�|� |j�|� d S rq )r1 r+ r� r� r� r� )r� rU r r1 rw rw rx r@ � s z2_ORMColumnEntity.setup_dml_returning_compile_statec C s� |� � }|r8|| jd�}|d u r>|js*J �| j| _d S n| j}| j}| jj}|d usdd| jf|jv r~||jrr|j nd f|j |< |j r�|j s�|� � }t| jj��|jj�r�|j�|j� |j�|� |j�|� || _d S )NFr� )r; r1 r� r+ r� r� r� r� r� r� r0 r� Z_expression_labelr3 r- rO � intersectionr� r. r� r� r� r� )r� rU r9 r1 r� r rw rw rx r1 � s8 ���� � z$_ORMColumnEntity.setup_compile_state)N) rl rm rn r� r r� r� r� r@ r1 rw rw rw rx r$ g s � C r$ c @ s e Zd ZdZdd� Zdd� ZdS )r/ Fc C s d S r| rw r rw rw rx r1 � s z(_IdentityTokenEntity.setup_compile_statec s � fdd�}|| j | jfS )Nc s � j jS r| )rY rs )�row�r� rw rx r5 s z2_IdentityTokenEntity.row_processor.<locals>.getter)r� r )r� r� r� r5 rw r; rx r s z"_IdentityTokenEntity.row_processorN)rl rm rn r. r1 r rw rw rw rx r/ � s r/ )NF)N)�� __future__r rQ �typingr r r r r r r r r r r r � r r r �baser r r Z path_registryr r# r r r r r r r r r# r r! r" r$ r% r& r r' Z sql._typingr( r) r* r+ Zsql.baser, r- r. r/ r0 r1 Zsql.dmlr2 Z sql.elementsr3 r4 Zsql.selectabler5 r6 r7 r8 r9 r: r; r< Z sql.visitorsr= Z_typingr> r? r@ r� rA rV rB r\ rC rD ZenginerE Zengine.interfacesrF rG Z sql.compilerrH rI rJ rK rL rM rN rO Z sql.type_apirP rQ �rootr� r_ r� ra rS r� r� r� rk r r r Z plugin_forr r rZ rK r� r r� r� r) r� r r r0 r$ r/ rw rw rw rx �<module> s t�l- +' ;x � � �_ - yN sqlalchemy/orm/__pycache__/evaluator.cpython-39.pyc 0000644 00000030204 15125143220 0016340 0 ustar 00 a ��JhA0 � @ s d Z ddlmZ ddlmZ ddlmZ ddlm Z ddlm Z ddlmZ dd lm Z dd l m Z dd l mZ dd lmZ dd lmZ ddlmZ ddlmZ G dd� dej�ZG dd� dej�ZG dd� dej�Ze� Ze� ZG dd� d�Z ddd�dd �Z d S ) z�Evaluation functions used **INTERNALLY** by ORM DML use cases. This module is **private, for internal use by SQLAlchemy**. .. versionchanged:: 2.0.4 renamed ``EvaluatorCompiler`` to ``_EvaluatorCompiler``. � )� annotations)�Type� )�exc)�LoaderCallableStatus)� PassiveFlag� )�inspect)�and_)� operators)� Concatenable)�Integer)�Numeric)�warn_deprecatedc @ s e Zd ZdS )�UnevaluatableErrorN)�__name__� __module__� __qualname__� r r �M/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/evaluator.pyr % s r c @ s e Zd Zdd� Zdd� ZdS )� _NoObjectc O s d S �Nr ��self�arg�kwr r r �operate* s z_NoObject.operatec O s d S r r r r r r �reverse_operate- s z_NoObject.reverse_operateN�r r r r r r r r r r ) s r c @ s e Zd Zdd� Zdd� ZdS )�_ExpiredObjectc O s | S r r r r r r r 2 s z_ExpiredObject.operatec O s | S r r r r r r r 5 s z _ExpiredObject.reverse_operateNr r r r r r 1 s r c @ s e Zd Zd6dd�Zdd� Zdd� Zdd � Zd d � Zd d � Zdd� Z dd� Z dd� Z dd� Z dd� Z dd� Zdd� Zd d � Zd d � Zd d!� Zd"d#� Zd$d%� Zd&d'� ZeZeZeZeZeZeZeZ eZ eZ eZ eZ d(d)� Z!d*d+� Z"d,d-� Z#d.d/� Z$d0d1� Z%d2d3� Z&d4d5� Z'dS )7�_EvaluatorCompilerNc C s || _ d S r )� target_cls)r r! r r r �__init__> s z_EvaluatorCompiler.__init__c G sH |rt |g|�R � }t| d|j� �d �}|s@tdt|�j� ���||�S )N�visit_�Cannot evaluate )r �getattrZ__visit_name__r �typer )r �clause�clauses�methr r r �processA s �z_EvaluatorCompiler.processc C s | � |j�S r )r* �element�r r' r r r �visit_groupingL s z!_EvaluatorCompiler.visit_groupingc C s dd� S )Nc S s d S r r ��objr r r �<lambda>P � z/_EvaluatorCompiler.visit_null.<locals>.<lambda>r r, r r r � visit_nullO s z _EvaluatorCompiler.visit_nullc C s dd� S )Nc S s dS )NFr r. r r r r0 S r1 z0_EvaluatorCompiler.visit_false.<locals>.<lambda>r r, r r r � visit_falseR s z _EvaluatorCompiler.visit_falsec C s dd� S )Nc S s dS )NTr r. r r r r0 V r1 z/_EvaluatorCompiler.visit_true.<locals>.<lambda>r r, r r r � visit_trueU s z _EvaluatorCompiler.visit_truec s� z|j d }W n4 tyB } z td|� ��|�W Y d }~n d }~0 0 | jrht| j|j�shtd|j� ���|�� z|j| j}W n6 t j y� } z td|� ��|�W Y d }~n d }~0 0 |j | j � � fdd�}|S )N� parentmapperzCannot evaluate column: z0Can't evaluate criteria against alternate class z Cannot evaluate expression: c s> | d u r t S t| �}|j}� j||tjd�}|tju r:tS |S )N)Zpassive) � _NO_OBJECTr �dict�getr ZPASSIVE_NO_FETCHr ZPASSIVE_NO_RESULT�_EXPIRED_OBJECT)r/ �stateZdict_�value��implr r �get_corresponding_attr s � z?_EvaluatorCompiler.visit_column.<locals>.get_corresponding_attr) Z _annotations�KeyErrorr r! � issubclass�class_Z_check_configureZ_columntoproperty�key�orm_excZUnmappedColumnErrorZ class_managerr= )r r' r5 ZkerB �errr> r r< r � visit_columnX s8 ����� �� z _EvaluatorCompiler.visit_columnc C s | � |�S r ��visit_clauselistr, r r r � visit_tuple� s z _EvaluatorCompiler.visit_tuplec C s | � |�S r rF r, r r r �visit_expression_clauselist� s z._EvaluatorCompiler.visit_expression_clauselistc s\ � fdd�|j D �}d|jj�d�� d�}t� |d �}|rH||j||�S td|j� ���d S )Nc s g | ]}� � |��qS r )r* )�.0r' �r r r � <listcomp>� r1 z7_EvaluatorCompiler.visit_clauselist.<locals>.<listcomp>r# �_Z_clauselist_opz)Cannot evaluate clauselist with operator )r( �operatorr �rstripr% r )r r' � evaluators�dispatchr) r rK r rG � s � �z#_EvaluatorCompiler.visit_clauselistc C sn | � |j�}| � |j�}d|jj�d�� d�}t| |d �}|rN||j|||�S tdt|�j� d|j� ���d S )Nr# rM Z _binary_opr$ � with operator ) r* �left�rightrN r rO r% r r& )r r' � eval_left� eval_rightrQ r) r r r � visit_binary� s ��z _EvaluatorCompiler.visit_binaryc s � fdd�}|S )Nc sH d}� D ]2}|| �}|t u r$t S |r. dS |p8|d u }q|rDd S dS �NFT�r9 )r/ Zhas_null� sub_evaluater; �rP r r �evaluate� s z;_EvaluatorCompiler.visit_or_clauselist_op.<locals>.evaluater �r rN rP r' r\ r r[ r �visit_or_clauselist_op� s z)_EvaluatorCompiler.visit_or_clauselist_opc s � fdd�}|S )Nc sF � D ]<}|| �}|t u r t S |s|d u s4|tu r: d S dS qdS rX )r9 r6 )r/ rZ r; r[ r r r\ � s z<_EvaluatorCompiler.visit_and_clauselist_op.<locals>.evaluater r] r r[ r �visit_and_clauselist_op� s z*_EvaluatorCompiler.visit_and_clauselist_opc s � fdd�}|S )Nc sN g }� D ]<}|| �}|t u r$t S |d u s4|tu r: d S |�|� qt|�S r )r9 r6 �append�tuple)r/ �valuesrZ r; r[ r r r\ � s zA_EvaluatorCompiler.visit_comma_op_clauselist_op.<locals>.evaluater r] r r[ r � visit_comma_op_clauselist_op� s z/_EvaluatorCompiler.visit_comma_op_clauselist_opc C s, |j r| �||||�S td|j�d���d S )NzCustom operator zR can't be evaluated in Python unless it specifies a callable using `.python_impl`.)Z python_impl�_straight_evaluater Zopstring�r rN rU rV r' r r r �visit_custom_op_binary_op� s � �z,_EvaluatorCompiler.visit_custom_op_binary_opc s � �fdd�}|S )Nc s, � | �}�| �}|t u s |t u r$t S ||kS r rY �r/ Zleft_valZ right_val�rU rV r r r\ � s z7_EvaluatorCompiler.visit_is_binary_op.<locals>.evaluater �r rN rU rV r' r\ r rh r �visit_is_binary_op� s z%_EvaluatorCompiler.visit_is_binary_opc s � �fdd�}|S )Nc s, � | �}�| �}|t u s |t u r$t S ||kS r rY rg rh r r r\ � s z;_EvaluatorCompiler.visit_is_not_binary_op.<locals>.evaluater ri r rh r �visit_is_not_binary_op� s z)_EvaluatorCompiler.visit_is_not_binary_opc s � ��fdd�}|S )Nc sJ � | �}�| �}|t u s |t u r$t S |d u s4|d u r8d S �� | ��| ��S r rY rg �rU rV rN r r r\ s z7_EvaluatorCompiler._straight_evaluate.<locals>.evaluater ri r rl r rd � s z%_EvaluatorCompiler._straight_evaluatec C sX |j jjttfvs$|jjjttfvrHtd|j� d|j j� d|jj� ���| �||||�S )Nz Cannot evaluate math operator "�" for datatypes �, ) rS r& �_type_affinityr r rT r r rd re r r r � _straight_evaluate_numeric_only s �� ���z2_EvaluatorCompiler._straight_evaluate_numeric_onlyc C s | � dd� |||�S )Nc S s | t ur| |v S d S r �r6 ��a�br r r r0 ( r1 z:_EvaluatorCompiler.visit_in_op_binary_op.<locals>.<lambda>�rd re r r r �visit_in_op_binary_op& s �z(_EvaluatorCompiler.visit_in_op_binary_opc C s | � dd� |||�S )Nc S s | t ur| |vS d S r rq rr r r r r0 2 r1 z>_EvaluatorCompiler.visit_not_in_op_binary_op.<locals>.<lambda>ru re r r r �visit_not_in_op_binary_op. s �z,_EvaluatorCompiler.visit_not_in_op_binary_opc C sX t |jjjt�r t |jjjt�sDtd|j� d|jj� d|jj� ���| �dd� |||�S )Nz&Cannot evaluate concatenate operator "rm rn c S s | | S r r rr r r r r0 F r1 z>_EvaluatorCompiler.visit_concat_op_binary_op.<locals>.<lambda>) r@ rS r& ro r rT r r rd re r r r �visit_concat_op_binary_op8 s" ������ �z,_EvaluatorCompiler.visit_concat_op_binary_opc C s | � dd� |||�S )Nc S s | � |�S r )� startswithrr r r r r0 M r1 zB_EvaluatorCompiler.visit_startswith_op_binary_op.<locals>.<lambda>ru re r r r � visit_startswith_op_binary_opI s �z0_EvaluatorCompiler.visit_startswith_op_binary_opc C s | � dd� |||�S )Nc S s | � |�S r )�endswithrr r r r r0 T r1 z@_EvaluatorCompiler.visit_endswith_op_binary_op.<locals>.<lambda>ru re r r r �visit_endswith_op_binary_opP s �z._EvaluatorCompiler.visit_endswith_op_binary_opc sH | � |j�� |jtju r(� fdd�}|S tdt|�j� d|j� ���d S )Nc s& � | �}|t u rt S |d u r d S | S r rY )r/ r; �Z eval_innerr r r\ [ s z0_EvaluatorCompiler.visit_unary.<locals>.evaluater$ rR )r* r+ rN r �invr r& r )r r' r\ r r} r � visit_unaryW s ��z _EvaluatorCompiler.visit_unaryc s" |j r|� � � n|j� � fdd�S )Nc s � S r r r. ��valr r r0 n r1 z4_EvaluatorCompiler.visit_bindparam.<locals>.<lambda>)�callabler; r, r r� r �visit_bindparami s z"_EvaluatorCompiler.visit_bindparam)N)(r r r r" r* r- r2 r3 r4 rE rH rI rG rW r^ r_ rc rf rj rk rd rp Zvisit_add_binary_opZvisit_mul_binary_opZvisit_sub_binary_opZvisit_mod_binary_opZvisit_truediv_binary_opZvisit_lt_binary_opZvisit_le_binary_opZvisit_ne_binary_opZvisit_gt_binary_opZvisit_ge_binary_opZvisit_eq_binary_oprv rw rx rz r| r r� r r r r r = sJ 6 r �strzType[_EvaluatorCompiler])�name�returnc C s. | dkrt dd� tS tdt�d| ����d S )NZEvaluatorCompilerz�Direct use of 'EvaluatorCompiler' is not supported, and this name will be removed in a future release. '_EvaluatorCompiler' is for internal use onlyz2.0zmodule z has no attribute )r r �AttributeErrorr )r� r r r � __getattr__q s �r� N) �__doc__� __future__r �typingr � r rC �baser r r Zsqlr r Z sql.sqltypesr r r �utilr ZInvalidRequestErrorr ZColumnOperatorsr r r6 r9 r r� r r r r �<module> s, 6 sqlalchemy/orm/__pycache__/decl_api.cpython-39.pyc 0000644 00000155503 15125143220 0016110 0 ustar 00 a ��Jh�� � @ s d Z ddlmZ ddlZddlZddlZddlmZ ddlmZ ddlmZ ddlm Z ddlm Z dd lm Z dd lm Z dd lm Z dd lmZ dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlZddlmZ ddlmZ ddlmZ ddlm Z ddlm Z ddl m Z dd l m Z dd l m!Z! dd l m"Z" dd l m#Z# dd lm$Z$ dd!l%m&Z& dd"l%m'Z' dd#l%m(Z( dd$l%m)Z) dd%l*m+Z+ dd&l*m,Z, dd'l*m-Z- dd(l*m.Z. dd)l*m/Z/ dd*l*m0Z0 dd+l*m1Z1 dd,l2m3Z3 dd-l2m4Z4 dd-l2m4Z5 dd.l6m7Z7 dd/l8m9Z9 dd0l:m;Z; dd1l<m=Z= d2d3lm>Z> d2d4lm?Z? d2d5lm@Z@ d2d6lAmBZB d2d7lCmDZD d2d8lEmFZF d2d9lGmHZH d2d:lImJZJ d2d;l@mKZK d2d<l@mLZL d2d=l@mZM d2d>l@mNZN d2d?lOmPZP d2d@lOmQZQ d2dAlOmRZR d2dBlOmSZS d2dClOmTZT d2dDlOmUZU d2dElOmVZV d2dFlOmWZW d2dGlOmXZX d2dHlOmYZY e�r�ddIlZm[Z[ ddJlZm\Z\ ddKl*m]Z] ddLlm^Z^ ddMl m_Z_ dd1l<m=Z= d2dNl`maZa d2dOlbmcZc edPedQ�ZdedRedQ�ZeeedSf Zfe edSf ZgedTee(ed e)ed eFed f f ZhdUdVdW�dXdY�ZiG dZd[� d[ej�ZkG d\d]� d]eke?jle7e �ZmeMjne9e;e3e4e!e"e e#e f d^�G d_d`� d`em��ZoG dadb� dbem�Zpd�dddVdedf�dgdh�ZqG didj� dj�ZrG dkdl� dlere ed �ZsG dmdn� dne jted er�ZuG dodp� dpeued �ZvdqdqdW�drds�ZwdtdudW�dvdw�ZxG dxdy� dyeodz�ZyG d{d|� d|e?jle=e emdz�Zzdtdtdud}�d~d�Z{G d�d�� d�e?jle=e �Z|dUddd�dud��d�d��Z}dde~d�dde.epd��d�d�dtddd�d�d�dtd�d�� d�d��ZG d�d�� d��Z�e�Z�e�s�e�Z\d�d�d��d�d��Z�e?��epezem�dtd�dW�d�d���Z�dS )�z1Public API functions and helpers for declarative.� )� annotationsN)�Any)�Callable)�ClassVar)�Dict)� FrozenSet)�Generic)�Iterable)�Iterator)�Mapping)�Optional)�overload)�Set)�Tuple)�Type)� TYPE_CHECKING)�TypeVar)�Union� )� attributes)� clsregistry)�instrumentation)� interfaces)� mapperlib)� composite)�deferred)� mapped_column)� relationship)�synonym)�InstrumentedAttribute)�_inspect_mapped_class)�_is_mapped_class)�Mapped)� ORMDescriptor��_add_attribute)�_as_declarative)�_ClassScanMapperConfig)�_declarative_constructor)�_DeferredMapperConfig)�_del_attribute��_mapper)� Composite)�Synonym)�Mapper)� MappedColumn)�RelationshipProperty)� InstanceState� )�exc)� inspection)�util)�sqltypes)�_NoArg)�SQLCoreOperations)�MetaData)� FromClause)� hybridmethod)�hybridproperty)�typing)�warn_deprecated)�CallableReference��de_optionalize_union_types)�flatten_newtype)� is_generic)� is_literal)� is_newtype)� is_pep695)�Literal)� LITERAL_TYPES)�Self)�_O)� _RegistryType)�_DataclassArguments)� ClassManager)�MapperProperty)�_TypeEngineArgument)�_MatchedOnType�_T)�bound�_TTz_TypeEngineArgument[Any].�Type[_O]�bool��cls�returnc C s. | j dd� D ]}t|dd�dur dS qdS )aK Given a class, return True if any of the classes it inherits from has a mapped table, otherwise return False. This is used in declarative mixins to build attributes that behave differently for the base class vs. a subclass in an inheritance hierarchy. .. seealso:: :ref:`decl_mixin_inheritance` r N� __table__TF)�__mro__�getattr)rX �class_� r^ �L/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/decl_api.py�has_inherited_tablen s r` c @ s. e Zd Zdddd�dd�Zddd�dd �Zd S ) �_DynamicAttributesType�strr �None)�key�valuerY c C s* d| j v rt| ||� nt�| ||� d S �N� __mapper__)�__dict__r% �type� __setattr__)rX rd re r^ r^ r_ rj � s z"_DynamicAttributesType.__setattr__)rd rY c C s& d| j v rt| |� n t�| |� d S rf )rh r* ri � __delattr__�rX rd r^ r^ r_ rk � s z"_DynamicAttributesType.__delattr__N)�__name__� __module__� __qualname__rj rk r^ r^ r^ r_ ra � s ra c @ s e Zd ZdZdS )� DeclarativeAttributeInterceptz�Metaclass that may be used in conjunction with the :class:`_orm.DeclarativeBase` class to support addition of class attributes dynamically. N�rm rn ro �__doc__r^ r^ r^ r_ rp � s rp �Zfield_specifiersc @ s e Zd ZdZdS )�DCTransformDeclarativez-metaclass that includes @dataclass_transformsNrq r^ r^ r^ r_ rt � s rt c @ s4 e Zd ZU ded< ded< dddddd�dd �Zd S ) �DeclarativeMetar: �metadata� RegistryType�registryr rc )� classname�bases�dict_�kwrY c K sp | j }t| dd �}|d u rB|�dd �}t|t�s<t�d��n|| _| j �dd�s\t|| |� t � | |||� d S )N� _sa_registryrx ziDeclarative base class has no 'registry' attribute, or registry is not a sqlalchemy.orm.registry() object� __abstract__F) rh r\ �get� isinstancerx r4 �InvalidRequestErrorr} r& ri �__init__)rX ry rz r{ r| �regr^ r^ r_ r� � s � zDeclarativeMeta.__init__N)rm rn ro �__annotations__r� r^ r^ r^ r_ ru � s ru Frb z,Callable[[Callable[..., Any]], Synonym[Any]])�name� map_columnrY c s ddd�� �fdd� }|S )a Decorator that produces an :func:`_orm.synonym` attribute in conjunction with a Python descriptor. The function being decorated is passed to :func:`_orm.synonym` as the :paramref:`.orm.synonym.descriptor` parameter:: class MyClass(Base): __tablename__ = "my_table" id = Column(Integer, primary_key=True) _job_status = Column("job_status", String(50)) @synonym_for("job_status") @property def job_status(self): return "Status: %s" % self._job_status The :ref:`hybrid properties <mapper_hybrids>` feature of SQLAlchemy is typically preferred instead of synonyms, which is a more legacy feature. .. seealso:: :ref:`synonyms` - Overview of synonyms :func:`_orm.synonym` - the mapper-level function :ref:`mapper_hybrids` - The Hybrid Attribute extension provides an updated approach to augmenting attribute behavior more flexibly than can be achieved with synonyms. �Callable[..., Any]z Synonym[Any]��fnrY c s t �� | d�S )N)r� Z descriptor)� _orm_synonym)r� �r� r� r^ r_ �decorate� s z synonym_for.<locals>.decorater^ )r� r� r� r^ r� r_ � synonym_for� s $r� c @ s@ e Zd Zddddd�dd�Zdd�d d �Zd d d d �dd�ZdS )�_declared_attr_commonFr� rV )r� � cascading�quietc C s. t |t�r|j}|| _|| _|| _|j| _d S �N)r� � classmethod�__func__�fgetZ _cascadingZ_quietrr )�selfr� r� r� r^ r^ r_ r� � s z _declared_attr_common.__init__zOptional[Type[Any]]�rY c C s t �| j��d�S )NrY )r6 Zget_annotationsr� r �r� r^ r^ r_ �_collect_return_annotation s z0_declared_attr_common._collect_return_annotation�Optional[object]r ��instance�ownerrY c C s� |}t �|�}|d u rHt�d| jj�s>t�d| jj|jf � | �|�S |jrX| �|�S |� � }|d uslJ �|j }| |v r�|| S | �|� || < }|S d S )Nz^__.+__$zEUnmanaged access of declarative attribute %s from non-mapped class %s) r Zopt_manager_of_class�re�matchr� rm r6 �warn� is_mapped�declarative_scanZdeclared_attr_reg)r� r� r� rX �managerr� r� �objr^ r^ r_ �__get__ s& �� z _declared_attr_common.__get__N)FF)rm rn ro r� r� r� r^ r^ r^ r_ r� � s �r� c @ sh e Zd Zejrddddd�dd�Zddd d �d d �Zddd d�dd�Zdd d�dd�Zddd�dd�Z dS )�_declared_directiveFzCallable[..., _T]rV �r� r� c C s d S r� r^ �r� r� r� r^ r^ r_ r� : s z _declared_directive.__init__r� r rR r� c C s d S r� r^ �r� r� r� r^ r^ r_ r� @ � z_declared_directive.__get__rc �r� re rY c C s d S r� r^ �r� r� re r^ r^ r_ �__set__B r� z_declared_directive.__set__�r� rY c C s d S r� r^ �r� r� r^ r^ r_ � __delete__D r� z _declared_directive.__delete__zCallable[..., _TT]z_declared_directive[_TT]r� c C s d S r� r^ �r� r� r^ r^ r_ �__call__F s z _declared_directive.__call__N)F) rm rn ro r> r r� r� r� r� r� r^ r^ r^ r_ r� 5 s �r� c @ s� e Zd ZdZejr�d%ddd�dd�Zddd d �d d �Zdd d �dd�Ze d ddd�dd��Z e dddd�dd��Z dddd�dd�Z e ddd�d d ��Z e d d �d d!��Ze dd �d"d#��Zd$S )&� declared_attra Mark a class-level method as representing the definition of a mapped property or Declarative directive. :class:`_orm.declared_attr` is typically applied as a decorator to a class level method, turning the attribute into a scalar-like property that can be invoked from the uninstantiated class. The Declarative mapping process looks for these :class:`_orm.declared_attr` callables as it scans classes, and assumes any attribute marked with :class:`_orm.declared_attr` will be a callable that will produce an object specific to the Declarative mapping or table configuration. :class:`_orm.declared_attr` is usually applicable to :ref:`mixins <orm_mixins_toplevel>`, to define relationships that are to be applied to different implementors of the class. It may also be used to define dynamically generated column expressions and other Declarative attributes. Example:: class ProvidesUserMixin: "A mixin that adds a 'user' relationship to classes." user_id: Mapped[int] = mapped_column(ForeignKey("user_table.id")) @declared_attr def user(cls) -> Mapped["User"]: return relationship("User") When used with Declarative directives such as ``__tablename__``, the :meth:`_orm.declared_attr.directive` modifier may be used which indicates to :pep:`484` typing tools that the given method is not dealing with :class:`_orm.Mapped` attributes:: class CreateTableName: @declared_attr.directive def __tablename__(cls) -> str: return cls.__name__.lower() :class:`_orm.declared_attr` can also be applied directly to mapped classes, to allow for attributes that dynamically configure themselves on subclasses when using mapped inheritance schemes. Below illustrates :class:`_orm.declared_attr` to create a dynamic scheme for generating the :paramref:`_orm.Mapper.polymorphic_identity` parameter for subclasses:: class Employee(Base): __tablename__ = "employee" id: Mapped[int] = mapped_column(primary_key=True) type: Mapped[str] = mapped_column(String(50)) @declared_attr.directive def __mapper_args__(cls) -> Dict[str, Any]: if cls.__name__ == "Employee": return { "polymorphic_on": cls.type, "polymorphic_identity": "Employee", } else: return {"polymorphic_identity": cls.__name__} class Engineer(Employee): pass :class:`_orm.declared_attr` supports decorating functions that are explicitly decorated with ``@classmethod``. This is never necessary from a runtime perspective, however may be needed in order to support :pep:`484` typing tools that don't otherwise recognize the decorated function as having class-level behaviors for the ``cls`` parameter:: class SomethingMixin: x: Mapped[int] y: Mapped[int] @declared_attr @classmethod def x_plus_y(cls) -> Mapped[int]: return column_property(cls.x + cls.y) .. versionadded:: 2.0 - :class:`_orm.declared_attr` can accommodate a function decorated with ``@classmethod`` to help with :pep:`484` integration where needed. .. seealso:: :ref:`orm_mixins_toplevel` - Declarative Mixin documentation with background on use patterns for :class:`_orm.declared_attr`. F�_DeclaredAttrDecorated[_T]rV r� c C s d S r� r^ r� r^ r^ r_ r� � s zdeclared_attr.__init__r rc r� c C s d S r� r^ r� r^ r^ r_ r� � r� zdeclared_attr.__set__r� c C s d S r� r^ r� r^ r^ r_ r� � r� zdeclared_attr.__delete__zInstrumentedAttribute[_T]r� c C s d S r� r^ r� r^ r^ r_ r� � s zdeclared_attr.__get__�objectrR c C s d S r� r^ r� r^ r^ r_ r� � s r� z$Union[InstrumentedAttribute[_T], _T]c C s d S r� r^ r� r^ r^ r_ r� � s �_stateful_declared_attr[_T]�r| rY c K s t f i |��S r� )�_stateful_declared_attr�rX r| r^ r^ r_ � _stateful� s zdeclared_attr._statefulz_declared_directive[Any]r� c C s t S r� )r� �rX r^ r^ r_ � directive� s zdeclared_attr.directivec C s | j dd�S )NT)r� )r� r� r^ r^ r_ r� � s zdeclared_attr.cascadingN)F)rm rn ro rr r> r r� r� r� r r� r< r� r= r� r� r^ r^ r^ r_ r� K s" \ �r� c @ sH e Zd ZU ded< dd�dd�Zeddd�d d ��Zd d d �dd�ZdS )r� zDict[str, Any]r| r �r| c K s || _ d S r� r� �r� r| r^ r^ r_ r� � s z _stateful_declared_attr.__init__r� r� c K s" | j �� }|�|� tf i |��S r� )r| �copy�updater� )r� r| Znew_kwr^ r^ r_ r� � s z!_stateful_declared_attr._statefulr� zdeclared_attr[_T]r� c C s t |fi | j��S r� )r� r| r� r^ r^ r_ r� � s z _stateful_declared_attr.__call__N)rm rn ro r� r� r< r� r� r^ r^ r^ r_ r� � s r� �Type[_T]c C s | S )a. Mark a class as providing the feature of "declarative mixin". E.g.:: from sqlalchemy.orm import declared_attr from sqlalchemy.orm import declarative_mixin @declarative_mixin class MyMixin: @declared_attr def __tablename__(cls): return cls.__name__.lower() __table_args__ = {"mysql_engine": "InnoDB"} __mapper_args__ = {"always_refresh": True} id = Column(Integer, primary_key=True) class MyModel(MyMixin, Base): name = Column(String(1000)) The :func:`_orm.declarative_mixin` decorator currently does not modify the given class in any way; it's current purpose is strictly to assist the :ref:`Mypy plugin <mypy_toplevel>` in being able to identify SQLAlchemy declarative mixin classes when no other context is present. .. versionadded:: 1.4.6 .. seealso:: :ref:`orm_mixins_toplevel` :ref:`mypy_declarative_mixins` - in the :ref:`Mypy plugin documentation <mypy_toplevel>` r^ r� r^ r^ r_ �declarative_mixin� s )r� � Type[Any]rc c C s� d| j v r| j d }nd }d| j v r0| j d }nd }| j �dd �}|d urtt|t�s`t�d��q�|d ur�t�d��nt||d�}|| _|| _d| j vr�| jj| _t| dt j �t j u r�| jj | _ d S )Nrv �type_annotation_maprx zfDeclarative base class has a 'registry' attribute that is not an instance of sqlalchemy.orm.registry()z�Declarative base class has both a 'registry' attribute and a type_annotation_map entry. Per-base type_annotation_maps are not supported. Please apply the type_annotation_map to this registry directly.)rv r� r� ) rh r r� rx r4 r� r} rv r\ r� r� � constructor)rX rv r� r� r^ r^ r_ �_setup_declarative_base s2 ��� r� c sZ e Zd ZdZejejejejejejejejfddddddddddd� � fdd� Z� ZS ) �MappedAsDataclassa Mixin class to indicate when mapping this class, also convert it to be a dataclass. .. seealso:: :ref:`orm_declarative_native_dataclasses` - complete background on SQLAlchemy native dataclass mapping .. versionadded:: 2.0 �Union[_NoArg, bool]�'Union[_NoArg, Callable[..., Type[Any]]]r rc ) �init�repr�eq�order� unsafe_hash� match_args�kw_only�dataclass_callabler| rY c s� ||||||||d�} t | d�rN| j� t�� � � fdd�| �� D � | _} n | | _} t� jf i | �� t| �s�t�| �} t� | | | � d S )N�r� r� r� r� r� r� r� r� �_sa_apply_dc_transformsc s. i | ]&\}}||t ju r&� �|t j�n|�qS r^ )r8 �NO_ARGr )�.0�k�v��currentr^ r_ � <dictcomp>e s �z7MappedAsDataclass.__init_subclass__.<locals>.<dictcomp>) �hasattrr� r' Z_assert_dc_arguments�items�super�__init_subclass__r! Z(_update_annotations_for_non_mapped_classZ _apply_dataclasses_to_any_class) rX r� r� r� r� r� r� r� r� r| Zapply_dc_transformsZcurrent_transformsZnew_anno�� __class__r� r_ r� E s4 � �����z#MappedAsDataclass.__init_subclass__)rm rn ro rr r8 r� r� � __classcell__r^ r^ r� r_ r� 8 s �r� )� metaclassc s� e Zd ZU dZejr�dd�dd�Zdd�dd�Zd ed < d ed < d ed < ded< ded< ded< ded< ded< ded< dd�dd�Z ddd �� fd d � Z � Z S ) �DeclarativeBasea� Base class used for declarative class definitions. The :class:`_orm.DeclarativeBase` allows for the creation of new declarative bases in such a way that is compatible with type checkers:: from sqlalchemy.orm import DeclarativeBase class Base(DeclarativeBase): pass The above ``Base`` class is now usable as the base for new declarative mappings. The superclass makes use of the ``__init_subclass__()`` method to set up new classes and metaclasses aren't used. When first used, the :class:`_orm.DeclarativeBase` class instantiates a new :class:`_orm.registry` to be used with the base, assuming one was not provided explicitly. The :class:`_orm.DeclarativeBase` class supports class-level attributes which act as parameters for the construction of this registry; such as to indicate a specific :class:`_schema.MetaData` collection as well as a specific value for :paramref:`_orm.registry.type_annotation_map`:: from typing_extensions import Annotated from sqlalchemy import BigInteger from sqlalchemy import MetaData from sqlalchemy import String from sqlalchemy.orm import DeclarativeBase bigint = Annotated[int, "bigint"] my_metadata = MetaData() class Base(DeclarativeBase): metadata = my_metadata type_annotation_map = { str: String().with_variant(String(255), "mysql", "mariadb"), bigint: BigInteger(), } Class-level attributes which may be specified include: :param metadata: optional :class:`_schema.MetaData` collection. If a :class:`_orm.registry` is constructed automatically, this :class:`_schema.MetaData` collection will be used to construct it. Otherwise, the local :class:`_schema.MetaData` collection will supercede that used by an existing :class:`_orm.registry` passed using the :paramref:`_orm.DeclarativeBase.registry` parameter. :param type_annotation_map: optional type annotation map that will be passed to the :class:`_orm.registry` as :paramref:`_orm.registry.type_annotation_map`. :param registry: supply a pre-existing :class:`_orm.registry` directly. .. versionadded:: 2.0 Added :class:`.DeclarativeBase`, so that declarative base classes may be constructed in such a way that is also recognized by :pep:`484` type checkers. As a result, :class:`.DeclarativeBase` and other subclassing-oriented APIs should be seen as superseding previous "class returned by a function" APIs, namely :func:`_orm.declarative_base` and :meth:`_orm.registry.generate_base`, where the base class returned cannot be recognized by type checkers without using plugins. **__init__ behavior** In a plain Python class, the base-most ``__init__()`` method in the class hierarchy is ``object.__init__()``, which accepts no arguments. However, when the :class:`_orm.DeclarativeBase` subclass is first declared, the class is given an ``__init__()`` method that links to the :paramref:`_orm.registry.constructor` constructor function, if no ``__init__()`` method is already present; this is the usual declarative constructor that will assign keyword arguments as attributes on the instance, assuming those attributes are established at the class level (i.e. are mapped, or are linked to a descriptor). This constructor is **never accessed by a mapped class without being called explicitly via super()**, as mapped classes are themselves given an ``__init__()`` method directly which calls :paramref:`_orm.registry.constructor`, so in the default case works independently of what the base-most ``__init__()`` method does. .. versionchanged:: 2.0.1 :class:`_orm.DeclarativeBase` has a default constructor that links to :paramref:`_orm.registry.constructor` by default, so that calls to ``super().__init__()`` can access this constructor. Previously, due to an implementation mistake, this default constructor was missing, and calling ``super().__init__()`` would invoke ``object.__init__()``. The :class:`_orm.DeclarativeBase` subclass may also declare an explicit ``__init__()`` method which will replace the use of the :paramref:`_orm.registry.constructor` function at this level:: class Base(DeclarativeBase): def __init__(self, id=None): self.id = id Mapped classes still will not invoke this constructor implicitly; it remains only accessible by calling ``super().__init__()``:: class MyClass(Base): def __init__(self, id=None, name=None): self.name = name super().__init__(id=id) Note that this is a different behavior from what functions like the legacy :func:`_orm.declarative_base` would do; the base created by those functions would always install :paramref:`_orm.registry.constructor` for ``__init__()``. � Mapper[Self]r� c C s d S r� r^ r� r^ r^ r_ �_sa_inspect_type� r� z DeclarativeBase._sa_inspect_type�InstanceState[Self]c C s d S r� r^ r� r^ r^ r_ �_sa_inspect_instance� r� z$DeclarativeBase._sa_inspect_instance�ClassVar[_RegistryType]r} rx �ClassVar[MetaData]rv z ClassVar[str]rm �ClassVar[Mapper[Any]]rg zClassVar[FromClause]rZ r � __tablename__�__mapper_args__�__table_args__r� c K s d S r� r^ r� r^ r^ r_ r� C r� zDeclarativeBase.__init__rc r� c sD t | jv r t| t � t| � nt| j| | j� t� jf i |�� d S r� ) r� � __bases__�_check_not_declarativer� r& r} rh r� r� r� r� r^ r_ r� E s z!DeclarativeBase.__init_subclass__) rm rn ro rr r> r r� r� r� r� r� r� r^ r^ r� r_ r� y s p r� )rX �baserY c C sR | j }d|v r(t|d �s(t|d d�r:t|�dd �t�rNt�d|j�d���d S )NrZ r� r� z Cannot use zR directly as a declarative base class. Create a Base by creating a subclass of it.) rh �callabler� r� r rb r4 r� rm )rX r� Zcls_dictr^ r^ r_ r� N s � � �� �r� c s� e Zd ZU dZded< ded< ded< ded< d ed < ejr~d d �d d�Zdd �dd�Zded< ded< ded< dd�dd�Z ddd�� fdd � Z � Z S ) �DeclarativeBaseNoMetaz�Same as :class:`_orm.DeclarativeBase`, but does not use a metaclass to intercept new attributes. The :class:`_orm.DeclarativeBaseNoMeta` base may be used when use of custom metaclasses is desirable. .. versionadded:: 2.0 r� r} rx r� rv r� rg �Optional[FromClause]rZ r� r� c C s d S r� r^ r� r^ r^ r_ r� � r� z&DeclarativeBaseNoMeta._sa_inspect_typer� c C s d S r� r^ r� r^ r^ r_ r� � r� z*DeclarativeBaseNoMeta._sa_inspect_instancer r� r� r� r� c K s d S r� r^ r� r^ r^ r_ r� � r� z DeclarativeBaseNoMeta.__init__rc r� c sD t | jv r t| t � t| � nt| j| | j� t� jf i |�� d S r� ) r� r� r� r� r& r} rh r� r� r� r� r^ r_ r� � s z'DeclarativeBaseNoMeta.__init_subclass__) rm rn ro rr r� r> r r� r� r� r� r� r^ r^ r� r_ r� ] s r� zMapperProperty[Any])�targetrd �attrrY c C s t | ||� dS )a' Add a new mapped attribute to an ORM mapped class. E.g.:: add_mapped_attribute(User, "addresses", relationship(Address)) This may be used for ORM mappings that aren't using a declarative metaclass that intercepts attribute set operations. .. versionadded:: 2.0 Nr$ )r� rd r� r^ r^ r_ �add_mapped_attribute� s r� �Base�rv �mapperrX r� �class_registryr� r� r� �Optional[MetaData]�$Optional[Callable[..., Mapper[Any]]]�&Optional[clsregistry._ClsRegistryType]� Optional[_TypeAnnotationMapType]�Callable[..., None]r ) rv r� rX r� r� r� r� r� rY c C s t | |||d�j||||d�S )a Construct a base class for declarative class definitions. The new base class will be given a metaclass that produces appropriate :class:`~sqlalchemy.schema.Table` objects and makes the appropriate :class:`_orm.Mapper` calls based on the information provided declaratively in the class and any subclasses of the class. .. versionchanged:: 2.0 Note that the :func:`_orm.declarative_base` function is superseded by the new :class:`_orm.DeclarativeBase` class, which generates a new "base" class using subclassing, rather than return value of a function. This allows an approach that is compatible with :pep:`484` typing tools. The :func:`_orm.declarative_base` function is a shorthand version of using the :meth:`_orm.registry.generate_base` method. That is, the following:: from sqlalchemy.orm import declarative_base Base = declarative_base() Is equivalent to:: from sqlalchemy.orm import registry mapper_registry = registry() Base = mapper_registry.generate_base() See the docstring for :class:`_orm.registry` and :meth:`_orm.registry.generate_base` for more details. .. versionchanged:: 1.4 The :func:`_orm.declarative_base` function is now a specialization of the more generic :class:`_orm.registry` class. The function also moves to the ``sqlalchemy.orm`` package from the ``declarative.ext`` package. :param metadata: An optional :class:`~sqlalchemy.schema.MetaData` instance. All :class:`~sqlalchemy.schema.Table` objects implicitly declared by subclasses of the base will share this MetaData. A MetaData instance will be created if none is provided. The :class:`~sqlalchemy.schema.MetaData` instance will be available via the ``metadata`` attribute of the generated declarative base class. :param mapper: An optional callable, defaults to :class:`_orm.Mapper`. Will be used to map subclasses to their Tables. :param cls: Defaults to :class:`object`. A type to use as the base for the generated declarative base class. May be a class or tuple of classes. :param name: Defaults to ``Base``. The display name for the generated class. Customizing this is not required, but can improve clarity in tracebacks and debugging. :param constructor: Specify the implementation for the ``__init__`` function on a mapped class that has no ``__init__`` of its own. Defaults to an implementation that assigns \**kwargs for declared fields and relationships to an instance. If ``None`` is supplied, no __init__ will be provided and construction will fall back to cls.__init__ by way of the normal Python semantics. :param class_registry: optional dictionary that will serve as the registry of class names-> mapped classes when string names are used to identify classes inside of :func:`_orm.relationship` and others. Allows two or more declarative base classes to share the same registry of class names for simplified inter-base relationships. :param type_annotation_map: optional dictionary of Python types to SQLAlchemy :class:`_types.TypeEngine` classes or instances. This is used exclusively by the :class:`_orm.MappedColumn` construct to produce column types based on annotations within the :class:`_orm.Mapped` type. .. versionadded:: 2.0 .. seealso:: :ref:`orm_declarative_mapped_column_type_map` :param metaclass: Defaults to :class:`.DeclarativeMeta`. A metaclass or __metaclass__ compatible callable to use as the meta type of the generated declarative base class. .. seealso:: :class:`_orm.registry` )rv r� r� r� )r� rX r� r� )rx � generate_baser� r^ r^ r_ �declarative_base� s n��r c @ s� e Zd ZU dZded< ded< ded< ded < d ed < d ed < ded< ded< ded< ddded�ddddd�dd�Zdd d �d d �Zdsd!dd"d#�d$d%�Ze d&d'�d(d)��Z d*d d+�d,d-�Z d.d d/�d0d1�Z e d2d3d4�d5d6��Ze d2d3d4�d7d8��Zd9d'�d:d;�Zd.d d<�d=d>�Zd?d d@�dAdB�ZdCd dD�dEdF�Zdtdd dH�dIdJ�Zdudd dH�dKdL�ZdCd dD�dMdN�ZdedOefdPdQdRdQdSdT�dUdV�Zeje e e e e e!e"e#e$f dW�e%d?d?dX�dYdZ���Z&e%dvd[d[d[d[d[d[d[d[d\�d]d^d^d^d^d^d^d^d_d`da� dbdZ��Z&dwe'j(e'j(e'j(e'j(e'j(e'j(e'j(e'j(d\�dcd^d^d^d^d^d^d^d_ddda� dedZ�Z&d?d?d@�dfdg�Z)dSdhdi�djdk�Z*d?dld@�dmdn�Z+dxd?dodSdldp�dqdr�Z,dS )yrx a� Generalized registry for mapping classes. The :class:`_orm.registry` serves as the basis for maintaining a collection of mappings, and provides configurational hooks used to map classes. The three general kinds of mappings supported are Declarative Base, Declarative Decorator, and Imperative Mapping. All of these mapping styles may be used interchangeably: * :meth:`_orm.registry.generate_base` returns a new declarative base class, and is the underlying implementation of the :func:`_orm.declarative_base` function. * :meth:`_orm.registry.mapped` provides a class decorator that will apply declarative mapping to a class without the use of a declarative base class. * :meth:`_orm.registry.map_imperatively` will produce a :class:`_orm.Mapper` for a class without scanning the class for declarative class attributes. This method suits the use case historically provided by the ``sqlalchemy.orm.mapper()`` classical mapping function, which is removed as of SQLAlchemy 2.0. .. versionadded:: 1.4 .. seealso:: :ref:`orm_mapping_classes_toplevel` - overview of class mapping styles. z clsregistry._ClsRegistryType�_class_registryz;weakref.WeakKeyDictionary[ClassManager[Any], Literal[True]]� _managersz5weakref.WeakKeyDictionary[Mapper[Any], Literal[True]]�_non_primary_mappersr: rv z&CallableReference[Callable[..., None]]r� � _MutableTypeAnnotationMapTyper� zSet[_RegistryType]� _dependents� _dependenciesrV � _new_mappersN)rv r� r� r� r� r� r� r� c C s� |pt � }|du rt�� }|| _t�� | _t�� | _|| _|| _i | _ |durX| � |� t � | _ t � | _ d| _tj� dtj| < W d � n1 s�0 Y dS )a� Construct a new :class:`_orm.registry` :param metadata: An optional :class:`_schema.MetaData` instance. All :class:`_schema.Table` objects generated using declarative table mapping will make use of this :class:`_schema.MetaData` collection. If this argument is left at its default of ``None``, a blank :class:`_schema.MetaData` collection is created. :param constructor: Specify the implementation for the ``__init__`` function on a mapped class that has no ``__init__`` of its own. Defaults to an implementation that assigns \**kwargs for declared fields and relationships to an instance. If ``None`` is supplied, no __init__ will be provided and construction will fall back to cls.__init__ by way of the normal Python semantics. :param class_registry: optional dictionary that will serve as the registry of class names-> mapped classes when string names are used to identify classes inside of :func:`_orm.relationship` and others. Allows two or more declarative base classes to share the same registry of class names for simplified inter-base relationships. :param type_annotation_map: optional dictionary of Python types to SQLAlchemy :class:`_types.TypeEngine` classes or instances. The provided dict will update the default type mapping. This is used exclusively by the :class:`_orm.MappedColumn` construct to produce column types based on annotations within the :class:`_orm.Mapped` type. .. versionadded:: 2.0 .. seealso:: :ref:`orm_declarative_mapped_column_type_map` NFT)r: �weakref�WeakValueDictionaryr �WeakKeyDictionaryr r rv r� r� �update_type_annotation_map�setr r r r Z_CONFIGURE_MUTEXZ_mapper_registries)r� rv r� r� r� Z lcl_metadatar^ r^ r_ r� � s / zregistry.__init__�_TypeAnnotationMapTyperc )r� rY c C s | j �dd� |�� D �� dS )zQupdate the :paramref:`_orm.registry.type_annotation_map` with new values.c S s i | ]\}}t |�|�qS r^ rA )r� �typZsqltyper^ r^ r_ r� � s �z7registry.update_type_annotation_map.<locals>.<dictcomp>N)r� r� r� )r� r� r^ r^ r_ r � s ��z#registry.update_type_annotation_mapTrQ z"Optional[sqltypes.TypeEngine[Any]])� python_type� _do_fallbacksrY c sl t |�rFt|�r4|� |� fg� fdd�tD ��R }qt|j� |� ff}n.t|t�rf|� dd� � jD �}n|� |� ff}|D ]V\}}| j�|�}|d u r�t � |�}|d urxt � |�}|� � ||�}|d urx| S qx|�rhd } d } t |��r|} t | �r�| j} q�t| �} d} t|��r t|�} d} | d u�rh| �| d�} | d u�rh| d u�sLJ �td| � d|� d �d � | S d S ) Nc 3 s | ]}|� fV qd S r� r^ )r� �lt�Zpython_type_typer^ r_ � <genexpr>� r� z)registry._resolve_type.<locals>.<genexpr>c s s | ]}||fV qd S r� r^ )r� �ptr^ r^ r_ r � r� Z TypeAliasType�NewTypeFzMatching the provided z 'z�' on its resolved value without matching it in the type_annotation_map is deprecated; add this type to the type_annotation_map to allow it to match explicitly.z2.0)rD rE rI � __origin__r� ri r[ r� r r7 Z _type_map_getZ to_instanceZ_resolve_for_python_typerG Z __value__rB rF rC � _resolve_typer? ) r� r r �searchr Z flattenedZsql_typeZ sql_type_instZresolved_sql_typeZpython_type_to_check�kindZres_after_fallbackr^ r r_ r � sj �� � � � �zregistry._resolve_typezFrozenSet[Mapper[Any]]r� c C s t dd� | jD ���| j�S )z9read only collection of all :class:`_orm.Mapper` objects.c s s | ] }|j V qd S r� )r� �r� r� r^ r^ r_ r ( r� z#registry.mappers.<locals>.<genexpr>)� frozensetr �unionr r� r^ r^ r_ �mappers$ s �zregistry.mappersrw )rx rY c C s( || u r d S |j �| � | j�|� d S r� )r �addr )r� rx r^ r^ r_ �_set_depends_on, s zregistry._set_depends_onz Mapper[Any])r� rY c C s, d|_ | jrd S | �| h�D ] }d|_q d S �NT)�_ready_for_configurer �_recurse_with_dependents)r� r� r� r^ r^ r_ �_flag_new_mapper2 s zregistry._flag_new_mapperzSet[RegistryType]zIterator[RegistryType])� registriesrY c c sP |}t � }|rL|�� }|�|� |�|j�|�� |V |�|j�|�� q d S r� )r �popr r� r � difference�rX r$ �todo�doner� r^ r^ r_ r" : s z!registry._recurse_with_dependentsc c sP |}t � }|rL|�� }|�|� |�|j�|�� |V |�|j�|�� q d S r� )r r% r r� r r& r' r^ r^ r_ �_recurse_with_dependenciesM s z#registry._recurse_with_dependencieszIterator[Mapper[Any]]c C s, t �dd� t| j�D �dd� t| j�D ��S )Nc s s* | ]"}|j r|jjs|jjr|jV qd S r� )r� r� � configuredr! r r^ r^ r_ r c s �z1registry._mappers_to_configure.<locals>.<genexpr>c s s | ]}|j s|jr|V qd S r� )r+ r! )r� Znpmr^ r^ r_ r j s �)� itertools�chain�listr r r� r^ r^ r_ �_mappers_to_configurea s ���z registry._mappers_to_configure)� np_mapperrY c C s d| j |< d S r )r )r� r0 r^ r^ r_ �_add_non_primary_mapperq s z registry._add_non_primary_mapperrU rW c C s t �|j|| j� d S r� )r Z remove_classrm r �r� rX r^ r^ r_ � _dispose_clst s zregistry._dispose_clszClassManager[Any])r� rY c C s8 d| j |< |jr t�d|j ��|jd u s.J �| |_d S )NTz1Class '%s' already has a primary mapper defined. )r r� r4 � ArgumentErrorr] rx )r� r� r^ r^ r_ � _add_managerw s ��zregistry._add_managerF)�cascaderY c C s t j| h|d� dS )a] Configure all as-yet unconfigured mappers in this :class:`_orm.registry`. The configure step is used to reconcile and initialize the :func:`_orm.relationship` linkages between mapped classes, as well as to invoke configuration events such as the :meth:`_orm.MapperEvents.before_configured` and :meth:`_orm.MapperEvents.after_configured`, which may be used by ORM extensions or user-defined extension hooks. If one or more mappers in this registry contain :func:`_orm.relationship` constructs that refer to mapped classes in other registries, this registry is said to be *dependent* on those registries. In order to configure those dependent registries automatically, the :paramref:`_orm.registry.configure.cascade` flag should be set to ``True``. Otherwise, if they are not configured, an exception will be raised. The rationale behind this behavior is to allow an application to programmatically invoke configuration of registries while controlling whether or not the process implicitly reaches other registries. As an alternative to invoking :meth:`_orm.registry.configure`, the ORM function :func:`_orm.configure_mappers` function may be used to ensure configuration is complete for all :class:`_orm.registry` objects in memory. This is generally simpler to use and also predates the usage of :class:`_orm.registry` objects overall. However, this function will impact all mappings throughout the running Python process and may be more memory/time consuming for an application that has many registries in use for different purposes that may not be needed immediately. .. seealso:: :func:`_orm.configure_mappers` .. versionadded:: 1.4.0b2 �r6 N)r Z_configure_registries�r� r6 r^ r^ r_ � configure� s 'zregistry.configurec C s t j| h|d� dS )a� Dispose of all mappers in this :class:`_orm.registry`. After invocation, all the classes that were mapped within this registry will no longer have class instrumentation associated with them. This method is the per-:class:`_orm.registry` analogue to the application-wide :func:`_orm.clear_mappers` function. If this registry contains mappers that are dependencies of other registries, typically via :func:`_orm.relationship` links, then those registries must be disposed as well. When such registries exist in relation to this one, their :meth:`_orm.registry.dispose` method will also be called, if the :paramref:`_orm.registry.dispose.cascade` flag is set to ``True``; otherwise, an error is raised if those registries were not already disposed. .. versionadded:: 1.4.0b2 .. seealso:: :func:`_orm.clear_mappers` r7 N)r Z_dispose_registriesr8 r^ r^ r_ �dispose� s zregistry.disposec C s8 d|j v r|j}|�� |j}| �|� tj�|� d S )Nr� )rh r� Z_set_dispose_flagsr] r3 r Z_instrumentation_factory� unregister)r� r� r� r] r^ r^ r_ �_dispose_manager_and_mapper� s z$registry._dispose_manager_and_mapperr� r� r� rb r )r� rX r� r� rY c C s� | j }t|t� r|fp|}t| |d�}t|t�r<|j|d< | jdurP| j|d< d|d< |rd||d< t|d�r�d d d d �d d �}||d< ||||�S )a� Generate a declarative base class. Classes that inherit from the returned class object will be automatically mapped using declarative mapping. E.g.:: from sqlalchemy.orm import registry mapper_registry = registry() Base = mapper_registry.generate_base() class MyClass(Base): __tablename__ = "my_table" id = Column(Integer, primary_key=True) The above dynamically generated class is equivalent to the non-dynamic example below:: from sqlalchemy.orm import registry from sqlalchemy.orm.decl_api import DeclarativeMeta mapper_registry = registry() class Base(metaclass=DeclarativeMeta): __abstract__ = True registry = mapper_registry metadata = mapper_registry.metadata __init__ = mapper_registry.constructor .. versionchanged:: 2.0 Note that the :meth:`_orm.registry.generate_base` method is superseded by the new :class:`_orm.DeclarativeBase` class, which generates a new "base" class using subclassing, rather than return value of a function. This allows an approach that is compatible with :pep:`484` typing tools. The :meth:`_orm.registry.generate_base` method provides the implementation for the :func:`_orm.declarative_base` function, which creates the :class:`_orm.registry` and base class all at once. See the section :ref:`orm_declarative_mapping` for background and examples. :param mapper: An optional callable, defaults to :class:`_orm.Mapper`. This function is used to generate new :class:`_orm.Mapper` objects. :param cls: Defaults to :class:`object`. A type to use as the base for the generated declarative base class. May be a class or tuple of classes. :param name: Defaults to ``Base``. The display name for the generated class. Customizing this is not required, but can improve clarity in tracebacks and debugging. :param metaclass: Defaults to :class:`.DeclarativeMeta`. A metaclass or __metaclass__ compatible callable to use as the meta type of the generated declarative base class. .. seealso:: :ref:`orm_declarative_mapping` :func:`_orm.declarative_base` )rx rv rr Nr� Tr~ Z__mapper_cls__�__class_getitem__r� r )rX rd rY c S s | S r� r^ rl r^ r^ r_ r= / s z1registry.generate_base.<locals>.__class_getitem__)rv r� �tuple�dictri rr r� r� ) r� r� rX r� r� rv rz � class_dictr= r^ r^ r_ r� � s P zregistry.generate_basers )�_registry__clsrY c C s d S r� r^ )r� rA r^ r^ r_ �mapped_as_dataclass7 s z registry.mapped_as_dataclass.r� z Literal[None]r� r� z Callable[[Type[_O]], Type[_O]]) rA r� r� r� r� r� r� r� r� rY c C s d S r� r^ ) r� rA r� r� r� r� r� r� r� r� r^ r^ r_ rB G s zOptional[Type[_O]]z/Union[Type[_O], Callable[[Type[_O]], Type[_O]]]c s8 ddd�� ��������f dd� } |r0| |�S | S dS )a_ Class decorator that will apply the Declarative mapping process to a given class, and additionally convert the class to be a Python dataclass. .. seealso:: :ref:`orm_declarative_native_dataclasses` - complete background on SQLAlchemy native dataclass mapping .. versionadded:: 2.0 rU rW c s0 t | d�������� d�� t�| | j� | S )Nr� r� )�setattrr& rh r� � r� r� r� r� r� r� r� r� r� r^ r_ r� t s ��z.registry.mapped_as_dataclass.<locals>.decorateNr^ ) r� rA r� r� r� r� r� r� r� r� r� r^ rD r_ rB V s $c C s t | ||j� |S )a� Class decorator that will apply the Declarative mapping process to a given class. E.g.:: from sqlalchemy.orm import registry mapper_registry = registry() @mapper_registry.mapped class Foo: __tablename__ = "some_table" id = Column(Integer, primary_key=True) name = Column(String) See the section :ref:`orm_declarative_mapping` for complete details and examples. :param cls: class to be mapped. :return: the class that was passed. .. seealso:: :ref:`orm_declarative_mapping` :meth:`_orm.registry.generate_base` - generates a base class that will apply Declarative mapping to subclasses automatically using a Python metaclass. .. seealso:: :meth:`_orm.registry.mapped_as_dataclass` )r& rh r2 r^ r^ r_ �mapped� s &zregistry.mapped� Callable[[Type[_T]], Type[_T]]r� c s ddd�� �fdd� }|S )a� Class decorator which will invoke :meth:`_orm.registry.generate_base` for a given base class. E.g.:: from sqlalchemy.orm import registry mapper_registry = registry() @mapper_registry.as_declarative_base() class Base: @declared_attr def __tablename__(cls): return cls.__name__.lower() id = Column(Integer, primary_key=True) class MyMappedClass(Base): ... All keyword arguments passed to :meth:`_orm.registry.as_declarative_base` are passed along to :meth:`_orm.registry.generate_base`. r� rW c s" | � d< | j � d< �jf i � ��S )NrX r� )rm r� r� �r| r� r^ r_ r� � s z.registry.as_declarative_base.<locals>.decorater^ )r� r| r� r^ rG r_ �as_declarative_base� s z registry.as_declarative_basez Mapper[_O]c C s t | ||j� |jS )a� Map a class declaratively. In this form of mapping, the class is scanned for mapping information, including for columns to be associated with a table, and/or an actual table object. Returns the :class:`_orm.Mapper` object. E.g.:: from sqlalchemy.orm import registry mapper_registry = registry() class Foo: __tablename__ = "some_table" id = Column(Integer, primary_key=True) name = Column(String) mapper = mapper_registry.map_declaratively(Foo) This function is more conveniently invoked indirectly via either the :meth:`_orm.registry.mapped` class decorator or by subclassing a declarative metaclass generated from :meth:`_orm.registry.generate_base`. See the section :ref:`orm_declarative_mapping` for complete details and examples. :param cls: class to be mapped. :return: a :class:`_orm.Mapper` object. .. seealso:: :ref:`orm_declarative_mapping` :meth:`_orm.registry.mapped` - more common decorator interface to this function. :meth:`_orm.registry.map_imperatively` )r& rh rg r2 r^ r^ r_ �map_declaratively� s /zregistry.map_declarativelyr� )r] � local_tabler| rY c K s t | |||�S )a� Map a class imperatively. In this form of mapping, the class is not scanned for any mapping information. Instead, all mapping constructs are passed as arguments. This method is intended to be fully equivalent to the now-removed SQLAlchemy ``mapper()`` function, except that it's in terms of a particular registry. E.g.:: from sqlalchemy.orm import registry mapper_registry = registry() my_table = Table( "my_table", mapper_registry.metadata, Column("id", Integer, primary_key=True), ) class MyClass: pass mapper_registry.map_imperatively(MyClass, my_table) See the section :ref:`orm_imperative_mapping` for complete background and usage examples. :param class\_: The class to be mapped. Corresponds to the :paramref:`_orm.Mapper.class_` parameter. :param local_table: the :class:`_schema.Table` or other :class:`_sql.FromClause` object that is the subject of the mapping. Corresponds to the :paramref:`_orm.Mapper.local_table` parameter. :param \**kw: all other keyword arguments are passed to the :class:`_orm.Mapper` constructor directly. .. seealso:: :ref:`orm_imperative_mapping` :ref:`orm_declarative_mapping` r+ )r� r] rJ r| r^ r^ r_ �map_imperatively s 8zregistry.map_imperatively)T)F)F).)N)N)-rm rn ro rr r� r( r� r r �propertyr r r# r� r" r* r/ r1 r3 r5 r9 r: r< r� ru r� � compat_typing�dataclass_transformr0 r1 r- r. r r r r r r rB r8 r� rE rH rI rK r^ r^ r^ r_ rx V s� �D �Q ) �i�� ��& ��$5)%5 �rx rF r� c K s2 | � dd�| � dd� }}t||d�jf i | ��S )a� Class decorator which will adapt a given class into a :func:`_orm.declarative_base`. This function makes use of the :meth:`_orm.registry.as_declarative_base` method, by first creating a :class:`_orm.registry` automatically and then invoking the decorator. E.g.:: from sqlalchemy.orm import as_declarative @as_declarative() class Base: @declared_attr def __tablename__(cls): return cls.__name__.lower() id = Column(Integer, primary_key=True) class MyMappedClass(Base): ... .. seealso:: :meth:`_orm.registry.as_declarative_base` rv Nr� )rv r� )r% rx rH )r| rv r� r^ r^ r_ �as_declarativeM s �� �rO zOptional[Mapper[Any]]c C s( t | �}|d u r$t�| �r$t�| � |S r� )r r) Zhas_clsZraise_unmapped_for_cls)rX �mpr^ r^ r_ �_inspect_decl_metau s rQ )F)�rr � __future__r r, r� r> r r r r r r r r r r r r r r r r r r � r r r r r Z_orm_constructorsr r r r r r r� r r! r" r# Z decl_baser% r& r' r( r) r* r, Zdescriptor_propsr- r. r� r� r/ Z propertiesr0 Z relationshipsr1 �stater2 r4 r5 r6 Zsqlr7 Zsql.baser8 Z sql.elementsr9 Z sql.schemar: Zsql.selectabler; r< r= rM r? Z util.typingr@ rB rC rD rE rF rG rH rI rJ Z_typingrK rL rM rN rO Z sql._typingrP Z sql.type_apirQ rR rT r r Z_DeclaredAttrDecoratedr` ri ra Z Inspectablerp rN rt ru r� r� r� Z_MappedAttributer� r� r� r� r� r� r� r� r� r� r rx rw rO Z _inspectsrQ r^ r^ r^ r_ �<module> s0 � � �� �*A ,)A � V �k�"{ u(� sqlalchemy/orm/__pycache__/writeonly.cpython-39.pyc 0000644 00000045370 15125143220 0016404 0 ustar 00 a ��Jh!W � @ s� d Z ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z dd lm Z dd lm Z dd lm Z dd lm Z dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z ddlm Z ddlm Z d d lm Z d d lm Z d d lm!Z! d d lm"Z" d d!l#m$Z$ d d"l#m%Z% d d#l#m&Z& d d$l#m'Z' d d%l(m)Z) d d&l(m*Z* d d'l(m+Z+ d d(l,m-Z- e�rbdd)lm.Z. dd*l/m0Z0 dd+lm1Z1 dd,lm2Z2 dd-l3m4Z4 dd.l3m5Z5 dd/l6m7Z7 dd0lm8Z8 dd1l9m:Z: dd2l"m;Z; d d3l<m=Z= d d4l>m?Z? d d5l>m@Z@ ed6ed7�ZAG d8d9� d9eeA �ZBG d:d;� d;ejCejD�ZEe!jFejGjHd<d=�G d>d?� d?ejIe!jJ���ZKG d@dA� dA�ZLG dBdC� dCeeA �ZMG dDdE� dEeMeA �ZNdFS )Gz�Write-only collection API. This is an alternate mapped attribute style that only supports single-item collection mutation operations. To read the collection, a select() object must be executed each time. .. versionadded:: 2.0 � )� annotations)�Any)� Collection)�Dict)�Generic)�Iterable)�Iterator)�List)�NoReturn)�Optional)�overload)�Tuple)�Type)� TYPE_CHECKING)�TypeVar)�Union)� bindparam� )� attributes)� interfaces)� relationships)� strategies)� NEVER_SET)� object_mapper)� PassiveFlag)�RelationshipDirection� )�exc)�inspect)�log)�util)�delete)�insert)�select)�update)�Delete)�Insert)�Update)�Literal)�QueryableAttribute)� _InstanceDict)�AttributeEventToken)�LoaderCallableStatus)�_AdaptedCollectionProtocol)�CollectionAdapter)�Mapper)�_RelationshipOrderByArg)� InstanceState)� AliasedClass)� _Dispatch)� FromClause)�Select�_T)�boundc @ s� e Zd ZU dZded< ded< ded< ded< d%d d d d d d�dd�Zedd�dd��Zedd�dd��Zdd�dd�Z ddd �d d �Z d d d �d!d"�Z d d d �d#d$�Z dS )&�WriteOnlyHistoryzDOverrides AttributeHistory to receive append/remove events directly.zutil.OrderedIdentitySet�unchanged_items� added_items� deleted_items�bool�_reconcile_collectionN�WriteOnlyAttributeImpl�InstanceState[_T]r z Optional[WriteOnlyHistory[_T]]�None)�attr�state�passive�apply_to�returnc C sp |rH|t j@ r&t�d|� d|� d���|j| _|j| _|j| _|j| _n$t� � | _t� � | _t� � | _d| _d S )Nz Attribute z� can't load the existing state from the database for this operation; full iteration is not permitted. If this is a delete operation, configure passive_deletes=True on the z- relationship in order to resolve this error.F) r �SQL_OKr �InvalidRequestErrorr9 r: r; r= r ZOrderedIdentitySet)�selfrA rB rC rD � rI �M/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/writeonly.py�__init__U s �� zWriteOnlyHistory.__init__zList[_T]�rE c C s t | j�| j��S �N)�listr: �unionr9 �rH rI rI rJ �added_plus_unchangedp s z%WriteOnlyHistory.added_plus_unchangedc C s t | j�| j��| j��S rM )rN r: rO r9 r; rP rI rI rJ � all_itemst s ��zWriteOnlyHistory.all_items�attributes.Historyc C s` | j r0| j�| j�}| j�| j�}| j�|�}n| j| j| j }}}t�t|�t|�t|��S rM ) r= r: � differencer9 r; � intersectionr ZHistoryrN )rH �addedZdeletedZ unchangedrI rI rJ � as_history| s � zWriteOnlyHistory.as_historyzUnion[int, slice]zUnion[List[_T], _T])�indexrE c C s t | j�| S rM )rN r: )rH rX rI rI rJ �indexed� s zWriteOnlyHistory.indexedr6 )�valuerE c C s | j �|� d S rM )r: �add�rH rZ rI rI rJ � add_added� s zWriteOnlyHistory.add_addedc C s( || j v r| j �|� n | j�|� d S rM )r: �remover; r[ r\ rI rI rJ � add_removed� s z WriteOnlyHistory.add_removed)N) �__name__� __module__� __qualname__�__doc__�__annotations__rK �propertyrQ rR rW rY r] r_ rI rI rI rJ r8 M s � r8 c s� e Zd ZU dZded< dZded< dZded< dZded< dZded< dZ ded < d Z d ed < e Z d ed< ded< ddddd dd�� fdd� Z ejfdddd d �d d �ZedZddd!d"d#d$�d%d&��Zed[ddd'dd#d$�d(d&��Zed\ddd)dd*d$�d+d&��Zd,ejfddd)dd*d$�d-d&�Zejd.d/�d0d1��Zejd.d/�d2d3��Zd]dddd4d5d6d7�d8d9�Zd^dddd4d5d6d7�d:d;�Zddd<d=�d>d?�Zd,ejd,ddfdddd4ddddd6d@� dAdB�ZdddCdD�dEdF�ZddddCdG�dHdI�Z ej fddddJd �dKdL�Z ej fddddMd �dNdO�Z ddd<dP�dQdR�Z!ej fdddd4dd6dS�dTdU�Z"ej fdddd4dd6dS�dVdW�Z#ej fdddd4dd6dS�dXdY�Z$� Z%S )_r> Tr< � uses_objectsF� default_accepts_scalar_loader�supports_population�_supports_dynamic_iteration� collection�dynamicrI r0 �order_byzType[WriteOnlyHistory[Any]]�collection_history_clsz Type[WriteOnlyCollection[Any]]� query_classz#Union[Type[Any], AliasedClass[Any]]�strz"_Dispatch[QueryableAttribute[Any]]z Mapper[_T]r )�class_�key�dispatch� target_mapperrl �kwc s8 t � j||d |fi |�� || _t| _|r4t|�| _d S rM )�superrK rs �WriteOnlyCollectionrn �tuplerl )rH rp rq rr rs rl rt �� __class__rI rJ rK � s z WriteOnlyAttributeImpl.__init__zInstanceState[Any]r* r z8Union[util.OrderedIdentitySet, WriteOnlyCollection[Any]])rB �dict_rC rE c C s* |t j@ s| �|t j�jS | �| |�S d S rM )r rF �_get_collection_history�PASSIVE_NO_INITIALIZEr: rn )rH rB rz rC rI rI rJ �get� s �zWriteOnlyAttributeImpl.get.z Literal[None]z Literal[PassiveFlag.PASSIVE_OFF]r. )rB rz � user_datarC rE c C s d S rM rI �rH rB rz r~ rC rI rI rJ �get_collection� s z%WriteOnlyAttributeImpl.get_collectionr- c C s d S rM rI r rI rI rJ r� � s z$Optional[_AdaptedCollectionProtocol]zIUnion[Literal[LoaderCallableStatus.PASSIVE_NO_RESULT], CollectionAdapter]c C s d S rM rI r rI rI rJ r� � s Nc C s4 |t j@ s| �||�j}n| �||�}|j}t|�S rM )r rF r{ r: rQ �DynamicCollectionAdapter)rH rB rz r~ rC �data�historyrI rI rJ r� � s z attributes.AttributeEventTokenrL c C s t �| t j�S rM )r r+ Z OP_APPENDrP rI rI rJ � _append_token� s z$WriteOnlyAttributeImpl._append_tokenc C s t �| t j�S rM )r r+ Z OP_REMOVErP rI rI rJ � _remove_token� s z$WriteOnlyAttributeImpl._remove_tokenz Optional[AttributeEventToken]z Optional[WriteOnlyHistory[Any]]r@ )rB rz rZ � initiator�collection_historyrE c C sd |d u r| � ||�}|�|� | jjD ]}||||p8| j�}q&| jr`|d ur`| �t�|�|d� d S �NT) �_modified_eventr] rr �appendr� � trackparent� sethasparentr �instance_state�rH rB rz rZ r� r� �fnrI rI rJ �fire_append_event� s z(WriteOnlyAttributeImpl.fire_append_eventc C sd |d u r| � ||�}|�|� | jr@|d ur@| �t�|�|d� | jjD ]}||||pZ| j� qHd S )NF) r� r_ r� r� r r� rr r^ r� r� rI rI rJ �fire_remove_event s z(WriteOnlyAttributeImpl.fire_remove_eventzWriteOnlyHistory[Any])rB rz rE c C sH | j |jvr$| �| |tj�|j| j < |�|| t� d|| j < |j| j S r� )rq �committed_staterm r �PASSIVE_NO_FETCHr� r )rH rB rz rI rI rJ r� s � z&WriteOnlyAttributeImpl._modified_event) rB rz rZ r� rC � check_old�pop�_adaptrE c C s� |r|j | j u rd S |r$|d u r$d S |} t| �} |jrd| jsNt�d| � d���t�| j|||d��} | � ||�} |js~| j } n | � | j �} | � | �} t�| �� | �}| � | �}| D ] }||v r�| j|||d | d� q�|D ]}| j|||d | d� q�d S )Nz Collection "zV" does not support implicit iteration; collection replacement operations can't be used�rC )r� )Z parent_tokenrN � has_identityri r rG r Z IdentitySetr} r� r: rO rU rT r� r� )rH rB rz rZ r� rC r� r� r� �iterable� new_valuesZold_collectionr� � constants� additionsZremovals�memberrI rI rJ �set/ sP �� � ��zWriteOnlyAttributeImpl.setr )�args�kwargsrE c O s t � �d S rM ��NotImplementedError)rH r� r� rI rI rJ r! l s z WriteOnlyAttributeImpl.delete)rB rz rZ rE c C s t d��d S )Nz7Dynamic attributes don't support collection population.r� )rH rB rz rZ rI rI rJ �set_committed_valueo s �z*WriteOnlyAttributeImpl.set_committed_valuerS c C s | � ||�}|�� S rM )r{ rW �rH rB rz rC �crI rI rJ � get_historyv s z"WriteOnlyAttributeImpl.get_historyz$List[Tuple[InstanceState[Any], Any]]c C s | � ||�}dd� |jD �S )Nc S s g | ]}t �|�|f�qS rI )r r� )�.0�xrI rI rJ � <listcomp>� � z:WriteOnlyAttributeImpl.get_all_pending.<locals>.<listcomp>)r{ rR r� rI rI rJ �get_all_pending s z&WriteOnlyAttributeImpl.get_all_pending)rB rC rE c C sT | j |jv r|j| j }n| �| |tj�}|jrL|tj@ rL| j| |||d�S |S d S )N)rD )rq r� rm r r� r� ZINIT_OK)rH rB rC r� rI rI rJ r{ � s ��z.WriteOnlyAttributeImpl._get_collection_history)rB rz rZ r� rC rE c C s || ur| � ||||� d S rM )r� �rH rB rz rZ r� rC rI rI rJ r� � s z WriteOnlyAttributeImpl.appendc C s || ur| � ||||� d S rM )r� r� rI rI rJ r^ � s z WriteOnlyAttributeImpl.removec C s | j |||||d� d S )Nr� )r^ r� rI rI rJ r� � s zWriteOnlyAttributeImpl.pop)..)..)..)N)N)&r` ra rb rf rd rg rh ri rj rk rl r8 rm rK r Z PASSIVE_OFFr} r r� r Zmemoized_propertyr� r� r� r� r� r� r! r� r� r� r| r� r{ r� r^ r� � __classcell__rI rI rx rJ r> � sn � � � �� � �� = � � ���r> Z write_only)Zlazyc @ s e Zd ZeZddd�dd�ZdS )�WriteOnlyLoaderz Mapper[Any]r@ )�mapperrE c C s\ d| _ | jr | jjtjtjfvr0t�d| j ��t j | j|d| j | jj | jj | jjd� d S )NTztOn relationship %s, 'dynamic' loaders cannot be used with many-to-one/one-to-one relationships and/or uselist=False.)Z useobject� impl_classrs rl rn )Zis_class_levelZuselistZparent_property� directionr � ONETOMANYZ MANYTOMANYr rG r Z_register_attributer� r� rl rn )rH r� rI rI rJ �init_class_attribute� s& ����z$WriteOnlyLoader.init_class_attributeN)r` ra rb r> r� r� rI rI rI rJ r� � s r� c @ s` e Zd ZU dZded< dd�dd�Zdd�d d �Zd d�d d �Zdd�dd�Zdd�dd�Z dS )r� z9simplified CollectionAdapter for internal API consistencyzCollection[Any]r� �r� c C s || _ d S rM r� )rH r� rI rI rJ rK � s z!DynamicCollectionAdapter.__init__z Iterator[Any]rL c C s t | j�S rM )�iterr� rP rI rI rJ �__iter__� s z!DynamicCollectionAdapter.__iter__r@ c C s d S rM rI rP rI rI rJ � _reset_empty� s z%DynamicCollectionAdapter._reset_empty�intc C s t | j�S rM )�lenr� rP rI rI rJ �__len__� s z DynamicCollectionAdapter.__len__r< c C s dS r� rI rP rI rI rJ �__bool__� s z!DynamicCollectionAdapter.__bool__N) r` ra rb rc rd rK r� r� r� r� rI rI rI rJ r� � s r� c @ sZ e Zd ZU dZesdZded< ded< ddd �d d �Zd d d�dd�Zdd d�dd�Z dS )�AbstractCollectionWriterzsVirtual collection which includes append/remove methods that synchronize into the attribute event system. rI r6 �instancezTuple[FromClause, ...]� _from_objr> r? )rA rB c C s� |� � }tr|sJ �|| _|| _t|�}|j| jj }|jd urT|j� � |jf| _ nd| _ |j |dd�f| _ | jj r�| jj | _nd| _d S )NrI F)Zalias_secondary)�objr r� rA r �_propsrq Z secondaryr� Z__clause_element__r� Z _with_parent�_where_criteriarl �_order_by_clauses)rH rA rB r� r� �proprI rI rJ rK � s � z!AbstractCollectionWriter.__init__� Iterable[_T]r@ ��iteratorrE c C s0 |D ]&}| j �t�| j�t�| j�|d � qd S rM )rA r� r r� r� � instance_dict)rH r� �itemrI rI rJ � _add_all_impl s �z&AbstractCollectionWriter._add_all_impl�r� rE c C s& | j �t�| j�t�| j�|d � d S rM )rA r^ r r� r� r� �rH r� rI rI rJ � _remove_impl" s �z%AbstractCollectionWriter._remove_implN) r` ra rb rc r � __slots__rd rK r� r� rI rI rI rJ r� � s ! r� c @ s� e Zd ZdZdZdd�dd�Zdd�dd �Zd d�d d �Zd d�dd�Zdd�dd�Z ddd�dd�Z ddd�dd�Z ddd�d d �Z d S ) rv a� Write-only collection which can synchronize changes into the attribute event system. The :class:`.WriteOnlyCollection` is used in a mapping by using the ``"write_only"`` lazy loading strategy with :func:`_orm.relationship`. For background on this configuration, see :ref:`write_only_relationship`. .. versionadded:: 2.0 .. seealso:: :ref:`write_only_relationship` )r� rA r� r� r� r rL c C s t d��d S )Nz�WriteOnly collections don't support iteration in-place; to query for collection items, use the select() method to produce a SQL statement and execute it with session.scalars().)� TypeErrorrP rI rI rJ r� D s �z WriteOnlyCollection.__iter__zSelect[Tuple[_T]]c C s< t | jj�j| j� }| jr&|j| j� }| jr8|j| j� }|S )z�Produce a :class:`_sql.Select` construct that represents the rows within this instance-local :class:`_orm.WriteOnlyCollection`. ) r# rA rs �wherer� r� � select_fromr� rl )rH �stmtrI rI rJ r# K s zWriteOnlyCollection.selectr& c C s� t | j�}|j}|j| jj }|jtjur4t � d��i }|j D ],\}}|� |||j |�}td|d�||j< q>t| jj�jf i |��S )aN For one-to-many collections, produce a :class:`_dml.Insert` which will insert new rows in terms of this this instance-local :class:`_orm.WriteOnlyCollection`. This construct is only supported for a :class:`_orm.Relationship` that does **not** include the :paramref:`_orm.relationship.secondary` parameter. For relationships that refer to a many-to-many table, use ordinary bulk insert techniques to produce new objects, then use :meth:`_orm.AbstractCollectionWriter.add_all` to associate them with the collection. z�Write only bulk INSERT only supported for one-to-many collections; for many-to-many, use a separate bulk INSERT along with add_all().N)Z callable_)r r� r� r� rA rq r� r r� r rG Zsynchronize_pairsZ_get_attr_w_warn_on_none�dictr r" rs �values)rH rB r� r� rz �l�rr� rI rI rJ r" W s" ��zWriteOnlyCollection.insertr' c C s t | jj�j| j� S )z�Produce a :class:`_dml.Update` which will refer to rows in terms of this instance-local :class:`_orm.WriteOnlyCollection`. )r$ rA rs r� r� rP rI rI rJ r$ s zWriteOnlyCollection.updater% c C s t | jj�j| j� S )z�Produce a :class:`_dml.Delete` which will refer to rows in terms of this instance-local :class:`_orm.WriteOnlyCollection`. )r! rA rs r� r� rP rI rI rJ r! � s zWriteOnlyCollection.deleter� r@ r� c C s | � |� dS )z�Add an iterable of items to this :class:`_orm.WriteOnlyCollection`. The given items will be persisted to the database in terms of the parent instance's collection on the next flush. N�r� )rH r� rI rI rJ �add_all� s zWriteOnlyCollection.add_allr6 r� c C s | � |g� dS )z�Add an item to this :class:`_orm.WriteOnlyCollection`. The given item will be persisted to the database in terms of the parent instance's collection on the next flush. Nr� r� rI rI rJ r[ � s zWriteOnlyCollection.addc C s | � |� dS )z�Remove an item from this :class:`_orm.WriteOnlyCollection`. The given item will be removed from the parent instance's collection on the next flush. N)r� r� rI rI rJ r^ � s zWriteOnlyCollection.removeN) r` ra rb rc r� r� r# r" r$ r! r� r[ r^ rI rI rI rJ rv + s ( rv N)Orc � __future__r �typingr r r r r r r r r r r r r r r Zsqlalchemy.sqlr � r r r r �baser r r r r r r r Zsqlr! r" r# r$ Zsql.dmlr% r& r' Z util.typingr( r) Z_typingr* r+ r, � collectionsr- r. r� r/ r0 rB r1 r2 �eventr3 Zsql.selectabler4 r5 r6 r8 ZHasCollectionAdapterZ AttributeImplr> Z class_loggerZRelationshipPropertyZ strategy_forZAbstractRelationshipLoaderZ Identifiedr� r� r� rv rI rI rI rJ �<module> s� I � ' ? sqlalchemy/orm/__pycache__/descriptor_props.cpython-39.pyc 0000644 00000100646 15125143220 0017747 0 ustar 00 a ��Jho� � @ s U d Z ddlmZ ddlmZ ddlZddlZddlZddlZddlm Z ddlm Z ddlm Z ddlm Z dd lm Z dd lmZ dd lmZ dd lmZ dd lmZ ddlmZ ddlmZ ddlmZ ddlZddlmZ ddlmZ ddlmZ ddlm Z ddlm Z ddlm Z ddlm Z ddl m!Z! ddl m"Z" ddl m#Z# dd l m$Z$ dd l m%Z% dd lm&Z& dd lm'Z' d d!lm(Z( d d"lm)Z* d d#lm+Z+ d d$lm,Z, d dlmZ d d%l,m-Z- d d&l,m.Z. d d'l/m0Z0 d d(l1m2Z2 d d)l1m3Z3 d d*l1m4Z4 ej�r*dd+l5m6Z6 dd,l5m7Z7 dd-lm8Z8 dd.lm9Z9 dd/lm:Z: dd0l;m<Z< dd1l=m>Z> dd2l?m@Z@ dd3lAmBZB dd4lAmCZC dd5lDmEZE d d6lFmGZG d d7lHmIZI d d8lJmKZK d d9lJmLZL d d:l/mMZM d d;l/mNZN d d<lOmPZP d d=lQmRZR d d>lSmTZT d d?l1mUZU d d@l1mVZV d dAl1mWZW d dBl1mXZX edCe dD�ZYedEe dD�ZZG dFdG� dGe$eY �Z[ee\dHdIdJdKf Z]edLe dD�Z^e�_� Z`dMeadN< G dOdP� dPe#e^ e"e[e^ �ZbG dQdR� dRebeY eeY �ZcG dSdT� dTe[eY �ZdG dUdV� dVe[eY �ZeG dWdX� dXeeeY eeY �ZfdS )Yz�Descriptor properties are more "auxiliary" properties that exist as configurational elements, but don't participate as actively in the load/persist ORM loop. � )� annotations)� is_dataclassN)�Any)�Callable)�Dict)�List)�NoReturn)�Optional)�Sequence)�Tuple)�Type)� TYPE_CHECKING)�TypeVar)�Union� )� attributes)�util)�_DeclarativeMapped)�LoaderCallableStatus)�Mapped)� PassiveFlag)�SQLORMOperations)�_AttributeOptions)�_IntrospectsAnnotations)� _MapsColumns)�MapperProperty)�PropComparator)� _none_set)�de_stringify_annotation� )�event)�exc)�schema)�sql�� expression)� operators)� BindParameter)�get_args)� is_fwd_ref)� is_pep593)� _InstanceDict)� _RegistryType)�History)�InstrumentedAttribute)�QueryableAttribute)�ORMCompileState)�_ClassScanMapperConfig)�Mapper)�ColumnProperty�� MappedColumn)� InstanceState)� Connection)�Row)�_DMLColumnArgument)� _InfoType)� ClauseList)� ColumnElement)� OperatorType)�Column)�Select)�_AnnotationScanType)�CallableReference)�DescriptorReference)�RODescriptorReference�_T)�bound�_PTc @ sX e Zd ZU dZdZded< dZdZded< ej fdd d d d �d d�Z ddd�dd�Z dS )�DescriptorPropertyzO:class:`.MapperProperty` which proxies access to a user-defined descriptor.N� Optional[str]�docFzDescriptorReference[Any]� descriptor�InstanceState[Any]r+ r r- ��state�dict_�passive�returnc C s t � �d S �N)�NotImplementedError��selfrM rN rO � rU �T/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/descriptor_props.py� get_historyf s z DescriptorProperty.get_history� Mapper[Any]�None��mapperrP c s� ��G �fdd�dt j�}�jd u rHt� j�jd �}� ��j|�rH|�_�jd u r�dddd��fdd� }ddd��fd d � }ddd��fd d � }t|||d ��_t ��j��j j�j�j� �fdd��j �d�}|�j�|_ � j � �j|� d S )Nc sZ e Zd ZdZdZdZedd�� fdd� �Zdd�d d �Ze j fd d d dd�� fdd� Z dS )z7DescriptorProperty.instrument_class.<locals>._ProxyImplFT�bool�rP c s � j S rQ )� uses_objects�rT ��proprU rV r^ v s zDDescriptorProperty.instrument_class.<locals>._ProxyImpl.uses_objects�str��keyc S s || _ d S rQ rc )rT rd rU rU rV �__init__z s z@DescriptorProperty.instrument_class.<locals>._ProxyImpl.__init__rK r+ r r- rL c s � � |||�S rQ )rW rS r` rU rV rW } s zCDescriptorProperty.instrument_class.<locals>._ProxyImpl.get_historyN) �__name__� __module__� __qualname__Zaccepts_scalar_loaderZload_on_unexpireZ collection�propertyr^ re r � PASSIVE_OFFrW rU r` rU rV � _ProxyImplq s �rk r rY )�obj�valuerP c s t | � j|� d S rQ )�setattr�name)rl rm r_ rU rV �fset� s z1DescriptorProperty.instrument_class.<locals>.fset)rl rP c s t | � j� d S rQ )�delattrro �rl r_ rU rV �fdel� s z1DescriptorProperty.instrument_class.<locals>.fdelc s t | � j�S rQ )�getattrro rr r_ rU rV �fget� s z1DescriptorProperty.instrument_class.<locals>.fget)ru rp rs c s �� � �S rQ )�_comparator_factoryrU )r[ rT rU rV �<lambda>� � z5DescriptorProperty.instrument_class.<locals>.<lambda>)rI Zoriginal_property)r Z AttributeImplrJ rt �class_rd Z_is_userland_descriptorri Zcreate_proxied_attribute�parentrI �impl� class_managerZinstrument_attribute)rT r[ rk �descrp rs ru � proxy_attrrU )r[ ra rT rV �instrument_classn s* � z#DescriptorProperty.instrument_class) rf rg rh �__doc__rI �__annotations__r^ Z_links_to_entityr rj rW r rU rU rU rV rG [ s �rG z Column[_T]zMappedColumn[_T]zInstrumentedAttribute[_T]z Mapped[_T]�_CCzFweakref.WeakKeyDictionary[Type[Any], Callable[[Any], Tuple[Any, ...]]]�_composite_gettersc s0 e Zd ZU dZded< ded< ded< ded < dad d d d d d d �d ddddddddd� � fdd�Zddd�� fdd � Zd d d �d d!�Zdd"�d#d$�Ze � Z dd"�d%d&�Z e � d'�d(d)d*dd+d,d-d-ddd.� d/d0��Zdd"�d1d2�Ze � d'�e � d3�d)d*dd+dd4�d5d6���Ze jd7d"�d8d9��Ze je � d:�d;d"�d<d=���Ze je � d:�d>d"�d?d@���ZedAd"�dBdC��ZedDd"�dEdF��Ze � d:�dd"�dGdH��Zdd"�dIdJ�Ze jdKd"�dLdM��ZdNd"�dOdP�Z e j fdQdRdSdTdU�dVdW�Z ddXd�dYdZ�Z G d[d\� d\e!j"e# �Z$G d]d^� d^e%e& �Z'd+d"�d_d`�Z(� Z)S )b�CompositePropertyz�Defines a "composite" mapped attribute, representing a collection of columns as one attribute. :class:`.CompositeProperty` is constructed using the :func:`.composite` function. .. seealso:: :ref:`mapper_composite` z$Union[Type[_CC], Callable[..., _CC]]�composite_classz#Tuple[_CompositeAttrType[Any], ...]�attrsz=CallableReference[Optional[Callable[[_CC], Tuple[Any, ...]]]]� _generated_composite_accessorzType[Comparator[_CC]]�comparator_factoryNF)�attribute_options�active_history�deferred�groupr� �infozCUnion[None, Type[_CC], Callable[..., _CC], _CompositeAttrType[Any]]z_CompositeAttrType[Any]�Optional[_AttributeOptions]r\ rH z Optional[Type[Comparator[_CC]]]�Optional[_InfoType]r ) �_class_or_attrr� r� r� r� r� r� r� �kwargsc s� t � j|d� t|tttjf�r4|f| | _d | _n || _|| _|| _ || _ || _ |d ur^|n| j j | _d | _|d ur�| j�|� t�| � | �� | �� d S �N)r� )�superre � isinstancer rb r# r< r� r� r� r� r� � __class__� Comparatorr� r� r� �updater �set_creation_order�_create_descriptor�_init_accessor) rT r� r� r� r� r� r� r� r� r� �r� rU rV re � s& �� zCompositeProperty.__init__rX rY rZ c s t � �|� | �� d S rQ )r� r �_setup_event_handlers�rT r[ r� rU rV r � s z"CompositeProperty.instrument_classr� zTuple[Any, ...]�rm rP c C sb | j r| � |�S z |j}W n< tyV } z$t�d| jj� d��|�W Y d }~nd }~0 0 |� S d S )NzComposite class zX is not a dataclass and does not define a __composite_values__() method; can't get state)r� �__composite_values__�AttributeError�sa_exc�InvalidRequestErrorr� rf )rT rm �accessorZaerU rU rV � _composite_values_from_instance� s ��z1CompositeProperty._composite_values_from_instancer] c C s | � � dS )zwInitialization which occurs after the :class:`.Composite` has been associated with its parent mapper. N)�_setup_arguments_on_columnsr_ rU rU rV �do_init s zCompositeProperty.do_initc sT ddd��fdd� � dddd�� �fdd� }ddd�� �fd d � }t � ||��_d S ) ztCreate the Python descriptor that will serve as the access point on instances of the mapped class. r )�instancerP c s� t �� �}t �� �}�j|vrx� fdd��jD �}�j|vrx|jd usPt�|�sx�j|� |�j< |jj � |�j �jg� |� �jd �S )Nc s g | ]}t � |��qS rU )rt ��.0rd �r� rU rV � <listcomp> s zFCompositeProperty._create_descriptor.<locals>.fget.<locals>.<listcomp>) r � instance_dict�instance_staterd �_attribute_keysr � issupersetr� �manager�dispatch�refresh�_COMPOSITE_FGET�get)r� rN rM �valuesr_ r� rV ru s � �� �z2CompositeProperty._create_descriptor.<locals>.fgetrY )r� rm rP c s� t �| �}t �| �}|j�j }|jjr2� | �}n|��jtj �}|jj D ]}|||||j �}qJ||�j< |d u r��j D ]}t | |d � qxn(t�j ��|��D ]\}}t | ||� q�d S rQ )r r� r� r� rd r� �_active_historyr� r �NO_VALUE�setr{ r� rn �zipr� )r� rm rN rM �attr�previous�fnrd �ru rT rU rV rp 1 s" � z2CompositeProperty._create_descriptor.<locals>.fsetc s� t �| �}t �| �}|j�j }|jjr@� | �}|��jd � n|��jtj �}|j�j }|j� |||j � �j D ]}t | |d � qtd S rQ )r r� r� r� rd r� r� �popr r� �remover{ r� rn )r� rM rN r� r� rd r� rU rV rs H s z2CompositeProperty._create_descriptor.<locals>.fdelN)ri rJ )rT rp rs rU r� rV r� s z$CompositeProperty._create_descriptor�sqlalchemy.orm.propertiesr1 r, z Type[Any]rb zOptional[Type[Mapped[Any]]]z Optional[_AnnotationScanType]) � decl_scan�registry�cls�originating_modulerd �mapped_container� annotation�extracted_mapped_annotation�is_dataclass_fieldrP c C s t jjj} | jd u r(|d u r(| �||� |} t| �r@t| �d } | r�| jd u r�t| t �sdt | dd�r�|d u r�t | d�r|| j nt | �} t �d| � d| � d���t|| |dd�} | | _t| j�r�| �||||� n0| jD ](} t| | tjf�r�| jd u r�t �d ��q�| �� d S ) Nr T)Z check_generic�__forward_arg__zCan't use forward ref z9 for composite class argument; set up the type as Mapped[�])Zinclude_genericzIComposite class column arguments must be named unless a dataclass is used)r � preloaded�orm_propertiesr5 r� Z_raise_for_requiredr* r( r� rb r) �hasattrr� r� � ArgumentErrorr r �_setup_for_dataclassr� r" r> ro r� )rT r� r� r� r� rd r� r� r� r� r5 �argumentZstr_argr� rU rU rV �declarative_scanZ sL �� ������ ���z"CompositeProperty.declarative_scanc s� t | j�r`t| jd�s`t�| j�}tjdd� |j�� D �� � t |j�dkrZ� fdd�| _ n� | _ | jd ur�t | jt �r�| jt vr�| j d ur�| j t | j< nt| jd�r�dd� t | j< d S )Nr� c S s g | ] }|j �qS rU )ro )r� �prU rU rV r� � rx z4CompositeProperty._init_accessor.<locals>.<listcomp>r c s � | �fS rQ rU rr ��getterrU rV rw � rx z2CompositeProperty._init_accessor.<locals>.<lambda>c S s | � � S rQ �r� rr rU rU rV rw � rx )r r� r� �inspect� signature�operator� attrgetter� parametersr� �lenr� r� �typer� )rT �insprU r� rV r� � s, � �� �� � �z CompositeProperty._init_accessorzsqlalchemy.orm.decl_base)r� r� r� rd rP c C s� t jjj}t jj}t�| j�}t� |j � � | j �D ]�\}} |d u rnt �dt| j �� d| jj� dt|j �� ���| d u r�|� } | j | f7 _ t| |�r�| �|||||j|j� q2t| tj�r2|�|j| � q2d S )Nz number of composite attributes z3 exceeds that of the number of attributes in class � )r r� r� r5 Z orm_decl_baser� r� r� � itertools� zip_longestr� r� r� r� r� r� rf r� Z declarative_scan_for_compositero r� r" r> Z_undefer_column_name) rT r� r� r� rd r5 � decl_baser� �paramr� rU rU rV r� � s< � ���� � z&CompositeProperty._setup_for_dataclass�!Sequence[QueryableAttribute[Any]]c s � fdd�� j D �S )Nc s g | ]}t � jj|j��qS rU )rt rz ry rd �r� ra r_ rU rV r� � rx z:CompositeProperty._comparable_elements.<locals>.<listcomp>��propsr_ rU r_ rV �_comparable_elements� s z&CompositeProperty._comparable_elementszorm.propertiesz Sequence[MapperProperty[Any]]c C s� g }t jjj}| jD ]�}t|t�r4| jj|dd�}nLt|t j �rN| jj | }n2t||�rh| jj |j }nt|t j�r||j}nd }t|t�s�t�d|����|�|� q|S )NF)Z_configure_mapperszYComposite expects Column objects or mapped attributes/attribute names as arguments, got: )r r� r� r5 r� r� rb rz Z get_propertyr" r> �_columntoproperty�columnr r. ri r r� r� �append)rT r� r5 r� ra rU rU rV r� � s( �� zCompositeProperty.propszSequence[Column[Any]]c s t jjj� � fdd�| jD �S )Nc s0 g | ](}t |tj� f�rt |� �r(|jn|�qS rU )r� r" r> r� )r� �ar4 rU rV r� � s �z-CompositeProperty.columns.<locals>.<listcomp>)r r� r� r5 r� r_ rU r4 rV �columns� s �zCompositeProperty.columnsz Optional[MapperProperty[_CC]]c C s | S rQ rU r_ rU rU rV �mapper_property_to_assign s z+CompositeProperty.mapper_property_to_assignz$List[Tuple[schema.Column[Any], int]]c C s dd� | j D �S )Nc S s g | ]}|j d u r|df�qS )Nr )�table)r� �crU rU rV r� rx z7CompositeProperty.columns_to_assign.<locals>.<listcomp>)r� r_ rU rU rV �columns_to_assign s z#CompositeProperty.columns_to_assignc C sP t jjj}| jD ]:}t||�s"qn|}| j|_| jrB| j|_d|_| j |_ qdS )zwPropagate configuration arguments made on this composite to the target columns, for those that apply. ))r� T)Z instrumentTN) r r� r� r3 r� r� r� r� Z strategy_keyr� )rT r3 ra ZcproprU rU rV r� s z-CompositeProperty._setup_arguments_on_columnsc s dddd�� fdd� }ddddd�� �fd d � }dddd dd ��fd d� � dddd��fdd� }ddddd��fdd� }t j�jd|dd� t j�jd|dd� t j�jd|ddd � t j�jd |ddd � t j�jd |ddd � �jj�j }|j|j_�j|jj_d S ) z>Establish events that populate/expire the composite attribute.rK r0 rY )rM �contextrP c s � | |d dd� d S )NF�� is_refreshrU )rM r� )�_load_refresh_handlerrU rV � load_handler s z=CompositeProperty._setup_event_handlers.<locals>.load_handlerzOptional[Sequence[str]])rM r� �to_loadrP c s. |r�j h��j��|�r*� | ||dd� d S )NTr� )rd �unionr� � intersection)rM r� r� �r� rT rU rV �refresh_handler% s ��z@CompositeProperty._setup_event_handlers.<locals>.refresh_handlerr\ )rM r� r� r� rP c s` � j }|r|�ju r"�j|v r"d S �jD ]}||vr( d S q(�j� fdd��jD �� |�j< d S )Nc s g | ]}� j | �qS rU )�dictr� �rM rU rV r� O rx zZCompositeProperty._setup_event_handlers.<locals>._load_refresh_handler.<locals>.<listcomp>)r� r� rd r� r� )rM r� r� r� rN �kr_ r� rV r� 1 s ��� �zFCompositeProperty._setup_event_handlers.<locals>._load_refresh_handler)rM �keysrP c s, |d u st � j��|�r(| j�� jd � d S rQ )r� r� r� r� r� rd )rM r� r_ rU rV �expire_handlerR s z?CompositeProperty._setup_event_handlers.<locals>.expire_handlerrX r7 )r[ � connectionrM rP c s |j �� jd� dS )z�After an insert or update, some columns may be expired due to server side defaults, or re-populated due to client side defaults. Pop out the composite value here so that it recreates. N)r� r� rd )r[ r rM r_ rU rV �insert_update_handlerX s zFCompositeProperty._setup_event_handlers.<locals>.insert_update_handlerZ after_insertT)�rawZ after_update�load)r � propagater� ZexpireN) r �listenrz r| rd r� r{ r� r� )rT r� r� r� r r~ rU r� rV r� s. ! � � � � � z'CompositeProperty._setup_event_handlers� Sequence[str]c C s dd� | j D �S )Nc S s g | ] }|j �qS rU rc r� rU rU rV r� ~ rx z5CompositeProperty._attribute_keys.<locals>.<listcomp>r� r_ rU rU rV r� | s z!CompositeProperty._attribute_keysz Callable[[Dict[str, Any]], None]c sJ �j r�j �nddd�dd��dd� �jD �� dd d �� ��fd d � }|S ) Nr z Tuple[Any])�valrP c S s | � � S rQ r� )r rU rU rV � get_values� s zOCompositeProperty._populate_composite_bulk_save_mappings_fn.<locals>.get_valuesc S s g | ] }|j �qS rU rc r� rU rU rV r� � rx zOCompositeProperty._populate_composite_bulk_save_mappings_fn.<locals>.<listcomp>zDict[str, Any]rY )� dest_dictrP c s* | � dd� t� �| ��j���D �� d S )Nc S s i | ]\}}||�qS rU rU )r� rd r rU rU rV � <dictcomp>� s �zaCompositeProperty._populate_composite_bulk_save_mappings_fn.<locals>.populate.<locals>.<dictcomp>)r� r� r� rd )r �r� r rT rU rV �populate� s ���zMCompositeProperty._populate_composite_bulk_save_mappings_fn.<locals>.populate)r� r� )rT r rU r rV �)_populate_composite_bulk_save_mappings_fn� s z;CompositeProperty._populate_composite_bulk_save_mappings_fnrK r+ r r- rL c C s� g }g }d}| j D ]j}|j}|j| j�||�} | �� r<d}| �� } | rT|�| � n |�d� | j rr|�| j � q|�d� q|r�t � | j |� gd| j |� g�S t � d| j |� gd�S dS )z>Provided for userland code that uses attributes.get_history().FTNrU ) r� rd r� r{ rW Z has_changes� non_deleted�extendr� �deletedr r- r� ) rT rM rN rO �addedr Z has_historyra rd �histr rU rU rV rW � s, �z CompositeProperty.get_historyzComposite.Comparator[_CC]c C s | � | |�S rQ )r� r� rU rU rV rv � s z%CompositeProperty._comparator_factoryc s8 e Zd Zddd�� fdd� Zdddd d �d d �Z� ZS ) z!CompositeProperty.CompositeBundlez Composite[_T]r; )� property_�exprc s || _ t� j|jg|�R � d S rQ )ri r� re rd )rT r r r� rU rV re � s z*CompositeProperty.CompositeBundle.__init__z Select[Any]z#Sequence[Callable[[Row[Any]], Any]]r zCallable[[Row[Any]], Any])�query�procs�labelsrP c s ddd�� �fdd� }|S )NzRow[Any]r )�rowrP c s �j j� fdd��D �� S )Nc s g | ] }|� ��qS rU rU )r� �proc�r rU rV r� � rx zXCompositeProperty.CompositeBundle.create_row_processor.<locals>.proc.<locals>.<listcomp>)ri r� r �r rT r rV r � s �zDCompositeProperty.CompositeBundle.create_row_processor.<locals>.procrU )rT r r r r rU r rV �create_row_processor� s z6CompositeProperty.CompositeBundle.create_row_processor)rf rg rh re r � __classcell__rU rU r� rV �CompositeBundle� s r c @ s� e Zd ZU dZdZded< ejdd�dd��Zd d�d d �Z ejd d�d d ��Z ddd�dd�Z ejdd�dd��Z ddd�dd�Z ddd�dd�Zddd�d d �Zddd�d d �Zddd�d d!�Zddd�d"d#�Zd$ddd%�d&d'�ZdS )(z CompositeProperty.Comparatora� Produce boolean, comparison, and other operators for :class:`.Composite` attributes. See the example in :ref:`composite_operations` for an overview of usage , as well as the documentation for :class:`.PropComparator`. .. seealso:: :class:`.PropComparator` :class:`.ColumnOperators` :ref:`types_operators` :attr:`.TypeEngine.comparator_factory` Nz%RODescriptorReference[Composite[_PT]]ra r; r] c C s t j| jddi�S )Nr� F)r% r; r� r_ rU rU rV �clauses� s ��z$CompositeProperty.Comparator.clausesz&CompositeProperty.CompositeBundle[_PT]c C s | j S rQ r$ r_ rU rU rV �__clause_element__� s z/CompositeProperty.Comparator.__clause_element__c C s* | j �| j| j| jjd��}t�| j|�S )N)Z parententityZ parentmapper� proxy_key)r Z _annotateZ _parententityra rd r� r )rT r rU rU rV r% � s ��z'CompositeProperty.Comparator.expressionr z(Sequence[Tuple[_DMLColumnArgument, Any]]r� c C sz t |t�r|j}|d u r,dd� | jjD �}n>t | jjt�rVt || jj�rV| j�|�}nt� d| j|f ��t t | j |��S )Nc S s g | ]}d �qS rQ rU r� rU rU rV r� rx zDCompositeProperty.Comparator._bulk_update_tuples.<locals>.<listcomp>z)Can't UPDATE composite attribute %s to %r) r� r' rm ra r� r� r� r� r� r� �listr� r� )rT rm r� rU rU rV �_bulk_update_tuples s ����z0CompositeProperty.Comparator._bulk_update_tuplesr� c s( � j r � fdd�� jjD �S � jjS d S )Nc s g | ]}t � jj|j��qS rU )rt �_adapt_to_entity�entityrd r� r_ rU rV r� s �zECompositeProperty.Comparator._comparable_elements.<locals>.<listcomp>)r$ ra r� r_ rU r_ rV r� s �z1CompositeProperty.Comparator._comparable_elementszColumnElement[bool])�otherrP c C s | � tj|�S rQ )�_comparer& �eq�rT r& rU rU rV �__eq__& s z#CompositeProperty.Comparator.__eq__c C s | � tj|�S rQ )r' r& �ner) rU rU rV �__ne__) s z#CompositeProperty.Comparator.__ne__c C s | � tj|�S rQ )r' r& �ltr) rU rU rV �__lt__, s z#CompositeProperty.Comparator.__lt__c C s | � tj|�S rQ )r' r& �gtr) rU rU rV �__gt__/ s z#CompositeProperty.Comparator.__gt__c C s | � tj|�S rQ )r' r& �ler) rU rU rV �__le__2 s z#CompositeProperty.Comparator.__le__c C s | � tj|�S rQ )r' r& �ger) rU rU rV �__ge__5 s z#CompositeProperty.Comparator.__ge__r= )r� r& rP c st |d u r d gt �jj� }n �j�|�}� fdd�t�jj|�D �}�jrj�jd usXJ ��fdd�|D �}tj|� S )Nc s g | ]\}}� ||��qS rU rU )r� r� �b)r� rU rV r� G s �z9CompositeProperty.Comparator._compare.<locals>.<listcomp>c s g | ]}� � |��qS rU )�adapter)r� �xr_ rU rV r� M rx ) r� ra r� r� r� r$ r6 r# �and_)rT r� r& r� Z comparisonsrU )r� rT rV r' ? s �z%CompositeProperty.Comparator._compare)rf rg rh r� �__hash__r� r �memoized_propertyr r r% r# r� r* r, r. r0 r2 r4 r' rU rU rU rV r� � s$ r� c C s t | jjj�d | j S )N�.)rb rz ry rf rd r_ rU rU rV �__str__P s zCompositeProperty.__str__)N)*rf rg rh r� r� re r r� r� �objectr� r� r �preload_moduler� r� r� r: r� r� Znon_memoized_propertyr� ri r� r� r� r� r� r r rj rW rv �orm_utilZBundlerD r r rF r� r< r rU rU r� rV r� � sb ��&(J"9'_ �%xr� c @ s e Zd ZdZdZdS )� CompositeaS Declarative-compatible front-end for the :class:`.CompositeProperty` class. Public constructor is the :func:`_orm.composite` function. .. versionchanged:: 2.0 Added :class:`_orm.Composite` as a Declarative compatible subclass of :class:`_orm.CompositeProperty`. .. seealso:: :ref:`mapper_composite` TN�rf rg rh r� Z inherit_cacherU rU rU rV r@ T s r@ c s6 e Zd ZdZddd�dd�Zdd�� fd d � Z� ZS ) �ConcreteInheritedPropertya4 A 'do nothing' :class:`.MapperProperty` that disables an attribute on a concrete subclass that is only present on the inherited mapper, not the concrete classes' mapper. Cases where this occurs include: * When the superclass mapper is mapped against a "polymorphic union", which includes all attributes from all subclasses. * When a relationship() is configured on an inherited mapper, but not on the subclass mapper. Concrete mappers require that relationship() is configured explicitly on each subclass. rX zType[PropComparator[_T]]rZ c C sP d }| j �� D ]*}|j| j }t|dd �d ur|j} q:q|d usFJ �|||�S )Nr� )rz Ziterate_to_rootZ_propsrd rt r� )rT r[ Zcomparator_callable�mr� rU rU rV rv x s z-ConcreteInheritedProperty._comparator_factoryrY r] c s< t � �� dd�� fdd� �G � �fdd�d�}|� � _d S )Nr r] c s t d� j� j� jf ��d S )NzgConcrete %s does not implement attribute %r at the instance level. Add this property explicitly to %s.)r� rz rd rU r_ rU rV �warn� s ��z0ConcreteInheritedProperty.__init__.<locals>.warnc sT e Zd Zddddd��fdd� Zdddd��fdd� Zddddd �� �fd d � Zd S ) zDConcreteInheritedProperty.__init__.<locals>.NoninheritedConcretePropr r )�srl rm rP c s � � d S rQ rU )rE rl rm �rD rU rV �__set__� s zLConcreteInheritedProperty.__init__.<locals>.NoninheritedConcreteProp.__set__)rE rl rP c s � � d S rQ rU )rE rl rF rU rV � __delete__� s zOConcreteInheritedProperty.__init__.<locals>.NoninheritedConcreteProp.__delete__)rE rl �ownerrP c s |d u r� j S �� d S rQ )rJ )rE rl rI �rT rD rU rV �__get__� s zLConcreteInheritedProperty.__init__.<locals>.NoninheritedConcreteProp.__get__N)rf rg rh rG rH rK rU rJ rU rV �NoninheritedConcreteProp� s rL )r� re rJ )rT rL r� rJ rV re � s z"ConcreteInheritedProperty.__init__)rf rg rh r� rv re r rU rU r� rV rB g s rB c s� e Zd ZU dZded< d&dddddd d d �� fd d � ZesLedd�dd��Ze j dd�dd��Z ddd�dd�Z e jfddd d d �d d �Ze �d!�ddd"d#�d$d%��Z� ZS )'�SynonymPropertya8 Denote an attribute name as a synonym to a mapped property, in that the attribute will mirror the value and expression behavior of another attribute. :class:`.Synonym` is constructed using the :func:`_orm.synonym` function. .. seealso:: :ref:`synonyms` - Overview of synonyms z"Optional[Type[PropComparator[_T]]]r� Nrb zOptional[bool]z Optional[Any]r� r� rH )ro � map_columnrJ r� r� r� rI c sj t � j|d� || _|| _|| _|| _|r2|| _n|rF|jrF|j| _nd | _|r\| j� |� t � | � d S r� ) r� re ro rN rJ r� rI r� r� r� r r� )rT ro rN rJ r� r� r� rI r� rU rV re � s zSynonymProperty.__init__r\ r] c C s t | jj| j�jjS rQ )rt rz ry ro r{ r^ r_ rU rU rV r^ � s z SynonymProperty.uses_objectsz/Union[MapperProperty[_T], SQLORMOperations[_T]]c C sh t | jj| j�}t|d�r&t|jt�sbt|tj �r8|j S t|t �rF|S t � d| jjj| j|f ��|jS )Nri zGsynonym() attribute "%s.%s" only supports ORM mapped attributes, got %r)rt rz ry ro r� r� ri r r r/ Z comparatorr r� r� rf )rT r� rU rU rV �_proxied_object� s � ��z SynonymProperty._proxied_objectrX zSQLORMOperations[_T]rZ c C s< | j }t|t�r4| jr$| �||�}n |�||�}|S |S d S rQ )rO r� r r� )rT r[ ra �comprU rU rV rv � s z#SynonymProperty._comparator_factoryrK r+ r r- rL c C s" t | jj| j�}|jj|||d�S )N)rO )rt rz ry ro r{ rW )rT rM rN rO r� rU rU rV rW � s zSynonymProperty.get_historyr� rY )rz �initrP c C s� t jj}| jr�| j|jjvr:t�d| j |jj | jf ��nN|jj| j |j v r�|j |jj| j j| j kr�t�d| j| j | j | jf ��|� |jj| j �}|j | j ||dd� | j|_|| _d S )Nz>Can't compile synonym '%s': no column on table '%s' named '%s'zpCan't call map_column=True for synonym %r=%r, a ColumnProperty already exists keyed to the name %r for column %rT)rQ Z setparent)r r� r� rN rd Zpersist_selectabler� r� r� ro � descriptionr� r3 Z_configure_propertyZ_mapped_by_synonymrz )rT rz rQ � propertiesr� rU rU rV � set_parent� s@ ��� �� ����� �zSynonymProperty.set_parent)NNNNNN)rf rg rh r� r� re r ri r^ r r: rO rv r rj rW r> rT r rU rU r� rV rM � s& � � rM c @ s e Zd ZdZdZdS )�SynonymaK Declarative front-end for the :class:`.SynonymProperty` class. Public constructor is the :func:`_orm.synonym` function. .. versionchanged:: 2.0 Added :class:`_orm.Synonym` as a Declarative compatible subclass for :class:`_orm.SynonymProperty` .. seealso:: :ref:`synonyms` - Overview of synonyms TNrA rU rU rU rV rU & s rU )gr� � __future__r Z dataclassesr r� r� r� �typingr r r r r r r r r r r r �weakref� r r r? �baser r r r r Z interfacesr r r r r r r r r! r� r" r# r% r& Z sql.elementsr' Z util.typingr( r) r* Z_typingr+ r, r- r. r/ r� r0 r� r1 r[ r2 rS r3 r5 rM r6 Z engine.baser7 Z engine.rowr8 Z sql._typingr9 r: r; r< Z sql.operatorsr= Z sql.schemar> Zsql.selectabler? r@ rA rB rC rD rF rG rb Z_CompositeAttrTyper� �WeakKeyDictionaryr� r� r� r@ rB rM rU rU rU rU rV �<module> s� H�� � � %8 sqlalchemy/orm/__pycache__/bulk_persistence.cpython-39.pyc 0000644 00000121170 15125143220 0017702 0 ustar 00 a ��Jh� � @ s� d Z ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z dd lm Z dd lm Z dd lm Z d d l mZ d dl mZ d dl mZ d dl mZ d dl mZ d dl mZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ ddl mZ ddl m Z ddl m Z ddl m Z dd l!m"Z" dd l!m#Z# dd l!m$Z$ dd l!m%Z% dd l!m&Z& dd!l!m'Z' dd"l(m)Z) dd#l(m*Z* dd$l(m+Z+ dd%l,m-Z- dd&l,m.Z. dd'l,m/Z/ dd(l m0Z0 dd)l1m2Z2 e �rnd d*l3m4Z4 d d+l3m5Z5 d d,l3m6Z6 d d-l7m8Z8 d d.l9m:Z: d d/l9m;Z; d d0l9m<Z< d d1l9m=Z= d d2l>m?Z? dd3l m@Z@ dd4l mAZA dd5lBmCZC e d6eDd7�ZEe d8d8d9�d:d;d<d=d=d=d>d?d@dA� dBdC��ZFe d8d8d9�d:d;d<d=d=d=dDd?dEdA� dFdC��ZFdGdGd9�d:d;d<d=d=d=dDd?dHdA� dIdC�ZFe d8dJdK�dLd;d<d=d=d>d=d@dM�dNdO��ZGe d8dJdK�dLd;d<d=d=dPd=dQdM�dRdO��ZGdGdJdK�dLd;d<d=d=dPd=dSdM�dTdO�ZGdUdV� ZHG dWdX� dXe�ZIG dYdZ� dZeI�ZJe*�Kd[d\�G d]d^� d^eIe.��ZLe*�Kd[d_�G d`da� daeJe/��ZMe*�Kd[db�G dcdd� ddeJe-��ZNdGS )ezoadditional ORM persistence classes related to "bulk" operations, specifically outside of the flush() process. � )� annotations)�Any)�cast)�Dict)�Iterable)�Optional)�overload)� TYPE_CHECKING)�TypeVar)�Union� )� attributes)�context)� evaluator)�exc)�loading)� persistence)�NO_VALUE)�AbstractORMCompileState)� FromStatement)� ORMFromStatementCompileState)� QueryContext� )�util)�Dialect)�result)� coercions)�dml)� expression)�roles)�select)�sqltypes)�_entity_namespace_key)� CompileState)�Options)�DeleteDMLState)�InsertDMLState)�UpdateDMLState)� EMPTY_DICT)�Literal)�DMLStrategyArgument)�OrmExecuteOptionsParameter)�SynchronizeSessionArgument)�Mapper)�_BindArguments)�ORMExecuteState)�Session)�SessionTransaction)� InstanceState)� Connection)�cursor)�_CoreAnyExecuteParams�_O)�bound.)�use_orm_insert_stmt�execution_optionsz Mapper[_O]z<Union[Iterable[InstanceState[_O]], Iterable[Dict[str, Any]]]r1 �boolz Literal[None]z$Optional[OrmExecuteOptionsParameter]�None) �mapper�mappings�session_transaction�isstates�return_defaults� render_nullsr8 r9 �returnc C s d S �N� �r< r= r> r? r@ rA r8 r9 rD rD �T/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/bulk_persistence.py� _bulk_insertJ s rG zOptional[dml.Insert]zcursor.CursorResult[Any]c C s d S rC rD rE rD rD rF rG X s Nz"Optional[cursor.CursorResult[Any]]c s �j }|jjrtd��|rbtr0tttt ���|rRdd� �D �} dd� | D ��q�dd� �D ��n@tr|ttt t t f ���|r�t ���ndd� �D ��t ��� |�|�� d } �fdd�|j�� D �} |r�d} nt| �d kr�d} nd } | D ]�\} }|d u�r�fd d�|�� D �nd }� �fd d�tj| � �fdd��D �d| ||d�D �}tj|d || || ||d�}|d ur�|j�r�| d u �r�|} q�|jr�| �s�J �| �|�} q�|�r�|�r�j}dd� �jD �}| D ](\}�|t�fdd�|D ��d f|_ �q�|d u�r| d u�s J �| S d S )NzJconnection_callable / per-instance sharding not supported in bulk_insert()c S s g | ]}||j f�qS rD ��dict��.0�staterD rD rF � <listcomp> � z _bulk_insert.<locals>.<listcomp>c S s g | ] \}}|�qS rD rD )rK rL �dict_rD rD rF rM � rN c S s g | ] }|j �qS rD rH rJ rD rD rF rM � rN c S s g | ] }t |��qS rD rH �rK �mrD rD rF rM � rN c s" g | ]\}}|� j v r||f�qS rD )� _pks_by_table)rK �table�mp�r< rD rF rM � s �Tr Fc s g | ]}|j � d v r|j �qS �r ��key�rK �b�r= rD rF rM � s �rD c 3 s2 | ]*\}}}}}}}}d ||�� |||fV qd S rC rD ) rK rL Z state_dict�paramsrT �connZ value_paramsZ has_all_pksZhas_all_defaults�� connectionr< rD rF � <genexpr>� s$ ��z _bulk_insert.<locals>.<genexpr>c 3 s | ]}d |�� fV qd S rC rD �rK �mappingr^ rD rF r` � rN )�bulkr@ rA �include_bulk_keys)� bookkeepingr8 r9 c S s g | ] }|j �qS rD rW )rK �prD rD rF rM � rN c s g | ] }� | �qS rD rD �rK rX )rO rD rF rM � rN ) � base_mapper�session�connection_callable�NotImplementedErrorr r r r2 r6 r �strr �list�_expand_compositesr_ �_sorted_tables�items�len�_get_embedded_bindparamsr Z_collect_insert_commandsZ_emit_insert_statements� _returningZ returns_rowsZsplice_horizontallyZ_identity_class�_identity_key_props�tuplerX )r< r= r> r? r@ rA r8 r9 rh �statesZ return_resultZmappers_to_runre rS � super_mapper�extra_bp_names�recordsr Z identity_clsZidentity_propsrL rD )r_ rO r< r= rF rG f s� � � ��� �� � � T)�use_orm_update_stmt�enable_check_rowcount� Mapper[Any])r< r= r> r? �update_changed_onlyrz r{ rB c C s d S rC rD �r< r= r> r? r} rz r{ rD rD rF � _bulk_update� s r zOptional[dml.Update]z_result.Result[Any]c C s d S rC rD r~ rD rD rF r s z Optional[_result.Result[Any]]c s0 �j }�j��jr"�jjh�����fdd�� |r\|rL� �fdd��D ��qtdd� �D ��ndd� �D ��t��� |jjr�td��|� |��|d ur��fdd�|� � D �nd }|j � � D ]^\} } �� | �r�| �jvr�q�tjd | ��fd d ��D �d ||d �} tj|d | | | d||d� q�|d u�r,t�� S d S )Nc s �� fdd�� j �� D �S )Nc s( i | ] \}}|�j v s |� v r||�qS rD )Zcommitted_state�rK �k�v)� search_keysrL rD rF � <dictcomp>) s �z7_bulk_update.<locals>._changed_dict.<locals>.<dictcomp>)rI rp )r< rL )r� )rL rF � _changed_dict( s �z#_bulk_update.<locals>._changed_dictc s g | ]}� �|��qS rD rD rJ )r� r< rD rF rM 1 rN z _bulk_update.<locals>.<listcomp>c S s g | ] }|j �qS rD rH rJ rD rD rF rM 3 rN c S s g | ] }t |��qS rD rH rP rD rD rF rM 5 rN zJconnection_callable / per-instance sharding not supported in bulk_update()c s g | ]}|j � d v r|j �qS rV rW rY r[ rD rF rM C s �rD c 3 s. | ]&}d |�� �j r |�j j nd fV qd S rC )�_version_id_proprX ra r^ rD rF r` S s ���z _bulk_update.<locals>.<genexpr>T)rc rz rd F)re rz r{ )rh Z_primary_key_propkeysr� rX �unionrn ri rj rk r_ rr ro rp �isarR r Z_collect_update_commandsZ_emit_update_statements�_result� null_result) r< r= r> r? r} rz r{ rh rx rS rw ry rD )r� r_ r< r= r� rF r s^ � � �� ��� c sV | j � � sd S t� �� �}� fdd�|D �}|D ] }|�|�D ]}|| |� q>q0d S )Nc s i | ]}|� | � � �qS rD )Z)_populate_composite_bulk_save_mappings_fnrg �Zcomposite_attrsrD rF r� z s �z&_expand_composites.<locals>.<dictcomp>)Z composites�set�keys� intersection)r< r= Zcomposite_keysZ populatorsrb rX rD r� rF rn t s �rn c @ st e Zd ZU dZdZded< edd� �Zedd� �Zed d � �Z ed d � �Z ed d� �Z dd�dd�Z edd� �Z dS )� ORMDMLStateTNz&Optional[ORMFromStatementCompileState]�from_statement_ctxc c s� t j}|D ]�\}}t�tj|�}t|t�r�t||t d�}|t u rrt�tj|�|rhtjtj |t � � dd�n|fV q�|||� |�|�E d H q d|jv r�|j} t| d | d �} ||| � |�|�E d H q ||s�|ntjtj |t � � dd�fV q d S )N)�defaultT)�type_Zis_crudZentity_namespace� proxy_key)r' �_get_crud_kv_pairsr �expectr Z DMLColumnRole� isinstancerl r" r �ExpressionElementRoler! ZNullTypeZ_bulk_update_tuples� _annotations) �clsr< � statement� kv_iterator�needs_to_be_cacheableZcore_get_crud_kv_pairsr� r� �descZk_anno�attrrD rD rF �_get_orm_crud_kv_pairs� sR ���� �� ���z"ORMDMLState._get_orm_crud_kv_pairsc s6 �j d ��r�js t��|�S � ��fdd�|D �S )N�plugin_subjectc s& g | ] }t � ��j�|�� d ���qS )F)rI r� r< rp )rK Z value_dict�r� r� r� rD rF rM � s ���z8ORMDMLState._get_multi_crud_kv_pairs.<locals>.<listcomp>)�_propagate_attrsr< r' �_get_multi_crud_kv_pairs)r� r� r� rD r� rF r� � s ��z$ORMDMLState._get_multi_crud_kv_pairsc C sD |s J d��|j d }|r |js.t�|||�S t| �|j|||��S )Nz0no test coverage for needs_to_be_cacheable=Falser� )r� r< r' r� rm r� )r� r� r� r� r� rD rD rF r� � s" �� ���z ORMDMLState._get_crud_kv_pairsc C s@ |j jd }|j}|jr |j}n|jj}||j|j|j|jd�S )N� parententity)�name�type�expr�entityrS ) rS r� r< �is_aliased_classr� �class_�__name__r� � local_table)r� r� �ext_infor< Z _label_namerD rD rF �get_entity_description� s �z"ORMDMLState.get_entity_descriptionc s2 dd� �dd� � � fdd��fdd�|j D �D �S )Nc S s | j �dd �S )Nr� )r� �get)�crD rD rF � _ent_for_col� s zCORMDMLState.get_returning_column_descriptions.<locals>._ent_for_colc S s4 |d u r | S | j �dd �}|s"| S t|j|| �S d S )Nr� )r� r� �getattrr� )r� �entr� rD rD rF � _attr_for_col� s zDORMDMLState.get_returning_column_descriptions.<locals>._attr_for_colc s. g | ]&\}}|j |j� ||�|j|jd ��qS ))r� r� r� �aliasedr� )rX r� r� r� )rK r� r� )r� rD rF rM s ��zAORMDMLState.get_returning_column_descriptions.<locals>.<listcomp>c s g | ]}|� |�f�qS rD rD �rK r� )r� rD rF rM s )Z_all_selected_columns)r� r� rD )r� r� rF �!get_returning_column_descriptions� s ��z-ORMDMLState.get_returning_column_descriptions)�use_supplemental_colsc C s� |j r�t|j |dd�}|jf i |j��}|j|j� }|| _t�||� | _ }|� |� |� � }d|_ dd� |j D �}|s�|� |j� |r�|j|jd|i�}n |j|� }|S )al establish ORM column handlers for an INSERT, UPDATE, or DELETE which uses explicit returning(). called within compilation level create_for_statement. The _return_orm_returning() method then receives the Result after the statement was executed, and applies ORM loading to the state that we first established here. F)Z_adapt_on_namesrD c S s g | ]}|d ur|�qS rC rD r� rD rD rF rM 8 rN z4ORMDMLState._setup_orm_returning.<locals>.<listcomp>Zsupplemental_cols)rs r r9 �_execution_options�options� _with_options�select_statementr �create_for_statementr� Z!setup_dml_returning_compile_stateZ _generateZprimary_columns�extend� primary_keyr@ Z returning) �self�compiler�orm_level_statementZdml_level_statement� dml_mapperr� �fsZfscZcols_to_returnrD rD rF �_setup_orm_returning s6 � � � ��z ORMDMLState._setup_orm_returningc C sZ |j }|jj}|jrR|jjjsR|�dtj�} t|j|j |||| ||�} t � || �S |S d S )N�_sa_orm_load_options) r Zcompiled� compile_stater� �compile_options�_is_starr� r �default_load_optionsr� r Z instances) r� ri r� r\ r9 �bind_argumentsr Zexecution_contextr� � load_optionsZ querycontextrD rD rF �_return_orm_returningV s* ���� z!ORMDMLState._return_orm_returning)r� � __module__� __qualname__Zis_dml_returningr� �__annotations__� classmethodr� r� r� r� r� r� r� rD rD rD rF r� � s 7 !� Cr� c @ s� e Zd ZG dd� de�Zeddddd�dddddddd�d d ��Zed d � �Zed d� �Zedd� �Z edd� �Z edd� �Z edd� �Z edd� �Z edd� �Zedd � �Zed d � �Zed d � �Zd!S )"�BulkUDCompileStatec @ s~ e Zd ZU dZded< dZded< dZded< dZded < dZded < d Z ded < d Z ded< e Z d Z d Zd ZdZded< d S )z)BulkUDCompileState.default_update_options�autor* � _dml_strategyr, �_synchronize_sessionFr: �_can_use_returning�_is_delete_using�_is_update_fromT� _autoflushN�Optional[Mapper[Any]]�_subject_mapper�_populate_existing)r� r� r� r� r� r� r� r� r� r� r� r( �_resolved_values�_eval_condition� _matched_rows�_identity_tokenr� rD rD rD rF �default_update_options{ s r� F�� is_multitable�is_update_from�is_delete_using�is_executemanyr r| r: ��dialectr< r� r� r� r� rB c C s t � �d S rC )rk )r� r� r< r� r� r� r� rD rD rF �can_use_returning� s z$BulkUDCompileState.can_use_returningc C s� t j�dh d�||j�\}}||d< z|jd }W n tyP dsLJ d��Y n 0 |rn|j|d< |d|ji7 }d |jjvr�|d d i7 }nNt |t �s�|j d kr�|d d i7 }q�|j dkr�t � d��n|j d kr�|d di7 }|j} | d u�r| dvr�t �d��|j dk�r| dk�rt � d��|�s�|j�r.|�� |j d k�r�|jd k�r\| �||||||�}nB|jdk�r~| �||||||�}n |jdk�r�| �||||||�}n$|j dk�r�|jd k�r�|ddi7 }|�|j|j|j|j |jd��}|t�|��d|i�fS )N�_sa_orm_update_options> � autoflush�populate_existing�synchronize_session� dml_strategyr� �identity_tokenr� �clauser� F�0statement had 'orm' plugin but no plugin_subjectr< r� r� r� � core_onlyr� �ormrc �HCan't use "bulk" ORM insert strategy without passing separate parameters)r� �evaluate�fetchFzSValid strategies for session synchronization are 'auto', 'evaluate', 'fetch', Falser� zkThe 'fetch' synchronization strategy is not available for 'bulk' ORM updates (i.e. multiple parameter sets)r� r� )r� r� r� r� r� )r� r� �from_execution_optionsr� r� �KeyErrorr< rS r� r� rm r� �sa_exc�InvalidRequestErrorr� � ArgumentErrorr� �_do_pre_synchronize_auto� _do_pre_synchronize_evaluate�_do_pre_synchronize_fetch� _annotater� r� r� r � immutabledictr� ) r� ri r� r\ r9 r� � is_pre_event�update_optionsr� �syncrD rD rF �orm_pre_session_exec� s� �� � �� � � � �� ��z'BulkUDCompileState.orm_pre_session_execc C s� |d }|j dkrJ|jdkr.| �||||� qr|jdkrr| �||||� n(|j dkrr|jdkrn| �||||� |S | �||||||�S )Nr� r� r� r� rc )r� r� � _do_post_synchronize_evaluate�_do_post_synchronize_fetch�"_do_post_synchronize_bulk_evaluater� )r� ri r� r\ r9 r� r r rD rD rF �orm_setup_cursor_result s0 � � ��z*BulkUDCompileState.orm_setup_cursor_resultc s~ d}�j r�jnd� d�jf|v rF|t�fdd�|d�jf D ��7 }�jjdur`|�jjf7 }� rzt� fdd�|D ��}|S )a� Apply extra criteria filtering. For all distinct single-table-inheritance mappers represented in the table being updated or deleted, produce additional WHERE criteria such that only the appropriate subtypes are selected from the total results. Additionally, add WHERE criteria originating from LoaderCriteriaOptions collected from the statement. rD NZadditional_entity_criteriac 3 s( | ] }|j s|j� u r|�� �V qd S rC )Zinclude_aliasesr� Z_resolve_where_criteria)rK Zae)r� rD rF r` P s �z@BulkUDCompileState._adjust_for_extra_criteria.<locals>.<genexpr>c 3 s | ]}� � |�V qd S rC )�traverse)rK �crit)�adapterrD rF r` \ rN )r� Z_adapterr< ru Z_single_table_criterion)r� �global_attributesr� Z return_critrD )r r� rF �_adjust_for_extra_criteria; s" ���� z-BulkUDCompileState._adjust_for_extra_criteriac sX z.|j |jj ur |�|j j�� n |�|j�� W n tyD g Y S 0 � fdd�|D �S )a� return rows that indicate PK cols in mapper.primary_key position for RETURNING rows. Prior to 2.0.36, this method seemed to be written for some kind of inheritance scenario but the scenario was unused for actual joined inheritance, and the function instead seemed to perform some kind of partial translation that would remove non-PK cols if the PK cols happened to be first in the row, but not otherwise. The joined inheritance walk feature here seems to have never been used as it was always skipped by the "local_table" check. As of 2.0.36 the function strips away non-PK cols and provides the PK cols for the table in mapper PK order. c s g | ] }� |��qS rD rD �rK �row��pk_keysrD rF rM � rN z@BulkUDCompileState._interpret_returning_rows.<locals>.<listcomp>)r� rh Z _tuple_getterr� r� )r� r r< �rowsrD r rF �_interpret_returning_rows` s z,BulkUDCompileState._interpret_returning_rowsc s� |j �|j}�fdd�|D �}|j� � d ur>� fdd�|D �}g }|D ]<\}}}||�} | du sj| tju rF|�|||| tju f� qF|S )Nc s. g | ]&}|j �� �r|js|�� ||jf�qS rD )r< r� Zexpired�objrI rJ rU rD rF rM � s �zGBulkUDCompileState._get_matched_objects_on_criteria.<locals>.<listcomp>c s& g | ] \}}}|j � kr|||f�qS rD �r� )rK r rL rO r rD rF rM � s �T)r� r� r� r Z_EXPIRED_OBJECT�append) r� r rv �eval_condition�raw_datar r rL rO Zevaled_conditionrD )r� r< rF � _get_matched_objects_on_criteria� s2 � �����z3BulkUDCompileState._get_matched_objects_on_criteriac C s~ |j }|j}t�|�}d}|jr*||j7 }i }|jD ]}|jr4|�|� q4|r^|| �||�7 }|rn|j |� } n dd� } | } | S )NrD c S s dS )NTrD )r rD rD rF r� � s zJBulkUDCompileState._eval_condition_from_statement.<locals>._eval_condition) r� r� r �_EvaluatorCompiler�_where_criteriar� Z_is_criteria_optionZget_global_criteriar �process) r� r r� r< � target_cls�evaluator_compilerr r �optr r� rD rD rF � _eval_condition_from_statement� s" z1BulkUDCompileState._eval_condition_from_statementc C sT z| � ||�}W n tjy$ Y n0 ||dd� S |ddi7 }| �||||||�S )a� setup auto sync strategy "auto" checks if we can use "evaluate" first, then falls back to "fetch" evaluate is vastly more efficient for the common case where session is empty, only has a few objects, and the UPDATE statement can potentially match thousands/millions of rows. OTOH more complex criteria that fails to work with "evaluate" we would hope usually correlates with fewer net rows. r� )r� r� r� r� )r r �UnevaluatableErrorr� )r� ri r� r\ r9 r� r r rD rD rF r� � s& �� �z+BulkUDCompileState._do_pre_synchronize_autoc C sT z| � ||�}W n6 tjyF } z t�d| �|�W Y d }~n d }~0 0 |d|i S )Nz{Could not evaluate current criteria in Python: "%s". Specify 'fetch' or False for the synchronize_session execution option.r� )r r r! r� r� ) r� ri r� r\ r9 r� r r �errrD rD rF r� � s �����z/BulkUDCompileState._do_pre_synchronize_evaluatec C s6 |j r g S |jrt|j�S |jr.t|j�� �S g S d S rC )Z _multi_values�_ordered_valuesrm �_valuesrp )r� r< r� rD rD rF �_get_resolved_values s z'BulkUDCompileState._get_resolved_valuesc C sj g }|D ]\\}}|rVt |tj�rVz|j| }W n tjyB Y qd0 |�|j|f� qt� d| ��q|S )NzCAttribute name not found, can't be synchronized back to objects: %r) r� r Z ColumnElement�_columntoproperty�orm_excZUnmappedColumnErrorr rX r� r� )r� r< �resolved_values�valuesr� r� r� rD rD rF �_resolved_keys_as_propnames s ��z.BulkUDCompileState._resolved_keys_as_propnamesc sv �j �t�j�jf � ���j|j� }|j|_d � ddd�� ���fdd� }|j|||||d�} | � � } �| � d� S )Nr/ r )� orm_contextrB c sz | j jf i | j��}�j|j��j�j| jd�}� d urL� |krft� d��n| jrb|sbt� d��n|� |rrt � � S d S d S )N)r� r� r� zjFor synchronize_session='fetch', can't mix multiple backends where some support RETURNING and others don'tz�For synchronize_session='fetch', can't use multiple parameter sets in ORM mode, which this backend does not support with RETURNING) ri Zget_bindr� r� r� r� r� r� r� r� r� r� )r+ �bindZper_bind_result�r� r� r< r rD rF �skip_for_returningP s* �� �zHBulkUDCompileState._do_pre_synchronize_fetch.<locals>.skip_for_returning)r9 r� Z _add_event)r� r� ) r� r r� Zselect_identity_token� select_fromr� r� r �executeZfetchall) r� ri r� r\ r9 r� r Z select_stmtr. r � matched_rowsrD r- rF r� . s, ���!��z,BulkUDCompileState._do_pre_synchronize_fetchN)r� r� r� r$ r� r� r� r r r r r r r� r� r% r* r� rD rD rD rF r� z s: � x + $ " & / r� r� �insertc s� e Zd ZU G dd� de�ZdZded< edd� �Zedd d d d d dd�dd��Z ed d�� fdd� �Z edd� �Z dd� Z dd� Z � ZS )� BulkORMInsertc @ sV e Zd ZU dZded< dZded< dZded< dZd ed < d Zded < dZ ded < dS )z$BulkORMInsert.default_insert_optionsr� r* r� Fr: � _render_nulls�_return_defaultsNr� r� Tr� r� ) r� r� r� r� r� r4 r5 r� r� r� rD rD rD rF �default_insert_options� s r6 NzOptional[FromStatement]r� c C s t j�dh d�||j�\}}||d< z|jd }W n tyP dsLJ d��Y n 0 |rn|j|d< |d|ji7 }|s�|jd kr�|d d i7 }q�|jd kr�t� d ��n|jd kr�|d d i7 }|jdkr�|s�t j }n |� t j �}|s�|j r�|� � |�d|ji�}|t�|�� d|i�fS )N�_sa_orm_insert_options> rA r� r� r� r� r� Fr� r< r� r� r� r� rc r� �rawr� )r3 r6 r� r� r� r� r< r� r� r� r Z_orm_load_exec_optionsr� r� r� r r ) r� ri r� r\ r9 r� r �insert_optionsr� rD rD rF r � sT �� � � � ��z"BulkORMInsert.orm_pre_session_execr0 z dml.Insertr5 r+ r. r3 �_result.Result�ri r� r\ r9 r� r] rB c C s< |� d| j�}|jdvr"t�d��|jdkrD|j||p8i |d�}|S |jdkr�|j} |jd urt| jrtt� d| � ���| d us�J �|j d us�J �t | t dt |t�r�|gn|�|j d |j|j||d �}n&|jd kr�|j||p�i |d�}nt� �t|j�s�|S |j�r(|� d tj�} | d di7 } |�d | i�}| �||||||�S )Nr7 )r8 rc r� r� zHValid strategies for ORM insert strategy are 'raw', 'orm', 'bulk', 'autor8 )r9 rc z`bulk INSERT with a 'post values' clause (typically upsert) not supported for multi-table mapper �Iterable[Dict[str, Any]]F)r? r@ rA r8 r9 r� r� r� T)r� r6 r� r� r� r0 r� Z_post_values_clauseZ _multiple_persistence_tablesr� � _transactionrG r r� rI r5 r4 �AssertionErrorr: rs r� r r� r� r� ) r� ri r� r\ r9 r� r] r9 r r< r� rD rD rF �orm_execute_statement� sz � � � ���� �� � � ��z#BulkORMInsert.orm_execute_statement)rB c s~ t tt� j||fi |���}|d ur.|j }nd}|s:|S |jd }|j�dd�}|dkrf|�|� n|dkrz|� ||� |S )NTr� r� r8 rc r� ) r r3 �superr� �stackr� r� r� �_setup_for_bulk_insert�_setup_for_orm_insert)r� r� r� �kwr� �toplevelr< r� �� __class__rD rF r� ) s � z"BulkORMInsert.create_for_statementc s dd� � fdd�|� � D �D �S )Nc S s& i | ] \}}}|d ur |j n||�qS rC rW )rK �colr� r� rD rD rF r� B s �z<BulkORMInsert._resolved_keys_as_col_keys.<locals>.<dictcomp>c 3 s$ | ] \}}� j �|�||fV qd S rC )r� r� r� rU rD rF r` D s z;BulkORMInsert._resolved_keys_as_col_keys.<locals>.<genexpr>)rp )r� r< Zresolved_value_dictrD rU rF �_resolved_keys_as_col_keys@ s ��z(BulkORMInsert._resolved_keys_as_col_keysc C s0 t tj| j� }}| j||||dd�}|| _d S )NF�r� r� )r r �Insertr� r� )r� r� r< r� r� rD rD rF rC I s �z#BulkORMInsert._setup_for_orm_insertc s� t tj| j� }}|j}|d |d � }|�� }� |_| jrX� fdd�| j�� D �| _| j ||||dd�}| j dur�| j j j r�t �d��|| _dS ) z�establish an INSERT statement within the context of bulk insert. This method will be within the "conn.execute()" call that is invoked by persistence._emit_insert_statement(). Z_emit_insert_tableZ_emit_insert_mapperc s i | ]\}}|j � u r||�qS rD �rS �rK rH �val�Zemit_insert_tablerD rF r� i s �z8BulkORMInsert._setup_for_bulk_insert.<locals>.<dictcomp>TrJ Nz�Can't use RETURNING * with bulk ORM INSERT. Please use a different INSERT form, such as INSERT..VALUES or INSERT with a Core Connection)r r rK r� r� �_clonerS �_dict_parametersrp r� r� r� r� r� � CompileError)r� r� r� r� �anZemit_insert_mapperrD rO rF rB U s4 � �� ���z$BulkORMInsert._setup_for_bulk_insert)r� r� r� r$ r6 r� r� r� r r? r� rI rC rB � __classcell__rD rD rF rF r3 � s C X r3 �updatec s� e Zd Zedd� �Zdd� Zdd� Zeddd d d d d d�� fdd� �Zeddddd�dddddddd�dd��Zedd� �Z edd � �Z ed d � �Z ed d � �Z � Z S )!� BulkORMUpdatec K s� | � | �}|j�dd�}|j }|r:|dkr:|�||� nL|dksV|dkrnd|jjvrntj|||fi |�� n|rz|dv r�|�||� |S )Nr� � unspecifiedrc r� r� )r� rW ) �__new__r� r� rA �_setup_for_bulk_updaterS r' �__init__�_setup_for_orm_update)r� r� r� rD r� r� rE rD rD rF r� � s" � �� � z"BulkORMUpdate.create_for_statementc K s^ |}|j }|jjd }|j | _}| �||�| _| j||||d� |jrVt| j�| _|� � }|jjd |u rv|j |_|j r�| j|_ n|jr�| j|_| � | j |�} | r�|j| � }tj| ||fi |�� d} |s�d } n|j�dd �} |j�dd �} | du�r| dk�o| j|j|| jd�} | dk�r:| �r:d} |j|jj� }|�rT| j||||| d �}|| _d S ) Nr� �rE Z process_criteria_for_toplevelFr� r� r� )r� TrJ )rA rS r� r< r% r� �_init_global_attributesr$ rI rP r� r# r r �wherer' rZ r� r� r� r� r@ r� r� r� ) r� r� r� rD r� rE r� r< �new_stmt�new_critr� r� r� rD rD rF r[ � sj � � �� �� �z#BulkORMUpdate._setup_for_orm_updatec s� t tj|�}|j}|d |d � }|�� }� |_tj| ||fi |�� | jrXt � d��| j rx� fdd�| j � � D �| _ || _ dS )z�establish an UPDATE statement within the context of bulk insert. This method will be within the "conn.execute()" call that is invoked by persistence._emit_update_statement(). Z_emit_update_tableZ_emit_update_mapperz�bulk ORM UPDATE does not support ordered_values() for custom UPDATE statements with bulk parameter sets. Use a non-bulk UPDATE statement or use values().c s i | ]\}}|j � u r||�qS rD rL rM �Zemit_update_tablerD rF r� s �z8BulkORMUpdate._setup_for_bulk_update.<locals>.<dictcomp>N)r r ZUpdater� rP rS r' rZ r# r� r� rQ rp r� )r� r� r� rD rS �_rD ra rF rY � s" �� �z$BulkORMUpdate._setup_for_bulk_updater0 z dml.Updater5 r+ r. r3 r: r; c s |� d| j�}|jr<|� dtj�}|ddi7 }|�d|i�}|jdvrPt�d��|jdkr�|j } |j dkspJ �|j r�|j d kr�t� d ��|j } | d us�J �|j d us�J �t| td t|t�r�|gn|�|j d d || d �} | �|||||| �S t� �||||||�S d S )Nr� r� r� T)r� r� rc r� zOValid strategies for ORM UPDATE strategy are 'orm', 'auto', 'bulk', 'core_only'rc r� r� z�bulk synchronize of persistent objects not supported when using bulk update with additional WHERE criteria right now. add synchronize_session=None execution option to bypass synchronize of persistent objects.r< F)r? r} rz r{ )r� r� r� r r� r� r� r� r� r r� r� r� r= r r r� rI r r@ r? ) r� ri r� r\ r9 r� r] r r� r{ r< r rF rD rF r? # sp �� � � ��� �� � �z#BulkORMUpdate.orm_execute_statementFr� r r| r: r� c C sL |j o |jj}|sdS |r |jS |r*|jS |rH|jsHt�d|j� d���dS )NF� Dialect "z�" does not support RETURNING with UPDATE..FROM; for synchronize_session='fetch', please add the additional execution option 'is_update_from=True' to the statement to indicate that a separate SELECT should be used for this backend.T)Zupdate_returningr� �implicit_returningZ update_executemany_returningZupdate_returning_multifromr� rR r� �r� r� r< r� r� r� r� Z normal_answerrD rD rF r� y s � �z BulkORMUpdate.can_use_returningc s� |sd S |j }dd� |jD �}|j}|D ]�� |�� fdd�|D �|j�}|�|�} | sXq(t� ��|�} | j} | j � | �} | D ]} | | v r|� | | | < q|| j j � | d | � | �| t| �� | � | ��| �}|r(| �| |� q(d S )Nc S s g | ] }|j �qS rD rW )rK �proprD rD rF rM � rN zDBulkORMUpdate._do_post_synchronize_bulk_evaluate.<locals>.<listcomp>c 3 s | ]}� | V qd S rC rD rg ��paramrD rF r` � rN zCBulkORMUpdate._do_post_synchronize_bulk_evaluate.<locals>.<genexpr>)r� rt � identity_map� identity_key_from_primary_keyr� Zfast_get_stater� � differencerI � unmodifiedr� �manager�dispatch�refresh�_commitrm �_expire_attributes)r� ri r\ r r r< r ri � identity_keyrL �evaluated_keysrO � to_evaluaterX � to_expirerD rg rF r � s4 � �z0BulkORMUpdate._do_post_synchronize_bulk_evaluatec C sF | � ||j�� �}| �||||jjd dd� |D �|�� |�� � d S )Nr c S s g | ]\}}}}|||f�qS rD rD )rK r rL rO rb rD rD rF rM � rN z?BulkORMUpdate._do_post_synchronize_evaluate.<locals>.<listcomp>)r ri � all_states�#_apply_update_set_values_to_objectsr �compiled_parameters� prefetch_cols�postfetch_cols)r� ri r� r r �matched_objectsrD rD rF r � s � �z+BulkORMUpdate._do_post_synchronize_evaluatec s� �j �|j}|r2| �|�|�}�fdd�|D �}n�j}� fdd���fdd�dd� |D �D �D �}|sld S | �� �||jjd dd� |D �|�� |�� � d S )Nc s g | ]}t |�� jf �qS rD �ru r� r �r rD rF rM � s �z<BulkORMUpdate._do_post_synchronize_fetch.<locals>.<listcomp>c s g | ]}|� j v r� j | �qS rD )ri )rK rr )ri rD rF rM � s �c s6 g | ].\}}�j d u s |�j kr� jt|�|d��qS )Nr )r� rj rm )rK r� r� )� target_mapperr rD rF rM � s ��c S s g | ]}|d d� |d f�qS )r ���rD r rD rD rF rM � s r c S s" g | ]}|t �|�t �|�f�qS rD )r �instance_state� instance_dict)rK r rD rD rF rM s ��) r� �returned_defaults_rowsr r� rw r rx ry rz ) r� ri r� r r r� �pk_rowsr1 �objsrD )ri r~ r rF r � s< � � ��� ��z(BulkORMUpdate._do_post_synchronize_fetchc s� |j ��j}t�|�} | ��|�} | ��| �} i } | D ]>\} }z| �t�t j |��}W n tj yj Y q60 || | < q6t | � � ��dd� | D �}t� }� ��fdd�|D �}�fdd�|D ����}�fdd�|D �}|D ]�\}}}|�� fdd�|D �� |�|j|� |j���}|D ] } | |v �r| | |�|| < �q|jj�|d |� |�|t |�� |�|��|�}|�r�|�||� |�|� q�|�|� d S ) zeapply values to objects derived from an update statement, e.g. UPDATE..SET <values> c S s h | ] \}}|�qS rD rD r� rD rD rF � <setcomp>5 rN zDBulkORMUpdate._apply_update_set_values_to_objects.<locals>.<setcomp>c s. h | ]&}|j � v r|�jv r|j �vr|�qS rD )rX r& r� ��effective_paramsrs r< rD rF r� 9 s �c s" h | ]}|� j v r� j | j�qS rD �r& rX r� rU rD rF r� @ s �c s g | ]}� j | j|jf�qS rD r� r� rU rD rF rM F s zEBulkORMUpdate._apply_update_set_values_to_objects.<locals>.<listcomp>c s i | ]\}}|� | �qS rD rD )rK Z col_to_propZc_key)r� rD rF r� M s �zEBulkORMUpdate._apply_update_set_values_to_objects.<locals>.<dictcomp>N)r� r� r r r% r* r r r� r r� r! rm r� r� rk rU rq rI rl r� rm rn ro rp �addZ_register_altered)r� ri r r� r� r{ ry rz r r r( Zresolved_keys_as_propnamesZvalue_evaluatorsrX �valueZ _evaluator�attribrv Z to_prefetchru Zprefetch_transferr rL rO rt rD r� rF rw s` � � � �� � �� z1BulkORMUpdate._apply_update_set_values_to_objects)r� r� r� r� r� r[ rY r? r� r r r rw rT rD rD rF rF rV � s( b$ U� $ * 5rV �deletec s� e Zd Zedd� �Zeddddddd d �� fd d � �Zed d d d d�dddddddd�dd��Zedd� �Zedd� �Z� Z S )� BulkORMDeletec K sp | � | �}|j�dd�}|dks4|dkrNd|jjvrNtj|||fi |�� |S |j }|}|jjd }|j |_} |j||||d� |� � } | jjd | u r�| j | _| � |j | �} | r�| j | � } tj|| |fi |�� d} |s�d } n|j�dd �} |j�dd �}|du�r4| d k�o2|j|j| |j|j�d d�d �}|�rLd } | j| jj� } |�rf|j||| | | d �} | |_|S )Nr� rW r� r� r\ Fr� r� r� r� )r� r� TrJ )rX r� r� rS r% rZ rA r< r] rP r� r r r^ r� r� r� r@ r� r� r� )r� r� r� rD r� r� rE r� r� r< r_ r` r� r� r� rD rD rF r� m s� ��� � �� �� ��� �z"BulkORMDelete.create_for_statementr0 z dml.Deleter5 r+ r. r3 r: r; c sL |� d| j�}|jdkr"t�d��|jdvr6t�d��t� �||||||�S )Nr� rc z�Bulk ORM DELETE not supported right now. Statement may be invoked at the Core level using session.connection().execute(stmt, parameters))r� r� r� zGValid strategies for ORM DELETE strategy are 'orm', 'auto', 'core_only')r� r� r� r� r� r� r@ r? )r� ri r� r\ r9 r� r] r rF rD rF r? � s � � � �z#BulkORMDelete.orm_execute_statementFr� r r| r: r� c C sB |j o |jj}|sdS |r |jS |r>|js>t�d|j� d���dS )NFrc z�" does not support RETURNING with DELETE..USING; for synchronize_session='fetch', please add the additional execution option 'is_delete_using=True' to the statement to indicate that a separate SELECT should be used for this backend.T)Zdelete_returningr� rd Zdelete_returning_multifromr� rR r� re rD rD rF r� � s � �z BulkORMDelete.can_use_returningc C sZ | � ||j�� �}g }|D ],\}}} } | r<|�| |jj� q|�|� q|rV|�|� d S rC )r ri rv Z_expireZ _modifiedr �_remove_newly_deleted) r� ri r� r r r{ Z to_deleterb rL rO Zis_partially_expiredrD rD rF r s � z+BulkORMDelete._do_post_synchronize_evaluatec s� � j }|j}|r2| �|||�}� fdd�|D �}n� j}|D ]L} | dd� } | d } |jt| �| d�} | |jv r<|�t� |j| �g� q<d S )Nc s g | ]}t |�� jf �qS rD r| r r} rD rF rM 3 s �z<BulkORMDelete._do_post_synchronize_fetch.<locals>.<listcomp>r r r ) r� r� r r� rj rm ri r� r r� ) r� ri r� r r r~ r� r� r1 r r� r� rr rD r} rF r & s0 � � � ���z(BulkORMDelete._do_post_synchronize_fetch) r� r� r� r� r� r? r� r r rT rD rD rF rF r� k s [ � ( r� )O�__doc__� __future__r �typingr r r r r r r r r � r r r r r' r r �baser r r r r r� r Zenginer r r� Zsqlr r r r r r! Zsql.baser" r# r$ Zsql.dmlr% r& r' r( Z util.typingr) Z_typingr* r+ r, r< r- ri r. r/ r0 r1 rL r2 r3 r4 Zengine.interfacesr5 �objectr6 rG r rn r� r� Z plugin_forr3 rV r� rD rD rD rF �<module> s� �$ �$�" �" �"� \ x i sqlalchemy/orm/__pycache__/events.cpython-39.pyc 0000644 00000367015 15125143220 0015657 0 ustar 00 a ��Jh%� � @ s� U d Z ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z dd lm Z dd lm Z dd lm Z dd lm Z dd lmZ ddlmZ ddlmZ ddlZddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z ddl m Z ddl m Z dd l m Z dd l!m"Z" dd l#m$Z$ dd l#m%Z% d d!lm&Z& d d"lm'Z' d d#lm(Z( d d$l&m)Z) d d%l*m+Z+ d d&l,m-Z- e�r�dd'lm.Z. dd(l/m0Z0 dd)l/m1Z1 dd*l/m2Z2 dd+l/m3Z3 dd,lm4Z4 dd-lm5Z5 dd.l#m6Z6 dd/l#m7Z7 dd0l8m9Z9 d d1l:m;Z; d d2l<m=Z= d d3l<m>Z> d d4l*m?Z? d d5l@mAZA d d6lBmCZC d d7lDmEZE d d8lDmFZF d d9lGmHZH d d:lImJZJ ed;ed<�ZKed=e)d<�ZLG d>d?� d?e&jMe �ZNG d@dA� dA�ZOG dBdC� dCe&jMee �ZPG dDdE� dEe&jQe+ �ZRG dFdG� dGeRe+ �ZSG dHdI� dIe&jMejHe �ZTG dJdK� dKeRe+ �ZUeV� ZWdLeXdM< G dNdO� dOe&jMe$ �ZYG dPdQ� dQe&jMee �ZZG dRdS� dSe&jMe e �Z[dS )TzORM event interfaces. � )� annotations)�Any)�Callable)� Collection)�Dict)�Generic)�Iterable)�Optional)�Sequence)�Set)�Type)� TYPE_CHECKING)�TypeVar)�UnionN� )�instrumentation)� interfaces)� mapperlib)�QueryableAttribute��_mapper_or_none)�NO_KEY)� ClassManager)�InstrumentationFactory)� BulkDelete)� BulkUpdate)�Query)�scoped_session)�Session)� sessionmaker� )�event)�exc)�util)� EventTarget)�_ET)�inspect_getfullargspec)� ReferenceType)� _InstanceDict)�_InternalEntityType)�_O)�_T)�Event)�EventConstants)�ORMExecuteState)�SessionTransaction)�UOWTransaction)� Connection)� _Dispatch)�_HasEventsDispatch)� _EventKey)�CollectionAdapter)� QueryContext)� DeclarativeAttributeIntercept)�DeclarativeMeta)�Mapper)� InstanceState�_KT)�bound�_ET2c s� e Zd ZdZdZeZedddd�dd��Zed d d d d d�dd��Z ed d�� fdd� �Z dd d�dd�Z dd d�dd�Z dddd d �d d �Z � ZS ) �InstrumentationEventsa Events related to class instrumentation events. The listeners here support being established against any new style class, that is any object that is a subclass of 'type'. Events will then be fired off for events against that class. If the "propagate=True" flag is passed to event.listen(), the event will fire off for subclasses of that class as well. The Python ``type`` builtin is also accepted as a target, which when used has the effect of events being emitted for all classes. Note the "propagate" flag here is defaulted to ``True``, unlike the other class level events where it defaults to ``False``. This means that new subclasses will also be the subject of these events, when a listener is established on a superclass. Z SomeBaseClassz;Union[InstrumentationFactory, Type[InstrumentationFactory]]�strzEOptional[Union[InstrumentationFactory, Type[InstrumentationFactory]]]��target� identifier�returnc C s t |t�rt|�S d S d S �N)� isinstance�type�_InstrumentationEventsHold��clsrA rB � rJ �J/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/events.py� _accept_withe s z"InstrumentationEvents._accept_withTz _EventKey[_T]�boolr �None)� event_key� propagate�kwrC c sv |j |j|j ��� dddd�� ��fdd� �ddd ���fd d � }t��j|��|�tj�� ��j f i |�� d S ) NrF r � Optional[Any])� target_cls�argrC c sT �� }|d u rd S �r0t | |�r0� | g|�R � S �sL| |u rL� | g|�R � S d S d S rD )� issubclass)rS rT Z listen_cls)�fnrP rA rJ rK �listen� s z-InstrumentationEvents._listen.<locals>.listenzReferenceType[_T]rN )�refrC c s, t j�d � �tj�}ttjj� ��|� d S rD )r! �registryr4 r �_instrumentation_factory�getattr�dispatch�remove)rX �key)rB rW rJ rK r] � s ���z-InstrumentationEvents._listen.<locals>.remove) �dispatch_targetrB � _listen_fn�weakrefrX �class_�with_dispatch_targetr rZ � with_wrapper� base_listen)rI rO rP rQ r] rJ )rV rB rW rP rA rK �_listenx s � ���z InstrumentationEvents._listen�rC c s t � �� tjj�� d S rD )�super�_clearr rZ r\ �rI �� __class__rJ rK ri � s z InstrumentationEvents._clear�ClassManager[_O])rI rC c C s dS )z�Called after the given class is instrumented. To get at the :class:`.ClassManager`, use :func:`.manager_of_class`. NrJ ��selfrI rJ rJ rK �class_instrument� s z&InstrumentationEvents.class_instrumentc C s dS )z�Called before the given class is uninstrumented. To get at the :class:`.ClassManager`, use :func:`.manager_of_class`. NrJ rn rJ rJ rK �class_uninstrument� s z(InstrumentationEvents.class_uninstrumentr; r* )rI r^ �instrC c C s dS )z)Called when an attribute is instrumented.NrJ )ro rI r^ rr rJ rJ rK �attribute_instrument� s z*InstrumentationEvents.attribute_instrument)T)�__name__� __module__� __qualname__�__doc__�_target_class_docr �_dispatch_target� classmethodrL rf ri rp rq rs � __classcell__rJ rJ rk rK r> L s �+r> c @ s* e Zd ZdZddd�dd�Ze�e�ZdS )rG zwtemporary marker object used to transfer from _accept_with() to _listen() on the InstrumentationEvents class. rF rN �rb rC c C s || _ d S rD �rb �ro rb rJ rJ rK �__init__� s z#_InstrumentationEventsHold.__init__N) rt ru rv rw r r! � dispatcherr> r\ rJ rJ rJ rK rG � s rG c sB e Zd ZdZdZeZedddd�dd��Zee � d �d d d d �dd���Z ed;ddddddd�dd��Z edd�� fdd� �Z dddd�d d �Zd dddd �d d!�Zd dddd �d"d#�Zd d$dd%�d&d'�Zd d$dd%�d(d)�Zd d$d*dd+�d,d-�Zd d.d*dd/�d0d1�Zd d*dd2�d3d4�Zd d5dd6�d7d8�Zd d5dd6�d9d:�Z� ZS )<�InstanceEventsa� Define events specific to object lifecycle. e.g.:: from sqlalchemy import event def my_load_listener(target, context): print("on load!") event.listen(SomeClass, "load", my_load_listener) Available targets include: * mapped classes * unmapped superclasses of mapped or to-be-mapped classes (using the ``propagate=True`` flag) * :class:`_orm.Mapper` objects * the :class:`_orm.Mapper` class itself indicates listening for all mappers. Instance events are closely related to mapper events, but are more specific to the instance and its instrumentation, rather than its system of persistence. When using :class:`.InstanceEvents`, several modifiers are available to the :func:`.event.listen` function. :param propagate=False: When True, the event listener should be applied to all inheriting classes as well as the class which is the target of this listener. :param raw=False: When True, the "target" argument passed to applicable event listener functions will be the instance's :class:`.InstanceState` management object, rather than the mapped instance itself. :param restore_load_context=False: Applies to the :meth:`.InstanceEvents.load` and :meth:`.InstanceEvents.refresh` events. Restores the loader context of the object when the event hook is complete, so that ongoing eager load operations continue to target the object appropriately. A warning is emitted if the object is moved to a new loader context from within one of these events if this flag is not set. .. versionadded:: 1.3.14 � SomeClass�;Union[DeclarativeAttributeIntercept, DeclarativeMeta, type]rm rN )rb � classmanagerrC c C s t �||� d S rD )�_InstanceEventsHold�populate)rI rb r� rJ rJ rK �_new_classmanager_instance s z)InstanceEvents._new_classmanager_instance�sqlalchemy.ormz1Union[ClassManager[Any], Type[ClassManager[Any]]]r? z;Optional[Union[ClassManager[Any], Type[ClassManager[Any]]]]r@ c C sz t jj}t|t�r|S t|tj�r(|jS ||ju rBt � dd� tS t|t �rvt |tj�r\tS t � |�}|rn|S t|�S d S �Nz�The `sqlalchemy.orm.mapper()` symbol is deprecated and will be removed in a future release. For the mapper-wide event target, use the 'sqlalchemy.orm.Mapper' class.z2.0)r# � preloaded�ormrE r r r9 Z class_manager�mapper�warn_deprecatedrF rU r �opt_manager_of_classr� )rI rA rB r� �managerrJ rJ rK rL s& � zInstanceEvents._accept_withFz _EventKey[ClassManager[Any]]rM r )rO �rawrP �restore_load_contextrQ rC c sz |j |j }� �r�r<ddddd�� ��fdd� }|�|�}|jf d|i|�� |rv|�d�D ]}|�|�jdd � q^d S ) N�InstanceState[_O]r rR )�staterT rQ rC c sR �s| � � }n| }�r | j}z$� |g|�R i |��W �r>|| _S n �rL|| _0 d S rD ��obj�runid)r� rT rQ rA r� �rV r� r� rJ rK �wrap9 s � �z$InstanceEvents._listen.<locals>.wraprP T�rP )r_ r` rd re �subclass_managersrc ) rI rO r� rP r� rQ rA r� �mgrrJ r� rK rf , s zInstanceEvents._listenrg c s t � �� t�� d S rD )rh ri r� rj rk rJ rK ri P s zInstanceEvents._clear�Type[_O])r� rI rC c C s dS )a] Called when the first instance of a particular mapping is called. This event is called when the ``__init__`` method of a class is called the first time for that particular class. The event invokes before ``__init__`` actually proceeds as well as before the :meth:`.InstanceEvents.init` event is invoked. NrJ )ro r� rI rJ rJ rK � first_initU s zInstanceEvents.first_initr* )rA �args�kwargsrC c C s dS )a� Receive an instance when its constructor is called. This method is only called during a userland construction of an object, in conjunction with the object's constructor, e.g. its ``__init__`` method. It is not called when an object is loaded from the database; see the :meth:`.InstanceEvents.load` event in order to intercept a database load. The event is called before the actual ``__init__`` constructor of the object is called. The ``kwargs`` dictionary may be modified in-place in order to affect what is passed to ``__init__``. :param target: the mapped instance. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :param args: positional arguments passed to the ``__init__`` method. This is passed as a tuple and is currently immutable. :param kwargs: keyword arguments passed to the ``__init__`` method. This structure *can* be altered in place. .. seealso:: :meth:`.InstanceEvents.init_failure` :meth:`.InstanceEvents.load` NrJ �ro rA r� r� rJ rJ rK �init_ s zInstanceEvents.initc C s dS )a� Receive an instance when its constructor has been called, and raised an exception. This method is only called during a userland construction of an object, in conjunction with the object's constructor, e.g. its ``__init__`` method. It is not called when an object is loaded from the database. The event is invoked after an exception raised by the ``__init__`` method is caught. After the event is invoked, the original exception is re-raised outwards, so that the construction of the object still raises an exception. The actual exception and stack trace raised should be present in ``sys.exc_info()``. :param target: the mapped instance. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :param args: positional arguments that were passed to the ``__init__`` method. :param kwargs: keyword arguments that were passed to the ``__init__`` method. .. seealso:: :meth:`.InstanceEvents.init` :meth:`.InstanceEvents.load` NrJ r� rJ rJ rK � init_failure~ s zInstanceEvents.init_failurer6 )rA �contextrC c C s dS )a� receive an object instance after it was the subject of a merge() call, when load=False was passed. The target would be the already-loaded object in the Session which would have had its attributes overwritten by the incoming object. This overwrite operation does not use attribute events, instead just populating dict directly. Therefore the purpose of this event is so that extensions like sqlalchemy.ext.mutable know that object state has changed and incoming state needs to be set up for "parents" etc. This functionality is acceptable to be made public in a later release. .. versionadded:: 1.4.41 NrJ �ro rA r� rJ rJ rK �_sa_event_merge_wo_load� s z&InstanceEvents._sa_event_merge_wo_loadc C s dS )a Receive an object instance after it has been created via ``__new__``, and after initial attribute population has occurred. This typically occurs when the instance is created based on incoming result rows, and is only called once for that instance's lifetime. .. warning:: During a result-row load, this event is invoked when the first row received for this instance is processed. When using eager loading with collection-oriented attributes, the additional rows that are to be loaded / processed in order to load subsequent collection items have not occurred yet. This has the effect both that collections will not be fully loaded, as well as that if an operation occurs within this event handler that emits another database load operation for the object, the "loading context" for the object can change and interfere with the existing eager loaders still in progress. Examples of what can cause the "loading context" to change within the event handler include, but are not necessarily limited to: * accessing deferred attributes that weren't part of the row, will trigger an "undefer" operation and refresh the object * accessing attributes on a joined-inheritance subclass that weren't part of the row, will trigger a refresh operation. As of SQLAlchemy 1.3.14, a warning is emitted when this occurs. The :paramref:`.InstanceEvents.restore_load_context` option may be used on the event to prevent this warning; this will ensure that the existing loading context is maintained for the object after the event is called:: @event.listens_for(SomeClass, "load", restore_load_context=True) def on_load(instance, context): instance.some_unloaded_attribute .. versionchanged:: 1.3.14 Added :paramref:`.InstanceEvents.restore_load_context` and :paramref:`.SessionEvents.restore_load_context` flags which apply to "on load" events, which will ensure that the loading context for an object is restored when the event hook is complete; a warning is emitted if the load context of the object changes without this flag being set. The :meth:`.InstanceEvents.load` event is also available in a class-method decorator format called :func:`_orm.reconstructor`. :param target: the mapped instance. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :param context: the :class:`.QueryContext` corresponding to the current :class:`_query.Query` in progress. This argument may be ``None`` if the load does not correspond to a :class:`_query.Query`, such as during :meth:`.Session.merge`. .. seealso:: :ref:`mapped_class_load_events` :meth:`.InstanceEvents.init` :meth:`.InstanceEvents.refresh` :meth:`.SessionEvents.loaded_as_persistent` NrJ r� rJ rJ rK �load� s zInstanceEvents.loadzOptional[Iterable[str]])rA r� �attrsrC c C s dS )a� Receive an object instance after one or more attributes have been refreshed from a query. Contrast this to the :meth:`.InstanceEvents.load` method, which is invoked when the object is first loaded from a query. .. note:: This event is invoked within the loader process before eager loaders may have been completed, and the object's state may not be complete. Additionally, invoking row-level refresh operations on the object will place the object into a new loader context, interfering with the existing load context. See the note on :meth:`.InstanceEvents.load` for background on making use of the :paramref:`.InstanceEvents.restore_load_context` parameter, in order to resolve this scenario. :param target: the mapped instance. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :param context: the :class:`.QueryContext` corresponding to the current :class:`_query.Query` in progress. :param attrs: sequence of attribute names which were populated, or None if all column-mapped, non-deferred attributes were populated. .. seealso:: :ref:`mapped_class_load_events` :meth:`.InstanceEvents.load` NrJ )ro rA r� r� rJ rJ rK �refresh� s zInstanceEvents.refreshr0 )rA � flush_contextr� rC c C s dS )a% Receive an object instance after one or more attributes that contain a column-level default or onupdate handler have been refreshed during persistence of the object's state. This event is the same as :meth:`.InstanceEvents.refresh` except it is invoked within the unit of work flush process, and includes only non-primary-key columns that have column level default or onupdate handlers, including Python callables as well as server side defaults and triggers which may be fetched via the RETURNING clause. .. note:: While the :meth:`.InstanceEvents.refresh_flush` event is triggered for an object that was INSERTed as well as for an object that was UPDATEd, the event is geared primarily towards the UPDATE process; it is mostly an internal artifact that INSERT actions can also trigger this event, and note that **primary key columns for an INSERTed row are explicitly omitted** from this event. In order to intercept the newly INSERTed state of an object, the :meth:`.SessionEvents.pending_to_persistent` and :meth:`.MapperEvents.after_insert` are better choices. :param target: the mapped instance. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :param flush_context: Internal :class:`.UOWTransaction` object which handles the details of the flush. :param attrs: sequence of attribute names which were populated. .. seealso:: :ref:`mapped_class_load_events` :ref:`orm_server_defaults` :ref:`metadata_defaults_toplevel` NrJ )ro rA r� r� rJ rJ rK � refresh_flush s z InstanceEvents.refresh_flush)rA r� rC c C s dS )a Receive an object instance after its attributes or some subset have been expired. 'keys' is a list of attribute names. If None, the entire state was expired. :param target: the mapped instance. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :param attrs: sequence of attribute names which were expired, or None if all attributes were expired. NrJ )ro rA r� rJ rJ rK �expireO s zInstanceEvents.expirer( )rA � state_dictrC c C s dS )a� Receive an object instance when its associated state is being pickled. :param target: the mapped instance. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :param state_dict: the dictionary returned by :class:`.InstanceState.__getstate__`, containing the state to be pickled. NrJ �ro rA r� rJ rJ rK �pickle` s zInstanceEvents.picklec C s dS )a� Receive an object instance after its associated state has been unpickled. :param target: the mapped instance. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :param state_dict: the dictionary sent to :class:`.InstanceState.__setstate__`, containing the state dictionary which was pickled. NrJ r� rJ rJ rK �unpicklen s zInstanceEvents.unpickle)FFF)rt ru rv rw rx r ry rz r� r# �preload_modulerL rf ri r� r� r� r� r� r� r� r� r� r� r{ rJ rJ rk rK r� � s2 1! � # !J$/r� c @ sv e Zd ZU dZded< ddd�dd�Zedd �d d ��ZG d d � d ee �Z ddd�dd�Z edddd�dd��Z dS )� _EventsHoldz�Hold onto listeners against unmapped, uninstrumented classes. Establish _listen() for that class' mapper/instrumentation when those objects are created for that class. �#weakref.WeakKeyDictionary[Any, Any]� all_holdsr� rN r| c C s || _ d S rD r} r~ rJ rJ rK r � s z_EventsHold.__init__rg c C s | j �� d S rD )r� �clearrj rJ rJ rK ri � s z_EventsHold._clearc @ s8 e Zd ZU dZded< ed ddddddd �d d ��ZdS ) z_EventsHold.HoldEventsNzOptional[Type[_ET2]]ry Fz_EventKey[_ET2]rM r rN )rO r� rP �retvalrQ rC c K s� |j }|j|jv r |j|j }ni }|j|j< tj�||� |||||f||j< |r�t|j�� �}|r�|� d�} |� | �� � |� | �} | d urd|� | �j f |d|d�|�� qdd S )Nr F�r� rP r� )r_ rb r� r! rY Z_stored_in_collection�_key�list�__subclasses__�pop�extend�resolverc rW ) rI rO r� rP r� rQ rA � collection�stack�subclass�subjectrJ rJ rK rf � s. � ��z _EventsHold.HoldEvents._listen)FFF)rt ru rv ry �__annotations__rz rf rJ rJ rJ rK � HoldEvents� s �r� �_EventKey[_ET])rO rC c C s( |j }t|t�r$|j|j }||j= d S rD )r_ rE r� r� rb r� )ro rO rA r� rJ rJ rK r] � s z_EventsHold.removez#Union[ClassManager[_O], Mapper[_O]])rb r� rC c C sf |j D ]Z}|| jv r| j| }|�� D ]8\}}}}} |s@||u r&|�|�jf |d|d�| �� q&qd S )NFr� )�__mro__r� �valuesrc rW ) rI rb r� r� r� rO r� rP r� rQ rJ rJ rK r� � s � ��z_EventsHold.populateN) rt ru rv rw r� r rz ri r r= r� r] r� rJ rJ rJ rK r� } s )r� c @ sP e Zd ZU e�� Zded< ddd�dd�ZG dd � d ej e e �Z e �e �Zd S ) r� r� r� r� zOptional[ClassManager[_O]]r| c C s t �|�S rD )r r� r~ rJ rJ rK r� � s z_InstanceEventsHold.resolvec @ s e Zd ZdS )z&_InstanceEventsHold.HoldInstanceEventsN�rt ru rv rJ rJ rJ rK �HoldInstanceEvents� s r� N)rt ru rv ra �WeakKeyDictionaryr� r� r� r� r� r% r� r� r! r� r\ rJ rJ rJ rK r� � s � r� c sd e Zd ZdZdZejZedddd�dd��Z ee � d �d d d d �dd���Z ed7ddddddd�dd��Z edd�� fdd� �Zdddd�d d �Zdddd�d d �Zdddd�d d!�Zdddd�d"d#�Zdd�d$d%�Zdd�d&d'�Zdd(d)dd*�d+d,�Zdd(d)dd*�d-d.�Zdd(d)dd*�d/d0�Zdd(d)dd*�d1d2�Zdd(d)dd*�d3d4�Zdd(d)dd*�d5d6�Z� ZS )8� MapperEventsa� Define events specific to mappings. e.g.:: from sqlalchemy import event def my_before_insert_listener(mapper, connection, target): # execute a stored procedure upon INSERT, # apply the value to the row to be inserted target.calculated_value = connection.execute( text("select my_special_function(%d)" % target.special_number) ).scalar() # associate the listener function with SomeClass, # to execute during the "before_insert" hook event.listen(SomeClass, "before_insert", my_before_insert_listener) Available targets include: * mapped classes * unmapped superclasses of mapped or to-be-mapped classes (using the ``propagate=True`` flag) * :class:`_orm.Mapper` objects * the :class:`_orm.Mapper` class itself indicates listening for all mappers. Mapper events provide hooks into critical sections of the mapper, including those related to object instrumentation, object loading, and object persistence. In particular, the persistence methods :meth:`~.MapperEvents.before_insert`, and :meth:`~.MapperEvents.before_update` are popular places to augment the state being persisted - however, these methods operate with several significant restrictions. The user is encouraged to evaluate the :meth:`.SessionEvents.before_flush` and :meth:`.SessionEvents.after_flush` methods as more flexible and user-friendly hooks in which to apply additional database state during a flush. When using :class:`.MapperEvents`, several modifiers are available to the :func:`.event.listen` function. :param propagate=False: When True, the event listener should be applied to all inheriting mappers and/or the mappers of inheriting classes, as well as any mapper which is the target of this listener. :param raw=False: When True, the "target" argument passed to applicable event listener functions will be the instance's :class:`.InstanceState` management object, rather than the mapped instance itself. :param retval=False: when True, the user-defined event function must have a return value, the purpose of which is either to control subsequent event propagation, or to otherwise alter the operation in progress by the mapper. Possible return values are: * ``sqlalchemy.orm.interfaces.EXT_CONTINUE`` - continue event processing normally. * ``sqlalchemy.orm.interfaces.EXT_STOP`` - cancel all subsequent event handlers in the chain. * other values - the return value specified by specific listeners. r� r� z Mapper[_O]rN )rb r� rC c C s t �||� d S rD )�_MapperEventsHoldr� )rI rb r� rJ rJ rK �_new_mapper_instance0 s z!MapperEvents._new_mapper_instancer� z9Union[mapperlib.Mapper[Any], Type[mapperlib.Mapper[Any]]]r? zCOptional[Union[mapperlib.Mapper[Any], Type[mapperlib.Mapper[Any]]]]r@ c C sd t jj}||ju r$t �dd� tjS t|t�r\t |tj�r>|S t |�}|d urR|S t |�S n|S d S r� ) r# r� r� r� r� r r9 rE rF rU r r� )rI rA rB r� r� rJ rJ rK rL 8 s � zMapperEvents._accept_withFr� rM r )rO r� r� rP rQ rC c s� |j |j|j }}� |dv r2|tjur2t�d� �r:�s��szt| |�}zt|�d � d�d �W n t yx d �Y n0 dddd�� ���fdd � } |� | �}|r�|j D ] } |� | �jf d d i|�� q�n|jf i |�� d S ) N)�before_configured�after_configuredzf'before_configured' and 'after_configured' ORM events only invoke with the Mapper class as the target.r rA r r �rT rQ rC c sN �s$�d ur$t | �} | � �� | �< �s<� | i |�� tjS � | i |��S d S rD )r� r� r Z EXT_CONTINUE�rT rQ �rV r� r� Z target_indexrJ rK r� x s z"MapperEvents._listen.<locals>.wraprP T)r_ rB r` r r9 r# �warnr[ r& �index� ValueErrorrd Zself_and_descendantsrc re ) rI rO r� r� rP rQ rA rB �methr� r� rJ r� rK rf U s: � ��� � �� zMapperEvents._listenrg c s t � �� t�� d S rD )rh ri r� rj rk rJ rK ri � s zMapperEvents._clearr� )r� rb rC c C s dS )an Receive a class when the mapper is first constructed, before instrumentation is applied to the mapped class. This event is the earliest phase of mapper construction. Most attributes of the mapper are not yet initialized. To receive an event within initial mapper construction where basic state is available such as the :attr:`_orm.Mapper.attrs` collection, the :meth:`_orm.MapperEvents.after_mapper_constructed` event may be a better choice. This listener can either be applied to the :class:`_orm.Mapper` class overall, or to any un-mapped class which serves as a base for classes that will be mapped (using the ``propagate=True`` flag):: Base = declarative_base() @event.listens_for(Base, "instrument_class", propagate=True) def on_new_class(mapper, cls_): "..." :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param class\_: the mapped class. .. seealso:: :meth:`_orm.MapperEvents.after_mapper_constructed` NrJ �ro r� rb rJ rJ rK �instrument_class� s z MapperEvents.instrument_classc C s dS )a� Receive a class and mapper when the :class:`_orm.Mapper` has been fully constructed. This event is called after the initial constructor for :class:`_orm.Mapper` completes. This occurs after the :meth:`_orm.MapperEvents.instrument_class` event and after the :class:`_orm.Mapper` has done an initial pass of its arguments to generate its collection of :class:`_orm.MapperProperty` objects, which are accessible via the :meth:`_orm.Mapper.get_property` method and the :attr:`_orm.Mapper.iterate_properties` attribute. This event differs from the :meth:`_orm.MapperEvents.before_mapper_configured` event in that it is invoked within the constructor for :class:`_orm.Mapper`, rather than within the :meth:`_orm.registry.configure` process. Currently, this event is the only one which is appropriate for handlers that wish to create additional mapped classes in response to the construction of this :class:`_orm.Mapper`, which will be part of the same configure step when :meth:`_orm.registry.configure` next runs. .. versionadded:: 2.0.2 .. seealso:: :ref:`examples_versioning` - an example which illustrates the use of the :meth:`_orm.MapperEvents.before_mapper_configured` event to create new mappers to record change-audit histories on objects. NrJ r� rJ rJ rK �after_mapper_constructed� s z%MapperEvents.after_mapper_constructedc C s dS )a� Called right before a specific mapper is to be configured. This event is intended to allow a specific mapper to be skipped during the configure step, by returning the :attr:`.orm.interfaces.EXT_SKIP` symbol which indicates to the :func:`.configure_mappers` call that this particular mapper (or hierarchy of mappers, if ``propagate=True`` is used) should be skipped in the current configuration run. When one or more mappers are skipped, the "new mappers" flag will remain set, meaning the :func:`.configure_mappers` function will continue to be called when mappers are used, to continue to try to configure all available mappers. In comparison to the other configure-level events, :meth:`.MapperEvents.before_configured`, :meth:`.MapperEvents.after_configured`, and :meth:`.MapperEvents.mapper_configured`, the :meth:`.MapperEvents.before_mapper_configured` event provides for a meaningful return value when it is registered with the ``retval=True`` parameter. .. versionadded:: 1.3 e.g.:: from sqlalchemy.orm import EXT_SKIP Base = declarative_base() DontConfigureBase = declarative_base() @event.listens_for( DontConfigureBase, "before_mapper_configured", retval=True, propagate=True, ) def dont_configure(mapper, cls): return EXT_SKIP .. seealso:: :meth:`.MapperEvents.before_configured` :meth:`.MapperEvents.after_configured` :meth:`.MapperEvents.mapper_configured` NrJ r� rJ rJ rK �before_mapper_configured� s z%MapperEvents.before_mapper_configuredc C s dS )a Called when a specific mapper has completed its own configuration within the scope of the :func:`.configure_mappers` call. The :meth:`.MapperEvents.mapper_configured` event is invoked for each mapper that is encountered when the :func:`_orm.configure_mappers` function proceeds through the current list of not-yet-configured mappers. :func:`_orm.configure_mappers` is typically invoked automatically as mappings are first used, as well as each time new mappers have been made available and new mapper use is detected. When the event is called, the mapper should be in its final state, but **not including backrefs** that may be invoked from other mappers; they might still be pending within the configuration operation. Bidirectional relationships that are instead configured via the :paramref:`.orm.relationship.back_populates` argument *will* be fully available, since this style of relationship does not rely upon other possibly-not-configured mappers to know that they exist. For an event that is guaranteed to have **all** mappers ready to go including backrefs that are defined only on other mappings, use the :meth:`.MapperEvents.after_configured` event; this event invokes only after all known mappings have been fully configured. The :meth:`.MapperEvents.mapper_configured` event, unlike :meth:`.MapperEvents.before_configured` or :meth:`.MapperEvents.after_configured`, is called for each mapper/class individually, and the mapper is passed to the event itself. It also is called exactly once for a particular mapper. The event is therefore useful for configurational steps that benefit from being invoked just once on a specific mapper basis, which don't require that "backref" configurations are necessarily ready yet. :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param class\_: the mapped class. .. seealso:: :meth:`.MapperEvents.before_configured` :meth:`.MapperEvents.after_configured` :meth:`.MapperEvents.before_mapper_configured` NrJ r� rJ rJ rK �mapper_configured s z MapperEvents.mapper_configuredc C s dS )a� Called before a series of mappers have been configured. The :meth:`.MapperEvents.before_configured` event is invoked each time the :func:`_orm.configure_mappers` function is invoked, before the function has done any of its work. :func:`_orm.configure_mappers` is typically invoked automatically as mappings are first used, as well as each time new mappers have been made available and new mapper use is detected. This event can **only** be applied to the :class:`_orm.Mapper` class, and not to individual mappings or mapped classes. It is only invoked for all mappings as a whole:: from sqlalchemy.orm import Mapper @event.listens_for(Mapper, "before_configured") def go(): ... Contrast this event to :meth:`.MapperEvents.after_configured`, which is invoked after the series of mappers has been configured, as well as :meth:`.MapperEvents.before_mapper_configured` and :meth:`.MapperEvents.mapper_configured`, which are both invoked on a per-mapper basis. Theoretically this event is called once per application, but is actually called any time new mappers are to be affected by a :func:`_orm.configure_mappers` call. If new mappings are constructed after existing ones have already been used, this event will likely be called again. To ensure that a particular event is only called once and no further, the ``once=True`` argument (new in 0.9.4) can be applied:: from sqlalchemy.orm import mapper @event.listens_for(mapper, "before_configured", once=True) def go(): ... .. seealso:: :meth:`.MapperEvents.before_mapper_configured` :meth:`.MapperEvents.mapper_configured` :meth:`.MapperEvents.after_configured` NrJ �ro rJ rJ rK r� > s z MapperEvents.before_configuredc C s dS )a3 Called after a series of mappers have been configured. The :meth:`.MapperEvents.after_configured` event is invoked each time the :func:`_orm.configure_mappers` function is invoked, after the function has completed its work. :func:`_orm.configure_mappers` is typically invoked automatically as mappings are first used, as well as each time new mappers have been made available and new mapper use is detected. Contrast this event to the :meth:`.MapperEvents.mapper_configured` event, which is called on a per-mapper basis while the configuration operation proceeds; unlike that event, when this event is invoked, all cross-configurations (e.g. backrefs) will also have been made available for any mappers that were pending. Also contrast to :meth:`.MapperEvents.before_configured`, which is invoked before the series of mappers has been configured. This event can **only** be applied to the :class:`_orm.Mapper` class, and not to individual mappings or mapped classes. It is only invoked for all mappings as a whole:: from sqlalchemy.orm import Mapper @event.listens_for(Mapper, "after_configured") def go(): ... Theoretically this event is called once per application, but is actually called any time new mappers have been affected by a :func:`_orm.configure_mappers` call. If new mappings are constructed after existing ones have already been used, this event will likely be called again. To ensure that a particular event is only called once and no further, the ``once=True`` argument (new in 0.9.4) can be applied:: from sqlalchemy.orm import mapper @event.listens_for(mapper, "after_configured", once=True) def go(): ... .. seealso:: :meth:`.MapperEvents.before_mapper_configured` :meth:`.MapperEvents.mapper_configured` :meth:`.MapperEvents.before_configured` NrJ r� rJ rJ rK r� q s z MapperEvents.after_configuredr1 r* )r� � connectionrA rC c C s dS )a# Receive an object instance before an INSERT statement is emitted corresponding to that instance. .. note:: this event **only** applies to the :ref:`session flush operation <session_flushing>` and does **not** apply to the ORM DML operations described at :ref:`orm_expression_update_delete`. To intercept ORM DML events, use :meth:`_orm.SessionEvents.do_orm_execute`. This event is used to modify local, non-object related attributes on the instance before an INSERT occurs, as well as to emit additional SQL statements on the given connection. The event is often called for a batch of objects of the same class before their INSERT statements are emitted at once in a later step. In the extremely rare case that this is not desirable, the :class:`_orm.Mapper` object can be configured with ``batch=False``, which will cause batches of instances to be broken up into individual (and more poorly performing) event->persist->event steps. .. warning:: Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param connection: the :class:`_engine.Connection` being used to emit INSERT statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. :param target: the mapped instance being persisted. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :return: No return value is supported by this event. .. seealso:: :ref:`session_persistence_events` NrJ �ro r� r� rA rJ rJ rK � before_insert� s zMapperEvents.before_insertc C s dS )a Receive an object instance after an INSERT statement is emitted corresponding to that instance. .. note:: this event **only** applies to the :ref:`session flush operation <session_flushing>` and does **not** apply to the ORM DML operations described at :ref:`orm_expression_update_delete`. To intercept ORM DML events, use :meth:`_orm.SessionEvents.do_orm_execute`. This event is used to modify in-Python-only state on the instance after an INSERT occurs, as well as to emit additional SQL statements on the given connection. The event is often called for a batch of objects of the same class after their INSERT statements have been emitted at once in a previous step. In the extremely rare case that this is not desirable, the :class:`_orm.Mapper` object can be configured with ``batch=False``, which will cause batches of instances to be broken up into individual (and more poorly performing) event->persist->event steps. .. warning:: Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param connection: the :class:`_engine.Connection` being used to emit INSERT statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. :param target: the mapped instance being persisted. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :return: No return value is supported by this event. .. seealso:: :ref:`session_persistence_events` NrJ r� rJ rJ rK � after_insert� s zMapperEvents.after_insertc C s dS )a� Receive an object instance before an UPDATE statement is emitted corresponding to that instance. .. note:: this event **only** applies to the :ref:`session flush operation <session_flushing>` and does **not** apply to the ORM DML operations described at :ref:`orm_expression_update_delete`. To intercept ORM DML events, use :meth:`_orm.SessionEvents.do_orm_execute`. This event is used to modify local, non-object related attributes on the instance before an UPDATE occurs, as well as to emit additional SQL statements on the given connection. This method is called for all instances that are marked as "dirty", *even those which have no net changes to their column-based attributes*. An object is marked as dirty when any of its column-based attributes have a "set attribute" operation called or when any of its collections are modified. If, at update time, no column-based attributes have any net changes, no UPDATE statement will be issued. This means that an instance being sent to :meth:`~.MapperEvents.before_update` is *not* a guarantee that an UPDATE statement will be issued, although you can affect the outcome here by modifying attributes so that a net change in value does exist. To detect if the column-based attributes on the object have net changes, and will therefore generate an UPDATE statement, use ``object_session(instance).is_modified(instance, include_collections=False)``. The event is often called for a batch of objects of the same class before their UPDATE statements are emitted at once in a later step. In the extremely rare case that this is not desirable, the :class:`_orm.Mapper` can be configured with ``batch=False``, which will cause batches of instances to be broken up into individual (and more poorly performing) event->persist->event steps. .. warning:: Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param connection: the :class:`_engine.Connection` being used to emit UPDATE statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. :param target: the mapped instance being persisted. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :return: No return value is supported by this event. .. seealso:: :ref:`session_persistence_events` NrJ r� rJ rJ rK � before_update s zMapperEvents.before_updatec C s dS )a� Receive an object instance after an UPDATE statement is emitted corresponding to that instance. .. note:: this event **only** applies to the :ref:`session flush operation <session_flushing>` and does **not** apply to the ORM DML operations described at :ref:`orm_expression_update_delete`. To intercept ORM DML events, use :meth:`_orm.SessionEvents.do_orm_execute`. This event is used to modify in-Python-only state on the instance after an UPDATE occurs, as well as to emit additional SQL statements on the given connection. This method is called for all instances that are marked as "dirty", *even those which have no net changes to their column-based attributes*, and for which no UPDATE statement has proceeded. An object is marked as dirty when any of its column-based attributes have a "set attribute" operation called or when any of its collections are modified. If, at update time, no column-based attributes have any net changes, no UPDATE statement will be issued. This means that an instance being sent to :meth:`~.MapperEvents.after_update` is *not* a guarantee that an UPDATE statement has been issued. To detect if the column-based attributes on the object have net changes, and therefore resulted in an UPDATE statement, use ``object_session(instance).is_modified(instance, include_collections=False)``. The event is often called for a batch of objects of the same class after their UPDATE statements have been emitted at once in a previous step. In the extremely rare case that this is not desirable, the :class:`_orm.Mapper` can be configured with ``batch=False``, which will cause batches of instances to be broken up into individual (and more poorly performing) event->persist->event steps. .. warning:: Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param connection: the :class:`_engine.Connection` being used to emit UPDATE statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. :param target: the mapped instance being persisted. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :return: No return value is supported by this event. .. seealso:: :ref:`session_persistence_events` NrJ r� rJ rJ rK � after_update[ s zMapperEvents.after_updatec C s dS )a� Receive an object instance before a DELETE statement is emitted corresponding to that instance. .. note:: this event **only** applies to the :ref:`session flush operation <session_flushing>` and does **not** apply to the ORM DML operations described at :ref:`orm_expression_update_delete`. To intercept ORM DML events, use :meth:`_orm.SessionEvents.do_orm_execute`. This event is used to emit additional SQL statements on the given connection as well as to perform application specific bookkeeping related to a deletion event. The event is often called for a batch of objects of the same class before their DELETE statements are emitted at once in a later step. .. warning:: Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param connection: the :class:`_engine.Connection` being used to emit DELETE statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. :param target: the mapped instance being deleted. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :return: No return value is supported by this event. .. seealso:: :ref:`session_persistence_events` NrJ r� rJ rJ rK � before_delete� s zMapperEvents.before_deletec C s dS )a� Receive an object instance after a DELETE statement has been emitted corresponding to that instance. .. note:: this event **only** applies to the :ref:`session flush operation <session_flushing>` and does **not** apply to the ORM DML operations described at :ref:`orm_expression_update_delete`. To intercept ORM DML events, use :meth:`_orm.SessionEvents.do_orm_execute`. This event is used to emit additional SQL statements on the given connection as well as to perform application specific bookkeeping related to a deletion event. The event is often called for a batch of objects of the same class after their DELETE statements have been emitted at once in a previous step. .. warning:: Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param connection: the :class:`_engine.Connection` being used to emit DELETE statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. :param target: the mapped instance being deleted. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :return: No return value is supported by this event. .. seealso:: :ref:`session_persistence_events` NrJ r� rJ rJ rK � after_delete� s zMapperEvents.after_delete)FFF) rt ru rv rw rx r r9 ry rz r� r# r� rL rf ri r� r� r� r� r� r� r� r� r� r� r� r� r{ rJ rJ rk rK r� � s6 B � 6 "563566IH0r� c @ sF e Zd Ze�� Zddd�dd�ZG dd� deje e �Z e � e �ZdS ) r� z(Union[Type[_T], _InternalEntityType[_T]]zOptional[Mapper[_T]]r| c C s t |�S rD r r~ rJ rJ rK r� s z_MapperEventsHold.resolvec @ s e Zd ZdS )z"_MapperEventsHold.HoldMapperEventsNr� rJ rJ rJ rK �HoldMapperEvents s r� N)rt ru rv ra r� r� r� r� r� r% r� r� r! r� r\ rJ rJ rJ rK r� s r� zSet[str]�$_sessionevents_lifecycle_event_namesc @ sv e Zd ZdZdZeZddd�dd�Zeddd d �d d ��Z ed d d�dddddd�dd��Z ddd�dd�Z dddd�dd �Z dddd�d d �Z ddd �d d!�Zddd �d"d#�Zddd �d$d%�Zdddd&�d'd(�Zdd)d*dd+�d,d-�Zdd)dd.�d/d0�Zdd)dd.�d1d2�Zddd3dd4�d5d6�Zedd7dd8�d9d:��Zedd7dd8�d;d<��Ze�d=g d>�d?d@� �d7ddA�dBdC��Ze�d=g d>�dDd@� �d7ddE�dFdG��Zedd7dd8�dHdI��Z edd7dd8�dJdK��Z edd7dd8�dLdM��Z edd7dd8�dNdO��Z edd7dd8�dPdQ��Z edd7dd8�dRdS��Z!edd7dd8�dTdU��Z"edd7dd8�dVdW��Z#edd7dd8�dXdY��Z$edd7dd8�dZd[��Z%d\S )]� SessionEventsat Define events specific to :class:`.Session` lifecycle. e.g.:: from sqlalchemy import event from sqlalchemy.orm import sessionmaker def my_before_commit(session): print("before commit!") Session = sessionmaker() event.listen(Session, "before_commit", my_before_commit) The :func:`~.event.listen` function will accept :class:`.Session` objects as well as the return result of :class:`~.sessionmaker()` and :class:`~.scoped_session()`. Additionally, it accepts the :class:`.Session` class which will apply listeners to all :class:`.Session` instances globally. :param raw=False: When True, the "target" argument passed to applicable event listener functions that work on individual objects will be the instance's :class:`.InstanceState` management object, rather than the mapped instance itself. .. versionadded:: 1.3.14 :param restore_load_context=False: Applies to the :meth:`.SessionEvents.loaded_as_persistent` event. Restores the loader context of the object when the event hook is complete, so that ongoing eager load operations continue to target the object appropriately. A warning is emitted if the object is moved to a new loader context from within this event if this flag is not set. .. versionadded:: 1.3.14 ZSomeSessionClassOrObjectz-Callable[[SessionEvents, Session, Any], None])rV rC c C s t �| j� | S rD )r� �addrt �rV rJ rJ rK �_lifecycle_eventD s z SessionEvents._lifecycle_eventr r? zUnion[Session, type]r@ c C s� t |t�r8|j}t |t�s8t |t�r.t|t�s8t�d��t |t�rH|j S t |t�rpt|t�r`tS t|t�r�|S n0t |t�r~|S t |d�r�|� � nt j �||�S d S )NzrSession event listen on a scoped_session requires that its creation callable is associated with the Session class.�_no_async_engine_events)rE r Zsession_factoryr rF rU r r" � ArgumentErrorrb �hasattrr� r! �EventsrL rH rJ rJ rK rL J s, ��� zSessionEvents._accept_withF)r� r� rM rN )rO r� r� rQ rC c sX |j tv }|rD�r�rD|j� dddddd�� ��fdd� }|�|�}|jf i |�� d S )Nr r� r rR )�sessionr� rT rQ rC c s` �s|� � }|d u r d S n|}�r(|j}z&� | |g|�R i |��W �rL||_S n �rZ||_0 d S rD r� )r� r� rT rQ rA r� r� rJ rK r� y s � �z#SessionEvents._listen.<locals>.wrap)rB r� r` rd re )rI rO r� r� rQ Zis_instance_eventr� rJ r� rK rf h s � zSessionEvents._listenr. )�orm_execute_staterC c C s dS )aV Intercept statement executions that occur on behalf of an ORM :class:`.Session` object. This event is invoked for all top-level SQL statements invoked from the :meth:`_orm.Session.execute` method, as well as related methods such as :meth:`_orm.Session.scalars` and :meth:`_orm.Session.scalar`. As of SQLAlchemy 1.4, all ORM queries that run through the :meth:`_orm.Session.execute` method as well as related methods :meth:`_orm.Session.scalars`, :meth:`_orm.Session.scalar` etc. will participate in this event. This event hook does **not** apply to the queries that are emitted internally within the ORM flush process, i.e. the process described at :ref:`session_flushing`. .. note:: The :meth:`_orm.SessionEvents.do_orm_execute` event hook is triggered **for ORM statement executions only**, meaning those invoked via the :meth:`_orm.Session.execute` and similar methods on the :class:`_orm.Session` object. It does **not** trigger for statements that are invoked by SQLAlchemy Core only, i.e. statements invoked directly using :meth:`_engine.Connection.execute` or otherwise originating from an :class:`_engine.Engine` object without any :class:`_orm.Session` involved. To intercept **all** SQL executions regardless of whether the Core or ORM APIs are in use, see the event hooks at :class:`.ConnectionEvents`, such as :meth:`.ConnectionEvents.before_execute` and :meth:`.ConnectionEvents.before_cursor_execute`. Also, this event hook does **not** apply to queries that are emitted internally within the ORM flush process, i.e. the process described at :ref:`session_flushing`; to intercept steps within the flush process, see the event hooks described at :ref:`session_persistence_events` as well as :ref:`session_persistence_mapper`. This event is a ``do_`` event, meaning it has the capability to replace the operation that the :meth:`_orm.Session.execute` method normally performs. The intended use for this includes sharding and result-caching schemes which may seek to invoke the same statement across multiple database connections, returning a result that is merged from each of them, or which don't invoke the statement at all, instead returning data from a cache. The hook intends to replace the use of the ``Query._execute_and_instances`` method that could be subclassed prior to SQLAlchemy 1.4. :param orm_execute_state: an instance of :class:`.ORMExecuteState` which contains all information about the current execution, as well as helper functions used to derive other commonly required information. See that object for details. .. seealso:: :ref:`session_execute_events` - top level documentation on how to use :meth:`_orm.SessionEvents.do_orm_execute` :class:`.ORMExecuteState` - the object passed to the :meth:`_orm.SessionEvents.do_orm_execute` event which contains all information about the statement to be invoked. It also provides an interface to extend the current statement, options, and parameters as well as an option that allows programmatic invocation of the statement at any point. :ref:`examples_session_orm_events` - includes examples of using :meth:`_orm.SessionEvents.do_orm_execute` :ref:`examples_caching` - an example of how to integrate Dogpile caching with the ORM :class:`_orm.Session` making use of the :meth:`_orm.SessionEvents.do_orm_execute` event hook. :ref:`examples_sharding` - the Horizontal Sharding example / extension relies upon the :meth:`_orm.SessionEvents.do_orm_execute` event hook to invoke a SQL statement on multiple backends and return a merged result. .. versionadded:: 1.4 NrJ )ro r� rJ rJ rK �do_orm_execute� s z SessionEvents.do_orm_executer r/ )r� � transactionrC c C s dS )az Execute when a new :class:`.SessionTransaction` is created. This event differs from :meth:`~.SessionEvents.after_begin` in that it occurs for each :class:`.SessionTransaction` overall, as opposed to when transactions are begun on individual database connections. It is also invoked for nested transactions and subtransactions, and is always matched by a corresponding :meth:`~.SessionEvents.after_transaction_end` event (assuming normal operation of the :class:`.Session`). :param session: the target :class:`.Session`. :param transaction: the target :class:`.SessionTransaction`. To detect if this is the outermost :class:`.SessionTransaction`, as opposed to a "subtransaction" or a SAVEPOINT, test that the :attr:`.SessionTransaction.parent` attribute is ``None``:: @event.listens_for(session, "after_transaction_create") def after_transaction_create(session, transaction): if transaction.parent is None: ... # work with top-level transaction To detect if the :class:`.SessionTransaction` is a SAVEPOINT, use the :attr:`.SessionTransaction.nested` attribute:: @event.listens_for(session, "after_transaction_create") def after_transaction_create(session, transaction): if transaction.nested: ... # work with SAVEPOINT transaction .. seealso:: :class:`.SessionTransaction` :meth:`~.SessionEvents.after_transaction_end` NrJ �ro r� r� rJ rJ rK �after_transaction_create� s z&SessionEvents.after_transaction_createc C s dS )a� Execute when the span of a :class:`.SessionTransaction` ends. This event differs from :meth:`~.SessionEvents.after_commit` in that it corresponds to all :class:`.SessionTransaction` objects in use, including those for nested transactions and subtransactions, and is always matched by a corresponding :meth:`~.SessionEvents.after_transaction_create` event. :param session: the target :class:`.Session`. :param transaction: the target :class:`.SessionTransaction`. To detect if this is the outermost :class:`.SessionTransaction`, as opposed to a "subtransaction" or a SAVEPOINT, test that the :attr:`.SessionTransaction.parent` attribute is ``None``:: @event.listens_for(session, "after_transaction_create") def after_transaction_end(session, transaction): if transaction.parent is None: ... # work with top-level transaction To detect if the :class:`.SessionTransaction` is a SAVEPOINT, use the :attr:`.SessionTransaction.nested` attribute:: @event.listens_for(session, "after_transaction_create") def after_transaction_end(session, transaction): if transaction.nested: ... # work with SAVEPOINT transaction .. seealso:: :class:`.SessionTransaction` :meth:`~.SessionEvents.after_transaction_create` NrJ r� rJ rJ rK �after_transaction_end s z#SessionEvents.after_transaction_end)r� rC c C s dS )a! Execute before commit is called. .. note:: The :meth:`~.SessionEvents.before_commit` hook is *not* per-flush, that is, the :class:`.Session` can emit SQL to the database many times within the scope of a transaction. For interception of these events, use the :meth:`~.SessionEvents.before_flush`, :meth:`~.SessionEvents.after_flush`, or :meth:`~.SessionEvents.after_flush_postexec` events. :param session: The target :class:`.Session`. .. seealso:: :meth:`~.SessionEvents.after_commit` :meth:`~.SessionEvents.after_begin` :meth:`~.SessionEvents.after_transaction_create` :meth:`~.SessionEvents.after_transaction_end` NrJ �ro r� rJ rJ rK � before_commit7 s zSessionEvents.before_commitc C s dS )aq Execute after a commit has occurred. .. note:: The :meth:`~.SessionEvents.after_commit` hook is *not* per-flush, that is, the :class:`.Session` can emit SQL to the database many times within the scope of a transaction. For interception of these events, use the :meth:`~.SessionEvents.before_flush`, :meth:`~.SessionEvents.after_flush`, or :meth:`~.SessionEvents.after_flush_postexec` events. .. note:: The :class:`.Session` is not in an active transaction when the :meth:`~.SessionEvents.after_commit` event is invoked, and therefore can not emit SQL. To emit SQL corresponding to every transaction, use the :meth:`~.SessionEvents.before_commit` event. :param session: The target :class:`.Session`. .. seealso:: :meth:`~.SessionEvents.before_commit` :meth:`~.SessionEvents.after_begin` :meth:`~.SessionEvents.after_transaction_create` :meth:`~.SessionEvents.after_transaction_end` NrJ r� rJ rJ rK � after_commitS s zSessionEvents.after_commitc C s dS )a� Execute after a real DBAPI rollback has occurred. Note that this event only fires when the *actual* rollback against the database occurs - it does *not* fire each time the :meth:`.Session.rollback` method is called, if the underlying DBAPI transaction has already been rolled back. In many cases, the :class:`.Session` will not be in an "active" state during this event, as the current transaction is not valid. To acquire a :class:`.Session` which is active after the outermost rollback has proceeded, use the :meth:`.SessionEvents.after_soft_rollback` event, checking the :attr:`.Session.is_active` flag. :param session: The target :class:`.Session`. NrJ r� rJ rJ rK �after_rollbackw s z SessionEvents.after_rollback)r� �previous_transactionrC c C s dS )a� Execute after any rollback has occurred, including "soft" rollbacks that don't actually emit at the DBAPI level. This corresponds to both nested and outer rollbacks, i.e. the innermost rollback that calls the DBAPI's rollback() method, as well as the enclosing rollback calls that only pop themselves from the transaction stack. The given :class:`.Session` can be used to invoke SQL and :meth:`.Session.query` operations after an outermost rollback by first checking the :attr:`.Session.is_active` flag:: @event.listens_for(Session, "after_soft_rollback") def do_something(session, previous_transaction): if session.is_active: session.execute(text("select * from some_table")) :param session: The target :class:`.Session`. :param previous_transaction: The :class:`.SessionTransaction` transactional marker object which was just closed. The current :class:`.SessionTransaction` for the given :class:`.Session` is available via the :attr:`.Session.transaction` attribute. NrJ )ro r� r� rJ rJ rK �after_soft_rollback� s z!SessionEvents.after_soft_rollbackr0 zOptional[Sequence[_O]])r� r� � instancesrC c C s dS )aL Execute before flush process has started. :param session: The target :class:`.Session`. :param flush_context: Internal :class:`.UOWTransaction` object which handles the details of the flush. :param instances: Usually ``None``, this is the collection of objects which can be passed to the :meth:`.Session.flush` method (note this usage is deprecated). .. seealso:: :meth:`~.SessionEvents.after_flush` :meth:`~.SessionEvents.after_flush_postexec` :ref:`session_persistence_events` NrJ )ro r� r� r� rJ rJ rK � before_flush� s zSessionEvents.before_flush)r� r� rC c C s dS )a� Execute after flush has completed, but before commit has been called. Note that the session's state is still in pre-flush, i.e. 'new', 'dirty', and 'deleted' lists still show pre-flush state as well as the history settings on instance attributes. .. warning:: This event runs after the :class:`.Session` has emitted SQL to modify the database, but **before** it has altered its internal state to reflect those changes, including that newly inserted objects are placed into the identity map. ORM operations emitted within this event such as loads of related items may produce new identity map entries that will immediately be replaced, sometimes causing confusing results. SQLAlchemy will emit a warning for this condition as of version 1.3.9. :param session: The target :class:`.Session`. :param flush_context: Internal :class:`.UOWTransaction` object which handles the details of the flush. .. seealso:: :meth:`~.SessionEvents.before_flush` :meth:`~.SessionEvents.after_flush_postexec` :ref:`session_persistence_events` NrJ �ro r� r� rJ rJ rK � after_flush� s zSessionEvents.after_flushc C s dS )a� Execute after flush has completed, and after the post-exec state occurs. This will be when the 'new', 'dirty', and 'deleted' lists are in their final state. An actual commit() may or may not have occurred, depending on whether or not the flush started its own transaction or participated in a larger transaction. :param session: The target :class:`.Session`. :param flush_context: Internal :class:`.UOWTransaction` object which handles the details of the flush. .. seealso:: :meth:`~.SessionEvents.before_flush` :meth:`~.SessionEvents.after_flush` :ref:`session_persistence_events` NrJ r� rJ rJ rK �after_flush_postexec� s z"SessionEvents.after_flush_postexecr1 )r� r� r� rC c C s dS )ap Execute after a transaction is begun on a connection. .. note:: This event is called within the process of the :class:`_orm.Session` modifying its own internal state. To invoke SQL operations within this hook, use the :class:`_engine.Connection` provided to the event; do not run SQL operations using the :class:`_orm.Session` directly. :param session: The target :class:`.Session`. :param transaction: The :class:`.SessionTransaction`. :param connection: The :class:`_engine.Connection` object which will be used for SQL statements. .. seealso:: :meth:`~.SessionEvents.before_commit` :meth:`~.SessionEvents.after_commit` :meth:`~.SessionEvents.after_transaction_create` :meth:`~.SessionEvents.after_transaction_end` NrJ )ro r� r� r� rJ rJ rK � after_begin� s zSessionEvents.after_beginr* )r� �instancerC c C s dS )a Execute before an instance is attached to a session. This is called before an add, delete or merge causes the object to be part of the session. .. seealso:: :meth:`~.SessionEvents.after_attach` :ref:`session_lifecycle_events` NrJ �ro r� r rJ rJ rK � before_attach s zSessionEvents.before_attachc C s dS )a� Execute after an instance is attached to a session. This is called after an add, delete or merge. .. note:: As of 0.8, this event fires off *after* the item has been fully associated with the session, which is different than previous releases. For event handlers that require the object not yet be part of session state (such as handlers which may autoflush while the target object is not yet complete) consider the new :meth:`.before_attach` event. .. seealso:: :meth:`~.SessionEvents.before_attach` :ref:`session_lifecycle_events` NrJ r rJ rJ rK � after_attach( s zSessionEvents.after_attachz0.9)r� �queryZ query_context�resultc C s | j | jd | jfS rD �r� r r )�update_contextrJ rJ rK �<lambda>D s �zSessionEvents.<lambda>)r rC c C s dS )aU Event for after the legacy :meth:`_orm.Query.update` method has been called. .. legacy:: The :meth:`_orm.SessionEvents.after_bulk_update` method is a legacy event hook as of SQLAlchemy 2.0. The event **does not participate** in :term:`2.0 style` invocations using :func:`_dml.update` documented at :ref:`orm_queryguide_update_delete_where`. For 2.0 style use, the :meth:`_orm.SessionEvents.do_orm_execute` hook will intercept these calls. :param update_context: an "update context" object which contains details about the update, including these attributes: * ``session`` - the :class:`.Session` involved * ``query`` -the :class:`_query.Query` object that this update operation was called upon. * ``values`` The "values" dictionary that was passed to :meth:`_query.Query.update`. * ``result`` the :class:`_engine.CursorResult` returned as a result of the bulk UPDATE operation. .. versionchanged:: 1.4 the update_context no longer has a ``QueryContext`` object associated with it. .. seealso:: :meth:`.QueryEvents.before_compile_update` :meth:`.SessionEvents.after_bulk_delete` NrJ )ro r rJ rJ rK �after_bulk_updateA s z SessionEvents.after_bulk_updatec C s | j | jd | jfS rD r )�delete_contextrJ rJ rK r r s �)r rC c C s dS )a� Event for after the legacy :meth:`_orm.Query.delete` method has been called. .. legacy:: The :meth:`_orm.SessionEvents.after_bulk_delete` method is a legacy event hook as of SQLAlchemy 2.0. The event **does not participate** in :term:`2.0 style` invocations using :func:`_dml.delete` documented at :ref:`orm_queryguide_update_delete_where`. For 2.0 style use, the :meth:`_orm.SessionEvents.do_orm_execute` hook will intercept these calls. :param delete_context: a "delete context" object which contains details about the update, including these attributes: * ``session`` - the :class:`.Session` involved * ``query`` -the :class:`_query.Query` object that this update operation was called upon. * ``result`` the :class:`_engine.CursorResult` returned as a result of the bulk DELETE operation. .. versionchanged:: 1.4 the update_context no longer has a ``QueryContext`` object associated with it. .. seealso:: :meth:`.QueryEvents.before_compile_delete` :meth:`.SessionEvents.after_bulk_update` NrJ )ro r rJ rJ rK �after_bulk_deleteo s z SessionEvents.after_bulk_deletec C s dS )a� Intercept the "transient to pending" transition for a specific object. This event is a specialization of the :meth:`.SessionEvents.after_attach` event which is only invoked for this specific transition. It is invoked typically during the :meth:`.Session.add` call. :param session: target :class:`.Session` :param instance: the ORM-mapped instance being operated upon. .. seealso:: :ref:`session_lifecycle_events` NrJ r rJ rJ rK �transient_to_pending� s z"SessionEvents.transient_to_pendingc C s dS )a0 Intercept the "pending to transient" transition for a specific object. This less common transition occurs when an pending object that has not been flushed is evicted from the session; this can occur when the :meth:`.Session.rollback` method rolls back the transaction, or when the :meth:`.Session.expunge` method is used. :param session: target :class:`.Session` :param instance: the ORM-mapped instance being operated upon. .. seealso:: :ref:`session_lifecycle_events` NrJ r rJ rJ rK �pending_to_transient� s z"SessionEvents.pending_to_transientc C s dS )a� Intercept the "persistent to transient" transition for a specific object. This less common transition occurs when an pending object that has has been flushed is evicted from the session; this can occur when the :meth:`.Session.rollback` method rolls back the transaction. :param session: target :class:`.Session` :param instance: the ORM-mapped instance being operated upon. .. seealso:: :ref:`session_lifecycle_events` NrJ r rJ rJ rK �persistent_to_transient� s z%SessionEvents.persistent_to_transientc C s dS )aN Intercept the "pending to persistent"" transition for a specific object. This event is invoked within the flush process, and is similar to scanning the :attr:`.Session.new` collection within the :meth:`.SessionEvents.after_flush` event. However, in this case the object has already been moved to the persistent state when the event is called. :param session: target :class:`.Session` :param instance: the ORM-mapped instance being operated upon. .. seealso:: :ref:`session_lifecycle_events` NrJ r rJ rJ rK �pending_to_persistent� s z#SessionEvents.pending_to_persistentc C s dS )a: Intercept the "detached to persistent" transition for a specific object. This event is a specialization of the :meth:`.SessionEvents.after_attach` event which is only invoked for this specific transition. It is invoked typically during the :meth:`.Session.add` call, as well as during the :meth:`.Session.delete` call if the object was not previously associated with the :class:`.Session` (note that an object marked as "deleted" remains in the "persistent" state until the flush proceeds). .. note:: If the object becomes persistent as part of a call to :meth:`.Session.delete`, the object is **not** yet marked as deleted when this event is called. To detect deleted objects, check the ``deleted`` flag sent to the :meth:`.SessionEvents.persistent_to_detached` to event after the flush proceeds, or check the :attr:`.Session.deleted` collection within the :meth:`.SessionEvents.before_flush` event if deleted objects need to be intercepted before the flush. :param session: target :class:`.Session` :param instance: the ORM-mapped instance being operated upon. .. seealso:: :ref:`session_lifecycle_events` NrJ r rJ rJ rK �detached_to_persistent� s z$SessionEvents.detached_to_persistentc C s dS )a� Intercept the "loaded as persistent" transition for a specific object. This event is invoked within the ORM loading process, and is invoked very similarly to the :meth:`.InstanceEvents.load` event. However, the event here is linkable to a :class:`.Session` class or instance, rather than to a mapper or class hierarchy, and integrates with the other session lifecycle events smoothly. The object is guaranteed to be present in the session's identity map when this event is called. .. note:: This event is invoked within the loader process before eager loaders may have been completed, and the object's state may not be complete. Additionally, invoking row-level refresh operations on the object will place the object into a new loader context, interfering with the existing load context. See the note on :meth:`.InstanceEvents.load` for background on making use of the :paramref:`.SessionEvents.restore_load_context` parameter, which works in the same manner as that of :paramref:`.InstanceEvents.restore_load_context`, in order to resolve this scenario. :param session: target :class:`.Session` :param instance: the ORM-mapped instance being operated upon. .. seealso:: :ref:`session_lifecycle_events` NrJ r rJ rJ rK �loaded_as_persistent s z"SessionEvents.loaded_as_persistentc C s dS )a� Intercept the "persistent to deleted" transition for a specific object. This event is invoked when a persistent object's identity is deleted from the database within a flush, however the object still remains associated with the :class:`.Session` until the transaction completes. If the transaction is rolled back, the object moves again to the persistent state, and the :meth:`.SessionEvents.deleted_to_persistent` event is called. If the transaction is committed, the object becomes detached, which will emit the :meth:`.SessionEvents.deleted_to_detached` event. Note that while the :meth:`.Session.delete` method is the primary public interface to mark an object as deleted, many objects get deleted due to cascade rules, which are not always determined until flush time. Therefore, there's no way to catch every object that will be deleted until the flush has proceeded. the :meth:`.SessionEvents.persistent_to_deleted` event is therefore invoked at the end of a flush. .. seealso:: :ref:`session_lifecycle_events` NrJ r rJ rJ rK �persistent_to_deleted0 s z#SessionEvents.persistent_to_deletedc C s dS )a� Intercept the "deleted to persistent" transition for a specific object. This transition occurs only when an object that's been deleted successfully in a flush is restored due to a call to :meth:`.Session.rollback`. The event is not called under any other circumstances. .. seealso:: :ref:`session_lifecycle_events` NrJ r rJ rJ rK �deleted_to_persistentO s z#SessionEvents.deleted_to_persistentc C s dS )a� Intercept the "deleted to detached" transition for a specific object. This event is invoked when a deleted object is evicted from the session. The typical case when this occurs is when the transaction for a :class:`.Session` in which the object was deleted is committed; the object moves from the deleted state to the detached state. It is also invoked for objects that were deleted in a flush when the :meth:`.Session.expunge_all` or :meth:`.Session.close` events are called, as well as if the object is individually expunged from its deleted state via :meth:`.Session.expunge`. .. seealso:: :ref:`session_lifecycle_events` NrJ r rJ rJ rK �deleted_to_detached_ s z!SessionEvents.deleted_to_detachedc C s dS )aD Intercept the "persistent to detached" transition for a specific object. This event is invoked when a persistent object is evicted from the session. There are many conditions that cause this to happen, including: * using a method such as :meth:`.Session.expunge` or :meth:`.Session.close` * Calling the :meth:`.Session.rollback` method, when the object was part of an INSERT statement for that session's transaction :param session: target :class:`.Session` :param instance: the ORM-mapped instance being operated upon. :param deleted: boolean. If True, indicates this object moved to the detached state because it was marked as deleted and flushed. .. seealso:: :ref:`session_lifecycle_events` NrJ r rJ rJ rK �persistent_to_detachedu s z$SessionEvents.persistent_to_detachedN)&rt ru rv rw rx r ry r� rz rL rf r� r� r� r� r� r� r� r� r� r� r� r r r! Z_legacy_signaturer r r r r r r r r r r r rJ rJ rJ rK r� sr * � *Q+( $ ! � $� ""! r� c @ s8 e Zd ZdZdZeZedddd�dd��Ze d d d d �d d ��Z e d;dddddddd�dd��Z e d�dddddd�d d �Z e d�dddddd�d d �Zd d!�dd"dd#dd$�d%d&�Ze d�dddddd�d'd(�Zdddddd)�d*d+�Zddd,dd-�d.d/�Zdd0d1dd2�d3d4�Zdd5d1dd2�d6d7�Zdddd8�d9d:�Zd S )<�AttributeEventsa3 Define events for object attributes. These are typically defined on the class-bound descriptor for the target class. For example, to register a listener that will receive the :meth:`_orm.AttributeEvents.append` event:: from sqlalchemy import event @event.listens_for(MyClass.collection, "append", propagate=True) def my_append_listener(target, value, initiator): print("received append event for target: %s" % target) Listeners have the option to return a possibly modified version of the value, when the :paramref:`.AttributeEvents.retval` flag is passed to :func:`.event.listen` or :func:`.event.listens_for`, such as below, illustrated using the :meth:`_orm.AttributeEvents.set` event:: def validate_phone(target, value, oldvalue, initiator): "Strip non-numeric characters from a phone number" return re.sub(r"\D", "", value) # setup listener on UserContact.phone attribute, instructing # it to use the return value listen(UserContact.phone, "set", validate_phone, retval=True) A validation function like the above can also raise an exception such as :exc:`ValueError` to halt the operation. The :paramref:`.AttributeEvents.propagate` flag is also important when applying listeners to mapped classes that also have mapped subclasses, as when using mapper inheritance patterns:: @event.listens_for(MySuperClass.attr, "set", propagate=True) def receive_set(target, value, initiator): print("value set: %s" % target) The full list of modifiers available to the :func:`.event.listen` and :func:`.event.listens_for` functions are below. :param active_history=False: When True, indicates that the "set" event would like to receive the "old" value being replaced unconditionally, even if this requires firing off database loads. Note that ``active_history`` can also be set directly via :func:`.column_property` and :func:`_orm.relationship`. :param propagate=False: When True, the listener function will be established not just for the class attribute given, but for attributes of the same name on all current subclasses of that class, as well as all future subclasses of that class, using an additional listener that listens for instrumentation events. :param raw=False: When True, the "target" argument to the event will be the :class:`.InstanceState` management object, rather than the mapped instance itself. :param retval=False: when True, the user-defined event listening must return the "value" argument from the function. This gives the listening function the opportunity to change the value that is ultimately used for a "set" or "append" event. zSomeClass.some_attributez Type[_HasEventsDispatch[Any]]zType[_Dispatch[Any]]z_Dispatch[Any])rI � dispatch_clsrC c C s t j�| |�}d|_|S )NF)r! r� � _set_dispatch�_active_history)rI r r\ rJ rJ rK r � s z AttributeEvents._set_dispatchz=Union[QueryableAttribute[Any], Type[QueryableAttribute[Any]]]r? r@ c C s$ t |tj�r t|jj|j�S |S d S rD )rE r ZMapperPropertyr[ �parentrb r^ rH rJ rJ rK rL � s z AttributeEvents._accept_withFz"_EventKey[QueryableAttribute[Any]]rM rN )rO �active_historyr� r� rP � include_keyrC c s� |j |j }� |rd|j_�r&�r&�sNddddd�� ���fdd� }|�|�}|j|d� |r�t�|j�} | � d�D ].} |� | |j �jdd� |rtd| |j j_qtd S )NTr� r )rA rT rQ rC c s� �s | � � } �sR|r |d }nd }�r>� | g|�R i |�� n� | g|�R � |S �rl� | g|�R i |��S � | g|�R � S d S �Nr )r� )rA rT rQ �value�rV r r� r� rJ rK r� s z%AttributeEvents._listen.<locals>.wrapr� ) r_ r` r\ r rd re r Zmanager_of_classrb r� rc r^ ) rI rO r r� r� rP r rA r� r� r� rJ r rK rf � s �zAttributeEvents._listen)r^ r* r+ r, r- z Optional[_T])rA r � initiatorr^ rC c C s dS )aI Receive a collection append event. The append event is invoked for each element as it is appended to the collection. This occurs for single-item appends as well as for a "bulk replace" operation. :param target: the object instance receiving the event. If the listener is registered with ``raw=True``, this will be the :class:`.InstanceState` object. :param value: the value being appended. If this listener is registered with ``retval=True``, the listener function must return this value, or a new value which replaces it. :param initiator: An instance of :class:`.attributes.Event` representing the initiation of the event. May be modified from its original value by backref handlers in order to control chained event propagation, as well as be inspected for information about the source of the event. :param key: When the event is established using the :paramref:`.AttributeEvents.include_key` parameter set to True, this will be the key used in the operation, such as ``collection[some_key_or_index] = value``. The parameter is not passed to the event at all if the the :paramref:`.AttributeEvents.include_key` was not used to set up the event; this is to allow backwards compatibility with existing event handlers that don't include the ``key`` parameter. .. versionadded:: 2.0 :return: if the event was registered with ``retval=True``, the given value, or a new effective value, should be returned. .. seealso:: :class:`.AttributeEvents` - background on listener options such as propagation to subclasses. :meth:`.AttributeEvents.bulk_replace` NrJ �ro rA r r r^ rJ rJ rK �append# s zAttributeEvents.appendc C s dS )af Receive a collection append event where the collection was not actually mutated. This event differs from :meth:`_orm.AttributeEvents.append` in that it is fired off for de-duplicating collections such as sets and dictionaries, when the object already exists in the target collection. The event does not have a return value and the identity of the given object cannot be changed. The event is used for cascading objects into a :class:`_orm.Session` when the collection has already been mutated via a backref event. :param target: the object instance receiving the event. If the listener is registered with ``raw=True``, this will be the :class:`.InstanceState` object. :param value: the value that would be appended if the object did not already exist in the collection. :param initiator: An instance of :class:`.attributes.Event` representing the initiation of the event. May be modified from its original value by backref handlers in order to control chained event propagation, as well as be inspected for information about the source of the event. :param key: When the event is established using the :paramref:`.AttributeEvents.include_key` parameter set to True, this will be the key used in the operation, such as ``collection[some_key_or_index] = value``. The parameter is not passed to the event at all if the the :paramref:`.AttributeEvents.include_key` was not used to set up the event; this is to allow backwards compatibility with existing event handlers that don't include the ``key`` parameter. .. versionadded:: 2.0 :return: No return value is defined for this event. .. versionadded:: 1.4.15 NrJ r! rJ rJ rK �append_wo_mutationV s z"AttributeEvents.append_wo_mutationN)�keysz Iterable[_T]z"Optional[Iterable[EventConstants]])rA r� r r$ rC c C s dS )aR Receive a collection 'bulk replace' event. This event is invoked for a sequence of values as they are incoming to a bulk collection set operation, which can be modified in place before the values are treated as ORM objects. This is an "early hook" that runs before the bulk replace routine attempts to reconcile which objects are already present in the collection and which are being removed by the net replace operation. It is typical that this method be combined with use of the :meth:`.AttributeEvents.append` event. When using both of these events, note that a bulk replace operation will invoke the :meth:`.AttributeEvents.append` event for all new items, even after :meth:`.AttributeEvents.bulk_replace` has been invoked for the collection as a whole. In order to determine if an :meth:`.AttributeEvents.append` event is part of a bulk replace, use the symbol :attr:`~.attributes.OP_BULK_REPLACE` to test the incoming initiator:: from sqlalchemy.orm.attributes import OP_BULK_REPLACE @event.listens_for(SomeObject.collection, "bulk_replace") def process_collection(target, values, initiator): values[:] = [_make_value(value) for value in values] @event.listens_for(SomeObject.collection, "append", retval=True) def process_collection(target, value, initiator): # make sure bulk_replace didn't already do it if initiator is None or initiator.op is not OP_BULK_REPLACE: return _make_value(value) else: return value .. versionadded:: 1.2 :param target: the object instance receiving the event. If the listener is registered with ``raw=True``, this will be the :class:`.InstanceState` object. :param value: a sequence (e.g. a list) of the values being set. The handler can modify this list in place. :param initiator: An instance of :class:`.attributes.Event` representing the initiation of the event. :param keys: When the event is established using the :paramref:`.AttributeEvents.include_key` parameter set to True, this will be the sequence of keys used in the operation, typically only for a dictionary update. The parameter is not passed to the event at all if the the :paramref:`.AttributeEvents.include_key` was not used to set up the event; this is to allow backwards compatibility with existing event handlers that don't include the ``key`` parameter. .. versionadded:: 2.0 .. seealso:: :class:`.AttributeEvents` - background on listener options such as propagation to subclasses. NrJ )ro rA r� r r$ rJ rJ rK � bulk_replace� s z AttributeEvents.bulk_replacec C s dS )a Receive a collection remove event. :param target: the object instance receiving the event. If the listener is registered with ``raw=True``, this will be the :class:`.InstanceState` object. :param value: the value being removed. :param initiator: An instance of :class:`.attributes.Event` representing the initiation of the event. May be modified from its original value by backref handlers in order to control chained event propagation. :param key: When the event is established using the :paramref:`.AttributeEvents.include_key` parameter set to True, this will be the key used in the operation, such as ``del collection[some_key_or_index]``. The parameter is not passed to the event at all if the the :paramref:`.AttributeEvents.include_key` was not used to set up the event; this is to allow backwards compatibility with existing event handlers that don't include the ``key`` parameter. .. versionadded:: 2.0 :return: No return value is defined for this event. .. seealso:: :class:`.AttributeEvents` - background on listener options such as propagation to subclasses. NrJ r! rJ rJ rK r] � s zAttributeEvents.remove)rA r �oldvaluer rC c C s dS )a Receive a scalar set event. :param target: the object instance receiving the event. If the listener is registered with ``raw=True``, this will be the :class:`.InstanceState` object. :param value: the value being set. If this listener is registered with ``retval=True``, the listener function must return this value, or a new value which replaces it. :param oldvalue: the previous value being replaced. This may also be the symbol ``NEVER_SET`` or ``NO_VALUE``. If the listener is registered with ``active_history=True``, the previous value of the attribute will be loaded from the database if the existing value is currently unloaded or expired. :param initiator: An instance of :class:`.attributes.Event` representing the initiation of the event. May be modified from its original value by backref handlers in order to control chained event propagation. :return: if the event was registered with ``retval=True``, the given value, or a new effective value, should be returned. .. seealso:: :class:`.AttributeEvents` - background on listener options such as propagation to subclasses. NrJ )ro rA r r& r rJ rJ rK �set� s zAttributeEvents.setzDict[Any, Any])rA r �dict_rC c C s dS )a� Receive a scalar "init" event. This event is invoked when an uninitialized, unpersisted scalar attribute is accessed, e.g. read:: x = my_object.some_attribute The ORM's default behavior when this occurs for an un-initialized attribute is to return the value ``None``; note this differs from Python's usual behavior of raising ``AttributeError``. The event here can be used to customize what value is actually returned, with the assumption that the event listener would be mirroring a default generator that is configured on the Core :class:`_schema.Column` object as well. Since a default generator on a :class:`_schema.Column` might also produce a changing value such as a timestamp, the :meth:`.AttributeEvents.init_scalar` event handler can also be used to **set** the newly returned value, so that a Core-level default generation function effectively fires off only once, but at the moment the attribute is accessed on the non-persisted object. Normally, no change to the object's state is made when an uninitialized attribute is accessed (much older SQLAlchemy versions did in fact change the object's state). If a default generator on a column returned a particular constant, a handler might be used as follows:: SOME_CONSTANT = 3.1415926 class MyClass(Base): # ... some_attribute = Column(Numeric, default=SOME_CONSTANT) @event.listens_for( MyClass.some_attribute, "init_scalar", retval=True, propagate=True ) def _init_some_attribute(target, dict_, value): dict_["some_attribute"] = SOME_CONSTANT return SOME_CONSTANT Above, we initialize the attribute ``MyClass.some_attribute`` to the value of ``SOME_CONSTANT``. The above code includes the following features: * By setting the value ``SOME_CONSTANT`` in the given ``dict_``, we indicate that this value is to be persisted to the database. This supersedes the use of ``SOME_CONSTANT`` in the default generator for the :class:`_schema.Column`. The ``active_column_defaults.py`` example given at :ref:`examples_instrumentation` illustrates using the same approach for a changing default, e.g. a timestamp generator. In this particular example, it is not strictly necessary to do this since ``SOME_CONSTANT`` would be part of the INSERT statement in either case. * By establishing the ``retval=True`` flag, the value we return from the function will be returned by the attribute getter. Without this flag, the event is assumed to be a passive observer and the return value of our function is ignored. * The ``propagate=True`` flag is significant if the mapped class includes inheriting subclasses, which would also make use of this event listener. Without this flag, an inheriting subclass will not use our event handler. In the above example, the attribute set event :meth:`.AttributeEvents.set` as well as the related validation feature provided by :obj:`_orm.validates` is **not** invoked when we apply our value to the given ``dict_``. To have these events to invoke in response to our newly generated value, apply the value to the given object as a normal attribute set operation:: SOME_CONSTANT = 3.1415926 @event.listens_for( MyClass.some_attribute, "init_scalar", retval=True, propagate=True ) def _init_some_attribute(target, dict_, value): # will also fire off attribute set events target.some_attribute = SOME_CONSTANT return SOME_CONSTANT When multiple listeners are set up, the generation of the value is "chained" from one listener to the next by passing the value returned by the previous listener that specifies ``retval=True`` as the ``value`` argument of the next listener. :param target: the object instance receiving the event. If the listener is registered with ``raw=True``, this will be the :class:`.InstanceState` object. :param value: the value that is to be returned before this event listener were invoked. This value begins as the value ``None``, however will be the return value of the previous event handler function if multiple listeners are present. :param dict\_: the attribute dictionary of this mapped object. This is normally the ``__dict__`` of the object, but in all cases represents the destination that the attribute system uses to get at the actual value of this attribute. Placing the value in this dictionary has the effect that the value will be used in the INSERT statement generated by the unit of work. .. seealso:: :meth:`.AttributeEvents.init_collection` - collection version of this event :class:`.AttributeEvents` - background on listener options such as propagation to subclasses. :ref:`examples_instrumentation` - see the ``active_column_defaults.py`` example. NrJ )ro rA r r( rJ rJ rK � init_scalar s zAttributeEvents.init_scalarzType[Collection[Any]]r5 )rA r� �collection_adapterrC c C s dS )aQ Receive a 'collection init' event. This event is triggered for a collection-based attribute, when the initial "empty collection" is first generated for a blank attribute, as well as for when the collection is replaced with a new one, such as via a set event. E.g., given that ``User.addresses`` is a relationship-based collection, the event is triggered here:: u1 = User() u1.addresses.append(a1) # <- new collection and also during replace operations:: u1.addresses = [a2, a3] # <- new collection :param target: the object instance receiving the event. If the listener is registered with ``raw=True``, this will be the :class:`.InstanceState` object. :param collection: the new collection. This will always be generated from what was specified as :paramref:`_orm.relationship.collection_class`, and will always be empty. :param collection_adapter: the :class:`.CollectionAdapter` that will mediate internal access to the collection. .. seealso:: :class:`.AttributeEvents` - background on listener options such as propagation to subclasses. :meth:`.AttributeEvents.init_scalar` - "scalar" version of this event. NrJ �ro rA r� r* rJ rJ rK �init_collection� s z AttributeEvents.init_collectionzCollection[Any]c C s dS )a� Receive a 'collection dispose' event. This event is triggered for a collection-based attribute when a collection is replaced, that is:: u1.addresses.append(a1) u1.addresses = [a2, a3] # <- old collection is disposed The old collection received will contain its previous contents. .. versionchanged:: 1.2 The collection passed to :meth:`.AttributeEvents.dispose_collection` will now have its contents before the dispose intact; previously, the collection would be empty. .. seealso:: :class:`.AttributeEvents` - background on listener options such as propagation to subclasses. NrJ r+ rJ rJ rK �dispose_collection� s z"AttributeEvents.dispose_collection)rA r rC c C s dS )a� Receive a 'modified' event. This event is triggered when the :func:`.attributes.flag_modified` function is used to trigger a modify event on an attribute without any specific value being set. .. versionadded:: 1.2 :param target: the object instance receiving the event. If the listener is registered with ``raw=True``, this will be the :class:`.InstanceState` object. :param initiator: An instance of :class:`.attributes.Event` representing the initiation of the event. .. seealso:: :class:`.AttributeEvents` - background on listener options such as propagation to subclasses. NrJ )ro rA r rJ rJ rK �modified� s zAttributeEvents.modified)FFFFF)rt ru rv rw rx r ry � staticmethodr rz rL rf r r" r# r% r] r' r) r, r- r. rJ rJ rJ rK r � s6 E � 7�9�7�N�)!}+ r c @ sh e Zd ZdZdZeZddd�dd�Zdddd �d d �Zdd dd �dd�Z e ddddddd�dd��Z dS )� QueryEventsa3 Represent events within the construction of a :class:`_query.Query` object. .. legacy:: The :class:`_orm.QueryEvents` event methods are legacy as of SQLAlchemy 2.0, and only apply to direct use of the :class:`_orm.Query` object. They are not used for :term:`2.0 style` statements. For events to intercept and modify 2.0 style ORM use, use the :meth:`_orm.SessionEvents.do_orm_execute` hook. The :class:`_orm.QueryEvents` hooks are now superseded by the :meth:`_orm.SessionEvents.do_orm_execute` event hook. Z SomeQueryz Query[Any]rN )r rC c C s dS )a# Receive the :class:`_query.Query` object before it is composed into a core :class:`_expression.Select` object. .. deprecated:: 1.4 The :meth:`_orm.QueryEvents.before_compile` event is superseded by the much more capable :meth:`_orm.SessionEvents.do_orm_execute` hook. In version 1.4, the :meth:`_orm.QueryEvents.before_compile` event is **no longer used** for ORM-level attribute loads, such as loads of deferred or expired attributes as well as relationship loaders. See the new examples in :ref:`examples_session_orm_events` which illustrate new ways of intercepting and modifying ORM queries for the most common purpose of adding arbitrary filter criteria. This event is intended to allow changes to the query given:: @event.listens_for(Query, "before_compile", retval=True) def no_deleted(query): for desc in query.column_descriptions: if desc["type"] is User: entity = desc["entity"] query = query.filter(entity.deleted == False) return query The event should normally be listened with the ``retval=True`` parameter set, so that the modified query may be returned. The :meth:`.QueryEvents.before_compile` event by default will disallow "baked" queries from caching a query, if the event hook returns a new :class:`_query.Query` object. This affects both direct use of the baked query extension as well as its operation within lazy loaders and eager loaders for relationships. In order to re-establish the query being cached, apply the event adding the ``bake_ok`` flag:: @event.listens_for(Query, "before_compile", retval=True, bake_ok=True) def my_event(query): for desc in query.column_descriptions: if desc["type"] is User: entity = desc["entity"] query = query.filter(entity.deleted == False) return query When ``bake_ok`` is set to True, the event hook will only be invoked once, and not called for subsequent invocations of a particular query that is being cached. .. versionadded:: 1.3.11 - added the "bake_ok" flag to the :meth:`.QueryEvents.before_compile` event and disallowed caching via the "baked" extension from occurring for event handlers that return a new :class:`_query.Query` object if this flag is not set. .. seealso:: :meth:`.QueryEvents.before_compile_update` :meth:`.QueryEvents.before_compile_delete` :ref:`baked_with_before_compile` NrJ )ro r rJ rJ rK �before_compile s zQueryEvents.before_compiler )r r rC c C s dS )a� Allow modifications to the :class:`_query.Query` object within :meth:`_query.Query.update`. .. deprecated:: 1.4 The :meth:`_orm.QueryEvents.before_compile_update` event is superseded by the much more capable :meth:`_orm.SessionEvents.do_orm_execute` hook. Like the :meth:`.QueryEvents.before_compile` event, if the event is to be used to alter the :class:`_query.Query` object, it should be configured with ``retval=True``, and the modified :class:`_query.Query` object returned, as in :: @event.listens_for(Query, "before_compile_update", retval=True) def no_deleted(query, update_context): for desc in query.column_descriptions: if desc["type"] is User: entity = desc["entity"] query = query.filter(entity.deleted == False) update_context.values["timestamp"] = datetime.datetime.now( datetime.UTC ) return query The ``.values`` dictionary of the "update context" object can also be modified in place as illustrated above. :param query: a :class:`_query.Query` instance; this is also the ``.query`` attribute of the given "update context" object. :param update_context: an "update context" object which is the same kind of object as described in :paramref:`.QueryEvents.after_bulk_update.update_context`. The object has a ``.values`` attribute in an UPDATE context which is the dictionary of parameters passed to :meth:`_query.Query.update`. This dictionary can be modified to alter the VALUES clause of the resulting UPDATE statement. .. versionadded:: 1.2.17 .. seealso:: :meth:`.QueryEvents.before_compile` :meth:`.QueryEvents.before_compile_delete` NrJ )ro r r rJ rJ rK �before_compile_updateJ s z!QueryEvents.before_compile_updater )r r rC c C s dS )a] Allow modifications to the :class:`_query.Query` object within :meth:`_query.Query.delete`. .. deprecated:: 1.4 The :meth:`_orm.QueryEvents.before_compile_delete` event is superseded by the much more capable :meth:`_orm.SessionEvents.do_orm_execute` hook. Like the :meth:`.QueryEvents.before_compile` event, this event should be configured with ``retval=True``, and the modified :class:`_query.Query` object returned, as in :: @event.listens_for(Query, "before_compile_delete", retval=True) def no_deleted(query, delete_context): for desc in query.column_descriptions: if desc["type"] is User: entity = desc["entity"] query = query.filter(entity.deleted == False) return query :param query: a :class:`_query.Query` instance; this is also the ``.query`` attribute of the given "delete context" object. :param delete_context: a "delete context" object which is the same kind of object as described in :paramref:`.QueryEvents.after_bulk_delete.delete_context`. .. versionadded:: 1.2.17 .. seealso:: :meth:`.QueryEvents.before_compile` :meth:`.QueryEvents.before_compile_update` NrJ )ro r r rJ rJ rK �before_compile_delete� s z!QueryEvents.before_compile_deleteFr� rM r )rO r� �bake_okrQ rC c sh |j � �s.dddd�� �fdd� }|�|�}n dddd�� fdd� }|�|�}||_|jf i |�� d S )Nr r� c s0 �s | d }� | i |�� |S � | i |��S d S r rJ )rT rQ r �rV r� rJ rK r� � s z!QueryEvents._listen.<locals>.wrapc s � | i |��S rD rJ r� r� rJ rK r� � s )r` rd Z_bake_okre )rI rO r� r4 rQ r� rJ r5 rK rf � s zQueryEvents._listenN)FF) rt ru rv rw rx r ry r1 r2 r3 rz rf rJ rJ rJ rK r0 � s A6) �r0 )\rw � __future__r �typingr r r r r r r r r r r r r ra � r r r � attributesr �baser r r r r r r r Zscopingr r� r r r! r" r# r$ Zevent.registryr% Z util.compatr& r' Z_typingr( r) r* r+ r, r- r. r/ Z unitofworkr0 Zenginer1 Z event.baser2 r3 r4 Zorm.collectionsr5 Z orm.contextr6 Z orm.decl_apir7 r8 Z orm.mapperr9 Z orm.stater: r; r= r� r> rG r� Z RefCollectionr� r� r� r� r' r� r� r� r r0 rJ rJ rJ rK �<module> s� s 5_ f sqlalchemy/orm/__pycache__/unitofwork.cpython-39.pyc 0000644 00000051453 15125143220 0016556 0 ustar 00 a ��Jh�i � @ s� d Z ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ dd l m Z dd l m Z dd l m Z d d l mZ d d l m Z d dl mZ er�ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ dd� Z G dd� d�Z G dd� d�Z G dd � d e �Z G d d � d �Z G d d � d e e �Z!G d!d"� d"e �Z"G d#d$� d$e �Z#G d%d&� d&e �Z$G d'd(� d(e �Z%G d)d*� d*e �Z&G d+d,� d,e �Z'd-S ).z�The internals for the unit of work system. The session's flush() process passes objects to a contextual object here, which assembles flush tasks based on mappers and their properties, organizes them in order of dependency, and executes. � )� annotations)�Any)�Dict)�Optional)�Set)� TYPE_CHECKING� �� attributes)�exc)�util� )�event)� topological)�DependencyProcessor)�MapperProperty)�Mapper)�Session)�SessionTransaction)� InstanceStatec s� |j � � fdd�}� fdd�}� fdd�}tj| d|ddd � tj| d |dddd � tj| d |dddd � tj| d |dddd � dS )z\Establish event listeners on object attributes which handle cascade-on-set/append. c sh |d u r d S | j }|rd|jr&|�d� | jjj� }t�|�}|jj rd� |j krd|� |�sd|� |� |S )Nzcollection append) �session�_warn_on_events�_flush_warning�manager�mapper�_propsr �instance_state�_cascade� save_update�key�_contains_state�_save_or_update_state��state�item� initiator�kw�sess�propZ item_state�r � �N/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/unitofwork.py�append2 s ��� z$track_cascade_events.<locals>.appendc s� |d u r d S | j }| jjj� }|r>|jr>|�|jr8dnd� |d ur�|tjur�|tj ur�|j j r�t� |�}|j� |�r�|r�||jv r�|�|� nd|_d S )Nzcollection removezrelated attribute deleteT)r r r r r r Zuselistr � NEVER_SET�PASSIVE_NO_RESULTr � delete_orphanr � _is_orphan�_new�expungeZ _orphaned_outside_of_sessionr" r) r* r+ �removeI s. ������ z$track_cascade_events.<locals>.removec s� ||u r |S | j }|r�|jr&|�d� | jjj� }|d urlt�|�}|jj rl� |j krl|� |�sl|� |� |d ur�|tj ur�|tjur�|jjr�t�|�}||jv r�|j�|�r�|�|� |S )Nzrelated attribute set)r r r r r r r r r r r r r! r- r. r/ r1 r0 r2 ) r# ZnewvalueZoldvaluer% r& r' r( Znewvalue_stateZoldvalue_stater) r* r+ �set_k s< ��� ���� � z"track_cascade_events.<locals>.set_Zappend_wo_mutationT)�raw� include_keyr, )r5 �retvalr6 r3 �setN)r r �listen)Z descriptorr( r, r3 r4 r* r) r+ �track_cascade_events+ s " $ � � � �r: c @ s� e Zd ZU ded< ded< ded< ded< d ed < dd �d d �Zedd� �Zdd� Zdd� Zdd� Z dd� Z e j fdd�Z dd� Zd d � Zd9d d!d!d!d"d#d!d$�d%d&�Zd'd(� Zd)d*� Zejd+d,� �Zd-d.� Zd/d0� Zd1d2� Zd3d4�d5d6�Zd3d4�d7d8�Zd S ):�UOWTransactionr r r Z transactionzDict[str, Any]r z7util.defaultdict[Mapper[Any], Set[DependencyProcessor]]�depsz6util.defaultdict[Mapper[Any], Set[InstanceState[Any]]]�mappers)r c C sR || _ i | _t�t�| _t�t�| _i | _i | _t� | _ i | _ t�dd� �| _ d S )Nc S s t � t � fS �N)r8 r* r* r* r+ �<lambda>� � z)UOWTransaction.__init__.<locals>.<lambda>) r r r � defaultdictr8 r< r= �presort_actions�postsort_actions� dependencies�states�post_update_states)�selfr r* r* r+ �__init__� s zUOWTransaction.__init__c C s t | j�S r> )�boolrE �rG r* r* r+ �has_work� s zUOWTransaction.has_workc C sB |j r>z|�|tj� W n$ tjy< | j�|g� Y dS 0 dS )zZReturn ``True`` if the given state is expired and was deleted previously. TF)ZexpiredZ _load_expiredr � PASSIVE_OFF�orm_excZObjectDeletedErrorr �_remove_newly_deleted�rG r# r* r* r+ �was_already_deleted� s z"UOWTransaction.was_already_deletedc C s || j v o| j | d S )z[Return ``True`` if the given state is marked as deleted within this uowtransaction.r �rE rO r* r* r+ � is_deleted� s zUOWTransaction.is_deletedc C s, || j v r| j | S |� | j |< }|S d S r> r )rG r Z callable_�retr* r* r+ �memo� s zUOWTransaction.memoc C s | j | d }|df| j |< dS )z;Remove pending actions for a state from the uowtransaction.r TNrQ )rG r# �isdeleter* r* r+ �remove_state_actions� s z#UOWTransaction.remove_state_actionsc C s� d||f}|| j v r�| j | \}}}|t j@ s�|t j@ r�|j| j}|�||jt jt jB t jB �}|rv|j rv|� � }n|}|||f| j |< nP|j| j}|�||j|t jB t jB �}|r�|j r�|� � }n|}|||f| j |< |S )zOFacade to attributes.get_state_history(), including caching of results.�history) r ZSQL_OKr �implZ get_history�dictrL ZLOAD_AGAINST_COMMITTEDZNO_RAISEZ uses_objectsZas_state) rG r# r ZpassiveZhashkeyrW Z state_historyZcached_passiverX r* r* r+ �get_attribute_history� sH �� ��� ��� z$UOWTransaction.get_attribute_historyc C s |df| j v S )NT)rB )rG � processorr* r* r+ �has_dep* s zUOWTransaction.has_depc C s& ||f}|| j vr"t||�| j |< d S r> )rB � Preprocess)rG r[ � fromparentr r* r* r+ �register_preprocessor- s z$UOWTransaction.register_preprocessorFNzInstanceState[Any]rI z Optional[str]zOptional[MapperProperty])r# rU �listonly� cancel_delete� operationr( �returnc C s� | j �|�s8|js4|d ur4t�dt�|�||f � dS || jvr~|jj }|| j vr^| � |� | j | � |� ||f| j|< n|s�|s�|r�|df| j|< dS )NzJObject of type %s not in session, %s operation along '%s' will not proceedFT) r r Zdeletedr �warn�orm_utilZstate_class_strrE r r r= �_per_mapper_flush_actions�add)rG r# rU r` ra rb r( r r* r* r+ �register_object2 s" �� z UOWTransaction.register_objectc C s0 |j jj}| j| \}}|�|� |�|� d S r> )r r � base_mapperrF rg �update)rG r# Zpost_update_colsr rE �colsr* r* r+ �register_post_updateT s z#UOWTransaction.register_post_updatec C sf t | |j�}t| |j�}| j�||f� |jD ]}|�| � q.|jD ] }|jrPqD|j }|�| � qDd S r> ) � SaveUpdateAllri � DeleteAllrD rg Z_dependency_processorsZper_property_preprocessorsZ relationshipsZviewonlyZ_dependency_processor)rG r ZsavesZdeletes�depr( r* r* r+ rf Z s z(UOWTransaction._per_mapper_flush_actionsc C s t �dd� �S )a return a dynamic mapping of (Mapper, DependencyProcessor) to True or False, indicating if the DependencyProcessor operates on objects of that Mapper. The result is stored in the dictionary persistently once calculated. c S s | d j �| d j�| d ju S )Nr r )r �getr r( )�tupr* r* r+ r? s r@ z0UOWTransaction._mapper_for_dep.<locals>.<lambda>)r Z PopulateDictrJ r* r* r+ �_mapper_for_deph s �z UOWTransaction._mapper_for_depc s | j �� �fdd�|D �S )zmFilter the given list of InstanceStates to those relevant to the given DependencyProcessor. c s g | ]}�|j j� f r|�qS r* )r r ��.0�s�ro Zmapper_for_depr* r+ � <listcomp>| r@ z8UOWTransaction.filter_states_for_dep.<locals>.<listcomp>)rr )rG ro rE r* rv r+ �filter_states_for_depv s z$UOWTransaction.filter_states_for_depc c s> ||f}|j jD ](}| j| D ]}| j| |kr |V q qd S r> )ri �self_and_descendantsr= rE )rG r rU r` Zchecktupr# r* r* r+ �states_for_mapper_hierarchy~ s z*UOWTransaction.states_for_mapper_hierarchyc sB d}t � j�� �D ]}|�� �rd}q|s q.q t�� jt � j�� �� � _}|�r(� fdd�|D �}t � j�D ]�}d|v s�|d j s�|d j s�|� |�r�� j� |� qn|d |v r� j� |� ||d D ]}� j� ||d f� q�qn|d |v rn� j� |� ||d D ]}� j� |d |f� �q qndd � � j�� D �� |�S ) z}Generate the full, unsorted collection of PostSortRecs as well as dependency pairs for this UOWTransaction. FTc s i | ]}|t |�� ���qS r* )r8 �per_state_flush_actions)rt �recrJ r* r+ � <dictcomp>� s z4UOWTransaction._generate_actions.<locals>.<dictcomp>Nr r c S s h | ]}|j s|�qS r* ��disabled)rt �ar* r* r+ � <setcomp>� s z3UOWTransaction._generate_actions.<locals>.<setcomp>)�listrB �values�executer Z find_cyclesrD rC �cyclesr � issupersetr3 rg � difference)rG rS �actionr� �convertZedgero r* rJ r+ �_generate_actions� sH � ����� ��z UOWTransaction._generate_actions�None)rc c C sx | � � }t|dd� d�}| jrVt�| j|�D ]&}t|�}|r,|�� }|�| |� q8q,n t� | j|�D ]}|� | � qdd S )Nc S s | j S r> )�sort_key)r$ r* r* r+ r? � r@ z(UOWTransaction.execute.<locals>.<lambda>r) ) r� �sortedr� r Zsort_as_subsetsrD r8 �pop�execute_aggregate�sortr� )rG rC Zsubsetr4 �nr| r* r* r+ r� � s � �zUOWTransaction.executec C sV | j s dS t| j �}dd� | j �� D �}|�|�}|rB| j�|� |rR| j�|� dS )z�Mark processed objects as clean / deleted after a successful flush(). This method is called within the flush() method after the execute() method has succeeded and the transaction has been committed. Nc S s h | ]\}\}}|r|�qS r* r* )rt ru rU r` r* r* r+ r� � s z8UOWTransaction.finalize_flush_changes.<locals>.<setcomp>)rE r8 �itemsr� r rN Z_register_persistent)rG rE Zisdel�otherr* r* r+ �finalize_flush_changes� s � z%UOWTransaction.finalize_flush_changes)FFFNN)�__name__� __module__� __qualname__�__annotations__rH �propertyrK rP rR rT rV r ZPASSIVE_NO_INITIALIZErZ r\ r_ rh rl rf r Zmemoized_propertyrr rx rz r� r� r� r* r* r* r+ r; � s> - � 5 � " 4r; c @ s e Zd ZdZdd� ZdS )�IterateMappersMixinr* c s2 � j r$t� �fdd�� jjjD ��S � jjjS d S )Nc 3 s" | ]}�j |� jf r|V qd S r> )rr �dependency_processor)rt �m�rG �uowr* r+ � <genexpr>� s �z/IterateMappersMixin._mappers.<locals>.<genexpr>)r^ �iterr� �parentry r r� r* r� r+ �_mappers� s �z IterateMappersMixin._mappersN)r� r� r� � __slots__r� r* r* r* r+ r� � s r� c @ s e Zd ZdZdd� Zdd� ZdS )r] )r� r^ � processed�setup_flush_actionsc C s || _ || _t� | _d| _d S �NF)r� r^ r8 r� r� )rG r� r^ r* r* r+ rH s zPreprocess.__init__c C s� t � }t � }| �|�D ]H}|j| �| j�D ]0}|j| \}}|s,|rR|�|� q,|�|� q,q|r~| j�||� | j� |� |r�| j� ||� | j� |� |s�|r�| j s�| j� ||d�s�| j� ||d�r�| j� |� d| _ dS dS d S �NTF)r8 r� r= r� r� rE rg r� Zpresort_deletesrj Z presort_savesr� Zprop_has_changesZper_property_flush_actions)rG r� Z delete_statesZ save_statesr r# rU r` r* r* r+ r� s: ���� zPreprocess.executeN)r� r� r� r� rH r� r* r* r* r+ r] � s r] c @ s e Zd ZdZdd� Zdd� ZdS )� PostSortRecr~ c G s@ | f| }||j v r |j | S t�| � |j |< }d|_|S d S r� )rC �object�__new__r )�clsr� �argsr rS r* r* r+ r� - s zPostSortRec.__new__c C s | � |� d S r> )r� )rG r� �recsr* r* r+ r� 6 s z PostSortRec.execute_aggregateN)r� r� r� r� r� r� r* r* r* r+ r� * s r� c @ s8 e Zd ZdZdd� Zdd� Zdd� Zdd � Zd d � Zd S ) � ProcessAll)r� rU r^ r� c C s: || _ d| j j|f| _|| _|| _|j|jj �|� d S )Nr� )r� r� rU r^ r< r� ri rg )rG r� r� rU r^ r* r* r+ rH = s ��zProcessAll.__init__c C s2 | � |�}| jr | j�||� n| j�||� d S r> )� _elementsrU r� �process_deletes� process_saves)rG r� rE r* r* r+ r� J s zProcessAll.executec C s t g �S r> )r� r� r* r* r+ r{ Q s z"ProcessAll.per_state_flush_actionsc C s d| j j| j| jf S )Nz%s(%s, isdelete=%s))� __class__r� r� rU rJ r* r* r+ �__repr__X s �zProcessAll.__repr__c c sF | � |�D ]6}|j| D ]&}|j| \}}|| jkr|s|V qq d S r> )r� r= rE rU )rG r� r r# rU r` r* r* r+ r� _ s zProcessAll._elementsN) r� r� r� r� rH r� r{ r� r� r* r* r* r+ r� : s r� c @ s* e Zd ZdZdd� Ze�d�dd� �ZdS )� PostUpdateAll)r rU r� c C s || _ || _d|j|f| _d S )Nr� )r rU � _sort_keyr� )rG r� r rU r* r* r+ rH j s zPostUpdateAll.__init__�sqlalchemy.orm.persistencec sB t jj}�j� j \}}� �fdd�|D �}|�� j|�|� d S )Nc s$ g | ] }�j | d � jkr|�qS �r )rE rU rs r� r* r+ rw s r@ z)PostUpdateAll.execute.<locals>.<listcomp>)r � preloaded�orm_persistencerF r Z post_update)rG r� � persistencerE rk r* r� r+ r� o s zPostUpdateAll.executeN)r� r� r� r� rH r �preload_moduler� r* r* r* r+ r� g s r� c @ s: e Zd ZdZdd� Ze�d�dd� �Zdd� Zd d � Z d S ) rm �r r� c C s$ || _ d|jf| _||ju s J �d S )Nrm �r r� r� ri �rG r� r r* r* r+ rH { s zSaveUpdateAll.__init__r� c C s$ t jj�| j|�| jdd�|� d S r� )r r� r� �save_objr rz r� r* r* r+ r� � s �zSaveUpdateAll.executec c s� t |�| jdd��}| jj}t||�}|D ]$}t||�}|j�||f� |V q*|j| j D ] }|� ||�}|� ||d� q\d S r� ) r� rz r ri rn �SaveUpdateStaterD rg r< rx r{ ) rG r� rE ri Z delete_allr# r� ro �states_for_propr* r* r+ r{ � s � z%SaveUpdateAll.per_state_flush_actionsc C s d| j j| jf S �Nz%s(%s)�r� r� r rJ r* r* r+ r� � s zSaveUpdateAll.__repr__N� r� r� r� r� rH r r� r� r{ r� r* r* r* r+ rm x s rm c @ s: e Zd ZdZdd� Ze�d�dd� �Zdd� Zd d � Z d S ) rn r� c C s$ || _ d|jf| _||ju s J �d S )Nrn r� r� r* r* r+ rH � s zDeleteAll.__init__r� c C s$ t jj�| j|�| jdd�|� d S r� )r r� r� � delete_objr rz r� r* r* r+ r� � s �zDeleteAll.executec c s� t |�| jdd��}| jj}t||�}|D ]$}t||�}|j�||f� |V q*|j| j D ] }|� ||�}|� ||d� q\d S r� ) r� rz r ri rm � DeleteStaterD rg r< rx r{ ) rG r� rE ri Zsave_allr# r� ro r� r* r* r+ r{ � s � z!DeleteAll.per_state_flush_actionsc C s d| j j| jf S r� r� rJ r* r* r+ r� � s zDeleteAll.__repr__Nr� r* r* r* r+ rn � s rn c @ s( e Zd ZdZdd� Zdd� Zdd� ZdS ) � ProcessState)r� rU r# r� c C s" || _ d|jf| _|| _|| _d S �Nr� )r� r� rU r# )rG r� r� rU r# r* r* r+ rH � s zProcessState.__init__c sj | j � | j�| j�� ��fdd�|D �}|�|� | jgdd� |D � }�rZ��||� n ��||� d S )Nc s. g | ]&}|j � u r|j�u r|j�u r|�qS r* )r� r� rU �rt �r��cls_r� rU r* r+ rw � s �z2ProcessState.execute_aggregate.<locals>.<listcomp>c S s g | ] }|j �qS r* �r# r� r* r* r+ rw � r@ )r� r� rU �difference_updater# r� r� )rG r� r� �our_recsrE r* r� r+ r� � s � z ProcessState.execute_aggregatec C s d| j j| jt�| j�| jf S )Nz%s(%s, %s, delete=%s))r� r� r� re � state_strr# rU rJ r* r* r+ r� � s �zProcessState.__repr__N)r� r� r� r� rH r� r� r* r* r* r+ r� � s r� c @ s2 e Zd ZdZdd� Ze�d�dd� �Zdd� Zd S ) r� �r# r r� c C s" || _ |jj| _d| jjf| _d S r� �r# r ri r� r� �rG r� r# r* r* r+ rH � s zSaveUpdateState.__init__r� c sV t jj}| j� | j�� �fdd�|D �}|�|� |��| jgdd� |D � |� d S )Nc s$ g | ] }|j � u r|j�u r|�qS r* �r� r r� �r� r r* r+ rw � s z5SaveUpdateState.execute_aggregate.<locals>.<listcomp>c S s g | ] }|j �qS r* r� r� r* r* r+ rw � r@ )r r� r� r� r r� r� r# )rG r� r� r� r� r* r� r+ r� � s � �z!SaveUpdateState.execute_aggregatec C s d| j jt�| j�f S r� �r� r� re r� r# rJ r* r* r+ r� � s �zSaveUpdateState.__repr__N� r� r� r� r� rH r r� r� r� r* r* r* r+ r� � s r� c @ s2 e Zd ZdZdd� Ze�d�dd� �Zdd� Zd S ) r� r� c C s" || _ |jj| _d| jjf| _d S )Nr� r� r� r* r* r+ rH s zDeleteState.__init__r� c sh t jj}| j� | j�� �fdd�|D �}|�|� | jgdd� |D � }|���fdd�|D ��� d S )Nc s$ g | ] }|j � u r|j�u r|�qS r* r� r� r� r* r+ rw s z1DeleteState.execute_aggregate.<locals>.<listcomp>c S s g | ] }|j �qS r* r� r� r* r* r+ rw r@ c s g | ]}� j | d r|�qS r� rQ rs )r� r* r+ rw r@ )r r� r� r� r r� r# r� )rG r� r� r� r� rE r* )r� r r� r+ r� s � �z DeleteState.execute_aggregatec C s d| j jt�| j�f S r� r� rJ r* r* r+ r� s �zDeleteState.__repr__Nr� r* r* r* r+ r� s r� N)(�__doc__� __future__r �typingr r r r r � r r rM r re r r � dependencyr Z interfacesr r r r r r r# r r: r; r� r] r� r� r� rm rn r� r� r� r* r* r* r+ �<module> sB r O2-%%$ sqlalchemy/orm/__pycache__/relationships.cpython-39.pyc 0000644 00000246030 15125143220 0017230 0 ustar 00 a ��Jh8� � @ s� d Z ddlmZ ddlZddlmZ ddlZddlZddlZddl Z ddl Z ddl m Z ddl m Z ddl m Z ddl mZ dd l mZ dd l mZ dd l mZ dd l mZ dd l mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl m Z ddl m Z ddl Z ddl m Z ddl m!Z! ddl"m#Z# dd l"m$Z$ dd l%m&Z& dd l%m'Z' dd l%m(Z( dd l%m)Z) dd!l%m*Z* dd"l%m+Z+ dd#l%m,Z, dd$l%m-Z- dd%l.m/Z/ dd&l.m0Z0 dd'l.m1Z1 dd(l.m2Z2 dd)l.m3Z3 dd*l.m4Z4 dd+l.m5Z5 dd,l.m6Z6 dd-l7m8Z8 dd.l7m9Z9 dd/l7m:Z: d0d1l m;Z< d0d2l m=Z= d0d3l m>Z> d0d4l m?Z? d0d5l m@Z@ d0d6l m7Z7 d0d7lAmZ d0d8l@mBZB d0d9l@mCZC d0d:l@mDZD d0d;l@mEZE d0d<l@mFZF d0d=lGmHZH d0d>lGmIZI d0d?lJmKZK d0d@lLmMZM d0dAlLmNZN d0dBlOmPZP d0dClOmQZQ d0dDlOmRZR d0dElOmSZS d0dFlOmTZT d0dGlOmUZU d0dHlOmVZV d0dIlOmWZW d0dJlXmYZY d0dKlXmZZZ d0dLlXm[Z[ e j\�rddMl"m]Z] ddNl"m^Z^ ddOl"m_Z_ ddPl"m`Z` ddQl"maZa ddRl"mbZb ddSl"mcZc ddTl%mdZd ddUlemfZf ddVlemgZg ddWlhmiZi ddXljmkZk ddYllmmZm ddZlnmoZo dd[lpmqZq dd\lrmsZs dd]ltmuZu dd^l7mvZv dd_l7mwZw d0d`lGmxZx d0dalGmyZy d0dblGmzZz d0dclJm{Z{ d0ddlJm|Z| d0delLm}Z} d0dflLm~Z~ d0dglLmZ d0dhl�m�Z� d0dil�m�Z� d0djlXm�Z� d0dklXm�Z� e dle dm�Z�e dne dm�Z�e doe dm�Z�e dpe dm�Z�e dqe dm�Z�e e�ee� e g ee� f drdse g drf e g dsf f Z�eZdt Z�e e�eHe� f Z�e due�e g duf f Z�e eZdv e�eHe e g eHe f e g eeHe f ee e�eHe f f Z�e e�ee�ee�e f f f Z�e eMe eIe eEj�dwf Z�e e�ee� e g ee� f e g e�f e�f Z�e dxeHe dm�Z�e dydzdm�Z�eeeNe eNe f Z�eeeNe eNe f Z�eeeNe eNe f Z�dxdxd{�d|d}�Z�dxdxd{�d~d�Z�ej�G d�d�� d�ee�e�f ��Z�e eZdv eeNe d�f f Z�G d�d�� d�e�Z�e>j�G d�d�� d�e0e6e� e>j���Z�dyd�dyd��d�d��Z�G d�d�� d��Z�G d�d�� d��Z�e�d�d��Z�e�d}d��Z�G d�d�� d�e�e� e&e� �Z�G d�d�� d�e�e� e-e� e)e� �Z�dS )�a Heuristics related to join conditions as used in :func:`_orm.relationship`. Provides the :class:`.JoinCondition` object, which encapsulates SQL annotation and aliasing behavior focused on the `primaryjoin` and `secondaryjoin` aspects of :func:`_orm.relationship`. � )� annotationsN)�abc)�Any)�Callable)�cast)� Collection)�Dict)� FrozenSet)�Generic)�Iterable)�Iterator)�List)� NamedTuple)�NoReturn)�Optional)�Sequence)�Set)�Tuple)�Type)�TypeVar)�Union� )� attributes)�strategy_options)�insp_is_aliased_class)�is_has_collection_adapter)�_DeclarativeMapped)�_is_mapped_class)� class_mapper)� DynamicMapped)�LoaderCallableStatus)� PassiveFlag)� state_str)�WriteOnlyMapped)�_AttributeOptions)�_IntrospectsAnnotations)� MANYTOMANY)� MANYTOONE)� ONETOMANY)�PropComparator)�RelationshipDirection)�StrategizedProperty)� _orm_annotate)�_orm_deannotate)�CascadeOptions� )�exc)�Exists)�log)�schema)�sql)�util)�inspect)� coercions)� expression)� operators)�roles)�visitors)�_ColumnExpressionArgument)�_HasClauseElement)�_safe_annotate)� ColumnClause)� ColumnElement��_deep_annotate)�_deep_deannotate)�_shallow_annotate)�adapt_criterion_to_null)� ClauseAdapter)�join_condition)�selectables_overlap��visit_binary_product)�de_optionalize_union_types)�Literal)� resolve_name_to_real_class_name)� _EntityType)�_ExternalEntityType)�_IdentityKeyType)� _InstanceDict)�_InternalEntityType)�_O)� _RegistryType)�Mapped)�_class_resolver)�_ModNS)�_ClassScanMapperConfig)�DependencyProcessor)�Mapper)�Query)�Session)� InstanceState)� LazyLoader)� AliasedClass)� AliasedInsp)�_CoreAdapterProto)�_EquivalentColumnMap)� _InfoType)�_AnnotationDict)�SupportsAnnotations)�BinaryExpression)� BindParameter)� ClauseElement)�Table)� FromClause)�_AnnotationScanType)�RODescriptorReference�_T)�bound�_T1�_T2�_PT�_PT2� Mapper[_T]zAliasedClass[_T]) �selectZjoinedZselectinZsubquery�raiseZ raise_on_sqlZnoloadZ immediate� write_only�dynamicTFNrj Fz Mapped[Any]�_CEA�_CE�ColumnElement[Any])�expr�returnc C s t t�tj| �ddi�S )a Annotate a portion of a primaryjoin expression with a 'remote' annotation. See the section :ref:`relationship_custom_foreign` for a description of use. .. seealso:: :ref:`relationship_custom_foreign` :func:`.foreign` �remoteT��_annotate_columnsr7 �expectr: �ColumnArgumentRole�r{ � r� �Q/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/relationships.pyr} � s �r} c C s t t�tj| �ddi�S )a Annotate a portion of a primaryjoin expression with a 'foreign' annotation. See the section :ref:`relationship_custom_foreign` for a description of use. .. seealso:: :ref:`relationship_custom_foreign` :func:`.remote` �foreignTr~ r� r� r� r� r� � s �r� c @ sL e Zd ZU dZdZded< ded< ded< d d �d d �Zd dd�dd�ZdS )�_RelationshipArgztstores a user-defined parameter value that must be resolved and parsed later at mapper configuration time. )�name�argument�resolved�strr� ro r� z Optional[_T2]r� �bool�r| c C s | j d uS �N)r� ��selfr� r� r� � _is_populated s z _RelationshipArg._is_populated�&Callable[[str, bool], _class_resolver]�None)�clsregistry_resolverr| c C sJ | j }t|t�r&||| jdk�� | _n t|�r@t|�s@|� | _n|| _d S )N� secondary)r� � isinstancer� r� r� �callabler )r� r� � attr_valuer� r� r� �_resolve_against_registry s � z*_RelationshipArg._resolve_against_registryN)�__name__� __module__� __qualname__�__doc__� __slots__�__annotations__r� r� r� r� r� r� r� � s r� .c @ sB e Zd ZU dZded< ded< ded< ded< d ed < d ed < d S ) �_RelationshipArgszWstores user-passed parameters that are resolved at mapper configuration time. zP_RelationshipArg[Optional[_RelationshipSecondaryArgument], Optional[FromClause]]r� z\_RelationshipArg[Optional[_RelationshipJoinConditionArgument], Optional[ColumnElement[Any]]]� primaryjoin� secondaryjoinz>_RelationshipArg[_ORMOrderByArgument, _RelationshipOrderByArg]�order_byzN_RelationshipArg[Optional[_ORMColCollectionArgument], Set[ColumnElement[Any]]]� foreign_keys� remote_sideN)r� r� r� r� r� r� r� r� r� r� s r� c ' sT e Zd ZU dZejZdZdZdZ de d< de d< e dddddd�Z d Z d e d < d e d < de d< de d< de d< de d< de d< de d< de d< de d< de d < d e d < d e d < d e d!< d"e d#< d�d d d d d dd d dd$dd d%ddddd d d d ddd dd d d d d ddd dd&�"d'd(d)d*d+d+d,d-d.d,d/d0d/d1d2d3d/d/d/d4d4d5d6d/d/d)d/d7d8d9d)d,d:d;d d/d<�$� fd=d>�Zd?d@dA�dBdC�ZdDd@dE�dFdG�ZG dHdI� dIejee �Zd�dJd/dKd dL�dMdN�Zd�d?d/dOd/d dP�dQdR�ZdDdSdTdUdVdW�dXdY�Zd�d/dOd dZ�d[d\�Zd0d]�d^d_�Zd`dSdTdSdTd/dadbd@dc� ddde�Ze j fdfdTd0dgdhdi�djdk�Z d�d0dSdTdldmdndo�dpdq�Z e d/d]�drds��Z!e"dtdtd@du�dvdw��Z#d0d@dx�dydz�Z$ej%d{d]�d|d}��Z&ej%d~d]�dd���Z'd@d]�� fd�d�� Z(d@d]�d�d��Z)d@d]�d�d��Z*d�d�d�d,d0d�d�d�d/d@d�� d�d��Z+e�,d��d�d?d@d��d�d���Z-d@d]�d�d��Z.e d�d]�d�d���Z/e d�d]�d�d���Z0ej%e�,d��d�d]�d�d����Z1d@d]�d�d��Z2e d�d]�d�d���Z3e3j4d�d@d��d�d���Z3d�d@d��d�d��Z5d�d@d��d�d��Z6dDd/dE�d�d��Z7dUd/d��d�d��Z8d@d]�d�d��Z9e�,d��d@d]�d�d���Z:ej%d/d]�d�d���Z;ej%d/d]�d�d���Z<d�d/ddd�d/d�d�d��d�d��Z=� Z>S )��RelationshipPropertyz�Describes an object property that holds a single item or list of items that correspond to a related database table. Public constructor is the :func:`_orm.relationship` function. .. seealso:: :ref:`relationship_config_toplevel` Tz Sequence[str]� _overlapsr^ �_lazy_strategyF��passive_deletes�passive_updates�enable_typechecks�active_history�cascade_backrefsNz Optional[DependencyProcessor]�_dependency_processor�ColumnElement[bool]r� � Optional[ColumnElement[bool]]r� �Optional[FromClause]r� � JoinCondition�_join_condition�_RelationshipOrderByArgr� �Set[ColumnElement[Any]]�_user_defined_foreign_keys�_calculated_foreign_keysr� � local_columns� _ColumnPairs�synchronize_pairs�Optional[_ColumnPairs]�secondary_synchronize_pairs�local_remote_pairsr* � directionr� � _init_argszsave-update, mergert )"�uselist�collection_classr� r� �back_populatesr� �backref�overlaps� post_update�cascade�viewonly�attribute_options�lazyr� r� r� r� r� r� � join_depth�comparator_factory� single_parent� innerjoin�distinct_target_key�load_on_pending� query_class�info� omit_join� sync_backref�doc� bake_queriesr� �_local_remote_pairs� _legacy_inactive_history_stylez'Optional[_RelationshipArgumentType[_T]]z(Optional[_RelationshipSecondaryArgument]zOptional[bool]zEOptional[Union[Type[Collection[Any]], Callable[[], Collection[Any]]]]z,Optional[_RelationshipJoinConditionArgument]z Optional[str]�_ORMOrderByArgumentz Optional[ORMBackrefArgument]r� r� zOptional[_AttributeOptions]�_LazyLoadArgumentTypezUnion[Literal['all'], bool]z#Optional[_ORMColCollectionArgument]z Optional[int]z4Optional[Type[RelationshipProperty.Comparator[Any]]]zOptional[Type[Query[Any]]]zOptional[_InfoType]zLiteral[None, False]z Literal[True]zLiteral[False])$r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� c " % s� t � j|d� || _|| _ttd|d �td|d �td|d �td|d �td|d �td|d ��| _| | _| | _| r�| j |||||"d� | r�| r�t � d ��| | _ || _ || _|| _|| _|"r�t � d ��|| _|| _| | _|| _|| _| | _|| _|$| _|| _| �rt�d � | | _ |#| _ || _ |�p"t j | _!t�"| � | d u�rF| j#�$| � d | j ff| _%t&� | _'| �rvt&t(�)d | ��| _*nd| _*| | _+|| _,| j,�r�| �r�t � d��d | _-n| | _-d S )N)r� r� r� r� r� r� r� r� z-sync_backref and viewonly cannot both be TruezSThe 'cascade_backrefs' parameter passed to relationship() may only be set to False.z�setting omit_join to True is not supported; selectin loading of this relationship may not work correctly if this flag is set explicitly. omit_join optimization is automatically detected for conditions under which it is supported.r� z\s*,\s*r� zCbackref and back_populates keyword arguments are mutually exclusive).�super�__init__r� r� r� r� r� r� r� � _warn_for_persistence_only_flags�sa_exc� ArgumentErrorr� r� r� r� r� r� r� r� r� r� r� r� r� r� r5 �warnr� r� r� r� � Comparatorr� Zset_creation_orderr� �update� strategy_key�set�_reverse_property�re�splitr� r� r� r� )%r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� �� __class__r� r� r� n s� , � ���� � �z RelationshipProperty.__init__r r� )�kwr| c K s4 |� � D ]&\}}|| j| krt�d|f � qd S )Nz�Setting %s on relationship() while also setting viewonly=True does not make sense, as a viewonly=True relationship does not perform persistence operations. This configuration may raise an error in a future release.)�items�_persistence_onlyr5 r� )r� r� �k�vr� r� r� r� � s ��z5RelationshipProperty._warn_for_persistence_only_flagsz Mapper[Any])�mapperr| c C s& t j|j| j| �| |�|| jd� d S )N)Z comparator� parententityr� )r Zregister_descriptor�class_�keyr� r� �r� r� r� r� r� �instrument_class s �z%RelationshipProperty.instrument_classc @ sV e Zd ZU dZdZded< ded< dHd d d dd d �dd�Zddd�dd�Zded< ded< dd�dd�Zdd�d d �Z d d�d d �Z d!d�d"d#�Z d$d%d&�d'd(�Z d)d*d+�d,d-�Z d.d/d0�d1d2�ZdZd.d!d0�d3d4�ZdId5d.d6d7�d8d9�ZdJd5d.d!d7�d:d;�ZdKd5d.d!d7�d<d=�Zd>d.d!d?�d@dA�Zd.d!d0�dBdC�Zd.d!d0�dDdE�Zd d�dFdG�ZdS )Lz RelationshipProperty.Comparatora� Produce boolean, comparison, and other operators for :class:`.RelationshipProperty` attributes. See the documentation for :class:`.PropComparator` for a brief overview of ORM level operator definition. .. seealso:: :class:`.PropComparator` :class:`.ColumnProperty.Comparator` :class:`.ColumnOperators` :ref:`types_operators` :attr:`.TypeEngine.comparator_factory` )�entityr� �property�_of_type�_extra_criteriaz0RODescriptorReference[RelationshipProperty[_PT]]�propzOptional[_EntityType[_PT]]r� Nr� zRelationshipProperty[_PT]z_InternalEntityType[Any]zOptional[AliasedInsp[Any]]� Tuple[ColumnElement[bool], ...])r� � parentmapper�adapt_to_entity�of_type�extra_criteriac C s. || _ || _|| _|r || _nd| _|| _dS )z�Construction of :class:`.RelationshipProperty.Comparator` is internal to the ORM's attribute mechanics. N)r� � _parententity�_adapt_to_entityr� r� )r� r� r� r� r� r� r� r� r� r� 3 s z(RelationshipProperty.Comparator.__init__zAliasedInsp[Any]z$RelationshipProperty.Comparator[Any])r� r| c C s | j | j| j|| jd�S )N)r� r� )r� r� r� r� )r� r� r� r� r� r� H s �z/RelationshipProperty.Comparator.adapt_to_entityz_InternalEntityType[_PT]r� z Mapper[_PT]r� r� c C s | j rt| j �S | jjS d S r� )r� r6 r� r� r� r� r� r� �_memoized_attr_entityg s z5RelationshipProperty.Comparator._memoized_attr_entityc C s | j jS r� �r� r� r� r� r� r� �_memoized_attr_mapperm s z5RelationshipProperty.Comparator._memoized_attr_mapperrj c C s | j r| j jS | jjjS d S r� )r� � selectabler� �parent� _with_polymorphic_selectabler� r� r� r� �_source_selectablep s z2RelationshipProperty.Comparator._source_selectabler� c C sZ | � � }| jrt| j�}nd }| jj|d|d| jd�\}}}}}}|d urR||@ S |S d S )NT)�source_selectable�source_polymorphic�of_type_entity�alias_secondaryr� )r r� r6 r� � _create_joinsr� ) r� Z adapt_fromr �pj�sj�source�destr� �target_adapterr� r� r� �__clause_element__v s* ��z2RelationshipProperty.Comparator.__clause_element__z_EntityType[Any]zPropComparator[_PT])r� r| c C s t j| j| j| j|| jd�S )z�Redefine this object in terms of a polymorphic subclass. See :meth:`.PropComparator.of_type` for an example. �r� r� r� )r� r� r� r� r� r� )r� r� r� r� r� r� � s �z'RelationshipProperty.Comparator.of_typez _ColumnExpressionArgument[bool]zPropComparator[Any])�criteriar| c G s: t dd� t�|�D ��}tj| j| j| j| j| j | d�S )z�Add AND criteria. See :meth:`.PropComparator.and_` for an example. .. versionadded:: 1.4 c s s | ]}t �tj|�V qd S r� )r7 r� r: �WhereHavingRole)�.0�clauser� r� r� � <genexpr>� s �z7RelationshipProperty.Comparator.and_.<locals>.<genexpr>r ) �tupler5 Zcoerce_generator_argr� r� r� r� r� r� r� )r� r �exprsr� r� r� �and_� s ��z$RelationshipProperty.Comparator.and_r r )�otherr| c C s t d��dS )z�Produce an IN clause - this is not implemented for :func:`_orm.relationship`-based attributes at this time. zvin_() not yet supported for relationships. For a simple many-to-one, use in_() against the set of foreign key values.N)�NotImplementedError�r� r r� r� r� �in_� s �z#RelationshipProperty.Comparator.in_c C st |du st |tj�rF| jjttfv r.| �� S t| jj d| j d��S n*| jj rZt � d��nt| jj || j d��S dS )a� Implement the ``==`` operator. In a many-to-one context, such as: .. sourcecode:: text MyClass.some_prop == <some object> this will typically produce a clause such as: .. sourcecode:: text mytable.related_id == <some id> Where ``<some id>`` is the primary key of the given object. The ``==`` operator provides partial functionality for non- many-to-one comparisons: * Comparisons against collections are not supported. Use :meth:`~.Relationship.Comparator.contains`. * Compared to a scalar one-to-many, will produce a clause that compares the target columns in the parent to the given target. * Compared to a scalar many-to-many, an alias of the association table will be rendered as well, forming a natural join that is part of the main body of the query. This will not work for queries that go beyond simple AND conjunctions of comparisons, such as those which use OR. Use explicit joins, outerjoins, or :meth:`~.Relationship.Comparator.has` for more comprehensive non-many-to-one scalar membership tests. * Comparisons against ``None`` given in a one-to-many or many-to-many context produce a NOT EXISTS clause. N�� adapt_source�]Can't compare a collection to an object or collection; use contains() to test for membership.)r� r8 �Nullr� r� r( r& �_criterion_existsr, �_optimized_compare�adapterr� r� �InvalidRequestErrorr r� r� r� �__eq__� s" ) �����z&RelationshipProperty.Comparator.__eq__z)Optional[_ColumnExpressionArgument[bool]]r1 )� criterion�kwargsr| c K s� |d urt �tj|�nd }t| dd �r�t| j�}|d us<J �|j|j|j }}}| j j rf|sf|� � }|j }|d ur�|d ur�||@ }q�|}nd}d }| jr�| �� } nd } | j j|| d�\} } } } }}|D ]2}t| j jj|�|| k}|d u r�|}q�||@ }q�| d u�rt| �| @ }nt| | j jd�}|d u�rD|�rD|�sD|�|�}|d u�r\|�ddi�}|tj�|�@ }|d u�r�t�d��|��| |�� | |�}n t�d��|��| �� | �}|S )Nr� F)�dest_selectabler )�exclude�no_replacement_traverseTr ) r7 r� r: r �getattrr6 r� r� r �is_aliased_classr� �_is_self_referential�_anonymous_fromclause�_single_table_criterionr% r r r� r, r� �traverse� _annotater4 ZTrue_Z_ifnone�exists�where� select_fromZcorrelate_except)r� r( r) Zwhere_criteriar� Z target_mapperZ to_selectabler. � single_critr r r r r r� r r� �crit�j�exr� r� r� r# s� �� � � �� ��� � ���� ����z1RelationshipProperty.Comparator._criterion_existsc K s$ | j jst�d��| j|fi |��S )an Produce an expression that tests a collection against particular criterion, using EXISTS. An expression like:: session.query(MyClass).filter( MyClass.somereference.any(SomeRelated.x == 2) ) Will produce a query like: .. sourcecode:: sql SELECT * FROM my_table WHERE EXISTS (SELECT 1 FROM related WHERE related.my_id=my_table.id AND related.x=2) Because :meth:`~.Relationship.Comparator.any` uses a correlated subquery, its performance is not nearly as good when compared against large target tables as that of using a join. :meth:`~.Relationship.Comparator.any` is particularly useful for testing for empty collections:: session.query(MyClass).filter(~MyClass.somereference.any()) will produce: .. sourcecode:: sql SELECT * FROM my_table WHERE NOT (EXISTS (SELECT 1 FROM related WHERE related.my_id=my_table.id)) :meth:`~.Relationship.Comparator.any` is only valid for collections, i.e. a :func:`_orm.relationship` that has ``uselist=True``. For scalar references, use :meth:`~.Relationship.Comparator.has`. z9'any()' not implemented for scalar attributes. Use has().�r� r� r� r& r# �r� r( r) r� r� r� �anyi s .�z#RelationshipProperty.Comparator.anyc K s$ | j jrt�d��| j|fi |��S )a� Produce an expression that tests a scalar reference against particular criterion, using EXISTS. An expression like:: session.query(MyClass).filter( MyClass.somereference.has(SomeRelated.x == 2) ) Will produce a query like: .. sourcecode:: sql SELECT * FROM my_table WHERE EXISTS (SELECT 1 FROM related WHERE related.id==my_table.related_id AND related.x=2) Because :meth:`~.Relationship.Comparator.has` uses a correlated subquery, its performance is not nearly as good when compared against large target tables as that of using a join. :meth:`~.Relationship.Comparator.has` is only valid for scalar references, i.e. a :func:`_orm.relationship` that has ``uselist=False``. For collection references, use :meth:`~.Relationship.Comparator.any`. z3'has()' not implemented for collections. Use any().r; r< r� r� r� �has� s !�z#RelationshipProperty.Comparator.hasz _ColumnExpressionArgument[Any])r r) r| c K s@ | j jst�d��| j j|| jd�}| j jdur<| �|�|_|S )a� Return a simple expression that tests a collection for containment of a particular item. :meth:`~.Relationship.Comparator.contains` is only valid for a collection, i.e. a :func:`_orm.relationship` that implements one-to-many or many-to-many with ``uselist=True``. When used in a simple one-to-many context, an expression like:: MyClass.contains(other) Produces a clause like: .. sourcecode:: sql mytable.id == <some id> Where ``<some id>`` is the value of the foreign key attribute on ``other`` which refers to the primary key of its parent object. From this it follows that :meth:`~.Relationship.Comparator.contains` is very useful when used with simple one-to-many operations. For many-to-many operations, the behavior of :meth:`~.Relationship.Comparator.contains` has more caveats. The association table will be rendered in the statement, producing an "implicit" join, that is, includes multiple tables in the FROM clause which are equated in the WHERE clause:: query(MyClass).filter(MyClass.contains(other)) Produces a query like: .. sourcecode:: sql SELECT * FROM my_table, my_association_table AS my_association_table_1 WHERE my_table.id = my_association_table_1.parent_id AND my_association_table_1.child_id = <some id> Where ``<some id>`` would be the primary key of ``other``. From the above, it is clear that :meth:`~.Relationship.Comparator.contains` will **not** work with many-to-many collections when used in queries that move beyond simple AND conjunctions, such as multiple :meth:`~.Relationship.Comparator.contains` expressions joined by OR. In such cases subqueries or explicit "outer joins" will need to be used instead. See :meth:`~.Relationship.Comparator.any` for a less-performant alternative using EXISTS, or refer to :meth:`_query.Query.outerjoin` as well as :ref:`orm_queryguide_joins` for more details on constructing outer joins. kwargs may be ignored by this operator but are required for API conformance. z9'contains' not implemented for scalar attributes. Use ==r N) r� r� r� r& r$ r% r� �'_Comparator__negated_contains_or_equalsZnegation_clause)r� r r) r r� r� r� �contains� s A�� �z(RelationshipProperty.Comparator.containsc s� �j jtkrjt�|��ddddd��fdd� �ddd��fd d � � �jjrjtj� ��fd d ��jj D �� S tjd d � t �jj j �jj � |��D �� }��|� S )Nrz �InstanceState[Any]�BindParameter[Any])� local_col�state� remote_colr| c s. |j }tj| j| jd� j�� jj|||�d�S )NT)�type_�uniqueZ callable_)�dictr4 � bindparamr� �typer� �_get_attr_w_warn_on_noner� )rC rD rE �dict_r� r� r� �state_bindparam s ��zURelationshipProperty.Comparator.__negated_contains_or_equals.<locals>.state_bindparamry )�colr| c s � j r� � | �S | S d S r� )r% �rN r� r� r� �adapt- s zKRelationshipProperty.Comparator.__negated_contains_or_equals.<locals>.adaptc s8 g | ]0\}}t �� |��� |��|�k� |�d k��qS r� )r4 �or_�r �x�y)rP rD rM r� r� � <listcomp>5 s �� �zPRelationshipProperty.Comparator.__negated_contains_or_equals.<locals>.<listcomp>c S s g | ]\}}||k�qS r� r� rR r� r� r� rU @ s �)r� r� r' r �instance_stater� �_use_getr4 r r� �zipr� Z primary_keyZprimary_key_from_instancer# )r� r r( r� )rP r� rD rM r� Z __negated_contains_or_equals s& �� ��� z<RelationshipProperty.Comparator.__negated_contains_or_equalsc C sh |du st |tj�rB| jjtkr8t| jjd| jd� �S | � � S n"| jj rVt � d��nt| � |��S dS )aS Implement the ``!=`` operator. In a many-to-one context, such as: .. sourcecode:: text MyClass.some_prop != <some object> This will typically produce a clause such as: .. sourcecode:: sql mytable.related_id != <some id> Where ``<some id>`` is the primary key of the given object. The ``!=`` operator provides partial functionality for non- many-to-one comparisons: * Comparisons against collections are not supported. Use :meth:`~.Relationship.Comparator.contains` in conjunction with :func:`_expression.not_`. * Compared to a scalar one-to-many, will produce a clause that compares the target columns in the parent to the given target. * Compared to a scalar many-to-many, an alias of the association table will be rendered as well, forming a natural join that is part of the main body of the query. This will not work for queries that go beyond simple AND conjunctions of comparisons, such as those which use OR. Use explicit joins, outerjoins, or :meth:`~.Relationship.Comparator.has` in conjunction with :func:`_expression.not_` for more comprehensive non-many-to-one scalar membership tests. * Comparisons against ``None`` given in a one-to-many or many-to-many context produce an EXISTS clause. Nr r! )r� r8 r" r� r� r' r, r$ r% r# r� r� r& r? r r� r� r� �__ne__K s + �� �z&RelationshipProperty.Comparator.__ne__c C s | j j�� | j S r� )r� r �_check_configurer� r� r� r� �_memoized_attr_property� s z7RelationshipProperty.Comparator._memoized_attr_property)NNr� )N)N)N)r� r� r� r� r� r� r� r� r r r r r� r r �__hash__r' r# r= r> r@ r? rY r[ r� r� r� r� r� s< � @ �h �8 �'R3>r� �objectzOptional[_EntityType[Any]])�instancer � from_entityr| c C sN |d us J �d }|d ur<t |�}|d us,J �t|�r<|jj}| j|d||d�S )NT)�value_is_parentr r )r6 r Z_adapterZ adapt_clauser$ )r� r^ r r_ r Zinspr� r� r� � _with_parent� s �z!RelationshipProperty._with_parentzOptional[_CoreAdapterProto])rD r` r r r| c s �d urPz t ���W n tjy, d �Y n0 �d u sBt�dd�sPt�d� ��| }�d u rl�j||d�S |s��jj�jj }� n�jj �jj }� |r��j �n�j �t ���� ��ddd�� ����fdd � }�jd ur�|r�t�j�� ��|�}t�|i d |i�}|�r||�}|S ) NZ is_instanceFz�Mapped instance expected for relationship comparison to object. Classes, queries and other SQL elements are not accepted in this context; for comparison with a subquery, use %s.has(**criteria).r rB r� )rI r| c s& | j � v r"������ | j �| _d S r� )Z_identifying_keyrK r� )rI �� bind_to_colrL r� r� rD r� r� �visit_bindparam� s �z@RelationshipProperty._optimized_compare.<locals>.visit_bindparamrI )r6 r� �NoInspectionAvailabler- r� �_lazy_none_clauser� � _lazywhere� _bind_to_col�_rev_lazywhere�_rev_bind_to_colr� r r � instance_dict�objr� rF r0 r2 r; �cloned_traverse)r� rD r` r r �reverse_directionr( rd r� rb r� r$ � sP ����� �� �z'RelationshipProperty._optimized_comparerA rQ rz zCallable[[], Any])r� rD rL �columnr| c s< �� � �����j� �j�dd�� �����fdd� }|S )aK Create the callable that is used in a many-to-one expression. E.g.:: u1 = s.query(User).get(5) expr = Address.user == u1 Above, the SQL should be "address.user_id = 5". The callable returned by this method produces the value "5" based on the identity of ``u1``. r r� c s� �d us J ���j } }| tju}�j��� �jr:tjn tjtjA d�}|tj u rp|s�t � d� t ��f ��n*|tj u r�|s�t � d� t ��f ��n|}|d u r�t�d� � |S )N��passivezUCan't resolve value for column %s on object %s; no value has been set for this columnz`Can't resolve value for column %s on object %s; the object is detached and the value was expiredz�Got None for value of column %s; this is unsupported for a relationship comparison and will not currently produce an IS comparison (but may in a future release))r� r ZNO_VALUEZ_get_state_attr_by_column� persistentr! � PASSIVE_OFFZPASSIVE_NO_FETCHZINIT_OKZ NEVER_SETr� r& r" �PASSIVE_NO_RESULTr5 r� )Z last_knownZ to_returnZexisting_is_availableZ current_value�ro rL Z lkv_fixedr� r� rD r� r� �_go sD �� � �� ����z:RelationshipProperty._get_attr_w_warn_on_none.<locals>._go)Zget_property_by_columnZ_track_last_known_valuer� Z_last_known_values)r� r� rD rL ro rv r� ru r� rK � s 1 /z-RelationshipProperty._get_attr_w_warn_on_none)rn r r| c C sD |s| j j| j j }}n| j j| j j }}t||�}|r@||�}|S r� )r� rg rh ri rj rE )r� rn r r( rc r� r� r� rf P s �� z&RelationshipProperty._lazy_none_clauser� c C s t | jjj�d | j S )N�.)r� r r� r� r� r� r� r� r� �__str__f s z RelationshipProperty.__str__r\ zDict[Any, object]z#Dict[_IdentityKeyType[Any], object]) �session� source_state� source_dict� dest_state� dest_dict�load� _recursive�_resolve_conflict_mapr| c C s� |r"| j D ]} || f|v r d S q d| jvr0d S | j|vr>d S | j�rR|�| j�} t| �s^J �| �||�} | jrx| jr�nds�J �|r�|�| j�j ||t j d� g } | D ]J} t � | �}t �| �}d||| f< |j|||||d�}|d ur�| �|� q�|�s t �||| j�}| D ]}|�|� �q n0|�| j�}t|��s:J �|j||| dt j d� nx|| j } | d u�r�t � | �}t �| �}d||| f< |j|||||d�}nd }|�s�||| j< n|�| j��|||d � d S )N�mergeTrp )r~ r r� F)Z_adaptrq )r� �_cascader� r� Zget_implr �get_collection� collection�empty�getr! Z PASSIVE_MERGEr rV rk �_merge�appendZinit_state_collectionZappend_without_eventr� )r� ry rz r{ r| r} r~ r r� �r�implZinstances_iterableZ dest_list�currentZ current_stateZ current_dictrl Zcoll�cZ dest_implr� r� r� r� i s� � � � � � �zRelationshipProperty.mergezInstanceState[_O]r! z&Sequence[Tuple[InstanceState[_O], _O]])rD rL r� rq r| c C sj |j | j}|j|||d�}|tju s.|du r2g S t|�rVdd� |j||||d�D �S t�|�|fgS dS )z�Return a list of tuples (state, obj) for the given key. returns an empty list if the value is None/empty/PASSIVE_NO_RESULT rp Nc S s g | ]}t �|�|f�qS r� )r rV )r �or� r� r� rU � s �z;RelationshipProperty._value_as_iterable.<locals>.<listcomp>) �managerr� r� r rt r r� r rV )r� rD rL r� rq r� rS r� r� r� �_value_as_iterable� s �z'RelationshipProperty._value_as_iterablezSet[InstanceState[Any]]z.Optional[Callable[[InstanceState[Any]], bool]]zDIterator[Tuple[Any, Mapper[Any], InstanceState[Any], _InstanceDict]])rF rD rL �visited_states�halt_onr| c c s |dks| j rtj}n tjtjB }|dkrB|j| j j�||�}n| j ||| j|d�}|dkofd| j v}|D ]�\} } | |v r~ql| d u r�ql| d us�J �t � | �} |r�|| �r�ql|r�| js�ql| jj } | �| j jj �s�td| j| jj| jf ��|�| � | | | | fV qld S )N�deletez save-updaterp zrefresh-expire� delete-orphanz@Attribute '%s' on class '%s' doesn't handle objects of type '%s')r� r! ZPASSIVE_NO_INITIALIZErs ZNO_RAISEr� r� r� Zget_all_pendingr� r� r rk r� ZisaZ class_manager�AssertionErrorr r� r� �add) r� rF rD rL r� r� rq ZtuplesZ skip_pendingrV r� rk Zinstance_mapperr� r� r� �cascade_iterator� s< �� �� z%RelationshipProperty.cascade_iteratorc C s | j r dS | jduS d S )NF)r� r� r� r� r� r� �_effective_sync_backref s z,RelationshipProperty._effective_sync_backref�RelationshipProperty[Any])�rel_a�rel_br| c C s> | j r |jr t�d|| f ��| j r:|j s:|jdur:d|_d S )NzQRelationship %s cannot specify sync_backref=True since %s includes viewonly=True.F)r� r� r� r& )r� r� r� r� r� �_check_sync_backref' s �����z(RelationshipProperty._check_sync_backref)r� r| c C s� | j j|dd�}t|t�s,t�d| |f ��| �| |� | �|| � | j�|� |j�| � |� � |j � | j �s�t� d|| || j f ��|j r�| jttfv r�| j|jkr�t� d|| | jf ��d S )NF)Z_configure_mappersz�back_populates on relationship '%s' refers to attribute '%s' that is not a relationship. The back_populates parameter should refer to the name of a relationship on the target class.zereverse_property %r on relationship %s references relationship %s, which does not reference mapper %szv%s and back-reference %s are both of the same direction %r. Did you mean to set remote_side on the many-to-one side ?)r� Z get_propertyr� r� r� r& r� r� r� � _setup_entity� common_parentr r� Z_configure_startedr� r( r' )r� r� r r� r� r� �_add_reverse_property7 s: �� ��� � � ��z*RelationshipProperty._add_reverse_propertyz_InternalEntityType[_T]c C s | j �� | jS )z�Return the target mapped entity, which is an inspect() of the class or aliased class that is referenced by this :class:`.RelationshipProperty`. )r rZ r� r� r� r� r� r� c s zRelationshipProperty.entityrs c C s | j jS )zcReturn the targeted :class:`_orm.Mapper` for this :class:`.RelationshipProperty`. r r� r� r� r� r� m s zRelationshipProperty.mapperc sn | � � | �� | �� | �� | �� | �| j� | �� | �� | j � � t � � � t d| �d��| _d S )Nr^ ))r� rt )�_check_conflicts� _process_dependent_argumentsr� � _setup_registry_dependencies�_setup_join_conditions�_check_cascade_settingsr� � _post_init�_generate_backrefr� �"_warn_for_conflicting_sync_targetsr� �do_initr Z _get_strategyr� r� r� r� r� r� u s �z RelationshipProperty.do_initc C s | j jj�| jjj� d S r� )r r� �registryZ_set_depends_onr� r� r� r� r� r� � s �z1RelationshipProperty._setup_registry_dependenciesc C s | j }dD ] }t||�}|�| jd � q dD ]4}t||�}|j}|dur.ttjtj ||d��|_q.|j j}|dur�t |�r�t � d|| f ��|jjdur�|jjdur�tdd � t�|jj�D ��| _nd| _t�d d � t�|jj�D ��| _t�d d � t�|jj�D ��| _dS ) z�Convert incoming configuration arguments to their proper form. Callables are resolved, ORM annotations removed. )r� r� r� r� r� r� r )r� r� N��argnamez�secondary argument %s passed to to relationship() %s must be a Table object or other FROM clause; can't send a mapped class directly as rows in 'secondary' are persisted independently of a class that is mapped to that same table.Fc s s | ]}t jtj|d d�V qdS )r� r� N�r7 r� r: r� �r rS r� r� r� r � s ��zDRelationshipProperty._process_dependent_arguments.<locals>.<genexpr>c s s | ]}t jtj|d d�V qdS )r� r� Nr� r� r� r� r� r � s ��c s s | ]}t jtj|d d�V qdS )r� r� Nr� r� r� r� r� r � s ��)r� r- r� �_clsregistry_resolversr� r- r7 r� r: r� r� r r� r� r� r r5 Zto_list� column_setZ to_column_setr� r� r� )r� Z init_args�attrZrel_arg�valr� r� r� r� r� � sD ���� � � � � �z1RelationshipProperty._process_dependent_argumentsrX rT z Type[Any]zOptional[Type[Mapped[Any]]]z Optional[_AnnotationScanType]) � decl_scanr� �cls�originating_moduler� �mapped_container� annotation�extracted_mapped_annotation�is_dataclass_fieldr| c C s� |d u r$| j d u r | �||� nd S |} |d us4J �|d ur�t|t�} t|t�} | rjd| _d| jff| _q�| r�d| _d| jff| _nd } } t| �} t| d��rh| j } t | t �r�t| t j �r�| jd u r�t�| �r�t�d| � d���| | _n| s�| s�d| _| j�rTt | t ��r&t| tj��r&| jd }n | jd }t|d ��rN|j}t||�} n|} nt�d | � d ���n t| d ��r�| j} t| |�} | jd u �r�| �s�| �s�d| _| j d u �r�td | �| _ d S )Nrv r� rw F� __origin__zCollection annotation type z� cannot be instantiated; please provide an explicit 'collection_class' parameter (e.g. list, set, etc.) to the relationship() function to accompany this annotation���r �__forward_arg__zGeneric alias z requires an argumentz _RelationshipArgumentType[_T])r� Z_raise_for_required� issubclassr# r r� r� rK �hasattrr� r� rJ r r r� � _py_inspect� isabstractr� r� r� �__args__�typing�Mappingr� rM r )r� r� r� r� r� r� r� r� r� r� r� Z is_write_onlyZ is_dynamicZ arg_originZtype_argZ str_argumentr� r� r� �declarative_scan� sv � � � � � ���� z%RelationshipProperty.declarative_scanzsqlalchemy.orm.mapper)� _RelationshipProperty__argumentr| c C s� d| j v rd S tjj}|r |}n| j}t|t�rDtd| �|�� �}n$t |�rdt|t |j f�sd|� }n|}t|t �r�t |dd�}nHz t |�}W n tjy� d }Y n0 t|d�s�t�d| jt |�f ��|| _| jj| _d S )Nr� z_ExternalEntityType[Any]F�� configurer� zErelationship '%s' expects a class or a mapper argument (received: %s))�__dict__r5 � preloadedZ orm_mapperr� r� r� r �_clsregistry_resolve_namer� rJ rZ r r6 r� re r� r� r� r� �persist_selectable�target)r� r� Z mapperlibr� Zresolved_argumentr� r� r� r� r� 7 s< � � ��z"RelationshipProperty._setup_entityc C s� t | jj| jj| jj| jj| jjj| jjj| jj j| jj | j j | j | j | j| j| | j | jd� | _}|j| _|j | _ |j| _|j| _|j | _ |j| _|j| _|j| _|j| _|j| _d S )N��parent_persist_selectable�child_persist_selectable�parent_local_selectable�child_local_selectabler� r� r� �parent_equivalents�child_equivalents�consider_as_foreign_keysr� r� �self_referentialr� � support_sync�can_be_synced_fn)r� r r� r� � local_tabler� r� r� r� r� Z_equivalent_columnsr� r� r� r� r/ r� �_columns_are_mappedr� r� �remote_columnsr� r� �foreign_key_columnsr� r� )r� Zjcr� r� r� r� g s8 � z+RelationshipProperty._setup_join_conditionsr� c C s | j d S )Nr �r� r� r� r� r� �_clsregistry_resolve_arg� s z-RelationshipProperty._clsregistry_resolve_argz>Callable[[str], Callable[[], Union[Type[Any], Table, _ModNS]]]c C s | j d S )Nr r� r� r� r� r� r� � s z.RelationshipProperty._clsregistry_resolve_namezsqlalchemy.orm.clsregistryzmTuple[Callable[[str], Callable[[], Union[Type[Any], Table, _ModNS]]], Callable[[str, bool], _class_resolver]]c C s t jjj}|| jj| �S r� )r5 r� Zorm_clsregistry� _resolverr r� )r� r� r� r� r� r� � s z+RelationshipProperty._clsregistry_resolversc C sF | j jrBt| j jdd��| j�sBt�d| j| j jj| j jjf ��dS )zOTest that this relationship is legal, warn about inheritance conflicts.Fr� z�Attempting to assign a new relationship '%s' to a non-primary mapper on class '%s'. New relationships can only be added to the primary mapper, i.e. the very first mapper created for class '%s' N) r � non_primaryr r� � has_propertyr� r� r� r� r� r� r� r� r� � s �����z%RelationshipProperty._check_conflictsr. c C s | j S )z\Return the current cascade setting for this :class:`.RelationshipProperty`. )r� r� r� r� r� r� � s z RelationshipProperty.cascadezUnion[str, CascadeOptions])r� r| c C s | � |� d S r� )� _set_cascade�r� r� r� r� r� r� � s )� cascade_argr| c C sJ t |�}| jr t |�t j��}d| jv r2| �|� || _| jrF|| j_d S )Nr� ) r. r� � intersectionZ_viewonly_cascadesr� r� r� r� r� )r� r� r� r� r� r� r� � s � z!RelationshipProperty._set_cascadec C s� |j rV| jsV| jtu s | jtu rVtjd| | jtu r6dnd| jjj | j jj d� dd��| j dkr~d|v spd |v r~t�d | ��|j r�| j � � j �| j| jjf� d S ) Na� For %(direction)s relationship %(rel)s, delete-orphan cascade is normally configured only on the "one" side of a one-to-many relationship, and not on the "many" side of a many-to-one or many-to-many relationship. To force this relationship to allow a particular "%(relatedcls)s" object to be referenced by only a single "%(clsname)s" object at a time via the %(rel)s relationship, which would allow delete-orphan cascade to take place in this direction, set the single_parent=True flag.z many-to-onez many-to-many)�relr� �clsnameZ relatedclsZbbf0��code�allr� r� z^On %s, can't set passive_deletes='all' in conjunction with 'delete' or 'delete-orphan' cascade)Z delete_orphanr� r� r& r' r� r� r r� r� r� r� �primary_mapperZ_delete_orphansr� r� r� r� r� r� r� � sD �������� ���� �z,RelationshipProperty._check_cascade_settingsc C s | j |jv o|j| j | u S )zaReturn True if this property will persist values on behalf of the given mapper. )r� Z relationshipsr� r� r� r� � _persists_for� s �z"RelationshipProperty._persists_for)�colsr| c G sR | j jj}|D ]>}|dur(|j�|�r(q| jjj�|�s| jj�|�s dS qdS )z�Return True if all columns in the given collection are mapped by the tables referenced by this :class:`.RelationshipProperty`. NFT)r� r� r� r� �contains_columnr r� r� )r� r� r� r� r� r� r� r� s � �z(RelationshipProperty._columns_are_mappedc C s� | j jr dS | jdu�rr| j�srt| jt�r:| ji }}n | j\}}| j�� }|js�t |� � �� |j �}|D ](}|� |�rl|jslt�d|| |f ��ql| jdur�|�d| jj�}|�d| jj�}n*|�d| jj�}|�dd�}|r�t�d��|�d| j�}| j �� } |�d| j� |�d| j� |�d | j� |�d | j � || _t | | jf|||| j d �|��} |j || d d � | j�r�| � | j� dS )zlInterpret the 'backref' instruction to create a :func:`_orm.relationship` complementary to this one.Nz]Error creating backref '%s' on relationship '%s': property of that name exists on mapper '%s'r� r� zOCan't assign 'secondaryjoin' on a backref against a non-secondary relationship.r� r� r� r� r� )r� r� r� r� T)Zwarn_for_existing)!r r� r� r� r� r� r� r� Zconcreter� Ziterate_to_root�unionZself_and_descendantsr� r� r� r� �popr� �secondaryjoin_minus_local�primaryjoin_minus_local�primaryjoin_reverse_remoter& r� � setdefaultr� r� r� r� r� r� Z_configure_propertyr� ) r� Z backref_keyr) r� �check�mr r r� r Z relationshipr� r� r� r� sz ��� ��� �� ��� �z&RelationshipProperty._generate_backrefzsqlalchemy.orm.dependencyc C s6 t jj}| jd u r | jtu| _| js2|j�| �| _ d S r� ) r5 r� Zorm_dependencyr� r� r' r� rY Zfrom_relationshipr� )r� � dependencyr� r� r� r� c s ��z RelationshipProperty._post_initc C s | j }|jS )zPmemoize the 'use_get' attribute of this RelationshipLoader's lazyloader.)r� Zuse_get)r� Zstrategyr� r� r� rW n s z RelationshipProperty._use_getc C s | j �| j�S r� )r� r� r r� r� r� r� r/ v s z)RelationshipProperty._is_self_referentialr� z"Optional[_InternalEntityType[Any]]r� z�Tuple[ColumnElement[bool], Optional[ColumnElement[bool]], FromClause, FromClause, Optional[FromClause], Optional[ClauseAdapter]])r r r* r r r� r| c C s d}|r| j d urd}|d u r2|r2| jjr2| jj}|rP|j}|d u rV|j}d}n| j}|d u r�| jj}| jjrrd}| jr�|d u r�|�� }d}n|| jjus�| jjr�d}|j } |p�|d uo�|| jjup�|j }| j � |||| |�\} } } } }|d u r�| jj }|d u �r | jj }| | ||| | fS )NFT)r� r Zwith_polymorphicr r� r r� r/ r0 r1 Z _is_subqueryr� � join_targetsr� )r� r r r* r r r� �aliasedZ dest_mapperr7 r� r� r� r r� r� r� r z sp ������ �z"RelationshipProperty._create_joins)NN)TN)FNT)FN)N)N)FNNNFr� )?r� r� r� r� r Z_RELATIONSHIP_TOKENZstrategy_wildcard_key� inherit_cacheZ_links_to_entityZ_is_relationshipr� rH r� r� r� r� r� r5 Z MemoizedSlotsr) rq r� ra r$ rK rf rx r� r! rs r� r� r� r� � staticmethodr� r� �memoized_propertyr� r� r� r� r� r� Zpreload_moduler� r� r� r� r� r� r� �setterr� r� r� r� r� r� rW r/ r � __classcell__r� r� r� r� r� 5 s � ��\ � �Dm � f� �=, L b/ . P �r� rd )�elementr r| c s. ddd�� �fdd� �| d ur&�| �} d �| S )Nry )�elemr| c s* t | tj�r| �� �� �} | j�d� | S )N)�clone)r� r8 r? r3 �copyZ_copy_internals)r� �r r� r� r� r� � s z _annotate_columns.<locals>.cloner� )r� r r� r r� r � s r c @ s, e Zd ZU ded< ded< ded< ded< ded < d ed < d ed < d ed< ded< ded< ded< ded< ded< dddddddddddd� d� dddddddd d d dd d dd d d �d!d"�Zd#d$�d%d&�Zd#d$�d'd(�Zd#d$�d)d*�Zedd$�d+d,��Z edd$�d-d.��Z e j dd$�d/d0��Z d1d2d d3�d4d5�Ze j d d$�d6d7��Ze j d d$�d8d9��Zd#d$�d:d;�Zd#d$�d<d=�Zd#d$�d>d?�Zd d$�d@dA�Zd d$�dBdC�Zd#d$�dDdE�Zd#d$�dFdG�ZdHd d#dI�dJdK�Zd#d$�dLdM�Zd#d$�dNdO�Zd#d$�dPdQ�Zd#d$�dRdS�Z d#d$�dTdU�Z d#d$�dVdW�Z d#d$�dXdY�Z dd d#dZ�d[d\�Z d#d$�d]d^�Z!d_d`da�dbdc�Z"d#d$�ddde�Z#e$�%� Z&dfedg< d#d$�dhdi�Z'e j djd$�dkdl��Z(e j djd$�dmdn��Z)e j djd$�dodp��Z*d2djdq�drds�Z+dtdudjd3�dvdw�Z,e j dxd$�dydz��Z-d�ddd dd|d}d~�dd��Z.d�d d�d��d�d��Z/dS )�r� r� �primaryjoin_initialr� r� r� r� r� r� r� r� r� r� r* r� rj r� r� r� r� r� r� NFTc G s dS �NTr� )r� r� r� r� �<lambda>� � zJoinCondition.<lambda>) r� r� r� r� r� r� r� r� r� r� r� z Optional[_EquivalentColumnMap]r r� zCallable[..., bool]r� c C s� || _ || _|| _|| _|| _| | _|| _|| _|| _| | _ | | _ | | _ || _ | | _ || _|| _| �� | jd usvJ �| �� | �� | �� | �� | �� | �� | �| jd� | jd ur�| �| jd� | �� | �� | �� d S �NTF) r� r� r� r� r� r� r r� r� r� r� � _remote_sider� r� r� r� �_determine_joinsr� �_sanitize_joins� _annotate_fks�_annotate_remote�_annotate_local�_annotate_parentmapper� _setup_pairs�_check_foreign_cols�_determine_direction�_check_remote_side� _log_joins)r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� � s< zJoinCondition.__init__r� r� c C s� | j j}|�d| j | j� |�d| j | j� |�d| j d�dd� | jD ��� |�d| j d�dd� | jpjg D ��� |�d | j d�d d� | jD ��� |�d | j d�d d� | j D ��� |�d | j d�dd� | j D ��� |�d| j | j � d S )Nz%s setup primary join %sz%s setup secondary join %sz%s synchronize pairs [%s]�,c s s | ]\}}d ||f V qdS �z (%s => %s)Nr� �r �lr� r� r� r� r ) s z+JoinCondition._log_joins.<locals>.<genexpr>z#%s secondary synchronize pairs [%s]c s s | ]\}}d ||f V qdS r r� r r� r� r� r 0 s �z%s local/remote pairs [%s]c s s | ]\}}d ||f V qdS )z (%s / %s)Nr� r r� r� r� r 8 s z%s remote columns [%s]c s s | ]}d | V qdS �z%sNr� �r rN r� r� r� r ? r z%s local columns [%s]c s s | ]}d | V qdS r r� r r� r� r� r D r z %s relationship direction %s) r� �loggerr� r� r� �joinr� r� r� r� r� r� )r� r2 r� r� r� r " sF �� �� ����zJoinCondition._log_joinsc C s. t | jdd�| _| jdur*t | jdd�| _dS )a_ remove the parententity annotation from our join conditions which can leak in here based on some declarative patterns and maybe others. "parentmapper" is relied upon both by the ORM evaluator as well as the use case in _join_fixture_inh_selfref_w_entity that relies upon it being present, see :ticket:`3364`. )r� � proxy_key��valuesN)rC r� r� r� r� r� r� r H s � �z JoinCondition._sanitize_joinsc C sz | j dur$| jdu r$t�d| j ��z�| jp.d}| jdur�| j du r\t| j| j| j|d�| _ | j du r�t| j | j| j |d�| _ q�| j | _ n,| j du r�t| j | j| j |d�| _ n| j | _ W n� tj �y } zB| jdur�t� d| j| jf �|�nt� d| j �|�W Y d}~nhd}~0 tj�yt } zD| jdu�rNt�d| j| jf �|�nt�d| j �|�W Y d}~n d}~0 0 dS )z�Determine the 'primaryjoin' and 'secondaryjoin' attributes, if not passed to the constructor already. This is based on analysis of the foreign key relationships between the parent and target mapped selectables. NzMProperty %s specified with secondary join condition but no secondary argument)Za_subsetr� a1 Could not determine join condition between parent/child tables on relationship %s - there are no foreign keys linking these tables via secondary table '%s'. Ensure that referencing columns are associated with a ForeignKey or ForeignKeyConstraint, or specify 'primaryjoin' and 'secondaryjoin' expressions.a Could not determine join condition between parent/child tables on relationship %s - there are no foreign keys linking these tables. Ensure that referencing columns are associated with a ForeignKey or ForeignKeyConstraint, or specify a 'primaryjoin' expression.al Could not determine join condition between parent/child tables on relationship %s - there are multiple foreign key paths linking the tables via secondary table '%s'. Specify the 'foreign_keys' argument, providing a list of those columns which should be counted as containing a foreign key reference from the secondary table to each of the parent and child tables.a' Could not determine join condition between parent/child tables on relationship %s - there are multiple foreign key paths linking the tables. Specify the 'foreign_keys' argument, providing a list of those columns which should be counted as containing a foreign key reference to the parent table.)r� r� r� r� r� r� rG r� r� r r� r� r� ZNoForeignKeysErrorZAmbiguousForeignKeysError)r� r� ZnfeZafer� r� r� r Z s� �� � � � �� � ��� �� � ���z JoinCondition._determine_joinsc C s t | jdd�S �N��localr} r )rC r� r� r� r� r� r� � s z%JoinCondition.primaryjoin_minus_localc C s | j d usJ �t| j dd�S r )r� rC r� r� r� r� r� � s z'JoinCondition.secondaryjoin_minus_localc C sJ | j r(dddd�dd�}t�| ji |�S | jr<t| jdd�S t| j�S d S ) a( Return the primaryjoin condition suitable for the "reverse" direction. If the primaryjoin was delivered here with pre-existing "remote" annotations, the local/remote annotations are reversed. Otherwise, the local/remote annotations are removed. ry r � Optional[_CE]�r� r� r| c [ s\ d| j v r,t| j �}|d= d|d< | �|�S d| j v rXt| j �}|d= d|d< | �|�S d S )Nr} Tr )� _annotationsrH Z_with_annotations)r� r� r� r� r� r� �replace� s z9JoinCondition.primaryjoin_reverse_remote.<locals>.replacer r N)�_has_remote_annotationsr; �replacement_traverser� �_has_foreign_annotationsrC )r� r# r� r� r� r� � s �z(JoinCondition.primaryjoin_reverse_remoterh r� )r r� r| c C s& t �|i �D ]}||jv r dS q dS r )r; �iterater" )r� r r� rN r� r� r� �_has_annotation� s z JoinCondition._has_annotationc C s | � | jd�S �Nr� �r( r� r� r� r� r� r& � s z&JoinCondition._has_foreign_annotationsc C s | � | jd�S �Nr} r* r� r� r� r� r$ � s z%JoinCondition._has_remote_annotationsc C s& | j r dS | jr| �� n| �� dS )z�Annotate the primaryjoin and secondaryjoin structures with 'foreign' annotations marking columns considered as foreign. N)r& r� �_annotate_from_fk_list�_annotate_present_fksr� r� r� r� r � s zJoinCondition._annotate_fksc sH dddd�� fdd� }t �� ji |�� _� jd urDt �� ji |�� _d S )Nry r r r! c s | � j v r| �ddi�S d S �Nr� T)r� r3 �r� r� r� r� r� �check_fk s z6JoinCondition._annotate_from_fk_list.<locals>.check_fk)r; r% r� r� )r� r0 r� r� r� r, s � �z$JoinCondition._annotate_from_fk_listc s� | j d urt�| j j��nt� �dddd��fdd� � ddd�� fd d � }t�| ji d |i�| _| jd ur�t�| ji d |i�| _d S ) Nrz z Optional[ColumnElement[Any]])�a�br| c sd t | tj�r4t |tj�r4| �|�r&| S |�| �r4|S � r`| � v rL|� vrL| S |� v r`| � vr`|S d S r� )r� r3 ZColumnZ references)r1 r2 )� secondarycolsr� r� � is_foreign s z7JoinCondition._annotate_present_fks.<locals>.is_foreign�BinaryExpression[Any]r� ��binaryr| c s� t | jtj�r t | jtj�s d S d| jjvr�d| jjvr�� | j| j�}|d ur�|�| j�rn| j�ddi�| _n |�| j�r�| j�ddi�| _d S r. )r� �leftr4 r@ �rightr" �comparer3 )r7 rN )r4 r� r� � visit_binary) s$ � � � � �z9JoinCondition._annotate_present_fks.<locals>.visit_binaryr7 ) r� r5 r� r� r� r; rm r� r� �r� r; r� )r4 r3 r� r- s � �z#JoinCondition._annotate_present_fksc s@ | j �| j� d�ddd�� ��fdd� }t�| ji d|i� �S )zvReturn True if the join condition contains column comparisons where both columns are in both tables. Fr5 r� r6 c s^ | j | j }}t|tj�rZt|tj�rZ��|j�rZ��|j�rZ� �|j�rZ� �|j�rZd�d S r )r8 r9 r� r8 r? Zis_derived_from�table)r7 r� �f��mt�pt�resultr� r� r; M s � � � � � �z;JoinCondition._refers_to_parent_table.<locals>.visit_binaryr7 )r� r� r; r2 r� r< r� r? r� �_refers_to_parent_tableD s z%JoinCondition._refers_to_parent_tablec C s t | j| j�S )z5Return True if parent/child tables have some overlap.)rH r� r� r� r� r� r� �_tables_overlap] s �z JoinCondition._tables_overlapc C sl | j r dS | jdur | �� nJ| js*| jr4| �� n4| �� rN| �dd� d� n| �� r`| � � n| � � dS )z�Annotate the primaryjoin and secondaryjoin structures with 'remote' annotations marking columns considered as part of the 'remote' side. Nc S s d| j v S r) �r" rO r� r� r� r s r z0JoinCondition._annotate_remote.<locals>.<lambda>F) r$ r� �_annotate_remote_secondaryr� r �_annotate_remote_from_argsrC �_annotate_selfrefrD � _annotate_remote_with_overlap�%_annotate_remote_distinct_selectablesr� r� r� r� r d s � z JoinCondition._annotate_remotec s` | j dusJ �| j � dddd�� fdd� }t�| ji |�| _| jdusJJ �t�| ji |�| _dS )z^annotate 'remote' in primaryjoin, secondaryjoin when 'secondary' is present. Nry r r r! c s � j �| �r| �ddi�S d S �Nr} T)r� r� r3 r/ �Zfixed_secondaryr� r� �repl� s z6JoinCondition._annotate_remote_secondary.<locals>.repl)r� r; r% r� r� �r� rM r� rL r� rF z s ��z(JoinCondition._annotate_remote_secondaryz$Callable[[ColumnElement[Any]], bool])�fn�remote_side_givenr| c s2 ddd�� ��fdd� }t ��ji d|i��_dS )zxannotate 'remote' in primaryjoin, secondaryjoin when the relationship is detected as self-referential. r5 r� r6 c sx | j �| j�}t| j tj�rht| jtj�rh� | j �rF| j �ddi�| _ � | j�rt|st| j�ddi�| _n �st��� d S rK )r8 r: r9 r� r8 r? r3 �_warn_non_column_elements)r7 Zequated�rO rP r� r� r� r; � s � z5JoinCondition._annotate_selfref.<locals>.visit_binaryr7 N)r; rm r� )r� rO rP r; r� rR r� rH � s �z JoinCondition._annotate_selfrefc sx | j r(| jrt�d��dd� | j D �� n| j� | �� rL| �� fdd�d� n(ddd d �� fd d � }t�| ji |�| _d S )z�annotate 'remote' in primaryjoin, secondaryjoin when the 'remote_side' or '_local_remote_pairs' arguments are used. zTremote_side argument is redundant against more detailed _local_remote_side argument.c S s g | ] \}}|�qS r� r� r r� r� r� rU � r z<JoinCondition._annotate_remote_from_args.<locals>.<listcomp>c s | � v S r� r� rO �r� r� r� r � r z:JoinCondition._annotate_remote_from_args.<locals>.<lambda>Try r r r! c s | t � �v r| �ddi�S d S rK )r� r3 r/ rS r� r� rM � s z6JoinCondition._annotate_remote_from_args.<locals>.replN) r� r r� r� rC rH r; r% r� rN r� rS r� rG � s ��z(JoinCondition._annotate_remote_from_argsc s` ddd��fdd� }�j duo,�j j�j ju� dddd �� �fd d � �t��ji d |i��_dS ) z�annotate 'remote' in primaryjoin, secondaryjoin when the parent/child tables have some set of tables in common, though is not a fully self-referential relationship. r5 r� r6 c s0 � | j | j�\| _ | _� | j| j �\| _| _ d S r� �r8 r9 )r7 )�proc_left_rightr� r� r; � s � �zAJoinCondition._annotate_remote_with_overlap.<locals>.visit_binaryNrz z-Tuple[ColumnElement[Any], ColumnElement[Any]])r8 r9 r| c s� t | tj�rDt |tj�rD�jj�|�r��jj�| �r�|�ddi�}nX� rl|j� d��j j u rl|�ddi�}n0� r�| j� d��j j u r�| �ddi�} n�� � | |fS )Nr} Tr� ) r� r8 r? r� r� r� r� r3 r" r� r� r� rQ rT )�check_entitiesr� r� r� rU � s* �� �����zDJoinCondition._annotate_remote_with_overlap.<locals>.proc_left_rightr7 )r� r� r r; rm r� r< r� )rV rU r� r� rI � s � �z+JoinCondition._annotate_remote_with_overlapc s, dddd�� fdd� }t �� ji |�� _dS )z}annotate 'remote' in primaryjoin, secondaryjoin when the parent/child tables are entirely separate. ry r r r! c s< � j j�| �r8� jj�| �r*� jj�| �r8| �ddi�S d S rK )r� r� r� r� r� r3 r/ r� r� r� rM s � �zAJoinCondition._annotate_remote_distinct_selectables.<locals>.replN�r; r% r� rN r� r� r� rJ � s �z3JoinCondition._annotate_remote_distinct_selectablesc C s t �d| j � d S )Nz�Non-simple column elements in primary join condition for property %s - consider using remote() annotations to mark the remote side.)r5 r� r� r� r� r� r� rQ s ��z'JoinCondition._warn_non_column_elementsc sj | � | jd�rdS | jr0t�dd� | jD ��� nt�| jj�� dddd�� fd d � }t�| ji |�| _dS ) aC Annotate the primaryjoin and secondaryjoin structures with 'local' annotations. This annotates all column elements found simultaneously in the parent table and the join condition that don't have a 'remote' annotation set up from _annotate_remote() or user-defined. r Nc S s g | ] \}}|�qS r� r� r r� r� r� rU & r z1JoinCondition._annotate_local.<locals>.<listcomp>ry r r r! c s$ d| j vr | � v r | �ddi�S d S )Nr} r T)r" r3 r/ �Z local_sider� r� �locals_+ s z.JoinCondition._annotate_local.<locals>.locals_) r( r� r� r5 r� r� r� r; r% )r� rY r� rX r� r s ��z JoinCondition._annotate_localc s, dddd�� fdd� }t �� ji |�� _d S )Nry r r r! c s< d| j v r | �d� jji�S d| j v r8| �d� jji�S d S )Nr} r� r )r" r3 r� r� r r/ r� r� r� �parentmappers_5 s z<JoinCondition._annotate_parentmapper.<locals>.parentmappers_rW )r� rZ r� r� r� r 4 s �z$JoinCondition._annotate_parentmapperc C s^ | j st�d| jf ��n@t�| jj��| j j�}| j D ] \}}||v r8t� d|f � q8d S )Na Relationship %s could not determine any unambiguous local/remote column pairs based on join condition and remote_side arguments. Consider using the remote() annotation to accurately mark those elements of the join condition that are on the remote side of the relationship.z�Expression %s is marked as 'remote', but these column(s) are local to the local side. The remote() annotation is needed only for a self-referential relationship where both sides of the relationship refer to the same tables.) r� r� r� r� r5 r� r� r� � differencer� r� )r� Z not_target�_Zrmtr� r� r� r @ s$ �� ����z JoinCondition._check_remote_side)rG �primaryr| c C s� | � |d�}t|�}|r$t| j�}n t| j�}| jr8|sB| jsF|rFdS | jr�|r�|s�d|r^dp`d|| jf }|d7 }t�|��n*d|r�dp�d|| jf }|d7 }t�|��dS ) zHCheck the foreign key columns collected and emit error messages.r� Nz�Could not locate any simple equality expressions involving locally mapped foreign key columns for %s join condition '%s' on relationship %s.r] r� a Ensure that referencing columns are associated with a ForeignKey or ForeignKeyConstraint, or are annotated in the join condition with the foreign() annotation. To allow comparison operators other than '==', the relationship can be marked as viewonly=True.z`Could not locate any relevant foreign key columns for %s join condition '%s' on relationship %s.z� Ensure that referencing columns are associated with a ForeignKey or ForeignKeyConstraint, or are annotated in the join condition with the foreign() annotation.)� _gather_columns_with_annotationr� r� r� r� r� r� r� )r� rG r] Z foreign_colsZ has_foreignZcan_sync�errr� r� r� r \ sN � ���� ��� � ��� �z!JoinCondition._check_foreign_colsc C s� | j durt| _n�t�| jj�}t�| jj�}|�| j �}|�| j �}|r�|r�| � | j dd�}dd� | � | j d�D �}|r�|r�| j �| j �}|�|�}|�|�}|r�|s�t| _q�|r�|s�t| _q�t�d| j ��n(|r�t| _n |r�t| _nt�d| j ��dS )z[Determine if this relationship is one to many, many to one, many to many. Nr} r� c S s h | ]}d |j vr|�qS )r} rE �r r� r� r� r� � <setcomp>� s �z5JoinCondition._determine_direction.<locals>.<setcomp>aD Can't determine relationship direction for relationship '%s' - foreign key columns within the join condition are present in both the parent and the child's mapped tables. Ensure that only those columns referring to a parent column are marked as foreign, either via the foreign() annotation or via the foreign_keys argument.z�Can't determine relationship direction for relationship '%s' - foreign key columns are present in neither the parent nor the child's mapped tables)r� r& r� r5 r� r� r� r� r� r� r^ r� r� r� r[ r( r' r� r� r� )r� Z parentcolsZ targetcolsZ onetomany_fkZ manytoone_fkZonetomany_localZmanytoone_localZ self_equatedr� r� r� r � sN ��� � �� ��z"JoinCondition._determine_direction�_ColumnPairIterable�_MutableColumnPairs)r� r| c C s dd� |D �S )z�provide deannotation for the various lists of pairs, so that using them in hashes doesn't incur high-overhead __eq__() comparisons against original columns mapped. c S s g | ]\}}|� � |� � f�qS r� �Z _deannotaterR r� r� r� rU � r z3JoinCondition._deannotate_pairs.<locals>.<listcomp>r� )r� r� r� r� r� �_deannotate_pairs� s z JoinCondition._deannotate_pairsc s� g }t �g �� g }dddd�� �fdd� }�j|f�j|ffD ] \}}|d u rPq>|||� q>��� ��_��|��_��|��_d S )Nr� rc r� )�joincondr� r| c s* ddddd�� ��fdd� }t || � d S )Nr5 rz r� )r7 r8 r9 r| c s� d|j v r.d|j vr.��|�r.��||f� n,d|j v rZd|j vrZ��|�rZ��||f� | jtju r���||�r�d|j v r�� �||f� nd|j v r�� �||f� d S )Nr} r� )r" r� r� �operatorr9 �eqr� )r7 r8 r9 )r� �lrpr� r� r� r; s* ������� z<JoinCondition._setup_pairs.<locals>.go.<locals>.visit_binaryrI )rf r� r; �ri r� )r� r� �go s z&JoinCondition._setup_pairs.<locals>.go)r5 Z OrderedSetr� r� re r� r� r� )r� Z sync_pairsZsecondary_sync_pairsrk rf r� r� rj r� r � s � � �zJoinCondition._setup_pairszwweakref.WeakKeyDictionary[ColumnElement[Any], weakref.WeakKeyDictionary[RelationshipProperty[Any], ColumnElement[Any]]]� _track_overlapping_sync_targetsc s� | j s d S dd� | jD �dd� | jD � D �]b\}� � | jvrVt�| j|i�| j� < q*g }| j� }|�� D ]�\}}|jj sl|| jj vrl|j | jj vrl| jj |j vrld| jj vrld|j vrl| jj �|j �sl| jj�|j�sl| jj �|j�sl| jj�|j �sl| jj |j k�s| jj �|j �sl|�||f� ql|�r~tjd| j|� d�t� fdd�|D ���d �td d� |D ���| jf d d � || j� | j< q*d S ) Nc S s g | ]\}}||f�qS r� r� �r �from_�to_r� r� r� rU > s zDJoinCondition._warn_for_conflicting_sync_targets.<locals>.<listcomp>c S s g | ]\}}||f�qS r� r� rm r� r� r� rU @ s z__*a relationship '%s' will copy column %s to column %s, which conflicts with relationship(s): %s. If this is not the intention, consider if these relationships should be linked with back_populates, or if viewonly=True should be applied to one or more if they are read-only. For the less common case that foreign key constraints are partially overlapping, the orm.foreign() annotation can be used to isolate the columns that should be written towards. To silence this warning, add the parameter 'overlaps="%s"' to the '%s' relationship.z, c 3 s | ]\}}d ||� f V qdS )z'%s' (copies %s to %s)Nr� )r �pr�fr_�ro r� r� r s �zCJoinCondition._warn_for_conflicting_sync_targets.<locals>.<genexpr>r c s s | ]\}}|j V qd S r� �r� )r rp �frr� r� r� r � r Zqzyxr� )r� r� r� rl �weakref�WeakKeyDictionaryr� r� r� Z_dispose_calledr� r� r� r Z is_siblingr� r� r5 r� r �sorted)r� rn Z other_propsZ prop_to_fromrp rq r� rr r� r� 5 st ��� � � � � � � � ���� �� ����� z0JoinCondition._warn_for_conflicting_sync_targetsr� c C s | � d�S r+ ��_gather_join_annotationsr� r� r� r� r� � s z JoinCondition.remote_columnsc C s | � d�S )Nr rx r� r� r� r� r� � s zJoinCondition.local_columnsc C s | � d�S r) rx r� r� r� r� r� � s z!JoinCondition.foreign_key_columns)r� r| c C s> t | �| j|��}| jd ur0|�| �| j|�� dd� |D �S )Nc S s h | ] }|� � �qS r� rd r� r� r� r� ra � r z9JoinCondition._gather_join_annotations.<locals>.<setcomp>)r� r^ r� r� r� )r� r� �sr� r� r� ry � s � ��z&JoinCondition._gather_join_annotationsrz z Iterable[str]c s" t |�� � fdd�t�|i �D �S )Nc s& h | ] }� � |j�rttt |��qS r� )�issubsetr" r r@ r r �Zannotation_setr� r� ra � s �z@JoinCondition._gather_columns_with_annotation.<locals>.<setcomp>)r� r; r' )r� r r� r� r| r� r^ � s �z-JoinCondition._gather_columns_with_annotationz FrozenSet[ColumnElement[Any]]c C s0 | j d ur&ttjdd� | j jD �� �S tjS d S )Nc S s g | ] }|j �qS r� )Z proxy_setr` r� r� r� rU � r z8JoinCondition._secondary_lineage_set.<locals>.<listcomp>)r� � frozenset� itertools�chainr� r5 � EMPTY_SETr� r� r� r� �_secondary_lineage_set� s �z$JoinCondition._secondary_lineage_setr� r� ztTuple[ColumnElement[bool], Optional[ColumnElement[bool]], Optional[FromClause], Optional[ClauseAdapter], FromClause])r r* r� r7 r� r| c sj t |ddi�}�j�j�j }}}|durF|dur>||@ }n||@ }|r�dddd��fdd� � t� fd d �|D ��}|dur�|tj|� @ }n|tj|� @ }|�rX|du�r|jdd �}t|t d �} t|�j d �� | �} |dur�t|t d �� t|�j d ��} | � |�}n4t|t �j d�} |du�r8| � t|t�j d�� d} | � |�}| �pN| } d| _nd} |||| |fS )a7 Given a source and destination selectable, create a join between them. This takes into account aliasing the join clause to reference the appropriate corresponding columns in the target objects, as well as the extra child criterion, equivalent column sets, etc. r, TNre rd )r� r r| c sB | j �dd�}|� jjur:|� jjur:| � jvr:t| |�S | S dS )a note unrelated columns in the "extra criteria" as either should be adapted or not adapted, even though they are not part of our "local" or "remote" side. see #9779 for this case, as well as #11010 for a follow up r� N)r" r� r� r r� r� r> )r� r Zparentmapper_for_elementr� r� r� �mark_exclude_cols� s � � �� z5JoinCondition.join_targets.<locals>.mark_exclude_colsc 3 s | ]}t |d di� d�V qdS )�should_not_adaptT)Zannotate_callableNrA )r r� )r� r� r� r s ��z-JoinCondition.join_targets.<locals>.<genexpr>)Zflat)� exclude_fn)� equivalents)r� r� )rD r� r� r� r r4 r r0 rF �_local_col_excluder� r r� r2 �_remote_col_excluder� ) r� r r* r� r7 r� r� r� r� Zprimary_aliasizerZsecondary_aliasizerr r� )r� r� r� r� � s� �� � ������ � �� �zJoinCondition.join_targetszgTuple[ColumnElement[bool], Dict[str, ColumnElement[Any]], Dict[ColumnElement[Any], ColumnElement[Any]]])rn r| c s i � i }| j d u��rLt�t��| jD ]"\}}�| �||f� |||< q&n6�sj| jD ]\}}|||< qVn| jD ]\}}|||< qpdddd�� ���fdd� }| j}| j d u s��s�t�|i |�}| j d ur�| j }�r�t�|i |�}t � ||�}� fdd�� D �}|||fS ) Nrz r z Optional[BindParameter[Any]]r! c sX �sd| j v s,�rT�r | �v s,�sTd| j v rT| � vrLtjd d | jdd�� | < � | S d S )Nr r} T)rF rG )r" r4 rI rJ r/ ��bindsZ has_secondary�lookuprn r� r� � col_to_bindY s( ������� � z5JoinCondition.create_lazy_clause.<locals>.col_to_bindc s i | ]}� | j |�qS r� rs r )r� r� r� � <dictcomp>y r z4JoinCondition.create_lazy_clause.<locals>.<dictcomp>) r� � collections� defaultdict�listr� r� r� r; r% r4 r ) r� rn Zequated_columnsr r� r� Z lazywherer� rc r� r� r� �create_lazy_clauseC s8 � � z JoinCondition.create_lazy_clause)Nr� )F)0r� r� r� r� r� r r r r� r� r� r5 r� r� r( r& r$ r r, r- rC rD r rF rH rG rI rJ rQ r r r r r re r ru rv rl r� r� r� r� ry r^ r� r� r� r� r� r� r� r� � s� �05&_$2!1 AR 9� V � r� c @ s2 e Zd ZdZdZdd�dd�Zddd�d d �Zd S ) �_ColInAnnotationsz�Serializable object that tests for names in c._annotations. TODO: does this need to be serializable anymore? can we find what the use case was for that? )�namesr� c G s t |�| _d S r� )r} r� )r� r� r� r� r� r� � s z_ColInAnnotations.__init__rh r� )r� r| c C s t | j�|j��S r� )r� r� r� r" )r� r� r� r� r� �__call__� s z_ColInAnnotations.__call__N)r� r� r� r� r� r� r� r� r� r� r� r� ~ s r� r r� c @ s e Zd ZdZdZdS )� Relationshipa� Describes an object property that holds a single item or list of items that correspond to a related database table. Public constructor is the :func:`_orm.relationship` function. .. seealso:: :ref:`relationship_config_toplevel` .. versionchanged:: 2.0 Added :class:`_orm.Relationship` as a Declarative compatible subclass for :class:`_orm.RelationshipProperty`. TN)r� r� r� r� r� r� r� r� r� r� � s r� c @ s& e Zd ZdZdZedd�dd��ZdS )�_RelationshipDeclaredz>Relationship subclass used implicitly for declarative mapping.Tr� r� c C s dS )Nr� r� )r� r� r� r� �_mapper_property_name� s z+_RelationshipDeclared._mapper_property_nameN)r� r� r� r� r� � classmethodr� r� r� r� r� r� � s r� )�r� � __future__r r� r Z dataclassesr6 r� r~ r� r� r r r r r r r r r r r r r r r r r r r ru � r r Z_typingr r �baser r r r r r! r" r# Z interfacesr$ r% r& r' r( r) r* r+ r5 r, r- r. r0 r� r1 r2 r3 r4 Z inspectionr7 r8 r9 r: r; Z sql._typingr< r= Zsql.annotationr> Z sql.elementsr? r@ Zsql.utilrB rC rD rE rF rG rH rJ Z util.typingrK rL rM � TYPE_CHECKINGrN rO rP rQ rR rS rT rU Z clsregistryrV rW Z decl_baserX r� rY r� rZ �queryr[ ry r\ rD r] � strategiesr^ r_ r` ra rb rc rd re rf rg rh Z sql.schemari Zsql.selectablerj rk rl rm ro rp rq rr r� Z_RelationshipArgumentTyper� r� Z"_RelationshipJoinConditionArgumentZ _RelationshipSecondaryArgumentr� ZORMBackrefArgumentZ DMLColumnRoleZ_ORMColCollectionElementZ_ORMColCollectionArgumentrx ry rb r� rc r} r� Z dataclassr� r� r� Z class_loggerZ Identifiedr� r r� r� r� r� r� r� r� r� r� r� �<module> s� �� � ���� �� �� � ' , � � sqlalchemy/orm/__pycache__/state_changes.cpython-39.pyc 0000644 00000011466 15125143220 0017157 0 ustar 00 a ��Jh� � @ s� d Z ddlmZ ddlZddlmZ ddlmZ ddlmZ ddlm Z ddlm Z dd lm Z dd lm Z dd lm Z dd lmZ dd lmZ ddlmZ ddlmZ ddlmZ ededef d�ZG dd� de�ZG dd� de�ZG dd� d�ZdS )z9State tracking utilities used by :class:`_orm.Session`. � )� annotationsN)�Enum)�Any)�Callable)�cast)�Iterator)�NoReturn)�Optional)�Tuple)�TypeVar)�Union� )�exc)�util)�Literal�_F.)�boundc @ s e Zd ZdS )�_StateChangeStateN)�__name__� __module__� __qualname__� r r �Q/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/state_changes.pyr ! s r c @ s e Zd ZdZdZdZdS )�_StateChangeStates� r � N)r r r �ANY� NO_CHANGE�CHANGE_IN_PROGRESSr r r r r % s r c @ sx e Zd ZU dZejZded< ejZ ded< dZ ded< ddd d �d d �Z e d ddd�dd��Z ejddd�dd��ZdS )� _StateChangea! Supplies state assertion decorators. The current use case is for the :class:`_orm.SessionTransaction` class. The :class:`_StateChange` class itself is agnostic of the :class:`_orm.SessionTransaction` class so could in theory be generalized for other systems as well. r � _next_state�_stateNz Optional[Callable[..., Any]]� _current_fn�strr )�operation_name�state�returnc C s t jd|� d|��dd��d S )NzCan't run operation 'z ()' when Session is in state �isce��code)�sa_exc�IllegalStateChangeError)�selfr$ r% r r r � _raise_for_prerequisite_state9 s ��z*_StateChange._raise_for_prerequisite_statezEUnion[Literal[_StateChangeStates.ANY], Tuple[_StateChangeState, ...]]zCallable[[_F], _F])�prerequisite_states�moves_tor& c sT |s J d��|t ju�td|���t ju� tjdddddd�� ���fdd� �}|S )a� Method decorator declaring valid states. :param prerequisite_states: sequence of acceptable prerequisite states. Can be the single constant _State.ANY to indicate no prerequisite state :param moves_to: the expected state at the end of the method, assuming no exceptions raised. Can be the constant _State.NO_CHANGE to indicate state should not change at the end of the method. zno prequisite states sentz Tuple[_StateChangeState, ...]r r )�fnr, �arg�kwr& c s� |j }�r |�vr |�| j|� |j}|j}� r4�n|}|tjur�� r�||ur�|r�|tjtjfv r�t j d| j� d|j� d���dd��n"t j d| j� d��d|��dd��| |_tj|_z�z| |g|�R i |��}W n � Y n�0 |j |u �r|W ||_||_S |j |u �r.t j d| j� d ��d �dd��nL|�r\t j d |j� d | j� d |j ��dd��n t j d| j� d |j ��dd��W ||_||_n||_||_0 d S )NzMethod 'z"()' can't be called here; method 'zN()' is already in progress and this would cause an unexpected state change to r' r( zCant run operation 'z ()' here; will move to state z where we are expecting z ()' failed to change state to z as expectedzWhile method 'z()' was running, method 'z)()' caused an unexpected state change to ) r! r- r r r" r r r r r* r+ ) r0 r, r1 r2 Z current_state� next_stateZ existing_fnZ expect_stateZ ret_value�Zexpect_state_changeZhas_prerequisite_statesr/ Z prerequisite_state_collectionr r �_go_ s� �� ���� ��� ��� � �� ��� ���z(_StateChange.declare_states.<locals>._go)r r r r r � decorator)�clsr. r/ r5 r r4 r �declare_statesB s �� "Mz_StateChange.declare_statesz Iterator[Any])�expectedr& c c sp | j tju sJ d��|| _ zFz dV W n � Y n"0 | j|urVtjd| j��dd��W tj| _ n tj| _ 0 dS )zxcalled within a method that changes states. method must also use the ``@declare_states()`` decorator. zAUnexpected call to _expect_state outside of state-changing methodNzUnexpected state change to r' r( )r r r r! r* r+ )r, r9 r r r � _expect_state� s � �z_StateChange._expect_state)r r r �__doc__r r r �__annotations__r r! r" r- � classmethodr8 � contextlib�contextmanagerr: r r r r r + s lr )r; � __future__r r> �enumr �typingr r r r r r r r r � r r* r Z util.typingr r r r r r r r r �<module> s& sqlalchemy/orm/__pycache__/exc.cpython-39.pyc 0000644 00000017540 15125143220 0015125 0 ustar 00 a ��Jh� � @ s� d Z ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z d d l m Z d d l m Z d d l m Z d dl mZ d dl mZ er�d dlmZ d dlmZ d dlmZ e ded�ZeefZG dd� dej�ZeZ G dd� dej�Z G dd� dej �Z G dd � d ej �Z!G d d � d ej�Z"G d d � d ej�Z#G d!d"� d"e!�Z$G d#d$� d$e!�Z%G d%d&� d&ej �Z&G d'd(� d(ej �Z'G d)d*� d*ej �Z(d+d,d-�d.d/�Z)e �*d0�d+d1d-�d2d3��Z+d4S )5zSQLAlchemy ORM exceptions.� )� annotations)�Any)�Optional)�Tuple)�Type)� TYPE_CHECKING)�TypeVar� )� _mapper_property_as_plain_name� )�exc)�util)�MultipleResultsFound)� NoResultFound)�LoaderStrategy)�MapperProperty)� InstanceState�_T)�boundc @ s e Zd ZdZdS )�StaleDataErroraa An operation encountered database state that is unaccounted for. Conditions which cause this to happen include: * A flush may have attempted to update or delete rows and an unexpected number of rows were matched during the UPDATE or DELETE statement. Note that when version_id_col is used, rows in UPDATE or DELETE statements are also matched against the current known version identifier. * A mapped object with version_id_col was refreshed, and the version number coming back from the database does not match that of the object itself. * A object is detached from its parent object, however the object was previously attached to a different parent identity which was garbage collected, and a decision cannot be made if the new parent was really the most recent "parent". N��__name__� __module__� __qualname__�__doc__� r r �G/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/exc.pyr $ s r c @ s e Zd ZdZdS )� FlushErrorz0A invalid condition was detected during flush().Nr r r r r r @ s r c @ s e Zd ZdZdS )�MappedAnnotationErrorz�Raised when ORM annotated declarative cannot interpret the expression present inside of the :class:`.Mapped` construct. .. versionadded:: 2.0.40 Nr r r r r r D s r c @ s e Zd ZdZdS )� UnmappedErrorz?Base for exceptions that involve expected mappings not present.Nr r r r r r M s r c @ s e Zd ZdZdS )�ObjectDereferencedErrorzPAn operation cannot complete due to an object being garbage collected. Nr r r r r r Q s r c @ s e Zd ZdZdZdS )�DetachedInstanceErrorzSAn attempt to access unloaded attributes on a mapped instance that is detached.Zbhk3N)r r r r �coder r r r r! X s r! c @ s: e Zd ZdZe�d�d ddd�dd��Zd d �d d �ZdS )�UnmappedInstanceErrorz;An mapping operation was requested for an unknown instance.�sqlalchemy.orm.baseN�object� Optional[str])�obj�msgc C s� t jj}|sxz*|�t|�� tt|��}d||f }W n@ tyv dtt|��� d�}t|t�rr|dt|� 7 }Y n0 t� | |� d S )Nz�Class %r is mapped, but this instance lacks instrumentation. This occurs when the instance is created before sqlalchemy.orm.mapper(%s) was called.�Class '�' is not mappedz;; was a class (%s) supplied where an instance was required?) r � preloaded�orm_baseZ class_mapper�type�_safe_cls_name�UnmappedClassError� isinstancer �__init__)�selfr' r( �base�namer r r r1 b s$ �� �� z UnmappedInstanceError.__init__r ��returnc C s | j d | jd ffS �Nr �� __class__�args�r2 r r r � __reduce__y s z UnmappedInstanceError.__reduce__)N�r r r r r �preload_moduler1 r< r r r r r# _ s r# c @ s0 e Zd ZdZd ddd�dd�Zdd �d d �ZdS ) r/ z8An mapping operation was requested for an unknown class.NzType[_T]r& )�clsr( c C s |s t |�}t�| |� d S )N)�_default_unmappedr r1 )r2 r? r( r r r r1 � s zUnmappedClassError.__init__r r5 c C s | j d | jd ffS r7 r8 r; r r r r< � s z UnmappedClassError.__reduce__)N)r r r r r1 r< r r r r r/ } s r/ c @ s: e Zd ZdZe�d�d ddd�dd��Zd d �d d �ZdS )�ObjectDeletedErrora� A refresh operation failed to retrieve the database row corresponding to an object's known primary key identity. A refresh operation proceeds when an expired attribute is accessed on an object, or when :meth:`_query.Query.get` is used to retrieve an object which is, upon retrieval, detected as expired. A SELECT is emitted for the target row based on primary key; if no row is returned, this exception is raised. The true meaning of this exception is simply that no row exists for the primary key identifier associated with a persistent object. The row may have been deleted, or in some cases the primary key updated to a new value, outside of the ORM's management of the target object. r$ NzInstanceState[Any]r& )�stater( c C s, t jj}|sd|�|� }tj�| |� d S )NzDInstance '%s' has been deleted, or its row is otherwise not present.)r r+ r, � state_str�sa_exc�InvalidRequestErrorr1 )r2 rB r( r3 r r r r1 � s ��zObjectDeletedError.__init__r r5 c C s | j d | jd ffS r7 r8 r; r r r r< � s z ObjectDeletedError.__reduce__)Nr= r r r r rA � s rA c @ s e Zd ZdZdS )�UnmappedColumnErrorz5Mapping operation was requested on an unknown column.Nr r r r r rF � s rF c @ s& e Zd ZdZdddddd�dd �Zd S ) �LoaderStrategyExceptionz2A loader strategy for an attribute does not exist.� Type[Any]zMapperProperty[Any]z#Optional[Type[MapperProperty[Any]]]z Optional[Type[LoaderStrategy]]zTuple[Any, ...])�applied_to_property_type�requesting_property� applies_to�actual_strategy_type� strategy_keyc C sX |d u r t j�| d||f � n4|d us,J �t j�| dt�|�|t|�t|�f � d S )Nz Can't find strategy %s for %szuCan't apply "%s" strategy to property "%s", which is a "%s"; this loader strategy is intended to be used with a "%s".)rD rE r1 r Zclsname_as_plain_namer )r2 rI rJ rK rL rM r r r r1 � s$ �� ���z LoaderStrategyException.__init__N)r r r r r1 r r r r rG � s rG rH �str)r? r6 c C sJ zd� | j| jf�}W n. tyD t| dd �}|d u r@t| �}Y n0 |S )N�.r )�joinr r �AttributeError�getattr�repr)r? �cls_namer r r r. � s r. r$ r& c C sX t jj}z|�| �j}W n ttft y6 i }Y n0 t| �}|sPd|� d�S d S d S )Nr) r* ) r r+ r, Zmanager_of_class�mappersr/ � TypeError�NO_STATEr. )r? r3 rU r4 r r r r@ � s �� r@ N),r � __future__r �typingr r r r r r r r � r rD r r Z interfacesr r rB r r rQ �KeyErrorrW ZSQLAlchemyErrorr ZConcurrentModificationErrorr � ArgumentErrorr rE r r r! r# r/ rA rF rG r. r> r@ r r r r �<module> sB $! sqlalchemy/orm/__pycache__/base.cpython-39.pyc 0000644 00000060166 15125143220 0015262 0 ustar 00 a ��Jhmk � @ s& d Z ddlmZ ddlmZ ddlZddlZddlmZ ddlmZ ddlm Z ddlm Z dd lm Z dd lm Z dd lm Z dd lmZ dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddl m Z ddl m Z ddlm Z ddl m!Z! dd l"m#Z# ej�r�dd lm$Z$ dd lm%Z% dd lm&Z& dd l'm(Z( dd!l)m*Z* dd"l+m,Z, dd#l-m.Z. dd$l/m0Z0 dd%l1m2Z2 dd&lm3Z3 dd'l4m5Z5 dd(l6m7Z7 dd)l6m8Z8 dd*l m9Z9 dd+l:m;Z; ed,ed-�Z<ed.ed/d0�Z=ed1e>d-�Z?G d2d3� d3e�Z@eAe@�\ZBZCZDZEZFeFZGG d4d5� d5e �ZHeHjI�J� \ZKZLZMZNZOZPZQZRZSZTZUZVZWZXZYZZZ[Z\d6Z]d7Z^G d8d9� d9e�Z_eAe_�\Z`ZaZbZcG d:d;� d;e�ZdeAed�\ZeZfZgG d<d=� d=e�ZhG d>d?� d?eh�ZiejeGg�ZkejdeGeBg�Zlejdg�Zme�nd@�Zoe�ndA�Zpe�ndB�ZqedCedDef d-�ZredE�ZsdFdGdH�dIdJ�Zte�r�dKdLdM�dNdO�Zue dPdQdM�dRdS��Zve dTdUdM�dVdS��ZvdTdUdM�dWdS�Zvd1dXdY�dZd[�Zwd\d]dY�d^d_�Zxn$d`dO� ZudadS� Zve�ye^�Zwe�ydb�Zxd\dcdY�ddde�Zzdfdcdg�dhdi�Z{dfdcdg�djdk�Z|d\dcdcdl�dmdn�Z}dfdcdcdo�dpdq�Z~d,drdY�dsdt�Zd,dudY�dvdw�Z�e��e>�d,dxdY�dydz��Z�d{drd|�d}d~�Z�dd�d��d�d��Z�dFd�d��d�d��Z�dFd�d��d�d��Z�e d�dcdFd��d�d���Z�e�r�dXd�dg�d�d��Z�n e��d��Z�d�dKd�d�d��d�d��Z�d�d�d��d�d��Z�d�dKd�d�d��d�d��Z�G d�d�� d��Z�G d�d�� d�e��Z�G d�d�� d�e e= e!�Z�G d�d�� d�e e= e!�Z�G d�d�� d�e e= e!�Z�G d�d�� d�e�e= e e= e!�Z�G d�d�� d�e�e= e�e= e�e= ej��Z�G d�d�� d�e e= e!�Z�G d�d�� d�e�e= e�e= �Z�G d�d�� d�e�e= �Z�G d�d�� d�e�e= �Z�dS )�z=Constants and rudimental functions used throughout the ORM. � )� annotations)�EnumN)�Any)�Callable)�Dict)�Generic)� no_type_check)�Optional)�overload)�Tuple)�Type)� TYPE_CHECKING)�TypeVar)�Union� )�exc)�insp_is_mapper� )� inspection)�util)�roles)�SQLColumnExpression)�SQLCoreOperations)� FastIntFlag)� TypingOnly)�Literal)� _EntityType)�_ExternalEntityType)�_InternalEntityType)�InstrumentedAttribute)� AppenderQuery)� ClassManager)�PropComparator)�Mapper)� InstanceState)� AliasedClass)�WriteOnlyCollection)�_ColumnExpressionArgument)� _InfoType)� ColumnElement)� OperatorType�_T)�bound�_T_coT)r, � covariant�_Oc @ s$ e Zd ZdZdZdZdZdZeZdS )�LoaderCallableStatusr r r � � N) �__name__� __module__� __qualname__�PASSIVE_NO_RESULT�PASSIVE_CLASS_MISMATCH� ATTR_WAS_SET� ATTR_EMPTY�NO_VALUE� NEVER_SET� r< r< �H/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/base.pyr0 A s r0 c @ s� e Zd ZdZdZdZdZdZdZdZ dZ d Z d Z d Z d Zee B eB eB eB ZeeA ZeeA ZeeA ZeeA Zee A Zee B Zd S )� PassiveFlagz;Bitflag interface that passes options onto loader callablesr r r r2 � � � �@ � � i N)r3 r4 r5 �__doc__� NO_CHANGE� CALLABLES_OK�SQL_OK�RELATED_OBJECT_OK�INIT_OK�NON_PERSISTENT_OK�LOAD_AGAINST_COMMITTED� NO_AUTOFLUSH�NO_RAISE�DEFERRED_HISTORY_LOAD�INCLUDE_PENDING_MUTATIONS� PASSIVE_OFF�PASSIVE_RETURN_NO_VALUE�PASSIVE_NO_INITIALIZE�PASSIVE_NO_FETCH�PASSIVE_NO_FETCH_RELATED�PASSIVE_ONLY_PERSISTENT� PASSIVE_MERGEr< r< r< r= r> p s* �r> Z_sa_class_managerZ_sa_instance_statec @ s e Zd ZdZdZdZdZdS )�EventConstantsr r r1 r2 N)r3 r4 r5 � EXT_CONTINUE�EXT_STOP�EXT_SKIP�NO_KEYr< r< r< r= rX � s rX c @ s e Zd ZdZdZdZdZdS )�RelationshipDirectionz�enumeration which indicates the 'direction' of a :class:`_orm.RelationshipProperty`. :class:`.RelationshipDirection` is accessible from the :attr:`_orm.Relationship.direction` attribute of :class:`_orm.RelationshipProperty`. r r r1 N)r3 r4 r5 rE � ONETOMANY� MANYTOONE� MANYTOMANYr< r< r< r= r] � s r] c @ s e Zd ZdZdS )�InspectionAttrExtensionTypezXSymbols indicating the type of extension that a :class:`.InspectionAttr` is part of.N)r3 r4 r5 rE r< r< r< r= ra s ra c @ s e Zd ZdZdS )� NotExtensionZ not_extensionN)r3 r4 r5 � NOT_EXTENSIONr< r< r< r= rb s rb ZSET_DEFERRED_EXPIREDZDEFER_FOR_STATEZRAISE_FOR_STATE�_F.�_Selfr zCallable[[_F], _F])� assertions�returnc s$ t jdddddd�� fdd� �}|S )Nrd re r )�fn�self�args�kwrg c s0 � D ]}||| j � q| |g|�R i |�� |S �N)r3 )rh ri rj rk Z assertion�rf r< r= �generate. s z _assertions.<locals>.generate)r � decorator)rf rn r< rm r= � _assertions+ s rp zType[_O]zClassManager[_O])�clsrg c C s d S rl r< �rq r< r< r= �manager_of_class: � rs zAliasedClass[Any]�Nonec C s d S rl r< rr r< r< r= �opt_manager_of_class< s rv z_ExternalEntityType[_O]zOptional[ClassManager[_O]]c C s d S rl r< rr r< r< r= rv ? s c C s d S rl r< rr r< r< r= rv D s zInstanceState[_O]��instancerg c C s d S rl r< �rx r< r< r= �instance_stateH rt rz �objectzDict[str, Any]c C s d S rl r< ry r< r< r= � instance_dictJ rt r| c C sJ z | j t W S tyD } z t�| d| � ��|�W Y d }~n d }~0 0 d S )Nz2Can't locate an instrumentation manager for class )�__dict__�DEFAULT_MANAGER_ATTR�KeyErrorr �UnmappedClassError)rq Zker< r< r= rs P s ��c C s | j �t�S rl )r} �getr~ rr r< r< r= rv X s r} �strc C s t t| ��S )z'Return a string describing an instance.)� state_strrz ry r< r< r= � instance_str` s r� zInstanceState[Any])�staterg c C s( | du r dS d| j jt| �� �f S dS )z=Return a string describing an instance via its InstanceState.Nru z <%s at 0x%x>)�class_r3 �id�obj�r� r< r< r= r� f s r� c C s | du r dS d| j jf S dS )zNReturn a string describing an instance's class via its InstanceState. Nru z<%s>)r� r3 r� r< r< r= �state_class_stro s r� )rx � attributerg c C s t | �d | S �N�.)r� )rx r� r< r< r= � attribute_strz s r� )r� r� rg c C s t | �d | S r� )r� )r� r� r< r< r= �state_attribute_str~ s r� z Mapper[_T]c C s t | �jS )a� Given an object, return the primary Mapper associated with the object instance. Raises :class:`sqlalchemy.orm.exc.UnmappedInstanceError` if no mapping is configured. This function is available via the inspection system as:: inspect(instance).mapper Using the inspection system will raise :class:`sqlalchemy.exc.NoInspectionAvailable` if the instance is not part of a mapping. )� object_state�mapperry r< r< r= � object_mapper� s r� zInstanceState[_T]c C s$ t | �}|du r t�| ��n|S dS )a� Given an object, return the :class:`.InstanceState` associated with the object. Raises :class:`sqlalchemy.orm.exc.UnmappedInstanceError` if no mapping is configured. Equivalent functionality is available via the :func:`_sa.inspect` function as:: inspect(instance) Using the inspection system will raise :class:`sqlalchemy.exc.NoInspectionAvailable` if the instance is not part of a mapping. N)�_inspect_mapped_objectr ZUnmappedInstanceError)rx r� r< r< r= r� � s r� zOptional[InstanceState[_T]]c C s. z t | �W S tjftj y( Y d S 0 d S rl )rz r r� �NO_STATEry r< r< r= r� � s r� zUnion[Mapper[_T], Type[_T]])�class_or_mapperrg c C s6 t �| d�}|d ur|jS t| t�s(J �t�| ��d S )NF)r �inspectr� � isinstance�typer r� )r� �inspr< r< r= �_class_to_mapper� s r� z(Union[Type[_T], _InternalEntityType[_T]]zOptional[Mapper[_T]])�entityrg c C s" t �| d�}|dur|jS dS dS )z`Return the :class:`_orm.Mapper` for the given class or None if the class is not mapped. FN)r r� r� �r� r� r< r< r= �_mapper_or_none� s r� �boolc C s( t �| d�}|duo&|j o&|jp&|jS )zlReturn True if the given object is a mapped class, :class:`_orm.Mapper`, or :class:`.AliasedClass`. FN)r r� �is_clause_element� is_mapper�is_aliased_classr� r< r< r= �_is_mapped_class� s � �r� c C s t �| d�}|d uo t|dd�S )NFr� )r r� �getattrr� r< r< r= �_is_aliased_class� s r� �_EntityType[Any])r� �keyrg c C s� t �| �}|jr | }|j} n.|jr.|j} | }n t|d�rF|jj }} n| }z t | |�W S t y� } z t � d||f �|�W Y d}~n d}~0 0 dS )z�Return a class attribute given an entity and string name. May return :class:`.InstrumentedAttribute` or user-defined attribute. r� z Entity '%s' has no property '%s'N) r r� � is_selectable�cr� r� �hasattrr� r� r� �AttributeError�sa_excZInvalidRequestError)r� r� r� � description�errr< r< r= �_entity_descriptor� s$ ��r� z Mapper[_O]c C s d S rl r< r� r< r< r= � _state_mapper rt r� zmanager.mapperFzOptional[Mapper[_O]])r� � configurerg c C sR z&t | �}|d u s|js W d S |j}W n tjy< Y d S 0 |rJ|�� |S d S rl )rv Z is_mappedr� r r� Z_check_configure)r� r� Z class_managerr� r< r< r= �_inspect_mapped_class s r� zUnion[Mapper[_O], Type[_O]])�argrg c C s. t j| dd�}t|�r|S t�d| ����d S )NF)Zraiseerrz%Mapper or mapped class expected, got )r r� r r� � ArgumentError)r� r� r< r< r= �_parse_mapper_argument s r� c C sB t | |d�}|du r:t| t�s.t�d| f ��t�| ��n|S dS )a� Given a class, return the primary :class:`_orm.Mapper` associated with the key. Raises :exc:`.UnmappedClassError` if no mapping is configured on the given class, or :exc:`.ArgumentError` if a non-class object is passed. Equivalent functionality is available via the :func:`_sa.inspect` function as:: inspect(some_mapped_class) Using the inspection system will raise :class:`sqlalchemy.exc.NoInspectionAvailable` if the class is not mapped. )r� Nz Class object expected, got '%r'.)r� r� r� r� r� r r� )r� r� r� r< r< r= � class_mapper s � r� c @ sP e Zd ZU dZdZded< dZdZdZdZ dZ dZ dZ dZ dZejZded< dS ) �InspectionAttraM A base class applied to all ORM objects and attributes that are related to things that can be returned by the :func:`_sa.inspect` function. The attributes defined here allow the usage of simple boolean checks to test basic facts about the object returned. While the boolean checks here are basically the same as using the Python isinstance() function, the flags here can be used without the need to import all of these classes, and also such that the SQLAlchemy class system can change while leaving the flags here intact for forwards-compatibility. r< zTuple[str, ...]� __slots__Fra �extension_typeN)r3 r4 r5 rE r� �__annotations__r� r� Z is_instancer� Z is_bundleZ is_propertyZ is_attributeZ_is_internal_proxyr� rb rc r� r< r< r< r= r� : s r� c @ s( e Zd ZdZdZejdd�dd��ZdS )�InspectionAttrInfoa Adds the ``.info`` attribute to :class:`.InspectionAttr`. The rationale for :class:`.InspectionAttr` vs. :class:`.InspectionAttrInfo` is that the former is compatible as a mixin for classes that specify ``__slots__``; this is essentially an implementation artifact. r< r( )rg c C s i S )a� Info dictionary associated with the object, allowing user-defined data to be associated with this :class:`.InspectionAttr`. The dictionary is generated when first accessed. Alternatively, it can be specified as a constructor argument to the :func:`.column_property`, :func:`_orm.relationship`, or :func:`.composite` functions. .. seealso:: :attr:`.QueryableAttribute.info` :attr:`.SchemaItem.info` r< )ri r< r< r= �info� s zInspectionAttrInfo.infoN)r3 r4 r5 rE r� r Zro_memoized_propertyr� r< r< r< r= r� � s r� c @ s^ e Zd ZdZejrZddd�dd�Zddd �d d �Zdd ddd�dd�Zdd ddd�dd�Z d S )�SQLORMOperationsr< r� zPropComparator[_T_co])r� rg c C s d S rl r< )ri r� r< r< r= �of_type� s zSQLORMOperations.of_typez _ColumnExpressionArgument[bool]zPropComparator[bool])�criteriarg c G s d S rl r< )ri r� r< r< r= �and_� s zSQLORMOperations.and_Nz)Optional[_ColumnExpressionArgument[bool]]r zColumnElement[bool])� criterion�kwargsrg c K s d S rl r< �ri r� r� r< r< r= �any� s zSQLORMOperations.anyc K s d S rl r< r� r< r< r= �has� s zSQLORMOperations.has)N)N) r3 r4 r5 r� �typingr r� r� r� r� r< r< r< r= r� � s � �r� c @ sn e Zd ZdZdZejrjedddd�dd��Zeddd d�d d��Zed dd d�d d��Zd ddd�dd�ZdS )� ORMDescriptorz`Represent any Python descriptor that provides a SQL expression construct at the class level.r< r z Literal[None]zORMDescriptor[_T_co]�rx �ownerrg c C s d S rl r< �ri rx r� r< r< r= �__get__� s zORMDescriptor.__get__zSQLCoreOperations[_T_co]c C s d S rl r< r� r< r< r= r� � s r{ r- c C s d S rl r< r� r< r< r= r� � s z<Union[ORMDescriptor[_T_co], SQLCoreOperations[_T_co], _T_co]c C s d S rl r< r� r< r< r= r� � s N) r3 r4 r5 rE r� r� r r r� r< r< r< r= r� � s r� c @ s e Zd ZdZdZdS )�_MappedAnnotationBasez�common class for Mapped and similar ORM container classes. these are classes that can appear on the left side of an ORM declarative mapping, containing a mapped class or in some cases a collection surrounding a mapped class. r< N�r3 r4 r5 rE r� r< r< r< r= r� � s r� c @ s e Zd ZdZdZdS )�SQLORMExpressionaC A type that may be used to indicate any ORM-level attribute or object that acts in place of one, in the context of SQL expression construction. :class:`.SQLORMExpression` extends from the Core :class:`.SQLColumnExpression` to add additional SQL methods that are ORM specific, such as :meth:`.PropComparator.of_type`, and is part of the bases for :class:`.InstrumentedAttribute`. It may be used in :pep:`484` typing to indicate arguments or return values that should behave as ORM-level attribute expressions. .. versionadded:: 2.0.0b4 r< Nr� r< r< r< r= r� � s r� c @ s� e Zd ZdZdZejr�edddd�dd��Zed dd d�d d��Zd dd d�dd�Ze ddd�dd��Z dddd�dd�Z ddd�dd�Z dS )�Mappedaj Represent an ORM mapped attribute on a mapped class. This class represents the complete descriptor interface for any class attribute that will have been :term:`instrumented` by the ORM :class:`_orm.Mapper` class. Provides appropriate information to type checkers such as pylance and mypy so that ORM-mapped attributes are correctly typed. The most prominent use of :class:`_orm.Mapped` is in the :ref:`Declarative Mapping <orm_explicit_declarative_base>` form of :class:`_orm.Mapper` configuration, where used explicitly it drives the configuration of ORM attributes such as :func:`_orm.mapped_class` and :func:`_orm.relationship`. .. seealso:: :ref:`orm_explicit_declarative_base` :ref:`orm_declarative_table` .. tip:: The :class:`_orm.Mapped` class represents attributes that are handled directly by the :class:`_orm.Mapper` class. It does not include other Python descriptor classes that are provided as extensions, including :ref:`hybrids_toplevel` and the :ref:`associationproxy_toplevel`. While these systems still make use of ORM-specific superclasses and structures, they are not :term:`instrumented` by the :class:`_orm.Mapper` and instead provide their own functionality when they are accessed on a class. .. versionadded:: 1.4 r< ru r � InstrumentedAttribute[_T_co]r� c C s d S rl r< r� r< r< r= r� * s zMapped.__get__r{ r- c C s d S rl r< r� r< r< r= r� / s �Optional[object]z*Union[InstrumentedAttribute[_T_co], _T_co]c C s d S rl r< r� r< r< r= r� 2 s z Mapped[_T_co])�arg1rg c C s d S rl r< )rq r� r< r< r= �_empty_constructor6 s zMapped._empty_constructorz&Union[SQLCoreOperations[_T_co], _T_co]�rx �valuerg c C s d S rl r< �ri rx r� r< r< r= �__set__9 s zMapped.__set__rw c C s d S rl r< )ri rx r< r< r= � __delete__= rt zMapped.__delete__N) r3 r4 r5 rE r� r� r r r� � classmethodr� r� r� r< r< r< r= r� � s $r� c @ s e Zd ZdZdZdS )�_MappedAttributezVMixin for attributes which should be replaced by mapper-assigned attributes. r< Nr� r< r< r< r= r� @ s r� c @ s@ e Zd ZdZdZddddd�dd�ZeZddddd�dd �Zd S ) �_DeclarativeMappedz�Mixin for :class:`.MapperProperty` subclasses that allows them to be compatible with ORM-annotated declarative mappings. r< r* r )�op�otherr� rg c O s t S rl ��NotImplemented�ri r� r� r� r< r< r= �operateW s z_DeclarativeMapped.operatec K s t S rl r� r� r< r< r= �reverse_operate\ s z"_DeclarativeMapped.reverse_operateN)r3 r4 r5 rE r� r� Z__sa_operate__r� r< r< r< r= r� I s r� c @ sh e Zd ZdZdZerdedddd�dd��Zed dd d�d d��Zd dd d�dd�Zdddd�dd�ZdS )� DynamicMappeda� Represent the ORM mapped attribute type for a "dynamic" relationship. The :class:`_orm.DynamicMapped` type annotation may be used in an :ref:`Annotated Declarative Table <orm_declarative_mapped_column>` mapping to indicate that the ``lazy="dynamic"`` loader strategy should be used for a particular :func:`_orm.relationship`. .. legacy:: The "dynamic" lazy loader strategy is the legacy form of what is now the "write_only" strategy described in the section :ref:`write_only_relationship`. E.g.:: class User(Base): __tablename__ = "user" id: Mapped[int] = mapped_column(primary_key=True) addresses: DynamicMapped[Address] = relationship( cascade="all,delete-orphan" ) See the section :ref:`dynamic_relationship` for background. .. versionadded:: 2.0 .. seealso:: :ref:`dynamic_relationship` - complete background :class:`.WriteOnlyMapped` - fully 2.0 style version r< ru r r� r� c C s d S rl r< r� r< r< r= r� � s zDynamicMapped.__get__r{ zAppenderQuery[_T_co]c C s d S rl r< r� r< r< r= r� � s r� z9Union[InstrumentedAttribute[_T_co], AppenderQuery[_T_co]]c C s d S rl r< r� r< r< r= r� � s �typing.Collection[_T_co]r� c C s d S rl r< r� r< r< r= r� � s zDynamicMapped.__set__N� r3 r4 r5 rE r� r r r� r� r< r< r< r= r� b s r� c @ sh e Zd ZdZdZerdedddd�dd��Zed dd d�d d��Zd dd d�dd�Zdddd�dd�ZdS )�WriteOnlyMappedad Represent the ORM mapped attribute type for a "write only" relationship. The :class:`_orm.WriteOnlyMapped` type annotation may be used in an :ref:`Annotated Declarative Table <orm_declarative_mapped_column>` mapping to indicate that the ``lazy="write_only"`` loader strategy should be used for a particular :func:`_orm.relationship`. E.g.:: class User(Base): __tablename__ = "user" id: Mapped[int] = mapped_column(primary_key=True) addresses: WriteOnlyMapped[Address] = relationship( cascade="all,delete-orphan" ) See the section :ref:`write_only_relationship` for background. .. versionadded:: 2.0 .. seealso:: :ref:`write_only_relationship` - complete background :class:`.DynamicMapped` - includes legacy :class:`_orm.Query` support r< ru r r� r� c C s d S rl r< r� r< r< r= r� � s zWriteOnlyMapped.__get__r{ zWriteOnlyCollection[_T_co]c C s d S rl r< r� r< r< r= r� � s r� z?Union[InstrumentedAttribute[_T_co], WriteOnlyCollection[_T_co]]c C s d S rl r< r� r< r< r= r� � s r� r� c C s d S rl r< r� r< r< r= r� � s zWriteOnlyMapped.__set__Nr� r< r< r< r= r� � s r� )F)T)�rE � __future__r �enumr �operatorr� r r r r r r r r r r r r � r Z_typingr r� r r Zsqlr Z sql.elementsr r r Zutil.langhelpersr Z util.typingr r r r � attributesr Zdynamicr Zinstrumentationr! Z interfacesr" r� r# r� r$ r% Z writeonlyr& Z sql._typingr' r( r) Z sql.operatorsr* r+ r- r{ r/ r0 �tupler6 r7 r8 r9 r: r; r> � __members__�valuesrF rG rH rI rJ rK rL rM rN rO rP rQ rR rS rT rU rV rW r~ ZDEFAULT_STATE_ATTRrX rY rZ r[ r\ r] r^ r_ r` ra rb � frozensetZ _never_setZ _none_setZ_none_only_set�symbolZ_SET_DEFERRED_EXPIREDZ_DEFER_FOR_STATEZ_RAISE_FOR_STATErd re rp rs rv rz r| � attrgetterr� r� r� r� r� r� r� Z _inspectsr� r� r� r� r� r� r� Z dottedgetterr� r� r� r� r� r� r� r� r� ZDDLConstraintColumnRoler� r� r� r� r� r< r< r< r= �<module> s$ *�^� # � L � �D 8 sqlalchemy/orm/__pycache__/clsregistry.cpython-39.pyc 0000644 00000037231 15125143220 0016717 0 ustar 00 a ��Jh F � @ s� U d Z ddlmZ ddlZddlmZ ddlmZ ddlmZ ddlmZ ddlm Z dd lm Z dd lm Z dd lm Z dd lm Z dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlZddlmZ ddlmZ ddlmZ ddl m Z ddl m Z dd lm Z dd lm!Z! dd lm Z dd l"m#Z# dd l$m%Z% e�r�dd!l&m'Z' dd"l"m(Z( dd#l"m)Z) ed$ed%�Z*e e+ee,d&f f Z-e.� Z/d'e0d(< d)d*d+d,d-�d.d/�Z1d)d0d+d,d-�d1d2�Z2d)d+d3d4d5�d6d7�Z3G d8d&� d&�Z4G d9d:� d:e4�Z5G d;d<� d<e4�Z6G d=d>� d>�Z7G d?d@� d@�Z8e!�9e8�dAdB� � G dCdD� dD�Z:d)dEd@dF�dGdH�Z;G dIdJ� dJ�Z<da=dKe0dL< d0dMdNdO�dPdQ�Z>dS )Rz�Routines to handle the string class registry used by declarative. This system allows specification of classes and expressions used in :func:`_orm.relationship` using strings. � )� annotationsN)�Any)�Callable)�cast)�Dict)� Generator)�Iterable)�List)�Mapping)�MutableMapping)�NoReturn)�Optional)�Set)�Tuple)�Type)� TYPE_CHECKING)�TypeVar)�Union� )� attributes)� interfaces)�SynonymProperty)�ColumnProperty)� class_mapper� )�exc)� inspection)�util)�_get_table_key)�CallableReference)�RelationshipProperty)�MetaData)�Table�_T)�bound�ClsRegistryTokenzSet[ClsRegistryToken]� _registries�strzType[_T]�_ClsRegistryType�None)� classname�cls�decl_class_registry�returnc C s | |v r2|| }t |t�s:t|td|�g�|| < n||| < ztt|d �}W n$ typ tdd� |d< }Y n0 |j�d�}|�r|�d�}|�|�}|D ]}|�|�}q�z|� | |� W q~ t �y } z.t |t�s�t � d| � d��|�n� W Y d}~q~d}~0 0 q~dS )z^Add a class to the _decl_class_registry associated with the given declarative class. � Type[Any]�_sa_module_registryN�.r �name "�-" matches both a class name and a module name) � isinstance�_MultipleClassMarkerr � _ModuleMarker�KeyError� __module__�split�pop� get_module� add_class�AttributeErrorr �InvalidRequestError) r* r+ r, �existing� root_module�tokens�token�module�ae� rD �O/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/clsregistry.pyr; @ s< � � � ��r; r. c C s� | |v r,|| }t |t�r&|�|� n|| = ztt|d �}W n tyR Y d S 0 |j�d�}|r�|�d�}|� |�}|D ]}|� |�}q|z|� | |� W q` t y� t |t�s�n� Y q`0 q`d S )Nr/ r0 r ) r3 r4 � remove_itemr r5 r6 r7 r8 r9 r: � remove_classr< )r* r+ r, r> r? r@ rA rB rD rD rE rG v s. � rG zCallable[[Any], bool]�bool)�keyr, �testr- c C sP | |vr dS || }t |t�rB|jD ]}||�r$ dS q$td��n ||� S dS )a� test if a key is empty of a certain object. used for unit tests against the registry to see if garbage collection is working. "test" is a callable that will be passed an object should return True if the given object is the one we were looking for. We can't pass the actual object itself b.c. this is for testing garbage collection; the caller will have to have removed references to the object itself. TFzunknown codepathN)r3 r4 �contents�NotImplementedError)rI r, rJ �thingZ sub_thingrD rD rE � _key_is_empty� s rN c @ s e Zd ZdZdZdS )r% zAan object that can be in the registry._class_registry as a value.rD N)�__name__r7 � __qualname__�__doc__� __slots__rD rD rD rE r% � s c @ s� e Zd ZU dZdZded< ded< d"dd d �d d �Zd dd�dd�Zdd�dd�Zddd d�dd�Z ddd �d d �Z d dd �d d!�Z dS )#r4 zRrefers to multiple classes of the same name within _decl_class_registry. )� on_removerK � __weakref__zSet[weakref.ref[Type[Any]]]rK z/CallableReference[Optional[Callable[[], None]]]rS NzIterable[Type[Any]]z Optional[Callable[[], None]])�classesrS c s( |� _ � fdd�|D �� _t�� � d S )Nc s h | ]}t �|� j��qS rD )�weakref�ref� _remove_item)�.0�item��selfrD rE � <setcomp>� s z0_MultipleClassMarker.__init__.<locals>.<setcomp>)rS rK r& �add)r\ rU rS rD r[ rE �__init__� s �z _MultipleClassMarker.__init__r. r) )r+ r- c C s | � t�|�� d S �N)rX rV rW �r\ r+ rD rD rE rF � s z _MultipleClassMarker.remove_itemz*Generator[Optional[Type[Any]], None, None]�r- c C s dd� | j D �S )Nc s s | ] }|� V qd S r` rD �rY rW rD rD rE � <genexpr>� � z0_MultipleClassMarker.__iter__.<locals>.<genexpr>�rK r[ rD rD rE �__iter__� s z _MultipleClassMarker.__iter__� List[str]r' )�pathrI r- c C sV t | j�dkr*t�dd�||g � ��n(t| j�d }|� }|d u rNt|��|S d S )Nr zxMultiple classes found for path "%s" in the registry of this declarative base. Please use a fully module-qualified path.r0 r )�lenrK r r= �join�list� NameError)r\ ri rI rW r+ rD rD rE � attempt_get� s ��z _MultipleClassMarker.attempt_getzweakref.ref[Type[Any]])rW r- c C s. | j �|� | j s*t�| � | jr*| �� d S r` )rK �discardr& rS )r\ rW rD rD rE rX � s z!_MultipleClassMarker._remove_item)rZ r- c C sX dd� dd� t | j�D �D �}|j|v r>t�d|j|jf � | j�t�|| j �� d S )Nc S s h | ]}|d ur|j �qS r` )r7 )rY r+ rD rD rE r] � s �z0_MultipleClassMarker.add_item.<locals>.<setcomp>c S s g | ] }|� �qS rD rD rc rD rD rE � <listcomp>� re z1_MultipleClassMarker.add_item.<locals>.<listcomp>z�This declarative base already contains a class with the same class name and module name as %s.%s, and will be replaced in the string-lookup table.) rl rK r7 r �warnrO r^ rV rW rX )r\ rZ �modulesrD rD rE �add_item� s � ��z _MultipleClassMarker.add_item)N) rO r7 rP rQ rR �__annotations__r_ rF rg rn rX rs rD rD rD rE r4 � s � r4 c @ s� e Zd ZU dZdZded< ded< ded< d ed < d dd �d d�Zd dd�dd�Zd dd�dd�Zd dd�dd�Z d dd�dd �Z d d d�d d �Z d d dd �d!d"�Z d d dd �d#d$�Z d%S )&r5 z>Refers to a module name within _decl_class_registry. )�parent�namerK �mod_nsri rT zOptional[_ModuleMarker]ru z5Dict[str, Union[_ModuleMarker, _MultipleClassMarker]]rK �_ModNSrw rh ri r' )rv ru c C sJ || _ || _i | _t| �| _| j r6| j j| jg | _ng | _t�| � d S r` )ru rv rK rx rw ri r& r^ )r\ rv ru rD rD rE r_ s z_ModuleMarker.__init__rH )rv r- c C s || j v S r` rf �r\ rv rD rD rE � __contains__ s z_ModuleMarker.__contains__r% c C s | j | S r` rf ry rD rD rE � __getitem__ s z_ModuleMarker.__getitem__r) c C s: | j �|d � | j s6| jd ur,| j�| j� t�| � d S r` )rK r9 ru rX rv r& ro ry rD rD rE rX s z_ModuleMarker._remove_item�Union[_ModNS, Type[Any]]�rI r- c C s | j �|�S r` )rw � __getattr__�r\ rI rD rD rE � resolve_attr' s z_ModuleMarker.resolve_attrc C s4 || j vr t|| �}|| j |< ntt| j | �}|S r` )rK r5 r )r\ rv �markerrD rD rE r: * s z_ModuleMarker.get_moduler. )rv r+ r- c s� � �j v rrtt�j � �}z|�|� W q� tyn } z.t|t�sXt�d� � d��|�n� W Y d }~q�d }~0 0 n t|g� �fdd�d��j � < d S )Nr1 r2 c s �� � �S r` )rX rD �rv r\ rD rE �<lambda>A re z)_ModuleMarker.add_class.<locals>.<lambda>)rS )rK r r4 rs r< r3 r r= )r\ rv r+ r> rC rD r� rE r; 2 s ���z_ModuleMarker.add_classc C s( || j v r$tt| j | �}|�|� d S r` )rK r r4 rF )r\ rv r+ r> rD rD rE rG D s z_ModuleMarker.remove_classN)rO r7 rP rQ rR rt r_ rz r{ rX r� r: r; rG rD rD rD rE r5 s r5 c @ s8 e Zd ZU dZded< dd�dd�Zddd �d d �Zd S ) rx )Z__parentr5 �_ModNS__parent)ru c C s || _ d S r` )r� )r\ ru rD rD rE r_ O s z_ModNS.__init__r' r| r} c C sr z| j j| }W n ty" Y n80 |d urZt|t�r<|jS t|t�sJJ �|�| j j|�S t d| j j |f ��d S )Nz<Module %r has no mapped classes registered under the name %r) r� rK r6 r3 r5 rw r4 rn ri rm rv )r\ rI �valuerD rD rE r~ R s ��z_ModNS.__getattr__N�rO r7 rP rR rt r_ r~ rD rD rD rE rx J s rx c @ s8 e Zd ZU dZded< dd�dd�Zddd�d d �Zd S ) � _GetColumns�r+ r. r+ c C s || _ d S r` r� ra rD rD rE r_ i s z_GetColumns.__init__r' r r} c C s� t | jdd�}|r�||jvr.td| j|f ��|j| }|jtjju r�t|t j �sVJ �|j }t|t �rn|j }nt|t�s�t�d| ��t| j|�S )NF)� configurez/Class %r does not have a mapped column named %rzaProperty %r is not an instance of ColumnProperty (i.e. does not correspond directly to a Column).)r r+ Zall_orm_descriptorsr< Zextension_typer Z NotExtensionZ NOT_EXTENSIONr3 r ZQueryableAttribute�propertyr rv r r r= �getattr)r\ rI �mp�desc�proprD rD rE r~ l s* �� ��z_GetColumns.__getattr__Nr� rD rD rD rE r� d s r� c C s t �| j�S r` )r �inspectr+ )�targetrD rD rE r� � re r� c @ sB e Zd ZU dZded< ded< ddd�dd�Zddd �d d �Zd S ) � _GetTable�rI �metadatar' rI r! r� c C s || _ || _d S r` r� )r\ rI r� rD rD rE r_ � s z_GetTable.__init__r" r} c C s | j jt|| j� S r` )r� �tablesr rI r rD rD rE r~ � s z_GetTable.__getattr__Nr� rD rD rD rE r� � s r� r )rI r� r- c C s t |t�r|�g | �}t|�S r` )r3 r4 rn r� )rI r� rD rD rE �_determine_container� s r� c @ s� e Zd ZU dZded< ded< ded< ded < d ed < d ed < d"ddddd d�dd�Zddd�dd�Zdddd�dd�Zdd �d d �Zdd �d d �Z d!S )#�_class_resolver)r+ r� �arg�fallback�_dict� _resolvers� favor_tablesr. r+ �RelationshipProperty[Any]r� �Mapping[str, Any]r� r' r� rH r� z Tuple[Callable[[str], Any], ...]r� F)r+ r� r� r� r� c C s6 || _ || _|| _|| _t�| j�| _d| _|| _ d S )NrD ) r+ r� r� r� r Z PopulateDict� _access_clsr� r� r� )r\ r+ r� r� r� r� rD rD rE r_ � s z_class_resolver.__init__r r} c C s | j }t�|�}|j}|d us"J �|j}|j}| jrd||jv rH|j| S ||jv rdt |t |d|��S ||v rzt ||| �S | js�||jv r�|j| S ||jv r�t |t |d|��S d|v r�|t t |d �v r�t t |d �}|�|�S | j�r| jD ] }||�} | d ur�| S q�| j| S )Nr� r/ )r+ r Zmanager_of_class�registryZ_class_registryr� r� r� Z_schemasr� r� r� r r5 r� r� r� ) r\ rI r+ �managerZ decl_baser, r� r� Zresolvr� rD rD rE r� � s> �� z_class_resolver._access_cls� Exceptionr )rv �errr- c C s� t �d|�}|r^|�d��d�}t�d| jj� d| j�d| jj � d|�d�� d |� d � �|�n t�d | jj| j|| j f �|�d S ) Nz (.+)\[(.+)\]r �'zWhen initializing mapper z, expression "relationship(z�)" seems to be using a generic class as the argument to relationship(); please state the generic argument using an annotation, e.g. "z : Mapped[r z['z']] = relationship()"z�When initializing mapper %s, expression %r failed to locate a name (%r). If this is a class name, consider adding this relationship() to the %r class after both dependent classes have been defined.) �re�match�group�stripr r= r� ru r� rI r+ )r\ rv r� Z generic_matchZclsargrD rD rE �_raise_for_name� s. ������ ���z _class_resolver._raise_for_namez Union[Table, Type[Any], _ModNS]rb c C s� | j }| j}d }z0|�d�D ] }|d u r2|| }q t||�}q W nd typ } z| �||� W Y d }~njd }~0 ty� } z | �|jd |� W Y d }~n6d }~0 0 t|t �r�|j S t r�t|t t tf�s�J �|S d S )Nr0 r )r� r� r8 r� r6 r� rm �argsr3 r� r+ r �typer" rx )r\ rv �d�rvalrA r� �nrD rD rE � _resolve_name� s" ( z _class_resolver._resolve_namec C sj z.t | jt� | j�}t|t�r&|jW S |W S W n6 tyd } z | �|j d |� W Y d }~n d }~0 0 d S )Nr ) �evalr� �globalsr� r3 r� r+ rm r� r� )r\ �xr� rD rD rE �__call__ s z_class_resolver.__call__N)F) rO r7 rP rR rt r_ r� r� r� r� rD rD rD rE r� � s �'r� r� �_fallback_dictr� zmTuple[Callable[[str], Callable[[], Union[Type[Any], Table, _ModNS]]], Callable[[str, bool], _class_resolver]])r+ r� r- c sx t d u r@dd l}ddlm} ddlm} t�|j��||d��a dddd d �� �fd d � }dd d�� �fdd� }||fS )Nr r )�foreign)�remote)r� r� Fr' rH r� )r� r� r- c s t � �t| |d�S )N)r� )r� r� )r� r� �r+ r� rD rE � resolve_arg1 s �z _resolver.<locals>.resolve_argz-Callable[[], Union[Type[Any], Table, _ModNS]])r� r- c s t � �t| �jS r` )r� r� r� )r� r� rD rE � resolve_name6 s z _resolver.<locals>.resolve_name)F) r� � sqlalchemy� r� r� r Z immutabledict�__dict__�union)r+ r� r� r� r� r� r� rD r� rE � _resolver" s �r� )?rQ � __future__r r� �typingr r r r r r r r r r r r r r r r r rV r� r r Zdescriptor_propsr Z propertiesr r r r r Z sql.schemar Z util.typingr Z relationshipsr r! r" r# r' r� r( �setr& rt r; rG rN r% r4 r5 rx r� Z _inspectsr� r� r� r� r� rD rD rD rE �<module> sl 6! EH � sqlalchemy/orm/__pycache__/dependency.cpython-39.pyc 0000644 00000056123 15125143220 0016464 0 ustar 00 a ��Jh� � @ s� d Z ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ dd l m Z dd l m Z dd l m Z d dlmZ d d lmZ d dlmZ G dd� d�ZG dd� de�ZG dd� de�ZG dd� de�ZG dd� de�Ze ee ee eiZdS )z Relationship dependencies. � )� annotations� )� attributes)�exc)�sync)� unitofwork)�util)� MANYTOMANY)� MANYTOONE)� ONETOMANY� )�sqlc @ s� e Zd Zdd� Zedd� �Zdd� Zdd� Zd d � Zd d � Z d d� Z dd� Z dd� Z dd� Z dd� Zdd� Zdd� Zdd � Zd%d d �Zd d!� Zd"d#� Zd$S )&�DependencyProcessorc C s� || _ |j| _|j| _|j| _|j| _|j| _|j| _|j| _|j| _|j | _ | jr^t j | _ nt j | _ | jrvt j | _nt j | _d| jj|jf | _|j| _| j js�t�d| j ��d S )Nz%s_%sz|Can't build a DependencyProcessor for relationship %s. No target attributes to populate between parent and child are present)�prop�cascade�mapper�parent� secondary� direction� post_update�passive_deletes�passive_updates�enable_typechecksr �PASSIVE_NO_INITIALIZE�_passive_delete_flag� PASSIVE_OFF�_passive_update_flag� _sort_key�key�sort_key�synchronize_pairs�sa_exc� ArgumentError)�selfr � r$ �N/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/dependency.py�__init__ s0 ��z DependencyProcessor.__init__c C s t |j |�S �N)�_direction_to_processorr )�clsr r$ r$ r% �from_relationship; s z%DependencyProcessor.from_relationshipc C s | j j�| j��|�S )z�return True if the given object instance has a parent, according to the ``InstrumentedAttribute`` handled by this ``DependencyProcessor``. )r Z class_manager�get_implr � hasparent�r# �stater$ r$ r% r, ? s z DependencyProcessor.hasparentc C s |� | d� dS )z�establish actions and dependencies related to a flush. These actions will operate on all relevant states in the aggregate. TN)�register_preprocessor�r# �uowr$ r$ r% �per_property_preprocessorsG s z.DependencyProcessor.per_property_preprocessorsc C sz t �|| dd�}t �|| dd�}t �|| jj�}t �|| jj�}t �|| jj�}t �|| jj�}| �|||||||� d S �NFT)r � ProcessAll� SaveUpdateAllr �primary_base_mapperr � DeleteAll�per_property_dependencies)r# r1 � after_save� before_delete� parent_saves� child_saves�parent_deletes� child_deletesr$ r$ r% �per_property_flush_actionsP s. �����z.DependencyProcessor.per_property_flush_actionsc C s� | j j}t�||�}t�||�}|r<t�|| dd�}d|_nt�|| dd�}d|_||jvr�||jvsjJ �|df|dfg} d} nd} |s�t�|| jj �} d } }| |jv r�d} n&t�|| jj �} d } }| |jv r�d} |D �]}|j | j j � ||j|r�| jntj�}|�sq�|�r8t�|| d|�}| �rZt�||�} n"t�|| d|�}| �rZt�||�} | �r�g } |D ]\\}}||jv�r�d}n6|j| \}}|�r�t�||�df}nt�||�df}| �|� �qh| D ]"\}}| �|| | |||||� �q�q�dS )z�establish actions and dependencies related to a flush. These actions will operate on all relevant states individually. This occurs only if there are cycles in the 'aggregated' version of events. TFN)NN)r r6 r r5 r7 r4 �disabledZcyclesr � base_mapper�managerr �implZget_all_pending�dictr r r Z ProcessStateZ DeleteStateZSaveUpdateState�states�append�per_state_dependencies)r# r1 rE �isdeleteZchild_base_mapperr< r> r: r9 Z child_actionsZchild_in_cyclesr; r= Zparent_in_cyclesr. Zsum_Z child_state�child� child_action�deletedZlistonly� childisdeleter$ r$ r% �per_state_flush_actionsl s� � �� � � �z+DependencyProcessor.per_state_flush_actionsc C s dS �NFr$ �r# � uowcommitrE r$ r$ r% �presort_deletes� s z#DependencyProcessor.presort_deletesc C s dS rN r$ rO r$ r$ r% � presort_saves� s z!DependencyProcessor.presort_savesc C s d S r' r$ rO r$ r$ r% �process_deletes� s z#DependencyProcessor.process_deletesc C s d S r' r$ rO r$ r$ r% � process_saves� s z!DependencyProcessor.process_savesc C s| |r | j rtjtjB }n | jtu r*tj}n tjtjB }|D ]&}|�|| j |�}|r:|� � s: dS q:|oz| j j oz| j |jv S )NT)r r r �INCLUDE_PENDING_MUTATIONSr r ZPASSIVE_NO_FETCH_RELATEDr �get_attribute_historyr �emptyr Z_is_self_referentialr Zmappers)r# rP rE rH �passive�s�historyr$ r$ r% �prop_has_changes� s$ �� � � �z$DependencyProcessor.prop_has_changesc C s� | j jr$|d u r$t�d| j f ��nn|d ur�| jj|| j d�s�| jj|dd�rtt�d|j| j | jj| jd� ��n t�d|j| j | jjd� ��d S )Nz-Can't flush None value found in collection %s)Zallow_subtypesTaE Attempting to flush an item of type %(x)s as a member of collection "%(y)s". Expected an object of type %(z)s or a polymorphic subclass of this type. If %(x)s is a subclass of %(z)s, configure mapper "%(zm)s" to load this subtype polymorphically, or set enable_typechecks=False to allow any subtype to be accepted for flush. )�x�y�zZzmz�Attempting to flush an item of type %(x)s as a member of collection "%(y)s". Expected an object of type %(z)s or a polymorphic subclass of this type.)r\ r] r^ )r �uselistr Z FlushErrorr Z_canloadr �class_r- r$ r$ r% �_verify_canload s6 ��� ������z#DependencyProcessor._verify_canloadc C s t � �d S r' ��NotImplementedError)r# r. rI �associationrow� clearkeysrP r$ r$ r% � _synchronize3 s z DependencyProcessor._synchronizec C s> | j js d S tt| jgdd� | j jD � ��}|�d|ft�S )Nc S s g | ] }|j �qS r$ )r )�.0�pr$ r$ r% � <listcomp>; � zCDependencyProcessor._get_reversed_processed_set.<locals>.<listcomp>Z reverse_key)r �_reverse_property�tuple�sortedr �memo�set)r# r1 Z process_keyr$ r$ r% �_get_reversed_processed_set6 s �z/DependencyProcessor._get_reversed_processed_setFc C s8 |D ].}|r|d ur|� |dd� | jjD �� q4qd S )Nc S s g | ] \}}|�qS r$ r$ )rg �l�rr$ r$ r% ri C rj z4DependencyProcessor._post_update.<locals>.<listcomp>)Zregister_post_updater r )r# r. rP �related� is_m2o_deleter\ r$ r$ r% � _post_update? s �z DependencyProcessor._post_updatec C s t � �d S r' rb �r# rP r. r$ r$ r% � _pks_changedG s z DependencyProcessor._pks_changedc C s d| j j| jf S )Nz%s(%s))� __class__�__name__r )r# r$ r$ r% �__repr__J s z DependencyProcessor.__repr__N)F)ry � __module__� __qualname__r& � classmethodr* r, r2 r? rM rQ rR rS rT r[ ra rf rp ru rw rz r$ r$ r$ r% r s$ r ) r c @ sL e Zd Zdd� Zdd� Zdd� Zdd� Zd d � Zd d � Zd d� Z dd� Z dS )� OneToManyDPc C s� | j r\t�|| jjd�}t�|| jjd�} |j�||f||f||f|| f| |f| |fg� n6|j�||f||f||f||f||f||f||fg� d S r3 �r r � PostUpdateAllr r6 � dependencies�update) r# r1 r; r< r= r> r9 r: �child_post_updates�child_pre_updatesr$ r$ r% r8 O s4 � ��� ��z%OneToManyDP.per_property_dependenciesc C s� | j r�t�|| jjd�} t�|| jjd�} |sl|rL|j�||f|| fg� q�|j�||f||f|| fg� q�|r�|j�|| f| |fg� q�|j�|| f| |fg� n<|s�|j�||f||f||fg� n|j�||f||fg� d S r3 r ) r# r1 � save_parent� delete_parentrJ r9 r: rH rL r� r� r$ r$ r% rG x sR � ������������z"OneToManyDP.per_state_dependenciesc C s� | j j o| jdk }|D ]�}|�|| j| j�}|r|jD ]<}|d ur:| �|�du r:| j jrl|j |dd� q:|� |� q:|r|j D ] }|d ur�|j |d| j d� q�qd S )N�allFT�rH �delete�� operationr ) r r� r rV r r rK r, � delete_orphan�register_object� unchangedr �r# rP rE �should_null_fksr. rZ rI r$ r$ r% rQ � s$ � � �zOneToManyDP.presort_deletesc C sd |� d| ft�}| jj o$| jdk }|D �]2}| �||�}|rF| jrTtjtj B }n tj tj B }|� || j |�}|�r&|j D ] } | d ur||j| dd| jd� q||�|j � |jD ]t} | jjs�|r�|j| dd| jd� q�| �| �du r�|j| dd| jd� | j�d| �D ] \} } } } |j| dd � �qq�|r*|r*|jD ](} | d u�r4|j| d| jd | jd � �q4q*d S ) N�children_addedr� T�add)Z cancel_deleter� r Fr� �rH r� r r� z pk changer� )rn ro r r� r rw r r r rU r rV r �addedr� r r� rK r, r �cascade_iteratorr� )r# rP rE r� r� r. � pks_changedrX rZ rI �c�m�st_�dct_r$ r$ r% rR � sr � ���� � ��� �zOneToManyDP.presort_savesc C s� | j s| jdks�|�d| ft�}|D ]�}|�|| j| j�}|r$|jD ]H}|d urD| �|�du rD| � ||d d|d� | j rD|rD| � |||g� qD| j s�| j j s$t|j ��|�D ]:}|d ur�| � ||d d|d� | j r�|r�| � |||g� q�q$d S )Nr� r� FT)r r rn ro rV r r rK r, rf ru r r� r� � difference)r# rP rE r� r. rZ rI r$ r$ r% rS s: � � � � � � �zOneToManyDP.process_deletesc C s� | j j o| jdk }|D ]�}|�|| jtj�}|r|jD ]6}| �||d d|d� |d ur:| j r:| � |||g� q:|j D ].}|rx| j jsx| � |�sx| �||d d|d� qx| � ||�r|jD ]}| �||d d|d� q�qd S )Nr� FT)r r� r rV r r r r� rf r ru rK r, rw r� r� r$ r$ r% rT D s: � � � ��� � �zOneToManyDP.process_savesc C sp |}|}| � |� |d u s*| js.|�|�r.d S |rHt�|| j| jj� n$t�|| j || j| jj|| j oh|� d S r' ) ra r � is_deletedr �clearr r r �populater r ) r# r. rI rd re rP r� �source�destr$ r$ r% rf f s( ���zOneToManyDP._synchronizec C s t �||| j| jj�S r' �r �source_modifiedr r r rv r$ r$ r% rw } s �zOneToManyDP._pks_changedN) ry r{ r| r8 rG rQ rR rS rT rf rw r$ r$ r$ r% r~ N s )AD,"r~ c @ sN e Zd Zdd� Zdd� Zdd� Zdd� Zd d � Zd d � Zd d� Z ddd�Z dS )� ManyToOneDPc C s. t �| |� | jjD ]}|j�t|�� qd S r' )r r& r Zself_and_descendantsZ_dependency_processorsrF �DetectKeySwitch)r# r r r$ r$ r% r& � s zManyToOneDP.__init__c C s� | j rbt�|| jjd�}t�|| jjd�} |j�||f||f||f|| f|| f| |f| |fg� n$|j�||f||f||f||fg� d S r3 �r r r� r r6 r� r� ) r# r1 r; r< r= r> r9 r: �parent_post_updates�parent_pre_updatesr$ r$ r% r8 � s0 � ��� ��z%ManyToOneDP.per_property_dependenciesc C s� | j r�|sZt�|| jjd�} |r:|j�|| f| |fg� q�|j�||f||f|| fg� q�t�|| jjd�} |j�|| f| |f| |fg� nL|s�|s�|j�||f||fg� q�|j�||fg� n|r�|j�||fg� d S r3 r� ) r# r1 r� r� rJ r9 r: rH rL r� r� r$ r$ r% rG � sD ����� ����z"ManyToOneDP.per_state_dependenciesc C s� | j js| j jr�|D ]�}|�|| j| j�}|r| j jr@|�� }n|�� }|D ]P}|d u rZqL|j|dd| j d� | j � d|�}|D ]\}} } } |j| dd� q�qLqd S )NTr� r� r� ) r r� r� rV r r �sumZ non_deletedr� r r r� ) r# rP rE r. rZ ZtodeleterI �tr� r� r� r� r$ r$ r% rQ � s* � �zManyToOneDP.presort_deletesc C s� |D ]�}|j |d| jd� | jjr|�|| j| j�}|r|jD ]T}| �|�du r>|j |dd| jd� | j � d|�}|D ]\}}} } |j | dd� qvq>qd S )Nr� r� FTr� r� r� ) r� r r r� rV r r rK r, r r� ) r# rP rE r. rZ rI r� r� r� r� r� r$ r$ r% rR s$ � �zManyToOneDP.presort_savesc C sn | j rj| jjsj| jdksj|D ]L}| �|d d d|� |r | j r |�|| j| j�}|r | j|||� � dd� q d S )Nr� T)rt ) r r r� r rf rV r r ru r� )r# rP rE r. rZ r$ r$ r% rS s ��� � �zManyToOneDP.process_deletesc C s~ |D ]t}|� || jtj�}|r|jrF|jD ]}| �||d d|d� q*n|jr`| �|d d d|d� | jr| �|||� � � qd S )NFr� Tr� ) rV r r r r� rf rK r ru r� )r# rP rE r. rZ rI r$ r$ r% rT ) s � � �zManyToOneDP.process_savesNc C s� |d u s| j s |�|�r d S |d urX|d urX|j�|�sXt�dt�|�|| jf � d S |sd|d u rzt � || j | jj � n(| � |� t �|| j|| j | jj |d� d S )N�GObject of type %s not in session, %s operation along '%s' won't proceedF)r r� �session�_contains_stater �warn� mapperutil�state_class_strr r r� r r ra r� r �r# r. rI rd re rP r� r$ r$ r% rf ; s< ���� ��� �zManyToOneDP._synchronize)N) ry r{ r| r& r8 rG rQ rR rS rT rf r$ r$ r$ r% r� � s '8 �r� c @ sh e Zd ZdZdd� Zdd� Zdd� Zdd � Zd d � Zd d � Z dd� Z dd� Z dd� Z dd� Z dd� ZdS )r� a� For many-to-one relationships with no one-to-many backref, searches for parents through the unit of work when a primary key has changed and updates them. Theoretically, this approach could be expanded to support transparent deletion of objects referenced via many-to-one as well, although the current attribute system doesn't do enough bookkeeping for this to be efficient. c C s< | j jr,| jrd S ddd� | j jD �v r,d S |�| d� d S )NFc s s | ] }|j V qd S r' )r )rg r r$ r$ r% � <genexpr>u s �z=DetectKeySwitch.per_property_preprocessors.<locals>.<genexpr>)r rk r r/ r0 r$ r$ r% r2 p s �z*DetectKeySwitch.per_property_preprocessorsc C s6 t �|| jj�}t �|| dd�}|j�||fg� d S rN )r r5 r rA r4 r� r� )r# r1 r; r9 r$ r$ r% r? } s z*DetectKeySwitch.per_property_flush_actionsc C s d S r' r$ )r# r1 rE rH r$ r$ r% rM � s z'DetectKeySwitch.per_state_flush_actionsc C s d S r' r$ rO r$ r$ r% rQ � s z DetectKeySwitch.presort_deletesc C s | j s| �||� d S r' �r �_process_key_switches)r# r1 rE r$ r$ r% rR � s z DetectKeySwitch.presort_savesc C s" |s | j r | �||�}t|�S dS rN )r �_key_switchers�bool)r# r1 rE rH �dr$ r$ r% r[ � s z DetectKeySwitch.prop_has_changesc C s dsJ �d S rN r$ rO r$ r$ r% rS � s z DetectKeySwitch.process_deletesc C s | j s J �| �||� d S r' r� rO r$ r$ r% rT � s z DetectKeySwitch.process_savesc C sZ |� d| fdd� �\}}|�|�}|D ].}||vr&| �||�rJ|�|� q&|�|� q&|S )NZ pk_switchersc S s t � t � fS r' )ro r$ r$ r$ r% �<lambda>� rj z0DetectKeySwitch._key_switchers.<locals>.<lambda>)rn �unionrw r� )r# r1 rE ZswitchedZ notswitchedZ allstatesrY r$ r$ r% r� � s � z DetectKeySwitch._key_switchersc C s� | � ||�}|r�|jj�� D ]�}t|j| jj�s2q |j}|�| j �j ||| j d�}|t j ur |d ur | jjr||srq |d }n|}t �|�}||v r |�|d| j� t�|| j|| j| jj|| j� q d S )N)rX r F)r� r� Z identity_mapZ all_states� issubclassr` r rD r+ r �getr r ZPASSIVE_NO_RESULTr r_ Zinstance_stater� r r r� r r ) r# ZdeplistrP Z switchersr. Zdict_rs Z related_objZ related_stater$ r$ r% r� � s@ ��� ��z%DetectKeySwitch._process_key_switchesc C s t |j�o t�||| j| jj�S r' )r� r r r� r r r rv r$ r$ r% rw � s �z DetectKeySwitch._pks_changedN)ry r{ r| �__doc__r2 r? rM rQ rR r[ rS rT r� r� rw r$ r$ r$ r% r� d s %r� c @ sT e Zd Zdd� Zdd� Zdd� Zdd� Zd d � Zd d � Zd d� Z dd� Z dd� Z dS )� ManyToManyDPc C s: |j �||f||f||f||f||f||f||fg� d S r' �r� r� )r# r1 r; r< r= r> r9 r: r$ r$ r% r8 � s ��z&ManyToManyDP.per_property_dependenciesc C sX |s<|r"|j �||f||fg� qT|j �||f||fg� n|j �||f||fg� d S r' r� ) r# r1 r� r� rJ r9 r: rH rL r$ r$ r% rG � s ���z#ManyToManyDP.per_state_dependenciesc C s& | j s"|D ]}|�|| j| j� q d S r' )r rV r r )r# rP rE r. r$ r$ r% rQ s �z ManyToManyDP.presort_deletesc C s� | j s.|D ]"}| �||�r |�|| jtj� q | jjs:d S |D ]r}|�|| jtj�}|r>|j D ]P}| � |�du r^|j |dd| j d� | j �d|�D ]\}}}} |j |dd� q�q^q>d S )NFTr� r� r� )r rw rV r r r r r� r rK r, r� r r r� ) r# rP rE r. rZ rI r� r� r� r� r$ r$ r% rR s2 � � ��zManyToManyDP.presort_savesc s� g }g }g }| � |�}t� }|D ]�� |�� | j| j�}|r |�� D ]F} | d u sB|d urd� | f|v rdqBi } | �� | | d|d�s~qB|�| � qB|�� fdd�|�� D �� q |d ur�|�|� | � ||||� d S )NFr� c 3 s | ]}|� fV qd S r' r$ �rg r� �r. r$ r% r� [ rj z/ManyToManyDP.process_deletes.<locals>.<genexpr>) rp ro rV r r Z non_addedrf rF r� � _run_crud) r# rP rE �secondary_delete�secondary_insert�secondary_update� processed�tmprZ rI rd r$ r� r% rS < sD � � �� �z ManyToManyDP.process_deletesc s� g }g }g }| � |�}t� }|D �]F� | j o8| �|� �}|rLtjtjB } n tjtjB } |�� | j | �} | r | j D ]>} |d ur�� | f|v r�qri } | � � | | d|d�s�qr|� | � qr| j D ]>} |d ur҈ | f|v r�q�i } | � � | | d|d�s�q�|� | � q�|�� fdd�| j | j D �� |r | jD ]D} i } t�� | j| d| jj� t�| | j| d| jj� |� | � �q"q |d u�r~|�|� | �||||� d S )NFr� r� c 3 s | ]}|� fV qd S r' r$ r� r� r$ r% r� � rj z-ManyToManyDP.process_saves.<locals>.<genexpr>�old_)rp ro r rw r r rU r rV r r� rf rF rK r� r� r r r r r �secondary_synchronize_pairsr� ) r# rP rE r� r� r� r� r� Zneed_cascade_pksrX rZ rI rd r$ r� r% rT d s� ����� � � �� �zManyToManyDP.process_savesc s |j �| j�}|r�|d � | j�� �tj� fdd�| jjD �� �}|� ||�}|� � r�|j t |�kr�t �d| jjt |�|j f ��|r�|d � | j�� �tj� fdd�| jjD �� �}|� ||�}|� � r�|j t |�kr�t �d| jjt |�|j f ��|�r| j�� }|� ||� d S )Nr c s, g | ]$}|j � v r|tj|j |jd �k�qS )��type_�r r Z bindparam�typer� �rd r$ r% ri � s �z*ManyToManyDP._run_crud.<locals>.<listcomp>zRDELETE statement on table '%s' expected to delete %d row(s); Only %d were matched.c s0 g | ](}|j � v r|tjd |j |jd�k�qS )r� r� r� r� r� r$ r% ri � s �zRUPDATE statement on table '%s' expected to update %d row(s); Only %d were matched.)Z transaction� connectionr r r� �wherer �and_r� �executeZ supports_sane_multi_rowcountZrowcount�lenr ZStaleDataError� descriptionr� �insert)r# rP r� r� r� r� Z statement�resultr$ r� r% r� � s` ��� � ���� ��� � ���� zManyToManyDP._run_crudc C s� | � |� |d u rdS |d urP|j�|�sP|jsLt�dt�|�|| jf � dS t � || j || jj � t � || j || jj� dS )NFr� T)ra r� r� rK r r� r� r� r r Z populate_dictr r r r� r� r$ r$ r% rf � s* ����zManyToManyDP._synchronizec C s t �||| j| jj�S r' r� rv r$ r$ r% rw s �zManyToManyDP._pks_changedN) ry r{ r| r8 rG rQ rR rS rT r� rf rw r$ r$ r$ r% r� � s "(M= r� N)r� � __future__r � r r r r r r� Z interfacesr r r r! r r r~ r� r� r� r( r$ r$ r$ r% �<module> s8 3 7 bu >� sqlalchemy/orm/__pycache__/util.cpython-39.pyc 0000644 00000165431 15125143220 0015326 0 ustar 00 a ��Jh < � @ s& d dl mZ d dlZd dlZd dlZd dlZd dlZd dlmZ d dlmZ d dlm Z d dlm Z d dlm Z d dlm Z d d lm Z d d lmZ d d lmZ d d lmZ d d lmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlZddlmZ ddlm Z ddlm Z ddl m Z ddl m Z ddl m!Z! ddl m"Z" dd l#m$Z$ dd l#m%Z% dd l#m&Z& dd l#m'Z' dd l#m(Z( dd!l#m)Z) dd"l#m*Z* dd#l#m+Z+ dd$l#m,Z, dd%l#m-Z- dd&l#m.Z. dd'l#m/Z/ dd(l#m0Z0 dd)l#m1Z1 dd*l#m2Z2 dd+l#m3Z3 dd,l#m4Z4 dd-l#m5Z5 dd.l#m6Z6 dd/l7m8Z8 dd0l7m9Z9 dd1l7m:Z: dd2l7m;Z; dd3l7m<Z< dd4l=m>Z> d5d6lm?Z? d5dlm Z@ d5d7lmAZA d5d8lmBZB d5d9lmCZC d5d:lDmEZE d5d;lBmFZF d5d<lBmGZG d5d=lBmHZH d5d>lBmIZI d5d9lBmCZJ d5d?lBmKZK d5d@lLmMZM d5dAlNmOZO d5dBlPmQZQ d5dClRmSZS d5dDlRmTZT d5dElUmVZV d5dFlUmWZW d5dGlXmYZY d5dHlZm[Z[ d5dIl\m]Z^ d5dJl\m_Z` d5dKl\maZa d5dLl\mbZb d5dMl\mcZc d5dNl\mdZd d5dOl\meZe ej�r$ddPl mfZf ddQl mgZg ddRl mhZh ddSl miZi ddTljmkZk ddUljmlZl ddVlmmnZn ddWl=moZo ddXlpmqZq ddYlrmsZs d5dZltmuZu d5d[ltmvZv d5d\lLmwZw d5d]lLmxZx d5d^lLmyZy d5d_lLmzZz d5d`lLm{Z{ d5dalLm|Z| d5dblNm}Z} d5dclPm~Z~ d5ddlUmZ d5delXm�Z� d5dflXm�Z� d5dglXm�Z� d5dhl�m�Z� d5dil\m�Z� edjedk�Z�e�dl�Z�ej�ej�eC��e.e6e+dm��dn�Z�G dodp� dpee�Z�e e�e�e^��Z]G dqdr� dree�Z�e e�e�e`��Z_G dsdt� dte e� �Z�dudv� Z�d�dydz�Z�d�dddd{�d|d}d~dd�d�d��d�d��Z�G d�d�� d�ej��Z�G d�d�� d�eJj��Z�G d�d�� d�eJj��Z�G d�d�� d�eAj�d� e:e �Z�eAj�G d�d�� d�e;e e<eSe,e[eAj�d� e e � �Z�G d�d�� d��Z�G d�d�� d�e8�Z�eA��e��d�d�� � eA��e��d�d�d��d�d���Z�e�ee �Z�eA��e��d�d�d��d�d���Z�eAj�G d�d�� d�e:e� eOeTeAj�d� e,��Z�d�d�d�d�d��d�d��Z�d�d�d��d�d��Z�d�d�d��d�d��Z�G d�d�� d�eGj��Z�d�d�d�d�d�d��d�d��Z�d�d�d��d�d��Z�d�d�d��d�d��Z�d�d�d�d��d�d��Z�d�d�d�d��d�d��Z�d�d�d�d��d�d��Z�d�d�d�dĜd�dƄZ�d�d�d�d�dɜd�d˄Z�G d�d̈́ d�e��Z�d�d�d�dϜd�dфZ�d�d�d�d�d�d�d�d�d�d�d�d՜ d�dׄZ�d�d�dd�dڄZ�dS )�� )� annotationsN)� AbstractSet)�Any)�Callable)�cast)�Dict)� FrozenSet)�Generic)�Iterable)�Iterator)�List)�Match)�Optional)�Sequence)�Tuple)�Type)� TYPE_CHECKING)�TypeVar)�Union� )� attributes)�exc)�_O)�insp_is_aliased_class)�insp_is_mapper)�prop_is_relationship)�_class_to_mapper)�_MappedAnnotationBase)� _never_set)�_none_only_set)� _none_set)� attribute_str)� class_mapper)� DynamicMapped)�InspectionAttr)� instance_str)�Mapped)� object_mapper)� object_state)�opt_manager_of_class)� ORMDescriptor)�state_attribute_str)�state_class_str)� state_str)�WriteOnlyMapped)�CriteriaOption)�MapperProperty)�ORMColumnsClauseRole)�ORMEntityColumnsClauseRole)�ORMFromClauseRole)� PathRegistry� )�event)� inspection)�sql)�util�� result_tuple)� coercions)� expression)�lambdas)�roles)�visitors)� is_selectable)�SupportsCloneAnnotations)�ColumnCollection)� HasCacheKey)�MemoizedHasCacheKey)� ColumnElement)�KeyedColumnElement)� FromClause)� MemoizedSlots)�de_stringify_annotation)�eval_name_only)�fixup_container_fwd_refs)� get_origin)�is_origin_of_cls)�Literal)�Protocol)� _EntityType)�_IdentityKeyType)�_InternalEntityType)� _ORMCOLEXPR)� _MapperEntity)�ORMCompileState)�Mapper)�AbstractEntityRegistry)�Query)�RelationshipProperty)�Row)� RowMapping)�_CE)�_ColumnExpressionArgument)�_EquivalentColumnMap)�_FromClauseArgument)�_OnClauseArgument)�_PropagateAttrsType)�_SA)�ReadOnlyColumnCollection)� BindParameter)�_ColumnsClauseElement)�Select)� Selectable)�anon_map)�_AnnotationScanType�_T)�bound)�delete� delete-orphan�all�merge�expunge� save-update�refresh-expire�none)r& r. r# )Zlocals_c @ s, e Zd Zddd�ddddddd �d d �ZdS ) �_DeStringifyAnnotationNF)�str_cleanup_fn�include_generic� Type[Any]rj �strz#Optional[Callable[[str, str], str]]�bool)�cls� annotation�originating_modulerv rw �returnc C s d S �N� )�selfr{ r| r} rv rw r� r� �H/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/util.py�__call__� s z _DeStringifyAnnotation.__call__��__name__� __module__� __qualname__r� r� r� r� r� ru � s �ru c @ s e Zd Zdddd�dd�ZdS )� _EvalNameOnlyry r )�name� module_namer~ c C s d S r r� )r� r� r� r� r� r� r� � � z_EvalNameOnly.__call__Nr� r� r� r� r� r� � s r� c s� e Zd ZU dZe�g d��ZeZg d�ZdZ de d< de d< de d< de d < de d < de d < d d d �� fdd� Z dd� Z e dd� �Z� ZS )�CascadeOptionszHKeeps track of the options sent to :paramref:`.relationship.cascade`)ro rt rn )rq ro rt rs rp )� save_updaterm �refresh_expirerp rq � delete_orphanrz r� rm r� rp rq r� z#Optional[Union[Iterable[str], str]])� value_listr~ c s� t |t�s|d u r | �|�S t|�}|�| j�rZt�dd�dd� t |�| j��D �� ��d|v rn|� | j � d|v r~|� � |� d� t� �| |�}d|v |_d|v |_d |v |_d |v |_d |v |_d |v |_|jr�|js�t�d � |S )Nz Invalid cascade option(s): %s�, c S s g | ] }t |��qS r� )�repr��.0�xr� r� r� � <listcomp>� s �z*CascadeOptions.__new__.<locals>.<listcomp>ro rt rr rm rs rp rq rn z5The 'delete-orphan' cascade option requires 'delete'.)� isinstancery � from_string�set� difference�_allowed_cascades�sa_exc� ArgumentError�join�sorted�update�_add_w_all_cascades�clear�discard�super�__new__r� rm r� rp rq r� r9 �warn)r{ r� �valuesr� �� __class__r� r� r� � s< ����� zCascadeOptions.__new__c C s dd� dd� t| �D �� S )NzCascadeOptions(%r)�,c S s g | ]}|�qS r� r� r� r� r� r� r� � r� z+CascadeOptions.__repr__.<locals>.<listcomp>)r� r� �r� r� r� r� �__repr__� s zCascadeOptions.__repr__c C s" dd� t �d|pd�D �}| |�S )Nc S s g | ] }|r|�qS r� r� )r� �cr� r� r� r� � r� z.CascadeOptions.from_string.<locals>.<listcomp>z\s*,\s*� )�re�split)r{ �argr� r� r� r� r� � s zCascadeOptions.from_string)r� r� r� �__doc__� all_cascadesr� r� r� Z_viewonly_cascades� __slots__�__annotations__r� r� � classmethodr� � __classcell__r� r� r� r� r� � s" � %r� c s� �s�fdd�� |r^� ���fdd�}� ���fdd�}� ���fdd�}� ���fd d �}n6� ���fd d�}� ���fd d�}� ���fd d�}t j| d|ddd� t j| d|dd� t j| d|ddd� |r�t j| d|ddd� dS )zNRuns a validation method on an attribute value to be set or appended. c s | j � j}|j|uS r )�manager�impl)�state� initiatorr� )�keyr� r� �detect_is_backref s z,_validator_events.<locals>.detect_is_backrefc s4 |j tjur,�s� | |�s,�| �� �|d�S |S d S �NF��opr ZOP_BULK_REPLACE�obj�r� �valuer� �r� �include_backrefsr� � validatorr� r� �append s ��z!_validator_events.<locals>.appendc s8 �s�| |�s4| � � � �� �fdd�|D �|d d �< d S )Nc s g | ]}��� |d ��qS )Fr� �r� r� �r� r� r� r� r� r� s �7_validator_events.<locals>.bulk_set.<locals>.<listcomp>�r� �r� r� r� r� r� r� �bulk_set s �z#_validator_events.<locals>.bulk_setc s( �s� | |�s �| � � �|d�S |S d S r� r� �r� r� Zoldvaluer� r� r� r� �set_ s z _validator_events.<locals>.set_c s$ �s� | |�s �| � � �|d� d S )NTr� r� r� r� r� �remove s z!_validator_events.<locals>.removec s2 |j tjur*�s� | |�s*�| �� �|�S |S d S r r� r� r� r� r� r� $ s ��c s8 �s�| |�s4| � � � �� �fdd�|D �|d d �< d S )Nc s g | ]}��� |��qS r� r� r� r� r� r� r� / r� r� r� r� r� r� r� r� , s c s& �s� | |�s �| � � �|�S |S d S r r� r� r� r� r� r� 1 s r� T)�raw�retvalZ bulk_replace)r� r� r� N)r6 �listen) �descr� r� Zinclude_removesr� r� r� r� r� r� r� r� �_validator_events� s r� �p_unionTc s6 t �� }i �i �| D ]|}| | �tjtj�dd���| |< i }�jD ]B}|j|krdt� d||f ��|� |j� |||j< |j �|j< qD|��< q� ��fdd��g }| � � D ]v\} �|dur�|� tj��fdd�|D �t�t�| ���|�g � ���� q�|� tj��fd d�|D �� ���� q�tj|� �|�S ) a0 Create a ``UNION`` statement used by a polymorphic mapper. See :ref:`concrete_inheritance` for an example of how this is used. :param table_map: mapping of polymorphic identities to :class:`_schema.Table` objects. :param typecolname: string name of a "discriminator" column, which will be derived from the query, producing the polymorphic identity for each row. If ``None``, no polymorphic discriminator is generated. :param aliasname: name of the :func:`~sqlalchemy.sql.expression.alias()` construct generated. :param cast_nulls: if True, non-existent columns, which are represented as labeled NULLs, will be passed into CAST. This is a legacy behavior that is problematic on some backends such as Oracle - in which case it can be set to False. T)Z allow_selectz�Polymorphic union can't use '%s' as the discriminator column due to mapped column %r; please apply the 'typecolname' argument; this is available on ConcreteBase as '_concrete_discriminator_name'c sf z�| | W S t y` � r>t�t�� �| ��| � Y S t�t�� �| ��| � Y S Y n0 d S r )�KeyErrorr8 r �null�labelZ type_coerce)r� �table)� cast_nulls� colnamemaps�typesr� r� �colo s z polymorphic_union.<locals>.colNc s g | ]}� |���qS r� r� �r� r� �r� r� r� r� r� ~ r� z%polymorphic_union.<locals>.<listcomp>c s g | ]}� |���qS r� r� r� r� r� r� r� � r� )r9 Z OrderedSetr< �expectr? ZStrictFromClauseRoler� r� r� ZInvalidRequestError�add�type�itemsr� r8 �selectZliteral_column�sql_utilZ_quote_ddl_exprr� � select_fromZ union_all�alias) Z table_mapZ typecolnameZ aliasnamer� Zcolnamesr� �mr� �result�type_r� )r� r� r� r� r� r� �polymorphic_union> s^ � �� ����� �� ���r� )�instance�row�identity_tokenzOptional[Type[_T]]zUnion[Any, Tuple[Any, ...]]z Optional[_T]z%Optional[Union[Row[Any], RowMapping]]� Optional[Any]z_IdentityKeyType[_T])�class_�identr� r� r� r~ c C sz | durRt | �}|du rB|du r*t�d��|jtt�|��|d�S |j||d�S n$|durlt|�}|� |�S t�d��dS )a5 Generate "identity key" tuples, as are used as keys in the :attr:`.Session.identity_map` dictionary. This function has several call styles: * ``identity_key(class, ident, identity_token=token)`` This form receives a mapped class and a primary key scalar or tuple as an argument. E.g.:: >>> identity_key(MyClass, (1, 2)) (<class '__main__.MyClass'>, (1, 2), None) :param class: mapped class (must be a positional argument) :param ident: primary key, may be a scalar or tuple argument. :param identity_token: optional identity token .. versionadded:: 1.2 added identity_token * ``identity_key(instance=instance)`` This form will produce the identity key for a given instance. The instance need not be persistent, only that its primary key attributes are populated (else the key will contain ``None`` for those missing values). E.g.:: >>> instance = MyClass(1, 2) >>> identity_key(instance=instance) (<class '__main__.MyClass'>, (1, 2), None) In this form, the given instance is ultimately run though :meth:`_orm.Mapper.identity_key_from_instance`, which will have the effect of performing a database check for the corresponding row if the object is expired. :param instance: object instance (must be given as a keyword arg) * ``identity_key(class, row=row, identity_token=token)`` This form is similar to the class/tuple form, except is passed a database result row as a :class:`.Row` or :class:`.RowMapping` object. E.g.:: >>> row = engine.execute(text("select * from table where a=1 and b=2")).first() >>> identity_key(MyClass, row=row) (<class '__main__.MyClass'>, (1, 2), None) :param class: mapped class (must be a positional argument) :param row: :class:`.Row` row returned by a :class:`_engine.CursorResult` (must be given as a keyword arg) :param identity_token: optional identity token .. versionadded:: 1.2 added identity_token Nzident or row is required)r� z class or instance is required) r" r� r� Z identity_key_from_primary_key�tupler9 Zto_listZidentity_key_from_rowr' Zidentity_key_from_instance)r� r� r� r� r� �mapperr� r� r� � identity_key� s E �� r� c @ sh e Zd ZdZe�� Ze�� Ze�� Ze�� Z e�� Z e�� Z e�� Z e�� Z e�� Ze�� Ze�� ZdS )�_TraceAdaptRolea� Enumeration of all the use cases for ORMAdapter. ORMAdapter remains one of the most complicated aspects of the ORM, as it is used for in-place adaption of column expressions to be applied to a SELECT, replacing :class:`.Table` and other objects that are mapped to classes with aliases of those tables in the case of joined eager loading, or in the case of polymorphic loading as used with concrete mappings or other custom "with polymorphic" parameters, with whole user-defined subqueries. The enumerations provide an overview of all the use cases used by ORMAdapter, a layer of formality as to the introduction of new ORMAdapter use cases (of which none are anticipated), as well as a means to trace the origins of a particular ORMAdapter within runtime debugging. SQLAlchemy 2.0 has greatly scaled back ORM features which relied heavily on open-ended statement adaption, including the ``Query.with_polymorphic()`` method and the ``Query.select_from_entity()`` methods, favoring user-explicit aliasing schemes using the ``aliased()`` and ``with_polymorphic()`` standalone constructs; these still use adaption, however the adaption is applied in a narrower scope. N)r� r� r� r� �enum�auto� ALIASED_INSPZ JOINEDLOAD_USER_DEFINED_ALIASZ JOINEDLOAD_PATH_WITH_POLYMORPHICZJOINEDLOAD_MEMOIZED_ADAPTERZMAPPER_POLYMORPHIC_ADAPTERZWITH_POLYMORPHIC_ADAPTERZ#WITH_POLYMORPHIC_ADAPTER_RIGHT_JOINZ DEPRECATED_JOIN_ADAPT_RIGHT_SIDEZADAPT_FROM_STATEMENTZCOMPOUND_EAGER_STATEMENTZLEGACY_SELECT_FROM_ALIASr� r� r� r� r� � s r� c sH e Zd ZdZdZddddddd�ddd d d d d d d �� fd d�Z� ZS )�ORMStatementAdapterz.ColumnAdapter which includes a role attribute.)�roleNFT�� equivalents�adapt_required�allow_label_resolve�anonymize_labels�adapt_on_names�adapt_from_selectablesr� rh � Optional[_EquivalentColumnMap]rz �!Optional[AbstractSet[FromClause]])r� � selectabler� r� r� r r r c s$ || _ t� j|||||||d� d S )Nr� )r� r� �__init__) r� r� r r� r� r� r r r r� r� r� r ) s �z ORMStatementAdapter.__init__)r� r� r� r� r� r r� r� r� r� r� r� $ s �r� c sj e Zd ZU dZdZded< ded< ddd ddd ddd �d d d dddddddd� � fdd�Zdd� Z� ZS )� ORMAdapterzaColumnAdapter subclass which excludes adaptation of entities from non-matching mappers. )r� r� �is_aliased_class� aliased_insprz r �Optional[AliasedInsp[Any]]r NFT)r� r� r� r r �limit_on_entityr r r� �_InternalEntityType[Any]r zOptional[Selectable]r ) r� �entityr� r� r� r r r r r c sh || _ |j| _|d u r |j}t|�r2d| _|| _n d| _d | _t� j||||||rX| jnd | | d� d S )NTF)r� r� r Z include_fnr r ) r� r� r r r r r� r � _include_fn) r� r� r r� r� r� r r r r r r� r� r� r L s& �zORMAdapter.__init__c C s, |j �dd �}| p*|�| j�p*| j�|�S )N� parentmapper)� _annotations�get�isar� )r� �elemr r� r� r� r p s zORMAdapter._include_fn) r� r� r� r� r� r� r r r� r� r� r� r� r A s �($r c @ s� e Zd ZU dZded< d"dddd d d d d d d d � dd�Zeddd�dd��Zddd�dd�Zddddd�dd �Z dd �d d �Z dd �d d!�Z dS )#� AliasedClassa� Represents an "aliased" form of a mapped class for usage with Query. The ORM equivalent of a :func:`~sqlalchemy.sql.expression.alias` construct, this object mimics the mapped class using a ``__getattr__`` scheme and maintains a reference to a real :class:`~sqlalchemy.sql.expression.Alias` object. A primary purpose of :class:`.AliasedClass` is to serve as an alternate within a SQL statement generated by the ORM, such that an existing mapped entity can be used in multiple contexts. A simple example:: # find all pairs of users with the same name user_alias = aliased(User) session.query(User, user_alias).join( (user_alias, User.id > user_alias.id) ).filter(User.name == user_alias.name) :class:`.AliasedClass` is also capable of mapping an existing mapped class to an entirely new selectable, provided this selectable is column- compatible with the existing mapped selectable, and it can also be configured in a mapping as the target of a :func:`_orm.relationship`. See the links below for examples. The :class:`.AliasedClass` object is constructed typically using the :func:`_orm.aliased` function. It also is produced with additional configuration when using the :func:`_orm.with_polymorphic` function. The resulting object is an instance of :class:`.AliasedClass`. This object implements an attribute scheme which produces the same attribute and method interface as the original mapped class, allowing :class:`.AliasedClass` to be compatible with any attribute technique which works on the original class, including hybrid attributes (see :ref:`hybrids_toplevel`). The :class:`.AliasedClass` can be inspected for its underlying :class:`_orm.Mapper`, aliased selectable, and other information using :func:`_sa.inspect`:: from sqlalchemy import inspect my_alias = aliased(MyClass) insp = inspect(my_alias) The resulting inspection object is an instance of :class:`.AliasedInsp`. .. seealso:: :func:`.aliased` :func:`.with_polymorphic` :ref:`relationship_aliased_class` :ref:`relationship_to_window_function` ry r� NFz_EntityType[_O]�Optional[FromClause]� Optional[str]rz � Optional[Sequence[Mapper[Any]]]� Optional[ColumnElement[Any]]r ) �mapped_class_or_acr� r� �flatr �with_polymorphic_mappers� with_polymorphic_discriminator� base_alias�use_mapper_path�represents_outer_joinc C s� t dt�|��} | j} d} |d u rN| jr<| jjr<| j�� }qX| jj ||d�}n | jrXd} |d usdJ �t | | |||rv|n| j |d ur�|n| j || || | � | _ d| jj� d�| _d S )N�_InternalEntityType[_O]F�r� r T�aliased(�))r r7 �inspectr� r r Z _is_subqueryr� Z _with_polymorphic_selectable�_anonymous_fromclause� AliasedInspr �polymorphic_on� _aliased_inspr� r� )r� r r� r� r r r r r r r Zinspr� � nest_adaptersr� r� r� r � sD � �� ���zAliasedClass.__init__�AliasedInsp[_O]�AliasedClass[_O])r r~ c C s\ | � | �}d|jjj� d�|_||_|jrX|jD ]&}||ur0t�|�}t ||jj|� q0|S )Nr" r# ) r� r� r� r� r( �_is_with_polymorphic�_with_polymorphic_entitiesr � _reconstitute_from_aliased_insp�setattr)r{ r r� Zsub_aliased_insp�entr� r� r� r. � s �z,AliasedClass._reconstitute_from_aliased_inspr )r� r~ c C s� z| j d }W n ty& t� �Y n0 |j}t||�}t|d�rZt|d�rZt�|j| �S t|d�rp|� d | �}t|d�r�|� |�}t | ||� |S )Nr( r� �__self__�__get__�adapt_to_entity) �__dict__r� �AttributeError�_target�getattr�hasattrr� � MethodType�__func__r2 r3 r/ )r� r� r( �target�attrr� r� r� � __getattr__ s zAliasedClass.__getattr__r )r� � mapped_classr r~ c C sr t ||�}t|d�r,t|d�r,t�|j| �S t|d�rB|�d | �}t|d�rnt�| �|_|� |�}t | ||� |S )Nr� r1 r2 r3 ) r7 r8 r� r9 r: r2 �weakref�ref� _weak_entityr3 r/ )r� r� r> r r< r� r� r� �_get_from_serialized s z!AliasedClass._get_from_serialized�r~ c C s dt | �| jjjf S )Nz<AliasedClass at 0x%x; %s>)�idr( r6 r� r� r� r� r� r� 6 s �zAliasedClass.__repr__c C s t | j�S r )ry r( r� r� r� r� �__str__< s zAliasedClass.__str__) NNFFNNNFF) r� r� r� r� r� r r� r. r= rB r� rE r� r� r� r� r v s$ ; �": r r* c @ s� e Zd ZU dZdZdejjfdejjfdejjfdejj fdejj fdej j fd ej j fgZ d ed < d ed< d ed< ded< ded< ded< ded< ddd ddddddddd � d d �Zed\d!d"dddd#d$�d%d&��Zed]d'd(d)ddddddddd*� d+d,��Zedd-�d.d/��Zd0Zd d-�d1d2�Zedd-�d3d4��Zed5d-�d6d7��Zed8d-�d9d:��Zd;d-�d<d=�Zd;d>d?�d@dA�ZdBdBdC�dDdE�Z d^dFddFdG�dHdI�Z e �r�d_dJddJdK�dLdM�Z ne Z dNdO� Z dPdQ� Z!dRdS� Z"dTdU� Z#dVdW� Z$dXdY� Z%dZd[� Z&d S )`r& a� Provide an inspection interface for an :class:`.AliasedClass` object. The :class:`.AliasedInsp` object is returned given an :class:`.AliasedClass` using the :func:`_sa.inspect` function:: from sqlalchemy import inspect from sqlalchemy.orm import aliased my_alias = aliased(MyMappedClass) insp = inspect(my_alias) Attributes on :class:`.AliasedInsp` include: * ``entity`` - the :class:`.AliasedClass` represented. * ``mapper`` - the :class:`_orm.Mapper` mapping the underlying class. * ``selectable`` - the :class:`_expression.Alias` construct which ultimately represents an aliased :class:`_schema.Table` or :class:`_expression.Select` construct. * ``name`` - the name of the alias. Also is used as the attribute name when returned in a result tuple from :class:`_query.Query`. * ``with_polymorphic_mappers`` - collection of :class:`_orm.Mapper` objects indicating all those mappers expressed in the select construct for the :class:`.AliasedClass`. * ``polymorphic_on`` - an alternate column or SQL expression which will be used as the "discriminator" for a polymorphic load. .. seealso:: :ref:`inspection_toplevel` )� __weakref__rA r� r r� �_adapt_on_namesr r' �_use_mapper_path� _base_aliasr �persist_selectable� local_tabler, r- �_adapterr6 �__clause_element__�_memoized_valuesZ_all_column_expressions�_nest_adaptersr� rG rH r6 r r r' z Mapper[_O]r� rH r rL zSequence[Mapper[Any]]zSequence[AliasedInsp[Any]]r- z weakref.ref[AliasedClass[_O]]rA z!Union[Type[_O], AliasedClass[_O]]r+ r r r r r rz ) r � inspectedr r� r r' rI rH r r r) c s0 |j } |j} t�|�| _| | _| | _ | _| _|| _|| _ t�|pF| �| _ || _ | | _ | | _ |r�d| _|| _g | _| jD ]@}|| urzt|j|| � |d�}t| j |jj|� | j�|j� qznd| _| g| _ttj| || j� d� fdd�| jD �dd�| _| �r t |t ��sJ �|j� | j�| _� | _ | | _ d S )NT)r r r Fc s h | ]}� s|j �qS r� )r )r� r� �r r� r� � <setcomp>� s �z'AliasedInsp.__init__.<locals>.<setcomp>)r r� r r r r )!r r� r? r@ rA r rJ rK r� r' rI rH r rO r, r r- r r� r/ r� r� r( r r� r� Z_equivalent_columnsrL r� r& �wraprG r6 )r� r rP r r� r r' rI rH r r r) r r� Zpolyr0 r� rQ r� r � s\ � � ��zAliasedInsp.__init__NFz"Union[_EntityType[_O], FromClause]r z#Union[AliasedClass[_O], FromClause])�elementr� r� r r r~ c C sT t |t�r>|rt�d��|r*|j||d�S tjtj||d�S nt |||||d�S d S )Nz+adapt_on_names only applies to ORM elementsr! �r )r� r r� r ) r� rH r� r� r� r< r� r? ZAnonymizedFromClauseRoler )r{ rT r� r� r r r� r� r� �_alias_factory� s" ���zAliasedInsp._alias_factoryzUnion[Type[_O], Mapper[_O]]z/Union[Literal['*'], Iterable[_EntityType[Any]]]z'Union[Literal[False, None], FromClause]) �base�classesr r r' �aliased� innerjoinr r� rH r~ c C sl t |�} |dvr |r t�d��| j|||d�\} }|s:|rR|d usFJ �|j|d�}t||| | ||| | d�S )Nr� z[the 'flat' and 'selectable' arguments cannot be passed simultaneously to with_polymorphic()�rZ rU )r� r r r r r )r r� r� �_with_polymorphic_argsr% r ) r{ rW rX r r r' rY rZ r r� rH �primary_mapper�mappersr� r� r� �_with_polymorphic_factory s* �� �z%AliasedInsp._with_polymorphic_factoryrC c C s* | � � }|d u r&t�| �}t�|�| _ |S r )rA r r. r? r@ )r� r0 r� r� r� r 7 s zAliasedInsp.entityTc C s" | j �| j| | d���d| d��S )N)r � parententity�entity_namespace�orm�Zcompile_state_plugin�plugin_subject)r � _annotater� �_set_propagate_attrsr� r� r� r� �#_memoized_method___clause_element__H s ���z/AliasedInsp._memoized_method___clause_element__c C s | j S r )r r� r� r� r� ra S s z AliasedInsp.entity_namespace�Type[_O]c C s | j jS )zUReturn the mapped class ultimately represented by this :class:`.AliasedInsp`.)r� r� r� r� r� r� r� W s zAliasedInsp.class_rX c C s | j r| jjS t�| �S d S r )rH r� �_path_registryr4 Z per_mapperr� r� r� r� ri ] s zAliasedInsp._path_registryzDict[str, Any]c C s4 | j | j| j| j| j| j| j| �� | j| j | j d� S )N) r r� r� r� r r r r r r r) ) r r� r r� rG r r' rI rH r rO r� r� r� r� � __getstate__d s �zAliasedInsp.__getstate__�None)r� r~ c C sN | � |d |d |d |d |d |d |d |d |d |d |d � d S ) Nr r� r� r� r r r r r r r) )r )r� r� r� r� r� � __setstate__s s �zAliasedInsp.__setstate__r* )�otherr~ c C s� |j }| j |u sJ �t�dd� | jD ��}dd� |jD �}||krF|S |�|�}|j|d |j d�\}}|jdd�}t||||j |j |jd�j S ) Nc s s | ] }|j V qd S r �r� �r� �mpr� r� r� � <genexpr>� s z*AliasedInsp._merge_with.<locals>.<genexpr>c S s h | ] }|j �qS r� rn ro r� r� r� rR � r� z*AliasedInsp._merge_with.<locals>.<setcomp>r[ TrU )r r r r ) r� r9 Zto_setr �unionr\ r r% r r' rH r( )r� rm r] Z our_classesZ new_classesrX r^ r r� r� r� � _merge_with� s* � � �zAliasedInsp._merge_withrT )�exprr� r~ c C sD t |t�sJ �| | jd�}|r&||d< | j�|��|��d| d��S )N)r` r � proxy_keyrb rc )r� rF r� rL �traversere rf )r� rt r� �dr� r� r� �_adapt_element� s � ���zAliasedInsp._adapt_elementr] )r� r� r~ c C s d S r r� )r� r� r� r� r� r� �_orm_adapt_element� s z AliasedInsp._orm_adapt_elementc C sX | j }||v r0|| ju r | S t| j|jj�jS n$|�| j�r@| S dsTJ d|| f ��d S )NFz"mapper %s doesn't correspond to %s)r r� r7 r r� r� r( r )r� r� Z self_polyr� r� r� �_entity_for_mapper� s � z AliasedInsp._entity_for_mapperc s. � j j\}}� j�|�� fdd�|�� D �fS )Nc s i | ]\}}� j �|�|�qS r� )rL rv )r� r� �paramr� r� r� � <dictcomp>� s �z:AliasedInsp._memoized_attr__get_clause.<locals>.<dictcomp>)r� Z _get_clauserL rv r� )r� �onclauseZ replacemapr� r� r� �_memoized_attr__get_clause� s ��z&AliasedInsp._memoized_attr__get_clausec C s i S r r� r� r� r� r� � _memoized_attr__memoized_values� s z+AliasedInsp._memoized_attr__memoized_valuesc sD � j r � j�dd� � jD ��}n � j�� }� fdd�|D �}t|�S )Nc S s g | ] }|j �qS r� )r� )r� r0 r� r� r� r� � r� zFAliasedInsp._memoized_attr__all_column_expressions.<locals>.<listcomp>c s g | ]\}}|� � |�f�qS r� )rx )r� r� r� r� r� r� r� � s )r, r� Z_columns_plus_keysr- rC )r� Zcols_plus_keysr� r� r� �&_memoized_attr__all_column_expressions� s � �z2AliasedInsp._memoized_attr__all_column_expressionsc O s4 || j v r| j | S ||i |�� | j |< }|S d S r )rN )r� r� Z callable_�args�kwr� r� r� r� �_memo� s zAliasedInsp._memoc C s< | j r"dd�dd� | j D �� }nd}dt| �| jj|f S )Nz(%s)r� c s s | ]}|j jV qd S r )r� r� ro r� r� r� rq � s z'AliasedInsp.__repr__.<locals>.<genexpr>r� z<AliasedInsp at 0x%x; %s%s>)r r� rD r� r� )r� Z with_polyr� r� r� r� � s � �zAliasedInsp.__repr__c s> � j r,d� jjd�� fdd�� jD ��f S d� jjf S d S )Nzwith_polymorphic(%s, [%s])r� c 3 s | ]}|� j ur|jjV qd S r )r� r� r� ro r� r� r� rq s �z&AliasedInsp.__str__.<locals>.<genexpr>z aliased(%s))r, r6 r� r� r r� r� r� r� rE � s �� zAliasedInsp.__str__)NNFF)FFNFFFNF)N)N)'r� r� r� r� r� r@ �ExtendedInternalTraversalZ dp_string� dp_booleanZdp_inspectable�dp_clauseelement�InternalTraversalZdp_has_cache_key_listZ_cache_key_traversalr� r r� rV r_ �propertyr r rg ra r� ri rj rl rs rx r ry rz r~ r r� r� r� rE r� r� r� r� r& @ s| & � � "L � �&' � � r& c @ s. e Zd ZdZdZdd� Ze�d�dd� �ZdS ) �_WrapUserEntitya A wrapper used within the loader_criteria lambda caller so that we can bypass declared_attr descriptors on unmapped mixins, which normally emit a warning for such use. might also be useful for other per-lambda instrumentations should the need arise. ��subjectc C s || _ d S r r� )r� r� r� r� r� r s z_WrapUserEntity.__init__zsqlalchemy.orm.decl_apic C sP t jjj}t�| d�}||jv rBt|j| |j�rB|j| � |�S t ||�S d S )Nr� ) r9 Z preloadedrb �decl_api�object�__getattribute__r4 r� Z declared_attr�fgetr7 )r� r� r� r� r� r� r� r� s �z _WrapUserEntity.__getattribute__N) r� r� r� r� r� r r9 Zpreload_moduler� r� r� r� r� r� s r� c @ s e Zd ZU dZdZdejjfdejjfdej j fdej j fdej j fgZ de d< d e d< d e d< d e d < d e d< d e d< d e d< d3ddd d d d d�dd�Zedd� �Zdd� Zdd�d d �Zd d d �d d!�Zd"d#d$�d%d&�Zd d'd(d)�d*d+�Zd d(d �d,d-�Zd.d(d/�d0d1�Zd2S )4�LoaderCriteriaOptiona Add additional WHERE criteria to the load for all occurrences of a particular entity. :class:`_orm.LoaderCriteriaOption` is invoked using the :func:`_orm.with_loader_criteria` function; see that function for details. .. versionadded:: 1.4 )� root_entityr �deferred_where_criteria�where_criteria�_where_crit_orig�include_aliases�propagate_to_loadersr� r r� r� r� zOptional[Type[Any]]�"Optional[_InternalEntityType[Any]]z9Union[ColumnElement[bool], lambdas.DeferredLambdaElement]rz r� r r� FTz_EntityType[Any]zXUnion[_ColumnExpressionArgument[bool], Callable[[Any], _ColumnExpressionArgument[bool]]])�entity_or_baser� � loader_onlyr� r� �track_closure_variablesc C s� t dt�|d��}|d u r.t d|�| _d | _n d | _|| _|| _t|�r�| jd urZ| j}n|d usfJ �|j}d| _tj |t j t |�ftj |d�d�| _nd| _t�t j |�| _|| _|| _d S )Nr Frx T)r� )Z lambda_args�opts)r r7 r$ r� r r� �callabler� r> ZDeferredLambdaElementr? ZWhereHavingRoler� Z LambdaOptionsr� r< r� r� r� ) r� r� r� r� r� r� r� r Z wrap_entityr� r� r� r P s< � �� �z LoaderCriteriaOption.__init__c C s t ||||d�S )N)r� r� )r� )r{ r r� r� r� r� r� r� � _unreduce� s �z LoaderCriteriaOption._unreducec C s( t j| jr| jjn| j| j| j| jffS r )r� r� r r� r� r� r� r� r� r� r� r� � __reduce__� s ��z LoaderCriteriaOption.__reduce__zIterator[Mapper[Any]]rC c c sz | j r| j jjE d H n^| js"J �t| j�� �}|rv|�d�}tdtj |dd��}|rf|jjE d H q0|� |�� � q0d S )Nr r F)�raiseerr) r r� Zself_and_descendantsr� �list�__subclasses__�popr r7 r$ �extend)r� �stack�subclassr0 r� r� r� � _all_mappers� s �z!LoaderCriteriaOption._all_mappersrV )� compile_stater~ c C s |j j�dd �| u rdS dS )N�for_loader_criteriaFT)Zselect_statementr r �r� r� r� r� r� �_should_include� s ���z$LoaderCriteriaOption._should_includer �ColumnElement[bool])�ext_infor~ c C sF | j r td| j�|j��}n| j}t|t�s0J �tj|d| iddd�S )Nr� r� T)Zdetect_subquery_colsZind_cols_on_fromclause) r� r r� Z_resolve_with_argsr r� rF r� �_deep_annotate)r� r� �critr� r� r� �_resolve_where_criteria� s ��z,LoaderCriteriaOption._resolve_where_criteriazIterable[_MapperEntity]rk )r� �mapper_entitiesr~ c C s | � |� d S r )�process_compile_state)r� r� r� r� r� r� �'process_compile_state_replaced_entities� s z<LoaderCriteriaOption.process_compile_state_replaced_entitiesc C s | � |j� dS )z7Apply a modification to a given :class:`.CompileState`.N)�get_global_criteriaZglobal_attributesr� r� r� r� r� � s z*LoaderCriteriaOption.process_compile_statezDict[Any, Any])r r~ c C s, | � � D ] }|�d|fg �}|�| � qd S )NZadditional_entity_criteria)r� � setdefaultr� )r� r rp Z load_criteriar� r� r� r� � s �z(LoaderCriteriaOption.get_global_criteriaN)FFTT)r� r� r� r� r� r@ r� Z dp_plain_objZdp_has_cache_keyr� r� r� Z_traverse_internalsr� r r� r� r� r� r� r� r� r� r� r� r� r� r� r� ) s: � �1 r� c C s | j S r )r( )r; r� r� r� �<lambda>� r� r� rh zOptional[Mapper[_O]])r� r~ c C sF z&t | �}|d u s|js W d S |j}W n tjy< Y d S 0 |S d S r )r) Z is_mappedr� r ZNO_STATE)r� Z class_managerr� r� r� r� � _inspect_mc� s r� c C s t dt| ��}t|�S )Nrh )r rM r� )r� �originr� r� r� �_inspect_generic_alias� s r� c @ s� e Zd ZU dZdZdZdZdZdZe � � Z de d< e j Zde d< dd d d �d d �Zdddd�dd�Zedd�dd��Zedd�dd��Zedd�d d ��Zde d < de d < d d!� Zd"d#� Zed$d%� �Zd&d'� Zd(d)d*d+d,�d-d.�Zd/S )0�Bundlea+ A grouping of SQL expressions that are returned by a :class:`.Query` under one namespace. The :class:`.Bundle` essentially allows nesting of the tuple-based results returned by a column-oriented :class:`_query.Query` object. It also is extensible via simple subclassing, where the primary capability to override is that of how the set of expressions should be returned, allowing post-processing as well as custom return types, without involving ORM identity-mapped classes. .. seealso:: :ref:`bundles` FTrb �_propagate_attrszList[_ColumnsClauseElement]�exprsry z _ColumnExpressionArgument[Any]r )r� r� r� c s` | � _ � _� fdd�|D �}|� _tdd� dd� |D �D ���� � _� _|�d� j�� _dS )a< Construct a new :class:`.Bundle`. e.g.:: bn = Bundle("mybundle", MyClass.x, MyClass.y) for row in session.query(bn).filter(bn.c.x == 5).filter(bn.c.y == 4): print(row.mybundle.x, row.mybundle.y) :param name: name of the bundle. :param \*exprs: columns or SQL expressions comprising the bundle. :param single_entity=False: if True, rows for this :class:`.Bundle` can be returned as a "single entity" outside of any enclosing tuple in the same manner as a mapped entity. c s g | ]}t jtj|� d ��qS ))Zapply_propagate_attrs)r< r� r? �ColumnsClauseRole�r� rt r� r� r� r� 9 s ��z#Bundle.__init__.<locals>.<listcomp>c s s | ]}t |d |j�|fV qdS )r� N)r7 �_label)r� r� r� r� r� rq A s �z"Bundle.__init__.<locals>.<genexpr>c S s g | ]}|j �d |��qS ��bundle�r r �r� �er� r� r� r� C r� � single_entityN) r� r� r� rC Z as_readonlyr� �columnsr� r� )r� r� r� r� Z coerced_exprsr� r� r� r % s � �zBundle.__init__ri zList[BindParameter[Any]]zTuple[Any, ...])ri � bindparamsr~ c s* | j | j| jft� �fdd�| jD �� S )Nc s g | ]}|� � ���qS r� )�_gen_cache_keyr� �ri r� r� r� r� K r� z)Bundle._gen_cache_key.<locals>.<listcomp>)r� r� r� r� r� )r� ri r� r� r� r� r� G s �zBundle._gen_cache_keyzOptional[Mapper[Any]]rC c C s | j d j�dd �}|S )Nr r �r� r r )r� rp r� r� r� r� N s �z Bundle.mapperr� c C s | j d j�dd �}|S )Nr r` r� )r� Zier� r� r� r U s ��z Bundle.entityz6ReadOnlyColumnCollection[str, KeyedColumnElement[Any]]c C s | j S r )r� r� r� r� r� ra \ s zBundle.entity_namespacer� r� c K s | j �| j �}|j�| j� |S r )r� r� r4 r� )r� r� �clonedr� r� r� �_clone s z Bundle._clonec C s^ | | d�}|� | j� | jd j�d| j�}tjdd� | jD �tj dd��� |�� d|d ��S ) N)r� ra r rd c S s g | ]}|j �d |��qS r� r� r� r� r� r� r� � r� z-Bundle.__clause_element__.<locals>.<listcomp>F)Z_literal_as_text_role�grouprb rc ) r� r r� r� r r r= Z ClauseListr? r� re rf )r� r rd r� r� r� rM � s" ���� ���zBundle.__clause_element__c C s | � � jS r )rM �clausesr� r� r� r� r� � s zBundle.clausesc C s | � � }||_|S )z<Provide a copy of this :class:`.Bundle` passing a new label.)r� r� )r� r� r� r� r� r� r� � s z Bundle.labelz Select[Any]z#Sequence[Callable[[Row[Any]], Any]]z Sequence[str]zCallable[[Row[Any]], Any])�query�procs�labelsr~ c s. t |dd� |D ��� ddd�� �fdd� }|S )a Produce the "row processing" function for this :class:`.Bundle`. May be overridden by subclasses to provide custom behaviors when results are fetched. The method is passed the statement object and a set of "row processor" functions at query execution time; these processor functions when given a result row will return the individual attribute value, which can then be adapted into any kind of return data structure. The example below illustrates replacing the usual :class:`.Row` return structure with a straight Python dictionary:: from sqlalchemy.orm import Bundle class DictBundle(Bundle): def create_row_processor(self, query, procs, labels): "Override create_row_processor to return values as dictionaries" def proc(row): return dict(zip(labels, (proc(row) for proc in procs))) return proc A result from the above :class:`_orm.Bundle` will return dictionary values:: bn = DictBundle("mybundle", MyClass.data1, MyClass.data2) for row in session.execute(select(bn)).where(bn.c.data1 == "d1"): print(row.mybundle["data1"], row.mybundle["data2"]) c S s g | ]}d �qS )r� r� )r� �lr� r� r� r� � r� z/Bundle.create_row_processor.<locals>.<listcomp>zRow[Any]r )r� r~ c s �� fdd��D ��S )Nc s g | ] }|� ��qS r� r� )r� �proc�r� r� r� r� � r� z=Bundle.create_row_processor.<locals>.proc.<locals>.<listcomp>r� r� �Z keyed_tupler� r� r� r� � s z)Bundle.create_row_processor.<locals>.procr: )r� r� r� r� r� r� r� r� �create_row_processor� s &zBundle.create_row_processorN)r� r� r� r� r� Zis_clause_elementZ is_mapperr Z is_bundler9 � immutabledictr� r� � EMPTY_SETZ proxy_setr r� r� r� r ra r� rM r� r� r� r� r� r� r� r� � s2 " r� z Bundle[_T]rc )rT �excluder~ c C s t �| ddi|�S )z�Deep copy the given ClauseElement, annotating each element with the "_orm_adapt" flag. Elements within the exclude collection will be cloned but not annotated. � _orm_adaptT)r� r� )rT r� r� r� r� � _orm_annotate� s r� )rT r~ c C s t j| dd�S )z�Remove annotations that link a column to a particular mapping. Note this doesn't affect "remote" and "foreign" annotations passed by the :func:`_orm.foreign` and :func:`_orm.remote` annotators. )r� r` )r� �r� Z_deep_deannotate�rT r� r� r� �_orm_deannotate� s �r� c C s t �| �S r r� r� r� r� r� �_orm_full_deannotate� s r� c @ sp e Zd ZdZejjZdZddddddd d d d �d d �Zdd� Z dddddd d�dd�Z ddddd d�dd�Z dS )�_ORMJoinz/Extend Join to support ORM constructs as input.TNFr� r` zOptional[_OnClauseArgument]rz r� z Tuple[ColumnElement[bool], ...])�left�rightr} �isouter�full� _left_memo� _right_memo�_extra_criteriac C s* t dt�|��} t dt�|��} | j} || _|| _t|tj�rpt rTt|j t j �sTJ �|j � � } |j} ||j7 }n t|t�r�|} | jj} nd } d } | j}| �r&t�| |�r�| }nt|t�s�J �|}| j|| d| d|d�\}}}}}}|d u�r |�rt�|||�}|}nt�||||�}|}n|}|| _t| ��r@|j�dd �}n t | ��sTt | ��rZ| }nd }|d u�rz| j� d|i�| _t |��o�| }t j!�"| |||||� | j#d u�s�J �|�r�| j#tj$|� M _#| �s&t%| dd ��r&| j&j'�r&t d| �} | j&j(}|d u�r&t | ��r| j)�*|�}| j#|@ | _#d S )Nz+Union[FromClause, _InternalEntityType[Any]]T)Zsource_selectableZdest_selectableZsource_polymorphicZof_type_entityZalias_secondaryZextra_criteriar` r� r )+r r7 r$ r r� r� r� r �QueryableAttributer Z comparatorrZ Z ComparatorZ_source_selectabler� r� r0 �parentr� Zclause_is_presentrH Z _create_joinsr8 r� Z_target_adapterrA r r r r rr rz r= �Joinr r} �and_r7 r� �singleZ_single_table_criterionrL rv )r� r� r� r} r� r� r� r� r� Z left_infoZ right_infoZadapt_toZ on_selectable�propZleft_selectableZ adapt_fromZpjZsj�source�destZ secondaryZtarget_adapterr` Zaugment_onclauseZ single_critr� r� r� r � s� �� � �� � �� �� z_ORMJoin.__init__c C sb |}t |tj�r|j}q| j|u s&J �t| j|j| j| j| j|jj d�}t||j|j|j|j d�S )zlSplice a join into the center. Given join(a, b) and join(b, c), return join(a, b).join(c) )r� r� r� )r� r� ) r� r8 r� r� r� r� r} r� r� ri r� )r� rm Zleftmostr� r� r� r� �_splice_into_centerr s& � �z _ORMJoin._splice_into_center)r� r} r� r� r~ c C s t | ||||d�S )N)r� r� �r� )r� r� r} r� r� r� r� r� r� � s z _ORMJoin.join)r� r} r� r~ c C s t | ||d|d�S )NT)r� r� r� )r� r� r} r� r� r� r� � outerjoin� s z_ORMJoin.outerjoin)NFFNNr� )NFF)NF) r� r� r� r� r= r� Z__visit_name__Z inherit_cacher r� r� r� r� r� r� r� r� � s$ � y � �r� r� z"attributes.QueryableAttribute[Any]zOptional[_EntityType[Any]]r� )r� r� � from_entityr~ c C sl t |t�rt�d��nHt |tj�rZ|jr.|j}|j}|du sDt|�sTt�d|� ���|}n|}|j | |d�S )a Create filtering criterion that relates this query's primary entity to the given related instance, using established :func:`_orm.relationship()` configuration. E.g.:: stmt = select(Address).where(with_parent(some_user, User.addresses)) The SQL rendered is the same as that rendered when a lazy loader would fire off from the given parent on that attribute, meaning that the appropriate state is taken from the parent object in Python without the need to render joins to the parent table in the rendered statement. The given property may also make use of :meth:`_orm.PropComparator.of_type` to indicate the left side of the criteria:: a1 = aliased(Address) a2 = aliased(Address) stmt = select(a1, a2).where(with_parent(u1, User.addresses.of_type(a2))) The above use is equivalent to using the :func:`_orm.with_parent.from_entity` argument:: a1 = aliased(Address) a2 = aliased(Address) stmt = select(a1, a2).where( with_parent(u1, User.addresses, from_entity=a2) ) :param instance: An instance which has some :func:`_orm.relationship`. :param property: Class-bound attribute, which indicates what relationship from the instance should be used to reconcile the parent/child relationship. :param from_entity: Entity in which to consider as the left side. This defaults to the "zero" entity of the :class:`_query.Query` itself. .. versionadded:: 1.2 z@with_parent() accepts class-bound mapped attributes, not stringsNz6Expected relationship property for with_parent(), got )r� ) r� ry r� r� r r� Z_of_typer� r Z _with_parent)r� r� r� Zmapper_propertyZprop_tr� r� r� � with_parent� s& 6 � ���r� rz )�object_r~ c C s t �| �}|jS )z�Return True if the given object has a database identity. This typically corresponds to the object being in either the persistent or detached state. .. seealso:: :func:`.was_deleted` )r �instance_state� has_identity�r� r� r� r� r� r� � s r� c C s t �| �}|jS )z�Return True if the given object was deleted within a session flush. This is regardless of whether or not the object is persistent or detached. .. seealso:: :attr:`.InstanceState.was_deleted` )r r� � was_deletedr� r� r� r� r� � s r� r )�givenr r~ c C s^ t |�r(t | �r$|�� | �� u r$dS dS t | �rH| jr@|| jv S || u S t| �sTJ �|�| �S )z�determine if 'given' corresponds to 'entity', in terms of an entity passed to Query that would match the same entity being referred to elsewhere in the query. TF)r rI rH r r Z common_parent�r� r r� r� r� �_entity_corresponds_to s r� c C sR t | �r*t |�o(|j o(| |u p(|| jv S t |�s>| �|j�S |joL| |jv S dS )a� determine if 'given' corresponds to 'entity', in terms of a path of loader options where a mapped attribute is taken to be a member of a parent entity. e.g.:: someoption(A).someoption(A.b) # -> fn(A, A) -> True someoption(A).someoption(C.d) # -> fn(A, C) -> False a1 = aliased(A) someoption(a1).someoption(A.b) # -> fn(a1, A) -> False someoption(a1).someoption(a1.b) # -> fn(a1, a1) -> True wp = with_polymorphic(A, [A1, A2]) someoption(wp).someoption(A1.foo) # -> fn(wp, A1) -> False someoption(wp).someoption(wp.A1.foo) # -> fn(wp, wp.A1) -> True N)r rH r- r r� r r� r� r� r� �$_entity_corresponds_to_use_path_impl% s �� �r� z Mapper[Any])r� r� r~ c C sD | j r || jv p| j�|�S | jr6|| jv p4| �|�S | �|�S dS )zedetermine if 'given' "is a" mapper, in terms of the given would load rows of type 'mapper'. N)r r r� r )r� r� r� r� r� � _entity_isaI s �r� z Query[Any]r )�iterable_query�itemr~ c C s� dd� }t |t�r�t�|�\}}}t |t�rFt |t�rF|| dkrFg S t |t�rX|dk sjt |t�rp|dk rp|� | �||�}|dur�t|�dd|j� S t|�S n(|dkr�|� nt| ||d � �d S dS )zdcalculate __getitem__ in terms of an iterable query object that also has a slice() method. c S s t d��d S )Nz@negative indexes are not accepted by SQL index / slice operators)� IndexErrorr� r� r� r� �_no_negative_indexes^ s �z&_getitem.<locals>._no_negative_indexesr N���r )r� �slicer9 Z decode_slice�intr� �step)r� r� r �start�stopr �resr� r� r� �_getitemX s. �� ��� r rj rx )�raw_annotationr{ �originating_clsr~ c C s6 zt || |j�}W n ty& Y dS 0 t|t�S d S r� )rJ r� � NameErrorrN r )r r{ r � annotatedr� r� r� �_is_mapped_annotation s � r c @ s e Zd ZdS )� _CleanupErrorN)r� r� r� r� r� r� r� r � s r ry )r| r} r~ c sn t �d| �}|s| S zt|�d�|�}W nB tyj } z*td| � d|�d�� d��|�W Y d }~n d }~0 0 |tju r|d}n4z t|t �r�|j }n| W S W n t y� | Y S 0 g }|}|� ||u r�|n|�d�� |�d�}t �d|�}|d u r�|� |� �qq�t �d|d ��sjt � d |d ��sjd � d �� fd d�|d �d�D ��|d < d�|�dt|�d } | S )Nz^([^ \|]+?)\[(.+)\]$r zFor annotation "z%", could not resolve container type "z[". Please ensure this type is imported at the module level outside of TYPE_CHECKING blocks�ClassVarr5 z ^["'].*["']$r z[\[\]]z"' r� c 3 s | ]}d |� � �� d �V qdS )�"N)�strip)r� r �Z stripcharsr� r� rq � s z1_cleanup_mapped_str_annotation.<locals>.<genexpr>r� �[�])r� �matchrK r� r r �typingr � issubclassr r� � TypeErrorr� �searchr� r� �len) r| r} �mmr� �neZ real_symbolr� �innerZg2r� r r� � _cleanup_mapped_str_annotation� sN ��� �� � r z Optional[_AnnotationScanType]r� z@Optional[Tuple[Union[_AnnotationScanType, str], Optional[type]]]) r r{ r} r� �attr_cls�required�is_dataclass_field� expect_mappedr� r~ c C s� | du r2|r.t �d|j� d|� d|j� d���dS zt|| |td�} W n~ ty~ } z t �d| � d��| �W Y d} ~ nPd} ~ 0 ty� } z0|r�d | v r�t �d| � d��| �| } W Y d} ~ n d} ~ 0 0 |r�| dfS t| d �r�t| t ��sV|�rN|s�dS t | d d�} | t j u �rdS t | t��r.t| t��r.dS t jd |j� d|� d �d d��n| dfS t| j�dk�rpt �d��t| jd �| jfS dS )z�given an annotation, figure out if it's ``Mapped[something]`` and if so, return the ``something`` part. Includes error raise scenarios and other options. Nz4Python typing annotation is required for attribute "�.z " when primary argument(s) for "z#" construct are None or not present)rv z Could not interpret annotation zt. Check that it uses names that are correctly imported at the module level. See chained stack trace for more hints.zMapped[� __origin__zType annotation for "a " can't be correctly interpreted for Annotated Declarative Table form. ORM annotations should normally make use of the ``Mapped[]`` generic type, or other ORM-compatible generic type, as a container for the actual type, which indicates the intent that the attribute is mapped. Class variables that are not intended to be mapped by the ORM should use ClassVar[]. To allow Annotated Declarative to disregard legacy annotations which don't use Mapped[] to pass, set "__allow_unmapped__ = True" on the class or a superclass this class.Zzlpr)�coder z)Expected sub-type for Mapped[] annotationr )�orm_excZMappedAnnotationErrorr� rJ r r r r8 rN r r7 r r r� r� r r* r �__args__rL r% ) r r{ r} r� r r! r" r# r� r Zcer r� r� r� r� �_extract_mapped_subtype� sx ����� �� �� � � �� �r) )r� r~ c C s$ t | d�r| �� }nd }t�| |�S )N�_mapper_property_name)r8 r* r9 Zclsname_as_plain_name)r� r� r� r� r� � _mapper_property_as_plain_name^ s r+ )r� T)NN)N)N)TT)�� __future__r r� � functoolsr� r� r r r r r r r r r r r r r r r r r r r r? r� r r r' Z_typingr r r r rW r r r r r r! r" r# r$ r% r& r' r( r) r* r+ r, r- r. Z interfacesr/ r0 r1 r2 r3 Z path_registryr4 r6 r� r7 r8 r9 Z engine.resultr; r< r= r> r? r� r@ Z sql._typingrA Zsql.annotationrB Zsql.baserC Z sql.cache_keyrD rE Z sql.elementsrF rG Zsql.selectablerH Zutil.langhelpersrI Z util.typingrJ Z_de_stringify_annotationrK Z_eval_name_onlyrL rM rN rO rP rQ rR rS rT �contextrU rV r� rW rX r� rY Z relationshipsrZ Zenginer[ r\ r] r^ r_ r` ra rb rc rd re rf rg rh Z sql.visitorsri rj rk � frozensetr� �partialr� Z_de_stringify_partialru r� ry r� r� r� r� �Enumr� Z ColumnAdapterr� r Z Inspectabler Z_self_inspectsr& r� r� Z _inspectsr� r� � GenericAliasr� r� r� r� r� r� r� r� r� r� r� r� r� r r � Exceptionr r r) r+ r� r� r� r� �<module> s� � ��� �IC � S �� X< 5 � K � O 4 � ] 3 �L$'b �"l sqlalchemy/orm/__pycache__/_typing.cpython-39.pyc 0000644 00000012671 15125143220 0016017 0 ustar 00 a ��Jhm � @ s� d dl mZ d dlZd dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlm Z d d lm Z d d lm Z d d lm Z d d l mZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ e �r�ddlm Z ddlm Z ddlm Z ddlm Z ddl m!Z! ddl"m#Z$ dd l%m&Z& dd l%m'Z' dd l%m(Z( dd l%m)Z) dd l*m+Z+ dd!l,m-Z- dd"l.m/Z/ dd#l0m1Z1 dd$l0m2Z2 d d%lm3Z3 d d&l4m5Z5 e d'ed(�Z6e d)ed*d+�Z7e d,e8d(�Z9e �r�e$Z:e d- Z;e e e6 d.f Z<e e e6 d.d/d0f Z=ee>ef Z?ee>ef Z@ee e6 eed1f ee f ZAe ee6 ee6 ejBe6 f ZCe d2ee d(�ZDG d3d4� d4ed5d6�ZEe eEee>ef f ZFG d7d8� d8e�ZGG d9d:� d:e�ZHd;d<d=�d>d?�ZId;d@d=�dAdB�ZJdCdDdE�dFdG�ZKe �rpdCdHdE�dIdJ�ZLdCdKdE�dLdM�ZMdCdNdE�dOdP�ZNdQdRdE�dSdT�ZOdQdRdE�dUdV�ZPdWdXdY�dZd[�ZQd\d]d^�d_d`�ZRd\dad^�dbdc�ZSnPe�Tdd�ZLe�Tde�ZMe�Tdf�ZNe�Tdg�ZOe�Tdh�ZPe�Tdi�ZRe�Tdj�ZQe�Tdk�ZSdS )l� )� annotationsN)�Any)�Dict)�Mapping)�Optional)�Tuple)�Type)� TYPE_CHECKING)�TypeVar)�Union� )�_CoreKnownExecutionOptions)�roles)�DMLStrategyArgument)�SynchronizeSessionArgument)�_HasClauseElement)� ColumnElement)�Protocol)� TypeGuard� )� AttributeImpl)�CollectionAttributeImpl)�HasCollectionAdapter)�QueryableAttribute)� PassiveFlag)�registry)�InspectionAttr)�MapperProperty)� ORMOption)�UserDefinedOption)�Mapper)�RelationshipProperty)� InstanceState)� AliasedClass)� AliasedInsp)�_CE)�ExecutableOption�_T)�bound�_T_coT)r( � covariant�_O)� Mapper[_T]�AliasedInsp[_T]zAliasedClass[_T]r, r- .� _ORMCOLEXPRc @ sF e Zd ZU ded< ded< ded< ded< ded< ded < ded < d S ) �_OrmKnownExecutionOptions�boolZpopulate_existingZ autoflushr Zsynchronize_sessionr Z dml_strategyZis_delete_usingZis_update_fromZ render_nullsN)�__name__� __module__� __qualname__�__annotations__� r5 r5 �K/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/_typing.pyr/ Y s r/ F)�totalc @ s$ e Zd ZdZddddd�dd�ZdS ) �_ORMAdapterProtoz�protocol for the :class:`.AliasedInsp._orm_adapt_element` method which is a synonym for :class:`.AliasedInsp._adapt_element`. Nr% z Optional[str])�obj�key�returnc C s d S �Nr5 )�selfr9 r: r5 r5 r6 �__call__o � z_ORMAdapterProto.__call__)N)r1 r2 r3 �__doc__r> r5 r5 r5 r6 r8 h s r8 c @ s e Zd Zdddd�dd�ZdS )�_LoaderCallablezInstanceState[Any]r r )�state�passiver; c C s d S r< r5 )r= rB rC r5 r5 r6 r> s s z_LoaderCallable.__call__N)r1 r2 r3 r> r5 r5 r5 r6 rA r s rA r& zTypeGuard[ORMOption])�optr; c C s | j S r< )�_is_core�rD r5 r5 r6 � is_orm_optionx s rG z TypeGuard[UserDefinedOption]c C s | j o | jS r< )rE Z_is_user_definedrF r5 r5 r6 �is_user_defined_option~ s rH r r0 )r9 r; c C s t | d�pt | d�S )NZ__composite_values__Z__dataclass_fields__)�hasattr�r9 r5 r5 r6 �is_composite_class� s �rK z TypeGuard[MapperProperty[Any]]c C s d S r< r5 rJ r5 r5 r6 �insp_is_mapper_property� s rL zTypeGuard[Mapper[Any]]c C s d S r< r5 rJ r5 r5 r6 �insp_is_mapper� r? rM zTypeGuard[AliasedInsp[Any]]c C s d S r< r5 rJ r5 r5 r6 �insp_is_aliased_class� r? rN r z"TypeGuard[QueryableAttribute[Any]]c C s d S r< r5 rJ r5 r5 r6 �insp_is_attribute� s rO c C s d S r< r5 rJ r5 r5 r6 �attr_is_internal_proxy� s rP zMapperProperty[Any]z$TypeGuard[RelationshipProperty[Any]])�propr; c C s d S r< r5 )rQ r5 r5 r6 �prop_is_relationship� s rR r z"TypeGuard[CollectionAttributeImpl])�implr; c C s d S r< r5 �rS r5 r5 r6 �is_collection_impl� s rU z TypeGuard[HasCollectionAdapter]c C s d S r< r5 rT r5 r5 r6 �is_has_collection_adapter� s rV Z is_propertyZ is_mapperZis_aliased_classZ is_attributeZ_is_internal_proxyZ collectionZ_is_relationshipZ_is_has_collection_adapter)U� __future__r �operator�typingr r r r r r r r r Zengine.interfacesr Zsqlr Zsql._orm_typesr r Z sql._typingr Z sql.elementsr Z util.typingr r � attributesr r r r �baser Zdecl_apir Z_registry_typeZ interfacesr r r r Zmapperr Z relationshipsr! rB r" �utilr# r$ r% Zsql.baser& r' r) �objectr+ Z _RegistryTypeZ_InternalEntityTypeZ_ExternalEntityTypeZ _EntityType�strZ _ClassDictZ _InstanceDictZ_IdentityKeyTypeZExpressionElementRoleZ_ORMColumnExprArgumentr. r/ ZOrmExecuteOptionsParameterr8 rA rG rH rK rL rM rN rO rP rR rU rV � attrgetterr5 r5 r5 r6 �<module> s� � �� � � sqlalchemy/orm/__pycache__/attributes.cpython-39.pyc 0000644 00000202631 15125143220 0016531 0 ustar 00 a ��Jhvi � @ s� d Z ddlmZ ddlZddlZddlmZ ddlmZ ddlmZ ddlm Z ddlm Z dd lm Z dd lm Z dd lm Z dd lmZ dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z ddl m Z ddl m Z ddl m Z dd l m!Z! dd l m"Z" dd l m#Z# dd l m$Z$ dd l m%Z% dd!l m&Z& dd"l m'Z' dd#l m(Z( dd$l m)Z) dd%l m*Z* dd&l m+Z+ dd'l m,Z, dd(l m-Z- dd)l m.Z. dd*l m/Z/ dd+l m0Z0 dd,l m1Z1 dd-l m2Z2 dd.l m3Z3 dd/l m4Z4 dd0l m5Z5 dd1l m6Z6 dd2l m7Z7 dd3l m8Z8 dd4l m9Z9 dd5l m:Z: dd6l m;Z; dd7l m<Z< dd8l m=Z= dd9l m>Z> dd:l m?Z? dd;l m@Z@ d<d=lmAZA d<dlmZ d<d>lmBZB d<d?lmCZC d<d@lAmDZD d<dAlAmEZE d<dBlFm ZG d<dClFmHZH d<dDlFmIZI d<dElFmJZJ d<dFlFmKZK d<dGlLmMZM d<dHlNmOZO d<dIlNmPZP d<dJlQmRZR d<dKlQmSZS d<dLlQmTZT e�r�ddMlmUZU ddNlmVZV ddOlmWZW ddPlmXZX ddQlmYZY ddRlmZZZ ddSlm[Z[ ddTlm\Z\ ddUlm]Z] ddVl^m_Z_ ddWl`maZa ddXlCmbZb ddYlcmdZd d<dZlemfZf d<d[lgmhZh d<d\lgmiZi d<d]lgmjZj d<d^lgmkZk d<d_llmmZm d<d`lnmoZo d<dalnmpZp d<dblqmrZr d<dclsmtZt edd�Zuedeedfdg�Zveeedh eew f Zxew� ZyeBjzG didj� dje ev e?ev ej{ej|ev eJj}eJj~eGjeHj�eCj�eE� �Z�dkdldmdndodp�dqdr�Z�G dsdt� dte�ev �Z�ej�dfdu�G dvdw� dweM��Z�dodxdy�dzd{�Z�eC��d|�Z�eC��d}�Z�eC��d~�Z�eC��d�Z�eC��d��Z�G d�d�� d��Z�e�Z�e�Z�G d�d�� d��Z�G d�d�� d�e��Z�G d�d�� d�e��Z�G d�d�� d��Z�e�rd�d�d��d�d��Z�n e��d��Z�G d�d�� d�e�e��Z�d�dkd�d�d��d�d��Z�eC��d��Z�e�e�e8�e�e1�g�Z�G d�d�� d�e �Z�e�d�d�d��Z�e9fd�dkd�d�d��d�d��Z�e9fdhdkd�d�d��d�d��Z�d�dld�dkd�d�d��d�d��Z�dd��dldkd�dmd�dod�d��d�d��Z�d�dldkd�d�d�d�d�dod�d�� d�d��Z�dd��d�dkd�d�d�d�d��d�d��Z�d�dkd�d��d�d��Z�d�dkd�d��d�d��Z�dhd�dkd�dd�dĄZ�d�dƄ Z�d�d�dkdod�d�dȜd�dʄZ�d�dkdod˜d�d̈́Z�d�dkd�d˜d�dτZ�d�dkd�d˜d�dфZ�d�d�dҜd�dԄZ�dS )�z�Defines instrumentation for class attributes and their interaction with instances. This module is usually not directly visible to user applications, but defines a large part of the ORM's interactivity. � )� annotationsN)�Any)�Callable)�cast)�ClassVar)�Dict)�Iterable)�List)� NamedTuple)�Optional)�overload)�Sequence)�Tuple)�Type)� TYPE_CHECKING)�TypeVar)�Union� )� collections)�exc)� interfaces)�insp_is_aliased_class)�_DeclarativeMapped)� ATTR_EMPTY)� ATTR_WAS_SET)� CALLABLES_OK)�DEFERRED_HISTORY_LOAD)�INCLUDE_PENDING_MUTATIONS)�INIT_OK)� instance_dict��instance_state)� instance_str)�LOAD_AGAINST_COMMITTED)�LoaderCallableStatus)�manager_of_class)�Mapped)� NEVER_SET)� NO_AUTOFLUSH)� NO_CHANGE)�NO_KEY)�NO_RAISE)�NO_VALUE)�NON_PERSISTENT_OK)�opt_manager_of_class)�PASSIVE_CLASS_MISMATCH)�PASSIVE_NO_FETCH)�PASSIVE_NO_FETCH_RELATED)�PASSIVE_NO_INITIALIZE)�PASSIVE_NO_RESULT)� PASSIVE_OFF)�PASSIVE_ONLY_PERSISTENT)�PASSIVE_RETURN_NO_VALUE)� PassiveFlag)�RELATED_OBJECT_OK)�SQL_OK)�SQLORMExpression)� state_str� )�event)� inspection)�util)� dispatcher)� EventTarget)�base)� cache_key)� coercions)�roles)�visitors)� HasCacheKey)�_TraverseInternalsType)�InternalTraversal)�Literal)�Self)� TypeGuard)� _EntityType)�_ExternalEntityType)� _InstanceDict)�_InternalEntityType)�_LoaderCallable)�_O)�_AdaptedCollectionProtocol)�CollectionAdapter)�MapperProperty)�RelationshipProperty)� InstanceState)� AliasedInsp)�WriteOnlyAttributeImpl)� _Dispatch)�_ColumnExpressionArgument)�_DMLColumnArgument)� _InfoType)�_PropagateAttrsType)�_AnnotationDict)� ColumnElement)�Label)� OperatorType)� FromClause�_T�_T_coT)�bound� covariant�InstanceState[Any]c @ s. e Zd ZU dZdZdZded< ded< ded < d ed < d ed < ded< ded< ded< ded< dZdpdddddddd �d d �Zd e j j fd e j j fde j j fde j jfgZd d!�d"d#�Zed$d!�d%d&��Zefd d'd(d)�d*d+�Zed,d!�d-d.��Zd ed/< d0ed1< d2d!�d3d4�Zd5d!�d6d7�Zed d!�d8d9��Zed:d!�d;d<��Zd0d!�d=d>�Zed?d!�d@dA��Zd dBdC�dDdE�Z dFdGdH�dIdJ�Z dKdLdM�dNdO�Z dPdQdR�dSdT�Z d dLdU�dVdW�Z ddXdY�dZd[�Z!d\d d d]d^�d_d`�Z"d\d d d]d^�dadb�Z#dqddd$d$de�dfdg�Z$dd dh�didj�Z%dd!�dkdl�Z&dmd!�dndo�Z'dS )r�QueryableAttributea� Base class for :term:`descriptor` objects that intercept attribute events on behalf of a :class:`.MapperProperty` object. The actual :class:`.MapperProperty` is accessible via the :attr:`.QueryableAttribute.property` attribute. .. seealso:: :class:`.InstrumentedAttribute` :class:`.MapperProperty` :attr:`_orm.Mapper.all_orm_descriptors` :attr:`_orm.Mapper.attrs` ) �class_�key�impl� comparator�property�parent� expression�_of_type�_extra_criteriaZ_slots_dispatchZ_propagate_attrs�_docTz%dispatcher[QueryableAttribute[_T_co]]�dispatch�_ExternalEntityType[Any]rj �strrk �_InternalEntityType[Any]� parententity� AttributeImplrl z interfaces.PropComparator[_T_co]rm z"Optional[_InternalEntityType[Any]]rq z Tuple[ColumnElement[bool], ...]rr � Optional[str]rs Zorm_instrumented_attributeN� �_ExternalEntityType[_O]�_InternalEntityType[_O]zOptional[AttributeImpl])rj rk rx rm rl �of_type�extra_criteriac C s� || _ || _| | _| _|| _|d us*J �|| _|| _|| _d | _t |�}|r�|j D ]2} || v rT| j � | | j � | | j j rTd| j _ qTd S �NT)rj rk � _parententityro rl rm rq rr rs r. Z_basesrt �_update�_active_history) �selfrj rk rx rm rl r~ r �managerrB r{ r{ �N/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/attributes.py�__init__� s zQueryableAttribute.__init__r� r ��returnc C s t | j| jjj| j| jjffS �N)� _queryable_attribute_unreducerk r� Zmapperrj �entity�r� r{ r{ r� � __reduce__� s ��z QueryableAttribute.__reduce__�boolc C s | j jS r� )rl � uses_objectsr� r{ r{ r� �_impl_uses_objects� s z%QueryableAttribute._impl_uses_objectsr7 �History)�instance�passiver� c C s | j �t|�t|�|�S r� )rl � get_historyr! r )r� r� r� r{ r{ r� r� s �z QueryableAttribute.get_historyr] c C s | j jS )a� Return the 'info' dictionary for the underlying SQL element. The behavior here is as follows: * If the attribute is a column-mapped property, i.e. :class:`.ColumnProperty`, which is mapped directly to a schema-level :class:`_schema.Column` object, this attribute will return the :attr:`.SchemaItem.info` dictionary associated with the core-level :class:`_schema.Column` object. * If the attribute is a :class:`.ColumnProperty` but is mapped to any other kind of SQL expression other than a :class:`_schema.Column`, the attribute will refer to the :attr:`.MapperProperty.info` dictionary associated directly with the :class:`.ColumnProperty`, assuming the SQL expression itself does not have its own ``.info`` attribute (which should be the case, unless a user-defined SQL construct has defined one). * If the attribute refers to any other kind of :class:`.MapperProperty`, including :class:`.Relationship`, the attribute will refer to the :attr:`.MapperProperty.info` dictionary associated with that :class:`.MapperProperty`. * To access the :attr:`.MapperProperty.info` dictionary of the :class:`.MapperProperty` unconditionally, including for a :class:`.ColumnProperty` that's associated directly with a :class:`_schema.Column`, the attribute can be referred to using :attr:`.QueryableAttribute.property` attribute, as ``MyClass.someattribute.property.info``. .. seealso:: :attr:`.SchemaItem.info` :attr:`.MapperProperty.info` )rm �infor� r{ r{ r� r� s (zQueryableAttribute.inforo zColumnElement[_T_co]rp zColumnElement[_T]c C s� | j }t|t�sJ �| jtu r(d|i}n| j| j|d�}| j�� }z trVt|t �sVJ �|j }W n8 t y� } z t � d| |f �|�W Y d }~nd }~0 0 ||�S d S )N�entity_namespace)� proxy_keyZ proxy_ownerr� z}When interpreting attribute "%s" as a SQL expression, expected __clause_element__() to return a ClauseElement object, got: %r)�_entity_namespace� isinstancerG rk �_UNKNOWN_ATTR_KEYr� rm �__clause_element__r r` Z _annotate�AttributeErrorr ZInvalidRequestError)r� r� r Zce�annoZaer{ r{ r� �_memoized_attr_expressionG s, � ���z,QueryableAttribute._memoized_attr_expressionr^ c C s t �d| jd��S )NZorm)Zcompile_state_pluginZplugin_subject)r? Z immutabledictZ _parentmapperr� r{ r{ r� � _memoized_attr__propagate_attrsi s ��z2QueryableAttribute._memoized_attr__propagate_attrsc C s | j S r� )r� r� r{ r{ r� r� t s z$QueryableAttribute._entity_namespacer_ c C s | � � jS r� )r� � _annotationsr� r{ r{ r� r� x s z QueryableAttribute._annotationsc C s | j S r� )rp r� r{ r{ r� r� | s z%QueryableAttribute.__clause_element__zList[FromClause]c C s | j jS r� )rp � _from_objectsr� r{ r{ r� r� s z QueryableAttribute._from_objectsz(Sequence[Tuple[_DMLColumnArgument, Any]]��valuer� c C s | j �|�S )z'Return setter tuples for a bulk UPDATE.)rm �_bulk_update_tuples�r� r� r{ r{ r� r� � s z&QueryableAttribute._bulk_update_tupleszAliasedInsp[Any]rK )�adapt_to_entityr� c C s, | j r J �| j|j| j| j| j�|�|d�S )N)rl rm rx )rq � __class__r� rk rl rm r� �r� r� r{ r{ r� r� � s �z"QueryableAttribute.adapt_to_entityz_EntityType[_T]zQueryableAttribute[_T])r� r� c C s. t | j| j| j| j| j�|�t�|�| j d�S �N�rl rm r~ r ) ri rj rk r� rl rm r~ r> �inspectrr )r� r� r{ r{ r� r~ � s �zQueryableAttribute.of_typez _ColumnExpressionArgument[bool]zQueryableAttribute[bool])�clausesr� c G s\ t rt| jtj�sJ �tdd� t�|�D ��}t| j | j | j | j | jj |� | j| j| d�S )Nc s s | ]}t �tj|�V qd S r� )rD �expectrE ZWhereHavingRole)�.0Zclauser{ r{ r� � <genexpr>� s �z*QueryableAttribute.and_.<locals>.<genexpr>r� )r r� rm rV Z Comparator�tupler? Zcoerce_generator_argri rj rk r� rl �and_rq rr )r� r� �exprsr{ r{ r� r� � s � �zQueryableAttribute.and_)�kwr� c K s$ t | j| j| j| j| j| j| jd�S r� )ri rj rk r� rl rm rq rr �r� r� r{ r{ r� �_clone� s �zQueryableAttribute._clonez Label[_T_co])�namer� c C s | � � �|�S r� )r� �label)r� r� r{ r{ r� r� � s zQueryableAttribute.labelrb zColumnElement[Any])�op�other�kwargsr� c O s || j g|�R i |��S r� �rm �r� r� r� r� r{ r{ r� �operate� s zQueryableAttribute.operatec K s ||| j fi |��S r� r� r� r{ r{ r� �reverse_operate� s z"QueryableAttribute.reverse_operateFrh ��state� optimisticr� c C s | j j||d�duS )N)r� F�rl � hasparent)r� r� r� r{ r{ r� r� � s z QueryableAttribute.hasparent)rk r� c C s� zt j�| |�W S ty" Y n0 zt| j|�W S tyz } z0tdt| �jt| j�j| |f �|�W Y d }~n d }~0 0 d S )N�FNeither %r object nor %r object associated with %s has an attribute %r�r? � MemoizedSlots� __getattr__r� �getattrrm �type�__name__)r� rk �errr{ r{ r� r� � s$ ��� �z QueryableAttribute.__getattr__c C s | j j� d| j� �S �N�.�rj r� rk r� r{ r{ r� �__str__� s zQueryableAttribute.__str__z Optional[MapperProperty[Any]]c C s | j jS r� �rm rn r� r{ r{ r� �_memoized_attr_property� s z*QueryableAttribute._memoized_attr_property)NNr{ )F)(r� � __module__� __qualname__�__doc__� __slots__Z is_attribute�__annotations__Z__visit_name__r� rF �ExtendedInternalTraversal� dp_string�dp_multirI Zdp_clauseelement_list�_cache_key_traversalr� rn r� r4 r� r� r� r� r� r� r� r� r� r� r~ r� r� r� r� r� r� r� r� r� r{ r{ r{ r� ri � sj � ' � �) " �ri rv zType[_O]r} ru r )rk � mapped_classrx r� r� c C s$ t |�r|�| ||�S t|| �S d S r� )r Z_get_from_serializedr� )rk r� rx r� r{ r{ r� r� � s r� c s� e Zd ZdZdZdZejdd�dd��Zejddd �d d��Zej dd�� fd d� �Zd d dd�dd�Z d dd�dd�Z e dd dd�dd��Z e d d dd�dd��Z dd dd�d d�Z � ZS ) �InstrumentedAttributez�Class bound instrumented attribute which adds basic :term:`descriptor` methods. See :class:`.QueryableAttribute` for a description of most features. r{ Trz r� c C s | j S r� �rs r� r{ r{ r� r� s z InstrumentedAttribute.__doc__�Noner� c C s || _ d S r� r� r� r{ r{ r� r� s c s t � jS r� )�superr� )�cls�r� r{ r� r� s �objectr )r� r� r� c C s | j �t|�t|�|d � d S r� )rl �setr! r )r� r� r� r{ r{ r� �__set__ s �z InstrumentedAttribute.__set__�r� r� c C s | j �t|�t|�� d S r� )rl �deleter! r )r� r� r{ r{ r� � __delete__ s z InstrumentedAttribute.__delete__z InstrumentedAttribute[_T_co])r� �ownerr� c C s d S r� r{ �r� r� r� r{ r{ r� �__get__ s z InstrumentedAttribute.__get__re c C s d S r� r{ r� r{ r{ r� r� % s �Optional[object]z*Union[InstrumentedAttribute[_T_co], _T_co]c C s� |d u r | S t |�}| jjr0| j|v r0|| j S z t|�}W n0 tyl } zt�|�|�W Y d }~n d }~0 0 | j�||�S d S r� ) r rl �supports_populationrk r! r� �orm_excZUnmappedInstanceError�get)r� r� r� �dict_r� r� r{ r{ r� r� ( s ")r� r� r� r� r� Z inherit_cacher? Zrw_hybridproperty�setterZ classlevelr� r� r r� � __classcell__r{ r{ r� r� r� � s r� )�frozenc @ sR e Zd ZU dejfgZded< dZded< dZded< dZ ded < e d d � �Z d S ) �AdHocHasEntityNamespacer� z ClassVar[_TraverseInternalsType]�_traverse_internals)r� rw FzClassVar[bool]� is_mapper�is_aliased_classc C s | j jS r� )r� r� r� r{ r{ r� r� E s z(AdHocHasEntityNamespace.entity_namespaceN) r� r� r� rI Zdp_has_cache_keyr� r� r� r� r� rn r� r{ r{ r{ r� r� 9 s � r� z&Callable[..., QueryableAttribute[Any]])� descriptorr� c sB G � fdd�dt t �}t� �jd |_tj|t� �d� d� |S )z�Create an QueryableAttribute / user descriptor hybrid. Returns a new QueryableAttribute type that delegates descriptor behavior and getattr() to the given descriptor. c s� e Zd ZdZdZd!dd�Zedd� �Zedd � �Zd Z d e j j fd e j j fgZed d� �Zedd� �Zedd� �Zejdd� �Zdd� Zdd� Zdd� Zdd �d d �Z� fd d �ZdS )"z'create_proxied_attribute.<locals>.Proxyz�Presents the :class:`.QueryableAttribute` interface as a proxy on top of a Python descriptor / :class:`.PropComparator` combination. r{ Nc S s4 || _ || _|| _|| _|| _|| _| | _| _d S r� )rj rk r� �original_property� _comparator�_adapt_to_entityrs r� )r� rj rk r� rm r� �docr� r{ r{ r� r� c s z0create_proxied_attribute.<locals>.Proxy.__init__c S s t j| jdd�S �NF)Zraiseerr�r> r� rj r� r{ r{ r� r� u s z5create_proxied_attribute.<locals>.Proxy._parententityc S s t j| jdd�S r� r� r� r{ r{ r� ro y s z.create_proxied_attribute.<locals>.Proxy.parentTrk r� c S s | j d uot| j| j�jjS r� )r� r� rj rk rl r� r� r{ r{ r� r� � s �z:create_proxied_attribute.<locals>.Proxy._impl_uses_objectsc S s" t | jd�r| jjS t| j�S d S )Nr� )�hasattrr� r� r� r� r{ r{ r� r� � s z9create_proxied_attribute.<locals>.Proxy._entity_namespacec S s | j jS r� r� r� r{ r{ r� rn � s z0create_proxied_attribute.<locals>.Proxy.propertyc S s0 t | j�r| �� | _| jr*| j�| j�| _| jS r� )�callabler� r� r� r� r{ r{ r� rm � s �z2create_proxied_attribute.<locals>.Proxy.comparatorc S s | � |j| j| j| j|�S r� )r� r� rk r� r� r� r{ r{ r� r� � s �z7create_proxied_attribute.<locals>.Proxy.adapt_to_entityc [ s" | j | j| j| j| j| j| jd�S )N)r� r� )r� rj rk r� r� r� r� r� r{ r{ r� r� � s �z.create_proxied_attribute.<locals>.Proxy._clonec S s, | j �||�}|| j u r$|d u r$| S |S d S r� )r� r� )r� r� r� �retvalr{ r{ r� r� � s z/create_proxied_attribute.<locals>.Proxy.__get__rv r� c S s | j j� d| j� �S r� r� r� r{ r{ r� r� � s z/create_proxied_attribute.<locals>.Proxy.__str__c s zt j�| |�W S ty" Y n0 z t� |�W S t�y } z�|dkrTtd�|�z | j}W n> ty� } z&tdt� �j| |f �|�W Y d}~nld}~0 0 zt||�W W Y d}~S t� y� } z.tdt� �jt|�j| |f �|�W Y d}~n d}~0 0 W Y d}~n d}~0 0 dS )zNDelegate __getattr__ to the original descriptor and/or comparator.rm z[Neither %r object nor unconfigured comparator object associated with %s has an attribute %rNr� r� )r� � attributer� rm Zerr2Zerr3�r� r{ r� r� � sB ������ �z3create_proxied_attribute.<locals>.Proxy.__getattr__)NNN)r� r� r� r� rr r� rn r� ro Z_is_internal_proxyrF r� r� r� r� r� r� r? Zmemoized_propertyrm r� r� r� r� r� r{ r r{ r� �ProxyV s6 � � r r� )r� Z from_instance)ri r r� r� r? Z monkeypatch_proxied_specials)r� r r{ r r� �create_proxied_attributeJ s �r ZREMOVE�APPENDZREPLACEZ BULK_REPLACEZMODIFIEDc @ s@ e Zd ZdZdZddd�dd�Zdd � Zed d � �Zd d � Z dS )�AttributeEventTokena� A token propagated throughout the course of a chain of attribute events. Serves as an indicator of the source of the event and also provides a means of controlling propagation across a chain of attribute operations. The :class:`.Event` object is sent as the ``initiator`` argument when dealing with events such as :meth:`.AttributeEvents.append`, :meth:`.AttributeEvents.set`, and :meth:`.AttributeEvents.remove`. The :class:`.Event` object is currently interpreted by the backref event handlers, and is used to control the propagation of operations across two mutually-dependent attributes. .. versionchanged:: 2.0 Changed the name from ``AttributeEvent`` to ``AttributeEventToken``. :attribute impl: The :class:`.AttributeImpl` which is the current event initiator. :attribute op: The symbol :attr:`.OP_APPEND`, :attr:`.OP_REMOVE`, :attr:`.OP_REPLACE`, or :attr:`.OP_BULK_REPLACE`, indicating the source operation. �rl r� � parent_tokenry z util.symbol)�attribute_implr� c C s || _ || _| j j| _d S r� r )r� r r� r{ r{ r� r� s z AttributeEventToken.__init__c C s" t |t�o |j| ju o |j| jkS r� )r� r rl r� )r� r� r{ r{ r� �__eq__ s � �zAttributeEventToken.__eq__c C s | j jS r� )rl rk r� r{ r{ r� rk & s zAttributeEventToken.keyc C s | j �|�S r� r� )r� r� r{ r{ r� r� * s z AttributeEventToken.hasparentN) r� r� r� r� r� r� r rn rk r� r{ r{ r{ r� r � s r c @ s� e Zd ZU dZded< ded< ded< ded< ded< dZd ed < d ed < d ed < dKddddddddddddd� dd�ZdZdd�d d �Zd d � Z d d!� Z e e e �Z dLd"ddd#�d$d%�Z d"d"dd&d'�d(d)�Zefd"d*d+d,d-�d.d/�Zefd"d*d+d0d-�d1d2�Zd"d*dd3�d4d5�Zefd"d*d+dd-�d6d7�Zd"dd+dd8�d9d:�Zefd"d*ddd+d&d;�d<d=�Zefd"d*ddd+d&d;�d>d?�Zefd"d*ddd+d&d;�d@dA�Zd ed dfd"d*ddd+ddd&dB�dCdD�Zd"d*d&d3�dEdF�Zefd"d*d+dd-�dGdH�ZdIdJ� Z d S )Mry z4internal implementation for instrumented attributes.r� � collection� default_accepts_scalar_loaderr� r� �dynamicFr �_replace_token� _remove_token� _append_tokenNTr| rv �Optional[_LoaderCallable]�"_Dispatch[QueryableAttribute[Any]]z Optional[Callable[..., bool]]� Optional[AttributeEventToken]zOptional[bool]r ) rj rk � callable_rt � trackparent�compare_function�active_historyr �load_on_unexpire�send_modified_events�accepts_scalar_loaderr� c K s� || _ || _|| _|| _|| _|p$| | _| | _|du r@tj| _ n|| _ | durV| | _ n| j | _ | � dd�} | | _ |r|d| j_| | _t| t�| _dS )a� Construct an AttributeImpl. :param \class_: associated class :param key: string name of the attribute :param \callable_: optional function which generates a callable based on a parent instance, which produces the "default" values for a scalar or collection attribute when it's first accessed, if not present already. :param trackparent: if True, attempt to track if an instance has a parent attached to it via this attribute. :param compare_function: a function that compares two values which are normally assignable to this attribute. :param active_history: indicates that get_history() should always return the "old" value, even if it means executing a lazy callable upon attribute change. :param parent_token: Usually references the MapperProperty, used as a key for the hasparent() function to identify an "owning" attribute. Allows multiple AttributeImpls to all match a single owner attribute. :param load_on_unexpire: if False, don't include this attribute in a load-on-expired operation, i.e. the "expired_attribute_loader" process. The attribute can still be in the "expired" list and be considered to be "expired". Previously, this flag was called "expire_missing" and is only used by a deferred column attribute. :param send_modified_events: if False, the InstanceState._modified_event method will have no effect; this means the attribute will never show up as changed in a history entry. N�_deferred_historyFT)rj rk r rt r r r �operator�eq�is_equalr r �popr r� r r � OP_MODIFIED�_modified_token)r� rj rk r rt r r r r r r r r� r r{ r{ r� r� A s& ; zAttributeImpl.__init__) rj rk r rt r r r r r r" r r r� c C s | j j� d| j� �S r� r� r� r{ r{ r� r� � s zAttributeImpl.__str__c C s | j jS )z(Backwards compat for impl.active_history�rt r� r� r{ r{ r� �_get_active_history� s z!AttributeImpl._get_active_historyc C s || j _d S r� r# r� r{ r{ r� �_set_active_history� s z!AttributeImpl._set_active_historyrh r� c C s* d}| j sJ |��|j�t| j�|�duS )a4 Return the boolean value of a `hasparent` flag attached to the given state. The `optimistic` flag determines what the default return value should be if no `hasparent` flag can be located. As this function is used to determine if an instance is an *orphan*, instances that were loaded from storage should be assumed to not be orphans, until a True/False value for this flag is set. An instance attribute that is loaded by a callable function will also not have a `hasparent` flag. �6This AttributeImpl is not configured to track parents.F)r �parentsr� �idr )r� r� r� �msgr{ r{ r� r� � s �zAttributeImpl.hasparentr� )r� � parent_stater� r� c C s� d}| j sJ |��t| j�}|r,||j|< n`||jv r�|j| }|dur�|j|jkr�|�� du r~t�dt|�t|�| jf ��dS d|j|< dS )z�Set a boolean flag on the given item corresponding to whether or not it is attached to a parent object via the attribute represented by this ``InstrumentedAttribute``. r& FNz�Removing state %s from parent state %s along attribute '%s', but the parent record has gone stale, can't be sure this is the most recent parent.) r r( r r' rk �objr� ZStaleDataErrorr; )r� r� r* r� r) Zid_Z last_parentr{ r{ r� � sethasparent� s, � � ��� zAttributeImpl.sethasparentrO r7 r� �r� r� r� r� c C s t � �d S r� ��NotImplementedError�r� r� r� r� r{ r{ r� r� � s zAttributeImpl.get_history�_AllPendingTypec C s t � �dS )a� Return a list of tuples of (state, obj) for all objects in this attribute's current state + history. Only applies to object-based attributes. This is an inlining of existing functionality which roughly corresponds to: get_state_history( state, key, passive=PASSIVE_NO_INITIALIZE).sum() Nr. r0 r{ r{ r� �get_all_pending� s z AttributeImpl.get_all_pending�r� r� r� c C s@ | j |vsJ d��d}| jjD ] }||||�}|tur |}q |S )z=Produce an empty value for an uninitialized scalar attribute.�O_default_value should only be invoked for an uninitialized or expired attributeN)rk rt Z init_scalarr )r� r� r� r� �fn�retr{ r{ r� �_default_value s � z AttributeImpl._default_valuec C s� | j |v r|| j S | j }||jvs2|j| tu r�|t@ s>tS | �|||�}|tu s\|tu r`|S |tu r�z || W S ty� } ztd| �|�W Y d}~q�d}~0 0 n|tur�| � |||�S |t @ s�tS | � ||�S dS )z�Retrieve a value from the given object. If a callable is assembled on this object's attribute, and passive is False, the callable will be executed and the resulting value will be set as the new value for this attribute. z=Deferred loader for attribute %r failed to populate correctlyN) rk �committed_stater, r r3 �_fire_loader_callablesr �KeyErrorr �set_committed_valuer r7 )r� r� r� r� rk r� r� r{ r{ r� r� ' s8 � � ���zAttributeImpl.get�r� rk r� r� c C sZ | j r"| jr"||jv r"|�||�S ||jv r@|j| }|||�S | jrR| �||�S tS d S r� )r r �expired_attributesZ _load_expiredZ callablesr r )r� r� rk r� r r{ r{ r� r9 T s ��� z$AttributeImpl._fire_loader_callables�r� r� r� � initiatorr� r� c C s | j |||||d� d S �N�r� �r� �r� r� r� r� r? r� r{ r{ r� �appende s zAttributeImpl.appendc C s | j ||d |||d� d S )N)r� � check_oldrB rC r{ r{ r� �removeo s �zAttributeImpl.removec C s | j ||d |||dd� d S )NT)r� rE r rB rC r{ r{ r� r { s �zAttributeImpl.pop�r� r� r� r? r� rE r r� c C s t � �d S r� r. )r� r� r� r� r? r� rE r r{ r{ r� r� � s zAttributeImpl.setc C s t � �d S r� r. )r� r� r� r{ r{ r� r� � s zAttributeImpl.deletec C s> | j |jv r*|j| j }|tu r$dS |S n| j|||d�S dS )z,return the unchanged value of this attributeNrA )rk r8 r, r� )r� r� r� r� r� r{ r{ r� �get_committed_value� s z!AttributeImpl.get_committed_valuec C s ||| j < |�|| j g� |S )z=set an attribute value on the given instance and 'commit' it.)rk �_commit)r� r� r� r� r{ r{ r� r; � s z!AttributeImpl.set_committed_value)FNFNTTN)F) r� r� r� r� r� �_is_has_collection_adapterr� r� r� r$ r% rn r r� r, r4 r� r2 r2 r7 r� r9 rD rF r r� r� rH r; r{ r{ r{ r� ry 2 sb �&U �/� ��-���� �ry c s� e Zd ZdZdZdZdZdZdZdZ � fdd�Z ddd d �d d �Z e fdd ddd�dd�Z de ddfdd dddddd d�dd�Zddddddd �d d �Zddddd d �d d!�Z� ZS )"�ScalarAttributeImplz8represents a scalar value-holding InstrumentedAttribute.TF)r r r c s4 t � j|i |�� t| t� | _| _t| t�| _d S r� )r� r� r � OP_REPLACEr r � OP_REMOVEr )r� �argr� r� r{ r� r� � s � z ScalarAttributeImpl.__init__rh rO r� r3 c C s� | j jr| �||t�}n|�| jt�}| j jr@| �|||| j� |� || |� |� | jt�}|tu r�|tu r�|j s�| j|j vr�t d| ��d S )N� %s object does not have a value)rt r� r� r6 rk r, rF �fire_remove_eventr �_modified_eventr Zexpiredr= r� �r� r� r� �old�existingr{ r{ r� r� � s ��� �zScalarAttributeImpl.deletezDict[str, Any]r7 r� r- c C sv | j |v r t�| ||| j �S | j |jv r8t�| |t�S |t@ rH|tN }| j|||d�}|tu rdtS t�| ||�S d S r@ ) rk r� �from_scalar_attributer8 r, r r� r3 � HISTORY_BLANK)r� r� r� r� �currentr{ r{ r� r� � s z ScalarAttributeImpl.get_historyNr r r� r� rG c C s\ | j jr| �||t�}n|�| jt�}| j jr@| �|||||�}|�|| |� ||| j< d S r� ) rt r� r� r6 rk r, r� �fire_replace_eventrQ � r� r� r� r� r? r� rE r rS r{ r{ r� r� � s �zScalarAttributeImpl.setrd �r� r� r� �previousr? r� c C s& | j jD ]}|||||p | j�}q|S r� )rt r� r �r� r� r� r� r[ r? r5 r{ r{ r� rX s �z&ScalarAttributeImpl.fire_replace_event�r� r� r� r? r� c C s$ | j jD ]}||||p| j� qd S r� )rt rF r �r� r� r� r� r? r5 r{ r{ r� rP s z%ScalarAttributeImpl.fire_remove_event)r� r� r� r� r r� r� r r r� r� r� r4 r� r� rX rP r� r{ r{ r� r� rK � s$ �� rK c @ s� e Zd ZdZdZdZdZdZdZdddd�d d �Z e fddd d d �dd�Z e fddd dd �dd�Z de ddfddddd dddd�dd�Zdddddd�dd �Zddd ddd d �d d �ZdS )!�ScalarObjectAttributeImplz�represents a scalar-holding InstrumentedAttribute, where the target object is also instrumented. Adds events to delete/set operations. FTr{ rh rO r� r3 c C s� | j jr"| j||ttB tB d�}n | j||ttA tB tB d�}| � |||| j � |� | j t �}|t u r�|tur�|j d u r�td| ��d S )NrA rO )rt r� r� r5 r( r# r0 r r+ rP r r rk r, r3 r� rR r{ r{ r� r� + s8 ���������z ScalarObjectAttributeImpl.deleter7 r� r- c C s� | j |v r|| j }n,|t@ r&|tN }| j|||d�}|tu rBtS | jsVt�| ||�S |j�| j t �}|tu r�|t t B t B t B tB B }| �|| j |�}tj| |||d�S d S )NrA )�original)rk r r� r3 rV r r� �from_object_attributer8 � _NO_HISTORYr5 r( r# r+ r r9 )r� r� r� r� rW r` Zloader_passiver{ r{ r� r� K s8 �������z%ScalarObjectAttributeImpl.get_historyr1 c C s� | j |v r|| j }n |t@ r0| j|||d�}ng S |d ur\|tur\|tur\t|�|fg}ndg}| j |jv r�|j| j }|d ur�|tur�|tur�||ur�|�t|�|f� |S )NrA )NN)rk r r� r3 r, r! r8 rD )r� r� r� r� rW r6 r` r{ r{ r� r2 m s2 ��� ����z)ScalarObjectAttributeImpl.get_all_pendingNr r r� rG c C s� | j jr"| j||ttB tB d�}n | j||ttA tB tB d�}|durz|t urz||urz|r^dS t dt |�t |�| j f ��| �|||||�}||| j < dS )z'Set a value on the given InstanceState.rA Nz2Object %s not associated with %s on attribute '%s')rt r� r� r5 r( r# r0 r r+ r3 � ValueErrorr" r; rk rX rY r{ r{ r� r� � sD ������ �����z ScalarObjectAttributeImpl.setr] c C sX | j r&|d ttfvr&| �t|�|d� | jjD ]}||||p@| j� q.|�|| |� d S )NF) r r3 r, r, r! rt rF r rQ r^ r{ r{ r� rP � s � z+ScalarObjectAttributeImpl.fire_remove_eventrd rZ c C s� | j r.||ur.|d ttfvr.| �t|�|d� | jjD ]}|||||pJ| j�}q6|�|| |� | j r~|d ur~| �t|�|d� |S )NFT) r r3 r, r, r! rt r� r rQ r\ r{ r{ r� rX � s � �z,ScalarObjectAttributeImpl.fire_replace_event)r� r� r� r� r r� r� r r� r� r4 r� r2 r2 r� rP rX r{ r{ r{ r� r_ s$ $�&�)� -r_ c @ s� e Zd ZU dZded< dZdddddd �d d �Zed dd dddd�dd��Zed!dd dddd�dd��Zed"dd dddd�dd��Zde j fdd dddd�dd�Zde j dddfdd dd dddddd � d d �Z dS )#�HasCollectionAdapterr{ r� r Trh rS rT r� �r� r �adapter� fire_eventr� c C s t � �d S r� r. �r� r� r rf rg r{ r{ r� � _dispose_previous_collection� s z1HasCollectionAdapter._dispose_previous_collection.rO � Literal[None]� Literal[PassiveFlag.PASSIVE_OFF]�r� r� � user_datar� r� c C s d S r� r{ �r� r� r� rm r� r{ r{ r� �get_collection� s z#HasCollectionAdapter.get_collectionr7 c C s d S r� r{ rn r{ r{ r� ro s �$Optional[_AdaptedCollectionProtocol]�IUnion[Literal[LoaderCallableStatus.PASSIVE_NO_RESULT], CollectionAdapter]c C s d S r� r{ rn r{ r{ r� ro s Nc C s t � �d S r� r. rn r{ r{ r� ro s Fr r � r� r� r� r? r� rE r �_adaptr� c C s t � �d S r� r. ) r� r� r� r� r? r� rE r rs r{ r{ r� r� & s zHasCollectionAdapter.set)..)..)..) r� r� r� r� r� rJ ri r ro r7 r4 r� r{ r{ r{ r� rd � s2 � � ���rd z"TypeGuard[CollectionAttributeImpl])rl r� c C s d S r� r{ )rl r{ r{ r� � _is_collection_attribute_impl6 s rt r c s< e Zd ZU dZdZdZdZdZdZde d< dZ dO� fdd � Z d d � Z e fd d ddd�dd�Zefd d ddd�dd�Zd d ddddd�dd�Zd d ddddd�d d �Zd d ddd d �d d!�Zd d d"ddd d�d#d$�Zd d d d%�d&d'�Zd d d(d%�d)d*�Zd d+d,�d-d.�Ze fd d d"ddd d/�d0d1�Ze fd d d"ddd d/�d2d3�Ze fd d d"ddd d/�d4d5�Zdej dddfd d d"ddd"d6d6d d7� d8d9�Z d d(d:d6d d;�d<d=�Z d(d d>�d?d@�Z d d d"d(dA�dBdC�Z e dPd d dEdFd:dG�dHdI��Z!e dQd d d(dd:dG�dJdI��Z!e dDe fd d dKddLdG�dMdI��Z!de fd d dKddLdG�dNdI�Z!� Z"S )R�CollectionAttributeImpla� A collection-holding attribute that instruments changes in membership. Only handles collections of instrumented objects. InstrumentedCollectionAttribute holds an arbitrary, user-specified container object (defaulting to a list) and brokers access to the CollectionAdapter, a "view" onto that object that presents consistent bag semantics to the orm layer independent of the user data implementation. TFr �_bulk_replace_token)�copy�collection_factoryr r rv �_duck_typed_asNc s� t � j||||f||d�| �� |d u r.| j}|| _|| _t| t�| _t| t�| _ t| t �| _ t � | �� �| _t| jdd �r�t�| d�dd� �} t�| d�dd� �} d S ) N)r r � _sa_linker�init_collectionc S s |� |� d S r� �rz ��targetr �collection_adapterr{ r{ r� �link~ s z.CollectionAttributeImpl.__init__.<locals>.link�dispose_collectionc S s |� d � d S r� r| r} r{ r{ r� �unlink� s z0CollectionAttributeImpl.__init__.<locals>.unlink)r� r� � _CollectionAttributeImpl__copyrw rx r � OP_APPENDr rM r �OP_BULK_REPLACErv r? �duck_type_collectionry r� r= Z listens_for) r� rj rk r rt � typecallabler � copy_functionr r� r� r� r� r{ r� r� [ s4 ��� � z CollectionAttributeImpl.__init__c C s dd� t �|�D �S )Nc S s g | ]}|�qS r{ r{ )r� �yr{ r{ r� � <listcomp>� � z2CollectionAttributeImpl.__copy.<locals>.<listcomp>)r r )r� �itemr{ r{ r� Z__copy� s z CollectionAttributeImpl.__copyrh rO r7 r� r- c C sv | j |||d�}|tu rJ|tj@ rD| j|jv rD|j| j }|�t�S tS n(|tj@ rd| j|jvsdJ �t� | ||�S d S r@ ) r� r3 r7 r rk �_pending_mutationsZmerge_with_historyrV r� �from_collection)r� r� r� r� rW �pendingr{ r{ r� r� � s � � z#CollectionAttributeImpl.get_historyr1 c s� | j |vrg S || j }t|d�}| j |jv r�|j| j }|tur�dd� |D �}dd� |D �}t|�� t|���fdd�|D ��fdd�|D � � fdd�|D � S dd� |D �S ) N� _sa_adapterc S s$ g | ] }|d urt |�pd |f�qS r� r �r� �cr{ r{ r� r� � s �z;CollectionAttributeImpl.get_all_pending.<locals>.<listcomp>c S s$ g | ] }|d urt |�pd |f�qS r� r r� r{ r{ r� r� � s �c s g | ]\}}|� vr||f�qS r{ r{ �r� �s�o�� original_setr{ r� r� � s �c s g | ]\}}|� v r||f�qS r{ r{ r� r� r{ r� r� � r� c s g | ]\}}|� vr||f�qS r{ r{ r� �� current_setr{ r� r� � s �c S s g | ]}t |�|f�qS r{ r )r� r� r{ r{ r� r� � r� )rk r� r8 r, �dict)r� r� r� r� rW r` �current_states�original_statesr{ �r� r� r� r2 � s4 �� �� ���z'CollectionAttributeImpl.get_all_pendingrd r z Optional[Any])r� r� r� r? rk r� c C sX | j jD ]}||||p| j|d�}q|�|| td� | jrT|d urT| �t|�|d� |S )N�rk T)rt rD r rQ r, r r, r! �r� r� r� r� r? rk r5 r{ r{ r� �fire_append_event� s z)CollectionAttributeImpl.fire_append_eventc C s( | j jD ]}||||p| j|d�}q|S )Nr� )rt Zappend_wo_mutationr r� r{ r{ r� � fire_append_wo_mutation_event� s z5CollectionAttributeImpl.fire_append_wo_mutation_eventr� )r� r� r? rk r� c C s |� || td� dS )af A special event used for pop() operations. The "remove" event needs to have the item to be removed passed to it, which in the case of pop from a set, we don't have a way to access the item before the operation. the event is used for all pop() operations (even though set.pop is the one where it is really needed). TN)rQ r, )r� r� r� r? rk r{ r{ r� �fire_pre_remove_event� s z-CollectionAttributeImpl.fire_pre_remove_eventr c C sX | j r |d ur | �t|�|d� | jjD ]}||||p:| j|d� q(|�|| td� d S )NFr� T)r r, r! rt rF r rQ r, r� r{ r{ r� rP � s z)CollectionAttributeImpl.fire_remove_eventr3 c C s@ | j |vrd S |�|| td� | �||j�}|�� || j = d S r� )rk rQ r, ro r� Zclear_with_event)r� r� r� r r{ r{ r� r� s z CollectionAttributeImpl.deleterS c C sF | j |vsJ d��| j |jv r*|j| j S | �|�\}}|�|� |S )z;Produce an empty collection for an un-initialized attributer4 )rk �_empty_collections�_initialize_collectionZ _set_empty)r� r� r� rf rm r{ r{ r� r7 s � z&CollectionAttributeImpl._default_valuez4Tuple[CollectionAdapter, _AdaptedCollectionProtocol])r� r� c C s0 |j �| j|| j�\}}| j�|||� ||fS r� )r� Zinitialize_collectionrk rx rt r{ )r� r� rf r r{ r{ r� r� - s �z.CollectionAttributeImpl._initialize_collectionr> c C sv | j ||d |d�}|tu rT| j||||td�}| j|vs@J d��|�| j��|� n trft|t �sfJ �|� ||� d S �N)rm r� r� z,Collection was loaded during event handling.) ro r3 r� r* rk �_get_pending_mutationrD r r� rT Zappend_with_event�r� r� r� r� r? r� r r{ r{ r� rD 8 s � ���z CollectionAttributeImpl.appendc C sx | j ||jd |d�}|tu rV| j||||td� | j|vsBJ d��|�| j��|� n trht |t �shJ �|� ||� d S r� ) ro r� r3 rP r* rk r� rF r r� rT Zremove_with_eventr� r{ r{ r� rF P s ���z CollectionAttributeImpl.removec C s6 z| j |||||d� W n tttfy0 Y n0 d S r@ )rF rc r: � IndexErrorrC r{ r{ r� r f s zCollectionAttributeImpl.popr� rr c C sn | } } d } | � |�\} } |r�| jd ur4| �| �} q�t�| �}| j}||urx| d u rXdp^| jj}| jj}td||f ��t| d�r�| � � } q�|t u r�t | �} | � � } q�t | �} nt�| �t u r�t |�} t | �}| j}| jj|||| d� | j||t|tj@ A d�}|tu �r| �||�}n|| u �r(d S |�|| |d� |j}| || j< tj||| |d� | �|||d� d S )Nr� z/Incompatible collection type: %s is not %s-like� _sa_iterator)�keysrA T)r? ) r� Z _converterr? r� ry r� r� � TypeErrorr� r� r� �list�values�iterrv rt Z bulk_replacer� r5 r7 r+ r3 r7 rQ r� rk r ri )r� r� r� r� r? r� rE r rs �iterableZ orig_iterableZnew_keysZnew_collectionrm Z setting_typeZreceiving_type�given�wanted� new_valuesZevtrS �old_collectionr{ r{ r� r� v s^ ���� � �zCollectionAttributeImpl.setrT re c C s, |` |j�| jd � |r(| j�|||� d S r� )r� r� r rk rt r� rh r{ r{ r� ri � s z4CollectionAttributeImpl._dispose_previous_collection)r r� c C s t |d�}d|_d S )Nr� T)r� Z invalidated)r� r rf r{ r{ r� �_invalidate_collection� s z.CollectionAttributeImpl._invalidate_collection)r� r� r� r� c C s� | � |�\}}|r |�|� ||j| j< |�|| jg� | j|jv r�|�|| |d� |j�| j�}|j}|j }|D ]} |� | � qr|D ]} |� | � q�|S )z=Set an attribute value on the given instance and 'commit' it.T) r� Z append_multiple_without_eventr� rk rI r� rQ r Z added_itemsZ deleted_itemsZappend_without_eventZremove_without_event) r� r� r� r� r rm r� �added�removedr� r{ r{ r� r; � s z+CollectionAttributeImpl.set_committed_value.rj rk rl c C s d S r� r{ rn r{ r{ r� ro � s z&CollectionAttributeImpl.get_collectionc C s d S r� r{ rn r{ r{ r� ro s rp rq c C s d S r� r{ rn r{ r{ r� ro s c C s6 |du r0| j |||d�}|tju r&|S td|�}|jS )z�Retrieve the CollectionAdapter associated with the given state. if user_data is None, retrieves it from the state using normal "get()" rules, which will fire lazy callables or return the "empty" collection value. NrA rS )r� r$ r3 r r� )r� r� r� rm r� Zfetch_user_datar{ r{ r� ro s )NFNN)..)..)#r� r� r� r� r� r r r� r r� r� r� r� r4 r� r2 r2 r� r� r� rP r� r7 r� rD rF r r7 r� ri r� r; r ro r� r{ r{ r� r� ru > sn �+� �- � � �� Q � ���ru zQueryableAttribute[Any]r� r� )r rk �uselistr� c s� �j j��j ��fdd�� � ���fdd�}� ��fdd�}���fdd�}�rhtj�d |d d d d � ntj�d |d d d d � tj�d |d d d d � dS )z6Apply listeners to synchronize a two-way relationship.c s$ t dt| �|j|j� jjf ��d S )Nz�Bidirectional attribute conflict detected: Passing object %s to attribute "%s" triggers a modify event on attribute "%s" via the backref "%s".)rc r; r rl )� child_stater? � child_impl)r r{ r� �_acceptable_key_err@ s ���z.backref_listeners.<locals>._acceptable_key_errc s ||u r |S |d ur~|t ur~|tur~t|�t|� }}|j� j}|jsV|jsV|j}n|j }||ur~|j ||| � � �j t d� |d u�r t|�t|� } } | j� j} |j�ur�|j| jurȈ | || � | j } t| �r�| jnd } || u�r || u�r | j| | | � � |t d� |S r@ )r3 r, r! r r� rl r r r r r r+ r r0 r rt rv rD )r� �childZoldchildr? r� � old_stateZold_dictrl Zcheck_recursive_tokenr� � child_dictr� �check_append_token�check_bulk_replace_token)r� rk � parent_implr r{ r� �"emit_backref_from_scalar_set_eventN sd ���� � � � � �����z=backref_listeners.<locals>.emit_backref_from_scalar_set_eventc s� |d u r d S t |�t|� }}|j� j}|j�urL|j|jurL� | ||� |j}t|�r`|jnd }||ur�||ur�|j||| � � |t d� |S r@ ) r! r r� rl r r rt rv rD r+ r0 ) r� r� r? r� r� r� r� r� r� )r� rk r r{ r� �)emit_backref_from_collection_append_event� s4 � � �����zDbackref_listeners.<locals>.emit_backref_from_collection_append_eventc s� |d ur�|t ur�|tur�t|�t|� }}|j� j}|js\|js\|j}|j }�oX�j } n |j}t |�rp|j nd }d} ||ur�||ur�| r�t � | j�j |�s�|j||| �� |td� d S )NFrA )r3 r, r! r r� rl r r r r rt rv r? Z has_dupesr� rk r r+ r0 ) r� r� r? r� r� r� r� Zcheck_remove_tokenZcheck_replace_tokenZcheck_for_dupes_on_remove)rk r� r� r{ r� �)emit_backref_from_collection_remove_event� sF ���� ���� ��zDbackref_listeners.<locals>.emit_backref_from_collection_remove_eventrD T)r �rawZ include_keyr� rF N)rl r r= �listen)r rk r� r� r� r� r{ )r� r rk r� r r� r� �backref_listeners0 s> C$0� � �r� Z NO_HISTORYc @ s� e Zd ZU dZded< ded< ded< dd�dd �Zdd�d d �Zd d�d d�Zd d�dd�Zd d�dd�Z dd�dd�Z ddd d�dd�Z d d�dd�Z e dd d d d �d d ��Ze efd!d d d d d"�d#d$��Ze d%d d d d �d&d'��Zd(S ))r� a A 3-tuple of added, unchanged and deleted values, representing the changes which have occurred on an instrumented attribute. The easiest way to get a :class:`.History` object for a particular attribute on an object is to use the :func:`_sa.inspect` function:: from sqlalchemy import inspect hist = inspect(myobject).attrs.myattribute.history Each tuple member is an iterable sequence: * ``added`` - the collection of items added to the attribute (the first tuple element). * ``unchanged`` - the collection of items that have not changed on the attribute (the second tuple element). * ``deleted`` - the collection of items that have been removed from the attribute (the third tuple element). zUnion[Tuple[()], List[Any]]r� � unchanged�deletedr� r� c C s | t kS r� )rV r� r{ r{ r� �__bool__# s zHistory.__bool__c C s t | jp| jp| j� S )zhReturn True if this :class:`.History` has no changes and no existing, unchanged state. )r� r� r� r� r� r{ r{ r� �empty& s z History.emptyz Sequence[Any]c C s | j pg | jpg | jpg S )z3Return a collection of added + unchanged + deleted.)r� r� r� r� r{ r{ r� �sum. s �z History.sumc C s | j pg | jpg S )z)Return a collection of added + unchanged.)r� r� r� r{ r{ r� � non_deleted5 s zHistory.non_deletedc C s | j pg | jpg S )z+Return a collection of unchanged + deleted.)r� r� r� r{ r{ r� � non_added: s zHistory.non_addedc C s t | jp | j�S )z2Return True if this :class:`.History` has changes.)r� r� r� r� r{ r{ r� � has_changes? s zHistory.has_changesz Iterable[Any])r� r� r� c C s* t t| j�t|� | jt| j�t|� �S r� )r� r� r� r� r� )r� r� r� r{ r{ r� �_mergeD s �zHistory._mergec C s0 t dd� | jD �dd� | jD �dd� | jD ��S )Nc S s g | ]}|d urt |�pd �qS r� r r� r{ r{ r� r� M s �z$History.as_state.<locals>.<listcomp>c S s g | ]}|d urt |�pd �qS r� r r� r{ r{ r� r� Q s �c S s g | ]}|d urt |�pd �qS r� r r� r{ r{ r� r� U s �)r� r� r� r� r� r{ r{ r� �as_stateK s ����zHistory.as_staterK rh r )r r� rW r� c C s� |j �|jt�}|tu r<|tu r,| ddd�S | d|gd�S np|turb|�||�du rb| d|gd�S t|�tv r�d}t|�tv r�d }n|g}|tu r�| dd|�S | |gd|�S d S )Nr{ T)r8 r� rk rb r, r r( �_NO_STATE_SYMBOLS�r� r r� rW r` r� r{ r{ r� rU [ s$ �� z History.from_scalar_attributer_ )r r� rW r` r� c C s� |t u r|j�|jt �}|t u rD|tu r4| ddd�S | d|gd�S np||u rb|turb| d|gd�S t|�tv sv|d u r�d}t|�tv r�d }n|g}|tu r�| dd|�S | |gd|�S d S )Nr{ )rb r8 r� rk r, r( r� r� r{ r{ r� ra � s z History.from_object_attributeru c s� |j �|jt�}|tu r$| ddd�S t|d�}|tu rF| t|�dd�S |tu r^| dt|�d�S dd� |D �}dd� |D �}t|�� t|��| �fdd�|D ��fdd�|D �� fdd�|D ��S d S ) Nr{ r� c S s$ g | ] }|d urt |�pd |f�qS r� r r� r{ r{ r� r� � s �z+History.from_collection.<locals>.<listcomp>c S s$ g | ] }|d urt |�pd |f�qS r� r r� r{ r{ r� r� � s �c s g | ]\}}|� vr|�qS r{ r{ r� r� r{ r� r� � r� c s g | ]\}}|� v r|�qS r{ r{ r� r� r{ r� r� � r� c s g | ]\}}|� vr|�qS r{ r{ r� r� r{ r� r� � r� )r8 r� rk rb r, r� r� r� )r� r r� rW r` r� r� r{ r� r� r� � s* ���zHistory.from_collectionN)r� r� r� r� r� r� r� r� r� r� r� r� r� � classmethodrU rb ra r� r{ r{ r{ r� r� s& (�&r� r{ r� r7 )r+ rk r� r� c C s t t| �||�S )a Return a :class:`.History` record for the given object and attribute key. This is the **pre-flush** history for a given attribute, which is reset each time the :class:`.Session` flushes changes to the current database transaction. .. note:: Prefer to use the :attr:`.AttributeState.history` and :meth:`.AttributeState.load_history` accessors to retrieve the :class:`.History` for instance attributes. :param obj: an object whose class is instrumented by the attributes package. :param key: string attribute name. :param passive: indicates loading behavior for the attribute if the value is not already present. This is a bitflag attribute, which defaults to the symbol :attr:`.PASSIVE_OFF` indicating all necessary SQL should be emitted. .. seealso:: :attr:`.AttributeState.history` :meth:`.AttributeState.load_history` - retrieve history using loader callables if the value is not locally present. )�get_state_historyr! )r+ rk r� r{ r{ r� r� � s %r� r< c C s | � ||�S r� )r� )r� rk r� r{ r{ r� r� � s r� FrR )r� r+ rk r� r� c C s t | �}t|�}|�|||�S )ZTODO)r% r! � has_parent)r� r+ rk r� r� r� r{ r{ r� r� s r� )r� z interfaces.PropComparator[_T]rz zInstrumentedAttribute[_T])rj rk rm rx r� r� r� c K s( t | ||||d�}t| |fi |�� |S )N)rm rx r� )�register_descriptor�register_attribute_impl)rj rk rm rx r� r� �descr{ r{ r� �register_attribute s �r� r z Optional[Type[AttributeImpl]]) rj rk r� r � useobject� impl_class�backrefr� r� c K s� t | �}|r*|�dd �} |�|| p$t�} n |�dd �} td|| j�} |rftd|�| || fi |��} nR|r�t| ||| fd| i|��} n2|r�t| ||| fi |��} nt| ||| fi |��} | || _ |r�t || ||� |� |� || S )Nr� r z Type[WriteOnlyAttributeImpl]) r% r Zinstrument_collection_classr� r rt ru r_ rK rl r� Zpost_configure_attribute) rj rk r� r r� r� r� r� r� �factoryr� rt rl r{ r{ r� r� sH � �������� r� z Type[Any]rw )rj rk rm rx r� r� c C s. t | �}t| |||d�}||_|�||� |S )N)rm rx )r% r� r� Zinstrument_attribute)rj rk rm rx r� r� r� r{ r{ r� r� L s � r� )rj rk r� c C s t | ��|� d S r� )r% Zuninstrument_attribute)rj rk r{ r{ r� �unregister_attribute` s r� rT )r+ rk r� c C s t | �}|j}t|||�S )a4 Initialize a collection attribute and return the collection adapter. This function is used to provide direct access to collection internals for a previously unloaded attribute. e.g.:: collection_adapter = init_collection(someobject, "elements") for elem in values: collection_adapter.append_without_event(elem) For an easier way to do the above, see :func:`~sqlalchemy.orm.attributes.set_committed_value`. :param obj: a mapped object :param key: string attribute name where the collection is located. )r! r� �init_state_collection)r+ rk r� r� r{ r{ r� r{ d s r{ rO )r� r� rk r� c C st | j | j}tr t|t�s J �|�|d�}|durH|j}|�| ||d� |�| |�}|j | ||t j d�}|� � |S )z�Initialize a collection attribute and return the collection adapter. Discards any existing collection which may be there. NFrA ) r� rl r r� rd r r� ri r7 ro r7 r0 Z _reset_empty)r� r� rk �attrrS r� rm rf r{ r{ r� r� { s �r� c C s, t | �t| � }}|j| j�|||� dS )a[ Set the value of an attribute with no history events. Cancels any previous history present. The value should be a scalar value for scalar-holding attributes, or an iterable for any collection-holding attribute. This is the same underlying method used when a lazy loader fires off and loads additional data from the database. In particular, this method can be used by application code which has loaded additional attributes or collections through separate queries, which can then be attached to an instance as though it were part of its original loaded state. N)r! r r� rl r; )r� rk r� r� r� r{ r{ r� r; � s r; r )r� rk r� r? r� c C s. t | �t| � }}|j| j�||||� dS )as Set the value of an attribute, firing history events. This function may be used regardless of instrumentation applied directly to the class, i.e. no descriptors are required. Custom attribute management schemes will need to make usage of this method to establish attribute state as understood by SQLAlchemy. :param instance: the object that will be modified :param key: string name of the attribute :param value: value to assign :param initiator: an instance of :class:`.Event` that would have been propagated from a previous event listener. This argument is used when the :func:`.set_attribute` function is being used within an existing event listening function where an :class:`.Event` object is being supplied; the object may be used to track the origin of the chain of events. .. versionadded:: 1.2.3 N)r! r r� rl r� )r� rk r� r? r� r� r{ r{ r� � set_attribute� s r� )r� rk r� c C s& t | �t| � }}|j| j�||�S )aZ Get the value of an attribute, firing any callables required. This function may be used regardless of instrumentation applied directly to the class, i.e. no descriptors are required. Custom attribute management schemes will need to make usage of this method to make usage of attribute state as understood by SQLAlchemy. )r! r r� rl r� �r� rk r� r� r{ r{ r� � get_attribute� s r� c C s* t | �t| � }}|j| j�||� dS )aQ Delete the value of an attribute, firing history events. This function may be used regardless of instrumentation applied directly to the class, i.e. no descriptors are required. Custom attribute management schemes will need to make usage of this method to establish attribute state as understood by SQLAlchemy. N)r! r r� rl r� r� r{ r{ r� � del_attribute� s r� c C sD t | �t| � }}|j| j}|j�||j� |j||tdd� dS )a� Mark an attribute on an instance as 'modified'. This sets the 'modified' flag on the instance and establishes an unconditional change event for the given attribute. The attribute must have a value present, else an :class:`.InvalidRequestError` is raised. To mark an object "dirty" without referring to any specific attribute so that it is considered within a flush, use the :func:`.attributes.flag_dirty` call. .. seealso:: :func:`.attributes.flag_dirty` T�Z is_userlandN) r! r r� rl rt �modifiedr" rQ r, )r� rk r� r� rl r{ r{ r� � flag_modified� s r� r� c C s( t | �t| � }}|j|dtdd� dS )a� Mark an instance as 'dirty' without any specific attribute mentioned. This is a special operation that will allow the object to travel through the flush process for interception by events such as :meth:`.SessionEvents.before_flush`. Note that no SQL will be emitted in the flush process for an object that has no changes, even if marked dirty via this method. However, a :meth:`.SessionEvents.before_flush` handler will be able to see the object in the :attr:`.Session.dirty` collection and may establish changes on it, which will then be included in the SQL emitted. .. versionadded:: 1.2 .. seealso:: :func:`.attributes.flag_modified` NTr� )r! r rQ r, )r� r� r� r{ r{ r� � flag_dirty� s r� )F)FNFNN)N)�r� � __future__r Z dataclassesr �typingr r r r r r r r r r r r r r r r � r r r� r Z_typingr rB r r r r r r r r r! r" r# r$ r% r& r' r( r) r* r+ r, r- r. r/ r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 r: r; r= r> r? r@ rA ZsqlZsql_baserC rD rE rF Z sql.cache_keyrG Z sql.visitorsrH rI Z util.typingrJ rK rL rM rN rO rP rQ rR rS rT rU Z relationshipsrV r� rW rX Z writeonlyrY Z event.baserZ Z sql._typingr[ r\ r] r^ Zsql.annotationr_ Z sql.elementsr` ra Z sql.operatorsrb Zsql.selectablerc rd re r� r1 r� Z_self_inspectsZInspectionAttrZPropComparatorZJoinTargetRoleZ OnClauseRoleZ ImmutableZSlotsMemoizedHasCacheKeyr� ri r� r� Z dataclassr� r �symbolrM r� rL r� r! r ZAttributeEvent�Eventry rK r_ rd rt � attrgetterru r� rb � frozensetr( r� r� rV r� r� r� r� r� r� r� r{ r� r; r� r� r� r� r� r{ r{ r{ r� �<module> sl � � g? + 3 g TE u S J �)� �� � 9� �" sqlalchemy/orm/__pycache__/__init__.cpython-39.pyc 0000644 00000013566 15125143220 0016111 0 ustar 00 a ��Jh! � @ s� d Z ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z ddl m Z dd l m Z dd l m Z dd l mZ dd l mZ dd l mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl m Z ddl m Z ddl m Z dd l m Z dd l m!Z! dd l"m#Z# dd l"m$Z$ dd l"m%Z% dd!l"m&Z& dd"l"m'Z' dd#l"m(Z( dd$l"m)Z) dd%l"m*Z* dd&l"m+Z+ dd'l"m,Z, dd(l-m.Z. dd)l-m/Z/ dd*l0m1Z1 dd+l0m2Z2 dd,l0m3Z3 dd-l0m4Z4 dd.l0m5Z5 dd/l0m6Z6 dd0l0m7Z7 dd1l0m8Z8 dd2l0m9Z9 dd3l0m:Z: dd4l0m;Z; dd5l0m<Z< dd6l=m>Z> dd7l?m@Z@ dd8l?mAZA dd9l?mBZB dd:l?mCZC dd;lDmEZE dd<lFmGZG dd=lFmHZH dd>lFmIZI dd?lFmJZJ dd@lFmKZK ddAlFmLZL ddBlMmNZN ddClOmPZP ddDlQmRZR ddElQmSZS ddFlQmTZT ddGlQmUZU ddHlQmVZV ddIlQmWZW ddJlQmXZX ddKlQmYZY ddLlQmZZZ ddMlQm[Z[ ddNlQm\Z\ ddOlQm]Z] ddPlQm^Z^ ddQlQm_Z_ ddRl`maZa ddSl`mbZb ddTlcmdZd ddUlcmeZe ddVlcmfZf ddWlcmgZg ddXlcmhZh ddYlcmiZi ddZlcmcZc dd[lcmjZj dd\lmkZk dd]lmlZl dd^lmmZm dd_lmnZn dd`lompZp ddalomqZq ddblomrZr ddclsmtZt dddlsmuZu ddelvmwZw ddflvmxZx ddglvmyZy ddhlvmzZz ddil{m|Z| ddjl{m}Z} ddkl~mZ ddll~m�Z� ddml~m�Z� ddnl~m�Z� ddol~m�Z� ddpl~m�Z� ddql~m�Z� ddrl~m�Z� ddsl~m�Z� ddtl�m�Z� ddul�m�Z� ddvl m�Z� ddwl m�Z� ddxl m�Z� ddyl m�Z� ddzl m�Z� dd{l m�Z� dd|l m�Z� dd}l m�Z� dd~l m�Z� ddl m�Z� dd�l m�Z� dd�l m�Z� dd�l m�Z� dd�l m�Z� dd�l m�Z� dd�l m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� dd�l�m�Z� d�d�lm�Z� d�d�d��d�d��Z�e�e�� � d�S )�z� Functional constructs for ORM configuration. See the SQLAlchemy object relational tutorial and mapper configuration documentation for an overview of how this module is used. � )� annotations)�Any� )�exc)�mapper)�strategy_options)� _mapper_fn)�aliased)�backref)� clear_mappers)�column_property)� composite)�contains_alias)�create_session)�deferred)�dynamic_loader)�join)� mapped_column)�orm_insert_sentinel)� outerjoin)�query_expression)� relationship)�synonym)�with_loader_criteria)�with_polymorphic)�AttributeEventToken)�InstrumentedAttribute)�QueryableAttribute)� class_mapper)� DynamicMapped)�InspectionAttrExtensionType)�LoaderCallableStatus)�Mapped)� NotExtension)� ORMDescriptor)� PassiveFlag)�SQLORMExpression)�WriteOnlyMapped)� FromStatement)� QueryContext)�add_mapped_attribute)�as_declarative)�declarative_base)�declarative_mixin)�DeclarativeBase)�DeclarativeBaseNoMeta)�DeclarativeMeta)� declared_attr)�has_inherited_table)�MappedAsDataclass)�registry)� synonym_for)�MappedClassProtocol)� Composite)�CompositeProperty)�Synonym)�SynonymProperty)� AppenderQuery)�AttributeEvents)�InstanceEvents)�InstrumentationEvents)� MapperEvents)� QueryEvents)� SessionEvents)� IdentityMap)� ClassManager)� EXT_CONTINUE)�EXT_SKIP)�EXT_STOP)�InspectionAttr)�InspectionAttrInfo)� MANYTOMANY)� MANYTOONE)�MapperProperty)�NO_KEY)�NO_VALUE)� ONETOMANY)�PropComparator)�RelationshipDirection)�UserDefinedOption)�merge_frozen_result)� merge_result)�attribute_keyed_dict)�attribute_mapped_collection)�column_keyed_dict)�column_mapped_collection)�keyfunc_mapping)� KeyFuncDict)�mapped_collection)�MappedCollection)�configure_mappers)�Mapper)� reconstructor)� validates)�ColumnProperty)� MappedColumn)�MappedSQLExpression)� AliasOption)�Query)�foreign)� Relationship)�RelationshipProperty)�remote)�QueryPropertyDescriptor)�scoped_session)�close_all_sessions)�make_transient)�make_transient_to_detached)�object_session)�ORMExecuteState)�Session)� sessionmaker)�SessionTransaction)�SessionTransactionOrigin)�AttributeState)� InstanceState)�contains_eager)� defaultload)�defer)� immediateload)� joinedload)�lazyload)�Load)� load_only)�noload)� raiseload)�selectin_polymorphic)� selectinload)� subqueryload)�undefer)� undefer_group)�with_expression)�UOWTransaction)�Bundle)�CascadeOptions)�LoaderCriteriaOption)� object_mapper)�polymorphic_union)� was_deleted)� with_parent)�WriteOnlyCollection� )�utilr �None)�lcls�returnc C s t j�d� t j�d� d S )Nzsqlalchemy.ormzsqlalchemy.ext)�_sa_utilZ preloadedZ import_prefix)r� � r� �L/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/__init__.py�__go� s r� N)��__doc__� __future__r �typingr � r r Z mapperlibr Z_orm_constructorsr r r r r r r r r r r r r r r r r r r � attributesr r r �baser r r r! r" r# r$ r% r& r' �contextr( r) Zdecl_apir* r+ r, r- r. r/ r0 r1 r2 r3 r4 r5 Z decl_baser6 Zdescriptor_propsr7 r8 r9 r: Zdynamicr; �eventsr< r= r> r? r@ rA �identityrB ZinstrumentationrC Z interfacesrD rE rF rG rH rI rJ rK rL rM rN rO rP rQ ZloadingrR rS rZ rT rU rV rW rX rY r[ r\ r] r^ r_ Z propertiesr` ra rb �queryrc rd Z relationshipsre rf rg rh Zscopingri rj �sessionrk rl rm rn ro rp rq rr rs �statert ru rv rw rx ry rz r{ r| r} r~ r r� r� r� r� r� r� Z unitofworkr� r� r� r� r� r� r� r� r� Z writeonlyr� r� r� �localsr� r� r� r� �<module> s sqlalchemy/orm/__pycache__/collections.cpython-39.pyc 0000644 00000133622 15125143220 0016664 0 ustar 00 a ��Jh � � @ s� U d Z ddlmZ ddlZddlZddlZddlmZ ddlmZ ddlmZ ddlm Z ddlm Z dd lm Z dd lm Z dd lm Z dd lmZ dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlZddlmZ ddlmZ ddlmZ ddl m Z ddl m Z ddl m!Z! ej�r�ddl"m#Z# dd l"m$Z$ dd l%m&a& dd l%m'a' dd l%m(a( dd l%m)a) dd!l*m+Z+ g d"�Z,e�-� Z.eg d#f Z/ed$ed%�Z0ed&ed%�Z1ed'ed%�Z2ed(d)d%�Z3ed*d+d%�Z4G d,d-� d-e!�Z5G d.d#� d#e!�Z6G d/d0� d0�Z7e�r(d)d1d2�d3d4�Z8n e�9d5�Z8G d6d1� d1�Z:dtd7d8�Z;d9d:d;�d<d=�Z<d>d?� Z=d@dA� Z>dBdC� Z?dDdE� Z@dFdG� ZAdHdI� ZBdudJdK�ZCdLdM� ZDdNdO� ZEdvdPdQ�ZFdRdS�dTdU�ZGdRdS�dVdW�ZHeIeJfZKdXdXdYdZ�d[d\�ZLdXdXdYdZ�d]d^�ZMdRdS�d_d`�ZNG dadb� dbe e0 �ZOG dcdd� ddee0 �ZPG dedf� dfe e1e2f �ZQe�ReSeOeIePeTeQi�ZUdgeVdh< e�ReSdidjdkdl�eG� feIdmdjdkdl�eN� feTdndoieH� fi�ZWdpeVdq< drds� ZXeXeY� � dS )waL Support for collections of mapped entities. The collections package supplies the machinery used to inform the ORM of collection membership changes. An instrumentation via decoration approach is used, allowing arbitrary types (including built-ins) to be used as entity collections without requiring inheritance from a base class. Instrumentation decoration relays membership change events to the :class:`.CollectionAttributeImpl` that is currently managing the collection. The decorators observe function call arguments and return values, tracking entities entering or leaving the collection. Two decorator approaches are provided. One is a bundle of generic decorators that map function arguments and return values to events:: from sqlalchemy.orm.collections import collection class MyClass: # ... @collection.adds(1) def store(self, item): self.data.append(item) @collection.removes_return() def pop(self): return self.data.pop() The second approach is a bundle of targeted decorators that wrap appropriate append and remove notifiers around the mutation methods present in the standard Python ``list``, ``set`` and ``dict`` interfaces. These could be specified in terms of generic decorator recipes, but are instead hand-tooled for increased efficiency. The targeted decorators occasionally implement adapter-like behavior, such as mapping bulk-set methods (``extend``, ``update``, ``__setslice__``, etc.) into the series of atomic mutation events that the ORM requires. The targeted decorators are used internally for automatic instrumentation of entity collection classes. Every collection class goes through a transformation process roughly like so: 1. If the class is a built-in, substitute a trivial sub-class 2. Is this class already instrumented? 3. Add in generic decorators 4. Sniff out the collection interface through duck-typing 5. Add targeted decoration to any undecorated interface method This process modifies the class at runtime, decorating methods and adding some bookkeeping properties. This isn't possible (or desirable) for built-in classes like ``list``, so trivial sub-classes are substituted to hold decoration:: class InstrumentedList(list): pass Collection classes can be specified in ``relationship(collection_class=)`` as types or a function that returns an instance. Collection classes are inspected and instrumented during the mapper compilation phase. The collection_class callable will be executed once to produce a specimen instance, and the type of that specimen will be instrumented. Functions that return built-in types like ``lists`` will be adapted to produce instrumented instances. When extending a known type like ``list``, additional decorations are not generally not needed. Odds are, the extension method will delegate to a method that's already instrumented. For example:: class QueueIsh(list): def push(self, item): self.append(item) def shift(self): return self.pop(0) There's no need to decorate these methods. ``append`` and ``pop`` are already instrumented as part of the ``list`` interface. Decorating them would fire duplicate events, which should be avoided. The targeted decoration tries not to rely on other methods in the underlying collection class, but some are unavoidable. Many depend on 'read' methods being present to properly instrument a 'write', for example, ``__setitem__`` needs ``__getitem__``. "Bulk" methods like ``update`` and ``extend`` may also reimplemented in terms of atomic appends and removes, so the ``extend`` decoration will actually perform many ``append`` operations and not call the underlying method at all. Tight control over bulk operation and the firing of events is also possible by implementing the instrumentation internally in your methods. The basic instrumentation package works under the general assumption that collection mutation will not raise unusual exceptions. If you want to closely orchestrate append and remove events with exception management, internal instrumentation may be the answer. Within your method, ``collection_adapter(self)`` will retrieve an object that you can use for explicit control over triggering append and remove events. The owning object and :class:`.CollectionAttributeImpl` are also reachable through the adapter, allowing for some very sophisticated behavior. � )� annotationsN)�Any)�Callable)�cast)� Collection)�Dict)�Iterable)�List)�NoReturn)�Optional)�Set)�Tuple)�Type)� TYPE_CHECKING)�TypeVar)�Union� )�NO_KEY� )�exc)�util��NO_ARG)�inspect_getfullargspec)�Protocol)�AttributeEventToken)�CollectionAttributeImpl��attribute_keyed_dict��column_keyed_dict��keyfunc_mapping�� KeyFuncDict)� InstanceState) � collection�collection_adapterr" r r r$ �mapped_collection�column_mapped_collection�attribute_mapped_collection�MappedCollection�_AdaptedCollectionProtocol�_T)�bound�_KT�_VT�_COLzCollection[Any]�_FN�Callable[..., Any]c @ s e Zd Zddd�dd�ZdS )� _CollectionConverterProtocolr1 �r& �returnc C s d S �N� )�selfr& r8 r8 �O/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/collections.py�__call__� � z%_CollectionConverterProtocol.__call__N)�__name__� __module__� __qualname__r; r8 r8 r8 r: r4 � s r4 c @ s6 e Zd ZU ded< ded< ded< ded< ded < d S ) r, �CollectionAdapter� _sa_adapterr3 � _sa_appender� _sa_removerz Callable[..., Iterable[Any]]� _sa_iteratorr4 � _sa_converterN)r= r> r? �__annotations__r8 r8 r8 r: r, � s c @ s� e Zd ZdZedd� �Zedd� �Zedd� �Zedd � �Zee � d d �d d � ��Z edd� �Z edd� �Z edd� �Zedd� �ZdS )r& av Decorators for entity collection classes. The decorators fall into two groups: annotations and interception recipes. The annotating decorators (appender, remover, iterator, converter, internally_instrumented) indicate the method's purpose and take no arguments. They are not written with parens:: @collection.appender def append(self, append): ... The recipe decorators all require parens, even those that take no arguments:: @collection.adds("entity") def insert(self, position, entity): ... @collection.removes_return() def popitem(self): ... c C s d| _ | S )a Tag the method as the collection appender. The appender method is called with one positional argument: the value to append. The method will be automatically decorated with 'adds(1)' if not already decorated:: @collection.appender def add(self, append): ... # or, equivalently @collection.appender @collection.adds(1) def add(self, append): ... # for mapping type, an 'append' may kick out a previous value # that occupies that slot. consider d['a'] = 'foo'- any previous # value in d['a'] is discarded. @collection.appender @collection.replaces(1) def add(self, entity): key = some_key_func(entity) previous = None if key in self: previous = self[key] self[key] = entity return previous If the value to append is not allowed in the collection, you may raise an exception. Something to remember is that the appender will be called for each object mapped by a database query. If the database contains rows that violate your collection semantics, you will need to get creative to fix the problem, as access via the collection will not work. If the appender method is internally instrumented, you must also receive the keyword argument '_sa_initiator' and ensure its promulgation to collection events. �appender��_sa_instrument_role��fnr8 r8 r: rG � s +zcollection.appenderc C s d| _ | S )a Tag the method as the collection remover. The remover method is called with one positional argument: the value to remove. The method will be automatically decorated with :meth:`removes_return` if not already decorated:: @collection.remover def zap(self, entity): ... # or, equivalently @collection.remover @collection.removes_return() def zap(self): ... If the value to remove is not present in the collection, you may raise an exception or return None to ignore the error. If the remove method is internally instrumented, you must also receive the keyword argument '_sa_initiator' and ensure its promulgation to collection events. �removerrH rJ r8 r8 r: rL s zcollection.removerc C s d| _ | S )z�Tag the method as the collection remover. The iterator method is called with no arguments. It is expected to return an iterator over all collection members:: @collection.iterator def __iter__(self): ... �iteratorrH rJ r8 r8 r: rM s zcollection.iteratorc C s d| _ | S )a� Tag the method as instrumented. This tag will prevent any decoration from being applied to the method. Use this if you are orchestrating your own calls to :func:`.collection_adapter` in one of the basic SQLAlchemy interface methods, or to prevent an automatic ABC method decoration from wrapping your implementation:: # normally an 'extend' method on a list-like class would be # automatically intercepted and re-implemented in terms of # SQLAlchemy events and append(). your implementation will # never be called, unless: @collection.internally_instrumented def extend(self, items): ... T)�_sa_instrumentedrJ r8 r8 r: �internally_instrumented, s z"collection.internally_instrumentedz1.3z�The :meth:`.collection.converter` handler is deprecated and will be removed in a future release. Please refer to the :class:`.AttributeEvents.bulk_replace` listener interface in conjunction with the :func:`.event.listen` function.c C s d| _ | S )a� Tag the method as the collection converter. This optional method will be called when a collection is being replaced entirely, as in:: myobj.acollection = [newvalue1, newvalue2] The converter method will receive the object being assigned and should return an iterable of values suitable for use by the ``appender`` method. A converter must not assign values or mutate the collection, its sole job is to adapt the value the user provides into an iterable of values for the ORM's use. The default converter implementation will use duck-typing to do the conversion. A dict-like collection will be convert into an iterable of dictionary values, and other types will simply be iterated:: @collection.converter def convert(self, other): ... If the duck-typing of the object does not match the type of this collection, a TypeError is raised. Supply an implementation of this method if you want to expand the range of possible types that can be assigned in bulk or perform validation on the values about to be assigned. � converterrH rJ r8 r8 r: rP A s %zcollection.converterc s � fdd�}|S )a� Mark the method as adding an entity to the collection. Adds "add to collection" handling to the method. The decorator argument indicates which method argument holds the SQLAlchemy-relevant value. Arguments can be specified positionally (i.e. integer) or by name:: @collection.adds(1) def push(self, item): ... @collection.adds("entity") def do_stuff(self, thing, entity=None): ... c s d� f| _ | S )N�fire_append_event��_sa_instrument_beforerJ ��argr8 r: � decorator{ s z"collection.adds.<locals>.decoratorr8 �rU rV r8 rT r: �addsi s zcollection.addsc s � fdd�}|S )a Mark the method as replacing an entity in the collection. Adds "add to collection" and "remove from collection" handling to the method. The decorator argument indicates which method argument holds the SQLAlchemy-relevant value to be added, and return value, if any will be considered the value to remove. Arguments can be specified positionally (i.e. integer) or by name:: @collection.replaces(2) def __setitem__(self, index, item): ... c s d� f| _ d| _| S )NrQ �fire_remove_event)rS �_sa_instrument_afterrJ rT r8 r: rV � s z&collection.replaces.<locals>.decoratorr8 rW r8 rT r: �replaces� s zcollection.replacesc s � fdd�}|S )a Mark the method as removing an entity in the collection. Adds "remove from collection" handling to the method. The decorator argument indicates which method argument holds the SQLAlchemy-relevant value to be removed. Arguments can be specified positionally (i.e. integer) or by name:: @collection.removes(1) def zap(self, item): ... For methods where the value to remove is not known at call-time, use collection.removes_return. c s d� f| _ | S �NrY rR rJ rT r8 r: rV � s z%collection.removes.<locals>.decoratorr8 rW r8 rT r: �removes� s zcollection.removesc C s dd� } | S )a� Mark the method as removing an entity in the collection. Adds "remove from collection" handling to the method. The return value of the method, if any, is considered the value to remove. The method arguments are not inspected:: @collection.removes_return() def pop(self): ... For methods where the value to remove is known at call-time, use collection.remove. c S s d| _ | S r\ )rZ rJ r8 r8 r: rV � s z,collection.removes_return.<locals>.decoratorr8 )rV r8 r8 r: �removes_return� s zcollection.removes_returnN)r= r> r? �__doc__� staticmethodrG rL rM rO r � deprecatedrP rX r[ r] r^ r8 r8 r8 r: r& � s. - � r& r@ r5 c C s dS )z7Fetch the :class:`.CollectionAdapter` for a collection.Nr8 )r& r8 r8 r: r' � s r' rA c @ s� e Zd ZU dZdZded< ded< ded< d ed < d ed < d ed< d ed< dd dd�dd�Zdd�dd�Zedd�dd��Z ed d�dd��Z d d � Z dSd d dd!�d"d#�Z d$d%� Z dd�d&d'�Zd(d�d)d*�Zd dd+�d,d-�Zd.dd/�d0d1�Zd2d3� ZdTd d dd!�d4d5�Zd dd+�d6d7�ZdUd dd8�d9d:�Zdd�d;d<�Zd=d>� Zd?d@� ZdAdB� Zd efdCdD�Zd efdEdF�Z d efdGdH�Z d efdIdJ�Z d efdKdL�Z d efdMdN�Z dOdP� Z!dQdR� Z"d S )Vr@ ai Bridges between the ORM and arbitrary Python collections. Proxies base-level collection operations (append, remove, iterate) to the underlying Python collection, and emits add/remove events for entities entering or leaving the collection. The ORM uses :class:`.CollectionAdapter` exclusively for interaction with entity collections. )�attr�_key�_data� owner_state� _converter� invalidated�emptyr rb �strrc z)Callable[..., _AdaptedCollectionProtocol]rd zInstanceState[Any]re r4 rf �boolrg rh r, )rb re �datac C s> || _ |j| _t�|�| _|| _| |_|j| _ d| _ d| _ d S �NF) rb �keyrc �weakref�refrd re rA rE rf rg rh )r9 rb re rk r8 r8 r: �__init__� s zCollectionAdapter.__init__�None�r6 c C s t �d� d S )Nz%This collection has been invalidated.)r �warn�r9 r8 r8 r: �_warn_invalidated s z#CollectionAdapter._warn_invalidatedc C s | � � S )z$The entity collection being adapted.)rd rt r8 r8 r: rk s zCollectionAdapter.datac C s | j j| j | �� u S )z�return True if the owner state still refers to this collection. This will return False within a bulk replace operation, where this collection is the one being replaced. )re �dictrc rd rt r8 r8 r: �_referenced_by_owner s z&CollectionAdapter._referenced_by_ownerc C s | � � jS r7 �rd rB rt r8 r8 r: � bulk_appender s z CollectionAdapter.bulk_appenderNr z Optional[AttributeEventToken])�item� initiatorr6 c C s | � � j||d� dS )z8Add an entity to the collection, firing mutation events.�� _sa_initiatorNrx �r9 rz r{ r8 r8 r: �append_with_event s z#CollectionAdapter.append_with_eventc C s& | j rJ d��d| _ || jj| j< d S )Nz7This collection adapter is already in the 'empty' stateT)rh re �_empty_collectionsrc )r9 � user_datar8 r8 r: � _set_empty# s ��z CollectionAdapter._set_emptyc C s2 | j sJ d��d| _ | jj�| j�| jj| j< d S )Nz3This collection adapter is not in the 'empty' stateF)rh re r� �poprc rv rt r8 r8 r: � _reset_empty* s ���z CollectionAdapter._reset_emptyr c C s t �d��d S )NzZThis is a special 'empty' collection which cannot accommodate internal mutation operations)�sa_excZInvalidRequestErrorrt r8 r8 r: � _refuse_empty3 s �z CollectionAdapter._refuse_empty)rz r6 c C s$ | j r| �� | �� j|dd� dS �z=Add or restore an entity to the collection, firing no events.Fr| N�rh r� rd rB �r9 rz r8 r8 r: �append_without_event9 s z&CollectionAdapter.append_without_eventz Iterable[Any])�itemsr6 c C s2 | j r| �� | �� j}|D ]}||dd� q dS r� r� )r9 r� rG rz r8 r8 r: � append_multiple_without_event@ s z/CollectionAdapter.append_multiple_without_eventc C s | � � jS r7 �rd rC rt r8 r8 r: � bulk_removerH s z CollectionAdapter.bulk_removerc C s | � � j||d� dS )z=Remove an entity from the collection, firing mutation events.r| Nr� r~ r8 r8 r: �remove_with_eventK s z#CollectionAdapter.remove_with_eventc C s$ | j r| �� | �� j|dd� dS )z7Remove an entity from the collection, firing no events.Fr| N)rh r� rd rC r� r8 r8 r: �remove_without_eventQ s z&CollectionAdapter.remove_without_event)r{ r6 c C s6 | j r| �� | �� j}t| �D ]}|||d� q dS )z>Empty the collection, firing a mutation event for each entity.r| N�rh r� rd rC �list)r9 r{ rL rz r8 r8 r: �clear_with_eventW s z"CollectionAdapter.clear_with_eventc C s6 | j r| �� | �� j}t| �D ]}||dd� q dS )z'Empty the collection, firing no events.Fr| Nr� )r9 rL rz r8 r8 r: �clear_without_eventb s z%CollectionAdapter.clear_without_eventc C s t | �� �� �S )z(Iterate over entities in the collection.)�iterrd rD rt r8 r8 r: �__iter__k s zCollectionAdapter.__iter__c C s t t| �� �� ��S )z!Count entities in the collection.)�lenr� rd rD rt r8 r8 r: �__len__p s zCollectionAdapter.__len__c C s dS �NTr8 rt r8 r8 r: �__bool__t s zCollectionAdapter.__bool__c C sT |sd S |durP| j r | �� | jr,| �� |D ] }| j�| j| jj|||� q0d S rl �rg ru rh r� rb � fire_append_wo_mutation_eventre rv �r9 r� r{ rm rz r8 r8 r: �#_fire_append_wo_mutation_event_bulkw s �z5CollectionAdapter._fire_append_wo_mutation_event_bulkc C sF |dur>| j r| �� | jr$| �� | j�| j| jj|||�S |S dS )ab Notify that a entity is entering the collection but is already present. Initiator is a token owned by the InstrumentedAttribute that initiated the membership mutation, and should be left as None unless you are passing along an initiator value from a chained operation. .. versionadded:: 1.4.15 FNr� �r9 rz r{ rm r8 r8 r: r� � s �z/CollectionAdapter.fire_append_wo_mutation_eventc C sF |dur>| j r| �� | jr$| �� | j�| j| jj|||�S |S dS )a Notify that a entity has entered the collection. Initiator is a token owned by the InstrumentedAttribute that initiated the membership mutation, and should be left as None unless you are passing along an initiator value from a chained operation. FN)rg ru rh r� rb rQ re rv r� r8 r8 r: rQ � s �z#CollectionAdapter.fire_append_eventc C sT |sd S |durP| j r | �� | jr,| �� |D ] }| j�| j| jj|||� q0d S rl �rg ru rh r� rb rY re rv r� r8 r8 r: �_fire_remove_event_bulk� s �z)CollectionAdapter._fire_remove_event_bulkc C sB |dur>| j r| �� | jr$| �� | j�| j| jj|||� dS )a Notify that a entity has been removed from the collection. Initiator is the InstrumentedAttribute that initiated the membership mutation, and should be left as None unless you are passing along an initiator value from a chained operation. FNr� r� r8 r8 r: rY � s �z#CollectionAdapter.fire_remove_eventc C s, | j r| �� | jj| j| jj||d� dS )z�Notify that an entity is about to be removed from the collection. Only called if the entity cannot be removed after calling fire_remove_event(). )r{ rm N)rg ru rb �fire_pre_remove_eventre rv )r9 r{ rm r8 r8 r: r� � s �z'CollectionAdapter.fire_pre_remove_eventc C s | j | j| jj| j| j| jd�S )N)rm re � owner_clsrk rg rh )rc re �class_rk rg rh rt r8 r8 r: � __getstate__� s �z CollectionAdapter.__getstate__c C sj |d | _ |d | _t�|d �| _|d j| _| |d _|d | _t |d | j �j | _ |� dd�| _ d S )Nrm re rk rg r� rh F)rc re rn ro rd rE rf rA rg �getattr�implrb �getrh )r9 �dr8 r8 r: � __setstate__� s z CollectionAdapter.__setstate__)N)N)N)#r= r> r? r_ � __slots__rF rp ru �propertyrk rw ry r r� r� r� r� r� r� r� r� r� r� r� r� r� r r� r� rQ r� rY r� r� r� r8 r8 r8 r: r@ � sT � � � � c C s� t | t�sJ �tj}||p d�}|�| p*d�}|| p6d��|�}|�|�}|�� } | pXdD ].} | |v rt| | |d� qZ| |v rZ| | dd� qZ|r�|j||d� |j||d� dS )aF Load a new collection, firing events based on prior like membership. Appends instances in ``values`` onto the ``new_adapter``. Events will be fired for any instance not present in the ``existing_adapter``. Any instances in ``existing_adapter`` not present in ``values`` will have remove events fired upon them. :param values: An iterable of collection member instances :param existing_adapter: A :class:`.CollectionAdapter` of instances to be replaced :param new_adapter: An empty :class:`.CollectionAdapter` to load with ``values`` r8 r| F)r{ N) � isinstancer� r Z IdentitySet� intersection� differencery r� r� ) �valuesZexisting_adapterZ new_adapterr{ ZidsetZexisting_idset� constants� additionsZremovalsrG �memberr8 r8 r: � bulk_replace s" �r� z4Union[Type[Collection[Any]], _CollectionFactoryType]�_CollectionFactoryType)�factoryr6 c C s� | t v rt | }n tt| �}t|� �}|t v r@t | }t|� �}t�� r|z(t|dd�t|�krft|� W t� � n t� � 0 |S )ao Prepare a callable for future use as a collection class factory. Given a collection class factory (either a type or no-arg callable), return another factory that will produce compatible instances when called. This function is responsible for converting collection_class=list into the run-time behavior of collection_class=InstrumentedList. rN N) �__canned_instrumentationr r� �type�__instrumentation_mutex�acquirer� �id�_instrument_class�release)r� Z impl_factory�clsr8 r8 r: �prepare_instrumentation6 s r� c C sH | j dkrt�d��t| �\}}t| ||� t| ||� t| ||� dS )z6Modify methods in a class and install instrumentation.� __builtin__zGCan not instrument a built-in type. Use a subclass, even a trivial one.N)r> r� � ArgumentError�_locate_roles_and_methods�_setup_canned_roles�_assert_required_roles�_set_collection_attributes�r� �roles�methodsr8 r8 r: r� f s � r� c C s� i }i }| j D ]�}t|��� D ]�\}}t|�s0q t|d�rX|j}|dv sLJ �|�||� d}d}t|d�r�|j\} } | dv s�J �| | f}t|d�r�|j} | dv s�J �| }|r�||f ||< q |r dd|f||< q q||fS )zgsearch for _sa_instrument_role-decorated methods in method resolution order, assign to roles. rI )rG rL rM rP NrS )rQ rY rZ ) �__mro__�varsr� �callable�hasattrrI � setdefaultrS rZ ) r� r� r� Zsupercls�name�method�role�before�after�op�argumentr8 r8 r: r� { s2 r� c C s� t �| �}|tv r�|dus J �t| \}}|�� D ]\}}|�||� q2|�� D ]:\}} t| |d�} | rP||vrPt| d�sPt| || | �� qPdS )z�see if this class has "canned" roles based on a known collection type (dict, set, list). Apply those roles as needed to the "roles" dictionary, and also prepare "decorator" methods NrN )r �duck_type_collection� __interfacesr� r� r� r� �setattr) r� r� r� Zcollection_typeZ canned_rolesZ decoratorsr� r� r� rV rK r8 r8 r: r� � s ���r� c C s� d|vst | |d �s(t�d| j ��n,|d |vrTt t| |d �d�sTd||d < d|vsjt | |d �s|t�d| j ��n,|d |vr�t t| |d �d�s�d||d < d|vs�t | |d �s�t�d | j ��d S ) zTensure all roles are present, and apply implicit instrumentation if needed rG z>Type %s must elect an appender method to be a collection classrN )rQ r NrL z<Type %s must elect a remover method to be a collection class)rY r NrM z>Type %s must elect an iterator method to be a collection classN)r� r� r� r= r� r� r8 r8 r: r� � s4 ��� ��� ��r� c C s� |� � D ]*\}\}}}t| |tt| |�|||�� q|� � D ] \}}t| d| t| |�� q<d| _t| d�srd| _t| �| _dS )zkapply ad-hoc instrumentation from decorators, class-level defaults and implicit role declarations z_sa_%sNrE ) r� r� � _instrument_membership_mutatorr� rA r� rE r� rN )r� r� r� � method_namer� r� r� r� r8 r8 r: r� � s �� r� c s� �r`t t�t��d ��}t�t�rB��t|��kr<|� p>d�n �|v rV|����nd���~� �����fdd�}d|_t �d�r��j |_ �j |_ �j |_ |S )zIRoute method args and/or return value through the collection adapter.r Nc s� �rb�d u r,�|vr"t �d� ��|� }n6t| ��krB| � }n �|v rT|� }nt �d� ��|�dd �}|du r|d }n | d j}�r�|r�t|��||� � r�|s��| i |��S �| i |��}|d ur�t|� �||� |S d S )NzMissing argument %sr} Fr )r� r� r� r� rA r� )�args�kw�valuer{ �executor�res�r� r� r� r� Z named_argZpos_argr8 r: �wrapper s4 � � z/_instrument_membership_mutator.<locals>.wrapperTrI ) r� r Zflatten_iteratorr r� �intr� �indexrN r� rI r= r_ )r� r� r� r� Zfn_argsr� r8 r� r: r� � s& � # r� c C s& |dur"| j }|r"|j||dd� dS )zERun set wo mutation events. The collection is not mutated. FN�rm )rA r� )r& rz r} r� r8 r8 r: �__set_wo_mutation7 s �r� c C s& |dur"| j }|r"|j|||d�}|S )z^Run set events. This event always occurs before the collection is actually mutated. Fr� )rA rQ �r& rz r} rm r� r8 r8 r: �__setE s r� c C s& |dur"| j }|r"|j|||d� dS )a Run del events. This event occurs before the collection is actually mutated, *except* in the case of a pop operation, in which case it occurs afterwards. For pop operations, the __before_pop hook is called before the operation occurs. Fr� N)rA rY r� r8 r8 r: �__delS s r� c C s | j }|r|�|� dS )z;An event which occurs on a before a pop() operation occurs.N)rA r� )r& r} r� r8 r8 r: � __before_popb s r� z Dict[str, Callable[[_FN], _FN]]rr c s� dd� � � fdd�} � fdd�}� fdd�}� fd d �}� fd d �}� fd d�}� fdd�}� fdd�}� fdd�}t � �� } | �d� | S )z:Tailored instrumentation wrappers for any list-like class.c S s d| _ tt| j�j| _d S r� )rN r� r� r= r_ rJ r8 r8 r: �_tidyl s z _list_decorators.<locals>._tidyc s d� fdd� }�|� |S )Nc s t | ||t�}� | |� d S r7 )r� r )r9 rz r} rJ r8 r: �appendq s z0_list_decorators.<locals>.append.<locals>.append)Nr8 )rK r� �r� rJ r: r� p s z _list_decorators.<locals>.appendc s d� fdd� }�|� |S )Nc s t | ||t� � | |� d S r7 �r� r �r9 r� r} rJ r8 r: �removey s z0_list_decorators.<locals>.remove.<locals>.remove)Nr8 �rK r� r� rJ r: r� x s z _list_decorators.<locals>.removec s � fdd�}�|� |S )Nc s t | |d |�}� | ||� d S r7 )r� )r9 r� r� rJ r8 r: �insert� s z0_list_decorators.<locals>.insert.<locals>.insertr8 )rK r� r� rJ r: r� � s z _list_decorators.<locals>.insertc s � fdd�}�|� |S )Nc sX t |t�sF| | }|d ur(t| |d |� t| |d |�}� | ||� �n|jpNd}|jpXd}|dk rn|t| �7 }|jd ur�|j}nt| �}|dk r�|t| �7 }|dkr�|| u r�d S t|||�D ]}t| �|kr�| |= q�t |�D ]\}}| � || |� q�n\t t|||��} t|�t| �k�r2t dt|�t| �f ��t | |�D ]\}}| �||� �q<d S )Nr r zBattempt to assign sequence of size %s to extended slice of size %s)r� �slicer� r� �step�startr� �stop�range� enumerater� r� � ValueError�zip� __setitem__) r9 r� r� �existingr� r� r� �irz �rngrJ r8 r: r� � s@ ��z:_list_decorators.<locals>.__setitem__.<locals>.__setitem__r8 �rK r� r� rJ r: r� � s (z%_list_decorators.<locals>.__setitem__c s � fdd�}�|� |S )Nc sV t |t�s,| | }t| |d |� � | |� n&| | D ]}t| |d |� q4� | |� d S r7 )r� r� r� �r9 r� rz rJ r8 r: � __delitem__� s z:_list_decorators.<locals>.__delitem__.<locals>.__delitem__r8 �rK r� r� rJ r: r� � s z%_list_decorators.<locals>.__delitem__c s dd� }� |� |S )Nc S s t |�D ]}| �|� qd S r7 �r� r� �r9 �iterabler� r8 r8 r: �extend� s z0_list_decorators.<locals>.extend.<locals>.extendr8 )rK r r� r8 r: r � s z _list_decorators.<locals>.extendc s dd� }� |� |S )Nc S s t |�D ]}| �|� q| S r7 r r r8 r8 r: �__iadd__� s z4_list_decorators.<locals>.__iadd__.<locals>.__iadd__r8 )rK r r� r8 r: r � s z"_list_decorators.<locals>.__iadd__c s d� fdd� }�|� |S )N���c s$ t | � � | |�}t| |d |� |S r7 �r� r� r� rJ r8 r: r� � s z*_list_decorators.<locals>.pop.<locals>.pop)r r8 �rK r� r� rJ r: r� � s z _list_decorators.<locals>.popc s d� fdd� }�|� |S )Nr c s$ | D ]}t | |d |� q� | � d S r7 �r� r� rJ r8 r: �clear� s z._list_decorators.<locals>.clear.<locals>.clear)r r8 �rK r r� rJ r: r � s z _list_decorators.<locals>.clearr� ��locals�copyr� ) r� r� r� r� r� r r r� r �lr8 r� r: �_list_decoratorsi s , r c st dd� � � fdd�} � fdd�}� fdd�}� fd d �}� fd d �}� fd d�}� fdd�}t � �� }|�d� |S )zBTailored instrumentation wrappers for any dict-like mapping class.c S s d| _ tt| j�j| _d S r� )rN r� rv r= r_ rJ r8 r8 r: r� � s z _dict_decorators.<locals>._tidyc s d� fdd� }�|� |S )Nc s8 || v rt | | | ||� t| |||�}� | ||� d S r7 )r� r� )r9 rm r� r} rJ r8 r: r� � s z:_dict_decorators.<locals>.__setitem__.<locals>.__setitem__)Nr8 r� r� rJ r: r� � s z%_dict_decorators.<locals>.__setitem__c s d� fdd� }�|� |S )Nc s( || v rt | | | ||� � | |� d S r7 r )r9 rm r} rJ r8 r: r� s z:_dict_decorators.<locals>.__delitem__.<locals>.__delitem__)Nr8 r r� rJ r: r� s z%_dict_decorators.<locals>.__delitem__c s � fdd�}�|� |S )Nc s( | D ]}t | | | d |� q� | � d S r7 r )r9 rm rJ r8 r: r s z._dict_decorators.<locals>.clear.<locals>.clearr8 r r� rJ r: r s z _dict_decorators.<locals>.clearc s t f� fdd� }�|� |S )Nc sF t | � || v }|tu r$� | |�}n � | ||�}|rBt| |d |� |S r7 )r� r r� )r9 rm �defaultZ_to_delrz rJ r8 r: r� s z*_dict_decorators.<locals>.pop.<locals>.popr r r� rJ r: r� s z _dict_decorators.<locals>.popc s � fdd�}�|� |S )Nc s& t | � � | �}t| |d d d� |S )Nr r r� rJ r8 r: �popitem) s z2_dict_decorators.<locals>.popitem.<locals>.popitemr8 )rK r r� rJ r: r ( s z!_dict_decorators.<locals>.popitemc s ddd�}� |� |S )Nc S s> || vr| � ||� |S | �|�}||u r6t| |d � |S d S r7 )r� � __getitem__r� )r9 rm r r� r8 r8 r: r� 3 s z8_dict_decorators.<locals>.setdefault.<locals>.setdefault)Nr8 )rK r� r� r8 r: r� 2 s z$_dict_decorators.<locals>.setdefaultc s t fdd�}� |� |S )Nc [ s� |t ur�t|d�rXt|�D ]:}|| vs6| | || urD|| | |< qt| || d � qn8|D ]2\}}|| vsx| | |ur�|| |< q\t| |d � q\|D ]:}|| vs�| | || ur�|| | |< q�t| || d � q�d S )N�keys)r r� r� r� )r9 Z__otherr� rm r� r8 r8 r: �updateB s z0_dict_decorators.<locals>.update.<locals>.updater �rK r r� r8 r: r A s z _dict_decorators.<locals>.updater� r )r� r� r r� r r� r r r8 r� r: �_dict_decorators� s r r rj )r9 �objr6 c C s t |t| jf �S )zKAllow only set, frozenset and self.__class__-derived objects in binops.)r� �_set_binop_bases� __class__�r9 r r8 r8 r: �_set_binops_check_stricta s r c C s t |t| jf �p t�|�tkS )z5Allow anything set-like to participate in set binops.)r� r r r r� �setr r8 r8 r: �_set_binops_check_looseg s �r c s� dd� � � fdd�} � fdd�}� fdd�}� fd d �}� fd d �}� fd d�}� fdd�}� fdd�}� fdd�}� fdd�} � fdd�} � fdd�} � fdd �} t � �� } | �d � | S ) z9Tailored instrumentation wrappers for any set-like class.c S s d| _ tt| j�j| _d S r� )rN r� r r= r_ rJ r8 r8 r: r� r s z _set_decorators.<locals>._tidyc s d� fdd� }�|� |S )Nc s2 || vrt | ||t�}n t| ||� � | |� d S r7 )r� r r� r� rJ r8 r: �addw s z)_set_decorators.<locals>.add.<locals>.add)Nr8 )rK r r� rJ r: r v s z _set_decorators.<locals>.addc s d� fdd� }�|� |S )Nc s$ || v rt | ||t� � | |� d S r7 r� r� rJ r8 r: �discard� s z1_set_decorators.<locals>.discard.<locals>.discard)Nr8 )rK r r� rJ r: r � s z _set_decorators.<locals>.discardc s d� fdd� }�|� |S )Nc s$ || v rt | ||t� � | |� d S r7 r� r� rJ r8 r: r� � s z/_set_decorators.<locals>.remove.<locals>.remove)Nr8 r� r� rJ r: r� � s z _set_decorators.<locals>.removec s � fdd�}�|� |S )Nc s" t | � � | �}t| |d t� |S r7 )r� r� r r� rJ r8 r: r� � s z)_set_decorators.<locals>.pop.<locals>.popr8 r r� rJ r: r� � s z _set_decorators.<locals>.popc s dd� }� |� |S )Nc S s t | �D ]}| �|� qd S r7 )r� r� r� r8 r8 r: r � s z-_set_decorators.<locals>.clear.<locals>.clearr8 r r� r8 r: r � s z _set_decorators.<locals>.clearc s dd� }� |� |S )Nc S s |D ]}| � |� qd S r7 )r �r9 r� rz r8 r8 r: r � s z/_set_decorators.<locals>.update.<locals>.updater8 r r� r8 r: r � s z _set_decorators.<locals>.updatec s dd� }� |� |S )Nc S s& t | |�stS |D ]}| �|� q| S r7 )r �NotImplementedr r! r8 r8 r: �__ior__� s z1_set_decorators.<locals>.__ior__.<locals>.__ior__r8 )rK r# r� r8 r: r# � s z _set_decorators.<locals>.__ior__c s dd� }� |� |S )Nc S s |D ]}| � |� qd S r7 )r r! r8 r8 r: �difference_update� s zE_set_decorators.<locals>.difference_update.<locals>.difference_updater8 )rK r$ r� r8 r: r$ � s z*_set_decorators.<locals>.difference_updatec s dd� }� |� |S )Nc S s& t | |�stS |D ]}| �|� q| S r7 )r r" r r! r8 r8 r: �__isub__� s z3_set_decorators.<locals>.__isub__.<locals>.__isub__r8 )rK r% r� r8 r: r% � s z!_set_decorators.<locals>.__isub__c s dd� }� |� |S )Nc S sR | � |�t| � }}|| || }}|D ]}| �|� q*|D ]}| �|� q>d S r7 )r� r r� r �r9 �otherZwantZhaver� r rz r8 r8 r: �intersection_update� s zI_set_decorators.<locals>.intersection_update.<locals>.intersection_updater8 )rK r( r� r8 r: r( � s z,_set_decorators.<locals>.intersection_updatec s dd� }� |� |S )Nc S s` t | |�stS | �|�t| � }}|| || }}|D ]}| �|� q8|D ]}| �|� qL| S r7 )r r" r� r r� r r& r8 r8 r: �__iand__� s z3_set_decorators.<locals>.__iand__.<locals>.__iand__r8 )rK r) r� r8 r: r) � s z!_set_decorators.<locals>.__iand__c s dd� }� |� |S )Nc S sR | � |�t| � }}|| || }}|D ]}| �|� q*|D ]}| �|� q>d S r7 )�symmetric_differencer r� r r& r8 r8 r: �symmetric_difference_update� s zY_set_decorators.<locals>.symmetric_difference_update.<locals>.symmetric_difference_updater8 )rK r+ r� r8 r: r+ � s z4_set_decorators.<locals>.symmetric_difference_updatec s dd� }� |� |S )Nc S s` t | |�stS | �|�t| � }}|| || }}|D ]}| �|� q8|D ]}| �|� qL| S r7 )r r" r* r r� r r& r8 r8 r: �__ixor__� s z3_set_decorators.<locals>.__ixor__.<locals>.__ixor__r8 )rK r, r� r8 r: r, � s z!_set_decorators.<locals>.__ixor__r� r )r r r� r� r r r# r$ r% r( r) r+ r, r r8 r� r: �_set_decoratorso s" r- c @ s e Zd ZdZdS )�InstrumentedListz-An instrumented version of the built-in list.N�r= r> r? r_ r8 r8 r8 r: r. s r. c @ s e Zd ZdZdS )�InstrumentedSetz,An instrumented version of the built-in set.Nr/ r8 r8 r8 r: r0 s r0 c @ s e Zd ZdZdS )�InstrumentedDictz-An instrumented version of the built-in dict.Nr/ r8 r8 r8 r: r1 s r1 z/util.immutabledict[Any, _CollectionFactoryType]r� r� r� r� )rG rL rM r rM r� zMutil.immutabledict[Any, Tuple[Dict[str, str], Dict[str, Callable[..., Any]]]]r� c C s| ddl ma ddl ma ddl ma ddl ma ddl m a ddl ma ddl ma dd l ma tt � tt � tt� d S ) Nr r! r r r# )r( )r) )r* )r+ ) r( r" r r r$ r) r* r+ r� r. r0 )Zlclsr8 r8 r: �__goA s r2 )N)N)N)Zr_ � __future__r �operator� threading�typingr r r r r r r r r r r r r r r rn �baser � r r� r Zsql.baser Z util.compatr Z util.typingr � attributesr r r( r r r" r$ �stater% �__all__�Lockr� r� r- r/ r0 r1 r2 r4 r, r& r' � attrgetterr@ r� r� r� r� r� r� r� r� r� r� r� r� r r r � frozensetr r r r- r. r0 r1 Z immutabledictr� rv r� rF r� r2 r r8 r8 r8 r: �<module> s� c ? *0- > h #��� �� ���� sqlalchemy/orm/__pycache__/identity.cpython-39.pyc 0000644 00000021652 15125143220 0016176 0 ustar 00 a ��Jh!$ � @ s$ d dl mZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlm Z d d lm Z d d lm Z d d lm Z d d lm Z d d lmZ d dlZddlmZ ddlmZ e r�ddlmZ ddlmZ eded�Zeded�ZG dd� d�Z G dd� de �Z d d d d �d d!�Z dS )"� )� annotations)�Any)�cast)�Dict)�Iterable)�Iterator)�List)�NoReturn)�Optional)�Set)�Tuple)� TYPE_CHECKING)�TypeVarN� )�util� )�exc)�_IdentityKeyType)� InstanceState�_T)�bound�_Oc @ sl e Zd ZU ded< ded< ded< dd�d d �Zdd�d d �Zd d�dd�Zddd�dd�Zddd�dd�Zddd�dd�Z dd d�d d �Z dDdd d d!�d"d#�Z dd$d�d%d&�Z d'd�d(d)�Z d*d�d+d,�Zd-d$d�d.d/�Zddd�d0d1�Zddd�d2d3�Zdddd4�d5d6�Zddd�d7d8�Zddd�d9d:�Zdd�d;d<�Zdd�d=d>�Zddd�d?d@�ZdAd�dBdC�Zd S )E� IdentityMapzweakref.ref[IdentityMap]�_wrz Dict[_IdentityKeyType[Any], Any]�_dictzSet[InstanceState[Any]]� _modified�None��returnc C s i | _ t� | _t�| �| _d S �N)r �setr �weakref�refr ��self� r% �L/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/identity.py�__init__+ s zIdentityMap.__init__c C s t | _d S r )�_killed�_add_unpresentr# r% r% r& �_kill0 s zIdentityMap._kill�List[InstanceState[Any]]c C s t � �d S r ��NotImplementedErrorr# r% r% r& � all_states3 s zIdentityMap.all_states�InstanceState[Any]�bool��stater c C s t � �d S r r, �r$ r2 r% r% r& �contains_state6 s zIdentityMap.contains_state�_IdentityKeyType[Any]��keyr c C s t � �d S r r, �r$ r7 r% r% r& � __contains__9 s zIdentityMap.__contains__c C s t � �d S r r, r3 r% r% r& � safe_discard< s zIdentityMap.safe_discard�_IdentityKeyType[_O]r c C s t � �d S r r, r8 r% r% r& � __getitem__? s zIdentityMap.__getitem__N� Optional[_O]�r7 �defaultr c C s t � �d S r r, )r$ r7 r? r% r% r& �getB s zIdentityMap.get�Optional[InstanceState[_O]]c C s t � �d S r r, r8 r% r% r& �fast_get_stateG s zIdentityMap.fast_get_statez Iterable[_IdentityKeyType[Any]]c C s | j �� S r )r �keysr# r% r% r& rC L s zIdentityMap.keyszIterable[object]c C s t � �d S r r, r# r% r% r& �valuesO s zIdentityMap.values�InstanceState[_O]c C s t � �d S r r, r3 r% r% r& �replaceR s zIdentityMap.replacec C s t � �d S r r, r3 r% r% r& �addU s zIdentityMap.addc C s t � �d S r r, r3 r% r% r& � _fast_discardX s zIdentityMap._fast_discard�r2 r7 r c C s | � |� dS )zUoptional inlined form of add() which can assume item isn't present in the mapN)rG �r$ r2 r7 r% r% r& r) [ s zIdentityMap._add_unpresentc C s | j |_|jr| j�|� d S r )r �_instance_dict�modifiedr rG r3 r% r% r& �_manage_incoming_stateb s z"IdentityMap._manage_incoming_statec C s |` |jr| j�|� d S r )rK rL r �discardr3 r% r% r& �_manage_removed_stateh s z!IdentityMap._manage_removed_statec C s | j S r )r r# r% r% r& � _dirty_statesm s zIdentityMap._dirty_statesc C s t | j�S )z[return True if any InstanceStates present have been marked as 'modified'. )r0 r r# r% r% r& �check_modifiedp s zIdentityMap.check_modifiedc C s || v S r r% r8 r% r% r& �has_keyw s zIdentityMap.has_key�intc C s t | j�S r )�lenr r# r% r% r& �__len__z s zIdentityMap.__len__)N)�__name__� __module__� __qualname__�__annotations__r' r* r. r4 r9 r: r< r@ rB rC rD rF rG rH r) rM rO rP rQ rR rU r% r% r% r& r % s2 �r c @ s e Zd ZU ded< ddd�dd�Zdd d�d d �Zd d d �dd�Zd dd �dd�Zd d d �dd�Zd ddd�dd�Z ddd�dd�Z d4dd d d �d d �Z d!d"�d#d$�Z d%d"�d&d'�Z d(d"�d)d*�Zd+d"�d,d-�Zd dd �d.d/�Zd dd �d0d1�Zd dd �d2d3�Zd S )5�WeakInstanceDictz/Dict[_IdentityKeyType[Any], InstanceState[Any]]r r; r r6 c C s, t d| j| �}|�� }|d u r(t|��|S �NrE )r r �obj�KeyError�r$ r7 r2 �or% r% r& r< � s z WeakInstanceDict.__getitem__r5 r0 c C sJ z(|| j v r | j | }|�� }nW dS W n ty< Y dS 0 |d uS d S �NF)r r\ r] r^ r% r% r& r9 � s z WeakInstanceDict.__contains__r/ r1 c C sP |j | jv rHtr |j d us J �z| j|j |u W S tyD Y dS 0 ndS d S r` )r7 r r r] r3 r% r% r& r4 � s z WeakInstanceDict.contains_statez Optional[InstanceState[Any]]c C s~ |j d usJ �|j | jv r`z| j|j }}W n tyD d }Y qd0 ||urZ| �|� qdd S nd }|| j|j < | �|� |S r )r7 r r] rO rM )r$ r2 �existingZexisting_non_noner% r% r& rF � s zWeakInstanceDict.replacec C s� |j }|d usJ �|| jv rvz| j| }W n ty< Y n:0 ||urr|�� }|d urvt�dt�|�|j f ��ndS || j|< | �|� dS )NzZCan't attach instance %s; another instance with key %s is already present in this session.FT) r7 r r] r\ �sa_exc�InvalidRequestError�orm_util� state_strrM )r$ r2 r7 Zexisting_stater_ r% r% r& rG � s& �� zWeakInstanceDict.addr rI c C s || j |< | j|_d S r )r r rK rJ r% r% r& r) � s z WeakInstanceDict._add_unpresentrA c C s | j �|�S r )r r@ r8 r% r% r& rB � s z WeakInstanceDict.fast_get_stateNr= r> c C sV || j vr|S ztd| j | �}W n ty8 | Y S 0 |�� }|d u rN|S |S d S r[ )r r r] r\ )r$ r7 r? r2 r_ r% r% r& r@ � s zWeakInstanceDict.getz6List[Tuple[_IdentityKeyType[Any], InstanceState[Any]]]r c C sJ | � � }g }|D ]4}|�� }|j}|d us.J �|d ur|�||f� q|S r )r. r\ r7 �append)r$ rD �resultr2 �valuer7 r% r% r& �items� s zWeakInstanceDict.itemsz List[object]c C s4 | � � }g }|D ] }|�� }|d ur|�|� q|S r )r. r\ rf )r$ rD rg r2 rh r% r% r& rD � s zWeakInstanceDict.valuesz Iterator[_IdentityKeyType[Any]]c C s t | �� �S r )�iterrC r# r% r% r& �__iter__ s zWeakInstanceDict.__iter__r+ c C s t | j�� �S r )�listr rD r# r% r% r& r. s zWeakInstanceDict.all_statesc C sN |j }|d usJ �z| j| }W n ty2 Y n0 ||u rJ| j�|d � d S r )r7 r r] �pop�r$ r2 r7 �str% r% r& rH s z WeakInstanceDict._fast_discardc C s | � |� d S r )r: r3 r% r% r& rN s zWeakInstanceDict.discardc C sb |j }|| jv r^|d us J �z| j| }W n ty< Y n"0 ||u r^| j�|d � | �|� d S r )r7 r r] rm rO rn r% r% r& r: s z WeakInstanceDict.safe_discard)N)rV rW rX rY r< r9 r4 rF rG r) rB r@ ri rD rk r. rH rN r: r% r% r% r& rZ ~ s" � rZ r/ r5 r rI c C s t jdt�| � dd��d S )Nz�Object %s cannot be converted to 'persistent' state, as this identity map is no longer valid. Has the owning Session been closed?Zlkrp)�code)rb rc rd re )r2 r7 r% r% r& r( & s ��r( ) � __future__r �typingr r r r r r r r r r r r r! � r rd r rb Z_typingr r2 r r �objectr r rZ r( r% r% r% r& �<module> s0 Y ) sqlalchemy/orm/__pycache__/session.cpython-39.pyc 0000644 00000457164 15125143220 0016043 0 ustar 00 a ��Jh&� � @ s8 U d Z ddlmZ ddlZddlmZ ddlZddlZddlZddlm Z ddlm Z ddlm Z ddlm Z dd lm Z dd lmZ dd lmZ dd lmZ dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlZddl m Z ddl m Z ddl m Z ddl m Z dd l m!Z! dd l m"Z" dd l m#Z# dd l m$Z$ dd l m%Z& dd!l'm(Z( dd"l'm)Z) dd#l'm*Z* dd$l'm+Z+ dd%l'm,Z, dd&l-m.Z. dd'l-m/Z/ dd(l-m0Z0 dd)l-m1Z1 dd*l-m2Z2 dd+l-m3Z3 dd,l-m4Z4 dd-l-m5Z5 dd.l-m6Z6 dd/l m7Z7 dd0l m8Z8 dd1l"m9Z9 dd2l$m:Z: dd3l%m;Z; dd4l<m=Z= dd5l<m>Z> dd6l<m?Z? dd7l@mAZA d8d9l mBZB d8d l m!ZC d8d:l mDZD d8d;l mEZE d8d<lBmFZF d8d=lBmGZG d8d>lHmIZI d8d?lJmKZK d8d@lJmLZL d8dAlMmNZN d8dBlMmOZO d8dClDmPZP d8dDlDmQZQ d8dElDmRZR d8dFlDmSZS d8dGlDmTZT d8dHlDmUZU d8dIlVmWZW d8dJlVmXZX d8dKlYmZZZ d8dLl[m\Z\ d8dMl[m]Z] d8dNlEm^Z^ d8dOl_m`Z` d8dPl_maZa ej�r�ddQl'mbZb ddRl'mcZc ddSl'mdZd ddTl'meZe ddUlfmgZg ddVlfmhZh ddWlimjZj ddXlkmlZl ddYl$mmZm d8dZlBmnZn d8d[lBmoZo d8d\lBmpZp d8d]lBmqZq d8d^lrmsZs d8d_lrmtZt d8d`lumvZv d8dalumwZw d8dblumxZx d8dclumyZy d8ddlzm{Z{ d8delJm|Z| d8dfl}m~Z~ d8dgl}mZ d8dhl}m�Z� d8dil}m�Z� d8djl}m�Z� d8dkl}m�Z� d8dll}m�Z� d8dml}m�Z� d8dnl}m�Z� d8dol}m�Z� d8dpl}m�Z� d8dqlVm�Z� d8drlVm�Z� d8dsl�m�Z� d8dtl�m�Z� d8dul�m�Z� d8dvl[m�Z� d8dwl[m�Z� edxe dy�Z�g dz�Z�e��� Z�d{e�d|< e�e&_�ee ee d}f f Z�e e�e f Z�eee( d~f Z�eee dd�e�f Z�ed� Z�e`d� Z�G d�d�� d�ea�Z�d�d�d��d�d��Z�G d�d�� d��Z�G d�d�� d�e>�Z�e�e��\Z�Z�Z�Z�Z�Z�G d�d�� d�eEj��Z�G d�d�� d�e�Z�G d�d�� d�e=eI�Z�G d�d�� d�e�Z�G d�d�� d�e�eL�Z�ed�d�dy�Z�G d�d�� d�e�e e� �Z�d�d��d�d��Z�d�d�d��d�d��Z�d�d�d��d�d��Z�d�d�d��d�d��Z�eE��� Z�dS )�z1Provides the Session class and related utilities.� )� annotationsN)�Enum)�Any)�Callable)�cast)�Dict)�Generic)�Iterable)�Iterator)�List)�NoReturn)�Optional)�overload)�Sequence)�Set)�Tuple)�Type)� TYPE_CHECKING)�TypeVar)�Union� )� attributes)�bulk_persistence)�context)�descriptor_props)�exc)�identity)�loading)�query��state)�_O)�insp_is_mapper)�is_composite_class)� is_orm_option��is_user_defined_option)�_class_to_mapper)� _none_set)� _state_mapper)� instance_str)�LoaderCallableStatus)� object_mapper)� object_state)� PassiveFlag)� state_str)� FromStatement)�ORMCompileState)� IdentityMap)�Query)� InstanceState)� _StateChange)�_StateChangeState)�_StateChangeStates)�UOWTransaction� )�engine)�sql)�util)� Connection)�Engine)�TransactionalContext)� dispatcher)� EventTarget)�inspect)� Inspectable)� coercions)�dml)�roles)�Select)� TableClause)�visitors)�_NoArg)� CompileState)�Table)� ForUpdateArg)� LABEL_STYLE_TABLENAME_PLUS_COL)� IdentitySet)�Literal)�Protocol)� _EntityType)�_IdentityKeyType)� _InstanceDict)�OrmExecuteOptionsParameter)� ORMOption)�UserDefinedOption)�Mapper)� PathRegistry)�RowReturningQuery)� CursorResult)�Result)�Row)� RowMapping)� Transaction)�TwoPhaseTransaction)�_CoreAnyExecuteParams)�_CoreSingleExecuteParams)�_ExecuteOptions)�CoreExecuteOptionsParameter)� ScalarResult)�_InstanceLevelDispatch)�_ColumnsClauseArgument)� _InfoType)�_T0)�_T1)�_T2)�_T3)�_T4)�_T5)�_T6)�_T7)�_TypedColumnClauseArgument)� Executable)�ExecutableOption)� UpdateBase)� ClauseElement)�TypedColumnsClauseRole)�ForUpdateParameter)�TypedReturnsRows�_T)�bound)�Session�SessionTransaction� sessionmaker�ORMExecuteState�close_all_sessions�make_transient�make_transient_to_detached�object_sessionz)weakref.WeakValueDictionary[int, Session]� _sessions.� Mapper[_O]� Mapper[Any]rH )r> r= )�conditional_savepoint� rollback_only� control_fully�create_savepointc @ s& e Zd ZdZd ddddd�dd �ZdS ) �_ConnectionCallableProtoa� a callable that returns a :class:`.Connection` given an instance. This callable, when present on a :class:`.Session`, is called only from the ORM's persistence mechanism (i.e. the unit of work flush process) to allow for connection-per-instance schemes (i.e. horizontal sharding) to be used as persistence time. This callable is not present on a plain :class:`.Session`, however is established when using the horizontal sharding extension. N�Optional[Mapper[Any]]zOptional[object]r r= )�mapper�instance�kw�returnc K s d S �N� )�selfr� r� r� r� r� �K/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/orm/session.py�__call__� s z!_ConnectionCallableProto.__call__)NN)�__name__� __module__� __qualname__�__doc__r� r� r� r� r� r� � s �r� �InstanceState[Any]�Optional[Session]�r r� c C s | j S )z[Given an :class:`.InstanceState`, return the :class:`.Session` associated, if any. ��sessionr r� r� r� �_state_session� s r� c @ st e Zd ZdZee�dd�dd�dd���Zee�d�dd d d d �d d d dd dd�dd���Z eddd�dd��Z d S )�_SessionClassMethodszBClass-level methods for :class:`.Session`, :class:`.sessionmaker`.z1.3z�The :meth:`.Session.close_all` method is deprecated and will be removed in a future release. Please refer to :func:`.session.close_all_sessions`.�None�r� c C s t � dS )z Close *all* sessions in memory.N)r )�clsr� r� r� � close_all� s z _SessionClassMethods.close_allzsqlalchemy.orm.utilN�r� �row�identity_tokenzOptional[Type[Any]]�Union[Any, Tuple[Any, ...]]� Optional[Any]z%Optional[Union[Row[Any], RowMapping]]z_IdentityKeyType[Any])�class_�identr� r� r� r� c C s t jjj|||||d�S )zZReturn an identity key. This is an alias of :func:`.util.identity_key`. r� )r< Z preloadedZorm_util� identity_key)r� r� r� r� r� r� r� r� r� r� � s �z!_SessionClassMethods.identity_key�objectr� �r� r� c C s t |�S )zxReturn the :class:`.Session` to which an object belongs. This is an alias of :func:`.object_session`. )r� )r� r� r� r� r� r� � s z#_SessionClassMethods.object_session)NN) r� r� r� r� � classmethodr< � deprecatedr� Zpreload_moduler� r� r� r� r� r� r� � s$ � �� r� c @ s$ e Zd ZdZdZdZdZdZdZdS )�SessionTransactionStater r9 � � � � N) r� r� r� �ACTIVE�PREPARED� COMMITTED�DEACTIVE�CLOSED�PROVISIONING_CONNECTIONr� r� r� r� r� � s r� c @ s e Zd ZU dZdZded< ded< ded< d ed < d ed < d ed < ded< ded< ded< ded< dddd d ddd�dd�Zdd�dd �ZdZd dd d d!d"�d#d$�Ze d%d�d&d'��Z e d(d�d)d*��Z e d+d�d,d-��Z e d+d�d.d/��Z e d+d�d0d1��Ze d+d�d2d3��Ze d+d�d4d5��Ze d+d�d6d7��Ze d+d�d8d9��Ze d+d�d:d;��Zd<d=d>�d?d@�ZdAd�dBdC�Ze dDd�dEdF��Ze dGd�dHdI��Ze d+d�dJdK��Ze d+d�dLdM��Ze dNd�dOdP��Ze dQd�dRdS��Ze dTd�dUdV��Z e dWd�dXdY��Z d S )[r~ a8 Represents a call to the :meth:`_orm.Session.execute` method, as passed to the :meth:`.SessionEvents.do_orm_execute` event hook. .. versionadded:: 1.4 .. seealso:: :ref:`session_execute_events` - top level documentation on how to use :meth:`_orm.SessionEvents.do_orm_execute` ) r� � statement� parameters�execution_options�local_execution_options�bind_argumentsr� �_compile_state_cls�_starting_event_idx� _events_todo�_update_execution_optionsr{ r� rr r� � Optional[_CoreAnyExecuteParams]r� rc r� r� �_BindArgumentsr� z Optional[Type[ORMCompileState]]r� �intr� z List[Any]r� �Optional[_ExecuteOptions]r� z%List[_InstanceLevelDispatch[Session]])r� r� r� r� r� �compile_state_cls� events_todoc C s@ || _ || _|| _|| _|j�|�| _|| _|| _t |�| _ dS )zhConstruct a new :class:`_orm.ORMExecuteState`. this object is constructed internally. N) r� r� r� r� �_execution_options�unionr� r� r� �listr� )r� r� r� r� r� r� r� r� r� r� r� �__init__` s �zORMExecuteState.__init__r� c C s | j | jd d � S )Nr )r� r� �r� r� r� r� �_remaining_eventsz s z!ORMExecuteState._remaining_eventsNzOptional[Executable]z$Optional[OrmExecuteOptionsParameter]�Optional[_BindArguments]� Result[Any])r� �paramsr� r� r� c C s |du r| j }t| j�}|r&|�|� d|d< |r�| jr�g }td| j�}t�|td|��D ]T\}} |du sr| du r�t � dt |�� dt |�� d���t|�}|�| � |� |� qZq�ttd| j��}|�td|�� n| j}| j } |r�| �|�} | jj||| || d �S ) a� Execute the statement represented by this :class:`.ORMExecuteState`, without re-invoking events that have already proceeded. This method essentially performs a re-entrant execution of the current statement for which the :meth:`.SessionEvents.do_orm_execute` event is being currently invoked. The use case for this is for event handlers that want to override how the ultimate :class:`_engine.Result` object is returned, such as for schemes that retrieve results from an offline cache or which concatenate results from multiple executions. When the :class:`_engine.Result` object is returned by the actual handler function within :meth:`_orm.SessionEvents.do_orm_execute` and is propagated to the calling :meth:`_orm.Session.execute` method, the remainder of the :meth:`_orm.Session.execute` method is preempted and the :class:`_engine.Result` object is returned to the caller of :meth:`_orm.Session.execute` immediately. :param statement: optional statement to be invoked, in place of the statement currently represented by :attr:`.ORMExecuteState.statement`. :param params: optional dictionary of parameters or list of parameters which will be merged into the existing :attr:`.ORMExecuteState.parameters` of this :class:`.ORMExecuteState`. .. versionchanged:: 2.0 a list of parameter dictionaries is accepted for executemany executions. :param execution_options: optional dictionary of execution options will be merged into the existing :attr:`.ORMExecuteState.execution_options` of this :class:`.ORMExecuteState`. :param bind_arguments: optional dictionary of bind_arguments which will be merged amongst the current :attr:`.ORMExecuteState.bind_arguments` of this :class:`.ORMExecuteState`. :return: a :class:`_engine.Result` object with ORM-level results. .. seealso:: :ref:`do_orm_execute_re_executing` - background and examples on the appropriate usage of :meth:`_orm.ORMExecuteState.invoke_statement`. NT�_sa_skip_eventszList[Dict[str, Any]]zgCan't apply executemany parameters to statement; number of parameter sets passed to Session.execute() (zW) does not match number of parameter sets given to ORMExecuteState.invoke_statement() (�)zDict[str, Any])r� r� �_parent_execute_state)r� �dictr� �update�is_executemanyr r� � itertools� zip_longest�sa_exc�InvalidRequestError�len�appendr� r� r� �_execute_internal) r� r� r� r� r� Z_bind_arguments�_paramsZexec_many_parametersZ_existing_paramsZ _new_paramsr� r� r� r� �invoke_statement} sP 9 �� ��� �z ORMExecuteState.invoke_statementr� c C s | j �dd�}|S )a� Return the :class:`_orm.Mapper` that is the primary "bind" mapper. For an :class:`_orm.ORMExecuteState` object invoking an ORM statement, that is, the :attr:`_orm.ORMExecuteState.is_orm_statement` attribute is ``True``, this attribute will return the :class:`_orm.Mapper` that is considered to be the "primary" mapper of the statement. The term "bind mapper" refers to the fact that a :class:`_orm.Session` object may be "bound" to multiple :class:`_engine.Engine` objects keyed to mapped classes, and the "bind mapper" determines which of those :class:`_engine.Engine` objects would be selected. For a statement that is invoked against a single mapped class, :attr:`_orm.ORMExecuteState.bind_mapper` is intended to be a reliable way of getting this mapper. .. versionadded:: 1.4.0b2 .. seealso:: :attr:`_orm.ORMExecuteState.all_mappers` r� N)r� �get)r� �mpr� r� r� � bind_mapper� s zORMExecuteState.bind_mapperzSequence[Mapper[Any]]c C s� | j s g S t| jttf�rzg }t� }| jjD ]H}|d }|r,t|dd�}|r,|jr,|j|vr,|� |j� |� |j� q,|S | jj r�| j r�| j gS g S dS )a Return a sequence of all :class:`_orm.Mapper` objects that are involved at the top level of this statement. By "top level" we mean those :class:`_orm.Mapper` objects that would be represented in the result set rows for a :func:`_sql.select` query, or for a :func:`_dml.update` or :func:`_dml.delete` query, the mapper that is the main subject of the UPDATE or DELETE. .. versionadded:: 1.4.0b2 .. seealso:: :attr:`_orm.ORMExecuteState.bind_mapper` �entityF)ZraiseerrN) �is_orm_statement� isinstancer� rG r0 �setZcolumn_descriptionsrB r� �addr� �is_dmlr� )r� �result�seen�d�ent�inspr� r� r� � all_mappers s zORMExecuteState.all_mappers�boolc C s | j duS )a� return True if the operation is an ORM statement. This indicates that the select(), insert(), update(), or delete() being invoked contains ORM entities as subjects. For a statement that does not have ORM entities and instead refers only to :class:`.Table` metadata, it is invoked as a Core SQL statement and no ORM-level automation takes place. N)r� r� r� r� r� r� ) s z ORMExecuteState.is_orm_statementc C s t | jt�S )z�return True if the parameters are a multi-element list of dictionaries with more than one dictionary. .. versionadded:: 2.0 )r� r� r� r� r� r� r� r� 6 s z ORMExecuteState.is_executemanyc C s | j jS )a8 return True if this is a SELECT operation. .. versionchanged:: 2.0.30 - the attribute is also True for a :meth:`_sql.Select.from_statement` construct that is itself against a :class:`_sql.Select` construct, such as ``select(Entity).from_statement(select(..))`` )r� � is_selectr� r� r� r� r� @ s zORMExecuteState.is_selectc C s | j jS )a return True if this operation is a :meth:`_sql.Select.from_statement` operation. This is independent from :attr:`_orm.ORMExecuteState.is_select`, as a ``select().from_statement()`` construct can be used with INSERT/UPDATE/DELETE RETURNING types of statements as well. :attr:`_orm.ORMExecuteState.is_select` will only be set if the :meth:`_sql.Select.from_statement` is itself against a :class:`_sql.Select` construct. .. versionadded:: 2.0.30 )r� �is_from_statementr� r� r� r� r� L s z!ORMExecuteState.is_from_statementc C s | j jo| j jS )a9 return True if this is an INSERT operation. .. versionchanged:: 2.0.30 - the attribute is also True for a :meth:`_sql.Select.from_statement` construct that is itself against a :class:`_sql.Insert` construct, such as ``select(Entity).from_statement(insert(..))`` )r� r� � is_insertr� r� r� r� r� ] s zORMExecuteState.is_insertc C s | j jo| j jS )a9 return True if this is an UPDATE operation. .. versionchanged:: 2.0.30 - the attribute is also True for a :meth:`_sql.Select.from_statement` construct that is itself against a :class:`_sql.Update` construct, such as ``select(Entity).from_statement(update(..))`` )r� r� � is_updater� r� r� r� r� i s zORMExecuteState.is_updatec C s | j jo| j jS )a8 return True if this is a DELETE operation. .. versionchanged:: 2.0.30 - the attribute is also True for a :meth:`_sql.Select.from_statement` construct that is itself against a :class:`_sql.Delete` construct, such as ``select(Entity).from_statement(delete(..))`` )r� r� � is_deleter� r� r� r� r� u s zORMExecuteState.is_deletec C s t | jtjtjf�S r� )r� r� rE ZUpdate�Deleter� r� r� r� �_is_crud� s zORMExecuteState._is_crudr r� )�optsr� c K s | j �|�| _ dS )z3Update the local execution options with new values.N)r� r� �r� r� r� r� r� �update_execution_options� s z(ORMExecuteState.update_execution_optionszwOptional[Union[context.ORMCompileState.default_compile_options, Type[context.ORMCompileState.default_compile_options]]]c C sN | j s d S z | jj}W n ty* Y d S 0 |d urF|�tjj�rF|S d S d S r� )r� r� Z_compile_options�AttributeErrorr� r r1 Zdefault_compile_optionsr� r� r� r� �_orm_compile_options� s �z$ORMExecuteState._orm_compile_options� Optional[InstanceState[Any]]c C s | j jS )a� An :class:`.InstanceState` that is using this statement execution for a lazy load operation. The primary rationale for this attribute is to support the horizontal sharding extension, where it is available within specific query execution time hooks created by this extension. To that end, the attribute is only intended to be meaningful at **query execution time**, and importantly not any time prior to that, including query compilation time. )� load_optionsZ_lazy_loaded_fromr� r� r� r� �lazy_loaded_from� s z ORMExecuteState.lazy_loaded_fromzOptional[PathRegistry]c C s | � � }|dur|jS dS dS )z�Return the :class:`.PathRegistry` for the current load path. This object represents the "path" in a query along relationships when a particular object or collection is being loaded. N)r� Z _current_pathr� r� r� r� �loader_strategy_path� s z$ORMExecuteState.loader_strategy_pathc C s | � � }|duo|jS )aq Return True if the operation is refreshing column-oriented attributes on an existing ORM object. This occurs during operations such as :meth:`_orm.Session.refresh`, as well as when an attribute deferred by :func:`_orm.defer` is being loaded, or an attribute that was expired either directly by :meth:`_orm.Session.expire` or via a commit operation is being loaded. Handlers will very likely not want to add any options to queries when such an operation is occurring as the query should be a straight primary key fetch which should not have any additional WHERE criteria, and loader options travelling with the instance will have already been added to the query. .. versionadded:: 1.4.0b2 .. seealso:: :attr:`_orm.ORMExecuteState.is_relationship_load` N)r� Z_for_refresh_stater� r� r� r� �is_column_load� s z ORMExecuteState.is_column_loadc C s* | � � }|du rdS | j}|duo(|j S )az Return True if this load is loading objects on behalf of a relationship. This means, the loader in effect is either a LazyLoader, SelectInLoader, SubqueryLoader, or similar, and the entire SELECT statement being emitted is on behalf of a relationship load. Handlers will very likely not want to add any options to queries when such an operation is occurring, as loader options are already capable of being propagated to relationship loaders and should be already present. .. seealso:: :attr:`_orm.ORMExecuteState.is_column_load` NF)r� r Zis_root)r� r� �pathr� r� r� �is_relationship_load� s z$ORMExecuteState.is_relationship_loadzaUnion[context.QueryContext.default_load_options, Type[context.QueryContext.default_load_options]]c C s& | j st�d��| j�dtjj�}|S )z=Return the load_options that will be used for this execution.zRThis ORM execution is not against a SELECT statement so there are no load options.Z_sa_orm_load_options)r� r� r� r� r� r � QueryContext�default_load_options)r� �lor� r� r� r� � s ���z ORMExecuteState.load_optionsz�Union[bulk_persistence.BulkUDCompileState.default_update_options, Type[bulk_persistence.BulkUDCompileState.default_update_options]]c C s& | j st�d��| j�dtjj�}|S )zNReturn the update_delete_options that will be used for this execution.z_This ORM execution is not against an UPDATE or DELETE statement so there are no update options.Z_sa_orm_update_options)r� r� r� r� r� r ZBulkUDCompileStateZdefault_update_options)r� Zuor� r� r� �update_delete_options s ���z%ORMExecuteState.update_delete_optionszSequence[ORMOption]c C s dd� | j jD �S )Nc S s g | ]}t |�r|js|�qS r� )r$ Z_is_compile_state��.0�optr� r� r� � <listcomp>" s �z<ORMExecuteState._non_compile_orm_options.<locals>.<listcomp>�r� Z _with_optionsr� r� r� r� �_non_compile_orm_options s �z(ORMExecuteState._non_compile_orm_optionszSequence[UserDefinedOption]c C s dd� | j jD �S )zzThe sequence of :class:`.UserDefinedOptions` that have been associated with the statement being invoked. c S s g | ]}t |�r|�qS r� r% r r� r� r� r . s �z8ORMExecuteState.user_defined_options.<locals>.<listcomp>r r� r� r� r� �user_defined_options( s �z$ORMExecuteState.user_defined_options)NNNN) r� r� r� r� � __slots__�__annotations__r� r� r� �propertyr� r� r� r� r� r� r� r� r� r� r� r� r r r r r� r r r r� r� r� r� r~ sr �j $ r~ c @ s e Zd ZdZdZdZdZdZdS )�SessionTransactionOriginz�indicates the origin of a :class:`.SessionTransaction`. This enumeration is present on the :attr:`.SessionTransaction.origin` attribute of any :class:`.SessionTransaction` object. .. versionadded:: 2.0 r r r9 r� N)r� r� r� r� � AUTOBEGIN�BEGIN� BEGIN_NESTED�SUBTRANSACTIONr� r� r� r� r 5 s r c @ s\ e Zd ZU dZdZded< ded< ded< d ed < d ed < d ed< d ed< d ed< ded< ded< dZded< dXddd d�dd�Zdd d d �d d �Ze d d!�d"d#��Z e dd!�d$d%��Z e dd!�d&d'��Z e �ejfej�dYd(d)d*d+d,�d-d.��Ze �ejfej�dZdd d/�d0d1��Zd[d d2d3�d4d5�Zd6d!�d7d8�Zd\dd6d9�d:d;�Zd6d!�d<d=�Ze �ejfej�d>d?d+d@�dAdB��Zd6d!�dCdD�Ze �ejfej�d6d!�dEdF��Z e �ejejfej �d]dd6dG�dHdI��Z e �ejej ejfej �d^ddd6dJ�dKdL��Z e �ej!ej �d_dd6dM�dNdO��Z"dd!�dPdQ�Z#dd!�dRdS�Z$dd!�dTdU�Z%dd!�dVdW�Z&dS )`r| a� A :class:`.Session`-level transaction. :class:`.SessionTransaction` is produced from the :meth:`_orm.Session.begin` and :meth:`_orm.Session.begin_nested` methods. It's largely an internal object that in modern use provides a context manager for session transactions. Documentation on interacting with :class:`_orm.SessionTransaction` is at: :ref:`unitofwork_transaction`. .. versionchanged:: 1.4 The scoping and API methods to work with the :class:`_orm.SessionTransaction` object directly have been simplified. .. seealso:: :ref:`unitofwork_transaction` :meth:`.Session.begin` :meth:`.Session.begin_nested` :meth:`.Session.rollback` :meth:`.Session.commit` :meth:`.Session.in_transaction` :meth:`.Session.in_nested_transaction` :meth:`.Session.get_transaction` :meth:`.Session.get_nested_transaction` NzOptional[BaseException]�_rollback_exceptionzKDict[Union[Engine, Connection], Tuple[Connection, Transaction, bool, bool]]� _connectionsr{ r� � Optional[SessionTransaction]�_parentr� �_statez5weakref.WeakKeyDictionary[InstanceState[Any], object]�_new�_deleted�_dirtyz>weakref.WeakKeyDictionary[InstanceState[Any], Tuple[Any, Any]]� _key_switchesr �originFr� �nested)r� r! �parentc C s� t �|� || _i | _|| _|tju | _}|| _|j t j u rHt � d��|rd|sZt � d��|j| _n$|tju r||d us�J �n |d u s�J �tj| _| �� | | j_| jj�| j| � d S )Nz_This Session has been permanently closed and is unable to handle any more transaction requests.zOCan't start a SAVEPOINT transaction when no existing transaction is in progress)r? �_trans_ctx_checkr� r r r r r" r! � _close_state�_SessionCloseStater� r� r� �_nested_transaction� _previous_nested_transactionr r� r� r �_take_snapshot� _transaction�dispatchZafter_transaction_create)r� r� r! r# r" r� r� r� r� � s. �� zSessionTransaction.__init__�strr6 r )�operation_namer r� c C s� |t ju r4| jr(tjd| j� �dd��q|t�d��nH|t ju rJt�d��n2|t ju rdtjddd��nt�d|j � � � d ���d S ) Nz�This Session's transaction has been rolled back due to a previous exception during flush. To begin a new transaction with this Session, first issue Session.rollback(). Original exception was: Z7s2a)�codez�This session is in 'inactive' state, due to the SQL transaction being rolled back; no further SQL can be emitted within this transaction.zThis transaction is closedzVThis session is provisioning a new connection; concurrent operations are not permittedZiscezThis session is in 'z?' state; no further SQL can be emitted within this transaction.) r� r� r r� ZPendingRollbackErrorr� r� ZResourceClosedErrorr� �name�lower)r� r- r r� r� r� � _raise_for_prerequisite_state� s* �� � ��z0SessionTransaction._raise_for_prerequisite_stater� c C s | j S )aa The parent :class:`.SessionTransaction` of this :class:`.SessionTransaction`. If this attribute is ``None``, indicates this :class:`.SessionTransaction` is at the top of the stack, and corresponds to a real "COMMIT"/"ROLLBACK" block. If non-``None``, then this is either a "subtransaction" (an internal marker object used by the flush process) or a "nested" / SAVEPOINT transaction. If the :attr:`.SessionTransaction.nested` attribute is ``True``, then this is a SAVEPOINT, and if ``False``, indicates this a subtransaction. )r r� r� r� r� r# � s zSessionTransaction.parentc C s | j d uo| jtju S r� )r� r r� r� r� r� r� r� � is_active� s �z SessionTransaction.is_activec C s | j p | j S r� )r" r r� r� r� r� �_is_transaction_boundary s z+SessionTransaction._is_transaction_boundaryr� r� r r= )�bindkeyr� �kwargsr� c K s | j j|fi |��}| �||�S r� )r� �get_bind�_connection_for_bind)r� r4 r� r5 �bindr� r� r� � connection s z SessionTransaction.connection�r" r� c C s t | j|rtjntj| �S r� )r| r� r r r )r� r" r� r� r� �_begin s ��zSessionTransaction._beginz Iterable[SessionTransaction])�uptor� c C sJ | }d}|rF||f7 }|j |u r$qFq|j d u r>t�d| ��q|j }q|S )Nr� z4Transaction %s is not on the active transaction list)r r� r� )r� r< �currentr� r� r� r� �_iterate_self_and_parents s ��z,SessionTransaction._iterate_self_and_parentsr� c C s� | j s<| j}|d usJ �|j| _|j| _|j| _|j| _d S | jtjtj fv }|sd| j j sd| j � � t �� | _t �� | _t �� | _t �� | _d S r� )r3 r r r r r r! r r r r� � _flushing�flush�weakref�WeakKeyDictionary)r� r# Zis_beginr� r� r� r) 2 s$ � z!SessionTransaction._take_snapshot)� dirty_onlyr� c C s� | j s J �t| j��| jj�}| jj|dd� | j�� D ]6\}\}}| jj� |� ||_ ||vr8| jj� |� q8t| j ��| jj �D ]}| jj |dd� q�| jj r�J �| jj�� D ],}|r�|js�|| jv r�|�|j| jjj� q�dS )zmRestore the restoration state taken before a transaction began. Corresponds to a rollback. T�� to_transient)�revert_deletionN)r3 r� r r� r� �_expunge_statesr �items� identity_map� safe_discard�key�replacer � _update_impl� all_states�modifiedr �_expirer� � _modified)r� rC Z to_expunge�sZoldkeyZnewkeyr� r� r� �_restore_snapshotH s z$SessionTransaction._restore_snapshotc C s� | j s J �| js`| jjr`| jj�� D ]}|�|j| jjj� q$t j � t | j �| j� | j �� nP| jr�| j}|dusxJ �|j�| j� |j�| j� |j �| j � |j�| j� dS )zjRemove the restoration state taken before a transaction began. Corresponds to a commit. N)r3 r" r� �expire_on_commitrI rN rP r� rQ �statelibr4 �_detach_statesr� r �clearr r r� r r )r� rR r# r� r� r� �_remove_snapshoth s � z#SessionTransaction._remove_snapshot� _SessionBind�%Optional[CoreExecuteOptionsParameter])r8 r� r� c C s || j v r&|rt�d� | j | d S tj| _d}d}�z�| jrd| j�||�}| js�|W tj | _S n4t |t j �r�|}|j | j v r�t �d��n |�� }d}z�|r�|jf i |��}| jjr�| jd u r�|�� }n�| jr�|�� }n�|�� �r|| jj}|dk�r"|�� �rd}nd}|�r"t�d |�d �� |d v �rX|�� �r@|�� }n|�� }|dk�rzd}n"|dk�rl|�� }nd�s�J |��n|�� }W n |�r�|�� � Y nP0 t |t j �}|||| f | j |< | j |j < | jj � | j| |� |W tj | _S W tj | _n tj | _0 d S ) NzOConnection is already established for the given bind; execution_options ignoredr FTzMSession already has a Connection associated for the given Connection's Enginer� r� r� z�The engine provided as bind produced a connection that is already in a transaction. This is usually caused by a core event, such as 'engine_connect', that has left a transaction open. The effective join transaction mode used by this session is z9. To silence this warning, do not leave transactions open)r� r� ) r r< �warnr� r� r r r7 r" r� r� r: r= r� r� �connectr� r� �twophaseZbegin_twophase� begin_nested�in_transaction�join_transaction_mode�in_nested_transactionZ _get_required_nested_transactionZ_get_required_transaction�begin�closer+ Z after_begin) r� r8 r� Z local_connect� should_commit�conn� transactionr` Zbind_is_connectionr� r� r� r7 � s� ��R� � �� � ��z'SessionTransaction._connection_for_bindc C s( | j d us| jjs t�d��| �� d S )NzD'twophase' mode not enabled, or not root transaction; can't prepare.)r r� r] r� r� � _prepare_implr� r� r� r� �prepare� s �zSessionTransaction.preparec C s | j d u s| jr | jj�| j� | jj}|d us4J �|| urV|j| d�D ] }|�� qH| jjs�t d�D ] }| j� � rx q�| j� � qft � d��| j d u �r | jj�r z*t| j�� �D ]}td|d ��� q�W n< t�� � | �� W d � n1 s�0 Y Y n0 tj| _d S )N�r< �d zrOver 100 subsequent flushes have occurred within session.commit() - is an after_flush() hook creating new objects?r` r )r r" r� r+ Z before_commitr* r> �commitr? �range� _is_cleanr@ r � FlushErrorr] r� r �valuesr rh r< � safe_reraise�rollbackr� r� r )r� �stx�subtransactionZ _flush_guard�tr� r� r� rg � s. � ,z SessionTransaction._prepare_impl)�_to_rootr� c C s� | j tjur@| �tj�� | �� W d � n1 s60 Y | jd u sP| jr�t| j� � �D ]\}}}}|r^|� � q^tj | _ | j j �| j � | �� | �tj�� | �� W d � n1 s�0 Y |r�| jr�| jj dd� d S )NT�ru )r r� r� � _expect_staterg r r" r� r ro rk r� r� r+ Z after_commitrX r� rc )r� ru re �transrd � autocloser� r� r� rk s &� & zSessionTransaction.commit)�_capture_exceptionru r� c C s� | j j}|d usJ �|| ur6|j| d�D ] }|�� q(| }d }| jtjtjfv �r | �� D ]�}|jd u sp|j �rzlz<t |j � � �D ]}|d � � q�tj|_| j j�| j � W n t�� }Y n0 W tj|_|j|j d� ntj|_|j|j d� 0 |} �q qZtj|_qZ| j } |�s:| �� �s:t�d� |j|j d� | �tj�� | �� W d � n1 �sf0 Y | j�r�|�r�t�� d | j_|�r�|d �r�|d �|d ��| j�| | � |�r�| j�r�| jj dd� d S )Nri r )rC z\Session's state has been changed on a non-active transaction - this state will be discarded.r9 Trv ) r� r* r> rc r r� r� r� r r" r� r ro rq r� r+ Zafter_rollback�sys�exc_inforS rm r< r[ rw r� r �with_tracebackZafter_soft_rollback) r� rz ru rr rs �boundaryZ rollback_errrf rt �sessr� r� r� rq 5 s\ � ��� �(zSessionTransaction.rollback)� invalidater� c C s� | j r| j| j_| j| j_t| j�� �D ]J\}}}}|rJ| jd u rJ|� � |r\|j r\|� � |r(| jd u r(|� � q(t j | _| j}|j�|| � d S r� )r" r( r� r' r r* r� r ro r� r2 rc r� r� r r+ Zafter_transaction_end)r� r� r9 rf rd ry r r� r� r� rc z s � � zSessionTransaction.closec C s | j S r� r� r� r� r� r� � _get_subject� s z SessionTransaction._get_subjectc C s | j tju S r� )r r� r� r� r� r� r� �_transaction_is_active� s z)SessionTransaction._transaction_is_activec C s | j tju S r� )r r� r� r� r� r� r� �_transaction_is_closed� s z)SessionTransaction._transaction_is_closedc C s | j ttfvS r� )r r� r� r� r� r� r� �_rollback_can_be_called� s z*SessionTransaction._rollback_can_be_called)N)N)F)N)F)F)FF)F)'r� r� r� r� r r r" r� r1 r r# r2 r3 r5 Zdeclare_statesr� r� r7 � NO_CHANGEr9 r; r> r) rS rX r7 rh r� rg r� rk r� rq �ANYrc r� r� r� r� r� r� r� r� r| M s� & �+! � � � � �l � ��� �=� r| c @ s e Zd ZdZdZdZdS )r& r r9 r� N)r� r� r� r� r� �CLOSE_IS_RESETr� r� r� r� r& � s r& c @ s2 e Zd ZU dZdZded< ded< ded< ded < d ed < d ed < ded< ded< ded< ded< ded< ded< ded< ded< ded< ded< d ed < d ed < �dmd!d!d!d!dd d!d d dd"ejd#� d$dd%dddd&dd'd(d)dd*d+� d,d-�Zd Z d.ed/< d Z d0ed1< d2d2d3�d4d5�Z d6d6d6d7d8�d9d:�Z e jd2d;d3�d<d=��Zdd>�d?d@�Zdd>�dAdB�Zdd>�dCdD�Zdd>�dEdF�ZejdGd>�dHdI��Z�dnddJdK�dLdM�Z�doddJdN�dOdP�ZdJd>�dQdR�Zd7d>�dSdT�Zd7d>�dUdV�Zd7d>�dWdX�Z �dpdYdZd[d\�d]d^�Z �dqd_dZd6d[d`�dadb�Z e �drej d d d dcdd�dedfdgdYdhdhd%d6di�djdk��Z!e �dsej d d d dcdd�dedldgdYdhdhddmdi�dndk��Z!�dtej d d d ddd�dedldgdYdhdhdd6di�dodk�Z!e �duej d d d dp�dqdldgdYdhdhdrds�dtdu��Z"e �dvej d d d dp�dvdldgdYdhdhdwds�dxdu��Z"e �dwej d d d dp�dedldgdYdhdhdmds�dydu��Z"�dxej d d d dp�dedldgdYdhdhdmds�dzdu�Z"e �dyej d d{�d|dfdgdYd6d}d~�dd���Z#e �dzej d d{�dedfdgdYd6d6d~�d�d���Z#�d{ej d d{�dedfdgdYd6d6d~�d�d��Z#e �d|ej d d{�d|dldgdYd6d�d~�d�d���Z$e �d}ej d d{�dedldgdYd6d�d~�d�d���Z$�d~ej d d{�dedldgdYd6d�d~�d�d��Z$d7d>�d�d��Z%d7d>�d�d��Z&d7d>�d�d��Z'�dddd7d��d�d��Z(d7d>�d�d��Z)d�d_d7d��d�d��Z*d�d_d7d��d�d��Z+d�d_d7d��d�d��Z,�d�d d d dd��d�d�d$d�dd6d�d��d�d��Z-e d�d�d��d�d���Z.e d�d�d��d�d���Z.e d�d�d�d��d�d���Z.e d�d�d�d�d��d�d���Z.e d�d�d�d�d�d��d�d���Z.e d�d�d�d�d�d�d��d�d���Z.e d�d�d�d�d�d�d�dĜd�d���Z.e d�d�d�d�d�d�d�d�dȜd�d���Z.e d�d�d�d�d�d�d�d�d�d̜ d�d���Z.e d�d6d�dМd�d���Z.d�d6d�dМd�d��Z.d e/j0d ej d fd�d�d6d�d�dgdYd�dd�dڄZ1ej2e jd�d>�d�d݄��Z3ej4�5d�e6j7�d7d>�d�d��Z8�d�d�d�d�d7d�d�d�Z9d7d>�d�d�Z:�d�d�d�d7d�d�d�Z;d�d�d7d�d�d�Z<�d�d�d�d7d�d�d�Z=d�d7d�d�d��Z>�d�d�dd7d��d�d��Z?d�d7d��d�d��Z@d�d7d��d�d��ZAd�d7d���d �d�ZB�d�d�dd7�d��d�d�ZC�dd7�d��d�d�ZDd�d7�d ��d �d �ZEd�d7d��d �d �ZFd�d�dd7�d��d�d�ZGd dd d ej d �d�d��d�ddd�dhdgdY�d�d� �d�d�ZHd dd d ej d �d�d��d�ddd�dhdgdY�d�d� �d�d�ZId dd d ej d �d�d��d�d�d dd�dhdgdY�d�d � �d �d �ZJd!d �d ��dd�d�d�d!��d"�d#�ZKd �d$��d%�d&�dd�d'�d(�d�d)��d*�d+�ZLd�d7�d ��d,�d-�ZMd�d7�d ��d.�d/�ZN�d�d�dd7�d0��d1�d2�ZOd�d7�d ��d3�d4�ZPd�d7�d5��d6�d7�ZQd�d�d�d8��d9�d:�ZRd�d�d7�d8��d;�d<�ZSd�dd��d=�d>�ZT�d?d>��d@�dA�ZUd�d�d ��dB�dC�ZV�d��dDd7�dE��dF�dG�ZWd6d7�dH��dI�dJ�ZXdd>��dK�dL�ZY�d��dMd7�dE��dN�dO�ZZ�d��ddddd7�dP��dQ�dR�Z[�d��dS�dTddd7�dU��dV�dW�Z\�dS�dTd7�dX��dY�dZ�Z]dӐd[dddddd7�d\��d]�d^�Z^�d�d�dd�d_��d`�da�Z_e`dd>��db�dc��Zae`d�d>��dd�de��Zbe`�dfd>��dg�dh��Zce`�dfd>��di�dj��Zde`�dfd>��dk�dl��Zed S (� r{ a Manages persistence operations for ORM-mapped objects. The :class:`_orm.Session` is **not safe for use in concurrent threads.**. See :ref:`session_faq_threadsafe` for background. The Session's usage paradigm is described at :doc:`/orm/session`. Fzdispatcher[Session]r+ r2 rI z Dict[InstanceState[Any], Any]r r z#Optional[Union[Engine, Connection]]r8 z#Dict[_SessionBindKey, _SessionBind]�_Session__bindsr� r? �_warn_on_eventsr r* r' r� �hash_key� autoflushrT �enable_baked_queriesr] �JoinTransactionModer` zType[Query[Any]]� _query_clsr& r% NTr� ) r� �futurerT � autobeginr] �bindsr� �info� query_cls� autocommitr` �close_resets_only�Optional[_SessionBind]z Literal[True]z-Optional[Dict[_SessionBindKey, _SessionBind]]�Optional[_InfoType]zOptional[Type[Query[Any]]]zLiteral[False]zUnion[bool, _NoArg]) r8 r� r� rT r� r] r� r� r� r� r� r` r� c C s | rt �d��t�� | _|s&t �d��i | _i | _|| _i | _d| _ d| _ d| _ d| _ t � | _|| _|| _|| _|| _| dtjfv r�tj| _ntj| _| r�| tjvr�t �d| � d���| | _|| _ | r�| nt j | _ | r�| j �!| � |du�r |�"� D ]\}}| �#||� q�| t$| j< dS )a�+ Construct a new :class:`_orm.Session`. See also the :class:`.sessionmaker` function which is used to generate a :class:`.Session`-producing callable with a given set of arguments. :param autoflush: When ``True``, all query operations will issue a :meth:`~.Session.flush` call to this ``Session`` before proceeding. This is a convenience feature so that :meth:`~.Session.flush` need not be called repeatedly in order for database queries to retrieve results. .. seealso:: :ref:`session_flushing` - additional background on autoflush :param autobegin: Automatically start transactions (i.e. equivalent to invoking :meth:`_orm.Session.begin`) when database access is requested by an operation. Defaults to ``True``. Set to ``False`` to prevent a :class:`_orm.Session` from implicitly beginning transactions after construction, as well as after any of the :meth:`_orm.Session.rollback`, :meth:`_orm.Session.commit`, or :meth:`_orm.Session.close` methods are called. .. versionadded:: 2.0 .. seealso:: :ref:`session_autobegin_disable` :param bind: An optional :class:`_engine.Engine` or :class:`_engine.Connection` to which this ``Session`` should be bound. When specified, all SQL operations performed by this session will execute via this connectable. :param binds: A dictionary which may specify any number of :class:`_engine.Engine` or :class:`_engine.Connection` objects as the source of connectivity for SQL operations on a per-entity basis. The keys of the dictionary consist of any series of mapped classes, arbitrary Python classes that are bases for mapped classes, :class:`_schema.Table` objects and :class:`_orm.Mapper` objects. The values of the dictionary are then instances of :class:`_engine.Engine` or less commonly :class:`_engine.Connection` objects. Operations which proceed relative to a particular mapped class will consult this dictionary for the closest matching entity in order to determine which :class:`_engine.Engine` should be used for a particular SQL operation. The complete heuristics for resolution are described at :meth:`.Session.get_bind`. Usage looks like:: Session = sessionmaker( binds={ SomeMappedClass: create_engine("postgresql+psycopg2://engine1"), SomeDeclarativeBase: create_engine( "postgresql+psycopg2://engine2" ), some_mapper: create_engine("postgresql+psycopg2://engine3"), some_table: create_engine("postgresql+psycopg2://engine4"), } ) .. seealso:: :ref:`session_partitioning` :meth:`.Session.bind_mapper` :meth:`.Session.bind_table` :meth:`.Session.get_bind` :param \class_: Specify an alternate class other than ``sqlalchemy.orm.session.Session`` which should be used by the returned class. This is the only argument that is local to the :class:`.sessionmaker` function, and is not sent directly to the constructor for ``Session``. :param enable_baked_queries: legacy; defaults to ``True``. A parameter consumed by the :mod:`sqlalchemy.ext.baked` extension to determine if "baked queries" should be cached, as is the normal operation of this extension. When set to ``False``, caching as used by this particular extension is disabled. .. versionchanged:: 1.4 The ``sqlalchemy.ext.baked`` extension is legacy and is not used by any of SQLAlchemy's internals. This flag therefore only affects applications that are making explicit use of this extension within their own code. :param expire_on_commit: Defaults to ``True``. When ``True``, all instances will be fully expired after each :meth:`~.commit`, so that all attribute/object access subsequent to a completed transaction will load from the most recent database state. .. seealso:: :ref:`session_committing` :param future: Deprecated; this flag is always True. .. seealso:: :ref:`migration_20_toplevel` :param info: optional dictionary of arbitrary data to be associated with this :class:`.Session`. Is available via the :attr:`.Session.info` attribute. Note the dictionary is copied at construction time so that modifications to the per- :class:`.Session` dictionary will be local to that :class:`.Session`. :param query_cls: Class which should be used to create new Query objects, as returned by the :meth:`~.Session.query` method. Defaults to :class:`_query.Query`. :param twophase: When ``True``, all transactions will be started as a "two phase" transaction, i.e. using the "two phase" semantics of the database in use along with an XID. During a :meth:`~.commit`, after :meth:`~.flush` has been issued for all attached databases, the :meth:`~.TwoPhaseTransaction.prepare` method on each database's :class:`.TwoPhaseTransaction` will be called. This allows each database to roll back the entire transaction, before each transaction is committed. :param autocommit: the "autocommit" keyword is present for backwards compatibility but must remain at its default value of ``False``. :param join_transaction_mode: Describes the transactional behavior to take when a given bind is a :class:`_engine.Connection` that has already begun a transaction outside the scope of this :class:`_orm.Session`; in other words the :meth:`_engine.Connection.in_transaction()` method returns True. The following behaviors only take effect when the :class:`_orm.Session` **actually makes use of the connection given**; that is, a method such as :meth:`_orm.Session.execute`, :meth:`_orm.Session.connection`, etc. are actually invoked: * ``"conditional_savepoint"`` - this is the default. if the given :class:`_engine.Connection` is begun within a transaction but does not have a SAVEPOINT, then ``"rollback_only"`` is used. If the :class:`_engine.Connection` is additionally within a SAVEPOINT, in other words :meth:`_engine.Connection.in_nested_transaction()` method returns True, then ``"create_savepoint"`` is used. ``"conditional_savepoint"`` behavior attempts to make use of savepoints in order to keep the state of the existing transaction unchanged, but only if there is already a savepoint in progress; otherwise, it is not assumed that the backend in use has adequate support for SAVEPOINT, as availability of this feature varies. ``"conditional_savepoint"`` also seeks to establish approximate backwards compatibility with previous :class:`_orm.Session` behavior, for applications that are not setting a specific mode. It is recommended that one of the explicit settings be used. * ``"create_savepoint"`` - the :class:`_orm.Session` will use :meth:`_engine.Connection.begin_nested()` in all cases to create its own transaction. This transaction by its nature rides "on top" of any existing transaction that's opened on the given :class:`_engine.Connection`; if the underlying database and the driver in use has full, non-broken support for SAVEPOINT, the external transaction will remain unaffected throughout the lifespan of the :class:`_orm.Session`. The ``"create_savepoint"`` mode is the most useful for integrating a :class:`_orm.Session` into a test suite where an externally initiated transaction should remain unaffected; however, it relies on proper SAVEPOINT support from the underlying driver and database. .. tip:: When using SQLite, the SQLite driver included through Python 3.11 does not handle SAVEPOINTs correctly in all cases without workarounds. See the sections :ref:`pysqlite_serializable` and :ref:`aiosqlite_serializable` for details on current workarounds. * ``"control_fully"`` - the :class:`_orm.Session` will take control of the given transaction as its own; :meth:`_orm.Session.commit` will call ``.commit()`` on the transaction, :meth:`_orm.Session.rollback` will call ``.rollback()`` on the transaction, :meth:`_orm.Session.close` will call ``.rollback`` on the transaction. .. tip:: This mode of use is equivalent to how SQLAlchemy 1.4 would handle a :class:`_engine.Connection` given with an existing SAVEPOINT (i.e. :meth:`_engine.Connection.begin_nested`); the :class:`_orm.Session` would take full control of the existing SAVEPOINT. * ``"rollback_only"`` - the :class:`_orm.Session` will take control of the given transaction for ``.rollback()`` calls only; ``.commit()`` calls will not be propagated to the given transaction. ``.close()`` calls will have no effect on the given transaction. .. tip:: This mode of use is equivalent to how SQLAlchemy 1.4 would handle a :class:`_engine.Connection` given with an existing regular database transaction (i.e. :meth:`_engine.Connection.begin`); the :class:`_orm.Session` would propagate :meth:`_orm.Session.rollback` calls to the underlying transaction, but not :meth:`_orm.Session.commit` or :meth:`_orm.Session.close` calls. .. versionadded:: 2.0.0rc1 :param close_resets_only: Defaults to ``True``. Determines if the session should reset itself after calling ``.close()`` or should pass in a no longer usable state, disabling re-use. .. versionadded:: 2.0.22 added flag ``close_resets_only``. A future SQLAlchemy version may change the default value of this flag to ``False``. .. seealso:: :ref:`session_closing` - Detail on the semantics of :meth:`_orm.Session.close` and :meth:`_orm.Session.reset`. z&autocommit=True is no longer supportedzCThe 'future' parameter passed to Session() may only be set to True.FNTz.invalid selection for join_transaction_mode: "�")%r� � ArgumentErrorr �WeakInstanceDictrI r r r8 r� r? r� r* r' �_new_sessionidr� r� r� rT r� rJ �NO_ARGr& r� r% r� r� �__args__r` r] r r3 r� r� r� rH � _add_bindr� )r� r8 r� r� rT r� r] r� r� r� r� r� r` r� rK r� r� r� r� � s\ x� � ����� zSession.__init__z Optional[TransactionalContext]�_trans_context_managerz"Optional[_ConnectionCallableProto]�connection_callable�_S)r� r� c C s | S r� r� r� r� r� r� � __enter__ s zSession.__enter__r r� )�type_�value� tracebackr� c C s | � � d S r� )rc )r� r� r� r� r� r� r� �__exit__ s zSession.__exit__z Iterator[_S]c c sV | �> | � � � | V W d � n1 s*0 Y W d � n1 sH0 Y d S r� �rb r� r� r� r� �_maker_context_manager s z Session._maker_context_managerr� c C s | j duS )z�Return True if this :class:`_orm.Session` has begun a transaction. .. versionadded:: 1.4 .. seealso:: :attr:`_orm.Session.is_active` N)r* r� r� r� r� r_ s zSession.in_transactionc C s | j duS )z�Return True if this :class:`_orm.Session` has begun a nested transaction, e.g. SAVEPOINT. .. versionadded:: 1.4 N�r' r� r� r� r� ra ( s z Session.in_nested_transactionc C s$ | j }|dur |jdur |j}q|S )zaReturn the current root transaction in progress, if any. .. versionadded:: 1.4 N)r* r �r� rx r� r� r� �get_transaction1 s zSession.get_transactionc C s | j S )zcReturn the current nested transaction in progress, if any. .. versionadded:: 1.4 r� r� r� r� r� �get_nested_transaction< s z Session.get_nested_transactionrh c C s i S )a� A user-modifiable dictionary. The initial value of this dictionary can be populated using the ``info`` argument to the :class:`.Session` constructor or :class:`.sessionmaker` constructor or factory methods. The dictionary here is always local to this :class:`.Session` and can be modified independently of all other :class:`.Session` objects. r� r� r� r� r� r� E s z Session.infor| )rb r� c C sL | j d u rF|s | js t�d��t| |r,tjntj�}| j |u sBJ �|S | j S )Nz]Autobegin is disabled on this Session; please call session.begin() to start a new transaction)r* r� r� r� r| r r r )r� rb rx r� r� r� � _autobegin_tR s ���zSession._autobegin_tr: c C sb | j }|du r"| jdd�}|s"|S |dus.J �|rT|j|d�}| j |u sLJ �|| _n t�d��|S )a� Begin a transaction, or nested transaction, on this :class:`.Session`, if one is not already begun. The :class:`_orm.Session` object features **autobegin** behavior, so that normally it is not necessary to call the :meth:`_orm.Session.begin` method explicitly. However, it may be used in order to control the scope of when the transactional state is begun. When used to begin the outermost transaction, an error is raised if this :class:`.Session` is already inside of a transaction. :param nested: if True, begins a SAVEPOINT transaction and is equivalent to calling :meth:`~.Session.begin_nested`. For documentation on SAVEPOINT transactions, please see :ref:`session_begin_nested`. :return: the :class:`.SessionTransaction` object. Note that :class:`.SessionTransaction` acts as a Python context manager, allowing :meth:`.Session.begin` to be used in a "with" block. See :ref:`session_explicit_begin` for an example. .. seealso:: :ref:`session_autobegin` :ref:`unitofwork_transaction` :meth:`.Session.begin_nested` NTr� �r" z/A transaction is already begun on this Session.)r* r� r; r' r� r� )r� r" rx r� r� r� rb f s # �z Session.beginc C s | j dd�S )at Begin a "nested" transaction on this Session, e.g. SAVEPOINT. The target database(s) and associated drivers must support SQL SAVEPOINT for this method to function correctly. For documentation on SAVEPOINT transactions, please see :ref:`session_begin_nested`. :return: the :class:`.SessionTransaction` object. Note that :class:`.SessionTransaction` acts as a context manager, allowing :meth:`.Session.begin_nested` to be used in a "with" block. See :ref:`session_begin_nested` for a usage example. .. seealso:: :ref:`session_begin_nested` :ref:`pysqlite_serializable` - special workarounds required with the SQLite driver in order for SAVEPOINT to work correctly. For asyncio use cases, see the section :ref:`aiosqlite_serializable`. Tr� r� r� r� r� r� r^ � s zSession.begin_nestedc C s | j du r n| j jdd� dS )a{ Rollback the current transaction in progress. If no transaction is in progress, this method is a pass-through. The method always rolls back the topmost database transaction, discarding any nested transactions that may be in progress. .. seealso:: :ref:`session_rollback` :ref:`unitofwork_transaction` NTrv )r* rq r� r� r� r� rq � s zSession.rollbackc C s& | j }|du r| �� }|jdd� dS )ae Flush pending changes and commit the current transaction. When the COMMIT operation is complete, all objects are fully :term:`expired`, erasing their internal contents, which will be automatically re-loaded when the objects are next accessed. In the interim, these objects are in an expired state and will not function if they are :term:`detached` from the :class:`.Session`. Additionally, this re-load operation is not supported when using asyncio-oriented APIs. The :paramref:`.Session.expire_on_commit` parameter may be used to disable this behavior. When there is no transaction in place for the :class:`.Session`, indicating that no operations were invoked on this :class:`.Session` since the previous call to :meth:`.Session.commit`, the method will begin and commit an internal-only "logical" transaction, that does not normally affect the database unless pending flush changes were detected, but will still invoke event handlers and object expiration rules. The outermost database transaction is committed unconditionally, automatically releasing any SAVEPOINTs in effect. .. seealso:: :ref:`session_committing` :ref:`unitofwork_transaction` :ref:`asyncio_orm_avoid_lazyloads` NTrv )r* r� rk r� r� r� r� rk � s zSession.commitc C s" | j }|du r| �� }|�� dS )ax Prepare the current transaction in progress for two phase commit. If no transaction is in progress, this method raises an :exc:`~sqlalchemy.exc.InvalidRequestError`. Only root transactions of two phase sessions can be prepared. If the current transaction is not such, an :exc:`~sqlalchemy.exc.InvalidRequestError` is raised. N)r* r� rh r� r� r� r� rh � s zSession.preparer� rZ r= )r� r� r� c C s@ |r*|� dd�}|du r2| jf i |��}n| �� }| j||d�S )a" Return a :class:`_engine.Connection` object corresponding to this :class:`.Session` object's transactional state. Either the :class:`_engine.Connection` corresponding to the current transaction is returned, or if no transaction is in progress, a new one is begun and the :class:`_engine.Connection` returned (note that no transactional state is established with the DBAPI until the first SQL statement is emitted). Ambiguity in multi-bind or unbound :class:`.Session` objects can be resolved through any of the optional keyword arguments. This ultimately makes usage of the :meth:`.get_bind` method for resolution. :param bind_arguments: dictionary of bind arguments. May include "mapper", "bind", "clause", other custom arguments that are passed to :meth:`.Session.get_bind`. :param execution_options: a dictionary of execution options that will be passed to :meth:`_engine.Connection.execution_options`, **when the connection is first procured only**. If the connection is already present within the :class:`.Session`, a warning is emitted and the arguments are ignored. .. seealso:: :ref:`session_transaction_isolation` r8 N�r� )�popr6 r7 )r� r� r� r8 r� r� r� r9 s # �zSession.connectionrY )r: r� r� r� c K s, t �| � | j}|d u r | �� }|�||�S r� )r? r$ r* r� r7 )r� r: r� r� rx r� r� r� r7 3 s z Session._connection_for_bind.)r� r� r� � _add_event�_scalar_resultrr z"Optional[_CoreSingleExecuteParams]rU r� )r� r� r� r� r� r� r� r� c C s d S r� r� �r� r� r� r� r� r� r� r� r� r� r� r� @ s zSession._execute_internalr� r� c C s d S r� r� r� r� r� r� r� M s c C s� t �tj|�}|si }nt|�}|j�dd �dkrTt�|d�}t rdt |t j �sdJ �nd }|� d|� t�|�}|r||�� } n| jj} |r�t| �|g } | �r|d ur�|�| ||||d�\}}t| |||||| �} t| �D ]4\} } | | _| | �} | r�|�r| �� S | S q�| j}| j}|d u�r<|�| ||||d�\}}| jf i |��}| � |�}|�r�|�s�t �rrt t |�}|j||�p�i |d�S |�r�|� | ||�p�i |||�}n|j ||�p�i |d�}|�r�|�� S |S d S )NZcompile_state_pluginZorm�clauseTFr� )!rD �expectrF Z StatementRoler� �_propagate_attrsr� rK Z _get_plugin_class_for_pluginr r� r ZAbstractORMCompileState� setdefaultr< Zcoerce_to_immutabledictr� r+ Zdo_orm_executer� Zorm_pre_session_execr~ � enumerater� �scalarr� r� r6 r7 r rb Zorm_execute_statement�execute)r� r� r� r� r� r� r� r� r� r� Zorm_exec_state�idx�fnZ fn_resultr8 re r� r� r� r� r� Z s� ���� �� � �� �� ��r� r� r� r� zTypedReturnsRows[_T]z Result[_T])r� r� r� r� r� r� r� c C s d S r� r� �r� r� r� r� r� r� r� r� r� r� r� � s zSession.executert zCursorResult[Any]c C s d S r� r� r� r� r� r� r� � s c C s d S r� r� r� r� r� r� r� � s c C s | j ||||||d�S )a� Execute a SQL expression construct. Returns a :class:`_engine.Result` object representing results of the statement execution. E.g.:: from sqlalchemy import select result = session.execute(select(User).where(User.id == 5)) The API contract of :meth:`_orm.Session.execute` is similar to that of :meth:`_engine.Connection.execute`, the :term:`2.0 style` version of :class:`_engine.Connection`. .. versionchanged:: 1.4 the :meth:`_orm.Session.execute` method is now the primary point of ORM statement execution when using :term:`2.0 style` ORM usage. :param statement: An executable statement (i.e. an :class:`.Executable` expression such as :func:`_expression.select`). :param params: Optional dictionary, or list of dictionaries, containing bound parameter values. If a single dictionary, single-row execution occurs; if a list of dictionaries, an "executemany" will be invoked. The keys in each dictionary must correspond to parameter names present in the statement. :param execution_options: optional dictionary of execution options, which will be associated with the statement execution. This dictionary can provide a subset of the options that are accepted by :meth:`_engine.Connection.execution_options`, and may also provide additional options understood only in an ORM context. .. seealso:: :ref:`orm_queryguide_execution_options` - ORM-specific execution options :param bind_arguments: dictionary of additional arguments to determine the bind. May include "mapper", "bind", or other custom arguments. Contents of this dictionary are passed to the :meth:`.Session.get_bind` method. :return: a :class:`_engine.Result` object. r� �r� r� r� r� r� r� s <�)r� r� zTypedReturnsRows[Tuple[_T]]z Optional[_T])r� r� r� r� r� r� c K s d S r� r� �r� r� r� r� r� r� r� r� r� r� F s zSession.scalarc K s d S r� r� r� r� r� r� r� Q s c K s | j ||f||dd�|��S )z�Execute a statement and return a scalar result. Usage and parameters are the same as that of :meth:`_orm.Session.execute`; the return result is a scalar Python value. T)r� r� r� r� r� r� r� r� r� \ s ���zScalarResult[_T]c K s d S r� r� r� r� r� r� �scalarsv s zSession.scalarszScalarResult[Any]c K s d S r� r� r� r� r� r� r� � s c K s | j |f|||dd�|���� S )a� Execute a statement and return the results as scalars. Usage and parameters are the same as that of :meth:`_orm.Session.execute`; the return result is a :class:`_result.ScalarResult` filtering object which will return single elements rather than :class:`_row.Row` objects. :return: a :class:`_result.ScalarResult` object .. versionadded:: 1.4.24 Added :meth:`_orm.Session.scalars` .. versionadded:: 1.4.26 Added :meth:`_orm.scoped_session.scalars` .. seealso:: :ref:`orm_queryguide_select_orm_entities` - contrasts the behavior of :meth:`_orm.Session.execute` to :meth:`_orm.Session.scalars` F)r� r� r� r� )r� r� r� r� r� r� r� � s ���c C s | j dd� dS )a� Close out the transactional resources and ORM objects used by this :class:`_orm.Session`. This expunges all ORM objects associated with this :class:`_orm.Session`, ends any transaction in progress and :term:`releases` any :class:`_engine.Connection` objects which this :class:`_orm.Session` itself has checked out from associated :class:`_engine.Engine` objects. The operation then leaves the :class:`_orm.Session` in a state which it may be used again. .. tip:: In the default running mode the :meth:`_orm.Session.close` method **does not prevent the Session from being used again**. The :class:`_orm.Session` itself does not actually have a distinct "closed" state; it merely means the :class:`_orm.Session` will release all database connections and ORM objects. Setting the parameter :paramref:`_orm.Session.close_resets_only` to ``False`` will instead make the ``close`` final, meaning that any further action on the session will be forbidden. .. versionchanged:: 1.4 The :meth:`.Session.close` method does not immediately create a new :class:`.SessionTransaction` object; instead, the new :class:`.SessionTransaction` is created only if the :class:`.Session` is used again for a database operation. .. seealso:: :ref:`session_closing` - detail on the semantics of :meth:`_orm.Session.close` and :meth:`_orm.Session.reset`. :meth:`_orm.Session.reset` - a similar method that behaves like ``close()`` with the parameter :paramref:`_orm.Session.close_resets_only` set to ``True``. F�r� N�� _close_implr� r� r� r� rc � s 'z Session.closec C s | j ddd� dS )a Close out the transactional resources and ORM objects used by this :class:`_orm.Session`, resetting the session to its initial state. This method provides for same "reset-only" behavior that the :meth:`_orm.Session.close` method has provided historically, where the state of the :class:`_orm.Session` is reset as though the object were brand new, and ready to be used again. This method may then be useful for :class:`_orm.Session` objects which set :paramref:`_orm.Session.close_resets_only` to ``False``, so that "reset only" behavior is still available. .. versionadded:: 2.0.22 .. seealso:: :ref:`session_closing` - detail on the semantics of :meth:`_orm.Session.close` and :meth:`_orm.Session.reset`. :meth:`_orm.Session.close` - a similar method will additionally prevent re-use of the Session when the parameter :paramref:`_orm.Session.close_resets_only` is set to ``False``. FT)r� �is_resetNr� r� r� r� r� �reset� s z Session.resetc C s | j dd� dS )a� Close this Session, using connection invalidation. This is a variant of :meth:`.Session.close` that will additionally ensure that the :meth:`_engine.Connection.invalidate` method will be called on each :class:`_engine.Connection` object that is currently in use for a transaction (typically there is only one connection unless the :class:`_orm.Session` is used with multiple engines). This can be called when the database is known to be in a state where the connections are no longer safe to be used. Below illustrates a scenario when using `gevent <https://www.gevent.org/>`_, which can produce ``Timeout`` exceptions that may mean the underlying connection should be discarded:: import gevent try: sess = Session() sess.add(User()) sess.commit() except gevent.Timeout: sess.invalidate() raise except: sess.rollback() raise The method additionally does everything that :meth:`_orm.Session.close` does, including that all ORM objects are expunged. Tr� Nr� r� r� r� r� r� � s "zSession.invalidate)r� r� r� c C sH |s| j tju rtj| _ | �� | jd urD| j�� D ]}|�|� q4d S r� )r% r& r� r� � expunge_allr* r> rc )r� r� r� rf r� r� r� r� s zSession._close_implc C sF | j �� t| j� }| j �� t�� | _ i | _i | _tj � || � dS )z�Remove all object instances from this ``Session``. This is equivalent to calling ``expunge(obj)`` on all objects in this ``Session``. N) rI rN r� r Z_killr r� r rU r4 rV )r� rN r� r� r� r� s zSession.expunge_all�_SessionBindKey)rK r8 r� c C s� z t |�}W nL tjyX } z2t|t�s:t�d| �|�n || j|< W Y d }~nld }~0 0 trlt|t�slJ �t|t �r�|| j|< n:t |�r�|| j|j < |j D ]}|| j|< q�nt�d| ��d S )Nz!Not an acceptable bind target: %s) rB r� �NoInspectionAvailabler� �typer� r� r rC rH r" r� Z _all_tables)r� rK r8 r� �errZ _selectabler� r� r� r� 0 s* �� �zSession._add_bindz_EntityBindKey[_O])r� r8 r� c C s | � ||� dS )a� Associate a :class:`_orm.Mapper` or arbitrary Python class with a "bind", e.g. an :class:`_engine.Engine` or :class:`_engine.Connection`. The given entity is added to a lookup used by the :meth:`.Session.get_bind` method. :param mapper: a :class:`_orm.Mapper` object, or an instance of a mapped class, or any Python class that is the base of a set of mapped classes. :param bind: an :class:`_engine.Engine` or :class:`_engine.Connection` object. .. seealso:: :ref:`session_partitioning` :paramref:`.Session.binds` :meth:`.Session.bind_table` N�r� )r� r� r8 r� r� r� r� I s zSession.bind_mapperrH )�tabler8 r� c C s | � ||� dS )a� Associate a :class:`_schema.Table` with a "bind", e.g. an :class:`_engine.Engine` or :class:`_engine.Connection`. The given :class:`_schema.Table` is added to a lookup used by the :meth:`.Session.get_bind` method. :param table: a :class:`_schema.Table` object, which is typically the target of an ORM mapping, or is present within a selectable that is mapped. :param bind: an :class:`_engine.Engine` or :class:`_engine.Connection` object. .. seealso:: :ref:`session_partitioning` :paramref:`.Session.binds` :meth:`.Session.bind_mapper` Nr� )r� r� r8 r� r� r� � bind_tableg s zSession.bind_table)r� r8 r� � _sa_skip_for_implicit_returningz Optional[_EntityBindKey[_O]]zOptional[ClauseElement]zOptional[bool]zUnion[Engine, Connection])r� r� r8 r� r� r� r� c K s� |r|S | j s| jr| jS |du r@|du r@| jr6| jS t�d��|dur�z t|�}W q� tjy� } z&t|t�r~t� |�|�n� W Y d}~q�d}~0 0 nd}| j �rl|r�|j j D ] } | | j v r�| j | S q�|du r�|j }|du�rl|j �dd�} | du�r*| jj j D ] } | | j v �r| j | S �qt�|�D ]6} | | j v �r4t�rZt| t��sZJ �| j | S �q4| j�rz| jS g } |du�r�| �d|� �� |du�r�| �d� t�dd�| �� d���dS ) aG Return a "bind" to which this :class:`.Session` is bound. The "bind" is usually an instance of :class:`_engine.Engine`, except in the case where the :class:`.Session` has been explicitly bound directly to a :class:`_engine.Connection`. For a multiply-bound or unbound :class:`.Session`, the ``mapper`` or ``clause`` arguments are used to determine the appropriate bind to return. Note that the "mapper" argument is usually present when :meth:`.Session.get_bind` is called via an ORM operation such as a :meth:`.Session.query`, each individual INSERT/UPDATE/DELETE operation within a :meth:`.Session.flush`, call, etc. The order of resolution is: 1. if mapper given and :paramref:`.Session.binds` is present, locate a bind based first on the mapper in use, then on the mapped class in use, then on any base classes that are present in the ``__mro__`` of the mapped class, from more specific superclasses to more general. 2. if clause given and ``Session.binds`` is present, locate a bind based on :class:`_schema.Table` objects found in the given clause present in ``Session.binds``. 3. if ``Session.binds`` is present, return that. 4. if clause given, attempt to return a bind linked to the :class:`_schema.MetaData` ultimately associated with the clause. 5. if mapper given, attempt to return a bind linked to the :class:`_schema.MetaData` ultimately associated with the :class:`_schema.Table` or other selectable to which the mapper is mapped. 6. No bind can be found, :exc:`~sqlalchemy.exc.UnboundExecutionError` is raised. Note that the :meth:`.Session.get_bind` method can be overridden on a user-defined subclass of :class:`.Session` to provide any kind of bind resolution scheme. See the example at :ref:`session_custom_partitioning`. :param mapper: Optional mapped class or corresponding :class:`_orm.Mapper` instance. The bind can be derived from a :class:`_orm.Mapper` first by consulting the "binds" map associated with this :class:`.Session`, and secondly by consulting the :class:`_schema.MetaData` associated with the :class:`_schema.Table` to which the :class:`_orm.Mapper` is mapped for a bind. :param clause: A :class:`_expression.ClauseElement` (i.e. :func:`_expression.select`, :func:`_expression.text`, etc.). If the ``mapper`` argument is not present or could not produce a bind, the given expression construct will be searched for a bound element, typically a :class:`_schema.Table` associated with bound :class:`_schema.MetaData`. .. seealso:: :ref:`session_partitioning` :paramref:`.Session.binds` :meth:`.Session.bind_mapper` :meth:`.Session.bind_table` NzlThis session is not bound to a single Engine or Connection, and no context was provided to locate a binding.�plugin_subjectzmapper zSQL expressionz&Could not locate a bind configured on �, z or this Session.)r� r8 r� ZUnboundExecutionErrorrB r� r� r� r ZUnmappedClassErrorr� �__mro__Zpersist_selectabler� r� r� rI Ziterater rL r� �join) r� r� r� r8 r� r� r� Zinspected_mapperr� r� r� �objr r� r� r� r6 � sd T � � ��zSession.get_bindz_EntityType[_O]z Query[_O])�_entityr� c C s d S r� r� )r� r� r� r� r� r " s z Session.queryzTypedColumnsClauseRole[_T]z RowReturningQuery[Tuple[_T]])�_colexprr� c C s d S r� r� )r� r� r� r� r� r % s z _TCCA[_T0]z _TCCA[_T1]z"RowReturningQuery[Tuple[_T0, _T1]])�_Session__ent0�_Session__ent1r� c C s d S r� r� )r� r� r� r� r� r� r / s z _TCCA[_T2]z'RowReturningQuery[Tuple[_T0, _T1, _T2]])r� r� �_Session__ent2r� c C s d S r� r� )r� r� r� r� r� r� r� r 4 s z _TCCA[_T3]z,RowReturningQuery[Tuple[_T0, _T1, _T2, _T3]])r� r� r� �_Session__ent3r� c C s d S r� r� )r� r� r� r� r� r� r� r� r 9 s z _TCCA[_T4]z1RowReturningQuery[Tuple[_T0, _T1, _T2, _T3, _T4]])r� r� r� r� �_Session__ent4r� c C s d S r� r� )r� r� r� r� r� r� r� r� r� r B s z _TCCA[_T5]z6RowReturningQuery[Tuple[_T0, _T1, _T2, _T3, _T4, _T5]])r� r� r� r� r� �_Session__ent5r� c C s d S r� r� )r� r� r� r� r� r� r� r� r� r� r L s z _TCCA[_T6]z;RowReturningQuery[Tuple[_T0, _T1, _T2, _T3, _T4, _T5, _T6]])r� r� r� r� r� r� �_Session__ent6r� c C s d S r� r� )r� r� r� r� r� r� r� r� r� r� r� r W s z _TCCA[_T7]z@RowReturningQuery[Tuple[_T0, _T1, _T2, _T3, _T4, _T5, _T6, _T7]]) r� r� r� r� r� r� r� �_Session__ent7r� c C s d S r� r� ) r� r� r� r� r� r� r� r� r� r� r� r� r c s z_ColumnsClauseArgument[Any]z Query[Any])�entitiesr5 r� c O s d S r� r� �r� r� r5 r� r� r� r r s c O s | j || fi |��S )a� Return a new :class:`_query.Query` object corresponding to this :class:`_orm.Session`. Note that the :class:`_query.Query` object is legacy as of SQLAlchemy 2.0; the :func:`_sql.select` construct is now used to construct ORM queries. .. seealso:: :ref:`unified_tutorial` :ref:`queryguide_toplevel` :ref:`query_api_toplevel` - legacy API doc )r� r� r� r� r� r w s r� r� r. r� z)Union[Optional[_O], LoaderCallableStatus])r� �primary_key_identityr� �passiver r� r� r� c C s" |j ||d�}t�| |||�} | S )ay Locate an object in the identity map. Given a primary key identity, constructs an identity key and then looks in the session's identity map. If present, the object may be run through unexpiration rules (e.g. load unloaded attributes, check if was deleted). e.g.:: obj = session._identity_lookup(inspect(SomeClass), (1,)) :param mapper: mapper in use :param primary_key_identity: the primary key we are searching for, as a tuple. :param identity_token: identity token that should be used to create the identity key. Used as is, however overriding subclasses can repurpose this in order to interpret the value in a special way, such as if None then look among multiple target tokens. :param passive: passive load flag passed to :func:`.loading.get_from_identity`, which impacts the behavior if the object is found; the object may be validated and/or unexpired if the flag allows for SQL to be emitted. :param lazy_loaded_from: an :class:`.InstanceState` that is specifically asking for this identity as a related identity. Used for sharding schemes where there is a correspondence between an object and a related object being lazy-loaded (or otherwise relationship-loaded). :return: None if the object is not found in the identity map, *or* if the object was unexpired and found to have been deleted. if passive flags disallow SQL and the object is expired, returns PASSIVE_NO_RESULT. In all other cases the instance is returned. .. versionchanged:: 1.4.0 - the :meth:`.Session._identity_lookup` method was moved from :class:`_query.Query` to :class:`.Session`, to avoid having to instantiate the :class:`_query.Query` object. )r� )Z identity_key_from_primary_keyr Zget_from_identity) r� r� r� r� r� r r� r� rK Z return_valuer� r� r� �_identity_lookup� s 3�zSession._identity_lookupzIterator[Session]c c s* | j }d| _ z| V W || _ n|| _ 0 dS )ag Return a context manager that disables autoflush. e.g.:: with session.no_autoflush: some_object = SomeClass() session.add(some_object) # won't autoflush some_object.related_thing = session.query(SomeRelated).first() Operations that proceed within the ``with:`` block will not be subject to flushes occurring upon query access. This is useful when initializing a series of objects which involve existing database queries, where the uncompleted object should not yet be flushed. FN)r� )r� r� r� r� r� � no_autoflush� s zSession.no_autoflushz�This warning originated from the Session 'autoflush' process, which was invoked automatically in response to a user-initiated operation. Consider using ``no_autoflush`` context manager if this warning happended while initializing objects.c C s` | j r\| js\z | �� W nB tjyZ } z(|�d� |�t�� d ��W Y d }~n d }~0 0 d S )Nz�raised as a result of Query-invoked autoflush; consider using a session.no_autoflush block if this flush is occurring prematurelyr9 ) r� r? r@ r� ZStatementErrorZ add_detailr} r{ r| )r� �er� r� r� � _autoflush� s �zSession._autoflushr� zOptional[Iterable[str]]rw )r� �attribute_names�with_for_updater� c C s� zt �|�}W n2 tjy@ } zt�|�|�W Y d}~n d}~0 0 | �||� | �� |i krht�d��t � |�}t � t |��}tj| ||j|||dddd� du r�t�dt|� ��dS )a Expire and refresh attributes on the given instance. The selected attributes will first be expired as they would when using :meth:`_orm.Session.expire`; then a SELECT statement will be issued to the database to refresh column-oriented attributes with the current value available in the current transaction. :func:`_orm.relationship` oriented attributes will also be immediately loaded if they were already eagerly loaded on the object, using the same eager loading strategy that they were loaded with originally. .. versionadded:: 1.4 - the :meth:`_orm.Session.refresh` method can also refresh eagerly loaded attributes. :func:`_orm.relationship` oriented attributes that would normally load using the ``select`` (or "lazy") loader strategy will also load **if they are named explicitly in the attribute_names collection**, emitting a SELECT statement for the attribute using the ``immediate`` loader strategy. If lazy-loaded relationships are not named in :paramref:`_orm.Session.refresh.attribute_names`, then they remain as "lazy loaded" attributes and are not implicitly refreshed. .. versionchanged:: 2.0.4 The :meth:`_orm.Session.refresh` method will now refresh lazy-loaded :func:`_orm.relationship` oriented attributes for those which are named explicitly in the :paramref:`_orm.Session.refresh.attribute_names` collection. .. tip:: While the :meth:`_orm.Session.refresh` method is capable of refreshing both column and relationship oriented attributes, its primary focus is on refreshing of local column-oriented attributes on a single instance. For more open ended "refresh" functionality, including the ability to refresh the attributes on many objects at once while having explicit control over relationship loader strategies, use the :ref:`populate existing <orm_queryguide_populate_existing>` feature instead. Note that a highly isolated transaction will return the same values as were previously read in that same transaction, regardless of changes in database state outside of that transaction. Refreshing attributes usually only makes sense at the start of a transaction where database rows have not yet been accessed. :param attribute_names: optional. An iterable collection of string attribute names indicating a subset of attributes to be refreshed. :param with_for_update: optional boolean ``True`` indicating FOR UPDATE should be used, or may be a dictionary containing flags to indicate a more specific set of FOR UPDATE flags for the SELECT; flags should match the parameters of :meth:`_query.Query.with_for_update`. Supersedes the :paramref:`.Session.refresh.lockmode` parameter. .. seealso:: :ref:`session_expire` - introductory material :meth:`.Session.expire` :meth:`.Session.expire_all` :ref:`orm_queryguide_populate_existing` - allows any ORM query to refresh objects as they would be loaded normally. Nzqwith_for_update should be the boolean value True, or a dictionary with options. A blank dictionary is ambiguous.T)Z refresh_stater� Zonly_load_propsZrequire_pk_colsr� Zis_user_refreshz Could not refresh instance '%s')r �instance_stater �NO_STATE�UnmappedInstanceError� _expire_stater� r� r� rM �_from_argumentr; �selectr, r Z load_on_identrK r� r* )r� r� r� r� r r� �stmtr� r� r� �refresh� s: K" � ��� �zSession.refreshc C s& | j �� D ]}|�|j| j j� q dS )a� Expires all persistent instances within this Session. When any attributes on a persistent instance is next accessed, a query will be issued using the :class:`.Session` object's current transactional context in order to load all expired attributes for the given instance. Note that a highly isolated transaction will return the same values as were previously read in that same transaction, regardless of changes in database state outside of that transaction. To expire individual objects and individual attributes on those objects, use :meth:`Session.expire`. The :class:`.Session` object's default behavior is to expire all state whenever the :meth:`Session.rollback` or :meth:`Session.commit` methods are called, so that new state can be loaded for the new transaction. For this reason, calling :meth:`Session.expire_all` is not usually needed, assuming the transaction is isolated. .. seealso:: :ref:`session_expire` - introductory material :meth:`.Session.expire` :meth:`.Session.refresh` :meth:`_orm.Query.populate_existing` N)rI rN rP r� rQ �r� r r� r� r� � expire_allt s zSession.expire_all)r� r� r� c C sR zt �|�}W n2 tjy@ } zt�|�|�W Y d}~n d}~0 0 | �||� dS )a� Expire the attributes on an instance. Marks the attributes of an instance as out of date. When an expired attribute is next accessed, a query will be issued to the :class:`.Session` object's current transactional context in order to load all expired attributes for the given instance. Note that a highly isolated transaction will return the same values as were previously read in that same transaction, regardless of changes in database state outside of that transaction. To expire all objects in the :class:`.Session` simultaneously, use :meth:`Session.expire_all`. The :class:`.Session` object's default behavior is to expire all state whenever the :meth:`Session.rollback` or :meth:`Session.commit` methods are called, so that new state can be loaded for the new transaction. For this reason, calling :meth:`Session.expire` only makes sense for the specific case that a non-ORM SQL statement was emitted in the current transaction. :param instance: The instance to be refreshed. :param attribute_names: optional list of string attribute names indicating a subset of attributes to be expired. .. seealso:: :ref:`session_expire` - introductory material :meth:`.Session.expire` :meth:`.Session.refresh` :meth:`_orm.Query.populate_existing` N)r r� r r� r� r� )r� r� r� r r� r� r� r� �expire� s '"zSession.expirer� )r r� r� c C s\ | � |� |r |�|j|� n:t|jj�d|��}| �|� |D ]\}}}}| �|� q@d S )Nzrefresh-expire)�_validate_persistent�_expire_attributesr� r� �managerr� �cascade_iterator�_conditional_expire)r� r r� �cascaded�o�m�st_�dct_r� r� r� r� � s � zSession._expire_state)r r� r� c C s> |j r|�|j| jj� n || jv r:| j�|� |�| � dS )z5Expire a state if persistent, else expunge if pendingN)rK rP r� rI rQ r r� �_detach)r� r r� r� r� r� r� � s zSession._conditional_expirer� c C s� zt �|�}W n2 tjy@ } zt�|�|�W Y d}~n d}~0 0 |j| jur`t�dt |� ��t |j j � d|��}| �|gdd� |D � � dS )z�Remove the `instance` from this ``Session``. This will free all internal references to the instance. Cascading will be applied according to the *expunge* cascade rule. Nz*Instance %s is not present in this Session�expungec S s g | ]\}}}}|�qS r� r� )r r� r� r� r� r� r� r� r � � z#Session.expunge.<locals>.<listcomp>)r r� r r� r� � session_idr� r� r� r/ r� r� r� r� rG )r� r� r r� r� r� r� r� r� � s " ��zSession.expungez Iterable[InstanceState[Any]])�statesrE r� c C sv |D ]Z}|| j v r | j �|� q| j�|�rH| j�|� | j�|d � q| jr| jj�|d � qtjj || |d� d S )NrD ) r r� rI �contains_staterJ r r* rU r4 rV )r� r rE r r� r� r� rG � s �zSession._expunge_stateszSet[InstanceState[Any]])r r� c C s� | j jp d}|D �]}t|�}|�� }|dur|�|�}t�|d �rL|jrZt�|d �rlt � dt |� ��|j du r~||_ n\|j |kr�| j �|� | j}|dus�J �||jv r�|j| d }n|j }||f|j|< ||_ | j �|�} | du�r |�| �|k�r | �� du�r t�d|f � d|_qtj�dd� |D �| j � | �|� |du�rr|�| j�D ]}|| |� �q`t|��| j�D ]}| j�|� �q�dS ) z�Register all persistent objects from a flush. This is used both for pending objects moving to the persistent state as well as already persistent objects. Nr aO Instance %s has a NULL identity key. If this is an auto-generated value, check that the database table allows generation of new primary key values, and that the mapped Column object is configured to expect these generated values. Ensure also that this flush() is not occurring at an inappropriate time, such as within a load() event.r z�Identity map already had an identity for %s, replacing it with newly flushed object. Are there load operations occurring inside of an event handler within the flush?Fc s s | ]}||j fV qd S r� �r� �r r r� r� r� � <genexpr>M r z/Session._register_persistent.<locals>.<genexpr>) r+ �pending_to_persistentr) r� �_identity_key_from_stater( � intersection�allow_partial_pks� issupersetr rn r/ rK rI rJ r* r rL r< r[ � _orphaned_outside_of_sessionrU r4 �_commit_all_states�_register_alteredr r� r� ) r� r r r r� r� Z instance_keyrx Zorig_key�oldr� r� r� �_register_persistent sh �� ��� � � � ���� z Session._register_persistentc C s8 | j r4|D ](}|| jv r&d| j j|< q d| j j|< q d S �NT)r* r r )r� r r r� r� r� r Z s zSession._register_alteredc C sn | j jp d }|D ]X}| jr&d| jj|< |d ur6|�� }| j�|� | j�|d � d|_|d ur|| |� qd S r )r+ �persistent_to_deletedr* r r� rI rJ r� )r� r r r r� r� r� r� �_remove_newly_deletedb s z Session._remove_newly_deleted)r� �_warnr� c C sd |r| j r| �d� zt�|�}W n2 tjyT } zt�|�|�W Y d}~n d}~0 0 | �|� dS )a� Place an object into this :class:`_orm.Session`. Objects that are in the :term:`transient` state when passed to the :meth:`_orm.Session.add` method will move to the :term:`pending` state, until the next flush, at which point they will move to the :term:`persistent` state. Objects that are in the :term:`detached` state when passed to the :meth:`_orm.Session.add` method will move to the :term:`persistent` state directly. If the transaction used by the :class:`_orm.Session` is rolled back, objects which were transient when they were passed to :meth:`_orm.Session.add` will be moved back to the :term:`transient` state, and will no longer be present within this :class:`_orm.Session`. .. seealso:: :meth:`_orm.Session.add_all` :ref:`session_adding` - at :ref:`session_basics` z Session.add()N)r� �_flush_warningr r� r r� r� �_save_or_update_state)r� r� r r r� r� r� r� r� x s "z Session.addzIterable[object])� instancesr� c C s, | j r| �d� |D ]}| j|dd� qdS )a2 Add the given collection of instances to this :class:`_orm.Session`. See the documentation for :meth:`_orm.Session.add` for a general behavioral description. .. seealso:: :meth:`_orm.Session.add` :ref:`session_adding` - at :ref:`session_basics` zSession.add_all()F)r N)r� r r� )r� r r� r� r� r� �add_all� s zSession.add_allr� c C sF d|_ | �|� t|�}|jd|| jd�D ]\}}}}| �|� q*d S )NFz save-update)Zhalt_on)r �_save_or_update_implr) r� �_contains_state)r� r r� r� r� r� r� r� r� r� r � s �z Session._save_or_update_statec C sf | j r| �d� zt�|�}W n2 tjyP } zt�|�|�W Y d}~n d}~0 0 | j||dd� dS )aV Mark an instance as deleted. The object is assumed to be either :term:`persistent` or :term:`detached` when passed; after the method is called, the object will remain in the :term:`persistent` state until the next flush proceeds. During this time, the object will also be a member of the :attr:`_orm.Session.deleted` collection. When the next flush proceeds, the object will move to the :term:`deleted` state, indicating a ``DELETE`` statement was emitted for its row within the current transaction. When the transaction is successfully committed, the deleted object is moved to the :term:`detached` state and is no longer present within this :class:`_orm.Session`. .. seealso:: :ref:`session_deleting` - at :ref:`session_basics` zSession.delete()NT)�head)r� r r r� r r� r� � _delete_impl�r� r� r r� r� r� r� �delete� s "zSession.delete)r r� r r� c C s� |j d u r&|r"t�dt|� ��nd S | �||�}|| jv r@d S | j�|� |r\| �||� |rvt |j j � d|��}nd }|| j|< |r�t r�|d us�J �|D ]\}}}} | �||d� q�d S )N� Instance '%s' is not persistedr F)rK r� r� r/ �_before_attachr rI r� � _after_attachr� r� r� r� r r ) r� r r� r � to_attachZcascade_statesr� r� r� r� r� r� r� r � s. � � zSession._delete_impl��options�populate_existingr� r� r� r� �_PKIdentityArgumentz Optional[Sequence[ORMOption]]z Optional[_O]) r� r� r$ r% r� r� r� r� r� c C s | j ||tj||||||d� S )a� Return an instance based on the given primary key identifier, or ``None`` if not found. E.g.:: my_user = session.get(User, 5) some_object = session.get(VersionedFoo, (5, 10)) some_object = session.get(VersionedFoo, {"id": 5, "version_id": 10}) .. versionadded:: 1.4 Added :meth:`_orm.Session.get`, which is moved from the now legacy :meth:`_orm.Query.get` method. :meth:`_orm.Session.get` is special in that it provides direct access to the identity map of the :class:`.Session`. If the given primary key identifier is present in the local identity map, the object is returned directly from this collection and no SQL is emitted, unless the object has been marked fully expired. If not present, a SELECT is performed in order to locate the object. :meth:`_orm.Session.get` also will perform a check if the object is present in the identity map and marked as expired - a SELECT is emitted to refresh the object as well as to ensure that the row is still present. If not, :class:`~sqlalchemy.orm.exc.ObjectDeletedError` is raised. :param entity: a mapped class or :class:`.Mapper` indicating the type of entity to be loaded. :param ident: A scalar, tuple, or dictionary representing the primary key. For a composite (e.g. multiple column) primary key, a tuple or dictionary should be passed. For a single-column primary key, the scalar calling form is typically the most expedient. If the primary key of a row is the value "5", the call looks like:: my_object = session.get(SomeClass, 5) The tuple form contains primary key values typically in the order in which they correspond to the mapped :class:`_schema.Table` object's primary key columns, or if the :paramref:`_orm.Mapper.primary_key` configuration parameter were used, in the order used for that parameter. For example, if the primary key of a row is represented by the integer digits "5, 10" the call would look like:: my_object = session.get(SomeClass, (5, 10)) The dictionary form should include as keys the mapped attribute names corresponding to each element of the primary key. If the mapped class has the attributes ``id``, ``version_id`` as the attributes which store the object's primary key value, the call would look like:: my_object = session.get(SomeClass, {"id": 5, "version_id": 10}) :param options: optional sequence of loader options which will be applied to the query, if one is emitted. :param populate_existing: causes the method to unconditionally emit a SQL query and refresh the object with the newly loaded data, regardless of whether or not the object is already present. :param with_for_update: optional boolean ``True`` indicating FOR UPDATE should be used, or may be a dictionary containing flags to indicate a more specific set of FOR UPDATE flags for the SELECT; flags should match the parameters of :meth:`_query.Query.with_for_update`. Supersedes the :paramref:`.Session.refresh.lockmode` parameter. :param execution_options: optional dictionary of execution options, which will be associated with the query execution if one is emitted. This dictionary can provide a subset of the options that are accepted by :meth:`_engine.Connection.execution_options`, and may also provide additional options understood only in an ORM context. .. versionadded:: 1.4.29 .. seealso:: :ref:`orm_queryguide_execution_options` - ORM-specific execution options :param bind_arguments: dictionary of additional arguments to determine the bind. May include "mapper", "bind", or other custom arguments. Contents of this dictionary are passed to the :meth:`.Session.get_bind` method. .. versionadded: 2.0.0rc1 :return: The object instance, or ``None``. r# )� _get_implr Zload_on_pk_identity) r� r� r� r$ r% r� r� r� r� r� r� r� r� � s o�z Session.getr! c C s0 | j ||||||||d�} | du r,t�d��| S )a+ Return exactly one instance based on the given primary key identifier, or raise an exception if not found. Raises :class:`_exc.NoResultFound` if the query selects no rows. For a detailed documentation of the arguments see the method :meth:`.Session.get`. .. versionadded:: 2.0.22 :return: The object instance. .. seealso:: :meth:`.Session.get` - equivalent method that instead returns ``None`` if no row was found with the provided primary key r# Nz&No row was found when one was required)r� r� Z NoResultFound) r� r� r� r$ r% r� r� r� r� r� r� r� r� �get_onez s � �zSession.get_onezCallable[..., _O]z$Optional[Sequence[ExecutableOption]]) r� r� � db_load_fnr$ r% r� r� r� r� r� c s t � �r,t� �tjv r,tjt� � } | � �� t|�} | d u sB| jsPt�d| ��t� t �} | snt j � d gd�� t � �t | j �kr�t�dd�dd� | j D �� ��| �rJ| j} | r�t| ��� �}|r�t � �� |D ]}� | � | | < q�z t� fdd�| jD ��� W nH t�yH } z.t�dd�d d� | jD �� �|�W Y d }~n d }~0 0 |�s�| j�s�|d u �r�| j| � ||| d �}|d u�r�t|| j��s�d S |S |tju�s�J �tj j }|�r�|d |i7 }t � | �� t!�}|d u�r�t"�#|�|_$|�r�|j%|� }|| |� |||| d �S ) Nz(Expected mapped class or mapper, got: %r)�defaultzoIncorrect number of values in identifier to formulate primary key for session.get(); primary key columns are %s�,c s s | ]}d | V qdS �z'%s'Nr� )r �cr� r� r� r � r z$Session._get_impl.<locals>.<genexpr>c 3 s | ]}� |j V qd S r� �rK �r �prop�r� r� r� r � s �z�Incorrect names of values in identifier to formulate primary key for session.get(); primary key attribute names are %s (synonym names are also accepted)c s s | ]}d |j V qdS r, r. r/ r� r� r� r � s �)r� r� r� Z_populate_existing)r� r� r� r� )&r# r� r Z_composite_gettersrB Z is_mapperr� r� r� r� r< Zto_listr� Z primary_keyr� r� Z _pk_synonymsr� r r� Z_identity_key_props�KeyErrorZalways_refreshr� r� r+ ZPASSIVE_CLASS_MISMATCHr r r r; r� Zset_label_stylerN rM r� Z_for_update_argr$ )r� r� r� r) r$ r% r� r� r� r� �getterr� Zis_dictZ pk_synonymsZ correct_keys�kr� r� r� r� r� r1 r� r' � s� ����� ����� � ���� ���� � � �zSession._get_impl)�loadr$ )r� r5 r$ r� c C sp | j r| �d� i }i }|r$| �� t|� | j}z0d| _| jt�|�t�|�||||d�W || _S || _0 dS )a Copy the state of a given instance into a corresponding instance within this :class:`.Session`. :meth:`.Session.merge` examines the primary key attributes of the source instance, and attempts to reconcile it with an instance of the same primary key in the session. If not found locally, it attempts to load the object from the database based on primary key, and if none can be located, creates a new instance. The state of each attribute on the source instance is then copied to the target instance. The resulting target instance is then returned by the method; the original source instance is left unmodified, and un-associated with the :class:`.Session` if not already. This operation cascades to associated instances if the association is mapped with ``cascade="merge"``. See :ref:`unitofwork_merging` for a detailed discussion of merging. :param instance: Instance to be merged. :param load: Boolean, when False, :meth:`.merge` switches into a "high performance" mode which causes it to forego emitting history events as well as all database access. This flag is used for cases such as transferring graphs of objects into a :class:`.Session` from a second level cache, or to transfer just-loaded objects into the :class:`.Session` owned by a worker thread or process without re-querying the database. The ``load=False`` use case adds the caveat that the given object has to be in a "clean" state, that is, has no pending changes to be flushed - even if the incoming object is detached from any :class:`.Session`. This is so that when the merge operation populates local attributes and cascades to related objects and collections, the values can be "stamped" onto the target object as is, without generating any history or attribute events, and without the need to reconcile the incoming data with any existing related objects or collections that might not be loaded. The resulting objects from ``load=False`` are always produced as "clean", so it is only appropriate that the given objects should be "clean" as well, else this suggests a mis-use of the method. :param options: optional sequence of loader options which will be applied to the :meth:`_orm.Session.get` method when the merge operation loads the existing version of the object from the database. .. versionadded:: 1.4.24 .. seealso:: :func:`.make_transient_to_detached` - provides for an alternative means of "merging" a single object into the :class:`.Session` zSession.merge()F)r5 r$ � _recursive�_resolve_conflict_mapN) r� r r� r, r� �_merger r� � instance_dict)r� r� r5 r$ r6 r7 r� r� r� r� �merge+ s* > � � z Session.merge)r$ �InstanceState[_O]rT zDict[Any, object]z#Dict[_IdentityKeyType[Any], object])r � state_dictr$ r5 r6 r7 r� c C s� t |�}||v r tt|| �S d}|j} | d u r�|| jv rLt�dt|� � |sZt� d��|� |�} t j | d vo�t �| d � p�|jo�t �| d � } nd} | j�| �} | d u �r2| r�| |v r�tt|| �} nb|�s|jr�t� d��|j�� } t�| �} | | _| �| � d}n"| �r2| j|j| d | d |d�} | d u �rj|j�� } t�| �} t�| �} d}| �| � nt�| �} t�| �} | ||< | || < || u�rJ|j d u�r |j |||j t j d �}|j | | |j t j d �}|t j u�r |t j u�r ||k�r t!�"d |t| �|f ��|j#| _#|j$| _$| �%|� |j&D ] }|�'| ||| | |||� �q*|�sn| �(| | j� | j)j*�+| d � |�r�| j)j*�,| d � | S ) NFzrInstance %s is already pending in this Session yet is being merged again; this is probably not what you want to doz�merge() with load=False option does not support objects transient (i.e. unpersisted) objects. flush() all changes on mapped instances before merging with load=False.r Tz�merge() with load=False option does not support objects marked as 'dirty'. flush() all changes on mapped instances before merging with load=False.r9 )r� r$ �r� z�Version id '%s' on merged state %s does not match existing version '%s'. Leave the version attribute unset when merging to update the most recent version.)-r) r r! rK r r< r[ r/ r� r� r r+ Z NEVER_SETr( r r r rI r� rO Z class_manager� new_instancer r� rM r� r9 r Zversion_id_colZ_get_state_attr_by_columnr. ZPASSIVE_NO_INITIALIZEZPASSIVE_NO_RESULTr ZStaleDataErrorZ load_pathr� Z_copy_callablesZiterate_propertiesr: � _commit_allr� r+ Z_sa_event_merge_wo_loadr5 )r� r r< r$ r5 r6 r7 r� r> rK Zkey_is_persistent�mergedZ merged_stateZ merged_dict�existing_versionZmerged_versionr0 r� r� r� r8 � s� ��� �� � � ���������� � �zSession._mergec C s" | j �|�s t�dt|� ��d S )Nz3Instance '%s' is not persistent within this Session)rI r r� r� r/ r� r� r� r� r� ! s ��z Session._validate_persistentc C sd |j d ur t�dt|� ��|�� }| �||�}|| jvrP|| j|< t| j�|_|r`| � ||� d S )NzGObject '%s' already has an identity - it can't be registered as pending) rK r� r� r/ r� r r r� Z insert_orderr! )r� r r� r" r� r� r� � _save_impl( s �� zSession._save_impl)r rF r� c C s� |j d u r t�dt|� ��|jrH|r6|js0d S |`nt�dt|� ��|�� }|d u r\d S | �||�}| j�|d � |r�| j � |� n | j � |� |r�| � ||� n|r�| j �| |� d S )Nr zsInstance '%s' has been deleted. Use the make_transient() function to send this object back to the transient state.)rK r� r� r/ r Z _attachedr� r r� rI rL r� r! r+ Zdeleted_to_persistent)r� r rF r� r" r� r� r� rM 7 s4 ��� zSession._update_implc C s$ |j d u r| �|� n | �|� d S r� )rK rB rM r� r� r� r� r _ s z Session._save_or_update_impl)r� r� c C sh zt �|�}W n2 tjy@ } zt�|�|�W Y d}~n d}~0 0 | �||�}d|_|rd| �||� dS )a Associate an object with this :class:`.Session` for related object loading. .. warning:: :meth:`.enable_relationship_loading` exists to serve special use cases and is not recommended for general use. Accesses of attributes mapped with :func:`_orm.relationship` will attempt to load a value from the database using this :class:`.Session` as the source of connectivity. The values will be loaded based on foreign key and primary key values present on this object - if not present, then those relationships will be unavailable. The object will be attached to this session, but will **not** participate in any persistence operations; its state for almost all purposes will remain either "transient" or "detached", except for the case of relationship loading. Also note that backrefs will often not work as expected. Altering a relationship-bound attribute on the target object may not fire off a backref event, if the effective value is what was already loaded from a foreign-key-holding value. The :meth:`.Session.enable_relationship_loading` method is similar to the ``load_on_pending`` flag on :func:`_orm.relationship`. Unlike that flag, :meth:`.Session.enable_relationship_loading` allows an object to remain transient while still being able to load related items. To make a transient object associated with a :class:`.Session` via :meth:`.Session.enable_relationship_loading` pending, add it to the :class:`.Session` using :meth:`.Session.add` normally. If the object instead represents an existing identity in the database, it should be merged using :meth:`.Session.merge`. :meth:`.Session.enable_relationship_loading` does not improve behavior when the ORM is used normally - object references should be constructed at the object level, not at the foreign key level, so that they are present in an ordinary way before flush() proceeds. This method is not intended for general use. .. seealso:: :paramref:`_orm.relationship.load_on_pending` - this flag allows per-relationship loading of many-to-ones on items that are pending. :func:`.make_transient_to_detached` - allows for an object to be added to a :class:`.Session` without SQL emitted, which then will unexpire attributes on access. NT)r r� r r� r� r Z _load_pendingr! )r� r� r r� r" r� r� r� �enable_relationship_loadinge s 7" z#Session.enable_relationship_loading)r r� r� c C sV | � � |j| jkrdS |jrD|jtv rDt�dt|�|j| jf ��| j�| |� dS )NFz>Object '%s' is already attached to session '%s' (this is '%s')T) r� r r� r� r� r� r/ r+ Z before_attach�r� r r� r� r� r� r � s ��zSession._before_attachc C sT | j |_|jr |jd u r ||_| j�| |� |jrB| j�| |� n| j�| |� d S r� ) r� r rO Z _strong_objr+ Z after_attachrK Zdetached_to_persistentZtransient_to_pendingrD r� r� r� r! � s zSession._after_attachc C sL zt �|�}W n2 tjy@ } zt�|�|�W Y d}~n d}~0 0 | �|�S )z�Return True if the instance is associated with this session. The instance may be pending or persistent within the Session for a result of True. N)r r� r r� r� r r r� r� r� � __contains__� s "zSession.__contains__zIterator[object]c C s t t| j�� �t| j�� � �S )zWIterate over all pending or persistent instances within this Session. )�iterr� r ro rI r� r� r� r� �__iter__� s �zSession.__iter__c C s || j v p| j�|�S r� )r rI r r� r� r� r� r � s zSession._contains_statezOptional[Sequence[Any]])�objectsr� c C sD | j rt�d��| �� r dS zd| _ | �|� W d| _ nd| _ 0 dS )a� Flush all the object changes to the database. Writes out all pending object creations, deletions and modifications to the database as INSERTs, DELETEs, UPDATEs, etc. Operations are automatically ordered by the Session's unit of work dependency solver. Database operations will be issued in the current transactional context and do not affect the state of the transaction, unless an error occurs, in which case the entire transaction is rolled back. You may flush() as often as you like within a transaction to move changes from Python to the database's transaction buffer. :param objects: Optional; restricts the flush operation to operate only on elements that are in the given collection. This feature is for an extremely narrow set of use cases where particular objects may need to be operated upon before the full flush() occurs. It is not intended for general use. zSession is already flushingNTF)r? r� r� rm �_flush)r� rH r� r� r� r@ � s z Session.flush)�methodr� c C s t �d| � d S )Nz�Usage of the '%s' operation is not currently supported within the execution stage of the flush process. Results may not be consistent. Consider using alternative event listeners or connection-level operations instead.)r< r[ )r� rJ r� r� r� r � s ��zSession._flush_warningc C s | j �� o| j o| j S r� )rI Zcheck_modifiedr r r� r� r� r� rm s ��zSession._is_cleanzOptional[Sequence[object]]c C s� | j }|s&| js&| js&| jj�� d S t| �}| jjrL| j�| ||� | j }t | j�}t | j�}t |�� |�}|r�t � }|D ]P}zt � |�}W n2 t jy� } zt �|�| �W Y d } ~ n d } ~ 0 0 |�|� q|nd }t � } |r�|�|��|�� |�} n|�|�� |�} | D ]h}t|��|�} | �o&|j} | �rJ| �sJ|j�rJ| �|g� n&|j|| d�}|�sfJ d��| �|� �q |�r�|�|�� | �} n |� | �} | D ]"}|j|dd�}|�s�J d���q�|j�s�d S | �� �� |_ }z�d| _ z|� � W d| _ nd| _ 0 | j� | |� |� � |�s`| jj�r`t!| jj�}t"j#j$dd� | jjD �| jd� t%�&d| � | j�'| |� |�(� W nB t%�)� � |j*dd � W d � n1 �s�0 Y Y n0 d S ) N)Zisdeletez*Failed to add object to the flush context!TFc S s g | ]}||j f�qS r� r r r� r� r� r e s �z"Session._flush.<locals>.<listcomp>)r9 z�Attribute history events accumulated on %d previously clean instances within inner-flush event handlers have been reset, and will not result in database updates. Consider using set_committed_value() within inner-flush event handlers to avoid this warning.�rz )+� _dirty_statesr r rI rQ rW r8 r+ Z before_flushr� � differencer r� r r� r� r� r� r r) Z _is_orphanZ has_identityr rG Zregister_objectZhas_workr� r; rf r� r� Z after_flushZfinalize_flush_changesr� rU r4 r r< r[ Zafter_flush_postexecrk rp rq )r� rH �dirtyZ flush_context�deleted�newZobjsetr� r r� � processed�procZ is_orphanZis_persistent_orphanZ_regrf Zlen_r� r� r� rI s� " ���� ���� zSession._flush)rH �return_defaults�update_changed_only�preserve_orderr� c C sh dd� |D �}|s"t |dd� d�}ddd�d d �}t�||�D ]$\\}}} | j|| |d ||d d � q>dS )a� Perform a bulk save of the given list of objects. .. legacy:: This method is a legacy feature as of the 2.0 series of SQLAlchemy. For modern bulk INSERT and UPDATE, see the sections :ref:`orm_queryguide_bulk_insert` and :ref:`orm_queryguide_bulk_update`. For general INSERT and UPDATE of existing ORM mapped objects, prefer standard :term:`unit of work` data management patterns, introduced in the :ref:`unified_tutorial` at :ref:`tutorial_orm_data_manipulation`. SQLAlchemy 2.0 now uses :ref:`engine_insertmanyvalues` with modern dialects which solves previous issues of bulk INSERT slowness. :param objects: a sequence of mapped object instances. The mapped objects are persisted as is, and are **not** associated with the :class:`.Session` afterwards. For each object, whether the object is sent as an INSERT or an UPDATE is dependent on the same rules used by the :class:`.Session` in traditional operation; if the object has the :attr:`.InstanceState.key` attribute set, then the object is assumed to be "detached" and will result in an UPDATE. Otherwise, an INSERT is used. In the case of an UPDATE, statements are grouped based on which attributes have changed, and are thus to be the subject of each SET clause. If ``update_changed_only`` is False, then all attributes present within each object are applied to the UPDATE statement, which may help in allowing the statements to be grouped together into a larger executemany(), and will also reduce the overhead of checking history on attributes. :param return_defaults: when True, rows that are missing values which generate defaults, namely integer primary key defaults and sequences, will be inserted **one at a time**, so that the primary key value is available. In particular this will allow joined-inheritance and other multi-table mappings to insert correctly without the need to provide primary key values ahead of time; however, :paramref:`.Session.bulk_save_objects.return_defaults` **greatly reduces the performance gains** of the method overall. It is strongly advised to please use the standard :meth:`_orm.Session.add_all` approach. :param update_changed_only: when True, UPDATE statements are rendered based on those attributes in each state that have logged changes. When False, all attributes present are rendered into the SET clause with the exception of primary key attributes. :param preserve_order: when True, the order of inserts and updates matches exactly the order in which the objects are given. When False, common types of objects are grouped into inserts and updates, to allow for more batching opportunities. .. seealso:: :doc:`queryguide/dml` :meth:`.Session.bulk_insert_mappings` :meth:`.Session.bulk_update_mappings` c s s | ]}t �|�V qd S r� )r r� )r r� r� r� r� r � r z,Session.bulk_save_objects.<locals>.<genexpr>c S s t | j�| jd ufS r� )�idr� rK r r� r� r� �<lambda>� r z+Session.bulk_save_objects.<locals>.<lambda>r. r; zTuple[Mapper[_O], bool]r� c S s | j | jd ufS r� )r� rK r r� r� r� � grouping_key� s z/Session.bulk_save_objects.<locals>.grouping_keyTF��isupdate�isstatesrS rT � render_nullsN)�sortedr� �groupby�_bulk_save_mappings) r� rH rS rT rU Z obj_statesrX r� rZ r r� r� r� �bulk_save_objects� s& K���zSession.bulk_save_objectsr� zIterable[Dict[str, Any]])r� �mappingsrS r\ r� c C s | j ||dd|d|d� dS )a= Perform a bulk insert of the given list of mapping dictionaries. .. legacy:: This method is a legacy feature as of the 2.0 series of SQLAlchemy. For modern bulk INSERT and UPDATE, see the sections :ref:`orm_queryguide_bulk_insert` and :ref:`orm_queryguide_bulk_update`. The 2.0 API shares implementation details with this method and adds new features as well. :param mapper: a mapped class, or the actual :class:`_orm.Mapper` object, representing the single kind of object represented within the mapping list. :param mappings: a sequence of dictionaries, each one containing the state of the mapped row to be inserted, in terms of the attribute names on the mapped class. If the mapping refers to multiple tables, such as a joined-inheritance mapping, each dictionary must contain all keys to be populated into all tables. :param return_defaults: when True, the INSERT process will be altered to ensure that newly generated primary key values will be fetched. The rationale for this parameter is typically to enable :ref:`Joined Table Inheritance <joined_inheritance>` mappings to be bulk inserted. .. note:: for backends that don't support RETURNING, the :paramref:`_orm.Session.bulk_insert_mappings.return_defaults` parameter can significantly decrease performance as INSERT statements can no longer be batched. See :ref:`engine_insertmanyvalues` for background on which backends are affected. :param render_nulls: When True, a value of ``None`` will result in a NULL value being included in the INSERT statement, rather than the column being omitted from the INSERT. This allows all the rows being INSERTed to have the identical set of columns which allows the full set of rows to be batched to the DBAPI. Normally, each column-set that contains a different combination of NULL values than the previous row must omit a different series of columns from the rendered INSERT statement, which means it must be emitted as a separate statement. By passing this flag, the full set of rows are guaranteed to be batchable into one batch; the cost however is that server-side defaults which are invoked by an omitted column will be skipped, so care must be taken to ensure that these are not necessary. .. warning:: When this flag is set, **server side default SQL values will not be invoked** for those columns that are inserted as NULL; the NULL value will be sent explicitly. Care must be taken to ensure that no server-side default functions need to be invoked for the operation as a whole. .. seealso:: :doc:`queryguide/dml` :meth:`.Session.bulk_save_objects` :meth:`.Session.bulk_update_mappings` FrY N�r_ )r� r� ra rS r\ r� r� r� �bulk_insert_mappings� s I�z Session.bulk_insert_mappings)r� ra r� c C s | j ||dddddd� dS )aa Perform a bulk update of the given list of mapping dictionaries. .. legacy:: This method is a legacy feature as of the 2.0 series of SQLAlchemy. For modern bulk INSERT and UPDATE, see the sections :ref:`orm_queryguide_bulk_insert` and :ref:`orm_queryguide_bulk_update`. The 2.0 API shares implementation details with this method and adds new features as well. :param mapper: a mapped class, or the actual :class:`_orm.Mapper` object, representing the single kind of object represented within the mapping list. :param mappings: a sequence of dictionaries, each one containing the state of the mapped row to be updated, in terms of the attribute names on the mapped class. If the mapping refers to multiple tables, such as a joined-inheritance mapping, each dictionary may contain keys corresponding to all tables. All those keys which are present and are not part of the primary key are applied to the SET clause of the UPDATE statement; the primary key values, which are required, are applied to the WHERE clause. .. seealso:: :doc:`queryguide/dml` :meth:`.Session.bulk_insert_mappings` :meth:`.Session.bulk_save_objects` TFrY Nrb )r� r� ra r� r� r� �bulk_update_mappings? s &�z Session.bulk_update_mappingsz<Union[Iterable[InstanceState[_O]], Iterable[Dict[str, Any]]])r� ra rZ r[ rS rT r\ r� c C s� t |�}d| _| �� �� }z�z<|r8tj|||||d� ntj||||||d� |�� W n@ t� � � |j dd� W d � n1 s�0 Y Y n0 W d| _nd| _0 d S )NT)r[ rT )r[ rS r\ rK F) r' r? r� r; r Z _bulk_updateZ _bulk_insertrk r< rp rq ) r� r� ra rZ r[ rS rT r\ rf r� r� r� r_ o s2 �� 2zSession._bulk_save_mappings)r� �include_collectionsr� c C sp t |�}|jsdS |j}|jjD ]J}|s4t|jd�s t|jd�sBq |jj||tj d�\}}}|sd|r dS q dS )aD Return ``True`` if the given instance has locally modified attributes. This method retrieves the history for each instrumented attribute on the instance and performs a comparison of the current value to its previously flushed or committed value, if any. It is in effect a more expensive and accurate version of checking for the given instance in the :attr:`.Session.dirty` collection; a full test for each attribute's net "dirty" status is performed. E.g.:: return session.is_modified(someobject) A few caveats to this method apply: * Instances present in the :attr:`.Session.dirty` collection may report ``False`` when tested with this method. This is because the object may have received change events via attribute mutation, thus placing it in :attr:`.Session.dirty`, but ultimately the state is the same as that loaded from the database, resulting in no net change here. * Scalar attributes may not have recorded the previously set value when a new value was applied, if the attribute was not loaded, or was expired, at the time the new value was received - in these cases, the attribute is assumed to have a change, even if there is ultimately no net change against its database value. SQLAlchemy in most cases does not need the "old" value when a set event occurs, so it skips the expense of a SQL call if the old value isn't present, based on the assumption that an UPDATE of the scalar value is usually needed, and in those few cases where it isn't, is less expensive on average than issuing a defensive SELECT. The "old" value is fetched unconditionally upon set only if the attribute container has the ``active_history`` flag set to ``True``. This flag is set typically for primary key attributes and scalar object references that are not a simple many-to-one. To set this flag for any arbitrary mapped column, use the ``active_history`` argument with :func:`.column_property`. :param instance: mapped instance to be tested for pending changes. :param include_collections: Indicates if multivalued collections should be included in the operation. Setting this to ``False`` is a way to detect only local-column based properties (i.e. scalar columns or many-to-one foreign keys) that would result in an UPDATE for this instance upon flush. FZget_collection� get_historyr= TN) r- rO r� r� r �hasattr�implrf r. r� ) r� r� re r Zdict_�attr�addedZ unchangedrO r� r� r� � is_modified� s$ 5 � � �� zSession.is_modifiedc C s | j du p| j jS )a4 True if this :class:`.Session` not in "partial rollback" state. .. versionchanged:: 1.4 The :class:`_orm.Session` no longer begins a new transaction immediately, so this attribute will be False when the :class:`_orm.Session` is first instantiated. "partial rollback" state typically indicates that the flush process of the :class:`_orm.Session` has failed, and that the :meth:`_orm.Session.rollback` method must be emitted in order to fully roll back the transaction. If this :class:`_orm.Session` is not in a transaction at all, the :class:`_orm.Session` will autobegin when it is first used, so in this case :attr:`_orm.Session.is_active` will return True. Otherwise, if this :class:`_orm.Session` is within a transaction, and that transaction has not been rolled back internally, the :attr:`_orm.Session.is_active` will also return True. .. seealso:: :ref:`faq_session_rollback` :meth:`_orm.Session.in_transaction` N)r* r2 r� r� r� r� r2 � s zSession.is_activec C s | j �� S )z�The set of all persistent states considered dirty. This method returns all states that were modified including those that were possibly deleted. )rI rL r� r� r� r� rL s zSession._dirty_statesrO c s t � fdd�� jD ��S )aZ The set of all persistent instances considered dirty. E.g.:: some_mapped_object in session.dirty Instances are considered dirty when they were modified but not deleted. Note that this 'dirty' calculation is 'optimistic'; most attribute-setting or collection modification operations will mark an instance as 'dirty' and place it in this set, even if there is no net change to the attribute's value. At flush time, the value of each attribute is compared to its previously saved value, and if there's no net change, no SQL operation will occur (this is a more expensive operation so it's only done at flush time). To check if an instance has actionable net changes to its attributes, use the :meth:`.Session.is_modified` method. c s g | ]}|� j vr|�� �qS r� )r r� r r� r� r� r % s �z!Session.dirty.<locals>.<listcomp>)rO rL r� r� r� r� rN s ��z Session.dirtyc C s t �t| j�� ��S )zDThe set of all instances marked as 'deleted' within this ``Session``)r< rO r� r ro r� r� r� r� rO , s zSession.deletedc C s t �t| j�� ��S )zAThe set of all instances marked as 'new' within this ``Session``.)r< rO r� r ro r� r� r� r� rP 2 s z Session.new)N)F)F)NN)N)N)N)N)N)N)N)N)N)N)N)N)N)N)F)N)NN)N)N)F)T)F)N)N)FTT)FF)T)fr� r� r� r� Z _is_asyncior rJ r� r� r� r� r� r� � contextlib�contextmanagerr� r_ ra r� r� r< Zmemoized_propertyr� r� rb r^ rq rk rh r9 r7 r � EMPTY_DICTr� r� r� r� rc r� r� r� r� r� r� r� r6 r r. Z PASSIVE_OFFr� Znon_memoized_propertyr� Z langhelpersZtag_method_for_warningsr� Z SAWarningr� r� r� r� r� r� r� rG r r r r� r r r r r� r( r' r: r8 r� rB rM r rC r r! rE rG r r@ r rm rI r` rc rd r_ rk r r2 rL rN rO rP r� r� r� r� r{ � s@ ��* 0 7& �3� ��" ��"�� �� �� �� �� E�� �� �� �� �� �� &)$ �� � ;� �y$�-� �S # ,�0 �08�4 �&\�2 �(A " z � m �"S 0$*�L r{ r� c @ s� e Zd ZU dZded< ed#dddd�dddddd d �d d ��Zed$dddd�d ddddd d�dd ��Zd%edddd�dddddd d �dd �Zdd�dd�Zd dd�dd�Z d d d �d d �Z d d�d!d"�Z dS )&r} a� A configurable :class:`.Session` factory. The :class:`.sessionmaker` factory generates new :class:`.Session` objects when called, creating them given the configurational arguments established here. e.g.:: from sqlalchemy import create_engine from sqlalchemy.orm import sessionmaker # an Engine, which the Session will use for connection # resources engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/") Session = sessionmaker(engine) with Session() as session: session.add(some_object) session.add(some_other_object) session.commit() Context manager use is optional; otherwise, the returned :class:`_orm.Session` object may be closed explicitly via the :meth:`_orm.Session.close` method. Using a ``try:/finally:`` block is optional, however will ensure that the close takes place even if there are database errors:: session = Session() try: session.add(some_object) session.add(some_other_object) session.commit() finally: session.close() :class:`.sessionmaker` acts as a factory for :class:`_orm.Session` objects in the same way as an :class:`_engine.Engine` acts as a factory for :class:`_engine.Connection` objects. In this way it also includes a :meth:`_orm.sessionmaker.begin` method, that provides a context manager which both begins and commits a transaction, as well as closes out the :class:`_orm.Session` when complete, rolling back the transaction if any errors occur:: Session = sessionmaker(engine) with Session.begin() as session: session.add(some_object) session.add(some_other_object) # commits transaction, closes session .. versionadded:: 1.4 When calling upon :class:`_orm.sessionmaker` to construct a :class:`_orm.Session`, keyword arguments may also be passed to the method; these arguments will override that of the globally configured parameters. Below we use a :class:`_orm.sessionmaker` bound to a certain :class:`_engine.Engine` to produce a :class:`_orm.Session` that is instead bound to a specific :class:`_engine.Connection` procured from that engine:: Session = sessionmaker(engine) # bind an individual session to a connection with engine.connect() as connection: with Session(bind=connection) as session: ... # work with session The class also includes a method :meth:`_orm.sessionmaker.configure`, which can be used to specify additional keyword arguments to the factory, which will take effect for subsequent :class:`.Session` objects generated. This is usually used to associate one or more :class:`_engine.Engine` objects with an existing :class:`.sessionmaker` factory before it is first used:: # application starts, sessionmaker does not have # an engine bound yet Session = sessionmaker() # ... later, when an engine URL is read from a configuration # file or other events allow the engine to be created engine = create_engine("sqlite:///foo.db") Session.configure(bind=engine) sess = Session() # work with session .. seealso:: :ref:`session_getting` - introductory text on creating sessions using :class:`.sessionmaker`. zType[_S]r� .)r� rT r� r� r� r� r )r8 r� r� rT r� r� c K s d S r� r� �r� r8 r� r� rT r� r� r� r� r� r� � s zsessionmaker.__init__z'sessionmaker[Session]'�r� r8 r� rT r� r� c K s d S r� r� rp r� r� r� r� � s NT)r� r� rT r� c K sD ||d< ||d< ||d< |dur(||d< || _ t|j|fi �| _dS )a< Construct a new :class:`.sessionmaker`. All arguments here except for ``class_`` correspond to arguments accepted by :class:`.Session` directly. See the :meth:`.Session.__init__` docstring for more details on parameters. :param bind: a :class:`_engine.Engine` or other :class:`.Connectable` with which newly created :class:`.Session` objects will be associated. :param class\_: class to use in order to create new :class:`.Session` objects. Defaults to :class:`.Session`. :param autoflush: The autoflush setting to use with newly created :class:`.Session` objects. .. seealso:: :ref:`session_flushing` - additional background on autoflush :param expire_on_commit=True: the :paramref:`_orm.Session.expire_on_commit` setting to use with newly created :class:`.Session` objects. :param info: optional dictionary of information that will be available via :attr:`.Session.info`. Note this dictionary is *updated*, not replaced, when the ``info`` parameter is specified to the specific :class:`.Session` construction operation. :param \**kw: all other keyword arguments are passed to the constructor of newly created :class:`.Session` objects. r8 r� rT Nr� )r� r� r� r� ro r� r� r� r� � s )z%contextlib.AbstractContextManager[_S]r� c C s | � }|� � S )am Produce a context manager that both provides a new :class:`_orm.Session` as well as a transaction that commits. e.g.:: Session = sessionmaker(some_engine) with Session.begin() as session: session.add(some_object) # commits transaction, closes session .. versionadded:: 1.4 )r� )r� r� r� r� r� rb � s zsessionmaker.beginr� )�local_kwr� c K s` | j �� D ]D\}}|dkrBd|v rB|�� }|�|d � ||d< q |�||� q | jf i |��S )ap Produce a new :class:`.Session` object using the configuration established in this :class:`.sessionmaker`. In Python, the ``__call__`` method is invoked on an object when it is "called" in the same way as a function:: Session = sessionmaker(some_engine) session = Session() # invokes sessionmaker.__call__() r� )r� rH �copyr� r� r� )r� rq r4 �vr� r� r� r� r� � s zsessionmaker.__call__r� )�new_kwr� c K s | j �|� dS )z�(Re)configure the arguments for this sessionmaker. e.g.:: Session = sessionmaker() Session.configure(bind=create_engine("sqlite://")) N)r� r� )r� rt r� r� r� � configure s zsessionmaker.configurer, c C s, d| j j| jjd�dd� | j�� D ��f S )Nz%s(class_=%r, %s)r� c s s | ]\}}d ||f V qdS )z%s=%rNr� )r r4 rs r� r� r� r r z(sessionmaker.__repr__.<locals>.<genexpr>)� __class__r� r� r� r� rH r� r� r� r� �__repr__ s �zsessionmaker.__repr__).).)N) r� r� r� r� r r r� r{ rb r� ru rw r� r� r� r� r} < s6 ^ �� �� �� 3 r} r� r� c C s t �� D ] } | �� qdS )aO Close all sessions in memory. This function consults a global registry of all :class:`.Session` objects and calls :meth:`.Session.close` on them, which resets them to a clean state. This function is not for general use but may be useful for test suites within the teardown scheme. .. versionadded:: 1.3 N)r� ro rc )r r� r� r� r $ s r r� r� c C sN t �| �}t|�}|r"|�|g� |j�� |jr6|`|jr@|`|jrJ|`dS )ao Alter the state of the given instance so that it is :term:`transient`. .. note:: :func:`.make_transient` is a special-case function for advanced use cases only. The given mapped instance is assumed to be in the :term:`persistent` or :term:`detached` state. The function will remove its association with any :class:`.Session` as well as its :attr:`.InstanceState.identity`. The effect is that the object will behave as though it were newly constructed, except retaining any attribute / collection values that were loaded at the time of the call. The :attr:`.InstanceState.deleted` flag is also reset if this object had been deleted as a result of using :meth:`.Session.delete`. .. warning:: :func:`.make_transient` does **not** "unexpire" or otherwise eagerly load ORM-mapped attributes that are not currently loaded at the time the function is called. This includes attributes which: * were expired via :meth:`.Session.expire` * were expired as the natural effect of committing a session transaction, e.g. :meth:`.Session.commit` * are normally :term:`lazy loaded` but are not currently loaded * are "deferred" (see :ref:`orm_queryguide_column_deferral`) and are not yet loaded * were not present in the query which loaded this object, such as that which is common in joined table inheritance and other scenarios. After :func:`.make_transient` is called, unloaded attributes such as those above will normally resolve to the value ``None`` when accessed, or an empty collection for a collection-oriented attribute. As the object is transient and un-associated with any database identity, it will no longer retrieve these values. .. seealso:: :func:`.make_transient_to_detached` N) r r� r� rG Zexpired_attributesrW Z callablesrK r )r� r rR r� r� r� r� 6 s / r� c C sX t �| �}|js|jr t�d��|j�|�|_|jr8|`|� |j � |� |j |j � dS )a� Make the given transient instance :term:`detached`. .. note:: :func:`.make_transient_to_detached` is a special-case function for advanced use cases only. All attribute history on the given instance will be reset as though the instance were freshly loaded from a query. Missing attributes will be marked as expired. The primary key attributes of the object, which are required, will be made into the "key" of the instance. The object can then be added to a session, or merged possibly with the load=False flag, at which point it will look as if it were loaded that way, without emitting SQL. This is a special use case function that differs from a normal call to :meth:`.Session.merge` in that a given persistent state can be manufactured without any SQL calls. .. seealso:: :func:`.make_transient` :meth:`.Session.enable_relationship_loading` z Given object must be transientN) r r� r rK r� r� r� r r r? r� r� Zunloaded)r� r r� r� r� r� w s r� c C sN zt �| �}W n2 tjy@ } zt�| �|�W Y d}~nd}~0 0 t|�S dS )z�Return the :class:`.Session` to which the given instance belongs. This is essentially the same as the :attr:`.InstanceState.session` accessor. See that attribute for details. N)r r� r r� r� r� )r� r r� r� r� r� r� � s "r� )�r� � __future__r rl �enumr r� r{ �typingr r r r r r r r r r r r r r r r r r rA � r r r r r r r r r rU Z_typingr! r" r# r$ r& �baser' r( r) r* r+ r, r- r. r/ r0 r1 r2 r3 r4 Z state_changesr5 r6 r7 Z unitofworkr8 r: r� r; r< r= r> Z engine.utilr? �eventr@ rA Z inspectionrB rC rD rE rF rG rH rI Zsql.baserJ rK Z sql.schemarL Zsql.selectablerM rN rO Z util.typingrP rQ rR rS rT rU Z interfacesrV rW r� rX Z path_registryrY rZ r[ r\ r] r^ Z engine.baser_ r` Zengine.interfacesra rb rc rd Z engine.resultre rf Z sql._typingrg rh ri rj rk rl rm rn ro rp rq Z_TCCArr rs Zsql.dmlrt Z sql.elementsru Z sql.rolesrv rw rx ry �__all__�WeakValueDictionaryr� r r& r, r� Z_EntityBindKeyr� rY r� r� r� r� r� �tupler� r� r� r� r� r� Z MemoizedSlotsr~ r r| r& r{ r� r} r r� r� r� �counterr� r� r� r� r� �<module> s| � �2 � / ` % iA' sqlalchemy/orm/util.py 0000755 00000236011 15125143220 0011033 0 ustar 00 # orm/util.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: allow-untyped-defs, allow-untyped-calls from __future__ import annotations import enum import functools import re import types import typing from typing import AbstractSet from typing import Any from typing import Callable from typing import cast from typing import Dict from typing import FrozenSet from typing import Generic from typing import Iterable from typing import Iterator from typing import List from typing import Match from typing import Optional from typing import Sequence from typing import Tuple from typing import Type from typing import TYPE_CHECKING from typing import TypeVar from typing import Union import weakref from . import attributes # noqa from . import exc from . import exc as orm_exc from ._typing import _O from ._typing import insp_is_aliased_class from ._typing import insp_is_mapper from ._typing import prop_is_relationship from .base import _class_to_mapper as _class_to_mapper from .base import _MappedAnnotationBase from .base import _never_set as _never_set # noqa: F401 from .base import _none_only_set as _none_only_set # noqa: F401 from .base import _none_set as _none_set # noqa: F401 from .base import attribute_str as attribute_str # noqa: F401 from .base import class_mapper as class_mapper from .base import DynamicMapped from .base import InspectionAttr as InspectionAttr from .base import instance_str as instance_str # noqa: F401 from .base import Mapped from .base import object_mapper as object_mapper from .base import object_state as object_state # noqa: F401 from .base import opt_manager_of_class from .base import ORMDescriptor from .base import state_attribute_str as state_attribute_str # noqa: F401 from .base import state_class_str as state_class_str # noqa: F401 from .base import state_str as state_str # noqa: F401 from .base import WriteOnlyMapped from .interfaces import CriteriaOption from .interfaces import MapperProperty as MapperProperty from .interfaces import ORMColumnsClauseRole from .interfaces import ORMEntityColumnsClauseRole from .interfaces import ORMFromClauseRole from .path_registry import PathRegistry as PathRegistry from .. import event from .. import exc as sa_exc from .. import inspection from .. import sql from .. import util from ..engine.result import result_tuple from ..sql import coercions from ..sql import expression from ..sql import lambdas from ..sql import roles from ..sql import util as sql_util from ..sql import visitors from ..sql._typing import is_selectable from ..sql.annotation import SupportsCloneAnnotations from ..sql.base import ColumnCollection from ..sql.cache_key import HasCacheKey from ..sql.cache_key import MemoizedHasCacheKey from ..sql.elements import ColumnElement from ..sql.elements import KeyedColumnElement from ..sql.selectable import FromClause from ..util.langhelpers import MemoizedSlots from ..util.typing import de_stringify_annotation as _de_stringify_annotation from ..util.typing import eval_name_only as _eval_name_only from ..util.typing import fixup_container_fwd_refs from ..util.typing import get_origin from ..util.typing import is_origin_of_cls from ..util.typing import Literal from ..util.typing import Protocol if typing.TYPE_CHECKING: from ._typing import _EntityType from ._typing import _IdentityKeyType from ._typing import _InternalEntityType from ._typing import _ORMCOLEXPR from .context import _MapperEntity from .context import ORMCompileState from .mapper import Mapper from .path_registry import AbstractEntityRegistry from .query import Query from .relationships import RelationshipProperty from ..engine import Row from ..engine import RowMapping from ..sql._typing import _CE from ..sql._typing import _ColumnExpressionArgument from ..sql._typing import _EquivalentColumnMap from ..sql._typing import _FromClauseArgument from ..sql._typing import _OnClauseArgument from ..sql._typing import _PropagateAttrsType from ..sql.annotation import _SA from ..sql.base import ReadOnlyColumnCollection from ..sql.elements import BindParameter from ..sql.selectable import _ColumnsClauseElement from ..sql.selectable import Select from ..sql.selectable import Selectable from ..sql.visitors import anon_map from ..util.typing import _AnnotationScanType _T = TypeVar("_T", bound=Any) all_cascades = frozenset( ( "delete", "delete-orphan", "all", "merge", "expunge", "save-update", "refresh-expire", "none", ) ) _de_stringify_partial = functools.partial( functools.partial, locals_=util.immutabledict( { "Mapped": Mapped, "WriteOnlyMapped": WriteOnlyMapped, "DynamicMapped": DynamicMapped, } ), ) # partial is practically useless as we have to write out the whole # function and maintain the signature anyway class _DeStringifyAnnotation(Protocol): def __call__( self, cls: Type[Any], annotation: _AnnotationScanType, originating_module: str, *, str_cleanup_fn: Optional[Callable[[str, str], str]] = None, include_generic: bool = False, ) -> Type[Any]: ... de_stringify_annotation = cast( _DeStringifyAnnotation, _de_stringify_partial(_de_stringify_annotation) ) class _EvalNameOnly(Protocol): def __call__(self, name: str, module_name: str) -> Any: ... eval_name_only = cast(_EvalNameOnly, _de_stringify_partial(_eval_name_only)) class CascadeOptions(FrozenSet[str]): """Keeps track of the options sent to :paramref:`.relationship.cascade`""" _add_w_all_cascades = all_cascades.difference( ["all", "none", "delete-orphan"] ) _allowed_cascades = all_cascades _viewonly_cascades = ["expunge", "all", "none", "refresh-expire", "merge"] __slots__ = ( "save_update", "delete", "refresh_expire", "merge", "expunge", "delete_orphan", ) save_update: bool delete: bool refresh_expire: bool merge: bool expunge: bool delete_orphan: bool def __new__( cls, value_list: Optional[Union[Iterable[str], str]] ) -> CascadeOptions: if isinstance(value_list, str) or value_list is None: return cls.from_string(value_list) # type: ignore values = set(value_list) if values.difference(cls._allowed_cascades): raise sa_exc.ArgumentError( "Invalid cascade option(s): %s" % ", ".join( [ repr(x) for x in sorted( values.difference(cls._allowed_cascades) ) ] ) ) if "all" in values: values.update(cls._add_w_all_cascades) if "none" in values: values.clear() values.discard("all") self = super().__new__(cls, values) self.save_update = "save-update" in values self.delete = "delete" in values self.refresh_expire = "refresh-expire" in values self.merge = "merge" in values self.expunge = "expunge" in values self.delete_orphan = "delete-orphan" in values if self.delete_orphan and not self.delete: util.warn("The 'delete-orphan' cascade option requires 'delete'.") return self def __repr__(self): return "CascadeOptions(%r)" % (",".join([x for x in sorted(self)])) @classmethod def from_string(cls, arg): values = [c for c in re.split(r"\s*,\s*", arg or "") if c] return cls(values) def _validator_events(desc, key, validator, include_removes, include_backrefs): """Runs a validation method on an attribute value to be set or appended. """ if not include_backrefs: def detect_is_backref(state, initiator): impl = state.manager[key].impl return initiator.impl is not impl if include_removes: def append(state, value, initiator): if initiator.op is not attributes.OP_BULK_REPLACE and ( include_backrefs or not detect_is_backref(state, initiator) ): return validator(state.obj(), key, value, False) else: return value def bulk_set(state, values, initiator): if include_backrefs or not detect_is_backref(state, initiator): obj = state.obj() values[:] = [ validator(obj, key, value, False) for value in values ] def set_(state, value, oldvalue, initiator): if include_backrefs or not detect_is_backref(state, initiator): return validator(state.obj(), key, value, False) else: return value def remove(state, value, initiator): if include_backrefs or not detect_is_backref(state, initiator): validator(state.obj(), key, value, True) else: def append(state, value, initiator): if initiator.op is not attributes.OP_BULK_REPLACE and ( include_backrefs or not detect_is_backref(state, initiator) ): return validator(state.obj(), key, value) else: return value def bulk_set(state, values, initiator): if include_backrefs or not detect_is_backref(state, initiator): obj = state.obj() values[:] = [validator(obj, key, value) for value in values] def set_(state, value, oldvalue, initiator): if include_backrefs or not detect_is_backref(state, initiator): return validator(state.obj(), key, value) else: return value event.listen(desc, "append", append, raw=True, retval=True) event.listen(desc, "bulk_replace", bulk_set, raw=True) event.listen(desc, "set", set_, raw=True, retval=True) if include_removes: event.listen(desc, "remove", remove, raw=True, retval=True) def polymorphic_union( table_map, typecolname, aliasname="p_union", cast_nulls=True ): """Create a ``UNION`` statement used by a polymorphic mapper. See :ref:`concrete_inheritance` for an example of how this is used. :param table_map: mapping of polymorphic identities to :class:`_schema.Table` objects. :param typecolname: string name of a "discriminator" column, which will be derived from the query, producing the polymorphic identity for each row. If ``None``, no polymorphic discriminator is generated. :param aliasname: name of the :func:`~sqlalchemy.sql.expression.alias()` construct generated. :param cast_nulls: if True, non-existent columns, which are represented as labeled NULLs, will be passed into CAST. This is a legacy behavior that is problematic on some backends such as Oracle - in which case it can be set to False. """ colnames: util.OrderedSet[str] = util.OrderedSet() colnamemaps = {} types = {} for key in table_map: table = table_map[key] table = coercions.expect( roles.StrictFromClauseRole, table, allow_select=True ) table_map[key] = table m = {} for c in table.c: if c.key == typecolname: raise sa_exc.InvalidRequestError( "Polymorphic union can't use '%s' as the discriminator " "column due to mapped column %r; please apply the " "'typecolname' " "argument; this is available on " "ConcreteBase as '_concrete_discriminator_name'" % (typecolname, c) ) colnames.add(c.key) m[c.key] = c types[c.key] = c.type colnamemaps[table] = m def col(name, table): try: return colnamemaps[table][name] except KeyError: if cast_nulls: return sql.cast(sql.null(), types[name]).label(name) else: return sql.type_coerce(sql.null(), types[name]).label(name) result = [] for type_, table in table_map.items(): if typecolname is not None: result.append( sql.select( *( [col(name, table) for name in colnames] + [ sql.literal_column( sql_util._quote_ddl_expr(type_) ).label(typecolname) ] ) ).select_from(table) ) else: result.append( sql.select( *[col(name, table) for name in colnames] ).select_from(table) ) return sql.union_all(*result).alias(aliasname) def identity_key( class_: Optional[Type[_T]] = None, ident: Union[Any, Tuple[Any, ...]] = None, *, instance: Optional[_T] = None, row: Optional[Union[Row[Any], RowMapping]] = None, identity_token: Optional[Any] = None, ) -> _IdentityKeyType[_T]: r"""Generate "identity key" tuples, as are used as keys in the :attr:`.Session.identity_map` dictionary. This function has several call styles: * ``identity_key(class, ident, identity_token=token)`` This form receives a mapped class and a primary key scalar or tuple as an argument. E.g.:: >>> identity_key(MyClass, (1, 2)) (<class '__main__.MyClass'>, (1, 2), None) :param class: mapped class (must be a positional argument) :param ident: primary key, may be a scalar or tuple argument. :param identity_token: optional identity token .. versionadded:: 1.2 added identity_token * ``identity_key(instance=instance)`` This form will produce the identity key for a given instance. The instance need not be persistent, only that its primary key attributes are populated (else the key will contain ``None`` for those missing values). E.g.:: >>> instance = MyClass(1, 2) >>> identity_key(instance=instance) (<class '__main__.MyClass'>, (1, 2), None) In this form, the given instance is ultimately run though :meth:`_orm.Mapper.identity_key_from_instance`, which will have the effect of performing a database check for the corresponding row if the object is expired. :param instance: object instance (must be given as a keyword arg) * ``identity_key(class, row=row, identity_token=token)`` This form is similar to the class/tuple form, except is passed a database result row as a :class:`.Row` or :class:`.RowMapping` object. E.g.:: >>> row = engine.execute(text("select * from table where a=1 and b=2")).first() >>> identity_key(MyClass, row=row) (<class '__main__.MyClass'>, (1, 2), None) :param class: mapped class (must be a positional argument) :param row: :class:`.Row` row returned by a :class:`_engine.CursorResult` (must be given as a keyword arg) :param identity_token: optional identity token .. versionadded:: 1.2 added identity_token """ # noqa: E501 if class_ is not None: mapper = class_mapper(class_) if row is None: if ident is None: raise sa_exc.ArgumentError("ident or row is required") return mapper.identity_key_from_primary_key( tuple(util.to_list(ident)), identity_token=identity_token ) else: return mapper.identity_key_from_row( row, identity_token=identity_token ) elif instance is not None: mapper = object_mapper(instance) return mapper.identity_key_from_instance(instance) else: raise sa_exc.ArgumentError("class or instance is required") class _TraceAdaptRole(enum.Enum): """Enumeration of all the use cases for ORMAdapter. ORMAdapter remains one of the most complicated aspects of the ORM, as it is used for in-place adaption of column expressions to be applied to a SELECT, replacing :class:`.Table` and other objects that are mapped to classes with aliases of those tables in the case of joined eager loading, or in the case of polymorphic loading as used with concrete mappings or other custom "with polymorphic" parameters, with whole user-defined subqueries. The enumerations provide an overview of all the use cases used by ORMAdapter, a layer of formality as to the introduction of new ORMAdapter use cases (of which none are anticipated), as well as a means to trace the origins of a particular ORMAdapter within runtime debugging. SQLAlchemy 2.0 has greatly scaled back ORM features which relied heavily on open-ended statement adaption, including the ``Query.with_polymorphic()`` method and the ``Query.select_from_entity()`` methods, favoring user-explicit aliasing schemes using the ``aliased()`` and ``with_polymorphic()`` standalone constructs; these still use adaption, however the adaption is applied in a narrower scope. """ # aliased() use that is used to adapt individual attributes at query # construction time ALIASED_INSP = enum.auto() # joinedload cases; typically adapt an ON clause of a relationship # join JOINEDLOAD_USER_DEFINED_ALIAS = enum.auto() JOINEDLOAD_PATH_WITH_POLYMORPHIC = enum.auto() JOINEDLOAD_MEMOIZED_ADAPTER = enum.auto() # polymorphic cases - these are complex ones that replace FROM # clauses, replacing tables with subqueries MAPPER_POLYMORPHIC_ADAPTER = enum.auto() WITH_POLYMORPHIC_ADAPTER = enum.auto() WITH_POLYMORPHIC_ADAPTER_RIGHT_JOIN = enum.auto() DEPRECATED_JOIN_ADAPT_RIGHT_SIDE = enum.auto() # the from_statement() case, used only to adapt individual attributes # from a given statement to local ORM attributes at result fetching # time. assigned to ORMCompileState._from_obj_alias ADAPT_FROM_STATEMENT = enum.auto() # the joinedload for queries that have LIMIT/OFFSET/DISTINCT case; # the query is placed inside of a subquery with the LIMIT/OFFSET/etc., # joinedloads are then placed on the outside. # assigned to ORMCompileState.compound_eager_adapter COMPOUND_EAGER_STATEMENT = enum.auto() # the legacy Query._set_select_from() case. # this is needed for Query's set operations (i.e. UNION, etc. ) # as well as "legacy from_self()", which while removed from 2.0 as # public API, is used for the Query.count() method. this one # still does full statement traversal # assigned to ORMCompileState._from_obj_alias LEGACY_SELECT_FROM_ALIAS = enum.auto() class ORMStatementAdapter(sql_util.ColumnAdapter): """ColumnAdapter which includes a role attribute.""" __slots__ = ("role",) def __init__( self, role: _TraceAdaptRole, selectable: Selectable, *, equivalents: Optional[_EquivalentColumnMap] = None, adapt_required: bool = False, allow_label_resolve: bool = True, anonymize_labels: bool = False, adapt_on_names: bool = False, adapt_from_selectables: Optional[AbstractSet[FromClause]] = None, ): self.role = role super().__init__( selectable, equivalents=equivalents, adapt_required=adapt_required, allow_label_resolve=allow_label_resolve, anonymize_labels=anonymize_labels, adapt_on_names=adapt_on_names, adapt_from_selectables=adapt_from_selectables, ) class ORMAdapter(sql_util.ColumnAdapter): """ColumnAdapter subclass which excludes adaptation of entities from non-matching mappers. """ __slots__ = ("role", "mapper", "is_aliased_class", "aliased_insp") is_aliased_class: bool aliased_insp: Optional[AliasedInsp[Any]] def __init__( self, role: _TraceAdaptRole, entity: _InternalEntityType[Any], *, equivalents: Optional[_EquivalentColumnMap] = None, adapt_required: bool = False, allow_label_resolve: bool = True, anonymize_labels: bool = False, selectable: Optional[Selectable] = None, limit_on_entity: bool = True, adapt_on_names: bool = False, adapt_from_selectables: Optional[AbstractSet[FromClause]] = None, ): self.role = role self.mapper = entity.mapper if selectable is None: selectable = entity.selectable if insp_is_aliased_class(entity): self.is_aliased_class = True self.aliased_insp = entity else: self.is_aliased_class = False self.aliased_insp = None super().__init__( selectable, equivalents, adapt_required=adapt_required, allow_label_resolve=allow_label_resolve, anonymize_labels=anonymize_labels, include_fn=self._include_fn if limit_on_entity else None, adapt_on_names=adapt_on_names, adapt_from_selectables=adapt_from_selectables, ) def _include_fn(self, elem): entity = elem._annotations.get("parentmapper", None) return not entity or entity.isa(self.mapper) or self.mapper.isa(entity) class AliasedClass( inspection.Inspectable["AliasedInsp[_O]"], ORMColumnsClauseRole[_O] ): r"""Represents an "aliased" form of a mapped class for usage with Query. The ORM equivalent of a :func:`~sqlalchemy.sql.expression.alias` construct, this object mimics the mapped class using a ``__getattr__`` scheme and maintains a reference to a real :class:`~sqlalchemy.sql.expression.Alias` object. A primary purpose of :class:`.AliasedClass` is to serve as an alternate within a SQL statement generated by the ORM, such that an existing mapped entity can be used in multiple contexts. A simple example:: # find all pairs of users with the same name user_alias = aliased(User) session.query(User, user_alias).join( (user_alias, User.id > user_alias.id) ).filter(User.name == user_alias.name) :class:`.AliasedClass` is also capable of mapping an existing mapped class to an entirely new selectable, provided this selectable is column- compatible with the existing mapped selectable, and it can also be configured in a mapping as the target of a :func:`_orm.relationship`. See the links below for examples. The :class:`.AliasedClass` object is constructed typically using the :func:`_orm.aliased` function. It also is produced with additional configuration when using the :func:`_orm.with_polymorphic` function. The resulting object is an instance of :class:`.AliasedClass`. This object implements an attribute scheme which produces the same attribute and method interface as the original mapped class, allowing :class:`.AliasedClass` to be compatible with any attribute technique which works on the original class, including hybrid attributes (see :ref:`hybrids_toplevel`). The :class:`.AliasedClass` can be inspected for its underlying :class:`_orm.Mapper`, aliased selectable, and other information using :func:`_sa.inspect`:: from sqlalchemy import inspect my_alias = aliased(MyClass) insp = inspect(my_alias) The resulting inspection object is an instance of :class:`.AliasedInsp`. .. seealso:: :func:`.aliased` :func:`.with_polymorphic` :ref:`relationship_aliased_class` :ref:`relationship_to_window_function` """ __name__: str def __init__( self, mapped_class_or_ac: _EntityType[_O], alias: Optional[FromClause] = None, name: Optional[str] = None, flat: bool = False, adapt_on_names: bool = False, with_polymorphic_mappers: Optional[Sequence[Mapper[Any]]] = None, with_polymorphic_discriminator: Optional[ColumnElement[Any]] = None, base_alias: Optional[AliasedInsp[Any]] = None, use_mapper_path: bool = False, represents_outer_join: bool = False, ): insp = cast( "_InternalEntityType[_O]", inspection.inspect(mapped_class_or_ac) ) mapper = insp.mapper nest_adapters = False if alias is None: if insp.is_aliased_class and insp.selectable._is_subquery: alias = insp.selectable.alias() else: alias = ( mapper._with_polymorphic_selectable._anonymous_fromclause( name=name, flat=flat, ) ) elif insp.is_aliased_class: nest_adapters = True assert alias is not None self._aliased_insp = AliasedInsp( self, insp, alias, name, ( with_polymorphic_mappers if with_polymorphic_mappers else mapper.with_polymorphic_mappers ), ( with_polymorphic_discriminator if with_polymorphic_discriminator is not None else mapper.polymorphic_on ), base_alias, use_mapper_path, adapt_on_names, represents_outer_join, nest_adapters, ) self.__name__ = f"aliased({mapper.class_.__name__})" @classmethod def _reconstitute_from_aliased_insp( cls, aliased_insp: AliasedInsp[_O] ) -> AliasedClass[_O]: obj = cls.__new__(cls) obj.__name__ = f"aliased({aliased_insp.mapper.class_.__name__})" obj._aliased_insp = aliased_insp if aliased_insp._is_with_polymorphic: for sub_aliased_insp in aliased_insp._with_polymorphic_entities: if sub_aliased_insp is not aliased_insp: ent = AliasedClass._reconstitute_from_aliased_insp( sub_aliased_insp ) setattr(obj, sub_aliased_insp.class_.__name__, ent) return obj def __getattr__(self, key: str) -> Any: try: _aliased_insp = self.__dict__["_aliased_insp"] except KeyError: raise AttributeError() else: target = _aliased_insp._target # maintain all getattr mechanics attr = getattr(target, key) # attribute is a method, that will be invoked against a # "self"; so just return a new method with the same function and # new self if hasattr(attr, "__call__") and hasattr(attr, "__self__"): return types.MethodType(attr.__func__, self) # attribute is a descriptor, that will be invoked against a # "self"; so invoke the descriptor against this self if hasattr(attr, "__get__"): attr = attr.__get__(None, self) # attributes within the QueryableAttribute system will want this # to be invoked so the object can be adapted if hasattr(attr, "adapt_to_entity"): attr = attr.adapt_to_entity(_aliased_insp) setattr(self, key, attr) return attr def _get_from_serialized( self, key: str, mapped_class: _O, aliased_insp: AliasedInsp[_O] ) -> Any: # this method is only used in terms of the # sqlalchemy.ext.serializer extension attr = getattr(mapped_class, key) if hasattr(attr, "__call__") and hasattr(attr, "__self__"): return types.MethodType(attr.__func__, self) # attribute is a descriptor, that will be invoked against a # "self"; so invoke the descriptor against this self if hasattr(attr, "__get__"): attr = attr.__get__(None, self) # attributes within the QueryableAttribute system will want this # to be invoked so the object can be adapted if hasattr(attr, "adapt_to_entity"): aliased_insp._weak_entity = weakref.ref(self) attr = attr.adapt_to_entity(aliased_insp) setattr(self, key, attr) return attr def __repr__(self) -> str: return "<AliasedClass at 0x%x; %s>" % ( id(self), self._aliased_insp._target.__name__, ) def __str__(self) -> str: return str(self._aliased_insp) @inspection._self_inspects class AliasedInsp( ORMEntityColumnsClauseRole[_O], ORMFromClauseRole, HasCacheKey, InspectionAttr, MemoizedSlots, inspection.Inspectable["AliasedInsp[_O]"], Generic[_O], ): """Provide an inspection interface for an :class:`.AliasedClass` object. The :class:`.AliasedInsp` object is returned given an :class:`.AliasedClass` using the :func:`_sa.inspect` function:: from sqlalchemy import inspect from sqlalchemy.orm import aliased my_alias = aliased(MyMappedClass) insp = inspect(my_alias) Attributes on :class:`.AliasedInsp` include: * ``entity`` - the :class:`.AliasedClass` represented. * ``mapper`` - the :class:`_orm.Mapper` mapping the underlying class. * ``selectable`` - the :class:`_expression.Alias` construct which ultimately represents an aliased :class:`_schema.Table` or :class:`_expression.Select` construct. * ``name`` - the name of the alias. Also is used as the attribute name when returned in a result tuple from :class:`_query.Query`. * ``with_polymorphic_mappers`` - collection of :class:`_orm.Mapper` objects indicating all those mappers expressed in the select construct for the :class:`.AliasedClass`. * ``polymorphic_on`` - an alternate column or SQL expression which will be used as the "discriminator" for a polymorphic load. .. seealso:: :ref:`inspection_toplevel` """ __slots__ = ( "__weakref__", "_weak_entity", "mapper", "selectable", "name", "_adapt_on_names", "with_polymorphic_mappers", "polymorphic_on", "_use_mapper_path", "_base_alias", "represents_outer_join", "persist_selectable", "local_table", "_is_with_polymorphic", "_with_polymorphic_entities", "_adapter", "_target", "__clause_element__", "_memoized_values", "_all_column_expressions", "_nest_adapters", ) _cache_key_traversal = [ ("name", visitors.ExtendedInternalTraversal.dp_string), ("_adapt_on_names", visitors.ExtendedInternalTraversal.dp_boolean), ("_use_mapper_path", visitors.ExtendedInternalTraversal.dp_boolean), ("_target", visitors.ExtendedInternalTraversal.dp_inspectable), ("selectable", visitors.ExtendedInternalTraversal.dp_clauseelement), ( "with_polymorphic_mappers", visitors.InternalTraversal.dp_has_cache_key_list, ), ("polymorphic_on", visitors.InternalTraversal.dp_clauseelement), ] mapper: Mapper[_O] selectable: FromClause _adapter: ORMAdapter with_polymorphic_mappers: Sequence[Mapper[Any]] _with_polymorphic_entities: Sequence[AliasedInsp[Any]] _weak_entity: weakref.ref[AliasedClass[_O]] """the AliasedClass that refers to this AliasedInsp""" _target: Union[Type[_O], AliasedClass[_O]] """the thing referenced by the AliasedClass/AliasedInsp. In the vast majority of cases, this is the mapped class. However it may also be another AliasedClass (alias of alias). """ def __init__( self, entity: AliasedClass[_O], inspected: _InternalEntityType[_O], selectable: FromClause, name: Optional[str], with_polymorphic_mappers: Optional[Sequence[Mapper[Any]]], polymorphic_on: Optional[ColumnElement[Any]], _base_alias: Optional[AliasedInsp[Any]], _use_mapper_path: bool, adapt_on_names: bool, represents_outer_join: bool, nest_adapters: bool, ): mapped_class_or_ac = inspected.entity mapper = inspected.mapper self._weak_entity = weakref.ref(entity) self.mapper = mapper self.selectable = self.persist_selectable = self.local_table = ( selectable ) self.name = name self.polymorphic_on = polymorphic_on self._base_alias = weakref.ref(_base_alias or self) self._use_mapper_path = _use_mapper_path self.represents_outer_join = represents_outer_join self._nest_adapters = nest_adapters if with_polymorphic_mappers: self._is_with_polymorphic = True self.with_polymorphic_mappers = with_polymorphic_mappers self._with_polymorphic_entities = [] for poly in self.with_polymorphic_mappers: if poly is not mapper: ent = AliasedClass( poly.class_, selectable, base_alias=self, adapt_on_names=adapt_on_names, use_mapper_path=_use_mapper_path, ) setattr(self.entity, poly.class_.__name__, ent) self._with_polymorphic_entities.append(ent._aliased_insp) else: self._is_with_polymorphic = False self.with_polymorphic_mappers = [mapper] self._adapter = ORMAdapter( _TraceAdaptRole.ALIASED_INSP, mapper, selectable=selectable, equivalents=mapper._equivalent_columns, adapt_on_names=adapt_on_names, anonymize_labels=True, # make sure the adapter doesn't try to grab other tables that # are not even the thing we are mapping, such as embedded # selectables in subqueries or CTEs. See issue #6060 adapt_from_selectables={ m.selectable for m in self.with_polymorphic_mappers if not adapt_on_names }, limit_on_entity=False, ) if nest_adapters: # supports "aliased class of aliased class" use case assert isinstance(inspected, AliasedInsp) self._adapter = inspected._adapter.wrap(self._adapter) self._adapt_on_names = adapt_on_names self._target = mapped_class_or_ac @classmethod def _alias_factory( cls, element: Union[_EntityType[_O], FromClause], alias: Optional[FromClause] = None, name: Optional[str] = None, flat: bool = False, adapt_on_names: bool = False, ) -> Union[AliasedClass[_O], FromClause]: if isinstance(element, FromClause): if adapt_on_names: raise sa_exc.ArgumentError( "adapt_on_names only applies to ORM elements" ) if name: return element.alias(name=name, flat=flat) else: return coercions.expect( roles.AnonymizedFromClauseRole, element, flat=flat ) else: return AliasedClass( element, alias=alias, flat=flat, name=name, adapt_on_names=adapt_on_names, ) @classmethod def _with_polymorphic_factory( cls, base: Union[Type[_O], Mapper[_O]], classes: Union[Literal["*"], Iterable[_EntityType[Any]]], selectable: Union[Literal[False, None], FromClause] = False, flat: bool = False, polymorphic_on: Optional[ColumnElement[Any]] = None, aliased: bool = False, innerjoin: bool = False, adapt_on_names: bool = False, name: Optional[str] = None, _use_mapper_path: bool = False, ) -> AliasedClass[_O]: primary_mapper = _class_to_mapper(base) if selectable not in (None, False) and flat: raise sa_exc.ArgumentError( "the 'flat' and 'selectable' arguments cannot be passed " "simultaneously to with_polymorphic()" ) mappers, selectable = primary_mapper._with_polymorphic_args( classes, selectable, innerjoin=innerjoin ) if aliased or flat: assert selectable is not None selectable = selectable._anonymous_fromclause(flat=flat) return AliasedClass( base, selectable, name=name, with_polymorphic_mappers=mappers, adapt_on_names=adapt_on_names, with_polymorphic_discriminator=polymorphic_on, use_mapper_path=_use_mapper_path, represents_outer_join=not innerjoin, ) @property def entity(self) -> AliasedClass[_O]: # to eliminate reference cycles, the AliasedClass is held weakly. # this produces some situations where the AliasedClass gets lost, # particularly when one is created internally and only the AliasedInsp # is passed around. # to work around this case, we just generate a new one when we need # it, as it is a simple class with very little initial state on it. ent = self._weak_entity() if ent is None: ent = AliasedClass._reconstitute_from_aliased_insp(self) self._weak_entity = weakref.ref(ent) return ent is_aliased_class = True "always returns True" def _memoized_method___clause_element__(self) -> FromClause: return self.selectable._annotate( { "parentmapper": self.mapper, "parententity": self, "entity_namespace": self, } )._set_propagate_attrs( {"compile_state_plugin": "orm", "plugin_subject": self} ) @property def entity_namespace(self) -> AliasedClass[_O]: return self.entity @property def class_(self) -> Type[_O]: """Return the mapped class ultimately represented by this :class:`.AliasedInsp`.""" return self.mapper.class_ @property def _path_registry(self) -> AbstractEntityRegistry: if self._use_mapper_path: return self.mapper._path_registry else: return PathRegistry.per_mapper(self) def __getstate__(self) -> Dict[str, Any]: return { "entity": self.entity, "mapper": self.mapper, "alias": self.selectable, "name": self.name, "adapt_on_names": self._adapt_on_names, "with_polymorphic_mappers": self.with_polymorphic_mappers, "with_polymorphic_discriminator": self.polymorphic_on, "base_alias": self._base_alias(), "use_mapper_path": self._use_mapper_path, "represents_outer_join": self.represents_outer_join, "nest_adapters": self._nest_adapters, } def __setstate__(self, state: Dict[str, Any]) -> None: self.__init__( # type: ignore state["entity"], state["mapper"], state["alias"], state["name"], state["with_polymorphic_mappers"], state["with_polymorphic_discriminator"], state["base_alias"], state["use_mapper_path"], state["adapt_on_names"], state["represents_outer_join"], state["nest_adapters"], ) def _merge_with(self, other: AliasedInsp[_O]) -> AliasedInsp[_O]: # assert self._is_with_polymorphic # assert other._is_with_polymorphic primary_mapper = other.mapper assert self.mapper is primary_mapper our_classes = util.to_set( mp.class_ for mp in self.with_polymorphic_mappers ) new_classes = {mp.class_ for mp in other.with_polymorphic_mappers} if our_classes == new_classes: return other else: classes = our_classes.union(new_classes) mappers, selectable = primary_mapper._with_polymorphic_args( classes, None, innerjoin=not other.represents_outer_join ) selectable = selectable._anonymous_fromclause(flat=True) return AliasedClass( primary_mapper, selectable, with_polymorphic_mappers=mappers, with_polymorphic_discriminator=other.polymorphic_on, use_mapper_path=other._use_mapper_path, represents_outer_join=other.represents_outer_join, )._aliased_insp def _adapt_element( self, expr: _ORMCOLEXPR, key: Optional[str] = None ) -> _ORMCOLEXPR: assert isinstance(expr, ColumnElement) d: Dict[str, Any] = { "parententity": self, "parentmapper": self.mapper, } if key: d["proxy_key"] = key # IMO mypy should see this one also as returning the same type # we put into it, but it's not return ( self._adapter.traverse(expr) ._annotate(d) ._set_propagate_attrs( {"compile_state_plugin": "orm", "plugin_subject": self} ) ) if TYPE_CHECKING: # establish compatibility with the _ORMAdapterProto protocol, # which in turn is compatible with _CoreAdapterProto. def _orm_adapt_element( self, obj: _CE, key: Optional[str] = None, ) -> _CE: ... else: _orm_adapt_element = _adapt_element def _entity_for_mapper(self, mapper): self_poly = self.with_polymorphic_mappers if mapper in self_poly: if mapper is self.mapper: return self else: return getattr( self.entity, mapper.class_.__name__ )._aliased_insp elif mapper.isa(self.mapper): return self else: assert False, "mapper %s doesn't correspond to %s" % (mapper, self) def _memoized_attr__get_clause(self): onclause, replacemap = self.mapper._get_clause return ( self._adapter.traverse(onclause), { self._adapter.traverse(col): param for col, param in replacemap.items() }, ) def _memoized_attr__memoized_values(self): return {} def _memoized_attr__all_column_expressions(self): if self._is_with_polymorphic: cols_plus_keys = self.mapper._columns_plus_keys( [ent.mapper for ent in self._with_polymorphic_entities] ) else: cols_plus_keys = self.mapper._columns_plus_keys() cols_plus_keys = [ (key, self._adapt_element(col)) for key, col in cols_plus_keys ] return ColumnCollection(cols_plus_keys) def _memo(self, key, callable_, *args, **kw): if key in self._memoized_values: return self._memoized_values[key] else: self._memoized_values[key] = value = callable_(*args, **kw) return value def __repr__(self): if self.with_polymorphic_mappers: with_poly = "(%s)" % ", ".join( mp.class_.__name__ for mp in self.with_polymorphic_mappers ) else: with_poly = "" return "<AliasedInsp at 0x%x; %s%s>" % ( id(self), self.class_.__name__, with_poly, ) def __str__(self): if self._is_with_polymorphic: return "with_polymorphic(%s, [%s])" % ( self._target.__name__, ", ".join( mp.class_.__name__ for mp in self.with_polymorphic_mappers if mp is not self.mapper ), ) else: return "aliased(%s)" % (self._target.__name__,) class _WrapUserEntity: """A wrapper used within the loader_criteria lambda caller so that we can bypass declared_attr descriptors on unmapped mixins, which normally emit a warning for such use. might also be useful for other per-lambda instrumentations should the need arise. """ __slots__ = ("subject",) def __init__(self, subject): self.subject = subject @util.preload_module("sqlalchemy.orm.decl_api") def __getattribute__(self, name): decl_api = util.preloaded.orm.decl_api subject = object.__getattribute__(self, "subject") if name in subject.__dict__ and isinstance( subject.__dict__[name], decl_api.declared_attr ): return subject.__dict__[name].fget(subject) else: return getattr(subject, name) class LoaderCriteriaOption(CriteriaOption): """Add additional WHERE criteria to the load for all occurrences of a particular entity. :class:`_orm.LoaderCriteriaOption` is invoked using the :func:`_orm.with_loader_criteria` function; see that function for details. .. versionadded:: 1.4 """ __slots__ = ( "root_entity", "entity", "deferred_where_criteria", "where_criteria", "_where_crit_orig", "include_aliases", "propagate_to_loaders", ) _traverse_internals = [ ("root_entity", visitors.ExtendedInternalTraversal.dp_plain_obj), ("entity", visitors.ExtendedInternalTraversal.dp_has_cache_key), ("where_criteria", visitors.InternalTraversal.dp_clauseelement), ("include_aliases", visitors.InternalTraversal.dp_boolean), ("propagate_to_loaders", visitors.InternalTraversal.dp_boolean), ] root_entity: Optional[Type[Any]] entity: Optional[_InternalEntityType[Any]] where_criteria: Union[ColumnElement[bool], lambdas.DeferredLambdaElement] deferred_where_criteria: bool include_aliases: bool propagate_to_loaders: bool _where_crit_orig: Any def __init__( self, entity_or_base: _EntityType[Any], where_criteria: Union[ _ColumnExpressionArgument[bool], Callable[[Any], _ColumnExpressionArgument[bool]], ], loader_only: bool = False, include_aliases: bool = False, propagate_to_loaders: bool = True, track_closure_variables: bool = True, ): entity = cast( "_InternalEntityType[Any]", inspection.inspect(entity_or_base, False), ) if entity is None: self.root_entity = cast("Type[Any]", entity_or_base) self.entity = None else: self.root_entity = None self.entity = entity self._where_crit_orig = where_criteria if callable(where_criteria): if self.root_entity is not None: wrap_entity = self.root_entity else: assert entity is not None wrap_entity = entity.entity self.deferred_where_criteria = True self.where_criteria = lambdas.DeferredLambdaElement( where_criteria, roles.WhereHavingRole, lambda_args=(_WrapUserEntity(wrap_entity),), opts=lambdas.LambdaOptions( track_closure_variables=track_closure_variables ), ) else: self.deferred_where_criteria = False self.where_criteria = coercions.expect( roles.WhereHavingRole, where_criteria ) self.include_aliases = include_aliases self.propagate_to_loaders = propagate_to_loaders @classmethod def _unreduce( cls, entity, where_criteria, include_aliases, propagate_to_loaders ): return LoaderCriteriaOption( entity, where_criteria, include_aliases=include_aliases, propagate_to_loaders=propagate_to_loaders, ) def __reduce__(self): return ( LoaderCriteriaOption._unreduce, ( self.entity.class_ if self.entity else self.root_entity, self._where_crit_orig, self.include_aliases, self.propagate_to_loaders, ), ) def _all_mappers(self) -> Iterator[Mapper[Any]]: if self.entity: yield from self.entity.mapper.self_and_descendants else: assert self.root_entity stack = list(self.root_entity.__subclasses__()) while stack: subclass = stack.pop(0) ent = cast( "_InternalEntityType[Any]", inspection.inspect(subclass, raiseerr=False), ) if ent: yield from ent.mapper.self_and_descendants else: stack.extend(subclass.__subclasses__()) def _should_include(self, compile_state: ORMCompileState) -> bool: if ( compile_state.select_statement._annotations.get( "for_loader_criteria", None ) is self ): return False return True def _resolve_where_criteria( self, ext_info: _InternalEntityType[Any] ) -> ColumnElement[bool]: if self.deferred_where_criteria: crit = cast( "ColumnElement[bool]", self.where_criteria._resolve_with_args(ext_info.entity), ) else: crit = self.where_criteria # type: ignore assert isinstance(crit, ColumnElement) return sql_util._deep_annotate( crit, {"for_loader_criteria": self}, detect_subquery_cols=True, ind_cols_on_fromclause=True, ) def process_compile_state_replaced_entities( self, compile_state: ORMCompileState, mapper_entities: Iterable[_MapperEntity], ) -> None: self.process_compile_state(compile_state) def process_compile_state(self, compile_state: ORMCompileState) -> None: """Apply a modification to a given :class:`.CompileState`.""" # if options to limit the criteria to immediate query only, # use compile_state.attributes instead self.get_global_criteria(compile_state.global_attributes) def get_global_criteria(self, attributes: Dict[Any, Any]) -> None: for mp in self._all_mappers(): load_criteria = attributes.setdefault( ("additional_entity_criteria", mp), [] ) load_criteria.append(self) inspection._inspects(AliasedClass)(lambda target: target._aliased_insp) @inspection._inspects(type) def _inspect_mc( class_: Type[_O], ) -> Optional[Mapper[_O]]: try: class_manager = opt_manager_of_class(class_) if class_manager is None or not class_manager.is_mapped: return None mapper = class_manager.mapper except exc.NO_STATE: return None else: return mapper GenericAlias = type(List[Any]) @inspection._inspects(GenericAlias) def _inspect_generic_alias( class_: Type[_O], ) -> Optional[Mapper[_O]]: origin = cast("Type[_O]", get_origin(class_)) return _inspect_mc(origin) @inspection._self_inspects class Bundle( ORMColumnsClauseRole[_T], SupportsCloneAnnotations, MemoizedHasCacheKey, inspection.Inspectable["Bundle[_T]"], InspectionAttr, ): """A grouping of SQL expressions that are returned by a :class:`.Query` under one namespace. The :class:`.Bundle` essentially allows nesting of the tuple-based results returned by a column-oriented :class:`_query.Query` object. It also is extensible via simple subclassing, where the primary capability to override is that of how the set of expressions should be returned, allowing post-processing as well as custom return types, without involving ORM identity-mapped classes. .. seealso:: :ref:`bundles` """ single_entity = False """If True, queries for a single Bundle will be returned as a single entity, rather than an element within a keyed tuple.""" is_clause_element = False is_mapper = False is_aliased_class = False is_bundle = True _propagate_attrs: _PropagateAttrsType = util.immutabledict() proxy_set = util.EMPTY_SET # type: ignore exprs: List[_ColumnsClauseElement] def __init__( self, name: str, *exprs: _ColumnExpressionArgument[Any], **kw: Any ): r"""Construct a new :class:`.Bundle`. e.g.:: bn = Bundle("mybundle", MyClass.x, MyClass.y) for row in session.query(bn).filter(bn.c.x == 5).filter(bn.c.y == 4): print(row.mybundle.x, row.mybundle.y) :param name: name of the bundle. :param \*exprs: columns or SQL expressions comprising the bundle. :param single_entity=False: if True, rows for this :class:`.Bundle` can be returned as a "single entity" outside of any enclosing tuple in the same manner as a mapped entity. """ # noqa: E501 self.name = self._label = name coerced_exprs = [ coercions.expect( roles.ColumnsClauseRole, expr, apply_propagate_attrs=self ) for expr in exprs ] self.exprs = coerced_exprs self.c = self.columns = ColumnCollection( (getattr(col, "key", col._label), col) for col in [e._annotations.get("bundle", e) for e in coerced_exprs] ).as_readonly() self.single_entity = kw.pop("single_entity", self.single_entity) def _gen_cache_key( self, anon_map: anon_map, bindparams: List[BindParameter[Any]] ) -> Tuple[Any, ...]: return (self.__class__, self.name, self.single_entity) + tuple( [expr._gen_cache_key(anon_map, bindparams) for expr in self.exprs] ) @property def mapper(self) -> Optional[Mapper[Any]]: mp: Optional[Mapper[Any]] = self.exprs[0]._annotations.get( "parentmapper", None ) return mp @property def entity(self) -> Optional[_InternalEntityType[Any]]: ie: Optional[_InternalEntityType[Any]] = self.exprs[ 0 ]._annotations.get("parententity", None) return ie @property def entity_namespace( self, ) -> ReadOnlyColumnCollection[str, KeyedColumnElement[Any]]: return self.c columns: ReadOnlyColumnCollection[str, KeyedColumnElement[Any]] """A namespace of SQL expressions referred to by this :class:`.Bundle`. e.g.:: bn = Bundle("mybundle", MyClass.x, MyClass.y) q = sess.query(bn).filter(bn.c.x == 5) Nesting of bundles is also supported:: b1 = Bundle( "b1", Bundle("b2", MyClass.a, MyClass.b), Bundle("b3", MyClass.x, MyClass.y), ) q = sess.query(b1).filter(b1.c.b2.c.a == 5).filter(b1.c.b3.c.y == 9) .. seealso:: :attr:`.Bundle.c` """ # noqa: E501 c: ReadOnlyColumnCollection[str, KeyedColumnElement[Any]] """An alias for :attr:`.Bundle.columns`.""" def _clone(self, **kw): cloned = self.__class__.__new__(self.__class__) cloned.__dict__.update(self.__dict__) return cloned def __clause_element__(self): # ensure existing entity_namespace remains annotations = {"bundle": self, "entity_namespace": self} annotations.update(self._annotations) plugin_subject = self.exprs[0]._propagate_attrs.get( "plugin_subject", self.entity ) return ( expression.ClauseList( _literal_as_text_role=roles.ColumnsClauseRole, group=False, *[e._annotations.get("bundle", e) for e in self.exprs], ) ._annotate(annotations) ._set_propagate_attrs( # the Bundle *must* use the orm plugin no matter what. the # subject can be None but it's much better if it's not. { "compile_state_plugin": "orm", "plugin_subject": plugin_subject, } ) ) @property def clauses(self): return self.__clause_element__().clauses def label(self, name): """Provide a copy of this :class:`.Bundle` passing a new label.""" cloned = self._clone() cloned.name = name return cloned def create_row_processor( self, query: Select[Any], procs: Sequence[Callable[[Row[Any]], Any]], labels: Sequence[str], ) -> Callable[[Row[Any]], Any]: """Produce the "row processing" function for this :class:`.Bundle`. May be overridden by subclasses to provide custom behaviors when results are fetched. The method is passed the statement object and a set of "row processor" functions at query execution time; these processor functions when given a result row will return the individual attribute value, which can then be adapted into any kind of return data structure. The example below illustrates replacing the usual :class:`.Row` return structure with a straight Python dictionary:: from sqlalchemy.orm import Bundle class DictBundle(Bundle): def create_row_processor(self, query, procs, labels): "Override create_row_processor to return values as dictionaries" def proc(row): return dict(zip(labels, (proc(row) for proc in procs))) return proc A result from the above :class:`_orm.Bundle` will return dictionary values:: bn = DictBundle("mybundle", MyClass.data1, MyClass.data2) for row in session.execute(select(bn)).where(bn.c.data1 == "d1"): print(row.mybundle["data1"], row.mybundle["data2"]) """ # noqa: E501 keyed_tuple = result_tuple(labels, [() for l in labels]) def proc(row: Row[Any]) -> Any: return keyed_tuple([proc(row) for proc in procs]) return proc def _orm_annotate(element: _SA, exclude: Optional[Any] = None) -> _SA: """Deep copy the given ClauseElement, annotating each element with the "_orm_adapt" flag. Elements within the exclude collection will be cloned but not annotated. """ return sql_util._deep_annotate(element, {"_orm_adapt": True}, exclude) def _orm_deannotate(element: _SA) -> _SA: """Remove annotations that link a column to a particular mapping. Note this doesn't affect "remote" and "foreign" annotations passed by the :func:`_orm.foreign` and :func:`_orm.remote` annotators. """ return sql_util._deep_deannotate( element, values=("_orm_adapt", "parententity") ) def _orm_full_deannotate(element: _SA) -> _SA: return sql_util._deep_deannotate(element) class _ORMJoin(expression.Join): """Extend Join to support ORM constructs as input.""" __visit_name__ = expression.Join.__visit_name__ inherit_cache = True def __init__( self, left: _FromClauseArgument, right: _FromClauseArgument, onclause: Optional[_OnClauseArgument] = None, isouter: bool = False, full: bool = False, _left_memo: Optional[Any] = None, _right_memo: Optional[Any] = None, _extra_criteria: Tuple[ColumnElement[bool], ...] = (), ): left_info = cast( "Union[FromClause, _InternalEntityType[Any]]", inspection.inspect(left), ) right_info = cast( "Union[FromClause, _InternalEntityType[Any]]", inspection.inspect(right), ) adapt_to = right_info.selectable # used by joined eager loader self._left_memo = _left_memo self._right_memo = _right_memo if isinstance(onclause, attributes.QueryableAttribute): if TYPE_CHECKING: assert isinstance( onclause.comparator, RelationshipProperty.Comparator ) on_selectable = onclause.comparator._source_selectable() prop = onclause.property _extra_criteria += onclause._extra_criteria elif isinstance(onclause, MapperProperty): # used internally by joined eager loader...possibly not ideal prop = onclause on_selectable = prop.parent.selectable else: prop = None on_selectable = None left_selectable = left_info.selectable if prop: adapt_from: Optional[FromClause] if sql_util.clause_is_present(on_selectable, left_selectable): adapt_from = on_selectable else: assert isinstance(left_selectable, FromClause) adapt_from = left_selectable ( pj, sj, source, dest, secondary, target_adapter, ) = prop._create_joins( source_selectable=adapt_from, dest_selectable=adapt_to, source_polymorphic=True, of_type_entity=right_info, alias_secondary=True, extra_criteria=_extra_criteria, ) if sj is not None: if isouter: # note this is an inner join from secondary->right right = sql.join(secondary, right, sj) onclause = pj else: left = sql.join(left, secondary, pj, isouter) onclause = sj else: onclause = pj self._target_adapter = target_adapter # we don't use the normal coercions logic for _ORMJoin # (probably should), so do some gymnastics to get the entity. # logic here is for #8721, which was a major bug in 1.4 # for almost two years, not reported/fixed until 1.4.43 (!) if is_selectable(left_info): parententity = left_selectable._annotations.get( "parententity", None ) elif insp_is_mapper(left_info) or insp_is_aliased_class(left_info): parententity = left_info else: parententity = None if parententity is not None: self._annotations = self._annotations.union( {"parententity": parententity} ) augment_onclause = bool(_extra_criteria) and not prop expression.Join.__init__(self, left, right, onclause, isouter, full) assert self.onclause is not None if augment_onclause: self.onclause &= sql.and_(*_extra_criteria) if ( not prop and getattr(right_info, "mapper", None) and right_info.mapper.single # type: ignore ): right_info = cast("_InternalEntityType[Any]", right_info) # if single inheritance target and we are using a manual # or implicit ON clause, augment it the same way we'd augment the # WHERE. single_crit = right_info.mapper._single_table_criterion if single_crit is not None: if insp_is_aliased_class(right_info): single_crit = right_info._adapter.traverse(single_crit) self.onclause = self.onclause & single_crit def _splice_into_center(self, other): """Splice a join into the center. Given join(a, b) and join(b, c), return join(a, b).join(c) """ leftmost = other while isinstance(leftmost, sql.Join): leftmost = leftmost.left assert self.right is leftmost left = _ORMJoin( self.left, other.left, self.onclause, isouter=self.isouter, _left_memo=self._left_memo, _right_memo=other._left_memo._path_registry, ) return _ORMJoin( left, other.right, other.onclause, isouter=other.isouter, _right_memo=other._right_memo, ) def join( self, right: _FromClauseArgument, onclause: Optional[_OnClauseArgument] = None, isouter: bool = False, full: bool = False, ) -> _ORMJoin: return _ORMJoin(self, right, onclause, full=full, isouter=isouter) def outerjoin( self, right: _FromClauseArgument, onclause: Optional[_OnClauseArgument] = None, full: bool = False, ) -> _ORMJoin: return _ORMJoin(self, right, onclause, isouter=True, full=full) def with_parent( instance: object, prop: attributes.QueryableAttribute[Any], from_entity: Optional[_EntityType[Any]] = None, ) -> ColumnElement[bool]: """Create filtering criterion that relates this query's primary entity to the given related instance, using established :func:`_orm.relationship()` configuration. E.g.:: stmt = select(Address).where(with_parent(some_user, User.addresses)) The SQL rendered is the same as that rendered when a lazy loader would fire off from the given parent on that attribute, meaning that the appropriate state is taken from the parent object in Python without the need to render joins to the parent table in the rendered statement. The given property may also make use of :meth:`_orm.PropComparator.of_type` to indicate the left side of the criteria:: a1 = aliased(Address) a2 = aliased(Address) stmt = select(a1, a2).where(with_parent(u1, User.addresses.of_type(a2))) The above use is equivalent to using the :func:`_orm.with_parent.from_entity` argument:: a1 = aliased(Address) a2 = aliased(Address) stmt = select(a1, a2).where( with_parent(u1, User.addresses, from_entity=a2) ) :param instance: An instance which has some :func:`_orm.relationship`. :param property: Class-bound attribute, which indicates what relationship from the instance should be used to reconcile the parent/child relationship. :param from_entity: Entity in which to consider as the left side. This defaults to the "zero" entity of the :class:`_query.Query` itself. .. versionadded:: 1.2 """ # noqa: E501 prop_t: RelationshipProperty[Any] if isinstance(prop, str): raise sa_exc.ArgumentError( "with_parent() accepts class-bound mapped attributes, not strings" ) elif isinstance(prop, attributes.QueryableAttribute): if prop._of_type: from_entity = prop._of_type mapper_property = prop.property if mapper_property is None or not prop_is_relationship( mapper_property ): raise sa_exc.ArgumentError( f"Expected relationship property for with_parent(), " f"got {mapper_property}" ) prop_t = mapper_property else: prop_t = prop return prop_t._with_parent(instance, from_entity=from_entity) def has_identity(object_: object) -> bool: """Return True if the given object has a database identity. This typically corresponds to the object being in either the persistent or detached state. .. seealso:: :func:`.was_deleted` """ state = attributes.instance_state(object_) return state.has_identity def was_deleted(object_: object) -> bool: """Return True if the given object was deleted within a session flush. This is regardless of whether or not the object is persistent or detached. .. seealso:: :attr:`.InstanceState.was_deleted` """ state = attributes.instance_state(object_) return state.was_deleted def _entity_corresponds_to( given: _InternalEntityType[Any], entity: _InternalEntityType[Any] ) -> bool: """determine if 'given' corresponds to 'entity', in terms of an entity passed to Query that would match the same entity being referred to elsewhere in the query. """ if insp_is_aliased_class(entity): if insp_is_aliased_class(given): if entity._base_alias() is given._base_alias(): return True return False elif insp_is_aliased_class(given): if given._use_mapper_path: return entity in given.with_polymorphic_mappers else: return entity is given assert insp_is_mapper(given) return entity.common_parent(given) def _entity_corresponds_to_use_path_impl( given: _InternalEntityType[Any], entity: _InternalEntityType[Any] ) -> bool: """determine if 'given' corresponds to 'entity', in terms of a path of loader options where a mapped attribute is taken to be a member of a parent entity. e.g.:: someoption(A).someoption(A.b) # -> fn(A, A) -> True someoption(A).someoption(C.d) # -> fn(A, C) -> False a1 = aliased(A) someoption(a1).someoption(A.b) # -> fn(a1, A) -> False someoption(a1).someoption(a1.b) # -> fn(a1, a1) -> True wp = with_polymorphic(A, [A1, A2]) someoption(wp).someoption(A1.foo) # -> fn(wp, A1) -> False someoption(wp).someoption(wp.A1.foo) # -> fn(wp, wp.A1) -> True """ if insp_is_aliased_class(given): return ( insp_is_aliased_class(entity) and not entity._use_mapper_path and (given is entity or entity in given._with_polymorphic_entities) ) elif not insp_is_aliased_class(entity): return given.isa(entity.mapper) else: return ( entity._use_mapper_path and given in entity.with_polymorphic_mappers ) def _entity_isa(given: _InternalEntityType[Any], mapper: Mapper[Any]) -> bool: """determine if 'given' "is a" mapper, in terms of the given would load rows of type 'mapper'. """ if given.is_aliased_class: return mapper in given.with_polymorphic_mappers or given.mapper.isa( mapper ) elif given.with_polymorphic_mappers: return mapper in given.with_polymorphic_mappers or given.isa(mapper) else: return given.isa(mapper) def _getitem(iterable_query: Query[Any], item: Any) -> Any: """calculate __getitem__ in terms of an iterable query object that also has a slice() method. """ def _no_negative_indexes(): raise IndexError( "negative indexes are not accepted by SQL " "index / slice operators" ) if isinstance(item, slice): start, stop, step = util.decode_slice(item) if ( isinstance(stop, int) and isinstance(start, int) and stop - start <= 0 ): return [] elif (isinstance(start, int) and start < 0) or ( isinstance(stop, int) and stop < 0 ): _no_negative_indexes() res = iterable_query.slice(start, stop) if step is not None: return list(res)[None : None : item.step] else: return list(res) else: if item == -1: _no_negative_indexes() else: return list(iterable_query[item : item + 1])[0] def _is_mapped_annotation( raw_annotation: _AnnotationScanType, cls: Type[Any], originating_cls: Type[Any], ) -> bool: try: annotated = de_stringify_annotation( cls, raw_annotation, originating_cls.__module__ ) except NameError: # in most cases, at least within our own tests, we can raise # here, which is more accurate as it prevents us from returning # false negatives. However, in the real world, try to avoid getting # involved with end-user annotations that have nothing to do with us. # see issue #8888 where we bypass using this function in the case # that we want to detect an unresolvable Mapped[] type. return False else: return is_origin_of_cls(annotated, _MappedAnnotationBase) class _CleanupError(Exception): pass def _cleanup_mapped_str_annotation( annotation: str, originating_module: str ) -> str: # fix up an annotation that comes in as the form: # 'Mapped[List[Address]]' so that it instead looks like: # 'Mapped[List["Address"]]' , which will allow us to get # "Address" as a string # additionally, resolve symbols for these names since this is where # we'd have to do it inner: Optional[Match[str]] mm = re.match(r"^([^ \|]+?)\[(.+)\]$", annotation) if not mm: return annotation # ticket #8759. Resolve the Mapped name to a real symbol. # originally this just checked the name. try: obj = eval_name_only(mm.group(1), originating_module) except NameError as ne: raise _CleanupError( f'For annotation "{annotation}", could not resolve ' f'container type "{mm.group(1)}". ' "Please ensure this type is imported at the module level " "outside of TYPE_CHECKING blocks" ) from ne if obj is typing.ClassVar: real_symbol = "ClassVar" else: try: if issubclass(obj, _MappedAnnotationBase): real_symbol = obj.__name__ else: return annotation except TypeError: # avoid isinstance(obj, type) check, just catch TypeError return annotation # note: if one of the codepaths above didn't define real_symbol and # then didn't return, real_symbol raises UnboundLocalError # which is actually a NameError, and the calling routines don't # notice this since they are catching NameError anyway. Just in case # this is being modified in the future, something to be aware of. stack = [] inner = mm while True: stack.append(real_symbol if mm is inner else inner.group(1)) g2 = inner.group(2) inner = re.match(r"^([^ \|]+?)\[(.+)\]$", g2) if inner is None: stack.append(g2) break # stacks we want to rewrite, that is, quote the last entry which # we think is a relationship class name: # # ['Mapped', 'List', 'Address'] # ['Mapped', 'A'] # # stacks we dont want to rewrite, which are generally MappedColumn # use cases: # # ['Mapped', "'Optional[Dict[str, str]]'"] # ['Mapped', 'dict[str, str] | None'] if ( # avoid already quoted symbols such as # ['Mapped', "'Optional[Dict[str, str]]'"] not re.match(r"""^["'].*["']$""", stack[-1]) # avoid further generics like Dict[] such as # ['Mapped', 'dict[str, str] | None'], # ['Mapped', 'list[int] | list[str]'], # ['Mapped', 'Union[list[int], list[str]]'], and not re.search(r"[\[\]]", stack[-1]) ): stripchars = "\"' " stack[-1] = ", ".join( f'"{elem.strip(stripchars)}"' for elem in stack[-1].split(",") ) annotation = "[".join(stack) + ("]" * (len(stack) - 1)) return annotation def _extract_mapped_subtype( raw_annotation: Optional[_AnnotationScanType], cls: type, originating_module: str, key: str, attr_cls: Type[Any], required: bool, is_dataclass_field: bool, expect_mapped: bool = True, raiseerr: bool = True, ) -> Optional[Tuple[Union[_AnnotationScanType, str], Optional[type]]]: """given an annotation, figure out if it's ``Mapped[something]`` and if so, return the ``something`` part. Includes error raise scenarios and other options. """ if raw_annotation is None: if required: raise orm_exc.MappedAnnotationError( f"Python typing annotation is required for attribute " f'"{cls.__name__}.{key}" when primary argument(s) for ' f'"{attr_cls.__name__}" construct are None or not present' ) return None try: # destringify the "outside" of the annotation. note we are not # adding include_generic so it will *not* dig into generic contents, # which will remain as ForwardRef or plain str under future annotations # mode. The full destringify happens later when mapped_column goes # to do a full lookup in the registry type_annotations_map. annotated = de_stringify_annotation( cls, raw_annotation, originating_module, str_cleanup_fn=_cleanup_mapped_str_annotation, ) except _CleanupError as ce: raise orm_exc.MappedAnnotationError( f"Could not interpret annotation {raw_annotation}. " "Check that it uses names that are correctly imported at the " "module level. See chained stack trace for more hints." ) from ce except NameError as ne: if raiseerr and "Mapped[" in raw_annotation: # type: ignore raise orm_exc.MappedAnnotationError( f"Could not interpret annotation {raw_annotation}. " "Check that it uses names that are correctly imported at the " "module level. See chained stack trace for more hints." ) from ne annotated = raw_annotation # type: ignore if is_dataclass_field: return annotated, None else: if not hasattr(annotated, "__origin__") or not is_origin_of_cls( annotated, _MappedAnnotationBase ): if expect_mapped: if not raiseerr: return None origin = getattr(annotated, "__origin__", None) if origin is typing.ClassVar: return None # check for other kind of ORM descriptor like AssociationProxy, # don't raise for that (issue #9957) elif isinstance(origin, type) and issubclass( origin, ORMDescriptor ): return None raise orm_exc.MappedAnnotationError( f'Type annotation for "{cls.__name__}.{key}" ' "can't be correctly interpreted for " "Annotated Declarative Table form. ORM annotations " "should normally make use of the ``Mapped[]`` generic " "type, or other ORM-compatible generic type, as a " "container for the actual type, which indicates the " "intent that the attribute is mapped. " "Class variables that are not intended to be mapped " "by the ORM should use ClassVar[]. " "To allow Annotated Declarative to disregard legacy " "annotations which don't use Mapped[] to pass, set " '"__allow_unmapped__ = True" on the class or a ' "superclass this class.", code="zlpr", ) else: return annotated, None if len(annotated.__args__) != 1: raise orm_exc.MappedAnnotationError( "Expected sub-type for Mapped[] annotation" ) return ( # fix dict/list/set args to be ForwardRef, see #11814 fixup_container_fwd_refs(annotated.__args__[0]), annotated.__origin__, ) def _mapper_property_as_plain_name(prop: Type[Any]) -> str: if hasattr(prop, "_mapper_property_name"): name = prop._mapper_property_name() else: name = None return util.clsname_as_plain_name(prop, name) sqlalchemy/orm/collections.py 0000755 00000146034 15125143220 0012401 0 ustar 00 # orm/collections.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: allow-untyped-defs, allow-untyped-calls """Support for collections of mapped entities. The collections package supplies the machinery used to inform the ORM of collection membership changes. An instrumentation via decoration approach is used, allowing arbitrary types (including built-ins) to be used as entity collections without requiring inheritance from a base class. Instrumentation decoration relays membership change events to the :class:`.CollectionAttributeImpl` that is currently managing the collection. The decorators observe function call arguments and return values, tracking entities entering or leaving the collection. Two decorator approaches are provided. One is a bundle of generic decorators that map function arguments and return values to events:: from sqlalchemy.orm.collections import collection class MyClass: # ... @collection.adds(1) def store(self, item): self.data.append(item) @collection.removes_return() def pop(self): return self.data.pop() The second approach is a bundle of targeted decorators that wrap appropriate append and remove notifiers around the mutation methods present in the standard Python ``list``, ``set`` and ``dict`` interfaces. These could be specified in terms of generic decorator recipes, but are instead hand-tooled for increased efficiency. The targeted decorators occasionally implement adapter-like behavior, such as mapping bulk-set methods (``extend``, ``update``, ``__setslice__``, etc.) into the series of atomic mutation events that the ORM requires. The targeted decorators are used internally for automatic instrumentation of entity collection classes. Every collection class goes through a transformation process roughly like so: 1. If the class is a built-in, substitute a trivial sub-class 2. Is this class already instrumented? 3. Add in generic decorators 4. Sniff out the collection interface through duck-typing 5. Add targeted decoration to any undecorated interface method This process modifies the class at runtime, decorating methods and adding some bookkeeping properties. This isn't possible (or desirable) for built-in classes like ``list``, so trivial sub-classes are substituted to hold decoration:: class InstrumentedList(list): pass Collection classes can be specified in ``relationship(collection_class=)`` as types or a function that returns an instance. Collection classes are inspected and instrumented during the mapper compilation phase. The collection_class callable will be executed once to produce a specimen instance, and the type of that specimen will be instrumented. Functions that return built-in types like ``lists`` will be adapted to produce instrumented instances. When extending a known type like ``list``, additional decorations are not generally not needed. Odds are, the extension method will delegate to a method that's already instrumented. For example:: class QueueIsh(list): def push(self, item): self.append(item) def shift(self): return self.pop(0) There's no need to decorate these methods. ``append`` and ``pop`` are already instrumented as part of the ``list`` interface. Decorating them would fire duplicate events, which should be avoided. The targeted decoration tries not to rely on other methods in the underlying collection class, but some are unavoidable. Many depend on 'read' methods being present to properly instrument a 'write', for example, ``__setitem__`` needs ``__getitem__``. "Bulk" methods like ``update`` and ``extend`` may also reimplemented in terms of atomic appends and removes, so the ``extend`` decoration will actually perform many ``append`` operations and not call the underlying method at all. Tight control over bulk operation and the firing of events is also possible by implementing the instrumentation internally in your methods. The basic instrumentation package works under the general assumption that collection mutation will not raise unusual exceptions. If you want to closely orchestrate append and remove events with exception management, internal instrumentation may be the answer. Within your method, ``collection_adapter(self)`` will retrieve an object that you can use for explicit control over triggering append and remove events. The owning object and :class:`.CollectionAttributeImpl` are also reachable through the adapter, allowing for some very sophisticated behavior. """ from __future__ import annotations import operator import threading import typing from typing import Any from typing import Callable from typing import cast from typing import Collection from typing import Dict from typing import Iterable from typing import List from typing import NoReturn from typing import Optional from typing import Set from typing import Tuple from typing import Type from typing import TYPE_CHECKING from typing import TypeVar from typing import Union import weakref from .base import NO_KEY from .. import exc as sa_exc from .. import util from ..sql.base import NO_ARG from ..util.compat import inspect_getfullargspec from ..util.typing import Protocol if typing.TYPE_CHECKING: from .attributes import AttributeEventToken from .attributes import CollectionAttributeImpl from .mapped_collection import attribute_keyed_dict from .mapped_collection import column_keyed_dict from .mapped_collection import keyfunc_mapping from .mapped_collection import KeyFuncDict # noqa: F401 from .state import InstanceState __all__ = [ "collection", "collection_adapter", "keyfunc_mapping", "column_keyed_dict", "attribute_keyed_dict", "KeyFuncDict", # old names in < 2.0 "mapped_collection", "column_mapped_collection", "attribute_mapped_collection", "MappedCollection", ] __instrumentation_mutex = threading.Lock() _CollectionFactoryType = Callable[[], "_AdaptedCollectionProtocol"] _T = TypeVar("_T", bound=Any) _KT = TypeVar("_KT", bound=Any) _VT = TypeVar("_VT", bound=Any) _COL = TypeVar("_COL", bound="Collection[Any]") _FN = TypeVar("_FN", bound="Callable[..., Any]") class _CollectionConverterProtocol(Protocol): def __call__(self, collection: _COL) -> _COL: ... class _AdaptedCollectionProtocol(Protocol): _sa_adapter: CollectionAdapter _sa_appender: Callable[..., Any] _sa_remover: Callable[..., Any] _sa_iterator: Callable[..., Iterable[Any]] _sa_converter: _CollectionConverterProtocol class collection: """Decorators for entity collection classes. The decorators fall into two groups: annotations and interception recipes. The annotating decorators (appender, remover, iterator, converter, internally_instrumented) indicate the method's purpose and take no arguments. They are not written with parens:: @collection.appender def append(self, append): ... The recipe decorators all require parens, even those that take no arguments:: @collection.adds("entity") def insert(self, position, entity): ... @collection.removes_return() def popitem(self): ... """ # Bundled as a class solely for ease of use: packaging, doc strings, # importability. @staticmethod def appender(fn): """Tag the method as the collection appender. The appender method is called with one positional argument: the value to append. The method will be automatically decorated with 'adds(1)' if not already decorated:: @collection.appender def add(self, append): ... # or, equivalently @collection.appender @collection.adds(1) def add(self, append): ... # for mapping type, an 'append' may kick out a previous value # that occupies that slot. consider d['a'] = 'foo'- any previous # value in d['a'] is discarded. @collection.appender @collection.replaces(1) def add(self, entity): key = some_key_func(entity) previous = None if key in self: previous = self[key] self[key] = entity return previous If the value to append is not allowed in the collection, you may raise an exception. Something to remember is that the appender will be called for each object mapped by a database query. If the database contains rows that violate your collection semantics, you will need to get creative to fix the problem, as access via the collection will not work. If the appender method is internally instrumented, you must also receive the keyword argument '_sa_initiator' and ensure its promulgation to collection events. """ fn._sa_instrument_role = "appender" return fn @staticmethod def remover(fn): """Tag the method as the collection remover. The remover method is called with one positional argument: the value to remove. The method will be automatically decorated with :meth:`removes_return` if not already decorated:: @collection.remover def zap(self, entity): ... # or, equivalently @collection.remover @collection.removes_return() def zap(self): ... If the value to remove is not present in the collection, you may raise an exception or return None to ignore the error. If the remove method is internally instrumented, you must also receive the keyword argument '_sa_initiator' and ensure its promulgation to collection events. """ fn._sa_instrument_role = "remover" return fn @staticmethod def iterator(fn): """Tag the method as the collection remover. The iterator method is called with no arguments. It is expected to return an iterator over all collection members:: @collection.iterator def __iter__(self): ... """ fn._sa_instrument_role = "iterator" return fn @staticmethod def internally_instrumented(fn): """Tag the method as instrumented. This tag will prevent any decoration from being applied to the method. Use this if you are orchestrating your own calls to :func:`.collection_adapter` in one of the basic SQLAlchemy interface methods, or to prevent an automatic ABC method decoration from wrapping your implementation:: # normally an 'extend' method on a list-like class would be # automatically intercepted and re-implemented in terms of # SQLAlchemy events and append(). your implementation will # never be called, unless: @collection.internally_instrumented def extend(self, items): ... """ fn._sa_instrumented = True return fn @staticmethod @util.deprecated( "1.3", "The :meth:`.collection.converter` handler is deprecated and will " "be removed in a future release. Please refer to the " ":class:`.AttributeEvents.bulk_replace` listener interface in " "conjunction with the :func:`.event.listen` function.", ) def converter(fn): """Tag the method as the collection converter. This optional method will be called when a collection is being replaced entirely, as in:: myobj.acollection = [newvalue1, newvalue2] The converter method will receive the object being assigned and should return an iterable of values suitable for use by the ``appender`` method. A converter must not assign values or mutate the collection, its sole job is to adapt the value the user provides into an iterable of values for the ORM's use. The default converter implementation will use duck-typing to do the conversion. A dict-like collection will be convert into an iterable of dictionary values, and other types will simply be iterated:: @collection.converter def convert(self, other): ... If the duck-typing of the object does not match the type of this collection, a TypeError is raised. Supply an implementation of this method if you want to expand the range of possible types that can be assigned in bulk or perform validation on the values about to be assigned. """ fn._sa_instrument_role = "converter" return fn @staticmethod def adds(arg): """Mark the method as adding an entity to the collection. Adds "add to collection" handling to the method. The decorator argument indicates which method argument holds the SQLAlchemy-relevant value. Arguments can be specified positionally (i.e. integer) or by name:: @collection.adds(1) def push(self, item): ... @collection.adds("entity") def do_stuff(self, thing, entity=None): ... """ def decorator(fn): fn._sa_instrument_before = ("fire_append_event", arg) return fn return decorator @staticmethod def replaces(arg): """Mark the method as replacing an entity in the collection. Adds "add to collection" and "remove from collection" handling to the method. The decorator argument indicates which method argument holds the SQLAlchemy-relevant value to be added, and return value, if any will be considered the value to remove. Arguments can be specified positionally (i.e. integer) or by name:: @collection.replaces(2) def __setitem__(self, index, item): ... """ def decorator(fn): fn._sa_instrument_before = ("fire_append_event", arg) fn._sa_instrument_after = "fire_remove_event" return fn return decorator @staticmethod def removes(arg): """Mark the method as removing an entity in the collection. Adds "remove from collection" handling to the method. The decorator argument indicates which method argument holds the SQLAlchemy-relevant value to be removed. Arguments can be specified positionally (i.e. integer) or by name:: @collection.removes(1) def zap(self, item): ... For methods where the value to remove is not known at call-time, use collection.removes_return. """ def decorator(fn): fn._sa_instrument_before = ("fire_remove_event", arg) return fn return decorator @staticmethod def removes_return(): """Mark the method as removing an entity in the collection. Adds "remove from collection" handling to the method. The return value of the method, if any, is considered the value to remove. The method arguments are not inspected:: @collection.removes_return() def pop(self): ... For methods where the value to remove is known at call-time, use collection.remove. """ def decorator(fn): fn._sa_instrument_after = "fire_remove_event" return fn return decorator if TYPE_CHECKING: def collection_adapter(collection: Collection[Any]) -> CollectionAdapter: """Fetch the :class:`.CollectionAdapter` for a collection.""" else: collection_adapter = operator.attrgetter("_sa_adapter") class CollectionAdapter: """Bridges between the ORM and arbitrary Python collections. Proxies base-level collection operations (append, remove, iterate) to the underlying Python collection, and emits add/remove events for entities entering or leaving the collection. The ORM uses :class:`.CollectionAdapter` exclusively for interaction with entity collections. """ __slots__ = ( "attr", "_key", "_data", "owner_state", "_converter", "invalidated", "empty", ) attr: CollectionAttributeImpl _key: str # this is actually a weakref; see note in constructor _data: Callable[..., _AdaptedCollectionProtocol] owner_state: InstanceState[Any] _converter: _CollectionConverterProtocol invalidated: bool empty: bool def __init__( self, attr: CollectionAttributeImpl, owner_state: InstanceState[Any], data: _AdaptedCollectionProtocol, ): self.attr = attr self._key = attr.key # this weakref stays referenced throughout the lifespan of # CollectionAdapter. so while the weakref can return None, this # is realistically only during garbage collection of this object, so # we type this as a callable that returns _AdaptedCollectionProtocol # in all cases. self._data = weakref.ref(data) # type: ignore self.owner_state = owner_state data._sa_adapter = self self._converter = data._sa_converter self.invalidated = False self.empty = False def _warn_invalidated(self) -> None: util.warn("This collection has been invalidated.") @property def data(self) -> _AdaptedCollectionProtocol: "The entity collection being adapted." return self._data() @property def _referenced_by_owner(self) -> bool: """return True if the owner state still refers to this collection. This will return False within a bulk replace operation, where this collection is the one being replaced. """ return self.owner_state.dict[self._key] is self._data() def bulk_appender(self): return self._data()._sa_appender def append_with_event( self, item: Any, initiator: Optional[AttributeEventToken] = None ) -> None: """Add an entity to the collection, firing mutation events.""" self._data()._sa_appender(item, _sa_initiator=initiator) def _set_empty(self, user_data): assert ( not self.empty ), "This collection adapter is already in the 'empty' state" self.empty = True self.owner_state._empty_collections[self._key] = user_data def _reset_empty(self) -> None: assert ( self.empty ), "This collection adapter is not in the 'empty' state" self.empty = False self.owner_state.dict[self._key] = ( self.owner_state._empty_collections.pop(self._key) ) def _refuse_empty(self) -> NoReturn: raise sa_exc.InvalidRequestError( "This is a special 'empty' collection which cannot accommodate " "internal mutation operations" ) def append_without_event(self, item: Any) -> None: """Add or restore an entity to the collection, firing no events.""" if self.empty: self._refuse_empty() self._data()._sa_appender(item, _sa_initiator=False) def append_multiple_without_event(self, items: Iterable[Any]) -> None: """Add or restore an entity to the collection, firing no events.""" if self.empty: self._refuse_empty() appender = self._data()._sa_appender for item in items: appender(item, _sa_initiator=False) def bulk_remover(self): return self._data()._sa_remover def remove_with_event( self, item: Any, initiator: Optional[AttributeEventToken] = None ) -> None: """Remove an entity from the collection, firing mutation events.""" self._data()._sa_remover(item, _sa_initiator=initiator) def remove_without_event(self, item: Any) -> None: """Remove an entity from the collection, firing no events.""" if self.empty: self._refuse_empty() self._data()._sa_remover(item, _sa_initiator=False) def clear_with_event( self, initiator: Optional[AttributeEventToken] = None ) -> None: """Empty the collection, firing a mutation event for each entity.""" if self.empty: self._refuse_empty() remover = self._data()._sa_remover for item in list(self): remover(item, _sa_initiator=initiator) def clear_without_event(self) -> None: """Empty the collection, firing no events.""" if self.empty: self._refuse_empty() remover = self._data()._sa_remover for item in list(self): remover(item, _sa_initiator=False) def __iter__(self): """Iterate over entities in the collection.""" return iter(self._data()._sa_iterator()) def __len__(self): """Count entities in the collection.""" return len(list(self._data()._sa_iterator())) def __bool__(self): return True def _fire_append_wo_mutation_event_bulk( self, items, initiator=None, key=NO_KEY ): if not items: return if initiator is not False: if self.invalidated: self._warn_invalidated() if self.empty: self._reset_empty() for item in items: self.attr.fire_append_wo_mutation_event( self.owner_state, self.owner_state.dict, item, initiator, key, ) def fire_append_wo_mutation_event(self, item, initiator=None, key=NO_KEY): """Notify that a entity is entering the collection but is already present. Initiator is a token owned by the InstrumentedAttribute that initiated the membership mutation, and should be left as None unless you are passing along an initiator value from a chained operation. .. versionadded:: 1.4.15 """ if initiator is not False: if self.invalidated: self._warn_invalidated() if self.empty: self._reset_empty() return self.attr.fire_append_wo_mutation_event( self.owner_state, self.owner_state.dict, item, initiator, key ) else: return item def fire_append_event(self, item, initiator=None, key=NO_KEY): """Notify that a entity has entered the collection. Initiator is a token owned by the InstrumentedAttribute that initiated the membership mutation, and should be left as None unless you are passing along an initiator value from a chained operation. """ if initiator is not False: if self.invalidated: self._warn_invalidated() if self.empty: self._reset_empty() return self.attr.fire_append_event( self.owner_state, self.owner_state.dict, item, initiator, key ) else: return item def _fire_remove_event_bulk(self, items, initiator=None, key=NO_KEY): if not items: return if initiator is not False: if self.invalidated: self._warn_invalidated() if self.empty: self._reset_empty() for item in items: self.attr.fire_remove_event( self.owner_state, self.owner_state.dict, item, initiator, key, ) def fire_remove_event(self, item, initiator=None, key=NO_KEY): """Notify that a entity has been removed from the collection. Initiator is the InstrumentedAttribute that initiated the membership mutation, and should be left as None unless you are passing along an initiator value from a chained operation. """ if initiator is not False: if self.invalidated: self._warn_invalidated() if self.empty: self._reset_empty() self.attr.fire_remove_event( self.owner_state, self.owner_state.dict, item, initiator, key ) def fire_pre_remove_event(self, initiator=None, key=NO_KEY): """Notify that an entity is about to be removed from the collection. Only called if the entity cannot be removed after calling fire_remove_event(). """ if self.invalidated: self._warn_invalidated() self.attr.fire_pre_remove_event( self.owner_state, self.owner_state.dict, initiator=initiator, key=key, ) def __getstate__(self): return { "key": self._key, "owner_state": self.owner_state, "owner_cls": self.owner_state.class_, "data": self.data, "invalidated": self.invalidated, "empty": self.empty, } def __setstate__(self, d): self._key = d["key"] self.owner_state = d["owner_state"] # see note in constructor regarding this type: ignore self._data = weakref.ref(d["data"]) # type: ignore self._converter = d["data"]._sa_converter d["data"]._sa_adapter = self self.invalidated = d["invalidated"] self.attr = getattr(d["owner_cls"], self._key).impl self.empty = d.get("empty", False) def bulk_replace(values, existing_adapter, new_adapter, initiator=None): """Load a new collection, firing events based on prior like membership. Appends instances in ``values`` onto the ``new_adapter``. Events will be fired for any instance not present in the ``existing_adapter``. Any instances in ``existing_adapter`` not present in ``values`` will have remove events fired upon them. :param values: An iterable of collection member instances :param existing_adapter: A :class:`.CollectionAdapter` of instances to be replaced :param new_adapter: An empty :class:`.CollectionAdapter` to load with ``values`` """ assert isinstance(values, list) idset = util.IdentitySet existing_idset = idset(existing_adapter or ()) constants = existing_idset.intersection(values or ()) additions = idset(values or ()).difference(constants) removals = existing_idset.difference(constants) appender = new_adapter.bulk_appender() for member in values or (): if member in additions: appender(member, _sa_initiator=initiator) elif member in constants: appender(member, _sa_initiator=False) if existing_adapter: existing_adapter._fire_append_wo_mutation_event_bulk( constants, initiator=initiator ) existing_adapter._fire_remove_event_bulk(removals, initiator=initiator) def prepare_instrumentation( factory: Union[Type[Collection[Any]], _CollectionFactoryType], ) -> _CollectionFactoryType: """Prepare a callable for future use as a collection class factory. Given a collection class factory (either a type or no-arg callable), return another factory that will produce compatible instances when called. This function is responsible for converting collection_class=list into the run-time behavior of collection_class=InstrumentedList. """ impl_factory: _CollectionFactoryType # Convert a builtin to 'Instrumented*' if factory in __canned_instrumentation: impl_factory = __canned_instrumentation[factory] else: impl_factory = cast(_CollectionFactoryType, factory) cls: Union[_CollectionFactoryType, Type[Collection[Any]]] # Create a specimen cls = type(impl_factory()) # Did factory callable return a builtin? if cls in __canned_instrumentation: # if so, just convert. # in previous major releases, this codepath wasn't working and was # not covered by tests. prior to that it supplied a "wrapper" # function that would return the class, though the rationale for this # case is not known impl_factory = __canned_instrumentation[cls] cls = type(impl_factory()) # Instrument the class if needed. if __instrumentation_mutex.acquire(): try: if getattr(cls, "_sa_instrumented", None) != id(cls): _instrument_class(cls) finally: __instrumentation_mutex.release() return impl_factory def _instrument_class(cls): """Modify methods in a class and install instrumentation.""" # In the normal call flow, a request for any of the 3 basic collection # types is transformed into one of our trivial subclasses # (e.g. InstrumentedList). Catch anything else that sneaks in here... if cls.__module__ == "__builtin__": raise sa_exc.ArgumentError( "Can not instrument a built-in type. Use a " "subclass, even a trivial one." ) roles, methods = _locate_roles_and_methods(cls) _setup_canned_roles(cls, roles, methods) _assert_required_roles(cls, roles, methods) _set_collection_attributes(cls, roles, methods) def _locate_roles_and_methods(cls): """search for _sa_instrument_role-decorated methods in method resolution order, assign to roles. """ roles: Dict[str, str] = {} methods: Dict[str, Tuple[Optional[str], Optional[int], Optional[str]]] = {} for supercls in cls.__mro__: for name, method in vars(supercls).items(): if not callable(method): continue # note role declarations if hasattr(method, "_sa_instrument_role"): role = method._sa_instrument_role assert role in ( "appender", "remover", "iterator", "converter", ) roles.setdefault(role, name) # transfer instrumentation requests from decorated function # to the combined queue before: Optional[Tuple[str, int]] = None after: Optional[str] = None if hasattr(method, "_sa_instrument_before"): op, argument = method._sa_instrument_before assert op in ("fire_append_event", "fire_remove_event") before = op, argument if hasattr(method, "_sa_instrument_after"): op = method._sa_instrument_after assert op in ("fire_append_event", "fire_remove_event") after = op if before: methods[name] = before + (after,) elif after: methods[name] = None, None, after return roles, methods def _setup_canned_roles(cls, roles, methods): """see if this class has "canned" roles based on a known collection type (dict, set, list). Apply those roles as needed to the "roles" dictionary, and also prepare "decorator" methods """ collection_type = util.duck_type_collection(cls) if collection_type in __interfaces: assert collection_type is not None canned_roles, decorators = __interfaces[collection_type] for role, name in canned_roles.items(): roles.setdefault(role, name) # apply ABC auto-decoration to methods that need it for method, decorator in decorators.items(): fn = getattr(cls, method, None) if ( fn and method not in methods and not hasattr(fn, "_sa_instrumented") ): setattr(cls, method, decorator(fn)) def _assert_required_roles(cls, roles, methods): """ensure all roles are present, and apply implicit instrumentation if needed """ if "appender" not in roles or not hasattr(cls, roles["appender"]): raise sa_exc.ArgumentError( "Type %s must elect an appender method to be " "a collection class" % cls.__name__ ) elif roles["appender"] not in methods and not hasattr( getattr(cls, roles["appender"]), "_sa_instrumented" ): methods[roles["appender"]] = ("fire_append_event", 1, None) if "remover" not in roles or not hasattr(cls, roles["remover"]): raise sa_exc.ArgumentError( "Type %s must elect a remover method to be " "a collection class" % cls.__name__ ) elif roles["remover"] not in methods and not hasattr( getattr(cls, roles["remover"]), "_sa_instrumented" ): methods[roles["remover"]] = ("fire_remove_event", 1, None) if "iterator" not in roles or not hasattr(cls, roles["iterator"]): raise sa_exc.ArgumentError( "Type %s must elect an iterator method to be " "a collection class" % cls.__name__ ) def _set_collection_attributes(cls, roles, methods): """apply ad-hoc instrumentation from decorators, class-level defaults and implicit role declarations """ for method_name, (before, argument, after) in methods.items(): setattr( cls, method_name, _instrument_membership_mutator( getattr(cls, method_name), before, argument, after ), ) # intern the role map for role, method_name in roles.items(): setattr(cls, "_sa_%s" % role, getattr(cls, method_name)) cls._sa_adapter = None if not hasattr(cls, "_sa_converter"): cls._sa_converter = None cls._sa_instrumented = id(cls) def _instrument_membership_mutator(method, before, argument, after): """Route method args and/or return value through the collection adapter.""" # This isn't smart enough to handle @adds(1) for 'def fn(self, (a, b))' if before: fn_args = list( util.flatten_iterator(inspect_getfullargspec(method)[0]) ) if isinstance(argument, int): pos_arg = argument named_arg = len(fn_args) > argument and fn_args[argument] or None else: if argument in fn_args: pos_arg = fn_args.index(argument) else: pos_arg = None named_arg = argument del fn_args def wrapper(*args, **kw): if before: if pos_arg is None: if named_arg not in kw: raise sa_exc.ArgumentError( "Missing argument %s" % argument ) value = kw[named_arg] else: if len(args) > pos_arg: value = args[pos_arg] elif named_arg in kw: value = kw[named_arg] else: raise sa_exc.ArgumentError( "Missing argument %s" % argument ) initiator = kw.pop("_sa_initiator", None) if initiator is False: executor = None else: executor = args[0]._sa_adapter if before and executor: getattr(executor, before)(value, initiator) if not after or not executor: return method(*args, **kw) else: res = method(*args, **kw) if res is not None: getattr(executor, after)(res, initiator) return res wrapper._sa_instrumented = True # type: ignore[attr-defined] if hasattr(method, "_sa_instrument_role"): wrapper._sa_instrument_role = method._sa_instrument_role # type: ignore[attr-defined] # noqa: E501 wrapper.__name__ = method.__name__ wrapper.__doc__ = method.__doc__ return wrapper def __set_wo_mutation(collection, item, _sa_initiator=None): """Run set wo mutation events. The collection is not mutated. """ if _sa_initiator is not False: executor = collection._sa_adapter if executor: executor.fire_append_wo_mutation_event( item, _sa_initiator, key=None ) def __set(collection, item, _sa_initiator, key): """Run set events. This event always occurs before the collection is actually mutated. """ if _sa_initiator is not False: executor = collection._sa_adapter if executor: item = executor.fire_append_event(item, _sa_initiator, key=key) return item def __del(collection, item, _sa_initiator, key): """Run del events. This event occurs before the collection is actually mutated, *except* in the case of a pop operation, in which case it occurs afterwards. For pop operations, the __before_pop hook is called before the operation occurs. """ if _sa_initiator is not False: executor = collection._sa_adapter if executor: executor.fire_remove_event(item, _sa_initiator, key=key) def __before_pop(collection, _sa_initiator=None): """An event which occurs on a before a pop() operation occurs.""" executor = collection._sa_adapter if executor: executor.fire_pre_remove_event(_sa_initiator) def _list_decorators() -> Dict[str, Callable[[_FN], _FN]]: """Tailored instrumentation wrappers for any list-like class.""" def _tidy(fn): fn._sa_instrumented = True fn.__doc__ = getattr(list, fn.__name__).__doc__ def append(fn): def append(self, item, _sa_initiator=None): item = __set(self, item, _sa_initiator, NO_KEY) fn(self, item) _tidy(append) return append def remove(fn): def remove(self, value, _sa_initiator=None): __del(self, value, _sa_initiator, NO_KEY) # testlib.pragma exempt:__eq__ fn(self, value) _tidy(remove) return remove def insert(fn): def insert(self, index, value): value = __set(self, value, None, index) fn(self, index, value) _tidy(insert) return insert def __setitem__(fn): def __setitem__(self, index, value): if not isinstance(index, slice): existing = self[index] if existing is not None: __del(self, existing, None, index) value = __set(self, value, None, index) fn(self, index, value) else: # slice assignment requires __delitem__, insert, __len__ step = index.step or 1 start = index.start or 0 if start < 0: start += len(self) if index.stop is not None: stop = index.stop else: stop = len(self) if stop < 0: stop += len(self) if step == 1: if value is self: return for i in range(start, stop, step): if len(self) > start: del self[start] for i, item in enumerate(value): self.insert(i + start, item) else: rng = list(range(start, stop, step)) if len(value) != len(rng): raise ValueError( "attempt to assign sequence of size %s to " "extended slice of size %s" % (len(value), len(rng)) ) for i, item in zip(rng, value): self.__setitem__(i, item) _tidy(__setitem__) return __setitem__ def __delitem__(fn): def __delitem__(self, index): if not isinstance(index, slice): item = self[index] __del(self, item, None, index) fn(self, index) else: # slice deletion requires __getslice__ and a slice-groking # __getitem__ for stepped deletion # note: not breaking this into atomic dels for item in self[index]: __del(self, item, None, index) fn(self, index) _tidy(__delitem__) return __delitem__ def extend(fn): def extend(self, iterable): for value in list(iterable): self.append(value) _tidy(extend) return extend def __iadd__(fn): def __iadd__(self, iterable): # list.__iadd__ takes any iterable and seems to let TypeError # raise as-is instead of returning NotImplemented for value in list(iterable): self.append(value) return self _tidy(__iadd__) return __iadd__ def pop(fn): def pop(self, index=-1): __before_pop(self) item = fn(self, index) __del(self, item, None, index) return item _tidy(pop) return pop def clear(fn): def clear(self, index=-1): for item in self: __del(self, item, None, index) fn(self) _tidy(clear) return clear # __imul__ : not wrapping this. all members of the collection are already # present, so no need to fire appends... wrapping it with an explicit # decorator is still possible, so events on *= can be had if they're # desired. hard to imagine a use case for __imul__, though. l = locals().copy() l.pop("_tidy") return l def _dict_decorators() -> Dict[str, Callable[[_FN], _FN]]: """Tailored instrumentation wrappers for any dict-like mapping class.""" def _tidy(fn): fn._sa_instrumented = True fn.__doc__ = getattr(dict, fn.__name__).__doc__ def __setitem__(fn): def __setitem__(self, key, value, _sa_initiator=None): if key in self: __del(self, self[key], _sa_initiator, key) value = __set(self, value, _sa_initiator, key) fn(self, key, value) _tidy(__setitem__) return __setitem__ def __delitem__(fn): def __delitem__(self, key, _sa_initiator=None): if key in self: __del(self, self[key], _sa_initiator, key) fn(self, key) _tidy(__delitem__) return __delitem__ def clear(fn): def clear(self): for key in self: __del(self, self[key], None, key) fn(self) _tidy(clear) return clear def pop(fn): def pop(self, key, default=NO_ARG): __before_pop(self) _to_del = key in self if default is NO_ARG: item = fn(self, key) else: item = fn(self, key, default) if _to_del: __del(self, item, None, key) return item _tidy(pop) return pop def popitem(fn): def popitem(self): __before_pop(self) item = fn(self) __del(self, item[1], None, 1) return item _tidy(popitem) return popitem def setdefault(fn): def setdefault(self, key, default=None): if key not in self: self.__setitem__(key, default) return default else: value = self.__getitem__(key) if value is default: __set_wo_mutation(self, value, None) return value _tidy(setdefault) return setdefault def update(fn): def update(self, __other=NO_ARG, **kw): if __other is not NO_ARG: if hasattr(__other, "keys"): for key in list(__other): if key not in self or self[key] is not __other[key]: self[key] = __other[key] else: __set_wo_mutation(self, __other[key], None) else: for key, value in __other: if key not in self or self[key] is not value: self[key] = value else: __set_wo_mutation(self, value, None) for key in kw: if key not in self or self[key] is not kw[key]: self[key] = kw[key] else: __set_wo_mutation(self, kw[key], None) _tidy(update) return update l = locals().copy() l.pop("_tidy") return l _set_binop_bases = (set, frozenset) def _set_binops_check_strict(self: Any, obj: Any) -> bool: """Allow only set, frozenset and self.__class__-derived objects in binops.""" return isinstance(obj, _set_binop_bases + (self.__class__,)) def _set_binops_check_loose(self: Any, obj: Any) -> bool: """Allow anything set-like to participate in set binops.""" return ( isinstance(obj, _set_binop_bases + (self.__class__,)) or util.duck_type_collection(obj) == set ) def _set_decorators() -> Dict[str, Callable[[_FN], _FN]]: """Tailored instrumentation wrappers for any set-like class.""" def _tidy(fn): fn._sa_instrumented = True fn.__doc__ = getattr(set, fn.__name__).__doc__ def add(fn): def add(self, value, _sa_initiator=None): if value not in self: value = __set(self, value, _sa_initiator, NO_KEY) else: __set_wo_mutation(self, value, _sa_initiator) # testlib.pragma exempt:__hash__ fn(self, value) _tidy(add) return add def discard(fn): def discard(self, value, _sa_initiator=None): # testlib.pragma exempt:__hash__ if value in self: __del(self, value, _sa_initiator, NO_KEY) # testlib.pragma exempt:__hash__ fn(self, value) _tidy(discard) return discard def remove(fn): def remove(self, value, _sa_initiator=None): # testlib.pragma exempt:__hash__ if value in self: __del(self, value, _sa_initiator, NO_KEY) # testlib.pragma exempt:__hash__ fn(self, value) _tidy(remove) return remove def pop(fn): def pop(self): __before_pop(self) item = fn(self) # for set in particular, we have no way to access the item # that will be popped before pop is called. __del(self, item, None, NO_KEY) return item _tidy(pop) return pop def clear(fn): def clear(self): for item in list(self): self.remove(item) _tidy(clear) return clear def update(fn): def update(self, value): for item in value: self.add(item) _tidy(update) return update def __ior__(fn): def __ior__(self, value): if not _set_binops_check_strict(self, value): return NotImplemented for item in value: self.add(item) return self _tidy(__ior__) return __ior__ def difference_update(fn): def difference_update(self, value): for item in value: self.discard(item) _tidy(difference_update) return difference_update def __isub__(fn): def __isub__(self, value): if not _set_binops_check_strict(self, value): return NotImplemented for item in value: self.discard(item) return self _tidy(__isub__) return __isub__ def intersection_update(fn): def intersection_update(self, other): want, have = self.intersection(other), set(self) remove, add = have - want, want - have for item in remove: self.remove(item) for item in add: self.add(item) _tidy(intersection_update) return intersection_update def __iand__(fn): def __iand__(self, other): if not _set_binops_check_strict(self, other): return NotImplemented want, have = self.intersection(other), set(self) remove, add = have - want, want - have for item in remove: self.remove(item) for item in add: self.add(item) return self _tidy(__iand__) return __iand__ def symmetric_difference_update(fn): def symmetric_difference_update(self, other): want, have = self.symmetric_difference(other), set(self) remove, add = have - want, want - have for item in remove: self.remove(item) for item in add: self.add(item) _tidy(symmetric_difference_update) return symmetric_difference_update def __ixor__(fn): def __ixor__(self, other): if not _set_binops_check_strict(self, other): return NotImplemented want, have = self.symmetric_difference(other), set(self) remove, add = have - want, want - have for item in remove: self.remove(item) for item in add: self.add(item) return self _tidy(__ixor__) return __ixor__ l = locals().copy() l.pop("_tidy") return l class InstrumentedList(List[_T]): """An instrumented version of the built-in list.""" class InstrumentedSet(Set[_T]): """An instrumented version of the built-in set.""" class InstrumentedDict(Dict[_KT, _VT]): """An instrumented version of the built-in dict.""" __canned_instrumentation: util.immutabledict[Any, _CollectionFactoryType] = ( util.immutabledict( { list: InstrumentedList, set: InstrumentedSet, dict: InstrumentedDict, } ) ) __interfaces: util.immutabledict[ Any, Tuple[ Dict[str, str], Dict[str, Callable[..., Any]], ], ] = util.immutabledict( { list: ( { "appender": "append", "remover": "remove", "iterator": "__iter__", }, _list_decorators(), ), set: ( {"appender": "add", "remover": "remove", "iterator": "__iter__"}, _set_decorators(), ), # decorators are required for dicts and object collections. dict: ({"iterator": "values"}, _dict_decorators()), } ) def __go(lcls): global keyfunc_mapping, mapped_collection global column_keyed_dict, column_mapped_collection global MappedCollection, KeyFuncDict global attribute_keyed_dict, attribute_mapped_collection from .mapped_collection import keyfunc_mapping from .mapped_collection import column_keyed_dict from .mapped_collection import attribute_keyed_dict from .mapped_collection import KeyFuncDict from .mapped_collection import mapped_collection from .mapped_collection import column_mapped_collection from .mapped_collection import attribute_mapped_collection from .mapped_collection import MappedCollection # ensure instrumentation is associated with # these built-in classes; if a user-defined class # subclasses these and uses @internally_instrumented, # the superclass is otherwise not instrumented. # see [ticket:2406]. _instrument_class(InstrumentedList) _instrument_class(InstrumentedSet) _instrument_class(KeyFuncDict) __go(locals()) sqlalchemy/orm/events.py 0000755 00000371445 15125143220 0011375 0 ustar 00 # orm/events.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """ORM event interfaces. """ from __future__ import annotations from typing import Any from typing import Callable from typing import Collection from typing import Dict from typing import Generic from typing import Iterable from typing import Optional from typing import Sequence from typing import Set from typing import Type from typing import TYPE_CHECKING from typing import TypeVar from typing import Union import weakref from . import instrumentation from . import interfaces from . import mapperlib from .attributes import QueryableAttribute from .base import _mapper_or_none from .base import NO_KEY from .instrumentation import ClassManager from .instrumentation import InstrumentationFactory from .query import BulkDelete from .query import BulkUpdate from .query import Query from .scoping import scoped_session from .session import Session from .session import sessionmaker from .. import event from .. import exc from .. import util from ..event import EventTarget from ..event.registry import _ET from ..util.compat import inspect_getfullargspec if TYPE_CHECKING: from weakref import ReferenceType from ._typing import _InstanceDict from ._typing import _InternalEntityType from ._typing import _O from ._typing import _T from .attributes import Event from .base import EventConstants from .session import ORMExecuteState from .session import SessionTransaction from .unitofwork import UOWTransaction from ..engine import Connection from ..event.base import _Dispatch from ..event.base import _HasEventsDispatch from ..event.registry import _EventKey from ..orm.collections import CollectionAdapter from ..orm.context import QueryContext from ..orm.decl_api import DeclarativeAttributeIntercept from ..orm.decl_api import DeclarativeMeta from ..orm.mapper import Mapper from ..orm.state import InstanceState _KT = TypeVar("_KT", bound=Any) _ET2 = TypeVar("_ET2", bound=EventTarget) class InstrumentationEvents(event.Events[InstrumentationFactory]): """Events related to class instrumentation events. The listeners here support being established against any new style class, that is any object that is a subclass of 'type'. Events will then be fired off for events against that class. If the "propagate=True" flag is passed to event.listen(), the event will fire off for subclasses of that class as well. The Python ``type`` builtin is also accepted as a target, which when used has the effect of events being emitted for all classes. Note the "propagate" flag here is defaulted to ``True``, unlike the other class level events where it defaults to ``False``. This means that new subclasses will also be the subject of these events, when a listener is established on a superclass. """ _target_class_doc = "SomeBaseClass" _dispatch_target = InstrumentationFactory @classmethod def _accept_with( cls, target: Union[ InstrumentationFactory, Type[InstrumentationFactory], ], identifier: str, ) -> Optional[ Union[ InstrumentationFactory, Type[InstrumentationFactory], ] ]: if isinstance(target, type): return _InstrumentationEventsHold(target) # type: ignore [return-value] # noqa: E501 else: return None @classmethod def _listen( cls, event_key: _EventKey[_T], propagate: bool = True, **kw: Any ) -> None: target, identifier, fn = ( event_key.dispatch_target, event_key.identifier, event_key._listen_fn, ) def listen(target_cls: type, *arg: Any) -> Optional[Any]: listen_cls = target() # if weakref were collected, however this is not something # that normally happens. it was occurring during test teardown # between mapper/registry/instrumentation_manager, however this # interaction was changed to not rely upon the event system. if listen_cls is None: return None if propagate and issubclass(target_cls, listen_cls): return fn(target_cls, *arg) elif not propagate and target_cls is listen_cls: return fn(target_cls, *arg) else: return None def remove(ref: ReferenceType[_T]) -> None: key = event.registry._EventKey( # type: ignore [type-var] None, identifier, listen, instrumentation._instrumentation_factory, ) getattr( instrumentation._instrumentation_factory.dispatch, identifier ).remove(key) target = weakref.ref(target.class_, remove) event_key.with_dispatch_target( instrumentation._instrumentation_factory ).with_wrapper(listen).base_listen(**kw) @classmethod def _clear(cls) -> None: super()._clear() instrumentation._instrumentation_factory.dispatch._clear() def class_instrument(self, cls: ClassManager[_O]) -> None: """Called after the given class is instrumented. To get at the :class:`.ClassManager`, use :func:`.manager_of_class`. """ def class_uninstrument(self, cls: ClassManager[_O]) -> None: """Called before the given class is uninstrumented. To get at the :class:`.ClassManager`, use :func:`.manager_of_class`. """ def attribute_instrument( self, cls: ClassManager[_O], key: _KT, inst: _O ) -> None: """Called when an attribute is instrumented.""" class _InstrumentationEventsHold: """temporary marker object used to transfer from _accept_with() to _listen() on the InstrumentationEvents class. """ def __init__(self, class_: type) -> None: self.class_ = class_ dispatch = event.dispatcher(InstrumentationEvents) class InstanceEvents(event.Events[ClassManager[Any]]): """Define events specific to object lifecycle. e.g.:: from sqlalchemy import event def my_load_listener(target, context): print("on load!") event.listen(SomeClass, "load", my_load_listener) Available targets include: * mapped classes * unmapped superclasses of mapped or to-be-mapped classes (using the ``propagate=True`` flag) * :class:`_orm.Mapper` objects * the :class:`_orm.Mapper` class itself indicates listening for all mappers. Instance events are closely related to mapper events, but are more specific to the instance and its instrumentation, rather than its system of persistence. When using :class:`.InstanceEvents`, several modifiers are available to the :func:`.event.listen` function. :param propagate=False: When True, the event listener should be applied to all inheriting classes as well as the class which is the target of this listener. :param raw=False: When True, the "target" argument passed to applicable event listener functions will be the instance's :class:`.InstanceState` management object, rather than the mapped instance itself. :param restore_load_context=False: Applies to the :meth:`.InstanceEvents.load` and :meth:`.InstanceEvents.refresh` events. Restores the loader context of the object when the event hook is complete, so that ongoing eager load operations continue to target the object appropriately. A warning is emitted if the object is moved to a new loader context from within one of these events if this flag is not set. .. versionadded:: 1.3.14 """ _target_class_doc = "SomeClass" _dispatch_target = ClassManager @classmethod def _new_classmanager_instance( cls, class_: Union[DeclarativeAttributeIntercept, DeclarativeMeta, type], classmanager: ClassManager[_O], ) -> None: _InstanceEventsHold.populate(class_, classmanager) @classmethod @util.preload_module("sqlalchemy.orm") def _accept_with( cls, target: Union[ ClassManager[Any], Type[ClassManager[Any]], ], identifier: str, ) -> Optional[Union[ClassManager[Any], Type[ClassManager[Any]]]]: orm = util.preloaded.orm if isinstance(target, ClassManager): return target elif isinstance(target, mapperlib.Mapper): return target.class_manager elif target is orm.mapper: # type: ignore [attr-defined] util.warn_deprecated( "The `sqlalchemy.orm.mapper()` symbol is deprecated and " "will be removed in a future release. For the mapper-wide " "event target, use the 'sqlalchemy.orm.Mapper' class.", "2.0", ) return ClassManager elif isinstance(target, type): if issubclass(target, mapperlib.Mapper): return ClassManager else: manager = instrumentation.opt_manager_of_class(target) if manager: return manager else: return _InstanceEventsHold(target) # type: ignore [return-value] # noqa: E501 return None @classmethod def _listen( cls, event_key: _EventKey[ClassManager[Any]], raw: bool = False, propagate: bool = False, restore_load_context: bool = False, **kw: Any, ) -> None: target, fn = (event_key.dispatch_target, event_key._listen_fn) if not raw or restore_load_context: def wrap( state: InstanceState[_O], *arg: Any, **kw: Any ) -> Optional[Any]: if not raw: target: Any = state.obj() else: target = state if restore_load_context: runid = state.runid try: return fn(target, *arg, **kw) finally: if restore_load_context: state.runid = runid event_key = event_key.with_wrapper(wrap) event_key.base_listen(propagate=propagate, **kw) if propagate: for mgr in target.subclass_managers(True): event_key.with_dispatch_target(mgr).base_listen(propagate=True) @classmethod def _clear(cls) -> None: super()._clear() _InstanceEventsHold._clear() def first_init(self, manager: ClassManager[_O], cls: Type[_O]) -> None: """Called when the first instance of a particular mapping is called. This event is called when the ``__init__`` method of a class is called the first time for that particular class. The event invokes before ``__init__`` actually proceeds as well as before the :meth:`.InstanceEvents.init` event is invoked. """ def init(self, target: _O, args: Any, kwargs: Any) -> None: """Receive an instance when its constructor is called. This method is only called during a userland construction of an object, in conjunction with the object's constructor, e.g. its ``__init__`` method. It is not called when an object is loaded from the database; see the :meth:`.InstanceEvents.load` event in order to intercept a database load. The event is called before the actual ``__init__`` constructor of the object is called. The ``kwargs`` dictionary may be modified in-place in order to affect what is passed to ``__init__``. :param target: the mapped instance. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :param args: positional arguments passed to the ``__init__`` method. This is passed as a tuple and is currently immutable. :param kwargs: keyword arguments passed to the ``__init__`` method. This structure *can* be altered in place. .. seealso:: :meth:`.InstanceEvents.init_failure` :meth:`.InstanceEvents.load` """ def init_failure(self, target: _O, args: Any, kwargs: Any) -> None: """Receive an instance when its constructor has been called, and raised an exception. This method is only called during a userland construction of an object, in conjunction with the object's constructor, e.g. its ``__init__`` method. It is not called when an object is loaded from the database. The event is invoked after an exception raised by the ``__init__`` method is caught. After the event is invoked, the original exception is re-raised outwards, so that the construction of the object still raises an exception. The actual exception and stack trace raised should be present in ``sys.exc_info()``. :param target: the mapped instance. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :param args: positional arguments that were passed to the ``__init__`` method. :param kwargs: keyword arguments that were passed to the ``__init__`` method. .. seealso:: :meth:`.InstanceEvents.init` :meth:`.InstanceEvents.load` """ def _sa_event_merge_wo_load( self, target: _O, context: QueryContext ) -> None: """receive an object instance after it was the subject of a merge() call, when load=False was passed. The target would be the already-loaded object in the Session which would have had its attributes overwritten by the incoming object. This overwrite operation does not use attribute events, instead just populating dict directly. Therefore the purpose of this event is so that extensions like sqlalchemy.ext.mutable know that object state has changed and incoming state needs to be set up for "parents" etc. This functionality is acceptable to be made public in a later release. .. versionadded:: 1.4.41 """ def load(self, target: _O, context: QueryContext) -> None: """Receive an object instance after it has been created via ``__new__``, and after initial attribute population has occurred. This typically occurs when the instance is created based on incoming result rows, and is only called once for that instance's lifetime. .. warning:: During a result-row load, this event is invoked when the first row received for this instance is processed. When using eager loading with collection-oriented attributes, the additional rows that are to be loaded / processed in order to load subsequent collection items have not occurred yet. This has the effect both that collections will not be fully loaded, as well as that if an operation occurs within this event handler that emits another database load operation for the object, the "loading context" for the object can change and interfere with the existing eager loaders still in progress. Examples of what can cause the "loading context" to change within the event handler include, but are not necessarily limited to: * accessing deferred attributes that weren't part of the row, will trigger an "undefer" operation and refresh the object * accessing attributes on a joined-inheritance subclass that weren't part of the row, will trigger a refresh operation. As of SQLAlchemy 1.3.14, a warning is emitted when this occurs. The :paramref:`.InstanceEvents.restore_load_context` option may be used on the event to prevent this warning; this will ensure that the existing loading context is maintained for the object after the event is called:: @event.listens_for(SomeClass, "load", restore_load_context=True) def on_load(instance, context): instance.some_unloaded_attribute .. versionchanged:: 1.3.14 Added :paramref:`.InstanceEvents.restore_load_context` and :paramref:`.SessionEvents.restore_load_context` flags which apply to "on load" events, which will ensure that the loading context for an object is restored when the event hook is complete; a warning is emitted if the load context of the object changes without this flag being set. The :meth:`.InstanceEvents.load` event is also available in a class-method decorator format called :func:`_orm.reconstructor`. :param target: the mapped instance. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :param context: the :class:`.QueryContext` corresponding to the current :class:`_query.Query` in progress. This argument may be ``None`` if the load does not correspond to a :class:`_query.Query`, such as during :meth:`.Session.merge`. .. seealso:: :ref:`mapped_class_load_events` :meth:`.InstanceEvents.init` :meth:`.InstanceEvents.refresh` :meth:`.SessionEvents.loaded_as_persistent` """ # noqa: E501 def refresh( self, target: _O, context: QueryContext, attrs: Optional[Iterable[str]] ) -> None: """Receive an object instance after one or more attributes have been refreshed from a query. Contrast this to the :meth:`.InstanceEvents.load` method, which is invoked when the object is first loaded from a query. .. note:: This event is invoked within the loader process before eager loaders may have been completed, and the object's state may not be complete. Additionally, invoking row-level refresh operations on the object will place the object into a new loader context, interfering with the existing load context. See the note on :meth:`.InstanceEvents.load` for background on making use of the :paramref:`.InstanceEvents.restore_load_context` parameter, in order to resolve this scenario. :param target: the mapped instance. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :param context: the :class:`.QueryContext` corresponding to the current :class:`_query.Query` in progress. :param attrs: sequence of attribute names which were populated, or None if all column-mapped, non-deferred attributes were populated. .. seealso:: :ref:`mapped_class_load_events` :meth:`.InstanceEvents.load` """ def refresh_flush( self, target: _O, flush_context: UOWTransaction, attrs: Optional[Iterable[str]], ) -> None: """Receive an object instance after one or more attributes that contain a column-level default or onupdate handler have been refreshed during persistence of the object's state. This event is the same as :meth:`.InstanceEvents.refresh` except it is invoked within the unit of work flush process, and includes only non-primary-key columns that have column level default or onupdate handlers, including Python callables as well as server side defaults and triggers which may be fetched via the RETURNING clause. .. note:: While the :meth:`.InstanceEvents.refresh_flush` event is triggered for an object that was INSERTed as well as for an object that was UPDATEd, the event is geared primarily towards the UPDATE process; it is mostly an internal artifact that INSERT actions can also trigger this event, and note that **primary key columns for an INSERTed row are explicitly omitted** from this event. In order to intercept the newly INSERTed state of an object, the :meth:`.SessionEvents.pending_to_persistent` and :meth:`.MapperEvents.after_insert` are better choices. :param target: the mapped instance. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :param flush_context: Internal :class:`.UOWTransaction` object which handles the details of the flush. :param attrs: sequence of attribute names which were populated. .. seealso:: :ref:`mapped_class_load_events` :ref:`orm_server_defaults` :ref:`metadata_defaults_toplevel` """ def expire(self, target: _O, attrs: Optional[Iterable[str]]) -> None: """Receive an object instance after its attributes or some subset have been expired. 'keys' is a list of attribute names. If None, the entire state was expired. :param target: the mapped instance. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :param attrs: sequence of attribute names which were expired, or None if all attributes were expired. """ def pickle(self, target: _O, state_dict: _InstanceDict) -> None: """Receive an object instance when its associated state is being pickled. :param target: the mapped instance. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :param state_dict: the dictionary returned by :class:`.InstanceState.__getstate__`, containing the state to be pickled. """ def unpickle(self, target: _O, state_dict: _InstanceDict) -> None: """Receive an object instance after its associated state has been unpickled. :param target: the mapped instance. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :param state_dict: the dictionary sent to :class:`.InstanceState.__setstate__`, containing the state dictionary which was pickled. """ class _EventsHold(event.RefCollection[_ET]): """Hold onto listeners against unmapped, uninstrumented classes. Establish _listen() for that class' mapper/instrumentation when those objects are created for that class. """ all_holds: weakref.WeakKeyDictionary[Any, Any] def __init__( self, class_: Union[DeclarativeAttributeIntercept, DeclarativeMeta, type], ) -> None: self.class_ = class_ @classmethod def _clear(cls) -> None: cls.all_holds.clear() class HoldEvents(Generic[_ET2]): _dispatch_target: Optional[Type[_ET2]] = None @classmethod def _listen( cls, event_key: _EventKey[_ET2], raw: bool = False, propagate: bool = False, retval: bool = False, **kw: Any, ) -> None: target = event_key.dispatch_target if target.class_ in target.all_holds: collection = target.all_holds[target.class_] else: collection = target.all_holds[target.class_] = {} event.registry._stored_in_collection(event_key, target) collection[event_key._key] = ( event_key, raw, propagate, retval, kw, ) if propagate: stack = list(target.class_.__subclasses__()) while stack: subclass = stack.pop(0) stack.extend(subclass.__subclasses__()) subject = target.resolve(subclass) if subject is not None: # we are already going through __subclasses__() # so leave generic propagate flag False event_key.with_dispatch_target(subject).listen( raw=raw, propagate=False, retval=retval, **kw ) def remove(self, event_key: _EventKey[_ET]) -> None: target = event_key.dispatch_target if isinstance(target, _EventsHold): collection = target.all_holds[target.class_] del collection[event_key._key] @classmethod def populate( cls, class_: Union[DeclarativeAttributeIntercept, DeclarativeMeta, type], subject: Union[ClassManager[_O], Mapper[_O]], ) -> None: for subclass in class_.__mro__: if subclass in cls.all_holds: collection = cls.all_holds[subclass] for ( event_key, raw, propagate, retval, kw, ) in collection.values(): if propagate or subclass is class_: # since we can't be sure in what order different # classes in a hierarchy are triggered with # populate(), we rely upon _EventsHold for all event # assignment, instead of using the generic propagate # flag. event_key.with_dispatch_target(subject).listen( raw=raw, propagate=False, retval=retval, **kw ) class _InstanceEventsHold(_EventsHold[_ET]): all_holds: weakref.WeakKeyDictionary[Any, Any] = ( weakref.WeakKeyDictionary() ) def resolve(self, class_: Type[_O]) -> Optional[ClassManager[_O]]: return instrumentation.opt_manager_of_class(class_) class HoldInstanceEvents(_EventsHold.HoldEvents[_ET], InstanceEvents): # type: ignore [misc] # noqa: E501 pass dispatch = event.dispatcher(HoldInstanceEvents) class MapperEvents(event.Events[mapperlib.Mapper[Any]]): """Define events specific to mappings. e.g.:: from sqlalchemy import event def my_before_insert_listener(mapper, connection, target): # execute a stored procedure upon INSERT, # apply the value to the row to be inserted target.calculated_value = connection.execute( text("select my_special_function(%d)" % target.special_number) ).scalar() # associate the listener function with SomeClass, # to execute during the "before_insert" hook event.listen(SomeClass, "before_insert", my_before_insert_listener) Available targets include: * mapped classes * unmapped superclasses of mapped or to-be-mapped classes (using the ``propagate=True`` flag) * :class:`_orm.Mapper` objects * the :class:`_orm.Mapper` class itself indicates listening for all mappers. Mapper events provide hooks into critical sections of the mapper, including those related to object instrumentation, object loading, and object persistence. In particular, the persistence methods :meth:`~.MapperEvents.before_insert`, and :meth:`~.MapperEvents.before_update` are popular places to augment the state being persisted - however, these methods operate with several significant restrictions. The user is encouraged to evaluate the :meth:`.SessionEvents.before_flush` and :meth:`.SessionEvents.after_flush` methods as more flexible and user-friendly hooks in which to apply additional database state during a flush. When using :class:`.MapperEvents`, several modifiers are available to the :func:`.event.listen` function. :param propagate=False: When True, the event listener should be applied to all inheriting mappers and/or the mappers of inheriting classes, as well as any mapper which is the target of this listener. :param raw=False: When True, the "target" argument passed to applicable event listener functions will be the instance's :class:`.InstanceState` management object, rather than the mapped instance itself. :param retval=False: when True, the user-defined event function must have a return value, the purpose of which is either to control subsequent event propagation, or to otherwise alter the operation in progress by the mapper. Possible return values are: * ``sqlalchemy.orm.interfaces.EXT_CONTINUE`` - continue event processing normally. * ``sqlalchemy.orm.interfaces.EXT_STOP`` - cancel all subsequent event handlers in the chain. * other values - the return value specified by specific listeners. """ _target_class_doc = "SomeClass" _dispatch_target = mapperlib.Mapper @classmethod def _new_mapper_instance( cls, class_: Union[DeclarativeAttributeIntercept, DeclarativeMeta, type], mapper: Mapper[_O], ) -> None: _MapperEventsHold.populate(class_, mapper) @classmethod @util.preload_module("sqlalchemy.orm") def _accept_with( cls, target: Union[mapperlib.Mapper[Any], Type[mapperlib.Mapper[Any]]], identifier: str, ) -> Optional[Union[mapperlib.Mapper[Any], Type[mapperlib.Mapper[Any]]]]: orm = util.preloaded.orm if target is orm.mapper: # type: ignore [attr-defined] util.warn_deprecated( "The `sqlalchemy.orm.mapper()` symbol is deprecated and " "will be removed in a future release. For the mapper-wide " "event target, use the 'sqlalchemy.orm.Mapper' class.", "2.0", ) return mapperlib.Mapper elif isinstance(target, type): if issubclass(target, mapperlib.Mapper): return target else: mapper = _mapper_or_none(target) if mapper is not None: return mapper else: return _MapperEventsHold(target) else: return target @classmethod def _listen( cls, event_key: _EventKey[_ET], raw: bool = False, retval: bool = False, propagate: bool = False, **kw: Any, ) -> None: target, identifier, fn = ( event_key.dispatch_target, event_key.identifier, event_key._listen_fn, ) if ( identifier in ("before_configured", "after_configured") and target is not mapperlib.Mapper ): util.warn( "'before_configured' and 'after_configured' ORM events " "only invoke with the Mapper class " "as the target." ) if not raw or not retval: if not raw: meth = getattr(cls, identifier) try: target_index = ( inspect_getfullargspec(meth)[0].index("target") - 1 ) except ValueError: target_index = None def wrap(*arg: Any, **kw: Any) -> Any: if not raw and target_index is not None: arg = list(arg) # type: ignore [assignment] arg[target_index] = arg[target_index].obj() # type: ignore [index] # noqa: E501 if not retval: fn(*arg, **kw) return interfaces.EXT_CONTINUE else: return fn(*arg, **kw) event_key = event_key.with_wrapper(wrap) if propagate: for mapper in target.self_and_descendants: event_key.with_dispatch_target(mapper).base_listen( propagate=True, **kw ) else: event_key.base_listen(**kw) @classmethod def _clear(cls) -> None: super()._clear() _MapperEventsHold._clear() def instrument_class(self, mapper: Mapper[_O], class_: Type[_O]) -> None: r"""Receive a class when the mapper is first constructed, before instrumentation is applied to the mapped class. This event is the earliest phase of mapper construction. Most attributes of the mapper are not yet initialized. To receive an event within initial mapper construction where basic state is available such as the :attr:`_orm.Mapper.attrs` collection, the :meth:`_orm.MapperEvents.after_mapper_constructed` event may be a better choice. This listener can either be applied to the :class:`_orm.Mapper` class overall, or to any un-mapped class which serves as a base for classes that will be mapped (using the ``propagate=True`` flag):: Base = declarative_base() @event.listens_for(Base, "instrument_class", propagate=True) def on_new_class(mapper, cls_): "..." :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param class\_: the mapped class. .. seealso:: :meth:`_orm.MapperEvents.after_mapper_constructed` """ def after_mapper_constructed( self, mapper: Mapper[_O], class_: Type[_O] ) -> None: """Receive a class and mapper when the :class:`_orm.Mapper` has been fully constructed. This event is called after the initial constructor for :class:`_orm.Mapper` completes. This occurs after the :meth:`_orm.MapperEvents.instrument_class` event and after the :class:`_orm.Mapper` has done an initial pass of its arguments to generate its collection of :class:`_orm.MapperProperty` objects, which are accessible via the :meth:`_orm.Mapper.get_property` method and the :attr:`_orm.Mapper.iterate_properties` attribute. This event differs from the :meth:`_orm.MapperEvents.before_mapper_configured` event in that it is invoked within the constructor for :class:`_orm.Mapper`, rather than within the :meth:`_orm.registry.configure` process. Currently, this event is the only one which is appropriate for handlers that wish to create additional mapped classes in response to the construction of this :class:`_orm.Mapper`, which will be part of the same configure step when :meth:`_orm.registry.configure` next runs. .. versionadded:: 2.0.2 .. seealso:: :ref:`examples_versioning` - an example which illustrates the use of the :meth:`_orm.MapperEvents.before_mapper_configured` event to create new mappers to record change-audit histories on objects. """ def before_mapper_configured( self, mapper: Mapper[_O], class_: Type[_O] ) -> None: """Called right before a specific mapper is to be configured. This event is intended to allow a specific mapper to be skipped during the configure step, by returning the :attr:`.orm.interfaces.EXT_SKIP` symbol which indicates to the :func:`.configure_mappers` call that this particular mapper (or hierarchy of mappers, if ``propagate=True`` is used) should be skipped in the current configuration run. When one or more mappers are skipped, the "new mappers" flag will remain set, meaning the :func:`.configure_mappers` function will continue to be called when mappers are used, to continue to try to configure all available mappers. In comparison to the other configure-level events, :meth:`.MapperEvents.before_configured`, :meth:`.MapperEvents.after_configured`, and :meth:`.MapperEvents.mapper_configured`, the :meth:`.MapperEvents.before_mapper_configured` event provides for a meaningful return value when it is registered with the ``retval=True`` parameter. .. versionadded:: 1.3 e.g.:: from sqlalchemy.orm import EXT_SKIP Base = declarative_base() DontConfigureBase = declarative_base() @event.listens_for( DontConfigureBase, "before_mapper_configured", retval=True, propagate=True, ) def dont_configure(mapper, cls): return EXT_SKIP .. seealso:: :meth:`.MapperEvents.before_configured` :meth:`.MapperEvents.after_configured` :meth:`.MapperEvents.mapper_configured` """ def mapper_configured(self, mapper: Mapper[_O], class_: Type[_O]) -> None: r"""Called when a specific mapper has completed its own configuration within the scope of the :func:`.configure_mappers` call. The :meth:`.MapperEvents.mapper_configured` event is invoked for each mapper that is encountered when the :func:`_orm.configure_mappers` function proceeds through the current list of not-yet-configured mappers. :func:`_orm.configure_mappers` is typically invoked automatically as mappings are first used, as well as each time new mappers have been made available and new mapper use is detected. When the event is called, the mapper should be in its final state, but **not including backrefs** that may be invoked from other mappers; they might still be pending within the configuration operation. Bidirectional relationships that are instead configured via the :paramref:`.orm.relationship.back_populates` argument *will* be fully available, since this style of relationship does not rely upon other possibly-not-configured mappers to know that they exist. For an event that is guaranteed to have **all** mappers ready to go including backrefs that are defined only on other mappings, use the :meth:`.MapperEvents.after_configured` event; this event invokes only after all known mappings have been fully configured. The :meth:`.MapperEvents.mapper_configured` event, unlike :meth:`.MapperEvents.before_configured` or :meth:`.MapperEvents.after_configured`, is called for each mapper/class individually, and the mapper is passed to the event itself. It also is called exactly once for a particular mapper. The event is therefore useful for configurational steps that benefit from being invoked just once on a specific mapper basis, which don't require that "backref" configurations are necessarily ready yet. :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param class\_: the mapped class. .. seealso:: :meth:`.MapperEvents.before_configured` :meth:`.MapperEvents.after_configured` :meth:`.MapperEvents.before_mapper_configured` """ # TODO: need coverage for this event def before_configured(self) -> None: """Called before a series of mappers have been configured. The :meth:`.MapperEvents.before_configured` event is invoked each time the :func:`_orm.configure_mappers` function is invoked, before the function has done any of its work. :func:`_orm.configure_mappers` is typically invoked automatically as mappings are first used, as well as each time new mappers have been made available and new mapper use is detected. This event can **only** be applied to the :class:`_orm.Mapper` class, and not to individual mappings or mapped classes. It is only invoked for all mappings as a whole:: from sqlalchemy.orm import Mapper @event.listens_for(Mapper, "before_configured") def go(): ... Contrast this event to :meth:`.MapperEvents.after_configured`, which is invoked after the series of mappers has been configured, as well as :meth:`.MapperEvents.before_mapper_configured` and :meth:`.MapperEvents.mapper_configured`, which are both invoked on a per-mapper basis. Theoretically this event is called once per application, but is actually called any time new mappers are to be affected by a :func:`_orm.configure_mappers` call. If new mappings are constructed after existing ones have already been used, this event will likely be called again. To ensure that a particular event is only called once and no further, the ``once=True`` argument (new in 0.9.4) can be applied:: from sqlalchemy.orm import mapper @event.listens_for(mapper, "before_configured", once=True) def go(): ... .. seealso:: :meth:`.MapperEvents.before_mapper_configured` :meth:`.MapperEvents.mapper_configured` :meth:`.MapperEvents.after_configured` """ def after_configured(self) -> None: """Called after a series of mappers have been configured. The :meth:`.MapperEvents.after_configured` event is invoked each time the :func:`_orm.configure_mappers` function is invoked, after the function has completed its work. :func:`_orm.configure_mappers` is typically invoked automatically as mappings are first used, as well as each time new mappers have been made available and new mapper use is detected. Contrast this event to the :meth:`.MapperEvents.mapper_configured` event, which is called on a per-mapper basis while the configuration operation proceeds; unlike that event, when this event is invoked, all cross-configurations (e.g. backrefs) will also have been made available for any mappers that were pending. Also contrast to :meth:`.MapperEvents.before_configured`, which is invoked before the series of mappers has been configured. This event can **only** be applied to the :class:`_orm.Mapper` class, and not to individual mappings or mapped classes. It is only invoked for all mappings as a whole:: from sqlalchemy.orm import Mapper @event.listens_for(Mapper, "after_configured") def go(): ... Theoretically this event is called once per application, but is actually called any time new mappers have been affected by a :func:`_orm.configure_mappers` call. If new mappings are constructed after existing ones have already been used, this event will likely be called again. To ensure that a particular event is only called once and no further, the ``once=True`` argument (new in 0.9.4) can be applied:: from sqlalchemy.orm import mapper @event.listens_for(mapper, "after_configured", once=True) def go(): ... .. seealso:: :meth:`.MapperEvents.before_mapper_configured` :meth:`.MapperEvents.mapper_configured` :meth:`.MapperEvents.before_configured` """ def before_insert( self, mapper: Mapper[_O], connection: Connection, target: _O ) -> None: """Receive an object instance before an INSERT statement is emitted corresponding to that instance. .. note:: this event **only** applies to the :ref:`session flush operation <session_flushing>` and does **not** apply to the ORM DML operations described at :ref:`orm_expression_update_delete`. To intercept ORM DML events, use :meth:`_orm.SessionEvents.do_orm_execute`. This event is used to modify local, non-object related attributes on the instance before an INSERT occurs, as well as to emit additional SQL statements on the given connection. The event is often called for a batch of objects of the same class before their INSERT statements are emitted at once in a later step. In the extremely rare case that this is not desirable, the :class:`_orm.Mapper` object can be configured with ``batch=False``, which will cause batches of instances to be broken up into individual (and more poorly performing) event->persist->event steps. .. warning:: Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param connection: the :class:`_engine.Connection` being used to emit INSERT statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. :param target: the mapped instance being persisted. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :return: No return value is supported by this event. .. seealso:: :ref:`session_persistence_events` """ def after_insert( self, mapper: Mapper[_O], connection: Connection, target: _O ) -> None: """Receive an object instance after an INSERT statement is emitted corresponding to that instance. .. note:: this event **only** applies to the :ref:`session flush operation <session_flushing>` and does **not** apply to the ORM DML operations described at :ref:`orm_expression_update_delete`. To intercept ORM DML events, use :meth:`_orm.SessionEvents.do_orm_execute`. This event is used to modify in-Python-only state on the instance after an INSERT occurs, as well as to emit additional SQL statements on the given connection. The event is often called for a batch of objects of the same class after their INSERT statements have been emitted at once in a previous step. In the extremely rare case that this is not desirable, the :class:`_orm.Mapper` object can be configured with ``batch=False``, which will cause batches of instances to be broken up into individual (and more poorly performing) event->persist->event steps. .. warning:: Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param connection: the :class:`_engine.Connection` being used to emit INSERT statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. :param target: the mapped instance being persisted. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :return: No return value is supported by this event. .. seealso:: :ref:`session_persistence_events` """ def before_update( self, mapper: Mapper[_O], connection: Connection, target: _O ) -> None: """Receive an object instance before an UPDATE statement is emitted corresponding to that instance. .. note:: this event **only** applies to the :ref:`session flush operation <session_flushing>` and does **not** apply to the ORM DML operations described at :ref:`orm_expression_update_delete`. To intercept ORM DML events, use :meth:`_orm.SessionEvents.do_orm_execute`. This event is used to modify local, non-object related attributes on the instance before an UPDATE occurs, as well as to emit additional SQL statements on the given connection. This method is called for all instances that are marked as "dirty", *even those which have no net changes to their column-based attributes*. An object is marked as dirty when any of its column-based attributes have a "set attribute" operation called or when any of its collections are modified. If, at update time, no column-based attributes have any net changes, no UPDATE statement will be issued. This means that an instance being sent to :meth:`~.MapperEvents.before_update` is *not* a guarantee that an UPDATE statement will be issued, although you can affect the outcome here by modifying attributes so that a net change in value does exist. To detect if the column-based attributes on the object have net changes, and will therefore generate an UPDATE statement, use ``object_session(instance).is_modified(instance, include_collections=False)``. The event is often called for a batch of objects of the same class before their UPDATE statements are emitted at once in a later step. In the extremely rare case that this is not desirable, the :class:`_orm.Mapper` can be configured with ``batch=False``, which will cause batches of instances to be broken up into individual (and more poorly performing) event->persist->event steps. .. warning:: Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param connection: the :class:`_engine.Connection` being used to emit UPDATE statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. :param target: the mapped instance being persisted. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :return: No return value is supported by this event. .. seealso:: :ref:`session_persistence_events` """ def after_update( self, mapper: Mapper[_O], connection: Connection, target: _O ) -> None: """Receive an object instance after an UPDATE statement is emitted corresponding to that instance. .. note:: this event **only** applies to the :ref:`session flush operation <session_flushing>` and does **not** apply to the ORM DML operations described at :ref:`orm_expression_update_delete`. To intercept ORM DML events, use :meth:`_orm.SessionEvents.do_orm_execute`. This event is used to modify in-Python-only state on the instance after an UPDATE occurs, as well as to emit additional SQL statements on the given connection. This method is called for all instances that are marked as "dirty", *even those which have no net changes to their column-based attributes*, and for which no UPDATE statement has proceeded. An object is marked as dirty when any of its column-based attributes have a "set attribute" operation called or when any of its collections are modified. If, at update time, no column-based attributes have any net changes, no UPDATE statement will be issued. This means that an instance being sent to :meth:`~.MapperEvents.after_update` is *not* a guarantee that an UPDATE statement has been issued. To detect if the column-based attributes on the object have net changes, and therefore resulted in an UPDATE statement, use ``object_session(instance).is_modified(instance, include_collections=False)``. The event is often called for a batch of objects of the same class after their UPDATE statements have been emitted at once in a previous step. In the extremely rare case that this is not desirable, the :class:`_orm.Mapper` can be configured with ``batch=False``, which will cause batches of instances to be broken up into individual (and more poorly performing) event->persist->event steps. .. warning:: Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param connection: the :class:`_engine.Connection` being used to emit UPDATE statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. :param target: the mapped instance being persisted. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :return: No return value is supported by this event. .. seealso:: :ref:`session_persistence_events` """ def before_delete( self, mapper: Mapper[_O], connection: Connection, target: _O ) -> None: """Receive an object instance before a DELETE statement is emitted corresponding to that instance. .. note:: this event **only** applies to the :ref:`session flush operation <session_flushing>` and does **not** apply to the ORM DML operations described at :ref:`orm_expression_update_delete`. To intercept ORM DML events, use :meth:`_orm.SessionEvents.do_orm_execute`. This event is used to emit additional SQL statements on the given connection as well as to perform application specific bookkeeping related to a deletion event. The event is often called for a batch of objects of the same class before their DELETE statements are emitted at once in a later step. .. warning:: Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param connection: the :class:`_engine.Connection` being used to emit DELETE statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. :param target: the mapped instance being deleted. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :return: No return value is supported by this event. .. seealso:: :ref:`session_persistence_events` """ def after_delete( self, mapper: Mapper[_O], connection: Connection, target: _O ) -> None: """Receive an object instance after a DELETE statement has been emitted corresponding to that instance. .. note:: this event **only** applies to the :ref:`session flush operation <session_flushing>` and does **not** apply to the ORM DML operations described at :ref:`orm_expression_update_delete`. To intercept ORM DML events, use :meth:`_orm.SessionEvents.do_orm_execute`. This event is used to emit additional SQL statements on the given connection as well as to perform application specific bookkeeping related to a deletion event. The event is often called for a batch of objects of the same class after their DELETE statements have been emitted at once in a previous step. .. warning:: Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param connection: the :class:`_engine.Connection` being used to emit DELETE statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. :param target: the mapped instance being deleted. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :return: No return value is supported by this event. .. seealso:: :ref:`session_persistence_events` """ class _MapperEventsHold(_EventsHold[_ET]): all_holds = weakref.WeakKeyDictionary() def resolve( self, class_: Union[Type[_T], _InternalEntityType[_T]] ) -> Optional[Mapper[_T]]: return _mapper_or_none(class_) class HoldMapperEvents(_EventsHold.HoldEvents[_ET], MapperEvents): # type: ignore [misc] # noqa: E501 pass dispatch = event.dispatcher(HoldMapperEvents) _sessionevents_lifecycle_event_names: Set[str] = set() class SessionEvents(event.Events[Session]): """Define events specific to :class:`.Session` lifecycle. e.g.:: from sqlalchemy import event from sqlalchemy.orm import sessionmaker def my_before_commit(session): print("before commit!") Session = sessionmaker() event.listen(Session, "before_commit", my_before_commit) The :func:`~.event.listen` function will accept :class:`.Session` objects as well as the return result of :class:`~.sessionmaker()` and :class:`~.scoped_session()`. Additionally, it accepts the :class:`.Session` class which will apply listeners to all :class:`.Session` instances globally. :param raw=False: When True, the "target" argument passed to applicable event listener functions that work on individual objects will be the instance's :class:`.InstanceState` management object, rather than the mapped instance itself. .. versionadded:: 1.3.14 :param restore_load_context=False: Applies to the :meth:`.SessionEvents.loaded_as_persistent` event. Restores the loader context of the object when the event hook is complete, so that ongoing eager load operations continue to target the object appropriately. A warning is emitted if the object is moved to a new loader context from within this event if this flag is not set. .. versionadded:: 1.3.14 """ _target_class_doc = "SomeSessionClassOrObject" _dispatch_target = Session def _lifecycle_event( # type: ignore [misc] fn: Callable[[SessionEvents, Session, Any], None] ) -> Callable[[SessionEvents, Session, Any], None]: _sessionevents_lifecycle_event_names.add(fn.__name__) return fn @classmethod def _accept_with( # type: ignore [return] cls, target: Any, identifier: str ) -> Union[Session, type]: if isinstance(target, scoped_session): target = target.session_factory if not isinstance(target, sessionmaker) and ( not isinstance(target, type) or not issubclass(target, Session) ): raise exc.ArgumentError( "Session event listen on a scoped_session " "requires that its creation callable " "is associated with the Session class." ) if isinstance(target, sessionmaker): return target.class_ elif isinstance(target, type): if issubclass(target, scoped_session): return Session elif issubclass(target, Session): return target elif isinstance(target, Session): return target elif hasattr(target, "_no_async_engine_events"): target._no_async_engine_events() else: # allows alternate SessionEvents-like-classes to be consulted return event.Events._accept_with(target, identifier) # type: ignore [return-value] # noqa: E501 @classmethod def _listen( cls, event_key: Any, *, raw: bool = False, restore_load_context: bool = False, **kw: Any, ) -> None: is_instance_event = ( event_key.identifier in _sessionevents_lifecycle_event_names ) if is_instance_event: if not raw or restore_load_context: fn = event_key._listen_fn def wrap( session: Session, state: InstanceState[_O], *arg: Any, **kw: Any, ) -> Optional[Any]: if not raw: target = state.obj() if target is None: # existing behavior is that if the object is # garbage collected, no event is emitted return None else: target = state # type: ignore [assignment] if restore_load_context: runid = state.runid try: return fn(session, target, *arg, **kw) finally: if restore_load_context: state.runid = runid event_key = event_key.with_wrapper(wrap) event_key.base_listen(**kw) def do_orm_execute(self, orm_execute_state: ORMExecuteState) -> None: """Intercept statement executions that occur on behalf of an ORM :class:`.Session` object. This event is invoked for all top-level SQL statements invoked from the :meth:`_orm.Session.execute` method, as well as related methods such as :meth:`_orm.Session.scalars` and :meth:`_orm.Session.scalar`. As of SQLAlchemy 1.4, all ORM queries that run through the :meth:`_orm.Session.execute` method as well as related methods :meth:`_orm.Session.scalars`, :meth:`_orm.Session.scalar` etc. will participate in this event. This event hook does **not** apply to the queries that are emitted internally within the ORM flush process, i.e. the process described at :ref:`session_flushing`. .. note:: The :meth:`_orm.SessionEvents.do_orm_execute` event hook is triggered **for ORM statement executions only**, meaning those invoked via the :meth:`_orm.Session.execute` and similar methods on the :class:`_orm.Session` object. It does **not** trigger for statements that are invoked by SQLAlchemy Core only, i.e. statements invoked directly using :meth:`_engine.Connection.execute` or otherwise originating from an :class:`_engine.Engine` object without any :class:`_orm.Session` involved. To intercept **all** SQL executions regardless of whether the Core or ORM APIs are in use, see the event hooks at :class:`.ConnectionEvents`, such as :meth:`.ConnectionEvents.before_execute` and :meth:`.ConnectionEvents.before_cursor_execute`. Also, this event hook does **not** apply to queries that are emitted internally within the ORM flush process, i.e. the process described at :ref:`session_flushing`; to intercept steps within the flush process, see the event hooks described at :ref:`session_persistence_events` as well as :ref:`session_persistence_mapper`. This event is a ``do_`` event, meaning it has the capability to replace the operation that the :meth:`_orm.Session.execute` method normally performs. The intended use for this includes sharding and result-caching schemes which may seek to invoke the same statement across multiple database connections, returning a result that is merged from each of them, or which don't invoke the statement at all, instead returning data from a cache. The hook intends to replace the use of the ``Query._execute_and_instances`` method that could be subclassed prior to SQLAlchemy 1.4. :param orm_execute_state: an instance of :class:`.ORMExecuteState` which contains all information about the current execution, as well as helper functions used to derive other commonly required information. See that object for details. .. seealso:: :ref:`session_execute_events` - top level documentation on how to use :meth:`_orm.SessionEvents.do_orm_execute` :class:`.ORMExecuteState` - the object passed to the :meth:`_orm.SessionEvents.do_orm_execute` event which contains all information about the statement to be invoked. It also provides an interface to extend the current statement, options, and parameters as well as an option that allows programmatic invocation of the statement at any point. :ref:`examples_session_orm_events` - includes examples of using :meth:`_orm.SessionEvents.do_orm_execute` :ref:`examples_caching` - an example of how to integrate Dogpile caching with the ORM :class:`_orm.Session` making use of the :meth:`_orm.SessionEvents.do_orm_execute` event hook. :ref:`examples_sharding` - the Horizontal Sharding example / extension relies upon the :meth:`_orm.SessionEvents.do_orm_execute` event hook to invoke a SQL statement on multiple backends and return a merged result. .. versionadded:: 1.4 """ def after_transaction_create( self, session: Session, transaction: SessionTransaction ) -> None: """Execute when a new :class:`.SessionTransaction` is created. This event differs from :meth:`~.SessionEvents.after_begin` in that it occurs for each :class:`.SessionTransaction` overall, as opposed to when transactions are begun on individual database connections. It is also invoked for nested transactions and subtransactions, and is always matched by a corresponding :meth:`~.SessionEvents.after_transaction_end` event (assuming normal operation of the :class:`.Session`). :param session: the target :class:`.Session`. :param transaction: the target :class:`.SessionTransaction`. To detect if this is the outermost :class:`.SessionTransaction`, as opposed to a "subtransaction" or a SAVEPOINT, test that the :attr:`.SessionTransaction.parent` attribute is ``None``:: @event.listens_for(session, "after_transaction_create") def after_transaction_create(session, transaction): if transaction.parent is None: ... # work with top-level transaction To detect if the :class:`.SessionTransaction` is a SAVEPOINT, use the :attr:`.SessionTransaction.nested` attribute:: @event.listens_for(session, "after_transaction_create") def after_transaction_create(session, transaction): if transaction.nested: ... # work with SAVEPOINT transaction .. seealso:: :class:`.SessionTransaction` :meth:`~.SessionEvents.after_transaction_end` """ def after_transaction_end( self, session: Session, transaction: SessionTransaction ) -> None: """Execute when the span of a :class:`.SessionTransaction` ends. This event differs from :meth:`~.SessionEvents.after_commit` in that it corresponds to all :class:`.SessionTransaction` objects in use, including those for nested transactions and subtransactions, and is always matched by a corresponding :meth:`~.SessionEvents.after_transaction_create` event. :param session: the target :class:`.Session`. :param transaction: the target :class:`.SessionTransaction`. To detect if this is the outermost :class:`.SessionTransaction`, as opposed to a "subtransaction" or a SAVEPOINT, test that the :attr:`.SessionTransaction.parent` attribute is ``None``:: @event.listens_for(session, "after_transaction_create") def after_transaction_end(session, transaction): if transaction.parent is None: ... # work with top-level transaction To detect if the :class:`.SessionTransaction` is a SAVEPOINT, use the :attr:`.SessionTransaction.nested` attribute:: @event.listens_for(session, "after_transaction_create") def after_transaction_end(session, transaction): if transaction.nested: ... # work with SAVEPOINT transaction .. seealso:: :class:`.SessionTransaction` :meth:`~.SessionEvents.after_transaction_create` """ def before_commit(self, session: Session) -> None: """Execute before commit is called. .. note:: The :meth:`~.SessionEvents.before_commit` hook is *not* per-flush, that is, the :class:`.Session` can emit SQL to the database many times within the scope of a transaction. For interception of these events, use the :meth:`~.SessionEvents.before_flush`, :meth:`~.SessionEvents.after_flush`, or :meth:`~.SessionEvents.after_flush_postexec` events. :param session: The target :class:`.Session`. .. seealso:: :meth:`~.SessionEvents.after_commit` :meth:`~.SessionEvents.after_begin` :meth:`~.SessionEvents.after_transaction_create` :meth:`~.SessionEvents.after_transaction_end` """ def after_commit(self, session: Session) -> None: """Execute after a commit has occurred. .. note:: The :meth:`~.SessionEvents.after_commit` hook is *not* per-flush, that is, the :class:`.Session` can emit SQL to the database many times within the scope of a transaction. For interception of these events, use the :meth:`~.SessionEvents.before_flush`, :meth:`~.SessionEvents.after_flush`, or :meth:`~.SessionEvents.after_flush_postexec` events. .. note:: The :class:`.Session` is not in an active transaction when the :meth:`~.SessionEvents.after_commit` event is invoked, and therefore can not emit SQL. To emit SQL corresponding to every transaction, use the :meth:`~.SessionEvents.before_commit` event. :param session: The target :class:`.Session`. .. seealso:: :meth:`~.SessionEvents.before_commit` :meth:`~.SessionEvents.after_begin` :meth:`~.SessionEvents.after_transaction_create` :meth:`~.SessionEvents.after_transaction_end` """ def after_rollback(self, session: Session) -> None: """Execute after a real DBAPI rollback has occurred. Note that this event only fires when the *actual* rollback against the database occurs - it does *not* fire each time the :meth:`.Session.rollback` method is called, if the underlying DBAPI transaction has already been rolled back. In many cases, the :class:`.Session` will not be in an "active" state during this event, as the current transaction is not valid. To acquire a :class:`.Session` which is active after the outermost rollback has proceeded, use the :meth:`.SessionEvents.after_soft_rollback` event, checking the :attr:`.Session.is_active` flag. :param session: The target :class:`.Session`. """ def after_soft_rollback( self, session: Session, previous_transaction: SessionTransaction ) -> None: """Execute after any rollback has occurred, including "soft" rollbacks that don't actually emit at the DBAPI level. This corresponds to both nested and outer rollbacks, i.e. the innermost rollback that calls the DBAPI's rollback() method, as well as the enclosing rollback calls that only pop themselves from the transaction stack. The given :class:`.Session` can be used to invoke SQL and :meth:`.Session.query` operations after an outermost rollback by first checking the :attr:`.Session.is_active` flag:: @event.listens_for(Session, "after_soft_rollback") def do_something(session, previous_transaction): if session.is_active: session.execute(text("select * from some_table")) :param session: The target :class:`.Session`. :param previous_transaction: The :class:`.SessionTransaction` transactional marker object which was just closed. The current :class:`.SessionTransaction` for the given :class:`.Session` is available via the :attr:`.Session.transaction` attribute. """ def before_flush( self, session: Session, flush_context: UOWTransaction, instances: Optional[Sequence[_O]], ) -> None: """Execute before flush process has started. :param session: The target :class:`.Session`. :param flush_context: Internal :class:`.UOWTransaction` object which handles the details of the flush. :param instances: Usually ``None``, this is the collection of objects which can be passed to the :meth:`.Session.flush` method (note this usage is deprecated). .. seealso:: :meth:`~.SessionEvents.after_flush` :meth:`~.SessionEvents.after_flush_postexec` :ref:`session_persistence_events` """ def after_flush( self, session: Session, flush_context: UOWTransaction ) -> None: """Execute after flush has completed, but before commit has been called. Note that the session's state is still in pre-flush, i.e. 'new', 'dirty', and 'deleted' lists still show pre-flush state as well as the history settings on instance attributes. .. warning:: This event runs after the :class:`.Session` has emitted SQL to modify the database, but **before** it has altered its internal state to reflect those changes, including that newly inserted objects are placed into the identity map. ORM operations emitted within this event such as loads of related items may produce new identity map entries that will immediately be replaced, sometimes causing confusing results. SQLAlchemy will emit a warning for this condition as of version 1.3.9. :param session: The target :class:`.Session`. :param flush_context: Internal :class:`.UOWTransaction` object which handles the details of the flush. .. seealso:: :meth:`~.SessionEvents.before_flush` :meth:`~.SessionEvents.after_flush_postexec` :ref:`session_persistence_events` """ def after_flush_postexec( self, session: Session, flush_context: UOWTransaction ) -> None: """Execute after flush has completed, and after the post-exec state occurs. This will be when the 'new', 'dirty', and 'deleted' lists are in their final state. An actual commit() may or may not have occurred, depending on whether or not the flush started its own transaction or participated in a larger transaction. :param session: The target :class:`.Session`. :param flush_context: Internal :class:`.UOWTransaction` object which handles the details of the flush. .. seealso:: :meth:`~.SessionEvents.before_flush` :meth:`~.SessionEvents.after_flush` :ref:`session_persistence_events` """ def after_begin( self, session: Session, transaction: SessionTransaction, connection: Connection, ) -> None: """Execute after a transaction is begun on a connection. .. note:: This event is called within the process of the :class:`_orm.Session` modifying its own internal state. To invoke SQL operations within this hook, use the :class:`_engine.Connection` provided to the event; do not run SQL operations using the :class:`_orm.Session` directly. :param session: The target :class:`.Session`. :param transaction: The :class:`.SessionTransaction`. :param connection: The :class:`_engine.Connection` object which will be used for SQL statements. .. seealso:: :meth:`~.SessionEvents.before_commit` :meth:`~.SessionEvents.after_commit` :meth:`~.SessionEvents.after_transaction_create` :meth:`~.SessionEvents.after_transaction_end` """ @_lifecycle_event def before_attach(self, session: Session, instance: _O) -> None: """Execute before an instance is attached to a session. This is called before an add, delete or merge causes the object to be part of the session. .. seealso:: :meth:`~.SessionEvents.after_attach` :ref:`session_lifecycle_events` """ @_lifecycle_event def after_attach(self, session: Session, instance: _O) -> None: """Execute after an instance is attached to a session. This is called after an add, delete or merge. .. note:: As of 0.8, this event fires off *after* the item has been fully associated with the session, which is different than previous releases. For event handlers that require the object not yet be part of session state (such as handlers which may autoflush while the target object is not yet complete) consider the new :meth:`.before_attach` event. .. seealso:: :meth:`~.SessionEvents.before_attach` :ref:`session_lifecycle_events` """ @event._legacy_signature( "0.9", ["session", "query", "query_context", "result"], lambda update_context: ( update_context.session, update_context.query, None, update_context.result, ), ) def after_bulk_update(self, update_context: _O) -> None: """Event for after the legacy :meth:`_orm.Query.update` method has been called. .. legacy:: The :meth:`_orm.SessionEvents.after_bulk_update` method is a legacy event hook as of SQLAlchemy 2.0. The event **does not participate** in :term:`2.0 style` invocations using :func:`_dml.update` documented at :ref:`orm_queryguide_update_delete_where`. For 2.0 style use, the :meth:`_orm.SessionEvents.do_orm_execute` hook will intercept these calls. :param update_context: an "update context" object which contains details about the update, including these attributes: * ``session`` - the :class:`.Session` involved * ``query`` -the :class:`_query.Query` object that this update operation was called upon. * ``values`` The "values" dictionary that was passed to :meth:`_query.Query.update`. * ``result`` the :class:`_engine.CursorResult` returned as a result of the bulk UPDATE operation. .. versionchanged:: 1.4 the update_context no longer has a ``QueryContext`` object associated with it. .. seealso:: :meth:`.QueryEvents.before_compile_update` :meth:`.SessionEvents.after_bulk_delete` """ @event._legacy_signature( "0.9", ["session", "query", "query_context", "result"], lambda delete_context: ( delete_context.session, delete_context.query, None, delete_context.result, ), ) def after_bulk_delete(self, delete_context: _O) -> None: """Event for after the legacy :meth:`_orm.Query.delete` method has been called. .. legacy:: The :meth:`_orm.SessionEvents.after_bulk_delete` method is a legacy event hook as of SQLAlchemy 2.0. The event **does not participate** in :term:`2.0 style` invocations using :func:`_dml.delete` documented at :ref:`orm_queryguide_update_delete_where`. For 2.0 style use, the :meth:`_orm.SessionEvents.do_orm_execute` hook will intercept these calls. :param delete_context: a "delete context" object which contains details about the update, including these attributes: * ``session`` - the :class:`.Session` involved * ``query`` -the :class:`_query.Query` object that this update operation was called upon. * ``result`` the :class:`_engine.CursorResult` returned as a result of the bulk DELETE operation. .. versionchanged:: 1.4 the update_context no longer has a ``QueryContext`` object associated with it. .. seealso:: :meth:`.QueryEvents.before_compile_delete` :meth:`.SessionEvents.after_bulk_update` """ @_lifecycle_event def transient_to_pending(self, session: Session, instance: _O) -> None: """Intercept the "transient to pending" transition for a specific object. This event is a specialization of the :meth:`.SessionEvents.after_attach` event which is only invoked for this specific transition. It is invoked typically during the :meth:`.Session.add` call. :param session: target :class:`.Session` :param instance: the ORM-mapped instance being operated upon. .. seealso:: :ref:`session_lifecycle_events` """ @_lifecycle_event def pending_to_transient(self, session: Session, instance: _O) -> None: """Intercept the "pending to transient" transition for a specific object. This less common transition occurs when an pending object that has not been flushed is evicted from the session; this can occur when the :meth:`.Session.rollback` method rolls back the transaction, or when the :meth:`.Session.expunge` method is used. :param session: target :class:`.Session` :param instance: the ORM-mapped instance being operated upon. .. seealso:: :ref:`session_lifecycle_events` """ @_lifecycle_event def persistent_to_transient(self, session: Session, instance: _O) -> None: """Intercept the "persistent to transient" transition for a specific object. This less common transition occurs when an pending object that has has been flushed is evicted from the session; this can occur when the :meth:`.Session.rollback` method rolls back the transaction. :param session: target :class:`.Session` :param instance: the ORM-mapped instance being operated upon. .. seealso:: :ref:`session_lifecycle_events` """ @_lifecycle_event def pending_to_persistent(self, session: Session, instance: _O) -> None: """Intercept the "pending to persistent"" transition for a specific object. This event is invoked within the flush process, and is similar to scanning the :attr:`.Session.new` collection within the :meth:`.SessionEvents.after_flush` event. However, in this case the object has already been moved to the persistent state when the event is called. :param session: target :class:`.Session` :param instance: the ORM-mapped instance being operated upon. .. seealso:: :ref:`session_lifecycle_events` """ @_lifecycle_event def detached_to_persistent(self, session: Session, instance: _O) -> None: """Intercept the "detached to persistent" transition for a specific object. This event is a specialization of the :meth:`.SessionEvents.after_attach` event which is only invoked for this specific transition. It is invoked typically during the :meth:`.Session.add` call, as well as during the :meth:`.Session.delete` call if the object was not previously associated with the :class:`.Session` (note that an object marked as "deleted" remains in the "persistent" state until the flush proceeds). .. note:: If the object becomes persistent as part of a call to :meth:`.Session.delete`, the object is **not** yet marked as deleted when this event is called. To detect deleted objects, check the ``deleted`` flag sent to the :meth:`.SessionEvents.persistent_to_detached` to event after the flush proceeds, or check the :attr:`.Session.deleted` collection within the :meth:`.SessionEvents.before_flush` event if deleted objects need to be intercepted before the flush. :param session: target :class:`.Session` :param instance: the ORM-mapped instance being operated upon. .. seealso:: :ref:`session_lifecycle_events` """ @_lifecycle_event def loaded_as_persistent(self, session: Session, instance: _O) -> None: """Intercept the "loaded as persistent" transition for a specific object. This event is invoked within the ORM loading process, and is invoked very similarly to the :meth:`.InstanceEvents.load` event. However, the event here is linkable to a :class:`.Session` class or instance, rather than to a mapper or class hierarchy, and integrates with the other session lifecycle events smoothly. The object is guaranteed to be present in the session's identity map when this event is called. .. note:: This event is invoked within the loader process before eager loaders may have been completed, and the object's state may not be complete. Additionally, invoking row-level refresh operations on the object will place the object into a new loader context, interfering with the existing load context. See the note on :meth:`.InstanceEvents.load` for background on making use of the :paramref:`.SessionEvents.restore_load_context` parameter, which works in the same manner as that of :paramref:`.InstanceEvents.restore_load_context`, in order to resolve this scenario. :param session: target :class:`.Session` :param instance: the ORM-mapped instance being operated upon. .. seealso:: :ref:`session_lifecycle_events` """ @_lifecycle_event def persistent_to_deleted(self, session: Session, instance: _O) -> None: """Intercept the "persistent to deleted" transition for a specific object. This event is invoked when a persistent object's identity is deleted from the database within a flush, however the object still remains associated with the :class:`.Session` until the transaction completes. If the transaction is rolled back, the object moves again to the persistent state, and the :meth:`.SessionEvents.deleted_to_persistent` event is called. If the transaction is committed, the object becomes detached, which will emit the :meth:`.SessionEvents.deleted_to_detached` event. Note that while the :meth:`.Session.delete` method is the primary public interface to mark an object as deleted, many objects get deleted due to cascade rules, which are not always determined until flush time. Therefore, there's no way to catch every object that will be deleted until the flush has proceeded. the :meth:`.SessionEvents.persistent_to_deleted` event is therefore invoked at the end of a flush. .. seealso:: :ref:`session_lifecycle_events` """ @_lifecycle_event def deleted_to_persistent(self, session: Session, instance: _O) -> None: """Intercept the "deleted to persistent" transition for a specific object. This transition occurs only when an object that's been deleted successfully in a flush is restored due to a call to :meth:`.Session.rollback`. The event is not called under any other circumstances. .. seealso:: :ref:`session_lifecycle_events` """ @_lifecycle_event def deleted_to_detached(self, session: Session, instance: _O) -> None: """Intercept the "deleted to detached" transition for a specific object. This event is invoked when a deleted object is evicted from the session. The typical case when this occurs is when the transaction for a :class:`.Session` in which the object was deleted is committed; the object moves from the deleted state to the detached state. It is also invoked for objects that were deleted in a flush when the :meth:`.Session.expunge_all` or :meth:`.Session.close` events are called, as well as if the object is individually expunged from its deleted state via :meth:`.Session.expunge`. .. seealso:: :ref:`session_lifecycle_events` """ @_lifecycle_event def persistent_to_detached(self, session: Session, instance: _O) -> None: """Intercept the "persistent to detached" transition for a specific object. This event is invoked when a persistent object is evicted from the session. There are many conditions that cause this to happen, including: * using a method such as :meth:`.Session.expunge` or :meth:`.Session.close` * Calling the :meth:`.Session.rollback` method, when the object was part of an INSERT statement for that session's transaction :param session: target :class:`.Session` :param instance: the ORM-mapped instance being operated upon. :param deleted: boolean. If True, indicates this object moved to the detached state because it was marked as deleted and flushed. .. seealso:: :ref:`session_lifecycle_events` """ class AttributeEvents(event.Events[QueryableAttribute[Any]]): r"""Define events for object attributes. These are typically defined on the class-bound descriptor for the target class. For example, to register a listener that will receive the :meth:`_orm.AttributeEvents.append` event:: from sqlalchemy import event @event.listens_for(MyClass.collection, "append", propagate=True) def my_append_listener(target, value, initiator): print("received append event for target: %s" % target) Listeners have the option to return a possibly modified version of the value, when the :paramref:`.AttributeEvents.retval` flag is passed to :func:`.event.listen` or :func:`.event.listens_for`, such as below, illustrated using the :meth:`_orm.AttributeEvents.set` event:: def validate_phone(target, value, oldvalue, initiator): "Strip non-numeric characters from a phone number" return re.sub(r"\D", "", value) # setup listener on UserContact.phone attribute, instructing # it to use the return value listen(UserContact.phone, "set", validate_phone, retval=True) A validation function like the above can also raise an exception such as :exc:`ValueError` to halt the operation. The :paramref:`.AttributeEvents.propagate` flag is also important when applying listeners to mapped classes that also have mapped subclasses, as when using mapper inheritance patterns:: @event.listens_for(MySuperClass.attr, "set", propagate=True) def receive_set(target, value, initiator): print("value set: %s" % target) The full list of modifiers available to the :func:`.event.listen` and :func:`.event.listens_for` functions are below. :param active_history=False: When True, indicates that the "set" event would like to receive the "old" value being replaced unconditionally, even if this requires firing off database loads. Note that ``active_history`` can also be set directly via :func:`.column_property` and :func:`_orm.relationship`. :param propagate=False: When True, the listener function will be established not just for the class attribute given, but for attributes of the same name on all current subclasses of that class, as well as all future subclasses of that class, using an additional listener that listens for instrumentation events. :param raw=False: When True, the "target" argument to the event will be the :class:`.InstanceState` management object, rather than the mapped instance itself. :param retval=False: when True, the user-defined event listening must return the "value" argument from the function. This gives the listening function the opportunity to change the value that is ultimately used for a "set" or "append" event. """ _target_class_doc = "SomeClass.some_attribute" _dispatch_target = QueryableAttribute @staticmethod def _set_dispatch( cls: Type[_HasEventsDispatch[Any]], dispatch_cls: Type[_Dispatch[Any]] ) -> _Dispatch[Any]: dispatch = event.Events._set_dispatch(cls, dispatch_cls) dispatch_cls._active_history = False return dispatch @classmethod def _accept_with( cls, target: Union[QueryableAttribute[Any], Type[QueryableAttribute[Any]]], identifier: str, ) -> Union[QueryableAttribute[Any], Type[QueryableAttribute[Any]]]: # TODO: coverage if isinstance(target, interfaces.MapperProperty): return getattr(target.parent.class_, target.key) else: return target @classmethod def _listen( # type: ignore [override] cls, event_key: _EventKey[QueryableAttribute[Any]], active_history: bool = False, raw: bool = False, retval: bool = False, propagate: bool = False, include_key: bool = False, ) -> None: target, fn = event_key.dispatch_target, event_key._listen_fn if active_history: target.dispatch._active_history = True if not raw or not retval or not include_key: def wrap(target: InstanceState[_O], *arg: Any, **kw: Any) -> Any: if not raw: target = target.obj() # type: ignore [assignment] if not retval: if arg: value = arg[0] else: value = None if include_key: fn(target, *arg, **kw) else: fn(target, *arg) return value else: if include_key: return fn(target, *arg, **kw) else: return fn(target, *arg) event_key = event_key.with_wrapper(wrap) event_key.base_listen(propagate=propagate) if propagate: manager = instrumentation.manager_of_class(target.class_) for mgr in manager.subclass_managers(True): # type: ignore [no-untyped-call] # noqa: E501 event_key.with_dispatch_target(mgr[target.key]).base_listen( propagate=True ) if active_history: mgr[target.key].dispatch._active_history = True def append( self, target: _O, value: _T, initiator: Event, *, key: EventConstants = NO_KEY, ) -> Optional[_T]: """Receive a collection append event. The append event is invoked for each element as it is appended to the collection. This occurs for single-item appends as well as for a "bulk replace" operation. :param target: the object instance receiving the event. If the listener is registered with ``raw=True``, this will be the :class:`.InstanceState` object. :param value: the value being appended. If this listener is registered with ``retval=True``, the listener function must return this value, or a new value which replaces it. :param initiator: An instance of :class:`.attributes.Event` representing the initiation of the event. May be modified from its original value by backref handlers in order to control chained event propagation, as well as be inspected for information about the source of the event. :param key: When the event is established using the :paramref:`.AttributeEvents.include_key` parameter set to True, this will be the key used in the operation, such as ``collection[some_key_or_index] = value``. The parameter is not passed to the event at all if the the :paramref:`.AttributeEvents.include_key` was not used to set up the event; this is to allow backwards compatibility with existing event handlers that don't include the ``key`` parameter. .. versionadded:: 2.0 :return: if the event was registered with ``retval=True``, the given value, or a new effective value, should be returned. .. seealso:: :class:`.AttributeEvents` - background on listener options such as propagation to subclasses. :meth:`.AttributeEvents.bulk_replace` """ def append_wo_mutation( self, target: _O, value: _T, initiator: Event, *, key: EventConstants = NO_KEY, ) -> None: """Receive a collection append event where the collection was not actually mutated. This event differs from :meth:`_orm.AttributeEvents.append` in that it is fired off for de-duplicating collections such as sets and dictionaries, when the object already exists in the target collection. The event does not have a return value and the identity of the given object cannot be changed. The event is used for cascading objects into a :class:`_orm.Session` when the collection has already been mutated via a backref event. :param target: the object instance receiving the event. If the listener is registered with ``raw=True``, this will be the :class:`.InstanceState` object. :param value: the value that would be appended if the object did not already exist in the collection. :param initiator: An instance of :class:`.attributes.Event` representing the initiation of the event. May be modified from its original value by backref handlers in order to control chained event propagation, as well as be inspected for information about the source of the event. :param key: When the event is established using the :paramref:`.AttributeEvents.include_key` parameter set to True, this will be the key used in the operation, such as ``collection[some_key_or_index] = value``. The parameter is not passed to the event at all if the the :paramref:`.AttributeEvents.include_key` was not used to set up the event; this is to allow backwards compatibility with existing event handlers that don't include the ``key`` parameter. .. versionadded:: 2.0 :return: No return value is defined for this event. .. versionadded:: 1.4.15 """ def bulk_replace( self, target: _O, values: Iterable[_T], initiator: Event, *, keys: Optional[Iterable[EventConstants]] = None, ) -> None: """Receive a collection 'bulk replace' event. This event is invoked for a sequence of values as they are incoming to a bulk collection set operation, which can be modified in place before the values are treated as ORM objects. This is an "early hook" that runs before the bulk replace routine attempts to reconcile which objects are already present in the collection and which are being removed by the net replace operation. It is typical that this method be combined with use of the :meth:`.AttributeEvents.append` event. When using both of these events, note that a bulk replace operation will invoke the :meth:`.AttributeEvents.append` event for all new items, even after :meth:`.AttributeEvents.bulk_replace` has been invoked for the collection as a whole. In order to determine if an :meth:`.AttributeEvents.append` event is part of a bulk replace, use the symbol :attr:`~.attributes.OP_BULK_REPLACE` to test the incoming initiator:: from sqlalchemy.orm.attributes import OP_BULK_REPLACE @event.listens_for(SomeObject.collection, "bulk_replace") def process_collection(target, values, initiator): values[:] = [_make_value(value) for value in values] @event.listens_for(SomeObject.collection, "append", retval=True) def process_collection(target, value, initiator): # make sure bulk_replace didn't already do it if initiator is None or initiator.op is not OP_BULK_REPLACE: return _make_value(value) else: return value .. versionadded:: 1.2 :param target: the object instance receiving the event. If the listener is registered with ``raw=True``, this will be the :class:`.InstanceState` object. :param value: a sequence (e.g. a list) of the values being set. The handler can modify this list in place. :param initiator: An instance of :class:`.attributes.Event` representing the initiation of the event. :param keys: When the event is established using the :paramref:`.AttributeEvents.include_key` parameter set to True, this will be the sequence of keys used in the operation, typically only for a dictionary update. The parameter is not passed to the event at all if the the :paramref:`.AttributeEvents.include_key` was not used to set up the event; this is to allow backwards compatibility with existing event handlers that don't include the ``key`` parameter. .. versionadded:: 2.0 .. seealso:: :class:`.AttributeEvents` - background on listener options such as propagation to subclasses. """ def remove( self, target: _O, value: _T, initiator: Event, *, key: EventConstants = NO_KEY, ) -> None: """Receive a collection remove event. :param target: the object instance receiving the event. If the listener is registered with ``raw=True``, this will be the :class:`.InstanceState` object. :param value: the value being removed. :param initiator: An instance of :class:`.attributes.Event` representing the initiation of the event. May be modified from its original value by backref handlers in order to control chained event propagation. :param key: When the event is established using the :paramref:`.AttributeEvents.include_key` parameter set to True, this will be the key used in the operation, such as ``del collection[some_key_or_index]``. The parameter is not passed to the event at all if the the :paramref:`.AttributeEvents.include_key` was not used to set up the event; this is to allow backwards compatibility with existing event handlers that don't include the ``key`` parameter. .. versionadded:: 2.0 :return: No return value is defined for this event. .. seealso:: :class:`.AttributeEvents` - background on listener options such as propagation to subclasses. """ def set( self, target: _O, value: _T, oldvalue: _T, initiator: Event ) -> None: """Receive a scalar set event. :param target: the object instance receiving the event. If the listener is registered with ``raw=True``, this will be the :class:`.InstanceState` object. :param value: the value being set. If this listener is registered with ``retval=True``, the listener function must return this value, or a new value which replaces it. :param oldvalue: the previous value being replaced. This may also be the symbol ``NEVER_SET`` or ``NO_VALUE``. If the listener is registered with ``active_history=True``, the previous value of the attribute will be loaded from the database if the existing value is currently unloaded or expired. :param initiator: An instance of :class:`.attributes.Event` representing the initiation of the event. May be modified from its original value by backref handlers in order to control chained event propagation. :return: if the event was registered with ``retval=True``, the given value, or a new effective value, should be returned. .. seealso:: :class:`.AttributeEvents` - background on listener options such as propagation to subclasses. """ def init_scalar( self, target: _O, value: _T, dict_: Dict[Any, Any] ) -> None: r"""Receive a scalar "init" event. This event is invoked when an uninitialized, unpersisted scalar attribute is accessed, e.g. read:: x = my_object.some_attribute The ORM's default behavior when this occurs for an un-initialized attribute is to return the value ``None``; note this differs from Python's usual behavior of raising ``AttributeError``. The event here can be used to customize what value is actually returned, with the assumption that the event listener would be mirroring a default generator that is configured on the Core :class:`_schema.Column` object as well. Since a default generator on a :class:`_schema.Column` might also produce a changing value such as a timestamp, the :meth:`.AttributeEvents.init_scalar` event handler can also be used to **set** the newly returned value, so that a Core-level default generation function effectively fires off only once, but at the moment the attribute is accessed on the non-persisted object. Normally, no change to the object's state is made when an uninitialized attribute is accessed (much older SQLAlchemy versions did in fact change the object's state). If a default generator on a column returned a particular constant, a handler might be used as follows:: SOME_CONSTANT = 3.1415926 class MyClass(Base): # ... some_attribute = Column(Numeric, default=SOME_CONSTANT) @event.listens_for( MyClass.some_attribute, "init_scalar", retval=True, propagate=True ) def _init_some_attribute(target, dict_, value): dict_["some_attribute"] = SOME_CONSTANT return SOME_CONSTANT Above, we initialize the attribute ``MyClass.some_attribute`` to the value of ``SOME_CONSTANT``. The above code includes the following features: * By setting the value ``SOME_CONSTANT`` in the given ``dict_``, we indicate that this value is to be persisted to the database. This supersedes the use of ``SOME_CONSTANT`` in the default generator for the :class:`_schema.Column`. The ``active_column_defaults.py`` example given at :ref:`examples_instrumentation` illustrates using the same approach for a changing default, e.g. a timestamp generator. In this particular example, it is not strictly necessary to do this since ``SOME_CONSTANT`` would be part of the INSERT statement in either case. * By establishing the ``retval=True`` flag, the value we return from the function will be returned by the attribute getter. Without this flag, the event is assumed to be a passive observer and the return value of our function is ignored. * The ``propagate=True`` flag is significant if the mapped class includes inheriting subclasses, which would also make use of this event listener. Without this flag, an inheriting subclass will not use our event handler. In the above example, the attribute set event :meth:`.AttributeEvents.set` as well as the related validation feature provided by :obj:`_orm.validates` is **not** invoked when we apply our value to the given ``dict_``. To have these events to invoke in response to our newly generated value, apply the value to the given object as a normal attribute set operation:: SOME_CONSTANT = 3.1415926 @event.listens_for( MyClass.some_attribute, "init_scalar", retval=True, propagate=True ) def _init_some_attribute(target, dict_, value): # will also fire off attribute set events target.some_attribute = SOME_CONSTANT return SOME_CONSTANT When multiple listeners are set up, the generation of the value is "chained" from one listener to the next by passing the value returned by the previous listener that specifies ``retval=True`` as the ``value`` argument of the next listener. :param target: the object instance receiving the event. If the listener is registered with ``raw=True``, this will be the :class:`.InstanceState` object. :param value: the value that is to be returned before this event listener were invoked. This value begins as the value ``None``, however will be the return value of the previous event handler function if multiple listeners are present. :param dict\_: the attribute dictionary of this mapped object. This is normally the ``__dict__`` of the object, but in all cases represents the destination that the attribute system uses to get at the actual value of this attribute. Placing the value in this dictionary has the effect that the value will be used in the INSERT statement generated by the unit of work. .. seealso:: :meth:`.AttributeEvents.init_collection` - collection version of this event :class:`.AttributeEvents` - background on listener options such as propagation to subclasses. :ref:`examples_instrumentation` - see the ``active_column_defaults.py`` example. """ # noqa: E501 def init_collection( self, target: _O, collection: Type[Collection[Any]], collection_adapter: CollectionAdapter, ) -> None: """Receive a 'collection init' event. This event is triggered for a collection-based attribute, when the initial "empty collection" is first generated for a blank attribute, as well as for when the collection is replaced with a new one, such as via a set event. E.g., given that ``User.addresses`` is a relationship-based collection, the event is triggered here:: u1 = User() u1.addresses.append(a1) # <- new collection and also during replace operations:: u1.addresses = [a2, a3] # <- new collection :param target: the object instance receiving the event. If the listener is registered with ``raw=True``, this will be the :class:`.InstanceState` object. :param collection: the new collection. This will always be generated from what was specified as :paramref:`_orm.relationship.collection_class`, and will always be empty. :param collection_adapter: the :class:`.CollectionAdapter` that will mediate internal access to the collection. .. seealso:: :class:`.AttributeEvents` - background on listener options such as propagation to subclasses. :meth:`.AttributeEvents.init_scalar` - "scalar" version of this event. """ def dispose_collection( self, target: _O, collection: Collection[Any], collection_adapter: CollectionAdapter, ) -> None: """Receive a 'collection dispose' event. This event is triggered for a collection-based attribute when a collection is replaced, that is:: u1.addresses.append(a1) u1.addresses = [a2, a3] # <- old collection is disposed The old collection received will contain its previous contents. .. versionchanged:: 1.2 The collection passed to :meth:`.AttributeEvents.dispose_collection` will now have its contents before the dispose intact; previously, the collection would be empty. .. seealso:: :class:`.AttributeEvents` - background on listener options such as propagation to subclasses. """ def modified(self, target: _O, initiator: Event) -> None: """Receive a 'modified' event. This event is triggered when the :func:`.attributes.flag_modified` function is used to trigger a modify event on an attribute without any specific value being set. .. versionadded:: 1.2 :param target: the object instance receiving the event. If the listener is registered with ``raw=True``, this will be the :class:`.InstanceState` object. :param initiator: An instance of :class:`.attributes.Event` representing the initiation of the event. .. seealso:: :class:`.AttributeEvents` - background on listener options such as propagation to subclasses. """ class QueryEvents(event.Events[Query[Any]]): """Represent events within the construction of a :class:`_query.Query` object. .. legacy:: The :class:`_orm.QueryEvents` event methods are legacy as of SQLAlchemy 2.0, and only apply to direct use of the :class:`_orm.Query` object. They are not used for :term:`2.0 style` statements. For events to intercept and modify 2.0 style ORM use, use the :meth:`_orm.SessionEvents.do_orm_execute` hook. The :class:`_orm.QueryEvents` hooks are now superseded by the :meth:`_orm.SessionEvents.do_orm_execute` event hook. """ _target_class_doc = "SomeQuery" _dispatch_target = Query def before_compile(self, query: Query[Any]) -> None: """Receive the :class:`_query.Query` object before it is composed into a core :class:`_expression.Select` object. .. deprecated:: 1.4 The :meth:`_orm.QueryEvents.before_compile` event is superseded by the much more capable :meth:`_orm.SessionEvents.do_orm_execute` hook. In version 1.4, the :meth:`_orm.QueryEvents.before_compile` event is **no longer used** for ORM-level attribute loads, such as loads of deferred or expired attributes as well as relationship loaders. See the new examples in :ref:`examples_session_orm_events` which illustrate new ways of intercepting and modifying ORM queries for the most common purpose of adding arbitrary filter criteria. This event is intended to allow changes to the query given:: @event.listens_for(Query, "before_compile", retval=True) def no_deleted(query): for desc in query.column_descriptions: if desc["type"] is User: entity = desc["entity"] query = query.filter(entity.deleted == False) return query The event should normally be listened with the ``retval=True`` parameter set, so that the modified query may be returned. The :meth:`.QueryEvents.before_compile` event by default will disallow "baked" queries from caching a query, if the event hook returns a new :class:`_query.Query` object. This affects both direct use of the baked query extension as well as its operation within lazy loaders and eager loaders for relationships. In order to re-establish the query being cached, apply the event adding the ``bake_ok`` flag:: @event.listens_for(Query, "before_compile", retval=True, bake_ok=True) def my_event(query): for desc in query.column_descriptions: if desc["type"] is User: entity = desc["entity"] query = query.filter(entity.deleted == False) return query When ``bake_ok`` is set to True, the event hook will only be invoked once, and not called for subsequent invocations of a particular query that is being cached. .. versionadded:: 1.3.11 - added the "bake_ok" flag to the :meth:`.QueryEvents.before_compile` event and disallowed caching via the "baked" extension from occurring for event handlers that return a new :class:`_query.Query` object if this flag is not set. .. seealso:: :meth:`.QueryEvents.before_compile_update` :meth:`.QueryEvents.before_compile_delete` :ref:`baked_with_before_compile` """ # noqa: E501 def before_compile_update( self, query: Query[Any], update_context: BulkUpdate ) -> None: """Allow modifications to the :class:`_query.Query` object within :meth:`_query.Query.update`. .. deprecated:: 1.4 The :meth:`_orm.QueryEvents.before_compile_update` event is superseded by the much more capable :meth:`_orm.SessionEvents.do_orm_execute` hook. Like the :meth:`.QueryEvents.before_compile` event, if the event is to be used to alter the :class:`_query.Query` object, it should be configured with ``retval=True``, and the modified :class:`_query.Query` object returned, as in :: @event.listens_for(Query, "before_compile_update", retval=True) def no_deleted(query, update_context): for desc in query.column_descriptions: if desc["type"] is User: entity = desc["entity"] query = query.filter(entity.deleted == False) update_context.values["timestamp"] = datetime.datetime.now( datetime.UTC ) return query The ``.values`` dictionary of the "update context" object can also be modified in place as illustrated above. :param query: a :class:`_query.Query` instance; this is also the ``.query`` attribute of the given "update context" object. :param update_context: an "update context" object which is the same kind of object as described in :paramref:`.QueryEvents.after_bulk_update.update_context`. The object has a ``.values`` attribute in an UPDATE context which is the dictionary of parameters passed to :meth:`_query.Query.update`. This dictionary can be modified to alter the VALUES clause of the resulting UPDATE statement. .. versionadded:: 1.2.17 .. seealso:: :meth:`.QueryEvents.before_compile` :meth:`.QueryEvents.before_compile_delete` """ # noqa: E501 def before_compile_delete( self, query: Query[Any], delete_context: BulkDelete ) -> None: """Allow modifications to the :class:`_query.Query` object within :meth:`_query.Query.delete`. .. deprecated:: 1.4 The :meth:`_orm.QueryEvents.before_compile_delete` event is superseded by the much more capable :meth:`_orm.SessionEvents.do_orm_execute` hook. Like the :meth:`.QueryEvents.before_compile` event, this event should be configured with ``retval=True``, and the modified :class:`_query.Query` object returned, as in :: @event.listens_for(Query, "before_compile_delete", retval=True) def no_deleted(query, delete_context): for desc in query.column_descriptions: if desc["type"] is User: entity = desc["entity"] query = query.filter(entity.deleted == False) return query :param query: a :class:`_query.Query` instance; this is also the ``.query`` attribute of the given "delete context" object. :param delete_context: a "delete context" object which is the same kind of object as described in :paramref:`.QueryEvents.after_bulk_delete.delete_context`. .. versionadded:: 1.2.17 .. seealso:: :meth:`.QueryEvents.before_compile` :meth:`.QueryEvents.before_compile_update` """ @classmethod def _listen( cls, event_key: _EventKey[_ET], retval: bool = False, bake_ok: bool = False, **kw: Any, ) -> None: fn = event_key._listen_fn if not retval: def wrap(*arg: Any, **kw: Any) -> Any: if not retval: query = arg[0] fn(*arg, **kw) return query else: return fn(*arg, **kw) event_key = event_key.with_wrapper(wrap) else: # don't assume we can apply an attribute to the callable def wrap(*arg: Any, **kw: Any) -> Any: return fn(*arg, **kw) event_key = event_key.with_wrapper(wrap) wrap._bake_ok = bake_ok # type: ignore [attr-defined] event_key.base_listen(**kw) sqlalchemy/orm/decl_base.py 0000755 00000242457 15125143220 0011772 0 ustar 00 # orm/decl_base.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """Internal implementation for declarative.""" from __future__ import annotations import collections import dataclasses import re from typing import Any from typing import Callable from typing import cast from typing import Dict from typing import Iterable from typing import List from typing import Mapping from typing import NamedTuple from typing import NoReturn from typing import Optional from typing import Sequence from typing import Tuple from typing import Type from typing import TYPE_CHECKING from typing import TypeVar from typing import Union import weakref from . import attributes from . import clsregistry from . import exc as orm_exc from . import instrumentation from . import mapperlib from ._typing import _O from ._typing import attr_is_internal_proxy from .attributes import InstrumentedAttribute from .attributes import QueryableAttribute from .base import _is_mapped_class from .base import InspectionAttr from .descriptor_props import CompositeProperty from .descriptor_props import SynonymProperty from .interfaces import _AttributeOptions from .interfaces import _DCAttributeOptions from .interfaces import _IntrospectsAnnotations from .interfaces import _MappedAttribute from .interfaces import _MapsColumns from .interfaces import MapperProperty from .mapper import Mapper from .properties import ColumnProperty from .properties import MappedColumn from .util import _extract_mapped_subtype from .util import _is_mapped_annotation from .util import class_mapper from .util import de_stringify_annotation from .. import event from .. import exc from .. import util from ..sql import expression from ..sql.base import _NoArg from ..sql.schema import Column from ..sql.schema import Table from ..util import topological from ..util.typing import _AnnotationScanType from ..util.typing import get_args from ..util.typing import is_fwd_ref from ..util.typing import is_literal from ..util.typing import Protocol from ..util.typing import TypedDict if TYPE_CHECKING: from ._typing import _ClassDict from ._typing import _RegistryType from .base import Mapped from .decl_api import declared_attr from .instrumentation import ClassManager from ..sql.elements import NamedColumn from ..sql.schema import MetaData from ..sql.selectable import FromClause _T = TypeVar("_T", bound=Any) _MapperKwArgs = Mapping[str, Any] _TableArgsType = Union[Tuple[Any, ...], Dict[str, Any]] class MappedClassProtocol(Protocol[_O]): """A protocol representing a SQLAlchemy mapped class. The protocol is generic on the type of class, use ``MappedClassProtocol[Any]`` to allow any mapped class. """ __name__: str __mapper__: Mapper[_O] __table__: FromClause def __call__(self, **kw: Any) -> _O: ... class _DeclMappedClassProtocol(MappedClassProtocol[_O], Protocol): "Internal more detailed version of ``MappedClassProtocol``." metadata: MetaData __tablename__: str __mapper_args__: _MapperKwArgs __table_args__: Optional[_TableArgsType] _sa_apply_dc_transforms: Optional[_DataclassArguments] def __declare_first__(self) -> None: ... def __declare_last__(self) -> None: ... class _DataclassArguments(TypedDict): init: Union[_NoArg, bool] repr: Union[_NoArg, bool] eq: Union[_NoArg, bool] order: Union[_NoArg, bool] unsafe_hash: Union[_NoArg, bool] match_args: Union[_NoArg, bool] kw_only: Union[_NoArg, bool] dataclass_callable: Union[_NoArg, Callable[..., Type[Any]]] def _declared_mapping_info( cls: Type[Any], ) -> Optional[Union[_DeferredMapperConfig, Mapper[Any]]]: # deferred mapping if _DeferredMapperConfig.has_cls(cls): return _DeferredMapperConfig.config_for_cls(cls) # regular mapping elif _is_mapped_class(cls): return class_mapper(cls, configure=False) else: return None def _is_supercls_for_inherits(cls: Type[Any]) -> bool: """return True if this class will be used as a superclass to set in 'inherits'. This includes deferred mapper configs that aren't mapped yet, however does not include classes with _sa_decl_prepare_nocascade (e.g. ``AbstractConcreteBase``); these concrete-only classes are not set up as "inherits" until after mappers are configured using mapper._set_concrete_base() """ if _DeferredMapperConfig.has_cls(cls): return not _get_immediate_cls_attr( cls, "_sa_decl_prepare_nocascade", strict=True ) # regular mapping elif _is_mapped_class(cls): return True else: return False def _resolve_for_abstract_or_classical(cls: Type[Any]) -> Optional[Type[Any]]: if cls is object: return None sup: Optional[Type[Any]] if cls.__dict__.get("__abstract__", False): for base_ in cls.__bases__: sup = _resolve_for_abstract_or_classical(base_) if sup is not None: return sup else: return None else: clsmanager = _dive_for_cls_manager(cls) if clsmanager: return clsmanager.class_ else: return cls def _get_immediate_cls_attr( cls: Type[Any], attrname: str, strict: bool = False ) -> Optional[Any]: """return an attribute of the class that is either present directly on the class, e.g. not on a superclass, or is from a superclass but this superclass is a non-mapped mixin, that is, not a descendant of the declarative base and is also not classically mapped. This is used to detect attributes that indicate something about a mapped class independently from any mapped classes that it may inherit from. """ # the rules are different for this name than others, # make sure we've moved it out. transitional assert attrname != "__abstract__" if not issubclass(cls, object): return None if attrname in cls.__dict__: return getattr(cls, attrname) for base in cls.__mro__[1:]: _is_classical_inherits = _dive_for_cls_manager(base) is not None if attrname in base.__dict__ and ( base is cls or ( (base in cls.__bases__ if strict else True) and not _is_classical_inherits ) ): return getattr(base, attrname) else: return None def _dive_for_cls_manager(cls: Type[_O]) -> Optional[ClassManager[_O]]: # because the class manager registration is pluggable, # we need to do the search for every class in the hierarchy, # rather than just a simple "cls._sa_class_manager" for base in cls.__mro__: manager: Optional[ClassManager[_O]] = attributes.opt_manager_of_class( base ) if manager: return manager return None def _as_declarative( registry: _RegistryType, cls: Type[Any], dict_: _ClassDict ) -> Optional[_MapperConfig]: # declarative scans the class for attributes. no table or mapper # args passed separately. return _MapperConfig.setup_mapping(registry, cls, dict_, None, {}) def _mapper( registry: _RegistryType, cls: Type[_O], table: Optional[FromClause], mapper_kw: _MapperKwArgs, ) -> Mapper[_O]: _ImperativeMapperConfig(registry, cls, table, mapper_kw) return cast("MappedClassProtocol[_O]", cls).__mapper__ @util.preload_module("sqlalchemy.orm.decl_api") def _is_declarative_props(obj: Any) -> bool: _declared_attr_common = util.preloaded.orm_decl_api._declared_attr_common return isinstance(obj, (_declared_attr_common, util.classproperty)) def _check_declared_props_nocascade( obj: Any, name: str, cls: Type[_O] ) -> bool: if _is_declarative_props(obj): if getattr(obj, "_cascading", False): util.warn( "@declared_attr.cascading is not supported on the %s " "attribute on class %s. This attribute invokes for " "subclasses in any case." % (name, cls) ) return True else: return False class _MapperConfig: __slots__ = ( "cls", "classname", "properties", "declared_attr_reg", "__weakref__", ) cls: Type[Any] classname: str properties: util.OrderedDict[ str, Union[ Sequence[NamedColumn[Any]], NamedColumn[Any], MapperProperty[Any] ], ] declared_attr_reg: Dict[declared_attr[Any], Any] @classmethod def setup_mapping( cls, registry: _RegistryType, cls_: Type[_O], dict_: _ClassDict, table: Optional[FromClause], mapper_kw: _MapperKwArgs, ) -> Optional[_MapperConfig]: manager = attributes.opt_manager_of_class(cls) if manager and manager.class_ is cls_: raise exc.InvalidRequestError( f"Class {cls!r} already has been instrumented declaratively" ) if cls_.__dict__.get("__abstract__", False): return None defer_map = _get_immediate_cls_attr( cls_, "_sa_decl_prepare_nocascade", strict=True ) or hasattr(cls_, "_sa_decl_prepare") if defer_map: return _DeferredMapperConfig( registry, cls_, dict_, table, mapper_kw ) else: return _ClassScanMapperConfig( registry, cls_, dict_, table, mapper_kw ) def __init__( self, registry: _RegistryType, cls_: Type[Any], mapper_kw: _MapperKwArgs, ): self.cls = util.assert_arg_type(cls_, type, "cls_") self.classname = cls_.__name__ self.properties = util.OrderedDict() self.declared_attr_reg = {} if not mapper_kw.get("non_primary", False): instrumentation.register_class( self.cls, finalize=False, registry=registry, declarative_scan=self, init_method=registry.constructor, ) else: manager = attributes.opt_manager_of_class(self.cls) if not manager or not manager.is_mapped: raise exc.InvalidRequestError( "Class %s has no primary mapper configured. Configure " "a primary mapper first before setting up a non primary " "Mapper." % self.cls ) def set_cls_attribute(self, attrname: str, value: _T) -> _T: manager = instrumentation.manager_of_class(self.cls) manager.install_member(attrname, value) return value def map(self, mapper_kw: _MapperKwArgs = ...) -> Mapper[Any]: raise NotImplementedError() def _early_mapping(self, mapper_kw: _MapperKwArgs) -> None: self.map(mapper_kw) class _ImperativeMapperConfig(_MapperConfig): __slots__ = ("local_table", "inherits") def __init__( self, registry: _RegistryType, cls_: Type[_O], table: Optional[FromClause], mapper_kw: _MapperKwArgs, ): super().__init__(registry, cls_, mapper_kw) self.local_table = self.set_cls_attribute("__table__", table) with mapperlib._CONFIGURE_MUTEX: if not mapper_kw.get("non_primary", False): clsregistry.add_class( self.classname, self.cls, registry._class_registry ) self._setup_inheritance(mapper_kw) self._early_mapping(mapper_kw) def map(self, mapper_kw: _MapperKwArgs = util.EMPTY_DICT) -> Mapper[Any]: mapper_cls = Mapper return self.set_cls_attribute( "__mapper__", mapper_cls(self.cls, self.local_table, **mapper_kw), ) def _setup_inheritance(self, mapper_kw: _MapperKwArgs) -> None: cls = self.cls inherits = mapper_kw.get("inherits", None) if inherits is None: # since we search for classical mappings now, search for # multiple mapped bases as well and raise an error. inherits_search = [] for base_ in cls.__bases__: c = _resolve_for_abstract_or_classical(base_) if c is None: continue if _is_supercls_for_inherits(c) and c not in inherits_search: inherits_search.append(c) if inherits_search: if len(inherits_search) > 1: raise exc.InvalidRequestError( "Class %s has multiple mapped bases: %r" % (cls, inherits_search) ) inherits = inherits_search[0] elif isinstance(inherits, Mapper): inherits = inherits.class_ self.inherits = inherits class _CollectedAnnotation(NamedTuple): raw_annotation: _AnnotationScanType mapped_container: Optional[Type[Mapped[Any]]] extracted_mapped_annotation: Union[_AnnotationScanType, str] is_dataclass: bool attr_value: Any originating_module: str originating_class: Type[Any] class _ClassScanMapperConfig(_MapperConfig): __slots__ = ( "registry", "clsdict_view", "collected_attributes", "collected_annotations", "local_table", "persist_selectable", "declared_columns", "column_ordering", "column_copies", "table_args", "tablename", "mapper_args", "mapper_args_fn", "table_fn", "inherits", "single", "allow_dataclass_fields", "dataclass_setup_arguments", "is_dataclass_prior_to_mapping", "allow_unmapped_annotations", ) is_deferred = False registry: _RegistryType clsdict_view: _ClassDict collected_annotations: Dict[str, _CollectedAnnotation] collected_attributes: Dict[str, Any] local_table: Optional[FromClause] persist_selectable: Optional[FromClause] declared_columns: util.OrderedSet[Column[Any]] column_ordering: Dict[Column[Any], int] column_copies: Dict[ Union[MappedColumn[Any], Column[Any]], Union[MappedColumn[Any], Column[Any]], ] tablename: Optional[str] mapper_args: Mapping[str, Any] table_args: Optional[_TableArgsType] mapper_args_fn: Optional[Callable[[], Dict[str, Any]]] inherits: Optional[Type[Any]] single: bool is_dataclass_prior_to_mapping: bool allow_unmapped_annotations: bool dataclass_setup_arguments: Optional[_DataclassArguments] """if the class has SQLAlchemy native dataclass parameters, where we will turn the class into a dataclass within the declarative mapping process. """ allow_dataclass_fields: bool """if true, look for dataclass-processed Field objects on the target class as well as superclasses and extract ORM mapping directives from the "metadata" attribute of each Field. if False, dataclass fields can still be used, however they won't be mapped. """ def __init__( self, registry: _RegistryType, cls_: Type[_O], dict_: _ClassDict, table: Optional[FromClause], mapper_kw: _MapperKwArgs, ): # grab class dict before the instrumentation manager has been added. # reduces cycles self.clsdict_view = ( util.immutabledict(dict_) if dict_ else util.EMPTY_DICT ) super().__init__(registry, cls_, mapper_kw) self.registry = registry self.persist_selectable = None self.collected_attributes = {} self.collected_annotations = {} self.declared_columns = util.OrderedSet() self.column_ordering = {} self.column_copies = {} self.single = False self.dataclass_setup_arguments = dca = getattr( self.cls, "_sa_apply_dc_transforms", None ) self.allow_unmapped_annotations = getattr( self.cls, "__allow_unmapped__", False ) or bool(self.dataclass_setup_arguments) self.is_dataclass_prior_to_mapping = cld = dataclasses.is_dataclass( cls_ ) sdk = _get_immediate_cls_attr(cls_, "__sa_dataclass_metadata_key__") # we don't want to consume Field objects from a not-already-dataclass. # the Field objects won't have their "name" or "type" populated, # and while it seems like we could just set these on Field as we # read them, Field is documented as "user read only" and we need to # stay far away from any off-label use of dataclasses APIs. if (not cld or dca) and sdk: raise exc.InvalidRequestError( "SQLAlchemy mapped dataclasses can't consume mapping " "information from dataclass.Field() objects if the immediate " "class is not already a dataclass." ) # if already a dataclass, and __sa_dataclass_metadata_key__ present, # then also look inside of dataclass.Field() objects yielded by # dataclasses.get_fields(cls) when scanning for attributes self.allow_dataclass_fields = bool(sdk and cld) self._setup_declared_events() self._scan_attributes() self._setup_dataclasses_transforms() with mapperlib._CONFIGURE_MUTEX: clsregistry.add_class( self.classname, self.cls, registry._class_registry ) self._setup_inheriting_mapper(mapper_kw) self._extract_mappable_attributes() self._extract_declared_columns() self._setup_table(table) self._setup_inheriting_columns(mapper_kw) self._early_mapping(mapper_kw) def _setup_declared_events(self) -> None: if _get_immediate_cls_attr(self.cls, "__declare_last__"): @event.listens_for(Mapper, "after_configured") def after_configured() -> None: cast( "_DeclMappedClassProtocol[Any]", self.cls ).__declare_last__() if _get_immediate_cls_attr(self.cls, "__declare_first__"): @event.listens_for(Mapper, "before_configured") def before_configured() -> None: cast( "_DeclMappedClassProtocol[Any]", self.cls ).__declare_first__() def _cls_attr_override_checker( self, cls: Type[_O] ) -> Callable[[str, Any], bool]: """Produce a function that checks if a class has overridden an attribute, taking SQLAlchemy-enabled dataclass fields into account. """ if self.allow_dataclass_fields: sa_dataclass_metadata_key = _get_immediate_cls_attr( cls, "__sa_dataclass_metadata_key__" ) else: sa_dataclass_metadata_key = None if not sa_dataclass_metadata_key: def attribute_is_overridden(key: str, obj: Any) -> bool: return getattr(cls, key, obj) is not obj else: all_datacls_fields = { f.name: f.metadata[sa_dataclass_metadata_key] for f in util.dataclass_fields(cls) if sa_dataclass_metadata_key in f.metadata } local_datacls_fields = { f.name: f.metadata[sa_dataclass_metadata_key] for f in util.local_dataclass_fields(cls) if sa_dataclass_metadata_key in f.metadata } absent = object() def attribute_is_overridden(key: str, obj: Any) -> bool: if _is_declarative_props(obj): obj = obj.fget # this function likely has some failure modes still if # someone is doing a deep mixing of the same attribute # name as plain Python attribute vs. dataclass field. ret = local_datacls_fields.get(key, absent) if _is_declarative_props(ret): ret = ret.fget if ret is obj: return False elif ret is not absent: return True all_field = all_datacls_fields.get(key, absent) ret = getattr(cls, key, obj) if ret is obj: return False # for dataclasses, this could be the # 'default' of the field. so filter more specifically # for an already-mapped InstrumentedAttribute if ret is not absent and isinstance( ret, InstrumentedAttribute ): return True if all_field is obj: return False elif all_field is not absent: return True # can't find another attribute return False return attribute_is_overridden _include_dunders = { "__table__", "__mapper_args__", "__tablename__", "__table_args__", } _match_exclude_dunders = re.compile(r"^(?:_sa_|__)") def _cls_attr_resolver( self, cls: Type[Any] ) -> Callable[[], Iterable[Tuple[str, Any, Any, bool]]]: """produce a function to iterate the "attributes" of a class which we want to consider for mapping, adjusting for SQLAlchemy fields embedded in dataclass fields. """ cls_annotations = util.get_annotations(cls) cls_vars = vars(cls) _include_dunders = self._include_dunders _match_exclude_dunders = self._match_exclude_dunders names = [ n for n in util.merge_lists_w_ordering( list(cls_vars), list(cls_annotations) ) if not _match_exclude_dunders.match(n) or n in _include_dunders ] if self.allow_dataclass_fields: sa_dataclass_metadata_key: Optional[str] = _get_immediate_cls_attr( cls, "__sa_dataclass_metadata_key__" ) else: sa_dataclass_metadata_key = None if not sa_dataclass_metadata_key: def local_attributes_for_class() -> ( Iterable[Tuple[str, Any, Any, bool]] ): return ( ( name, cls_vars.get(name), cls_annotations.get(name), False, ) for name in names ) else: dataclass_fields = { field.name: field for field in util.local_dataclass_fields(cls) } fixed_sa_dataclass_metadata_key = sa_dataclass_metadata_key def local_attributes_for_class() -> ( Iterable[Tuple[str, Any, Any, bool]] ): for name in names: field = dataclass_fields.get(name, None) if field and sa_dataclass_metadata_key in field.metadata: yield field.name, _as_dc_declaredattr( field.metadata, fixed_sa_dataclass_metadata_key ), cls_annotations.get(field.name), True else: yield name, cls_vars.get(name), cls_annotations.get( name ), False return local_attributes_for_class def _scan_attributes(self) -> None: cls = self.cls cls_as_Decl = cast("_DeclMappedClassProtocol[Any]", cls) clsdict_view = self.clsdict_view collected_attributes = self.collected_attributes column_copies = self.column_copies _include_dunders = self._include_dunders mapper_args_fn = None table_args = inherited_table_args = None table_fn = None tablename = None fixed_table = "__table__" in clsdict_view attribute_is_overridden = self._cls_attr_override_checker(self.cls) bases = [] for base in cls.__mro__: # collect bases and make sure standalone columns are copied # to be the column they will ultimately be on the class, # so that declared_attr functions use the right columns. # need to do this all the way up the hierarchy first # (see #8190) class_mapped = base is not cls and _is_supercls_for_inherits(base) local_attributes_for_class = self._cls_attr_resolver(base) if not class_mapped and base is not cls: locally_collected_columns = self._produce_column_copies( local_attributes_for_class, attribute_is_overridden, fixed_table, base, ) else: locally_collected_columns = {} bases.append( ( base, class_mapped, local_attributes_for_class, locally_collected_columns, ) ) for ( base, class_mapped, local_attributes_for_class, locally_collected_columns, ) in bases: # this transfer can also take place as we scan each name # for finer-grained control of how collected_attributes is # populated, as this is what impacts column ordering. # however it's simpler to get it out of the way here. collected_attributes.update(locally_collected_columns) for ( name, obj, annotation, is_dataclass_field, ) in local_attributes_for_class(): if name in _include_dunders: if name == "__mapper_args__": check_decl = _check_declared_props_nocascade( obj, name, cls ) if not mapper_args_fn and ( not class_mapped or check_decl ): # don't even invoke __mapper_args__ until # after we've determined everything about the # mapped table. # make a copy of it so a class-level dictionary # is not overwritten when we update column-based # arguments. def _mapper_args_fn() -> Dict[str, Any]: return dict(cls_as_Decl.__mapper_args__) mapper_args_fn = _mapper_args_fn elif name == "__tablename__": check_decl = _check_declared_props_nocascade( obj, name, cls ) if not tablename and (not class_mapped or check_decl): tablename = cls_as_Decl.__tablename__ elif name == "__table__": check_decl = _check_declared_props_nocascade( obj, name, cls ) # if a @declared_attr using "__table__" is detected, # wrap up a callable to look for "__table__" from # the final concrete class when we set up a table. # this was fixed by # #11509, regression in 2.0 from version 1.4. if check_decl and not table_fn: # don't even invoke __table__ until we're ready def _table_fn() -> FromClause: return cls_as_Decl.__table__ table_fn = _table_fn elif name == "__table_args__": check_decl = _check_declared_props_nocascade( obj, name, cls ) if not table_args and (not class_mapped or check_decl): table_args = cls_as_Decl.__table_args__ if not isinstance( table_args, (tuple, dict, type(None)) ): raise exc.ArgumentError( "__table_args__ value must be a tuple, " "dict, or None" ) if base is not cls: inherited_table_args = True else: # any other dunder names; should not be here # as we have tested for all four names in # _include_dunders assert False elif class_mapped: if _is_declarative_props(obj) and not obj._quiet: util.warn( "Regular (i.e. not __special__) " "attribute '%s.%s' uses @declared_attr, " "but owning class %s is mapped - " "not applying to subclass %s." % (base.__name__, name, base, cls) ) continue elif base is not cls: # we're a mixin, abstract base, or something that is # acting like that for now. if isinstance(obj, (Column, MappedColumn)): # already copied columns to the mapped class. continue elif isinstance(obj, MapperProperty): raise exc.InvalidRequestError( "Mapper properties (i.e. deferred," "column_property(), relationship(), etc.) must " "be declared as @declared_attr callables " "on declarative mixin classes. For dataclass " "field() objects, use a lambda:" ) elif _is_declarative_props(obj): # tried to get overloads to tell this to # pylance, no luck assert obj is not None if obj._cascading: if name in clsdict_view: # unfortunately, while we can use the user- # defined attribute here to allow a clean # override, if there's another # subclass below then it still tries to use # this. not sure if there is enough # information here to add this as a feature # later on. util.warn( "Attribute '%s' on class %s cannot be " "processed due to " "@declared_attr.cascading; " "skipping" % (name, cls) ) collected_attributes[name] = column_copies[obj] = ( ret ) = obj.__get__(obj, cls) setattr(cls, name, ret) else: if is_dataclass_field: # access attribute using normal class access # first, to see if it's been mapped on a # superclass. note if the dataclasses.field() # has "default", this value can be anything. ret = getattr(cls, name, None) # so, if it's anything that's not ORM # mapped, assume we should invoke the # declared_attr if not isinstance(ret, InspectionAttr): ret = obj.fget() else: # access attribute using normal class access. # if the declared attr already took place # on a superclass that is mapped, then # this is no longer a declared_attr, it will # be the InstrumentedAttribute ret = getattr(cls, name) # correct for proxies created from hybrid_property # or similar. note there is no known case that # produces nested proxies, so we are only # looking one level deep right now. if ( isinstance(ret, InspectionAttr) and attr_is_internal_proxy(ret) and not isinstance( ret.original_property, MapperProperty ) ): ret = ret.descriptor collected_attributes[name] = column_copies[obj] = ( ret ) if ( isinstance(ret, (Column, MapperProperty)) and ret.doc is None ): ret.doc = obj.__doc__ self._collect_annotation( name, obj._collect_return_annotation(), base, True, obj, ) elif _is_mapped_annotation(annotation, cls, base): # Mapped annotation without any object. # product_column_copies should have handled this. # if future support for other MapperProperty, # then test if this name is already handled and # otherwise proceed to generate. if not fixed_table: assert ( name in collected_attributes or attribute_is_overridden(name, None) ) continue else: # here, the attribute is some other kind of # property that we assume is not part of the # declarative mapping. however, check for some # more common mistakes self._warn_for_decl_attributes(base, name, obj) elif is_dataclass_field and ( name not in clsdict_view or clsdict_view[name] is not obj ): # here, we are definitely looking at the target class # and not a superclass. this is currently a # dataclass-only path. if the name is only # a dataclass field and isn't in local cls.__dict__, # put the object there. # assert that the dataclass-enabled resolver agrees # with what we are seeing assert not attribute_is_overridden(name, obj) if _is_declarative_props(obj): obj = obj.fget() collected_attributes[name] = obj self._collect_annotation( name, annotation, base, False, obj ) else: collected_annotation = self._collect_annotation( name, annotation, base, None, obj ) is_mapped = ( collected_annotation is not None and collected_annotation.mapped_container is not None ) generated_obj = ( collected_annotation.attr_value if collected_annotation is not None else obj ) if obj is None and not fixed_table and is_mapped: collected_attributes[name] = ( generated_obj if generated_obj is not None else MappedColumn() ) elif name in clsdict_view: collected_attributes[name] = obj # else if the name is not in the cls.__dict__, # don't collect it as an attribute. # we will see the annotation only, which is meaningful # both for mapping and dataclasses setup if inherited_table_args and not tablename: table_args = None self.table_args = table_args self.tablename = tablename self.mapper_args_fn = mapper_args_fn self.table_fn = table_fn def _setup_dataclasses_transforms(self) -> None: dataclass_setup_arguments = self.dataclass_setup_arguments if not dataclass_setup_arguments: return # can't use is_dataclass since it uses hasattr if "__dataclass_fields__" in self.cls.__dict__: raise exc.InvalidRequestError( f"Class {self.cls} is already a dataclass; ensure that " "base classes / decorator styles of establishing dataclasses " "are not being mixed. " "This can happen if a class that inherits from " "'MappedAsDataclass', even indirectly, is been mapped with " "'@registry.mapped_as_dataclass'" ) # can't create a dataclass if __table__ is already there. This would # fail an assertion when calling _get_arguments_for_make_dataclass: # assert False, "Mapped[] received without a mapping declaration" if "__table__" in self.cls.__dict__: raise exc.InvalidRequestError( f"Class {self.cls} already defines a '__table__'. " "ORM Annotated Dataclasses do not support a pre-existing " "'__table__' element" ) warn_for_non_dc_attrs = collections.defaultdict(list) def _allow_dataclass_field( key: str, originating_class: Type[Any] ) -> bool: if ( originating_class is not self.cls and "__dataclass_fields__" not in originating_class.__dict__ ): warn_for_non_dc_attrs[originating_class].append(key) return True manager = instrumentation.manager_of_class(self.cls) assert manager is not None field_list = [ _AttributeOptions._get_arguments_for_make_dataclass( key, anno, mapped_container, self.collected_attributes.get(key, _NoArg.NO_ARG), ) for key, anno, mapped_container in ( ( key, mapped_anno if mapped_anno else raw_anno, mapped_container, ) for key, ( raw_anno, mapped_container, mapped_anno, is_dc, attr_value, originating_module, originating_class, ) in self.collected_annotations.items() if _allow_dataclass_field(key, originating_class) and ( key not in self.collected_attributes # issue #9226; check for attributes that we've collected # which are already instrumented, which we would assume # mean we are in an ORM inheritance mapping and this # attribute is already mapped on the superclass. Under # no circumstance should any QueryableAttribute be sent to # the dataclass() function; anything that's mapped should # be Field and that's it or not isinstance( self.collected_attributes[key], QueryableAttribute ) ) ) ] if warn_for_non_dc_attrs: for ( originating_class, non_dc_attrs, ) in warn_for_non_dc_attrs.items(): util.warn_deprecated( f"When transforming {self.cls} to a dataclass, " f"attribute(s) " f"{', '.join(repr(key) for key in non_dc_attrs)} " f"originates from superclass " f"{originating_class}, which is not a dataclass. This " f"usage is deprecated and will raise an error in " f"SQLAlchemy 2.1. When declaring SQLAlchemy Declarative " f"Dataclasses, ensure that all mixin classes and other " f"superclasses which include attributes are also a " f"subclass of MappedAsDataclass.", "2.0", code="dcmx", ) annotations = {} defaults = {} for item in field_list: if len(item) == 2: name, tp = item elif len(item) == 3: name, tp, spec = item defaults[name] = spec else: assert False annotations[name] = tp for k, v in defaults.items(): setattr(self.cls, k, v) self._apply_dataclasses_to_any_class( dataclass_setup_arguments, self.cls, annotations ) @classmethod def _update_annotations_for_non_mapped_class( cls, klass: Type[_O] ) -> Mapping[str, _AnnotationScanType]: cls_annotations = util.get_annotations(klass) new_anno = {} for name, annotation in cls_annotations.items(): if _is_mapped_annotation(annotation, klass, klass): extracted = _extract_mapped_subtype( annotation, klass, klass.__module__, name, type(None), required=False, is_dataclass_field=False, expect_mapped=False, ) if extracted: inner, _ = extracted new_anno[name] = inner else: new_anno[name] = annotation return new_anno @classmethod def _apply_dataclasses_to_any_class( cls, dataclass_setup_arguments: _DataclassArguments, klass: Type[_O], use_annotations: Mapping[str, _AnnotationScanType], ) -> None: cls._assert_dc_arguments(dataclass_setup_arguments) dataclass_callable = dataclass_setup_arguments["dataclass_callable"] if dataclass_callable is _NoArg.NO_ARG: dataclass_callable = dataclasses.dataclass restored: Optional[Any] if use_annotations: # apply constructed annotations that should look "normal" to a # dataclasses callable, based on the fields present. This # means remove the Mapped[] container and ensure all Field # entries have an annotation restored = getattr(klass, "__annotations__", None) klass.__annotations__ = cast("Dict[str, Any]", use_annotations) else: restored = None try: dataclass_callable( klass, **{ k: v for k, v in dataclass_setup_arguments.items() if v is not _NoArg.NO_ARG and k != "dataclass_callable" }, ) except (TypeError, ValueError) as ex: raise exc.InvalidRequestError( f"Python dataclasses error encountered when creating " f"dataclass for {klass.__name__!r}: " f"{ex!r}. Please refer to Python dataclasses " "documentation for additional information.", code="dcte", ) from ex finally: # restore original annotations outside of the dataclasses # process; for mixins and __abstract__ superclasses, SQLAlchemy # Declarative will need to see the Mapped[] container inside the # annotations in order to map subclasses if use_annotations: if restored is None: del klass.__annotations__ else: klass.__annotations__ = restored @classmethod def _assert_dc_arguments(cls, arguments: _DataclassArguments) -> None: allowed = { "init", "repr", "order", "eq", "unsafe_hash", "kw_only", "match_args", "dataclass_callable", } disallowed_args = set(arguments).difference(allowed) if disallowed_args: msg = ", ".join(f"{arg!r}" for arg in sorted(disallowed_args)) raise exc.ArgumentError( f"Dataclass argument(s) {msg} are not accepted" ) def _collect_annotation( self, name: str, raw_annotation: _AnnotationScanType, originating_class: Type[Any], expect_mapped: Optional[bool], attr_value: Any, ) -> Optional[_CollectedAnnotation]: if name in self.collected_annotations: return self.collected_annotations[name] if raw_annotation is None: return None is_dataclass = self.is_dataclass_prior_to_mapping allow_unmapped = self.allow_unmapped_annotations if expect_mapped is None: is_dataclass_field = isinstance(attr_value, dataclasses.Field) expect_mapped = ( not is_dataclass_field and not allow_unmapped and ( attr_value is None or isinstance(attr_value, _MappedAttribute) ) ) is_dataclass_field = False extracted = _extract_mapped_subtype( raw_annotation, self.cls, originating_class.__module__, name, type(attr_value), required=False, is_dataclass_field=is_dataclass_field, expect_mapped=expect_mapped and not is_dataclass, ) if extracted is None: # ClassVar can come out here return None extracted_mapped_annotation, mapped_container = extracted if attr_value is None and not is_literal(extracted_mapped_annotation): for elem in get_args(extracted_mapped_annotation): if is_fwd_ref( elem, check_generic=True, check_for_plain_string=True ): elem = de_stringify_annotation( self.cls, elem, originating_class.__module__, include_generic=True, ) # look in Annotated[...] for an ORM construct, # such as Annotated[int, mapped_column(primary_key=True)] if isinstance(elem, _IntrospectsAnnotations): attr_value = elem.found_in_pep593_annotated() self.collected_annotations[name] = ca = _CollectedAnnotation( raw_annotation, mapped_container, extracted_mapped_annotation, is_dataclass, attr_value, originating_class.__module__, originating_class, ) return ca def _warn_for_decl_attributes( self, cls: Type[Any], key: str, c: Any ) -> None: if isinstance(c, expression.ColumnElement): util.warn( f"Attribute '{key}' on class {cls} appears to " "be a non-schema SQLAlchemy expression " "object; this won't be part of the declarative mapping. " "To map arbitrary expressions, use ``column_property()`` " "or a similar function such as ``deferred()``, " "``query_expression()`` etc. " ) def _produce_column_copies( self, attributes_for_class: Callable[ [], Iterable[Tuple[str, Any, Any, bool]] ], attribute_is_overridden: Callable[[str, Any], bool], fixed_table: bool, originating_class: Type[Any], ) -> Dict[str, Union[Column[Any], MappedColumn[Any]]]: cls = self.cls dict_ = self.clsdict_view locally_collected_attributes = {} column_copies = self.column_copies # copy mixin columns to the mapped class for name, obj, annotation, is_dataclass in attributes_for_class(): if ( not fixed_table and obj is None and _is_mapped_annotation(annotation, cls, originating_class) ): # obj is None means this is the annotation only path if attribute_is_overridden(name, obj): # perform same "overridden" check as we do for # Column/MappedColumn, this is how a mixin col is not # applied to an inherited subclass that does not have # the mixin. the anno-only path added here for # #9564 continue collected_annotation = self._collect_annotation( name, annotation, originating_class, True, obj ) obj = ( collected_annotation.attr_value if collected_annotation is not None else obj ) if obj is None: obj = MappedColumn() locally_collected_attributes[name] = obj setattr(cls, name, obj) elif isinstance(obj, (Column, MappedColumn)): if attribute_is_overridden(name, obj): # if column has been overridden # (like by the InstrumentedAttribute of the # superclass), skip. don't collect the annotation # either (issue #8718) continue collected_annotation = self._collect_annotation( name, annotation, originating_class, True, obj ) obj = ( collected_annotation.attr_value if collected_annotation is not None else obj ) if name not in dict_ and not ( "__table__" in dict_ and (getattr(obj, "name", None) or name) in dict_["__table__"].c ): if obj.foreign_keys: for fk in obj.foreign_keys: if ( fk._table_column is not None and fk._table_column.table is None ): raise exc.InvalidRequestError( "Columns with foreign keys to " "non-table-bound " "columns must be declared as " "@declared_attr callables " "on declarative mixin classes. " "For dataclass " "field() objects, use a lambda:." ) column_copies[obj] = copy_ = obj._copy() locally_collected_attributes[name] = copy_ setattr(cls, name, copy_) return locally_collected_attributes def _extract_mappable_attributes(self) -> None: cls = self.cls collected_attributes = self.collected_attributes our_stuff = self.properties _include_dunders = self._include_dunders late_mapped = _get_immediate_cls_attr( cls, "_sa_decl_prepare_nocascade", strict=True ) allow_unmapped_annotations = self.allow_unmapped_annotations expect_annotations_wo_mapped = ( allow_unmapped_annotations or self.is_dataclass_prior_to_mapping ) look_for_dataclass_things = bool(self.dataclass_setup_arguments) for k in list(collected_attributes): if k in _include_dunders: continue value = collected_attributes[k] if _is_declarative_props(value): # @declared_attr in collected_attributes only occurs here for a # @declared_attr that's directly on the mapped class; # for a mixin, these have already been evaluated if value._cascading: util.warn( "Use of @declared_attr.cascading only applies to " "Declarative 'mixin' and 'abstract' classes. " "Currently, this flag is ignored on mapped class " "%s" % self.cls ) value = getattr(cls, k) elif ( isinstance(value, QueryableAttribute) and value.class_ is not cls and value.key != k ): # detect a QueryableAttribute that's already mapped being # assigned elsewhere in userland, turn into a synonym() value = SynonymProperty(value.key) setattr(cls, k, value) if ( isinstance(value, tuple) and len(value) == 1 and isinstance(value[0], (Column, _MappedAttribute)) ): util.warn( "Ignoring declarative-like tuple value of attribute " "'%s': possibly a copy-and-paste error with a comma " "accidentally placed at the end of the line?" % k ) continue elif look_for_dataclass_things and isinstance( value, dataclasses.Field ): # we collected a dataclass Field; dataclasses would have # set up the correct state on the class continue elif not isinstance(value, (Column, _DCAttributeOptions)): # using @declared_attr for some object that # isn't Column/MapperProperty/_DCAttributeOptions; remove # from the clsdict_view # and place the evaluated value onto the class. collected_attributes.pop(k) self._warn_for_decl_attributes(cls, k, value) if not late_mapped: setattr(cls, k, value) continue # we expect to see the name 'metadata' in some valid cases; # however at this point we see it's assigned to something trying # to be mapped, so raise for that. # TODO: should "registry" here be also? might be too late # to change that now (2.0 betas) elif k in ("metadata",): raise exc.InvalidRequestError( f"Attribute name '{k}' is reserved when using the " "Declarative API." ) elif isinstance(value, Column): _undefer_column_name( k, self.column_copies.get(value, value) # type: ignore ) else: if isinstance(value, _IntrospectsAnnotations): ( annotation, mapped_container, extracted_mapped_annotation, is_dataclass, attr_value, originating_module, originating_class, ) = self.collected_annotations.get( k, (None, None, None, False, None, None, None) ) # issue #8692 - don't do any annotation interpretation if # an annotation were present and a container such as # Mapped[] etc. were not used. If annotation is None, # do declarative_scan so that the property can raise # for required if ( mapped_container is not None or annotation is None # issue #10516: need to do declarative_scan even with # a non-Mapped annotation if we are doing # __allow_unmapped__, for things like col.name # assignment or allow_unmapped_annotations ): try: value.declarative_scan( self, self.registry, cls, originating_module, k, mapped_container, annotation, extracted_mapped_annotation, is_dataclass, ) except NameError as ne: raise orm_exc.MappedAnnotationError( f"Could not resolve all types within mapped " f'annotation: "{annotation}". Ensure all ' f"types are written correctly and are " f"imported within the module in use." ) from ne else: # assert that we were expecting annotations # without Mapped[] were going to be passed. # otherwise an error should have been raised # by util._extract_mapped_subtype before we got here. assert expect_annotations_wo_mapped if isinstance(value, _DCAttributeOptions): if ( value._has_dataclass_arguments and not look_for_dataclass_things ): if isinstance(value, MapperProperty): argnames = [ "init", "default_factory", "repr", "default", ] else: argnames = ["init", "default_factory", "repr"] args = { a for a in argnames if getattr( value._attribute_options, f"dataclasses_{a}" ) is not _NoArg.NO_ARG } raise exc.ArgumentError( f"Attribute '{k}' on class {cls} includes " f"dataclasses argument(s): " f"{', '.join(sorted(repr(a) for a in args))} but " f"class does not specify " "SQLAlchemy native dataclass configuration." ) if not isinstance(value, (MapperProperty, _MapsColumns)): # filter for _DCAttributeOptions objects that aren't # MapperProperty / mapped_column(). Currently this # includes AssociationProxy. pop it from the things # we're going to map and set it up as a descriptor # on the class. collected_attributes.pop(k) # Assoc Prox (or other descriptor object that may # use _DCAttributeOptions) is usually here, except if # 1. we're a # dataclass, dataclasses would have removed the # attr here or 2. assoc proxy is coming from a # superclass, we want it to be direct here so it # tracks state or 3. assoc prox comes from # declared_attr, uncommon case setattr(cls, k, value) continue our_stuff[k] = value def _extract_declared_columns(self) -> None: our_stuff = self.properties # extract columns from the class dict declared_columns = self.declared_columns column_ordering = self.column_ordering name_to_prop_key = collections.defaultdict(set) for key, c in list(our_stuff.items()): if isinstance(c, _MapsColumns): mp_to_assign = c.mapper_property_to_assign if mp_to_assign: our_stuff[key] = mp_to_assign else: # if no mapper property to assign, this currently means # this is a MappedColumn that will produce a Column for us del our_stuff[key] for col, sort_order in c.columns_to_assign: if not isinstance(c, CompositeProperty): name_to_prop_key[col.name].add(key) declared_columns.add(col) # we would assert this, however we want the below # warning to take effect instead. See #9630 # assert col not in column_ordering column_ordering[col] = sort_order # if this is a MappedColumn and the attribute key we # have is not what the column has for its key, map the # Column explicitly under the attribute key name. # otherwise, Mapper will map it under the column key. if mp_to_assign is None and key != col.key: our_stuff[key] = col elif isinstance(c, Column): # undefer previously occurred here, and now occurs earlier. # ensure every column we get here has been named assert c.name is not None name_to_prop_key[c.name].add(key) declared_columns.add(c) # if the column is the same name as the key, # remove it from the explicit properties dict. # the normal rules for assigning column-based properties # will take over, including precedence of columns # in multi-column ColumnProperties. if key == c.key: del our_stuff[key] for name, keys in name_to_prop_key.items(): if len(keys) > 1: util.warn( "On class %r, Column object %r named " "directly multiple times, " "only one will be used: %s. " "Consider using orm.synonym instead" % (self.classname, name, (", ".join(sorted(keys)))) ) def _setup_table(self, table: Optional[FromClause] = None) -> None: cls = self.cls cls_as_Decl = cast("MappedClassProtocol[Any]", cls) tablename = self.tablename table_args = self.table_args clsdict_view = self.clsdict_view declared_columns = self.declared_columns column_ordering = self.column_ordering manager = attributes.manager_of_class(cls) if ( self.table_fn is None and "__table__" not in clsdict_view and table is None ): if hasattr(cls, "__table_cls__"): table_cls = cast( Type[Table], util.unbound_method_to_callable(cls.__table_cls__), # type: ignore # noqa: E501 ) else: table_cls = Table if tablename is not None: args: Tuple[Any, ...] = () table_kw: Dict[str, Any] = {} if table_args: if isinstance(table_args, dict): table_kw = table_args elif isinstance(table_args, tuple): if isinstance(table_args[-1], dict): args, table_kw = table_args[0:-1], table_args[-1] else: args = table_args autoload_with = clsdict_view.get("__autoload_with__") if autoload_with: table_kw["autoload_with"] = autoload_with autoload = clsdict_view.get("__autoload__") if autoload: table_kw["autoload"] = True sorted_columns = sorted( declared_columns, key=lambda c: column_ordering.get(c, 0), ) table = self.set_cls_attribute( "__table__", table_cls( tablename, self._metadata_for_cls(manager), *sorted_columns, *args, **table_kw, ), ) else: if table is None: if self.table_fn: table = self.set_cls_attribute( "__table__", self.table_fn() ) else: table = cls_as_Decl.__table__ if declared_columns: for c in declared_columns: if not table.c.contains_column(c): raise exc.ArgumentError( "Can't add additional column %r when " "specifying __table__" % c.key ) self.local_table = table def _metadata_for_cls(self, manager: ClassManager[Any]) -> MetaData: meta: Optional[MetaData] = getattr(self.cls, "metadata", None) if meta is not None: return meta else: return manager.registry.metadata def _setup_inheriting_mapper(self, mapper_kw: _MapperKwArgs) -> None: cls = self.cls inherits = mapper_kw.get("inherits", None) if inherits is None: # since we search for classical mappings now, search for # multiple mapped bases as well and raise an error. inherits_search = [] for base_ in cls.__bases__: c = _resolve_for_abstract_or_classical(base_) if c is None: continue if _is_supercls_for_inherits(c) and c not in inherits_search: inherits_search.append(c) if inherits_search: if len(inherits_search) > 1: raise exc.InvalidRequestError( "Class %s has multiple mapped bases: %r" % (cls, inherits_search) ) inherits = inherits_search[0] elif isinstance(inherits, Mapper): inherits = inherits.class_ self.inherits = inherits clsdict_view = self.clsdict_view if "__table__" not in clsdict_view and self.tablename is None: self.single = True def _setup_inheriting_columns(self, mapper_kw: _MapperKwArgs) -> None: table = self.local_table cls = self.cls table_args = self.table_args declared_columns = self.declared_columns if ( table is None and self.inherits is None and not _get_immediate_cls_attr(cls, "__no_table__") ): raise exc.InvalidRequestError( "Class %r does not have a __table__ or __tablename__ " "specified and does not inherit from an existing " "table-mapped class." % cls ) elif self.inherits: inherited_mapper_or_config = _declared_mapping_info(self.inherits) assert inherited_mapper_or_config is not None inherited_table = inherited_mapper_or_config.local_table inherited_persist_selectable = ( inherited_mapper_or_config.persist_selectable ) if table is None: # single table inheritance. # ensure no table args if table_args: raise exc.ArgumentError( "Can't place __table_args__ on an inherited class " "with no table." ) # add any columns declared here to the inherited table. if declared_columns and not isinstance(inherited_table, Table): raise exc.ArgumentError( f"Can't declare columns on single-table-inherited " f"subclass {self.cls}; superclass {self.inherits} " "is not mapped to a Table" ) for col in declared_columns: assert inherited_table is not None if col.name in inherited_table.c: if inherited_table.c[col.name] is col: continue raise exc.ArgumentError( f"Column '{col}' on class {cls.__name__} " f"conflicts with existing column " f"'{inherited_table.c[col.name]}'. If using " f"Declarative, consider using the " "use_existing_column parameter of mapped_column() " "to resolve conflicts." ) if col.primary_key: raise exc.ArgumentError( "Can't place primary key columns on an inherited " "class with no table." ) if TYPE_CHECKING: assert isinstance(inherited_table, Table) inherited_table.append_column(col) if ( inherited_persist_selectable is not None and inherited_persist_selectable is not inherited_table ): inherited_persist_selectable._refresh_for_new_column( col ) def _prepare_mapper_arguments(self, mapper_kw: _MapperKwArgs) -> None: properties = self.properties if self.mapper_args_fn: mapper_args = self.mapper_args_fn() else: mapper_args = {} if mapper_kw: mapper_args.update(mapper_kw) if "properties" in mapper_args: properties = dict(properties) properties.update(mapper_args["properties"]) # make sure that column copies are used rather # than the original columns from any mixins for k in ("version_id_col", "polymorphic_on"): if k in mapper_args: v = mapper_args[k] mapper_args[k] = self.column_copies.get(v, v) if "primary_key" in mapper_args: mapper_args["primary_key"] = [ self.column_copies.get(v, v) for v in util.to_list(mapper_args["primary_key"]) ] if "inherits" in mapper_args: inherits_arg = mapper_args["inherits"] if isinstance(inherits_arg, Mapper): inherits_arg = inherits_arg.class_ if inherits_arg is not self.inherits: raise exc.InvalidRequestError( "mapper inherits argument given for non-inheriting " "class %s" % (mapper_args["inherits"]) ) if self.inherits: mapper_args["inherits"] = self.inherits if self.inherits and not mapper_args.get("concrete", False): # note the superclass is expected to have a Mapper assigned and # not be a deferred config, as this is called within map() inherited_mapper = class_mapper(self.inherits, False) inherited_table = inherited_mapper.local_table # single or joined inheritance # exclude any cols on the inherited table which are # not mapped on the parent class, to avoid # mapping columns specific to sibling/nephew classes if "exclude_properties" not in mapper_args: mapper_args["exclude_properties"] = exclude_properties = { c.key for c in inherited_table.c if c not in inherited_mapper._columntoproperty }.union(inherited_mapper.exclude_properties or ()) exclude_properties.difference_update( [c.key for c in self.declared_columns] ) # look through columns in the current mapper that # are keyed to a propname different than the colname # (if names were the same, we'd have popped it out above, # in which case the mapper makes this combination). # See if the superclass has a similar column property. # If so, join them together. for k, col in list(properties.items()): if not isinstance(col, expression.ColumnElement): continue if k in inherited_mapper._props: p = inherited_mapper._props[k] if isinstance(p, ColumnProperty): # note here we place the subclass column # first. See [ticket:1892] for background. properties[k] = [col] + p.columns result_mapper_args = mapper_args.copy() result_mapper_args["properties"] = properties self.mapper_args = result_mapper_args def map(self, mapper_kw: _MapperKwArgs = util.EMPTY_DICT) -> Mapper[Any]: self._prepare_mapper_arguments(mapper_kw) if hasattr(self.cls, "__mapper_cls__"): mapper_cls = cast( "Type[Mapper[Any]]", util.unbound_method_to_callable( self.cls.__mapper_cls__ # type: ignore ), ) else: mapper_cls = Mapper return self.set_cls_attribute( "__mapper__", mapper_cls(self.cls, self.local_table, **self.mapper_args), ) @util.preload_module("sqlalchemy.orm.decl_api") def _as_dc_declaredattr( field_metadata: Mapping[str, Any], sa_dataclass_metadata_key: str ) -> Any: # wrap lambdas inside dataclass fields inside an ad-hoc declared_attr. # we can't write it because field.metadata is immutable :( so we have # to go through extra trouble to compare these decl_api = util.preloaded.orm_decl_api obj = field_metadata[sa_dataclass_metadata_key] if callable(obj) and not isinstance(obj, decl_api.declared_attr): return decl_api.declared_attr(obj) else: return obj class _DeferredMapperConfig(_ClassScanMapperConfig): _cls: weakref.ref[Type[Any]] is_deferred = True _configs: util.OrderedDict[ weakref.ref[Type[Any]], _DeferredMapperConfig ] = util.OrderedDict() def _early_mapping(self, mapper_kw: _MapperKwArgs) -> None: pass # mypy disallows plain property override of variable @property # type: ignore def cls(self) -> Type[Any]: return self._cls() # type: ignore @cls.setter def cls(self, class_: Type[Any]) -> None: self._cls = weakref.ref(class_, self._remove_config_cls) self._configs[self._cls] = self @classmethod def _remove_config_cls(cls, ref: weakref.ref[Type[Any]]) -> None: cls._configs.pop(ref, None) @classmethod def has_cls(cls, class_: Type[Any]) -> bool: # 2.6 fails on weakref if class_ is an old style class return isinstance(class_, type) and weakref.ref(class_) in cls._configs @classmethod def raise_unmapped_for_cls(cls, class_: Type[Any]) -> NoReturn: if hasattr(class_, "_sa_raise_deferred_config"): class_._sa_raise_deferred_config() raise orm_exc.UnmappedClassError( class_, msg=( f"Class {orm_exc._safe_cls_name(class_)} has a deferred " "mapping on it. It is not yet usable as a mapped class." ), ) @classmethod def config_for_cls(cls, class_: Type[Any]) -> _DeferredMapperConfig: return cls._configs[weakref.ref(class_)] @classmethod def classes_for_base( cls, base_cls: Type[Any], sort: bool = True ) -> List[_DeferredMapperConfig]: classes_for_base = [ m for m, cls_ in [(m, m.cls) for m in cls._configs.values()] if cls_ is not None and issubclass(cls_, base_cls) ] if not sort: return classes_for_base all_m_by_cls = {m.cls: m for m in classes_for_base} tuples: List[Tuple[_DeferredMapperConfig, _DeferredMapperConfig]] = [] for m_cls in all_m_by_cls: tuples.extend( (all_m_by_cls[base_cls], all_m_by_cls[m_cls]) for base_cls in m_cls.__bases__ if base_cls in all_m_by_cls ) return list(topological.sort(tuples, classes_for_base)) def map(self, mapper_kw: _MapperKwArgs = util.EMPTY_DICT) -> Mapper[Any]: self._configs.pop(self._cls, None) return super().map(mapper_kw) def _add_attribute( cls: Type[Any], key: str, value: MapperProperty[Any] ) -> None: """add an attribute to an existing declarative class. This runs through the logic to determine MapperProperty, adds it to the Mapper, adds a column to the mapped Table, etc. """ if "__mapper__" in cls.__dict__: mapped_cls = cast("MappedClassProtocol[Any]", cls) def _table_or_raise(mc: MappedClassProtocol[Any]) -> Table: if isinstance(mc.__table__, Table): return mc.__table__ raise exc.InvalidRequestError( f"Cannot add a new attribute to mapped class {mc.__name__!r} " "because it's not mapped against a table." ) if isinstance(value, Column): _undefer_column_name(key, value) _table_or_raise(mapped_cls).append_column( value, replace_existing=True ) mapped_cls.__mapper__.add_property(key, value) elif isinstance(value, _MapsColumns): mp = value.mapper_property_to_assign for col, _ in value.columns_to_assign: _undefer_column_name(key, col) _table_or_raise(mapped_cls).append_column( col, replace_existing=True ) if not mp: mapped_cls.__mapper__.add_property(key, col) if mp: mapped_cls.__mapper__.add_property(key, mp) elif isinstance(value, MapperProperty): mapped_cls.__mapper__.add_property(key, value) elif isinstance(value, QueryableAttribute) and value.key != key: # detect a QueryableAttribute that's already mapped being # assigned elsewhere in userland, turn into a synonym() value = SynonymProperty(value.key) mapped_cls.__mapper__.add_property(key, value) else: type.__setattr__(cls, key, value) mapped_cls.__mapper__._expire_memoizations() else: type.__setattr__(cls, key, value) def _del_attribute(cls: Type[Any], key: str) -> None: if ( "__mapper__" in cls.__dict__ and key in cls.__dict__ and not cast( "MappedClassProtocol[Any]", cls ).__mapper__._dispose_called ): value = cls.__dict__[key] if isinstance( value, (Column, _MapsColumns, MapperProperty, QueryableAttribute) ): raise NotImplementedError( "Can't un-map individual mapped attributes on a mapped class." ) else: type.__delattr__(cls, key) cast( "MappedClassProtocol[Any]", cls ).__mapper__._expire_memoizations() else: type.__delattr__(cls, key) def _declarative_constructor(self: Any, **kwargs: Any) -> None: """A simple constructor that allows initialization from kwargs. Sets attributes on the constructed instance using the names and values in ``kwargs``. Only keys that are present as attributes of the instance's class are allowed. These could be, for example, any mapped columns or relationships. """ cls_ = type(self) for k in kwargs: if not hasattr(cls_, k): raise TypeError( "%r is an invalid keyword argument for %s" % (k, cls_.__name__) ) setattr(self, k, kwargs[k]) _declarative_constructor.__name__ = "__init__" def _undefer_column_name(key: str, column: Column[Any]) -> None: if column.key is None: column.key = key if column.name is None: column.name = key sqlalchemy/orm/loading.py 0000755 00000161645 15125143220 0011505 0 ustar 00 # orm/loading.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors """private module containing functions used to convert database rows into object instances and associated state. the functions here are called primarily by Query, Mapper, as well as some of the attribute loading strategies. """ from __future__ import annotations from typing import Any from typing import Dict from typing import Iterable from typing import List from typing import Mapping from typing import Optional from typing import Sequence from typing import Tuple from typing import TYPE_CHECKING from typing import TypeVar from typing import Union from . import attributes from . import exc as orm_exc from . import path_registry from .base import _DEFER_FOR_STATE from .base import _RAISE_FOR_STATE from .base import _SET_DEFERRED_EXPIRED from .base import PassiveFlag from .context import FromStatement from .context import ORMCompileState from .context import QueryContext from .util import _none_set from .util import state_str from .. import exc as sa_exc from .. import util from ..engine import result_tuple from ..engine.result import ChunkedIteratorResult from ..engine.result import FrozenResult from ..engine.result import SimpleResultMetaData from ..sql import select from ..sql import util as sql_util from ..sql.selectable import ForUpdateArg from ..sql.selectable import LABEL_STYLE_TABLENAME_PLUS_COL from ..sql.selectable import SelectState from ..util import EMPTY_DICT if TYPE_CHECKING: from ._typing import _IdentityKeyType from .base import LoaderCallableStatus from .interfaces import ORMOption from .mapper import Mapper from .query import Query from .session import Session from .state import InstanceState from ..engine.cursor import CursorResult from ..engine.interfaces import _ExecuteOptions from ..engine.result import Result from ..sql import Select _T = TypeVar("_T", bound=Any) _O = TypeVar("_O", bound=object) _new_runid = util.counter() _PopulatorDict = Dict[str, List[Tuple[str, Any]]] def instances(cursor: CursorResult[Any], context: QueryContext) -> Result[Any]: """Return a :class:`.Result` given an ORM query context. :param cursor: a :class:`.CursorResult`, generated by a statement which came from :class:`.ORMCompileState` :param context: a :class:`.QueryContext` object :return: a :class:`.Result` object representing ORM results .. versionchanged:: 1.4 The instances() function now uses :class:`.Result` objects and has an all new interface. """ context.runid = _new_runid() if context.top_level_context: is_top_level = False context.post_load_paths = context.top_level_context.post_load_paths else: is_top_level = True context.post_load_paths = {} compile_state = context.compile_state filtered = compile_state._has_mapper_entities single_entity = ( not context.load_options._only_return_tuples and len(compile_state._entities) == 1 and compile_state._entities[0].supports_single_entity ) try: (process, labels, extra) = list( zip( *[ query_entity.row_processor(context, cursor) for query_entity in context.compile_state._entities ] ) ) if context.yield_per and ( context.loaders_require_buffering or context.loaders_require_uniquing ): raise sa_exc.InvalidRequestError( "Can't use yield_per with eager loaders that require uniquing " "or row buffering, e.g. joinedload() against collections " "or subqueryload(). Consider the selectinload() strategy " "for better flexibility in loading objects." ) except Exception: with util.safe_reraise(): cursor.close() def _no_unique(entry): raise sa_exc.InvalidRequestError( "Can't use the ORM yield_per feature in conjunction with unique()" ) def _not_hashable(datatype, *, legacy=False, uncertain=False): if not legacy: def go(obj): if uncertain: try: return hash(obj) except: pass raise sa_exc.InvalidRequestError( "Can't apply uniqueness to row tuple containing value of " f"""type {datatype!r}; { 'the values returned appear to be' if uncertain else 'this datatype produces' } non-hashable values""" ) return go elif not uncertain: return id else: _use_id = False def go(obj): nonlocal _use_id if not _use_id: try: return hash(obj) except: pass # in #10459, we considered using a warning here, however # as legacy query uses result.unique() in all cases, this # would lead to too many warning cases. _use_id = True return id(obj) return go unique_filters = [ ( _no_unique if context.yield_per else ( _not_hashable( ent.column.type, # type: ignore legacy=context.load_options._legacy_uniquing, uncertain=ent._null_column_type, ) if ( not ent.use_id_for_hash and (ent._non_hashable_value or ent._null_column_type) ) else id if ent.use_id_for_hash else None ) ) for ent in context.compile_state._entities ] row_metadata = SimpleResultMetaData( labels, extra, _unique_filters=unique_filters ) def chunks(size): # type: ignore while True: yield_per = size context.partials = {} if yield_per: fetch = cursor.fetchmany(yield_per) if not fetch: break else: fetch = cursor._raw_all_rows() if single_entity: proc = process[0] rows = [proc(row) for row in fetch] else: rows = [ tuple([proc(row) for proc in process]) for row in fetch ] # if we are the originating load from a query, meaning we # aren't being called as a result of a nested "post load", # iterate through all the collected post loaders and fire them # off. Previously this used to work recursively, however that # prevented deeply nested structures from being loadable if is_top_level: if yield_per: # if using yield per, memoize the state of the # collection so that it can be restored top_level_post_loads = list( context.post_load_paths.items() ) while context.post_load_paths: post_loads = list(context.post_load_paths.items()) context.post_load_paths.clear() for path, post_load in post_loads: post_load.invoke(context, path) if yield_per: context.post_load_paths.clear() context.post_load_paths.update(top_level_post_loads) yield rows if not yield_per: break if context.execution_options.get("prebuffer_rows", False): # this is a bit of a hack at the moment. # I would rather have some option in the result to pre-buffer # internally. _prebuffered = list(chunks(None)) def chunks(size): return iter(_prebuffered) result = ChunkedIteratorResult( row_metadata, chunks, source_supports_scalars=single_entity, raw=cursor, dynamic_yield_per=cursor.context._is_server_side, ) # filtered and single_entity are used to indicate to legacy Query that the # query has ORM entities, so legacy deduping and scalars should be called # on the result. result._attributes = result._attributes.union( dict(filtered=filtered, is_single_entity=single_entity) ) # multi_row_eager_loaders OTOH is specific to joinedload. if context.compile_state.multi_row_eager_loaders: def require_unique(obj): raise sa_exc.InvalidRequestError( "The unique() method must be invoked on this Result, " "as it contains results that include joined eager loads " "against collections" ) result._unique_filter_state = (None, require_unique) if context.yield_per: result.yield_per(context.yield_per) return result @util.preload_module("sqlalchemy.orm.context") def merge_frozen_result(session, statement, frozen_result, load=True): """Merge a :class:`_engine.FrozenResult` back into a :class:`_orm.Session`, returning a new :class:`_engine.Result` object with :term:`persistent` objects. See the section :ref:`do_orm_execute_re_executing` for an example. .. seealso:: :ref:`do_orm_execute_re_executing` :meth:`_engine.Result.freeze` :class:`_engine.FrozenResult` """ querycontext = util.preloaded.orm_context if load: # flush current contents if we expect to load data session._autoflush() ctx = querycontext.ORMSelectCompileState._create_entities_collection( statement, legacy=False ) autoflush = session.autoflush try: session.autoflush = False mapped_entities = [ i for i, e in enumerate(ctx._entities) if isinstance(e, querycontext._MapperEntity) ] keys = [ent._label_name for ent in ctx._entities] keyed_tuple = result_tuple( keys, [ent._extra_entities for ent in ctx._entities] ) result = [] for newrow in frozen_result.rewrite_rows(): for i in mapped_entities: if newrow[i] is not None: newrow[i] = session._merge( attributes.instance_state(newrow[i]), attributes.instance_dict(newrow[i]), load=load, _recursive={}, _resolve_conflict_map={}, ) result.append(keyed_tuple(newrow)) return frozen_result.with_new_rows(result) finally: session.autoflush = autoflush @util.became_legacy_20( ":func:`_orm.merge_result`", alternative="The function as well as the method on :class:`_orm.Query` " "is superseded by the :func:`_orm.merge_frozen_result` function.", ) @util.preload_module("sqlalchemy.orm.context") def merge_result( query: Query[Any], iterator: Union[FrozenResult, Iterable[Sequence[Any]], Iterable[object]], load: bool = True, ) -> Union[FrozenResult, Iterable[Any]]: """Merge a result into the given :class:`.Query` object's Session. See :meth:`_orm.Query.merge_result` for top-level documentation on this function. """ querycontext = util.preloaded.orm_context session = query.session if load: # flush current contents if we expect to load data session._autoflush() # TODO: need test coverage and documentation for the FrozenResult # use case. if isinstance(iterator, FrozenResult): frozen_result = iterator iterator = iter(frozen_result.data) else: frozen_result = None ctx = querycontext.ORMSelectCompileState._create_entities_collection( query, legacy=True ) autoflush = session.autoflush try: session.autoflush = False single_entity = not frozen_result and len(ctx._entities) == 1 if single_entity: if isinstance(ctx._entities[0], querycontext._MapperEntity): result = [ session._merge( attributes.instance_state(instance), attributes.instance_dict(instance), load=load, _recursive={}, _resolve_conflict_map={}, ) for instance in iterator ] else: result = list(iterator) else: mapped_entities = [ i for i, e in enumerate(ctx._entities) if isinstance(e, querycontext._MapperEntity) ] result = [] keys = [ent._label_name for ent in ctx._entities] keyed_tuple = result_tuple( keys, [ent._extra_entities for ent in ctx._entities] ) for row in iterator: newrow = list(row) for i in mapped_entities: if newrow[i] is not None: newrow[i] = session._merge( attributes.instance_state(newrow[i]), attributes.instance_dict(newrow[i]), load=load, _recursive={}, _resolve_conflict_map={}, ) result.append(keyed_tuple(newrow)) if frozen_result: return frozen_result.with_new_rows(result) else: return iter(result) finally: session.autoflush = autoflush def get_from_identity( session: Session, mapper: Mapper[_O], key: _IdentityKeyType[_O], passive: PassiveFlag, ) -> Union[LoaderCallableStatus, Optional[_O]]: """Look up the given key in the given session's identity map, check the object for expired state if found. """ instance = session.identity_map.get(key) if instance is not None: state = attributes.instance_state(instance) if mapper.inherits and not state.mapper.isa(mapper): return attributes.PASSIVE_CLASS_MISMATCH # expired - ensure it still exists if state.expired: if not passive & attributes.SQL_OK: # TODO: no coverage here return attributes.PASSIVE_NO_RESULT elif not passive & attributes.RELATED_OBJECT_OK: # this mode is used within a flush and the instance's # expired state will be checked soon enough, if necessary. # also used by immediateloader for a mutually-dependent # o2m->m2m load, :ticket:`6301` return instance try: state._load_expired(state, passive) except orm_exc.ObjectDeletedError: session._remove_newly_deleted([state]) return None return instance else: return None def load_on_ident( session: Session, statement: Union[Select, FromStatement], key: Optional[_IdentityKeyType], *, load_options: Optional[Sequence[ORMOption]] = None, refresh_state: Optional[InstanceState[Any]] = None, with_for_update: Optional[ForUpdateArg] = None, only_load_props: Optional[Iterable[str]] = None, no_autoflush: bool = False, bind_arguments: Mapping[str, Any] = util.EMPTY_DICT, execution_options: _ExecuteOptions = util.EMPTY_DICT, require_pk_cols: bool = False, is_user_refresh: bool = False, ): """Load the given identity key from the database.""" if key is not None: ident = key[1] identity_token = key[2] else: ident = identity_token = None return load_on_pk_identity( session, statement, ident, load_options=load_options, refresh_state=refresh_state, with_for_update=with_for_update, only_load_props=only_load_props, identity_token=identity_token, no_autoflush=no_autoflush, bind_arguments=bind_arguments, execution_options=execution_options, require_pk_cols=require_pk_cols, is_user_refresh=is_user_refresh, ) def load_on_pk_identity( session: Session, statement: Union[Select, FromStatement], primary_key_identity: Optional[Tuple[Any, ...]], *, load_options: Optional[Sequence[ORMOption]] = None, refresh_state: Optional[InstanceState[Any]] = None, with_for_update: Optional[ForUpdateArg] = None, only_load_props: Optional[Iterable[str]] = None, identity_token: Optional[Any] = None, no_autoflush: bool = False, bind_arguments: Mapping[str, Any] = util.EMPTY_DICT, execution_options: _ExecuteOptions = util.EMPTY_DICT, require_pk_cols: bool = False, is_user_refresh: bool = False, ): """Load the given primary key identity from the database.""" query = statement q = query._clone() assert not q._is_lambda_element if load_options is None: load_options = QueryContext.default_load_options if ( statement._compile_options is SelectState.default_select_compile_options ): compile_options = ORMCompileState.default_compile_options else: compile_options = statement._compile_options if primary_key_identity is not None: mapper = query._propagate_attrs["plugin_subject"] (_get_clause, _get_params) = mapper._get_clause # None present in ident - turn those comparisons # into "IS NULL" if None in primary_key_identity: nones = { _get_params[col].key for col, value in zip(mapper.primary_key, primary_key_identity) if value is None } _get_clause = sql_util.adapt_criterion_to_null(_get_clause, nones) if len(nones) == len(primary_key_identity): util.warn( "fully NULL primary key identity cannot load any " "object. This condition may raise an error in a future " "release." ) q._where_criteria = ( sql_util._deep_annotate(_get_clause, {"_orm_adapt": True}), ) params = { _get_params[primary_key].key: id_val for id_val, primary_key in zip( primary_key_identity, mapper.primary_key ) } else: params = None if with_for_update is not None: version_check = True q._for_update_arg = with_for_update elif query._for_update_arg is not None: version_check = True q._for_update_arg = query._for_update_arg else: version_check = False if require_pk_cols and only_load_props: if not refresh_state: raise sa_exc.ArgumentError( "refresh_state is required when require_pk_cols is present" ) refresh_state_prokeys = refresh_state.mapper._primary_key_propkeys has_changes = { key for key in refresh_state_prokeys.difference(only_load_props) if refresh_state.attrs[key].history.has_changes() } if has_changes: # raise if pending pk changes are present. # technically, this could be limited to the case where we have # relationships in the only_load_props collection to be refreshed # also (and only ones that have a secondary eager loader, at that). # however, the error is in place across the board so that behavior # here is easier to predict. The use case it prevents is one # of mutating PK attrs, leaving them unflushed, # calling session.refresh(), and expecting those attrs to remain # still unflushed. It seems likely someone doing all those # things would be better off having the PK attributes flushed # to the database before tinkering like that (session.refresh() is # tinkering). raise sa_exc.InvalidRequestError( f"Please flush pending primary key changes on " "attributes " f"{has_changes} for mapper {refresh_state.mapper} before " "proceeding with a refresh" ) # overall, the ORM has no internal flow right now for "dont load the # primary row of an object at all, but fire off # selectinload/subqueryload/immediateload for some relationships". # It would probably be a pretty big effort to add such a flow. So # here, the case for #8703 is introduced; user asks to refresh some # relationship attributes only which are # selectinload/subqueryload/immediateload/ etc. (not joinedload). # ORM complains there's no columns in the primary row to load. # So here, we just add the PK cols if that # case is detected, so that there is a SELECT emitted for the primary # row. # # Let's just state right up front, for this one little case, # the ORM here is adding a whole extra SELECT just to satisfy # limitations in the internal flow. This is really not a thing # SQLAlchemy finds itself doing like, ever, obviously, we are # constantly working to *remove* SELECTs we don't need. We # rationalize this for now based on 1. session.refresh() is not # commonly used 2. session.refresh() with only relationship attrs is # even less commonly used 3. the SELECT in question is very low # latency. # # to add the flow to not include the SELECT, the quickest way # might be to just manufacture a single-row result set to send off to # instances(), but we'd have to weave that into context.py and all # that. For 2.0.0, we have enough big changes to navigate for now. # mp = refresh_state.mapper._props for p in only_load_props: if mp[p]._is_relationship: only_load_props = refresh_state_prokeys.union(only_load_props) break if refresh_state and refresh_state.load_options: compile_options += {"_current_path": refresh_state.load_path.parent} q = q.options(*refresh_state.load_options) new_compile_options, load_options = _set_get_options( compile_options, load_options, version_check=version_check, only_load_props=only_load_props, refresh_state=refresh_state, identity_token=identity_token, is_user_refresh=is_user_refresh, ) q._compile_options = new_compile_options q._order_by = None if no_autoflush: load_options += {"_autoflush": False} execution_options = util.EMPTY_DICT.merge_with( execution_options, {"_sa_orm_load_options": load_options} ) result = ( session.execute( q, params=params, execution_options=execution_options, bind_arguments=bind_arguments, ) .unique() .scalars() ) try: return result.one() except orm_exc.NoResultFound: return None def _set_get_options( compile_opt, load_opt, populate_existing=None, version_check=None, only_load_props=None, refresh_state=None, identity_token=None, is_user_refresh=None, ): compile_options = {} load_options = {} if version_check: load_options["_version_check"] = version_check if populate_existing: load_options["_populate_existing"] = populate_existing if refresh_state: load_options["_refresh_state"] = refresh_state compile_options["_for_refresh_state"] = True if only_load_props: compile_options["_only_load_props"] = frozenset(only_load_props) if identity_token: load_options["_identity_token"] = identity_token if is_user_refresh: load_options["_is_user_refresh"] = is_user_refresh if load_options: load_opt += load_options if compile_options: compile_opt += compile_options return compile_opt, load_opt def _setup_entity_query( compile_state, mapper, query_entity, path, adapter, column_collection, with_polymorphic=None, only_load_props=None, polymorphic_discriminator=None, **kw, ): if with_polymorphic: poly_properties = mapper._iterate_polymorphic_properties( with_polymorphic ) else: poly_properties = mapper._polymorphic_properties quick_populators = {} path.set(compile_state.attributes, "memoized_setups", quick_populators) # for the lead entities in the path, e.g. not eager loads, and # assuming a user-passed aliased class, e.g. not a from_self() or any # implicit aliasing, don't add columns to the SELECT that aren't # in the thing that's aliased. check_for_adapt = adapter and len(path) == 1 and path[-1].is_aliased_class for value in poly_properties: if only_load_props and value.key not in only_load_props: continue value.setup( compile_state, query_entity, path, adapter, only_load_props=only_load_props, column_collection=column_collection, memoized_populators=quick_populators, check_for_adapt=check_for_adapt, **kw, ) if ( polymorphic_discriminator is not None and polymorphic_discriminator is not mapper.polymorphic_on ): if adapter: pd = adapter.columns[polymorphic_discriminator] else: pd = polymorphic_discriminator column_collection.append(pd) def _warn_for_runid_changed(state): util.warn( "Loading context for %s has changed within a load/refresh " "handler, suggesting a row refresh operation took place. If this " "event handler is expected to be " "emitting row refresh operations within an existing load or refresh " "operation, set restore_load_context=True when establishing the " "listener to ensure the context remains unchanged when the event " "handler completes." % (state_str(state),) ) def _instance_processor( query_entity, mapper, context, result, path, adapter, only_load_props=None, refresh_state=None, polymorphic_discriminator=None, _polymorphic_from=None, ): """Produce a mapper level row processor callable which processes rows into mapped instances.""" # note that this method, most of which exists in a closure # called _instance(), resists being broken out, as # attempts to do so tend to add significant function # call overhead. _instance() is the most # performance-critical section in the whole ORM. identity_class = mapper._identity_class compile_state = context.compile_state # look for "row getter" functions that have been assigned along # with the compile state that were cached from a previous load. # these are operator.itemgetter() objects that each will extract a # particular column from each row. getter_key = ("getters", mapper) getters = path.get(compile_state.attributes, getter_key, None) if getters is None: # no getters, so go through a list of attributes we are loading for, # and the ones that are column based will have already put information # for us in another collection "memoized_setups", which represents the # output of the LoaderStrategy.setup_query() method. We can just as # easily call LoaderStrategy.create_row_processor for each, but by # getting it all at once from setup_query we save another method call # per attribute. props = mapper._prop_set if only_load_props is not None: props = props.intersection( mapper._props[k] for k in only_load_props ) quick_populators = path.get( context.attributes, "memoized_setups", EMPTY_DICT ) todo = [] cached_populators = { "new": [], "quick": [], "deferred": [], "expire": [], "existing": [], "eager": [], } if refresh_state is None: # we can also get the "primary key" tuple getter function pk_cols = mapper.primary_key if adapter: pk_cols = [adapter.columns[c] for c in pk_cols] primary_key_getter = result._tuple_getter(pk_cols) else: primary_key_getter = None getters = { "cached_populators": cached_populators, "todo": todo, "primary_key_getter": primary_key_getter, } for prop in props: if prop in quick_populators: # this is an inlined path just for column-based attributes. col = quick_populators[prop] if col is _DEFER_FOR_STATE: cached_populators["new"].append( (prop.key, prop._deferred_column_loader) ) elif col is _SET_DEFERRED_EXPIRED: # note that in this path, we are no longer # searching in the result to see if the column might # be present in some unexpected way. cached_populators["expire"].append((prop.key, False)) elif col is _RAISE_FOR_STATE: cached_populators["new"].append( (prop.key, prop._raise_column_loader) ) else: getter = None if adapter: # this logic had been removed for all 1.4 releases # up until 1.4.18; the adapter here is particularly # the compound eager adapter which isn't accommodated # in the quick_populators right now. The "fallback" # logic below instead took over in many more cases # until issue #6596 was identified. # note there is still an issue where this codepath # produces no "getter" for cases where a joined-inh # mapping includes a labeled column property, meaning # KeyError is caught internally and we fall back to # _getter(col), which works anyway. The adapter # here for joined inh without any aliasing might not # be useful. Tests which see this include # test.orm.inheritance.test_basic -> # EagerTargetingTest.test_adapt_stringency # OptimizedLoadTest.test_column_expression_joined # PolymorphicOnNotLocalTest.test_polymorphic_on_column_prop # noqa: E501 # adapted_col = adapter.columns[col] if adapted_col is not None: getter = result._getter(adapted_col, False) if not getter: getter = result._getter(col, False) if getter: cached_populators["quick"].append((prop.key, getter)) else: # fall back to the ColumnProperty itself, which # will iterate through all of its columns # to see if one fits prop.create_row_processor( context, query_entity, path, mapper, result, adapter, cached_populators, ) else: # loader strategies like subqueryload, selectinload, # joinedload, basically relationships, these need to interact # with the context each time to work correctly. todo.append(prop) path.set(compile_state.attributes, getter_key, getters) cached_populators = getters["cached_populators"] populators = {key: list(value) for key, value in cached_populators.items()} for prop in getters["todo"]: prop.create_row_processor( context, query_entity, path, mapper, result, adapter, populators ) propagated_loader_options = context.propagated_loader_options load_path = ( context.compile_state.current_path + path if context.compile_state.current_path.path else path ) session_identity_map = context.session.identity_map populate_existing = context.populate_existing or mapper.always_refresh load_evt = bool(mapper.class_manager.dispatch.load) refresh_evt = bool(mapper.class_manager.dispatch.refresh) persistent_evt = bool(context.session.dispatch.loaded_as_persistent) if persistent_evt: loaded_as_persistent = context.session.dispatch.loaded_as_persistent instance_state = attributes.instance_state instance_dict = attributes.instance_dict session_id = context.session.hash_key runid = context.runid identity_token = context.identity_token version_check = context.version_check if version_check: version_id_col = mapper.version_id_col if version_id_col is not None: if adapter: version_id_col = adapter.columns[version_id_col] version_id_getter = result._getter(version_id_col) else: version_id_getter = None if not refresh_state and _polymorphic_from is not None: key = ("loader", path.path) if key in context.attributes and context.attributes[key].strategy == ( ("selectinload_polymorphic", True), ): option_entities = context.attributes[key].local_opts["entities"] else: option_entities = None selectin_load_via = mapper._should_selectin_load( option_entities, _polymorphic_from, ) if selectin_load_via and selectin_load_via is not _polymorphic_from: # only_load_props goes w/ refresh_state only, and in a refresh # we are a single row query for the exact entity; polymorphic # loading does not apply assert only_load_props is None if selectin_load_via.is_mapper: _load_supers = [] _endmost_mapper = selectin_load_via while ( _endmost_mapper and _endmost_mapper is not _polymorphic_from ): _load_supers.append(_endmost_mapper) _endmost_mapper = _endmost_mapper.inherits else: _load_supers = [selectin_load_via] for _selectinload_entity in _load_supers: if PostLoad.path_exists( context, load_path, _selectinload_entity ): continue callable_ = _load_subclass_via_in( context, path, _selectinload_entity, _polymorphic_from, option_entities, ) PostLoad.callable_for_path( context, load_path, _selectinload_entity.mapper, _selectinload_entity, callable_, _selectinload_entity, ) post_load = PostLoad.for_context(context, load_path, only_load_props) if refresh_state: refresh_identity_key = refresh_state.key if refresh_identity_key is None: # super-rare condition; a refresh is being called # on a non-instance-key instance; this is meant to only # occur within a flush() refresh_identity_key = mapper._identity_key_from_state( refresh_state ) else: refresh_identity_key = None primary_key_getter = getters["primary_key_getter"] if mapper.allow_partial_pks: is_not_primary_key = _none_set.issuperset else: is_not_primary_key = _none_set.intersection def _instance(row): # determine the state that we'll be populating if refresh_identity_key: # fixed state that we're refreshing state = refresh_state instance = state.obj() dict_ = instance_dict(instance) isnew = state.runid != runid currentload = True loaded_instance = False else: # look at the row, see if that identity is in the # session, or we have to create a new one identitykey = ( identity_class, primary_key_getter(row), identity_token, ) instance = session_identity_map.get(identitykey) if instance is not None: # existing instance state = instance_state(instance) dict_ = instance_dict(instance) isnew = state.runid != runid currentload = not isnew loaded_instance = False if version_check and version_id_getter and not currentload: _validate_version_id( mapper, state, dict_, row, version_id_getter ) else: # create a new instance # check for non-NULL values in the primary key columns, # else no entity is returned for the row if is_not_primary_key(identitykey[1]): return None isnew = True currentload = True loaded_instance = True instance = mapper.class_manager.new_instance() dict_ = instance_dict(instance) state = instance_state(instance) state.key = identitykey state.identity_token = identity_token # attach instance to session. state.session_id = session_id session_identity_map._add_unpresent(state, identitykey) effective_populate_existing = populate_existing if refresh_state is state: effective_populate_existing = True # populate. this looks at whether this state is new # for this load or was existing, and whether or not this # row is the first row with this identity. if currentload or effective_populate_existing: # full population routines. Objects here are either # just created, or we are doing a populate_existing # be conservative about setting load_path when populate_existing # is in effect; want to maintain options from the original # load. see test_expire->test_refresh_maintains_deferred_options if isnew and ( propagated_loader_options or not effective_populate_existing ): state.load_options = propagated_loader_options state.load_path = load_path _populate_full( context, row, state, dict_, isnew, load_path, loaded_instance, effective_populate_existing, populators, ) if isnew: # state.runid should be equal to context.runid / runid # here, however for event checks we are being more conservative # and checking against existing run id # assert state.runid == runid existing_runid = state.runid if loaded_instance: if load_evt: state.manager.dispatch.load(state, context) if state.runid != existing_runid: _warn_for_runid_changed(state) if persistent_evt: loaded_as_persistent(context.session, state) if state.runid != existing_runid: _warn_for_runid_changed(state) elif refresh_evt: state.manager.dispatch.refresh( state, context, only_load_props ) if state.runid != runid: _warn_for_runid_changed(state) if effective_populate_existing or state.modified: if refresh_state and only_load_props: state._commit(dict_, only_load_props) else: state._commit_all(dict_, session_identity_map) if post_load: post_load.add_state(state, True) else: # partial population routines, for objects that were already # in the Session, but a row matches them; apply eager loaders # on existing objects, etc. unloaded = state.unloaded isnew = state not in context.partials if not isnew or unloaded or populators["eager"]: # state is having a partial set of its attributes # refreshed. Populate those attributes, # and add to the "context.partials" collection. to_load = _populate_partial( context, row, state, dict_, isnew, load_path, unloaded, populators, ) if isnew: if refresh_evt: existing_runid = state.runid state.manager.dispatch.refresh(state, context, to_load) if state.runid != existing_runid: _warn_for_runid_changed(state) state._commit(dict_, to_load) if post_load and context.invoke_all_eagers: post_load.add_state(state, False) return instance if mapper.polymorphic_map and not _polymorphic_from and not refresh_state: # if we are doing polymorphic, dispatch to a different _instance() # method specific to the subclass mapper def ensure_no_pk(row): identitykey = ( identity_class, primary_key_getter(row), identity_token, ) if not is_not_primary_key(identitykey[1]): return identitykey else: return None _instance = _decorate_polymorphic_switch( _instance, context, query_entity, mapper, result, path, polymorphic_discriminator, adapter, ensure_no_pk, ) return _instance def _load_subclass_via_in( context, path, entity, polymorphic_from, option_entities ): mapper = entity.mapper # TODO: polymorphic_from seems to be a Mapper in all cases. # this is likely not needed, but as we dont have typing in loading.py # yet, err on the safe side polymorphic_from_mapper = polymorphic_from.mapper not_against_basemost = polymorphic_from_mapper.inherits is not None zero_idx = len(mapper.base_mapper.primary_key) == 1 if entity.is_aliased_class or not_against_basemost: q, enable_opt, disable_opt = mapper._subclass_load_via_in( entity, polymorphic_from ) else: q, enable_opt, disable_opt = mapper._subclass_load_via_in_mapper def do_load(context, path, states, load_only, effective_entity): if not option_entities: # filter out states for those that would have selectinloaded # from another loader # TODO: we are currently ignoring the case where the # "selectin_polymorphic" option is used, as this is much more # complex / specific / very uncommon API use states = [ (s, v) for s, v in states if s.mapper._would_selectin_load_only_from_given_mapper(mapper) ] if not states: return orig_query = context.query if path.parent: enable_opt_lcl = enable_opt._prepend_path(path) disable_opt_lcl = disable_opt._prepend_path(path) else: enable_opt_lcl = enable_opt disable_opt_lcl = disable_opt options = ( (enable_opt_lcl,) + orig_query._with_options + (disable_opt_lcl,) ) q2 = q.options(*options) q2._compile_options = context.compile_state.default_compile_options q2._compile_options += {"_current_path": path.parent} if context.populate_existing: q2 = q2.execution_options(populate_existing=True) context.session.execute( q2, dict( primary_keys=[ state.key[1][0] if zero_idx else state.key[1] for state, load_attrs in states ] ), ).unique().scalars().all() return do_load def _populate_full( context, row, state, dict_, isnew, load_path, loaded_instance, populate_existing, populators, ): if isnew: # first time we are seeing a row with this identity. state.runid = context.runid for key, getter in populators["quick"]: dict_[key] = getter(row) if populate_existing: for key, set_callable in populators["expire"]: dict_.pop(key, None) if set_callable: state.expired_attributes.add(key) else: for key, set_callable in populators["expire"]: if set_callable: state.expired_attributes.add(key) for key, populator in populators["new"]: populator(state, dict_, row) elif load_path != state.load_path: # new load path, e.g. object is present in more than one # column position in a series of rows state.load_path = load_path # if we have data, and the data isn't in the dict, OK, let's put # it in. for key, getter in populators["quick"]: if key not in dict_: dict_[key] = getter(row) # otherwise treat like an "already seen" row for key, populator in populators["existing"]: populator(state, dict_, row) # TODO: allow "existing" populator to know this is # a new path for the state: # populator(state, dict_, row, new_path=True) else: # have already seen rows with this identity in this same path. for key, populator in populators["existing"]: populator(state, dict_, row) # TODO: same path # populator(state, dict_, row, new_path=False) def _populate_partial( context, row, state, dict_, isnew, load_path, unloaded, populators ): if not isnew: if unloaded: # extra pass, see #8166 for key, getter in populators["quick"]: if key in unloaded: dict_[key] = getter(row) to_load = context.partials[state] for key, populator in populators["existing"]: if key in to_load: populator(state, dict_, row) else: to_load = unloaded context.partials[state] = to_load for key, getter in populators["quick"]: if key in to_load: dict_[key] = getter(row) for key, set_callable in populators["expire"]: if key in to_load: dict_.pop(key, None) if set_callable: state.expired_attributes.add(key) for key, populator in populators["new"]: if key in to_load: populator(state, dict_, row) for key, populator in populators["eager"]: if key not in unloaded: populator(state, dict_, row) return to_load def _validate_version_id(mapper, state, dict_, row, getter): if mapper._get_state_attr_by_column( state, dict_, mapper.version_id_col ) != getter(row): raise orm_exc.StaleDataError( "Instance '%s' has version id '%s' which " "does not match database-loaded version id '%s'." % ( state_str(state), mapper._get_state_attr_by_column( state, dict_, mapper.version_id_col ), getter(row), ) ) def _decorate_polymorphic_switch( instance_fn, context, query_entity, mapper, result, path, polymorphic_discriminator, adapter, ensure_no_pk, ): if polymorphic_discriminator is not None: polymorphic_on = polymorphic_discriminator else: polymorphic_on = mapper.polymorphic_on if polymorphic_on is None: return instance_fn if adapter: polymorphic_on = adapter.columns[polymorphic_on] def configure_subclass_mapper(discriminator): try: sub_mapper = mapper.polymorphic_map[discriminator] except KeyError: raise AssertionError( "No such polymorphic_identity %r is defined" % discriminator ) else: if sub_mapper is mapper: return None elif not sub_mapper.isa(mapper): return False return _instance_processor( query_entity, sub_mapper, context, result, path, adapter, _polymorphic_from=mapper, ) polymorphic_instances = util.PopulateDict(configure_subclass_mapper) getter = result._getter(polymorphic_on) def polymorphic_instance(row): discriminator = getter(row) if discriminator is not None: _instance = polymorphic_instances[discriminator] if _instance: return _instance(row) elif _instance is False: identitykey = ensure_no_pk(row) if identitykey: raise sa_exc.InvalidRequestError( "Row with identity key %s can't be loaded into an " "object; the polymorphic discriminator column '%s' " "refers to %s, which is not a sub-mapper of " "the requested %s" % ( identitykey, polymorphic_on, mapper.polymorphic_map[discriminator], mapper, ) ) else: return None else: return instance_fn(row) else: identitykey = ensure_no_pk(row) if identitykey: raise sa_exc.InvalidRequestError( "Row with identity key %s can't be loaded into an " "object; the polymorphic discriminator column '%s' is " "NULL" % (identitykey, polymorphic_on) ) else: return None return polymorphic_instance class PostLoad: """Track loaders and states for "post load" operations.""" __slots__ = "loaders", "states", "load_keys" def __init__(self): self.loaders = {} self.states = util.OrderedDict() self.load_keys = None def add_state(self, state, overwrite): # the states for a polymorphic load here are all shared # within a single PostLoad object among multiple subtypes. # Filtering of callables on a per-subclass basis needs to be done at # the invocation level self.states[state] = overwrite def invoke(self, context, path): if not self.states: return path = path_registry.PathRegistry.coerce(path) for ( effective_context, token, limit_to_mapper, loader, arg, kw, ) in self.loaders.values(): states = [ (state, overwrite) for state, overwrite in self.states.items() if state.manager.mapper.isa(limit_to_mapper) ] if states: loader( effective_context, path, states, self.load_keys, *arg, **kw ) self.states.clear() @classmethod def for_context(cls, context, path, only_load_props): pl = context.post_load_paths.get(path.path) if pl is not None and only_load_props: pl.load_keys = only_load_props return pl @classmethod def path_exists(self, context, path, key): return ( path.path in context.post_load_paths and key in context.post_load_paths[path.path].loaders ) @classmethod def callable_for_path( cls, context, path, limit_to_mapper, token, loader_callable, *arg, **kw ): if path.path in context.post_load_paths: pl = context.post_load_paths[path.path] else: pl = context.post_load_paths[path.path] = PostLoad() pl.loaders[token] = ( context, token, limit_to_mapper, loader_callable, arg, kw, ) def load_scalar_attributes(mapper, state, attribute_names, passive): """initiate a column-based attribute refresh operation.""" # assert mapper is _state_mapper(state) session = state.session if not session: raise orm_exc.DetachedInstanceError( "Instance %s is not bound to a Session; " "attribute refresh operation cannot proceed" % (state_str(state)) ) no_autoflush = bool(passive & attributes.NO_AUTOFLUSH) # in the case of inheritance, particularly concrete and abstract # concrete inheritance, the class manager might have some keys # of attributes on the superclass that we didn't actually map. # These could be mapped as "concrete, don't load" or could be completely # excluded from the mapping and we know nothing about them. Filter them # here to prevent them from coming through. if attribute_names: attribute_names = attribute_names.intersection(mapper.attrs.keys()) if mapper.inherits and not mapper.concrete: # load based on committed attributes in the object, formed into # a truncated SELECT that only includes relevant tables. does not # currently use state.key statement = mapper._optimized_get_statement(state, attribute_names) if statement is not None: # undefer() isn't needed here because statement has the # columns needed already, this implicitly undefers that column stmt = FromStatement(mapper, statement) return load_on_ident( session, stmt, None, only_load_props=attribute_names, refresh_state=state, no_autoflush=no_autoflush, ) # normal load, use state.key as the identity to SELECT has_key = bool(state.key) if has_key: identity_key = state.key else: # this codepath is rare - only valid when inside a flush, and the # object is becoming persistent but hasn't yet been assigned # an identity_key. # check here to ensure we have the attrs we need. pk_attrs = [ mapper._columntoproperty[col].key for col in mapper.primary_key ] if state.expired_attributes.intersection(pk_attrs): raise sa_exc.InvalidRequestError( "Instance %s cannot be refreshed - it's not " " persistent and does not " "contain a full primary key." % state_str(state) ) identity_key = mapper._identity_key_from_state(state) if ( _none_set.issubset(identity_key) and not mapper.allow_partial_pks ) or _none_set.issuperset(identity_key): util.warn_limited( "Instance %s to be refreshed doesn't " "contain a full primary key - can't be refreshed " "(and shouldn't be expired, either).", state_str(state), ) return result = load_on_ident( session, select(mapper).set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL), identity_key, refresh_state=state, only_load_props=attribute_names, no_autoflush=no_autoflush, ) # if instance is pending, a refresh operation # may not complete (even if PK attributes are assigned) if has_key and result is None: raise orm_exc.ObjectDeletedError(state) sqlalchemy/orm/base.py 0000755 00000065555 15125143220 0011005 0 ustar 00 # orm/base.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """Constants and rudimental functions used throughout the ORM. """ from __future__ import annotations from enum import Enum import operator import typing from typing import Any from typing import Callable from typing import Dict from typing import Generic from typing import no_type_check from typing import Optional from typing import overload from typing import Tuple from typing import Type from typing import TYPE_CHECKING from typing import TypeVar from typing import Union from . import exc from ._typing import insp_is_mapper from .. import exc as sa_exc from .. import inspection from .. import util from ..sql import roles from ..sql.elements import SQLColumnExpression from ..sql.elements import SQLCoreOperations from ..util import FastIntFlag from ..util.langhelpers import TypingOnly from ..util.typing import Literal if typing.TYPE_CHECKING: from ._typing import _EntityType from ._typing import _ExternalEntityType from ._typing import _InternalEntityType from .attributes import InstrumentedAttribute from .dynamic import AppenderQuery from .instrumentation import ClassManager from .interfaces import PropComparator from .mapper import Mapper from .state import InstanceState from .util import AliasedClass from .writeonly import WriteOnlyCollection from ..sql._typing import _ColumnExpressionArgument from ..sql._typing import _InfoType from ..sql.elements import ColumnElement from ..sql.operators import OperatorType _T = TypeVar("_T", bound=Any) _T_co = TypeVar("_T_co", bound=Any, covariant=True) _O = TypeVar("_O", bound=object) class LoaderCallableStatus(Enum): PASSIVE_NO_RESULT = 0 """Symbol returned by a loader callable or other attribute/history retrieval operation when a value could not be determined, based on loader callable flags. """ PASSIVE_CLASS_MISMATCH = 1 """Symbol indicating that an object is locally present for a given primary key identity but it is not of the requested class. The return value is therefore None and no SQL should be emitted.""" ATTR_WAS_SET = 2 """Symbol returned by a loader callable to indicate the retrieved value, or values, were assigned to their attributes on the target object. """ ATTR_EMPTY = 3 """Symbol used internally to indicate an attribute had no callable.""" NO_VALUE = 4 """Symbol which may be placed as the 'previous' value of an attribute, indicating no value was loaded for an attribute when it was modified, and flags indicated we were not to load it. """ NEVER_SET = NO_VALUE """ Synonymous with NO_VALUE .. versionchanged:: 1.4 NEVER_SET was merged with NO_VALUE """ ( PASSIVE_NO_RESULT, PASSIVE_CLASS_MISMATCH, ATTR_WAS_SET, ATTR_EMPTY, NO_VALUE, ) = tuple(LoaderCallableStatus) NEVER_SET = NO_VALUE class PassiveFlag(FastIntFlag): """Bitflag interface that passes options onto loader callables""" NO_CHANGE = 0 """No callables or SQL should be emitted on attribute access and no state should change """ CALLABLES_OK = 1 """Loader callables can be fired off if a value is not present. """ SQL_OK = 2 """Loader callables can emit SQL at least on scalar value attributes.""" RELATED_OBJECT_OK = 4 """Callables can use SQL to load related objects as well as scalar value attributes. """ INIT_OK = 8 """Attributes should be initialized with a blank value (None or an empty collection) upon get, if no other value can be obtained. """ NON_PERSISTENT_OK = 16 """Callables can be emitted if the parent is not persistent.""" LOAD_AGAINST_COMMITTED = 32 """Callables should use committed values as primary/foreign keys during a load. """ NO_AUTOFLUSH = 64 """Loader callables should disable autoflush.""" NO_RAISE = 128 """Loader callables should not raise any assertions""" DEFERRED_HISTORY_LOAD = 256 """indicates special load of the previous value of an attribute""" INCLUDE_PENDING_MUTATIONS = 512 # pre-packaged sets of flags used as inputs PASSIVE_OFF = ( RELATED_OBJECT_OK | NON_PERSISTENT_OK | INIT_OK | CALLABLES_OK | SQL_OK ) "Callables can be emitted in all cases." PASSIVE_RETURN_NO_VALUE = PASSIVE_OFF ^ INIT_OK """PASSIVE_OFF ^ INIT_OK""" PASSIVE_NO_INITIALIZE = PASSIVE_RETURN_NO_VALUE ^ CALLABLES_OK "PASSIVE_RETURN_NO_VALUE ^ CALLABLES_OK" PASSIVE_NO_FETCH = PASSIVE_OFF ^ SQL_OK "PASSIVE_OFF ^ SQL_OK" PASSIVE_NO_FETCH_RELATED = PASSIVE_OFF ^ RELATED_OBJECT_OK "PASSIVE_OFF ^ RELATED_OBJECT_OK" PASSIVE_ONLY_PERSISTENT = PASSIVE_OFF ^ NON_PERSISTENT_OK "PASSIVE_OFF ^ NON_PERSISTENT_OK" PASSIVE_MERGE = PASSIVE_OFF | NO_RAISE """PASSIVE_OFF | NO_RAISE Symbol used specifically for session.merge() and similar cases """ ( NO_CHANGE, CALLABLES_OK, SQL_OK, RELATED_OBJECT_OK, INIT_OK, NON_PERSISTENT_OK, LOAD_AGAINST_COMMITTED, NO_AUTOFLUSH, NO_RAISE, DEFERRED_HISTORY_LOAD, INCLUDE_PENDING_MUTATIONS, PASSIVE_OFF, PASSIVE_RETURN_NO_VALUE, PASSIVE_NO_INITIALIZE, PASSIVE_NO_FETCH, PASSIVE_NO_FETCH_RELATED, PASSIVE_ONLY_PERSISTENT, PASSIVE_MERGE, ) = PassiveFlag.__members__.values() DEFAULT_MANAGER_ATTR = "_sa_class_manager" DEFAULT_STATE_ATTR = "_sa_instance_state" class EventConstants(Enum): EXT_CONTINUE = 1 EXT_STOP = 2 EXT_SKIP = 3 NO_KEY = 4 """indicates an :class:`.AttributeEvent` event that did not have any key argument. .. versionadded:: 2.0 """ EXT_CONTINUE, EXT_STOP, EXT_SKIP, NO_KEY = tuple(EventConstants) class RelationshipDirection(Enum): """enumeration which indicates the 'direction' of a :class:`_orm.RelationshipProperty`. :class:`.RelationshipDirection` is accessible from the :attr:`_orm.Relationship.direction` attribute of :class:`_orm.RelationshipProperty`. """ ONETOMANY = 1 """Indicates the one-to-many direction for a :func:`_orm.relationship`. This symbol is typically used by the internals but may be exposed within certain API features. """ MANYTOONE = 2 """Indicates the many-to-one direction for a :func:`_orm.relationship`. This symbol is typically used by the internals but may be exposed within certain API features. """ MANYTOMANY = 3 """Indicates the many-to-many direction for a :func:`_orm.relationship`. This symbol is typically used by the internals but may be exposed within certain API features. """ ONETOMANY, MANYTOONE, MANYTOMANY = tuple(RelationshipDirection) class InspectionAttrExtensionType(Enum): """Symbols indicating the type of extension that a :class:`.InspectionAttr` is part of.""" class NotExtension(InspectionAttrExtensionType): NOT_EXTENSION = "not_extension" """Symbol indicating an :class:`InspectionAttr` that's not part of sqlalchemy.ext. Is assigned to the :attr:`.InspectionAttr.extension_type` attribute. """ _never_set = frozenset([NEVER_SET]) _none_set = frozenset([None, NEVER_SET, PASSIVE_NO_RESULT]) _none_only_set = frozenset([None]) _SET_DEFERRED_EXPIRED = util.symbol("SET_DEFERRED_EXPIRED") _DEFER_FOR_STATE = util.symbol("DEFER_FOR_STATE") _RAISE_FOR_STATE = util.symbol("RAISE_FOR_STATE") _F = TypeVar("_F", bound=Callable[..., Any]) _Self = TypeVar("_Self") def _assertions( *assertions: Any, ) -> Callable[[_F], _F]: @util.decorator def generate(fn: _F, self: _Self, *args: Any, **kw: Any) -> _Self: for assertion in assertions: assertion(self, fn.__name__) fn(self, *args, **kw) return self return generate if TYPE_CHECKING: def manager_of_class(cls: Type[_O]) -> ClassManager[_O]: ... @overload def opt_manager_of_class(cls: AliasedClass[Any]) -> None: ... @overload def opt_manager_of_class( cls: _ExternalEntityType[_O], ) -> Optional[ClassManager[_O]]: ... def opt_manager_of_class( cls: _ExternalEntityType[_O], ) -> Optional[ClassManager[_O]]: ... def instance_state(instance: _O) -> InstanceState[_O]: ... def instance_dict(instance: object) -> Dict[str, Any]: ... else: # these can be replaced by sqlalchemy.ext.instrumentation # if augmented class instrumentation is enabled. def manager_of_class(cls): try: return cls.__dict__[DEFAULT_MANAGER_ATTR] except KeyError as ke: raise exc.UnmappedClassError( cls, f"Can't locate an instrumentation manager for class {cls}" ) from ke def opt_manager_of_class(cls): return cls.__dict__.get(DEFAULT_MANAGER_ATTR) instance_state = operator.attrgetter(DEFAULT_STATE_ATTR) instance_dict = operator.attrgetter("__dict__") def instance_str(instance: object) -> str: """Return a string describing an instance.""" return state_str(instance_state(instance)) def state_str(state: InstanceState[Any]) -> str: """Return a string describing an instance via its InstanceState.""" if state is None: return "None" else: return "<%s at 0x%x>" % (state.class_.__name__, id(state.obj())) def state_class_str(state: InstanceState[Any]) -> str: """Return a string describing an instance's class via its InstanceState. """ if state is None: return "None" else: return "<%s>" % (state.class_.__name__,) def attribute_str(instance: object, attribute: str) -> str: return instance_str(instance) + "." + attribute def state_attribute_str(state: InstanceState[Any], attribute: str) -> str: return state_str(state) + "." + attribute def object_mapper(instance: _T) -> Mapper[_T]: """Given an object, return the primary Mapper associated with the object instance. Raises :class:`sqlalchemy.orm.exc.UnmappedInstanceError` if no mapping is configured. This function is available via the inspection system as:: inspect(instance).mapper Using the inspection system will raise :class:`sqlalchemy.exc.NoInspectionAvailable` if the instance is not part of a mapping. """ return object_state(instance).mapper def object_state(instance: _T) -> InstanceState[_T]: """Given an object, return the :class:`.InstanceState` associated with the object. Raises :class:`sqlalchemy.orm.exc.UnmappedInstanceError` if no mapping is configured. Equivalent functionality is available via the :func:`_sa.inspect` function as:: inspect(instance) Using the inspection system will raise :class:`sqlalchemy.exc.NoInspectionAvailable` if the instance is not part of a mapping. """ state = _inspect_mapped_object(instance) if state is None: raise exc.UnmappedInstanceError(instance) else: return state @inspection._inspects(object) def _inspect_mapped_object(instance: _T) -> Optional[InstanceState[_T]]: try: return instance_state(instance) except (exc.UnmappedClassError,) + exc.NO_STATE: return None def _class_to_mapper( class_or_mapper: Union[Mapper[_T], Type[_T]] ) -> Mapper[_T]: # can't get mypy to see an overload for this insp = inspection.inspect(class_or_mapper, False) if insp is not None: return insp.mapper # type: ignore else: assert isinstance(class_or_mapper, type) raise exc.UnmappedClassError(class_or_mapper) def _mapper_or_none( entity: Union[Type[_T], _InternalEntityType[_T]] ) -> Optional[Mapper[_T]]: """Return the :class:`_orm.Mapper` for the given class or None if the class is not mapped. """ # can't get mypy to see an overload for this insp = inspection.inspect(entity, False) if insp is not None: return insp.mapper # type: ignore else: return None def _is_mapped_class(entity: Any) -> bool: """Return True if the given object is a mapped class, :class:`_orm.Mapper`, or :class:`.AliasedClass`. """ insp = inspection.inspect(entity, False) return ( insp is not None and not insp.is_clause_element and (insp.is_mapper or insp.is_aliased_class) ) def _is_aliased_class(entity: Any) -> bool: insp = inspection.inspect(entity, False) return insp is not None and getattr(insp, "is_aliased_class", False) @no_type_check def _entity_descriptor(entity: _EntityType[Any], key: str) -> Any: """Return a class attribute given an entity and string name. May return :class:`.InstrumentedAttribute` or user-defined attribute. """ insp = inspection.inspect(entity) if insp.is_selectable: description = entity entity = insp.c elif insp.is_aliased_class: entity = insp.entity description = entity elif hasattr(insp, "mapper"): description = entity = insp.mapper.class_ else: description = entity try: return getattr(entity, key) except AttributeError as err: raise sa_exc.InvalidRequestError( "Entity '%s' has no property '%s'" % (description, key) ) from err if TYPE_CHECKING: def _state_mapper(state: InstanceState[_O]) -> Mapper[_O]: ... else: _state_mapper = util.dottedgetter("manager.mapper") def _inspect_mapped_class( class_: Type[_O], configure: bool = False ) -> Optional[Mapper[_O]]: try: class_manager = opt_manager_of_class(class_) if class_manager is None or not class_manager.is_mapped: return None mapper = class_manager.mapper except exc.NO_STATE: return None else: if configure: mapper._check_configure() return mapper def _parse_mapper_argument(arg: Union[Mapper[_O], Type[_O]]) -> Mapper[_O]: insp = inspection.inspect(arg, raiseerr=False) if insp_is_mapper(insp): return insp raise sa_exc.ArgumentError(f"Mapper or mapped class expected, got {arg!r}") def class_mapper(class_: Type[_O], configure: bool = True) -> Mapper[_O]: """Given a class, return the primary :class:`_orm.Mapper` associated with the key. Raises :exc:`.UnmappedClassError` if no mapping is configured on the given class, or :exc:`.ArgumentError` if a non-class object is passed. Equivalent functionality is available via the :func:`_sa.inspect` function as:: inspect(some_mapped_class) Using the inspection system will raise :class:`sqlalchemy.exc.NoInspectionAvailable` if the class is not mapped. """ mapper = _inspect_mapped_class(class_, configure=configure) if mapper is None: if not isinstance(class_, type): raise sa_exc.ArgumentError( "Class object expected, got '%r'." % (class_,) ) raise exc.UnmappedClassError(class_) else: return mapper class InspectionAttr: """A base class applied to all ORM objects and attributes that are related to things that can be returned by the :func:`_sa.inspect` function. The attributes defined here allow the usage of simple boolean checks to test basic facts about the object returned. While the boolean checks here are basically the same as using the Python isinstance() function, the flags here can be used without the need to import all of these classes, and also such that the SQLAlchemy class system can change while leaving the flags here intact for forwards-compatibility. """ __slots__: Tuple[str, ...] = () is_selectable = False """Return True if this object is an instance of :class:`_expression.Selectable`.""" is_aliased_class = False """True if this object is an instance of :class:`.AliasedClass`.""" is_instance = False """True if this object is an instance of :class:`.InstanceState`.""" is_mapper = False """True if this object is an instance of :class:`_orm.Mapper`.""" is_bundle = False """True if this object is an instance of :class:`.Bundle`.""" is_property = False """True if this object is an instance of :class:`.MapperProperty`.""" is_attribute = False """True if this object is a Python :term:`descriptor`. This can refer to one of many types. Usually a :class:`.QueryableAttribute` which handles attributes events on behalf of a :class:`.MapperProperty`. But can also be an extension type such as :class:`.AssociationProxy` or :class:`.hybrid_property`. The :attr:`.InspectionAttr.extension_type` will refer to a constant identifying the specific subtype. .. seealso:: :attr:`_orm.Mapper.all_orm_descriptors` """ _is_internal_proxy = False """True if this object is an internal proxy object. .. versionadded:: 1.2.12 """ is_clause_element = False """True if this object is an instance of :class:`_expression.ClauseElement`.""" extension_type: InspectionAttrExtensionType = NotExtension.NOT_EXTENSION """The extension type, if any. Defaults to :attr:`.interfaces.NotExtension.NOT_EXTENSION` .. seealso:: :class:`.HybridExtensionType` :class:`.AssociationProxyExtensionType` """ class InspectionAttrInfo(InspectionAttr): """Adds the ``.info`` attribute to :class:`.InspectionAttr`. The rationale for :class:`.InspectionAttr` vs. :class:`.InspectionAttrInfo` is that the former is compatible as a mixin for classes that specify ``__slots__``; this is essentially an implementation artifact. """ __slots__ = () @util.ro_memoized_property def info(self) -> _InfoType: """Info dictionary associated with the object, allowing user-defined data to be associated with this :class:`.InspectionAttr`. The dictionary is generated when first accessed. Alternatively, it can be specified as a constructor argument to the :func:`.column_property`, :func:`_orm.relationship`, or :func:`.composite` functions. .. seealso:: :attr:`.QueryableAttribute.info` :attr:`.SchemaItem.info` """ return {} class SQLORMOperations(SQLCoreOperations[_T_co], TypingOnly): __slots__ = () if typing.TYPE_CHECKING: def of_type( self, class_: _EntityType[Any] ) -> PropComparator[_T_co]: ... def and_( self, *criteria: _ColumnExpressionArgument[bool] ) -> PropComparator[bool]: ... def any( # noqa: A001 self, criterion: Optional[_ColumnExpressionArgument[bool]] = None, **kwargs: Any, ) -> ColumnElement[bool]: ... def has( self, criterion: Optional[_ColumnExpressionArgument[bool]] = None, **kwargs: Any, ) -> ColumnElement[bool]: ... class ORMDescriptor(Generic[_T_co], TypingOnly): """Represent any Python descriptor that provides a SQL expression construct at the class level.""" __slots__ = () if typing.TYPE_CHECKING: @overload def __get__( self, instance: Any, owner: Literal[None] ) -> ORMDescriptor[_T_co]: ... @overload def __get__( self, instance: Literal[None], owner: Any ) -> SQLCoreOperations[_T_co]: ... @overload def __get__(self, instance: object, owner: Any) -> _T_co: ... def __get__( self, instance: object, owner: Any ) -> Union[ORMDescriptor[_T_co], SQLCoreOperations[_T_co], _T_co]: ... class _MappedAnnotationBase(Generic[_T_co], TypingOnly): """common class for Mapped and similar ORM container classes. these are classes that can appear on the left side of an ORM declarative mapping, containing a mapped class or in some cases a collection surrounding a mapped class. """ __slots__ = () class SQLORMExpression( SQLORMOperations[_T_co], SQLColumnExpression[_T_co], TypingOnly ): """A type that may be used to indicate any ORM-level attribute or object that acts in place of one, in the context of SQL expression construction. :class:`.SQLORMExpression` extends from the Core :class:`.SQLColumnExpression` to add additional SQL methods that are ORM specific, such as :meth:`.PropComparator.of_type`, and is part of the bases for :class:`.InstrumentedAttribute`. It may be used in :pep:`484` typing to indicate arguments or return values that should behave as ORM-level attribute expressions. .. versionadded:: 2.0.0b4 """ __slots__ = () class Mapped( SQLORMExpression[_T_co], ORMDescriptor[_T_co], _MappedAnnotationBase[_T_co], roles.DDLConstraintColumnRole, ): """Represent an ORM mapped attribute on a mapped class. This class represents the complete descriptor interface for any class attribute that will have been :term:`instrumented` by the ORM :class:`_orm.Mapper` class. Provides appropriate information to type checkers such as pylance and mypy so that ORM-mapped attributes are correctly typed. The most prominent use of :class:`_orm.Mapped` is in the :ref:`Declarative Mapping <orm_explicit_declarative_base>` form of :class:`_orm.Mapper` configuration, where used explicitly it drives the configuration of ORM attributes such as :func:`_orm.mapped_class` and :func:`_orm.relationship`. .. seealso:: :ref:`orm_explicit_declarative_base` :ref:`orm_declarative_table` .. tip:: The :class:`_orm.Mapped` class represents attributes that are handled directly by the :class:`_orm.Mapper` class. It does not include other Python descriptor classes that are provided as extensions, including :ref:`hybrids_toplevel` and the :ref:`associationproxy_toplevel`. While these systems still make use of ORM-specific superclasses and structures, they are not :term:`instrumented` by the :class:`_orm.Mapper` and instead provide their own functionality when they are accessed on a class. .. versionadded:: 1.4 """ __slots__ = () if typing.TYPE_CHECKING: @overload def __get__( self, instance: None, owner: Any ) -> InstrumentedAttribute[_T_co]: ... @overload def __get__(self, instance: object, owner: Any) -> _T_co: ... def __get__( self, instance: Optional[object], owner: Any ) -> Union[InstrumentedAttribute[_T_co], _T_co]: ... @classmethod def _empty_constructor(cls, arg1: Any) -> Mapped[_T_co]: ... def __set__( self, instance: Any, value: Union[SQLCoreOperations[_T_co], _T_co] ) -> None: ... def __delete__(self, instance: Any) -> None: ... class _MappedAttribute(Generic[_T_co], TypingOnly): """Mixin for attributes which should be replaced by mapper-assigned attributes. """ __slots__ = () class _DeclarativeMapped(Mapped[_T_co], _MappedAttribute[_T_co]): """Mixin for :class:`.MapperProperty` subclasses that allows them to be compatible with ORM-annotated declarative mappings. """ __slots__ = () # MappedSQLExpression, Relationship, Composite etc. dont actually do # SQL expression behavior. yet there is code that compares them with # __eq__(), __ne__(), etc. Since #8847 made Mapped even more full # featured including ColumnOperators, we need to have those methods # be no-ops for these objects, so return NotImplemented to fall back # to normal comparison behavior. def operate(self, op: OperatorType, *other: Any, **kwargs: Any) -> Any: return NotImplemented __sa_operate__ = operate def reverse_operate( self, op: OperatorType, other: Any, **kwargs: Any ) -> Any: return NotImplemented class DynamicMapped(_MappedAnnotationBase[_T_co]): """Represent the ORM mapped attribute type for a "dynamic" relationship. The :class:`_orm.DynamicMapped` type annotation may be used in an :ref:`Annotated Declarative Table <orm_declarative_mapped_column>` mapping to indicate that the ``lazy="dynamic"`` loader strategy should be used for a particular :func:`_orm.relationship`. .. legacy:: The "dynamic" lazy loader strategy is the legacy form of what is now the "write_only" strategy described in the section :ref:`write_only_relationship`. E.g.:: class User(Base): __tablename__ = "user" id: Mapped[int] = mapped_column(primary_key=True) addresses: DynamicMapped[Address] = relationship( cascade="all,delete-orphan" ) See the section :ref:`dynamic_relationship` for background. .. versionadded:: 2.0 .. seealso:: :ref:`dynamic_relationship` - complete background :class:`.WriteOnlyMapped` - fully 2.0 style version """ __slots__ = () if TYPE_CHECKING: @overload def __get__( self, instance: None, owner: Any ) -> InstrumentedAttribute[_T_co]: ... @overload def __get__( self, instance: object, owner: Any ) -> AppenderQuery[_T_co]: ... def __get__( self, instance: Optional[object], owner: Any ) -> Union[InstrumentedAttribute[_T_co], AppenderQuery[_T_co]]: ... def __set__( self, instance: Any, value: typing.Collection[_T_co] ) -> None: ... class WriteOnlyMapped(_MappedAnnotationBase[_T_co]): """Represent the ORM mapped attribute type for a "write only" relationship. The :class:`_orm.WriteOnlyMapped` type annotation may be used in an :ref:`Annotated Declarative Table <orm_declarative_mapped_column>` mapping to indicate that the ``lazy="write_only"`` loader strategy should be used for a particular :func:`_orm.relationship`. E.g.:: class User(Base): __tablename__ = "user" id: Mapped[int] = mapped_column(primary_key=True) addresses: WriteOnlyMapped[Address] = relationship( cascade="all,delete-orphan" ) See the section :ref:`write_only_relationship` for background. .. versionadded:: 2.0 .. seealso:: :ref:`write_only_relationship` - complete background :class:`.DynamicMapped` - includes legacy :class:`_orm.Query` support """ __slots__ = () if TYPE_CHECKING: @overload def __get__( self, instance: None, owner: Any ) -> InstrumentedAttribute[_T_co]: ... @overload def __get__( self, instance: object, owner: Any ) -> WriteOnlyCollection[_T_co]: ... def __get__( self, instance: Optional[object], owner: Any ) -> Union[ InstrumentedAttribute[_T_co], WriteOnlyCollection[_T_co] ]: ... def __set__( self, instance: Any, value: typing.Collection[_T_co] ) -> None: ... sqlalchemy/orm/dynamic.py 0000755 00000023130 15125143220 0011476 0 ustar 00 # orm/dynamic.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """Dynamic collection API. Dynamic collections act like Query() objects for read operations and support basic add/delete mutation. .. legacy:: the "dynamic" loader is a legacy feature, superseded by the "write_only" loader. """ from __future__ import annotations from typing import Any from typing import Iterable from typing import Iterator from typing import List from typing import Optional from typing import Tuple from typing import Type from typing import TYPE_CHECKING from typing import TypeVar from typing import Union from . import attributes from . import exc as orm_exc from . import relationships from . import util as orm_util from .base import PassiveFlag from .query import Query from .session import object_session from .writeonly import AbstractCollectionWriter from .writeonly import WriteOnlyAttributeImpl from .writeonly import WriteOnlyHistory from .writeonly import WriteOnlyLoader from .. import util from ..engine import result if TYPE_CHECKING: from . import QueryableAttribute from .mapper import Mapper from .relationships import _RelationshipOrderByArg from .session import Session from .state import InstanceState from .util import AliasedClass from ..event import _Dispatch from ..sql.elements import ColumnElement _T = TypeVar("_T", bound=Any) class DynamicCollectionHistory(WriteOnlyHistory[_T]): def __init__( self, attr: DynamicAttributeImpl, state: InstanceState[_T], passive: PassiveFlag, apply_to: Optional[DynamicCollectionHistory[_T]] = None, ) -> None: if apply_to: coll = AppenderQuery(attr, state).autoflush(False) self.unchanged_items = util.OrderedIdentitySet(coll) self.added_items = apply_to.added_items self.deleted_items = apply_to.deleted_items self._reconcile_collection = True else: self.deleted_items = util.OrderedIdentitySet() self.added_items = util.OrderedIdentitySet() self.unchanged_items = util.OrderedIdentitySet() self._reconcile_collection = False class DynamicAttributeImpl(WriteOnlyAttributeImpl): _supports_dynamic_iteration = True collection_history_cls = DynamicCollectionHistory[Any] query_class: Type[AppenderMixin[Any]] # type: ignore[assignment] def __init__( self, class_: Union[Type[Any], AliasedClass[Any]], key: str, dispatch: _Dispatch[QueryableAttribute[Any]], target_mapper: Mapper[_T], order_by: _RelationshipOrderByArg, query_class: Optional[Type[AppenderMixin[_T]]] = None, **kw: Any, ) -> None: attributes.AttributeImpl.__init__( self, class_, key, None, dispatch, **kw ) self.target_mapper = target_mapper if order_by: self.order_by = tuple(order_by) if not query_class: self.query_class = AppenderQuery elif AppenderMixin in query_class.mro(): self.query_class = query_class else: self.query_class = mixin_user_query(query_class) @relationships.RelationshipProperty.strategy_for(lazy="dynamic") class DynaLoader(WriteOnlyLoader): impl_class = DynamicAttributeImpl class AppenderMixin(AbstractCollectionWriter[_T]): """A mixin that expects to be mixing in a Query class with AbstractAppender. """ query_class: Optional[Type[Query[_T]]] = None _order_by_clauses: Tuple[ColumnElement[Any], ...] def __init__( self, attr: DynamicAttributeImpl, state: InstanceState[_T] ) -> None: Query.__init__( self, # type: ignore[arg-type] attr.target_mapper, None, ) super().__init__(attr, state) @property def session(self) -> Optional[Session]: sess = object_session(self.instance) if sess is not None and sess.autoflush and self.instance in sess: sess.flush() if not orm_util.has_identity(self.instance): return None else: return sess @session.setter def session(self, session: Session) -> None: self.sess = session def _iter(self) -> Union[result.ScalarResult[_T], result.Result[_T]]: sess = self.session if sess is None: state = attributes.instance_state(self.instance) if state.detached: util.warn( "Instance %s is detached, dynamic relationship cannot " "return a correct result. This warning will become " "a DetachedInstanceError in a future release." % (orm_util.state_str(state)) ) return result.IteratorResult( result.SimpleResultMetaData([self.attr.class_.__name__]), iter( self.attr._get_collection_history( attributes.instance_state(self.instance), PassiveFlag.PASSIVE_NO_INITIALIZE, ).added_items ), _source_supports_scalars=True, ).scalars() else: return self._generate(sess)._iter() if TYPE_CHECKING: def __iter__(self) -> Iterator[_T]: ... def __getitem__(self, index: Any) -> Union[_T, List[_T]]: sess = self.session if sess is None: return self.attr._get_collection_history( attributes.instance_state(self.instance), PassiveFlag.PASSIVE_NO_INITIALIZE, ).indexed(index) else: return self._generate(sess).__getitem__(index) # type: ignore[no-any-return] # noqa: E501 def count(self) -> int: sess = self.session if sess is None: return len( self.attr._get_collection_history( attributes.instance_state(self.instance), PassiveFlag.PASSIVE_NO_INITIALIZE, ).added_items ) else: return self._generate(sess).count() def _generate( self, sess: Optional[Session] = None, ) -> Query[_T]: # note we're returning an entirely new Query class instance # here without any assignment capabilities; the class of this # query is determined by the session. instance = self.instance if sess is None: sess = object_session(instance) if sess is None: raise orm_exc.DetachedInstanceError( "Parent instance %s is not bound to a Session, and no " "contextual session is established; lazy load operation " "of attribute '%s' cannot proceed" % (orm_util.instance_str(instance), self.attr.key) ) if self.query_class: query = self.query_class(self.attr.target_mapper, session=sess) else: query = sess.query(self.attr.target_mapper) query._where_criteria = self._where_criteria query._from_obj = self._from_obj query._order_by_clauses = self._order_by_clauses return query def add_all(self, iterator: Iterable[_T]) -> None: """Add an iterable of items to this :class:`_orm.AppenderQuery`. The given items will be persisted to the database in terms of the parent instance's collection on the next flush. This method is provided to assist in delivering forwards-compatibility with the :class:`_orm.WriteOnlyCollection` collection class. .. versionadded:: 2.0 """ self._add_all_impl(iterator) def add(self, item: _T) -> None: """Add an item to this :class:`_orm.AppenderQuery`. The given item will be persisted to the database in terms of the parent instance's collection on the next flush. This method is provided to assist in delivering forwards-compatibility with the :class:`_orm.WriteOnlyCollection` collection class. .. versionadded:: 2.0 """ self._add_all_impl([item]) def extend(self, iterator: Iterable[_T]) -> None: """Add an iterable of items to this :class:`_orm.AppenderQuery`. The given items will be persisted to the database in terms of the parent instance's collection on the next flush. """ self._add_all_impl(iterator) def append(self, item: _T) -> None: """Append an item to this :class:`_orm.AppenderQuery`. The given item will be persisted to the database in terms of the parent instance's collection on the next flush. """ self._add_all_impl([item]) def remove(self, item: _T) -> None: """Remove an item from this :class:`_orm.AppenderQuery`. The given item will be removed from the parent instance's collection on the next flush. """ self._remove_impl(item) class AppenderQuery(AppenderMixin[_T], Query[_T]): # type: ignore[misc] """A dynamic query that supports basic collection storage operations. Methods on :class:`.AppenderQuery` include all methods of :class:`_orm.Query`, plus additional methods used for collection persistence. """ def mixin_user_query(cls: Any) -> type[AppenderMixin[Any]]: """Return a new class with AppenderQuery functionality layered over.""" name = "Appender" + cls.__name__ return type(name, (AppenderMixin, cls), {"query_class": cls}) sqlalchemy/orm/sync.py 0000755 00000013223 15125143220 0011030 0 ustar 00 # orm/sync.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: allow-untyped-defs, allow-untyped-calls """private module containing functions used for copying data between instances based on join conditions. """ from __future__ import annotations from . import exc from . import util as orm_util from .base import PassiveFlag def populate( source, source_mapper, dest, dest_mapper, synchronize_pairs, uowcommit, flag_cascaded_pks, ): source_dict = source.dict dest_dict = dest.dict for l, r in synchronize_pairs: try: # inline of source_mapper._get_state_attr_by_column prop = source_mapper._columntoproperty[l] value = source.manager[prop.key].impl.get( source, source_dict, PassiveFlag.PASSIVE_OFF ) except exc.UnmappedColumnError as err: _raise_col_to_prop(False, source_mapper, l, dest_mapper, r, err) try: # inline of dest_mapper._set_state_attr_by_column prop = dest_mapper._columntoproperty[r] dest.manager[prop.key].impl.set(dest, dest_dict, value, None) except exc.UnmappedColumnError as err: _raise_col_to_prop(True, source_mapper, l, dest_mapper, r, err) # technically the "r.primary_key" check isn't # needed here, but we check for this condition to limit # how often this logic is invoked for memory/performance # reasons, since we only need this info for a primary key # destination. if ( flag_cascaded_pks and l.primary_key and r.primary_key and r.references(l) ): uowcommit.attributes[("pk_cascaded", dest, r)] = True def bulk_populate_inherit_keys(source_dict, source_mapper, synchronize_pairs): # a simplified version of populate() used by bulk insert mode for l, r in synchronize_pairs: try: prop = source_mapper._columntoproperty[l] value = source_dict[prop.key] except exc.UnmappedColumnError as err: _raise_col_to_prop(False, source_mapper, l, source_mapper, r, err) try: prop = source_mapper._columntoproperty[r] source_dict[prop.key] = value except exc.UnmappedColumnError as err: _raise_col_to_prop(True, source_mapper, l, source_mapper, r, err) def clear(dest, dest_mapper, synchronize_pairs): for l, r in synchronize_pairs: if ( r.primary_key and dest_mapper._get_state_attr_by_column(dest, dest.dict, r) not in orm_util._none_set ): raise AssertionError( f"Dependency rule on column '{l}' " "tried to blank-out primary key " f"column '{r}' on instance '{orm_util.state_str(dest)}'" ) try: dest_mapper._set_state_attr_by_column(dest, dest.dict, r, None) except exc.UnmappedColumnError as err: _raise_col_to_prop(True, None, l, dest_mapper, r, err) def update(source, source_mapper, dest, old_prefix, synchronize_pairs): for l, r in synchronize_pairs: try: oldvalue = source_mapper._get_committed_attr_by_column( source.obj(), l ) value = source_mapper._get_state_attr_by_column( source, source.dict, l, passive=PassiveFlag.PASSIVE_OFF ) except exc.UnmappedColumnError as err: _raise_col_to_prop(False, source_mapper, l, None, r, err) dest[r.key] = value dest[old_prefix + r.key] = oldvalue def populate_dict(source, source_mapper, dict_, synchronize_pairs): for l, r in synchronize_pairs: try: value = source_mapper._get_state_attr_by_column( source, source.dict, l, passive=PassiveFlag.PASSIVE_OFF ) except exc.UnmappedColumnError as err: _raise_col_to_prop(False, source_mapper, l, None, r, err) dict_[r.key] = value def source_modified(uowcommit, source, source_mapper, synchronize_pairs): """return true if the source object has changes from an old to a new value on the given synchronize pairs """ for l, r in synchronize_pairs: try: prop = source_mapper._columntoproperty[l] except exc.UnmappedColumnError as err: _raise_col_to_prop(False, source_mapper, l, None, r, err) history = uowcommit.get_attribute_history( source, prop.key, PassiveFlag.PASSIVE_NO_INITIALIZE ) if bool(history.deleted): return True else: return False def _raise_col_to_prop( isdest, source_mapper, source_column, dest_mapper, dest_column, err ): if isdest: raise exc.UnmappedColumnError( "Can't execute sync rule for " "destination column '%s'; mapper '%s' does not map " "this column. Try using an explicit `foreign_keys` " "collection which does not include this column (or use " "a viewonly=True relation)." % (dest_column, dest_mapper) ) from err else: raise exc.UnmappedColumnError( "Can't execute sync rule for " "source column '%s'; mapper '%s' does not map this " "column. Try using an explicit `foreign_keys` " "collection which does not include destination column " "'%s' (or use a viewonly=True relation)." % (source_column, source_mapper, dest_column) ) from err sqlalchemy/orm/strategy_options.py 0000755 00000246036 15125143220 0013503 0 ustar 00 # orm/strategy_options.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: allow-untyped-defs, allow-untyped-calls """ """ from __future__ import annotations import typing from typing import Any from typing import Callable from typing import cast from typing import Dict from typing import Iterable from typing import Optional from typing import overload from typing import Sequence from typing import Tuple from typing import Type from typing import TypeVar from typing import Union from . import util as orm_util from ._typing import insp_is_aliased_class from ._typing import insp_is_attribute from ._typing import insp_is_mapper from ._typing import insp_is_mapper_property from .attributes import QueryableAttribute from .base import InspectionAttr from .interfaces import LoaderOption from .path_registry import _DEFAULT_TOKEN from .path_registry import _StrPathToken from .path_registry import _WILDCARD_TOKEN from .path_registry import AbstractEntityRegistry from .path_registry import path_is_property from .path_registry import PathRegistry from .path_registry import TokenRegistry from .util import _orm_full_deannotate from .util import AliasedInsp from .. import exc as sa_exc from .. import inspect from .. import util from ..sql import and_ from ..sql import cache_key from ..sql import coercions from ..sql import roles from ..sql import traversals from ..sql import visitors from ..sql.base import _generative from ..util.typing import Final from ..util.typing import Literal from ..util.typing import Self _RELATIONSHIP_TOKEN: Final[Literal["relationship"]] = "relationship" _COLUMN_TOKEN: Final[Literal["column"]] = "column" _FN = TypeVar("_FN", bound="Callable[..., Any]") if typing.TYPE_CHECKING: from ._typing import _EntityType from ._typing import _InternalEntityType from .context import _MapperEntity from .context import ORMCompileState from .context import QueryContext from .interfaces import _StrategyKey from .interfaces import MapperProperty from .interfaces import ORMOption from .mapper import Mapper from .path_registry import _PathRepresentation from ..sql._typing import _ColumnExpressionArgument from ..sql._typing import _FromClauseArgument from ..sql.cache_key import _CacheKeyTraversalType from ..sql.cache_key import CacheKey _AttrType = Union[Literal["*"], "QueryableAttribute[Any]"] _WildcardKeyType = Literal["relationship", "column"] _StrategySpec = Dict[str, Any] _OptsType = Dict[str, Any] _AttrGroupType = Tuple[_AttrType, ...] class _AbstractLoad(traversals.GenerativeOnTraversal, LoaderOption): __slots__ = ("propagate_to_loaders",) _is_strategy_option = True propagate_to_loaders: bool def contains_eager( self, attr: _AttrType, alias: Optional[_FromClauseArgument] = None, _is_chain: bool = False, _propagate_to_loaders: bool = False, ) -> Self: r"""Indicate that the given attribute should be eagerly loaded from columns stated manually in the query. This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. The option is used in conjunction with an explicit join that loads the desired rows, i.e.:: sess.query(Order).join(Order.user).options(contains_eager(Order.user)) The above query would join from the ``Order`` entity to its related ``User`` entity, and the returned ``Order`` objects would have the ``Order.user`` attribute pre-populated. It may also be used for customizing the entries in an eagerly loaded collection; queries will normally want to use the :ref:`orm_queryguide_populate_existing` execution option assuming the primary collection of parent objects may already have been loaded:: sess.query(User).join(User.addresses).filter( Address.email_address.like("%@aol.com") ).options(contains_eager(User.addresses)).populate_existing() See the section :ref:`contains_eager` for complete usage details. .. seealso:: :ref:`loading_toplevel` :ref:`contains_eager` """ if alias is not None: if not isinstance(alias, str): coerced_alias = coercions.expect(roles.FromClauseRole, alias) else: util.warn_deprecated( "Passing a string name for the 'alias' argument to " "'contains_eager()` is deprecated, and will not work in a " "future release. Please use a sqlalchemy.alias() or " "sqlalchemy.orm.aliased() construct.", version="1.4", ) coerced_alias = alias elif getattr(attr, "_of_type", None): assert isinstance(attr, QueryableAttribute) ot: Optional[_InternalEntityType[Any]] = inspect(attr._of_type) assert ot is not None coerced_alias = ot.selectable else: coerced_alias = None cloned = self._set_relationship_strategy( attr, {"lazy": "joined"}, propagate_to_loaders=_propagate_to_loaders, opts={"eager_from_alias": coerced_alias}, _reconcile_to_other=True if _is_chain else None, ) return cloned def load_only(self, *attrs: _AttrType, raiseload: bool = False) -> Self: r"""Indicate that for a particular entity, only the given list of column-based attribute names should be loaded; all others will be deferred. This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. Example - given a class ``User``, load only the ``name`` and ``fullname`` attributes:: session.query(User).options(load_only(User.name, User.fullname)) Example - given a relationship ``User.addresses -> Address``, specify subquery loading for the ``User.addresses`` collection, but on each ``Address`` object load only the ``email_address`` attribute:: session.query(User).options( subqueryload(User.addresses).load_only(Address.email_address) ) For a statement that has multiple entities, the lead entity can be specifically referred to using the :class:`_orm.Load` constructor:: stmt = ( select(User, Address) .join(User.addresses) .options( Load(User).load_only(User.name, User.fullname), Load(Address).load_only(Address.email_address), ) ) When used together with the :ref:`populate_existing <orm_queryguide_populate_existing>` execution option only the attributes listed will be refreshed. :param \*attrs: Attributes to be loaded, all others will be deferred. :param raiseload: raise :class:`.InvalidRequestError` rather than lazy loading a value when a deferred attribute is accessed. Used to prevent unwanted SQL from being emitted. .. versionadded:: 2.0 .. seealso:: :ref:`orm_queryguide_column_deferral` - in the :ref:`queryguide_toplevel` :param \*attrs: Attributes to be loaded, all others will be deferred. :param raiseload: raise :class:`.InvalidRequestError` rather than lazy loading a value when a deferred attribute is accessed. Used to prevent unwanted SQL from being emitted. .. versionadded:: 2.0 """ cloned = self._set_column_strategy( attrs, {"deferred": False, "instrument": True}, ) wildcard_strategy = {"deferred": True, "instrument": True} if raiseload: wildcard_strategy["raiseload"] = True cloned = cloned._set_column_strategy( ("*",), wildcard_strategy, ) return cloned def joinedload( self, attr: _AttrType, innerjoin: Optional[bool] = None, ) -> Self: """Indicate that the given attribute should be loaded using joined eager loading. This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. examples:: # joined-load the "orders" collection on "User" select(User).options(joinedload(User.orders)) # joined-load Order.items and then Item.keywords select(Order).options(joinedload(Order.items).joinedload(Item.keywords)) # lazily load Order.items, but when Items are loaded, # joined-load the keywords collection select(Order).options(lazyload(Order.items).joinedload(Item.keywords)) :param innerjoin: if ``True``, indicates that the joined eager load should use an inner join instead of the default of left outer join:: select(Order).options(joinedload(Order.user, innerjoin=True)) In order to chain multiple eager joins together where some may be OUTER and others INNER, right-nested joins are used to link them:: select(A).options( joinedload(A.bs, innerjoin=False).joinedload(B.cs, innerjoin=True) ) The above query, linking A.bs via "outer" join and B.cs via "inner" join would render the joins as "a LEFT OUTER JOIN (b JOIN c)". When using older versions of SQLite (< 3.7.16), this form of JOIN is translated to use full subqueries as this syntax is otherwise not directly supported. The ``innerjoin`` flag can also be stated with the term ``"unnested"``. This indicates that an INNER JOIN should be used, *unless* the join is linked to a LEFT OUTER JOIN to the left, in which case it will render as LEFT OUTER JOIN. For example, supposing ``A.bs`` is an outerjoin:: select(A).options(joinedload(A.bs).joinedload(B.cs, innerjoin="unnested")) The above join will render as "a LEFT OUTER JOIN b LEFT OUTER JOIN c", rather than as "a LEFT OUTER JOIN (b JOIN c)". .. note:: The "unnested" flag does **not** affect the JOIN rendered from a many-to-many association table, e.g. a table configured as :paramref:`_orm.relationship.secondary`, to the target table; for correctness of results, these joins are always INNER and are therefore right-nested if linked to an OUTER join. .. note:: The joins produced by :func:`_orm.joinedload` are **anonymously aliased**. The criteria by which the join proceeds cannot be modified, nor can the ORM-enabled :class:`_sql.Select` or legacy :class:`_query.Query` refer to these joins in any way, including ordering. See :ref:`zen_of_eager_loading` for further detail. To produce a specific SQL JOIN which is explicitly available, use :meth:`_sql.Select.join` and :meth:`_query.Query.join`. To combine explicit JOINs with eager loading of collections, use :func:`_orm.contains_eager`; see :ref:`contains_eager`. .. seealso:: :ref:`loading_toplevel` :ref:`joined_eager_loading` """ # noqa: E501 loader = self._set_relationship_strategy( attr, {"lazy": "joined"}, opts=( {"innerjoin": innerjoin} if innerjoin is not None else util.EMPTY_DICT ), ) return loader def subqueryload(self, attr: _AttrType) -> Self: """Indicate that the given attribute should be loaded using subquery eager loading. This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. examples:: # subquery-load the "orders" collection on "User" select(User).options(subqueryload(User.orders)) # subquery-load Order.items and then Item.keywords select(Order).options( subqueryload(Order.items).subqueryload(Item.keywords) ) # lazily load Order.items, but when Items are loaded, # subquery-load the keywords collection select(Order).options(lazyload(Order.items).subqueryload(Item.keywords)) .. seealso:: :ref:`loading_toplevel` :ref:`subquery_eager_loading` """ return self._set_relationship_strategy(attr, {"lazy": "subquery"}) def selectinload( self, attr: _AttrType, recursion_depth: Optional[int] = None, ) -> Self: """Indicate that the given attribute should be loaded using SELECT IN eager loading. This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. examples:: # selectin-load the "orders" collection on "User" select(User).options(selectinload(User.orders)) # selectin-load Order.items and then Item.keywords select(Order).options( selectinload(Order.items).selectinload(Item.keywords) ) # lazily load Order.items, but when Items are loaded, # selectin-load the keywords collection select(Order).options(lazyload(Order.items).selectinload(Item.keywords)) :param recursion_depth: optional int; when set to a positive integer in conjunction with a self-referential relationship, indicates "selectin" loading will continue that many levels deep automatically until no items are found. .. note:: The :paramref:`_orm.selectinload.recursion_depth` option currently supports only self-referential relationships. There is not yet an option to automatically traverse recursive structures with more than one relationship involved. Additionally, the :paramref:`_orm.selectinload.recursion_depth` parameter is new and experimental and should be treated as "alpha" status for the 2.0 series. .. versionadded:: 2.0 added :paramref:`_orm.selectinload.recursion_depth` .. seealso:: :ref:`loading_toplevel` :ref:`selectin_eager_loading` """ return self._set_relationship_strategy( attr, {"lazy": "selectin"}, opts={"recursion_depth": recursion_depth}, ) def lazyload(self, attr: _AttrType) -> Self: """Indicate that the given attribute should be loaded using "lazy" loading. This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. .. seealso:: :ref:`loading_toplevel` :ref:`lazy_loading` """ return self._set_relationship_strategy(attr, {"lazy": "select"}) def immediateload( self, attr: _AttrType, recursion_depth: Optional[int] = None, ) -> Self: """Indicate that the given attribute should be loaded using an immediate load with a per-attribute SELECT statement. The load is achieved using the "lazyloader" strategy and does not fire off any additional eager loaders. The :func:`.immediateload` option is superseded in general by the :func:`.selectinload` option, which performs the same task more efficiently by emitting a SELECT for all loaded objects. This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. :param recursion_depth: optional int; when set to a positive integer in conjunction with a self-referential relationship, indicates "selectin" loading will continue that many levels deep automatically until no items are found. .. note:: The :paramref:`_orm.immediateload.recursion_depth` option currently supports only self-referential relationships. There is not yet an option to automatically traverse recursive structures with more than one relationship involved. .. warning:: This parameter is new and experimental and should be treated as "alpha" status .. versionadded:: 2.0 added :paramref:`_orm.immediateload.recursion_depth` .. seealso:: :ref:`loading_toplevel` :ref:`selectin_eager_loading` """ loader = self._set_relationship_strategy( attr, {"lazy": "immediate"}, opts={"recursion_depth": recursion_depth}, ) return loader def noload(self, attr: _AttrType) -> Self: """Indicate that the given relationship attribute should remain unloaded. The relationship attribute will return ``None`` when accessed without producing any loading effect. This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. :func:`_orm.noload` applies to :func:`_orm.relationship` attributes only. .. legacy:: The :func:`_orm.noload` option is **legacy**. As it forces collections to be empty, which invariably leads to non-intuitive and difficult to predict results. There are no legitimate uses for this option in modern SQLAlchemy. .. seealso:: :ref:`loading_toplevel` """ return self._set_relationship_strategy(attr, {"lazy": "noload"}) def raiseload(self, attr: _AttrType, sql_only: bool = False) -> Self: """Indicate that the given attribute should raise an error if accessed. A relationship attribute configured with :func:`_orm.raiseload` will raise an :exc:`~sqlalchemy.exc.InvalidRequestError` upon access. The typical way this is useful is when an application is attempting to ensure that all relationship attributes that are accessed in a particular context would have been already loaded via eager loading. Instead of having to read through SQL logs to ensure lazy loads aren't occurring, this strategy will cause them to raise immediately. :func:`_orm.raiseload` applies to :func:`_orm.relationship` attributes only. In order to apply raise-on-SQL behavior to a column-based attribute, use the :paramref:`.orm.defer.raiseload` parameter on the :func:`.defer` loader option. :param sql_only: if True, raise only if the lazy load would emit SQL, but not if it is only checking the identity map, or determining that the related value should just be None due to missing keys. When False, the strategy will raise for all varieties of relationship loading. This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. .. seealso:: :ref:`loading_toplevel` :ref:`prevent_lazy_with_raiseload` :ref:`orm_queryguide_deferred_raiseload` """ return self._set_relationship_strategy( attr, {"lazy": "raise_on_sql" if sql_only else "raise"} ) def defaultload(self, attr: _AttrType) -> Self: """Indicate an attribute should load using its predefined loader style. The behavior of this loading option is to not change the current loading style of the attribute, meaning that the previously configured one is used or, if no previous style was selected, the default loading will be used. This method is used to link to other loader options further into a chain of attributes without altering the loader style of the links along the chain. For example, to set joined eager loading for an element of an element:: session.query(MyClass).options( defaultload(MyClass.someattribute).joinedload( MyOtherClass.someotherattribute ) ) :func:`.defaultload` is also useful for setting column-level options on a related class, namely that of :func:`.defer` and :func:`.undefer`:: session.scalars( select(MyClass).options( defaultload(MyClass.someattribute) .defer("some_column") .undefer("some_other_column") ) ) .. seealso:: :ref:`orm_queryguide_relationship_sub_options` :meth:`_orm.Load.options` """ return self._set_relationship_strategy(attr, None) def defer(self, key: _AttrType, raiseload: bool = False) -> Self: r"""Indicate that the given column-oriented attribute should be deferred, e.g. not loaded until accessed. This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. e.g.:: from sqlalchemy.orm import defer session.query(MyClass).options( defer(MyClass.attribute_one), defer(MyClass.attribute_two) ) To specify a deferred load of an attribute on a related class, the path can be specified one token at a time, specifying the loading style for each link along the chain. To leave the loading style for a link unchanged, use :func:`_orm.defaultload`:: session.query(MyClass).options( defaultload(MyClass.someattr).defer(RelatedClass.some_column) ) Multiple deferral options related to a relationship can be bundled at once using :meth:`_orm.Load.options`:: select(MyClass).options( defaultload(MyClass.someattr).options( defer(RelatedClass.some_column), defer(RelatedClass.some_other_column), defer(RelatedClass.another_column), ) ) :param key: Attribute to be deferred. :param raiseload: raise :class:`.InvalidRequestError` rather than lazy loading a value when the deferred attribute is accessed. Used to prevent unwanted SQL from being emitted. .. versionadded:: 1.4 .. seealso:: :ref:`orm_queryguide_column_deferral` - in the :ref:`queryguide_toplevel` :func:`_orm.load_only` :func:`_orm.undefer` """ strategy = {"deferred": True, "instrument": True} if raiseload: strategy["raiseload"] = True return self._set_column_strategy((key,), strategy) def undefer(self, key: _AttrType) -> Self: r"""Indicate that the given column-oriented attribute should be undeferred, e.g. specified within the SELECT statement of the entity as a whole. The column being undeferred is typically set up on the mapping as a :func:`.deferred` attribute. This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. Examples:: # undefer two columns session.query(MyClass).options( undefer(MyClass.col1), undefer(MyClass.col2) ) # undefer all columns specific to a single class using Load + * session.query(MyClass, MyOtherClass).options(Load(MyClass).undefer("*")) # undefer a column on a related object select(MyClass).options(defaultload(MyClass.items).undefer(MyClass.text)) :param key: Attribute to be undeferred. .. seealso:: :ref:`orm_queryguide_column_deferral` - in the :ref:`queryguide_toplevel` :func:`_orm.defer` :func:`_orm.undefer_group` """ # noqa: E501 return self._set_column_strategy( (key,), {"deferred": False, "instrument": True} ) def undefer_group(self, name: str) -> Self: """Indicate that columns within the given deferred group name should be undeferred. The columns being undeferred are set up on the mapping as :func:`.deferred` attributes and include a "group" name. E.g:: session.query(MyClass).options(undefer_group("large_attrs")) To undefer a group of attributes on a related entity, the path can be spelled out using relationship loader options, such as :func:`_orm.defaultload`:: select(MyClass).options( defaultload("someattr").undefer_group("large_attrs") ) .. seealso:: :ref:`orm_queryguide_column_deferral` - in the :ref:`queryguide_toplevel` :func:`_orm.defer` :func:`_orm.undefer` """ return self._set_column_strategy( (_WILDCARD_TOKEN,), None, {f"undefer_group_{name}": True} ) def with_expression( self, key: _AttrType, expression: _ColumnExpressionArgument[Any], ) -> Self: r"""Apply an ad-hoc SQL expression to a "deferred expression" attribute. This option is used in conjunction with the :func:`_orm.query_expression` mapper-level construct that indicates an attribute which should be the target of an ad-hoc SQL expression. E.g.:: stmt = select(SomeClass).options( with_expression(SomeClass.x_y_expr, SomeClass.x + SomeClass.y) ) .. versionadded:: 1.2 :param key: Attribute to be populated :param expr: SQL expression to be applied to the attribute. .. seealso:: :ref:`orm_queryguide_with_expression` - background and usage examples """ expression = _orm_full_deannotate( coercions.expect(roles.LabeledColumnExprRole, expression) ) return self._set_column_strategy( (key,), {"query_expression": True}, extra_criteria=(expression,) ) def selectin_polymorphic(self, classes: Iterable[Type[Any]]) -> Self: """Indicate an eager load should take place for all attributes specific to a subclass. This uses an additional SELECT with IN against all matched primary key values, and is the per-query analogue to the ``"selectin"`` setting on the :paramref:`.mapper.polymorphic_load` parameter. .. versionadded:: 1.2 .. seealso:: :ref:`polymorphic_selectin` """ self = self._set_class_strategy( {"selectinload_polymorphic": True}, opts={ "entities": tuple( sorted((inspect(cls) for cls in classes), key=id) ) }, ) return self @overload def _coerce_strat(self, strategy: _StrategySpec) -> _StrategyKey: ... @overload def _coerce_strat(self, strategy: Literal[None]) -> None: ... def _coerce_strat( self, strategy: Optional[_StrategySpec] ) -> Optional[_StrategyKey]: if strategy is not None: strategy_key = tuple(sorted(strategy.items())) else: strategy_key = None return strategy_key @_generative def _set_relationship_strategy( self, attr: _AttrType, strategy: Optional[_StrategySpec], propagate_to_loaders: bool = True, opts: Optional[_OptsType] = None, _reconcile_to_other: Optional[bool] = None, ) -> Self: strategy_key = self._coerce_strat(strategy) self._clone_for_bind_strategy( (attr,), strategy_key, _RELATIONSHIP_TOKEN, opts=opts, propagate_to_loaders=propagate_to_loaders, reconcile_to_other=_reconcile_to_other, ) return self @_generative def _set_column_strategy( self, attrs: Tuple[_AttrType, ...], strategy: Optional[_StrategySpec], opts: Optional[_OptsType] = None, extra_criteria: Optional[Tuple[Any, ...]] = None, ) -> Self: strategy_key = self._coerce_strat(strategy) self._clone_for_bind_strategy( attrs, strategy_key, _COLUMN_TOKEN, opts=opts, attr_group=attrs, extra_criteria=extra_criteria, ) return self @_generative def _set_generic_strategy( self, attrs: Tuple[_AttrType, ...], strategy: _StrategySpec, _reconcile_to_other: Optional[bool] = None, ) -> Self: strategy_key = self._coerce_strat(strategy) self._clone_for_bind_strategy( attrs, strategy_key, None, propagate_to_loaders=True, reconcile_to_other=_reconcile_to_other, ) return self @_generative def _set_class_strategy( self, strategy: _StrategySpec, opts: _OptsType ) -> Self: strategy_key = self._coerce_strat(strategy) self._clone_for_bind_strategy(None, strategy_key, None, opts=opts) return self def _apply_to_parent(self, parent: Load) -> None: """apply this :class:`_orm._AbstractLoad` object as a sub-option o a :class:`_orm.Load` object. Implementation is provided by subclasses. """ raise NotImplementedError() def options(self, *opts: _AbstractLoad) -> Self: r"""Apply a series of options as sub-options to this :class:`_orm._AbstractLoad` object. Implementation is provided by subclasses. """ raise NotImplementedError() def _clone_for_bind_strategy( self, attrs: Optional[Tuple[_AttrType, ...]], strategy: Optional[_StrategyKey], wildcard_key: Optional[_WildcardKeyType], opts: Optional[_OptsType] = None, attr_group: Optional[_AttrGroupType] = None, propagate_to_loaders: bool = True, reconcile_to_other: Optional[bool] = None, extra_criteria: Optional[Tuple[Any, ...]] = None, ) -> Self: raise NotImplementedError() def process_compile_state_replaced_entities( self, compile_state: ORMCompileState, mapper_entities: Sequence[_MapperEntity], ) -> None: if not compile_state.compile_options._enable_eagerloads: return # process is being run here so that the options given are validated # against what the lead entities were, as well as to accommodate # for the entities having been replaced with equivalents self._process( compile_state, mapper_entities, not bool(compile_state.current_path), ) def process_compile_state(self, compile_state: ORMCompileState) -> None: if not compile_state.compile_options._enable_eagerloads: return self._process( compile_state, compile_state._lead_mapper_entities, not bool(compile_state.current_path) and not compile_state.compile_options._for_refresh_state, ) def _process( self, compile_state: ORMCompileState, mapper_entities: Sequence[_MapperEntity], raiseerr: bool, ) -> None: """implemented by subclasses""" raise NotImplementedError() @classmethod def _chop_path( cls, to_chop: _PathRepresentation, path: PathRegistry, debug: bool = False, ) -> Optional[_PathRepresentation]: i = -1 for i, (c_token, p_token) in enumerate( zip(to_chop, path.natural_path) ): if isinstance(c_token, str): if i == 0 and ( c_token.endswith(f":{_DEFAULT_TOKEN}") or c_token.endswith(f":{_WILDCARD_TOKEN}") ): return to_chop elif ( c_token != f"{_RELATIONSHIP_TOKEN}:{_WILDCARD_TOKEN}" and c_token != p_token.key # type: ignore ): return None if c_token is p_token: continue elif ( isinstance(c_token, InspectionAttr) and insp_is_mapper(c_token) and insp_is_mapper(p_token) and c_token.isa(p_token) ): continue else: return None return to_chop[i + 1 :] class Load(_AbstractLoad): """Represents loader options which modify the state of a ORM-enabled :class:`_sql.Select` or a legacy :class:`_query.Query` in order to affect how various mapped attributes are loaded. The :class:`_orm.Load` object is in most cases used implicitly behind the scenes when one makes use of a query option like :func:`_orm.joinedload`, :func:`_orm.defer`, or similar. It typically is not instantiated directly except for in some very specific cases. .. seealso:: :ref:`orm_queryguide_relationship_per_entity_wildcard` - illustrates an example where direct use of :class:`_orm.Load` may be useful """ __slots__ = ( "path", "context", "additional_source_entities", ) _traverse_internals = [ ("path", visitors.ExtendedInternalTraversal.dp_has_cache_key), ( "context", visitors.InternalTraversal.dp_has_cache_key_list, ), ("propagate_to_loaders", visitors.InternalTraversal.dp_boolean), ( "additional_source_entities", visitors.InternalTraversal.dp_has_cache_key_list, ), ] _cache_key_traversal = None path: PathRegistry context: Tuple[_LoadElement, ...] additional_source_entities: Tuple[_InternalEntityType[Any], ...] def __init__(self, entity: _EntityType[Any]): insp = cast("Union[Mapper[Any], AliasedInsp[Any]]", inspect(entity)) insp._post_inspect self.path = insp._path_registry self.context = () self.propagate_to_loaders = False self.additional_source_entities = () def __str__(self) -> str: return f"Load({self.path[0]})" @classmethod def _construct_for_existing_path( cls, path: AbstractEntityRegistry ) -> Load: load = cls.__new__(cls) load.path = path load.context = () load.propagate_to_loaders = False load.additional_source_entities = () return load def _adapt_cached_option_to_uncached_option( self, context: QueryContext, uncached_opt: ORMOption ) -> ORMOption: if uncached_opt is self: return self return self._adjust_for_extra_criteria(context) def _prepend_path(self, path: PathRegistry) -> Load: cloned = self._clone() cloned.context = tuple( element._prepend_path(path) for element in self.context ) return cloned def _adjust_for_extra_criteria(self, context: QueryContext) -> Load: """Apply the current bound parameters in a QueryContext to all occurrences "extra_criteria" stored within this ``Load`` object, returning a new instance of this ``Load`` object. """ # avoid generating cache keys for the queries if we don't # actually have any extra_criteria options, which is the # common case for value in self.context: if value._extra_criteria: break else: return self replacement_cache_key = context.user_passed_query._generate_cache_key() if replacement_cache_key is None: return self orig_query = context.compile_state.select_statement orig_cache_key = orig_query._generate_cache_key() assert orig_cache_key is not None def process( opt: _LoadElement, replacement_cache_key: CacheKey, orig_cache_key: CacheKey, ) -> _LoadElement: cloned_opt = opt._clone() cloned_opt._extra_criteria = tuple( replacement_cache_key._apply_params_to_element( orig_cache_key, crit ) for crit in cloned_opt._extra_criteria ) return cloned_opt cloned = self._clone() cloned.context = tuple( ( process(value, replacement_cache_key, orig_cache_key) if value._extra_criteria else value ) for value in self.context ) return cloned def _reconcile_query_entities_with_us(self, mapper_entities, raiseerr): """called at process time to allow adjustment of the root entity inside of _LoadElement objects. """ path = self.path for ent in mapper_entities: ezero = ent.entity_zero if ezero and orm_util._entity_corresponds_to( # technically this can be a token also, but this is # safe to pass to _entity_corresponds_to() ezero, cast("_InternalEntityType[Any]", path[0]), ): return ezero return None def _process( self, compile_state: ORMCompileState, mapper_entities: Sequence[_MapperEntity], raiseerr: bool, ) -> None: reconciled_lead_entity = self._reconcile_query_entities_with_us( mapper_entities, raiseerr ) # if the context has a current path, this is a lazy load has_current_path = bool(compile_state.compile_options._current_path) for loader in self.context: # issue #11292 # historically, propagate_to_loaders was only considered at # object loading time, whether or not to carry along options # onto an object's loaded state where it would be used by lazyload. # however, the defaultload() option needs to propagate in case # its sub-options propagate_to_loaders, but its sub-options # that dont propagate should not be applied for lazy loaders. # so we check again if has_current_path and not loader.propagate_to_loaders: continue loader.process_compile_state( self, compile_state, mapper_entities, reconciled_lead_entity, raiseerr, ) def _apply_to_parent(self, parent: Load) -> None: """apply this :class:`_orm.Load` object as a sub-option of another :class:`_orm.Load` object. This method is used by the :meth:`_orm.Load.options` method. """ cloned = self._generate() assert cloned.propagate_to_loaders == self.propagate_to_loaders if not any( orm_util._entity_corresponds_to_use_path_impl( elem, cloned.path.odd_element(0) ) for elem in (parent.path.odd_element(-1),) + parent.additional_source_entities ): if len(cloned.path) > 1: attrname = cloned.path[1] parent_entity = cloned.path[0] else: attrname = cloned.path[0] parent_entity = cloned.path[0] _raise_for_does_not_link(parent.path, attrname, parent_entity) cloned.path = PathRegistry.coerce(parent.path[0:-1] + cloned.path[:]) if self.context: cloned.context = tuple( value._prepend_path_from(parent) for value in self.context ) if cloned.context: parent.context += cloned.context parent.additional_source_entities += ( cloned.additional_source_entities ) @_generative def options(self, *opts: _AbstractLoad) -> Self: r"""Apply a series of options as sub-options to this :class:`_orm.Load` object. E.g.:: query = session.query(Author) query = query.options( joinedload(Author.book).options( load_only(Book.summary, Book.excerpt), joinedload(Book.citations).options(joinedload(Citation.author)), ) ) :param \*opts: A series of loader option objects (ultimately :class:`_orm.Load` objects) which should be applied to the path specified by this :class:`_orm.Load` object. .. versionadded:: 1.3.6 .. seealso:: :func:`.defaultload` :ref:`orm_queryguide_relationship_sub_options` """ for opt in opts: try: opt._apply_to_parent(self) except AttributeError as ae: if not isinstance(opt, _AbstractLoad): raise sa_exc.ArgumentError( f"Loader option {opt} is not compatible with the " "Load.options() method." ) from ae else: raise return self def _clone_for_bind_strategy( self, attrs: Optional[Tuple[_AttrType, ...]], strategy: Optional[_StrategyKey], wildcard_key: Optional[_WildcardKeyType], opts: Optional[_OptsType] = None, attr_group: Optional[_AttrGroupType] = None, propagate_to_loaders: bool = True, reconcile_to_other: Optional[bool] = None, extra_criteria: Optional[Tuple[Any, ...]] = None, ) -> Self: # for individual strategy that needs to propagate, set the whole # Load container to also propagate, so that it shows up in # InstanceState.load_options if propagate_to_loaders: self.propagate_to_loaders = True if self.path.is_token: raise sa_exc.ArgumentError( "Wildcard token cannot be followed by another entity" ) elif path_is_property(self.path): # re-use the lookup which will raise a nicely formatted # LoaderStrategyException if strategy: self.path.prop._strategy_lookup(self.path.prop, strategy[0]) else: raise sa_exc.ArgumentError( f"Mapped attribute '{self.path.prop}' does not " "refer to a mapped entity" ) if attrs is None: load_element = _ClassStrategyLoad.create( self.path, None, strategy, wildcard_key, opts, propagate_to_loaders, attr_group=attr_group, reconcile_to_other=reconcile_to_other, extra_criteria=extra_criteria, ) if load_element: self.context += (load_element,) assert opts is not None self.additional_source_entities += cast( "Tuple[_InternalEntityType[Any]]", opts["entities"] ) else: for attr in attrs: if isinstance(attr, str): load_element = _TokenStrategyLoad.create( self.path, attr, strategy, wildcard_key, opts, propagate_to_loaders, attr_group=attr_group, reconcile_to_other=reconcile_to_other, extra_criteria=extra_criteria, ) else: load_element = _AttributeStrategyLoad.create( self.path, attr, strategy, wildcard_key, opts, propagate_to_loaders, attr_group=attr_group, reconcile_to_other=reconcile_to_other, extra_criteria=extra_criteria, ) if load_element: # for relationship options, update self.path on this Load # object with the latest path. if wildcard_key is _RELATIONSHIP_TOKEN: self.path = load_element.path self.context += (load_element,) # this seems to be effective for selectinloader, # giving the extra match to one more level deep. # but does not work for immediateloader, which still # must add additional options at load time if load_element.local_opts.get("recursion_depth", False): r1 = load_element._recurse() self.context += (r1,) return self def __getstate__(self): d = self._shallow_to_dict() d["path"] = self.path.serialize() return d def __setstate__(self, state): state["path"] = PathRegistry.deserialize(state["path"]) self._shallow_from_dict(state) class _WildcardLoad(_AbstractLoad): """represent a standalone '*' load operation""" __slots__ = ("strategy", "path", "local_opts") _traverse_internals = [ ("strategy", visitors.ExtendedInternalTraversal.dp_plain_obj), ("path", visitors.ExtendedInternalTraversal.dp_plain_obj), ( "local_opts", visitors.ExtendedInternalTraversal.dp_string_multi_dict, ), ] cache_key_traversal: _CacheKeyTraversalType = None strategy: Optional[Tuple[Any, ...]] local_opts: _OptsType path: Union[Tuple[()], Tuple[str]] propagate_to_loaders = False def __init__(self) -> None: self.path = () self.strategy = None self.local_opts = util.EMPTY_DICT def _clone_for_bind_strategy( self, attrs, strategy, wildcard_key, opts=None, attr_group=None, propagate_to_loaders=True, reconcile_to_other=None, extra_criteria=None, ): assert attrs is not None attr = attrs[0] assert ( wildcard_key and isinstance(attr, str) and attr in (_WILDCARD_TOKEN, _DEFAULT_TOKEN) ) attr = f"{wildcard_key}:{attr}" self.strategy = strategy self.path = (attr,) if opts: self.local_opts = util.immutabledict(opts) assert extra_criteria is None def options(self, *opts: _AbstractLoad) -> Self: raise NotImplementedError("Star option does not support sub-options") def _apply_to_parent(self, parent: Load) -> None: """apply this :class:`_orm._WildcardLoad` object as a sub-option of a :class:`_orm.Load` object. This method is used by the :meth:`_orm.Load.options` method. Note that :class:`_orm.WildcardLoad` itself can't have sub-options, but it may be used as the sub-option of a :class:`_orm.Load` object. """ assert self.path attr = self.path[0] if attr.endswith(_DEFAULT_TOKEN): attr = f"{attr.split(':')[0]}:{_WILDCARD_TOKEN}" effective_path = cast(AbstractEntityRegistry, parent.path).token(attr) assert effective_path.is_token loader = _TokenStrategyLoad.create( effective_path, None, self.strategy, None, self.local_opts, self.propagate_to_loaders, ) parent.context += (loader,) def _process(self, compile_state, mapper_entities, raiseerr): is_refresh = compile_state.compile_options._for_refresh_state if is_refresh and not self.propagate_to_loaders: return entities = [ent.entity_zero for ent in mapper_entities] current_path = compile_state.current_path start_path: _PathRepresentation = self.path if current_path: # TODO: no cases in test suite where we actually get # None back here new_path = self._chop_path(start_path, current_path) if new_path is None: return # chop_path does not actually "chop" a wildcard token path, # just returns it assert new_path == start_path # start_path is a single-token tuple assert start_path and len(start_path) == 1 token = start_path[0] assert isinstance(token, str) entity = self._find_entity_basestring(entities, token, raiseerr) if not entity: return path_element = entity # transfer our entity-less state into a Load() object # with a real entity path. Start with the lead entity # we just located, then go through the rest of our path # tokens and populate into the Load(). assert isinstance(token, str) loader = _TokenStrategyLoad.create( path_element._path_registry, token, self.strategy, None, self.local_opts, self.propagate_to_loaders, raiseerr=raiseerr, ) if not loader: return assert loader.path.is_token # don't pass a reconciled lead entity here loader.process_compile_state( self, compile_state, mapper_entities, None, raiseerr ) return loader def _find_entity_basestring( self, entities: Iterable[_InternalEntityType[Any]], token: str, raiseerr: bool, ) -> Optional[_InternalEntityType[Any]]: if token.endswith(f":{_WILDCARD_TOKEN}"): if len(list(entities)) != 1: if raiseerr: raise sa_exc.ArgumentError( "Can't apply wildcard ('*') or load_only() " f"loader option to multiple entities " f"{', '.join(str(ent) for ent in entities)}. Specify " "loader options for each entity individually, such as " f"""{ ", ".join( f"Load({ent}).some_option('*')" for ent in entities ) }.""" ) elif token.endswith(_DEFAULT_TOKEN): raiseerr = False for ent in entities: # return only the first _MapperEntity when searching # based on string prop name. Ideally object # attributes are used to specify more exactly. return ent else: if raiseerr: raise sa_exc.ArgumentError( "Query has only expression-based entities - " f'can\'t find property named "{token}".' ) else: return None def __getstate__(self) -> Dict[str, Any]: d = self._shallow_to_dict() return d def __setstate__(self, state: Dict[str, Any]) -> None: self._shallow_from_dict(state) class _LoadElement( cache_key.HasCacheKey, traversals.HasShallowCopy, visitors.Traversible ): """represents strategy information to select for a LoaderStrategy and pass options to it. :class:`._LoadElement` objects provide the inner datastructure stored by a :class:`_orm.Load` object and are also the object passed to methods like :meth:`.LoaderStrategy.setup_query`. .. versionadded:: 2.0 """ __slots__ = ( "path", "strategy", "propagate_to_loaders", "local_opts", "_extra_criteria", "_reconcile_to_other", ) __visit_name__ = "load_element" _traverse_internals = [ ("path", visitors.ExtendedInternalTraversal.dp_has_cache_key), ("strategy", visitors.ExtendedInternalTraversal.dp_plain_obj), ( "local_opts", visitors.ExtendedInternalTraversal.dp_string_multi_dict, ), ("_extra_criteria", visitors.InternalTraversal.dp_clauseelement_list), ("propagate_to_loaders", visitors.InternalTraversal.dp_plain_obj), ("_reconcile_to_other", visitors.InternalTraversal.dp_plain_obj), ] _cache_key_traversal = None _extra_criteria: Tuple[Any, ...] _reconcile_to_other: Optional[bool] strategy: Optional[_StrategyKey] path: PathRegistry propagate_to_loaders: bool local_opts: util.immutabledict[str, Any] is_token_strategy: bool is_class_strategy: bool def __hash__(self) -> int: return id(self) def __eq__(self, other): return traversals.compare(self, other) @property def is_opts_only(self) -> bool: return bool(self.local_opts and self.strategy is None) def _clone(self, **kw: Any) -> _LoadElement: cls = self.__class__ s = cls.__new__(cls) self._shallow_copy_to(s) return s def _update_opts(self, **kw: Any) -> _LoadElement: new = self._clone() new.local_opts = new.local_opts.union(kw) return new def __getstate__(self) -> Dict[str, Any]: d = self._shallow_to_dict() d["path"] = self.path.serialize() return d def __setstate__(self, state: Dict[str, Any]) -> None: state["path"] = PathRegistry.deserialize(state["path"]) self._shallow_from_dict(state) def _raise_for_no_match(self, parent_loader, mapper_entities): path = parent_loader.path found_entities = False for ent in mapper_entities: ezero = ent.entity_zero if ezero: found_entities = True break if not found_entities: raise sa_exc.ArgumentError( "Query has only expression-based entities; " f"attribute loader options for {path[0]} can't " "be applied here." ) else: raise sa_exc.ArgumentError( f"Mapped class {path[0]} does not apply to any of the " f"root entities in this query, e.g. " f"""{ ", ".join( str(x.entity_zero) for x in mapper_entities if x.entity_zero )}. Please """ "specify the full path " "from one of the root entities to the target " "attribute. " ) def _adjust_effective_path_for_current_path( self, effective_path: PathRegistry, current_path: PathRegistry ) -> Optional[PathRegistry]: """receives the 'current_path' entry from an :class:`.ORMCompileState` instance, which is set during lazy loads and secondary loader strategy loads, and adjusts the given path to be relative to the current_path. E.g. given a loader path and current path: .. sourcecode:: text lp: User -> orders -> Order -> items -> Item -> keywords -> Keyword cp: User -> orders -> Order -> items The adjusted path would be: .. sourcecode:: text Item -> keywords -> Keyword """ chopped_start_path = Load._chop_path( effective_path.natural_path, current_path ) if not chopped_start_path: return None tokens_removed_from_start_path = len(effective_path) - len( chopped_start_path ) loader_lead_path_element = self.path[tokens_removed_from_start_path] effective_path = PathRegistry.coerce( (loader_lead_path_element,) + chopped_start_path[1:] ) return effective_path def _init_path( self, path, attr, wildcard_key, attr_group, raiseerr, extra_criteria ): """Apply ORM attributes and/or wildcard to an existing path, producing a new path. This method is used within the :meth:`.create` method to initialize a :class:`._LoadElement` object. """ raise NotImplementedError() def _prepare_for_compile_state( self, parent_loader, compile_state, mapper_entities, reconciled_lead_entity, raiseerr, ): """implemented by subclasses.""" raise NotImplementedError() def process_compile_state( self, parent_loader, compile_state, mapper_entities, reconciled_lead_entity, raiseerr, ): """populate ORMCompileState.attributes with loader state for this _LoadElement. """ keys = self._prepare_for_compile_state( parent_loader, compile_state, mapper_entities, reconciled_lead_entity, raiseerr, ) for key in keys: if key in compile_state.attributes: compile_state.attributes[key] = _LoadElement._reconcile( self, compile_state.attributes[key] ) else: compile_state.attributes[key] = self @classmethod def create( cls, path: PathRegistry, attr: Union[_AttrType, _StrPathToken, None], strategy: Optional[_StrategyKey], wildcard_key: Optional[_WildcardKeyType], local_opts: Optional[_OptsType], propagate_to_loaders: bool, raiseerr: bool = True, attr_group: Optional[_AttrGroupType] = None, reconcile_to_other: Optional[bool] = None, extra_criteria: Optional[Tuple[Any, ...]] = None, ) -> _LoadElement: """Create a new :class:`._LoadElement` object.""" opt = cls.__new__(cls) opt.path = path opt.strategy = strategy opt.propagate_to_loaders = propagate_to_loaders opt.local_opts = ( util.immutabledict(local_opts) if local_opts else util.EMPTY_DICT ) opt._extra_criteria = () if reconcile_to_other is not None: opt._reconcile_to_other = reconcile_to_other elif strategy is None and not local_opts: opt._reconcile_to_other = True else: opt._reconcile_to_other = None path = opt._init_path( path, attr, wildcard_key, attr_group, raiseerr, extra_criteria ) if not path: return None # type: ignore assert opt.is_token_strategy == path.is_token opt.path = path return opt def __init__(self) -> None: raise NotImplementedError() def _recurse(self) -> _LoadElement: cloned = self._clone() cloned.path = PathRegistry.coerce(self.path[:] + self.path[-2:]) return cloned def _prepend_path_from(self, parent: Load) -> _LoadElement: """adjust the path of this :class:`._LoadElement` to be a subpath of that of the given parent :class:`_orm.Load` object's path. This is used by the :meth:`_orm.Load._apply_to_parent` method, which is in turn part of the :meth:`_orm.Load.options` method. """ if not any( orm_util._entity_corresponds_to_use_path_impl( elem, self.path.odd_element(0), ) for elem in (parent.path.odd_element(-1),) + parent.additional_source_entities ): raise sa_exc.ArgumentError( f'Attribute "{self.path[1]}" does not link ' f'from element "{parent.path[-1]}".' ) return self._prepend_path(parent.path) def _prepend_path(self, path: PathRegistry) -> _LoadElement: cloned = self._clone() assert cloned.strategy == self.strategy assert cloned.local_opts == self.local_opts assert cloned.is_class_strategy == self.is_class_strategy cloned.path = PathRegistry.coerce(path[0:-1] + cloned.path[:]) return cloned @staticmethod def _reconcile( replacement: _LoadElement, existing: _LoadElement ) -> _LoadElement: """define behavior for when two Load objects are to be put into the context.attributes under the same key. :param replacement: ``_LoadElement`` that seeks to replace the existing one :param existing: ``_LoadElement`` that is already present. """ # mapper inheritance loading requires fine-grained "block other # options" / "allow these options to be overridden" behaviors # see test_poly_loading.py if replacement._reconcile_to_other: return existing elif replacement._reconcile_to_other is False: return replacement elif existing._reconcile_to_other: return replacement elif existing._reconcile_to_other is False: return existing if existing is replacement: return replacement elif ( existing.strategy == replacement.strategy and existing.local_opts == replacement.local_opts ): return replacement elif replacement.is_opts_only: existing = existing._clone() existing.local_opts = existing.local_opts.union( replacement.local_opts ) existing._extra_criteria += replacement._extra_criteria return existing elif existing.is_opts_only: replacement = replacement._clone() replacement.local_opts = replacement.local_opts.union( existing.local_opts ) replacement._extra_criteria += existing._extra_criteria return replacement elif replacement.path.is_token: # use 'last one wins' logic for wildcard options. this is also # kind of inconsistent vs. options that are specific paths which # will raise as below return replacement raise sa_exc.InvalidRequestError( f"Loader strategies for {replacement.path} conflict" ) class _AttributeStrategyLoad(_LoadElement): """Loader strategies against specific relationship or column paths. e.g.:: joinedload(User.addresses) defer(Order.name) selectinload(User.orders).lazyload(Order.items) """ __slots__ = ("_of_type", "_path_with_polymorphic_path") __visit_name__ = "attribute_strategy_load_element" _traverse_internals = _LoadElement._traverse_internals + [ ("_of_type", visitors.ExtendedInternalTraversal.dp_multi), ( "_path_with_polymorphic_path", visitors.ExtendedInternalTraversal.dp_has_cache_key, ), ] _of_type: Union[Mapper[Any], AliasedInsp[Any], None] _path_with_polymorphic_path: Optional[PathRegistry] is_class_strategy = False is_token_strategy = False def _init_path( self, path, attr, wildcard_key, attr_group, raiseerr, extra_criteria ): assert attr is not None self._of_type = None self._path_with_polymorphic_path = None insp, _, prop = _parse_attr_argument(attr) if insp.is_property: # direct property can be sent from internal strategy logic # that sets up specific loaders, such as # emit_lazyload->_lazyload_reverse # prop = found_property = attr prop = attr path = path[prop] if path.has_entity: path = path.entity_path return path elif not insp.is_attribute: # should not reach here; assert False # here we assume we have user-passed InstrumentedAttribute if not orm_util._entity_corresponds_to_use_path_impl( path[-1], attr.parent ): if raiseerr: if attr_group and attr is not attr_group[0]: raise sa_exc.ArgumentError( "Can't apply wildcard ('*') or load_only() " "loader option to multiple entities in the " "same option. Use separate options per entity." ) else: _raise_for_does_not_link(path, str(attr), attr.parent) else: return None # note the essential logic of this attribute was very different in # 1.4, where there were caching failures in e.g. # test_relationship_criteria.py::RelationshipCriteriaTest:: # test_selectinload_nested_criteria[True] if an existing # "_extra_criteria" on a Load object were replaced with that coming # from an attribute. This appears to have been an artifact of how # _UnboundLoad / Load interacted together, which was opaque and # poorly defined. if extra_criteria: assert not attr._extra_criteria self._extra_criteria = extra_criteria else: self._extra_criteria = attr._extra_criteria if getattr(attr, "_of_type", None): ac = attr._of_type ext_info = inspect(ac) self._of_type = ext_info self._path_with_polymorphic_path = path.entity_path[prop] path = path[prop][ext_info] else: path = path[prop] if path.has_entity: path = path.entity_path return path def _generate_extra_criteria(self, context): """Apply the current bound parameters in a QueryContext to the immediate "extra_criteria" stored with this Load object. Load objects are typically pulled from the cached version of the statement from a QueryContext. The statement currently being executed will have new values (and keys) for bound parameters in the extra criteria which need to be applied by loader strategies when they handle this criteria for a result set. """ assert ( self._extra_criteria ), "this should only be called if _extra_criteria is present" orig_query = context.compile_state.select_statement current_query = context.query # NOTE: while it seems like we should not do the "apply" operation # here if orig_query is current_query, skipping it in the "optimized" # case causes the query to be different from a cache key perspective, # because we are creating a copy of the criteria which is no longer # the same identity of the _extra_criteria in the loader option # itself. cache key logic produces a different key for # (A, copy_of_A) vs. (A, A), because in the latter case it shortens # the second part of the key to just indicate on identity. # if orig_query is current_query: # not cached yet. just do the and_() # return and_(*self._extra_criteria) k1 = orig_query._generate_cache_key() k2 = current_query._generate_cache_key() return k2._apply_params_to_element(k1, and_(*self._extra_criteria)) def _set_of_type_info(self, context, current_path): assert self._path_with_polymorphic_path pwpi = self._of_type assert pwpi if not pwpi.is_aliased_class: pwpi = inspect( orm_util.AliasedInsp._with_polymorphic_factory( pwpi.mapper.base_mapper, (pwpi.mapper,), aliased=True, _use_mapper_path=True, ) ) start_path = self._path_with_polymorphic_path if current_path: new_path = self._adjust_effective_path_for_current_path( start_path, current_path ) if new_path is None: return start_path = new_path key = ("path_with_polymorphic", start_path.natural_path) if key in context: existing_aliased_insp = context[key] this_aliased_insp = pwpi new_aliased_insp = existing_aliased_insp._merge_with( this_aliased_insp ) context[key] = new_aliased_insp else: context[key] = pwpi def _prepare_for_compile_state( self, parent_loader, compile_state, mapper_entities, reconciled_lead_entity, raiseerr, ): # _AttributeStrategyLoad current_path = compile_state.current_path is_refresh = compile_state.compile_options._for_refresh_state assert not self.path.is_token if is_refresh and not self.propagate_to_loaders: return [] if self._of_type: # apply additional with_polymorphic alias that may have been # generated. this has to happen even if this is a defaultload self._set_of_type_info(compile_state.attributes, current_path) # omit setting loader attributes for a "defaultload" type of option if not self.strategy and not self.local_opts: return [] if raiseerr and not reconciled_lead_entity: self._raise_for_no_match(parent_loader, mapper_entities) if self.path.has_entity: effective_path = self.path.parent else: effective_path = self.path if current_path: assert effective_path is not None effective_path = self._adjust_effective_path_for_current_path( effective_path, current_path ) if effective_path is None: return [] return [("loader", cast(PathRegistry, effective_path).natural_path)] def __getstate__(self): d = super().__getstate__() # can't pickle this. See # test_pickled.py -> test_lazyload_extra_criteria_not_supported # where we should be emitting a warning for the usual case where this # would be non-None d["_extra_criteria"] = () if self._path_with_polymorphic_path: d["_path_with_polymorphic_path"] = ( self._path_with_polymorphic_path.serialize() ) if self._of_type: if self._of_type.is_aliased_class: d["_of_type"] = None elif self._of_type.is_mapper: d["_of_type"] = self._of_type.class_ else: assert False, "unexpected object for _of_type" return d def __setstate__(self, state): super().__setstate__(state) if state.get("_path_with_polymorphic_path", None): self._path_with_polymorphic_path = PathRegistry.deserialize( state["_path_with_polymorphic_path"] ) else: self._path_with_polymorphic_path = None if state.get("_of_type", None): self._of_type = inspect(state["_of_type"]) else: self._of_type = None class _TokenStrategyLoad(_LoadElement): """Loader strategies against wildcard attributes e.g.:: raiseload("*") Load(User).lazyload("*") defer("*") load_only(User.name, User.email) # will create a defer('*') joinedload(User.addresses).raiseload("*") """ __visit_name__ = "token_strategy_load_element" inherit_cache = True is_class_strategy = False is_token_strategy = True def _init_path( self, path, attr, wildcard_key, attr_group, raiseerr, extra_criteria ): # assert isinstance(attr, str) or attr is None if attr is not None: default_token = attr.endswith(_DEFAULT_TOKEN) if attr.endswith(_WILDCARD_TOKEN) or default_token: if wildcard_key: attr = f"{wildcard_key}:{attr}" path = path.token(attr) return path else: raise sa_exc.ArgumentError( "Strings are not accepted for attribute names in loader " "options; please use class-bound attributes directly." ) return path def _prepare_for_compile_state( self, parent_loader, compile_state, mapper_entities, reconciled_lead_entity, raiseerr, ): # _TokenStrategyLoad current_path = compile_state.current_path is_refresh = compile_state.compile_options._for_refresh_state assert self.path.is_token if is_refresh and not self.propagate_to_loaders: return [] # omit setting attributes for a "defaultload" type of option if not self.strategy and not self.local_opts: return [] effective_path = self.path if reconciled_lead_entity: effective_path = PathRegistry.coerce( (reconciled_lead_entity,) + effective_path.path[1:] ) if current_path: new_effective_path = self._adjust_effective_path_for_current_path( effective_path, current_path ) if new_effective_path is None: return [] effective_path = new_effective_path # for a wildcard token, expand out the path we set # to encompass everything from the query entity on # forward. not clear if this is necessary when current_path # is set. return [ ("loader", natural_path) for natural_path in ( cast( TokenRegistry, effective_path )._generate_natural_for_superclasses() ) ] class _ClassStrategyLoad(_LoadElement): """Loader strategies that deals with a class as a target, not an attribute path e.g.:: q = s.query(Person).options( selectin_polymorphic(Person, [Engineer, Manager]) ) """ inherit_cache = True is_class_strategy = True is_token_strategy = False __visit_name__ = "class_strategy_load_element" def _init_path( self, path, attr, wildcard_key, attr_group, raiseerr, extra_criteria ): return path def _prepare_for_compile_state( self, parent_loader, compile_state, mapper_entities, reconciled_lead_entity, raiseerr, ): # _ClassStrategyLoad current_path = compile_state.current_path is_refresh = compile_state.compile_options._for_refresh_state if is_refresh and not self.propagate_to_loaders: return [] # omit setting attributes for a "defaultload" type of option if not self.strategy and not self.local_opts: return [] effective_path = self.path if current_path: new_effective_path = self._adjust_effective_path_for_current_path( effective_path, current_path ) if new_effective_path is None: return [] effective_path = new_effective_path return [("loader", effective_path.natural_path)] def _generate_from_keys( meth: Callable[..., _AbstractLoad], keys: Tuple[_AttrType, ...], chained: bool, kw: Any, ) -> _AbstractLoad: lead_element: Optional[_AbstractLoad] = None attr: Any for is_default, _keys in (True, keys[0:-1]), (False, keys[-1:]): for attr in _keys: if isinstance(attr, str): if attr.startswith("." + _WILDCARD_TOKEN): util.warn_deprecated( "The undocumented `.{WILDCARD}` format is " "deprecated " "and will be removed in a future version as " "it is " "believed to be unused. " "If you have been using this functionality, " "please " "comment on Issue #4390 on the SQLAlchemy project " "tracker.", version="1.4", ) attr = attr[1:] if attr == _WILDCARD_TOKEN: if is_default: raise sa_exc.ArgumentError( "Wildcard token cannot be followed by " "another entity", ) if lead_element is None: lead_element = _WildcardLoad() lead_element = meth(lead_element, _DEFAULT_TOKEN, **kw) else: raise sa_exc.ArgumentError( "Strings are not accepted for attribute names in " "loader options; please use class-bound " "attributes directly.", ) else: if lead_element is None: _, lead_entity, _ = _parse_attr_argument(attr) lead_element = Load(lead_entity) if is_default: if not chained: lead_element = lead_element.defaultload(attr) else: lead_element = meth( lead_element, attr, _is_chain=True, **kw ) else: lead_element = meth(lead_element, attr, **kw) assert lead_element return lead_element def _parse_attr_argument( attr: _AttrType, ) -> Tuple[InspectionAttr, _InternalEntityType[Any], MapperProperty[Any]]: """parse an attribute or wildcard argument to produce an :class:`._AbstractLoad` instance. This is used by the standalone loader strategy functions like ``joinedload()``, ``defer()``, etc. to produce :class:`_orm.Load` or :class:`._WildcardLoad` objects. """ try: # TODO: need to figure out this None thing being returned by # inspect(), it should not have None as an option in most cases # if at all insp: InspectionAttr = inspect(attr) # type: ignore except sa_exc.NoInspectionAvailable as err: raise sa_exc.ArgumentError( "expected ORM mapped attribute for loader strategy argument" ) from err lead_entity: _InternalEntityType[Any] if insp_is_mapper_property(insp): lead_entity = insp.parent prop = insp elif insp_is_attribute(insp): lead_entity = insp.parent prop = insp.prop else: raise sa_exc.ArgumentError( "expected ORM mapped attribute for loader strategy argument" ) return insp, lead_entity, prop def loader_unbound_fn(fn: _FN) -> _FN: """decorator that applies docstrings between standalone loader functions and the loader methods on :class:`._AbstractLoad`. """ bound_fn = getattr(_AbstractLoad, fn.__name__) fn_doc = bound_fn.__doc__ bound_fn.__doc__ = f"""Produce a new :class:`_orm.Load` object with the :func:`_orm.{fn.__name__}` option applied. See :func:`_orm.{fn.__name__}` for usage examples. """ fn.__doc__ = fn_doc return fn # standalone functions follow. docstrings are filled in # by the ``@loader_unbound_fn`` decorator. @loader_unbound_fn def contains_eager(*keys: _AttrType, **kw: Any) -> _AbstractLoad: return _generate_from_keys(Load.contains_eager, keys, True, kw) @loader_unbound_fn def load_only(*attrs: _AttrType, raiseload: bool = False) -> _AbstractLoad: # TODO: attrs against different classes. we likely have to # add some extra state to Load of some kind _, lead_element, _ = _parse_attr_argument(attrs[0]) return Load(lead_element).load_only(*attrs, raiseload=raiseload) @loader_unbound_fn def joinedload(*keys: _AttrType, **kw: Any) -> _AbstractLoad: return _generate_from_keys(Load.joinedload, keys, False, kw) @loader_unbound_fn def subqueryload(*keys: _AttrType) -> _AbstractLoad: return _generate_from_keys(Load.subqueryload, keys, False, {}) @loader_unbound_fn def selectinload( *keys: _AttrType, recursion_depth: Optional[int] = None ) -> _AbstractLoad: return _generate_from_keys( Load.selectinload, keys, False, {"recursion_depth": recursion_depth} ) @loader_unbound_fn def lazyload(*keys: _AttrType) -> _AbstractLoad: return _generate_from_keys(Load.lazyload, keys, False, {}) @loader_unbound_fn def immediateload( *keys: _AttrType, recursion_depth: Optional[int] = None ) -> _AbstractLoad: return _generate_from_keys( Load.immediateload, keys, False, {"recursion_depth": recursion_depth} ) @loader_unbound_fn def noload(*keys: _AttrType) -> _AbstractLoad: return _generate_from_keys(Load.noload, keys, False, {}) @loader_unbound_fn def raiseload(*keys: _AttrType, **kw: Any) -> _AbstractLoad: return _generate_from_keys(Load.raiseload, keys, False, kw) @loader_unbound_fn def defaultload(*keys: _AttrType) -> _AbstractLoad: return _generate_from_keys(Load.defaultload, keys, False, {}) @loader_unbound_fn def defer( key: _AttrType, *addl_attrs: _AttrType, raiseload: bool = False ) -> _AbstractLoad: if addl_attrs: util.warn_deprecated( "The *addl_attrs on orm.defer is deprecated. Please use " "method chaining in conjunction with defaultload() to " "indicate a path.", version="1.3", ) if raiseload: kw = {"raiseload": raiseload} else: kw = {} return _generate_from_keys(Load.defer, (key,) + addl_attrs, False, kw) @loader_unbound_fn def undefer(key: _AttrType, *addl_attrs: _AttrType) -> _AbstractLoad: if addl_attrs: util.warn_deprecated( "The *addl_attrs on orm.undefer is deprecated. Please use " "method chaining in conjunction with defaultload() to " "indicate a path.", version="1.3", ) return _generate_from_keys(Load.undefer, (key,) + addl_attrs, False, {}) @loader_unbound_fn def undefer_group(name: str) -> _AbstractLoad: element = _WildcardLoad() return element.undefer_group(name) @loader_unbound_fn def with_expression( key: _AttrType, expression: _ColumnExpressionArgument[Any] ) -> _AbstractLoad: return _generate_from_keys( Load.with_expression, (key,), False, {"expression": expression} ) @loader_unbound_fn def selectin_polymorphic( base_cls: _EntityType[Any], classes: Iterable[Type[Any]] ) -> _AbstractLoad: ul = Load(base_cls) return ul.selectin_polymorphic(classes) def _raise_for_does_not_link(path, attrname, parent_entity): if len(path) > 1: path_is_of_type = path[-1].entity is not path[-2].mapper.class_ if insp_is_aliased_class(parent_entity): parent_entity_str = str(parent_entity) else: parent_entity_str = parent_entity.class_.__name__ raise sa_exc.ArgumentError( f'ORM mapped entity or attribute "{attrname}" does not ' f'link from relationship "{path[-2]}%s".%s' % ( f".of_type({path[-1]})" if path_is_of_type else "", ( " Did you mean to use " f'"{path[-2]}' f'.of_type({parent_entity_str})" or "loadopt.options(' f"selectin_polymorphic({path[-2].mapper.class_.__name__}, " f'[{parent_entity_str}]), ...)" ?' if not path_is_of_type and not path[-1].is_aliased_class and orm_util._entity_corresponds_to( path.entity, inspect(parent_entity).mapper ) else "" ), ) ) else: raise sa_exc.ArgumentError( f'ORM mapped attribute "{attrname}" does not ' f'link mapped class "{path[-1]}"' ) sqlalchemy/orm/scoping.py 0000755 00000231410 15125143220 0011516 0 ustar 00 # orm/scoping.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php from __future__ import annotations from typing import Any from typing import Callable from typing import Dict from typing import Generic from typing import Iterable from typing import Iterator from typing import Optional from typing import overload from typing import Sequence from typing import Tuple from typing import Type from typing import TYPE_CHECKING from typing import TypeVar from typing import Union from .session import _S from .session import Session from .. import exc as sa_exc from .. import util from ..util import create_proxy_methods from ..util import ScopedRegistry from ..util import ThreadLocalRegistry from ..util import warn from ..util import warn_deprecated from ..util.typing import Protocol if TYPE_CHECKING: from ._typing import _EntityType from ._typing import _IdentityKeyType from ._typing import OrmExecuteOptionsParameter from .identity import IdentityMap from .interfaces import ORMOption from .mapper import Mapper from .query import Query from .query import RowReturningQuery from .session import _BindArguments from .session import _EntityBindKey from .session import _PKIdentityArgument from .session import _SessionBind from .session import sessionmaker from .session import SessionTransaction from ..engine import Connection from ..engine import CursorResult from ..engine import Engine from ..engine import Result from ..engine import Row from ..engine import RowMapping from ..engine.interfaces import _CoreAnyExecuteParams from ..engine.interfaces import _CoreSingleExecuteParams from ..engine.interfaces import CoreExecuteOptionsParameter from ..engine.result import ScalarResult from ..sql._typing import _ColumnsClauseArgument from ..sql._typing import _T0 from ..sql._typing import _T1 from ..sql._typing import _T2 from ..sql._typing import _T3 from ..sql._typing import _T4 from ..sql._typing import _T5 from ..sql._typing import _T6 from ..sql._typing import _T7 from ..sql._typing import _TypedColumnClauseArgument as _TCCA from ..sql.base import Executable from ..sql.dml import UpdateBase from ..sql.elements import ClauseElement from ..sql.roles import TypedColumnsClauseRole from ..sql.selectable import ForUpdateParameter from ..sql.selectable import TypedReturnsRows _T = TypeVar("_T", bound=Any) class QueryPropertyDescriptor(Protocol): """Describes the type applied to a class-level :meth:`_orm.scoped_session.query_property` attribute. .. versionadded:: 2.0.5 """ def __get__(self, instance: Any, owner: Type[_T]) -> Query[_T]: ... _O = TypeVar("_O", bound=object) __all__ = ["scoped_session"] @create_proxy_methods( Session, ":class:`_orm.Session`", ":class:`_orm.scoping.scoped_session`", classmethods=["close_all", "object_session", "identity_key"], methods=[ "__contains__", "__iter__", "add", "add_all", "begin", "begin_nested", "close", "reset", "commit", "connection", "delete", "execute", "expire", "expire_all", "expunge", "expunge_all", "flush", "get", "get_one", "get_bind", "is_modified", "bulk_save_objects", "bulk_insert_mappings", "bulk_update_mappings", "merge", "query", "refresh", "rollback", "scalar", "scalars", ], attributes=[ "bind", "dirty", "deleted", "new", "identity_map", "is_active", "autoflush", "no_autoflush", "info", ], ) class scoped_session(Generic[_S]): """Provides scoped management of :class:`.Session` objects. See :ref:`unitofwork_contextual` for a tutorial. .. note:: When using :ref:`asyncio_toplevel`, the async-compatible :class:`_asyncio.async_scoped_session` class should be used in place of :class:`.scoped_session`. """ _support_async: bool = False session_factory: sessionmaker[_S] """The `session_factory` provided to `__init__` is stored in this attribute and may be accessed at a later time. This can be useful when a new non-scoped :class:`.Session` is needed.""" registry: ScopedRegistry[_S] def __init__( self, session_factory: sessionmaker[_S], scopefunc: Optional[Callable[[], Any]] = None, ): """Construct a new :class:`.scoped_session`. :param session_factory: a factory to create new :class:`.Session` instances. This is usually, but not necessarily, an instance of :class:`.sessionmaker`. :param scopefunc: optional function which defines the current scope. If not passed, the :class:`.scoped_session` object assumes "thread-local" scope, and will use a Python ``threading.local()`` in order to maintain the current :class:`.Session`. If passed, the function should return a hashable token; this token will be used as the key in a dictionary in order to store and retrieve the current :class:`.Session`. """ self.session_factory = session_factory if scopefunc: self.registry = ScopedRegistry(session_factory, scopefunc) else: self.registry = ThreadLocalRegistry(session_factory) @property def _proxied(self) -> _S: return self.registry() def __call__(self, **kw: Any) -> _S: r"""Return the current :class:`.Session`, creating it using the :attr:`.scoped_session.session_factory` if not present. :param \**kw: Keyword arguments will be passed to the :attr:`.scoped_session.session_factory` callable, if an existing :class:`.Session` is not present. If the :class:`.Session` is present and keyword arguments have been passed, :exc:`~sqlalchemy.exc.InvalidRequestError` is raised. """ if kw: if self.registry.has(): raise sa_exc.InvalidRequestError( "Scoped session is already present; " "no new arguments may be specified." ) else: sess = self.session_factory(**kw) self.registry.set(sess) else: sess = self.registry() if not self._support_async and sess._is_asyncio: warn_deprecated( "Using `scoped_session` with asyncio is deprecated and " "will raise an error in a future version. " "Please use `async_scoped_session` instead.", "1.4.23", ) return sess def configure(self, **kwargs: Any) -> None: """reconfigure the :class:`.sessionmaker` used by this :class:`.scoped_session`. See :meth:`.sessionmaker.configure`. """ if self.registry.has(): warn( "At least one scoped session is already present. " " configure() can not affect sessions that have " "already been created." ) self.session_factory.configure(**kwargs) def remove(self) -> None: """Dispose of the current :class:`.Session`, if present. This will first call :meth:`.Session.close` method on the current :class:`.Session`, which releases any existing transactional/connection resources still being held; transactions specifically are rolled back. The :class:`.Session` is then discarded. Upon next usage within the same scope, the :class:`.scoped_session` will produce a new :class:`.Session` object. """ if self.registry.has(): self.registry().close() self.registry.clear() def query_property( self, query_cls: Optional[Type[Query[_T]]] = None ) -> QueryPropertyDescriptor: """return a class property which produces a legacy :class:`_query.Query` object against the class and the current :class:`.Session` when called. .. legacy:: The :meth:`_orm.scoped_session.query_property` accessor is specific to the legacy :class:`.Query` object and is not considered to be part of :term:`2.0-style` ORM use. e.g.:: from sqlalchemy.orm import QueryPropertyDescriptor from sqlalchemy.orm import scoped_session from sqlalchemy.orm import sessionmaker Session = scoped_session(sessionmaker()) class MyClass: query: QueryPropertyDescriptor = Session.query_property() # after mappers are defined result = MyClass.query.filter(MyClass.name == "foo").all() Produces instances of the session's configured query class by default. To override and use a custom implementation, provide a ``query_cls`` callable. The callable will be invoked with the class's mapper as a positional argument and a session keyword argument. There is no limit to the number of query properties placed on a class. """ class query: def __get__(s, instance: Any, owner: Type[_O]) -> Query[_O]: if query_cls: # custom query class return query_cls(owner, session=self.registry()) # type: ignore # noqa: E501 else: # session's configured query class return self.registry().query(owner) return query() # START PROXY METHODS scoped_session # code within this block is **programmatically, # statically generated** by tools/generate_proxy_methods.py def __contains__(self, instance: object) -> bool: r"""Return True if the instance is associated with this session. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. The instance may be pending or persistent within the Session for a result of True. """ # noqa: E501 return self._proxied.__contains__(instance) def __iter__(self) -> Iterator[object]: r"""Iterate over all pending or persistent instances within this Session. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. """ # noqa: E501 return self._proxied.__iter__() def add(self, instance: object, _warn: bool = True) -> None: r"""Place an object into this :class:`_orm.Session`. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. Objects that are in the :term:`transient` state when passed to the :meth:`_orm.Session.add` method will move to the :term:`pending` state, until the next flush, at which point they will move to the :term:`persistent` state. Objects that are in the :term:`detached` state when passed to the :meth:`_orm.Session.add` method will move to the :term:`persistent` state directly. If the transaction used by the :class:`_orm.Session` is rolled back, objects which were transient when they were passed to :meth:`_orm.Session.add` will be moved back to the :term:`transient` state, and will no longer be present within this :class:`_orm.Session`. .. seealso:: :meth:`_orm.Session.add_all` :ref:`session_adding` - at :ref:`session_basics` """ # noqa: E501 return self._proxied.add(instance, _warn=_warn) def add_all(self, instances: Iterable[object]) -> None: r"""Add the given collection of instances to this :class:`_orm.Session`. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. See the documentation for :meth:`_orm.Session.add` for a general behavioral description. .. seealso:: :meth:`_orm.Session.add` :ref:`session_adding` - at :ref:`session_basics` """ # noqa: E501 return self._proxied.add_all(instances) def begin(self, nested: bool = False) -> SessionTransaction: r"""Begin a transaction, or nested transaction, on this :class:`.Session`, if one is not already begun. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. The :class:`_orm.Session` object features **autobegin** behavior, so that normally it is not necessary to call the :meth:`_orm.Session.begin` method explicitly. However, it may be used in order to control the scope of when the transactional state is begun. When used to begin the outermost transaction, an error is raised if this :class:`.Session` is already inside of a transaction. :param nested: if True, begins a SAVEPOINT transaction and is equivalent to calling :meth:`~.Session.begin_nested`. For documentation on SAVEPOINT transactions, please see :ref:`session_begin_nested`. :return: the :class:`.SessionTransaction` object. Note that :class:`.SessionTransaction` acts as a Python context manager, allowing :meth:`.Session.begin` to be used in a "with" block. See :ref:`session_explicit_begin` for an example. .. seealso:: :ref:`session_autobegin` :ref:`unitofwork_transaction` :meth:`.Session.begin_nested` """ # noqa: E501 return self._proxied.begin(nested=nested) def begin_nested(self) -> SessionTransaction: r"""Begin a "nested" transaction on this Session, e.g. SAVEPOINT. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. The target database(s) and associated drivers must support SQL SAVEPOINT for this method to function correctly. For documentation on SAVEPOINT transactions, please see :ref:`session_begin_nested`. :return: the :class:`.SessionTransaction` object. Note that :class:`.SessionTransaction` acts as a context manager, allowing :meth:`.Session.begin_nested` to be used in a "with" block. See :ref:`session_begin_nested` for a usage example. .. seealso:: :ref:`session_begin_nested` :ref:`pysqlite_serializable` - special workarounds required with the SQLite driver in order for SAVEPOINT to work correctly. For asyncio use cases, see the section :ref:`aiosqlite_serializable`. """ # noqa: E501 return self._proxied.begin_nested() def close(self) -> None: r"""Close out the transactional resources and ORM objects used by this :class:`_orm.Session`. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. This expunges all ORM objects associated with this :class:`_orm.Session`, ends any transaction in progress and :term:`releases` any :class:`_engine.Connection` objects which this :class:`_orm.Session` itself has checked out from associated :class:`_engine.Engine` objects. The operation then leaves the :class:`_orm.Session` in a state which it may be used again. .. tip:: In the default running mode the :meth:`_orm.Session.close` method **does not prevent the Session from being used again**. The :class:`_orm.Session` itself does not actually have a distinct "closed" state; it merely means the :class:`_orm.Session` will release all database connections and ORM objects. Setting the parameter :paramref:`_orm.Session.close_resets_only` to ``False`` will instead make the ``close`` final, meaning that any further action on the session will be forbidden. .. versionchanged:: 1.4 The :meth:`.Session.close` method does not immediately create a new :class:`.SessionTransaction` object; instead, the new :class:`.SessionTransaction` is created only if the :class:`.Session` is used again for a database operation. .. seealso:: :ref:`session_closing` - detail on the semantics of :meth:`_orm.Session.close` and :meth:`_orm.Session.reset`. :meth:`_orm.Session.reset` - a similar method that behaves like ``close()`` with the parameter :paramref:`_orm.Session.close_resets_only` set to ``True``. """ # noqa: E501 return self._proxied.close() def reset(self) -> None: r"""Close out the transactional resources and ORM objects used by this :class:`_orm.Session`, resetting the session to its initial state. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. This method provides for same "reset-only" behavior that the :meth:`_orm.Session.close` method has provided historically, where the state of the :class:`_orm.Session` is reset as though the object were brand new, and ready to be used again. This method may then be useful for :class:`_orm.Session` objects which set :paramref:`_orm.Session.close_resets_only` to ``False``, so that "reset only" behavior is still available. .. versionadded:: 2.0.22 .. seealso:: :ref:`session_closing` - detail on the semantics of :meth:`_orm.Session.close` and :meth:`_orm.Session.reset`. :meth:`_orm.Session.close` - a similar method will additionally prevent re-use of the Session when the parameter :paramref:`_orm.Session.close_resets_only` is set to ``False``. """ # noqa: E501 return self._proxied.reset() def commit(self) -> None: r"""Flush pending changes and commit the current transaction. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. When the COMMIT operation is complete, all objects are fully :term:`expired`, erasing their internal contents, which will be automatically re-loaded when the objects are next accessed. In the interim, these objects are in an expired state and will not function if they are :term:`detached` from the :class:`.Session`. Additionally, this re-load operation is not supported when using asyncio-oriented APIs. The :paramref:`.Session.expire_on_commit` parameter may be used to disable this behavior. When there is no transaction in place for the :class:`.Session`, indicating that no operations were invoked on this :class:`.Session` since the previous call to :meth:`.Session.commit`, the method will begin and commit an internal-only "logical" transaction, that does not normally affect the database unless pending flush changes were detected, but will still invoke event handlers and object expiration rules. The outermost database transaction is committed unconditionally, automatically releasing any SAVEPOINTs in effect. .. seealso:: :ref:`session_committing` :ref:`unitofwork_transaction` :ref:`asyncio_orm_avoid_lazyloads` """ # noqa: E501 return self._proxied.commit() def connection( self, bind_arguments: Optional[_BindArguments] = None, execution_options: Optional[CoreExecuteOptionsParameter] = None, ) -> Connection: r"""Return a :class:`_engine.Connection` object corresponding to this :class:`.Session` object's transactional state. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. Either the :class:`_engine.Connection` corresponding to the current transaction is returned, or if no transaction is in progress, a new one is begun and the :class:`_engine.Connection` returned (note that no transactional state is established with the DBAPI until the first SQL statement is emitted). Ambiguity in multi-bind or unbound :class:`.Session` objects can be resolved through any of the optional keyword arguments. This ultimately makes usage of the :meth:`.get_bind` method for resolution. :param bind_arguments: dictionary of bind arguments. May include "mapper", "bind", "clause", other custom arguments that are passed to :meth:`.Session.get_bind`. :param execution_options: a dictionary of execution options that will be passed to :meth:`_engine.Connection.execution_options`, **when the connection is first procured only**. If the connection is already present within the :class:`.Session`, a warning is emitted and the arguments are ignored. .. seealso:: :ref:`session_transaction_isolation` """ # noqa: E501 return self._proxied.connection( bind_arguments=bind_arguments, execution_options=execution_options ) def delete(self, instance: object) -> None: r"""Mark an instance as deleted. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. The object is assumed to be either :term:`persistent` or :term:`detached` when passed; after the method is called, the object will remain in the :term:`persistent` state until the next flush proceeds. During this time, the object will also be a member of the :attr:`_orm.Session.deleted` collection. When the next flush proceeds, the object will move to the :term:`deleted` state, indicating a ``DELETE`` statement was emitted for its row within the current transaction. When the transaction is successfully committed, the deleted object is moved to the :term:`detached` state and is no longer present within this :class:`_orm.Session`. .. seealso:: :ref:`session_deleting` - at :ref:`session_basics` """ # noqa: E501 return self._proxied.delete(instance) @overload def execute( self, statement: TypedReturnsRows[_T], params: Optional[_CoreAnyExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, _parent_execute_state: Optional[Any] = None, _add_event: Optional[Any] = None, ) -> Result[_T]: ... @overload def execute( self, statement: UpdateBase, params: Optional[_CoreAnyExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, _parent_execute_state: Optional[Any] = None, _add_event: Optional[Any] = None, ) -> CursorResult[Any]: ... @overload def execute( self, statement: Executable, params: Optional[_CoreAnyExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, _parent_execute_state: Optional[Any] = None, _add_event: Optional[Any] = None, ) -> Result[Any]: ... def execute( self, statement: Executable, params: Optional[_CoreAnyExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, _parent_execute_state: Optional[Any] = None, _add_event: Optional[Any] = None, ) -> Result[Any]: r"""Execute a SQL expression construct. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. Returns a :class:`_engine.Result` object representing results of the statement execution. E.g.:: from sqlalchemy import select result = session.execute(select(User).where(User.id == 5)) The API contract of :meth:`_orm.Session.execute` is similar to that of :meth:`_engine.Connection.execute`, the :term:`2.0 style` version of :class:`_engine.Connection`. .. versionchanged:: 1.4 the :meth:`_orm.Session.execute` method is now the primary point of ORM statement execution when using :term:`2.0 style` ORM usage. :param statement: An executable statement (i.e. an :class:`.Executable` expression such as :func:`_expression.select`). :param params: Optional dictionary, or list of dictionaries, containing bound parameter values. If a single dictionary, single-row execution occurs; if a list of dictionaries, an "executemany" will be invoked. The keys in each dictionary must correspond to parameter names present in the statement. :param execution_options: optional dictionary of execution options, which will be associated with the statement execution. This dictionary can provide a subset of the options that are accepted by :meth:`_engine.Connection.execution_options`, and may also provide additional options understood only in an ORM context. .. seealso:: :ref:`orm_queryguide_execution_options` - ORM-specific execution options :param bind_arguments: dictionary of additional arguments to determine the bind. May include "mapper", "bind", or other custom arguments. Contents of this dictionary are passed to the :meth:`.Session.get_bind` method. :return: a :class:`_engine.Result` object. """ # noqa: E501 return self._proxied.execute( statement, params=params, execution_options=execution_options, bind_arguments=bind_arguments, _parent_execute_state=_parent_execute_state, _add_event=_add_event, ) def expire( self, instance: object, attribute_names: Optional[Iterable[str]] = None ) -> None: r"""Expire the attributes on an instance. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. Marks the attributes of an instance as out of date. When an expired attribute is next accessed, a query will be issued to the :class:`.Session` object's current transactional context in order to load all expired attributes for the given instance. Note that a highly isolated transaction will return the same values as were previously read in that same transaction, regardless of changes in database state outside of that transaction. To expire all objects in the :class:`.Session` simultaneously, use :meth:`Session.expire_all`. The :class:`.Session` object's default behavior is to expire all state whenever the :meth:`Session.rollback` or :meth:`Session.commit` methods are called, so that new state can be loaded for the new transaction. For this reason, calling :meth:`Session.expire` only makes sense for the specific case that a non-ORM SQL statement was emitted in the current transaction. :param instance: The instance to be refreshed. :param attribute_names: optional list of string attribute names indicating a subset of attributes to be expired. .. seealso:: :ref:`session_expire` - introductory material :meth:`.Session.expire` :meth:`.Session.refresh` :meth:`_orm.Query.populate_existing` """ # noqa: E501 return self._proxied.expire(instance, attribute_names=attribute_names) def expire_all(self) -> None: r"""Expires all persistent instances within this Session. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. When any attributes on a persistent instance is next accessed, a query will be issued using the :class:`.Session` object's current transactional context in order to load all expired attributes for the given instance. Note that a highly isolated transaction will return the same values as were previously read in that same transaction, regardless of changes in database state outside of that transaction. To expire individual objects and individual attributes on those objects, use :meth:`Session.expire`. The :class:`.Session` object's default behavior is to expire all state whenever the :meth:`Session.rollback` or :meth:`Session.commit` methods are called, so that new state can be loaded for the new transaction. For this reason, calling :meth:`Session.expire_all` is not usually needed, assuming the transaction is isolated. .. seealso:: :ref:`session_expire` - introductory material :meth:`.Session.expire` :meth:`.Session.refresh` :meth:`_orm.Query.populate_existing` """ # noqa: E501 return self._proxied.expire_all() def expunge(self, instance: object) -> None: r"""Remove the `instance` from this ``Session``. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. This will free all internal references to the instance. Cascading will be applied according to the *expunge* cascade rule. """ # noqa: E501 return self._proxied.expunge(instance) def expunge_all(self) -> None: r"""Remove all object instances from this ``Session``. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. This is equivalent to calling ``expunge(obj)`` on all objects in this ``Session``. """ # noqa: E501 return self._proxied.expunge_all() def flush(self, objects: Optional[Sequence[Any]] = None) -> None: r"""Flush all the object changes to the database. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. Writes out all pending object creations, deletions and modifications to the database as INSERTs, DELETEs, UPDATEs, etc. Operations are automatically ordered by the Session's unit of work dependency solver. Database operations will be issued in the current transactional context and do not affect the state of the transaction, unless an error occurs, in which case the entire transaction is rolled back. You may flush() as often as you like within a transaction to move changes from Python to the database's transaction buffer. :param objects: Optional; restricts the flush operation to operate only on elements that are in the given collection. This feature is for an extremely narrow set of use cases where particular objects may need to be operated upon before the full flush() occurs. It is not intended for general use. """ # noqa: E501 return self._proxied.flush(objects=objects) def get( self, entity: _EntityBindKey[_O], ident: _PKIdentityArgument, *, options: Optional[Sequence[ORMOption]] = None, populate_existing: bool = False, with_for_update: ForUpdateParameter = None, identity_token: Optional[Any] = None, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, ) -> Optional[_O]: r"""Return an instance based on the given primary key identifier, or ``None`` if not found. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. E.g.:: my_user = session.get(User, 5) some_object = session.get(VersionedFoo, (5, 10)) some_object = session.get(VersionedFoo, {"id": 5, "version_id": 10}) .. versionadded:: 1.4 Added :meth:`_orm.Session.get`, which is moved from the now legacy :meth:`_orm.Query.get` method. :meth:`_orm.Session.get` is special in that it provides direct access to the identity map of the :class:`.Session`. If the given primary key identifier is present in the local identity map, the object is returned directly from this collection and no SQL is emitted, unless the object has been marked fully expired. If not present, a SELECT is performed in order to locate the object. :meth:`_orm.Session.get` also will perform a check if the object is present in the identity map and marked as expired - a SELECT is emitted to refresh the object as well as to ensure that the row is still present. If not, :class:`~sqlalchemy.orm.exc.ObjectDeletedError` is raised. :param entity: a mapped class or :class:`.Mapper` indicating the type of entity to be loaded. :param ident: A scalar, tuple, or dictionary representing the primary key. For a composite (e.g. multiple column) primary key, a tuple or dictionary should be passed. For a single-column primary key, the scalar calling form is typically the most expedient. If the primary key of a row is the value "5", the call looks like:: my_object = session.get(SomeClass, 5) The tuple form contains primary key values typically in the order in which they correspond to the mapped :class:`_schema.Table` object's primary key columns, or if the :paramref:`_orm.Mapper.primary_key` configuration parameter were used, in the order used for that parameter. For example, if the primary key of a row is represented by the integer digits "5, 10" the call would look like:: my_object = session.get(SomeClass, (5, 10)) The dictionary form should include as keys the mapped attribute names corresponding to each element of the primary key. If the mapped class has the attributes ``id``, ``version_id`` as the attributes which store the object's primary key value, the call would look like:: my_object = session.get(SomeClass, {"id": 5, "version_id": 10}) :param options: optional sequence of loader options which will be applied to the query, if one is emitted. :param populate_existing: causes the method to unconditionally emit a SQL query and refresh the object with the newly loaded data, regardless of whether or not the object is already present. :param with_for_update: optional boolean ``True`` indicating FOR UPDATE should be used, or may be a dictionary containing flags to indicate a more specific set of FOR UPDATE flags for the SELECT; flags should match the parameters of :meth:`_query.Query.with_for_update`. Supersedes the :paramref:`.Session.refresh.lockmode` parameter. :param execution_options: optional dictionary of execution options, which will be associated with the query execution if one is emitted. This dictionary can provide a subset of the options that are accepted by :meth:`_engine.Connection.execution_options`, and may also provide additional options understood only in an ORM context. .. versionadded:: 1.4.29 .. seealso:: :ref:`orm_queryguide_execution_options` - ORM-specific execution options :param bind_arguments: dictionary of additional arguments to determine the bind. May include "mapper", "bind", or other custom arguments. Contents of this dictionary are passed to the :meth:`.Session.get_bind` method. .. versionadded: 2.0.0rc1 :return: The object instance, or ``None``. """ # noqa: E501 return self._proxied.get( entity, ident, options=options, populate_existing=populate_existing, with_for_update=with_for_update, identity_token=identity_token, execution_options=execution_options, bind_arguments=bind_arguments, ) def get_one( self, entity: _EntityBindKey[_O], ident: _PKIdentityArgument, *, options: Optional[Sequence[ORMOption]] = None, populate_existing: bool = False, with_for_update: ForUpdateParameter = None, identity_token: Optional[Any] = None, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, ) -> _O: r"""Return exactly one instance based on the given primary key identifier, or raise an exception if not found. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. Raises :class:`_exc.NoResultFound` if the query selects no rows. For a detailed documentation of the arguments see the method :meth:`.Session.get`. .. versionadded:: 2.0.22 :return: The object instance. .. seealso:: :meth:`.Session.get` - equivalent method that instead returns ``None`` if no row was found with the provided primary key """ # noqa: E501 return self._proxied.get_one( entity, ident, options=options, populate_existing=populate_existing, with_for_update=with_for_update, identity_token=identity_token, execution_options=execution_options, bind_arguments=bind_arguments, ) def get_bind( self, mapper: Optional[_EntityBindKey[_O]] = None, *, clause: Optional[ClauseElement] = None, bind: Optional[_SessionBind] = None, _sa_skip_events: Optional[bool] = None, _sa_skip_for_implicit_returning: bool = False, **kw: Any, ) -> Union[Engine, Connection]: r"""Return a "bind" to which this :class:`.Session` is bound. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. The "bind" is usually an instance of :class:`_engine.Engine`, except in the case where the :class:`.Session` has been explicitly bound directly to a :class:`_engine.Connection`. For a multiply-bound or unbound :class:`.Session`, the ``mapper`` or ``clause`` arguments are used to determine the appropriate bind to return. Note that the "mapper" argument is usually present when :meth:`.Session.get_bind` is called via an ORM operation such as a :meth:`.Session.query`, each individual INSERT/UPDATE/DELETE operation within a :meth:`.Session.flush`, call, etc. The order of resolution is: 1. if mapper given and :paramref:`.Session.binds` is present, locate a bind based first on the mapper in use, then on the mapped class in use, then on any base classes that are present in the ``__mro__`` of the mapped class, from more specific superclasses to more general. 2. if clause given and ``Session.binds`` is present, locate a bind based on :class:`_schema.Table` objects found in the given clause present in ``Session.binds``. 3. if ``Session.binds`` is present, return that. 4. if clause given, attempt to return a bind linked to the :class:`_schema.MetaData` ultimately associated with the clause. 5. if mapper given, attempt to return a bind linked to the :class:`_schema.MetaData` ultimately associated with the :class:`_schema.Table` or other selectable to which the mapper is mapped. 6. No bind can be found, :exc:`~sqlalchemy.exc.UnboundExecutionError` is raised. Note that the :meth:`.Session.get_bind` method can be overridden on a user-defined subclass of :class:`.Session` to provide any kind of bind resolution scheme. See the example at :ref:`session_custom_partitioning`. :param mapper: Optional mapped class or corresponding :class:`_orm.Mapper` instance. The bind can be derived from a :class:`_orm.Mapper` first by consulting the "binds" map associated with this :class:`.Session`, and secondly by consulting the :class:`_schema.MetaData` associated with the :class:`_schema.Table` to which the :class:`_orm.Mapper` is mapped for a bind. :param clause: A :class:`_expression.ClauseElement` (i.e. :func:`_expression.select`, :func:`_expression.text`, etc.). If the ``mapper`` argument is not present or could not produce a bind, the given expression construct will be searched for a bound element, typically a :class:`_schema.Table` associated with bound :class:`_schema.MetaData`. .. seealso:: :ref:`session_partitioning` :paramref:`.Session.binds` :meth:`.Session.bind_mapper` :meth:`.Session.bind_table` """ # noqa: E501 return self._proxied.get_bind( mapper=mapper, clause=clause, bind=bind, _sa_skip_events=_sa_skip_events, _sa_skip_for_implicit_returning=_sa_skip_for_implicit_returning, **kw, ) def is_modified( self, instance: object, include_collections: bool = True ) -> bool: r"""Return ``True`` if the given instance has locally modified attributes. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. This method retrieves the history for each instrumented attribute on the instance and performs a comparison of the current value to its previously flushed or committed value, if any. It is in effect a more expensive and accurate version of checking for the given instance in the :attr:`.Session.dirty` collection; a full test for each attribute's net "dirty" status is performed. E.g.:: return session.is_modified(someobject) A few caveats to this method apply: * Instances present in the :attr:`.Session.dirty` collection may report ``False`` when tested with this method. This is because the object may have received change events via attribute mutation, thus placing it in :attr:`.Session.dirty`, but ultimately the state is the same as that loaded from the database, resulting in no net change here. * Scalar attributes may not have recorded the previously set value when a new value was applied, if the attribute was not loaded, or was expired, at the time the new value was received - in these cases, the attribute is assumed to have a change, even if there is ultimately no net change against its database value. SQLAlchemy in most cases does not need the "old" value when a set event occurs, so it skips the expense of a SQL call if the old value isn't present, based on the assumption that an UPDATE of the scalar value is usually needed, and in those few cases where it isn't, is less expensive on average than issuing a defensive SELECT. The "old" value is fetched unconditionally upon set only if the attribute container has the ``active_history`` flag set to ``True``. This flag is set typically for primary key attributes and scalar object references that are not a simple many-to-one. To set this flag for any arbitrary mapped column, use the ``active_history`` argument with :func:`.column_property`. :param instance: mapped instance to be tested for pending changes. :param include_collections: Indicates if multivalued collections should be included in the operation. Setting this to ``False`` is a way to detect only local-column based properties (i.e. scalar columns or many-to-one foreign keys) that would result in an UPDATE for this instance upon flush. """ # noqa: E501 return self._proxied.is_modified( instance, include_collections=include_collections ) def bulk_save_objects( self, objects: Iterable[object], return_defaults: bool = False, update_changed_only: bool = True, preserve_order: bool = True, ) -> None: r"""Perform a bulk save of the given list of objects. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. .. legacy:: This method is a legacy feature as of the 2.0 series of SQLAlchemy. For modern bulk INSERT and UPDATE, see the sections :ref:`orm_queryguide_bulk_insert` and :ref:`orm_queryguide_bulk_update`. For general INSERT and UPDATE of existing ORM mapped objects, prefer standard :term:`unit of work` data management patterns, introduced in the :ref:`unified_tutorial` at :ref:`tutorial_orm_data_manipulation`. SQLAlchemy 2.0 now uses :ref:`engine_insertmanyvalues` with modern dialects which solves previous issues of bulk INSERT slowness. :param objects: a sequence of mapped object instances. The mapped objects are persisted as is, and are **not** associated with the :class:`.Session` afterwards. For each object, whether the object is sent as an INSERT or an UPDATE is dependent on the same rules used by the :class:`.Session` in traditional operation; if the object has the :attr:`.InstanceState.key` attribute set, then the object is assumed to be "detached" and will result in an UPDATE. Otherwise, an INSERT is used. In the case of an UPDATE, statements are grouped based on which attributes have changed, and are thus to be the subject of each SET clause. If ``update_changed_only`` is False, then all attributes present within each object are applied to the UPDATE statement, which may help in allowing the statements to be grouped together into a larger executemany(), and will also reduce the overhead of checking history on attributes. :param return_defaults: when True, rows that are missing values which generate defaults, namely integer primary key defaults and sequences, will be inserted **one at a time**, so that the primary key value is available. In particular this will allow joined-inheritance and other multi-table mappings to insert correctly without the need to provide primary key values ahead of time; however, :paramref:`.Session.bulk_save_objects.return_defaults` **greatly reduces the performance gains** of the method overall. It is strongly advised to please use the standard :meth:`_orm.Session.add_all` approach. :param update_changed_only: when True, UPDATE statements are rendered based on those attributes in each state that have logged changes. When False, all attributes present are rendered into the SET clause with the exception of primary key attributes. :param preserve_order: when True, the order of inserts and updates matches exactly the order in which the objects are given. When False, common types of objects are grouped into inserts and updates, to allow for more batching opportunities. .. seealso:: :doc:`queryguide/dml` :meth:`.Session.bulk_insert_mappings` :meth:`.Session.bulk_update_mappings` """ # noqa: E501 return self._proxied.bulk_save_objects( objects, return_defaults=return_defaults, update_changed_only=update_changed_only, preserve_order=preserve_order, ) def bulk_insert_mappings( self, mapper: Mapper[Any], mappings: Iterable[Dict[str, Any]], return_defaults: bool = False, render_nulls: bool = False, ) -> None: r"""Perform a bulk insert of the given list of mapping dictionaries. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. .. legacy:: This method is a legacy feature as of the 2.0 series of SQLAlchemy. For modern bulk INSERT and UPDATE, see the sections :ref:`orm_queryguide_bulk_insert` and :ref:`orm_queryguide_bulk_update`. The 2.0 API shares implementation details with this method and adds new features as well. :param mapper: a mapped class, or the actual :class:`_orm.Mapper` object, representing the single kind of object represented within the mapping list. :param mappings: a sequence of dictionaries, each one containing the state of the mapped row to be inserted, in terms of the attribute names on the mapped class. If the mapping refers to multiple tables, such as a joined-inheritance mapping, each dictionary must contain all keys to be populated into all tables. :param return_defaults: when True, the INSERT process will be altered to ensure that newly generated primary key values will be fetched. The rationale for this parameter is typically to enable :ref:`Joined Table Inheritance <joined_inheritance>` mappings to be bulk inserted. .. note:: for backends that don't support RETURNING, the :paramref:`_orm.Session.bulk_insert_mappings.return_defaults` parameter can significantly decrease performance as INSERT statements can no longer be batched. See :ref:`engine_insertmanyvalues` for background on which backends are affected. :param render_nulls: When True, a value of ``None`` will result in a NULL value being included in the INSERT statement, rather than the column being omitted from the INSERT. This allows all the rows being INSERTed to have the identical set of columns which allows the full set of rows to be batched to the DBAPI. Normally, each column-set that contains a different combination of NULL values than the previous row must omit a different series of columns from the rendered INSERT statement, which means it must be emitted as a separate statement. By passing this flag, the full set of rows are guaranteed to be batchable into one batch; the cost however is that server-side defaults which are invoked by an omitted column will be skipped, so care must be taken to ensure that these are not necessary. .. warning:: When this flag is set, **server side default SQL values will not be invoked** for those columns that are inserted as NULL; the NULL value will be sent explicitly. Care must be taken to ensure that no server-side default functions need to be invoked for the operation as a whole. .. seealso:: :doc:`queryguide/dml` :meth:`.Session.bulk_save_objects` :meth:`.Session.bulk_update_mappings` """ # noqa: E501 return self._proxied.bulk_insert_mappings( mapper, mappings, return_defaults=return_defaults, render_nulls=render_nulls, ) def bulk_update_mappings( self, mapper: Mapper[Any], mappings: Iterable[Dict[str, Any]] ) -> None: r"""Perform a bulk update of the given list of mapping dictionaries. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. .. legacy:: This method is a legacy feature as of the 2.0 series of SQLAlchemy. For modern bulk INSERT and UPDATE, see the sections :ref:`orm_queryguide_bulk_insert` and :ref:`orm_queryguide_bulk_update`. The 2.0 API shares implementation details with this method and adds new features as well. :param mapper: a mapped class, or the actual :class:`_orm.Mapper` object, representing the single kind of object represented within the mapping list. :param mappings: a sequence of dictionaries, each one containing the state of the mapped row to be updated, in terms of the attribute names on the mapped class. If the mapping refers to multiple tables, such as a joined-inheritance mapping, each dictionary may contain keys corresponding to all tables. All those keys which are present and are not part of the primary key are applied to the SET clause of the UPDATE statement; the primary key values, which are required, are applied to the WHERE clause. .. seealso:: :doc:`queryguide/dml` :meth:`.Session.bulk_insert_mappings` :meth:`.Session.bulk_save_objects` """ # noqa: E501 return self._proxied.bulk_update_mappings(mapper, mappings) def merge( self, instance: _O, *, load: bool = True, options: Optional[Sequence[ORMOption]] = None, ) -> _O: r"""Copy the state of a given instance into a corresponding instance within this :class:`.Session`. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. :meth:`.Session.merge` examines the primary key attributes of the source instance, and attempts to reconcile it with an instance of the same primary key in the session. If not found locally, it attempts to load the object from the database based on primary key, and if none can be located, creates a new instance. The state of each attribute on the source instance is then copied to the target instance. The resulting target instance is then returned by the method; the original source instance is left unmodified, and un-associated with the :class:`.Session` if not already. This operation cascades to associated instances if the association is mapped with ``cascade="merge"``. See :ref:`unitofwork_merging` for a detailed discussion of merging. :param instance: Instance to be merged. :param load: Boolean, when False, :meth:`.merge` switches into a "high performance" mode which causes it to forego emitting history events as well as all database access. This flag is used for cases such as transferring graphs of objects into a :class:`.Session` from a second level cache, or to transfer just-loaded objects into the :class:`.Session` owned by a worker thread or process without re-querying the database. The ``load=False`` use case adds the caveat that the given object has to be in a "clean" state, that is, has no pending changes to be flushed - even if the incoming object is detached from any :class:`.Session`. This is so that when the merge operation populates local attributes and cascades to related objects and collections, the values can be "stamped" onto the target object as is, without generating any history or attribute events, and without the need to reconcile the incoming data with any existing related objects or collections that might not be loaded. The resulting objects from ``load=False`` are always produced as "clean", so it is only appropriate that the given objects should be "clean" as well, else this suggests a mis-use of the method. :param options: optional sequence of loader options which will be applied to the :meth:`_orm.Session.get` method when the merge operation loads the existing version of the object from the database. .. versionadded:: 1.4.24 .. seealso:: :func:`.make_transient_to_detached` - provides for an alternative means of "merging" a single object into the :class:`.Session` """ # noqa: E501 return self._proxied.merge(instance, load=load, options=options) @overload def query(self, _entity: _EntityType[_O]) -> Query[_O]: ... @overload def query( self, _colexpr: TypedColumnsClauseRole[_T] ) -> RowReturningQuery[Tuple[_T]]: ... # START OVERLOADED FUNCTIONS self.query RowReturningQuery 2-8 # code within this block is **programmatically, # statically generated** by tools/generate_tuple_map_overloads.py @overload def query( self, __ent0: _TCCA[_T0], __ent1: _TCCA[_T1] ) -> RowReturningQuery[Tuple[_T0, _T1]]: ... @overload def query( self, __ent0: _TCCA[_T0], __ent1: _TCCA[_T1], __ent2: _TCCA[_T2] ) -> RowReturningQuery[Tuple[_T0, _T1, _T2]]: ... @overload def query( self, __ent0: _TCCA[_T0], __ent1: _TCCA[_T1], __ent2: _TCCA[_T2], __ent3: _TCCA[_T3], ) -> RowReturningQuery[Tuple[_T0, _T1, _T2, _T3]]: ... @overload def query( self, __ent0: _TCCA[_T0], __ent1: _TCCA[_T1], __ent2: _TCCA[_T2], __ent3: _TCCA[_T3], __ent4: _TCCA[_T4], ) -> RowReturningQuery[Tuple[_T0, _T1, _T2, _T3, _T4]]: ... @overload def query( self, __ent0: _TCCA[_T0], __ent1: _TCCA[_T1], __ent2: _TCCA[_T2], __ent3: _TCCA[_T3], __ent4: _TCCA[_T4], __ent5: _TCCA[_T5], ) -> RowReturningQuery[Tuple[_T0, _T1, _T2, _T3, _T4, _T5]]: ... @overload def query( self, __ent0: _TCCA[_T0], __ent1: _TCCA[_T1], __ent2: _TCCA[_T2], __ent3: _TCCA[_T3], __ent4: _TCCA[_T4], __ent5: _TCCA[_T5], __ent6: _TCCA[_T6], ) -> RowReturningQuery[Tuple[_T0, _T1, _T2, _T3, _T4, _T5, _T6]]: ... @overload def query( self, __ent0: _TCCA[_T0], __ent1: _TCCA[_T1], __ent2: _TCCA[_T2], __ent3: _TCCA[_T3], __ent4: _TCCA[_T4], __ent5: _TCCA[_T5], __ent6: _TCCA[_T6], __ent7: _TCCA[_T7], ) -> RowReturningQuery[Tuple[_T0, _T1, _T2, _T3, _T4, _T5, _T6, _T7]]: ... # END OVERLOADED FUNCTIONS self.query @overload def query( self, *entities: _ColumnsClauseArgument[Any], **kwargs: Any ) -> Query[Any]: ... def query( self, *entities: _ColumnsClauseArgument[Any], **kwargs: Any ) -> Query[Any]: r"""Return a new :class:`_query.Query` object corresponding to this :class:`_orm.Session`. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. Note that the :class:`_query.Query` object is legacy as of SQLAlchemy 2.0; the :func:`_sql.select` construct is now used to construct ORM queries. .. seealso:: :ref:`unified_tutorial` :ref:`queryguide_toplevel` :ref:`query_api_toplevel` - legacy API doc """ # noqa: E501 return self._proxied.query(*entities, **kwargs) def refresh( self, instance: object, attribute_names: Optional[Iterable[str]] = None, with_for_update: ForUpdateParameter = None, ) -> None: r"""Expire and refresh attributes on the given instance. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. The selected attributes will first be expired as they would when using :meth:`_orm.Session.expire`; then a SELECT statement will be issued to the database to refresh column-oriented attributes with the current value available in the current transaction. :func:`_orm.relationship` oriented attributes will also be immediately loaded if they were already eagerly loaded on the object, using the same eager loading strategy that they were loaded with originally. .. versionadded:: 1.4 - the :meth:`_orm.Session.refresh` method can also refresh eagerly loaded attributes. :func:`_orm.relationship` oriented attributes that would normally load using the ``select`` (or "lazy") loader strategy will also load **if they are named explicitly in the attribute_names collection**, emitting a SELECT statement for the attribute using the ``immediate`` loader strategy. If lazy-loaded relationships are not named in :paramref:`_orm.Session.refresh.attribute_names`, then they remain as "lazy loaded" attributes and are not implicitly refreshed. .. versionchanged:: 2.0.4 The :meth:`_orm.Session.refresh` method will now refresh lazy-loaded :func:`_orm.relationship` oriented attributes for those which are named explicitly in the :paramref:`_orm.Session.refresh.attribute_names` collection. .. tip:: While the :meth:`_orm.Session.refresh` method is capable of refreshing both column and relationship oriented attributes, its primary focus is on refreshing of local column-oriented attributes on a single instance. For more open ended "refresh" functionality, including the ability to refresh the attributes on many objects at once while having explicit control over relationship loader strategies, use the :ref:`populate existing <orm_queryguide_populate_existing>` feature instead. Note that a highly isolated transaction will return the same values as were previously read in that same transaction, regardless of changes in database state outside of that transaction. Refreshing attributes usually only makes sense at the start of a transaction where database rows have not yet been accessed. :param attribute_names: optional. An iterable collection of string attribute names indicating a subset of attributes to be refreshed. :param with_for_update: optional boolean ``True`` indicating FOR UPDATE should be used, or may be a dictionary containing flags to indicate a more specific set of FOR UPDATE flags for the SELECT; flags should match the parameters of :meth:`_query.Query.with_for_update`. Supersedes the :paramref:`.Session.refresh.lockmode` parameter. .. seealso:: :ref:`session_expire` - introductory material :meth:`.Session.expire` :meth:`.Session.expire_all` :ref:`orm_queryguide_populate_existing` - allows any ORM query to refresh objects as they would be loaded normally. """ # noqa: E501 return self._proxied.refresh( instance, attribute_names=attribute_names, with_for_update=with_for_update, ) def rollback(self) -> None: r"""Rollback the current transaction in progress. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. If no transaction is in progress, this method is a pass-through. The method always rolls back the topmost database transaction, discarding any nested transactions that may be in progress. .. seealso:: :ref:`session_rollback` :ref:`unitofwork_transaction` """ # noqa: E501 return self._proxied.rollback() @overload def scalar( self, statement: TypedReturnsRows[Tuple[_T]], params: Optional[_CoreSingleExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, **kw: Any, ) -> Optional[_T]: ... @overload def scalar( self, statement: Executable, params: Optional[_CoreSingleExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, **kw: Any, ) -> Any: ... def scalar( self, statement: Executable, params: Optional[_CoreSingleExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, **kw: Any, ) -> Any: r"""Execute a statement and return a scalar result. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. Usage and parameters are the same as that of :meth:`_orm.Session.execute`; the return result is a scalar Python value. """ # noqa: E501 return self._proxied.scalar( statement, params=params, execution_options=execution_options, bind_arguments=bind_arguments, **kw, ) @overload def scalars( self, statement: TypedReturnsRows[Tuple[_T]], params: Optional[_CoreAnyExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, **kw: Any, ) -> ScalarResult[_T]: ... @overload def scalars( self, statement: Executable, params: Optional[_CoreAnyExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, **kw: Any, ) -> ScalarResult[Any]: ... def scalars( self, statement: Executable, params: Optional[_CoreAnyExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, **kw: Any, ) -> ScalarResult[Any]: r"""Execute a statement and return the results as scalars. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. Usage and parameters are the same as that of :meth:`_orm.Session.execute`; the return result is a :class:`_result.ScalarResult` filtering object which will return single elements rather than :class:`_row.Row` objects. :return: a :class:`_result.ScalarResult` object .. versionadded:: 1.4.24 Added :meth:`_orm.Session.scalars` .. versionadded:: 1.4.26 Added :meth:`_orm.scoped_session.scalars` .. seealso:: :ref:`orm_queryguide_select_orm_entities` - contrasts the behavior of :meth:`_orm.Session.execute` to :meth:`_orm.Session.scalars` """ # noqa: E501 return self._proxied.scalars( statement, params=params, execution_options=execution_options, bind_arguments=bind_arguments, **kw, ) @property def bind(self) -> Optional[Union[Engine, Connection]]: r"""Proxy for the :attr:`_orm.Session.bind` attribute on behalf of the :class:`_orm.scoping.scoped_session` class. """ # noqa: E501 return self._proxied.bind @bind.setter def bind(self, attr: Optional[Union[Engine, Connection]]) -> None: self._proxied.bind = attr @property def dirty(self) -> Any: r"""The set of all persistent instances considered dirty. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. E.g.:: some_mapped_object in session.dirty Instances are considered dirty when they were modified but not deleted. Note that this 'dirty' calculation is 'optimistic'; most attribute-setting or collection modification operations will mark an instance as 'dirty' and place it in this set, even if there is no net change to the attribute's value. At flush time, the value of each attribute is compared to its previously saved value, and if there's no net change, no SQL operation will occur (this is a more expensive operation so it's only done at flush time). To check if an instance has actionable net changes to its attributes, use the :meth:`.Session.is_modified` method. """ # noqa: E501 return self._proxied.dirty @property def deleted(self) -> Any: r"""The set of all instances marked as 'deleted' within this ``Session`` .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. """ # noqa: E501 return self._proxied.deleted @property def new(self) -> Any: r"""The set of all instances marked as 'new' within this ``Session``. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. """ # noqa: E501 return self._proxied.new @property def identity_map(self) -> IdentityMap: r"""Proxy for the :attr:`_orm.Session.identity_map` attribute on behalf of the :class:`_orm.scoping.scoped_session` class. """ # noqa: E501 return self._proxied.identity_map @identity_map.setter def identity_map(self, attr: IdentityMap) -> None: self._proxied.identity_map = attr @property def is_active(self) -> Any: r"""True if this :class:`.Session` not in "partial rollback" state. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. .. versionchanged:: 1.4 The :class:`_orm.Session` no longer begins a new transaction immediately, so this attribute will be False when the :class:`_orm.Session` is first instantiated. "partial rollback" state typically indicates that the flush process of the :class:`_orm.Session` has failed, and that the :meth:`_orm.Session.rollback` method must be emitted in order to fully roll back the transaction. If this :class:`_orm.Session` is not in a transaction at all, the :class:`_orm.Session` will autobegin when it is first used, so in this case :attr:`_orm.Session.is_active` will return True. Otherwise, if this :class:`_orm.Session` is within a transaction, and that transaction has not been rolled back internally, the :attr:`_orm.Session.is_active` will also return True. .. seealso:: :ref:`faq_session_rollback` :meth:`_orm.Session.in_transaction` """ # noqa: E501 return self._proxied.is_active @property def autoflush(self) -> bool: r"""Proxy for the :attr:`_orm.Session.autoflush` attribute on behalf of the :class:`_orm.scoping.scoped_session` class. """ # noqa: E501 return self._proxied.autoflush @autoflush.setter def autoflush(self, attr: bool) -> None: self._proxied.autoflush = attr @property def no_autoflush(self) -> Any: r"""Return a context manager that disables autoflush. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. e.g.:: with session.no_autoflush: some_object = SomeClass() session.add(some_object) # won't autoflush some_object.related_thing = session.query(SomeRelated).first() Operations that proceed within the ``with:`` block will not be subject to flushes occurring upon query access. This is useful when initializing a series of objects which involve existing database queries, where the uncompleted object should not yet be flushed. """ # noqa: E501 return self._proxied.no_autoflush @property def info(self) -> Any: r"""A user-modifiable dictionary. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. The initial value of this dictionary can be populated using the ``info`` argument to the :class:`.Session` constructor or :class:`.sessionmaker` constructor or factory methods. The dictionary here is always local to this :class:`.Session` and can be modified independently of all other :class:`.Session` objects. """ # noqa: E501 return self._proxied.info @classmethod def close_all(cls) -> None: r"""Close *all* sessions in memory. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. .. deprecated:: 1.3 The :meth:`.Session.close_all` method is deprecated and will be removed in a future release. Please refer to :func:`.session.close_all_sessions`. """ # noqa: E501 return Session.close_all() @classmethod def object_session(cls, instance: object) -> Optional[Session]: r"""Return the :class:`.Session` to which an object belongs. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. This is an alias of :func:`.object_session`. """ # noqa: E501 return Session.object_session(instance) @classmethod def identity_key( cls, class_: Optional[Type[Any]] = None, ident: Union[Any, Tuple[Any, ...]] = None, *, instance: Optional[Any] = None, row: Optional[Union[Row[Any], RowMapping]] = None, identity_token: Optional[Any] = None, ) -> _IdentityKeyType[Any]: r"""Return an identity key. .. container:: class_bases Proxied for the :class:`_orm.Session` class on behalf of the :class:`_orm.scoping.scoped_session` class. This is an alias of :func:`.util.identity_key`. """ # noqa: E501 return Session.identity_key( class_=class_, ident=ident, instance=instance, row=row, identity_token=identity_token, ) # END PROXY METHODS scoped_session ScopedSession = scoped_session """Old name for backwards compatibility.""" sqlalchemy/orm/_orm_constructors.py 0000755 00000312312 15125143220 0013641 0 ustar 00 # orm/_orm_constructors.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php from __future__ import annotations import typing from typing import Any from typing import Callable from typing import Collection from typing import Iterable from typing import NoReturn from typing import Optional from typing import overload from typing import Type from typing import TYPE_CHECKING from typing import Union from . import mapperlib as mapperlib from ._typing import _O from .descriptor_props import Composite from .descriptor_props import Synonym from .interfaces import _AttributeOptions from .properties import MappedColumn from .properties import MappedSQLExpression from .query import AliasOption from .relationships import _RelationshipArgumentType from .relationships import _RelationshipDeclared from .relationships import _RelationshipSecondaryArgument from .relationships import RelationshipProperty from .session import Session from .util import _ORMJoin from .util import AliasedClass from .util import AliasedInsp from .util import LoaderCriteriaOption from .. import sql from .. import util from ..exc import InvalidRequestError from ..sql._typing import _no_kw from ..sql.base import _NoArg from ..sql.base import SchemaEventTarget from ..sql.schema import _InsertSentinelColumnDefault from ..sql.schema import SchemaConst from ..sql.selectable import FromClause from ..util.typing import Annotated from ..util.typing import Literal if TYPE_CHECKING: from ._typing import _EntityType from ._typing import _ORMColumnExprArgument from .descriptor_props import _CC from .descriptor_props import _CompositeAttrType from .interfaces import PropComparator from .mapper import Mapper from .query import Query from .relationships import _LazyLoadArgumentType from .relationships import _ORMColCollectionArgument from .relationships import _ORMOrderByArgument from .relationships import _RelationshipJoinConditionArgument from .relationships import ORMBackrefArgument from .session import _SessionBind from ..sql._typing import _AutoIncrementType from ..sql._typing import _ColumnExpressionArgument from ..sql._typing import _FromClauseArgument from ..sql._typing import _InfoType from ..sql._typing import _OnClauseArgument from ..sql._typing import _TypeEngineArgument from ..sql.elements import ColumnElement from ..sql.schema import _ServerDefaultArgument from ..sql.schema import _ServerOnUpdateArgument from ..sql.selectable import Alias from ..sql.selectable import Subquery _T = typing.TypeVar("_T") @util.deprecated( "1.4", "The :class:`.AliasOption` object is not necessary " "for entities to be matched up to a query that is established " "via :meth:`.Query.from_statement` and now does nothing.", enable_warnings=False, # AliasOption itself warns ) def contains_alias(alias: Union[Alias, Subquery]) -> AliasOption: r"""Return a :class:`.MapperOption` that will indicate to the :class:`_query.Query` that the main table has been aliased. """ return AliasOption(alias) def mapped_column( __name_pos: Optional[ Union[str, _TypeEngineArgument[Any], SchemaEventTarget] ] = None, __type_pos: Optional[ Union[_TypeEngineArgument[Any], SchemaEventTarget] ] = None, *args: SchemaEventTarget, init: Union[_NoArg, bool] = _NoArg.NO_ARG, repr: Union[_NoArg, bool] = _NoArg.NO_ARG, # noqa: A002 default: Optional[Any] = _NoArg.NO_ARG, default_factory: Union[_NoArg, Callable[[], _T]] = _NoArg.NO_ARG, compare: Union[_NoArg, bool] = _NoArg.NO_ARG, kw_only: Union[_NoArg, bool] = _NoArg.NO_ARG, hash: Union[_NoArg, bool, None] = _NoArg.NO_ARG, # noqa: A002 nullable: Optional[ Union[bool, Literal[SchemaConst.NULL_UNSPECIFIED]] ] = SchemaConst.NULL_UNSPECIFIED, primary_key: Optional[bool] = False, deferred: Union[_NoArg, bool] = _NoArg.NO_ARG, deferred_group: Optional[str] = None, deferred_raiseload: Optional[bool] = None, use_existing_column: bool = False, name: Optional[str] = None, type_: Optional[_TypeEngineArgument[Any]] = None, autoincrement: _AutoIncrementType = "auto", doc: Optional[str] = None, key: Optional[str] = None, index: Optional[bool] = None, unique: Optional[bool] = None, info: Optional[_InfoType] = None, onupdate: Optional[Any] = None, insert_default: Optional[Any] = _NoArg.NO_ARG, server_default: Optional[_ServerDefaultArgument] = None, server_onupdate: Optional[_ServerOnUpdateArgument] = None, active_history: bool = False, quote: Optional[bool] = None, system: bool = False, comment: Optional[str] = None, sort_order: Union[_NoArg, int] = _NoArg.NO_ARG, **kw: Any, ) -> MappedColumn[Any]: r"""declare a new ORM-mapped :class:`_schema.Column` construct for use within :ref:`Declarative Table <orm_declarative_table>` configuration. The :func:`_orm.mapped_column` function provides an ORM-aware and Python-typing-compatible construct which is used with :ref:`declarative <orm_declarative_mapping>` mappings to indicate an attribute that's mapped to a Core :class:`_schema.Column` object. It provides the equivalent feature as mapping an attribute to a :class:`_schema.Column` object directly when using Declarative, specifically when using :ref:`Declarative Table <orm_declarative_table>` configuration. .. versionadded:: 2.0 :func:`_orm.mapped_column` is normally used with explicit typing along with the :class:`_orm.Mapped` annotation type, where it can derive the SQL type and nullability for the column based on what's present within the :class:`_orm.Mapped` annotation. It also may be used without annotations as a drop-in replacement for how :class:`_schema.Column` is used in Declarative mappings in SQLAlchemy 1.x style. For usage examples of :func:`_orm.mapped_column`, see the documentation at :ref:`orm_declarative_table`. .. seealso:: :ref:`orm_declarative_table` - complete documentation :ref:`whatsnew_20_orm_declarative_typing` - migration notes for Declarative mappings using 1.x style mappings :param __name: String name to give to the :class:`_schema.Column`. This is an optional, positional only argument that if present must be the first positional argument passed. If omitted, the attribute name to which the :func:`_orm.mapped_column` is mapped will be used as the SQL column name. :param __type: :class:`_types.TypeEngine` type or instance which will indicate the datatype to be associated with the :class:`_schema.Column`. This is an optional, positional-only argument that if present must immediately follow the ``__name`` parameter if present also, or otherwise be the first positional parameter. If omitted, the ultimate type for the column may be derived either from the annotated type, or if a :class:`_schema.ForeignKey` is present, from the datatype of the referenced column. :param \*args: Additional positional arguments include constructs such as :class:`_schema.ForeignKey`, :class:`_schema.CheckConstraint`, and :class:`_schema.Identity`, which are passed through to the constructed :class:`_schema.Column`. :param nullable: Optional bool, whether the column should be "NULL" or "NOT NULL". If omitted, the nullability is derived from the type annotation based on whether or not ``typing.Optional`` is present. ``nullable`` defaults to ``True`` otherwise for non-primary key columns, and ``False`` for primary key columns. :param primary_key: optional bool, indicates the :class:`_schema.Column` would be part of the table's primary key or not. :param deferred: Optional bool - this keyword argument is consumed by the ORM declarative process, and is not part of the :class:`_schema.Column` itself; instead, it indicates that this column should be "deferred" for loading as though mapped by :func:`_orm.deferred`. .. seealso:: :ref:`orm_queryguide_deferred_declarative` :param deferred_group: Implies :paramref:`_orm.mapped_column.deferred` to ``True``, and set the :paramref:`_orm.deferred.group` parameter. .. seealso:: :ref:`orm_queryguide_deferred_group` :param deferred_raiseload: Implies :paramref:`_orm.mapped_column.deferred` to ``True``, and set the :paramref:`_orm.deferred.raiseload` parameter. .. seealso:: :ref:`orm_queryguide_deferred_raiseload` :param use_existing_column: if True, will attempt to locate the given column name on an inherited superclass (typically single inheriting superclass), and if present, will not produce a new column, mapping to the superclass column as though it were omitted from this class. This is used for mixins that add new columns to an inherited superclass. .. seealso:: :ref:`orm_inheritance_column_conflicts` .. versionadded:: 2.0.0b4 :param default: Passed directly to the :paramref:`_schema.Column.default` parameter if the :paramref:`_orm.mapped_column.insert_default` parameter is not present. Additionally, when used with :ref:`orm_declarative_native_dataclasses`, indicates a default Python value that should be applied to the keyword constructor within the generated ``__init__()`` method. Note that in the case of dataclass generation when :paramref:`_orm.mapped_column.insert_default` is not present, this means the :paramref:`_orm.mapped_column.default` value is used in **two** places, both the ``__init__()`` method as well as the :paramref:`_schema.Column.default` parameter. While this behavior may change in a future release, for the moment this tends to "work out"; a default of ``None`` will mean that the :class:`_schema.Column` gets no default generator, whereas a default that refers to a non-``None`` Python or SQL expression value will be assigned up front on the object when ``__init__()`` is called, which is the same value that the Core :class:`_sql.Insert` construct would use in any case, leading to the same end result. .. note:: When using Core level column defaults that are callables to be interpreted by the underlying :class:`_schema.Column` in conjunction with :ref:`ORM-mapped dataclasses <orm_declarative_native_dataclasses>`, especially those that are :ref:`context-aware default functions <context_default_functions>`, **the** :paramref:`_orm.mapped_column.insert_default` **parameter must be used instead**. This is necessary to disambiguate the callable from being interpreted as a dataclass level default. .. seealso:: :ref:`defaults_default_factory_insert_default` :paramref:`_orm.mapped_column.insert_default` :paramref:`_orm.mapped_column.default_factory` :param insert_default: Passed directly to the :paramref:`_schema.Column.default` parameter; will supersede the value of :paramref:`_orm.mapped_column.default` when present, however :paramref:`_orm.mapped_column.default` will always apply to the constructor default for a dataclasses mapping. .. seealso:: :ref:`defaults_default_factory_insert_default` :paramref:`_orm.mapped_column.default` :paramref:`_orm.mapped_column.default_factory` :param sort_order: An integer that indicates how this mapped column should be sorted compared to the others when the ORM is creating a :class:`_schema.Table`. Among mapped columns that have the same value the default ordering is used, placing first the mapped columns defined in the main class, then the ones in the super classes. Defaults to 0. The sort is ascending. .. versionadded:: 2.0.4 :param active_history=False: When ``True``, indicates that the "previous" value for a scalar attribute should be loaded when replaced, if not already loaded. Normally, history tracking logic for simple non-primary-key scalar values only needs to be aware of the "new" value in order to perform a flush. This flag is available for applications that make use of :func:`.attributes.get_history` or :meth:`.Session.is_modified` which also need to know the "previous" value of the attribute. .. versionadded:: 2.0.10 :param init: Specific to :ref:`orm_declarative_native_dataclasses`, specifies if the mapped attribute should be part of the ``__init__()`` method as generated by the dataclass process. :param repr: Specific to :ref:`orm_declarative_native_dataclasses`, specifies if the mapped attribute should be part of the ``__repr__()`` method as generated by the dataclass process. :param default_factory: Specific to :ref:`orm_declarative_native_dataclasses`, specifies a default-value generation function that will take place as part of the ``__init__()`` method as generated by the dataclass process. .. seealso:: :ref:`defaults_default_factory_insert_default` :paramref:`_orm.mapped_column.default` :paramref:`_orm.mapped_column.insert_default` :param compare: Specific to :ref:`orm_declarative_native_dataclasses`, indicates if this field should be included in comparison operations when generating the ``__eq__()`` and ``__ne__()`` methods for the mapped class. .. versionadded:: 2.0.0b4 :param kw_only: Specific to :ref:`orm_declarative_native_dataclasses`, indicates if this field should be marked as keyword-only when generating the ``__init__()``. :param hash: Specific to :ref:`orm_declarative_native_dataclasses`, controls if this field is included when generating the ``__hash__()`` method for the mapped class. .. versionadded:: 2.0.36 :param \**kw: All remaining keyword arguments are passed through to the constructor for the :class:`_schema.Column`. """ return MappedColumn( __name_pos, __type_pos, *args, name=name, type_=type_, autoincrement=autoincrement, insert_default=insert_default, attribute_options=_AttributeOptions( init, repr, default, default_factory, compare, kw_only, hash ), doc=doc, key=key, index=index, unique=unique, info=info, active_history=active_history, nullable=nullable, onupdate=onupdate, primary_key=primary_key, server_default=server_default, server_onupdate=server_onupdate, use_existing_column=use_existing_column, quote=quote, comment=comment, system=system, deferred=deferred, deferred_group=deferred_group, deferred_raiseload=deferred_raiseload, sort_order=sort_order, **kw, ) def orm_insert_sentinel( name: Optional[str] = None, type_: Optional[_TypeEngineArgument[Any]] = None, *, default: Optional[Any] = None, omit_from_statements: bool = True, ) -> MappedColumn[Any]: """Provides a surrogate :func:`_orm.mapped_column` that generates a so-called :term:`sentinel` column, allowing efficient bulk inserts with deterministic RETURNING sorting for tables that don't otherwise have qualifying primary key configurations. Use of :func:`_orm.orm_insert_sentinel` is analogous to the use of the :func:`_schema.insert_sentinel` construct within a Core :class:`_schema.Table` construct. Guidelines for adding this construct to a Declarative mapped class are the same as that of the :func:`_schema.insert_sentinel` construct; the database table itself also needs to have a column with this name present. For background on how this object is used, see the section :ref:`engine_insertmanyvalues_sentinel_columns` as part of the section :ref:`engine_insertmanyvalues`. .. seealso:: :func:`_schema.insert_sentinel` :ref:`engine_insertmanyvalues` :ref:`engine_insertmanyvalues_sentinel_columns` .. versionadded:: 2.0.10 """ return mapped_column( name=name, default=( default if default is not None else _InsertSentinelColumnDefault() ), _omit_from_statements=omit_from_statements, insert_sentinel=True, use_existing_column=True, nullable=True, ) @util.deprecated_params( **{ arg: ( "2.0", f"The :paramref:`_orm.column_property.{arg}` parameter is " "deprecated for :func:`_orm.column_property`. This parameter " "applies to a writeable-attribute in a Declarative Dataclasses " "configuration only, and :func:`_orm.column_property` is treated " "as a read-only attribute in this context.", ) for arg in ("init", "kw_only", "default", "default_factory") } ) def column_property( column: _ORMColumnExprArgument[_T], *additional_columns: _ORMColumnExprArgument[Any], group: Optional[str] = None, deferred: bool = False, raiseload: bool = False, comparator_factory: Optional[Type[PropComparator[_T]]] = None, init: Union[_NoArg, bool] = _NoArg.NO_ARG, repr: Union[_NoArg, bool] = _NoArg.NO_ARG, # noqa: A002 default: Optional[Any] = _NoArg.NO_ARG, default_factory: Union[_NoArg, Callable[[], _T]] = _NoArg.NO_ARG, compare: Union[_NoArg, bool] = _NoArg.NO_ARG, kw_only: Union[_NoArg, bool] = _NoArg.NO_ARG, hash: Union[_NoArg, bool, None] = _NoArg.NO_ARG, # noqa: A002 active_history: bool = False, expire_on_flush: bool = True, info: Optional[_InfoType] = None, doc: Optional[str] = None, ) -> MappedSQLExpression[_T]: r"""Provide a column-level property for use with a mapping. With Declarative mappings, :func:`_orm.column_property` is used to map read-only SQL expressions to a mapped class. When using Imperative mappings, :func:`_orm.column_property` also takes on the role of mapping table columns with additional features. When using fully Declarative mappings, the :func:`_orm.mapped_column` construct should be used for this purpose. With Declarative Dataclass mappings, :func:`_orm.column_property` is considered to be **read only**, and will not be included in the Dataclass ``__init__()`` constructor. The :func:`_orm.column_property` function returns an instance of :class:`.ColumnProperty`. .. seealso:: :ref:`mapper_column_property_sql_expressions` - general use of :func:`_orm.column_property` to map SQL expressions :ref:`orm_imperative_table_column_options` - usage of :func:`_orm.column_property` with Imperative Table mappings to apply additional options to a plain :class:`_schema.Column` object :param \*cols: list of Column objects to be mapped. :param active_history=False: Used only for Imperative Table mappings, or legacy-style Declarative mappings (i.e. which have not been upgraded to :func:`_orm.mapped_column`), for column-based attributes that are expected to be writeable; use :func:`_orm.mapped_column` with :paramref:`_orm.mapped_column.active_history` for Declarative mappings. See that parameter for functional details. :param comparator_factory: a class which extends :class:`.ColumnProperty.Comparator` which provides custom SQL clause generation for comparison operations. :param group: a group name for this property when marked as deferred. :param deferred: when True, the column property is "deferred", meaning that it does not load immediately, and is instead loaded when the attribute is first accessed on an instance. See also :func:`~sqlalchemy.orm.deferred`. :param doc: optional string that will be applied as the doc on the class-bound descriptor. :param expire_on_flush=True: Disable expiry on flush. A column_property() which refers to a SQL expression (and not a single table-bound column) is considered to be a "read only" property; populating it has no effect on the state of data, and it can only return database state. For this reason a column_property()'s value is expired whenever the parent object is involved in a flush, that is, has any kind of "dirty" state within a flush. Setting this parameter to ``False`` will have the effect of leaving any existing value present after the flush proceeds. Note that the :class:`.Session` with default expiration settings still expires all attributes after a :meth:`.Session.commit` call, however. :param info: Optional data dictionary which will be populated into the :attr:`.MapperProperty.info` attribute of this object. :param raiseload: if True, indicates the column should raise an error when undeferred, rather than loading the value. This can be altered at query time by using the :func:`.deferred` option with raiseload=False. .. versionadded:: 1.4 .. seealso:: :ref:`orm_queryguide_deferred_raiseload` :param init: Specific to :ref:`orm_declarative_native_dataclasses`, specifies if the mapped attribute should be part of the ``__init__()`` method as generated by the dataclass process. :param repr: Specific to :ref:`orm_declarative_native_dataclasses`, specifies if the mapped attribute should be part of the ``__repr__()`` method as generated by the dataclass process. :param default_factory: Specific to :ref:`orm_declarative_native_dataclasses`, specifies a default-value generation function that will take place as part of the ``__init__()`` method as generated by the dataclass process. .. seealso:: :ref:`defaults_default_factory_insert_default` :paramref:`_orm.mapped_column.default` :paramref:`_orm.mapped_column.insert_default` :param compare: Specific to :ref:`orm_declarative_native_dataclasses`, indicates if this field should be included in comparison operations when generating the ``__eq__()`` and ``__ne__()`` methods for the mapped class. .. versionadded:: 2.0.0b4 :param kw_only: Specific to :ref:`orm_declarative_native_dataclasses`, indicates if this field should be marked as keyword-only when generating the ``__init__()``. :param hash: Specific to :ref:`orm_declarative_native_dataclasses`, controls if this field is included when generating the ``__hash__()`` method for the mapped class. .. versionadded:: 2.0.36 """ return MappedSQLExpression( column, *additional_columns, attribute_options=_AttributeOptions( False if init is _NoArg.NO_ARG else init, repr, default, default_factory, compare, kw_only, hash, ), group=group, deferred=deferred, raiseload=raiseload, comparator_factory=comparator_factory, active_history=active_history, expire_on_flush=expire_on_flush, info=info, doc=doc, _assume_readonly_dc_attributes=True, ) @overload def composite( _class_or_attr: _CompositeAttrType[Any], *attrs: _CompositeAttrType[Any], group: Optional[str] = None, deferred: bool = False, raiseload: bool = False, comparator_factory: Optional[Type[Composite.Comparator[_T]]] = None, active_history: bool = False, init: Union[_NoArg, bool] = _NoArg.NO_ARG, repr: Union[_NoArg, bool] = _NoArg.NO_ARG, # noqa: A002 default: Optional[Any] = _NoArg.NO_ARG, default_factory: Union[_NoArg, Callable[[], _T]] = _NoArg.NO_ARG, compare: Union[_NoArg, bool] = _NoArg.NO_ARG, kw_only: Union[_NoArg, bool] = _NoArg.NO_ARG, hash: Union[_NoArg, bool, None] = _NoArg.NO_ARG, # noqa: A002 info: Optional[_InfoType] = None, doc: Optional[str] = None, **__kw: Any, ) -> Composite[Any]: ... @overload def composite( _class_or_attr: Type[_CC], *attrs: _CompositeAttrType[Any], group: Optional[str] = None, deferred: bool = False, raiseload: bool = False, comparator_factory: Optional[Type[Composite.Comparator[_T]]] = None, active_history: bool = False, init: Union[_NoArg, bool] = _NoArg.NO_ARG, repr: Union[_NoArg, bool] = _NoArg.NO_ARG, # noqa: A002 default: Optional[Any] = _NoArg.NO_ARG, default_factory: Union[_NoArg, Callable[[], _T]] = _NoArg.NO_ARG, compare: Union[_NoArg, bool] = _NoArg.NO_ARG, kw_only: Union[_NoArg, bool] = _NoArg.NO_ARG, hash: Union[_NoArg, bool, None] = _NoArg.NO_ARG, # noqa: A002 info: Optional[_InfoType] = None, doc: Optional[str] = None, **__kw: Any, ) -> Composite[_CC]: ... @overload def composite( _class_or_attr: Callable[..., _CC], *attrs: _CompositeAttrType[Any], group: Optional[str] = None, deferred: bool = False, raiseload: bool = False, comparator_factory: Optional[Type[Composite.Comparator[_T]]] = None, active_history: bool = False, init: Union[_NoArg, bool] = _NoArg.NO_ARG, repr: Union[_NoArg, bool] = _NoArg.NO_ARG, # noqa: A002 default: Optional[Any] = _NoArg.NO_ARG, default_factory: Union[_NoArg, Callable[[], _T]] = _NoArg.NO_ARG, compare: Union[_NoArg, bool] = _NoArg.NO_ARG, kw_only: Union[_NoArg, bool] = _NoArg.NO_ARG, hash: Union[_NoArg, bool, None] = _NoArg.NO_ARG, # noqa: A002 info: Optional[_InfoType] = None, doc: Optional[str] = None, **__kw: Any, ) -> Composite[_CC]: ... def composite( _class_or_attr: Union[ None, Type[_CC], Callable[..., _CC], _CompositeAttrType[Any] ] = None, *attrs: _CompositeAttrType[Any], group: Optional[str] = None, deferred: bool = False, raiseload: bool = False, comparator_factory: Optional[Type[Composite.Comparator[_T]]] = None, active_history: bool = False, init: Union[_NoArg, bool] = _NoArg.NO_ARG, repr: Union[_NoArg, bool] = _NoArg.NO_ARG, # noqa: A002 default: Optional[Any] = _NoArg.NO_ARG, default_factory: Union[_NoArg, Callable[[], _T]] = _NoArg.NO_ARG, compare: Union[_NoArg, bool] = _NoArg.NO_ARG, kw_only: Union[_NoArg, bool] = _NoArg.NO_ARG, hash: Union[_NoArg, bool, None] = _NoArg.NO_ARG, # noqa: A002 info: Optional[_InfoType] = None, doc: Optional[str] = None, **__kw: Any, ) -> Composite[Any]: r"""Return a composite column-based property for use with a Mapper. See the mapping documentation section :ref:`mapper_composite` for a full usage example. The :class:`.MapperProperty` returned by :func:`.composite` is the :class:`.Composite`. :param class\_: The "composite type" class, or any classmethod or callable which will produce a new instance of the composite object given the column values in order. :param \*attrs: List of elements to be mapped, which may include: * :class:`_schema.Column` objects * :func:`_orm.mapped_column` constructs * string names of other attributes on the mapped class, which may be any other SQL or object-mapped attribute. This can for example allow a composite that refers to a many-to-one relationship :param active_history=False: When ``True``, indicates that the "previous" value for a scalar attribute should be loaded when replaced, if not already loaded. See the same flag on :func:`.column_property`. :param group: A group name for this property when marked as deferred. :param deferred: When True, the column property is "deferred", meaning that it does not load immediately, and is instead loaded when the attribute is first accessed on an instance. See also :func:`~sqlalchemy.orm.deferred`. :param comparator_factory: a class which extends :class:`.Composite.Comparator` which provides custom SQL clause generation for comparison operations. :param doc: optional string that will be applied as the doc on the class-bound descriptor. :param info: Optional data dictionary which will be populated into the :attr:`.MapperProperty.info` attribute of this object. :param init: Specific to :ref:`orm_declarative_native_dataclasses`, specifies if the mapped attribute should be part of the ``__init__()`` method as generated by the dataclass process. :param repr: Specific to :ref:`orm_declarative_native_dataclasses`, specifies if the mapped attribute should be part of the ``__repr__()`` method as generated by the dataclass process. :param default_factory: Specific to :ref:`orm_declarative_native_dataclasses`, specifies a default-value generation function that will take place as part of the ``__init__()`` method as generated by the dataclass process. :param compare: Specific to :ref:`orm_declarative_native_dataclasses`, indicates if this field should be included in comparison operations when generating the ``__eq__()`` and ``__ne__()`` methods for the mapped class. .. versionadded:: 2.0.0b4 :param kw_only: Specific to :ref:`orm_declarative_native_dataclasses`, indicates if this field should be marked as keyword-only when generating the ``__init__()``. :param hash: Specific to :ref:`orm_declarative_native_dataclasses`, controls if this field is included when generating the ``__hash__()`` method for the mapped class. .. versionadded:: 2.0.36 """ if __kw: raise _no_kw() return Composite( _class_or_attr, *attrs, attribute_options=_AttributeOptions( init, repr, default, default_factory, compare, kw_only, hash ), group=group, deferred=deferred, raiseload=raiseload, comparator_factory=comparator_factory, active_history=active_history, info=info, doc=doc, ) def with_loader_criteria( entity_or_base: _EntityType[Any], where_criteria: Union[ _ColumnExpressionArgument[bool], Callable[[Any], _ColumnExpressionArgument[bool]], ], loader_only: bool = False, include_aliases: bool = False, propagate_to_loaders: bool = True, track_closure_variables: bool = True, ) -> LoaderCriteriaOption: """Add additional WHERE criteria to the load for all occurrences of a particular entity. .. versionadded:: 1.4 The :func:`_orm.with_loader_criteria` option is intended to add limiting criteria to a particular kind of entity in a query, **globally**, meaning it will apply to the entity as it appears in the SELECT query as well as within any subqueries, join conditions, and relationship loads, including both eager and lazy loaders, without the need for it to be specified in any particular part of the query. The rendering logic uses the same system used by single table inheritance to ensure a certain discriminator is applied to a table. E.g., using :term:`2.0-style` queries, we can limit the way the ``User.addresses`` collection is loaded, regardless of the kind of loading used:: from sqlalchemy.orm import with_loader_criteria stmt = select(User).options( selectinload(User.addresses), with_loader_criteria(Address, Address.email_address != "foo"), ) Above, the "selectinload" for ``User.addresses`` will apply the given filtering criteria to the WHERE clause. Another example, where the filtering will be applied to the ON clause of the join, in this example using :term:`1.x style` queries:: q = ( session.query(User) .outerjoin(User.addresses) .options(with_loader_criteria(Address, Address.email_address != "foo")) ) The primary purpose of :func:`_orm.with_loader_criteria` is to use it in the :meth:`_orm.SessionEvents.do_orm_execute` event handler to ensure that all occurrences of a particular entity are filtered in a certain way, such as filtering for access control roles. It also can be used to apply criteria to relationship loads. In the example below, we can apply a certain set of rules to all queries emitted by a particular :class:`_orm.Session`:: session = Session(bind=engine) @event.listens_for("do_orm_execute", session) def _add_filtering_criteria(execute_state): if ( execute_state.is_select and not execute_state.is_column_load and not execute_state.is_relationship_load ): execute_state.statement = execute_state.statement.options( with_loader_criteria( SecurityRole, lambda cls: cls.role.in_(["some_role"]), include_aliases=True, ) ) In the above example, the :meth:`_orm.SessionEvents.do_orm_execute` event will intercept all queries emitted using the :class:`_orm.Session`. For those queries which are SELECT statements and are not attribute or relationship loads a custom :func:`_orm.with_loader_criteria` option is added to the query. The :func:`_orm.with_loader_criteria` option will be used in the given statement and will also be automatically propagated to all relationship loads that descend from this query. The criteria argument given is a ``lambda`` that accepts a ``cls`` argument. The given class will expand to include all mapped subclass and need not itself be a mapped class. .. tip:: When using :func:`_orm.with_loader_criteria` option in conjunction with the :func:`_orm.contains_eager` loader option, it's important to note that :func:`_orm.with_loader_criteria` only affects the part of the query that determines what SQL is rendered in terms of the WHERE and FROM clauses. The :func:`_orm.contains_eager` option does not affect the rendering of the SELECT statement outside of the columns clause, so does not have any interaction with the :func:`_orm.with_loader_criteria` option. However, the way things "work" is that :func:`_orm.contains_eager` is meant to be used with a query that is already selecting from the additional entities in some way, where :func:`_orm.with_loader_criteria` can apply it's additional criteria. In the example below, assuming a mapping relationship as ``A -> A.bs -> B``, the given :func:`_orm.with_loader_criteria` option will affect the way in which the JOIN is rendered:: stmt = ( select(A) .join(A.bs) .options(contains_eager(A.bs), with_loader_criteria(B, B.flag == 1)) ) Above, the given :func:`_orm.with_loader_criteria` option will affect the ON clause of the JOIN that is specified by ``.join(A.bs)``, so is applied as expected. The :func:`_orm.contains_eager` option has the effect that columns from ``B`` are added to the columns clause: .. sourcecode:: sql SELECT b.id, b.a_id, b.data, b.flag, a.id AS id_1, a.data AS data_1 FROM a JOIN b ON a.id = b.a_id AND b.flag = :flag_1 The use of the :func:`_orm.contains_eager` option within the above statement has no effect on the behavior of the :func:`_orm.with_loader_criteria` option. If the :func:`_orm.contains_eager` option were omitted, the SQL would be the same as regards the FROM and WHERE clauses, where :func:`_orm.with_loader_criteria` continues to add its criteria to the ON clause of the JOIN. The addition of :func:`_orm.contains_eager` only affects the columns clause, in that additional columns against ``b`` are added which are then consumed by the ORM to produce ``B`` instances. .. warning:: The use of a lambda inside of the call to :func:`_orm.with_loader_criteria` is only invoked **once per unique class**. Custom functions should not be invoked within this lambda. See :ref:`engine_lambda_caching` for an overview of the "lambda SQL" feature, which is for advanced use only. :param entity_or_base: a mapped class, or a class that is a super class of a particular set of mapped classes, to which the rule will apply. :param where_criteria: a Core SQL expression that applies limiting criteria. This may also be a "lambda:" or Python function that accepts a target class as an argument, when the given class is a base with many different mapped subclasses. .. note:: To support pickling, use a module-level Python function to produce the SQL expression instead of a lambda or a fixed SQL expression, which tend to not be picklable. :param include_aliases: if True, apply the rule to :func:`_orm.aliased` constructs as well. :param propagate_to_loaders: defaults to True, apply to relationship loaders such as lazy loaders. This indicates that the option object itself including SQL expression is carried along with each loaded instance. Set to ``False`` to prevent the object from being assigned to individual instances. .. seealso:: :ref:`examples_session_orm_events` - includes examples of using :func:`_orm.with_loader_criteria`. :ref:`do_orm_execute_global_criteria` - basic example on how to combine :func:`_orm.with_loader_criteria` with the :meth:`_orm.SessionEvents.do_orm_execute` event. :param track_closure_variables: when False, closure variables inside of a lambda expression will not be used as part of any cache key. This allows more complex expressions to be used inside of a lambda expression but requires that the lambda ensures it returns the identical SQL every time given a particular class. .. versionadded:: 1.4.0b2 """ # noqa: E501 return LoaderCriteriaOption( entity_or_base, where_criteria, loader_only, include_aliases, propagate_to_loaders, track_closure_variables, ) def relationship( argument: Optional[_RelationshipArgumentType[Any]] = None, secondary: Optional[_RelationshipSecondaryArgument] = None, *, uselist: Optional[bool] = None, collection_class: Optional[ Union[Type[Collection[Any]], Callable[[], Collection[Any]]] ] = None, primaryjoin: Optional[_RelationshipJoinConditionArgument] = None, secondaryjoin: Optional[_RelationshipJoinConditionArgument] = None, back_populates: Optional[str] = None, order_by: _ORMOrderByArgument = False, backref: Optional[ORMBackrefArgument] = None, overlaps: Optional[str] = None, post_update: bool = False, cascade: str = "save-update, merge", viewonly: bool = False, init: Union[_NoArg, bool] = _NoArg.NO_ARG, repr: Union[_NoArg, bool] = _NoArg.NO_ARG, # noqa: A002 default: Union[_NoArg, _T] = _NoArg.NO_ARG, default_factory: Union[_NoArg, Callable[[], _T]] = _NoArg.NO_ARG, compare: Union[_NoArg, bool] = _NoArg.NO_ARG, kw_only: Union[_NoArg, bool] = _NoArg.NO_ARG, hash: Union[_NoArg, bool, None] = _NoArg.NO_ARG, # noqa: A002 lazy: _LazyLoadArgumentType = "select", passive_deletes: Union[Literal["all"], bool] = False, passive_updates: bool = True, active_history: bool = False, enable_typechecks: bool = True, foreign_keys: Optional[_ORMColCollectionArgument] = None, remote_side: Optional[_ORMColCollectionArgument] = None, join_depth: Optional[int] = None, comparator_factory: Optional[ Type[RelationshipProperty.Comparator[Any]] ] = None, single_parent: bool = False, innerjoin: bool = False, distinct_target_key: Optional[bool] = None, load_on_pending: bool = False, query_class: Optional[Type[Query[Any]]] = None, info: Optional[_InfoType] = None, omit_join: Literal[None, False] = None, sync_backref: Optional[bool] = None, **kw: Any, ) -> _RelationshipDeclared[Any]: """Provide a relationship between two mapped classes. This corresponds to a parent-child or associative table relationship. The constructed class is an instance of :class:`.Relationship`. .. seealso:: :ref:`tutorial_orm_related_objects` - tutorial introduction to :func:`_orm.relationship` in the :ref:`unified_tutorial` :ref:`relationship_config_toplevel` - narrative documentation :param argument: This parameter refers to the class that is to be related. It accepts several forms, including a direct reference to the target class itself, the :class:`_orm.Mapper` instance for the target class, a Python callable / lambda that will return a reference to the class or :class:`_orm.Mapper` when called, and finally a string name for the class, which will be resolved from the :class:`_orm.registry` in use in order to locate the class, e.g.:: class SomeClass(Base): # ... related = relationship("RelatedClass") The :paramref:`_orm.relationship.argument` may also be omitted from the :func:`_orm.relationship` construct entirely, and instead placed inside a :class:`_orm.Mapped` annotation on the left side, which should include a Python collection type if the relationship is expected to be a collection, such as:: class SomeClass(Base): # ... related_items: Mapped[List["RelatedItem"]] = relationship() Or for a many-to-one or one-to-one relationship:: class SomeClass(Base): # ... related_item: Mapped["RelatedItem"] = relationship() .. seealso:: :ref:`orm_declarative_properties` - further detail on relationship configuration when using Declarative. :param secondary: For a many-to-many relationship, specifies the intermediary table, and is typically an instance of :class:`_schema.Table`. In less common circumstances, the argument may also be specified as an :class:`_expression.Alias` construct, or even a :class:`_expression.Join` construct. :paramref:`_orm.relationship.secondary` may also be passed as a callable function which is evaluated at mapper initialization time. When using Declarative, it may also be a string argument noting the name of a :class:`_schema.Table` that is present in the :class:`_schema.MetaData` collection associated with the parent-mapped :class:`_schema.Table`. .. warning:: When passed as a Python-evaluable string, the argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on declarative evaluation of :func:`_orm.relationship` arguments. The :paramref:`_orm.relationship.secondary` keyword argument is typically applied in the case where the intermediary :class:`_schema.Table` is not otherwise expressed in any direct class mapping. If the "secondary" table is also explicitly mapped elsewhere (e.g. as in :ref:`association_pattern`), one should consider applying the :paramref:`_orm.relationship.viewonly` flag so that this :func:`_orm.relationship` is not used for persistence operations which may conflict with those of the association object pattern. .. seealso:: :ref:`relationships_many_to_many` - Reference example of "many to many". :ref:`self_referential_many_to_many` - Specifics on using many-to-many in a self-referential case. :ref:`declarative_many_to_many` - Additional options when using Declarative. :ref:`association_pattern` - an alternative to :paramref:`_orm.relationship.secondary` when composing association table relationships, allowing additional attributes to be specified on the association table. :ref:`composite_secondary_join` - a lesser-used pattern which in some cases can enable complex :func:`_orm.relationship` SQL conditions to be used. :param active_history=False: When ``True``, indicates that the "previous" value for a many-to-one reference should be loaded when replaced, if not already loaded. Normally, history tracking logic for simple many-to-ones only needs to be aware of the "new" value in order to perform a flush. This flag is available for applications that make use of :func:`.attributes.get_history` which also need to know the "previous" value of the attribute. :param backref: A reference to a string relationship name, or a :func:`_orm.backref` construct, which will be used to automatically generate a new :func:`_orm.relationship` on the related class, which then refers to this one using a bi-directional :paramref:`_orm.relationship.back_populates` configuration. In modern Python, explicit use of :func:`_orm.relationship` with :paramref:`_orm.relationship.back_populates` should be preferred, as it is more robust in terms of mapper configuration as well as more conceptually straightforward. It also integrates with new :pep:`484` typing features introduced in SQLAlchemy 2.0 which is not possible with dynamically generated attributes. .. seealso:: :ref:`relationships_backref` - notes on using :paramref:`_orm.relationship.backref` :ref:`tutorial_orm_related_objects` - in the :ref:`unified_tutorial`, presents an overview of bi-directional relationship configuration and behaviors using :paramref:`_orm.relationship.back_populates` :func:`.backref` - allows control over :func:`_orm.relationship` configuration when using :paramref:`_orm.relationship.backref`. :param back_populates: Indicates the name of a :func:`_orm.relationship` on the related class that will be synchronized with this one. It is usually expected that the :func:`_orm.relationship` on the related class also refer to this one. This allows objects on both sides of each :func:`_orm.relationship` to synchronize in-Python state changes and also provides directives to the :term:`unit of work` flush process how changes along these relationships should be persisted. .. seealso:: :ref:`tutorial_orm_related_objects` - in the :ref:`unified_tutorial`, presents an overview of bi-directional relationship configuration and behaviors. :ref:`relationship_patterns` - includes many examples of :paramref:`_orm.relationship.back_populates`. :paramref:`_orm.relationship.backref` - legacy form which allows more succinct configuration, but does not support explicit typing :param overlaps: A string name or comma-delimited set of names of other relationships on either this mapper, a descendant mapper, or a target mapper with which this relationship may write to the same foreign keys upon persistence. The only effect this has is to eliminate the warning that this relationship will conflict with another upon persistence. This is used for such relationships that are truly capable of conflicting with each other on write, but the application will ensure that no such conflicts occur. .. versionadded:: 1.4 .. seealso:: :ref:`error_qzyx` - usage example :param cascade: A comma-separated list of cascade rules which determines how Session operations should be "cascaded" from parent to child. This defaults to ``False``, which means the default cascade should be used - this default cascade is ``"save-update, merge"``. The available cascades are ``save-update``, ``merge``, ``expunge``, ``delete``, ``delete-orphan``, and ``refresh-expire``. An additional option, ``all`` indicates shorthand for ``"save-update, merge, refresh-expire, expunge, delete"``, and is often used as in ``"all, delete-orphan"`` to indicate that related objects should follow along with the parent object in all cases, and be deleted when de-associated. .. seealso:: :ref:`unitofwork_cascades` - Full detail on each of the available cascade options. :param cascade_backrefs=False: Legacy; this flag is always False. .. versionchanged:: 2.0 "cascade_backrefs" functionality has been removed. :param collection_class: A class or callable that returns a new list-holding object. will be used in place of a plain list for storing elements. .. seealso:: :ref:`custom_collections` - Introductory documentation and examples. :param comparator_factory: A class which extends :class:`.Relationship.Comparator` which provides custom SQL clause generation for comparison operations. .. seealso:: :class:`.PropComparator` - some detail on redefining comparators at this level. :ref:`custom_comparators` - Brief intro to this feature. :param distinct_target_key=None: Indicate if a "subquery" eager load should apply the DISTINCT keyword to the innermost SELECT statement. When left as ``None``, the DISTINCT keyword will be applied in those cases when the target columns do not comprise the full primary key of the target table. When set to ``True``, the DISTINCT keyword is applied to the innermost SELECT unconditionally. It may be desirable to set this flag to False when the DISTINCT is reducing performance of the innermost subquery beyond that of what duplicate innermost rows may be causing. .. seealso:: :ref:`loading_toplevel` - includes an introduction to subquery eager loading. :param doc: Docstring which will be applied to the resulting descriptor. :param foreign_keys: A list of columns which are to be used as "foreign key" columns, or columns which refer to the value in a remote column, within the context of this :func:`_orm.relationship` object's :paramref:`_orm.relationship.primaryjoin` condition. That is, if the :paramref:`_orm.relationship.primaryjoin` condition of this :func:`_orm.relationship` is ``a.id == b.a_id``, and the values in ``b.a_id`` are required to be present in ``a.id``, then the "foreign key" column of this :func:`_orm.relationship` is ``b.a_id``. In normal cases, the :paramref:`_orm.relationship.foreign_keys` parameter is **not required.** :func:`_orm.relationship` will automatically determine which columns in the :paramref:`_orm.relationship.primaryjoin` condition are to be considered "foreign key" columns based on those :class:`_schema.Column` objects that specify :class:`_schema.ForeignKey`, or are otherwise listed as referencing columns in a :class:`_schema.ForeignKeyConstraint` construct. :paramref:`_orm.relationship.foreign_keys` is only needed when: 1. There is more than one way to construct a join from the local table to the remote table, as there are multiple foreign key references present. Setting ``foreign_keys`` will limit the :func:`_orm.relationship` to consider just those columns specified here as "foreign". 2. The :class:`_schema.Table` being mapped does not actually have :class:`_schema.ForeignKey` or :class:`_schema.ForeignKeyConstraint` constructs present, often because the table was reflected from a database that does not support foreign key reflection (MySQL MyISAM). 3. The :paramref:`_orm.relationship.primaryjoin` argument is used to construct a non-standard join condition, which makes use of columns or expressions that do not normally refer to their "parent" column, such as a join condition expressed by a complex comparison using a SQL function. The :func:`_orm.relationship` construct will raise informative error messages that suggest the use of the :paramref:`_orm.relationship.foreign_keys` parameter when presented with an ambiguous condition. In typical cases, if :func:`_orm.relationship` doesn't raise any exceptions, the :paramref:`_orm.relationship.foreign_keys` parameter is usually not needed. :paramref:`_orm.relationship.foreign_keys` may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. .. warning:: When passed as a Python-evaluable string, the argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on declarative evaluation of :func:`_orm.relationship` arguments. .. seealso:: :ref:`relationship_foreign_keys` :ref:`relationship_custom_foreign` :func:`.foreign` - allows direct annotation of the "foreign" columns within a :paramref:`_orm.relationship.primaryjoin` condition. :param info: Optional data dictionary which will be populated into the :attr:`.MapperProperty.info` attribute of this object. :param innerjoin=False: When ``True``, joined eager loads will use an inner join to join against related tables instead of an outer join. The purpose of this option is generally one of performance, as inner joins generally perform better than outer joins. This flag can be set to ``True`` when the relationship references an object via many-to-one using local foreign keys that are not nullable, or when the reference is one-to-one or a collection that is guaranteed to have one or at least one entry. The option supports the same "nested" and "unnested" options as that of :paramref:`_orm.joinedload.innerjoin`. See that flag for details on nested / unnested behaviors. .. seealso:: :paramref:`_orm.joinedload.innerjoin` - the option as specified by loader option, including detail on nesting behavior. :ref:`what_kind_of_loading` - Discussion of some details of various loader options. :param join_depth: When non-``None``, an integer value indicating how many levels deep "eager" loaders should join on a self-referring or cyclical relationship. The number counts how many times the same Mapper shall be present in the loading condition along a particular join branch. When left at its default of ``None``, eager loaders will stop chaining when they encounter a the same target mapper which is already higher up in the chain. This option applies both to joined- and subquery- eager loaders. .. seealso:: :ref:`self_referential_eager_loading` - Introductory documentation and examples. :param lazy='select': specifies How the related items should be loaded. Default value is ``select``. Values include: * ``select`` - items should be loaded lazily when the property is first accessed, using a separate SELECT statement, or identity map fetch for simple many-to-one references. * ``immediate`` - items should be loaded as the parents are loaded, using a separate SELECT statement, or identity map fetch for simple many-to-one references. * ``joined`` - items should be loaded "eagerly" in the same query as that of the parent, using a JOIN or LEFT OUTER JOIN. Whether the join is "outer" or not is determined by the :paramref:`_orm.relationship.innerjoin` parameter. * ``subquery`` - items should be loaded "eagerly" as the parents are loaded, using one additional SQL statement, which issues a JOIN to a subquery of the original statement, for each collection requested. * ``selectin`` - items should be loaded "eagerly" as the parents are loaded, using one or more additional SQL statements, which issues a JOIN to the immediate parent object, specifying primary key identifiers using an IN clause. * ``noload`` - no loading should occur at any time. The related collection will remain empty. The ``noload`` strategy is not recommended for general use. For a general use "never load" approach, see :ref:`write_only_relationship` * ``raise`` - lazy loading is disallowed; accessing the attribute, if its value were not already loaded via eager loading, will raise an :exc:`~sqlalchemy.exc.InvalidRequestError`. This strategy can be used when objects are to be detached from their attached :class:`.Session` after they are loaded. * ``raise_on_sql`` - lazy loading that emits SQL is disallowed; accessing the attribute, if its value were not already loaded via eager loading, will raise an :exc:`~sqlalchemy.exc.InvalidRequestError`, **if the lazy load needs to emit SQL**. If the lazy load can pull the related value from the identity map or determine that it should be None, the value is loaded. This strategy can be used when objects will remain associated with the attached :class:`.Session`, however additional SELECT statements should be blocked. * ``write_only`` - the attribute will be configured with a special "virtual collection" that may receive :meth:`_orm.WriteOnlyCollection.add` and :meth:`_orm.WriteOnlyCollection.remove` commands to add or remove individual objects, but will not under any circumstances load or iterate the full set of objects from the database directly. Instead, methods such as :meth:`_orm.WriteOnlyCollection.select`, :meth:`_orm.WriteOnlyCollection.insert`, :meth:`_orm.WriteOnlyCollection.update` and :meth:`_orm.WriteOnlyCollection.delete` are provided which generate SQL constructs that may be used to load and modify rows in bulk. Used for large collections that are never appropriate to load at once into memory. The ``write_only`` loader style is configured automatically when the :class:`_orm.WriteOnlyMapped` annotation is provided on the left hand side within a Declarative mapping. See the section :ref:`write_only_relationship` for examples. .. versionadded:: 2.0 .. seealso:: :ref:`write_only_relationship` - in the :ref:`queryguide_toplevel` * ``dynamic`` - the attribute will return a pre-configured :class:`_query.Query` object for all read operations, onto which further filtering operations can be applied before iterating the results. The ``dynamic`` loader style is configured automatically when the :class:`_orm.DynamicMapped` annotation is provided on the left hand side within a Declarative mapping. See the section :ref:`dynamic_relationship` for examples. .. legacy:: The "dynamic" lazy loader strategy is the legacy form of what is now the "write_only" strategy described in the section :ref:`write_only_relationship`. .. seealso:: :ref:`dynamic_relationship` - in the :ref:`queryguide_toplevel` :ref:`write_only_relationship` - more generally useful approach for large collections that should not fully load into memory * True - a synonym for 'select' * False - a synonym for 'joined' * None - a synonym for 'noload' .. seealso:: :ref:`orm_queryguide_relationship_loaders` - Full documentation on relationship loader configuration in the :ref:`queryguide_toplevel`. :param load_on_pending=False: Indicates loading behavior for transient or pending parent objects. When set to ``True``, causes the lazy-loader to issue a query for a parent object that is not persistent, meaning it has never been flushed. This may take effect for a pending object when autoflush is disabled, or for a transient object that has been "attached" to a :class:`.Session` but is not part of its pending collection. The :paramref:`_orm.relationship.load_on_pending` flag does not improve behavior when the ORM is used normally - object references should be constructed at the object level, not at the foreign key level, so that they are present in an ordinary way before a flush proceeds. This flag is not not intended for general use. .. seealso:: :meth:`.Session.enable_relationship_loading` - this method establishes "load on pending" behavior for the whole object, and also allows loading on objects that remain transient or detached. :param order_by: Indicates the ordering that should be applied when loading these items. :paramref:`_orm.relationship.order_by` is expected to refer to one of the :class:`_schema.Column` objects to which the target class is mapped, or the attribute itself bound to the target class which refers to the column. :paramref:`_orm.relationship.order_by` may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. .. warning:: When passed as a Python-evaluable string, the argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on declarative evaluation of :func:`_orm.relationship` arguments. :param passive_deletes=False: Indicates loading behavior during delete operations. A value of True indicates that unloaded child items should not be loaded during a delete operation on the parent. Normally, when a parent item is deleted, all child items are loaded so that they can either be marked as deleted, or have their foreign key to the parent set to NULL. Marking this flag as True usually implies an ON DELETE <CASCADE|SET NULL> rule is in place which will handle updating/deleting child rows on the database side. Additionally, setting the flag to the string value 'all' will disable the "nulling out" of the child foreign keys, when the parent object is deleted and there is no delete or delete-orphan cascade enabled. This is typically used when a triggering or error raise scenario is in place on the database side. Note that the foreign key attributes on in-session child objects will not be changed after a flush occurs so this is a very special use-case setting. Additionally, the "nulling out" will still occur if the child object is de-associated with the parent. .. seealso:: :ref:`passive_deletes` - Introductory documentation and examples. :param passive_updates=True: Indicates the persistence behavior to take when a referenced primary key value changes in place, indicating that the referencing foreign key columns will also need their value changed. When True, it is assumed that ``ON UPDATE CASCADE`` is configured on the foreign key in the database, and that the database will handle propagation of an UPDATE from a source column to dependent rows. When False, the SQLAlchemy :func:`_orm.relationship` construct will attempt to emit its own UPDATE statements to modify related targets. However note that SQLAlchemy **cannot** emit an UPDATE for more than one level of cascade. Also, setting this flag to False is not compatible in the case where the database is in fact enforcing referential integrity, unless those constraints are explicitly "deferred", if the target backend supports it. It is highly advised that an application which is employing mutable primary keys keeps ``passive_updates`` set to True, and instead uses the referential integrity features of the database itself in order to handle the change efficiently and fully. .. seealso:: :ref:`passive_updates` - Introductory documentation and examples. :paramref:`.mapper.passive_updates` - a similar flag which takes effect for joined-table inheritance mappings. :param post_update: This indicates that the relationship should be handled by a second UPDATE statement after an INSERT or before a DELETE. This flag is used to handle saving bi-directional dependencies between two individual rows (i.e. each row references the other), where it would otherwise be impossible to INSERT or DELETE both rows fully since one row exists before the other. Use this flag when a particular mapping arrangement will incur two rows that are dependent on each other, such as a table that has a one-to-many relationship to a set of child rows, and also has a column that references a single child row within that list (i.e. both tables contain a foreign key to each other). If a flush operation returns an error that a "cyclical dependency" was detected, this is a cue that you might want to use :paramref:`_orm.relationship.post_update` to "break" the cycle. .. seealso:: :ref:`post_update` - Introductory documentation and examples. :param primaryjoin: A SQL expression that will be used as the primary join of the child object against the parent object, or in a many-to-many relationship the join of the parent object to the association table. By default, this value is computed based on the foreign key relationships of the parent and child tables (or association table). :paramref:`_orm.relationship.primaryjoin` may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. .. warning:: When passed as a Python-evaluable string, the argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on declarative evaluation of :func:`_orm.relationship` arguments. .. seealso:: :ref:`relationship_primaryjoin` :param remote_side: Used for self-referential relationships, indicates the column or list of columns that form the "remote side" of the relationship. :paramref:`_orm.relationship.remote_side` may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. .. warning:: When passed as a Python-evaluable string, the argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on declarative evaluation of :func:`_orm.relationship` arguments. .. seealso:: :ref:`self_referential` - in-depth explanation of how :paramref:`_orm.relationship.remote_side` is used to configure self-referential relationships. :func:`.remote` - an annotation function that accomplishes the same purpose as :paramref:`_orm.relationship.remote_side`, typically when a custom :paramref:`_orm.relationship.primaryjoin` condition is used. :param query_class: A :class:`_query.Query` subclass that will be used internally by the ``AppenderQuery`` returned by a "dynamic" relationship, that is, a relationship that specifies ``lazy="dynamic"`` or was otherwise constructed using the :func:`_orm.dynamic_loader` function. .. seealso:: :ref:`dynamic_relationship` - Introduction to "dynamic" relationship loaders. :param secondaryjoin: A SQL expression that will be used as the join of an association table to the child object. By default, this value is computed based on the foreign key relationships of the association and child tables. :paramref:`_orm.relationship.secondaryjoin` may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. .. warning:: When passed as a Python-evaluable string, the argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on declarative evaluation of :func:`_orm.relationship` arguments. .. seealso:: :ref:`relationship_primaryjoin` :param single_parent: When True, installs a validator which will prevent objects from being associated with more than one parent at a time. This is used for many-to-one or many-to-many relationships that should be treated either as one-to-one or one-to-many. Its usage is optional, except for :func:`_orm.relationship` constructs which are many-to-one or many-to-many and also specify the ``delete-orphan`` cascade option. The :func:`_orm.relationship` construct itself will raise an error instructing when this option is required. .. seealso:: :ref:`unitofwork_cascades` - includes detail on when the :paramref:`_orm.relationship.single_parent` flag may be appropriate. :param uselist: A boolean that indicates if this property should be loaded as a list or a scalar. In most cases, this value is determined automatically by :func:`_orm.relationship` at mapper configuration time. When using explicit :class:`_orm.Mapped` annotations, :paramref:`_orm.relationship.uselist` may be derived from the whether or not the annotation within :class:`_orm.Mapped` contains a collection class. Otherwise, :paramref:`_orm.relationship.uselist` may be derived from the type and direction of the relationship - one to many forms a list, many to one forms a scalar, many to many is a list. If a scalar is desired where normally a list would be present, such as a bi-directional one-to-one relationship, use an appropriate :class:`_orm.Mapped` annotation or set :paramref:`_orm.relationship.uselist` to False. The :paramref:`_orm.relationship.uselist` flag is also available on an existing :func:`_orm.relationship` construct as a read-only attribute, which can be used to determine if this :func:`_orm.relationship` deals with collections or scalar attributes:: >>> User.addresses.property.uselist True .. seealso:: :ref:`relationships_one_to_one` - Introduction to the "one to one" relationship pattern, which is typically when an alternate setting for :paramref:`_orm.relationship.uselist` is involved. :param viewonly=False: When set to ``True``, the relationship is used only for loading objects, and not for any persistence operation. A :func:`_orm.relationship` which specifies :paramref:`_orm.relationship.viewonly` can work with a wider range of SQL operations within the :paramref:`_orm.relationship.primaryjoin` condition, including operations that feature the use of a variety of comparison operators as well as SQL functions such as :func:`_expression.cast`. The :paramref:`_orm.relationship.viewonly` flag is also of general use when defining any kind of :func:`_orm.relationship` that doesn't represent the full set of related objects, to prevent modifications of the collection from resulting in persistence operations. .. seealso:: :ref:`relationship_viewonly_notes` - more details on best practices when using :paramref:`_orm.relationship.viewonly`. :param sync_backref: A boolean that enables the events used to synchronize the in-Python attributes when this relationship is target of either :paramref:`_orm.relationship.backref` or :paramref:`_orm.relationship.back_populates`. Defaults to ``None``, which indicates that an automatic value should be selected based on the value of the :paramref:`_orm.relationship.viewonly` flag. When left at its default, changes in state will be back-populated only if neither sides of a relationship is viewonly. .. versionadded:: 1.3.17 .. versionchanged:: 1.4 - A relationship that specifies :paramref:`_orm.relationship.viewonly` automatically implies that :paramref:`_orm.relationship.sync_backref` is ``False``. .. seealso:: :paramref:`_orm.relationship.viewonly` :param omit_join: Allows manual control over the "selectin" automatic join optimization. Set to ``False`` to disable the "omit join" feature added in SQLAlchemy 1.3; or leave as ``None`` to leave automatic optimization in place. .. note:: This flag may only be set to ``False``. It is not necessary to set it to ``True`` as the "omit_join" optimization is automatically detected; if it is not detected, then the optimization is not supported. .. versionchanged:: 1.3.11 setting ``omit_join`` to True will now emit a warning as this was not the intended use of this flag. .. versionadded:: 1.3 :param init: Specific to :ref:`orm_declarative_native_dataclasses`, specifies if the mapped attribute should be part of the ``__init__()`` method as generated by the dataclass process. :param repr: Specific to :ref:`orm_declarative_native_dataclasses`, specifies if the mapped attribute should be part of the ``__repr__()`` method as generated by the dataclass process. :param default_factory: Specific to :ref:`orm_declarative_native_dataclasses`, specifies a default-value generation function that will take place as part of the ``__init__()`` method as generated by the dataclass process. :param compare: Specific to :ref:`orm_declarative_native_dataclasses`, indicates if this field should be included in comparison operations when generating the ``__eq__()`` and ``__ne__()`` methods for the mapped class. .. versionadded:: 2.0.0b4 :param kw_only: Specific to :ref:`orm_declarative_native_dataclasses`, indicates if this field should be marked as keyword-only when generating the ``__init__()``. :param hash: Specific to :ref:`orm_declarative_native_dataclasses`, controls if this field is included when generating the ``__hash__()`` method for the mapped class. .. versionadded:: 2.0.36 """ return _RelationshipDeclared( argument, secondary=secondary, uselist=uselist, collection_class=collection_class, primaryjoin=primaryjoin, secondaryjoin=secondaryjoin, back_populates=back_populates, order_by=order_by, backref=backref, overlaps=overlaps, post_update=post_update, cascade=cascade, viewonly=viewonly, attribute_options=_AttributeOptions( init, repr, default, default_factory, compare, kw_only, hash ), lazy=lazy, passive_deletes=passive_deletes, passive_updates=passive_updates, active_history=active_history, enable_typechecks=enable_typechecks, foreign_keys=foreign_keys, remote_side=remote_side, join_depth=join_depth, comparator_factory=comparator_factory, single_parent=single_parent, innerjoin=innerjoin, distinct_target_key=distinct_target_key, load_on_pending=load_on_pending, query_class=query_class, info=info, omit_join=omit_join, sync_backref=sync_backref, **kw, ) def synonym( name: str, *, map_column: Optional[bool] = None, descriptor: Optional[Any] = None, comparator_factory: Optional[Type[PropComparator[_T]]] = None, init: Union[_NoArg, bool] = _NoArg.NO_ARG, repr: Union[_NoArg, bool] = _NoArg.NO_ARG, # noqa: A002 default: Union[_NoArg, _T] = _NoArg.NO_ARG, default_factory: Union[_NoArg, Callable[[], _T]] = _NoArg.NO_ARG, compare: Union[_NoArg, bool] = _NoArg.NO_ARG, kw_only: Union[_NoArg, bool] = _NoArg.NO_ARG, hash: Union[_NoArg, bool, None] = _NoArg.NO_ARG, # noqa: A002 info: Optional[_InfoType] = None, doc: Optional[str] = None, ) -> Synonym[Any]: """Denote an attribute name as a synonym to a mapped property, in that the attribute will mirror the value and expression behavior of another attribute. e.g.:: class MyClass(Base): __tablename__ = "my_table" id = Column(Integer, primary_key=True) job_status = Column(String(50)) status = synonym("job_status") :param name: the name of the existing mapped property. This can refer to the string name ORM-mapped attribute configured on the class, including column-bound attributes and relationships. :param descriptor: a Python :term:`descriptor` that will be used as a getter (and potentially a setter) when this attribute is accessed at the instance level. :param map_column: **For classical mappings and mappings against an existing Table object only**. if ``True``, the :func:`.synonym` construct will locate the :class:`_schema.Column` object upon the mapped table that would normally be associated with the attribute name of this synonym, and produce a new :class:`.ColumnProperty` that instead maps this :class:`_schema.Column` to the alternate name given as the "name" argument of the synonym; in this way, the usual step of redefining the mapping of the :class:`_schema.Column` to be under a different name is unnecessary. This is usually intended to be used when a :class:`_schema.Column` is to be replaced with an attribute that also uses a descriptor, that is, in conjunction with the :paramref:`.synonym.descriptor` parameter:: my_table = Table( "my_table", metadata, Column("id", Integer, primary_key=True), Column("job_status", String(50)), ) class MyClass: @property def _job_status_descriptor(self): return "Status: %s" % self._job_status mapper( MyClass, my_table, properties={ "job_status": synonym( "_job_status", map_column=True, descriptor=MyClass._job_status_descriptor, ) }, ) Above, the attribute named ``_job_status`` is automatically mapped to the ``job_status`` column:: >>> j1 = MyClass() >>> j1._job_status = "employed" >>> j1.job_status Status: employed When using Declarative, in order to provide a descriptor in conjunction with a synonym, use the :func:`sqlalchemy.ext.declarative.synonym_for` helper. However, note that the :ref:`hybrid properties <mapper_hybrids>` feature should usually be preferred, particularly when redefining attribute behavior. :param info: Optional data dictionary which will be populated into the :attr:`.InspectionAttr.info` attribute of this object. :param comparator_factory: A subclass of :class:`.PropComparator` that will provide custom comparison behavior at the SQL expression level. .. note:: For the use case of providing an attribute which redefines both Python-level and SQL-expression level behavior of an attribute, please refer to the Hybrid attribute introduced at :ref:`mapper_hybrids` for a more effective technique. .. seealso:: :ref:`synonyms` - Overview of synonyms :func:`.synonym_for` - a helper oriented towards Declarative :ref:`mapper_hybrids` - The Hybrid Attribute extension provides an updated approach to augmenting attribute behavior more flexibly than can be achieved with synonyms. """ return Synonym( name, map_column=map_column, descriptor=descriptor, comparator_factory=comparator_factory, attribute_options=_AttributeOptions( init, repr, default, default_factory, compare, kw_only, hash ), doc=doc, info=info, ) def create_session( bind: Optional[_SessionBind] = None, **kwargs: Any ) -> Session: r"""Create a new :class:`.Session` with no automation enabled by default. This function is used primarily for testing. The usual route to :class:`.Session` creation is via its constructor or the :func:`.sessionmaker` function. :param bind: optional, a single Connectable to use for all database access in the created :class:`~sqlalchemy.orm.session.Session`. :param \*\*kwargs: optional, passed through to the :class:`.Session` constructor. :returns: an :class:`~sqlalchemy.orm.session.Session` instance The defaults of create_session() are the opposite of that of :func:`sessionmaker`; ``autoflush`` and ``expire_on_commit`` are False. Usage:: >>> from sqlalchemy.orm import create_session >>> session = create_session() It is recommended to use :func:`sessionmaker` instead of create_session(). """ kwargs.setdefault("autoflush", False) kwargs.setdefault("expire_on_commit", False) return Session(bind=bind, **kwargs) def _mapper_fn(*arg: Any, **kw: Any) -> NoReturn: """Placeholder for the now-removed ``mapper()`` function. Classical mappings should be performed using the :meth:`_orm.registry.map_imperatively` method. This symbol remains in SQLAlchemy 2.0 to suit the deprecated use case of using the ``mapper()`` function as a target for ORM event listeners, which failed to be marked as deprecated in the 1.4 series. Global ORM mapper listeners should instead use the :class:`_orm.Mapper` class as the target. .. versionchanged:: 2.0 The ``mapper()`` function was removed; the symbol remains temporarily as a placeholder for the event listening use case. """ raise InvalidRequestError( "The 'sqlalchemy.orm.mapper()' function is removed as of " "SQLAlchemy 2.0. Use the " "'sqlalchemy.orm.registry.map_imperatively()` " "method of the ``sqlalchemy.orm.registry`` class to perform " "classical mapping." ) def dynamic_loader( argument: Optional[_RelationshipArgumentType[Any]] = None, **kw: Any ) -> RelationshipProperty[Any]: """Construct a dynamically-loading mapper property. This is essentially the same as using the ``lazy='dynamic'`` argument with :func:`relationship`:: dynamic_loader(SomeClass) # is the same as relationship(SomeClass, lazy="dynamic") See the section :ref:`dynamic_relationship` for more details on dynamic loading. """ kw["lazy"] = "dynamic" return relationship(argument, **kw) def backref(name: str, **kwargs: Any) -> ORMBackrefArgument: """When using the :paramref:`_orm.relationship.backref` parameter, provides specific parameters to be used when the new :func:`_orm.relationship` is generated. E.g.:: "items": relationship(SomeItem, backref=backref("parent", lazy="subquery")) The :paramref:`_orm.relationship.backref` parameter is generally considered to be legacy; for modern applications, using explicit :func:`_orm.relationship` constructs linked together using the :paramref:`_orm.relationship.back_populates` parameter should be preferred. .. seealso:: :ref:`relationships_backref` - background on backrefs """ # noqa: E501 return (name, kwargs) def deferred( column: _ORMColumnExprArgument[_T], *additional_columns: _ORMColumnExprArgument[Any], group: Optional[str] = None, raiseload: bool = False, comparator_factory: Optional[Type[PropComparator[_T]]] = None, init: Union[_NoArg, bool] = _NoArg.NO_ARG, repr: Union[_NoArg, bool] = _NoArg.NO_ARG, # noqa: A002 default: Optional[Any] = _NoArg.NO_ARG, default_factory: Union[_NoArg, Callable[[], _T]] = _NoArg.NO_ARG, compare: Union[_NoArg, bool] = _NoArg.NO_ARG, kw_only: Union[_NoArg, bool] = _NoArg.NO_ARG, hash: Union[_NoArg, bool, None] = _NoArg.NO_ARG, # noqa: A002 active_history: bool = False, expire_on_flush: bool = True, info: Optional[_InfoType] = None, doc: Optional[str] = None, ) -> MappedSQLExpression[_T]: r"""Indicate a column-based mapped attribute that by default will not load unless accessed. When using :func:`_orm.mapped_column`, the same functionality as that of :func:`_orm.deferred` construct is provided by using the :paramref:`_orm.mapped_column.deferred` parameter. :param \*columns: columns to be mapped. This is typically a single :class:`_schema.Column` object, however a collection is supported in order to support multiple columns mapped under the same attribute. :param raiseload: boolean, if True, indicates an exception should be raised if the load operation is to take place. .. versionadded:: 1.4 Additional arguments are the same as that of :func:`_orm.column_property`. .. seealso:: :ref:`orm_queryguide_deferred_imperative` """ return MappedSQLExpression( column, *additional_columns, attribute_options=_AttributeOptions( init, repr, default, default_factory, compare, kw_only, hash ), group=group, deferred=True, raiseload=raiseload, comparator_factory=comparator_factory, active_history=active_history, expire_on_flush=expire_on_flush, info=info, doc=doc, ) def query_expression( default_expr: _ORMColumnExprArgument[_T] = sql.null(), *, repr: Union[_NoArg, bool] = _NoArg.NO_ARG, # noqa: A002 compare: Union[_NoArg, bool] = _NoArg.NO_ARG, # noqa: A002 expire_on_flush: bool = True, info: Optional[_InfoType] = None, doc: Optional[str] = None, ) -> MappedSQLExpression[_T]: """Indicate an attribute that populates from a query-time SQL expression. :param default_expr: Optional SQL expression object that will be used in all cases if not assigned later with :func:`_orm.with_expression`. .. versionadded:: 1.2 .. seealso:: :ref:`orm_queryguide_with_expression` - background and usage examples """ prop = MappedSQLExpression( default_expr, attribute_options=_AttributeOptions( False, repr, _NoArg.NO_ARG, _NoArg.NO_ARG, compare, _NoArg.NO_ARG, _NoArg.NO_ARG, ), expire_on_flush=expire_on_flush, info=info, doc=doc, _assume_readonly_dc_attributes=True, ) prop.strategy_key = (("query_expression", True),) return prop def clear_mappers() -> None: """Remove all mappers from all classes. .. versionchanged:: 1.4 This function now locates all :class:`_orm.registry` objects and calls upon the :meth:`_orm.registry.dispose` method of each. This function removes all instrumentation from classes and disposes of their associated mappers. Once called, the classes are unmapped and can be later re-mapped with new mappers. :func:`.clear_mappers` is *not* for normal use, as there is literally no valid usage for it outside of very specific testing scenarios. Normally, mappers are permanent structural components of user-defined classes, and are never discarded independently of their class. If a mapped class itself is garbage collected, its mapper is automatically disposed of as well. As such, :func:`.clear_mappers` is only for usage in test suites that re-use the same classes with different mappings, which is itself an extremely rare use case - the only such use case is in fact SQLAlchemy's own test suite, and possibly the test suites of other ORM extension libraries which intend to test various combinations of mapper construction upon a fixed set of classes. """ mapperlib._dispose_registries(mapperlib._all_registries(), False) # I would really like a way to get the Type[] here that shows up # in a different way in typing tools, however there is no current method # that is accepted by mypy (subclass of Type[_O] works in pylance, rejected # by mypy). AliasedType = Annotated[Type[_O], "aliased"] @overload def aliased( element: Type[_O], alias: Optional[FromClause] = None, name: Optional[str] = None, flat: bool = False, adapt_on_names: bool = False, ) -> AliasedType[_O]: ... @overload def aliased( element: Union[AliasedClass[_O], Mapper[_O], AliasedInsp[_O]], alias: Optional[FromClause] = None, name: Optional[str] = None, flat: bool = False, adapt_on_names: bool = False, ) -> AliasedClass[_O]: ... @overload def aliased( element: FromClause, alias: None = None, name: Optional[str] = None, flat: bool = False, adapt_on_names: bool = False, ) -> FromClause: ... def aliased( element: Union[_EntityType[_O], FromClause], alias: Optional[FromClause] = None, name: Optional[str] = None, flat: bool = False, adapt_on_names: bool = False, ) -> Union[AliasedClass[_O], FromClause, AliasedType[_O]]: """Produce an alias of the given element, usually an :class:`.AliasedClass` instance. E.g.:: my_alias = aliased(MyClass) stmt = select(MyClass, my_alias).filter(MyClass.id > my_alias.id) result = session.execute(stmt) The :func:`.aliased` function is used to create an ad-hoc mapping of a mapped class to a new selectable. By default, a selectable is generated from the normally mapped selectable (typically a :class:`_schema.Table` ) using the :meth:`_expression.FromClause.alias` method. However, :func:`.aliased` can also be used to link the class to a new :func:`_expression.select` statement. Also, the :func:`.with_polymorphic` function is a variant of :func:`.aliased` that is intended to specify a so-called "polymorphic selectable", that corresponds to the union of several joined-inheritance subclasses at once. For convenience, the :func:`.aliased` function also accepts plain :class:`_expression.FromClause` constructs, such as a :class:`_schema.Table` or :func:`_expression.select` construct. In those cases, the :meth:`_expression.FromClause.alias` method is called on the object and the new :class:`_expression.Alias` object returned. The returned :class:`_expression.Alias` is not ORM-mapped in this case. .. seealso:: :ref:`tutorial_orm_entity_aliases` - in the :ref:`unified_tutorial` :ref:`orm_queryguide_orm_aliases` - in the :ref:`queryguide_toplevel` :param element: element to be aliased. Is normally a mapped class, but for convenience can also be a :class:`_expression.FromClause` element. :param alias: Optional selectable unit to map the element to. This is usually used to link the object to a subquery, and should be an aliased select construct as one would produce from the :meth:`_query.Query.subquery` method or the :meth:`_expression.Select.subquery` or :meth:`_expression.Select.alias` methods of the :func:`_expression.select` construct. :param name: optional string name to use for the alias, if not specified by the ``alias`` parameter. The name, among other things, forms the attribute name that will be accessible via tuples returned by a :class:`_query.Query` object. Not supported when creating aliases of :class:`_sql.Join` objects. :param flat: Boolean, will be passed through to the :meth:`_expression.FromClause.alias` call so that aliases of :class:`_expression.Join` objects will alias the individual tables inside the join, rather than creating a subquery. This is generally supported by all modern databases with regards to right-nested joins and generally produces more efficient queries. When :paramref:`_orm.aliased.flat` is combined with :paramref:`_orm.aliased.name`, the resulting joins will alias individual tables using a naming scheme similar to ``<prefix>_<tablename>``. This naming scheme is for visibility / debugging purposes only and the specific scheme is subject to change without notice. .. versionadded:: 2.0.32 added support for combining :paramref:`_orm.aliased.name` with :paramref:`_orm.aliased.flat`. Previously, this would raise ``NotImplementedError``. :param adapt_on_names: if True, more liberal "matching" will be used when mapping the mapped columns of the ORM entity to those of the given selectable - a name-based match will be performed if the given selectable doesn't otherwise have a column that corresponds to one on the entity. The use case for this is when associating an entity with some derived selectable such as one that uses aggregate functions:: class UnitPrice(Base): __tablename__ = "unit_price" ... unit_id = Column(Integer) price = Column(Numeric) aggregated_unit_price = ( Session.query(func.sum(UnitPrice.price).label("price")) .group_by(UnitPrice.unit_id) .subquery() ) aggregated_unit_price = aliased( UnitPrice, alias=aggregated_unit_price, adapt_on_names=True ) Above, functions on ``aggregated_unit_price`` which refer to ``.price`` will return the ``func.sum(UnitPrice.price).label('price')`` column, as it is matched on the name "price". Ordinarily, the "price" function wouldn't have any "column correspondence" to the actual ``UnitPrice.price`` column as it is not a proxy of the original. """ return AliasedInsp._alias_factory( element, alias=alias, name=name, flat=flat, adapt_on_names=adapt_on_names, ) def with_polymorphic( base: Union[Type[_O], Mapper[_O]], classes: Union[Literal["*"], Iterable[Type[Any]]], selectable: Union[Literal[False, None], FromClause] = False, flat: bool = False, polymorphic_on: Optional[ColumnElement[Any]] = None, aliased: bool = False, innerjoin: bool = False, adapt_on_names: bool = False, name: Optional[str] = None, _use_mapper_path: bool = False, ) -> AliasedClass[_O]: """Produce an :class:`.AliasedClass` construct which specifies columns for descendant mappers of the given base. Using this method will ensure that each descendant mapper's tables are included in the FROM clause, and will allow filter() criterion to be used against those tables. The resulting instances will also have those columns already loaded so that no "post fetch" of those columns will be required. .. seealso:: :ref:`with_polymorphic` - full discussion of :func:`_orm.with_polymorphic`. :param base: Base class to be aliased. :param classes: a single class or mapper, or list of class/mappers, which inherit from the base class. Alternatively, it may also be the string ``'*'``, in which case all descending mapped classes will be added to the FROM clause. :param aliased: when True, the selectable will be aliased. For a JOIN, this means the JOIN will be SELECTed from inside of a subquery unless the :paramref:`_orm.with_polymorphic.flat` flag is set to True, which is recommended for simpler use cases. :param flat: Boolean, will be passed through to the :meth:`_expression.FromClause.alias` call so that aliases of :class:`_expression.Join` objects will alias the individual tables inside the join, rather than creating a subquery. This is generally supported by all modern databases with regards to right-nested joins and generally produces more efficient queries. Setting this flag is recommended as long as the resulting SQL is functional. :param selectable: a table or subquery that will be used in place of the generated FROM clause. This argument is required if any of the desired classes use concrete table inheritance, since SQLAlchemy currently cannot generate UNIONs among tables automatically. If used, the ``selectable`` argument must represent the full set of tables and columns mapped by every mapped class. Otherwise, the unaccounted mapped columns will result in their table being appended directly to the FROM clause which will usually lead to incorrect results. When left at its default value of ``False``, the polymorphic selectable assigned to the base mapper is used for selecting rows. However, it may also be passed as ``None``, which will bypass the configured polymorphic selectable and instead construct an ad-hoc selectable for the target classes given; for joined table inheritance this will be a join that includes all target mappers and their subclasses. :param polymorphic_on: a column to be used as the "discriminator" column for the given selectable. If not given, the polymorphic_on attribute of the base classes' mapper will be used, if any. This is useful for mappings that don't have polymorphic loading behavior by default. :param innerjoin: if True, an INNER JOIN will be used. This should only be specified if querying for one specific subtype only :param adapt_on_names: Passes through the :paramref:`_orm.aliased.adapt_on_names` parameter to the aliased object. This may be useful in situations where the given selectable is not directly related to the existing mapped selectable. .. versionadded:: 1.4.33 :param name: Name given to the generated :class:`.AliasedClass`. .. versionadded:: 2.0.31 """ return AliasedInsp._with_polymorphic_factory( base, classes, selectable=selectable, flat=flat, polymorphic_on=polymorphic_on, adapt_on_names=adapt_on_names, aliased=aliased, innerjoin=innerjoin, name=name, _use_mapper_path=_use_mapper_path, ) def join( left: _FromClauseArgument, right: _FromClauseArgument, onclause: Optional[_OnClauseArgument] = None, isouter: bool = False, full: bool = False, ) -> _ORMJoin: r"""Produce an inner join between left and right clauses. :func:`_orm.join` is an extension to the core join interface provided by :func:`_expression.join()`, where the left and right selectable may be not only core selectable objects such as :class:`_schema.Table`, but also mapped classes or :class:`.AliasedClass` instances. The "on" clause can be a SQL expression or an ORM mapped attribute referencing a configured :func:`_orm.relationship`. :func:`_orm.join` is not commonly needed in modern usage, as its functionality is encapsulated within that of the :meth:`_sql.Select.join` and :meth:`_query.Query.join` methods. which feature a significant amount of automation beyond :func:`_orm.join` by itself. Explicit use of :func:`_orm.join` with ORM-enabled SELECT statements involves use of the :meth:`_sql.Select.select_from` method, as in:: from sqlalchemy.orm import join stmt = ( select(User) .select_from(join(User, Address, User.addresses)) .filter(Address.email_address == "foo@bar.com") ) In modern SQLAlchemy the above join can be written more succinctly as:: stmt = ( select(User) .join(User.addresses) .filter(Address.email_address == "foo@bar.com") ) .. warning:: using :func:`_orm.join` directly may not work properly with modern ORM options such as :func:`_orm.with_loader_criteria`. It is strongly recommended to use the idiomatic join patterns provided by methods such as :meth:`.Select.join` and :meth:`.Select.join_from` when creating ORM joins. .. seealso:: :ref:`orm_queryguide_joins` - in the :ref:`queryguide_toplevel` for background on idiomatic ORM join patterns """ return _ORMJoin(left, right, onclause, isouter, full) def outerjoin( left: _FromClauseArgument, right: _FromClauseArgument, onclause: Optional[_OnClauseArgument] = None, full: bool = False, ) -> _ORMJoin: """Produce a left outer join between left and right clauses. This is the "outer join" version of the :func:`_orm.join` function, featuring the same behavior except that an OUTER JOIN is generated. See that function's documentation for other usage details. """ return _ORMJoin(left, right, onclause, True, full) sqlalchemy/orm/_typing.py 0000755 00000011555 15125143220 0011533 0 ustar 00 # orm/_typing.py # Copyright (C) 2022-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php from __future__ import annotations import operator from typing import Any from typing import Dict from typing import Mapping from typing import Optional from typing import Tuple from typing import Type from typing import TYPE_CHECKING from typing import TypeVar from typing import Union from ..engine.interfaces import _CoreKnownExecutionOptions from ..sql import roles from ..sql._orm_types import DMLStrategyArgument as DMLStrategyArgument from ..sql._orm_types import ( SynchronizeSessionArgument as SynchronizeSessionArgument, ) from ..sql._typing import _HasClauseElement from ..sql.elements import ColumnElement from ..util.typing import Protocol from ..util.typing import TypeGuard if TYPE_CHECKING: from .attributes import AttributeImpl from .attributes import CollectionAttributeImpl from .attributes import HasCollectionAdapter from .attributes import QueryableAttribute from .base import PassiveFlag from .decl_api import registry as _registry_type from .interfaces import InspectionAttr from .interfaces import MapperProperty from .interfaces import ORMOption from .interfaces import UserDefinedOption from .mapper import Mapper from .relationships import RelationshipProperty from .state import InstanceState from .util import AliasedClass from .util import AliasedInsp from ..sql._typing import _CE from ..sql.base import ExecutableOption _T = TypeVar("_T", bound=Any) _T_co = TypeVar("_T_co", bound=Any, covariant=True) _O = TypeVar("_O", bound=object) """The 'ORM mapped object' type. """ if TYPE_CHECKING: _RegistryType = _registry_type _InternalEntityType = Union["Mapper[_T]", "AliasedInsp[_T]"] _ExternalEntityType = Union[Type[_T], "AliasedClass[_T]"] _EntityType = Union[ Type[_T], "AliasedClass[_T]", "Mapper[_T]", "AliasedInsp[_T]" ] _ClassDict = Mapping[str, Any] _InstanceDict = Dict[str, Any] _IdentityKeyType = Tuple[Type[_T], Tuple[Any, ...], Optional[Any]] _ORMColumnExprArgument = Union[ ColumnElement[_T], _HasClauseElement[_T], roles.ExpressionElementRole[_T], ] _ORMCOLEXPR = TypeVar("_ORMCOLEXPR", bound=ColumnElement[Any]) class _OrmKnownExecutionOptions(_CoreKnownExecutionOptions, total=False): populate_existing: bool autoflush: bool synchronize_session: SynchronizeSessionArgument dml_strategy: DMLStrategyArgument is_delete_using: bool is_update_from: bool render_nulls: bool OrmExecuteOptionsParameter = Union[ _OrmKnownExecutionOptions, Mapping[str, Any] ] class _ORMAdapterProto(Protocol): """protocol for the :class:`.AliasedInsp._orm_adapt_element` method which is a synonym for :class:`.AliasedInsp._adapt_element`. """ def __call__(self, obj: _CE, key: Optional[str] = None) -> _CE: ... class _LoaderCallable(Protocol): def __call__( self, state: InstanceState[Any], passive: PassiveFlag ) -> Any: ... def is_orm_option( opt: ExecutableOption, ) -> TypeGuard[ORMOption]: return not opt._is_core def is_user_defined_option( opt: ExecutableOption, ) -> TypeGuard[UserDefinedOption]: return not opt._is_core and opt._is_user_defined # type: ignore def is_composite_class(obj: Any) -> bool: # inlining is_dataclass(obj) return hasattr(obj, "__composite_values__") or hasattr( obj, "__dataclass_fields__" ) if TYPE_CHECKING: def insp_is_mapper_property( obj: Any, ) -> TypeGuard[MapperProperty[Any]]: ... def insp_is_mapper(obj: Any) -> TypeGuard[Mapper[Any]]: ... def insp_is_aliased_class(obj: Any) -> TypeGuard[AliasedInsp[Any]]: ... def insp_is_attribute( obj: InspectionAttr, ) -> TypeGuard[QueryableAttribute[Any]]: ... def attr_is_internal_proxy( obj: InspectionAttr, ) -> TypeGuard[QueryableAttribute[Any]]: ... def prop_is_relationship( prop: MapperProperty[Any], ) -> TypeGuard[RelationshipProperty[Any]]: ... def is_collection_impl( impl: AttributeImpl, ) -> TypeGuard[CollectionAttributeImpl]: ... def is_has_collection_adapter( impl: AttributeImpl, ) -> TypeGuard[HasCollectionAdapter]: ... else: insp_is_mapper_property = operator.attrgetter("is_property") insp_is_mapper = operator.attrgetter("is_mapper") insp_is_aliased_class = operator.attrgetter("is_aliased_class") insp_is_attribute = operator.attrgetter("is_attribute") attr_is_internal_proxy = operator.attrgetter("_is_internal_proxy") is_collection_impl = operator.attrgetter("collection") prop_is_relationship = operator.attrgetter("_is_relationship") is_has_collection_adapter = operator.attrgetter( "_is_has_collection_adapter" ) sqlalchemy/orm/persistence.py 0000755 00000170405 15125143220 0012406 0 ustar 00 # orm/persistence.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors """private module containing functions used to emit INSERT, UPDATE and DELETE statements on behalf of a :class:`_orm.Mapper` and its descending mappers. The functions here are called only by the unit of work functions in unitofwork.py. """ from __future__ import annotations from itertools import chain from itertools import groupby from itertools import zip_longest import operator from . import attributes from . import exc as orm_exc from . import loading from . import sync from .base import state_str from .. import exc as sa_exc from .. import future from .. import sql from .. import util from ..engine import cursor as _cursor from ..sql import operators from ..sql.elements import BooleanClauseList from ..sql.selectable import LABEL_STYLE_TABLENAME_PLUS_COL def save_obj(base_mapper, states, uowtransaction, single=False): """Issue ``INSERT`` and/or ``UPDATE`` statements for a list of objects. This is called within the context of a UOWTransaction during a flush operation, given a list of states to be flushed. The base mapper in an inheritance hierarchy handles the inserts/ updates for all descendant mappers. """ # if batch=false, call _save_obj separately for each object if not single and not base_mapper.batch: for state in _sort_states(base_mapper, states): save_obj(base_mapper, [state], uowtransaction, single=True) return states_to_update = [] states_to_insert = [] for ( state, dict_, mapper, connection, has_identity, row_switch, update_version_id, ) in _organize_states_for_save(base_mapper, states, uowtransaction): if has_identity or row_switch: states_to_update.append( (state, dict_, mapper, connection, update_version_id) ) else: states_to_insert.append((state, dict_, mapper, connection)) for table, mapper in base_mapper._sorted_tables.items(): if table not in mapper._pks_by_table: continue insert = _collect_insert_commands(table, states_to_insert) update = _collect_update_commands( uowtransaction, table, states_to_update ) _emit_update_statements( base_mapper, uowtransaction, mapper, table, update, ) _emit_insert_statements( base_mapper, uowtransaction, mapper, table, insert, ) _finalize_insert_update_commands( base_mapper, uowtransaction, chain( ( (state, state_dict, mapper, connection, False) for (state, state_dict, mapper, connection) in states_to_insert ), ( (state, state_dict, mapper, connection, True) for ( state, state_dict, mapper, connection, update_version_id, ) in states_to_update ), ), ) def post_update(base_mapper, states, uowtransaction, post_update_cols): """Issue UPDATE statements on behalf of a relationship() which specifies post_update. """ states_to_update = list( _organize_states_for_post_update(base_mapper, states, uowtransaction) ) for table, mapper in base_mapper._sorted_tables.items(): if table not in mapper._pks_by_table: continue update = ( ( state, state_dict, sub_mapper, connection, ( mapper._get_committed_state_attr_by_column( state, state_dict, mapper.version_id_col ) if mapper.version_id_col is not None else None ), ) for state, state_dict, sub_mapper, connection in states_to_update if table in sub_mapper._pks_by_table ) update = _collect_post_update_commands( base_mapper, uowtransaction, table, update, post_update_cols ) _emit_post_update_statements( base_mapper, uowtransaction, mapper, table, update, ) def delete_obj(base_mapper, states, uowtransaction): """Issue ``DELETE`` statements for a list of objects. This is called within the context of a UOWTransaction during a flush operation. """ states_to_delete = list( _organize_states_for_delete(base_mapper, states, uowtransaction) ) table_to_mapper = base_mapper._sorted_tables for table in reversed(list(table_to_mapper.keys())): mapper = table_to_mapper[table] if table not in mapper._pks_by_table: continue elif mapper.inherits and mapper.passive_deletes: continue delete = _collect_delete_commands( base_mapper, uowtransaction, table, states_to_delete ) _emit_delete_statements( base_mapper, uowtransaction, mapper, table, delete, ) for ( state, state_dict, mapper, connection, update_version_id, ) in states_to_delete: mapper.dispatch.after_delete(mapper, connection, state) def _organize_states_for_save(base_mapper, states, uowtransaction): """Make an initial pass across a set of states for INSERT or UPDATE. This includes splitting out into distinct lists for each, calling before_insert/before_update, obtaining key information for each state including its dictionary, mapper, the connection to use for the execution per state, and the identity flag. """ for state, dict_, mapper, connection in _connections_for_states( base_mapper, uowtransaction, states ): has_identity = bool(state.key) instance_key = state.key or mapper._identity_key_from_state(state) row_switch = update_version_id = None # call before_XXX extensions if not has_identity: mapper.dispatch.before_insert(mapper, connection, state) else: mapper.dispatch.before_update(mapper, connection, state) if mapper._validate_polymorphic_identity: mapper._validate_polymorphic_identity(mapper, state, dict_) # detect if we have a "pending" instance (i.e. has # no instance_key attached to it), and another instance # with the same identity key already exists as persistent. # convert to an UPDATE if so. if ( not has_identity and instance_key in uowtransaction.session.identity_map ): instance = uowtransaction.session.identity_map[instance_key] existing = attributes.instance_state(instance) if not uowtransaction.was_already_deleted(existing): if not uowtransaction.is_deleted(existing): util.warn( "New instance %s with identity key %s conflicts " "with persistent instance %s" % (state_str(state), instance_key, state_str(existing)) ) else: base_mapper._log_debug( "detected row switch for identity %s. " "will update %s, remove %s from " "transaction", instance_key, state_str(state), state_str(existing), ) # remove the "delete" flag from the existing element uowtransaction.remove_state_actions(existing) row_switch = existing if (has_identity or row_switch) and mapper.version_id_col is not None: update_version_id = mapper._get_committed_state_attr_by_column( row_switch if row_switch else state, row_switch.dict if row_switch else dict_, mapper.version_id_col, ) yield ( state, dict_, mapper, connection, has_identity, row_switch, update_version_id, ) def _organize_states_for_post_update(base_mapper, states, uowtransaction): """Make an initial pass across a set of states for UPDATE corresponding to post_update. This includes obtaining key information for each state including its dictionary, mapper, the connection to use for the execution per state. """ return _connections_for_states(base_mapper, uowtransaction, states) def _organize_states_for_delete(base_mapper, states, uowtransaction): """Make an initial pass across a set of states for DELETE. This includes calling out before_delete and obtaining key information for each state including its dictionary, mapper, the connection to use for the execution per state. """ for state, dict_, mapper, connection in _connections_for_states( base_mapper, uowtransaction, states ): mapper.dispatch.before_delete(mapper, connection, state) if mapper.version_id_col is not None: update_version_id = mapper._get_committed_state_attr_by_column( state, dict_, mapper.version_id_col ) else: update_version_id = None yield (state, dict_, mapper, connection, update_version_id) def _collect_insert_commands( table, states_to_insert, *, bulk=False, return_defaults=False, render_nulls=False, include_bulk_keys=(), ): """Identify sets of values to use in INSERT statements for a list of states. """ for state, state_dict, mapper, connection in states_to_insert: if table not in mapper._pks_by_table: continue params = {} value_params = {} propkey_to_col = mapper._propkey_to_col[table] eval_none = mapper._insert_cols_evaluating_none[table] for propkey in set(propkey_to_col).intersection(state_dict): value = state_dict[propkey] col = propkey_to_col[propkey] if value is None and col not in eval_none and not render_nulls: continue elif not bulk and ( hasattr(value, "__clause_element__") or isinstance(value, sql.ClauseElement) ): value_params[col] = ( value.__clause_element__() if hasattr(value, "__clause_element__") else value ) else: params[col.key] = value if not bulk: # for all the columns that have no default and we don't have # a value and where "None" is not a special value, add # explicit None to the INSERT. This is a legacy behavior # which might be worth removing, as it should not be necessary # and also produces confusion, given that "missing" and None # now have distinct meanings for colkey in ( mapper._insert_cols_as_none[table] .difference(params) .difference([c.key for c in value_params]) ): params[colkey] = None if not bulk or return_defaults: # params are in terms of Column key objects, so # compare to pk_keys_by_table has_all_pks = mapper._pk_keys_by_table[table].issubset(params) if mapper.base_mapper._prefer_eager_defaults( connection.dialect, table ): has_all_defaults = mapper._server_default_col_keys[ table ].issubset(params) else: has_all_defaults = True else: has_all_defaults = has_all_pks = True if ( mapper.version_id_generator is not False and mapper.version_id_col is not None and mapper.version_id_col in mapper._cols_by_table[table] ): params[mapper.version_id_col.key] = mapper.version_id_generator( None ) if bulk: if mapper._set_polymorphic_identity: params.setdefault( mapper._polymorphic_attr_key, mapper.polymorphic_identity ) if include_bulk_keys: params.update((k, state_dict[k]) for k in include_bulk_keys) yield ( state, state_dict, params, mapper, connection, value_params, has_all_pks, has_all_defaults, ) def _collect_update_commands( uowtransaction, table, states_to_update, *, bulk=False, use_orm_update_stmt=None, include_bulk_keys=(), ): """Identify sets of values to use in UPDATE statements for a list of states. This function works intricately with the history system to determine exactly what values should be updated as well as how the row should be matched within an UPDATE statement. Includes some tricky scenarios where the primary key of an object might have been changed. """ for ( state, state_dict, mapper, connection, update_version_id, ) in states_to_update: if table not in mapper._pks_by_table: continue pks = mapper._pks_by_table[table] if use_orm_update_stmt is not None: # TODO: ordered values, etc value_params = use_orm_update_stmt._values else: value_params = {} propkey_to_col = mapper._propkey_to_col[table] if bulk: # keys here are mapped attribute keys, so # look at mapper attribute keys for pk params = { propkey_to_col[propkey].key: state_dict[propkey] for propkey in set(propkey_to_col) .intersection(state_dict) .difference(mapper._pk_attr_keys_by_table[table]) } has_all_defaults = True else: params = {} for propkey in set(propkey_to_col).intersection( state.committed_state ): value = state_dict[propkey] col = propkey_to_col[propkey] if hasattr(value, "__clause_element__") or isinstance( value, sql.ClauseElement ): value_params[col] = ( value.__clause_element__() if hasattr(value, "__clause_element__") else value ) # guard against values that generate non-__nonzero__ # objects for __eq__() elif ( state.manager[propkey].impl.is_equal( value, state.committed_state[propkey] ) is not True ): params[col.key] = value if mapper.base_mapper.eager_defaults is True: has_all_defaults = ( mapper._server_onupdate_default_col_keys[table] ).issubset(params) else: has_all_defaults = True if ( update_version_id is not None and mapper.version_id_col in mapper._cols_by_table[table] ): if not bulk and not (params or value_params): # HACK: check for history in other tables, in case the # history is only in a different table than the one # where the version_id_col is. This logic was lost # from 0.9 -> 1.0.0 and restored in 1.0.6. for prop in mapper._columntoproperty.values(): history = state.manager[prop.key].impl.get_history( state, state_dict, attributes.PASSIVE_NO_INITIALIZE ) if history.added: break else: # no net change, break continue col = mapper.version_id_col no_params = not params and not value_params params[col._label] = update_version_id if ( bulk or col.key not in params ) and mapper.version_id_generator is not False: val = mapper.version_id_generator(update_version_id) params[col.key] = val elif mapper.version_id_generator is False and no_params: # no version id generator, no values set on the table, # and version id wasn't manually incremented. # set version id to itself so we get an UPDATE # statement params[col.key] = update_version_id elif not (params or value_params): continue has_all_pks = True expect_pk_cascaded = False if bulk: # keys here are mapped attribute keys, so # look at mapper attribute keys for pk pk_params = { propkey_to_col[propkey]._label: state_dict.get(propkey) for propkey in set(propkey_to_col).intersection( mapper._pk_attr_keys_by_table[table] ) } if util.NONE_SET.intersection(pk_params.values()): raise sa_exc.InvalidRequestError( f"No primary key value supplied for column(s) " f"""{ ', '.join( str(c) for c in pks if pk_params[c._label] is None ) }; """ "per-row ORM Bulk UPDATE by Primary Key requires that " "records contain primary key values", code="bupq", ) else: pk_params = {} for col in pks: propkey = mapper._columntoproperty[col].key history = state.manager[propkey].impl.get_history( state, state_dict, attributes.PASSIVE_OFF ) if history.added: if ( not history.deleted or ("pk_cascaded", state, col) in uowtransaction.attributes ): expect_pk_cascaded = True pk_params[col._label] = history.added[0] params.pop(col.key, None) else: # else, use the old value to locate the row pk_params[col._label] = history.deleted[0] if col in value_params: has_all_pks = False else: pk_params[col._label] = history.unchanged[0] if pk_params[col._label] is None: raise orm_exc.FlushError( "Can't update table %s using NULL for primary " "key value on column %s" % (table, col) ) if include_bulk_keys: params.update((k, state_dict[k]) for k in include_bulk_keys) if params or value_params: params.update(pk_params) yield ( state, state_dict, params, mapper, connection, value_params, has_all_defaults, has_all_pks, ) elif expect_pk_cascaded: # no UPDATE occurs on this table, but we expect that CASCADE rules # have changed the primary key of the row; propagate this event to # other columns that expect to have been modified. this normally # occurs after the UPDATE is emitted however we invoke it here # explicitly in the absence of our invoking an UPDATE for m, equated_pairs in mapper._table_to_equated[table]: sync.populate( state, m, state, m, equated_pairs, uowtransaction, mapper.passive_updates, ) def _collect_post_update_commands( base_mapper, uowtransaction, table, states_to_update, post_update_cols ): """Identify sets of values to use in UPDATE statements for a list of states within a post_update operation. """ for ( state, state_dict, mapper, connection, update_version_id, ) in states_to_update: # assert table in mapper._pks_by_table pks = mapper._pks_by_table[table] params = {} hasdata = False for col in mapper._cols_by_table[table]: if col in pks: params[col._label] = mapper._get_state_attr_by_column( state, state_dict, col, passive=attributes.PASSIVE_OFF ) elif col in post_update_cols or col.onupdate is not None: prop = mapper._columntoproperty[col] history = state.manager[prop.key].impl.get_history( state, state_dict, attributes.PASSIVE_NO_INITIALIZE ) if history.added: value = history.added[0] params[col.key] = value hasdata = True if hasdata: if ( update_version_id is not None and mapper.version_id_col in mapper._cols_by_table[table] ): col = mapper.version_id_col params[col._label] = update_version_id if ( bool(state.key) and col.key not in params and mapper.version_id_generator is not False ): val = mapper.version_id_generator(update_version_id) params[col.key] = val yield state, state_dict, mapper, connection, params def _collect_delete_commands( base_mapper, uowtransaction, table, states_to_delete ): """Identify values to use in DELETE statements for a list of states to be deleted.""" for ( state, state_dict, mapper, connection, update_version_id, ) in states_to_delete: if table not in mapper._pks_by_table: continue params = {} for col in mapper._pks_by_table[table]: params[col.key] = value = ( mapper._get_committed_state_attr_by_column( state, state_dict, col ) ) if value is None: raise orm_exc.FlushError( "Can't delete from table %s " "using NULL for primary " "key value on column %s" % (table, col) ) if ( update_version_id is not None and mapper.version_id_col in mapper._cols_by_table[table] ): params[mapper.version_id_col.key] = update_version_id yield params, connection def _emit_update_statements( base_mapper, uowtransaction, mapper, table, update, *, bookkeeping=True, use_orm_update_stmt=None, enable_check_rowcount=True, ): """Emit UPDATE statements corresponding to value lists collected by _collect_update_commands().""" needs_version_id = ( mapper.version_id_col is not None and mapper.version_id_col in mapper._cols_by_table[table] ) execution_options = {"compiled_cache": base_mapper._compiled_cache} def update_stmt(existing_stmt=None): clauses = BooleanClauseList._construct_raw(operators.and_) for col in mapper._pks_by_table[table]: clauses._append_inplace( col == sql.bindparam(col._label, type_=col.type) ) if needs_version_id: clauses._append_inplace( mapper.version_id_col == sql.bindparam( mapper.version_id_col._label, type_=mapper.version_id_col.type, ) ) if existing_stmt is not None: stmt = existing_stmt.where(clauses) else: stmt = table.update().where(clauses) return stmt if use_orm_update_stmt is not None: cached_stmt = update_stmt(use_orm_update_stmt) else: cached_stmt = base_mapper._memo(("update", table), update_stmt) for ( (connection, paramkeys, hasvalue, has_all_defaults, has_all_pks), records, ) in groupby( update, lambda rec: ( rec[4], # connection set(rec[2]), # set of parameter keys bool(rec[5]), # whether or not we have "value" parameters rec[6], # has_all_defaults rec[7], # has all pks ), ): rows = 0 records = list(records) statement = cached_stmt if use_orm_update_stmt is not None: statement = statement._annotate( { "_emit_update_table": table, "_emit_update_mapper": mapper, } ) return_defaults = False if not has_all_pks: statement = statement.return_defaults(*mapper._pks_by_table[table]) return_defaults = True if ( bookkeeping and not has_all_defaults and mapper.base_mapper.eager_defaults is True # change as of #8889 - if RETURNING is not going to be used anyway, # (applies to MySQL, MariaDB which lack UPDATE RETURNING) ensure # we can do an executemany UPDATE which is more efficient and table.implicit_returning and connection.dialect.update_returning ): statement = statement.return_defaults( *mapper._server_onupdate_default_cols[table] ) return_defaults = True if mapper._version_id_has_server_side_value: statement = statement.return_defaults(mapper.version_id_col) return_defaults = True assert_singlerow = connection.dialect.supports_sane_rowcount assert_multirow = ( assert_singlerow and connection.dialect.supports_sane_multi_rowcount ) # change as of #8889 - if RETURNING is not going to be used anyway, # (applies to MySQL, MariaDB which lack UPDATE RETURNING) ensure # we can do an executemany UPDATE which is more efficient allow_executemany = not return_defaults and not needs_version_id if hasvalue: for ( state, state_dict, params, mapper, connection, value_params, has_all_defaults, has_all_pks, ) in records: c = connection.execute( statement.values(value_params), params, execution_options=execution_options, ) if bookkeeping: _postfetch( mapper, uowtransaction, table, state, state_dict, c, c.context.compiled_parameters[0], value_params, True, c.returned_defaults, ) rows += c.rowcount check_rowcount = enable_check_rowcount and assert_singlerow else: if not allow_executemany: check_rowcount = enable_check_rowcount and assert_singlerow for ( state, state_dict, params, mapper, connection, value_params, has_all_defaults, has_all_pks, ) in records: c = connection.execute( statement, params, execution_options=execution_options ) # TODO: why with bookkeeping=False? if bookkeeping: _postfetch( mapper, uowtransaction, table, state, state_dict, c, c.context.compiled_parameters[0], value_params, True, c.returned_defaults, ) rows += c.rowcount else: multiparams = [rec[2] for rec in records] check_rowcount = enable_check_rowcount and ( assert_multirow or (assert_singlerow and len(multiparams) == 1) ) c = connection.execute( statement, multiparams, execution_options=execution_options ) rows += c.rowcount for ( state, state_dict, params, mapper, connection, value_params, has_all_defaults, has_all_pks, ) in records: if bookkeeping: _postfetch( mapper, uowtransaction, table, state, state_dict, c, c.context.compiled_parameters[0], value_params, True, ( c.returned_defaults if not c.context.executemany else None ), ) if check_rowcount: if rows != len(records): raise orm_exc.StaleDataError( "UPDATE statement on table '%s' expected to " "update %d row(s); %d were matched." % (table.description, len(records), rows) ) elif needs_version_id: util.warn( "Dialect %s does not support updated rowcount " "- versioning cannot be verified." % c.dialect.dialect_description ) def _emit_insert_statements( base_mapper, uowtransaction, mapper, table, insert, *, bookkeeping=True, use_orm_insert_stmt=None, execution_options=None, ): """Emit INSERT statements corresponding to value lists collected by _collect_insert_commands().""" if use_orm_insert_stmt is not None: cached_stmt = use_orm_insert_stmt exec_opt = util.EMPTY_DICT # if a user query with RETURNING was passed, we definitely need # to use RETURNING. returning_is_required_anyway = bool(use_orm_insert_stmt._returning) deterministic_results_reqd = ( returning_is_required_anyway and use_orm_insert_stmt._sort_by_parameter_order ) or bookkeeping else: returning_is_required_anyway = False deterministic_results_reqd = bookkeeping cached_stmt = base_mapper._memo(("insert", table), table.insert) exec_opt = {"compiled_cache": base_mapper._compiled_cache} if execution_options: execution_options = util.EMPTY_DICT.merge_with( exec_opt, execution_options ) else: execution_options = exec_opt return_result = None for ( (connection, _, hasvalue, has_all_pks, has_all_defaults), records, ) in groupby( insert, lambda rec: ( rec[4], # connection set(rec[2]), # parameter keys bool(rec[5]), # whether we have "value" parameters rec[6], rec[7], ), ): statement = cached_stmt if use_orm_insert_stmt is not None: statement = statement._annotate( { "_emit_insert_table": table, "_emit_insert_mapper": mapper, } ) if ( ( not bookkeeping or ( has_all_defaults or not base_mapper._prefer_eager_defaults( connection.dialect, table ) or not table.implicit_returning or not connection.dialect.insert_returning ) ) and not returning_is_required_anyway and has_all_pks and not hasvalue ): # the "we don't need newly generated values back" section. # here we have all the PKs, all the defaults or we don't want # to fetch them, or the dialect doesn't support RETURNING at all # so we have to post-fetch / use lastrowid anyway. records = list(records) multiparams = [rec[2] for rec in records] result = connection.execute( statement, multiparams, execution_options=execution_options ) if bookkeeping: for ( ( state, state_dict, params, mapper_rec, conn, value_params, has_all_pks, has_all_defaults, ), last_inserted_params, ) in zip(records, result.context.compiled_parameters): if state: _postfetch( mapper_rec, uowtransaction, table, state, state_dict, result, last_inserted_params, value_params, False, ( result.returned_defaults if not result.context.executemany else None ), ) else: _postfetch_bulk_save(mapper_rec, state_dict, table) else: # here, we need defaults and/or pk values back or we otherwise # know that we are using RETURNING in any case records = list(records) if returning_is_required_anyway or ( table.implicit_returning and not hasvalue and len(records) > 1 ): if ( deterministic_results_reqd and connection.dialect.insert_executemany_returning_sort_by_parameter_order # noqa: E501 ) or ( not deterministic_results_reqd and connection.dialect.insert_executemany_returning ): do_executemany = True elif returning_is_required_anyway: if deterministic_results_reqd: dt = " with RETURNING and sort by parameter order" else: dt = " with RETURNING" raise sa_exc.InvalidRequestError( f"Can't use explicit RETURNING for bulk INSERT " f"operation with " f"{connection.dialect.dialect_description} backend; " f"executemany{dt} is not enabled for this dialect." ) else: do_executemany = False else: do_executemany = False if use_orm_insert_stmt is None: if ( not has_all_defaults and base_mapper._prefer_eager_defaults( connection.dialect, table ) ): statement = statement.return_defaults( *mapper._server_default_cols[table], sort_by_parameter_order=bookkeeping, ) if mapper.version_id_col is not None: statement = statement.return_defaults( mapper.version_id_col, sort_by_parameter_order=bookkeeping, ) elif do_executemany: statement = statement.return_defaults( *table.primary_key, sort_by_parameter_order=bookkeeping ) if do_executemany: multiparams = [rec[2] for rec in records] result = connection.execute( statement, multiparams, execution_options=execution_options ) if use_orm_insert_stmt is not None: if return_result is None: return_result = result else: return_result = return_result.splice_vertically(result) if bookkeeping: for ( ( state, state_dict, params, mapper_rec, conn, value_params, has_all_pks, has_all_defaults, ), last_inserted_params, inserted_primary_key, returned_defaults, ) in zip_longest( records, result.context.compiled_parameters, result.inserted_primary_key_rows, result.returned_defaults_rows or (), ): if inserted_primary_key is None: # this is a real problem and means that we didn't # get back as many PK rows. we can't continue # since this indicates PK rows were missing, which # means we likely mis-populated records starting # at that point with incorrectly matched PK # values. raise orm_exc.FlushError( "Multi-row INSERT statement for %s did not " "produce " "the correct number of INSERTed rows for " "RETURNING. Ensure there are no triggers or " "special driver issues preventing INSERT from " "functioning properly." % mapper_rec ) for pk, col in zip( inserted_primary_key, mapper._pks_by_table[table], ): prop = mapper_rec._columntoproperty[col] if state_dict.get(prop.key) is None: state_dict[prop.key] = pk if state: _postfetch( mapper_rec, uowtransaction, table, state, state_dict, result, last_inserted_params, value_params, False, returned_defaults, ) else: _postfetch_bulk_save(mapper_rec, state_dict, table) else: assert not returning_is_required_anyway for ( state, state_dict, params, mapper_rec, connection, value_params, has_all_pks, has_all_defaults, ) in records: if value_params: result = connection.execute( statement.values(value_params), params, execution_options=execution_options, ) else: result = connection.execute( statement, params, execution_options=execution_options, ) primary_key = result.inserted_primary_key if primary_key is None: raise orm_exc.FlushError( "Single-row INSERT statement for %s " "did not produce a " "new primary key result " "being invoked. Ensure there are no triggers or " "special driver issues preventing INSERT from " "functioning properly." % (mapper_rec,) ) for pk, col in zip( primary_key, mapper._pks_by_table[table] ): prop = mapper_rec._columntoproperty[col] if ( col in value_params or state_dict.get(prop.key) is None ): state_dict[prop.key] = pk if bookkeeping: if state: _postfetch( mapper_rec, uowtransaction, table, state, state_dict, result, result.context.compiled_parameters[0], value_params, False, ( result.returned_defaults if not result.context.executemany else None ), ) else: _postfetch_bulk_save(mapper_rec, state_dict, table) if use_orm_insert_stmt is not None: if return_result is None: return _cursor.null_dml_result() else: return return_result def _emit_post_update_statements( base_mapper, uowtransaction, mapper, table, update ): """Emit UPDATE statements corresponding to value lists collected by _collect_post_update_commands().""" execution_options = {"compiled_cache": base_mapper._compiled_cache} needs_version_id = ( mapper.version_id_col is not None and mapper.version_id_col in mapper._cols_by_table[table] ) def update_stmt(): clauses = BooleanClauseList._construct_raw(operators.and_) for col in mapper._pks_by_table[table]: clauses._append_inplace( col == sql.bindparam(col._label, type_=col.type) ) if needs_version_id: clauses._append_inplace( mapper.version_id_col == sql.bindparam( mapper.version_id_col._label, type_=mapper.version_id_col.type, ) ) stmt = table.update().where(clauses) return stmt statement = base_mapper._memo(("post_update", table), update_stmt) if mapper._version_id_has_server_side_value: statement = statement.return_defaults(mapper.version_id_col) # execute each UPDATE in the order according to the original # list of states to guarantee row access order, but # also group them into common (connection, cols) sets # to support executemany(). for key, records in groupby( update, lambda rec: (rec[3], set(rec[4])), # connection # parameter keys ): rows = 0 records = list(records) connection = key[0] assert_singlerow = connection.dialect.supports_sane_rowcount assert_multirow = ( assert_singlerow and connection.dialect.supports_sane_multi_rowcount ) allow_executemany = not needs_version_id or assert_multirow if not allow_executemany: check_rowcount = assert_singlerow for state, state_dict, mapper_rec, connection, params in records: c = connection.execute( statement, params, execution_options=execution_options ) _postfetch_post_update( mapper_rec, uowtransaction, table, state, state_dict, c, c.context.compiled_parameters[0], ) rows += c.rowcount else: multiparams = [ params for state, state_dict, mapper_rec, conn, params in records ] check_rowcount = assert_multirow or ( assert_singlerow and len(multiparams) == 1 ) c = connection.execute( statement, multiparams, execution_options=execution_options ) rows += c.rowcount for state, state_dict, mapper_rec, connection, params in records: _postfetch_post_update( mapper_rec, uowtransaction, table, state, state_dict, c, c.context.compiled_parameters[0], ) if check_rowcount: if rows != len(records): raise orm_exc.StaleDataError( "UPDATE statement on table '%s' expected to " "update %d row(s); %d were matched." % (table.description, len(records), rows) ) elif needs_version_id: util.warn( "Dialect %s does not support updated rowcount " "- versioning cannot be verified." % c.dialect.dialect_description ) def _emit_delete_statements( base_mapper, uowtransaction, mapper, table, delete ): """Emit DELETE statements corresponding to value lists collected by _collect_delete_commands().""" need_version_id = ( mapper.version_id_col is not None and mapper.version_id_col in mapper._cols_by_table[table] ) def delete_stmt(): clauses = BooleanClauseList._construct_raw(operators.and_) for col in mapper._pks_by_table[table]: clauses._append_inplace( col == sql.bindparam(col.key, type_=col.type) ) if need_version_id: clauses._append_inplace( mapper.version_id_col == sql.bindparam( mapper.version_id_col.key, type_=mapper.version_id_col.type ) ) return table.delete().where(clauses) statement = base_mapper._memo(("delete", table), delete_stmt) for connection, recs in groupby(delete, lambda rec: rec[1]): # connection del_objects = [params for params, connection in recs] execution_options = {"compiled_cache": base_mapper._compiled_cache} expected = len(del_objects) rows_matched = -1 only_warn = False if ( need_version_id and not connection.dialect.supports_sane_multi_rowcount ): if connection.dialect.supports_sane_rowcount: rows_matched = 0 # execute deletes individually so that versioned # rows can be verified for params in del_objects: c = connection.execute( statement, params, execution_options=execution_options ) rows_matched += c.rowcount else: util.warn( "Dialect %s does not support deleted rowcount " "- versioning cannot be verified." % connection.dialect.dialect_description ) connection.execute( statement, del_objects, execution_options=execution_options ) else: c = connection.execute( statement, del_objects, execution_options=execution_options ) if not need_version_id: only_warn = True rows_matched = c.rowcount if ( base_mapper.confirm_deleted_rows and rows_matched > -1 and expected != rows_matched and ( connection.dialect.supports_sane_multi_rowcount or len(del_objects) == 1 ) ): # TODO: why does this "only warn" if versioning is turned off, # whereas the UPDATE raises? if only_warn: util.warn( "DELETE statement on table '%s' expected to " "delete %d row(s); %d were matched. Please set " "confirm_deleted_rows=False within the mapper " "configuration to prevent this warning." % (table.description, expected, rows_matched) ) else: raise orm_exc.StaleDataError( "DELETE statement on table '%s' expected to " "delete %d row(s); %d were matched. Please set " "confirm_deleted_rows=False within the mapper " "configuration to prevent this warning." % (table.description, expected, rows_matched) ) def _finalize_insert_update_commands(base_mapper, uowtransaction, states): """finalize state on states that have been inserted or updated, including calling after_insert/after_update events. """ for state, state_dict, mapper, connection, has_identity in states: if mapper._readonly_props: readonly = state.unmodified_intersection( [ p.key for p in mapper._readonly_props if ( p.expire_on_flush and (not p.deferred or p.key in state.dict) ) or ( not p.expire_on_flush and not p.deferred and p.key not in state.dict ) ] ) if readonly: state._expire_attributes(state.dict, readonly) # if eager_defaults option is enabled, load # all expired cols. Else if we have a version_id_col, make sure # it isn't expired. toload_now = [] # this is specifically to emit a second SELECT for eager_defaults, # so only if it's set to True, not "auto" if base_mapper.eager_defaults is True: toload_now.extend( state._unloaded_non_object.intersection( mapper._server_default_plus_onupdate_propkeys ) ) if ( mapper.version_id_col is not None and mapper.version_id_generator is False ): if mapper._version_id_prop.key in state.unloaded: toload_now.extend([mapper._version_id_prop.key]) if toload_now: state.key = base_mapper._identity_key_from_state(state) stmt = future.select(mapper).set_label_style( LABEL_STYLE_TABLENAME_PLUS_COL ) loading.load_on_ident( uowtransaction.session, stmt, state.key, refresh_state=state, only_load_props=toload_now, ) # call after_XXX extensions if not has_identity: mapper.dispatch.after_insert(mapper, connection, state) else: mapper.dispatch.after_update(mapper, connection, state) if ( mapper.version_id_generator is False and mapper.version_id_col is not None ): if state_dict[mapper._version_id_prop.key] is None: raise orm_exc.FlushError( "Instance does not contain a non-NULL version value" ) def _postfetch_post_update( mapper, uowtransaction, table, state, dict_, result, params ): needs_version_id = ( mapper.version_id_col is not None and mapper.version_id_col in mapper._cols_by_table[table] ) if not uowtransaction.is_deleted(state): # post updating after a regular INSERT or UPDATE, do a full postfetch prefetch_cols = result.context.compiled.prefetch postfetch_cols = result.context.compiled.postfetch elif needs_version_id: # post updating before a DELETE with a version_id_col, need to # postfetch just version_id_col prefetch_cols = postfetch_cols = () else: # post updating before a DELETE without a version_id_col, # don't need to postfetch return if needs_version_id: prefetch_cols = list(prefetch_cols) + [mapper.version_id_col] refresh_flush = bool(mapper.class_manager.dispatch.refresh_flush) if refresh_flush: load_evt_attrs = [] for c in prefetch_cols: if c.key in params and c in mapper._columntoproperty: dict_[mapper._columntoproperty[c].key] = params[c.key] if refresh_flush: load_evt_attrs.append(mapper._columntoproperty[c].key) if refresh_flush and load_evt_attrs: mapper.class_manager.dispatch.refresh_flush( state, uowtransaction, load_evt_attrs ) if postfetch_cols: state._expire_attributes( state.dict, [ mapper._columntoproperty[c].key for c in postfetch_cols if c in mapper._columntoproperty ], ) def _postfetch( mapper, uowtransaction, table, state, dict_, result, params, value_params, isupdate, returned_defaults, ): """Expire attributes in need of newly persisted database state, after an INSERT or UPDATE statement has proceeded for that state.""" prefetch_cols = result.context.compiled.prefetch postfetch_cols = result.context.compiled.postfetch returning_cols = result.context.compiled.effective_returning if ( mapper.version_id_col is not None and mapper.version_id_col in mapper._cols_by_table[table] ): prefetch_cols = list(prefetch_cols) + [mapper.version_id_col] refresh_flush = bool(mapper.class_manager.dispatch.refresh_flush) if refresh_flush: load_evt_attrs = [] if returning_cols: row = returned_defaults if row is not None: for row_value, col in zip(row, returning_cols): # pk cols returned from insert are handled # distinctly, don't step on the values here if col.primary_key and result.context.isinsert: continue # note that columns can be in the "return defaults" that are # not mapped to this mapper, typically because they are # "excluded", which can be specified directly or also occurs # when using declarative w/ single table inheritance prop = mapper._columntoproperty.get(col) if prop: dict_[prop.key] = row_value if refresh_flush: load_evt_attrs.append(prop.key) for c in prefetch_cols: if c.key in params and c in mapper._columntoproperty: pkey = mapper._columntoproperty[c].key # set prefetched value in dict and also pop from committed_state, # since this is new database state that replaces whatever might # have previously been fetched (see #10800). this is essentially a # shorthand version of set_committed_value(), which could also be # used here directly (with more overhead) dict_[pkey] = params[c.key] state.committed_state.pop(pkey, None) if refresh_flush: load_evt_attrs.append(pkey) if refresh_flush and load_evt_attrs: mapper.class_manager.dispatch.refresh_flush( state, uowtransaction, load_evt_attrs ) if isupdate and value_params: # explicitly suit the use case specified by # [ticket:3801], PK SQL expressions for UPDATE on non-RETURNING # database which are set to themselves in order to do a version bump. postfetch_cols.extend( [ col for col in value_params if col.primary_key and col not in returning_cols ] ) if postfetch_cols: state._expire_attributes( state.dict, [ mapper._columntoproperty[c].key for c in postfetch_cols if c in mapper._columntoproperty ], ) # synchronize newly inserted ids from one table to the next # TODO: this still goes a little too often. would be nice to # have definitive list of "columns that changed" here for m, equated_pairs in mapper._table_to_equated[table]: sync.populate( state, m, state, m, equated_pairs, uowtransaction, mapper.passive_updates, ) def _postfetch_bulk_save(mapper, dict_, table): for m, equated_pairs in mapper._table_to_equated[table]: sync.bulk_populate_inherit_keys(dict_, m, equated_pairs) def _connections_for_states(base_mapper, uowtransaction, states): """Return an iterator of (state, state.dict, mapper, connection). The states are sorted according to _sort_states, then paired with the connection they should be using for the given unit of work transaction. """ # if session has a connection callable, # organize individual states with the connection # to use for update if uowtransaction.session.connection_callable: connection_callable = uowtransaction.session.connection_callable else: connection = uowtransaction.transaction.connection(base_mapper) connection_callable = None for state in _sort_states(base_mapper, states): if connection_callable: connection = connection_callable(base_mapper, state.obj()) mapper = state.manager.mapper yield state, state.dict, mapper, connection def _sort_states(mapper, states): pending = set(states) persistent = {s for s in pending if s.key is not None} pending.difference_update(persistent) try: persistent_sorted = sorted( persistent, key=mapper._persistent_sortkey_fn ) except TypeError as err: raise sa_exc.InvalidRequestError( "Could not sort objects by primary key; primary key " "values must be sortable in Python (was: %s)" % err ) from err return ( sorted(pending, key=operator.attrgetter("insert_order")) + persistent_sorted ) sqlalchemy/orm/descriptor_props.py 0000755 00000110557 15125143220 0013465 0 ustar 00 # orm/descriptor_props.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """Descriptor properties are more "auxiliary" properties that exist as configurational elements, but don't participate as actively in the load/persist ORM loop. """ from __future__ import annotations from dataclasses import is_dataclass import inspect import itertools import operator import typing from typing import Any from typing import Callable from typing import Dict from typing import List from typing import NoReturn from typing import Optional from typing import Sequence from typing import Tuple from typing import Type from typing import TYPE_CHECKING from typing import TypeVar from typing import Union import weakref from . import attributes from . import util as orm_util from .base import _DeclarativeMapped from .base import LoaderCallableStatus from .base import Mapped from .base import PassiveFlag from .base import SQLORMOperations from .interfaces import _AttributeOptions from .interfaces import _IntrospectsAnnotations from .interfaces import _MapsColumns from .interfaces import MapperProperty from .interfaces import PropComparator from .util import _none_set from .util import de_stringify_annotation from .. import event from .. import exc as sa_exc from .. import schema from .. import sql from .. import util from ..sql import expression from ..sql import operators from ..sql.elements import BindParameter from ..util.typing import get_args from ..util.typing import is_fwd_ref from ..util.typing import is_pep593 if typing.TYPE_CHECKING: from ._typing import _InstanceDict from ._typing import _RegistryType from .attributes import History from .attributes import InstrumentedAttribute from .attributes import QueryableAttribute from .context import ORMCompileState from .decl_base import _ClassScanMapperConfig from .mapper import Mapper from .properties import ColumnProperty from .properties import MappedColumn from .state import InstanceState from ..engine.base import Connection from ..engine.row import Row from ..sql._typing import _DMLColumnArgument from ..sql._typing import _InfoType from ..sql.elements import ClauseList from ..sql.elements import ColumnElement from ..sql.operators import OperatorType from ..sql.schema import Column from ..sql.selectable import Select from ..util.typing import _AnnotationScanType from ..util.typing import CallableReference from ..util.typing import DescriptorReference from ..util.typing import RODescriptorReference _T = TypeVar("_T", bound=Any) _PT = TypeVar("_PT", bound=Any) class DescriptorProperty(MapperProperty[_T]): """:class:`.MapperProperty` which proxies access to a user-defined descriptor.""" doc: Optional[str] = None uses_objects = False _links_to_entity = False descriptor: DescriptorReference[Any] def get_history( self, state: InstanceState[Any], dict_: _InstanceDict, passive: PassiveFlag = PassiveFlag.PASSIVE_OFF, ) -> History: raise NotImplementedError() def instrument_class(self, mapper: Mapper[Any]) -> None: prop = self class _ProxyImpl(attributes.AttributeImpl): accepts_scalar_loader = False load_on_unexpire = True collection = False @property def uses_objects(self) -> bool: # type: ignore return prop.uses_objects def __init__(self, key: str): self.key = key def get_history( self, state: InstanceState[Any], dict_: _InstanceDict, passive: PassiveFlag = PassiveFlag.PASSIVE_OFF, ) -> History: return prop.get_history(state, dict_, passive) if self.descriptor is None: desc = getattr(mapper.class_, self.key, None) if mapper._is_userland_descriptor(self.key, desc): self.descriptor = desc if self.descriptor is None: def fset(obj: Any, value: Any) -> None: setattr(obj, self.name, value) def fdel(obj: Any) -> None: delattr(obj, self.name) def fget(obj: Any) -> Any: return getattr(obj, self.name) self.descriptor = property(fget=fget, fset=fset, fdel=fdel) proxy_attr = attributes.create_proxied_attribute(self.descriptor)( self.parent.class_, self.key, self.descriptor, lambda: self._comparator_factory(mapper), doc=self.doc, original_property=self, ) proxy_attr.impl = _ProxyImpl(self.key) mapper.class_manager.instrument_attribute(self.key, proxy_attr) _CompositeAttrType = Union[ str, "Column[_T]", "MappedColumn[_T]", "InstrumentedAttribute[_T]", "Mapped[_T]", ] _CC = TypeVar("_CC", bound=Any) _composite_getters: weakref.WeakKeyDictionary[ Type[Any], Callable[[Any], Tuple[Any, ...]] ] = weakref.WeakKeyDictionary() class CompositeProperty( _MapsColumns[_CC], _IntrospectsAnnotations, DescriptorProperty[_CC] ): """Defines a "composite" mapped attribute, representing a collection of columns as one attribute. :class:`.CompositeProperty` is constructed using the :func:`.composite` function. .. seealso:: :ref:`mapper_composite` """ composite_class: Union[Type[_CC], Callable[..., _CC]] attrs: Tuple[_CompositeAttrType[Any], ...] _generated_composite_accessor: CallableReference[ Optional[Callable[[_CC], Tuple[Any, ...]]] ] comparator_factory: Type[Comparator[_CC]] def __init__( self, _class_or_attr: Union[ None, Type[_CC], Callable[..., _CC], _CompositeAttrType[Any] ] = None, *attrs: _CompositeAttrType[Any], attribute_options: Optional[_AttributeOptions] = None, active_history: bool = False, deferred: bool = False, group: Optional[str] = None, comparator_factory: Optional[Type[Comparator[_CC]]] = None, info: Optional[_InfoType] = None, **kwargs: Any, ): super().__init__(attribute_options=attribute_options) if isinstance(_class_or_attr, (Mapped, str, sql.ColumnElement)): self.attrs = (_class_or_attr,) + attrs # will initialize within declarative_scan self.composite_class = None # type: ignore else: self.composite_class = _class_or_attr # type: ignore self.attrs = attrs self.active_history = active_history self.deferred = deferred self.group = group self.comparator_factory = ( comparator_factory if comparator_factory is not None else self.__class__.Comparator ) self._generated_composite_accessor = None if info is not None: self.info.update(info) util.set_creation_order(self) self._create_descriptor() self._init_accessor() def instrument_class(self, mapper: Mapper[Any]) -> None: super().instrument_class(mapper) self._setup_event_handlers() def _composite_values_from_instance(self, value: _CC) -> Tuple[Any, ...]: if self._generated_composite_accessor: return self._generated_composite_accessor(value) else: try: accessor = value.__composite_values__ except AttributeError as ae: raise sa_exc.InvalidRequestError( f"Composite class {self.composite_class.__name__} is not " f"a dataclass and does not define a __composite_values__()" " method; can't get state" ) from ae else: return accessor() # type: ignore def do_init(self) -> None: """Initialization which occurs after the :class:`.Composite` has been associated with its parent mapper. """ self._setup_arguments_on_columns() _COMPOSITE_FGET = object() def _create_descriptor(self) -> None: """Create the Python descriptor that will serve as the access point on instances of the mapped class. """ def fget(instance: Any) -> Any: dict_ = attributes.instance_dict(instance) state = attributes.instance_state(instance) if self.key not in dict_: # key not present. Iterate through related # attributes, retrieve their values. This # ensures they all load. values = [ getattr(instance, key) for key in self._attribute_keys ] # current expected behavior here is that the composite is # created on access if the object is persistent or if # col attributes have non-None. This would be better # if the composite were created unconditionally, # but that would be a behavioral change. if self.key not in dict_ and ( state.key is not None or not _none_set.issuperset(values) ): dict_[self.key] = self.composite_class(*values) state.manager.dispatch.refresh( state, self._COMPOSITE_FGET, [self.key] ) return dict_.get(self.key, None) def fset(instance: Any, value: Any) -> None: dict_ = attributes.instance_dict(instance) state = attributes.instance_state(instance) attr = state.manager[self.key] if attr.dispatch._active_history: previous = fget(instance) else: previous = dict_.get(self.key, LoaderCallableStatus.NO_VALUE) for fn in attr.dispatch.set: value = fn(state, value, previous, attr.impl) dict_[self.key] = value if value is None: for key in self._attribute_keys: setattr(instance, key, None) else: for key, value in zip( self._attribute_keys, self._composite_values_from_instance(value), ): setattr(instance, key, value) def fdel(instance: Any) -> None: state = attributes.instance_state(instance) dict_ = attributes.instance_dict(instance) attr = state.manager[self.key] if attr.dispatch._active_history: previous = fget(instance) dict_.pop(self.key, None) else: previous = dict_.pop(self.key, LoaderCallableStatus.NO_VALUE) attr = state.manager[self.key] attr.dispatch.remove(state, previous, attr.impl) for key in self._attribute_keys: setattr(instance, key, None) self.descriptor = property(fget, fset, fdel) @util.preload_module("sqlalchemy.orm.properties") def declarative_scan( self, decl_scan: _ClassScanMapperConfig, registry: _RegistryType, cls: Type[Any], originating_module: Optional[str], key: str, mapped_container: Optional[Type[Mapped[Any]]], annotation: Optional[_AnnotationScanType], extracted_mapped_annotation: Optional[_AnnotationScanType], is_dataclass_field: bool, ) -> None: MappedColumn = util.preloaded.orm_properties.MappedColumn if ( self.composite_class is None and extracted_mapped_annotation is None ): self._raise_for_required(key, cls) argument = extracted_mapped_annotation if is_pep593(argument): argument = get_args(argument)[0] if argument and self.composite_class is None: if isinstance(argument, str) or is_fwd_ref( argument, check_generic=True ): if originating_module is None: str_arg = ( argument.__forward_arg__ if hasattr(argument, "__forward_arg__") else str(argument) ) raise sa_exc.ArgumentError( f"Can't use forward ref {argument} for composite " f"class argument; set up the type as Mapped[{str_arg}]" ) argument = de_stringify_annotation( cls, argument, originating_module, include_generic=True ) self.composite_class = argument if is_dataclass(self.composite_class): self._setup_for_dataclass(registry, cls, originating_module, key) else: for attr in self.attrs: if ( isinstance(attr, (MappedColumn, schema.Column)) and attr.name is None ): raise sa_exc.ArgumentError( "Composite class column arguments must be named " "unless a dataclass is used" ) self._init_accessor() def _init_accessor(self) -> None: if is_dataclass(self.composite_class) and not hasattr( self.composite_class, "__composite_values__" ): insp = inspect.signature(self.composite_class) getter = operator.attrgetter( *[p.name for p in insp.parameters.values()] ) if len(insp.parameters) == 1: self._generated_composite_accessor = lambda obj: (getter(obj),) else: self._generated_composite_accessor = getter if ( self.composite_class is not None and isinstance(self.composite_class, type) and self.composite_class not in _composite_getters ): if self._generated_composite_accessor is not None: _composite_getters[self.composite_class] = ( self._generated_composite_accessor ) elif hasattr(self.composite_class, "__composite_values__"): _composite_getters[self.composite_class] = ( lambda obj: obj.__composite_values__() ) @util.preload_module("sqlalchemy.orm.properties") @util.preload_module("sqlalchemy.orm.decl_base") def _setup_for_dataclass( self, registry: _RegistryType, cls: Type[Any], originating_module: Optional[str], key: str, ) -> None: MappedColumn = util.preloaded.orm_properties.MappedColumn decl_base = util.preloaded.orm_decl_base insp = inspect.signature(self.composite_class) for param, attr in itertools.zip_longest( insp.parameters.values(), self.attrs ): if param is None: raise sa_exc.ArgumentError( f"number of composite attributes " f"{len(self.attrs)} exceeds " f"that of the number of attributes in class " f"{self.composite_class.__name__} {len(insp.parameters)}" ) if attr is None: # fill in missing attr spots with empty MappedColumn attr = MappedColumn() self.attrs += (attr,) if isinstance(attr, MappedColumn): attr.declarative_scan_for_composite( registry, cls, originating_module, key, param.name, param.annotation, ) elif isinstance(attr, schema.Column): decl_base._undefer_column_name(param.name, attr) @util.memoized_property def _comparable_elements(self) -> Sequence[QueryableAttribute[Any]]: return [getattr(self.parent.class_, prop.key) for prop in self.props] @util.memoized_property @util.preload_module("orm.properties") def props(self) -> Sequence[MapperProperty[Any]]: props = [] MappedColumn = util.preloaded.orm_properties.MappedColumn for attr in self.attrs: if isinstance(attr, str): prop = self.parent.get_property(attr, _configure_mappers=False) elif isinstance(attr, schema.Column): prop = self.parent._columntoproperty[attr] elif isinstance(attr, MappedColumn): prop = self.parent._columntoproperty[attr.column] elif isinstance(attr, attributes.InstrumentedAttribute): prop = attr.property else: prop = None if not isinstance(prop, MapperProperty): raise sa_exc.ArgumentError( "Composite expects Column objects or mapped " f"attributes/attribute names as arguments, got: {attr!r}" ) props.append(prop) return props @util.non_memoized_property @util.preload_module("orm.properties") def columns(self) -> Sequence[Column[Any]]: MappedColumn = util.preloaded.orm_properties.MappedColumn return [ a.column if isinstance(a, MappedColumn) else a for a in self.attrs if isinstance(a, (schema.Column, MappedColumn)) ] @property def mapper_property_to_assign(self) -> Optional[MapperProperty[_CC]]: return self @property def columns_to_assign(self) -> List[Tuple[schema.Column[Any], int]]: return [(c, 0) for c in self.columns if c.table is None] @util.preload_module("orm.properties") def _setup_arguments_on_columns(self) -> None: """Propagate configuration arguments made on this composite to the target columns, for those that apply. """ ColumnProperty = util.preloaded.orm_properties.ColumnProperty for prop in self.props: if not isinstance(prop, ColumnProperty): continue else: cprop = prop cprop.active_history = self.active_history if self.deferred: cprop.deferred = self.deferred cprop.strategy_key = (("deferred", True), ("instrument", True)) cprop.group = self.group def _setup_event_handlers(self) -> None: """Establish events that populate/expire the composite attribute.""" def load_handler( state: InstanceState[Any], context: ORMCompileState ) -> None: _load_refresh_handler(state, context, None, is_refresh=False) def refresh_handler( state: InstanceState[Any], context: ORMCompileState, to_load: Optional[Sequence[str]], ) -> None: # note this corresponds to sqlalchemy.ext.mutable load_attrs() if not to_load or ( {self.key}.union(self._attribute_keys) ).intersection(to_load): _load_refresh_handler(state, context, to_load, is_refresh=True) def _load_refresh_handler( state: InstanceState[Any], context: ORMCompileState, to_load: Optional[Sequence[str]], is_refresh: bool, ) -> None: dict_ = state.dict # if context indicates we are coming from the # fget() handler, this already set the value; skip the # handler here. (other handlers like mutablecomposite will still # want to catch it) # there's an insufficiency here in that the fget() handler # really should not be using the refresh event and there should # be some other event that mutablecomposite can subscribe # towards for this. if ( not is_refresh or context is self._COMPOSITE_FGET ) and self.key in dict_: return # if column elements aren't loaded, skip. # __get__() will initiate a load for those # columns for k in self._attribute_keys: if k not in dict_: return dict_[self.key] = self.composite_class( *[state.dict[key] for key in self._attribute_keys] ) def expire_handler( state: InstanceState[Any], keys: Optional[Sequence[str]] ) -> None: if keys is None or set(self._attribute_keys).intersection(keys): state.dict.pop(self.key, None) def insert_update_handler( mapper: Mapper[Any], connection: Connection, state: InstanceState[Any], ) -> None: """After an insert or update, some columns may be expired due to server side defaults, or re-populated due to client side defaults. Pop out the composite value here so that it recreates. """ state.dict.pop(self.key, None) event.listen( self.parent, "after_insert", insert_update_handler, raw=True ) event.listen( self.parent, "after_update", insert_update_handler, raw=True ) event.listen( self.parent, "load", load_handler, raw=True, propagate=True ) event.listen( self.parent, "refresh", refresh_handler, raw=True, propagate=True ) event.listen( self.parent, "expire", expire_handler, raw=True, propagate=True ) proxy_attr = self.parent.class_manager[self.key] proxy_attr.impl.dispatch = proxy_attr.dispatch # type: ignore proxy_attr.impl.dispatch._active_history = self.active_history # TODO: need a deserialize hook here @util.memoized_property def _attribute_keys(self) -> Sequence[str]: return [prop.key for prop in self.props] def _populate_composite_bulk_save_mappings_fn( self, ) -> Callable[[Dict[str, Any]], None]: if self._generated_composite_accessor: get_values = self._generated_composite_accessor else: def get_values(val: Any) -> Tuple[Any]: return val.__composite_values__() # type: ignore attrs = [prop.key for prop in self.props] def populate(dest_dict: Dict[str, Any]) -> None: dest_dict.update( { key: val for key, val in zip( attrs, get_values(dest_dict.pop(self.key)) ) } ) return populate def get_history( self, state: InstanceState[Any], dict_: _InstanceDict, passive: PassiveFlag = PassiveFlag.PASSIVE_OFF, ) -> History: """Provided for userland code that uses attributes.get_history().""" added: List[Any] = [] deleted: List[Any] = [] has_history = False for prop in self.props: key = prop.key hist = state.manager[key].impl.get_history(state, dict_) if hist.has_changes(): has_history = True non_deleted = hist.non_deleted() if non_deleted: added.extend(non_deleted) else: added.append(None) if hist.deleted: deleted.extend(hist.deleted) else: deleted.append(None) if has_history: return attributes.History( [self.composite_class(*added)], (), [self.composite_class(*deleted)], ) else: return attributes.History((), [self.composite_class(*added)], ()) def _comparator_factory( self, mapper: Mapper[Any] ) -> Composite.Comparator[_CC]: return self.comparator_factory(self, mapper) class CompositeBundle(orm_util.Bundle[_T]): def __init__( self, property_: Composite[_T], expr: ClauseList, ): self.property = property_ super().__init__(property_.key, *expr) def create_row_processor( self, query: Select[Any], procs: Sequence[Callable[[Row[Any]], Any]], labels: Sequence[str], ) -> Callable[[Row[Any]], Any]: def proc(row: Row[Any]) -> Any: return self.property.composite_class( *[proc(row) for proc in procs] ) return proc class Comparator(PropComparator[_PT]): """Produce boolean, comparison, and other operators for :class:`.Composite` attributes. See the example in :ref:`composite_operations` for an overview of usage , as well as the documentation for :class:`.PropComparator`. .. seealso:: :class:`.PropComparator` :class:`.ColumnOperators` :ref:`types_operators` :attr:`.TypeEngine.comparator_factory` """ # https://github.com/python/mypy/issues/4266 __hash__ = None # type: ignore prop: RODescriptorReference[Composite[_PT]] @util.memoized_property def clauses(self) -> ClauseList: return expression.ClauseList( group=False, *self._comparable_elements ) def __clause_element__(self) -> CompositeProperty.CompositeBundle[_PT]: return self.expression @util.memoized_property def expression(self) -> CompositeProperty.CompositeBundle[_PT]: clauses = self.clauses._annotate( { "parententity": self._parententity, "parentmapper": self._parententity, "proxy_key": self.prop.key, } ) return CompositeProperty.CompositeBundle(self.prop, clauses) def _bulk_update_tuples( self, value: Any ) -> Sequence[Tuple[_DMLColumnArgument, Any]]: if isinstance(value, BindParameter): value = value.value values: Sequence[Any] if value is None: values = [None for key in self.prop._attribute_keys] elif isinstance(self.prop.composite_class, type) and isinstance( value, self.prop.composite_class ): values = self.prop._composite_values_from_instance( value # type: ignore[arg-type] ) else: raise sa_exc.ArgumentError( "Can't UPDATE composite attribute %s to %r" % (self.prop, value) ) return list(zip(self._comparable_elements, values)) @util.memoized_property def _comparable_elements(self) -> Sequence[QueryableAttribute[Any]]: if self._adapt_to_entity: return [ getattr(self._adapt_to_entity.entity, prop.key) for prop in self.prop._comparable_elements ] else: return self.prop._comparable_elements def __eq__(self, other: Any) -> ColumnElement[bool]: # type: ignore[override] # noqa: E501 return self._compare(operators.eq, other) def __ne__(self, other: Any) -> ColumnElement[bool]: # type: ignore[override] # noqa: E501 return self._compare(operators.ne, other) def __lt__(self, other: Any) -> ColumnElement[bool]: return self._compare(operators.lt, other) def __gt__(self, other: Any) -> ColumnElement[bool]: return self._compare(operators.gt, other) def __le__(self, other: Any) -> ColumnElement[bool]: return self._compare(operators.le, other) def __ge__(self, other: Any) -> ColumnElement[bool]: return self._compare(operators.ge, other) # what might be interesting would be if we create # an instance of the composite class itself with # the columns as data members, then use "hybrid style" comparison # to create these comparisons. then your Point.__eq__() method could # be where comparison behavior is defined for SQL also. Likely # not a good choice for default behavior though, not clear how it would # work w/ dataclasses, etc. also no demand for any of this anyway. def _compare( self, operator: OperatorType, other: Any ) -> ColumnElement[bool]: values: Sequence[Any] if other is None: values = [None] * len(self.prop._comparable_elements) else: values = self.prop._composite_values_from_instance(other) comparisons = [ operator(a, b) for a, b in zip(self.prop._comparable_elements, values) ] if self._adapt_to_entity: assert self.adapter is not None comparisons = [self.adapter(x) for x in comparisons] return sql.and_(*comparisons) def __str__(self) -> str: return str(self.parent.class_.__name__) + "." + self.key class Composite(CompositeProperty[_T], _DeclarativeMapped[_T]): """Declarative-compatible front-end for the :class:`.CompositeProperty` class. Public constructor is the :func:`_orm.composite` function. .. versionchanged:: 2.0 Added :class:`_orm.Composite` as a Declarative compatible subclass of :class:`_orm.CompositeProperty`. .. seealso:: :ref:`mapper_composite` """ inherit_cache = True """:meta private:""" class ConcreteInheritedProperty(DescriptorProperty[_T]): """A 'do nothing' :class:`.MapperProperty` that disables an attribute on a concrete subclass that is only present on the inherited mapper, not the concrete classes' mapper. Cases where this occurs include: * When the superclass mapper is mapped against a "polymorphic union", which includes all attributes from all subclasses. * When a relationship() is configured on an inherited mapper, but not on the subclass mapper. Concrete mappers require that relationship() is configured explicitly on each subclass. """ def _comparator_factory( self, mapper: Mapper[Any] ) -> Type[PropComparator[_T]]: comparator_callable = None for m in self.parent.iterate_to_root(): p = m._props[self.key] if getattr(p, "comparator_factory", None) is not None: comparator_callable = p.comparator_factory break assert comparator_callable is not None return comparator_callable(p, mapper) # type: ignore def __init__(self) -> None: super().__init__() def warn() -> NoReturn: raise AttributeError( "Concrete %s does not implement " "attribute %r at the instance level. Add " "this property explicitly to %s." % (self.parent, self.key, self.parent) ) class NoninheritedConcreteProp: def __set__(s: Any, obj: Any, value: Any) -> NoReturn: warn() def __delete__(s: Any, obj: Any) -> NoReturn: warn() def __get__(s: Any, obj: Any, owner: Any) -> Any: if obj is None: return self.descriptor warn() self.descriptor = NoninheritedConcreteProp() class SynonymProperty(DescriptorProperty[_T]): """Denote an attribute name as a synonym to a mapped property, in that the attribute will mirror the value and expression behavior of another attribute. :class:`.Synonym` is constructed using the :func:`_orm.synonym` function. .. seealso:: :ref:`synonyms` - Overview of synonyms """ comparator_factory: Optional[Type[PropComparator[_T]]] def __init__( self, name: str, map_column: Optional[bool] = None, descriptor: Optional[Any] = None, comparator_factory: Optional[Type[PropComparator[_T]]] = None, attribute_options: Optional[_AttributeOptions] = None, info: Optional[_InfoType] = None, doc: Optional[str] = None, ): super().__init__(attribute_options=attribute_options) self.name = name self.map_column = map_column self.descriptor = descriptor self.comparator_factory = comparator_factory if doc: self.doc = doc elif descriptor and descriptor.__doc__: self.doc = descriptor.__doc__ else: self.doc = None if info: self.info.update(info) util.set_creation_order(self) if not TYPE_CHECKING: @property def uses_objects(self) -> bool: return getattr(self.parent.class_, self.name).impl.uses_objects # TODO: when initialized, check _proxied_object, # emit a warning if its not a column-based property @util.memoized_property def _proxied_object( self, ) -> Union[MapperProperty[_T], SQLORMOperations[_T]]: attr = getattr(self.parent.class_, self.name) if not hasattr(attr, "property") or not isinstance( attr.property, MapperProperty ): # attribute is a non-MapperProprerty proxy such as # hybrid or association proxy if isinstance(attr, attributes.QueryableAttribute): return attr.comparator elif isinstance(attr, SQLORMOperations): # assocaition proxy comes here return attr raise sa_exc.InvalidRequestError( """synonym() attribute "%s.%s" only supports """ """ORM mapped attributes, got %r""" % (self.parent.class_.__name__, self.name, attr) ) return attr.property def _comparator_factory(self, mapper: Mapper[Any]) -> SQLORMOperations[_T]: prop = self._proxied_object if isinstance(prop, MapperProperty): if self.comparator_factory: comp = self.comparator_factory(prop, mapper) else: comp = prop.comparator_factory(prop, mapper) return comp else: return prop def get_history( self, state: InstanceState[Any], dict_: _InstanceDict, passive: PassiveFlag = PassiveFlag.PASSIVE_OFF, ) -> History: attr: QueryableAttribute[Any] = getattr(self.parent.class_, self.name) return attr.impl.get_history(state, dict_, passive=passive) @util.preload_module("sqlalchemy.orm.properties") def set_parent(self, parent: Mapper[Any], init: bool) -> None: properties = util.preloaded.orm_properties if self.map_column: # implement the 'map_column' option. if self.key not in parent.persist_selectable.c: raise sa_exc.ArgumentError( "Can't compile synonym '%s': no column on table " "'%s' named '%s'" % ( self.name, parent.persist_selectable.description, self.key, ) ) elif ( parent.persist_selectable.c[self.key] in parent._columntoproperty and parent._columntoproperty[ parent.persist_selectable.c[self.key] ].key == self.name ): raise sa_exc.ArgumentError( "Can't call map_column=True for synonym %r=%r, " "a ColumnProperty already exists keyed to the name " "%r for column %r" % (self.key, self.name, self.name, self.key) ) p: ColumnProperty[Any] = properties.ColumnProperty( parent.persist_selectable.c[self.key] ) parent._configure_property(self.name, p, init=init, setparent=True) p._mapped_by_synonym = self.key self.parent = parent class Synonym(SynonymProperty[_T], _DeclarativeMapped[_T]): """Declarative front-end for the :class:`.SynonymProperty` class. Public constructor is the :func:`_orm.synonym` function. .. versionchanged:: 2.0 Added :class:`_orm.Synonym` as a Declarative compatible subclass for :class:`_orm.SynonymProperty` .. seealso:: :ref:`synonyms` - Overview of synonyms """ inherit_cache = True """:meta private:""" sqlalchemy/orm/strategies.py 0000755 00000351776 15125143220 0012250 0 ustar 00 # orm/strategies.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors """sqlalchemy.orm.interfaces.LoaderStrategy implementations, and related MapperOptions.""" from __future__ import annotations import collections import itertools from typing import Any from typing import Dict from typing import Optional from typing import Tuple from typing import TYPE_CHECKING from typing import Union from . import attributes from . import exc as orm_exc from . import interfaces from . import loading from . import path_registry from . import properties from . import query from . import relationships from . import unitofwork from . import util as orm_util from .base import _DEFER_FOR_STATE from .base import _RAISE_FOR_STATE from .base import _SET_DEFERRED_EXPIRED from .base import ATTR_WAS_SET from .base import LoaderCallableStatus from .base import PASSIVE_OFF from .base import PassiveFlag from .context import _column_descriptions from .context import ORMCompileState from .context import ORMSelectCompileState from .context import QueryContext from .interfaces import LoaderStrategy from .interfaces import StrategizedProperty from .session import _state_session from .state import InstanceState from .strategy_options import Load from .util import _none_only_set from .util import AliasedClass from .. import event from .. import exc as sa_exc from .. import inspect from .. import log from .. import sql from .. import util from ..sql import util as sql_util from ..sql import visitors from ..sql.selectable import LABEL_STYLE_TABLENAME_PLUS_COL from ..sql.selectable import Select from ..util.typing import Literal if TYPE_CHECKING: from .mapper import Mapper from .relationships import RelationshipProperty from ..sql.elements import ColumnElement def _register_attribute( prop, mapper, useobject, compare_function=None, typecallable=None, callable_=None, proxy_property=None, active_history=False, impl_class=None, **kw, ): listen_hooks = [] uselist = useobject and prop.uselist if useobject and prop.single_parent: listen_hooks.append(single_parent_validator) if prop.key in prop.parent.validators: fn, opts = prop.parent.validators[prop.key] listen_hooks.append( lambda desc, prop: orm_util._validator_events( desc, prop.key, fn, **opts ) ) if useobject: listen_hooks.append(unitofwork.track_cascade_events) # need to assemble backref listeners # after the singleparentvalidator, mapper validator if useobject: backref = prop.back_populates if backref and prop._effective_sync_backref: listen_hooks.append( lambda desc, prop: attributes.backref_listeners( desc, backref, uselist ) ) # a single MapperProperty is shared down a class inheritance # hierarchy, so we set up attribute instrumentation and backref event # for each mapper down the hierarchy. # typically, "mapper" is the same as prop.parent, due to the way # the configure_mappers() process runs, however this is not strongly # enforced, and in the case of a second configure_mappers() run the # mapper here might not be prop.parent; also, a subclass mapper may # be called here before a superclass mapper. That is, can't depend # on mappers not already being set up so we have to check each one. for m in mapper.self_and_descendants: if prop is m._props.get( prop.key ) and not m.class_manager._attr_has_impl(prop.key): desc = attributes.register_attribute_impl( m.class_, prop.key, parent_token=prop, uselist=uselist, compare_function=compare_function, useobject=useobject, trackparent=useobject and ( prop.single_parent or prop.direction is interfaces.ONETOMANY ), typecallable=typecallable, callable_=callable_, active_history=active_history, impl_class=impl_class, send_modified_events=not useobject or not prop.viewonly, doc=prop.doc, **kw, ) for hook in listen_hooks: hook(desc, prop) @properties.ColumnProperty.strategy_for(instrument=False, deferred=False) class UninstrumentedColumnLoader(LoaderStrategy): """Represent a non-instrumented MapperProperty. The polymorphic_on argument of mapper() often results in this, if the argument is against the with_polymorphic selectable. """ __slots__ = ("columns",) def __init__(self, parent, strategy_key): super().__init__(parent, strategy_key) self.columns = self.parent_property.columns def setup_query( self, compile_state, query_entity, path, loadopt, adapter, column_collection=None, **kwargs, ): for c in self.columns: if adapter: c = adapter.columns[c] compile_state._append_dedupe_col_collection(c, column_collection) def create_row_processor( self, context, query_entity, path, loadopt, mapper, result, adapter, populators, ): pass @log.class_logger @properties.ColumnProperty.strategy_for(instrument=True, deferred=False) class ColumnLoader(LoaderStrategy): """Provide loading behavior for a :class:`.ColumnProperty`.""" __slots__ = "columns", "is_composite" def __init__(self, parent, strategy_key): super().__init__(parent, strategy_key) self.columns = self.parent_property.columns self.is_composite = hasattr(self.parent_property, "composite_class") def setup_query( self, compile_state, query_entity, path, loadopt, adapter, column_collection, memoized_populators, check_for_adapt=False, **kwargs, ): for c in self.columns: if adapter: if check_for_adapt: c = adapter.adapt_check_present(c) if c is None: return else: c = adapter.columns[c] compile_state._append_dedupe_col_collection(c, column_collection) fetch = self.columns[0] if adapter: fetch = adapter.columns[fetch] if fetch is None: # None happens here only for dml bulk_persistence cases # when context.DMLReturningColFilter is used return memoized_populators[self.parent_property] = fetch def init_class_attribute(self, mapper): self.is_class_level = True coltype = self.columns[0].type # TODO: check all columns ? check for foreign key as well? active_history = ( self.parent_property.active_history or self.columns[0].primary_key or ( mapper.version_id_col is not None and mapper._columntoproperty.get(mapper.version_id_col, None) is self.parent_property ) ) _register_attribute( self.parent_property, mapper, useobject=False, compare_function=coltype.compare_values, active_history=active_history, ) def create_row_processor( self, context, query_entity, path, loadopt, mapper, result, adapter, populators, ): # look through list of columns represented here # to see which, if any, is present in the row. for col in self.columns: if adapter: col = adapter.columns[col] getter = result._getter(col, False) if getter: populators["quick"].append((self.key, getter)) break else: populators["expire"].append((self.key, True)) @log.class_logger @properties.ColumnProperty.strategy_for(query_expression=True) class ExpressionColumnLoader(ColumnLoader): def __init__(self, parent, strategy_key): super().__init__(parent, strategy_key) # compare to the "default" expression that is mapped in # the column. If it's sql.null, we don't need to render # unless an expr is passed in the options. null = sql.null().label(None) self._have_default_expression = any( not c.compare(null) for c in self.parent_property.columns ) def setup_query( self, compile_state, query_entity, path, loadopt, adapter, column_collection, memoized_populators, **kwargs, ): columns = None if loadopt and loadopt._extra_criteria: columns = loadopt._extra_criteria elif self._have_default_expression: columns = self.parent_property.columns if columns is None: return for c in columns: if adapter: c = adapter.columns[c] compile_state._append_dedupe_col_collection(c, column_collection) fetch = columns[0] if adapter: fetch = adapter.columns[fetch] if fetch is None: # None is not expected to be the result of any # adapter implementation here, however there may be theoretical # usages of returning() with context.DMLReturningColFilter return memoized_populators[self.parent_property] = fetch def create_row_processor( self, context, query_entity, path, loadopt, mapper, result, adapter, populators, ): # look through list of columns represented here # to see which, if any, is present in the row. if loadopt and loadopt._extra_criteria: columns = loadopt._extra_criteria for col in columns: if adapter: col = adapter.columns[col] getter = result._getter(col, False) if getter: populators["quick"].append((self.key, getter)) break else: populators["expire"].append((self.key, True)) def init_class_attribute(self, mapper): self.is_class_level = True _register_attribute( self.parent_property, mapper, useobject=False, compare_function=self.columns[0].type.compare_values, accepts_scalar_loader=False, ) @log.class_logger @properties.ColumnProperty.strategy_for(deferred=True, instrument=True) @properties.ColumnProperty.strategy_for( deferred=True, instrument=True, raiseload=True ) @properties.ColumnProperty.strategy_for(do_nothing=True) class DeferredColumnLoader(LoaderStrategy): """Provide loading behavior for a deferred :class:`.ColumnProperty`.""" __slots__ = "columns", "group", "raiseload" def __init__(self, parent, strategy_key): super().__init__(parent, strategy_key) if hasattr(self.parent_property, "composite_class"): raise NotImplementedError( "Deferred loading for composite types not implemented yet" ) self.raiseload = self.strategy_opts.get("raiseload", False) self.columns = self.parent_property.columns self.group = self.parent_property.group def create_row_processor( self, context, query_entity, path, loadopt, mapper, result, adapter, populators, ): # for a DeferredColumnLoader, this method is only used during a # "row processor only" query; see test_deferred.py -> # tests with "rowproc_only" in their name. As of the 1.0 series, # loading._instance_processor doesn't use a "row processing" function # to populate columns, instead it uses data in the "populators" # dictionary. Normally, the DeferredColumnLoader.setup_query() # sets up that data in the "memoized_populators" dictionary # and "create_row_processor()" here is never invoked. if ( context.refresh_state and context.query._compile_options._only_load_props and self.key in context.query._compile_options._only_load_props ): self.parent_property._get_strategy( (("deferred", False), ("instrument", True)) ).create_row_processor( context, query_entity, path, loadopt, mapper, result, adapter, populators, ) elif not self.is_class_level: if self.raiseload: set_deferred_for_local_state = ( self.parent_property._raise_column_loader ) else: set_deferred_for_local_state = ( self.parent_property._deferred_column_loader ) populators["new"].append((self.key, set_deferred_for_local_state)) else: populators["expire"].append((self.key, False)) def init_class_attribute(self, mapper): self.is_class_level = True _register_attribute( self.parent_property, mapper, useobject=False, compare_function=self.columns[0].type.compare_values, callable_=self._load_for_state, load_on_unexpire=False, ) def setup_query( self, compile_state, query_entity, path, loadopt, adapter, column_collection, memoized_populators, only_load_props=None, **kw, ): if ( ( compile_state.compile_options._render_for_subquery and self.parent_property._renders_in_subqueries ) or ( loadopt and set(self.columns).intersection( self.parent._should_undefer_in_wildcard ) ) or ( loadopt and self.group and loadopt.local_opts.get( "undefer_group_%s" % self.group, False ) ) or (only_load_props and self.key in only_load_props) ): self.parent_property._get_strategy( (("deferred", False), ("instrument", True)) ).setup_query( compile_state, query_entity, path, loadopt, adapter, column_collection, memoized_populators, **kw, ) elif self.is_class_level: memoized_populators[self.parent_property] = _SET_DEFERRED_EXPIRED elif not self.raiseload: memoized_populators[self.parent_property] = _DEFER_FOR_STATE else: memoized_populators[self.parent_property] = _RAISE_FOR_STATE def _load_for_state(self, state, passive): if not state.key: return LoaderCallableStatus.ATTR_EMPTY if not passive & PassiveFlag.SQL_OK: return LoaderCallableStatus.PASSIVE_NO_RESULT localparent = state.manager.mapper if self.group: toload = [ p.key for p in localparent.iterate_properties if isinstance(p, StrategizedProperty) and isinstance(p.strategy, DeferredColumnLoader) and p.group == self.group ] else: toload = [self.key] # narrow the keys down to just those which have no history group = [k for k in toload if k in state.unmodified] session = _state_session(state) if session is None: raise orm_exc.DetachedInstanceError( "Parent instance %s is not bound to a Session; " "deferred load operation of attribute '%s' cannot proceed" % (orm_util.state_str(state), self.key) ) if self.raiseload: self._invoke_raise_load(state, passive, "raise") loading.load_scalar_attributes( state.mapper, state, set(group), PASSIVE_OFF ) return LoaderCallableStatus.ATTR_WAS_SET def _invoke_raise_load(self, state, passive, lazy): raise sa_exc.InvalidRequestError( "'%s' is not available due to raiseload=True" % (self,) ) class LoadDeferredColumns: """serializable loader object used by DeferredColumnLoader""" def __init__(self, key: str, raiseload: bool = False): self.key = key self.raiseload = raiseload def __call__(self, state, passive=attributes.PASSIVE_OFF): key = self.key localparent = state.manager.mapper prop = localparent._props[key] if self.raiseload: strategy_key = ( ("deferred", True), ("instrument", True), ("raiseload", True), ) else: strategy_key = (("deferred", True), ("instrument", True)) strategy = prop._get_strategy(strategy_key) return strategy._load_for_state(state, passive) class AbstractRelationshipLoader(LoaderStrategy): """LoaderStratgies which deal with related objects.""" __slots__ = "mapper", "target", "uselist", "entity" def __init__(self, parent, strategy_key): super().__init__(parent, strategy_key) self.mapper = self.parent_property.mapper self.entity = self.parent_property.entity self.target = self.parent_property.target self.uselist = self.parent_property.uselist def _immediateload_create_row_processor( self, context, query_entity, path, loadopt, mapper, result, adapter, populators, ): return self.parent_property._get_strategy( (("lazy", "immediate"),) ).create_row_processor( context, query_entity, path, loadopt, mapper, result, adapter, populators, ) @log.class_logger @relationships.RelationshipProperty.strategy_for(do_nothing=True) class DoNothingLoader(LoaderStrategy): """Relationship loader that makes no change to the object's state. Compared to NoLoader, this loader does not initialize the collection/attribute to empty/none; the usual default LazyLoader will take effect. """ @log.class_logger @relationships.RelationshipProperty.strategy_for(lazy="noload") @relationships.RelationshipProperty.strategy_for(lazy=None) class NoLoader(AbstractRelationshipLoader): """Provide loading behavior for a :class:`.Relationship` with "lazy=None". """ __slots__ = () def init_class_attribute(self, mapper): self.is_class_level = True _register_attribute( self.parent_property, mapper, useobject=True, typecallable=self.parent_property.collection_class, ) def create_row_processor( self, context, query_entity, path, loadopt, mapper, result, adapter, populators, ): def invoke_no_load(state, dict_, row): if self.uselist: attributes.init_state_collection(state, dict_, self.key) else: dict_[self.key] = None populators["new"].append((self.key, invoke_no_load)) @log.class_logger @relationships.RelationshipProperty.strategy_for(lazy=True) @relationships.RelationshipProperty.strategy_for(lazy="select") @relationships.RelationshipProperty.strategy_for(lazy="raise") @relationships.RelationshipProperty.strategy_for(lazy="raise_on_sql") @relationships.RelationshipProperty.strategy_for(lazy="baked_select") class LazyLoader( AbstractRelationshipLoader, util.MemoizedSlots, log.Identified ): """Provide loading behavior for a :class:`.Relationship` with "lazy=True", that is loads when first accessed. """ __slots__ = ( "_lazywhere", "_rev_lazywhere", "_lazyload_reverse_option", "_order_by", "use_get", "is_aliased_class", "_bind_to_col", "_equated_columns", "_rev_bind_to_col", "_rev_equated_columns", "_simple_lazy_clause", "_raise_always", "_raise_on_sql", ) _lazywhere: ColumnElement[bool] _bind_to_col: Dict[str, ColumnElement[Any]] _rev_lazywhere: ColumnElement[bool] _rev_bind_to_col: Dict[str, ColumnElement[Any]] parent_property: RelationshipProperty[Any] def __init__( self, parent: RelationshipProperty[Any], strategy_key: Tuple[Any, ...] ): super().__init__(parent, strategy_key) self._raise_always = self.strategy_opts["lazy"] == "raise" self._raise_on_sql = self.strategy_opts["lazy"] == "raise_on_sql" self.is_aliased_class = inspect(self.entity).is_aliased_class join_condition = self.parent_property._join_condition ( self._lazywhere, self._bind_to_col, self._equated_columns, ) = join_condition.create_lazy_clause() ( self._rev_lazywhere, self._rev_bind_to_col, self._rev_equated_columns, ) = join_condition.create_lazy_clause(reverse_direction=True) if self.parent_property.order_by: self._order_by = [ sql_util._deep_annotate(elem, {"_orm_adapt": True}) for elem in util.to_list(self.parent_property.order_by) ] else: self._order_by = None self.logger.info("%s lazy loading clause %s", self, self._lazywhere) # determine if our "lazywhere" clause is the same as the mapper's # get() clause. then we can just use mapper.get() # # TODO: the "not self.uselist" can be taken out entirely; a m2o # load that populates for a list (very unusual, but is possible with # the API) can still set for "None" and the attribute system will # populate as an empty list. self.use_get = ( not self.is_aliased_class and not self.uselist and self.entity._get_clause[0].compare( self._lazywhere, use_proxies=True, compare_keys=False, equivalents=self.mapper._equivalent_columns, ) ) if self.use_get: for col in list(self._equated_columns): if col in self.mapper._equivalent_columns: for c in self.mapper._equivalent_columns[col]: self._equated_columns[c] = self._equated_columns[col] self.logger.info( "%s will use Session.get() to optimize instance loads", self ) def init_class_attribute(self, mapper): self.is_class_level = True _legacy_inactive_history_style = ( self.parent_property._legacy_inactive_history_style ) if self.parent_property.active_history: active_history = True _deferred_history = False elif ( self.parent_property.direction is not interfaces.MANYTOONE or not self.use_get ): if _legacy_inactive_history_style: active_history = True _deferred_history = False else: active_history = False _deferred_history = True else: active_history = _deferred_history = False _register_attribute( self.parent_property, mapper, useobject=True, callable_=self._load_for_state, typecallable=self.parent_property.collection_class, active_history=active_history, _deferred_history=_deferred_history, ) def _memoized_attr__simple_lazy_clause(self): lazywhere = sql_util._deep_annotate( self._lazywhere, {"_orm_adapt": True} ) criterion, bind_to_col = (lazywhere, self._bind_to_col) params = [] def visit_bindparam(bindparam): bindparam.unique = False visitors.traverse(criterion, {}, {"bindparam": visit_bindparam}) def visit_bindparam(bindparam): if bindparam._identifying_key in bind_to_col: params.append( ( bindparam.key, bind_to_col[bindparam._identifying_key], None, ) ) elif bindparam.callable is None: params.append((bindparam.key, None, bindparam.value)) criterion = visitors.cloned_traverse( criterion, {}, {"bindparam": visit_bindparam} ) return criterion, params def _generate_lazy_clause(self, state, passive): criterion, param_keys = self._simple_lazy_clause if state is None: return sql_util.adapt_criterion_to_null( criterion, [key for key, ident, value in param_keys] ) mapper = self.parent_property.parent o = state.obj() # strong ref dict_ = attributes.instance_dict(o) if passive & PassiveFlag.INIT_OK: passive ^= PassiveFlag.INIT_OK params = {} for key, ident, value in param_keys: if ident is not None: if passive and passive & PassiveFlag.LOAD_AGAINST_COMMITTED: value = mapper._get_committed_state_attr_by_column( state, dict_, ident, passive ) else: value = mapper._get_state_attr_by_column( state, dict_, ident, passive ) params[key] = value return criterion, params def _invoke_raise_load(self, state, passive, lazy): raise sa_exc.InvalidRequestError( "'%s' is not available due to lazy='%s'" % (self, lazy) ) def _load_for_state( self, state, passive, loadopt=None, extra_criteria=(), extra_options=(), alternate_effective_path=None, execution_options=util.EMPTY_DICT, ): if not state.key and ( ( not self.parent_property.load_on_pending and not state._load_pending ) or not state.session_id ): return LoaderCallableStatus.ATTR_EMPTY pending = not state.key primary_key_identity = None use_get = self.use_get and (not loadopt or not loadopt._extra_criteria) if (not passive & PassiveFlag.SQL_OK and not use_get) or ( not passive & attributes.NON_PERSISTENT_OK and pending ): return LoaderCallableStatus.PASSIVE_NO_RESULT if ( # we were given lazy="raise" self._raise_always # the no_raise history-related flag was not passed and not passive & PassiveFlag.NO_RAISE and ( # if we are use_get and related_object_ok is disabled, # which means we are at most looking in the identity map # for history purposes or otherwise returning # PASSIVE_NO_RESULT, don't raise. This is also a # history-related flag not use_get or passive & PassiveFlag.RELATED_OBJECT_OK ) ): self._invoke_raise_load(state, passive, "raise") session = _state_session(state) if not session: if passive & PassiveFlag.NO_RAISE: return LoaderCallableStatus.PASSIVE_NO_RESULT raise orm_exc.DetachedInstanceError( "Parent instance %s is not bound to a Session; " "lazy load operation of attribute '%s' cannot proceed" % (orm_util.state_str(state), self.key) ) # if we have a simple primary key load, check the # identity map without generating a Query at all if use_get: primary_key_identity = self._get_ident_for_use_get( session, state, passive ) if LoaderCallableStatus.PASSIVE_NO_RESULT in primary_key_identity: return LoaderCallableStatus.PASSIVE_NO_RESULT elif LoaderCallableStatus.NEVER_SET in primary_key_identity: return LoaderCallableStatus.NEVER_SET # test for None alone in primary_key_identity based on # allow_partial_pks preference. PASSIVE_NO_RESULT and NEVER_SET # have already been tested above if not self.mapper.allow_partial_pks: if _none_only_set.intersection(primary_key_identity): return None else: if _none_only_set.issuperset(primary_key_identity): return None if ( self.key in state.dict and not passive & PassiveFlag.DEFERRED_HISTORY_LOAD ): return LoaderCallableStatus.ATTR_WAS_SET # look for this identity in the identity map. Delegate to the # Query class in use, as it may have special rules for how it # does this, including how it decides what the correct # identity_token would be for this identity. instance = session._identity_lookup( self.entity, primary_key_identity, passive=passive, lazy_loaded_from=state, ) if instance is not None: if instance is LoaderCallableStatus.PASSIVE_CLASS_MISMATCH: return None else: return instance elif ( not passive & PassiveFlag.SQL_OK or not passive & PassiveFlag.RELATED_OBJECT_OK ): return LoaderCallableStatus.PASSIVE_NO_RESULT return self._emit_lazyload( session, state, primary_key_identity, passive, loadopt, extra_criteria, extra_options, alternate_effective_path, execution_options, ) def _get_ident_for_use_get(self, session, state, passive): instance_mapper = state.manager.mapper if passive & PassiveFlag.LOAD_AGAINST_COMMITTED: get_attr = instance_mapper._get_committed_state_attr_by_column else: get_attr = instance_mapper._get_state_attr_by_column dict_ = state.dict return [ get_attr(state, dict_, self._equated_columns[pk], passive=passive) for pk in self.mapper.primary_key ] @util.preload_module("sqlalchemy.orm.strategy_options") def _emit_lazyload( self, session, state, primary_key_identity, passive, loadopt, extra_criteria, extra_options, alternate_effective_path, execution_options, ): strategy_options = util.preloaded.orm_strategy_options clauseelement = self.entity.__clause_element__() stmt = Select._create_raw_select( _raw_columns=[clauseelement], _propagate_attrs=clauseelement._propagate_attrs, _label_style=LABEL_STYLE_TABLENAME_PLUS_COL, _compile_options=ORMCompileState.default_compile_options, ) load_options = QueryContext.default_load_options load_options += { "_invoke_all_eagers": False, "_lazy_loaded_from": state, } if self.parent_property.secondary is not None: stmt = stmt.select_from( self.mapper, self.parent_property.secondary ) pending = not state.key # don't autoflush on pending if pending or passive & attributes.NO_AUTOFLUSH: stmt._execution_options = util.immutabledict({"autoflush": False}) use_get = self.use_get if state.load_options or (loadopt and loadopt._extra_criteria): if alternate_effective_path is None: effective_path = state.load_path[self.parent_property] else: effective_path = alternate_effective_path[self.parent_property] opts = state.load_options if loadopt and loadopt._extra_criteria: use_get = False opts += ( orm_util.LoaderCriteriaOption(self.entity, extra_criteria), ) stmt._with_options = opts elif alternate_effective_path is None: # this path is used if there are not already any options # in the query, but an event may want to add them effective_path = state.mapper._path_registry[self.parent_property] else: # added by immediateloader effective_path = alternate_effective_path[self.parent_property] if extra_options: stmt._with_options += extra_options stmt._compile_options += {"_current_path": effective_path} if use_get: if self._raise_on_sql and not passive & PassiveFlag.NO_RAISE: self._invoke_raise_load(state, passive, "raise_on_sql") return loading.load_on_pk_identity( session, stmt, primary_key_identity, load_options=load_options, execution_options=execution_options, ) if self._order_by: stmt._order_by_clauses = self._order_by def _lazyload_reverse(compile_context): for rev in self.parent_property._reverse_property: # reverse props that are MANYTOONE are loading *this* # object from get(), so don't need to eager out to those. if ( rev.direction is interfaces.MANYTOONE and rev._use_get and not isinstance(rev.strategy, LazyLoader) ): strategy_options.Load._construct_for_existing_path( compile_context.compile_options._current_path[ rev.parent ] ).lazyload(rev).process_compile_state(compile_context) stmt._with_context_options += ( (_lazyload_reverse, self.parent_property), ) lazy_clause, params = self._generate_lazy_clause(state, passive) if execution_options: execution_options = util.EMPTY_DICT.merge_with( execution_options, { "_sa_orm_load_options": load_options, }, ) else: execution_options = { "_sa_orm_load_options": load_options, } if ( self.key in state.dict and not passive & PassiveFlag.DEFERRED_HISTORY_LOAD ): return LoaderCallableStatus.ATTR_WAS_SET if pending: if util.has_intersection(orm_util._none_set, params.values()): return None elif util.has_intersection(orm_util._never_set, params.values()): return None if self._raise_on_sql and not passive & PassiveFlag.NO_RAISE: self._invoke_raise_load(state, passive, "raise_on_sql") stmt._where_criteria = (lazy_clause,) result = session.execute( stmt, params, execution_options=execution_options ) result = result.unique().scalars().all() if self.uselist: return result else: l = len(result) if l: if l > 1: util.warn( "Multiple rows returned with " "uselist=False for lazily-loaded attribute '%s' " % self.parent_property ) return result[0] else: return None def create_row_processor( self, context, query_entity, path, loadopt, mapper, result, adapter, populators, ): key = self.key if ( context.load_options._is_user_refresh and context.query._compile_options._only_load_props and self.key in context.query._compile_options._only_load_props ): return self._immediateload_create_row_processor( context, query_entity, path, loadopt, mapper, result, adapter, populators, ) if not self.is_class_level or (loadopt and loadopt._extra_criteria): # we are not the primary manager for this attribute # on this class - set up a # per-instance lazyloader, which will override the # class-level behavior. # this currently only happens when using a # "lazyload" option on a "no load" # attribute - "eager" attributes always have a # class-level lazyloader installed. set_lazy_callable = ( InstanceState._instance_level_callable_processor )( mapper.class_manager, LoadLazyAttribute( key, self, loadopt, ( loadopt._generate_extra_criteria(context) if loadopt._extra_criteria else None ), ), key, ) populators["new"].append((self.key, set_lazy_callable)) elif context.populate_existing or mapper.always_refresh: def reset_for_lazy_callable(state, dict_, row): # we are the primary manager for this attribute on # this class - reset its # per-instance attribute state, so that the class-level # lazy loader is # executed when next referenced on this instance. # this is needed in # populate_existing() types of scenarios to reset # any existing state. state._reset(dict_, key) populators["new"].append((self.key, reset_for_lazy_callable)) class LoadLazyAttribute: """semi-serializable loader object used by LazyLoader Historically, this object would be carried along with instances that needed to run lazyloaders, so it had to be serializable to support cached instances. this is no longer a general requirement, and the case where this object is used is exactly the case where we can't really serialize easily, which is when extra criteria in the loader option is present. We can't reliably serialize that as it refers to mapped entities and AliasedClass objects that are local to the current process, which would need to be matched up on deserialize e.g. the sqlalchemy.ext.serializer approach. """ def __init__(self, key, initiating_strategy, loadopt, extra_criteria): self.key = key self.strategy_key = initiating_strategy.strategy_key self.loadopt = loadopt self.extra_criteria = extra_criteria def __getstate__(self): if self.extra_criteria is not None: util.warn( "Can't reliably serialize a lazyload() option that " "contains additional criteria; please use eager loading " "for this case" ) return { "key": self.key, "strategy_key": self.strategy_key, "loadopt": self.loadopt, "extra_criteria": (), } def __call__(self, state, passive=attributes.PASSIVE_OFF): key = self.key instance_mapper = state.manager.mapper prop = instance_mapper._props[key] strategy = prop._strategies[self.strategy_key] return strategy._load_for_state( state, passive, loadopt=self.loadopt, extra_criteria=self.extra_criteria, ) class PostLoader(AbstractRelationshipLoader): """A relationship loader that emits a second SELECT statement.""" __slots__ = () def _setup_for_recursion(self, context, path, loadopt, join_depth=None): effective_path = ( context.compile_state.current_path or orm_util.PathRegistry.root ) + path top_level_context = context._get_top_level_context() execution_options = util.immutabledict( {"sa_top_level_orm_context": top_level_context} ) if loadopt: recursion_depth = loadopt.local_opts.get("recursion_depth", None) unlimited_recursion = recursion_depth == -1 else: recursion_depth = None unlimited_recursion = False if recursion_depth is not None: if not self.parent_property._is_self_referential: raise sa_exc.InvalidRequestError( f"recursion_depth option on relationship " f"{self.parent_property} not valid for " "non-self-referential relationship" ) recursion_depth = context.execution_options.get( f"_recursion_depth_{id(self)}", recursion_depth ) if not unlimited_recursion and recursion_depth < 0: return ( effective_path, False, execution_options, recursion_depth, ) if not unlimited_recursion: execution_options = execution_options.union( { f"_recursion_depth_{id(self)}": recursion_depth - 1, } ) if loading.PostLoad.path_exists( context, effective_path, self.parent_property ): return effective_path, False, execution_options, recursion_depth path_w_prop = path[self.parent_property] effective_path_w_prop = effective_path[self.parent_property] if not path_w_prop.contains(context.attributes, "loader"): if join_depth: if effective_path_w_prop.length / 2 > join_depth: return ( effective_path, False, execution_options, recursion_depth, ) elif effective_path_w_prop.contains_mapper(self.mapper): return ( effective_path, False, execution_options, recursion_depth, ) return effective_path, True, execution_options, recursion_depth @relationships.RelationshipProperty.strategy_for(lazy="immediate") class ImmediateLoader(PostLoader): __slots__ = ("join_depth",) def __init__(self, parent, strategy_key): super().__init__(parent, strategy_key) self.join_depth = self.parent_property.join_depth def init_class_attribute(self, mapper): self.parent_property._get_strategy( (("lazy", "select"),) ).init_class_attribute(mapper) def create_row_processor( self, context, query_entity, path, loadopt, mapper, result, adapter, populators, ): if not context.compile_state.compile_options._enable_eagerloads: return ( effective_path, run_loader, execution_options, recursion_depth, ) = self._setup_for_recursion(context, path, loadopt, self.join_depth) if not run_loader: # this will not emit SQL and will only emit for a many-to-one # "use get" load. the "_RELATED" part means it may return # instance even if its expired, since this is a mutually-recursive # load operation. flags = attributes.PASSIVE_NO_FETCH_RELATED | PassiveFlag.NO_RAISE else: flags = attributes.PASSIVE_OFF | PassiveFlag.NO_RAISE loading.PostLoad.callable_for_path( context, effective_path, self.parent, self.parent_property, self._load_for_path, loadopt, flags, recursion_depth, execution_options, ) def _load_for_path( self, context, path, states, load_only, loadopt, flags, recursion_depth, execution_options, ): if recursion_depth: new_opt = Load(loadopt.path.entity) new_opt.context = ( loadopt, loadopt._recurse(), ) alternate_effective_path = path._truncate_recursive() extra_options = (new_opt,) else: alternate_effective_path = path extra_options = () key = self.key lazyloader = self.parent_property._get_strategy((("lazy", "select"),)) for state, overwrite in states: dict_ = state.dict if overwrite or key not in dict_: value = lazyloader._load_for_state( state, flags, extra_options=extra_options, alternate_effective_path=alternate_effective_path, execution_options=execution_options, ) if value not in ( ATTR_WAS_SET, LoaderCallableStatus.PASSIVE_NO_RESULT, ): state.get_impl(key).set_committed_value( state, dict_, value ) @log.class_logger @relationships.RelationshipProperty.strategy_for(lazy="subquery") class SubqueryLoader(PostLoader): __slots__ = ("join_depth",) def __init__(self, parent, strategy_key): super().__init__(parent, strategy_key) self.join_depth = self.parent_property.join_depth def init_class_attribute(self, mapper): self.parent_property._get_strategy( (("lazy", "select"),) ).init_class_attribute(mapper) def _get_leftmost( self, orig_query_entity_index, subq_path, current_compile_state, is_root, ): given_subq_path = subq_path subq_path = subq_path.path subq_mapper = orm_util._class_to_mapper(subq_path[0]) # determine attributes of the leftmost mapper if ( self.parent.isa(subq_mapper) and self.parent_property is subq_path[1] ): leftmost_mapper, leftmost_prop = self.parent, self.parent_property else: leftmost_mapper, leftmost_prop = subq_mapper, subq_path[1] if is_root: # the subq_path is also coming from cached state, so when we start # building up this path, it has to also be converted to be in terms # of the current state. this is for the specific case of the entity # is an AliasedClass against a subquery that's not otherwise going # to adapt new_subq_path = current_compile_state._entities[ orig_query_entity_index ].entity_zero._path_registry[leftmost_prop] additional = len(subq_path) - len(new_subq_path) if additional: new_subq_path += path_registry.PathRegistry.coerce( subq_path[-additional:] ) else: new_subq_path = given_subq_path leftmost_cols = leftmost_prop.local_columns leftmost_attr = [ getattr( new_subq_path.path[0].entity, leftmost_mapper._columntoproperty[c].key, ) for c in leftmost_cols ] return leftmost_mapper, leftmost_attr, leftmost_prop, new_subq_path def _generate_from_original_query( self, orig_compile_state, orig_query, leftmost_mapper, leftmost_attr, leftmost_relationship, orig_entity, ): # reformat the original query # to look only for significant columns q = orig_query._clone().correlate(None) # LEGACY: make a Query back from the select() !! # This suits at least two legacy cases: # 1. applications which expect before_compile() to be called # below when we run .subquery() on this query (Keystone) # 2. applications which are doing subqueryload with complex # from_self() queries, as query.subquery() / .statement # has to do the full compile context for multiply-nested # from_self() (Neutron) - see test_subqload_from_self # for demo. q2 = query.Query.__new__(query.Query) q2.__dict__.update(q.__dict__) q = q2 # set the query's "FROM" list explicitly to what the # FROM list would be in any case, as we will be limiting # the columns in the SELECT list which may no longer include # all entities mentioned in things like WHERE, JOIN, etc. if not q._from_obj: q._enable_assertions = False q.select_from.non_generative( q, *{ ent["entity"] for ent in _column_descriptions( orig_query, compile_state=orig_compile_state ) if ent["entity"] is not None }, ) # select from the identity columns of the outer (specifically, these # are the 'local_cols' of the property). This will remove other # columns from the query that might suggest the right entity which is # why we do set select_from above. The attributes we have are # coerced and adapted using the original query's adapter, which is # needed only for the case of adapting a subclass column to # that of a polymorphic selectable, e.g. we have # Engineer.primary_language and the entity is Person. All other # adaptations, e.g. from_self, select_entity_from(), will occur # within the new query when it compiles, as the compile_state we are # using here is only a partial one. If the subqueryload is from a # with_polymorphic() or other aliased() object, left_attr will already # be the correct attributes so no adaptation is needed. target_cols = orig_compile_state._adapt_col_list( [ sql.coercions.expect(sql.roles.ColumnsClauseRole, o) for o in leftmost_attr ], orig_compile_state._get_current_adapter(), ) q._raw_columns = target_cols distinct_target_key = leftmost_relationship.distinct_target_key if distinct_target_key is True: q._distinct = True elif distinct_target_key is None: # if target_cols refer to a non-primary key or only # part of a composite primary key, set the q as distinct for t in {c.table for c in target_cols}: if not set(target_cols).issuperset(t.primary_key): q._distinct = True break # don't need ORDER BY if no limit/offset if not q._has_row_limiting_clause: q._order_by_clauses = () if q._distinct is True and q._order_by_clauses: # the logic to automatically add the order by columns to the query # when distinct is True is deprecated in the query to_add = sql_util.expand_column_list_from_order_by( target_cols, q._order_by_clauses ) if to_add: q._set_entities(target_cols + to_add) # the original query now becomes a subquery # which we'll join onto. # LEGACY: as "q" is a Query, the before_compile() event is invoked # here. embed_q = q.set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL).subquery() left_alias = orm_util.AliasedClass( leftmost_mapper, embed_q, use_mapper_path=True ) return left_alias def _prep_for_joins(self, left_alias, subq_path): # figure out what's being joined. a.k.a. the fun part to_join = [] pairs = list(subq_path.pairs()) for i, (mapper, prop) in enumerate(pairs): if i > 0: # look at the previous mapper in the chain - # if it is as or more specific than this prop's # mapper, use that instead. # note we have an assumption here that # the non-first element is always going to be a mapper, # not an AliasedClass prev_mapper = pairs[i - 1][1].mapper to_append = prev_mapper if prev_mapper.isa(mapper) else mapper else: to_append = mapper to_join.append((to_append, prop.key)) # determine the immediate parent class we are joining from, # which needs to be aliased. if len(to_join) < 2: # in the case of a one level eager load, this is the # leftmost "left_alias". parent_alias = left_alias else: info = inspect(to_join[-1][0]) if info.is_aliased_class: parent_alias = info.entity else: # alias a plain mapper as we may be # joining multiple times parent_alias = orm_util.AliasedClass( info.entity, use_mapper_path=True ) local_cols = self.parent_property.local_columns local_attr = [ getattr(parent_alias, self.parent._columntoproperty[c].key) for c in local_cols ] return to_join, local_attr, parent_alias def _apply_joins( self, q, to_join, left_alias, parent_alias, effective_entity ): ltj = len(to_join) if ltj == 1: to_join = [ getattr(left_alias, to_join[0][1]).of_type(effective_entity) ] elif ltj == 2: to_join = [ getattr(left_alias, to_join[0][1]).of_type(parent_alias), getattr(parent_alias, to_join[-1][1]).of_type( effective_entity ), ] elif ltj > 2: middle = [ ( ( orm_util.AliasedClass(item[0]) if not inspect(item[0]).is_aliased_class else item[0].entity ), item[1], ) for item in to_join[1:-1] ] inner = [] while middle: item = middle.pop(0) attr = getattr(item[0], item[1]) if middle: attr = attr.of_type(middle[0][0]) else: attr = attr.of_type(parent_alias) inner.append(attr) to_join = ( [getattr(left_alias, to_join[0][1]).of_type(inner[0].parent)] + inner + [ getattr(parent_alias, to_join[-1][1]).of_type( effective_entity ) ] ) for attr in to_join: q = q.join(attr) return q def _setup_options( self, context, q, subq_path, rewritten_path, orig_query, effective_entity, loadopt, ): # note that because the subqueryload object # does not re-use the cached query, instead always making # use of the current invoked query, while we have two queries # here (orig and context.query), they are both non-cached # queries and we can transfer the options as is without # adjusting for new criteria. Some work on #6881 / #6889 # brought this into question. new_options = orig_query._with_options if loadopt and loadopt._extra_criteria: new_options += ( orm_util.LoaderCriteriaOption( self.entity, loadopt._generate_extra_criteria(context), ), ) # propagate loader options etc. to the new query. # these will fire relative to subq_path. q = q._with_current_path(rewritten_path) q = q.options(*new_options) return q def _setup_outermost_orderby(self, q): if self.parent_property.order_by: def _setup_outermost_orderby(compile_context): compile_context.eager_order_by += tuple( util.to_list(self.parent_property.order_by) ) q = q._add_context_option( _setup_outermost_orderby, self.parent_property ) return q class _SubqCollections: """Given a :class:`_query.Query` used to emit the "subquery load", provide a load interface that executes the query at the first moment a value is needed. """ __slots__ = ( "session", "execution_options", "load_options", "params", "subq", "_data", ) def __init__(self, context, subq): # avoid creating a cycle by storing context # even though that's preferable self.session = context.session self.execution_options = context.execution_options self.load_options = context.load_options self.params = context.params or {} self.subq = subq self._data = None def get(self, key, default): if self._data is None: self._load() return self._data.get(key, default) def _load(self): self._data = collections.defaultdict(list) q = self.subq assert q.session is None q = q.with_session(self.session) if self.load_options._populate_existing: q = q.populate_existing() # to work with baked query, the parameters may have been # updated since this query was created, so take these into account rows = list(q.params(self.params)) for k, v in itertools.groupby(rows, lambda x: x[1:]): self._data[k].extend(vv[0] for vv in v) def loader(self, state, dict_, row): if self._data is None: self._load() def _setup_query_from_rowproc( self, context, query_entity, path, entity, loadopt, adapter, ): compile_state = context.compile_state if ( not compile_state.compile_options._enable_eagerloads or compile_state.compile_options._for_refresh_state ): return orig_query_entity_index = compile_state._entities.index(query_entity) context.loaders_require_buffering = True path = path[self.parent_property] # build up a path indicating the path from the leftmost # entity to the thing we're subquery loading. with_poly_entity = path.get( compile_state.attributes, "path_with_polymorphic", None ) if with_poly_entity is not None: effective_entity = with_poly_entity else: effective_entity = self.entity subq_path, rewritten_path = context.query._execution_options.get( ("subquery_paths", None), (orm_util.PathRegistry.root, orm_util.PathRegistry.root), ) is_root = subq_path is orm_util.PathRegistry.root subq_path = subq_path + path rewritten_path = rewritten_path + path # use the current query being invoked, not the compile state # one. this is so that we get the current parameters. however, # it means we can't use the existing compile state, we have to make # a new one. other approaches include possibly using the # compiled query but swapping the params, seems only marginally # less time spent but more complicated orig_query = context.query._execution_options.get( ("orig_query", SubqueryLoader), context.query ) # make a new compile_state for the query that's probably cached, but # we're sort of undoing a bit of that caching :( compile_state_cls = ORMCompileState._get_plugin_class_for_plugin( orig_query, "orm" ) if orig_query._is_lambda_element: if context.load_options._lazy_loaded_from is None: util.warn( 'subqueryloader for "%s" must invoke lambda callable ' "at %r in " "order to produce a new query, decreasing the efficiency " "of caching for this statement. Consider using " "selectinload() for more effective full-lambda caching" % (self, orig_query) ) orig_query = orig_query._resolved # this is the more "quick" version, however it's not clear how # much of this we need. in particular I can't get a test to # fail if the "set_base_alias" is missing and not sure why that is. orig_compile_state = compile_state_cls._create_entities_collection( orig_query, legacy=False ) ( leftmost_mapper, leftmost_attr, leftmost_relationship, rewritten_path, ) = self._get_leftmost( orig_query_entity_index, rewritten_path, orig_compile_state, is_root, ) # generate a new Query from the original, then # produce a subquery from it. left_alias = self._generate_from_original_query( orig_compile_state, orig_query, leftmost_mapper, leftmost_attr, leftmost_relationship, entity, ) # generate another Query that will join the # left alias to the target relationships. # basically doing a longhand # "from_self()". (from_self() itself not quite industrial # strength enough for all contingencies...but very close) q = query.Query(effective_entity) q._execution_options = context.query._execution_options.merge_with( context.execution_options, { ("orig_query", SubqueryLoader): orig_query, ("subquery_paths", None): (subq_path, rewritten_path), }, ) q = q._set_enable_single_crit(False) to_join, local_attr, parent_alias = self._prep_for_joins( left_alias, subq_path ) q = q.add_columns(*local_attr) q = self._apply_joins( q, to_join, left_alias, parent_alias, effective_entity ) q = self._setup_options( context, q, subq_path, rewritten_path, orig_query, effective_entity, loadopt, ) q = self._setup_outermost_orderby(q) return q def create_row_processor( self, context, query_entity, path, loadopt, mapper, result, adapter, populators, ): if ( loadopt and context.compile_state.statement is not None and context.compile_state.statement.is_dml ): util.warn_deprecated( "The subqueryload loader option is not compatible with DML " "statements such as INSERT, UPDATE. Only SELECT may be used." "This warning will become an exception in a future release.", "2.0", ) if context.refresh_state: return self._immediateload_create_row_processor( context, query_entity, path, loadopt, mapper, result, adapter, populators, ) _, run_loader, _, _ = self._setup_for_recursion( context, path, loadopt, self.join_depth ) if not run_loader: return if not isinstance(context.compile_state, ORMSelectCompileState): # issue 7505 - subqueryload() in 1.3 and previous would silently # degrade for from_statement() without warning. this behavior # is restored here return if not self.parent.class_manager[self.key].impl.supports_population: raise sa_exc.InvalidRequestError( "'%s' does not support object " "population - eager loading cannot be applied." % self ) # a little dance here as the "path" is still something that only # semi-tracks the exact series of things we are loading, still not # telling us about with_polymorphic() and stuff like that when it's at # the root.. the initial MapperEntity is more accurate for this case. if len(path) == 1: if not orm_util._entity_isa(query_entity.entity_zero, self.parent): return elif not orm_util._entity_isa(path[-1], self.parent): return subq = self._setup_query_from_rowproc( context, query_entity, path, path[-1], loadopt, adapter, ) if subq is None: return assert subq.session is None path = path[self.parent_property] local_cols = self.parent_property.local_columns # cache the loaded collections in the context # so that inheriting mappers don't re-load when they # call upon create_row_processor again collections = path.get(context.attributes, "collections") if collections is None: collections = self._SubqCollections(context, subq) path.set(context.attributes, "collections", collections) if adapter: local_cols = [adapter.columns[c] for c in local_cols] if self.uselist: self._create_collection_loader( context, result, collections, local_cols, populators ) else: self._create_scalar_loader( context, result, collections, local_cols, populators ) def _create_collection_loader( self, context, result, collections, local_cols, populators ): tuple_getter = result._tuple_getter(local_cols) def load_collection_from_subq(state, dict_, row): collection = collections.get(tuple_getter(row), ()) state.get_impl(self.key).set_committed_value( state, dict_, collection ) def load_collection_from_subq_existing_row(state, dict_, row): if self.key not in dict_: load_collection_from_subq(state, dict_, row) populators["new"].append((self.key, load_collection_from_subq)) populators["existing"].append( (self.key, load_collection_from_subq_existing_row) ) if context.invoke_all_eagers: populators["eager"].append((self.key, collections.loader)) def _create_scalar_loader( self, context, result, collections, local_cols, populators ): tuple_getter = result._tuple_getter(local_cols) def load_scalar_from_subq(state, dict_, row): collection = collections.get(tuple_getter(row), (None,)) if len(collection) > 1: util.warn( "Multiple rows returned with " "uselist=False for eagerly-loaded attribute '%s' " % self ) scalar = collection[0] state.get_impl(self.key).set_committed_value(state, dict_, scalar) def load_scalar_from_subq_existing_row(state, dict_, row): if self.key not in dict_: load_scalar_from_subq(state, dict_, row) populators["new"].append((self.key, load_scalar_from_subq)) populators["existing"].append( (self.key, load_scalar_from_subq_existing_row) ) if context.invoke_all_eagers: populators["eager"].append((self.key, collections.loader)) @log.class_logger @relationships.RelationshipProperty.strategy_for(lazy="joined") @relationships.RelationshipProperty.strategy_for(lazy=False) class JoinedLoader(AbstractRelationshipLoader): """Provide loading behavior for a :class:`.Relationship` using joined eager loading. """ __slots__ = "join_depth" def __init__(self, parent, strategy_key): super().__init__(parent, strategy_key) self.join_depth = self.parent_property.join_depth def init_class_attribute(self, mapper): self.parent_property._get_strategy( (("lazy", "select"),) ).init_class_attribute(mapper) def setup_query( self, compile_state, query_entity, path, loadopt, adapter, column_collection=None, parentmapper=None, chained_from_outerjoin=False, **kwargs, ): """Add a left outer join to the statement that's being constructed.""" if not compile_state.compile_options._enable_eagerloads: return elif ( loadopt and compile_state.statement is not None and compile_state.statement.is_dml ): util.warn_deprecated( "The joinedload loader option is not compatible with DML " "statements such as INSERT, UPDATE. Only SELECT may be used." "This warning will become an exception in a future release.", "2.0", ) elif self.uselist: compile_state.multi_row_eager_loaders = True path = path[self.parent_property] user_defined_adapter = ( self._init_user_defined_eager_proc( loadopt, compile_state, compile_state.attributes ) if loadopt else False ) if user_defined_adapter is not False: # setup an adapter but dont create any JOIN, assume it's already # in the query ( clauses, adapter, add_to_collection, ) = self._setup_query_on_user_defined_adapter( compile_state, query_entity, path, adapter, user_defined_adapter, ) # don't do "wrap" for multi-row, we want to wrap # limited/distinct SELECT, # because we want to put the JOIN on the outside. else: # if not via query option, check for # a cycle if not path.contains(compile_state.attributes, "loader"): if self.join_depth: if path.length / 2 > self.join_depth: return elif path.contains_mapper(self.mapper): return # add the JOIN and create an adapter ( clauses, adapter, add_to_collection, chained_from_outerjoin, ) = self._generate_row_adapter( compile_state, query_entity, path, loadopt, adapter, column_collection, parentmapper, chained_from_outerjoin, ) # for multi-row, we want to wrap limited/distinct SELECT, # because we want to put the JOIN on the outside. compile_state.eager_adding_joins = True with_poly_entity = path.get( compile_state.attributes, "path_with_polymorphic", None ) if with_poly_entity is not None: with_polymorphic = inspect( with_poly_entity ).with_polymorphic_mappers else: with_polymorphic = None path = path[self.entity] loading._setup_entity_query( compile_state, self.mapper, query_entity, path, clauses, add_to_collection, with_polymorphic=with_polymorphic, parentmapper=self.mapper, chained_from_outerjoin=chained_from_outerjoin, ) has_nones = util.NONE_SET.intersection(compile_state.secondary_columns) if has_nones: if with_poly_entity is not None: raise sa_exc.InvalidRequestError( "Detected unaliased columns when generating joined " "load. Make sure to use aliased=True or flat=True " "when using joined loading with with_polymorphic()." ) else: compile_state.secondary_columns = [ c for c in compile_state.secondary_columns if c is not None ] def _init_user_defined_eager_proc( self, loadopt, compile_state, target_attributes ): # check if the opt applies at all if "eager_from_alias" not in loadopt.local_opts: # nope return False path = loadopt.path.parent # the option applies. check if the "user_defined_eager_row_processor" # has been built up. adapter = path.get( compile_state.attributes, "user_defined_eager_row_processor", False ) if adapter is not False: # just return it return adapter # otherwise figure it out. alias = loadopt.local_opts["eager_from_alias"] root_mapper, prop = path[-2:] if alias is not None: if isinstance(alias, str): alias = prop.target.alias(alias) adapter = orm_util.ORMAdapter( orm_util._TraceAdaptRole.JOINEDLOAD_USER_DEFINED_ALIAS, prop.mapper, selectable=alias, equivalents=prop.mapper._equivalent_columns, limit_on_entity=False, ) else: if path.contains( compile_state.attributes, "path_with_polymorphic" ): with_poly_entity = path.get( compile_state.attributes, "path_with_polymorphic" ) adapter = orm_util.ORMAdapter( orm_util._TraceAdaptRole.JOINEDLOAD_PATH_WITH_POLYMORPHIC, with_poly_entity, equivalents=prop.mapper._equivalent_columns, ) else: adapter = compile_state._polymorphic_adapters.get( prop.mapper, None ) path.set( target_attributes, "user_defined_eager_row_processor", adapter, ) return adapter def _setup_query_on_user_defined_adapter( self, context, entity, path, adapter, user_defined_adapter ): # apply some more wrapping to the "user defined adapter" # if we are setting up the query for SQL render. adapter = entity._get_entity_clauses(context) if adapter and user_defined_adapter: user_defined_adapter = user_defined_adapter.wrap(adapter) path.set( context.attributes, "user_defined_eager_row_processor", user_defined_adapter, ) elif adapter: user_defined_adapter = adapter path.set( context.attributes, "user_defined_eager_row_processor", user_defined_adapter, ) add_to_collection = context.primary_columns return user_defined_adapter, adapter, add_to_collection def _generate_row_adapter( self, compile_state, entity, path, loadopt, adapter, column_collection, parentmapper, chained_from_outerjoin, ): with_poly_entity = path.get( compile_state.attributes, "path_with_polymorphic", None ) if with_poly_entity: to_adapt = with_poly_entity else: insp = inspect(self.entity) if insp.is_aliased_class: alt_selectable = insp.selectable else: alt_selectable = None to_adapt = orm_util.AliasedClass( self.mapper, alias=( alt_selectable._anonymous_fromclause(flat=True) if alt_selectable is not None else None ), flat=True, use_mapper_path=True, ) to_adapt_insp = inspect(to_adapt) clauses = to_adapt_insp._memo( ("joinedloader_ormadapter", self), orm_util.ORMAdapter, orm_util._TraceAdaptRole.JOINEDLOAD_MEMOIZED_ADAPTER, to_adapt_insp, equivalents=self.mapper._equivalent_columns, adapt_required=True, allow_label_resolve=False, anonymize_labels=True, ) assert clauses.is_aliased_class innerjoin = ( loadopt.local_opts.get("innerjoin", self.parent_property.innerjoin) if loadopt is not None else self.parent_property.innerjoin ) if not innerjoin: # if this is an outer join, all non-nested eager joins from # this path must also be outer joins chained_from_outerjoin = True compile_state.create_eager_joins.append( ( self._create_eager_join, entity, path, adapter, parentmapper, clauses, innerjoin, chained_from_outerjoin, loadopt._extra_criteria if loadopt else (), ) ) add_to_collection = compile_state.secondary_columns path.set(compile_state.attributes, "eager_row_processor", clauses) return clauses, adapter, add_to_collection, chained_from_outerjoin def _create_eager_join( self, compile_state, query_entity, path, adapter, parentmapper, clauses, innerjoin, chained_from_outerjoin, extra_criteria, ): if parentmapper is None: localparent = query_entity.mapper else: localparent = parentmapper # whether or not the Query will wrap the selectable in a subquery, # and then attach eager load joins to that (i.e., in the case of # LIMIT/OFFSET etc.) should_nest_selectable = ( compile_state.multi_row_eager_loaders and compile_state._should_nest_selectable ) query_entity_key = None if ( query_entity not in compile_state.eager_joins and not should_nest_selectable and compile_state.from_clauses ): indexes = sql_util.find_left_clause_that_matches_given( compile_state.from_clauses, query_entity.selectable ) if len(indexes) > 1: # for the eager load case, I can't reproduce this right # now. For query.join() I can. raise sa_exc.InvalidRequestError( "Can't identify which query entity in which to joined " "eager load from. Please use an exact match when " "specifying the join path." ) if indexes: clause = compile_state.from_clauses[indexes[0]] # join to an existing FROM clause on the query. # key it to its list index in the eager_joins dict. # Query._compile_context will adapt as needed and # append to the FROM clause of the select(). query_entity_key, default_towrap = indexes[0], clause if query_entity_key is None: query_entity_key, default_towrap = ( query_entity, query_entity.selectable, ) towrap = compile_state.eager_joins.setdefault( query_entity_key, default_towrap ) if adapter: if getattr(adapter, "is_aliased_class", False): # joining from an adapted entity. The adapted entity # might be a "with_polymorphic", so resolve that to our # specific mapper's entity before looking for our attribute # name on it. efm = adapter.aliased_insp._entity_for_mapper( localparent if localparent.isa(self.parent) else self.parent ) # look for our attribute on the adapted entity, else fall back # to our straight property onclause = getattr(efm.entity, self.key, self.parent_property) else: onclause = getattr( orm_util.AliasedClass( self.parent, adapter.selectable, use_mapper_path=True ), self.key, self.parent_property, ) else: onclause = self.parent_property assert clauses.is_aliased_class attach_on_outside = ( not chained_from_outerjoin or not innerjoin or innerjoin == "unnested" or query_entity.entity_zero.represents_outer_join ) extra_join_criteria = extra_criteria additional_entity_criteria = compile_state.global_attributes.get( ("additional_entity_criteria", self.mapper), () ) if additional_entity_criteria: extra_join_criteria += tuple( ae._resolve_where_criteria(self.mapper) for ae in additional_entity_criteria if ae.propagate_to_loaders ) if attach_on_outside: # this is the "classic" eager join case. eagerjoin = orm_util._ORMJoin( towrap, clauses.aliased_insp, onclause, isouter=not innerjoin or query_entity.entity_zero.represents_outer_join or (chained_from_outerjoin and isinstance(towrap, sql.Join)), _left_memo=self.parent, _right_memo=path[self.mapper], _extra_criteria=extra_join_criteria, ) else: # all other cases are innerjoin=='nested' approach eagerjoin = self._splice_nested_inner_join( path, path[-2], towrap, clauses, onclause, extra_join_criteria ) compile_state.eager_joins[query_entity_key] = eagerjoin # send a hint to the Query as to where it may "splice" this join eagerjoin.stop_on = query_entity.selectable if not parentmapper: # for parentclause that is the non-eager end of the join, # ensure all the parent cols in the primaryjoin are actually # in the # columns clause (i.e. are not deferred), so that aliasing applied # by the Query propagates those columns outward. # This has the effect # of "undefering" those columns. for col in sql_util._find_columns( self.parent_property.primaryjoin ): if localparent.persist_selectable.c.contains_column(col): if adapter: col = adapter.columns[col] compile_state._append_dedupe_col_collection( col, compile_state.primary_columns ) if self.parent_property.order_by: compile_state.eager_order_by += tuple( (eagerjoin._target_adapter.copy_and_process)( util.to_list(self.parent_property.order_by) ) ) def _splice_nested_inner_join( self, path, entity_we_want_to_splice_onto, join_obj, clauses, onclause, extra_criteria, entity_inside_join_structure: Union[ Mapper, None, Literal[False] ] = False, detected_existing_path: Optional[path_registry.PathRegistry] = None, ): # recursive fn to splice a nested join into an existing one. # entity_inside_join_structure=False means this is the outermost call, # and it should return a value. entity_inside_join_structure=<mapper> # indicates we've descended into a join and are looking at a FROM # clause representing this mapper; if this is not # entity_we_want_to_splice_onto then return None to end the recursive # branch assert entity_we_want_to_splice_onto is path[-2] if entity_inside_join_structure is False: assert isinstance(join_obj, orm_util._ORMJoin) if isinstance(join_obj, sql.selectable.FromGrouping): # FromGrouping - continue descending into the structure return self._splice_nested_inner_join( path, entity_we_want_to_splice_onto, join_obj.element, clauses, onclause, extra_criteria, entity_inside_join_structure, ) elif isinstance(join_obj, orm_util._ORMJoin): # _ORMJoin - continue descending into the structure join_right_path = join_obj._right_memo # see if right side of join is viable target_join = self._splice_nested_inner_join( path, entity_we_want_to_splice_onto, join_obj.right, clauses, onclause, extra_criteria, entity_inside_join_structure=( join_right_path[-1].mapper if join_right_path is not None else None ), ) if target_join is not None: # for a right splice, attempt to flatten out # a JOIN b JOIN c JOIN .. to avoid needless # parenthesis nesting if not join_obj.isouter and not target_join.isouter: eagerjoin = join_obj._splice_into_center(target_join) else: eagerjoin = orm_util._ORMJoin( join_obj.left, target_join, join_obj.onclause, isouter=join_obj.isouter, _left_memo=join_obj._left_memo, ) eagerjoin._target_adapter = target_join._target_adapter return eagerjoin else: # see if left side of join is viable target_join = self._splice_nested_inner_join( path, entity_we_want_to_splice_onto, join_obj.left, clauses, onclause, extra_criteria, entity_inside_join_structure=join_obj._left_memo, detected_existing_path=join_right_path, ) if target_join is not None: eagerjoin = orm_util._ORMJoin( target_join, join_obj.right, join_obj.onclause, isouter=join_obj.isouter, _right_memo=join_obj._right_memo, ) eagerjoin._target_adapter = target_join._target_adapter return eagerjoin # neither side viable, return None, or fail if this was the top # most call if entity_inside_join_structure is False: assert ( False ), "assertion failed attempting to produce joined eager loads" return None # reached an endpoint (e.g. a table that's mapped, or an alias of that # table). determine if we can use this endpoint to splice onto # is this the entity we want to splice onto in the first place? if not entity_we_want_to_splice_onto.isa(entity_inside_join_structure): return None # path check. if we know the path how this join endpoint got here, # lets look at our path we are satisfying and see if we're in the # wrong place. This is specifically for when our entity may # appear more than once in the path, issue #11449 # updated in issue #11965. if detected_existing_path and len(detected_existing_path) > 2: # this assertion is currently based on how this call is made, # where given a join_obj, the call will have these parameters as # entity_inside_join_structure=join_obj._left_memo # and entity_inside_join_structure=join_obj._right_memo.mapper assert detected_existing_path[-3] is entity_inside_join_structure # from that, see if the path we are targeting matches the # "existing" path of this join all the way up to the midpoint # of this join object (e.g. the relationship). # if not, then this is not our target # # a test condition where this test is false looks like: # # desired splice: Node->kind->Kind # path of desired splice: NodeGroup->nodes->Node->kind # path we've located: NodeGroup->nodes->Node->common_node->Node # # above, because we want to splice kind->Kind onto # NodeGroup->nodes->Node, this is not our path because it actually # goes more steps than we want into self-referential # ->common_node->Node # # a test condition where this test is true looks like: # # desired splice: B->c2s->C2 # path of desired splice: A->bs->B->c2s # path we've located: A->bs->B->c1s->C1 # # above, we want to splice c2s->C2 onto B, and the located path # shows that the join ends with B->c1s->C1. so we will # add another join onto that, which would create a "branch" that # we might represent in a pseudopath as: # # B->c1s->C1 # ->c2s->C2 # # i.e. A JOIN B ON <bs> JOIN C1 ON <c1s> # JOIN C2 ON <c2s> # if detected_existing_path[0:-2] != path.path[0:-1]: return None return orm_util._ORMJoin( join_obj, clauses.aliased_insp, onclause, isouter=False, _left_memo=entity_inside_join_structure, _right_memo=path[path[-1].mapper], _extra_criteria=extra_criteria, ) def _create_eager_adapter(self, context, result, adapter, path, loadopt): compile_state = context.compile_state user_defined_adapter = ( self._init_user_defined_eager_proc( loadopt, compile_state, context.attributes ) if loadopt else False ) if user_defined_adapter is not False: decorator = user_defined_adapter # user defined eagerloads are part of the "primary" # portion of the load. # the adapters applied to the Query should be honored. if compile_state.compound_eager_adapter and decorator: decorator = decorator.wrap( compile_state.compound_eager_adapter ) elif compile_state.compound_eager_adapter: decorator = compile_state.compound_eager_adapter else: decorator = path.get( compile_state.attributes, "eager_row_processor" ) if decorator is None: return False if self.mapper._result_has_identity_key(result, decorator): return decorator else: # no identity key - don't return a row # processor, will cause a degrade to lazy return False def create_row_processor( self, context, query_entity, path, loadopt, mapper, result, adapter, populators, ): if not context.compile_state.compile_options._enable_eagerloads: return if not self.parent.class_manager[self.key].impl.supports_population: raise sa_exc.InvalidRequestError( "'%s' does not support object " "population - eager loading cannot be applied." % self ) if self.uselist: context.loaders_require_uniquing = True our_path = path[self.parent_property] eager_adapter = self._create_eager_adapter( context, result, adapter, our_path, loadopt ) if eager_adapter is not False: key = self.key _instance = loading._instance_processor( query_entity, self.mapper, context, result, our_path[self.entity], eager_adapter, ) if not self.uselist: self._create_scalar_loader(context, key, _instance, populators) else: self._create_collection_loader( context, key, _instance, populators ) else: self.parent_property._get_strategy( (("lazy", "select"),) ).create_row_processor( context, query_entity, path, loadopt, mapper, result, adapter, populators, ) def _create_collection_loader(self, context, key, _instance, populators): def load_collection_from_joined_new_row(state, dict_, row): # note this must unconditionally clear out any existing collection. # an existing collection would be present only in the case of # populate_existing(). collection = attributes.init_state_collection(state, dict_, key) result_list = util.UniqueAppender( collection, "append_without_event" ) context.attributes[(state, key)] = result_list inst = _instance(row) if inst is not None: result_list.append(inst) def load_collection_from_joined_existing_row(state, dict_, row): if (state, key) in context.attributes: result_list = context.attributes[(state, key)] else: # appender_key can be absent from context.attributes # with isnew=False when self-referential eager loading # is used; the same instance may be present in two # distinct sets of result columns collection = attributes.init_state_collection( state, dict_, key ) result_list = util.UniqueAppender( collection, "append_without_event" ) context.attributes[(state, key)] = result_list inst = _instance(row) if inst is not None: result_list.append(inst) def load_collection_from_joined_exec(state, dict_, row): _instance(row) populators["new"].append( (self.key, load_collection_from_joined_new_row) ) populators["existing"].append( (self.key, load_collection_from_joined_existing_row) ) if context.invoke_all_eagers: populators["eager"].append( (self.key, load_collection_from_joined_exec) ) def _create_scalar_loader(self, context, key, _instance, populators): def load_scalar_from_joined_new_row(state, dict_, row): # set a scalar object instance directly on the parent # object, bypassing InstrumentedAttribute event handlers. dict_[key] = _instance(row) def load_scalar_from_joined_existing_row(state, dict_, row): # call _instance on the row, even though the object has # been created, so that we further descend into properties existing = _instance(row) # conflicting value already loaded, this shouldn't happen if key in dict_: if existing is not dict_[key]: util.warn( "Multiple rows returned with " "uselist=False for eagerly-loaded attribute '%s' " % self ) else: # this case is when one row has multiple loads of the # same entity (e.g. via aliasing), one has an attribute # that the other doesn't. dict_[key] = existing def load_scalar_from_joined_exec(state, dict_, row): _instance(row) populators["new"].append((self.key, load_scalar_from_joined_new_row)) populators["existing"].append( (self.key, load_scalar_from_joined_existing_row) ) if context.invoke_all_eagers: populators["eager"].append( (self.key, load_scalar_from_joined_exec) ) @log.class_logger @relationships.RelationshipProperty.strategy_for(lazy="selectin") class SelectInLoader(PostLoader, util.MemoizedSlots): __slots__ = ( "join_depth", "omit_join", "_parent_alias", "_query_info", "_fallback_query_info", ) query_info = collections.namedtuple( "queryinfo", [ "load_only_child", "load_with_join", "in_expr", "pk_cols", "zero_idx", "child_lookup_cols", ], ) _chunksize = 500 def __init__(self, parent, strategy_key): super().__init__(parent, strategy_key) self.join_depth = self.parent_property.join_depth is_m2o = self.parent_property.direction is interfaces.MANYTOONE if self.parent_property.omit_join is not None: self.omit_join = self.parent_property.omit_join else: lazyloader = self.parent_property._get_strategy( (("lazy", "select"),) ) if is_m2o: self.omit_join = lazyloader.use_get else: self.omit_join = self.parent._get_clause[0].compare( lazyloader._rev_lazywhere, use_proxies=True, compare_keys=False, equivalents=self.parent._equivalent_columns, ) if self.omit_join: if is_m2o: self._query_info = self._init_for_omit_join_m2o() self._fallback_query_info = self._init_for_join() else: self._query_info = self._init_for_omit_join() else: self._query_info = self._init_for_join() def _init_for_omit_join(self): pk_to_fk = dict( self.parent_property._join_condition.local_remote_pairs ) pk_to_fk.update( (equiv, pk_to_fk[k]) for k in list(pk_to_fk) for equiv in self.parent._equivalent_columns.get(k, ()) ) pk_cols = fk_cols = [ pk_to_fk[col] for col in self.parent.primary_key if col in pk_to_fk ] if len(fk_cols) > 1: in_expr = sql.tuple_(*fk_cols) zero_idx = False else: in_expr = fk_cols[0] zero_idx = True return self.query_info(False, False, in_expr, pk_cols, zero_idx, None) def _init_for_omit_join_m2o(self): pk_cols = self.mapper.primary_key if len(pk_cols) > 1: in_expr = sql.tuple_(*pk_cols) zero_idx = False else: in_expr = pk_cols[0] zero_idx = True lazyloader = self.parent_property._get_strategy((("lazy", "select"),)) lookup_cols = [lazyloader._equated_columns[pk] for pk in pk_cols] return self.query_info( True, False, in_expr, pk_cols, zero_idx, lookup_cols ) def _init_for_join(self): self._parent_alias = AliasedClass(self.parent.class_) pa_insp = inspect(self._parent_alias) pk_cols = [ pa_insp._adapt_element(col) for col in self.parent.primary_key ] if len(pk_cols) > 1: in_expr = sql.tuple_(*pk_cols) zero_idx = False else: in_expr = pk_cols[0] zero_idx = True return self.query_info(False, True, in_expr, pk_cols, zero_idx, None) def init_class_attribute(self, mapper): self.parent_property._get_strategy( (("lazy", "select"),) ).init_class_attribute(mapper) def create_row_processor( self, context, query_entity, path, loadopt, mapper, result, adapter, populators, ): if context.refresh_state: return self._immediateload_create_row_processor( context, query_entity, path, loadopt, mapper, result, adapter, populators, ) ( effective_path, run_loader, execution_options, recursion_depth, ) = self._setup_for_recursion( context, path, loadopt, join_depth=self.join_depth ) if not run_loader: return if not context.compile_state.compile_options._enable_eagerloads: return if not self.parent.class_manager[self.key].impl.supports_population: raise sa_exc.InvalidRequestError( "'%s' does not support object " "population - eager loading cannot be applied." % self ) # a little dance here as the "path" is still something that only # semi-tracks the exact series of things we are loading, still not # telling us about with_polymorphic() and stuff like that when it's at # the root.. the initial MapperEntity is more accurate for this case. if len(path) == 1: if not orm_util._entity_isa(query_entity.entity_zero, self.parent): return elif not orm_util._entity_isa(path[-1], self.parent): return selectin_path = effective_path path_w_prop = path[self.parent_property] # build up a path indicating the path from the leftmost # entity to the thing we're subquery loading. with_poly_entity = path_w_prop.get( context.attributes, "path_with_polymorphic", None ) if with_poly_entity is not None: effective_entity = inspect(with_poly_entity) else: effective_entity = self.entity loading.PostLoad.callable_for_path( context, selectin_path, self.parent, self.parent_property, self._load_for_path, effective_entity, loadopt, recursion_depth, execution_options, ) def _load_for_path( self, context, path, states, load_only, effective_entity, loadopt, recursion_depth, execution_options, ): if load_only and self.key not in load_only: return query_info = self._query_info if query_info.load_only_child: our_states = collections.defaultdict(list) none_states = [] mapper = self.parent for state, overwrite in states: state_dict = state.dict related_ident = tuple( mapper._get_state_attr_by_column( state, state_dict, lk, passive=attributes.PASSIVE_NO_FETCH, ) for lk in query_info.child_lookup_cols ) # if the loaded parent objects do not have the foreign key # to the related item loaded, then degrade into the joined # version of selectinload if LoaderCallableStatus.PASSIVE_NO_RESULT in related_ident: query_info = self._fallback_query_info break # organize states into lists keyed to particular foreign # key values. if None not in related_ident: our_states[related_ident].append( (state, state_dict, overwrite) ) else: # For FK values that have None, add them to a # separate collection that will be populated separately none_states.append((state, state_dict, overwrite)) # note the above conditional may have changed query_info if not query_info.load_only_child: our_states = [ (state.key[1], state, state.dict, overwrite) for state, overwrite in states ] pk_cols = query_info.pk_cols in_expr = query_info.in_expr if not query_info.load_with_join: # in "omit join" mode, the primary key column and the # "in" expression are in terms of the related entity. So # if the related entity is polymorphic or otherwise aliased, # we need to adapt our "pk_cols" and "in_expr" to that # entity. in non-"omit join" mode, these are against the # parent entity and do not need adaption. if effective_entity.is_aliased_class: pk_cols = [ effective_entity._adapt_element(col) for col in pk_cols ] in_expr = effective_entity._adapt_element(in_expr) bundle_ent = orm_util.Bundle("pk", *pk_cols) bundle_sql = bundle_ent.__clause_element__() entity_sql = effective_entity.__clause_element__() q = Select._create_raw_select( _raw_columns=[bundle_sql, entity_sql], _label_style=LABEL_STYLE_TABLENAME_PLUS_COL, _compile_options=ORMCompileState.default_compile_options, _propagate_attrs={ "compile_state_plugin": "orm", "plugin_subject": effective_entity, }, ) if not query_info.load_with_join: # the Bundle we have in the "omit_join" case is against raw, non # annotated columns, so to ensure the Query knows its primary # entity, we add it explicitly. If we made the Bundle against # annotated columns, we hit a performance issue in this specific # case, which is detailed in issue #4347. q = q.select_from(effective_entity) else: # in the non-omit_join case, the Bundle is against the annotated/ # mapped column of the parent entity, but the #4347 issue does not # occur in this case. q = q.select_from(self._parent_alias).join( getattr(self._parent_alias, self.parent_property.key).of_type( effective_entity ) ) q = q.filter(in_expr.in_(sql.bindparam("primary_keys"))) # a test which exercises what these comments talk about is # test_selectin_relations.py -> test_twolevel_selectin_w_polymorphic # # effective_entity above is given to us in terms of the cached # statement, namely this one: orig_query = context.compile_state.select_statement # the actual statement that was requested is this one: # context_query = context.user_passed_query # # that's not the cached one, however. So while it is of the identical # structure, if it has entities like AliasedInsp, which we get from # aliased() or with_polymorphic(), the AliasedInsp will likely be a # different object identity each time, and will not match up # hashing-wise to the corresponding AliasedInsp that's in the # cached query, meaning it won't match on paths and loader lookups # and loaders like this one will be skipped if it is used in options. # # as it turns out, standard loader options like selectinload(), # lazyload() that have a path need # to come from the cached query so that the AliasedInsp etc. objects # that are in the query line up with the object that's in the path # of the strategy object. however other options like # with_loader_criteria() that doesn't have a path (has a fixed entity) # and needs to have access to the latest closure state in order to # be correct, we need to use the uncached one. # # as of #8399 we let the loader option itself figure out what it # wants to do given cached and uncached version of itself. effective_path = path[self.parent_property] if orig_query is context.user_passed_query: new_options = orig_query._with_options else: cached_options = orig_query._with_options uncached_options = context.user_passed_query._with_options # propagate compile state options from the original query, # updating their "extra_criteria" as necessary. # note this will create a different cache key than # "orig" options if extra_criteria is present, because the copy # of extra_criteria will have different boundparam than that of # the QueryableAttribute in the path new_options = [ orig_opt._adapt_cached_option_to_uncached_option( context, uncached_opt ) for orig_opt, uncached_opt in zip( cached_options, uncached_options ) ] if loadopt and loadopt._extra_criteria: new_options += ( orm_util.LoaderCriteriaOption( effective_entity, loadopt._generate_extra_criteria(context), ), ) if recursion_depth is not None: effective_path = effective_path._truncate_recursive() q = q.options(*new_options) q = q._update_compile_options({"_current_path": effective_path}) if context.populate_existing: q = q.execution_options(populate_existing=True) if self.parent_property.order_by: if not query_info.load_with_join: eager_order_by = self.parent_property.order_by if effective_entity.is_aliased_class: eager_order_by = [ effective_entity._adapt_element(elem) for elem in eager_order_by ] q = q.order_by(*eager_order_by) else: def _setup_outermost_orderby(compile_context): compile_context.eager_order_by += tuple( util.to_list(self.parent_property.order_by) ) q = q._add_context_option( _setup_outermost_orderby, self.parent_property ) if query_info.load_only_child: self._load_via_child( our_states, none_states, query_info, q, context, execution_options, ) else: self._load_via_parent( our_states, query_info, q, context, execution_options ) def _load_via_child( self, our_states, none_states, query_info, q, context, execution_options, ): uselist = self.uselist # this sort is really for the benefit of the unit tests our_keys = sorted(our_states) while our_keys: chunk = our_keys[0 : self._chunksize] our_keys = our_keys[self._chunksize :] data = { k: v for k, v in context.session.execute( q, params={ "primary_keys": [ key[0] if query_info.zero_idx else key for key in chunk ] }, execution_options=execution_options, ).unique() } for key in chunk: # for a real foreign key and no concurrent changes to the # DB while running this method, "key" is always present in # data. However, for primaryjoins without real foreign keys # a non-None primaryjoin condition may still refer to no # related object. related_obj = data.get(key, None) for state, dict_, overwrite in our_states[key]: if not overwrite and self.key in dict_: continue state.get_impl(self.key).set_committed_value( state, dict_, related_obj if not uselist else [related_obj], ) # populate none states with empty value / collection for state, dict_, overwrite in none_states: if not overwrite and self.key in dict_: continue # note it's OK if this is a uselist=True attribute, the empty # collection will be populated state.get_impl(self.key).set_committed_value(state, dict_, None) def _load_via_parent( self, our_states, query_info, q, context, execution_options ): uselist = self.uselist _empty_result = () if uselist else None while our_states: chunk = our_states[0 : self._chunksize] our_states = our_states[self._chunksize :] primary_keys = [ key[0] if query_info.zero_idx else key for key, state, state_dict, overwrite in chunk ] data = collections.defaultdict(list) for k, v in itertools.groupby( context.session.execute( q, params={"primary_keys": primary_keys}, execution_options=execution_options, ).unique(), lambda x: x[0], ): data[k].extend(vv[1] for vv in v) for key, state, state_dict, overwrite in chunk: if not overwrite and self.key in state_dict: continue collection = data.get(key, _empty_result) if not uselist and collection: if len(collection) > 1: util.warn( "Multiple rows returned with " "uselist=False for eagerly-loaded " "attribute '%s' " % self ) state.get_impl(self.key).set_committed_value( state, state_dict, collection[0] ) else: # note that empty tuple set on uselist=False sets the # value to None state.get_impl(self.key).set_committed_value( state, state_dict, collection ) def single_parent_validator(desc, prop): def _do_check(state, value, oldvalue, initiator): if value is not None and initiator.key == prop.key: hasparent = initiator.hasparent(attributes.instance_state(value)) if hasparent and oldvalue is not value: raise sa_exc.InvalidRequestError( "Instance %s is already associated with an instance " "of %s via its %s attribute, and is only allowed a " "single parent." % (orm_util.instance_str(value), state.class_, prop), code="bbf1", ) return value def append(state, value, initiator): return _do_check(state, value, None, initiator) def set_(state, value, oldvalue, initiator): return _do_check(state, value, oldvalue, initiator) event.listen( desc, "append", append, raw=True, retval=True, active_history=True ) event.listen(desc, "set", set_, raw=True, retval=True, active_history=True) sqlalchemy/orm/bulk_persistence.py 0000755 00000215727 15125143220 0013432 0 ustar 00 # orm/bulk_persistence.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors """additional ORM persistence classes related to "bulk" operations, specifically outside of the flush() process. """ from __future__ import annotations from typing import Any from typing import cast from typing import Dict from typing import Iterable from typing import Optional from typing import overload from typing import TYPE_CHECKING from typing import TypeVar from typing import Union from . import attributes from . import context from . import evaluator from . import exc as orm_exc from . import loading from . import persistence from .base import NO_VALUE from .context import AbstractORMCompileState from .context import FromStatement from .context import ORMFromStatementCompileState from .context import QueryContext from .. import exc as sa_exc from .. import util from ..engine import Dialect from ..engine import result as _result from ..sql import coercions from ..sql import dml from ..sql import expression from ..sql import roles from ..sql import select from ..sql import sqltypes from ..sql.base import _entity_namespace_key from ..sql.base import CompileState from ..sql.base import Options from ..sql.dml import DeleteDMLState from ..sql.dml import InsertDMLState from ..sql.dml import UpdateDMLState from ..util import EMPTY_DICT from ..util.typing import Literal if TYPE_CHECKING: from ._typing import DMLStrategyArgument from ._typing import OrmExecuteOptionsParameter from ._typing import SynchronizeSessionArgument from .mapper import Mapper from .session import _BindArguments from .session import ORMExecuteState from .session import Session from .session import SessionTransaction from .state import InstanceState from ..engine import Connection from ..engine import cursor from ..engine.interfaces import _CoreAnyExecuteParams _O = TypeVar("_O", bound=object) @overload def _bulk_insert( mapper: Mapper[_O], mappings: Union[Iterable[InstanceState[_O]], Iterable[Dict[str, Any]]], session_transaction: SessionTransaction, *, isstates: bool, return_defaults: bool, render_nulls: bool, use_orm_insert_stmt: Literal[None] = ..., execution_options: Optional[OrmExecuteOptionsParameter] = ..., ) -> None: ... @overload def _bulk_insert( mapper: Mapper[_O], mappings: Union[Iterable[InstanceState[_O]], Iterable[Dict[str, Any]]], session_transaction: SessionTransaction, *, isstates: bool, return_defaults: bool, render_nulls: bool, use_orm_insert_stmt: Optional[dml.Insert] = ..., execution_options: Optional[OrmExecuteOptionsParameter] = ..., ) -> cursor.CursorResult[Any]: ... def _bulk_insert( mapper: Mapper[_O], mappings: Union[Iterable[InstanceState[_O]], Iterable[Dict[str, Any]]], session_transaction: SessionTransaction, *, isstates: bool, return_defaults: bool, render_nulls: bool, use_orm_insert_stmt: Optional[dml.Insert] = None, execution_options: Optional[OrmExecuteOptionsParameter] = None, ) -> Optional[cursor.CursorResult[Any]]: base_mapper = mapper.base_mapper if session_transaction.session.connection_callable: raise NotImplementedError( "connection_callable / per-instance sharding " "not supported in bulk_insert()" ) if isstates: if TYPE_CHECKING: mappings = cast(Iterable[InstanceState[_O]], mappings) if return_defaults: # list of states allows us to attach .key for return_defaults case states = [(state, state.dict) for state in mappings] mappings = [dict_ for (state, dict_) in states] else: mappings = [state.dict for state in mappings] else: if TYPE_CHECKING: mappings = cast(Iterable[Dict[str, Any]], mappings) if return_defaults: # use dictionaries given, so that newly populated defaults # can be delivered back to the caller (see #11661). This is **not** # compatible with other use cases such as a session-executed # insert() construct, as this will confuse the case of # insert-per-subclass for joined inheritance cases (see # test_bulk_statements.py::BulkDMLReturningJoinedInhTest). # # So in this conditional, we have **only** called # session.bulk_insert_mappings() which does not have this # requirement mappings = list(mappings) else: # for all other cases we need to establish a local dictionary # so that the incoming dictionaries aren't mutated mappings = [dict(m) for m in mappings] _expand_composites(mapper, mappings) connection = session_transaction.connection(base_mapper) return_result: Optional[cursor.CursorResult[Any]] = None mappers_to_run = [ (table, mp) for table, mp in base_mapper._sorted_tables.items() if table in mapper._pks_by_table ] if return_defaults: # not used by new-style bulk inserts, only used for legacy bookkeeping = True elif len(mappers_to_run) > 1: # if we have more than one table, mapper to run where we will be # either horizontally splicing, or copying values between tables, # we need the "bookkeeping" / deterministic returning order bookkeeping = True else: bookkeeping = False for table, super_mapper in mappers_to_run: # find bindparams in the statement. For bulk, we don't really know if # a key in the params applies to a different table since we are # potentially inserting for multiple tables here; looking at the # bindparam() is a lot more direct. in most cases this will # use _generate_cache_key() which is memoized, although in practice # the ultimate statement that's executed is probably not the same # object so that memoization might not matter much. extra_bp_names = ( [ b.key for b in use_orm_insert_stmt._get_embedded_bindparams() if b.key in mappings[0] ] if use_orm_insert_stmt is not None else () ) records = ( ( None, state_dict, params, mapper, connection, value_params, has_all_pks, has_all_defaults, ) for ( state, state_dict, params, mp, conn, value_params, has_all_pks, has_all_defaults, ) in persistence._collect_insert_commands( table, ((None, mapping, mapper, connection) for mapping in mappings), bulk=True, return_defaults=bookkeeping, render_nulls=render_nulls, include_bulk_keys=extra_bp_names, ) ) result = persistence._emit_insert_statements( base_mapper, None, super_mapper, table, records, bookkeeping=bookkeeping, use_orm_insert_stmt=use_orm_insert_stmt, execution_options=execution_options, ) if use_orm_insert_stmt is not None: if not use_orm_insert_stmt._returning or return_result is None: return_result = result elif result.returns_rows: assert bookkeeping return_result = return_result.splice_horizontally(result) if return_defaults and isstates: identity_cls = mapper._identity_class identity_props = [p.key for p in mapper._identity_key_props] for state, dict_ in states: state.key = ( identity_cls, tuple([dict_[key] for key in identity_props]), None, ) if use_orm_insert_stmt is not None: assert return_result is not None return return_result @overload def _bulk_update( mapper: Mapper[Any], mappings: Union[Iterable[InstanceState[_O]], Iterable[Dict[str, Any]]], session_transaction: SessionTransaction, *, isstates: bool, update_changed_only: bool, use_orm_update_stmt: Literal[None] = ..., enable_check_rowcount: bool = True, ) -> None: ... @overload def _bulk_update( mapper: Mapper[Any], mappings: Union[Iterable[InstanceState[_O]], Iterable[Dict[str, Any]]], session_transaction: SessionTransaction, *, isstates: bool, update_changed_only: bool, use_orm_update_stmt: Optional[dml.Update] = ..., enable_check_rowcount: bool = True, ) -> _result.Result[Any]: ... def _bulk_update( mapper: Mapper[Any], mappings: Union[Iterable[InstanceState[_O]], Iterable[Dict[str, Any]]], session_transaction: SessionTransaction, *, isstates: bool, update_changed_only: bool, use_orm_update_stmt: Optional[dml.Update] = None, enable_check_rowcount: bool = True, ) -> Optional[_result.Result[Any]]: base_mapper = mapper.base_mapper search_keys = mapper._primary_key_propkeys if mapper._version_id_prop: search_keys = {mapper._version_id_prop.key}.union(search_keys) def _changed_dict(mapper, state): return { k: v for k, v in state.dict.items() if k in state.committed_state or k in search_keys } if isstates: if update_changed_only: mappings = [_changed_dict(mapper, state) for state in mappings] else: mappings = [state.dict for state in mappings] else: mappings = [dict(m) for m in mappings] _expand_composites(mapper, mappings) if session_transaction.session.connection_callable: raise NotImplementedError( "connection_callable / per-instance sharding " "not supported in bulk_update()" ) connection = session_transaction.connection(base_mapper) # find bindparams in the statement. see _bulk_insert for similar # notes for the insert case extra_bp_names = ( [ b.key for b in use_orm_update_stmt._get_embedded_bindparams() if b.key in mappings[0] ] if use_orm_update_stmt is not None else () ) for table, super_mapper in base_mapper._sorted_tables.items(): if not mapper.isa(super_mapper) or table not in mapper._pks_by_table: continue records = persistence._collect_update_commands( None, table, ( ( None, mapping, mapper, connection, ( mapping[mapper._version_id_prop.key] if mapper._version_id_prop else None ), ) for mapping in mappings ), bulk=True, use_orm_update_stmt=use_orm_update_stmt, include_bulk_keys=extra_bp_names, ) persistence._emit_update_statements( base_mapper, None, super_mapper, table, records, bookkeeping=False, use_orm_update_stmt=use_orm_update_stmt, enable_check_rowcount=enable_check_rowcount, ) if use_orm_update_stmt is not None: return _result.null_result() def _expand_composites(mapper, mappings): composite_attrs = mapper.composites if not composite_attrs: return composite_keys = set(composite_attrs.keys()) populators = { key: composite_attrs[key]._populate_composite_bulk_save_mappings_fn() for key in composite_keys } for mapping in mappings: for key in composite_keys.intersection(mapping): populators[key](mapping) class ORMDMLState(AbstractORMCompileState): is_dml_returning = True from_statement_ctx: Optional[ORMFromStatementCompileState] = None @classmethod def _get_orm_crud_kv_pairs( cls, mapper, statement, kv_iterator, needs_to_be_cacheable ): core_get_crud_kv_pairs = UpdateDMLState._get_crud_kv_pairs for k, v in kv_iterator: k = coercions.expect(roles.DMLColumnRole, k) if isinstance(k, str): desc = _entity_namespace_key(mapper, k, default=NO_VALUE) if desc is NO_VALUE: yield ( coercions.expect(roles.DMLColumnRole, k), ( coercions.expect( roles.ExpressionElementRole, v, type_=sqltypes.NullType(), is_crud=True, ) if needs_to_be_cacheable else v ), ) else: yield from core_get_crud_kv_pairs( statement, desc._bulk_update_tuples(v), needs_to_be_cacheable, ) elif "entity_namespace" in k._annotations: k_anno = k._annotations attr = _entity_namespace_key( k_anno["entity_namespace"], k_anno["proxy_key"] ) yield from core_get_crud_kv_pairs( statement, attr._bulk_update_tuples(v), needs_to_be_cacheable, ) else: yield ( k, ( v if not needs_to_be_cacheable else coercions.expect( roles.ExpressionElementRole, v, type_=sqltypes.NullType(), is_crud=True, ) ), ) @classmethod def _get_multi_crud_kv_pairs(cls, statement, kv_iterator): plugin_subject = statement._propagate_attrs["plugin_subject"] if not plugin_subject or not plugin_subject.mapper: return UpdateDMLState._get_multi_crud_kv_pairs( statement, kv_iterator ) return [ dict( cls._get_orm_crud_kv_pairs( plugin_subject.mapper, statement, value_dict.items(), False ) ) for value_dict in kv_iterator ] @classmethod def _get_crud_kv_pairs(cls, statement, kv_iterator, needs_to_be_cacheable): assert ( needs_to_be_cacheable ), "no test coverage for needs_to_be_cacheable=False" plugin_subject = statement._propagate_attrs["plugin_subject"] if not plugin_subject or not plugin_subject.mapper: return UpdateDMLState._get_crud_kv_pairs( statement, kv_iterator, needs_to_be_cacheable ) return list( cls._get_orm_crud_kv_pairs( plugin_subject.mapper, statement, kv_iterator, needs_to_be_cacheable, ) ) @classmethod def get_entity_description(cls, statement): ext_info = statement.table._annotations["parententity"] mapper = ext_info.mapper if ext_info.is_aliased_class: _label_name = ext_info.name else: _label_name = mapper.class_.__name__ return { "name": _label_name, "type": mapper.class_, "expr": ext_info.entity, "entity": ext_info.entity, "table": mapper.local_table, } @classmethod def get_returning_column_descriptions(cls, statement): def _ent_for_col(c): return c._annotations.get("parententity", None) def _attr_for_col(c, ent): if ent is None: return c proxy_key = c._annotations.get("proxy_key", None) if not proxy_key: return c else: return getattr(ent.entity, proxy_key, c) return [ { "name": c.key, "type": c.type, "expr": _attr_for_col(c, ent), "aliased": ent.is_aliased_class, "entity": ent.entity, } for c, ent in [ (c, _ent_for_col(c)) for c in statement._all_selected_columns ] ] def _setup_orm_returning( self, compiler, orm_level_statement, dml_level_statement, dml_mapper, *, use_supplemental_cols=True, ): """establish ORM column handlers for an INSERT, UPDATE, or DELETE which uses explicit returning(). called within compilation level create_for_statement. The _return_orm_returning() method then receives the Result after the statement was executed, and applies ORM loading to the state that we first established here. """ if orm_level_statement._returning: fs = FromStatement( orm_level_statement._returning, dml_level_statement, _adapt_on_names=False, ) fs = fs.execution_options(**orm_level_statement._execution_options) fs = fs.options(*orm_level_statement._with_options) self.select_statement = fs self.from_statement_ctx = fsc = ( ORMFromStatementCompileState.create_for_statement(fs, compiler) ) fsc.setup_dml_returning_compile_state(dml_mapper) dml_level_statement = dml_level_statement._generate() dml_level_statement._returning = () cols_to_return = [c for c in fsc.primary_columns if c is not None] # since we are splicing result sets together, make sure there # are columns of some kind returned in each result set if not cols_to_return: cols_to_return.extend(dml_mapper.primary_key) if use_supplemental_cols: dml_level_statement = dml_level_statement.return_defaults( # this is a little weird looking, but by passing # primary key as the main list of cols, this tells # return_defaults to omit server-default cols (and # actually all cols, due to some weird thing we should # clean up in crud.py). # Since we have cols_to_return, just return what we asked # for (plus primary key, which ORM persistence needs since # we likely set bookkeeping=True here, which is another # whole thing...). We dont want to clutter the # statement up with lots of other cols the user didn't # ask for. see #9685 *dml_mapper.primary_key, supplemental_cols=cols_to_return, ) else: dml_level_statement = dml_level_statement.returning( *cols_to_return ) return dml_level_statement @classmethod def _return_orm_returning( cls, session, statement, params, execution_options, bind_arguments, result, ): execution_context = result.context compile_state = execution_context.compiled.compile_state if ( compile_state.from_statement_ctx and not compile_state.from_statement_ctx.compile_options._is_star ): load_options = execution_options.get( "_sa_orm_load_options", QueryContext.default_load_options ) querycontext = QueryContext( compile_state.from_statement_ctx, compile_state.select_statement, statement, params, session, load_options, execution_options, bind_arguments, ) return loading.instances(result, querycontext) else: return result class BulkUDCompileState(ORMDMLState): class default_update_options(Options): _dml_strategy: DMLStrategyArgument = "auto" _synchronize_session: SynchronizeSessionArgument = "auto" _can_use_returning: bool = False _is_delete_using: bool = False _is_update_from: bool = False _autoflush: bool = True _subject_mapper: Optional[Mapper[Any]] = None _resolved_values = EMPTY_DICT _eval_condition = None _matched_rows = None _identity_token = None _populate_existing: bool = False @classmethod def can_use_returning( cls, dialect: Dialect, mapper: Mapper[Any], *, is_multitable: bool = False, is_update_from: bool = False, is_delete_using: bool = False, is_executemany: bool = False, ) -> bool: raise NotImplementedError() @classmethod def orm_pre_session_exec( cls, session, statement, params, execution_options, bind_arguments, is_pre_event, ): ( update_options, execution_options, ) = BulkUDCompileState.default_update_options.from_execution_options( "_sa_orm_update_options", { "synchronize_session", "autoflush", "populate_existing", "identity_token", "is_delete_using", "is_update_from", "dml_strategy", }, execution_options, statement._execution_options, ) bind_arguments["clause"] = statement try: plugin_subject = statement._propagate_attrs["plugin_subject"] except KeyError: assert False, "statement had 'orm' plugin but no plugin_subject" else: if plugin_subject: bind_arguments["mapper"] = plugin_subject.mapper update_options += {"_subject_mapper": plugin_subject.mapper} if "parententity" not in statement.table._annotations: update_options += {"_dml_strategy": "core_only"} elif not isinstance(params, list): if update_options._dml_strategy == "auto": update_options += {"_dml_strategy": "orm"} elif update_options._dml_strategy == "bulk": raise sa_exc.InvalidRequestError( 'Can\'t use "bulk" ORM insert strategy without ' "passing separate parameters" ) else: if update_options._dml_strategy == "auto": update_options += {"_dml_strategy": "bulk"} sync = update_options._synchronize_session if sync is not None: if sync not in ("auto", "evaluate", "fetch", False): raise sa_exc.ArgumentError( "Valid strategies for session synchronization " "are 'auto', 'evaluate', 'fetch', False" ) if update_options._dml_strategy == "bulk" and sync == "fetch": raise sa_exc.InvalidRequestError( "The 'fetch' synchronization strategy is not available " "for 'bulk' ORM updates (i.e. multiple parameter sets)" ) if not is_pre_event: if update_options._autoflush: session._autoflush() if update_options._dml_strategy == "orm": if update_options._synchronize_session == "auto": update_options = cls._do_pre_synchronize_auto( session, statement, params, execution_options, bind_arguments, update_options, ) elif update_options._synchronize_session == "evaluate": update_options = cls._do_pre_synchronize_evaluate( session, statement, params, execution_options, bind_arguments, update_options, ) elif update_options._synchronize_session == "fetch": update_options = cls._do_pre_synchronize_fetch( session, statement, params, execution_options, bind_arguments, update_options, ) elif update_options._dml_strategy == "bulk": if update_options._synchronize_session == "auto": update_options += {"_synchronize_session": "evaluate"} # indicators from the "pre exec" step that are then # added to the DML statement, which will also be part of the cache # key. The compile level create_for_statement() method will then # consume these at compiler time. statement = statement._annotate( { "synchronize_session": update_options._synchronize_session, "is_delete_using": update_options._is_delete_using, "is_update_from": update_options._is_update_from, "dml_strategy": update_options._dml_strategy, "can_use_returning": update_options._can_use_returning, } ) return ( statement, util.immutabledict(execution_options).union( {"_sa_orm_update_options": update_options} ), ) @classmethod def orm_setup_cursor_result( cls, session, statement, params, execution_options, bind_arguments, result, ): # this stage of the execution is called after the # do_orm_execute event hook. meaning for an extension like # horizontal sharding, this step happens *within* the horizontal # sharding event handler which calls session.execute() re-entrantly # and will occur for each backend individually. # the sharding extension then returns its own merged result from the # individual ones we return here. update_options = execution_options["_sa_orm_update_options"] if update_options._dml_strategy == "orm": if update_options._synchronize_session == "evaluate": cls._do_post_synchronize_evaluate( session, statement, result, update_options ) elif update_options._synchronize_session == "fetch": cls._do_post_synchronize_fetch( session, statement, result, update_options ) elif update_options._dml_strategy == "bulk": if update_options._synchronize_session == "evaluate": cls._do_post_synchronize_bulk_evaluate( session, params, result, update_options ) return result return cls._return_orm_returning( session, statement, params, execution_options, bind_arguments, result, ) @classmethod def _adjust_for_extra_criteria(cls, global_attributes, ext_info): """Apply extra criteria filtering. For all distinct single-table-inheritance mappers represented in the table being updated or deleted, produce additional WHERE criteria such that only the appropriate subtypes are selected from the total results. Additionally, add WHERE criteria originating from LoaderCriteriaOptions collected from the statement. """ return_crit = () adapter = ext_info._adapter if ext_info.is_aliased_class else None if ( "additional_entity_criteria", ext_info.mapper, ) in global_attributes: return_crit += tuple( ae._resolve_where_criteria(ext_info) for ae in global_attributes[ ("additional_entity_criteria", ext_info.mapper) ] if ae.include_aliases or ae.entity is ext_info ) if ext_info.mapper._single_table_criterion is not None: return_crit += (ext_info.mapper._single_table_criterion,) if adapter: return_crit = tuple(adapter.traverse(crit) for crit in return_crit) return return_crit @classmethod def _interpret_returning_rows(cls, result, mapper, rows): """return rows that indicate PK cols in mapper.primary_key position for RETURNING rows. Prior to 2.0.36, this method seemed to be written for some kind of inheritance scenario but the scenario was unused for actual joined inheritance, and the function instead seemed to perform some kind of partial translation that would remove non-PK cols if the PK cols happened to be first in the row, but not otherwise. The joined inheritance walk feature here seems to have never been used as it was always skipped by the "local_table" check. As of 2.0.36 the function strips away non-PK cols and provides the PK cols for the table in mapper PK order. """ try: if mapper.local_table is not mapper.base_mapper.local_table: # TODO: dive more into how a local table PK is used for fetch # sync, not clear if this is correct as it depends on the # downstream routine to fetch rows using # local_table.primary_key order pk_keys = result._tuple_getter(mapper.local_table.primary_key) else: pk_keys = result._tuple_getter(mapper.primary_key) except KeyError: # can't use these rows, they don't have PK cols in them # this is an unusual case where the user would have used # .return_defaults() return [] return [pk_keys(row) for row in rows] @classmethod def _get_matched_objects_on_criteria(cls, update_options, states): mapper = update_options._subject_mapper eval_condition = update_options._eval_condition raw_data = [ (state.obj(), state, state.dict) for state in states if state.mapper.isa(mapper) and not state.expired ] identity_token = update_options._identity_token if identity_token is not None: raw_data = [ (obj, state, dict_) for obj, state, dict_ in raw_data if state.identity_token == identity_token ] result = [] for obj, state, dict_ in raw_data: evaled_condition = eval_condition(obj) # caution: don't use "in ()" or == here, _EXPIRE_OBJECT # evaluates as True for all comparisons if ( evaled_condition is True or evaled_condition is evaluator._EXPIRED_OBJECT ): result.append( ( obj, state, dict_, evaled_condition is evaluator._EXPIRED_OBJECT, ) ) return result @classmethod def _eval_condition_from_statement(cls, update_options, statement): mapper = update_options._subject_mapper target_cls = mapper.class_ evaluator_compiler = evaluator._EvaluatorCompiler(target_cls) crit = () if statement._where_criteria: crit += statement._where_criteria global_attributes = {} for opt in statement._with_options: if opt._is_criteria_option: opt.get_global_criteria(global_attributes) if global_attributes: crit += cls._adjust_for_extra_criteria(global_attributes, mapper) if crit: eval_condition = evaluator_compiler.process(*crit) else: # workaround for mypy https://github.com/python/mypy/issues/14027 def _eval_condition(obj): return True eval_condition = _eval_condition return eval_condition @classmethod def _do_pre_synchronize_auto( cls, session, statement, params, execution_options, bind_arguments, update_options, ): """setup auto sync strategy "auto" checks if we can use "evaluate" first, then falls back to "fetch" evaluate is vastly more efficient for the common case where session is empty, only has a few objects, and the UPDATE statement can potentially match thousands/millions of rows. OTOH more complex criteria that fails to work with "evaluate" we would hope usually correlates with fewer net rows. """ try: eval_condition = cls._eval_condition_from_statement( update_options, statement ) except evaluator.UnevaluatableError: pass else: return update_options + { "_eval_condition": eval_condition, "_synchronize_session": "evaluate", } update_options += {"_synchronize_session": "fetch"} return cls._do_pre_synchronize_fetch( session, statement, params, execution_options, bind_arguments, update_options, ) @classmethod def _do_pre_synchronize_evaluate( cls, session, statement, params, execution_options, bind_arguments, update_options, ): try: eval_condition = cls._eval_condition_from_statement( update_options, statement ) except evaluator.UnevaluatableError as err: raise sa_exc.InvalidRequestError( 'Could not evaluate current criteria in Python: "%s". ' "Specify 'fetch' or False for the " "synchronize_session execution option." % err ) from err return update_options + { "_eval_condition": eval_condition, } @classmethod def _get_resolved_values(cls, mapper, statement): if statement._multi_values: return [] elif statement._ordered_values: return list(statement._ordered_values) elif statement._values: return list(statement._values.items()) else: return [] @classmethod def _resolved_keys_as_propnames(cls, mapper, resolved_values): values = [] for k, v in resolved_values: if mapper and isinstance(k, expression.ColumnElement): try: attr = mapper._columntoproperty[k] except orm_exc.UnmappedColumnError: pass else: values.append((attr.key, v)) else: raise sa_exc.InvalidRequestError( "Attribute name not found, can't be " "synchronized back to objects: %r" % k ) return values @classmethod def _do_pre_synchronize_fetch( cls, session, statement, params, execution_options, bind_arguments, update_options, ): mapper = update_options._subject_mapper select_stmt = ( select(*(mapper.primary_key + (mapper.select_identity_token,))) .select_from(mapper) .options(*statement._with_options) ) select_stmt._where_criteria = statement._where_criteria # conditionally run the SELECT statement for pre-fetch, testing the # "bind" for if we can use RETURNING or not using the do_orm_execute # event. If RETURNING is available, the do_orm_execute event # will cancel the SELECT from being actually run. # # The way this is organized seems strange, why don't we just # call can_use_returning() before invoking the statement and get # answer?, why does this go through the whole execute phase using an # event? Answer: because we are integrating with extensions such # as the horizontal sharding extention that "multiplexes" an individual # statement run through multiple engines, and it uses # do_orm_execute() to do that. can_use_returning = None def skip_for_returning(orm_context: ORMExecuteState) -> Any: bind = orm_context.session.get_bind(**orm_context.bind_arguments) nonlocal can_use_returning per_bind_result = cls.can_use_returning( bind.dialect, mapper, is_update_from=update_options._is_update_from, is_delete_using=update_options._is_delete_using, is_executemany=orm_context.is_executemany, ) if can_use_returning is not None: if can_use_returning != per_bind_result: raise sa_exc.InvalidRequestError( "For synchronize_session='fetch', can't mix multiple " "backends where some support RETURNING and others " "don't" ) elif orm_context.is_executemany and not per_bind_result: raise sa_exc.InvalidRequestError( "For synchronize_session='fetch', can't use multiple " "parameter sets in ORM mode, which this backend does not " "support with RETURNING" ) else: can_use_returning = per_bind_result if per_bind_result: return _result.null_result() else: return None result = session.execute( select_stmt, params, execution_options=execution_options, bind_arguments=bind_arguments, _add_event=skip_for_returning, ) matched_rows = result.fetchall() return update_options + { "_matched_rows": matched_rows, "_can_use_returning": can_use_returning, } @CompileState.plugin_for("orm", "insert") class BulkORMInsert(ORMDMLState, InsertDMLState): class default_insert_options(Options): _dml_strategy: DMLStrategyArgument = "auto" _render_nulls: bool = False _return_defaults: bool = False _subject_mapper: Optional[Mapper[Any]] = None _autoflush: bool = True _populate_existing: bool = False select_statement: Optional[FromStatement] = None @classmethod def orm_pre_session_exec( cls, session, statement, params, execution_options, bind_arguments, is_pre_event, ): ( insert_options, execution_options, ) = BulkORMInsert.default_insert_options.from_execution_options( "_sa_orm_insert_options", {"dml_strategy", "autoflush", "populate_existing", "render_nulls"}, execution_options, statement._execution_options, ) bind_arguments["clause"] = statement try: plugin_subject = statement._propagate_attrs["plugin_subject"] except KeyError: assert False, "statement had 'orm' plugin but no plugin_subject" else: if plugin_subject: bind_arguments["mapper"] = plugin_subject.mapper insert_options += {"_subject_mapper": plugin_subject.mapper} if not params: if insert_options._dml_strategy == "auto": insert_options += {"_dml_strategy": "orm"} elif insert_options._dml_strategy == "bulk": raise sa_exc.InvalidRequestError( 'Can\'t use "bulk" ORM insert strategy without ' "passing separate parameters" ) else: if insert_options._dml_strategy == "auto": insert_options += {"_dml_strategy": "bulk"} if insert_options._dml_strategy != "raw": # for ORM object loading, like ORMContext, we have to disable # result set adapt_to_context, because we will be generating a # new statement with specific columns that's cached inside of # an ORMFromStatementCompileState, which we will re-use for # each result. if not execution_options: execution_options = context._orm_load_exec_options else: execution_options = execution_options.union( context._orm_load_exec_options ) if not is_pre_event and insert_options._autoflush: session._autoflush() statement = statement._annotate( {"dml_strategy": insert_options._dml_strategy} ) return ( statement, util.immutabledict(execution_options).union( {"_sa_orm_insert_options": insert_options} ), ) @classmethod def orm_execute_statement( cls, session: Session, statement: dml.Insert, params: _CoreAnyExecuteParams, execution_options: OrmExecuteOptionsParameter, bind_arguments: _BindArguments, conn: Connection, ) -> _result.Result: insert_options = execution_options.get( "_sa_orm_insert_options", cls.default_insert_options ) if insert_options._dml_strategy not in ( "raw", "bulk", "orm", "auto", ): raise sa_exc.ArgumentError( "Valid strategies for ORM insert strategy " "are 'raw', 'orm', 'bulk', 'auto" ) result: _result.Result[Any] if insert_options._dml_strategy == "raw": result = conn.execute( statement, params or {}, execution_options=execution_options ) return result if insert_options._dml_strategy == "bulk": mapper = insert_options._subject_mapper if ( statement._post_values_clause is not None and mapper._multiple_persistence_tables ): raise sa_exc.InvalidRequestError( "bulk INSERT with a 'post values' clause " "(typically upsert) not supported for multi-table " f"mapper {mapper}" ) assert mapper is not None assert session._transaction is not None result = _bulk_insert( mapper, cast( "Iterable[Dict[str, Any]]", [params] if isinstance(params, dict) else params, ), session._transaction, isstates=False, return_defaults=insert_options._return_defaults, render_nulls=insert_options._render_nulls, use_orm_insert_stmt=statement, execution_options=execution_options, ) elif insert_options._dml_strategy == "orm": result = conn.execute( statement, params or {}, execution_options=execution_options ) else: raise AssertionError() if not bool(statement._returning): return result if insert_options._populate_existing: load_options = execution_options.get( "_sa_orm_load_options", QueryContext.default_load_options ) load_options += {"_populate_existing": True} execution_options = execution_options.union( {"_sa_orm_load_options": load_options} ) return cls._return_orm_returning( session, statement, params, execution_options, bind_arguments, result, ) @classmethod def create_for_statement(cls, statement, compiler, **kw) -> BulkORMInsert: self = cast( BulkORMInsert, super().create_for_statement(statement, compiler, **kw), ) if compiler is not None: toplevel = not compiler.stack else: toplevel = True if not toplevel: return self mapper = statement._propagate_attrs["plugin_subject"] dml_strategy = statement._annotations.get("dml_strategy", "raw") if dml_strategy == "bulk": self._setup_for_bulk_insert(compiler) elif dml_strategy == "orm": self._setup_for_orm_insert(compiler, mapper) return self @classmethod def _resolved_keys_as_col_keys(cls, mapper, resolved_value_dict): return { col.key if col is not None else k: v for col, k, v in ( (mapper.c.get(k), k, v) for k, v in resolved_value_dict.items() ) } def _setup_for_orm_insert(self, compiler, mapper): statement = orm_level_statement = cast(dml.Insert, self.statement) statement = self._setup_orm_returning( compiler, orm_level_statement, statement, dml_mapper=mapper, use_supplemental_cols=False, ) self.statement = statement def _setup_for_bulk_insert(self, compiler): """establish an INSERT statement within the context of bulk insert. This method will be within the "conn.execute()" call that is invoked by persistence._emit_insert_statement(). """ statement = orm_level_statement = cast(dml.Insert, self.statement) an = statement._annotations emit_insert_table, emit_insert_mapper = ( an["_emit_insert_table"], an["_emit_insert_mapper"], ) statement = statement._clone() statement.table = emit_insert_table if self._dict_parameters: self._dict_parameters = { col: val for col, val in self._dict_parameters.items() if col.table is emit_insert_table } statement = self._setup_orm_returning( compiler, orm_level_statement, statement, dml_mapper=emit_insert_mapper, use_supplemental_cols=True, ) if ( self.from_statement_ctx is not None and self.from_statement_ctx.compile_options._is_star ): raise sa_exc.CompileError( "Can't use RETURNING * with bulk ORM INSERT. " "Please use a different INSERT form, such as INSERT..VALUES " "or INSERT with a Core Connection" ) self.statement = statement @CompileState.plugin_for("orm", "update") class BulkORMUpdate(BulkUDCompileState, UpdateDMLState): @classmethod def create_for_statement(cls, statement, compiler, **kw): self = cls.__new__(cls) dml_strategy = statement._annotations.get( "dml_strategy", "unspecified" ) toplevel = not compiler.stack if toplevel and dml_strategy == "bulk": self._setup_for_bulk_update(statement, compiler) elif ( dml_strategy == "core_only" or dml_strategy == "unspecified" and "parententity" not in statement.table._annotations ): UpdateDMLState.__init__(self, statement, compiler, **kw) elif not toplevel or dml_strategy in ("orm", "unspecified"): self._setup_for_orm_update(statement, compiler) return self def _setup_for_orm_update(self, statement, compiler, **kw): orm_level_statement = statement toplevel = not compiler.stack ext_info = statement.table._annotations["parententity"] self.mapper = mapper = ext_info.mapper self._resolved_values = self._get_resolved_values(mapper, statement) self._init_global_attributes( statement, compiler, toplevel=toplevel, process_criteria_for_toplevel=toplevel, ) if statement._values: self._resolved_values = dict(self._resolved_values) new_stmt = statement._clone() if new_stmt.table._annotations["parententity"] is mapper: new_stmt.table = mapper.local_table # note if the statement has _multi_values, these # are passed through to the new statement, which will then raise # InvalidRequestError because UPDATE doesn't support multi_values # right now. if statement._ordered_values: new_stmt._ordered_values = self._resolved_values elif statement._values: new_stmt._values = self._resolved_values new_crit = self._adjust_for_extra_criteria( self.global_attributes, mapper ) if new_crit: new_stmt = new_stmt.where(*new_crit) # if we are against a lambda statement we might not be the # topmost object that received per-execute annotations # do this first as we need to determine if there is # UPDATE..FROM UpdateDMLState.__init__(self, new_stmt, compiler, **kw) use_supplemental_cols = False if not toplevel: synchronize_session = None else: synchronize_session = compiler._annotations.get( "synchronize_session", None ) can_use_returning = compiler._annotations.get( "can_use_returning", None ) if can_use_returning is not False: # even though pre_exec has determined basic # can_use_returning for the dialect, if we are to use # RETURNING we need to run can_use_returning() at this level # unconditionally because is_delete_using was not known # at the pre_exec level can_use_returning = ( synchronize_session == "fetch" and self.can_use_returning( compiler.dialect, mapper, is_multitable=self.is_multitable ) ) if synchronize_session == "fetch" and can_use_returning: use_supplemental_cols = True # NOTE: we might want to RETURNING the actual columns to be # synchronized also. however this is complicated and difficult # to align against the behavior of "evaluate". Additionally, # in a large number (if not the majority) of cases, we have the # "evaluate" answer, usually a fixed value, in memory already and # there's no need to re-fetch the same value # over and over again. so perhaps if it could be RETURNING just # the elements that were based on a SQL expression and not # a constant. For now it doesn't quite seem worth it new_stmt = new_stmt.return_defaults(*new_stmt.table.primary_key) if toplevel: new_stmt = self._setup_orm_returning( compiler, orm_level_statement, new_stmt, dml_mapper=mapper, use_supplemental_cols=use_supplemental_cols, ) self.statement = new_stmt def _setup_for_bulk_update(self, statement, compiler, **kw): """establish an UPDATE statement within the context of bulk insert. This method will be within the "conn.execute()" call that is invoked by persistence._emit_update_statement(). """ statement = cast(dml.Update, statement) an = statement._annotations emit_update_table, _ = ( an["_emit_update_table"], an["_emit_update_mapper"], ) statement = statement._clone() statement.table = emit_update_table UpdateDMLState.__init__(self, statement, compiler, **kw) if self._ordered_values: raise sa_exc.InvalidRequestError( "bulk ORM UPDATE does not support ordered_values() for " "custom UPDATE statements with bulk parameter sets. Use a " "non-bulk UPDATE statement or use values()." ) if self._dict_parameters: self._dict_parameters = { col: val for col, val in self._dict_parameters.items() if col.table is emit_update_table } self.statement = statement @classmethod def orm_execute_statement( cls, session: Session, statement: dml.Update, params: _CoreAnyExecuteParams, execution_options: OrmExecuteOptionsParameter, bind_arguments: _BindArguments, conn: Connection, ) -> _result.Result: update_options = execution_options.get( "_sa_orm_update_options", cls.default_update_options ) if update_options._populate_existing: load_options = execution_options.get( "_sa_orm_load_options", QueryContext.default_load_options ) load_options += {"_populate_existing": True} execution_options = execution_options.union( {"_sa_orm_load_options": load_options} ) if update_options._dml_strategy not in ( "orm", "auto", "bulk", "core_only", ): raise sa_exc.ArgumentError( "Valid strategies for ORM UPDATE strategy " "are 'orm', 'auto', 'bulk', 'core_only'" ) result: _result.Result[Any] if update_options._dml_strategy == "bulk": enable_check_rowcount = not statement._where_criteria assert update_options._synchronize_session != "fetch" if ( statement._where_criteria and update_options._synchronize_session == "evaluate" ): raise sa_exc.InvalidRequestError( "bulk synchronize of persistent objects not supported " "when using bulk update with additional WHERE " "criteria right now. add synchronize_session=None " "execution option to bypass synchronize of persistent " "objects." ) mapper = update_options._subject_mapper assert mapper is not None assert session._transaction is not None result = _bulk_update( mapper, cast( "Iterable[Dict[str, Any]]", [params] if isinstance(params, dict) else params, ), session._transaction, isstates=False, update_changed_only=False, use_orm_update_stmt=statement, enable_check_rowcount=enable_check_rowcount, ) return cls.orm_setup_cursor_result( session, statement, params, execution_options, bind_arguments, result, ) else: return super().orm_execute_statement( session, statement, params, execution_options, bind_arguments, conn, ) @classmethod def can_use_returning( cls, dialect: Dialect, mapper: Mapper[Any], *, is_multitable: bool = False, is_update_from: bool = False, is_delete_using: bool = False, is_executemany: bool = False, ) -> bool: # normal answer for "should we use RETURNING" at all. normal_answer = ( dialect.update_returning and mapper.local_table.implicit_returning ) if not normal_answer: return False if is_executemany: return dialect.update_executemany_returning # these workarounds are currently hypothetical for UPDATE, # unlike DELETE where they impact MariaDB if is_update_from: return dialect.update_returning_multifrom elif is_multitable and not dialect.update_returning_multifrom: raise sa_exc.CompileError( f'Dialect "{dialect.name}" does not support RETURNING ' "with UPDATE..FROM; for synchronize_session='fetch', " "please add the additional execution option " "'is_update_from=True' to the statement to indicate that " "a separate SELECT should be used for this backend." ) return True @classmethod def _do_post_synchronize_bulk_evaluate( cls, session, params, result, update_options ): if not params: return mapper = update_options._subject_mapper pk_keys = [prop.key for prop in mapper._identity_key_props] identity_map = session.identity_map for param in params: identity_key = mapper.identity_key_from_primary_key( (param[key] for key in pk_keys), update_options._identity_token, ) state = identity_map.fast_get_state(identity_key) if not state: continue evaluated_keys = set(param).difference(pk_keys) dict_ = state.dict # only evaluate unmodified attributes to_evaluate = state.unmodified.intersection(evaluated_keys) for key in to_evaluate: if key in dict_: dict_[key] = param[key] state.manager.dispatch.refresh(state, None, to_evaluate) state._commit(dict_, list(to_evaluate)) # attributes that were formerly modified instead get expired. # this only gets hit if the session had pending changes # and autoflush were set to False. to_expire = evaluated_keys.intersection(dict_).difference( to_evaluate ) if to_expire: state._expire_attributes(dict_, to_expire) @classmethod def _do_post_synchronize_evaluate( cls, session, statement, result, update_options ): matched_objects = cls._get_matched_objects_on_criteria( update_options, session.identity_map.all_states(), ) cls._apply_update_set_values_to_objects( session, update_options, statement, result.context.compiled_parameters[0], [(obj, state, dict_) for obj, state, dict_, _ in matched_objects], result.prefetch_cols(), result.postfetch_cols(), ) @classmethod def _do_post_synchronize_fetch( cls, session, statement, result, update_options ): target_mapper = update_options._subject_mapper returned_defaults_rows = result.returned_defaults_rows if returned_defaults_rows: pk_rows = cls._interpret_returning_rows( result, target_mapper, returned_defaults_rows ) matched_rows = [ tuple(row) + (update_options._identity_token,) for row in pk_rows ] else: matched_rows = update_options._matched_rows objs = [ session.identity_map[identity_key] for identity_key in [ target_mapper.identity_key_from_primary_key( list(primary_key), identity_token=identity_token, ) for primary_key, identity_token in [ (row[0:-1], row[-1]) for row in matched_rows ] if update_options._identity_token is None or identity_token == update_options._identity_token ] if identity_key in session.identity_map ] if not objs: return cls._apply_update_set_values_to_objects( session, update_options, statement, result.context.compiled_parameters[0], [ ( obj, attributes.instance_state(obj), attributes.instance_dict(obj), ) for obj in objs ], result.prefetch_cols(), result.postfetch_cols(), ) @classmethod def _apply_update_set_values_to_objects( cls, session, update_options, statement, effective_params, matched_objects, prefetch_cols, postfetch_cols, ): """apply values to objects derived from an update statement, e.g. UPDATE..SET <values> """ mapper = update_options._subject_mapper target_cls = mapper.class_ evaluator_compiler = evaluator._EvaluatorCompiler(target_cls) resolved_values = cls._get_resolved_values(mapper, statement) resolved_keys_as_propnames = cls._resolved_keys_as_propnames( mapper, resolved_values ) value_evaluators = {} for key, value in resolved_keys_as_propnames: try: _evaluator = evaluator_compiler.process( coercions.expect(roles.ExpressionElementRole, value) ) except evaluator.UnevaluatableError: pass else: value_evaluators[key] = _evaluator evaluated_keys = list(value_evaluators.keys()) attrib = {k for k, v in resolved_keys_as_propnames} states = set() to_prefetch = { c for c in prefetch_cols if c.key in effective_params and c in mapper._columntoproperty and c.key not in evaluated_keys } to_expire = { mapper._columntoproperty[c].key for c in postfetch_cols if c in mapper._columntoproperty }.difference(evaluated_keys) prefetch_transfer = [ (mapper._columntoproperty[c].key, c.key) for c in to_prefetch ] for obj, state, dict_ in matched_objects: dict_.update( { col_to_prop: effective_params[c_key] for col_to_prop, c_key in prefetch_transfer } ) state._expire_attributes(state.dict, to_expire) to_evaluate = state.unmodified.intersection(evaluated_keys) for key in to_evaluate: if key in dict_: # only run eval for attributes that are present. dict_[key] = value_evaluators[key](obj) state.manager.dispatch.refresh(state, None, to_evaluate) state._commit(dict_, list(to_evaluate)) # attributes that were formerly modified instead get expired. # this only gets hit if the session had pending changes # and autoflush were set to False. to_expire = attrib.intersection(dict_).difference(to_evaluate) if to_expire: state._expire_attributes(dict_, to_expire) states.add(state) session._register_altered(states) @CompileState.plugin_for("orm", "delete") class BulkORMDelete(BulkUDCompileState, DeleteDMLState): @classmethod def create_for_statement(cls, statement, compiler, **kw): self = cls.__new__(cls) dml_strategy = statement._annotations.get( "dml_strategy", "unspecified" ) if ( dml_strategy == "core_only" or dml_strategy == "unspecified" and "parententity" not in statement.table._annotations ): DeleteDMLState.__init__(self, statement, compiler, **kw) return self toplevel = not compiler.stack orm_level_statement = statement ext_info = statement.table._annotations["parententity"] self.mapper = mapper = ext_info.mapper self._init_global_attributes( statement, compiler, toplevel=toplevel, process_criteria_for_toplevel=toplevel, ) new_stmt = statement._clone() if new_stmt.table._annotations["parententity"] is mapper: new_stmt.table = mapper.local_table new_crit = cls._adjust_for_extra_criteria( self.global_attributes, mapper ) if new_crit: new_stmt = new_stmt.where(*new_crit) # do this first as we need to determine if there is # DELETE..FROM DeleteDMLState.__init__(self, new_stmt, compiler, **kw) use_supplemental_cols = False if not toplevel: synchronize_session = None else: synchronize_session = compiler._annotations.get( "synchronize_session", None ) can_use_returning = compiler._annotations.get( "can_use_returning", None ) if can_use_returning is not False: # even though pre_exec has determined basic # can_use_returning for the dialect, if we are to use # RETURNING we need to run can_use_returning() at this level # unconditionally because is_delete_using was not known # at the pre_exec level can_use_returning = ( synchronize_session == "fetch" and self.can_use_returning( compiler.dialect, mapper, is_multitable=self.is_multitable, is_delete_using=compiler._annotations.get( "is_delete_using", False ), ) ) if can_use_returning: use_supplemental_cols = True new_stmt = new_stmt.return_defaults(*new_stmt.table.primary_key) if toplevel: new_stmt = self._setup_orm_returning( compiler, orm_level_statement, new_stmt, dml_mapper=mapper, use_supplemental_cols=use_supplemental_cols, ) self.statement = new_stmt return self @classmethod def orm_execute_statement( cls, session: Session, statement: dml.Delete, params: _CoreAnyExecuteParams, execution_options: OrmExecuteOptionsParameter, bind_arguments: _BindArguments, conn: Connection, ) -> _result.Result: update_options = execution_options.get( "_sa_orm_update_options", cls.default_update_options ) if update_options._dml_strategy == "bulk": raise sa_exc.InvalidRequestError( "Bulk ORM DELETE not supported right now. " "Statement may be invoked at the " "Core level using " "session.connection().execute(stmt, parameters)" ) if update_options._dml_strategy not in ("orm", "auto", "core_only"): raise sa_exc.ArgumentError( "Valid strategies for ORM DELETE strategy are 'orm', 'auto', " "'core_only'" ) return super().orm_execute_statement( session, statement, params, execution_options, bind_arguments, conn ) @classmethod def can_use_returning( cls, dialect: Dialect, mapper: Mapper[Any], *, is_multitable: bool = False, is_update_from: bool = False, is_delete_using: bool = False, is_executemany: bool = False, ) -> bool: # normal answer for "should we use RETURNING" at all. normal_answer = ( dialect.delete_returning and mapper.local_table.implicit_returning ) if not normal_answer: return False # now get into special workarounds because MariaDB supports # DELETE...RETURNING but not DELETE...USING...RETURNING. if is_delete_using: # is_delete_using hint was passed. use # additional dialect feature (True for PG, False for MariaDB) return dialect.delete_returning_multifrom elif is_multitable and not dialect.delete_returning_multifrom: # is_delete_using hint was not passed, but we determined # at compile time that this is in fact a DELETE..USING. # it's too late to continue since we did not pre-SELECT. # raise that we need that hint up front. raise sa_exc.CompileError( f'Dialect "{dialect.name}" does not support RETURNING ' "with DELETE..USING; for synchronize_session='fetch', " "please add the additional execution option " "'is_delete_using=True' to the statement to indicate that " "a separate SELECT should be used for this backend." ) return True @classmethod def _do_post_synchronize_evaluate( cls, session, statement, result, update_options ): matched_objects = cls._get_matched_objects_on_criteria( update_options, session.identity_map.all_states(), ) to_delete = [] for _, state, dict_, is_partially_expired in matched_objects: if is_partially_expired: state._expire(dict_, session.identity_map._modified) else: to_delete.append(state) if to_delete: session._remove_newly_deleted(to_delete) @classmethod def _do_post_synchronize_fetch( cls, session, statement, result, update_options ): target_mapper = update_options._subject_mapper returned_defaults_rows = result.returned_defaults_rows if returned_defaults_rows: pk_rows = cls._interpret_returning_rows( result, target_mapper, returned_defaults_rows ) matched_rows = [ tuple(row) + (update_options._identity_token,) for row in pk_rows ] else: matched_rows = update_options._matched_rows for row in matched_rows: primary_key = row[0:-1] identity_token = row[-1] # TODO: inline this and call remove_newly_deleted # once identity_key = target_mapper.identity_key_from_primary_key( list(primary_key), identity_token=identity_token, ) if identity_key in session.identity_map: session._remove_newly_deleted( [ attributes.instance_state( session.identity_map[identity_key] ) ] ) sqlalchemy/orm/writeonly.py 0000755 00000053441 15125143220 0012116 0 ustar 00 # orm/writeonly.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """Write-only collection API. This is an alternate mapped attribute style that only supports single-item collection mutation operations. To read the collection, a select() object must be executed each time. .. versionadded:: 2.0 """ from __future__ import annotations from typing import Any from typing import Collection from typing import Dict from typing import Generic from typing import Iterable from typing import Iterator from typing import List from typing import NoReturn from typing import Optional from typing import overload from typing import Tuple from typing import Type from typing import TYPE_CHECKING from typing import TypeVar from typing import Union from sqlalchemy.sql import bindparam from . import attributes from . import interfaces from . import relationships from . import strategies from .base import NEVER_SET from .base import object_mapper from .base import PassiveFlag from .base import RelationshipDirection from .. import exc from .. import inspect from .. import log from .. import util from ..sql import delete from ..sql import insert from ..sql import select from ..sql import update from ..sql.dml import Delete from ..sql.dml import Insert from ..sql.dml import Update from ..util.typing import Literal if TYPE_CHECKING: from . import QueryableAttribute from ._typing import _InstanceDict from .attributes import AttributeEventToken from .base import LoaderCallableStatus from .collections import _AdaptedCollectionProtocol from .collections import CollectionAdapter from .mapper import Mapper from .relationships import _RelationshipOrderByArg from .state import InstanceState from .util import AliasedClass from ..event import _Dispatch from ..sql.selectable import FromClause from ..sql.selectable import Select _T = TypeVar("_T", bound=Any) class WriteOnlyHistory(Generic[_T]): """Overrides AttributeHistory to receive append/remove events directly.""" unchanged_items: util.OrderedIdentitySet added_items: util.OrderedIdentitySet deleted_items: util.OrderedIdentitySet _reconcile_collection: bool def __init__( self, attr: WriteOnlyAttributeImpl, state: InstanceState[_T], passive: PassiveFlag, apply_to: Optional[WriteOnlyHistory[_T]] = None, ) -> None: if apply_to: if passive & PassiveFlag.SQL_OK: raise exc.InvalidRequestError( f"Attribute {attr} can't load the existing state from the " "database for this operation; full iteration is not " "permitted. If this is a delete operation, configure " f"passive_deletes=True on the {attr} relationship in " "order to resolve this error." ) self.unchanged_items = apply_to.unchanged_items self.added_items = apply_to.added_items self.deleted_items = apply_to.deleted_items self._reconcile_collection = apply_to._reconcile_collection else: self.deleted_items = util.OrderedIdentitySet() self.added_items = util.OrderedIdentitySet() self.unchanged_items = util.OrderedIdentitySet() self._reconcile_collection = False @property def added_plus_unchanged(self) -> List[_T]: return list(self.added_items.union(self.unchanged_items)) @property def all_items(self) -> List[_T]: return list( self.added_items.union(self.unchanged_items).union( self.deleted_items ) ) def as_history(self) -> attributes.History: if self._reconcile_collection: added = self.added_items.difference(self.unchanged_items) deleted = self.deleted_items.intersection(self.unchanged_items) unchanged = self.unchanged_items.difference(deleted) else: added, unchanged, deleted = ( self.added_items, self.unchanged_items, self.deleted_items, ) return attributes.History(list(added), list(unchanged), list(deleted)) def indexed(self, index: Union[int, slice]) -> Union[List[_T], _T]: return list(self.added_items)[index] def add_added(self, value: _T) -> None: self.added_items.add(value) def add_removed(self, value: _T) -> None: if value in self.added_items: self.added_items.remove(value) else: self.deleted_items.add(value) class WriteOnlyAttributeImpl( attributes.HasCollectionAdapter, attributes.AttributeImpl ): uses_objects: bool = True default_accepts_scalar_loader: bool = False supports_population: bool = False _supports_dynamic_iteration: bool = False collection: bool = False dynamic: bool = True order_by: _RelationshipOrderByArg = () collection_history_cls: Type[WriteOnlyHistory[Any]] = WriteOnlyHistory query_class: Type[WriteOnlyCollection[Any]] def __init__( self, class_: Union[Type[Any], AliasedClass[Any]], key: str, dispatch: _Dispatch[QueryableAttribute[Any]], target_mapper: Mapper[_T], order_by: _RelationshipOrderByArg, **kw: Any, ): super().__init__(class_, key, None, dispatch, **kw) self.target_mapper = target_mapper self.query_class = WriteOnlyCollection if order_by: self.order_by = tuple(order_by) def get( self, state: InstanceState[Any], dict_: _InstanceDict, passive: PassiveFlag = PassiveFlag.PASSIVE_OFF, ) -> Union[util.OrderedIdentitySet, WriteOnlyCollection[Any]]: if not passive & PassiveFlag.SQL_OK: return self._get_collection_history( state, PassiveFlag.PASSIVE_NO_INITIALIZE ).added_items else: return self.query_class(self, state) @overload def get_collection( self, state: InstanceState[Any], dict_: _InstanceDict, user_data: Literal[None] = ..., passive: Literal[PassiveFlag.PASSIVE_OFF] = ..., ) -> CollectionAdapter: ... @overload def get_collection( self, state: InstanceState[Any], dict_: _InstanceDict, user_data: _AdaptedCollectionProtocol = ..., passive: PassiveFlag = ..., ) -> CollectionAdapter: ... @overload def get_collection( self, state: InstanceState[Any], dict_: _InstanceDict, user_data: Optional[_AdaptedCollectionProtocol] = ..., passive: PassiveFlag = ..., ) -> Union[ Literal[LoaderCallableStatus.PASSIVE_NO_RESULT], CollectionAdapter ]: ... def get_collection( self, state: InstanceState[Any], dict_: _InstanceDict, user_data: Optional[_AdaptedCollectionProtocol] = None, passive: PassiveFlag = PassiveFlag.PASSIVE_OFF, ) -> Union[ Literal[LoaderCallableStatus.PASSIVE_NO_RESULT], CollectionAdapter ]: data: Collection[Any] if not passive & PassiveFlag.SQL_OK: data = self._get_collection_history(state, passive).added_items else: history = self._get_collection_history(state, passive) data = history.added_plus_unchanged return DynamicCollectionAdapter(data) # type: ignore[return-value] @util.memoized_property def _append_token( # type:ignore[override] self, ) -> attributes.AttributeEventToken: return attributes.AttributeEventToken(self, attributes.OP_APPEND) @util.memoized_property def _remove_token( # type:ignore[override] self, ) -> attributes.AttributeEventToken: return attributes.AttributeEventToken(self, attributes.OP_REMOVE) def fire_append_event( self, state: InstanceState[Any], dict_: _InstanceDict, value: Any, initiator: Optional[AttributeEventToken], collection_history: Optional[WriteOnlyHistory[Any]] = None, ) -> None: if collection_history is None: collection_history = self._modified_event(state, dict_) collection_history.add_added(value) for fn in self.dispatch.append: value = fn(state, value, initiator or self._append_token) if self.trackparent and value is not None: self.sethasparent(attributes.instance_state(value), state, True) def fire_remove_event( self, state: InstanceState[Any], dict_: _InstanceDict, value: Any, initiator: Optional[AttributeEventToken], collection_history: Optional[WriteOnlyHistory[Any]] = None, ) -> None: if collection_history is None: collection_history = self._modified_event(state, dict_) collection_history.add_removed(value) if self.trackparent and value is not None: self.sethasparent(attributes.instance_state(value), state, False) for fn in self.dispatch.remove: fn(state, value, initiator or self._remove_token) def _modified_event( self, state: InstanceState[Any], dict_: _InstanceDict ) -> WriteOnlyHistory[Any]: if self.key not in state.committed_state: state.committed_state[self.key] = self.collection_history_cls( self, state, PassiveFlag.PASSIVE_NO_FETCH ) state._modified_event(dict_, self, NEVER_SET) # this is a hack to allow the entities.ComparableEntity fixture # to work dict_[self.key] = True return state.committed_state[self.key] # type: ignore[no-any-return] def set( self, state: InstanceState[Any], dict_: _InstanceDict, value: Any, initiator: Optional[AttributeEventToken] = None, passive: PassiveFlag = PassiveFlag.PASSIVE_OFF, check_old: Any = None, pop: bool = False, _adapt: bool = True, ) -> None: if initiator and initiator.parent_token is self.parent_token: return if pop and value is None: return iterable = value new_values = list(iterable) if state.has_identity: if not self._supports_dynamic_iteration: raise exc.InvalidRequestError( f'Collection "{self}" does not support implicit ' "iteration; collection replacement operations " "can't be used" ) old_collection = util.IdentitySet( self.get(state, dict_, passive=passive) ) collection_history = self._modified_event(state, dict_) if not state.has_identity: old_collection = collection_history.added_items else: old_collection = old_collection.union( collection_history.added_items ) constants = old_collection.intersection(new_values) additions = util.IdentitySet(new_values).difference(constants) removals = old_collection.difference(constants) for member in new_values: if member in additions: self.fire_append_event( state, dict_, member, None, collection_history=collection_history, ) for member in removals: self.fire_remove_event( state, dict_, member, None, collection_history=collection_history, ) def delete(self, *args: Any, **kwargs: Any) -> NoReturn: raise NotImplementedError() def set_committed_value( self, state: InstanceState[Any], dict_: _InstanceDict, value: Any ) -> NoReturn: raise NotImplementedError( "Dynamic attributes don't support collection population." ) def get_history( self, state: InstanceState[Any], dict_: _InstanceDict, passive: PassiveFlag = PassiveFlag.PASSIVE_NO_FETCH, ) -> attributes.History: c = self._get_collection_history(state, passive) return c.as_history() def get_all_pending( self, state: InstanceState[Any], dict_: _InstanceDict, passive: PassiveFlag = PassiveFlag.PASSIVE_NO_INITIALIZE, ) -> List[Tuple[InstanceState[Any], Any]]: c = self._get_collection_history(state, passive) return [(attributes.instance_state(x), x) for x in c.all_items] def _get_collection_history( self, state: InstanceState[Any], passive: PassiveFlag ) -> WriteOnlyHistory[Any]: c: WriteOnlyHistory[Any] if self.key in state.committed_state: c = state.committed_state[self.key] else: c = self.collection_history_cls( self, state, PassiveFlag.PASSIVE_NO_FETCH ) if state.has_identity and (passive & PassiveFlag.INIT_OK): return self.collection_history_cls( self, state, passive, apply_to=c ) else: return c def append( self, state: InstanceState[Any], dict_: _InstanceDict, value: Any, initiator: Optional[AttributeEventToken], passive: PassiveFlag = PassiveFlag.PASSIVE_NO_FETCH, ) -> None: if initiator is not self: self.fire_append_event(state, dict_, value, initiator) def remove( self, state: InstanceState[Any], dict_: _InstanceDict, value: Any, initiator: Optional[AttributeEventToken], passive: PassiveFlag = PassiveFlag.PASSIVE_NO_FETCH, ) -> None: if initiator is not self: self.fire_remove_event(state, dict_, value, initiator) def pop( self, state: InstanceState[Any], dict_: _InstanceDict, value: Any, initiator: Optional[AttributeEventToken], passive: PassiveFlag = PassiveFlag.PASSIVE_NO_FETCH, ) -> None: self.remove(state, dict_, value, initiator, passive=passive) @log.class_logger @relationships.RelationshipProperty.strategy_for(lazy="write_only") class WriteOnlyLoader(strategies.AbstractRelationshipLoader, log.Identified): impl_class = WriteOnlyAttributeImpl def init_class_attribute(self, mapper: Mapper[Any]) -> None: self.is_class_level = True if not self.uselist or self.parent_property.direction not in ( interfaces.ONETOMANY, interfaces.MANYTOMANY, ): raise exc.InvalidRequestError( "On relationship %s, 'dynamic' loaders cannot be used with " "many-to-one/one-to-one relationships and/or " "uselist=False." % self.parent_property ) strategies._register_attribute( # type: ignore[no-untyped-call] self.parent_property, mapper, useobject=True, impl_class=self.impl_class, target_mapper=self.parent_property.mapper, order_by=self.parent_property.order_by, query_class=self.parent_property.query_class, ) class DynamicCollectionAdapter: """simplified CollectionAdapter for internal API consistency""" data: Collection[Any] def __init__(self, data: Collection[Any]): self.data = data def __iter__(self) -> Iterator[Any]: return iter(self.data) def _reset_empty(self) -> None: pass def __len__(self) -> int: return len(self.data) def __bool__(self) -> bool: return True class AbstractCollectionWriter(Generic[_T]): """Virtual collection which includes append/remove methods that synchronize into the attribute event system. """ if not TYPE_CHECKING: __slots__ = () instance: _T _from_obj: Tuple[FromClause, ...] def __init__(self, attr: WriteOnlyAttributeImpl, state: InstanceState[_T]): instance = state.obj() if TYPE_CHECKING: assert instance self.instance = instance self.attr = attr mapper = object_mapper(instance) prop = mapper._props[self.attr.key] if prop.secondary is not None: # this is a hack right now. The Query only knows how to # make subsequent joins() without a given left-hand side # from self._from_obj[0]. We need to ensure prop.secondary # is in the FROM. So we purposely put the mapper selectable # in _from_obj[0] to ensure a user-defined join() later on # doesn't fail, and secondary is then in _from_obj[1]. # note also, we are using the official ORM-annotated selectable # from __clause_element__(), see #7868 self._from_obj = (prop.mapper.__clause_element__(), prop.secondary) else: self._from_obj = () self._where_criteria = ( prop._with_parent(instance, alias_secondary=False), ) if self.attr.order_by: self._order_by_clauses = self.attr.order_by else: self._order_by_clauses = () def _add_all_impl(self, iterator: Iterable[_T]) -> None: for item in iterator: self.attr.append( attributes.instance_state(self.instance), attributes.instance_dict(self.instance), item, None, ) def _remove_impl(self, item: _T) -> None: self.attr.remove( attributes.instance_state(self.instance), attributes.instance_dict(self.instance), item, None, ) class WriteOnlyCollection(AbstractCollectionWriter[_T]): """Write-only collection which can synchronize changes into the attribute event system. The :class:`.WriteOnlyCollection` is used in a mapping by using the ``"write_only"`` lazy loading strategy with :func:`_orm.relationship`. For background on this configuration, see :ref:`write_only_relationship`. .. versionadded:: 2.0 .. seealso:: :ref:`write_only_relationship` """ __slots__ = ( "instance", "attr", "_where_criteria", "_from_obj", "_order_by_clauses", ) def __iter__(self) -> NoReturn: raise TypeError( "WriteOnly collections don't support iteration in-place; " "to query for collection items, use the select() method to " "produce a SQL statement and execute it with session.scalars()." ) def select(self) -> Select[Tuple[_T]]: """Produce a :class:`_sql.Select` construct that represents the rows within this instance-local :class:`_orm.WriteOnlyCollection`. """ stmt = select(self.attr.target_mapper).where(*self._where_criteria) if self._from_obj: stmt = stmt.select_from(*self._from_obj) if self._order_by_clauses: stmt = stmt.order_by(*self._order_by_clauses) return stmt def insert(self) -> Insert: """For one-to-many collections, produce a :class:`_dml.Insert` which will insert new rows in terms of this this instance-local :class:`_orm.WriteOnlyCollection`. This construct is only supported for a :class:`_orm.Relationship` that does **not** include the :paramref:`_orm.relationship.secondary` parameter. For relationships that refer to a many-to-many table, use ordinary bulk insert techniques to produce new objects, then use :meth:`_orm.AbstractCollectionWriter.add_all` to associate them with the collection. """ state = inspect(self.instance) mapper = state.mapper prop = mapper._props[self.attr.key] if prop.direction is not RelationshipDirection.ONETOMANY: raise exc.InvalidRequestError( "Write only bulk INSERT only supported for one-to-many " "collections; for many-to-many, use a separate bulk " "INSERT along with add_all()." ) dict_: Dict[str, Any] = {} for l, r in prop.synchronize_pairs: fn = prop._get_attr_w_warn_on_none( mapper, state, state.dict, l, ) dict_[r.key] = bindparam(None, callable_=fn) return insert(self.attr.target_mapper).values(**dict_) def update(self) -> Update: """Produce a :class:`_dml.Update` which will refer to rows in terms of this instance-local :class:`_orm.WriteOnlyCollection`. """ return update(self.attr.target_mapper).where(*self._where_criteria) def delete(self) -> Delete: """Produce a :class:`_dml.Delete` which will refer to rows in terms of this instance-local :class:`_orm.WriteOnlyCollection`. """ return delete(self.attr.target_mapper).where(*self._where_criteria) def add_all(self, iterator: Iterable[_T]) -> None: """Add an iterable of items to this :class:`_orm.WriteOnlyCollection`. The given items will be persisted to the database in terms of the parent instance's collection on the next flush. """ self._add_all_impl(iterator) def add(self, item: _T) -> None: """Add an item to this :class:`_orm.WriteOnlyCollection`. The given item will be persisted to the database in terms of the parent instance's collection on the next flush. """ self._add_all_impl([item]) def remove(self, item: _T) -> None: """Remove an item from this :class:`_orm.WriteOnlyCollection`. The given item will be removed from the parent instance's collection on the next flush. """ self._remove_impl(item) sqlalchemy/orm/unitofwork.py 0000755 00000064631 15125143220 0012274 0 ustar 00 # orm/unitofwork.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors """The internals for the unit of work system. The session's flush() process passes objects to a contextual object here, which assembles flush tasks based on mappers and their properties, organizes them in order of dependency, and executes. """ from __future__ import annotations from typing import Any from typing import Dict from typing import Optional from typing import Set from typing import TYPE_CHECKING from . import attributes from . import exc as orm_exc from . import util as orm_util from .. import event from .. import util from ..util import topological if TYPE_CHECKING: from .dependency import DependencyProcessor from .interfaces import MapperProperty from .mapper import Mapper from .session import Session from .session import SessionTransaction from .state import InstanceState def track_cascade_events(descriptor, prop): """Establish event listeners on object attributes which handle cascade-on-set/append. """ key = prop.key def append(state, item, initiator, **kw): # process "save_update" cascade rules for when # an instance is appended to the list of another instance if item is None: return sess = state.session if sess: if sess._warn_on_events: sess._flush_warning("collection append") prop = state.manager.mapper._props[key] item_state = attributes.instance_state(item) if ( prop._cascade.save_update and (key == initiator.key) and not sess._contains_state(item_state) ): sess._save_or_update_state(item_state) return item def remove(state, item, initiator, **kw): if item is None: return sess = state.session prop = state.manager.mapper._props[key] if sess and sess._warn_on_events: sess._flush_warning( "collection remove" if prop.uselist else "related attribute delete" ) if ( item is not None and item is not attributes.NEVER_SET and item is not attributes.PASSIVE_NO_RESULT and prop._cascade.delete_orphan ): # expunge pending orphans item_state = attributes.instance_state(item) if prop.mapper._is_orphan(item_state): if sess and item_state in sess._new: sess.expunge(item) else: # the related item may or may not itself be in a # Session, however the parent for which we are catching # the event is not in a session, so memoize this on the # item item_state._orphaned_outside_of_session = True def set_(state, newvalue, oldvalue, initiator, **kw): # process "save_update" cascade rules for when an instance # is attached to another instance if oldvalue is newvalue: return newvalue sess = state.session if sess: if sess._warn_on_events: sess._flush_warning("related attribute set") prop = state.manager.mapper._props[key] if newvalue is not None: newvalue_state = attributes.instance_state(newvalue) if ( prop._cascade.save_update and (key == initiator.key) and not sess._contains_state(newvalue_state) ): sess._save_or_update_state(newvalue_state) if ( oldvalue is not None and oldvalue is not attributes.NEVER_SET and oldvalue is not attributes.PASSIVE_NO_RESULT and prop._cascade.delete_orphan ): # possible to reach here with attributes.NEVER_SET ? oldvalue_state = attributes.instance_state(oldvalue) if oldvalue_state in sess._new and prop.mapper._is_orphan( oldvalue_state ): sess.expunge(oldvalue) return newvalue event.listen( descriptor, "append_wo_mutation", append, raw=True, include_key=True ) event.listen( descriptor, "append", append, raw=True, retval=True, include_key=True ) event.listen( descriptor, "remove", remove, raw=True, retval=True, include_key=True ) event.listen( descriptor, "set", set_, raw=True, retval=True, include_key=True ) class UOWTransaction: session: Session transaction: SessionTransaction attributes: Dict[str, Any] deps: util.defaultdict[Mapper[Any], Set[DependencyProcessor]] mappers: util.defaultdict[Mapper[Any], Set[InstanceState[Any]]] def __init__(self, session: Session): self.session = session # dictionary used by external actors to # store arbitrary state information. self.attributes = {} # dictionary of mappers to sets of # DependencyProcessors, which are also # set to be part of the sorted flush actions, # which have that mapper as a parent. self.deps = util.defaultdict(set) # dictionary of mappers to sets of InstanceState # items pending for flush which have that mapper # as a parent. self.mappers = util.defaultdict(set) # a dictionary of Preprocess objects, which gather # additional states impacted by the flush # and determine if a flush action is needed self.presort_actions = {} # dictionary of PostSortRec objects, each # one issues work during the flush within # a certain ordering. self.postsort_actions = {} # a set of 2-tuples, each containing two # PostSortRec objects where the second # is dependent on the first being executed # first self.dependencies = set() # dictionary of InstanceState-> (isdelete, listonly) # tuples, indicating if this state is to be deleted # or insert/updated, or just refreshed self.states = {} # tracks InstanceStates which will be receiving # a "post update" call. Keys are mappers, # values are a set of states and a set of the # columns which should be included in the update. self.post_update_states = util.defaultdict(lambda: (set(), set())) @property def has_work(self): return bool(self.states) def was_already_deleted(self, state): """Return ``True`` if the given state is expired and was deleted previously. """ if state.expired: try: state._load_expired(state, attributes.PASSIVE_OFF) except orm_exc.ObjectDeletedError: self.session._remove_newly_deleted([state]) return True return False def is_deleted(self, state): """Return ``True`` if the given state is marked as deleted within this uowtransaction.""" return state in self.states and self.states[state][0] def memo(self, key, callable_): if key in self.attributes: return self.attributes[key] else: self.attributes[key] = ret = callable_() return ret def remove_state_actions(self, state): """Remove pending actions for a state from the uowtransaction.""" isdelete = self.states[state][0] self.states[state] = (isdelete, True) def get_attribute_history( self, state, key, passive=attributes.PASSIVE_NO_INITIALIZE ): """Facade to attributes.get_state_history(), including caching of results.""" hashkey = ("history", state, key) # cache the objects, not the states; the strong reference here # prevents newly loaded objects from being dereferenced during the # flush process if hashkey in self.attributes: history, state_history, cached_passive = self.attributes[hashkey] # if the cached lookup was "passive" and now # we want non-passive, do a non-passive lookup and re-cache if ( not cached_passive & attributes.SQL_OK and passive & attributes.SQL_OK ): impl = state.manager[key].impl history = impl.get_history( state, state.dict, attributes.PASSIVE_OFF | attributes.LOAD_AGAINST_COMMITTED | attributes.NO_RAISE, ) if history and impl.uses_objects: state_history = history.as_state() else: state_history = history self.attributes[hashkey] = (history, state_history, passive) else: impl = state.manager[key].impl # TODO: store the history as (state, object) tuples # so we don't have to keep converting here history = impl.get_history( state, state.dict, passive | attributes.LOAD_AGAINST_COMMITTED | attributes.NO_RAISE, ) if history and impl.uses_objects: state_history = history.as_state() else: state_history = history self.attributes[hashkey] = (history, state_history, passive) return state_history def has_dep(self, processor): return (processor, True) in self.presort_actions def register_preprocessor(self, processor, fromparent): key = (processor, fromparent) if key not in self.presort_actions: self.presort_actions[key] = Preprocess(processor, fromparent) def register_object( self, state: InstanceState[Any], isdelete: bool = False, listonly: bool = False, cancel_delete: bool = False, operation: Optional[str] = None, prop: Optional[MapperProperty] = None, ) -> bool: if not self.session._contains_state(state): # this condition is normal when objects are registered # as part of a relationship cascade operation. it should # not occur for the top-level register from Session.flush(). if not state.deleted and operation is not None: util.warn( "Object of type %s not in session, %s operation " "along '%s' will not proceed" % (orm_util.state_class_str(state), operation, prop) ) return False if state not in self.states: mapper = state.manager.mapper if mapper not in self.mappers: self._per_mapper_flush_actions(mapper) self.mappers[mapper].add(state) self.states[state] = (isdelete, listonly) else: if not listonly and (isdelete or cancel_delete): self.states[state] = (isdelete, False) return True def register_post_update(self, state, post_update_cols): mapper = state.manager.mapper.base_mapper states, cols = self.post_update_states[mapper] states.add(state) cols.update(post_update_cols) def _per_mapper_flush_actions(self, mapper): saves = SaveUpdateAll(self, mapper.base_mapper) deletes = DeleteAll(self, mapper.base_mapper) self.dependencies.add((saves, deletes)) for dep in mapper._dependency_processors: dep.per_property_preprocessors(self) for prop in mapper.relationships: if prop.viewonly: continue dep = prop._dependency_processor dep.per_property_preprocessors(self) @util.memoized_property def _mapper_for_dep(self): """return a dynamic mapping of (Mapper, DependencyProcessor) to True or False, indicating if the DependencyProcessor operates on objects of that Mapper. The result is stored in the dictionary persistently once calculated. """ return util.PopulateDict( lambda tup: tup[0]._props.get(tup[1].key) is tup[1].prop ) def filter_states_for_dep(self, dep, states): """Filter the given list of InstanceStates to those relevant to the given DependencyProcessor. """ mapper_for_dep = self._mapper_for_dep return [s for s in states if mapper_for_dep[(s.manager.mapper, dep)]] def states_for_mapper_hierarchy(self, mapper, isdelete, listonly): checktup = (isdelete, listonly) for mapper in mapper.base_mapper.self_and_descendants: for state in self.mappers[mapper]: if self.states[state] == checktup: yield state def _generate_actions(self): """Generate the full, unsorted collection of PostSortRecs as well as dependency pairs for this UOWTransaction. """ # execute presort_actions, until all states # have been processed. a presort_action might # add new states to the uow. while True: ret = False for action in list(self.presort_actions.values()): if action.execute(self): ret = True if not ret: break # see if the graph of mapper dependencies has cycles. self.cycles = cycles = topological.find_cycles( self.dependencies, list(self.postsort_actions.values()) ) if cycles: # if yes, break the per-mapper actions into # per-state actions convert = { rec: set(rec.per_state_flush_actions(self)) for rec in cycles } # rewrite the existing dependencies to point to # the per-state actions for those per-mapper actions # that were broken up. for edge in list(self.dependencies): if ( None in edge or edge[0].disabled or edge[1].disabled or cycles.issuperset(edge) ): self.dependencies.remove(edge) elif edge[0] in cycles: self.dependencies.remove(edge) for dep in convert[edge[0]]: self.dependencies.add((dep, edge[1])) elif edge[1] in cycles: self.dependencies.remove(edge) for dep in convert[edge[1]]: self.dependencies.add((edge[0], dep)) return { a for a in self.postsort_actions.values() if not a.disabled }.difference(cycles) def execute(self) -> None: postsort_actions = self._generate_actions() postsort_actions = sorted( postsort_actions, key=lambda item: item.sort_key, ) # sort = topological.sort(self.dependencies, postsort_actions) # print "--------------" # print "\ndependencies:", self.dependencies # print "\ncycles:", self.cycles # print "\nsort:", list(sort) # print "\nCOUNT OF POSTSORT ACTIONS", len(postsort_actions) # execute if self.cycles: for subset in topological.sort_as_subsets( self.dependencies, postsort_actions ): set_ = set(subset) while set_: n = set_.pop() n.execute_aggregate(self, set_) else: for rec in topological.sort(self.dependencies, postsort_actions): rec.execute(self) def finalize_flush_changes(self) -> None: """Mark processed objects as clean / deleted after a successful flush(). This method is called within the flush() method after the execute() method has succeeded and the transaction has been committed. """ if not self.states: return states = set(self.states) isdel = { s for (s, (isdelete, listonly)) in self.states.items() if isdelete } other = states.difference(isdel) if isdel: self.session._remove_newly_deleted(isdel) if other: self.session._register_persistent(other) class IterateMappersMixin: __slots__ = () def _mappers(self, uow): if self.fromparent: return iter( m for m in self.dependency_processor.parent.self_and_descendants if uow._mapper_for_dep[(m, self.dependency_processor)] ) else: return self.dependency_processor.mapper.self_and_descendants class Preprocess(IterateMappersMixin): __slots__ = ( "dependency_processor", "fromparent", "processed", "setup_flush_actions", ) def __init__(self, dependency_processor, fromparent): self.dependency_processor = dependency_processor self.fromparent = fromparent self.processed = set() self.setup_flush_actions = False def execute(self, uow): delete_states = set() save_states = set() for mapper in self._mappers(uow): for state in uow.mappers[mapper].difference(self.processed): (isdelete, listonly) = uow.states[state] if not listonly: if isdelete: delete_states.add(state) else: save_states.add(state) if delete_states: self.dependency_processor.presort_deletes(uow, delete_states) self.processed.update(delete_states) if save_states: self.dependency_processor.presort_saves(uow, save_states) self.processed.update(save_states) if delete_states or save_states: if not self.setup_flush_actions and ( self.dependency_processor.prop_has_changes( uow, delete_states, True ) or self.dependency_processor.prop_has_changes( uow, save_states, False ) ): self.dependency_processor.per_property_flush_actions(uow) self.setup_flush_actions = True return True else: return False class PostSortRec: __slots__ = ("disabled",) def __new__(cls, uow, *args): key = (cls,) + args if key in uow.postsort_actions: return uow.postsort_actions[key] else: uow.postsort_actions[key] = ret = object.__new__(cls) ret.disabled = False return ret def execute_aggregate(self, uow, recs): self.execute(uow) class ProcessAll(IterateMappersMixin, PostSortRec): __slots__ = "dependency_processor", "isdelete", "fromparent", "sort_key" def __init__(self, uow, dependency_processor, isdelete, fromparent): self.dependency_processor = dependency_processor self.sort_key = ( "ProcessAll", self.dependency_processor.sort_key, isdelete, ) self.isdelete = isdelete self.fromparent = fromparent uow.deps[dependency_processor.parent.base_mapper].add( dependency_processor ) def execute(self, uow): states = self._elements(uow) if self.isdelete: self.dependency_processor.process_deletes(uow, states) else: self.dependency_processor.process_saves(uow, states) def per_state_flush_actions(self, uow): # this is handled by SaveUpdateAll and DeleteAll, # since a ProcessAll should unconditionally be pulled # into per-state if either the parent/child mappers # are part of a cycle return iter([]) def __repr__(self): return "%s(%s, isdelete=%s)" % ( self.__class__.__name__, self.dependency_processor, self.isdelete, ) def _elements(self, uow): for mapper in self._mappers(uow): for state in uow.mappers[mapper]: (isdelete, listonly) = uow.states[state] if isdelete == self.isdelete and not listonly: yield state class PostUpdateAll(PostSortRec): __slots__ = "mapper", "isdelete", "sort_key" def __init__(self, uow, mapper, isdelete): self.mapper = mapper self.isdelete = isdelete self.sort_key = ("PostUpdateAll", mapper._sort_key, isdelete) @util.preload_module("sqlalchemy.orm.persistence") def execute(self, uow): persistence = util.preloaded.orm_persistence states, cols = uow.post_update_states[self.mapper] states = [s for s in states if uow.states[s][0] == self.isdelete] persistence.post_update(self.mapper, states, uow, cols) class SaveUpdateAll(PostSortRec): __slots__ = ("mapper", "sort_key") def __init__(self, uow, mapper): self.mapper = mapper self.sort_key = ("SaveUpdateAll", mapper._sort_key) assert mapper is mapper.base_mapper @util.preload_module("sqlalchemy.orm.persistence") def execute(self, uow): util.preloaded.orm_persistence.save_obj( self.mapper, uow.states_for_mapper_hierarchy(self.mapper, False, False), uow, ) def per_state_flush_actions(self, uow): states = list( uow.states_for_mapper_hierarchy(self.mapper, False, False) ) base_mapper = self.mapper.base_mapper delete_all = DeleteAll(uow, base_mapper) for state in states: # keep saves before deletes - # this ensures 'row switch' operations work action = SaveUpdateState(uow, state) uow.dependencies.add((action, delete_all)) yield action for dep in uow.deps[self.mapper]: states_for_prop = uow.filter_states_for_dep(dep, states) dep.per_state_flush_actions(uow, states_for_prop, False) def __repr__(self): return "%s(%s)" % (self.__class__.__name__, self.mapper) class DeleteAll(PostSortRec): __slots__ = ("mapper", "sort_key") def __init__(self, uow, mapper): self.mapper = mapper self.sort_key = ("DeleteAll", mapper._sort_key) assert mapper is mapper.base_mapper @util.preload_module("sqlalchemy.orm.persistence") def execute(self, uow): util.preloaded.orm_persistence.delete_obj( self.mapper, uow.states_for_mapper_hierarchy(self.mapper, True, False), uow, ) def per_state_flush_actions(self, uow): states = list( uow.states_for_mapper_hierarchy(self.mapper, True, False) ) base_mapper = self.mapper.base_mapper save_all = SaveUpdateAll(uow, base_mapper) for state in states: # keep saves before deletes - # this ensures 'row switch' operations work action = DeleteState(uow, state) uow.dependencies.add((save_all, action)) yield action for dep in uow.deps[self.mapper]: states_for_prop = uow.filter_states_for_dep(dep, states) dep.per_state_flush_actions(uow, states_for_prop, True) def __repr__(self): return "%s(%s)" % (self.__class__.__name__, self.mapper) class ProcessState(PostSortRec): __slots__ = "dependency_processor", "isdelete", "state", "sort_key" def __init__(self, uow, dependency_processor, isdelete, state): self.dependency_processor = dependency_processor self.sort_key = ("ProcessState", dependency_processor.sort_key) self.isdelete = isdelete self.state = state def execute_aggregate(self, uow, recs): cls_ = self.__class__ dependency_processor = self.dependency_processor isdelete = self.isdelete our_recs = [ r for r in recs if r.__class__ is cls_ and r.dependency_processor is dependency_processor and r.isdelete is isdelete ] recs.difference_update(our_recs) states = [self.state] + [r.state for r in our_recs] if isdelete: dependency_processor.process_deletes(uow, states) else: dependency_processor.process_saves(uow, states) def __repr__(self): return "%s(%s, %s, delete=%s)" % ( self.__class__.__name__, self.dependency_processor, orm_util.state_str(self.state), self.isdelete, ) class SaveUpdateState(PostSortRec): __slots__ = "state", "mapper", "sort_key" def __init__(self, uow, state): self.state = state self.mapper = state.mapper.base_mapper self.sort_key = ("ProcessState", self.mapper._sort_key) @util.preload_module("sqlalchemy.orm.persistence") def execute_aggregate(self, uow, recs): persistence = util.preloaded.orm_persistence cls_ = self.__class__ mapper = self.mapper our_recs = [ r for r in recs if r.__class__ is cls_ and r.mapper is mapper ] recs.difference_update(our_recs) persistence.save_obj( mapper, [self.state] + [r.state for r in our_recs], uow ) def __repr__(self): return "%s(%s)" % ( self.__class__.__name__, orm_util.state_str(self.state), ) class DeleteState(PostSortRec): __slots__ = "state", "mapper", "sort_key" def __init__(self, uow, state): self.state = state self.mapper = state.mapper.base_mapper self.sort_key = ("DeleteState", self.mapper._sort_key) @util.preload_module("sqlalchemy.orm.persistence") def execute_aggregate(self, uow, recs): persistence = util.preloaded.orm_persistence cls_ = self.__class__ mapper = self.mapper our_recs = [ r for r in recs if r.__class__ is cls_ and r.mapper is mapper ] recs.difference_update(our_recs) states = [self.state] + [r.state for r in our_recs] persistence.delete_obj( mapper, [s for s in states if uow.states[s][0]], uow ) def __repr__(self): return "%s(%s)" % ( self.__class__.__name__, orm_util.state_str(self.state), ) sqlalchemy/orm/evaluator.py 0000755 00000030101 15125143220 0012050 0 ustar 00 # orm/evaluator.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors """Evaluation functions used **INTERNALLY** by ORM DML use cases. This module is **private, for internal use by SQLAlchemy**. .. versionchanged:: 2.0.4 renamed ``EvaluatorCompiler`` to ``_EvaluatorCompiler``. """ from __future__ import annotations from typing import Type from . import exc as orm_exc from .base import LoaderCallableStatus from .base import PassiveFlag from .. import exc from .. import inspect from ..sql import and_ from ..sql import operators from ..sql.sqltypes import Concatenable from ..sql.sqltypes import Integer from ..sql.sqltypes import Numeric from ..util import warn_deprecated class UnevaluatableError(exc.InvalidRequestError): pass class _NoObject(operators.ColumnOperators): def operate(self, *arg, **kw): return None def reverse_operate(self, *arg, **kw): return None class _ExpiredObject(operators.ColumnOperators): def operate(self, *arg, **kw): return self def reverse_operate(self, *arg, **kw): return self _NO_OBJECT = _NoObject() _EXPIRED_OBJECT = _ExpiredObject() class _EvaluatorCompiler: def __init__(self, target_cls=None): self.target_cls = target_cls def process(self, clause, *clauses): if clauses: clause = and_(clause, *clauses) meth = getattr(self, f"visit_{clause.__visit_name__}", None) if not meth: raise UnevaluatableError( f"Cannot evaluate {type(clause).__name__}" ) return meth(clause) def visit_grouping(self, clause): return self.process(clause.element) def visit_null(self, clause): return lambda obj: None def visit_false(self, clause): return lambda obj: False def visit_true(self, clause): return lambda obj: True def visit_column(self, clause): try: parentmapper = clause._annotations["parentmapper"] except KeyError as ke: raise UnevaluatableError( f"Cannot evaluate column: {clause}" ) from ke if self.target_cls and not issubclass( self.target_cls, parentmapper.class_ ): raise UnevaluatableError( "Can't evaluate criteria against " f"alternate class {parentmapper.class_}" ) parentmapper._check_configure() # we'd like to use "proxy_key" annotation to get the "key", however # in relationship primaryjoin cases proxy_key is sometimes deannotated # and sometimes apparently not present in the first place (?). # While I can stop it from being deannotated (though need to see if # this breaks other things), not sure right now about cases where it's # not there in the first place. can fix at some later point. # key = clause._annotations["proxy_key"] # for now, use the old way try: key = parentmapper._columntoproperty[clause].key except orm_exc.UnmappedColumnError as err: raise UnevaluatableError( f"Cannot evaluate expression: {err}" ) from err # note this used to fall back to a simple `getattr(obj, key)` evaluator # if impl was None; as of #8656, we ensure mappers are configured # so that impl is available impl = parentmapper.class_manager[key].impl def get_corresponding_attr(obj): if obj is None: return _NO_OBJECT state = inspect(obj) dict_ = state.dict value = impl.get( state, dict_, passive=PassiveFlag.PASSIVE_NO_FETCH ) if value is LoaderCallableStatus.PASSIVE_NO_RESULT: return _EXPIRED_OBJECT return value return get_corresponding_attr def visit_tuple(self, clause): return self.visit_clauselist(clause) def visit_expression_clauselist(self, clause): return self.visit_clauselist(clause) def visit_clauselist(self, clause): evaluators = [self.process(clause) for clause in clause.clauses] dispatch = ( f"visit_{clause.operator.__name__.rstrip('_')}_clauselist_op" ) meth = getattr(self, dispatch, None) if meth: return meth(clause.operator, evaluators, clause) else: raise UnevaluatableError( f"Cannot evaluate clauselist with operator {clause.operator}" ) def visit_binary(self, clause): eval_left = self.process(clause.left) eval_right = self.process(clause.right) dispatch = f"visit_{clause.operator.__name__.rstrip('_')}_binary_op" meth = getattr(self, dispatch, None) if meth: return meth(clause.operator, eval_left, eval_right, clause) else: raise UnevaluatableError( f"Cannot evaluate {type(clause).__name__} with " f"operator {clause.operator}" ) def visit_or_clauselist_op(self, operator, evaluators, clause): def evaluate(obj): has_null = False for sub_evaluate in evaluators: value = sub_evaluate(obj) if value is _EXPIRED_OBJECT: return _EXPIRED_OBJECT elif value: return True has_null = has_null or value is None if has_null: return None return False return evaluate def visit_and_clauselist_op(self, operator, evaluators, clause): def evaluate(obj): for sub_evaluate in evaluators: value = sub_evaluate(obj) if value is _EXPIRED_OBJECT: return _EXPIRED_OBJECT if not value: if value is None or value is _NO_OBJECT: return None return False return True return evaluate def visit_comma_op_clauselist_op(self, operator, evaluators, clause): def evaluate(obj): values = [] for sub_evaluate in evaluators: value = sub_evaluate(obj) if value is _EXPIRED_OBJECT: return _EXPIRED_OBJECT elif value is None or value is _NO_OBJECT: return None values.append(value) return tuple(values) return evaluate def visit_custom_op_binary_op( self, operator, eval_left, eval_right, clause ): if operator.python_impl: return self._straight_evaluate( operator, eval_left, eval_right, clause ) else: raise UnevaluatableError( f"Custom operator {operator.opstring!r} can't be evaluated " "in Python unless it specifies a callable using " "`.python_impl`." ) def visit_is_binary_op(self, operator, eval_left, eval_right, clause): def evaluate(obj): left_val = eval_left(obj) right_val = eval_right(obj) if left_val is _EXPIRED_OBJECT or right_val is _EXPIRED_OBJECT: return _EXPIRED_OBJECT return left_val == right_val return evaluate def visit_is_not_binary_op(self, operator, eval_left, eval_right, clause): def evaluate(obj): left_val = eval_left(obj) right_val = eval_right(obj) if left_val is _EXPIRED_OBJECT or right_val is _EXPIRED_OBJECT: return _EXPIRED_OBJECT return left_val != right_val return evaluate def _straight_evaluate(self, operator, eval_left, eval_right, clause): def evaluate(obj): left_val = eval_left(obj) right_val = eval_right(obj) if left_val is _EXPIRED_OBJECT or right_val is _EXPIRED_OBJECT: return _EXPIRED_OBJECT elif left_val is None or right_val is None: return None return operator(eval_left(obj), eval_right(obj)) return evaluate def _straight_evaluate_numeric_only( self, operator, eval_left, eval_right, clause ): if clause.left.type._type_affinity not in ( Numeric, Integer, ) or clause.right.type._type_affinity not in (Numeric, Integer): raise UnevaluatableError( f'Cannot evaluate math operator "{operator.__name__}" for ' f"datatypes {clause.left.type}, {clause.right.type}" ) return self._straight_evaluate(operator, eval_left, eval_right, clause) visit_add_binary_op = _straight_evaluate_numeric_only visit_mul_binary_op = _straight_evaluate_numeric_only visit_sub_binary_op = _straight_evaluate_numeric_only visit_mod_binary_op = _straight_evaluate_numeric_only visit_truediv_binary_op = _straight_evaluate_numeric_only visit_lt_binary_op = _straight_evaluate visit_le_binary_op = _straight_evaluate visit_ne_binary_op = _straight_evaluate visit_gt_binary_op = _straight_evaluate visit_ge_binary_op = _straight_evaluate visit_eq_binary_op = _straight_evaluate def visit_in_op_binary_op(self, operator, eval_left, eval_right, clause): return self._straight_evaluate( lambda a, b: a in b if a is not _NO_OBJECT else None, eval_left, eval_right, clause, ) def visit_not_in_op_binary_op( self, operator, eval_left, eval_right, clause ): return self._straight_evaluate( lambda a, b: a not in b if a is not _NO_OBJECT else None, eval_left, eval_right, clause, ) def visit_concat_op_binary_op( self, operator, eval_left, eval_right, clause ): if not issubclass( clause.left.type._type_affinity, Concatenable ) or not issubclass(clause.right.type._type_affinity, Concatenable): raise UnevaluatableError( f"Cannot evaluate concatenate operator " f'"{operator.__name__}" for ' f"datatypes {clause.left.type}, {clause.right.type}" ) return self._straight_evaluate( lambda a, b: a + b, eval_left, eval_right, clause ) def visit_startswith_op_binary_op( self, operator, eval_left, eval_right, clause ): return self._straight_evaluate( lambda a, b: a.startswith(b), eval_left, eval_right, clause ) def visit_endswith_op_binary_op( self, operator, eval_left, eval_right, clause ): return self._straight_evaluate( lambda a, b: a.endswith(b), eval_left, eval_right, clause ) def visit_unary(self, clause): eval_inner = self.process(clause.element) if clause.operator is operators.inv: def evaluate(obj): value = eval_inner(obj) if value is _EXPIRED_OBJECT: return _EXPIRED_OBJECT elif value is None: return None return not value return evaluate raise UnevaluatableError( f"Cannot evaluate {type(clause).__name__} " f"with operator {clause.operator}" ) def visit_bindparam(self, clause): if clause.callable: val = clause.callable() else: val = clause.value return lambda obj: val def __getattr__(name: str) -> Type[_EvaluatorCompiler]: if name == "EvaluatorCompiler": warn_deprecated( "Direct use of 'EvaluatorCompiler' is not supported, and this " "name will be removed in a future release. " "'_EvaluatorCompiler' is for internal use only", "2.0", ) return _EvaluatorCompiler else: raise AttributeError(f"module {__name__!r} has no attribute {name!r}") sqlalchemy/orm/dependency.py 0000755 00000135005 15125143220 0012175 0 ustar 00 # orm/dependency.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors """Relationship dependencies. """ from __future__ import annotations from . import attributes from . import exc from . import sync from . import unitofwork from . import util as mapperutil from .interfaces import MANYTOMANY from .interfaces import MANYTOONE from .interfaces import ONETOMANY from .. import exc as sa_exc from .. import sql from .. import util class DependencyProcessor: def __init__(self, prop): self.prop = prop self.cascade = prop.cascade self.mapper = prop.mapper self.parent = prop.parent self.secondary = prop.secondary self.direction = prop.direction self.post_update = prop.post_update self.passive_deletes = prop.passive_deletes self.passive_updates = prop.passive_updates self.enable_typechecks = prop.enable_typechecks if self.passive_deletes: self._passive_delete_flag = attributes.PASSIVE_NO_INITIALIZE else: self._passive_delete_flag = attributes.PASSIVE_OFF if self.passive_updates: self._passive_update_flag = attributes.PASSIVE_NO_INITIALIZE else: self._passive_update_flag = attributes.PASSIVE_OFF self.sort_key = "%s_%s" % (self.parent._sort_key, prop.key) self.key = prop.key if not self.prop.synchronize_pairs: raise sa_exc.ArgumentError( "Can't build a DependencyProcessor for relationship %s. " "No target attributes to populate between parent and " "child are present" % self.prop ) @classmethod def from_relationship(cls, prop): return _direction_to_processor[prop.direction](prop) def hasparent(self, state): """return True if the given object instance has a parent, according to the ``InstrumentedAttribute`` handled by this ``DependencyProcessor``. """ return self.parent.class_manager.get_impl(self.key).hasparent(state) def per_property_preprocessors(self, uow): """establish actions and dependencies related to a flush. These actions will operate on all relevant states in the aggregate. """ uow.register_preprocessor(self, True) def per_property_flush_actions(self, uow): after_save = unitofwork.ProcessAll(uow, self, False, True) before_delete = unitofwork.ProcessAll(uow, self, True, True) parent_saves = unitofwork.SaveUpdateAll( uow, self.parent.primary_base_mapper ) child_saves = unitofwork.SaveUpdateAll( uow, self.mapper.primary_base_mapper ) parent_deletes = unitofwork.DeleteAll( uow, self.parent.primary_base_mapper ) child_deletes = unitofwork.DeleteAll( uow, self.mapper.primary_base_mapper ) self.per_property_dependencies( uow, parent_saves, child_saves, parent_deletes, child_deletes, after_save, before_delete, ) def per_state_flush_actions(self, uow, states, isdelete): """establish actions and dependencies related to a flush. These actions will operate on all relevant states individually. This occurs only if there are cycles in the 'aggregated' version of events. """ child_base_mapper = self.mapper.primary_base_mapper child_saves = unitofwork.SaveUpdateAll(uow, child_base_mapper) child_deletes = unitofwork.DeleteAll(uow, child_base_mapper) # locate and disable the aggregate processors # for this dependency if isdelete: before_delete = unitofwork.ProcessAll(uow, self, True, True) before_delete.disabled = True else: after_save = unitofwork.ProcessAll(uow, self, False, True) after_save.disabled = True # check if the "child" side is part of the cycle if child_saves not in uow.cycles: # based on the current dependencies we use, the saves/ # deletes should always be in the 'cycles' collection # together. if this changes, we will have to break up # this method a bit more. assert child_deletes not in uow.cycles # child side is not part of the cycle, so we will link per-state # actions to the aggregate "saves", "deletes" actions child_actions = [(child_saves, False), (child_deletes, True)] child_in_cycles = False else: child_in_cycles = True # check if the "parent" side is part of the cycle if not isdelete: parent_saves = unitofwork.SaveUpdateAll( uow, self.parent.base_mapper ) parent_deletes = before_delete = None if parent_saves in uow.cycles: parent_in_cycles = True else: parent_deletes = unitofwork.DeleteAll(uow, self.parent.base_mapper) parent_saves = after_save = None if parent_deletes in uow.cycles: parent_in_cycles = True # now create actions /dependencies for each state. for state in states: # detect if there's anything changed or loaded # by a preprocessor on this state/attribute. In the # case of deletes we may try to load missing items here as well. sum_ = state.manager[self.key].impl.get_all_pending( state, state.dict, ( self._passive_delete_flag if isdelete else attributes.PASSIVE_NO_INITIALIZE ), ) if not sum_: continue if isdelete: before_delete = unitofwork.ProcessState(uow, self, True, state) if parent_in_cycles: parent_deletes = unitofwork.DeleteState(uow, state) else: after_save = unitofwork.ProcessState(uow, self, False, state) if parent_in_cycles: parent_saves = unitofwork.SaveUpdateState(uow, state) if child_in_cycles: child_actions = [] for child_state, child in sum_: if child_state not in uow.states: child_action = (None, None) else: (deleted, listonly) = uow.states[child_state] if deleted: child_action = ( unitofwork.DeleteState(uow, child_state), True, ) else: child_action = ( unitofwork.SaveUpdateState(uow, child_state), False, ) child_actions.append(child_action) # establish dependencies between our possibly per-state # parent action and our possibly per-state child action. for child_action, childisdelete in child_actions: self.per_state_dependencies( uow, parent_saves, parent_deletes, child_action, after_save, before_delete, isdelete, childisdelete, ) def presort_deletes(self, uowcommit, states): return False def presort_saves(self, uowcommit, states): return False def process_deletes(self, uowcommit, states): pass def process_saves(self, uowcommit, states): pass def prop_has_changes(self, uowcommit, states, isdelete): if not isdelete or self.passive_deletes: passive = ( attributes.PASSIVE_NO_INITIALIZE | attributes.INCLUDE_PENDING_MUTATIONS ) elif self.direction is MANYTOONE: # here, we were hoping to optimize having to fetch many-to-one # for history and ignore it, if there's no further cascades # to take place. however there are too many less common conditions # that still take place and tests in test_relationships / # test_cascade etc. will still fail. passive = attributes.PASSIVE_NO_FETCH_RELATED else: passive = ( attributes.PASSIVE_OFF | attributes.INCLUDE_PENDING_MUTATIONS ) for s in states: # TODO: add a high speed method # to InstanceState which returns: attribute # has a non-None value, or had one history = uowcommit.get_attribute_history(s, self.key, passive) if history and not history.empty(): return True else: return ( states and not self.prop._is_self_referential and self.mapper in uowcommit.mappers ) def _verify_canload(self, state): if self.prop.uselist and state is None: raise exc.FlushError( "Can't flush None value found in " "collection %s" % (self.prop,) ) elif state is not None and not self.mapper._canload( state, allow_subtypes=not self.enable_typechecks ): if self.mapper._canload(state, allow_subtypes=True): raise exc.FlushError( "Attempting to flush an item of type " "%(x)s as a member of collection " '"%(y)s". Expected an object of type ' "%(z)s or a polymorphic subclass of " "this type. If %(x)s is a subclass of " '%(z)s, configure mapper "%(zm)s" to ' "load this subtype polymorphically, or " "set enable_typechecks=False to allow " "any subtype to be accepted for flush. " % { "x": state.class_, "y": self.prop, "z": self.mapper.class_, "zm": self.mapper, } ) else: raise exc.FlushError( "Attempting to flush an item of type " "%(x)s as a member of collection " '"%(y)s". Expected an object of type ' "%(z)s or a polymorphic subclass of " "this type." % { "x": state.class_, "y": self.prop, "z": self.mapper.class_, } ) def _synchronize(self, state, child, associationrow, clearkeys, uowcommit): raise NotImplementedError() def _get_reversed_processed_set(self, uow): if not self.prop._reverse_property: return None process_key = tuple( sorted([self.key] + [p.key for p in self.prop._reverse_property]) ) return uow.memo(("reverse_key", process_key), set) def _post_update(self, state, uowcommit, related, is_m2o_delete=False): for x in related: if not is_m2o_delete or x is not None: uowcommit.register_post_update( state, [r for l, r in self.prop.synchronize_pairs] ) break def _pks_changed(self, uowcommit, state): raise NotImplementedError() def __repr__(self): return "%s(%s)" % (self.__class__.__name__, self.prop) class OneToManyDP(DependencyProcessor): def per_property_dependencies( self, uow, parent_saves, child_saves, parent_deletes, child_deletes, after_save, before_delete, ): if self.post_update: child_post_updates = unitofwork.PostUpdateAll( uow, self.mapper.primary_base_mapper, False ) child_pre_updates = unitofwork.PostUpdateAll( uow, self.mapper.primary_base_mapper, True ) uow.dependencies.update( [ (child_saves, after_save), (parent_saves, after_save), (after_save, child_post_updates), (before_delete, child_pre_updates), (child_pre_updates, parent_deletes), (child_pre_updates, child_deletes), ] ) else: uow.dependencies.update( [ (parent_saves, after_save), (after_save, child_saves), (after_save, child_deletes), (child_saves, parent_deletes), (child_deletes, parent_deletes), (before_delete, child_saves), (before_delete, child_deletes), ] ) def per_state_dependencies( self, uow, save_parent, delete_parent, child_action, after_save, before_delete, isdelete, childisdelete, ): if self.post_update: child_post_updates = unitofwork.PostUpdateAll( uow, self.mapper.primary_base_mapper, False ) child_pre_updates = unitofwork.PostUpdateAll( uow, self.mapper.primary_base_mapper, True ) # TODO: this whole block is not covered # by any tests if not isdelete: if childisdelete: uow.dependencies.update( [ (child_action, after_save), (after_save, child_post_updates), ] ) else: uow.dependencies.update( [ (save_parent, after_save), (child_action, after_save), (after_save, child_post_updates), ] ) else: if childisdelete: uow.dependencies.update( [ (before_delete, child_pre_updates), (child_pre_updates, delete_parent), ] ) else: uow.dependencies.update( [ (before_delete, child_pre_updates), (child_pre_updates, delete_parent), ] ) elif not isdelete: uow.dependencies.update( [ (save_parent, after_save), (after_save, child_action), (save_parent, child_action), ] ) else: uow.dependencies.update( [(before_delete, child_action), (child_action, delete_parent)] ) def presort_deletes(self, uowcommit, states): # head object is being deleted, and we manage its list of # child objects the child objects have to have their # foreign key to the parent set to NULL should_null_fks = ( not self.cascade.delete and not self.passive_deletes == "all" ) for state in states: history = uowcommit.get_attribute_history( state, self.key, self._passive_delete_flag ) if history: for child in history.deleted: if child is not None and self.hasparent(child) is False: if self.cascade.delete_orphan: uowcommit.register_object(child, isdelete=True) else: uowcommit.register_object(child) if should_null_fks: for child in history.unchanged: if child is not None: uowcommit.register_object( child, operation="delete", prop=self.prop ) def presort_saves(self, uowcommit, states): children_added = uowcommit.memo(("children_added", self), set) should_null_fks = ( not self.cascade.delete_orphan and not self.passive_deletes == "all" ) for state in states: pks_changed = self._pks_changed(uowcommit, state) if not pks_changed or self.passive_updates: passive = ( attributes.PASSIVE_NO_INITIALIZE | attributes.INCLUDE_PENDING_MUTATIONS ) else: passive = ( attributes.PASSIVE_OFF | attributes.INCLUDE_PENDING_MUTATIONS ) history = uowcommit.get_attribute_history(state, self.key, passive) if history: for child in history.added: if child is not None: uowcommit.register_object( child, cancel_delete=True, operation="add", prop=self.prop, ) children_added.update(history.added) for child in history.deleted: if not self.cascade.delete_orphan: if should_null_fks: uowcommit.register_object( child, isdelete=False, operation="delete", prop=self.prop, ) elif self.hasparent(child) is False: uowcommit.register_object( child, isdelete=True, operation="delete", prop=self.prop, ) for c, m, st_, dct_ in self.mapper.cascade_iterator( "delete", child ): uowcommit.register_object(st_, isdelete=True) if pks_changed: if history: for child in history.unchanged: if child is not None: uowcommit.register_object( child, False, self.passive_updates, operation="pk change", prop=self.prop, ) def process_deletes(self, uowcommit, states): # head object is being deleted, and we manage its list of # child objects the child objects have to have their foreign # key to the parent set to NULL this phase can be called # safely for any cascade but is unnecessary if delete cascade # is on. if self.post_update or not self.passive_deletes == "all": children_added = uowcommit.memo(("children_added", self), set) for state in states: history = uowcommit.get_attribute_history( state, self.key, self._passive_delete_flag ) if history: for child in history.deleted: if ( child is not None and self.hasparent(child) is False ): self._synchronize( state, child, None, True, uowcommit, False ) if self.post_update and child: self._post_update(child, uowcommit, [state]) if self.post_update or not self.cascade.delete: for child in set(history.unchanged).difference( children_added ): if child is not None: self._synchronize( state, child, None, True, uowcommit, False ) if self.post_update and child: self._post_update( child, uowcommit, [state] ) # technically, we can even remove each child from the # collection here too. but this would be a somewhat # inconsistent behavior since it wouldn't happen # if the old parent wasn't deleted but child was moved. def process_saves(self, uowcommit, states): should_null_fks = ( not self.cascade.delete_orphan and not self.passive_deletes == "all" ) for state in states: history = uowcommit.get_attribute_history( state, self.key, attributes.PASSIVE_NO_INITIALIZE ) if history: for child in history.added: self._synchronize( state, child, None, False, uowcommit, False ) if child is not None and self.post_update: self._post_update(child, uowcommit, [state]) for child in history.deleted: if ( should_null_fks and not self.cascade.delete_orphan and not self.hasparent(child) ): self._synchronize( state, child, None, True, uowcommit, False ) if self._pks_changed(uowcommit, state): for child in history.unchanged: self._synchronize( state, child, None, False, uowcommit, True ) def _synchronize( self, state, child, associationrow, clearkeys, uowcommit, pks_changed ): source = state dest = child self._verify_canload(child) if dest is None or ( not self.post_update and uowcommit.is_deleted(dest) ): return if clearkeys: sync.clear(dest, self.mapper, self.prop.synchronize_pairs) else: sync.populate( source, self.parent, dest, self.mapper, self.prop.synchronize_pairs, uowcommit, self.passive_updates and pks_changed, ) def _pks_changed(self, uowcommit, state): return sync.source_modified( uowcommit, state, self.parent, self.prop.synchronize_pairs ) class ManyToOneDP(DependencyProcessor): def __init__(self, prop): DependencyProcessor.__init__(self, prop) for mapper in self.mapper.self_and_descendants: mapper._dependency_processors.append(DetectKeySwitch(prop)) def per_property_dependencies( self, uow, parent_saves, child_saves, parent_deletes, child_deletes, after_save, before_delete, ): if self.post_update: parent_post_updates = unitofwork.PostUpdateAll( uow, self.parent.primary_base_mapper, False ) parent_pre_updates = unitofwork.PostUpdateAll( uow, self.parent.primary_base_mapper, True ) uow.dependencies.update( [ (child_saves, after_save), (parent_saves, after_save), (after_save, parent_post_updates), (after_save, parent_pre_updates), (before_delete, parent_pre_updates), (parent_pre_updates, child_deletes), (parent_pre_updates, parent_deletes), ] ) else: uow.dependencies.update( [ (child_saves, after_save), (after_save, parent_saves), (parent_saves, child_deletes), (parent_deletes, child_deletes), ] ) def per_state_dependencies( self, uow, save_parent, delete_parent, child_action, after_save, before_delete, isdelete, childisdelete, ): if self.post_update: if not isdelete: parent_post_updates = unitofwork.PostUpdateAll( uow, self.parent.primary_base_mapper, False ) if childisdelete: uow.dependencies.update( [ (after_save, parent_post_updates), (parent_post_updates, child_action), ] ) else: uow.dependencies.update( [ (save_parent, after_save), (child_action, after_save), (after_save, parent_post_updates), ] ) else: parent_pre_updates = unitofwork.PostUpdateAll( uow, self.parent.primary_base_mapper, True ) uow.dependencies.update( [ (before_delete, parent_pre_updates), (parent_pre_updates, delete_parent), (parent_pre_updates, child_action), ] ) elif not isdelete: if not childisdelete: uow.dependencies.update( [(child_action, after_save), (after_save, save_parent)] ) else: uow.dependencies.update([(after_save, save_parent)]) else: if childisdelete: uow.dependencies.update([(delete_parent, child_action)]) def presort_deletes(self, uowcommit, states): if self.cascade.delete or self.cascade.delete_orphan: for state in states: history = uowcommit.get_attribute_history( state, self.key, self._passive_delete_flag ) if history: if self.cascade.delete_orphan: todelete = history.sum() else: todelete = history.non_deleted() for child in todelete: if child is None: continue uowcommit.register_object( child, isdelete=True, operation="delete", prop=self.prop, ) t = self.mapper.cascade_iterator("delete", child) for c, m, st_, dct_ in t: uowcommit.register_object(st_, isdelete=True) def presort_saves(self, uowcommit, states): for state in states: uowcommit.register_object(state, operation="add", prop=self.prop) if self.cascade.delete_orphan: history = uowcommit.get_attribute_history( state, self.key, self._passive_delete_flag ) if history: for child in history.deleted: if self.hasparent(child) is False: uowcommit.register_object( child, isdelete=True, operation="delete", prop=self.prop, ) t = self.mapper.cascade_iterator("delete", child) for c, m, st_, dct_ in t: uowcommit.register_object(st_, isdelete=True) def process_deletes(self, uowcommit, states): if ( self.post_update and not self.cascade.delete_orphan and not self.passive_deletes == "all" ): # post_update means we have to update our # row to not reference the child object # before we can DELETE the row for state in states: self._synchronize(state, None, None, True, uowcommit) if state and self.post_update: history = uowcommit.get_attribute_history( state, self.key, self._passive_delete_flag ) if history: self._post_update( state, uowcommit, history.sum(), is_m2o_delete=True ) def process_saves(self, uowcommit, states): for state in states: history = uowcommit.get_attribute_history( state, self.key, attributes.PASSIVE_NO_INITIALIZE ) if history: if history.added: for child in history.added: self._synchronize( state, child, None, False, uowcommit, "add" ) elif history.deleted: self._synchronize( state, None, None, True, uowcommit, "delete" ) if self.post_update: self._post_update(state, uowcommit, history.sum()) def _synchronize( self, state, child, associationrow, clearkeys, uowcommit, operation=None, ): if state is None or ( not self.post_update and uowcommit.is_deleted(state) ): return if ( operation is not None and child is not None and not uowcommit.session._contains_state(child) ): util.warn( "Object of type %s not in session, %s " "operation along '%s' won't proceed" % (mapperutil.state_class_str(child), operation, self.prop) ) return if clearkeys or child is None: sync.clear(state, self.parent, self.prop.synchronize_pairs) else: self._verify_canload(child) sync.populate( child, self.mapper, state, self.parent, self.prop.synchronize_pairs, uowcommit, False, ) class DetectKeySwitch(DependencyProcessor): """For many-to-one relationships with no one-to-many backref, searches for parents through the unit of work when a primary key has changed and updates them. Theoretically, this approach could be expanded to support transparent deletion of objects referenced via many-to-one as well, although the current attribute system doesn't do enough bookkeeping for this to be efficient. """ def per_property_preprocessors(self, uow): if self.prop._reverse_property: if self.passive_updates: return else: if False in ( prop.passive_updates for prop in self.prop._reverse_property ): return uow.register_preprocessor(self, False) def per_property_flush_actions(self, uow): parent_saves = unitofwork.SaveUpdateAll(uow, self.parent.base_mapper) after_save = unitofwork.ProcessAll(uow, self, False, False) uow.dependencies.update([(parent_saves, after_save)]) def per_state_flush_actions(self, uow, states, isdelete): pass def presort_deletes(self, uowcommit, states): pass def presort_saves(self, uow, states): if not self.passive_updates: # for non-passive updates, register in the preprocess stage # so that mapper save_obj() gets a hold of changes self._process_key_switches(states, uow) def prop_has_changes(self, uow, states, isdelete): if not isdelete and self.passive_updates: d = self._key_switchers(uow, states) return bool(d) return False def process_deletes(self, uowcommit, states): assert False def process_saves(self, uowcommit, states): # for passive updates, register objects in the process stage # so that we avoid ManyToOneDP's registering the object without # the listonly flag in its own preprocess stage (results in UPDATE) # statements being emitted assert self.passive_updates self._process_key_switches(states, uowcommit) def _key_switchers(self, uow, states): switched, notswitched = uow.memo( ("pk_switchers", self), lambda: (set(), set()) ) allstates = switched.union(notswitched) for s in states: if s not in allstates: if self._pks_changed(uow, s): switched.add(s) else: notswitched.add(s) return switched def _process_key_switches(self, deplist, uowcommit): switchers = self._key_switchers(uowcommit, deplist) if switchers: # if primary key values have actually changed somewhere, perform # a linear search through the UOW in search of a parent. for state in uowcommit.session.identity_map.all_states(): if not issubclass(state.class_, self.parent.class_): continue dict_ = state.dict related = state.get_impl(self.key).get( state, dict_, passive=self._passive_update_flag ) if ( related is not attributes.PASSIVE_NO_RESULT and related is not None ): if self.prop.uselist: if not related: continue related_obj = related[0] else: related_obj = related related_state = attributes.instance_state(related_obj) if related_state in switchers: uowcommit.register_object( state, False, self.passive_updates ) sync.populate( related_state, self.mapper, state, self.parent, self.prop.synchronize_pairs, uowcommit, self.passive_updates, ) def _pks_changed(self, uowcommit, state): return bool(state.key) and sync.source_modified( uowcommit, state, self.mapper, self.prop.synchronize_pairs ) class ManyToManyDP(DependencyProcessor): def per_property_dependencies( self, uow, parent_saves, child_saves, parent_deletes, child_deletes, after_save, before_delete, ): uow.dependencies.update( [ (parent_saves, after_save), (child_saves, after_save), (after_save, child_deletes), # a rowswitch on the parent from deleted to saved # can make this one occur, as the "save" may remove # an element from the # "deleted" list before we have a chance to # process its child rows (before_delete, parent_saves), (before_delete, parent_deletes), (before_delete, child_deletes), (before_delete, child_saves), ] ) def per_state_dependencies( self, uow, save_parent, delete_parent, child_action, after_save, before_delete, isdelete, childisdelete, ): if not isdelete: if childisdelete: uow.dependencies.update( [(save_parent, after_save), (after_save, child_action)] ) else: uow.dependencies.update( [(save_parent, after_save), (child_action, after_save)] ) else: uow.dependencies.update( [(before_delete, child_action), (before_delete, delete_parent)] ) def presort_deletes(self, uowcommit, states): # TODO: no tests fail if this whole # thing is removed !!!! if not self.passive_deletes: # if no passive deletes, load history on # the collection, so that prop_has_changes() # returns True for state in states: uowcommit.get_attribute_history( state, self.key, self._passive_delete_flag ) def presort_saves(self, uowcommit, states): if not self.passive_updates: # if no passive updates, load history on # each collection where parent has changed PK, # so that prop_has_changes() returns True for state in states: if self._pks_changed(uowcommit, state): uowcommit.get_attribute_history( state, self.key, attributes.PASSIVE_OFF ) if not self.cascade.delete_orphan: return # check for child items removed from the collection # if delete_orphan check is turned on. for state in states: history = uowcommit.get_attribute_history( state, self.key, attributes.PASSIVE_NO_INITIALIZE ) if history: for child in history.deleted: if self.hasparent(child) is False: uowcommit.register_object( child, isdelete=True, operation="delete", prop=self.prop, ) for c, m, st_, dct_ in self.mapper.cascade_iterator( "delete", child ): uowcommit.register_object(st_, isdelete=True) def process_deletes(self, uowcommit, states): secondary_delete = [] secondary_insert = [] secondary_update = [] processed = self._get_reversed_processed_set(uowcommit) tmp = set() for state in states: # this history should be cached already, as # we loaded it in preprocess_deletes history = uowcommit.get_attribute_history( state, self.key, self._passive_delete_flag ) if history: for child in history.non_added(): if child is None or ( processed is not None and (state, child) in processed ): continue associationrow = {} if not self._synchronize( state, child, associationrow, False, uowcommit, "delete", ): continue secondary_delete.append(associationrow) tmp.update((c, state) for c in history.non_added()) if processed is not None: processed.update(tmp) self._run_crud( uowcommit, secondary_insert, secondary_update, secondary_delete ) def process_saves(self, uowcommit, states): secondary_delete = [] secondary_insert = [] secondary_update = [] processed = self._get_reversed_processed_set(uowcommit) tmp = set() for state in states: need_cascade_pks = not self.passive_updates and self._pks_changed( uowcommit, state ) if need_cascade_pks: passive = ( attributes.PASSIVE_OFF | attributes.INCLUDE_PENDING_MUTATIONS ) else: passive = ( attributes.PASSIVE_NO_INITIALIZE | attributes.INCLUDE_PENDING_MUTATIONS ) history = uowcommit.get_attribute_history(state, self.key, passive) if history: for child in history.added: if processed is not None and (state, child) in processed: continue associationrow = {} if not self._synchronize( state, child, associationrow, False, uowcommit, "add" ): continue secondary_insert.append(associationrow) for child in history.deleted: if processed is not None and (state, child) in processed: continue associationrow = {} if not self._synchronize( state, child, associationrow, False, uowcommit, "delete", ): continue secondary_delete.append(associationrow) tmp.update((c, state) for c in history.added + history.deleted) if need_cascade_pks: for child in history.unchanged: associationrow = {} sync.update( state, self.parent, associationrow, "old_", self.prop.synchronize_pairs, ) sync.update( child, self.mapper, associationrow, "old_", self.prop.secondary_synchronize_pairs, ) secondary_update.append(associationrow) if processed is not None: processed.update(tmp) self._run_crud( uowcommit, secondary_insert, secondary_update, secondary_delete ) def _run_crud( self, uowcommit, secondary_insert, secondary_update, secondary_delete ): connection = uowcommit.transaction.connection(self.mapper) if secondary_delete: associationrow = secondary_delete[0] statement = self.secondary.delete().where( sql.and_( *[ c == sql.bindparam(c.key, type_=c.type) for c in self.secondary.c if c.key in associationrow ] ) ) result = connection.execute(statement, secondary_delete) if ( result.supports_sane_multi_rowcount() ) and result.rowcount != len(secondary_delete): raise exc.StaleDataError( "DELETE statement on table '%s' expected to delete " "%d row(s); Only %d were matched." % ( self.secondary.description, len(secondary_delete), result.rowcount, ) ) if secondary_update: associationrow = secondary_update[0] statement = self.secondary.update().where( sql.and_( *[ c == sql.bindparam("old_" + c.key, type_=c.type) for c in self.secondary.c if c.key in associationrow ] ) ) result = connection.execute(statement, secondary_update) if ( result.supports_sane_multi_rowcount() ) and result.rowcount != len(secondary_update): raise exc.StaleDataError( "UPDATE statement on table '%s' expected to update " "%d row(s); Only %d were matched." % ( self.secondary.description, len(secondary_update), result.rowcount, ) ) if secondary_insert: statement = self.secondary.insert() connection.execute(statement, secondary_insert) def _synchronize( self, state, child, associationrow, clearkeys, uowcommit, operation ): # this checks for None if uselist=True self._verify_canload(child) # but if uselist=False we get here. If child is None, # no association row can be generated, so return. if child is None: return False if child is not None and not uowcommit.session._contains_state(child): if not child.deleted: util.warn( "Object of type %s not in session, %s " "operation along '%s' won't proceed" % (mapperutil.state_class_str(child), operation, self.prop) ) return False sync.populate_dict( state, self.parent, associationrow, self.prop.synchronize_pairs ) sync.populate_dict( child, self.mapper, associationrow, self.prop.secondary_synchronize_pairs, ) return True def _pks_changed(self, uowcommit, state): return sync.source_modified( uowcommit, state, self.parent, self.prop.synchronize_pairs ) _direction_to_processor = { ONETOMANY: OneToManyDP, MANYTOONE: ManyToOneDP, MANYTOMANY: ManyToManyDP, } sqlalchemy/orm/session.py 0000755 00000576446 15125143220 0011564 0 ustar 00 # orm/session.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """Provides the Session class and related utilities.""" from __future__ import annotations import contextlib from enum import Enum import itertools import sys import typing from typing import Any from typing import Callable from typing import cast from typing import Dict from typing import Generic from typing import Iterable from typing import Iterator from typing import List from typing import NoReturn from typing import Optional from typing import overload from typing import Sequence from typing import Set from typing import Tuple from typing import Type from typing import TYPE_CHECKING from typing import TypeVar from typing import Union import weakref from . import attributes from . import bulk_persistence from . import context from . import descriptor_props from . import exc from . import identity from . import loading from . import query from . import state as statelib from ._typing import _O from ._typing import insp_is_mapper from ._typing import is_composite_class from ._typing import is_orm_option from ._typing import is_user_defined_option from .base import _class_to_mapper from .base import _none_set from .base import _state_mapper from .base import instance_str from .base import LoaderCallableStatus from .base import object_mapper from .base import object_state from .base import PassiveFlag from .base import state_str from .context import FromStatement from .context import ORMCompileState from .identity import IdentityMap from .query import Query from .state import InstanceState from .state_changes import _StateChange from .state_changes import _StateChangeState from .state_changes import _StateChangeStates from .unitofwork import UOWTransaction from .. import engine from .. import exc as sa_exc from .. import sql from .. import util from ..engine import Connection from ..engine import Engine from ..engine.util import TransactionalContext from ..event import dispatcher from ..event import EventTarget from ..inspection import inspect from ..inspection import Inspectable from ..sql import coercions from ..sql import dml from ..sql import roles from ..sql import Select from ..sql import TableClause from ..sql import visitors from ..sql.base import _NoArg from ..sql.base import CompileState from ..sql.schema import Table from ..sql.selectable import ForUpdateArg from ..sql.selectable import LABEL_STYLE_TABLENAME_PLUS_COL from ..util import IdentitySet from ..util.typing import Literal from ..util.typing import Protocol if typing.TYPE_CHECKING: from ._typing import _EntityType from ._typing import _IdentityKeyType from ._typing import _InstanceDict from ._typing import OrmExecuteOptionsParameter from .interfaces import ORMOption from .interfaces import UserDefinedOption from .mapper import Mapper from .path_registry import PathRegistry from .query import RowReturningQuery from ..engine import CursorResult from ..engine import Result from ..engine import Row from ..engine import RowMapping from ..engine.base import Transaction from ..engine.base import TwoPhaseTransaction from ..engine.interfaces import _CoreAnyExecuteParams from ..engine.interfaces import _CoreSingleExecuteParams from ..engine.interfaces import _ExecuteOptions from ..engine.interfaces import CoreExecuteOptionsParameter from ..engine.result import ScalarResult from ..event import _InstanceLevelDispatch from ..sql._typing import _ColumnsClauseArgument from ..sql._typing import _InfoType from ..sql._typing import _T0 from ..sql._typing import _T1 from ..sql._typing import _T2 from ..sql._typing import _T3 from ..sql._typing import _T4 from ..sql._typing import _T5 from ..sql._typing import _T6 from ..sql._typing import _T7 from ..sql._typing import _TypedColumnClauseArgument as _TCCA from ..sql.base import Executable from ..sql.base import ExecutableOption from ..sql.dml import UpdateBase from ..sql.elements import ClauseElement from ..sql.roles import TypedColumnsClauseRole from ..sql.selectable import ForUpdateParameter from ..sql.selectable import TypedReturnsRows _T = TypeVar("_T", bound=Any) __all__ = [ "Session", "SessionTransaction", "sessionmaker", "ORMExecuteState", "close_all_sessions", "make_transient", "make_transient_to_detached", "object_session", ] _sessions: weakref.WeakValueDictionary[int, Session] = ( weakref.WeakValueDictionary() ) """Weak-referencing dictionary of :class:`.Session` objects. """ statelib._sessions = _sessions _PKIdentityArgument = Union[Any, Tuple[Any, ...]] _BindArguments = Dict[str, Any] _EntityBindKey = Union[Type[_O], "Mapper[_O]"] _SessionBindKey = Union[Type[Any], "Mapper[Any]", "TableClause", str] _SessionBind = Union["Engine", "Connection"] JoinTransactionMode = Literal[ "conditional_savepoint", "rollback_only", "control_fully", "create_savepoint", ] class _ConnectionCallableProto(Protocol): """a callable that returns a :class:`.Connection` given an instance. This callable, when present on a :class:`.Session`, is called only from the ORM's persistence mechanism (i.e. the unit of work flush process) to allow for connection-per-instance schemes (i.e. horizontal sharding) to be used as persistence time. This callable is not present on a plain :class:`.Session`, however is established when using the horizontal sharding extension. """ def __call__( self, mapper: Optional[Mapper[Any]] = None, instance: Optional[object] = None, **kw: Any, ) -> Connection: ... def _state_session(state: InstanceState[Any]) -> Optional[Session]: """Given an :class:`.InstanceState`, return the :class:`.Session` associated, if any. """ return state.session class _SessionClassMethods: """Class-level methods for :class:`.Session`, :class:`.sessionmaker`.""" @classmethod @util.deprecated( "1.3", "The :meth:`.Session.close_all` method is deprecated and will be " "removed in a future release. Please refer to " ":func:`.session.close_all_sessions`.", ) def close_all(cls) -> None: """Close *all* sessions in memory.""" close_all_sessions() @classmethod @util.preload_module("sqlalchemy.orm.util") def identity_key( cls, class_: Optional[Type[Any]] = None, ident: Union[Any, Tuple[Any, ...]] = None, *, instance: Optional[Any] = None, row: Optional[Union[Row[Any], RowMapping]] = None, identity_token: Optional[Any] = None, ) -> _IdentityKeyType[Any]: """Return an identity key. This is an alias of :func:`.util.identity_key`. """ return util.preloaded.orm_util.identity_key( class_, ident, instance=instance, row=row, identity_token=identity_token, ) @classmethod def object_session(cls, instance: object) -> Optional[Session]: """Return the :class:`.Session` to which an object belongs. This is an alias of :func:`.object_session`. """ return object_session(instance) class SessionTransactionState(_StateChangeState): ACTIVE = 1 PREPARED = 2 COMMITTED = 3 DEACTIVE = 4 CLOSED = 5 PROVISIONING_CONNECTION = 6 # backwards compatibility ACTIVE, PREPARED, COMMITTED, DEACTIVE, CLOSED, PROVISIONING_CONNECTION = tuple( SessionTransactionState ) class ORMExecuteState(util.MemoizedSlots): """Represents a call to the :meth:`_orm.Session.execute` method, as passed to the :meth:`.SessionEvents.do_orm_execute` event hook. .. versionadded:: 1.4 .. seealso:: :ref:`session_execute_events` - top level documentation on how to use :meth:`_orm.SessionEvents.do_orm_execute` """ __slots__ = ( "session", "statement", "parameters", "execution_options", "local_execution_options", "bind_arguments", "identity_token", "_compile_state_cls", "_starting_event_idx", "_events_todo", "_update_execution_options", ) session: Session """The :class:`_orm.Session` in use.""" statement: Executable """The SQL statement being invoked. For an ORM selection as would be retrieved from :class:`_orm.Query`, this is an instance of :class:`_sql.select` that was generated from the ORM query. """ parameters: Optional[_CoreAnyExecuteParams] """Dictionary of parameters that was passed to :meth:`_orm.Session.execute`.""" execution_options: _ExecuteOptions """The complete dictionary of current execution options. This is a merge of the statement level options with the locally passed execution options. .. seealso:: :attr:`_orm.ORMExecuteState.local_execution_options` :meth:`_sql.Executable.execution_options` :ref:`orm_queryguide_execution_options` """ local_execution_options: _ExecuteOptions """Dictionary view of the execution options passed to the :meth:`.Session.execute` method. This does not include options that may be associated with the statement being invoked. .. seealso:: :attr:`_orm.ORMExecuteState.execution_options` """ bind_arguments: _BindArguments """The dictionary passed as the :paramref:`_orm.Session.execute.bind_arguments` dictionary. This dictionary may be used by extensions to :class:`_orm.Session` to pass arguments that will assist in determining amongst a set of database connections which one should be used to invoke this statement. """ _compile_state_cls: Optional[Type[ORMCompileState]] _starting_event_idx: int _events_todo: List[Any] _update_execution_options: Optional[_ExecuteOptions] def __init__( self, session: Session, statement: Executable, parameters: Optional[_CoreAnyExecuteParams], execution_options: _ExecuteOptions, bind_arguments: _BindArguments, compile_state_cls: Optional[Type[ORMCompileState]], events_todo: List[_InstanceLevelDispatch[Session]], ): """Construct a new :class:`_orm.ORMExecuteState`. this object is constructed internally. """ self.session = session self.statement = statement self.parameters = parameters self.local_execution_options = execution_options self.execution_options = statement._execution_options.union( execution_options ) self.bind_arguments = bind_arguments self._compile_state_cls = compile_state_cls self._events_todo = list(events_todo) def _remaining_events(self) -> List[_InstanceLevelDispatch[Session]]: return self._events_todo[self._starting_event_idx + 1 :] def invoke_statement( self, statement: Optional[Executable] = None, params: Optional[_CoreAnyExecuteParams] = None, execution_options: Optional[OrmExecuteOptionsParameter] = None, bind_arguments: Optional[_BindArguments] = None, ) -> Result[Any]: """Execute the statement represented by this :class:`.ORMExecuteState`, without re-invoking events that have already proceeded. This method essentially performs a re-entrant execution of the current statement for which the :meth:`.SessionEvents.do_orm_execute` event is being currently invoked. The use case for this is for event handlers that want to override how the ultimate :class:`_engine.Result` object is returned, such as for schemes that retrieve results from an offline cache or which concatenate results from multiple executions. When the :class:`_engine.Result` object is returned by the actual handler function within :meth:`_orm.SessionEvents.do_orm_execute` and is propagated to the calling :meth:`_orm.Session.execute` method, the remainder of the :meth:`_orm.Session.execute` method is preempted and the :class:`_engine.Result` object is returned to the caller of :meth:`_orm.Session.execute` immediately. :param statement: optional statement to be invoked, in place of the statement currently represented by :attr:`.ORMExecuteState.statement`. :param params: optional dictionary of parameters or list of parameters which will be merged into the existing :attr:`.ORMExecuteState.parameters` of this :class:`.ORMExecuteState`. .. versionchanged:: 2.0 a list of parameter dictionaries is accepted for executemany executions. :param execution_options: optional dictionary of execution options will be merged into the existing :attr:`.ORMExecuteState.execution_options` of this :class:`.ORMExecuteState`. :param bind_arguments: optional dictionary of bind_arguments which will be merged amongst the current :attr:`.ORMExecuteState.bind_arguments` of this :class:`.ORMExecuteState`. :return: a :class:`_engine.Result` object with ORM-level results. .. seealso:: :ref:`do_orm_execute_re_executing` - background and examples on the appropriate usage of :meth:`_orm.ORMExecuteState.invoke_statement`. """ if statement is None: statement = self.statement _bind_arguments = dict(self.bind_arguments) if bind_arguments: _bind_arguments.update(bind_arguments) _bind_arguments["_sa_skip_events"] = True _params: Optional[_CoreAnyExecuteParams] if params: if self.is_executemany: _params = [] exec_many_parameters = cast( "List[Dict[str, Any]]", self.parameters ) for _existing_params, _new_params in itertools.zip_longest( exec_many_parameters, cast("List[Dict[str, Any]]", params), ): if _existing_params is None or _new_params is None: raise sa_exc.InvalidRequestError( f"Can't apply executemany parameters to " f"statement; number of parameter sets passed to " f"Session.execute() ({len(exec_many_parameters)}) " f"does not match number of parameter sets given " f"to ORMExecuteState.invoke_statement() " f"({len(params)})" ) _existing_params = dict(_existing_params) _existing_params.update(_new_params) _params.append(_existing_params) else: _params = dict(cast("Dict[str, Any]", self.parameters)) _params.update(cast("Dict[str, Any]", params)) else: _params = self.parameters _execution_options = self.local_execution_options if execution_options: _execution_options = _execution_options.union(execution_options) return self.session._execute_internal( statement, _params, execution_options=_execution_options, bind_arguments=_bind_arguments, _parent_execute_state=self, ) @property def bind_mapper(self) -> Optional[Mapper[Any]]: """Return the :class:`_orm.Mapper` that is the primary "bind" mapper. For an :class:`_orm.ORMExecuteState` object invoking an ORM statement, that is, the :attr:`_orm.ORMExecuteState.is_orm_statement` attribute is ``True``, this attribute will return the :class:`_orm.Mapper` that is considered to be the "primary" mapper of the statement. The term "bind mapper" refers to the fact that a :class:`_orm.Session` object may be "bound" to multiple :class:`_engine.Engine` objects keyed to mapped classes, and the "bind mapper" determines which of those :class:`_engine.Engine` objects would be selected. For a statement that is invoked against a single mapped class, :attr:`_orm.ORMExecuteState.bind_mapper` is intended to be a reliable way of getting this mapper. .. versionadded:: 1.4.0b2 .. seealso:: :attr:`_orm.ORMExecuteState.all_mappers` """ mp: Optional[Mapper[Any]] = self.bind_arguments.get("mapper", None) return mp @property def all_mappers(self) -> Sequence[Mapper[Any]]: """Return a sequence of all :class:`_orm.Mapper` objects that are involved at the top level of this statement. By "top level" we mean those :class:`_orm.Mapper` objects that would be represented in the result set rows for a :func:`_sql.select` query, or for a :func:`_dml.update` or :func:`_dml.delete` query, the mapper that is the main subject of the UPDATE or DELETE. .. versionadded:: 1.4.0b2 .. seealso:: :attr:`_orm.ORMExecuteState.bind_mapper` """ if not self.is_orm_statement: return [] elif isinstance(self.statement, (Select, FromStatement)): result = [] seen = set() for d in self.statement.column_descriptions: ent = d["entity"] if ent: insp = inspect(ent, raiseerr=False) if insp and insp.mapper and insp.mapper not in seen: seen.add(insp.mapper) result.append(insp.mapper) return result elif self.statement.is_dml and self.bind_mapper: return [self.bind_mapper] else: return [] @property def is_orm_statement(self) -> bool: """return True if the operation is an ORM statement. This indicates that the select(), insert(), update(), or delete() being invoked contains ORM entities as subjects. For a statement that does not have ORM entities and instead refers only to :class:`.Table` metadata, it is invoked as a Core SQL statement and no ORM-level automation takes place. """ return self._compile_state_cls is not None @property def is_executemany(self) -> bool: """return True if the parameters are a multi-element list of dictionaries with more than one dictionary. .. versionadded:: 2.0 """ return isinstance(self.parameters, list) @property def is_select(self) -> bool: """return True if this is a SELECT operation. .. versionchanged:: 2.0.30 - the attribute is also True for a :meth:`_sql.Select.from_statement` construct that is itself against a :class:`_sql.Select` construct, such as ``select(Entity).from_statement(select(..))`` """ return self.statement.is_select @property def is_from_statement(self) -> bool: """return True if this operation is a :meth:`_sql.Select.from_statement` operation. This is independent from :attr:`_orm.ORMExecuteState.is_select`, as a ``select().from_statement()`` construct can be used with INSERT/UPDATE/DELETE RETURNING types of statements as well. :attr:`_orm.ORMExecuteState.is_select` will only be set if the :meth:`_sql.Select.from_statement` is itself against a :class:`_sql.Select` construct. .. versionadded:: 2.0.30 """ return self.statement.is_from_statement @property def is_insert(self) -> bool: """return True if this is an INSERT operation. .. versionchanged:: 2.0.30 - the attribute is also True for a :meth:`_sql.Select.from_statement` construct that is itself against a :class:`_sql.Insert` construct, such as ``select(Entity).from_statement(insert(..))`` """ return self.statement.is_dml and self.statement.is_insert @property def is_update(self) -> bool: """return True if this is an UPDATE operation. .. versionchanged:: 2.0.30 - the attribute is also True for a :meth:`_sql.Select.from_statement` construct that is itself against a :class:`_sql.Update` construct, such as ``select(Entity).from_statement(update(..))`` """ return self.statement.is_dml and self.statement.is_update @property def is_delete(self) -> bool: """return True if this is a DELETE operation. .. versionchanged:: 2.0.30 - the attribute is also True for a :meth:`_sql.Select.from_statement` construct that is itself against a :class:`_sql.Delete` construct, such as ``select(Entity).from_statement(delete(..))`` """ return self.statement.is_dml and self.statement.is_delete @property def _is_crud(self) -> bool: return isinstance(self.statement, (dml.Update, dml.Delete)) def update_execution_options(self, **opts: Any) -> None: """Update the local execution options with new values.""" self.local_execution_options = self.local_execution_options.union(opts) def _orm_compile_options( self, ) -> Optional[ Union[ context.ORMCompileState.default_compile_options, Type[context.ORMCompileState.default_compile_options], ] ]: if not self.is_select: return None try: opts = self.statement._compile_options except AttributeError: return None if opts is not None and opts.isinstance( context.ORMCompileState.default_compile_options ): return opts # type: ignore else: return None @property def lazy_loaded_from(self) -> Optional[InstanceState[Any]]: """An :class:`.InstanceState` that is using this statement execution for a lazy load operation. The primary rationale for this attribute is to support the horizontal sharding extension, where it is available within specific query execution time hooks created by this extension. To that end, the attribute is only intended to be meaningful at **query execution time**, and importantly not any time prior to that, including query compilation time. """ return self.load_options._lazy_loaded_from @property def loader_strategy_path(self) -> Optional[PathRegistry]: """Return the :class:`.PathRegistry` for the current load path. This object represents the "path" in a query along relationships when a particular object or collection is being loaded. """ opts = self._orm_compile_options() if opts is not None: return opts._current_path else: return None @property def is_column_load(self) -> bool: """Return True if the operation is refreshing column-oriented attributes on an existing ORM object. This occurs during operations such as :meth:`_orm.Session.refresh`, as well as when an attribute deferred by :func:`_orm.defer` is being loaded, or an attribute that was expired either directly by :meth:`_orm.Session.expire` or via a commit operation is being loaded. Handlers will very likely not want to add any options to queries when such an operation is occurring as the query should be a straight primary key fetch which should not have any additional WHERE criteria, and loader options travelling with the instance will have already been added to the query. .. versionadded:: 1.4.0b2 .. seealso:: :attr:`_orm.ORMExecuteState.is_relationship_load` """ opts = self._orm_compile_options() return opts is not None and opts._for_refresh_state @property def is_relationship_load(self) -> bool: """Return True if this load is loading objects on behalf of a relationship. This means, the loader in effect is either a LazyLoader, SelectInLoader, SubqueryLoader, or similar, and the entire SELECT statement being emitted is on behalf of a relationship load. Handlers will very likely not want to add any options to queries when such an operation is occurring, as loader options are already capable of being propagated to relationship loaders and should be already present. .. seealso:: :attr:`_orm.ORMExecuteState.is_column_load` """ opts = self._orm_compile_options() if opts is None: return False path = self.loader_strategy_path return path is not None and not path.is_root @property def load_options( self, ) -> Union[ context.QueryContext.default_load_options, Type[context.QueryContext.default_load_options], ]: """Return the load_options that will be used for this execution.""" if not self.is_select: raise sa_exc.InvalidRequestError( "This ORM execution is not against a SELECT statement " "so there are no load options." ) lo: Union[ context.QueryContext.default_load_options, Type[context.QueryContext.default_load_options], ] = self.execution_options.get( "_sa_orm_load_options", context.QueryContext.default_load_options ) return lo @property def update_delete_options( self, ) -> Union[ bulk_persistence.BulkUDCompileState.default_update_options, Type[bulk_persistence.BulkUDCompileState.default_update_options], ]: """Return the update_delete_options that will be used for this execution.""" if not self._is_crud: raise sa_exc.InvalidRequestError( "This ORM execution is not against an UPDATE or DELETE " "statement so there are no update options." ) uo: Union[ bulk_persistence.BulkUDCompileState.default_update_options, Type[bulk_persistence.BulkUDCompileState.default_update_options], ] = self.execution_options.get( "_sa_orm_update_options", bulk_persistence.BulkUDCompileState.default_update_options, ) return uo @property def _non_compile_orm_options(self) -> Sequence[ORMOption]: return [ opt for opt in self.statement._with_options if is_orm_option(opt) and not opt._is_compile_state ] @property def user_defined_options(self) -> Sequence[UserDefinedOption]: """The sequence of :class:`.UserDefinedOptions` that have been associated with the statement being invoked. """ return [ opt for opt in self.statement._with_options if is_user_defined_option(opt) ] class SessionTransactionOrigin(Enum): """indicates the origin of a :class:`.SessionTransaction`. This enumeration is present on the :attr:`.SessionTransaction.origin` attribute of any :class:`.SessionTransaction` object. .. versionadded:: 2.0 """ AUTOBEGIN = 0 """transaction were started by autobegin""" BEGIN = 1 """transaction were started by calling :meth:`_orm.Session.begin`""" BEGIN_NESTED = 2 """tranaction were started by :meth:`_orm.Session.begin_nested`""" SUBTRANSACTION = 3 """transaction is an internal "subtransaction" """ class SessionTransaction(_StateChange, TransactionalContext): """A :class:`.Session`-level transaction. :class:`.SessionTransaction` is produced from the :meth:`_orm.Session.begin` and :meth:`_orm.Session.begin_nested` methods. It's largely an internal object that in modern use provides a context manager for session transactions. Documentation on interacting with :class:`_orm.SessionTransaction` is at: :ref:`unitofwork_transaction`. .. versionchanged:: 1.4 The scoping and API methods to work with the :class:`_orm.SessionTransaction` object directly have been simplified. .. seealso:: :ref:`unitofwork_transaction` :meth:`.Session.begin` :meth:`.Session.begin_nested` :meth:`.Session.rollback` :meth:`.Session.commit` :meth:`.Session.in_transaction` :meth:`.Session.in_nested_transaction` :meth:`.Session.get_transaction` :meth:`.Session.get_nested_transaction` """ _rollback_exception: Optional[BaseException] = None _connections: Dict[ Union[Engine, Connection], Tuple[Connection, Transaction, bool, bool] ] session: Session _parent: Optional[SessionTransaction] _state: SessionTransactionState _new: weakref.WeakKeyDictionary[InstanceState[Any], object] _deleted: weakref.WeakKeyDictionary[InstanceState[Any], object] _dirty: weakref.WeakKeyDictionary[InstanceState[Any], object] _key_switches: weakref.WeakKeyDictionary[ InstanceState[Any], Tuple[Any, Any] ] origin: SessionTransactionOrigin """Origin of this :class:`_orm.SessionTransaction`. Refers to a :class:`.SessionTransactionOrigin` instance which is an enumeration indicating the source event that led to constructing this :class:`_orm.SessionTransaction`. .. versionadded:: 2.0 """ nested: bool = False """Indicates if this is a nested, or SAVEPOINT, transaction. When :attr:`.SessionTransaction.nested` is True, it is expected that :attr:`.SessionTransaction.parent` will be present as well, linking to the enclosing :class:`.SessionTransaction`. .. seealso:: :attr:`.SessionTransaction.origin` """ def __init__( self, session: Session, origin: SessionTransactionOrigin, parent: Optional[SessionTransaction] = None, ): TransactionalContext._trans_ctx_check(session) self.session = session self._connections = {} self._parent = parent self.nested = nested = origin is SessionTransactionOrigin.BEGIN_NESTED self.origin = origin if session._close_state is _SessionCloseState.CLOSED: raise sa_exc.InvalidRequestError( "This Session has been permanently closed and is unable " "to handle any more transaction requests." ) if nested: if not parent: raise sa_exc.InvalidRequestError( "Can't start a SAVEPOINT transaction when no existing " "transaction is in progress" ) self._previous_nested_transaction = session._nested_transaction elif origin is SessionTransactionOrigin.SUBTRANSACTION: assert parent is not None else: assert parent is None self._state = SessionTransactionState.ACTIVE self._take_snapshot() # make sure transaction is assigned before we call the # dispatch self.session._transaction = self self.session.dispatch.after_transaction_create(self.session, self) def _raise_for_prerequisite_state( self, operation_name: str, state: _StateChangeState ) -> NoReturn: if state is SessionTransactionState.DEACTIVE: if self._rollback_exception: raise sa_exc.PendingRollbackError( "This Session's transaction has been rolled back " "due to a previous exception during flush." " To begin a new transaction with this Session, " "first issue Session.rollback()." f" Original exception was: {self._rollback_exception}", code="7s2a", ) else: raise sa_exc.InvalidRequestError( "This session is in 'inactive' state, due to the " "SQL transaction being rolled back; no further SQL " "can be emitted within this transaction." ) elif state is SessionTransactionState.CLOSED: raise sa_exc.ResourceClosedError("This transaction is closed") elif state is SessionTransactionState.PROVISIONING_CONNECTION: raise sa_exc.InvalidRequestError( "This session is provisioning a new connection; concurrent " "operations are not permitted", code="isce", ) else: raise sa_exc.InvalidRequestError( f"This session is in '{state.name.lower()}' state; no " "further SQL can be emitted within this transaction." ) @property def parent(self) -> Optional[SessionTransaction]: """The parent :class:`.SessionTransaction` of this :class:`.SessionTransaction`. If this attribute is ``None``, indicates this :class:`.SessionTransaction` is at the top of the stack, and corresponds to a real "COMMIT"/"ROLLBACK" block. If non-``None``, then this is either a "subtransaction" (an internal marker object used by the flush process) or a "nested" / SAVEPOINT transaction. If the :attr:`.SessionTransaction.nested` attribute is ``True``, then this is a SAVEPOINT, and if ``False``, indicates this a subtransaction. """ return self._parent @property def is_active(self) -> bool: return ( self.session is not None and self._state is SessionTransactionState.ACTIVE ) @property def _is_transaction_boundary(self) -> bool: return self.nested or not self._parent @_StateChange.declare_states( (SessionTransactionState.ACTIVE,), _StateChangeStates.NO_CHANGE ) def connection( self, bindkey: Optional[Mapper[Any]], execution_options: Optional[_ExecuteOptions] = None, **kwargs: Any, ) -> Connection: bind = self.session.get_bind(bindkey, **kwargs) return self._connection_for_bind(bind, execution_options) @_StateChange.declare_states( (SessionTransactionState.ACTIVE,), _StateChangeStates.NO_CHANGE ) def _begin(self, nested: bool = False) -> SessionTransaction: return SessionTransaction( self.session, ( SessionTransactionOrigin.BEGIN_NESTED if nested else SessionTransactionOrigin.SUBTRANSACTION ), self, ) def _iterate_self_and_parents( self, upto: Optional[SessionTransaction] = None ) -> Iterable[SessionTransaction]: current = self result: Tuple[SessionTransaction, ...] = () while current: result += (current,) if current._parent is upto: break elif current._parent is None: raise sa_exc.InvalidRequestError( "Transaction %s is not on the active transaction list" % (upto) ) else: current = current._parent return result def _take_snapshot(self) -> None: if not self._is_transaction_boundary: parent = self._parent assert parent is not None self._new = parent._new self._deleted = parent._deleted self._dirty = parent._dirty self._key_switches = parent._key_switches return is_begin = self.origin in ( SessionTransactionOrigin.BEGIN, SessionTransactionOrigin.AUTOBEGIN, ) if not is_begin and not self.session._flushing: self.session.flush() self._new = weakref.WeakKeyDictionary() self._deleted = weakref.WeakKeyDictionary() self._dirty = weakref.WeakKeyDictionary() self._key_switches = weakref.WeakKeyDictionary() def _restore_snapshot(self, dirty_only: bool = False) -> None: """Restore the restoration state taken before a transaction began. Corresponds to a rollback. """ assert self._is_transaction_boundary to_expunge = set(self._new).union(self.session._new) self.session._expunge_states(to_expunge, to_transient=True) for s, (oldkey, newkey) in self._key_switches.items(): # we probably can do this conditionally based on # if we expunged or not, but safe_discard does that anyway self.session.identity_map.safe_discard(s) # restore the old key s.key = oldkey # now restore the object, but only if we didn't expunge if s not in to_expunge: self.session.identity_map.replace(s) for s in set(self._deleted).union(self.session._deleted): self.session._update_impl(s, revert_deletion=True) assert not self.session._deleted for s in self.session.identity_map.all_states(): if not dirty_only or s.modified or s in self._dirty: s._expire(s.dict, self.session.identity_map._modified) def _remove_snapshot(self) -> None: """Remove the restoration state taken before a transaction began. Corresponds to a commit. """ assert self._is_transaction_boundary if not self.nested and self.session.expire_on_commit: for s in self.session.identity_map.all_states(): s._expire(s.dict, self.session.identity_map._modified) statelib.InstanceState._detach_states( list(self._deleted), self.session ) self._deleted.clear() elif self.nested: parent = self._parent assert parent is not None parent._new.update(self._new) parent._dirty.update(self._dirty) parent._deleted.update(self._deleted) parent._key_switches.update(self._key_switches) @_StateChange.declare_states( (SessionTransactionState.ACTIVE,), _StateChangeStates.NO_CHANGE ) def _connection_for_bind( self, bind: _SessionBind, execution_options: Optional[CoreExecuteOptionsParameter], ) -> Connection: if bind in self._connections: if execution_options: util.warn( "Connection is already established for the " "given bind; execution_options ignored" ) return self._connections[bind][0] self._state = SessionTransactionState.PROVISIONING_CONNECTION local_connect = False should_commit = True try: if self._parent: conn = self._parent._connection_for_bind( bind, execution_options ) if not self.nested: return conn else: if isinstance(bind, engine.Connection): conn = bind if conn.engine in self._connections: raise sa_exc.InvalidRequestError( "Session already has a Connection associated " "for the given Connection's Engine" ) else: conn = bind.connect() local_connect = True try: if execution_options: conn = conn.execution_options(**execution_options) transaction: Transaction if self.session.twophase and self._parent is None: # TODO: shouldn't we only be here if not # conn.in_transaction() ? # if twophase is set and conn.in_transaction(), validate # that it is in fact twophase. transaction = conn.begin_twophase() elif self.nested: transaction = conn.begin_nested() elif conn.in_transaction(): join_transaction_mode = self.session.join_transaction_mode if join_transaction_mode == "conditional_savepoint": if conn.in_nested_transaction(): join_transaction_mode = "create_savepoint" else: join_transaction_mode = "rollback_only" if local_connect: util.warn( "The engine provided as bind produced a " "connection that is already in a transaction. " "This is usually caused by a core event, " "such as 'engine_connect', that has left a " "transaction open. The effective join " "transaction mode used by this session is " f"{join_transaction_mode!r}. To silence this " "warning, do not leave transactions open" ) if join_transaction_mode in ( "control_fully", "rollback_only", ): if conn.in_nested_transaction(): transaction = ( conn._get_required_nested_transaction() ) else: transaction = conn._get_required_transaction() if join_transaction_mode == "rollback_only": should_commit = False elif join_transaction_mode == "create_savepoint": transaction = conn.begin_nested() else: assert False, join_transaction_mode else: transaction = conn.begin() except: # connection will not not be associated with this Session; # close it immediately so that it isn't closed under GC if local_connect: conn.close() raise else: bind_is_connection = isinstance(bind, engine.Connection) self._connections[conn] = self._connections[conn.engine] = ( conn, transaction, should_commit, not bind_is_connection, ) self.session.dispatch.after_begin(self.session, self, conn) return conn finally: self._state = SessionTransactionState.ACTIVE def prepare(self) -> None: if self._parent is not None or not self.session.twophase: raise sa_exc.InvalidRequestError( "'twophase' mode not enabled, or not root transaction; " "can't prepare." ) self._prepare_impl() @_StateChange.declare_states( (SessionTransactionState.ACTIVE,), SessionTransactionState.PREPARED ) def _prepare_impl(self) -> None: if self._parent is None or self.nested: self.session.dispatch.before_commit(self.session) stx = self.session._transaction assert stx is not None if stx is not self: for subtransaction in stx._iterate_self_and_parents(upto=self): subtransaction.commit() if not self.session._flushing: for _flush_guard in range(100): if self.session._is_clean(): break self.session.flush() else: raise exc.FlushError( "Over 100 subsequent flushes have occurred within " "session.commit() - is an after_flush() hook " "creating new objects?" ) if self._parent is None and self.session.twophase: try: for t in set(self._connections.values()): cast("TwoPhaseTransaction", t[1]).prepare() except: with util.safe_reraise(): self.rollback() self._state = SessionTransactionState.PREPARED @_StateChange.declare_states( (SessionTransactionState.ACTIVE, SessionTransactionState.PREPARED), SessionTransactionState.CLOSED, ) def commit(self, _to_root: bool = False) -> None: if self._state is not SessionTransactionState.PREPARED: with self._expect_state(SessionTransactionState.PREPARED): self._prepare_impl() if self._parent is None or self.nested: for conn, trans, should_commit, autoclose in set( self._connections.values() ): if should_commit: trans.commit() self._state = SessionTransactionState.COMMITTED self.session.dispatch.after_commit(self.session) self._remove_snapshot() with self._expect_state(SessionTransactionState.CLOSED): self.close() if _to_root and self._parent: self._parent.commit(_to_root=True) @_StateChange.declare_states( ( SessionTransactionState.ACTIVE, SessionTransactionState.DEACTIVE, SessionTransactionState.PREPARED, ), SessionTransactionState.CLOSED, ) def rollback( self, _capture_exception: bool = False, _to_root: bool = False ) -> None: stx = self.session._transaction assert stx is not None if stx is not self: for subtransaction in stx._iterate_self_and_parents(upto=self): subtransaction.close() boundary = self rollback_err = None if self._state in ( SessionTransactionState.ACTIVE, SessionTransactionState.PREPARED, ): for transaction in self._iterate_self_and_parents(): if transaction._parent is None or transaction.nested: try: for t in set(transaction._connections.values()): t[1].rollback() transaction._state = SessionTransactionState.DEACTIVE self.session.dispatch.after_rollback(self.session) except: rollback_err = sys.exc_info() finally: transaction._state = SessionTransactionState.DEACTIVE transaction._restore_snapshot( dirty_only=transaction.nested ) boundary = transaction break else: transaction._state = SessionTransactionState.DEACTIVE sess = self.session if not rollback_err and not sess._is_clean(): # if items were added, deleted, or mutated # here, we need to re-restore the snapshot util.warn( "Session's state has been changed on " "a non-active transaction - this state " "will be discarded." ) boundary._restore_snapshot(dirty_only=boundary.nested) with self._expect_state(SessionTransactionState.CLOSED): self.close() if self._parent and _capture_exception: self._parent._rollback_exception = sys.exc_info()[1] if rollback_err and rollback_err[1]: raise rollback_err[1].with_traceback(rollback_err[2]) sess.dispatch.after_soft_rollback(sess, self) if _to_root and self._parent: self._parent.rollback(_to_root=True) @_StateChange.declare_states( _StateChangeStates.ANY, SessionTransactionState.CLOSED ) def close(self, invalidate: bool = False) -> None: if self.nested: self.session._nested_transaction = ( self._previous_nested_transaction ) self.session._transaction = self._parent for connection, transaction, should_commit, autoclose in set( self._connections.values() ): if invalidate and self._parent is None: connection.invalidate() if should_commit and transaction.is_active: transaction.close() if autoclose and self._parent is None: connection.close() self._state = SessionTransactionState.CLOSED sess = self.session # TODO: these two None sets were historically after the # event hook below, and in 2.0 I changed it this way for some reason, # and I remember there being a reason, but not what it was. # Why do we need to get rid of them at all? test_memusage::CycleTest # passes with these commented out. # self.session = None # type: ignore # self._connections = None # type: ignore sess.dispatch.after_transaction_end(sess, self) def _get_subject(self) -> Session: return self.session def _transaction_is_active(self) -> bool: return self._state is SessionTransactionState.ACTIVE def _transaction_is_closed(self) -> bool: return self._state is SessionTransactionState.CLOSED def _rollback_can_be_called(self) -> bool: return self._state not in (COMMITTED, CLOSED) class _SessionCloseState(Enum): ACTIVE = 1 CLOSED = 2 CLOSE_IS_RESET = 3 class Session(_SessionClassMethods, EventTarget): """Manages persistence operations for ORM-mapped objects. The :class:`_orm.Session` is **not safe for use in concurrent threads.**. See :ref:`session_faq_threadsafe` for background. The Session's usage paradigm is described at :doc:`/orm/session`. """ _is_asyncio = False dispatch: dispatcher[Session] identity_map: IdentityMap """A mapping of object identities to objects themselves. Iterating through ``Session.identity_map.values()`` provides access to the full set of persistent objects (i.e., those that have row identity) currently in the session. .. seealso:: :func:`.identity_key` - helper function to produce the keys used in this dictionary. """ _new: Dict[InstanceState[Any], Any] _deleted: Dict[InstanceState[Any], Any] bind: Optional[Union[Engine, Connection]] __binds: Dict[_SessionBindKey, _SessionBind] _flushing: bool _warn_on_events: bool _transaction: Optional[SessionTransaction] _nested_transaction: Optional[SessionTransaction] hash_key: int autoflush: bool expire_on_commit: bool enable_baked_queries: bool twophase: bool join_transaction_mode: JoinTransactionMode _query_cls: Type[Query[Any]] _close_state: _SessionCloseState def __init__( self, bind: Optional[_SessionBind] = None, *, autoflush: bool = True, future: Literal[True] = True, expire_on_commit: bool = True, autobegin: bool = True, twophase: bool = False, binds: Optional[Dict[_SessionBindKey, _SessionBind]] = None, enable_baked_queries: bool = True, info: Optional[_InfoType] = None, query_cls: Optional[Type[Query[Any]]] = None, autocommit: Literal[False] = False, join_transaction_mode: JoinTransactionMode = "conditional_savepoint", close_resets_only: Union[bool, _NoArg] = _NoArg.NO_ARG, ): r"""Construct a new :class:`_orm.Session`. See also the :class:`.sessionmaker` function which is used to generate a :class:`.Session`-producing callable with a given set of arguments. :param autoflush: When ``True``, all query operations will issue a :meth:`~.Session.flush` call to this ``Session`` before proceeding. This is a convenience feature so that :meth:`~.Session.flush` need not be called repeatedly in order for database queries to retrieve results. .. seealso:: :ref:`session_flushing` - additional background on autoflush :param autobegin: Automatically start transactions (i.e. equivalent to invoking :meth:`_orm.Session.begin`) when database access is requested by an operation. Defaults to ``True``. Set to ``False`` to prevent a :class:`_orm.Session` from implicitly beginning transactions after construction, as well as after any of the :meth:`_orm.Session.rollback`, :meth:`_orm.Session.commit`, or :meth:`_orm.Session.close` methods are called. .. versionadded:: 2.0 .. seealso:: :ref:`session_autobegin_disable` :param bind: An optional :class:`_engine.Engine` or :class:`_engine.Connection` to which this ``Session`` should be bound. When specified, all SQL operations performed by this session will execute via this connectable. :param binds: A dictionary which may specify any number of :class:`_engine.Engine` or :class:`_engine.Connection` objects as the source of connectivity for SQL operations on a per-entity basis. The keys of the dictionary consist of any series of mapped classes, arbitrary Python classes that are bases for mapped classes, :class:`_schema.Table` objects and :class:`_orm.Mapper` objects. The values of the dictionary are then instances of :class:`_engine.Engine` or less commonly :class:`_engine.Connection` objects. Operations which proceed relative to a particular mapped class will consult this dictionary for the closest matching entity in order to determine which :class:`_engine.Engine` should be used for a particular SQL operation. The complete heuristics for resolution are described at :meth:`.Session.get_bind`. Usage looks like:: Session = sessionmaker( binds={ SomeMappedClass: create_engine("postgresql+psycopg2://engine1"), SomeDeclarativeBase: create_engine( "postgresql+psycopg2://engine2" ), some_mapper: create_engine("postgresql+psycopg2://engine3"), some_table: create_engine("postgresql+psycopg2://engine4"), } ) .. seealso:: :ref:`session_partitioning` :meth:`.Session.bind_mapper` :meth:`.Session.bind_table` :meth:`.Session.get_bind` :param \class_: Specify an alternate class other than ``sqlalchemy.orm.session.Session`` which should be used by the returned class. This is the only argument that is local to the :class:`.sessionmaker` function, and is not sent directly to the constructor for ``Session``. :param enable_baked_queries: legacy; defaults to ``True``. A parameter consumed by the :mod:`sqlalchemy.ext.baked` extension to determine if "baked queries" should be cached, as is the normal operation of this extension. When set to ``False``, caching as used by this particular extension is disabled. .. versionchanged:: 1.4 The ``sqlalchemy.ext.baked`` extension is legacy and is not used by any of SQLAlchemy's internals. This flag therefore only affects applications that are making explicit use of this extension within their own code. :param expire_on_commit: Defaults to ``True``. When ``True``, all instances will be fully expired after each :meth:`~.commit`, so that all attribute/object access subsequent to a completed transaction will load from the most recent database state. .. seealso:: :ref:`session_committing` :param future: Deprecated; this flag is always True. .. seealso:: :ref:`migration_20_toplevel` :param info: optional dictionary of arbitrary data to be associated with this :class:`.Session`. Is available via the :attr:`.Session.info` attribute. Note the dictionary is copied at construction time so that modifications to the per- :class:`.Session` dictionary will be local to that :class:`.Session`. :param query_cls: Class which should be used to create new Query objects, as returned by the :meth:`~.Session.query` method. Defaults to :class:`_query.Query`. :param twophase: When ``True``, all transactions will be started as a "two phase" transaction, i.e. using the "two phase" semantics of the database in use along with an XID. During a :meth:`~.commit`, after :meth:`~.flush` has been issued for all attached databases, the :meth:`~.TwoPhaseTransaction.prepare` method on each database's :class:`.TwoPhaseTransaction` will be called. This allows each database to roll back the entire transaction, before each transaction is committed. :param autocommit: the "autocommit" keyword is present for backwards compatibility but must remain at its default value of ``False``. :param join_transaction_mode: Describes the transactional behavior to take when a given bind is a :class:`_engine.Connection` that has already begun a transaction outside the scope of this :class:`_orm.Session`; in other words the :meth:`_engine.Connection.in_transaction()` method returns True. The following behaviors only take effect when the :class:`_orm.Session` **actually makes use of the connection given**; that is, a method such as :meth:`_orm.Session.execute`, :meth:`_orm.Session.connection`, etc. are actually invoked: * ``"conditional_savepoint"`` - this is the default. if the given :class:`_engine.Connection` is begun within a transaction but does not have a SAVEPOINT, then ``"rollback_only"`` is used. If the :class:`_engine.Connection` is additionally within a SAVEPOINT, in other words :meth:`_engine.Connection.in_nested_transaction()` method returns True, then ``"create_savepoint"`` is used. ``"conditional_savepoint"`` behavior attempts to make use of savepoints in order to keep the state of the existing transaction unchanged, but only if there is already a savepoint in progress; otherwise, it is not assumed that the backend in use has adequate support for SAVEPOINT, as availability of this feature varies. ``"conditional_savepoint"`` also seeks to establish approximate backwards compatibility with previous :class:`_orm.Session` behavior, for applications that are not setting a specific mode. It is recommended that one of the explicit settings be used. * ``"create_savepoint"`` - the :class:`_orm.Session` will use :meth:`_engine.Connection.begin_nested()` in all cases to create its own transaction. This transaction by its nature rides "on top" of any existing transaction that's opened on the given :class:`_engine.Connection`; if the underlying database and the driver in use has full, non-broken support for SAVEPOINT, the external transaction will remain unaffected throughout the lifespan of the :class:`_orm.Session`. The ``"create_savepoint"`` mode is the most useful for integrating a :class:`_orm.Session` into a test suite where an externally initiated transaction should remain unaffected; however, it relies on proper SAVEPOINT support from the underlying driver and database. .. tip:: When using SQLite, the SQLite driver included through Python 3.11 does not handle SAVEPOINTs correctly in all cases without workarounds. See the sections :ref:`pysqlite_serializable` and :ref:`aiosqlite_serializable` for details on current workarounds. * ``"control_fully"`` - the :class:`_orm.Session` will take control of the given transaction as its own; :meth:`_orm.Session.commit` will call ``.commit()`` on the transaction, :meth:`_orm.Session.rollback` will call ``.rollback()`` on the transaction, :meth:`_orm.Session.close` will call ``.rollback`` on the transaction. .. tip:: This mode of use is equivalent to how SQLAlchemy 1.4 would handle a :class:`_engine.Connection` given with an existing SAVEPOINT (i.e. :meth:`_engine.Connection.begin_nested`); the :class:`_orm.Session` would take full control of the existing SAVEPOINT. * ``"rollback_only"`` - the :class:`_orm.Session` will take control of the given transaction for ``.rollback()`` calls only; ``.commit()`` calls will not be propagated to the given transaction. ``.close()`` calls will have no effect on the given transaction. .. tip:: This mode of use is equivalent to how SQLAlchemy 1.4 would handle a :class:`_engine.Connection` given with an existing regular database transaction (i.e. :meth:`_engine.Connection.begin`); the :class:`_orm.Session` would propagate :meth:`_orm.Session.rollback` calls to the underlying transaction, but not :meth:`_orm.Session.commit` or :meth:`_orm.Session.close` calls. .. versionadded:: 2.0.0rc1 :param close_resets_only: Defaults to ``True``. Determines if the session should reset itself after calling ``.close()`` or should pass in a no longer usable state, disabling re-use. .. versionadded:: 2.0.22 added flag ``close_resets_only``. A future SQLAlchemy version may change the default value of this flag to ``False``. .. seealso:: :ref:`session_closing` - Detail on the semantics of :meth:`_orm.Session.close` and :meth:`_orm.Session.reset`. """ # noqa # considering allowing the "autocommit" keyword to still be accepted # as long as it's False, so that external test suites, oslo.db etc # continue to function as the argument appears to be passed in lots # of cases including in our own test suite if autocommit: raise sa_exc.ArgumentError( "autocommit=True is no longer supported" ) self.identity_map = identity.WeakInstanceDict() if not future: raise sa_exc.ArgumentError( "The 'future' parameter passed to " "Session() may only be set to True." ) self._new = {} # InstanceState->object, strong refs object self._deleted = {} # same self.bind = bind self.__binds = {} self._flushing = False self._warn_on_events = False self._transaction = None self._nested_transaction = None self.hash_key = _new_sessionid() self.autobegin = autobegin self.autoflush = autoflush self.expire_on_commit = expire_on_commit self.enable_baked_queries = enable_baked_queries # the idea is that at some point NO_ARG will warn that in the future # the default will switch to close_resets_only=False. if close_resets_only in (True, _NoArg.NO_ARG): self._close_state = _SessionCloseState.CLOSE_IS_RESET else: self._close_state = _SessionCloseState.ACTIVE if ( join_transaction_mode and join_transaction_mode not in JoinTransactionMode.__args__ # type: ignore ): raise sa_exc.ArgumentError( f"invalid selection for join_transaction_mode: " f'"{join_transaction_mode}"' ) self.join_transaction_mode = join_transaction_mode self.twophase = twophase self._query_cls = query_cls if query_cls else query.Query if info: self.info.update(info) if binds is not None: for key, bind in binds.items(): self._add_bind(key, bind) _sessions[self.hash_key] = self # used by sqlalchemy.engine.util.TransactionalContext _trans_context_manager: Optional[TransactionalContext] = None connection_callable: Optional[_ConnectionCallableProto] = None def __enter__(self: _S) -> _S: return self def __exit__(self, type_: Any, value: Any, traceback: Any) -> None: self.close() @contextlib.contextmanager def _maker_context_manager(self: _S) -> Iterator[_S]: with self: with self.begin(): yield self def in_transaction(self) -> bool: """Return True if this :class:`_orm.Session` has begun a transaction. .. versionadded:: 1.4 .. seealso:: :attr:`_orm.Session.is_active` """ return self._transaction is not None def in_nested_transaction(self) -> bool: """Return True if this :class:`_orm.Session` has begun a nested transaction, e.g. SAVEPOINT. .. versionadded:: 1.4 """ return self._nested_transaction is not None def get_transaction(self) -> Optional[SessionTransaction]: """Return the current root transaction in progress, if any. .. versionadded:: 1.4 """ trans = self._transaction while trans is not None and trans._parent is not None: trans = trans._parent return trans def get_nested_transaction(self) -> Optional[SessionTransaction]: """Return the current nested transaction in progress, if any. .. versionadded:: 1.4 """ return self._nested_transaction @util.memoized_property def info(self) -> _InfoType: """A user-modifiable dictionary. The initial value of this dictionary can be populated using the ``info`` argument to the :class:`.Session` constructor or :class:`.sessionmaker` constructor or factory methods. The dictionary here is always local to this :class:`.Session` and can be modified independently of all other :class:`.Session` objects. """ return {} def _autobegin_t(self, begin: bool = False) -> SessionTransaction: if self._transaction is None: if not begin and not self.autobegin: raise sa_exc.InvalidRequestError( "Autobegin is disabled on this Session; please call " "session.begin() to start a new transaction" ) trans = SessionTransaction( self, ( SessionTransactionOrigin.BEGIN if begin else SessionTransactionOrigin.AUTOBEGIN ), ) assert self._transaction is trans return trans return self._transaction def begin(self, nested: bool = False) -> SessionTransaction: """Begin a transaction, or nested transaction, on this :class:`.Session`, if one is not already begun. The :class:`_orm.Session` object features **autobegin** behavior, so that normally it is not necessary to call the :meth:`_orm.Session.begin` method explicitly. However, it may be used in order to control the scope of when the transactional state is begun. When used to begin the outermost transaction, an error is raised if this :class:`.Session` is already inside of a transaction. :param nested: if True, begins a SAVEPOINT transaction and is equivalent to calling :meth:`~.Session.begin_nested`. For documentation on SAVEPOINT transactions, please see :ref:`session_begin_nested`. :return: the :class:`.SessionTransaction` object. Note that :class:`.SessionTransaction` acts as a Python context manager, allowing :meth:`.Session.begin` to be used in a "with" block. See :ref:`session_explicit_begin` for an example. .. seealso:: :ref:`session_autobegin` :ref:`unitofwork_transaction` :meth:`.Session.begin_nested` """ trans = self._transaction if trans is None: trans = self._autobegin_t(begin=True) if not nested: return trans assert trans is not None if nested: trans = trans._begin(nested=nested) assert self._transaction is trans self._nested_transaction = trans else: raise sa_exc.InvalidRequestError( "A transaction is already begun on this Session." ) return trans # needed for __enter__/__exit__ hook def begin_nested(self) -> SessionTransaction: """Begin a "nested" transaction on this Session, e.g. SAVEPOINT. The target database(s) and associated drivers must support SQL SAVEPOINT for this method to function correctly. For documentation on SAVEPOINT transactions, please see :ref:`session_begin_nested`. :return: the :class:`.SessionTransaction` object. Note that :class:`.SessionTransaction` acts as a context manager, allowing :meth:`.Session.begin_nested` to be used in a "with" block. See :ref:`session_begin_nested` for a usage example. .. seealso:: :ref:`session_begin_nested` :ref:`pysqlite_serializable` - special workarounds required with the SQLite driver in order for SAVEPOINT to work correctly. For asyncio use cases, see the section :ref:`aiosqlite_serializable`. """ return self.begin(nested=True) def rollback(self) -> None: """Rollback the current transaction in progress. If no transaction is in progress, this method is a pass-through. The method always rolls back the topmost database transaction, discarding any nested transactions that may be in progress. .. seealso:: :ref:`session_rollback` :ref:`unitofwork_transaction` """ if self._transaction is None: pass else: self._transaction.rollback(_to_root=True) def commit(self) -> None: """Flush pending changes and commit the current transaction. When the COMMIT operation is complete, all objects are fully :term:`expired`, erasing their internal contents, which will be automatically re-loaded when the objects are next accessed. In the interim, these objects are in an expired state and will not function if they are :term:`detached` from the :class:`.Session`. Additionally, this re-load operation is not supported when using asyncio-oriented APIs. The :paramref:`.Session.expire_on_commit` parameter may be used to disable this behavior. When there is no transaction in place for the :class:`.Session`, indicating that no operations were invoked on this :class:`.Session` since the previous call to :meth:`.Session.commit`, the method will begin and commit an internal-only "logical" transaction, that does not normally affect the database unless pending flush changes were detected, but will still invoke event handlers and object expiration rules. The outermost database transaction is committed unconditionally, automatically releasing any SAVEPOINTs in effect. .. seealso:: :ref:`session_committing` :ref:`unitofwork_transaction` :ref:`asyncio_orm_avoid_lazyloads` """ trans = self._transaction if trans is None: trans = self._autobegin_t() trans.commit(_to_root=True) def prepare(self) -> None: """Prepare the current transaction in progress for two phase commit. If no transaction is in progress, this method raises an :exc:`~sqlalchemy.exc.InvalidRequestError`. Only root transactions of two phase sessions can be prepared. If the current transaction is not such, an :exc:`~sqlalchemy.exc.InvalidRequestError` is raised. """ trans = self._transaction if trans is None: trans = self._autobegin_t() trans.prepare() def connection( self, bind_arguments: Optional[_BindArguments] = None, execution_options: Optional[CoreExecuteOptionsParameter] = None, ) -> Connection: r"""Return a :class:`_engine.Connection` object corresponding to this :class:`.Session` object's transactional state. Either the :class:`_engine.Connection` corresponding to the current transaction is returned, or if no transaction is in progress, a new one is begun and the :class:`_engine.Connection` returned (note that no transactional state is established with the DBAPI until the first SQL statement is emitted). Ambiguity in multi-bind or unbound :class:`.Session` objects can be resolved through any of the optional keyword arguments. This ultimately makes usage of the :meth:`.get_bind` method for resolution. :param bind_arguments: dictionary of bind arguments. May include "mapper", "bind", "clause", other custom arguments that are passed to :meth:`.Session.get_bind`. :param execution_options: a dictionary of execution options that will be passed to :meth:`_engine.Connection.execution_options`, **when the connection is first procured only**. If the connection is already present within the :class:`.Session`, a warning is emitted and the arguments are ignored. .. seealso:: :ref:`session_transaction_isolation` """ if bind_arguments: bind = bind_arguments.pop("bind", None) if bind is None: bind = self.get_bind(**bind_arguments) else: bind = self.get_bind() return self._connection_for_bind( bind, execution_options=execution_options, ) def _connection_for_bind( self, engine: _SessionBind, execution_options: Optional[CoreExecuteOptionsParameter] = None, **kw: Any, ) -> Connection: TransactionalContext._trans_ctx_check(self) trans = self._transaction if trans is None: trans = self._autobegin_t() return trans._connection_for_bind(engine, execution_options) @overload def _execute_internal( self, statement: Executable, params: Optional[_CoreSingleExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, _parent_execute_state: Optional[Any] = None, _add_event: Optional[Any] = None, _scalar_result: Literal[True] = ..., ) -> Any: ... @overload def _execute_internal( self, statement: Executable, params: Optional[_CoreAnyExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, _parent_execute_state: Optional[Any] = None, _add_event: Optional[Any] = None, _scalar_result: bool = ..., ) -> Result[Any]: ... def _execute_internal( self, statement: Executable, params: Optional[_CoreAnyExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, _parent_execute_state: Optional[Any] = None, _add_event: Optional[Any] = None, _scalar_result: bool = False, ) -> Any: statement = coercions.expect(roles.StatementRole, statement) if not bind_arguments: bind_arguments = {} else: bind_arguments = dict(bind_arguments) if ( statement._propagate_attrs.get("compile_state_plugin", None) == "orm" ): compile_state_cls = CompileState._get_plugin_class_for_plugin( statement, "orm" ) if TYPE_CHECKING: assert isinstance( compile_state_cls, context.AbstractORMCompileState ) else: compile_state_cls = None bind_arguments.setdefault("clause", statement) execution_options = util.coerce_to_immutabledict(execution_options) if _parent_execute_state: events_todo = _parent_execute_state._remaining_events() else: events_todo = self.dispatch.do_orm_execute if _add_event: events_todo = list(events_todo) + [_add_event] if events_todo: if compile_state_cls is not None: # for event handlers, do the orm_pre_session_exec # pass ahead of the event handlers, so that things like # .load_options, .update_delete_options etc. are populated. # is_pre_event=True allows the hook to hold off on things # it doesn't want to do twice, including autoflush as well # as "pre fetch" for DML, etc. ( statement, execution_options, ) = compile_state_cls.orm_pre_session_exec( self, statement, params, execution_options, bind_arguments, True, ) orm_exec_state = ORMExecuteState( self, statement, params, execution_options, bind_arguments, compile_state_cls, events_todo, ) for idx, fn in enumerate(events_todo): orm_exec_state._starting_event_idx = idx fn_result: Optional[Result[Any]] = fn(orm_exec_state) if fn_result: if _scalar_result: return fn_result.scalar() else: return fn_result statement = orm_exec_state.statement execution_options = orm_exec_state.local_execution_options if compile_state_cls is not None: # now run orm_pre_session_exec() "for real". if there were # event hooks, this will re-run the steps that interpret # new execution_options into load_options / update_delete_options, # which we assume the event hook might have updated. # autoflush will also be invoked in this step if enabled. ( statement, execution_options, ) = compile_state_cls.orm_pre_session_exec( self, statement, params, execution_options, bind_arguments, False, ) bind = self.get_bind(**bind_arguments) conn = self._connection_for_bind(bind) if _scalar_result and not compile_state_cls: if TYPE_CHECKING: params = cast(_CoreSingleExecuteParams, params) return conn.scalar( statement, params or {}, execution_options=execution_options ) if compile_state_cls: result: Result[Any] = compile_state_cls.orm_execute_statement( self, statement, params or {}, execution_options, bind_arguments, conn, ) else: result = conn.execute( statement, params or {}, execution_options=execution_options ) if _scalar_result: return result.scalar() else: return result @overload def execute( self, statement: TypedReturnsRows[_T], params: Optional[_CoreAnyExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, _parent_execute_state: Optional[Any] = None, _add_event: Optional[Any] = None, ) -> Result[_T]: ... @overload def execute( self, statement: UpdateBase, params: Optional[_CoreAnyExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, _parent_execute_state: Optional[Any] = None, _add_event: Optional[Any] = None, ) -> CursorResult[Any]: ... @overload def execute( self, statement: Executable, params: Optional[_CoreAnyExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, _parent_execute_state: Optional[Any] = None, _add_event: Optional[Any] = None, ) -> Result[Any]: ... def execute( self, statement: Executable, params: Optional[_CoreAnyExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, _parent_execute_state: Optional[Any] = None, _add_event: Optional[Any] = None, ) -> Result[Any]: r"""Execute a SQL expression construct. Returns a :class:`_engine.Result` object representing results of the statement execution. E.g.:: from sqlalchemy import select result = session.execute(select(User).where(User.id == 5)) The API contract of :meth:`_orm.Session.execute` is similar to that of :meth:`_engine.Connection.execute`, the :term:`2.0 style` version of :class:`_engine.Connection`. .. versionchanged:: 1.4 the :meth:`_orm.Session.execute` method is now the primary point of ORM statement execution when using :term:`2.0 style` ORM usage. :param statement: An executable statement (i.e. an :class:`.Executable` expression such as :func:`_expression.select`). :param params: Optional dictionary, or list of dictionaries, containing bound parameter values. If a single dictionary, single-row execution occurs; if a list of dictionaries, an "executemany" will be invoked. The keys in each dictionary must correspond to parameter names present in the statement. :param execution_options: optional dictionary of execution options, which will be associated with the statement execution. This dictionary can provide a subset of the options that are accepted by :meth:`_engine.Connection.execution_options`, and may also provide additional options understood only in an ORM context. .. seealso:: :ref:`orm_queryguide_execution_options` - ORM-specific execution options :param bind_arguments: dictionary of additional arguments to determine the bind. May include "mapper", "bind", or other custom arguments. Contents of this dictionary are passed to the :meth:`.Session.get_bind` method. :return: a :class:`_engine.Result` object. """ return self._execute_internal( statement, params, execution_options=execution_options, bind_arguments=bind_arguments, _parent_execute_state=_parent_execute_state, _add_event=_add_event, ) @overload def scalar( self, statement: TypedReturnsRows[Tuple[_T]], params: Optional[_CoreSingleExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, **kw: Any, ) -> Optional[_T]: ... @overload def scalar( self, statement: Executable, params: Optional[_CoreSingleExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, **kw: Any, ) -> Any: ... def scalar( self, statement: Executable, params: Optional[_CoreSingleExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, **kw: Any, ) -> Any: """Execute a statement and return a scalar result. Usage and parameters are the same as that of :meth:`_orm.Session.execute`; the return result is a scalar Python value. """ return self._execute_internal( statement, params, execution_options=execution_options, bind_arguments=bind_arguments, _scalar_result=True, **kw, ) @overload def scalars( self, statement: TypedReturnsRows[Tuple[_T]], params: Optional[_CoreAnyExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, **kw: Any, ) -> ScalarResult[_T]: ... @overload def scalars( self, statement: Executable, params: Optional[_CoreAnyExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, **kw: Any, ) -> ScalarResult[Any]: ... def scalars( self, statement: Executable, params: Optional[_CoreAnyExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, **kw: Any, ) -> ScalarResult[Any]: """Execute a statement and return the results as scalars. Usage and parameters are the same as that of :meth:`_orm.Session.execute`; the return result is a :class:`_result.ScalarResult` filtering object which will return single elements rather than :class:`_row.Row` objects. :return: a :class:`_result.ScalarResult` object .. versionadded:: 1.4.24 Added :meth:`_orm.Session.scalars` .. versionadded:: 1.4.26 Added :meth:`_orm.scoped_session.scalars` .. seealso:: :ref:`orm_queryguide_select_orm_entities` - contrasts the behavior of :meth:`_orm.Session.execute` to :meth:`_orm.Session.scalars` """ return self._execute_internal( statement, params=params, execution_options=execution_options, bind_arguments=bind_arguments, _scalar_result=False, # mypy appreciates this **kw, ).scalars() def close(self) -> None: """Close out the transactional resources and ORM objects used by this :class:`_orm.Session`. This expunges all ORM objects associated with this :class:`_orm.Session`, ends any transaction in progress and :term:`releases` any :class:`_engine.Connection` objects which this :class:`_orm.Session` itself has checked out from associated :class:`_engine.Engine` objects. The operation then leaves the :class:`_orm.Session` in a state which it may be used again. .. tip:: In the default running mode the :meth:`_orm.Session.close` method **does not prevent the Session from being used again**. The :class:`_orm.Session` itself does not actually have a distinct "closed" state; it merely means the :class:`_orm.Session` will release all database connections and ORM objects. Setting the parameter :paramref:`_orm.Session.close_resets_only` to ``False`` will instead make the ``close`` final, meaning that any further action on the session will be forbidden. .. versionchanged:: 1.4 The :meth:`.Session.close` method does not immediately create a new :class:`.SessionTransaction` object; instead, the new :class:`.SessionTransaction` is created only if the :class:`.Session` is used again for a database operation. .. seealso:: :ref:`session_closing` - detail on the semantics of :meth:`_orm.Session.close` and :meth:`_orm.Session.reset`. :meth:`_orm.Session.reset` - a similar method that behaves like ``close()`` with the parameter :paramref:`_orm.Session.close_resets_only` set to ``True``. """ self._close_impl(invalidate=False) def reset(self) -> None: """Close out the transactional resources and ORM objects used by this :class:`_orm.Session`, resetting the session to its initial state. This method provides for same "reset-only" behavior that the :meth:`_orm.Session.close` method has provided historically, where the state of the :class:`_orm.Session` is reset as though the object were brand new, and ready to be used again. This method may then be useful for :class:`_orm.Session` objects which set :paramref:`_orm.Session.close_resets_only` to ``False``, so that "reset only" behavior is still available. .. versionadded:: 2.0.22 .. seealso:: :ref:`session_closing` - detail on the semantics of :meth:`_orm.Session.close` and :meth:`_orm.Session.reset`. :meth:`_orm.Session.close` - a similar method will additionally prevent re-use of the Session when the parameter :paramref:`_orm.Session.close_resets_only` is set to ``False``. """ self._close_impl(invalidate=False, is_reset=True) def invalidate(self) -> None: """Close this Session, using connection invalidation. This is a variant of :meth:`.Session.close` that will additionally ensure that the :meth:`_engine.Connection.invalidate` method will be called on each :class:`_engine.Connection` object that is currently in use for a transaction (typically there is only one connection unless the :class:`_orm.Session` is used with multiple engines). This can be called when the database is known to be in a state where the connections are no longer safe to be used. Below illustrates a scenario when using `gevent <https://www.gevent.org/>`_, which can produce ``Timeout`` exceptions that may mean the underlying connection should be discarded:: import gevent try: sess = Session() sess.add(User()) sess.commit() except gevent.Timeout: sess.invalidate() raise except: sess.rollback() raise The method additionally does everything that :meth:`_orm.Session.close` does, including that all ORM objects are expunged. """ self._close_impl(invalidate=True) def _close_impl(self, invalidate: bool, is_reset: bool = False) -> None: if not is_reset and self._close_state is _SessionCloseState.ACTIVE: self._close_state = _SessionCloseState.CLOSED self.expunge_all() if self._transaction is not None: for transaction in self._transaction._iterate_self_and_parents(): transaction.close(invalidate) def expunge_all(self) -> None: """Remove all object instances from this ``Session``. This is equivalent to calling ``expunge(obj)`` on all objects in this ``Session``. """ all_states = self.identity_map.all_states() + list(self._new) self.identity_map._kill() self.identity_map = identity.WeakInstanceDict() self._new = {} self._deleted = {} statelib.InstanceState._detach_states(all_states, self) def _add_bind(self, key: _SessionBindKey, bind: _SessionBind) -> None: try: insp = inspect(key) except sa_exc.NoInspectionAvailable as err: if not isinstance(key, type): raise sa_exc.ArgumentError( "Not an acceptable bind target: %s" % key ) from err else: self.__binds[key] = bind else: if TYPE_CHECKING: assert isinstance(insp, Inspectable) if isinstance(insp, TableClause): self.__binds[insp] = bind elif insp_is_mapper(insp): self.__binds[insp.class_] = bind for _selectable in insp._all_tables: self.__binds[_selectable] = bind else: raise sa_exc.ArgumentError( "Not an acceptable bind target: %s" % key ) def bind_mapper( self, mapper: _EntityBindKey[_O], bind: _SessionBind ) -> None: """Associate a :class:`_orm.Mapper` or arbitrary Python class with a "bind", e.g. an :class:`_engine.Engine` or :class:`_engine.Connection`. The given entity is added to a lookup used by the :meth:`.Session.get_bind` method. :param mapper: a :class:`_orm.Mapper` object, or an instance of a mapped class, or any Python class that is the base of a set of mapped classes. :param bind: an :class:`_engine.Engine` or :class:`_engine.Connection` object. .. seealso:: :ref:`session_partitioning` :paramref:`.Session.binds` :meth:`.Session.bind_table` """ self._add_bind(mapper, bind) def bind_table(self, table: TableClause, bind: _SessionBind) -> None: """Associate a :class:`_schema.Table` with a "bind", e.g. an :class:`_engine.Engine` or :class:`_engine.Connection`. The given :class:`_schema.Table` is added to a lookup used by the :meth:`.Session.get_bind` method. :param table: a :class:`_schema.Table` object, which is typically the target of an ORM mapping, or is present within a selectable that is mapped. :param bind: an :class:`_engine.Engine` or :class:`_engine.Connection` object. .. seealso:: :ref:`session_partitioning` :paramref:`.Session.binds` :meth:`.Session.bind_mapper` """ self._add_bind(table, bind) def get_bind( self, mapper: Optional[_EntityBindKey[_O]] = None, *, clause: Optional[ClauseElement] = None, bind: Optional[_SessionBind] = None, _sa_skip_events: Optional[bool] = None, _sa_skip_for_implicit_returning: bool = False, **kw: Any, ) -> Union[Engine, Connection]: """Return a "bind" to which this :class:`.Session` is bound. The "bind" is usually an instance of :class:`_engine.Engine`, except in the case where the :class:`.Session` has been explicitly bound directly to a :class:`_engine.Connection`. For a multiply-bound or unbound :class:`.Session`, the ``mapper`` or ``clause`` arguments are used to determine the appropriate bind to return. Note that the "mapper" argument is usually present when :meth:`.Session.get_bind` is called via an ORM operation such as a :meth:`.Session.query`, each individual INSERT/UPDATE/DELETE operation within a :meth:`.Session.flush`, call, etc. The order of resolution is: 1. if mapper given and :paramref:`.Session.binds` is present, locate a bind based first on the mapper in use, then on the mapped class in use, then on any base classes that are present in the ``__mro__`` of the mapped class, from more specific superclasses to more general. 2. if clause given and ``Session.binds`` is present, locate a bind based on :class:`_schema.Table` objects found in the given clause present in ``Session.binds``. 3. if ``Session.binds`` is present, return that. 4. if clause given, attempt to return a bind linked to the :class:`_schema.MetaData` ultimately associated with the clause. 5. if mapper given, attempt to return a bind linked to the :class:`_schema.MetaData` ultimately associated with the :class:`_schema.Table` or other selectable to which the mapper is mapped. 6. No bind can be found, :exc:`~sqlalchemy.exc.UnboundExecutionError` is raised. Note that the :meth:`.Session.get_bind` method can be overridden on a user-defined subclass of :class:`.Session` to provide any kind of bind resolution scheme. See the example at :ref:`session_custom_partitioning`. :param mapper: Optional mapped class or corresponding :class:`_orm.Mapper` instance. The bind can be derived from a :class:`_orm.Mapper` first by consulting the "binds" map associated with this :class:`.Session`, and secondly by consulting the :class:`_schema.MetaData` associated with the :class:`_schema.Table` to which the :class:`_orm.Mapper` is mapped for a bind. :param clause: A :class:`_expression.ClauseElement` (i.e. :func:`_expression.select`, :func:`_expression.text`, etc.). If the ``mapper`` argument is not present or could not produce a bind, the given expression construct will be searched for a bound element, typically a :class:`_schema.Table` associated with bound :class:`_schema.MetaData`. .. seealso:: :ref:`session_partitioning` :paramref:`.Session.binds` :meth:`.Session.bind_mapper` :meth:`.Session.bind_table` """ # this function is documented as a subclassing hook, so we have # to call this method even if the return is simple if bind: return bind elif not self.__binds and self.bind: # simplest and most common case, we have a bind and no # per-mapper/table binds, we're done return self.bind # we don't have self.bind and either have self.__binds # or we don't have self.__binds (which is legacy). Look at the # mapper and the clause if mapper is None and clause is None: if self.bind: return self.bind else: raise sa_exc.UnboundExecutionError( "This session is not bound to a single Engine or " "Connection, and no context was provided to locate " "a binding." ) # look more closely at the mapper. if mapper is not None: try: inspected_mapper = inspect(mapper) except sa_exc.NoInspectionAvailable as err: if isinstance(mapper, type): raise exc.UnmappedClassError(mapper) from err else: raise else: inspected_mapper = None # match up the mapper or clause in the __binds if self.__binds: # matching mappers and selectables to entries in the # binds dictionary; supported use case. if inspected_mapper: for cls in inspected_mapper.class_.__mro__: if cls in self.__binds: return self.__binds[cls] if clause is None: clause = inspected_mapper.persist_selectable if clause is not None: plugin_subject = clause._propagate_attrs.get( "plugin_subject", None ) if plugin_subject is not None: for cls in plugin_subject.mapper.class_.__mro__: if cls in self.__binds: return self.__binds[cls] for obj in visitors.iterate(clause): if obj in self.__binds: if TYPE_CHECKING: assert isinstance(obj, Table) return self.__binds[obj] # none of the __binds matched, but we have a fallback bind. # return that if self.bind: return self.bind context = [] if inspected_mapper is not None: context.append(f"mapper {inspected_mapper}") if clause is not None: context.append("SQL expression") raise sa_exc.UnboundExecutionError( f"Could not locate a bind configured on " f'{", ".join(context)} or this Session.' ) @overload def query(self, _entity: _EntityType[_O]) -> Query[_O]: ... @overload def query( self, _colexpr: TypedColumnsClauseRole[_T] ) -> RowReturningQuery[Tuple[_T]]: ... # START OVERLOADED FUNCTIONS self.query RowReturningQuery 2-8 # code within this block is **programmatically, # statically generated** by tools/generate_tuple_map_overloads.py @overload def query( self, __ent0: _TCCA[_T0], __ent1: _TCCA[_T1] ) -> RowReturningQuery[Tuple[_T0, _T1]]: ... @overload def query( self, __ent0: _TCCA[_T0], __ent1: _TCCA[_T1], __ent2: _TCCA[_T2] ) -> RowReturningQuery[Tuple[_T0, _T1, _T2]]: ... @overload def query( self, __ent0: _TCCA[_T0], __ent1: _TCCA[_T1], __ent2: _TCCA[_T2], __ent3: _TCCA[_T3], ) -> RowReturningQuery[Tuple[_T0, _T1, _T2, _T3]]: ... @overload def query( self, __ent0: _TCCA[_T0], __ent1: _TCCA[_T1], __ent2: _TCCA[_T2], __ent3: _TCCA[_T3], __ent4: _TCCA[_T4], ) -> RowReturningQuery[Tuple[_T0, _T1, _T2, _T3, _T4]]: ... @overload def query( self, __ent0: _TCCA[_T0], __ent1: _TCCA[_T1], __ent2: _TCCA[_T2], __ent3: _TCCA[_T3], __ent4: _TCCA[_T4], __ent5: _TCCA[_T5], ) -> RowReturningQuery[Tuple[_T0, _T1, _T2, _T3, _T4, _T5]]: ... @overload def query( self, __ent0: _TCCA[_T0], __ent1: _TCCA[_T1], __ent2: _TCCA[_T2], __ent3: _TCCA[_T3], __ent4: _TCCA[_T4], __ent5: _TCCA[_T5], __ent6: _TCCA[_T6], ) -> RowReturningQuery[Tuple[_T0, _T1, _T2, _T3, _T4, _T5, _T6]]: ... @overload def query( self, __ent0: _TCCA[_T0], __ent1: _TCCA[_T1], __ent2: _TCCA[_T2], __ent3: _TCCA[_T3], __ent4: _TCCA[_T4], __ent5: _TCCA[_T5], __ent6: _TCCA[_T6], __ent7: _TCCA[_T7], ) -> RowReturningQuery[Tuple[_T0, _T1, _T2, _T3, _T4, _T5, _T6, _T7]]: ... # END OVERLOADED FUNCTIONS self.query @overload def query( self, *entities: _ColumnsClauseArgument[Any], **kwargs: Any ) -> Query[Any]: ... def query( self, *entities: _ColumnsClauseArgument[Any], **kwargs: Any ) -> Query[Any]: """Return a new :class:`_query.Query` object corresponding to this :class:`_orm.Session`. Note that the :class:`_query.Query` object is legacy as of SQLAlchemy 2.0; the :func:`_sql.select` construct is now used to construct ORM queries. .. seealso:: :ref:`unified_tutorial` :ref:`queryguide_toplevel` :ref:`query_api_toplevel` - legacy API doc """ return self._query_cls(entities, self, **kwargs) def _identity_lookup( self, mapper: Mapper[_O], primary_key_identity: Union[Any, Tuple[Any, ...]], identity_token: Any = None, passive: PassiveFlag = PassiveFlag.PASSIVE_OFF, lazy_loaded_from: Optional[InstanceState[Any]] = None, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, ) -> Union[Optional[_O], LoaderCallableStatus]: """Locate an object in the identity map. Given a primary key identity, constructs an identity key and then looks in the session's identity map. If present, the object may be run through unexpiration rules (e.g. load unloaded attributes, check if was deleted). e.g.:: obj = session._identity_lookup(inspect(SomeClass), (1,)) :param mapper: mapper in use :param primary_key_identity: the primary key we are searching for, as a tuple. :param identity_token: identity token that should be used to create the identity key. Used as is, however overriding subclasses can repurpose this in order to interpret the value in a special way, such as if None then look among multiple target tokens. :param passive: passive load flag passed to :func:`.loading.get_from_identity`, which impacts the behavior if the object is found; the object may be validated and/or unexpired if the flag allows for SQL to be emitted. :param lazy_loaded_from: an :class:`.InstanceState` that is specifically asking for this identity as a related identity. Used for sharding schemes where there is a correspondence between an object and a related object being lazy-loaded (or otherwise relationship-loaded). :return: None if the object is not found in the identity map, *or* if the object was unexpired and found to have been deleted. if passive flags disallow SQL and the object is expired, returns PASSIVE_NO_RESULT. In all other cases the instance is returned. .. versionchanged:: 1.4.0 - the :meth:`.Session._identity_lookup` method was moved from :class:`_query.Query` to :class:`.Session`, to avoid having to instantiate the :class:`_query.Query` object. """ key = mapper.identity_key_from_primary_key( primary_key_identity, identity_token=identity_token ) # work around: https://github.com/python/typing/discussions/1143 return_value = loading.get_from_identity(self, mapper, key, passive) return return_value @util.non_memoized_property @contextlib.contextmanager def no_autoflush(self) -> Iterator[Session]: """Return a context manager that disables autoflush. e.g.:: with session.no_autoflush: some_object = SomeClass() session.add(some_object) # won't autoflush some_object.related_thing = session.query(SomeRelated).first() Operations that proceed within the ``with:`` block will not be subject to flushes occurring upon query access. This is useful when initializing a series of objects which involve existing database queries, where the uncompleted object should not yet be flushed. """ autoflush = self.autoflush self.autoflush = False try: yield self finally: self.autoflush = autoflush @util.langhelpers.tag_method_for_warnings( "This warning originated from the Session 'autoflush' process, " "which was invoked automatically in response to a user-initiated " "operation. Consider using ``no_autoflush`` context manager if this " "warning happended while initializing objects.", sa_exc.SAWarning, ) def _autoflush(self) -> None: if self.autoflush and not self._flushing: try: self.flush() except sa_exc.StatementError as e: # note we are reraising StatementError as opposed to # raising FlushError with "chaining" to remain compatible # with code that catches StatementError, IntegrityError, # etc. e.add_detail( "raised as a result of Query-invoked autoflush; " "consider using a session.no_autoflush block if this " "flush is occurring prematurely" ) raise e.with_traceback(sys.exc_info()[2]) def refresh( self, instance: object, attribute_names: Optional[Iterable[str]] = None, with_for_update: ForUpdateParameter = None, ) -> None: """Expire and refresh attributes on the given instance. The selected attributes will first be expired as they would when using :meth:`_orm.Session.expire`; then a SELECT statement will be issued to the database to refresh column-oriented attributes with the current value available in the current transaction. :func:`_orm.relationship` oriented attributes will also be immediately loaded if they were already eagerly loaded on the object, using the same eager loading strategy that they were loaded with originally. .. versionadded:: 1.4 - the :meth:`_orm.Session.refresh` method can also refresh eagerly loaded attributes. :func:`_orm.relationship` oriented attributes that would normally load using the ``select`` (or "lazy") loader strategy will also load **if they are named explicitly in the attribute_names collection**, emitting a SELECT statement for the attribute using the ``immediate`` loader strategy. If lazy-loaded relationships are not named in :paramref:`_orm.Session.refresh.attribute_names`, then they remain as "lazy loaded" attributes and are not implicitly refreshed. .. versionchanged:: 2.0.4 The :meth:`_orm.Session.refresh` method will now refresh lazy-loaded :func:`_orm.relationship` oriented attributes for those which are named explicitly in the :paramref:`_orm.Session.refresh.attribute_names` collection. .. tip:: While the :meth:`_orm.Session.refresh` method is capable of refreshing both column and relationship oriented attributes, its primary focus is on refreshing of local column-oriented attributes on a single instance. For more open ended "refresh" functionality, including the ability to refresh the attributes on many objects at once while having explicit control over relationship loader strategies, use the :ref:`populate existing <orm_queryguide_populate_existing>` feature instead. Note that a highly isolated transaction will return the same values as were previously read in that same transaction, regardless of changes in database state outside of that transaction. Refreshing attributes usually only makes sense at the start of a transaction where database rows have not yet been accessed. :param attribute_names: optional. An iterable collection of string attribute names indicating a subset of attributes to be refreshed. :param with_for_update: optional boolean ``True`` indicating FOR UPDATE should be used, or may be a dictionary containing flags to indicate a more specific set of FOR UPDATE flags for the SELECT; flags should match the parameters of :meth:`_query.Query.with_for_update`. Supersedes the :paramref:`.Session.refresh.lockmode` parameter. .. seealso:: :ref:`session_expire` - introductory material :meth:`.Session.expire` :meth:`.Session.expire_all` :ref:`orm_queryguide_populate_existing` - allows any ORM query to refresh objects as they would be loaded normally. """ try: state = attributes.instance_state(instance) except exc.NO_STATE as err: raise exc.UnmappedInstanceError(instance) from err self._expire_state(state, attribute_names) # this autoflush previously used to occur as a secondary effect # of the load_on_ident below. Meaning we'd organize the SELECT # based on current DB pks, then flush, then if pks changed in that # flush, crash. this was unticketed but discovered as part of # #8703. So here, autoflush up front, dont autoflush inside # load_on_ident. self._autoflush() if with_for_update == {}: raise sa_exc.ArgumentError( "with_for_update should be the boolean value " "True, or a dictionary with options. " "A blank dictionary is ambiguous." ) with_for_update = ForUpdateArg._from_argument(with_for_update) stmt: Select[Any] = sql.select(object_mapper(instance)) if ( loading.load_on_ident( self, stmt, state.key, refresh_state=state, with_for_update=with_for_update, only_load_props=attribute_names, require_pk_cols=True, # technically unnecessary as we just did autoflush # above, however removes the additional unnecessary # call to _autoflush() no_autoflush=True, is_user_refresh=True, ) is None ): raise sa_exc.InvalidRequestError( "Could not refresh instance '%s'" % instance_str(instance) ) def expire_all(self) -> None: """Expires all persistent instances within this Session. When any attributes on a persistent instance is next accessed, a query will be issued using the :class:`.Session` object's current transactional context in order to load all expired attributes for the given instance. Note that a highly isolated transaction will return the same values as were previously read in that same transaction, regardless of changes in database state outside of that transaction. To expire individual objects and individual attributes on those objects, use :meth:`Session.expire`. The :class:`.Session` object's default behavior is to expire all state whenever the :meth:`Session.rollback` or :meth:`Session.commit` methods are called, so that new state can be loaded for the new transaction. For this reason, calling :meth:`Session.expire_all` is not usually needed, assuming the transaction is isolated. .. seealso:: :ref:`session_expire` - introductory material :meth:`.Session.expire` :meth:`.Session.refresh` :meth:`_orm.Query.populate_existing` """ for state in self.identity_map.all_states(): state._expire(state.dict, self.identity_map._modified) def expire( self, instance: object, attribute_names: Optional[Iterable[str]] = None ) -> None: """Expire the attributes on an instance. Marks the attributes of an instance as out of date. When an expired attribute is next accessed, a query will be issued to the :class:`.Session` object's current transactional context in order to load all expired attributes for the given instance. Note that a highly isolated transaction will return the same values as were previously read in that same transaction, regardless of changes in database state outside of that transaction. To expire all objects in the :class:`.Session` simultaneously, use :meth:`Session.expire_all`. The :class:`.Session` object's default behavior is to expire all state whenever the :meth:`Session.rollback` or :meth:`Session.commit` methods are called, so that new state can be loaded for the new transaction. For this reason, calling :meth:`Session.expire` only makes sense for the specific case that a non-ORM SQL statement was emitted in the current transaction. :param instance: The instance to be refreshed. :param attribute_names: optional list of string attribute names indicating a subset of attributes to be expired. .. seealso:: :ref:`session_expire` - introductory material :meth:`.Session.expire` :meth:`.Session.refresh` :meth:`_orm.Query.populate_existing` """ try: state = attributes.instance_state(instance) except exc.NO_STATE as err: raise exc.UnmappedInstanceError(instance) from err self._expire_state(state, attribute_names) def _expire_state( self, state: InstanceState[Any], attribute_names: Optional[Iterable[str]], ) -> None: self._validate_persistent(state) if attribute_names: state._expire_attributes(state.dict, attribute_names) else: # pre-fetch the full cascade since the expire is going to # remove associations cascaded = list( state.manager.mapper.cascade_iterator("refresh-expire", state) ) self._conditional_expire(state) for o, m, st_, dct_ in cascaded: self._conditional_expire(st_) def _conditional_expire( self, state: InstanceState[Any], autoflush: Optional[bool] = None ) -> None: """Expire a state if persistent, else expunge if pending""" if state.key: state._expire(state.dict, self.identity_map._modified) elif state in self._new: self._new.pop(state) state._detach(self) def expunge(self, instance: object) -> None: """Remove the `instance` from this ``Session``. This will free all internal references to the instance. Cascading will be applied according to the *expunge* cascade rule. """ try: state = attributes.instance_state(instance) except exc.NO_STATE as err: raise exc.UnmappedInstanceError(instance) from err if state.session_id is not self.hash_key: raise sa_exc.InvalidRequestError( "Instance %s is not present in this Session" % state_str(state) ) cascaded = list( state.manager.mapper.cascade_iterator("expunge", state) ) self._expunge_states([state] + [st_ for o, m, st_, dct_ in cascaded]) def _expunge_states( self, states: Iterable[InstanceState[Any]], to_transient: bool = False ) -> None: for state in states: if state in self._new: self._new.pop(state) elif self.identity_map.contains_state(state): self.identity_map.safe_discard(state) self._deleted.pop(state, None) elif self._transaction: # state is "detached" from being deleted, but still present # in the transaction snapshot self._transaction._deleted.pop(state, None) statelib.InstanceState._detach_states( states, self, to_transient=to_transient ) def _register_persistent(self, states: Set[InstanceState[Any]]) -> None: """Register all persistent objects from a flush. This is used both for pending objects moving to the persistent state as well as already persistent objects. """ pending_to_persistent = self.dispatch.pending_to_persistent or None for state in states: mapper = _state_mapper(state) # prevent against last minute dereferences of the object obj = state.obj() if obj is not None: instance_key = mapper._identity_key_from_state(state) if ( _none_set.intersection(instance_key[1]) and not mapper.allow_partial_pks or _none_set.issuperset(instance_key[1]) ): raise exc.FlushError( "Instance %s has a NULL identity key. If this is an " "auto-generated value, check that the database table " "allows generation of new primary key values, and " "that the mapped Column object is configured to " "expect these generated values. Ensure also that " "this flush() is not occurring at an inappropriate " "time, such as within a load() event." % state_str(state) ) if state.key is None: state.key = instance_key elif state.key != instance_key: # primary key switch. use safe_discard() in case another # state has already replaced this one in the identity # map (see test/orm/test_naturalpks.py ReversePKsTest) self.identity_map.safe_discard(state) trans = self._transaction assert trans is not None if state in trans._key_switches: orig_key = trans._key_switches[state][0] else: orig_key = state.key trans._key_switches[state] = ( orig_key, instance_key, ) state.key = instance_key # there can be an existing state in the identity map # that is replaced when the primary keys of two instances # are swapped; see test/orm/test_naturalpks.py -> test_reverse old = self.identity_map.replace(state) if ( old is not None and mapper._identity_key_from_state(old) == instance_key and old.obj() is not None ): util.warn( "Identity map already had an identity for %s, " "replacing it with newly flushed object. Are there " "load operations occurring inside of an event handler " "within the flush?" % (instance_key,) ) state._orphaned_outside_of_session = False statelib.InstanceState._commit_all_states( ((state, state.dict) for state in states), self.identity_map ) self._register_altered(states) if pending_to_persistent is not None: for state in states.intersection(self._new): pending_to_persistent(self, state) # remove from new last, might be the last strong ref for state in set(states).intersection(self._new): self._new.pop(state) def _register_altered(self, states: Iterable[InstanceState[Any]]) -> None: if self._transaction: for state in states: if state in self._new: self._transaction._new[state] = True else: self._transaction._dirty[state] = True def _remove_newly_deleted( self, states: Iterable[InstanceState[Any]] ) -> None: persistent_to_deleted = self.dispatch.persistent_to_deleted or None for state in states: if self._transaction: self._transaction._deleted[state] = True if persistent_to_deleted is not None: # get a strong reference before we pop out of # self._deleted obj = state.obj() # noqa self.identity_map.safe_discard(state) self._deleted.pop(state, None) state._deleted = True # can't call state._detach() here, because this state # is still in the transaction snapshot and needs to be # tracked as part of that if persistent_to_deleted is not None: persistent_to_deleted(self, state) def add(self, instance: object, _warn: bool = True) -> None: """Place an object into this :class:`_orm.Session`. Objects that are in the :term:`transient` state when passed to the :meth:`_orm.Session.add` method will move to the :term:`pending` state, until the next flush, at which point they will move to the :term:`persistent` state. Objects that are in the :term:`detached` state when passed to the :meth:`_orm.Session.add` method will move to the :term:`persistent` state directly. If the transaction used by the :class:`_orm.Session` is rolled back, objects which were transient when they were passed to :meth:`_orm.Session.add` will be moved back to the :term:`transient` state, and will no longer be present within this :class:`_orm.Session`. .. seealso:: :meth:`_orm.Session.add_all` :ref:`session_adding` - at :ref:`session_basics` """ if _warn and self._warn_on_events: self._flush_warning("Session.add()") try: state = attributes.instance_state(instance) except exc.NO_STATE as err: raise exc.UnmappedInstanceError(instance) from err self._save_or_update_state(state) def add_all(self, instances: Iterable[object]) -> None: """Add the given collection of instances to this :class:`_orm.Session`. See the documentation for :meth:`_orm.Session.add` for a general behavioral description. .. seealso:: :meth:`_orm.Session.add` :ref:`session_adding` - at :ref:`session_basics` """ if self._warn_on_events: self._flush_warning("Session.add_all()") for instance in instances: self.add(instance, _warn=False) def _save_or_update_state(self, state: InstanceState[Any]) -> None: state._orphaned_outside_of_session = False self._save_or_update_impl(state) mapper = _state_mapper(state) for o, m, st_, dct_ in mapper.cascade_iterator( "save-update", state, halt_on=self._contains_state ): self._save_or_update_impl(st_) def delete(self, instance: object) -> None: """Mark an instance as deleted. The object is assumed to be either :term:`persistent` or :term:`detached` when passed; after the method is called, the object will remain in the :term:`persistent` state until the next flush proceeds. During this time, the object will also be a member of the :attr:`_orm.Session.deleted` collection. When the next flush proceeds, the object will move to the :term:`deleted` state, indicating a ``DELETE`` statement was emitted for its row within the current transaction. When the transaction is successfully committed, the deleted object is moved to the :term:`detached` state and is no longer present within this :class:`_orm.Session`. .. seealso:: :ref:`session_deleting` - at :ref:`session_basics` """ if self._warn_on_events: self._flush_warning("Session.delete()") try: state = attributes.instance_state(instance) except exc.NO_STATE as err: raise exc.UnmappedInstanceError(instance) from err self._delete_impl(state, instance, head=True) def _delete_impl( self, state: InstanceState[Any], obj: object, head: bool ) -> None: if state.key is None: if head: raise sa_exc.InvalidRequestError( "Instance '%s' is not persisted" % state_str(state) ) else: return to_attach = self._before_attach(state, obj) if state in self._deleted: return self.identity_map.add(state) if to_attach: self._after_attach(state, obj) if head: # grab the cascades before adding the item to the deleted list # so that autoflush does not delete the item # the strong reference to the instance itself is significant here cascade_states = list( state.manager.mapper.cascade_iterator("delete", state) ) else: cascade_states = None self._deleted[state] = obj if head: if TYPE_CHECKING: assert cascade_states is not None for o, m, st_, dct_ in cascade_states: self._delete_impl(st_, o, False) def get( self, entity: _EntityBindKey[_O], ident: _PKIdentityArgument, *, options: Optional[Sequence[ORMOption]] = None, populate_existing: bool = False, with_for_update: ForUpdateParameter = None, identity_token: Optional[Any] = None, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, ) -> Optional[_O]: """Return an instance based on the given primary key identifier, or ``None`` if not found. E.g.:: my_user = session.get(User, 5) some_object = session.get(VersionedFoo, (5, 10)) some_object = session.get(VersionedFoo, {"id": 5, "version_id": 10}) .. versionadded:: 1.4 Added :meth:`_orm.Session.get`, which is moved from the now legacy :meth:`_orm.Query.get` method. :meth:`_orm.Session.get` is special in that it provides direct access to the identity map of the :class:`.Session`. If the given primary key identifier is present in the local identity map, the object is returned directly from this collection and no SQL is emitted, unless the object has been marked fully expired. If not present, a SELECT is performed in order to locate the object. :meth:`_orm.Session.get` also will perform a check if the object is present in the identity map and marked as expired - a SELECT is emitted to refresh the object as well as to ensure that the row is still present. If not, :class:`~sqlalchemy.orm.exc.ObjectDeletedError` is raised. :param entity: a mapped class or :class:`.Mapper` indicating the type of entity to be loaded. :param ident: A scalar, tuple, or dictionary representing the primary key. For a composite (e.g. multiple column) primary key, a tuple or dictionary should be passed. For a single-column primary key, the scalar calling form is typically the most expedient. If the primary key of a row is the value "5", the call looks like:: my_object = session.get(SomeClass, 5) The tuple form contains primary key values typically in the order in which they correspond to the mapped :class:`_schema.Table` object's primary key columns, or if the :paramref:`_orm.Mapper.primary_key` configuration parameter were used, in the order used for that parameter. For example, if the primary key of a row is represented by the integer digits "5, 10" the call would look like:: my_object = session.get(SomeClass, (5, 10)) The dictionary form should include as keys the mapped attribute names corresponding to each element of the primary key. If the mapped class has the attributes ``id``, ``version_id`` as the attributes which store the object's primary key value, the call would look like:: my_object = session.get(SomeClass, {"id": 5, "version_id": 10}) :param options: optional sequence of loader options which will be applied to the query, if one is emitted. :param populate_existing: causes the method to unconditionally emit a SQL query and refresh the object with the newly loaded data, regardless of whether or not the object is already present. :param with_for_update: optional boolean ``True`` indicating FOR UPDATE should be used, or may be a dictionary containing flags to indicate a more specific set of FOR UPDATE flags for the SELECT; flags should match the parameters of :meth:`_query.Query.with_for_update`. Supersedes the :paramref:`.Session.refresh.lockmode` parameter. :param execution_options: optional dictionary of execution options, which will be associated with the query execution if one is emitted. This dictionary can provide a subset of the options that are accepted by :meth:`_engine.Connection.execution_options`, and may also provide additional options understood only in an ORM context. .. versionadded:: 1.4.29 .. seealso:: :ref:`orm_queryguide_execution_options` - ORM-specific execution options :param bind_arguments: dictionary of additional arguments to determine the bind. May include "mapper", "bind", or other custom arguments. Contents of this dictionary are passed to the :meth:`.Session.get_bind` method. .. versionadded: 2.0.0rc1 :return: The object instance, or ``None``. """ # noqa: E501 return self._get_impl( entity, ident, loading.load_on_pk_identity, options=options, populate_existing=populate_existing, with_for_update=with_for_update, identity_token=identity_token, execution_options=execution_options, bind_arguments=bind_arguments, ) def get_one( self, entity: _EntityBindKey[_O], ident: _PKIdentityArgument, *, options: Optional[Sequence[ORMOption]] = None, populate_existing: bool = False, with_for_update: ForUpdateParameter = None, identity_token: Optional[Any] = None, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, ) -> _O: """Return exactly one instance based on the given primary key identifier, or raise an exception if not found. Raises :class:`_exc.NoResultFound` if the query selects no rows. For a detailed documentation of the arguments see the method :meth:`.Session.get`. .. versionadded:: 2.0.22 :return: The object instance. .. seealso:: :meth:`.Session.get` - equivalent method that instead returns ``None`` if no row was found with the provided primary key """ instance = self.get( entity, ident, options=options, populate_existing=populate_existing, with_for_update=with_for_update, identity_token=identity_token, execution_options=execution_options, bind_arguments=bind_arguments, ) if instance is None: raise sa_exc.NoResultFound( "No row was found when one was required" ) return instance def _get_impl( self, entity: _EntityBindKey[_O], primary_key_identity: _PKIdentityArgument, db_load_fn: Callable[..., _O], *, options: Optional[Sequence[ExecutableOption]] = None, populate_existing: bool = False, with_for_update: ForUpdateParameter = None, identity_token: Optional[Any] = None, execution_options: OrmExecuteOptionsParameter = util.EMPTY_DICT, bind_arguments: Optional[_BindArguments] = None, ) -> Optional[_O]: # convert composite types to individual args if ( is_composite_class(primary_key_identity) and type(primary_key_identity) in descriptor_props._composite_getters ): getter = descriptor_props._composite_getters[ type(primary_key_identity) ] primary_key_identity = getter(primary_key_identity) mapper: Optional[Mapper[_O]] = inspect(entity) if mapper is None or not mapper.is_mapper: raise sa_exc.ArgumentError( "Expected mapped class or mapper, got: %r" % entity ) is_dict = isinstance(primary_key_identity, dict) if not is_dict: primary_key_identity = util.to_list( primary_key_identity, default=[None] ) if len(primary_key_identity) != len(mapper.primary_key): raise sa_exc.InvalidRequestError( "Incorrect number of values in identifier to formulate " "primary key for session.get(); primary key columns " "are %s" % ",".join("'%s'" % c for c in mapper.primary_key) ) if is_dict: pk_synonyms = mapper._pk_synonyms if pk_synonyms: correct_keys = set(pk_synonyms).intersection( primary_key_identity ) if correct_keys: primary_key_identity = dict(primary_key_identity) for k in correct_keys: primary_key_identity[pk_synonyms[k]] = ( primary_key_identity[k] ) try: primary_key_identity = list( primary_key_identity[prop.key] for prop in mapper._identity_key_props ) except KeyError as err: raise sa_exc.InvalidRequestError( "Incorrect names of values in identifier to formulate " "primary key for session.get(); primary key attribute " "names are %s (synonym names are also accepted)" % ",".join( "'%s'" % prop.key for prop in mapper._identity_key_props ) ) from err if ( not populate_existing and not mapper.always_refresh and with_for_update is None ): instance = self._identity_lookup( mapper, primary_key_identity, identity_token=identity_token, execution_options=execution_options, bind_arguments=bind_arguments, ) if instance is not None: # reject calls for id in identity map but class # mismatch. if not isinstance(instance, mapper.class_): return None return instance # TODO: this was being tested before, but this is not possible assert instance is not LoaderCallableStatus.PASSIVE_CLASS_MISMATCH # set_label_style() not strictly necessary, however this will ensure # that tablename_colname style is used which at the moment is # asserted in a lot of unit tests :) load_options = context.QueryContext.default_load_options if populate_existing: load_options += {"_populate_existing": populate_existing} statement = sql.select(mapper).set_label_style( LABEL_STYLE_TABLENAME_PLUS_COL ) if with_for_update is not None: statement._for_update_arg = ForUpdateArg._from_argument( with_for_update ) if options: statement = statement.options(*options) return db_load_fn( self, statement, primary_key_identity, load_options=load_options, identity_token=identity_token, execution_options=execution_options, bind_arguments=bind_arguments, ) def merge( self, instance: _O, *, load: bool = True, options: Optional[Sequence[ORMOption]] = None, ) -> _O: """Copy the state of a given instance into a corresponding instance within this :class:`.Session`. :meth:`.Session.merge` examines the primary key attributes of the source instance, and attempts to reconcile it with an instance of the same primary key in the session. If not found locally, it attempts to load the object from the database based on primary key, and if none can be located, creates a new instance. The state of each attribute on the source instance is then copied to the target instance. The resulting target instance is then returned by the method; the original source instance is left unmodified, and un-associated with the :class:`.Session` if not already. This operation cascades to associated instances if the association is mapped with ``cascade="merge"``. See :ref:`unitofwork_merging` for a detailed discussion of merging. :param instance: Instance to be merged. :param load: Boolean, when False, :meth:`.merge` switches into a "high performance" mode which causes it to forego emitting history events as well as all database access. This flag is used for cases such as transferring graphs of objects into a :class:`.Session` from a second level cache, or to transfer just-loaded objects into the :class:`.Session` owned by a worker thread or process without re-querying the database. The ``load=False`` use case adds the caveat that the given object has to be in a "clean" state, that is, has no pending changes to be flushed - even if the incoming object is detached from any :class:`.Session`. This is so that when the merge operation populates local attributes and cascades to related objects and collections, the values can be "stamped" onto the target object as is, without generating any history or attribute events, and without the need to reconcile the incoming data with any existing related objects or collections that might not be loaded. The resulting objects from ``load=False`` are always produced as "clean", so it is only appropriate that the given objects should be "clean" as well, else this suggests a mis-use of the method. :param options: optional sequence of loader options which will be applied to the :meth:`_orm.Session.get` method when the merge operation loads the existing version of the object from the database. .. versionadded:: 1.4.24 .. seealso:: :func:`.make_transient_to_detached` - provides for an alternative means of "merging" a single object into the :class:`.Session` """ if self._warn_on_events: self._flush_warning("Session.merge()") _recursive: Dict[InstanceState[Any], object] = {} _resolve_conflict_map: Dict[_IdentityKeyType[Any], object] = {} if load: # flush current contents if we expect to load data self._autoflush() object_mapper(instance) # verify mapped autoflush = self.autoflush try: self.autoflush = False return self._merge( attributes.instance_state(instance), attributes.instance_dict(instance), load=load, options=options, _recursive=_recursive, _resolve_conflict_map=_resolve_conflict_map, ) finally: self.autoflush = autoflush def _merge( self, state: InstanceState[_O], state_dict: _InstanceDict, *, options: Optional[Sequence[ORMOption]] = None, load: bool, _recursive: Dict[Any, object], _resolve_conflict_map: Dict[_IdentityKeyType[Any], object], ) -> _O: mapper: Mapper[_O] = _state_mapper(state) if state in _recursive: return cast(_O, _recursive[state]) new_instance = False key = state.key merged: Optional[_O] if key is None: if state in self._new: util.warn( "Instance %s is already pending in this Session yet is " "being merged again; this is probably not what you want " "to do" % state_str(state) ) if not load: raise sa_exc.InvalidRequestError( "merge() with load=False option does not support " "objects transient (i.e. unpersisted) objects. flush() " "all changes on mapped instances before merging with " "load=False." ) key = mapper._identity_key_from_state(state) key_is_persistent = LoaderCallableStatus.NEVER_SET not in key[ 1 ] and ( not _none_set.intersection(key[1]) or ( mapper.allow_partial_pks and not _none_set.issuperset(key[1]) ) ) else: key_is_persistent = True merged = self.identity_map.get(key) if merged is None: if key_is_persistent and key in _resolve_conflict_map: merged = cast(_O, _resolve_conflict_map[key]) elif not load: if state.modified: raise sa_exc.InvalidRequestError( "merge() with load=False option does not support " "objects marked as 'dirty'. flush() all changes on " "mapped instances before merging with load=False." ) merged = mapper.class_manager.new_instance() merged_state = attributes.instance_state(merged) merged_state.key = key self._update_impl(merged_state) new_instance = True elif key_is_persistent: merged = self.get( mapper.class_, key[1], identity_token=key[2], options=options, ) if merged is None: merged = mapper.class_manager.new_instance() merged_state = attributes.instance_state(merged) merged_dict = attributes.instance_dict(merged) new_instance = True self._save_or_update_state(merged_state) else: merged_state = attributes.instance_state(merged) merged_dict = attributes.instance_dict(merged) _recursive[state] = merged _resolve_conflict_map[key] = merged # check that we didn't just pull the exact same # state out. if state is not merged_state: # version check if applicable if mapper.version_id_col is not None: existing_version = mapper._get_state_attr_by_column( state, state_dict, mapper.version_id_col, passive=PassiveFlag.PASSIVE_NO_INITIALIZE, ) merged_version = mapper._get_state_attr_by_column( merged_state, merged_dict, mapper.version_id_col, passive=PassiveFlag.PASSIVE_NO_INITIALIZE, ) if ( existing_version is not LoaderCallableStatus.PASSIVE_NO_RESULT and merged_version is not LoaderCallableStatus.PASSIVE_NO_RESULT and existing_version != merged_version ): raise exc.StaleDataError( "Version id '%s' on merged state %s " "does not match existing version '%s'. " "Leave the version attribute unset when " "merging to update the most recent version." % ( existing_version, state_str(merged_state), merged_version, ) ) merged_state.load_path = state.load_path merged_state.load_options = state.load_options # since we are copying load_options, we need to copy # the callables_ that would have been generated by those # load_options. # assumes that the callables we put in state.callables_ # are not instance-specific (which they should not be) merged_state._copy_callables(state) for prop in mapper.iterate_properties: prop.merge( self, state, state_dict, merged_state, merged_dict, load, _recursive, _resolve_conflict_map, ) if not load: # remove any history merged_state._commit_all(merged_dict, self.identity_map) merged_state.manager.dispatch._sa_event_merge_wo_load( merged_state, None ) if new_instance: merged_state.manager.dispatch.load(merged_state, None) return merged def _validate_persistent(self, state: InstanceState[Any]) -> None: if not self.identity_map.contains_state(state): raise sa_exc.InvalidRequestError( "Instance '%s' is not persistent within this Session" % state_str(state) ) def _save_impl(self, state: InstanceState[Any]) -> None: if state.key is not None: raise sa_exc.InvalidRequestError( "Object '%s' already has an identity - " "it can't be registered as pending" % state_str(state) ) obj = state.obj() to_attach = self._before_attach(state, obj) if state not in self._new: self._new[state] = obj state.insert_order = len(self._new) if to_attach: self._after_attach(state, obj) def _update_impl( self, state: InstanceState[Any], revert_deletion: bool = False ) -> None: if state.key is None: raise sa_exc.InvalidRequestError( "Instance '%s' is not persisted" % state_str(state) ) if state._deleted: if revert_deletion: if not state._attached: return del state._deleted else: raise sa_exc.InvalidRequestError( "Instance '%s' has been deleted. " "Use the make_transient() " "function to send this object back " "to the transient state." % state_str(state) ) obj = state.obj() # check for late gc if obj is None: return to_attach = self._before_attach(state, obj) self._deleted.pop(state, None) if revert_deletion: self.identity_map.replace(state) else: self.identity_map.add(state) if to_attach: self._after_attach(state, obj) elif revert_deletion: self.dispatch.deleted_to_persistent(self, state) def _save_or_update_impl(self, state: InstanceState[Any]) -> None: if state.key is None: self._save_impl(state) else: self._update_impl(state) def enable_relationship_loading(self, obj: object) -> None: """Associate an object with this :class:`.Session` for related object loading. .. warning:: :meth:`.enable_relationship_loading` exists to serve special use cases and is not recommended for general use. Accesses of attributes mapped with :func:`_orm.relationship` will attempt to load a value from the database using this :class:`.Session` as the source of connectivity. The values will be loaded based on foreign key and primary key values present on this object - if not present, then those relationships will be unavailable. The object will be attached to this session, but will **not** participate in any persistence operations; its state for almost all purposes will remain either "transient" or "detached", except for the case of relationship loading. Also note that backrefs will often not work as expected. Altering a relationship-bound attribute on the target object may not fire off a backref event, if the effective value is what was already loaded from a foreign-key-holding value. The :meth:`.Session.enable_relationship_loading` method is similar to the ``load_on_pending`` flag on :func:`_orm.relationship`. Unlike that flag, :meth:`.Session.enable_relationship_loading` allows an object to remain transient while still being able to load related items. To make a transient object associated with a :class:`.Session` via :meth:`.Session.enable_relationship_loading` pending, add it to the :class:`.Session` using :meth:`.Session.add` normally. If the object instead represents an existing identity in the database, it should be merged using :meth:`.Session.merge`. :meth:`.Session.enable_relationship_loading` does not improve behavior when the ORM is used normally - object references should be constructed at the object level, not at the foreign key level, so that they are present in an ordinary way before flush() proceeds. This method is not intended for general use. .. seealso:: :paramref:`_orm.relationship.load_on_pending` - this flag allows per-relationship loading of many-to-ones on items that are pending. :func:`.make_transient_to_detached` - allows for an object to be added to a :class:`.Session` without SQL emitted, which then will unexpire attributes on access. """ try: state = attributes.instance_state(obj) except exc.NO_STATE as err: raise exc.UnmappedInstanceError(obj) from err to_attach = self._before_attach(state, obj) state._load_pending = True if to_attach: self._after_attach(state, obj) def _before_attach(self, state: InstanceState[Any], obj: object) -> bool: self._autobegin_t() if state.session_id == self.hash_key: return False if state.session_id and state.session_id in _sessions: raise sa_exc.InvalidRequestError( "Object '%s' is already attached to session '%s' " "(this is '%s')" % (state_str(state), state.session_id, self.hash_key) ) self.dispatch.before_attach(self, state) return True def _after_attach(self, state: InstanceState[Any], obj: object) -> None: state.session_id = self.hash_key if state.modified and state._strong_obj is None: state._strong_obj = obj self.dispatch.after_attach(self, state) if state.key: self.dispatch.detached_to_persistent(self, state) else: self.dispatch.transient_to_pending(self, state) def __contains__(self, instance: object) -> bool: """Return True if the instance is associated with this session. The instance may be pending or persistent within the Session for a result of True. """ try: state = attributes.instance_state(instance) except exc.NO_STATE as err: raise exc.UnmappedInstanceError(instance) from err return self._contains_state(state) def __iter__(self) -> Iterator[object]: """Iterate over all pending or persistent instances within this Session. """ return iter( list(self._new.values()) + list(self.identity_map.values()) ) def _contains_state(self, state: InstanceState[Any]) -> bool: return state in self._new or self.identity_map.contains_state(state) def flush(self, objects: Optional[Sequence[Any]] = None) -> None: """Flush all the object changes to the database. Writes out all pending object creations, deletions and modifications to the database as INSERTs, DELETEs, UPDATEs, etc. Operations are automatically ordered by the Session's unit of work dependency solver. Database operations will be issued in the current transactional context and do not affect the state of the transaction, unless an error occurs, in which case the entire transaction is rolled back. You may flush() as often as you like within a transaction to move changes from Python to the database's transaction buffer. :param objects: Optional; restricts the flush operation to operate only on elements that are in the given collection. This feature is for an extremely narrow set of use cases where particular objects may need to be operated upon before the full flush() occurs. It is not intended for general use. """ if self._flushing: raise sa_exc.InvalidRequestError("Session is already flushing") if self._is_clean(): return try: self._flushing = True self._flush(objects) finally: self._flushing = False def _flush_warning(self, method: Any) -> None: util.warn( "Usage of the '%s' operation is not currently supported " "within the execution stage of the flush process. " "Results may not be consistent. Consider using alternative " "event listeners or connection-level operations instead." % method ) def _is_clean(self) -> bool: return ( not self.identity_map.check_modified() and not self._deleted and not self._new ) def _flush(self, objects: Optional[Sequence[object]] = None) -> None: dirty = self._dirty_states if not dirty and not self._deleted and not self._new: self.identity_map._modified.clear() return flush_context = UOWTransaction(self) if self.dispatch.before_flush: self.dispatch.before_flush(self, flush_context, objects) # re-establish "dirty states" in case the listeners # added dirty = self._dirty_states deleted = set(self._deleted) new = set(self._new) dirty = set(dirty).difference(deleted) # create the set of all objects we want to operate upon if objects: # specific list passed in objset = set() for o in objects: try: state = attributes.instance_state(o) except exc.NO_STATE as err: raise exc.UnmappedInstanceError(o) from err objset.add(state) else: objset = None # store objects whose fate has been decided processed = set() # put all saves/updates into the flush context. detect top-level # orphans and throw them into deleted. if objset: proc = new.union(dirty).intersection(objset).difference(deleted) else: proc = new.union(dirty).difference(deleted) for state in proc: is_orphan = _state_mapper(state)._is_orphan(state) is_persistent_orphan = is_orphan and state.has_identity if ( is_orphan and not is_persistent_orphan and state._orphaned_outside_of_session ): self._expunge_states([state]) else: _reg = flush_context.register_object( state, isdelete=is_persistent_orphan ) assert _reg, "Failed to add object to the flush context!" processed.add(state) # put all remaining deletes into the flush context. if objset: proc = deleted.intersection(objset).difference(processed) else: proc = deleted.difference(processed) for state in proc: _reg = flush_context.register_object(state, isdelete=True) assert _reg, "Failed to add object to the flush context!" if not flush_context.has_work: return flush_context.transaction = transaction = self._autobegin_t()._begin() try: self._warn_on_events = True try: flush_context.execute() finally: self._warn_on_events = False self.dispatch.after_flush(self, flush_context) flush_context.finalize_flush_changes() if not objects and self.identity_map._modified: len_ = len(self.identity_map._modified) statelib.InstanceState._commit_all_states( [ (state, state.dict) for state in self.identity_map._modified ], instance_dict=self.identity_map, ) util.warn( "Attribute history events accumulated on %d " "previously clean instances " "within inner-flush event handlers have been " "reset, and will not result in database updates. " "Consider using set_committed_value() within " "inner-flush event handlers to avoid this warning." % len_ ) # useful assertions: # if not objects: # assert not self.identity_map._modified # else: # assert self.identity_map._modified == \ # self.identity_map._modified.difference(objects) self.dispatch.after_flush_postexec(self, flush_context) transaction.commit() except: with util.safe_reraise(): transaction.rollback(_capture_exception=True) def bulk_save_objects( self, objects: Iterable[object], return_defaults: bool = False, update_changed_only: bool = True, preserve_order: bool = True, ) -> None: """Perform a bulk save of the given list of objects. .. legacy:: This method is a legacy feature as of the 2.0 series of SQLAlchemy. For modern bulk INSERT and UPDATE, see the sections :ref:`orm_queryguide_bulk_insert` and :ref:`orm_queryguide_bulk_update`. For general INSERT and UPDATE of existing ORM mapped objects, prefer standard :term:`unit of work` data management patterns, introduced in the :ref:`unified_tutorial` at :ref:`tutorial_orm_data_manipulation`. SQLAlchemy 2.0 now uses :ref:`engine_insertmanyvalues` with modern dialects which solves previous issues of bulk INSERT slowness. :param objects: a sequence of mapped object instances. The mapped objects are persisted as is, and are **not** associated with the :class:`.Session` afterwards. For each object, whether the object is sent as an INSERT or an UPDATE is dependent on the same rules used by the :class:`.Session` in traditional operation; if the object has the :attr:`.InstanceState.key` attribute set, then the object is assumed to be "detached" and will result in an UPDATE. Otherwise, an INSERT is used. In the case of an UPDATE, statements are grouped based on which attributes have changed, and are thus to be the subject of each SET clause. If ``update_changed_only`` is False, then all attributes present within each object are applied to the UPDATE statement, which may help in allowing the statements to be grouped together into a larger executemany(), and will also reduce the overhead of checking history on attributes. :param return_defaults: when True, rows that are missing values which generate defaults, namely integer primary key defaults and sequences, will be inserted **one at a time**, so that the primary key value is available. In particular this will allow joined-inheritance and other multi-table mappings to insert correctly without the need to provide primary key values ahead of time; however, :paramref:`.Session.bulk_save_objects.return_defaults` **greatly reduces the performance gains** of the method overall. It is strongly advised to please use the standard :meth:`_orm.Session.add_all` approach. :param update_changed_only: when True, UPDATE statements are rendered based on those attributes in each state that have logged changes. When False, all attributes present are rendered into the SET clause with the exception of primary key attributes. :param preserve_order: when True, the order of inserts and updates matches exactly the order in which the objects are given. When False, common types of objects are grouped into inserts and updates, to allow for more batching opportunities. .. seealso:: :doc:`queryguide/dml` :meth:`.Session.bulk_insert_mappings` :meth:`.Session.bulk_update_mappings` """ obj_states: Iterable[InstanceState[Any]] obj_states = (attributes.instance_state(obj) for obj in objects) if not preserve_order: # the purpose of this sort is just so that common mappers # and persistence states are grouped together, so that groupby # will return a single group for a particular type of mapper. # it's not trying to be deterministic beyond that. obj_states = sorted( obj_states, key=lambda state: (id(state.mapper), state.key is not None), ) def grouping_key( state: InstanceState[_O], ) -> Tuple[Mapper[_O], bool]: return (state.mapper, state.key is not None) for (mapper, isupdate), states in itertools.groupby( obj_states, grouping_key ): self._bulk_save_mappings( mapper, states, isupdate=isupdate, isstates=True, return_defaults=return_defaults, update_changed_only=update_changed_only, render_nulls=False, ) def bulk_insert_mappings( self, mapper: Mapper[Any], mappings: Iterable[Dict[str, Any]], return_defaults: bool = False, render_nulls: bool = False, ) -> None: """Perform a bulk insert of the given list of mapping dictionaries. .. legacy:: This method is a legacy feature as of the 2.0 series of SQLAlchemy. For modern bulk INSERT and UPDATE, see the sections :ref:`orm_queryguide_bulk_insert` and :ref:`orm_queryguide_bulk_update`. The 2.0 API shares implementation details with this method and adds new features as well. :param mapper: a mapped class, or the actual :class:`_orm.Mapper` object, representing the single kind of object represented within the mapping list. :param mappings: a sequence of dictionaries, each one containing the state of the mapped row to be inserted, in terms of the attribute names on the mapped class. If the mapping refers to multiple tables, such as a joined-inheritance mapping, each dictionary must contain all keys to be populated into all tables. :param return_defaults: when True, the INSERT process will be altered to ensure that newly generated primary key values will be fetched. The rationale for this parameter is typically to enable :ref:`Joined Table Inheritance <joined_inheritance>` mappings to be bulk inserted. .. note:: for backends that don't support RETURNING, the :paramref:`_orm.Session.bulk_insert_mappings.return_defaults` parameter can significantly decrease performance as INSERT statements can no longer be batched. See :ref:`engine_insertmanyvalues` for background on which backends are affected. :param render_nulls: When True, a value of ``None`` will result in a NULL value being included in the INSERT statement, rather than the column being omitted from the INSERT. This allows all the rows being INSERTed to have the identical set of columns which allows the full set of rows to be batched to the DBAPI. Normally, each column-set that contains a different combination of NULL values than the previous row must omit a different series of columns from the rendered INSERT statement, which means it must be emitted as a separate statement. By passing this flag, the full set of rows are guaranteed to be batchable into one batch; the cost however is that server-side defaults which are invoked by an omitted column will be skipped, so care must be taken to ensure that these are not necessary. .. warning:: When this flag is set, **server side default SQL values will not be invoked** for those columns that are inserted as NULL; the NULL value will be sent explicitly. Care must be taken to ensure that no server-side default functions need to be invoked for the operation as a whole. .. seealso:: :doc:`queryguide/dml` :meth:`.Session.bulk_save_objects` :meth:`.Session.bulk_update_mappings` """ self._bulk_save_mappings( mapper, mappings, isupdate=False, isstates=False, return_defaults=return_defaults, update_changed_only=False, render_nulls=render_nulls, ) def bulk_update_mappings( self, mapper: Mapper[Any], mappings: Iterable[Dict[str, Any]] ) -> None: """Perform a bulk update of the given list of mapping dictionaries. .. legacy:: This method is a legacy feature as of the 2.0 series of SQLAlchemy. For modern bulk INSERT and UPDATE, see the sections :ref:`orm_queryguide_bulk_insert` and :ref:`orm_queryguide_bulk_update`. The 2.0 API shares implementation details with this method and adds new features as well. :param mapper: a mapped class, or the actual :class:`_orm.Mapper` object, representing the single kind of object represented within the mapping list. :param mappings: a sequence of dictionaries, each one containing the state of the mapped row to be updated, in terms of the attribute names on the mapped class. If the mapping refers to multiple tables, such as a joined-inheritance mapping, each dictionary may contain keys corresponding to all tables. All those keys which are present and are not part of the primary key are applied to the SET clause of the UPDATE statement; the primary key values, which are required, are applied to the WHERE clause. .. seealso:: :doc:`queryguide/dml` :meth:`.Session.bulk_insert_mappings` :meth:`.Session.bulk_save_objects` """ self._bulk_save_mappings( mapper, mappings, isupdate=True, isstates=False, return_defaults=False, update_changed_only=False, render_nulls=False, ) def _bulk_save_mappings( self, mapper: Mapper[_O], mappings: Union[Iterable[InstanceState[_O]], Iterable[Dict[str, Any]]], *, isupdate: bool, isstates: bool, return_defaults: bool, update_changed_only: bool, render_nulls: bool, ) -> None: mapper = _class_to_mapper(mapper) self._flushing = True transaction = self._autobegin_t()._begin() try: if isupdate: bulk_persistence._bulk_update( mapper, mappings, transaction, isstates=isstates, update_changed_only=update_changed_only, ) else: bulk_persistence._bulk_insert( mapper, mappings, transaction, isstates=isstates, return_defaults=return_defaults, render_nulls=render_nulls, ) transaction.commit() except: with util.safe_reraise(): transaction.rollback(_capture_exception=True) finally: self._flushing = False def is_modified( self, instance: object, include_collections: bool = True ) -> bool: r"""Return ``True`` if the given instance has locally modified attributes. This method retrieves the history for each instrumented attribute on the instance and performs a comparison of the current value to its previously flushed or committed value, if any. It is in effect a more expensive and accurate version of checking for the given instance in the :attr:`.Session.dirty` collection; a full test for each attribute's net "dirty" status is performed. E.g.:: return session.is_modified(someobject) A few caveats to this method apply: * Instances present in the :attr:`.Session.dirty` collection may report ``False`` when tested with this method. This is because the object may have received change events via attribute mutation, thus placing it in :attr:`.Session.dirty`, but ultimately the state is the same as that loaded from the database, resulting in no net change here. * Scalar attributes may not have recorded the previously set value when a new value was applied, if the attribute was not loaded, or was expired, at the time the new value was received - in these cases, the attribute is assumed to have a change, even if there is ultimately no net change against its database value. SQLAlchemy in most cases does not need the "old" value when a set event occurs, so it skips the expense of a SQL call if the old value isn't present, based on the assumption that an UPDATE of the scalar value is usually needed, and in those few cases where it isn't, is less expensive on average than issuing a defensive SELECT. The "old" value is fetched unconditionally upon set only if the attribute container has the ``active_history`` flag set to ``True``. This flag is set typically for primary key attributes and scalar object references that are not a simple many-to-one. To set this flag for any arbitrary mapped column, use the ``active_history`` argument with :func:`.column_property`. :param instance: mapped instance to be tested for pending changes. :param include_collections: Indicates if multivalued collections should be included in the operation. Setting this to ``False`` is a way to detect only local-column based properties (i.e. scalar columns or many-to-one foreign keys) that would result in an UPDATE for this instance upon flush. """ state = object_state(instance) if not state.modified: return False dict_ = state.dict for attr in state.manager.attributes: if ( not include_collections and hasattr(attr.impl, "get_collection") ) or not hasattr(attr.impl, "get_history"): continue (added, unchanged, deleted) = attr.impl.get_history( state, dict_, passive=PassiveFlag.NO_CHANGE ) if added or deleted: return True else: return False @property def is_active(self) -> bool: """True if this :class:`.Session` not in "partial rollback" state. .. versionchanged:: 1.4 The :class:`_orm.Session` no longer begins a new transaction immediately, so this attribute will be False when the :class:`_orm.Session` is first instantiated. "partial rollback" state typically indicates that the flush process of the :class:`_orm.Session` has failed, and that the :meth:`_orm.Session.rollback` method must be emitted in order to fully roll back the transaction. If this :class:`_orm.Session` is not in a transaction at all, the :class:`_orm.Session` will autobegin when it is first used, so in this case :attr:`_orm.Session.is_active` will return True. Otherwise, if this :class:`_orm.Session` is within a transaction, and that transaction has not been rolled back internally, the :attr:`_orm.Session.is_active` will also return True. .. seealso:: :ref:`faq_session_rollback` :meth:`_orm.Session.in_transaction` """ return self._transaction is None or self._transaction.is_active @property def _dirty_states(self) -> Iterable[InstanceState[Any]]: """The set of all persistent states considered dirty. This method returns all states that were modified including those that were possibly deleted. """ return self.identity_map._dirty_states() @property def dirty(self) -> IdentitySet: """The set of all persistent instances considered dirty. E.g.:: some_mapped_object in session.dirty Instances are considered dirty when they were modified but not deleted. Note that this 'dirty' calculation is 'optimistic'; most attribute-setting or collection modification operations will mark an instance as 'dirty' and place it in this set, even if there is no net change to the attribute's value. At flush time, the value of each attribute is compared to its previously saved value, and if there's no net change, no SQL operation will occur (this is a more expensive operation so it's only done at flush time). To check if an instance has actionable net changes to its attributes, use the :meth:`.Session.is_modified` method. """ return IdentitySet( [ state.obj() for state in self._dirty_states if state not in self._deleted ] ) @property def deleted(self) -> IdentitySet: "The set of all instances marked as 'deleted' within this ``Session``" return util.IdentitySet(list(self._deleted.values())) @property def new(self) -> IdentitySet: "The set of all instances marked as 'new' within this ``Session``." return util.IdentitySet(list(self._new.values())) _S = TypeVar("_S", bound="Session") class sessionmaker(_SessionClassMethods, Generic[_S]): """A configurable :class:`.Session` factory. The :class:`.sessionmaker` factory generates new :class:`.Session` objects when called, creating them given the configurational arguments established here. e.g.:: from sqlalchemy import create_engine from sqlalchemy.orm import sessionmaker # an Engine, which the Session will use for connection # resources engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/") Session = sessionmaker(engine) with Session() as session: session.add(some_object) session.add(some_other_object) session.commit() Context manager use is optional; otherwise, the returned :class:`_orm.Session` object may be closed explicitly via the :meth:`_orm.Session.close` method. Using a ``try:/finally:`` block is optional, however will ensure that the close takes place even if there are database errors:: session = Session() try: session.add(some_object) session.add(some_other_object) session.commit() finally: session.close() :class:`.sessionmaker` acts as a factory for :class:`_orm.Session` objects in the same way as an :class:`_engine.Engine` acts as a factory for :class:`_engine.Connection` objects. In this way it also includes a :meth:`_orm.sessionmaker.begin` method, that provides a context manager which both begins and commits a transaction, as well as closes out the :class:`_orm.Session` when complete, rolling back the transaction if any errors occur:: Session = sessionmaker(engine) with Session.begin() as session: session.add(some_object) session.add(some_other_object) # commits transaction, closes session .. versionadded:: 1.4 When calling upon :class:`_orm.sessionmaker` to construct a :class:`_orm.Session`, keyword arguments may also be passed to the method; these arguments will override that of the globally configured parameters. Below we use a :class:`_orm.sessionmaker` bound to a certain :class:`_engine.Engine` to produce a :class:`_orm.Session` that is instead bound to a specific :class:`_engine.Connection` procured from that engine:: Session = sessionmaker(engine) # bind an individual session to a connection with engine.connect() as connection: with Session(bind=connection) as session: ... # work with session The class also includes a method :meth:`_orm.sessionmaker.configure`, which can be used to specify additional keyword arguments to the factory, which will take effect for subsequent :class:`.Session` objects generated. This is usually used to associate one or more :class:`_engine.Engine` objects with an existing :class:`.sessionmaker` factory before it is first used:: # application starts, sessionmaker does not have # an engine bound yet Session = sessionmaker() # ... later, when an engine URL is read from a configuration # file or other events allow the engine to be created engine = create_engine("sqlite:///foo.db") Session.configure(bind=engine) sess = Session() # work with session .. seealso:: :ref:`session_getting` - introductory text on creating sessions using :class:`.sessionmaker`. """ class_: Type[_S] @overload def __init__( self, bind: Optional[_SessionBind] = ..., *, class_: Type[_S], autoflush: bool = ..., expire_on_commit: bool = ..., info: Optional[_InfoType] = ..., **kw: Any, ): ... @overload def __init__( self: "sessionmaker[Session]", bind: Optional[_SessionBind] = ..., *, autoflush: bool = ..., expire_on_commit: bool = ..., info: Optional[_InfoType] = ..., **kw: Any, ): ... def __init__( self, bind: Optional[_SessionBind] = None, *, class_: Type[_S] = Session, # type: ignore autoflush: bool = True, expire_on_commit: bool = True, info: Optional[_InfoType] = None, **kw: Any, ): r"""Construct a new :class:`.sessionmaker`. All arguments here except for ``class_`` correspond to arguments accepted by :class:`.Session` directly. See the :meth:`.Session.__init__` docstring for more details on parameters. :param bind: a :class:`_engine.Engine` or other :class:`.Connectable` with which newly created :class:`.Session` objects will be associated. :param class\_: class to use in order to create new :class:`.Session` objects. Defaults to :class:`.Session`. :param autoflush: The autoflush setting to use with newly created :class:`.Session` objects. .. seealso:: :ref:`session_flushing` - additional background on autoflush :param expire_on_commit=True: the :paramref:`_orm.Session.expire_on_commit` setting to use with newly created :class:`.Session` objects. :param info: optional dictionary of information that will be available via :attr:`.Session.info`. Note this dictionary is *updated*, not replaced, when the ``info`` parameter is specified to the specific :class:`.Session` construction operation. :param \**kw: all other keyword arguments are passed to the constructor of newly created :class:`.Session` objects. """ kw["bind"] = bind kw["autoflush"] = autoflush kw["expire_on_commit"] = expire_on_commit if info is not None: kw["info"] = info self.kw = kw # make our own subclass of the given class, so that # events can be associated with it specifically. self.class_ = type(class_.__name__, (class_,), {}) def begin(self) -> contextlib.AbstractContextManager[_S]: """Produce a context manager that both provides a new :class:`_orm.Session` as well as a transaction that commits. e.g.:: Session = sessionmaker(some_engine) with Session.begin() as session: session.add(some_object) # commits transaction, closes session .. versionadded:: 1.4 """ session = self() return session._maker_context_manager() def __call__(self, **local_kw: Any) -> _S: """Produce a new :class:`.Session` object using the configuration established in this :class:`.sessionmaker`. In Python, the ``__call__`` method is invoked on an object when it is "called" in the same way as a function:: Session = sessionmaker(some_engine) session = Session() # invokes sessionmaker.__call__() """ for k, v in self.kw.items(): if k == "info" and "info" in local_kw: d = v.copy() d.update(local_kw["info"]) local_kw["info"] = d else: local_kw.setdefault(k, v) return self.class_(**local_kw) def configure(self, **new_kw: Any) -> None: """(Re)configure the arguments for this sessionmaker. e.g.:: Session = sessionmaker() Session.configure(bind=create_engine("sqlite://")) """ self.kw.update(new_kw) def __repr__(self) -> str: return "%s(class_=%r, %s)" % ( self.__class__.__name__, self.class_.__name__, ", ".join("%s=%r" % (k, v) for k, v in self.kw.items()), ) def close_all_sessions() -> None: """Close all sessions in memory. This function consults a global registry of all :class:`.Session` objects and calls :meth:`.Session.close` on them, which resets them to a clean state. This function is not for general use but may be useful for test suites within the teardown scheme. .. versionadded:: 1.3 """ for sess in _sessions.values(): sess.close() def make_transient(instance: object) -> None: """Alter the state of the given instance so that it is :term:`transient`. .. note:: :func:`.make_transient` is a special-case function for advanced use cases only. The given mapped instance is assumed to be in the :term:`persistent` or :term:`detached` state. The function will remove its association with any :class:`.Session` as well as its :attr:`.InstanceState.identity`. The effect is that the object will behave as though it were newly constructed, except retaining any attribute / collection values that were loaded at the time of the call. The :attr:`.InstanceState.deleted` flag is also reset if this object had been deleted as a result of using :meth:`.Session.delete`. .. warning:: :func:`.make_transient` does **not** "unexpire" or otherwise eagerly load ORM-mapped attributes that are not currently loaded at the time the function is called. This includes attributes which: * were expired via :meth:`.Session.expire` * were expired as the natural effect of committing a session transaction, e.g. :meth:`.Session.commit` * are normally :term:`lazy loaded` but are not currently loaded * are "deferred" (see :ref:`orm_queryguide_column_deferral`) and are not yet loaded * were not present in the query which loaded this object, such as that which is common in joined table inheritance and other scenarios. After :func:`.make_transient` is called, unloaded attributes such as those above will normally resolve to the value ``None`` when accessed, or an empty collection for a collection-oriented attribute. As the object is transient and un-associated with any database identity, it will no longer retrieve these values. .. seealso:: :func:`.make_transient_to_detached` """ state = attributes.instance_state(instance) s = _state_session(state) if s: s._expunge_states([state]) # remove expired state state.expired_attributes.clear() # remove deferred callables if state.callables: del state.callables if state.key: del state.key if state._deleted: del state._deleted def make_transient_to_detached(instance: object) -> None: """Make the given transient instance :term:`detached`. .. note:: :func:`.make_transient_to_detached` is a special-case function for advanced use cases only. All attribute history on the given instance will be reset as though the instance were freshly loaded from a query. Missing attributes will be marked as expired. The primary key attributes of the object, which are required, will be made into the "key" of the instance. The object can then be added to a session, or merged possibly with the load=False flag, at which point it will look as if it were loaded that way, without emitting SQL. This is a special use case function that differs from a normal call to :meth:`.Session.merge` in that a given persistent state can be manufactured without any SQL calls. .. seealso:: :func:`.make_transient` :meth:`.Session.enable_relationship_loading` """ state = attributes.instance_state(instance) if state.session_id or state.key: raise sa_exc.InvalidRequestError("Given object must be transient") state.key = state.mapper._identity_key_from_state(state) if state._deleted: del state._deleted state._commit_all(state.dict) state._expire_attributes(state.dict, state.unloaded) def object_session(instance: object) -> Optional[Session]: """Return the :class:`.Session` to which the given instance belongs. This is essentially the same as the :attr:`.InstanceState.session` accessor. See that attribute for details. """ try: state = attributes.instance_state(instance) except exc.NO_STATE as err: raise exc.UnmappedInstanceError(instance) from err else: return _state_session(state) _new_sessionid = util.counter() sqlalchemy/orm/interfaces.py 0000755 00000137235 15125143220 0012211 0 ustar 00 # orm/interfaces.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """ Contains various base classes used throughout the ORM. Defines some key base classes prominent within the internals. This module and the classes within are mostly private, though some attributes are exposed when inspecting mappings. """ from __future__ import annotations import collections import dataclasses import typing from typing import Any from typing import Callable from typing import cast from typing import ClassVar from typing import Dict from typing import Generic from typing import Iterator from typing import List from typing import NamedTuple from typing import NoReturn from typing import Optional from typing import Sequence from typing import Set from typing import Tuple from typing import Type from typing import TYPE_CHECKING from typing import TypeVar from typing import Union from . import exc as orm_exc from . import path_registry from .base import _MappedAttribute as _MappedAttribute from .base import EXT_CONTINUE as EXT_CONTINUE # noqa: F401 from .base import EXT_SKIP as EXT_SKIP # noqa: F401 from .base import EXT_STOP as EXT_STOP # noqa: F401 from .base import InspectionAttr as InspectionAttr # noqa: F401 from .base import InspectionAttrInfo as InspectionAttrInfo from .base import MANYTOMANY as MANYTOMANY # noqa: F401 from .base import MANYTOONE as MANYTOONE # noqa: F401 from .base import NO_KEY as NO_KEY # noqa: F401 from .base import NO_VALUE as NO_VALUE # noqa: F401 from .base import NotExtension as NotExtension # noqa: F401 from .base import ONETOMANY as ONETOMANY # noqa: F401 from .base import RelationshipDirection as RelationshipDirection # noqa: F401 from .base import SQLORMOperations from .. import ColumnElement from .. import exc as sa_exc from .. import inspection from .. import util from ..sql import operators from ..sql import roles from ..sql import visitors from ..sql.base import _NoArg from ..sql.base import ExecutableOption from ..sql.cache_key import HasCacheKey from ..sql.operators import ColumnOperators from ..sql.schema import Column from ..sql.type_api import TypeEngine from ..util import warn_deprecated from ..util.typing import RODescriptorReference from ..util.typing import TypedDict if typing.TYPE_CHECKING: from ._typing import _EntityType from ._typing import _IdentityKeyType from ._typing import _InstanceDict from ._typing import _InternalEntityType from ._typing import _ORMAdapterProto from .attributes import InstrumentedAttribute from .base import Mapped from .context import _MapperEntity from .context import ORMCompileState from .context import QueryContext from .decl_api import RegistryType from .decl_base import _ClassScanMapperConfig from .loading import _PopulatorDict from .mapper import Mapper from .path_registry import AbstractEntityRegistry from .query import Query from .session import Session from .state import InstanceState from .strategy_options import _LoadElement from .util import AliasedInsp from .util import ORMAdapter from ..engine.result import Result from ..sql._typing import _ColumnExpressionArgument from ..sql._typing import _ColumnsClauseArgument from ..sql._typing import _DMLColumnArgument from ..sql._typing import _InfoType from ..sql.operators import OperatorType from ..sql.visitors import _TraverseInternalsType from ..util.typing import _AnnotationScanType _StrategyKey = Tuple[Any, ...] _T = TypeVar("_T", bound=Any) _T_co = TypeVar("_T_co", bound=Any, covariant=True) _TLS = TypeVar("_TLS", bound="Type[LoaderStrategy]") class ORMStatementRole(roles.StatementRole): __slots__ = () _role_name = ( "Executable SQL or text() construct, including ORM aware objects" ) class ORMColumnsClauseRole( roles.ColumnsClauseRole, roles.TypedColumnsClauseRole[_T] ): __slots__ = () _role_name = "ORM mapped entity, aliased entity, or Column expression" class ORMEntityColumnsClauseRole(ORMColumnsClauseRole[_T]): __slots__ = () _role_name = "ORM mapped or aliased entity" class ORMFromClauseRole(roles.StrictFromClauseRole): __slots__ = () _role_name = "ORM mapped entity, aliased entity, or FROM expression" class ORMColumnDescription(TypedDict): name: str # TODO: add python_type and sql_type here; combining them # into "type" is a bad idea type: Union[Type[Any], TypeEngine[Any]] aliased: bool expr: _ColumnsClauseArgument[Any] entity: Optional[_ColumnsClauseArgument[Any]] class _IntrospectsAnnotations: __slots__ = () @classmethod def _mapper_property_name(cls) -> str: return cls.__name__ def found_in_pep593_annotated(self) -> Any: """return a copy of this object to use in declarative when the object is found inside of an Annotated object.""" raise NotImplementedError( f"Use of the {self._mapper_property_name()!r} " "construct inside of an Annotated object is not yet supported." ) def declarative_scan( self, decl_scan: _ClassScanMapperConfig, registry: RegistryType, cls: Type[Any], originating_module: Optional[str], key: str, mapped_container: Optional[Type[Mapped[Any]]], annotation: Optional[_AnnotationScanType], extracted_mapped_annotation: Optional[_AnnotationScanType], is_dataclass_field: bool, ) -> None: """Perform class-specific initializaton at early declarative scanning time. .. versionadded:: 2.0 """ def _raise_for_required(self, key: str, cls: Type[Any]) -> NoReturn: raise sa_exc.ArgumentError( f"Python typing annotation is required for attribute " f'"{cls.__name__}.{key}" when primary argument(s) for ' f'"{self._mapper_property_name()}" ' "construct are None or not present" ) class _AttributeOptions(NamedTuple): """define Python-local attribute behavior options common to all :class:`.MapperProperty` objects. Currently this includes dataclass-generation arguments. .. versionadded:: 2.0 """ dataclasses_init: Union[_NoArg, bool] dataclasses_repr: Union[_NoArg, bool] dataclasses_default: Union[_NoArg, Any] dataclasses_default_factory: Union[_NoArg, Callable[[], Any]] dataclasses_compare: Union[_NoArg, bool] dataclasses_kw_only: Union[_NoArg, bool] dataclasses_hash: Union[_NoArg, bool, None] def _as_dataclass_field(self, key: str) -> Any: """Return a ``dataclasses.Field`` object given these arguments.""" kw: Dict[str, Any] = {} if self.dataclasses_default_factory is not _NoArg.NO_ARG: kw["default_factory"] = self.dataclasses_default_factory if self.dataclasses_default is not _NoArg.NO_ARG: kw["default"] = self.dataclasses_default if self.dataclasses_init is not _NoArg.NO_ARG: kw["init"] = self.dataclasses_init if self.dataclasses_repr is not _NoArg.NO_ARG: kw["repr"] = self.dataclasses_repr if self.dataclasses_compare is not _NoArg.NO_ARG: kw["compare"] = self.dataclasses_compare if self.dataclasses_kw_only is not _NoArg.NO_ARG: kw["kw_only"] = self.dataclasses_kw_only if self.dataclasses_hash is not _NoArg.NO_ARG: kw["hash"] = self.dataclasses_hash if "default" in kw and callable(kw["default"]): # callable defaults are ambiguous. deprecate them in favour of # insert_default or default_factory. #9936 warn_deprecated( f"Callable object passed to the ``default`` parameter for " f"attribute {key!r} in a ORM-mapped Dataclasses context is " "ambiguous, " "and this use will raise an error in a future release. " "If this callable is intended to produce Core level INSERT " "default values for an underlying ``Column``, use " "the ``mapped_column.insert_default`` parameter instead. " "To establish this callable as providing a default value " "for instances of the dataclass itself, use the " "``default_factory`` dataclasses parameter.", "2.0", ) if ( "init" in kw and not kw["init"] and "default" in kw and not callable(kw["default"]) # ignore callable defaults. #9936 and "default_factory" not in kw # illegal but let dc.field raise ): # fix for #9879 default = kw.pop("default") kw["default_factory"] = lambda: default return dataclasses.field(**kw) @classmethod def _get_arguments_for_make_dataclass( cls, key: str, annotation: _AnnotationScanType, mapped_container: Optional[Any], elem: _T, ) -> Union[ Tuple[str, _AnnotationScanType], Tuple[str, _AnnotationScanType, dataclasses.Field[Any]], ]: """given attribute key, annotation, and value from a class, return the argument tuple we would pass to dataclasses.make_dataclass() for this attribute. """ if isinstance(elem, _DCAttributeOptions): dc_field = elem._attribute_options._as_dataclass_field(key) return (key, annotation, dc_field) elif elem is not _NoArg.NO_ARG: # why is typing not erroring on this? return (key, annotation, elem) elif mapped_container is not None: # it's Mapped[], but there's no "element", which means declarative # did not actually do anything for this field. this shouldn't # happen. # previously, this would occur because _scan_attributes would # skip a field that's on an already mapped superclass, but it # would still include it in the annotations, leading # to issue #8718 assert False, "Mapped[] received without a mapping declaration" else: # plain dataclass field, not mapped. Is only possible # if __allow_unmapped__ is set up. I can see this mode causing # problems... return (key, annotation) _DEFAULT_ATTRIBUTE_OPTIONS = _AttributeOptions( _NoArg.NO_ARG, _NoArg.NO_ARG, _NoArg.NO_ARG, _NoArg.NO_ARG, _NoArg.NO_ARG, _NoArg.NO_ARG, _NoArg.NO_ARG, ) _DEFAULT_READONLY_ATTRIBUTE_OPTIONS = _AttributeOptions( False, _NoArg.NO_ARG, _NoArg.NO_ARG, _NoArg.NO_ARG, _NoArg.NO_ARG, _NoArg.NO_ARG, _NoArg.NO_ARG, ) class _DCAttributeOptions: """mixin for descriptors or configurational objects that include dataclass field options. This includes :class:`.MapperProperty`, :class:`._MapsColumn` within the ORM, but also includes :class:`.AssociationProxy` within ext. Can in theory be used for other descriptors that serve a similar role as association proxy. (*maybe* hybrids, not sure yet.) """ __slots__ = () _attribute_options: _AttributeOptions """behavioral options for ORM-enabled Python attributes .. versionadded:: 2.0 """ _has_dataclass_arguments: bool class _MapsColumns(_DCAttributeOptions, _MappedAttribute[_T]): """interface for declarative-capable construct that delivers one or more Column objects to the declarative process to be part of a Table. """ __slots__ = () @property def mapper_property_to_assign(self) -> Optional[MapperProperty[_T]]: """return a MapperProperty to be assigned to the declarative mapping""" raise NotImplementedError() @property def columns_to_assign(self) -> List[Tuple[Column[_T], int]]: """A list of Column objects that should be declaratively added to the new Table object. """ raise NotImplementedError() # NOTE: MapperProperty needs to extend _MappedAttribute so that declarative # typing works, i.e. "Mapped[A] = relationship()". This introduces an # inconvenience which is that all the MapperProperty objects are treated # as descriptors by typing tools, which are misled by this as assignment / # access to a descriptor attribute wants to move through __get__. # Therefore, references to MapperProperty as an instance variable, such # as in PropComparator, may have some special typing workarounds such as the # use of sqlalchemy.util.typing.DescriptorReference to avoid mis-interpretation # by typing tools @inspection._self_inspects class MapperProperty( HasCacheKey, _DCAttributeOptions, _MappedAttribute[_T], InspectionAttrInfo, util.MemoizedSlots, ): """Represent a particular class attribute mapped by :class:`_orm.Mapper`. The most common occurrences of :class:`.MapperProperty` are the mapped :class:`_schema.Column`, which is represented in a mapping as an instance of :class:`.ColumnProperty`, and a reference to another class produced by :func:`_orm.relationship`, represented in the mapping as an instance of :class:`.Relationship`. """ __slots__ = ( "_configure_started", "_configure_finished", "_attribute_options", "_has_dataclass_arguments", "parent", "key", "info", "doc", ) _cache_key_traversal: _TraverseInternalsType = [ ("parent", visitors.ExtendedInternalTraversal.dp_has_cache_key), ("key", visitors.ExtendedInternalTraversal.dp_string), ] if not TYPE_CHECKING: cascade = None is_property = True """Part of the InspectionAttr interface; states this object is a mapper property. """ comparator: PropComparator[_T] """The :class:`_orm.PropComparator` instance that implements SQL expression construction on behalf of this mapped attribute.""" key: str """name of class attribute""" parent: Mapper[Any] """the :class:`.Mapper` managing this property.""" _is_relationship = False _links_to_entity: bool """True if this MapperProperty refers to a mapped entity. Should only be True for Relationship, False for all others. """ doc: Optional[str] """optional documentation string""" info: _InfoType """Info dictionary associated with the object, allowing user-defined data to be associated with this :class:`.InspectionAttr`. The dictionary is generated when first accessed. Alternatively, it can be specified as a constructor argument to the :func:`.column_property`, :func:`_orm.relationship`, or :func:`.composite` functions. .. seealso:: :attr:`.QueryableAttribute.info` :attr:`.SchemaItem.info` """ def _memoized_attr_info(self) -> _InfoType: """Info dictionary associated with the object, allowing user-defined data to be associated with this :class:`.InspectionAttr`. The dictionary is generated when first accessed. Alternatively, it can be specified as a constructor argument to the :func:`.column_property`, :func:`_orm.relationship`, or :func:`.composite` functions. .. seealso:: :attr:`.QueryableAttribute.info` :attr:`.SchemaItem.info` """ return {} def setup( self, context: ORMCompileState, query_entity: _MapperEntity, path: AbstractEntityRegistry, adapter: Optional[ORMAdapter], **kwargs: Any, ) -> None: """Called by Query for the purposes of constructing a SQL statement. Each MapperProperty associated with the target mapper processes the statement referenced by the query context, adding columns and/or criterion as appropriate. """ def create_row_processor( self, context: ORMCompileState, query_entity: _MapperEntity, path: AbstractEntityRegistry, mapper: Mapper[Any], result: Result[Any], adapter: Optional[ORMAdapter], populators: _PopulatorDict, ) -> None: """Produce row processing functions and append to the given set of populators lists. """ def cascade_iterator( self, type_: str, state: InstanceState[Any], dict_: _InstanceDict, visited_states: Set[InstanceState[Any]], halt_on: Optional[Callable[[InstanceState[Any]], bool]] = None, ) -> Iterator[ Tuple[object, Mapper[Any], InstanceState[Any], _InstanceDict] ]: """Iterate through instances related to the given instance for a particular 'cascade', starting with this MapperProperty. Return an iterator3-tuples (instance, mapper, state). Note that the 'cascade' collection on this MapperProperty is checked first for the given type before cascade_iterator is called. This method typically only applies to Relationship. """ return iter(()) def set_parent(self, parent: Mapper[Any], init: bool) -> None: """Set the parent mapper that references this MapperProperty. This method is overridden by some subclasses to perform extra setup when the mapper is first known. """ self.parent = parent def instrument_class(self, mapper: Mapper[Any]) -> None: """Hook called by the Mapper to the property to initiate instrumentation of the class attribute managed by this MapperProperty. The MapperProperty here will typically call out to the attributes module to set up an InstrumentedAttribute. This step is the first of two steps to set up an InstrumentedAttribute, and is called early in the mapper setup process. The second step is typically the init_class_attribute step, called from StrategizedProperty via the post_instrument_class() hook. This step assigns additional state to the InstrumentedAttribute (specifically the "impl") which has been determined after the MapperProperty has determined what kind of persistence management it needs to do (e.g. scalar, object, collection, etc). """ def __init__( self, attribute_options: Optional[_AttributeOptions] = None, _assume_readonly_dc_attributes: bool = False, ) -> None: self._configure_started = False self._configure_finished = False if _assume_readonly_dc_attributes: default_attrs = _DEFAULT_READONLY_ATTRIBUTE_OPTIONS else: default_attrs = _DEFAULT_ATTRIBUTE_OPTIONS if attribute_options and attribute_options != default_attrs: self._has_dataclass_arguments = True self._attribute_options = attribute_options else: self._has_dataclass_arguments = False self._attribute_options = default_attrs def init(self) -> None: """Called after all mappers are created to assemble relationships between mappers and perform other post-mapper-creation initialization steps. """ self._configure_started = True self.do_init() self._configure_finished = True @property def class_attribute(self) -> InstrumentedAttribute[_T]: """Return the class-bound descriptor corresponding to this :class:`.MapperProperty`. This is basically a ``getattr()`` call:: return getattr(self.parent.class_, self.key) I.e. if this :class:`.MapperProperty` were named ``addresses``, and the class to which it is mapped is ``User``, this sequence is possible:: >>> from sqlalchemy import inspect >>> mapper = inspect(User) >>> addresses_property = mapper.attrs.addresses >>> addresses_property.class_attribute is User.addresses True >>> User.addresses.property is addresses_property True """ return getattr(self.parent.class_, self.key) # type: ignore def do_init(self) -> None: """Perform subclass-specific initialization post-mapper-creation steps. This is a template method called by the ``MapperProperty`` object's init() method. """ def post_instrument_class(self, mapper: Mapper[Any]) -> None: """Perform instrumentation adjustments that need to occur after init() has completed. The given Mapper is the Mapper invoking the operation, which may not be the same Mapper as self.parent in an inheritance scenario; however, Mapper will always at least be a sub-mapper of self.parent. This method is typically used by StrategizedProperty, which delegates it to LoaderStrategy.init_class_attribute() to perform final setup on the class-bound InstrumentedAttribute. """ def merge( self, session: Session, source_state: InstanceState[Any], source_dict: _InstanceDict, dest_state: InstanceState[Any], dest_dict: _InstanceDict, load: bool, _recursive: Dict[Any, object], _resolve_conflict_map: Dict[_IdentityKeyType[Any], object], ) -> None: """Merge the attribute represented by this ``MapperProperty`` from source to destination object. """ def __repr__(self) -> str: return "<%s at 0x%x; %s>" % ( self.__class__.__name__, id(self), getattr(self, "key", "no key"), ) @inspection._self_inspects class PropComparator(SQLORMOperations[_T_co], Generic[_T_co], ColumnOperators): r"""Defines SQL operations for ORM mapped attributes. SQLAlchemy allows for operators to be redefined at both the Core and ORM level. :class:`.PropComparator` is the base class of operator redefinition for ORM-level operations, including those of :class:`.ColumnProperty`, :class:`.Relationship`, and :class:`.Composite`. User-defined subclasses of :class:`.PropComparator` may be created. The built-in Python comparison and math operator methods, such as :meth:`.operators.ColumnOperators.__eq__`, :meth:`.operators.ColumnOperators.__lt__`, and :meth:`.operators.ColumnOperators.__add__`, can be overridden to provide new operator behavior. The custom :class:`.PropComparator` is passed to the :class:`.MapperProperty` instance via the ``comparator_factory`` argument. In each case, the appropriate subclass of :class:`.PropComparator` should be used:: # definition of custom PropComparator subclasses from sqlalchemy.orm.properties import ( ColumnProperty, Composite, Relationship, ) class MyColumnComparator(ColumnProperty.Comparator): def __eq__(self, other): return self.__clause_element__() == other class MyRelationshipComparator(Relationship.Comparator): def any(self, expression): "define the 'any' operation" # ... class MyCompositeComparator(Composite.Comparator): def __gt__(self, other): "redefine the 'greater than' operation" return sql.and_( *[ a > b for a, b in zip( self.__clause_element__().clauses, other.__composite_values__(), ) ] ) # application of custom PropComparator subclasses from sqlalchemy.orm import column_property, relationship, composite from sqlalchemy import Column, String class SomeMappedClass(Base): some_column = column_property( Column("some_column", String), comparator_factory=MyColumnComparator, ) some_relationship = relationship( SomeOtherClass, comparator_factory=MyRelationshipComparator ) some_composite = composite( Column("a", String), Column("b", String), comparator_factory=MyCompositeComparator, ) Note that for column-level operator redefinition, it's usually simpler to define the operators at the Core level, using the :attr:`.TypeEngine.comparator_factory` attribute. See :ref:`types_operators` for more detail. .. seealso:: :class:`.ColumnProperty.Comparator` :class:`.Relationship.Comparator` :class:`.Composite.Comparator` :class:`.ColumnOperators` :ref:`types_operators` :attr:`.TypeEngine.comparator_factory` """ __slots__ = "prop", "_parententity", "_adapt_to_entity" __visit_name__ = "orm_prop_comparator" _parententity: _InternalEntityType[Any] _adapt_to_entity: Optional[AliasedInsp[Any]] prop: RODescriptorReference[MapperProperty[_T_co]] def __init__( self, prop: MapperProperty[_T], parentmapper: _InternalEntityType[Any], adapt_to_entity: Optional[AliasedInsp[Any]] = None, ): self.prop = prop self._parententity = adapt_to_entity or parentmapper self._adapt_to_entity = adapt_to_entity @util.non_memoized_property def property(self) -> MapperProperty[_T_co]: """Return the :class:`.MapperProperty` associated with this :class:`.PropComparator`. Return values here will commonly be instances of :class:`.ColumnProperty` or :class:`.Relationship`. """ return self.prop def __clause_element__(self) -> roles.ColumnsClauseRole: raise NotImplementedError("%r" % self) def _bulk_update_tuples( self, value: Any ) -> Sequence[Tuple[_DMLColumnArgument, Any]]: """Receive a SQL expression that represents a value in the SET clause of an UPDATE statement. Return a tuple that can be passed to a :class:`_expression.Update` construct. """ return [(cast("_DMLColumnArgument", self.__clause_element__()), value)] def adapt_to_entity( self, adapt_to_entity: AliasedInsp[Any] ) -> PropComparator[_T_co]: """Return a copy of this PropComparator which will use the given :class:`.AliasedInsp` to produce corresponding expressions. """ return self.__class__(self.prop, self._parententity, adapt_to_entity) @util.ro_non_memoized_property def _parentmapper(self) -> Mapper[Any]: """legacy; this is renamed to _parententity to be compatible with QueryableAttribute.""" return self._parententity.mapper def _criterion_exists( self, criterion: Optional[_ColumnExpressionArgument[bool]] = None, **kwargs: Any, ) -> ColumnElement[Any]: return self.prop.comparator._criterion_exists(criterion, **kwargs) @util.ro_non_memoized_property def adapter(self) -> Optional[_ORMAdapterProto]: """Produce a callable that adapts column expressions to suit an aliased version of this comparator. """ if self._adapt_to_entity is None: return None else: return self._adapt_to_entity._orm_adapt_element @util.ro_non_memoized_property def info(self) -> _InfoType: return self.prop.info @staticmethod def _any_op(a: Any, b: Any, **kwargs: Any) -> Any: return a.any(b, **kwargs) @staticmethod def _has_op(left: Any, other: Any, **kwargs: Any) -> Any: return left.has(other, **kwargs) @staticmethod def _of_type_op(a: Any, class_: Any) -> Any: return a.of_type(class_) any_op = cast(operators.OperatorType, _any_op) has_op = cast(operators.OperatorType, _has_op) of_type_op = cast(operators.OperatorType, _of_type_op) if typing.TYPE_CHECKING: def operate( self, op: OperatorType, *other: Any, **kwargs: Any ) -> ColumnElement[Any]: ... def reverse_operate( self, op: OperatorType, other: Any, **kwargs: Any ) -> ColumnElement[Any]: ... def of_type(self, class_: _EntityType[Any]) -> PropComparator[_T_co]: r"""Redefine this object in terms of a polymorphic subclass, :func:`_orm.with_polymorphic` construct, or :func:`_orm.aliased` construct. Returns a new PropComparator from which further criterion can be evaluated. e.g.:: query.join(Company.employees.of_type(Engineer)).filter( Engineer.name == "foo" ) :param \class_: a class or mapper indicating that criterion will be against this specific subclass. .. seealso:: :ref:`orm_queryguide_joining_relationships_aliased` - in the :ref:`queryguide_toplevel` :ref:`inheritance_of_type` """ return self.operate(PropComparator.of_type_op, class_) # type: ignore def and_( self, *criteria: _ColumnExpressionArgument[bool] ) -> PropComparator[bool]: """Add additional criteria to the ON clause that's represented by this relationship attribute. E.g.:: stmt = select(User).join( User.addresses.and_(Address.email_address != "foo") ) stmt = select(User).options( joinedload(User.addresses.and_(Address.email_address != "foo")) ) .. versionadded:: 1.4 .. seealso:: :ref:`orm_queryguide_join_on_augmented` :ref:`loader_option_criteria` :func:`.with_loader_criteria` """ return self.operate(operators.and_, *criteria) # type: ignore def any( self, criterion: Optional[_ColumnExpressionArgument[bool]] = None, **kwargs: Any, ) -> ColumnElement[bool]: r"""Return a SQL expression representing true if this element references a member which meets the given criterion. The usual implementation of ``any()`` is :meth:`.Relationship.Comparator.any`. :param criterion: an optional ClauseElement formulated against the member class' table or attributes. :param \**kwargs: key/value pairs corresponding to member class attribute names which will be compared via equality to the corresponding values. """ return self.operate(PropComparator.any_op, criterion, **kwargs) def has( self, criterion: Optional[_ColumnExpressionArgument[bool]] = None, **kwargs: Any, ) -> ColumnElement[bool]: r"""Return a SQL expression representing true if this element references a member which meets the given criterion. The usual implementation of ``has()`` is :meth:`.Relationship.Comparator.has`. :param criterion: an optional ClauseElement formulated against the member class' table or attributes. :param \**kwargs: key/value pairs corresponding to member class attribute names which will be compared via equality to the corresponding values. """ return self.operate(PropComparator.has_op, criterion, **kwargs) class StrategizedProperty(MapperProperty[_T]): """A MapperProperty which uses selectable strategies to affect loading behavior. There is a single strategy selected by default. Alternate strategies can be selected at Query time through the usage of ``StrategizedOption`` objects via the Query.options() method. The mechanics of StrategizedProperty are used for every Query invocation for every mapped attribute participating in that Query, to determine first how the attribute will be rendered in SQL and secondly how the attribute will retrieve a value from a result row and apply it to a mapped object. The routines here are very performance-critical. """ __slots__ = ( "_strategies", "strategy", "_wildcard_token", "_default_path_loader_key", "strategy_key", ) inherit_cache = True strategy_wildcard_key: ClassVar[str] strategy_key: _StrategyKey _strategies: Dict[_StrategyKey, LoaderStrategy] def _memoized_attr__wildcard_token(self) -> Tuple[str]: return ( f"{self.strategy_wildcard_key}:{path_registry._WILDCARD_TOKEN}", ) def _memoized_attr__default_path_loader_key( self, ) -> Tuple[str, Tuple[str]]: return ( "loader", (f"{self.strategy_wildcard_key}:{path_registry._DEFAULT_TOKEN}",), ) def _get_context_loader( self, context: ORMCompileState, path: AbstractEntityRegistry ) -> Optional[_LoadElement]: load: Optional[_LoadElement] = None search_path = path[self] # search among: exact match, "attr.*", "default" strategy # if any. for path_key in ( search_path._loader_key, search_path._wildcard_path_loader_key, search_path._default_path_loader_key, ): if path_key in context.attributes: load = context.attributes[path_key] break # note that if strategy_options.Load is placing non-actionable # objects in the context like defaultload(), we would # need to continue the loop here if we got such an # option as below. # if load.strategy or load.local_opts: # break return load def _get_strategy(self, key: _StrategyKey) -> LoaderStrategy: try: return self._strategies[key] except KeyError: pass # run outside to prevent transfer of exception context cls = self._strategy_lookup(self, *key) # this previously was setting self._strategies[cls], that's # a bad idea; should use strategy key at all times because every # strategy has multiple keys at this point self._strategies[key] = strategy = cls(self, key) return strategy def setup( self, context: ORMCompileState, query_entity: _MapperEntity, path: AbstractEntityRegistry, adapter: Optional[ORMAdapter], **kwargs: Any, ) -> None: loader = self._get_context_loader(context, path) if loader and loader.strategy: strat = self._get_strategy(loader.strategy) else: strat = self.strategy strat.setup_query( context, query_entity, path, loader, adapter, **kwargs ) def create_row_processor( self, context: ORMCompileState, query_entity: _MapperEntity, path: AbstractEntityRegistry, mapper: Mapper[Any], result: Result[Any], adapter: Optional[ORMAdapter], populators: _PopulatorDict, ) -> None: loader = self._get_context_loader(context, path) if loader and loader.strategy: strat = self._get_strategy(loader.strategy) else: strat = self.strategy strat.create_row_processor( context, query_entity, path, loader, mapper, result, adapter, populators, ) def do_init(self) -> None: self._strategies = {} self.strategy = self._get_strategy(self.strategy_key) def post_instrument_class(self, mapper: Mapper[Any]) -> None: if ( not self.parent.non_primary and not mapper.class_manager._attr_has_impl(self.key) ): self.strategy.init_class_attribute(mapper) _all_strategies: collections.defaultdict[ Type[MapperProperty[Any]], Dict[_StrategyKey, Type[LoaderStrategy]] ] = collections.defaultdict(dict) @classmethod def strategy_for(cls, **kw: Any) -> Callable[[_TLS], _TLS]: def decorate(dec_cls: _TLS) -> _TLS: # ensure each subclass of the strategy has its # own _strategy_keys collection if "_strategy_keys" not in dec_cls.__dict__: dec_cls._strategy_keys = [] key = tuple(sorted(kw.items())) cls._all_strategies[cls][key] = dec_cls dec_cls._strategy_keys.append(key) return dec_cls return decorate @classmethod def _strategy_lookup( cls, requesting_property: MapperProperty[Any], *key: Any ) -> Type[LoaderStrategy]: requesting_property.parent._with_polymorphic_mappers for prop_cls in cls.__mro__: if prop_cls in cls._all_strategies: if TYPE_CHECKING: assert issubclass(prop_cls, MapperProperty) strategies = cls._all_strategies[prop_cls] try: return strategies[key] except KeyError: pass for property_type, strats in cls._all_strategies.items(): if key in strats: intended_property_type = property_type actual_strategy = strats[key] break else: intended_property_type = None actual_strategy = None raise orm_exc.LoaderStrategyException( cls, requesting_property, intended_property_type, actual_strategy, key, ) class ORMOption(ExecutableOption): """Base class for option objects that are passed to ORM queries. These options may be consumed by :meth:`.Query.options`, :meth:`.Select.options`, or in a more general sense by any :meth:`.Executable.options` method. They are interpreted at statement compile time or execution time in modern use. The deprecated :class:`.MapperOption` is consumed at ORM query construction time. .. versionadded:: 1.4 """ __slots__ = () _is_legacy_option = False propagate_to_loaders = False """if True, indicate this option should be carried along to "secondary" SELECT statements that occur for relationship lazy loaders as well as attribute load / refresh operations. """ _is_core = False _is_user_defined = False _is_compile_state = False _is_criteria_option = False _is_strategy_option = False def _adapt_cached_option_to_uncached_option( self, context: QueryContext, uncached_opt: ORMOption ) -> ORMOption: """adapt this option to the "uncached" version of itself in a loader strategy context. given "self" which is an option from a cached query, as well as the corresponding option from the uncached version of the same query, return the option we should use in a new query, in the context of a loader strategy being asked to load related rows on behalf of that cached query, which is assumed to be building a new query based on entities passed to us from the cached query. Currently this routine chooses between "self" and "uncached" without manufacturing anything new. If the option is itself a loader strategy option which has a path, that path needs to match to the entities being passed to us by the cached query, so the :class:`_orm.Load` subclass overrides this to return "self". For all other options, we return the uncached form which may have changing state, such as a with_loader_criteria() option which will very often have new state. This routine could in the future involve generating a new option based on both inputs if use cases arise, such as if with_loader_criteria() needed to match up to ``AliasedClass`` instances given in the parent query. However, longer term it might be better to restructure things such that ``AliasedClass`` entities are always matched up on their cache key, instead of identity, in things like paths and such, so that this whole issue of "the uncached option does not match the entities" goes away. However this would make ``PathRegistry`` more complicated and difficult to debug as well as potentially less performant in that it would be hashing enormous cache keys rather than a simple AliasedInsp. UNLESS, we could get cache keys overall to be reliably hashed into something like an md5 key. .. versionadded:: 1.4.41 """ if uncached_opt is not None: return uncached_opt else: return self class CompileStateOption(HasCacheKey, ORMOption): """base for :class:`.ORMOption` classes that affect the compilation of a SQL query and therefore need to be part of the cache key. .. note:: :class:`.CompileStateOption` is generally non-public and should not be used as a base class for user-defined options; instead, use :class:`.UserDefinedOption`, which is easier to use as it does not interact with ORM compilation internals or caching. :class:`.CompileStateOption` defines an internal attribute ``_is_compile_state=True`` which has the effect of the ORM compilation routines for SELECT and other statements will call upon these options when a SQL string is being compiled. As such, these classes implement :class:`.HasCacheKey` and need to provide robust ``_cache_key_traversal`` structures. The :class:`.CompileStateOption` class is used to implement the ORM :class:`.LoaderOption` and :class:`.CriteriaOption` classes. .. versionadded:: 1.4.28 """ __slots__ = () _is_compile_state = True def process_compile_state(self, compile_state: ORMCompileState) -> None: """Apply a modification to a given :class:`.ORMCompileState`. This method is part of the implementation of a particular :class:`.CompileStateOption` and is only invoked internally when an ORM query is compiled. """ def process_compile_state_replaced_entities( self, compile_state: ORMCompileState, mapper_entities: Sequence[_MapperEntity], ) -> None: """Apply a modification to a given :class:`.ORMCompileState`, given entities that were replaced by with_only_columns() or with_entities(). This method is part of the implementation of a particular :class:`.CompileStateOption` and is only invoked internally when an ORM query is compiled. .. versionadded:: 1.4.19 """ class LoaderOption(CompileStateOption): """Describe a loader modification to an ORM statement at compilation time. .. versionadded:: 1.4 """ __slots__ = () def process_compile_state_replaced_entities( self, compile_state: ORMCompileState, mapper_entities: Sequence[_MapperEntity], ) -> None: self.process_compile_state(compile_state) class CriteriaOption(CompileStateOption): """Describe a WHERE criteria modification to an ORM statement at compilation time. .. versionadded:: 1.4 """ __slots__ = () _is_criteria_option = True def get_global_criteria(self, attributes: Dict[str, Any]) -> None: """update additional entity criteria options in the given attributes dictionary. """ class UserDefinedOption(ORMOption): """Base class for a user-defined option that can be consumed from the :meth:`.SessionEvents.do_orm_execute` event hook. """ __slots__ = ("payload",) _is_legacy_option = False _is_user_defined = True propagate_to_loaders = False """if True, indicate this option should be carried along to "secondary" Query objects produced during lazy loads or refresh operations. """ def __init__(self, payload: Optional[Any] = None): self.payload = payload @util.deprecated_cls( "1.4", "The :class:`.MapperOption class is deprecated and will be removed " "in a future release. For " "modifications to queries on a per-execution basis, use the " ":class:`.UserDefinedOption` class to establish state within a " ":class:`.Query` or other Core statement, then use the " ":meth:`.SessionEvents.before_orm_execute` hook to consume them.", constructor=None, ) class MapperOption(ORMOption): """Describe a modification to a Query""" __slots__ = () _is_legacy_option = True propagate_to_loaders = False """if True, indicate this option should be carried along to "secondary" Query objects produced during lazy loads or refresh operations. """ def process_query(self, query: Query[Any]) -> None: """Apply a modification to the given :class:`_query.Query`.""" def process_query_conditionally(self, query: Query[Any]) -> None: """same as process_query(), except that this option may not apply to the given query. This is typically applied during a lazy load or scalar refresh operation to propagate options stated in the original Query to the new Query being used for the load. It occurs for those options that specify propagate_to_loaders=True. """ self.process_query(query) class LoaderStrategy: """Describe the loading behavior of a StrategizedProperty object. The ``LoaderStrategy`` interacts with the querying process in three ways: * it controls the configuration of the ``InstrumentedAttribute`` placed on a class to handle the behavior of the attribute. this may involve setting up class-level callable functions to fire off a select operation when the attribute is first accessed (i.e. a lazy load) * it processes the ``QueryContext`` at statement construction time, where it can modify the SQL statement that is being produced. For example, simple column attributes will add their represented column to the list of selected columns, a joined eager loader may establish join clauses to add to the statement. * It produces "row processor" functions at result fetching time. These "row processor" functions populate a particular attribute on a particular mapped instance. """ __slots__ = ( "parent_property", "is_class_level", "parent", "key", "strategy_key", "strategy_opts", ) _strategy_keys: ClassVar[List[_StrategyKey]] def __init__( self, parent: MapperProperty[Any], strategy_key: _StrategyKey ): self.parent_property = parent self.is_class_level = False self.parent = self.parent_property.parent self.key = self.parent_property.key self.strategy_key = strategy_key self.strategy_opts = dict(strategy_key) def init_class_attribute(self, mapper: Mapper[Any]) -> None: pass def setup_query( self, compile_state: ORMCompileState, query_entity: _MapperEntity, path: AbstractEntityRegistry, loadopt: Optional[_LoadElement], adapter: Optional[ORMAdapter], **kwargs: Any, ) -> None: """Establish column and other state for a given QueryContext. This method fulfills the contract specified by MapperProperty.setup(). StrategizedProperty delegates its setup() method directly to this method. """ def create_row_processor( self, context: ORMCompileState, query_entity: _MapperEntity, path: AbstractEntityRegistry, loadopt: Optional[_LoadElement], mapper: Mapper[Any], result: Result[Any], adapter: Optional[ORMAdapter], populators: _PopulatorDict, ) -> None: """Establish row processing functions for a given QueryContext. This method fulfills the contract specified by MapperProperty.create_row_processor(). StrategizedProperty delegates its create_row_processor() method directly to this method. """ def __str__(self) -> str: return str(self.parent_property) sqlalchemy/orm/context.py 0000755 00000340610 15125143220 0011543 0 ustar 00 # orm/context.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors from __future__ import annotations import itertools from typing import Any from typing import cast from typing import Dict from typing import Iterable from typing import List from typing import Optional from typing import Set from typing import Tuple from typing import Type from typing import TYPE_CHECKING from typing import TypeVar from typing import Union from . import attributes from . import interfaces from . import loading from .base import _is_aliased_class from .interfaces import ORMColumnDescription from .interfaces import ORMColumnsClauseRole from .path_registry import PathRegistry from .util import _entity_corresponds_to from .util import _ORMJoin from .util import _TraceAdaptRole from .util import AliasedClass from .util import Bundle from .util import ORMAdapter from .util import ORMStatementAdapter from .. import exc as sa_exc from .. import future from .. import inspect from .. import sql from .. import util from ..sql import coercions from ..sql import expression from ..sql import roles from ..sql import util as sql_util from ..sql import visitors from ..sql._typing import _TP from ..sql._typing import is_dml from ..sql._typing import is_insert_update from ..sql._typing import is_select_base from ..sql.base import _select_iterables from ..sql.base import CacheableOptions from ..sql.base import CompileState from ..sql.base import Executable from ..sql.base import Generative from ..sql.base import Options from ..sql.dml import UpdateBase from ..sql.elements import GroupedElement from ..sql.elements import TextClause from ..sql.selectable import CompoundSelectState from ..sql.selectable import LABEL_STYLE_DISAMBIGUATE_ONLY from ..sql.selectable import LABEL_STYLE_NONE from ..sql.selectable import LABEL_STYLE_TABLENAME_PLUS_COL from ..sql.selectable import Select from ..sql.selectable import SelectLabelStyle from ..sql.selectable import SelectState from ..sql.selectable import TypedReturnsRows from ..sql.visitors import InternalTraversal if TYPE_CHECKING: from ._typing import _InternalEntityType from ._typing import OrmExecuteOptionsParameter from .loading import PostLoad from .mapper import Mapper from .query import Query from .session import _BindArguments from .session import Session from ..engine import Result from ..engine.interfaces import _CoreSingleExecuteParams from ..sql._typing import _ColumnsClauseArgument from ..sql.compiler import SQLCompiler from ..sql.dml import _DMLTableElement from ..sql.elements import ColumnElement from ..sql.selectable import _JoinTargetElement from ..sql.selectable import _LabelConventionCallable from ..sql.selectable import _SetupJoinsElement from ..sql.selectable import ExecutableReturnsRows from ..sql.selectable import SelectBase from ..sql.type_api import TypeEngine _T = TypeVar("_T", bound=Any) _path_registry = PathRegistry.root _EMPTY_DICT = util.immutabledict() LABEL_STYLE_LEGACY_ORM = SelectLabelStyle.LABEL_STYLE_LEGACY_ORM class QueryContext: __slots__ = ( "top_level_context", "compile_state", "query", "user_passed_query", "params", "load_options", "bind_arguments", "execution_options", "session", "autoflush", "populate_existing", "invoke_all_eagers", "version_check", "refresh_state", "create_eager_joins", "propagated_loader_options", "attributes", "runid", "partials", "post_load_paths", "identity_token", "yield_per", "loaders_require_buffering", "loaders_require_uniquing", ) runid: int post_load_paths: Dict[PathRegistry, PostLoad] compile_state: ORMCompileState class default_load_options(Options): _only_return_tuples = False _populate_existing = False _version_check = False _invoke_all_eagers = True _autoflush = True _identity_token = None _yield_per = None _refresh_state = None _lazy_loaded_from = None _legacy_uniquing = False _sa_top_level_orm_context = None _is_user_refresh = False def __init__( self, compile_state: CompileState, statement: Union[Select[Any], FromStatement[Any], UpdateBase], user_passed_query: Union[ Select[Any], FromStatement[Any], UpdateBase, ], params: _CoreSingleExecuteParams, session: Session, load_options: Union[ Type[QueryContext.default_load_options], QueryContext.default_load_options, ], execution_options: Optional[OrmExecuteOptionsParameter] = None, bind_arguments: Optional[_BindArguments] = None, ): self.load_options = load_options self.execution_options = execution_options or _EMPTY_DICT self.bind_arguments = bind_arguments or _EMPTY_DICT self.compile_state = compile_state self.query = statement # the query that the end user passed to Session.execute() or similar. # this is usually the same as .query, except in the bulk_persistence # routines where a separate FromStatement is manufactured in the # compile stage; this allows differentiation in that case. self.user_passed_query = user_passed_query self.session = session self.loaders_require_buffering = False self.loaders_require_uniquing = False self.params = params self.top_level_context = load_options._sa_top_level_orm_context cached_options = compile_state.select_statement._with_options uncached_options = user_passed_query._with_options # see issue #7447 , #8399 for some background # propagated loader options will be present on loaded InstanceState # objects under state.load_options and are typically used by # LazyLoader to apply options to the SELECT statement it emits. # For compile state options (i.e. loader strategy options), these # need to line up with the ".load_path" attribute which in # loader.py is pulled from context.compile_state.current_path. # so, this means these options have to be the ones from the # *cached* statement that's travelling with compile_state, not the # *current* statement which won't match up for an ad-hoc # AliasedClass self.propagated_loader_options = tuple( opt._adapt_cached_option_to_uncached_option(self, uncached_opt) for opt, uncached_opt in zip(cached_options, uncached_options) if opt.propagate_to_loaders ) self.attributes = dict(compile_state.attributes) self.autoflush = load_options._autoflush self.populate_existing = load_options._populate_existing self.invoke_all_eagers = load_options._invoke_all_eagers self.version_check = load_options._version_check self.refresh_state = load_options._refresh_state self.yield_per = load_options._yield_per self.identity_token = load_options._identity_token def _get_top_level_context(self) -> QueryContext: return self.top_level_context or self _orm_load_exec_options = util.immutabledict( {"_result_disable_adapt_to_context": True} ) class AbstractORMCompileState(CompileState): is_dml_returning = False def _init_global_attributes( self, statement, compiler, *, toplevel, process_criteria_for_toplevel ): self.attributes = {} if compiler is None: # this is the legacy / testing only ORM _compile_state() use case. # there is no need to apply criteria options for this. self.global_attributes = {} assert toplevel return else: self.global_attributes = ga = compiler._global_attributes if toplevel: ga["toplevel_orm"] = True if process_criteria_for_toplevel: for opt in statement._with_options: if opt._is_criteria_option: opt.process_compile_state(self) return elif ga.get("toplevel_orm", False): return stack_0 = compiler.stack[0] try: toplevel_stmt = stack_0["selectable"] except KeyError: pass else: for opt in toplevel_stmt._with_options: if opt._is_compile_state and opt._is_criteria_option: opt.process_compile_state(self) ga["toplevel_orm"] = True @classmethod def create_for_statement( cls, statement: Executable, compiler: SQLCompiler, **kw: Any, ) -> CompileState: """Create a context for a statement given a :class:`.Compiler`. This method is always invoked in the context of SQLCompiler.process(). For a Select object, this would be invoked from SQLCompiler.visit_select(). For the special FromStatement object used by Query to indicate "Query.from_statement()", this is called by FromStatement._compiler_dispatch() that would be called by SQLCompiler.process(). """ return super().create_for_statement(statement, compiler, **kw) @classmethod def orm_pre_session_exec( cls, session, statement, params, execution_options, bind_arguments, is_pre_event, ): raise NotImplementedError() @classmethod def orm_execute_statement( cls, session, statement, params, execution_options, bind_arguments, conn, ) -> Result: result = conn.execute( statement, params or {}, execution_options=execution_options ) return cls.orm_setup_cursor_result( session, statement, params, execution_options, bind_arguments, result, ) @classmethod def orm_setup_cursor_result( cls, session, statement, params, execution_options, bind_arguments, result, ): raise NotImplementedError() class AutoflushOnlyORMCompileState(AbstractORMCompileState): """ORM compile state that is a passthrough, except for autoflush.""" @classmethod def orm_pre_session_exec( cls, session, statement, params, execution_options, bind_arguments, is_pre_event, ): # consume result-level load_options. These may have been set up # in an ORMExecuteState hook ( load_options, execution_options, ) = QueryContext.default_load_options.from_execution_options( "_sa_orm_load_options", { "autoflush", }, execution_options, statement._execution_options, ) if not is_pre_event and load_options._autoflush: session._autoflush() return statement, execution_options @classmethod def orm_setup_cursor_result( cls, session, statement, params, execution_options, bind_arguments, result, ): return result class ORMCompileState(AbstractORMCompileState): class default_compile_options(CacheableOptions): _cache_key_traversal = [ ("_use_legacy_query_style", InternalTraversal.dp_boolean), ("_for_statement", InternalTraversal.dp_boolean), ("_bake_ok", InternalTraversal.dp_boolean), ("_current_path", InternalTraversal.dp_has_cache_key), ("_enable_single_crit", InternalTraversal.dp_boolean), ("_enable_eagerloads", InternalTraversal.dp_boolean), ("_only_load_props", InternalTraversal.dp_plain_obj), ("_set_base_alias", InternalTraversal.dp_boolean), ("_for_refresh_state", InternalTraversal.dp_boolean), ("_render_for_subquery", InternalTraversal.dp_boolean), ("_is_star", InternalTraversal.dp_boolean), ] # set to True by default from Query._statement_20(), to indicate # the rendered query should look like a legacy ORM query. right # now this basically indicates we should use tablename_columnname # style labels. Generally indicates the statement originated # from a Query object. _use_legacy_query_style = False # set *only* when we are coming from the Query.statement # accessor, or a Query-level equivalent such as # query.subquery(). this supersedes "toplevel". _for_statement = False _bake_ok = True _current_path = _path_registry _enable_single_crit = True _enable_eagerloads = True _only_load_props = None _set_base_alias = False _for_refresh_state = False _render_for_subquery = False _is_star = False attributes: Dict[Any, Any] global_attributes: Dict[Any, Any] statement: Union[Select[Any], FromStatement[Any], UpdateBase] select_statement: Union[Select[Any], FromStatement[Any], UpdateBase] _entities: List[_QueryEntity] _polymorphic_adapters: Dict[_InternalEntityType, ORMAdapter] compile_options: Union[ Type[default_compile_options], default_compile_options ] _primary_entity: Optional[_QueryEntity] use_legacy_query_style: bool _label_convention: _LabelConventionCallable primary_columns: List[ColumnElement[Any]] secondary_columns: List[ColumnElement[Any]] dedupe_columns: Set[ColumnElement[Any]] create_eager_joins: List[ # TODO: this structure is set up by JoinedLoader Tuple[Any, ...] ] current_path: PathRegistry = _path_registry _has_mapper_entities = False def __init__(self, *arg, **kw): raise NotImplementedError() @classmethod def create_for_statement( cls, statement: Executable, compiler: SQLCompiler, **kw: Any, ) -> ORMCompileState: return cls._create_orm_context( cast("Union[Select, FromStatement]", statement), toplevel=not compiler.stack, compiler=compiler, **kw, ) @classmethod def _create_orm_context( cls, statement: Union[Select, FromStatement], *, toplevel: bool, compiler: Optional[SQLCompiler], **kw: Any, ) -> ORMCompileState: raise NotImplementedError() def _append_dedupe_col_collection(self, obj, col_collection): dedupe = self.dedupe_columns if obj not in dedupe: dedupe.add(obj) col_collection.append(obj) @classmethod def _column_naming_convention( cls, label_style: SelectLabelStyle, legacy: bool ) -> _LabelConventionCallable: if legacy: def name(col, col_name=None): if col_name: return col_name else: return getattr(col, "key") return name else: return SelectState._column_naming_convention(label_style) @classmethod def get_column_descriptions(cls, statement): return _column_descriptions(statement) @classmethod def orm_pre_session_exec( cls, session, statement, params, execution_options, bind_arguments, is_pre_event, ): # consume result-level load_options. These may have been set up # in an ORMExecuteState hook ( load_options, execution_options, ) = QueryContext.default_load_options.from_execution_options( "_sa_orm_load_options", { "populate_existing", "autoflush", "yield_per", "identity_token", "sa_top_level_orm_context", }, execution_options, statement._execution_options, ) # default execution options for ORM results: # 1. _result_disable_adapt_to_context=True # this will disable the ResultSetMetadata._adapt_to_context() # step which we don't need, as we have result processors cached # against the original SELECT statement before caching. if "sa_top_level_orm_context" in execution_options: ctx = execution_options["sa_top_level_orm_context"] execution_options = ctx.query._execution_options.merge_with( ctx.execution_options, execution_options ) if not execution_options: execution_options = _orm_load_exec_options else: execution_options = execution_options.union(_orm_load_exec_options) # would have been placed here by legacy Query only if load_options._yield_per: execution_options = execution_options.union( {"yield_per": load_options._yield_per} ) if ( getattr(statement._compile_options, "_current_path", None) and len(statement._compile_options._current_path) > 10 and execution_options.get("compiled_cache", True) is not None ): execution_options: util.immutabledict[str, Any] = ( execution_options.union( { "compiled_cache": None, "_cache_disable_reason": "excess depth for " "ORM loader options", } ) ) bind_arguments["clause"] = statement # new in 1.4 - the coercions system is leveraged to allow the # "subject" mapper of a statement be propagated to the top # as the statement is built. "subject" mapper is the generally # standard object used as an identifier for multi-database schemes. # we are here based on the fact that _propagate_attrs contains # "compile_state_plugin": "orm". The "plugin_subject" # needs to be present as well. try: plugin_subject = statement._propagate_attrs["plugin_subject"] except KeyError: assert False, "statement had 'orm' plugin but no plugin_subject" else: if plugin_subject: bind_arguments["mapper"] = plugin_subject.mapper if not is_pre_event and load_options._autoflush: session._autoflush() return statement, execution_options @classmethod def orm_setup_cursor_result( cls, session, statement, params, execution_options, bind_arguments, result, ): execution_context = result.context compile_state = execution_context.compiled.compile_state # cover edge case where ORM entities used in legacy select # were passed to session.execute: # session.execute(legacy_select([User.id, User.name])) # see test_query->test_legacy_tuple_old_select load_options = execution_options.get( "_sa_orm_load_options", QueryContext.default_load_options ) if compile_state.compile_options._is_star: return result querycontext = QueryContext( compile_state, statement, statement, params, session, load_options, execution_options, bind_arguments, ) return loading.instances(result, querycontext) @property def _lead_mapper_entities(self): """return all _MapperEntity objects in the lead entities collection. Does **not** include entities that have been replaced by with_entities(), with_only_columns() """ return [ ent for ent in self._entities if isinstance(ent, _MapperEntity) ] def _create_with_polymorphic_adapter(self, ext_info, selectable): """given MapperEntity or ORMColumnEntity, setup polymorphic loading if called for by the Mapper. As of #8168 in 2.0.0rc1, polymorphic adapters, which greatly increase the complexity of the query creation process, are not used at all except in the quasi-legacy cases of with_polymorphic referring to an alias and/or subquery. This would apply to concrete polymorphic loading, and joined inheritance where a subquery is passed to with_polymorphic (which is completely unnecessary in modern use). """ if ( not ext_info.is_aliased_class and ext_info.mapper.persist_selectable not in self._polymorphic_adapters ): for mp in ext_info.mapper.iterate_to_root(): self._mapper_loads_polymorphically_with( mp, ORMAdapter( _TraceAdaptRole.WITH_POLYMORPHIC_ADAPTER, mp, equivalents=mp._equivalent_columns, selectable=selectable, ), ) def _mapper_loads_polymorphically_with(self, mapper, adapter): for m2 in mapper._with_polymorphic_mappers or [mapper]: self._polymorphic_adapters[m2] = adapter for m in m2.iterate_to_root(): self._polymorphic_adapters[m.local_table] = adapter @classmethod def _create_entities_collection(cls, query, legacy): raise NotImplementedError( "this method only works for ORMSelectCompileState" ) class _DMLReturningColFilter: """a base for an adapter used for the DML RETURNING cases Has a subset of the interface used by :class:`.ORMAdapter` and is used for :class:`._QueryEntity` instances to set up their columns as used in RETURNING for a DML statement. """ __slots__ = ("mapper", "columns", "__weakref__") def __init__(self, target_mapper, immediate_dml_mapper): if ( immediate_dml_mapper is not None and target_mapper.local_table is not immediate_dml_mapper.local_table ): # joined inh, or in theory other kinds of multi-table mappings self.mapper = immediate_dml_mapper else: # single inh, normal mappings, etc. self.mapper = target_mapper self.columns = self.columns = util.WeakPopulateDict( self.adapt_check_present # type: ignore ) def __call__(self, col, as_filter): for cc in sql_util._find_columns(col): c2 = self.adapt_check_present(cc) if c2 is not None: return col else: return None def adapt_check_present(self, col): raise NotImplementedError() class _DMLBulkInsertReturningColFilter(_DMLReturningColFilter): """an adapter used for the DML RETURNING case specifically for ORM bulk insert (or any hypothetical DML that is splitting out a class hierarchy among multiple DML statements....ORM bulk insert is the only example right now) its main job is to limit the columns in a RETURNING to only a specific mapped table in a hierarchy. """ def adapt_check_present(self, col): mapper = self.mapper prop = mapper._columntoproperty.get(col, None) if prop is None: return None return mapper.local_table.c.corresponding_column(col) class _DMLUpdateDeleteReturningColFilter(_DMLReturningColFilter): """an adapter used for the DML RETURNING case specifically for ORM enabled UPDATE/DELETE its main job is to limit the columns in a RETURNING to include only direct persisted columns from the immediate selectable, not expressions like column_property(), or to also allow columns from other mappers for the UPDATE..FROM use case. """ def adapt_check_present(self, col): mapper = self.mapper prop = mapper._columntoproperty.get(col, None) if prop is not None: # if the col is from the immediate mapper, only return a persisted # column, not any kind of column_property expression return mapper.persist_selectable.c.corresponding_column(col) # if the col is from some other mapper, just return it, assume the # user knows what they are doing return col @sql.base.CompileState.plugin_for("orm", "orm_from_statement") class ORMFromStatementCompileState(ORMCompileState): _from_obj_alias = None _has_mapper_entities = False statement_container: FromStatement requested_statement: Union[SelectBase, TextClause, UpdateBase] dml_table: Optional[_DMLTableElement] = None _has_orm_entities = False multi_row_eager_loaders = False eager_adding_joins = False compound_eager_adapter = None extra_criteria_entities = _EMPTY_DICT eager_joins = _EMPTY_DICT @classmethod def _create_orm_context( cls, statement: Union[Select, FromStatement], *, toplevel: bool, compiler: Optional[SQLCompiler], **kw: Any, ) -> ORMFromStatementCompileState: statement_container = statement assert isinstance(statement_container, FromStatement) if compiler is not None and compiler.stack: raise sa_exc.CompileError( "The ORM FromStatement construct only supports being " "invoked as the topmost statement, as it is only intended to " "define how result rows should be returned." ) self = cls.__new__(cls) self._primary_entity = None self.use_legacy_query_style = ( statement_container._compile_options._use_legacy_query_style ) self.statement_container = self.select_statement = statement_container self.requested_statement = statement = statement_container.element if statement.is_dml: self.dml_table = statement.table self.is_dml_returning = True self._entities = [] self._polymorphic_adapters = {} self.compile_options = statement_container._compile_options if ( self.use_legacy_query_style and isinstance(statement, expression.SelectBase) and not statement._is_textual and not statement.is_dml and statement._label_style is LABEL_STYLE_NONE ): self.statement = statement.set_label_style( LABEL_STYLE_TABLENAME_PLUS_COL ) else: self.statement = statement self._label_convention = self._column_naming_convention( ( statement._label_style if not statement._is_textual and not statement.is_dml else LABEL_STYLE_NONE ), self.use_legacy_query_style, ) _QueryEntity.to_compile_state( self, statement_container._raw_columns, self._entities, is_current_entities=True, ) self.current_path = statement_container._compile_options._current_path self._init_global_attributes( statement_container, compiler, process_criteria_for_toplevel=False, toplevel=True, ) if statement_container._with_options: for opt in statement_container._with_options: if opt._is_compile_state: opt.process_compile_state(self) if statement_container._with_context_options: for fn, key in statement_container._with_context_options: fn(self) self.primary_columns = [] self.secondary_columns = [] self.dedupe_columns = set() self.create_eager_joins = [] self._fallback_from_clauses = [] self.order_by = None if isinstance(self.statement, expression.TextClause): # TextClause has no "column" objects at all. for this case, # we generate columns from our _QueryEntity objects, then # flip on all the "please match no matter what" parameters. self.extra_criteria_entities = {} for entity in self._entities: entity.setup_compile_state(self) compiler._ordered_columns = compiler._textual_ordered_columns = ( False ) # enable looser result column matching. this is shown to be # needed by test_query.py::TextTest compiler._loose_column_name_matching = True for c in self.primary_columns: compiler.process( c, within_columns_clause=True, add_to_result_map=compiler._add_to_result_map, ) else: # for everyone else, Select, Insert, Update, TextualSelect, they # have column objects already. After much # experimentation here, the best approach seems to be, use # those columns completely, don't interfere with the compiler # at all; just in ORM land, use an adapter to convert from # our ORM columns to whatever columns are in the statement, # before we look in the result row. Adapt on names # to accept cases such as issue #9217, however also allow # this to be overridden for cases such as #9273. self._from_obj_alias = ORMStatementAdapter( _TraceAdaptRole.ADAPT_FROM_STATEMENT, self.statement, adapt_on_names=statement_container._adapt_on_names, ) return self def _adapt_col_list(self, cols, current_adapter): return cols def _get_current_adapter(self): return None def setup_dml_returning_compile_state(self, dml_mapper): """used by BulkORMInsert, Update, Delete to set up a handler for RETURNING to return ORM objects and expressions """ target_mapper = self.statement._propagate_attrs.get( "plugin_subject", None ) if self.statement.is_insert: adapter = _DMLBulkInsertReturningColFilter( target_mapper, dml_mapper ) elif self.statement.is_update or self.statement.is_delete: adapter = _DMLUpdateDeleteReturningColFilter( target_mapper, dml_mapper ) else: adapter = None if self.compile_options._is_star and (len(self._entities) != 1): raise sa_exc.CompileError( "Can't generate ORM query that includes multiple expressions " "at the same time as '*'; query for '*' alone if present" ) for entity in self._entities: entity.setup_dml_returning_compile_state(self, adapter) class FromStatement(GroupedElement, Generative, TypedReturnsRows[_TP]): """Core construct that represents a load of ORM objects from various :class:`.ReturnsRows` and other classes including: :class:`.Select`, :class:`.TextClause`, :class:`.TextualSelect`, :class:`.CompoundSelect`, :class`.Insert`, :class:`.Update`, and in theory, :class:`.Delete`. """ __visit_name__ = "orm_from_statement" _compile_options = ORMFromStatementCompileState.default_compile_options _compile_state_factory = ORMFromStatementCompileState.create_for_statement _for_update_arg = None element: Union[ExecutableReturnsRows, TextClause] _adapt_on_names: bool _traverse_internals = [ ("_raw_columns", InternalTraversal.dp_clauseelement_list), ("element", InternalTraversal.dp_clauseelement), ] + Executable._executable_traverse_internals _cache_key_traversal = _traverse_internals + [ ("_compile_options", InternalTraversal.dp_has_cache_key) ] is_from_statement = True def __init__( self, entities: Iterable[_ColumnsClauseArgument[Any]], element: Union[ExecutableReturnsRows, TextClause], _adapt_on_names: bool = True, ): self._raw_columns = [ coercions.expect( roles.ColumnsClauseRole, ent, apply_propagate_attrs=self, post_inspect=True, ) for ent in util.to_list(entities) ] self.element = element self.is_dml = element.is_dml self.is_select = element.is_select self.is_delete = element.is_delete self.is_insert = element.is_insert self.is_update = element.is_update self._label_style = ( element._label_style if is_select_base(element) else None ) self._adapt_on_names = _adapt_on_names def _compiler_dispatch(self, compiler, **kw): """provide a fixed _compiler_dispatch method. This is roughly similar to using the sqlalchemy.ext.compiler ``@compiles`` extension. """ compile_state = self._compile_state_factory(self, compiler, **kw) toplevel = not compiler.stack if toplevel: compiler.compile_state = compile_state return compiler.process(compile_state.statement, **kw) @property def column_descriptions(self): """Return a :term:`plugin-enabled` 'column descriptions' structure referring to the columns which are SELECTed by this statement. See the section :ref:`queryguide_inspection` for an overview of this feature. .. seealso:: :ref:`queryguide_inspection` - ORM background """ meth = cast( ORMSelectCompileState, SelectState.get_plugin_class(self) ).get_column_descriptions return meth(self) def _ensure_disambiguated_names(self): return self def get_children(self, **kw): yield from itertools.chain.from_iterable( element._from_objects for element in self._raw_columns ) yield from super().get_children(**kw) @property def _all_selected_columns(self): return self.element._all_selected_columns @property def _return_defaults(self): return self.element._return_defaults if is_dml(self.element) else None @property def _returning(self): return self.element._returning if is_dml(self.element) else None @property def _inline(self): return self.element._inline if is_insert_update(self.element) else None @sql.base.CompileState.plugin_for("orm", "compound_select") class CompoundSelectCompileState( AutoflushOnlyORMCompileState, CompoundSelectState ): pass @sql.base.CompileState.plugin_for("orm", "select") class ORMSelectCompileState(ORMCompileState, SelectState): _already_joined_edges = () _memoized_entities = _EMPTY_DICT _from_obj_alias = None _has_mapper_entities = False _has_orm_entities = False multi_row_eager_loaders = False eager_adding_joins = False compound_eager_adapter = None correlate = None correlate_except = None _where_criteria = () _having_criteria = () @classmethod def _create_orm_context( cls, statement: Union[Select, FromStatement], *, toplevel: bool, compiler: Optional[SQLCompiler], **kw: Any, ) -> ORMSelectCompileState: self = cls.__new__(cls) select_statement = statement # if we are a select() that was never a legacy Query, we won't # have ORM level compile options. statement._compile_options = cls.default_compile_options.safe_merge( statement._compile_options ) if select_statement._execution_options: # execution options should not impact the compilation of a # query, and at the moment subqueryloader is putting some things # in here that we explicitly don't want stuck in a cache. self.select_statement = select_statement._clone() self.select_statement._execution_options = util.immutabledict() else: self.select_statement = select_statement # indicates this select() came from Query.statement self.for_statement = select_statement._compile_options._for_statement # generally if we are from Query or directly from a select() self.use_legacy_query_style = ( select_statement._compile_options._use_legacy_query_style ) self._entities = [] self._primary_entity = None self._polymorphic_adapters = {} self.compile_options = select_statement._compile_options if not toplevel: # for subqueries, turn off eagerloads and set # "render_for_subquery". self.compile_options += { "_enable_eagerloads": False, "_render_for_subquery": True, } # determine label style. we can make different decisions here. # at the moment, trying to see if we can always use DISAMBIGUATE_ONLY # rather than LABEL_STYLE_NONE, and if we can use disambiguate style # for new style ORM selects too. if ( self.use_legacy_query_style and self.select_statement._label_style is LABEL_STYLE_LEGACY_ORM ): if not self.for_statement: self.label_style = LABEL_STYLE_TABLENAME_PLUS_COL else: self.label_style = LABEL_STYLE_DISAMBIGUATE_ONLY else: self.label_style = self.select_statement._label_style if select_statement._memoized_select_entities: self._memoized_entities = { memoized_entities: _QueryEntity.to_compile_state( self, memoized_entities._raw_columns, [], is_current_entities=False, ) for memoized_entities in ( select_statement._memoized_select_entities ) } # label_convention is stateful and will yield deduping keys if it # sees the same key twice. therefore it's important that it is not # invoked for the above "memoized" entities that aren't actually # in the columns clause self._label_convention = self._column_naming_convention( statement._label_style, self.use_legacy_query_style ) _QueryEntity.to_compile_state( self, select_statement._raw_columns, self._entities, is_current_entities=True, ) self.current_path = select_statement._compile_options._current_path self.eager_order_by = () self._init_global_attributes( select_statement, compiler, toplevel=toplevel, process_criteria_for_toplevel=False, ) if toplevel and ( select_statement._with_options or select_statement._memoized_select_entities ): for ( memoized_entities ) in select_statement._memoized_select_entities: for opt in memoized_entities._with_options: if opt._is_compile_state: opt.process_compile_state_replaced_entities( self, [ ent for ent in self._memoized_entities[ memoized_entities ] if isinstance(ent, _MapperEntity) ], ) for opt in self.select_statement._with_options: if opt._is_compile_state: opt.process_compile_state(self) # uncomment to print out the context.attributes structure # after it's been set up above # self._dump_option_struct() if select_statement._with_context_options: for fn, key in select_statement._with_context_options: fn(self) self.primary_columns = [] self.secondary_columns = [] self.dedupe_columns = set() self.eager_joins = {} self.extra_criteria_entities = {} self.create_eager_joins = [] self._fallback_from_clauses = [] # normalize the FROM clauses early by themselves, as this makes # it an easier job when we need to assemble a JOIN onto these, # for select.join() as well as joinedload(). As of 1.4 there are now # potentially more complex sets of FROM objects here as the use # of lambda statements for lazyload, load_on_pk etc. uses more # cloning of the select() construct. See #6495 self.from_clauses = self._normalize_froms( info.selectable for info in select_statement._from_obj ) # this is a fairly arbitrary break into a second method, # so it might be nicer to break up create_for_statement() # and _setup_for_generate into three or four logical sections self._setup_for_generate() SelectState.__init__(self, self.statement, compiler, **kw) return self def _dump_option_struct(self): print("\n---------------------------------------------------\n") print(f"current path: {self.current_path}") for key in self.attributes: if isinstance(key, tuple) and key[0] == "loader": print(f"\nLoader: {PathRegistry.coerce(key[1])}") print(f" {self.attributes[key]}") print(f" {self.attributes[key].__dict__}") elif isinstance(key, tuple) and key[0] == "path_with_polymorphic": print(f"\nWith Polymorphic: {PathRegistry.coerce(key[1])}") print(f" {self.attributes[key]}") def _setup_for_generate(self): query = self.select_statement self.statement = None self._join_entities = () if self.compile_options._set_base_alias: # legacy Query only self._set_select_from_alias() for memoized_entities in query._memoized_select_entities: if memoized_entities._setup_joins: self._join( memoized_entities._setup_joins, self._memoized_entities[memoized_entities], ) if query._setup_joins: self._join(query._setup_joins, self._entities) current_adapter = self._get_current_adapter() if query._where_criteria: self._where_criteria = query._where_criteria if current_adapter: self._where_criteria = tuple( current_adapter(crit, True) for crit in self._where_criteria ) # TODO: some complexity with order_by here was due to mapper.order_by. # now that this is removed we can hopefully make order_by / # group_by act identically to how they are in Core select. self.order_by = ( self._adapt_col_list(query._order_by_clauses, current_adapter) if current_adapter and query._order_by_clauses not in (None, False) else query._order_by_clauses ) if query._having_criteria: self._having_criteria = tuple( current_adapter(crit, True) if current_adapter else crit for crit in query._having_criteria ) self.group_by = ( self._adapt_col_list( util.flatten_iterator(query._group_by_clauses), current_adapter ) if current_adapter and query._group_by_clauses not in (None, False) else query._group_by_clauses or None ) if self.eager_order_by: adapter = self.from_clauses[0]._target_adapter self.eager_order_by = adapter.copy_and_process(self.eager_order_by) if query._distinct_on: self.distinct_on = self._adapt_col_list( query._distinct_on, current_adapter ) else: self.distinct_on = () self.distinct = query._distinct if query._correlate: # ORM mapped entities that are mapped to joins can be passed # to .correlate, so here they are broken into their component # tables. self.correlate = tuple( util.flatten_iterator( sql_util.surface_selectables(s) if s is not None else None for s in query._correlate ) ) elif query._correlate_except is not None: self.correlate_except = tuple( util.flatten_iterator( sql_util.surface_selectables(s) if s is not None else None for s in query._correlate_except ) ) elif not query._auto_correlate: self.correlate = (None,) # PART II self._for_update_arg = query._for_update_arg if self.compile_options._is_star and (len(self._entities) != 1): raise sa_exc.CompileError( "Can't generate ORM query that includes multiple expressions " "at the same time as '*'; query for '*' alone if present" ) for entity in self._entities: entity.setup_compile_state(self) for rec in self.create_eager_joins: strategy = rec[0] strategy(self, *rec[1:]) # else "load from discrete FROMs" mode, # i.e. when each _MappedEntity has its own FROM if self.compile_options._enable_single_crit: self._adjust_for_extra_criteria() if not self.primary_columns: if self.compile_options._only_load_props: assert False, "no columns were included in _only_load_props" raise sa_exc.InvalidRequestError( "Query contains no columns with which to SELECT from." ) if not self.from_clauses: self.from_clauses = list(self._fallback_from_clauses) if self.order_by is False: self.order_by = None if ( self.multi_row_eager_loaders and self.eager_adding_joins and self._should_nest_selectable ): self.statement = self._compound_eager_statement() else: self.statement = self._simple_statement() if self.for_statement: ezero = self._mapper_zero() if ezero is not None: # TODO: this goes away once we get rid of the deep entity # thing self.statement = self.statement._annotate( {"deepentity": ezero} ) @classmethod def _create_entities_collection(cls, query, legacy): """Creates a partial ORMSelectCompileState that includes the full collection of _MapperEntity and other _QueryEntity objects. Supports a few remaining use cases that are pre-compilation but still need to gather some of the column / adaption information. """ self = cls.__new__(cls) self._entities = [] self._primary_entity = None self._polymorphic_adapters = {} self._label_convention = self._column_naming_convention( query._label_style, legacy ) # entities will also set up polymorphic adapters for mappers # that have with_polymorphic configured _QueryEntity.to_compile_state( self, query._raw_columns, self._entities, is_current_entities=True ) return self @classmethod def determine_last_joined_entity(cls, statement): setup_joins = statement._setup_joins return _determine_last_joined_entity(setup_joins, None) @classmethod def all_selected_columns(cls, statement): for element in statement._raw_columns: if ( element.is_selectable and "entity_namespace" in element._annotations ): ens = element._annotations["entity_namespace"] if not ens.is_mapper and not ens.is_aliased_class: yield from _select_iterables([element]) else: yield from _select_iterables(ens._all_column_expressions) else: yield from _select_iterables([element]) @classmethod def get_columns_clause_froms(cls, statement): return cls._normalize_froms( itertools.chain.from_iterable( ( element._from_objects if "parententity" not in element._annotations else [ element._annotations[ "parententity" ].__clause_element__() ] ) for element in statement._raw_columns ) ) @classmethod def from_statement(cls, statement, from_statement): from_statement = coercions.expect( roles.ReturnsRowsRole, from_statement, apply_propagate_attrs=statement, ) stmt = FromStatement(statement._raw_columns, from_statement) stmt.__dict__.update( _with_options=statement._with_options, _with_context_options=statement._with_context_options, _execution_options=statement._execution_options, _propagate_attrs=statement._propagate_attrs, ) return stmt def _set_select_from_alias(self): """used only for legacy Query cases""" query = self.select_statement # query assert self.compile_options._set_base_alias assert len(query._from_obj) == 1 adapter = self._get_select_from_alias_from_obj(query._from_obj[0]) if adapter: self.compile_options += {"_enable_single_crit": False} self._from_obj_alias = adapter def _get_select_from_alias_from_obj(self, from_obj): """used only for legacy Query cases""" info = from_obj if "parententity" in info._annotations: info = info._annotations["parententity"] if hasattr(info, "mapper"): if not info.is_aliased_class: raise sa_exc.ArgumentError( "A selectable (FromClause) instance is " "expected when the base alias is being set." ) else: return info._adapter elif isinstance(info.selectable, sql.selectable.AliasedReturnsRows): equivs = self._all_equivs() assert info is info.selectable return ORMStatementAdapter( _TraceAdaptRole.LEGACY_SELECT_FROM_ALIAS, info.selectable, equivalents=equivs, ) else: return None def _mapper_zero(self): """return the Mapper associated with the first QueryEntity.""" return self._entities[0].mapper def _entity_zero(self): """Return the 'entity' (mapper or AliasedClass) associated with the first QueryEntity, or alternatively the 'select from' entity if specified.""" for ent in self.from_clauses: if "parententity" in ent._annotations: return ent._annotations["parententity"] for qent in self._entities: if qent.entity_zero: return qent.entity_zero return None def _only_full_mapper_zero(self, methname): if self._entities != [self._primary_entity]: raise sa_exc.InvalidRequestError( "%s() can only be used against " "a single mapped class." % methname ) return self._primary_entity.entity_zero def _only_entity_zero(self, rationale=None): if len(self._entities) > 1: raise sa_exc.InvalidRequestError( rationale or "This operation requires a Query " "against a single mapper." ) return self._entity_zero() def _all_equivs(self): equivs = {} for memoized_entities in self._memoized_entities.values(): for ent in [ ent for ent in memoized_entities if isinstance(ent, _MapperEntity) ]: equivs.update(ent.mapper._equivalent_columns) for ent in [ ent for ent in self._entities if isinstance(ent, _MapperEntity) ]: equivs.update(ent.mapper._equivalent_columns) return equivs def _compound_eager_statement(self): # for eager joins present and LIMIT/OFFSET/DISTINCT, # wrap the query inside a select, # then append eager joins onto that if self.order_by: # the default coercion for ORDER BY is now the OrderByRole, # which adds an additional post coercion to ByOfRole in that # elements are converted into label references. For the # eager load / subquery wrapping case, we need to un-coerce # the original expressions outside of the label references # in order to have them render. unwrapped_order_by = [ ( elem.element if isinstance(elem, sql.elements._label_reference) else elem ) for elem in self.order_by ] order_by_col_expr = sql_util.expand_column_list_from_order_by( self.primary_columns, unwrapped_order_by ) else: order_by_col_expr = [] unwrapped_order_by = None # put FOR UPDATE on the inner query, where MySQL will honor it, # as well as if it has an OF so PostgreSQL can use it. inner = self._select_statement( self.primary_columns + [c for c in order_by_col_expr if c not in self.dedupe_columns], self.from_clauses, self._where_criteria, self._having_criteria, self.label_style, self.order_by, for_update=self._for_update_arg, hints=self.select_statement._hints, statement_hints=self.select_statement._statement_hints, correlate=self.correlate, correlate_except=self.correlate_except, **self._select_args, ) inner = inner.alias() equivs = self._all_equivs() self.compound_eager_adapter = ORMStatementAdapter( _TraceAdaptRole.COMPOUND_EAGER_STATEMENT, inner, equivalents=equivs ) statement = future.select( *([inner] + self.secondary_columns) # use_labels=self.labels ) statement._label_style = self.label_style # Oracle Database however does not allow FOR UPDATE on the subquery, # and the Oracle Database dialects ignore it, plus for PostgreSQL, # MySQL we expect that all elements of the row are locked, so also put # it on the outside (except in the case of PG when OF is used) if ( self._for_update_arg is not None and self._for_update_arg.of is None ): statement._for_update_arg = self._for_update_arg from_clause = inner for eager_join in self.eager_joins.values(): # EagerLoader places a 'stop_on' attribute on the join, # giving us a marker as to where the "splice point" of # the join should be from_clause = sql_util.splice_joins( from_clause, eager_join, eager_join.stop_on ) statement.select_from.non_generative(statement, from_clause) if unwrapped_order_by: statement.order_by.non_generative( statement, *self.compound_eager_adapter.copy_and_process( unwrapped_order_by ), ) statement.order_by.non_generative(statement, *self.eager_order_by) return statement def _simple_statement(self): statement = self._select_statement( self.primary_columns + self.secondary_columns, tuple(self.from_clauses) + tuple(self.eager_joins.values()), self._where_criteria, self._having_criteria, self.label_style, self.order_by, for_update=self._for_update_arg, hints=self.select_statement._hints, statement_hints=self.select_statement._statement_hints, correlate=self.correlate, correlate_except=self.correlate_except, **self._select_args, ) if self.eager_order_by: statement.order_by.non_generative(statement, *self.eager_order_by) return statement def _select_statement( self, raw_columns, from_obj, where_criteria, having_criteria, label_style, order_by, for_update, hints, statement_hints, correlate, correlate_except, limit_clause, offset_clause, fetch_clause, fetch_clause_options, distinct, distinct_on, prefixes, suffixes, group_by, independent_ctes, independent_ctes_opts, ): statement = Select._create_raw_select( _raw_columns=raw_columns, _from_obj=from_obj, _label_style=label_style, ) if where_criteria: statement._where_criteria = where_criteria if having_criteria: statement._having_criteria = having_criteria if order_by: statement._order_by_clauses += tuple(order_by) if distinct_on: statement.distinct.non_generative(statement, *distinct_on) elif distinct: statement.distinct.non_generative(statement) if group_by: statement._group_by_clauses += tuple(group_by) statement._limit_clause = limit_clause statement._offset_clause = offset_clause statement._fetch_clause = fetch_clause statement._fetch_clause_options = fetch_clause_options statement._independent_ctes = independent_ctes statement._independent_ctes_opts = independent_ctes_opts if prefixes: statement._prefixes = prefixes if suffixes: statement._suffixes = suffixes statement._for_update_arg = for_update if hints: statement._hints = hints if statement_hints: statement._statement_hints = statement_hints if correlate: statement.correlate.non_generative(statement, *correlate) if correlate_except is not None: statement.correlate_except.non_generative( statement, *correlate_except ) return statement def _adapt_polymorphic_element(self, element): if "parententity" in element._annotations: search = element._annotations["parententity"] alias = self._polymorphic_adapters.get(search, None) if alias: return alias.adapt_clause(element) if isinstance(element, expression.FromClause): search = element elif hasattr(element, "table"): search = element.table else: return None alias = self._polymorphic_adapters.get(search, None) if alias: return alias.adapt_clause(element) def _adapt_col_list(self, cols, current_adapter): if current_adapter: return [current_adapter(o, True) for o in cols] else: return cols def _get_current_adapter(self): adapters = [] if self._from_obj_alias: # used for legacy going forward for query set_ops, e.g. # union(), union_all(), etc. # 1.4 and previously, also used for from_self(), # select_entity_from() # # for the "from obj" alias, apply extra rule to the # 'ORM only' check, if this query were generated from a # subquery of itself, i.e. _from_selectable(), apply adaption # to all SQL constructs. adapters.append( ( True, self._from_obj_alias.replace, ) ) # this was *hopefully* the only adapter we were going to need # going forward...however, we unfortunately need _from_obj_alias # for query.union(), which we can't drop if self._polymorphic_adapters: adapters.append((False, self._adapt_polymorphic_element)) if not adapters: return None def _adapt_clause(clause, as_filter): # do we adapt all expression elements or only those # tagged as 'ORM' constructs ? def replace(elem): is_orm_adapt = ( "_orm_adapt" in elem._annotations or "parententity" in elem._annotations ) for always_adapt, adapter in adapters: if is_orm_adapt or always_adapt: e = adapter(elem) if e is not None: return e return visitors.replacement_traverse(clause, {}, replace) return _adapt_clause def _join(self, args, entities_collection): for right, onclause, from_, flags in args: isouter = flags["isouter"] full = flags["full"] right = inspect(right) if onclause is not None: onclause = inspect(onclause) if isinstance(right, interfaces.PropComparator): if onclause is not None: raise sa_exc.InvalidRequestError( "No 'on clause' argument may be passed when joining " "to a relationship path as a target" ) onclause = right right = None elif "parententity" in right._annotations: right = right._annotations["parententity"] if onclause is None: if not right.is_selectable and not hasattr(right, "mapper"): raise sa_exc.ArgumentError( "Expected mapped entity or " "selectable/table as join target" ) if isinstance(onclause, interfaces.PropComparator): # descriptor/property given (or determined); this tells us # explicitly what the expected "left" side of the join is. of_type = getattr(onclause, "_of_type", None) if right is None: if of_type: right = of_type else: right = onclause.property try: right = right.entity except AttributeError as err: raise sa_exc.ArgumentError( "Join target %s does not refer to a " "mapped entity" % right ) from err left = onclause._parententity prop = onclause.property if not isinstance(onclause, attributes.QueryableAttribute): onclause = prop # check for this path already present. don't render in that # case. if (left, right, prop.key) in self._already_joined_edges: continue if from_ is not None: if ( from_ is not left and from_._annotations.get("parententity", None) is not left ): raise sa_exc.InvalidRequestError( "explicit from clause %s does not match left side " "of relationship attribute %s" % ( from_._annotations.get("parententity", from_), onclause, ) ) elif from_ is not None: prop = None left = from_ else: # no descriptor/property given; we will need to figure out # what the effective "left" side is prop = left = None # figure out the final "left" and "right" sides and create an # ORMJoin to add to our _from_obj tuple self._join_left_to_right( entities_collection, left, right, onclause, prop, isouter, full, ) def _join_left_to_right( self, entities_collection, left, right, onclause, prop, outerjoin, full, ): """given raw "left", "right", "onclause" parameters consumed from a particular key within _join(), add a real ORMJoin object to our _from_obj list (or augment an existing one) """ if left is None: # left not given (e.g. no relationship object/name specified) # figure out the best "left" side based on our existing froms / # entities assert prop is None ( left, replace_from_obj_index, use_entity_index, ) = self._join_determine_implicit_left_side( entities_collection, left, right, onclause ) else: # left is given via a relationship/name, or as explicit left side. # Determine where in our # "froms" list it should be spliced/appended as well as what # existing entity it corresponds to. ( replace_from_obj_index, use_entity_index, ) = self._join_place_explicit_left_side(entities_collection, left) if left is right: raise sa_exc.InvalidRequestError( "Can't construct a join from %s to %s, they " "are the same entity" % (left, right) ) # the right side as given often needs to be adapted. additionally # a lot of things can be wrong with it. handle all that and # get back the new effective "right" side r_info, right, onclause = self._join_check_and_adapt_right_side( left, right, onclause, prop ) if not r_info.is_selectable: extra_criteria = self._get_extra_criteria(r_info) else: extra_criteria = () if replace_from_obj_index is not None: # splice into an existing element in the # self._from_obj list left_clause = self.from_clauses[replace_from_obj_index] self.from_clauses = ( self.from_clauses[:replace_from_obj_index] + [ _ORMJoin( left_clause, right, onclause, isouter=outerjoin, full=full, _extra_criteria=extra_criteria, ) ] + self.from_clauses[replace_from_obj_index + 1 :] ) else: # add a new element to the self._from_obj list if use_entity_index is not None: # make use of _MapperEntity selectable, which is usually # entity_zero.selectable, but if with_polymorphic() were used # might be distinct assert isinstance( entities_collection[use_entity_index], _MapperEntity ) left_clause = entities_collection[use_entity_index].selectable else: left_clause = left self.from_clauses = self.from_clauses + [ _ORMJoin( left_clause, r_info, onclause, isouter=outerjoin, full=full, _extra_criteria=extra_criteria, ) ] def _join_determine_implicit_left_side( self, entities_collection, left, right, onclause ): """When join conditions don't express the left side explicitly, determine if an existing FROM or entity in this query can serve as the left hand side. """ # when we are here, it means join() was called without an ORM- # specific way of telling us what the "left" side is, e.g.: # # join(RightEntity) # # or # # join(RightEntity, RightEntity.foo == LeftEntity.bar) # r_info = inspect(right) replace_from_obj_index = use_entity_index = None if self.from_clauses: # we have a list of FROMs already. So by definition this # join has to connect to one of those FROMs. indexes = sql_util.find_left_clause_to_join_from( self.from_clauses, r_info.selectable, onclause ) if len(indexes) == 1: replace_from_obj_index = indexes[0] left = self.from_clauses[replace_from_obj_index] elif len(indexes) > 1: raise sa_exc.InvalidRequestError( "Can't determine which FROM clause to join " "from, there are multiple FROMS which can " "join to this entity. Please use the .select_from() " "method to establish an explicit left side, as well as " "providing an explicit ON clause if not present already " "to help resolve the ambiguity." ) else: raise sa_exc.InvalidRequestError( "Don't know how to join to %r. " "Please use the .select_from() " "method to establish an explicit left side, as well as " "providing an explicit ON clause if not present already " "to help resolve the ambiguity." % (right,) ) elif entities_collection: # we have no explicit FROMs, so the implicit left has to # come from our list of entities. potential = {} for entity_index, ent in enumerate(entities_collection): entity = ent.entity_zero_or_selectable if entity is None: continue ent_info = inspect(entity) if ent_info is r_info: # left and right are the same, skip continue # by using a dictionary with the selectables as keys this # de-duplicates those selectables as occurs when the query is # against a series of columns from the same selectable if isinstance(ent, _MapperEntity): potential[ent.selectable] = (entity_index, entity) else: potential[ent_info.selectable] = (None, entity) all_clauses = list(potential.keys()) indexes = sql_util.find_left_clause_to_join_from( all_clauses, r_info.selectable, onclause ) if len(indexes) == 1: use_entity_index, left = potential[all_clauses[indexes[0]]] elif len(indexes) > 1: raise sa_exc.InvalidRequestError( "Can't determine which FROM clause to join " "from, there are multiple FROMS which can " "join to this entity. Please use the .select_from() " "method to establish an explicit left side, as well as " "providing an explicit ON clause if not present already " "to help resolve the ambiguity." ) else: raise sa_exc.InvalidRequestError( "Don't know how to join to %r. " "Please use the .select_from() " "method to establish an explicit left side, as well as " "providing an explicit ON clause if not present already " "to help resolve the ambiguity." % (right,) ) else: raise sa_exc.InvalidRequestError( "No entities to join from; please use " "select_from() to establish the left " "entity/selectable of this join" ) return left, replace_from_obj_index, use_entity_index def _join_place_explicit_left_side(self, entities_collection, left): """When join conditions express a left side explicitly, determine where in our existing list of FROM clauses we should join towards, or if we need to make a new join, and if so is it from one of our existing entities. """ # when we are here, it means join() was called with an indicator # as to an exact left side, which means a path to a # Relationship was given, e.g.: # # join(RightEntity, LeftEntity.right) # # or # # join(LeftEntity.right) # # as well as string forms: # # join(RightEntity, "right") # # etc. # replace_from_obj_index = use_entity_index = None l_info = inspect(left) if self.from_clauses: indexes = sql_util.find_left_clause_that_matches_given( self.from_clauses, l_info.selectable ) if len(indexes) > 1: raise sa_exc.InvalidRequestError( "Can't identify which entity in which to assign the " "left side of this join. Please use a more specific " "ON clause." ) # have an index, means the left side is already present in # an existing FROM in the self._from_obj tuple if indexes: replace_from_obj_index = indexes[0] # no index, means we need to add a new element to the # self._from_obj tuple # no from element present, so we will have to add to the # self._from_obj tuple. Determine if this left side matches up # with existing mapper entities, in which case we want to apply the # aliasing / adaptation rules present on that entity if any if ( replace_from_obj_index is None and entities_collection and hasattr(l_info, "mapper") ): for idx, ent in enumerate(entities_collection): # TODO: should we be checking for multiple mapper entities # matching? if isinstance(ent, _MapperEntity) and ent.corresponds_to(left): use_entity_index = idx break return replace_from_obj_index, use_entity_index def _join_check_and_adapt_right_side(self, left, right, onclause, prop): """transform the "right" side of the join as well as the onclause according to polymorphic mapping translations, aliasing on the query or on the join, special cases where the right and left side have overlapping tables. """ l_info = inspect(left) r_info = inspect(right) overlap = False right_mapper = getattr(r_info, "mapper", None) # if the target is a joined inheritance mapping, # be more liberal about auto-aliasing. if right_mapper and ( right_mapper.with_polymorphic or isinstance(right_mapper.persist_selectable, expression.Join) ): for from_obj in self.from_clauses or [l_info.selectable]: if sql_util.selectables_overlap( l_info.selectable, from_obj ) and sql_util.selectables_overlap( from_obj, r_info.selectable ): overlap = True break if overlap and l_info.selectable is r_info.selectable: raise sa_exc.InvalidRequestError( "Can't join table/selectable '%s' to itself" % l_info.selectable ) right_mapper, right_selectable, right_is_aliased = ( getattr(r_info, "mapper", None), r_info.selectable, getattr(r_info, "is_aliased_class", False), ) if ( right_mapper and prop and not right_mapper.common_parent(prop.mapper) ): raise sa_exc.InvalidRequestError( "Join target %s does not correspond to " "the right side of join condition %s" % (right, onclause) ) # _join_entities is used as a hint for single-table inheritance # purposes at the moment if hasattr(r_info, "mapper"): self._join_entities += (r_info,) need_adapter = False # test for joining to an unmapped selectable as the target if r_info.is_clause_element: if prop: right_mapper = prop.mapper if right_selectable._is_lateral: # orm_only is disabled to suit the case where we have to # adapt an explicit correlate(Entity) - the select() loses # the ORM-ness in this case right now, ideally it would not current_adapter = self._get_current_adapter() if current_adapter is not None: # TODO: we had orm_only=False here before, removing # it didn't break things. if we identify the rationale, # may need to apply "_orm_only" annotation here. right = current_adapter(right, True) elif prop: # joining to selectable with a mapper property given # as the ON clause if not right_selectable.is_derived_from( right_mapper.persist_selectable ): raise sa_exc.InvalidRequestError( "Selectable '%s' is not derived from '%s'" % ( right_selectable.description, right_mapper.persist_selectable.description, ) ) # if the destination selectable is a plain select(), # turn it into an alias(). if isinstance(right_selectable, expression.SelectBase): right_selectable = coercions.expect( roles.FromClauseRole, right_selectable ) need_adapter = True # make the right hand side target into an ORM entity right = AliasedClass(right_mapper, right_selectable) util.warn_deprecated( "An alias is being generated automatically against " "joined entity %s for raw clauseelement, which is " "deprecated and will be removed in a later release. " "Use the aliased() " "construct explicitly, see the linked example." % right_mapper, "1.4", code="xaj1", ) # test for overlap: # orm/inheritance/relationships.py # SelfReferentialM2MTest aliased_entity = right_mapper and not right_is_aliased and overlap if not need_adapter and aliased_entity: # there are a few places in the ORM that automatic aliasing # is still desirable, and can't be automatic with a Core # only approach. For illustrations of "overlaps" see # test/orm/inheritance/test_relationships.py. There are also # general overlap cases with many-to-many tables where automatic # aliasing is desirable. right = AliasedClass(right, flat=True) need_adapter = True util.warn( "An alias is being generated automatically against " "joined entity %s due to overlapping tables. This is a " "legacy pattern which may be " "deprecated in a later release. Use the " "aliased(<entity>, flat=True) " "construct explicitly, see the linked example." % right_mapper, code="xaj2", ) if need_adapter: # if need_adapter is True, we are in a deprecated case and # a warning has been emitted. assert right_mapper adapter = ORMAdapter( _TraceAdaptRole.DEPRECATED_JOIN_ADAPT_RIGHT_SIDE, inspect(right), equivalents=right_mapper._equivalent_columns, ) # if an alias() on the right side was generated, # which is intended to wrap a the right side in a subquery, # ensure that columns retrieved from this target in the result # set are also adapted. self._mapper_loads_polymorphically_with(right_mapper, adapter) elif ( not r_info.is_clause_element and not right_is_aliased and right_mapper._has_aliased_polymorphic_fromclause ): # for the case where the target mapper has a with_polymorphic # set up, ensure an adapter is set up for criteria that works # against this mapper. Previously, this logic used to # use the "create_aliases or aliased_entity" case to generate # an aliased() object, but this creates an alias that isn't # strictly necessary. # see test/orm/test_core_compilation.py # ::RelNaturalAliasedJoinsTest::test_straight # and similar self._mapper_loads_polymorphically_with( right_mapper, ORMAdapter( _TraceAdaptRole.WITH_POLYMORPHIC_ADAPTER_RIGHT_JOIN, right_mapper, selectable=right_mapper.selectable, equivalents=right_mapper._equivalent_columns, ), ) # if the onclause is a ClauseElement, adapt it with any # adapters that are in place right now if isinstance(onclause, expression.ClauseElement): current_adapter = self._get_current_adapter() if current_adapter: onclause = current_adapter(onclause, True) # if joining on a MapperProperty path, # track the path to prevent redundant joins if prop: self._already_joined_edges += ((left, right, prop.key),) return inspect(right), right, onclause @property def _select_args(self): return { "limit_clause": self.select_statement._limit_clause, "offset_clause": self.select_statement._offset_clause, "distinct": self.distinct, "distinct_on": self.distinct_on, "prefixes": self.select_statement._prefixes, "suffixes": self.select_statement._suffixes, "group_by": self.group_by or None, "fetch_clause": self.select_statement._fetch_clause, "fetch_clause_options": ( self.select_statement._fetch_clause_options ), "independent_ctes": self.select_statement._independent_ctes, "independent_ctes_opts": ( self.select_statement._independent_ctes_opts ), } @property def _should_nest_selectable(self): kwargs = self._select_args return ( kwargs.get("limit_clause") is not None or kwargs.get("offset_clause") is not None or kwargs.get("distinct", False) or kwargs.get("distinct_on", ()) or kwargs.get("group_by", False) ) def _get_extra_criteria(self, ext_info): if ( "additional_entity_criteria", ext_info.mapper, ) in self.global_attributes: return tuple( ae._resolve_where_criteria(ext_info) for ae in self.global_attributes[ ("additional_entity_criteria", ext_info.mapper) ] if (ae.include_aliases or ae.entity is ext_info) and ae._should_include(self) ) else: return () def _adjust_for_extra_criteria(self): """Apply extra criteria filtering. For all distinct single-table-inheritance mappers represented in the columns clause of this query, as well as the "select from entity", add criterion to the WHERE clause of the given QueryContext such that only the appropriate subtypes are selected from the total results. Additionally, add WHERE criteria originating from LoaderCriteriaOptions associated with the global context. """ for fromclause in self.from_clauses: ext_info = fromclause._annotations.get("parententity", None) if ( ext_info and ( ext_info.mapper._single_table_criterion is not None or ("additional_entity_criteria", ext_info.mapper) in self.global_attributes ) and ext_info not in self.extra_criteria_entities ): self.extra_criteria_entities[ext_info] = ( ext_info, ext_info._adapter if ext_info.is_aliased_class else None, ) search = set(self.extra_criteria_entities.values()) for ext_info, adapter in search: if ext_info in self._join_entities: continue single_crit = ext_info.mapper._single_table_criterion if self.compile_options._for_refresh_state: additional_entity_criteria = [] else: additional_entity_criteria = self._get_extra_criteria(ext_info) if single_crit is not None: additional_entity_criteria += (single_crit,) current_adapter = self._get_current_adapter() for crit in additional_entity_criteria: if adapter: crit = adapter.traverse(crit) if current_adapter: crit = sql_util._deep_annotate(crit, {"_orm_adapt": True}) crit = current_adapter(crit, False) self._where_criteria += (crit,) def _column_descriptions( query_or_select_stmt: Union[Query, Select, FromStatement], compile_state: Optional[ORMSelectCompileState] = None, legacy: bool = False, ) -> List[ORMColumnDescription]: if compile_state is None: compile_state = ORMSelectCompileState._create_entities_collection( query_or_select_stmt, legacy=legacy ) ctx = compile_state d = [ { "name": ent._label_name, "type": ent.type, "aliased": getattr(insp_ent, "is_aliased_class", False), "expr": ent.expr, "entity": ( getattr(insp_ent, "entity", None) if ent.entity_zero is not None and not insp_ent.is_clause_element else None ), } for ent, insp_ent in [ (_ent, _ent.entity_zero) for _ent in ctx._entities ] ] return d def _legacy_filter_by_entity_zero( query_or_augmented_select: Union[Query[Any], Select[Any]] ) -> Optional[_InternalEntityType[Any]]: self = query_or_augmented_select if self._setup_joins: _last_joined_entity = self._last_joined_entity if _last_joined_entity is not None: return _last_joined_entity if self._from_obj and "parententity" in self._from_obj[0]._annotations: return self._from_obj[0]._annotations["parententity"] return _entity_from_pre_ent_zero(self) def _entity_from_pre_ent_zero( query_or_augmented_select: Union[Query[Any], Select[Any]] ) -> Optional[_InternalEntityType[Any]]: self = query_or_augmented_select if not self._raw_columns: return None ent = self._raw_columns[0] if "parententity" in ent._annotations: return ent._annotations["parententity"] elif isinstance(ent, ORMColumnsClauseRole): return ent.entity elif "bundle" in ent._annotations: return ent._annotations["bundle"] else: return ent def _determine_last_joined_entity( setup_joins: Tuple[_SetupJoinsElement, ...], entity_zero: Optional[_InternalEntityType[Any]] = None, ) -> Optional[Union[_InternalEntityType[Any], _JoinTargetElement]]: if not setup_joins: return None (target, onclause, from_, flags) = setup_joins[-1] if isinstance( target, attributes.QueryableAttribute, ): return target.entity else: return target class _QueryEntity: """represent an entity column returned within a Query result.""" __slots__ = () supports_single_entity: bool _non_hashable_value = False _null_column_type = False use_id_for_hash = False _label_name: Optional[str] type: Union[Type[Any], TypeEngine[Any]] expr: Union[_InternalEntityType, ColumnElement[Any]] entity_zero: Optional[_InternalEntityType] def setup_compile_state(self, compile_state: ORMCompileState) -> None: raise NotImplementedError() def setup_dml_returning_compile_state( self, compile_state: ORMCompileState, adapter: Optional[_DMLReturningColFilter], ) -> None: raise NotImplementedError() def row_processor(self, context, result): raise NotImplementedError() @classmethod def to_compile_state( cls, compile_state, entities, entities_collection, is_current_entities ): for idx, entity in enumerate(entities): if entity._is_lambda_element: if entity._is_sequence: cls.to_compile_state( compile_state, entity._resolved, entities_collection, is_current_entities, ) continue else: entity = entity._resolved if entity.is_clause_element: if entity.is_selectable: if "parententity" in entity._annotations: _MapperEntity( compile_state, entity, entities_collection, is_current_entities, ) else: _ColumnEntity._for_columns( compile_state, entity._select_iterable, entities_collection, idx, is_current_entities, ) else: if entity._annotations.get("bundle", False): _BundleEntity( compile_state, entity, entities_collection, is_current_entities, ) elif entity._is_clause_list: # this is legacy only - test_composites.py # test_query_cols_legacy _ColumnEntity._for_columns( compile_state, entity._select_iterable, entities_collection, idx, is_current_entities, ) else: _ColumnEntity._for_columns( compile_state, [entity], entities_collection, idx, is_current_entities, ) elif entity.is_bundle: _BundleEntity(compile_state, entity, entities_collection) return entities_collection class _MapperEntity(_QueryEntity): """mapper/class/AliasedClass entity""" __slots__ = ( "expr", "mapper", "entity_zero", "is_aliased_class", "path", "_extra_entities", "_label_name", "_with_polymorphic_mappers", "selectable", "_polymorphic_discriminator", ) expr: _InternalEntityType mapper: Mapper[Any] entity_zero: _InternalEntityType is_aliased_class: bool path: PathRegistry _label_name: str def __init__( self, compile_state, entity, entities_collection, is_current_entities ): entities_collection.append(self) if is_current_entities: if compile_state._primary_entity is None: compile_state._primary_entity = self compile_state._has_mapper_entities = True compile_state._has_orm_entities = True entity = entity._annotations["parententity"] entity._post_inspect ext_info = self.entity_zero = entity entity = ext_info.entity self.expr = entity self.mapper = mapper = ext_info.mapper self._extra_entities = (self.expr,) if ext_info.is_aliased_class: self._label_name = ext_info.name else: self._label_name = mapper.class_.__name__ self.is_aliased_class = ext_info.is_aliased_class self.path = ext_info._path_registry self.selectable = ext_info.selectable self._with_polymorphic_mappers = ext_info.with_polymorphic_mappers self._polymorphic_discriminator = ext_info.polymorphic_on if mapper._should_select_with_poly_adapter: compile_state._create_with_polymorphic_adapter( ext_info, self.selectable ) supports_single_entity = True _non_hashable_value = True use_id_for_hash = True @property def type(self): return self.mapper.class_ @property def entity_zero_or_selectable(self): return self.entity_zero def corresponds_to(self, entity): return _entity_corresponds_to(self.entity_zero, entity) def _get_entity_clauses(self, compile_state): adapter = None if not self.is_aliased_class: if compile_state._polymorphic_adapters: adapter = compile_state._polymorphic_adapters.get( self.mapper, None ) else: adapter = self.entity_zero._adapter if adapter: if compile_state._from_obj_alias: ret = adapter.wrap(compile_state._from_obj_alias) else: ret = adapter else: ret = compile_state._from_obj_alias return ret def row_processor(self, context, result): compile_state = context.compile_state adapter = self._get_entity_clauses(compile_state) if compile_state.compound_eager_adapter and adapter: adapter = adapter.wrap(compile_state.compound_eager_adapter) elif not adapter: adapter = compile_state.compound_eager_adapter if compile_state._primary_entity is self: only_load_props = compile_state.compile_options._only_load_props refresh_state = context.refresh_state else: only_load_props = refresh_state = None _instance = loading._instance_processor( self, self.mapper, context, result, self.path, adapter, only_load_props=only_load_props, refresh_state=refresh_state, polymorphic_discriminator=self._polymorphic_discriminator, ) return _instance, self._label_name, self._extra_entities def setup_dml_returning_compile_state( self, compile_state: ORMCompileState, adapter: Optional[_DMLReturningColFilter], ) -> None: loading._setup_entity_query( compile_state, self.mapper, self, self.path, adapter, compile_state.primary_columns, with_polymorphic=self._with_polymorphic_mappers, only_load_props=compile_state.compile_options._only_load_props, polymorphic_discriminator=self._polymorphic_discriminator, ) def setup_compile_state(self, compile_state): adapter = self._get_entity_clauses(compile_state) single_table_crit = self.mapper._single_table_criterion if ( single_table_crit is not None or ("additional_entity_criteria", self.mapper) in compile_state.global_attributes ): ext_info = self.entity_zero compile_state.extra_criteria_entities[ext_info] = ( ext_info, ext_info._adapter if ext_info.is_aliased_class else None, ) loading._setup_entity_query( compile_state, self.mapper, self, self.path, adapter, compile_state.primary_columns, with_polymorphic=self._with_polymorphic_mappers, only_load_props=compile_state.compile_options._only_load_props, polymorphic_discriminator=self._polymorphic_discriminator, ) compile_state._fallback_from_clauses.append(self.selectable) class _BundleEntity(_QueryEntity): _extra_entities = () __slots__ = ( "bundle", "expr", "type", "_label_name", "_entities", "supports_single_entity", ) _entities: List[_QueryEntity] bundle: Bundle type: Type[Any] _label_name: str supports_single_entity: bool expr: Bundle def __init__( self, compile_state, expr, entities_collection, is_current_entities, setup_entities=True, parent_bundle=None, ): compile_state._has_orm_entities = True expr = expr._annotations["bundle"] if parent_bundle: parent_bundle._entities.append(self) else: entities_collection.append(self) if isinstance( expr, (attributes.QueryableAttribute, interfaces.PropComparator) ): bundle = expr.__clause_element__() else: bundle = expr self.bundle = self.expr = bundle self.type = type(bundle) self._label_name = bundle.name self._entities = [] if setup_entities: for expr in bundle.exprs: if "bundle" in expr._annotations: _BundleEntity( compile_state, expr, entities_collection, is_current_entities, parent_bundle=self, ) elif isinstance(expr, Bundle): _BundleEntity( compile_state, expr, entities_collection, is_current_entities, parent_bundle=self, ) else: _ORMColumnEntity._for_columns( compile_state, [expr], entities_collection, None, is_current_entities, parent_bundle=self, ) self.supports_single_entity = self.bundle.single_entity @property def mapper(self): ezero = self.entity_zero if ezero is not None: return ezero.mapper else: return None @property def entity_zero(self): for ent in self._entities: ezero = ent.entity_zero if ezero is not None: return ezero else: return None def corresponds_to(self, entity): # TODO: we might be able to implement this but for now # we are working around it return False @property def entity_zero_or_selectable(self): for ent in self._entities: ezero = ent.entity_zero_or_selectable if ezero is not None: return ezero else: return None def setup_compile_state(self, compile_state): for ent in self._entities: ent.setup_compile_state(compile_state) def setup_dml_returning_compile_state( self, compile_state: ORMCompileState, adapter: Optional[_DMLReturningColFilter], ) -> None: return self.setup_compile_state(compile_state) def row_processor(self, context, result): procs, labels, extra = zip( *[ent.row_processor(context, result) for ent in self._entities] ) proc = self.bundle.create_row_processor(context.query, procs, labels) return proc, self._label_name, self._extra_entities class _ColumnEntity(_QueryEntity): __slots__ = ( "_fetch_column", "_row_processor", "raw_column_index", "translate_raw_column", ) @classmethod def _for_columns( cls, compile_state, columns, entities_collection, raw_column_index, is_current_entities, parent_bundle=None, ): for column in columns: annotations = column._annotations if "parententity" in annotations: _entity = annotations["parententity"] else: _entity = sql_util.extract_first_column_annotation( column, "parententity" ) if _entity: if "identity_token" in column._annotations: _IdentityTokenEntity( compile_state, column, entities_collection, _entity, raw_column_index, is_current_entities, parent_bundle=parent_bundle, ) else: _ORMColumnEntity( compile_state, column, entities_collection, _entity, raw_column_index, is_current_entities, parent_bundle=parent_bundle, ) else: _RawColumnEntity( compile_state, column, entities_collection, raw_column_index, is_current_entities, parent_bundle=parent_bundle, ) @property def type(self): return self.column.type @property def _non_hashable_value(self): return not self.column.type.hashable @property def _null_column_type(self): return self.column.type._isnull def row_processor(self, context, result): compile_state = context.compile_state # the resulting callable is entirely cacheable so just return # it if we already made one if self._row_processor is not None: getter, label_name, extra_entities = self._row_processor if self.translate_raw_column: extra_entities += ( context.query._raw_columns[self.raw_column_index], ) return getter, label_name, extra_entities # retrieve the column that would have been set up in # setup_compile_state, to avoid doing redundant work if self._fetch_column is not None: column = self._fetch_column else: # fetch_column will be None when we are doing a from_statement # and setup_compile_state may not have been called. column = self.column # previously, the RawColumnEntity didn't look for from_obj_alias # however I can't think of a case where we would be here and # we'd want to ignore it if this is the from_statement use case. # it's not really a use case to have raw columns + from_statement if compile_state._from_obj_alias: column = compile_state._from_obj_alias.columns[column] if column._annotations: # annotated columns perform more slowly in compiler and # result due to the __eq__() method, so use deannotated column = column._deannotate() if compile_state.compound_eager_adapter: column = compile_state.compound_eager_adapter.columns[column] getter = result._getter(column) ret = getter, self._label_name, self._extra_entities self._row_processor = ret if self.translate_raw_column: extra_entities = self._extra_entities + ( context.query._raw_columns[self.raw_column_index], ) return getter, self._label_name, extra_entities else: return ret class _RawColumnEntity(_ColumnEntity): entity_zero = None mapper = None supports_single_entity = False __slots__ = ( "expr", "column", "_label_name", "entity_zero_or_selectable", "_extra_entities", ) def __init__( self, compile_state, column, entities_collection, raw_column_index, is_current_entities, parent_bundle=None, ): self.expr = column self.raw_column_index = raw_column_index self.translate_raw_column = raw_column_index is not None if column._is_star: compile_state.compile_options += {"_is_star": True} if not is_current_entities or column._is_text_clause: self._label_name = None else: if parent_bundle: self._label_name = column._proxy_key else: self._label_name = compile_state._label_convention(column) if parent_bundle: parent_bundle._entities.append(self) else: entities_collection.append(self) self.column = column self.entity_zero_or_selectable = ( self.column._from_objects[0] if self.column._from_objects else None ) self._extra_entities = (self.expr, self.column) self._fetch_column = self._row_processor = None def corresponds_to(self, entity): return False def setup_dml_returning_compile_state( self, compile_state: ORMCompileState, adapter: Optional[_DMLReturningColFilter], ) -> None: return self.setup_compile_state(compile_state) def setup_compile_state(self, compile_state): current_adapter = compile_state._get_current_adapter() if current_adapter: column = current_adapter(self.column, False) if column is None: return else: column = self.column if column._annotations: # annotated columns perform more slowly in compiler and # result due to the __eq__() method, so use deannotated column = column._deannotate() compile_state.dedupe_columns.add(column) compile_state.primary_columns.append(column) self._fetch_column = column class _ORMColumnEntity(_ColumnEntity): """Column/expression based entity.""" supports_single_entity = False __slots__ = ( "expr", "mapper", "column", "_label_name", "entity_zero_or_selectable", "entity_zero", "_extra_entities", ) def __init__( self, compile_state, column, entities_collection, parententity, raw_column_index, is_current_entities, parent_bundle=None, ): annotations = column._annotations _entity = parententity # an AliasedClass won't have proxy_key in the annotations for # a column if it was acquired using the class' adapter directly, # such as using AliasedInsp._adapt_element(). this occurs # within internal loaders. orm_key = annotations.get("proxy_key", None) proxy_owner = annotations.get("proxy_owner", _entity) if orm_key: self.expr = getattr(proxy_owner.entity, orm_key) self.translate_raw_column = False else: # if orm_key is not present, that means this is an ad-hoc # SQL ColumnElement, like a CASE() or other expression. # include this column position from the invoked statement # in the ORM-level ResultSetMetaData on each execute, so that # it can be targeted by identity after caching self.expr = column self.translate_raw_column = raw_column_index is not None self.raw_column_index = raw_column_index if is_current_entities: if parent_bundle: self._label_name = orm_key if orm_key else column._proxy_key else: self._label_name = compile_state._label_convention( column, col_name=orm_key ) else: self._label_name = None _entity._post_inspect self.entity_zero = self.entity_zero_or_selectable = ezero = _entity self.mapper = mapper = _entity.mapper if parent_bundle: parent_bundle._entities.append(self) else: entities_collection.append(self) compile_state._has_orm_entities = True self.column = column self._fetch_column = self._row_processor = None self._extra_entities = (self.expr, self.column) if mapper._should_select_with_poly_adapter: compile_state._create_with_polymorphic_adapter( ezero, ezero.selectable ) def corresponds_to(self, entity): if _is_aliased_class(entity): # TODO: polymorphic subclasses ? return entity is self.entity_zero else: return not _is_aliased_class( self.entity_zero ) and entity.common_parent(self.entity_zero) def setup_dml_returning_compile_state( self, compile_state: ORMCompileState, adapter: Optional[_DMLReturningColFilter], ) -> None: self._fetch_column = column = self.column if adapter: column = adapter(column, False) if column is not None: compile_state.dedupe_columns.add(column) compile_state.primary_columns.append(column) def setup_compile_state(self, compile_state): current_adapter = compile_state._get_current_adapter() if current_adapter: column = current_adapter(self.column, False) if column is None: assert compile_state.is_dml_returning self._fetch_column = self.column return else: column = self.column ezero = self.entity_zero single_table_crit = self.mapper._single_table_criterion if ( single_table_crit is not None or ("additional_entity_criteria", self.mapper) in compile_state.global_attributes ): compile_state.extra_criteria_entities[ezero] = ( ezero, ezero._adapter if ezero.is_aliased_class else None, ) if column._annotations and not column._expression_label: # annotated columns perform more slowly in compiler and # result due to the __eq__() method, so use deannotated column = column._deannotate() # use entity_zero as the from if we have it. this is necessary # for polymorphic scenarios where our FROM is based on ORM entity, # not the FROM of the column. but also, don't use it if our column # doesn't actually have any FROMs that line up, such as when its # a scalar subquery. if set(self.column._from_objects).intersection( ezero.selectable._from_objects ): compile_state._fallback_from_clauses.append(ezero.selectable) compile_state.dedupe_columns.add(column) compile_state.primary_columns.append(column) self._fetch_column = column class _IdentityTokenEntity(_ORMColumnEntity): translate_raw_column = False def setup_compile_state(self, compile_state): pass def row_processor(self, context, result): def getter(row): return context.load_options._identity_token return getter, self._label_name, self._extra_entities sqlalchemy/orm/attributes.py 0000755 00000264566 15125143220 0012264 0 ustar 00 # orm/attributes.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: allow-untyped-defs, allow-untyped-calls """Defines instrumentation for class attributes and their interaction with instances. This module is usually not directly visible to user applications, but defines a large part of the ORM's interactivity. """ from __future__ import annotations import dataclasses import operator from typing import Any from typing import Callable from typing import cast from typing import ClassVar from typing import Dict from typing import Iterable from typing import List from typing import NamedTuple from typing import Optional from typing import overload from typing import Sequence from typing import Tuple from typing import Type from typing import TYPE_CHECKING from typing import TypeVar from typing import Union from . import collections from . import exc as orm_exc from . import interfaces from ._typing import insp_is_aliased_class from .base import _DeclarativeMapped from .base import ATTR_EMPTY from .base import ATTR_WAS_SET from .base import CALLABLES_OK from .base import DEFERRED_HISTORY_LOAD from .base import INCLUDE_PENDING_MUTATIONS # noqa from .base import INIT_OK from .base import instance_dict as instance_dict from .base import instance_state as instance_state from .base import instance_str from .base import LOAD_AGAINST_COMMITTED from .base import LoaderCallableStatus from .base import manager_of_class as manager_of_class from .base import Mapped as Mapped # noqa from .base import NEVER_SET # noqa from .base import NO_AUTOFLUSH from .base import NO_CHANGE # noqa from .base import NO_KEY from .base import NO_RAISE from .base import NO_VALUE from .base import NON_PERSISTENT_OK # noqa from .base import opt_manager_of_class as opt_manager_of_class from .base import PASSIVE_CLASS_MISMATCH # noqa from .base import PASSIVE_NO_FETCH from .base import PASSIVE_NO_FETCH_RELATED # noqa from .base import PASSIVE_NO_INITIALIZE from .base import PASSIVE_NO_RESULT from .base import PASSIVE_OFF from .base import PASSIVE_ONLY_PERSISTENT from .base import PASSIVE_RETURN_NO_VALUE from .base import PassiveFlag from .base import RELATED_OBJECT_OK # noqa from .base import SQL_OK # noqa from .base import SQLORMExpression from .base import state_str from .. import event from .. import exc from .. import inspection from .. import util from ..event import dispatcher from ..event import EventTarget from ..sql import base as sql_base from ..sql import cache_key from ..sql import coercions from ..sql import roles from ..sql import visitors from ..sql.cache_key import HasCacheKey from ..sql.visitors import _TraverseInternalsType from ..sql.visitors import InternalTraversal from ..util.typing import Literal from ..util.typing import Self from ..util.typing import TypeGuard if TYPE_CHECKING: from ._typing import _EntityType from ._typing import _ExternalEntityType from ._typing import _InstanceDict from ._typing import _InternalEntityType from ._typing import _LoaderCallable from ._typing import _O from .collections import _AdaptedCollectionProtocol from .collections import CollectionAdapter from .interfaces import MapperProperty from .relationships import RelationshipProperty from .state import InstanceState from .util import AliasedInsp from .writeonly import WriteOnlyAttributeImpl from ..event.base import _Dispatch from ..sql._typing import _ColumnExpressionArgument from ..sql._typing import _DMLColumnArgument from ..sql._typing import _InfoType from ..sql._typing import _PropagateAttrsType from ..sql.annotation import _AnnotationDict from ..sql.elements import ColumnElement from ..sql.elements import Label from ..sql.operators import OperatorType from ..sql.selectable import FromClause _T = TypeVar("_T") _T_co = TypeVar("_T_co", bound=Any, covariant=True) _AllPendingType = Sequence[ Tuple[Optional["InstanceState[Any]"], Optional[object]] ] _UNKNOWN_ATTR_KEY = object() @inspection._self_inspects class QueryableAttribute( _DeclarativeMapped[_T_co], SQLORMExpression[_T_co], interfaces.InspectionAttr, interfaces.PropComparator[_T_co], roles.JoinTargetRole, roles.OnClauseRole, sql_base.Immutable, cache_key.SlotsMemoizedHasCacheKey, util.MemoizedSlots, EventTarget, ): """Base class for :term:`descriptor` objects that intercept attribute events on behalf of a :class:`.MapperProperty` object. The actual :class:`.MapperProperty` is accessible via the :attr:`.QueryableAttribute.property` attribute. .. seealso:: :class:`.InstrumentedAttribute` :class:`.MapperProperty` :attr:`_orm.Mapper.all_orm_descriptors` :attr:`_orm.Mapper.attrs` """ __slots__ = ( "class_", "key", "impl", "comparator", "property", "parent", "expression", "_of_type", "_extra_criteria", "_slots_dispatch", "_propagate_attrs", "_doc", ) is_attribute = True dispatch: dispatcher[QueryableAttribute[_T_co]] class_: _ExternalEntityType[Any] key: str parententity: _InternalEntityType[Any] impl: AttributeImpl comparator: interfaces.PropComparator[_T_co] _of_type: Optional[_InternalEntityType[Any]] _extra_criteria: Tuple[ColumnElement[bool], ...] _doc: Optional[str] # PropComparator has a __visit_name__ to participate within # traversals. Disambiguate the attribute vs. a comparator. __visit_name__ = "orm_instrumented_attribute" def __init__( self, class_: _ExternalEntityType[_O], key: str, parententity: _InternalEntityType[_O], comparator: interfaces.PropComparator[_T_co], impl: Optional[AttributeImpl] = None, of_type: Optional[_InternalEntityType[Any]] = None, extra_criteria: Tuple[ColumnElement[bool], ...] = (), ): self.class_ = class_ self.key = key self._parententity = self.parent = parententity # this attribute is non-None after mappers are set up, however in the # interim class manager setup, there's a check for None to see if it # needs to be populated, so we assign None here leaving the attribute # in a temporarily not-type-correct state self.impl = impl # type: ignore assert comparator is not None self.comparator = comparator self._of_type = of_type self._extra_criteria = extra_criteria self._doc = None manager = opt_manager_of_class(class_) # manager is None in the case of AliasedClass if manager: # propagate existing event listeners from # immediate superclass for base in manager._bases: if key in base: self.dispatch._update(base[key].dispatch) if base[key].dispatch._active_history: self.dispatch._active_history = True # type: ignore _cache_key_traversal = [ ("key", visitors.ExtendedInternalTraversal.dp_string), ("_parententity", visitors.ExtendedInternalTraversal.dp_multi), ("_of_type", visitors.ExtendedInternalTraversal.dp_multi), ("_extra_criteria", visitors.InternalTraversal.dp_clauseelement_list), ] def __reduce__(self) -> Any: # this method is only used in terms of the # sqlalchemy.ext.serializer extension return ( _queryable_attribute_unreduce, ( self.key, self._parententity.mapper.class_, self._parententity, self._parententity.entity, ), ) @property def _impl_uses_objects(self) -> bool: return self.impl.uses_objects def get_history( self, instance: Any, passive: PassiveFlag = PASSIVE_OFF ) -> History: return self.impl.get_history( instance_state(instance), instance_dict(instance), passive ) @property def info(self) -> _InfoType: """Return the 'info' dictionary for the underlying SQL element. The behavior here is as follows: * If the attribute is a column-mapped property, i.e. :class:`.ColumnProperty`, which is mapped directly to a schema-level :class:`_schema.Column` object, this attribute will return the :attr:`.SchemaItem.info` dictionary associated with the core-level :class:`_schema.Column` object. * If the attribute is a :class:`.ColumnProperty` but is mapped to any other kind of SQL expression other than a :class:`_schema.Column`, the attribute will refer to the :attr:`.MapperProperty.info` dictionary associated directly with the :class:`.ColumnProperty`, assuming the SQL expression itself does not have its own ``.info`` attribute (which should be the case, unless a user-defined SQL construct has defined one). * If the attribute refers to any other kind of :class:`.MapperProperty`, including :class:`.Relationship`, the attribute will refer to the :attr:`.MapperProperty.info` dictionary associated with that :class:`.MapperProperty`. * To access the :attr:`.MapperProperty.info` dictionary of the :class:`.MapperProperty` unconditionally, including for a :class:`.ColumnProperty` that's associated directly with a :class:`_schema.Column`, the attribute can be referred to using :attr:`.QueryableAttribute.property` attribute, as ``MyClass.someattribute.property.info``. .. seealso:: :attr:`.SchemaItem.info` :attr:`.MapperProperty.info` """ return self.comparator.info parent: _InternalEntityType[Any] """Return an inspection instance representing the parent. This will be either an instance of :class:`_orm.Mapper` or :class:`.AliasedInsp`, depending upon the nature of the parent entity which this attribute is associated with. """ expression: ColumnElement[_T_co] """The SQL expression object represented by this :class:`.QueryableAttribute`. This will typically be an instance of a :class:`_sql.ColumnElement` subclass representing a column expression. """ def _memoized_attr_expression(self) -> ColumnElement[_T]: annotations: _AnnotationDict # applies only to Proxy() as used by hybrid. # currently is an exception to typing rather than feeding through # non-string keys. # ideally Proxy() would have a separate set of methods to deal # with this case. entity_namespace = self._entity_namespace assert isinstance(entity_namespace, HasCacheKey) if self.key is _UNKNOWN_ATTR_KEY: annotations = {"entity_namespace": entity_namespace} else: annotations = { "proxy_key": self.key, "proxy_owner": self._parententity, "entity_namespace": entity_namespace, } ce = self.comparator.__clause_element__() try: if TYPE_CHECKING: assert isinstance(ce, ColumnElement) anno = ce._annotate except AttributeError as ae: raise exc.InvalidRequestError( 'When interpreting attribute "%s" as a SQL expression, ' "expected __clause_element__() to return " "a ClauseElement object, got: %r" % (self, ce) ) from ae else: return anno(annotations) def _memoized_attr__propagate_attrs(self) -> _PropagateAttrsType: # this suits the case in coercions where we don't actually # call ``__clause_element__()`` but still need to get # resolved._propagate_attrs. See #6558. return util.immutabledict( { "compile_state_plugin": "orm", "plugin_subject": self._parentmapper, } ) @property def _entity_namespace(self) -> _InternalEntityType[Any]: return self._parententity @property def _annotations(self) -> _AnnotationDict: return self.__clause_element__()._annotations def __clause_element__(self) -> ColumnElement[_T_co]: return self.expression @property def _from_objects(self) -> List[FromClause]: return self.expression._from_objects def _bulk_update_tuples( self, value: Any ) -> Sequence[Tuple[_DMLColumnArgument, Any]]: """Return setter tuples for a bulk UPDATE.""" return self.comparator._bulk_update_tuples(value) def adapt_to_entity(self, adapt_to_entity: AliasedInsp[Any]) -> Self: assert not self._of_type return self.__class__( adapt_to_entity.entity, self.key, impl=self.impl, comparator=self.comparator.adapt_to_entity(adapt_to_entity), parententity=adapt_to_entity, ) def of_type(self, entity: _EntityType[_T]) -> QueryableAttribute[_T]: return QueryableAttribute( self.class_, self.key, self._parententity, impl=self.impl, comparator=self.comparator.of_type(entity), of_type=inspection.inspect(entity), extra_criteria=self._extra_criteria, ) def and_( self, *clauses: _ColumnExpressionArgument[bool] ) -> QueryableAttribute[bool]: if TYPE_CHECKING: assert isinstance(self.comparator, RelationshipProperty.Comparator) exprs = tuple( coercions.expect(roles.WhereHavingRole, clause) for clause in util.coerce_generator_arg(clauses) ) return QueryableAttribute( self.class_, self.key, self._parententity, impl=self.impl, comparator=self.comparator.and_(*exprs), of_type=self._of_type, extra_criteria=self._extra_criteria + exprs, ) def _clone(self, **kw: Any) -> QueryableAttribute[_T]: return QueryableAttribute( self.class_, self.key, self._parententity, impl=self.impl, comparator=self.comparator, of_type=self._of_type, extra_criteria=self._extra_criteria, ) def label(self, name: Optional[str]) -> Label[_T_co]: return self.__clause_element__().label(name) def operate( self, op: OperatorType, *other: Any, **kwargs: Any ) -> ColumnElement[Any]: return op(self.comparator, *other, **kwargs) # type: ignore[no-any-return] # noqa: E501 def reverse_operate( self, op: OperatorType, other: Any, **kwargs: Any ) -> ColumnElement[Any]: return op(other, self.comparator, **kwargs) # type: ignore[no-any-return] # noqa: E501 def hasparent( self, state: InstanceState[Any], optimistic: bool = False ) -> bool: return self.impl.hasparent(state, optimistic=optimistic) is not False def __getattr__(self, key: str) -> Any: try: return util.MemoizedSlots.__getattr__(self, key) except AttributeError: pass try: return getattr(self.comparator, key) except AttributeError as err: raise AttributeError( "Neither %r object nor %r object associated with %s " "has an attribute %r" % ( type(self).__name__, type(self.comparator).__name__, self, key, ) ) from err def __str__(self) -> str: return f"{self.class_.__name__}.{self.key}" def _memoized_attr_property(self) -> Optional[MapperProperty[Any]]: return self.comparator.property def _queryable_attribute_unreduce( key: str, mapped_class: Type[_O], parententity: _InternalEntityType[_O], entity: _ExternalEntityType[Any], ) -> Any: # this method is only used in terms of the # sqlalchemy.ext.serializer extension if insp_is_aliased_class(parententity): return entity._get_from_serialized(key, mapped_class, parententity) else: return getattr(entity, key) class InstrumentedAttribute(QueryableAttribute[_T_co]): """Class bound instrumented attribute which adds basic :term:`descriptor` methods. See :class:`.QueryableAttribute` for a description of most features. """ __slots__ = () inherit_cache = True """:meta private:""" # hack to make __doc__ writeable on instances of # InstrumentedAttribute, while still keeping classlevel # __doc__ correct @util.rw_hybridproperty def __doc__(self) -> Optional[str]: return self._doc @__doc__.setter # type: ignore def __doc__(self, value: Optional[str]) -> None: self._doc = value @__doc__.classlevel # type: ignore def __doc__(cls) -> Optional[str]: return super().__doc__ def __set__(self, instance: object, value: Any) -> None: self.impl.set( instance_state(instance), instance_dict(instance), value, None ) def __delete__(self, instance: object) -> None: self.impl.delete(instance_state(instance), instance_dict(instance)) @overload def __get__( self, instance: None, owner: Any ) -> InstrumentedAttribute[_T_co]: ... @overload def __get__(self, instance: object, owner: Any) -> _T_co: ... def __get__( self, instance: Optional[object], owner: Any ) -> Union[InstrumentedAttribute[_T_co], _T_co]: if instance is None: return self dict_ = instance_dict(instance) if self.impl.supports_population and self.key in dict_: return dict_[self.key] # type: ignore[no-any-return] else: try: state = instance_state(instance) except AttributeError as err: raise orm_exc.UnmappedInstanceError(instance) from err return self.impl.get(state, dict_) # type: ignore[no-any-return] @dataclasses.dataclass(frozen=True) class AdHocHasEntityNamespace(HasCacheKey): _traverse_internals: ClassVar[_TraverseInternalsType] = [ ("_entity_namespace", InternalTraversal.dp_has_cache_key), ] # py37 compat, no slots=True on dataclass __slots__ = ("_entity_namespace",) _entity_namespace: _InternalEntityType[Any] is_mapper: ClassVar[bool] = False is_aliased_class: ClassVar[bool] = False @property def entity_namespace(self): return self._entity_namespace.entity_namespace def create_proxied_attribute( descriptor: Any, ) -> Callable[..., QueryableAttribute[Any]]: """Create an QueryableAttribute / user descriptor hybrid. Returns a new QueryableAttribute type that delegates descriptor behavior and getattr() to the given descriptor. """ # TODO: can move this to descriptor_props if the need for this # function is removed from ext/hybrid.py class Proxy(QueryableAttribute[Any]): """Presents the :class:`.QueryableAttribute` interface as a proxy on top of a Python descriptor / :class:`.PropComparator` combination. """ _extra_criteria = () # the attribute error catches inside of __getattr__ basically create a # singularity if you try putting slots on this too # __slots__ = ("descriptor", "original_property", "_comparator") def __init__( self, class_, key, descriptor, comparator, adapt_to_entity=None, doc=None, original_property=None, ): self.class_ = class_ self.key = key self.descriptor = descriptor self.original_property = original_property self._comparator = comparator self._adapt_to_entity = adapt_to_entity self._doc = self.__doc__ = doc @property def _parententity(self): return inspection.inspect(self.class_, raiseerr=False) @property def parent(self): return inspection.inspect(self.class_, raiseerr=False) _is_internal_proxy = True _cache_key_traversal = [ ("key", visitors.ExtendedInternalTraversal.dp_string), ("_parententity", visitors.ExtendedInternalTraversal.dp_multi), ] @property def _impl_uses_objects(self): return ( self.original_property is not None and getattr(self.class_, self.key).impl.uses_objects ) @property def _entity_namespace(self): if hasattr(self._comparator, "_parententity"): return self._comparator._parententity else: # used by hybrid attributes which try to remain # agnostic of any ORM concepts like mappers return AdHocHasEntityNamespace(self._parententity) @property def property(self): return self.comparator.property @util.memoized_property def comparator(self): if callable(self._comparator): self._comparator = self._comparator() if self._adapt_to_entity: self._comparator = self._comparator.adapt_to_entity( self._adapt_to_entity ) return self._comparator def adapt_to_entity(self, adapt_to_entity): return self.__class__( adapt_to_entity.entity, self.key, self.descriptor, self._comparator, adapt_to_entity, ) def _clone(self, **kw): return self.__class__( self.class_, self.key, self.descriptor, self._comparator, adapt_to_entity=self._adapt_to_entity, original_property=self.original_property, ) def __get__(self, instance, owner): retval = self.descriptor.__get__(instance, owner) # detect if this is a plain Python @property, which just returns # itself for class level access. If so, then return us. # Otherwise, return the object returned by the descriptor. if retval is self.descriptor and instance is None: return self else: return retval def __str__(self) -> str: return f"{self.class_.__name__}.{self.key}" def __getattr__(self, attribute): """Delegate __getattr__ to the original descriptor and/or comparator.""" # this is unfortunately very complicated, and is easily prone # to recursion overflows when implementations of related # __getattr__ schemes are changed try: return util.MemoizedSlots.__getattr__(self, attribute) except AttributeError: pass try: return getattr(descriptor, attribute) except AttributeError as err: if attribute == "comparator": raise AttributeError("comparator") from err try: # comparator itself might be unreachable comparator = self.comparator except AttributeError as err2: raise AttributeError( "Neither %r object nor unconfigured comparator " "object associated with %s has an attribute %r" % (type(descriptor).__name__, self, attribute) ) from err2 else: try: return getattr(comparator, attribute) except AttributeError as err3: raise AttributeError( "Neither %r object nor %r object " "associated with %s has an attribute %r" % ( type(descriptor).__name__, type(comparator).__name__, self, attribute, ) ) from err3 Proxy.__name__ = type(descriptor).__name__ + "Proxy" util.monkeypatch_proxied_specials( Proxy, type(descriptor), name="descriptor", from_instance=descriptor ) return Proxy OP_REMOVE = util.symbol("REMOVE") OP_APPEND = util.symbol("APPEND") OP_REPLACE = util.symbol("REPLACE") OP_BULK_REPLACE = util.symbol("BULK_REPLACE") OP_MODIFIED = util.symbol("MODIFIED") class AttributeEventToken: """A token propagated throughout the course of a chain of attribute events. Serves as an indicator of the source of the event and also provides a means of controlling propagation across a chain of attribute operations. The :class:`.Event` object is sent as the ``initiator`` argument when dealing with events such as :meth:`.AttributeEvents.append`, :meth:`.AttributeEvents.set`, and :meth:`.AttributeEvents.remove`. The :class:`.Event` object is currently interpreted by the backref event handlers, and is used to control the propagation of operations across two mutually-dependent attributes. .. versionchanged:: 2.0 Changed the name from ``AttributeEvent`` to ``AttributeEventToken``. :attribute impl: The :class:`.AttributeImpl` which is the current event initiator. :attribute op: The symbol :attr:`.OP_APPEND`, :attr:`.OP_REMOVE`, :attr:`.OP_REPLACE`, or :attr:`.OP_BULK_REPLACE`, indicating the source operation. """ __slots__ = "impl", "op", "parent_token" def __init__(self, attribute_impl: AttributeImpl, op: util.symbol): self.impl = attribute_impl self.op = op self.parent_token = self.impl.parent_token def __eq__(self, other): return ( isinstance(other, AttributeEventToken) and other.impl is self.impl and other.op == self.op ) @property def key(self): return self.impl.key def hasparent(self, state): return self.impl.hasparent(state) AttributeEvent = AttributeEventToken # legacy Event = AttributeEventToken # legacy class AttributeImpl: """internal implementation for instrumented attributes.""" collection: bool default_accepts_scalar_loader: bool uses_objects: bool supports_population: bool dynamic: bool _is_has_collection_adapter = False _replace_token: AttributeEventToken _remove_token: AttributeEventToken _append_token: AttributeEventToken def __init__( self, class_: _ExternalEntityType[_O], key: str, callable_: Optional[_LoaderCallable], dispatch: _Dispatch[QueryableAttribute[Any]], trackparent: bool = False, compare_function: Optional[Callable[..., bool]] = None, active_history: bool = False, parent_token: Optional[AttributeEventToken] = None, load_on_unexpire: bool = True, send_modified_events: bool = True, accepts_scalar_loader: Optional[bool] = None, **kwargs: Any, ): r"""Construct an AttributeImpl. :param \class_: associated class :param key: string name of the attribute :param \callable_: optional function which generates a callable based on a parent instance, which produces the "default" values for a scalar or collection attribute when it's first accessed, if not present already. :param trackparent: if True, attempt to track if an instance has a parent attached to it via this attribute. :param compare_function: a function that compares two values which are normally assignable to this attribute. :param active_history: indicates that get_history() should always return the "old" value, even if it means executing a lazy callable upon attribute change. :param parent_token: Usually references the MapperProperty, used as a key for the hasparent() function to identify an "owning" attribute. Allows multiple AttributeImpls to all match a single owner attribute. :param load_on_unexpire: if False, don't include this attribute in a load-on-expired operation, i.e. the "expired_attribute_loader" process. The attribute can still be in the "expired" list and be considered to be "expired". Previously, this flag was called "expire_missing" and is only used by a deferred column attribute. :param send_modified_events: if False, the InstanceState._modified_event method will have no effect; this means the attribute will never show up as changed in a history entry. """ self.class_ = class_ self.key = key self.callable_ = callable_ self.dispatch = dispatch self.trackparent = trackparent self.parent_token = parent_token or self self.send_modified_events = send_modified_events if compare_function is None: self.is_equal = operator.eq else: self.is_equal = compare_function if accepts_scalar_loader is not None: self.accepts_scalar_loader = accepts_scalar_loader else: self.accepts_scalar_loader = self.default_accepts_scalar_loader _deferred_history = kwargs.pop("_deferred_history", False) self._deferred_history = _deferred_history if active_history: self.dispatch._active_history = True self.load_on_unexpire = load_on_unexpire self._modified_token = AttributeEventToken(self, OP_MODIFIED) __slots__ = ( "class_", "key", "callable_", "dispatch", "trackparent", "parent_token", "send_modified_events", "is_equal", "load_on_unexpire", "_modified_token", "accepts_scalar_loader", "_deferred_history", ) def __str__(self) -> str: return f"{self.class_.__name__}.{self.key}" def _get_active_history(self): """Backwards compat for impl.active_history""" return self.dispatch._active_history def _set_active_history(self, value): self.dispatch._active_history = value active_history = property(_get_active_history, _set_active_history) def hasparent( self, state: InstanceState[Any], optimistic: bool = False ) -> bool: """Return the boolean value of a `hasparent` flag attached to the given state. The `optimistic` flag determines what the default return value should be if no `hasparent` flag can be located. As this function is used to determine if an instance is an *orphan*, instances that were loaded from storage should be assumed to not be orphans, until a True/False value for this flag is set. An instance attribute that is loaded by a callable function will also not have a `hasparent` flag. """ msg = "This AttributeImpl is not configured to track parents." assert self.trackparent, msg return ( state.parents.get(id(self.parent_token), optimistic) is not False ) def sethasparent( self, state: InstanceState[Any], parent_state: InstanceState[Any], value: bool, ) -> None: """Set a boolean flag on the given item corresponding to whether or not it is attached to a parent object via the attribute represented by this ``InstrumentedAttribute``. """ msg = "This AttributeImpl is not configured to track parents." assert self.trackparent, msg id_ = id(self.parent_token) if value: state.parents[id_] = parent_state else: if id_ in state.parents: last_parent = state.parents[id_] if ( last_parent is not False and last_parent.key != parent_state.key ): if last_parent.obj() is None: raise orm_exc.StaleDataError( "Removing state %s from parent " "state %s along attribute '%s', " "but the parent record " "has gone stale, can't be sure this " "is the most recent parent." % ( state_str(state), state_str(parent_state), self.key, ) ) return state.parents[id_] = False def get_history( self, state: InstanceState[Any], dict_: _InstanceDict, passive: PassiveFlag = PASSIVE_OFF, ) -> History: raise NotImplementedError() def get_all_pending( self, state: InstanceState[Any], dict_: _InstanceDict, passive: PassiveFlag = PASSIVE_NO_INITIALIZE, ) -> _AllPendingType: """Return a list of tuples of (state, obj) for all objects in this attribute's current state + history. Only applies to object-based attributes. This is an inlining of existing functionality which roughly corresponds to: get_state_history( state, key, passive=PASSIVE_NO_INITIALIZE).sum() """ raise NotImplementedError() def _default_value( self, state: InstanceState[Any], dict_: _InstanceDict ) -> Any: """Produce an empty value for an uninitialized scalar attribute.""" assert self.key not in dict_, ( "_default_value should only be invoked for an " "uninitialized or expired attribute" ) value = None for fn in self.dispatch.init_scalar: ret = fn(state, value, dict_) if ret is not ATTR_EMPTY: value = ret return value def get( self, state: InstanceState[Any], dict_: _InstanceDict, passive: PassiveFlag = PASSIVE_OFF, ) -> Any: """Retrieve a value from the given object. If a callable is assembled on this object's attribute, and passive is False, the callable will be executed and the resulting value will be set as the new value for this attribute. """ if self.key in dict_: return dict_[self.key] else: # if history present, don't load key = self.key if ( key not in state.committed_state or state.committed_state[key] is NO_VALUE ): if not passive & CALLABLES_OK: return PASSIVE_NO_RESULT value = self._fire_loader_callables(state, key, passive) if value is PASSIVE_NO_RESULT or value is NO_VALUE: return value elif value is ATTR_WAS_SET: try: return dict_[key] except KeyError as err: # TODO: no test coverage here. raise KeyError( "Deferred loader for attribute " "%r failed to populate " "correctly" % key ) from err elif value is not ATTR_EMPTY: return self.set_committed_value(state, dict_, value) if not passive & INIT_OK: return NO_VALUE else: return self._default_value(state, dict_) def _fire_loader_callables( self, state: InstanceState[Any], key: str, passive: PassiveFlag ) -> Any: if ( self.accepts_scalar_loader and self.load_on_unexpire and key in state.expired_attributes ): return state._load_expired(state, passive) elif key in state.callables: callable_ = state.callables[key] return callable_(state, passive) elif self.callable_: return self.callable_(state, passive) else: return ATTR_EMPTY def append( self, state: InstanceState[Any], dict_: _InstanceDict, value: Any, initiator: Optional[AttributeEventToken], passive: PassiveFlag = PASSIVE_OFF, ) -> None: self.set(state, dict_, value, initiator, passive=passive) def remove( self, state: InstanceState[Any], dict_: _InstanceDict, value: Any, initiator: Optional[AttributeEventToken], passive: PassiveFlag = PASSIVE_OFF, ) -> None: self.set( state, dict_, None, initiator, passive=passive, check_old=value ) def pop( self, state: InstanceState[Any], dict_: _InstanceDict, value: Any, initiator: Optional[AttributeEventToken], passive: PassiveFlag = PASSIVE_OFF, ) -> None: self.set( state, dict_, None, initiator, passive=passive, check_old=value, pop=True, ) def set( self, state: InstanceState[Any], dict_: _InstanceDict, value: Any, initiator: Optional[AttributeEventToken] = None, passive: PassiveFlag = PASSIVE_OFF, check_old: Any = None, pop: bool = False, ) -> None: raise NotImplementedError() def delete(self, state: InstanceState[Any], dict_: _InstanceDict) -> None: raise NotImplementedError() def get_committed_value( self, state: InstanceState[Any], dict_: _InstanceDict, passive: PassiveFlag = PASSIVE_OFF, ) -> Any: """return the unchanged value of this attribute""" if self.key in state.committed_state: value = state.committed_state[self.key] if value is NO_VALUE: return None else: return value else: return self.get(state, dict_, passive=passive) def set_committed_value(self, state, dict_, value): """set an attribute value on the given instance and 'commit' it.""" dict_[self.key] = value state._commit(dict_, [self.key]) return value class ScalarAttributeImpl(AttributeImpl): """represents a scalar value-holding InstrumentedAttribute.""" default_accepts_scalar_loader = True uses_objects = False supports_population = True collection = False dynamic = False __slots__ = "_replace_token", "_append_token", "_remove_token" def __init__(self, *arg, **kw): super().__init__(*arg, **kw) self._replace_token = self._append_token = AttributeEventToken( self, OP_REPLACE ) self._remove_token = AttributeEventToken(self, OP_REMOVE) def delete(self, state: InstanceState[Any], dict_: _InstanceDict) -> None: if self.dispatch._active_history: old = self.get(state, dict_, PASSIVE_RETURN_NO_VALUE) else: old = dict_.get(self.key, NO_VALUE) if self.dispatch.remove: self.fire_remove_event(state, dict_, old, self._remove_token) state._modified_event(dict_, self, old) existing = dict_.pop(self.key, NO_VALUE) if ( existing is NO_VALUE and old is NO_VALUE and not state.expired and self.key not in state.expired_attributes ): raise AttributeError("%s object does not have a value" % self) def get_history( self, state: InstanceState[Any], dict_: Dict[str, Any], passive: PassiveFlag = PASSIVE_OFF, ) -> History: if self.key in dict_: return History.from_scalar_attribute(self, state, dict_[self.key]) elif self.key in state.committed_state: return History.from_scalar_attribute(self, state, NO_VALUE) else: if passive & INIT_OK: passive ^= INIT_OK current = self.get(state, dict_, passive=passive) if current is PASSIVE_NO_RESULT: return HISTORY_BLANK else: return History.from_scalar_attribute(self, state, current) def set( self, state: InstanceState[Any], dict_: Dict[str, Any], value: Any, initiator: Optional[AttributeEventToken] = None, passive: PassiveFlag = PASSIVE_OFF, check_old: Optional[object] = None, pop: bool = False, ) -> None: if self.dispatch._active_history: old = self.get(state, dict_, PASSIVE_RETURN_NO_VALUE) else: old = dict_.get(self.key, NO_VALUE) if self.dispatch.set: value = self.fire_replace_event( state, dict_, value, old, initiator ) state._modified_event(dict_, self, old) dict_[self.key] = value def fire_replace_event( self, state: InstanceState[Any], dict_: _InstanceDict, value: _T, previous: Any, initiator: Optional[AttributeEventToken], ) -> _T: for fn in self.dispatch.set: value = fn( state, value, previous, initiator or self._replace_token ) return value def fire_remove_event( self, state: InstanceState[Any], dict_: _InstanceDict, value: Any, initiator: Optional[AttributeEventToken], ) -> None: for fn in self.dispatch.remove: fn(state, value, initiator or self._remove_token) class ScalarObjectAttributeImpl(ScalarAttributeImpl): """represents a scalar-holding InstrumentedAttribute, where the target object is also instrumented. Adds events to delete/set operations. """ default_accepts_scalar_loader = False uses_objects = True supports_population = True collection = False __slots__ = () def delete(self, state: InstanceState[Any], dict_: _InstanceDict) -> None: if self.dispatch._active_history: old = self.get( state, dict_, passive=PASSIVE_ONLY_PERSISTENT | NO_AUTOFLUSH | LOAD_AGAINST_COMMITTED, ) else: old = self.get( state, dict_, passive=PASSIVE_NO_FETCH ^ INIT_OK | LOAD_AGAINST_COMMITTED | NO_RAISE, ) self.fire_remove_event(state, dict_, old, self._remove_token) existing = dict_.pop(self.key, NO_VALUE) # if the attribute is expired, we currently have no way to tell # that an object-attribute was expired vs. not loaded. So # for this test, we look to see if the object has a DB identity. if ( existing is NO_VALUE and old is not PASSIVE_NO_RESULT and state.key is None ): raise AttributeError("%s object does not have a value" % self) def get_history( self, state: InstanceState[Any], dict_: _InstanceDict, passive: PassiveFlag = PASSIVE_OFF, ) -> History: if self.key in dict_: current = dict_[self.key] else: if passive & INIT_OK: passive ^= INIT_OK current = self.get(state, dict_, passive=passive) if current is PASSIVE_NO_RESULT: return HISTORY_BLANK if not self._deferred_history: return History.from_object_attribute(self, state, current) else: original = state.committed_state.get(self.key, _NO_HISTORY) if original is PASSIVE_NO_RESULT: loader_passive = passive | ( PASSIVE_ONLY_PERSISTENT | NO_AUTOFLUSH | LOAD_AGAINST_COMMITTED | NO_RAISE | DEFERRED_HISTORY_LOAD ) original = self._fire_loader_callables( state, self.key, loader_passive ) return History.from_object_attribute( self, state, current, original=original ) def get_all_pending( self, state: InstanceState[Any], dict_: _InstanceDict, passive: PassiveFlag = PASSIVE_NO_INITIALIZE, ) -> _AllPendingType: if self.key in dict_: current = dict_[self.key] elif passive & CALLABLES_OK: current = self.get(state, dict_, passive=passive) else: return [] ret: _AllPendingType # can't use __hash__(), can't use __eq__() here if ( current is not None and current is not PASSIVE_NO_RESULT and current is not NO_VALUE ): ret = [(instance_state(current), current)] else: ret = [(None, None)] if self.key in state.committed_state: original = state.committed_state[self.key] if ( original is not None and original is not PASSIVE_NO_RESULT and original is not NO_VALUE and original is not current ): ret.append((instance_state(original), original)) return ret def set( self, state: InstanceState[Any], dict_: _InstanceDict, value: Any, initiator: Optional[AttributeEventToken] = None, passive: PassiveFlag = PASSIVE_OFF, check_old: Any = None, pop: bool = False, ) -> None: """Set a value on the given InstanceState.""" if self.dispatch._active_history: old = self.get( state, dict_, passive=PASSIVE_ONLY_PERSISTENT | NO_AUTOFLUSH | LOAD_AGAINST_COMMITTED, ) else: old = self.get( state, dict_, passive=PASSIVE_NO_FETCH ^ INIT_OK | LOAD_AGAINST_COMMITTED | NO_RAISE, ) if ( check_old is not None and old is not PASSIVE_NO_RESULT and check_old is not old ): if pop: return else: raise ValueError( "Object %s not associated with %s on attribute '%s'" % (instance_str(check_old), state_str(state), self.key) ) value = self.fire_replace_event(state, dict_, value, old, initiator) dict_[self.key] = value def fire_remove_event( self, state: InstanceState[Any], dict_: _InstanceDict, value: Any, initiator: Optional[AttributeEventToken], ) -> None: if self.trackparent and value not in ( None, PASSIVE_NO_RESULT, NO_VALUE, ): self.sethasparent(instance_state(value), state, False) for fn in self.dispatch.remove: fn(state, value, initiator or self._remove_token) state._modified_event(dict_, self, value) def fire_replace_event( self, state: InstanceState[Any], dict_: _InstanceDict, value: _T, previous: Any, initiator: Optional[AttributeEventToken], ) -> _T: if self.trackparent: if previous is not value and previous not in ( None, PASSIVE_NO_RESULT, NO_VALUE, ): self.sethasparent(instance_state(previous), state, False) for fn in self.dispatch.set: value = fn( state, value, previous, initiator or self._replace_token ) state._modified_event(dict_, self, previous) if self.trackparent: if value is not None: self.sethasparent(instance_state(value), state, True) return value class HasCollectionAdapter: __slots__ = () collection: bool _is_has_collection_adapter = True def _dispose_previous_collection( self, state: InstanceState[Any], collection: _AdaptedCollectionProtocol, adapter: CollectionAdapter, fire_event: bool, ) -> None: raise NotImplementedError() @overload def get_collection( self, state: InstanceState[Any], dict_: _InstanceDict, user_data: Literal[None] = ..., passive: Literal[PassiveFlag.PASSIVE_OFF] = ..., ) -> CollectionAdapter: ... @overload def get_collection( self, state: InstanceState[Any], dict_: _InstanceDict, user_data: _AdaptedCollectionProtocol = ..., passive: PassiveFlag = ..., ) -> CollectionAdapter: ... @overload def get_collection( self, state: InstanceState[Any], dict_: _InstanceDict, user_data: Optional[_AdaptedCollectionProtocol] = ..., passive: PassiveFlag = ..., ) -> Union[ Literal[LoaderCallableStatus.PASSIVE_NO_RESULT], CollectionAdapter ]: ... def get_collection( self, state: InstanceState[Any], dict_: _InstanceDict, user_data: Optional[_AdaptedCollectionProtocol] = None, passive: PassiveFlag = PassiveFlag.PASSIVE_OFF, ) -> Union[ Literal[LoaderCallableStatus.PASSIVE_NO_RESULT], CollectionAdapter ]: raise NotImplementedError() def set( self, state: InstanceState[Any], dict_: _InstanceDict, value: Any, initiator: Optional[AttributeEventToken] = None, passive: PassiveFlag = PassiveFlag.PASSIVE_OFF, check_old: Any = None, pop: bool = False, _adapt: bool = True, ) -> None: raise NotImplementedError() if TYPE_CHECKING: def _is_collection_attribute_impl( impl: AttributeImpl, ) -> TypeGuard[CollectionAttributeImpl]: ... else: _is_collection_attribute_impl = operator.attrgetter("collection") class CollectionAttributeImpl(HasCollectionAdapter, AttributeImpl): """A collection-holding attribute that instruments changes in membership. Only handles collections of instrumented objects. InstrumentedCollectionAttribute holds an arbitrary, user-specified container object (defaulting to a list) and brokers access to the CollectionAdapter, a "view" onto that object that presents consistent bag semantics to the orm layer independent of the user data implementation. """ uses_objects = True collection = True default_accepts_scalar_loader = False supports_population = True dynamic = False _bulk_replace_token: AttributeEventToken __slots__ = ( "copy", "collection_factory", "_append_token", "_remove_token", "_bulk_replace_token", "_duck_typed_as", ) def __init__( self, class_, key, callable_, dispatch, typecallable=None, trackparent=False, copy_function=None, compare_function=None, **kwargs, ): super().__init__( class_, key, callable_, dispatch, trackparent=trackparent, compare_function=compare_function, **kwargs, ) if copy_function is None: copy_function = self.__copy self.copy = copy_function self.collection_factory = typecallable self._append_token = AttributeEventToken(self, OP_APPEND) self._remove_token = AttributeEventToken(self, OP_REMOVE) self._bulk_replace_token = AttributeEventToken(self, OP_BULK_REPLACE) self._duck_typed_as = util.duck_type_collection( self.collection_factory() ) if getattr(self.collection_factory, "_sa_linker", None): @event.listens_for(self, "init_collection") def link(target, collection, collection_adapter): collection._sa_linker(collection_adapter) @event.listens_for(self, "dispose_collection") def unlink(target, collection, collection_adapter): collection._sa_linker(None) def __copy(self, item): return [y for y in collections.collection_adapter(item)] def get_history( self, state: InstanceState[Any], dict_: _InstanceDict, passive: PassiveFlag = PASSIVE_OFF, ) -> History: current = self.get(state, dict_, passive=passive) if current is PASSIVE_NO_RESULT: if ( passive & PassiveFlag.INCLUDE_PENDING_MUTATIONS and self.key in state._pending_mutations ): pending = state._pending_mutations[self.key] return pending.merge_with_history(HISTORY_BLANK) else: return HISTORY_BLANK else: if passive & PassiveFlag.INCLUDE_PENDING_MUTATIONS: # this collection is loaded / present. should not be any # pending mutations assert self.key not in state._pending_mutations return History.from_collection(self, state, current) def get_all_pending( self, state: InstanceState[Any], dict_: _InstanceDict, passive: PassiveFlag = PASSIVE_NO_INITIALIZE, ) -> _AllPendingType: # NOTE: passive is ignored here at the moment if self.key not in dict_: return [] current = dict_[self.key] current = getattr(current, "_sa_adapter") if self.key in state.committed_state: original = state.committed_state[self.key] if original is not NO_VALUE: current_states = [ ((c is not None) and instance_state(c) or None, c) for c in current ] original_states = [ ((c is not None) and instance_state(c) or None, c) for c in original ] current_set = dict(current_states) original_set = dict(original_states) return ( [ (s, o) for s, o in current_states if s not in original_set ] + [(s, o) for s, o in current_states if s in original_set] + [ (s, o) for s, o in original_states if s not in current_set ] ) return [(instance_state(o), o) for o in current] def fire_append_event( self, state: InstanceState[Any], dict_: _InstanceDict, value: _T, initiator: Optional[AttributeEventToken], key: Optional[Any], ) -> _T: for fn in self.dispatch.append: value = fn(state, value, initiator or self._append_token, key=key) state._modified_event(dict_, self, NO_VALUE, True) if self.trackparent and value is not None: self.sethasparent(instance_state(value), state, True) return value def fire_append_wo_mutation_event( self, state: InstanceState[Any], dict_: _InstanceDict, value: _T, initiator: Optional[AttributeEventToken], key: Optional[Any], ) -> _T: for fn in self.dispatch.append_wo_mutation: value = fn(state, value, initiator or self._append_token, key=key) return value def fire_pre_remove_event( self, state: InstanceState[Any], dict_: _InstanceDict, initiator: Optional[AttributeEventToken], key: Optional[Any], ) -> None: """A special event used for pop() operations. The "remove" event needs to have the item to be removed passed to it, which in the case of pop from a set, we don't have a way to access the item before the operation. the event is used for all pop() operations (even though set.pop is the one where it is really needed). """ state._modified_event(dict_, self, NO_VALUE, True) def fire_remove_event( self, state: InstanceState[Any], dict_: _InstanceDict, value: Any, initiator: Optional[AttributeEventToken], key: Optional[Any], ) -> None: if self.trackparent and value is not None: self.sethasparent(instance_state(value), state, False) for fn in self.dispatch.remove: fn(state, value, initiator or self._remove_token, key=key) state._modified_event(dict_, self, NO_VALUE, True) def delete(self, state: InstanceState[Any], dict_: _InstanceDict) -> None: if self.key not in dict_: return state._modified_event(dict_, self, NO_VALUE, True) collection = self.get_collection(state, state.dict) collection.clear_with_event() # key is always present because we checked above. e.g. # del is a no-op if collection not present. del dict_[self.key] def _default_value( self, state: InstanceState[Any], dict_: _InstanceDict ) -> _AdaptedCollectionProtocol: """Produce an empty collection for an un-initialized attribute""" assert self.key not in dict_, ( "_default_value should only be invoked for an " "uninitialized or expired attribute" ) if self.key in state._empty_collections: return state._empty_collections[self.key] adapter, user_data = self._initialize_collection(state) adapter._set_empty(user_data) return user_data def _initialize_collection( self, state: InstanceState[Any] ) -> Tuple[CollectionAdapter, _AdaptedCollectionProtocol]: adapter, collection = state.manager.initialize_collection( self.key, state, self.collection_factory ) self.dispatch.init_collection(state, collection, adapter) return adapter, collection def append( self, state: InstanceState[Any], dict_: _InstanceDict, value: Any, initiator: Optional[AttributeEventToken], passive: PassiveFlag = PASSIVE_OFF, ) -> None: collection = self.get_collection( state, dict_, user_data=None, passive=passive ) if collection is PASSIVE_NO_RESULT: value = self.fire_append_event( state, dict_, value, initiator, key=NO_KEY ) assert ( self.key not in dict_ ), "Collection was loaded during event handling." state._get_pending_mutation(self.key).append(value) else: if TYPE_CHECKING: assert isinstance(collection, CollectionAdapter) collection.append_with_event(value, initiator) def remove( self, state: InstanceState[Any], dict_: _InstanceDict, value: Any, initiator: Optional[AttributeEventToken], passive: PassiveFlag = PASSIVE_OFF, ) -> None: collection = self.get_collection( state, state.dict, user_data=None, passive=passive ) if collection is PASSIVE_NO_RESULT: self.fire_remove_event(state, dict_, value, initiator, key=NO_KEY) assert ( self.key not in dict_ ), "Collection was loaded during event handling." state._get_pending_mutation(self.key).remove(value) else: if TYPE_CHECKING: assert isinstance(collection, CollectionAdapter) collection.remove_with_event(value, initiator) def pop( self, state: InstanceState[Any], dict_: _InstanceDict, value: Any, initiator: Optional[AttributeEventToken], passive: PassiveFlag = PASSIVE_OFF, ) -> None: try: # TODO: better solution here would be to add # a "popper" role to collections.py to complement # "remover". self.remove(state, dict_, value, initiator, passive=passive) except (ValueError, KeyError, IndexError): pass def set( self, state: InstanceState[Any], dict_: _InstanceDict, value: Any, initiator: Optional[AttributeEventToken] = None, passive: PassiveFlag = PassiveFlag.PASSIVE_OFF, check_old: Any = None, pop: bool = False, _adapt: bool = True, ) -> None: iterable = orig_iterable = value new_keys = None # pulling a new collection first so that an adaptation exception does # not trigger a lazy load of the old collection. new_collection, user_data = self._initialize_collection(state) if _adapt: if new_collection._converter is not None: iterable = new_collection._converter(iterable) else: setting_type = util.duck_type_collection(iterable) receiving_type = self._duck_typed_as if setting_type is not receiving_type: given = ( iterable is None and "None" or iterable.__class__.__name__ ) wanted = self._duck_typed_as.__name__ raise TypeError( "Incompatible collection type: %s is not %s-like" % (given, wanted) ) # If the object is an adapted collection, return the (iterable) # adapter. if hasattr(iterable, "_sa_iterator"): iterable = iterable._sa_iterator() elif setting_type is dict: new_keys = list(iterable) iterable = iterable.values() else: iterable = iter(iterable) elif util.duck_type_collection(iterable) is dict: new_keys = list(value) new_values = list(iterable) evt = self._bulk_replace_token self.dispatch.bulk_replace(state, new_values, evt, keys=new_keys) # propagate NO_RAISE in passive through to the get() for the # existing object (ticket #8862) old = self.get( state, dict_, passive=PASSIVE_ONLY_PERSISTENT ^ (passive & PassiveFlag.NO_RAISE), ) if old is PASSIVE_NO_RESULT: old = self._default_value(state, dict_) elif old is orig_iterable: # ignore re-assignment of the current collection, as happens # implicitly with in-place operators (foo.collection |= other) return # place a copy of "old" in state.committed_state state._modified_event(dict_, self, old, True) old_collection = old._sa_adapter dict_[self.key] = user_data collections.bulk_replace( new_values, old_collection, new_collection, initiator=evt ) self._dispose_previous_collection(state, old, old_collection, True) def _dispose_previous_collection( self, state: InstanceState[Any], collection: _AdaptedCollectionProtocol, adapter: CollectionAdapter, fire_event: bool, ) -> None: del collection._sa_adapter # discarding old collection make sure it is not referenced in empty # collections. state._empty_collections.pop(self.key, None) if fire_event: self.dispatch.dispose_collection(state, collection, adapter) def _invalidate_collection( self, collection: _AdaptedCollectionProtocol ) -> None: adapter = getattr(collection, "_sa_adapter") adapter.invalidated = True def set_committed_value( self, state: InstanceState[Any], dict_: _InstanceDict, value: Any ) -> _AdaptedCollectionProtocol: """Set an attribute value on the given instance and 'commit' it.""" collection, user_data = self._initialize_collection(state) if value: collection.append_multiple_without_event(value) state.dict[self.key] = user_data state._commit(dict_, [self.key]) if self.key in state._pending_mutations: # pending items exist. issue a modified event, # add/remove new items. state._modified_event(dict_, self, user_data, True) pending = state._pending_mutations.pop(self.key) added = pending.added_items removed = pending.deleted_items for item in added: collection.append_without_event(item) for item in removed: collection.remove_without_event(item) return user_data @overload def get_collection( self, state: InstanceState[Any], dict_: _InstanceDict, user_data: Literal[None] = ..., passive: Literal[PassiveFlag.PASSIVE_OFF] = ..., ) -> CollectionAdapter: ... @overload def get_collection( self, state: InstanceState[Any], dict_: _InstanceDict, user_data: _AdaptedCollectionProtocol = ..., passive: PassiveFlag = ..., ) -> CollectionAdapter: ... @overload def get_collection( self, state: InstanceState[Any], dict_: _InstanceDict, user_data: Optional[_AdaptedCollectionProtocol] = ..., passive: PassiveFlag = PASSIVE_OFF, ) -> Union[ Literal[LoaderCallableStatus.PASSIVE_NO_RESULT], CollectionAdapter ]: ... def get_collection( self, state: InstanceState[Any], dict_: _InstanceDict, user_data: Optional[_AdaptedCollectionProtocol] = None, passive: PassiveFlag = PASSIVE_OFF, ) -> Union[ Literal[LoaderCallableStatus.PASSIVE_NO_RESULT], CollectionAdapter ]: """Retrieve the CollectionAdapter associated with the given state. if user_data is None, retrieves it from the state using normal "get()" rules, which will fire lazy callables or return the "empty" collection value. """ if user_data is None: fetch_user_data = self.get(state, dict_, passive=passive) if fetch_user_data is LoaderCallableStatus.PASSIVE_NO_RESULT: return fetch_user_data else: user_data = cast("_AdaptedCollectionProtocol", fetch_user_data) return user_data._sa_adapter def backref_listeners( attribute: QueryableAttribute[Any], key: str, uselist: bool ) -> None: """Apply listeners to synchronize a two-way relationship.""" # use easily recognizable names for stack traces. # in the sections marked "tokens to test for a recursive loop", # this is somewhat brittle and very performance-sensitive logic # that is specific to how we might arrive at each event. a marker # that can target us directly to arguments being invoked against # the impl might be simpler, but could interfere with other systems. parent_token = attribute.impl.parent_token parent_impl = attribute.impl def _acceptable_key_err(child_state, initiator, child_impl): raise ValueError( "Bidirectional attribute conflict detected: " 'Passing object %s to attribute "%s" ' 'triggers a modify event on attribute "%s" ' 'via the backref "%s".' % ( state_str(child_state), initiator.parent_token, child_impl.parent_token, attribute.impl.parent_token, ) ) def emit_backref_from_scalar_set_event( state, child, oldchild, initiator, **kw ): if oldchild is child: return child if ( oldchild is not None and oldchild is not PASSIVE_NO_RESULT and oldchild is not NO_VALUE ): # With lazy=None, there's no guarantee that the full collection is # present when updating via a backref. old_state, old_dict = ( instance_state(oldchild), instance_dict(oldchild), ) impl = old_state.manager[key].impl # tokens to test for a recursive loop. if not impl.collection and not impl.dynamic: check_recursive_token = impl._replace_token else: check_recursive_token = impl._remove_token if initiator is not check_recursive_token: impl.pop( old_state, old_dict, state.obj(), parent_impl._append_token, passive=PASSIVE_NO_FETCH, ) if child is not None: child_state, child_dict = ( instance_state(child), instance_dict(child), ) child_impl = child_state.manager[key].impl if ( initiator.parent_token is not parent_token and initiator.parent_token is not child_impl.parent_token ): _acceptable_key_err(state, initiator, child_impl) # tokens to test for a recursive loop. check_append_token = child_impl._append_token check_bulk_replace_token = ( child_impl._bulk_replace_token if _is_collection_attribute_impl(child_impl) else None ) if ( initiator is not check_append_token and initiator is not check_bulk_replace_token ): child_impl.append( child_state, child_dict, state.obj(), initiator, passive=PASSIVE_NO_FETCH, ) return child def emit_backref_from_collection_append_event( state, child, initiator, **kw ): if child is None: return child_state, child_dict = instance_state(child), instance_dict(child) child_impl = child_state.manager[key].impl if ( initiator.parent_token is not parent_token and initiator.parent_token is not child_impl.parent_token ): _acceptable_key_err(state, initiator, child_impl) # tokens to test for a recursive loop. check_append_token = child_impl._append_token check_bulk_replace_token = ( child_impl._bulk_replace_token if _is_collection_attribute_impl(child_impl) else None ) if ( initiator is not check_append_token and initiator is not check_bulk_replace_token ): child_impl.append( child_state, child_dict, state.obj(), initiator, passive=PASSIVE_NO_FETCH, ) return child def emit_backref_from_collection_remove_event( state, child, initiator, **kw ): if ( child is not None and child is not PASSIVE_NO_RESULT and child is not NO_VALUE ): child_state, child_dict = ( instance_state(child), instance_dict(child), ) child_impl = child_state.manager[key].impl check_replace_token: Optional[AttributeEventToken] # tokens to test for a recursive loop. if not child_impl.collection and not child_impl.dynamic: check_remove_token = child_impl._remove_token check_replace_token = child_impl._replace_token check_for_dupes_on_remove = uselist and not parent_impl.dynamic else: check_remove_token = child_impl._remove_token check_replace_token = ( child_impl._bulk_replace_token if _is_collection_attribute_impl(child_impl) else None ) check_for_dupes_on_remove = False if ( initiator is not check_remove_token and initiator is not check_replace_token ): if not check_for_dupes_on_remove or not util.has_dupes( # when this event is called, the item is usually # present in the list, except for a pop() operation. state.dict[parent_impl.key], child, ): child_impl.pop( child_state, child_dict, state.obj(), initiator, passive=PASSIVE_NO_FETCH, ) if uselist: event.listen( attribute, "append", emit_backref_from_collection_append_event, retval=True, raw=True, include_key=True, ) else: event.listen( attribute, "set", emit_backref_from_scalar_set_event, retval=True, raw=True, include_key=True, ) # TODO: need coverage in test/orm/ of remove event event.listen( attribute, "remove", emit_backref_from_collection_remove_event, retval=True, raw=True, include_key=True, ) _NO_HISTORY = util.symbol("NO_HISTORY") _NO_STATE_SYMBOLS = frozenset([id(PASSIVE_NO_RESULT), id(NO_VALUE)]) class History(NamedTuple): """A 3-tuple of added, unchanged and deleted values, representing the changes which have occurred on an instrumented attribute. The easiest way to get a :class:`.History` object for a particular attribute on an object is to use the :func:`_sa.inspect` function:: from sqlalchemy import inspect hist = inspect(myobject).attrs.myattribute.history Each tuple member is an iterable sequence: * ``added`` - the collection of items added to the attribute (the first tuple element). * ``unchanged`` - the collection of items that have not changed on the attribute (the second tuple element). * ``deleted`` - the collection of items that have been removed from the attribute (the third tuple element). """ added: Union[Tuple[()], List[Any]] unchanged: Union[Tuple[()], List[Any]] deleted: Union[Tuple[()], List[Any]] def __bool__(self) -> bool: return self != HISTORY_BLANK def empty(self) -> bool: """Return True if this :class:`.History` has no changes and no existing, unchanged state. """ return not bool((self.added or self.deleted) or self.unchanged) def sum(self) -> Sequence[Any]: """Return a collection of added + unchanged + deleted.""" return ( (self.added or []) + (self.unchanged or []) + (self.deleted or []) ) def non_deleted(self) -> Sequence[Any]: """Return a collection of added + unchanged.""" return (self.added or []) + (self.unchanged or []) def non_added(self) -> Sequence[Any]: """Return a collection of unchanged + deleted.""" return (self.unchanged or []) + (self.deleted or []) def has_changes(self) -> bool: """Return True if this :class:`.History` has changes.""" return bool(self.added or self.deleted) def _merge(self, added: Iterable[Any], deleted: Iterable[Any]) -> History: return History( list(self.added) + list(added), self.unchanged, list(self.deleted) + list(deleted), ) def as_state(self) -> History: return History( [ (c is not None) and instance_state(c) or None for c in self.added ], [ (c is not None) and instance_state(c) or None for c in self.unchanged ], [ (c is not None) and instance_state(c) or None for c in self.deleted ], ) @classmethod def from_scalar_attribute( cls, attribute: ScalarAttributeImpl, state: InstanceState[Any], current: Any, ) -> History: original = state.committed_state.get(attribute.key, _NO_HISTORY) deleted: Union[Tuple[()], List[Any]] if original is _NO_HISTORY: if current is NO_VALUE: return cls((), (), ()) else: return cls((), [current], ()) # don't let ClauseElement expressions here trip things up elif ( current is not NO_VALUE and attribute.is_equal(current, original) is True ): return cls((), [current], ()) else: # current convention on native scalars is to not # include information # about missing previous value in "deleted", but # we do include None, which helps in some primary # key situations if id(original) in _NO_STATE_SYMBOLS: deleted = () # indicate a "del" operation occurred when we don't have # the previous value as: ([None], (), ()) if id(current) in _NO_STATE_SYMBOLS: current = None else: deleted = [original] if current is NO_VALUE: return cls((), (), deleted) else: return cls([current], (), deleted) @classmethod def from_object_attribute( cls, attribute: ScalarObjectAttributeImpl, state: InstanceState[Any], current: Any, original: Any = _NO_HISTORY, ) -> History: deleted: Union[Tuple[()], List[Any]] if original is _NO_HISTORY: original = state.committed_state.get(attribute.key, _NO_HISTORY) if original is _NO_HISTORY: if current is NO_VALUE: return cls((), (), ()) else: return cls((), [current], ()) elif current is original and current is not NO_VALUE: return cls((), [current], ()) else: # current convention on related objects is to not # include information # about missing previous value in "deleted", and # to also not include None - the dependency.py rules # ignore the None in any case. if id(original) in _NO_STATE_SYMBOLS or original is None: deleted = () # indicate a "del" operation occurred when we don't have # the previous value as: ([None], (), ()) if id(current) in _NO_STATE_SYMBOLS: current = None else: deleted = [original] if current is NO_VALUE: return cls((), (), deleted) else: return cls([current], (), deleted) @classmethod def from_collection( cls, attribute: CollectionAttributeImpl, state: InstanceState[Any], current: Any, ) -> History: original = state.committed_state.get(attribute.key, _NO_HISTORY) if current is NO_VALUE: return cls((), (), ()) current = getattr(current, "_sa_adapter") if original is NO_VALUE: return cls(list(current), (), ()) elif original is _NO_HISTORY: return cls((), list(current), ()) else: current_states = [ ((c is not None) and instance_state(c) or None, c) for c in current ] original_states = [ ((c is not None) and instance_state(c) or None, c) for c in original ] current_set = dict(current_states) original_set = dict(original_states) return cls( [o for s, o in current_states if s not in original_set], [o for s, o in current_states if s in original_set], [o for s, o in original_states if s not in current_set], ) HISTORY_BLANK = History((), (), ()) def get_history( obj: object, key: str, passive: PassiveFlag = PASSIVE_OFF ) -> History: """Return a :class:`.History` record for the given object and attribute key. This is the **pre-flush** history for a given attribute, which is reset each time the :class:`.Session` flushes changes to the current database transaction. .. note:: Prefer to use the :attr:`.AttributeState.history` and :meth:`.AttributeState.load_history` accessors to retrieve the :class:`.History` for instance attributes. :param obj: an object whose class is instrumented by the attributes package. :param key: string attribute name. :param passive: indicates loading behavior for the attribute if the value is not already present. This is a bitflag attribute, which defaults to the symbol :attr:`.PASSIVE_OFF` indicating all necessary SQL should be emitted. .. seealso:: :attr:`.AttributeState.history` :meth:`.AttributeState.load_history` - retrieve history using loader callables if the value is not locally present. """ return get_state_history(instance_state(obj), key, passive) def get_state_history( state: InstanceState[Any], key: str, passive: PassiveFlag = PASSIVE_OFF ) -> History: return state.get_history(key, passive) def has_parent( cls: Type[_O], obj: _O, key: str, optimistic: bool = False ) -> bool: """TODO""" manager = manager_of_class(cls) state = instance_state(obj) return manager.has_parent(state, key, optimistic) def register_attribute( class_: Type[_O], key: str, *, comparator: interfaces.PropComparator[_T], parententity: _InternalEntityType[_O], doc: Optional[str] = None, **kw: Any, ) -> InstrumentedAttribute[_T]: desc = register_descriptor( class_, key, comparator=comparator, parententity=parententity, doc=doc ) register_attribute_impl(class_, key, **kw) return desc def register_attribute_impl( class_: Type[_O], key: str, uselist: bool = False, callable_: Optional[_LoaderCallable] = None, useobject: bool = False, impl_class: Optional[Type[AttributeImpl]] = None, backref: Optional[str] = None, **kw: Any, ) -> QueryableAttribute[Any]: manager = manager_of_class(class_) if uselist: factory = kw.pop("typecallable", None) typecallable = manager.instrument_collection_class( key, factory or list ) else: typecallable = kw.pop("typecallable", None) dispatch = cast( "_Dispatch[QueryableAttribute[Any]]", manager[key].dispatch ) # noqa: E501 impl: AttributeImpl if impl_class: # TODO: this appears to be the WriteOnlyAttributeImpl / # DynamicAttributeImpl constructor which is hardcoded impl = cast("Type[WriteOnlyAttributeImpl]", impl_class)( class_, key, dispatch, **kw ) elif uselist: impl = CollectionAttributeImpl( class_, key, callable_, dispatch, typecallable=typecallable, **kw ) elif useobject: impl = ScalarObjectAttributeImpl( class_, key, callable_, dispatch, **kw ) else: impl = ScalarAttributeImpl(class_, key, callable_, dispatch, **kw) manager[key].impl = impl if backref: backref_listeners(manager[key], backref, uselist) manager.post_configure_attribute(key) return manager[key] def register_descriptor( class_: Type[Any], key: str, *, comparator: interfaces.PropComparator[_T], parententity: _InternalEntityType[Any], doc: Optional[str] = None, ) -> InstrumentedAttribute[_T]: manager = manager_of_class(class_) descriptor = InstrumentedAttribute( class_, key, comparator=comparator, parententity=parententity ) descriptor.__doc__ = doc # type: ignore manager.instrument_attribute(key, descriptor) return descriptor def unregister_attribute(class_: Type[Any], key: str) -> None: manager_of_class(class_).uninstrument_attribute(key) def init_collection(obj: object, key: str) -> CollectionAdapter: """Initialize a collection attribute and return the collection adapter. This function is used to provide direct access to collection internals for a previously unloaded attribute. e.g.:: collection_adapter = init_collection(someobject, "elements") for elem in values: collection_adapter.append_without_event(elem) For an easier way to do the above, see :func:`~sqlalchemy.orm.attributes.set_committed_value`. :param obj: a mapped object :param key: string attribute name where the collection is located. """ state = instance_state(obj) dict_ = state.dict return init_state_collection(state, dict_, key) def init_state_collection( state: InstanceState[Any], dict_: _InstanceDict, key: str ) -> CollectionAdapter: """Initialize a collection attribute and return the collection adapter. Discards any existing collection which may be there. """ attr = state.manager[key].impl if TYPE_CHECKING: assert isinstance(attr, HasCollectionAdapter) old = dict_.pop(key, None) # discard old collection if old is not None: old_collection = old._sa_adapter attr._dispose_previous_collection(state, old, old_collection, False) user_data = attr._default_value(state, dict_) adapter: CollectionAdapter = attr.get_collection( state, dict_, user_data, passive=PassiveFlag.PASSIVE_NO_FETCH ) adapter._reset_empty() return adapter def set_committed_value(instance, key, value): """Set the value of an attribute with no history events. Cancels any previous history present. The value should be a scalar value for scalar-holding attributes, or an iterable for any collection-holding attribute. This is the same underlying method used when a lazy loader fires off and loads additional data from the database. In particular, this method can be used by application code which has loaded additional attributes or collections through separate queries, which can then be attached to an instance as though it were part of its original loaded state. """ state, dict_ = instance_state(instance), instance_dict(instance) state.manager[key].impl.set_committed_value(state, dict_, value) def set_attribute( instance: object, key: str, value: Any, initiator: Optional[AttributeEventToken] = None, ) -> None: """Set the value of an attribute, firing history events. This function may be used regardless of instrumentation applied directly to the class, i.e. no descriptors are required. Custom attribute management schemes will need to make usage of this method to establish attribute state as understood by SQLAlchemy. :param instance: the object that will be modified :param key: string name of the attribute :param value: value to assign :param initiator: an instance of :class:`.Event` that would have been propagated from a previous event listener. This argument is used when the :func:`.set_attribute` function is being used within an existing event listening function where an :class:`.Event` object is being supplied; the object may be used to track the origin of the chain of events. .. versionadded:: 1.2.3 """ state, dict_ = instance_state(instance), instance_dict(instance) state.manager[key].impl.set(state, dict_, value, initiator) def get_attribute(instance: object, key: str) -> Any: """Get the value of an attribute, firing any callables required. This function may be used regardless of instrumentation applied directly to the class, i.e. no descriptors are required. Custom attribute management schemes will need to make usage of this method to make usage of attribute state as understood by SQLAlchemy. """ state, dict_ = instance_state(instance), instance_dict(instance) return state.manager[key].impl.get(state, dict_) def del_attribute(instance: object, key: str) -> None: """Delete the value of an attribute, firing history events. This function may be used regardless of instrumentation applied directly to the class, i.e. no descriptors are required. Custom attribute management schemes will need to make usage of this method to establish attribute state as understood by SQLAlchemy. """ state, dict_ = instance_state(instance), instance_dict(instance) state.manager[key].impl.delete(state, dict_) def flag_modified(instance: object, key: str) -> None: """Mark an attribute on an instance as 'modified'. This sets the 'modified' flag on the instance and establishes an unconditional change event for the given attribute. The attribute must have a value present, else an :class:`.InvalidRequestError` is raised. To mark an object "dirty" without referring to any specific attribute so that it is considered within a flush, use the :func:`.attributes.flag_dirty` call. .. seealso:: :func:`.attributes.flag_dirty` """ state, dict_ = instance_state(instance), instance_dict(instance) impl = state.manager[key].impl impl.dispatch.modified(state, impl._modified_token) state._modified_event(dict_, impl, NO_VALUE, is_userland=True) def flag_dirty(instance: object) -> None: """Mark an instance as 'dirty' without any specific attribute mentioned. This is a special operation that will allow the object to travel through the flush process for interception by events such as :meth:`.SessionEvents.before_flush`. Note that no SQL will be emitted in the flush process for an object that has no changes, even if marked dirty via this method. However, a :meth:`.SessionEvents.before_flush` handler will be able to see the object in the :attr:`.Session.dirty` collection and may establish changes on it, which will then be included in the SQL emitted. .. versionadded:: 1.2 .. seealso:: :func:`.attributes.flag_modified` """ state, dict_ = instance_state(instance), instance_dict(instance) state._modified_event(dict_, None, NO_VALUE, is_userland=True) sqlalchemy/orm/state.py 0000755 00000111446 15125143220 0011202 0 ustar 00 # orm/state.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """Defines instrumentation of instances. This module is usually not directly visible to user applications, but defines a large part of the ORM's interactivity. """ from __future__ import annotations from typing import Any from typing import Callable from typing import Dict from typing import Generic from typing import Iterable from typing import Optional from typing import Set from typing import Tuple from typing import TYPE_CHECKING from typing import Union import weakref from . import base from . import exc as orm_exc from . import interfaces from ._typing import _O from ._typing import is_collection_impl from .base import ATTR_WAS_SET from .base import INIT_OK from .base import LoaderCallableStatus from .base import NEVER_SET from .base import NO_VALUE from .base import PASSIVE_NO_INITIALIZE from .base import PASSIVE_NO_RESULT from .base import PASSIVE_OFF from .base import SQL_OK from .path_registry import PathRegistry from .. import exc as sa_exc from .. import inspection from .. import util from ..util.typing import Literal from ..util.typing import Protocol if TYPE_CHECKING: from ._typing import _IdentityKeyType from ._typing import _InstanceDict from ._typing import _LoaderCallable from .attributes import AttributeImpl from .attributes import History from .base import PassiveFlag from .collections import _AdaptedCollectionProtocol from .identity import IdentityMap from .instrumentation import ClassManager from .interfaces import ORMOption from .mapper import Mapper from .session import Session from ..engine import Row from ..ext.asyncio.session import async_session as _async_provider from ..ext.asyncio.session import AsyncSession if TYPE_CHECKING: _sessions: weakref.WeakValueDictionary[int, Session] else: # late-populated by session.py _sessions = None if not TYPE_CHECKING: # optionally late-provided by sqlalchemy.ext.asyncio.session _async_provider = None # noqa class _InstanceDictProto(Protocol): def __call__(self) -> Optional[IdentityMap]: ... class _InstallLoaderCallableProto(Protocol[_O]): """used at result loading time to install a _LoaderCallable callable upon a specific InstanceState, which will be used to populate an attribute when that attribute is accessed. Concrete examples are per-instance deferred column loaders and relationship lazy loaders. """ def __call__( self, state: InstanceState[_O], dict_: _InstanceDict, row: Row[Any] ) -> None: ... @inspection._self_inspects class InstanceState(interfaces.InspectionAttrInfo, Generic[_O]): """Tracks state information at the instance level. The :class:`.InstanceState` is a key object used by the SQLAlchemy ORM in order to track the state of an object; it is created the moment an object is instantiated, typically as a result of :term:`instrumentation` which SQLAlchemy applies to the ``__init__()`` method of the class. :class:`.InstanceState` is also a semi-public object, available for runtime inspection as to the state of a mapped instance, including information such as its current status within a particular :class:`.Session` and details about data on individual attributes. The public API in order to acquire a :class:`.InstanceState` object is to use the :func:`_sa.inspect` system:: >>> from sqlalchemy import inspect >>> insp = inspect(some_mapped_object) >>> insp.attrs.nickname.history History(added=['new nickname'], unchanged=(), deleted=['nickname']) .. seealso:: :ref:`orm_mapper_inspection_instancestate` """ __slots__ = ( "__dict__", "__weakref__", "class_", "manager", "obj", "committed_state", "expired_attributes", ) manager: ClassManager[_O] session_id: Optional[int] = None key: Optional[_IdentityKeyType[_O]] = None runid: Optional[int] = None load_options: Tuple[ORMOption, ...] = () load_path: PathRegistry = PathRegistry.root insert_order: Optional[int] = None _strong_obj: Optional[object] = None obj: weakref.ref[_O] committed_state: Dict[str, Any] modified: bool = False """When ``True`` the object was modified.""" expired: bool = False """When ``True`` the object is :term:`expired`. .. seealso:: :ref:`session_expire` """ _deleted: bool = False _load_pending: bool = False _orphaned_outside_of_session: bool = False is_instance: bool = True identity_token: object = None _last_known_values: Optional[Dict[str, Any]] = None _instance_dict: _InstanceDictProto """A weak reference, or in the default case a plain callable, that returns a reference to the current :class:`.IdentityMap`, if any. """ if not TYPE_CHECKING: def _instance_dict(self): """default 'weak reference' for _instance_dict""" return None expired_attributes: Set[str] """The set of keys which are 'expired' to be loaded by the manager's deferred scalar loader, assuming no pending changes. See also the ``unmodified`` collection which is intersected against this set when a refresh operation occurs. """ callables: Dict[str, Callable[[InstanceState[_O], PassiveFlag], Any]] """A namespace where a per-state loader callable can be associated. In SQLAlchemy 1.0, this is only used for lazy loaders / deferred loaders that were set up via query option. Previously, callables was used also to indicate expired attributes by storing a link to the InstanceState itself in this dictionary. This role is now handled by the expired_attributes set. """ if not TYPE_CHECKING: callables = util.EMPTY_DICT def __init__(self, obj: _O, manager: ClassManager[_O]): self.class_ = obj.__class__ self.manager = manager self.obj = weakref.ref(obj, self._cleanup) self.committed_state = {} self.expired_attributes = set() @util.memoized_property def attrs(self) -> util.ReadOnlyProperties[AttributeState]: """Return a namespace representing each attribute on the mapped object, including its current value and history. The returned object is an instance of :class:`.AttributeState`. This object allows inspection of the current data within an attribute as well as attribute history since the last flush. """ return util.ReadOnlyProperties( {key: AttributeState(self, key) for key in self.manager} ) @property def transient(self) -> bool: """Return ``True`` if the object is :term:`transient`. .. seealso:: :ref:`session_object_states` """ return self.key is None and not self._attached @property def pending(self) -> bool: """Return ``True`` if the object is :term:`pending`. .. seealso:: :ref:`session_object_states` """ return self.key is None and self._attached @property def deleted(self) -> bool: """Return ``True`` if the object is :term:`deleted`. An object that is in the deleted state is guaranteed to not be within the :attr:`.Session.identity_map` of its parent :class:`.Session`; however if the session's transaction is rolled back, the object will be restored to the persistent state and the identity map. .. note:: The :attr:`.InstanceState.deleted` attribute refers to a specific state of the object that occurs between the "persistent" and "detached" states; once the object is :term:`detached`, the :attr:`.InstanceState.deleted` attribute **no longer returns True**; in order to detect that a state was deleted, regardless of whether or not the object is associated with a :class:`.Session`, use the :attr:`.InstanceState.was_deleted` accessor. .. versionadded: 1.1 .. seealso:: :ref:`session_object_states` """ return self.key is not None and self._attached and self._deleted @property def was_deleted(self) -> bool: """Return True if this object is or was previously in the "deleted" state and has not been reverted to persistent. This flag returns True once the object was deleted in flush. When the object is expunged from the session either explicitly or via transaction commit and enters the "detached" state, this flag will continue to report True. .. seealso:: :attr:`.InstanceState.deleted` - refers to the "deleted" state :func:`.orm.util.was_deleted` - standalone function :ref:`session_object_states` """ return self._deleted @property def persistent(self) -> bool: """Return ``True`` if the object is :term:`persistent`. An object that is in the persistent state is guaranteed to be within the :attr:`.Session.identity_map` of its parent :class:`.Session`. .. seealso:: :ref:`session_object_states` """ return self.key is not None and self._attached and not self._deleted @property def detached(self) -> bool: """Return ``True`` if the object is :term:`detached`. .. seealso:: :ref:`session_object_states` """ return self.key is not None and not self._attached @util.non_memoized_property @util.preload_module("sqlalchemy.orm.session") def _attached(self) -> bool: return ( self.session_id is not None and self.session_id in util.preloaded.orm_session._sessions ) def _track_last_known_value(self, key: str) -> None: """Track the last known value of a particular key after expiration operations. .. versionadded:: 1.3 """ lkv = self._last_known_values if lkv is None: self._last_known_values = lkv = {} if key not in lkv: lkv[key] = NO_VALUE @property def session(self) -> Optional[Session]: """Return the owning :class:`.Session` for this instance, or ``None`` if none available. Note that the result here can in some cases be *different* from that of ``obj in session``; an object that's been deleted will report as not ``in session``, however if the transaction is still in progress, this attribute will still refer to that session. Only when the transaction is completed does the object become fully detached under normal circumstances. .. seealso:: :attr:`_orm.InstanceState.async_session` """ if self.session_id: try: return _sessions[self.session_id] except KeyError: pass return None @property def async_session(self) -> Optional[AsyncSession]: """Return the owning :class:`_asyncio.AsyncSession` for this instance, or ``None`` if none available. This attribute is only non-None when the :mod:`sqlalchemy.ext.asyncio` API is in use for this ORM object. The returned :class:`_asyncio.AsyncSession` object will be a proxy for the :class:`_orm.Session` object that would be returned from the :attr:`_orm.InstanceState.session` attribute for this :class:`_orm.InstanceState`. .. versionadded:: 1.4.18 .. seealso:: :ref:`asyncio_toplevel` """ if _async_provider is None: return None sess = self.session if sess is not None: return _async_provider(sess) else: return None @property def object(self) -> Optional[_O]: """Return the mapped object represented by this :class:`.InstanceState`. Returns None if the object has been garbage collected """ return self.obj() @property def identity(self) -> Optional[Tuple[Any, ...]]: """Return the mapped identity of the mapped object. This is the primary key identity as persisted by the ORM which can always be passed directly to :meth:`_query.Query.get`. Returns ``None`` if the object has no primary key identity. .. note:: An object which is :term:`transient` or :term:`pending` does **not** have a mapped identity until it is flushed, even if its attributes include primary key values. """ if self.key is None: return None else: return self.key[1] @property def identity_key(self) -> Optional[_IdentityKeyType[_O]]: """Return the identity key for the mapped object. This is the key used to locate the object within the :attr:`.Session.identity_map` mapping. It contains the identity as returned by :attr:`.identity` within it. """ return self.key @util.memoized_property def parents(self) -> Dict[int, Union[Literal[False], InstanceState[Any]]]: return {} @util.memoized_property def _pending_mutations(self) -> Dict[str, PendingCollection]: return {} @util.memoized_property def _empty_collections(self) -> Dict[str, _AdaptedCollectionProtocol]: return {} @util.memoized_property def mapper(self) -> Mapper[_O]: """Return the :class:`_orm.Mapper` used for this mapped object.""" return self.manager.mapper @property def has_identity(self) -> bool: """Return ``True`` if this object has an identity key. This should always have the same value as the expression ``state.persistent`` or ``state.detached``. """ return bool(self.key) @classmethod def _detach_states( self, states: Iterable[InstanceState[_O]], session: Session, to_transient: bool = False, ) -> None: persistent_to_detached = ( session.dispatch.persistent_to_detached or None ) deleted_to_detached = session.dispatch.deleted_to_detached or None pending_to_transient = session.dispatch.pending_to_transient or None persistent_to_transient = ( session.dispatch.persistent_to_transient or None ) for state in states: deleted = state._deleted pending = state.key is None persistent = not pending and not deleted state.session_id = None if to_transient and state.key: del state.key if persistent: if to_transient: if persistent_to_transient is not None: persistent_to_transient(session, state) elif persistent_to_detached is not None: persistent_to_detached(session, state) elif deleted and deleted_to_detached is not None: deleted_to_detached(session, state) elif pending and pending_to_transient is not None: pending_to_transient(session, state) state._strong_obj = None def _detach(self, session: Optional[Session] = None) -> None: if session: InstanceState._detach_states([self], session) else: self.session_id = self._strong_obj = None def _dispose(self) -> None: # used by the test suite, apparently self._detach() def _cleanup(self, ref: weakref.ref[_O]) -> None: """Weakref callback cleanup. This callable cleans out the state when it is being garbage collected. this _cleanup **assumes** that there are no strong refs to us! Will not work otherwise! """ # Python builtins become undefined during interpreter shutdown. # Guard against exceptions during this phase, as the method cannot # proceed in any case if builtins have been undefined. if dict is None: return instance_dict = self._instance_dict() if instance_dict is not None: instance_dict._fast_discard(self) del self._instance_dict # we can't possibly be in instance_dict._modified # b.c. this is weakref cleanup only, that set # is strong referencing! # assert self not in instance_dict._modified self.session_id = self._strong_obj = None @property def dict(self) -> _InstanceDict: """Return the instance dict used by the object. Under normal circumstances, this is always synonymous with the ``__dict__`` attribute of the mapped object, unless an alternative instrumentation system has been configured. In the case that the actual object has been garbage collected, this accessor returns a blank dictionary. """ o = self.obj() if o is not None: return base.instance_dict(o) else: return {} def _initialize_instance(*mixed: Any, **kwargs: Any) -> None: self, instance, args = mixed[0], mixed[1], mixed[2:] # noqa manager = self.manager manager.dispatch.init(self, args, kwargs) try: manager.original_init(*mixed[1:], **kwargs) except: with util.safe_reraise(): manager.dispatch.init_failure(self, args, kwargs) def get_history(self, key: str, passive: PassiveFlag) -> History: return self.manager[key].impl.get_history(self, self.dict, passive) def get_impl(self, key: str) -> AttributeImpl: return self.manager[key].impl def _get_pending_mutation(self, key: str) -> PendingCollection: if key not in self._pending_mutations: self._pending_mutations[key] = PendingCollection() return self._pending_mutations[key] def __getstate__(self) -> Dict[str, Any]: state_dict: Dict[str, Any] = { "instance": self.obj(), "class_": self.class_, "committed_state": self.committed_state, "expired_attributes": self.expired_attributes, } state_dict.update( (k, self.__dict__[k]) for k in ( "_pending_mutations", "modified", "expired", "callables", "key", "parents", "load_options", "class_", "expired_attributes", "info", ) if k in self.__dict__ ) if self.load_path: state_dict["load_path"] = self.load_path.serialize() state_dict["manager"] = self.manager._serialize(self, state_dict) return state_dict def __setstate__(self, state_dict: Dict[str, Any]) -> None: inst = state_dict["instance"] if inst is not None: self.obj = weakref.ref(inst, self._cleanup) self.class_ = inst.__class__ else: self.obj = lambda: None # type: ignore self.class_ = state_dict["class_"] self.committed_state = state_dict.get("committed_state", {}) self._pending_mutations = state_dict.get("_pending_mutations", {}) self.parents = state_dict.get("parents", {}) self.modified = state_dict.get("modified", False) self.expired = state_dict.get("expired", False) if "info" in state_dict: self.info.update(state_dict["info"]) if "callables" in state_dict: self.callables = state_dict["callables"] self.expired_attributes = state_dict["expired_attributes"] else: if "expired_attributes" in state_dict: self.expired_attributes = state_dict["expired_attributes"] else: self.expired_attributes = set() self.__dict__.update( [ (k, state_dict[k]) for k in ("key", "load_options") if k in state_dict ] ) if self.key: self.identity_token = self.key[2] if "load_path" in state_dict: self.load_path = PathRegistry.deserialize(state_dict["load_path"]) state_dict["manager"](self, inst, state_dict) def _reset(self, dict_: _InstanceDict, key: str) -> None: """Remove the given attribute and any callables associated with it.""" old = dict_.pop(key, None) manager_impl = self.manager[key].impl if old is not None and is_collection_impl(manager_impl): manager_impl._invalidate_collection(old) self.expired_attributes.discard(key) if self.callables: self.callables.pop(key, None) def _copy_callables(self, from_: InstanceState[Any]) -> None: if "callables" in from_.__dict__: self.callables = dict(from_.callables) @classmethod def _instance_level_callable_processor( cls, manager: ClassManager[_O], fn: _LoaderCallable, key: Any ) -> _InstallLoaderCallableProto[_O]: impl = manager[key].impl if is_collection_impl(impl): fixed_impl = impl def _set_callable( state: InstanceState[_O], dict_: _InstanceDict, row: Row[Any] ) -> None: if "callables" not in state.__dict__: state.callables = {} old = dict_.pop(key, None) if old is not None: fixed_impl._invalidate_collection(old) state.callables[key] = fn else: def _set_callable( state: InstanceState[_O], dict_: _InstanceDict, row: Row[Any] ) -> None: if "callables" not in state.__dict__: state.callables = {} state.callables[key] = fn return _set_callable def _expire( self, dict_: _InstanceDict, modified_set: Set[InstanceState[Any]] ) -> None: self.expired = True if self.modified: modified_set.discard(self) self.committed_state.clear() self.modified = False self._strong_obj = None if "_pending_mutations" in self.__dict__: del self.__dict__["_pending_mutations"] if "parents" in self.__dict__: del self.__dict__["parents"] self.expired_attributes.update( [impl.key for impl in self.manager._loader_impls] ) if self.callables: # the per state loader callables we can remove here are # LoadDeferredColumns, which undefers a column at the instance # level that is mapped with deferred, and LoadLazyAttribute, # which lazy loads a relationship at the instance level that # is mapped with "noload" or perhaps "immediateload". # Before 1.4, only column-based # attributes could be considered to be "expired", so here they # were the only ones "unexpired", which means to make them deferred # again. For the moment, as of 1.4 we also apply the same # treatment relationships now, that is, an instance level lazy # loader is reset in the same way as a column loader. for k in self.expired_attributes.intersection(self.callables): del self.callables[k] for k in self.manager._collection_impl_keys.intersection(dict_): collection = dict_.pop(k) collection._sa_adapter.invalidated = True if self._last_known_values: self._last_known_values.update( {k: dict_[k] for k in self._last_known_values if k in dict_} ) for key in self.manager._all_key_set.intersection(dict_): del dict_[key] self.manager.dispatch.expire(self, None) def _expire_attributes( self, dict_: _InstanceDict, attribute_names: Iterable[str], no_loader: bool = False, ) -> None: pending = self.__dict__.get("_pending_mutations", None) callables = self.callables for key in attribute_names: impl = self.manager[key].impl if impl.accepts_scalar_loader: if no_loader and (impl.callable_ or key in callables): continue self.expired_attributes.add(key) if callables and key in callables: del callables[key] old = dict_.pop(key, NO_VALUE) if is_collection_impl(impl) and old is not NO_VALUE: impl._invalidate_collection(old) lkv = self._last_known_values if lkv is not None and key in lkv and old is not NO_VALUE: lkv[key] = old self.committed_state.pop(key, None) if pending: pending.pop(key, None) self.manager.dispatch.expire(self, attribute_names) def _load_expired( self, state: InstanceState[_O], passive: PassiveFlag ) -> LoaderCallableStatus: """__call__ allows the InstanceState to act as a deferred callable for loading expired attributes, which is also serializable (picklable). """ if not passive & SQL_OK: return PASSIVE_NO_RESULT toload = self.expired_attributes.intersection(self.unmodified) toload = toload.difference( attr for attr in toload if not self.manager[attr].impl.load_on_unexpire ) self.manager.expired_attribute_loader(self, toload, passive) # if the loader failed, or this # instance state didn't have an identity, # the attributes still might be in the callables # dict. ensure they are removed. self.expired_attributes.clear() return ATTR_WAS_SET @property def unmodified(self) -> Set[str]: """Return the set of keys which have no uncommitted changes""" return set(self.manager).difference(self.committed_state) def unmodified_intersection(self, keys: Iterable[str]) -> Set[str]: """Return self.unmodified.intersection(keys).""" return ( set(keys) .intersection(self.manager) .difference(self.committed_state) ) @property def unloaded(self) -> Set[str]: """Return the set of keys which do not have a loaded value. This includes expired attributes and any other attribute that was never populated or modified. """ return ( set(self.manager) .difference(self.committed_state) .difference(self.dict) ) @property @util.deprecated( "2.0", "The :attr:`.InstanceState.unloaded_expirable` attribute is " "deprecated. Please use :attr:`.InstanceState.unloaded`.", ) def unloaded_expirable(self) -> Set[str]: """Synonymous with :attr:`.InstanceState.unloaded`. This attribute was added as an implementation-specific detail at some point and should be considered to be private. """ return self.unloaded @property def _unloaded_non_object(self) -> Set[str]: return self.unloaded.intersection( attr for attr in self.manager if self.manager[attr].impl.accepts_scalar_loader ) def _modified_event( self, dict_: _InstanceDict, attr: Optional[AttributeImpl], previous: Any, collection: bool = False, is_userland: bool = False, ) -> None: if attr: if not attr.send_modified_events: return if is_userland and attr.key not in dict_: raise sa_exc.InvalidRequestError( "Can't flag attribute '%s' modified; it's not present in " "the object state" % attr.key ) if attr.key not in self.committed_state or is_userland: if collection: if TYPE_CHECKING: assert is_collection_impl(attr) if previous is NEVER_SET: if attr.key in dict_: previous = dict_[attr.key] if previous not in (None, NO_VALUE, NEVER_SET): previous = attr.copy(previous) self.committed_state[attr.key] = previous lkv = self._last_known_values if lkv is not None and attr.key in lkv: lkv[attr.key] = NO_VALUE # assert self._strong_obj is None or self.modified if (self.session_id and self._strong_obj is None) or not self.modified: self.modified = True instance_dict = self._instance_dict() if instance_dict: has_modified = bool(instance_dict._modified) instance_dict._modified.add(self) else: has_modified = False # only create _strong_obj link if attached # to a session inst = self.obj() if self.session_id: self._strong_obj = inst # if identity map already had modified objects, # assume autobegin already occurred, else check # for autobegin if not has_modified: # inline of autobegin, to ensure session transaction # snapshot is established try: session = _sessions[self.session_id] except KeyError: pass else: if session._transaction is None: session._autobegin_t() if inst is None and attr: raise orm_exc.ObjectDereferencedError( "Can't emit change event for attribute '%s' - " "parent object of type %s has been garbage " "collected." % (self.manager[attr.key], base.state_class_str(self)) ) def _commit(self, dict_: _InstanceDict, keys: Iterable[str]) -> None: """Commit attributes. This is used by a partial-attribute load operation to mark committed those attributes which were refreshed from the database. Attributes marked as "expired" can potentially remain "expired" after this step if a value was not populated in state.dict. """ for key in keys: self.committed_state.pop(key, None) self.expired = False self.expired_attributes.difference_update( set(keys).intersection(dict_) ) # the per-keys commit removes object-level callables, # while that of commit_all does not. it's not clear # if this behavior has a clear rationale, however tests do # ensure this is what it does. if self.callables: for key in ( set(self.callables).intersection(keys).intersection(dict_) ): del self.callables[key] def _commit_all( self, dict_: _InstanceDict, instance_dict: Optional[IdentityMap] = None ) -> None: """commit all attributes unconditionally. This is used after a flush() or a full load/refresh to remove all pending state from the instance. - all attributes are marked as "committed" - the "strong dirty reference" is removed - the "modified" flag is set to False - any "expired" markers for scalar attributes loaded are removed. - lazy load callables for objects / collections *stay* Attributes marked as "expired" can potentially remain "expired" after this step if a value was not populated in state.dict. """ self._commit_all_states([(self, dict_)], instance_dict) @classmethod def _commit_all_states( self, iter_: Iterable[Tuple[InstanceState[Any], _InstanceDict]], instance_dict: Optional[IdentityMap] = None, ) -> None: """Mass / highly inlined version of commit_all().""" for state, dict_ in iter_: state_dict = state.__dict__ state.committed_state.clear() if "_pending_mutations" in state_dict: del state_dict["_pending_mutations"] state.expired_attributes.difference_update(dict_) if instance_dict and state.modified: instance_dict._modified.discard(state) state.modified = state.expired = False state._strong_obj = None class AttributeState: """Provide an inspection interface corresponding to a particular attribute on a particular mapped object. The :class:`.AttributeState` object is accessed via the :attr:`.InstanceState.attrs` collection of a particular :class:`.InstanceState`:: from sqlalchemy import inspect insp = inspect(some_mapped_object) attr_state = insp.attrs.some_attribute """ __slots__ = ("state", "key") state: InstanceState[Any] key: str def __init__(self, state: InstanceState[Any], key: str): self.state = state self.key = key @property def loaded_value(self) -> Any: """The current value of this attribute as loaded from the database. If the value has not been loaded, or is otherwise not present in the object's dictionary, returns NO_VALUE. """ return self.state.dict.get(self.key, NO_VALUE) @property def value(self) -> Any: """Return the value of this attribute. This operation is equivalent to accessing the object's attribute directly or via ``getattr()``, and will fire off any pending loader callables if needed. """ return self.state.manager[self.key].__get__( self.state.obj(), self.state.class_ ) @property def history(self) -> History: """Return the current **pre-flush** change history for this attribute, via the :class:`.History` interface. This method will **not** emit loader callables if the value of the attribute is unloaded. .. note:: The attribute history system tracks changes on a **per flush basis**. Each time the :class:`.Session` is flushed, the history of each attribute is reset to empty. The :class:`.Session` by default autoflushes each time a :class:`_query.Query` is invoked. For options on how to control this, see :ref:`session_flushing`. .. seealso:: :meth:`.AttributeState.load_history` - retrieve history using loader callables if the value is not locally present. :func:`.attributes.get_history` - underlying function """ return self.state.get_history(self.key, PASSIVE_NO_INITIALIZE) def load_history(self) -> History: """Return the current **pre-flush** change history for this attribute, via the :class:`.History` interface. This method **will** emit loader callables if the value of the attribute is unloaded. .. note:: The attribute history system tracks changes on a **per flush basis**. Each time the :class:`.Session` is flushed, the history of each attribute is reset to empty. The :class:`.Session` by default autoflushes each time a :class:`_query.Query` is invoked. For options on how to control this, see :ref:`session_flushing`. .. seealso:: :attr:`.AttributeState.history` :func:`.attributes.get_history` - underlying function """ return self.state.get_history(self.key, PASSIVE_OFF ^ INIT_OK) class PendingCollection: """A writable placeholder for an unloaded collection. Stores items appended to and removed from a collection that has not yet been loaded. When the collection is loaded, the changes stored in PendingCollection are applied to it to produce the final result. """ __slots__ = ("deleted_items", "added_items") deleted_items: util.IdentitySet added_items: util.OrderedIdentitySet def __init__(self) -> None: self.deleted_items = util.IdentitySet() self.added_items = util.OrderedIdentitySet() def merge_with_history(self, history: History) -> History: return history._merge(self.added_items, self.deleted_items) def append(self, value: Any) -> None: if value in self.deleted_items: self.deleted_items.remove(value) else: self.added_items.add(value) def remove(self, value: Any) -> None: if value in self.added_items: self.added_items.remove(value) else: self.deleted_items.add(value) sqlalchemy/orm/mapper.py 0000755 00000517261 15125143220 0011353 0 ustar 00 # orm/mapper.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: allow-untyped-defs, allow-untyped-calls """Logic to map Python classes to and from selectables. Defines the :class:`~sqlalchemy.orm.mapper.Mapper` class, the central configurational unit which associates a class with a database table. This is a semi-private module; the main configurational API of the ORM is available in :class:`~sqlalchemy.orm.`. """ from __future__ import annotations from collections import deque from functools import reduce from itertools import chain import sys import threading from typing import Any from typing import Callable from typing import cast from typing import Collection from typing import Deque from typing import Dict from typing import FrozenSet from typing import Generic from typing import Iterable from typing import Iterator from typing import List from typing import Mapping from typing import Optional from typing import Sequence from typing import Set from typing import Tuple from typing import Type from typing import TYPE_CHECKING from typing import TypeVar from typing import Union import weakref from . import attributes from . import exc as orm_exc from . import instrumentation from . import loading from . import properties from . import util as orm_util from ._typing import _O from .base import _class_to_mapper from .base import _parse_mapper_argument from .base import _state_mapper from .base import PassiveFlag from .base import state_str from .interfaces import _MappedAttribute from .interfaces import EXT_SKIP from .interfaces import InspectionAttr from .interfaces import MapperProperty from .interfaces import ORMEntityColumnsClauseRole from .interfaces import ORMFromClauseRole from .interfaces import StrategizedProperty from .path_registry import PathRegistry from .. import event from .. import exc as sa_exc from .. import inspection from .. import log from .. import schema from .. import sql from .. import util from ..event import dispatcher from ..event import EventTarget from ..sql import base as sql_base from ..sql import coercions from ..sql import expression from ..sql import operators from ..sql import roles from ..sql import TableClause from ..sql import util as sql_util from ..sql import visitors from ..sql.cache_key import MemoizedHasCacheKey from ..sql.elements import KeyedColumnElement from ..sql.schema import Column from ..sql.schema import Table from ..sql.selectable import LABEL_STYLE_TABLENAME_PLUS_COL from ..util import HasMemoized from ..util import HasMemoized_ro_memoized_attribute from ..util.typing import Literal if TYPE_CHECKING: from ._typing import _IdentityKeyType from ._typing import _InstanceDict from ._typing import _ORMColumnExprArgument from ._typing import _RegistryType from .decl_api import registry from .dependency import DependencyProcessor from .descriptor_props import CompositeProperty from .descriptor_props import SynonymProperty from .events import MapperEvents from .instrumentation import ClassManager from .path_registry import CachingEntityRegistry from .properties import ColumnProperty from .relationships import RelationshipProperty from .state import InstanceState from .util import ORMAdapter from ..engine import Row from ..engine import RowMapping from ..sql._typing import _ColumnExpressionArgument from ..sql._typing import _EquivalentColumnMap from ..sql.base import ReadOnlyColumnCollection from ..sql.elements import ColumnClause from ..sql.elements import ColumnElement from ..sql.selectable import FromClause from ..util import OrderedSet _T = TypeVar("_T", bound=Any) _MP = TypeVar("_MP", bound="MapperProperty[Any]") _Fn = TypeVar("_Fn", bound="Callable[..., Any]") _WithPolymorphicArg = Union[ Literal["*"], Tuple[ Union[Literal["*"], Sequence[Union["Mapper[Any]", Type[Any]]]], Optional["FromClause"], ], Sequence[Union["Mapper[Any]", Type[Any]]], ] _mapper_registries: weakref.WeakKeyDictionary[_RegistryType, bool] = ( weakref.WeakKeyDictionary() ) def _all_registries() -> Set[registry]: with _CONFIGURE_MUTEX: return set(_mapper_registries) def _unconfigured_mappers() -> Iterator[Mapper[Any]]: for reg in _all_registries(): yield from reg._mappers_to_configure() _already_compiling = False # a constant returned by _get_attr_by_column to indicate # this mapper is not handling an attribute for a particular # column NO_ATTRIBUTE = util.symbol("NO_ATTRIBUTE") # lock used to synchronize the "mapper configure" step _CONFIGURE_MUTEX = threading.RLock() @inspection._self_inspects @log.class_logger class Mapper( ORMFromClauseRole, ORMEntityColumnsClauseRole[_O], MemoizedHasCacheKey, InspectionAttr, log.Identified, inspection.Inspectable["Mapper[_O]"], EventTarget, Generic[_O], ): """Defines an association between a Python class and a database table or other relational structure, so that ORM operations against the class may proceed. The :class:`_orm.Mapper` object is instantiated using mapping methods present on the :class:`_orm.registry` object. For information about instantiating new :class:`_orm.Mapper` objects, see :ref:`orm_mapping_classes_toplevel`. """ dispatch: dispatcher[Mapper[_O]] _dispose_called = False _configure_failed: Any = False _ready_for_configure = False @util.deprecated_params( non_primary=( "1.3", "The :paramref:`.mapper.non_primary` parameter is deprecated, " "and will be removed in a future release. The functionality " "of non primary mappers is now better suited using the " ":class:`.AliasedClass` construct, which can also be used " "as the target of a :func:`_orm.relationship` in 1.3.", ), ) def __init__( self, class_: Type[_O], local_table: Optional[FromClause] = None, properties: Optional[Mapping[str, MapperProperty[Any]]] = None, primary_key: Optional[Iterable[_ORMColumnExprArgument[Any]]] = None, non_primary: bool = False, inherits: Optional[Union[Mapper[Any], Type[Any]]] = None, inherit_condition: Optional[_ColumnExpressionArgument[bool]] = None, inherit_foreign_keys: Optional[ Sequence[_ORMColumnExprArgument[Any]] ] = None, always_refresh: bool = False, version_id_col: Optional[_ORMColumnExprArgument[Any]] = None, version_id_generator: Optional[ Union[Literal[False], Callable[[Any], Any]] ] = None, polymorphic_on: Optional[ Union[_ORMColumnExprArgument[Any], str, MapperProperty[Any]] ] = None, _polymorphic_map: Optional[Dict[Any, Mapper[Any]]] = None, polymorphic_identity: Optional[Any] = None, concrete: bool = False, with_polymorphic: Optional[_WithPolymorphicArg] = None, polymorphic_abstract: bool = False, polymorphic_load: Optional[Literal["selectin", "inline"]] = None, allow_partial_pks: bool = True, batch: bool = True, column_prefix: Optional[str] = None, include_properties: Optional[Sequence[str]] = None, exclude_properties: Optional[Sequence[str]] = None, passive_updates: bool = True, passive_deletes: bool = False, confirm_deleted_rows: bool = True, eager_defaults: Literal[True, False, "auto"] = "auto", legacy_is_orphan: bool = False, _compiled_cache_size: int = 100, ): r"""Direct constructor for a new :class:`_orm.Mapper` object. The :class:`_orm.Mapper` constructor is not called directly, and is normally invoked through the use of the :class:`_orm.registry` object through either the :ref:`Declarative <orm_declarative_mapping>` or :ref:`Imperative <orm_imperative_mapping>` mapping styles. .. versionchanged:: 2.0 The public facing ``mapper()`` function is removed; for a classical mapping configuration, use the :meth:`_orm.registry.map_imperatively` method. Parameters documented below may be passed to either the :meth:`_orm.registry.map_imperatively` method, or may be passed in the ``__mapper_args__`` declarative class attribute described at :ref:`orm_declarative_mapper_options`. :param class\_: The class to be mapped. When using Declarative, this argument is automatically passed as the declared class itself. :param local_table: The :class:`_schema.Table` or other :class:`_sql.FromClause` (i.e. selectable) to which the class is mapped. May be ``None`` if this mapper inherits from another mapper using single-table inheritance. When using Declarative, this argument is automatically passed by the extension, based on what is configured via the :attr:`_orm.DeclarativeBase.__table__` attribute or via the :class:`_schema.Table` produced as a result of the :attr:`_orm.DeclarativeBase.__tablename__` attribute being present. :param polymorphic_abstract: Indicates this class will be mapped in a polymorphic hierarchy, but not directly instantiated. The class is mapped normally, except that it has no requirement for a :paramref:`_orm.Mapper.polymorphic_identity` within an inheritance hierarchy. The class however must be part of a polymorphic inheritance scheme which uses :paramref:`_orm.Mapper.polymorphic_on` at the base. .. versionadded:: 2.0 .. seealso:: :ref:`orm_inheritance_abstract_poly` :param always_refresh: If True, all query operations for this mapped class will overwrite all data within object instances that already exist within the session, erasing any in-memory changes with whatever information was loaded from the database. Usage of this flag is highly discouraged; as an alternative, see the method :meth:`_query.Query.populate_existing`. :param allow_partial_pks: Defaults to True. Indicates that a composite primary key with some NULL values should be considered as possibly existing within the database. This affects whether a mapper will assign an incoming row to an existing identity, as well as if :meth:`.Session.merge` will check the database first for a particular primary key value. A "partial primary key" can occur if one has mapped to an OUTER JOIN, for example. The :paramref:`.orm.Mapper.allow_partial_pks` parameter also indicates to the ORM relationship lazy loader, when loading a many-to-one related object, if a composite primary key that has partial NULL values should result in an attempt to load from the database, or if a load attempt is not necessary. .. versionadded:: 2.0.36 :paramref:`.orm.Mapper.allow_partial_pks` is consulted by the relationship lazy loader strategy, such that when set to False, a SELECT for a composite primary key that has partial NULL values will not be emitted. :param batch: Defaults to ``True``, indicating that save operations of multiple entities can be batched together for efficiency. Setting to False indicates that an instance will be fully saved before saving the next instance. This is used in the extremely rare case that a :class:`.MapperEvents` listener requires being called in between individual row persistence operations. :param column_prefix: A string which will be prepended to the mapped attribute name when :class:`_schema.Column` objects are automatically assigned as attributes to the mapped class. Does not affect :class:`.Column` objects that are mapped explicitly in the :paramref:`.Mapper.properties` dictionary. This parameter is typically useful with imperative mappings that keep the :class:`.Table` object separate. Below, assuming the ``user_table`` :class:`.Table` object has columns named ``user_id``, ``user_name``, and ``password``:: class User(Base): __table__ = user_table __mapper_args__ = {"column_prefix": "_"} The above mapping will assign the ``user_id``, ``user_name``, and ``password`` columns to attributes named ``_user_id``, ``_user_name``, and ``_password`` on the mapped ``User`` class. The :paramref:`.Mapper.column_prefix` parameter is uncommon in modern use. For dealing with reflected tables, a more flexible approach to automating a naming scheme is to intercept the :class:`.Column` objects as they are reflected; see the section :ref:`mapper_automated_reflection_schemes` for notes on this usage pattern. :param concrete: If True, indicates this mapper should use concrete table inheritance with its parent mapper. See the section :ref:`concrete_inheritance` for an example. :param confirm_deleted_rows: defaults to True; when a DELETE occurs of one more rows based on specific primary keys, a warning is emitted when the number of rows matched does not equal the number of rows expected. This parameter may be set to False to handle the case where database ON DELETE CASCADE rules may be deleting some of those rows automatically. The warning may be changed to an exception in a future release. :param eager_defaults: if True, the ORM will immediately fetch the value of server-generated default values after an INSERT or UPDATE, rather than leaving them as expired to be fetched on next access. This can be used for event schemes where the server-generated values are needed immediately before the flush completes. The fetch of values occurs either by using ``RETURNING`` inline with the ``INSERT`` or ``UPDATE`` statement, or by adding an additional ``SELECT`` statement subsequent to the ``INSERT`` or ``UPDATE``, if the backend does not support ``RETURNING``. The use of ``RETURNING`` is extremely performant in particular for ``INSERT`` statements where SQLAlchemy can take advantage of :ref:`insertmanyvalues <engine_insertmanyvalues>`, whereas the use of an additional ``SELECT`` is relatively poor performing, adding additional SQL round trips which would be unnecessary if these new attributes are not to be accessed in any case. For this reason, :paramref:`.Mapper.eager_defaults` defaults to the string value ``"auto"``, which indicates that server defaults for INSERT should be fetched using ``RETURNING`` if the backing database supports it and if the dialect in use supports "insertmanyreturning" for an INSERT statement. If the backing database does not support ``RETURNING`` or "insertmanyreturning" is not available, server defaults will not be fetched. .. versionchanged:: 2.0.0rc1 added the "auto" option for :paramref:`.Mapper.eager_defaults` .. seealso:: :ref:`orm_server_defaults` .. versionchanged:: 2.0.0 RETURNING now works with multiple rows INSERTed at once using the :ref:`insertmanyvalues <engine_insertmanyvalues>` feature, which among other things allows the :paramref:`.Mapper.eager_defaults` feature to be very performant on supporting backends. :param exclude_properties: A list or set of string column names to be excluded from mapping. .. seealso:: :ref:`include_exclude_cols` :param include_properties: An inclusive list or set of string column names to map. .. seealso:: :ref:`include_exclude_cols` :param inherits: A mapped class or the corresponding :class:`_orm.Mapper` of one indicating a superclass to which this :class:`_orm.Mapper` should *inherit* from. The mapped class here must be a subclass of the other mapper's class. When using Declarative, this argument is passed automatically as a result of the natural class hierarchy of the declared classes. .. seealso:: :ref:`inheritance_toplevel` :param inherit_condition: For joined table inheritance, a SQL expression which will define how the two tables are joined; defaults to a natural join between the two tables. :param inherit_foreign_keys: When ``inherit_condition`` is used and the columns present are missing a :class:`_schema.ForeignKey` configuration, this parameter can be used to specify which columns are "foreign". In most cases can be left as ``None``. :param legacy_is_orphan: Boolean, defaults to ``False``. When ``True``, specifies that "legacy" orphan consideration is to be applied to objects mapped by this mapper, which means that a pending (that is, not persistent) object is auto-expunged from an owning :class:`.Session` only when it is de-associated from *all* parents that specify a ``delete-orphan`` cascade towards this mapper. The new default behavior is that the object is auto-expunged when it is de-associated with *any* of its parents that specify ``delete-orphan`` cascade. This behavior is more consistent with that of a persistent object, and allows behavior to be consistent in more scenarios independently of whether or not an orphan object has been flushed yet or not. See the change note and example at :ref:`legacy_is_orphan_addition` for more detail on this change. :param non_primary: Specify that this :class:`_orm.Mapper` is in addition to the "primary" mapper, that is, the one used for persistence. The :class:`_orm.Mapper` created here may be used for ad-hoc mapping of the class to an alternate selectable, for loading only. .. seealso:: :ref:`relationship_aliased_class` - the new pattern that removes the need for the :paramref:`_orm.Mapper.non_primary` flag. :param passive_deletes: Indicates DELETE behavior of foreign key columns when a joined-table inheritance entity is being deleted. Defaults to ``False`` for a base mapper; for an inheriting mapper, defaults to ``False`` unless the value is set to ``True`` on the superclass mapper. When ``True``, it is assumed that ON DELETE CASCADE is configured on the foreign key relationships that link this mapper's table to its superclass table, so that when the unit of work attempts to delete the entity, it need only emit a DELETE statement for the superclass table, and not this table. When ``False``, a DELETE statement is emitted for this mapper's table individually. If the primary key attributes local to this table are unloaded, then a SELECT must be emitted in order to validate these attributes; note that the primary key columns of a joined-table subclass are not part of the "primary key" of the object as a whole. Note that a value of ``True`` is **always** forced onto the subclass mappers; that is, it's not possible for a superclass to specify passive_deletes without this taking effect for all subclass mappers. .. seealso:: :ref:`passive_deletes` - description of similar feature as used with :func:`_orm.relationship` :paramref:`.mapper.passive_updates` - supporting ON UPDATE CASCADE for joined-table inheritance mappers :param passive_updates: Indicates UPDATE behavior of foreign key columns when a primary key column changes on a joined-table inheritance mapping. Defaults to ``True``. When True, it is assumed that ON UPDATE CASCADE is configured on the foreign key in the database, and that the database will handle propagation of an UPDATE from a source column to dependent columns on joined-table rows. When False, it is assumed that the database does not enforce referential integrity and will not be issuing its own CASCADE operation for an update. The unit of work process will emit an UPDATE statement for the dependent columns during a primary key change. .. seealso:: :ref:`passive_updates` - description of a similar feature as used with :func:`_orm.relationship` :paramref:`.mapper.passive_deletes` - supporting ON DELETE CASCADE for joined-table inheritance mappers :param polymorphic_load: Specifies "polymorphic loading" behavior for a subclass in an inheritance hierarchy (joined and single table inheritance only). Valid values are: * "'inline'" - specifies this class should be part of the "with_polymorphic" mappers, e.g. its columns will be included in a SELECT query against the base. * "'selectin'" - specifies that when instances of this class are loaded, an additional SELECT will be emitted to retrieve the columns specific to this subclass. The SELECT uses IN to fetch multiple subclasses at once. .. versionadded:: 1.2 .. seealso:: :ref:`with_polymorphic_mapper_config` :ref:`polymorphic_selectin` :param polymorphic_on: Specifies the column, attribute, or SQL expression used to determine the target class for an incoming row, when inheriting classes are present. May be specified as a string attribute name, or as a SQL expression such as a :class:`_schema.Column` or in a Declarative mapping a :func:`_orm.mapped_column` object. It is typically expected that the SQL expression corresponds to a column in the base-most mapped :class:`.Table`:: class Employee(Base): __tablename__ = "employee" id: Mapped[int] = mapped_column(primary_key=True) discriminator: Mapped[str] = mapped_column(String(50)) __mapper_args__ = { "polymorphic_on": discriminator, "polymorphic_identity": "employee", } It may also be specified as a SQL expression, as in this example where we use the :func:`.case` construct to provide a conditional approach:: class Employee(Base): __tablename__ = "employee" id: Mapped[int] = mapped_column(primary_key=True) discriminator: Mapped[str] = mapped_column(String(50)) __mapper_args__ = { "polymorphic_on": case( (discriminator == "EN", "engineer"), (discriminator == "MA", "manager"), else_="employee", ), "polymorphic_identity": "employee", } It may also refer to any attribute using its string name, which is of particular use when using annotated column configurations:: class Employee(Base): __tablename__ = "employee" id: Mapped[int] = mapped_column(primary_key=True) discriminator: Mapped[str] __mapper_args__ = { "polymorphic_on": "discriminator", "polymorphic_identity": "employee", } When setting ``polymorphic_on`` to reference an attribute or expression that's not present in the locally mapped :class:`_schema.Table`, yet the value of the discriminator should be persisted to the database, the value of the discriminator is not automatically set on new instances; this must be handled by the user, either through manual means or via event listeners. A typical approach to establishing such a listener looks like:: from sqlalchemy import event from sqlalchemy.orm import object_mapper @event.listens_for(Employee, "init", propagate=True) def set_identity(instance, *arg, **kw): mapper = object_mapper(instance) instance.discriminator = mapper.polymorphic_identity Where above, we assign the value of ``polymorphic_identity`` for the mapped class to the ``discriminator`` attribute, thus persisting the value to the ``discriminator`` column in the database. .. warning:: Currently, **only one discriminator column may be set**, typically on the base-most class in the hierarchy. "Cascading" polymorphic columns are not yet supported. .. seealso:: :ref:`inheritance_toplevel` :param polymorphic_identity: Specifies the value which identifies this particular class as returned by the column expression referred to by the :paramref:`_orm.Mapper.polymorphic_on` setting. As rows are received, the value corresponding to the :paramref:`_orm.Mapper.polymorphic_on` column expression is compared to this value, indicating which subclass should be used for the newly reconstructed object. .. seealso:: :ref:`inheritance_toplevel` :param properties: A dictionary mapping the string names of object attributes to :class:`.MapperProperty` instances, which define the persistence behavior of that attribute. Note that :class:`_schema.Column` objects present in the mapped :class:`_schema.Table` are automatically placed into ``ColumnProperty`` instances upon mapping, unless overridden. When using Declarative, this argument is passed automatically, based on all those :class:`.MapperProperty` instances declared in the declared class body. .. seealso:: :ref:`orm_mapping_properties` - in the :ref:`orm_mapping_classes_toplevel` :param primary_key: A list of :class:`_schema.Column` objects, or alternatively string names of attribute names which refer to :class:`_schema.Column`, which define the primary key to be used against this mapper's selectable unit. This is normally simply the primary key of the ``local_table``, but can be overridden here. .. versionchanged:: 2.0.2 :paramref:`_orm.Mapper.primary_key` arguments may be indicated as string attribute names as well. .. seealso:: :ref:`mapper_primary_key` - background and example use :param version_id_col: A :class:`_schema.Column` that will be used to keep a running version id of rows in the table. This is used to detect concurrent updates or the presence of stale data in a flush. The methodology is to detect if an UPDATE statement does not match the last known version id, a :class:`~sqlalchemy.orm.exc.StaleDataError` exception is thrown. By default, the column must be of :class:`.Integer` type, unless ``version_id_generator`` specifies an alternative version generator. .. seealso:: :ref:`mapper_version_counter` - discussion of version counting and rationale. :param version_id_generator: Define how new version ids should be generated. Defaults to ``None``, which indicates that a simple integer counting scheme be employed. To provide a custom versioning scheme, provide a callable function of the form:: def generate_version(version): return next_version Alternatively, server-side versioning functions such as triggers, or programmatic versioning schemes outside of the version id generator may be used, by specifying the value ``False``. Please see :ref:`server_side_version_counter` for a discussion of important points when using this option. .. seealso:: :ref:`custom_version_counter` :ref:`server_side_version_counter` :param with_polymorphic: A tuple in the form ``(<classes>, <selectable>)`` indicating the default style of "polymorphic" loading, that is, which tables are queried at once. <classes> is any single or list of mappers and/or classes indicating the inherited classes that should be loaded at once. The special value ``'*'`` may be used to indicate all descending classes should be loaded immediately. The second tuple argument <selectable> indicates a selectable that will be used to query for multiple classes. The :paramref:`_orm.Mapper.polymorphic_load` parameter may be preferable over the use of :paramref:`_orm.Mapper.with_polymorphic` in modern mappings to indicate a per-subclass technique of indicating polymorphic loading styles. .. seealso:: :ref:`with_polymorphic_mapper_config` """ self.class_ = util.assert_arg_type(class_, type, "class_") self._sort_key = "%s.%s" % ( self.class_.__module__, self.class_.__name__, ) self._primary_key_argument = util.to_list(primary_key) self.non_primary = non_primary self.always_refresh = always_refresh if isinstance(version_id_col, MapperProperty): self.version_id_prop = version_id_col self.version_id_col = None else: self.version_id_col = ( coercions.expect( roles.ColumnArgumentOrKeyRole, version_id_col, argname="version_id_col", ) if version_id_col is not None else None ) if version_id_generator is False: self.version_id_generator = False elif version_id_generator is None: self.version_id_generator = lambda x: (x or 0) + 1 else: self.version_id_generator = version_id_generator self.concrete = concrete self.single = False if inherits is not None: self.inherits = _parse_mapper_argument(inherits) else: self.inherits = None if local_table is not None: self.local_table = coercions.expect( roles.StrictFromClauseRole, local_table, disable_inspection=True, argname="local_table", ) elif self.inherits: # note this is a new flow as of 2.0 so that # .local_table need not be Optional self.local_table = self.inherits.local_table self.single = True else: raise sa_exc.ArgumentError( f"Mapper[{self.class_.__name__}(None)] has None for a " "primary table argument and does not specify 'inherits'" ) if inherit_condition is not None: self.inherit_condition = coercions.expect( roles.OnClauseRole, inherit_condition ) else: self.inherit_condition = None self.inherit_foreign_keys = inherit_foreign_keys self._init_properties = dict(properties) if properties else {} self._delete_orphans = [] self.batch = batch self.eager_defaults = eager_defaults self.column_prefix = column_prefix # interim - polymorphic_on is further refined in # _configure_polymorphic_setter self.polymorphic_on = ( coercions.expect( # type: ignore roles.ColumnArgumentOrKeyRole, polymorphic_on, argname="polymorphic_on", ) if polymorphic_on is not None else None ) self.polymorphic_abstract = polymorphic_abstract self._dependency_processors = [] self.validators = util.EMPTY_DICT self.passive_updates = passive_updates self.passive_deletes = passive_deletes self.legacy_is_orphan = legacy_is_orphan self._clause_adapter = None self._requires_row_aliasing = False self._inherits_equated_pairs = None self._memoized_values = {} self._compiled_cache_size = _compiled_cache_size self._reconstructor = None self.allow_partial_pks = allow_partial_pks if self.inherits and not self.concrete: self.confirm_deleted_rows = False else: self.confirm_deleted_rows = confirm_deleted_rows self._set_with_polymorphic(with_polymorphic) self.polymorphic_load = polymorphic_load # our 'polymorphic identity', a string name that when located in a # result set row indicates this Mapper should be used to construct # the object instance for that row. self.polymorphic_identity = polymorphic_identity # a dictionary of 'polymorphic identity' names, associating those # names with Mappers that will be used to construct object instances # upon a select operation. if _polymorphic_map is None: self.polymorphic_map = {} else: self.polymorphic_map = _polymorphic_map if include_properties is not None: self.include_properties = util.to_set(include_properties) else: self.include_properties = None if exclude_properties: self.exclude_properties = util.to_set(exclude_properties) else: self.exclude_properties = None # prevent this mapper from being constructed # while a configure_mappers() is occurring (and defer a # configure_mappers() until construction succeeds) with _CONFIGURE_MUTEX: cast("MapperEvents", self.dispatch._events)._new_mapper_instance( class_, self ) self._configure_inheritance() self._configure_class_instrumentation() self._configure_properties() self._configure_polymorphic_setter() self._configure_pks() self.registry._flag_new_mapper(self) self._log("constructed") self._expire_memoizations() self.dispatch.after_mapper_constructed(self, self.class_) def _prefer_eager_defaults(self, dialect, table): if self.eager_defaults == "auto": if not table.implicit_returning: return False return ( table in self._server_default_col_keys and dialect.insert_executemany_returning ) else: return self.eager_defaults def _gen_cache_key(self, anon_map, bindparams): return (self,) # ### BEGIN # ATTRIBUTE DECLARATIONS START HERE is_mapper = True """Part of the inspection API.""" represents_outer_join = False registry: _RegistryType @property def mapper(self) -> Mapper[_O]: """Part of the inspection API. Returns self. """ return self @property def entity(self): r"""Part of the inspection API. Returns self.class\_. """ return self.class_ class_: Type[_O] """The class to which this :class:`_orm.Mapper` is mapped.""" _identity_class: Type[_O] _delete_orphans: List[Tuple[str, Type[Any]]] _dependency_processors: List[DependencyProcessor] _memoized_values: Dict[Any, Callable[[], Any]] _inheriting_mappers: util.WeakSequence[Mapper[Any]] _all_tables: Set[TableClause] _polymorphic_attr_key: Optional[str] _pks_by_table: Dict[FromClause, OrderedSet[ColumnClause[Any]]] _cols_by_table: Dict[FromClause, OrderedSet[ColumnElement[Any]]] _props: util.OrderedDict[str, MapperProperty[Any]] _init_properties: Dict[str, MapperProperty[Any]] _columntoproperty: _ColumnMapping _set_polymorphic_identity: Optional[Callable[[InstanceState[_O]], None]] _validate_polymorphic_identity: Optional[ Callable[[Mapper[_O], InstanceState[_O], _InstanceDict], None] ] tables: Sequence[TableClause] """A sequence containing the collection of :class:`_schema.Table` or :class:`_schema.TableClause` objects which this :class:`_orm.Mapper` is aware of. If the mapper is mapped to a :class:`_expression.Join`, or an :class:`_expression.Alias` representing a :class:`_expression.Select`, the individual :class:`_schema.Table` objects that comprise the full construct will be represented here. This is a *read only* attribute determined during mapper construction. Behavior is undefined if directly modified. """ validators: util.immutabledict[str, Tuple[str, Dict[str, Any]]] """An immutable dictionary of attributes which have been decorated using the :func:`_orm.validates` decorator. The dictionary contains string attribute names as keys mapped to the actual validation method. """ always_refresh: bool allow_partial_pks: bool version_id_col: Optional[ColumnElement[Any]] with_polymorphic: Optional[ Tuple[ Union[Literal["*"], Sequence[Union[Mapper[Any], Type[Any]]]], Optional[FromClause], ] ] version_id_generator: Optional[Union[Literal[False], Callable[[Any], Any]]] local_table: FromClause """The immediate :class:`_expression.FromClause` to which this :class:`_orm.Mapper` refers. Typically is an instance of :class:`_schema.Table`, may be any :class:`.FromClause`. The "local" table is the selectable that the :class:`_orm.Mapper` is directly responsible for managing from an attribute access and flush perspective. For non-inheriting mappers, :attr:`.Mapper.local_table` will be the same as :attr:`.Mapper.persist_selectable`. For inheriting mappers, :attr:`.Mapper.local_table` refers to the specific portion of :attr:`.Mapper.persist_selectable` that includes the columns to which this :class:`.Mapper` is loading/persisting, such as a particular :class:`.Table` within a join. .. seealso:: :attr:`_orm.Mapper.persist_selectable`. :attr:`_orm.Mapper.selectable`. """ persist_selectable: FromClause """The :class:`_expression.FromClause` to which this :class:`_orm.Mapper` is mapped. Typically is an instance of :class:`_schema.Table`, may be any :class:`.FromClause`. The :attr:`_orm.Mapper.persist_selectable` is similar to :attr:`.Mapper.local_table`, but represents the :class:`.FromClause` that represents the inheriting class hierarchy overall in an inheritance scenario. :attr.`.Mapper.persist_selectable` is also separate from the :attr:`.Mapper.selectable` attribute, the latter of which may be an alternate subquery used for selecting columns. :attr.`.Mapper.persist_selectable` is oriented towards columns that will be written on a persist operation. .. seealso:: :attr:`_orm.Mapper.selectable`. :attr:`_orm.Mapper.local_table`. """ inherits: Optional[Mapper[Any]] """References the :class:`_orm.Mapper` which this :class:`_orm.Mapper` inherits from, if any. """ inherit_condition: Optional[ColumnElement[bool]] configured: bool = False """Represent ``True`` if this :class:`_orm.Mapper` has been configured. This is a *read only* attribute determined during mapper construction. Behavior is undefined if directly modified. .. seealso:: :func:`.configure_mappers`. """ concrete: bool """Represent ``True`` if this :class:`_orm.Mapper` is a concrete inheritance mapper. This is a *read only* attribute determined during mapper construction. Behavior is undefined if directly modified. """ primary_key: Tuple[Column[Any], ...] """An iterable containing the collection of :class:`_schema.Column` objects which comprise the 'primary key' of the mapped table, from the perspective of this :class:`_orm.Mapper`. This list is against the selectable in :attr:`_orm.Mapper.persist_selectable`. In the case of inheriting mappers, some columns may be managed by a superclass mapper. For example, in the case of a :class:`_expression.Join`, the primary key is determined by all of the primary key columns across all tables referenced by the :class:`_expression.Join`. The list is also not necessarily the same as the primary key column collection associated with the underlying tables; the :class:`_orm.Mapper` features a ``primary_key`` argument that can override what the :class:`_orm.Mapper` considers as primary key columns. This is a *read only* attribute determined during mapper construction. Behavior is undefined if directly modified. """ class_manager: ClassManager[_O] """The :class:`.ClassManager` which maintains event listeners and class-bound descriptors for this :class:`_orm.Mapper`. This is a *read only* attribute determined during mapper construction. Behavior is undefined if directly modified. """ single: bool """Represent ``True`` if this :class:`_orm.Mapper` is a single table inheritance mapper. :attr:`_orm.Mapper.local_table` will be ``None`` if this flag is set. This is a *read only* attribute determined during mapper construction. Behavior is undefined if directly modified. """ non_primary: bool """Represent ``True`` if this :class:`_orm.Mapper` is a "non-primary" mapper, e.g. a mapper that is used only to select rows but not for persistence management. This is a *read only* attribute determined during mapper construction. Behavior is undefined if directly modified. """ polymorphic_on: Optional[KeyedColumnElement[Any]] """The :class:`_schema.Column` or SQL expression specified as the ``polymorphic_on`` argument for this :class:`_orm.Mapper`, within an inheritance scenario. This attribute is normally a :class:`_schema.Column` instance but may also be an expression, such as one derived from :func:`.cast`. This is a *read only* attribute determined during mapper construction. Behavior is undefined if directly modified. """ polymorphic_map: Dict[Any, Mapper[Any]] """A mapping of "polymorphic identity" identifiers mapped to :class:`_orm.Mapper` instances, within an inheritance scenario. The identifiers can be of any type which is comparable to the type of column represented by :attr:`_orm.Mapper.polymorphic_on`. An inheritance chain of mappers will all reference the same polymorphic map object. The object is used to correlate incoming result rows to target mappers. This is a *read only* attribute determined during mapper construction. Behavior is undefined if directly modified. """ polymorphic_identity: Optional[Any] """Represent an identifier which is matched against the :attr:`_orm.Mapper.polymorphic_on` column during result row loading. Used only with inheritance, this object can be of any type which is comparable to the type of column represented by :attr:`_orm.Mapper.polymorphic_on`. This is a *read only* attribute determined during mapper construction. Behavior is undefined if directly modified. """ base_mapper: Mapper[Any] """The base-most :class:`_orm.Mapper` in an inheritance chain. In a non-inheriting scenario, this attribute will always be this :class:`_orm.Mapper`. In an inheritance scenario, it references the :class:`_orm.Mapper` which is parent to all other :class:`_orm.Mapper` objects in the inheritance chain. This is a *read only* attribute determined during mapper construction. Behavior is undefined if directly modified. """ columns: ReadOnlyColumnCollection[str, Column[Any]] """A collection of :class:`_schema.Column` or other scalar expression objects maintained by this :class:`_orm.Mapper`. The collection behaves the same as that of the ``c`` attribute on any :class:`_schema.Table` object, except that only those columns included in this mapping are present, and are keyed based on the attribute name defined in the mapping, not necessarily the ``key`` attribute of the :class:`_schema.Column` itself. Additionally, scalar expressions mapped by :func:`.column_property` are also present here. This is a *read only* attribute determined during mapper construction. Behavior is undefined if directly modified. """ c: ReadOnlyColumnCollection[str, Column[Any]] """A synonym for :attr:`_orm.Mapper.columns`.""" @util.non_memoized_property @util.deprecated("1.3", "Use .persist_selectable") def mapped_table(self): return self.persist_selectable @util.memoized_property def _path_registry(self) -> CachingEntityRegistry: return PathRegistry.per_mapper(self) def _configure_inheritance(self): """Configure settings related to inheriting and/or inherited mappers being present.""" # a set of all mappers which inherit from this one. self._inheriting_mappers = util.WeakSequence() if self.inherits: if not issubclass(self.class_, self.inherits.class_): raise sa_exc.ArgumentError( "Class '%s' does not inherit from '%s'" % (self.class_.__name__, self.inherits.class_.__name__) ) self.dispatch._update(self.inherits.dispatch) if self.non_primary != self.inherits.non_primary: np = not self.non_primary and "primary" or "non-primary" raise sa_exc.ArgumentError( "Inheritance of %s mapper for class '%s' is " "only allowed from a %s mapper" % (np, self.class_.__name__, np) ) if self.single: self.persist_selectable = self.inherits.persist_selectable elif self.local_table is not self.inherits.local_table: if self.concrete: self.persist_selectable = self.local_table for mapper in self.iterate_to_root(): if mapper.polymorphic_on is not None: mapper._requires_row_aliasing = True else: if self.inherit_condition is None: # figure out inherit condition from our table to the # immediate table of the inherited mapper, not its # full table which could pull in other stuff we don't # want (allows test/inheritance.InheritTest4 to pass) try: self.inherit_condition = sql_util.join_condition( self.inherits.local_table, self.local_table ) except sa_exc.NoForeignKeysError as nfe: assert self.inherits.local_table is not None assert self.local_table is not None raise sa_exc.NoForeignKeysError( "Can't determine the inherit condition " "between inherited table '%s' and " "inheriting " "table '%s'; tables have no " "foreign key relationships established. " "Please ensure the inheriting table has " "a foreign key relationship to the " "inherited " "table, or provide an " "'on clause' using " "the 'inherit_condition' mapper argument." % ( self.inherits.local_table.description, self.local_table.description, ) ) from nfe except sa_exc.AmbiguousForeignKeysError as afe: assert self.inherits.local_table is not None assert self.local_table is not None raise sa_exc.AmbiguousForeignKeysError( "Can't determine the inherit condition " "between inherited table '%s' and " "inheriting " "table '%s'; tables have more than one " "foreign key relationship established. " "Please specify the 'on clause' using " "the 'inherit_condition' mapper argument." % ( self.inherits.local_table.description, self.local_table.description, ) ) from afe assert self.inherits.persist_selectable is not None self.persist_selectable = sql.join( self.inherits.persist_selectable, self.local_table, self.inherit_condition, ) fks = util.to_set(self.inherit_foreign_keys) self._inherits_equated_pairs = sql_util.criterion_as_pairs( self.persist_selectable.onclause, consider_as_foreign_keys=fks, ) else: self.persist_selectable = self.local_table if self.polymorphic_identity is None: self._identity_class = self.class_ if ( not self.polymorphic_abstract and self.inherits.base_mapper.polymorphic_on is not None ): util.warn( f"{self} does not indicate a 'polymorphic_identity', " "yet is part of an inheritance hierarchy that has a " f"'polymorphic_on' column of " f"'{self.inherits.base_mapper.polymorphic_on}'. " "If this is an intermediary class that should not be " "instantiated, the class may either be left unmapped, " "or may include the 'polymorphic_abstract=True' " "parameter in its Mapper arguments. To leave the " "class unmapped when using Declarative, set the " "'__abstract__ = True' attribute on the class." ) elif self.concrete: self._identity_class = self.class_ else: self._identity_class = self.inherits._identity_class if self.version_id_col is None: self.version_id_col = self.inherits.version_id_col self.version_id_generator = self.inherits.version_id_generator elif ( self.inherits.version_id_col is not None and self.version_id_col is not self.inherits.version_id_col ): util.warn( "Inheriting version_id_col '%s' does not match inherited " "version_id_col '%s' and will not automatically populate " "the inherited versioning column. " "version_id_col should only be specified on " "the base-most mapper that includes versioning." % ( self.version_id_col.description, self.inherits.version_id_col.description, ) ) self.polymorphic_map = self.inherits.polymorphic_map self.batch = self.inherits.batch self.inherits._inheriting_mappers.append(self) self.base_mapper = self.inherits.base_mapper self.passive_updates = self.inherits.passive_updates self.passive_deletes = ( self.inherits.passive_deletes or self.passive_deletes ) self._all_tables = self.inherits._all_tables if self.polymorphic_identity is not None: if self.polymorphic_identity in self.polymorphic_map: util.warn( "Reassigning polymorphic association for identity %r " "from %r to %r: Check for duplicate use of %r as " "value for polymorphic_identity." % ( self.polymorphic_identity, self.polymorphic_map[self.polymorphic_identity], self, self.polymorphic_identity, ) ) self.polymorphic_map[self.polymorphic_identity] = self if self.polymorphic_load and self.concrete: raise sa_exc.ArgumentError( "polymorphic_load is not currently supported " "with concrete table inheritance" ) if self.polymorphic_load == "inline": self.inherits._add_with_polymorphic_subclass(self) elif self.polymorphic_load == "selectin": pass elif self.polymorphic_load is not None: raise sa_exc.ArgumentError( "unknown argument for polymorphic_load: %r" % self.polymorphic_load ) else: self._all_tables = set() self.base_mapper = self assert self.local_table is not None self.persist_selectable = self.local_table if self.polymorphic_identity is not None: self.polymorphic_map[self.polymorphic_identity] = self self._identity_class = self.class_ if self.persist_selectable is None: raise sa_exc.ArgumentError( "Mapper '%s' does not have a persist_selectable specified." % self ) def _set_with_polymorphic( self, with_polymorphic: Optional[_WithPolymorphicArg] ) -> None: if with_polymorphic == "*": self.with_polymorphic = ("*", None) elif isinstance(with_polymorphic, (tuple, list)): if isinstance(with_polymorphic[0], (str, tuple, list)): self.with_polymorphic = cast( """Tuple[ Union[ Literal["*"], Sequence[Union["Mapper[Any]", Type[Any]]], ], Optional["FromClause"], ]""", with_polymorphic, ) else: self.with_polymorphic = (with_polymorphic, None) elif with_polymorphic is not None: raise sa_exc.ArgumentError( f"Invalid setting for with_polymorphic: {with_polymorphic!r}" ) else: self.with_polymorphic = None if self.with_polymorphic and self.with_polymorphic[1] is not None: self.with_polymorphic = ( self.with_polymorphic[0], coercions.expect( roles.StrictFromClauseRole, self.with_polymorphic[1], allow_select=True, ), ) if self.configured: self._expire_memoizations() def _add_with_polymorphic_subclass(self, mapper): subcl = mapper.class_ if self.with_polymorphic is None: self._set_with_polymorphic((subcl,)) elif self.with_polymorphic[0] != "*": assert isinstance(self.with_polymorphic[0], tuple) self._set_with_polymorphic( (self.with_polymorphic[0] + (subcl,), self.with_polymorphic[1]) ) def _set_concrete_base(self, mapper): """Set the given :class:`_orm.Mapper` as the 'inherits' for this :class:`_orm.Mapper`, assuming this :class:`_orm.Mapper` is concrete and does not already have an inherits.""" assert self.concrete assert not self.inherits assert isinstance(mapper, Mapper) self.inherits = mapper self.inherits.polymorphic_map.update(self.polymorphic_map) self.polymorphic_map = self.inherits.polymorphic_map for mapper in self.iterate_to_root(): if mapper.polymorphic_on is not None: mapper._requires_row_aliasing = True self.batch = self.inherits.batch for mp in self.self_and_descendants: mp.base_mapper = self.inherits.base_mapper self.inherits._inheriting_mappers.append(self) self.passive_updates = self.inherits.passive_updates self._all_tables = self.inherits._all_tables for key, prop in mapper._props.items(): if key not in self._props and not self._should_exclude( key, key, local=False, column=None ): self._adapt_inherited_property(key, prop, False) def _set_polymorphic_on(self, polymorphic_on): self.polymorphic_on = polymorphic_on self._configure_polymorphic_setter(True) def _configure_class_instrumentation(self): """If this mapper is to be a primary mapper (i.e. the non_primary flag is not set), associate this Mapper with the given class and entity name. Subsequent calls to ``class_mapper()`` for the ``class_`` / ``entity`` name combination will return this mapper. Also decorate the `__init__` method on the mapped class to include optional auto-session attachment logic. """ # we expect that declarative has applied the class manager # already and set up a registry. if this is None, # this raises as of 2.0. manager = attributes.opt_manager_of_class(self.class_) if self.non_primary: if not manager or not manager.is_mapped: raise sa_exc.InvalidRequestError( "Class %s has no primary mapper configured. Configure " "a primary mapper first before setting up a non primary " "Mapper." % self.class_ ) self.class_manager = manager assert manager.registry is not None self.registry = manager.registry self._identity_class = manager.mapper._identity_class manager.registry._add_non_primary_mapper(self) return if manager is None or not manager.registry: raise sa_exc.InvalidRequestError( "The _mapper() function and Mapper() constructor may not be " "invoked directly outside of a declarative registry." " Please use the sqlalchemy.orm.registry.map_imperatively() " "function for a classical mapping." ) self.dispatch.instrument_class(self, self.class_) # this invokes the class_instrument event and sets up # the __init__ method. documented behavior is that this must # occur after the instrument_class event above. # yes two events with the same two words reversed and different APIs. # :( manager = instrumentation.register_class( self.class_, mapper=self, expired_attribute_loader=util.partial( loading.load_scalar_attributes, self ), # finalize flag means instrument the __init__ method # and call the class_instrument event finalize=True, ) self.class_manager = manager assert manager.registry is not None self.registry = manager.registry # The remaining members can be added by any mapper, # e_name None or not. if manager.mapper is None: return event.listen(manager, "init", _event_on_init, raw=True) for key, method in util.iterate_attributes(self.class_): if key == "__init__" and hasattr(method, "_sa_original_init"): method = method._sa_original_init if hasattr(method, "__func__"): method = method.__func__ if callable(method): if hasattr(method, "__sa_reconstructor__"): self._reconstructor = method event.listen(manager, "load", _event_on_load, raw=True) elif hasattr(method, "__sa_validators__"): validation_opts = method.__sa_validation_opts__ for name in method.__sa_validators__: if name in self.validators: raise sa_exc.InvalidRequestError( "A validation function for mapped " "attribute %r on mapper %s already exists." % (name, self) ) self.validators = self.validators.union( {name: (method, validation_opts)} ) def _set_dispose_flags(self) -> None: self.configured = True self._ready_for_configure = True self._dispose_called = True self.__dict__.pop("_configure_failed", None) def _str_arg_to_mapped_col(self, argname: str, key: str) -> Column[Any]: try: prop = self._props[key] except KeyError as err: raise sa_exc.ArgumentError( f"Can't determine {argname} column '{key}' - " "no attribute is mapped to this name." ) from err try: expr = prop.expression except AttributeError as ae: raise sa_exc.ArgumentError( f"Can't determine {argname} column '{key}'; " "property does not refer to a single mapped Column" ) from ae if not isinstance(expr, Column): raise sa_exc.ArgumentError( f"Can't determine {argname} column '{key}'; " "property does not refer to a single " "mapped Column" ) return expr def _configure_pks(self) -> None: self.tables = sql_util.find_tables(self.persist_selectable) self._all_tables.update(t for t in self.tables) self._pks_by_table = {} self._cols_by_table = {} all_cols = util.column_set( chain(*[col.proxy_set for col in self._columntoproperty]) ) pk_cols = util.column_set(c for c in all_cols if c.primary_key) # identify primary key columns which are also mapped by this mapper. for fc in set(self.tables).union([self.persist_selectable]): if fc.primary_key and pk_cols.issuperset(fc.primary_key): # ordering is important since it determines the ordering of # mapper.primary_key (and therefore query.get()) self._pks_by_table[fc] = util.ordered_column_set( # type: ignore # noqa: E501 fc.primary_key ).intersection( pk_cols ) self._cols_by_table[fc] = util.ordered_column_set(fc.c).intersection( # type: ignore # noqa: E501 all_cols ) if self._primary_key_argument: coerced_pk_arg = [ ( self._str_arg_to_mapped_col("primary_key", c) if isinstance(c, str) else c ) for c in ( coercions.expect( roles.DDLConstraintColumnRole, coerce_pk, argname="primary_key", ) for coerce_pk in self._primary_key_argument ) ] else: coerced_pk_arg = None # if explicit PK argument sent, add those columns to the # primary key mappings if coerced_pk_arg: for k in coerced_pk_arg: if k.table not in self._pks_by_table: self._pks_by_table[k.table] = util.OrderedSet() self._pks_by_table[k.table].add(k) # otherwise, see that we got a full PK for the mapped table elif ( self.persist_selectable not in self._pks_by_table or len(self._pks_by_table[self.persist_selectable]) == 0 ): raise sa_exc.ArgumentError( "Mapper %s could not assemble any primary " "key columns for mapped table '%s'" % (self, self.persist_selectable.description) ) elif self.local_table not in self._pks_by_table and isinstance( self.local_table, schema.Table ): util.warn( "Could not assemble any primary " "keys for locally mapped table '%s' - " "no rows will be persisted in this Table." % self.local_table.description ) if ( self.inherits and not self.concrete and not self._primary_key_argument ): # if inheriting, the "primary key" for this mapper is # that of the inheriting (unless concrete or explicit) self.primary_key = self.inherits.primary_key else: # determine primary key from argument or persist_selectable pks primary_key: Collection[ColumnElement[Any]] if coerced_pk_arg: primary_key = [ cc if cc is not None else c for cc, c in ( (self.persist_selectable.corresponding_column(c), c) for c in coerced_pk_arg ) ] else: # if heuristically determined PKs, reduce to the minimal set # of columns by eliminating FK->PK pairs for a multi-table # expression. May over-reduce for some kinds of UNIONs # / CTEs; use explicit PK argument for these special cases primary_key = sql_util.reduce_columns( self._pks_by_table[self.persist_selectable], ignore_nonexistent_tables=True, ) if len(primary_key) == 0: raise sa_exc.ArgumentError( "Mapper %s could not assemble any primary " "key columns for mapped table '%s'" % (self, self.persist_selectable.description) ) self.primary_key = tuple(primary_key) self._log("Identified primary key columns: %s", primary_key) # determine cols that aren't expressed within our tables; mark these # as "read only" properties which are refreshed upon INSERT/UPDATE self._readonly_props = { self._columntoproperty[col] for col in self._columntoproperty if self._columntoproperty[col] not in self._identity_key_props and ( not hasattr(col, "table") or col.table not in self._cols_by_table ) } def _configure_properties(self) -> None: self.columns = self.c = sql_base.ColumnCollection() # type: ignore # object attribute names mapped to MapperProperty objects self._props = util.OrderedDict() # table columns mapped to MapperProperty self._columntoproperty = _ColumnMapping(self) explicit_col_props_by_column: Dict[ KeyedColumnElement[Any], Tuple[str, ColumnProperty[Any]] ] = {} explicit_col_props_by_key: Dict[str, ColumnProperty[Any]] = {} # step 1: go through properties that were explicitly passed # in the properties dictionary. For Columns that are local, put them # aside in a separate collection we will reconcile with the Table # that's given. For other properties, set them up in _props now. if self._init_properties: for key, prop_arg in self._init_properties.items(): if not isinstance(prop_arg, MapperProperty): possible_col_prop = self._make_prop_from_column( key, prop_arg ) else: possible_col_prop = prop_arg # issue #8705. if the explicit property is actually a # Column that is local to the local Table, don't set it up # in ._props yet, integrate it into the order given within # the Table. _map_as_property_now = True if isinstance(possible_col_prop, properties.ColumnProperty): for given_col in possible_col_prop.columns: if self.local_table.c.contains_column(given_col): _map_as_property_now = False explicit_col_props_by_key[key] = possible_col_prop explicit_col_props_by_column[given_col] = ( key, possible_col_prop, ) if _map_as_property_now: self._configure_property( key, possible_col_prop, init=False, ) # step 2: pull properties from the inherited mapper. reconcile # columns with those which are explicit above. for properties that # are only in the inheriting mapper, set them up as local props if self.inherits: for key, inherited_prop in self.inherits._props.items(): if self._should_exclude(key, key, local=False, column=None): continue incoming_prop = explicit_col_props_by_key.get(key) if incoming_prop: new_prop = self._reconcile_prop_with_incoming_columns( key, inherited_prop, warn_only=False, incoming_prop=incoming_prop, ) explicit_col_props_by_key[key] = new_prop for inc_col in incoming_prop.columns: explicit_col_props_by_column[inc_col] = ( key, new_prop, ) elif key not in self._props: self._adapt_inherited_property(key, inherited_prop, False) # step 3. Iterate through all columns in the persist selectable. # this includes not only columns in the local table / fromclause, # but also those columns in the superclass table if we are joined # inh or single inh mapper. map these columns as well. additional # reconciliation against inherited columns occurs here also. for column in self.persist_selectable.columns: if column in explicit_col_props_by_column: # column was explicitly passed to properties; configure # it now in the order in which it corresponds to the # Table / selectable key, prop = explicit_col_props_by_column[column] self._configure_property(key, prop, init=False) continue elif column in self._columntoproperty: continue column_key = (self.column_prefix or "") + column.key if self._should_exclude( column.key, column_key, local=self.local_table.c.contains_column(column), column=column, ): continue # adjust the "key" used for this column to that # of the inheriting mapper for mapper in self.iterate_to_root(): if column in mapper._columntoproperty: column_key = mapper._columntoproperty[column].key self._configure_property( column_key, column, init=False, setparent=True, ) def _configure_polymorphic_setter(self, init=False): """Configure an attribute on the mapper representing the 'polymorphic_on' column, if applicable, and not already generated by _configure_properties (which is typical). Also create a setter function which will assign this attribute to the value of the 'polymorphic_identity' upon instance construction, also if applicable. This routine will run when an instance is created. """ setter = False polymorphic_key: Optional[str] = None if self.polymorphic_on is not None: setter = True if isinstance(self.polymorphic_on, str): # polymorphic_on specified as a string - link # it to mapped ColumnProperty try: self.polymorphic_on = self._props[self.polymorphic_on] except KeyError as err: raise sa_exc.ArgumentError( "Can't determine polymorphic_on " "value '%s' - no attribute is " "mapped to this name." % self.polymorphic_on ) from err if self.polymorphic_on in self._columntoproperty: # polymorphic_on is a column that is already mapped # to a ColumnProperty prop = self._columntoproperty[self.polymorphic_on] elif isinstance(self.polymorphic_on, MapperProperty): # polymorphic_on is directly a MapperProperty, # ensure it's a ColumnProperty if not isinstance( self.polymorphic_on, properties.ColumnProperty ): raise sa_exc.ArgumentError( "Only direct column-mapped " "property or SQL expression " "can be passed for polymorphic_on" ) prop = self.polymorphic_on else: # polymorphic_on is a Column or SQL expression and # doesn't appear to be mapped. this means it can be 1. # only present in the with_polymorphic selectable or # 2. a totally standalone SQL expression which we'd # hope is compatible with this mapper's persist_selectable col = self.persist_selectable.corresponding_column( self.polymorphic_on ) if col is None: # polymorphic_on doesn't derive from any # column/expression isn't present in the mapped # table. we will make a "hidden" ColumnProperty # for it. Just check that if it's directly a # schema.Column and we have with_polymorphic, it's # likely a user error if the schema.Column isn't # represented somehow in either persist_selectable or # with_polymorphic. Otherwise as of 0.7.4 we # just go with it and assume the user wants it # that way (i.e. a CASE statement) setter = False instrument = False col = self.polymorphic_on if isinstance(col, schema.Column) and ( self.with_polymorphic is None or self.with_polymorphic[1] is None or self.with_polymorphic[1].corresponding_column(col) is None ): raise sa_exc.InvalidRequestError( "Could not map polymorphic_on column " "'%s' to the mapped table - polymorphic " "loads will not function properly" % col.description ) else: # column/expression that polymorphic_on derives from # is present in our mapped table # and is probably mapped, but polymorphic_on itself # is not. This happens when # the polymorphic_on is only directly present in the # with_polymorphic selectable, as when use # polymorphic_union. # we'll make a separate ColumnProperty for it. instrument = True key = getattr(col, "key", None) if key: if self._should_exclude(key, key, False, col): raise sa_exc.InvalidRequestError( "Cannot exclude or override the " "discriminator column %r" % key ) else: self.polymorphic_on = col = col.label("_sa_polymorphic_on") key = col.key prop = properties.ColumnProperty(col, _instrument=instrument) self._configure_property(key, prop, init=init, setparent=True) # the actual polymorphic_on should be the first public-facing # column in the property self.polymorphic_on = prop.columns[0] polymorphic_key = prop.key else: # no polymorphic_on was set. # check inheriting mappers for one. for mapper in self.iterate_to_root(): # determine if polymorphic_on of the parent # should be propagated here. If the col # is present in our mapped table, or if our mapped # table is the same as the parent (i.e. single table # inheritance), we can use it if mapper.polymorphic_on is not None: if self.persist_selectable is mapper.persist_selectable: self.polymorphic_on = mapper.polymorphic_on else: self.polymorphic_on = ( self.persist_selectable ).corresponding_column(mapper.polymorphic_on) # we can use the parent mapper's _set_polymorphic_identity # directly; it ensures the polymorphic_identity of the # instance's mapper is used so is portable to subclasses. if self.polymorphic_on is not None: self._set_polymorphic_identity = ( mapper._set_polymorphic_identity ) self._polymorphic_attr_key = ( mapper._polymorphic_attr_key ) self._validate_polymorphic_identity = ( mapper._validate_polymorphic_identity ) else: self._set_polymorphic_identity = None self._polymorphic_attr_key = None return if self.polymorphic_abstract and self.polymorphic_on is None: raise sa_exc.InvalidRequestError( "The Mapper.polymorphic_abstract parameter may only be used " "on a mapper hierarchy which includes the " "Mapper.polymorphic_on parameter at the base of the hierarchy." ) if setter: def _set_polymorphic_identity(state): dict_ = state.dict # TODO: what happens if polymorphic_on column attribute name # does not match .key? polymorphic_identity = ( state.manager.mapper.polymorphic_identity ) if ( polymorphic_identity is None and state.manager.mapper.polymorphic_abstract ): raise sa_exc.InvalidRequestError( f"Can't instantiate class for {state.manager.mapper}; " "mapper is marked polymorphic_abstract=True" ) state.get_impl(polymorphic_key).set( state, dict_, polymorphic_identity, None, ) self._polymorphic_attr_key = polymorphic_key def _validate_polymorphic_identity(mapper, state, dict_): if ( polymorphic_key in dict_ and dict_[polymorphic_key] not in mapper._acceptable_polymorphic_identities ): util.warn_limited( "Flushing object %s with " "incompatible polymorphic identity %r; the " "object may not refresh and/or load correctly", (state_str(state), dict_[polymorphic_key]), ) self._set_polymorphic_identity = _set_polymorphic_identity self._validate_polymorphic_identity = ( _validate_polymorphic_identity ) else: self._polymorphic_attr_key = None self._set_polymorphic_identity = None _validate_polymorphic_identity = None @HasMemoized.memoized_attribute def _version_id_prop(self): if self.version_id_col is not None: return self._columntoproperty[self.version_id_col] else: return None @HasMemoized.memoized_attribute def _acceptable_polymorphic_identities(self): identities = set() stack = deque([self]) while stack: item = stack.popleft() if item.persist_selectable is self.persist_selectable: identities.add(item.polymorphic_identity) stack.extend(item._inheriting_mappers) return identities @HasMemoized.memoized_attribute def _prop_set(self): return frozenset(self._props.values()) @util.preload_module("sqlalchemy.orm.descriptor_props") def _adapt_inherited_property(self, key, prop, init): descriptor_props = util.preloaded.orm_descriptor_props if not self.concrete: self._configure_property(key, prop, init=False, setparent=False) elif key not in self._props: # determine if the class implements this attribute; if not, # or if it is implemented by the attribute that is handling the # given superclass-mapped property, then we need to report that we # can't use this at the instance level since we are a concrete # mapper and we don't map this. don't trip user-defined # descriptors that might have side effects when invoked. implementing_attribute = self.class_manager._get_class_attr_mro( key, prop ) if implementing_attribute is prop or ( isinstance( implementing_attribute, attributes.InstrumentedAttribute ) and implementing_attribute._parententity is prop.parent ): self._configure_property( key, descriptor_props.ConcreteInheritedProperty(), init=init, setparent=True, ) @util.preload_module("sqlalchemy.orm.descriptor_props") def _configure_property( self, key: str, prop_arg: Union[KeyedColumnElement[Any], MapperProperty[Any]], *, init: bool = True, setparent: bool = True, warn_for_existing: bool = False, ) -> MapperProperty[Any]: descriptor_props = util.preloaded.orm_descriptor_props self._log( "_configure_property(%s, %s)", key, prop_arg.__class__.__name__ ) if not isinstance(prop_arg, MapperProperty): prop: MapperProperty[Any] = self._property_from_column( key, prop_arg ) else: prop = prop_arg if isinstance(prop, properties.ColumnProperty): col = self.persist_selectable.corresponding_column(prop.columns[0]) # if the column is not present in the mapped table, # test if a column has been added after the fact to the # parent table (or their parent, etc.) [ticket:1570] if col is None and self.inherits: path = [self] for m in self.inherits.iterate_to_root(): col = m.local_table.corresponding_column(prop.columns[0]) if col is not None: for m2 in path: m2.persist_selectable._refresh_for_new_column(col) col = self.persist_selectable.corresponding_column( prop.columns[0] ) break path.append(m) # subquery expression, column not present in the mapped # selectable. if col is None: col = prop.columns[0] # column is coming in after _readonly_props was # initialized; check for 'readonly' if hasattr(self, "_readonly_props") and ( not hasattr(col, "table") or col.table not in self._cols_by_table ): self._readonly_props.add(prop) else: # if column is coming in after _cols_by_table was # initialized, ensure the col is in the right set if ( hasattr(self, "_cols_by_table") and col.table in self._cols_by_table and col not in self._cols_by_table[col.table] ): self._cols_by_table[col.table].add(col) # if this properties.ColumnProperty represents the "polymorphic # discriminator" column, mark it. We'll need this when rendering # columns in SELECT statements. if not hasattr(prop, "_is_polymorphic_discriminator"): prop._is_polymorphic_discriminator = ( col is self.polymorphic_on or prop.columns[0] is self.polymorphic_on ) if isinstance(col, expression.Label): # new in 1.4, get column property against expressions # to be addressable in subqueries col.key = col._tq_key_label = key self.columns.add(col, key) for col in prop.columns: for proxy_col in col.proxy_set: self._columntoproperty[proxy_col] = prop if getattr(prop, "key", key) != key: util.warn( f"ORM mapped property {self.class_.__name__}.{prop.key} being " "assigned to attribute " f"{key!r} is already associated with " f"attribute {prop.key!r}. The attribute will be de-associated " f"from {prop.key!r}." ) prop.key = key if setparent: prop.set_parent(self, init) if key in self._props and getattr( self._props[key], "_mapped_by_synonym", False ): syn = self._props[key]._mapped_by_synonym raise sa_exc.ArgumentError( "Can't call map_column=True for synonym %r=%r, " "a ColumnProperty already exists keyed to the name " "%r for column %r" % (syn, key, key, syn) ) # replacement cases # case one: prop is replacing a prop that we have mapped. this is # independent of whatever might be in the actual class dictionary if ( key in self._props and not isinstance( self._props[key], descriptor_props.ConcreteInheritedProperty ) and not isinstance(prop, descriptor_props.SynonymProperty) ): if warn_for_existing: util.warn_deprecated( f"User-placed attribute {self.class_.__name__}.{key} on " f"{self} is replacing an existing ORM-mapped attribute. " "Behavior is not fully defined in this case. This " "use is deprecated and will raise an error in a future " "release", "2.0", ) oldprop = self._props[key] self._path_registry.pop(oldprop, None) # case two: prop is replacing an attribute on the class of some kind. # we have to be more careful here since it's normal when using # Declarative that all the "declared attributes" on the class # get replaced. elif ( warn_for_existing and self.class_.__dict__.get(key, None) is not None and not isinstance(prop, descriptor_props.SynonymProperty) and not isinstance( self._props.get(key, None), descriptor_props.ConcreteInheritedProperty, ) ): util.warn_deprecated( f"User-placed attribute {self.class_.__name__}.{key} on " f"{self} is replacing an existing class-bound " "attribute of the same name. " "Behavior is not fully defined in this case. This " "use is deprecated and will raise an error in a future " "release", "2.0", ) self._props[key] = prop if not self.non_primary: prop.instrument_class(self) for mapper in self._inheriting_mappers: mapper._adapt_inherited_property(key, prop, init) if init: prop.init() prop.post_instrument_class(self) if self.configured: self._expire_memoizations() return prop def _make_prop_from_column( self, key: str, column: Union[ Sequence[KeyedColumnElement[Any]], KeyedColumnElement[Any] ], ) -> ColumnProperty[Any]: columns = util.to_list(column) mapped_column = [] for c in columns: mc = self.persist_selectable.corresponding_column(c) if mc is None: mc = self.local_table.corresponding_column(c) if mc is not None: # if the column is in the local table but not the # mapped table, this corresponds to adding a # column after the fact to the local table. # [ticket:1523] self.persist_selectable._refresh_for_new_column(mc) mc = self.persist_selectable.corresponding_column(c) if mc is None: raise sa_exc.ArgumentError( "When configuring property '%s' on %s, " "column '%s' is not represented in the mapper's " "table. Use the `column_property()` function to " "force this column to be mapped as a read-only " "attribute." % (key, self, c) ) mapped_column.append(mc) return properties.ColumnProperty(*mapped_column) def _reconcile_prop_with_incoming_columns( self, key: str, existing_prop: MapperProperty[Any], warn_only: bool, incoming_prop: Optional[ColumnProperty[Any]] = None, single_column: Optional[KeyedColumnElement[Any]] = None, ) -> ColumnProperty[Any]: if incoming_prop and ( self.concrete or not isinstance(existing_prop, properties.ColumnProperty) ): return incoming_prop existing_column = existing_prop.columns[0] if incoming_prop and existing_column in incoming_prop.columns: return incoming_prop if incoming_prop is None: assert single_column is not None incoming_column = single_column equated_pair_key = (existing_prop.columns[0], incoming_column) else: assert single_column is None incoming_column = incoming_prop.columns[0] equated_pair_key = (incoming_column, existing_prop.columns[0]) if ( ( not self._inherits_equated_pairs or (equated_pair_key not in self._inherits_equated_pairs) ) and not existing_column.shares_lineage(incoming_column) and existing_column is not self.version_id_col and incoming_column is not self.version_id_col ): msg = ( "Implicitly combining column %s with column " "%s under attribute '%s'. Please configure one " "or more attributes for these same-named columns " "explicitly." % ( existing_prop.columns[-1], incoming_column, key, ) ) if warn_only: util.warn(msg) else: raise sa_exc.InvalidRequestError(msg) # existing properties.ColumnProperty from an inheriting # mapper. make a copy and append our column to it # breakpoint() new_prop = existing_prop.copy() new_prop.columns.insert(0, incoming_column) self._log( "inserting column to existing list " "in properties.ColumnProperty %s", key, ) return new_prop # type: ignore @util.preload_module("sqlalchemy.orm.descriptor_props") def _property_from_column( self, key: str, column: KeyedColumnElement[Any], ) -> ColumnProperty[Any]: """generate/update a :class:`.ColumnProperty` given a :class:`_schema.Column` or other SQL expression object.""" descriptor_props = util.preloaded.orm_descriptor_props prop = self._props.get(key) if isinstance(prop, properties.ColumnProperty): return self._reconcile_prop_with_incoming_columns( key, prop, single_column=column, warn_only=prop.parent is not self, ) elif prop is None or isinstance( prop, descriptor_props.ConcreteInheritedProperty ): return self._make_prop_from_column(key, column) else: raise sa_exc.ArgumentError( "WARNING: when configuring property '%s' on %s, " "column '%s' conflicts with property '%r'. " "To resolve this, map the column to the class under a " "different name in the 'properties' dictionary. Or, " "to remove all awareness of the column entirely " "(including its availability as a foreign key), " "use the 'include_properties' or 'exclude_properties' " "mapper arguments to control specifically which table " "columns get mapped." % (key, self, column.key, prop) ) @util.langhelpers.tag_method_for_warnings( "This warning originated from the `configure_mappers()` process, " "which was invoked automatically in response to a user-initiated " "operation.", sa_exc.SAWarning, ) def _check_configure(self) -> None: if self.registry._new_mappers: _configure_registries({self.registry}, cascade=True) def _post_configure_properties(self) -> None: """Call the ``init()`` method on all ``MapperProperties`` attached to this mapper. This is a deferred configuration step which is intended to execute once all mappers have been constructed. """ self._log("_post_configure_properties() started") l = [(key, prop) for key, prop in self._props.items()] for key, prop in l: self._log("initialize prop %s", key) if prop.parent is self and not prop._configure_started: prop.init() if prop._configure_finished: prop.post_instrument_class(self) self._log("_post_configure_properties() complete") self.configured = True def add_properties(self, dict_of_properties): """Add the given dictionary of properties to this mapper, using `add_property`. """ for key, value in dict_of_properties.items(): self.add_property(key, value) def add_property( self, key: str, prop: Union[Column[Any], MapperProperty[Any]] ) -> None: """Add an individual MapperProperty to this mapper. If the mapper has not been configured yet, just adds the property to the initial properties dictionary sent to the constructor. If this Mapper has already been configured, then the given MapperProperty is configured immediately. """ prop = self._configure_property( key, prop, init=self.configured, warn_for_existing=True ) assert isinstance(prop, MapperProperty) self._init_properties[key] = prop def _expire_memoizations(self) -> None: for mapper in self.iterate_to_root(): mapper._reset_memoizations() @property def _log_desc(self) -> str: return ( "(" + self.class_.__name__ + "|" + ( self.local_table is not None and self.local_table.description or str(self.local_table) ) + (self.non_primary and "|non-primary" or "") + ")" ) def _log(self, msg: str, *args: Any) -> None: self.logger.info("%s " + msg, *((self._log_desc,) + args)) def _log_debug(self, msg: str, *args: Any) -> None: self.logger.debug("%s " + msg, *((self._log_desc,) + args)) def __repr__(self) -> str: return "<Mapper at 0x%x; %s>" % (id(self), self.class_.__name__) def __str__(self) -> str: return "Mapper[%s%s(%s)]" % ( self.class_.__name__, self.non_primary and " (non-primary)" or "", ( self.local_table.description if self.local_table is not None else self.persist_selectable.description ), ) def _is_orphan(self, state: InstanceState[_O]) -> bool: orphan_possible = False for mapper in self.iterate_to_root(): for key, cls in mapper._delete_orphans: orphan_possible = True has_parent = attributes.manager_of_class(cls).has_parent( state, key, optimistic=state.has_identity ) if self.legacy_is_orphan and has_parent: return False elif not self.legacy_is_orphan and not has_parent: return True if self.legacy_is_orphan: return orphan_possible else: return False def has_property(self, key: str) -> bool: return key in self._props def get_property( self, key: str, _configure_mappers: bool = False ) -> MapperProperty[Any]: """return a MapperProperty associated with the given key.""" if _configure_mappers: self._check_configure() try: return self._props[key] except KeyError as err: raise sa_exc.InvalidRequestError( f"Mapper '{self}' has no property '{key}'. If this property " "was indicated from other mappers or configure events, ensure " "registry.configure() has been called." ) from err def get_property_by_column( self, column: ColumnElement[_T] ) -> MapperProperty[_T]: """Given a :class:`_schema.Column` object, return the :class:`.MapperProperty` which maps this column.""" return self._columntoproperty[column] @property def iterate_properties(self): """return an iterator of all MapperProperty objects.""" return iter(self._props.values()) def _mappers_from_spec( self, spec: Any, selectable: Optional[FromClause] ) -> Sequence[Mapper[Any]]: """given a with_polymorphic() argument, return the set of mappers it represents. Trims the list of mappers to just those represented within the given selectable, if present. This helps some more legacy-ish mappings. """ if spec == "*": mappers = list(self.self_and_descendants) elif spec: mapper_set = set() for m in util.to_list(spec): m = _class_to_mapper(m) if not m.isa(self): raise sa_exc.InvalidRequestError( "%r does not inherit from %r" % (m, self) ) if selectable is None: mapper_set.update(m.iterate_to_root()) else: mapper_set.add(m) mappers = [m for m in self.self_and_descendants if m in mapper_set] else: mappers = [] if selectable is not None: tables = set( sql_util.find_tables(selectable, include_aliases=True) ) mappers = [m for m in mappers if m.local_table in tables] return mappers def _selectable_from_mappers( self, mappers: Iterable[Mapper[Any]], innerjoin: bool ) -> FromClause: """given a list of mappers (assumed to be within this mapper's inheritance hierarchy), construct an outerjoin amongst those mapper's mapped tables. """ from_obj = self.persist_selectable for m in mappers: if m is self: continue if m.concrete: raise sa_exc.InvalidRequestError( "'with_polymorphic()' requires 'selectable' argument " "when concrete-inheriting mappers are used." ) elif not m.single: if innerjoin: from_obj = from_obj.join( m.local_table, m.inherit_condition ) else: from_obj = from_obj.outerjoin( m.local_table, m.inherit_condition ) return from_obj @HasMemoized.memoized_attribute def _version_id_has_server_side_value(self) -> bool: vid_col = self.version_id_col if vid_col is None: return False elif not isinstance(vid_col, Column): return True else: return vid_col.server_default is not None or ( vid_col.default is not None and ( not vid_col.default.is_scalar and not vid_col.default.is_callable ) ) @HasMemoized.memoized_attribute def _single_table_criterion(self): if self.single and self.inherits and self.polymorphic_on is not None: return self.polymorphic_on._annotate( {"parententity": self, "parentmapper": self} ).in_( [ m.polymorphic_identity for m in self.self_and_descendants if not m.polymorphic_abstract ] ) else: return None @HasMemoized.memoized_attribute def _has_aliased_polymorphic_fromclause(self): """return True if with_polymorphic[1] is an aliased fromclause, like a subquery. As of #8168, polymorphic adaption with ORMAdapter is used only if this is present. """ return self.with_polymorphic and isinstance( self.with_polymorphic[1], expression.AliasedReturnsRows, ) @HasMemoized.memoized_attribute def _should_select_with_poly_adapter(self): """determine if _MapperEntity or _ORMColumnEntity will need to use polymorphic adaption when setting up a SELECT as well as fetching rows for mapped classes and subclasses against this Mapper. moved here from context.py for #8456 to generalize the ruleset for this condition. """ # this has been simplified as of #8456. # rule is: if we have a with_polymorphic or a concrete-style # polymorphic selectable, *or* if the base mapper has either of those, # we turn on the adaption thing. if not, we do *no* adaption. # # (UPDATE for #8168: the above comment was not accurate, as we were # still saying "do polymorphic" if we were using an auto-generated # flattened JOIN for with_polymorphic.) # # this splits the behavior among the "regular" joined inheritance # and single inheritance mappers, vs. the "weird / difficult" # concrete and joined inh mappings that use a with_polymorphic of # some kind or polymorphic_union. # # note we have some tests in test_polymorphic_rel that query against # a subclass, then refer to the superclass that has a with_polymorphic # on it (such as test_join_from_polymorphic_explicit_aliased_three). # these tests actually adapt the polymorphic selectable (like, the # UNION or the SELECT subquery with JOIN in it) to be just the simple # subclass table. Hence even if we are a "plain" inheriting mapper # but our base has a wpoly on it, we turn on adaption. This is a # legacy case we should probably disable. # # # UPDATE: simplified way more as of #8168. polymorphic adaption # is turned off even if with_polymorphic is set, as long as there # is no user-defined aliased selectable / subquery configured. # this scales back the use of polymorphic adaption in practice # to basically no cases except for concrete inheritance with a # polymorphic base class. # return ( self._has_aliased_polymorphic_fromclause or self._requires_row_aliasing or (self.base_mapper._has_aliased_polymorphic_fromclause) or self.base_mapper._requires_row_aliasing ) @HasMemoized.memoized_attribute def _with_polymorphic_mappers(self) -> Sequence[Mapper[Any]]: self._check_configure() if not self.with_polymorphic: return [] return self._mappers_from_spec(*self.with_polymorphic) @HasMemoized.memoized_attribute def _post_inspect(self): """This hook is invoked by attribute inspection. E.g. when Query calls: coercions.expect(roles.ColumnsClauseRole, ent, keep_inspect=True) This allows the inspection process run a configure mappers hook. """ self._check_configure() @HasMemoized_ro_memoized_attribute def _with_polymorphic_selectable(self) -> FromClause: if not self.with_polymorphic: return self.persist_selectable spec, selectable = self.with_polymorphic if selectable is not None: return selectable else: return self._selectable_from_mappers( self._mappers_from_spec(spec, selectable), False ) with_polymorphic_mappers = _with_polymorphic_mappers """The list of :class:`_orm.Mapper` objects included in the default "polymorphic" query. """ @HasMemoized_ro_memoized_attribute def _insert_cols_evaluating_none(self): return { table: frozenset( col for col in columns if col.type.should_evaluate_none ) for table, columns in self._cols_by_table.items() } @HasMemoized.memoized_attribute def _insert_cols_as_none(self): return { table: frozenset( col.key for col in columns if not col.primary_key and not col.server_default and not col.default and not col.type.should_evaluate_none ) for table, columns in self._cols_by_table.items() } @HasMemoized.memoized_attribute def _propkey_to_col(self): return { table: {self._columntoproperty[col].key: col for col in columns} for table, columns in self._cols_by_table.items() } @HasMemoized.memoized_attribute def _pk_keys_by_table(self): return { table: frozenset([col.key for col in pks]) for table, pks in self._pks_by_table.items() } @HasMemoized.memoized_attribute def _pk_attr_keys_by_table(self): return { table: frozenset([self._columntoproperty[col].key for col in pks]) for table, pks in self._pks_by_table.items() } @HasMemoized.memoized_attribute def _server_default_cols( self, ) -> Mapping[FromClause, FrozenSet[Column[Any]]]: return { table: frozenset( [ col for col in cast("Iterable[Column[Any]]", columns) if col.server_default is not None or ( col.default is not None and col.default.is_clause_element ) ] ) for table, columns in self._cols_by_table.items() } @HasMemoized.memoized_attribute def _server_onupdate_default_cols( self, ) -> Mapping[FromClause, FrozenSet[Column[Any]]]: return { table: frozenset( [ col for col in cast("Iterable[Column[Any]]", columns) if col.server_onupdate is not None or ( col.onupdate is not None and col.onupdate.is_clause_element ) ] ) for table, columns in self._cols_by_table.items() } @HasMemoized.memoized_attribute def _server_default_col_keys(self) -> Mapping[FromClause, FrozenSet[str]]: return { table: frozenset(col.key for col in cols if col.key is not None) for table, cols in self._server_default_cols.items() } @HasMemoized.memoized_attribute def _server_onupdate_default_col_keys( self, ) -> Mapping[FromClause, FrozenSet[str]]: return { table: frozenset(col.key for col in cols if col.key is not None) for table, cols in self._server_onupdate_default_cols.items() } @HasMemoized.memoized_attribute def _server_default_plus_onupdate_propkeys(self) -> Set[str]: result: Set[str] = set() col_to_property = self._columntoproperty for table, columns in self._server_default_cols.items(): result.update( col_to_property[col].key for col in columns.intersection(col_to_property) ) for table, columns in self._server_onupdate_default_cols.items(): result.update( col_to_property[col].key for col in columns.intersection(col_to_property) ) return result @HasMemoized.memoized_instancemethod def __clause_element__(self): annotations: Dict[str, Any] = { "entity_namespace": self, "parententity": self, "parentmapper": self, } if self.persist_selectable is not self.local_table: # joined table inheritance, with polymorphic selectable, # etc. annotations["dml_table"] = self.local_table._annotate( { "entity_namespace": self, "parententity": self, "parentmapper": self, } )._set_propagate_attrs( {"compile_state_plugin": "orm", "plugin_subject": self} ) return self.selectable._annotate(annotations)._set_propagate_attrs( {"compile_state_plugin": "orm", "plugin_subject": self} ) @util.memoized_property def select_identity_token(self): return ( expression.null() ._annotate( { "entity_namespace": self, "parententity": self, "parentmapper": self, "identity_token": True, } ) ._set_propagate_attrs( {"compile_state_plugin": "orm", "plugin_subject": self} ) ) @property def selectable(self) -> FromClause: """The :class:`_schema.FromClause` construct this :class:`_orm.Mapper` selects from by default. Normally, this is equivalent to :attr:`.persist_selectable`, unless the ``with_polymorphic`` feature is in use, in which case the full "polymorphic" selectable is returned. """ return self._with_polymorphic_selectable def _with_polymorphic_args( self, spec: Any = None, selectable: Union[Literal[False, None], FromClause] = False, innerjoin: bool = False, ) -> Tuple[Sequence[Mapper[Any]], FromClause]: if selectable not in (None, False): selectable = coercions.expect( roles.StrictFromClauseRole, selectable, allow_select=True ) if self.with_polymorphic: if not spec: spec = self.with_polymorphic[0] if selectable is False: selectable = self.with_polymorphic[1] elif selectable is False: selectable = None mappers = self._mappers_from_spec(spec, selectable) if selectable is not None: return mappers, selectable else: return mappers, self._selectable_from_mappers(mappers, innerjoin) @HasMemoized.memoized_attribute def _polymorphic_properties(self): return list( self._iterate_polymorphic_properties( self._with_polymorphic_mappers ) ) @property def _all_column_expressions(self): poly_properties = self._polymorphic_properties adapter = self._polymorphic_adapter return [ adapter.columns[c] if adapter else c for prop in poly_properties if isinstance(prop, properties.ColumnProperty) and prop._renders_in_subqueries for c in prop.columns ] def _columns_plus_keys(self, polymorphic_mappers=()): if polymorphic_mappers: poly_properties = self._iterate_polymorphic_properties( polymorphic_mappers ) else: poly_properties = self._polymorphic_properties return [ (prop.key, prop.columns[0]) for prop in poly_properties if isinstance(prop, properties.ColumnProperty) ] @HasMemoized.memoized_attribute def _polymorphic_adapter(self) -> Optional[orm_util.ORMAdapter]: if self._has_aliased_polymorphic_fromclause: return orm_util.ORMAdapter( orm_util._TraceAdaptRole.MAPPER_POLYMORPHIC_ADAPTER, self, selectable=self.selectable, equivalents=self._equivalent_columns, limit_on_entity=False, ) else: return None def _iterate_polymorphic_properties(self, mappers=None): """Return an iterator of MapperProperty objects which will render into a SELECT.""" if mappers is None: mappers = self._with_polymorphic_mappers if not mappers: for c in self.iterate_properties: yield c else: # in the polymorphic case, filter out discriminator columns # from other mappers, as these are sometimes dependent on that # mapper's polymorphic selectable (which we don't want rendered) for c in util.unique_list( chain( *[ list(mapper.iterate_properties) for mapper in [self] + mappers ] ) ): if getattr(c, "_is_polymorphic_discriminator", False) and ( self.polymorphic_on is None or c.columns[0] is not self.polymorphic_on ): continue yield c @HasMemoized.memoized_attribute def attrs(self) -> util.ReadOnlyProperties[MapperProperty[Any]]: """A namespace of all :class:`.MapperProperty` objects associated this mapper. This is an object that provides each property based on its key name. For instance, the mapper for a ``User`` class which has ``User.name`` attribute would provide ``mapper.attrs.name``, which would be the :class:`.ColumnProperty` representing the ``name`` column. The namespace object can also be iterated, which would yield each :class:`.MapperProperty`. :class:`_orm.Mapper` has several pre-filtered views of this attribute which limit the types of properties returned, including :attr:`.synonyms`, :attr:`.column_attrs`, :attr:`.relationships`, and :attr:`.composites`. .. warning:: The :attr:`_orm.Mapper.attrs` accessor namespace is an instance of :class:`.OrderedProperties`. This is a dictionary-like object which includes a small number of named methods such as :meth:`.OrderedProperties.items` and :meth:`.OrderedProperties.values`. When accessing attributes dynamically, favor using the dict-access scheme, e.g. ``mapper.attrs[somename]`` over ``getattr(mapper.attrs, somename)`` to avoid name collisions. .. seealso:: :attr:`_orm.Mapper.all_orm_descriptors` """ self._check_configure() return util.ReadOnlyProperties(self._props) @HasMemoized.memoized_attribute def all_orm_descriptors(self) -> util.ReadOnlyProperties[InspectionAttr]: """A namespace of all :class:`.InspectionAttr` attributes associated with the mapped class. These attributes are in all cases Python :term:`descriptors` associated with the mapped class or its superclasses. This namespace includes attributes that are mapped to the class as well as attributes declared by extension modules. It includes any Python descriptor type that inherits from :class:`.InspectionAttr`. This includes :class:`.QueryableAttribute`, as well as extension types such as :class:`.hybrid_property`, :class:`.hybrid_method` and :class:`.AssociationProxy`. To distinguish between mapped attributes and extension attributes, the attribute :attr:`.InspectionAttr.extension_type` will refer to a constant that distinguishes between different extension types. The sorting of the attributes is based on the following rules: 1. Iterate through the class and its superclasses in order from subclass to superclass (i.e. iterate through ``cls.__mro__``) 2. For each class, yield the attributes in the order in which they appear in ``__dict__``, with the exception of those in step 3 below. In Python 3.6 and above this ordering will be the same as that of the class' construction, with the exception of attributes that were added after the fact by the application or the mapper. 3. If a certain attribute key is also in the superclass ``__dict__``, then it's included in the iteration for that class, and not the class in which it first appeared. The above process produces an ordering that is deterministic in terms of the order in which attributes were assigned to the class. .. versionchanged:: 1.3.19 ensured deterministic ordering for :meth:`_orm.Mapper.all_orm_descriptors`. When dealing with a :class:`.QueryableAttribute`, the :attr:`.QueryableAttribute.property` attribute refers to the :class:`.MapperProperty` property, which is what you get when referring to the collection of mapped properties via :attr:`_orm.Mapper.attrs`. .. warning:: The :attr:`_orm.Mapper.all_orm_descriptors` accessor namespace is an instance of :class:`.OrderedProperties`. This is a dictionary-like object which includes a small number of named methods such as :meth:`.OrderedProperties.items` and :meth:`.OrderedProperties.values`. When accessing attributes dynamically, favor using the dict-access scheme, e.g. ``mapper.all_orm_descriptors[somename]`` over ``getattr(mapper.all_orm_descriptors, somename)`` to avoid name collisions. .. seealso:: :attr:`_orm.Mapper.attrs` """ return util.ReadOnlyProperties( dict(self.class_manager._all_sqla_attributes()) ) @HasMemoized.memoized_attribute @util.preload_module("sqlalchemy.orm.descriptor_props") def _pk_synonyms(self) -> Dict[str, str]: """return a dictionary of {syn_attribute_name: pk_attr_name} for all synonyms that refer to primary key columns """ descriptor_props = util.preloaded.orm_descriptor_props pk_keys = {prop.key for prop in self._identity_key_props} return { syn.key: syn.name for k, syn in self._props.items() if isinstance(syn, descriptor_props.SynonymProperty) and syn.name in pk_keys } @HasMemoized.memoized_attribute @util.preload_module("sqlalchemy.orm.descriptor_props") def synonyms(self) -> util.ReadOnlyProperties[SynonymProperty[Any]]: """Return a namespace of all :class:`.Synonym` properties maintained by this :class:`_orm.Mapper`. .. seealso:: :attr:`_orm.Mapper.attrs` - namespace of all :class:`.MapperProperty` objects. """ descriptor_props = util.preloaded.orm_descriptor_props return self._filter_properties(descriptor_props.SynonymProperty) @property def entity_namespace(self): return self.class_ @HasMemoized.memoized_attribute def column_attrs(self) -> util.ReadOnlyProperties[ColumnProperty[Any]]: """Return a namespace of all :class:`.ColumnProperty` properties maintained by this :class:`_orm.Mapper`. .. seealso:: :attr:`_orm.Mapper.attrs` - namespace of all :class:`.MapperProperty` objects. """ return self._filter_properties(properties.ColumnProperty) @HasMemoized.memoized_attribute @util.preload_module("sqlalchemy.orm.relationships") def relationships( self, ) -> util.ReadOnlyProperties[RelationshipProperty[Any]]: """A namespace of all :class:`.Relationship` properties maintained by this :class:`_orm.Mapper`. .. warning:: the :attr:`_orm.Mapper.relationships` accessor namespace is an instance of :class:`.OrderedProperties`. This is a dictionary-like object which includes a small number of named methods such as :meth:`.OrderedProperties.items` and :meth:`.OrderedProperties.values`. When accessing attributes dynamically, favor using the dict-access scheme, e.g. ``mapper.relationships[somename]`` over ``getattr(mapper.relationships, somename)`` to avoid name collisions. .. seealso:: :attr:`_orm.Mapper.attrs` - namespace of all :class:`.MapperProperty` objects. """ return self._filter_properties( util.preloaded.orm_relationships.RelationshipProperty ) @HasMemoized.memoized_attribute @util.preload_module("sqlalchemy.orm.descriptor_props") def composites(self) -> util.ReadOnlyProperties[CompositeProperty[Any]]: """Return a namespace of all :class:`.Composite` properties maintained by this :class:`_orm.Mapper`. .. seealso:: :attr:`_orm.Mapper.attrs` - namespace of all :class:`.MapperProperty` objects. """ return self._filter_properties( util.preloaded.orm_descriptor_props.CompositeProperty ) def _filter_properties( self, type_: Type[_MP] ) -> util.ReadOnlyProperties[_MP]: self._check_configure() return util.ReadOnlyProperties( util.OrderedDict( (k, v) for k, v in self._props.items() if isinstance(v, type_) ) ) @HasMemoized.memoized_attribute def _get_clause(self): """create a "get clause" based on the primary key. this is used by query.get() and many-to-one lazyloads to load this item by primary key. """ params = [ ( primary_key, sql.bindparam("pk_%d" % idx, type_=primary_key.type), ) for idx, primary_key in enumerate(self.primary_key, 1) ] return ( sql.and_(*[k == v for (k, v) in params]), util.column_dict(params), ) @HasMemoized.memoized_attribute def _equivalent_columns(self) -> _EquivalentColumnMap: """Create a map of all equivalent columns, based on the determination of column pairs that are equated to one another based on inherit condition. This is designed to work with the queries that util.polymorphic_union comes up with, which often don't include the columns from the base table directly (including the subclass table columns only). The resulting structure is a dictionary of columns mapped to lists of equivalent columns, e.g.:: {tablea.col1: {tableb.col1, tablec.col1}, tablea.col2: {tabled.col2}} """ # noqa: E501 result: _EquivalentColumnMap = {} def visit_binary(binary): if binary.operator == operators.eq: if binary.left in result: result[binary.left].add(binary.right) else: result[binary.left] = {binary.right} if binary.right in result: result[binary.right].add(binary.left) else: result[binary.right] = {binary.left} for mapper in self.base_mapper.self_and_descendants: if mapper.inherit_condition is not None: visitors.traverse( mapper.inherit_condition, {}, {"binary": visit_binary} ) return result def _is_userland_descriptor(self, assigned_name: str, obj: Any) -> bool: if isinstance( obj, ( _MappedAttribute, instrumentation.ClassManager, expression.ColumnElement, ), ): return False else: return assigned_name not in self._dataclass_fields @HasMemoized.memoized_attribute def _dataclass_fields(self): return [f.name for f in util.dataclass_fields(self.class_)] def _should_exclude(self, name, assigned_name, local, column): """determine whether a particular property should be implicitly present on the class. This occurs when properties are propagated from an inherited class, or are applied from the columns present in the mapped table. """ if column is not None and sql_base._never_select_column(column): return True # check for class-bound attributes and/or descriptors, # either local or from an inherited class # ignore dataclass field default values if local: if self.class_.__dict__.get( assigned_name, None ) is not None and self._is_userland_descriptor( assigned_name, self.class_.__dict__[assigned_name] ): return True else: attr = self.class_manager._get_class_attr_mro(assigned_name, None) if attr is not None and self._is_userland_descriptor( assigned_name, attr ): return True if ( self.include_properties is not None and name not in self.include_properties and (column is None or column not in self.include_properties) ): self._log("not including property %s" % (name)) return True if self.exclude_properties is not None and ( name in self.exclude_properties or (column is not None and column in self.exclude_properties) ): self._log("excluding property %s" % (name)) return True return False def common_parent(self, other: Mapper[Any]) -> bool: """Return true if the given mapper shares a common inherited parent as this mapper.""" return self.base_mapper is other.base_mapper def is_sibling(self, other: Mapper[Any]) -> bool: """return true if the other mapper is an inheriting sibling to this one. common parent but different branch """ return ( self.base_mapper is other.base_mapper and not self.isa(other) and not other.isa(self) ) def _canload( self, state: InstanceState[Any], allow_subtypes: bool ) -> bool: s = self.primary_mapper() if self.polymorphic_on is not None or allow_subtypes: return _state_mapper(state).isa(s) else: return _state_mapper(state) is s def isa(self, other: Mapper[Any]) -> bool: """Return True if the this mapper inherits from the given mapper.""" m: Optional[Mapper[Any]] = self while m and m is not other: m = m.inherits return bool(m) def iterate_to_root(self) -> Iterator[Mapper[Any]]: m: Optional[Mapper[Any]] = self while m: yield m m = m.inherits @HasMemoized.memoized_attribute def self_and_descendants(self) -> Sequence[Mapper[Any]]: """The collection including this mapper and all descendant mappers. This includes not just the immediately inheriting mappers but all their inheriting mappers as well. """ descendants = [] stack = deque([self]) while stack: item = stack.popleft() descendants.append(item) stack.extend(item._inheriting_mappers) return util.WeakSequence(descendants) def polymorphic_iterator(self) -> Iterator[Mapper[Any]]: """Iterate through the collection including this mapper and all descendant mappers. This includes not just the immediately inheriting mappers but all their inheriting mappers as well. To iterate through an entire hierarchy, use ``mapper.base_mapper.polymorphic_iterator()``. """ return iter(self.self_and_descendants) def primary_mapper(self) -> Mapper[Any]: """Return the primary mapper corresponding to this mapper's class key (class).""" return self.class_manager.mapper @property def primary_base_mapper(self) -> Mapper[Any]: return self.class_manager.mapper.base_mapper def _result_has_identity_key(self, result, adapter=None): pk_cols: Sequence[ColumnClause[Any]] = self.primary_key if adapter: pk_cols = [adapter.columns[c] for c in pk_cols] rk = result.keys() for col in pk_cols: if col not in rk: return False else: return True def identity_key_from_row( self, row: Union[Row[Any], RowMapping], identity_token: Optional[Any] = None, adapter: Optional[ORMAdapter] = None, ) -> _IdentityKeyType[_O]: """Return an identity-map key for use in storing/retrieving an item from the identity map. :param row: A :class:`.Row` or :class:`.RowMapping` produced from a result set that selected from the ORM mapped primary key columns. .. versionchanged:: 2.0 :class:`.Row` or :class:`.RowMapping` are accepted for the "row" argument """ pk_cols: Sequence[ColumnClause[Any]] = self.primary_key if adapter: pk_cols = [adapter.columns[c] for c in pk_cols] mapping: RowMapping if hasattr(row, "_mapping"): mapping = row._mapping else: mapping = row # type: ignore[assignment] return ( self._identity_class, tuple(mapping[column] for column in pk_cols), identity_token, ) def identity_key_from_primary_key( self, primary_key: Tuple[Any, ...], identity_token: Optional[Any] = None, ) -> _IdentityKeyType[_O]: """Return an identity-map key for use in storing/retrieving an item from an identity map. :param primary_key: A list of values indicating the identifier. """ return ( self._identity_class, tuple(primary_key), identity_token, ) def identity_key_from_instance(self, instance: _O) -> _IdentityKeyType[_O]: """Return the identity key for the given instance, based on its primary key attributes. If the instance's state is expired, calling this method will result in a database check to see if the object has been deleted. If the row no longer exists, :class:`~sqlalchemy.orm.exc.ObjectDeletedError` is raised. This value is typically also found on the instance state under the attribute name `key`. """ state = attributes.instance_state(instance) return self._identity_key_from_state(state, PassiveFlag.PASSIVE_OFF) def _identity_key_from_state( self, state: InstanceState[_O], passive: PassiveFlag = PassiveFlag.PASSIVE_RETURN_NO_VALUE, ) -> _IdentityKeyType[_O]: dict_ = state.dict manager = state.manager return ( self._identity_class, tuple( [ manager[prop.key].impl.get(state, dict_, passive) for prop in self._identity_key_props ] ), state.identity_token, ) def primary_key_from_instance(self, instance: _O) -> Tuple[Any, ...]: """Return the list of primary key values for the given instance. If the instance's state is expired, calling this method will result in a database check to see if the object has been deleted. If the row no longer exists, :class:`~sqlalchemy.orm.exc.ObjectDeletedError` is raised. """ state = attributes.instance_state(instance) identity_key = self._identity_key_from_state( state, PassiveFlag.PASSIVE_OFF ) return identity_key[1] @HasMemoized.memoized_attribute def _persistent_sortkey_fn(self): key_fns = [col.type.sort_key_function for col in self.primary_key] if set(key_fns).difference([None]): def key(state): return tuple( key_fn(val) if key_fn is not None else val for key_fn, val in zip(key_fns, state.key[1]) ) else: def key(state): return state.key[1] return key @HasMemoized.memoized_attribute def _identity_key_props(self): return [self._columntoproperty[col] for col in self.primary_key] @HasMemoized.memoized_attribute def _all_pk_cols(self): collection: Set[ColumnClause[Any]] = set() for table in self.tables: collection.update(self._pks_by_table[table]) return collection @HasMemoized.memoized_attribute def _should_undefer_in_wildcard(self): cols: Set[ColumnElement[Any]] = set(self.primary_key) if self.polymorphic_on is not None: cols.add(self.polymorphic_on) return cols @HasMemoized.memoized_attribute def _primary_key_propkeys(self): return {self._columntoproperty[col].key for col in self._all_pk_cols} def _get_state_attr_by_column( self, state: InstanceState[_O], dict_: _InstanceDict, column: ColumnElement[Any], passive: PassiveFlag = PassiveFlag.PASSIVE_RETURN_NO_VALUE, ) -> Any: prop = self._columntoproperty[column] return state.manager[prop.key].impl.get(state, dict_, passive=passive) def _set_committed_state_attr_by_column(self, state, dict_, column, value): prop = self._columntoproperty[column] state.manager[prop.key].impl.set_committed_value(state, dict_, value) def _set_state_attr_by_column(self, state, dict_, column, value): prop = self._columntoproperty[column] state.manager[prop.key].impl.set(state, dict_, value, None) def _get_committed_attr_by_column(self, obj, column): state = attributes.instance_state(obj) dict_ = attributes.instance_dict(obj) return self._get_committed_state_attr_by_column( state, dict_, column, passive=PassiveFlag.PASSIVE_OFF ) def _get_committed_state_attr_by_column( self, state, dict_, column, passive=PassiveFlag.PASSIVE_RETURN_NO_VALUE ): prop = self._columntoproperty[column] return state.manager[prop.key].impl.get_committed_value( state, dict_, passive=passive ) def _optimized_get_statement(self, state, attribute_names): """assemble a WHERE clause which retrieves a given state by primary key, using a minimized set of tables. Applies to a joined-table inheritance mapper where the requested attribute names are only present on joined tables, not the base table. The WHERE clause attempts to include only those tables to minimize joins. """ props = self._props col_attribute_names = set(attribute_names).intersection( state.mapper.column_attrs.keys() ) tables: Set[FromClause] = set( chain( *[ sql_util.find_tables(c, check_columns=True) for key in col_attribute_names for c in props[key].columns ] ) ) if self.base_mapper.local_table in tables: return None def visit_binary(binary): leftcol = binary.left rightcol = binary.right if leftcol is None or rightcol is None: return if leftcol.table not in tables: leftval = self._get_committed_state_attr_by_column( state, state.dict, leftcol, passive=PassiveFlag.PASSIVE_NO_INITIALIZE, ) if leftval in orm_util._none_set: raise _OptGetColumnsNotAvailable() binary.left = sql.bindparam( None, leftval, type_=binary.right.type ) elif rightcol.table not in tables: rightval = self._get_committed_state_attr_by_column( state, state.dict, rightcol, passive=PassiveFlag.PASSIVE_NO_INITIALIZE, ) if rightval in orm_util._none_set: raise _OptGetColumnsNotAvailable() binary.right = sql.bindparam( None, rightval, type_=binary.right.type ) allconds: List[ColumnElement[bool]] = [] start = False # as of #7507, from the lowest base table on upwards, # we include all intermediary tables. for mapper in reversed(list(self.iterate_to_root())): if mapper.local_table in tables: start = True elif not isinstance(mapper.local_table, expression.TableClause): return None if start and not mapper.single: assert mapper.inherits assert not mapper.concrete assert mapper.inherit_condition is not None allconds.append(mapper.inherit_condition) tables.add(mapper.local_table) # only the bottom table needs its criteria to be altered to fit # the primary key ident - the rest of the tables upwards to the # descendant-most class should all be present and joined to each # other. try: _traversed = visitors.cloned_traverse( allconds[0], {}, {"binary": visit_binary} ) except _OptGetColumnsNotAvailable: return None else: allconds[0] = _traversed cond = sql.and_(*allconds) cols = [] for key in col_attribute_names: cols.extend(props[key].columns) return ( sql.select(*cols) .where(cond) .set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL) ) def _iterate_to_target_viawpoly(self, mapper): if self.isa(mapper): prev = self for m in self.iterate_to_root(): yield m if m is not prev and prev not in m._with_polymorphic_mappers: break prev = m if m is mapper: break @HasMemoized.memoized_attribute def _would_selectinload_combinations_cache(self): return {} def _would_selectin_load_only_from_given_mapper(self, super_mapper): """return True if this mapper would "selectin" polymorphic load based on the given super mapper, and not from a setting from a subclass. given:: class A: ... class B(A): __mapper_args__ = {"polymorphic_load": "selectin"} class C(B): ... class D(B): __mapper_args__ = {"polymorphic_load": "selectin"} ``inspect(C)._would_selectin_load_only_from_given_mapper(inspect(B))`` returns True, because C does selectin loading because of B's setting. OTOH, ``inspect(D) ._would_selectin_load_only_from_given_mapper(inspect(B))`` returns False, because D does selectin loading because of its own setting; when we are doing a selectin poly load from B, we want to filter out D because it would already have its own selectin poly load set up separately. Added as part of #9373. """ cache = self._would_selectinload_combinations_cache try: return cache[super_mapper] except KeyError: pass # assert that given object is a supermapper, meaning we already # strong reference it directly or indirectly. this allows us # to not worry that we are creating new strongrefs to unrelated # mappers or other objects. assert self.isa(super_mapper) mapper = super_mapper for m in self._iterate_to_target_viawpoly(mapper): if m.polymorphic_load == "selectin": retval = m is super_mapper break else: retval = False cache[super_mapper] = retval return retval def _should_selectin_load(self, enabled_via_opt, polymorphic_from): if not enabled_via_opt: # common case, takes place for all polymorphic loads mapper = polymorphic_from for m in self._iterate_to_target_viawpoly(mapper): if m.polymorphic_load == "selectin": return m else: # uncommon case, selectin load options were used enabled_via_opt = set(enabled_via_opt) enabled_via_opt_mappers = {e.mapper: e for e in enabled_via_opt} for entity in enabled_via_opt.union([polymorphic_from]): mapper = entity.mapper for m in self._iterate_to_target_viawpoly(mapper): if ( m.polymorphic_load == "selectin" or m in enabled_via_opt_mappers ): return enabled_via_opt_mappers.get(m, m) return None @util.preload_module("sqlalchemy.orm.strategy_options") def _subclass_load_via_in(self, entity, polymorphic_from): """Assemble a that can load the columns local to this subclass as a SELECT with IN. """ strategy_options = util.preloaded.orm_strategy_options assert self.inherits if self.polymorphic_on is not None: polymorphic_prop = self._columntoproperty[self.polymorphic_on] keep_props = set([polymorphic_prop] + self._identity_key_props) else: keep_props = set(self._identity_key_props) disable_opt = strategy_options.Load(entity) enable_opt = strategy_options.Load(entity) classes_to_include = {self} m: Optional[Mapper[Any]] = self.inherits while ( m is not None and m is not polymorphic_from and m.polymorphic_load == "selectin" ): classes_to_include.add(m) m = m.inherits for prop in self.column_attrs + self.relationships: # skip prop keys that are not instrumented on the mapped class. # this is primarily the "_sa_polymorphic_on" property that gets # created for an ad-hoc polymorphic_on SQL expression, issue #8704 if prop.key not in self.class_manager: continue if prop.parent in classes_to_include or prop in keep_props: # "enable" options, to turn on the properties that we want to # load by default (subject to options from the query) if not isinstance(prop, StrategizedProperty): continue enable_opt = enable_opt._set_generic_strategy( # convert string name to an attribute before passing # to loader strategy. note this must be in terms # of given entity, such as AliasedClass, etc. (getattr(entity.entity_namespace, prop.key),), dict(prop.strategy_key), _reconcile_to_other=True, ) else: # "disable" options, to turn off the properties from the # superclass that we *don't* want to load, applied after # the options from the query to override them disable_opt = disable_opt._set_generic_strategy( # convert string name to an attribute before passing # to loader strategy. note this must be in terms # of given entity, such as AliasedClass, etc. (getattr(entity.entity_namespace, prop.key),), {"do_nothing": True}, _reconcile_to_other=False, ) primary_key = [ sql_util._deep_annotate(pk, {"_orm_adapt": True}) for pk in self.primary_key ] in_expr: ColumnElement[Any] if len(primary_key) > 1: in_expr = sql.tuple_(*primary_key) else: in_expr = primary_key[0] if entity.is_aliased_class: assert entity.mapper is self q = sql.select(entity).set_label_style( LABEL_STYLE_TABLENAME_PLUS_COL ) in_expr = entity._adapter.traverse(in_expr) primary_key = [entity._adapter.traverse(k) for k in primary_key] q = q.where( in_expr.in_(sql.bindparam("primary_keys", expanding=True)) ).order_by(*primary_key) else: q = sql.select(self).set_label_style( LABEL_STYLE_TABLENAME_PLUS_COL ) q = q.where( in_expr.in_(sql.bindparam("primary_keys", expanding=True)) ).order_by(*primary_key) return q, enable_opt, disable_opt @HasMemoized.memoized_attribute def _subclass_load_via_in_mapper(self): # the default is loading this mapper against the basemost mapper return self._subclass_load_via_in(self, self.base_mapper) def cascade_iterator( self, type_: str, state: InstanceState[_O], halt_on: Optional[Callable[[InstanceState[Any]], bool]] = None, ) -> Iterator[ Tuple[object, Mapper[Any], InstanceState[Any], _InstanceDict] ]: r"""Iterate each element and its mapper in an object graph, for all relationships that meet the given cascade rule. :param type\_: The name of the cascade rule (i.e. ``"save-update"``, ``"delete"``, etc.). .. note:: the ``"all"`` cascade is not accepted here. For a generic object traversal function, see :ref:`faq_walk_objects`. :param state: The lead InstanceState. child items will be processed per the relationships defined for this object's mapper. :return: the method yields individual object instances. .. seealso:: :ref:`unitofwork_cascades` :ref:`faq_walk_objects` - illustrates a generic function to traverse all objects without relying on cascades. """ visited_states: Set[InstanceState[Any]] = set() prp, mpp = object(), object() assert state.mapper.isa(self) # this is actually a recursive structure, fully typing it seems # a little too difficult for what it's worth here visitables: Deque[ Tuple[ Deque[Any], object, Optional[InstanceState[Any]], Optional[_InstanceDict], ] ] visitables = deque( [(deque(state.mapper._props.values()), prp, state, state.dict)] ) while visitables: iterator, item_type, parent_state, parent_dict = visitables[-1] if not iterator: visitables.pop() continue if item_type is prp: prop = iterator.popleft() if not prop.cascade or type_ not in prop.cascade: continue assert parent_state is not None assert parent_dict is not None queue = deque( prop.cascade_iterator( type_, parent_state, parent_dict, visited_states, halt_on, ) ) if queue: visitables.append((queue, mpp, None, None)) elif item_type is mpp: ( instance, instance_mapper, corresponding_state, corresponding_dict, ) = iterator.popleft() yield ( instance, instance_mapper, corresponding_state, corresponding_dict, ) visitables.append( ( deque(instance_mapper._props.values()), prp, corresponding_state, corresponding_dict, ) ) @HasMemoized.memoized_attribute def _compiled_cache(self): return util.LRUCache(self._compiled_cache_size) @HasMemoized.memoized_attribute def _multiple_persistence_tables(self): return len(self.tables) > 1 @HasMemoized.memoized_attribute def _sorted_tables(self): table_to_mapper: Dict[TableClause, Mapper[Any]] = {} for mapper in self.base_mapper.self_and_descendants: for t in mapper.tables: table_to_mapper.setdefault(t, mapper) extra_dependencies = [] for table, mapper in table_to_mapper.items(): super_ = mapper.inherits if super_: extra_dependencies.extend( [(super_table, table) for super_table in super_.tables] ) def skip(fk): # attempt to skip dependencies that are not # significant to the inheritance chain # for two tables that are related by inheritance. # while that dependency may be important, it's technically # not what we mean to sort on here. parent = table_to_mapper.get(fk.parent.table) dep = table_to_mapper.get(fk.column.table) if ( parent is not None and dep is not None and dep is not parent and dep.inherit_condition is not None ): cols = set(sql_util._find_columns(dep.inherit_condition)) if parent.inherit_condition is not None: cols = cols.union( sql_util._find_columns(parent.inherit_condition) ) return fk.parent not in cols and fk.column not in cols else: return fk.parent not in cols return False sorted_ = sql_util.sort_tables( table_to_mapper, skip_fn=skip, extra_dependencies=extra_dependencies, ) ret = util.OrderedDict() for t in sorted_: ret[t] = table_to_mapper[t] return ret def _memo(self, key: Any, callable_: Callable[[], _T]) -> _T: if key in self._memoized_values: return cast(_T, self._memoized_values[key]) else: self._memoized_values[key] = value = callable_() return value @util.memoized_property def _table_to_equated(self): """memoized map of tables to collections of columns to be synchronized upwards to the base mapper.""" result: util.defaultdict[ Table, List[ Tuple[ Mapper[Any], List[Tuple[ColumnElement[Any], ColumnElement[Any]]], ] ], ] = util.defaultdict(list) def set_union(x, y): return x.union(y) for table in self._sorted_tables: cols = set(table.c) for m in self.iterate_to_root(): if m._inherits_equated_pairs and cols.intersection( reduce( set_union, [l.proxy_set for l, r in m._inherits_equated_pairs], ) ): result[table].append((m, m._inherits_equated_pairs)) return result class _OptGetColumnsNotAvailable(Exception): pass def configure_mappers() -> None: """Initialize the inter-mapper relationships of all mappers that have been constructed thus far across all :class:`_orm.registry` collections. The configure step is used to reconcile and initialize the :func:`_orm.relationship` linkages between mapped classes, as well as to invoke configuration events such as the :meth:`_orm.MapperEvents.before_configured` and :meth:`_orm.MapperEvents.after_configured`, which may be used by ORM extensions or user-defined extension hooks. Mapper configuration is normally invoked automatically, the first time mappings from a particular :class:`_orm.registry` are used, as well as whenever mappings are used and additional not-yet-configured mappers have been constructed. The automatic configuration process however is local only to the :class:`_orm.registry` involving the target mapper and any related :class:`_orm.registry` objects which it may depend on; this is equivalent to invoking the :meth:`_orm.registry.configure` method on a particular :class:`_orm.registry`. By contrast, the :func:`_orm.configure_mappers` function will invoke the configuration process on all :class:`_orm.registry` objects that exist in memory, and may be useful for scenarios where many individual :class:`_orm.registry` objects that are nonetheless interrelated are in use. .. versionchanged:: 1.4 As of SQLAlchemy 1.4.0b2, this function works on a per-:class:`_orm.registry` basis, locating all :class:`_orm.registry` objects present and invoking the :meth:`_orm.registry.configure` method on each. The :meth:`_orm.registry.configure` method may be preferred to limit the configuration of mappers to those local to a particular :class:`_orm.registry` and/or declarative base class. Points at which automatic configuration is invoked include when a mapped class is instantiated into an instance, as well as when ORM queries are emitted using :meth:`.Session.query` or :meth:`_orm.Session.execute` with an ORM-enabled statement. The mapper configure process, whether invoked by :func:`_orm.configure_mappers` or from :meth:`_orm.registry.configure`, provides several event hooks that can be used to augment the mapper configuration step. These hooks include: * :meth:`.MapperEvents.before_configured` - called once before :func:`.configure_mappers` or :meth:`_orm.registry.configure` does any work; this can be used to establish additional options, properties, or related mappings before the operation proceeds. * :meth:`.MapperEvents.mapper_configured` - called as each individual :class:`_orm.Mapper` is configured within the process; will include all mapper state except for backrefs set up by other mappers that are still to be configured. * :meth:`.MapperEvents.after_configured` - called once after :func:`.configure_mappers` or :meth:`_orm.registry.configure` is complete; at this stage, all :class:`_orm.Mapper` objects that fall within the scope of the configuration operation will be fully configured. Note that the calling application may still have other mappings that haven't been produced yet, such as if they are in modules as yet unimported, and may also have mappings that are still to be configured, if they are in other :class:`_orm.registry` collections not part of the current scope of configuration. """ _configure_registries(_all_registries(), cascade=True) def _configure_registries( registries: Set[_RegistryType], cascade: bool ) -> None: for reg in registries: if reg._new_mappers: break else: return with _CONFIGURE_MUTEX: global _already_compiling if _already_compiling: return _already_compiling = True try: # double-check inside mutex for reg in registries: if reg._new_mappers: break else: return Mapper.dispatch._for_class(Mapper).before_configured() # type: ignore # noqa: E501 # initialize properties on all mappers # note that _mapper_registry is unordered, which # may randomly conceal/reveal issues related to # the order of mapper compilation _do_configure_registries(registries, cascade) finally: _already_compiling = False Mapper.dispatch._for_class(Mapper).after_configured() # type: ignore @util.preload_module("sqlalchemy.orm.decl_api") def _do_configure_registries( registries: Set[_RegistryType], cascade: bool ) -> None: registry = util.preloaded.orm_decl_api.registry orig = set(registries) for reg in registry._recurse_with_dependencies(registries): has_skip = False for mapper in reg._mappers_to_configure(): run_configure = None for fn in mapper.dispatch.before_mapper_configured: run_configure = fn(mapper, mapper.class_) if run_configure is EXT_SKIP: has_skip = True break if run_configure is EXT_SKIP: continue if getattr(mapper, "_configure_failed", False): e = sa_exc.InvalidRequestError( "One or more mappers failed to initialize - " "can't proceed with initialization of other " "mappers. Triggering mapper: '%s'. " "Original exception was: %s" % (mapper, mapper._configure_failed) ) e._configure_failed = mapper._configure_failed # type: ignore raise e if not mapper.configured: try: mapper._post_configure_properties() mapper._expire_memoizations() mapper.dispatch.mapper_configured(mapper, mapper.class_) except Exception: exc = sys.exc_info()[1] if not hasattr(exc, "_configure_failed"): mapper._configure_failed = exc raise if not has_skip: reg._new_mappers = False if not cascade and reg._dependencies.difference(orig): raise sa_exc.InvalidRequestError( "configure was called with cascade=False but " "additional registries remain" ) @util.preload_module("sqlalchemy.orm.decl_api") def _dispose_registries(registries: Set[_RegistryType], cascade: bool) -> None: registry = util.preloaded.orm_decl_api.registry orig = set(registries) for reg in registry._recurse_with_dependents(registries): if not cascade and reg._dependents.difference(orig): raise sa_exc.InvalidRequestError( "Registry has dependent registries that are not disposed; " "pass cascade=True to clear these also" ) while reg._managers: try: manager, _ = reg._managers.popitem() except KeyError: # guard against race between while and popitem pass else: reg._dispose_manager_and_mapper(manager) reg._non_primary_mappers.clear() reg._dependents.clear() for dep in reg._dependencies: dep._dependents.discard(reg) reg._dependencies.clear() # this wasn't done in the 1.3 clear_mappers() and in fact it # was a bug, as it could cause configure_mappers() to invoke # the "before_configured" event even though mappers had all been # disposed. reg._new_mappers = False def reconstructor(fn: _Fn) -> _Fn: """Decorate a method as the 'reconstructor' hook. Designates a single method as the "reconstructor", an ``__init__``-like method that will be called by the ORM after the instance has been loaded from the database or otherwise reconstituted. .. tip:: The :func:`_orm.reconstructor` decorator makes use of the :meth:`_orm.InstanceEvents.load` event hook, which can be used directly. The reconstructor will be invoked with no arguments. Scalar (non-collection) database-mapped attributes of the instance will be available for use within the function. Eagerly-loaded collections are generally not yet available and will usually only contain the first element. ORM state changes made to objects at this stage will not be recorded for the next flush() operation, so the activity within a reconstructor should be conservative. .. seealso:: :meth:`.InstanceEvents.load` """ fn.__sa_reconstructor__ = True # type: ignore[attr-defined] return fn def validates( *names: str, include_removes: bool = False, include_backrefs: bool = True ) -> Callable[[_Fn], _Fn]: r"""Decorate a method as a 'validator' for one or more named properties. Designates a method as a validator, a method which receives the name of the attribute as well as a value to be assigned, or in the case of a collection, the value to be added to the collection. The function can then raise validation exceptions to halt the process from continuing (where Python's built-in ``ValueError`` and ``AssertionError`` exceptions are reasonable choices), or can modify or replace the value before proceeding. The function should otherwise return the given value. Note that a validator for a collection **cannot** issue a load of that collection within the validation routine - this usage raises an assertion to avoid recursion overflows. This is a reentrant condition which is not supported. :param \*names: list of attribute names to be validated. :param include_removes: if True, "remove" events will be sent as well - the validation function must accept an additional argument "is_remove" which will be a boolean. :param include_backrefs: defaults to ``True``; if ``False``, the validation function will not emit if the originator is an attribute event related via a backref. This can be used for bi-directional :func:`.validates` usage where only one validator should emit per attribute operation. .. versionchanged:: 2.0.16 This paramter inadvertently defaulted to ``False`` for releases 2.0.0 through 2.0.15. Its correct default of ``True`` is restored in 2.0.16. .. seealso:: :ref:`simple_validators` - usage examples for :func:`.validates` """ def wrap(fn: _Fn) -> _Fn: fn.__sa_validators__ = names # type: ignore[attr-defined] fn.__sa_validation_opts__ = { # type: ignore[attr-defined] "include_removes": include_removes, "include_backrefs": include_backrefs, } return fn return wrap def _event_on_load(state, ctx): instrumenting_mapper = state.manager.mapper if instrumenting_mapper._reconstructor: instrumenting_mapper._reconstructor(state.obj()) def _event_on_init(state, args, kwargs): """Run init_instance hooks. This also includes mapper compilation, normally not needed here but helps with some piecemeal configuration scenarios (such as in the ORM tutorial). """ instrumenting_mapper = state.manager.mapper if instrumenting_mapper: instrumenting_mapper._check_configure() if instrumenting_mapper._set_polymorphic_identity: instrumenting_mapper._set_polymorphic_identity(state) class _ColumnMapping(Dict["ColumnElement[Any]", "MapperProperty[Any]"]): """Error reporting helper for mapper._columntoproperty.""" __slots__ = ("mapper",) def __init__(self, mapper): # TODO: weakref would be a good idea here self.mapper = mapper def __missing__(self, column): prop = self.mapper._props.get(column) if prop: raise orm_exc.UnmappedColumnError( "Column '%s.%s' is not available, due to " "conflicting property '%s':%r" % (column.table.name, column.name, column.key, prop) ) raise orm_exc.UnmappedColumnError( "No column %s is configured on mapper %s..." % (column, self.mapper) ) sqlalchemy/orm/path_registry.py 0000755 00000062474 15125143220 0012754 0 ustar 00 # orm/path_registry.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """Path tracking utilities, representing mapper graph traversals. """ from __future__ import annotations from functools import reduce from itertools import chain import logging import operator from typing import Any from typing import cast from typing import Dict from typing import Iterator from typing import List from typing import Optional from typing import overload from typing import Sequence from typing import Tuple from typing import TYPE_CHECKING from typing import Union from . import base as orm_base from ._typing import insp_is_mapper_property from .. import exc from .. import util from ..sql import visitors from ..sql.cache_key import HasCacheKey if TYPE_CHECKING: from ._typing import _InternalEntityType from .interfaces import StrategizedProperty from .mapper import Mapper from .relationships import RelationshipProperty from .util import AliasedInsp from ..sql.cache_key import _CacheKeyTraversalType from ..sql.elements import BindParameter from ..sql.visitors import anon_map from ..util.typing import _LiteralStar from ..util.typing import TypeGuard def is_root(path: PathRegistry) -> TypeGuard[RootRegistry]: ... def is_entity(path: PathRegistry) -> TypeGuard[AbstractEntityRegistry]: ... else: is_root = operator.attrgetter("is_root") is_entity = operator.attrgetter("is_entity") _SerializedPath = List[Any] _StrPathToken = str _PathElementType = Union[ _StrPathToken, "_InternalEntityType[Any]", "StrategizedProperty[Any]" ] # the representation is in fact # a tuple with alternating: # [_InternalEntityType[Any], Union[str, StrategizedProperty[Any]], # _InternalEntityType[Any], Union[str, StrategizedProperty[Any]], ...] # this might someday be a tuple of 2-tuples instead, but paths can be # chopped at odd intervals as well so this is less flexible _PathRepresentation = Tuple[_PathElementType, ...] # NOTE: these names are weird since the array is 0-indexed, # the "_Odd" entries are at 0, 2, 4, etc _OddPathRepresentation = Sequence["_InternalEntityType[Any]"] _EvenPathRepresentation = Sequence[Union["StrategizedProperty[Any]", str]] log = logging.getLogger(__name__) def _unreduce_path(path: _SerializedPath) -> PathRegistry: return PathRegistry.deserialize(path) _WILDCARD_TOKEN: _LiteralStar = "*" _DEFAULT_TOKEN = "_sa_default" class PathRegistry(HasCacheKey): """Represent query load paths and registry functions. Basically represents structures like: (<User mapper>, "orders", <Order mapper>, "items", <Item mapper>) These structures are generated by things like query options (joinedload(), subqueryload(), etc.) and are used to compose keys stored in the query._attributes dictionary for various options. They are then re-composed at query compile/result row time as the query is formed and as rows are fetched, where they again serve to compose keys to look up options in the context.attributes dictionary, which is copied from query._attributes. The path structure has a limited amount of caching, where each "root" ultimately pulls from a fixed registry associated with the first mapper, that also contains elements for each of its property keys. However paths longer than two elements, which are the exception rather than the rule, are generated on an as-needed basis. """ __slots__ = () is_token = False is_root = False has_entity = False is_property = False is_entity = False is_unnatural: bool path: _PathRepresentation natural_path: _PathRepresentation parent: Optional[PathRegistry] root: RootRegistry _cache_key_traversal: _CacheKeyTraversalType = [ ("path", visitors.ExtendedInternalTraversal.dp_has_cache_key_list) ] def __eq__(self, other: Any) -> bool: try: return other is not None and self.path == other._path_for_compare except AttributeError: util.warn( "Comparison of PathRegistry to %r is not supported" % (type(other)) ) return False def __ne__(self, other: Any) -> bool: try: return other is None or self.path != other._path_for_compare except AttributeError: util.warn( "Comparison of PathRegistry to %r is not supported" % (type(other)) ) return True @property def _path_for_compare(self) -> Optional[_PathRepresentation]: return self.path def odd_element(self, index: int) -> _InternalEntityType[Any]: return self.path[index] # type: ignore def set(self, attributes: Dict[Any, Any], key: Any, value: Any) -> None: log.debug("set '%s' on path '%s' to '%s'", key, self, value) attributes[(key, self.natural_path)] = value def setdefault( self, attributes: Dict[Any, Any], key: Any, value: Any ) -> None: log.debug("setdefault '%s' on path '%s' to '%s'", key, self, value) attributes.setdefault((key, self.natural_path), value) def get( self, attributes: Dict[Any, Any], key: Any, value: Optional[Any] = None ) -> Any: key = (key, self.natural_path) if key in attributes: return attributes[key] else: return value def __len__(self) -> int: return len(self.path) def __hash__(self) -> int: return id(self) @overload def __getitem__(self, entity: _StrPathToken) -> TokenRegistry: ... @overload def __getitem__(self, entity: int) -> _PathElementType: ... @overload def __getitem__(self, entity: slice) -> _PathRepresentation: ... @overload def __getitem__( self, entity: _InternalEntityType[Any] ) -> AbstractEntityRegistry: ... @overload def __getitem__( self, entity: StrategizedProperty[Any] ) -> PropRegistry: ... def __getitem__( self, entity: Union[ _StrPathToken, int, slice, _InternalEntityType[Any], StrategizedProperty[Any], ], ) -> Union[ TokenRegistry, _PathElementType, _PathRepresentation, PropRegistry, AbstractEntityRegistry, ]: raise NotImplementedError() # TODO: what are we using this for? @property def length(self) -> int: return len(self.path) def pairs( self, ) -> Iterator[ Tuple[_InternalEntityType[Any], Union[str, StrategizedProperty[Any]]] ]: odd_path = cast(_OddPathRepresentation, self.path) even_path = cast(_EvenPathRepresentation, odd_path) for i in range(0, len(odd_path), 2): yield odd_path[i], even_path[i + 1] def contains_mapper(self, mapper: Mapper[Any]) -> bool: _m_path = cast(_OddPathRepresentation, self.path) for path_mapper in [_m_path[i] for i in range(0, len(_m_path), 2)]: if path_mapper.mapper.isa(mapper): return True else: return False def contains(self, attributes: Dict[Any, Any], key: Any) -> bool: return (key, self.path) in attributes def __reduce__(self) -> Any: return _unreduce_path, (self.serialize(),) @classmethod def _serialize_path(cls, path: _PathRepresentation) -> _SerializedPath: _m_path = cast(_OddPathRepresentation, path) _p_path = cast(_EvenPathRepresentation, path) return list( zip( tuple( m.class_ if (m.is_mapper or m.is_aliased_class) else str(m) for m in [_m_path[i] for i in range(0, len(_m_path), 2)] ), tuple( p.key if insp_is_mapper_property(p) else str(p) for p in [_p_path[i] for i in range(1, len(_p_path), 2)] ) + (None,), ) ) @classmethod def _deserialize_path(cls, path: _SerializedPath) -> _PathRepresentation: def _deserialize_mapper_token(mcls: Any) -> Any: return ( # note: we likely dont want configure=True here however # this is maintained at the moment for backwards compatibility orm_base._inspect_mapped_class(mcls, configure=True) if mcls not in PathToken._intern else PathToken._intern[mcls] ) def _deserialize_key_token(mcls: Any, key: Any) -> Any: if key is None: return None elif key in PathToken._intern: return PathToken._intern[key] else: mp = orm_base._inspect_mapped_class(mcls, configure=True) assert mp is not None return mp.attrs[key] p = tuple( chain( *[ ( _deserialize_mapper_token(mcls), _deserialize_key_token(mcls, key), ) for mcls, key in path ] ) ) if p and p[-1] is None: p = p[0:-1] return p def serialize(self) -> _SerializedPath: path = self.path return self._serialize_path(path) @classmethod def deserialize(cls, path: _SerializedPath) -> PathRegistry: assert path is not None p = cls._deserialize_path(path) return cls.coerce(p) @overload @classmethod def per_mapper(cls, mapper: Mapper[Any]) -> CachingEntityRegistry: ... @overload @classmethod def per_mapper(cls, mapper: AliasedInsp[Any]) -> SlotsEntityRegistry: ... @classmethod def per_mapper( cls, mapper: _InternalEntityType[Any] ) -> AbstractEntityRegistry: if mapper.is_mapper: return CachingEntityRegistry(cls.root, mapper) else: return SlotsEntityRegistry(cls.root, mapper) @classmethod def coerce(cls, raw: _PathRepresentation) -> PathRegistry: def _red(prev: PathRegistry, next_: _PathElementType) -> PathRegistry: return prev[next_] # can't quite get mypy to appreciate this one :) return reduce(_red, raw, cls.root) # type: ignore def __add__(self, other: PathRegistry) -> PathRegistry: def _red(prev: PathRegistry, next_: _PathElementType) -> PathRegistry: return prev[next_] return reduce(_red, other.path, self) def __str__(self) -> str: return f"ORM Path[{' -> '.join(str(elem) for elem in self.path)}]" def __repr__(self) -> str: return f"{self.__class__.__name__}({self.path!r})" class CreatesToken(PathRegistry): __slots__ = () is_aliased_class: bool is_root: bool def token(self, token: _StrPathToken) -> TokenRegistry: if token.endswith(f":{_WILDCARD_TOKEN}"): return TokenRegistry(self, token) elif token.endswith(f":{_DEFAULT_TOKEN}"): return TokenRegistry(self.root, token) else: raise exc.ArgumentError(f"invalid token: {token}") class RootRegistry(CreatesToken): """Root registry, defers to mappers so that paths are maintained per-root-mapper. """ __slots__ = () inherit_cache = True path = natural_path = () has_entity = False is_aliased_class = False is_root = True is_unnatural = False def _getitem( self, entity: Any ) -> Union[TokenRegistry, AbstractEntityRegistry]: if entity in PathToken._intern: if TYPE_CHECKING: assert isinstance(entity, _StrPathToken) return TokenRegistry(self, PathToken._intern[entity]) else: try: return entity._path_registry # type: ignore except AttributeError: raise IndexError( f"invalid argument for RootRegistry.__getitem__: {entity}" ) def _truncate_recursive(self) -> RootRegistry: return self if not TYPE_CHECKING: __getitem__ = _getitem PathRegistry.root = RootRegistry() class PathToken(orm_base.InspectionAttr, HasCacheKey, str): """cacheable string token""" _intern: Dict[str, PathToken] = {} def _gen_cache_key( self, anon_map: anon_map, bindparams: List[BindParameter[Any]] ) -> Tuple[Any, ...]: return (str(self),) @property def _path_for_compare(self) -> Optional[_PathRepresentation]: return None @classmethod def intern(cls, strvalue: str) -> PathToken: if strvalue in cls._intern: return cls._intern[strvalue] else: cls._intern[strvalue] = result = PathToken(strvalue) return result class TokenRegistry(PathRegistry): __slots__ = ("token", "parent", "path", "natural_path") inherit_cache = True token: _StrPathToken parent: CreatesToken def __init__(self, parent: CreatesToken, token: _StrPathToken): token = PathToken.intern(token) self.token = token self.parent = parent self.path = parent.path + (token,) self.natural_path = parent.natural_path + (token,) has_entity = False is_token = True def generate_for_superclasses(self) -> Iterator[PathRegistry]: # NOTE: this method is no longer used. consider removal parent = self.parent if is_root(parent): yield self return if TYPE_CHECKING: assert isinstance(parent, AbstractEntityRegistry) if not parent.is_aliased_class: for mp_ent in parent.mapper.iterate_to_root(): yield TokenRegistry(parent.parent[mp_ent], self.token) elif ( parent.is_aliased_class and cast( "AliasedInsp[Any]", parent.entity, )._is_with_polymorphic ): yield self for ent in cast( "AliasedInsp[Any]", parent.entity )._with_polymorphic_entities: yield TokenRegistry(parent.parent[ent], self.token) else: yield self def _generate_natural_for_superclasses( self, ) -> Iterator[_PathRepresentation]: parent = self.parent if is_root(parent): yield self.natural_path return if TYPE_CHECKING: assert isinstance(parent, AbstractEntityRegistry) for mp_ent in parent.mapper.iterate_to_root(): yield TokenRegistry(parent.parent[mp_ent], self.token).natural_path if ( parent.is_aliased_class and cast( "AliasedInsp[Any]", parent.entity, )._is_with_polymorphic ): yield self.natural_path for ent in cast( "AliasedInsp[Any]", parent.entity )._with_polymorphic_entities: yield ( TokenRegistry(parent.parent[ent], self.token).natural_path ) else: yield self.natural_path def _getitem(self, entity: Any) -> Any: try: return self.path[entity] except TypeError as err: raise IndexError(f"{entity}") from err if not TYPE_CHECKING: __getitem__ = _getitem class PropRegistry(PathRegistry): __slots__ = ( "prop", "parent", "path", "natural_path", "has_entity", "entity", "mapper", "_wildcard_path_loader_key", "_default_path_loader_key", "_loader_key", "is_unnatural", ) inherit_cache = True is_property = True prop: StrategizedProperty[Any] mapper: Optional[Mapper[Any]] entity: Optional[_InternalEntityType[Any]] def __init__( self, parent: AbstractEntityRegistry, prop: StrategizedProperty[Any] ): # restate this path in terms of the # given StrategizedProperty's parent. insp = cast("_InternalEntityType[Any]", parent[-1]) natural_parent: AbstractEntityRegistry = parent # inherit "is_unnatural" from the parent self.is_unnatural = parent.parent.is_unnatural or bool( parent.mapper.inherits ) if not insp.is_aliased_class or insp._use_mapper_path: # type: ignore parent = natural_parent = parent.parent[prop.parent] elif ( insp.is_aliased_class and insp.with_polymorphic_mappers and prop.parent in insp.with_polymorphic_mappers ): subclass_entity: _InternalEntityType[Any] = parent[-1]._entity_for_mapper(prop.parent) # type: ignore # noqa: E501 parent = parent.parent[subclass_entity] # when building a path where with_polymorphic() is in use, # special logic to determine the "natural path" when subclass # entities are used. # # here we are trying to distinguish between a path that starts # on a with_polymorphic entity vs. one that starts on a # normal entity that introduces a with_polymorphic() in the # middle using of_type(): # # # as in test_polymorphic_rel-> # # test_subqueryload_on_subclass_uses_path_correctly # wp = with_polymorphic(RegularEntity, "*") # sess.query(wp).options(someload(wp.SomeSubEntity.foos)) # # vs # # # as in test_relationship->JoinedloadWPolyOfTypeContinued # wp = with_polymorphic(SomeFoo, "*") # sess.query(RegularEntity).options( # someload(RegularEntity.foos.of_type(wp)) # .someload(wp.SubFoo.bar) # ) # # in the former case, the Query as it generates a path that we # want to match will be in terms of the with_polymorphic at the # beginning. in the latter case, Query will generate simple # paths that don't know about this with_polymorphic, so we must # use a separate natural path. # # if parent.parent: natural_parent = parent.parent[subclass_entity.mapper] self.is_unnatural = True else: natural_parent = parent elif ( natural_parent.parent and insp.is_aliased_class and prop.parent # this should always be the case here is not insp.mapper and insp.mapper.isa(prop.parent) ): natural_parent = parent.parent[prop.parent] self.prop = prop self.parent = parent self.path = parent.path + (prop,) self.natural_path = natural_parent.natural_path + (prop,) self.has_entity = prop._links_to_entity if prop._is_relationship: if TYPE_CHECKING: assert isinstance(prop, RelationshipProperty) self.entity = prop.entity self.mapper = prop.mapper else: self.entity = None self.mapper = None self._wildcard_path_loader_key = ( "loader", parent.natural_path + self.prop._wildcard_token, ) self._default_path_loader_key = self.prop._default_path_loader_key self._loader_key = ("loader", self.natural_path) def _truncate_recursive(self) -> PropRegistry: earliest = None for i, token in enumerate(reversed(self.path[:-1])): if token is self.prop: earliest = i if earliest is None: return self else: return self.coerce(self.path[0 : -(earliest + 1)]) # type: ignore @property def entity_path(self) -> AbstractEntityRegistry: assert self.entity is not None return self[self.entity] def _getitem( self, entity: Union[int, slice, _InternalEntityType[Any]] ) -> Union[AbstractEntityRegistry, _PathElementType, _PathRepresentation]: if isinstance(entity, (int, slice)): return self.path[entity] else: return SlotsEntityRegistry(self, entity) if not TYPE_CHECKING: __getitem__ = _getitem class AbstractEntityRegistry(CreatesToken): __slots__ = ( "key", "parent", "is_aliased_class", "path", "entity", "natural_path", ) has_entity = True is_entity = True parent: Union[RootRegistry, PropRegistry] key: _InternalEntityType[Any] entity: _InternalEntityType[Any] is_aliased_class: bool def __init__( self, parent: Union[RootRegistry, PropRegistry], entity: _InternalEntityType[Any], ): self.key = entity self.parent = parent self.is_aliased_class = entity.is_aliased_class self.entity = entity self.path = parent.path + (entity,) # the "natural path" is the path that we get when Query is traversing # from the lead entities into the various relationships; it corresponds # to the structure of mappers and relationships. when we are given a # path that comes from loader options, as of 1.3 it can have ac-hoc # with_polymorphic() and other AliasedInsp objects inside of it, which # are usually not present in mappings. So here we track both the # "enhanced" path in self.path and the "natural" path that doesn't # include those objects so these two traversals can be matched up. # the test here for "(self.is_aliased_class or parent.is_unnatural)" # are to avoid the more expensive conditional logic that follows if we # know we don't have to do it. This conditional can just as well be # "if parent.path:", it just is more function calls. # # This is basically the only place that the "is_unnatural" flag # actually changes behavior. if parent.path and (self.is_aliased_class or parent.is_unnatural): # this is an infrequent code path used only for loader strategies # that also make use of of_type(). if entity.mapper.isa(parent.natural_path[-1].mapper): # type: ignore # noqa: E501 self.natural_path = parent.natural_path + (entity.mapper,) else: self.natural_path = parent.natural_path + ( parent.natural_path[-1].entity, # type: ignore ) # it seems to make sense that since these paths get mixed up # with statements that are cached or not, we should make # sure the natural path is cacheable across different occurrences # of equivalent AliasedClass objects. however, so far this # does not seem to be needed for whatever reason. # elif not parent.path and self.is_aliased_class: # self.natural_path = (self.entity._generate_cache_key()[0], ) else: self.natural_path = self.path def _truncate_recursive(self) -> AbstractEntityRegistry: return self.parent._truncate_recursive()[self.entity] @property def root_entity(self) -> _InternalEntityType[Any]: return self.odd_element(0) @property def entity_path(self) -> PathRegistry: return self @property def mapper(self) -> Mapper[Any]: return self.entity.mapper def __bool__(self) -> bool: return True def _getitem( self, entity: Any ) -> Union[_PathElementType, _PathRepresentation, PathRegistry]: if isinstance(entity, (int, slice)): return self.path[entity] elif entity in PathToken._intern: return TokenRegistry(self, PathToken._intern[entity]) else: return PropRegistry(self, entity) if not TYPE_CHECKING: __getitem__ = _getitem class SlotsEntityRegistry(AbstractEntityRegistry): # for aliased class, return lightweight, no-cycles created # version inherit_cache = True class _ERDict(Dict[Any, Any]): def __init__(self, registry: CachingEntityRegistry): self.registry = registry def __missing__(self, key: Any) -> PropRegistry: self[key] = item = PropRegistry(self.registry, key) return item class CachingEntityRegistry(AbstractEntityRegistry): # for long lived mapper, return dict based caching # version that creates reference cycles __slots__ = ("_cache",) inherit_cache = True def __init__( self, parent: Union[RootRegistry, PropRegistry], entity: _InternalEntityType[Any], ): super().__init__(parent, entity) self._cache = _ERDict(self) def pop(self, key: Any, default: Any) -> Any: return self._cache.pop(key, default) def _getitem(self, entity: Any) -> Any: if isinstance(entity, (int, slice)): return self.path[entity] elif isinstance(entity, PathToken): return TokenRegistry(self, entity) else: return self._cache[entity] if not TYPE_CHECKING: __getitem__ = _getitem if TYPE_CHECKING: def path_is_entity( path: PathRegistry, ) -> TypeGuard[AbstractEntityRegistry]: ... def path_is_property(path: PathRegistry) -> TypeGuard[PropRegistry]: ... else: path_is_entity = operator.attrgetter("is_entity") path_is_property = operator.attrgetter("is_property") sqlalchemy/orm/identity.py 0000755 00000022041 15125143220 0011703 0 ustar 00 # orm/identity.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php from __future__ import annotations from typing import Any from typing import cast from typing import Dict from typing import Iterable from typing import Iterator from typing import List from typing import NoReturn from typing import Optional from typing import Set from typing import Tuple from typing import TYPE_CHECKING from typing import TypeVar import weakref from . import util as orm_util from .. import exc as sa_exc if TYPE_CHECKING: from ._typing import _IdentityKeyType from .state import InstanceState _T = TypeVar("_T", bound=Any) _O = TypeVar("_O", bound=object) class IdentityMap: _wr: weakref.ref[IdentityMap] _dict: Dict[_IdentityKeyType[Any], Any] _modified: Set[InstanceState[Any]] def __init__(self) -> None: self._dict = {} self._modified = set() self._wr = weakref.ref(self) def _kill(self) -> None: self._add_unpresent = _killed # type: ignore def all_states(self) -> List[InstanceState[Any]]: raise NotImplementedError() def contains_state(self, state: InstanceState[Any]) -> bool: raise NotImplementedError() def __contains__(self, key: _IdentityKeyType[Any]) -> bool: raise NotImplementedError() def safe_discard(self, state: InstanceState[Any]) -> None: raise NotImplementedError() def __getitem__(self, key: _IdentityKeyType[_O]) -> _O: raise NotImplementedError() def get( self, key: _IdentityKeyType[_O], default: Optional[_O] = None ) -> Optional[_O]: raise NotImplementedError() def fast_get_state( self, key: _IdentityKeyType[_O] ) -> Optional[InstanceState[_O]]: raise NotImplementedError() def keys(self) -> Iterable[_IdentityKeyType[Any]]: return self._dict.keys() def values(self) -> Iterable[object]: raise NotImplementedError() def replace(self, state: InstanceState[_O]) -> Optional[InstanceState[_O]]: raise NotImplementedError() def add(self, state: InstanceState[Any]) -> bool: raise NotImplementedError() def _fast_discard(self, state: InstanceState[Any]) -> None: raise NotImplementedError() def _add_unpresent( self, state: InstanceState[Any], key: _IdentityKeyType[Any] ) -> None: """optional inlined form of add() which can assume item isn't present in the map""" self.add(state) def _manage_incoming_state(self, state: InstanceState[Any]) -> None: state._instance_dict = self._wr if state.modified: self._modified.add(state) def _manage_removed_state(self, state: InstanceState[Any]) -> None: del state._instance_dict if state.modified: self._modified.discard(state) def _dirty_states(self) -> Set[InstanceState[Any]]: return self._modified def check_modified(self) -> bool: """return True if any InstanceStates present have been marked as 'modified'. """ return bool(self._modified) def has_key(self, key: _IdentityKeyType[Any]) -> bool: return key in self def __len__(self) -> int: return len(self._dict) class WeakInstanceDict(IdentityMap): _dict: Dict[_IdentityKeyType[Any], InstanceState[Any]] def __getitem__(self, key: _IdentityKeyType[_O]) -> _O: state = cast("InstanceState[_O]", self._dict[key]) o = state.obj() if o is None: raise KeyError(key) return o def __contains__(self, key: _IdentityKeyType[Any]) -> bool: try: if key in self._dict: state = self._dict[key] o = state.obj() else: return False except KeyError: return False else: return o is not None def contains_state(self, state: InstanceState[Any]) -> bool: if state.key in self._dict: if TYPE_CHECKING: assert state.key is not None try: return self._dict[state.key] is state except KeyError: return False else: return False def replace( self, state: InstanceState[Any] ) -> Optional[InstanceState[Any]]: assert state.key is not None if state.key in self._dict: try: existing = existing_non_none = self._dict[state.key] except KeyError: # catch gc removed the key after we just checked for it existing = None else: if existing_non_none is not state: self._manage_removed_state(existing_non_none) else: return None else: existing = None self._dict[state.key] = state self._manage_incoming_state(state) return existing def add(self, state: InstanceState[Any]) -> bool: key = state.key assert key is not None # inline of self.__contains__ if key in self._dict: try: existing_state = self._dict[key] except KeyError: # catch gc removed the key after we just checked for it pass else: if existing_state is not state: o = existing_state.obj() if o is not None: raise sa_exc.InvalidRequestError( "Can't attach instance " "%s; another instance with key %s is already " "present in this session." % (orm_util.state_str(state), state.key) ) else: return False self._dict[key] = state self._manage_incoming_state(state) return True def _add_unpresent( self, state: InstanceState[Any], key: _IdentityKeyType[Any] ) -> None: # inlined form of add() called by loading.py self._dict[key] = state state._instance_dict = self._wr def fast_get_state( self, key: _IdentityKeyType[_O] ) -> Optional[InstanceState[_O]]: return self._dict.get(key) def get( self, key: _IdentityKeyType[_O], default: Optional[_O] = None ) -> Optional[_O]: if key not in self._dict: return default try: state = cast("InstanceState[_O]", self._dict[key]) except KeyError: # catch gc removed the key after we just checked for it return default else: o = state.obj() if o is None: return default return o def items(self) -> List[Tuple[_IdentityKeyType[Any], InstanceState[Any]]]: values = self.all_states() result = [] for state in values: value = state.obj() key = state.key assert key is not None if value is not None: result.append((key, value)) return result def values(self) -> List[object]: values = self.all_states() result = [] for state in values: value = state.obj() if value is not None: result.append(value) return result def __iter__(self) -> Iterator[_IdentityKeyType[Any]]: return iter(self.keys()) def all_states(self) -> List[InstanceState[Any]]: return list(self._dict.values()) def _fast_discard(self, state: InstanceState[Any]) -> None: # used by InstanceState for state being # GC'ed, inlines _managed_removed_state key = state.key assert key is not None try: st = self._dict[key] except KeyError: # catch gc removed the key after we just checked for it pass else: if st is state: self._dict.pop(key, None) def discard(self, state: InstanceState[Any]) -> None: self.safe_discard(state) def safe_discard(self, state: InstanceState[Any]) -> None: key = state.key if key in self._dict: assert key is not None try: st = self._dict[key] except KeyError: # catch gc removed the key after we just checked for it pass else: if st is state: self._dict.pop(key, None) self._manage_removed_state(state) def _killed(state: InstanceState[Any], key: _IdentityKeyType[Any]) -> NoReturn: # external function to avoid creating cycles when assigned to # the IdentityMap raise sa_exc.InvalidRequestError( "Object %s cannot be converted to 'persistent' state, as this " "identity map is no longer valid. Has the owning Session " "been closed?" % orm_util.state_str(state), code="lkrp", ) sqlalchemy/orm/properties.py 0000755 00000071475 15125143220 0012265 0 ustar 00 # orm/properties.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """MapperProperty implementations. This is a private module which defines the behavior of individual ORM- mapped attributes. """ from __future__ import annotations from typing import Any from typing import cast from typing import Dict from typing import List from typing import Optional from typing import Sequence from typing import Set from typing import Tuple from typing import Type from typing import TYPE_CHECKING from typing import TypeVar from typing import Union from . import attributes from . import exc as orm_exc from . import strategy_options from .base import _DeclarativeMapped from .base import class_mapper from .descriptor_props import CompositeProperty from .descriptor_props import ConcreteInheritedProperty from .descriptor_props import SynonymProperty from .interfaces import _AttributeOptions from .interfaces import _DEFAULT_ATTRIBUTE_OPTIONS from .interfaces import _IntrospectsAnnotations from .interfaces import _MapsColumns from .interfaces import MapperProperty from .interfaces import PropComparator from .interfaces import StrategizedProperty from .relationships import RelationshipProperty from .util import de_stringify_annotation from .. import exc as sa_exc from .. import ForeignKey from .. import log from .. import util from ..sql import coercions from ..sql import roles from ..sql.base import _NoArg from ..sql.schema import Column from ..sql.schema import SchemaConst from ..sql.type_api import TypeEngine from ..util.typing import de_optionalize_union_types from ..util.typing import get_args from ..util.typing import includes_none from ..util.typing import is_a_type from ..util.typing import is_fwd_ref from ..util.typing import is_pep593 from ..util.typing import is_pep695 from ..util.typing import Self if TYPE_CHECKING: from ._typing import _IdentityKeyType from ._typing import _InstanceDict from ._typing import _ORMColumnExprArgument from ._typing import _RegistryType from .base import Mapped from .decl_base import _ClassScanMapperConfig from .mapper import Mapper from .session import Session from .state import _InstallLoaderCallableProto from .state import InstanceState from ..sql._typing import _InfoType from ..sql.elements import ColumnElement from ..sql.elements import NamedColumn from ..sql.operators import OperatorType from ..util.typing import _AnnotationScanType from ..util.typing import RODescriptorReference _T = TypeVar("_T", bound=Any) _PT = TypeVar("_PT", bound=Any) _NC = TypeVar("_NC", bound="NamedColumn[Any]") __all__ = [ "ColumnProperty", "CompositeProperty", "ConcreteInheritedProperty", "RelationshipProperty", "SynonymProperty", ] @log.class_logger class ColumnProperty( _MapsColumns[_T], StrategizedProperty[_T], _IntrospectsAnnotations, log.Identified, ): """Describes an object attribute that corresponds to a table column or other column expression. Public constructor is the :func:`_orm.column_property` function. """ strategy_wildcard_key = strategy_options._COLUMN_TOKEN inherit_cache = True """:meta private:""" _links_to_entity = False columns: List[NamedColumn[Any]] _is_polymorphic_discriminator: bool _mapped_by_synonym: Optional[str] comparator_factory: Type[PropComparator[_T]] __slots__ = ( "columns", "group", "deferred", "instrument", "comparator_factory", "active_history", "expire_on_flush", "_creation_order", "_is_polymorphic_discriminator", "_mapped_by_synonym", "_deferred_column_loader", "_raise_column_loader", "_renders_in_subqueries", "raiseload", ) def __init__( self, column: _ORMColumnExprArgument[_T], *additional_columns: _ORMColumnExprArgument[Any], attribute_options: Optional[_AttributeOptions] = None, group: Optional[str] = None, deferred: bool = False, raiseload: bool = False, comparator_factory: Optional[Type[PropComparator[_T]]] = None, active_history: bool = False, expire_on_flush: bool = True, info: Optional[_InfoType] = None, doc: Optional[str] = None, _instrument: bool = True, _assume_readonly_dc_attributes: bool = False, ): super().__init__( attribute_options=attribute_options, _assume_readonly_dc_attributes=_assume_readonly_dc_attributes, ) columns = (column,) + additional_columns self.columns = [ coercions.expect(roles.LabeledColumnExprRole, c) for c in columns ] self.group = group self.deferred = deferred self.raiseload = raiseload self.instrument = _instrument self.comparator_factory = ( comparator_factory if comparator_factory is not None else self.__class__.Comparator ) self.active_history = active_history self.expire_on_flush = expire_on_flush if info is not None: self.info.update(info) if doc is not None: self.doc = doc else: for col in reversed(self.columns): doc = getattr(col, "doc", None) if doc is not None: self.doc = doc break else: self.doc = None util.set_creation_order(self) self.strategy_key = ( ("deferred", self.deferred), ("instrument", self.instrument), ) if self.raiseload: self.strategy_key += (("raiseload", True),) def declarative_scan( self, decl_scan: _ClassScanMapperConfig, registry: _RegistryType, cls: Type[Any], originating_module: Optional[str], key: str, mapped_container: Optional[Type[Mapped[Any]]], annotation: Optional[_AnnotationScanType], extracted_mapped_annotation: Optional[_AnnotationScanType], is_dataclass_field: bool, ) -> None: column = self.columns[0] if column.key is None: column.key = key if column.name is None: column.name = key @property def mapper_property_to_assign(self) -> Optional[MapperProperty[_T]]: return self @property def columns_to_assign(self) -> List[Tuple[Column[Any], int]]: # mypy doesn't care about the isinstance here return [ (c, 0) # type: ignore for c in self.columns if isinstance(c, Column) and c.table is None ] def _memoized_attr__renders_in_subqueries(self) -> bool: if ("query_expression", True) in self.strategy_key: return self.strategy._have_default_expression # type: ignore return ("deferred", True) not in self.strategy_key or ( self not in self.parent._readonly_props # type: ignore ) @util.preload_module("sqlalchemy.orm.state", "sqlalchemy.orm.strategies") def _memoized_attr__deferred_column_loader( self, ) -> _InstallLoaderCallableProto[Any]: state = util.preloaded.orm_state strategies = util.preloaded.orm_strategies return state.InstanceState._instance_level_callable_processor( self.parent.class_manager, strategies.LoadDeferredColumns(self.key), self.key, ) @util.preload_module("sqlalchemy.orm.state", "sqlalchemy.orm.strategies") def _memoized_attr__raise_column_loader( self, ) -> _InstallLoaderCallableProto[Any]: state = util.preloaded.orm_state strategies = util.preloaded.orm_strategies return state.InstanceState._instance_level_callable_processor( self.parent.class_manager, strategies.LoadDeferredColumns(self.key, True), self.key, ) def __clause_element__(self) -> roles.ColumnsClauseRole: """Allow the ColumnProperty to work in expression before it is turned into an instrumented attribute. """ return self.expression @property def expression(self) -> roles.ColumnsClauseRole: """Return the primary column or expression for this ColumnProperty. E.g.:: class File(Base): # ... name = Column(String(64)) extension = Column(String(8)) filename = column_property(name + "." + extension) path = column_property("C:/" + filename.expression) .. seealso:: :ref:`mapper_column_property_sql_expressions_composed` """ return self.columns[0] def instrument_class(self, mapper: Mapper[Any]) -> None: if not self.instrument: return attributes.register_descriptor( mapper.class_, self.key, comparator=self.comparator_factory(self, mapper), parententity=mapper, doc=self.doc, ) def do_init(self) -> None: super().do_init() if len(self.columns) > 1 and set(self.parent.primary_key).issuperset( self.columns ): util.warn( ( "On mapper %s, primary key column '%s' is being combined " "with distinct primary key column '%s' in attribute '%s'. " "Use explicit properties to give each column its own " "mapped attribute name." ) % (self.parent, self.columns[1], self.columns[0], self.key) ) def copy(self) -> ColumnProperty[_T]: return ColumnProperty( *self.columns, deferred=self.deferred, group=self.group, active_history=self.active_history, ) def merge( self, session: Session, source_state: InstanceState[Any], source_dict: _InstanceDict, dest_state: InstanceState[Any], dest_dict: _InstanceDict, load: bool, _recursive: Dict[Any, object], _resolve_conflict_map: Dict[_IdentityKeyType[Any], object], ) -> None: if not self.instrument: return elif self.key in source_dict: value = source_dict[self.key] if not load: dest_dict[self.key] = value else: impl = dest_state.get_impl(self.key) impl.set(dest_state, dest_dict, value, None) elif dest_state.has_identity and self.key not in dest_dict: dest_state._expire_attributes( dest_dict, [self.key], no_loader=True ) class Comparator(util.MemoizedSlots, PropComparator[_PT]): """Produce boolean, comparison, and other operators for :class:`.ColumnProperty` attributes. See the documentation for :class:`.PropComparator` for a brief overview. .. seealso:: :class:`.PropComparator` :class:`.ColumnOperators` :ref:`types_operators` :attr:`.TypeEngine.comparator_factory` """ if not TYPE_CHECKING: # prevent pylance from being clever about slots __slots__ = "__clause_element__", "info", "expressions" prop: RODescriptorReference[ColumnProperty[_PT]] expressions: Sequence[NamedColumn[Any]] """The full sequence of columns referenced by this attribute, adjusted for any aliasing in progress. .. versionadded:: 1.3.17 .. seealso:: :ref:`maptojoin` - usage example """ def _orm_annotate_column(self, column: _NC) -> _NC: """annotate and possibly adapt a column to be returned as the mapped-attribute exposed version of the column. The column in this context needs to act as much like the column in an ORM mapped context as possible, so includes annotations to give hints to various ORM functions as to the source entity of this column. It also adapts it to the mapper's with_polymorphic selectable if one is present. """ pe = self._parententity annotations: Dict[str, Any] = { "entity_namespace": pe, "parententity": pe, "parentmapper": pe, "proxy_key": self.prop.key, } col = column # for a mapper with polymorphic_on and an adapter, return # the column against the polymorphic selectable. # see also orm.util._orm_downgrade_polymorphic_columns # for the reverse operation. if self._parentmapper._polymorphic_adapter: mapper_local_col = col col = self._parentmapper._polymorphic_adapter.traverse(col) # this is a clue to the ORM Query etc. that this column # was adapted to the mapper's polymorphic_adapter. the # ORM uses this hint to know which column its adapting. annotations["adapt_column"] = mapper_local_col return col._annotate(annotations)._set_propagate_attrs( {"compile_state_plugin": "orm", "plugin_subject": pe} ) if TYPE_CHECKING: def __clause_element__(self) -> NamedColumn[_PT]: ... def _memoized_method___clause_element__( self, ) -> NamedColumn[_PT]: if self.adapter: return self.adapter(self.prop.columns[0], self.prop.key) else: return self._orm_annotate_column(self.prop.columns[0]) def _memoized_attr_info(self) -> _InfoType: """The .info dictionary for this attribute.""" ce = self.__clause_element__() try: return ce.info # type: ignore except AttributeError: return self.prop.info def _memoized_attr_expressions(self) -> Sequence[NamedColumn[Any]]: """The full sequence of columns referenced by this attribute, adjusted for any aliasing in progress. .. versionadded:: 1.3.17 """ if self.adapter: return [ self.adapter(col, self.prop.key) for col in self.prop.columns ] else: return [ self._orm_annotate_column(col) for col in self.prop.columns ] def _fallback_getattr(self, key: str) -> Any: """proxy attribute access down to the mapped column. this allows user-defined comparison methods to be accessed. """ return getattr(self.__clause_element__(), key) def operate( self, op: OperatorType, *other: Any, **kwargs: Any ) -> ColumnElement[Any]: return op(self.__clause_element__(), *other, **kwargs) # type: ignore[no-any-return] # noqa: E501 def reverse_operate( self, op: OperatorType, other: Any, **kwargs: Any ) -> ColumnElement[Any]: col = self.__clause_element__() return op(col._bind_param(op, other), col, **kwargs) # type: ignore[no-any-return] # noqa: E501 def __str__(self) -> str: if not self.parent or not self.key: return object.__repr__(self) return str(self.parent.class_.__name__) + "." + self.key class MappedSQLExpression(ColumnProperty[_T], _DeclarativeMapped[_T]): """Declarative front-end for the :class:`.ColumnProperty` class. Public constructor is the :func:`_orm.column_property` function. .. versionchanged:: 2.0 Added :class:`_orm.MappedSQLExpression` as a Declarative compatible subclass for :class:`_orm.ColumnProperty`. .. seealso:: :class:`.MappedColumn` """ inherit_cache = True """:meta private:""" class MappedColumn( _IntrospectsAnnotations, _MapsColumns[_T], _DeclarativeMapped[_T], ): """Maps a single :class:`_schema.Column` on a class. :class:`_orm.MappedColumn` is a specialization of the :class:`_orm.ColumnProperty` class and is oriented towards declarative configuration. To construct :class:`_orm.MappedColumn` objects, use the :func:`_orm.mapped_column` constructor function. .. versionadded:: 2.0 """ __slots__ = ( "column", "_creation_order", "_sort_order", "foreign_keys", "_has_nullable", "_has_insert_default", "deferred", "deferred_group", "deferred_raiseload", "active_history", "_attribute_options", "_has_dataclass_arguments", "_use_existing_column", ) deferred: Union[_NoArg, bool] deferred_raiseload: bool deferred_group: Optional[str] column: Column[_T] foreign_keys: Optional[Set[ForeignKey]] _attribute_options: _AttributeOptions def __init__(self, *arg: Any, **kw: Any): self._attribute_options = attr_opts = kw.pop( "attribute_options", _DEFAULT_ATTRIBUTE_OPTIONS ) self._use_existing_column = kw.pop("use_existing_column", False) self._has_dataclass_arguments = ( attr_opts is not None and attr_opts != _DEFAULT_ATTRIBUTE_OPTIONS and any( attr_opts[i] is not _NoArg.NO_ARG for i, attr in enumerate(attr_opts._fields) if attr != "dataclasses_default" ) ) insert_default = kw.pop("insert_default", _NoArg.NO_ARG) self._has_insert_default = insert_default is not _NoArg.NO_ARG if self._has_insert_default: kw["default"] = insert_default elif attr_opts.dataclasses_default is not _NoArg.NO_ARG: kw["default"] = attr_opts.dataclasses_default self.deferred_group = kw.pop("deferred_group", None) self.deferred_raiseload = kw.pop("deferred_raiseload", None) self.deferred = kw.pop("deferred", _NoArg.NO_ARG) self.active_history = kw.pop("active_history", False) self._sort_order = kw.pop("sort_order", _NoArg.NO_ARG) self.column = cast("Column[_T]", Column(*arg, **kw)) self.foreign_keys = self.column.foreign_keys self._has_nullable = "nullable" in kw and kw.get("nullable") not in ( None, SchemaConst.NULL_UNSPECIFIED, ) util.set_creation_order(self) def _copy(self, **kw: Any) -> Self: new = self.__class__.__new__(self.__class__) new.column = self.column._copy(**kw) new.deferred = self.deferred new.deferred_group = self.deferred_group new.deferred_raiseload = self.deferred_raiseload new.foreign_keys = new.column.foreign_keys new.active_history = self.active_history new._has_nullable = self._has_nullable new._attribute_options = self._attribute_options new._has_insert_default = self._has_insert_default new._has_dataclass_arguments = self._has_dataclass_arguments new._use_existing_column = self._use_existing_column new._sort_order = self._sort_order util.set_creation_order(new) return new @property def name(self) -> str: return self.column.name @property def mapper_property_to_assign(self) -> Optional[MapperProperty[_T]]: effective_deferred = self.deferred if effective_deferred is _NoArg.NO_ARG: effective_deferred = bool( self.deferred_group or self.deferred_raiseload ) if effective_deferred or self.active_history: return ColumnProperty( self.column, deferred=effective_deferred, group=self.deferred_group, raiseload=self.deferred_raiseload, attribute_options=self._attribute_options, active_history=self.active_history, ) else: return None @property def columns_to_assign(self) -> List[Tuple[Column[Any], int]]: return [ ( self.column, ( self._sort_order if self._sort_order is not _NoArg.NO_ARG else 0 ), ) ] def __clause_element__(self) -> Column[_T]: return self.column def operate( self, op: OperatorType, *other: Any, **kwargs: Any ) -> ColumnElement[Any]: return op(self.__clause_element__(), *other, **kwargs) # type: ignore[no-any-return] # noqa: E501 def reverse_operate( self, op: OperatorType, other: Any, **kwargs: Any ) -> ColumnElement[Any]: col = self.__clause_element__() return op(col._bind_param(op, other), col, **kwargs) # type: ignore[no-any-return] # noqa: E501 def found_in_pep593_annotated(self) -> Any: # return a blank mapped_column(). This mapped_column()'s # Column will be merged into it in _init_column_for_annotation(). return MappedColumn() def declarative_scan( self, decl_scan: _ClassScanMapperConfig, registry: _RegistryType, cls: Type[Any], originating_module: Optional[str], key: str, mapped_container: Optional[Type[Mapped[Any]]], annotation: Optional[_AnnotationScanType], extracted_mapped_annotation: Optional[_AnnotationScanType], is_dataclass_field: bool, ) -> None: column = self.column if ( self._use_existing_column and decl_scan.inherits and decl_scan.single ): if decl_scan.is_deferred: raise sa_exc.ArgumentError( "Can't use use_existing_column with deferred mappers" ) supercls_mapper = class_mapper(decl_scan.inherits, False) colname = column.name if column.name is not None else key column = self.column = supercls_mapper.local_table.c.get( # type: ignore[assignment] # noqa: E501 colname, column ) if column.key is None: column.key = key if column.name is None: column.name = key sqltype = column.type if extracted_mapped_annotation is None: if sqltype._isnull and not self.column.foreign_keys: self._raise_for_required(key, cls) else: return self._init_column_for_annotation( cls, registry, extracted_mapped_annotation, originating_module, ) @util.preload_module("sqlalchemy.orm.decl_base") def declarative_scan_for_composite( self, registry: _RegistryType, cls: Type[Any], originating_module: Optional[str], key: str, param_name: str, param_annotation: _AnnotationScanType, ) -> None: decl_base = util.preloaded.orm_decl_base decl_base._undefer_column_name(param_name, self.column) self._init_column_for_annotation( cls, registry, param_annotation, originating_module ) def _init_column_for_annotation( self, cls: Type[Any], registry: _RegistryType, argument: _AnnotationScanType, originating_module: Optional[str], ) -> None: sqltype = self.column.type if is_fwd_ref( argument, check_generic=True, check_for_plain_string=True ): assert originating_module is not None argument = de_stringify_annotation( cls, argument, originating_module, include_generic=True ) nullable = includes_none(argument) if not self._has_nullable: self.column.nullable = nullable our_type = de_optionalize_union_types(argument) find_mapped_in: Tuple[Any, ...] = () our_type_is_pep593 = False raw_pep_593_type = None if is_pep593(our_type): our_type_is_pep593 = True pep_593_components = get_args(our_type) raw_pep_593_type = pep_593_components[0] if nullable: raw_pep_593_type = de_optionalize_union_types(raw_pep_593_type) find_mapped_in = pep_593_components[1:] elif is_pep695(argument) and is_pep593(argument.__value__): # do not support nested annotation inside unions ets find_mapped_in = get_args(argument.__value__)[1:] use_args_from: Optional[MappedColumn[Any]] for elem in find_mapped_in: if isinstance(elem, MappedColumn): use_args_from = elem break else: use_args_from = None if use_args_from is not None: if ( not self._has_insert_default and use_args_from.column.default is not None ): self.column.default = None use_args_from.column._merge(self.column) sqltype = self.column.type if ( use_args_from.deferred is not _NoArg.NO_ARG and self.deferred is _NoArg.NO_ARG ): self.deferred = use_args_from.deferred if ( use_args_from.deferred_group is not None and self.deferred_group is None ): self.deferred_group = use_args_from.deferred_group if ( use_args_from.deferred_raiseload is not None and self.deferred_raiseload is None ): self.deferred_raiseload = use_args_from.deferred_raiseload if ( use_args_from._use_existing_column and not self._use_existing_column ): self._use_existing_column = True if use_args_from.active_history: self.active_history = use_args_from.active_history if ( use_args_from._sort_order is not None and self._sort_order is _NoArg.NO_ARG ): self._sort_order = use_args_from._sort_order if ( use_args_from.column.key is not None or use_args_from.column.name is not None ): util.warn_deprecated( "Can't use the 'key' or 'name' arguments in " "Annotated with mapped_column(); this will be ignored", "2.0.22", ) if use_args_from._has_dataclass_arguments: for idx, arg in enumerate( use_args_from._attribute_options._fields ): if ( use_args_from._attribute_options[idx] is not _NoArg.NO_ARG ): arg = arg.replace("dataclasses_", "") util.warn_deprecated( f"Argument '{arg}' is a dataclass argument and " "cannot be specified within a mapped_column() " "bundled inside of an Annotated object", "2.0.22", ) if sqltype._isnull and not self.column.foreign_keys: checks: List[Any] if our_type_is_pep593: checks = [our_type, raw_pep_593_type] else: checks = [our_type] for check_type in checks: new_sqltype = registry._resolve_type(check_type) if new_sqltype is not None: break else: if isinstance(our_type, TypeEngine) or ( isinstance(our_type, type) and issubclass(our_type, TypeEngine) ): raise orm_exc.MappedAnnotationError( f"The type provided inside the {self.column.key!r} " "attribute Mapped annotation is the SQLAlchemy type " f"{our_type}. Expected a Python type instead" ) elif is_a_type(our_type): raise orm_exc.MappedAnnotationError( "Could not locate SQLAlchemy Core type for Python " f"type {our_type} inside the {self.column.key!r} " "attribute Mapped annotation" ) else: raise orm_exc.MappedAnnotationError( f"The object provided inside the {self.column.key!r} " "attribute Mapped annotation is not a Python type, " f"it's the object {our_type!r}. Expected a Python " "type." ) self.column._set_type(new_sqltype) sqlalchemy/orm/instrumentation.py 0000755 00000057401 15125143220 0013325 0 ustar 00 # orm/instrumentation.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: allow-untyped-defs, allow-untyped-calls """Defines SQLAlchemy's system of class instrumentation. This module is usually not directly visible to user applications, but defines a large part of the ORM's interactivity. instrumentation.py deals with registration of end-user classes for state tracking. It interacts closely with state.py and attributes.py which establish per-instance and per-class-attribute instrumentation, respectively. The class instrumentation system can be customized on a per-class or global basis using the :mod:`sqlalchemy.ext.instrumentation` module, which provides the means to build and specify alternate instrumentation forms. .. versionchanged: 0.8 The instrumentation extension system was moved out of the ORM and into the external :mod:`sqlalchemy.ext.instrumentation` package. When that package is imported, it installs itself within sqlalchemy.orm so that its more comprehensive resolution mechanics take effect. """ from __future__ import annotations from typing import Any from typing import Callable from typing import cast from typing import Collection from typing import Dict from typing import Generic from typing import Iterable from typing import List from typing import Optional from typing import Set from typing import Tuple from typing import Type from typing import TYPE_CHECKING from typing import TypeVar from typing import Union import weakref from . import base from . import collections from . import exc from . import interfaces from . import state from ._typing import _O from .attributes import _is_collection_attribute_impl from .. import util from ..event import EventTarget from ..util import HasMemoized from ..util.typing import Literal from ..util.typing import Protocol if TYPE_CHECKING: from ._typing import _RegistryType from .attributes import AttributeImpl from .attributes import QueryableAttribute from .collections import _AdaptedCollectionProtocol from .collections import _CollectionFactoryType from .decl_base import _MapperConfig from .events import InstanceEvents from .mapper import Mapper from .state import InstanceState from ..event import dispatcher _T = TypeVar("_T", bound=Any) DEL_ATTR = util.symbol("DEL_ATTR") class _ExpiredAttributeLoaderProto(Protocol): def __call__( self, state: state.InstanceState[Any], toload: Set[str], passive: base.PassiveFlag, ) -> None: ... class _ManagerFactory(Protocol): def __call__(self, class_: Type[_O]) -> ClassManager[_O]: ... class ClassManager( HasMemoized, Dict[str, "QueryableAttribute[Any]"], Generic[_O], EventTarget, ): """Tracks state information at the class level.""" dispatch: dispatcher[ClassManager[_O]] MANAGER_ATTR = base.DEFAULT_MANAGER_ATTR STATE_ATTR = base.DEFAULT_STATE_ATTR _state_setter = staticmethod(util.attrsetter(STATE_ATTR)) expired_attribute_loader: _ExpiredAttributeLoaderProto "previously known as deferred_scalar_loader" init_method: Optional[Callable[..., None]] original_init: Optional[Callable[..., None]] = None factory: Optional[_ManagerFactory] declarative_scan: Optional[weakref.ref[_MapperConfig]] = None registry: _RegistryType if not TYPE_CHECKING: # starts as None during setup registry = None class_: Type[_O] _bases: List[ClassManager[Any]] @property @util.deprecated( "1.4", message="The ClassManager.deferred_scalar_loader attribute is now " "named expired_attribute_loader", ) def deferred_scalar_loader(self): return self.expired_attribute_loader @deferred_scalar_loader.setter @util.deprecated( "1.4", message="The ClassManager.deferred_scalar_loader attribute is now " "named expired_attribute_loader", ) def deferred_scalar_loader(self, obj): self.expired_attribute_loader = obj def __init__(self, class_): self.class_ = class_ self.info = {} self.new_init = None self.local_attrs = {} self.originals = {} self._finalized = False self.factory = None self.init_method = None self._bases = [ mgr for mgr in cast( "List[Optional[ClassManager[Any]]]", [ opt_manager_of_class(base) for base in self.class_.__bases__ if isinstance(base, type) ], ) if mgr is not None ] for base_ in self._bases: self.update(base_) cast( "InstanceEvents", self.dispatch._events )._new_classmanager_instance(class_, self) for basecls in class_.__mro__: mgr = opt_manager_of_class(basecls) if mgr is not None: self.dispatch._update(mgr.dispatch) self.manage() if "__del__" in class_.__dict__: util.warn( "__del__() method on class %s will " "cause unreachable cycles and memory leaks, " "as SQLAlchemy instrumentation often creates " "reference cycles. Please remove this method." % class_ ) def _update_state( self, finalize: bool = False, mapper: Optional[Mapper[_O]] = None, registry: Optional[_RegistryType] = None, declarative_scan: Optional[_MapperConfig] = None, expired_attribute_loader: Optional[ _ExpiredAttributeLoaderProto ] = None, init_method: Optional[Callable[..., None]] = None, ) -> None: if mapper: self.mapper = mapper # if registry: registry._add_manager(self) if declarative_scan: self.declarative_scan = weakref.ref(declarative_scan) if expired_attribute_loader: self.expired_attribute_loader = expired_attribute_loader if init_method: assert not self._finalized, ( "class is already instrumented, " "init_method %s can't be applied" % init_method ) self.init_method = init_method if not self._finalized: self.original_init = ( self.init_method if self.init_method is not None and self.class_.__init__ is object.__init__ else self.class_.__init__ ) if finalize and not self._finalized: self._finalize() def _finalize(self) -> None: if self._finalized: return self._finalized = True self._instrument_init() _instrumentation_factory.dispatch.class_instrument(self.class_) def __hash__(self) -> int: # type: ignore[override] return id(self) def __eq__(self, other: Any) -> bool: return other is self @property def is_mapped(self) -> bool: return "mapper" in self.__dict__ @HasMemoized.memoized_attribute def _all_key_set(self): return frozenset(self) @HasMemoized.memoized_attribute def _collection_impl_keys(self): return frozenset( [attr.key for attr in self.values() if attr.impl.collection] ) @HasMemoized.memoized_attribute def _scalar_loader_impls(self): return frozenset( [ attr.impl for attr in self.values() if attr.impl.accepts_scalar_loader ] ) @HasMemoized.memoized_attribute def _loader_impls(self): return frozenset([attr.impl for attr in self.values()]) @util.memoized_property def mapper(self) -> Mapper[_O]: # raises unless self.mapper has been assigned raise exc.UnmappedClassError(self.class_) def _all_sqla_attributes(self, exclude=None): """return an iterator of all classbound attributes that are implement :class:`.InspectionAttr`. This includes :class:`.QueryableAttribute` as well as extension types such as :class:`.hybrid_property` and :class:`.AssociationProxy`. """ found: Dict[str, Any] = {} # constraints: # 1. yield keys in cls.__dict__ order # 2. if a subclass has the same key as a superclass, include that # key as part of the ordering of the superclass, because an # overridden key is usually installed by the mapper which is going # on a different ordering # 3. don't use getattr() as this fires off descriptors for supercls in self.class_.__mro__[0:-1]: inherits = supercls.__mro__[1] for key in supercls.__dict__: found.setdefault(key, supercls) if key in inherits.__dict__: continue val = found[key].__dict__[key] if ( isinstance(val, interfaces.InspectionAttr) and val.is_attribute ): yield key, val def _get_class_attr_mro(self, key, default=None): """return an attribute on the class without tripping it.""" for supercls in self.class_.__mro__: if key in supercls.__dict__: return supercls.__dict__[key] else: return default def _attr_has_impl(self, key: str) -> bool: """Return True if the given attribute is fully initialized. i.e. has an impl. """ return key in self and self[key].impl is not None def _subclass_manager(self, cls: Type[_T]) -> ClassManager[_T]: """Create a new ClassManager for a subclass of this ClassManager's class. This is called automatically when attributes are instrumented so that the attributes can be propagated to subclasses against their own class-local manager, without the need for mappers etc. to have already pre-configured managers for the full class hierarchy. Mappers can post-configure the auto-generated ClassManager when needed. """ return register_class(cls, finalize=False) def _instrument_init(self): self.new_init = _generate_init(self.class_, self, self.original_init) self.install_member("__init__", self.new_init) @util.memoized_property def _state_constructor(self) -> Type[state.InstanceState[_O]]: self.dispatch.first_init(self, self.class_) return state.InstanceState def manage(self): """Mark this instance as the manager for its class.""" setattr(self.class_, self.MANAGER_ATTR, self) @util.hybridmethod def manager_getter(self): return _default_manager_getter @util.hybridmethod def state_getter(self): """Return a (instance) -> InstanceState callable. "state getter" callables should raise either KeyError or AttributeError if no InstanceState could be found for the instance. """ return _default_state_getter @util.hybridmethod def dict_getter(self): return _default_dict_getter def instrument_attribute( self, key: str, inst: QueryableAttribute[Any], propagated: bool = False, ) -> None: if propagated: if key in self.local_attrs: return # don't override local attr with inherited attr else: self.local_attrs[key] = inst self.install_descriptor(key, inst) self._reset_memoizations() self[key] = inst for cls in self.class_.__subclasses__(): manager = self._subclass_manager(cls) manager.instrument_attribute(key, inst, True) def subclass_managers(self, recursive): for cls in self.class_.__subclasses__(): mgr = opt_manager_of_class(cls) if mgr is not None and mgr is not self: yield mgr if recursive: yield from mgr.subclass_managers(True) def post_configure_attribute(self, key): _instrumentation_factory.dispatch.attribute_instrument( self.class_, key, self[key] ) def uninstrument_attribute(self, key, propagated=False): if key not in self: return if propagated: if key in self.local_attrs: return # don't get rid of local attr else: del self.local_attrs[key] self.uninstall_descriptor(key) self._reset_memoizations() del self[key] for cls in self.class_.__subclasses__(): manager = opt_manager_of_class(cls) if manager: manager.uninstrument_attribute(key, True) def unregister(self) -> None: """remove all instrumentation established by this ClassManager.""" for key in list(self.originals): self.uninstall_member(key) self.mapper = None self.dispatch = None # type: ignore self.new_init = None self.info.clear() for key in list(self): if key in self.local_attrs: self.uninstrument_attribute(key) if self.MANAGER_ATTR in self.class_.__dict__: delattr(self.class_, self.MANAGER_ATTR) def install_descriptor( self, key: str, inst: QueryableAttribute[Any] ) -> None: if key in (self.STATE_ATTR, self.MANAGER_ATTR): raise KeyError( "%r: requested attribute name conflicts with " "instrumentation attribute of the same name." % key ) setattr(self.class_, key, inst) def uninstall_descriptor(self, key: str) -> None: delattr(self.class_, key) def install_member(self, key: str, implementation: Any) -> None: if key in (self.STATE_ATTR, self.MANAGER_ATTR): raise KeyError( "%r: requested attribute name conflicts with " "instrumentation attribute of the same name." % key ) self.originals.setdefault(key, self.class_.__dict__.get(key, DEL_ATTR)) setattr(self.class_, key, implementation) def uninstall_member(self, key: str) -> None: original = self.originals.pop(key, None) if original is not DEL_ATTR: setattr(self.class_, key, original) else: delattr(self.class_, key) def instrument_collection_class( self, key: str, collection_class: Type[Collection[Any]] ) -> _CollectionFactoryType: return collections.prepare_instrumentation(collection_class) def initialize_collection( self, key: str, state: InstanceState[_O], factory: _CollectionFactoryType, ) -> Tuple[collections.CollectionAdapter, _AdaptedCollectionProtocol]: user_data = factory() impl = self.get_impl(key) assert _is_collection_attribute_impl(impl) adapter = collections.CollectionAdapter(impl, state, user_data) return adapter, user_data def is_instrumented(self, key: str, search: bool = False) -> bool: if search: return key in self else: return key in self.local_attrs def get_impl(self, key: str) -> AttributeImpl: return self[key].impl @property def attributes(self) -> Iterable[Any]: return iter(self.values()) # InstanceState management def new_instance(self, state: Optional[InstanceState[_O]] = None) -> _O: # here, we would prefer _O to be bound to "object" # so that mypy sees that __new__ is present. currently # it's bound to Any as there were other problems not having # it that way but these can be revisited instance = self.class_.__new__(self.class_) if state is None: state = self._state_constructor(instance, self) self._state_setter(instance, state) return instance def setup_instance( self, instance: _O, state: Optional[InstanceState[_O]] = None ) -> None: if state is None: state = self._state_constructor(instance, self) self._state_setter(instance, state) def teardown_instance(self, instance: _O) -> None: delattr(instance, self.STATE_ATTR) def _serialize( self, state: InstanceState[_O], state_dict: Dict[str, Any] ) -> _SerializeManager: return _SerializeManager(state, state_dict) def _new_state_if_none( self, instance: _O ) -> Union[Literal[False], InstanceState[_O]]: """Install a default InstanceState if none is present. A private convenience method used by the __init__ decorator. """ if hasattr(instance, self.STATE_ATTR): return False elif self.class_ is not instance.__class__ and self.is_mapped: # this will create a new ClassManager for the # subclass, without a mapper. This is likely a # user error situation but allow the object # to be constructed, so that it is usable # in a non-ORM context at least. return self._subclass_manager( instance.__class__ )._new_state_if_none(instance) else: state = self._state_constructor(instance, self) self._state_setter(instance, state) return state def has_state(self, instance: _O) -> bool: return hasattr(instance, self.STATE_ATTR) def has_parent( self, state: InstanceState[_O], key: str, optimistic: bool = False ) -> bool: """TODO""" return self.get_impl(key).hasparent(state, optimistic=optimistic) def __bool__(self) -> bool: """All ClassManagers are non-zero regardless of attribute state.""" return True def __repr__(self) -> str: return "<%s of %r at %x>" % ( self.__class__.__name__, self.class_, id(self), ) class _SerializeManager: """Provide serialization of a :class:`.ClassManager`. The :class:`.InstanceState` uses ``__init__()`` on serialize and ``__call__()`` on deserialize. """ def __init__(self, state: state.InstanceState[Any], d: Dict[str, Any]): self.class_ = state.class_ manager = state.manager manager.dispatch.pickle(state, d) def __call__(self, state, inst, state_dict): state.manager = manager = opt_manager_of_class(self.class_) if manager is None: raise exc.UnmappedInstanceError( inst, "Cannot deserialize object of type %r - " "no mapper() has " "been configured for this class within the current " "Python process!" % self.class_, ) elif manager.is_mapped and not manager.mapper.configured: manager.mapper._check_configure() # setup _sa_instance_state ahead of time so that # unpickle events can access the object normally. # see [ticket:2362] if inst is not None: manager.setup_instance(inst, state) manager.dispatch.unpickle(state, state_dict) class InstrumentationFactory(EventTarget): """Factory for new ClassManager instances.""" dispatch: dispatcher[InstrumentationFactory] def create_manager_for_cls(self, class_: Type[_O]) -> ClassManager[_O]: assert class_ is not None assert opt_manager_of_class(class_) is None # give a more complicated subclass # a chance to do what it wants here manager, factory = self._locate_extended_factory(class_) if factory is None: factory = ClassManager manager = ClassManager(class_) else: assert manager is not None self._check_conflicts(class_, factory) manager.factory = factory return manager def _locate_extended_factory( self, class_: Type[_O] ) -> Tuple[Optional[ClassManager[_O]], Optional[_ManagerFactory]]: """Overridden by a subclass to do an extended lookup.""" return None, None def _check_conflicts( self, class_: Type[_O], factory: Callable[[Type[_O]], ClassManager[_O]] ) -> None: """Overridden by a subclass to test for conflicting factories.""" def unregister(self, class_: Type[_O]) -> None: manager = manager_of_class(class_) manager.unregister() self.dispatch.class_uninstrument(class_) # this attribute is replaced by sqlalchemy.ext.instrumentation # when imported. _instrumentation_factory = InstrumentationFactory() # these attributes are replaced by sqlalchemy.ext.instrumentation # when a non-standard InstrumentationManager class is first # used to instrument a class. instance_state = _default_state_getter = base.instance_state instance_dict = _default_dict_getter = base.instance_dict manager_of_class = _default_manager_getter = base.manager_of_class opt_manager_of_class = _default_opt_manager_getter = base.opt_manager_of_class def register_class( class_: Type[_O], finalize: bool = True, mapper: Optional[Mapper[_O]] = None, registry: Optional[_RegistryType] = None, declarative_scan: Optional[_MapperConfig] = None, expired_attribute_loader: Optional[_ExpiredAttributeLoaderProto] = None, init_method: Optional[Callable[..., None]] = None, ) -> ClassManager[_O]: """Register class instrumentation. Returns the existing or newly created class manager. """ manager = opt_manager_of_class(class_) if manager is None: manager = _instrumentation_factory.create_manager_for_cls(class_) manager._update_state( mapper=mapper, registry=registry, declarative_scan=declarative_scan, expired_attribute_loader=expired_attribute_loader, init_method=init_method, finalize=finalize, ) return manager def unregister_class(class_): """Unregister class instrumentation.""" _instrumentation_factory.unregister(class_) def is_instrumented(instance, key): """Return True if the given attribute on the given instance is instrumented by the attributes package. This function may be used regardless of instrumentation applied directly to the class, i.e. no descriptors are required. """ return manager_of_class(instance.__class__).is_instrumented( key, search=True ) def _generate_init(class_, class_manager, original_init): """Build an __init__ decorator that triggers ClassManager events.""" # TODO: we should use the ClassManager's notion of the # original '__init__' method, once ClassManager is fixed # to always reference that. if original_init is None: original_init = class_.__init__ # Go through some effort here and don't change the user's __init__ # calling signature, including the unlikely case that it has # a return value. # FIXME: need to juggle local names to avoid constructor argument # clashes. func_body = """\ def __init__(%(apply_pos)s): new_state = class_manager._new_state_if_none(%(self_arg)s) if new_state: return new_state._initialize_instance(%(apply_kw)s) else: return original_init(%(apply_kw)s) """ func_vars = util.format_argspec_init(original_init, grouped=False) func_text = func_body % func_vars func_defaults = getattr(original_init, "__defaults__", None) func_kw_defaults = getattr(original_init, "__kwdefaults__", None) env = locals().copy() env["__name__"] = __name__ exec(func_text, env) __init__ = env["__init__"] __init__.__doc__ = original_init.__doc__ __init__._sa_original_init = original_init if func_defaults: __init__.__defaults__ = func_defaults if func_kw_defaults: __init__.__kwdefaults__ = func_kw_defaults return __init__ sqlalchemy/orm/state_changes.py 0000755 00000015237 15125143220 0012673 0 ustar 00 # orm/state_changes.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """State tracking utilities used by :class:`_orm.Session`. """ from __future__ import annotations import contextlib from enum import Enum from typing import Any from typing import Callable from typing import cast from typing import Iterator from typing import NoReturn from typing import Optional from typing import Tuple from typing import TypeVar from typing import Union from .. import exc as sa_exc from .. import util from ..util.typing import Literal _F = TypeVar("_F", bound=Callable[..., Any]) class _StateChangeState(Enum): pass class _StateChangeStates(_StateChangeState): ANY = 1 NO_CHANGE = 2 CHANGE_IN_PROGRESS = 3 class _StateChange: """Supplies state assertion decorators. The current use case is for the :class:`_orm.SessionTransaction` class. The :class:`_StateChange` class itself is agnostic of the :class:`_orm.SessionTransaction` class so could in theory be generalized for other systems as well. """ _next_state: _StateChangeState = _StateChangeStates.ANY _state: _StateChangeState = _StateChangeStates.NO_CHANGE _current_fn: Optional[Callable[..., Any]] = None def _raise_for_prerequisite_state( self, operation_name: str, state: _StateChangeState ) -> NoReturn: raise sa_exc.IllegalStateChangeError( f"Can't run operation '{operation_name}()' when Session " f"is in state {state!r}", code="isce", ) @classmethod def declare_states( cls, prerequisite_states: Union[ Literal[_StateChangeStates.ANY], Tuple[_StateChangeState, ...] ], moves_to: _StateChangeState, ) -> Callable[[_F], _F]: """Method decorator declaring valid states. :param prerequisite_states: sequence of acceptable prerequisite states. Can be the single constant _State.ANY to indicate no prerequisite state :param moves_to: the expected state at the end of the method, assuming no exceptions raised. Can be the constant _State.NO_CHANGE to indicate state should not change at the end of the method. """ assert prerequisite_states, "no prequisite states sent" has_prerequisite_states = ( prerequisite_states is not _StateChangeStates.ANY ) prerequisite_state_collection = cast( "Tuple[_StateChangeState, ...]", prerequisite_states ) expect_state_change = moves_to is not _StateChangeStates.NO_CHANGE @util.decorator def _go(fn: _F, self: Any, *arg: Any, **kw: Any) -> Any: current_state = self._state if ( has_prerequisite_states and current_state not in prerequisite_state_collection ): self._raise_for_prerequisite_state(fn.__name__, current_state) next_state = self._next_state existing_fn = self._current_fn expect_state = moves_to if expect_state_change else current_state if ( # destination states are restricted next_state is not _StateChangeStates.ANY # method seeks to change state and expect_state_change # destination state incorrect and next_state is not expect_state ): if existing_fn and next_state in ( _StateChangeStates.NO_CHANGE, _StateChangeStates.CHANGE_IN_PROGRESS, ): raise sa_exc.IllegalStateChangeError( f"Method '{fn.__name__}()' can't be called here; " f"method '{existing_fn.__name__}()' is already " f"in progress and this would cause an unexpected " f"state change to {moves_to!r}", code="isce", ) else: raise sa_exc.IllegalStateChangeError( f"Cant run operation '{fn.__name__}()' here; " f"will move to state {moves_to!r} where we are " f"expecting {next_state!r}", code="isce", ) self._current_fn = fn self._next_state = _StateChangeStates.CHANGE_IN_PROGRESS try: ret_value = fn(self, *arg, **kw) except: raise else: if self._state is expect_state: return ret_value if self._state is current_state: raise sa_exc.IllegalStateChangeError( f"Method '{fn.__name__}()' failed to " "change state " f"to {moves_to!r} as expected", code="isce", ) elif existing_fn: raise sa_exc.IllegalStateChangeError( f"While method '{existing_fn.__name__}()' was " "running, " f"method '{fn.__name__}()' caused an " "unexpected " f"state change to {self._state!r}", code="isce", ) else: raise sa_exc.IllegalStateChangeError( f"Method '{fn.__name__}()' caused an unexpected " f"state change to {self._state!r}", code="isce", ) finally: self._next_state = next_state self._current_fn = existing_fn return _go @contextlib.contextmanager def _expect_state(self, expected: _StateChangeState) -> Iterator[Any]: """called within a method that changes states. method must also use the ``@declare_states()`` decorator. """ assert self._next_state is _StateChangeStates.CHANGE_IN_PROGRESS, ( "Unexpected call to _expect_state outside of " "state-changing method" ) self._next_state = expected try: yield except: raise else: if self._state is not expected: raise sa_exc.IllegalStateChangeError( f"Unexpected state change to {self._state!r}", code="isce" ) finally: self._next_state = _StateChangeStates.CHANGE_IN_PROGRESS sqlalchemy/orm/mapped_collection.py 0000755 00000046342 15125143220 0013545 0 ustar 00 # orm/mapped_collection.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php from __future__ import annotations import operator from typing import Any from typing import Callable from typing import Dict from typing import Generic from typing import List from typing import Optional from typing import Sequence from typing import Tuple from typing import Type from typing import TYPE_CHECKING from typing import TypeVar from typing import Union from . import base from .collections import collection from .collections import collection_adapter from .. import exc as sa_exc from .. import util from ..sql import coercions from ..sql import expression from ..sql import roles from ..util.langhelpers import Missing from ..util.langhelpers import MissingOr from ..util.typing import Literal if TYPE_CHECKING: from . import AttributeEventToken from . import Mapper from .collections import CollectionAdapter from ..sql.elements import ColumnElement _KT = TypeVar("_KT", bound=Any) _VT = TypeVar("_VT", bound=Any) class _PlainColumnGetter(Generic[_KT]): """Plain column getter, stores collection of Column objects directly. Serializes to a :class:`._SerializableColumnGetterV2` which has more expensive __call__() performance and some rare caveats. """ __slots__ = ("cols", "composite") def __init__(self, cols: Sequence[ColumnElement[_KT]]) -> None: self.cols = cols self.composite = len(cols) > 1 def __reduce__( self, ) -> Tuple[ Type[_SerializableColumnGetterV2[_KT]], Tuple[Sequence[Tuple[Optional[str], Optional[str]]]], ]: return _SerializableColumnGetterV2._reduce_from_cols(self.cols) def _cols(self, mapper: Mapper[_KT]) -> Sequence[ColumnElement[_KT]]: return self.cols def __call__(self, value: _KT) -> MissingOr[Union[_KT, Tuple[_KT, ...]]]: state = base.instance_state(value) m = base._state_mapper(state) key: List[_KT] = [ m._get_state_attr_by_column(state, state.dict, col) for col in self._cols(m) ] if self.composite: return tuple(key) else: obj = key[0] if obj is None: return Missing else: return obj class _SerializableColumnGetterV2(_PlainColumnGetter[_KT]): """Updated serializable getter which deals with multi-table mapped classes. Two extremely unusual cases are not supported. Mappings which have tables across multiple metadata objects, or which are mapped to non-Table selectables linked across inheriting mappers may fail to function here. """ __slots__ = ("colkeys",) def __init__( self, colkeys: Sequence[Tuple[Optional[str], Optional[str]]] ) -> None: self.colkeys = colkeys self.composite = len(colkeys) > 1 def __reduce__( self, ) -> Tuple[ Type[_SerializableColumnGetterV2[_KT]], Tuple[Sequence[Tuple[Optional[str], Optional[str]]]], ]: return self.__class__, (self.colkeys,) @classmethod def _reduce_from_cols(cls, cols: Sequence[ColumnElement[_KT]]) -> Tuple[ Type[_SerializableColumnGetterV2[_KT]], Tuple[Sequence[Tuple[Optional[str], Optional[str]]]], ]: def _table_key(c: ColumnElement[_KT]) -> Optional[str]: if not isinstance(c.table, expression.TableClause): return None else: return c.table.key # type: ignore colkeys = [(c.key, _table_key(c)) for c in cols] return _SerializableColumnGetterV2, (colkeys,) def _cols(self, mapper: Mapper[_KT]) -> Sequence[ColumnElement[_KT]]: cols: List[ColumnElement[_KT]] = [] metadata = getattr(mapper.local_table, "metadata", None) for ckey, tkey in self.colkeys: if tkey is None or metadata is None or tkey not in metadata: cols.append(mapper.local_table.c[ckey]) # type: ignore else: cols.append(metadata.tables[tkey].c[ckey]) return cols def column_keyed_dict( mapping_spec: Union[Type[_KT], Callable[[_KT], _VT]], *, ignore_unpopulated_attribute: bool = False, ) -> Type[KeyFuncDict[_KT, _KT]]: """A dictionary-based collection type with column-based keying. .. versionchanged:: 2.0 Renamed :data:`.column_mapped_collection` to :class:`.column_keyed_dict`. Returns a :class:`.KeyFuncDict` factory which will produce new dictionary keys based on the value of a particular :class:`.Column`-mapped attribute on ORM mapped instances to be added to the dictionary. .. note:: the value of the target attribute must be assigned with its value at the time that the object is being added to the dictionary collection. Additionally, changes to the key attribute are **not tracked**, which means the key in the dictionary is not automatically synchronized with the key value on the target object itself. See :ref:`key_collections_mutations` for further details. .. seealso:: :ref:`orm_dictionary_collection` - background on use :param mapping_spec: a :class:`_schema.Column` object that is expected to be mapped by the target mapper to a particular attribute on the mapped class, the value of which on a particular instance is to be used as the key for a new dictionary entry for that instance. :param ignore_unpopulated_attribute: if True, and the mapped attribute indicated by the given :class:`_schema.Column` target attribute on an object is not populated at all, the operation will be silently skipped. By default, an error is raised. .. versionadded:: 2.0 an error is raised by default if the attribute being used for the dictionary key is determined that it was never populated with any value. The :paramref:`_orm.column_keyed_dict.ignore_unpopulated_attribute` parameter may be set which will instead indicate that this condition should be ignored, and the append operation silently skipped. This is in contrast to the behavior of the 1.x series which would erroneously populate the value in the dictionary with an arbitrary key value of ``None``. """ cols = [ coercions.expect(roles.ColumnArgumentRole, q, argname="mapping_spec") for q in util.to_list(mapping_spec) ] keyfunc = _PlainColumnGetter(cols) return _mapped_collection_cls( keyfunc, ignore_unpopulated_attribute=ignore_unpopulated_attribute, ) class _AttrGetter: __slots__ = ("attr_name", "getter") def __init__(self, attr_name: str): self.attr_name = attr_name self.getter = operator.attrgetter(attr_name) def __call__(self, mapped_object: Any) -> Any: obj = self.getter(mapped_object) if obj is None: state = base.instance_state(mapped_object) mp = state.mapper if self.attr_name in mp.attrs: dict_ = state.dict obj = dict_.get(self.attr_name, base.NO_VALUE) if obj is None: return Missing else: return Missing return obj def __reduce__(self) -> Tuple[Type[_AttrGetter], Tuple[str]]: return _AttrGetter, (self.attr_name,) def attribute_keyed_dict( attr_name: str, *, ignore_unpopulated_attribute: bool = False ) -> Type[KeyFuncDict[Any, Any]]: """A dictionary-based collection type with attribute-based keying. .. versionchanged:: 2.0 Renamed :data:`.attribute_mapped_collection` to :func:`.attribute_keyed_dict`. Returns a :class:`.KeyFuncDict` factory which will produce new dictionary keys based on the value of a particular named attribute on ORM mapped instances to be added to the dictionary. .. note:: the value of the target attribute must be assigned with its value at the time that the object is being added to the dictionary collection. Additionally, changes to the key attribute are **not tracked**, which means the key in the dictionary is not automatically synchronized with the key value on the target object itself. See :ref:`key_collections_mutations` for further details. .. seealso:: :ref:`orm_dictionary_collection` - background on use :param attr_name: string name of an ORM-mapped attribute on the mapped class, the value of which on a particular instance is to be used as the key for a new dictionary entry for that instance. :param ignore_unpopulated_attribute: if True, and the target attribute on an object is not populated at all, the operation will be silently skipped. By default, an error is raised. .. versionadded:: 2.0 an error is raised by default if the attribute being used for the dictionary key is determined that it was never populated with any value. The :paramref:`_orm.attribute_keyed_dict.ignore_unpopulated_attribute` parameter may be set which will instead indicate that this condition should be ignored, and the append operation silently skipped. This is in contrast to the behavior of the 1.x series which would erroneously populate the value in the dictionary with an arbitrary key value of ``None``. """ return _mapped_collection_cls( _AttrGetter(attr_name), ignore_unpopulated_attribute=ignore_unpopulated_attribute, ) def keyfunc_mapping( keyfunc: Callable[[Any], Any], *, ignore_unpopulated_attribute: bool = False, ) -> Type[KeyFuncDict[_KT, Any]]: """A dictionary-based collection type with arbitrary keying. .. versionchanged:: 2.0 Renamed :data:`.mapped_collection` to :func:`.keyfunc_mapping`. Returns a :class:`.KeyFuncDict` factory with a keying function generated from keyfunc, a callable that takes an entity and returns a key value. .. note:: the given keyfunc is called only once at the time that the target object is being added to the collection. Changes to the effective value returned by the function are not tracked. .. seealso:: :ref:`orm_dictionary_collection` - background on use :param keyfunc: a callable that will be passed the ORM-mapped instance which should then generate a new key to use in the dictionary. If the value returned is :attr:`.LoaderCallableStatus.NO_VALUE`, an error is raised. :param ignore_unpopulated_attribute: if True, and the callable returns :attr:`.LoaderCallableStatus.NO_VALUE` for a particular instance, the operation will be silently skipped. By default, an error is raised. .. versionadded:: 2.0 an error is raised by default if the callable being used for the dictionary key returns :attr:`.LoaderCallableStatus.NO_VALUE`, which in an ORM attribute context indicates an attribute that was never populated with any value. The :paramref:`_orm.mapped_collection.ignore_unpopulated_attribute` parameter may be set which will instead indicate that this condition should be ignored, and the append operation silently skipped. This is in contrast to the behavior of the 1.x series which would erroneously populate the value in the dictionary with an arbitrary key value of ``None``. """ return _mapped_collection_cls( keyfunc, ignore_unpopulated_attribute=ignore_unpopulated_attribute ) class KeyFuncDict(Dict[_KT, _VT]): """Base for ORM mapped dictionary classes. Extends the ``dict`` type with additional methods needed by SQLAlchemy ORM collection classes. Use of :class:`_orm.KeyFuncDict` is most directly by using the :func:`.attribute_keyed_dict` or :func:`.column_keyed_dict` class factories. :class:`_orm.KeyFuncDict` may also serve as the base for user-defined custom dictionary classes. .. versionchanged:: 2.0 Renamed :class:`.MappedCollection` to :class:`.KeyFuncDict`. .. seealso:: :func:`_orm.attribute_keyed_dict` :func:`_orm.column_keyed_dict` :ref:`orm_dictionary_collection` :ref:`orm_custom_collection` """ def __init__( self, keyfunc: Callable[[Any], Any], *dict_args: Any, ignore_unpopulated_attribute: bool = False, ) -> None: """Create a new collection with keying provided by keyfunc. keyfunc may be any callable that takes an object and returns an object for use as a dictionary key. The keyfunc will be called every time the ORM needs to add a member by value-only (such as when loading instances from the database) or remove a member. The usual cautions about dictionary keying apply- ``keyfunc(object)`` should return the same output for the life of the collection. Keying based on mutable properties can result in unreachable instances "lost" in the collection. """ self.keyfunc = keyfunc self.ignore_unpopulated_attribute = ignore_unpopulated_attribute super().__init__(*dict_args) @classmethod def _unreduce( cls, keyfunc: Callable[[Any], Any], values: Dict[_KT, _KT], adapter: Optional[CollectionAdapter] = None, ) -> "KeyFuncDict[_KT, _KT]": mp: KeyFuncDict[_KT, _KT] = KeyFuncDict(keyfunc) mp.update(values) # note that the adapter sets itself up onto this collection # when its `__setstate__` method is called return mp def __reduce__( self, ) -> Tuple[ Callable[[_KT, _KT], KeyFuncDict[_KT, _KT]], Tuple[Any, Union[Dict[_KT, _KT], Dict[_KT, _KT]], CollectionAdapter], ]: return ( KeyFuncDict._unreduce, ( self.keyfunc, dict(self), collection_adapter(self), ), ) @util.preload_module("sqlalchemy.orm.attributes") def _raise_for_unpopulated( self, value: _KT, initiator: Union[AttributeEventToken, Literal[None, False]] = None, *, warn_only: bool, ) -> None: mapper = base.instance_state(value).mapper attributes = util.preloaded.orm_attributes if not isinstance(initiator, attributes.AttributeEventToken): relationship = "unknown relationship" elif initiator.key in mapper.attrs: relationship = f"{mapper.attrs[initiator.key]}" else: relationship = initiator.key if warn_only: util.warn( f"Attribute keyed dictionary value for " f"attribute '{relationship}' was None; this will raise " "in a future release. " f"To skip this assignment entirely, " f'Set the "ignore_unpopulated_attribute=True" ' f"parameter on the mapped collection factory." ) else: raise sa_exc.InvalidRequestError( "In event triggered from population of " f"attribute '{relationship}' " "(potentially from a backref), " f"can't populate value in KeyFuncDict; " "dictionary key " f"derived from {base.instance_str(value)} is not " f"populated. Ensure appropriate state is set up on " f"the {base.instance_str(value)} object " f"before assigning to the {relationship} attribute. " f"To skip this assignment entirely, " f'Set the "ignore_unpopulated_attribute=True" ' f"parameter on the mapped collection factory." ) @collection.appender # type: ignore[misc] @collection.internally_instrumented # type: ignore[misc] def set( self, value: _KT, _sa_initiator: Union[AttributeEventToken, Literal[None, False]] = None, ) -> None: """Add an item by value, consulting the keyfunc for the key.""" key = self.keyfunc(value) if key is base.NO_VALUE: if not self.ignore_unpopulated_attribute: self._raise_for_unpopulated( value, _sa_initiator, warn_only=False ) else: return elif key is Missing: if not self.ignore_unpopulated_attribute: self._raise_for_unpopulated( value, _sa_initiator, warn_only=True ) key = None else: return self.__setitem__(key, value, _sa_initiator) # type: ignore[call-arg] @collection.remover # type: ignore[misc] @collection.internally_instrumented # type: ignore[misc] def remove( self, value: _KT, _sa_initiator: Union[AttributeEventToken, Literal[None, False]] = None, ) -> None: """Remove an item by value, consulting the keyfunc for the key.""" key = self.keyfunc(value) if key is base.NO_VALUE: if not self.ignore_unpopulated_attribute: self._raise_for_unpopulated( value, _sa_initiator, warn_only=False ) return elif key is Missing: if not self.ignore_unpopulated_attribute: self._raise_for_unpopulated( value, _sa_initiator, warn_only=True ) key = None else: return # Let self[key] raise if key is not in this collection # testlib.pragma exempt:__ne__ if self[key] != value: raise sa_exc.InvalidRequestError( "Can not remove '%s': collection holds '%s' for key '%s'. " "Possible cause: is the KeyFuncDict key function " "based on mutable properties or properties that only obtain " "values after flush?" % (value, self[key], key) ) self.__delitem__(key, _sa_initiator) # type: ignore[call-arg] def _mapped_collection_cls( keyfunc: Callable[[Any], Any], ignore_unpopulated_attribute: bool ) -> Type[KeyFuncDict[_KT, _KT]]: class _MKeyfuncMapped(KeyFuncDict[_KT, _KT]): def __init__(self, *dict_args: Any) -> None: super().__init__( keyfunc, *dict_args, ignore_unpopulated_attribute=ignore_unpopulated_attribute, ) return _MKeyfuncMapped MappedCollection = KeyFuncDict """A synonym for :class:`.KeyFuncDict`. .. versionchanged:: 2.0 Renamed :class:`.MappedCollection` to :class:`.KeyFuncDict`. """ mapped_collection = keyfunc_mapping """A synonym for :func:`_orm.keyfunc_mapping`. .. versionchanged:: 2.0 Renamed :data:`.mapped_collection` to :func:`_orm.keyfunc_mapping` """ attribute_mapped_collection = attribute_keyed_dict """A synonym for :func:`_orm.attribute_keyed_dict`. .. versionchanged:: 2.0 Renamed :data:`.attribute_mapped_collection` to :func:`_orm.attribute_keyed_dict` """ column_mapped_collection = column_keyed_dict """A synonym for :func:`_orm.column_keyed_dict. .. versionchanged:: 2.0 Renamed :func:`.column_mapped_collection` to :func:`_orm.column_keyed_dict` """ sqlalchemy/orm/decl_api.py 0000755 00000176642 15125143220 0011633 0 ustar 00 # orm/decl_api.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """Public API functions and helpers for declarative.""" from __future__ import annotations import itertools import re import typing from typing import Any from typing import Callable from typing import ClassVar from typing import Dict from typing import FrozenSet from typing import Generic from typing import Iterable from typing import Iterator from typing import Mapping from typing import Optional from typing import overload from typing import Set from typing import Tuple from typing import Type from typing import TYPE_CHECKING from typing import TypeVar from typing import Union import weakref from . import attributes from . import clsregistry from . import instrumentation from . import interfaces from . import mapperlib from ._orm_constructors import composite from ._orm_constructors import deferred from ._orm_constructors import mapped_column from ._orm_constructors import relationship from ._orm_constructors import synonym from .attributes import InstrumentedAttribute from .base import _inspect_mapped_class from .base import _is_mapped_class from .base import Mapped from .base import ORMDescriptor from .decl_base import _add_attribute from .decl_base import _as_declarative from .decl_base import _ClassScanMapperConfig from .decl_base import _declarative_constructor from .decl_base import _DeferredMapperConfig from .decl_base import _del_attribute from .decl_base import _mapper from .descriptor_props import Composite from .descriptor_props import Synonym from .descriptor_props import Synonym as _orm_synonym from .mapper import Mapper from .properties import MappedColumn from .relationships import RelationshipProperty from .state import InstanceState from .. import exc from .. import inspection from .. import util from ..sql import sqltypes from ..sql.base import _NoArg from ..sql.elements import SQLCoreOperations from ..sql.schema import MetaData from ..sql.selectable import FromClause from ..util import hybridmethod from ..util import hybridproperty from ..util import typing as compat_typing from ..util import warn_deprecated from ..util.typing import CallableReference from ..util.typing import de_optionalize_union_types from ..util.typing import flatten_newtype from ..util.typing import is_generic from ..util.typing import is_literal from ..util.typing import is_newtype from ..util.typing import is_pep695 from ..util.typing import Literal from ..util.typing import LITERAL_TYPES from ..util.typing import Self if TYPE_CHECKING: from ._typing import _O from ._typing import _RegistryType from .decl_base import _DataclassArguments from .instrumentation import ClassManager from .interfaces import MapperProperty from .state import InstanceState # noqa from ..sql._typing import _TypeEngineArgument from ..sql.type_api import _MatchedOnType _T = TypeVar("_T", bound=Any) _TT = TypeVar("_TT", bound=Any) # it's not clear how to have Annotated, Union objects etc. as keys here # from a typing perspective so just leave it open ended for now _TypeAnnotationMapType = Mapping[Any, "_TypeEngineArgument[Any]"] _MutableTypeAnnotationMapType = Dict[Any, "_TypeEngineArgument[Any]"] _DeclaredAttrDecorated = Callable[ ..., Union[Mapped[_T], ORMDescriptor[_T], SQLCoreOperations[_T]] ] def has_inherited_table(cls: Type[_O]) -> bool: """Given a class, return True if any of the classes it inherits from has a mapped table, otherwise return False. This is used in declarative mixins to build attributes that behave differently for the base class vs. a subclass in an inheritance hierarchy. .. seealso:: :ref:`decl_mixin_inheritance` """ for class_ in cls.__mro__[1:]: if getattr(class_, "__table__", None) is not None: return True return False class _DynamicAttributesType(type): def __setattr__(cls, key: str, value: Any) -> None: if "__mapper__" in cls.__dict__: _add_attribute(cls, key, value) else: type.__setattr__(cls, key, value) def __delattr__(cls, key: str) -> None: if "__mapper__" in cls.__dict__: _del_attribute(cls, key) else: type.__delattr__(cls, key) class DeclarativeAttributeIntercept( _DynamicAttributesType, # Inspectable is used only by the mypy plugin inspection.Inspectable[Mapper[Any]], ): """Metaclass that may be used in conjunction with the :class:`_orm.DeclarativeBase` class to support addition of class attributes dynamically. """ @compat_typing.dataclass_transform( field_specifiers=( MappedColumn, RelationshipProperty, Composite, Synonym, mapped_column, relationship, composite, synonym, deferred, ), ) class DCTransformDeclarative(DeclarativeAttributeIntercept): """metaclass that includes @dataclass_transforms""" class DeclarativeMeta(DeclarativeAttributeIntercept): metadata: MetaData registry: RegistryType def __init__( cls, classname: Any, bases: Any, dict_: Any, **kw: Any ) -> None: # use cls.__dict__, which can be modified by an # __init_subclass__() method (#7900) dict_ = cls.__dict__ # early-consume registry from the initial declarative base, # assign privately to not conflict with subclass attributes named # "registry" reg = getattr(cls, "_sa_registry", None) if reg is None: reg = dict_.get("registry", None) if not isinstance(reg, registry): raise exc.InvalidRequestError( "Declarative base class has no 'registry' attribute, " "or registry is not a sqlalchemy.orm.registry() object" ) else: cls._sa_registry = reg if not cls.__dict__.get("__abstract__", False): _as_declarative(reg, cls, dict_) type.__init__(cls, classname, bases, dict_) def synonym_for( name: str, map_column: bool = False ) -> Callable[[Callable[..., Any]], Synonym[Any]]: """Decorator that produces an :func:`_orm.synonym` attribute in conjunction with a Python descriptor. The function being decorated is passed to :func:`_orm.synonym` as the :paramref:`.orm.synonym.descriptor` parameter:: class MyClass(Base): __tablename__ = "my_table" id = Column(Integer, primary_key=True) _job_status = Column("job_status", String(50)) @synonym_for("job_status") @property def job_status(self): return "Status: %s" % self._job_status The :ref:`hybrid properties <mapper_hybrids>` feature of SQLAlchemy is typically preferred instead of synonyms, which is a more legacy feature. .. seealso:: :ref:`synonyms` - Overview of synonyms :func:`_orm.synonym` - the mapper-level function :ref:`mapper_hybrids` - The Hybrid Attribute extension provides an updated approach to augmenting attribute behavior more flexibly than can be achieved with synonyms. """ def decorate(fn: Callable[..., Any]) -> Synonym[Any]: return _orm_synonym(name, map_column=map_column, descriptor=fn) return decorate class _declared_attr_common: def __init__( self, fn: Callable[..., Any], cascading: bool = False, quiet: bool = False, ): # suppport # @declared_attr # @classmethod # def foo(cls) -> Mapped[thing]: # ... # which seems to help typing tools interpret the fn as a classmethod # for situations where needed if isinstance(fn, classmethod): fn = fn.__func__ self.fget = fn self._cascading = cascading self._quiet = quiet self.__doc__ = fn.__doc__ def _collect_return_annotation(self) -> Optional[Type[Any]]: return util.get_annotations(self.fget).get("return") def __get__(self, instance: Optional[object], owner: Any) -> Any: # the declared_attr needs to make use of a cache that exists # for the span of the declarative scan_attributes() phase. # to achieve this we look at the class manager that's configured. # note this method should not be called outside of the declarative # setup phase cls = owner manager = attributes.opt_manager_of_class(cls) if manager is None: if not re.match(r"^__.+__$", self.fget.__name__): # if there is no manager at all, then this class hasn't been # run through declarative or mapper() at all, emit a warning. util.warn( "Unmanaged access of declarative attribute %s from " "non-mapped class %s" % (self.fget.__name__, cls.__name__) ) return self.fget(cls) elif manager.is_mapped: # the class is mapped, which means we're outside of the declarative # scan setup, just run the function. return self.fget(cls) # here, we are inside of the declarative scan. use the registry # that is tracking the values of these attributes. declarative_scan = manager.declarative_scan() # assert that we are in fact in the declarative scan assert declarative_scan is not None reg = declarative_scan.declared_attr_reg if self in reg: return reg[self] else: reg[self] = obj = self.fget(cls) return obj class _declared_directive(_declared_attr_common, Generic[_T]): # see mapping_api.rst for docstring if typing.TYPE_CHECKING: def __init__( self, fn: Callable[..., _T], cascading: bool = False, ): ... def __get__(self, instance: Optional[object], owner: Any) -> _T: ... def __set__(self, instance: Any, value: Any) -> None: ... def __delete__(self, instance: Any) -> None: ... def __call__(self, fn: Callable[..., _TT]) -> _declared_directive[_TT]: # extensive fooling of mypy underway... ... class declared_attr(interfaces._MappedAttribute[_T], _declared_attr_common): """Mark a class-level method as representing the definition of a mapped property or Declarative directive. :class:`_orm.declared_attr` is typically applied as a decorator to a class level method, turning the attribute into a scalar-like property that can be invoked from the uninstantiated class. The Declarative mapping process looks for these :class:`_orm.declared_attr` callables as it scans classes, and assumes any attribute marked with :class:`_orm.declared_attr` will be a callable that will produce an object specific to the Declarative mapping or table configuration. :class:`_orm.declared_attr` is usually applicable to :ref:`mixins <orm_mixins_toplevel>`, to define relationships that are to be applied to different implementors of the class. It may also be used to define dynamically generated column expressions and other Declarative attributes. Example:: class ProvidesUserMixin: "A mixin that adds a 'user' relationship to classes." user_id: Mapped[int] = mapped_column(ForeignKey("user_table.id")) @declared_attr def user(cls) -> Mapped["User"]: return relationship("User") When used with Declarative directives such as ``__tablename__``, the :meth:`_orm.declared_attr.directive` modifier may be used which indicates to :pep:`484` typing tools that the given method is not dealing with :class:`_orm.Mapped` attributes:: class CreateTableName: @declared_attr.directive def __tablename__(cls) -> str: return cls.__name__.lower() :class:`_orm.declared_attr` can also be applied directly to mapped classes, to allow for attributes that dynamically configure themselves on subclasses when using mapped inheritance schemes. Below illustrates :class:`_orm.declared_attr` to create a dynamic scheme for generating the :paramref:`_orm.Mapper.polymorphic_identity` parameter for subclasses:: class Employee(Base): __tablename__ = "employee" id: Mapped[int] = mapped_column(primary_key=True) type: Mapped[str] = mapped_column(String(50)) @declared_attr.directive def __mapper_args__(cls) -> Dict[str, Any]: if cls.__name__ == "Employee": return { "polymorphic_on": cls.type, "polymorphic_identity": "Employee", } else: return {"polymorphic_identity": cls.__name__} class Engineer(Employee): pass :class:`_orm.declared_attr` supports decorating functions that are explicitly decorated with ``@classmethod``. This is never necessary from a runtime perspective, however may be needed in order to support :pep:`484` typing tools that don't otherwise recognize the decorated function as having class-level behaviors for the ``cls`` parameter:: class SomethingMixin: x: Mapped[int] y: Mapped[int] @declared_attr @classmethod def x_plus_y(cls) -> Mapped[int]: return column_property(cls.x + cls.y) .. versionadded:: 2.0 - :class:`_orm.declared_attr` can accommodate a function decorated with ``@classmethod`` to help with :pep:`484` integration where needed. .. seealso:: :ref:`orm_mixins_toplevel` - Declarative Mixin documentation with background on use patterns for :class:`_orm.declared_attr`. """ # noqa: E501 if typing.TYPE_CHECKING: def __init__( self, fn: _DeclaredAttrDecorated[_T], cascading: bool = False, ): ... def __set__(self, instance: Any, value: Any) -> None: ... def __delete__(self, instance: Any) -> None: ... # this is the Mapped[] API where at class descriptor get time we want # the type checker to see InstrumentedAttribute[_T]. However the # callable function prior to mapping in fact calls the given # declarative function that does not return InstrumentedAttribute @overload def __get__( self, instance: None, owner: Any ) -> InstrumentedAttribute[_T]: ... @overload def __get__(self, instance: object, owner: Any) -> _T: ... def __get__( self, instance: Optional[object], owner: Any ) -> Union[InstrumentedAttribute[_T], _T]: ... @hybridmethod def _stateful(cls, **kw: Any) -> _stateful_declared_attr[_T]: return _stateful_declared_attr(**kw) @hybridproperty def directive(cls) -> _declared_directive[Any]: # see mapping_api.rst for docstring return _declared_directive # type: ignore @hybridproperty def cascading(cls) -> _stateful_declared_attr[_T]: # see mapping_api.rst for docstring return cls._stateful(cascading=True) class _stateful_declared_attr(declared_attr[_T]): kw: Dict[str, Any] def __init__(self, **kw: Any): self.kw = kw @hybridmethod def _stateful(self, **kw: Any) -> _stateful_declared_attr[_T]: new_kw = self.kw.copy() new_kw.update(kw) return _stateful_declared_attr(**new_kw) def __call__(self, fn: _DeclaredAttrDecorated[_T]) -> declared_attr[_T]: return declared_attr(fn, **self.kw) def declarative_mixin(cls: Type[_T]) -> Type[_T]: """Mark a class as providing the feature of "declarative mixin". E.g.:: from sqlalchemy.orm import declared_attr from sqlalchemy.orm import declarative_mixin @declarative_mixin class MyMixin: @declared_attr def __tablename__(cls): return cls.__name__.lower() __table_args__ = {"mysql_engine": "InnoDB"} __mapper_args__ = {"always_refresh": True} id = Column(Integer, primary_key=True) class MyModel(MyMixin, Base): name = Column(String(1000)) The :func:`_orm.declarative_mixin` decorator currently does not modify the given class in any way; it's current purpose is strictly to assist the :ref:`Mypy plugin <mypy_toplevel>` in being able to identify SQLAlchemy declarative mixin classes when no other context is present. .. versionadded:: 1.4.6 .. seealso:: :ref:`orm_mixins_toplevel` :ref:`mypy_declarative_mixins` - in the :ref:`Mypy plugin documentation <mypy_toplevel>` """ # noqa: E501 return cls def _setup_declarative_base(cls: Type[Any]) -> None: if "metadata" in cls.__dict__: metadata = cls.__dict__["metadata"] else: metadata = None if "type_annotation_map" in cls.__dict__: type_annotation_map = cls.__dict__["type_annotation_map"] else: type_annotation_map = None reg = cls.__dict__.get("registry", None) if reg is not None: if not isinstance(reg, registry): raise exc.InvalidRequestError( "Declarative base class has a 'registry' attribute that is " "not an instance of sqlalchemy.orm.registry()" ) elif type_annotation_map is not None: raise exc.InvalidRequestError( "Declarative base class has both a 'registry' attribute and a " "type_annotation_map entry. Per-base type_annotation_maps " "are not supported. Please apply the type_annotation_map " "to this registry directly." ) else: reg = registry( metadata=metadata, type_annotation_map=type_annotation_map ) cls.registry = reg cls._sa_registry = reg if "metadata" not in cls.__dict__: cls.metadata = cls.registry.metadata if getattr(cls, "__init__", object.__init__) is object.__init__: cls.__init__ = cls.registry.constructor class MappedAsDataclass(metaclass=DCTransformDeclarative): """Mixin class to indicate when mapping this class, also convert it to be a dataclass. .. seealso:: :ref:`orm_declarative_native_dataclasses` - complete background on SQLAlchemy native dataclass mapping .. versionadded:: 2.0 """ def __init_subclass__( cls, init: Union[_NoArg, bool] = _NoArg.NO_ARG, repr: Union[_NoArg, bool] = _NoArg.NO_ARG, # noqa: A002 eq: Union[_NoArg, bool] = _NoArg.NO_ARG, order: Union[_NoArg, bool] = _NoArg.NO_ARG, unsafe_hash: Union[_NoArg, bool] = _NoArg.NO_ARG, match_args: Union[_NoArg, bool] = _NoArg.NO_ARG, kw_only: Union[_NoArg, bool] = _NoArg.NO_ARG, dataclass_callable: Union[ _NoArg, Callable[..., Type[Any]] ] = _NoArg.NO_ARG, **kw: Any, ) -> None: apply_dc_transforms: _DataclassArguments = { "init": init, "repr": repr, "eq": eq, "order": order, "unsafe_hash": unsafe_hash, "match_args": match_args, "kw_only": kw_only, "dataclass_callable": dataclass_callable, } current_transforms: _DataclassArguments if hasattr(cls, "_sa_apply_dc_transforms"): current = cls._sa_apply_dc_transforms _ClassScanMapperConfig._assert_dc_arguments(current) cls._sa_apply_dc_transforms = current_transforms = { # type: ignore # noqa: E501 k: current.get(k, _NoArg.NO_ARG) if v is _NoArg.NO_ARG else v for k, v in apply_dc_transforms.items() } else: cls._sa_apply_dc_transforms = current_transforms = ( apply_dc_transforms ) super().__init_subclass__(**kw) if not _is_mapped_class(cls): new_anno = ( _ClassScanMapperConfig._update_annotations_for_non_mapped_class )(cls) _ClassScanMapperConfig._apply_dataclasses_to_any_class( current_transforms, cls, new_anno ) class DeclarativeBase( # Inspectable is used only by the mypy plugin inspection.Inspectable[InstanceState[Any]], metaclass=DeclarativeAttributeIntercept, ): """Base class used for declarative class definitions. The :class:`_orm.DeclarativeBase` allows for the creation of new declarative bases in such a way that is compatible with type checkers:: from sqlalchemy.orm import DeclarativeBase class Base(DeclarativeBase): pass The above ``Base`` class is now usable as the base for new declarative mappings. The superclass makes use of the ``__init_subclass__()`` method to set up new classes and metaclasses aren't used. When first used, the :class:`_orm.DeclarativeBase` class instantiates a new :class:`_orm.registry` to be used with the base, assuming one was not provided explicitly. The :class:`_orm.DeclarativeBase` class supports class-level attributes which act as parameters for the construction of this registry; such as to indicate a specific :class:`_schema.MetaData` collection as well as a specific value for :paramref:`_orm.registry.type_annotation_map`:: from typing_extensions import Annotated from sqlalchemy import BigInteger from sqlalchemy import MetaData from sqlalchemy import String from sqlalchemy.orm import DeclarativeBase bigint = Annotated[int, "bigint"] my_metadata = MetaData() class Base(DeclarativeBase): metadata = my_metadata type_annotation_map = { str: String().with_variant(String(255), "mysql", "mariadb"), bigint: BigInteger(), } Class-level attributes which may be specified include: :param metadata: optional :class:`_schema.MetaData` collection. If a :class:`_orm.registry` is constructed automatically, this :class:`_schema.MetaData` collection will be used to construct it. Otherwise, the local :class:`_schema.MetaData` collection will supercede that used by an existing :class:`_orm.registry` passed using the :paramref:`_orm.DeclarativeBase.registry` parameter. :param type_annotation_map: optional type annotation map that will be passed to the :class:`_orm.registry` as :paramref:`_orm.registry.type_annotation_map`. :param registry: supply a pre-existing :class:`_orm.registry` directly. .. versionadded:: 2.0 Added :class:`.DeclarativeBase`, so that declarative base classes may be constructed in such a way that is also recognized by :pep:`484` type checkers. As a result, :class:`.DeclarativeBase` and other subclassing-oriented APIs should be seen as superseding previous "class returned by a function" APIs, namely :func:`_orm.declarative_base` and :meth:`_orm.registry.generate_base`, where the base class returned cannot be recognized by type checkers without using plugins. **__init__ behavior** In a plain Python class, the base-most ``__init__()`` method in the class hierarchy is ``object.__init__()``, which accepts no arguments. However, when the :class:`_orm.DeclarativeBase` subclass is first declared, the class is given an ``__init__()`` method that links to the :paramref:`_orm.registry.constructor` constructor function, if no ``__init__()`` method is already present; this is the usual declarative constructor that will assign keyword arguments as attributes on the instance, assuming those attributes are established at the class level (i.e. are mapped, or are linked to a descriptor). This constructor is **never accessed by a mapped class without being called explicitly via super()**, as mapped classes are themselves given an ``__init__()`` method directly which calls :paramref:`_orm.registry.constructor`, so in the default case works independently of what the base-most ``__init__()`` method does. .. versionchanged:: 2.0.1 :class:`_orm.DeclarativeBase` has a default constructor that links to :paramref:`_orm.registry.constructor` by default, so that calls to ``super().__init__()`` can access this constructor. Previously, due to an implementation mistake, this default constructor was missing, and calling ``super().__init__()`` would invoke ``object.__init__()``. The :class:`_orm.DeclarativeBase` subclass may also declare an explicit ``__init__()`` method which will replace the use of the :paramref:`_orm.registry.constructor` function at this level:: class Base(DeclarativeBase): def __init__(self, id=None): self.id = id Mapped classes still will not invoke this constructor implicitly; it remains only accessible by calling ``super().__init__()``:: class MyClass(Base): def __init__(self, id=None, name=None): self.name = name super().__init__(id=id) Note that this is a different behavior from what functions like the legacy :func:`_orm.declarative_base` would do; the base created by those functions would always install :paramref:`_orm.registry.constructor` for ``__init__()``. """ if typing.TYPE_CHECKING: def _sa_inspect_type(self) -> Mapper[Self]: ... def _sa_inspect_instance(self) -> InstanceState[Self]: ... _sa_registry: ClassVar[_RegistryType] registry: ClassVar[_RegistryType] """Refers to the :class:`_orm.registry` in use where new :class:`_orm.Mapper` objects will be associated.""" metadata: ClassVar[MetaData] """Refers to the :class:`_schema.MetaData` collection that will be used for new :class:`_schema.Table` objects. .. seealso:: :ref:`orm_declarative_metadata` """ __name__: ClassVar[str] # this ideally should be Mapper[Self], but mypy as of 1.4.1 does not # like it, and breaks the declared_attr_one test. Pyright/pylance is # ok with it. __mapper__: ClassVar[Mapper[Any]] """The :class:`_orm.Mapper` object to which a particular class is mapped. May also be acquired using :func:`_sa.inspect`, e.g. ``inspect(klass)``. """ __table__: ClassVar[FromClause] """The :class:`_sql.FromClause` to which a particular subclass is mapped. This is usually an instance of :class:`_schema.Table` but may also refer to other kinds of :class:`_sql.FromClause` such as :class:`_sql.Subquery`, depending on how the class is mapped. .. seealso:: :ref:`orm_declarative_metadata` """ # pyright/pylance do not consider a classmethod a ClassVar so use Any # https://github.com/microsoft/pylance-release/issues/3484 __tablename__: Any """String name to assign to the generated :class:`_schema.Table` object, if not specified directly via :attr:`_orm.DeclarativeBase.__table__`. .. seealso:: :ref:`orm_declarative_table` """ __mapper_args__: Any """Dictionary of arguments which will be passed to the :class:`_orm.Mapper` constructor. .. seealso:: :ref:`orm_declarative_mapper_options` """ __table_args__: Any """A dictionary or tuple of arguments that will be passed to the :class:`_schema.Table` constructor. See :ref:`orm_declarative_table_configuration` for background on the specific structure of this collection. .. seealso:: :ref:`orm_declarative_table_configuration` """ def __init__(self, **kw: Any): ... def __init_subclass__(cls, **kw: Any) -> None: if DeclarativeBase in cls.__bases__: _check_not_declarative(cls, DeclarativeBase) _setup_declarative_base(cls) else: _as_declarative(cls._sa_registry, cls, cls.__dict__) super().__init_subclass__(**kw) def _check_not_declarative(cls: Type[Any], base: Type[Any]) -> None: cls_dict = cls.__dict__ if ( "__table__" in cls_dict and not ( callable(cls_dict["__table__"]) or hasattr(cls_dict["__table__"], "__get__") ) ) or isinstance(cls_dict.get("__tablename__", None), str): raise exc.InvalidRequestError( f"Cannot use {base.__name__!r} directly as a declarative base " "class. Create a Base by creating a subclass of it." ) class DeclarativeBaseNoMeta( # Inspectable is used only by the mypy plugin inspection.Inspectable[InstanceState[Any]] ): """Same as :class:`_orm.DeclarativeBase`, but does not use a metaclass to intercept new attributes. The :class:`_orm.DeclarativeBaseNoMeta` base may be used when use of custom metaclasses is desirable. .. versionadded:: 2.0 """ _sa_registry: ClassVar[_RegistryType] registry: ClassVar[_RegistryType] """Refers to the :class:`_orm.registry` in use where new :class:`_orm.Mapper` objects will be associated.""" metadata: ClassVar[MetaData] """Refers to the :class:`_schema.MetaData` collection that will be used for new :class:`_schema.Table` objects. .. seealso:: :ref:`orm_declarative_metadata` """ # this ideally should be Mapper[Self], but mypy as of 1.4.1 does not # like it, and breaks the declared_attr_one test. Pyright/pylance is # ok with it. __mapper__: ClassVar[Mapper[Any]] """The :class:`_orm.Mapper` object to which a particular class is mapped. May also be acquired using :func:`_sa.inspect`, e.g. ``inspect(klass)``. """ __table__: Optional[FromClause] """The :class:`_sql.FromClause` to which a particular subclass is mapped. This is usually an instance of :class:`_schema.Table` but may also refer to other kinds of :class:`_sql.FromClause` such as :class:`_sql.Subquery`, depending on how the class is mapped. .. seealso:: :ref:`orm_declarative_metadata` """ if typing.TYPE_CHECKING: def _sa_inspect_type(self) -> Mapper[Self]: ... def _sa_inspect_instance(self) -> InstanceState[Self]: ... __tablename__: Any """String name to assign to the generated :class:`_schema.Table` object, if not specified directly via :attr:`_orm.DeclarativeBase.__table__`. .. seealso:: :ref:`orm_declarative_table` """ __mapper_args__: Any """Dictionary of arguments which will be passed to the :class:`_orm.Mapper` constructor. .. seealso:: :ref:`orm_declarative_mapper_options` """ __table_args__: Any """A dictionary or tuple of arguments that will be passed to the :class:`_schema.Table` constructor. See :ref:`orm_declarative_table_configuration` for background on the specific structure of this collection. .. seealso:: :ref:`orm_declarative_table_configuration` """ def __init__(self, **kw: Any): ... def __init_subclass__(cls, **kw: Any) -> None: if DeclarativeBaseNoMeta in cls.__bases__: _check_not_declarative(cls, DeclarativeBaseNoMeta) _setup_declarative_base(cls) else: _as_declarative(cls._sa_registry, cls, cls.__dict__) super().__init_subclass__(**kw) def add_mapped_attribute( target: Type[_O], key: str, attr: MapperProperty[Any] ) -> None: """Add a new mapped attribute to an ORM mapped class. E.g.:: add_mapped_attribute(User, "addresses", relationship(Address)) This may be used for ORM mappings that aren't using a declarative metaclass that intercepts attribute set operations. .. versionadded:: 2.0 """ _add_attribute(target, key, attr) def declarative_base( *, metadata: Optional[MetaData] = None, mapper: Optional[Callable[..., Mapper[Any]]] = None, cls: Type[Any] = object, name: str = "Base", class_registry: Optional[clsregistry._ClsRegistryType] = None, type_annotation_map: Optional[_TypeAnnotationMapType] = None, constructor: Callable[..., None] = _declarative_constructor, metaclass: Type[Any] = DeclarativeMeta, ) -> Any: r"""Construct a base class for declarative class definitions. The new base class will be given a metaclass that produces appropriate :class:`~sqlalchemy.schema.Table` objects and makes the appropriate :class:`_orm.Mapper` calls based on the information provided declaratively in the class and any subclasses of the class. .. versionchanged:: 2.0 Note that the :func:`_orm.declarative_base` function is superseded by the new :class:`_orm.DeclarativeBase` class, which generates a new "base" class using subclassing, rather than return value of a function. This allows an approach that is compatible with :pep:`484` typing tools. The :func:`_orm.declarative_base` function is a shorthand version of using the :meth:`_orm.registry.generate_base` method. That is, the following:: from sqlalchemy.orm import declarative_base Base = declarative_base() Is equivalent to:: from sqlalchemy.orm import registry mapper_registry = registry() Base = mapper_registry.generate_base() See the docstring for :class:`_orm.registry` and :meth:`_orm.registry.generate_base` for more details. .. versionchanged:: 1.4 The :func:`_orm.declarative_base` function is now a specialization of the more generic :class:`_orm.registry` class. The function also moves to the ``sqlalchemy.orm`` package from the ``declarative.ext`` package. :param metadata: An optional :class:`~sqlalchemy.schema.MetaData` instance. All :class:`~sqlalchemy.schema.Table` objects implicitly declared by subclasses of the base will share this MetaData. A MetaData instance will be created if none is provided. The :class:`~sqlalchemy.schema.MetaData` instance will be available via the ``metadata`` attribute of the generated declarative base class. :param mapper: An optional callable, defaults to :class:`_orm.Mapper`. Will be used to map subclasses to their Tables. :param cls: Defaults to :class:`object`. A type to use as the base for the generated declarative base class. May be a class or tuple of classes. :param name: Defaults to ``Base``. The display name for the generated class. Customizing this is not required, but can improve clarity in tracebacks and debugging. :param constructor: Specify the implementation for the ``__init__`` function on a mapped class that has no ``__init__`` of its own. Defaults to an implementation that assigns \**kwargs for declared fields and relationships to an instance. If ``None`` is supplied, no __init__ will be provided and construction will fall back to cls.__init__ by way of the normal Python semantics. :param class_registry: optional dictionary that will serve as the registry of class names-> mapped classes when string names are used to identify classes inside of :func:`_orm.relationship` and others. Allows two or more declarative base classes to share the same registry of class names for simplified inter-base relationships. :param type_annotation_map: optional dictionary of Python types to SQLAlchemy :class:`_types.TypeEngine` classes or instances. This is used exclusively by the :class:`_orm.MappedColumn` construct to produce column types based on annotations within the :class:`_orm.Mapped` type. .. versionadded:: 2.0 .. seealso:: :ref:`orm_declarative_mapped_column_type_map` :param metaclass: Defaults to :class:`.DeclarativeMeta`. A metaclass or __metaclass__ compatible callable to use as the meta type of the generated declarative base class. .. seealso:: :class:`_orm.registry` """ return registry( metadata=metadata, class_registry=class_registry, constructor=constructor, type_annotation_map=type_annotation_map, ).generate_base( mapper=mapper, cls=cls, name=name, metaclass=metaclass, ) class registry: """Generalized registry for mapping classes. The :class:`_orm.registry` serves as the basis for maintaining a collection of mappings, and provides configurational hooks used to map classes. The three general kinds of mappings supported are Declarative Base, Declarative Decorator, and Imperative Mapping. All of these mapping styles may be used interchangeably: * :meth:`_orm.registry.generate_base` returns a new declarative base class, and is the underlying implementation of the :func:`_orm.declarative_base` function. * :meth:`_orm.registry.mapped` provides a class decorator that will apply declarative mapping to a class without the use of a declarative base class. * :meth:`_orm.registry.map_imperatively` will produce a :class:`_orm.Mapper` for a class without scanning the class for declarative class attributes. This method suits the use case historically provided by the ``sqlalchemy.orm.mapper()`` classical mapping function, which is removed as of SQLAlchemy 2.0. .. versionadded:: 1.4 .. seealso:: :ref:`orm_mapping_classes_toplevel` - overview of class mapping styles. """ _class_registry: clsregistry._ClsRegistryType _managers: weakref.WeakKeyDictionary[ClassManager[Any], Literal[True]] _non_primary_mappers: weakref.WeakKeyDictionary[Mapper[Any], Literal[True]] metadata: MetaData constructor: CallableReference[Callable[..., None]] type_annotation_map: _MutableTypeAnnotationMapType _dependents: Set[_RegistryType] _dependencies: Set[_RegistryType] _new_mappers: bool def __init__( self, *, metadata: Optional[MetaData] = None, class_registry: Optional[clsregistry._ClsRegistryType] = None, type_annotation_map: Optional[_TypeAnnotationMapType] = None, constructor: Callable[..., None] = _declarative_constructor, ): r"""Construct a new :class:`_orm.registry` :param metadata: An optional :class:`_schema.MetaData` instance. All :class:`_schema.Table` objects generated using declarative table mapping will make use of this :class:`_schema.MetaData` collection. If this argument is left at its default of ``None``, a blank :class:`_schema.MetaData` collection is created. :param constructor: Specify the implementation for the ``__init__`` function on a mapped class that has no ``__init__`` of its own. Defaults to an implementation that assigns \**kwargs for declared fields and relationships to an instance. If ``None`` is supplied, no __init__ will be provided and construction will fall back to cls.__init__ by way of the normal Python semantics. :param class_registry: optional dictionary that will serve as the registry of class names-> mapped classes when string names are used to identify classes inside of :func:`_orm.relationship` and others. Allows two or more declarative base classes to share the same registry of class names for simplified inter-base relationships. :param type_annotation_map: optional dictionary of Python types to SQLAlchemy :class:`_types.TypeEngine` classes or instances. The provided dict will update the default type mapping. This is used exclusively by the :class:`_orm.MappedColumn` construct to produce column types based on annotations within the :class:`_orm.Mapped` type. .. versionadded:: 2.0 .. seealso:: :ref:`orm_declarative_mapped_column_type_map` """ lcl_metadata = metadata or MetaData() if class_registry is None: class_registry = weakref.WeakValueDictionary() self._class_registry = class_registry self._managers = weakref.WeakKeyDictionary() self._non_primary_mappers = weakref.WeakKeyDictionary() self.metadata = lcl_metadata self.constructor = constructor self.type_annotation_map = {} if type_annotation_map is not None: self.update_type_annotation_map(type_annotation_map) self._dependents = set() self._dependencies = set() self._new_mappers = False with mapperlib._CONFIGURE_MUTEX: mapperlib._mapper_registries[self] = True def update_type_annotation_map( self, type_annotation_map: _TypeAnnotationMapType, ) -> None: """update the :paramref:`_orm.registry.type_annotation_map` with new values.""" self.type_annotation_map.update( { de_optionalize_union_types(typ): sqltype for typ, sqltype in type_annotation_map.items() } ) def _resolve_type( self, python_type: _MatchedOnType, _do_fallbacks: bool = True ) -> Optional[sqltypes.TypeEngine[Any]]: python_type_type: Type[Any] search: Iterable[Tuple[_MatchedOnType, Type[Any]]] if is_generic(python_type): if is_literal(python_type): python_type_type = python_type # type: ignore[assignment] search = ( (python_type, python_type_type), *((lt, python_type_type) for lt in LITERAL_TYPES), ) else: python_type_type = python_type.__origin__ search = ((python_type, python_type_type),) elif isinstance(python_type, type): python_type_type = python_type search = ((pt, pt) for pt in python_type_type.__mro__) else: python_type_type = python_type # type: ignore[assignment] search = ((python_type, python_type_type),) for pt, flattened in search: # we search through full __mro__ for types. however... sql_type = self.type_annotation_map.get(pt) if sql_type is None: sql_type = sqltypes._type_map_get(pt) # type: ignore # noqa: E501 if sql_type is not None: sql_type_inst = sqltypes.to_instance(sql_type) # ... this additional step will reject most # type -> supertype matches, such as if we had # a MyInt(int) subclass. note also we pass NewType() # here directly; these always have to be in the # type_annotation_map to be useful resolved_sql_type = sql_type_inst._resolve_for_python_type( python_type_type, pt, flattened, ) if resolved_sql_type is not None: return resolved_sql_type # 2.0 fallbacks if _do_fallbacks: python_type_to_check: Any = None kind = None if is_pep695(python_type): # NOTE: assume there aren't type alias types of new types. python_type_to_check = python_type while is_pep695(python_type_to_check): python_type_to_check = python_type_to_check.__value__ python_type_to_check = de_optionalize_union_types( python_type_to_check ) kind = "TypeAliasType" if is_newtype(python_type): python_type_to_check = flatten_newtype(python_type) kind = "NewType" if python_type_to_check is not None: res_after_fallback = self._resolve_type( python_type_to_check, False ) if res_after_fallback is not None: assert kind is not None warn_deprecated( f"Matching the provided {kind} '{python_type}' on " "its resolved value without matching it in the " "type_annotation_map is deprecated; add this type to " "the type_annotation_map to allow it to match " "explicitly.", "2.0", ) return res_after_fallback return None @property def mappers(self) -> FrozenSet[Mapper[Any]]: """read only collection of all :class:`_orm.Mapper` objects.""" return frozenset(manager.mapper for manager in self._managers).union( self._non_primary_mappers ) def _set_depends_on(self, registry: RegistryType) -> None: if registry is self: return registry._dependents.add(self) self._dependencies.add(registry) def _flag_new_mapper(self, mapper: Mapper[Any]) -> None: mapper._ready_for_configure = True if self._new_mappers: return for reg in self._recurse_with_dependents({self}): reg._new_mappers = True @classmethod def _recurse_with_dependents( cls, registries: Set[RegistryType] ) -> Iterator[RegistryType]: todo = registries done = set() while todo: reg = todo.pop() done.add(reg) # if yielding would remove dependents, make sure we have # them before todo.update(reg._dependents.difference(done)) yield reg # if yielding would add dependents, make sure we have them # after todo.update(reg._dependents.difference(done)) @classmethod def _recurse_with_dependencies( cls, registries: Set[RegistryType] ) -> Iterator[RegistryType]: todo = registries done = set() while todo: reg = todo.pop() done.add(reg) # if yielding would remove dependencies, make sure we have # them before todo.update(reg._dependencies.difference(done)) yield reg # if yielding would remove dependencies, make sure we have # them before todo.update(reg._dependencies.difference(done)) def _mappers_to_configure(self) -> Iterator[Mapper[Any]]: return itertools.chain( ( manager.mapper for manager in list(self._managers) if manager.is_mapped and not manager.mapper.configured and manager.mapper._ready_for_configure ), ( npm for npm in list(self._non_primary_mappers) if not npm.configured and npm._ready_for_configure ), ) def _add_non_primary_mapper(self, np_mapper: Mapper[Any]) -> None: self._non_primary_mappers[np_mapper] = True def _dispose_cls(self, cls: Type[_O]) -> None: clsregistry.remove_class(cls.__name__, cls, self._class_registry) def _add_manager(self, manager: ClassManager[Any]) -> None: self._managers[manager] = True if manager.is_mapped: raise exc.ArgumentError( "Class '%s' already has a primary mapper defined. " % manager.class_ ) assert manager.registry is None manager.registry = self def configure(self, cascade: bool = False) -> None: """Configure all as-yet unconfigured mappers in this :class:`_orm.registry`. The configure step is used to reconcile and initialize the :func:`_orm.relationship` linkages between mapped classes, as well as to invoke configuration events such as the :meth:`_orm.MapperEvents.before_configured` and :meth:`_orm.MapperEvents.after_configured`, which may be used by ORM extensions or user-defined extension hooks. If one or more mappers in this registry contain :func:`_orm.relationship` constructs that refer to mapped classes in other registries, this registry is said to be *dependent* on those registries. In order to configure those dependent registries automatically, the :paramref:`_orm.registry.configure.cascade` flag should be set to ``True``. Otherwise, if they are not configured, an exception will be raised. The rationale behind this behavior is to allow an application to programmatically invoke configuration of registries while controlling whether or not the process implicitly reaches other registries. As an alternative to invoking :meth:`_orm.registry.configure`, the ORM function :func:`_orm.configure_mappers` function may be used to ensure configuration is complete for all :class:`_orm.registry` objects in memory. This is generally simpler to use and also predates the usage of :class:`_orm.registry` objects overall. However, this function will impact all mappings throughout the running Python process and may be more memory/time consuming for an application that has many registries in use for different purposes that may not be needed immediately. .. seealso:: :func:`_orm.configure_mappers` .. versionadded:: 1.4.0b2 """ mapperlib._configure_registries({self}, cascade=cascade) def dispose(self, cascade: bool = False) -> None: """Dispose of all mappers in this :class:`_orm.registry`. After invocation, all the classes that were mapped within this registry will no longer have class instrumentation associated with them. This method is the per-:class:`_orm.registry` analogue to the application-wide :func:`_orm.clear_mappers` function. If this registry contains mappers that are dependencies of other registries, typically via :func:`_orm.relationship` links, then those registries must be disposed as well. When such registries exist in relation to this one, their :meth:`_orm.registry.dispose` method will also be called, if the :paramref:`_orm.registry.dispose.cascade` flag is set to ``True``; otherwise, an error is raised if those registries were not already disposed. .. versionadded:: 1.4.0b2 .. seealso:: :func:`_orm.clear_mappers` """ mapperlib._dispose_registries({self}, cascade=cascade) def _dispose_manager_and_mapper(self, manager: ClassManager[Any]) -> None: if "mapper" in manager.__dict__: mapper = manager.mapper mapper._set_dispose_flags() class_ = manager.class_ self._dispose_cls(class_) instrumentation._instrumentation_factory.unregister(class_) def generate_base( self, mapper: Optional[Callable[..., Mapper[Any]]] = None, cls: Type[Any] = object, name: str = "Base", metaclass: Type[Any] = DeclarativeMeta, ) -> Any: """Generate a declarative base class. Classes that inherit from the returned class object will be automatically mapped using declarative mapping. E.g.:: from sqlalchemy.orm import registry mapper_registry = registry() Base = mapper_registry.generate_base() class MyClass(Base): __tablename__ = "my_table" id = Column(Integer, primary_key=True) The above dynamically generated class is equivalent to the non-dynamic example below:: from sqlalchemy.orm import registry from sqlalchemy.orm.decl_api import DeclarativeMeta mapper_registry = registry() class Base(metaclass=DeclarativeMeta): __abstract__ = True registry = mapper_registry metadata = mapper_registry.metadata __init__ = mapper_registry.constructor .. versionchanged:: 2.0 Note that the :meth:`_orm.registry.generate_base` method is superseded by the new :class:`_orm.DeclarativeBase` class, which generates a new "base" class using subclassing, rather than return value of a function. This allows an approach that is compatible with :pep:`484` typing tools. The :meth:`_orm.registry.generate_base` method provides the implementation for the :func:`_orm.declarative_base` function, which creates the :class:`_orm.registry` and base class all at once. See the section :ref:`orm_declarative_mapping` for background and examples. :param mapper: An optional callable, defaults to :class:`_orm.Mapper`. This function is used to generate new :class:`_orm.Mapper` objects. :param cls: Defaults to :class:`object`. A type to use as the base for the generated declarative base class. May be a class or tuple of classes. :param name: Defaults to ``Base``. The display name for the generated class. Customizing this is not required, but can improve clarity in tracebacks and debugging. :param metaclass: Defaults to :class:`.DeclarativeMeta`. A metaclass or __metaclass__ compatible callable to use as the meta type of the generated declarative base class. .. seealso:: :ref:`orm_declarative_mapping` :func:`_orm.declarative_base` """ metadata = self.metadata bases = not isinstance(cls, tuple) and (cls,) or cls class_dict: Dict[str, Any] = dict(registry=self, metadata=metadata) if isinstance(cls, type): class_dict["__doc__"] = cls.__doc__ if self.constructor is not None: class_dict["__init__"] = self.constructor class_dict["__abstract__"] = True if mapper: class_dict["__mapper_cls__"] = mapper if hasattr(cls, "__class_getitem__"): def __class_getitem__(cls: Type[_T], key: Any) -> Type[_T]: # allow generic classes in py3.9+ return cls class_dict["__class_getitem__"] = __class_getitem__ return metaclass(name, bases, class_dict) @compat_typing.dataclass_transform( field_specifiers=( MappedColumn, RelationshipProperty, Composite, Synonym, mapped_column, relationship, composite, synonym, deferred, ), ) @overload def mapped_as_dataclass(self, __cls: Type[_O]) -> Type[_O]: ... @overload def mapped_as_dataclass( self, __cls: Literal[None] = ..., *, init: Union[_NoArg, bool] = ..., repr: Union[_NoArg, bool] = ..., # noqa: A002 eq: Union[_NoArg, bool] = ..., order: Union[_NoArg, bool] = ..., unsafe_hash: Union[_NoArg, bool] = ..., match_args: Union[_NoArg, bool] = ..., kw_only: Union[_NoArg, bool] = ..., dataclass_callable: Union[_NoArg, Callable[..., Type[Any]]] = ..., ) -> Callable[[Type[_O]], Type[_O]]: ... def mapped_as_dataclass( self, __cls: Optional[Type[_O]] = None, *, init: Union[_NoArg, bool] = _NoArg.NO_ARG, repr: Union[_NoArg, bool] = _NoArg.NO_ARG, # noqa: A002 eq: Union[_NoArg, bool] = _NoArg.NO_ARG, order: Union[_NoArg, bool] = _NoArg.NO_ARG, unsafe_hash: Union[_NoArg, bool] = _NoArg.NO_ARG, match_args: Union[_NoArg, bool] = _NoArg.NO_ARG, kw_only: Union[_NoArg, bool] = _NoArg.NO_ARG, dataclass_callable: Union[ _NoArg, Callable[..., Type[Any]] ] = _NoArg.NO_ARG, ) -> Union[Type[_O], Callable[[Type[_O]], Type[_O]]]: """Class decorator that will apply the Declarative mapping process to a given class, and additionally convert the class to be a Python dataclass. .. seealso:: :ref:`orm_declarative_native_dataclasses` - complete background on SQLAlchemy native dataclass mapping .. versionadded:: 2.0 """ def decorate(cls: Type[_O]) -> Type[_O]: setattr( cls, "_sa_apply_dc_transforms", { "init": init, "repr": repr, "eq": eq, "order": order, "unsafe_hash": unsafe_hash, "match_args": match_args, "kw_only": kw_only, "dataclass_callable": dataclass_callable, }, ) _as_declarative(self, cls, cls.__dict__) return cls if __cls: return decorate(__cls) else: return decorate def mapped(self, cls: Type[_O]) -> Type[_O]: """Class decorator that will apply the Declarative mapping process to a given class. E.g.:: from sqlalchemy.orm import registry mapper_registry = registry() @mapper_registry.mapped class Foo: __tablename__ = "some_table" id = Column(Integer, primary_key=True) name = Column(String) See the section :ref:`orm_declarative_mapping` for complete details and examples. :param cls: class to be mapped. :return: the class that was passed. .. seealso:: :ref:`orm_declarative_mapping` :meth:`_orm.registry.generate_base` - generates a base class that will apply Declarative mapping to subclasses automatically using a Python metaclass. .. seealso:: :meth:`_orm.registry.mapped_as_dataclass` """ _as_declarative(self, cls, cls.__dict__) return cls def as_declarative_base(self, **kw: Any) -> Callable[[Type[_T]], Type[_T]]: """ Class decorator which will invoke :meth:`_orm.registry.generate_base` for a given base class. E.g.:: from sqlalchemy.orm import registry mapper_registry = registry() @mapper_registry.as_declarative_base() class Base: @declared_attr def __tablename__(cls): return cls.__name__.lower() id = Column(Integer, primary_key=True) class MyMappedClass(Base): ... All keyword arguments passed to :meth:`_orm.registry.as_declarative_base` are passed along to :meth:`_orm.registry.generate_base`. """ def decorate(cls: Type[_T]) -> Type[_T]: kw["cls"] = cls kw["name"] = cls.__name__ return self.generate_base(**kw) # type: ignore return decorate def map_declaratively(self, cls: Type[_O]) -> Mapper[_O]: """Map a class declaratively. In this form of mapping, the class is scanned for mapping information, including for columns to be associated with a table, and/or an actual table object. Returns the :class:`_orm.Mapper` object. E.g.:: from sqlalchemy.orm import registry mapper_registry = registry() class Foo: __tablename__ = "some_table" id = Column(Integer, primary_key=True) name = Column(String) mapper = mapper_registry.map_declaratively(Foo) This function is more conveniently invoked indirectly via either the :meth:`_orm.registry.mapped` class decorator or by subclassing a declarative metaclass generated from :meth:`_orm.registry.generate_base`. See the section :ref:`orm_declarative_mapping` for complete details and examples. :param cls: class to be mapped. :return: a :class:`_orm.Mapper` object. .. seealso:: :ref:`orm_declarative_mapping` :meth:`_orm.registry.mapped` - more common decorator interface to this function. :meth:`_orm.registry.map_imperatively` """ _as_declarative(self, cls, cls.__dict__) return cls.__mapper__ # type: ignore def map_imperatively( self, class_: Type[_O], local_table: Optional[FromClause] = None, **kw: Any, ) -> Mapper[_O]: r"""Map a class imperatively. In this form of mapping, the class is not scanned for any mapping information. Instead, all mapping constructs are passed as arguments. This method is intended to be fully equivalent to the now-removed SQLAlchemy ``mapper()`` function, except that it's in terms of a particular registry. E.g.:: from sqlalchemy.orm import registry mapper_registry = registry() my_table = Table( "my_table", mapper_registry.metadata, Column("id", Integer, primary_key=True), ) class MyClass: pass mapper_registry.map_imperatively(MyClass, my_table) See the section :ref:`orm_imperative_mapping` for complete background and usage examples. :param class\_: The class to be mapped. Corresponds to the :paramref:`_orm.Mapper.class_` parameter. :param local_table: the :class:`_schema.Table` or other :class:`_sql.FromClause` object that is the subject of the mapping. Corresponds to the :paramref:`_orm.Mapper.local_table` parameter. :param \**kw: all other keyword arguments are passed to the :class:`_orm.Mapper` constructor directly. .. seealso:: :ref:`orm_imperative_mapping` :ref:`orm_declarative_mapping` """ return _mapper(self, class_, local_table, kw) RegistryType = registry if not TYPE_CHECKING: # allow for runtime type resolution of ``ClassVar[_RegistryType]`` _RegistryType = registry # noqa def as_declarative(**kw: Any) -> Callable[[Type[_T]], Type[_T]]: """ Class decorator which will adapt a given class into a :func:`_orm.declarative_base`. This function makes use of the :meth:`_orm.registry.as_declarative_base` method, by first creating a :class:`_orm.registry` automatically and then invoking the decorator. E.g.:: from sqlalchemy.orm import as_declarative @as_declarative() class Base: @declared_attr def __tablename__(cls): return cls.__name__.lower() id = Column(Integer, primary_key=True) class MyMappedClass(Base): ... .. seealso:: :meth:`_orm.registry.as_declarative_base` """ metadata, class_registry = ( kw.pop("metadata", None), kw.pop("class_registry", None), ) return registry( metadata=metadata, class_registry=class_registry ).as_declarative_base(**kw) @inspection._inspects( DeclarativeMeta, DeclarativeBase, DeclarativeAttributeIntercept ) def _inspect_decl_meta(cls: Type[Any]) -> Optional[Mapper[Any]]: mp: Optional[Mapper[Any]] = _inspect_mapped_class(cls) if mp is None: if _DeferredMapperConfig.has_cls(cls): _DeferredMapperConfig.raise_unmapped_for_cls(cls) return mp sqlalchemy/orm/__init__.py 0000755 00000020417 15125143220 0011616 0 ustar 00 # orm/__init__.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """ Functional constructs for ORM configuration. See the SQLAlchemy object relational tutorial and mapper configuration documentation for an overview of how this module is used. """ from __future__ import annotations from typing import Any from . import exc as exc from . import mapper as mapperlib from . import strategy_options as strategy_options from ._orm_constructors import _mapper_fn as mapper from ._orm_constructors import aliased as aliased from ._orm_constructors import backref as backref from ._orm_constructors import clear_mappers as clear_mappers from ._orm_constructors import column_property as column_property from ._orm_constructors import composite as composite from ._orm_constructors import contains_alias as contains_alias from ._orm_constructors import create_session as create_session from ._orm_constructors import deferred as deferred from ._orm_constructors import dynamic_loader as dynamic_loader from ._orm_constructors import join as join from ._orm_constructors import mapped_column as mapped_column from ._orm_constructors import orm_insert_sentinel as orm_insert_sentinel from ._orm_constructors import outerjoin as outerjoin from ._orm_constructors import query_expression as query_expression from ._orm_constructors import relationship as relationship from ._orm_constructors import synonym as synonym from ._orm_constructors import with_loader_criteria as with_loader_criteria from ._orm_constructors import with_polymorphic as with_polymorphic from .attributes import AttributeEventToken as AttributeEventToken from .attributes import InstrumentedAttribute as InstrumentedAttribute from .attributes import QueryableAttribute as QueryableAttribute from .base import class_mapper as class_mapper from .base import DynamicMapped as DynamicMapped from .base import InspectionAttrExtensionType as InspectionAttrExtensionType from .base import LoaderCallableStatus as LoaderCallableStatus from .base import Mapped as Mapped from .base import NotExtension as NotExtension from .base import ORMDescriptor as ORMDescriptor from .base import PassiveFlag as PassiveFlag from .base import SQLORMExpression as SQLORMExpression from .base import WriteOnlyMapped as WriteOnlyMapped from .context import FromStatement as FromStatement from .context import QueryContext as QueryContext from .decl_api import add_mapped_attribute as add_mapped_attribute from .decl_api import as_declarative as as_declarative from .decl_api import declarative_base as declarative_base from .decl_api import declarative_mixin as declarative_mixin from .decl_api import DeclarativeBase as DeclarativeBase from .decl_api import DeclarativeBaseNoMeta as DeclarativeBaseNoMeta from .decl_api import DeclarativeMeta as DeclarativeMeta from .decl_api import declared_attr as declared_attr from .decl_api import has_inherited_table as has_inherited_table from .decl_api import MappedAsDataclass as MappedAsDataclass from .decl_api import registry as registry from .decl_api import synonym_for as synonym_for from .decl_base import MappedClassProtocol as MappedClassProtocol from .descriptor_props import Composite as Composite from .descriptor_props import CompositeProperty as CompositeProperty from .descriptor_props import Synonym as Synonym from .descriptor_props import SynonymProperty as SynonymProperty from .dynamic import AppenderQuery as AppenderQuery from .events import AttributeEvents as AttributeEvents from .events import InstanceEvents as InstanceEvents from .events import InstrumentationEvents as InstrumentationEvents from .events import MapperEvents as MapperEvents from .events import QueryEvents as QueryEvents from .events import SessionEvents as SessionEvents from .identity import IdentityMap as IdentityMap from .instrumentation import ClassManager as ClassManager from .interfaces import EXT_CONTINUE as EXT_CONTINUE from .interfaces import EXT_SKIP as EXT_SKIP from .interfaces import EXT_STOP as EXT_STOP from .interfaces import InspectionAttr as InspectionAttr from .interfaces import InspectionAttrInfo as InspectionAttrInfo from .interfaces import MANYTOMANY as MANYTOMANY from .interfaces import MANYTOONE as MANYTOONE from .interfaces import MapperProperty as MapperProperty from .interfaces import NO_KEY as NO_KEY from .interfaces import NO_VALUE as NO_VALUE from .interfaces import ONETOMANY as ONETOMANY from .interfaces import PropComparator as PropComparator from .interfaces import RelationshipDirection as RelationshipDirection from .interfaces import UserDefinedOption as UserDefinedOption from .loading import merge_frozen_result as merge_frozen_result from .loading import merge_result as merge_result from .mapped_collection import attribute_keyed_dict as attribute_keyed_dict from .mapped_collection import ( attribute_mapped_collection as attribute_mapped_collection, ) from .mapped_collection import column_keyed_dict as column_keyed_dict from .mapped_collection import ( column_mapped_collection as column_mapped_collection, ) from .mapped_collection import keyfunc_mapping as keyfunc_mapping from .mapped_collection import KeyFuncDict as KeyFuncDict from .mapped_collection import mapped_collection as mapped_collection from .mapped_collection import MappedCollection as MappedCollection from .mapper import configure_mappers as configure_mappers from .mapper import Mapper as Mapper from .mapper import reconstructor as reconstructor from .mapper import validates as validates from .properties import ColumnProperty as ColumnProperty from .properties import MappedColumn as MappedColumn from .properties import MappedSQLExpression as MappedSQLExpression from .query import AliasOption as AliasOption from .query import Query as Query from .relationships import foreign as foreign from .relationships import Relationship as Relationship from .relationships import RelationshipProperty as RelationshipProperty from .relationships import remote as remote from .scoping import QueryPropertyDescriptor as QueryPropertyDescriptor from .scoping import scoped_session as scoped_session from .session import close_all_sessions as close_all_sessions from .session import make_transient as make_transient from .session import make_transient_to_detached as make_transient_to_detached from .session import object_session as object_session from .session import ORMExecuteState as ORMExecuteState from .session import Session as Session from .session import sessionmaker as sessionmaker from .session import SessionTransaction as SessionTransaction from .session import SessionTransactionOrigin as SessionTransactionOrigin from .state import AttributeState as AttributeState from .state import InstanceState as InstanceState from .strategy_options import contains_eager as contains_eager from .strategy_options import defaultload as defaultload from .strategy_options import defer as defer from .strategy_options import immediateload as immediateload from .strategy_options import joinedload as joinedload from .strategy_options import lazyload as lazyload from .strategy_options import Load as Load from .strategy_options import load_only as load_only from .strategy_options import noload as noload from .strategy_options import raiseload as raiseload from .strategy_options import selectin_polymorphic as selectin_polymorphic from .strategy_options import selectinload as selectinload from .strategy_options import subqueryload as subqueryload from .strategy_options import undefer as undefer from .strategy_options import undefer_group as undefer_group from .strategy_options import with_expression as with_expression from .unitofwork import UOWTransaction as UOWTransaction from .util import Bundle as Bundle from .util import CascadeOptions as CascadeOptions from .util import LoaderCriteriaOption as LoaderCriteriaOption from .util import object_mapper as object_mapper from .util import polymorphic_union as polymorphic_union from .util import was_deleted as was_deleted from .util import with_parent as with_parent from .writeonly import WriteOnlyCollection as WriteOnlyCollection from .. import util as _sa_util def __go(lcls: Any) -> None: _sa_util.preloaded.import_prefix("sqlalchemy.orm") _sa_util.preloaded.import_prefix("sqlalchemy.ext") __go(locals()) sqlalchemy/orm/clsregistry.py 0000755 00000043040 15125143220 0012426 0 ustar 00 # orm/clsregistry.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """Routines to handle the string class registry used by declarative. This system allows specification of classes and expressions used in :func:`_orm.relationship` using strings. """ from __future__ import annotations import re from typing import Any from typing import Callable from typing import cast from typing import Dict from typing import Generator from typing import Iterable from typing import List from typing import Mapping from typing import MutableMapping from typing import NoReturn from typing import Optional from typing import Set from typing import Tuple from typing import Type from typing import TYPE_CHECKING from typing import TypeVar from typing import Union import weakref from . import attributes from . import interfaces from .descriptor_props import SynonymProperty from .properties import ColumnProperty from .util import class_mapper from .. import exc from .. import inspection from .. import util from ..sql.schema import _get_table_key from ..util.typing import CallableReference if TYPE_CHECKING: from .relationships import RelationshipProperty from ..sql.schema import MetaData from ..sql.schema import Table _T = TypeVar("_T", bound=Any) _ClsRegistryType = MutableMapping[str, Union[type, "ClsRegistryToken"]] # strong references to registries which we place in # the _decl_class_registry, which is usually weak referencing. # the internal registries here link to classes with weakrefs and remove # themselves when all references to contained classes are removed. _registries: Set[ClsRegistryToken] = set() def add_class( classname: str, cls: Type[_T], decl_class_registry: _ClsRegistryType ) -> None: """Add a class to the _decl_class_registry associated with the given declarative class. """ if classname in decl_class_registry: # class already exists. existing = decl_class_registry[classname] if not isinstance(existing, _MultipleClassMarker): decl_class_registry[classname] = _MultipleClassMarker( [cls, cast("Type[Any]", existing)] ) else: decl_class_registry[classname] = cls try: root_module = cast( _ModuleMarker, decl_class_registry["_sa_module_registry"] ) except KeyError: decl_class_registry["_sa_module_registry"] = root_module = ( _ModuleMarker("_sa_module_registry", None) ) tokens = cls.__module__.split(".") # build up a tree like this: # modulename: myapp.snacks.nuts # # myapp->snack->nuts->(classes) # snack->nuts->(classes) # nuts->(classes) # # this allows partial token paths to be used. while tokens: token = tokens.pop(0) module = root_module.get_module(token) for token in tokens: module = module.get_module(token) try: module.add_class(classname, cls) except AttributeError as ae: if not isinstance(module, _ModuleMarker): raise exc.InvalidRequestError( f'name "{classname}" matches both a ' "class name and a module name" ) from ae else: raise def remove_class( classname: str, cls: Type[Any], decl_class_registry: _ClsRegistryType ) -> None: if classname in decl_class_registry: existing = decl_class_registry[classname] if isinstance(existing, _MultipleClassMarker): existing.remove_item(cls) else: del decl_class_registry[classname] try: root_module = cast( _ModuleMarker, decl_class_registry["_sa_module_registry"] ) except KeyError: return tokens = cls.__module__.split(".") while tokens: token = tokens.pop(0) module = root_module.get_module(token) for token in tokens: module = module.get_module(token) try: module.remove_class(classname, cls) except AttributeError: if not isinstance(module, _ModuleMarker): pass else: raise def _key_is_empty( key: str, decl_class_registry: _ClsRegistryType, test: Callable[[Any], bool], ) -> bool: """test if a key is empty of a certain object. used for unit tests against the registry to see if garbage collection is working. "test" is a callable that will be passed an object should return True if the given object is the one we were looking for. We can't pass the actual object itself b.c. this is for testing garbage collection; the caller will have to have removed references to the object itself. """ if key not in decl_class_registry: return True thing = decl_class_registry[key] if isinstance(thing, _MultipleClassMarker): for sub_thing in thing.contents: if test(sub_thing): return False else: raise NotImplementedError("unknown codepath") else: return not test(thing) class ClsRegistryToken: """an object that can be in the registry._class_registry as a value.""" __slots__ = () class _MultipleClassMarker(ClsRegistryToken): """refers to multiple classes of the same name within _decl_class_registry. """ __slots__ = "on_remove", "contents", "__weakref__" contents: Set[weakref.ref[Type[Any]]] on_remove: CallableReference[Optional[Callable[[], None]]] def __init__( self, classes: Iterable[Type[Any]], on_remove: Optional[Callable[[], None]] = None, ): self.on_remove = on_remove self.contents = { weakref.ref(item, self._remove_item) for item in classes } _registries.add(self) def remove_item(self, cls: Type[Any]) -> None: self._remove_item(weakref.ref(cls)) def __iter__(self) -> Generator[Optional[Type[Any]], None, None]: return (ref() for ref in self.contents) def attempt_get(self, path: List[str], key: str) -> Type[Any]: if len(self.contents) > 1: raise exc.InvalidRequestError( 'Multiple classes found for path "%s" ' "in the registry of this declarative " "base. Please use a fully module-qualified path." % (".".join(path + [key])) ) else: ref = list(self.contents)[0] cls = ref() if cls is None: raise NameError(key) return cls def _remove_item(self, ref: weakref.ref[Type[Any]]) -> None: self.contents.discard(ref) if not self.contents: _registries.discard(self) if self.on_remove: self.on_remove() def add_item(self, item: Type[Any]) -> None: # protect against class registration race condition against # asynchronous garbage collection calling _remove_item, # [ticket:3208] and [ticket:10782] modules = { cls.__module__ for cls in [ref() for ref in list(self.contents)] if cls is not None } if item.__module__ in modules: util.warn( "This declarative base already contains a class with the " "same class name and module name as %s.%s, and will " "be replaced in the string-lookup table." % (item.__module__, item.__name__) ) self.contents.add(weakref.ref(item, self._remove_item)) class _ModuleMarker(ClsRegistryToken): """Refers to a module name within _decl_class_registry. """ __slots__ = "parent", "name", "contents", "mod_ns", "path", "__weakref__" parent: Optional[_ModuleMarker] contents: Dict[str, Union[_ModuleMarker, _MultipleClassMarker]] mod_ns: _ModNS path: List[str] def __init__(self, name: str, parent: Optional[_ModuleMarker]): self.parent = parent self.name = name self.contents = {} self.mod_ns = _ModNS(self) if self.parent: self.path = self.parent.path + [self.name] else: self.path = [] _registries.add(self) def __contains__(self, name: str) -> bool: return name in self.contents def __getitem__(self, name: str) -> ClsRegistryToken: return self.contents[name] def _remove_item(self, name: str) -> None: self.contents.pop(name, None) if not self.contents: if self.parent is not None: self.parent._remove_item(self.name) _registries.discard(self) def resolve_attr(self, key: str) -> Union[_ModNS, Type[Any]]: return self.mod_ns.__getattr__(key) def get_module(self, name: str) -> _ModuleMarker: if name not in self.contents: marker = _ModuleMarker(name, self) self.contents[name] = marker else: marker = cast(_ModuleMarker, self.contents[name]) return marker def add_class(self, name: str, cls: Type[Any]) -> None: if name in self.contents: existing = cast(_MultipleClassMarker, self.contents[name]) try: existing.add_item(cls) except AttributeError as ae: if not isinstance(existing, _MultipleClassMarker): raise exc.InvalidRequestError( f'name "{name}" matches both a ' "class name and a module name" ) from ae else: raise else: self.contents[name] = _MultipleClassMarker( [cls], on_remove=lambda: self._remove_item(name) ) def remove_class(self, name: str, cls: Type[Any]) -> None: if name in self.contents: existing = cast(_MultipleClassMarker, self.contents[name]) existing.remove_item(cls) class _ModNS: __slots__ = ("__parent",) __parent: _ModuleMarker def __init__(self, parent: _ModuleMarker): self.__parent = parent def __getattr__(self, key: str) -> Union[_ModNS, Type[Any]]: try: value = self.__parent.contents[key] except KeyError: pass else: if value is not None: if isinstance(value, _ModuleMarker): return value.mod_ns else: assert isinstance(value, _MultipleClassMarker) return value.attempt_get(self.__parent.path, key) raise NameError( "Module %r has no mapped classes " "registered under the name %r" % (self.__parent.name, key) ) class _GetColumns: __slots__ = ("cls",) cls: Type[Any] def __init__(self, cls: Type[Any]): self.cls = cls def __getattr__(self, key: str) -> Any: mp = class_mapper(self.cls, configure=False) if mp: if key not in mp.all_orm_descriptors: raise AttributeError( "Class %r does not have a mapped column named %r" % (self.cls, key) ) desc = mp.all_orm_descriptors[key] if desc.extension_type is interfaces.NotExtension.NOT_EXTENSION: assert isinstance(desc, attributes.QueryableAttribute) prop = desc.property if isinstance(prop, SynonymProperty): key = prop.name elif not isinstance(prop, ColumnProperty): raise exc.InvalidRequestError( "Property %r is not an instance of" " ColumnProperty (i.e. does not correspond" " directly to a Column)." % key ) return getattr(self.cls, key) inspection._inspects(_GetColumns)( lambda target: inspection.inspect(target.cls) ) class _GetTable: __slots__ = "key", "metadata" key: str metadata: MetaData def __init__(self, key: str, metadata: MetaData): self.key = key self.metadata = metadata def __getattr__(self, key: str) -> Table: return self.metadata.tables[_get_table_key(key, self.key)] def _determine_container(key: str, value: Any) -> _GetColumns: if isinstance(value, _MultipleClassMarker): value = value.attempt_get([], key) return _GetColumns(value) class _class_resolver: __slots__ = ( "cls", "prop", "arg", "fallback", "_dict", "_resolvers", "favor_tables", ) cls: Type[Any] prop: RelationshipProperty[Any] fallback: Mapping[str, Any] arg: str favor_tables: bool _resolvers: Tuple[Callable[[str], Any], ...] def __init__( self, cls: Type[Any], prop: RelationshipProperty[Any], fallback: Mapping[str, Any], arg: str, favor_tables: bool = False, ): self.cls = cls self.prop = prop self.arg = arg self.fallback = fallback self._dict = util.PopulateDict(self._access_cls) self._resolvers = () self.favor_tables = favor_tables def _access_cls(self, key: str) -> Any: cls = self.cls manager = attributes.manager_of_class(cls) decl_base = manager.registry assert decl_base is not None decl_class_registry = decl_base._class_registry metadata = decl_base.metadata if self.favor_tables: if key in metadata.tables: return metadata.tables[key] elif key in metadata._schemas: return _GetTable(key, getattr(cls, "metadata", metadata)) if key in decl_class_registry: return _determine_container(key, decl_class_registry[key]) if not self.favor_tables: if key in metadata.tables: return metadata.tables[key] elif key in metadata._schemas: return _GetTable(key, getattr(cls, "metadata", metadata)) if "_sa_module_registry" in decl_class_registry and key in cast( _ModuleMarker, decl_class_registry["_sa_module_registry"] ): registry = cast( _ModuleMarker, decl_class_registry["_sa_module_registry"] ) return registry.resolve_attr(key) elif self._resolvers: for resolv in self._resolvers: value = resolv(key) if value is not None: return value return self.fallback[key] def _raise_for_name(self, name: str, err: Exception) -> NoReturn: generic_match = re.match(r"(.+)\[(.+)\]", name) if generic_match: clsarg = generic_match.group(2).strip("'") raise exc.InvalidRequestError( f"When initializing mapper {self.prop.parent}, " f'expression "relationship({self.arg!r})" seems to be ' "using a generic class as the argument to relationship(); " "please state the generic argument " "using an annotation, e.g. " f'"{self.prop.key}: Mapped[{generic_match.group(1)}' f"['{clsarg}']] = relationship()\"" ) from err else: raise exc.InvalidRequestError( "When initializing mapper %s, expression %r failed to " "locate a name (%r). If this is a class name, consider " "adding this relationship() to the %r class after " "both dependent classes have been defined." % (self.prop.parent, self.arg, name, self.cls) ) from err def _resolve_name(self) -> Union[Table, Type[Any], _ModNS]: name = self.arg d = self._dict rval = None try: for token in name.split("."): if rval is None: rval = d[token] else: rval = getattr(rval, token) except KeyError as err: self._raise_for_name(name, err) except NameError as n: self._raise_for_name(n.args[0], n) else: if isinstance(rval, _GetColumns): return rval.cls else: if TYPE_CHECKING: assert isinstance(rval, (type, Table, _ModNS)) return rval def __call__(self) -> Any: try: x = eval(self.arg, globals(), self._dict) if isinstance(x, _GetColumns): return x.cls else: return x except NameError as n: self._raise_for_name(n.args[0], n) _fallback_dict: Mapping[str, Any] = None # type: ignore def _resolver(cls: Type[Any], prop: RelationshipProperty[Any]) -> Tuple[ Callable[[str], Callable[[], Union[Type[Any], Table, _ModNS]]], Callable[[str, bool], _class_resolver], ]: global _fallback_dict if _fallback_dict is None: import sqlalchemy from . import foreign from . import remote _fallback_dict = util.immutabledict(sqlalchemy.__dict__).union( {"foreign": foreign, "remote": remote} ) def resolve_arg(arg: str, favor_tables: bool = False) -> _class_resolver: return _class_resolver( cls, prop, _fallback_dict, arg, favor_tables=favor_tables ) def resolve_name( arg: str, ) -> Callable[[], Union[Type[Any], Table, _ModNS]]: return _class_resolver(cls, prop, _fallback_dict, arg)._resolve_name return resolve_name, resolve_arg sqlalchemy/orm/relationships.py 0000755 00000373470 15125143220 0012755 0 ustar 00 # orm/relationships.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """Heuristics related to join conditions as used in :func:`_orm.relationship`. Provides the :class:`.JoinCondition` object, which encapsulates SQL annotation and aliasing behavior focused on the `primaryjoin` and `secondaryjoin` aspects of :func:`_orm.relationship`. """ from __future__ import annotations import collections from collections import abc import dataclasses import inspect as _py_inspect import itertools import re import typing from typing import Any from typing import Callable from typing import cast from typing import Collection from typing import Dict from typing import FrozenSet from typing import Generic from typing import Iterable from typing import Iterator from typing import List from typing import NamedTuple from typing import NoReturn from typing import Optional from typing import Sequence from typing import Set from typing import Tuple from typing import Type from typing import TypeVar from typing import Union import weakref from . import attributes from . import strategy_options from ._typing import insp_is_aliased_class from ._typing import is_has_collection_adapter from .base import _DeclarativeMapped from .base import _is_mapped_class from .base import class_mapper from .base import DynamicMapped from .base import LoaderCallableStatus from .base import PassiveFlag from .base import state_str from .base import WriteOnlyMapped from .interfaces import _AttributeOptions from .interfaces import _IntrospectsAnnotations from .interfaces import MANYTOMANY from .interfaces import MANYTOONE from .interfaces import ONETOMANY from .interfaces import PropComparator from .interfaces import RelationshipDirection from .interfaces import StrategizedProperty from .util import _orm_annotate from .util import _orm_deannotate from .util import CascadeOptions from .. import exc as sa_exc from .. import Exists from .. import log from .. import schema from .. import sql from .. import util from ..inspection import inspect from ..sql import coercions from ..sql import expression from ..sql import operators from ..sql import roles from ..sql import visitors from ..sql._typing import _ColumnExpressionArgument from ..sql._typing import _HasClauseElement from ..sql.annotation import _safe_annotate from ..sql.elements import ColumnClause from ..sql.elements import ColumnElement from ..sql.util import _deep_annotate from ..sql.util import _deep_deannotate from ..sql.util import _shallow_annotate from ..sql.util import adapt_criterion_to_null from ..sql.util import ClauseAdapter from ..sql.util import join_condition from ..sql.util import selectables_overlap from ..sql.util import visit_binary_product from ..util.typing import de_optionalize_union_types from ..util.typing import Literal from ..util.typing import resolve_name_to_real_class_name if typing.TYPE_CHECKING: from ._typing import _EntityType from ._typing import _ExternalEntityType from ._typing import _IdentityKeyType from ._typing import _InstanceDict from ._typing import _InternalEntityType from ._typing import _O from ._typing import _RegistryType from .base import Mapped from .clsregistry import _class_resolver from .clsregistry import _ModNS from .decl_base import _ClassScanMapperConfig from .dependency import DependencyProcessor from .mapper import Mapper from .query import Query from .session import Session from .state import InstanceState from .strategies import LazyLoader from .util import AliasedClass from .util import AliasedInsp from ..sql._typing import _CoreAdapterProto from ..sql._typing import _EquivalentColumnMap from ..sql._typing import _InfoType from ..sql.annotation import _AnnotationDict from ..sql.annotation import SupportsAnnotations from ..sql.elements import BinaryExpression from ..sql.elements import BindParameter from ..sql.elements import ClauseElement from ..sql.schema import Table from ..sql.selectable import FromClause from ..util.typing import _AnnotationScanType from ..util.typing import RODescriptorReference _T = TypeVar("_T", bound=Any) _T1 = TypeVar("_T1", bound=Any) _T2 = TypeVar("_T2", bound=Any) _PT = TypeVar("_PT", bound=Any) _PT2 = TypeVar("_PT2", bound=Any) _RelationshipArgumentType = Union[ str, Type[_T], Callable[[], Type[_T]], "Mapper[_T]", "AliasedClass[_T]", Callable[[], "Mapper[_T]"], Callable[[], "AliasedClass[_T]"], ] _LazyLoadArgumentType = Literal[ "select", "joined", "selectin", "subquery", "raise", "raise_on_sql", "noload", "immediate", "write_only", "dynamic", True, False, None, ] _RelationshipJoinConditionArgument = Union[ str, _ColumnExpressionArgument[bool] ] _RelationshipSecondaryArgument = Union[ "FromClause", str, Callable[[], "FromClause"] ] _ORMOrderByArgument = Union[ Literal[False], str, _ColumnExpressionArgument[Any], Callable[[], _ColumnExpressionArgument[Any]], Callable[[], Iterable[_ColumnExpressionArgument[Any]]], Iterable[Union[str, _ColumnExpressionArgument[Any]]], ] ORMBackrefArgument = Union[str, Tuple[str, Dict[str, Any]]] _ORMColCollectionElement = Union[ ColumnClause[Any], _HasClauseElement[Any], roles.DMLColumnRole, "Mapped[Any]", ] _ORMColCollectionArgument = Union[ str, Sequence[_ORMColCollectionElement], Callable[[], Sequence[_ORMColCollectionElement]], Callable[[], _ORMColCollectionElement], _ORMColCollectionElement, ] _CEA = TypeVar("_CEA", bound=_ColumnExpressionArgument[Any]) _CE = TypeVar("_CE", bound="ColumnElement[Any]") _ColumnPairIterable = Iterable[Tuple[ColumnElement[Any], ColumnElement[Any]]] _ColumnPairs = Sequence[Tuple[ColumnElement[Any], ColumnElement[Any]]] _MutableColumnPairs = List[Tuple[ColumnElement[Any], ColumnElement[Any]]] def remote(expr: _CEA) -> _CEA: """Annotate a portion of a primaryjoin expression with a 'remote' annotation. See the section :ref:`relationship_custom_foreign` for a description of use. .. seealso:: :ref:`relationship_custom_foreign` :func:`.foreign` """ return _annotate_columns( # type: ignore coercions.expect(roles.ColumnArgumentRole, expr), {"remote": True} ) def foreign(expr: _CEA) -> _CEA: """Annotate a portion of a primaryjoin expression with a 'foreign' annotation. See the section :ref:`relationship_custom_foreign` for a description of use. .. seealso:: :ref:`relationship_custom_foreign` :func:`.remote` """ return _annotate_columns( # type: ignore coercions.expect(roles.ColumnArgumentRole, expr), {"foreign": True} ) @dataclasses.dataclass class _RelationshipArg(Generic[_T1, _T2]): """stores a user-defined parameter value that must be resolved and parsed later at mapper configuration time. """ __slots__ = "name", "argument", "resolved" name: str argument: _T1 resolved: Optional[_T2] def _is_populated(self) -> bool: return self.argument is not None def _resolve_against_registry( self, clsregistry_resolver: Callable[[str, bool], _class_resolver] ) -> None: attr_value = self.argument if isinstance(attr_value, str): self.resolved = clsregistry_resolver( attr_value, self.name == "secondary" )() elif callable(attr_value) and not _is_mapped_class(attr_value): self.resolved = attr_value() else: self.resolved = attr_value _RelationshipOrderByArg = Union[Literal[False], Tuple[ColumnElement[Any], ...]] class _RelationshipArgs(NamedTuple): """stores user-passed parameters that are resolved at mapper configuration time. """ secondary: _RelationshipArg[ Optional[_RelationshipSecondaryArgument], Optional[FromClause], ] primaryjoin: _RelationshipArg[ Optional[_RelationshipJoinConditionArgument], Optional[ColumnElement[Any]], ] secondaryjoin: _RelationshipArg[ Optional[_RelationshipJoinConditionArgument], Optional[ColumnElement[Any]], ] order_by: _RelationshipArg[_ORMOrderByArgument, _RelationshipOrderByArg] foreign_keys: _RelationshipArg[ Optional[_ORMColCollectionArgument], Set[ColumnElement[Any]] ] remote_side: _RelationshipArg[ Optional[_ORMColCollectionArgument], Set[ColumnElement[Any]] ] @log.class_logger class RelationshipProperty( _IntrospectsAnnotations, StrategizedProperty[_T], log.Identified ): """Describes an object property that holds a single item or list of items that correspond to a related database table. Public constructor is the :func:`_orm.relationship` function. .. seealso:: :ref:`relationship_config_toplevel` """ strategy_wildcard_key = strategy_options._RELATIONSHIP_TOKEN inherit_cache = True """:meta private:""" _links_to_entity = True _is_relationship = True _overlaps: Sequence[str] _lazy_strategy: LazyLoader _persistence_only = dict( passive_deletes=False, passive_updates=True, enable_typechecks=True, active_history=False, cascade_backrefs=False, ) _dependency_processor: Optional[DependencyProcessor] = None primaryjoin: ColumnElement[bool] secondaryjoin: Optional[ColumnElement[bool]] secondary: Optional[FromClause] _join_condition: JoinCondition order_by: _RelationshipOrderByArg _user_defined_foreign_keys: Set[ColumnElement[Any]] _calculated_foreign_keys: Set[ColumnElement[Any]] remote_side: Set[ColumnElement[Any]] local_columns: Set[ColumnElement[Any]] synchronize_pairs: _ColumnPairs secondary_synchronize_pairs: Optional[_ColumnPairs] local_remote_pairs: Optional[_ColumnPairs] direction: RelationshipDirection _init_args: _RelationshipArgs def __init__( self, argument: Optional[_RelationshipArgumentType[_T]] = None, secondary: Optional[_RelationshipSecondaryArgument] = None, *, uselist: Optional[bool] = None, collection_class: Optional[ Union[Type[Collection[Any]], Callable[[], Collection[Any]]] ] = None, primaryjoin: Optional[_RelationshipJoinConditionArgument] = None, secondaryjoin: Optional[_RelationshipJoinConditionArgument] = None, back_populates: Optional[str] = None, order_by: _ORMOrderByArgument = False, backref: Optional[ORMBackrefArgument] = None, overlaps: Optional[str] = None, post_update: bool = False, cascade: str = "save-update, merge", viewonly: bool = False, attribute_options: Optional[_AttributeOptions] = None, lazy: _LazyLoadArgumentType = "select", passive_deletes: Union[Literal["all"], bool] = False, passive_updates: bool = True, active_history: bool = False, enable_typechecks: bool = True, foreign_keys: Optional[_ORMColCollectionArgument] = None, remote_side: Optional[_ORMColCollectionArgument] = None, join_depth: Optional[int] = None, comparator_factory: Optional[ Type[RelationshipProperty.Comparator[Any]] ] = None, single_parent: bool = False, innerjoin: bool = False, distinct_target_key: Optional[bool] = None, load_on_pending: bool = False, query_class: Optional[Type[Query[Any]]] = None, info: Optional[_InfoType] = None, omit_join: Literal[None, False] = None, sync_backref: Optional[bool] = None, doc: Optional[str] = None, bake_queries: Literal[True] = True, cascade_backrefs: Literal[False] = False, _local_remote_pairs: Optional[_ColumnPairs] = None, _legacy_inactive_history_style: bool = False, ): super().__init__(attribute_options=attribute_options) self.uselist = uselist self.argument = argument self._init_args = _RelationshipArgs( _RelationshipArg("secondary", secondary, None), _RelationshipArg("primaryjoin", primaryjoin, None), _RelationshipArg("secondaryjoin", secondaryjoin, None), _RelationshipArg("order_by", order_by, None), _RelationshipArg("foreign_keys", foreign_keys, None), _RelationshipArg("remote_side", remote_side, None), ) self.post_update = post_update self.viewonly = viewonly if viewonly: self._warn_for_persistence_only_flags( passive_deletes=passive_deletes, passive_updates=passive_updates, enable_typechecks=enable_typechecks, active_history=active_history, cascade_backrefs=cascade_backrefs, ) if viewonly and sync_backref: raise sa_exc.ArgumentError( "sync_backref and viewonly cannot both be True" ) self.sync_backref = sync_backref self.lazy = lazy self.single_parent = single_parent self.collection_class = collection_class self.passive_deletes = passive_deletes if cascade_backrefs: raise sa_exc.ArgumentError( "The 'cascade_backrefs' parameter passed to " "relationship() may only be set to False." ) self.passive_updates = passive_updates self.enable_typechecks = enable_typechecks self.query_class = query_class self.innerjoin = innerjoin self.distinct_target_key = distinct_target_key self.doc = doc self.active_history = active_history self._legacy_inactive_history_style = _legacy_inactive_history_style self.join_depth = join_depth if omit_join: util.warn( "setting omit_join to True is not supported; selectin " "loading of this relationship may not work correctly if this " "flag is set explicitly. omit_join optimization is " "automatically detected for conditions under which it is " "supported." ) self.omit_join = omit_join self.local_remote_pairs = _local_remote_pairs self.load_on_pending = load_on_pending self.comparator_factory = ( comparator_factory or RelationshipProperty.Comparator ) util.set_creation_order(self) if info is not None: self.info.update(info) self.strategy_key = (("lazy", self.lazy),) self._reverse_property: Set[RelationshipProperty[Any]] = set() if overlaps: self._overlaps = set(re.split(r"\s*,\s*", overlaps)) # type: ignore # noqa: E501 else: self._overlaps = () # mypy ignoring the @property setter self.cascade = cascade # type: ignore self.back_populates = back_populates if self.back_populates: if backref: raise sa_exc.ArgumentError( "backref and back_populates keyword arguments " "are mutually exclusive" ) self.backref = None else: self.backref = backref def _warn_for_persistence_only_flags(self, **kw: Any) -> None: for k, v in kw.items(): if v != self._persistence_only[k]: # we are warning here rather than warn deprecated as this is a # configuration mistake, and Python shows regular warnings more # aggressively than deprecation warnings by default. Unlike the # case of setting viewonly with cascade, the settings being # warned about here are not actively doing the wrong thing # against viewonly=True, so it is not as urgent to have these # raise an error. util.warn( "Setting %s on relationship() while also " "setting viewonly=True does not make sense, as a " "viewonly=True relationship does not perform persistence " "operations. This configuration may raise an error " "in a future release." % (k,) ) def instrument_class(self, mapper: Mapper[Any]) -> None: attributes.register_descriptor( mapper.class_, self.key, comparator=self.comparator_factory(self, mapper), parententity=mapper, doc=self.doc, ) class Comparator(util.MemoizedSlots, PropComparator[_PT]): """Produce boolean, comparison, and other operators for :class:`.RelationshipProperty` attributes. See the documentation for :class:`.PropComparator` for a brief overview of ORM level operator definition. .. seealso:: :class:`.PropComparator` :class:`.ColumnProperty.Comparator` :class:`.ColumnOperators` :ref:`types_operators` :attr:`.TypeEngine.comparator_factory` """ __slots__ = ( "entity", "mapper", "property", "_of_type", "_extra_criteria", ) prop: RODescriptorReference[RelationshipProperty[_PT]] _of_type: Optional[_EntityType[_PT]] def __init__( self, prop: RelationshipProperty[_PT], parentmapper: _InternalEntityType[Any], adapt_to_entity: Optional[AliasedInsp[Any]] = None, of_type: Optional[_EntityType[_PT]] = None, extra_criteria: Tuple[ColumnElement[bool], ...] = (), ): """Construction of :class:`.RelationshipProperty.Comparator` is internal to the ORM's attribute mechanics. """ self.prop = prop self._parententity = parentmapper self._adapt_to_entity = adapt_to_entity if of_type: self._of_type = of_type else: self._of_type = None self._extra_criteria = extra_criteria def adapt_to_entity( self, adapt_to_entity: AliasedInsp[Any] ) -> RelationshipProperty.Comparator[Any]: return self.__class__( self.prop, self._parententity, adapt_to_entity=adapt_to_entity, of_type=self._of_type, ) entity: _InternalEntityType[_PT] """The target entity referred to by this :class:`.RelationshipProperty.Comparator`. This is either a :class:`_orm.Mapper` or :class:`.AliasedInsp` object. This is the "target" or "remote" side of the :func:`_orm.relationship`. """ mapper: Mapper[_PT] """The target :class:`_orm.Mapper` referred to by this :class:`.RelationshipProperty.Comparator`. This is the "target" or "remote" side of the :func:`_orm.relationship`. """ def _memoized_attr_entity(self) -> _InternalEntityType[_PT]: if self._of_type: return inspect(self._of_type) # type: ignore else: return self.prop.entity def _memoized_attr_mapper(self) -> Mapper[_PT]: return self.entity.mapper def _source_selectable(self) -> FromClause: if self._adapt_to_entity: return self._adapt_to_entity.selectable else: return self.property.parent._with_polymorphic_selectable def __clause_element__(self) -> ColumnElement[bool]: adapt_from = self._source_selectable() if self._of_type: of_type_entity = inspect(self._of_type) else: of_type_entity = None ( pj, sj, source, dest, secondary, target_adapter, ) = self.prop._create_joins( source_selectable=adapt_from, source_polymorphic=True, of_type_entity=of_type_entity, alias_secondary=True, extra_criteria=self._extra_criteria, ) if sj is not None: return pj & sj else: return pj def of_type(self, class_: _EntityType[Any]) -> PropComparator[_PT]: r"""Redefine this object in terms of a polymorphic subclass. See :meth:`.PropComparator.of_type` for an example. """ return RelationshipProperty.Comparator( self.prop, self._parententity, adapt_to_entity=self._adapt_to_entity, of_type=class_, extra_criteria=self._extra_criteria, ) def and_( self, *criteria: _ColumnExpressionArgument[bool] ) -> PropComparator[Any]: """Add AND criteria. See :meth:`.PropComparator.and_` for an example. .. versionadded:: 1.4 """ exprs = tuple( coercions.expect(roles.WhereHavingRole, clause) for clause in util.coerce_generator_arg(criteria) ) return RelationshipProperty.Comparator( self.prop, self._parententity, adapt_to_entity=self._adapt_to_entity, of_type=self._of_type, extra_criteria=self._extra_criteria + exprs, ) def in_(self, other: Any) -> NoReturn: """Produce an IN clause - this is not implemented for :func:`_orm.relationship`-based attributes at this time. """ raise NotImplementedError( "in_() not yet supported for " "relationships. For a simple " "many-to-one, use in_() against " "the set of foreign key values." ) # https://github.com/python/mypy/issues/4266 __hash__ = None # type: ignore def __eq__(self, other: Any) -> ColumnElement[bool]: # type: ignore[override] # noqa: E501 """Implement the ``==`` operator. In a many-to-one context, such as: .. sourcecode:: text MyClass.some_prop == <some object> this will typically produce a clause such as: .. sourcecode:: text mytable.related_id == <some id> Where ``<some id>`` is the primary key of the given object. The ``==`` operator provides partial functionality for non- many-to-one comparisons: * Comparisons against collections are not supported. Use :meth:`~.Relationship.Comparator.contains`. * Compared to a scalar one-to-many, will produce a clause that compares the target columns in the parent to the given target. * Compared to a scalar many-to-many, an alias of the association table will be rendered as well, forming a natural join that is part of the main body of the query. This will not work for queries that go beyond simple AND conjunctions of comparisons, such as those which use OR. Use explicit joins, outerjoins, or :meth:`~.Relationship.Comparator.has` for more comprehensive non-many-to-one scalar membership tests. * Comparisons against ``None`` given in a one-to-many or many-to-many context produce a NOT EXISTS clause. """ if other is None or isinstance(other, expression.Null): if self.property.direction in [ONETOMANY, MANYTOMANY]: return ~self._criterion_exists() else: return _orm_annotate( self.property._optimized_compare( None, adapt_source=self.adapter ) ) elif self.property.uselist: raise sa_exc.InvalidRequestError( "Can't compare a collection to an object or collection; " "use contains() to test for membership." ) else: return _orm_annotate( self.property._optimized_compare( other, adapt_source=self.adapter ) ) def _criterion_exists( self, criterion: Optional[_ColumnExpressionArgument[bool]] = None, **kwargs: Any, ) -> Exists: where_criteria = ( coercions.expect(roles.WhereHavingRole, criterion) if criterion is not None else None ) if getattr(self, "_of_type", None): info: Optional[_InternalEntityType[Any]] = inspect( self._of_type ) assert info is not None target_mapper, to_selectable, is_aliased_class = ( info.mapper, info.selectable, info.is_aliased_class, ) if self.property._is_self_referential and not is_aliased_class: to_selectable = to_selectable._anonymous_fromclause() single_crit = target_mapper._single_table_criterion if single_crit is not None: if where_criteria is not None: where_criteria = single_crit & where_criteria else: where_criteria = single_crit else: is_aliased_class = False to_selectable = None if self.adapter: source_selectable = self._source_selectable() else: source_selectable = None ( pj, sj, source, dest, secondary, target_adapter, ) = self.property._create_joins( dest_selectable=to_selectable, source_selectable=source_selectable, ) for k in kwargs: crit = getattr(self.property.mapper.class_, k) == kwargs[k] if where_criteria is None: where_criteria = crit else: where_criteria = where_criteria & crit # annotate the *local* side of the join condition, in the case # of pj + sj this is the full primaryjoin, in the case of just # pj its the local side of the primaryjoin. if sj is not None: j = _orm_annotate(pj) & sj else: j = _orm_annotate(pj, exclude=self.property.remote_side) if ( where_criteria is not None and target_adapter and not is_aliased_class ): # limit this adapter to annotated only? where_criteria = target_adapter.traverse(where_criteria) # only have the "joined left side" of what we # return be subject to Query adaption. The right # side of it is used for an exists() subquery and # should not correlate or otherwise reach out # to anything in the enclosing query. if where_criteria is not None: where_criteria = where_criteria._annotate( {"no_replacement_traverse": True} ) crit = j & sql.True_._ifnone(where_criteria) if secondary is not None: ex = ( sql.exists(1) .where(crit) .select_from(dest, secondary) .correlate_except(dest, secondary) ) else: ex = ( sql.exists(1) .where(crit) .select_from(dest) .correlate_except(dest) ) return ex def any( self, criterion: Optional[_ColumnExpressionArgument[bool]] = None, **kwargs: Any, ) -> ColumnElement[bool]: """Produce an expression that tests a collection against particular criterion, using EXISTS. An expression like:: session.query(MyClass).filter( MyClass.somereference.any(SomeRelated.x == 2) ) Will produce a query like: .. sourcecode:: sql SELECT * FROM my_table WHERE EXISTS (SELECT 1 FROM related WHERE related.my_id=my_table.id AND related.x=2) Because :meth:`~.Relationship.Comparator.any` uses a correlated subquery, its performance is not nearly as good when compared against large target tables as that of using a join. :meth:`~.Relationship.Comparator.any` is particularly useful for testing for empty collections:: session.query(MyClass).filter(~MyClass.somereference.any()) will produce: .. sourcecode:: sql SELECT * FROM my_table WHERE NOT (EXISTS (SELECT 1 FROM related WHERE related.my_id=my_table.id)) :meth:`~.Relationship.Comparator.any` is only valid for collections, i.e. a :func:`_orm.relationship` that has ``uselist=True``. For scalar references, use :meth:`~.Relationship.Comparator.has`. """ if not self.property.uselist: raise sa_exc.InvalidRequestError( "'any()' not implemented for scalar " "attributes. Use has()." ) return self._criterion_exists(criterion, **kwargs) def has( self, criterion: Optional[_ColumnExpressionArgument[bool]] = None, **kwargs: Any, ) -> ColumnElement[bool]: """Produce an expression that tests a scalar reference against particular criterion, using EXISTS. An expression like:: session.query(MyClass).filter( MyClass.somereference.has(SomeRelated.x == 2) ) Will produce a query like: .. sourcecode:: sql SELECT * FROM my_table WHERE EXISTS (SELECT 1 FROM related WHERE related.id==my_table.related_id AND related.x=2) Because :meth:`~.Relationship.Comparator.has` uses a correlated subquery, its performance is not nearly as good when compared against large target tables as that of using a join. :meth:`~.Relationship.Comparator.has` is only valid for scalar references, i.e. a :func:`_orm.relationship` that has ``uselist=False``. For collection references, use :meth:`~.Relationship.Comparator.any`. """ if self.property.uselist: raise sa_exc.InvalidRequestError( "'has()' not implemented for collections. Use any()." ) return self._criterion_exists(criterion, **kwargs) def contains( self, other: _ColumnExpressionArgument[Any], **kwargs: Any ) -> ColumnElement[bool]: """Return a simple expression that tests a collection for containment of a particular item. :meth:`~.Relationship.Comparator.contains` is only valid for a collection, i.e. a :func:`_orm.relationship` that implements one-to-many or many-to-many with ``uselist=True``. When used in a simple one-to-many context, an expression like:: MyClass.contains(other) Produces a clause like: .. sourcecode:: sql mytable.id == <some id> Where ``<some id>`` is the value of the foreign key attribute on ``other`` which refers to the primary key of its parent object. From this it follows that :meth:`~.Relationship.Comparator.contains` is very useful when used with simple one-to-many operations. For many-to-many operations, the behavior of :meth:`~.Relationship.Comparator.contains` has more caveats. The association table will be rendered in the statement, producing an "implicit" join, that is, includes multiple tables in the FROM clause which are equated in the WHERE clause:: query(MyClass).filter(MyClass.contains(other)) Produces a query like: .. sourcecode:: sql SELECT * FROM my_table, my_association_table AS my_association_table_1 WHERE my_table.id = my_association_table_1.parent_id AND my_association_table_1.child_id = <some id> Where ``<some id>`` would be the primary key of ``other``. From the above, it is clear that :meth:`~.Relationship.Comparator.contains` will **not** work with many-to-many collections when used in queries that move beyond simple AND conjunctions, such as multiple :meth:`~.Relationship.Comparator.contains` expressions joined by OR. In such cases subqueries or explicit "outer joins" will need to be used instead. See :meth:`~.Relationship.Comparator.any` for a less-performant alternative using EXISTS, or refer to :meth:`_query.Query.outerjoin` as well as :ref:`orm_queryguide_joins` for more details on constructing outer joins. kwargs may be ignored by this operator but are required for API conformance. """ if not self.prop.uselist: raise sa_exc.InvalidRequestError( "'contains' not implemented for scalar " "attributes. Use ==" ) clause = self.prop._optimized_compare( other, adapt_source=self.adapter ) if self.prop.secondaryjoin is not None: clause.negation_clause = self.__negated_contains_or_equals( other ) return clause def __negated_contains_or_equals( self, other: Any ) -> ColumnElement[bool]: if self.prop.direction == MANYTOONE: state = attributes.instance_state(other) def state_bindparam( local_col: ColumnElement[Any], state: InstanceState[Any], remote_col: ColumnElement[Any], ) -> BindParameter[Any]: dict_ = state.dict return sql.bindparam( local_col.key, type_=local_col.type, unique=True, callable_=self.prop._get_attr_w_warn_on_none( self.prop.mapper, state, dict_, remote_col ), ) def adapt(col: _CE) -> _CE: if self.adapter: return self.adapter(col) else: return col if self.property._use_get: return sql.and_( *[ sql.or_( adapt(x) != state_bindparam(adapt(x), state, y), adapt(x) == None, ) for (x, y) in self.property.local_remote_pairs ] ) criterion = sql.and_( *[ x == y for (x, y) in zip( self.property.mapper.primary_key, self.property.mapper.primary_key_from_instance(other), ) ] ) return ~self._criterion_exists(criterion) def __ne__(self, other: Any) -> ColumnElement[bool]: # type: ignore[override] # noqa: E501 """Implement the ``!=`` operator. In a many-to-one context, such as: .. sourcecode:: text MyClass.some_prop != <some object> This will typically produce a clause such as: .. sourcecode:: sql mytable.related_id != <some id> Where ``<some id>`` is the primary key of the given object. The ``!=`` operator provides partial functionality for non- many-to-one comparisons: * Comparisons against collections are not supported. Use :meth:`~.Relationship.Comparator.contains` in conjunction with :func:`_expression.not_`. * Compared to a scalar one-to-many, will produce a clause that compares the target columns in the parent to the given target. * Compared to a scalar many-to-many, an alias of the association table will be rendered as well, forming a natural join that is part of the main body of the query. This will not work for queries that go beyond simple AND conjunctions of comparisons, such as those which use OR. Use explicit joins, outerjoins, or :meth:`~.Relationship.Comparator.has` in conjunction with :func:`_expression.not_` for more comprehensive non-many-to-one scalar membership tests. * Comparisons against ``None`` given in a one-to-many or many-to-many context produce an EXISTS clause. """ if other is None or isinstance(other, expression.Null): if self.property.direction == MANYTOONE: return _orm_annotate( ~self.property._optimized_compare( None, adapt_source=self.adapter ) ) else: return self._criterion_exists() elif self.property.uselist: raise sa_exc.InvalidRequestError( "Can't compare a collection" " to an object or collection; use " "contains() to test for membership." ) else: return _orm_annotate(self.__negated_contains_or_equals(other)) def _memoized_attr_property(self) -> RelationshipProperty[_PT]: self.prop.parent._check_configure() return self.prop def _with_parent( self, instance: object, alias_secondary: bool = True, from_entity: Optional[_EntityType[Any]] = None, ) -> ColumnElement[bool]: assert instance is not None adapt_source: Optional[_CoreAdapterProto] = None if from_entity is not None: insp: Optional[_InternalEntityType[Any]] = inspect(from_entity) assert insp is not None if insp_is_aliased_class(insp): adapt_source = insp._adapter.adapt_clause return self._optimized_compare( instance, value_is_parent=True, adapt_source=adapt_source, alias_secondary=alias_secondary, ) def _optimized_compare( self, state: Any, value_is_parent: bool = False, adapt_source: Optional[_CoreAdapterProto] = None, alias_secondary: bool = True, ) -> ColumnElement[bool]: if state is not None: try: state = inspect(state) except sa_exc.NoInspectionAvailable: state = None if state is None or not getattr(state, "is_instance", False): raise sa_exc.ArgumentError( "Mapped instance expected for relationship " "comparison to object. Classes, queries and other " "SQL elements are not accepted in this context; for " "comparison with a subquery, " "use %s.has(**criteria)." % self ) reverse_direction = not value_is_parent if state is None: return self._lazy_none_clause( reverse_direction, adapt_source=adapt_source ) if not reverse_direction: criterion, bind_to_col = ( self._lazy_strategy._lazywhere, self._lazy_strategy._bind_to_col, ) else: criterion, bind_to_col = ( self._lazy_strategy._rev_lazywhere, self._lazy_strategy._rev_bind_to_col, ) if reverse_direction: mapper = self.mapper else: mapper = self.parent dict_ = attributes.instance_dict(state.obj()) def visit_bindparam(bindparam: BindParameter[Any]) -> None: if bindparam._identifying_key in bind_to_col: bindparam.callable = self._get_attr_w_warn_on_none( mapper, state, dict_, bind_to_col[bindparam._identifying_key], ) if self.secondary is not None and alias_secondary: criterion = ClauseAdapter( self.secondary._anonymous_fromclause() ).traverse(criterion) criterion = visitors.cloned_traverse( criterion, {}, {"bindparam": visit_bindparam} ) if adapt_source: criterion = adapt_source(criterion) return criterion def _get_attr_w_warn_on_none( self, mapper: Mapper[Any], state: InstanceState[Any], dict_: _InstanceDict, column: ColumnElement[Any], ) -> Callable[[], Any]: """Create the callable that is used in a many-to-one expression. E.g.:: u1 = s.query(User).get(5) expr = Address.user == u1 Above, the SQL should be "address.user_id = 5". The callable returned by this method produces the value "5" based on the identity of ``u1``. """ # in this callable, we're trying to thread the needle through # a wide variety of scenarios, including: # # * the object hasn't been flushed yet and there's no value for # the attribute as of yet # # * the object hasn't been flushed yet but it has a user-defined # value # # * the object has a value but it's expired and not locally present # # * the object has a value but it's expired and not locally present, # and the object is also detached # # * The object hadn't been flushed yet, there was no value, but # later, the object has been expired and detached, and *now* # they're trying to evaluate it # # * the object had a value, but it was changed to a new value, and # then expired # # * the object had a value, but it was changed to a new value, and # then expired, then the object was detached # # * the object has a user-set value, but it's None and we don't do # the comparison correctly for that so warn # prop = mapper.get_property_by_column(column) # by invoking this method, InstanceState will track the last known # value for this key each time the attribute is to be expired. # this feature was added explicitly for use in this method. state._track_last_known_value(prop.key) lkv_fixed = state._last_known_values def _go() -> Any: assert lkv_fixed is not None last_known = to_return = lkv_fixed[prop.key] existing_is_available = ( last_known is not LoaderCallableStatus.NO_VALUE ) # we support that the value may have changed. so here we # try to get the most recent value including re-fetching. # only if we can't get a value now due to detachment do we return # the last known value current_value = mapper._get_state_attr_by_column( state, dict_, column, passive=( PassiveFlag.PASSIVE_OFF if state.persistent else PassiveFlag.PASSIVE_NO_FETCH ^ PassiveFlag.INIT_OK ), ) if current_value is LoaderCallableStatus.NEVER_SET: if not existing_is_available: raise sa_exc.InvalidRequestError( "Can't resolve value for column %s on object " "%s; no value has been set for this column" % (column, state_str(state)) ) elif current_value is LoaderCallableStatus.PASSIVE_NO_RESULT: if not existing_is_available: raise sa_exc.InvalidRequestError( "Can't resolve value for column %s on object " "%s; the object is detached and the value was " "expired" % (column, state_str(state)) ) else: to_return = current_value if to_return is None: util.warn( "Got None for value of column %s; this is unsupported " "for a relationship comparison and will not " "currently produce an IS comparison " "(but may in a future release)" % column ) return to_return return _go def _lazy_none_clause( self, reverse_direction: bool = False, adapt_source: Optional[_CoreAdapterProto] = None, ) -> ColumnElement[bool]: if not reverse_direction: criterion, bind_to_col = ( self._lazy_strategy._lazywhere, self._lazy_strategy._bind_to_col, ) else: criterion, bind_to_col = ( self._lazy_strategy._rev_lazywhere, self._lazy_strategy._rev_bind_to_col, ) criterion = adapt_criterion_to_null(criterion, bind_to_col) if adapt_source: criterion = adapt_source(criterion) return criterion def __str__(self) -> str: return str(self.parent.class_.__name__) + "." + self.key def merge( self, session: Session, source_state: InstanceState[Any], source_dict: _InstanceDict, dest_state: InstanceState[Any], dest_dict: _InstanceDict, load: bool, _recursive: Dict[Any, object], _resolve_conflict_map: Dict[_IdentityKeyType[Any], object], ) -> None: if load: for r in self._reverse_property: if (source_state, r) in _recursive: return if "merge" not in self._cascade: return if self.key not in source_dict: return if self.uselist: impl = source_state.get_impl(self.key) assert is_has_collection_adapter(impl) instances_iterable = impl.get_collection(source_state, source_dict) # if this is a CollectionAttributeImpl, then empty should # be False, otherwise "self.key in source_dict" should not be # True assert not instances_iterable.empty if impl.collection else True if load: # for a full merge, pre-load the destination collection, # so that individual _merge of each item pulls from identity # map for those already present. # also assumes CollectionAttributeImpl behavior of loading # "old" list in any case dest_state.get_impl(self.key).get( dest_state, dest_dict, passive=PassiveFlag.PASSIVE_MERGE ) dest_list = [] for current in instances_iterable: current_state = attributes.instance_state(current) current_dict = attributes.instance_dict(current) _recursive[(current_state, self)] = True obj = session._merge( current_state, current_dict, load=load, _recursive=_recursive, _resolve_conflict_map=_resolve_conflict_map, ) if obj is not None: dest_list.append(obj) if not load: coll = attributes.init_state_collection( dest_state, dest_dict, self.key ) for c in dest_list: coll.append_without_event(c) else: dest_impl = dest_state.get_impl(self.key) assert is_has_collection_adapter(dest_impl) dest_impl.set( dest_state, dest_dict, dest_list, _adapt=False, passive=PassiveFlag.PASSIVE_MERGE, ) else: current = source_dict[self.key] if current is not None: current_state = attributes.instance_state(current) current_dict = attributes.instance_dict(current) _recursive[(current_state, self)] = True obj = session._merge( current_state, current_dict, load=load, _recursive=_recursive, _resolve_conflict_map=_resolve_conflict_map, ) else: obj = None if not load: dest_dict[self.key] = obj else: dest_state.get_impl(self.key).set( dest_state, dest_dict, obj, None ) def _value_as_iterable( self, state: InstanceState[_O], dict_: _InstanceDict, key: str, passive: PassiveFlag = PassiveFlag.PASSIVE_OFF, ) -> Sequence[Tuple[InstanceState[_O], _O]]: """Return a list of tuples (state, obj) for the given key. returns an empty list if the value is None/empty/PASSIVE_NO_RESULT """ impl = state.manager[key].impl x = impl.get(state, dict_, passive=passive) if x is LoaderCallableStatus.PASSIVE_NO_RESULT or x is None: return [] elif is_has_collection_adapter(impl): return [ (attributes.instance_state(o), o) for o in impl.get_collection(state, dict_, x, passive=passive) ] else: return [(attributes.instance_state(x), x)] def cascade_iterator( self, type_: str, state: InstanceState[Any], dict_: _InstanceDict, visited_states: Set[InstanceState[Any]], halt_on: Optional[Callable[[InstanceState[Any]], bool]] = None, ) -> Iterator[Tuple[Any, Mapper[Any], InstanceState[Any], _InstanceDict]]: # assert type_ in self._cascade # only actively lazy load on the 'delete' cascade if type_ != "delete" or self.passive_deletes: passive = PassiveFlag.PASSIVE_NO_INITIALIZE else: passive = PassiveFlag.PASSIVE_OFF | PassiveFlag.NO_RAISE if type_ == "save-update": tuples = state.manager[self.key].impl.get_all_pending(state, dict_) else: tuples = self._value_as_iterable( state, dict_, self.key, passive=passive ) skip_pending = ( type_ == "refresh-expire" and "delete-orphan" not in self._cascade ) for instance_state, c in tuples: if instance_state in visited_states: continue if c is None: # would like to emit a warning here, but # would not be consistent with collection.append(None) # current behavior of silently skipping. # see [ticket:2229] continue assert instance_state is not None instance_dict = attributes.instance_dict(c) if halt_on and halt_on(instance_state): continue if skip_pending and not instance_state.key: continue instance_mapper = instance_state.manager.mapper if not instance_mapper.isa(self.mapper.class_manager.mapper): raise AssertionError( "Attribute '%s' on class '%s' " "doesn't handle objects " "of type '%s'" % (self.key, self.parent.class_, c.__class__) ) visited_states.add(instance_state) yield c, instance_mapper, instance_state, instance_dict @property def _effective_sync_backref(self) -> bool: if self.viewonly: return False else: return self.sync_backref is not False @staticmethod def _check_sync_backref( rel_a: RelationshipProperty[Any], rel_b: RelationshipProperty[Any] ) -> None: if rel_a.viewonly and rel_b.sync_backref: raise sa_exc.InvalidRequestError( "Relationship %s cannot specify sync_backref=True since %s " "includes viewonly=True." % (rel_b, rel_a) ) if ( rel_a.viewonly and not rel_b.viewonly and rel_b.sync_backref is not False ): rel_b.sync_backref = False def _add_reverse_property(self, key: str) -> None: other = self.mapper.get_property(key, _configure_mappers=False) if not isinstance(other, RelationshipProperty): raise sa_exc.InvalidRequestError( "back_populates on relationship '%s' refers to attribute '%s' " "that is not a relationship. The back_populates parameter " "should refer to the name of a relationship on the target " "class." % (self, other) ) # viewonly and sync_backref cases # 1. self.viewonly==True and other.sync_backref==True -> error # 2. self.viewonly==True and other.viewonly==False and # other.sync_backref==None -> warn sync_backref=False, set to False self._check_sync_backref(self, other) # 3. other.viewonly==True and self.sync_backref==True -> error # 4. other.viewonly==True and self.viewonly==False and # self.sync_backref==None -> warn sync_backref=False, set to False self._check_sync_backref(other, self) self._reverse_property.add(other) other._reverse_property.add(self) other._setup_entity() if not other.mapper.common_parent(self.parent): raise sa_exc.ArgumentError( "reverse_property %r on " "relationship %s references relationship %s, which " "does not reference mapper %s" % (key, self, other, self.parent) ) if ( other._configure_started and self.direction in (ONETOMANY, MANYTOONE) and self.direction == other.direction ): raise sa_exc.ArgumentError( "%s and back-reference %s are " "both of the same direction %r. Did you mean to " "set remote_side on the many-to-one side ?" % (other, self, self.direction) ) @util.memoized_property def entity(self) -> _InternalEntityType[_T]: """Return the target mapped entity, which is an inspect() of the class or aliased class that is referenced by this :class:`.RelationshipProperty`. """ self.parent._check_configure() return self.entity @util.memoized_property def mapper(self) -> Mapper[_T]: """Return the targeted :class:`_orm.Mapper` for this :class:`.RelationshipProperty`. """ return self.entity.mapper def do_init(self) -> None: self._check_conflicts() self._process_dependent_arguments() self._setup_entity() self._setup_registry_dependencies() self._setup_join_conditions() self._check_cascade_settings(self._cascade) self._post_init() self._generate_backref() self._join_condition._warn_for_conflicting_sync_targets() super().do_init() self._lazy_strategy = cast( "LazyLoader", self._get_strategy((("lazy", "select"),)) ) def _setup_registry_dependencies(self) -> None: self.parent.mapper.registry._set_depends_on( self.entity.mapper.registry ) def _process_dependent_arguments(self) -> None: """Convert incoming configuration arguments to their proper form. Callables are resolved, ORM annotations removed. """ # accept callables for other attributes which may require # deferred initialization. This technique is used # by declarative "string configs" and some recipes. init_args = self._init_args for attr in ( "order_by", "primaryjoin", "secondaryjoin", "secondary", "foreign_keys", "remote_side", ): rel_arg = getattr(init_args, attr) rel_arg._resolve_against_registry(self._clsregistry_resolvers[1]) # remove "annotations" which are present if mapped class # descriptors are used to create the join expression. for attr in "primaryjoin", "secondaryjoin": rel_arg = getattr(init_args, attr) val = rel_arg.resolved if val is not None: rel_arg.resolved = _orm_deannotate( coercions.expect( roles.ColumnArgumentRole, val, argname=attr ) ) secondary = init_args.secondary.resolved if secondary is not None and _is_mapped_class(secondary): raise sa_exc.ArgumentError( "secondary argument %s passed to to relationship() %s must " "be a Table object or other FROM clause; can't send a mapped " "class directly as rows in 'secondary' are persisted " "independently of a class that is mapped " "to that same table." % (secondary, self) ) # ensure expressions in self.order_by, foreign_keys, # remote_side are all columns, not strings. if ( init_args.order_by.resolved is not False and init_args.order_by.resolved is not None ): self.order_by = tuple( coercions.expect( roles.ColumnArgumentRole, x, argname="order_by" ) for x in util.to_list(init_args.order_by.resolved) ) else: self.order_by = False self._user_defined_foreign_keys = util.column_set( coercions.expect( roles.ColumnArgumentRole, x, argname="foreign_keys" ) for x in util.to_column_set(init_args.foreign_keys.resolved) ) self.remote_side = util.column_set( coercions.expect( roles.ColumnArgumentRole, x, argname="remote_side" ) for x in util.to_column_set(init_args.remote_side.resolved) ) def declarative_scan( self, decl_scan: _ClassScanMapperConfig, registry: _RegistryType, cls: Type[Any], originating_module: Optional[str], key: str, mapped_container: Optional[Type[Mapped[Any]]], annotation: Optional[_AnnotationScanType], extracted_mapped_annotation: Optional[_AnnotationScanType], is_dataclass_field: bool, ) -> None: if extracted_mapped_annotation is None: if self.argument is None: self._raise_for_required(key, cls) else: return argument = extracted_mapped_annotation assert originating_module is not None if mapped_container is not None: is_write_only = issubclass(mapped_container, WriteOnlyMapped) is_dynamic = issubclass(mapped_container, DynamicMapped) if is_write_only: self.lazy = "write_only" self.strategy_key = (("lazy", self.lazy),) elif is_dynamic: self.lazy = "dynamic" self.strategy_key = (("lazy", self.lazy),) else: is_write_only = is_dynamic = False argument = de_optionalize_union_types(argument) if hasattr(argument, "__origin__"): arg_origin = argument.__origin__ if isinstance(arg_origin, type) and issubclass( arg_origin, abc.Collection ): if self.collection_class is None: if _py_inspect.isabstract(arg_origin): raise sa_exc.ArgumentError( f"Collection annotation type {arg_origin} cannot " "be instantiated; please provide an explicit " "'collection_class' parameter " "(e.g. list, set, etc.) to the " "relationship() function to accompany this " "annotation" ) self.collection_class = arg_origin elif not is_write_only and not is_dynamic: self.uselist = False if argument.__args__: # type: ignore if isinstance(arg_origin, type) and issubclass( arg_origin, typing.Mapping ): type_arg = argument.__args__[-1] # type: ignore else: type_arg = argument.__args__[0] # type: ignore if hasattr(type_arg, "__forward_arg__"): str_argument = type_arg.__forward_arg__ argument = resolve_name_to_real_class_name( str_argument, originating_module ) else: argument = type_arg else: raise sa_exc.ArgumentError( f"Generic alias {argument} requires an argument" ) elif hasattr(argument, "__forward_arg__"): argument = argument.__forward_arg__ argument = resolve_name_to_real_class_name( argument, originating_module ) if ( self.collection_class is None and not is_write_only and not is_dynamic ): self.uselist = False # ticket #8759 # if a lead argument was given to relationship(), like # `relationship("B")`, use that, don't replace it with class we # found in the annotation. The declarative_scan() method call here is # still useful, as we continue to derive collection type and do # checking of the annotation in any case. if self.argument is None: self.argument = cast("_RelationshipArgumentType[_T]", argument) @util.preload_module("sqlalchemy.orm.mapper") def _setup_entity(self, __argument: Any = None) -> None: if "entity" in self.__dict__: return mapperlib = util.preloaded.orm_mapper if __argument: argument = __argument else: argument = self.argument resolved_argument: _ExternalEntityType[Any] if isinstance(argument, str): # we might want to cleanup clsregistry API to make this # more straightforward resolved_argument = cast( "_ExternalEntityType[Any]", self._clsregistry_resolve_name(argument)(), ) elif callable(argument) and not isinstance( argument, (type, mapperlib.Mapper) ): resolved_argument = argument() else: resolved_argument = argument entity: _InternalEntityType[Any] if isinstance(resolved_argument, type): entity = class_mapper(resolved_argument, configure=False) else: try: entity = inspect(resolved_argument) except sa_exc.NoInspectionAvailable: entity = None # type: ignore if not hasattr(entity, "mapper"): raise sa_exc.ArgumentError( "relationship '%s' expects " "a class or a mapper argument (received: %s)" % (self.key, type(resolved_argument)) ) self.entity = entity self.target = self.entity.persist_selectable def _setup_join_conditions(self) -> None: self._join_condition = jc = JoinCondition( parent_persist_selectable=self.parent.persist_selectable, child_persist_selectable=self.entity.persist_selectable, parent_local_selectable=self.parent.local_table, child_local_selectable=self.entity.local_table, primaryjoin=self._init_args.primaryjoin.resolved, secondary=self._init_args.secondary.resolved, secondaryjoin=self._init_args.secondaryjoin.resolved, parent_equivalents=self.parent._equivalent_columns, child_equivalents=self.mapper._equivalent_columns, consider_as_foreign_keys=self._user_defined_foreign_keys, local_remote_pairs=self.local_remote_pairs, remote_side=self.remote_side, self_referential=self._is_self_referential, prop=self, support_sync=not self.viewonly, can_be_synced_fn=self._columns_are_mapped, ) self.primaryjoin = jc.primaryjoin self.secondaryjoin = jc.secondaryjoin self.secondary = jc.secondary self.direction = jc.direction self.local_remote_pairs = jc.local_remote_pairs self.remote_side = jc.remote_columns self.local_columns = jc.local_columns self.synchronize_pairs = jc.synchronize_pairs self._calculated_foreign_keys = jc.foreign_key_columns self.secondary_synchronize_pairs = jc.secondary_synchronize_pairs @property def _clsregistry_resolve_arg( self, ) -> Callable[[str, bool], _class_resolver]: return self._clsregistry_resolvers[1] @property def _clsregistry_resolve_name( self, ) -> Callable[[str], Callable[[], Union[Type[Any], Table, _ModNS]]]: return self._clsregistry_resolvers[0] @util.memoized_property @util.preload_module("sqlalchemy.orm.clsregistry") def _clsregistry_resolvers( self, ) -> Tuple[ Callable[[str], Callable[[], Union[Type[Any], Table, _ModNS]]], Callable[[str, bool], _class_resolver], ]: _resolver = util.preloaded.orm_clsregistry._resolver return _resolver(self.parent.class_, self) def _check_conflicts(self) -> None: """Test that this relationship is legal, warn about inheritance conflicts.""" if self.parent.non_primary and not class_mapper( self.parent.class_, configure=False ).has_property(self.key): raise sa_exc.ArgumentError( "Attempting to assign a new " "relationship '%s' to a non-primary mapper on " "class '%s'. New relationships can only be added " "to the primary mapper, i.e. the very first mapper " "created for class '%s' " % ( self.key, self.parent.class_.__name__, self.parent.class_.__name__, ) ) @property def cascade(self) -> CascadeOptions: """Return the current cascade setting for this :class:`.RelationshipProperty`. """ return self._cascade @cascade.setter def cascade(self, cascade: Union[str, CascadeOptions]) -> None: self._set_cascade(cascade) def _set_cascade(self, cascade_arg: Union[str, CascadeOptions]) -> None: cascade = CascadeOptions(cascade_arg) if self.viewonly: cascade = CascadeOptions( cascade.intersection(CascadeOptions._viewonly_cascades) ) if "mapper" in self.__dict__: self._check_cascade_settings(cascade) self._cascade = cascade if self._dependency_processor: self._dependency_processor.cascade = cascade def _check_cascade_settings(self, cascade: CascadeOptions) -> None: if ( cascade.delete_orphan and not self.single_parent and (self.direction is MANYTOMANY or self.direction is MANYTOONE) ): raise sa_exc.ArgumentError( "For %(direction)s relationship %(rel)s, delete-orphan " "cascade is normally " 'configured only on the "one" side of a one-to-many ' "relationship, " 'and not on the "many" side of a many-to-one or many-to-many ' "relationship. " "To force this relationship to allow a particular " '"%(relatedcls)s" object to be referenced by only ' 'a single "%(clsname)s" object at a time via the ' "%(rel)s relationship, which " "would allow " "delete-orphan cascade to take place in this direction, set " "the single_parent=True flag." % { "rel": self, "direction": ( "many-to-one" if self.direction is MANYTOONE else "many-to-many" ), "clsname": self.parent.class_.__name__, "relatedcls": self.mapper.class_.__name__, }, code="bbf0", ) if self.passive_deletes == "all" and ( "delete" in cascade or "delete-orphan" in cascade ): raise sa_exc.ArgumentError( "On %s, can't set passive_deletes='all' in conjunction " "with 'delete' or 'delete-orphan' cascade" % self ) if cascade.delete_orphan: self.mapper.primary_mapper()._delete_orphans.append( (self.key, self.parent.class_) ) def _persists_for(self, mapper: Mapper[Any]) -> bool: """Return True if this property will persist values on behalf of the given mapper. """ return ( self.key in mapper.relationships and mapper.relationships[self.key] is self ) def _columns_are_mapped(self, *cols: ColumnElement[Any]) -> bool: """Return True if all columns in the given collection are mapped by the tables referenced by this :class:`.RelationshipProperty`. """ secondary = self._init_args.secondary.resolved for c in cols: if secondary is not None and secondary.c.contains_column(c): continue if not self.parent.persist_selectable.c.contains_column( c ) and not self.target.c.contains_column(c): return False return True def _generate_backref(self) -> None: """Interpret the 'backref' instruction to create a :func:`_orm.relationship` complementary to this one.""" if self.parent.non_primary: return if self.backref is not None and not self.back_populates: kwargs: Dict[str, Any] if isinstance(self.backref, str): backref_key, kwargs = self.backref, {} else: backref_key, kwargs = self.backref mapper = self.mapper.primary_mapper() if not mapper.concrete: check = set(mapper.iterate_to_root()).union( mapper.self_and_descendants ) for m in check: if m.has_property(backref_key) and not m.concrete: raise sa_exc.ArgumentError( "Error creating backref " "'%s' on relationship '%s': property of that " "name exists on mapper '%s'" % (backref_key, self, m) ) # determine primaryjoin/secondaryjoin for the # backref. Use the one we had, so that # a custom join doesn't have to be specified in # both directions. if self.secondary is not None: # for many to many, just switch primaryjoin/ # secondaryjoin. use the annotated # pj/sj on the _join_condition. pj = kwargs.pop( "primaryjoin", self._join_condition.secondaryjoin_minus_local, ) sj = kwargs.pop( "secondaryjoin", self._join_condition.primaryjoin_minus_local, ) else: pj = kwargs.pop( "primaryjoin", self._join_condition.primaryjoin_reverse_remote, ) sj = kwargs.pop("secondaryjoin", None) if sj: raise sa_exc.InvalidRequestError( "Can't assign 'secondaryjoin' on a backref " "against a non-secondary relationship." ) foreign_keys = kwargs.pop( "foreign_keys", self._user_defined_foreign_keys ) parent = self.parent.primary_mapper() kwargs.setdefault("viewonly", self.viewonly) kwargs.setdefault("post_update", self.post_update) kwargs.setdefault("passive_updates", self.passive_updates) kwargs.setdefault("sync_backref", self.sync_backref) self.back_populates = backref_key relationship = RelationshipProperty( parent, self.secondary, primaryjoin=pj, secondaryjoin=sj, foreign_keys=foreign_keys, back_populates=self.key, **kwargs, ) mapper._configure_property( backref_key, relationship, warn_for_existing=True ) if self.back_populates: self._add_reverse_property(self.back_populates) @util.preload_module("sqlalchemy.orm.dependency") def _post_init(self) -> None: dependency = util.preloaded.orm_dependency if self.uselist is None: self.uselist = self.direction is not MANYTOONE if not self.viewonly: self._dependency_processor = ( # type: ignore dependency.DependencyProcessor.from_relationship )(self) @util.memoized_property def _use_get(self) -> bool: """memoize the 'use_get' attribute of this RelationshipLoader's lazyloader.""" strategy = self._lazy_strategy return strategy.use_get @util.memoized_property def _is_self_referential(self) -> bool: return self.mapper.common_parent(self.parent) def _create_joins( self, source_polymorphic: bool = False, source_selectable: Optional[FromClause] = None, dest_selectable: Optional[FromClause] = None, of_type_entity: Optional[_InternalEntityType[Any]] = None, alias_secondary: bool = False, extra_criteria: Tuple[ColumnElement[bool], ...] = (), ) -> Tuple[ ColumnElement[bool], Optional[ColumnElement[bool]], FromClause, FromClause, Optional[FromClause], Optional[ClauseAdapter], ]: aliased = False if alias_secondary and self.secondary is not None: aliased = True if source_selectable is None: if source_polymorphic and self.parent.with_polymorphic: source_selectable = self.parent._with_polymorphic_selectable if of_type_entity: dest_mapper = of_type_entity.mapper if dest_selectable is None: dest_selectable = of_type_entity.selectable aliased = True else: dest_mapper = self.mapper if dest_selectable is None: dest_selectable = self.entity.selectable if self.mapper.with_polymorphic: aliased = True if self._is_self_referential and source_selectable is None: dest_selectable = dest_selectable._anonymous_fromclause() aliased = True elif ( dest_selectable is not self.mapper._with_polymorphic_selectable or self.mapper.with_polymorphic ): aliased = True single_crit = dest_mapper._single_table_criterion aliased = aliased or ( source_selectable is not None and ( source_selectable is not self.parent._with_polymorphic_selectable or source_selectable._is_subquery ) ) ( primaryjoin, secondaryjoin, secondary, target_adapter, dest_selectable, ) = self._join_condition.join_targets( source_selectable, dest_selectable, aliased, single_crit, extra_criteria, ) if source_selectable is None: source_selectable = self.parent.local_table if dest_selectable is None: dest_selectable = self.entity.local_table return ( primaryjoin, secondaryjoin, source_selectable, dest_selectable, secondary, target_adapter, ) def _annotate_columns(element: _CE, annotations: _AnnotationDict) -> _CE: def clone(elem: _CE) -> _CE: if isinstance(elem, expression.ColumnClause): elem = elem._annotate(annotations.copy()) # type: ignore elem._copy_internals(clone=clone) return elem if element is not None: element = clone(element) clone = None # type: ignore # remove gc cycles return element class JoinCondition: primaryjoin_initial: Optional[ColumnElement[bool]] primaryjoin: ColumnElement[bool] secondaryjoin: Optional[ColumnElement[bool]] secondary: Optional[FromClause] prop: RelationshipProperty[Any] synchronize_pairs: _ColumnPairs secondary_synchronize_pairs: _ColumnPairs direction: RelationshipDirection parent_persist_selectable: FromClause child_persist_selectable: FromClause parent_local_selectable: FromClause child_local_selectable: FromClause _local_remote_pairs: Optional[_ColumnPairs] def __init__( self, parent_persist_selectable: FromClause, child_persist_selectable: FromClause, parent_local_selectable: FromClause, child_local_selectable: FromClause, *, primaryjoin: Optional[ColumnElement[bool]] = None, secondary: Optional[FromClause] = None, secondaryjoin: Optional[ColumnElement[bool]] = None, parent_equivalents: Optional[_EquivalentColumnMap] = None, child_equivalents: Optional[_EquivalentColumnMap] = None, consider_as_foreign_keys: Any = None, local_remote_pairs: Optional[_ColumnPairs] = None, remote_side: Any = None, self_referential: Any = False, prop: RelationshipProperty[Any], support_sync: bool = True, can_be_synced_fn: Callable[..., bool] = lambda *c: True, ): self.parent_persist_selectable = parent_persist_selectable self.parent_local_selectable = parent_local_selectable self.child_persist_selectable = child_persist_selectable self.child_local_selectable = child_local_selectable self.parent_equivalents = parent_equivalents self.child_equivalents = child_equivalents self.primaryjoin_initial = primaryjoin self.secondaryjoin = secondaryjoin self.secondary = secondary self.consider_as_foreign_keys = consider_as_foreign_keys self._local_remote_pairs = local_remote_pairs self._remote_side = remote_side self.prop = prop self.self_referential = self_referential self.support_sync = support_sync self.can_be_synced_fn = can_be_synced_fn self._determine_joins() assert self.primaryjoin is not None self._sanitize_joins() self._annotate_fks() self._annotate_remote() self._annotate_local() self._annotate_parentmapper() self._setup_pairs() self._check_foreign_cols(self.primaryjoin, True) if self.secondaryjoin is not None: self._check_foreign_cols(self.secondaryjoin, False) self._determine_direction() self._check_remote_side() self._log_joins() def _log_joins(self) -> None: log = self.prop.logger log.info("%s setup primary join %s", self.prop, self.primaryjoin) log.info("%s setup secondary join %s", self.prop, self.secondaryjoin) log.info( "%s synchronize pairs [%s]", self.prop, ",".join( "(%s => %s)" % (l, r) for (l, r) in self.synchronize_pairs ), ) log.info( "%s secondary synchronize pairs [%s]", self.prop, ",".join( "(%s => %s)" % (l, r) for (l, r) in self.secondary_synchronize_pairs or [] ), ) log.info( "%s local/remote pairs [%s]", self.prop, ",".join( "(%s / %s)" % (l, r) for (l, r) in self.local_remote_pairs ), ) log.info( "%s remote columns [%s]", self.prop, ",".join("%s" % col for col in self.remote_columns), ) log.info( "%s local columns [%s]", self.prop, ",".join("%s" % col for col in self.local_columns), ) log.info("%s relationship direction %s", self.prop, self.direction) def _sanitize_joins(self) -> None: """remove the parententity annotation from our join conditions which can leak in here based on some declarative patterns and maybe others. "parentmapper" is relied upon both by the ORM evaluator as well as the use case in _join_fixture_inh_selfref_w_entity that relies upon it being present, see :ticket:`3364`. """ self.primaryjoin = _deep_deannotate( self.primaryjoin, values=("parententity", "proxy_key") ) if self.secondaryjoin is not None: self.secondaryjoin = _deep_deannotate( self.secondaryjoin, values=("parententity", "proxy_key") ) def _determine_joins(self) -> None: """Determine the 'primaryjoin' and 'secondaryjoin' attributes, if not passed to the constructor already. This is based on analysis of the foreign key relationships between the parent and target mapped selectables. """ if self.secondaryjoin is not None and self.secondary is None: raise sa_exc.ArgumentError( "Property %s specified with secondary " "join condition but " "no secondary argument" % self.prop ) # find a join between the given mapper's mapped table and # the given table. will try the mapper's local table first # for more specificity, then if not found will try the more # general mapped table, which in the case of inheritance is # a join. try: consider_as_foreign_keys = self.consider_as_foreign_keys or None if self.secondary is not None: if self.secondaryjoin is None: self.secondaryjoin = join_condition( self.child_persist_selectable, self.secondary, a_subset=self.child_local_selectable, consider_as_foreign_keys=consider_as_foreign_keys, ) if self.primaryjoin_initial is None: self.primaryjoin = join_condition( self.parent_persist_selectable, self.secondary, a_subset=self.parent_local_selectable, consider_as_foreign_keys=consider_as_foreign_keys, ) else: self.primaryjoin = self.primaryjoin_initial else: if self.primaryjoin_initial is None: self.primaryjoin = join_condition( self.parent_persist_selectable, self.child_persist_selectable, a_subset=self.parent_local_selectable, consider_as_foreign_keys=consider_as_foreign_keys, ) else: self.primaryjoin = self.primaryjoin_initial except sa_exc.NoForeignKeysError as nfe: if self.secondary is not None: raise sa_exc.NoForeignKeysError( "Could not determine join " "condition between parent/child tables on " "relationship %s - there are no foreign keys " "linking these tables via secondary table '%s'. " "Ensure that referencing columns are associated " "with a ForeignKey or ForeignKeyConstraint, or " "specify 'primaryjoin' and 'secondaryjoin' " "expressions." % (self.prop, self.secondary) ) from nfe else: raise sa_exc.NoForeignKeysError( "Could not determine join " "condition between parent/child tables on " "relationship %s - there are no foreign keys " "linking these tables. " "Ensure that referencing columns are associated " "with a ForeignKey or ForeignKeyConstraint, or " "specify a 'primaryjoin' expression." % self.prop ) from nfe except sa_exc.AmbiguousForeignKeysError as afe: if self.secondary is not None: raise sa_exc.AmbiguousForeignKeysError( "Could not determine join " "condition between parent/child tables on " "relationship %s - there are multiple foreign key " "paths linking the tables via secondary table '%s'. " "Specify the 'foreign_keys' " "argument, providing a list of those columns which " "should be counted as containing a foreign key " "reference from the secondary table to each of the " "parent and child tables." % (self.prop, self.secondary) ) from afe else: raise sa_exc.AmbiguousForeignKeysError( "Could not determine join " "condition between parent/child tables on " "relationship %s - there are multiple foreign key " "paths linking the tables. Specify the " "'foreign_keys' argument, providing a list of those " "columns which should be counted as containing a " "foreign key reference to the parent table." % self.prop ) from afe @property def primaryjoin_minus_local(self) -> ColumnElement[bool]: return _deep_deannotate(self.primaryjoin, values=("local", "remote")) @property def secondaryjoin_minus_local(self) -> ColumnElement[bool]: assert self.secondaryjoin is not None return _deep_deannotate(self.secondaryjoin, values=("local", "remote")) @util.memoized_property def primaryjoin_reverse_remote(self) -> ColumnElement[bool]: """Return the primaryjoin condition suitable for the "reverse" direction. If the primaryjoin was delivered here with pre-existing "remote" annotations, the local/remote annotations are reversed. Otherwise, the local/remote annotations are removed. """ if self._has_remote_annotations: def replace(element: _CE, **kw: Any) -> Optional[_CE]: if "remote" in element._annotations: v = dict(element._annotations) del v["remote"] v["local"] = True return element._with_annotations(v) elif "local" in element._annotations: v = dict(element._annotations) del v["local"] v["remote"] = True return element._with_annotations(v) return None return visitors.replacement_traverse(self.primaryjoin, {}, replace) else: if self._has_foreign_annotations: # TODO: coverage return _deep_deannotate( self.primaryjoin, values=("local", "remote") ) else: return _deep_deannotate(self.primaryjoin) def _has_annotation(self, clause: ClauseElement, annotation: str) -> bool: for col in visitors.iterate(clause, {}): if annotation in col._annotations: return True else: return False @util.memoized_property def _has_foreign_annotations(self) -> bool: return self._has_annotation(self.primaryjoin, "foreign") @util.memoized_property def _has_remote_annotations(self) -> bool: return self._has_annotation(self.primaryjoin, "remote") def _annotate_fks(self) -> None: """Annotate the primaryjoin and secondaryjoin structures with 'foreign' annotations marking columns considered as foreign. """ if self._has_foreign_annotations: return if self.consider_as_foreign_keys: self._annotate_from_fk_list() else: self._annotate_present_fks() def _annotate_from_fk_list(self) -> None: def check_fk(element: _CE, **kw: Any) -> Optional[_CE]: if element in self.consider_as_foreign_keys: return element._annotate({"foreign": True}) return None self.primaryjoin = visitors.replacement_traverse( self.primaryjoin, {}, check_fk ) if self.secondaryjoin is not None: self.secondaryjoin = visitors.replacement_traverse( self.secondaryjoin, {}, check_fk ) def _annotate_present_fks(self) -> None: if self.secondary is not None: secondarycols = util.column_set(self.secondary.c) else: secondarycols = set() def is_foreign( a: ColumnElement[Any], b: ColumnElement[Any] ) -> Optional[ColumnElement[Any]]: if isinstance(a, schema.Column) and isinstance(b, schema.Column): if a.references(b): return a elif b.references(a): return b if secondarycols: if a in secondarycols and b not in secondarycols: return a elif b in secondarycols and a not in secondarycols: return b return None def visit_binary(binary: BinaryExpression[Any]) -> None: if not isinstance( binary.left, sql.ColumnElement ) or not isinstance(binary.right, sql.ColumnElement): return if ( "foreign" not in binary.left._annotations and "foreign" not in binary.right._annotations ): col = is_foreign(binary.left, binary.right) if col is not None: if col.compare(binary.left): binary.left = binary.left._annotate({"foreign": True}) elif col.compare(binary.right): binary.right = binary.right._annotate( {"foreign": True} ) self.primaryjoin = visitors.cloned_traverse( self.primaryjoin, {}, {"binary": visit_binary} ) if self.secondaryjoin is not None: self.secondaryjoin = visitors.cloned_traverse( self.secondaryjoin, {}, {"binary": visit_binary} ) def _refers_to_parent_table(self) -> bool: """Return True if the join condition contains column comparisons where both columns are in both tables. """ pt = self.parent_persist_selectable mt = self.child_persist_selectable result = False def visit_binary(binary: BinaryExpression[Any]) -> None: nonlocal result c, f = binary.left, binary.right if ( isinstance(c, expression.ColumnClause) and isinstance(f, expression.ColumnClause) and pt.is_derived_from(c.table) and pt.is_derived_from(f.table) and mt.is_derived_from(c.table) and mt.is_derived_from(f.table) ): result = True visitors.traverse(self.primaryjoin, {}, {"binary": visit_binary}) return result def _tables_overlap(self) -> bool: """Return True if parent/child tables have some overlap.""" return selectables_overlap( self.parent_persist_selectable, self.child_persist_selectable ) def _annotate_remote(self) -> None: """Annotate the primaryjoin and secondaryjoin structures with 'remote' annotations marking columns considered as part of the 'remote' side. """ if self._has_remote_annotations: return if self.secondary is not None: self._annotate_remote_secondary() elif self._local_remote_pairs or self._remote_side: self._annotate_remote_from_args() elif self._refers_to_parent_table(): self._annotate_selfref( lambda col: "foreign" in col._annotations, False ) elif self._tables_overlap(): self._annotate_remote_with_overlap() else: self._annotate_remote_distinct_selectables() def _annotate_remote_secondary(self) -> None: """annotate 'remote' in primaryjoin, secondaryjoin when 'secondary' is present. """ assert self.secondary is not None fixed_secondary = self.secondary def repl(element: _CE, **kw: Any) -> Optional[_CE]: if fixed_secondary.c.contains_column(element): return element._annotate({"remote": True}) return None self.primaryjoin = visitors.replacement_traverse( self.primaryjoin, {}, repl ) assert self.secondaryjoin is not None self.secondaryjoin = visitors.replacement_traverse( self.secondaryjoin, {}, repl ) def _annotate_selfref( self, fn: Callable[[ColumnElement[Any]], bool], remote_side_given: bool ) -> None: """annotate 'remote' in primaryjoin, secondaryjoin when the relationship is detected as self-referential. """ def visit_binary(binary: BinaryExpression[Any]) -> None: equated = binary.left.compare(binary.right) if isinstance(binary.left, expression.ColumnClause) and isinstance( binary.right, expression.ColumnClause ): # assume one to many - FKs are "remote" if fn(binary.left): binary.left = binary.left._annotate({"remote": True}) if fn(binary.right) and not equated: binary.right = binary.right._annotate({"remote": True}) elif not remote_side_given: self._warn_non_column_elements() self.primaryjoin = visitors.cloned_traverse( self.primaryjoin, {}, {"binary": visit_binary} ) def _annotate_remote_from_args(self) -> None: """annotate 'remote' in primaryjoin, secondaryjoin when the 'remote_side' or '_local_remote_pairs' arguments are used. """ if self._local_remote_pairs: if self._remote_side: raise sa_exc.ArgumentError( "remote_side argument is redundant " "against more detailed _local_remote_side " "argument." ) remote_side = [r for (l, r) in self._local_remote_pairs] else: remote_side = self._remote_side if self._refers_to_parent_table(): self._annotate_selfref(lambda col: col in remote_side, True) else: def repl(element: _CE, **kw: Any) -> Optional[_CE]: # use set() to avoid generating ``__eq__()`` expressions # against each element if element in set(remote_side): return element._annotate({"remote": True}) return None self.primaryjoin = visitors.replacement_traverse( self.primaryjoin, {}, repl ) def _annotate_remote_with_overlap(self) -> None: """annotate 'remote' in primaryjoin, secondaryjoin when the parent/child tables have some set of tables in common, though is not a fully self-referential relationship. """ def visit_binary(binary: BinaryExpression[Any]) -> None: binary.left, binary.right = proc_left_right( binary.left, binary.right ) binary.right, binary.left = proc_left_right( binary.right, binary.left ) check_entities = ( self.prop is not None and self.prop.mapper is not self.prop.parent ) def proc_left_right( left: ColumnElement[Any], right: ColumnElement[Any] ) -> Tuple[ColumnElement[Any], ColumnElement[Any]]: if isinstance(left, expression.ColumnClause) and isinstance( right, expression.ColumnClause ): if self.child_persist_selectable.c.contains_column( right ) and self.parent_persist_selectable.c.contains_column(left): right = right._annotate({"remote": True}) elif ( check_entities and right._annotations.get("parentmapper") is self.prop.mapper ): right = right._annotate({"remote": True}) elif ( check_entities and left._annotations.get("parentmapper") is self.prop.mapper ): left = left._annotate({"remote": True}) else: self._warn_non_column_elements() return left, right self.primaryjoin = visitors.cloned_traverse( self.primaryjoin, {}, {"binary": visit_binary} ) def _annotate_remote_distinct_selectables(self) -> None: """annotate 'remote' in primaryjoin, secondaryjoin when the parent/child tables are entirely separate. """ def repl(element: _CE, **kw: Any) -> Optional[_CE]: if self.child_persist_selectable.c.contains_column(element) and ( not self.parent_local_selectable.c.contains_column(element) or self.child_local_selectable.c.contains_column(element) ): return element._annotate({"remote": True}) return None self.primaryjoin = visitors.replacement_traverse( self.primaryjoin, {}, repl ) def _warn_non_column_elements(self) -> None: util.warn( "Non-simple column elements in primary " "join condition for property %s - consider using " "remote() annotations to mark the remote side." % self.prop ) def _annotate_local(self) -> None: """Annotate the primaryjoin and secondaryjoin structures with 'local' annotations. This annotates all column elements found simultaneously in the parent table and the join condition that don't have a 'remote' annotation set up from _annotate_remote() or user-defined. """ if self._has_annotation(self.primaryjoin, "local"): return if self._local_remote_pairs: local_side = util.column_set( [l for (l, r) in self._local_remote_pairs] ) else: local_side = util.column_set(self.parent_persist_selectable.c) def locals_(element: _CE, **kw: Any) -> Optional[_CE]: if "remote" not in element._annotations and element in local_side: return element._annotate({"local": True}) return None self.primaryjoin = visitors.replacement_traverse( self.primaryjoin, {}, locals_ ) def _annotate_parentmapper(self) -> None: def parentmappers_(element: _CE, **kw: Any) -> Optional[_CE]: if "remote" in element._annotations: return element._annotate({"parentmapper": self.prop.mapper}) elif "local" in element._annotations: return element._annotate({"parentmapper": self.prop.parent}) return None self.primaryjoin = visitors.replacement_traverse( self.primaryjoin, {}, parentmappers_ ) def _check_remote_side(self) -> None: if not self.local_remote_pairs: raise sa_exc.ArgumentError( "Relationship %s could " "not determine any unambiguous local/remote column " "pairs based on join condition and remote_side " "arguments. " "Consider using the remote() annotation to " "accurately mark those elements of the join " "condition that are on the remote side of " "the relationship." % (self.prop,) ) else: not_target = util.column_set( self.parent_persist_selectable.c ).difference(self.child_persist_selectable.c) for _, rmt in self.local_remote_pairs: if rmt in not_target: util.warn( "Expression %s is marked as 'remote', but these " "column(s) are local to the local side. The " "remote() annotation is needed only for a " "self-referential relationship where both sides " "of the relationship refer to the same tables." % (rmt,) ) def _check_foreign_cols( self, join_condition: ColumnElement[bool], primary: bool ) -> None: """Check the foreign key columns collected and emit error messages.""" foreign_cols = self._gather_columns_with_annotation( join_condition, "foreign" ) has_foreign = bool(foreign_cols) if primary: can_sync = bool(self.synchronize_pairs) else: can_sync = bool(self.secondary_synchronize_pairs) if ( self.support_sync and can_sync or (not self.support_sync and has_foreign) ): return # from here below is just determining the best error message # to report. Check for a join condition using any operator # (not just ==), perhaps they need to turn on "viewonly=True". if self.support_sync and has_foreign and not can_sync: err = ( "Could not locate any simple equality expressions " "involving locally mapped foreign key columns for " "%s join condition " "'%s' on relationship %s." % ( primary and "primary" or "secondary", join_condition, self.prop, ) ) err += ( " Ensure that referencing columns are associated " "with a ForeignKey or ForeignKeyConstraint, or are " "annotated in the join condition with the foreign() " "annotation. To allow comparison operators other than " "'==', the relationship can be marked as viewonly=True." ) raise sa_exc.ArgumentError(err) else: err = ( "Could not locate any relevant foreign key columns " "for %s join condition '%s' on relationship %s." % ( primary and "primary" or "secondary", join_condition, self.prop, ) ) err += ( " Ensure that referencing columns are associated " "with a ForeignKey or ForeignKeyConstraint, or are " "annotated in the join condition with the foreign() " "annotation." ) raise sa_exc.ArgumentError(err) def _determine_direction(self) -> None: """Determine if this relationship is one to many, many to one, many to many. """ if self.secondaryjoin is not None: self.direction = MANYTOMANY else: parentcols = util.column_set(self.parent_persist_selectable.c) targetcols = util.column_set(self.child_persist_selectable.c) # fk collection which suggests ONETOMANY. onetomany_fk = targetcols.intersection(self.foreign_key_columns) # fk collection which suggests MANYTOONE. manytoone_fk = parentcols.intersection(self.foreign_key_columns) if onetomany_fk and manytoone_fk: # fks on both sides. test for overlap of local/remote # with foreign key. # we will gather columns directly from their annotations # without deannotating, so that we can distinguish on a column # that refers to itself. # 1. columns that are both remote and FK suggest # onetomany. onetomany_local = self._gather_columns_with_annotation( self.primaryjoin, "remote", "foreign" ) # 2. columns that are FK but are not remote (e.g. local) # suggest manytoone. manytoone_local = { c for c in self._gather_columns_with_annotation( self.primaryjoin, "foreign" ) if "remote" not in c._annotations } # 3. if both collections are present, remove columns that # refer to themselves. This is for the case of # and_(Me.id == Me.remote_id, Me.version == Me.version) if onetomany_local and manytoone_local: self_equated = self.remote_columns.intersection( self.local_columns ) onetomany_local = onetomany_local.difference(self_equated) manytoone_local = manytoone_local.difference(self_equated) # at this point, if only one or the other collection is # present, we know the direction, otherwise it's still # ambiguous. if onetomany_local and not manytoone_local: self.direction = ONETOMANY elif manytoone_local and not onetomany_local: self.direction = MANYTOONE else: raise sa_exc.ArgumentError( "Can't determine relationship" " direction for relationship '%s' - foreign " "key columns within the join condition are present " "in both the parent and the child's mapped tables. " "Ensure that only those columns referring " "to a parent column are marked as foreign, " "either via the foreign() annotation or " "via the foreign_keys argument." % self.prop ) elif onetomany_fk: self.direction = ONETOMANY elif manytoone_fk: self.direction = MANYTOONE else: raise sa_exc.ArgumentError( "Can't determine relationship " "direction for relationship '%s' - foreign " "key columns are present in neither the parent " "nor the child's mapped tables" % self.prop ) def _deannotate_pairs( self, collection: _ColumnPairIterable ) -> _MutableColumnPairs: """provide deannotation for the various lists of pairs, so that using them in hashes doesn't incur high-overhead __eq__() comparisons against original columns mapped. """ return [(x._deannotate(), y._deannotate()) for x, y in collection] def _setup_pairs(self) -> None: sync_pairs: _MutableColumnPairs = [] lrp: util.OrderedSet[Tuple[ColumnElement[Any], ColumnElement[Any]]] = ( util.OrderedSet([]) ) secondary_sync_pairs: _MutableColumnPairs = [] def go( joincond: ColumnElement[bool], collection: _MutableColumnPairs, ) -> None: def visit_binary( binary: BinaryExpression[Any], left: ColumnElement[Any], right: ColumnElement[Any], ) -> None: if ( "remote" in right._annotations and "remote" not in left._annotations and self.can_be_synced_fn(left) ): lrp.add((left, right)) elif ( "remote" in left._annotations and "remote" not in right._annotations and self.can_be_synced_fn(right) ): lrp.add((right, left)) if binary.operator is operators.eq and self.can_be_synced_fn( left, right ): if "foreign" in right._annotations: collection.append((left, right)) elif "foreign" in left._annotations: collection.append((right, left)) visit_binary_product(visit_binary, joincond) for joincond, collection in [ (self.primaryjoin, sync_pairs), (self.secondaryjoin, secondary_sync_pairs), ]: if joincond is None: continue go(joincond, collection) self.local_remote_pairs = self._deannotate_pairs(lrp) self.synchronize_pairs = self._deannotate_pairs(sync_pairs) self.secondary_synchronize_pairs = self._deannotate_pairs( secondary_sync_pairs ) _track_overlapping_sync_targets: weakref.WeakKeyDictionary[ ColumnElement[Any], weakref.WeakKeyDictionary[ RelationshipProperty[Any], ColumnElement[Any] ], ] = weakref.WeakKeyDictionary() def _warn_for_conflicting_sync_targets(self) -> None: if not self.support_sync: return # we would like to detect if we are synchronizing any column # pairs in conflict with another relationship that wishes to sync # an entirely different column to the same target. This is a # very rare edge case so we will try to minimize the memory/overhead # impact of this check for from_, to_ in [ (from_, to_) for (from_, to_) in self.synchronize_pairs ] + [ (from_, to_) for (from_, to_) in self.secondary_synchronize_pairs ]: # save ourselves a ton of memory and overhead by only # considering columns that are subject to a overlapping # FK constraints at the core level. This condition can arise # if multiple relationships overlap foreign() directly, but # we're going to assume it's typically a ForeignKeyConstraint- # level configuration that benefits from this warning. if to_ not in self._track_overlapping_sync_targets: self._track_overlapping_sync_targets[to_] = ( weakref.WeakKeyDictionary({self.prop: from_}) ) else: other_props = [] prop_to_from = self._track_overlapping_sync_targets[to_] for pr, fr_ in prop_to_from.items(): if ( not pr.mapper._dispose_called and pr not in self.prop._reverse_property and pr.key not in self.prop._overlaps and self.prop.key not in pr._overlaps # note: the "__*" symbol is used internally by # SQLAlchemy as a general means of suppressing the # overlaps warning for some extension cases, however # this is not currently # a publicly supported symbol and may change at # any time. and "__*" not in self.prop._overlaps and "__*" not in pr._overlaps and not self.prop.parent.is_sibling(pr.parent) and not self.prop.mapper.is_sibling(pr.mapper) and not self.prop.parent.is_sibling(pr.mapper) and not self.prop.mapper.is_sibling(pr.parent) and ( self.prop.key != pr.key or not self.prop.parent.common_parent(pr.parent) ) ): other_props.append((pr, fr_)) if other_props: util.warn( "relationship '%s' will copy column %s to column %s, " "which conflicts with relationship(s): %s. " "If this is not the intention, consider if these " "relationships should be linked with " "back_populates, or if viewonly=True should be " "applied to one or more if they are read-only. " "For the less common case that foreign key " "constraints are partially overlapping, the " "orm.foreign() " "annotation can be used to isolate the columns that " "should be written towards. To silence this " "warning, add the parameter 'overlaps=\"%s\"' to the " "'%s' relationship." % ( self.prop, from_, to_, ", ".join( sorted( "'%s' (copies %s to %s)" % (pr, fr_, to_) for (pr, fr_) in other_props ) ), ",".join(sorted(pr.key for pr, fr in other_props)), self.prop, ), code="qzyx", ) self._track_overlapping_sync_targets[to_][self.prop] = from_ @util.memoized_property def remote_columns(self) -> Set[ColumnElement[Any]]: return self._gather_join_annotations("remote") @util.memoized_property def local_columns(self) -> Set[ColumnElement[Any]]: return self._gather_join_annotations("local") @util.memoized_property def foreign_key_columns(self) -> Set[ColumnElement[Any]]: return self._gather_join_annotations("foreign") def _gather_join_annotations( self, annotation: str ) -> Set[ColumnElement[Any]]: s = set( self._gather_columns_with_annotation(self.primaryjoin, annotation) ) if self.secondaryjoin is not None: s.update( self._gather_columns_with_annotation( self.secondaryjoin, annotation ) ) return {x._deannotate() for x in s} def _gather_columns_with_annotation( self, clause: ColumnElement[Any], *annotation: Iterable[str] ) -> Set[ColumnElement[Any]]: annotation_set = set(annotation) return { cast(ColumnElement[Any], col) for col in visitors.iterate(clause, {}) if annotation_set.issubset(col._annotations) } @util.memoized_property def _secondary_lineage_set(self) -> FrozenSet[ColumnElement[Any]]: if self.secondary is not None: return frozenset( itertools.chain(*[c.proxy_set for c in self.secondary.c]) ) else: return util.EMPTY_SET def join_targets( self, source_selectable: Optional[FromClause], dest_selectable: FromClause, aliased: bool, single_crit: Optional[ColumnElement[bool]] = None, extra_criteria: Tuple[ColumnElement[bool], ...] = (), ) -> Tuple[ ColumnElement[bool], Optional[ColumnElement[bool]], Optional[FromClause], Optional[ClauseAdapter], FromClause, ]: """Given a source and destination selectable, create a join between them. This takes into account aliasing the join clause to reference the appropriate corresponding columns in the target objects, as well as the extra child criterion, equivalent column sets, etc. """ # place a barrier on the destination such that # replacement traversals won't ever dig into it. # its internal structure remains fixed # regardless of context. dest_selectable = _shallow_annotate( dest_selectable, {"no_replacement_traverse": True} ) primaryjoin, secondaryjoin, secondary = ( self.primaryjoin, self.secondaryjoin, self.secondary, ) # adjust the join condition for single table inheritance, # in the case that the join is to a subclass # this is analogous to the # "_adjust_for_single_table_inheritance()" method in Query. if single_crit is not None: if secondaryjoin is not None: secondaryjoin = secondaryjoin & single_crit else: primaryjoin = primaryjoin & single_crit if extra_criteria: def mark_exclude_cols( elem: SupportsAnnotations, annotations: _AnnotationDict ) -> SupportsAnnotations: """note unrelated columns in the "extra criteria" as either should be adapted or not adapted, even though they are not part of our "local" or "remote" side. see #9779 for this case, as well as #11010 for a follow up """ parentmapper_for_element = elem._annotations.get( "parentmapper", None ) if ( parentmapper_for_element is not self.prop.parent and parentmapper_for_element is not self.prop.mapper and elem not in self._secondary_lineage_set ): return _safe_annotate(elem, annotations) else: return elem extra_criteria = tuple( _deep_annotate( elem, {"should_not_adapt": True}, annotate_callable=mark_exclude_cols, ) for elem in extra_criteria ) if secondaryjoin is not None: secondaryjoin = secondaryjoin & sql.and_(*extra_criteria) else: primaryjoin = primaryjoin & sql.and_(*extra_criteria) if aliased: if secondary is not None: secondary = secondary._anonymous_fromclause(flat=True) primary_aliasizer = ClauseAdapter( secondary, exclude_fn=_local_col_exclude, ) secondary_aliasizer = ClauseAdapter( dest_selectable, equivalents=self.child_equivalents ).chain(primary_aliasizer) if source_selectable is not None: primary_aliasizer = ClauseAdapter( secondary, exclude_fn=_local_col_exclude, ).chain( ClauseAdapter( source_selectable, equivalents=self.parent_equivalents, ) ) secondaryjoin = secondary_aliasizer.traverse(secondaryjoin) else: primary_aliasizer = ClauseAdapter( dest_selectable, exclude_fn=_local_col_exclude, equivalents=self.child_equivalents, ) if source_selectable is not None: primary_aliasizer.chain( ClauseAdapter( source_selectable, exclude_fn=_remote_col_exclude, equivalents=self.parent_equivalents, ) ) secondary_aliasizer = None primaryjoin = primary_aliasizer.traverse(primaryjoin) target_adapter = secondary_aliasizer or primary_aliasizer target_adapter.exclude_fn = None else: target_adapter = None return ( primaryjoin, secondaryjoin, secondary, target_adapter, dest_selectable, ) def create_lazy_clause(self, reverse_direction: bool = False) -> Tuple[ ColumnElement[bool], Dict[str, ColumnElement[Any]], Dict[ColumnElement[Any], ColumnElement[Any]], ]: binds: Dict[ColumnElement[Any], BindParameter[Any]] = {} equated_columns: Dict[ColumnElement[Any], ColumnElement[Any]] = {} has_secondary = self.secondaryjoin is not None if has_secondary: lookup = collections.defaultdict(list) for l, r in self.local_remote_pairs: lookup[l].append((l, r)) equated_columns[r] = l elif not reverse_direction: for l, r in self.local_remote_pairs: equated_columns[r] = l else: for l, r in self.local_remote_pairs: equated_columns[l] = r def col_to_bind( element: ColumnElement[Any], **kw: Any ) -> Optional[BindParameter[Any]]: if ( (not reverse_direction and "local" in element._annotations) or reverse_direction and ( (has_secondary and element in lookup) or (not has_secondary and "remote" in element._annotations) ) ): if element not in binds: binds[element] = sql.bindparam( None, None, type_=element.type, unique=True ) return binds[element] return None lazywhere = self.primaryjoin if self.secondaryjoin is None or not reverse_direction: lazywhere = visitors.replacement_traverse( lazywhere, {}, col_to_bind ) if self.secondaryjoin is not None: secondaryjoin = self.secondaryjoin if reverse_direction: secondaryjoin = visitors.replacement_traverse( secondaryjoin, {}, col_to_bind ) lazywhere = sql.and_(lazywhere, secondaryjoin) bind_to_col = {binds[col].key: col for col in binds} return lazywhere, bind_to_col, equated_columns class _ColInAnnotations: """Serializable object that tests for names in c._annotations. TODO: does this need to be serializable anymore? can we find what the use case was for that? """ __slots__ = ("names",) def __init__(self, *names: str): self.names = frozenset(names) def __call__(self, c: ClauseElement) -> bool: return bool(self.names.intersection(c._annotations)) _local_col_exclude = _ColInAnnotations("local", "should_not_adapt") _remote_col_exclude = _ColInAnnotations("remote", "should_not_adapt") class Relationship( RelationshipProperty[_T], _DeclarativeMapped[_T], ): """Describes an object property that holds a single item or list of items that correspond to a related database table. Public constructor is the :func:`_orm.relationship` function. .. seealso:: :ref:`relationship_config_toplevel` .. versionchanged:: 2.0 Added :class:`_orm.Relationship` as a Declarative compatible subclass for :class:`_orm.RelationshipProperty`. """ inherit_cache = True """:meta private:""" class _RelationshipDeclared( # type: ignore[misc] Relationship[_T], WriteOnlyMapped[_T], # not compatible with Mapped[_T] DynamicMapped[_T], # not compatible with Mapped[_T] ): """Relationship subclass used implicitly for declarative mapping.""" inherit_cache = True """:meta private:""" @classmethod def _mapper_property_name(cls) -> str: return "Relationship" sqlalchemy/orm/exc.py 0000755 00000016724 15125143220 0010644 0 ustar 00 # orm/exc.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """SQLAlchemy ORM exceptions.""" from __future__ import annotations from typing import Any from typing import Optional from typing import Tuple from typing import Type from typing import TYPE_CHECKING from typing import TypeVar from .util import _mapper_property_as_plain_name from .. import exc as sa_exc from .. import util from ..exc import MultipleResultsFound # noqa from ..exc import NoResultFound # noqa if TYPE_CHECKING: from .interfaces import LoaderStrategy from .interfaces import MapperProperty from .state import InstanceState _T = TypeVar("_T", bound=Any) NO_STATE = (AttributeError, KeyError) """Exception types that may be raised by instrumentation implementations.""" class StaleDataError(sa_exc.SQLAlchemyError): """An operation encountered database state that is unaccounted for. Conditions which cause this to happen include: * A flush may have attempted to update or delete rows and an unexpected number of rows were matched during the UPDATE or DELETE statement. Note that when version_id_col is used, rows in UPDATE or DELETE statements are also matched against the current known version identifier. * A mapped object with version_id_col was refreshed, and the version number coming back from the database does not match that of the object itself. * A object is detached from its parent object, however the object was previously attached to a different parent identity which was garbage collected, and a decision cannot be made if the new parent was really the most recent "parent". """ ConcurrentModificationError = StaleDataError class FlushError(sa_exc.SQLAlchemyError): """A invalid condition was detected during flush().""" class MappedAnnotationError(sa_exc.ArgumentError): """Raised when ORM annotated declarative cannot interpret the expression present inside of the :class:`.Mapped` construct. .. versionadded:: 2.0.40 """ class UnmappedError(sa_exc.InvalidRequestError): """Base for exceptions that involve expected mappings not present.""" class ObjectDereferencedError(sa_exc.SQLAlchemyError): """An operation cannot complete due to an object being garbage collected. """ class DetachedInstanceError(sa_exc.SQLAlchemyError): """An attempt to access unloaded attributes on a mapped instance that is detached.""" code = "bhk3" class UnmappedInstanceError(UnmappedError): """An mapping operation was requested for an unknown instance.""" @util.preload_module("sqlalchemy.orm.base") def __init__(self, obj: object, msg: Optional[str] = None): base = util.preloaded.orm_base if not msg: try: base.class_mapper(type(obj)) name = _safe_cls_name(type(obj)) msg = ( "Class %r is mapped, but this instance lacks " "instrumentation. This occurs when the instance " "is created before sqlalchemy.orm.mapper(%s) " "was called." % (name, name) ) except UnmappedClassError: msg = f"Class '{_safe_cls_name(type(obj))}' is not mapped" if isinstance(obj, type): msg += ( "; was a class (%s) supplied where an instance was " "required?" % _safe_cls_name(obj) ) UnmappedError.__init__(self, msg) def __reduce__(self) -> Any: return self.__class__, (None, self.args[0]) class UnmappedClassError(UnmappedError): """An mapping operation was requested for an unknown class.""" def __init__(self, cls: Type[_T], msg: Optional[str] = None): if not msg: msg = _default_unmapped(cls) UnmappedError.__init__(self, msg) def __reduce__(self) -> Any: return self.__class__, (None, self.args[0]) class ObjectDeletedError(sa_exc.InvalidRequestError): """A refresh operation failed to retrieve the database row corresponding to an object's known primary key identity. A refresh operation proceeds when an expired attribute is accessed on an object, or when :meth:`_query.Query.get` is used to retrieve an object which is, upon retrieval, detected as expired. A SELECT is emitted for the target row based on primary key; if no row is returned, this exception is raised. The true meaning of this exception is simply that no row exists for the primary key identifier associated with a persistent object. The row may have been deleted, or in some cases the primary key updated to a new value, outside of the ORM's management of the target object. """ @util.preload_module("sqlalchemy.orm.base") def __init__(self, state: InstanceState[Any], msg: Optional[str] = None): base = util.preloaded.orm_base if not msg: msg = ( "Instance '%s' has been deleted, or its " "row is otherwise not present." % base.state_str(state) ) sa_exc.InvalidRequestError.__init__(self, msg) def __reduce__(self) -> Any: return self.__class__, (None, self.args[0]) class UnmappedColumnError(sa_exc.InvalidRequestError): """Mapping operation was requested on an unknown column.""" class LoaderStrategyException(sa_exc.InvalidRequestError): """A loader strategy for an attribute does not exist.""" def __init__( self, applied_to_property_type: Type[Any], requesting_property: MapperProperty[Any], applies_to: Optional[Type[MapperProperty[Any]]], actual_strategy_type: Optional[Type[LoaderStrategy]], strategy_key: Tuple[Any, ...], ): if actual_strategy_type is None: sa_exc.InvalidRequestError.__init__( self, "Can't find strategy %s for %s" % (strategy_key, requesting_property), ) else: assert applies_to is not None sa_exc.InvalidRequestError.__init__( self, 'Can\'t apply "%s" strategy to property "%s", ' 'which is a "%s"; this loader strategy is intended ' 'to be used with a "%s".' % ( util.clsname_as_plain_name(actual_strategy_type), requesting_property, _mapper_property_as_plain_name(applied_to_property_type), _mapper_property_as_plain_name(applies_to), ), ) def _safe_cls_name(cls: Type[Any]) -> str: cls_name: Optional[str] try: cls_name = ".".join((cls.__module__, cls.__name__)) except AttributeError: cls_name = getattr(cls, "__name__", None) if cls_name is None: cls_name = repr(cls) return cls_name @util.preload_module("sqlalchemy.orm.base") def _default_unmapped(cls: Type[Any]) -> Optional[str]: base = util.preloaded.orm_base try: mappers = base.manager_of_class(cls).mappers # type: ignore except ( UnmappedClassError, TypeError, ) + NO_STATE: mappers = {} name = _safe_cls_name(cls) if not mappers: return f"Class '{name}' is not mapped" else: return None sqlalchemy/engine/create.py 0000755 00000100701 15125143220 0011765 0 ustar 00 # engine/create.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php from __future__ import annotations import inspect import typing from typing import Any from typing import Callable from typing import cast from typing import Dict from typing import List from typing import Optional from typing import overload from typing import Type from typing import Union from . import base from . import url as _url from .interfaces import DBAPIConnection from .mock import create_mock_engine from .. import event from .. import exc from .. import util from ..pool import _AdhocProxiedConnection from ..pool import ConnectionPoolEntry from ..sql import compiler from ..util import immutabledict if typing.TYPE_CHECKING: from .base import Engine from .interfaces import _ExecuteOptions from .interfaces import _ParamStyle from .interfaces import IsolationLevel from .url import URL from ..log import _EchoFlagType from ..pool import _CreatorFnType from ..pool import _CreatorWRecFnType from ..pool import _ResetStyleArgType from ..pool import Pool from ..util.typing import Literal @overload def create_engine( url: Union[str, URL], *, connect_args: Dict[Any, Any] = ..., convert_unicode: bool = ..., creator: Union[_CreatorFnType, _CreatorWRecFnType] = ..., echo: _EchoFlagType = ..., echo_pool: _EchoFlagType = ..., enable_from_linting: bool = ..., execution_options: _ExecuteOptions = ..., future: Literal[True], hide_parameters: bool = ..., implicit_returning: Literal[True] = ..., insertmanyvalues_page_size: int = ..., isolation_level: IsolationLevel = ..., json_deserializer: Callable[..., Any] = ..., json_serializer: Callable[..., Any] = ..., label_length: Optional[int] = ..., logging_name: str = ..., max_identifier_length: Optional[int] = ..., max_overflow: int = ..., module: Optional[Any] = ..., paramstyle: Optional[_ParamStyle] = ..., pool: Optional[Pool] = ..., poolclass: Optional[Type[Pool]] = ..., pool_logging_name: str = ..., pool_pre_ping: bool = ..., pool_size: int = ..., pool_recycle: int = ..., pool_reset_on_return: Optional[_ResetStyleArgType] = ..., pool_timeout: float = ..., pool_use_lifo: bool = ..., plugins: List[str] = ..., query_cache_size: int = ..., use_insertmanyvalues: bool = ..., **kwargs: Any, ) -> Engine: ... @overload def create_engine(url: Union[str, URL], **kwargs: Any) -> Engine: ... @util.deprecated_params( strategy=( "1.4", "The :paramref:`_sa.create_engine.strategy` keyword is deprecated, " "and the only argument accepted is 'mock'; please use " ":func:`.create_mock_engine` going forward. For general " "customization of create_engine which may have been accomplished " "using strategies, see :class:`.CreateEnginePlugin`.", ), empty_in_strategy=( "1.4", "The :paramref:`_sa.create_engine.empty_in_strategy` keyword is " "deprecated, and no longer has any effect. All IN expressions " "are now rendered using " 'the "expanding parameter" strategy which renders a set of bound' 'expressions, or an "empty set" SELECT, at statement execution' "time.", ), implicit_returning=( "2.0", "The :paramref:`_sa.create_engine.implicit_returning` parameter " "is deprecated and will be removed in a future release. ", ), ) def create_engine(url: Union[str, _url.URL], **kwargs: Any) -> Engine: """Create a new :class:`_engine.Engine` instance. The standard calling form is to send the :ref:`URL <database_urls>` as the first positional argument, usually a string that indicates database dialect and connection arguments:: engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test") .. note:: Please review :ref:`database_urls` for general guidelines in composing URL strings. In particular, special characters, such as those often part of passwords, must be URL encoded to be properly parsed. Additional keyword arguments may then follow it which establish various options on the resulting :class:`_engine.Engine` and its underlying :class:`.Dialect` and :class:`_pool.Pool` constructs:: engine = create_engine( "mysql+mysqldb://scott:tiger@hostname/dbname", pool_recycle=3600, echo=True, ) The string form of the URL is ``dialect[+driver]://user:password@host/dbname[?key=value..]``, where ``dialect`` is a database name such as ``mysql``, ``oracle``, ``postgresql``, etc., and ``driver`` the name of a DBAPI, such as ``psycopg2``, ``pyodbc``, ``cx_oracle``, etc. Alternatively, the URL can be an instance of :class:`~sqlalchemy.engine.url.URL`. ``**kwargs`` takes a wide variety of options which are routed towards their appropriate components. Arguments may be specific to the :class:`_engine.Engine`, the underlying :class:`.Dialect`, as well as the :class:`_pool.Pool`. Specific dialects also accept keyword arguments that are unique to that dialect. Here, we describe the parameters that are common to most :func:`_sa.create_engine()` usage. Once established, the newly resulting :class:`_engine.Engine` will request a connection from the underlying :class:`_pool.Pool` once :meth:`_engine.Engine.connect` is called, or a method which depends on it such as :meth:`_engine.Engine.execute` is invoked. The :class:`_pool.Pool` in turn will establish the first actual DBAPI connection when this request is received. The :func:`_sa.create_engine` call itself does **not** establish any actual DBAPI connections directly. .. seealso:: :doc:`/core/engines` :doc:`/dialects/index` :ref:`connections_toplevel` :param connect_args: a dictionary of options which will be passed directly to the DBAPI's ``connect()`` method as additional keyword arguments. See the example at :ref:`custom_dbapi_args`. :param creator: a callable which returns a DBAPI connection. This creation function will be passed to the underlying connection pool and will be used to create all new database connections. Usage of this function causes connection parameters specified in the URL argument to be bypassed. This hook is not as flexible as the newer :meth:`_events.DialectEvents.do_connect` hook which allows complete control over how a connection is made to the database, given the full set of URL arguments and state beforehand. .. seealso:: :meth:`_events.DialectEvents.do_connect` - event hook that allows full control over DBAPI connection mechanics. :ref:`custom_dbapi_args` :param echo=False: if True, the Engine will log all statements as well as a ``repr()`` of their parameter lists to the default log handler, which defaults to ``sys.stdout`` for output. If set to the string ``"debug"``, result rows will be printed to the standard output as well. The ``echo`` attribute of ``Engine`` can be modified at any time to turn logging on and off; direct control of logging is also available using the standard Python ``logging`` module. .. seealso:: :ref:`dbengine_logging` - further detail on how to configure logging. :param echo_pool=False: if True, the connection pool will log informational output such as when connections are invalidated as well as when connections are recycled to the default log handler, which defaults to ``sys.stdout`` for output. If set to the string ``"debug"``, the logging will include pool checkouts and checkins. Direct control of logging is also available using the standard Python ``logging`` module. .. seealso:: :ref:`dbengine_logging` - further detail on how to configure logging. :param empty_in_strategy: No longer used; SQLAlchemy now uses "empty set" behavior for IN in all cases. :param enable_from_linting: defaults to True. Will emit a warning if a given SELECT statement is found to have un-linked FROM elements which would cause a cartesian product. .. versionadded:: 1.4 .. seealso:: :ref:`change_4737` :param execution_options: Dictionary execution options which will be applied to all connections. See :meth:`~sqlalchemy.engine.Connection.execution_options` :param future: Use the 2.0 style :class:`_engine.Engine` and :class:`_engine.Connection` API. As of SQLAlchemy 2.0, this parameter is present for backwards compatibility only and must remain at its default value of ``True``. The :paramref:`_sa.create_engine.future` parameter will be deprecated in a subsequent 2.x release and eventually removed. .. versionadded:: 1.4 .. versionchanged:: 2.0 All :class:`_engine.Engine` objects are "future" style engines and there is no longer a ``future=False`` mode of operation. .. seealso:: :ref:`migration_20_toplevel` :param hide_parameters: Boolean, when set to True, SQL statement parameters will not be displayed in INFO logging nor will they be formatted into the string representation of :class:`.StatementError` objects. .. versionadded:: 1.3.8 .. seealso:: :ref:`dbengine_logging` - further detail on how to configure logging. :param implicit_returning=True: Legacy parameter that may only be set to True. In SQLAlchemy 2.0, this parameter does nothing. In order to disable "implicit returning" for statements invoked by the ORM, configure this on a per-table basis using the :paramref:`.Table.implicit_returning` parameter. :param insertmanyvalues_page_size: number of rows to format into an INSERT statement when the statement uses "insertmanyvalues" mode, which is a paged form of bulk insert that is used for many backends when using :term:`executemany` execution typically in conjunction with RETURNING. Defaults to 1000, but may also be subject to dialect-specific limiting factors which may override this value on a per-statement basis. .. versionadded:: 2.0 .. seealso:: :ref:`engine_insertmanyvalues` :ref:`engine_insertmanyvalues_page_size` :paramref:`_engine.Connection.execution_options.insertmanyvalues_page_size` :param isolation_level: optional string name of an isolation level which will be set on all new connections unconditionally. Isolation levels are typically some subset of the string names ``"SERIALIZABLE"``, ``"REPEATABLE READ"``, ``"READ COMMITTED"``, ``"READ UNCOMMITTED"`` and ``"AUTOCOMMIT"`` based on backend. The :paramref:`_sa.create_engine.isolation_level` parameter is in contrast to the :paramref:`.Connection.execution_options.isolation_level` execution option, which may be set on an individual :class:`.Connection`, as well as the same parameter passed to :meth:`.Engine.execution_options`, where it may be used to create multiple engines with different isolation levels that share a common connection pool and dialect. .. versionchanged:: 2.0 The :paramref:`_sa.create_engine.isolation_level` parameter has been generalized to work on all dialects which support the concept of isolation level, and is provided as a more succinct, up front configuration switch in contrast to the execution option which is more of an ad-hoc programmatic option. .. seealso:: :ref:`dbapi_autocommit` :param json_deserializer: for dialects that support the :class:`_types.JSON` datatype, this is a Python callable that will convert a JSON string to a Python object. By default, the Python ``json.loads`` function is used. .. versionchanged:: 1.3.7 The SQLite dialect renamed this from ``_json_deserializer``. :param json_serializer: for dialects that support the :class:`_types.JSON` datatype, this is a Python callable that will render a given object as JSON. By default, the Python ``json.dumps`` function is used. .. versionchanged:: 1.3.7 The SQLite dialect renamed this from ``_json_serializer``. :param label_length=None: optional integer value which limits the size of dynamically generated column labels to that many characters. If less than 6, labels are generated as "_(counter)". If ``None``, the value of ``dialect.max_identifier_length``, which may be affected via the :paramref:`_sa.create_engine.max_identifier_length` parameter, is used instead. The value of :paramref:`_sa.create_engine.label_length` may not be larger than that of :paramref:`_sa.create_engine.max_identfier_length`. .. seealso:: :paramref:`_sa.create_engine.max_identifier_length` :param logging_name: String identifier which will be used within the "name" field of logging records generated within the "sqlalchemy.engine" logger. Defaults to a hexstring of the object's id. .. seealso:: :ref:`dbengine_logging` - further detail on how to configure logging. :paramref:`_engine.Connection.execution_options.logging_token` :param max_identifier_length: integer; override the max_identifier_length determined by the dialect. if ``None`` or zero, has no effect. This is the database's configured maximum number of characters that may be used in a SQL identifier such as a table name, column name, or label name. All dialects determine this value automatically, however in the case of a new database version for which this value has changed but SQLAlchemy's dialect has not been adjusted, the value may be passed here. .. versionadded:: 1.3.9 .. seealso:: :paramref:`_sa.create_engine.label_length` :param max_overflow=10: the number of connections to allow in connection pool "overflow", that is connections that can be opened above and beyond the pool_size setting, which defaults to five. this is only used with :class:`~sqlalchemy.pool.QueuePool`. :param module=None: reference to a Python module object (the module itself, not its string name). Specifies an alternate DBAPI module to be used by the engine's dialect. Each sub-dialect references a specific DBAPI which will be imported before first connect. This parameter causes the import to be bypassed, and the given module to be used instead. Can be used for testing of DBAPIs as well as to inject "mock" DBAPI implementations into the :class:`_engine.Engine`. :param paramstyle=None: The `paramstyle <https://legacy.python.org/dev/peps/pep-0249/#paramstyle>`_ to use when rendering bound parameters. This style defaults to the one recommended by the DBAPI itself, which is retrieved from the ``.paramstyle`` attribute of the DBAPI. However, most DBAPIs accept more than one paramstyle, and in particular it may be desirable to change a "named" paramstyle into a "positional" one, or vice versa. When this attribute is passed, it should be one of the values ``"qmark"``, ``"numeric"``, ``"named"``, ``"format"`` or ``"pyformat"``, and should correspond to a parameter style known to be supported by the DBAPI in use. :param pool=None: an already-constructed instance of :class:`~sqlalchemy.pool.Pool`, such as a :class:`~sqlalchemy.pool.QueuePool` instance. If non-None, this pool will be used directly as the underlying connection pool for the engine, bypassing whatever connection parameters are present in the URL argument. For information on constructing connection pools manually, see :ref:`pooling_toplevel`. :param poolclass=None: a :class:`~sqlalchemy.pool.Pool` subclass, which will be used to create a connection pool instance using the connection parameters given in the URL. Note this differs from ``pool`` in that you don't actually instantiate the pool in this case, you just indicate what type of pool to be used. :param pool_logging_name: String identifier which will be used within the "name" field of logging records generated within the "sqlalchemy.pool" logger. Defaults to a hexstring of the object's id. .. seealso:: :ref:`dbengine_logging` - further detail on how to configure logging. :param pool_pre_ping: boolean, if True will enable the connection pool "pre-ping" feature that tests connections for liveness upon each checkout. .. versionadded:: 1.2 .. seealso:: :ref:`pool_disconnects_pessimistic` :param pool_size=5: the number of connections to keep open inside the connection pool. This used with :class:`~sqlalchemy.pool.QueuePool` as well as :class:`~sqlalchemy.pool.SingletonThreadPool`. With :class:`~sqlalchemy.pool.QueuePool`, a ``pool_size`` setting of 0 indicates no limit; to disable pooling, set ``poolclass`` to :class:`~sqlalchemy.pool.NullPool` instead. :param pool_recycle=-1: this setting causes the pool to recycle connections after the given number of seconds has passed. It defaults to -1, or no timeout. For example, setting to 3600 means connections will be recycled after one hour. Note that MySQL in particular will disconnect automatically if no activity is detected on a connection for eight hours (although this is configurable with the MySQLDB connection itself and the server configuration as well). .. seealso:: :ref:`pool_setting_recycle` :param pool_reset_on_return='rollback': set the :paramref:`_pool.Pool.reset_on_return` parameter of the underlying :class:`_pool.Pool` object, which can be set to the values ``"rollback"``, ``"commit"``, or ``None``. .. seealso:: :ref:`pool_reset_on_return` :param pool_timeout=30: number of seconds to wait before giving up on getting a connection from the pool. This is only used with :class:`~sqlalchemy.pool.QueuePool`. This can be a float but is subject to the limitations of Python time functions which may not be reliable in the tens of milliseconds. .. note: don't use 30.0 above, it seems to break with the :param tag :param pool_use_lifo=False: use LIFO (last-in-first-out) when retrieving connections from :class:`.QueuePool` instead of FIFO (first-in-first-out). Using LIFO, a server-side timeout scheme can reduce the number of connections used during non- peak periods of use. When planning for server-side timeouts, ensure that a recycle or pre-ping strategy is in use to gracefully handle stale connections. .. versionadded:: 1.3 .. seealso:: :ref:`pool_use_lifo` :ref:`pool_disconnects` :param plugins: string list of plugin names to load. See :class:`.CreateEnginePlugin` for background. .. versionadded:: 1.2.3 :param query_cache_size: size of the cache used to cache the SQL string form of queries. Set to zero to disable caching. The cache is pruned of its least recently used items when its size reaches N * 1.5. Defaults to 500, meaning the cache will always store at least 500 SQL statements when filled, and will grow up to 750 items at which point it is pruned back down to 500 by removing the 250 least recently used items. Caching is accomplished on a per-statement basis by generating a cache key that represents the statement's structure, then generating string SQL for the current dialect only if that key is not present in the cache. All statements support caching, however some features such as an INSERT with a large set of parameters will intentionally bypass the cache. SQL logging will indicate statistics for each statement whether or not it were pull from the cache. .. note:: some ORM functions related to unit-of-work persistence as well as some attribute loading strategies will make use of individual per-mapper caches outside of the main cache. .. seealso:: :ref:`sql_caching` .. versionadded:: 1.4 :param use_insertmanyvalues: True by default, use the "insertmanyvalues" execution style for INSERT..RETURNING statements by default. .. versionadded:: 2.0 .. seealso:: :ref:`engine_insertmanyvalues` """ # noqa if "strategy" in kwargs: strat = kwargs.pop("strategy") if strat == "mock": # this case is deprecated return create_mock_engine(url, **kwargs) # type: ignore else: raise exc.ArgumentError("unknown strategy: %r" % strat) kwargs.pop("empty_in_strategy", None) # create url.URL object u = _url.make_url(url) u, plugins, kwargs = u._instantiate_plugins(kwargs) entrypoint = u._get_entrypoint() _is_async = kwargs.pop("_is_async", False) if _is_async: dialect_cls = entrypoint.get_async_dialect_cls(u) else: dialect_cls = entrypoint.get_dialect_cls(u) if kwargs.pop("_coerce_config", False): def pop_kwarg(key: str, default: Optional[Any] = None) -> Any: value = kwargs.pop(key, default) if key in dialect_cls.engine_config_types: value = dialect_cls.engine_config_types[key](value) return value else: pop_kwarg = kwargs.pop # type: ignore dialect_args = {} # consume dialect arguments from kwargs for k in util.get_cls_kwargs(dialect_cls): if k in kwargs: dialect_args[k] = pop_kwarg(k) dbapi = kwargs.pop("module", None) if dbapi is None: dbapi_args = {} if "import_dbapi" in dialect_cls.__dict__: dbapi_meth = dialect_cls.import_dbapi elif hasattr(dialect_cls, "dbapi") and inspect.ismethod( dialect_cls.dbapi ): util.warn_deprecated( "The dbapi() classmethod on dialect classes has been " "renamed to import_dbapi(). Implement an import_dbapi() " f"classmethod directly on class {dialect_cls} to remove this " "warning; the old .dbapi() classmethod may be maintained for " "backwards compatibility.", "2.0", ) dbapi_meth = dialect_cls.dbapi else: dbapi_meth = dialect_cls.import_dbapi for k in util.get_func_kwargs(dbapi_meth): if k in kwargs: dbapi_args[k] = pop_kwarg(k) dbapi = dbapi_meth(**dbapi_args) dialect_args["dbapi"] = dbapi dialect_args.setdefault("compiler_linting", compiler.NO_LINTING) enable_from_linting = kwargs.pop("enable_from_linting", True) if enable_from_linting: dialect_args["compiler_linting"] ^= compiler.COLLECT_CARTESIAN_PRODUCTS for plugin in plugins: plugin.handle_dialect_kwargs(dialect_cls, dialect_args) # create dialect dialect = dialect_cls(**dialect_args) # assemble connection arguments (cargs_tup, cparams) = dialect.create_connect_args(u) cparams.update(pop_kwarg("connect_args", {})) if "async_fallback" in cparams and util.asbool(cparams["async_fallback"]): util.warn_deprecated( "The async_fallback dialect argument is deprecated and will be " "removed in SQLAlchemy 2.1.", "2.0", ) cargs = list(cargs_tup) # allow mutability # look for existing pool or create pool = pop_kwarg("pool", None) if pool is None: def connect( connection_record: Optional[ConnectionPoolEntry] = None, ) -> DBAPIConnection: if dialect._has_events: for fn in dialect.dispatch.do_connect: connection = cast( DBAPIConnection, fn(dialect, connection_record, cargs, cparams), ) if connection is not None: return connection return dialect.connect(*cargs, **cparams) creator = pop_kwarg("creator", connect) poolclass = pop_kwarg("poolclass", None) if poolclass is None: poolclass = dialect.get_dialect_pool_class(u) pool_args = {"dialect": dialect} # consume pool arguments from kwargs, translating a few of # the arguments for k in util.get_cls_kwargs(poolclass): tk = _pool_translate_kwargs.get(k, k) if tk in kwargs: pool_args[k] = pop_kwarg(tk) for plugin in plugins: plugin.handle_pool_kwargs(poolclass, pool_args) pool = poolclass(creator, **pool_args) else: pool._dialect = dialect if ( hasattr(pool, "_is_asyncio") and pool._is_asyncio is not dialect.is_async ): raise exc.ArgumentError( f"Pool class {pool.__class__.__name__} cannot be " f"used with {'non-' if not dialect.is_async else ''}" "asyncio engine", code="pcls", ) # create engine. if not pop_kwarg("future", True): raise exc.ArgumentError( "The 'future' parameter passed to " "create_engine() may only be set to True." ) engineclass = base.Engine engine_args = {} for k in util.get_cls_kwargs(engineclass): if k in kwargs: engine_args[k] = pop_kwarg(k) # internal flags used by the test suite for instrumenting / proxying # engines with mocks etc. _initialize = kwargs.pop("_initialize", True) # all kwargs should be consumed if kwargs: raise TypeError( "Invalid argument(s) %s sent to create_engine(), " "using configuration %s/%s/%s. Please check that the " "keyword arguments are appropriate for this combination " "of components." % ( ",".join("'%s'" % k for k in kwargs), dialect.__class__.__name__, pool.__class__.__name__, engineclass.__name__, ) ) engine = engineclass(pool, dialect, u, **engine_args) if _initialize: do_on_connect = dialect.on_connect_url(u) if do_on_connect: def on_connect( dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry, ) -> None: assert do_on_connect is not None do_on_connect(dbapi_connection) event.listen(pool, "connect", on_connect) builtin_on_connect = dialect._builtin_onconnect() if builtin_on_connect: event.listen(pool, "connect", builtin_on_connect) def first_connect( dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry, ) -> None: c = base.Connection( engine, connection=_AdhocProxiedConnection( dbapi_connection, connection_record ), _has_events=False, # reconnecting will be a reentrant condition, so if the # connection goes away, Connection is then closed _allow_revalidate=False, # dont trigger the autobegin sequence # within the up front dialect checks _allow_autobegin=False, ) c._execution_options = util.EMPTY_DICT try: dialect.initialize(c) finally: # note that "invalidated" and "closed" are mutually # exclusive in 1.4 Connection. if not c.invalidated and not c.closed: # transaction is rolled back otherwise, tested by # test/dialect/postgresql/test_dialect.py # ::MiscBackendTest::test_initial_transaction_state dialect.do_rollback(c.connection) # previously, the "first_connect" event was used here, which was then # scaled back if the "on_connect" handler were present. now, # since "on_connect" is virtually always present, just use # "connect" event with once_unless_exception in all cases so that # the connection event flow is consistent in all cases. event.listen( pool, "connect", first_connect, _once_unless_exception=True ) dialect_cls.engine_created(engine) if entrypoint is not dialect_cls: entrypoint.engine_created(engine) for plugin in plugins: plugin.engine_created(engine) return engine def engine_from_config( configuration: Dict[str, Any], prefix: str = "sqlalchemy.", **kwargs: Any ) -> Engine: """Create a new Engine instance using a configuration dictionary. The dictionary is typically produced from a config file. The keys of interest to ``engine_from_config()`` should be prefixed, e.g. ``sqlalchemy.url``, ``sqlalchemy.echo``, etc. The 'prefix' argument indicates the prefix to be searched for. Each matching key (after the prefix is stripped) is treated as though it were the corresponding keyword argument to a :func:`_sa.create_engine` call. The only required key is (assuming the default prefix) ``sqlalchemy.url``, which provides the :ref:`database URL <database_urls>`. A select set of keyword arguments will be "coerced" to their expected type based on string values. The set of arguments is extensible per-dialect using the ``engine_config_types`` accessor. :param configuration: A dictionary (typically produced from a config file, but this is not a requirement). Items whose keys start with the value of 'prefix' will have that prefix stripped, and will then be passed to :func:`_sa.create_engine`. :param prefix: Prefix to match and then strip from keys in 'configuration'. :param kwargs: Each keyword argument to ``engine_from_config()`` itself overrides the corresponding item taken from the 'configuration' dictionary. Keyword arguments should *not* be prefixed. """ options = { key[len(prefix) :]: configuration[key] for key in configuration if key.startswith(prefix) } options["_coerce_config"] = True options.update(kwargs) url = options.pop("url") return create_engine(url, **options) @overload def create_pool_from_url( url: Union[str, URL], *, poolclass: Optional[Type[Pool]] = ..., logging_name: str = ..., pre_ping: bool = ..., size: int = ..., recycle: int = ..., reset_on_return: Optional[_ResetStyleArgType] = ..., timeout: float = ..., use_lifo: bool = ..., **kwargs: Any, ) -> Pool: ... @overload def create_pool_from_url(url: Union[str, URL], **kwargs: Any) -> Pool: ... def create_pool_from_url(url: Union[str, URL], **kwargs: Any) -> Pool: """Create a pool instance from the given url. If ``poolclass`` is not provided the pool class used is selected using the dialect specified in the URL. The arguments passed to :func:`_sa.create_pool_from_url` are identical to the pool argument passed to the :func:`_sa.create_engine` function. .. versionadded:: 2.0.10 """ for key in _pool_translate_kwargs: if key in kwargs: kwargs[_pool_translate_kwargs[key]] = kwargs.pop(key) engine = create_engine(url, **kwargs, _initialize=False) return engine.pool _pool_translate_kwargs = immutabledict( { "logging_name": "pool_logging_name", "echo": "echo_pool", "timeout": "pool_timeout", "recycle": "pool_recycle", "events": "pool_events", # deprecated "reset_on_return": "pool_reset_on_return", "pre_ping": "pool_pre_ping", "use_lifo": "pool_use_lifo", } ) sqlalchemy/engine/__pycache__/default.cpython-39.pyc 0000644 00000164677 15125143220 0016460 0 ustar 00 a ��Jh:M � @ s d Z ddlmZ ddlZddlZddlZddlZddlmZ ddl Z ddl m Z ddl m Z ddl m Z ddl m Z dd l mZ dd l mZ dd l mZ dd l mZ dd l mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddlZddlmZ ddlm Z ddlm Z ddl m Z ddl m!Z! ddl m"Z" ddl m#Z# dd l m$Z$ dd l m%Z% dd l&m'Z' dd l&m(Z( d d!lm)Z) d d"lm*Z* d d#lm+Z+ d d$lm,Z, d d%l-m.Z. d d&l-m/Z/ d d'l-m0Z0 d d(l-m1Z1 d d$l-m,Z2 d d)l3m4Z4 d d*l5m6Z6 d d+l7m8Z8 d d,l7m9Z9 d d-l7m:Z: d d.l;m<Z< d d/l=m>Z> d d0l=m?Z? e j�r�dd1l@mAZA dd2l mBZB dd3l mCZC dd4l mDZD dd5l mEZE dd6l mFZF dd7l mGZG dd8l mHZH dd9l mIZI dd:l mJZJ dd;l mKZK dd<l mLZL dd=l mMZM dd>l mNZN dd?lOmPZP dd@lQmRZR d dAl)mSZS d dBl+mTZT d dCl+mUZU d dDl-mVZV d dEl7mWZW d dFl7mXZX d dGl7mYZY d dHlZm[Z[ d dIlZm\Z\ d dJl;m]Z] d dKl^m_Z_ d dLl`maZa d dMl`mbZb d dNl`mcZc e�ddOejeejfB �Zgehe!�\ZiZjZkZlZmG dPdQ� dQe#�ZnG dRdS� dSen�ZoG dTdU� dUe%�Zpepen_qdS )Va Default implementations of per-dialect sqlalchemy.engine classes. These are semi-private implementation classes which are only of importance to database dialect authors; dialects will usually use the classes here as the base class for their own corresponding classes. � )� annotationsN)� perf_counter)�Any)�Callable)�cast)�Dict)�List)�Mapping)�MutableMapping)�MutableSequence)�Optional)�Sequence)�Set)�Tuple)�Type)� TYPE_CHECKING)�Union� )�characteristics)�cursor)� interfaces)� Connection)� CacheStats)� DBAPICursor)�Dialect)� ExecuteStyle)�ExecutionContext)� ObjectKind)� ObjectScope� )�event)�exc)�pool)�util)�compiler)�dml)� expression)�type_api)� is_tuple_type)�_NoArg)� DDLCompiler)� InsertmanyvaluesSentinelOpts)� SQLCompiler)� quoted_name)�Final)�Literal)� ModuleType)�Engine)�ResultFetchStrategy)�_CoreMultiExecuteParams)�_CoreSingleExecuteParams)�_DBAPICursorDescription)�_DBAPIMultiExecuteParams)�_DBAPISingleExecuteParams)�_ExecuteOptions)� _MutableCoreSingleExecuteParams)� _ParamStyle)�ConnectArgsType)�DBAPIConnection)�IsolationLevel)�Row)�URL)�_ListenerFnType)�Pool)�PoolProxiedConnection)� Executable)�Compiled)�Linting)�ResultColumnsEntry)�DMLState)� UpdateBase)� BindParameter)�Column)�_BindProcessorType)�_ResultProcessorType)� TypeEnginez \s*SELECTc @ s e Zd ZU dZejZejZej Z ej Z dZ dZdZdZdZdZejjZdZded< dZded< dZeZ dZ dZ dZ dZ dZ!dZ"dZ#dZ$dZ%dZ&dZ'dZ(dZ)dZ*dZ+dZ,dZ-dZ.dZ/dZ0dZ1dZ2e3�4e5�6� e5�7� d ��Z8e3�4e3j9e3�:d �e3�:d �e3j9e3j9e3j9e3j;d ��Z<d ed < dZ=dZ>dZ?dZ@ded< dZAded< dZBded< dZCded< dZDdZEi ZFded< dZGdZHdZIdZJdZKdZLdZMded< dZNded < eOjPZQd ed < d ZRd ed!< d"ZSdZTdZUdZVdZWdZXdZYded#< dZZdZ[dZ\d$Z]e3j^d%d&d'�ddddddde_j`deaejb�df d(d)d*d+d,ddd-d,d.dd/d0� d1d2��Zcede3�ed3d4�d5d6� ��Zfe3jgd7d8� �Zhe3jgd9d:� �ZidZjdZke3jgd;d<�d=d>��Zle3jgd?d@� �ZmdAdBdC�dDdE�Zne3jgdFdG� �Zoe3jgdHdI� �ZpeddJdK� �ZqeddLdM� �ZresdNdOdP�dQdR��ZtdNdOdP�dSdT�ZuesdUdV� �ZvdWd<�dXdY�ZwdAdBdZ�d[d\�Zxd]d<�d^d_�Zyd`da� Zzdbdc� Z{ddde� Z|d�dfdg�Z}dAdhd/ddi�djdk�Z~dhdBdl�dmdn�Zd/d/dodp�dqdr�Z�dNdsdP�dtdu�Z�dvd dBdw�dxdy�Z�dAd dBdz�d{d|�Z�d}d~� Z�dd�� Z�d�d�� Z�d�d�� Z�d�d�� Z�d�d�� Z�d�d�� Z�e3jgd�d�� �Z�dodd��d�d��Z�dodd��d�d��Z�d�d�� Z�d�d�� Z�d�d�� Z�d�d�� Z�d�d�� Z�d�d�d��Z�d�d�d��Z�d�d�d��Z�d�d�d�dd��d�d��Z�e3j�d�d�� �Z�d�d�� Z�d�d�� Z�d�d�� Z�d�d�� Z�d�d�� Z�d�d�� Z�d�d�� Z�d�d�� Z�d�d�� Z�d�d�� Z�d�d�� Z�d�d�� Z�d�dÄ Z�d�dń Z�d�dDŽ Z�dS )��DefaultDialectz!Default implementation of DialectTFNzOptional[Set[Any]]�include_set_input_sizes�exclude_set_input_sizesr )�isolation_levelZ logging_token�debug)� pool_timeoutZechoZ echo_poolZ pool_recycleZ pool_sizeZ max_overflow�future�Mapping[str, Any]�engine_config_types�defaulti' � Optional[int]�#_user_defined_max_identifier_lengthz Optional[str]rQ �max_index_name_length�max_constraint_name_lengthz<MutableMapping[Type[TypeEngine[Any]], Type[TypeEngine[Any]]]�colspecs�named�DEFAULT�bool�use_insertmanyvalues�!use_insertmanyvalues_wo_returningr+ �"insertmanyvalues_implicit_sentineli� �int�insertmanyvalues_page_sizei� �default_schema_namezutf-8)�1.4a The :paramref:`_sa.create_engine.empty_in_strategy` keyword is deprecated, and no longer has any effect. All IN expressions are now rendered using the "expanding parameter" strategy which renders a set of boundexpressions, or an "empty set" SELECT, at statement executiontime.)rf z�The :paramref:`_sa.create_engine.server_side_cursors` parameter is deprecated and will be removed in a future release. Please use the :paramref:`_engine.Connection.execution_options.stream_results` parameter.)Zempty_in_strategy�server_side_cursorszOptional[_ParamStyle]zOptional[IsolationLevel]zOptional[ModuleType]z Literal[True]zOptional[bool]zUnion[_NoArg, int]rE r ) � paramstylerQ �dbapi�implicit_returning�supports_native_boolean�max_identifier_length� label_lengthrd r` �compiler_lintingrg �kwargsc K s4 | r | j st�d| ��nd| _t| dd�rBt�dd� tjj | _ d| _ d | _ || _ |d urd|| _n | j d urz| j j| _n| j| _| jdv | _ | �| �| _|| _t| dd �} | d ur�tttj | j�}n| j}|| � | _| _|d ur�|| _|| _| j�r| j| _ || _ | | _ | d u�r | | _ |t j!u�r0|| _"d S ) Nz/Dialect %s does not support server side cursorsTZuse_setinputsizesFzoThe dialect-level use_setinputsizes attribute is deprecated. Please use bind_typing = BindTyping.SETINPUTSIZES�2.0)Zqmark�format�numericZnumeric_dollar� type_compiler)#� supports_server_side_cursorsr! � ArgumentErrorrg �getattrr# Zwarn_deprecatedr � BindTypingZ SETINPUTSIZES� bind_typing� positionalZ_ischemari rh �default_paramstyle�preparer�identifier_preparer�_on_connect_isolation_levelr r r$ �GenericTypeCompilerrs �type_compiler_clsZtype_compiler_instancerk rY rl rm rn r` r) �NO_ARGrd )�selfrh rQ ri rj rk rl rm rd r` rn rg ro Zlegacy_tt_callableZ tt_callable� r� �N/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/engine/default.py�__init__ sV $� � �� zDefaultDialect.__init__rp z]full_returning is deprecated, please use insert_returning, update_returning, delete_returningc C s | j o| jo| jS �N)�insert_returning�update_returning�delete_returning�r� r� r� r� �full_returningx s ��z DefaultDialect.full_returningc C s | j o | jS )a Default implementation for insert_executemany_returning, if not otherwise overridden by the specific dialect. The default dialect determines "insert_executemany_returning" is available if the dialect in use has opted into using the "use_insertmanyvalues" feature. If they haven't opted into that, then this attribute is False, unless the dialect in question overrides this and provides some other implementation (such as the Oracle Database dialects). �r� r` r� r� r� r� � insert_executemany_returning� s z+DefaultDialect.insert_executemany_returningc C s | j o | jS )a� Default implementation for insert_executemany_returning_deterministic_order, if not otherwise overridden by the specific dialect. The default dialect determines "insert_executemany_returning" can have deterministic order only if the dialect in use has opted into using the "use_insertmanyvalues" feature, which implements deterministic ordering using client side sentinel columns only by default. The "insertmanyvalues" feature also features alternate forms that can use server-generated PK values as "sentinels", but those are only used if the :attr:`.Dialect.insertmanyvalues_implicit_sentinel` bitflag enables those alternate SQL forms, which are disabled by default. If the dialect in use hasn't opted into that, then this attribute is False, unless the dialect in question overrides this and provides some other implementation (such as the Oracle Database dialects). r� r� r� r� r� �4insert_executemany_returning_sort_by_parameter_order� s zCDefaultDialect.insert_executemany_returning_sort_by_parameter_orderr0 ��returnc C s" | j d u r t�d| � d���| j S )N�Dialect z\ does not have a Python DBAPI established and cannot be used for actual database interaction)ri r! �InvalidRequestErrorr� r� r� r� � loaded_dbapi� s �zDefaultDialect.loaded_dbapic C s | j tjju S r� )rx r rw Z RENDER_CASTSr� r� r� r� �_bind_typing_render_casts� s z(DefaultDialect._bind_typing_render_castsr �None)�argr� c C s$ t |t�s t�dtt|�f ��d S )Nz�The argument passed to Dialect.has_table() should be a %s, got %s. Additionally, the Dialect.has_table() method is for internal dialect use only; please use ``inspect(some_engine).has_table(<tablename>>)`` for public API use.)� isinstancer r! ru �type)r� r� r� r� r� � _ensure_has_table_connection� s ��z+DefaultDialect._ensure_has_table_connectionc C s: | j j�dd �}|d u r2tjd| j| jf dd� t|�S )N�supports_statement_cachea� Dialect %s:%s will not make use of SQL compilation caching as it does not set the 'supports_statement_cache' attribute to ``True``. This can have significant performance implications including some performance degradations in comparison to prior SQLAlchemy versions. Dialect maintainers should seek to set this attribute to True after appropriate development and testing for SQLAlchemy 1.4 caching support. Alternatively, this attribute may be set to False which will disable this warning.Zcprf)�code)� __class__�__dict__�getr# �warn�name�driverr_ )r� Zsscr� r� r� �_supports_statement_cache� s � �z(DefaultDialect._supports_statement_cachec C s t �� S r� )�weakref�WeakKeyDictionaryr� r� r� r� � _type_memos� s zDefaultDialect._type_memosc C s | j d | j S )N�+)r� r� r� r� r� r� �dialect_description� s z"DefaultDialect.dialect_descriptionc C s | j S )z�True if this dialect supports sane rowcount even if RETURNING is in use. For dialects that don't support RETURNING, this is synonymous with ``supports_sane_rowcount``. )�supports_sane_rowcountr� r� r� r� � supports_sane_rowcount_returning� s z/DefaultDialect.supports_sane_rowcount_returningr? z Type[Pool])�urlr� c C s t | dtj�S )NZ poolclass)rv r" Z QueuePool)�clsr� r� r� r� �get_pool_class� s z DefaultDialect.get_pool_classc C s | � |�S r� )r� )r� r� r� r� r� �get_dialect_pool_class� s z%DefaultDialect.get_dialect_pool_classc C sB d� | j�d�dd� �}zt|d � W n ty< Y n0 d S )N�.r ���z .provision)�join� __module__�split� __import__� ImportError)r� �packager� r� r� �load_provisioning� s z DefaultDialect.load_provisioningzOptional[_ListenerFnType]c s" � j d ur� fdd�}|S d S d S )Nc s � � | � j� d S r� )� _assert_and_set_isolation_levelr} )� dbapi_connZconn_recr� r� r� �builtin_connect s �z:DefaultDialect._builtin_onconnect.<locals>.builtin_connect)r} )r� r� r� r� r� �_builtin_onconnect� s z!DefaultDialect._builtin_onconnect)� connectionr� c C s� z| � |�| _W n ty( d | _Y n0 z| �|�| _W n tyR d | _Y n0 z| �|jj�| _W n ty� d | _Y n0 | j s�| � |�}|r�|| _ | j r�| j | j kr�t �d| j | j f ��d S )NzQLabel length of %d is greater than this dialect's maximum identifier length of %d)Z_get_server_version_info�server_version_info�NotImplementedErrorZ_get_default_schema_namere �get_default_isolation_levelr� �dbapi_connection�default_isolation_levelrY � _check_max_identifier_lengthrl rm r! ru )r� r� Zmax_ident_lengthr� r� r� � initialize s> � � � � � ��zDefaultDialect.initializez Optional[Callable[[Any], Any]]c C s d S r� r� r� r� r� r� � on_connect- s zDefaultDialect.on_connectc C s dS )z�Perform a connection / server version specific check to determine the max_identifier_length. If the dialect's class level max_identifier_length should be used, can return None. .. versionadded:: 1.3.9 Nr� �r� r� r� r� r� r� 1 s z+DefaultDialect._check_max_identifier_lengthc C s | � |�S )a� Given a DBAPI connection, return its isolation level, or a default isolation level if one cannot be retrieved. May be overridden by subclasses in order to provide a "fallback" isolation level for databases that cannot reliably retrieve the actual isolation level. By default, calls the :meth:`_engine.Interfaces.get_isolation_level` method, propagating any exceptions raised. .. versionadded:: 1.3.22 )Zget_isolation_level�r� r� r� r� r� r� = s z*DefaultDialect.get_default_isolation_levelc C s t �|| j�S )a) Provide a database-specific :class:`.TypeEngine` object, given the generic object which comes from the types module. This method looks for a dictionary called ``colspecs`` as a class or instance-level variable, and passes on to :func:`_types.adapt_type`. )r' Z adapt_typer\ )r� Ztypeobjr� r� r� �type_descriptorM s z DefaultDialect.type_descriptorc K sP | j ||fd|i|��s dS | j||fd|i|��D ]}|d |kr4 dS q4dS )N�schemaFr� T)Z has_table� get_indexes)r� r� Z table_nameZ index_namer� �kw�idxr� r� r� � has_indexX s ��� zDefaultDialect.has_index�str)r� � schema_namer� r� c K s || j |fi |��v S r� )Zget_schema_names)r� r� r� r� r� r� r� � has_schemac s zDefaultDialect.has_schema)�identr� c C s& t |�| jkr"t�d|| jf ��d S )Nz7Identifier '%s' exceeds maximum length of %d characters)�lenrl r! ZIdentifierError)r� r� r� r� r� �validate_identifierh s ��z"DefaultDialect.validate_identifierr< )�cargs�cparamsr� c O s | j j|i |��S r� )r� �connect)r� r� r� r� r� r� r� o s zDefaultDialect.connectr; c C s |� � }|�|j� g |fS r� )Ztranslate_connect_args�update�query)r� r� �optsr� r� r� �create_connect_argss s z"DefaultDialect.create_connect_argsr1 )�enginer� r� c sJ t �j����}|rFt��fdd�|D ��� t�|d�� �fdd��}d S )Nc 3 s | ]}|� | fV qd S r� r� ��.0r� �r� r� r� � <genexpr>� s z>DefaultDialect.set_engine_execution_options.<locals>.<genexpr>Zengine_connectc s �� | � � d S r� )� _set_connection_characteristics)r� )r r� r� r� � set_connection_characteristics� s �zSDefaultDialect.set_engine_execution_options.<locals>.set_connection_characteristics)�set�connection_characteristics� intersectionr# � immutabledictr Z listens_for)r� r� r� �supported_namesr� r� )r r� r� r� � set_engine_execution_optionsy s �� z+DefaultDialect.set_engine_execution_options)r� r� r� c s< t | j��� �}|r8t�� fdd�|D ��}| �||� d S )Nc 3 s | ]}|� | fV qd S r� r� r� r� r� r� r� � s zBDefaultDialect.set_connection_execution_options.<locals>.<genexpr>)r� r� r� r# r� r� )r� r� r� r� r r� r� r� � set_connection_execution_options� s ��z/DefaultDialect.set_connection_execution_optionsc s� � fdd�|� � D �}|�� rNdd� |D �}|rNt�dd�dd� |D �� ��|jj}|D ]\}}}|�� |||� qZ|jjj � t � � j |�� d S )Nc s g | ]\}}|� j | |f�qS r� )r� )r� r� �valuer� r� r� � <listcomp>� s �zBDefaultDialect._set_connection_characteristics.<locals>.<listcomp>c S s g | ]\}}}|j r||f�qS r� )Z transactional)r� r� �obj�_r� r� r� r� � s �z�This connection has already initialized a SQLAlchemy Transaction() object via begin() or autobegin; %s may not be altered unless rollback() or commit() is called first.�, c s s | ]\}}|V qd S r� r� )r� r� r� r� r� r� r� � � zADefaultDialect._set_connection_characteristics.<locals>.<genexpr>)�itemsZin_transactionr! r� r� r� r� Z set_connection_characteristicZ_connection_recordZfinalize_callback�append� functools�partial�_reset_characteristics) r� r� r Zcharacteristic_valuesZ trans_objsr� r� �characteristicr� r� r� r� r� � s* ����� �z.DefaultDialect._set_connection_characteristicsc C s$ |D ]}| j | }|�| |� qd S r� )r� Zreset_characteristic)r� r r� Zcharacteristic_namer� r� r� r� r� � s �z%DefaultDialect._reset_characteristicsc C s d S r� r� �r� r� r� r� r� �do_begin� s zDefaultDialect.do_beginc C s |� � d S r� )�rollbackr� r� r� r� � do_rollback� s zDefaultDialect.do_rollbackc C s |� � d S r� )�commitr� r� r� r� � do_commit� s zDefaultDialect.do_commitc C s | � |� d S r� )�do_closer� r� r� r� � do_terminate� s zDefaultDialect.do_terminatec C s |� � d S r� )�closer� r� r� r� r� � s zDefaultDialect.do_closec C s t t�d�j| d��S )Nr ��dialect)r� r& �select�compiler� r� r� r� � _dialect_specific_select_one� s z+DefaultDialect._dialect_specific_select_one)r� r� c C s� z | � |�W S | jjy� } zz| �||d �}| jrzztj|| |ddd� W n, tjyx } z|j }W Y d }~n d }~0 0 |r�W Y d }~dS � W Y d }~n d }~0 0 d S )NFT)� is_disconnectZ invalidate_pool_on_disconnectZ is_pre_ping) �do_pingr� �Errorr � _has_eventsr Z$_handle_dbapi_exception_noconnectionr! ZStatementErrorZconnection_invalidated)r� r� �errr Znew_errr� r� r� �_do_ping_w_event� s$ � z DefaultDialect._do_ping_w_eventc C s0 |� � }z|�| j� W |�� n |�� 0 dS )NT)r �executer� r� )r� r� r r� r� r� r � s zDefaultDialect.do_pingc C s dt �ddd � S )z�Create a random two-phase transaction ID. This id will be passed to do_begin_twophase(), do_rollback_twophase(), do_commit_twophase(). Its format is unspecified. z _sa_%032xr r � )�random�randintr� r� r� r� � create_xid� s zDefaultDialect.create_xidc C s |� t�|�� d S r� )r r& ZSavepointClause�r� r� r� r� r� r� � do_savepoint� s zDefaultDialect.do_savepointc C s |� t�|�� d S r� )r r& ZRollbackToSavepointClauser r� r� r� �do_rollback_to_savepoint� s z'DefaultDialect.do_rollback_to_savepointc C s |� t�|�� d S r� )r r& ZReleaseSavepointClauser r� r� r� �do_release_savepoint� s z#DefaultDialect.do_release_savepointc # s� t t|�}t t|j�}d� d �d}|j} |j} | d us:J �t|j�} |j� d�j �} |j rj|j� di �} nd } | r�g }||_ | j }nd}d }|�||| || || �D �]}|V | r�z|�|�}W nF t�y } z,|j|t�|j�|jd |dd� W Y d }~n d }~0 0 |d u�sJ �| j�r�|j�s�| jdk}| j�r\|�rBJ �|�t|t� d�d �� q�| j �shJ �| j �stJ �| j�|�s�|�r��fd d �t | j |j � d � �D �� n | j d j!�"�|j d d ��d}|�r� �fd d�|D ��n(��r�fdd�|D ��ndd� |D ��t#��t#|j$�k�rJt%�&dt#|j$�� dt#��� d���z�fdd �|j'D �}W n@ t(�y� } z&t%�&d|j)d �d��|�W Y d }~n d }~0 0 |�|� q�|�|� q�d S )Nr� Frd �schema_translate_mapT)Z is_sub_execr r� )�keyc s" g | ]\}}|j �� |d ��qS )r )r� �_cached_result_processor)r� �colZ cursor_descr� r� r� r� ] s ��zDDefaultDialect._deliver_insertmanyvalues_batches.<locals>.<listcomp>r c s0 i | ](}t d d� t|� d� � �D ��|�qS )c s s" | ]\}}|r||�n|V qd S r� r� )r� �val�procr� r� r� r� t s �zNDefaultDialect._deliver_insertmanyvalues_batches.<locals>.<dictcomp>.<genexpr>N)�tuple�zip�r� �row)�_composite_sentinel_proc�_nscr� r� � <dictcomp>s s ���zDDefaultDialect._deliver_insertmanyvalues_batches.<locals>.<dictcomp>c s i | ]}� |d �|�qS �r� r� r )�_scalar_sentinel_procr� r� r } s c S s i | ]}|d |�qS r r� r r� r� r� r � r� zASentinel-keyed result set did not produce correct number of rows z ; produced zP. Please ensure the sentinel column is fully unique and populated in all cases.c s g | ] }� | �qS r� r� )r� Z sentinel_keys)�rows_by_sentinelr� r� r� � s �zACan't match sentinel values in result set to parameter sets; key aT was not found. There may be a mismatch between the datatype passed to the DBAPI driver vs. that which it returns in a result row. Ensure the given Python value matches the expected result type *exactly*, taking care to not rely upon implicit conversions which may occur such as when using strings in place of UUID or integer values, etc. )*r �DefaultExecutionContextr, �compiled�compiled_parameters�_insertmanyvaluesr_ �effective_returning�execution_optionsr� rd r �_insertmanyvalues_rows�sort_by_parameter_order�!_deliver_insertmanyvalues_batches�fetchall_for_returning� BaseExceptionZ_handle_dbapi_exception�sql_utilZ_long_statementZreplaced_statementZreplaced_parameters�num_sentinel_columnsZ is_downgradedZimplicit_sentinel�extend�sorted�operator� itemgetterZsentinel_param_keys�sentinel_columnsr � descriptionr� r r� �batchr! r� Zsentinel_values�KeyError�args)r� r� r � statement� parametersZgeneric_setinputsizes�contextr Z_sentinel_proc_initializedr! �imvZ is_returningZ batch_sizer �resultr& Z imv_batch�rows�beZcomposite_sentinelZ ordered_rowsZker� )r r r r r� r� r' � s� � ��� � � �� �� � ���� � �� � z0DefaultDialect._deliver_insertmanyvalues_batchesc C s |� ||� d S r� )� executemany�r� r r5 r6 r7 r� r� r� �do_executemany� s z DefaultDialect.do_executemanyc C s |� ||� d S r� �r r= r� r� r� � do_execute� s zDefaultDialect.do_executec C s |� |� d S r� r? )r� r r5 r7 r� r� r� �do_execute_no_params� s z#DefaultDialect.do_execute_no_params� ExceptionzCUnion[pool.PoolProxiedConnection, interfaces.DBAPIConnection, None]z Optional[interfaces.DBAPICursor])�er� r r� c C s dS )NFr� )r� rC r� r r� r� r� r � s z DefaultDialect.is_disconnectc C sn zt | �|��}W n ty& Y d S 0 dd� |D �}||krbtd| j�dtt|��|��� ���t|�S d S )Nc S s g | ]}|� d d��� �qS )r� � )�replace�upper)r� �levelr� r� r� r� � s z@DefaultDialect._gen_allowed_isolation_levels.<locals>.<listcomp>r� zi get_isolation_level_values() method should return names as UPPERCASE using spaces, not underscores; got ) �listZget_isolation_level_valuesr� � ValueErrorr� r- r� � differencer )r� r� Z raw_levelsZnormalized_levelsr� r� r� � _gen_allowed_isolation_levels� s � ��z,DefaultDialect._gen_allowed_isolation_levelsc C sZ |� dd��� }| �|�}|rJ||vrJt�d|�d| j�dd�|�� ���| �||� d S )Nr� rD zInvalid value z1 for isolation_level. Valid isolation levels for z are r� )rE rF rK r! ru r� r� Zset_isolation_level)r� r� rG Z_allowed_isolation_levelsr� r� r� r� � s ������z.DefaultDialect._assert_and_set_isolation_levelc C sT | j d ur4| j dks$| j | jks$J �| �|| j � n | jd usBJ �| �|| j� d S )NZ AUTOCOMMIT)r} r� r� r� r� r� r� �reset_isolation_level� s �����z$DefaultDialect.reset_isolation_levelc C s\ |d u r d S |� � }|�� }||kr(|S ||kr@| j�|�s@|S ||krTt|dd�S |S d S )NT)�quote)�lowerrF r| �_requires_quotesr- �r� r� Z name_lowerZ name_upperr� r� r� �normalize_name� s �� z DefaultDialect.normalize_namec C sD |d u r d S |� � }|�� }||kr(|S ||kr@| j�|�s@|}|S r� )rN rF r| rO rP r� r� r� �denormalize_name s ��z DefaultDialect.denormalize_namec C s |S r� r� r� r� r� r� �get_driver_connection s z$DefaultDialect.get_driver_connectionc C s t t| �|�jt t|�juS r� )rv r� �__code__rN )r� �methodr� r� r� �_overrides_default" s ��z!DefaultDialect._overrides_defaultc k s� g }g } t j|v r*|�| j� | �| j� t j|v rL|�| j� | �| j� t j|v rb|�| j � |� di �} |r�|t j u r�|t j u r�|} ntg } d|i|�} g } t j |v r�| �|� t j|v r�| �| � | D ]2}z| �||fi | ��� W q� ty� Y q�0 q�|�rt|�}| D ]�}|�r&||v �r||f}z ||||fd|i|��fV W nN tj�y� } z || v�rt|| |< W Y d }~n d }~0 tj�y� Y n0 �qd S )N� unreflectabler� )r ZTABLEr� Zget_table_namesZget_temp_table_namesZVIEWZget_view_namesZget_temp_view_namesZMATERIALIZED_VIEWZget_materialized_view_names�popr �ANYr^ r, � TEMPORARYr� r� r! ZUnreflectableTableErrorZNoSuchTableError)r� Zsingle_tbl_methodr� �kindr� Z filter_namesZscoper� Z names_fnsZtemp_names_fnsrW �namesZname_kw�fns�fn�tabler r r� r� r� �_default_multi_reflect( sd ��� ���� z%DefaultDialect._default_multi_reflectc K s | j | j|fi |��S r� )r` Zget_table_options�r� r� r� r� r� r� �get_multi_table_optionsq s ��z&DefaultDialect.get_multi_table_optionsc K s | j | j|fi |��S r� )r` Z get_columnsra r� r� r� �get_multi_columnsv s z DefaultDialect.get_multi_columnsc K s | j | j|fi |��S r� )r` Zget_pk_constraintra r� r� r� �get_multi_pk_constrainty s ��z&DefaultDialect.get_multi_pk_constraintc K s | j | j|fi |��S r� )r` Zget_foreign_keysra r� r� r� �get_multi_foreign_keys~ s ��z%DefaultDialect.get_multi_foreign_keysc K s | j | j|fi |��S r� )r` r� ra r� r� r� �get_multi_indexes� s z DefaultDialect.get_multi_indexesc K s | j | j|fi |��S r� )r` Zget_unique_constraintsra r� r� r� � get_multi_unique_constraints� s ��z+DefaultDialect.get_multi_unique_constraintsc K s | j | j|fi |��S r� )r` Zget_check_constraintsra r� r� r� �get_multi_check_constraints� s ��z*DefaultDialect.get_multi_check_constraintsc K s | j | j|fi |��S r� )r` Zget_table_commentra r� r� r� �get_multi_table_comment� s ��z&DefaultDialect.get_multi_table_comment)N)N)N)N)��__name__r� � __qualname__�__doc__r$ r, �statement_compilerr* � ddl_compilerr~ r �IdentifierPreparerr{ Zsupports_alterZsupports_commentsZ supports_constraint_commentsZinline_commentsr� Zdiv_is_floordivr rw �NONErx rO �__annotations__rP Zdefault_sequence_baser �execute_sequence_formatZsupports_schemasZsupports_views�supports_sequences�sequences_optional�"preexecute_autoincrement_sequences�supports_identity_columns�postfetch_lastrowidZ favor_returning_over_lastrowidZ#insert_null_pk_still_autoincrementsr� r� Zupdate_returning_multifromZdelete_returning_multifromr� Zcte_follows_insertZsupports_native_enumrk Zsupports_native_uuidZreturns_native_bytesZ#non_native_boolean_check_constraint� supports_simple_order_by_labelZtuple_in_valuesr# r� r Z IsolationLevelCharacteristicZLoggingTokenCharacteristicr� ZasintZ bool_or_strZasboolrV Zsupports_native_decimalr� rl rY rQ rZ r[ r� � supports_sane_multi_rowcountr\ rz Zsupports_default_valuesZsupports_default_metavalueZdefault_metavalue_tokenZsupports_empty_insert�supports_multivalues_insertr` ra r+ Z NOT_SUPPORTEDrb rd Z insertmanyvalues_max_parametersZsupports_is_distinct_fromrt rg Zsupports_for_update_ofr� re Zrequires_name_normalize�is_asyncZ has_terminateZ$_legacy_binary_type_literal_encodingZdeprecated_paramsr) r� rc Z NO_LINTINGr� �property� deprecatedr� �memoized_propertyr� r� � update_executemany_returning� delete_executemany_returningr� r� r� r� r� r� r� � classmethodr� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r r r r r r r' r> r@ rA r Zmemoized_instancemethodrK r� rL rQ rR rS rV r` rb rc rd re rf rg rh ri r� r� r� r� rN v sl ���� � ��(R� $ - IrN c @ sP e Zd ZejZejZejZ ej Z dZ dZ dZdZdZdZdZdZdZdZdZdS )�StrCompileDialectTFN)rj r� rk r$ ZStrSQLCompilerrm r* rn ZStrSQLTypeCompilerr ro r{ r� r� r� r� rv rs rt ru rk rz rx r� r� r� r� r� � s r� c @ sV e Zd ZU dZdZdZdZdZdZe j Z de d< dZ de d< dZde d< dZd e d < ejZd e d < ejZdZd e d< dZdZdZdZdZdZ de d< dZ de d< e� � Z de d< e Z!de d< de d< de d< de d < d e d < d e d < d!e d"< d#e d$< e"d%ej�Z#dZ$d&e d'< d(Z%d)e d*< e&dddd d+d,d-�d.d/��Z'e&e(j)fdddd d0d1d2d#d3d,d4� d5d6��Z*e&dddd dd!d,d7�d8d9��Z+e&dddd d,d:�d;d<��Z,dd=�d>d?�Z-e.d@dA� �Z/ej0dBdC� �Z1ej0dDdE� �Z2ej0dFd=�dGdH��Z3ej0dFd=�dIdJ��Z4ej0dKdL� �Z5d�ddMdNdOdP�dQdR�Z6ej0dSdT� �Z7dUdV� Z8d d=�dWdX�Z9dYdZ� Z:d d=�d[d\�Z;d d=�d]d^�Z<d_d`� Z=dadb� Z>dcdd� Z?dedf� Z@dgdh� ZAdidj� ZBejCd)d=�dkdl��ZDe.dmdn� �ZEdodp� ZFdqdr� ZGdsdt� ZHdudv� ZIdwdx� ZJej0dydz� �ZKd{d|� ZLd}d~� ZMdd�� ZNd�d�� ZOd�d=�d�d��ZPd�d�� ZQd�d�� ZRdZSd�e d�< d�d�d��ZTd�d�� ZUd�d�� ZVd�d�� ZWdS )�r Fr � execute_styleNzOptional[Compiled]r zAOptional[Tuple[List[ResultColumnsEntry], bool, bool, bool, bool]]�result_column_structz Optional[Sequence[Row[Any]]]�returned_default_rowsr8 r$ zOptional[Executable]�invoked_statementrX � _rowcountz Optional[Callable[[str], str]]�_translate_colnamezMapping[str, List[str]]�_expanded_parametersr �root_connectionrB �_dbapi_connectionr r� r� �unicode_statementr r z%List[_MutableCoreSingleExecuteParams]r! r6 r6 z&Optional[Sequence[BindParameter[Any]]]�extracted_parametersrU z Optional[List[Tuple[Any, ...]]]r% r rc �_num_sentinel_colsr* r )r� r� r� r$ � compiled_ddlr� c C s� | � | �}||_||_|j|_| |_}d|_||_t|�|_|j rh|j� di �}|j j } | |j|�|_|j|_ |�� |_g |_|jr�|�� g|_n |jg|_|S )zKInitialize execution context for an ExecutableDDLElement construct.Tr )�__new__r� r� r� r �isddlr$ r� r� r r� r{ �_render_schema_translatesr5 � create_cursorr r! ry rr r6 �_empty_dict_params) r� r� r� r� r$ r� r� r r �rstr� r� r� � _init_ddl� s. �� z!DefaultExecutionContext._init_ddlr, r3 rC r ) r� r� r� r$ r r6 r� r� � cache_hitr� c s� | � | �} || _|| _|j| _�| _|| _� | _| | _|| _� j � j � j � j � j f| _� j | _} � j | _} � j | _} � j| _| s�| s�| �rȈ jj}tr�t|t�s�J �d| _t|j� | _ }t� j � | _ }|r�|j r�d| _ |r�|r�J �|s�|�rȈ j!�r�| �r&| jj"�s&t#�$d| jj%� d���n�| �rV|j&�rV| jj'�sVt#�$d| jj%� d���nr| �rz| jj(�rz� j)�szt#�$d��nN| �r�| jj*�s�t#�$d| jj%� d���n&| �r�| jj+�s�t#�$d| jj%� d���|�s� j,�dd �g| _-nd� �fd d �t.|�D �| _-t/|�d k�rF| j�r>� j)�r>t0j1| _2� j)}|j3d u�rF|j4| _5nt0j6| _2� j7| _8| �9� | _:| jj;�sl| jj<�rt| �=� � j>}|�� j?�s�� j@�r�| jA�r�t#�$d��� �B| j-d �}|j| _8|jC| _DtE|����F|jG� |jH}n� jI�r�| jjH}nd }� jJ�r | j�Kdi �}� jLjM}|| j8|�| _8| j8| _� jI�rzg }|d u�s@J �| j-D ]*���fdd �|D �}|�N|�O|�� �qF|| _PnZg }� jQ�| j-D ]B���r����fdd��D �}n��fdd��D �}|�N|� �q�|| _P| S )z6Initialize execution context for a Compiled construct.Tr� z] with current server capabilities does not support INSERT..RETURNING when executemany is usedz} with current server capabilities does not support INSERT..RETURNING with deterministic row ordering when executemany is usedznStatement does not have "insertmanyvalues" enabled, can't use INSERT..RETURNING with executemany in this case.z] with current server capabilities does not support UPDATE..RETURNING when executemany is usedz] with current server capabilities does not support DELETE..RETURNING when executemany is usedF)r� � escape_namesc s" g | ]\}}� j |d |�d��qS )F)r� Z _group_numberr� )�construct_params)r� �grp�m)r r� r� r� r� } s ��z:DefaultExecutionContext._init_compiled.<locals>.<listcomp>r NzL'literal_execute' or 'expanding' parameters can't be used with executemany()r r c s, g | ]$}|�v r �| � | �n� | �qS r� r� �r� r ��compiled_params�flattened_processorsr� r� r� � s ��c s6 i | ].}�� ||�|�v r*�| � | �n� | �qS r� )r� r� )r� � escaped_namesr� r� r� r � s � �z:DefaultExecutionContext._init_compiled.<locals>.<dictcomp>c s. i | ]&}||�v r"�| � | �n� | �qS r� r� r� r� r� r� r � s ��)Rr� r� r� r� r� r� r r� r$ Z_result_columnsZ_ordered_columnsZ_textual_ordered_columnsZ_ad_hoc_textualZ_loose_column_name_matchingr� �isinsert�isupdate�isdeleteZ isplaintext�is_text� compile_stater5 r r� rH �is_crudr_ Z _returning�_is_explicit_returningrj �_is_implicit_returningZ_supplemental_returning�_is_supplemental_returningZfor_executemanyr� r! r� r� Z_sort_by_parameter_orderr� r` r" r r� r� r! � enumerater� r �INSERTMANYVALUESr� r0 r+ r� � EXECUTEMANY�stringr� r� r �insert_prefetch�update_prefetch�_process_execute_defaults�_bind_processors�literal_execute_paramsZpost_compile_paramsr< Z#_process_parameters_for_postcompileZparameter_expansionr� �dictr� � processors� positiontupry r r� r{ r� r� rr r6 �escaped_bind_names)r� r� r� r� r$ r r6 r� r� r� r� �ii�iuZid_Z dml_statementZierZiirr8 r� Zexpanded_stater� r r� Zcore_positional_parametersZl_paramZcore_dict_parametersZd_paramr� )r r� r� r� r� r� �_init_compiled s � � ������������� � ��� �� �� � � z&DefaultExecutionContext._init_compiled)r� r� r� r$ r5 r6 r� c s� | � | �}||_||_|j|_d|_||_|sP|jjrD� �� g|_q�|j g|_nBt |d � j�rh||_n*t |d t �r~||_n� fdd�|D �|_t |�dkr�t j|_| |_|_|�� |_|S )z8Initialize execution context for a string SQL statement.Tr c s g | ]}� � |��qS r� )rr )r� �pr� r� r� r� s z;DefaultExecutionContext._init_statement.<locals>.<listcomp>r )r� r� r� r� r� r$ ry rr r6 r� r� r� r� r r� r� r5 r� r� r )r� r� r� r� r$ r5 r6 r� r� r� r� �_init_statement� s, � z'DefaultExecutionContext._init_statement)r� r� r� r$ r� c C s2 | � | �}||_||_|j|_||_|�� |_|S )z;Initialize execution context for a ColumnDefault construct.)r� r� r� r� r$ r� r )r� r� r� r� r$ r� r� r� r� � _init_default& s z%DefaultExecutionContext._init_defaultr� c C s� | j d u rdS t� }| j}| j j}|d us.J �|tu rDd|| f S |tu rZd|| f S |tu rpd|| f S |tu r�d| jv r�d| jd || f S d|| f S n&|t u r�d| j j | j j || f S d S d S ) Nzraw sqlz no key %.5fszcached since %.4gs agozgenerated in %.5fsZ_cache_disable_reasonz caching disabled (%s) %.5fs zcaching disabled %.5fsz,dialect %s+%s does not support caching %.5fs�unknown) r r r� Z _gen_time� NO_CACHE_KEY� CACHE_HIT� CACHE_MISS�CACHING_DISABLEDr$ �NO_DIALECT_SUPPORTr� r� r� )r� �now�chZgen_timer� r� r� �_get_cache_stats: s4 ��z(DefaultExecutionContext._get_cache_statsc C s | j tjtjfv S r� )r� r r� r� r� r� r� r� r< \ s �z#DefaultExecutionContext.executemanyc C s8 | j r| j jS d| jv r,| jj�| jd �S | jjS d S )Nr )r r{ r$ r� r| Z_with_schema_translater� r� r� r� r| c s �z+DefaultExecutionContext.identifier_preparerc C s | j jS r� )r� r� r� r� r� r� r� n s z DefaultExecutionContext.enginez Optional[Sequence[Column[Any]]]c C s t rt| jt�sJ �| jjS r� )r r� r r, � postfetchr� r� r� r� �postfetch_colsr s z&DefaultExecutionContext.postfetch_colsc C s8 t rt| jt�sJ �| jr"| jjS | jr0| jjS dS d S )Nr� )r r� r r, r� r� r� r� r� r� r� r� � prefetch_colsx s z%DefaultExecutionContext.prefetch_colsc C s | j �dd�S )N� no_parametersF)r$ r� r� r� r� r� r� � s z%DefaultExecutionContext.no_parameterszOptional[TypeEngine[Any]]z#Optional[_DBAPISingleExecuteParams]r )�stmt�type_r6 r� c C s� | j }d| jv r0| j�di �}| jj}|||�}|sL| jjrH| j�� }ni }|j| j ||| d� | j � � }|dur||d }nd}|dur�|� | j| j j d d �} | r�| |�S |S )a Execute a string statement on the current cursor, returning a scalar result. Used to fire off sequences, default phrases, and "select lastrowid" types of statements individually or in the context of a parent INSERT or UPDATE statement. r )r7 Nr r ) r� r$ r� r| r� r� ry rr Z_cursor_executer Zfetchoner r1 ) r� r� r� r6 �connr r� r �rr r� r� r� �_execute_scalar� s. � �z'DefaultExecutionContext._execute_scalarc C s | j S r� )r� r� r� r� r� r� � s z"DefaultExecutionContext.connectionc C sv | j js dS | j jrd| j�dd�o`| jr8t| jjtj �p`| j sPt| jjtj �o`| j o`t � | j �}n| j�dd�}|S )NF�stream_resultsT)r� rt rg r$ r� r r� r5 r& Z SelectableZ TextClauser� �SERVER_SIDE_CURSOR_RE�match)r� Zuse_server_sider� r� r� �_use_server_side_cursor� s, �� ��� ��z/DefaultExecutionContext._use_server_side_cursorc C sF | j jr4| j�dd�s&| j jr4| �� r4d| _| �� S d| _| �� S d S )Nr� FT) r� rt r$ r� rg r� �_is_server_side�create_server_side_cursor�create_default_cursorr� r� r� r� r� � s � ��� z%DefaultExecutionContext.create_cursorc C s |� � S r� )Zfetchall)r� r r� r� r� r( � s z.DefaultExecutionContext.fetchall_for_returningc C s | j �� S r� )r� r r� r� r� r� r� � s z-DefaultExecutionContext.create_default_cursorc C s t � �d S r� �r� r� r� r� r� r� � s z1DefaultExecutionContext.create_server_side_cursorc C s d S r� r� r� r� r� r� �pre_exec� s z DefaultExecutionContext.pre_execc C s t d��d S )Nz,This dialect does not support OUT parametersr� )r� r\ r� r� r� �get_out_parameter_values� s �z0DefaultExecutionContext.get_out_parameter_valuesc C s d S r� r� r� r� r� r� � post_exec� s z!DefaultExecutionContext.post_execc C s |� | j|�S )z�Return a 'result processor' for a given type as present in cursor.description. This has a default implementation that dialects can override for context-sensitive result type handling. )r r� )r� r� ZcolnameZcoltyper� r� r� �get_result_processor� s z,DefaultExecutionContext.get_result_processorc C s | j jS )a return self.cursor.lastrowid, or equivalent, after an INSERT. This may involve calling special cursor functions, issuing a new SELECT on the cursor (or a new one), or returning a stored value that was calculated within post_exec(). This function will only be called for dialects which support "implicit" primary key generation, keep preexecute_autoincrement_sequences set to False, and when no explicit id value was bound to the statement. The function is called once for an INSERT statement that would need to return the last inserted primary key for those dialects that make use of the lastrowid concept. In these cases, it is called directly after :meth:`.ExecutionContext.post_exec`. )r � lastrowidr� r� r� r� � get_lastrowid s z%DefaultExecutionContext.get_lastrowidc C s d S r� r� )r� rC r� r� r� �handle_dbapi_exception s z.DefaultExecutionContext.handle_dbapi_exceptionc C s | j d ur| j S | jjS d S r� )r� r �rowcountr� r� r� r� r� s z DefaultExecutionContext.rowcountc C s | j d uS r� )r� r� r� r� r� � _has_rowcount# s z%DefaultExecutionContext._has_rowcountc C s | j jS r� )r� r� r� r� r� r� r� ' s z.DefaultExecutionContext.supports_sane_rowcountc C s | j jS r� )r� ry r� r� r� r� ry * s z4DefaultExecutionContext.supports_sane_multi_rowcountc C s� | j }| jd u r&|�dd�r&| jj| _| js2| jr@| �� }d}nl|�dd �}| jp\|�dd�}| j }|r�|t j u r�t � | j| j �}|j p�| jj}|d u r�t j}t �| ||�}| j}|r�| js�tt|�jr�| �|� |j| _|r�|�|�}|S )NZpreserve_rowcountF� yield_perr� )r$ r� r� r r� r� r� �_setup_dml_or_text_resultr� �cursor_fetch_strategy�_cursor�_DEFAULT_FETCH� BufferedRowCursorFetchStrategy� alternate_cursor_descriptionr1 Z_NO_CURSOR_DQL� CursorResultr r� r r, Zhas_out_parameters�_setup_out_parameters� _soft_closedr� )r� Zexec_optr9 Zyp�sr�strategy�cursor_descriptionr r� r� r� �_setup_result_proxy- s> ���� � z+DefaultExecutionContext._setup_result_proxyc C s� t t| j�}dd� |j�� D �}i }tdd� |D �| �dd� |D ���D ]P\}}|j}|�| j �}|� | j j �} |� | j | �} | d ur�| |�}|||j < qH||_d S )Nc S s g | ]\}}|j r||f�qS r� )Z isoutparam�r� �paramr� r� r� r� r� Z s �zADefaultExecutionContext._setup_out_parameters.<locals>.<listcomp>c S s g | ] \}}|�qS r� r� r� r� r� r� r� b r� c S s g | ] \}}|�qS r� r� r� r� r� r� r� d r� )r r, r � bind_namesr� r r� r� Z dialect_implr� Zget_dbapi_typer� �result_processorr �out_parameters) r� r9 r Zout_bindparamsr� � bindparam� raw_valuer� Z impl_typeZ dbapi_typer� r� r� r� r� W s* � �� � z-DefaultExecutionContext._setup_out_parametersc C s� t t| j�}| j}| jrP| jtju r@|jr@t j | j | j |j d�}|jrP| �� | _| jrp|t ju rpt �| j | j�}|t ju r�d }n|j p�| j j}|d u r�t j}n&| jr�| jtju s�J �|d| j � }t �| ||�}| j�r<| j�r*|�� }|| _| � ||�| _|j j �s J �| j �r |� |� n|�!� n| j"�s�|�!� n�| j�r�|�� }|�rX|| _t#|�| _$| j �rv|� |� n|�!� |j j �s�J �nP|j j �s�| j$d u �r�| j j%| _$|�!� n&| j&�s�| j'�r�| j$d u �r�| j j%| _$|S )N)Zinitial_bufferZalternate_descriptionr )(r r, r r� r� r� r r� r# r� Z FullyBufferedCursorFetchStrategyr r% r� rw � _setup_ins_pk_from_lastrowid�inserted_primary_key_rowsr� r� r� r$ Z_NO_CURSOR_DMLr1 r� r� r� �allr� �%_setup_ins_pk_from_implicit_returning� _metadataZ returns_rowsr� �_rewindZ _soft_closer� r� r� r� r� r� )r� r r� r� r9 r: r� r� r� r� s s~ ��� �� � �� � z1DefaultExecutionContext._setup_dml_or_text_resultc C s | � � S r� )�_setup_ins_pk_from_emptyr� r� r� r� r� � s z1DefaultExecutionContext.inserted_primary_key_rowsc C s( t t| j�j}| �� }||| jd �gS )Nr )r r, r �+_inserted_primary_key_from_lastrowid_getterr� r! )r� �getterr� r� r� r� r� � s �z4DefaultExecutionContext._setup_ins_pk_from_lastrowidc s" t t| j�j� � fdd�| jD �S )Nc s g | ]}� d |��qS r� r� )r� r� �r� r� r� r� � r� zDDefaultExecutionContext._setup_ins_pk_from_empty.<locals>.<listcomp>)r r, r r� r! r� r� r� r� r� � s �z0DefaultExecutionContext._setup_ins_pk_from_emptyc s4 |sg S t t| j�j� | j}� fdd�t||�D �S )Nc s g | ]\}}� ||��qS r� r� )r� r r� r� r� r� r� s zQDefaultExecutionContext._setup_ins_pk_from_implicit_returning.<locals>.<listcomp>)r r, r Z+_inserted_primary_key_from_returning_getterr! r )r� r9 r: r� r� r� r� r� � s � �z=DefaultExecutionContext._setup_ins_pk_from_implicit_returningc C s | j s | jo ttt| j�j�S r� )r� r� r_ r r, r r� r� r� r� r� �lastrow_has_defaults s �z,DefaultExecutionContext.lastrow_has_defaultsz0Optional[List[Tuple[str, Any, TypeEngine[Any]]]]c s� | j s | jrdS tt| j����� }|du r0dS | j}|jr^t|�}|j � || j | j | j | � �jrl�j�nd�|jr��fdd��jp�dD �}ndd� �j�� D �}g }|D ]�\}� � �jv r�q�|| jv �rFt� j��rt� jj��|� �|�� ���fdd�t| j| �D �� n.|�� d��|�� ��fdd�| j| D �� q�|�� d���du�rh��||�n|}|� |�� jf� q�|S ) a� Given a cursor and ClauseParameters, prepare arguments in order to call the appropriate style of ``setinputsizes()`` on the cursor, using DB-API types from the bind parameter's ``TypeEngine`` objects. This method only called by those dialects which set the :attr:`.Dialect.bind_typing` attribute to :attr:`.BindTyping.SETINPUTSIZES`. Python-oracledb and cx_Oracle are the only DBAPIs that requires setinputsizes(); pyodbc offers it as an option. Prior to SQLAlchemy 2.0, the setinputsizes() approach was also used for pg8000 and asyncpg, which has been changed to inline rendering of casts. Nc s g | ]}|� j | f�qS r� )Zbindsr� )r r� r� r� 8 s �zDDefaultExecutionContext._prepare_set_input_sizes.<locals>.<listcomp>r� c S s g | ]\}}||f�qS r� r� )r� r� r r� r� r� r� = s �c 3 sD | ]<\}}�d ur �� ||�n|�|� � jj|� fV qd S r� )r� r� �types)r� r� � paramname)r� �dbtypesr� �numr� r� r� K s �� �zCDefaultExecutionContext._prepare_set_input_sizes.<locals>.<genexpr>c 3 s. | ]&}�d ur�� ||�n|�� jfV qd S r� )r� r� )r� r )r� �dbtyper� r� r� r� [ s ���) r� r� r r, r Z_get_set_input_sizes_lookupr� r r� �dispatchZdo_setinputsizesr r5 r6 r� ry r� r� r� r� r� r( r� r� r r, r� r� r� )r� Z inputsizesr� r� Zgeneric_inputsizesr Z escaped_namer� )r� r r r r� r r� �_prepare_set_input_sizes s` � �� �� � �� �z0DefaultExecutionContext._prepare_set_input_sizesc C sF |j r| �||�S |jr(|| _|�| �S |jr<| �|||�S |jS d S r� )Z is_sequenceZ fire_sequence� is_callable�current_columnr� Zis_clause_element� _exec_default_clause_element)r� �columnrW r� r� r� r� � _exec_defaultv s z%DefaultExecutionContext._exec_defaultc s� |j st�|j|�}n|j}t�|�j| jd�}|�� � |j�|j rh| j� � �fdd�|j p^dD ��}n� �fdd�� D �}| j t |�||d�S )Nr� c s, g | ]$}|�v r �| � | �n� | �qS r� r� r� �r� r� r� r� r� � s ��zHDefaultExecutionContext._exec_default_clause_element.<locals>.<listcomp>r� c s. i | ]&}||�v r"�| � | �n� | �qS r� r� r� r r� r� r � s ��zHDefaultExecutionContext._exec_default_clause_element.<locals>.<dictcomp>)r6 )Z _arg_is_typedr& Z type_coercer� r� r� r� r� r� ry rr r� r� r� )r� r rW r� Z default_argr r6 r� r r� r � s$ �� � �z4DefaultExecutionContext._exec_default_clause_elementz"Optional[_CoreSingleExecuteParams]�current_parametersTc s� z| j �| j}W n ty, t�d��Y n0 |dus:J ��dusFJ �tdtt| j�j�}|dusfJ �|r�t � |�r�|j r�|j r�|j d � |jj�|j i}n|j�|j i}d� |jdus�J �|j�� }|�� �fdd�|D �� |S �S dS )ai Return a dictionary of parameters applied to the current row. This method can only be used in the context of a user-defined default generation function, e.g. as described at :ref:`context_default_functions`. When invoked, a dictionary is returned which includes entries for each column/value pair that is part of the INSERT or UPDATE statement. The keys of the dictionary will be the key value of each :class:`_schema.Column`, which is usually synonymous with the name. :param isolate_multiinsert_groups=True: indicates that multi-valued INSERT constructs created using :meth:`_expression.Insert.values` should be handled by returning only the subset of parameters that are local to the current column default invocation. When ``False``, the raw parameters of the statement are returned including the naming convention used in the case of multi-valued INSERT. .. versionadded:: 1.2 added :meth:`.DefaultExecutionContext.get_current_parameters` which provides more functionality over the existing :attr:`.DefaultExecutionContext.current_parameters` attribute. .. seealso:: :attr:`.DefaultExecutionContext.current_parameters` :ref:`context_default_functions` zdget_current_parameters() can only be invoked in the context of a Python side column default functionNrG r r c 3 s" | ]}|�d |� f fV qdS )z%s_m%dNr� r� ��indexr6 r� r� r� s zADefaultExecutionContext.get_current_parameters.<locals>.<genexpr>)r r �AttributeErrorr! r� r r, r r� r% r� Z_has_multi_parametersZ_is_multiparam_columnr �originalr Z_dict_parameters�keysr� )r� Zisolate_multiinsert_groupsr r� �dr r� r r� �get_current_parameters� s> ! � � ��� �z.DefaultExecutionContext.get_current_parametersc C s$ |j d u rd S | �||j |j�S d S r� )rW r r� �r� r r� r� r� �get_insert_default s z*DefaultExecutionContext.get_insert_defaultc C s$ |j d u rd S | �||j |j�S d S r� )Zonupdater r� r r� r� r� �get_update_default s z*DefaultExecutionContext.get_update_defaultc s� t t�j�}|j� d}|jr4� �fdd�|jD �}n"|jrR� �fdd�|jD �}ng }�jD ]x}|�_|D ]h\}}\}}} } } | r�|||< |d7 }qj|r�|||< qj| r�|�_|��||< qj| |�} | d urj| ||< qjq\�`d S )Nr c s g | ]}|� |�|j �jf�qS r� )Z_default_description_tupler �r� �c�Z key_getterr� r� r� r� s ��zEDefaultExecutionContext._process_execute_defaults.<locals>.<listcomp>c s g | ]}|� |�|j �jf�qS r� )Z_onupdate_description_tupler r r r� r� r� ' s ��r ) r r, r Z _within_exec_param_key_getterr� r� r! r r ) r� r Zsentinel_counterZ prefetch_recsr� r Z param_keyr� Z is_scalarr Z is_sentinel�fallbackr r� r r� r� s@ � � � z1DefaultExecutionContext._process_execute_defaults)N)T)Xrj r� rk r� r� r� r� r� r� r ZEXECUTEr� rq r r� r� r# � EMPTY_DICTr$ r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r r� r% r� r� r� r r� r� r� r� r� r| r< r~ r| r� r� r� r� r� r� r� r� r( r� r� r� r� r� r� r� r� Znon_memoized_propertyr� r� r� ry r� r� r� r� r� r� r� r� r r r r r r r r� r� r� r� r� r � s� � , �$ f )" �. * r k' Dr )rrl � __future__r r� r. r �re�timer �typingr r r r r r r r r r r r r r r r� � r r r� r �baser r r r r r Z reflectionr r r r! r" r# Zsqlr$ r% r& r' r* Z sql._typingr( Zsql.baser) Z sql.compilerr* r+ r, Z sql.elementsr- Z util.typingr. r/ r r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 r: r; r< r= r r> r� r? r@ rA rB rC rD rE rF Zsql.dmlrG rH rI Z sql.schemarJ Z sql.type_apirK rL rM r� �I�UNICODEr� rH r� r� r� r� r� rN r� r Zexecution_ctx_clsr� r� r� r� �<module> s� � ( ' sqlalchemy/engine/__pycache__/strategies.cpython-39.pyc 0000644 00000000774 15125143220 0017171 0 ustar 00 a ��Jh� � @ s. d Z ddlmZ ddlmZ G dd� d�ZdS )z3Deprecated mock engine strategy used by Alembic. � )� annotations� )�MockConnectionc @ s e Zd ZeZdS )�MockEngineStrategyN)�__name__� __module__� __qualname__r � r r �Q/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/engine/strategies.pyr s r N)�__doc__� __future__r Zmockr r r r r r �<module> s sqlalchemy/engine/__pycache__/interfaces.cpython-39.pyc 0000644 00000261664 15125143220 0017151 0 ustar 00 a ��Jh0� � @ s� d Z ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z ddlm Z ddlm Z dd lm Z dd lm Z dd lmZ dd lmZ dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z ddl m Z ddl m Z dd l m!Z! dd l"m#Z# dd l"m#Z# dd l"m$Z$ dd l"m$Z$ dd l m%Z% dd l&m'Z' dd!l(m)Z) dd"l(m*Z* dd#l(m+Z+ dd$l(m,Z, e�r�d%d&l-m.Z. d%d'l-m/Z/ d%d(l0m1Z1 d%d)l2m3Z3 dd*l m4Z4 dd+l m5Z5 dd,l6m7Z7 dd-l8m9Z9 dd.l"m:Z: dd/l"m;Z; dd0l"m<Z< dd1l"m=Z= dd2l"m>Z> dd3l"m?Z? dd4l@mAZA dd5l@mBZB dd6lCmDZD dd7lCmEZE dd8lCmFZF ddlCmZG dd9lHmIZI dd:lJmKZK dd;lJmLZL eeeM eeMef f ZNed<d=d>�ZOG d?d@� d@e�ZPG dAdB� dBe�ZQG dCdD� dDe+�ZRG dEdF� dFe+�ZSG dGdH� dHe+�ZTeeMef ZUeeMef ZVeeU ZWeeWeUf ZXeee eUf ZYeeee eWf ZZeeZeYf Z[eeeMdFee\ ee\ ee\ ee\ ee] f Z^eYZ_eZZ`e[ZaeedIf ZbeeeM eeM f Zce%eMef Zde)dJ ZeeeeMedKf Zfe)dL ZgG dMdN� dNe,dOdP�Zhe%eMef ZieeheeMef f ZjG dQdR� dRe,�ZkG dSdT� dTe,�ZlG dUdV� dVe,�ZmG dWdX� dXe,�ZnG dYdZ� dZen�ZoG d[d\� d\en�ZpG d]d^� d^en�ZqG d_d`� d`en�ZrG dadb� dbe,�ZsG dcdd� dde,�ZtG dedf� dfe�Zueee\eMf dgf ZveeeM eMf ZwG dhdi� die �ZxG djdk� dk�ZyG dldm� dm�ZzG dndo� doe �Z{e{Z|G dpdq� dq�Z}G drds� ds�Z~dtS )uz1Define core interfaces used by the engine system.� )� annotations)�Enum)� ModuleType)�Any)� Awaitable)�Callable)�ClassVar)� Collection)�Dict)�Iterable)�Iterator)�List)�Mapping)�MutableMapping)�Optional)�Sequence)�Set)�Tuple)�Type)� TYPE_CHECKING)�TypeVar)�Union� )�util)� EventTarget)�Pool)�PoolProxiedConnection)�Compiled)� TypeCompiler)� immutabledict)� await_only)�Literal)� NotRequired)�Protocol)� TypedDict� )� Connection)�Engine)� CursorResult)�URL)�_ListenerFnType)� dispatcher)�StatementError)� Executable)�_InsertManyValuesBatch)� DDLCompiler)�IdentifierPreparer)� InsertmanyvaluesSentinelOpts)�Linting)� SQLCompiler)� BindParameter)� ClauseElement)�Column)�DefaultGenerator)� SchemaItem)�Integer)� _TypeMemoDict)� TypeEngine�_Tr )�boundc @ s e Zd ZdZdZdZdZdZdS )� CacheStatsr r% r � � N)�__name__� __module__� __qualname__� CACHE_HIT� CACHE_MISS�CACHING_DISABLED� NO_CACHE_KEY�NO_DIALECT_SUPPORT� rI rI �Q/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/engine/interfaces.pyr> O s r> c @ s e Zd ZdZdZdZdZdS )� ExecuteStylezVindicates the :term:`DBAPI` cursor method that will be used to invoke a statement.r r% r N)rA rB rC �__doc__ZEXECUTEZ EXECUTEMANYZINSERTMANYVALUESrI rI rI rJ rK W s rK c @ sV e Zd ZU dZdd�dd�Zdd�dd�Zddd d �d d �Zdd�d d�Zded< dS )�DBAPIConnectionz�protocol representing a :pep:`249` database connection. .. versionadded:: 2.0 .. seealso:: `Connection Objects <https://www.python.org/dev/peps/pep-0249/#connection-objects>`_ - in :pep:`249` �None��returnc C s d S �NrI ��selfrI rI rJ �closey � zDBAPIConnection.closec C s d S rQ rI rR rI rI rJ �commit{ rU zDBAPIConnection.commitr � DBAPICursor)�args�kwargsrP c O s d S rQ rI )rS rX rY rI rI rJ �cursor} rU zDBAPIConnection.cursorc C s d S rQ rI rR rI rI rJ �rollback rU zDBAPIConnection.rollback�boolZ autocommitN) rA rB rC rL rT rV rZ r[ �__annotations__rI rI rI rJ rM m s rM c @ s e Zd ZdZdS )� DBAPITypez�protocol representing a :pep:`249` database type. .. versionadded:: 2.0 .. seealso:: `Type Objects <https://www.python.org/dev/peps/pep-0249/#type-objects>`_ - in :pep:`249` N)rA rB rC rL rI rI rI rJ r^ � s r^ c @ s� e Zd ZU dZedd�dd��Zedd�dd��Zded < ded < d d�d d �Zd1dddd�dd�Z dddd�dd�Z dd�dd�Z d2ddd �d d �Z dd�d d �Z dd d!�d"d#�Zddd d$�d%d&�Zd3d'ddd(�d)d*�Zd+d�d,d-�Zd'dd.�d/d0�ZdS )4rW z�protocol representing a :pep:`249` database cursor. .. versionadded:: 2.0 .. seealso:: `Cursor Objects <https://www.python.org/dev/peps/pep-0249/#cursor-objects>`_ - in :pep:`249` �_DBAPICursorDescriptionrO c C s dS )z�The description attribute of the Cursor. .. seealso:: `cursor.description <https://www.python.org/dev/peps/pep-0249/#description>`_ - in :pep:`249` NrI rR rI rI rJ � description� s zDBAPICursor.description�intc C s d S rQ rI rR rI rI rJ �rowcount� s zDBAPICursor.rowcountZ arraysizeZ lastrowidrN c C s d S rQ rI rR rI rI rJ rT � rU zDBAPICursor.closeNr �#Optional[_DBAPISingleExecuteParams])� operation� parametersrP c C s d S rQ rI �rS rd re rI rI rJ �execute� s zDBAPICursor.execute�_DBAPIMultiExecuteParamsc C s d S rQ rI rf rI rI rJ � executemany� s zDBAPICursor.executemanyz Optional[Any]c C s d S rQ rI rR rI rI rJ �fetchone� rU zDBAPICursor.fetchone.� Sequence[Any])�sizerP c C s d S rQ rI )rS rl rI rI rJ � fetchmany� rU zDBAPICursor.fetchmanyc C s d S rQ rI rR rI rI rJ �fetchall� rU zDBAPICursor.fetchall)�sizesrP c C s d S rQ rI )rS ro rI rI rJ � setinputsizes� rU zDBAPICursor.setinputsizes)rl �columnrP c C s d S rQ rI )rS rl rq rI rI rJ � setoutputsize� rU zDBAPICursor.setoutputsize�str)�procnamere rP c C s d S rQ rI )rS rt re rI rI rJ �callproc� s zDBAPICursor.callproczOptional[bool]c C s d S rQ rI rR rI rI rJ �nextset� rU zDBAPICursor.nextset)�keyrP c C s d S rQ rI )rS rw rI rI rJ � __getattr__� rU zDBAPICursor.__getattr__)N).).)rA rB rC rL �propertyr` rb r] rT rg ri rj rm rn rp rr ru rv rx rI rI rI rJ rW � s( � �rW r )Zqmark�numeric�named�formatZpyformatZnumeric_dollar�TypeEngine[Any])Z SERIALIZABLEzREPEATABLE READzREAD COMMITTEDzREAD UNCOMMITTEDZ AUTOCOMMITc @ s^ e Zd ZU ded< ded< ded< ded< ded < d ed < d ed < d ed < ded< ded< dS )�_CoreKnownExecutionOptionszOptional[CompiledCacheType]Zcompiled_cachers Z logging_token�IsolationLevelZisolation_levelr\ � no_parametersZstream_resultsra Zmax_row_bufferZ yield_per�insertmanyvalues_page_sizez Optional[SchemaTranslateMapType]Zschema_translate_mapZpreserve_rowcountN)rA rB rC r] rI rI rI rJ r~ s r~ F)�totalc @ sj e Zd ZU dZded< ded< ded< ded< ded< ded < ded < ded < ded < d ed< ded< dS )�ReflectedIdentitya& represent the reflected IDENTITY structure of a column, corresponding to the :class:`_schema.Identity` construct. The :class:`.ReflectedIdentity` structure is part of the :class:`.ReflectedColumn` structure, which is returned by the :meth:`.Inspector.get_columns` method. r\ �alwaysZon_nullra �start� incrementZminvalueZmaxvalueZ nominvalueZ nomaxvalue�cycle� Optional[int]�cache�orderN�rA rB rC rL r] rI rI rI rJ r� s r� c @ s" e Zd ZU dZded< ded< dS )�ReflectedComputeda% Represent the reflected elements of a computed column, corresponding to the :class:`_schema.Computed` construct. The :class:`.ReflectedComputed` structure is part of the :class:`.ReflectedColumn` structure, which is returned by the :meth:`.Inspector.get_columns` method. rs �sqltext�NotRequired[bool]Z persistedNr� rI rI rI rJ r� H s r� c @ sZ e Zd ZU dZded< ded< ded< ded < d ed < d ed < ded< ded< ded< dS )�ReflectedColumnz�Dictionary representing the reflected elements corresponding to a :class:`_schema.Column` object. The :class:`.ReflectedColumn` structure is returned by the :class:`.Inspector.get_columns` method. rs �namer} �typer\ Znullable� Optional[str]�defaultr� Z autoincrement�NotRequired[Optional[str]]�commentz NotRequired[ReflectedComputed]Zcomputedz NotRequired[ReflectedIdentity]�identity�NotRequired[Dict[str, Any]]�dialect_optionsNr� rI rI rI rJ r� Z s r� c @ s" e Zd ZU dZded< ded< dS )�ReflectedConstraintz�Dictionary representing the reflected elements corresponding to :class:`.Constraint` A base class for all constraints r� r� r� r� Nr� rI rI rI rJ r� � s r� c @ s" e Zd ZU dZded< ded< dS )�ReflectedCheckConstraintz�Dictionary representing the reflected elements corresponding to :class:`.CheckConstraint`. The :class:`.ReflectedCheckConstraint` structure is returned by the :meth:`.Inspector.get_check_constraints` method. rs r� r� r� Nr� rI rI rI rJ r� � s r� c @ s* e Zd ZU dZded< ded< ded< dS ) �ReflectedUniqueConstraintz�Dictionary representing the reflected elements corresponding to :class:`.UniqueConstraint`. The :class:`.ReflectedUniqueConstraint` structure is returned by the :meth:`.Inspector.get_unique_constraints` method. � List[str]� column_namesr� Zduplicates_indexr� r� Nr� rI rI rI rJ r� � s r� c @ s" e Zd ZU dZded< ded< dS )� ReflectedPrimaryKeyConstraintz�Dictionary representing the reflected elements corresponding to :class:`.PrimaryKeyConstraint`. The :class:`.ReflectedPrimaryKeyConstraint` structure is returned by the :meth:`.Inspector.get_pk_constraint` method. r� �constrained_columnsr� r� Nr� rI rI rI rJ r� � s r� c @ s: e Zd ZU dZded< ded< ded< ded< d ed < d S ) � ReflectedForeignKeyConstraintz�Dictionary representing the reflected elements corresponding to :class:`.ForeignKeyConstraint`. The :class:`.ReflectedForeignKeyConstraint` structure is returned by the :meth:`.Inspector.get_foreign_keys` method. r� r� r� Zreferred_schemars Zreferred_tableZreferred_columnsr� �optionsNr� rI rI rI rJ r� � s r� c @ sR e Zd ZU dZded< ded< ded< ded < d ed < ded < d ed< ded< dS )�ReflectedIndexz�Dictionary representing the reflected elements corresponding to :class:`.Index`. The :class:`.ReflectedIndex` structure is returned by the :meth:`.Inspector.get_indexes` method. r� r� zList[Optional[str]]r� zNotRequired[List[str]]Z expressionsr\ �uniquer� Zduplicates_constraintZinclude_columnsz"NotRequired[Dict[str, Tuple[str]]]Zcolumn_sortingr� r� Nr� rI rI rI rJ r� � s r� c @ s e Zd ZU dZded< dS )�ReflectedTableCommentz�Dictionary representing the reflected comment corresponding to the :attr:`_schema.Table.comment` attribute. The :class:`.ReflectedTableComment` structure is returned by the :meth:`.Inspector.get_table_comment` method. r� �textNr� rI rI rI rJ r� & s r� c @ s e Zd ZdZdZdZdZdS )� BindTypingz�Define different methods of passing typing information for bound parameters in a statement to the database driver. .. versionadded:: 2.0 r% r r? N)rA rB rC rL �NONEZ SETINPUTSIZESZ RENDER_CASTSrI rI rI rJ r� 3 s r� .c @ s& e Zd ZU dZejZejZejZejZej Z de d< de d< de d< de d< de d < e j d d �d d ��Z de d< de d< de d< de d< de d< de d< de d< de d < d e d < d e d < d!e d"< d#e d$< d%e d&< d%e d'< d(e d)< d*e d+< de d,< d-e d.< d/e d0< d/e d1< de d2< de d3< de d4< de d5< de d6< de d7< de d8< d9Zde d:< de d;< de d<< de d=< de d>< de d?< de d@< de dA< dBe dC< d-e dD< d-e dE< de dF< de dG< de dH< de dI< de dJ< de dK< de dL< de dM< de dN< dOe dP< de dQ< de dR< d-e dS< de dT< de dU< de dV< de dW< de dX< dYZdZe d[< d\Zd]e d^< e jZd_e d`< de da< de db< de dc< ddZdeZde df< de dg< ejZde dh< de di< dje dk< d/e dl< dme dn< dme do< de dp< de dq< de dr< de ds< dte du< dvd �dwdx�Zdydzd{�d|d}�Zed d �d~d��Zd�d�d��d�d��Z d�d�d��d�d��Z e �rFddd��d�d��Z �d^d�dd#dd�d��d�d��Z dYdYd��d�d#d�dd�d��d�d��Z!�d_d�dd#dd�d��d�d��Z"dYdYd��d�d#d�dd�d��d�d��Z#�d`d�dd#dd�d��d�d��Z$dYdYd��d�d#d�dd�d��d�d��Z%�dad�d#dd�d��d�d��Z&�dbd�d#dd�d��d�d��Z'�dcd�d#dd�d��d�d��Z(�ddd�d#dd�d��d�d��Z)�ded�d#dd�d��d�d��Z*�dfd�d#dd�d��d�d��Z+d�dd�d��d�d��Z,�dgd�dd#ddd��d�d��Z-�dhd�dd#dd�d��d�d��Z.dYdYd��d�d#d�dd�d��d�d��Z/�did�dd#dd�d��d�d��Z0dYdYd��d�d#d�dd�d��d�d��Z1�djd�dd#dd�d��d�dĄZ2dYdYd��d�d#d�dd�d��d�dDŽZ3�dkd�dd#dd�d��d�dʄZ4dYdYd��d�d#d�dd�d��d�d̈́Z5�dld�dd#dd�d��d�dЄZ6dYdYd��d�d#d�dd�d��d�dӄZ7dddԜd�dքZ8dddԜd�dZ9�dmd�dd#ddd��d�dڄZ:�dnd�ddd#dddۜd�d݄Z;�dod�dd#dddޜd�d�Z<d�dddd�d�d�Z=d�dd��d�d�Z>d�dd��d�d�Z?d�d�d�d�d�Z@d�d�d�d�d�ZAd�d�d�d�d�ZBd�d�d�d�d�ZCd�d�d�d�d�ZDd�dd�d�d��ZEd�dd�d�d��ZFd�d�d�dd��d�d��ZGdd �d��d �ZHd�dd��d��d�d�ZId�dd��d��d�d�ZJd�dd��d��d�d�ZKd�dd��d��d �d �ZLd�dd��d��d �d �ZM�dpd�dddd��d ��d�d�ZN�dqd�dddd��d ��d�d�ZOd��dd���d�d�ZPd�d�d�d�dd��d�d��d�d�ZQ�drd�d�d�dd��d ��d �d �ZR�dsd�d�d �dd��d ��d �d!�ZS�dtd�d�dd��d"��d#�d$�ZT�d%�d&�d'd�d(��d)�d*�ZUddd�d+��d,�d-�ZVdy�d.d{��d/�d0�ZW�d.d ��d1�d2�ZXd�d�d��d3�d4�ZYd�d5d��d6��d7�d8�ZZd�d5d��d9�d:�Z[d�d5�d;��d<�d=�Z\d�d>�d;��d?�d@�Z]d�d5d��dA��dB�dC�Z^edy�dDd{��dE�dF��Z_edy�dDd{��dG�dH��Z`ed�d ��dI�dJ��Zae�dKd��dL��dM�dN��Zbd�dd���dO�dP�Zc�dK�dQd��dR��dS�dT�Zdd��dQd��dU��dV�dW�Zedy�dXd{��dY�dZ�Zfdd��d[��d\�d]�ZgdYS (u �Dialectae Define the behavior of a specific database and DB-API combination. Any aspect of metadata definition, SQL query generation, execution, result-set handling, or anything else which varies between databases is defined under the general category of the Dialect. The Dialect acts as a factory for other database-specific object implementations including ExecutionContext, Compiled, DefaultGenerator, and TypeEngine. .. note:: Third party dialects should not subclass :class:`.Dialect` directly. Instead, subclass :class:`.default.DefaultDialect` or descendant class. zdispatcher[Dialect]�dispatchrs r� ZdriverZdialect_descriptionzOptional[ModuleType]Zdbapir rO c C s t � �dS )zsame as .dbapi, but is never None; will raise an error if no DBAPI was set up. .. versionadded:: 2.0 N��NotImplementedErrorrR rI rI rJ � loaded_dbapi� s zDialect.loaded_dbapir\ � positionalZ paramstyler2 Zcompiler_lintingzType[SQLCompiler]Zstatement_compilerzType[DDLCompiler]Z ddl_compilerz ClassVar[Type[TypeCompiler]]Ztype_compiler_clsr Ztype_compiler_instancer Z type_compilerzType[IdentifierPreparer]�preparerr0 Zidentifier_preparerzOptional[Tuple[Any, ...]]Zserver_version_infor� Zdefault_schema_namezOptional[IsolationLevel]Zdefault_isolation_levelZ_on_connect_isolation_levelzType[ExecutionContext]Zexecution_ctx_clsz4Union[Type[Tuple[Any, ...]], Type[Tuple[List[Any]]]]Zexecute_sequence_formatZsupports_alterra Zmax_identifier_lengthr� Zmax_index_name_lengthZmax_constraint_name_lengthZ supports_server_side_cursorsZserver_side_cursorsZsupports_sane_rowcountZ supports_sane_multi_rowcountZsupports_empty_insertZsupports_default_valuesZsupports_default_metavalue�DEFAULT�default_metavalue_tokenZsupports_multivalues_insertZ insert_executemany_returningZ4insert_executemany_returning_sort_by_parameter_orderZ update_executemany_returningZ delete_executemany_returningZuse_insertmanyvaluesZ!use_insertmanyvalues_wo_returningr1 Z"insertmanyvalues_implicit_sentinelr� Z insertmanyvalues_max_parametersZ"preexecute_autoincrement_sequencesZinsert_returningZupdate_returningZupdate_returning_multifromZdelete_returningZdelete_returning_multifromZ favor_returning_over_lastrowidZsupports_identity_columnsZcte_follows_insertz<MutableMapping[Type[TypeEngine[Any]], Type[TypeEngine[Any]]]ZcolspecsZsupports_sequencesZsequences_optionalZdefault_sequence_baseZsupports_native_enumZsupports_native_booleanZsupports_native_decimalZsupports_native_uuidZreturns_native_bytesNzPOptional[List[Tuple[Type[Union[SchemaItem, ClauseElement]], Mapping[str, Any]]]]�construct_argumentsrI � Sequence[str]�reflection_optionszMapping[str, str]� dbapi_exception_translation_mapZsupports_commentsZinline_commentsZ supports_constraint_commentsFT�supports_statement_cacheZ_supports_statement_cache�is_asyncZ has_terminatezMapping[str, Any]Zengine_config_typesZ label_lengthzOptional[Set[Any]]Zinclude_set_input_sizesZexclude_set_input_sizesZ supports_simple_order_by_labelZdiv_is_floordivZtuple_in_valuesZ_bind_typing_render_castsz.MutableMapping[TypeEngine[Any], _TypeMemoDict]Z _type_memoszOptional[_ListenerFnType]c C s t � �d S rQ r� rR rI rI rJ �_builtin_onconnect� s zDialect._builtin_onconnectr) �ConnectArgsType��urlrP c C s t � �dS )a� Build DB-API compatible connection arguments. Given a :class:`.URL` object, returns a tuple consisting of a ``(*args, **kwargs)`` suitable to send directly to the dbapi's connect function. The arguments are sent to the :meth:`.Dialect.connect` method which then runs the DBAPI-level ``connect()`` function. The method typically makes use of the :meth:`.URL.translate_connect_args` method in order to generate a dictionary of options. The default implementation is:: def create_connect_args(self, url): opts = url.translate_connect_args() opts.update(url.query) return ([], opts) :param url: a :class:`.URL` object :return: a tuple of ``(*args, **kwargs)`` which will be passed to the :meth:`.Dialect.connect` method. .. seealso:: :meth:`.URL.translate_connect_args` Nr� �rS r� rI rI rJ �create_connect_args� s zDialect.create_connect_argsc C s t � �dS )a� Import the DBAPI module that is used by this dialect. The Python module object returned here will be assigned as an instance variable to a constructed dialect under the name ``.dbapi``. .. versionchanged:: 2.0 The :meth:`.Dialect.import_dbapi` class method is renamed from the previous method ``.Dialect.dbapi()``, which would be replaced at dialect instantiation time by the DBAPI module itself, thus using the same name in two different ways. If a ``.Dialect.dbapi()`` classmethod is present on a third-party dialect, it will be used and a deprecation warning will be emitted. Nr� ��clsrI rI rJ � import_dbapi� s zDialect.import_dbapizTypeEngine[_T])�typeobjrP c C s t � �dS )a4 Transform a generic type to a dialect-specific type. Dialect classes will usually use the :func:`_types.adapt_type` function in the types module to accomplish this. The returned result is cached *per dialect class* so can contain no dialect-instance state. Nr� )rS r� rI rI rJ �type_descriptor� s zDialect.type_descriptorr& rN )� connectionrP c C s dS )a Called during strategized creation of the dialect with a connection. Allows dialects to configure options based on server version info or other properties. The connection passed here is a SQLAlchemy Connection object, with full capabilities. The initialize() method of the base dialect should be called via super(). .. note:: as of SQLAlchemy 1.4, this method is called **before** any :meth:`_engine.Dialect.on_connect` hooks are called. NrI �rS r� rI rI rJ � initialize� s zDialect.initialize)� method_namerP c C s d S rQ rI )rS r� rI rI rJ �_overrides_default rU zDialect._overrides_defaultzList[ReflectedColumn])r� � table_name�schema�kwrP c K s t � �dS )a� Return information about columns in ``table_name``. Given a :class:`_engine.Connection`, a string ``table_name``, and an optional string ``schema``, return column information as a list of dictionaries corresponding to the :class:`.ReflectedColumn` dictionary. This is an internal dialect method. Applications should use :meth:`.Inspector.get_columns`. Nr� �rS r� r� r� r� rI rI rJ � get_columns s zDialect.get_columns)r� � filter_nameszOptional[Collection[str]]z0Iterable[Tuple[TableKey, List[ReflectedColumn]]])r� r� r� r� rP c K s t � �dS )a� Return information about columns in all tables in the given ``schema``. This is an internal dialect method. Applications should use :meth:`.Inspector.get_multi_columns`. .. note:: The :class:`_engine.DefaultDialect` provides a default implementation that will call the single table method for each object returned by :meth:`Dialect.get_table_names`, :meth:`Dialect.get_view_names` or :meth:`Dialect.get_materialized_view_names` depending on the provided ``kind``. Dialects that want to support a faster implementation should implement this method. .. versionadded:: 2.0 Nr� �rS r� r� r� r� rI rI rJ �get_multi_columns$ s zDialect.get_multi_columnsr� c K s t � �dS )a� Return information about the primary key constraint on table_name`. Given a :class:`_engine.Connection`, a string ``table_name``, and an optional string ``schema``, return primary key information as a dictionary corresponding to the :class:`.ReflectedPrimaryKeyConstraint` dictionary. This is an internal dialect method. Applications should use :meth:`.Inspector.get_pk_constraint`. Nr� r� rI rI rJ �get_pk_constraint@ s zDialect.get_pk_constraintz8Iterable[Tuple[TableKey, ReflectedPrimaryKeyConstraint]]c K s t � �dS )a� Return information about primary key constraints in all tables in the given ``schema``. This is an internal dialect method. Applications should use :meth:`.Inspector.get_multi_pk_constraint`. .. note:: The :class:`_engine.DefaultDialect` provides a default implementation that will call the single table method for each object returned by :meth:`Dialect.get_table_names`, :meth:`Dialect.get_view_names` or :meth:`Dialect.get_materialized_view_names` depending on the provided ``kind``. Dialects that want to support a faster implementation should implement this method. .. versionadded:: 2.0 Nr� r� rI rI rJ �get_multi_pk_constraintU s z Dialect.get_multi_pk_constraintz#List[ReflectedForeignKeyConstraint]c K s t � �dS )a� Return information about foreign_keys in ``table_name``. Given a :class:`_engine.Connection`, a string ``table_name``, and an optional string ``schema``, return foreign key information as a list of dicts corresponding to the :class:`.ReflectedForeignKeyConstraint` dictionary. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.get_foreign_keys`. Nr� r� rI rI rJ �get_foreign_keysp s zDialect.get_foreign_keysz>Iterable[Tuple[TableKey, List[ReflectedForeignKeyConstraint]]]c K s t � �dS )a� Return information about foreign_keys in all tables in the given ``schema``. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.get_multi_foreign_keys`. .. note:: The :class:`_engine.DefaultDialect` provides a default implementation that will call the single table method for each object returned by :meth:`Dialect.get_table_names`, :meth:`Dialect.get_view_names` or :meth:`Dialect.get_materialized_view_names` depending on the provided ``kind``. Dialects that want to support a faster implementation should implement this method. .. versionadded:: 2.0 Nr� r� rI rI rJ �get_multi_foreign_keys� s z Dialect.get_multi_foreign_keysr� )r� r� r� rP c K s t � �dS )z�Return a list of table names for ``schema``. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.get_table_names`. Nr� �rS r� r� r� rI rI rJ �get_table_names� s zDialect.get_table_namesc K s t � �dS )z�Return a list of temporary table names on the given connection, if supported by the underlying backend. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.get_temp_table_names`. Nr� r� rI rI rJ �get_temp_table_names� s z Dialect.get_temp_table_namesc K s t � �dS )a Return a list of all non-materialized view names available in the database. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.get_view_names`. :param schema: schema name to query, if not the default schema. Nr� r� rI rI rJ �get_view_names� s zDialect.get_view_namesc K s t � �dS )aF Return a list of all materialized view names available in the database. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.get_materialized_view_names`. :param schema: schema name to query, if not the default schema. .. versionadded:: 2.0 Nr� r� rI rI rJ �get_materialized_view_names� s z#Dialect.get_materialized_view_namesc K s t � �dS )a* Return a list of all sequence names available in the database. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.get_sequence_names`. :param schema: schema name to query, if not the default schema. .. versionadded:: 1.4 Nr� r� rI rI rJ �get_sequence_names� s zDialect.get_sequence_namesc K s t � �dS )z�Return a list of temporary view names on the given connection, if supported by the underlying backend. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.get_temp_view_names`. Nr� r� rI rI rJ �get_temp_view_names� s zDialect.get_temp_view_names)r� r� rP c K s t � �dS )z�Return a list of all schema names available in the database. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.get_schema_names`. Nr� )rS r� r� rI rI rJ �get_schema_names� s zDialect.get_schema_names)r� � view_namer� r� rP c K s t � �dS )aG Return plain or materialized view definition. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.get_view_definition`. Given a :class:`_engine.Connection`, a string ``view_name``, and an optional string ``schema``, return the view definition. Nr� )rS r� r� r� r� rI rI rJ �get_view_definition� s zDialect.get_view_definitionzList[ReflectedIndex]c K s t � �dS )a� Return information about indexes in ``table_name``. Given a :class:`_engine.Connection`, a string ``table_name`` and an optional string ``schema``, return index information as a list of dictionaries corresponding to the :class:`.ReflectedIndex` dictionary. This is an internal dialect method. Applications should use :meth:`.Inspector.get_indexes`. Nr� r� rI rI rJ � get_indexes s zDialect.get_indexesz/Iterable[Tuple[TableKey, List[ReflectedIndex]]]c K s t � �dS )a� Return information about indexes in in all tables in the given ``schema``. This is an internal dialect method. Applications should use :meth:`.Inspector.get_multi_indexes`. .. note:: The :class:`_engine.DefaultDialect` provides a default implementation that will call the single table method for each object returned by :meth:`Dialect.get_table_names`, :meth:`Dialect.get_view_names` or :meth:`Dialect.get_materialized_view_names` depending on the provided ``kind``. Dialects that want to support a faster implementation should implement this method. .. versionadded:: 2.0 Nr� r� rI rI rJ �get_multi_indexes$ s zDialect.get_multi_indexesz List[ReflectedUniqueConstraint]c K s t � �dS )a� Return information about unique constraints in ``table_name``. Given a string ``table_name`` and an optional string ``schema``, return unique constraint information as a list of dicts corresponding to the :class:`.ReflectedUniqueConstraint` dictionary. This is an internal dialect method. Applications should use :meth:`.Inspector.get_unique_constraints`. Nr� r� rI rI rJ �get_unique_constraints@ s z Dialect.get_unique_constraintsz:Iterable[Tuple[TableKey, List[ReflectedUniqueConstraint]]]c K s t � �dS )a� Return information about unique constraints in all tables in the given ``schema``. This is an internal dialect method. Applications should use :meth:`.Inspector.get_multi_unique_constraints`. .. note:: The :class:`_engine.DefaultDialect` provides a default implementation that will call the single table method for each object returned by :meth:`Dialect.get_table_names`, :meth:`Dialect.get_view_names` or :meth:`Dialect.get_materialized_view_names` depending on the provided ``kind``. Dialects that want to support a faster implementation should implement this method. .. versionadded:: 2.0 Nr� r� rI rI rJ � get_multi_unique_constraintsS s z$Dialect.get_multi_unique_constraintsz List[ReflectedCheckConstraint]c K s t � �dS )a� Return information about check constraints in ``table_name``. Given a string ``table_name`` and an optional string ``schema``, return check constraint information as a list of dicts corresponding to the :class:`.ReflectedCheckConstraint` dictionary. This is an internal dialect method. Applications should use :meth:`.Inspector.get_check_constraints`. Nr� r� rI rI rJ �get_check_constraintso s z Dialect.get_check_constraintsz9Iterable[Tuple[TableKey, List[ReflectedCheckConstraint]]]c K s t � �dS )a� Return information about check constraints in all tables in the given ``schema``. This is an internal dialect method. Applications should use :meth:`.Inspector.get_multi_check_constraints`. .. note:: The :class:`_engine.DefaultDialect` provides a default implementation that will call the single table method for each object returned by :meth:`Dialect.get_table_names`, :meth:`Dialect.get_view_names` or :meth:`Dialect.get_materialized_view_names` depending on the provided ``kind``. Dialects that want to support a faster implementation should implement this method. .. versionadded:: 2.0 Nr� r� rI rI rJ �get_multi_check_constraints� s z#Dialect.get_multi_check_constraints�Dict[str, Any]c K s t � �dS )z�Return a dictionary of options specified when ``table_name`` was created. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.get_table_options`. Nr� r� rI rI rJ �get_table_options� s zDialect.get_table_optionsz)Iterable[Tuple[TableKey, Dict[str, Any]]]c K s t � �dS )a� Return a dictionary of options specified when the tables in the given schema were created. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.get_multi_table_options`. .. note:: The :class:`_engine.DefaultDialect` provides a default implementation that will call the single table method for each object returned by :meth:`Dialect.get_table_names`, :meth:`Dialect.get_view_names` or :meth:`Dialect.get_materialized_view_names` depending on the provided ``kind``. Dialects that want to support a faster implementation should implement this method. .. versionadded:: 2.0 Nr� r� rI rI rJ �get_multi_table_options� s z Dialect.get_multi_table_optionsr� c K s t � �dS )a Return the "comment" for the table identified by ``table_name``. Given a string ``table_name`` and an optional string ``schema``, return table comment information as a dictionary corresponding to the :class:`.ReflectedTableComment` dictionary. This is an internal dialect method. Applications should use :meth:`.Inspector.get_table_comment`. :raise: ``NotImplementedError`` for dialects that don't support comments. .. versionadded:: 1.2 Nr� r� rI rI rJ �get_table_comment� s zDialect.get_table_commentz0Iterable[Tuple[TableKey, ReflectedTableComment]]c K s t � �dS )a� Return information about the table comment in all tables in the given ``schema``. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.get_multi_table_comment`. .. note:: The :class:`_engine.DefaultDialect` provides a default implementation that will call the single table method for each object returned by :meth:`Dialect.get_table_names`, :meth:`Dialect.get_view_names` or :meth:`Dialect.get_materialized_view_names` depending on the provided ``kind``. Dialects that want to support a faster implementation should implement this method. .. versionadded:: 2.0 Nr� r� rI rI rJ �get_multi_table_comment� s z Dialect.get_multi_table_comment)r� rP c C s t � �dS )z�convert the given name to lowercase if it is detected as case insensitive. This method is only used if the dialect defines requires_name_normalize=True. Nr� �rS r� rI rI rJ �normalize_name� s zDialect.normalize_namec C s t � �dS )z�convert the given name to a case insensitive identifier for the backend if it is an all-lowercase name. This method is only used if the dialect defines requires_name_normalize=True. Nr� r� rI rI rJ �denormalize_name s zDialect.denormalize_namec K s t � �dS )a For internal dialect use, check the existence of a particular table or view in the database. Given a :class:`_engine.Connection` object, a string table_name and optional schema name, return True if the given table exists in the database, False otherwise. This method serves as the underlying implementation of the public facing :meth:`.Inspector.has_table` method, and is also used internally to implement the "checkfirst" behavior for methods like :meth:`_schema.Table.create` and :meth:`_schema.MetaData.create_all`. .. note:: This method is used internally by SQLAlchemy, and is published so that third-party dialects may provide an implementation. It is **not** the public API for checking for table presence. Please use the :meth:`.Inspector.has_table` method. .. versionchanged:: 2.0:: :meth:`_engine.Dialect.has_table` now formally supports checking for additional table-like objects: * any type of views (plain or materialized) * temporary tables of any kind Previously, these two checks were not formally specified and different dialects would vary in their behavior. The dialect testing suite now includes tests for all of these object types, and dialects to the degree that the backing database supports views or temporary tables should seek to support locating these objects for full compliance. Nr� r� rI rI rJ � has_table s 'zDialect.has_table)r� r� � index_namer� r� rP c K s t � �dS )a� Check the existence of a particular index name in the database. Given a :class:`_engine.Connection` object, a string ``table_name`` and string index name, return ``True`` if an index of the given name on the given table exists, ``False`` otherwise. The :class:`.DefaultDialect` implements this in terms of the :meth:`.Dialect.has_table` and :meth:`.Dialect.get_indexes` methods, however dialects can implement a more performant version. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.has_index`. .. versionadded:: 1.4 Nr� )rS r� r� r� r� r� rI rI rJ � has_index; s zDialect.has_index)r� � sequence_namer� r� rP c K s t � �dS )ap Check the existence of a particular sequence in the database. Given a :class:`_engine.Connection` object and a string `sequence_name`, return ``True`` if the given sequence exists in the database, ``False`` otherwise. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.has_sequence`. Nr� )rS r� r� r� r� rI rI rJ � has_sequenceV s zDialect.has_sequence)r� � schema_namer� rP c K s t � �dS )av Check the existence of a particular schema name in the database. Given a :class:`_engine.Connection` object, a string ``schema_name``, return ``True`` if a schema of the given exists, ``False`` otherwise. The :class:`.DefaultDialect` implements this by checking the presence of ``schema_name`` among the schemas returned by :meth:`.Dialect.get_schema_names`, however dialects can implement a more performant version. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.has_schema`. .. versionadded:: 2.0 Nr� )rS r� r� r� rI rI rJ � has_schemai s zDialect.has_schemac C s t � �dS )z�Retrieve the server version info from the given connection. This is used by the default implementation to populate the "server_version_info" attribute and is called exactly once upon first connect. Nr� r� rI rI rJ �_get_server_version_info� s z Dialect._get_server_version_infoc C s t � �dS )a Return the string name of the currently selected schema from the given connection. This is used by the default implementation to populate the "default_schema_name" attribute and is called exactly once upon first connect. Nr� r� rI rI rJ �_get_default_schema_name� s z Dialect._get_default_schema_namer )�dbapi_connectionrP c C s t � �dS )a� Provide an implementation of ``connection.begin()``, given a DB-API connection. The DBAPI has no dedicated "begin" method and it is expected that transactions are implicit. This hook is provided for those DBAPIs that might need additional help in this area. :param dbapi_connection: a DBAPI connection, typically proxied within a :class:`.ConnectionFairy`. Nr� �rS r� rI rI rJ �do_begin� s zDialect.do_beginc C s t � �dS )z�Provide an implementation of ``connection.rollback()``, given a DB-API connection. :param dbapi_connection: a DBAPI connection, typically proxied within a :class:`.ConnectionFairy`. Nr� r� rI rI rJ � do_rollback� s zDialect.do_rollbackc C s t � �dS )z�Provide an implementation of ``connection.commit()``, given a DB-API connection. :param dbapi_connection: a DBAPI connection, typically proxied within a :class:`.ConnectionFairy`. Nr� r� rI rI rJ � do_commit� s zDialect.do_commitrM c C s t � �dS )a� Provide an implementation of ``connection.close()`` that tries as much as possible to not block, given a DBAPI connection. In the vast majority of cases this just calls .close(), however for some asyncio dialects may call upon different API features. This hook is called by the :class:`_pool.Pool` when a connection is being recycled or has been invalidated. .. versionadded:: 1.4.41 Nr� r� rI rI rJ � do_terminate� s zDialect.do_terminatec C s t � �dS )a Provide an implementation of ``connection.close()``, given a DBAPI connection. This hook is called by the :class:`_pool.Pool` when a connection has been detached from the pool, or is being returned beyond the normal capacity of the pool. Nr� r� rI rI rJ �do_close� s zDialect.do_closec C s t � �d S rQ r� r� rI rI rJ �_do_ping_w_event� s zDialect._do_ping_w_eventc C s t � �dS )zNping the DBAPI connection and return True if the connection is usable.Nr� r� rI rI rJ �do_ping� s zDialect.do_pingrW �_GenericSetInputSizesType�ExecutionContext)rZ �list_of_tuples�contextrP c C s t � �dS )aJ invoke the cursor.setinputsizes() method with appropriate arguments This hook is called if the :attr:`.Dialect.bind_typing` attribute is set to the :attr:`.BindTyping.SETINPUTSIZES` value. Parameter data is passed in a list of tuples (paramname, dbtype, sqltype), where ``paramname`` is the key of the parameter in the statement, ``dbtype`` is the DBAPI datatype and ``sqltype`` is the SQLAlchemy type. The order of tuples is in the correct parameter order. .. versionadded:: 1.4 .. versionchanged:: 2.0 - setinputsizes mode is now enabled by setting :attr:`.Dialect.bind_typing` to :attr:`.BindTyping.SETINPUTSIZES`. Dialects which accept a ``use_setinputsizes`` parameter should set this value appropriately. Nr� )rS rZ r� r rI rI rJ �do_set_input_sizes� s zDialect.do_set_input_sizesc C s t � �dS )z�Create a two-phase transaction ID. This id will be passed to do_begin_twophase(), do_rollback_twophase(), do_commit_twophase(). Its format is unspecified. Nr� rR rI rI rJ � create_xid� s zDialect.create_xid)r� r� rP c C s t � �dS )z�Create a savepoint with the given name. :param connection: a :class:`_engine.Connection`. :param name: savepoint name. Nr� �rS r� r� rI rI rJ � do_savepoint s zDialect.do_savepointc C s t � �dS )z�Rollback a connection to the named savepoint. :param connection: a :class:`_engine.Connection`. :param name: savepoint name. Nr� r rI rI rJ �do_rollback_to_savepoint s z Dialect.do_rollback_to_savepointc C s t � �dS )z�Release the named savepoint on a connection. :param connection: a :class:`_engine.Connection`. :param name: savepoint name. Nr� r rI rI rJ �do_release_savepoint s z Dialect.do_release_savepoint)r� �xidrP c C s t � �dS )z�Begin a two phase transaction on the given connection. :param connection: a :class:`_engine.Connection`. :param xid: xid Nr� �rS r� r rI rI rJ �do_begin_twophase' s zDialect.do_begin_twophasec C s t � �dS )z�Prepare a two phase transaction on the given connection. :param connection: a :class:`_engine.Connection`. :param xid: xid Nr� r rI rI rJ �do_prepare_twophase1 s zDialect.do_prepare_twophase)r� r � is_prepared�recoverrP c C s t � �dS )a3 Rollback a two phase transaction on the given connection. :param connection: a :class:`_engine.Connection`. :param xid: xid :param is_prepared: whether or not :meth:`.TwoPhaseTransaction.prepare` was called. :param recover: if the recover flag was passed. Nr� �rS r� r r r rI rI rJ �do_rollback_twophase; s z Dialect.do_rollback_twophasec C s t � �dS )a2 Commit a two phase transaction on the given connection. :param connection: a :class:`_engine.Connection`. :param xid: xid :param is_prepared: whether or not :meth:`.TwoPhaseTransaction.prepare` was called. :param recover: if the recover flag was passed. Nr� r rI rI rJ �do_commit_twophaseN s zDialect.do_commit_twophasez List[Any]c C s t � �dS )z�Recover list of uncommitted prepared two phase transaction identifiers on the given connection. :param connection: a :class:`_engine.Connection`. Nr� r� rI rI rJ �do_recover_twophaseb s zDialect.do_recover_twophaserh z#Optional[_GenericSetInputSizesType]z Iterator[_InsertManyValuesBatch])r� rZ � statementre �generic_setinputsizesr rP c C s t � �dS )z�convert executemany parameters for an INSERT into an iterator of statement/single execute values, used by the insertmanyvalues feature. Nr� )rS r� rZ r re r r rI rI rJ �!_deliver_insertmanyvalues_batchesl s z)Dialect._deliver_insertmanyvalues_batches�Optional[ExecutionContext])rZ r re r rP c C s t � �dS )zSProvide an implementation of ``cursor.executemany(statement, parameters)``.Nr� �rS rZ r re r rI rI rJ �do_executemany| s zDialect.do_executemanyrc c C s t � �dS )zOProvide an implementation of ``cursor.execute(statement, parameters)``.Nr� r rI rI rJ � do_execute� s zDialect.do_execute)rZ r r rP c C s t � �dS )z{Provide an implementation of ``cursor.execute(statement)``. The parameter collection should not be sent. Nr� )rS rZ r r rI rI rJ �do_execute_no_params� s z Dialect.do_execute_no_params� Exceptionz7Optional[Union[PoolProxiedConnection, DBAPIConnection]]�Optional[DBAPICursor])�er� rZ rP c C s t � �dS )zMReturn True if the given DB-API error indicates an invalid connectionNr� )rS r r� rZ rI rI rJ � is_disconnect� s zDialect.is_disconnect)�cargs�cparamsrP c O s t � �dS )a� Establish a connection using this dialect's DBAPI. The default implementation of this method is:: def connect(self, *cargs, **cparams): return self.dbapi.connect(*cargs, **cparams) The ``*cargs, **cparams`` parameters are generated directly from this dialect's :meth:`.Dialect.create_connect_args` method. This method may be used for dialects that need to perform programmatic per-connection steps when a new connection is procured from the DBAPI. :param \*cargs: positional parameters returned from the :meth:`.Dialect.create_connect_args` method :param \*\*cparams: keyword parameters returned from the :meth:`.Dialect.create_connect_args` method. :return: a DBAPI connection, typically from the :pep:`249` module level ``.connect()`` function. .. seealso:: :meth:`.Dialect.create_connect_args` :meth:`.Dialect.on_connect` Nr� )rS r r rI rI rJ �connect� s zDialect.connectz Optional[Callable[[Any], Any]]c C s | � � S )a& return a callable which sets up a newly created DBAPI connection. This method is a new hook that supersedes the :meth:`_engine.Dialect.on_connect` method when implemented by a dialect. When not implemented by a dialect, it invokes the :meth:`_engine.Dialect.on_connect` method directly to maintain compatibility with existing dialects. There is no deprecation for :meth:`_engine.Dialect.on_connect` expected. The callable should accept a single argument "conn" which is the DBAPI connection itself. The inner callable has no return value. E.g.:: class MyDialect(default.DefaultDialect): # ... def on_connect_url(self, url): def do_on_connect(connection): connection.execute("SET SPECIAL FLAGS etc") return do_on_connect This is used to set dialect-wide per-connection options such as isolation modes, Unicode modes, etc. This method differs from :meth:`_engine.Dialect.on_connect` in that it is passed the :class:`_engine.URL` object that's relevant to the connect args. Normally the only way to get this is from the :meth:`_engine.Dialect.on_connect` hook is to look on the :class:`_engine.Engine` itself, however this URL object may have been replaced by plugins. .. note:: The default implementation of :meth:`_engine.Dialect.on_connect_url` is to invoke the :meth:`_engine.Dialect.on_connect` method. Therefore if a dialect implements this method, the :meth:`_engine.Dialect.on_connect` method **will not be called** unless the overriding dialect calls it directly from here. .. versionadded:: 1.4.3 added :meth:`_engine.Dialect.on_connect_url` which normally calls into :meth:`_engine.Dialect.on_connect`. :param url: a :class:`_engine.URL` object representing the :class:`_engine.URL` that was passed to the :meth:`_engine.Dialect.create_connect_args` method. :return: a callable that accepts a single DBAPI connection as an argument, or None. .. seealso:: :meth:`_engine.Dialect.on_connect` )� on_connectr� rI rI rJ �on_connect_url� s ;zDialect.on_connect_urlc C s dS )a� return a callable which sets up a newly created DBAPI connection. The callable should accept a single argument "conn" which is the DBAPI connection itself. The inner callable has no return value. E.g.:: class MyDialect(default.DefaultDialect): # ... def on_connect(self): def do_on_connect(connection): connection.execute("SET SPECIAL FLAGS etc") return do_on_connect This is used to set dialect-wide per-connection options such as isolation modes, Unicode modes, etc. The "do_on_connect" callable is invoked by using the :meth:`_events.PoolEvents.connect` event hook, then unwrapping the DBAPI connection and passing it into the callable. .. versionchanged:: 1.4 the on_connect hook is no longer called twice for the first connection of a dialect. The on_connect hook is still called before the :meth:`_engine.Dialect.initialize` method however. .. versionchanged:: 1.4.3 the on_connect hook is invoked from a new method on_connect_url that passes the URL that was used to create the connect args. Dialects can implement on_connect_url instead of on_connect if they need the URL object that was used for the connection in order to get additional context. If None is returned, no event listener is generated. :return: a callable that accepts a single DBAPI connection as an argument, or None. .. seealso:: :meth:`.Dialect.connect` - allows the DBAPI ``connect()`` sequence itself to be controlled. :meth:`.Dialect.on_connect_url` - supersedes :meth:`.Dialect.on_connect` to also receive the :class:`_engine.URL` object in context. NrI rR rI rI rJ r s 3zDialect.on_connectc C s t � �dS )a2 Given a DBAPI connection, revert its isolation to the default. Note that this is a dialect-level method which is used as part of the implementation of the :class:`_engine.Connection` and :class:`_engine.Engine` isolation level facilities; these APIs should be preferred for most typical use cases. .. seealso:: :meth:`_engine.Connection.get_isolation_level` - view current level :attr:`_engine.Connection.default_isolation_level` - view default level :paramref:`.Connection.execution_options.isolation_level` - set per :class:`_engine.Connection` isolation level :paramref:`_sa.create_engine.isolation_level` - set per :class:`_engine.Engine` isolation level Nr� r� rI rI rJ �reset_isolation_levelA s z Dialect.reset_isolation_levelr )r� �levelrP c C s t � �dS )a2 Given a DBAPI connection, set its isolation level. Note that this is a dialect-level method which is used as part of the implementation of the :class:`_engine.Connection` and :class:`_engine.Engine` isolation level facilities; these APIs should be preferred for most typical use cases. If the dialect also implements the :meth:`.Dialect.get_isolation_level_values` method, then the given level is guaranteed to be one of the string names within that sequence, and the method will not need to anticipate a lookup failure. .. seealso:: :meth:`_engine.Connection.get_isolation_level` - view current level :attr:`_engine.Connection.default_isolation_level` - view default level :paramref:`.Connection.execution_options.isolation_level` - set per :class:`_engine.Connection` isolation level :paramref:`_sa.create_engine.isolation_level` - set per :class:`_engine.Engine` isolation level Nr� )rS r� r# rI rI rJ �set_isolation_level\ s zDialect.set_isolation_levelc C s t � �dS )a� Given a DBAPI connection, return its isolation level. When working with a :class:`_engine.Connection` object, the corresponding DBAPI connection may be procured using the :attr:`_engine.Connection.connection` accessor. Note that this is a dialect-level method which is used as part of the implementation of the :class:`_engine.Connection` and :class:`_engine.Engine` isolation level facilities; these APIs should be preferred for most typical use cases. .. seealso:: :meth:`_engine.Connection.get_isolation_level` - view current level :attr:`_engine.Connection.default_isolation_level` - view default level :paramref:`.Connection.execution_options.isolation_level` - set per :class:`_engine.Connection` isolation level :paramref:`_sa.create_engine.isolation_level` - set per :class:`_engine.Engine` isolation level Nr� r� rI rI rJ �get_isolation_level~ s !zDialect.get_isolation_level)� dbapi_connrP c C s t � �dS )a� Given a DBAPI connection, return its isolation level, or a default isolation level if one cannot be retrieved. This method may only raise NotImplementedError and **must not raise any other exception**, as it is used implicitly upon first connect. The method **must return a value** for a dialect that supports isolation level settings, as this level is what will be reverted towards when a per-connection isolation level change is made. The method defaults to using the :meth:`.Dialect.get_isolation_level` method unless overridden by a dialect. .. versionadded:: 1.3.22 Nr� �rS r& rI rI rJ �get_default_isolation_level� s z#Dialect.get_default_isolation_levelzSequence[IsolationLevel]c C s t � �dS )a return a sequence of string isolation level names that are accepted by this dialect. The available names should use the following conventions: * use UPPERCASE names. isolation level methods will accept lowercase names but these are normalized into UPPERCASE before being passed along to the dialect. * separate words should be separated by spaces, not underscores, e.g. ``REPEATABLE READ``. isolation level names will have underscores converted to spaces before being passed along to the dialect. * The names for the four standard isolation names to the extent that they are supported by the backend should be ``READ UNCOMMITTED``, ``READ COMMITTED``, ``REPEATABLE READ``, ``SERIALIZABLE`` * if the dialect supports an autocommit option it should be provided using the isolation level name ``AUTOCOMMIT``. * Other isolation modes may also be present, provided that they are named in UPPERCASE and use spaces not underscores. This function is used so that the default dialect can check that a given isolation level parameter is valid, else raises an :class:`_exc.ArgumentError`. A DBAPI connection is passed to the method, in the unlikely event that the dialect needs to interrogate the connection itself to determine this list, however it is expected that most backends will return a hardcoded list of values. If the dialect supports "AUTOCOMMIT", that value should also be present in the sequence returned. The method raises ``NotImplementedError`` by default. If a dialect does not implement this method, then the default dialect will not perform any checking on a given isolation level value before passing it onto the :meth:`.Dialect.set_isolation_level` method. This is to allow backwards-compatibility with third party dialects that may not yet be implementing this method. .. versionadded:: 2.0 Nr� r' rI rI rJ �get_isolation_level_values� s *z"Dialect.get_isolation_level_values)r& r# rP c C s t � �d S rQ r� )rS r& r# rI rI rJ � _assert_and_set_isolation_level� s z'Dialect._assert_and_set_isolation_level� Type[Dialect]c C s | S )a} Given a URL, return the :class:`.Dialect` that will be used. This is a hook that allows an external plugin to provide functionality around an existing dialect, by allowing the plugin to be loaded from the url based on an entrypoint, and then the plugin returns the actual dialect to be used. By default this just returns the cls. rI �r� r� rI rI rJ �get_dialect_cls� s zDialect.get_dialect_clsc C s | � |�S )a� Given a URL, return the :class:`.Dialect` that will be used by an async engine. By default this is an alias of :meth:`.Dialect.get_dialect_cls` and just returns the cls. It may be used if a dialect provides both a sync and async version under the same name, like the ``psycopg`` driver. .. versionadded:: 2 .. seealso:: :meth:`.Dialect.get_dialect_cls` )r- r, rI rI rJ �get_async_dialect_cls� s z Dialect.get_async_dialect_clsc C s dS )aJ set up the provision.py module for this dialect. For dialects that include a provision.py module that sets up provisioning followers, this method should initiate that process. A typical implementation would be:: @classmethod def load_provisioning(cls): __import__("mydialect.provision") The default method assumes a module named ``provision.py`` inside the owning package of the current dialect, based on the ``__module__`` attribute:: @classmethod def load_provisioning(cls): package = ".".join(cls.__module__.split(".")[0:-1]) try: __import__(package + ".provision") except ImportError: pass .. versionadded:: 1.3.14 NrI r� rI rI rJ �load_provisioning s zDialect.load_provisioningr' ��enginerP c C s dS )a_ A convenience hook called before returning the final :class:`_engine.Engine`. If the dialect returned a different class from the :meth:`.get_dialect_cls` method, then the hook is called on both classes, first on the dialect class returned by the :meth:`.get_dialect_cls` method and then on the class on which the method was called. The hook should be used by dialects and/or wrappers to apply special events to the engine or its components. In particular, it allows a dialect-wrapping class to apply dialect-level events. NrI )r� r1 rI rI rJ �engine_created& s zDialect.engine_createdc C s t � �dS )a� Returns the connection object as returned by the external driver package. For normal dialects that use a DBAPI compliant driver this call will just return the ``connection`` passed as argument. For dialects that instead adapt a non DBAPI compliant driver, like when adapting an asyncio driver, this call will return the connection-like object as returned by the driver. .. versionadded:: 1.4.24 Nr� r� rI rI rJ �get_driver_connection7 s z Dialect.get_driver_connection�CoreExecuteOptionsParameter)r1 �optsrP c C s t � �dS )aa Establish execution options for a given engine. This is implemented by :class:`.DefaultDialect` to establish event hooks for new :class:`.Connection` instances created by the given :class:`.Engine` which will then invoke the :meth:`.Dialect.set_connection_execution_options` method for that connection. Nr� )rS r1 r5 rI rI rJ � set_engine_execution_optionsF s z$Dialect.set_engine_execution_options)r� r5 rP c C s t � �dS )a� Establish execution options for a given connection. This is implemented by :class:`.DefaultDialect` in order to implement the :paramref:`_engine.Connection.execution_options.isolation_level` execution option. Dialects can intercept various execution options which may need to modify state on a particular DBAPI connection. .. versionadded:: 1.4 Nr� )rS r� r5 rI rI rJ � set_connection_execution_optionsT s z(Dialect.set_connection_execution_options� Type[Pool]c C s t � �dS )z*return a Pool class to use for a given URLNr� r� rI rI rJ �get_dialect_pool_classc s z Dialect.get_dialect_pool_class)�identrP c C s dS )z=Validates an identifier name, raising an exception if invalidNrI )rS r: rI rI rJ �validate_identifierg s zDialect.validate_identifier)N)N)N)N)N)N)N)N)N)N)N)N)N)N)N)N)N)N)TF)TF)N)N)N)hrA rB rC rL r> rD rE rF rG rH r] r Znon_memoized_propertyr� r� r� r� � EMPTY_DICTr� Z _has_eventsr� r� r� Z bind_typingr� r� � classmethodr� r� r� r r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r r r r r r r r r r r r r r r r r! r r" r$ r% r( r) r* r- r. r/ r2 r3 r6 r7 r9 r; rI rI rI rJ r� s s� � ! !�� �� �� � ����� ��� �� �� �� � � �.� � � � &�"�"� "=5"#, r� c @ sd e Zd ZdZddd�dd�Zddd�dd �Zd dd d �d d�Zddd d�dd�Zdd d�dd�ZdS )�CreateEnginePlugina� A set of hooks intended to augment the construction of an :class:`_engine.Engine` object based on entrypoint names in a URL. The purpose of :class:`_engine.CreateEnginePlugin` is to allow third-party systems to apply engine, pool and dialect level event listeners without the need for the target application to be modified; instead, the plugin names can be added to the database URL. Target applications for :class:`_engine.CreateEnginePlugin` include: * connection and SQL performance tools, e.g. which use events to track number of checkouts and/or time spent with statements * connectivity plugins such as proxies A rudimentary :class:`_engine.CreateEnginePlugin` that attaches a logger to an :class:`_engine.Engine` object might look like:: import logging from sqlalchemy.engine import CreateEnginePlugin from sqlalchemy import event class LogCursorEventsPlugin(CreateEnginePlugin): def __init__(self, url, kwargs): # consume the parameter "log_cursor_logging_name" from the # URL query logging_name = url.query.get( "log_cursor_logging_name", "log_cursor" ) self.log = logging.getLogger(logging_name) def update_url(self, url): "update the URL to one that no longer includes our parameters" return url.difference_update_query(["log_cursor_logging_name"]) def engine_created(self, engine): "attach an event listener after the new Engine is constructed" event.listen(engine, "before_cursor_execute", self._log_event) def _log_event( self, conn, cursor, statement, parameters, context, executemany, ): self.log.info("Plugin logged cursor event: %s", statement) Plugins are registered using entry points in a similar way as that of dialects:: entry_points = { "sqlalchemy.plugins": [ "log_cursor_plugin = myapp.plugins:LogCursorEventsPlugin" ] } A plugin that uses the above names would be invoked from a database URL as in:: from sqlalchemy import create_engine engine = create_engine( "mysql+pymysql://scott:tiger@localhost/test?" "plugin=log_cursor_plugin&log_cursor_logging_name=mylogger" ) The ``plugin`` URL parameter supports multiple instances, so that a URL may specify multiple plugins; they are loaded in the order stated in the URL:: engine = create_engine( "mysql+pymysql://scott:tiger@localhost/test?" "plugin=plugin_one&plugin=plugin_twp&plugin=plugin_three" ) The plugin names may also be passed directly to :func:`_sa.create_engine` using the :paramref:`_sa.create_engine.plugins` argument:: engine = create_engine( "mysql+pymysql://scott:tiger@localhost/test", plugins=["myplugin"] ) .. versionadded:: 1.2.3 plugin names can also be specified to :func:`_sa.create_engine` as a list A plugin may consume plugin-specific arguments from the :class:`_engine.URL` object as well as the ``kwargs`` dictionary, which is the dictionary of arguments passed to the :func:`_sa.create_engine` call. "Consuming" these arguments includes that they must be removed when the plugin initializes, so that the arguments are not passed along to the :class:`_engine.Dialect` constructor, where they will raise an :class:`_exc.ArgumentError` because they are not known by the dialect. As of version 1.4 of SQLAlchemy, arguments should continue to be consumed from the ``kwargs`` dictionary directly, by removing the values with a method such as ``dict.pop``. Arguments from the :class:`_engine.URL` object should be consumed by implementing the :meth:`_engine.CreateEnginePlugin.update_url` method, returning a new copy of the :class:`_engine.URL` with plugin-specific parameters removed:: class MyPlugin(CreateEnginePlugin): def __init__(self, url, kwargs): self.my_argument_one = url.query["my_argument_one"] self.my_argument_two = url.query["my_argument_two"] self.my_argument_three = kwargs.pop("my_argument_three", None) def update_url(self, url): return url.difference_update_query( ["my_argument_one", "my_argument_two"] ) Arguments like those illustrated above would be consumed from a :func:`_sa.create_engine` call such as:: from sqlalchemy import create_engine engine = create_engine( "mysql+pymysql://scott:tiger@localhost/test?" "plugin=myplugin&my_argument_one=foo&my_argument_two=bar", my_argument_three="bat", ) .. versionchanged:: 1.4 The :class:`_engine.URL` object is now immutable; a :class:`_engine.CreateEnginePlugin` that needs to alter the :class:`_engine.URL` should implement the newly added :meth:`_engine.CreateEnginePlugin.update_url` method, which is invoked after the plugin is constructed. For migration, construct the plugin in the following way, checking for the existence of the :meth:`_engine.CreateEnginePlugin.update_url` method to detect which version is running:: class MyPlugin(CreateEnginePlugin): def __init__(self, url, kwargs): if hasattr(CreateEnginePlugin, "update_url"): # detect the 1.4 API self.my_argument_one = url.query["my_argument_one"] self.my_argument_two = url.query["my_argument_two"] else: # detect the 1.3 and earlier API - mutate the # URL directly self.my_argument_one = url.query.pop("my_argument_one") self.my_argument_two = url.query.pop("my_argument_two") self.my_argument_three = kwargs.pop("my_argument_three", None) def update_url(self, url): # this method is only called in the 1.4 version return url.difference_update_query( ["my_argument_one", "my_argument_two"] ) .. seealso:: :ref:`change_5526` - overview of the :class:`_engine.URL` change which also includes notes regarding :class:`_engine.CreateEnginePlugin`. When the engine creation process completes and produces the :class:`_engine.Engine` object, it is again passed to the plugin via the :meth:`_engine.CreateEnginePlugin.engine_created` hook. In this hook, additional changes can be made to the engine, most typically involving setup of events (e.g. those defined in :ref:`core_event_toplevel`). r) r� )r� rY c C s || _ dS )a� Construct a new :class:`.CreateEnginePlugin`. The plugin object is instantiated individually for each call to :func:`_sa.create_engine`. A single :class:`_engine. Engine` will be passed to the :meth:`.CreateEnginePlugin.engine_created` method corresponding to this URL. :param url: the :class:`_engine.URL` object. The plugin may inspect the :class:`_engine.URL` for arguments. Arguments used by the plugin should be removed, by returning an updated :class:`_engine.URL` from the :meth:`_engine.CreateEnginePlugin.update_url` method. .. versionchanged:: 1.4 The :class:`_engine.URL` object is now immutable, so a :class:`_engine.CreateEnginePlugin` that needs to alter the :class:`_engine.URL` object should implement the :meth:`_engine.CreateEnginePlugin.update_url` method. :param kwargs: The keyword arguments passed to :func:`_sa.create_engine`. N)r� )rS r� rY rI rI rJ �__init__ s zCreateEnginePlugin.__init__r� c C s t � �dS )a Update the :class:`_engine.URL`. A new :class:`_engine.URL` should be returned. This method is typically used to consume configuration arguments from the :class:`_engine.URL` which must be removed, as they will not be recognized by the dialect. The :meth:`_engine.URL.difference_update_query` method is available to remove these arguments. See the docstring at :class:`_engine.CreateEnginePlugin` for an example. .. versionadded:: 1.4 Nr� r� rI rI rJ � update_url6 s z CreateEnginePlugin.update_urlr+ rN )� dialect_cls� dialect_argsrP c C s dS )z parse and modify dialect kwargsNrI )rS rA rB rI rI rJ �handle_dialect_kwargsG s z(CreateEnginePlugin.handle_dialect_kwargsr8 )�pool_cls� pool_argsrP c C s dS )z parse and modify pool kwargsNrI )rS rD rE rI rI rJ �handle_pool_kwargsL s z%CreateEnginePlugin.handle_pool_kwargsr' r0 c C s dS )z�Receive the :class:`_engine.Engine` object when it is fully constructed. The plugin may make additional changes to the engine, such as registering engine or connection pool events. NrI )rS r1 rI rI rJ r2 Q s z!CreateEnginePlugin.engine_createdN) rA rB rC rL r? r@ rC rF r2 rI rI rI rJ r> k s 0r> c @ s� e Zd ZU dZded< ded< ded< ded< d ed < d ed < d ed< ded< ded< ded< ded< ded< ded< ded< ded< ded < d ed < eddd d d d d!�d"d#��Zeejfddd d d$d%d&d'd(d d)� d*d+��Z eddd d d d,d d-�d.d/��Z eddd d d d0�d1d2��Z d3d4d5d6d7�d8d9�Z d:d;�d<d=�Z d d;�d>d?�Zd@d;�dAdB�ZdCdDdEdF�dGdH�Zd d;�dIdJ�ZdKd;�dLdM�ZdNdOdP�dQdR�ZdKd;�dSdT�ZdUdKdV�dWdX�Zdd;�dYdZ�Zd[d;�d\d]�Zd dOd^�d_d`�ZdaS )br� zRA messenger object for a Dialect that corresponds to a single execution. r' r1 r& r� Zroot_connectionr� �dialectrW rZ zOptional[Compiled]�compiledrs r zOptional[Executable]�invoked_statement�_AnyMultiExecuteParamsre r\ r� ZisinsertZisupdaterK Z execute_styleri z;util.generic_fn_descriptor[Optional[Sequence[Column[Any]]]]Z prefetch_colsZpostfetch_cols�_ExecuteOptions�execution_optionsr r/ )rG r� r� rL � compiled_ddlrP c C s t � �d S rQ r� )r� rG r� r� rL rM rI rI rJ � _init_ddl� s zExecutionContext._init_ddlr3 �_CoreMultiExecuteParamsr- z&Optional[Sequence[BindParameter[Any]]]r> ) rG r� r� rL rH re rI �extracted_parameters� cache_hitrP c C s t � �d S rQ r� ) r� rG r� r� rL rH re rI rP rQ rI rI rJ �_init_compiled� s z ExecutionContext._init_compiledrh )rG r� r� rL r re rP c C s t � �d S rQ r� )r� rG r� r� rL r re rI rI rJ �_init_statement� s z ExecutionContext._init_statement)rG r� r� rL rP c C s t � �d S rQ r� )r� rG r� r� rL rI rI rJ � _init_default� s z ExecutionContext._init_defaultzOptional[Column[Any]]r7 zOptional[TypeEngine[Any]]r )rq r� �type_rP c C s t � �d S rQ r� )rS rq r� rU rI rI rJ � _exec_default� s z ExecutionContext._exec_defaultz0Optional[List[Tuple[str, Any, TypeEngine[Any]]]]rO c C s t � �d S rQ r� rR rI rI rJ �_prepare_set_input_sizes� s z)ExecutionContext._prepare_set_input_sizesc C s t � �d S rQ r� rR rI rI rJ �_get_cache_stats� s z!ExecutionContext._get_cache_statszCursorResult[Any]c C s t � �d S rQ r� rR rI rI rJ �_setup_result_proxy� s z$ExecutionContext._setup_result_proxy�Sequence_SchemaItemr9 ra )�seqrU rP c C s t � �dS )zKgiven a :class:`.Sequence`, invoke it and return the next int valueNr� )rS r[ rU rI rI rJ � fire_sequence� s z ExecutionContext.fire_sequencec C s t � �dS )z�Return a new cursor generated from this ExecutionContext's connection. Some dialects may wish to change the behavior of connection.cursor(), such as postgresql which may return a PG "server side" cursor. Nr� rR rI rI rJ � create_cursor� s z ExecutionContext.create_cursorrN c C s t � �dS )z�Called before an execution of a compiled statement. If a compiled statement was passed to this ExecutionContext, the `statement` and `parameters` datamembers must be initialized after this statement is complete. Nr� rR rI rI rJ �pre_exec s zExecutionContext.pre_execr� rk )�out_param_namesrP c C s t � �dS )a! Return a sequence of OUT parameter values from a cursor. For dialects that support OUT parameters, this method will be called when there is a :class:`.SQLCompiler` object which has the :attr:`.SQLCompiler.has_out_parameters` flag set. This flag in turn will be set to True if the statement itself has :class:`.BindParameter` objects that have the ``.isoutparam`` flag set which are consumed by the :meth:`.SQLCompiler.visit_bindparam` method. If the dialect compiler produces :class:`.BindParameter` objects with ``.isoutparam`` set which are not handled by :meth:`.SQLCompiler.visit_bindparam`, it should set this flag explicitly. The list of names that were rendered for each bound parameter is passed to the method. The method should then return a sequence of values corresponding to the list of parameter objects. Unlike in previous SQLAlchemy versions, the values can be the **raw values** from the DBAPI; the execution context will apply the appropriate type handler based on what's present in self.compiled.binds and update the values. The processed dictionary will then be made available via the ``.out_parameters`` collection on the result object. Note that SQLAlchemy 1.4 has multiple kinds of result object as part of the 2.0 transition. .. versionadded:: 1.4 - added :meth:`.ExecutionContext.get_out_parameter_values`, which is invoked automatically by the :class:`.DefaultExecutionContext` when there are :class:`.BindParameter` objects with the ``.isoutparam`` flag set. This replaces the practice of setting out parameters within the now-removed ``get_result_proxy()`` method. Nr� )rS r_ rI rI rJ �get_out_parameter_values s "z)ExecutionContext.get_out_parameter_valuesc C s t � �dS )a Called after the execution of a compiled statement. If a compiled statement was passed to this ExecutionContext, the `last_insert_ids`, `last_inserted_params`, etc. datamembers should be available after this method completes. Nr� rR rI rI rJ � post_exec8 s zExecutionContext.post_exec� BaseException)r rP c C s t � �dS )zQReceive a DBAPI exception which occurred upon execute, result fetch, etc.Nr� )rS r rI rI rJ �handle_dbapi_exceptionB s z'ExecutionContext.handle_dbapi_exceptionc C s t � �dS )zjReturn True if the last INSERT or UPDATE row contained inlined or database-side defaults. Nr� rR rI rI rJ �lastrow_has_defaultsH s z%ExecutionContext.lastrow_has_defaultsr� c C s t � �dS )z�Return the DBAPI ``cursor.rowcount`` value, or in some cases an interpreted value. See :attr:`_engine.CursorResult.rowcount` for details on this. Nr� rR rI rI rJ � get_rowcountO s z ExecutionContext.get_rowcount)rZ rP c C s t � �dS )a For a RETURNING result, deliver cursor.fetchall() from the DBAPI cursor. This is a dialect-specific hook for dialects that have special considerations when calling upon the rows delivered for a "RETURNING" statement. Default implementation is ``cursor.fetchall()``. This hook is currently used only by the :term:`insertmanyvalues` feature. Dialects that don't set ``use_insertmanyvalues=True`` don't need to consider this hook. .. versionadded:: 2.0.10 Nr� )rS rZ rI rI rJ �fetchall_for_returningY s z'ExecutionContext.fetchall_for_returningN)rA rB rC rL r] r= rN r> rF rR rS rT rV rW rX rY r\ r] r^ r` ra rc rd re rf rI rI rI rJ r� [ sP �$ $ r� c @ s e Zd ZU dZded< dS )�ConnectionEventsTargetz�An object which can accept events from :class:`.ConnectionEvents`. Includes :class:`_engine.Connection` and :class:`_engine.Engine`. .. versionadded:: 2.0 z"dispatcher[ConnectionEventsTarget]r� Nr� rI rI rI rJ rg l s rg c @ s~ e Zd ZU dZdZded< ded< ded< d ed < d ed < d ed< ded< ded< ded< ded< ded< ded< ded< dS ) �ExceptionContexta Encapsulate information about an error condition in progress. This object exists solely to be passed to the :meth:`_events.DialectEvents.handle_error` event, supporting an interface that can be extended without backwards-incompatibility. rI r� rG zOptional[Connection]r� zOptional[Engine]r1 r rZ r� r z Optional[_DBAPIAnyExecuteParams]re rb Zoriginal_exceptionzOptional[StatementError]Zsqlalchemy_exceptionzOptional[BaseException]Zchained_exceptionr Zexecution_contextr\ r Z invalidate_pool_on_disconnectZ is_pre_pingN)rA rB rC rL � __slots__r] rI rI rI rJ rh { s rh c @ sN e Zd ZU dZdZded< edd�dd��Zdd d �d d �Zd d�dd�Z dS )�AdaptedConnectionz�Interface of an adapted connection object to support the DBAPI protocol. Used by asyncio dialects to provide a sync-style pep-249 facade on top of the asyncio connection/cursor API provided by the driver. .. versionadded:: 1.4.24 �� _connectionr rl rO c C s | j S )z@The connection object as returned by the driver after a connect.rk rR rI rI rJ �driver_connection/ s z#AdaptedConnection.driver_connectionz Callable[[Any], Awaitable[_T]]r< )�fnrP c C s t || j��S )aA Run the awaitable returned by the given function, which is passed the raw asyncio driver connection. This is used to invoke awaitable-only methods on the driver connection within the context of a "synchronous" method, like a connection pool event handler. E.g.:: engine = create_async_engine(...) @event.listens_for(engine.sync_engine, "connect") def register_custom_types( dbapi_connection, # ... ): dbapi_connection.run_async( lambda connection: connection.set_type_codec( "MyCustomType", encoder, decoder, ... ) ) .. versionadded:: 1.4.30 .. seealso:: :ref:`asyncio_events_run_async` )r rl )rS rn rI rI rJ � run_async4 s zAdaptedConnection.run_asyncrs c C s d| j S )Nz<AdaptedConnection %s>rk rR rI rI rJ �__repr__T s zAdaptedConnection.__repr__N) rA rB rC rL ri r] ry rm ro rp rI rI rI rJ rj ! s rj N)rL � __future__r �enumr �typesr �typingr r r r r r r r r r r r r r r r r r r � r �eventr �poolr r Z sql.compilerr r r Zutil.concurrencyr Z util.typingr! r" r# r$ �baser& r' rZ r( r� r) r* r+ �excr, Zsqlr- r. r/ r0 r1 r2 r3 Z sql.elementsr4 r5 Z sql.schemar6 r7 r8 rZ Z sql.sqltypesr9 Z sql.type_apir: r; rs r� r< r> rK rM r^ rW Z_CoreSingleExecuteParamsZ _MutableCoreSingleExecuteParamsrO Z_CoreAnyExecuteParamsZ_DBAPISingleExecuteParamsrh Z_DBAPIAnyExecuteParamsra r\ r_ Z_AnySingleExecuteParamsrJ Z_AnyExecuteParamsZCompiledCacheTypeZSchemaTranslateMapTypeZ_ImmutableExecuteOptionsZ _ParamStyler� r r~ rK r4 r� r� r� r� r� r� r� r� r� r� r� ZVersionInfoTypeZTableKeyr� r> r� rg Z Connectablerh rj rI rI rI rJ �<module> s, C ������ �� �.:4 < q ' sqlalchemy/engine/__pycache__/mock.cpython-39.pyc 0000644 00000011267 15125143220 0015747 0 ustar 00 a ��Jh< � @ s d dl mZ d dlmZ d dlZd dlmZ d dlmZ d dlmZ d dlmZ d dlm Z d d lm Z d d l m Z d d l mZ ejr�d dlmZ d dlmZ d dlmZ d dlmZ d dl mZ d dlmZ d dlmZ d dlm Z d dl m Z G dd� d�Z ddddd�d d �Z dS ) � )� annotations)� attrgetterN)�Any)�Callable)�cast)�Optional)�Type)�Union� )�url� )�util)�Engine)�_CoreAnyExecuteParams)�CoreExecuteOptionsParameter)�Dialect)�URL)� Executable)� InvokeDDLBase)� HasSchemaAttr)� Visitablec @ s� e Zd ZU ddd�dd�Zeeedd� ��Zded < eeee d ���Z ded < eeed d� ��Z d ed< dd d�dd�Z ddd�dd�Z dd d�dd�Zdd dd d �d d �Zd(d"d#d$dd%�d&d'�Zd!S ))�MockConnectionr zCallable[..., Any])�dialect�executec C s || _ || _d S �N)�_dialect� _execute_impl)�selfr r � r �K/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/engine/mock.py�__init__$ s zMockConnection.__init__c C s | S r r ��sr r r �<lambda>( � zMockConnection.<lambda>r �enginer r c C s | j jS r )r �namer! r r r r# * r$ �strr& r )�kwargs�returnc K s | S r r )r r( r r r �connect, s zMockConnection.connectr z Optional[str])�objr) c C s |j S r )Zschema)r r+ r r r �schema_for_object/ s z MockConnection.schema_for_object)�kwr) c K s | S r r )r r- r r r �execution_options2 s z MockConnection.execution_optionszType[InvokeDDLBase]r �None)�visitorcallable�elementr( r) c K s( d|d< |f | j | d�|���|� d S )NFZ checkfirst)r � connection)r Ztraverse_single)r r0 r1 r( r r r �_run_ddl_visitor5 s ���z MockConnection._run_ddl_visitorNr z Optional[_CoreAnyExecuteParams]z%Optional[CoreExecuteOptionsParameter])r+ � parametersr. r) c C s | � ||�S r )r )r r+ r4 r. r r r r @ s zMockConnection.execute)NN)�__name__� __module__� __qualname__r r r �propertyr% �__annotations__r r r& r* r, r. r3 r r r r r r # s �r zUnion[str, URL]r )r �executorr- r) c K sT t �| �}|�� }i }t�|�D ]}||v r |�|�||< q |f i |��}t||�S )a? Create a "mock" engine used for echoing DDL. This is a utility function used for debugging or storing the output of DDL sequences as generated by :meth:`_schema.MetaData.create_all` and related methods. The function accepts a URL which is used only to determine the kind of dialect to be used, as well as an "executor" callable function which will receive a SQL expression object and parameters, which can then be echoed or otherwise printed. The executor's return value is not handled, nor does the engine allow regular string statements to be invoked, and is therefore only useful for DDL that is sent to the database without receiving any results. E.g.:: from sqlalchemy import create_mock_engine def dump(sql, *multiparams, **params): print(sql.compile(dialect=engine.dialect)) engine = create_mock_engine("postgresql+psycopg2://", dump) metadata.create_all(engine, checkfirst=False) :param url: A string URL which typically needs to contain only the database backend name. :param executor: a callable which receives the arguments ``sql``, ``*multiparams`` and ``**params``. The ``sql`` parameter is typically an instance of :class:`.ExecutableDDLElement`, which can then be compiled into a string using :meth:`.ExecutableDDLElement.compile`. .. versionadded:: 1.4 - the :func:`.create_mock_engine` function replaces the previous "mock" engine strategy used with :func:`_sa.create_engine`. .. seealso:: :ref:`faq_ddl_as_string` )�_urlZmake_url� get_dialectr Zget_cls_kwargs�popr )r r: r- �uZ dialect_clsZ dialect_args�kr r r r �create_mock_engineI s 0 r@ )!� __future__r �operatorr �typingr r r r r r � r r; r � TYPE_CHECKING�baser Z interfacesr r r r Zsql.baser Zsql.ddlr Z sql.schemar Z sql.visitorsr r r@ r r r r �<module> s, & sqlalchemy/engine/__pycache__/_py_util.cpython-39.pyc 0000644 00000002717 15125143220 0016642 0 ustar 00 a ��Jh� � @ s� U d dl mZ d dlZd dlmZ d dlmZ d dlmZ d dlmZ ddlmZ ej r�d d l m Z d d l m Z d d l m Z d d l mZ dZded< ddd�dd�Zddd�dd�ZdS )� )� annotationsN)�Any)�Mapping)�Optional)�Tuple� )�exc� )�_CoreAnyExecuteParams)�_CoreMultiExecuteParams)�_DBAPIAnyExecuteParams)�_DBAPIMultiExecuteParams� zTuple[Any, ...]� _no_tuplez Optional[_CoreAnyExecuteParams]r )�params�returnc C sl | d u r t S t| t�s t| t�rD| r@t| d ttf�s@t�d��| S t| t�sXt| t�r^| gS t�d��d S )Nr �9List argument must consist only of tuples or dictionariesz'mapping or list expected for parameters�r � isinstance�list�tupler r � ArgumentError�dict�r r r �O/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/engine/_py_util.py�_distill_params_20 s � �r z Optional[_DBAPIAnyExecuteParams]r c C sf | d u r t S t| t�r:| r6t| d ttf�s6t�d��| S t| ttf�sRt| t�rX| gS t�d��d S )Nr r z+mapping or sequence expected for parametersr r r r r �_distill_raw_params4 s ��r )� __future__r �typingr r r r � r � TYPE_CHECKINGZ interfacesr r r r r �__annotations__r r r r r r �<module> s sqlalchemy/engine/__pycache__/url.cpython-39.pyc 0000644 00000064374 15125143220 0015627 0 ustar 00 a ��Jh[y � @ s` d Z ddlmZ ddlmZ ddlZddlmZ ddlm Z ddlm Z ddlm Z ddlm Z dd lm Z dd lmZ dd lmZ dd lmZ dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddl m Z ddl m Z ddl m Z ddl m!Z! G d d � d e�Z"d d d �d d!�Z#d"d d#�d$d%�Z$dS )&a Provides the :class:`~sqlalchemy.engine.url.URL` class which encapsulates information about a database connection specification. The URL object is created automatically when :func:`~sqlalchemy.engine.create_engine` is called with a string argument; alternatively, the URL is a public-facing construct which can be used directly and is also accepted directly by ``create_engine()``. � )� annotationsN)�Any)�cast)�Dict)�Iterable)�List)�Mapping)� NamedTuple)�Optional)�overload)�Sequence)�Tuple)�Type)�Union)� parse_qsl)�quote)� quote_plus)�unquote� )�Dialect� )�exc)�util)�plugins)�registryc @ sD e Zd ZU dZded< ded< ded< ded< ded < ded < d ed < ed d d d d ejfdddddddd d�dd��Zeddd�dd��Z edddd�dd��Z edddd�dd��Z edd d�d d ��Z deddddddd d d�d d �Z d!d d"�d#d$�Zdfdd&d d'�d(d)�Zdgd*d&d d+�d,d-�Zdhd.d&d d/�d0d1�Zd2d d3�d4d5�Zed6d7�d8d9��Ze�d:d;�did&dd=�d>d?��Zdjd&dd=�d@dA�Zdd7�dBdC�Zd d7�dDdE�Zd!d dF�dGdH�ZdId7�dJdK�Zd!d&dL�dMdN�Z d!d&dL�dOdP�Z dd7�dQdR�Z dd7�dSdT�Z dUdVdW�dXdY�Z dZd7�d[d\�Z!dkd&dZd]�d^d_�Z"dld`d!dadb�dcdd�Z#d S )m�URLa� Represent the components of a URL used to connect to a database. URLs are typically constructed from a fully formatted URL string, where the :func:`.make_url` function is used internally by the :func:`_sa.create_engine` function in order to parse the URL string into its individual components, which are then used to construct a new :class:`.URL` object. When parsing from a formatted URL string, the parsing format generally follows `RFC-1738 <https://www.ietf.org/rfc/rfc1738.txt>`_, with some exceptions. A :class:`_engine.URL` object may also be produced directly, either by using the :func:`.make_url` function with a fully formed URL string, or by using the :meth:`_engine.URL.create` constructor in order to construct a :class:`_engine.URL` programmatically given individual fields. The resulting :class:`.URL` object may be passed directly to :func:`_sa.create_engine` in place of a string argument, which will bypass the usage of :func:`.make_url` within the engine's creation process. .. versionchanged:: 1.4 The :class:`_engine.URL` object is now an immutable object. To create a URL, use the :func:`_engine.make_url` or :meth:`_engine.URL.create` function / method. To modify a :class:`_engine.URL`, use methods like :meth:`_engine.URL.set` and :meth:`_engine.URL.update_query_dict` to return a new :class:`_engine.URL` object with modifications. See notes for this change at :ref:`change_5526`. .. seealso:: :ref:`database_urls` :class:`_engine.URL` contains the following attributes: * :attr:`_engine.URL.drivername`: database backend and driver name, such as ``postgresql+psycopg2`` * :attr:`_engine.URL.username`: username string * :attr:`_engine.URL.password`: password string * :attr:`_engine.URL.host`: string hostname * :attr:`_engine.URL.port`: integer port number * :attr:`_engine.URL.database`: string database name * :attr:`_engine.URL.query`: an immutable mapping representing the query string. contains strings for keys and either strings or tuples of strings for values. �str� drivernamez Optional[str]�username�password�hostz Optional[int]�port�databasez4util.immutabledict[str, Union[Tuple[str, ...], str]]�queryNz'Mapping[str, Union[Sequence[str], str]])r r r r r! r" r# �returnc C s@ | | � |d�| �|d�|| �|d�| �|�| �|d�| �|��S )a� Create a new :class:`_engine.URL` object. .. seealso:: :ref:`database_urls` :param drivername: the name of the database backend. This name will correspond to a module in sqlalchemy/databases or a third party plug-in. :param username: The user name. :param password: database password. Is typically a string, but may also be an object that can be stringified with ``str()``. .. note:: The password string should **not** be URL encoded when passed as an argument to :meth:`_engine.URL.create`; the string should contain the password characters exactly as they would be typed. .. note:: A password-producing object will be stringified only **once** per :class:`_engine.Engine` object. For dynamic password generation per connect, see :ref:`engines_dynamic_tokens`. :param host: The name of the host. :param port: The port number. :param database: The database name. :param query: A dictionary of string keys to string values to be passed to the dialect and/or the DBAPI upon connect. To specify non-string parameters to a Python DBAPI directly, use the :paramref:`_sa.create_engine.connect_args` parameter to :func:`_sa.create_engine`. See also :attr:`_engine.URL.normalized_query` for a dictionary that is consistently string->list of string. :return: new :class:`_engine.URL` object. .. versionadded:: 1.4 The :class:`_engine.URL` object is now an **immutable named tuple**. In addition, the ``query`` dictionary is also immutable. To create a URL, use the :func:`_engine.url.make_url` or :meth:`_engine.URL.create` function/ method. To modify a :class:`_engine.URL`, use the :meth:`_engine.URL.set` and :meth:`_engine.URL.update_query` methods. r r r r" )� _assert_str�_assert_none_str� _assert_port� _str_dict)�clsr r r r r! r" r# � r* �J/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/engine/url.py�create� s 8 �z URL.create)r! r$ c C s6 |d u r d S z t |�W S ty0 td��Y n0 d S )Nz(Port argument must be an integer or None)�int� TypeError)r) r! r* r* r+ r' � s zURL._assert_port)�v� paramnamer$ c C s t |t�std| ��|S )Nz%s must be a string�� isinstancer r. �r) r/ r0 r* r* r+ r% � s zURL._assert_strc C s |d u r |S | � ||�S �N)r% r3 r* r* r+ r& � s zURL._assert_none_strziOptional[Union[Sequence[Tuple[str, Union[Sequence[str], str]]], Mapping[str, Union[Sequence[str], str]]]])�dict_r$ c s� |d u rt jS tddd�dd���tddd�dd���ddd��fd d� �ddd �d d �� t|tj�rl|}n|�� }t �� �fd d�|D ��S )Nr )�valr$ c S s d S r4 r* �r6 r* r* r+ � _assert_value� s z$URL._str_dict.<locals>._assert_valuez Sequence[str]zUnion[str, Tuple[str, ...]]c S s d S r4 r* r7 r* r* r+ r8 s zUnion[str, Sequence[str]]c s< t | t�r| S t | tj�r0t� fdd�| D ��S td��d S )Nc 3 s | ]}� |�V qd S r4 r* )�.0�elem�r8 r* r+ � <genexpr> � z7URL._str_dict.<locals>._assert_value.<locals>.<genexpr>z?Query dictionary values must be strings or sequences of strings)r2 r �collections_abcr �tupler. r7 r; r* r+ r8 s �)r/ r$ c S s t | t�std��| S )Nz%Query dictionary keys must be stringsr1 )r/ r* r* r+ r% s z"URL._str_dict.<locals>._assert_strc s i | ]\}}� |��|��qS r* r* )r9 �key�value�r% r8 r* r+ � <dictcomp>" s ��z!URL._str_dict.<locals>.<dictcomp>)r � EMPTY_DICTr r2 r> r �items� immutabledict)r) r5 � dict_itemsr* rB r+ r( � s ��z URL._str_dictz1Optional[Mapping[str, Union[Sequence[str], str]]]c C s� i }|dur||d< |dur$||d< |dur4||d< |durD||d< |durT||d< |durd||d< |durt||d< | j f i |��S ) a return a new :class:`_engine.URL` object with modifications. Values are used if they are non-None. To set a value to ``None`` explicitly, use the :meth:`_engine.URL._replace` method adapted from ``namedtuple``. :param drivername: new drivername :param username: new username :param password: new password :param host: new hostname :param port: new port :param query: new query parameters, passed a dict of string keys referring to string or sequence of string values. Fully replaces the previous list of arguments. :return: new :class:`_engine.URL` object. .. versionadded:: 1.4 .. seealso:: :meth:`_engine.URL.update_query_dict` Nr r r r r! r" r# )�_assert_replace) �selfr r r r r! r" r# �kwr* r* r+ �set* s #zURL.setr )rJ r$ c K sz d|v r| � |d d� dD ] }||v r | �|| |� q d|v rP| �|d � d|v rj| �|d �|d< | jf i |��S )z)argument checks before calling _replace()r )r r r" r! r# )r% r& r' r( �_replace)rI rJ �namer* r* r+ rH _ s zURL._assert_replaceF�bool)� query_string�appendr$ c C s | j t|�|d�S )ak Return a new :class:`_engine.URL` object with the :attr:`_engine.URL.query` parameter dictionary updated by the given query string. E.g.:: >>> from sqlalchemy.engine import make_url >>> url = make_url("postgresql+psycopg2://user:pass@host/dbname") >>> url = url.update_query_string( ... "alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt" ... ) >>> str(url) 'postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt' :param query_string: a URL escaped query string, not including the question mark. :param append: if True, parameters in the existing query string will not be removed; new parameters will be in addition to those present. If left at its default of False, keys present in the given query parameters will replace those of the existing query string. .. versionadded:: 1.4 .. seealso:: :attr:`_engine.URL.query` :meth:`_engine.URL.update_query_dict` �rP )�update_query_pairsr )rI rO rP r* r* r+ �update_query_stringn s !zURL.update_query_stringz+Iterable[Tuple[str, Union[str, List[str]]]])�key_value_pairsrP r$ c s | j � i }|D ]\\}}||v rLt�|| �||< td|| ��tt|�� qt|ttf�rbt|�n|||< q|r�i }|D ]>}|� v r�tt�� | �t�|| � �||< qx|| ||< qx|� � fdd�t � �� |�D �� n| j � dd� |� � D ��}| j |d�S )a Return a new :class:`_engine.URL` object with the :attr:`_engine.URL.query` parameter dictionary updated by the given sequence of key/value pairs E.g.:: >>> from sqlalchemy.engine import make_url >>> url = make_url("postgresql+psycopg2://user:pass@host/dbname") >>> url = url.update_query_pairs( ... [ ... ("alt_host", "host1"), ... ("alt_host", "host2"), ... ("ssl_cipher", "/path/to/crt"), ... ] ... ) >>> str(url) 'postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt' :param key_value_pairs: A sequence of tuples containing two strings each. :param append: if True, parameters in the existing query string will not be removed; new parameters will be in addition to those present. If left at its default of False, keys present in the given query parameters will replace those of the existing query string. .. versionadded:: 1.4 .. seealso:: :attr:`_engine.URL.query` :meth:`_engine.URL.difference_update_query` :meth:`_engine.URL.set` � List[str]c s i | ]}|� | �qS r* r* )r9 �k�Zexisting_queryr* r+ rC � s �z*URL.update_query_pairs.<locals>.<dictcomp>c S s( i | ] \}}|t |t�r t|�n|�qS r* )r2 �listr? �r9 rV r/ r* r* r+ rC � s ��r# )r# r �to_listr rP r r2 rX r? �updaterK � difference�unionrE )rI rT rP Znew_keysr@ rA Z new_queryrV r* rW r+ rR � s: + � �� ����zURL.update_query_pairsz#Mapping[str, Union[str, List[str]]])�query_parametersrP r$ c C s | j |�� |d�S )a� Return a new :class:`_engine.URL` object with the :attr:`_engine.URL.query` parameter dictionary updated by the given dictionary. The dictionary typically contains string keys and string values. In order to represent a query parameter that is expressed multiple times, pass a sequence of string values. E.g.:: >>> from sqlalchemy.engine import make_url >>> url = make_url("postgresql+psycopg2://user:pass@host/dbname") >>> url = url.update_query_dict( ... {"alt_host": ["host1", "host2"], "ssl_cipher": "/path/to/crt"} ... ) >>> str(url) 'postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt' :param query_parameters: A dictionary with string keys and values that are either strings, or sequences of strings. :param append: if True, parameters in the existing query string will not be removed; new parameters will be in addition to those present. If left at its default of False, keys present in the given query parameters will replace those of the existing query string. .. versionadded:: 1.4 .. seealso:: :attr:`_engine.URL.query` :meth:`_engine.URL.update_query_string` :meth:`_engine.URL.update_query_pairs` :meth:`_engine.URL.difference_update_query` :meth:`_engine.URL.set` rQ )rR rE )rI r_ rP r* r* r+ �update_query_dict� s 1zURL.update_query_dictz Iterable[str])�namesr$ c sT t |��� j�s� S t� j� j� j� j� j� j t � � fdd�t � j�� |�D ���S )a� Remove the given names from the :attr:`_engine.URL.query` dictionary, returning the new :class:`_engine.URL`. E.g.:: url = url.difference_update_query(["foo", "bar"]) Equivalent to using :meth:`_engine.URL.set` as follows:: url = url.set( query={ key: url.query[key] for key in set(url.query).difference(["foo", "bar"]) } ) .. versionadded:: 1.4 .. seealso:: :attr:`_engine.URL.query` :meth:`_engine.URL.update_query_dict` :meth:`_engine.URL.set` c s i | ]}|� j | �qS r* rZ )r9 r@ �rI r* r+ rC @ s �z/URL.difference_update_query.<locals>.<dictcomp>) rK � intersectionr# r r r r r r! r" r rF r] )rI ra r* rb r+ �difference_update_query s ���zURL.difference_update_queryzMapping[str, Sequence[str]])r$ c C s t �dd� | j�� D ��S )a& Return the :attr:`_engine.URL.query` dictionary with values normalized into sequences. As the :attr:`_engine.URL.query` dictionary may contain either string values or sequences of string values to differentiate between parameters that are specified multiple times in the query string, code that needs to handle multiple parameters generically will wish to use this attribute so that all parameters present are presented as sequences. Inspiration is from Python's ``urllib.parse.parse_qs`` function. E.g.:: >>> from sqlalchemy.engine import make_url >>> url = make_url( ... "postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt" ... ) >>> url.query immutabledict({'alt_host': ('host1', 'host2'), 'ssl_cipher': '/path/to/crt'}) >>> url.normalized_query immutabledict({'alt_host': ('host1', 'host2'), 'ssl_cipher': ('/path/to/crt',)}) c S s& i | ] \}}|t |t�s |fn|�qS r* )r2 r? rY r* r* r+ rC a s �z(URL.normalized_query.<locals>.<dictcomp>)r rF r# rE rb r* r* r+ �normalized_queryG s ��zURL.normalized_query�1.4z�The :meth:`_engine.URL.__to_string__ method is deprecated and will be removed in a future release. Please use the :meth:`_engine.URL.render_as_string` method.T)� hide_passwordr$ c C s | j |d�S )z�Render this :class:`_engine.URL` object as a string. :param hide_password: Defaults to True. The password is not shown in the string unless this is set to False. )rg ��render_as_string)rI rg r* r* r+ � __to_string__g s zURL.__to_string__c s� � j d }� jdurZ|t� jdd�7 }� jdurR|d|r<dntt� j�dd� 7 }|d7 }� jdur�d� jv r�|d� j� d �7 }n |� j7 }� jdur�|dt� j� 7 }� jdur�|d � j 7 }� jr�t � j�}|� � |d d � � fd d�|D �� 7 }|S )aR Render this :class:`_engine.URL` object as a string. This method is used when the ``__str__()`` or ``__repr__()`` methods are used. The method directly includes additional options. :param hide_password: Defaults to True. The password is not shown in the string unless this is set to False. z://Nz +)�safe�:z***�@�[�]�/�?�&c 3 s: | ]2}t �� j| �D ] }t|�� d t|�� �V qqdS )�=N)r r[ r# r )r9 rV �elementrb r* r+ r< � s �z'URL.render_as_string.<locals>.<genexpr>) r r r r r r r! r" r# rX �sort�join)rI rg �s�keysr* rb r+ ri v s2 �� � zURL.render_as_stringc C s | � � S r4 rh rb r* r* r+ �__repr__� s z URL.__repr__c C s& | j �| j| j| j| j| j| j| j�S r4 ) � __class__r, r r r r r! r" r# rb r* r* r+ �__copy__� s �z URL.__copy__)�memor$ c C s | � � S r4 )r{ )rI r| r* r* r+ � __deepcopy__� s zURL.__deepcopy__r- c C s t t| ��S r4 )�hashr rb r* r* r+ �__hash__� s z URL.__hash__)�otherr$ c C s^ t |t�o\| j|jko\| j|jko\| j|jko\| j|jko\| j|jko\| j|jko\| j|jkS r4 ) r2 r r r r r r" r# r! �rI r� r* r* r+ �__eq__� s � � � � � � �z URL.__eq__c C s | |k S r4 r* r� r* r* r+ �__ne__� s z URL.__ne__c C s$ d| j vr| j S | j �d�d S dS )z�Return the backend name. This is the name that corresponds to the database backend in use, and is the portion of the :attr:`_engine.URL.drivername` that is to the left of the plus sign. �+r N)r �splitrb r* r* r+ �get_backend_name� s zURL.get_backend_namec C s( d| j vr| �� jS | j �d�d S dS )a� Return the backend name. This is the name that corresponds to the DBAPI driver in use, and is the portion of the :attr:`_engine.URL.drivername` that is to the right of the plus sign. If the :attr:`_engine.URL.drivername` does not include a plus sign, then the default :class:`_engine.Dialect` for this :class:`_engine.URL` is imported in order to get the driver name. r� r N)r � get_dialectZdriverr� rb r* r* r+ �get_driver_name� s zURL.get_driver_namezMapping[str, Any]z%Tuple[URL, List[Any], Dict[str, Any]])�kwargsr$ c s� t ��j�dd��}|� �dg �7 }t� �� � �fdd�|D �}��ddg�}|D ]}|�|�}|d urR|}qR� �dd � ||� fS )N�pluginr* r c s g | ]}t �|��� ��qS r* )r �load)r9 Z plugin_name�r� rI r* r+ � <listcomp>� s �z,URL._instantiate_plugins.<locals>.<listcomp>)r r[ r# �get�dictrd Z update_url�pop)rI r� Z plugin_namesZloaded_plugins�ur� Znew_ur* r� r+ �_instantiate_plugins� s � zURL._instantiate_plugins� Type[Dialect]c C s` d| j vr| j }n| j �dd�}t�|�}t|d�rRt|jt�rRt|jt �rR|jS t d|�S dS )z�Return the "entry point" dialect class. This is normally the dialect itself except in the case when the returned class implements the get_dialect_cls() method. r� �.�dialectr� N) r �replacer r� �hasattrr2 r� �type� issubclassr r )rI rM r) r* r* r+ �_get_entrypoint� s � � �zURL._get_entrypoint)� _is_asyncr$ c C s& | � � }|r|�| �}n |�| �}|S )zoReturn the SQLAlchemy :class:`_engine.Dialect` class corresponding to this URL's driver name. )r� Zget_async_dialect_clsZget_dialect_cls)rI r� Z entrypointZ dialect_clsr* r* r+ r� s zURL.get_dialectzOptional[List[str]]zDict[str, Any])ra rJ r$ c K s� |durt �dd� i }g d�}|D ]h}|r8|�d�}n||v rJ|| }n|}|dur$t| |d�r$|dkr~tt| |��||< q$t| |�||< q$|S )a2 Translate url attributes into a dictionary of connection arguments. Returns attributes of this url (`host`, `database`, `username`, `password`, `port`) as a plain dictionary. The attribute names are used as the keys by default. Unset or false attributes are omitted from the final dictionary. :param \**kw: Optional, alternate key names for url attributes. :param names: Deprecated. Same purpose as the keyword-based alternate names, but correlates the name to the original positionally. NzpThe `URL.translate_connect_args.name`s parameter is deprecated. Please pass the alternate names as kw arguments.rf )r r" r r r! r Fr )r Zwarn_deprecatedr� �getattrr )rI ra rJ Z translatedZattribute_namesZsnamerM r* r* r+ �translate_connect_args s$ � zURL.translate_connect_args)NNNNNNN)F)F)F)T)T)F)N)$�__name__� __module__� __qualname__�__doc__�__annotations__� classmethodr rD r, r' r% r& r( rK rH rS rR r` rd �propertyre � deprecatedrj ri ry r{ r} r r� r� r� r� r� r� r� r� r* r* r* r+ r . sz 2 � A9 � 5 �& �V �30 � ' �r zUnion[str, URL])� name_or_urlr$ c C s@ t | t�rt| �S t | t�s8t| d�s8t�d| ����n| S dS )a� Given a string, produce a new URL instance. The format of the URL generally follows `RFC-1738 <https://www.ietf.org/rfc/rfc1738.txt>`_, with some exceptions, including that underscores, and not dashes or periods, are accepted within the "scheme" portion. If a :class:`.URL` object is passed, it is returned as is. .. seealso:: :ref:`database_urls` Z)_sqla_is_testing_if_this_is_a_mock_objectz#Expected string or URL object, got N)r2 r � _parse_urlr r� r � ArgumentError)r� r* r* r+ �make_urlG s ��r� r )rM r$ c C s2 t �dt j�}|�| �}|d u�r$|�� }|d d ur�i }t|d �D ]@\}}||v r~t�|| �||< td|| �� |� qF|||< qFnd }||d< |d d ur�t |d �|d< |d d ur�t |d �|d< |� d�}|� d�}|p�||d< |� d �} |d �rt |d �|d < t j| fi |��S t�d ��d S ) Na� (?P<name>[\w\+]+):// (?: (?P<username>[^:/]*) (?::(?P<password>[^@]*))? @)? (?: (?: \[(?P<ipv6host>[^/\?]+)\] | (?P<ipv4host>[^/:\?]+) )? (?::(?P<port>[^/\?]*))? )? (?:/(?P<database>[^\?]*))? (?:\?(?P<query>.*))? r# rU r r �ipv4host�ipv6hostr rM r! z4Could not parse SQLAlchemy URL from given URL string)�re�compile�X�match� groupdictr r r[ r rP r r� r- r r, r r� ) rM �pattern�m� componentsr# r@ rA r� r� r* r* r+ r� c s< � �r� )%r� � __future__r �collections.abc�abcr> r� �typingr r r r r r r r r r r r r � urllib.parser r r r Z interfacesr � r r Zdialectsr r r r� r� r* r* r* r+ �<module> sD sqlalchemy/engine/__pycache__/result.cpython-39.pyc 0000644 00000222351 15125143220 0016332 0 ustar 00 a ��Jh�/ � @ s d Z ddlmZ ddlmZ ddlZddlZddlZddlZddlm Z ddlm Z ddlm Z ddlm Z dd lm Z dd lmZ dd lmZ dd lmZ dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z ddlm Z ddl m Z dd l m Z dd l!m"Z" dd l!m#Z# dd l!m$Z$ dd l m%Z% dd!l m&Z& dd"l'm(Z( dd#l)m*Z* dd$l)m+Z+ ej�s�e(�s�dd%l,m-Z- n dd%l.m-Z- ej�r�dd&l/m0Z0 dd'l1m2Z2 ee3d(f Z4ee4e5f Z6e Z7ee4e7f Z8ee e e e f Z9ee d)f Z:ed*e9d+�Z;ed,e d+�Z<ed-ee d)f d+�Z=ee;e:f Z>ee e e f Z?eed. Z@e ee gee f ZAe e ge f ZBeee eeB f ZCG d/d0� d0�ZDG d1d2� d2ejEe �ZFG d3d4� d4eD�ZGdWd5d6d7d8�d9d:�ZHG d;d<� d<e�ZIeIjJZJG d=d>� d>e$e e; �ZKG d?d@� d@�ZLG dAdB� dBeLeKe e= �ZMG dCdD� dDeKe; �ZNG dEdF� dFeNe; �ZOG dGdH� dHeNe; e jP�ZQG dIdJ� dJeLeNe �ZRG dKdL� dLe e= �ZSG dMdN� dNeMe= �ZTdOdP�dQdR�ZUG dSdT� dTeTe= �ZVG dUdV� dVeTe= �ZWdS )Xz%Define generic result set constructs.� )� annotations)�EnumN)�Any)�Callable)�cast)�Dict)�Generic)�Iterable)�Iterator)�List)�Mapping)�NoReturn)�Optional)�overload)�Sequence)�Set)�Tuple)� TYPE_CHECKING)�TypeVar)�Union� )�Row)� RowMapping� )�exc)�util)� _generative)� HasMemoized)�InPlaceGenerative)�!HasMemoized_ro_memoized_attribute)�NONE_SET)�HAS_CYEXTENSION)�Literal)�Self)� tuplegetter)�SQLCoreOperations)�_ResultProcessorTypezSQLCoreOperations[Any].�_R)�bound�_T�_TPz_ResultProcessorType[Any]c @ s� e Zd ZU dZdZdZded< dZded< dZded < d ed < d ed < ded< ded< e dd�dd��Z ddd�dd�Z d d�dd �Z e dOd d d d!d"�d#d$��Ze dPd d d%d&d"�d'd$��Ze dQd d dd(d"�d)d$��ZdRd d dd(d"�d+d$�Zd,d!d-�d.d/�Zd0dd1d2�d3d4�Zd5d6d7�d8d9�Zd5d:d7�d;d<�Zd5d d7�d=d>�ZdSd dd?d2�d@dA�Zd5dBd7�dCdD�ZdEdFddG�dHdI�Zd dd!dJ�dKdL�Ze dd�dMdN��ZdS )T�ResultMetaDataz$Base for metadata about result rows.� N�Optional[_TupleGetterType]� _tuplefilter�Optional[Sequence[int]]�_translated_indexes�(Optional[Sequence[Callable[[Any], Any]]]�_unique_filters� _KeyMapType�_keymap� Sequence[str]�_keys�Optional[_ProcessorsType]� _processors�Mapping[_KeyType, int]� _key_to_index� RMKeyView��returnc C s t | �S �N)r; ��selfr, r, �M/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/engine/result.py�keysj s zResultMetaData.keys�object�bool��keyr= c C s t � �d S r> ��NotImplementedError�r@ rF r, r, rA �_has_keyn s zResultMetaData._has_keyc C s t � �d S r> rG r? r, r, rA � _for_freezeq s zResultMetaData._for_freeze.r zOptional[Exception]� Literal[True]r )rF �err�raiseerrr= c C s d S r> r, �r@ rF rM rN r, r, rA � _key_fallbackt s z ResultMetaData._key_fallbackzLiteral[False]�Nonec C s d S r> r, rO r, r, rA rP y s zOptional[NoReturn]c C s d S r> r, rO r, r, rA rP � s Tc C s |sJ �t |�|�d S r> )�KeyErrorrO r, r, rA rP � s �_KeyMapRecType)�recr= c C s t d��d S )NzCambiguous column name logic is implemented for CursorResultMetaDatarG )r@ rT r, r, rA � _raise_for_ambiguous_column_name� s �z/ResultMetaData._raise_for_ambiguous_column_name� _KeyIndexType� Optional[int]�rF rN r= c C s t � �d S r> rG �r@ rF rN r, r, rA �_index_for_key� s z ResultMetaData._index_for_key�Sequence[_KeyIndexType]� Sequence[int]�rB r= c C s t � �d S r> rG �r@ rB r, r, rA �_indexes_for_keys� s z ResultMetaData._indexes_for_keys�Iterator[_KeyMapRecType]c C s t � �d S r> rG r^ r, r, rA �_metadata_for_keys� s z!ResultMetaData._metadata_for_keysc C s t � �d S r> rG r^ r, r, rA �_reduce� s zResultMetaData._reduce�#Optional[Callable[[Row[Any]], Any]]c C s& | � ||�}|d ur t�|�S d S d S r> )rZ �operator� itemgetter)r@ rF rN �indexr, r, rA �_getter� s zResultMetaData._getter�_TupleGetterTypec C s | � |�}t|� S r> )r_ r$ )r@ rB �indexesr, r, rA �_row_as_tuple_getter� s z#ResultMetaData._row_as_tuple_getterz Mapping[_KeyType, Sequence[Any]]�int)�keymaprf r= c s � fdd�|� � D �S )Nc s& i | ] \}}|� d ur||� �qS r> r, )�.0rF rT �rf r, rA � <dictcomp>� s �z5ResultMetaData._make_key_to_index.<locals>.<dictcomp>)�items)r@ rl rf r, rn rA �_make_key_to_index� s �z!ResultMetaData._make_key_to_index)rF � attr_errorr= c C sx || j v r | �| j | � nX|rhz| �|d � W qt tyd } z t|jd �|�W Y d }~qtd }~0 0 n | �|d � d S �Nr )r4 rU rP rR �AttributeError�args)r@ rF rr �ker, r, rA �_key_not_found� s (z ResultMetaData._key_not_foundc C s | j rt�| j �rd S | j S d S r> )r8 r � issupersetr? r, r, rA �_effective_processors� s z$ResultMetaData._effective_processors).).).)T)T)�__name__� __module__� __qualname__�__doc__� __slots__r. �__annotations__r0 r2 �propertyrB rJ rK r rP rU rZ r_ ra rb rg rj rq rw ry r, r, r, rA r+ ] sH � � � � � r+ c @ s� e Zd ZU dZded< ded< dd�dd�Zd d �d d �Zd d �dd�Zdd �dd�Zddd�dd�Z ddd�dd�Z ddd�dd �Z d S ) r; ��_parentr6 r+ r� r5 r6 )�parentc C s || _ dd� |jD �| _d S )Nc S s g | ]}|d ur|�qS r> r, )rm �kr, r, rA � <listcomp>� � z&RMKeyView.__init__.<locals>.<listcomp>r� )r@ r� r, r, rA �__init__� s zRMKeyView.__init__rk r< c C s t | j�S r> )�lenr6 r? r, r, rA �__len__� s zRMKeyView.__len__�strc C s d� | �S )Nz#{0.__class__.__name__}({0._keys!r}))�formatr? r, r, rA �__repr__� s zRMKeyView.__repr__z Iterator[str]c C s t | j�S r> )�iterr6 r? r, r, rA �__iter__� s zRMKeyView.__iter__r rD )�itemr= c C s t |t�rdS | j�|�S )NF)� isinstancerk r� rJ )r@ r� r, r, rA � __contains__� s zRMKeyView.__contains__)�otherr= c C s t |�t | �kS r> ��list�r@ r� r, r, rA �__eq__� s zRMKeyView.__eq__c C s t |�t | �kS r> r� r� r, r, rA �__ne__� s zRMKeyView.__ne__N) rz r{ r| r~ r r� r� r� r� r� r� r� r, r, r, rA r; � s r; c @ s� e Zd ZU dZdZded< d.ddddd d d �d d �Zddd�dd�Zdd�dd�Zdd�dd�Z ddd�d d �Z d/d dd d!�d"d#�Z d$d%d&�d'd(�Z d$d)d&�d*d+�Z d$dd&�d,d-�ZdS )0�SimpleResultMetaDataz*result metadata for in-memory collections.)r6 r4 r8 r. r0 r2 r: r5 r6 NzOptional[Sequence[Any]]r7 r- r/ r1 )rB �extrar8 r. r0 r2 c C sz t |�| _|| _|| _|| _|r<dd� tt| j|��D �}ndd� t| j�D �}dd� |D �| _|| _| � | jd�| _ d S )Nc S s0 g | ](\}\}}|f|r |nd |||ff�qS �r, r, )rm rf �name�extrasr, r, rA r� s ��z1SimpleResultMetaData.__init__.<locals>.<listcomp>c S s g | ]\}}|f||d ff�qS r� r, )rm rf r� r, r, rA r� s �c S s i | ]\}}|D ] }||�qqS r, r, )rm rB rT rF r, r, rA ro ! r� z1SimpleResultMetaData.__init__.<locals>.<dictcomp>r ) r� r6 r. r0 r2 � enumerate�zipr4 r8 rq r: )r@ rB r� r8 r. r0 r2 Z recs_namesr, r, rA r� s ��z SimpleResultMetaData.__init__rC rD rE c C s || j v S r> �r4 rI r, r, rA rJ ' s z SimpleResultMetaData._has_keyr+ r< c s: � j }|r� jr� �|�}t� j� fdd�� jD �|d�S )Nc s g | ]}� j | d �qS )r r� �rm rF r? r, rA r� 3 r� z4SimpleResultMetaData._for_freeze.<locals>.<listcomp>)r� r2 )r2 r. r� r6 )r@ Zunique_filtersr, r? rA rK * s �z SimpleResultMetaData._for_freezezDict[str, Any]c C s | j | jd�S )N�r6 r0 r� r? r, r, rA � __getstate__7 s �z!SimpleResultMetaData.__getstate__rQ )�stater= c C s: |d r|d }t |� }nd }}| j|d ||d� d S )Nr0 r6 )r0 r. )r$ r� )r@ r� r0 r. r, r, rA � __setstate__= s �z!SimpleResultMetaData.__setstate__Tr rk rX c C s` t |jjv r| j| }z| j| }W n2 tyV } z| �|||�}W Y d }~n d }~0 0 |d S rs �rk � __class__�__mro__r6 r4 rR rP )r@ rF rN rT rv r, r, rA rZ I s $z#SimpleResultMetaData._index_for_key� Sequence[Any]r\ r] c s � fdd�|D �S )Nc s g | ]}� j | d �qS �r r� r� r? r, rA r� T r� z:SimpleResultMetaData._indexes_for_keys.<locals>.<listcomp>r, r^ r, r? rA r_ S s z&SimpleResultMetaData._indexes_for_keysr` c c sl |D ]b}t |jjv r | j| }z| j| }W n2 ty^ } z| �||d�}W Y d }~n d }~0 0 |V qd S )NTr� )r@ rB rF rT rv r, r, rA ra V s $z'SimpleResultMetaData._metadata_for_keysc s� z� fdd�|D �}W n8 t yN } z � �|jd |d� W Y d }~n d }~0 0 t|� \}}}� jrv� fdd�|D �}t|� }t||||� j� jd�}|S )Nc s, g | ]$}� j t|jjv r"� j| n| �qS r, )r4 rk r� r� r6 r� r? r, rA r� f s ��z0SimpleResultMetaData._reduce.<locals>.<listcomp>r Tc s g | ]}� j | �qS r, )r0 )rm �idxr? r, rA r� u r� )r� r. r0 r8 r2 ) rR rP ru r� r0 r$ r� r8 r2 ) r@ rB Zmetadata_for_keysrv ri Znew_keysr� �tupZ new_metadatar, r? rA rb d s& � *� z SimpleResultMetaData._reduce)NNNNN)T)rz r{ r| r} r~ r r� rJ rK r� r� rZ r_ ra rb r, r, r, rA r� � s" �! r� r5 � Optional[Any]z#Callable[[Iterable[Any]], Row[Any]])�fieldsr� r= c C s t | |�}t�t||j|j�S r> )r� � functools�partialr ry r: )r� r� r� r, r, rA � result_tuple� s �r� c @ s e Zd ZdZdS )�_NoRowr N)rz r{ r| �_NO_ROWr, r, r, rA r� � s r� c @ s� e Zd ZU dZdZded< dZded< ded < dZd ed < dZded < d Z ded< ded< dd�dd�Z dNddd�dd�Z dOddd�d d �Z dd�d d �Z dPdd d!�d"d#�Zed$d�d%d&��Zed'd�d(d)��Zd*d�d+d,�Zd*d�d-d.�Zed/d�d0d1��Zed2d�d3d4��Zed5ddd6d7d8�d9d:��Zedd6dd;d<�d=d:��Zedddd>d<�d?d:��Zdddd>d<�d@d:�ZdAd�dBdC�Zd;d�dDdE�ZedFdGdH�dIdJ��Ze j dKd�dLdM��Z dS )Q�ResultInternalr, N�Optional[Result[Any]]� _real_resultTrD �_generate_rows� Optional[Callable[[Any], Any]]�_row_logging_fnz Optional[_UniqueFilterStateType]�_unique_filter_state�_post_creational_filterFr+ � _metadata�_source_supports_scalars�#Iterator[_InterimRowType[Row[Any]]]r< c C s t � �d S r> rG r? r, r, rA �_fetchiter_impl� s z ResultInternal._fetchiter_impl�#Optional[_InterimRowType[Row[Any]]]�� hard_closer= c C s t � �d S r> rG �r@ r� r, r, rA �_fetchone_impl� s z ResultInternal._fetchone_implrW � List[_InterimRowType[Row[Any]]]��sizer= c C s t � �d S r> rG �r@ r� r, r, rA �_fetchmany_impl� s z ResultInternal._fetchmany_implc C s t � �d S r> rG r? r, r, rA �_fetchall_impl� s z ResultInternal._fetchall_implrQ ��hardr= c C s t � �d S r> rG �r@ r� r, r, rA � _soft_close� s zResultInternal._soft_close�Optional[Callable[..., _R]]c s� | j r | j ntd| �}|jrF| js&d S t�dddddd��fdd � }nt}| j}|j}|j}|j}|r�|js�|rx||�}t � ||||��|�d d d ���fd d� }nt � ||||�}|j r�|j � |�d d d �� �fdd� }|S )N� Result[Any]r+ r7 r9 r zRow[Any])�metadata� processors� key_to_index� scalar_objr= c s � | |||f�S r> r, )r� r� r� r� )�_procr, rA � process_row� s �z/ResultInternal._row_getter.<locals>.process_rowz_InterimRowType[Row[Any]]r' )�rowr= c s � �| ��S r> r, �r� )�_make_row_orig�fixed_tfr, rA �make_row� s z,ResultInternal._row_getter.<locals>.make_rowc s � �| ��S r> r, r� )�_log_row� _make_rowr, rA r� � s ) r� r r� r� r r� r: ry r. r� r� r� )r@ � real_resultr� r� r� r� �tfr� r, )r� r� r� r� r� rA � _row_getter� s< �� ��zResultInternal._row_getterzCallable[..., Iterator[_R]]c sR | j � | j�| jr8| j\��ddd�� ���fdd� }nddd�� �fdd� }|S )Nr� � Iterator[_R]�r@ r= c 3 sX | � � D ]J}� r� |�n|}�r(�|�n|}|�v r6q��|� �rL�|�}|V qd S r> )r� �add)r@ �raw_row�obj�hashed�r� �post_creational_filter�strategy�uniquesr, rA �iterrows� s � z1ResultInternal._iterator_getter.<locals>.iterrowsc 3 s4 | � � D ]&}� r� |�n|}�r(�|�}|V qd S r> )r� )r@ r� r� �r� r� r, rA r� s ��r� r� r� �_unique_strategy)r@ r� r, r� rA �_iterator_getter� s z ResultInternal._iterator_getter�List[_R]c s, | j � � d usJ �| �� }� fdd�|D �S )Nc s g | ] }� |��qS r, r, �rm r� �r� r, rA r� r� z0ResultInternal._raw_all_rows.<locals>.<listcomp>)r� r� )r@ �rowsr, r� rA � _raw_all_rows s z ResultInternal._raw_all_rowsc s� | j �| j� | �� }� r,� fdd�|D �}n|}| jrb| j\���fdd��fdd�|D �D �}n|}�r|�fdd�|D �}|S )Nc s g | ] }� |��qS r, r, r� r� r, rA r� ' r� z+ResultInternal._allrows.<locals>.<listcomp>c s& g | ] \}}|� vr� � |�s|�qS r, �r� �rm �made_rowZsig_row�r� r, rA r� 0 s �c s g | ]}|� r� |�n|f�qS r, r, �rm r� �r� r, rA r� 2 s ��c s g | ] }� |��qS r, r, r� �r� r, rA r� ? s )r� r� r� r� r� )r@ r� � made_rowsZ interim_rowsr, r� rA �_allrows s& �� �zResultInternal._allrowsz1Callable[..., Union[Literal[_NoRow._NO_ROW], _R]]c sR | j � | j�| jr8| j\��ddd�� ���fdd� }nddd�� �fdd� }|S )Nr� zUnion[_NoRow, _R]r� c sd | j }|� }|d u rtS � r$� |�n|}�r4�|�n|}|�v rDqn ��|� �rZ�|�}|S qd S r> )r� r� r� )r@ Z_onerowr� r� r� r� r, rA �onerowO s � z-ResultInternal._onerow_getter.<locals>.onerowc s8 | � � }|d u rtS � r � |�n|}�r0�|�}|S d S r> )r� r� )r@ r� Z interim_rowr� r, rA r� d s �r� )r@ r� r, r� rA �_onerow_getterD s z ResultInternal._onerow_getterzCallable[..., List[_R]]c sn | j �| j�| jrR| j\��dddddd�dd�� d d dd �� ����fd d � }nd d dd ���fdd � }|S )Nr� z List[Any]z$Optional[Callable[[List[Any]], Any]]zSet[Any]r� )r� r� r� r� r= c sN � r� fdd�|D �}�r.�fdd�|D �}ndd� |D �}�fdd�|D �S )Nc s g | ] }� |��qS r, r, r� r� r, rA r� � r� zFResultInternal._manyrow_getter.<locals>.filterrows.<locals>.<listcomp>c 3 s | ]}|� |�fV qd S r> r, r� r� r, rA � <genexpr>� s zEResultInternal._manyrow_getter.<locals>.filterrows.<locals>.<genexpr>c s s | ]}||fV qd S r> r, r� r, r, rA r� � r� c s& g | ] \}}|� vr� � |�s|�qS r, r� r� r� r, rA r� � s �r, )r� r� r� r� r� r, )r� r� r� rA � filterrows{ s � �z2ResultInternal._manyrow_getter.<locals>.filterrowszResultInternal[_R]rW )r@ �numr= c s� g }| j }|d u rx| jr | jntd| �}|jr:|j }}q|||�}t|�}�d usVJ �|�� �|���� |t|� }n|}|d us�J �|r�||�}|s�q�|�� �|���� |t|� }q��r҇fdd�|D �}|S )Nr� c s g | ] }� |��qS r, r, r� r� r, rA r� � r� �DResultInternal._manyrow_getter.<locals>.manyrows.<locals>.<listcomp>)r� r� r � _yield_perr� �extend)r@ r ZcollectZ _manyrowsr� Z num_requiredr� �r r� r� r� r� r, rA �manyrows� s: �� � �z0ResultInternal._manyrow_getter.<locals>.manyrowsc s^ |d u r$| j r| j ntd| �}|j}| �|�}� rD� fdd�|D �}�rZ�fdd�|D �}|S )Nr� c s g | ] }� |��qS r, r, r� r� r, rA r� � r� r c s g | ] }� |��qS r, r, r� r� r, rA r� � r� )r� r r r� )r@ r r� r� r� r, rA r � s �� r� )r@ r r, r rA �_manyrow_getterr s 1z ResultInternal._manyrow_getterzResultInternal[Row[Any]]rL r )r@ �raise_for_second_row�raise_for_none�scalarr= c C s d S r> r, �r@ r r r r, r, rA � _only_one_row� s z ResultInternal._only_one_rowr' )r r r r= c C s d S r> r, r r, r, rA r � s � Optional[_R]c C s d S r> r, r r, r, rA r � s c C s� | j }|dd�}|d u r,|r(t�d��nd S |rB| jrBd| _d }n| j}z|rV||�n|}W n | jdd� � Y n0 |�rf| j�r"| j\}}|r�||�n|} |dd�} | d u r�t } �q:zH|r�|| �n| } |r�| t us�J �| || �kr�W q�n || kr�W q�W �q:W q� | jdd� � Y q�0 q�n|dd�} | d u �r:t } | t u�rr| jdd� t� |�r^dnd��n | jdd� |�s�| j } | �r�| |�}|�r�|�r�|d S |S d S ) NT�r� z&No row was found when one was requiredF�r� z6Multiple rows were found when exactly one was requiredz6Multiple rows were found when one or none was requiredr ) r� r Z NoResultFoundr� r� r� r� r� r� r� ZMultipleResultsFoundr� ) r@ r r r r� r� r� r� r� Zexisting_row_hashZnext_rowr� r, r, rA r � sn � �� r� c C s | � | �S r> )r� r? r, r, rA � _iter_implB s zResultInternal._iter_implc C s" | � | �}|tu rt� �n|S d S r> )r� r� � StopIteration�r@ r� r, r, rA � _next_implE s zResultInternal._next_implr[ r# )ri r= c C sD | j r | j ntd| �}|jr(t|�dkr6| j�|�| _| js@J �| S )Nr� r )r� r r� r� r� rb r� )r@ ri r� r, r, rA �_column_slicesL s �� z ResultInternal._column_slices�_UniqueFilterStateTypec C s� | j d usJ �| j \}}| jd ur(| jntd| �}|s�| jjr�|jrX| jsX| jjd }n(| jj}| jjrt| j�|�}t� d|�}||fS )Nr� r Z_filter_on_values) r� r� r r� r2 r� r� r. rd � methodcaller)r@ r� r� r� �filtersr, r, rA r� [ s" �� �� z ResultInternal._unique_strategy)F)N)F) rz r{ r| r~ r� r r� r� r� Z _is_cursorr� r� r� r� r� r r� r� r� r� r� r r r r r r r r Zmemoized_attributer� r, r, r, rA r� � sN � �;"%-bUr� c @ s( e Zd ZU dZded< dd�dd�ZdS ) � _WithKeysr, r+ r� r; r< c C s | j jS )ak Return an iterable view which yields the string keys that would be represented by each :class:`_engine.Row`. The keys can represent the labels of the columns returned by a core statement or the names of the orm classes returned by an orm execution. The view also can be tested for key containment using the Python ``in`` operator, which will test both for the string keys represented in the view, as well as for alternate keys such as column objects. .. versionchanged:: 1.4 a key view object is returned rather than a plain list. )r� rB r? r, r, rA rB { s z_WithKeys.keysN)rz r{ r| r~ r rB r, r, r, rA r u s r c @ s� e Zd ZU dZdZdZded< dZded< dZd ed < e � � Z d ed < d d�dd�Z dd�dd�Z ddddd�dd�Zdd�dd�Zedd�d d ��Zedd�d d ��Zed dd!�d"d#��Zedd$dd%�d&d'��Zd(dd)�d*d+�Zed,d-d.�d/d0��Zed,d1d-d2�d3d0��Zed�d(d5d6�d7d0��Zd�d(d5d6�d8d0�Zd�d(dd:d;�d<d=�Zd>d?d@�dAdB�ZdCd�dDdE�ZedFd�dGdH��Z dFd�dIdJ�Z dKd�dLdM�Z dNd�dOdP�Z dQd�dRdS�Z d�d dTdU�dVdW�Z!dXd�dYdZ�Z"d[d�d\d]�Z#d�d dXdU�d^d_�Z$dXd�d`da�Z%d[d�dbdc�Z&d[d�ddde�Z'ed,dfd.�dgdh��Z(edd�didh��Z(dd�djdh�Z(ed,dkd.�dldm��Z)ednd�dodm��Z)dnd�dpdm�Z)dQd�dqdr�Z*ed,dkd.�dsdt��Z+edd�dudt��Z+dd�dvdt�Z+dwd�dxdy�Z,dzd{d|�d}d~�Z-dS )��Resulta\ Represent a set of database results. .. versionadded:: 1.4 The :class:`_engine.Result` object provides a completely updated usage model and calling facade for SQLAlchemy Core and SQLAlchemy ORM. In Core, it forms the basis of the :class:`_engine.CursorResult` object which replaces the previous :class:`_engine.ResultProxy` interface. When using the ORM, a higher level object called :class:`_engine.ChunkedIteratorResult` is normally used. .. note:: In SQLAlchemy 1.4 and above, this object is used for ORM results returned by :meth:`_orm.Session.execute`, which can yield instances of ORM mapped objects either individually or within tuple-like rows. Note that the :class:`_engine.Result` object does not deduplicate instances or rows automatically as is the case with the legacy :class:`_orm.Query` object. For in-Python de-duplication of instances or rows, use the :meth:`_engine.Result.unique` modifier method. .. seealso:: :ref:`tutorial_fetching_rows` - in the :doc:`/tutorial/index` )r� �__dict__Nz(Optional[Callable[[Row[Any]], Row[Any]]]r� FrD r� rW r z util.immutabledict[Any, Any]� _attributesr+ )�cursor_metadatac C s || _ d S r> )r� )r@ r r, r, rA r� � s zResult.__init__r# r< c C s | S r> r, r? r, r, rA � __enter__� s zResult.__enter__r rQ ��type_�value� tracebackr= c C s | � � d S r> )�close�r@ r r r! r, r, rA �__exit__� s zResult.__exit__c C s | j dd� dS )a� close this :class:`_engine.Result`. The behavior of this method is implementation specific, and is not implemented by default. The method should generally end the resources in use by the result object and also cause any subsequent iteration or row fetching to raise :class:`.ResourceClosedError`. .. versionadded:: 1.4.27 - ``.close()`` was previously not generally available for all :class:`_engine.Result` classes, instead only being available on the :class:`_engine.CursorResult` returned for Core statement executions. As most other result objects, namely the ones used by the ORM, are proxying a :class:`_engine.CursorResult` in any case, this allows the underlying cursor result to be closed from the outside facade for the case when the ORM query is using the ``yield_per`` execution option where it does not immediately exhaust and autoclose the database cursor. Tr N)r� r? r, r, rA r" � s z Result.closec C s t � �d S r> rG r? r, r, rA � _soft_closed� s zResult._soft_closedc C s t � �dS )zkreturn ``True`` if this :class:`_engine.Result` reports .closed .. versionadded:: 1.4.43 NrG r? r, r, rA �closed� s z Result.closedrk �r r= c C s || _ | S )a� Configure the row-fetching strategy to fetch ``num`` rows at a time. This impacts the underlying behavior of the result when iterating over the result object, or otherwise making use of methods such as :meth:`_engine.Result.fetchone` that return one row at a time. Data from the underlying cursor or other data source will be buffered up to this many rows in memory, and the buffered collection will then be yielded out one row at a time or as many rows are requested. Each time the buffer clears, it will be refreshed to this many rows or as many rows remain if fewer remain. The :meth:`_engine.Result.yield_per` method is generally used in conjunction with the :paramref:`_engine.Connection.execution_options.stream_results` execution option, which will allow the database dialect in use to make use of a server side cursor, if the DBAPI supports a specific "server side cursor" mode separate from its default mode of operation. .. tip:: Consider using the :paramref:`_engine.Connection.execution_options.yield_per` execution option, which will simultaneously set :paramref:`_engine.Connection.execution_options.stream_results` to ensure the use of server side cursors, as well as automatically invoke the :meth:`_engine.Result.yield_per` method to establish a fixed row buffer size at once. The :paramref:`_engine.Connection.execution_options.yield_per` execution option is available for ORM operations, with :class:`_orm.Session`-oriented use described at :ref:`orm_queryguide_yield_per`. The Core-only version which works with :class:`_engine.Connection` is new as of SQLAlchemy 1.4.40. .. versionadded:: 1.4 :param num: number of rows to fetch each time the buffer is refilled. If set to a value below 1, fetches all rows for the next buffer. .. seealso:: :ref:`engine_stream_results` - describes Core behavior for :meth:`_engine.Result.yield_per` :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel` )r �r@ r r, r, rA � yield_per� s 1zResult.yield_per�Optional[_UniqueFilterType]�r� r= c C s t � |f| _| S )a Apply unique filtering to the objects returned by this :class:`_engine.Result`. When this filter is applied with no arguments, the rows or objects returned will filtered such that each row is returned uniquely. The algorithm used to determine this uniqueness is by default the Python hashing identity of the whole tuple. In some cases a specialized per-entity hashing scheme may be used, such as when using the ORM, a scheme is applied which works against the primary key identity of returned objects. The unique filter is applied **after all other filters**, which means if the columns returned have been refined using a method such as the :meth:`_engine.Result.columns` or :meth:`_engine.Result.scalars` method, the uniquing is applied to **only the column or columns returned**. This occurs regardless of the order in which these methods have been called upon the :class:`_engine.Result` object. The unique filter also changes the calculus used for methods like :meth:`_engine.Result.fetchmany` and :meth:`_engine.Result.partitions`. When using :meth:`_engine.Result.unique`, these methods will continue to yield the number of rows or objects requested, after uniquing has been applied. However, this necessarily impacts the buffering behavior of the underlying cursor or datasource, such that multiple underlying calls to ``cursor.fetchmany()`` may be necessary in order to accumulate enough objects in order to provide a unique collection of the requested size. :param strategy: a callable that will be applied to rows or objects being iterated, which should return an object that represents the unique value of the row. A Python ``set()`` is used to store these identities. If not passed, a default uniqueness strategy is used which may have been assembled by the source of this :class:`_engine.Result` object. ��setr� �r@ r� r, r, rA �unique s & z Result.uniquerV ��col_expressionsr= c G s | � |�S )a Establish the columns that should be returned in each row. This method may be used to limit the columns returned as well as to reorder them. The given list of expressions are normally a series of integers or string key names. They may also be appropriate :class:`.ColumnElement` objects which correspond to a given statement construct. .. versionchanged:: 2.0 Due to a bug in 1.4, the :meth:`_engine.Result.columns` method had an incorrect behavior where calling upon the method with just one index would cause the :class:`_engine.Result` object to yield scalar values rather than :class:`_engine.Row` objects. In version 2.0, this behavior has been corrected such that calling upon :meth:`_engine.Result.columns` with a single index will produce a :class:`_engine.Result` object that continues to yield :class:`_engine.Row` objects, which include only a single column. E.g.:: statement = select(table.c.x, table.c.y, table.c.z) result = connection.execute(statement) for z, y in result.columns("z", "y"): ... Example of using the column objects from the statement itself:: for z, y in result.columns( statement.selected_columns.c.z, statement.selected_columns.c.y ): ... .. versionadded:: 1.4 :param \*col_expressions: indicates columns to be returned. Elements may be integer row indexes, string column names, or appropriate :class:`.ColumnElement` objects corresponding to a select construct. :return: this :class:`_engine.Result` object with the modifications given. �r �r@ r1 r, r, rA �columns< s -zResult.columnszResult[Tuple[_T]]zScalarResult[_T]r� c C s d S r> r, r? r, r, rA �scalarsk s zResult.scalarsz Literal[0])r@ rf r= c C s d S r> r, �r@ rf r, r, rA r5 n s r zScalarResult[Any])rf r= c C s d S r> r, r6 r, r, rA r5 s s c C s t | |�S )a@ Return a :class:`_engine.ScalarResult` filtering object which will return single elements rather than :class:`_row.Row` objects. E.g.:: >>> result = conn.execute(text("select int_id from table")) >>> result.scalars().all() [1, 2, 3] When results are fetched from the :class:`_engine.ScalarResult` filtering object, the single column-row that would be returned by the :class:`_engine.Result` is instead returned as the column's value. .. versionadded:: 1.4 :param index: integer or row key indicating the column to be fetched from each row, defaults to ``0`` indicating the first column. :return: a new :class:`_engine.ScalarResult` filtering object referring to this :class:`_engine.Result` object. )� ScalarResultr6 r, r, rA r5 v s Trc rX c C s | j rtd��| j�||�S )zareturn a callable that will retrieve the given key from a :class:`_engine.Row`. �.can't use this function in 'only scalars' mode)r� rH r� rg rY r, r, rA rg � s �zResult._getterr[ rh r] c C s | j rtd��| j�|�S )zbreturn a callable that will retrieve the given keys from a :class:`_engine.Row`. r8 )r� rH r� rj r^ r, r, rA � _tuple_getter� s �zResult._tuple_getter� MappingResultc C s t | �S )a� Apply a mappings filter to returned rows, returning an instance of :class:`_engine.MappingResult`. When this filter is applied, fetching rows will return :class:`_engine.RowMapping` objects instead of :class:`_engine.Row` objects. .. versionadded:: 1.4 :return: a new :class:`_engine.MappingResult` filtering object referring to this :class:`_engine.Result` object. )r: r? r, r, rA �mappings� s zResult.mappingszTupleResult[_TP]c C s | S )z�Apply a "typed tuple" typing filter to returned rows. The :attr:`_engine.Result.t` attribute is a synonym for calling the :meth:`_engine.Result.tuples` method. .. versionadded:: 2.0 r, r? r, r, rA �t� s zResult.tc C s | S )a, Apply a "typed tuple" typing filter to returned rows. This method returns the same :class:`_engine.Result` object at runtime, however annotates as returning a :class:`_engine.TupleResult` object that will indicate to :pep:`484` typing tools that plain typed ``Tuple`` instances are returned rather than rows. This allows tuple unpacking and ``__getitem__`` access of :class:`_engine.Row` objects to by typed, for those cases where the statement invoked itself included typing information. .. versionadded:: 2.0 :return: the :class:`_engine.TupleResult` type at typing time. .. seealso:: :attr:`_engine.Result.t` - shorter synonym :attr:`_engine.Row._t` - :class:`_engine.Row` version r, r? r, r, rA �tuples� s z Result.tuples�Iterator[_RowData]c C s t � �dS )z�Return a safe iterator that yields raw row data. This is used by the :meth:`_engine.Result.merge` method to merge multiple compatible results together. NrG r? r, r, rA �_raw_row_iterator� s zResult._raw_row_iteratorzIterator[Row[_TP]]c C s | � � S r> �r r? r, r, rA r� � s zResult.__iter__zRow[_TP]c C s | � � S r> �r r? r, r, rA �__next__� s zResult.__next__z Iterator[Sequence[Row[_TP]]]r� c c s$ | j }|| |�}|r |V qq qdS )a� Iterate through sub-lists of rows of the size given. Each list will be of the size given, excluding the last list to be yielded, which may have a small number of rows. No empty lists will be yielded. The result object is automatically closed when the iterator is fully consumed. Note that the backend driver will usually buffer the entire result ahead of time unless the :paramref:`.Connection.execution_options.stream_results` execution option is used indicating that the driver should not pre-buffer results, if possible. Not all drivers support this option and the option is silently ignored for those who do not. When using the ORM, the :meth:`_engine.Result.partitions` method is typically more effective from a memory perspective when it is combined with use of the :ref:`yield_per execution option <orm_queryguide_yield_per>`, which instructs both the DBAPI driver to use server side cursors, if available, as well as instructs the ORM loading internals to only build a certain amount of ORM objects from a result at a time before yielding them out. .. versionadded:: 1.4 :param size: indicate the maximum number of rows to be present in each list yielded. If None, makes use of the value set by the :meth:`_engine.Result.yield_per`, method, if it were called, or the :paramref:`_engine.Connection.execution_options.yield_per` execution option, which is equivalent in this regard. If yield_per weren't set, it makes use of the :meth:`_engine.Result.fetchmany` default, which may be backend specific and not well defined. :return: iterator of lists .. seealso:: :ref:`engine_stream_results` :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel` N�r �r@ r� �getter� partitionr, r, rA � partitions� s 1 zResult.partitions�Sequence[Row[_TP]]c C s | � � S )z4A synonym for the :meth:`_engine.Result.all` method.�r� r? r, r, rA �fetchall' s zResult.fetchallzOptional[Row[_TP]]c C s | � | �}|tu rdS |S dS )a� Fetch one row. When all rows are exhausted, returns None. This method is provided for backwards compatibility with SQLAlchemy 1.x.x. To fetch the first row of a result only, use the :meth:`_engine.Result.first` method. To iterate through all rows, iterate the :class:`_engine.Result` object directly. :return: a :class:`_engine.Row` object if no filters are applied, or ``None`` if no rows remain. N�r� r� r r, r, rA �fetchone, s zResult.fetchonec C s | � | |�S )a� Fetch many rows. When all rows are exhausted, returns an empty sequence. This method is provided for backwards compatibility with SQLAlchemy 1.x.x. To fetch rows in groups, use the :meth:`_engine.Result.partitions` method. :return: a sequence of :class:`_engine.Row` objects. .. seealso:: :meth:`_engine.Result.partitions` rC r� r, r, rA � fetchmanyB s zResult.fetchmanyc C s | � � S )a� Return all rows in a sequence. Closes the result set after invocation. Subsequent invocations will return an empty sequence. .. versionadded:: 1.4 :return: a sequence of :class:`_engine.Row` objects. .. seealso:: :ref:`engine_stream_results` - How to stream a large result set without loading it completely in python. rI r? r, r, rA �allW s z Result.allc C s | j dddd�S )a� Fetch the first row or ``None`` if no row is present. Closes the result set and discards remaining rows. .. note:: This method returns one **row**, e.g. tuple, by default. To return exactly one single scalar value, that is, the first column of the first row, use the :meth:`_engine.Result.scalar` method, or combine :meth:`_engine.Result.scalars` and :meth:`_engine.Result.first`. Additionally, in contrast to the behavior of the legacy ORM :meth:`_orm.Query.first` method, **no limit is applied** to the SQL query which was invoked to produce this :class:`_engine.Result`; for a DBAPI driver that buffers results in memory before yielding rows, all rows will be sent to the Python process and all but the first row will be discarded. .. seealso:: :ref:`migration_20_unify_select` :return: a :class:`_engine.Row` object, or None if no rows remain. .. seealso:: :meth:`_engine.Result.scalar` :meth:`_engine.Result.one` F�r r r �r r? r, r, rA �firstj s #�z Result.firstc C s | j dddd�S )a� Return at most one result or raise an exception. Returns ``None`` if the result has no rows. Raises :class:`.MultipleResultsFound` if multiple rows are returned. .. versionadded:: 1.4 :return: The first :class:`_engine.Row` or ``None`` if no row is available. :raises: :class:`.MultipleResultsFound` .. seealso:: :meth:`_engine.Result.first` :meth:`_engine.Result.one` TFrO rP r? r, r, rA � one_or_none� s �zResult.one_or_noner) c C s d S r> r, r? r, r, rA � scalar_one� s zResult.scalar_onec C s d S r> r, r? r, r, rA rS � s c C s | j dddd�S )a* Return exactly one scalar result or raise an exception. This is equivalent to calling :meth:`_engine.Result.scalars` and then :meth:`_engine.ScalarResult.one`. .. seealso:: :meth:`_engine.ScalarResult.one` :meth:`_engine.Result.scalars` TrO rP r? r, r, rA rS � s �� Optional[_T]c C s d S r> r, r? r, r, rA �scalar_one_or_none� s zResult.scalar_one_or_noner� c C s d S r> r, r? r, r, rA rU � s c C s | j dddd�S )a0 Return exactly one scalar result or ``None``. This is equivalent to calling :meth:`_engine.Result.scalars` and then :meth:`_engine.ScalarResult.one_or_none`. .. seealso:: :meth:`_engine.ScalarResult.one_or_none` :meth:`_engine.Result.scalars` TFrO rP r? r, r, rA rU � s �c C s | j dddd�S )am Return exactly one row or raise an exception. Raises :class:`_exc.NoResultFound` if the result returns no rows, or :class:`_exc.MultipleResultsFound` if multiple rows would be returned. .. note:: This method returns one **row**, e.g. tuple, by default. To return exactly one single scalar value, that is, the first column of the first row, use the :meth:`_engine.Result.scalar_one` method, or combine :meth:`_engine.Result.scalars` and :meth:`_engine.Result.one`. .. versionadded:: 1.4 :return: The first :class:`_engine.Row`. :raises: :class:`.MultipleResultsFound`, :class:`.NoResultFound` .. seealso:: :meth:`_engine.Result.first` :meth:`_engine.Result.one_or_none` :meth:`_engine.Result.scalar_one` TFrO rP r? r, r, rA �one� s �z Result.onec C s d S r> r, r? r, r, rA r � s z Result.scalarc C s d S r> r, r? r, r, rA r � s c C s | j dddd�S )a� Fetch the first column of the first row, and close the result set. Returns ``None`` if there are no rows to fetch. No validation is performed to test if additional rows remain. After calling this method, the object is fully closed, e.g. the :meth:`_engine.CursorResult.close` method will have been called. :return: a Python scalar value, or ``None`` if no rows remain. FTrO rP r? r, r, rA r � s ��FrozenResult[_TP]c C s t | �S )a Return a callable object that will produce copies of this :class:`_engine.Result` when invoked. The callable object returned is an instance of :class:`_engine.FrozenResult`. This is used for result set caching. The method must be called on the result when it has been unconsumed, and calling the method will consume the result fully. When the :class:`_engine.FrozenResult` is retrieved from a cache, it can be called any number of times where it will produce a new :class:`_engine.Result` object each time against its stored set of rows. .. seealso:: :ref:`do_orm_execute_re_executing` - example usage within the ORM to implement a result-set cache. )� FrozenResultr? r, r, rA �freeze s z Result.freezer� zMergedResult[_TP])�othersr= c G s t | j| f| �S )a� Merge this :class:`_engine.Result` with other compatible result objects. The object returned is an instance of :class:`_engine.MergedResult`, which will be composed of iterators from the given result objects. The new result will use the metadata from this result object. The subsequent result objects must be against an identical set of result / cursor metadata, otherwise the behavior is undefined. )� MergedResultr� )r@ rZ r, r, rA �merge( s z Result.merge)N)r )r )T)N)N).rz r{ r| r} r~ r� r r� r r Z immutabledictr r� r r$ r" r� r% r& r r) r/ r4 r r5 rg r9 r; r< r= r? r� rB rG rJ rL rM rN rQ rR rS rU rV r rY r\ r, r, r, rA r � s| 3(/ � �:'!r c @ s� e Zd ZU dZdZded< ded< dd�d d �Zd d d d d �dd�Zeddd�dd��Z d1dd d�dd�Z e dd�dd��Z e dd�dd ��Z d d�d d �Ze d d�d d!��Zd"d�d#d$�Zd2dd%d&�d'd(�Zd)d�d*d+�Zd3d-d)d.�d/d0�Zd,S )4� FilterResultaZ A wrapper for a :class:`_engine.Result` that returns objects other than :class:`_engine.Row` objects, such as dictionaries or scalar objects. :class:`_engine.FilterResult` is the common base for additional result APIs including :class:`_engine.MappingResult`, :class:`_engine.ScalarResult` and :class:`_engine.AsyncResult`. )r� r� r� r� r r� r� r� r� r# r< c C s | S r> r, r? r, r, rA r O s zFilterResult.__enter__r rQ r c C s | j �|||� d S r> )r� r$ r# r, r, rA r$ R s zFilterResult.__exit__rk r' c C s | j �|�| _ | S )a� Configure the row-fetching strategy to fetch ``num`` rows at a time. The :meth:`_engine.FilterResult.yield_per` method is a pass through to the :meth:`_engine.Result.yield_per` method. See that method's documentation for usage notes. .. versionadded:: 1.4.40 - added :meth:`_engine.FilterResult.yield_per` so that the method is available on all result set implementations .. seealso:: :ref:`engine_stream_results` - describes Core behavior for :meth:`_engine.Result.yield_per` :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel` )r� r) r( r, r, rA r) U s zFilterResult.yield_perFrD r� c C s | j j|d� d S �Nr )r� r� r� r, r, rA r� k s zFilterResult._soft_closec C s | j jS r> )r� r% r? r, r, rA r% n s zFilterResult._soft_closedc C s | j jS )z|Return ``True`` if the underlying :class:`_engine.Result` reports closed .. versionadded:: 1.4.43 )r� r& r? r, r, rA r& r s zFilterResult.closedc C s | j �� dS )zUClose this :class:`_engine.FilterResult`. .. versionadded:: 1.4.43 N)r� r" r? r, r, rA r" | s zFilterResult.closezDict[Any, Any]c C s | j jS r> )r� r r? r, r, rA r � s zFilterResult._attributesr� c C s | j �� S r> )r� r� r? r, r, rA r� � s z FilterResult._fetchiter_implr� r� c C s | j j|d�S )Nr )r� r� r� r, r, rA r� � s zFilterResult._fetchone_implr� c C s | j �� S r> )r� r� r? r, r, rA r� � s zFilterResult._fetchall_implNrW r� c C s | j j|d�S �N�r� )r� r� r� r, r, rA r� � s z FilterResult._fetchmany_impl)F)F)N)rz r{ r| r} r~ r r r$ r r) r� r� r% r& r" r r� r� r� r� r, r, r, rA r] 9 s, � �r] c @ s� e Zd ZU dZdZdZded< ddd�d d �Zd+d d d�dd�Zd,ddd�dd�Z dd�dd�Z d-ddd�dd�Z dd�d d �Z d d�d d �Z d!d�d"d#�Zd$d�d%d&�Zd$d�d'd(�Zd!d�d)d*�Zd S ).r7 a� A wrapper for a :class:`_engine.Result` that returns scalar values rather than :class:`_row.Row` values. The :class:`_engine.ScalarResult` object is acquired by calling the :meth:`_engine.Result.scalars` method. A special limitation of :class:`_engine.ScalarResult` is that it has no ``fetchone()`` method; since the semantics of ``fetchone()`` are that the ``None`` value indicates no more results, this is not compatible with :class:`_engine.ScalarResult` since there is no way to distinguish between ``None`` as a row value versus ``None`` as an indicator. Use ``next(result)`` to receive values individually. r, Fr� r� r� rV )r� rf c C sD || _ |jr |j| _d | _n |j�|g�| _t�d�| _|j| _d S rs )r� r� r� r� rb rd re r� )r@ r� rf r, r, rA r� � s zScalarResult.__init__Nr* r# r+ c C s t � |f| _| S )z�Apply unique filtering to the objects returned by this :class:`_engine.ScalarResult`. See :meth:`_engine.Result.unique` for usage details. r, r. r, r, rA r/ � s zScalarResult.uniquerW �Iterator[Sequence[_R]]r� c c s$ | j }|| |�}|r |V qq qdS )z�Iterate through sub-lists of elements of the size given. Equivalent to :meth:`_engine.Result.partitions` except that scalar values, rather than :class:`_engine.Row` objects, are returned. NrC rD r, r, rA rG � s zScalarResult.partitions� Sequence[_R]r< c C s | � � S )�:A synonym for the :meth:`_engine.ScalarResult.all` method.rI r? r, r, rA rJ � s zScalarResult.fetchallc C s | � | |�S )z�Fetch many objects. Equivalent to :meth:`_engine.Result.fetchmany` except that scalar values, rather than :class:`_engine.Row` objects, are returned. rC r� r, r, rA rM � s zScalarResult.fetchmanyc C s | � � S )z�Return all scalar values in a sequence. Equivalent to :meth:`_engine.Result.all` except that scalar values, rather than :class:`_engine.Row` objects, are returned. rI r? r, r, rA rN � s zScalarResult.allr� c C s | � � S r> r@ r? r, r, rA r� � s zScalarResult.__iter__r' c C s | � � S r> rA r? r, r, rA rB � s zScalarResult.__next__r c C s | j dddd�S )z�Fetch the first object or ``None`` if no object is present. Equivalent to :meth:`_engine.Result.first` except that scalar values, rather than :class:`_engine.Row` objects, are returned. FrO rP r? r, r, rA rQ � s �zScalarResult.firstc C s | j dddd�S )z�Return at most one object or raise an exception. Equivalent to :meth:`_engine.Result.one_or_none` except that scalar values, rather than :class:`_engine.Row` objects, are returned. TFrO rP r? r, r, rA rR s �zScalarResult.one_or_nonec C s | j dddd�S )z�Return exactly one object or raise an exception. Equivalent to :meth:`_engine.Result.one` except that scalar values, rather than :class:`_engine.Row` objects, are returned. TFrO rP r? r, r, rA rV s �zScalarResult.one)N)N)N)rz r{ r| r} r~ r� r r� r/ rG rJ rM rN r� rB rQ rR rV r, r, r, rA r7 � s r7 c @ sJ e Zd ZdZdZe�rFd2ddd�dd�Zd d �d d �Zd d �dd�Zd3dd d�dd�Z d d �dd�Z dd �dd�Z dd �dd�Z d d �dd�Z d d �d d �Zdd �d d �Zed d!d"�d#d$��Zed%d �d&d$��Zd%d �d'd$�Zed d(d"�d)d*��Zed+d �d,d*��Zd+d �d-d*�Zed d(d"�d.d/��Zed%d �d0d/��Zd%d �d1d/�ZdS )4� TupleResulta A :class:`_engine.Result` that's typed as returning plain Python tuples instead of rows. Since :class:`_engine.Row` acts like a tuple in every way already, this class is a typing only class, regular :class:`_engine.Result` is still used at runtime. r, NrW ra r� c C s dS )z�Iterate through sub-lists of elements of the size given. Equivalent to :meth:`_engine.Result.partitions` except that tuple values, rather than :class:`_engine.Row` objects, are returned. Nr, r� r, r, rA rG * s zTupleResult.partitionsr r< c C s dS )z�Fetch one tuple. Equivalent to :meth:`_engine.Result.fetchone` except that tuple values, rather than :class:`_engine.Row` objects, are returned. Nr, r? r, r, rA rL 6 s zTupleResult.fetchonerb c C s dS )rc Nr, r? r, r, rA rJ @ s zTupleResult.fetchallc C s dS )z�Fetch many objects. Equivalent to :meth:`_engine.Result.fetchmany` except that tuple values, rather than :class:`_engine.Row` objects, are returned. Nr, r� r, r, rA rM D s zTupleResult.fetchmanyc C s dS )z�Return all scalar values in a sequence. Equivalent to :meth:`_engine.Result.all` except that tuple values, rather than :class:`_engine.Row` objects, are returned. Nr, r? r, r, rA rN N s zTupleResult.allr� c C s d S r> r, r? r, r, rA r� X r� zTupleResult.__iter__r' c C s d S r> r, r? r, r, rA rB Z r� zTupleResult.__next__c C s dS )z�Fetch the first object or ``None`` if no object is present. Equivalent to :meth:`_engine.Result.first` except that tuple values, rather than :class:`_engine.Row` objects, are returned. Nr, r? r, r, rA rQ \ s zTupleResult.firstc C s dS )z�Return at most one object or raise an exception. Equivalent to :meth:`_engine.Result.one_or_none` except that tuple values, rather than :class:`_engine.Row` objects, are returned. Nr, r? r, r, rA rR g s zTupleResult.one_or_nonec C s dS )z�Return exactly one object or raise an exception. Equivalent to :meth:`_engine.Result.one` except that tuple values, rather than :class:`_engine.Row` objects, are returned. Nr, r? r, r, rA rV q s zTupleResult.onezTupleResult[Tuple[_T]]r) r� c C s d S r> r, r? r, r, rA rS { s zTupleResult.scalar_oner c C s d S r> r, r? r, r, rA rS ~ s c C s dS )aB Return exactly one scalar result or raise an exception. This is equivalent to calling :meth:`_engine.Result.scalars` and then :meth:`_engine.ScalarResult.one`. .. seealso:: :meth:`_engine.ScalarResult.one` :meth:`_engine.Result.scalars` Nr, r? r, r, rA rS � s rT c C s d S r> r, r? r, r, rA rU � s z TupleResult.scalar_one_or_noner� c C s d S r> r, r? r, r, rA rU � s c C s dS )aB Return exactly one or no scalar result. This is equivalent to calling :meth:`_engine.Result.scalars` and then :meth:`_engine.ScalarResult.one_or_none`. .. seealso:: :meth:`_engine.ScalarResult.one_or_none` :meth:`_engine.Result.scalars` Nr, r? r, r, rA rU � s c C s d S r> r, r? r, r, rA r � s zTupleResult.scalarc C s d S r> r, r? r, r, rA r � s c C s dS )a� Fetch the first column of the first row, and close the result set. Returns ``None`` if there are no rows to fetch. No validation is performed to test if additional rows remain. After calling this method, the object is fully closed, e.g. the :meth:`_engine.CursorResult.close` method will have been called. :return: a Python scalar value , or ``None`` if no rows remain. Nr, r? r, r, rA r � s )N)N)rz r{ r| r} r~ r rG rL rJ rM rN r� rB rQ rR rV r rS rU r r, r, r, rA rd s: � rd c @ s� e Zd ZdZdZdZe�d�Zdd�dd�Z d/d d d �d d�Z dd d�dd�Z d0ddd�dd�Z dd�dd�Z d d�d d �Zd1ddd�d d �Zdd�d!d"�Zd#d�d$d%�Zd&d�d'd(�Zd d�d)d*�Zd d�d+d,�Zd&d�d-d.�Zd S )2r: z�A wrapper for a :class:`_engine.Result` that returns dictionary values rather than :class:`_engine.Row` values. The :class:`_engine.MappingResult` object is acquired by calling the :meth:`_engine.Result.mappings` method. r, T�_mappingr� ��resultc C s0 || _ |j| _|j| _|jr,| j�dg�| _d S rs )r� r� r� r� rb �r@ rg r, r, rA r� � s zMappingResult.__init__Nr* r# r+ c C s t � |f| _| S )z�Apply unique filtering to the objects returned by this :class:`_engine.MappingResult`. See :meth:`_engine.Result.unique` for usage details. r, r. r, r, rA r/ � s zMappingResult.uniquerV r0 c G s | � |�S )z:Establish the columns that should be returned in each row.r2 r3 r, r, rA r4 � s zMappingResult.columnsrW z Iterator[Sequence[RowMapping]]r� c c s$ | j }|| |�}|r |V qq qdS )z�Iterate through sub-lists of elements of the size given. Equivalent to :meth:`_engine.Result.partitions` except that :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. NrC rD r, r, rA rG � s zMappingResult.partitionszSequence[RowMapping]r< c C s | � � S )z;A synonym for the :meth:`_engine.MappingResult.all` method.rI r? r, r, rA rJ � s zMappingResult.fetchallzOptional[RowMapping]c C s | � | �}|tu rdS |S dS )z�Fetch one object. Equivalent to :meth:`_engine.Result.fetchone` except that :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. NrK r r, r, rA rL � s zMappingResult.fetchonec C s | � | |�S )z�Fetch many objects. Equivalent to :meth:`_engine.Result.fetchmany` except that :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. rC r� r, r, rA rM s zMappingResult.fetchmanyc C s | � � S )z�Return all scalar values in a sequence. Equivalent to :meth:`_engine.Result.all` except that :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. rI r? r, r, rA rN s zMappingResult.allzIterator[RowMapping]c C s | � � S r> r@ r? r, r, rA r� ! s zMappingResult.__iter__r c C s | � � S r> rA r? r, r, rA rB $ s zMappingResult.__next__c C s | j dddd�S )z�Fetch the first object or ``None`` if no object is present. Equivalent to :meth:`_engine.Result.first` except that :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. FrO rP r? r, r, rA rQ ' s �zMappingResult.firstc C s | j dddd�S )z�Return at most one object or raise an exception. Equivalent to :meth:`_engine.Result.one_or_none` except that :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. TFrO rP r? r, r, rA rR 4 s �zMappingResult.one_or_nonec C s | j dddd�S )z�Return exactly one object or raise an exception. Equivalent to :meth:`_engine.Result.one` except that :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. TFrO rP r? r, r, rA rV @ s �zMappingResult.one)N)N)N)rz r{ r| r} r~ r� rd � attrgetterr� r� r/ r4 rG rJ rL rM rN r� rB rQ rR rV r, r, r, rA r: � s$ � r: c @ sT e Zd ZU dZded< dd�dd�Zdd �d d �Zd d d�dd�Zdd �dd�ZdS )rX a� Represents a :class:`_engine.Result` object in a "frozen" state suitable for caching. The :class:`_engine.FrozenResult` object is returned from the :meth:`_engine.Result.freeze` method of any :class:`_engine.Result` object. A new iterable :class:`_engine.Result` object is generated from a fixed set of data each time the :class:`_engine.FrozenResult` is invoked as a callable:: result = connection.execute(query) frozen = result.freeze() unfrozen_result_one = frozen() for row in unfrozen_result_one: print(row) unfrozen_result_two = frozen() rows = unfrozen_result_two.all() # ... etc .. versionadded:: 1.4 .. seealso:: :ref:`do_orm_execute_re_executing` - example usage within the ORM to implement a result-set cache. :func:`_orm.loading.merge_frozen_result` - ORM function to merge a frozen result back into a :class:`_orm.Session`. r� �dataz Result[_TP]rf c C s@ |j �� | _|j| _|j| _| jr2t|�� �| _n |�� | _d S r> ) r� rK r� r� r r� r? rj rJ rh r, r, rA r� v s zFrozenResult.__init__zSequence[Sequence[Any]]r< c C s* | j rdd� | jD �S dd� | jD �S d S )Nc S s g | ] }|g�qS r, r, )rm �elemr, r, rA r� � r� z-FrozenResult.rewrite_rows.<locals>.<listcomp>c S s g | ] }t |��qS r, r� r� r, r, rA r� � r� )r� rj r? r, r, rA � rewrite_rows� s zFrozenResult.rewrite_rowsrH rW )� tuple_datar= c C sD t �t �}| j|_| j|_| j|_| jr:dd� |D �|_n||_|S )Nc S s g | ] }|d �qS r� r, )rm �dr, r, rA r� � r� z.FrozenResult.with_new_rows.<locals>.<listcomp>)rX �__new__r� r r� rj )r@ rm �frr, r, rA � with_new_rows� s zFrozenResult.with_new_rowsc C s& t | jt| j��}| j|_| j|_|S r> )�IteratorResultr� r� rj r r� rh r, r, rA �__call__� s �zFrozenResult.__call__N) rz r{ r| r} r r� rl rq rs r, r, r, rA rX M s & rX c @ s� e Zd ZdZdZdZd&ddddd�d d �Zedd �d d ��Zd'dddd�dd�Z dd �dd�Z dd �dd�Z dd �dd�Z d(ddd �d d �Z d d �d d!�Zd)d"d d#�d$d%�ZdS )*rr z�A :class:`_engine.Result` that gets data from a Python iterator of :class:`_engine.Row` objects or similar row-like data. .. versionadded:: 1.4 FNr+ z(Iterator[_InterimSupportsScalarsRowType]r� rD )r �iterator�rawr� c C s || _ || _|| _|| _d S r> )r� rt ru r� )r@ r rt ru r� r, r, rA r� � s zIteratorResult.__init__r< c C s | j S )z{Return ``True`` if this :class:`_engine.IteratorResult` has been closed .. versionadded:: 1.4.43 )� _hard_closedr? r, r, rA r& � s zIteratorResult.closedr rQ �r� �kwr= c K sF |r d| _ | jd ur*| jjf d|i|�� tg �| _| �� d| _d S )NTr� )rv ru r� r� rt Z_reset_memoizationsr% �r@ r� rx r, r, rA r� � s zIteratorResult._soft_closer c C s t �d��d S )Nz This result object is closed.)r ZResourceClosedErrorr? r, r, rA �_raise_hard_closed� s z!IteratorResult._raise_hard_closedr> c C s | j S r> )rt r? r, r, rA r? � s z IteratorResult._raw_row_iteratorc C s | j r| �� | jS r> )rv rz rt r? r, r, rA r� � s z IteratorResult._fetchiter_implr� r� c C s: | j r| �� t| jt�}|tu r2| j|d� d S |S d S r^ )rv rz �nextrt r� r� )r@ r� r� r, r, rA r� � s z IteratorResult._fetchone_implr� c C s2 | j r| �� zt| j�W | �� S | �� 0 d S r> )rv rz r� rt r� r? r, r, rA r� � s �z IteratorResult._fetchall_implrW r� c C s" | j r| �� tt�| jd|��S rs )rv rz r� � itertools�islicert r� r, r, rA r� � s z IteratorResult._fetchmany_impl)NF)F)F)N)rz r{ r| r} rv r% r� r� r& r� rz r? r� r� r� r� r, r, r, rA rr � s" � � �rr zIteratorResult[Any]r< c C s t tg �tg ��S r> )rr r� r� r, r, r, rA � null_result� s r~ c sn e Zd ZdZddddddd�d d �Zed d d �dd��Zddddd�� fdd� Zd ddd�� fdd� Z� Z S ) �ChunkedIteratorResulta� An :class:`_engine.IteratorResult` that works from an iterator-producing callable. The given ``chunks`` argument is a function that is given a number of rows to return in each chunk, or ``None`` for all rows. The function should then return an un-consumed iterator of lists, each list of the requested size. The function can be called at any time again, in which case it should continue from the same result set but adjust the chunk size as given. .. versionadded:: 1.4 FNr+ zBCallable[[Optional[int]], Iterator[Sequence[_InterimRowType[_R]]]]rD r� )r �chunks�source_supports_scalarsru �dynamic_yield_perc C s6 || _ || _|| _|| _tj�| �d ��| _|| _d S r> ) r� r� r� ru r| �chain� from_iterablert r� )r@ r r� r� ru r� r, r, rA r� s z ChunkedIteratorResult.__init__rk r# r' c C s || _ tj�| �|��| _| S r> )r r| r� r� r� rt r( r, r, rA r) s z ChunkedIteratorResult.yield_perr rQ rw c s$ t � jf d|i|�� dd� | _d S )Nr� c S s g S r> r, r` r, r, rA �<lambda># r� z3ChunkedIteratorResult._soft_close.<locals>.<lambda>)�superr� r� ry �r� r, rA r� ! s z!ChunkedIteratorResult._soft_closerW r� r� c s( | j rtj�| �|��| _t� j|d�S r_ )r� r| r� r� r� rt r� r� r� r� r, rA r� % s z%ChunkedIteratorResult._fetchmany_impl)FNF)F)N) rz r{ r| r} r� r r) r� r� � __classcell__r, r, r� rA r � s � �r c sJ e Zd ZU dZdZded< ddd�� fdd � Zdd d d d �dd�Z� ZS )r[ z�A :class:`_engine.Result` that is merged from any number of :class:`_engine.Result` objects. Returned by the :meth:`_engine.Result.merge` method. .. versionadded:: 1.4 FrW Zrowcountr+ zSequence[Result[_TP]])r �resultsc sf || _ t� �|tj�dd� |D ��� |d j| _|d j| _|d j| _| j j dd� |D �� | _ d S )Nc s s | ]}|� � V qd S r> )r? �rm �rr, r, rA r� @ s z(MergedResult.__init__.<locals>.<genexpr>r c S s g | ] }|j �qS r, )r r� r, r, rA r� L r� z)MergedResult.__init__.<locals>.<listcomp>) �_resultsr� r� r| r� r� r� r r� r Z merge_with)r@ r r� r� r, rA r� : s �� �zMergedResult.__init__rD r rQ rw c K s. | j D ]}|jf d|i|�� q|r*d| _d S )Nr� T)r� r� r& )r@ r� rx r� r, r, rA r� O s zMergedResult._soft_close)F) rz r{ r| r} r& r r� r� r� r, r, r� rA r[ - s r[ )N)Xr} � __future__r �enumr r� r| rd �typingr r r r r r r r r r r r r r r r r r r� r r � r r Zsql.baser r r r r Z util._has_cyr! Z util.typingr" r# Z_py_rowr$ Z"sqlalchemy.cyextension.resultproxyZ sql.elementsr% Z sql.type_apir& r� Z_KeyTyperk rV rS r3 Z_RowDataZ _RawRowTyper' r) r* Z_InterimRowTypeZ _InterimSupportsScalarsRowTypeZ_ProcessorsTyperh Z_UniqueFilterTyper r+ �KeysViewr; r� r� r� r� r� r r r] r7 Z TypingOnlyrd r: rX rr r~ r r[ r, r, r, rA �<module> s� x" � ` /` $ PS9 sqlalchemy/engine/__pycache__/characteristics.cpython-39.pyc 0000644 00000012760 15125143220 0020170 0 ustar 00 a ��Jh� � @ s� d dl mZ d dlZd dlZd dlmZ d dlmZ ejr^ddlmZ ddl m Z ddl m Z G d d � d ej �Z G d d � d e �ZG d d� de �ZdS )� )� annotationsN)�Any)�ClassVar� )� Connection)�DBAPIConnection)�Dialectc @ s� e Zd ZU dZdZdZded< ejdddd �d d ��Z ejddd dd �dd��Z dddd dd�dd�Z ejddd d �dd��Z dddd d�dd�Z dS )�ConnectionCharacteristica� An abstract base for an object that can set, get and reset a per-connection characteristic, typically one that gets reset when the connection is returned to the connection pool. transaction isolation is the canonical example, and the ``IsolationLevelCharacteristic`` implementation provides this for the ``DefaultDialect``. The ``ConnectionCharacteristic`` class should call upon the ``Dialect`` for the implementation of each method. The object exists strictly to serve as a dialect visitor that can be placed into the ``DefaultDialect.connection_characteristics`` dictionary where it will take effect for calls to :meth:`_engine.Connection.execution_options` and related APIs. .. versionadded:: 1.4 � F�ClassVar[bool]� transactionalr r �None��dialect� dbapi_conn�returnc C s dS )zNReset the characteristic on the DBAPI connection to its default value.Nr ��selfr r r r �V/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/engine/characteristics.py�reset_characteristic, s z-ConnectionCharacteristic.reset_characteristicr �r r �valuer c C s dS )z<set characteristic on the DBAPI connection to a given value.Nr �r r r r r r r �set_characteristic3 s z+ConnectionCharacteristic.set_characteristicr �r �connr r r c C s | � |||� dS )z�set characteristic on the :class:`_engine.Connection` to a given value. .. versionadded:: 2.0.30 - added to support elements that are local to the :class:`_engine.Connection` itself. N)r �r r r r r r r r � set_connection_characteristic9 s z6ConnectionCharacteristic.set_connection_characteristicc C s dS )zXGiven a DBAPI connection, get the current value of the characteristic. Nr r r r r �get_characteristicI s z+ConnectionCharacteristic.get_characteristic�r r r r c C s | � ||�S )z�Given a :class:`_engine.Connection`, get the current value of the characteristic. .. versionadded:: 2.0.30 - added to support elements that are local to the :class:`_engine.Connection` itself. )r �r r r r r r r � get_connection_characteristicR s z6ConnectionCharacteristic.get_connection_characteristicN)�__name__� __module__� __qualname__�__doc__� __slots__r �__annotations__�abc�abstractmethodr r r r r! r r r r r s r c @ sV e Zd ZU dZdZded< dddd�d d �Zddd dd �d d�Zddd d�dd�ZdS )� IsolationLevelCharacteristicz0Manage the isolation level on a DBAPI connectionTr r r r r r c C s |� |� d S �N)Zreset_isolation_levelr r r r r d s z1IsolationLevelCharacteristic.reset_characteristicr r c C s |� ||� d S r+ )Z _assert_and_set_isolation_levelr r r r r i s z/IsolationLevelCharacteristic.set_characteristicc C s |� |�S r+ )Zget_isolation_levelr r r r r n s z/IsolationLevelCharacteristic.get_characteristicN) r" r# r$ r% r r' r r r r r r r r* _ s r* c @ s� e Zd ZU dZdZded< dddd�d d �Zddd dd �d d�Zdddd dd�dd�Zddd d�dd�Z dddd d�dd�Z dS )�LoggingTokenCharacteristiczgManage the 'logging_token' option of a :class:`_engine.Connection`. .. versionadded:: 2.0.30 Fr r r r r r c C s d S r+ r r r r r r } s z/LoggingTokenCharacteristic.reset_characteristicr r c C s t � �d S r+ ��NotImplementedErrorr r r r r � s z-LoggingTokenCharacteristic.set_characteristicr r c s � r� fdd�|_ n|` d S )Nc s d� | f S )Nz[%s] %sr )�msg�r r r �<lambda>� � zJLoggingTokenCharacteristic.set_connection_characteristic.<locals>.<lambda>)Z_message_formatterr r r0 r r � s z8LoggingTokenCharacteristic.set_connection_characteristicc C s t � �d S r+ r- r r r r r � s z-LoggingTokenCharacteristic.get_characteristicr c C s |j �dd �S )NZ logging_token)Z_execution_options�getr r r r r! � s z8LoggingTokenCharacteristic.get_connection_characteristicN) r" r# r$ r% r r' r r r r r! r r r r r, t s r, )� __future__r r( �typingr r � TYPE_CHECKING�baser Z interfacesr r �ABCr r* r, r r r r �<module> s K sqlalchemy/engine/__pycache__/processors.cpython-39.pyc 0000644 00000002160 15125143220 0017210 0 ustar 00 a ��JhK � @ s� d Z ddlmZ ddlZddlmZ ddlmZ ejs:es�ddlm Z dd lm Z dd lm Z dd lm Z dd lm Z dd lmZ ddlmZ n\ddlmZ ddlm Z dd lm Z dd lm Z dd lm Z dd lmZ ddlmZ dd� Z dS )z�defines generic type conversion functions, as used in bind and result processors. They all share one common characteristic: None is passed through unchanged. � )� annotationsN� )�!str_to_datetime_processor_factory� )�HAS_CYEXTENSION)�int_to_boolean)� str_to_date)�str_to_datetime)� str_to_time)� to_decimal_processor_factory)�to_float)�to_str)�DecimalResultProcessorc C s t | d| �jS )Nz%%.%df)r �process)Z target_classZscale� r �Q/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/engine/processors.pyr 7 s r )�__doc__� __future__r �typingZ_py_processorsr Z util._has_cyr � TYPE_CHECKINGr r r r r r r Z!sqlalchemy.cyextension.processorsr r r r r �<module> s( sqlalchemy/engine/__pycache__/reflection.cpython-39.pyc 0000644 00000170505 15125143220 0017151 0 ustar 00 a ��Jh-' � @ s� d Z ddlmZ ddlZddlmZ ddlmZ ddlmZ ddlm Z ddl m Z dd l m Z dd l m Z dd l mZ dd l mZ dd l mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddl mZ ddlmZ ddlmZ ddl m Z ddl m Z dd l m Z dd l m Z dd l m!Z! dd l m"Z# dd l$m%Z% dd!l&m'Z' dd"l&m(Z( dd#l)m*Z* dd$l+m,Z, dd%l m-Z- dd&l.m/Z/ e�rdd'l0m1Z1 dd(l0m2Z2 dd)l0m3Z3 dd*l0m4Z4 dd+l0m5Z5 dd,l0m6Z6 dd-l0m7Z7 dd.l0m8Z8 dd/l0m9Z9 ed0�Z:e j;d1d2d3d4d4d0d5�d6d7��Z<d8d9d:�d;d<�Z=e G d=d>� d>e��Z>e G d?d@� d@e��Z?e j@G dAdB� dBe jAdB ��ZBe/G dCdD� dD��ZCeG dEdF� dF��ZDdS )Ga� Provides an abstraction for obtaining database schema information. Usage Notes: Here are some general conventions when accessing the low level inspector methods such as get_table_names, get_columns, etc. 1. Inspector methods return lists of dicts in most cases for the following reasons: * They're both standard types that can be serialized. * Using a dict instead of a tuple allows easy expansion of attributes. * Using a list for the outer structure maintains order and is easy to work with (e.g. list comprehension [d['name'] for d in cols]). 2. Records that contain a name, such as the column name in a column record use the key 'name'. So for most return values, each record will have a 'name' attribute.. � )� annotationsN)� dataclass)�auto)�Flag)�unique)�Any)�Callable)� Collection)�Dict)� Generator)�Iterable)�List)�Optional)�Sequence)�Set)�Tuple)� TYPE_CHECKING)�TypeVar)�Union� )� Connection)�Engine� )�exc)� inspection)�sql)�util)� operators)�schema)�_ad_hoc_cache_key_from_args)� quoted_name)� TextClause)� TypeEngine)�InternalTraversal)� topological)�final)�Dialect)�ReflectedCheckConstraint)�ReflectedColumn)� ReflectedForeignKeyConstraint)�ReflectedIndex)� ReflectedPrimaryKeyConstraint)�ReflectedTableComment)�ReflectedUniqueConstraint)�TableKey�_R�Callable[..., _R]r& r r ��fn�self�con�args�kw�returnc s� |� dd �}|d u r,| ||g|�R i |��S ddh� | jtdd� |D ��t� fdd�|�� D ��f}|� |�}|d u r�| ||g|�R i |��}|||< |S )N� info_cache� unreflectablec s s4 | ],}t |t�rt |t�r(t|�|jfn|V qd S �N)� isinstance�strr �quote)�.0�a� r@ �Q/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/engine/reflection.py� <genexpr>] s �zcache.<locals>.<genexpr>c 3 s: | ]2\}}|� vr|t |t�r,t|�|jfn|fV qd S r: )r; r r< r= )r> �k�v��excluder@ rA rB b s �)�get�__name__�tuple�items�r2 r3 r4 r5 r6 r8 �key�retr@ rE rA �cacheO s" � �� rN z Tuple[str, InternalTraversal]z0Callable[[Callable[..., _R]], Callable[..., _R]])� traverse_argsr7 c s& t jddddddd�� fdd� �}|S ) Nr0 r& r r r/ r1 c sr |� dd �}|d u r,| ||g|�R i |��S t| jf� |�}|� |�}|d u rn| ||g|�R i |��}|||< |S )Nr8 )rG r rH rK �rO r@ rA �gor s zflexi_cache.<locals>.go)r � decorator)rO rQ r@ rP rA � flexi_cacheo s rS c @ s6 e Zd ZdZe� Ze� Ze� ZeeB ZeeB eB Z dS )� ObjectKinda� Enumerator that indicates which kind of object to return when calling the ``get_multi`` methods. This is a Flag enum, so custom combinations can be passed. For example, to reflect tables and plain views ``ObjectKind.TABLE | ObjectKind.VIEW`` may be used. .. note:: Not all dialect may support all kind of object. If a dialect does not support a particular object an empty dict is returned. In case a dialect supports an object, but the requested method is not applicable for the specified kind the default value will be returned for each reflected object. For example reflecting check constraints of view return a dict with all the views with empty lists as values. N) rH � __module__� __qualname__�__doc__r �TABLEZVIEWZMATERIALIZED_VIEWZANY_VIEW�ANYr@ r@ r@ rA rT � s rT c @ s$ e Zd ZdZe� Ze� ZeeB ZdS )� ObjectScopez]Enumerator that indicates which scope to use when calling the ``get_multi`` methods. N)rH rU rV rW r �DEFAULT� TEMPORARYrY r@ r@ r@ rA rZ � s rZ c @ s@ e Zd ZU dZded< ded< ded< ded < d ed < e�d d �dd�dd��Zeddd d�dd��Z ddd�dd�Z ddd�dd�Z d dd �d d �Z dd �d!d"�Z ee�d d#�dd d�d$d%���Ze�e�dd d�d&d'��Ze�e�d d d�d(d)��Zejd*d �d+d,��Zejd-d �d.d/��Zed0d �d1d2��Zd3d4d5�d6d7�Zd�d0d3d4d9�d:d;�Z d�d<d0d3dd=�d>d?�Z d�d<d0d3dd@�dAdB�Z d�d<d<d0d3ddC�dDdE�Z d<d3ddF�dGdH�Z d�d0d3dId9�dJdK�Z!d�dMd3dNdO�dPdQ�Z"d3d4d5�dRdS�Z#d3d4d5�dTdU�Z$d�d<d0d3dVd=�dWdX�Z%d8d8e&j'e(j)fd0dYdZd[d3d\d]�d^d_�Z*d�d0d3d4d9�d`da�Z+d�d0d3d4d9�dbdc�Z,d�d0d3d4d9�ddde�Z-d�d<d0d3d<df�dgdh�Z.d�d<d0d3did=�djdk�Z/dlddm�dndo�Z0d8d8e&j'e(j)fd0dYdZd[d3dpd]�dqdr�Z1d�d<d0d3dsd=�dtdu�Z2d8d8e&j'e(j)fd0dYdZd[d3dvd]�dwdx�Z3d�d<d0d3dyd=�dzd{�Z4d8d8e&j'e(j)fd0dYdZd[d3d|d]�d}d~�Z5d�d<d0d3dd=�d�d��Z6d8d8e&j'e(j)fd0dYdZd[d3d�d]�d�d��Z7d�d<d0d3d�d=�d�d��Z8d8d8e&j'e(j)fd0dYdZd[d3d�d]�d�d��Z9d�d<d0d3d�d=�d�d��Z:d8d8e&j'e(j)fd0dYdZd[d3d�d]�d�d��Z;d�d<d0d3d�d=�d�d��Z<d8d8e&j'e(j)fd0dYdZd[d3d�d]�d�d��Z=d�d�d�d�dd�d�dd��d�d��Z>d�d�d�d�d�dd��d�d��Z?d�d�d�d�d�dd��d�d��Z@d�d�d�d�d�d�dd�dVdd�� d�d��ZAeBjCeBjDeBjEeBjFd��ZGd�d�d�d�d�d�dVdd��d�d��ZHd�d�d�d�d�d�dVdd��d�d��ZId�d�d�d�d�d�dVdd��d�d��ZJd�d�d�dVdd��d�d��ZKd�d0d�d�d�d3d�d��d�d��ZLd8S )�� Inspectora= Performs database schema inspection. The Inspector acts as a proxy to the reflection methods of the :class:`~sqlalchemy.engine.interfaces.Dialect`, providing a consistent interface as well as caching support for previously fetched metadata. A :class:`_reflection.Inspector` object is usually created via the :func:`_sa.inspect` function, which may be passed an :class:`_engine.Engine` or a :class:`_engine.Connection`:: from sqlalchemy import inspect, create_engine engine = create_engine("...") insp = inspect(engine) Where above, the :class:`~sqlalchemy.engine.interfaces.Dialect` associated with the engine may opt to return an :class:`_reflection.Inspector` subclass that provides additional methods specific to the dialect's target database. zUnion[Engine, Connection]�bindr �engine�bool� _op_context_requires_connectr& �dialectzDict[Any, Any]r8 z1.4a The __init__() method on :class:`_reflection.Inspector` is deprecated and will be removed in a future release. Please use the :func:`.sqlalchemy.inspect` function on an :class:`_engine.Engine` or :class:`_engine.Connection` in order to acquire an :class:`_reflection.Inspector`.�r^ c C s | � |� dS )a� Initialize a new :class:`_reflection.Inspector`. :param bind: a :class:`~sqlalchemy.engine.Connection`, which is typically an instance of :class:`~sqlalchemy.engine.Engine` or :class:`~sqlalchemy.engine.Connection`. For a dialect-specific instance of :class:`_reflection.Inspector`, see :meth:`_reflection.Inspector.from_engine` N)� _init_legacy�r3 r^ r@ r@ rA �__init__� s zInspector.__init__zCallable[..., Any])�initr^ r7 c C s, t |jd�r|jj} | �| �}|||� |S )N� inspector)�hasattrrb rh �__new__)�clsrg r^ r3 r@ r@ rA � _construct� s zInspector._construct�None)r^ r7 c C s$ t |d�r| �|� n | �|� d S )NZexec_driver_sql)ri �_init_connection� _init_enginere r@ r@ rA rd � s zInspector._init_legacy)r_ r7 c C s2 | | _ | _|�� �� d| _| jj| _i | _d S )NT)r^ r_ �connect�closera rb r8 )r3 r_ r@ r@ rA ro � s zInspector._init_enginer )� connectionr7 c C s( || _ |j| _d| _| jj| _i | _d S )NF)r^ r_ ra rb r8 )r3 rr r@ r@ rA rn s zInspector._init_connection�r7 c C s | j �� dS )z�reset the cache for this :class:`.Inspector`. Inspection methods that have data cached will emit SQL queries when next called to get new data. .. versionadded:: 2.0 N)r8 �clear�r3 r@ r@ rA � clear_cache s zInspector.clear_cachea The from_engine() method on :class:`_reflection.Inspector` is deprecated and will be removed in a future release. Please use the :func:`.sqlalchemy.inspect` function on an :class:`_engine.Engine` or :class:`_engine.Connection` in order to acquire an :class:`_reflection.Inspector`.c C s | � | j|�S )aZ Construct a new dialect-specific Inspector object from the given engine or connection. :param bind: a :class:`~sqlalchemy.engine.Connection` or :class:`~sqlalchemy.engine.Engine`. This method differs from direct a direct constructor call of :class:`_reflection.Inspector` in that the :class:`~sqlalchemy.engine.interfaces.Dialect` is given a chance to provide a dialect-specific :class:`_reflection.Inspector` instance, which may provide additional methods. See the example at :class:`_reflection.Inspector`. )rl rd )rk r^ r@ r@ rA � from_engine s zInspector.from_enginec C s t �t j| �S r: )r] rl ro rc r@ r@ rA � _engine_insp7 s zInspector._engine_inspc C s t �t j| �S r: )r] rl rn rc r@ r@ rA �_connection_insp; s zInspector._connection_inspz!Generator[Connection, None, None]c c sF | j r| j�� }n| j}z|V W | j rB|�� n| j r@|�� 0 dS )a Return a context that optimizes for multiple operations on a single transaction. This essentially allows connect()/close() to be called if we detected that we're against an :class:`_engine.Engine` and not a :class:`_engine.Connection`. N)ra r^ rp rq )r3 �connr@ r@ rA �_operation_context? s �z Inspector._operation_contextz Generator[Inspector, None, None]c c sJ | � � �.}| �| jj|�}| j|_|V W d � n1 s<0 Y dS )z�Return an :class:`_reflection.Inspector` from this one that will run all operations on a single connection. N)r{ rl � __class__rn r8 )r3 rz Zsub_inspr@ r@ rA �_inspection_contextT s z Inspector._inspection_contextz Optional[str]c C s | j jS )z�Return the default schema name presented by the dialect for the current engine's database user. E.g. this is typically ``public`` for PostgreSQL and ``dbo`` for SQL Server. )rb �default_schema_nameru r@ r@ rA r~ a s z Inspector.default_schema_namer z List[str])r6 r7 c K sF | � � �*}| jj|fd| ji|��W d � S 1 s80 Y dS )z�Return all schema names. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. r8 N)r{ rb �get_schema_namesr8 �r3 r6 rz r@ r@ rA r l s ���zInspector.get_schema_namesN)r r6 r7 c K sH | � � �,}| jj||fd| ji|��W d � S 1 s:0 Y dS )a� Return all table names within a particular schema. The names are expected to be real tables only, not views. Views are instead returned using the :meth:`_reflection.Inspector.get_view_names` and/or :meth:`_reflection.Inspector.get_materialized_view_names` methods. :param schema: Schema name. If ``schema`` is left at ``None``, the database's default schema is used, else the named schema is searched. If the database does not support named schemas, behavior is undefined if ``schema`` is not passed as ``None``. For special quoting, use :class:`.quoted_name`. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. .. seealso:: :meth:`_reflection.Inspector.get_sorted_table_and_fkc_names` :attr:`_schema.MetaData.sorted_tables` r8 N)r{ rb �get_table_namesr8 �r3 r r6 rz r@ r@ rA r� y s ���zInspector.get_table_namesr< )� table_namer r6 r7 c K sJ | � � �.}| jj|||fd| ji|��W d � S 1 s<0 Y dS )a Return True if the backend has a table, view, or temporary table of the given name. :param table_name: name of the table to check :param schema: schema name to query, if not the default schema. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. .. versionadded:: 1.4 - the :meth:`.Inspector.has_table` method replaces the :meth:`_engine.Engine.has_table` method. .. versionchanged:: 2.0:: :meth:`.Inspector.has_table` now formally supports checking for additional table-like objects: * any type of views (plain or materialized) * temporary tables of any kind Previously, these two checks were not formally specified and different dialects would vary in their behavior. The dialect testing suite now includes tests for all of these object types and should be supported by all SQLAlchemy-included dialects. Support among third party dialects may be lagging, however. r8 N)r{ rb � has_tabler8 �r3 r� r r6 rz r@ r@ rA r� � s ���zInspector.has_table)� sequence_namer r6 r7 c K sJ | � � �.}| jj|||fd| ji|��W d � S 1 s<0 Y dS )a� Return True if the backend has a sequence with the given name. :param sequence_name: name of the sequence to check :param schema: schema name to query, if not the default schema. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. .. versionadded:: 1.4 r8 N)r{ rb � has_sequencer8 )r3 r� r r6 rz r@ r@ rA r� � s ���zInspector.has_sequence)r� � index_namer r6 r7 c K sL | � � �0}| jj||||fd| ji|��W d � S 1 s>0 Y dS )a� Check the existence of a particular index name in the database. :param table_name: the name of the table the index belongs to :param index_name: the name of the index to check :param schema: schema name to query, if not the default schema. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. .. versionadded:: 2.0 r8 N)r{ rb � has_indexr8 )r3 r� r� r r6 rz r@ r@ rA r� � s ���zInspector.has_index)� schema_namer6 r7 c K sH | � � �,}| jj||fd| ji|��W d � S 1 s:0 Y dS )aT Return True if the backend has a schema with the given name. :param schema_name: name of the schema to check :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. .. versionadded:: 2.0 r8 N)r{ rb � has_schemar8 )r3 r� r6 rz r@ r@ rA r� � s ���zInspector.has_schemaz;List[Tuple[Optional[str], List[Tuple[str, Optional[str]]]]]c K s dd� | j |fd�D �S )ag Return dependency-sorted table and foreign key constraint names in referred to within a particular schema. This will yield 2-tuples of ``(tablename, [(tname, fkname), (tname, fkname), ...])`` consisting of table names in CREATE order grouped with the foreign key constraint names that are not detected as belonging to a cycle. The final element will be ``(None, [(tname, fkname), (tname, fkname), ..])`` which will consist of remaining foreign key constraint names that would require a separate CREATE step after-the-fact, based on dependencies between tables. :param schema: schema name to query, if not the default schema. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. .. seealso:: :meth:`_reflection.Inspector.get_table_names` :func:`.sort_tables_and_constraints` - similar method which works with an already-given :class:`_schema.MetaData`. c S s. g | ]&\}}|r|d nddd� |D �f�qS )r Nc S s g | ]\\}}}||f�qS r@ r@ )r> �_�tnameZfksr@ r@ rA � <listcomp> � zGInspector.get_sorted_table_and_fkc_names.<locals>.<listcomp>.<listcomp>r@ )r> � table_keyZ fk_collectionr@ r@ rA r� s � �z<Inspector.get_sorted_table_and_fkc_names.<locals>.<listcomp>)�consider_schemas)�%sort_tables_on_foreign_key_dependency)r3 r r6 r@ r@ rA � get_sorted_table_and_fkc_names� s ��z(Inspector.get_sorted_table_and_fkc_namesr: zCollection[Optional[str]]zgList[Tuple[Optional[Tuple[Optional[str], str]], List[Tuple[Tuple[Optional[str], str], Optional[str]]]]])r� r6 r7 c s` t tt tf }t� }t� �i �g }|D ]�}| j|fi |��}|�|� |�� D ]b\\}} } dd� | D ��|| f< | D ]:} | | d ks�|| d krv|�| d | d f|| ff� qvqPq(ztt � ||��} W nn t j �y8 } zR| j D ].� |�� � ��� fdd��� d D �� q�tt � ||��} W Y d} ~ n d} ~ 0 0 ��fd d �| D �}|dt��fg S ) a� Return dependency-sorted table and foreign key constraint names referred to within multiple schemas. This method may be compared to :meth:`.Inspector.get_sorted_table_and_fkc_names`, which works on one schema at a time; here, the method is a generalization that will consider multiple schemas at once including that it will resolve for cross-schema foreign keys. .. versionadded:: 2.0 c S s h | ] }|d �qS )�namer@ �r> Zfkr@ r@ rA � <setcomp>I s zBInspector.sort_tables_on_foreign_key_dependency.<locals>.<setcomp>�referred_table�referred_schemac 3 s | ]}� d |fV qdS )r Nr@ )r> Zfkc)�edger@ rA rB ` s zBInspector.sort_tables_on_foreign_key_dependency.<locals>.<genexpr>r Nc sD g | ]<\� �� �f� �fd d��� �f � dd� �D ��D �f�qS )c s g | ]}� �f|f�qS r@ r@ r� ��schnamer� r@ rA r� k s �zNInspector.sort_tables_on_foreign_key_dependency.<locals>.<listcomp>.<listcomp>c s s | ]\}}|V qd S r: r@ )r> r� r� r@ r@ rA rB m s zMInspector.sort_tables_on_foreign_key_dependency.<locals>.<listcomp>.<genexpr>)� difference)r> )�fknames_for_table�remaining_fkcsr� rA r� h s � ���zCInspector.sort_tables_on_foreign_key_dependency.<locals>.<listcomp>)r r r< �set�get_multi_foreign_keys�extendrJ �add�listr$ �sortr ZCircularDependencyError�edges�remove�update)r3 r� r6 Z SchemaTabZtuplesZtnamesr� Z schema_fkeysr� r� �fkeysZfkeyZcandidate_sort�errrM r@ )r� r� r� rA r� ( sJ � � ���� � & � z/Inspector.sort_tables_on_foreign_key_dependencyc K sF | � � �*}| jj|fd| ji|��W d � S 1 s80 Y dS )a� Return a list of temporary table names for the current bind. This method is unsupported by most dialects; currently only Oracle Database, PostgreSQL and SQLite implements it. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. r8 N)r{ rb �get_temp_table_namesr8 r� r@ r@ rA r� v s ���z Inspector.get_temp_table_namesc K sF | � � �*}| jj|fd| ji|��W d � S 1 s80 Y dS )an Return a list of temporary view names for the current bind. This method is unsupported by most dialects; currently only PostgreSQL and SQLite implements it. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. r8 N)r{ rb �get_temp_view_namesr8 r� r@ r@ rA r� � s ���z Inspector.get_temp_view_names�Dict[str, Any]c K sJ | � � �.}| jj|||fd| ji|��W d � S 1 s<0 Y dS )az Return a dictionary of options specified when the table of the given name was created. This currently includes some options that apply to MySQL and Oracle Database tables. :param table_name: string name of the table. For special quoting, use :class:`.quoted_name`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a dict with the table options. The returned keys depend on the dialect in use. Each one is prefixed with the dialect name. .. seealso:: :meth:`Inspector.get_multi_table_options` r8 N)r{ rb �get_table_optionsr8 r� r@ r@ rA r� � s ���zInspector.get_table_optionszOptional[Sequence[str]]rT rZ � Dict[TableKey, Dict[str, Any]])r � filter_names�kind�scoper6 r7 c K sV | � � �:}| jj|f||||| jd�|��}t|�W d � S 1 sH0 Y dS )a� Return a dictionary of options specified when the tables in the given schema were created. The tables can be filtered by passing the names to use to ``filter_names``. This currently includes some options that apply to MySQL and Oracle tables. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param filter_names: optionally return information only for the objects listed here. :param kind: a :class:`.ObjectKind` that specifies the type of objects to reflect. Defaults to ``ObjectKind.TABLE``. :param scope: a :class:`.ObjectScope` that specifies if options of default, temporary or any tables should be reflected. Defaults to ``ObjectScope.DEFAULT``. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a dictionary where the keys are two-tuple schema,table-name and the values are dictionaries with the table options. The returned keys in each dict depend on the dialect in use. Each one is prefixed with the dialect name. The schema is ``None`` if no schema is provided. .. versionadded:: 2.0 .. seealso:: :meth:`Inspector.get_table_options` �r r� r� r� r8 N)r{ rb �get_multi_table_optionsr8 �dict)r3 r r� r� r� r6 rz �resr@ r@ rA r� � s - ��� z!Inspector.get_multi_table_optionsc K sH | � � �,}| jj||fd| ji|��W d � S 1 s:0 Y dS )a Return all non-materialized view names in `schema`. :param schema: Optional, retrieve names from a non-default schema. For special quoting, use :class:`.quoted_name`. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. .. versionchanged:: 2.0 For those dialects that previously included the names of materialized views in this list (currently PostgreSQL), this method no longer returns the names of materialized views. the :meth:`.Inspector.get_materialized_view_names` method should be used instead. .. seealso:: :meth:`.Inspector.get_materialized_view_names` r8 N)r{ rb �get_view_namesr8 r� r@ r@ rA r� � s ���zInspector.get_view_namesc K sH | � � �,}| jj||fd| ji|��W d � S 1 s:0 Y dS )a� Return all materialized view names in `schema`. :param schema: Optional, retrieve names from a non-default schema. For special quoting, use :class:`.quoted_name`. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. .. versionadded:: 2.0 .. seealso:: :meth:`.Inspector.get_view_names` r8 N)r{ rb �get_materialized_view_namesr8 r� r@ r@ rA r� s ���z%Inspector.get_materialized_view_namesc K sH | � � �,}| jj||fd| ji|��W d � S 1 s:0 Y dS )ak Return all sequence names in `schema`. :param schema: Optional, retrieve names from a non-default schema. For special quoting, use :class:`.quoted_name`. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. r8 N)r{ rb �get_sequence_namesr8 r� r@ r@ rA r� $ s ���z Inspector.get_sequence_names)� view_namer r6 r7 c K sJ | � � �.}| jj|||fd| ji|��W d � S 1 s<0 Y dS )a� Return definition for the plain or materialized view called ``view_name``. :param view_name: Name of the view. :param schema: Optional, retrieve names from a non-default schema. For special quoting, use :class:`.quoted_name`. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. r8 N)r{ rb �get_view_definitionr8 )r3 r� r r6 rz r@ r@ rA r� 6 s ���z Inspector.get_view_definition�List[ReflectedColumn]c K sZ | � � �.}| jj|||fd| ji|��}W d � n1 s<0 Y |rV| �|g� |S )aJ Return information about columns in ``table_name``. Given a string ``table_name`` and an optional string ``schema``, return column information as a list of :class:`.ReflectedColumn`. :param table_name: string name of the table. For special quoting, use :class:`.quoted_name`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: list of dictionaries, each representing the definition of a database column. .. seealso:: :meth:`Inspector.get_multi_columns`. r8 N)r{ rb � get_columnsr8 �_instantiate_types)r3 r� r r6 rz �col_defsr@ r@ rA r� J s ���$ zInspector.get_columnsz Iterable[List[ReflectedColumn]])�datar7 c C s4 |D ]*}|D ] }|d }t |t�s |� |d< q qd S )N�type)r; r" )r3 r� r� Zcol_def�coltyper@ r@ rA r� l s z Inspector._instantiate_types�%Dict[TableKey, List[ReflectedColumn]]c K s` | � � �6}t| jj|f||||| jd�|���}W d � n1 sD0 Y | �|�� � |S )aW Return information about columns in all objects in the given schema. The objects can be filtered by passing the names to use to ``filter_names``. For each table the value is a list of :class:`.ReflectedColumn`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param filter_names: optionally return information only for the objects listed here. :param kind: a :class:`.ObjectKind` that specifies the type of objects to reflect. Defaults to ``ObjectKind.TABLE``. :param scope: a :class:`.ObjectScope` that specifies if columns of default, temporary or any tables should be reflected. Defaults to ``ObjectScope.DEFAULT``. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a dictionary where the keys are two-tuple schema,table-name and the values are list of dictionaries, each representing the definition of a database column. The schema is ``None`` if no schema is provided. .. versionadded:: 2.0 .. seealso:: :meth:`Inspector.get_columns` r� N)r{ r� rb �get_multi_columnsr8 r� �values)r3 r r� r� r� r6 rz Ztable_col_defsr@ r@ rA r� v s , ����" zInspector.get_multi_columnsr+ c K sJ | � � �.}| jj|||fd| ji|��W d � S 1 s<0 Y dS )a` Return information about primary key constraint in ``table_name``. Given a string ``table_name``, and an optional string `schema`, return primary key information as a :class:`.ReflectedPrimaryKeyConstraint`. :param table_name: string name of the table. For special quoting, use :class:`.quoted_name`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a dictionary representing the definition of a primary key constraint. .. seealso:: :meth:`Inspector.get_multi_pk_constraint` r8 N)r{ rb �get_pk_constraintr8 r� r@ r@ rA r� � s ���zInspector.get_pk_constraintz-Dict[TableKey, ReflectedPrimaryKeyConstraint]c K sR | � � �6}t| jj|f||||| jd�|���W d � S 1 sD0 Y dS )au Return information about primary key constraints in all tables in the given schema. The tables can be filtered by passing the names to use to ``filter_names``. For each table the value is a :class:`.ReflectedPrimaryKeyConstraint`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param filter_names: optionally return information only for the objects listed here. :param kind: a :class:`.ObjectKind` that specifies the type of objects to reflect. Defaults to ``ObjectKind.TABLE``. :param scope: a :class:`.ObjectScope` that specifies if primary keys of default, temporary or any tables should be reflected. Defaults to ``ObjectScope.DEFAULT``. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a dictionary where the keys are two-tuple schema,table-name and the values are dictionaries, each representing the definition of a primary key constraint. The schema is ``None`` if no schema is provided. .. versionadded:: 2.0 .. seealso:: :meth:`Inspector.get_pk_constraint` r� N)r{ r� rb �get_multi_pk_constraintr8 �r3 r r� r� r� r6 rz r@ r@ rA r� � s + ����z!Inspector.get_multi_pk_constraint�#List[ReflectedForeignKeyConstraint]c K sJ | � � �.}| jj|||fd| ji|��W d � S 1 s<0 Y dS )ag Return information about foreign_keys in ``table_name``. Given a string ``table_name``, and an optional string `schema`, return foreign key information as a list of :class:`.ReflectedForeignKeyConstraint`. :param table_name: string name of the table. For special quoting, use :class:`.quoted_name`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a list of dictionaries, each representing the a foreign key definition. .. seealso:: :meth:`Inspector.get_multi_foreign_keys` r8 N)r{ rb �get_foreign_keysr8 r� r@ r@ rA r� s ���zInspector.get_foreign_keys�3Dict[TableKey, List[ReflectedForeignKeyConstraint]]c K sR | � � �6}t| jj|f||||| jd�|���W d � S 1 sD0 Y dS )ao Return information about foreign_keys in all tables in the given schema. The tables can be filtered by passing the names to use to ``filter_names``. For each table the value is a list of :class:`.ReflectedForeignKeyConstraint`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param filter_names: optionally return information only for the objects listed here. :param kind: a :class:`.ObjectKind` that specifies the type of objects to reflect. Defaults to ``ObjectKind.TABLE``. :param scope: a :class:`.ObjectScope` that specifies if foreign keys of default, temporary or any tables should be reflected. Defaults to ``ObjectScope.DEFAULT``. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a dictionary where the keys are two-tuple schema,table-name and the values are list of dictionaries, each representing a foreign key definition. The schema is ``None`` if no schema is provided. .. versionadded:: 2.0 .. seealso:: :meth:`Inspector.get_foreign_keys` r� N)r{ r� rb r� r8 r� r@ r@ rA r� % s - ����z Inspector.get_multi_foreign_keys�List[ReflectedIndex]c K sJ | � � �.}| jj|||fd| ji|��W d � S 1 s<0 Y dS )a= Return information about indexes in ``table_name``. Given a string ``table_name`` and an optional string `schema`, return index information as a list of :class:`.ReflectedIndex`. :param table_name: string name of the table. For special quoting, use :class:`.quoted_name`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a list of dictionaries, each representing the definition of an index. .. seealso:: :meth:`Inspector.get_multi_indexes` r8 N)r{ rb � get_indexesr8 r� r@ r@ rA r� _ s ���zInspector.get_indexes�$Dict[TableKey, List[ReflectedIndex]]c K sR | � � �6}t| jj|f||||| jd�|���W d � S 1 sD0 Y dS )aP Return information about indexes in in all objects in the given schema. The objects can be filtered by passing the names to use to ``filter_names``. For each table the value is a list of :class:`.ReflectedIndex`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param filter_names: optionally return information only for the objects listed here. :param kind: a :class:`.ObjectKind` that specifies the type of objects to reflect. Defaults to ``ObjectKind.TABLE``. :param scope: a :class:`.ObjectScope` that specifies if indexes of default, temporary or any tables should be reflected. Defaults to ``ObjectScope.DEFAULT``. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a dictionary where the keys are two-tuple schema,table-name and the values are list of dictionaries, each representing the definition of an index. The schema is ``None`` if no schema is provided. .. versionadded:: 2.0 .. seealso:: :meth:`Inspector.get_indexes` r� N)r{ r� rb �get_multi_indexesr8 r� r@ r@ rA r� } s , ����zInspector.get_multi_indexes� List[ReflectedUniqueConstraint]c K sJ | � � �.}| jj|||fd| ji|��W d � S 1 s<0 Y dS )a~ Return information about unique constraints in ``table_name``. Given a string ``table_name`` and an optional string `schema`, return unique constraint information as a list of :class:`.ReflectedUniqueConstraint`. :param table_name: string name of the table. For special quoting, use :class:`.quoted_name`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a list of dictionaries, each representing the definition of an unique constraint. .. seealso:: :meth:`Inspector.get_multi_unique_constraints` r8 N)r{ rb �get_unique_constraintsr8 r� r@ r@ rA r� � s ���z Inspector.get_unique_constraints�/Dict[TableKey, List[ReflectedUniqueConstraint]]c K sR | � � �6}t| jj|f||||| jd�|���W d � S 1 sD0 Y dS )a� Return information about unique constraints in all tables in the given schema. The tables can be filtered by passing the names to use to ``filter_names``. For each table the value is a list of :class:`.ReflectedUniqueConstraint`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param filter_names: optionally return information only for the objects listed here. :param kind: a :class:`.ObjectKind` that specifies the type of objects to reflect. Defaults to ``ObjectKind.TABLE``. :param scope: a :class:`.ObjectScope` that specifies if constraints of default, temporary or any tables should be reflected. Defaults to ``ObjectScope.DEFAULT``. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a dictionary where the keys are two-tuple schema,table-name and the values are list of dictionaries, each representing the definition of an unique constraint. The schema is ``None`` if no schema is provided. .. versionadded:: 2.0 .. seealso:: :meth:`Inspector.get_unique_constraints` r� N)r{ r� rb � get_multi_unique_constraintsr8 r� r@ r@ rA r� � s - ����z&Inspector.get_multi_unique_constraintsr, c K sJ | � � �.}| jj|||fd| ji|��W d � S 1 s<0 Y dS )a� Return information about the table comment for ``table_name``. Given a string ``table_name`` and an optional string ``schema``, return table comment information as a :class:`.ReflectedTableComment`. Raises ``NotImplementedError`` for a dialect that does not support comments. :param table_name: string name of the table. For special quoting, use :class:`.quoted_name`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a dictionary, with the table comment. .. versionadded:: 1.2 .. seealso:: :meth:`Inspector.get_multi_table_comment` r8 N)r{ rb �get_table_commentr8 r� r@ r@ rA r� s ���zInspector.get_table_commentz%Dict[TableKey, ReflectedTableComment]c K sR | � � �6}t| jj|f||||| jd�|���W d � S 1 sD0 Y dS )a� Return information about the table comment in all objects in the given schema. The objects can be filtered by passing the names to use to ``filter_names``. For each table the value is a :class:`.ReflectedTableComment`. Raises ``NotImplementedError`` for a dialect that does not support comments. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param filter_names: optionally return information only for the objects listed here. :param kind: a :class:`.ObjectKind` that specifies the type of objects to reflect. Defaults to ``ObjectKind.TABLE``. :param scope: a :class:`.ObjectScope` that specifies if comments of default, temporary or any tables should be reflected. Defaults to ``ObjectScope.DEFAULT``. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a dictionary where the keys are two-tuple schema,table-name and the values are dictionaries, representing the table comments. The schema is ``None`` if no schema is provided. .. versionadded:: 2.0 .. seealso:: :meth:`Inspector.get_table_comment` r� N)r{ r� rb �get_multi_table_commentr8 r� r@ r@ rA r� 1 s / ����z!Inspector.get_multi_table_comment� List[ReflectedCheckConstraint]c K sJ | � � �.}| jj|||fd| ji|��W d � S 1 s<0 Y dS )ay Return information about check constraints in ``table_name``. Given a string ``table_name`` and an optional string `schema`, return check constraint information as a list of :class:`.ReflectedCheckConstraint`. :param table_name: string name of the table. For special quoting, use :class:`.quoted_name`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a list of dictionaries, each representing the definition of a check constraints. .. seealso:: :meth:`Inspector.get_multi_check_constraints` r8 N)r{ rb �get_check_constraintsr8 r� r@ r@ rA r� m s ���z Inspector.get_check_constraints�.Dict[TableKey, List[ReflectedCheckConstraint]]c K sR | � � �6}t| jj|f||||| jd�|���W d � S 1 sD0 Y dS )a� Return information about check constraints in all tables in the given schema. The tables can be filtered by passing the names to use to ``filter_names``. For each table the value is a list of :class:`.ReflectedCheckConstraint`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param filter_names: optionally return information only for the objects listed here. :param kind: a :class:`.ObjectKind` that specifies the type of objects to reflect. Defaults to ``ObjectKind.TABLE``. :param scope: a :class:`.ObjectScope` that specifies if constraints of default, temporary or any tables should be reflected. Defaults to ``ObjectScope.DEFAULT``. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a dictionary where the keys are two-tuple schema,table-name and the values are list of dictionaries, each representing the definition of a check constraints. The schema is ``None`` if no schema is provided. .. versionadded:: 2.0 .. seealso:: :meth:`Inspector.get_check_constraints` r� N)r{ r� rb �get_multi_check_constraintsr8 r� r@ r@ rA r� � s - ����z%Inspector.get_multi_check_constraintsr@ Tzsa_schema.TablezOptional[Collection[str]]zCollection[str]z Optional[Set[sa_schema.Table]]zOptional[_ReflectionInfo])�table�include_columns�exclude_columns� resolve_fks� _extend_on� _reflect_infor7 c s� |dur � |v rdS |� � � | jj}| �� �}|�� �} W d � n1 sN0 Y � j} � fdd�|jD �} | | f} |du s�| |jvr�| j| f| gt j t j |d�� j ��}| |j v r�|j | �| |jvr�t�| ��|jr�|j�| �} | r�� �| � d}i }|j| D ] }d}| �� ||||� �q |�sF| �| | ��sFt�| ��| �|| � ||� | �|| � |||||| � | �|| � |||| � | �|| � |||| � | �|| � |||| � | �|| � | � dS )aZ Given a :class:`_schema.Table` object, load its internal constructs based on introspection. This is the underlying method used by most dialects to produce table reflection. Direct usage is like:: from sqlalchemy import create_engine, MetaData, Table from sqlalchemy import inspect engine = create_engine("...") meta = MetaData() user_table = Table("user", meta) insp = inspect(engine) insp.reflect_table(user_table, None) .. versionchanged:: 1.4 Renamed from ``reflecttable`` to ``reflect_table`` :param table: a :class:`~sqlalchemy.schema.Table` instance. :param include_columns: a list of string column names to include in the reflection process. If ``None``, all columns are reflected. Nc s$ i | ] }|� j v r|� j �|��qS r@ )�dialect_kwargsrG �r> rC �r� r@ rA � <dictcomp>� s �z+Inspector.reflect_table.<locals>.<dictcomp>)r� r� r� r� FT)r� r^ rb r{ Zschema_for_objectr� �reflection_options�columns�_get_reflection_inforT rY rZ r� r9 r ZNoSuchTableError� table_optionsrG Z_validate_dialect_kwargs�_reflect_columnr� � _reflect_pk� _reflect_fk�_reflect_indexes�_reflect_unique_constraints�_reflect_check_constraints�_reflect_table_comment)r3 r� r� r� r� r� r� rb rz r r� r� r� Ztbl_optsZ found_table�cols_by_orig_name�col_dr@ r� rA � reflect_table� s� ! ( ���� � �� � � � �zInspector.reflect_tabler( z Dict[str, sa_schema.Column[Any]])r� r� r� r� r� r7 c s� � d }|j j�| |� � |j�| |� � � d }|r>||vsJ|rN||v rNd S � d }� fdd�dD �} d� v r~| �� d � g } � �d�d ur� d } | d us�J �t| t�r�tj| dd �} n&t| tj �s�tjt � | �dd �} n| } | � | � d � v �rtj f i � d ��} | � | � d � v �r>tjf i � d ��}| � |� tj||g| �R i | �� ||< }|j|jv �rtd|_|j|dd � d S ) Nr� r� c s i | ]}|� v r|� | �qS r@ r@ r� �r� r@ rA r� t s �z-Inspector._reflect_column.<locals>.<dictcomp>)ZnullableZ autoincrementr= �inforL �comment�dialect_options�defaultT)Z _reflected�computed�identity)Zreplace_existing)�metadata�dispatchZcolumn_reflectr� rG r; r! � sa_schemaZ DefaultClauseZ FetchedValuer �text�appendZComputedZIdentityZColumnrL � primary_keyZ append_column)r3 r� r� r� r� r� Z orig_namer� r� Zcol_kwZcolargsZ default_textr� r� r� �colr@ r� rA r� ] s\ �� � � � ���zInspector._reflect_column�_ReflectionInfor. )r� r� r� r� r� r7 c sr |j �|�}|rn� �fdd�|d D �}|�d�|j_|�dd �|j_|�d�}|rb|jj�|� |j�|� d S )Nc s$ g | ] }|� v r|�vr� | �qS r@ r@ )r> �pk�r� r� r@ rA r� � s �z)Inspector._reflect_pk.<locals>.<listcomp>�constrained_columnsr� r� r� )� pk_constraintrG r� r� r� r� r� Z_reload) r3 r� r� r� r� r� Zpk_consZpk_colsr� r@ r rA r� � s � zInspector._reflect_pk) r� r� r� r� r� r� r� r� r� r7 c s� |j �|g �} | D �]|} | d } � fdd�| d D �} |rHt| ��|�s|r\t| ��|�r\q| d }| d }| d }g }|d ur�|r�tj||jf|| j||d�| �� |D ]}|� d � |||g�� q�nF|r�tj||jf| jtj ||d �| �� |D ]}|� d � ||g�� q�d | v �r"| d }ni }z,|� tj | || fd | �d �d�|��� W q tj�y� t�d|j� d| � dd� | �� d�� Y q0 qd S )Nr� c s" g | ]}|� v r� | j n|�qS r@ )rL )r> �c�r� r@ rA r� � s �z)Inspector._reflect_fk.<locals>.<listcomp>r r� r� �referred_columns)r � autoload_withr� r� �.)r r r� r� �optionsTr� )Z link_to_namer� zOn reflected table z0, skipping reflection of foreign key constraint z-; one or more subject columns within name(s) z, z are not present in the table)� foreign_keysrG r� � intersectionr� r� ZTabler� r^ r� �joinZ BLANK_SCHEMA�append_constraintZForeignKeyConstraintr Z ConstraintColumnNotFoundErrorr �warnr� )r3 r� r� r� r� r� r� r� r� r� r� Zfkey_d�connamer r� r� r Zrefspec�columnr r@ r rA r� � s� �� �� ���� ���� ���� ���zInspector._reflect_fk)Zasc�descZ nulls_firstZ nulls_last)r� r� r� r� r� r� r� r7 c C s� |j �|g �}|D �]v} | d } | d } | �d�} | �di �} | d }| �dd�}| �di �}| �d �}|r|t| ��|�s|q|r�qg }t| �D ]�\}}|d u r�| s�t�d |� d | �d |d � d�� qt�| | �}n�z ||v r�|| }n |j | }W n4 t �y, t�|� d|�d|j ��� Y q�Y n0 | �|d�D ]$}|| j v �r:| j | }||�}�q:|� |� q�tj| g|�R ||d�|�� qd S )Nr� � column_names� expressions�column_sortingr r� �indexr� Zduplicates_constraintz Skipping � z because key r z5 reflected as None but no 'expressions' were returnedz key z& was not located in columns for table r@ )Z_tabler )�indexesrG r� �issubset� enumerater r r r� r �KeyErrorr� �_index_sort_exprsr� r� �Index)r3 r� r� r� r� r� r� r� r Zindex_dr� r� r r r Zflavorr� � duplicatesZ idx_elementsr r Z idx_element�option�opr@ r@ rA r� sf �� �� ����zInspector._reflect_indexesc C s� |j �|g �}|D ]�} | d } | d } | �d�} | �d�} | �di �}|rZt| ��|�sZq| r`qg }| D ]T}z ||v r~|| n|j| }W n& ty� t�d||jf � Y qh0 |� |� qh|� t j || | d�|��� qd S )Nr� r r� Zduplicates_indexr� zDunique constraint key '%s' was not located in columns for table '%s')r� r� ) �unique_constraintsrG r� r r r r r r� r� r r� ZUniqueConstraint)r3 r� r� r� r� r� r� r� � constraints�const_dr r� r� r r� Zconstrained_colsr Zconstrained_colr@ r@ rA r� b sD � � �� ���z%Inspector._reflect_unique_constraintsc C s2 |j �|g �}|D ]} |�tjf i | ��� qd S r: )�check_constraintsrG r r� ZCheckConstraint) r3 r� r� r� r� r� r� r� r! r" r@ r@ rA r� � s z$Inspector._reflect_check_constraints)r� r� r� r� r7 c C s |j �|�}|r|d |_d S �Nr� )� table_commentrG r� )r3 r� r� r� r� Z comment_dictr@ r@ rA r� � s z Inspector._reflect_table_comment)r r� � availabler� r6 r7 c s� |�d< � r.|r.t � �dkr.t � �t |� �nd �i �d< }d�ddd�ddddd �� ����fd d �}t|�jdd �|�j�|�j�|�j�|�jdd �|�jdd �|�jdd �|�j dd �|d� }|r�|� |� |S |S d S )Nr �d r9 TF)�optional� check_filter_names_from_methr r` )�methr( r) r7 c sv �d u s �dks �j �| j�s$� }nd }z,�rN| f d|i���}|rR|sRd�ni }W n typ |sh� i }Y n0 |S )Ng �?r� F)rb Z_overrides_defaultrH �NotImplementedError)r* r( r) �_fnr� �r� �fractionZ has_resultr6 r3 r@ rA �run� s& �� � z+Inspector._get_reflection_info.<locals>.run)r) )r( ) r� r r r r r% r# r� r9 ) �lenr� r� r� r� r� r� r� r� r� r� ) r3 r r� r& r� r6 r9 r/ r� r@ r- rA r� � s< �$#�� � � z Inspector._get_reflection_info)N)N)N)N)N)r: )N)N)N)N)N)N)N)N)N)N)N)N)r@ TNN)NNNN)MrH rU rV rW �__annotations__r � deprecatedrf � classmethodrl rd ro rn rv rw r Z _inspectsr rx r ry � contextlib�contextmanagerr{ r} �propertyr~ r r� r� r� r� r� r� r� r� r� r� rT rX rZ r[ r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r Zasc_opZdesc_opZnulls_first_opZ nulls_last_opr r� r� r� r� r� r@ r@ r@ rA r] � s � � �" �" � � �/ �N �!�: � � � � �" �< � �9 �!�; � �: �!�; �$�= �!�> � H Z� B 0 �r] c @ s� e Zd ZdZedd�dd��Zedd�dd��Zed d�d d ��Zed d�d d��Zedd�dd��Z edd�dd��Z edd�dd��Z edd�dd��Z dS ) �ReflectionDefaultsz5provides blank default values for reflection methods.r� rs c C s g S r: r@ �rk r@ r@ rA r� � s zReflectionDefaults.columnsr+ c C s d g d�S )N)r� r r@ r8 r@ r@ rA r s �z ReflectionDefaults.pk_constraintr� c C s g S r: r@ r8 r@ r@ rA r s z ReflectionDefaults.foreign_keysr� c C s g S r: r@ r8 r@ r@ rA r s zReflectionDefaults.indexesr� c C s g S r: r@ r8 r@ r@ rA r s z%ReflectionDefaults.unique_constraintsr� c C s g S r: r@ r8 r@ r@ rA r# s z$ReflectionDefaults.check_constraintsr� c C s i S r: r@ r8 r@ r@ rA r� s z ReflectionDefaults.table_optionsr, c C s dd iS r$ r@ r8 r@ r@ rA r% s z ReflectionDefaults.table_commentN) rH rU rV rW r3 r� r r r r r# r� r% r@ r@ r@ rA r7 � s" r7 c @ sf e Zd ZU ded< ded< ded< ded< d ed < d ed < d ed< ded< ded< d dd�dd�ZdS )r� r� r� z7Dict[TableKey, Optional[ReflectedPrimaryKeyConstraint]]r r� r r� r r� r z/Dict[TableKey, Optional[ReflectedTableComment]]r% r� r# r� r� z+Dict[TableKey, exc.UnreflectableTableError]r9 rm )�otherr7 c C sJ | j �� D ]:\}}t||�}|d ur |d u r:t| ||� q |�|� q d S r: )�__dict__rJ �getattr�setattrr� )r3 r9 rC rD �ovr@ r@ rA r� / s z_ReflectionInfo.updateN)rH rU rV r1 r� r@ r@ r@ rA r� " s r� )ErW � __future__r r4 Z dataclassesr �enumr r r �typingr r r r r r r r r r r r r r �baser r � r r r r r r r� Z sql.cache_keyr Z sql.elementsr r! Z sql.type_apir" Z sql.visitorsr# r$ Z util.typingr% Z interfacesr& r' r( r) r* r+ r, r- r. r/ rR rN rS rT rZ Z_self_inspectsZ Inspectabler] r7 r� r@ r@ r@ rA �<module> s� R' sqlalchemy/engine/__pycache__/cursor.cpython-39.pyc 0000644 00000167567 15125143220 0016352 0 ustar 00 a ��Jh�* � @ s U d Z ddlmZ ddlZddlZddlZddlZddlmZ ddlmZ ddlm Z ddlm Z ddlm Z dd lm Z dd lm Z dd lmZ dd lmZ dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z ddl m Z dd l m Z dd l m!Z! dd l"m#Z# dd l"m$Z$ dd l"m!Z% dd l&m'Z' dd!l(m)Z) dd"l(m*Z* dd#l(m+Z+ dd$l(m,Z, dd%l(m-Z- dd&l.m/Z/ dd'l!m0Z0 dd(l1m2Z2 dd)l1m3Z3 ej�r�dd*l4m5Z5 dd+l6m7Z7 dd,l8m9Z9 dd-l8m:Z: dd.l8m;Z; dd/l8m<Z< dd0lm=Z= dd1lm>Z> dd2lm?Z? dd3lm@Z@ dd4lmAZA dd5lmBZB dd6l.mCZC ed7ed8�ZDdZEd9eFd:< dZGd;eFd<< dZHd=eFd>< d?ZId@eFdA< dBZJdCeFdD< dEZKdFeFdG< dHZLdIeFdJ< eeeM eMe e eNeNedK eeN f ZOedLeOf ZPeeMeMe e eNeNedK eNf ZQG dMdN� dNe�ZRG dOdP� dP�ZSG dQdR� dReS�ZTG dSdT� dTeT�ZUeU� ZVG dUdV� dVeT�ZWeW� ZXG dWdX� dXeS�ZYeY� ZZG dYdZ� dZeY�Z[G d[d\� d\eY�Z\G d]d^� d^e�Z]e]� Z^d_d`�dadb�Z_G dcdd� ddeeD �Z`e`ZadS )ezNDefine cursor-specific result set constructs including :class:`.CursorResult`.� )� annotationsN)�Any)�cast)�ClassVar)�Dict)�Iterable)�Iterator)�List)�Mapping)�NoReturn)�Optional)�Sequence)�Tuple)� TYPE_CHECKING)�TypeVar)�Union� )�IteratorResult)� MergedResult)�Result)�ResultMetaData)�SimpleResultMetaData)� tuplegetter)�Row� )�exc)�util)�elements)�sqltypes)� _generative)�ResultColumnsEntry)�RM_NAME)� RM_OBJECTS)�RM_RENDERED_NAME)�RM_TYPE)� TypeEngine)�compat)�Literal)�Self)� Connection)�DefaultExecutionContext)�_DBAPICursorDescription)� DBAPICursor)�Dialect)�ExecutionContext)� _KeyIndexType)�_KeyMapRecType)� _KeyMapType)�_KeyType)�_ProcessorsType)�_TupleGetterType)�_ResultProcessorType�_T)�boundz Literal[0]�MD_INDEXz Literal[1]�MD_RESULT_MAP_INDEXz Literal[2]� MD_OBJECTS� z Literal[3]� MD_LOOKUP_KEY� z Literal[4]�MD_RENDERED_NAME� z Literal[5]� MD_PROCESSOR� z Literal[6]�MD_UNTRANSLATEDz_ResultProcessorType[Any]r2 c @ s| e Zd ZU dZdZded< ded< ded< d ed < d ed < d ed < dZded< dd d�dd�Zdd�dd�Zd ddddd d dd d � d d �Z d d�d d �Z d d d!�d"d#�Z d$dd%�d&d'�Z d(dd)�d*d+�Z d,d-d.�d/d0�Zd1d2� Zd3d4� Zd5d6� Zd7d8� ZedWd:d d;d<�d=d>��Zd?d@� Ze�s4dXddAd dBdC�dDdE�ZdFdG� ZdYdd dHdI�dJdK�ZdLdM� ZdNdOd%�dPdQ�ZdRdS� Z dTdU� Z dVS )Z�CursorResultMetaDataz"Result metadata for DBAPI cursors.) �_keymap� _processors�_keys� _keymap_by_result_column_idx� _tuplefilter�_translated_indexes�_safe_for_cache� _unpickled� _key_to_index�_CursorKeyMapTyperD r3 rE z#Optional[Dict[int, _KeyMapRecType]]rG �boolrK rJ zOptional[List[int]]rI TzClassVar[bool]� returns_rowsr )�key�returnc C s || j v S �N�rD ��selfrP � rV �M/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/engine/cursor.py�_has_key� s z CursorResultMetaData._has_keyr �rQ c s t � j� fdd�� jD �d�S )Nc s g | ]}� j | t �qS rV )rD r: ��.0rP �rU rV rW � <listcomp>� � z4CursorResultMetaData._for_freeze.<locals>.<listcomp>)�extra)r rF r\ rV r\ rW � _for_freeze� s �z CursorResultMetaData._for_freezez Sequence[str]r1 zOptional[_TupleGetterType]) � unpickled� processors�keys�keymap� tuplefilter�translated_indexes�safe_for_cache�keymap_by_result_column_idxrQ c C sP | j �| j �} || _|| _|| _|| _|| _|| _|| _|| _ | � |t �| _ | S rR ) � __class__�__new__rK rE rF rD rH rI rJ rG �_make_key_to_indexr8 rL ) rU ra rb rc rd re rf rg rh Znew_objrV rV rW �_make_new_metadata� s z'CursorResultMetaData._make_new_metadatac C sH | j r J �| j| jd gt| j� d d dd� | j�� D �| j| j| j d�S )Nc S s. i | ]&\}}||d d� d |dd� �qS )r r? rR rA NrV �r[ rP �valuerV rV rW � <dictcomp>� s �z;CursorResultMetaData._remove_processors.<locals>.<dictcomp>)ra rb re rf rd rc rg rh ) rH rl rK �lenrE rD �itemsrF rJ rG r\ rV rV rW �_remove_processors� s ��z'CursorResultMetaData._remove_processors)�otherrQ c sz | j r J �t| j�� t| j��� �� �fdd�|j�� D �� | j| j| j |j d d | j|j � | j dd� � � � D �d�S )Nc sP i | ]H\}}||d dur.|� vr.|d � nd|d � g|dd� �R �qS )r Nr r rV rm �rd �offsetrV rW ro � s � �� � �z=CursorResultMetaData._splice_horizontally.<locals>.<dictcomp>c S s i | ]}|t |�qS rV �r9 �r[ �metadata_entryrV rV rW ro � s �)ra rb re rf rc rd rg rh ) rH �dictrD rp rF �updaterq rl rK rE rJ �values)rU rs rV rt rW �_splice_horizontally� s( �� ��z)CursorResultMetaData._splice_horizontallyzSequence[_KeyIndexType])rc rQ c s� t � �|��}dd� |D �}dd� |D �}� jrB� fdd�|D �}t|� }dd� t|�D �}dd� |D �}|�dd � |D �� � j� j� j||||� j � j d �S ) Nc S s g | ] }|t �qS rV )r8 �r[ �recrV rV rW r] r^ z0CursorResultMetaData._reduce.<locals>.<listcomp>c S s g | ] }|t �qS rV �r< r} rV rV rW r] r^ c s g | ]}� j | �qS rV )rI )r[ �idxr\ rV rW r] r^ c S s" g | ]\}}|f|d d� �qS �r NrV )r[ �indexr~ rV rV rW r] r^ c S s i | ]}|t |�qS rV r r} rV rV rW ro r^ z0CursorResultMetaData._reduce.<locals>.<dictcomp>c s s( | ] }|t pd D ]}||fV qqdS )rV N�r: )r[ Znew_rec�erV rV rW � <genexpr> s �z/CursorResultMetaData._reduce.<locals>.<genexpr>)ra rb rc re rf rd rg rh ) �list�_metadata_for_keysrI r � enumeraterz rl rK rE rJ rG )rU rc ZrecsZindexesZnew_keys�tupZnew_recsrd rV r\ rW �_reduce� s* ��z CursorResultMetaData._reducer. )�contextrQ c s� |j r|j js| S |j j}|j}tr4t|tj�s4J �||u r@| S |dusLJ �| j� � du rtdd� | j � � D � � | _| j r~J �| j t �| j � fdd�t|j�D ��| j| jdd| j| j| jd�S )a[ When using a cached Compiled construct that has a _result_map, for a new statement that used the cached Compiled, we need to ensure the keymap has the Column objects from our new statement as keys. So here we rewrite keymap with new entries for the new columns as matched to those of the cached statement. Nc S s i | ]}|t |�qS rV rv rw rV rV rW ro B s �z:CursorResultMetaData._adapt_to_context.<locals>.<dictcomp>c s" i | ]\}}|� v r|� | �qS rV rV )r[ r� �new�Zkeymap_by_positionrV rW ro K s �)rd ra rb re rf rc rg rh )�compiled�_result_columns� statement�invoked_statementr � isinstancer Z ClauseElementrG rD r{ rH rl r& Z dict_unionr� Z_all_selected_columnsrK rE rF rJ )rU r� Zcompiled_statementr� rV r� rW �_adapt_to_context s@ � ��� �z&CursorResultMetaData._adapt_to_context�CursorResult[Any]r+ )�parent�cursor_descriptionc s� |j }d �_d �_d �_�_|jr>|j\}}}}}t|�} nd } } } } }}��|||| ||||�} dd� | D ��_d �_ | �r@dd� | D �} t| �| k�r"i } t � � | D ]B} | t f| t p�d D ]&}| t }| �||�|krΈ �|� q�q�� fdd�| D ��_| �dd� � D �� nd d� | D ��_�j�| � nd d� | D ��_| �sx|j�rx�j��fd d�| D �� ���jt ��_d S ) NFc S s g | ] }|t �qS rV )r@ rw rV rV rW r] � s z1CursorResultMetaData.__init__.<locals>.<listcomp>c S s i | ]}|t |�qS rV r rw rV rV rW ro � s �z1CursorResultMetaData.__init__.<locals>.<dictcomp>rV c s0 i | ](}|t r|t D ]}|� vr||�qqS rV r� �r[ rx Zobj_elem)�dupesrV rW ro � s �c S s i | ]}|d d g ||d d f�qS rR rV rZ rV rV rW ro � s �c S s( i | ] }|t r|t D ] }||�qqS rV r� r� rV rV rW ro � s �c S s i | ]}|t |�qS rV r rw rV rV rW ro � s �c s( i | ] }|t r|t � j|t �qS rV )rB rD r< rw r\ rV rW ro � s � �)r� rH rI rJ rK Zresult_column_structrp �_merge_cursor_descriptionrE rG �setr> r: r8 � setdefault�addrD rz �_translate_colnamerk rL )rU r� r� r� �result_columns�cols_are_ordered�textual_ordered�ad_hoc_textual�loose_column_name_matching� num_ctx_cols�raw�by_keyZ index_by_keyrx rP r� rV )r� rU rW �__init__\ s� � � ��� �� � � �� �� �� z CursorResultMetaData.__init__c s� |rF|rF|sF|t ��krFdd� |D �| _d| _� �fdd�t|�D �S |sZ|rpt ��|krpd| _| �� �|�} n.|r�d| _| �� �||�} nd| _| �� ��} � fdd�| D �S dS )a# Merge a cursor.description with compiled result column information. There are at least four separate strategies used here, selected depending on the type of SQL construct used to start with. The most common case is that of the compiled SQL expression construct, which generated the column names present in the raw SQL string and which has the identical number of columns as were reported by cursor.description. In this case, we assume a 1-1 positional mapping between the entries in cursor.description and the compiled object. This is also the most performant case as we disregard extracting / decoding the column names present in cursor.description since we already have the desired name we generated in the compiled SQL construct. The next common case is that of the completely raw string SQL, such as passed to connection.execute(). In this case we have no compiled construct to work with, so we extract and decode the names from cursor.description and index those as the primary result row target keys. The remaining fairly common case is that of the textual SQL that includes at least partial column information; this is when we use a :class:`_expression.TextualSelect` construct. This construct may have unordered or ordered column information. In the ordered case, we merge the cursor.description and the compiled construct's information positionally, and warn if there are additional description names present, however we still decode the names in cursor.description as we don't have a guarantee that the names in the columns match on these. In the unordered case, we match names in cursor.description to that of the compiled construct based on name matching. In both of these cases, the cursor.description names and the column expression objects and names are indexed as result row target keys. The final case is much less common, where we have a compiled non-textual SQL expression construct, but the number of columns in cursor.description doesn't match what's in the compiled construct. We make the guess here that there might be textual column expressions in the compiled construct that themselves include a comma in them causing them to split. We do the same name-matching as with textual non-ordered columns. The name-matched system of merging is the same as that used by SQLAlchemy for all cases up through the 0.9 series. Positional matching for compiled SQL expressions was introduced in 1.0 as a major performance feature, and positional matching for textual :class:`_expression.TextualSelect` objects in 1.1. As name matching is no longer a common case, it was acceptable to factor it into smaller generator- oriented methods that are easier to understand, but incur slightly more performance overhead. c S s g | ] }|d �qS �r rV )r[ �elemrV rV rW r] 9 r^ zBCursorResultMetaData._merge_cursor_description.<locals>.<listcomp>Tc sH g | ]@\}}|||t |t |t � �|t |t �| d �df�qS r� )r" r! r# �get_result_processorr$ )r[ r� Z rmap_entry�r� r� rV rW r] B s � ��Fc s6 g | ].\}}}}}}}|||||� � |||�|f�qS rV )r� )r[ r� �ridxZcursor_colname� mapped_type�coltype�obj� untranslated)r� rV rW r] r s$ ���N)rp rF rJ r� � _merge_textual_cols_by_position�_merge_cols_by_name�_merge_cols_by_none) rU r� r� r� r� r� r� r� r� Z raw_iteratorrV r� rW r� � sJ C��� � �� ��� � �z.CursorResultMetaData._merge_cursor_descriptionc c s� |j }|j}|jr|jnd}d}g | _t|�D ]N\}}|d } |d } |rV|| �\} }|rb|| �} | j�| � || || fV q.dS )z�Extract column names and data types from a cursor.description. Applies unicode decoding, column translation, "normalization", and case sensitivity rules to the names based on the dialect. Nr r )�dialectr� Zrequires_name_normalize�normalize_namerF r� �append) rU r� r� r� Ztranslate_colnamer� r� r� r~ �colnamer� rV rV rW �_colnames_from_description� s � z/CursorResultMetaData._colnames_from_descriptionc c s� t |�}|t |�kr*t�d|t |�f � t� }| �||�D ]�\}}}} ||k r�|| } | t } |} | t } | d |v r�t�d| d ��|� | d � nt j } d } d } || || | | |fV q<d S )NzVNumber of columns in textual SQL (%d) is smaller than number of columns requested (%d)r z8Duplicate column expression requested in textual SQL: %r) rp r �warnr� r� r" r$ r �InvalidRequestErrorr� r �NULLTYPE)rU r� r� r� r� �seenr� r� r� r� �ctx_recr� r� r� rV rV rW r� � s< �� � ��z4CursorResultMetaData._merge_textual_cols_by_positionc c s� | � ||�}| �||�D ]f\}}}} z || } W n tyP tj} d } d } Y n0 | d } | d } | d } || || | | |fV qd S )Nr r r; )� _create_description_match_mapr� �KeyErrorr r� )rU r� r� r� r� Z match_mapr� r� r� r� r� r� r� Zresult_columns_idxrV rV rW r� � s4 � � �z(CursorResultMetaData._merge_cols_by_nameFzList[ResultColumnsEntry]zKDict[Union[str, object], Tuple[str, Tuple[Any, ...], TypeEngine[Any], int]])r� r� rQ c C s� i }t |�D ]�\}}|t }||v rN|| \}}} } |||t | |f||< n |t |t |t |f||< |r |t D ]$} |�| |t |t |t |f� qvq |S )z�when matching cursor.description to a set of names that are present in a Compiled object, as is the case with TextualSelect, get all the names we expect might match those in cursor.description. )r� r# r" r! r$ r� ) �clsr� r� �dr� r� rP Ze_nameZe_obj�e_typeZe_ridxZr_keyrV rV rW r� � s � �z2CursorResultMetaData._create_description_match_mapc c s4 | � ||�D ]"\}}}}|d |tj|d |fV q d S rR )r� r r� )rU r� r� r� r� r� r� rV rV rW r� s ��z(CursorResultMetaData._merge_cols_by_nonezOptional[Exception]zOptional[NoReturn])rP �err�raiseerrrQ c C sD |r<| j r$t|tj�r$t�d�|�q@t�dt�|� �|�nd S d S )Nz9Row was unpickled; lookup by ColumnElement is unsupportedz.Could not locate column in row for column '%s')rK r� r Z ColumnElementr ZNoSuchColumnErrorr Zstring_or_unprintable)rU rP r� r� rV rV rW � _key_fallback/ s �����z"CursorResultMetaData._key_fallbackc C s t �d|t ��d S )Nz<Ambiguous column name '%s' in result set column descriptions)r r� r< )rU r~ rV rV rW � _raise_for_ambiguous_column_name@ s ��z5CursorResultMetaData._raise_for_ambiguous_column_name� Optional[int])rP r� rQ c C s� t |t�r| j| }z| j| }W n@ tyb } z(| �|||�}|d u sLJ �W Y d }~d S d }~0 0 |d }|d u r~| �|� |S �Nr )r� �intrF rD r� r� r� )rU rP r� r~ �ke�xr� rV rV rW �_index_for_keyF s z#CursorResultMetaData._index_for_keyc sR z� fdd�|D �W S t yL } z t�� |jd |� W Y d }~n d }~0 0 d S )Nc s g | ]}� j | d �qS r� rS rZ r\ rV rW r] [ r^ z:CursorResultMetaData._indexes_for_keys.<locals>.<listcomp>r )r� rC r� �args)rU rc r� rV r\ rW �_indexes_for_keysY s z&CursorResultMetaData._indexes_for_keysz Sequence[Any]z&Iterator[_NonAmbigCursorKeyMapRecType]c c s� |D ]�}t |jjv r | j| }z| j| }W n8 tyd } z t�| |jd |� W Y d }~n d }~0 0 |t }|d u r�| � |� t t |�V qd S r� ) r� ri �__mro__rF rD r� rC r� r� r8 r� r � _NonAmbigCursorKeyMapRecType)rU rc rP r~ r� r� rV rV rW r� ` s * z'CursorResultMetaData._metadata_for_keysc C s dd� | j �� D �| j| jd�S )Nc S s> i | ]6\}}t |ttf�r||t |t g ||t d d f�qS rR )r� �strr� r8 r9 r> )r[ rP r~ rV rV rW ro w s ��z5CursorResultMetaData.__getstate__.<locals>.<dictcomp>)rD rF rI )rD rq rF rI r\ rV rV rW � __getstate__t s � �z!CursorResultMetaData.__getstate__c C s� dd� t t|d ��D �| _|d | _d | _| �| jt�| _|d | _d| _ |d rrt d|d �| _ t | j � | _ n d | _ | _ d S )Nc S s g | ]}d �qS rR rV �r[ �_rV rV rW r] � r^ z5CursorResultMetaData.__setstate__.<locals>.<listcomp>rF rD TrI z List[int])�rangerp rE rD rG rk r8 rL rF rK r rI r rH )rU �staterV rV rW � __setstate__� s �z!CursorResultMetaData.__setstate__N)F)T)T) �__name__� __module__� __qualname__�__doc__� __slots__�__annotations__rO rX r` rl rr r| r� r� r� r� r� r� r� � classmethodr� r� r r� r� r� r� r� r� r� rV rV rV rW rC � sH $ > $& �) �rC c @ s� e Zd ZU dZdZdZded< dddd �d d �Zdddd �d d �Zddddd�dd�Z d$ddddd�dd�Z d%ddddd�dd �Z dddd �d d �Z ddd d d!�d"d#�Z dS )&�ResultFetchStrategyzQDefine a fetching strategy for a result object. .. versionadded:: 1.4 rV N�!Optional[_DBAPICursorDescription]� alternate_cursor_descriptionr� �Optional[DBAPICursor]�None��result� dbapi_cursorrQ c C s t � �d S rR ��NotImplementedError�rU r� r� rV rV rW � soft_close� s z ResultFetchStrategy.soft_closec C s t � �d S rR r� r� rV rV rW � hard_close� s z ResultFetchStrategy.hard_closer� �r� r� �numrQ c C s d S rR rV �rU r� r� r� rV rV rW � yield_per� s z ResultFetchStrategy.yield_perFr, rN r �r� r� r� rQ c C s t � �d S rR r� �rU r� r� r� rV rV rW �fetchone� s z ResultFetchStrategy.fetchoner� �r� r� �sizerQ c C s t � �d S rR r� �rU r� r� r� rV rV rW � fetchmany� s z ResultFetchStrategy.fetchmanyc C s t � �d S rR r� r� rV rV rW �fetchall� s z ResultFetchStrategy.fetchall� BaseExceptionr �r� r� r� rQ c C s |�d S rR rV �rU r� r� r� rV rV rW �handle_exception� s z$ResultFetchStrategy.handle_exception)F)N)r� r� r� r� r� r� r� r� r� r� r� r� r� r� rV rV rV rW r� � s � �r� c @ sJ e Zd ZdZdZdd� Zdd� Zddd �Zdd d �Zd d� Z ddd�Z d S )�NoCursorFetchStrategyz�Cursor strategy for a result that has no open cursor. There are two varieties of this strategy, one for DQL and one for DML (and also DDL), each of which represent a result that had a cursor but no longer has one. rV c C s d S rR rV r� rV rV rW r� � s z NoCursorFetchStrategy.soft_closec C s d S rR rV r� rV rV rW r� � s z NoCursorFetchStrategy.hard_closeFc C s | � |d �S rR �� _non_resultr� rV rV rW r� � s z NoCursorFetchStrategy.fetchoneNc C s | � |g �S rR r� r� rV rV rW r� � s z NoCursorFetchStrategy.fetchmanyc C s | � |g �S rR r� r� rV rV rW r� � s z NoCursorFetchStrategy.fetchallc C s t � �d S rR r� �rU r� �defaultr� rV rV rW r� � s z!NoCursorFetchStrategy._non_result)F)N)N) r� r� r� r� r� r� r� r� r� r� r� rV rV rV rW r� � s r� c @ s e Zd ZdZdZddd�ZdS )�NoCursorDQLFetchStrategya� Cursor strategy for a DQL result that has no open cursor. This is a result set that can return rows, i.e. for a SELECT, or for an INSERT, UPDATE, DELETE that includes RETURNING. However it is in the state where the cursor is closed and no rows remain available. The owning result object may or may not be "hard closed", which determines if the fetch methods send empty results or raise for closed result. rV Nc C s |j rt�d�|�n|S d S )Nz This result object is closed.)�closedr �ResourceClosedErrorr� rV rV rW r� s ��z$NoCursorDQLFetchStrategy._non_result)N�r� r� r� r� r� r� rV rV rV rW r � s r c @ s e Zd ZdZdZddd�ZdS )�NoCursorDMLFetchStrategyz�Cursor strategy for a DML result that has no open cursor. This is a result set that does not return rows, i.e. for an INSERT, UPDATE, DELETE that does not include RETURNING. rV Nc C s |j jr J �|j �|� d S rR )� _metadatarO �_we_dont_return_rowsr� rV rV rW r� s z$NoCursorDMLFetchStrategy._non_result)Nr rV rV rV rW r s r c @ s� e Zd ZdZdZdddd�dd�Zdddd�d d �Zddd d d �dd�Zddddd�dd�Zd"ddddd�dd�Z d#ddd dd �d d �Z dddd�d d!�Z dS )$�CursorFetchStrategyz�Call fetch methods from a DBAPI cursor. Alternate versions of this class may instead buffer the rows from cursors or not use cursors at all. rV r� r� r� r� c C s t |_d S rR ��_NO_CURSOR_DQL�cursor_strategyr� rV rV rW r� * s z CursorFetchStrategy.soft_closec C s t |_d S rR r r� rV rV rW r� / s z CursorFetchStrategy.hard_closer� r r� c C s |j �|d d ||j� d S rR )� connectionZ_handle_dbapi_exceptionr� r� rV rV rW r� 4 s �z$CursorFetchStrategy.handle_exceptionr� r� c C s t |d|it�� dd�|_d S )N�max_row_bufferr )�initial_buffer� growth_factor)� BufferedRowCursorFetchStrategy� collections�dequer r� rV rV rW r� > s �z CursorFetchStrategy.yield_perFr, rN r r� c C sZ z"|� � }|d u r |j|d� |W S tyT } z| �|||� W Y d }~n d }~0 0 d S �N��hard)r� � _soft_closer� r� )rU r� r� r� �rowr� rV rV rW r� K s z CursorFetchStrategy.fetchoneNr� r� c C sf z.|d u r|� � }n |� |�}|s*|�� |W S ty` } z| �|||� W Y d }~n d }~0 0 d S rR )r� r r� r� )rU r� r� r� �lr� rV rV rW r� Y s z CursorFetchStrategy.fetchmanyc C sN z|� � }|�� |W S tyH } z| �|||� W Y d }~n d }~0 0 d S rR )r� r r� r� )rU r� r� �rowsr� rV rV rW r� k s z CursorFetchStrategy.fetchall)F)N) r� r� r� r� r� r� r� r� r� r� r� r� rV rV rV rW r s � �r c sr e Zd ZdZdZddd�Zedd� �Zd d � Zd d � Z � fd d�Z � fdd�Z ddd�Z ddd�Z dd� Z� ZS )r a� A cursor fetch strategy with row buffering behavior. This strategy buffers the contents of a selection of rows before ``fetchone()`` is called. This is to allow the results of ``cursor.description`` to be available immediately, when interfacing with a DB-API that requires rows to be consumed before this information is available (currently psycopg2, when used with server-side cursors). The pre-fetching behavior fetches only one row initially, and then grows its buffer size by a fixed amount with each successive need for additional rows up the ``max_row_buffer`` size, which defaults to 1000:: with psycopg2_engine.connect() as conn: result = conn.execution_options( stream_results=True, max_row_buffer=50 ).execute(text("select * from table")) .. versionadded:: 1.4 ``max_row_buffer`` may now exceed 1000 rows. .. seealso:: :ref:`psycopg2_execution_options` )�_max_row_buffer� _rowbuffer�_bufsize�_growth_factorr? Nc C sX |� dd�| _|d ur || _nt�|�d��| _|| _|rLt| j| j�| _n| j| _d S )Nr i� r ) �getr r r r r� r �minr )rU r� �execution_optionsr r rV rV rW r� � s z'BufferedRowCursorFetchStrategy.__init__c C s t |j|jj�S rR )r �cursorr� r )r� r� rV rV rW �create� s �z%BufferedRowCursorFetchStrategy.createc C s� | j }z |dk r|�� }n |�|�}W n2 tyX } z| �|||� W Y d}~n d}~0 0 |sbdS t�|�| _| jr�|| j k r�t | j || j �| _ dS )z*this is currently used only by fetchone().r N) r r� r� r� r� r r r r r r )rU r� r� r� Znew_rowsr� rV rV rW � _buffer_rows� s $ �z+BufferedRowCursorFetchStrategy._buffer_rowsc C s d| _ | | _| _d S r� )r r r r� rV rV rW r� � s z(BufferedRowCursorFetchStrategy.yield_perc s | j �� t� �||� d S rR �r �clear�superr� r� �ri rV rW r� � s z)BufferedRowCursorFetchStrategy.soft_closec s | j �� t� �||� d S rR �r r$ r% r� r� r& rV rW r� � s z)BufferedRowCursorFetchStrategy.hard_closeFc C sj | j s`| �||� | j s`z|j|d� W n2 tyZ } z| �|||� W Y d }~n d }~0 0 d S | j �� S r )r r" r r� r� �popleft)rU r� r� r� r� rV rV rW r� � s $z'BufferedRowCursorFetchStrategy.fetchonec s� |d u r| � ||�S | j� t� �}d}||kr�z|�|| �}W n2 tyr } z| �|||� W Y d }~n d }~0 0 |s~d}n � �|� � fdd�tt|t� ���D �}|r�|� � |S )NFTc s g | ] }� � � �qS rV �r( r� ��rbrV rW r] � r^ z<BufferedRowCursorFetchStrategy.fetchmany.<locals>.<listcomp>) r� r rp r� r� r� �extendr� r r ) rU r� r� r� Zlb�closer� r� �resrV r* rW r� � s" $ z(BufferedRowCursorFetchStrategy.fetchmanyc C sf z.t | j�t |�� � }| j�� |�� |W S ty` } z| �|||� W Y d }~n d }~0 0 d S rR )r� r r� r$ r r� r� )rU r� r� �retr� rV rV rW r� � s z'BufferedRowCursorFetchStrategy.fetchall)r? N)F)N)r� r� r� r� r� r� r� r! r" r� r� r� r� r� r� � __classcell__rV rV r& rW r { s � r c sh e Zd ZdZdZddddd�dd �Zd d � Z� fd d �Z� fdd�Zddd�Z ddd�Z dd� Z � Z S )� FullyBufferedCursorFetchStrategyz�A cursor strategy that buffers rows fully upon creation. Used for operations where a result is to be delivered after the database conversation can not be continued, such as MSSQL INSERT...OUTPUT after an autocommit. )r r� Nr� r� zOptional[Iterable[Any]])r� �alternate_descriptionr c C s< || _ |d ur t�|�| _n |d us(J �t�|�� �| _d S rR )r� r r r r� )rU r� r2 r rV rV rW r� s z)FullyBufferedCursorFetchStrategy.__init__c C s d S rR rV r� rV rV rW r� s z*FullyBufferedCursorFetchStrategy.yield_perc s | j �� t� �||� d S rR r# r� r& rV rW r� s z+FullyBufferedCursorFetchStrategy.soft_closec s | j �� t� �||� d S rR r' r� r& rV rW r� s z+FullyBufferedCursorFetchStrategy.hard_closeFc C s$ | j r| j �� S |j|d� d S d S r )r r( r r� rV rV rW r� $ s z)FullyBufferedCursorFetchStrategy.fetchonec sJ |d u r| � ||�S | j� � fdd�tt|t� ���D �}|sF|�� |S )Nc s g | ] }� � � �qS rV r) r� r* rV rW r] 0 r^ z>FullyBufferedCursorFetchStrategy.fetchmany.<locals>.<listcomp>)r� r r� r rp r )rU r� r� r� r rV r* rW r� + s z*FullyBufferedCursorFetchStrategy.fetchmanyc C s | j }t�� | _ |�� |S rR )r r r r )rU r� r� r/ rV rV rW r� 5 s z)FullyBufferedCursorFetchStrategy.fetchall)NN)F)N) r� r� r� r� r� r� r� r� r� r� r� r� r0 rV rV r& rW r1 s � r1 c @ sf e Zd ZdZdZddd�Zdd� Zdd � Zd d � Ze d d � �Z e dd� �Z e dd� �Z e dd� �Z dS )�_NoResultMetaDatarV FNc C s t �d�|�d S )NzJThis result object does not return rows. It has been closed automatically.)r r )rU r� rV rV rW r A s ��z&_NoResultMetaData._we_dont_return_rowsc C s | � � d S rR �r )rU rc r� rV rV rW r� G s z _NoResultMetaData._index_for_keyc C s | � � d S rR r4 rT rV rV rW r� J s z$_NoResultMetaData._metadata_for_keysc C s | � � d S rR r4 )rU rc rV rV rW r� M s z_NoResultMetaData._reducec C s | � � d S rR r4 r\ rV rV rW rD P s z_NoResultMetaData._keymapc C s | � � d S rR r4 r\ rV rV rW rL T s z _NoResultMetaData._key_to_indexc C s | � � d S rR r4 r\ rV rV rW rE X s z _NoResultMetaData._processorsc C s | � � d S rR r4 r\ rV rV rW rc \ s z_NoResultMetaData.keys)N)r� r� r� r� rO r r� r� r� �propertyrD rL rE rc rV rV rV rW r3 < s r3 zIteratorResult[Any]rY c C s t t� tg ��} | �� | S rR )r r3 �iterr )�itrV rV rW �null_dml_resultd s r8 c s� e Zd ZU dZdZded< eZdZded< dZ ded< d Z d ed < d ed < ded< ded< d ddd�dd�Z dd� Z dWdd�Z edd� �Zed d � �Zd d � Zd d!� Zed"d#� �Zd$d%� Zd&d'� Zd(d)� Zed*d+� �Zd,d-� Zd.d/� Zd0d1� Zd2d3� Zd4d5� Z e j d6d7�d8d9��Z ed:d;� �Z ed<d=� �Z!ed>d?� �Z"d@dA� Z#dXdBdC�Z$dDdE� Z%dYdGdH�Z&dIdJ� Z'dKdLdM�� fdNdO� Z(dPd7�dQdR�Z)e*d6dSdT�dUdV��Z+� Z,S )Z� CursorResulta+ A Result that is representing state from a DBAPI cursor. .. versionchanged:: 1.4 The :class:`.CursorResult`` class replaces the previous :class:`.ResultProxy` interface. This classes are based on the :class:`.Result` calling API which provides an updated usage model and calling facade for SQLAlchemy Core and SQLAlchemy ORM. Returns database rows via the :class:`.Row` class, which provides additional API features and behaviors on top of the raw data returned by the DBAPI. Through the use of filters such as the :meth:`.Result.scalars` method, other kinds of objects may also be returned. .. seealso:: :ref:`tutorial_selecting_data` - introductory material for accessing :class:`_engine.CursorResult` and :class:`.Row` objects. )r� r� r r �_echor z.Union[CursorResultMetaData, _NoResultMetaData]r FrN � _soft_closedr Tr* r� r- r� r� r r) r r� )r� r r� c s� || _ |j| _|j| _|| _|j| _| jjo4|j�� | _}|d ur�| � ||�}t � t ||j |j��|jr�t�t|j �����fdd�}|�n��|r�| j jj��fdd�� � | _� �fdd�}|}n�}| �d|� n|jdks�J �| j| _d S ) Nc s � �| ��S rR rV )�raw_data)� _make_row�sentinel_filterrV rW � _sliced_row� s z*CursorResult.__init__.<locals>._sliced_rowc s � dt �| �� | S )NzRow %r)�sql_utilZ _repr_row�r )�logrV rW �_log_row� s z'CursorResult.__init__.<locals>._log_rowc s � �| ��S rR rV rA )rC � sliced_rowrV rW � _make_row_2� s z*CursorResult.__init__.<locals>._make_row_2Z _row_getterr )r� r� r r Zroot_connectionr r: ZengineZ_should_log_debug�_init_metadata� functools�partialr Z_effective_processorsrL Z_num_sentinel_cols�operator� itemgetter�slice� _log_debugZ_row_logging_fnZ_set_memoized_attribute�_no_result_metadatar ) rU r� r r� Zecho�metadatar? rE Zmake_rowrV )rC r= rB r> rD rW r� � s@ � � � zCursorResult.__init__c C s� |j rp|j }|jr|j}nt| |�}|jr0||_|j�dd�sh|jrh|j|jj u rh|j |j urh|� |�}|| _ nt| |� | _ }| jr�|j�dtdd� |D ��� |S )NZ _result_disable_adapt_to_contextFzCol %rc s s | ]}|d V qdS )r NrV )r[ r� rV rV rW r� � r^ z.CursorResult._init_metadata.<locals>.<genexpr>)r� Z_cached_metadatarC rJ r r r� Z cache_hitr� Z CACHE_HITr� r� r� r r: r rL �tuple)rU r� r� r� rN rV rV rW rF � s6 ��� � � � �zCursorResult._init_metadatac C sl |s | j s|r| jrdS |r4d| _| j�| | j� n| j�| | j� | j sh| j}d| _| j�|� d| _ dS )a\ Soft close this :class:`_engine.CursorResult`. This releases all DBAPI cursor resources, but leaves the CursorResult "open" from a semantic perspective, meaning the fetchXXX() methods will continue to return empty results. This method is called automatically when: * all result rows are exhausted using the fetchXXX() methods. * cursor.description is None. This method is **not public**, but is documented in order to clarify the "autoclose" process used. .. seealso:: :meth:`_engine.CursorResult.close` NT)r; r r r� r r� r Z_safe_close_cursor)rU r r rV rV rW r s zCursorResult._soft_closec C sB | j jst�d��n&| j js(t�d��n| j jr:t�d��| j jS )a� Return the value of :attr:`_engine.CursorResult.inserted_primary_key` as a row contained within a list; some dialects may support a multiple row form as well. .. note:: As indicated below, in current SQLAlchemy versions this accessor is only useful beyond what's already supplied by :attr:`_engine.CursorResult.inserted_primary_key` when using the :ref:`postgresql_psycopg2` dialect. Future versions hope to generalize this feature to more dialects. This accessor is added to support dialects that offer the feature that is currently implemented by the :ref:`psycopg2_executemany_mode` feature, currently **only the psycopg2 dialect**, which provides for many rows to be INSERTed at once while still retaining the behavior of being able to return server-generated primary key values. * **When using the psycopg2 dialect, or other dialects that may support "fast executemany" style inserts in upcoming releases** : When invoking an INSERT statement while passing a list of rows as the second argument to :meth:`_engine.Connection.execute`, this accessor will then provide a list of rows, where each row contains the primary key value for each row that was INSERTed. * **When using all other dialects / backends that don't yet support this feature**: This accessor is only useful for **single row INSERT statements**, and returns the same information as that of the :attr:`_engine.CursorResult.inserted_primary_key` within a single-element list. When an INSERT statement is executed in conjunction with a list of rows to be INSERTed, the list will contain one row per row inserted in the statement, however it will contain ``None`` for any server-generated values. Future releases of SQLAlchemy will further generalize the "fast execution helper" feature of psycopg2 to suit other dialects, thus allowing this accessor to be of more general use. .. versionadded:: 1.4 .. seealso:: :attr:`_engine.CursorResult.inserted_primary_key` �1Statement is not a compiled expression construct.�2Statement is not an insert() expression construct.z9Can't call inserted_primary_key when returning() is used.)r� r� r r� �isinsertZ_is_explicit_returning�inserted_primary_key_rowsr\ rV rV rW rS & s .���z&CursorResult.inserted_primary_key_rowsc C s, | j jrt�d��| j}|r$|d S dS dS )a� Return the primary key for the row just inserted. The return value is a :class:`_result.Row` object representing a named tuple of primary key values in the order in which the primary key columns are configured in the source :class:`_schema.Table`. .. versionchanged:: 1.4.8 - the :attr:`_engine.CursorResult.inserted_primary_key` value is now a named tuple via the :class:`_result.Row` class, rather than a plain tuple. This accessor only applies to single row :func:`_expression.insert` constructs which did not explicitly specify :meth:`_expression.Insert.returning`. Support for multirow inserts, while not yet available for most backends, would be accessed using the :attr:`_engine.CursorResult.inserted_primary_key_rows` accessor. Note that primary key columns which specify a server_default clause, or otherwise do not qualify as "autoincrement" columns (see the notes at :class:`_schema.Column`), and were generated using the database-side default, will appear in this list as ``None`` unless the backend supports "returning" and the insert statement executed with the "implicit returning" enabled. Raises :class:`~sqlalchemy.exc.InvalidRequestError` if the executed statement is not a compiled expression construct or is not an insert() construct. zuThis statement was an executemany call; if primary key returning is supported, please use .inserted_primary_key_rows.r N)r� � executemanyr r� rS )rU ZikprV rV rW �inserted_primary_keyd s !�z!CursorResult.inserted_primary_keyc C sH | j jst�d��n0| j js(t�d��n | j jr8| j jS | j jd S dS )a Return the collection of updated parameters from this execution. Raises :class:`~sqlalchemy.exc.InvalidRequestError` if the executed statement is not a compiled expression construct or is not an update() construct. rP z2Statement is not an update() expression construct.r N)r� r� r r� �isupdaterT �compiled_parametersr\ rV rV rW �last_updated_params� s ��z CursorResult.last_updated_paramsc C sH | j jst�d��n0| j js(t�d��n | j jr8| j jS | j jd S dS )a Return the collection of inserted parameters from this execution. Raises :class:`~sqlalchemy.exc.InvalidRequestError` if the executed statement is not a compiled expression construct or is not an insert() construct. rP rQ r N)r� r� r r� rR rT rW r\ rV rV rW �last_inserted_params� s ��z!CursorResult.last_inserted_paramsc C s | j jS )a Return a list of rows each containing the values of default columns that were fetched using the :meth:`.ValuesBase.return_defaults` feature. The return value is a list of :class:`.Row` objects. .. versionadded:: 1.4 )r� �returned_default_rowsr\ rV rV rW �returned_defaults_rows� s z#CursorResult.returned_defaults_rowsc C sV | � � }dd� tt| �� �t|�� ��D �}|j�|j�|_td|d�|_|�� |S )ak Return a new :class:`.CursorResult` that "horizontally splices" together the rows of this :class:`.CursorResult` with that of another :class:`.CursorResult`. .. tip:: This method is for the benefit of the SQLAlchemy ORM and is not intended for general use. "horizontally splices" means that for each row in the first and second result sets, a new row that concatenates the two rows together is produced, which then becomes the new row. The incoming :class:`.CursorResult` must have the identical number of rows. It is typically expected that the two result sets come from the same sort order as well, as the result rows are spliced together based on their position in the result. The expected use case here is so that multiple INSERT..RETURNING statements (which definitely need to be sorted) against different tables can produce a single result that looks like a JOIN of those two tables. E.g.:: r1 = connection.execute( users.insert().returning( users.c.user_name, users.c.user_id, sort_by_parameter_order=True ), user_values, ) r2 = connection.execute( addresses.insert().returning( addresses.c.address_id, addresses.c.address, addresses.c.user_id, sort_by_parameter_order=True, ), address_values, ) rows = r1.splice_horizontally(r2).all() assert rows == [ ("john", 1, 1, "foo@bar.com", 1), ("jack", 2, 2, "bar@bat.com", 2), ] .. versionadded:: 2.0 .. seealso:: :meth:`.CursorResult.splice_vertically` c S s g | ]\}}t |�t |� �qS rV )rO )r[ Zr1Zr2rV rV rW r] s �z4CursorResult.splice_horizontally.<locals>.<listcomp>N�r ) � _generate�zipr� �_raw_row_iteratorr r| r1 r �_reset_memoizations�rU rs �cloneZ total_rowsrV rV rW �splice_horizontally� s 7 ���z CursorResult.splice_horizontallyc C s: | � � }t| �� �t|�� � }td|d�|_|�� |S )a� Return a new :class:`.CursorResult` that "vertically splices", i.e. "extends", the rows of this :class:`.CursorResult` with that of another :class:`.CursorResult`. .. tip:: This method is for the benefit of the SQLAlchemy ORM and is not intended for general use. "vertically splices" means the rows of the given result are appended to the rows of this cursor result. The incoming :class:`.CursorResult` must have rows that represent the identical list of columns in the identical order as they are in this :class:`.CursorResult`. .. versionadded:: 2.0 .. seealso:: :meth:`.CursorResult.splice_horizontally` Nr\ )r] r� r_ r1 r r` ra rV rV rW �splice_vertically s ��z CursorResult.splice_verticallyc C sF | j r| jj�dt|�� tt| j��� | _t d|d�| _ | � � | S )a rewind this result back to the given rowset. this is used internally for the case where an :class:`.Insert` construct combines the use of :meth:`.Insert.return_defaults` along with the "supplemental columns" feature. z CursorResult rewound %d row(s)Nr\ ) r: r� r rL rp r rC r rr r1 r r` �rU r rV rV rW �_rewind4 s �� �zCursorResult._rewindc C s. | j jrt�d��| j j}|r&|d S dS dS )ax Return the values of default columns that were fetched using the :meth:`.ValuesBase.return_defaults` feature. The value is an instance of :class:`.Row`, or ``None`` if :meth:`.ValuesBase.return_defaults` was not used or if the backend does not support RETURNING. .. seealso:: :meth:`.ValuesBase.return_defaults` zlThis statement was an executemany call; if return defaults is supported, please use .returned_defaults_rows.r N)r� rT r r� rZ re rV rV rW �returned_defaultsT s �z CursorResult.returned_defaultsc C s | j �� S )z�Return ``lastrow_has_defaults()`` from the underlying :class:`.ExecutionContext`. See :class:`.ExecutionContext` for details. )r� �lastrow_has_defaultsr\ rV rV rW rh o s z!CursorResult.lastrow_has_defaultsc C s6 | j jst�d��n| j js.| j js.t�d��| j jS )aM Return ``postfetch_cols()`` from the underlying :class:`.ExecutionContext`. See :class:`.ExecutionContext` for details. Raises :class:`~sqlalchemy.exc.InvalidRequestError` if the executed statement is not a compiled expression construct or is not an insert() or update() construct. rP �>Statement is not an insert() or update() expression construct.)r� r� r r� rR rV �postfetch_colsr\ rV rV rW rj y s ��zCursorResult.postfetch_colsc C s6 | j jst�d��n| j js.| j js.t�d��| j jS )aL Return ``prefetch_cols()`` from the underlying :class:`.ExecutionContext`. See :class:`.ExecutionContext` for details. Raises :class:`~sqlalchemy.exc.InvalidRequestError` if the executed statement is not a compiled expression construct or is not an insert() or update() construct. rP ri )r� r� r r� rR rV � prefetch_colsr\ rV rV rW rk � s ��zCursorResult.prefetch_colsc C s | j jS )z�Return ``supports_sane_rowcount`` from the dialect. See :attr:`_engine.CursorResult.rowcount` for background. )r� �supports_sane_rowcountr\ rV rV rW rl � s z#CursorResult.supports_sane_rowcountc C s | j jS )z�Return ``supports_sane_multi_rowcount`` from the dialect. See :attr:`_engine.CursorResult.rowcount` for background. )r� � supports_sane_multi_rowcountr\ rV rV rW rm � s z)CursorResult.supports_sane_multi_rowcountr� rY c C sH z | j jW S tyB } z | j�| | j|� � W Y d}~n d}~0 0 dS )a Return the 'rowcount' for this result. The primary purpose of 'rowcount' is to report the number of rows matched by the WHERE criterion of an UPDATE or DELETE statement executed once (i.e. for a single parameter set), which may then be compared to the number of rows expected to be updated or deleted as a means of asserting data integrity. This attribute is transferred from the ``cursor.rowcount`` attribute of the DBAPI before the cursor is closed, to support DBAPIs that don't make this value available after cursor close. Some DBAPIs may offer meaningful values for other kinds of statements, such as INSERT and SELECT statements as well. In order to retrieve ``cursor.rowcount`` for these statements, set the :paramref:`.Connection.execution_options.preserve_rowcount` execution option to True, which will cause the ``cursor.rowcount`` value to be unconditionally memoized before any results are returned or the cursor is closed, regardless of statement type. For cases where the DBAPI does not support rowcount for a particular kind of statement and/or execution, the returned value will be ``-1``, which is delivered directly from the DBAPI and is part of :pep:`249`. All DBAPIs should support rowcount for single-parameter-set UPDATE and DELETE statements, however. .. note:: Notes regarding :attr:`_engine.CursorResult.rowcount`: * This attribute returns the number of rows *matched*, which is not necessarily the same as the number of rows that were actually *modified*. For example, an UPDATE statement may have no net change on a given row if the SET values given are the same as those present in the row already. Such a row would be matched but not modified. On backends that feature both styles, such as MySQL, rowcount is configured to return the match count in all cases. * :attr:`_engine.CursorResult.rowcount` in the default case is *only* useful in conjunction with an UPDATE or DELETE statement, and only with a single set of parameters. For other kinds of statements, SQLAlchemy will not attempt to pre-memoize the value unless the :paramref:`.Connection.execution_options.preserve_rowcount` execution option is used. Note that contrary to :pep:`249`, many DBAPIs do not support rowcount values for statements that are not UPDATE or DELETE, particularly when rows are being returned which are not fully pre-buffered. DBAPIs that dont support rowcount for a particular kind of statement should return the value ``-1`` for such statements. * :attr:`_engine.CursorResult.rowcount` may not be meaningful when executing a single statement with multiple parameter sets (i.e. an :term:`executemany`). Most DBAPIs do not sum "rowcount" values across multiple parameter sets and will return ``-1`` when accessed. * SQLAlchemy's :ref:`engine_insertmanyvalues` feature does support a correct population of :attr:`_engine.CursorResult.rowcount` when the :paramref:`.Connection.execution_options.preserve_rowcount` execution option is set to True. * Statements that use RETURNING may not support rowcount, returning a ``-1`` value instead. .. seealso:: :ref:`tutorial_update_delete_rowcount` - in the :ref:`unified_tutorial` :paramref:`.Connection.execution_options.preserve_rowcount` N)r� �rowcountr� r r� r �rU r� rV rV rW rn � s L zCursorResult.rowcountc C sH z | j �� W S tyB } z | j�| | j|� W Y d}~n d}~0 0 dS )a0 Return the 'lastrowid' accessor on the DBAPI cursor. This is a DBAPI specific method and is only functional for those backends which support it, for statements where it is appropriate. It's behavior is not consistent across backends. Usage of this method is normally unnecessary when using insert() expression constructs; the :attr:`~CursorResult.inserted_primary_key` attribute provides a tuple of primary key values for a newly inserted row, regardless of database backend. N)r� Z get_lastrowidr� r r� r ro rV rV rW � lastrowid s zCursorResult.lastrowidc C s | j jS )aq True if this :class:`_engine.CursorResult` returns zero or more rows. I.e. if it is legal to call the methods :meth:`_engine.CursorResult.fetchone`, :meth:`_engine.CursorResult.fetchmany` :meth:`_engine.CursorResult.fetchall`. Overall, the value of :attr:`_engine.CursorResult.returns_rows` should always be synonymous with whether or not the DBAPI cursor had a ``.description`` attribute, indicating the presence of result columns, noting that a cursor that returns zero rows still has a ``.description`` if a row-returning statement was emitted. This attribute should be True for all results that are against SELECT statements, as well as for DML statements INSERT/UPDATE/DELETE that use RETURNING. For INSERT/UPDATE/DELETE statements that were not using RETURNING, the value will usually be False, however there are some dialect-specific exceptions to this, such as when using the MSSQL / pyodbc dialect a SELECT is emitted inline in order to retrieve an inserted primary key value. )r rO r\ rV rV rW rO s zCursorResult.returns_rowsc C s | j jS )al True if this :class:`_engine.CursorResult` is the result of a executing an expression language compiled :func:`_expression.insert` construct. When True, this implies that the :attr:`inserted_primary_key` attribute is accessible, assuming the statement did not include a user defined "returning" construct. )r� rR r\ rV rV rW � is_insert< s zCursorResult.is_insertc c s* | j j}|| | j�}|d u r q&|V qd S rR �r r� r )rU r� r rV rV rW �_fetchiter_implJ s z CursorResult._fetchiter_implc C s | j �| | j|�S rR rr )rU r� rV rV rW �_fetchone_implS s zCursorResult._fetchone_implc C s | j �| | j�S rR )r r� r r\ rV rV rW �_fetchall_implV s zCursorResult._fetchall_implNc C s | j �| | j|�S rR )r r� r )rU r� rV rV rW �_fetchmany_implY s z CursorResult._fetchmany_implc C s | � � S rR )rs r\ rV rV rW r_ \ s z CursorResult._raw_row_iteratorz Result[Any]zMergedResult[Any])�othersrQ c s2 t � j|� }| jjr.tdd� | f| D ��|_|S )Nc s s | ]}t d |�jV qdS )r� N)r rn )r[ r� rV rV rW r� b s �z%CursorResult.merge.<locals>.<genexpr>)r% �merger� Z _has_rowcount�sumrn )rU rw Z merged_resultr& rV rW rx _ s � zCursorResult.merger c C s | j dd� dS )a� Close this :class:`_engine.CursorResult`. This closes out the underlying DBAPI cursor corresponding to the statement execution, if one is still present. Note that the DBAPI cursor is automatically released when the :class:`_engine.CursorResult` exhausts all available rows. :meth:`_engine.CursorResult.close` is generally an optional method except in the case when discarding a :class:`_engine.CursorResult` that still has additional rows pending for fetch. After this method is called, it is no longer valid to call upon the fetch methods, which will raise a :class:`.ResourceClosedError` on subsequent use. .. seealso:: :ref:`connections_toplevel` Tr N)r r\ rV rV rW r- h s zCursorResult.closer( )r� rQ c C s || _ | j�| | j|� | S rR )Z _yield_perr r� r )rU r� rV rV rW r� ~ s zCursorResult.yield_per)F)F)N)-r� r� r� r� r� r� �_NO_RESULT_METADATArM r; r Z _is_cursorr� rF r r5 rS rU rX rY r[ rc rd rf rg rh rj rk rl rm r Zmemoized_propertyrn rp rO rq rs rt ru rv r_ rx r- r r� r0 rV rV r& rW r9 j sb ?/ % = - I Q r9 )br� � __future__r r rG rI �typingr r r r r r r r r r r r r r r r� r r r r r r r r � r r Zsqlr r r@ Zsql.baser Z sql.compilerr r! r" r# r$ Z sql.type_apir% r& Z util.typingr' r( �baser) r� r* Z interfacesr+ r, r- r. r/ r0 r1 r2 r3 r4 r5 r6 r8 r� r9 r: r< r> r@ rB r� r� Z_CursorKeyMapRecTyperM r� rC r� r� r r r Z_NO_CURSOR_DMLr Z_DEFAULT_FETCHr r1 r3 rz r8 r9 Z ResultProxyrV rV rV rW �<module> s� �� �� > X ;% ! sqlalchemy/engine/__pycache__/create.cpython-39.pyc 0000644 00000071152 15125143220 0016260 0 ustar 00 a ��Jh�� � & @ s� d dl mZ d dlZd dlZd dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlm Z d d lm Z d d lm Z d d lm Z d d l mZ d dl mZ d dlmZ d dlmZ ddl mZ ddl mZ ddl mZ ddlmZ ddlmZ ddlm Z ddlm Z ej �r�d dlm Z d dlm Z d dlm!Z! d d lm"Z" d d lm#Z# dd l$m%Z% dd lm&Z& dd lm'Z' dd!lm(Z( dd"lm)Z) dd#l*m+Z+ e d$d$d$d$d$d$d$d$d$d$d$d$d$d$d$d$d$d$d$d$d$d$d$d$d$d$d$d$d$d$d$d%� d&d'd(d)d*d*d(d+d,d(d,d-d.d/d/d0d1d0d-d2d3d4d5d1d(d-d-d6d7d(d8d-d(d9d:d;�#d<d=��Z,e d&d9d:d>�d?d=��Z,ej-d@dAdBdC�dDd9d:d>�dEd=��Z,d[dGd1d9d:dH�dIdJ�Z.e d$d$d$d$d$d$d$d$dK�d&d5d1d(d-d-d6d7d(d9dLdM� dNdO��Z/e d&d9dLd>�dPdO��Z/d&d9dLd>�dQdO�Z/e dRdSdTdUdVdWdXdYdZ��Z0dS )\� )� annotationsN)�Any)�Callable)�cast)�Dict)�List)�Optional)�overload)�Type)�Union� )�base)�url)�DBAPIConnection)�create_mock_engine� )�event)�exc)�util)�_AdhocProxiedConnection)�ConnectionPoolEntry)�compiler)� immutabledict)�Engine)�_ExecuteOptions)� _ParamStyle)�IsolationLevel)�URL)� _EchoFlagType)�_CreatorFnType)�_CreatorWRecFnType)�_ResetStyleArgType)�Pool)�Literal.) � connect_args�convert_unicode�creator�echo� echo_pool�enable_from_linting�execution_options�hide_parameters�implicit_returning�insertmanyvalues_page_size�isolation_level�json_deserializer�json_serializer� label_length� logging_name�max_identifier_length� max_overflow�module� paramstyle�pool� poolclass�pool_logging_name� pool_pre_ping� pool_size� pool_recycle�pool_reset_on_return� pool_timeout� pool_use_lifo�plugins�query_cache_size�use_insertmanyvalueszUnion[str, URL]zDict[Any, Any]�boolz)Union[_CreatorFnType, _CreatorWRecFnType]r r z Literal[True]�intr zCallable[..., Any]z Optional[int]�str� Optional[Any]zOptional[_ParamStyle]zOptional[Pool]zOptional[Type[Pool]]z Optional[_ResetStyleArgType]�floatz List[str]r r )#r r$ r% r& r' r( r) r* �futurer+ r, r- r. r/ r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 r: r; r< r= r> r? r@ rA rB �kwargs�returnc " K s d S �N� )"r r$ r% r& r' r( r) r* rH r+ r, r- r. r/ r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 r: r; r< r= r> r? r@ rA rB rI rL rL �M/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/engine/create.py� create_engine0 s %rN )r rI rJ c K s d S rK rL �r rI rL rL rM rN X s )�1.4a" The :paramref:`_sa.create_engine.strategy` keyword is deprecated, and the only argument accepted is 'mock'; please use :func:`.create_mock_engine` going forward. For general customization of create_engine which may have been accomplished using strategies, see :class:`.CreateEnginePlugin`.)rP a The :paramref:`_sa.create_engine.empty_in_strategy` keyword is deprecated, and no longer has any effect. All IN expressions are now rendered using the "expanding parameter" strategy which renders a set of boundexpressions, or an "empty set" SELECT, at statement executiontime.)�2.0zvThe :paramref:`_sa.create_engine.implicit_returning` parameter is deprecated and will be removed in a future release. )�strategy�empty_in_strategyr, zUnion[str, _url.URL]c s� d�v r8�� d�}|dkr*t| fi ���S t�d| ���� dd� t�| �}|���\}}�|�� }�� dd�}|r�|�|��n |� |���� dd�r�d<d d d d ���fd d� }n�j }i }t � ��D ]} | �v r�|| �|| < qȈ� dd�} | du �r�i } d�j v �r�j } n<t�d��rFt��j��rFt �d�� d�d� �j} n�j } t �| �D ] } | �v �rV|| �| | < �qV| f i | ��} | |d< |�dtj� �� dd�} | �r�|d tjN < |D ]}|��|� �q��f i |�����|�\}���|di �� d�v �r&t ��d ��r&t �dd� t |�� |dd�}|du �r�d=d d d �� ��fd d � }|d!|�}|d"d�}|du �r��� |�}d#�i}t � |�D ](} t � | | �}|�v �r�||�|| < �q�|D ]}|� ||� �q�||fi |��}n�|_!t|d$��r6|j"�j#u�r6tjd%|j$j%� d&�j#�s&d'nd(� d)�d*d+��|d,d��sLt�d-��t&j'}i }t � |�D ] } | �v �r`|| �|| < �q`�� d.d�}��r�t(d/d0�)d1d2� �D ���j$j%|j$j%|j%f ��||�|fi |���|�rR��*|����r d d3d4d5��fd6d7� }t+�,|d8|� ��-� }|�r(t+�,|d8|� d d3d4d5���fd9d:� }t+j,|d8|dd;� ��.�� |�u�rp|�.�� |D ]}|�.�� �qt�S )>a�E Create a new :class:`_engine.Engine` instance. The standard calling form is to send the :ref:`URL <database_urls>` as the first positional argument, usually a string that indicates database dialect and connection arguments:: engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test") .. note:: Please review :ref:`database_urls` for general guidelines in composing URL strings. In particular, special characters, such as those often part of passwords, must be URL encoded to be properly parsed. Additional keyword arguments may then follow it which establish various options on the resulting :class:`_engine.Engine` and its underlying :class:`.Dialect` and :class:`_pool.Pool` constructs:: engine = create_engine( "mysql+mysqldb://scott:tiger@hostname/dbname", pool_recycle=3600, echo=True, ) The string form of the URL is ``dialect[+driver]://user:password@host/dbname[?key=value..]``, where ``dialect`` is a database name such as ``mysql``, ``oracle``, ``postgresql``, etc., and ``driver`` the name of a DBAPI, such as ``psycopg2``, ``pyodbc``, ``cx_oracle``, etc. Alternatively, the URL can be an instance of :class:`~sqlalchemy.engine.url.URL`. ``**kwargs`` takes a wide variety of options which are routed towards their appropriate components. Arguments may be specific to the :class:`_engine.Engine`, the underlying :class:`.Dialect`, as well as the :class:`_pool.Pool`. Specific dialects also accept keyword arguments that are unique to that dialect. Here, we describe the parameters that are common to most :func:`_sa.create_engine()` usage. Once established, the newly resulting :class:`_engine.Engine` will request a connection from the underlying :class:`_pool.Pool` once :meth:`_engine.Engine.connect` is called, or a method which depends on it such as :meth:`_engine.Engine.execute` is invoked. The :class:`_pool.Pool` in turn will establish the first actual DBAPI connection when this request is received. The :func:`_sa.create_engine` call itself does **not** establish any actual DBAPI connections directly. .. seealso:: :doc:`/core/engines` :doc:`/dialects/index` :ref:`connections_toplevel` :param connect_args: a dictionary of options which will be passed directly to the DBAPI's ``connect()`` method as additional keyword arguments. See the example at :ref:`custom_dbapi_args`. :param creator: a callable which returns a DBAPI connection. This creation function will be passed to the underlying connection pool and will be used to create all new database connections. Usage of this function causes connection parameters specified in the URL argument to be bypassed. This hook is not as flexible as the newer :meth:`_events.DialectEvents.do_connect` hook which allows complete control over how a connection is made to the database, given the full set of URL arguments and state beforehand. .. seealso:: :meth:`_events.DialectEvents.do_connect` - event hook that allows full control over DBAPI connection mechanics. :ref:`custom_dbapi_args` :param echo=False: if True, the Engine will log all statements as well as a ``repr()`` of their parameter lists to the default log handler, which defaults to ``sys.stdout`` for output. If set to the string ``"debug"``, result rows will be printed to the standard output as well. The ``echo`` attribute of ``Engine`` can be modified at any time to turn logging on and off; direct control of logging is also available using the standard Python ``logging`` module. .. seealso:: :ref:`dbengine_logging` - further detail on how to configure logging. :param echo_pool=False: if True, the connection pool will log informational output such as when connections are invalidated as well as when connections are recycled to the default log handler, which defaults to ``sys.stdout`` for output. If set to the string ``"debug"``, the logging will include pool checkouts and checkins. Direct control of logging is also available using the standard Python ``logging`` module. .. seealso:: :ref:`dbengine_logging` - further detail on how to configure logging. :param empty_in_strategy: No longer used; SQLAlchemy now uses "empty set" behavior for IN in all cases. :param enable_from_linting: defaults to True. Will emit a warning if a given SELECT statement is found to have un-linked FROM elements which would cause a cartesian product. .. versionadded:: 1.4 .. seealso:: :ref:`change_4737` :param execution_options: Dictionary execution options which will be applied to all connections. See :meth:`~sqlalchemy.engine.Connection.execution_options` :param future: Use the 2.0 style :class:`_engine.Engine` and :class:`_engine.Connection` API. As of SQLAlchemy 2.0, this parameter is present for backwards compatibility only and must remain at its default value of ``True``. The :paramref:`_sa.create_engine.future` parameter will be deprecated in a subsequent 2.x release and eventually removed. .. versionadded:: 1.4 .. versionchanged:: 2.0 All :class:`_engine.Engine` objects are "future" style engines and there is no longer a ``future=False`` mode of operation. .. seealso:: :ref:`migration_20_toplevel` :param hide_parameters: Boolean, when set to True, SQL statement parameters will not be displayed in INFO logging nor will they be formatted into the string representation of :class:`.StatementError` objects. .. versionadded:: 1.3.8 .. seealso:: :ref:`dbengine_logging` - further detail on how to configure logging. :param implicit_returning=True: Legacy parameter that may only be set to True. In SQLAlchemy 2.0, this parameter does nothing. In order to disable "implicit returning" for statements invoked by the ORM, configure this on a per-table basis using the :paramref:`.Table.implicit_returning` parameter. :param insertmanyvalues_page_size: number of rows to format into an INSERT statement when the statement uses "insertmanyvalues" mode, which is a paged form of bulk insert that is used for many backends when using :term:`executemany` execution typically in conjunction with RETURNING. Defaults to 1000, but may also be subject to dialect-specific limiting factors which may override this value on a per-statement basis. .. versionadded:: 2.0 .. seealso:: :ref:`engine_insertmanyvalues` :ref:`engine_insertmanyvalues_page_size` :paramref:`_engine.Connection.execution_options.insertmanyvalues_page_size` :param isolation_level: optional string name of an isolation level which will be set on all new connections unconditionally. Isolation levels are typically some subset of the string names ``"SERIALIZABLE"``, ``"REPEATABLE READ"``, ``"READ COMMITTED"``, ``"READ UNCOMMITTED"`` and ``"AUTOCOMMIT"`` based on backend. The :paramref:`_sa.create_engine.isolation_level` parameter is in contrast to the :paramref:`.Connection.execution_options.isolation_level` execution option, which may be set on an individual :class:`.Connection`, as well as the same parameter passed to :meth:`.Engine.execution_options`, where it may be used to create multiple engines with different isolation levels that share a common connection pool and dialect. .. versionchanged:: 2.0 The :paramref:`_sa.create_engine.isolation_level` parameter has been generalized to work on all dialects which support the concept of isolation level, and is provided as a more succinct, up front configuration switch in contrast to the execution option which is more of an ad-hoc programmatic option. .. seealso:: :ref:`dbapi_autocommit` :param json_deserializer: for dialects that support the :class:`_types.JSON` datatype, this is a Python callable that will convert a JSON string to a Python object. By default, the Python ``json.loads`` function is used. .. versionchanged:: 1.3.7 The SQLite dialect renamed this from ``_json_deserializer``. :param json_serializer: for dialects that support the :class:`_types.JSON` datatype, this is a Python callable that will render a given object as JSON. By default, the Python ``json.dumps`` function is used. .. versionchanged:: 1.3.7 The SQLite dialect renamed this from ``_json_serializer``. :param label_length=None: optional integer value which limits the size of dynamically generated column labels to that many characters. If less than 6, labels are generated as "_(counter)". If ``None``, the value of ``dialect.max_identifier_length``, which may be affected via the :paramref:`_sa.create_engine.max_identifier_length` parameter, is used instead. The value of :paramref:`_sa.create_engine.label_length` may not be larger than that of :paramref:`_sa.create_engine.max_identfier_length`. .. seealso:: :paramref:`_sa.create_engine.max_identifier_length` :param logging_name: String identifier which will be used within the "name" field of logging records generated within the "sqlalchemy.engine" logger. Defaults to a hexstring of the object's id. .. seealso:: :ref:`dbengine_logging` - further detail on how to configure logging. :paramref:`_engine.Connection.execution_options.logging_token` :param max_identifier_length: integer; override the max_identifier_length determined by the dialect. if ``None`` or zero, has no effect. This is the database's configured maximum number of characters that may be used in a SQL identifier such as a table name, column name, or label name. All dialects determine this value automatically, however in the case of a new database version for which this value has changed but SQLAlchemy's dialect has not been adjusted, the value may be passed here. .. versionadded:: 1.3.9 .. seealso:: :paramref:`_sa.create_engine.label_length` :param max_overflow=10: the number of connections to allow in connection pool "overflow", that is connections that can be opened above and beyond the pool_size setting, which defaults to five. this is only used with :class:`~sqlalchemy.pool.QueuePool`. :param module=None: reference to a Python module object (the module itself, not its string name). Specifies an alternate DBAPI module to be used by the engine's dialect. Each sub-dialect references a specific DBAPI which will be imported before first connect. This parameter causes the import to be bypassed, and the given module to be used instead. Can be used for testing of DBAPIs as well as to inject "mock" DBAPI implementations into the :class:`_engine.Engine`. :param paramstyle=None: The `paramstyle <https://legacy.python.org/dev/peps/pep-0249/#paramstyle>`_ to use when rendering bound parameters. This style defaults to the one recommended by the DBAPI itself, which is retrieved from the ``.paramstyle`` attribute of the DBAPI. However, most DBAPIs accept more than one paramstyle, and in particular it may be desirable to change a "named" paramstyle into a "positional" one, or vice versa. When this attribute is passed, it should be one of the values ``"qmark"``, ``"numeric"``, ``"named"``, ``"format"`` or ``"pyformat"``, and should correspond to a parameter style known to be supported by the DBAPI in use. :param pool=None: an already-constructed instance of :class:`~sqlalchemy.pool.Pool`, such as a :class:`~sqlalchemy.pool.QueuePool` instance. If non-None, this pool will be used directly as the underlying connection pool for the engine, bypassing whatever connection parameters are present in the URL argument. For information on constructing connection pools manually, see :ref:`pooling_toplevel`. :param poolclass=None: a :class:`~sqlalchemy.pool.Pool` subclass, which will be used to create a connection pool instance using the connection parameters given in the URL. Note this differs from ``pool`` in that you don't actually instantiate the pool in this case, you just indicate what type of pool to be used. :param pool_logging_name: String identifier which will be used within the "name" field of logging records generated within the "sqlalchemy.pool" logger. Defaults to a hexstring of the object's id. .. seealso:: :ref:`dbengine_logging` - further detail on how to configure logging. :param pool_pre_ping: boolean, if True will enable the connection pool "pre-ping" feature that tests connections for liveness upon each checkout. .. versionadded:: 1.2 .. seealso:: :ref:`pool_disconnects_pessimistic` :param pool_size=5: the number of connections to keep open inside the connection pool. This used with :class:`~sqlalchemy.pool.QueuePool` as well as :class:`~sqlalchemy.pool.SingletonThreadPool`. With :class:`~sqlalchemy.pool.QueuePool`, a ``pool_size`` setting of 0 indicates no limit; to disable pooling, set ``poolclass`` to :class:`~sqlalchemy.pool.NullPool` instead. :param pool_recycle=-1: this setting causes the pool to recycle connections after the given number of seconds has passed. It defaults to -1, or no timeout. For example, setting to 3600 means connections will be recycled after one hour. Note that MySQL in particular will disconnect automatically if no activity is detected on a connection for eight hours (although this is configurable with the MySQLDB connection itself and the server configuration as well). .. seealso:: :ref:`pool_setting_recycle` :param pool_reset_on_return='rollback': set the :paramref:`_pool.Pool.reset_on_return` parameter of the underlying :class:`_pool.Pool` object, which can be set to the values ``"rollback"``, ``"commit"``, or ``None``. .. seealso:: :ref:`pool_reset_on_return` :param pool_timeout=30: number of seconds to wait before giving up on getting a connection from the pool. This is only used with :class:`~sqlalchemy.pool.QueuePool`. This can be a float but is subject to the limitations of Python time functions which may not be reliable in the tens of milliseconds. .. note: don't use 30.0 above, it seems to break with the :param tag :param pool_use_lifo=False: use LIFO (last-in-first-out) when retrieving connections from :class:`.QueuePool` instead of FIFO (first-in-first-out). Using LIFO, a server-side timeout scheme can reduce the number of connections used during non- peak periods of use. When planning for server-side timeouts, ensure that a recycle or pre-ping strategy is in use to gracefully handle stale connections. .. versionadded:: 1.3 .. seealso:: :ref:`pool_use_lifo` :ref:`pool_disconnects` :param plugins: string list of plugin names to load. See :class:`.CreateEnginePlugin` for background. .. versionadded:: 1.2.3 :param query_cache_size: size of the cache used to cache the SQL string form of queries. Set to zero to disable caching. The cache is pruned of its least recently used items when its size reaches N * 1.5. Defaults to 500, meaning the cache will always store at least 500 SQL statements when filled, and will grow up to 750 items at which point it is pruned back down to 500 by removing the 250 least recently used items. Caching is accomplished on a per-statement basis by generating a cache key that represents the statement's structure, then generating string SQL for the current dialect only if that key is not present in the cache. All statements support caching, however some features such as an INSERT with a large set of parameters will intentionally bypass the cache. SQL logging will indicate statistics for each statement whether or not it were pull from the cache. .. note:: some ORM functions related to unit-of-work persistence as well as some attribute loading strategies will make use of individual per-mapper caches outside of the main cache. .. seealso:: :ref:`sql_caching` .. versionadded:: 1.4 :param use_insertmanyvalues: True by default, use the "insertmanyvalues" execution style for INSERT..RETURNING statements by default. .. versionadded:: 2.0 .. seealso:: :ref:`engine_insertmanyvalues` rR �mockzunknown strategy: %rrS N� _is_asyncF�_coerce_configrE rF r )�key�defaultrJ c s( �� | |�}| � jv r$� j| |�}|S rK )�popZengine_config_types)rW rX �value)� dialect_clsrI rL rM � pop_kwarg2 s z create_engine.<locals>.pop_kwargr5 � import_dbapi�dbapiz�The dbapi() classmethod on dialect classes has been renamed to import_dbapi(). Implement an import_dbapi() classmethod directly on class zd to remove this warning; the old .dbapi() classmethod may be maintained for backwards compatibility.rQ Zcompiler_lintingr) Tr$ Zasync_fallbackzXThe async_fallback dialect argument is deprecated and will be removed in SQLAlchemy 2.1.r7 z Optional[ConnectionPoolEntry]r )�connection_recordrJ c sH �j r8�jjD ](}tt|�| � ���}|d ur| S q�j� i ���S rK )� _has_events�dispatchZ do_connectr r �connect)r_ �fn� connection)�cargs�cparams�dialectrL rM rb z s � z create_engine.<locals>.connectr& r8 rg � _is_asyncioz Pool class z cannot be used with znon-� zasyncio engineZpcls)�coderH zIThe 'future' parameter passed to create_engine() may only be set to True.� _initializez�Invalid argument(s) %s sent to create_engine(), using configuration %s/%s/%s. Please check that the keyword arguments are appropriate for this combination of components.�,c s s | ]}d | V qdS )z'%s'NrL )�.0�krL rL rM � <genexpr>� � z create_engine.<locals>.<genexpr>r �None)�dbapi_connectionr_ rJ c s � d us J �� | � d S rK rL )rr r_ )� do_on_connectrL rM � on_connect� s z!create_engine.<locals>.on_connectrb c sh t j�t| |�dddd�}tj|_z&� �|� W |jsd|jsd� � |j � n|jsb|jsb� � |j � 0 d S )NF)rd r` Z_allow_revalidateZ_allow_autobegin) r � Connectionr r � EMPTY_DICTZ_execution_optionsZ initializeZ invalidated�closedZ do_rollbackrd )rr r_ �c)rg �enginerL rM � first_connect� s �� � z$create_engine.<locals>.first_connect)Z_once_unless_exception)N)N)/rY r r � ArgumentError�_urlZmake_urlZ_instantiate_pluginsZ_get_entrypointZget_async_dialect_clsZget_dialect_clsr Zget_cls_kwargs�__dict__r] �hasattr�inspect�ismethodr^ Zwarn_deprecatedZget_func_kwargs� setdefaultr Z NO_LINTINGZCOLLECT_CARTESIAN_PRODUCTSZhandle_dialect_kwargsZcreate_connect_args�updateZasbool�listZget_dialect_pool_class�_pool_translate_kwargs�getZhandle_pool_kwargsZ_dialectrh �is_async� __class__�__name__r r � TypeError�joinZon_connect_urlr �listenZ_builtin_onconnectZengine_created) r rI Zstrat�ur@ Z entrypointrU r\ Z dialect_argsrn r^ Z dbapi_argsZ dbapi_methr) ZpluginZ cargs_tupr7 rb r& r8 Z pool_argsZtkZ engineclassZ engine_argsrk rt Zbuiltin_on_connectrz rL )re rf rg r[ rs ry rI rM rN \ s� A ��� � � � � �� � ��� #� � sqlalchemy.zDict[str, Any])� configuration�prefixrI rJ c s@ � �fdd�� D �}d|d< |� |� |�d�}t|fi |��S )a� Create a new Engine instance using a configuration dictionary. The dictionary is typically produced from a config file. The keys of interest to ``engine_from_config()`` should be prefixed, e.g. ``sqlalchemy.url``, ``sqlalchemy.echo``, etc. The 'prefix' argument indicates the prefix to be searched for. Each matching key (after the prefix is stripped) is treated as though it were the corresponding keyword argument to a :func:`_sa.create_engine` call. The only required key is (assuming the default prefix) ``sqlalchemy.url``, which provides the :ref:`database URL <database_urls>`. A select set of keyword arguments will be "coerced" to their expected type based on string values. The set of arguments is extensible per-dialect using the ``engine_config_types`` accessor. :param configuration: A dictionary (typically produced from a config file, but this is not a requirement). Items whose keys start with the value of 'prefix' will have that prefix stripped, and will then be passed to :func:`_sa.create_engine`. :param prefix: Prefix to match and then strip from keys in 'configuration'. :param kwargs: Each keyword argument to ``engine_from_config()`` itself overrides the corresponding item taken from the 'configuration' dictionary. Keyword arguments should *not* be prefixed. c s, i | ]$}|� ��r|t��d � � | �qS rK )� startswith�len)rm rW �r� r� rL rM � <dictcomp>/ s �z&engine_from_config.<locals>.<dictcomp>TrV r )r� rY rN )r� r� rI �optionsr rL r� rM �engine_from_config s " � r� )r8 r2 �pre_ping�size�recycle�reset_on_return�timeout�use_lifor" ) r r8 r2 r� r� r� r� r� r� rI rJ c K s d S rK rL ) r r8 r2 r� r� r� r� r� r� rI rL rL rM �create_pool_from_url: s r� c K s d S rK rL rO rL rL rM r� J s c K sB t D ] }||v r|�|�|t | < qt| fi |�ddi��}|jS )aZ Create a pool instance from the given url. If ``poolclass`` is not provided the pool class used is selected using the dialect specified in the URL. The arguments passed to :func:`_sa.create_pool_from_url` are identical to the pool argument passed to the :func:`_sa.create_engine` function. .. versionadded:: 2.0.10 rk F)r� rY rN r7 )r rI rW ry rL rL rM r� N s r9 r( r> r< Z pool_eventsr= r: r? )r2 r' r� r� �eventsr� r� r� )r� )1� __future__r r �typingr r r r r r r r r ri r r r| Z interfacesr rT r r r r r7 r r Zsqlr r � TYPE_CHECKINGr r r r r �logr r r r! r" Z util.typingr# rN Zdeprecated_paramsr� r� r� rL rL rL rM �<module> s� �X' � �-�(�� sqlalchemy/engine/__pycache__/events.cpython-39.pyc 0000644 00000110500 15125143220 0016310 0 ustar 00 a ��Jh� � @ s� d dl mZ d dlZd dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d d l m Z d d l m Z d d l m Z d d l mZ d dl mZ d dl mZ ddlmZ ddlmZ ddlmZ ej�r`d dl mZ d dl mZ d dl mZ d dl mZ d dl mZ d dl m Z d dl m Z d dl m Z d d l m Z dd l!m"Z" dd l#m$Z$ dd l%m&Z& G d d!� d!ej'e �Z(G d"d#� d#ej'e �Z)dS )$� )� annotationsN)�Any)�Dict)�Optional)�Tuple)�Type)�Union� )� Connection)�Engine)�ConnectionEventsTarget)�DBAPIConnection)� DBAPICursor)�Dialect� )�event)�exc)�Literal)�_CoreMultiExecuteParams)�_CoreSingleExecuteParams)�_DBAPIAnyExecuteParams)�_DBAPIMultiExecuteParams)�_DBAPISingleExecuteParams)�_ExecuteOptions)�ExceptionContext)�ExecutionContext)�Result)�ConnectionPoolEntry)� Executable)� BindParameterc s� e Zd ZdZdZeZedddd�� fdd� �Zed d �d d d dd�dd��Z e � dg d�dd� �ddddddd �d d ��Z e � dg d �d d� �dddddd!dd"�d#d$��Z dd%dd&d'd d(d)�d*d+�Zdd%dd&d'd dd)�d,d-�Ze j d.d/d0gd1d� d2�ddd3�d4d5��Zdd6dd7�d8d9�Zd:d6dd;�d<d=�Zd:dd>�d?d@�Zddd3�dAdB�Zddd3�dCdD�Zddd3�dEdF�ZddddG�dHdI�ZdddddJ�dKdL�ZdddddJ�dMdN�Zdd ddO�dPdQ�Zdd ddO�dRdS�Zdd d ddT�dUdV�Z dd d ddT�dWdX�Z � Z S )Y�ConnectionEventsa Available events for :class:`_engine.Connection` and :class:`_engine.Engine`. The methods here define the name of an event as well as the names of members that are passed to listener functions. An event listener can be associated with any :class:`_engine.Connection` or :class:`_engine.Engine` class or instance, such as an :class:`_engine.Engine`, e.g.:: from sqlalchemy import event, create_engine def before_cursor_execute( conn, cursor, statement, parameters, context, executemany ): log.info("Received statement: %s", statement) engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test") event.listen(engine, "before_cursor_execute", before_cursor_execute) or with a specific :class:`_engine.Connection`:: with engine.begin() as conn: @event.listens_for(conn, "before_cursor_execute") def before_cursor_execute( conn, cursor, statement, parameters, context, executemany ): log.info("Received statement: %s", statement) When the methods are called with a `statement` parameter, such as in :meth:`.after_cursor_execute` or :meth:`.before_cursor_execute`, the statement is the exact SQL string that was prepared for transmission to the DBAPI ``cursor`` in the connection's :class:`.Dialect`. The :meth:`.before_execute` and :meth:`.before_cursor_execute` events can also be established with the ``retval=True`` flag, which allows modification of the statement and parameters to be sent to the database. The :meth:`.before_cursor_execute` event is particularly useful here to add ad-hoc string transformations, such as comments, to all executions:: from sqlalchemy.engine import Engine from sqlalchemy import event @event.listens_for(Engine, "before_cursor_execute", retval=True) def comment_sql_calls( conn, cursor, statement, parameters, context, executemany ): statement = statement + " -- some comment" return statement, parameters .. note:: :class:`_events.ConnectionEvents` can be established on any combination of :class:`_engine.Engine`, :class:`_engine.Connection`, as well as instances of each of those classes. Events across all four scopes will fire off for a given instance of :class:`_engine.Connection`. However, for performance reasons, the :class:`_engine.Connection` object determines at instantiation time whether or not its parent :class:`_engine.Engine` has event listeners established. Event listeners added to the :class:`_engine.Engine` class or to an instance of :class:`_engine.Engine` *after* the instantiation of a dependent :class:`_engine.Connection` instance will usually *not* be available on that :class:`_engine.Connection` instance. The newly added listeners will instead take effect for :class:`_engine.Connection` instances created subsequent to those event listeners being established on the parent :class:`_engine.Engine` class or instance. :param retval=False: Applies to the :meth:`.before_execute` and :meth:`.before_cursor_execute` events only. When True, the user-defined event function must have a return value, which is a tuple of parameters that replace the given statement and parameters. See those methods for a description of specific return arguments. � SomeEnginez;Union[ConnectionEventsTarget, Type[ConnectionEventsTarget]]�strzEOptional[Union[ConnectionEventsTarget, Type[ConnectionEventsTarget]]]��target� identifier�returnc s, t � �||�}|d u r(t|d�r(|�� |S )N�_no_async_engine_events)�super� _accept_with�hasattrr' )�clsr$ r% Zdefault_dispatch�� __class__� �M/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/engine/events.pyr) � s �z ConnectionEvents._accept_withF��retvalz'event._EventKey[ConnectionEventsTarget]�boolr �None�� event_keyr1 �kwr& c s� |j |j|j }}}d|_|s\|dkr>|� � fdd�}|}qr|dkrr|� � fdd�}|}n|rr|dvrrt�d ��|�|��� d S ) NT�before_executec s � | ||||� |||fS �Nr. ��conn� clauseelement� multiparams�params�execution_options�Zorig_fnr. r/ �wrap_before_execute� s �z5ConnectionEvents._listen.<locals>.wrap_before_execute�before_cursor_executec s � | |||||� ||fS r8 r. )r: �cursor� statement� parameters�context� executemanyr? r. r/ �wrap_before_cursor_execute� s �z<ConnectionEvents._listen.<locals>.wrap_before_cursor_execute)r7 rA zOnly the 'before_execute', 'before_cursor_execute' and 'handle_error' engine event listeners accept the 'retval=True' argument.)�dispatch_targetr% Z _listen_fn� _has_eventsr � ArgumentErrorZ with_wrapper� base_listen) r+ r5 r1 r6 r$ r% �fnr@ rG r. r? r/ �_listen� s& � �zConnectionEvents._listenz1.4)r: r; r< r= c C s | |||fS r8 r. r9 r. r. r/ �<lambda>� s �zConnectionEvents.<lambda>r r r r r zNOptional[Tuple[Executable, _CoreMultiExecuteParams, _CoreSingleExecuteParams]])r: r; r< r= r> r& c C s dS )a[ Intercept high level execute() events, receiving uncompiled SQL constructs and other objects prior to rendering into SQL. This event is good for debugging SQL compilation issues as well as early manipulation of the parameters being sent to the database, as the parameter lists will be in a consistent format here. This event can be optionally established with the ``retval=True`` flag. The ``clauseelement``, ``multiparams``, and ``params`` arguments should be returned as a three-tuple in this case:: @event.listens_for(Engine, "before_execute", retval=True) def before_execute(conn, clauseelement, multiparams, params): # do something with clauseelement, multiparams, params return clauseelement, multiparams, params :param conn: :class:`_engine.Connection` object :param clauseelement: SQL expression construct, :class:`.Compiled` instance, or string statement passed to :meth:`_engine.Connection.execute`. :param multiparams: Multiple parameter sets, a list of dictionaries. :param params: Single parameter set, a single dictionary. :param execution_options: dictionary of execution options passed along with the statement, if any. This is a merge of all options that will be used, including those of the statement, the connection, and those passed in to the method itself for the 2.0 style of execution. .. versionadded: 1.4 .. seealso:: :meth:`.before_cursor_execute` Nr. )�selfr: r; r< r= r> r. r. r/ r7 � s z ConnectionEvents.before_execute)r: r; r< r= �resultc C s | ||||fS r8 r. )r: r; r< r= r> rP r. r. r/ rN s �z Result[Any])r: r; r< r= r> rP r& c C s dS )ag Intercept high level execute() events after execute. :param conn: :class:`_engine.Connection` object :param clauseelement: SQL expression construct, :class:`.Compiled` instance, or string statement passed to :meth:`_engine.Connection.execute`. :param multiparams: Multiple parameter sets, a list of dictionaries. :param params: Single parameter set, a single dictionary. :param execution_options: dictionary of execution options passed along with the statement, if any. This is a merge of all options that will be used, including those of the statement, the connection, and those passed in to the method itself for the 2.0 style of execution. .. versionadded: 1.4 :param result: :class:`_engine.CursorResult` generated by the execution. Nr. )rO r: r; r< r= r> rP r. r. r/ � after_execute s z ConnectionEvents.after_executer r zOptional[ExecutionContext]z,Optional[Tuple[str, _DBAPIAnyExecuteParams]])r: rB rC rD rE rF r& c C s dS )a� Intercept low-level cursor execute() events before execution, receiving the string SQL statement and DBAPI-specific parameter list to be invoked against a cursor. This event is a good choice for logging as well as late modifications to the SQL string. It's less ideal for parameter modifications except for those which are specific to a target backend. This event can be optionally established with the ``retval=True`` flag. The ``statement`` and ``parameters`` arguments should be returned as a two-tuple in this case:: @event.listens_for(Engine, "before_cursor_execute", retval=True) def before_cursor_execute( conn, cursor, statement, parameters, context, executemany ): # do something with statement, parameters return statement, parameters See the example at :class:`_events.ConnectionEvents`. :param conn: :class:`_engine.Connection` object :param cursor: DBAPI cursor object :param statement: string SQL statement, as to be passed to the DBAPI :param parameters: Dictionary, tuple, or list of parameters being passed to the ``execute()`` or ``executemany()`` method of the DBAPI ``cursor``. In some cases may be ``None``. :param context: :class:`.ExecutionContext` object in use. May be ``None``. :param executemany: boolean, if ``True``, this is an ``executemany()`` call, if ``False``, this is an ``execute()`` call. .. seealso:: :meth:`.before_execute` :meth:`.after_cursor_execute` Nr. �rO r: rB rC rD rE rF r. r. r/ rA 0 s z&ConnectionEvents.before_cursor_executec C s dS )aQ Intercept low-level cursor execute() events after execution. :param conn: :class:`_engine.Connection` object :param cursor: DBAPI cursor object. Will have results pending if the statement was a SELECT, but these should not be consumed as they will be needed by the :class:`_engine.CursorResult`. :param statement: string SQL statement, as passed to the DBAPI :param parameters: Dictionary, tuple, or list of parameters being passed to the ``execute()`` or ``executemany()`` method of the DBAPI ``cursor``. In some cases may be ``None``. :param context: :class:`.ExecutionContext` object in use. May be ``None``. :param executemany: boolean, if ``True``, this is an ``executemany()`` call, if ``False``, this is an ``execute()`` call. Nr. rR r. r. r/ �after_cursor_executea s z%ConnectionEvents.after_cursor_executez2.0r: �branchc C s | dfS )NFr. )r: r. r. r/ rN | � )� converter)r: r& c C s dS )a� Intercept the creation of a new :class:`_engine.Connection`. This event is called typically as the direct result of calling the :meth:`_engine.Engine.connect` method. It differs from the :meth:`_events.PoolEvents.connect` method, which refers to the actual connection to a database at the DBAPI level; a DBAPI connection may be pooled and reused for many operations. In contrast, this event refers only to the production of a higher level :class:`_engine.Connection` wrapper around such a DBAPI connection. It also differs from the :meth:`_events.PoolEvents.checkout` event in that it is specific to the :class:`_engine.Connection` object, not the DBAPI connection that :meth:`_events.PoolEvents.checkout` deals with, although this DBAPI connection is available here via the :attr:`_engine.Connection.connection` attribute. But note there can in fact be multiple :meth:`_events.PoolEvents.checkout` events within the lifespan of a single :class:`_engine.Connection` object, if that :class:`_engine.Connection` is invalidated and re-established. :param conn: :class:`_engine.Connection` object. .. seealso:: :meth:`_events.PoolEvents.checkout` the lower-level pool checkout event for an individual DBAPI connection Nr. �rO r: r. r. r/ �engine_connect{ s z ConnectionEvents.engine_connect�Dict[str, Any])r: �optsr& c C s dS )a� Intercept when the :meth:`_engine.Connection.execution_options` method is called. This method is called after the new :class:`_engine.Connection` has been produced, with the newly updated execution options collection, but before the :class:`.Dialect` has acted upon any of those new options. Note that this method is not called when a new :class:`_engine.Connection` is produced which is inheriting execution options from its parent :class:`_engine.Engine`; to intercept this condition, use the :meth:`_events.ConnectionEvents.engine_connect` event. :param conn: The newly copied :class:`_engine.Connection` object :param opts: dictionary of options that were passed to the :meth:`_engine.Connection.execution_options` method. This dictionary may be modified in place to affect the ultimate options which take effect. .. versionadded:: 2.0 the ``opts`` dictionary may be modified in place. .. seealso:: :meth:`_events.ConnectionEvents.set_engine_execution_options` - event which is called when :meth:`_engine.Engine.execution_options` is called. Nr. )rO r: rZ r. r. r/ � set_connection_execution_options� s z1ConnectionEvents.set_connection_execution_optionsr )�enginerZ r& c C s dS )a� Intercept when the :meth:`_engine.Engine.execution_options` method is called. The :meth:`_engine.Engine.execution_options` method produces a shallow copy of the :class:`_engine.Engine` which stores the new options. That new :class:`_engine.Engine` is passed here. A particular application of this method is to add a :meth:`_events.ConnectionEvents.engine_connect` event handler to the given :class:`_engine.Engine` which will perform some per- :class:`_engine.Connection` task specific to these execution options. :param conn: The newly copied :class:`_engine.Engine` object :param opts: dictionary of options that were passed to the :meth:`_engine.Connection.execution_options` method. This dictionary may be modified in place to affect the ultimate options which take effect. .. versionadded:: 2.0 the ``opts`` dictionary may be modified in place. .. seealso:: :meth:`_events.ConnectionEvents.set_connection_execution_options` - event which is called when :meth:`_engine.Connection.execution_options` is called. Nr. )rO r\ rZ r. r. r/ � set_engine_execution_options� s z-ConnectionEvents.set_engine_execution_options)r\ r& c C s dS )a� Intercept when the :meth:`_engine.Engine.dispose` method is called. The :meth:`_engine.Engine.dispose` method instructs the engine to "dispose" of it's connection pool (e.g. :class:`_pool.Pool`), and replaces it with a new one. Disposing of the old pool has the effect that existing checked-in connections are closed. The new pool does not establish any new connections until it is first used. This event can be used to indicate that resources related to the :class:`_engine.Engine` should also be cleaned up, keeping in mind that the :class:`_engine.Engine` can still be used for new requests in which case it re-acquires connection resources. Nr. )rO r\ r. r. r/ �engine_disposed� s z ConnectionEvents.engine_disposedc C s dS )z\Intercept begin() events. :param conn: :class:`_engine.Connection` object Nr. rW r. r. r/ �begin� s zConnectionEvents.beginc C s dS )a� Intercept rollback() events, as initiated by a :class:`.Transaction`. Note that the :class:`_pool.Pool` also "auto-rolls back" a DBAPI connection upon checkin, if the ``reset_on_return`` flag is set to its default value of ``'rollback'``. To intercept this rollback, use the :meth:`_events.PoolEvents.reset` hook. :param conn: :class:`_engine.Connection` object .. seealso:: :meth:`_events.PoolEvents.reset` Nr. rW r. r. r/ �rollback s zConnectionEvents.rollbackc C s dS )a� Intercept commit() events, as initiated by a :class:`.Transaction`. Note that the :class:`_pool.Pool` may also "auto-commit" a DBAPI connection upon checkin, if the ``reset_on_return`` flag is set to the value ``'commit'``. To intercept this commit, use the :meth:`_events.PoolEvents.reset` hook. :param conn: :class:`_engine.Connection` object Nr. rW r. r. r/ �commit s zConnectionEvents.commit)r: �namer& c C s dS )z�Intercept savepoint() events. :param conn: :class:`_engine.Connection` object :param name: specified name used for the savepoint. Nr. )rO r: rb r. r. r/ � savepoint$ s zConnectionEvents.savepoint)r: rb rE r& c C s dS )z�Intercept rollback_savepoint() events. :param conn: :class:`_engine.Connection` object :param name: specified name used for the savepoint. :param context: not used Nr. �rO r: rb rE r. r. r/ �rollback_savepoint, s z#ConnectionEvents.rollback_savepointc C s dS )z�Intercept release_savepoint() events. :param conn: :class:`_engine.Connection` object :param name: specified name used for the savepoint. :param context: not used Nr. rd r. r. r/ �release_savepoint8 s z"ConnectionEvents.release_savepoint)r: �xidr& c C s dS )z�Intercept begin_twophase() events. :param conn: :class:`_engine.Connection` object :param xid: two-phase XID identifier Nr. �rO r: rg r. r. r/ �begin_twophaseD s z ConnectionEvents.begin_twophasec C s dS )z�Intercept prepare_twophase() events. :param conn: :class:`_engine.Connection` object :param xid: two-phase XID identifier Nr. rh r. r. r/ �prepare_twophaseL s z!ConnectionEvents.prepare_twophase)r: rg � is_preparedr& c C s dS )a Intercept rollback_twophase() events. :param conn: :class:`_engine.Connection` object :param xid: two-phase XID identifier :param is_prepared: boolean, indicates if :meth:`.TwoPhaseTransaction.prepare` was called. Nr. �rO r: rg rk r. r. r/ �rollback_twophaseS s z"ConnectionEvents.rollback_twophasec C s dS )z�Intercept commit_twophase() events. :param conn: :class:`_engine.Connection` object :param xid: two-phase XID identifier :param is_prepared: boolean, indicates if :meth:`.TwoPhaseTransaction.prepare` was called. Nr. rl r. r. r/ �commit_twophase_ s z ConnectionEvents.commit_twophase) �__name__� __module__� __qualname__�__doc__�_target_class_docr �_dispatch_target� classmethodr) rM r Z_legacy_signaturer7 rQ rA rS rX r[ r] r^ r_ r` ra rc re rf ri rj rm rn � __classcell__r. r. r, r/ r , sN S �<� .� 1�$&% r c @ s� e Zd ZdZdZeZedd�ddddd �d d ��Zed d dd�dd��Z ddd�dd�Z dddddd �d d �Z d d d d!d"d#�d$d%�Z d d d!d"d&�d'd(�Z d d d)d!d"d#�d*d+�Zd,d d d-d!dd.�d/d0�Zd1S )2� DialectEventsaY event interface for execution-replacement functions. These events allow direct instrumentation and replacement of key dialect functions which interact with the DBAPI. .. note:: :class:`.DialectEvents` hooks should be considered **semi-public** and experimental. These hooks are not for general use and are only for those situations where intricate re-statement of DBAPI mechanics must be injected onto an existing dialect. For general-use statement-interception events, please use the :class:`_events.ConnectionEvents` interface. .. seealso:: :meth:`_events.ConnectionEvents.before_cursor_execute` :meth:`_events.ConnectionEvents.before_execute` :meth:`_events.ConnectionEvents.after_cursor_execute` :meth:`_events.ConnectionEvents.after_execute` r! Fr0 zevent._EventKey[Dialect]r2 r r3 r4 c K s |j }d|_|�� d S )NT)rH rI rK )r+ r5 r1 r6 r$ r. r. r/ rM � s zDialectEvents._listenz3Union[Engine, Type[Engine], Dialect, Type[Dialect]]r" z'Optional[Union[Dialect, Type[Dialect]]]r# c C s� t |t�r(t|t�rtS t|t�r||S nTt |t�r8|jS t |t�rF|S t |t�rd|dkrdt�d��nt |d�rx|� � nd S d S )N� handle_errorz�The handle_error() event hook as of SQLAlchemy 2.0 is established on the Dialect, and may only be applied to the Engine as a whole or to a specific Dialect as a whole, not on a per-Connection basis.r' ) � isinstance�type� issubclassr r �dialectr r ZInvalidRequestErrorr* r' )r+ r$ r% r. r. r/ r) � s � zDialectEvents._accept_withr zOptional[BaseException])�exception_contextr& c C s dS )a� Intercept all exceptions processed by the :class:`_engine.Dialect`, typically but not limited to those emitted within the scope of a :class:`_engine.Connection`. .. versionchanged:: 2.0 the :meth:`.DialectEvents.handle_error` event is moved to the :class:`.DialectEvents` class, moved from the :class:`.ConnectionEvents` class, so that it may also participate in the "pre ping" operation configured with the :paramref:`_sa.create_engine.pool_pre_ping` parameter. The event remains registered by using the :class:`_engine.Engine` as the event target, however note that using the :class:`_engine.Connection` as an event target for :meth:`.DialectEvents.handle_error` is no longer supported. This includes all exceptions emitted by the DBAPI as well as within SQLAlchemy's statement invocation process, including encoding errors and other statement validation errors. Other areas in which the event is invoked include transaction begin and end, result row fetching, cursor creation. Note that :meth:`.handle_error` may support new kinds of exceptions and new calling scenarios at *any time*. Code which uses this event must expect new calling patterns to be present in minor releases. To support the wide variety of members that correspond to an exception, as well as to allow extensibility of the event without backwards incompatibility, the sole argument received is an instance of :class:`.ExceptionContext`. This object contains data members representing detail about the exception. Use cases supported by this hook include: * read-only, low-level exception handling for logging and debugging purposes * Establishing whether a DBAPI connection error message indicates that the database connection needs to be reconnected, including for the "pre_ping" handler used by **some** dialects * Establishing or disabling whether a connection or the owning connection pool is invalidated or expired in response to a specific exception * exception re-writing The hook is called while the cursor from the failed operation (if any) is still open and accessible. Special cleanup operations can be called on this cursor; SQLAlchemy will attempt to close this cursor subsequent to this hook being invoked. As of SQLAlchemy 2.0, the "pre_ping" handler enabled using the :paramref:`_sa.create_engine.pool_pre_ping` parameter will also participate in the :meth:`.handle_error` process, **for those dialects that rely upon disconnect codes to detect database liveness**. Note that some dialects such as psycopg, psycopg2, and most MySQL dialects make use of a native ``ping()`` method supplied by the DBAPI which does not make use of disconnect codes. .. versionchanged:: 2.0.0 The :meth:`.DialectEvents.handle_error` event hook participates in connection pool "pre-ping" operations. Within this usage, the :attr:`.ExceptionContext.engine` attribute will be ``None``, however the :class:`.Dialect` in use is always available via the :attr:`.ExceptionContext.dialect` attribute. .. versionchanged:: 2.0.5 Added :attr:`.ExceptionContext.is_pre_ping` attribute which will be set to ``True`` when the :meth:`.DialectEvents.handle_error` event hook is triggered within a connection pool pre-ping operation. .. versionchanged:: 2.0.5 An issue was repaired that allows for the PostgreSQL ``psycopg`` and ``psycopg2`` drivers, as well as all MySQL drivers, to properly participate in the :meth:`.DialectEvents.handle_error` event hook during connection pool "pre-ping" operations; previously, the implementation was non-working for these drivers. A handler function has two options for replacing the SQLAlchemy-constructed exception into one that is user defined. It can either raise this new exception directly, in which case all further event listeners are bypassed and the exception will be raised, after appropriate cleanup as taken place:: @event.listens_for(Engine, "handle_error") def handle_exception(context): if isinstance( context.original_exception, psycopg2.OperationalError ) and "failed" in str(context.original_exception): raise MySpecialException("failed operation") .. warning:: Because the :meth:`_events.DialectEvents.handle_error` event specifically provides for exceptions to be re-thrown as the ultimate exception raised by the failed statement, **stack traces will be misleading** if the user-defined event handler itself fails and throws an unexpected exception; the stack trace may not illustrate the actual code line that failed! It is advised to code carefully here and use logging and/or inline debugging if unexpected exceptions are occurring. Alternatively, a "chained" style of event handling can be used, by configuring the handler with the ``retval=True`` modifier and returning the new exception instance from the function. In this case, event handling will continue onto the next handler. The "chained" exception is available using :attr:`.ExceptionContext.chained_exception`:: @event.listens_for(Engine, "handle_error", retval=True) def handle_exception(context): if ( context.chained_exception is not None and "special" in context.chained_exception.message ): return MySpecialException( "failed", cause=context.chained_exception ) Handlers that return ``None`` may be used within the chain; when a handler returns ``None``, the previous exception instance, if any, is maintained as the current exception that is passed onto the next handler. When a custom exception is raised or returned, SQLAlchemy raises this new exception as-is, it is not wrapped by any SQLAlchemy object. If the exception is not a subclass of :class:`sqlalchemy.exc.StatementError`, certain features may not be available; currently this includes the ORM's feature of adding a detail hint about "autoflush" to exceptions raised within the autoflush process. :param context: an :class:`.ExceptionContext` object. See this class for details on all available members. .. seealso:: :ref:`pool_new_disconnect_codes` Nr. )rO r} r. r. r/ rx � s zDialectEvents.handle_errorr r zTuple[Any, ...]rY zOptional[DBAPIConnection])r| �conn_rec�cargs�cparamsr& c C s dS )a` Receive connection arguments before a connection is made. This event is useful in that it allows the handler to manipulate the cargs and/or cparams collections that control how the DBAPI ``connect()`` function will be called. ``cargs`` will always be a Python list that can be mutated in-place, and ``cparams`` a Python dictionary that may also be mutated:: e = create_engine("postgresql+psycopg2://user@host/dbname") @event.listens_for(e, "do_connect") def receive_do_connect(dialect, conn_rec, cargs, cparams): cparams["password"] = "some_password" The event hook may also be used to override the call to ``connect()`` entirely, by returning a non-``None`` DBAPI connection object:: e = create_engine("postgresql+psycopg2://user@host/dbname") @event.listens_for(e, "do_connect") def receive_do_connect(dialect, conn_rec, cargs, cparams): return psycopg2.connect(*cargs, **cparams) .. seealso:: :ref:`custom_dbapi_args` Nr. )rO r| r~ r r� r. r. r/ � do_connectA s zDialectEvents.do_connectr r r zOptional[Literal[True]])rB rC rD rE r& c C s dS )z�Receive a cursor to have executemany() called. Return the value True to halt further events from invoking, and to indicate that the cursor execution has already taken place within the event handler. Nr. �rO rB rC rD rE r. r. r/ �do_executemanyg s z DialectEvents.do_executemany)rB rC rE r& c C s dS )z�Receive a cursor to have execute() with no parameters called. Return the value True to halt further events from invoking, and to indicate that the cursor execution has already taken place within the event handler. Nr. )rO rB rC rE r. r. r/ �do_execute_no_paramsv s z"DialectEvents.do_execute_no_paramsr c C s dS )z�Receive a cursor to have execute() called. Return the value True to halt further events from invoking, and to indicate that the cursor execution has already taken place within the event handler. Nr. r� r. r. r/ � do_execute� s zDialectEvents.do_executez Dict[BindParameter[Any], Any]r )� inputsizesrB rC rD rE r& c C s dS )a� Receive the setinputsizes dictionary for possible modification. This event is emitted in the case where the dialect makes use of the DBAPI ``cursor.setinputsizes()`` method which passes information about parameter binding for a particular statement. The given ``inputsizes`` dictionary will contain :class:`.BindParameter` objects as keys, linked to DBAPI-specific type objects as values; for parameters that are not bound, they are added to the dictionary with ``None`` as the value, which means the parameter will not be included in the ultimate setinputsizes call. The event may be used to inspect and/or log the datatypes that are being bound, as well as to modify the dictionary in place. Parameters can be added, modified, or removed from this dictionary. Callers will typically want to inspect the :attr:`.BindParameter.type` attribute of the given bind objects in order to make decisions about the DBAPI object. After the event, the ``inputsizes`` dictionary is converted into an appropriate datastructure to be passed to ``cursor.setinputsizes``; either a list for a positional bound parameter execution style, or a dictionary of string parameter keys to DBAPI type objects for a named bound parameter execution style. The setinputsizes hook overall is only used for dialects which include the flag ``use_setinputsizes=True``. Dialects which use this include python-oracledb, cx_Oracle, pg8000, asyncpg, and pyodbc dialects. .. note:: For use with pyodbc, the ``use_setinputsizes`` flag must be passed to the dialect, e.g.:: create_engine("mssql+pyodbc://...", use_setinputsizes=True) .. seealso:: :ref:`mssql_pyodbc_setinputsizes` .. versionadded:: 1.2.9 .. seealso:: :ref:`cx_oracle_setinputsizes` Nr. )rO r� rB rC rD rE r. r. r/ �do_setinputsizes� s 5z DialectEvents.do_setinputsizesN)ro rp rq rr rs r rt ru rM r) rx r� r� r� r� r� r. r. r. r/ rw l s � & rw )*� __future__r �typingr r r r r r �baser r Z interfacesr r r r � r r Z util.typingr � TYPE_CHECKINGr r r r r r r r rP r �poolr Zsqlr Z sql.elementsr ZEventsr rw r. r. r. r/ �<module> sF D sqlalchemy/engine/__pycache__/base.cpython-39.pyc 0000644 00000275337 15125143220 0015742 0 ustar 00 a ��Jh�� � @ s� U d Z ddlmZ ddlZddlZddlZddlmZ ddlmZ ddlmZ ddlm Z ddlm Z dd lm Z dd lm Z dd lm Z dd lmZ dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddl m Z ddl m Z dd l m Z d d l m!Z! d d l m"Z" d d l m#Z# d d!l m Z d d"l$m%Z% d d!l$m Z& ej'�rdd#l m(Z( dd$l m)Z) dd%lm*Z* dd&lm+Z+ dd'lm,Z, dd(lm-Z- dd)lm.Z. dd*lm/Z/ dd+lm0Z0 dd,lm1Z1 dd-lm2Z2 dd.lm3Z3 dd/lm4Z4 dd0lm5Z5 dd1l6m7Z7 dd2l8m9Z9 d d3l:m;Z; d d4l#m<Z< d d5l=m>Z> d d6l=m?Z? d d7l=m@Z@ d d8l$mAZA d d9lBmCZC d d:lDmEZE d d;lFmGZG d d<lFmHZH d d=lImJZJ d d>lKmLZL d d?lKmMZM d d@lKmNZN d dAlOmPZP edBedC�ZQe jRZSdDeTdE< e jRZUdFeTdG< G dHdI� dIee"jVdJ �ZWG dKdL� dLe�ZXG dMdN� dNe �ZYG dOdP� dPeY�ZZG dQdR� dReY�Z[G dSdT� dTeZ�Z\G dUdV� dVee#j]e"jVdJ �Z^G dWdX� dXe#j]�Z_G dYdZ� dZe_e^�Z`e`e^_adS )[zBDefines :class:`_engine.Connection` and :class:`_engine.Engine`. � )� annotationsN)�Any)�Callable)�cast)�Iterable)�Iterator)�List)�Mapping)�NoReturn)�Optional)�overload)�Tuple)�Type)�TypeVar)�Union� )� BindTyping)�ConnectionEventsTarget)� DBAPICursor)�ExceptionContext)� ExecuteStyle)�ExecutionContext)�IsolationLevel)�_distill_params_20)�_distill_raw_params)�TransactionalContext� )�exc)� inspection)�log)�util)�compiler)� CursorResult)� ScalarResult)�_AnyExecuteParams)�_AnyMultiExecuteParams)�_CoreAnyExecuteParams)�_CoreMultiExecuteParams)�_CoreSingleExecuteParams)�_DBAPIAnyExecuteParams)�_DBAPISingleExecuteParams)�_ExecuteOptions)�CompiledCacheType)�CoreExecuteOptionsParameter)�Dialect)�SchemaTranslateMapType)� Inspector)�URL)� dispatcher)� _EchoFlagType)�_ConnectionFairy)�Pool)�PoolProxiedConnection)� Executable)� _InfoType)�Compiled)�ExecutableDDLElement)� InvokeDDLBase)�FunctionElement)�DefaultGenerator)� HasSchemaAttr)�SchemaVisitable)�TypedReturnsRows�_T)�boundr+ �_EMPTY_EXECUTION_OPTSzMapping[str, Any]� NO_OPTIONSc @ s& e Zd ZU dZded< ded< dZdZded < d Zd ed < d ed< ded< ded< d�dd dddd�dd�ZdZ ded< d ddd d �d d �Z d ddd d �d!d"�Z e d#d$�d%d&��Z d'd(d)�d*d+�Zd d$�d,d-�Zdddd d.�d/d0�Zed1d1d1d d d1d1d1d1d d2� d3d d4ddd5d5d5d#ddd d6� d7d8��Zedd d9�d:d8��Zdd d9�d;d8�Zd d$�d<d=�Ze dd$�d>d?��Ze dd$�d@dA��Ze dd$�dBdC��Ze dDd$�dEdF��Zd4d$�dGdH�Ze dId$�dJdK��ZdLd$�dMdN�ZdDd$�dOdP�Ze dQd$�dRdS��Z d�dTd dU�dVdW�Z d d$�dXdY�Z d d$�dZd[�Z d\d$�d]d^�Z d_d$�d`da�Z!d�dbdcdd�dedf�Z"d d$�dgdh�Z#d d$�didj�Z$dkd$�dldm�Z%d�ddd dn�dodp�Z&d�ddd dn�dqdr�Z'dd$�dsdt�Z(dd$�dudv�Z)dd$�dwdx�Z*d\d$�dydz�Z+d_d$�d{d|�Z,dd$�d}d~�Z-dd$�dd��Z.d\d d��d�d��Z/d d$�d�d��Z0d d$�d�d��Z1d�d(d d��d�d��Z2d d d��d�d��Z3d d d��d�d��Z4dcd d��d�d��Z5dd dd�d�d��Z6ddd d��d�d��Z7ddd d��d�d��Z8d d$�d�d��Z9ed�dd��d�d�d�d�d��d�d���Z:ed�dd��d�d�d�dd��d�d���Z:d�dd��d�d�d�dd��d�d��Z:ed�dd��d�d�d�d�d��d�d���Z;ed�dd��d�d�d�d�d��d�d���Z;d�dd��d�d�d�d�d��d�d��Z;e�d dd��d�d�d�d�d��d�d���Z<e�ddd��d�d�d�d�d��d�d���Z<�ddd��d�d�d�d�d��d�d��Z<d�d�d�d�d��d�d��Z=d�d�d�dd��d�d��Z>d�d�d�d�d��d�d��Z?dd�d d�dd�dĄZ@d�d�d�d�dŜd�dDŽZAeBfd�d�d�d�dɜd�d˄ZC�dd d�d�d�d��d�d΄ZDdd�d�d�d ddd�dҜd�dԄZEdd�d�d�d�d֜d�dZFdd�d�dٜd�dۄZG�dd�d d�d�d dߜd�d�ZHd�d d�d�d�ZId ZJd ZK�dd�d(d�d�d�ddLd�d�d�ZLeM�dd�dd�ddddLd�d�d��ZNd�d�dd d�d�d�ZOdS ( � Connectiona: Provides high-level functionality for a wrapped DB-API connection. The :class:`_engine.Connection` object is procured by calling the :meth:`_engine.Engine.connect` method of the :class:`_engine.Engine` object, and provides services for execution of SQL statements as well as transaction control. The Connection object is **not** thread-safe. While a Connection can be shared among threads using properly synchronized access, it is still possible that the underlying DBAPI connection may not support shared access between threads. Check the DBAPI documentation for details. The Connection object represents a single DBAPI connection checked out from the connection pool. In this state, the connection pool has no affect upon the connection, including its expiration or timeout state. For the connection pool to properly manage connections, connections should be returned to the connection pool (i.e. ``connection.close()``) whenever the connection is not in use. .. index:: single: thread safety; Connection r. �dialect�"dispatcher[ConnectionEventsTarget]�dispatchz sqlalchemy.engine.ConnectionNz Optional[TransactionalContext]�_trans_context_managerFz Optional[PoolProxiedConnection]�_dbapi_connectionr+ �_execution_optionszOptional[RootTransaction]� _transactionzOptional[NestedTransaction]�_nested_transactionT�EnginezOptional[bool]�bool)�engine� connection� _has_events�_allow_revalidate�_allow_autobeginc C s� || _ |j | _}|du rdz|�� | _W qj |jjy` } z t�|||� � W Y d}~qjd}~0 0 n|| _d | _| _ d| _ d| _ || _ || _ | j �� | _|du r�| j�|j�| _|p�|du o�|j| _|j| _| js�| j jr�| j�| � dS )zConstruct a new Connection.Nr F)rP rF �raw_connectionrJ � loaded_dbapi�ErrorrE �$_handle_dbapi_exception_noconnectionrL rM �_Connection__savepoint_seq�_Connection__in_begin�_Connection__can_reconnectrT �_should_log_info�_echorH �_joinrR rK Zengine_connect)�selfrP rQ rR rS rT rF �err� ra �K/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/engine/base.py�__init__� s2 � �zConnection.__init__r �_message_formatter�str�None)�message�arg�kw�returnc O sF | j }|r||�}tjr&dtj |d< | jjj|g|�R i |�� d S �Nr � stacklevel)rd r � STACKLEVEL�STACKLEVEL_OFFSETrP �logger�info�r_ rg rh ri �fmtra ra rb � _log_info� s zConnection._log_infoc O sF | j }|r||�}tjr&dtj |d< | jjj|g|�R i |�� d S rk )rd r rm rn rP ro �debugrq ra ra rb � _log_debug� s zConnection._log_debug� Optional[SchemaTranslateMapType]�rj c C s | j �dd �}|S )N�schema_translate_map)rK �get)r_ rx ra ra rb �_schema_translate_map� s �z Connection._schema_translate_mapr> � Optional[str])�objrj c C s6 |j }| j�dd�}|r.||v r.|jr.|| S |S dS )ztReturn the schema name for the given schema item taking into account current schema translate map. rx N)ZschemarK ry Z_use_schema_map)r_ r| �namerx ra ra rb �schema_for_object� s ����z Connection.schema_for_objectc C s | S �Nra �r_ ra ra rb � __enter__� s zConnection.__enter__)�type_�value� tracebackrj c C s | � � d S r )�close)r_ r� r� r� ra ra rb �__exit__� s zConnection.__exit__.) �compiled_cache� logging_token�isolation_level� no_parameters�stream_results�max_row_buffer� yield_per�insertmanyvalues_page_sizerx �preserve_rowcount�Optional[CompiledCacheType]r �int) r� r� r� r� r� r� r� r� rx r� �optrj c K s d S r ra ) r_ r� r� r� r� r� r� r� r� rx r� r� ra ra rb �execution_options� s z Connection.execution_options�r� rj c K s d S r ra �r_ r� ra ra rb r� � s c K s< | j s| jj r | j�| |� | j�|�| _| j�| |� | S )a�0 Set non-SQL options for the connection which take effect during execution. This method modifies this :class:`_engine.Connection` **in-place**; the return value is the same :class:`_engine.Connection` object upon which the method is called. Note that this is in contrast to the behavior of the ``execution_options`` methods on other objects such as :meth:`_engine.Engine.execution_options` and :meth:`_sql.Executable.execution_options`. The rationale is that many such execution options necessarily modify the state of the base DBAPI connection in any case so there is no feasible means of keeping the effect of such an option localized to a "sub" connection. .. versionchanged:: 2.0 The :meth:`_engine.Connection.execution_options` method, in contrast to other objects with this method, modifies the connection in-place without creating copy of it. As discussed elsewhere, the :meth:`_engine.Connection.execution_options` method accepts any arbitrary parameters including user defined names. All parameters given are consumable in a number of ways including by using the :meth:`_engine.Connection.get_execution_options` method. See the examples at :meth:`_sql.Executable.execution_options` and :meth:`_engine.Engine.execution_options`. The keywords that are currently recognized by SQLAlchemy itself include all those listed under :meth:`.Executable.execution_options`, as well as others that are specific to :class:`_engine.Connection`. :param compiled_cache: Available on: :class:`_engine.Connection`, :class:`_engine.Engine`. A dictionary where :class:`.Compiled` objects will be cached when the :class:`_engine.Connection` compiles a clause expression into a :class:`.Compiled` object. This dictionary will supersede the statement cache that may be configured on the :class:`_engine.Engine` itself. If set to None, caching is disabled, even if the engine has a configured cache size. Note that the ORM makes use of its own "compiled" caches for some operations, including flush operations. The caching used by the ORM internally supersedes a cache dictionary specified here. :param logging_token: Available on: :class:`_engine.Connection`, :class:`_engine.Engine`, :class:`_sql.Executable`. Adds the specified string token surrounded by brackets in log messages logged by the connection, i.e. the logging that's enabled either via the :paramref:`_sa.create_engine.echo` flag or via the ``logging.getLogger("sqlalchemy.engine")`` logger. This allows a per-connection or per-sub-engine token to be available which is useful for debugging concurrent connection scenarios. .. versionadded:: 1.4.0b2 .. seealso:: :ref:`dbengine_logging_tokens` - usage example :paramref:`_sa.create_engine.logging_name` - adds a name to the name used by the Python logger object itself. :param isolation_level: Available on: :class:`_engine.Connection`, :class:`_engine.Engine`. Set the transaction isolation level for the lifespan of this :class:`_engine.Connection` object. Valid values include those string values accepted by the :paramref:`_sa.create_engine.isolation_level` parameter passed to :func:`_sa.create_engine`. These levels are semi-database specific; see individual dialect documentation for valid levels. The isolation level option applies the isolation level by emitting statements on the DBAPI connection, and **necessarily affects the original Connection object overall**. The isolation level will remain at the given setting until explicitly changed, or when the DBAPI connection itself is :term:`released` to the connection pool, i.e. the :meth:`_engine.Connection.close` method is called, at which time an event handler will emit additional statements on the DBAPI connection in order to revert the isolation level change. .. note:: The ``isolation_level`` execution option may only be established before the :meth:`_engine.Connection.begin` method is called, as well as before any SQL statements are emitted which would otherwise trigger "autobegin", or directly after a call to :meth:`_engine.Connection.commit` or :meth:`_engine.Connection.rollback`. A database cannot change the isolation level on a transaction in progress. .. note:: The ``isolation_level`` execution option is implicitly reset if the :class:`_engine.Connection` is invalidated, e.g. via the :meth:`_engine.Connection.invalidate` method, or if a disconnection error occurs. The new connection produced after the invalidation will **not** have the selected isolation level re-applied to it automatically. .. seealso:: :ref:`dbapi_autocommit` :meth:`_engine.Connection.get_isolation_level` - view current actual level :param no_parameters: Available on: :class:`_engine.Connection`, :class:`_sql.Executable`. When ``True``, if the final parameter list or dictionary is totally empty, will invoke the statement on the cursor as ``cursor.execute(statement)``, not passing the parameter collection at all. Some DBAPIs such as psycopg2 and mysql-python consider percent signs as significant only when parameters are present; this option allows code to generate SQL containing percent signs (and possibly other characters) that is neutral regarding whether it's executed by the DBAPI or piped into a script that's later invoked by command line tools. :param stream_results: Available on: :class:`_engine.Connection`, :class:`_sql.Executable`. Indicate to the dialect that results should be "streamed" and not pre-buffered, if possible. For backends such as PostgreSQL, MySQL and MariaDB, this indicates the use of a "server side cursor" as opposed to a client side cursor. Other backends such as that of Oracle Database may already use server side cursors by default. The usage of :paramref:`_engine.Connection.execution_options.stream_results` is usually combined with setting a fixed number of rows to to be fetched in batches, to allow for efficient iteration of database rows while at the same time not loading all result rows into memory at once; this can be configured on a :class:`_engine.Result` object using the :meth:`_engine.Result.yield_per` method, after execution has returned a new :class:`_engine.Result`. If :meth:`_engine.Result.yield_per` is not used, the :paramref:`_engine.Connection.execution_options.stream_results` mode of operation will instead use a dynamically sized buffer which buffers sets of rows at a time, growing on each batch based on a fixed growth size up until a limit which may be configured using the :paramref:`_engine.Connection.execution_options.max_row_buffer` parameter. When using the ORM to fetch ORM mapped objects from a result, :meth:`_engine.Result.yield_per` should always be used with :paramref:`_engine.Connection.execution_options.stream_results`, so that the ORM does not fetch all rows into new ORM objects at once. For typical use, the :paramref:`_engine.Connection.execution_options.yield_per` execution option should be preferred, which sets up both :paramref:`_engine.Connection.execution_options.stream_results` and :meth:`_engine.Result.yield_per` at once. This option is supported both at a core level by :class:`_engine.Connection` as well as by the ORM :class:`_engine.Session`; the latter is described at :ref:`orm_queryguide_yield_per`. .. seealso:: :ref:`engine_stream_results` - background on :paramref:`_engine.Connection.execution_options.stream_results` :paramref:`_engine.Connection.execution_options.max_row_buffer` :paramref:`_engine.Connection.execution_options.yield_per` :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel` describing the ORM version of ``yield_per`` :param max_row_buffer: Available on: :class:`_engine.Connection`, :class:`_sql.Executable`. Sets a maximum buffer size to use when the :paramref:`_engine.Connection.execution_options.stream_results` execution option is used on a backend that supports server side cursors. The default value if not specified is 1000. .. seealso:: :paramref:`_engine.Connection.execution_options.stream_results` :ref:`engine_stream_results` :param yield_per: Available on: :class:`_engine.Connection`, :class:`_sql.Executable`. Integer value applied which will set the :paramref:`_engine.Connection.execution_options.stream_results` execution option and invoke :meth:`_engine.Result.yield_per` automatically at once. Allows equivalent functionality as is present when using this parameter with the ORM. .. versionadded:: 1.4.40 .. seealso:: :ref:`engine_stream_results` - background and examples on using server side cursors with Core. :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel` describing the ORM version of ``yield_per`` :param insertmanyvalues_page_size: Available on: :class:`_engine.Connection`, :class:`_engine.Engine`. Number of rows to format into an INSERT statement when the statement uses "insertmanyvalues" mode, which is a paged form of bulk insert that is used for many backends when using :term:`executemany` execution typically in conjunction with RETURNING. Defaults to 1000. May also be modified on a per-engine basis using the :paramref:`_sa.create_engine.insertmanyvalues_page_size` parameter. .. versionadded:: 2.0 .. seealso:: :ref:`engine_insertmanyvalues` :param schema_translate_map: Available on: :class:`_engine.Connection`, :class:`_engine.Engine`, :class:`_sql.Executable`. A dictionary mapping schema names to schema names, that will be applied to the :paramref:`_schema.Table.schema` element of each :class:`_schema.Table` encountered when SQL or DDL expression elements are compiled into strings; the resulting schema name will be converted based on presence in the map of the original name. .. seealso:: :ref:`schema_translating` :param preserve_rowcount: Boolean; when True, the ``cursor.rowcount`` attribute will be unconditionally memoized within the result and made available via the :attr:`.CursorResult.rowcount` attribute. Normally, this attribute is only preserved for UPDATE and DELETE statements. Using this option, the DBAPIs rowcount value can be accessed for other kinds of statements such as INSERT and SELECT, to the degree that the DBAPI supports these statements. See :attr:`.CursorResult.rowcount` for notes regarding the behavior of this attribute. .. versionadded:: 2.0.28 .. seealso:: :meth:`_engine.Engine.execution_options` :meth:`.Executable.execution_options` :meth:`_engine.Connection.get_execution_options` :ref:`orm_queryguide_execution_options` - documentation on all ORM-specific execution options )rR rP rH Z set_connection_execution_optionsrK �unionrF r� ra ra rb r� s c C s | j S )z�Get the non-SQL options which will take effect during execution. .. versionadded:: 1.3 .. seealso:: :meth:`_engine.Connection.execution_options` �rK r� ra ra rb �get_execution_options s z Connection.get_execution_optionsc C s | j }|d uo|jS r )rJ �is_valid�r_ �pool_proxied_connectionra ra rb �)_still_open_and_dbapi_connection_is_valid s �z4Connection._still_open_and_dbapi_connection_is_validc C s | j du o| j S )z)Return True if this connection is closed.N�rJ r[ r� ra ra rb �closed s zConnection.closedc C s | j }|du o| jS )z�Return True if this connection was invalidated. This does not indicate whether or not the connection was invalidated at the pool level, however Nr� r� ra ra rb � invalidated s zConnection.invalidatedr6 c C sr | j du rhz | �� W S tjtjfy0 � Y qn tyd } z | �|dddd� W Y d}~qnd}~0 0 n| j S dS )aV The underlying DB-API connection managed by this Connection. This is a SQLAlchemy connection-pool proxied connection which then has the attribute :attr:`_pool._ConnectionFairy.dbapi_connection` that refers to the actual driver connection. .. seealso:: :ref:`dbapi_connections` N)rJ �_revalidate_connectionr �PendingRollbackError�ResourceClosedError� BaseException�_handle_dbapi_exception�r_ �era ra rb rQ 5 s *zConnection.connectionc C s^ | j j}|dusJ �z| j�|�W S tyX } z | �|dddd� W Y d}~n d}~0 0 dS )a� Return the current **actual** isolation level that's present on the database within the scope of this connection. This attribute will perform a live SQL operation against the database in order to procure the current isolation level, so the value returned is the actual level on the underlying DBAPI connection regardless of how this state was set. This will be one of the four actual isolation modes ``READ UNCOMMITTED``, ``READ COMMITTED``, ``REPEATABLE READ``, ``SERIALIZABLE``. It will **not** include the ``AUTOCOMMIT`` isolation level setting. Third party dialects may also feature additional isolation level settings. .. note:: This method **will not report** on the ``AUTOCOMMIT`` isolation level, which is a separate :term:`dbapi` setting that's independent of **actual** isolation level. When ``AUTOCOMMIT`` is in use, the database connection still has a "traditional" isolation mode in effect, that is typically one of the four values ``READ UNCOMMITTED``, ``READ COMMITTED``, ``REPEATABLE READ``, ``SERIALIZABLE``. Compare to the :attr:`_engine.Connection.default_isolation_level` accessor which returns the isolation level that is present on the database at initial connection time. .. seealso:: :attr:`_engine.Connection.default_isolation_level` - view default level :paramref:`_sa.create_engine.isolation_level` - set per :class:`_engine.Engine` isolation level :paramref:`.Connection.execution_options.isolation_level` - set per :class:`_engine.Connection` isolation level N)rQ �dbapi_connectionrF �get_isolation_levelr� r� )r_ r� r� ra ra rb r� O s % z Connection.get_isolation_levelzOptional[IsolationLevel]c C s | j jS )a� The initial-connection time isolation level associated with the :class:`_engine.Dialect` in use. This value is independent of the :paramref:`.Connection.execution_options.isolation_level` and :paramref:`.Engine.execution_options.isolation_level` execution options, and is determined by the :class:`_engine.Dialect` when the first connection is created, by performing a SQL query against the database for the current isolation level before any additional commands have been emitted. Calling this accessor does not invoke any new SQL queries. .. seealso:: :meth:`_engine.Connection.get_isolation_level` - view current actual isolation level :paramref:`_sa.create_engine.isolation_level` - set per :class:`_engine.Engine` isolation level :paramref:`.Connection.execution_options.isolation_level` - set per :class:`_engine.Connection` isolation level )rF �default_isolation_levelr� ra ra rb r� { s z"Connection.default_isolation_levelr c C s$ t jd| jd urdnd dd��d S )NzfCan't reconnect until invalid %stransaction is rolled back. Please rollback() fully before proceedingz savepoint � Z8s2b)�code)r r� rM r� ra ra rb �_invalid_transaction� s ��z Connection._invalid_transactionc C s> | j r0| jr0| jd ur | �� | j�� | _| jS t�d��d S )N�This Connection is closed) r[ r� rL r� rP rU rJ r r� r� ra ra rb r� � s z!Connection._revalidate_connectionr8 c C s | j jS )a� Info dictionary associated with the underlying DBAPI connection referred to by this :class:`_engine.Connection`, allowing user-defined data to be associated with the connection. The data here will follow along with the DBAPI connection including after it is returned to the connection pool and used again in subsequent instances of :class:`_engine.Connection`. )rQ rp r� ra ra rb rp � s zConnection.infozOptional[BaseException])� exceptionrj c C sF | j r dS | jrt�d��| jr<| j}|dus2J �|�|� d| _dS )a� Invalidate the underlying DBAPI connection associated with this :class:`_engine.Connection`. An attempt will be made to close the underlying DBAPI connection immediately; however if this operation fails, the error is logged but not raised. The connection is then discarded whether or not close() succeeded. Upon the next use (where "use" typically means using the :meth:`_engine.Connection.execute` method or similar), this :class:`_engine.Connection` will attempt to procure a new DBAPI connection using the services of the :class:`_pool.Pool` as a source of connectivity (e.g. a "reconnection"). If a transaction was in progress (e.g. the :meth:`_engine.Connection.begin` method has been called) when :meth:`_engine.Connection.invalidate` method is called, at the DBAPI level all state associated with this transaction is lost, as the DBAPI connection is closed. The :class:`_engine.Connection` will not allow a reconnection to proceed until the :class:`.Transaction` object is ended, by calling the :meth:`.Transaction.rollback` method; until that point, any attempt at continuing to use the :class:`_engine.Connection` will raise an :class:`~sqlalchemy.exc.InvalidRequestError`. This is to prevent applications from accidentally continuing an ongoing transactional operations despite the fact that the transaction has been lost due to an invalidation. The :meth:`_engine.Connection.invalidate` method, just like auto-invalidation, will at the connection pool level invoke the :meth:`_events.PoolEvents.invalidate` event. :param exception: an optional ``Exception`` instance that's the reason for the invalidation. is passed along to event handlers and logging functions. .. seealso:: :ref:`pool_connection_invalidation` Nr� )r� r� r r� r� rJ � invalidate)r_ r� r� ra ra rb r� � s . zConnection.invalidatec C s4 | j rt�d��| j}|du r(t�d��|�� dS )a2 Detach the underlying DB-API connection from its connection pool. E.g.:: with engine.connect() as conn: conn.detach() conn.execute(text("SET search_path TO schema1, schema2")) # work with connection # connection is fully closed (since we used "with:", can # also call .close()) This :class:`_engine.Connection` instance will remain usable. When closed (or exited from a context manager context as above), the DB-API connection will be literally closed and not returned to its originating pool. This method can be used to insulate the rest of an application from a modified state on a connection (such as a transaction isolation level or similar). r� Nz&Can't detach an invalidated Connection)r� r r� rJ �InvalidRequestError�detachr� ra ra rb r� � s �zConnection.detachc C s | j r| js| �� d S r )rT rZ �beginr� ra ra rb � _autobegin s zConnection._autobegin�RootTransactionc C s( | j du rt| �| _ | j S t�d��dS )a� Begin a transaction prior to autobegin occurring. E.g.:: with engine.connect() as conn: with conn.begin() as trans: conn.execute(table.insert(), {"username": "sandy"}) The returned object is an instance of :class:`_engine.RootTransaction`. This object represents the "scope" of the transaction, which completes when either the :meth:`_engine.Transaction.rollback` or :meth:`_engine.Transaction.commit` method is called; the object also works as a context manager as illustrated above. The :meth:`_engine.Connection.begin` method begins a transaction that normally will be begun in any case when the connection is first used to execute a statement. The reason this method might be used would be to invoke the :meth:`_events.ConnectionEvents.begin` event at a specific time, or to organize code within the scope of a connection checkout in terms of context managed blocks, such as:: with engine.connect() as conn: with conn.begin(): conn.execute(...) conn.execute(...) with conn.begin(): conn.execute(...) conn.execute(...) The above code is not fundamentally any different in its behavior than the following code which does not use :meth:`_engine.Connection.begin`; the below style is known as "commit as you go" style:: with engine.connect() as conn: conn.execute(...) conn.execute(...) conn.commit() conn.execute(...) conn.execute(...) conn.commit() From a database point of view, the :meth:`_engine.Connection.begin` method does not emit any SQL or change the state of the underlying DBAPI connection in any way; the Python DBAPI does not have any concept of explicit transaction begin. .. seealso:: :ref:`tutorial_working_with_transactions` - in the :ref:`unified_tutorial` :meth:`_engine.Connection.begin_nested` - use a SAVEPOINT :meth:`_engine.Connection.begin_twophase` - use a two phase /XID transaction :meth:`_engine.Engine.begin` - context manager available from :class:`_engine.Engine` Nz�This connection has already initialized a SQLAlchemy Transaction() object via begin() or autobegin; can't call begin() here unless rollback() or commit() is called first.)rL r� r r� r� ra ra rb r� s @ �zConnection.begin�NestedTransactionc C s | j du r| �� t| �S )a� Begin a nested transaction (i.e. SAVEPOINT) and return a transaction handle that controls the scope of the SAVEPOINT. E.g.:: with engine.begin() as connection: with connection.begin_nested(): connection.execute(table.insert(), {"username": "sandy"}) The returned object is an instance of :class:`_engine.NestedTransaction`, which includes transactional methods :meth:`_engine.NestedTransaction.commit` and :meth:`_engine.NestedTransaction.rollback`; for a nested transaction, these methods correspond to the operations "RELEASE SAVEPOINT <name>" and "ROLLBACK TO SAVEPOINT <name>". The name of the savepoint is local to the :class:`_engine.NestedTransaction` object and is generated automatically. Like any other :class:`_engine.Transaction`, the :class:`_engine.NestedTransaction` may be used as a context manager as illustrated above which will "release" or "rollback" corresponding to if the operation within the block were successful or raised an exception. Nested transactions require SAVEPOINT support in the underlying database, else the behavior is undefined. SAVEPOINT is commonly used to run operations within a transaction that may fail, while continuing the outer transaction. E.g.:: from sqlalchemy import exc with engine.begin() as connection: trans = connection.begin_nested() try: connection.execute(table.insert(), {"username": "sandy"}) trans.commit() except exc.IntegrityError: # catch for duplicate username trans.rollback() # rollback to savepoint # outer transaction continues connection.execute(...) If :meth:`_engine.Connection.begin_nested` is called without first calling :meth:`_engine.Connection.begin` or :meth:`_engine.Engine.begin`, the :class:`_engine.Connection` object will "autobegin" the outer transaction first. This outer transaction may be committed using "commit-as-you-go" style, e.g.:: with engine.connect() as connection: # begin() wasn't called with connection.begin_nested(): # will auto-"begin()" first connection.execute(...) # savepoint is released connection.execute(...) # explicitly commit outer transaction connection.commit() # can continue working with connection here .. versionchanged:: 2.0 :meth:`_engine.Connection.begin_nested` will now participate in the connection "autobegin" behavior that is new as of 2.0 / "future" style connections in 1.4. .. seealso:: :meth:`_engine.Connection.begin` :ref:`session_begin_nested` - ORM support for SAVEPOINT N)rL r� r� r� ra ra rb � begin_nestedd s I zConnection.begin_nestedz Optional[Any]�TwoPhaseTransaction)�xidrj c C s2 | j durt�d��|du r(| jj�� }t| |�S )a' Begin a two-phase or XA transaction and return a transaction handle. The returned object is an instance of :class:`.TwoPhaseTransaction`, which in addition to the methods provided by :class:`.Transaction`, also provides a :meth:`~.TwoPhaseTransaction.prepare` method. :param xid: the two phase transaction id. If not supplied, a random id will be generated. .. seealso:: :meth:`_engine.Connection.begin` :meth:`_engine.Connection.begin_twophase` NzOCannot start a two phase transaction when a transaction is already in progress.)rL r r� rP rF Z create_xidr� )r_ r� ra ra rb �begin_twophase� s � zConnection.begin_twophasec C s | j r| j �� dS )a Commit the transaction that is currently in progress. This method commits the current transaction if one has been started. If no transaction was started, the method has no effect, assuming the connection is in a non-invalidated state. A transaction is begun on a :class:`_engine.Connection` automatically whenever a statement is first executed, or when the :meth:`_engine.Connection.begin` method is called. .. note:: The :meth:`_engine.Connection.commit` method only acts upon the primary database transaction that is linked to the :class:`_engine.Connection` object. It does not operate upon a SAVEPOINT that would have been invoked from the :meth:`_engine.Connection.begin_nested` method; for control of a SAVEPOINT, call :meth:`_engine.NestedTransaction.commit` on the :class:`_engine.NestedTransaction` that is returned by the :meth:`_engine.Connection.begin_nested` method itself. N)rL �commitr� ra ra rb r� � s zConnection.commitc C s | j r| j �� dS )aY Roll back the transaction that is currently in progress. This method rolls back the current transaction if one has been started. If no transaction was started, the method has no effect. If a transaction was started and the connection is in an invalidated state, the transaction is cleared using this method. A transaction is begun on a :class:`_engine.Connection` automatically whenever a statement is first executed, or when the :meth:`_engine.Connection.begin` method is called. .. note:: The :meth:`_engine.Connection.rollback` method only acts upon the primary database transaction that is linked to the :class:`_engine.Connection` object. It does not operate upon a SAVEPOINT that would have been invoked from the :meth:`_engine.Connection.begin_nested` method; for control of a SAVEPOINT, call :meth:`_engine.NestedTransaction.rollback` on the :class:`_engine.NestedTransaction` that is returned by the :meth:`_engine.Connection.begin_nested` method itself. N)rL �rollbackr� ra ra rb r� � s zConnection.rollbackz List[Any]c C s | j j�| �S r )rP rF Zdo_recover_twophaser� ra ra rb �recover_twophase s zConnection.recover_twophase)r� �recoverrj c C s | j jj| ||d� d S �N)r� )rP rF �do_rollback_twophase�r_ r� r� ra ra rb �rollback_prepared s z Connection.rollback_preparedc C s | j jj| ||d� d S r� )rP rF �do_commit_twophaser� ra ra rb �commit_prepared s zConnection.commit_preparedc C s | j duo| j jS �z,Return True if a transaction is in progress.N)rL � is_activer� ra ra rb �in_transaction s zConnection.in_transactionc C s | j duo| j jS r� )rM r� r� ra ra rb �in_nested_transaction s �z Connection.in_nested_transactionc C s0 | j �dd �}t|dkp,|d u o,| jjjdk�S )Nr� Z AUTOCOMMIT)rK ry rO rP rF Z_on_connect_isolation_level)r_ Zopt_isora ra rb �_is_autocommit_isolation s ��z#Connection._is_autocommit_isolationc C s | j }|d u rt�d��|S )Nz"connection is not in a transaction)rL r r� �r_ Ztransra ra rb �_get_required_transaction! s z$Connection._get_required_transactionc C s | j }|d u rt�d��|S )Nz)connection is not in a nested transaction)rM r r� r� ra ra rb � _get_required_nested_transaction' s �z+Connection._get_required_nested_transactionc C s | j S )zaReturn the current root transaction in progress, if any. .. versionadded:: 1.4 )rL r� ra ra rb �get_transaction/ s zConnection.get_transactionc C s | j S )zcReturn the current nested transaction in progress, if any. .. versionadded:: 1.4 )rM r� ra ra rb �get_nested_transaction8 s z!Connection.get_nested_transaction)� transactionrj c C s� | j r$| �� r| �d� n | �d� d| _| js8| jjrD| j�| � zVz| jj� | j � W n6 t y� } z | � |d d d d � W Y d }~n d }~0 0 W d| _nd| _0 d S )Nz?BEGIN (implicit; DBAPI should not BEGIN due to autocommit mode)zBEGIN (implicit)TF) r] r� rs rZ rR rP rH r� rF Zdo_beginrQ r� r� �r_ r� r� ra ra rb � _begin_impl@ s � *zConnection._begin_implc C s� | j s| jj r| j�| � | jr�| jrD| �� r:| �d� n | �d� z| jj� | j � W n6 t y� } z | � |d d d d � W Y d }~n d }~0 0 d S )NzVROLLBACK using DBAPI connection.rollback(), DBAPI should ignore due to autocommit modeZROLLBACK) rR rP rH r� r� r] r� rs rF Z do_rollbackrQ r� r� r� ra ra rb �_rollback_implV s � zConnection._rollback_implc C s� | j s| jj r| j�| � | jr>| �� r4| �d� n | �d� z| jj�| j � W n6 t y� } z | � |d d d d � W Y d }~n d }~0 0 d S )NzRCOMMIT using DBAPI connection.commit(), DBAPI should ignore due to autocommit modeZCOMMIT) rR rP rH r� r] r� rs rF Z do_commitrQ r� r� r� ra ra rb � _commit_implh s � zConnection._commit_impl)r} rj c C sP | j s| jj r | j�| |� |d u r<| jd7 _d| j }| jj�| |� |S )Nr zsa_savepoint_%s)rR rP rH Z savepointrY rF Z do_savepoint�r_ r} ra ra rb �_savepoint_imply s zConnection._savepoint_implc C s8 | j s| jj r | j�| |d � | jr4| jj�| |� d S r )rR rP rH Zrollback_savepointr� rF Zdo_rollback_to_savepointr� ra ra rb �_rollback_to_savepoint_impl� s z&Connection._rollback_to_savepoint_implc C s2 | j s| jj r | j�| |d � | jj�| |� d S r )rR rP rH Zrelease_savepointrF Zdo_release_savepointr� ra ra rb �_release_savepoint_impl� s z"Connection._release_savepoint_implc C s� | j r| �d� | js | jjr.| j�| |j� d| _zXz| jj� | |j� W n6 t y� } z | � |d d d d � W Y d }~n d }~0 0 W d| _nd| _0 d S )NzBEGIN TWOPHASE (implicit)TF) r] rs rR rP rH r� r� rZ rF Zdo_begin_twophaser� r� r� ra ra rb �_begin_twophase_impl� s *z Connection._begin_twophase_implc C s| | j s| jj r | j�| |� t| jt�s,J �z| jj�| |� W n6 t yv } z | � |d d d d � W Y d }~n d }~0 0 d S r ) rR rP rH Zprepare_twophase� isinstancerL r� rF Zdo_prepare_twophaser� r� )r_ r� r� ra ra rb �_prepare_twophase_impl� s z!Connection._prepare_twophase_impl)r� � is_preparedrj c C s� | j s| jj r | j�| ||� | jr�t| jt�s4J �z| jj� | ||� W n6 t y� } z | � |d d d d � W Y d }~n d }~0 0 d S r ) rR rP rH Zrollback_twophaser� r� rL r� rF r� r� r� �r_ r� r� r� ra ra rb �_rollback_twophase_impl� s �z"Connection._rollback_twophase_implc C s� | j s| jj r | j�| ||� t| jt�s.J �z| jj�| ||� W n6 t yz } z | � |d d d d � W Y d }~n d }~0 0 d S r ) rR rP rH Zcommit_twophaser� rL r� rF r� r� r� r� ra ra rb �_commit_twophase_impl� s z Connection._commit_twophase_implc C sZ | j r| j �� d}nd}| jdurP| j}|rBtd|�jdd� n|�� d| _d| _dS )a� Close this :class:`_engine.Connection`. This results in a release of the underlying database resources, that is, the DBAPI connection referenced internally. The DBAPI connection is typically restored back to the connection-holding :class:`_pool.Pool` referenced by the :class:`_engine.Engine` that produced this :class:`_engine.Connection`. Any transactional state present on the DBAPI connection is also unconditionally released via the DBAPI connection's ``rollback()`` method, regardless of any :class:`.Transaction` object that may be outstanding with regards to this :class:`_engine.Connection`. This has the effect of also calling :meth:`_engine.Connection.rollback` if any transaction is in place. After :meth:`_engine.Connection.close` is called, the :class:`_engine.Connection` is permanently in a closed state, and will allow no further operations. TFNr4 )Ztransaction_reset)rL r� rJ r Z_close_specialr[ )r_ Z skip_reset�connra ra rb r� � s �zConnection.close�r� zTypedReturnsRows[Tuple[_T]]z"Optional[_CoreSingleExecuteParams]z%Optional[CoreExecuteOptionsParameter]z Optional[_T])� statement� parametersr� rj c C s d S r ra �r_ r� r� r� ra ra rb �scalar� s zConnection.scalarr7 c C s d S r ra r� ra ra rb r� � s c C sX t |�}z |j}W n0 tyB } zt�|�|�W Y d}~nd}~0 0 || ||pPt�S dS )au Executes a SQL statement construct and returns a scalar object. This method is shorthand for invoking the :meth:`_engine.Result.scalar` method after invoking the :meth:`_engine.Connection.execute` method. Parameters are equivalent. :return: a scalar Python value representing the first column of the first row returned. N)r Z_execute_on_scalar�AttributeErrorr �ObjectNotExecutableErrorrD �r_ r� r� r� �distilled_parameters�methr` ra ra rb r� s "�z Optional[_CoreAnyExecuteParams]zScalarResult[_T]c C s d S r ra r� ra ra rb �scalars s zConnection.scalarszScalarResult[Any]c C s d S r ra r� ra ra rb r� ' s c C s | j |||d��� S )a� Executes and returns a scalar result set, which yields scalar values from the first column of each row. This method is equivalent to calling :meth:`_engine.Connection.execute` to receive a :class:`_result.Result` object, then invoking the :meth:`_result.Result.scalars` method to produce a :class:`_result.ScalarResult` instance. :return: a :class:`_result.ScalarResult` .. versionadded:: 1.4.24 r� )�executer� r� ra ra rb r� 0 s �zTypedReturnsRows[_T]zCursorResult[_T]c C s d S r ra r� ra ra rb r� I s zConnection.executezCursorResult[Any]c C s d S r ra r� ra ra rb r� R s c C sX t |�}z |j}W n0 tyB } zt�|�|�W Y d}~nd}~0 0 || ||pPt�S dS )a� Executes a SQL statement construct and returns a :class:`_engine.CursorResult`. :param statement: The statement to be executed. This is always an object that is in both the :class:`_expression.ClauseElement` and :class:`_expression.Executable` hierarchies, including: * :class:`_expression.Select` * :class:`_expression.Insert`, :class:`_expression.Update`, :class:`_expression.Delete` * :class:`_expression.TextClause` and :class:`_expression.TextualSelect` * :class:`_schema.DDL` and objects which inherit from :class:`_schema.ExecutableDDLElement` :param parameters: parameters which will be bound into the statement. This may be either a dictionary of parameter names to values, or a mutable sequence (e.g. a list) of dictionaries. When a list of dictionaries is passed, the underlying statement execution will make use of the DBAPI ``cursor.executemany()`` method. When a single dictionary is passed, the DBAPI ``cursor.execute()`` method will be used. :param execution_options: optional dictionary of execution options, which will be associated with the statement execution. This dictionary can provide a subset of the options that are accepted by :meth:`_engine.Connection.execution_options`. :return: a :class:`_engine.Result` object. N)r Z_execute_on_connectionr� r r� rD r� ra ra rb r� [ s & "�zFunctionElement[Any]r' r- )�funcr� r� rj c C s | � |�� ||�S )z%Execute a sql.FunctionElement object.)�_execute_clauseelement�select)r_ r� r� r� ra ra rb �_execute_function� s �z Connection._execute_functionr= )�defaultr� r� rj c C s� | j �|�}| js| jjr2| �|||�\}}}}nd }}z2| j}|du rR| �� }| j}|j� || ||�}W nP t j t j fy� � Y n6 t y� } z | �| dddd� W Y d} ~ n d} ~ 0 0 |�d|d�} | js�| jjr�| j�| ||||| � | S )z&Execute a schema.ColumnDefault object.N)rK � merge_withrR rP �_invoke_before_exec_eventrJ r� rF �execution_ctx_clsZ _init_defaultr r� r� r� r� Z _exec_defaultrH � after_execute) r_ r� r� r� �event_multiparams� event_paramsr� rF �ctxr� �retra ra rb �_execute_default� sJ � ��� �(� zConnection._execute_defaultr: )�ddlr� r� rj c C s� |j �| j |�}| js | jjr6| �|||�\}}}}nd }}|�dd�}| j}|j||d�} | �||j j | d|| �} | js�| jjr�| j � | ||||| � | S )z Execute a schema.DDL object.Nrx )rF rx ) rK r� rR rP r� ry rF �compile�_execute_contextr� Z _init_ddlrH r� ) r_ r� r� r� Z exec_optsr� r� rx rF �compiledr� ra ra rb � _execute_ddl� sJ ���� ���zConnection._execute_ddlzVTuple[Any, _CoreMultiExecuteParams, _CoreMultiExecuteParams, _CoreSingleExecuteParams])�elem�distilled_paramsr� rj c C s� t |�dkr g |d }}n |i }}| jjD ]}|| ||||�\}}}q.|rft|�}|rvt�d��n|rr|g}ng }||||fS )Nr r zLEvent handler can't return non-empty multiparams and params at the same time)�lenrH Zbefore_execute�listr r� )r_ r� r� r� r� r� �fnra ra rb r� s* � �z$Connection._invoke_before_exec_event)r� r� r� rj c C s� |j �| j |�}| jp | jj}|r8| �|||�\}}}}|rVt|d �}t|�dk}ng }d}| j} |�dd�} |�d| jj �} |j | | ||| | jj t j B d�\} } }| j| | jj| ||| ||| |d� }|r�| j�| |||||� |S ) z#Execute a sql.ClauseElement object.r r Frx Nr� )rF r� Z column_keys�for_executemanyrx Zlinting)� cache_hit)rK r� rR rP r� �sortedr rF ry �_compiled_cacheZ_compile_w_cacheZcompiler_lintingr! Z WARN_LINTINGr� r� �_init_compiledrH r� )r_ r� r� r� Z has_eventsr� r� �keysr rF rx r� Z compiled_sqlZextracted_paramsr r� ra ra rb r� 3 sn ��� �� � � �z!Connection._execute_clauseelementr9 )r� r� r� rj c C s� |j �| j|�}| js | jjr4| �|||�\}}}}| j}| �||jj |||||dd� }| jsf| jjr|| j � | |||||� |S )ziExecute a sql.Compiled object. TODO: why do we have this? likely deprecate or remove N) r� r� rK rR rP r� rF r� r� r rH r� )r_ r� r� r� r� r� rF r� ra ra rb �_execute_compiled| sD ���� �z Connection._execute_compiled� Optional[_DBAPIAnyExecuteParams]c C s8 t |�}| j�|�}| j}| �||jj|d|||�}|S )aL Executes a string SQL statement on the DBAPI cursor directly, without any SQL compilation steps. This can be used to pass any string directly to the ``cursor.execute()`` method of the DBAPI in use. :param statement: The statement str to be executed. Bound parameters must use the underlying DBAPI's paramstyle, such as "qmark", "pyformat", "format", etc. :param parameters: represent bound parameter values to be used in the execution. The format is one of: a dictionary of named parameters, a tuple of positional parameters, or a list containing either dictionaries or tuples for multiple-execute support. :return: a :class:`_engine.CursorResult`. E.g. multiple dictionaries:: conn.exec_driver_sql( "INSERT INTO table (id, value) VALUES (%(id)s, %(value)s)", [{"id": 1, "value": "v1"}, {"id": 2, "value": "v2"}], ) Single dictionary:: conn.exec_driver_sql( "INSERT INTO table (id, value) VALUES (%(id)s, %(value)s)", dict(id=1, value="v1"), ) Single tuple:: conn.exec_driver_sql( "INSERT INTO table (id, value) VALUES (?, ?)", (1, "v1") ) .. note:: The :meth:`_engine.Connection.exec_driver_sql` method does not participate in the :meth:`_events.ConnectionEvents.before_execute` and :meth:`_events.ConnectionEvents.after_execute` events. To intercept calls to :meth:`_engine.Connection.exec_driver_sql`, use :meth:`_events.ConnectionEvents.before_cursor_execute` and :meth:`_events.ConnectionEvents.after_cursor_execute`. .. seealso:: :pep:`249` N)r rK r� rF r� r� Z_init_statement)r_ r� r� r� r� rF r� ra ra rb �exec_driver_sql� s :�� zConnection.exec_driver_sqlz Callable[..., ExecutionContext]zUnion[str, Compiled]z Optional[_AnyMultiExecuteParams])rF � constructorr� r� r� �argsri rj c O s. |r$|� dd�}|r$|�d|d��}z6| j} | du r<| �� } ||| | |g|�R i |��} W nT tjtjfyv � Y n: ty� } z"| �| t |�|dd� W Y d} ~ n d} ~ 0 0 | j r�| j j r�| j r�| j j s�| � � n| jr�t�| � | j du r�| �� | �� | jtju �r| �|| �S | �|| ||�S dS )zdCreate an :class:`.ExecutionContext` and execute, returning a :class:`_engine.CursorResult`.r� NT)r� r� )ry r� rJ r� r r� r� r� r� re rL r� rM r� rI r �_trans_ctx_checkr� Zpre_exec� execute_styler ZINSERTMANYVALUES�_exec_insertmany_context�_exec_single_context) r_ rF r r� r� r� r ri Zypr� �contextr� ra ra rb r� � sT ���� ����� �zConnection._execute_contextr )rF r r� r� rj c C s� |j tju rh|�� }|rhz|�|j||� W n: tyf } z"| �|t|�|d|� W Y d}~n d}~0 0 |j|j |j }}}|j s�|d } n|} | j s�| j j r�| jjD ] } | | ||| ||j �\}} q�| j�r| �|� |�� } | j j�s| �d| tj| d|j d�� n | �d| � d} �zX|jtju �r�td| �} | jj �rj| jjjD ] } | ||| |��rHd } �qj�qH| �s6| j�||| |� n�| �s�|j �r�| jj �r�| jjj D ] } | |||��r�d } �qƐq�| �s6| j� |||� nXtd | �} | jj �r | jjj D ] } | ||| |��r�d } �q �q�| �s6| j� ||| |� | j �sH| j j �r`| j� | ||| ||j � |� � |�!� } W n8 t�y� } z | �||| ||� W Y d}~n d}~0 0 | S ) zzcontinue the _execute_context() method for a single DBAPI cursor.execute() or cursor.executemany() call. Nr �[%s] %r� �Zbatches�ismulti�8[%s] [SQL parameters hidden due to hide_parameters=True]Fr' Tr( )"� bind_typingr � SETINPUTSIZES�_prepare_set_input_sizes�do_set_input_sizes�cursorr� r� re r� r� � executemanyrR rP rH �before_cursor_executer] rs �_get_cache_stats�hide_parameters�sql_util� _repr_paramsr r Z EXECUTEMANYr rF Zdo_executemanyr� Zdo_execute_no_params� do_execute�after_cursor_execute� post_exec�_setup_result_proxy)r_ rF r r� r� �generic_setinputsizesr� r � str_statement�effective_parametersr �statsZ evt_handled�resultra ra rb r 6 s� ��� � �� �� � � �� � �� �z Connection._exec_single_context)rF r rj c C s� |j tju r|�� }nd}|j|j|j }}}|}| jp@| jj}| j jrV| j j j } nd} | j rl|� � d } |j�dd�} d} |�| |||||�D �]�} | jr�z|�|j| j|� W nD ty� } z,| j|t�| j�| jd|dd� W Y d}~n d}~0 0 | j}| j}|�r2| j jD ] }|| ||||d�\}}�q| j �r�| �t�|�� d | j� d | j � d | j �rhd nd � | j �rxdnd� d�}| jdk�r�| |7 } n d|� �} | jj �s�| �d| tj |ddd�� n | �d| � z6| D ] }|||||��r� �q�q�|� ||||� W nB t�yL } z(| j|t�|�|||dd� W Y d}~n d}~0 0 |�rl| j �!| |||||j"� | r�| | j#7 } q�z |�$� | �r�| |_%|�&� }W n8 t�y� } z | �|||||� W Y d}~n d}~0 0 |S )z�continue the _execute_context() method for an "insertmanyvalues" operation, which will invoke DBAPI cursor.execute() one or more times with individual log and event hook calls. Nra z (insertmanyvalues)r� Fr T)� is_sub_exec� �/z (Zordered� unorderedz; batch not supportedr� �)r Zinsertmanyvaluesr r r r )'r r r r r r� r� rR rP rF rH r# r] r r� ry Z!_deliver_insertmanyvalues_batchesZprocessed_setinputsizesr r� r� r! Z_long_statementZreplaced_statementZreplaced_parametersr rs ZbatchnumZ total_batchesZ rows_sortedZ is_downgradedr r" r$ r Zcurrent_batch_sizer% Z _rowcountr& )r_ rF r r' r r( r� r) Z engine_eventsZdo_execute_dispatchr* r� ZrowcountZ imv_batchr� Zsub_stmtZ sub_paramsr Z imv_statsr+ ra ra rb r � s � � �� � � � ����� �� �� �� � �z#Connection._exec_insertmany_contextr r* �Optional[ExecutionContext])r r� r� r rj c C s� | j s| jj r2| jjD ]}|| ||||d�\}}q| jrN| �|� | �d|� zD| jj s\dn| jjjD ]}|||||�rf q�qf| j�||||� W n6 ty� } z | � |||||� W Y d}~n d}~0 0 | j s�| jj r�| j� | ||||d� dS )a_ Execute a statement + params on the given cursor. Adds appropriate logging and exception handling. This method is used by DefaultDialect for special-case executions, such as for sequences and column defaults. The path of statement execution in the majority of cases terminates at _execute_context(). Fz [raw sql] %rra N) rR rP rH r r] rs rF r# r� r� r$ )r_ r r� r� r r r� ra ra rb �_cursor_executeo s0 � �� � �zConnection._cursor_execute)r rj c C s8 z |� � W n& ty2 | jjjjddd� Y n0 dS )z\Close the given cursor, catching exceptions and turning into log warnings. zError closing cursorT)�exc_infoN)r� � ExceptionrP �poolro �error)r_ r ra ra rb �_safe_close_cursor� s �z Connection._safe_close_cursorr� zOptional[_AnyExecuteParams]�Optional[DBAPICursor])r� r� r� r r r, rj c C s: t �� }t�|�}| jsZt|| jjj�rL| j rL| j� || j sD| j nd |�pV|oV| j | _| } |d urt| ov|j nd} | jr�tjj|||| jjj| jj| j| d��|d �|�d| _�z.t|| jjj�p�|d uo�|d u o�| } | �rtjj||tt|�| jjj| jj| j| j| d�} nd } d } | jj�r�| j�dd��s�t|| | j| j| ||||| j| d� }| jjj D ]b}z ||�}|d u�r�| |_ } W n: t�y� } z |} W Y d }~ �q�W Y d }~n d }~0 0 �qh| j|j k�r�|j | _| �r�|j | _ |j } | �r |�r |� |� | j�s6|�r$| �!|� | �"� �s6| �#� | �rN| �|d �|�nJ| �rt| d u�sbJ �| �|d �|�n$|d d u�s�J �|d �|d ��W | `| j�r6| `| j �s6| j }|d u�s�J �| �r�| jj$�%||� | �&|� nN| `| j�r4| `| j �s4| j }|d u�sJ �| �r*| jj$�%||� | �&|� 0 d S )NF)r rF r r T)r �connection_invalidatedrF r Zskip_user_error_eventsr )'�sysr3 r �is_exit_exception�_is_disconnectr� rF rV rW r� � is_disconnectr� rJ r �_reentrant_errorr � DBAPIError�instancerP r �with_tracebackr r4 rR rK ry �ExceptionContextImplrH � handle_error�chained_exceptionr9 � invalidate_pool_on_disconnectZhandle_dbapi_exceptionr7 r� r� r5 Z _invalidater� )r_ r� r� r� r r r, r3 r; rE r � should_wrap�sqlalchemy_exception�newraiser� r �per_fn�_raisedZdbapi_conn_wrapperra ra rb r� � s� ��� � ����� ��� �� *�� �z"Connection._handle_dbapi_exception�Optional[Engine])r� rF rP r= rE � is_pre_pingrj c C s� t �� }|d u r,t||jj�o*|�|d d �}t||jj�}|rrtjjd d t t |�|jj|d urd|j nd||d�} nd } d } |j �r"t || ||d d d d d |||� } |jjD ]^} z | | �} | d ur�| | _} W q� t �y } z |} W Y d }~ �qW Y d }~q�d }~0 0 q�| �r"|| jk�r"| j| _| �r:| �|d �|�nJ|�r`| d u�sNJ �| �|d �|�n$|d d u�srJ �|d �|d ��d S )NF)r r9 rF r r )r: r3 r� rV rW r= r r? r@ r r4 r rR rB rH rC rD r9 rA )�clsr� rF rP r= rE rL r3 rF rG rH r� r rI rJ ra ra rb rX > sh � �� � (z/Connection._handle_dbapi_exception_noconnection�Type[InvokeDDLBase]r? ��visitorcallable�element�kwargsrj c K s |f | j | d�|���|� dS )z�run a DDL visitor. This method is only here so that the MockConnection can change the options given to the visitor so that "checkfirst" is skipped. )rF rQ N)rF Ztraverse_single)r_ rP rQ rR ra ra rb �_run_ddl_visitor� s ���zConnection._run_ddl_visitor)NNTT)N)N)F)F)N)N)N)N)N)N)N)N)N)N)NN)N)F)NNTF)P�__name__� __module__� __qualname__�__doc__�__annotations__�_sqla_logger_namespacerI Zshould_close_with_resultrc rd rs ru �propertyrz r~ r� r� r r� r� r� r� r� rQ r� r� r� r� rp r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� rC r r r� r r r2 r7 r> r< r� � classmethodrX rS ra ra ra rb rE V s: �/ �* , ;$KN 0 �� �� �� �� �� ������ ��2 ;5*M�5 �M ; 1�. � � JrE r0 c @ s8 e Zd ZdZdZddddddd d d d d d d � dd�ZdS )rB z3Implement the :class:`.ExceptionContext` interface.) rQ rP rF r r� r� �original_exceptionrG rD �execution_contextr= rE rL r� z Optional[exc.StatementError]rK r. �Optional[Connection]r8 r{ r r1 rO ) r� rG rP rF rQ r r� r� r r= rE rL c C sF || _ || _|| _|| _|| _| | _|| _|| _| | _| | _ | | _ d S r ) rP rF rQ rG r\ r] r� r� r= rE rL ) r_ r� rG rP rF rQ r r� r� r r= rE rL ra ra rb rc � s z ExceptionContextImpl.__init__N)rT rU rV rW � __slots__rc ra ra ra rb rB � s rB c @ s� e Zd ZU dZdZdZded< ded< ded< dd �d d �Zedd �d d��Z dd �dd�Z dd �dd�Z dd �dd�Z edd �dd��Z dd �dd�Zdd �dd�Zdd �d d �Zdd �d d �Zdd �d d!�Zdd �d"d#�Zdd �d$d%�Zd&S )'� Transactiona~ Represent a database transaction in progress. The :class:`.Transaction` object is procured by calling the :meth:`_engine.Connection.begin` method of :class:`_engine.Connection`:: from sqlalchemy import create_engine engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test") connection = engine.connect() trans = connection.begin() connection.execute(text("insert into x (a, b) values (1, 2)")) trans.commit() The object provides :meth:`.rollback` and :meth:`.commit` methods in order to control transaction boundaries. It also implements a context manager interface so that the Python ``with`` statement can be used with the :meth:`_engine.Connection.begin` method:: with connection.begin(): connection.execute(text("insert into x (a, b) values (1, 2)")) The Transaction object is **not** threadsafe. .. seealso:: :meth:`_engine.Connection.begin` :meth:`_engine.Connection.begin_twophase` :meth:`_engine.Connection.begin_nested` .. index:: single: thread safety; Transaction ra FrO �_is_rootr� rE rQ �rQ c C s t � �d S r ��NotImplementedError�r_ rQ ra ra rb rc � s zTransaction.__init__rw c C s t � �dS )z�True if this transaction is totally deactivated from the connection and therefore can no longer affect its state. Nrc r� ra ra rb � _deactivated_from_connection� s z(Transaction._deactivated_from_connectionrf c C s t � �d S r rc r� ra ra rb � _do_close s zTransaction._do_closec C s t � �d S r rc r� ra ra rb � _do_rollback s zTransaction._do_rollbackc C s t � �d S r rc r� ra ra rb � _do_commit s zTransaction._do_commitc C s | j o| jj S r )r� rQ r� r� ra ra rb r� s zTransaction.is_validc C s( z| � � W | jr$J �n | jr"J �0 dS )a; Close this :class:`.Transaction`. If this transaction is the base transaction in a begin/commit nesting, the transaction will rollback(). Otherwise, the method returns. This is used to cancel a Transaction without affecting the scope of an enclosing transaction. N)rg r� r� ra ra rb r� s zTransaction.closec C s( z| � � W | jr$J �n | jr"J �0 dS )a� Roll back this :class:`.Transaction`. The implementation of this may vary based on the type of transaction in use: * For a simple database transaction (e.g. :class:`.RootTransaction`), it corresponds to a ROLLBACK. * For a :class:`.NestedTransaction`, it corresponds to a "ROLLBACK TO SAVEPOINT" operation. * For a :class:`.TwoPhaseTransaction`, DBAPI-specific methods for two phase transactions may be used. N)rh r� r� ra ra rb r� s zTransaction.rollbackc C s( z| � � W | jr$J �n | jr"J �0 dS )a� Commit this :class:`.Transaction`. The implementation of this may vary based on the type of transaction in use: * For a simple database transaction (e.g. :class:`.RootTransaction`), it corresponds to a COMMIT. * For a :class:`.NestedTransaction`, it corresponds to a "RELEASE SAVEPOINT" operation. * For a :class:`.TwoPhaseTransaction`, DBAPI-specific methods for two phase transactions may be used. N)ri r� r� ra ra rb r� 3 s zTransaction.commitc C s | j S r rb r� ra ra rb � _get_subjectH s zTransaction._get_subjectc C s | j S r )r� r� ra ra rb �_transaction_is_activeK s z"Transaction._transaction_is_activec C s | j S r )rf r� ra ra rb �_transaction_is_closedN s z"Transaction._transaction_is_closedc C s dS �NTra r� ra ra rb �_rollback_can_be_calledQ s z#Transaction._rollback_can_be_calledN)rT rU rV rW r_ ra rX rc rZ rf rg rh ri r� r� r� r� rj rk rl rn ra ra ra rb r` � s( % r` c @ s� e Zd ZdZdZdZdd�dd�Zdd �d d �Zed d �d d��Z dd �dd�Z dd �dd�Z dd �dd�Z d d dd�dd�Z dd �dd�Zdd �dd �Zdd �d d �Zd S )!r� a� Represent the "root" transaction on a :class:`_engine.Connection`. This corresponds to the current "BEGIN/COMMIT/ROLLBACK" that's occurring for the :class:`_engine.Connection`. The :class:`_engine.RootTransaction` is created by calling upon the :meth:`_engine.Connection.begin` method, and remains associated with the :class:`_engine.Connection` throughout its active span. The current :class:`_engine.RootTransaction` in use is accessible via the :attr:`_engine.Connection.get_transaction` method of :class:`_engine.Connection`. In :term:`2.0 style` use, the :class:`_engine.Connection` also employs "autobegin" behavior that will create a new :class:`_engine.RootTransaction` whenever a connection in a non-transactional state is used to emit commands on the DBAPI connection. The scope of the :class:`_engine.RootTransaction` in 2.0 style use can be controlled using the :meth:`_engine.Connection.commit` and :meth:`_engine.Connection.rollback` methods. T)rQ r� rE rb c C s< |j d u sJ �|jr t�|� || _| �� | |_ d| _d S rm )rL rI r r rQ �_connection_begin_implr� re ra ra rb rc s s zRootTransaction.__init__rf rw c C s8 | j r | jj| u sJ �d| _ n| jj| ur4t�d� d S )NFz0transaction already deassociated from connection)r� rQ rL r �warnr� ra ra rb �_deactivate_from_connection} s z+RootTransaction._deactivate_from_connectionrO c C s | j j| uS r )rQ rL r� ra ra rb rf � s z,RootTransaction._deactivated_from_connectionc C s | j �| � d S r )rQ r� r� ra ra rb ro � s z&RootTransaction._connection_begin_implc C s | j �� d S r )rQ r� r� ra ra rb �_connection_rollback_impl� s z)RootTransaction._connection_rollback_implc C s | j �� d S r )rQ r� r� ra ra rb �_connection_commit_impl� s z'RootTransaction._connection_commit_implF)�try_deactivaterj c C s� zL| j r| �� | jjr$| jj�� W | j s0|r8| �� | jj| u rvd | j_n(| j sX|r`| �� | jj| u rtd | j_0 | j r�J �| jj| us�J �d S r )r� rr rQ rM �_cancelrq rL )r_ rt ra ra rb � _close_impl� s � zRootTransaction._close_implc C s | � � d S r �rv r� ra ra rb rg � s zRootTransaction._do_closec C s | j dd� d S )NT)rt rw r� ra ra rb rh � s z RootTransaction._do_rollbackc C s� | j rh| jj| u sJ �z(| �� W | jjr6| jj�� | �� n | jjrT| jj�� | �� 0 d | j_n"| jj| u r�| j�� n t� d��| j r�J �| jj| us�J �d S )N� This transaction is inactive) r� rQ rL rs rM ru rq r� r r� r� ra ra rb ri � s � zRootTransaction._do_commitN)F)rT rU rV rW ra r_ rc rq rZ rf ro rr rs rv rg rh ri ra ra ra rb r� Y s r� c @ s� e Zd ZU dZdZded< dd�dd�Zd d d d �d d�Zed d�dd��Z d d�dd�Z d d d d�dd�Z d d�dd�Z d d�dd�Z d d�dd �Zd S ) r� a� Represent a 'nested', or SAVEPOINT transaction. The :class:`.NestedTransaction` object is created by calling the :meth:`_engine.Connection.begin_nested` method of :class:`_engine.Connection`. When using :class:`.NestedTransaction`, the semantics of "begin" / "commit" / "rollback" are as follows: * the "begin" operation corresponds to the "BEGIN SAVEPOINT" command, where the savepoint is given an explicit name that is part of the state of this object. * The :meth:`.NestedTransaction.commit` method corresponds to a "RELEASE SAVEPOINT" operation, using the savepoint identifier associated with this :class:`.NestedTransaction`. * The :meth:`.NestedTransaction.rollback` method corresponds to a "ROLLBACK TO SAVEPOINT" operation, using the savepoint identifier associated with this :class:`.NestedTransaction`. The rationale for mimicking the semantics of an outer transaction in terms of savepoints so that code may deal with a "savepoint" transaction and an "outer" transaction in an agnostic way. .. seealso:: :ref:`session_begin_nested` - ORM version of the SAVEPOINT API. )rQ r� � _savepoint�_previous_nestedre ry rE rb c C sH |j d usJ �|jr t�|� || _| j�� | _d| _|j| _ | |_d S rm ) rL rI r r rQ r� ry r� rM rz re ra ra rb rc � s zNestedTransaction.__init__TrO rf )rp rj c C s* | j j| u r| j| j _n|r&t�d� d S )Nz7nested transaction already deassociated from connection)rQ rM rz r rp )r_ rp ra ra rb rq � s �z-NestedTransaction._deactivate_from_connectionrw c C s | j j| uS r )rQ rM r� ra ra rb rf � s z.NestedTransaction._deactivated_from_connectionc C s" d| _ | �� | jr | j�� d S �NF)r� rq rz ru r� ra ra rb ru � s zNestedTransaction._cancel)�deactivate_from_connection�warn_already_deactiverj c C s| z@| j r(| jjr(| jjj r(| j�| j� W d| _ |rZ| j|d� nd| _ |rX| j|d� 0 | j rdJ �|rx| jj| usxJ �d S )NF)rp )r� rQ rL r� ry rq rM )r_ r| r} ra ra rb rv s" ���� z NestedTransaction._close_implc C s | � dd� d S )NTFrw r� ra ra rb rg s zNestedTransaction._do_closec C s | � dd� d S rm rw r� ra ra rb rh s z NestedTransaction._do_rollbackc C sX | j r2z| j�| j� W d| _ nd| _ 0 | �� n"| jj| u rJ| j�� n t�d��d S )NFz#This nested transaction is inactive) r� rQ r� ry rq rM r� r r� r� ra ra rb ri " s �z NestedTransaction._do_commitN)T)rT rU rV rW r_ rX rc rq rZ rf ru rv rg rh ri ra ra ra rb r� � s r� c sn e Zd ZU dZdZded< ddd�� fdd� Zd d �d d �Zd d �d d�Zd d �dd�Z d d �dd�Z � Z S )r� a Represent a two-phase transaction. A new :class:`.TwoPhaseTransaction` object may be procured using the :meth:`_engine.Connection.begin_twophase` method. The interface is the same as that of :class:`.Transaction` with the addition of the :meth:`prepare` method. )r� � _is_preparedr r� rE )rQ r� c s d| _ || _t� �|� d S r{ )r~ r� �superrc )r_ rQ r� �� __class__ra rb rc F s z TwoPhaseTransaction.__init__rf rw c C s( | j st�d��| j�| j� d| _dS )zqPrepare this :class:`.TwoPhaseTransaction`. After a PREPARE, the transaction can be committed. rx TN)r� r r� rQ r� r� r~ r� ra ra rb �prepareK s zTwoPhaseTransaction.preparec C s | j �| � d S r )rQ r� r� ra ra rb ro V s z*TwoPhaseTransaction._connection_begin_implc C s | j �| j| j� d S r )rQ r� r� r~ r� ra ra rb rr Y s z-TwoPhaseTransaction._connection_rollback_implc C s | j �| j| j� d S r )rQ r� r� r~ r� ra ra rb rs \ s z+TwoPhaseTransaction._connection_commit_impl) rT rU rV rW r_ rX rc r� ro rr rs � __classcell__ra ra r� rb r� 7 s r� c @ s� e Zd ZU dZded< ded< eZded< dZd ed < eZ d ed < d Z ded< dZ d ed< dZ ded< ded< ded< ded< ded< d ed < dZdddd d d d!d d"�d#d$�Z d%d&d'�d(d)�Zed d*�d+d,��Zd&d*�d-d.�Zd/d&d0�d1d2�Zed3d3d3d3d3d4�ddd5d dd/d6d7�d8d9��Zed/d6d0�d:d9��Zd/d6d0�d;d9�Zdd*�d<d=�Zedd*�d>d?��Zedd*�d@dA��Ze�� Zdd*�dBdC�Zd[d d&dE�dFdG�Z e j d\dHdIdJ�dKdL��Z e j dId*�dMdN��Z dOdPd/d&dQ�dRdS�Z!dTd*�dUdV�Z"dWd*�dXdY�Z#dS )]rN a� Connects a :class:`~sqlalchemy.pool.Pool` and :class:`~sqlalchemy.engine.interfaces.Dialect` together to provide a source of database connectivity and behavior. An :class:`_engine.Engine` object is instantiated publicly using the :func:`~sqlalchemy.create_engine` function. .. seealso:: :doc:`/core/engines` :ref:`connections_toplevel` rG rH r� r r+ rK FrO rR zType[Connection]�_connection_clszsqlalchemy.engine.Enginere rY � _is_futureNrv rz zType[OptionEngine]� _option_clsr. rF r5 r5 r1 �urlr �� r{ zOptional[_EchoFlagType]r� zOptional[Mapping[str, Any]])r5 rF r� � logging_name�echo�query_cache_sizer� r c C sp || _ || _|| _|r || _|| _|| _|dkrDtj|| jd�| _ nd | _ t j | |d� |rl| j f i |�� d S )Nr )Z size_alert�Zechoflag) r5 r� rF r� r� r r ZLRUCache�_lru_size_alertr r �instance_logger�update_execution_options) r_ r5 rF r� r� r� r� r� r ra ra rb rc � s � zEngine.__init__zutil.LRUCache[Any, Any]rf )�cacherj c C s" | � � r | j�dt|�|j� d S )NziCompiled cache size pruning from %d items to %d. Increase cache size to reduce the frequency of pruning.)r\ ro rp r �capacity)r_ r� ra ra rb r� � s �zEngine._lru_size_alertrw c C s | S )z�Returns this :class:`.Engine`. Used for legacy schemes that accept :class:`.Connection` / :class:`.Engine` objects within the same variable. ra r� ra ra rb rP � s z Engine.enginec C s | j r| j �� dS )a� Clear the compiled cache associated with the dialect. This applies **only** to the built-in cache that is established via the :paramref:`_engine.create_engine.query_cache_size` parameter. It will not impact any dictionary caches that were passed via the :paramref:`.Connection.execution_options.compiled_cache` parameter. .. versionadded:: 1.4 N)r �clearr� ra ra rb �clear_compiled_cache� s zEngine.clear_compiled_cacher r� c K s. | j �| |� | j�|�| _| j�| |� dS )a� Update the default execution_options dictionary of this :class:`_engine.Engine`. The given keys/values in \**opt are added to the default execution options that will be used for all connections. The initial contents of this dictionary can be sent via the ``execution_options`` parameter to :func:`_sa.create_engine`. .. seealso:: :meth:`_engine.Connection.execution_options` :meth:`_engine.Engine.execution_options` N)rH Z set_engine_execution_optionsrK r� rF r� ra ra rb r� � s z Engine.update_execution_options.)r� r� r� r� rx r � OptionEngine)r� r� r� r� rx r� rj c K s d S r ra )r_ r� r� r� r� rx r� ra ra rb r� � s zEngine.execution_optionsc K s d S r ra r� ra ra rb r� � s c K s | � | |�S )a Return a new :class:`_engine.Engine` that will provide :class:`_engine.Connection` objects with the given execution options. The returned :class:`_engine.Engine` remains related to the original :class:`_engine.Engine` in that it shares the same connection pool and other state: * The :class:`_pool.Pool` used by the new :class:`_engine.Engine` is the same instance. The :meth:`_engine.Engine.dispose` method will replace the connection pool instance for the parent engine as well as this one. * Event listeners are "cascaded" - meaning, the new :class:`_engine.Engine` inherits the events of the parent, and new events can be associated with the new :class:`_engine.Engine` individually. * The logging configuration and logging_name is copied from the parent :class:`_engine.Engine`. The intent of the :meth:`_engine.Engine.execution_options` method is to implement schemes where multiple :class:`_engine.Engine` objects refer to the same connection pool, but are differentiated by options that affect some execution-level behavior for each engine. One such example is breaking into separate "reader" and "writer" :class:`_engine.Engine` instances, where one :class:`_engine.Engine` has a lower :term:`isolation level` setting configured or is even transaction-disabled using "autocommit". An example of this configuration is at :ref:`dbapi_autocommit_multiple`. Another example is one that uses a custom option ``shard_id`` which is consumed by an event to change the current schema on a database connection:: from sqlalchemy import event from sqlalchemy.engine import Engine primary_engine = create_engine("mysql+mysqldb://") shard1 = primary_engine.execution_options(shard_id="shard1") shard2 = primary_engine.execution_options(shard_id="shard2") shards = {"default": "base", "shard_1": "db1", "shard_2": "db2"} @event.listens_for(Engine, "before_cursor_execute") def _switch_shard(conn, cursor, stmt, params, context, executemany): shard_id = conn.get_execution_options().get("shard_id", "default") current_shard = conn.info.get("current_shard", None) if current_shard != shard_id: cursor.execute("use %s" % shards[shard_id]) conn.info["current_shard"] = shard_id The above recipe illustrates two :class:`_engine.Engine` objects that will each serve as factories for :class:`_engine.Connection` objects that have pre-established "shard_id" execution options present. A :meth:`_events.ConnectionEvents.before_cursor_execute` event handler then interprets this execution option to emit a MySQL ``use`` statement to switch databases before a statement execution, while at the same time keeping track of which database we've established using the :attr:`_engine.Connection.info` dictionary. .. seealso:: :meth:`_engine.Connection.execution_options` - update execution options on a :class:`_engine.Connection` object. :meth:`_engine.Engine.update_execution_options` - update the execution options for a given :class:`_engine.Engine` in place. :meth:`_engine.Engine.get_execution_options` )r� r� ra ra rb r� � s Nc C s | j S )z�Get the non-SQL options which will take effect during execution. .. versionadded: 1.3 .. seealso:: :meth:`_engine.Engine.execution_options` r� r� ra ra rb r� 6 s z Engine.get_execution_optionsc C s | j jS )zsString name of the :class:`~sqlalchemy.engine.interfaces.Dialect` in use by this :class:`Engine`. )rF r} r� ra ra rb r} A s z Engine.namec C s | j jS )zsDriver name of the :class:`~sqlalchemy.engine.interfaces.Dialect` in use by this :class:`Engine`. )rF �driverr� ra ra rb r� J s z Engine.driverc C s d| j f S )Nz Engine(%r))r� r� ra ra rb �__repr__U s zEngine.__repr__T)r� rj c C s* |r| j �� | j �� | _ | j�| � dS )a Dispose of the connection pool used by this :class:`_engine.Engine`. A new connection pool is created immediately after the old one has been disposed. The previous connection pool is disposed either actively, by closing out all currently checked-in connections in that pool, or passively, by losing references to it but otherwise not closing any connections. The latter strategy is more appropriate for an initializer in a forked Python process. :param close: if left at its default of ``True``, has the effect of fully closing all **currently checked in** database connections. Connections that are still checked out will **not** be closed, however they will no longer be associated with this :class:`_engine.Engine`, so when they are closed individually, eventually the :class:`_pool.Pool` which they are associated with will be garbage collected and they will be closed out fully, if not already closed on checkin. If set to ``False``, the previous connection pool is de-referenced, and otherwise not touched in any way. .. versionadded:: 1.4.33 Added the :paramref:`.Engine.dispose.close` parameter to allow the replacement of a connection pool in a child process without interfering with the connections used by the parent process. .. seealso:: :ref:`engine_disposal` :ref:`pooling_multiprocessing` N)r5 �disposeZrecreaterH Zengine_disposed)r_ r� ra ra rb r� X s % zEngine.disposer^ zIterator[Connection])rQ rj c c sB |d u r8| � � �}|V W d � q>1 s,0 Y n|V d S r )�connect)r_ rQ r� ra ra rb �_optional_conn_ctx_manager� s &z!Engine._optional_conn_ctx_managerc c sZ | � � �>}|�� � |V W d � n1 s.0 Y W d � n1 sL0 Y dS )a Return a context manager delivering a :class:`_engine.Connection` with a :class:`.Transaction` established. E.g.:: with engine.begin() as conn: conn.execute(text("insert into table (x, y, z) values (1, 2, 3)")) conn.execute(text("my_special_procedure(5)")) Upon successful operation, the :class:`.Transaction` is committed. If an error is raised, the :class:`.Transaction` is rolled back. .. seealso:: :meth:`_engine.Engine.connect` - procure a :class:`_engine.Connection` from an :class:`_engine.Engine`. :meth:`_engine.Connection.begin` - start a :class:`.Transaction` for a particular :class:`_engine.Connection`. N)r� r� )r_ r� ra ra rb r� � s z Engine.beginrN r? rO c K s@ | � � �$}|j||fi |�� W d � n1 s20 Y d S r )r� rS )r_ rP rQ rR r� ra ra rb rS � s zEngine._run_ddl_visitorrE c C s | � | �S )a< Return a new :class:`_engine.Connection` object. The :class:`_engine.Connection` acts as a Python context manager, so the typical use of this method looks like:: with engine.connect() as connection: connection.execute(text("insert into table values ('foo')")) connection.commit() Where above, after the block is completed, the connection is "closed" and its underlying DBAPI resources are returned to the connection pool. This also has the effect of rolling back any transaction that was explicitly begun or was begun via autobegin, and will emit the :meth:`_events.ConnectionEvents.rollback` event if one was started and is still in progress. .. seealso:: :meth:`_engine.Engine.begin` )r� r� ra ra rb r� � s zEngine.connectr6 c C s | j �� S )aC Return a "raw" DBAPI connection from the connection pool. The returned object is a proxied version of the DBAPI connection object used by the underlying driver in use. The object will have all the same behavior as the real DBAPI connection, except that its ``close()`` method will result in the connection being returned to the pool, rather than being closed for real. This method provides direct DBAPI connection access for special situations when the API provided by :class:`_engine.Connection` is not needed. When a :class:`_engine.Connection` object is already present, the DBAPI connection is available using the :attr:`_engine.Connection.connection` accessor. .. seealso:: :ref:`dbapi_connections` )r5 r� r� ra ra rb rU � s zEngine.raw_connection)NNr� NF)T)N)$rT rU rV rW rX rC rK rR rE r� rY r� rz rc r� rZ rP r� r� r r� r� r} r� r Z echo_propertyr� r� r� � contextlib�contextmanagerr� r� rS r� rU ra ra ra rb rN ` sf � � P * � rN c @ s� e Zd ZU dZded< ded< ded< ded < d ed < d ed < ded< ddd�dd�Zddd�dd�Zejs�e dd�dd ��Z e j ddd �d d ��Z e d d�d d ��Z e j d dd!�d"d ��Z d#S )$�OptionEngineMixinFrG rH r� r r. rF r5 r5 r1 r� rO r zlog.echo_propertyr� rN r- )�proxiedr� c C sr || _ |j| _|j| _|j| _|j| _|j| _|j| _tj| | jd� | j � |j �| _ |j | _ | j f i |�� d S )Nr� ) �_proxiedr� rF r� r� r r r r� rH r^ rK r� )r_ r� r� ra ra rb rc � s zOptionEngineMixin.__init__r rf r� c K s t � �d S r rc r� ra ra rb r� s z*OptionEngineMixin.update_execution_optionsrw c C s | j jS r �r� r5 r� ra ra rb r5 s zOptionEngineMixin.pool)r5 rj c C s || j _d S r r� )r_ r5 ra ra rb r5 s c C s | j jp| j�dd�S )NrR F)r� rR �__dict__ry r� ra ra rb rR s �z OptionEngineMixin._has_events)r� rj c C s || j d< d S )NrR )r� )r_ r� ra ra rb rR s N) rT rU rV Z_sa_propagate_class_eventsrX rc r� �typing� TYPE_CHECKINGrZ r5 �setterrR ra ra ra rb r� � s& r� c @ s e Zd Zddd�dd�ZdS )r� r rf r� c K s t j| fi |�� d S r )rN r� r� ra ra rb r� & s z%OptionEngine.update_execution_optionsN)rT rU rV r� ra ra ra rb r� % s r� )brW � __future__r r� r: r� r r r r r r r r r r r r r r Z interfacesr r r r r r r r r r r r� r r r Zsqlr! r! r� r" r# r$ r% r& r' r( r) r* r+ r, r- r. r/ Z reflectionr0 r� r1 �eventr2 r3 r5 r4 r5 r6 r7 Z sql._typingr8 Z sql.compilerr9 Zsql.ddlr: r; Z sql.functionsr< Z sql.schemar= r> r? Zsql.selectabler@ rA � EMPTY_DICTrC rX rD Z InspectablerE rB r` r� r� r� Z IdentifiedrN r� r� r� ra ra ra rb �<module> s� V/ lr) � A sqlalchemy/engine/__pycache__/_py_row.cpython-39.pyc 0000644 00000010112 15125143220 0016460 0 ustar 00 a ��Jh� � @ s d dl mZ d dlZd dlZd dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlm Z d d lm Z d d lm Z d d lm Z ej r�d d lmZ d dlmZ d dlmZ d dlmZ d dlmZ d ZG dd� d�Zdddd�dd�Zddd�d d �ZdS ) � )� annotationsN)�Any)�Callable)�Dict)�Iterator)�List)�Mapping)�Optional)�Tuple)�Type� )�_KeyType)�_ProcessorsType)� _RawRowType)�_TupleGetterType)�ResultMetaDatac @ s� e Zd ZU dZded< ded< ded< ddddd �d d �Zd d �dd�Zdd �dd�Zddd�dd�Zdd �dd�Z dd �dd �Z d d �d d �Z d d �d d!�Z d"d"d#�d$d%�Z d&d"d#�d'd(�Zd&d"d)�d*d+�Zd,d �d-d.�Zd/S )0�BaseRow)�_parent�_data� _key_to_indexr r zMapping[_KeyType, int]r r r zOptional[_ProcessorsType])�parent� processors� key_to_index�datac C sZ t �| d|� t �| d|� |rDt �| dtdd� t||�D ��� nt �| dt|�� dS )z4Row objects are constructed by CursorResult objects.r r r c S s g | ]\}}|r||�n|�qS � r )�.0�proc�valuer r �N/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/engine/_py_row.py� <listcomp>7 s �z$BaseRow.__init__.<locals>.<listcomp>N)�object� __setattr__�tuple�zip)�selfr r r r r r r �__init__& s ��� zBaseRow.__init__z.Tuple[Callable[..., BaseRow], Tuple[Any, ...]])�returnc C s t | j| �� ffS �N)�rowproxy_reconstructor� __class__� __getstate__�r$ r r r � __reduce__@ s �zBaseRow.__reduce__�Dict[str, Any]c C s | j | jd�S )N�r r r. r+ r r r r* F s zBaseRow.__getstate__�None)�stater& c C s< |d }t �| d|� t �| d|d � t �| d|j� d S )Nr r r )r r! r )r$ r0 r r r r � __setstate__I s zBaseRow.__setstate__z List[Any]c C s t | �S r' )�listr+ r r r � _values_implO s zBaseRow._values_implz Iterator[Any]c C s t | j�S r' )�iterr r+ r r r �__iter__R s zBaseRow.__iter__�intc C s t | j�S r' )�lenr r+ r r r �__len__U s zBaseRow.__len__c C s t | j�S r' )�hashr r+ r r r �__hash__X s zBaseRow.__hash__r )�keyr& c C s | j | S r' �r �r$ r; r r r � __getitem__[ s zBaseRow.__getitem__�strc C s8 z| j | j| W S ty$ Y n0 | j�|d� d S )NF�r r �KeyErrorr Z_key_not_foundr= r r r �_get_by_key_impl_mapping^ s z BaseRow._get_by_key_impl_mapping)�namer& c C s8 z| j | j| W S ty$ Y n0 | j�|d� d S )NTr@ )r$ rC r r r � __getattr__e s zBaseRow.__getattr__zTuple[Any, ...]c C s | j S r' r< r+ r r r �_to_tuple_instancel s zBaseRow._to_tuple_instanceN)�__name__� __module__� __qualname__� __slots__�__annotations__r% r, r* r1 r3 r5 r8 r: r> rB rD rE r r r r r s r z Type[BaseRow]r- )�clsr0 r& c C s | � | �}|�|� |S r' )�__new__r1 )rK r0 �objr r r r( r s r( r6 r )�indexesr& c G sb t | �dkrFtdt | ��D ]*}| |d | | d krtj| � S qt�t| d | d d ��S )Nr r ���)r7 �range�operator� itemgetter�slice)rN �ir r r � tuplegetterz s rU )� __future__r rQ �typingr r r r r r r r r � TYPE_CHECKING�resultr r r r r ZMD_INDEXr r( rU r r r r �<module> s* S sqlalchemy/engine/__pycache__/util.cpython-39.pyc 0000644 00000011737 15125143220 0015775 0 ustar 00 a ��Jh2 � @ s d dl mZ d dlZd dlmZ d dlmZ d dlmZ d dlmZ ddlmZ dd lm Z dd l m Z dd l m Z dd l mZ ejs�e s�d dlmZ d dlmZ nd dlmZ d dlmZ edeg ef d�Zddd�dd�ZG dd� de �ZG dd� d�ZdS )� )� annotationsN)�Any)�Callable)�Optional)�TypeVar� )�exc)�util)�HAS_CYEXTENSION)�Protocol)�Self� )�_distill_params_20)�_distill_raw_params�_C)�bound�strzCallable[[_C], _C])�key�returnc s t j� fdd��}|S )z�Decorator, memoize a function in a connection.info stash. Only applicable to functions which take no arguments other than a connection. The memo will be stored in ``connection.info[key]``. c sD |� � }z |j� W S ty> | ||� |j� < }| Y S 0 d S �N)�connect�info�KeyError)�fn�self� connection�val�r � �K/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/engine/util.py� decorated+ s z%connection_memoize.<locals>.decorated)r � decorator)r r r r r �connection_memoize$ s r" c @ s e Zd ZU ded< dS )� _TConsSubjectz Optional[TransactionalContext]�_trans_context_managerN)�__name__� __module__� __qualname__�__annotations__r r r r r# 7 s r# c @ s� e Zd ZU dZdZded< dd�dd�Zdd�d d �Zdd�d d �Zd d�dd�Z dd�dd�Z dd�dd�Z dd�dd�Z e d dd�dd��Zdd�dd �Zd d d dd �d d �Zd!S )"�TransactionalContextz�Apply Python context manager behavior to transaction objects. Performs validation to ensure the subject of the transaction is not used if the transaction were ended prematurely. )�_outer_trans_ctx�_trans_subject� __weakref__zOptional[_TConsSubject]r+ �bool)r c C s t � �d S r ��NotImplementedError�r r r r �_transaction_is_activeG s z+TransactionalContext._transaction_is_activec C s t � �d S r r. r0 r r r �_transaction_is_closedJ s z+TransactionalContext._transaction_is_closedc C s t � �dS )a indicates the object is in a state that is known to be acceptable for rollback() to be called. This does not necessarily mean rollback() will succeed or not raise an error, just that there is currently no state detected that indicates rollback() would fail or emit warnings. It also does not mean that there's a transaction in progress, as it is usually safe to call rollback() even if no transaction is present. .. versionadded:: 1.4.28 Nr. r0 r r r �_rollback_can_be_calledM s z,TransactionalContext._rollback_can_be_calledr# c C s t � �d S r r. r0 r r r � _get_subject^ s z!TransactionalContext._get_subject�Nonec C s t � �d S r r. r0 r r r �commita s zTransactionalContext.commitc C s t � �d S r r. r0 r r r �rollbackd s z TransactionalContext.rollbackc C s t � �d S r r. r0 r r r �closeg s zTransactionalContext.close)�subjectr c C s |j }|r |�� s t�d��d S )Nz�Can't operate on closed transaction inside context manager. Please complete the context manager before emitting further commands.)r$ r1 r ZInvalidRequestError)�clsr9 � trans_contextr r r �_trans_ctx_checkj s �z%TransactionalContext._trans_ctx_checkr c C s$ | � � }|j}|| _|| _| |_| S r )r4 r$ r* r+ )r r9 r; r r r � __enter__u s z TransactionalContext.__enter__r )�type_�value� tracebackr c C sX t | dd �}|d u p |j| u}|d u r�| �� r�zzz | �� W nD t�� � | �� r^| �� W d � n1 sr0 Y Y n0 W |s�|d us�J �| j|_d | _ | _n&|s�|d us�J �| j|_d | _ | _0 n�zV| �� s�| � � s�| � � n| �� r�| �� W |�s |d u�sJ �| j|_d | _ | _n*|�sF|d u�s>J �| j|_d | _ | _0 d S )Nr+ ) �getattrr$ r1 r6 r Z safe_reraiser3 r7 r* r+ r2 r8 )r r> r? r@ r9 Zout_of_band_exitr r r �__exit__� s@ � . � �z TransactionalContext.__exit__N)r% r& r' �__doc__� __slots__r( r1 r2 r3 r4 r6 r7 r8 � classmethodr< r= rB r r r r r) ; s r) )� __future__r �typingr r r r � r r Z util._has_cyr Z util.typingr r � TYPE_CHECKINGZ_py_utilr r Zsqlalchemy.cyextension.utilr r" r# r) r r r r �<module> s& sqlalchemy/engine/__pycache__/_py_processors.cpython-39.pyc 0000644 00000006456 15125143220 0020073 0 ustar 00 a ��Jh� � @ s< d Z ddlmZ ddlZddlmZ ddlmZ ddlmZ ddl m Z ddl Z ddl m Z dd l m Z dd l mZ dd l mZ dd l mZ dd l mZ edeejejejf d�Zdddd�dd�Zdddd�dd�Zd d d �d d �Zd!d"d �d#d$�Zd%d&d �d'd(�Zd"d)d �d*d+�Zd"d,d �d-d.�Zd"d/d �d0d1�ZdS )2z�defines generic type conversion functions, as used in bind and result processors. They all share one common characteristic: None is passed through unchanged. � )� annotationsN)�date)�datetime)�time)�Decimal)�Any)�Callable)�Optional)�Type)�TypeVar)�Union�_DT)�boundztyping.Pattern[str]zCallable[..., _DT]z(Callable[[Optional[str]], Optional[_DT]])�regexp�type_�returnc s, | j �t| j�� ddd�� ��fdd� }|S )N� Optional[str]z Optional[_DT]��valuer c s� | d u r d S z �| �}W n8 t yP } z td�j| f �|�W Y d }~n d }~0 0 |d u rltd�j| f ��� r�|�d�}�f i tttt|�� �tt t t|� � ��������S �tt t |� d���� S d S )Nz6Couldn't parse %s string '%r' - value is not a string.z Couldn't parse %s string: '%s'r ) � TypeError� ValueError�__name__� groupdict�dict�list�zip�iter�keys�map�int�values�groups)r �m�errr! �Zhas_named_groupsZrmatchr � �U/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/engine/_py_processors.py�process- s> ����� ���� z2str_to_datetime_processor_factory.<locals>.process)�match�bool� groupindex)r r r' r% r$ r& �!str_to_datetime_processor_factory% s r+ z Type[Decimal]r z.Callable[[Optional[float]], Optional[Decimal]])� target_class�scaler c s" d| � ddd�� �fdd� }|S )Nz%%.%df�Optional[float]zOptional[Decimal]r c s | d u r d S �� | �S d S �Nr% �r �Zfstringr, r% r& r' U s z-to_decimal_processor_factory.<locals>.processr% )r, r- r' r% r1 r& � to_decimal_processor_factoryP s r2 zOptional[Union[int, float]]r. r c C s | d u r d S t | �S d S r/ )�floatr0 r% r% r& �to_float^ s r4 z Optional[Any]r c C s | d u r d S t | �S d S r/ )�strr0 r% r% r& �to_stre s r6 z Optional[int]zOptional[bool]c C s | d u r d S t | �S d S r/ )r) r0 r% r% r& �int_to_booleanl s r7 zOptional[datetime.datetime]c C s | d urt �| �}nd }|S r/ )� datetime_cls� fromisoformat�r Zdt_valuer% r% r& �str_to_datetimes s r; zOptional[datetime.time]c C s | d urt �| �}nd }|S r/ )�time_clsr9 r: r% r% r& � str_to_time{ s r= zOptional[datetime.date]c C s | d urt �| �}nd }|S r/ )�date_clsr9 r: r% r% r& � str_to_date� s r? )�__doc__� __future__r r r r> r8 r r< �decimalr �typingr r r r r r r r+ r2 r4 r6 r7 r; r= r? r% r% r% r& �<module> s0 �+ sqlalchemy/engine/__pycache__/row.cpython-39.pyc 0000644 00000034721 15125143220 0015625 0 ustar 00 a ��Jh�. � @ s d Z ddlmZ ddlmZ ddlmZ ddlZddlZddlm Z ddlm Z ddlm Z ddlm Z dd lm Z dd lmZ dd lmZ dd lmZ dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddl m Z e�s e �s*ddl m Z n ddl m Z e�r`ddl!m"Z" ddl!m#Z# dd l!m$Z$ ed e d �Z%ed ee d f d �Z&G d!d"� d"e ee e e& �Z'e Z(e'Z)G d#d$� d$e�Z*G d%d&� d&e*ej+d' ej,e �Z-G d(d)� d)e*ej.d'e f �Z/G d*d+� d+e ejd'e f �Z0dS ),z.Define row constructs including :class:`.Row`.� )� annotations)�ABCN)�Any)�Callable)�Dict)�Generic)�Iterator)�List)�Mapping)�NoReturn)�Optional)�overload)�Sequence)�Tuple)� TYPE_CHECKING)�TypeVar)�Union� )�util)� deprecated)�HAS_CYEXTENSION� )�BaseRow)�_KeyType)�_ProcessorsType)� RMKeyView�_T)�bound�_TP.c @ s� e Zd ZdZdZdddd�dd�Zddd �d d �Zd d �dd�Zedd�d d �dd��Z e d d �dd��Z e edd�d d �dd���Z e dd �dd��Z d d d �d d �Zes�ddd �d!d"�Zed#�Zed$�Zdd%d&�d'd(�Zdd)d%d*�d+d,�ZejZe�r2ed-dd.�d/d0��Zed1d2d.�d3d0��Zd4dd.�d5d0�Zdd%d6�d7d8�Zdd%d6�d9d:�Zdd%d6�d;d<�Zdd%d6�d=d>�Z dd%d6�d?d@�Z dd%d6�dAdB�Z dd �dCdD�Z e dEd �dFdG��Z dHd �dIdJ�Z!dKS )L�Rowa Represent a single result row. The :class:`.Row` object represents a row of a database result. It is typically associated in the 1.x series of SQLAlchemy with the :class:`_engine.CursorResult` object, however is also used by the ORM for tuple-like results as of SQLAlchemy 1.4. The :class:`.Row` object seeks to act as much like a Python named tuple as possible. For mapping (i.e. dictionary) behavior on a row, such as testing for containment of keys, refer to the :attr:`.Row._mapping` attribute. .. seealso:: :ref:`tutorial_selecting_data` - includes examples of selecting rows from SELECT statements. .. versionchanged:: 1.4 Renamed ``RowProxy`` to :class:`.Row`. :class:`.Row` is no longer a "proxy" object in that it contains the final form of data within it, and now acts mostly like a named tuple. Mapping-like functionality is moved to the :attr:`.Row._mapping` attribute. See :ref:`change_4710_core` for background on this change. � �strr r )�name�value�returnc C s t d��d S )Nzcan't set attribute��AttributeError)�selfr" r# r r �J/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/engine/row.py� __setattr__P s zRow.__setattr__)r" r$ c C s t d��d S )Nzcan't delete attributer% )r' r" r r r( � __delattr__S s zRow.__delattr__r �r$ c C s | S )a5 Return a 'tuple' form of this :class:`.Row`. At runtime, this method returns "self"; the :class:`.Row` object is already a named tuple. However, at the typing level, if this :class:`.Row` is typed, the "tuple" return type will be a :pep:`484` ``Tuple`` datatype that contains typing information about individual elements, supporting typed unpacking and attribute access. .. versionadded:: 2.0.19 - The :meth:`.Row._tuple` method supersedes the previous :meth:`.Row.tuple` method, which is now underscored to avoid name conflicts with column names in the same way as other named-tuple methods on :class:`.Row`. .. seealso:: :attr:`.Row._t` - shorthand attribute notation :meth:`.Result.tuples` r �r' r r r( �_tupleV s z Row._tuplez2.0.19z�The :meth:`.Row.tuple` method is deprecated in favor of :meth:`.Row._tuple`; all :class:`.Row` methods and library-level attributes are intended to be underscored to avoid name conflicts. Please use :meth:`Row._tuple`.c C s | � � S )zUReturn a 'tuple' form of this :class:`.Row`. .. versionadded:: 2.0 )r- r, r r r( �tuplen s z Row.tuplec C s | S )aw A synonym for :meth:`.Row._tuple`. .. versionadded:: 2.0.19 - The :attr:`.Row._t` attribute supersedes the previous :attr:`.Row.t` attribute, which is now underscored to avoid name conflicts with column names in the same way as other named-tuple methods on :class:`.Row`. .. seealso:: :attr:`.Result.t` r r, r r r( �_t} s zRow._tz�The :attr:`.Row.t` attribute is deprecated in favor of :attr:`.Row._t`; all :class:`.Row` methods and library-level attributes are intended to be underscored to avoid name conflicts. Please use :attr:`Row._t`.c C s | j S )zKA synonym for :meth:`.Row._tuple`. .. versionadded:: 2.0 )r/ r, r r r( �t� s zRow.t� RowMappingc C s t | jd| j| j�S )a] Return a :class:`.RowMapping` for this :class:`.Row`. This object provides a consistent Python mapping (i.e. dictionary) interface for the data contained within the row. The :class:`.Row` by itself behaves like a named tuple. .. seealso:: :attr:`.Row._fields` .. versionadded:: 1.4 N)r1 �_parent� _key_to_index�_datar, r r r( �_mapping� s z Row._mappingzOptional[_ProcessorsType]zRow[Any])� processorr$ c C s t | j|| j| j�S �N)r r2 r3 r4 )r' r6 r r r( �_filter_on_values� s zRow._filter_on_valuesc s t ddd�� fdd� �}|S )z3Handle ambiguous names such as "count" and "index" r r )r' r$ c s6 � j ���r� ���S dddd��� fdd� }|S d S )Nr )�arg�kwr$ c s t tj� ��g| �R i |��S r7 )�getattr�collections_abcr )r9 r: )r" r' r r( �meth� s ���z4Row._special_name_accessor.<locals>.go.<locals>.meth)r2 �_has_key� __getattr__)r' r= �r" r, r( �go� s z&Row._special_name_accessor.<locals>.go)�property)r" rA r r@ r( �_special_name_accessor� s zRow._special_name_accessor�count�index�bool��keyr$ c C s || j v S r7 )r4 �r' rH r r r( � __contains__� s zRow.__contains__zCallable[[Any, Any], bool])�other�opr$ c C s* t |t�r || �� |�� �S || �� |�S r7 )� isinstancer Z_to_tuple_instance)r' rK rL r r r( �_op� s � �zRow._op�int)rE r$ c C s d S r7 r �r' rE r r r( � __getitem__� s zRow.__getitem__�slice� Sequence[Any]c C s d S r7 r rP r r r( rQ � s zUnion[int, slice]c C s d S r7 r rP r r r( rQ � � �rK r$ c C s | � |tj�S r7 )rN �operator�lt�r' rK r r r( �__lt__� s z Row.__lt__c C s | � |tj�S r7 )rN rV �lerX r r r( �__le__� s z Row.__le__c C s | � |tj�S r7 )rN rV �gerX r r r( �__ge__� s z Row.__ge__c C s | � |tj�S r7 )rN rV �gtrX r r r( �__gt__� s z Row.__gt__c C s | � |tj�S r7 )rN rV �eqrX r r r( �__eq__� s z Row.__eq__c C s | � |tj�S r7 )rN rV �nerX r r r( �__ne__� s z Row.__ne__c C s t t�| ��S r7 )�repr�sql_utilZ _repr_rowr, r r r( �__repr__� s z Row.__repr__zTuple[str, ...]c C s t dd� | jjD ��S )a� Return a tuple of string keys as represented by this :class:`.Row`. The keys can represent the labels of the columns returned by a core statement or the names of the orm classes returned by an orm execution. This attribute is analogous to the Python named tuple ``._fields`` attribute. .. versionadded:: 1.4 .. seealso:: :attr:`.Row._mapping` c S s g | ]}|d ur|�qS r7 r ��.0�kr r r( � <listcomp> rT z Row._fields.<locals>.<listcomp>)r. r2 �keysr, r r r( �_fields� s z Row._fieldszDict[str, Any]c C s t | j�S )am Return a new dict which maps field names to their corresponding values. This method is analogous to the Python named tuple ``._asdict()`` method, and works by applying the ``dict()`` constructor to the :attr:`.Row._mapping` attribute. .. versionadded:: 1.4 .. seealso:: :attr:`.Row._mapping` )�dictr5 r, r r r( �_asdict s z Row._asdictN)"�__name__� __module__� __qualname__�__doc__� __slots__r) r* r- r r. rB r/ r0 r5 r8 r rC rD rE rJ rN r �__hash__r rQ rY r[ r] r_ ra rc rf rl rn r r r r( r 2 sX ��r c @ s� e Zd ZU dZded< ded< ddd�dd�Zd d �d d �Zd d �dd�Zdd �dd�Zddd�dd�Z ddd�dd�Z ddd�dd �Z d S ) � ROMappingViewr rS �_itemszMapping['_KeyType', Any]r5 )�mapping�itemsc C s || _ || _d S r7 )r5 rv )r' rw rx r r r( �__init__% s zROMappingView.__init__rO r+ c C s t | j�S r7 )�lenrv r, r r r( �__len__+ s zROMappingView.__len__r! c C s d� | �S )Nz&{0.__class__.__name__}({0._mapping!r}))�formatr, r r r( rf . s zROMappingView.__repr__z Iterator[Any]c C s t | j�S r7 )�iterrv r, r r r( �__iter__1 s zROMappingView.__iter__r rF )�itemr$ c C s || j v S r7 �rv )r' r r r r( rJ 4 s zROMappingView.__contains__rU c C s t |�t | �kS r7 ��listrX r r r( ra 7 s zROMappingView.__eq__c C s t |�t | �kS r7 r� rX r r r( rc : s zROMappingView.__ne__N) ro rp rq rs �__annotations__ry r{ rf r~ rJ ra rc r r r r( ru s ru c @ s e Zd ZdZdS )�ROMappingKeysValuesViewr� N�ro rp rq rs r r r r( r� > s r� r c @ s e Zd ZdZdS )�ROMappingItemsViewr� Nr� r r r r( r� D s r� c @ s� e Zd ZdZdZer&ddd�dd�ZnejZdd �d d �Z d d �d d�Z dd �dd�Z ddd�dd�Z dd �dd�Z dd �dd�Zd d �d d �Zd d �d d!�Zd"S )#r1 a� A ``Mapping`` that maps column names and objects to :class:`.Row` values. The :class:`.RowMapping` is available from a :class:`.Row` via the :attr:`.Row._mapping` attribute, as well as from the iterable interface provided by the :class:`.MappingResult` object returned by the :meth:`_engine.Result.mappings` method. :class:`.RowMapping` supplies Python mapping (i.e. dictionary) access to the contents of the row. This includes support for testing of containment of specific keys (string column names or objects), as well as iteration of keys, values, and items:: for row in result: if "a" in row._mapping: print("Column 'a': %s" % row._mapping["a"]) print("Column b: %s" % row._mapping[table.c.b]) .. versionadded:: 1.4 The :class:`.RowMapping` object replaces the mapping-like access previously provided by a database result row, which now seeks to behave mostly like a named tuple. r r r rG c C s d S r7 r rI r r r( rQ f rT zRowMapping.__getitem__z List[Any]r+ c C s t | j�S r7 )r� r4 r, r r r( � _values_implk s zRowMapping._values_implz Iterator[str]c C s dd� | j jD �S )Nc s s | ]}|d ur|V qd S r7 r rg r r r( � <genexpr>o rT z&RowMapping.__iter__.<locals>.<genexpr>�r2 rk r, r r r( r~ n s zRowMapping.__iter__rO c C s t | j�S r7 )rz r4 r, r r r( r{ q s zRowMapping.__len__�objectrF c C s | j �|�S r7 )r2 r> rI r r r( rJ t s zRowMapping.__contains__r! c C s t t| ��S r7 )rd rm r, r r r( rf w s zRowMapping.__repr__r� c s t � � fdd�� �� D ��S )zeReturn a view of key/value tuples for the elements in the underlying :class:`.Row`. c s g | ]}|� | f�qS r r )rh rH r, r r( rj � rT z$RowMapping.items.<locals>.<listcomp>)r� rk r, r r, r( rx z s �zRowMapping.itemsr c C s | j jS )znReturn a view of 'keys' for string column names represented by the underlying :class:`.Row`. r� r, r r r( rk � s zRowMapping.keysr� c C s t | | �� �S )zeReturn a view of values for the values represented in the underlying :class:`.Row`. )r� r� r, r r r( �values� s zRowMapping.valuesN)ro rp rq rr rs r rQ r Z_get_by_key_impl_mappingr� r~ r{ rJ rf rx rk r� r r r r( r1 H s r1 )1rr � __future__r �abcr �collections.abcr< rV �typingr r r r r r r r r r r r r r r Zsqlr re r Z util._has_cyr Z_py_rowr Z"sqlalchemy.cyextension.resultproxy�resultr r r r r r Z BaseRowProxyZRowProxyru �KeysView� ValuesViewr� � ItemsViewr� r1 r r r r( �<module> sT j � sqlalchemy/engine/__pycache__/__init__.cpython-39.pyc 0000644 00000004232 15125143220 0016547 0 ustar 00 a ��Jh � @ s$ d Z ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z dd lm Z dd l m Z dd l m Z dd l mZ dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlm Z ddlm Z ddl m Z ddl m!Z! dd l m"Z" dd l m#Z# dd l$m%Z% dd l$m&Z& dd l$m'Z' dd!l$m(Z( dd"l$m)Z) dd#l$m*Z* dd$l$m+Z+ dd%l$m,Z, dd&l$m-Z- dd'l$m.Z. dd(l/m0Z0 dd)l/m1Z1 dd*l/m2Z2 dd+l3m4Z4 dd,l3m5Z5 dd-lm6Z6 d.d/l7m8Z8 d0S )1ad SQL connections, SQL execution and high-level DB-API interface. The engine package defines the basic components used to interface DB-API modules with higher-level statement construction, connection-management, execution and result contexts. The primary "entry point" class into this package is the Engine and its public constructor ``create_engine()``. � )�events)�util)� Connection)�Engine)�NestedTransaction)�RootTransaction)� Transaction)�TwoPhaseTransaction)� create_engine)�create_pool_from_url)�engine_from_config)� CursorResult)� ResultProxy)�AdaptedConnection)� BindTyping)�Compiled)� Connectable)�ConnectArgsType)�ConnectionEventsTarget)�CreateEnginePlugin)�Dialect)�ExceptionContext)�ExecutionContext)� TypeCompiler)�create_mock_engine)� Inspector)� ObjectKind)� ObjectScope)�ChunkedIteratorResult)� FilterResult)� FrozenResult)�IteratorResult)� MappingResult)� MergedResult)�Result)� result_tuple)� ScalarResult)� TupleResult)�BaseRow)�Row)� RowMapping)�make_url)�URL)�connection_memoize� )�ddlN)9�__doc__� r r �baser r r r r r �creater r r �cursorr r Z interfacesr r r r r r r r r r r Zmockr Z reflectionr r r �resultr r r r! r" r# r$ r% r& r' �rowr( r) r* �urlr+ r, r- Zsqlr/ � r8 r8 �O/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/engine/__init__.py�<module> sZ sqlalchemy/engine/util.py 0000755 00000013062 15125143220 0011502 0 ustar 00 # engine/util.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php from __future__ import annotations import typing from typing import Any from typing import Callable from typing import Optional from typing import TypeVar from .. import exc from .. import util from ..util._has_cy import HAS_CYEXTENSION from ..util.typing import Protocol from ..util.typing import Self if typing.TYPE_CHECKING or not HAS_CYEXTENSION: from ._py_util import _distill_params_20 as _distill_params_20 from ._py_util import _distill_raw_params as _distill_raw_params else: from sqlalchemy.cyextension.util import ( # noqa: F401 _distill_params_20 as _distill_params_20, ) from sqlalchemy.cyextension.util import ( # noqa: F401 _distill_raw_params as _distill_raw_params, ) _C = TypeVar("_C", bound=Callable[[], Any]) def connection_memoize(key: str) -> Callable[[_C], _C]: """Decorator, memoize a function in a connection.info stash. Only applicable to functions which take no arguments other than a connection. The memo will be stored in ``connection.info[key]``. """ @util.decorator def decorated(fn, self, connection): # type: ignore connection = connection.connect() try: return connection.info[key] except KeyError: connection.info[key] = val = fn(self, connection) return val return decorated class _TConsSubject(Protocol): _trans_context_manager: Optional[TransactionalContext] class TransactionalContext: """Apply Python context manager behavior to transaction objects. Performs validation to ensure the subject of the transaction is not used if the transaction were ended prematurely. """ __slots__ = ("_outer_trans_ctx", "_trans_subject", "__weakref__") _trans_subject: Optional[_TConsSubject] def _transaction_is_active(self) -> bool: raise NotImplementedError() def _transaction_is_closed(self) -> bool: raise NotImplementedError() def _rollback_can_be_called(self) -> bool: """indicates the object is in a state that is known to be acceptable for rollback() to be called. This does not necessarily mean rollback() will succeed or not raise an error, just that there is currently no state detected that indicates rollback() would fail or emit warnings. It also does not mean that there's a transaction in progress, as it is usually safe to call rollback() even if no transaction is present. .. versionadded:: 1.4.28 """ raise NotImplementedError() def _get_subject(self) -> _TConsSubject: raise NotImplementedError() def commit(self) -> None: raise NotImplementedError() def rollback(self) -> None: raise NotImplementedError() def close(self) -> None: raise NotImplementedError() @classmethod def _trans_ctx_check(cls, subject: _TConsSubject) -> None: trans_context = subject._trans_context_manager if trans_context: if not trans_context._transaction_is_active(): raise exc.InvalidRequestError( "Can't operate on closed transaction inside context " "manager. Please complete the context manager " "before emitting further commands." ) def __enter__(self) -> Self: subject = self._get_subject() # none for outer transaction, may be non-None for nested # savepoint, legacy nesting cases trans_context = subject._trans_context_manager self._outer_trans_ctx = trans_context self._trans_subject = subject subject._trans_context_manager = self return self def __exit__(self, type_: Any, value: Any, traceback: Any) -> None: subject = getattr(self, "_trans_subject", None) # simplistically we could assume that # "subject._trans_context_manager is self". However, any calling # code that is manipulating __exit__ directly would break this # assumption. alembic context manager # is an example of partial use that just calls __exit__ and # not __enter__ at the moment. it's safe to assume this is being done # in the wild also out_of_band_exit = ( subject is None or subject._trans_context_manager is not self ) if type_ is None and self._transaction_is_active(): try: self.commit() except: with util.safe_reraise(): if self._rollback_can_be_called(): self.rollback() finally: if not out_of_band_exit: assert subject is not None subject._trans_context_manager = self._outer_trans_ctx self._trans_subject = self._outer_trans_ctx = None else: try: if not self._transaction_is_active(): if not self._transaction_is_closed(): self.close() else: if self._rollback_can_be_called(): self.rollback() finally: if not out_of_band_exit: assert subject is not None subject._trans_context_manager = self._outer_trans_ctx self._trans_subject = self._outer_trans_ctx = None sqlalchemy/engine/row.py 0000755 00000027377 15125143220 0011352 0 ustar 00 # engine/row.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """Define row constructs including :class:`.Row`.""" from __future__ import annotations from abc import ABC import collections.abc as collections_abc import operator import typing from typing import Any from typing import Callable from typing import Dict from typing import Generic from typing import Iterator from typing import List from typing import Mapping from typing import NoReturn from typing import Optional from typing import overload from typing import Sequence from typing import Tuple from typing import TYPE_CHECKING from typing import TypeVar from typing import Union from ..sql import util as sql_util from ..util import deprecated from ..util._has_cy import HAS_CYEXTENSION if TYPE_CHECKING or not HAS_CYEXTENSION: from ._py_row import BaseRow as BaseRow else: from sqlalchemy.cyextension.resultproxy import BaseRow as BaseRow if TYPE_CHECKING: from .result import _KeyType from .result import _ProcessorsType from .result import RMKeyView _T = TypeVar("_T", bound=Any) _TP = TypeVar("_TP", bound=Tuple[Any, ...]) class Row(BaseRow, Sequence[Any], Generic[_TP]): """Represent a single result row. The :class:`.Row` object represents a row of a database result. It is typically associated in the 1.x series of SQLAlchemy with the :class:`_engine.CursorResult` object, however is also used by the ORM for tuple-like results as of SQLAlchemy 1.4. The :class:`.Row` object seeks to act as much like a Python named tuple as possible. For mapping (i.e. dictionary) behavior on a row, such as testing for containment of keys, refer to the :attr:`.Row._mapping` attribute. .. seealso:: :ref:`tutorial_selecting_data` - includes examples of selecting rows from SELECT statements. .. versionchanged:: 1.4 Renamed ``RowProxy`` to :class:`.Row`. :class:`.Row` is no longer a "proxy" object in that it contains the final form of data within it, and now acts mostly like a named tuple. Mapping-like functionality is moved to the :attr:`.Row._mapping` attribute. See :ref:`change_4710_core` for background on this change. """ __slots__ = () def __setattr__(self, name: str, value: Any) -> NoReturn: raise AttributeError("can't set attribute") def __delattr__(self, name: str) -> NoReturn: raise AttributeError("can't delete attribute") def _tuple(self) -> _TP: """Return a 'tuple' form of this :class:`.Row`. At runtime, this method returns "self"; the :class:`.Row` object is already a named tuple. However, at the typing level, if this :class:`.Row` is typed, the "tuple" return type will be a :pep:`484` ``Tuple`` datatype that contains typing information about individual elements, supporting typed unpacking and attribute access. .. versionadded:: 2.0.19 - The :meth:`.Row._tuple` method supersedes the previous :meth:`.Row.tuple` method, which is now underscored to avoid name conflicts with column names in the same way as other named-tuple methods on :class:`.Row`. .. seealso:: :attr:`.Row._t` - shorthand attribute notation :meth:`.Result.tuples` """ return self # type: ignore @deprecated( "2.0.19", "The :meth:`.Row.tuple` method is deprecated in favor of " ":meth:`.Row._tuple`; all :class:`.Row` " "methods and library-level attributes are intended to be underscored " "to avoid name conflicts. Please use :meth:`Row._tuple`.", ) def tuple(self) -> _TP: """Return a 'tuple' form of this :class:`.Row`. .. versionadded:: 2.0 """ return self._tuple() @property def _t(self) -> _TP: """A synonym for :meth:`.Row._tuple`. .. versionadded:: 2.0.19 - The :attr:`.Row._t` attribute supersedes the previous :attr:`.Row.t` attribute, which is now underscored to avoid name conflicts with column names in the same way as other named-tuple methods on :class:`.Row`. .. seealso:: :attr:`.Result.t` """ return self # type: ignore @property @deprecated( "2.0.19", "The :attr:`.Row.t` attribute is deprecated in favor of " ":attr:`.Row._t`; all :class:`.Row` " "methods and library-level attributes are intended to be underscored " "to avoid name conflicts. Please use :attr:`Row._t`.", ) def t(self) -> _TP: """A synonym for :meth:`.Row._tuple`. .. versionadded:: 2.0 """ return self._t @property def _mapping(self) -> RowMapping: """Return a :class:`.RowMapping` for this :class:`.Row`. This object provides a consistent Python mapping (i.e. dictionary) interface for the data contained within the row. The :class:`.Row` by itself behaves like a named tuple. .. seealso:: :attr:`.Row._fields` .. versionadded:: 1.4 """ return RowMapping(self._parent, None, self._key_to_index, self._data) def _filter_on_values( self, processor: Optional[_ProcessorsType] ) -> Row[Any]: return Row(self._parent, processor, self._key_to_index, self._data) if not TYPE_CHECKING: def _special_name_accessor(name: str) -> Any: """Handle ambiguous names such as "count" and "index" """ @property def go(self: Row) -> Any: if self._parent._has_key(name): return self.__getattr__(name) else: def meth(*arg: Any, **kw: Any) -> Any: return getattr(collections_abc.Sequence, name)( self, *arg, **kw ) return meth return go count = _special_name_accessor("count") index = _special_name_accessor("index") def __contains__(self, key: Any) -> bool: return key in self._data def _op(self, other: Any, op: Callable[[Any, Any], bool]) -> bool: return ( op(self._to_tuple_instance(), other._to_tuple_instance()) if isinstance(other, Row) else op(self._to_tuple_instance(), other) ) __hash__ = BaseRow.__hash__ if TYPE_CHECKING: @overload def __getitem__(self, index: int) -> Any: ... @overload def __getitem__(self, index: slice) -> Sequence[Any]: ... def __getitem__(self, index: Union[int, slice]) -> Any: ... def __lt__(self, other: Any) -> bool: return self._op(other, operator.lt) def __le__(self, other: Any) -> bool: return self._op(other, operator.le) def __ge__(self, other: Any) -> bool: return self._op(other, operator.ge) def __gt__(self, other: Any) -> bool: return self._op(other, operator.gt) def __eq__(self, other: Any) -> bool: return self._op(other, operator.eq) def __ne__(self, other: Any) -> bool: return self._op(other, operator.ne) def __repr__(self) -> str: return repr(sql_util._repr_row(self)) @property def _fields(self) -> Tuple[str, ...]: """Return a tuple of string keys as represented by this :class:`.Row`. The keys can represent the labels of the columns returned by a core statement or the names of the orm classes returned by an orm execution. This attribute is analogous to the Python named tuple ``._fields`` attribute. .. versionadded:: 1.4 .. seealso:: :attr:`.Row._mapping` """ return tuple([k for k in self._parent.keys if k is not None]) def _asdict(self) -> Dict[str, Any]: """Return a new dict which maps field names to their corresponding values. This method is analogous to the Python named tuple ``._asdict()`` method, and works by applying the ``dict()`` constructor to the :attr:`.Row._mapping` attribute. .. versionadded:: 1.4 .. seealso:: :attr:`.Row._mapping` """ return dict(self._mapping) BaseRowProxy = BaseRow RowProxy = Row class ROMappingView(ABC): __slots__ = () _items: Sequence[Any] _mapping: Mapping["_KeyType", Any] def __init__( self, mapping: Mapping["_KeyType", Any], items: Sequence[Any] ): self._mapping = mapping # type: ignore[misc] self._items = items # type: ignore[misc] def __len__(self) -> int: return len(self._items) def __repr__(self) -> str: return "{0.__class__.__name__}({0._mapping!r})".format(self) def __iter__(self) -> Iterator[Any]: return iter(self._items) def __contains__(self, item: Any) -> bool: return item in self._items def __eq__(self, other: Any) -> bool: return list(other) == list(self) def __ne__(self, other: Any) -> bool: return list(other) != list(self) class ROMappingKeysValuesView( ROMappingView, typing.KeysView["_KeyType"], typing.ValuesView[Any] ): __slots__ = ("_items",) # mapping slot is provided by KeysView class ROMappingItemsView(ROMappingView, typing.ItemsView["_KeyType", Any]): __slots__ = ("_items",) # mapping slot is provided by ItemsView class RowMapping(BaseRow, typing.Mapping["_KeyType", Any]): """A ``Mapping`` that maps column names and objects to :class:`.Row` values. The :class:`.RowMapping` is available from a :class:`.Row` via the :attr:`.Row._mapping` attribute, as well as from the iterable interface provided by the :class:`.MappingResult` object returned by the :meth:`_engine.Result.mappings` method. :class:`.RowMapping` supplies Python mapping (i.e. dictionary) access to the contents of the row. This includes support for testing of containment of specific keys (string column names or objects), as well as iteration of keys, values, and items:: for row in result: if "a" in row._mapping: print("Column 'a': %s" % row._mapping["a"]) print("Column b: %s" % row._mapping[table.c.b]) .. versionadded:: 1.4 The :class:`.RowMapping` object replaces the mapping-like access previously provided by a database result row, which now seeks to behave mostly like a named tuple. """ __slots__ = () if TYPE_CHECKING: def __getitem__(self, key: _KeyType) -> Any: ... else: __getitem__ = BaseRow._get_by_key_impl_mapping def _values_impl(self) -> List[Any]: return list(self._data) def __iter__(self) -> Iterator[str]: return (k for k in self._parent.keys if k is not None) def __len__(self) -> int: return len(self._data) def __contains__(self, key: object) -> bool: return self._parent._has_key(key) def __repr__(self) -> str: return repr(dict(self)) def items(self) -> ROMappingItemsView: """Return a view of key/value tuples for the elements in the underlying :class:`.Row`. """ return ROMappingItemsView( self, [(key, self[key]) for key in self.keys()] ) def keys(self) -> RMKeyView: """Return a view of 'keys' for string column names represented by the underlying :class:`.Row`. """ return self._parent.keys def values(self) -> ROMappingKeysValuesView: """Return a view of values for the values represented in the underlying :class:`.Row`. """ return ROMappingKeysValuesView(self, self._values_impl()) sqlalchemy/engine/events.py 0000755 00000111030 15125143220 0012023 0 ustar 00 # engine/events.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php from __future__ import annotations import typing from typing import Any from typing import Dict from typing import Optional from typing import Tuple from typing import Type from typing import Union from .base import Connection from .base import Engine from .interfaces import ConnectionEventsTarget from .interfaces import DBAPIConnection from .interfaces import DBAPICursor from .interfaces import Dialect from .. import event from .. import exc from ..util.typing import Literal if typing.TYPE_CHECKING: from .interfaces import _CoreMultiExecuteParams from .interfaces import _CoreSingleExecuteParams from .interfaces import _DBAPIAnyExecuteParams from .interfaces import _DBAPIMultiExecuteParams from .interfaces import _DBAPISingleExecuteParams from .interfaces import _ExecuteOptions from .interfaces import ExceptionContext from .interfaces import ExecutionContext from .result import Result from ..pool import ConnectionPoolEntry from ..sql import Executable from ..sql.elements import BindParameter class ConnectionEvents(event.Events[ConnectionEventsTarget]): """Available events for :class:`_engine.Connection` and :class:`_engine.Engine`. The methods here define the name of an event as well as the names of members that are passed to listener functions. An event listener can be associated with any :class:`_engine.Connection` or :class:`_engine.Engine` class or instance, such as an :class:`_engine.Engine`, e.g.:: from sqlalchemy import event, create_engine def before_cursor_execute( conn, cursor, statement, parameters, context, executemany ): log.info("Received statement: %s", statement) engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test") event.listen(engine, "before_cursor_execute", before_cursor_execute) or with a specific :class:`_engine.Connection`:: with engine.begin() as conn: @event.listens_for(conn, "before_cursor_execute") def before_cursor_execute( conn, cursor, statement, parameters, context, executemany ): log.info("Received statement: %s", statement) When the methods are called with a `statement` parameter, such as in :meth:`.after_cursor_execute` or :meth:`.before_cursor_execute`, the statement is the exact SQL string that was prepared for transmission to the DBAPI ``cursor`` in the connection's :class:`.Dialect`. The :meth:`.before_execute` and :meth:`.before_cursor_execute` events can also be established with the ``retval=True`` flag, which allows modification of the statement and parameters to be sent to the database. The :meth:`.before_cursor_execute` event is particularly useful here to add ad-hoc string transformations, such as comments, to all executions:: from sqlalchemy.engine import Engine from sqlalchemy import event @event.listens_for(Engine, "before_cursor_execute", retval=True) def comment_sql_calls( conn, cursor, statement, parameters, context, executemany ): statement = statement + " -- some comment" return statement, parameters .. note:: :class:`_events.ConnectionEvents` can be established on any combination of :class:`_engine.Engine`, :class:`_engine.Connection`, as well as instances of each of those classes. Events across all four scopes will fire off for a given instance of :class:`_engine.Connection`. However, for performance reasons, the :class:`_engine.Connection` object determines at instantiation time whether or not its parent :class:`_engine.Engine` has event listeners established. Event listeners added to the :class:`_engine.Engine` class or to an instance of :class:`_engine.Engine` *after* the instantiation of a dependent :class:`_engine.Connection` instance will usually *not* be available on that :class:`_engine.Connection` instance. The newly added listeners will instead take effect for :class:`_engine.Connection` instances created subsequent to those event listeners being established on the parent :class:`_engine.Engine` class or instance. :param retval=False: Applies to the :meth:`.before_execute` and :meth:`.before_cursor_execute` events only. When True, the user-defined event function must have a return value, which is a tuple of parameters that replace the given statement and parameters. See those methods for a description of specific return arguments. """ # noqa _target_class_doc = "SomeEngine" _dispatch_target = ConnectionEventsTarget @classmethod def _accept_with( cls, target: Union[ConnectionEventsTarget, Type[ConnectionEventsTarget]], identifier: str, ) -> Optional[Union[ConnectionEventsTarget, Type[ConnectionEventsTarget]]]: default_dispatch = super()._accept_with(target, identifier) if default_dispatch is None and hasattr( target, "_no_async_engine_events" ): target._no_async_engine_events() return default_dispatch @classmethod def _listen( cls, event_key: event._EventKey[ConnectionEventsTarget], *, retval: bool = False, **kw: Any, ) -> None: target, identifier, fn = ( event_key.dispatch_target, event_key.identifier, event_key._listen_fn, ) target._has_events = True if not retval: if identifier == "before_execute": orig_fn = fn def wrap_before_execute( # type: ignore conn, clauseelement, multiparams, params, execution_options ): orig_fn( conn, clauseelement, multiparams, params, execution_options, ) return clauseelement, multiparams, params fn = wrap_before_execute elif identifier == "before_cursor_execute": orig_fn = fn def wrap_before_cursor_execute( # type: ignore conn, cursor, statement, parameters, context, executemany ): orig_fn( conn, cursor, statement, parameters, context, executemany, ) return statement, parameters fn = wrap_before_cursor_execute elif retval and identifier not in ( "before_execute", "before_cursor_execute", ): raise exc.ArgumentError( "Only the 'before_execute', " "'before_cursor_execute' and 'handle_error' engine " "event listeners accept the 'retval=True' " "argument." ) event_key.with_wrapper(fn).base_listen() @event._legacy_signature( "1.4", ["conn", "clauseelement", "multiparams", "params"], lambda conn, clauseelement, multiparams, params, execution_options: ( conn, clauseelement, multiparams, params, ), ) def before_execute( self, conn: Connection, clauseelement: Executable, multiparams: _CoreMultiExecuteParams, params: _CoreSingleExecuteParams, execution_options: _ExecuteOptions, ) -> Optional[ Tuple[Executable, _CoreMultiExecuteParams, _CoreSingleExecuteParams] ]: """Intercept high level execute() events, receiving uncompiled SQL constructs and other objects prior to rendering into SQL. This event is good for debugging SQL compilation issues as well as early manipulation of the parameters being sent to the database, as the parameter lists will be in a consistent format here. This event can be optionally established with the ``retval=True`` flag. The ``clauseelement``, ``multiparams``, and ``params`` arguments should be returned as a three-tuple in this case:: @event.listens_for(Engine, "before_execute", retval=True) def before_execute(conn, clauseelement, multiparams, params): # do something with clauseelement, multiparams, params return clauseelement, multiparams, params :param conn: :class:`_engine.Connection` object :param clauseelement: SQL expression construct, :class:`.Compiled` instance, or string statement passed to :meth:`_engine.Connection.execute`. :param multiparams: Multiple parameter sets, a list of dictionaries. :param params: Single parameter set, a single dictionary. :param execution_options: dictionary of execution options passed along with the statement, if any. This is a merge of all options that will be used, including those of the statement, the connection, and those passed in to the method itself for the 2.0 style of execution. .. versionadded: 1.4 .. seealso:: :meth:`.before_cursor_execute` """ @event._legacy_signature( "1.4", ["conn", "clauseelement", "multiparams", "params", "result"], lambda conn, clauseelement, multiparams, params, execution_options, result: ( # noqa conn, clauseelement, multiparams, params, result, ), ) def after_execute( self, conn: Connection, clauseelement: Executable, multiparams: _CoreMultiExecuteParams, params: _CoreSingleExecuteParams, execution_options: _ExecuteOptions, result: Result[Any], ) -> None: """Intercept high level execute() events after execute. :param conn: :class:`_engine.Connection` object :param clauseelement: SQL expression construct, :class:`.Compiled` instance, or string statement passed to :meth:`_engine.Connection.execute`. :param multiparams: Multiple parameter sets, a list of dictionaries. :param params: Single parameter set, a single dictionary. :param execution_options: dictionary of execution options passed along with the statement, if any. This is a merge of all options that will be used, including those of the statement, the connection, and those passed in to the method itself for the 2.0 style of execution. .. versionadded: 1.4 :param result: :class:`_engine.CursorResult` generated by the execution. """ def before_cursor_execute( self, conn: Connection, cursor: DBAPICursor, statement: str, parameters: _DBAPIAnyExecuteParams, context: Optional[ExecutionContext], executemany: bool, ) -> Optional[Tuple[str, _DBAPIAnyExecuteParams]]: """Intercept low-level cursor execute() events before execution, receiving the string SQL statement and DBAPI-specific parameter list to be invoked against a cursor. This event is a good choice for logging as well as late modifications to the SQL string. It's less ideal for parameter modifications except for those which are specific to a target backend. This event can be optionally established with the ``retval=True`` flag. The ``statement`` and ``parameters`` arguments should be returned as a two-tuple in this case:: @event.listens_for(Engine, "before_cursor_execute", retval=True) def before_cursor_execute( conn, cursor, statement, parameters, context, executemany ): # do something with statement, parameters return statement, parameters See the example at :class:`_events.ConnectionEvents`. :param conn: :class:`_engine.Connection` object :param cursor: DBAPI cursor object :param statement: string SQL statement, as to be passed to the DBAPI :param parameters: Dictionary, tuple, or list of parameters being passed to the ``execute()`` or ``executemany()`` method of the DBAPI ``cursor``. In some cases may be ``None``. :param context: :class:`.ExecutionContext` object in use. May be ``None``. :param executemany: boolean, if ``True``, this is an ``executemany()`` call, if ``False``, this is an ``execute()`` call. .. seealso:: :meth:`.before_execute` :meth:`.after_cursor_execute` """ def after_cursor_execute( self, conn: Connection, cursor: DBAPICursor, statement: str, parameters: _DBAPIAnyExecuteParams, context: Optional[ExecutionContext], executemany: bool, ) -> None: """Intercept low-level cursor execute() events after execution. :param conn: :class:`_engine.Connection` object :param cursor: DBAPI cursor object. Will have results pending if the statement was a SELECT, but these should not be consumed as they will be needed by the :class:`_engine.CursorResult`. :param statement: string SQL statement, as passed to the DBAPI :param parameters: Dictionary, tuple, or list of parameters being passed to the ``execute()`` or ``executemany()`` method of the DBAPI ``cursor``. In some cases may be ``None``. :param context: :class:`.ExecutionContext` object in use. May be ``None``. :param executemany: boolean, if ``True``, this is an ``executemany()`` call, if ``False``, this is an ``execute()`` call. """ @event._legacy_signature( "2.0", ["conn", "branch"], converter=lambda conn: (conn, False) ) def engine_connect(self, conn: Connection) -> None: """Intercept the creation of a new :class:`_engine.Connection`. This event is called typically as the direct result of calling the :meth:`_engine.Engine.connect` method. It differs from the :meth:`_events.PoolEvents.connect` method, which refers to the actual connection to a database at the DBAPI level; a DBAPI connection may be pooled and reused for many operations. In contrast, this event refers only to the production of a higher level :class:`_engine.Connection` wrapper around such a DBAPI connection. It also differs from the :meth:`_events.PoolEvents.checkout` event in that it is specific to the :class:`_engine.Connection` object, not the DBAPI connection that :meth:`_events.PoolEvents.checkout` deals with, although this DBAPI connection is available here via the :attr:`_engine.Connection.connection` attribute. But note there can in fact be multiple :meth:`_events.PoolEvents.checkout` events within the lifespan of a single :class:`_engine.Connection` object, if that :class:`_engine.Connection` is invalidated and re-established. :param conn: :class:`_engine.Connection` object. .. seealso:: :meth:`_events.PoolEvents.checkout` the lower-level pool checkout event for an individual DBAPI connection """ def set_connection_execution_options( self, conn: Connection, opts: Dict[str, Any] ) -> None: """Intercept when the :meth:`_engine.Connection.execution_options` method is called. This method is called after the new :class:`_engine.Connection` has been produced, with the newly updated execution options collection, but before the :class:`.Dialect` has acted upon any of those new options. Note that this method is not called when a new :class:`_engine.Connection` is produced which is inheriting execution options from its parent :class:`_engine.Engine`; to intercept this condition, use the :meth:`_events.ConnectionEvents.engine_connect` event. :param conn: The newly copied :class:`_engine.Connection` object :param opts: dictionary of options that were passed to the :meth:`_engine.Connection.execution_options` method. This dictionary may be modified in place to affect the ultimate options which take effect. .. versionadded:: 2.0 the ``opts`` dictionary may be modified in place. .. seealso:: :meth:`_events.ConnectionEvents.set_engine_execution_options` - event which is called when :meth:`_engine.Engine.execution_options` is called. """ def set_engine_execution_options( self, engine: Engine, opts: Dict[str, Any] ) -> None: """Intercept when the :meth:`_engine.Engine.execution_options` method is called. The :meth:`_engine.Engine.execution_options` method produces a shallow copy of the :class:`_engine.Engine` which stores the new options. That new :class:`_engine.Engine` is passed here. A particular application of this method is to add a :meth:`_events.ConnectionEvents.engine_connect` event handler to the given :class:`_engine.Engine` which will perform some per- :class:`_engine.Connection` task specific to these execution options. :param conn: The newly copied :class:`_engine.Engine` object :param opts: dictionary of options that were passed to the :meth:`_engine.Connection.execution_options` method. This dictionary may be modified in place to affect the ultimate options which take effect. .. versionadded:: 2.0 the ``opts`` dictionary may be modified in place. .. seealso:: :meth:`_events.ConnectionEvents.set_connection_execution_options` - event which is called when :meth:`_engine.Connection.execution_options` is called. """ def engine_disposed(self, engine: Engine) -> None: """Intercept when the :meth:`_engine.Engine.dispose` method is called. The :meth:`_engine.Engine.dispose` method instructs the engine to "dispose" of it's connection pool (e.g. :class:`_pool.Pool`), and replaces it with a new one. Disposing of the old pool has the effect that existing checked-in connections are closed. The new pool does not establish any new connections until it is first used. This event can be used to indicate that resources related to the :class:`_engine.Engine` should also be cleaned up, keeping in mind that the :class:`_engine.Engine` can still be used for new requests in which case it re-acquires connection resources. """ def begin(self, conn: Connection) -> None: """Intercept begin() events. :param conn: :class:`_engine.Connection` object """ def rollback(self, conn: Connection) -> None: """Intercept rollback() events, as initiated by a :class:`.Transaction`. Note that the :class:`_pool.Pool` also "auto-rolls back" a DBAPI connection upon checkin, if the ``reset_on_return`` flag is set to its default value of ``'rollback'``. To intercept this rollback, use the :meth:`_events.PoolEvents.reset` hook. :param conn: :class:`_engine.Connection` object .. seealso:: :meth:`_events.PoolEvents.reset` """ def commit(self, conn: Connection) -> None: """Intercept commit() events, as initiated by a :class:`.Transaction`. Note that the :class:`_pool.Pool` may also "auto-commit" a DBAPI connection upon checkin, if the ``reset_on_return`` flag is set to the value ``'commit'``. To intercept this commit, use the :meth:`_events.PoolEvents.reset` hook. :param conn: :class:`_engine.Connection` object """ def savepoint(self, conn: Connection, name: str) -> None: """Intercept savepoint() events. :param conn: :class:`_engine.Connection` object :param name: specified name used for the savepoint. """ def rollback_savepoint( self, conn: Connection, name: str, context: None ) -> None: """Intercept rollback_savepoint() events. :param conn: :class:`_engine.Connection` object :param name: specified name used for the savepoint. :param context: not used """ # TODO: deprecate "context" def release_savepoint( self, conn: Connection, name: str, context: None ) -> None: """Intercept release_savepoint() events. :param conn: :class:`_engine.Connection` object :param name: specified name used for the savepoint. :param context: not used """ # TODO: deprecate "context" def begin_twophase(self, conn: Connection, xid: Any) -> None: """Intercept begin_twophase() events. :param conn: :class:`_engine.Connection` object :param xid: two-phase XID identifier """ def prepare_twophase(self, conn: Connection, xid: Any) -> None: """Intercept prepare_twophase() events. :param conn: :class:`_engine.Connection` object :param xid: two-phase XID identifier """ def rollback_twophase( self, conn: Connection, xid: Any, is_prepared: bool ) -> None: """Intercept rollback_twophase() events. :param conn: :class:`_engine.Connection` object :param xid: two-phase XID identifier :param is_prepared: boolean, indicates if :meth:`.TwoPhaseTransaction.prepare` was called. """ def commit_twophase( self, conn: Connection, xid: Any, is_prepared: bool ) -> None: """Intercept commit_twophase() events. :param conn: :class:`_engine.Connection` object :param xid: two-phase XID identifier :param is_prepared: boolean, indicates if :meth:`.TwoPhaseTransaction.prepare` was called. """ class DialectEvents(event.Events[Dialect]): """event interface for execution-replacement functions. These events allow direct instrumentation and replacement of key dialect functions which interact with the DBAPI. .. note:: :class:`.DialectEvents` hooks should be considered **semi-public** and experimental. These hooks are not for general use and are only for those situations where intricate re-statement of DBAPI mechanics must be injected onto an existing dialect. For general-use statement-interception events, please use the :class:`_events.ConnectionEvents` interface. .. seealso:: :meth:`_events.ConnectionEvents.before_cursor_execute` :meth:`_events.ConnectionEvents.before_execute` :meth:`_events.ConnectionEvents.after_cursor_execute` :meth:`_events.ConnectionEvents.after_execute` """ _target_class_doc = "SomeEngine" _dispatch_target = Dialect @classmethod def _listen( cls, event_key: event._EventKey[Dialect], *, retval: bool = False, **kw: Any, ) -> None: target = event_key.dispatch_target target._has_events = True event_key.base_listen() @classmethod def _accept_with( cls, target: Union[Engine, Type[Engine], Dialect, Type[Dialect]], identifier: str, ) -> Optional[Union[Dialect, Type[Dialect]]]: if isinstance(target, type): if issubclass(target, Engine): return Dialect elif issubclass(target, Dialect): return target elif isinstance(target, Engine): return target.dialect elif isinstance(target, Dialect): return target elif isinstance(target, Connection) and identifier == "handle_error": raise exc.InvalidRequestError( "The handle_error() event hook as of SQLAlchemy 2.0 is " "established on the Dialect, and may only be applied to the " "Engine as a whole or to a specific Dialect as a whole, " "not on a per-Connection basis." ) elif hasattr(target, "_no_async_engine_events"): target._no_async_engine_events() else: return None def handle_error( self, exception_context: ExceptionContext ) -> Optional[BaseException]: r"""Intercept all exceptions processed by the :class:`_engine.Dialect`, typically but not limited to those emitted within the scope of a :class:`_engine.Connection`. .. versionchanged:: 2.0 the :meth:`.DialectEvents.handle_error` event is moved to the :class:`.DialectEvents` class, moved from the :class:`.ConnectionEvents` class, so that it may also participate in the "pre ping" operation configured with the :paramref:`_sa.create_engine.pool_pre_ping` parameter. The event remains registered by using the :class:`_engine.Engine` as the event target, however note that using the :class:`_engine.Connection` as an event target for :meth:`.DialectEvents.handle_error` is no longer supported. This includes all exceptions emitted by the DBAPI as well as within SQLAlchemy's statement invocation process, including encoding errors and other statement validation errors. Other areas in which the event is invoked include transaction begin and end, result row fetching, cursor creation. Note that :meth:`.handle_error` may support new kinds of exceptions and new calling scenarios at *any time*. Code which uses this event must expect new calling patterns to be present in minor releases. To support the wide variety of members that correspond to an exception, as well as to allow extensibility of the event without backwards incompatibility, the sole argument received is an instance of :class:`.ExceptionContext`. This object contains data members representing detail about the exception. Use cases supported by this hook include: * read-only, low-level exception handling for logging and debugging purposes * Establishing whether a DBAPI connection error message indicates that the database connection needs to be reconnected, including for the "pre_ping" handler used by **some** dialects * Establishing or disabling whether a connection or the owning connection pool is invalidated or expired in response to a specific exception * exception re-writing The hook is called while the cursor from the failed operation (if any) is still open and accessible. Special cleanup operations can be called on this cursor; SQLAlchemy will attempt to close this cursor subsequent to this hook being invoked. As of SQLAlchemy 2.0, the "pre_ping" handler enabled using the :paramref:`_sa.create_engine.pool_pre_ping` parameter will also participate in the :meth:`.handle_error` process, **for those dialects that rely upon disconnect codes to detect database liveness**. Note that some dialects such as psycopg, psycopg2, and most MySQL dialects make use of a native ``ping()`` method supplied by the DBAPI which does not make use of disconnect codes. .. versionchanged:: 2.0.0 The :meth:`.DialectEvents.handle_error` event hook participates in connection pool "pre-ping" operations. Within this usage, the :attr:`.ExceptionContext.engine` attribute will be ``None``, however the :class:`.Dialect` in use is always available via the :attr:`.ExceptionContext.dialect` attribute. .. versionchanged:: 2.0.5 Added :attr:`.ExceptionContext.is_pre_ping` attribute which will be set to ``True`` when the :meth:`.DialectEvents.handle_error` event hook is triggered within a connection pool pre-ping operation. .. versionchanged:: 2.0.5 An issue was repaired that allows for the PostgreSQL ``psycopg`` and ``psycopg2`` drivers, as well as all MySQL drivers, to properly participate in the :meth:`.DialectEvents.handle_error` event hook during connection pool "pre-ping" operations; previously, the implementation was non-working for these drivers. A handler function has two options for replacing the SQLAlchemy-constructed exception into one that is user defined. It can either raise this new exception directly, in which case all further event listeners are bypassed and the exception will be raised, after appropriate cleanup as taken place:: @event.listens_for(Engine, "handle_error") def handle_exception(context): if isinstance( context.original_exception, psycopg2.OperationalError ) and "failed" in str(context.original_exception): raise MySpecialException("failed operation") .. warning:: Because the :meth:`_events.DialectEvents.handle_error` event specifically provides for exceptions to be re-thrown as the ultimate exception raised by the failed statement, **stack traces will be misleading** if the user-defined event handler itself fails and throws an unexpected exception; the stack trace may not illustrate the actual code line that failed! It is advised to code carefully here and use logging and/or inline debugging if unexpected exceptions are occurring. Alternatively, a "chained" style of event handling can be used, by configuring the handler with the ``retval=True`` modifier and returning the new exception instance from the function. In this case, event handling will continue onto the next handler. The "chained" exception is available using :attr:`.ExceptionContext.chained_exception`:: @event.listens_for(Engine, "handle_error", retval=True) def handle_exception(context): if ( context.chained_exception is not None and "special" in context.chained_exception.message ): return MySpecialException( "failed", cause=context.chained_exception ) Handlers that return ``None`` may be used within the chain; when a handler returns ``None``, the previous exception instance, if any, is maintained as the current exception that is passed onto the next handler. When a custom exception is raised or returned, SQLAlchemy raises this new exception as-is, it is not wrapped by any SQLAlchemy object. If the exception is not a subclass of :class:`sqlalchemy.exc.StatementError`, certain features may not be available; currently this includes the ORM's feature of adding a detail hint about "autoflush" to exceptions raised within the autoflush process. :param context: an :class:`.ExceptionContext` object. See this class for details on all available members. .. seealso:: :ref:`pool_new_disconnect_codes` """ def do_connect( self, dialect: Dialect, conn_rec: ConnectionPoolEntry, cargs: Tuple[Any, ...], cparams: Dict[str, Any], ) -> Optional[DBAPIConnection]: """Receive connection arguments before a connection is made. This event is useful in that it allows the handler to manipulate the cargs and/or cparams collections that control how the DBAPI ``connect()`` function will be called. ``cargs`` will always be a Python list that can be mutated in-place, and ``cparams`` a Python dictionary that may also be mutated:: e = create_engine("postgresql+psycopg2://user@host/dbname") @event.listens_for(e, "do_connect") def receive_do_connect(dialect, conn_rec, cargs, cparams): cparams["password"] = "some_password" The event hook may also be used to override the call to ``connect()`` entirely, by returning a non-``None`` DBAPI connection object:: e = create_engine("postgresql+psycopg2://user@host/dbname") @event.listens_for(e, "do_connect") def receive_do_connect(dialect, conn_rec, cargs, cparams): return psycopg2.connect(*cargs, **cparams) .. seealso:: :ref:`custom_dbapi_args` """ def do_executemany( self, cursor: DBAPICursor, statement: str, parameters: _DBAPIMultiExecuteParams, context: ExecutionContext, ) -> Optional[Literal[True]]: """Receive a cursor to have executemany() called. Return the value True to halt further events from invoking, and to indicate that the cursor execution has already taken place within the event handler. """ def do_execute_no_params( self, cursor: DBAPICursor, statement: str, context: ExecutionContext ) -> Optional[Literal[True]]: """Receive a cursor to have execute() with no parameters called. Return the value True to halt further events from invoking, and to indicate that the cursor execution has already taken place within the event handler. """ def do_execute( self, cursor: DBAPICursor, statement: str, parameters: _DBAPISingleExecuteParams, context: ExecutionContext, ) -> Optional[Literal[True]]: """Receive a cursor to have execute() called. Return the value True to halt further events from invoking, and to indicate that the cursor execution has already taken place within the event handler. """ def do_setinputsizes( self, inputsizes: Dict[BindParameter[Any], Any], cursor: DBAPICursor, statement: str, parameters: _DBAPIAnyExecuteParams, context: ExecutionContext, ) -> None: """Receive the setinputsizes dictionary for possible modification. This event is emitted in the case where the dialect makes use of the DBAPI ``cursor.setinputsizes()`` method which passes information about parameter binding for a particular statement. The given ``inputsizes`` dictionary will contain :class:`.BindParameter` objects as keys, linked to DBAPI-specific type objects as values; for parameters that are not bound, they are added to the dictionary with ``None`` as the value, which means the parameter will not be included in the ultimate setinputsizes call. The event may be used to inspect and/or log the datatypes that are being bound, as well as to modify the dictionary in place. Parameters can be added, modified, or removed from this dictionary. Callers will typically want to inspect the :attr:`.BindParameter.type` attribute of the given bind objects in order to make decisions about the DBAPI object. After the event, the ``inputsizes`` dictionary is converted into an appropriate datastructure to be passed to ``cursor.setinputsizes``; either a list for a positional bound parameter execution style, or a dictionary of string parameter keys to DBAPI type objects for a named bound parameter execution style. The setinputsizes hook overall is only used for dialects which include the flag ``use_setinputsizes=True``. Dialects which use this include python-oracledb, cx_Oracle, pg8000, asyncpg, and pyodbc dialects. .. note:: For use with pyodbc, the ``use_setinputsizes`` flag must be passed to the dialect, e.g.:: create_engine("mssql+pyodbc://...", use_setinputsizes=True) .. seealso:: :ref:`mssql_pyodbc_setinputsizes` .. versionadded:: 1.2.9 .. seealso:: :ref:`cx_oracle_setinputsizes` """ pass sqlalchemy/engine/reflection.py 0000755 00000223455 15125143220 0012670 0 ustar 00 # engine/reflection.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """Provides an abstraction for obtaining database schema information. Usage Notes: Here are some general conventions when accessing the low level inspector methods such as get_table_names, get_columns, etc. 1. Inspector methods return lists of dicts in most cases for the following reasons: * They're both standard types that can be serialized. * Using a dict instead of a tuple allows easy expansion of attributes. * Using a list for the outer structure maintains order and is easy to work with (e.g. list comprehension [d['name'] for d in cols]). 2. Records that contain a name, such as the column name in a column record use the key 'name'. So for most return values, each record will have a 'name' attribute.. """ from __future__ import annotations import contextlib from dataclasses import dataclass from enum import auto from enum import Flag from enum import unique from typing import Any from typing import Callable from typing import Collection from typing import Dict from typing import Generator from typing import Iterable from typing import List from typing import Optional from typing import Sequence from typing import Set from typing import Tuple from typing import TYPE_CHECKING from typing import TypeVar from typing import Union from .base import Connection from .base import Engine from .. import exc from .. import inspection from .. import sql from .. import util from ..sql import operators from ..sql import schema as sa_schema from ..sql.cache_key import _ad_hoc_cache_key_from_args from ..sql.elements import quoted_name from ..sql.elements import TextClause from ..sql.type_api import TypeEngine from ..sql.visitors import InternalTraversal from ..util import topological from ..util.typing import final if TYPE_CHECKING: from .interfaces import Dialect from .interfaces import ReflectedCheckConstraint from .interfaces import ReflectedColumn from .interfaces import ReflectedForeignKeyConstraint from .interfaces import ReflectedIndex from .interfaces import ReflectedPrimaryKeyConstraint from .interfaces import ReflectedTableComment from .interfaces import ReflectedUniqueConstraint from .interfaces import TableKey _R = TypeVar("_R") @util.decorator def cache( fn: Callable[..., _R], self: Dialect, con: Connection, *args: Any, **kw: Any, ) -> _R: info_cache = kw.get("info_cache", None) if info_cache is None: return fn(self, con, *args, **kw) exclude = {"info_cache", "unreflectable"} key = ( fn.__name__, tuple( (str(a), a.quote) if isinstance(a, quoted_name) else a for a in args if isinstance(a, str) ), tuple( (k, (str(v), v.quote) if isinstance(v, quoted_name) else v) for k, v in kw.items() if k not in exclude ), ) ret: _R = info_cache.get(key) if ret is None: ret = fn(self, con, *args, **kw) info_cache[key] = ret return ret def flexi_cache( *traverse_args: Tuple[str, InternalTraversal] ) -> Callable[[Callable[..., _R]], Callable[..., _R]]: @util.decorator def go( fn: Callable[..., _R], self: Dialect, con: Connection, *args: Any, **kw: Any, ) -> _R: info_cache = kw.get("info_cache", None) if info_cache is None: return fn(self, con, *args, **kw) key = _ad_hoc_cache_key_from_args((fn.__name__,), traverse_args, args) ret: _R = info_cache.get(key) if ret is None: ret = fn(self, con, *args, **kw) info_cache[key] = ret return ret return go @unique class ObjectKind(Flag): """Enumerator that indicates which kind of object to return when calling the ``get_multi`` methods. This is a Flag enum, so custom combinations can be passed. For example, to reflect tables and plain views ``ObjectKind.TABLE | ObjectKind.VIEW`` may be used. .. note:: Not all dialect may support all kind of object. If a dialect does not support a particular object an empty dict is returned. In case a dialect supports an object, but the requested method is not applicable for the specified kind the default value will be returned for each reflected object. For example reflecting check constraints of view return a dict with all the views with empty lists as values. """ TABLE = auto() "Reflect table objects" VIEW = auto() "Reflect plain view objects" MATERIALIZED_VIEW = auto() "Reflect materialized view object" ANY_VIEW = VIEW | MATERIALIZED_VIEW "Reflect any kind of view objects" ANY = TABLE | VIEW | MATERIALIZED_VIEW "Reflect all type of objects" @unique class ObjectScope(Flag): """Enumerator that indicates which scope to use when calling the ``get_multi`` methods. """ DEFAULT = auto() "Include default scope" TEMPORARY = auto() "Include only temp scope" ANY = DEFAULT | TEMPORARY "Include both default and temp scope" @inspection._self_inspects class Inspector(inspection.Inspectable["Inspector"]): """Performs database schema inspection. The Inspector acts as a proxy to the reflection methods of the :class:`~sqlalchemy.engine.interfaces.Dialect`, providing a consistent interface as well as caching support for previously fetched metadata. A :class:`_reflection.Inspector` object is usually created via the :func:`_sa.inspect` function, which may be passed an :class:`_engine.Engine` or a :class:`_engine.Connection`:: from sqlalchemy import inspect, create_engine engine = create_engine("...") insp = inspect(engine) Where above, the :class:`~sqlalchemy.engine.interfaces.Dialect` associated with the engine may opt to return an :class:`_reflection.Inspector` subclass that provides additional methods specific to the dialect's target database. """ bind: Union[Engine, Connection] engine: Engine _op_context_requires_connect: bool dialect: Dialect info_cache: Dict[Any, Any] @util.deprecated( "1.4", "The __init__() method on :class:`_reflection.Inspector` " "is deprecated and " "will be removed in a future release. Please use the " ":func:`.sqlalchemy.inspect` " "function on an :class:`_engine.Engine` or " ":class:`_engine.Connection` " "in order to " "acquire an :class:`_reflection.Inspector`.", ) def __init__(self, bind: Union[Engine, Connection]): """Initialize a new :class:`_reflection.Inspector`. :param bind: a :class:`~sqlalchemy.engine.Connection`, which is typically an instance of :class:`~sqlalchemy.engine.Engine` or :class:`~sqlalchemy.engine.Connection`. For a dialect-specific instance of :class:`_reflection.Inspector`, see :meth:`_reflection.Inspector.from_engine` """ self._init_legacy(bind) @classmethod def _construct( cls, init: Callable[..., Any], bind: Union[Engine, Connection] ) -> Inspector: if hasattr(bind.dialect, "inspector"): cls = bind.dialect.inspector self = cls.__new__(cls) init(self, bind) return self def _init_legacy(self, bind: Union[Engine, Connection]) -> None: if hasattr(bind, "exec_driver_sql"): self._init_connection(bind) # type: ignore[arg-type] else: self._init_engine(bind) def _init_engine(self, engine: Engine) -> None: self.bind = self.engine = engine engine.connect().close() self._op_context_requires_connect = True self.dialect = self.engine.dialect self.info_cache = {} def _init_connection(self, connection: Connection) -> None: self.bind = connection self.engine = connection.engine self._op_context_requires_connect = False self.dialect = self.engine.dialect self.info_cache = {} def clear_cache(self) -> None: """reset the cache for this :class:`.Inspector`. Inspection methods that have data cached will emit SQL queries when next called to get new data. .. versionadded:: 2.0 """ self.info_cache.clear() @classmethod @util.deprecated( "1.4", "The from_engine() method on :class:`_reflection.Inspector` " "is deprecated and " "will be removed in a future release. Please use the " ":func:`.sqlalchemy.inspect` " "function on an :class:`_engine.Engine` or " ":class:`_engine.Connection` " "in order to " "acquire an :class:`_reflection.Inspector`.", ) def from_engine(cls, bind: Engine) -> Inspector: """Construct a new dialect-specific Inspector object from the given engine or connection. :param bind: a :class:`~sqlalchemy.engine.Connection` or :class:`~sqlalchemy.engine.Engine`. This method differs from direct a direct constructor call of :class:`_reflection.Inspector` in that the :class:`~sqlalchemy.engine.interfaces.Dialect` is given a chance to provide a dialect-specific :class:`_reflection.Inspector` instance, which may provide additional methods. See the example at :class:`_reflection.Inspector`. """ return cls._construct(cls._init_legacy, bind) @inspection._inspects(Engine) def _engine_insp(bind: Engine) -> Inspector: # type: ignore[misc] return Inspector._construct(Inspector._init_engine, bind) @inspection._inspects(Connection) def _connection_insp(bind: Connection) -> Inspector: # type: ignore[misc] return Inspector._construct(Inspector._init_connection, bind) @contextlib.contextmanager def _operation_context(self) -> Generator[Connection, None, None]: """Return a context that optimizes for multiple operations on a single transaction. This essentially allows connect()/close() to be called if we detected that we're against an :class:`_engine.Engine` and not a :class:`_engine.Connection`. """ conn: Connection if self._op_context_requires_connect: conn = self.bind.connect() # type: ignore[union-attr] else: conn = self.bind # type: ignore[assignment] try: yield conn finally: if self._op_context_requires_connect: conn.close() @contextlib.contextmanager def _inspection_context(self) -> Generator[Inspector, None, None]: """Return an :class:`_reflection.Inspector` from this one that will run all operations on a single connection. """ with self._operation_context() as conn: sub_insp = self._construct(self.__class__._init_connection, conn) sub_insp.info_cache = self.info_cache yield sub_insp @property def default_schema_name(self) -> Optional[str]: """Return the default schema name presented by the dialect for the current engine's database user. E.g. this is typically ``public`` for PostgreSQL and ``dbo`` for SQL Server. """ return self.dialect.default_schema_name def get_schema_names(self, **kw: Any) -> List[str]: r"""Return all schema names. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. """ with self._operation_context() as conn: return self.dialect.get_schema_names( conn, info_cache=self.info_cache, **kw ) def get_table_names( self, schema: Optional[str] = None, **kw: Any ) -> List[str]: r"""Return all table names within a particular schema. The names are expected to be real tables only, not views. Views are instead returned using the :meth:`_reflection.Inspector.get_view_names` and/or :meth:`_reflection.Inspector.get_materialized_view_names` methods. :param schema: Schema name. If ``schema`` is left at ``None``, the database's default schema is used, else the named schema is searched. If the database does not support named schemas, behavior is undefined if ``schema`` is not passed as ``None``. For special quoting, use :class:`.quoted_name`. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. .. seealso:: :meth:`_reflection.Inspector.get_sorted_table_and_fkc_names` :attr:`_schema.MetaData.sorted_tables` """ with self._operation_context() as conn: return self.dialect.get_table_names( conn, schema, info_cache=self.info_cache, **kw ) def has_table( self, table_name: str, schema: Optional[str] = None, **kw: Any ) -> bool: r"""Return True if the backend has a table, view, or temporary table of the given name. :param table_name: name of the table to check :param schema: schema name to query, if not the default schema. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. .. versionadded:: 1.4 - the :meth:`.Inspector.has_table` method replaces the :meth:`_engine.Engine.has_table` method. .. versionchanged:: 2.0:: :meth:`.Inspector.has_table` now formally supports checking for additional table-like objects: * any type of views (plain or materialized) * temporary tables of any kind Previously, these two checks were not formally specified and different dialects would vary in their behavior. The dialect testing suite now includes tests for all of these object types and should be supported by all SQLAlchemy-included dialects. Support among third party dialects may be lagging, however. """ with self._operation_context() as conn: return self.dialect.has_table( conn, table_name, schema, info_cache=self.info_cache, **kw ) def has_sequence( self, sequence_name: str, schema: Optional[str] = None, **kw: Any ) -> bool: r"""Return True if the backend has a sequence with the given name. :param sequence_name: name of the sequence to check :param schema: schema name to query, if not the default schema. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. .. versionadded:: 1.4 """ with self._operation_context() as conn: return self.dialect.has_sequence( conn, sequence_name, schema, info_cache=self.info_cache, **kw ) def has_index( self, table_name: str, index_name: str, schema: Optional[str] = None, **kw: Any, ) -> bool: r"""Check the existence of a particular index name in the database. :param table_name: the name of the table the index belongs to :param index_name: the name of the index to check :param schema: schema name to query, if not the default schema. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. .. versionadded:: 2.0 """ with self._operation_context() as conn: return self.dialect.has_index( conn, table_name, index_name, schema, info_cache=self.info_cache, **kw, ) def has_schema(self, schema_name: str, **kw: Any) -> bool: r"""Return True if the backend has a schema with the given name. :param schema_name: name of the schema to check :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. .. versionadded:: 2.0 """ with self._operation_context() as conn: return self.dialect.has_schema( conn, schema_name, info_cache=self.info_cache, **kw ) def get_sorted_table_and_fkc_names( self, schema: Optional[str] = None, **kw: Any, ) -> List[Tuple[Optional[str], List[Tuple[str, Optional[str]]]]]: r"""Return dependency-sorted table and foreign key constraint names in referred to within a particular schema. This will yield 2-tuples of ``(tablename, [(tname, fkname), (tname, fkname), ...])`` consisting of table names in CREATE order grouped with the foreign key constraint names that are not detected as belonging to a cycle. The final element will be ``(None, [(tname, fkname), (tname, fkname), ..])`` which will consist of remaining foreign key constraint names that would require a separate CREATE step after-the-fact, based on dependencies between tables. :param schema: schema name to query, if not the default schema. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. .. seealso:: :meth:`_reflection.Inspector.get_table_names` :func:`.sort_tables_and_constraints` - similar method which works with an already-given :class:`_schema.MetaData`. """ return [ ( table_key[1] if table_key else None, [(tname, fks) for (_, tname), fks in fk_collection], ) for ( table_key, fk_collection, ) in self.sort_tables_on_foreign_key_dependency( consider_schemas=(schema,) ) ] def sort_tables_on_foreign_key_dependency( self, consider_schemas: Collection[Optional[str]] = (None,), **kw: Any, ) -> List[ Tuple[ Optional[Tuple[Optional[str], str]], List[Tuple[Tuple[Optional[str], str], Optional[str]]], ] ]: r"""Return dependency-sorted table and foreign key constraint names referred to within multiple schemas. This method may be compared to :meth:`.Inspector.get_sorted_table_and_fkc_names`, which works on one schema at a time; here, the method is a generalization that will consider multiple schemas at once including that it will resolve for cross-schema foreign keys. .. versionadded:: 2.0 """ SchemaTab = Tuple[Optional[str], str] tuples: Set[Tuple[SchemaTab, SchemaTab]] = set() remaining_fkcs: Set[Tuple[SchemaTab, Optional[str]]] = set() fknames_for_table: Dict[SchemaTab, Set[Optional[str]]] = {} tnames: List[SchemaTab] = [] for schname in consider_schemas: schema_fkeys = self.get_multi_foreign_keys(schname, **kw) tnames.extend(schema_fkeys) for (_, tname), fkeys in schema_fkeys.items(): fknames_for_table[(schname, tname)] = { fk["name"] for fk in fkeys } for fkey in fkeys: if ( tname != fkey["referred_table"] or schname != fkey["referred_schema"] ): tuples.add( ( ( fkey["referred_schema"], fkey["referred_table"], ), (schname, tname), ) ) try: candidate_sort = list(topological.sort(tuples, tnames)) except exc.CircularDependencyError as err: edge: Tuple[SchemaTab, SchemaTab] for edge in err.edges: tuples.remove(edge) remaining_fkcs.update( (edge[1], fkc) for fkc in fknames_for_table[edge[1]] ) candidate_sort = list(topological.sort(tuples, tnames)) ret: List[ Tuple[Optional[SchemaTab], List[Tuple[SchemaTab, Optional[str]]]] ] ret = [ ( (schname, tname), [ ((schname, tname), fk) for fk in fknames_for_table[(schname, tname)].difference( name for _, name in remaining_fkcs ) ], ) for (schname, tname) in candidate_sort ] return ret + [(None, list(remaining_fkcs))] def get_temp_table_names(self, **kw: Any) -> List[str]: r"""Return a list of temporary table names for the current bind. This method is unsupported by most dialects; currently only Oracle Database, PostgreSQL and SQLite implements it. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. """ with self._operation_context() as conn: return self.dialect.get_temp_table_names( conn, info_cache=self.info_cache, **kw ) def get_temp_view_names(self, **kw: Any) -> List[str]: r"""Return a list of temporary view names for the current bind. This method is unsupported by most dialects; currently only PostgreSQL and SQLite implements it. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. """ with self._operation_context() as conn: return self.dialect.get_temp_view_names( conn, info_cache=self.info_cache, **kw ) def get_table_options( self, table_name: str, schema: Optional[str] = None, **kw: Any ) -> Dict[str, Any]: r"""Return a dictionary of options specified when the table of the given name was created. This currently includes some options that apply to MySQL and Oracle Database tables. :param table_name: string name of the table. For special quoting, use :class:`.quoted_name`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a dict with the table options. The returned keys depend on the dialect in use. Each one is prefixed with the dialect name. .. seealso:: :meth:`Inspector.get_multi_table_options` """ with self._operation_context() as conn: return self.dialect.get_table_options( conn, table_name, schema, info_cache=self.info_cache, **kw ) def get_multi_table_options( self, schema: Optional[str] = None, filter_names: Optional[Sequence[str]] = None, kind: ObjectKind = ObjectKind.TABLE, scope: ObjectScope = ObjectScope.DEFAULT, **kw: Any, ) -> Dict[TableKey, Dict[str, Any]]: r"""Return a dictionary of options specified when the tables in the given schema were created. The tables can be filtered by passing the names to use to ``filter_names``. This currently includes some options that apply to MySQL and Oracle tables. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param filter_names: optionally return information only for the objects listed here. :param kind: a :class:`.ObjectKind` that specifies the type of objects to reflect. Defaults to ``ObjectKind.TABLE``. :param scope: a :class:`.ObjectScope` that specifies if options of default, temporary or any tables should be reflected. Defaults to ``ObjectScope.DEFAULT``. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a dictionary where the keys are two-tuple schema,table-name and the values are dictionaries with the table options. The returned keys in each dict depend on the dialect in use. Each one is prefixed with the dialect name. The schema is ``None`` if no schema is provided. .. versionadded:: 2.0 .. seealso:: :meth:`Inspector.get_table_options` """ with self._operation_context() as conn: res = self.dialect.get_multi_table_options( conn, schema=schema, filter_names=filter_names, kind=kind, scope=scope, info_cache=self.info_cache, **kw, ) return dict(res) def get_view_names( self, schema: Optional[str] = None, **kw: Any ) -> List[str]: r"""Return all non-materialized view names in `schema`. :param schema: Optional, retrieve names from a non-default schema. For special quoting, use :class:`.quoted_name`. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. .. versionchanged:: 2.0 For those dialects that previously included the names of materialized views in this list (currently PostgreSQL), this method no longer returns the names of materialized views. the :meth:`.Inspector.get_materialized_view_names` method should be used instead. .. seealso:: :meth:`.Inspector.get_materialized_view_names` """ with self._operation_context() as conn: return self.dialect.get_view_names( conn, schema, info_cache=self.info_cache, **kw ) def get_materialized_view_names( self, schema: Optional[str] = None, **kw: Any ) -> List[str]: r"""Return all materialized view names in `schema`. :param schema: Optional, retrieve names from a non-default schema. For special quoting, use :class:`.quoted_name`. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. .. versionadded:: 2.0 .. seealso:: :meth:`.Inspector.get_view_names` """ with self._operation_context() as conn: return self.dialect.get_materialized_view_names( conn, schema, info_cache=self.info_cache, **kw ) def get_sequence_names( self, schema: Optional[str] = None, **kw: Any ) -> List[str]: r"""Return all sequence names in `schema`. :param schema: Optional, retrieve names from a non-default schema. For special quoting, use :class:`.quoted_name`. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. """ with self._operation_context() as conn: return self.dialect.get_sequence_names( conn, schema, info_cache=self.info_cache, **kw ) def get_view_definition( self, view_name: str, schema: Optional[str] = None, **kw: Any ) -> str: r"""Return definition for the plain or materialized view called ``view_name``. :param view_name: Name of the view. :param schema: Optional, retrieve names from a non-default schema. For special quoting, use :class:`.quoted_name`. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. """ with self._operation_context() as conn: return self.dialect.get_view_definition( conn, view_name, schema, info_cache=self.info_cache, **kw ) def get_columns( self, table_name: str, schema: Optional[str] = None, **kw: Any ) -> List[ReflectedColumn]: r"""Return information about columns in ``table_name``. Given a string ``table_name`` and an optional string ``schema``, return column information as a list of :class:`.ReflectedColumn`. :param table_name: string name of the table. For special quoting, use :class:`.quoted_name`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: list of dictionaries, each representing the definition of a database column. .. seealso:: :meth:`Inspector.get_multi_columns`. """ with self._operation_context() as conn: col_defs = self.dialect.get_columns( conn, table_name, schema, info_cache=self.info_cache, **kw ) if col_defs: self._instantiate_types([col_defs]) return col_defs def _instantiate_types( self, data: Iterable[List[ReflectedColumn]] ) -> None: # make this easy and only return instances for coltype for col_defs in data: for col_def in col_defs: coltype = col_def["type"] if not isinstance(coltype, TypeEngine): col_def["type"] = coltype() def get_multi_columns( self, schema: Optional[str] = None, filter_names: Optional[Sequence[str]] = None, kind: ObjectKind = ObjectKind.TABLE, scope: ObjectScope = ObjectScope.DEFAULT, **kw: Any, ) -> Dict[TableKey, List[ReflectedColumn]]: r"""Return information about columns in all objects in the given schema. The objects can be filtered by passing the names to use to ``filter_names``. For each table the value is a list of :class:`.ReflectedColumn`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param filter_names: optionally return information only for the objects listed here. :param kind: a :class:`.ObjectKind` that specifies the type of objects to reflect. Defaults to ``ObjectKind.TABLE``. :param scope: a :class:`.ObjectScope` that specifies if columns of default, temporary or any tables should be reflected. Defaults to ``ObjectScope.DEFAULT``. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a dictionary where the keys are two-tuple schema,table-name and the values are list of dictionaries, each representing the definition of a database column. The schema is ``None`` if no schema is provided. .. versionadded:: 2.0 .. seealso:: :meth:`Inspector.get_columns` """ with self._operation_context() as conn: table_col_defs = dict( self.dialect.get_multi_columns( conn, schema=schema, filter_names=filter_names, kind=kind, scope=scope, info_cache=self.info_cache, **kw, ) ) self._instantiate_types(table_col_defs.values()) return table_col_defs def get_pk_constraint( self, table_name: str, schema: Optional[str] = None, **kw: Any ) -> ReflectedPrimaryKeyConstraint: r"""Return information about primary key constraint in ``table_name``. Given a string ``table_name``, and an optional string `schema`, return primary key information as a :class:`.ReflectedPrimaryKeyConstraint`. :param table_name: string name of the table. For special quoting, use :class:`.quoted_name`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a dictionary representing the definition of a primary key constraint. .. seealso:: :meth:`Inspector.get_multi_pk_constraint` """ with self._operation_context() as conn: return self.dialect.get_pk_constraint( conn, table_name, schema, info_cache=self.info_cache, **kw ) def get_multi_pk_constraint( self, schema: Optional[str] = None, filter_names: Optional[Sequence[str]] = None, kind: ObjectKind = ObjectKind.TABLE, scope: ObjectScope = ObjectScope.DEFAULT, **kw: Any, ) -> Dict[TableKey, ReflectedPrimaryKeyConstraint]: r"""Return information about primary key constraints in all tables in the given schema. The tables can be filtered by passing the names to use to ``filter_names``. For each table the value is a :class:`.ReflectedPrimaryKeyConstraint`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param filter_names: optionally return information only for the objects listed here. :param kind: a :class:`.ObjectKind` that specifies the type of objects to reflect. Defaults to ``ObjectKind.TABLE``. :param scope: a :class:`.ObjectScope` that specifies if primary keys of default, temporary or any tables should be reflected. Defaults to ``ObjectScope.DEFAULT``. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a dictionary where the keys are two-tuple schema,table-name and the values are dictionaries, each representing the definition of a primary key constraint. The schema is ``None`` if no schema is provided. .. versionadded:: 2.0 .. seealso:: :meth:`Inspector.get_pk_constraint` """ with self._operation_context() as conn: return dict( self.dialect.get_multi_pk_constraint( conn, schema=schema, filter_names=filter_names, kind=kind, scope=scope, info_cache=self.info_cache, **kw, ) ) def get_foreign_keys( self, table_name: str, schema: Optional[str] = None, **kw: Any ) -> List[ReflectedForeignKeyConstraint]: r"""Return information about foreign_keys in ``table_name``. Given a string ``table_name``, and an optional string `schema`, return foreign key information as a list of :class:`.ReflectedForeignKeyConstraint`. :param table_name: string name of the table. For special quoting, use :class:`.quoted_name`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a list of dictionaries, each representing the a foreign key definition. .. seealso:: :meth:`Inspector.get_multi_foreign_keys` """ with self._operation_context() as conn: return self.dialect.get_foreign_keys( conn, table_name, schema, info_cache=self.info_cache, **kw ) def get_multi_foreign_keys( self, schema: Optional[str] = None, filter_names: Optional[Sequence[str]] = None, kind: ObjectKind = ObjectKind.TABLE, scope: ObjectScope = ObjectScope.DEFAULT, **kw: Any, ) -> Dict[TableKey, List[ReflectedForeignKeyConstraint]]: r"""Return information about foreign_keys in all tables in the given schema. The tables can be filtered by passing the names to use to ``filter_names``. For each table the value is a list of :class:`.ReflectedForeignKeyConstraint`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param filter_names: optionally return information only for the objects listed here. :param kind: a :class:`.ObjectKind` that specifies the type of objects to reflect. Defaults to ``ObjectKind.TABLE``. :param scope: a :class:`.ObjectScope` that specifies if foreign keys of default, temporary or any tables should be reflected. Defaults to ``ObjectScope.DEFAULT``. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a dictionary where the keys are two-tuple schema,table-name and the values are list of dictionaries, each representing a foreign key definition. The schema is ``None`` if no schema is provided. .. versionadded:: 2.0 .. seealso:: :meth:`Inspector.get_foreign_keys` """ with self._operation_context() as conn: return dict( self.dialect.get_multi_foreign_keys( conn, schema=schema, filter_names=filter_names, kind=kind, scope=scope, info_cache=self.info_cache, **kw, ) ) def get_indexes( self, table_name: str, schema: Optional[str] = None, **kw: Any ) -> List[ReflectedIndex]: r"""Return information about indexes in ``table_name``. Given a string ``table_name`` and an optional string `schema`, return index information as a list of :class:`.ReflectedIndex`. :param table_name: string name of the table. For special quoting, use :class:`.quoted_name`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a list of dictionaries, each representing the definition of an index. .. seealso:: :meth:`Inspector.get_multi_indexes` """ with self._operation_context() as conn: return self.dialect.get_indexes( conn, table_name, schema, info_cache=self.info_cache, **kw ) def get_multi_indexes( self, schema: Optional[str] = None, filter_names: Optional[Sequence[str]] = None, kind: ObjectKind = ObjectKind.TABLE, scope: ObjectScope = ObjectScope.DEFAULT, **kw: Any, ) -> Dict[TableKey, List[ReflectedIndex]]: r"""Return information about indexes in in all objects in the given schema. The objects can be filtered by passing the names to use to ``filter_names``. For each table the value is a list of :class:`.ReflectedIndex`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param filter_names: optionally return information only for the objects listed here. :param kind: a :class:`.ObjectKind` that specifies the type of objects to reflect. Defaults to ``ObjectKind.TABLE``. :param scope: a :class:`.ObjectScope` that specifies if indexes of default, temporary or any tables should be reflected. Defaults to ``ObjectScope.DEFAULT``. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a dictionary where the keys are two-tuple schema,table-name and the values are list of dictionaries, each representing the definition of an index. The schema is ``None`` if no schema is provided. .. versionadded:: 2.0 .. seealso:: :meth:`Inspector.get_indexes` """ with self._operation_context() as conn: return dict( self.dialect.get_multi_indexes( conn, schema=schema, filter_names=filter_names, kind=kind, scope=scope, info_cache=self.info_cache, **kw, ) ) def get_unique_constraints( self, table_name: str, schema: Optional[str] = None, **kw: Any ) -> List[ReflectedUniqueConstraint]: r"""Return information about unique constraints in ``table_name``. Given a string ``table_name`` and an optional string `schema`, return unique constraint information as a list of :class:`.ReflectedUniqueConstraint`. :param table_name: string name of the table. For special quoting, use :class:`.quoted_name`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a list of dictionaries, each representing the definition of an unique constraint. .. seealso:: :meth:`Inspector.get_multi_unique_constraints` """ with self._operation_context() as conn: return self.dialect.get_unique_constraints( conn, table_name, schema, info_cache=self.info_cache, **kw ) def get_multi_unique_constraints( self, schema: Optional[str] = None, filter_names: Optional[Sequence[str]] = None, kind: ObjectKind = ObjectKind.TABLE, scope: ObjectScope = ObjectScope.DEFAULT, **kw: Any, ) -> Dict[TableKey, List[ReflectedUniqueConstraint]]: r"""Return information about unique constraints in all tables in the given schema. The tables can be filtered by passing the names to use to ``filter_names``. For each table the value is a list of :class:`.ReflectedUniqueConstraint`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param filter_names: optionally return information only for the objects listed here. :param kind: a :class:`.ObjectKind` that specifies the type of objects to reflect. Defaults to ``ObjectKind.TABLE``. :param scope: a :class:`.ObjectScope` that specifies if constraints of default, temporary or any tables should be reflected. Defaults to ``ObjectScope.DEFAULT``. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a dictionary where the keys are two-tuple schema,table-name and the values are list of dictionaries, each representing the definition of an unique constraint. The schema is ``None`` if no schema is provided. .. versionadded:: 2.0 .. seealso:: :meth:`Inspector.get_unique_constraints` """ with self._operation_context() as conn: return dict( self.dialect.get_multi_unique_constraints( conn, schema=schema, filter_names=filter_names, kind=kind, scope=scope, info_cache=self.info_cache, **kw, ) ) def get_table_comment( self, table_name: str, schema: Optional[str] = None, **kw: Any ) -> ReflectedTableComment: r"""Return information about the table comment for ``table_name``. Given a string ``table_name`` and an optional string ``schema``, return table comment information as a :class:`.ReflectedTableComment`. Raises ``NotImplementedError`` for a dialect that does not support comments. :param table_name: string name of the table. For special quoting, use :class:`.quoted_name`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a dictionary, with the table comment. .. versionadded:: 1.2 .. seealso:: :meth:`Inspector.get_multi_table_comment` """ with self._operation_context() as conn: return self.dialect.get_table_comment( conn, table_name, schema, info_cache=self.info_cache, **kw ) def get_multi_table_comment( self, schema: Optional[str] = None, filter_names: Optional[Sequence[str]] = None, kind: ObjectKind = ObjectKind.TABLE, scope: ObjectScope = ObjectScope.DEFAULT, **kw: Any, ) -> Dict[TableKey, ReflectedTableComment]: r"""Return information about the table comment in all objects in the given schema. The objects can be filtered by passing the names to use to ``filter_names``. For each table the value is a :class:`.ReflectedTableComment`. Raises ``NotImplementedError`` for a dialect that does not support comments. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param filter_names: optionally return information only for the objects listed here. :param kind: a :class:`.ObjectKind` that specifies the type of objects to reflect. Defaults to ``ObjectKind.TABLE``. :param scope: a :class:`.ObjectScope` that specifies if comments of default, temporary or any tables should be reflected. Defaults to ``ObjectScope.DEFAULT``. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a dictionary where the keys are two-tuple schema,table-name and the values are dictionaries, representing the table comments. The schema is ``None`` if no schema is provided. .. versionadded:: 2.0 .. seealso:: :meth:`Inspector.get_table_comment` """ with self._operation_context() as conn: return dict( self.dialect.get_multi_table_comment( conn, schema=schema, filter_names=filter_names, kind=kind, scope=scope, info_cache=self.info_cache, **kw, ) ) def get_check_constraints( self, table_name: str, schema: Optional[str] = None, **kw: Any ) -> List[ReflectedCheckConstraint]: r"""Return information about check constraints in ``table_name``. Given a string ``table_name`` and an optional string `schema`, return check constraint information as a list of :class:`.ReflectedCheckConstraint`. :param table_name: string name of the table. For special quoting, use :class:`.quoted_name`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a list of dictionaries, each representing the definition of a check constraints. .. seealso:: :meth:`Inspector.get_multi_check_constraints` """ with self._operation_context() as conn: return self.dialect.get_check_constraints( conn, table_name, schema, info_cache=self.info_cache, **kw ) def get_multi_check_constraints( self, schema: Optional[str] = None, filter_names: Optional[Sequence[str]] = None, kind: ObjectKind = ObjectKind.TABLE, scope: ObjectScope = ObjectScope.DEFAULT, **kw: Any, ) -> Dict[TableKey, List[ReflectedCheckConstraint]]: r"""Return information about check constraints in all tables in the given schema. The tables can be filtered by passing the names to use to ``filter_names``. For each table the value is a list of :class:`.ReflectedCheckConstraint`. :param schema: string schema name; if omitted, uses the default schema of the database connection. For special quoting, use :class:`.quoted_name`. :param filter_names: optionally return information only for the objects listed here. :param kind: a :class:`.ObjectKind` that specifies the type of objects to reflect. Defaults to ``ObjectKind.TABLE``. :param scope: a :class:`.ObjectScope` that specifies if constraints of default, temporary or any tables should be reflected. Defaults to ``ObjectScope.DEFAULT``. :param \**kw: Additional keyword argument to pass to the dialect specific implementation. See the documentation of the dialect in use for more information. :return: a dictionary where the keys are two-tuple schema,table-name and the values are list of dictionaries, each representing the definition of a check constraints. The schema is ``None`` if no schema is provided. .. versionadded:: 2.0 .. seealso:: :meth:`Inspector.get_check_constraints` """ with self._operation_context() as conn: return dict( self.dialect.get_multi_check_constraints( conn, schema=schema, filter_names=filter_names, kind=kind, scope=scope, info_cache=self.info_cache, **kw, ) ) def reflect_table( self, table: sa_schema.Table, include_columns: Optional[Collection[str]], exclude_columns: Collection[str] = (), resolve_fks: bool = True, _extend_on: Optional[Set[sa_schema.Table]] = None, _reflect_info: Optional[_ReflectionInfo] = None, ) -> None: """Given a :class:`_schema.Table` object, load its internal constructs based on introspection. This is the underlying method used by most dialects to produce table reflection. Direct usage is like:: from sqlalchemy import create_engine, MetaData, Table from sqlalchemy import inspect engine = create_engine("...") meta = MetaData() user_table = Table("user", meta) insp = inspect(engine) insp.reflect_table(user_table, None) .. versionchanged:: 1.4 Renamed from ``reflecttable`` to ``reflect_table`` :param table: a :class:`~sqlalchemy.schema.Table` instance. :param include_columns: a list of string column names to include in the reflection process. If ``None``, all columns are reflected. """ if _extend_on is not None: if table in _extend_on: return else: _extend_on.add(table) dialect = self.bind.dialect with self._operation_context() as conn: schema = conn.schema_for_object(table) table_name = table.name # get table-level arguments that are specifically # intended for reflection, e.g. oracle_resolve_synonyms. # these are unconditionally passed to related Table # objects reflection_options = { k: table.dialect_kwargs.get(k) for k in dialect.reflection_options if k in table.dialect_kwargs } table_key = (schema, table_name) if _reflect_info is None or table_key not in _reflect_info.columns: _reflect_info = self._get_reflection_info( schema, filter_names=[table_name], kind=ObjectKind.ANY, scope=ObjectScope.ANY, _reflect_info=_reflect_info, **table.dialect_kwargs, ) if table_key in _reflect_info.unreflectable: raise _reflect_info.unreflectable[table_key] if table_key not in _reflect_info.columns: raise exc.NoSuchTableError(table_name) # reflect table options, like mysql_engine if _reflect_info.table_options: tbl_opts = _reflect_info.table_options.get(table_key) if tbl_opts: # add additional kwargs to the Table if the dialect # returned them table._validate_dialect_kwargs(tbl_opts) found_table = False cols_by_orig_name: Dict[str, sa_schema.Column[Any]] = {} for col_d in _reflect_info.columns[table_key]: found_table = True self._reflect_column( table, col_d, include_columns, exclude_columns, cols_by_orig_name, ) # NOTE: support tables/views with no columns if not found_table and not self.has_table(table_name, schema): raise exc.NoSuchTableError(table_name) self._reflect_pk( _reflect_info, table_key, table, cols_by_orig_name, exclude_columns ) self._reflect_fk( _reflect_info, table_key, table, cols_by_orig_name, include_columns, exclude_columns, resolve_fks, _extend_on, reflection_options, ) self._reflect_indexes( _reflect_info, table_key, table, cols_by_orig_name, include_columns, exclude_columns, reflection_options, ) self._reflect_unique_constraints( _reflect_info, table_key, table, cols_by_orig_name, include_columns, exclude_columns, reflection_options, ) self._reflect_check_constraints( _reflect_info, table_key, table, cols_by_orig_name, include_columns, exclude_columns, reflection_options, ) self._reflect_table_comment( _reflect_info, table_key, table, reflection_options, ) def _reflect_column( self, table: sa_schema.Table, col_d: ReflectedColumn, include_columns: Optional[Collection[str]], exclude_columns: Collection[str], cols_by_orig_name: Dict[str, sa_schema.Column[Any]], ) -> None: orig_name = col_d["name"] table.metadata.dispatch.column_reflect(self, table, col_d) table.dispatch.column_reflect(self, table, col_d) # fetch name again as column_reflect is allowed to # change it name = col_d["name"] if (include_columns and name not in include_columns) or ( exclude_columns and name in exclude_columns ): return coltype = col_d["type"] col_kw = { k: col_d[k] # type: ignore[literal-required] for k in [ "nullable", "autoincrement", "quote", "info", "key", "comment", ] if k in col_d } if "dialect_options" in col_d: col_kw.update(col_d["dialect_options"]) colargs = [] default: Any if col_d.get("default") is not None: default_text = col_d["default"] assert default_text is not None if isinstance(default_text, TextClause): default = sa_schema.DefaultClause( default_text, _reflected=True ) elif not isinstance(default_text, sa_schema.FetchedValue): default = sa_schema.DefaultClause( sql.text(default_text), _reflected=True ) else: default = default_text colargs.append(default) if "computed" in col_d: computed = sa_schema.Computed(**col_d["computed"]) colargs.append(computed) if "identity" in col_d: identity = sa_schema.Identity(**col_d["identity"]) colargs.append(identity) cols_by_orig_name[orig_name] = col = sa_schema.Column( name, coltype, *colargs, **col_kw ) if col.key in table.primary_key: col.primary_key = True table.append_column(col, replace_existing=True) def _reflect_pk( self, _reflect_info: _ReflectionInfo, table_key: TableKey, table: sa_schema.Table, cols_by_orig_name: Dict[str, sa_schema.Column[Any]], exclude_columns: Collection[str], ) -> None: pk_cons = _reflect_info.pk_constraint.get(table_key) if pk_cons: pk_cols = [ cols_by_orig_name[pk] for pk in pk_cons["constrained_columns"] if pk in cols_by_orig_name and pk not in exclude_columns ] # update pk constraint name, comment and dialect_kwargs table.primary_key.name = pk_cons.get("name") table.primary_key.comment = pk_cons.get("comment", None) dialect_options = pk_cons.get("dialect_options") if dialect_options: table.primary_key.dialect_kwargs.update(dialect_options) # tell the PKConstraint to re-initialize # its column collection table.primary_key._reload(pk_cols) def _reflect_fk( self, _reflect_info: _ReflectionInfo, table_key: TableKey, table: sa_schema.Table, cols_by_orig_name: Dict[str, sa_schema.Column[Any]], include_columns: Optional[Collection[str]], exclude_columns: Collection[str], resolve_fks: bool, _extend_on: Optional[Set[sa_schema.Table]], reflection_options: Dict[str, Any], ) -> None: fkeys = _reflect_info.foreign_keys.get(table_key, []) for fkey_d in fkeys: conname = fkey_d["name"] # look for columns by orig name in cols_by_orig_name, # but support columns that are in-Python only as fallback constrained_columns = [ cols_by_orig_name[c].key if c in cols_by_orig_name else c for c in fkey_d["constrained_columns"] ] if ( exclude_columns and set(constrained_columns).intersection(exclude_columns) or ( include_columns and set(constrained_columns).difference(include_columns) ) ): continue referred_schema = fkey_d["referred_schema"] referred_table = fkey_d["referred_table"] referred_columns = fkey_d["referred_columns"] refspec = [] if referred_schema is not None: if resolve_fks: sa_schema.Table( referred_table, table.metadata, schema=referred_schema, autoload_with=self.bind, _extend_on=_extend_on, _reflect_info=_reflect_info, **reflection_options, ) for column in referred_columns: refspec.append( ".".join([referred_schema, referred_table, column]) ) else: if resolve_fks: sa_schema.Table( referred_table, table.metadata, autoload_with=self.bind, schema=sa_schema.BLANK_SCHEMA, _extend_on=_extend_on, _reflect_info=_reflect_info, **reflection_options, ) for column in referred_columns: refspec.append(".".join([referred_table, column])) if "options" in fkey_d: options = fkey_d["options"] else: options = {} try: table.append_constraint( sa_schema.ForeignKeyConstraint( constrained_columns, refspec, conname, link_to_name=True, comment=fkey_d.get("comment"), **options, ) ) except exc.ConstraintColumnNotFoundError: util.warn( f"On reflected table {table.name}, skipping reflection of " "foreign key constraint " f"{conname}; one or more subject columns within " f"name(s) {', '.join(constrained_columns)} are not " "present in the table" ) _index_sort_exprs = { "asc": operators.asc_op, "desc": operators.desc_op, "nulls_first": operators.nulls_first_op, "nulls_last": operators.nulls_last_op, } def _reflect_indexes( self, _reflect_info: _ReflectionInfo, table_key: TableKey, table: sa_schema.Table, cols_by_orig_name: Dict[str, sa_schema.Column[Any]], include_columns: Optional[Collection[str]], exclude_columns: Collection[str], reflection_options: Dict[str, Any], ) -> None: # Indexes indexes = _reflect_info.indexes.get(table_key, []) for index_d in indexes: name = index_d["name"] columns = index_d["column_names"] expressions = index_d.get("expressions") column_sorting = index_d.get("column_sorting", {}) unique = index_d["unique"] flavor = index_d.get("type", "index") dialect_options = index_d.get("dialect_options", {}) duplicates = index_d.get("duplicates_constraint") if include_columns and not set(columns).issubset(include_columns): continue if duplicates: continue # look for columns by orig name in cols_by_orig_name, # but support columns that are in-Python only as fallback idx_element: Any idx_elements = [] for index, c in enumerate(columns): if c is None: if not expressions: util.warn( f"Skipping {flavor} {name!r} because key " f"{index + 1} reflected as None but no " "'expressions' were returned" ) break idx_element = sql.text(expressions[index]) else: try: if c in cols_by_orig_name: idx_element = cols_by_orig_name[c] else: idx_element = table.c[c] except KeyError: util.warn( f"{flavor} key {c!r} was not located in " f"columns for table {table.name!r}" ) continue for option in column_sorting.get(c, ()): if option in self._index_sort_exprs: op = self._index_sort_exprs[option] idx_element = op(idx_element) idx_elements.append(idx_element) else: sa_schema.Index( name, *idx_elements, _table=table, unique=unique, **dialect_options, ) def _reflect_unique_constraints( self, _reflect_info: _ReflectionInfo, table_key: TableKey, table: sa_schema.Table, cols_by_orig_name: Dict[str, sa_schema.Column[Any]], include_columns: Optional[Collection[str]], exclude_columns: Collection[str], reflection_options: Dict[str, Any], ) -> None: constraints = _reflect_info.unique_constraints.get(table_key, []) # Unique Constraints for const_d in constraints: conname = const_d["name"] columns = const_d["column_names"] comment = const_d.get("comment") duplicates = const_d.get("duplicates_index") dialect_options = const_d.get("dialect_options", {}) if include_columns and not set(columns).issubset(include_columns): continue if duplicates: continue # look for columns by orig name in cols_by_orig_name, # but support columns that are in-Python only as fallback constrained_cols = [] for c in columns: try: constrained_col = ( cols_by_orig_name[c] if c in cols_by_orig_name else table.c[c] ) except KeyError: util.warn( "unique constraint key '%s' was not located in " "columns for table '%s'" % (c, table.name) ) else: constrained_cols.append(constrained_col) table.append_constraint( sa_schema.UniqueConstraint( *constrained_cols, name=conname, comment=comment, **dialect_options, ) ) def _reflect_check_constraints( self, _reflect_info: _ReflectionInfo, table_key: TableKey, table: sa_schema.Table, cols_by_orig_name: Dict[str, sa_schema.Column[Any]], include_columns: Optional[Collection[str]], exclude_columns: Collection[str], reflection_options: Dict[str, Any], ) -> None: constraints = _reflect_info.check_constraints.get(table_key, []) for const_d in constraints: table.append_constraint(sa_schema.CheckConstraint(**const_d)) def _reflect_table_comment( self, _reflect_info: _ReflectionInfo, table_key: TableKey, table: sa_schema.Table, reflection_options: Dict[str, Any], ) -> None: comment_dict = _reflect_info.table_comment.get(table_key) if comment_dict: table.comment = comment_dict["text"] def _get_reflection_info( self, schema: Optional[str] = None, filter_names: Optional[Collection[str]] = None, available: Optional[Collection[str]] = None, _reflect_info: Optional[_ReflectionInfo] = None, **kw: Any, ) -> _ReflectionInfo: kw["schema"] = schema if filter_names and available and len(filter_names) > 100: fraction = len(filter_names) / len(available) else: fraction = None unreflectable: Dict[TableKey, exc.UnreflectableTableError] kw["unreflectable"] = unreflectable = {} has_result: bool = True def run( meth: Any, *, optional: bool = False, check_filter_names_from_meth: bool = False, ) -> Any: nonlocal has_result # simple heuristic to improve reflection performance if a # dialect implements multi_reflection: # if more than 50% of the tables in the db are in filter_names # load all the tables, since it's most likely faster to avoid # a filter on that many tables. if ( fraction is None or fraction <= 0.5 or not self.dialect._overrides_default(meth.__name__) ): _fn = filter_names else: _fn = None try: if has_result: res = meth(filter_names=_fn, **kw) if check_filter_names_from_meth and not res: # method returned no result data. # skip any future call methods has_result = False else: res = {} except NotImplementedError: if not optional: raise res = {} return res info = _ReflectionInfo( columns=run( self.get_multi_columns, check_filter_names_from_meth=True ), pk_constraint=run(self.get_multi_pk_constraint), foreign_keys=run(self.get_multi_foreign_keys), indexes=run(self.get_multi_indexes), unique_constraints=run( self.get_multi_unique_constraints, optional=True ), table_comment=run(self.get_multi_table_comment, optional=True), check_constraints=run( self.get_multi_check_constraints, optional=True ), table_options=run(self.get_multi_table_options, optional=True), unreflectable=unreflectable, ) if _reflect_info: _reflect_info.update(info) return _reflect_info else: return info @final class ReflectionDefaults: """provides blank default values for reflection methods.""" @classmethod def columns(cls) -> List[ReflectedColumn]: return [] @classmethod def pk_constraint(cls) -> ReflectedPrimaryKeyConstraint: return { "name": None, "constrained_columns": [], } @classmethod def foreign_keys(cls) -> List[ReflectedForeignKeyConstraint]: return [] @classmethod def indexes(cls) -> List[ReflectedIndex]: return [] @classmethod def unique_constraints(cls) -> List[ReflectedUniqueConstraint]: return [] @classmethod def check_constraints(cls) -> List[ReflectedCheckConstraint]: return [] @classmethod def table_options(cls) -> Dict[str, Any]: return {} @classmethod def table_comment(cls) -> ReflectedTableComment: return {"text": None} @dataclass class _ReflectionInfo: columns: Dict[TableKey, List[ReflectedColumn]] pk_constraint: Dict[TableKey, Optional[ReflectedPrimaryKeyConstraint]] foreign_keys: Dict[TableKey, List[ReflectedForeignKeyConstraint]] indexes: Dict[TableKey, List[ReflectedIndex]] # optionals unique_constraints: Dict[TableKey, List[ReflectedUniqueConstraint]] table_comment: Dict[TableKey, Optional[ReflectedTableComment]] check_constraints: Dict[TableKey, List[ReflectedCheckConstraint]] table_options: Dict[TableKey, Dict[str, Any]] unreflectable: Dict[TableKey, exc.UnreflectableTableError] def update(self, other: _ReflectionInfo) -> None: for k, v in self.__dict__.items(): ov = getattr(other, k) if ov is not None: if v is None: setattr(self, k, ov) else: v.update(ov) sqlalchemy/engine/base.py 0000755 00000357673 15125143220 0011462 0 ustar 00 # engine/base.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """Defines :class:`_engine.Connection` and :class:`_engine.Engine`. """ from __future__ import annotations import contextlib import sys import typing from typing import Any from typing import Callable from typing import cast from typing import Iterable from typing import Iterator from typing import List from typing import Mapping from typing import NoReturn from typing import Optional from typing import overload from typing import Tuple from typing import Type from typing import TypeVar from typing import Union from .interfaces import BindTyping from .interfaces import ConnectionEventsTarget from .interfaces import DBAPICursor from .interfaces import ExceptionContext from .interfaces import ExecuteStyle from .interfaces import ExecutionContext from .interfaces import IsolationLevel from .util import _distill_params_20 from .util import _distill_raw_params from .util import TransactionalContext from .. import exc from .. import inspection from .. import log from .. import util from ..sql import compiler from ..sql import util as sql_util if typing.TYPE_CHECKING: from . import CursorResult from . import ScalarResult from .interfaces import _AnyExecuteParams from .interfaces import _AnyMultiExecuteParams from .interfaces import _CoreAnyExecuteParams from .interfaces import _CoreMultiExecuteParams from .interfaces import _CoreSingleExecuteParams from .interfaces import _DBAPIAnyExecuteParams from .interfaces import _DBAPISingleExecuteParams from .interfaces import _ExecuteOptions from .interfaces import CompiledCacheType from .interfaces import CoreExecuteOptionsParameter from .interfaces import Dialect from .interfaces import SchemaTranslateMapType from .reflection import Inspector # noqa from .url import URL from ..event import dispatcher from ..log import _EchoFlagType from ..pool import _ConnectionFairy from ..pool import Pool from ..pool import PoolProxiedConnection from ..sql import Executable from ..sql._typing import _InfoType from ..sql.compiler import Compiled from ..sql.ddl import ExecutableDDLElement from ..sql.ddl import InvokeDDLBase from ..sql.functions import FunctionElement from ..sql.schema import DefaultGenerator from ..sql.schema import HasSchemaAttr from ..sql.schema import SchemaVisitable from ..sql.selectable import TypedReturnsRows _T = TypeVar("_T", bound=Any) _EMPTY_EXECUTION_OPTS: _ExecuteOptions = util.EMPTY_DICT NO_OPTIONS: Mapping[str, Any] = util.EMPTY_DICT class Connection(ConnectionEventsTarget, inspection.Inspectable["Inspector"]): """Provides high-level functionality for a wrapped DB-API connection. The :class:`_engine.Connection` object is procured by calling the :meth:`_engine.Engine.connect` method of the :class:`_engine.Engine` object, and provides services for execution of SQL statements as well as transaction control. The Connection object is **not** thread-safe. While a Connection can be shared among threads using properly synchronized access, it is still possible that the underlying DBAPI connection may not support shared access between threads. Check the DBAPI documentation for details. The Connection object represents a single DBAPI connection checked out from the connection pool. In this state, the connection pool has no affect upon the connection, including its expiration or timeout state. For the connection pool to properly manage connections, connections should be returned to the connection pool (i.e. ``connection.close()``) whenever the connection is not in use. .. index:: single: thread safety; Connection """ dialect: Dialect dispatch: dispatcher[ConnectionEventsTarget] _sqla_logger_namespace = "sqlalchemy.engine.Connection" # used by sqlalchemy.engine.util.TransactionalContext _trans_context_manager: Optional[TransactionalContext] = None # legacy as of 2.0, should be eventually deprecated and # removed. was used in the "pre_ping" recipe that's been in the docs # a long time should_close_with_result = False _dbapi_connection: Optional[PoolProxiedConnection] _execution_options: _ExecuteOptions _transaction: Optional[RootTransaction] _nested_transaction: Optional[NestedTransaction] def __init__( self, engine: Engine, connection: Optional[PoolProxiedConnection] = None, _has_events: Optional[bool] = None, _allow_revalidate: bool = True, _allow_autobegin: bool = True, ): """Construct a new Connection.""" self.engine = engine self.dialect = dialect = engine.dialect if connection is None: try: self._dbapi_connection = engine.raw_connection() except dialect.loaded_dbapi.Error as err: Connection._handle_dbapi_exception_noconnection( err, dialect, engine ) raise else: self._dbapi_connection = connection self._transaction = self._nested_transaction = None self.__savepoint_seq = 0 self.__in_begin = False self.__can_reconnect = _allow_revalidate self._allow_autobegin = _allow_autobegin self._echo = self.engine._should_log_info() if _has_events is None: # if _has_events is sent explicitly as False, # then don't join the dispatch of the engine; we don't # want to handle any of the engine's events in that case. self.dispatch = self.dispatch._join(engine.dispatch) self._has_events = _has_events or ( _has_events is None and engine._has_events ) self._execution_options = engine._execution_options if self._has_events or self.engine._has_events: self.dispatch.engine_connect(self) # this can be assigned differently via # characteristics.LoggingTokenCharacteristic _message_formatter: Any = None def _log_info(self, message: str, *arg: Any, **kw: Any) -> None: fmt = self._message_formatter if fmt: message = fmt(message) if log.STACKLEVEL: kw["stacklevel"] = 1 + log.STACKLEVEL_OFFSET self.engine.logger.info(message, *arg, **kw) def _log_debug(self, message: str, *arg: Any, **kw: Any) -> None: fmt = self._message_formatter if fmt: message = fmt(message) if log.STACKLEVEL: kw["stacklevel"] = 1 + log.STACKLEVEL_OFFSET self.engine.logger.debug(message, *arg, **kw) @property def _schema_translate_map(self) -> Optional[SchemaTranslateMapType]: schema_translate_map: Optional[SchemaTranslateMapType] = ( self._execution_options.get("schema_translate_map", None) ) return schema_translate_map def schema_for_object(self, obj: HasSchemaAttr) -> Optional[str]: """Return the schema name for the given schema item taking into account current schema translate map. """ name = obj.schema schema_translate_map: Optional[SchemaTranslateMapType] = ( self._execution_options.get("schema_translate_map", None) ) if ( schema_translate_map and name in schema_translate_map and obj._use_schema_map ): return schema_translate_map[name] else: return name def __enter__(self) -> Connection: return self def __exit__(self, type_: Any, value: Any, traceback: Any) -> None: self.close() @overload def execution_options( self, *, compiled_cache: Optional[CompiledCacheType] = ..., logging_token: str = ..., isolation_level: IsolationLevel = ..., no_parameters: bool = False, stream_results: bool = False, max_row_buffer: int = ..., yield_per: int = ..., insertmanyvalues_page_size: int = ..., schema_translate_map: Optional[SchemaTranslateMapType] = ..., preserve_rowcount: bool = False, **opt: Any, ) -> Connection: ... @overload def execution_options(self, **opt: Any) -> Connection: ... def execution_options(self, **opt: Any) -> Connection: r"""Set non-SQL options for the connection which take effect during execution. This method modifies this :class:`_engine.Connection` **in-place**; the return value is the same :class:`_engine.Connection` object upon which the method is called. Note that this is in contrast to the behavior of the ``execution_options`` methods on other objects such as :meth:`_engine.Engine.execution_options` and :meth:`_sql.Executable.execution_options`. The rationale is that many such execution options necessarily modify the state of the base DBAPI connection in any case so there is no feasible means of keeping the effect of such an option localized to a "sub" connection. .. versionchanged:: 2.0 The :meth:`_engine.Connection.execution_options` method, in contrast to other objects with this method, modifies the connection in-place without creating copy of it. As discussed elsewhere, the :meth:`_engine.Connection.execution_options` method accepts any arbitrary parameters including user defined names. All parameters given are consumable in a number of ways including by using the :meth:`_engine.Connection.get_execution_options` method. See the examples at :meth:`_sql.Executable.execution_options` and :meth:`_engine.Engine.execution_options`. The keywords that are currently recognized by SQLAlchemy itself include all those listed under :meth:`.Executable.execution_options`, as well as others that are specific to :class:`_engine.Connection`. :param compiled_cache: Available on: :class:`_engine.Connection`, :class:`_engine.Engine`. A dictionary where :class:`.Compiled` objects will be cached when the :class:`_engine.Connection` compiles a clause expression into a :class:`.Compiled` object. This dictionary will supersede the statement cache that may be configured on the :class:`_engine.Engine` itself. If set to None, caching is disabled, even if the engine has a configured cache size. Note that the ORM makes use of its own "compiled" caches for some operations, including flush operations. The caching used by the ORM internally supersedes a cache dictionary specified here. :param logging_token: Available on: :class:`_engine.Connection`, :class:`_engine.Engine`, :class:`_sql.Executable`. Adds the specified string token surrounded by brackets in log messages logged by the connection, i.e. the logging that's enabled either via the :paramref:`_sa.create_engine.echo` flag or via the ``logging.getLogger("sqlalchemy.engine")`` logger. This allows a per-connection or per-sub-engine token to be available which is useful for debugging concurrent connection scenarios. .. versionadded:: 1.4.0b2 .. seealso:: :ref:`dbengine_logging_tokens` - usage example :paramref:`_sa.create_engine.logging_name` - adds a name to the name used by the Python logger object itself. :param isolation_level: Available on: :class:`_engine.Connection`, :class:`_engine.Engine`. Set the transaction isolation level for the lifespan of this :class:`_engine.Connection` object. Valid values include those string values accepted by the :paramref:`_sa.create_engine.isolation_level` parameter passed to :func:`_sa.create_engine`. These levels are semi-database specific; see individual dialect documentation for valid levels. The isolation level option applies the isolation level by emitting statements on the DBAPI connection, and **necessarily affects the original Connection object overall**. The isolation level will remain at the given setting until explicitly changed, or when the DBAPI connection itself is :term:`released` to the connection pool, i.e. the :meth:`_engine.Connection.close` method is called, at which time an event handler will emit additional statements on the DBAPI connection in order to revert the isolation level change. .. note:: The ``isolation_level`` execution option may only be established before the :meth:`_engine.Connection.begin` method is called, as well as before any SQL statements are emitted which would otherwise trigger "autobegin", or directly after a call to :meth:`_engine.Connection.commit` or :meth:`_engine.Connection.rollback`. A database cannot change the isolation level on a transaction in progress. .. note:: The ``isolation_level`` execution option is implicitly reset if the :class:`_engine.Connection` is invalidated, e.g. via the :meth:`_engine.Connection.invalidate` method, or if a disconnection error occurs. The new connection produced after the invalidation will **not** have the selected isolation level re-applied to it automatically. .. seealso:: :ref:`dbapi_autocommit` :meth:`_engine.Connection.get_isolation_level` - view current actual level :param no_parameters: Available on: :class:`_engine.Connection`, :class:`_sql.Executable`. When ``True``, if the final parameter list or dictionary is totally empty, will invoke the statement on the cursor as ``cursor.execute(statement)``, not passing the parameter collection at all. Some DBAPIs such as psycopg2 and mysql-python consider percent signs as significant only when parameters are present; this option allows code to generate SQL containing percent signs (and possibly other characters) that is neutral regarding whether it's executed by the DBAPI or piped into a script that's later invoked by command line tools. :param stream_results: Available on: :class:`_engine.Connection`, :class:`_sql.Executable`. Indicate to the dialect that results should be "streamed" and not pre-buffered, if possible. For backends such as PostgreSQL, MySQL and MariaDB, this indicates the use of a "server side cursor" as opposed to a client side cursor. Other backends such as that of Oracle Database may already use server side cursors by default. The usage of :paramref:`_engine.Connection.execution_options.stream_results` is usually combined with setting a fixed number of rows to to be fetched in batches, to allow for efficient iteration of database rows while at the same time not loading all result rows into memory at once; this can be configured on a :class:`_engine.Result` object using the :meth:`_engine.Result.yield_per` method, after execution has returned a new :class:`_engine.Result`. If :meth:`_engine.Result.yield_per` is not used, the :paramref:`_engine.Connection.execution_options.stream_results` mode of operation will instead use a dynamically sized buffer which buffers sets of rows at a time, growing on each batch based on a fixed growth size up until a limit which may be configured using the :paramref:`_engine.Connection.execution_options.max_row_buffer` parameter. When using the ORM to fetch ORM mapped objects from a result, :meth:`_engine.Result.yield_per` should always be used with :paramref:`_engine.Connection.execution_options.stream_results`, so that the ORM does not fetch all rows into new ORM objects at once. For typical use, the :paramref:`_engine.Connection.execution_options.yield_per` execution option should be preferred, which sets up both :paramref:`_engine.Connection.execution_options.stream_results` and :meth:`_engine.Result.yield_per` at once. This option is supported both at a core level by :class:`_engine.Connection` as well as by the ORM :class:`_engine.Session`; the latter is described at :ref:`orm_queryguide_yield_per`. .. seealso:: :ref:`engine_stream_results` - background on :paramref:`_engine.Connection.execution_options.stream_results` :paramref:`_engine.Connection.execution_options.max_row_buffer` :paramref:`_engine.Connection.execution_options.yield_per` :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel` describing the ORM version of ``yield_per`` :param max_row_buffer: Available on: :class:`_engine.Connection`, :class:`_sql.Executable`. Sets a maximum buffer size to use when the :paramref:`_engine.Connection.execution_options.stream_results` execution option is used on a backend that supports server side cursors. The default value if not specified is 1000. .. seealso:: :paramref:`_engine.Connection.execution_options.stream_results` :ref:`engine_stream_results` :param yield_per: Available on: :class:`_engine.Connection`, :class:`_sql.Executable`. Integer value applied which will set the :paramref:`_engine.Connection.execution_options.stream_results` execution option and invoke :meth:`_engine.Result.yield_per` automatically at once. Allows equivalent functionality as is present when using this parameter with the ORM. .. versionadded:: 1.4.40 .. seealso:: :ref:`engine_stream_results` - background and examples on using server side cursors with Core. :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel` describing the ORM version of ``yield_per`` :param insertmanyvalues_page_size: Available on: :class:`_engine.Connection`, :class:`_engine.Engine`. Number of rows to format into an INSERT statement when the statement uses "insertmanyvalues" mode, which is a paged form of bulk insert that is used for many backends when using :term:`executemany` execution typically in conjunction with RETURNING. Defaults to 1000. May also be modified on a per-engine basis using the :paramref:`_sa.create_engine.insertmanyvalues_page_size` parameter. .. versionadded:: 2.0 .. seealso:: :ref:`engine_insertmanyvalues` :param schema_translate_map: Available on: :class:`_engine.Connection`, :class:`_engine.Engine`, :class:`_sql.Executable`. A dictionary mapping schema names to schema names, that will be applied to the :paramref:`_schema.Table.schema` element of each :class:`_schema.Table` encountered when SQL or DDL expression elements are compiled into strings; the resulting schema name will be converted based on presence in the map of the original name. .. seealso:: :ref:`schema_translating` :param preserve_rowcount: Boolean; when True, the ``cursor.rowcount`` attribute will be unconditionally memoized within the result and made available via the :attr:`.CursorResult.rowcount` attribute. Normally, this attribute is only preserved for UPDATE and DELETE statements. Using this option, the DBAPIs rowcount value can be accessed for other kinds of statements such as INSERT and SELECT, to the degree that the DBAPI supports these statements. See :attr:`.CursorResult.rowcount` for notes regarding the behavior of this attribute. .. versionadded:: 2.0.28 .. seealso:: :meth:`_engine.Engine.execution_options` :meth:`.Executable.execution_options` :meth:`_engine.Connection.get_execution_options` :ref:`orm_queryguide_execution_options` - documentation on all ORM-specific execution options """ # noqa if self._has_events or self.engine._has_events: self.dispatch.set_connection_execution_options(self, opt) self._execution_options = self._execution_options.union(opt) self.dialect.set_connection_execution_options(self, opt) return self def get_execution_options(self) -> _ExecuteOptions: """Get the non-SQL options which will take effect during execution. .. versionadded:: 1.3 .. seealso:: :meth:`_engine.Connection.execution_options` """ return self._execution_options @property def _still_open_and_dbapi_connection_is_valid(self) -> bool: pool_proxied_connection = self._dbapi_connection return ( pool_proxied_connection is not None and pool_proxied_connection.is_valid ) @property def closed(self) -> bool: """Return True if this connection is closed.""" return self._dbapi_connection is None and not self.__can_reconnect @property def invalidated(self) -> bool: """Return True if this connection was invalidated. This does not indicate whether or not the connection was invalidated at the pool level, however """ # prior to 1.4, "invalid" was stored as a state independent of # "closed", meaning an invalidated connection could be "closed", # the _dbapi_connection would be None and closed=True, yet the # "invalid" flag would stay True. This meant that there were # three separate states (open/valid, closed/valid, closed/invalid) # when there is really no reason for that; a connection that's # "closed" does not need to be "invalid". So the state is now # represented by the two facts alone. pool_proxied_connection = self._dbapi_connection return pool_proxied_connection is None and self.__can_reconnect @property def connection(self) -> PoolProxiedConnection: """The underlying DB-API connection managed by this Connection. This is a SQLAlchemy connection-pool proxied connection which then has the attribute :attr:`_pool._ConnectionFairy.dbapi_connection` that refers to the actual driver connection. .. seealso:: :ref:`dbapi_connections` """ if self._dbapi_connection is None: try: return self._revalidate_connection() except (exc.PendingRollbackError, exc.ResourceClosedError): raise except BaseException as e: self._handle_dbapi_exception(e, None, None, None, None) else: return self._dbapi_connection def get_isolation_level(self) -> IsolationLevel: """Return the current **actual** isolation level that's present on the database within the scope of this connection. This attribute will perform a live SQL operation against the database in order to procure the current isolation level, so the value returned is the actual level on the underlying DBAPI connection regardless of how this state was set. This will be one of the four actual isolation modes ``READ UNCOMMITTED``, ``READ COMMITTED``, ``REPEATABLE READ``, ``SERIALIZABLE``. It will **not** include the ``AUTOCOMMIT`` isolation level setting. Third party dialects may also feature additional isolation level settings. .. note:: This method **will not report** on the ``AUTOCOMMIT`` isolation level, which is a separate :term:`dbapi` setting that's independent of **actual** isolation level. When ``AUTOCOMMIT`` is in use, the database connection still has a "traditional" isolation mode in effect, that is typically one of the four values ``READ UNCOMMITTED``, ``READ COMMITTED``, ``REPEATABLE READ``, ``SERIALIZABLE``. Compare to the :attr:`_engine.Connection.default_isolation_level` accessor which returns the isolation level that is present on the database at initial connection time. .. seealso:: :attr:`_engine.Connection.default_isolation_level` - view default level :paramref:`_sa.create_engine.isolation_level` - set per :class:`_engine.Engine` isolation level :paramref:`.Connection.execution_options.isolation_level` - set per :class:`_engine.Connection` isolation level """ dbapi_connection = self.connection.dbapi_connection assert dbapi_connection is not None try: return self.dialect.get_isolation_level(dbapi_connection) except BaseException as e: self._handle_dbapi_exception(e, None, None, None, None) @property def default_isolation_level(self) -> Optional[IsolationLevel]: """The initial-connection time isolation level associated with the :class:`_engine.Dialect` in use. This value is independent of the :paramref:`.Connection.execution_options.isolation_level` and :paramref:`.Engine.execution_options.isolation_level` execution options, and is determined by the :class:`_engine.Dialect` when the first connection is created, by performing a SQL query against the database for the current isolation level before any additional commands have been emitted. Calling this accessor does not invoke any new SQL queries. .. seealso:: :meth:`_engine.Connection.get_isolation_level` - view current actual isolation level :paramref:`_sa.create_engine.isolation_level` - set per :class:`_engine.Engine` isolation level :paramref:`.Connection.execution_options.isolation_level` - set per :class:`_engine.Connection` isolation level """ return self.dialect.default_isolation_level def _invalid_transaction(self) -> NoReturn: raise exc.PendingRollbackError( "Can't reconnect until invalid %stransaction is rolled " "back. Please rollback() fully before proceeding" % ("savepoint " if self._nested_transaction is not None else ""), code="8s2b", ) def _revalidate_connection(self) -> PoolProxiedConnection: if self.__can_reconnect and self.invalidated: if self._transaction is not None: self._invalid_transaction() self._dbapi_connection = self.engine.raw_connection() return self._dbapi_connection raise exc.ResourceClosedError("This Connection is closed") @property def info(self) -> _InfoType: """Info dictionary associated with the underlying DBAPI connection referred to by this :class:`_engine.Connection`, allowing user-defined data to be associated with the connection. The data here will follow along with the DBAPI connection including after it is returned to the connection pool and used again in subsequent instances of :class:`_engine.Connection`. """ return self.connection.info def invalidate(self, exception: Optional[BaseException] = None) -> None: """Invalidate the underlying DBAPI connection associated with this :class:`_engine.Connection`. An attempt will be made to close the underlying DBAPI connection immediately; however if this operation fails, the error is logged but not raised. The connection is then discarded whether or not close() succeeded. Upon the next use (where "use" typically means using the :meth:`_engine.Connection.execute` method or similar), this :class:`_engine.Connection` will attempt to procure a new DBAPI connection using the services of the :class:`_pool.Pool` as a source of connectivity (e.g. a "reconnection"). If a transaction was in progress (e.g. the :meth:`_engine.Connection.begin` method has been called) when :meth:`_engine.Connection.invalidate` method is called, at the DBAPI level all state associated with this transaction is lost, as the DBAPI connection is closed. The :class:`_engine.Connection` will not allow a reconnection to proceed until the :class:`.Transaction` object is ended, by calling the :meth:`.Transaction.rollback` method; until that point, any attempt at continuing to use the :class:`_engine.Connection` will raise an :class:`~sqlalchemy.exc.InvalidRequestError`. This is to prevent applications from accidentally continuing an ongoing transactional operations despite the fact that the transaction has been lost due to an invalidation. The :meth:`_engine.Connection.invalidate` method, just like auto-invalidation, will at the connection pool level invoke the :meth:`_events.PoolEvents.invalidate` event. :param exception: an optional ``Exception`` instance that's the reason for the invalidation. is passed along to event handlers and logging functions. .. seealso:: :ref:`pool_connection_invalidation` """ if self.invalidated: return if self.closed: raise exc.ResourceClosedError("This Connection is closed") if self._still_open_and_dbapi_connection_is_valid: pool_proxied_connection = self._dbapi_connection assert pool_proxied_connection is not None pool_proxied_connection.invalidate(exception) self._dbapi_connection = None def detach(self) -> None: """Detach the underlying DB-API connection from its connection pool. E.g.:: with engine.connect() as conn: conn.detach() conn.execute(text("SET search_path TO schema1, schema2")) # work with connection # connection is fully closed (since we used "with:", can # also call .close()) This :class:`_engine.Connection` instance will remain usable. When closed (or exited from a context manager context as above), the DB-API connection will be literally closed and not returned to its originating pool. This method can be used to insulate the rest of an application from a modified state on a connection (such as a transaction isolation level or similar). """ if self.closed: raise exc.ResourceClosedError("This Connection is closed") pool_proxied_connection = self._dbapi_connection if pool_proxied_connection is None: raise exc.InvalidRequestError( "Can't detach an invalidated Connection" ) pool_proxied_connection.detach() def _autobegin(self) -> None: if self._allow_autobegin and not self.__in_begin: self.begin() def begin(self) -> RootTransaction: """Begin a transaction prior to autobegin occurring. E.g.:: with engine.connect() as conn: with conn.begin() as trans: conn.execute(table.insert(), {"username": "sandy"}) The returned object is an instance of :class:`_engine.RootTransaction`. This object represents the "scope" of the transaction, which completes when either the :meth:`_engine.Transaction.rollback` or :meth:`_engine.Transaction.commit` method is called; the object also works as a context manager as illustrated above. The :meth:`_engine.Connection.begin` method begins a transaction that normally will be begun in any case when the connection is first used to execute a statement. The reason this method might be used would be to invoke the :meth:`_events.ConnectionEvents.begin` event at a specific time, or to organize code within the scope of a connection checkout in terms of context managed blocks, such as:: with engine.connect() as conn: with conn.begin(): conn.execute(...) conn.execute(...) with conn.begin(): conn.execute(...) conn.execute(...) The above code is not fundamentally any different in its behavior than the following code which does not use :meth:`_engine.Connection.begin`; the below style is known as "commit as you go" style:: with engine.connect() as conn: conn.execute(...) conn.execute(...) conn.commit() conn.execute(...) conn.execute(...) conn.commit() From a database point of view, the :meth:`_engine.Connection.begin` method does not emit any SQL or change the state of the underlying DBAPI connection in any way; the Python DBAPI does not have any concept of explicit transaction begin. .. seealso:: :ref:`tutorial_working_with_transactions` - in the :ref:`unified_tutorial` :meth:`_engine.Connection.begin_nested` - use a SAVEPOINT :meth:`_engine.Connection.begin_twophase` - use a two phase /XID transaction :meth:`_engine.Engine.begin` - context manager available from :class:`_engine.Engine` """ if self._transaction is None: self._transaction = RootTransaction(self) return self._transaction else: raise exc.InvalidRequestError( "This connection has already initialized a SQLAlchemy " "Transaction() object via begin() or autobegin; can't " "call begin() here unless rollback() or commit() " "is called first." ) def begin_nested(self) -> NestedTransaction: """Begin a nested transaction (i.e. SAVEPOINT) and return a transaction handle that controls the scope of the SAVEPOINT. E.g.:: with engine.begin() as connection: with connection.begin_nested(): connection.execute(table.insert(), {"username": "sandy"}) The returned object is an instance of :class:`_engine.NestedTransaction`, which includes transactional methods :meth:`_engine.NestedTransaction.commit` and :meth:`_engine.NestedTransaction.rollback`; for a nested transaction, these methods correspond to the operations "RELEASE SAVEPOINT <name>" and "ROLLBACK TO SAVEPOINT <name>". The name of the savepoint is local to the :class:`_engine.NestedTransaction` object and is generated automatically. Like any other :class:`_engine.Transaction`, the :class:`_engine.NestedTransaction` may be used as a context manager as illustrated above which will "release" or "rollback" corresponding to if the operation within the block were successful or raised an exception. Nested transactions require SAVEPOINT support in the underlying database, else the behavior is undefined. SAVEPOINT is commonly used to run operations within a transaction that may fail, while continuing the outer transaction. E.g.:: from sqlalchemy import exc with engine.begin() as connection: trans = connection.begin_nested() try: connection.execute(table.insert(), {"username": "sandy"}) trans.commit() except exc.IntegrityError: # catch for duplicate username trans.rollback() # rollback to savepoint # outer transaction continues connection.execute(...) If :meth:`_engine.Connection.begin_nested` is called without first calling :meth:`_engine.Connection.begin` or :meth:`_engine.Engine.begin`, the :class:`_engine.Connection` object will "autobegin" the outer transaction first. This outer transaction may be committed using "commit-as-you-go" style, e.g.:: with engine.connect() as connection: # begin() wasn't called with connection.begin_nested(): # will auto-"begin()" first connection.execute(...) # savepoint is released connection.execute(...) # explicitly commit outer transaction connection.commit() # can continue working with connection here .. versionchanged:: 2.0 :meth:`_engine.Connection.begin_nested` will now participate in the connection "autobegin" behavior that is new as of 2.0 / "future" style connections in 1.4. .. seealso:: :meth:`_engine.Connection.begin` :ref:`session_begin_nested` - ORM support for SAVEPOINT """ if self._transaction is None: self._autobegin() return NestedTransaction(self) def begin_twophase(self, xid: Optional[Any] = None) -> TwoPhaseTransaction: """Begin a two-phase or XA transaction and return a transaction handle. The returned object is an instance of :class:`.TwoPhaseTransaction`, which in addition to the methods provided by :class:`.Transaction`, also provides a :meth:`~.TwoPhaseTransaction.prepare` method. :param xid: the two phase transaction id. If not supplied, a random id will be generated. .. seealso:: :meth:`_engine.Connection.begin` :meth:`_engine.Connection.begin_twophase` """ if self._transaction is not None: raise exc.InvalidRequestError( "Cannot start a two phase transaction when a transaction " "is already in progress." ) if xid is None: xid = self.engine.dialect.create_xid() return TwoPhaseTransaction(self, xid) def commit(self) -> None: """Commit the transaction that is currently in progress. This method commits the current transaction if one has been started. If no transaction was started, the method has no effect, assuming the connection is in a non-invalidated state. A transaction is begun on a :class:`_engine.Connection` automatically whenever a statement is first executed, or when the :meth:`_engine.Connection.begin` method is called. .. note:: The :meth:`_engine.Connection.commit` method only acts upon the primary database transaction that is linked to the :class:`_engine.Connection` object. It does not operate upon a SAVEPOINT that would have been invoked from the :meth:`_engine.Connection.begin_nested` method; for control of a SAVEPOINT, call :meth:`_engine.NestedTransaction.commit` on the :class:`_engine.NestedTransaction` that is returned by the :meth:`_engine.Connection.begin_nested` method itself. """ if self._transaction: self._transaction.commit() def rollback(self) -> None: """Roll back the transaction that is currently in progress. This method rolls back the current transaction if one has been started. If no transaction was started, the method has no effect. If a transaction was started and the connection is in an invalidated state, the transaction is cleared using this method. A transaction is begun on a :class:`_engine.Connection` automatically whenever a statement is first executed, or when the :meth:`_engine.Connection.begin` method is called. .. note:: The :meth:`_engine.Connection.rollback` method only acts upon the primary database transaction that is linked to the :class:`_engine.Connection` object. It does not operate upon a SAVEPOINT that would have been invoked from the :meth:`_engine.Connection.begin_nested` method; for control of a SAVEPOINT, call :meth:`_engine.NestedTransaction.rollback` on the :class:`_engine.NestedTransaction` that is returned by the :meth:`_engine.Connection.begin_nested` method itself. """ if self._transaction: self._transaction.rollback() def recover_twophase(self) -> List[Any]: return self.engine.dialect.do_recover_twophase(self) def rollback_prepared(self, xid: Any, recover: bool = False) -> None: self.engine.dialect.do_rollback_twophase(self, xid, recover=recover) def commit_prepared(self, xid: Any, recover: bool = False) -> None: self.engine.dialect.do_commit_twophase(self, xid, recover=recover) def in_transaction(self) -> bool: """Return True if a transaction is in progress.""" return self._transaction is not None and self._transaction.is_active def in_nested_transaction(self) -> bool: """Return True if a transaction is in progress.""" return ( self._nested_transaction is not None and self._nested_transaction.is_active ) def _is_autocommit_isolation(self) -> bool: opt_iso = self._execution_options.get("isolation_level", None) return bool( opt_iso == "AUTOCOMMIT" or ( opt_iso is None and self.engine.dialect._on_connect_isolation_level == "AUTOCOMMIT" ) ) def _get_required_transaction(self) -> RootTransaction: trans = self._transaction if trans is None: raise exc.InvalidRequestError("connection is not in a transaction") return trans def _get_required_nested_transaction(self) -> NestedTransaction: trans = self._nested_transaction if trans is None: raise exc.InvalidRequestError( "connection is not in a nested transaction" ) return trans def get_transaction(self) -> Optional[RootTransaction]: """Return the current root transaction in progress, if any. .. versionadded:: 1.4 """ return self._transaction def get_nested_transaction(self) -> Optional[NestedTransaction]: """Return the current nested transaction in progress, if any. .. versionadded:: 1.4 """ return self._nested_transaction def _begin_impl(self, transaction: RootTransaction) -> None: if self._echo: if self._is_autocommit_isolation(): self._log_info( "BEGIN (implicit; DBAPI should not BEGIN due to " "autocommit mode)" ) else: self._log_info("BEGIN (implicit)") self.__in_begin = True if self._has_events or self.engine._has_events: self.dispatch.begin(self) try: self.engine.dialect.do_begin(self.connection) except BaseException as e: self._handle_dbapi_exception(e, None, None, None, None) finally: self.__in_begin = False def _rollback_impl(self) -> None: if self._has_events or self.engine._has_events: self.dispatch.rollback(self) if self._still_open_and_dbapi_connection_is_valid: if self._echo: if self._is_autocommit_isolation(): self._log_info( "ROLLBACK using DBAPI connection.rollback(), " "DBAPI should ignore due to autocommit mode" ) else: self._log_info("ROLLBACK") try: self.engine.dialect.do_rollback(self.connection) except BaseException as e: self._handle_dbapi_exception(e, None, None, None, None) def _commit_impl(self) -> None: if self._has_events or self.engine._has_events: self.dispatch.commit(self) if self._echo: if self._is_autocommit_isolation(): self._log_info( "COMMIT using DBAPI connection.commit(), " "DBAPI should ignore due to autocommit mode" ) else: self._log_info("COMMIT") try: self.engine.dialect.do_commit(self.connection) except BaseException as e: self._handle_dbapi_exception(e, None, None, None, None) def _savepoint_impl(self, name: Optional[str] = None) -> str: if self._has_events or self.engine._has_events: self.dispatch.savepoint(self, name) if name is None: self.__savepoint_seq += 1 name = "sa_savepoint_%s" % self.__savepoint_seq self.engine.dialect.do_savepoint(self, name) return name def _rollback_to_savepoint_impl(self, name: str) -> None: if self._has_events or self.engine._has_events: self.dispatch.rollback_savepoint(self, name, None) if self._still_open_and_dbapi_connection_is_valid: self.engine.dialect.do_rollback_to_savepoint(self, name) def _release_savepoint_impl(self, name: str) -> None: if self._has_events or self.engine._has_events: self.dispatch.release_savepoint(self, name, None) self.engine.dialect.do_release_savepoint(self, name) def _begin_twophase_impl(self, transaction: TwoPhaseTransaction) -> None: if self._echo: self._log_info("BEGIN TWOPHASE (implicit)") if self._has_events or self.engine._has_events: self.dispatch.begin_twophase(self, transaction.xid) self.__in_begin = True try: self.engine.dialect.do_begin_twophase(self, transaction.xid) except BaseException as e: self._handle_dbapi_exception(e, None, None, None, None) finally: self.__in_begin = False def _prepare_twophase_impl(self, xid: Any) -> None: if self._has_events or self.engine._has_events: self.dispatch.prepare_twophase(self, xid) assert isinstance(self._transaction, TwoPhaseTransaction) try: self.engine.dialect.do_prepare_twophase(self, xid) except BaseException as e: self._handle_dbapi_exception(e, None, None, None, None) def _rollback_twophase_impl(self, xid: Any, is_prepared: bool) -> None: if self._has_events or self.engine._has_events: self.dispatch.rollback_twophase(self, xid, is_prepared) if self._still_open_and_dbapi_connection_is_valid: assert isinstance(self._transaction, TwoPhaseTransaction) try: self.engine.dialect.do_rollback_twophase( self, xid, is_prepared ) except BaseException as e: self._handle_dbapi_exception(e, None, None, None, None) def _commit_twophase_impl(self, xid: Any, is_prepared: bool) -> None: if self._has_events or self.engine._has_events: self.dispatch.commit_twophase(self, xid, is_prepared) assert isinstance(self._transaction, TwoPhaseTransaction) try: self.engine.dialect.do_commit_twophase(self, xid, is_prepared) except BaseException as e: self._handle_dbapi_exception(e, None, None, None, None) def close(self) -> None: """Close this :class:`_engine.Connection`. This results in a release of the underlying database resources, that is, the DBAPI connection referenced internally. The DBAPI connection is typically restored back to the connection-holding :class:`_pool.Pool` referenced by the :class:`_engine.Engine` that produced this :class:`_engine.Connection`. Any transactional state present on the DBAPI connection is also unconditionally released via the DBAPI connection's ``rollback()`` method, regardless of any :class:`.Transaction` object that may be outstanding with regards to this :class:`_engine.Connection`. This has the effect of also calling :meth:`_engine.Connection.rollback` if any transaction is in place. After :meth:`_engine.Connection.close` is called, the :class:`_engine.Connection` is permanently in a closed state, and will allow no further operations. """ if self._transaction: self._transaction.close() skip_reset = True else: skip_reset = False if self._dbapi_connection is not None: conn = self._dbapi_connection # as we just closed the transaction, close the connection # pool connection without doing an additional reset if skip_reset: cast("_ConnectionFairy", conn)._close_special( transaction_reset=True ) else: conn.close() # There is a slight chance that conn.close() may have # triggered an invalidation here in which case # _dbapi_connection would already be None, however usually # it will be non-None here and in a "closed" state. self._dbapi_connection = None self.__can_reconnect = False @overload def scalar( self, statement: TypedReturnsRows[Tuple[_T]], parameters: Optional[_CoreSingleExecuteParams] = None, *, execution_options: Optional[CoreExecuteOptionsParameter] = None, ) -> Optional[_T]: ... @overload def scalar( self, statement: Executable, parameters: Optional[_CoreSingleExecuteParams] = None, *, execution_options: Optional[CoreExecuteOptionsParameter] = None, ) -> Any: ... def scalar( self, statement: Executable, parameters: Optional[_CoreSingleExecuteParams] = None, *, execution_options: Optional[CoreExecuteOptionsParameter] = None, ) -> Any: r"""Executes a SQL statement construct and returns a scalar object. This method is shorthand for invoking the :meth:`_engine.Result.scalar` method after invoking the :meth:`_engine.Connection.execute` method. Parameters are equivalent. :return: a scalar Python value representing the first column of the first row returned. """ distilled_parameters = _distill_params_20(parameters) try: meth = statement._execute_on_scalar except AttributeError as err: raise exc.ObjectNotExecutableError(statement) from err else: return meth( self, distilled_parameters, execution_options or NO_OPTIONS, ) @overload def scalars( self, statement: TypedReturnsRows[Tuple[_T]], parameters: Optional[_CoreAnyExecuteParams] = None, *, execution_options: Optional[CoreExecuteOptionsParameter] = None, ) -> ScalarResult[_T]: ... @overload def scalars( self, statement: Executable, parameters: Optional[_CoreAnyExecuteParams] = None, *, execution_options: Optional[CoreExecuteOptionsParameter] = None, ) -> ScalarResult[Any]: ... def scalars( self, statement: Executable, parameters: Optional[_CoreAnyExecuteParams] = None, *, execution_options: Optional[CoreExecuteOptionsParameter] = None, ) -> ScalarResult[Any]: """Executes and returns a scalar result set, which yields scalar values from the first column of each row. This method is equivalent to calling :meth:`_engine.Connection.execute` to receive a :class:`_result.Result` object, then invoking the :meth:`_result.Result.scalars` method to produce a :class:`_result.ScalarResult` instance. :return: a :class:`_result.ScalarResult` .. versionadded:: 1.4.24 """ return self.execute( statement, parameters, execution_options=execution_options ).scalars() @overload def execute( self, statement: TypedReturnsRows[_T], parameters: Optional[_CoreAnyExecuteParams] = None, *, execution_options: Optional[CoreExecuteOptionsParameter] = None, ) -> CursorResult[_T]: ... @overload def execute( self, statement: Executable, parameters: Optional[_CoreAnyExecuteParams] = None, *, execution_options: Optional[CoreExecuteOptionsParameter] = None, ) -> CursorResult[Any]: ... def execute( self, statement: Executable, parameters: Optional[_CoreAnyExecuteParams] = None, *, execution_options: Optional[CoreExecuteOptionsParameter] = None, ) -> CursorResult[Any]: r"""Executes a SQL statement construct and returns a :class:`_engine.CursorResult`. :param statement: The statement to be executed. This is always an object that is in both the :class:`_expression.ClauseElement` and :class:`_expression.Executable` hierarchies, including: * :class:`_expression.Select` * :class:`_expression.Insert`, :class:`_expression.Update`, :class:`_expression.Delete` * :class:`_expression.TextClause` and :class:`_expression.TextualSelect` * :class:`_schema.DDL` and objects which inherit from :class:`_schema.ExecutableDDLElement` :param parameters: parameters which will be bound into the statement. This may be either a dictionary of parameter names to values, or a mutable sequence (e.g. a list) of dictionaries. When a list of dictionaries is passed, the underlying statement execution will make use of the DBAPI ``cursor.executemany()`` method. When a single dictionary is passed, the DBAPI ``cursor.execute()`` method will be used. :param execution_options: optional dictionary of execution options, which will be associated with the statement execution. This dictionary can provide a subset of the options that are accepted by :meth:`_engine.Connection.execution_options`. :return: a :class:`_engine.Result` object. """ distilled_parameters = _distill_params_20(parameters) try: meth = statement._execute_on_connection except AttributeError as err: raise exc.ObjectNotExecutableError(statement) from err else: return meth( self, distilled_parameters, execution_options or NO_OPTIONS, ) def _execute_function( self, func: FunctionElement[Any], distilled_parameters: _CoreMultiExecuteParams, execution_options: CoreExecuteOptionsParameter, ) -> CursorResult[Any]: """Execute a sql.FunctionElement object.""" return self._execute_clauseelement( func.select(), distilled_parameters, execution_options ) def _execute_default( self, default: DefaultGenerator, distilled_parameters: _CoreMultiExecuteParams, execution_options: CoreExecuteOptionsParameter, ) -> Any: """Execute a schema.ColumnDefault object.""" execution_options = self._execution_options.merge_with( execution_options ) event_multiparams: Optional[_CoreMultiExecuteParams] event_params: Optional[_CoreAnyExecuteParams] # note for event handlers, the "distilled parameters" which is always # a list of dicts is broken out into separate "multiparams" and # "params" collections, which allows the handler to distinguish # between an executemany and execute style set of parameters. if self._has_events or self.engine._has_events: ( default, distilled_parameters, event_multiparams, event_params, ) = self._invoke_before_exec_event( default, distilled_parameters, execution_options ) else: event_multiparams = event_params = None try: conn = self._dbapi_connection if conn is None: conn = self._revalidate_connection() dialect = self.dialect ctx = dialect.execution_ctx_cls._init_default( dialect, self, conn, execution_options ) except (exc.PendingRollbackError, exc.ResourceClosedError): raise except BaseException as e: self._handle_dbapi_exception(e, None, None, None, None) ret = ctx._exec_default(None, default, None) if self._has_events or self.engine._has_events: self.dispatch.after_execute( self, default, event_multiparams, event_params, execution_options, ret, ) return ret def _execute_ddl( self, ddl: ExecutableDDLElement, distilled_parameters: _CoreMultiExecuteParams, execution_options: CoreExecuteOptionsParameter, ) -> CursorResult[Any]: """Execute a schema.DDL object.""" exec_opts = ddl._execution_options.merge_with( self._execution_options, execution_options ) event_multiparams: Optional[_CoreMultiExecuteParams] event_params: Optional[_CoreSingleExecuteParams] if self._has_events or self.engine._has_events: ( ddl, distilled_parameters, event_multiparams, event_params, ) = self._invoke_before_exec_event( ddl, distilled_parameters, exec_opts ) else: event_multiparams = event_params = None schema_translate_map = exec_opts.get("schema_translate_map", None) dialect = self.dialect compiled = ddl.compile( dialect=dialect, schema_translate_map=schema_translate_map ) ret = self._execute_context( dialect, dialect.execution_ctx_cls._init_ddl, compiled, None, exec_opts, compiled, ) if self._has_events or self.engine._has_events: self.dispatch.after_execute( self, ddl, event_multiparams, event_params, exec_opts, ret, ) return ret def _invoke_before_exec_event( self, elem: Any, distilled_params: _CoreMultiExecuteParams, execution_options: _ExecuteOptions, ) -> Tuple[ Any, _CoreMultiExecuteParams, _CoreMultiExecuteParams, _CoreSingleExecuteParams, ]: event_multiparams: _CoreMultiExecuteParams event_params: _CoreSingleExecuteParams if len(distilled_params) == 1: event_multiparams, event_params = [], distilled_params[0] else: event_multiparams, event_params = distilled_params, {} for fn in self.dispatch.before_execute: elem, event_multiparams, event_params = fn( self, elem, event_multiparams, event_params, execution_options, ) if event_multiparams: distilled_params = list(event_multiparams) if event_params: raise exc.InvalidRequestError( "Event handler can't return non-empty multiparams " "and params at the same time" ) elif event_params: distilled_params = [event_params] else: distilled_params = [] return elem, distilled_params, event_multiparams, event_params def _execute_clauseelement( self, elem: Executable, distilled_parameters: _CoreMultiExecuteParams, execution_options: CoreExecuteOptionsParameter, ) -> CursorResult[Any]: """Execute a sql.ClauseElement object.""" execution_options = elem._execution_options.merge_with( self._execution_options, execution_options ) has_events = self._has_events or self.engine._has_events if has_events: ( elem, distilled_parameters, event_multiparams, event_params, ) = self._invoke_before_exec_event( elem, distilled_parameters, execution_options ) if distilled_parameters: # ensure we don't retain a link to the view object for keys() # which links to the values, which we don't want to cache keys = sorted(distilled_parameters[0]) for_executemany = len(distilled_parameters) > 1 else: keys = [] for_executemany = False dialect = self.dialect schema_translate_map = execution_options.get( "schema_translate_map", None ) compiled_cache: Optional[CompiledCacheType] = execution_options.get( "compiled_cache", self.engine._compiled_cache ) compiled_sql, extracted_params, cache_hit = elem._compile_w_cache( dialect=dialect, compiled_cache=compiled_cache, column_keys=keys, for_executemany=for_executemany, schema_translate_map=schema_translate_map, linting=self.dialect.compiler_linting | compiler.WARN_LINTING, ) ret = self._execute_context( dialect, dialect.execution_ctx_cls._init_compiled, compiled_sql, distilled_parameters, execution_options, compiled_sql, distilled_parameters, elem, extracted_params, cache_hit=cache_hit, ) if has_events: self.dispatch.after_execute( self, elem, event_multiparams, event_params, execution_options, ret, ) return ret def _execute_compiled( self, compiled: Compiled, distilled_parameters: _CoreMultiExecuteParams, execution_options: CoreExecuteOptionsParameter = _EMPTY_EXECUTION_OPTS, ) -> CursorResult[Any]: """Execute a sql.Compiled object. TODO: why do we have this? likely deprecate or remove """ execution_options = compiled.execution_options.merge_with( self._execution_options, execution_options ) if self._has_events or self.engine._has_events: ( compiled, distilled_parameters, event_multiparams, event_params, ) = self._invoke_before_exec_event( compiled, distilled_parameters, execution_options ) dialect = self.dialect ret = self._execute_context( dialect, dialect.execution_ctx_cls._init_compiled, compiled, distilled_parameters, execution_options, compiled, distilled_parameters, None, None, ) if self._has_events or self.engine._has_events: self.dispatch.after_execute( self, compiled, event_multiparams, event_params, execution_options, ret, ) return ret def exec_driver_sql( self, statement: str, parameters: Optional[_DBAPIAnyExecuteParams] = None, execution_options: Optional[CoreExecuteOptionsParameter] = None, ) -> CursorResult[Any]: r"""Executes a string SQL statement on the DBAPI cursor directly, without any SQL compilation steps. This can be used to pass any string directly to the ``cursor.execute()`` method of the DBAPI in use. :param statement: The statement str to be executed. Bound parameters must use the underlying DBAPI's paramstyle, such as "qmark", "pyformat", "format", etc. :param parameters: represent bound parameter values to be used in the execution. The format is one of: a dictionary of named parameters, a tuple of positional parameters, or a list containing either dictionaries or tuples for multiple-execute support. :return: a :class:`_engine.CursorResult`. E.g. multiple dictionaries:: conn.exec_driver_sql( "INSERT INTO table (id, value) VALUES (%(id)s, %(value)s)", [{"id": 1, "value": "v1"}, {"id": 2, "value": "v2"}], ) Single dictionary:: conn.exec_driver_sql( "INSERT INTO table (id, value) VALUES (%(id)s, %(value)s)", dict(id=1, value="v1"), ) Single tuple:: conn.exec_driver_sql( "INSERT INTO table (id, value) VALUES (?, ?)", (1, "v1") ) .. note:: The :meth:`_engine.Connection.exec_driver_sql` method does not participate in the :meth:`_events.ConnectionEvents.before_execute` and :meth:`_events.ConnectionEvents.after_execute` events. To intercept calls to :meth:`_engine.Connection.exec_driver_sql`, use :meth:`_events.ConnectionEvents.before_cursor_execute` and :meth:`_events.ConnectionEvents.after_cursor_execute`. .. seealso:: :pep:`249` """ distilled_parameters = _distill_raw_params(parameters) execution_options = self._execution_options.merge_with( execution_options ) dialect = self.dialect ret = self._execute_context( dialect, dialect.execution_ctx_cls._init_statement, statement, None, execution_options, statement, distilled_parameters, ) return ret def _execute_context( self, dialect: Dialect, constructor: Callable[..., ExecutionContext], statement: Union[str, Compiled], parameters: Optional[_AnyMultiExecuteParams], execution_options: _ExecuteOptions, *args: Any, **kw: Any, ) -> CursorResult[Any]: """Create an :class:`.ExecutionContext` and execute, returning a :class:`_engine.CursorResult`.""" if execution_options: yp = execution_options.get("yield_per", None) if yp: execution_options = execution_options.union( {"stream_results": True, "max_row_buffer": yp} ) try: conn = self._dbapi_connection if conn is None: conn = self._revalidate_connection() context = constructor( dialect, self, conn, execution_options, *args, **kw ) except (exc.PendingRollbackError, exc.ResourceClosedError): raise except BaseException as e: self._handle_dbapi_exception( e, str(statement), parameters, None, None ) if ( self._transaction and not self._transaction.is_active or ( self._nested_transaction and not self._nested_transaction.is_active ) ): self._invalid_transaction() elif self._trans_context_manager: TransactionalContext._trans_ctx_check(self) if self._transaction is None: self._autobegin() context.pre_exec() if context.execute_style is ExecuteStyle.INSERTMANYVALUES: return self._exec_insertmany_context(dialect, context) else: return self._exec_single_context( dialect, context, statement, parameters ) def _exec_single_context( self, dialect: Dialect, context: ExecutionContext, statement: Union[str, Compiled], parameters: Optional[_AnyMultiExecuteParams], ) -> CursorResult[Any]: """continue the _execute_context() method for a single DBAPI cursor.execute() or cursor.executemany() call. """ if dialect.bind_typing is BindTyping.SETINPUTSIZES: generic_setinputsizes = context._prepare_set_input_sizes() if generic_setinputsizes: try: dialect.do_set_input_sizes( context.cursor, generic_setinputsizes, context ) except BaseException as e: self._handle_dbapi_exception( e, str(statement), parameters, None, context ) cursor, str_statement, parameters = ( context.cursor, context.statement, context.parameters, ) effective_parameters: Optional[_AnyExecuteParams] if not context.executemany: effective_parameters = parameters[0] else: effective_parameters = parameters if self._has_events or self.engine._has_events: for fn in self.dispatch.before_cursor_execute: str_statement, effective_parameters = fn( self, cursor, str_statement, effective_parameters, context, context.executemany, ) if self._echo: self._log_info(str_statement) stats = context._get_cache_stats() if not self.engine.hide_parameters: self._log_info( "[%s] %r", stats, sql_util._repr_params( effective_parameters, batches=10, ismulti=context.executemany, ), ) else: self._log_info( "[%s] [SQL parameters hidden due to hide_parameters=True]", stats, ) evt_handled: bool = False try: if context.execute_style is ExecuteStyle.EXECUTEMANY: effective_parameters = cast( "_CoreMultiExecuteParams", effective_parameters ) if self.dialect._has_events: for fn in self.dialect.dispatch.do_executemany: if fn( cursor, str_statement, effective_parameters, context, ): evt_handled = True break if not evt_handled: self.dialect.do_executemany( cursor, str_statement, effective_parameters, context, ) elif not effective_parameters and context.no_parameters: if self.dialect._has_events: for fn in self.dialect.dispatch.do_execute_no_params: if fn(cursor, str_statement, context): evt_handled = True break if not evt_handled: self.dialect.do_execute_no_params( cursor, str_statement, context ) else: effective_parameters = cast( "_CoreSingleExecuteParams", effective_parameters ) if self.dialect._has_events: for fn in self.dialect.dispatch.do_execute: if fn( cursor, str_statement, effective_parameters, context, ): evt_handled = True break if not evt_handled: self.dialect.do_execute( cursor, str_statement, effective_parameters, context ) if self._has_events or self.engine._has_events: self.dispatch.after_cursor_execute( self, cursor, str_statement, effective_parameters, context, context.executemany, ) context.post_exec() result = context._setup_result_proxy() except BaseException as e: self._handle_dbapi_exception( e, str_statement, effective_parameters, cursor, context ) return result def _exec_insertmany_context( self, dialect: Dialect, context: ExecutionContext, ) -> CursorResult[Any]: """continue the _execute_context() method for an "insertmanyvalues" operation, which will invoke DBAPI cursor.execute() one or more times with individual log and event hook calls. """ if dialect.bind_typing is BindTyping.SETINPUTSIZES: generic_setinputsizes = context._prepare_set_input_sizes() else: generic_setinputsizes = None cursor, str_statement, parameters = ( context.cursor, context.statement, context.parameters, ) effective_parameters = parameters engine_events = self._has_events or self.engine._has_events if self.dialect._has_events: do_execute_dispatch: Iterable[Any] = ( self.dialect.dispatch.do_execute ) else: do_execute_dispatch = () if self._echo: stats = context._get_cache_stats() + " (insertmanyvalues)" preserve_rowcount = context.execution_options.get( "preserve_rowcount", False ) rowcount = 0 for imv_batch in dialect._deliver_insertmanyvalues_batches( self, cursor, str_statement, effective_parameters, generic_setinputsizes, context, ): if imv_batch.processed_setinputsizes: try: dialect.do_set_input_sizes( context.cursor, imv_batch.processed_setinputsizes, context, ) except BaseException as e: self._handle_dbapi_exception( e, sql_util._long_statement(imv_batch.replaced_statement), imv_batch.replaced_parameters, None, context, is_sub_exec=True, ) sub_stmt = imv_batch.replaced_statement sub_params = imv_batch.replaced_parameters if engine_events: for fn in self.dispatch.before_cursor_execute: sub_stmt, sub_params = fn( self, cursor, sub_stmt, sub_params, context, True, ) if self._echo: self._log_info(sql_util._long_statement(sub_stmt)) imv_stats = f""" {imv_batch.batchnum}/{ imv_batch.total_batches } ({ 'ordered' if imv_batch.rows_sorted else 'unordered' }{ '; batch not supported' if imv_batch.is_downgraded else '' })""" if imv_batch.batchnum == 1: stats += imv_stats else: stats = f"insertmanyvalues{imv_stats}" if not self.engine.hide_parameters: self._log_info( "[%s] %r", stats, sql_util._repr_params( sub_params, batches=10, ismulti=False, ), ) else: self._log_info( "[%s] [SQL parameters hidden due to " "hide_parameters=True]", stats, ) try: for fn in do_execute_dispatch: if fn( cursor, sub_stmt, sub_params, context, ): break else: dialect.do_execute( cursor, sub_stmt, sub_params, context, ) except BaseException as e: self._handle_dbapi_exception( e, sql_util._long_statement(sub_stmt), sub_params, cursor, context, is_sub_exec=True, ) if engine_events: self.dispatch.after_cursor_execute( self, cursor, str_statement, effective_parameters, context, context.executemany, ) if preserve_rowcount: rowcount += imv_batch.current_batch_size try: context.post_exec() if preserve_rowcount: context._rowcount = rowcount # type: ignore[attr-defined] result = context._setup_result_proxy() except BaseException as e: self._handle_dbapi_exception( e, str_statement, effective_parameters, cursor, context ) return result def _cursor_execute( self, cursor: DBAPICursor, statement: str, parameters: _DBAPISingleExecuteParams, context: Optional[ExecutionContext] = None, ) -> None: """Execute a statement + params on the given cursor. Adds appropriate logging and exception handling. This method is used by DefaultDialect for special-case executions, such as for sequences and column defaults. The path of statement execution in the majority of cases terminates at _execute_context(). """ if self._has_events or self.engine._has_events: for fn in self.dispatch.before_cursor_execute: statement, parameters = fn( self, cursor, statement, parameters, context, False ) if self._echo: self._log_info(statement) self._log_info("[raw sql] %r", parameters) try: for fn in ( () if not self.dialect._has_events else self.dialect.dispatch.do_execute ): if fn(cursor, statement, parameters, context): break else: self.dialect.do_execute(cursor, statement, parameters, context) except BaseException as e: self._handle_dbapi_exception( e, statement, parameters, cursor, context ) if self._has_events or self.engine._has_events: self.dispatch.after_cursor_execute( self, cursor, statement, parameters, context, False ) def _safe_close_cursor(self, cursor: DBAPICursor) -> None: """Close the given cursor, catching exceptions and turning into log warnings. """ try: cursor.close() except Exception: # log the error through the connection pool's logger. self.engine.pool.logger.error( "Error closing cursor", exc_info=True ) _reentrant_error = False _is_disconnect = False def _handle_dbapi_exception( self, e: BaseException, statement: Optional[str], parameters: Optional[_AnyExecuteParams], cursor: Optional[DBAPICursor], context: Optional[ExecutionContext], is_sub_exec: bool = False, ) -> NoReturn: exc_info = sys.exc_info() is_exit_exception = util.is_exit_exception(e) if not self._is_disconnect: self._is_disconnect = ( isinstance(e, self.dialect.loaded_dbapi.Error) and not self.closed and self.dialect.is_disconnect( e, self._dbapi_connection if not self.invalidated else None, cursor, ) ) or (is_exit_exception and not self.closed) invalidate_pool_on_disconnect = not is_exit_exception ismulti: bool = ( not is_sub_exec and context.executemany if context is not None else False ) if self._reentrant_error: raise exc.DBAPIError.instance( statement, parameters, e, self.dialect.loaded_dbapi.Error, hide_parameters=self.engine.hide_parameters, dialect=self.dialect, ismulti=ismulti, ).with_traceback(exc_info[2]) from e self._reentrant_error = True try: # non-DBAPI error - if we already got a context, # or there's no string statement, don't wrap it should_wrap = isinstance(e, self.dialect.loaded_dbapi.Error) or ( statement is not None and context is None and not is_exit_exception ) if should_wrap: sqlalchemy_exception = exc.DBAPIError.instance( statement, parameters, cast(Exception, e), self.dialect.loaded_dbapi.Error, hide_parameters=self.engine.hide_parameters, connection_invalidated=self._is_disconnect, dialect=self.dialect, ismulti=ismulti, ) else: sqlalchemy_exception = None newraise = None if (self.dialect._has_events) and not self._execution_options.get( "skip_user_error_events", False ): ctx = ExceptionContextImpl( e, sqlalchemy_exception, self.engine, self.dialect, self, cursor, statement, parameters, context, self._is_disconnect, invalidate_pool_on_disconnect, False, ) for fn in self.dialect.dispatch.handle_error: try: # handler returns an exception; # call next handler in a chain per_fn = fn(ctx) if per_fn is not None: ctx.chained_exception = newraise = per_fn except Exception as _raised: # handler raises an exception - stop processing newraise = _raised break if self._is_disconnect != ctx.is_disconnect: self._is_disconnect = ctx.is_disconnect if sqlalchemy_exception: sqlalchemy_exception.connection_invalidated = ( ctx.is_disconnect ) # set up potentially user-defined value for # invalidate pool. invalidate_pool_on_disconnect = ( ctx.invalidate_pool_on_disconnect ) if should_wrap and context: context.handle_dbapi_exception(e) if not self._is_disconnect: if cursor: self._safe_close_cursor(cursor) # "autorollback" was mostly relevant in 1.x series. # It's very unlikely to reach here, as the connection # does autobegin so when we are here, we are usually # in an explicit / semi-explicit transaction. # however we have a test which manufactures this # scenario in any case using an event handler. # test/engine/test_execute.py-> test_actual_autorollback if not self.in_transaction(): self._rollback_impl() if newraise: raise newraise.with_traceback(exc_info[2]) from e elif should_wrap: assert sqlalchemy_exception is not None raise sqlalchemy_exception.with_traceback(exc_info[2]) from e else: assert exc_info[1] is not None raise exc_info[1].with_traceback(exc_info[2]) finally: del self._reentrant_error if self._is_disconnect: del self._is_disconnect if not self.invalidated: dbapi_conn_wrapper = self._dbapi_connection assert dbapi_conn_wrapper is not None if invalidate_pool_on_disconnect: self.engine.pool._invalidate(dbapi_conn_wrapper, e) self.invalidate(e) @classmethod def _handle_dbapi_exception_noconnection( cls, e: BaseException, dialect: Dialect, engine: Optional[Engine] = None, is_disconnect: Optional[bool] = None, invalidate_pool_on_disconnect: bool = True, is_pre_ping: bool = False, ) -> NoReturn: exc_info = sys.exc_info() if is_disconnect is None: is_disconnect = isinstance( e, dialect.loaded_dbapi.Error ) and dialect.is_disconnect(e, None, None) should_wrap = isinstance(e, dialect.loaded_dbapi.Error) if should_wrap: sqlalchemy_exception = exc.DBAPIError.instance( None, None, cast(Exception, e), dialect.loaded_dbapi.Error, hide_parameters=( engine.hide_parameters if engine is not None else False ), connection_invalidated=is_disconnect, dialect=dialect, ) else: sqlalchemy_exception = None newraise = None if dialect._has_events: ctx = ExceptionContextImpl( e, sqlalchemy_exception, engine, dialect, None, None, None, None, None, is_disconnect, invalidate_pool_on_disconnect, is_pre_ping, ) for fn in dialect.dispatch.handle_error: try: # handler returns an exception; # call next handler in a chain per_fn = fn(ctx) if per_fn is not None: ctx.chained_exception = newraise = per_fn except Exception as _raised: # handler raises an exception - stop processing newraise = _raised break if sqlalchemy_exception and is_disconnect != ctx.is_disconnect: sqlalchemy_exception.connection_invalidated = ctx.is_disconnect if newraise: raise newraise.with_traceback(exc_info[2]) from e elif should_wrap: assert sqlalchemy_exception is not None raise sqlalchemy_exception.with_traceback(exc_info[2]) from e else: assert exc_info[1] is not None raise exc_info[1].with_traceback(exc_info[2]) def _run_ddl_visitor( self, visitorcallable: Type[InvokeDDLBase], element: SchemaVisitable, **kwargs: Any, ) -> None: """run a DDL visitor. This method is only here so that the MockConnection can change the options given to the visitor so that "checkfirst" is skipped. """ visitorcallable( dialect=self.dialect, connection=self, **kwargs ).traverse_single(element) class ExceptionContextImpl(ExceptionContext): """Implement the :class:`.ExceptionContext` interface.""" __slots__ = ( "connection", "engine", "dialect", "cursor", "statement", "parameters", "original_exception", "sqlalchemy_exception", "chained_exception", "execution_context", "is_disconnect", "invalidate_pool_on_disconnect", "is_pre_ping", ) def __init__( self, exception: BaseException, sqlalchemy_exception: Optional[exc.StatementError], engine: Optional[Engine], dialect: Dialect, connection: Optional[Connection], cursor: Optional[DBAPICursor], statement: Optional[str], parameters: Optional[_DBAPIAnyExecuteParams], context: Optional[ExecutionContext], is_disconnect: bool, invalidate_pool_on_disconnect: bool, is_pre_ping: bool, ): self.engine = engine self.dialect = dialect self.connection = connection self.sqlalchemy_exception = sqlalchemy_exception self.original_exception = exception self.execution_context = context self.statement = statement self.parameters = parameters self.is_disconnect = is_disconnect self.invalidate_pool_on_disconnect = invalidate_pool_on_disconnect self.is_pre_ping = is_pre_ping class Transaction(TransactionalContext): """Represent a database transaction in progress. The :class:`.Transaction` object is procured by calling the :meth:`_engine.Connection.begin` method of :class:`_engine.Connection`:: from sqlalchemy import create_engine engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test") connection = engine.connect() trans = connection.begin() connection.execute(text("insert into x (a, b) values (1, 2)")) trans.commit() The object provides :meth:`.rollback` and :meth:`.commit` methods in order to control transaction boundaries. It also implements a context manager interface so that the Python ``with`` statement can be used with the :meth:`_engine.Connection.begin` method:: with connection.begin(): connection.execute(text("insert into x (a, b) values (1, 2)")) The Transaction object is **not** threadsafe. .. seealso:: :meth:`_engine.Connection.begin` :meth:`_engine.Connection.begin_twophase` :meth:`_engine.Connection.begin_nested` .. index:: single: thread safety; Transaction """ # noqa __slots__ = () _is_root: bool = False is_active: bool connection: Connection def __init__(self, connection: Connection): raise NotImplementedError() @property def _deactivated_from_connection(self) -> bool: """True if this transaction is totally deactivated from the connection and therefore can no longer affect its state. """ raise NotImplementedError() def _do_close(self) -> None: raise NotImplementedError() def _do_rollback(self) -> None: raise NotImplementedError() def _do_commit(self) -> None: raise NotImplementedError() @property def is_valid(self) -> bool: return self.is_active and not self.connection.invalidated def close(self) -> None: """Close this :class:`.Transaction`. If this transaction is the base transaction in a begin/commit nesting, the transaction will rollback(). Otherwise, the method returns. This is used to cancel a Transaction without affecting the scope of an enclosing transaction. """ try: self._do_close() finally: assert not self.is_active def rollback(self) -> None: """Roll back this :class:`.Transaction`. The implementation of this may vary based on the type of transaction in use: * For a simple database transaction (e.g. :class:`.RootTransaction`), it corresponds to a ROLLBACK. * For a :class:`.NestedTransaction`, it corresponds to a "ROLLBACK TO SAVEPOINT" operation. * For a :class:`.TwoPhaseTransaction`, DBAPI-specific methods for two phase transactions may be used. """ try: self._do_rollback() finally: assert not self.is_active def commit(self) -> None: """Commit this :class:`.Transaction`. The implementation of this may vary based on the type of transaction in use: * For a simple database transaction (e.g. :class:`.RootTransaction`), it corresponds to a COMMIT. * For a :class:`.NestedTransaction`, it corresponds to a "RELEASE SAVEPOINT" operation. * For a :class:`.TwoPhaseTransaction`, DBAPI-specific methods for two phase transactions may be used. """ try: self._do_commit() finally: assert not self.is_active def _get_subject(self) -> Connection: return self.connection def _transaction_is_active(self) -> bool: return self.is_active def _transaction_is_closed(self) -> bool: return not self._deactivated_from_connection def _rollback_can_be_called(self) -> bool: # for RootTransaction / NestedTransaction, it's safe to call # rollback() even if the transaction is deactive and no warnings # will be emitted. tested in # test_transaction.py -> test_no_rollback_in_deactive(?:_savepoint)? return True class RootTransaction(Transaction): """Represent the "root" transaction on a :class:`_engine.Connection`. This corresponds to the current "BEGIN/COMMIT/ROLLBACK" that's occurring for the :class:`_engine.Connection`. The :class:`_engine.RootTransaction` is created by calling upon the :meth:`_engine.Connection.begin` method, and remains associated with the :class:`_engine.Connection` throughout its active span. The current :class:`_engine.RootTransaction` in use is accessible via the :attr:`_engine.Connection.get_transaction` method of :class:`_engine.Connection`. In :term:`2.0 style` use, the :class:`_engine.Connection` also employs "autobegin" behavior that will create a new :class:`_engine.RootTransaction` whenever a connection in a non-transactional state is used to emit commands on the DBAPI connection. The scope of the :class:`_engine.RootTransaction` in 2.0 style use can be controlled using the :meth:`_engine.Connection.commit` and :meth:`_engine.Connection.rollback` methods. """ _is_root = True __slots__ = ("connection", "is_active") def __init__(self, connection: Connection): assert connection._transaction is None if connection._trans_context_manager: TransactionalContext._trans_ctx_check(connection) self.connection = connection self._connection_begin_impl() connection._transaction = self self.is_active = True def _deactivate_from_connection(self) -> None: if self.is_active: assert self.connection._transaction is self self.is_active = False elif self.connection._transaction is not self: util.warn("transaction already deassociated from connection") @property def _deactivated_from_connection(self) -> bool: return self.connection._transaction is not self def _connection_begin_impl(self) -> None: self.connection._begin_impl(self) def _connection_rollback_impl(self) -> None: self.connection._rollback_impl() def _connection_commit_impl(self) -> None: self.connection._commit_impl() def _close_impl(self, try_deactivate: bool = False) -> None: try: if self.is_active: self._connection_rollback_impl() if self.connection._nested_transaction: self.connection._nested_transaction._cancel() finally: if self.is_active or try_deactivate: self._deactivate_from_connection() if self.connection._transaction is self: self.connection._transaction = None assert not self.is_active assert self.connection._transaction is not self def _do_close(self) -> None: self._close_impl() def _do_rollback(self) -> None: self._close_impl(try_deactivate=True) def _do_commit(self) -> None: if self.is_active: assert self.connection._transaction is self try: self._connection_commit_impl() finally: # whether or not commit succeeds, cancel any # nested transactions, make this transaction "inactive" # and remove it as a reset agent if self.connection._nested_transaction: self.connection._nested_transaction._cancel() self._deactivate_from_connection() # ...however only remove as the connection's current transaction # if commit succeeded. otherwise it stays on so that a rollback # needs to occur. self.connection._transaction = None else: if self.connection._transaction is self: self.connection._invalid_transaction() else: raise exc.InvalidRequestError("This transaction is inactive") assert not self.is_active assert self.connection._transaction is not self class NestedTransaction(Transaction): """Represent a 'nested', or SAVEPOINT transaction. The :class:`.NestedTransaction` object is created by calling the :meth:`_engine.Connection.begin_nested` method of :class:`_engine.Connection`. When using :class:`.NestedTransaction`, the semantics of "begin" / "commit" / "rollback" are as follows: * the "begin" operation corresponds to the "BEGIN SAVEPOINT" command, where the savepoint is given an explicit name that is part of the state of this object. * The :meth:`.NestedTransaction.commit` method corresponds to a "RELEASE SAVEPOINT" operation, using the savepoint identifier associated with this :class:`.NestedTransaction`. * The :meth:`.NestedTransaction.rollback` method corresponds to a "ROLLBACK TO SAVEPOINT" operation, using the savepoint identifier associated with this :class:`.NestedTransaction`. The rationale for mimicking the semantics of an outer transaction in terms of savepoints so that code may deal with a "savepoint" transaction and an "outer" transaction in an agnostic way. .. seealso:: :ref:`session_begin_nested` - ORM version of the SAVEPOINT API. """ __slots__ = ("connection", "is_active", "_savepoint", "_previous_nested") _savepoint: str def __init__(self, connection: Connection): assert connection._transaction is not None if connection._trans_context_manager: TransactionalContext._trans_ctx_check(connection) self.connection = connection self._savepoint = self.connection._savepoint_impl() self.is_active = True self._previous_nested = connection._nested_transaction connection._nested_transaction = self def _deactivate_from_connection(self, warn: bool = True) -> None: if self.connection._nested_transaction is self: self.connection._nested_transaction = self._previous_nested elif warn: util.warn( "nested transaction already deassociated from connection" ) @property def _deactivated_from_connection(self) -> bool: return self.connection._nested_transaction is not self def _cancel(self) -> None: # called by RootTransaction when the outer transaction is # committed, rolled back, or closed to cancel all savepoints # without any action being taken self.is_active = False self._deactivate_from_connection() if self._previous_nested: self._previous_nested._cancel() def _close_impl( self, deactivate_from_connection: bool, warn_already_deactive: bool ) -> None: try: if ( self.is_active and self.connection._transaction and self.connection._transaction.is_active ): self.connection._rollback_to_savepoint_impl(self._savepoint) finally: self.is_active = False if deactivate_from_connection: self._deactivate_from_connection(warn=warn_already_deactive) assert not self.is_active if deactivate_from_connection: assert self.connection._nested_transaction is not self def _do_close(self) -> None: self._close_impl(True, False) def _do_rollback(self) -> None: self._close_impl(True, True) def _do_commit(self) -> None: if self.is_active: try: self.connection._release_savepoint_impl(self._savepoint) finally: # nested trans becomes inactive on failed release # unconditionally. this prevents it from trying to # emit SQL when it rolls back. self.is_active = False # but only de-associate from connection if it succeeded self._deactivate_from_connection() else: if self.connection._nested_transaction is self: self.connection._invalid_transaction() else: raise exc.InvalidRequestError( "This nested transaction is inactive" ) class TwoPhaseTransaction(RootTransaction): """Represent a two-phase transaction. A new :class:`.TwoPhaseTransaction` object may be procured using the :meth:`_engine.Connection.begin_twophase` method. The interface is the same as that of :class:`.Transaction` with the addition of the :meth:`prepare` method. """ __slots__ = ("xid", "_is_prepared") xid: Any def __init__(self, connection: Connection, xid: Any): self._is_prepared = False self.xid = xid super().__init__(connection) def prepare(self) -> None: """Prepare this :class:`.TwoPhaseTransaction`. After a PREPARE, the transaction can be committed. """ if not self.is_active: raise exc.InvalidRequestError("This transaction is inactive") self.connection._prepare_twophase_impl(self.xid) self._is_prepared = True def _connection_begin_impl(self) -> None: self.connection._begin_twophase_impl(self) def _connection_rollback_impl(self) -> None: self.connection._rollback_twophase_impl(self.xid, self._is_prepared) def _connection_commit_impl(self) -> None: self.connection._commit_twophase_impl(self.xid, self._is_prepared) class Engine( ConnectionEventsTarget, log.Identified, inspection.Inspectable["Inspector"] ): """ Connects a :class:`~sqlalchemy.pool.Pool` and :class:`~sqlalchemy.engine.interfaces.Dialect` together to provide a source of database connectivity and behavior. An :class:`_engine.Engine` object is instantiated publicly using the :func:`~sqlalchemy.create_engine` function. .. seealso:: :doc:`/core/engines` :ref:`connections_toplevel` """ dispatch: dispatcher[ConnectionEventsTarget] _compiled_cache: Optional[CompiledCacheType] _execution_options: _ExecuteOptions = _EMPTY_EXECUTION_OPTS _has_events: bool = False _connection_cls: Type[Connection] = Connection _sqla_logger_namespace: str = "sqlalchemy.engine.Engine" _is_future: bool = False _schema_translate_map: Optional[SchemaTranslateMapType] = None _option_cls: Type[OptionEngine] dialect: Dialect pool: Pool url: URL hide_parameters: bool def __init__( self, pool: Pool, dialect: Dialect, url: URL, logging_name: Optional[str] = None, echo: Optional[_EchoFlagType] = None, query_cache_size: int = 500, execution_options: Optional[Mapping[str, Any]] = None, hide_parameters: bool = False, ): self.pool = pool self.url = url self.dialect = dialect if logging_name: self.logging_name = logging_name self.echo = echo self.hide_parameters = hide_parameters if query_cache_size != 0: self._compiled_cache = util.LRUCache( query_cache_size, size_alert=self._lru_size_alert ) else: self._compiled_cache = None log.instance_logger(self, echoflag=echo) if execution_options: self.update_execution_options(**execution_options) def _lru_size_alert(self, cache: util.LRUCache[Any, Any]) -> None: if self._should_log_info(): self.logger.info( "Compiled cache size pruning from %d items to %d. " "Increase cache size to reduce the frequency of pruning.", len(cache), cache.capacity, ) @property def engine(self) -> Engine: """Returns this :class:`.Engine`. Used for legacy schemes that accept :class:`.Connection` / :class:`.Engine` objects within the same variable. """ return self def clear_compiled_cache(self) -> None: """Clear the compiled cache associated with the dialect. This applies **only** to the built-in cache that is established via the :paramref:`_engine.create_engine.query_cache_size` parameter. It will not impact any dictionary caches that were passed via the :paramref:`.Connection.execution_options.compiled_cache` parameter. .. versionadded:: 1.4 """ if self._compiled_cache: self._compiled_cache.clear() def update_execution_options(self, **opt: Any) -> None: r"""Update the default execution_options dictionary of this :class:`_engine.Engine`. The given keys/values in \**opt are added to the default execution options that will be used for all connections. The initial contents of this dictionary can be sent via the ``execution_options`` parameter to :func:`_sa.create_engine`. .. seealso:: :meth:`_engine.Connection.execution_options` :meth:`_engine.Engine.execution_options` """ self.dispatch.set_engine_execution_options(self, opt) self._execution_options = self._execution_options.union(opt) self.dialect.set_engine_execution_options(self, opt) @overload def execution_options( self, *, compiled_cache: Optional[CompiledCacheType] = ..., logging_token: str = ..., isolation_level: IsolationLevel = ..., insertmanyvalues_page_size: int = ..., schema_translate_map: Optional[SchemaTranslateMapType] = ..., **opt: Any, ) -> OptionEngine: ... @overload def execution_options(self, **opt: Any) -> OptionEngine: ... def execution_options(self, **opt: Any) -> OptionEngine: """Return a new :class:`_engine.Engine` that will provide :class:`_engine.Connection` objects with the given execution options. The returned :class:`_engine.Engine` remains related to the original :class:`_engine.Engine` in that it shares the same connection pool and other state: * The :class:`_pool.Pool` used by the new :class:`_engine.Engine` is the same instance. The :meth:`_engine.Engine.dispose` method will replace the connection pool instance for the parent engine as well as this one. * Event listeners are "cascaded" - meaning, the new :class:`_engine.Engine` inherits the events of the parent, and new events can be associated with the new :class:`_engine.Engine` individually. * The logging configuration and logging_name is copied from the parent :class:`_engine.Engine`. The intent of the :meth:`_engine.Engine.execution_options` method is to implement schemes where multiple :class:`_engine.Engine` objects refer to the same connection pool, but are differentiated by options that affect some execution-level behavior for each engine. One such example is breaking into separate "reader" and "writer" :class:`_engine.Engine` instances, where one :class:`_engine.Engine` has a lower :term:`isolation level` setting configured or is even transaction-disabled using "autocommit". An example of this configuration is at :ref:`dbapi_autocommit_multiple`. Another example is one that uses a custom option ``shard_id`` which is consumed by an event to change the current schema on a database connection:: from sqlalchemy import event from sqlalchemy.engine import Engine primary_engine = create_engine("mysql+mysqldb://") shard1 = primary_engine.execution_options(shard_id="shard1") shard2 = primary_engine.execution_options(shard_id="shard2") shards = {"default": "base", "shard_1": "db1", "shard_2": "db2"} @event.listens_for(Engine, "before_cursor_execute") def _switch_shard(conn, cursor, stmt, params, context, executemany): shard_id = conn.get_execution_options().get("shard_id", "default") current_shard = conn.info.get("current_shard", None) if current_shard != shard_id: cursor.execute("use %s" % shards[shard_id]) conn.info["current_shard"] = shard_id The above recipe illustrates two :class:`_engine.Engine` objects that will each serve as factories for :class:`_engine.Connection` objects that have pre-established "shard_id" execution options present. A :meth:`_events.ConnectionEvents.before_cursor_execute` event handler then interprets this execution option to emit a MySQL ``use`` statement to switch databases before a statement execution, while at the same time keeping track of which database we've established using the :attr:`_engine.Connection.info` dictionary. .. seealso:: :meth:`_engine.Connection.execution_options` - update execution options on a :class:`_engine.Connection` object. :meth:`_engine.Engine.update_execution_options` - update the execution options for a given :class:`_engine.Engine` in place. :meth:`_engine.Engine.get_execution_options` """ # noqa: E501 return self._option_cls(self, opt) def get_execution_options(self) -> _ExecuteOptions: """Get the non-SQL options which will take effect during execution. .. versionadded: 1.3 .. seealso:: :meth:`_engine.Engine.execution_options` """ return self._execution_options @property def name(self) -> str: """String name of the :class:`~sqlalchemy.engine.interfaces.Dialect` in use by this :class:`Engine`. """ return self.dialect.name @property def driver(self) -> str: """Driver name of the :class:`~sqlalchemy.engine.interfaces.Dialect` in use by this :class:`Engine`. """ return self.dialect.driver echo = log.echo_property() def __repr__(self) -> str: return "Engine(%r)" % (self.url,) def dispose(self, close: bool = True) -> None: """Dispose of the connection pool used by this :class:`_engine.Engine`. A new connection pool is created immediately after the old one has been disposed. The previous connection pool is disposed either actively, by closing out all currently checked-in connections in that pool, or passively, by losing references to it but otherwise not closing any connections. The latter strategy is more appropriate for an initializer in a forked Python process. :param close: if left at its default of ``True``, has the effect of fully closing all **currently checked in** database connections. Connections that are still checked out will **not** be closed, however they will no longer be associated with this :class:`_engine.Engine`, so when they are closed individually, eventually the :class:`_pool.Pool` which they are associated with will be garbage collected and they will be closed out fully, if not already closed on checkin. If set to ``False``, the previous connection pool is de-referenced, and otherwise not touched in any way. .. versionadded:: 1.4.33 Added the :paramref:`.Engine.dispose.close` parameter to allow the replacement of a connection pool in a child process without interfering with the connections used by the parent process. .. seealso:: :ref:`engine_disposal` :ref:`pooling_multiprocessing` """ if close: self.pool.dispose() self.pool = self.pool.recreate() self.dispatch.engine_disposed(self) @contextlib.contextmanager def _optional_conn_ctx_manager( self, connection: Optional[Connection] = None ) -> Iterator[Connection]: if connection is None: with self.connect() as conn: yield conn else: yield connection @contextlib.contextmanager def begin(self) -> Iterator[Connection]: """Return a context manager delivering a :class:`_engine.Connection` with a :class:`.Transaction` established. E.g.:: with engine.begin() as conn: conn.execute(text("insert into table (x, y, z) values (1, 2, 3)")) conn.execute(text("my_special_procedure(5)")) Upon successful operation, the :class:`.Transaction` is committed. If an error is raised, the :class:`.Transaction` is rolled back. .. seealso:: :meth:`_engine.Engine.connect` - procure a :class:`_engine.Connection` from an :class:`_engine.Engine`. :meth:`_engine.Connection.begin` - start a :class:`.Transaction` for a particular :class:`_engine.Connection`. """ # noqa: E501 with self.connect() as conn: with conn.begin(): yield conn def _run_ddl_visitor( self, visitorcallable: Type[InvokeDDLBase], element: SchemaVisitable, **kwargs: Any, ) -> None: with self.begin() as conn: conn._run_ddl_visitor(visitorcallable, element, **kwargs) def connect(self) -> Connection: """Return a new :class:`_engine.Connection` object. The :class:`_engine.Connection` acts as a Python context manager, so the typical use of this method looks like:: with engine.connect() as connection: connection.execute(text("insert into table values ('foo')")) connection.commit() Where above, after the block is completed, the connection is "closed" and its underlying DBAPI resources are returned to the connection pool. This also has the effect of rolling back any transaction that was explicitly begun or was begun via autobegin, and will emit the :meth:`_events.ConnectionEvents.rollback` event if one was started and is still in progress. .. seealso:: :meth:`_engine.Engine.begin` """ return self._connection_cls(self) def raw_connection(self) -> PoolProxiedConnection: """Return a "raw" DBAPI connection from the connection pool. The returned object is a proxied version of the DBAPI connection object used by the underlying driver in use. The object will have all the same behavior as the real DBAPI connection, except that its ``close()`` method will result in the connection being returned to the pool, rather than being closed for real. This method provides direct DBAPI connection access for special situations when the API provided by :class:`_engine.Connection` is not needed. When a :class:`_engine.Connection` object is already present, the DBAPI connection is available using the :attr:`_engine.Connection.connection` accessor. .. seealso:: :ref:`dbapi_connections` """ return self.pool.connect() class OptionEngineMixin(log.Identified): _sa_propagate_class_events = False dispatch: dispatcher[ConnectionEventsTarget] _compiled_cache: Optional[CompiledCacheType] dialect: Dialect pool: Pool url: URL hide_parameters: bool echo: log.echo_property def __init__( self, proxied: Engine, execution_options: CoreExecuteOptionsParameter ): self._proxied = proxied self.url = proxied.url self.dialect = proxied.dialect self.logging_name = proxied.logging_name self.echo = proxied.echo self._compiled_cache = proxied._compiled_cache self.hide_parameters = proxied.hide_parameters log.instance_logger(self, echoflag=self.echo) # note: this will propagate events that are assigned to the parent # engine after this OptionEngine is created. Since we share # the events of the parent we also disallow class-level events # to apply to the OptionEngine class directly. # # the other way this can work would be to transfer existing # events only, using: # self.dispatch._update(proxied.dispatch) # # that might be more appropriate however it would be a behavioral # change for logic that assigns events to the parent engine and # would like it to take effect for the already-created sub-engine. self.dispatch = self.dispatch._join(proxied.dispatch) self._execution_options = proxied._execution_options self.update_execution_options(**execution_options) def update_execution_options(self, **opt: Any) -> None: raise NotImplementedError() if not typing.TYPE_CHECKING: # https://github.com/python/typing/discussions/1095 @property def pool(self) -> Pool: return self._proxied.pool @pool.setter def pool(self, pool: Pool) -> None: self._proxied.pool = pool @property def _has_events(self) -> bool: return self._proxied._has_events or self.__dict__.get( "_has_events", False ) @_has_events.setter def _has_events(self, value: bool) -> None: self.__dict__["_has_events"] = value class OptionEngine(OptionEngineMixin, Engine): def update_execution_options(self, **opt: Any) -> None: Engine.update_execution_options(self, **opt) Engine._option_cls = OptionEngine sqlalchemy/engine/characteristics.py 0000755 00000011235 15125143220 0013700 0 ustar 00 # engine/characteristics.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php from __future__ import annotations import abc import typing from typing import Any from typing import ClassVar if typing.TYPE_CHECKING: from .base import Connection from .interfaces import DBAPIConnection from .interfaces import Dialect class ConnectionCharacteristic(abc.ABC): """An abstract base for an object that can set, get and reset a per-connection characteristic, typically one that gets reset when the connection is returned to the connection pool. transaction isolation is the canonical example, and the ``IsolationLevelCharacteristic`` implementation provides this for the ``DefaultDialect``. The ``ConnectionCharacteristic`` class should call upon the ``Dialect`` for the implementation of each method. The object exists strictly to serve as a dialect visitor that can be placed into the ``DefaultDialect.connection_characteristics`` dictionary where it will take effect for calls to :meth:`_engine.Connection.execution_options` and related APIs. .. versionadded:: 1.4 """ __slots__ = () transactional: ClassVar[bool] = False @abc.abstractmethod def reset_characteristic( self, dialect: Dialect, dbapi_conn: DBAPIConnection ) -> None: """Reset the characteristic on the DBAPI connection to its default value.""" @abc.abstractmethod def set_characteristic( self, dialect: Dialect, dbapi_conn: DBAPIConnection, value: Any ) -> None: """set characteristic on the DBAPI connection to a given value.""" def set_connection_characteristic( self, dialect: Dialect, conn: Connection, dbapi_conn: DBAPIConnection, value: Any, ) -> None: """set characteristic on the :class:`_engine.Connection` to a given value. .. versionadded:: 2.0.30 - added to support elements that are local to the :class:`_engine.Connection` itself. """ self.set_characteristic(dialect, dbapi_conn, value) @abc.abstractmethod def get_characteristic( self, dialect: Dialect, dbapi_conn: DBAPIConnection ) -> Any: """Given a DBAPI connection, get the current value of the characteristic. """ def get_connection_characteristic( self, dialect: Dialect, conn: Connection, dbapi_conn: DBAPIConnection ) -> Any: """Given a :class:`_engine.Connection`, get the current value of the characteristic. .. versionadded:: 2.0.30 - added to support elements that are local to the :class:`_engine.Connection` itself. """ return self.get_characteristic(dialect, dbapi_conn) class IsolationLevelCharacteristic(ConnectionCharacteristic): """Manage the isolation level on a DBAPI connection""" transactional: ClassVar[bool] = True def reset_characteristic( self, dialect: Dialect, dbapi_conn: DBAPIConnection ) -> None: dialect.reset_isolation_level(dbapi_conn) def set_characteristic( self, dialect: Dialect, dbapi_conn: DBAPIConnection, value: Any ) -> None: dialect._assert_and_set_isolation_level(dbapi_conn, value) def get_characteristic( self, dialect: Dialect, dbapi_conn: DBAPIConnection ) -> Any: return dialect.get_isolation_level(dbapi_conn) class LoggingTokenCharacteristic(ConnectionCharacteristic): """Manage the 'logging_token' option of a :class:`_engine.Connection`. .. versionadded:: 2.0.30 """ transactional: ClassVar[bool] = False def reset_characteristic( self, dialect: Dialect, dbapi_conn: DBAPIConnection ) -> None: pass def set_characteristic( self, dialect: Dialect, dbapi_conn: DBAPIConnection, value: Any ) -> None: raise NotImplementedError() def set_connection_characteristic( self, dialect: Dialect, conn: Connection, dbapi_conn: DBAPIConnection, value: Any, ) -> None: if value: conn._message_formatter = lambda msg: "[%s] %s" % (value, msg) else: del conn._message_formatter def get_characteristic( self, dialect: Dialect, dbapi_conn: DBAPIConnection ) -> Any: raise NotImplementedError() def get_connection_characteristic( self, dialect: Dialect, conn: Connection, dbapi_conn: DBAPIConnection ) -> Any: return conn._execution_options.get("logging_token", None) sqlalchemy/engine/mock.py 0000755 00000010074 15125143220 0011456 0 ustar 00 # engine/mock.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php from __future__ import annotations from operator import attrgetter import typing from typing import Any from typing import Callable from typing import cast from typing import Optional from typing import Type from typing import Union from . import url as _url from .. import util if typing.TYPE_CHECKING: from .base import Engine from .interfaces import _CoreAnyExecuteParams from .interfaces import CoreExecuteOptionsParameter from .interfaces import Dialect from .url import URL from ..sql.base import Executable from ..sql.ddl import InvokeDDLBase from ..sql.schema import HasSchemaAttr from ..sql.visitors import Visitable class MockConnection: def __init__(self, dialect: Dialect, execute: Callable[..., Any]): self._dialect = dialect self._execute_impl = execute engine: Engine = cast(Any, property(lambda s: s)) dialect: Dialect = cast(Any, property(attrgetter("_dialect"))) name: str = cast(Any, property(lambda s: s._dialect.name)) def connect(self, **kwargs: Any) -> MockConnection: return self def schema_for_object(self, obj: HasSchemaAttr) -> Optional[str]: return obj.schema def execution_options(self, **kw: Any) -> MockConnection: return self def _run_ddl_visitor( self, visitorcallable: Type[InvokeDDLBase], element: Visitable, **kwargs: Any, ) -> None: kwargs["checkfirst"] = False visitorcallable( dialect=self.dialect, connection=self, **kwargs ).traverse_single(element) def execute( self, obj: Executable, parameters: Optional[_CoreAnyExecuteParams] = None, execution_options: Optional[CoreExecuteOptionsParameter] = None, ) -> Any: return self._execute_impl(obj, parameters) def create_mock_engine( url: Union[str, URL], executor: Any, **kw: Any ) -> MockConnection: """Create a "mock" engine used for echoing DDL. This is a utility function used for debugging or storing the output of DDL sequences as generated by :meth:`_schema.MetaData.create_all` and related methods. The function accepts a URL which is used only to determine the kind of dialect to be used, as well as an "executor" callable function which will receive a SQL expression object and parameters, which can then be echoed or otherwise printed. The executor's return value is not handled, nor does the engine allow regular string statements to be invoked, and is therefore only useful for DDL that is sent to the database without receiving any results. E.g.:: from sqlalchemy import create_mock_engine def dump(sql, *multiparams, **params): print(sql.compile(dialect=engine.dialect)) engine = create_mock_engine("postgresql+psycopg2://", dump) metadata.create_all(engine, checkfirst=False) :param url: A string URL which typically needs to contain only the database backend name. :param executor: a callable which receives the arguments ``sql``, ``*multiparams`` and ``**params``. The ``sql`` parameter is typically an instance of :class:`.ExecutableDDLElement`, which can then be compiled into a string using :meth:`.ExecutableDDLElement.compile`. .. versionadded:: 1.4 - the :func:`.create_mock_engine` function replaces the previous "mock" engine strategy used with :func:`_sa.create_engine`. .. seealso:: :ref:`faq_ddl_as_string` """ # create url.URL object u = _url.make_url(url) dialect_cls = u.get_dialect() dialect_args = {} # consume dialect arguments from kwargs for k in util.get_cls_kwargs(dialect_cls): if k in kw: dialect_args[k] = kw.pop(k) # create dialect dialect = dialect_cls(**dialect_args) return MockConnection(dialect, executor) sqlalchemy/engine/default.py 0000755 00000246472 15125143220 0012166 0 ustar 00 # engine/default.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: allow-untyped-defs, allow-untyped-calls """Default implementations of per-dialect sqlalchemy.engine classes. These are semi-private implementation classes which are only of importance to database dialect authors; dialects will usually use the classes here as the base class for their own corresponding classes. """ from __future__ import annotations import functools import operator import random import re from time import perf_counter import typing from typing import Any from typing import Callable from typing import cast from typing import Dict from typing import List from typing import Mapping from typing import MutableMapping from typing import MutableSequence from typing import Optional from typing import Sequence from typing import Set from typing import Tuple from typing import Type from typing import TYPE_CHECKING from typing import Union import weakref from . import characteristics from . import cursor as _cursor from . import interfaces from .base import Connection from .interfaces import CacheStats from .interfaces import DBAPICursor from .interfaces import Dialect from .interfaces import ExecuteStyle from .interfaces import ExecutionContext from .reflection import ObjectKind from .reflection import ObjectScope from .. import event from .. import exc from .. import pool from .. import util from ..sql import compiler from ..sql import dml from ..sql import expression from ..sql import type_api from ..sql import util as sql_util from ..sql._typing import is_tuple_type from ..sql.base import _NoArg from ..sql.compiler import DDLCompiler from ..sql.compiler import InsertmanyvaluesSentinelOpts from ..sql.compiler import SQLCompiler from ..sql.elements import quoted_name from ..util.typing import Final from ..util.typing import Literal if typing.TYPE_CHECKING: from types import ModuleType from .base import Engine from .cursor import ResultFetchStrategy from .interfaces import _CoreMultiExecuteParams from .interfaces import _CoreSingleExecuteParams from .interfaces import _DBAPICursorDescription from .interfaces import _DBAPIMultiExecuteParams from .interfaces import _DBAPISingleExecuteParams from .interfaces import _ExecuteOptions from .interfaces import _MutableCoreSingleExecuteParams from .interfaces import _ParamStyle from .interfaces import ConnectArgsType from .interfaces import DBAPIConnection from .interfaces import IsolationLevel from .row import Row from .url import URL from ..event import _ListenerFnType from ..pool import Pool from ..pool import PoolProxiedConnection from ..sql import Executable from ..sql.compiler import Compiled from ..sql.compiler import Linting from ..sql.compiler import ResultColumnsEntry from ..sql.dml import DMLState from ..sql.dml import UpdateBase from ..sql.elements import BindParameter from ..sql.schema import Column from ..sql.type_api import _BindProcessorType from ..sql.type_api import _ResultProcessorType from ..sql.type_api import TypeEngine # When we're handed literal SQL, ensure it's a SELECT query SERVER_SIDE_CURSOR_RE = re.compile(r"\s*SELECT", re.I | re.UNICODE) ( CACHE_HIT, CACHE_MISS, CACHING_DISABLED, NO_CACHE_KEY, NO_DIALECT_SUPPORT, ) = list(CacheStats) class DefaultDialect(Dialect): """Default implementation of Dialect""" statement_compiler = compiler.SQLCompiler ddl_compiler = compiler.DDLCompiler type_compiler_cls = compiler.GenericTypeCompiler preparer = compiler.IdentifierPreparer supports_alter = True supports_comments = False supports_constraint_comments = False inline_comments = False supports_statement_cache = True div_is_floordiv = True bind_typing = interfaces.BindTyping.NONE include_set_input_sizes: Optional[Set[Any]] = None exclude_set_input_sizes: Optional[Set[Any]] = None # the first value we'd get for an autoincrement column. default_sequence_base = 1 # most DBAPIs happy with this for execute(). # not cx_oracle. execute_sequence_format = tuple supports_schemas = True supports_views = True supports_sequences = False sequences_optional = False preexecute_autoincrement_sequences = False supports_identity_columns = False postfetch_lastrowid = True favor_returning_over_lastrowid = False insert_null_pk_still_autoincrements = False update_returning = False delete_returning = False update_returning_multifrom = False delete_returning_multifrom = False insert_returning = False cte_follows_insert = False supports_native_enum = False supports_native_boolean = False supports_native_uuid = False returns_native_bytes = False non_native_boolean_check_constraint = True supports_simple_order_by_label = True tuple_in_values = False connection_characteristics = util.immutabledict( { "isolation_level": characteristics.IsolationLevelCharacteristic(), "logging_token": characteristics.LoggingTokenCharacteristic(), } ) engine_config_types: Mapping[str, Any] = util.immutabledict( { "pool_timeout": util.asint, "echo": util.bool_or_str("debug"), "echo_pool": util.bool_or_str("debug"), "pool_recycle": util.asint, "pool_size": util.asint, "max_overflow": util.asint, "future": util.asbool, } ) # if the NUMERIC type # returns decimal.Decimal. # *not* the FLOAT type however. supports_native_decimal = False name = "default" # length at which to truncate # any identifier. max_identifier_length = 9999 _user_defined_max_identifier_length: Optional[int] = None isolation_level: Optional[str] = None # sub-categories of max_identifier_length. # currently these accommodate for MySQL which allows alias names # of 255 but DDL names only of 64. max_index_name_length: Optional[int] = None max_constraint_name_length: Optional[int] = None supports_sane_rowcount = True supports_sane_multi_rowcount = True colspecs: MutableMapping[Type[TypeEngine[Any]], Type[TypeEngine[Any]]] = {} default_paramstyle = "named" supports_default_values = False """dialect supports INSERT... DEFAULT VALUES syntax""" supports_default_metavalue = False """dialect supports INSERT... VALUES (DEFAULT) syntax""" default_metavalue_token = "DEFAULT" """for INSERT... VALUES (DEFAULT) syntax, the token to put in the parenthesis.""" # not sure if this is a real thing but the compiler will deliver it # if this is the only flag enabled. supports_empty_insert = True """dialect supports INSERT () VALUES ()""" supports_multivalues_insert = False use_insertmanyvalues: bool = False use_insertmanyvalues_wo_returning: bool = False insertmanyvalues_implicit_sentinel: InsertmanyvaluesSentinelOpts = ( InsertmanyvaluesSentinelOpts.NOT_SUPPORTED ) insertmanyvalues_page_size: int = 1000 insertmanyvalues_max_parameters = 32700 supports_is_distinct_from = True supports_server_side_cursors = False server_side_cursors = False # extra record-level locking features (#4860) supports_for_update_of = False server_version_info = None default_schema_name: Optional[str] = None # indicates symbol names are # UPPERCASED if they are case insensitive # within the database. # if this is True, the methods normalize_name() # and denormalize_name() must be provided. requires_name_normalize = False is_async = False has_terminate = False # TODO: this is not to be part of 2.0. implement rudimentary binary # literals for SQLite, PostgreSQL, MySQL only within # _Binary.literal_processor _legacy_binary_type_literal_encoding = "utf-8" @util.deprecated_params( empty_in_strategy=( "1.4", "The :paramref:`_sa.create_engine.empty_in_strategy` keyword is " "deprecated, and no longer has any effect. All IN expressions " "are now rendered using " 'the "expanding parameter" strategy which renders a set of bound' 'expressions, or an "empty set" SELECT, at statement execution' "time.", ), server_side_cursors=( "1.4", "The :paramref:`_sa.create_engine.server_side_cursors` parameter " "is deprecated and will be removed in a future release. Please " "use the " ":paramref:`_engine.Connection.execution_options.stream_results` " "parameter.", ), ) def __init__( self, paramstyle: Optional[_ParamStyle] = None, isolation_level: Optional[IsolationLevel] = None, dbapi: Optional[ModuleType] = None, implicit_returning: Literal[True] = True, supports_native_boolean: Optional[bool] = None, max_identifier_length: Optional[int] = None, label_length: Optional[int] = None, insertmanyvalues_page_size: Union[_NoArg, int] = _NoArg.NO_ARG, use_insertmanyvalues: Optional[bool] = None, # util.deprecated_params decorator cannot render the # Linting.NO_LINTING constant compiler_linting: Linting = int(compiler.NO_LINTING), # type: ignore server_side_cursors: bool = False, **kwargs: Any, ): if server_side_cursors: if not self.supports_server_side_cursors: raise exc.ArgumentError( "Dialect %s does not support server side cursors" % self ) else: self.server_side_cursors = True if getattr(self, "use_setinputsizes", False): util.warn_deprecated( "The dialect-level use_setinputsizes attribute is " "deprecated. Please use " "bind_typing = BindTyping.SETINPUTSIZES", "2.0", ) self.bind_typing = interfaces.BindTyping.SETINPUTSIZES self.positional = False self._ischema = None self.dbapi = dbapi if paramstyle is not None: self.paramstyle = paramstyle elif self.dbapi is not None: self.paramstyle = self.dbapi.paramstyle else: self.paramstyle = self.default_paramstyle self.positional = self.paramstyle in ( "qmark", "format", "numeric", "numeric_dollar", ) self.identifier_preparer = self.preparer(self) self._on_connect_isolation_level = isolation_level legacy_tt_callable = getattr(self, "type_compiler", None) if legacy_tt_callable is not None: tt_callable = cast( Type[compiler.GenericTypeCompiler], self.type_compiler, ) else: tt_callable = self.type_compiler_cls self.type_compiler_instance = self.type_compiler = tt_callable(self) if supports_native_boolean is not None: self.supports_native_boolean = supports_native_boolean self._user_defined_max_identifier_length = max_identifier_length if self._user_defined_max_identifier_length: self.max_identifier_length = ( self._user_defined_max_identifier_length ) self.label_length = label_length self.compiler_linting = compiler_linting if use_insertmanyvalues is not None: self.use_insertmanyvalues = use_insertmanyvalues if insertmanyvalues_page_size is not _NoArg.NO_ARG: self.insertmanyvalues_page_size = insertmanyvalues_page_size @property @util.deprecated( "2.0", "full_returning is deprecated, please use insert_returning, " "update_returning, delete_returning", ) def full_returning(self): return ( self.insert_returning and self.update_returning and self.delete_returning ) @util.memoized_property def insert_executemany_returning(self): """Default implementation for insert_executemany_returning, if not otherwise overridden by the specific dialect. The default dialect determines "insert_executemany_returning" is available if the dialect in use has opted into using the "use_insertmanyvalues" feature. If they haven't opted into that, then this attribute is False, unless the dialect in question overrides this and provides some other implementation (such as the Oracle Database dialects). """ return self.insert_returning and self.use_insertmanyvalues @util.memoized_property def insert_executemany_returning_sort_by_parameter_order(self): """Default implementation for insert_executemany_returning_deterministic_order, if not otherwise overridden by the specific dialect. The default dialect determines "insert_executemany_returning" can have deterministic order only if the dialect in use has opted into using the "use_insertmanyvalues" feature, which implements deterministic ordering using client side sentinel columns only by default. The "insertmanyvalues" feature also features alternate forms that can use server-generated PK values as "sentinels", but those are only used if the :attr:`.Dialect.insertmanyvalues_implicit_sentinel` bitflag enables those alternate SQL forms, which are disabled by default. If the dialect in use hasn't opted into that, then this attribute is False, unless the dialect in question overrides this and provides some other implementation (such as the Oracle Database dialects). """ return self.insert_returning and self.use_insertmanyvalues update_executemany_returning = False delete_executemany_returning = False @util.memoized_property def loaded_dbapi(self) -> ModuleType: if self.dbapi is None: raise exc.InvalidRequestError( f"Dialect {self} does not have a Python DBAPI established " "and cannot be used for actual database interaction" ) return self.dbapi @util.memoized_property def _bind_typing_render_casts(self): return self.bind_typing is interfaces.BindTyping.RENDER_CASTS def _ensure_has_table_connection(self, arg: Connection) -> None: if not isinstance(arg, Connection): raise exc.ArgumentError( "The argument passed to Dialect.has_table() should be a " "%s, got %s. " "Additionally, the Dialect.has_table() method is for " "internal dialect " "use only; please use " "``inspect(some_engine).has_table(<tablename>>)`` " "for public API use." % (Connection, type(arg)) ) @util.memoized_property def _supports_statement_cache(self): ssc = self.__class__.__dict__.get("supports_statement_cache", None) if ssc is None: util.warn( "Dialect %s:%s will not make use of SQL compilation caching " "as it does not set the 'supports_statement_cache' attribute " "to ``True``. This can have " "significant performance implications including some " "performance degradations in comparison to prior SQLAlchemy " "versions. Dialect maintainers should seek to set this " "attribute to True after appropriate development and testing " "for SQLAlchemy 1.4 caching support. Alternatively, this " "attribute may be set to False which will disable this " "warning." % (self.name, self.driver), code="cprf", ) return bool(ssc) @util.memoized_property def _type_memos(self): return weakref.WeakKeyDictionary() @property def dialect_description(self): return self.name + "+" + self.driver @property def supports_sane_rowcount_returning(self): """True if this dialect supports sane rowcount even if RETURNING is in use. For dialects that don't support RETURNING, this is synonymous with ``supports_sane_rowcount``. """ return self.supports_sane_rowcount @classmethod def get_pool_class(cls, url: URL) -> Type[Pool]: return getattr(cls, "poolclass", pool.QueuePool) def get_dialect_pool_class(self, url: URL) -> Type[Pool]: return self.get_pool_class(url) @classmethod def load_provisioning(cls): package = ".".join(cls.__module__.split(".")[0:-1]) try: __import__(package + ".provision") except ImportError: pass def _builtin_onconnect(self) -> Optional[_ListenerFnType]: if self._on_connect_isolation_level is not None: def builtin_connect(dbapi_conn, conn_rec): self._assert_and_set_isolation_level( dbapi_conn, self._on_connect_isolation_level ) return builtin_connect else: return None def initialize(self, connection: Connection) -> None: try: self.server_version_info = self._get_server_version_info( connection ) except NotImplementedError: self.server_version_info = None try: self.default_schema_name = self._get_default_schema_name( connection ) except NotImplementedError: self.default_schema_name = None try: self.default_isolation_level = self.get_default_isolation_level( connection.connection.dbapi_connection ) except NotImplementedError: self.default_isolation_level = None if not self._user_defined_max_identifier_length: max_ident_length = self._check_max_identifier_length(connection) if max_ident_length: self.max_identifier_length = max_ident_length if ( self.label_length and self.label_length > self.max_identifier_length ): raise exc.ArgumentError( "Label length of %d is greater than this dialect's" " maximum identifier length of %d" % (self.label_length, self.max_identifier_length) ) def on_connect(self) -> Optional[Callable[[Any], Any]]: # inherits the docstring from interfaces.Dialect.on_connect return None def _check_max_identifier_length(self, connection): """Perform a connection / server version specific check to determine the max_identifier_length. If the dialect's class level max_identifier_length should be used, can return None. .. versionadded:: 1.3.9 """ return None def get_default_isolation_level(self, dbapi_conn): """Given a DBAPI connection, return its isolation level, or a default isolation level if one cannot be retrieved. May be overridden by subclasses in order to provide a "fallback" isolation level for databases that cannot reliably retrieve the actual isolation level. By default, calls the :meth:`_engine.Interfaces.get_isolation_level` method, propagating any exceptions raised. .. versionadded:: 1.3.22 """ return self.get_isolation_level(dbapi_conn) def type_descriptor(self, typeobj): """Provide a database-specific :class:`.TypeEngine` object, given the generic object which comes from the types module. This method looks for a dictionary called ``colspecs`` as a class or instance-level variable, and passes on to :func:`_types.adapt_type`. """ return type_api.adapt_type(typeobj, self.colspecs) def has_index(self, connection, table_name, index_name, schema=None, **kw): if not self.has_table(connection, table_name, schema=schema, **kw): return False for idx in self.get_indexes( connection, table_name, schema=schema, **kw ): if idx["name"] == index_name: return True else: return False def has_schema( self, connection: Connection, schema_name: str, **kw: Any ) -> bool: return schema_name in self.get_schema_names(connection, **kw) def validate_identifier(self, ident: str) -> None: if len(ident) > self.max_identifier_length: raise exc.IdentifierError( "Identifier '%s' exceeds maximum length of %d characters" % (ident, self.max_identifier_length) ) def connect(self, *cargs: Any, **cparams: Any) -> DBAPIConnection: # inherits the docstring from interfaces.Dialect.connect return self.loaded_dbapi.connect(*cargs, **cparams) # type: ignore[no-any-return] # NOQA: E501 def create_connect_args(self, url: URL) -> ConnectArgsType: # inherits the docstring from interfaces.Dialect.create_connect_args opts = url.translate_connect_args() opts.update(url.query) return ([], opts) def set_engine_execution_options( self, engine: Engine, opts: Mapping[str, Any] ) -> None: supported_names = set(self.connection_characteristics).intersection( opts ) if supported_names: characteristics: Mapping[str, Any] = util.immutabledict( (name, opts[name]) for name in supported_names ) @event.listens_for(engine, "engine_connect") def set_connection_characteristics(connection): self._set_connection_characteristics( connection, characteristics ) def set_connection_execution_options( self, connection: Connection, opts: Mapping[str, Any] ) -> None: supported_names = set(self.connection_characteristics).intersection( opts ) if supported_names: characteristics: Mapping[str, Any] = util.immutabledict( (name, opts[name]) for name in supported_names ) self._set_connection_characteristics(connection, characteristics) def _set_connection_characteristics(self, connection, characteristics): characteristic_values = [ (name, self.connection_characteristics[name], value) for name, value in characteristics.items() ] if connection.in_transaction(): trans_objs = [ (name, obj) for name, obj, _ in characteristic_values if obj.transactional ] if trans_objs: raise exc.InvalidRequestError( "This connection has already initialized a SQLAlchemy " "Transaction() object via begin() or autobegin; " "%s may not be altered unless rollback() or commit() " "is called first." % (", ".join(name for name, obj in trans_objs)) ) dbapi_connection = connection.connection.dbapi_connection for _, characteristic, value in characteristic_values: characteristic.set_connection_characteristic( self, connection, dbapi_connection, value ) connection.connection._connection_record.finalize_callback.append( functools.partial(self._reset_characteristics, characteristics) ) def _reset_characteristics(self, characteristics, dbapi_connection): for characteristic_name in characteristics: characteristic = self.connection_characteristics[ characteristic_name ] characteristic.reset_characteristic(self, dbapi_connection) def do_begin(self, dbapi_connection): pass def do_rollback(self, dbapi_connection): dbapi_connection.rollback() def do_commit(self, dbapi_connection): dbapi_connection.commit() def do_terminate(self, dbapi_connection): self.do_close(dbapi_connection) def do_close(self, dbapi_connection): dbapi_connection.close() @util.memoized_property def _dialect_specific_select_one(self): return str(expression.select(1).compile(dialect=self)) def _do_ping_w_event(self, dbapi_connection: DBAPIConnection) -> bool: try: return self.do_ping(dbapi_connection) except self.loaded_dbapi.Error as err: is_disconnect = self.is_disconnect(err, dbapi_connection, None) if self._has_events: try: Connection._handle_dbapi_exception_noconnection( err, self, is_disconnect=is_disconnect, invalidate_pool_on_disconnect=False, is_pre_ping=True, ) except exc.StatementError as new_err: is_disconnect = new_err.connection_invalidated if is_disconnect: return False else: raise def do_ping(self, dbapi_connection: DBAPIConnection) -> bool: cursor = dbapi_connection.cursor() try: cursor.execute(self._dialect_specific_select_one) finally: cursor.close() return True def create_xid(self): """Create a random two-phase transaction ID. This id will be passed to do_begin_twophase(), do_rollback_twophase(), do_commit_twophase(). Its format is unspecified. """ return "_sa_%032x" % random.randint(0, 2**128) def do_savepoint(self, connection, name): connection.execute(expression.SavepointClause(name)) def do_rollback_to_savepoint(self, connection, name): connection.execute(expression.RollbackToSavepointClause(name)) def do_release_savepoint(self, connection, name): connection.execute(expression.ReleaseSavepointClause(name)) def _deliver_insertmanyvalues_batches( self, connection, cursor, statement, parameters, generic_setinputsizes, context, ): context = cast(DefaultExecutionContext, context) compiled = cast(SQLCompiler, context.compiled) _composite_sentinel_proc: Sequence[ Optional[_ResultProcessorType[Any]] ] = () _scalar_sentinel_proc: Optional[_ResultProcessorType[Any]] = None _sentinel_proc_initialized: bool = False compiled_parameters = context.compiled_parameters imv = compiled._insertmanyvalues assert imv is not None is_returning: Final[bool] = bool(compiled.effective_returning) batch_size = context.execution_options.get( "insertmanyvalues_page_size", self.insertmanyvalues_page_size ) if compiled.schema_translate_map: schema_translate_map = context.execution_options.get( "schema_translate_map", {} ) else: schema_translate_map = None if is_returning: result: Optional[List[Any]] = [] context._insertmanyvalues_rows = result sort_by_parameter_order = imv.sort_by_parameter_order else: sort_by_parameter_order = False result = None for imv_batch in compiled._deliver_insertmanyvalues_batches( statement, parameters, compiled_parameters, generic_setinputsizes, batch_size, sort_by_parameter_order, schema_translate_map, ): yield imv_batch if is_returning: try: rows = context.fetchall_for_returning(cursor) except BaseException as be: connection._handle_dbapi_exception( be, sql_util._long_statement(imv_batch.replaced_statement), imv_batch.replaced_parameters, None, context, is_sub_exec=True, ) # I would have thought "is_returning: Final[bool]" # would have assured this but pylance thinks not assert result is not None if imv.num_sentinel_columns and not imv_batch.is_downgraded: composite_sentinel = imv.num_sentinel_columns > 1 if imv.implicit_sentinel: # for implicit sentinel, which is currently single-col # integer autoincrement, do a simple sort. assert not composite_sentinel result.extend( sorted(rows, key=operator.itemgetter(-1)) ) continue # otherwise, create dictionaries to match up batches # with parameters assert imv.sentinel_param_keys assert imv.sentinel_columns _nsc = imv.num_sentinel_columns if not _sentinel_proc_initialized: if composite_sentinel: _composite_sentinel_proc = [ col.type._cached_result_processor( self, cursor_desc[1] ) for col, cursor_desc in zip( imv.sentinel_columns, cursor.description[-_nsc:], ) ] else: _scalar_sentinel_proc = ( imv.sentinel_columns[0] ).type._cached_result_processor( self, cursor.description[-1][1] ) _sentinel_proc_initialized = True rows_by_sentinel: Union[ Dict[Tuple[Any, ...], Any], Dict[Any, Any], ] if composite_sentinel: rows_by_sentinel = { tuple( (proc(val) if proc else val) for val, proc in zip( row[-_nsc:], _composite_sentinel_proc ) ): row for row in rows } elif _scalar_sentinel_proc: rows_by_sentinel = { _scalar_sentinel_proc(row[-1]): row for row in rows } else: rows_by_sentinel = {row[-1]: row for row in rows} if len(rows_by_sentinel) != len(imv_batch.batch): # see test_insert_exec.py:: # IMVSentinelTest::test_sentinel_incorrect_rowcount # for coverage / demonstration raise exc.InvalidRequestError( f"Sentinel-keyed result set did not produce " f"correct number of rows {len(imv_batch.batch)}; " "produced " f"{len(rows_by_sentinel)}. Please ensure the " "sentinel column is fully unique and populated in " "all cases." ) try: ordered_rows = [ rows_by_sentinel[sentinel_keys] for sentinel_keys in imv_batch.sentinel_values ] except KeyError as ke: # see test_insert_exec.py:: # IMVSentinelTest::test_sentinel_cant_match_keys # for coverage / demonstration raise exc.InvalidRequestError( f"Can't match sentinel values in result set to " f"parameter sets; key {ke.args[0]!r} was not " "found. " "There may be a mismatch between the datatype " "passed to the DBAPI driver vs. that which it " "returns in a result row. Ensure the given " "Python value matches the expected result type " "*exactly*, taking care to not rely upon implicit " "conversions which may occur such as when using " "strings in place of UUID or integer values, etc. " ) from ke result.extend(ordered_rows) else: result.extend(rows) def do_executemany(self, cursor, statement, parameters, context=None): cursor.executemany(statement, parameters) def do_execute(self, cursor, statement, parameters, context=None): cursor.execute(statement, parameters) def do_execute_no_params(self, cursor, statement, context=None): cursor.execute(statement) def is_disconnect( self, e: Exception, connection: Union[ pool.PoolProxiedConnection, interfaces.DBAPIConnection, None ], cursor: Optional[interfaces.DBAPICursor], ) -> bool: return False @util.memoized_instancemethod def _gen_allowed_isolation_levels(self, dbapi_conn): try: raw_levels = list(self.get_isolation_level_values(dbapi_conn)) except NotImplementedError: return None else: normalized_levels = [ level.replace("_", " ").upper() for level in raw_levels ] if raw_levels != normalized_levels: raise ValueError( f"Dialect {self.name!r} get_isolation_level_values() " f"method should return names as UPPERCASE using spaces, " f"not underscores; got " f"{sorted(set(raw_levels).difference(normalized_levels))}" ) return tuple(normalized_levels) def _assert_and_set_isolation_level(self, dbapi_conn, level): level = level.replace("_", " ").upper() _allowed_isolation_levels = self._gen_allowed_isolation_levels( dbapi_conn ) if ( _allowed_isolation_levels and level not in _allowed_isolation_levels ): raise exc.ArgumentError( f"Invalid value {level!r} for isolation_level. " f"Valid isolation levels for {self.name!r} are " f"{', '.join(_allowed_isolation_levels)}" ) self.set_isolation_level(dbapi_conn, level) def reset_isolation_level(self, dbapi_conn): if self._on_connect_isolation_level is not None: assert ( self._on_connect_isolation_level == "AUTOCOMMIT" or self._on_connect_isolation_level == self.default_isolation_level ) self._assert_and_set_isolation_level( dbapi_conn, self._on_connect_isolation_level ) else: assert self.default_isolation_level is not None self._assert_and_set_isolation_level( dbapi_conn, self.default_isolation_level, ) def normalize_name(self, name): if name is None: return None name_lower = name.lower() name_upper = name.upper() if name_upper == name_lower: # name has no upper/lower conversion, e.g. non-european characters. # return unchanged return name elif name_upper == name and not ( self.identifier_preparer._requires_quotes )(name_lower): # name is all uppercase and doesn't require quoting; normalize # to all lower case return name_lower elif name_lower == name: # name is all lower case, which if denormalized means we need to # force quoting on it return quoted_name(name, quote=True) else: # name is mixed case, means it will be quoted in SQL when used # later, no normalizes return name def denormalize_name(self, name): if name is None: return None name_lower = name.lower() name_upper = name.upper() if name_upper == name_lower: # name has no upper/lower conversion, e.g. non-european characters. # return unchanged return name elif name_lower == name and not ( self.identifier_preparer._requires_quotes )(name_lower): name = name_upper return name def get_driver_connection(self, connection): return connection def _overrides_default(self, method): return ( getattr(type(self), method).__code__ is not getattr(DefaultDialect, method).__code__ ) def _default_multi_reflect( self, single_tbl_method, connection, kind, schema, filter_names, scope, **kw, ): names_fns = [] temp_names_fns = [] if ObjectKind.TABLE in kind: names_fns.append(self.get_table_names) temp_names_fns.append(self.get_temp_table_names) if ObjectKind.VIEW in kind: names_fns.append(self.get_view_names) temp_names_fns.append(self.get_temp_view_names) if ObjectKind.MATERIALIZED_VIEW in kind: names_fns.append(self.get_materialized_view_names) # no temp materialized view at the moment # temp_names_fns.append(self.get_temp_materialized_view_names) unreflectable = kw.pop("unreflectable", {}) if ( filter_names and scope is ObjectScope.ANY and kind is ObjectKind.ANY ): # if names are given and no qualification on type of table # (i.e. the Table(..., autoload) case), take the names as given, # don't run names queries. If a table does not exit # NoSuchTableError is raised and it's skipped # this also suits the case for mssql where we can reflect # individual temp tables but there's no temp_names_fn names = filter_names else: names = [] name_kw = {"schema": schema, **kw} fns = [] if ObjectScope.DEFAULT in scope: fns.extend(names_fns) if ObjectScope.TEMPORARY in scope: fns.extend(temp_names_fns) for fn in fns: try: names.extend(fn(connection, **name_kw)) except NotImplementedError: pass if filter_names: filter_names = set(filter_names) # iterate over all the tables/views and call the single table method for table in names: if not filter_names or table in filter_names: key = (schema, table) try: yield ( key, single_tbl_method( connection, table, schema=schema, **kw ), ) except exc.UnreflectableTableError as err: if key not in unreflectable: unreflectable[key] = err except exc.NoSuchTableError: pass def get_multi_table_options(self, connection, **kw): return self._default_multi_reflect( self.get_table_options, connection, **kw ) def get_multi_columns(self, connection, **kw): return self._default_multi_reflect(self.get_columns, connection, **kw) def get_multi_pk_constraint(self, connection, **kw): return self._default_multi_reflect( self.get_pk_constraint, connection, **kw ) def get_multi_foreign_keys(self, connection, **kw): return self._default_multi_reflect( self.get_foreign_keys, connection, **kw ) def get_multi_indexes(self, connection, **kw): return self._default_multi_reflect(self.get_indexes, connection, **kw) def get_multi_unique_constraints(self, connection, **kw): return self._default_multi_reflect( self.get_unique_constraints, connection, **kw ) def get_multi_check_constraints(self, connection, **kw): return self._default_multi_reflect( self.get_check_constraints, connection, **kw ) def get_multi_table_comment(self, connection, **kw): return self._default_multi_reflect( self.get_table_comment, connection, **kw ) class StrCompileDialect(DefaultDialect): statement_compiler = compiler.StrSQLCompiler ddl_compiler = compiler.DDLCompiler type_compiler_cls = compiler.StrSQLTypeCompiler preparer = compiler.IdentifierPreparer insert_returning = True update_returning = True delete_returning = True supports_statement_cache = True supports_identity_columns = True supports_sequences = True sequences_optional = True preexecute_autoincrement_sequences = False supports_native_boolean = True supports_multivalues_insert = True supports_simple_order_by_label = True class DefaultExecutionContext(ExecutionContext): isinsert = False isupdate = False isdelete = False is_crud = False is_text = False isddl = False execute_style: ExecuteStyle = ExecuteStyle.EXECUTE compiled: Optional[Compiled] = None result_column_struct: Optional[ Tuple[List[ResultColumnsEntry], bool, bool, bool, bool] ] = None returned_default_rows: Optional[Sequence[Row[Any]]] = None execution_options: _ExecuteOptions = util.EMPTY_DICT cursor_fetch_strategy = _cursor._DEFAULT_FETCH invoked_statement: Optional[Executable] = None _is_implicit_returning = False _is_explicit_returning = False _is_supplemental_returning = False _is_server_side = False _soft_closed = False _rowcount: Optional[int] = None # a hook for SQLite's translation of # result column names # NOTE: pyhive is using this hook, can't remove it :( _translate_colname: Optional[Callable[[str], str]] = None _expanded_parameters: Mapping[str, List[str]] = util.immutabledict() """used by set_input_sizes(). This collection comes from ``ExpandedState.parameter_expansion``. """ cache_hit = NO_CACHE_KEY root_connection: Connection _dbapi_connection: PoolProxiedConnection dialect: Dialect unicode_statement: str cursor: DBAPICursor compiled_parameters: List[_MutableCoreSingleExecuteParams] parameters: _DBAPIMultiExecuteParams extracted_parameters: Optional[Sequence[BindParameter[Any]]] _empty_dict_params = cast("Mapping[str, Any]", util.EMPTY_DICT) _insertmanyvalues_rows: Optional[List[Tuple[Any, ...]]] = None _num_sentinel_cols: int = 0 @classmethod def _init_ddl( cls, dialect: Dialect, connection: Connection, dbapi_connection: PoolProxiedConnection, execution_options: _ExecuteOptions, compiled_ddl: DDLCompiler, ) -> ExecutionContext: """Initialize execution context for an ExecutableDDLElement construct.""" self = cls.__new__(cls) self.root_connection = connection self._dbapi_connection = dbapi_connection self.dialect = connection.dialect self.compiled = compiled = compiled_ddl self.isddl = True self.execution_options = execution_options self.unicode_statement = str(compiled) if compiled.schema_translate_map: schema_translate_map = self.execution_options.get( "schema_translate_map", {} ) rst = compiled.preparer._render_schema_translates self.unicode_statement = rst( self.unicode_statement, schema_translate_map ) self.statement = self.unicode_statement self.cursor = self.create_cursor() self.compiled_parameters = [] if dialect.positional: self.parameters = [dialect.execute_sequence_format()] else: self.parameters = [self._empty_dict_params] return self @classmethod def _init_compiled( cls, dialect: Dialect, connection: Connection, dbapi_connection: PoolProxiedConnection, execution_options: _ExecuteOptions, compiled: SQLCompiler, parameters: _CoreMultiExecuteParams, invoked_statement: Executable, extracted_parameters: Optional[Sequence[BindParameter[Any]]], cache_hit: CacheStats = CacheStats.CACHING_DISABLED, ) -> ExecutionContext: """Initialize execution context for a Compiled construct.""" self = cls.__new__(cls) self.root_connection = connection self._dbapi_connection = dbapi_connection self.dialect = connection.dialect self.extracted_parameters = extracted_parameters self.invoked_statement = invoked_statement self.compiled = compiled self.cache_hit = cache_hit self.execution_options = execution_options self.result_column_struct = ( compiled._result_columns, compiled._ordered_columns, compiled._textual_ordered_columns, compiled._ad_hoc_textual, compiled._loose_column_name_matching, ) self.isinsert = ii = compiled.isinsert self.isupdate = iu = compiled.isupdate self.isdelete = id_ = compiled.isdelete self.is_text = compiled.isplaintext if ii or iu or id_: dml_statement = compiled.compile_state.statement # type: ignore if TYPE_CHECKING: assert isinstance(dml_statement, UpdateBase) self.is_crud = True self._is_explicit_returning = ier = bool(dml_statement._returning) self._is_implicit_returning = iir = bool( compiled.implicit_returning ) if iir and dml_statement._supplemental_returning: self._is_supplemental_returning = True # dont mix implicit and explicit returning assert not (iir and ier) if (ier or iir) and compiled.for_executemany: if ii and not self.dialect.insert_executemany_returning: raise exc.InvalidRequestError( f"Dialect {self.dialect.dialect_description} with " f"current server capabilities does not support " "INSERT..RETURNING when executemany is used" ) elif ( ii and dml_statement._sort_by_parameter_order and not self.dialect.insert_executemany_returning_sort_by_parameter_order # noqa: E501 ): raise exc.InvalidRequestError( f"Dialect {self.dialect.dialect_description} with " f"current server capabilities does not support " "INSERT..RETURNING with deterministic row ordering " "when executemany is used" ) elif ( ii and self.dialect.use_insertmanyvalues and not compiled._insertmanyvalues ): raise exc.InvalidRequestError( 'Statement does not have "insertmanyvalues" ' "enabled, can't use INSERT..RETURNING with " "executemany in this case." ) elif iu and not self.dialect.update_executemany_returning: raise exc.InvalidRequestError( f"Dialect {self.dialect.dialect_description} with " f"current server capabilities does not support " "UPDATE..RETURNING when executemany is used" ) elif id_ and not self.dialect.delete_executemany_returning: raise exc.InvalidRequestError( f"Dialect {self.dialect.dialect_description} with " f"current server capabilities does not support " "DELETE..RETURNING when executemany is used" ) if not parameters: self.compiled_parameters = [ compiled.construct_params( extracted_parameters=extracted_parameters, escape_names=False, ) ] else: self.compiled_parameters = [ compiled.construct_params( m, escape_names=False, _group_number=grp, extracted_parameters=extracted_parameters, ) for grp, m in enumerate(parameters) ] if len(parameters) > 1: if self.isinsert and compiled._insertmanyvalues: self.execute_style = ExecuteStyle.INSERTMANYVALUES imv = compiled._insertmanyvalues if imv.sentinel_columns is not None: self._num_sentinel_cols = imv.num_sentinel_columns else: self.execute_style = ExecuteStyle.EXECUTEMANY self.unicode_statement = compiled.string self.cursor = self.create_cursor() if self.compiled.insert_prefetch or self.compiled.update_prefetch: self._process_execute_defaults() processors = compiled._bind_processors flattened_processors: Mapping[ str, _BindProcessorType[Any] ] = processors # type: ignore[assignment] if compiled.literal_execute_params or compiled.post_compile_params: if self.executemany: raise exc.InvalidRequestError( "'literal_execute' or 'expanding' parameters can't be " "used with executemany()" ) expanded_state = compiled._process_parameters_for_postcompile( self.compiled_parameters[0] ) # re-assign self.unicode_statement self.unicode_statement = expanded_state.statement self._expanded_parameters = expanded_state.parameter_expansion flattened_processors = dict(processors) # type: ignore flattened_processors.update(expanded_state.processors) positiontup = expanded_state.positiontup elif compiled.positional: positiontup = self.compiled.positiontup else: positiontup = None if compiled.schema_translate_map: schema_translate_map = self.execution_options.get( "schema_translate_map", {} ) rst = compiled.preparer._render_schema_translates self.unicode_statement = rst( self.unicode_statement, schema_translate_map ) # final self.unicode_statement is now assigned, encode if needed # by dialect self.statement = self.unicode_statement # Convert the dictionary of bind parameter values # into a dict or list to be sent to the DBAPI's # execute() or executemany() method. if compiled.positional: core_positional_parameters: MutableSequence[Sequence[Any]] = [] assert positiontup is not None for compiled_params in self.compiled_parameters: l_param: List[Any] = [ ( flattened_processors[key](compiled_params[key]) if key in flattened_processors else compiled_params[key] ) for key in positiontup ] core_positional_parameters.append( dialect.execute_sequence_format(l_param) ) self.parameters = core_positional_parameters else: core_dict_parameters: MutableSequence[Dict[str, Any]] = [] escaped_names = compiled.escaped_bind_names # note that currently, "expanded" parameters will be present # in self.compiled_parameters in their quoted form. This is # slightly inconsistent with the approach taken as of # #8056 where self.compiled_parameters is meant to contain unquoted # param names. d_param: Dict[str, Any] for compiled_params in self.compiled_parameters: if escaped_names: d_param = { escaped_names.get(key, key): ( flattened_processors[key](compiled_params[key]) if key in flattened_processors else compiled_params[key] ) for key in compiled_params } else: d_param = { key: ( flattened_processors[key](compiled_params[key]) if key in flattened_processors else compiled_params[key] ) for key in compiled_params } core_dict_parameters.append(d_param) self.parameters = core_dict_parameters return self @classmethod def _init_statement( cls, dialect: Dialect, connection: Connection, dbapi_connection: PoolProxiedConnection, execution_options: _ExecuteOptions, statement: str, parameters: _DBAPIMultiExecuteParams, ) -> ExecutionContext: """Initialize execution context for a string SQL statement.""" self = cls.__new__(cls) self.root_connection = connection self._dbapi_connection = dbapi_connection self.dialect = connection.dialect self.is_text = True self.execution_options = execution_options if not parameters: if self.dialect.positional: self.parameters = [dialect.execute_sequence_format()] else: self.parameters = [self._empty_dict_params] elif isinstance(parameters[0], dialect.execute_sequence_format): self.parameters = parameters elif isinstance(parameters[0], dict): self.parameters = parameters else: self.parameters = [ dialect.execute_sequence_format(p) for p in parameters ] if len(parameters) > 1: self.execute_style = ExecuteStyle.EXECUTEMANY self.statement = self.unicode_statement = statement self.cursor = self.create_cursor() return self @classmethod def _init_default( cls, dialect: Dialect, connection: Connection, dbapi_connection: PoolProxiedConnection, execution_options: _ExecuteOptions, ) -> ExecutionContext: """Initialize execution context for a ColumnDefault construct.""" self = cls.__new__(cls) self.root_connection = connection self._dbapi_connection = dbapi_connection self.dialect = connection.dialect self.execution_options = execution_options self.cursor = self.create_cursor() return self def _get_cache_stats(self) -> str: if self.compiled is None: return "raw sql" now = perf_counter() ch = self.cache_hit gen_time = self.compiled._gen_time assert gen_time is not None if ch is NO_CACHE_KEY: return "no key %.5fs" % (now - gen_time,) elif ch is CACHE_HIT: return "cached since %.4gs ago" % (now - gen_time,) elif ch is CACHE_MISS: return "generated in %.5fs" % (now - gen_time,) elif ch is CACHING_DISABLED: if "_cache_disable_reason" in self.execution_options: return "caching disabled (%s) %.5fs " % ( self.execution_options["_cache_disable_reason"], now - gen_time, ) else: return "caching disabled %.5fs" % (now - gen_time,) elif ch is NO_DIALECT_SUPPORT: return "dialect %s+%s does not support caching %.5fs" % ( self.dialect.name, self.dialect.driver, now - gen_time, ) else: return "unknown" @property def executemany(self): return self.execute_style in ( ExecuteStyle.EXECUTEMANY, ExecuteStyle.INSERTMANYVALUES, ) @util.memoized_property def identifier_preparer(self): if self.compiled: return self.compiled.preparer elif "schema_translate_map" in self.execution_options: return self.dialect.identifier_preparer._with_schema_translate( self.execution_options["schema_translate_map"] ) else: return self.dialect.identifier_preparer @util.memoized_property def engine(self): return self.root_connection.engine @util.memoized_property def postfetch_cols(self) -> Optional[Sequence[Column[Any]]]: if TYPE_CHECKING: assert isinstance(self.compiled, SQLCompiler) return self.compiled.postfetch @util.memoized_property def prefetch_cols(self) -> Optional[Sequence[Column[Any]]]: if TYPE_CHECKING: assert isinstance(self.compiled, SQLCompiler) if self.isinsert: return self.compiled.insert_prefetch elif self.isupdate: return self.compiled.update_prefetch else: return () @util.memoized_property def no_parameters(self): return self.execution_options.get("no_parameters", False) def _execute_scalar( self, stmt: str, type_: Optional[TypeEngine[Any]], parameters: Optional[_DBAPISingleExecuteParams] = None, ) -> Any: """Execute a string statement on the current cursor, returning a scalar result. Used to fire off sequences, default phrases, and "select lastrowid" types of statements individually or in the context of a parent INSERT or UPDATE statement. """ conn = self.root_connection if "schema_translate_map" in self.execution_options: schema_translate_map = self.execution_options.get( "schema_translate_map", {} ) rst = self.identifier_preparer._render_schema_translates stmt = rst(stmt, schema_translate_map) if not parameters: if self.dialect.positional: parameters = self.dialect.execute_sequence_format() else: parameters = {} conn._cursor_execute(self.cursor, stmt, parameters, context=self) row = self.cursor.fetchone() if row is not None: r = row[0] else: r = None if type_ is not None: # apply type post processors to the result proc = type_._cached_result_processor( self.dialect, self.cursor.description[0][1] ) if proc: return proc(r) return r @util.memoized_property def connection(self): return self.root_connection def _use_server_side_cursor(self): if not self.dialect.supports_server_side_cursors: return False if self.dialect.server_side_cursors: # this is deprecated use_server_side = self.execution_options.get( "stream_results", True ) and ( self.compiled and isinstance(self.compiled.statement, expression.Selectable) or ( ( not self.compiled or isinstance( self.compiled.statement, expression.TextClause ) ) and self.unicode_statement and SERVER_SIDE_CURSOR_RE.match(self.unicode_statement) ) ) else: use_server_side = self.execution_options.get( "stream_results", False ) return use_server_side def create_cursor(self) -> DBAPICursor: if ( # inlining initial preference checks for SS cursors self.dialect.supports_server_side_cursors and ( self.execution_options.get("stream_results", False) or ( self.dialect.server_side_cursors and self._use_server_side_cursor() ) ) ): self._is_server_side = True return self.create_server_side_cursor() else: self._is_server_side = False return self.create_default_cursor() def fetchall_for_returning(self, cursor): return cursor.fetchall() def create_default_cursor(self) -> DBAPICursor: return self._dbapi_connection.cursor() def create_server_side_cursor(self) -> DBAPICursor: raise NotImplementedError() def pre_exec(self): pass def get_out_parameter_values(self, names): raise NotImplementedError( "This dialect does not support OUT parameters" ) def post_exec(self): pass def get_result_processor(self, type_, colname, coltype): """Return a 'result processor' for a given type as present in cursor.description. This has a default implementation that dialects can override for context-sensitive result type handling. """ return type_._cached_result_processor(self.dialect, coltype) def get_lastrowid(self): """return self.cursor.lastrowid, or equivalent, after an INSERT. This may involve calling special cursor functions, issuing a new SELECT on the cursor (or a new one), or returning a stored value that was calculated within post_exec(). This function will only be called for dialects which support "implicit" primary key generation, keep preexecute_autoincrement_sequences set to False, and when no explicit id value was bound to the statement. The function is called once for an INSERT statement that would need to return the last inserted primary key for those dialects that make use of the lastrowid concept. In these cases, it is called directly after :meth:`.ExecutionContext.post_exec`. """ return self.cursor.lastrowid def handle_dbapi_exception(self, e): pass @util.non_memoized_property def rowcount(self) -> int: if self._rowcount is not None: return self._rowcount else: return self.cursor.rowcount @property def _has_rowcount(self): return self._rowcount is not None def supports_sane_rowcount(self): return self.dialect.supports_sane_rowcount def supports_sane_multi_rowcount(self): return self.dialect.supports_sane_multi_rowcount def _setup_result_proxy(self): exec_opt = self.execution_options if self._rowcount is None and exec_opt.get("preserve_rowcount", False): self._rowcount = self.cursor.rowcount if self.is_crud or self.is_text: result = self._setup_dml_or_text_result() yp = False else: yp = exec_opt.get("yield_per", None) sr = self._is_server_side or exec_opt.get("stream_results", False) strategy = self.cursor_fetch_strategy if sr and strategy is _cursor._DEFAULT_FETCH: strategy = _cursor.BufferedRowCursorFetchStrategy( self.cursor, self.execution_options ) cursor_description: _DBAPICursorDescription = ( strategy.alternate_cursor_description or self.cursor.description ) if cursor_description is None: strategy = _cursor._NO_CURSOR_DQL result = _cursor.CursorResult(self, strategy, cursor_description) compiled = self.compiled if ( compiled and not self.isddl and cast(SQLCompiler, compiled).has_out_parameters ): self._setup_out_parameters(result) self._soft_closed = result._soft_closed if yp: result = result.yield_per(yp) return result def _setup_out_parameters(self, result): compiled = cast(SQLCompiler, self.compiled) out_bindparams = [ (param, name) for param, name in compiled.bind_names.items() if param.isoutparam ] out_parameters = {} for bindparam, raw_value in zip( [param for param, name in out_bindparams], self.get_out_parameter_values( [name for param, name in out_bindparams] ), ): type_ = bindparam.type impl_type = type_.dialect_impl(self.dialect) dbapi_type = impl_type.get_dbapi_type(self.dialect.loaded_dbapi) result_processor = impl_type.result_processor( self.dialect, dbapi_type ) if result_processor is not None: raw_value = result_processor(raw_value) out_parameters[bindparam.key] = raw_value result.out_parameters = out_parameters def _setup_dml_or_text_result(self): compiled = cast(SQLCompiler, self.compiled) strategy: ResultFetchStrategy = self.cursor_fetch_strategy if self.isinsert: if ( self.execute_style is ExecuteStyle.INSERTMANYVALUES and compiled.effective_returning ): strategy = _cursor.FullyBufferedCursorFetchStrategy( self.cursor, initial_buffer=self._insertmanyvalues_rows, # maintain alt cursor description if set by the # dialect, e.g. mssql preserves it alternate_description=( strategy.alternate_cursor_description ), ) if compiled.postfetch_lastrowid: self.inserted_primary_key_rows = ( self._setup_ins_pk_from_lastrowid() ) # else if not self._is_implicit_returning, # the default inserted_primary_key_rows accessor will # return an "empty" primary key collection when accessed. if self._is_server_side and strategy is _cursor._DEFAULT_FETCH: strategy = _cursor.BufferedRowCursorFetchStrategy( self.cursor, self.execution_options ) if strategy is _cursor._NO_CURSOR_DML: cursor_description = None else: cursor_description = ( strategy.alternate_cursor_description or self.cursor.description ) if cursor_description is None: strategy = _cursor._NO_CURSOR_DML elif self._num_sentinel_cols: assert self.execute_style is ExecuteStyle.INSERTMANYVALUES # strip out the sentinel columns from cursor description # a similar logic is done to the rows only in CursorResult cursor_description = cursor_description[ 0 : -self._num_sentinel_cols ] result: _cursor.CursorResult[Any] = _cursor.CursorResult( self, strategy, cursor_description ) if self.isinsert: if self._is_implicit_returning: rows = result.all() self.returned_default_rows = rows self.inserted_primary_key_rows = ( self._setup_ins_pk_from_implicit_returning(result, rows) ) # test that it has a cursor metadata that is accurate. the # first row will have been fetched and current assumptions # are that the result has only one row, until executemany() # support is added here. assert result._metadata.returns_rows # Insert statement has both return_defaults() and # returning(). rewind the result on the list of rows # we just used. if self._is_supplemental_returning: result._rewind(rows) else: result._soft_close() elif not self._is_explicit_returning: result._soft_close() # we assume here the result does not return any rows. # *usually*, this will be true. However, some dialects # such as that of MSSQL/pyodbc need to SELECT a post fetch # function so this is not necessarily true. # assert not result.returns_rows elif self._is_implicit_returning: rows = result.all() if rows: self.returned_default_rows = rows self._rowcount = len(rows) if self._is_supplemental_returning: result._rewind(rows) else: result._soft_close() # test that it has a cursor metadata that is accurate. # the rows have all been fetched however. assert result._metadata.returns_rows elif not result._metadata.returns_rows: # no results, get rowcount # (which requires open cursor on some drivers) if self._rowcount is None: self._rowcount = self.cursor.rowcount result._soft_close() elif self.isupdate or self.isdelete: if self._rowcount is None: self._rowcount = self.cursor.rowcount return result @util.memoized_property def inserted_primary_key_rows(self): # if no specific "get primary key" strategy was set up # during execution, return a "default" primary key based # on what's in the compiled_parameters and nothing else. return self._setup_ins_pk_from_empty() def _setup_ins_pk_from_lastrowid(self): getter = cast( SQLCompiler, self.compiled )._inserted_primary_key_from_lastrowid_getter lastrowid = self.get_lastrowid() return [getter(lastrowid, self.compiled_parameters[0])] def _setup_ins_pk_from_empty(self): getter = cast( SQLCompiler, self.compiled )._inserted_primary_key_from_lastrowid_getter return [getter(None, param) for param in self.compiled_parameters] def _setup_ins_pk_from_implicit_returning(self, result, rows): if not rows: return [] getter = cast( SQLCompiler, self.compiled )._inserted_primary_key_from_returning_getter compiled_params = self.compiled_parameters return [ getter(row, param) for row, param in zip(rows, compiled_params) ] def lastrow_has_defaults(self): return (self.isinsert or self.isupdate) and bool( cast(SQLCompiler, self.compiled).postfetch ) def _prepare_set_input_sizes( self, ) -> Optional[List[Tuple[str, Any, TypeEngine[Any]]]]: """Given a cursor and ClauseParameters, prepare arguments in order to call the appropriate style of ``setinputsizes()`` on the cursor, using DB-API types from the bind parameter's ``TypeEngine`` objects. This method only called by those dialects which set the :attr:`.Dialect.bind_typing` attribute to :attr:`.BindTyping.SETINPUTSIZES`. Python-oracledb and cx_Oracle are the only DBAPIs that requires setinputsizes(); pyodbc offers it as an option. Prior to SQLAlchemy 2.0, the setinputsizes() approach was also used for pg8000 and asyncpg, which has been changed to inline rendering of casts. """ if self.isddl or self.is_text: return None compiled = cast(SQLCompiler, self.compiled) inputsizes = compiled._get_set_input_sizes_lookup() if inputsizes is None: return None dialect = self.dialect # all of the rest of this... cython? if dialect._has_events: inputsizes = dict(inputsizes) dialect.dispatch.do_setinputsizes( inputsizes, self.cursor, self.statement, self.parameters, self ) if compiled.escaped_bind_names: escaped_bind_names = compiled.escaped_bind_names else: escaped_bind_names = None if dialect.positional: items = [ (key, compiled.binds[key]) for key in compiled.positiontup or () ] else: items = [ (key, bindparam) for bindparam, key in compiled.bind_names.items() ] generic_inputsizes: List[Tuple[str, Any, TypeEngine[Any]]] = [] for key, bindparam in items: if bindparam in compiled.literal_execute_params: continue if key in self._expanded_parameters: if is_tuple_type(bindparam.type): num = len(bindparam.type.types) dbtypes = inputsizes[bindparam] generic_inputsizes.extend( ( ( escaped_bind_names.get(paramname, paramname) if escaped_bind_names is not None else paramname ), dbtypes[idx % num], bindparam.type.types[idx % num], ) for idx, paramname in enumerate( self._expanded_parameters[key] ) ) else: dbtype = inputsizes.get(bindparam, None) generic_inputsizes.extend( ( ( escaped_bind_names.get(paramname, paramname) if escaped_bind_names is not None else paramname ), dbtype, bindparam.type, ) for paramname in self._expanded_parameters[key] ) else: dbtype = inputsizes.get(bindparam, None) escaped_name = ( escaped_bind_names.get(key, key) if escaped_bind_names is not None else key ) generic_inputsizes.append( (escaped_name, dbtype, bindparam.type) ) return generic_inputsizes def _exec_default(self, column, default, type_): if default.is_sequence: return self.fire_sequence(default, type_) elif default.is_callable: # this codepath is not normally used as it's inlined # into _process_execute_defaults self.current_column = column return default.arg(self) elif default.is_clause_element: return self._exec_default_clause_element(column, default, type_) else: # this codepath is not normally used as it's inlined # into _process_execute_defaults return default.arg def _exec_default_clause_element(self, column, default, type_): # execute a default that's a complete clause element. Here, we have # to re-implement a miniature version of the compile->parameters-> # cursor.execute() sequence, since we don't want to modify the state # of the connection / result in progress or create new connection/ # result objects etc. # .. versionchanged:: 1.4 if not default._arg_is_typed: default_arg = expression.type_coerce(default.arg, type_) else: default_arg = default.arg compiled = expression.select(default_arg).compile(dialect=self.dialect) compiled_params = compiled.construct_params() processors = compiled._bind_processors if compiled.positional: parameters = self.dialect.execute_sequence_format( [ ( processors[key](compiled_params[key]) # type: ignore if key in processors else compiled_params[key] ) for key in compiled.positiontup or () ] ) else: parameters = { key: ( processors[key](compiled_params[key]) # type: ignore if key in processors else compiled_params[key] ) for key in compiled_params } return self._execute_scalar( str(compiled), type_, parameters=parameters ) current_parameters: Optional[_CoreSingleExecuteParams] = None """A dictionary of parameters applied to the current row. This attribute is only available in the context of a user-defined default generation function, e.g. as described at :ref:`context_default_functions`. It consists of a dictionary which includes entries for each column/value pair that is to be part of the INSERT or UPDATE statement. The keys of the dictionary will be the key value of each :class:`_schema.Column`, which is usually synonymous with the name. Note that the :attr:`.DefaultExecutionContext.current_parameters` attribute does not accommodate for the "multi-values" feature of the :meth:`_expression.Insert.values` method. The :meth:`.DefaultExecutionContext.get_current_parameters` method should be preferred. .. seealso:: :meth:`.DefaultExecutionContext.get_current_parameters` :ref:`context_default_functions` """ def get_current_parameters(self, isolate_multiinsert_groups=True): """Return a dictionary of parameters applied to the current row. This method can only be used in the context of a user-defined default generation function, e.g. as described at :ref:`context_default_functions`. When invoked, a dictionary is returned which includes entries for each column/value pair that is part of the INSERT or UPDATE statement. The keys of the dictionary will be the key value of each :class:`_schema.Column`, which is usually synonymous with the name. :param isolate_multiinsert_groups=True: indicates that multi-valued INSERT constructs created using :meth:`_expression.Insert.values` should be handled by returning only the subset of parameters that are local to the current column default invocation. When ``False``, the raw parameters of the statement are returned including the naming convention used in the case of multi-valued INSERT. .. versionadded:: 1.2 added :meth:`.DefaultExecutionContext.get_current_parameters` which provides more functionality over the existing :attr:`.DefaultExecutionContext.current_parameters` attribute. .. seealso:: :attr:`.DefaultExecutionContext.current_parameters` :ref:`context_default_functions` """ try: parameters = self.current_parameters column = self.current_column except AttributeError: raise exc.InvalidRequestError( "get_current_parameters() can only be invoked in the " "context of a Python side column default function" ) else: assert column is not None assert parameters is not None compile_state = cast( "DMLState", cast(SQLCompiler, self.compiled).compile_state ) assert compile_state is not None if ( isolate_multiinsert_groups and dml.isinsert(compile_state) and compile_state._has_multi_parameters ): if column._is_multiparam_column: index = column.index + 1 d = {column.original.key: parameters[column.key]} else: d = {column.key: parameters[column.key]} index = 0 assert compile_state._dict_parameters is not None keys = compile_state._dict_parameters.keys() d.update( (key, parameters["%s_m%d" % (key, index)]) for key in keys ) return d else: return parameters def get_insert_default(self, column): if column.default is None: return None else: return self._exec_default(column, column.default, column.type) def get_update_default(self, column): if column.onupdate is None: return None else: return self._exec_default(column, column.onupdate, column.type) def _process_execute_defaults(self): compiled = cast(SQLCompiler, self.compiled) key_getter = compiled._within_exec_param_key_getter sentinel_counter = 0 if compiled.insert_prefetch: prefetch_recs = [ ( c, key_getter(c), c._default_description_tuple, self.get_insert_default, ) for c in compiled.insert_prefetch ] elif compiled.update_prefetch: prefetch_recs = [ ( c, key_getter(c), c._onupdate_description_tuple, self.get_update_default, ) for c in compiled.update_prefetch ] else: prefetch_recs = [] for param in self.compiled_parameters: self.current_parameters = param for ( c, param_key, (arg, is_scalar, is_callable, is_sentinel), fallback, ) in prefetch_recs: if is_sentinel: param[param_key] = sentinel_counter sentinel_counter += 1 elif is_scalar: param[param_key] = arg elif is_callable: self.current_column = c param[param_key] = arg(self) else: val = fallback(c) if val is not None: param[param_key] = val del self.current_parameters DefaultDialect.execution_ctx_cls = DefaultExecutionContext sqlalchemy/engine/_py_row.py 0000755 00000007313 15125143220 0012205 0 ustar 00 # engine/_py_row.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php from __future__ import annotations import operator import typing from typing import Any from typing import Callable from typing import Dict from typing import Iterator from typing import List from typing import Mapping from typing import Optional from typing import Tuple from typing import Type if typing.TYPE_CHECKING: from .result import _KeyType from .result import _ProcessorsType from .result import _RawRowType from .result import _TupleGetterType from .result import ResultMetaData MD_INDEX = 0 # integer index in cursor.description class BaseRow: __slots__ = ("_parent", "_data", "_key_to_index") _parent: ResultMetaData _key_to_index: Mapping[_KeyType, int] _data: _RawRowType def __init__( self, parent: ResultMetaData, processors: Optional[_ProcessorsType], key_to_index: Mapping[_KeyType, int], data: _RawRowType, ): """Row objects are constructed by CursorResult objects.""" object.__setattr__(self, "_parent", parent) object.__setattr__(self, "_key_to_index", key_to_index) if processors: object.__setattr__( self, "_data", tuple( [ proc(value) if proc else value for proc, value in zip(processors, data) ] ), ) else: object.__setattr__(self, "_data", tuple(data)) def __reduce__(self) -> Tuple[Callable[..., BaseRow], Tuple[Any, ...]]: return ( rowproxy_reconstructor, (self.__class__, self.__getstate__()), ) def __getstate__(self) -> Dict[str, Any]: return {"_parent": self._parent, "_data": self._data} def __setstate__(self, state: Dict[str, Any]) -> None: parent = state["_parent"] object.__setattr__(self, "_parent", parent) object.__setattr__(self, "_data", state["_data"]) object.__setattr__(self, "_key_to_index", parent._key_to_index) def _values_impl(self) -> List[Any]: return list(self) def __iter__(self) -> Iterator[Any]: return iter(self._data) def __len__(self) -> int: return len(self._data) def __hash__(self) -> int: return hash(self._data) def __getitem__(self, key: Any) -> Any: return self._data[key] def _get_by_key_impl_mapping(self, key: str) -> Any: try: return self._data[self._key_to_index[key]] except KeyError: pass self._parent._key_not_found(key, False) def __getattr__(self, name: str) -> Any: try: return self._data[self._key_to_index[name]] except KeyError: pass self._parent._key_not_found(name, True) def _to_tuple_instance(self) -> Tuple[Any, ...]: return self._data # This reconstructor is necessary so that pickles with the Cy extension or # without use the same Binary format. def rowproxy_reconstructor( cls: Type[BaseRow], state: Dict[str, Any] ) -> BaseRow: obj = cls.__new__(cls) obj.__setstate__(state) return obj def tuplegetter(*indexes: int) -> _TupleGetterType: if len(indexes) != 1: for i in range(1, len(indexes)): if indexes[i - 1] != indexes[i] - 1: return operator.itemgetter(*indexes) # slice form is faster but returns a list if input is list return operator.itemgetter(slice(indexes[0], indexes[-1] + 1)) sqlalchemy/engine/strategies.py 0000755 00000000672 15125143220 0012702 0 ustar 00 # engine/strategies.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """Deprecated mock engine strategy used by Alembic. """ from __future__ import annotations from .mock import MockConnection # noqa class MockEngineStrategy: MockConnection = MockConnection sqlalchemy/engine/url.py 0000755 00000074533 15125143220 0011341 0 ustar 00 # engine/url.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """Provides the :class:`~sqlalchemy.engine.url.URL` class which encapsulates information about a database connection specification. The URL object is created automatically when :func:`~sqlalchemy.engine.create_engine` is called with a string argument; alternatively, the URL is a public-facing construct which can be used directly and is also accepted directly by ``create_engine()``. """ from __future__ import annotations import collections.abc as collections_abc import re from typing import Any from typing import cast from typing import Dict from typing import Iterable from typing import List from typing import Mapping from typing import NamedTuple from typing import Optional from typing import overload from typing import Sequence from typing import Tuple from typing import Type from typing import Union from urllib.parse import parse_qsl from urllib.parse import quote from urllib.parse import quote_plus from urllib.parse import unquote from .interfaces import Dialect from .. import exc from .. import util from ..dialects import plugins from ..dialects import registry class URL(NamedTuple): """ Represent the components of a URL used to connect to a database. URLs are typically constructed from a fully formatted URL string, where the :func:`.make_url` function is used internally by the :func:`_sa.create_engine` function in order to parse the URL string into its individual components, which are then used to construct a new :class:`.URL` object. When parsing from a formatted URL string, the parsing format generally follows `RFC-1738 <https://www.ietf.org/rfc/rfc1738.txt>`_, with some exceptions. A :class:`_engine.URL` object may also be produced directly, either by using the :func:`.make_url` function with a fully formed URL string, or by using the :meth:`_engine.URL.create` constructor in order to construct a :class:`_engine.URL` programmatically given individual fields. The resulting :class:`.URL` object may be passed directly to :func:`_sa.create_engine` in place of a string argument, which will bypass the usage of :func:`.make_url` within the engine's creation process. .. versionchanged:: 1.4 The :class:`_engine.URL` object is now an immutable object. To create a URL, use the :func:`_engine.make_url` or :meth:`_engine.URL.create` function / method. To modify a :class:`_engine.URL`, use methods like :meth:`_engine.URL.set` and :meth:`_engine.URL.update_query_dict` to return a new :class:`_engine.URL` object with modifications. See notes for this change at :ref:`change_5526`. .. seealso:: :ref:`database_urls` :class:`_engine.URL` contains the following attributes: * :attr:`_engine.URL.drivername`: database backend and driver name, such as ``postgresql+psycopg2`` * :attr:`_engine.URL.username`: username string * :attr:`_engine.URL.password`: password string * :attr:`_engine.URL.host`: string hostname * :attr:`_engine.URL.port`: integer port number * :attr:`_engine.URL.database`: string database name * :attr:`_engine.URL.query`: an immutable mapping representing the query string. contains strings for keys and either strings or tuples of strings for values. """ drivername: str """database backend and driver name, such as ``postgresql+psycopg2`` """ username: Optional[str] "username string" password: Optional[str] """password, which is normally a string but may also be any object that has a ``__str__()`` method.""" host: Optional[str] """hostname or IP number. May also be a data source name for some drivers.""" port: Optional[int] """integer port number""" database: Optional[str] """database name""" query: util.immutabledict[str, Union[Tuple[str, ...], str]] """an immutable mapping representing the query string. contains strings for keys and either strings or tuples of strings for values, e.g.:: >>> from sqlalchemy.engine import make_url >>> url = make_url( ... "postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt" ... ) >>> url.query immutabledict({'alt_host': ('host1', 'host2'), 'ssl_cipher': '/path/to/crt'}) To create a mutable copy of this mapping, use the ``dict`` constructor:: mutable_query_opts = dict(url.query) .. seealso:: :attr:`_engine.URL.normalized_query` - normalizes all values into sequences for consistent processing Methods for altering the contents of :attr:`_engine.URL.query`: :meth:`_engine.URL.update_query_dict` :meth:`_engine.URL.update_query_string` :meth:`_engine.URL.update_query_pairs` :meth:`_engine.URL.difference_update_query` """ # noqa: E501 @classmethod def create( cls, drivername: str, username: Optional[str] = None, password: Optional[str] = None, host: Optional[str] = None, port: Optional[int] = None, database: Optional[str] = None, query: Mapping[str, Union[Sequence[str], str]] = util.EMPTY_DICT, ) -> URL: """Create a new :class:`_engine.URL` object. .. seealso:: :ref:`database_urls` :param drivername: the name of the database backend. This name will correspond to a module in sqlalchemy/databases or a third party plug-in. :param username: The user name. :param password: database password. Is typically a string, but may also be an object that can be stringified with ``str()``. .. note:: The password string should **not** be URL encoded when passed as an argument to :meth:`_engine.URL.create`; the string should contain the password characters exactly as they would be typed. .. note:: A password-producing object will be stringified only **once** per :class:`_engine.Engine` object. For dynamic password generation per connect, see :ref:`engines_dynamic_tokens`. :param host: The name of the host. :param port: The port number. :param database: The database name. :param query: A dictionary of string keys to string values to be passed to the dialect and/or the DBAPI upon connect. To specify non-string parameters to a Python DBAPI directly, use the :paramref:`_sa.create_engine.connect_args` parameter to :func:`_sa.create_engine`. See also :attr:`_engine.URL.normalized_query` for a dictionary that is consistently string->list of string. :return: new :class:`_engine.URL` object. .. versionadded:: 1.4 The :class:`_engine.URL` object is now an **immutable named tuple**. In addition, the ``query`` dictionary is also immutable. To create a URL, use the :func:`_engine.url.make_url` or :meth:`_engine.URL.create` function/ method. To modify a :class:`_engine.URL`, use the :meth:`_engine.URL.set` and :meth:`_engine.URL.update_query` methods. """ return cls( cls._assert_str(drivername, "drivername"), cls._assert_none_str(username, "username"), password, cls._assert_none_str(host, "host"), cls._assert_port(port), cls._assert_none_str(database, "database"), cls._str_dict(query), ) @classmethod def _assert_port(cls, port: Optional[int]) -> Optional[int]: if port is None: return None try: return int(port) except TypeError: raise TypeError("Port argument must be an integer or None") @classmethod def _assert_str(cls, v: str, paramname: str) -> str: if not isinstance(v, str): raise TypeError("%s must be a string" % paramname) return v @classmethod def _assert_none_str( cls, v: Optional[str], paramname: str ) -> Optional[str]: if v is None: return v return cls._assert_str(v, paramname) @classmethod def _str_dict( cls, dict_: Optional[ Union[ Sequence[Tuple[str, Union[Sequence[str], str]]], Mapping[str, Union[Sequence[str], str]], ] ], ) -> util.immutabledict[str, Union[Tuple[str, ...], str]]: if dict_ is None: return util.EMPTY_DICT @overload def _assert_value( val: str, ) -> str: ... @overload def _assert_value( val: Sequence[str], ) -> Union[str, Tuple[str, ...]]: ... def _assert_value( val: Union[str, Sequence[str]], ) -> Union[str, Tuple[str, ...]]: if isinstance(val, str): return val elif isinstance(val, collections_abc.Sequence): return tuple(_assert_value(elem) for elem in val) else: raise TypeError( "Query dictionary values must be strings or " "sequences of strings" ) def _assert_str(v: str) -> str: if not isinstance(v, str): raise TypeError("Query dictionary keys must be strings") return v dict_items: Iterable[Tuple[str, Union[Sequence[str], str]]] if isinstance(dict_, collections_abc.Sequence): dict_items = dict_ else: dict_items = dict_.items() return util.immutabledict( { _assert_str(key): _assert_value( value, ) for key, value in dict_items } ) def set( self, drivername: Optional[str] = None, username: Optional[str] = None, password: Optional[str] = None, host: Optional[str] = None, port: Optional[int] = None, database: Optional[str] = None, query: Optional[Mapping[str, Union[Sequence[str], str]]] = None, ) -> URL: """return a new :class:`_engine.URL` object with modifications. Values are used if they are non-None. To set a value to ``None`` explicitly, use the :meth:`_engine.URL._replace` method adapted from ``namedtuple``. :param drivername: new drivername :param username: new username :param password: new password :param host: new hostname :param port: new port :param query: new query parameters, passed a dict of string keys referring to string or sequence of string values. Fully replaces the previous list of arguments. :return: new :class:`_engine.URL` object. .. versionadded:: 1.4 .. seealso:: :meth:`_engine.URL.update_query_dict` """ kw: Dict[str, Any] = {} if drivername is not None: kw["drivername"] = drivername if username is not None: kw["username"] = username if password is not None: kw["password"] = password if host is not None: kw["host"] = host if port is not None: kw["port"] = port if database is not None: kw["database"] = database if query is not None: kw["query"] = query return self._assert_replace(**kw) def _assert_replace(self, **kw: Any) -> URL: """argument checks before calling _replace()""" if "drivername" in kw: self._assert_str(kw["drivername"], "drivername") for name in "username", "host", "database": if name in kw: self._assert_none_str(kw[name], name) if "port" in kw: self._assert_port(kw["port"]) if "query" in kw: kw["query"] = self._str_dict(kw["query"]) return self._replace(**kw) def update_query_string( self, query_string: str, append: bool = False ) -> URL: """Return a new :class:`_engine.URL` object with the :attr:`_engine.URL.query` parameter dictionary updated by the given query string. E.g.:: >>> from sqlalchemy.engine import make_url >>> url = make_url("postgresql+psycopg2://user:pass@host/dbname") >>> url = url.update_query_string( ... "alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt" ... ) >>> str(url) 'postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt' :param query_string: a URL escaped query string, not including the question mark. :param append: if True, parameters in the existing query string will not be removed; new parameters will be in addition to those present. If left at its default of False, keys present in the given query parameters will replace those of the existing query string. .. versionadded:: 1.4 .. seealso:: :attr:`_engine.URL.query` :meth:`_engine.URL.update_query_dict` """ # noqa: E501 return self.update_query_pairs(parse_qsl(query_string), append=append) def update_query_pairs( self, key_value_pairs: Iterable[Tuple[str, Union[str, List[str]]]], append: bool = False, ) -> URL: """Return a new :class:`_engine.URL` object with the :attr:`_engine.URL.query` parameter dictionary updated by the given sequence of key/value pairs E.g.:: >>> from sqlalchemy.engine import make_url >>> url = make_url("postgresql+psycopg2://user:pass@host/dbname") >>> url = url.update_query_pairs( ... [ ... ("alt_host", "host1"), ... ("alt_host", "host2"), ... ("ssl_cipher", "/path/to/crt"), ... ] ... ) >>> str(url) 'postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt' :param key_value_pairs: A sequence of tuples containing two strings each. :param append: if True, parameters in the existing query string will not be removed; new parameters will be in addition to those present. If left at its default of False, keys present in the given query parameters will replace those of the existing query string. .. versionadded:: 1.4 .. seealso:: :attr:`_engine.URL.query` :meth:`_engine.URL.difference_update_query` :meth:`_engine.URL.set` """ # noqa: E501 existing_query = self.query new_keys: Dict[str, Union[str, List[str]]] = {} for key, value in key_value_pairs: if key in new_keys: new_keys[key] = util.to_list(new_keys[key]) cast("List[str]", new_keys[key]).append(cast(str, value)) else: new_keys[key] = ( list(value) if isinstance(value, (list, tuple)) else value ) new_query: Mapping[str, Union[str, Sequence[str]]] if append: new_query = {} for k in new_keys: if k in existing_query: new_query[k] = tuple( util.to_list(existing_query[k]) + util.to_list(new_keys[k]) ) else: new_query[k] = new_keys[k] new_query.update( { k: existing_query[k] for k in set(existing_query).difference(new_keys) } ) else: new_query = self.query.union( { k: tuple(v) if isinstance(v, list) else v for k, v in new_keys.items() } ) return self.set(query=new_query) def update_query_dict( self, query_parameters: Mapping[str, Union[str, List[str]]], append: bool = False, ) -> URL: """Return a new :class:`_engine.URL` object with the :attr:`_engine.URL.query` parameter dictionary updated by the given dictionary. The dictionary typically contains string keys and string values. In order to represent a query parameter that is expressed multiple times, pass a sequence of string values. E.g.:: >>> from sqlalchemy.engine import make_url >>> url = make_url("postgresql+psycopg2://user:pass@host/dbname") >>> url = url.update_query_dict( ... {"alt_host": ["host1", "host2"], "ssl_cipher": "/path/to/crt"} ... ) >>> str(url) 'postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt' :param query_parameters: A dictionary with string keys and values that are either strings, or sequences of strings. :param append: if True, parameters in the existing query string will not be removed; new parameters will be in addition to those present. If left at its default of False, keys present in the given query parameters will replace those of the existing query string. .. versionadded:: 1.4 .. seealso:: :attr:`_engine.URL.query` :meth:`_engine.URL.update_query_string` :meth:`_engine.URL.update_query_pairs` :meth:`_engine.URL.difference_update_query` :meth:`_engine.URL.set` """ # noqa: E501 return self.update_query_pairs(query_parameters.items(), append=append) def difference_update_query(self, names: Iterable[str]) -> URL: """ Remove the given names from the :attr:`_engine.URL.query` dictionary, returning the new :class:`_engine.URL`. E.g.:: url = url.difference_update_query(["foo", "bar"]) Equivalent to using :meth:`_engine.URL.set` as follows:: url = url.set( query={ key: url.query[key] for key in set(url.query).difference(["foo", "bar"]) } ) .. versionadded:: 1.4 .. seealso:: :attr:`_engine.URL.query` :meth:`_engine.URL.update_query_dict` :meth:`_engine.URL.set` """ if not set(names).intersection(self.query): return self return URL( self.drivername, self.username, self.password, self.host, self.port, self.database, util.immutabledict( { key: self.query[key] for key in set(self.query).difference(names) } ), ) @property def normalized_query(self) -> Mapping[str, Sequence[str]]: """Return the :attr:`_engine.URL.query` dictionary with values normalized into sequences. As the :attr:`_engine.URL.query` dictionary may contain either string values or sequences of string values to differentiate between parameters that are specified multiple times in the query string, code that needs to handle multiple parameters generically will wish to use this attribute so that all parameters present are presented as sequences. Inspiration is from Python's ``urllib.parse.parse_qs`` function. E.g.:: >>> from sqlalchemy.engine import make_url >>> url = make_url( ... "postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt" ... ) >>> url.query immutabledict({'alt_host': ('host1', 'host2'), 'ssl_cipher': '/path/to/crt'}) >>> url.normalized_query immutabledict({'alt_host': ('host1', 'host2'), 'ssl_cipher': ('/path/to/crt',)}) """ # noqa: E501 return util.immutabledict( { k: (v,) if not isinstance(v, tuple) else v for k, v in self.query.items() } ) @util.deprecated( "1.4", "The :meth:`_engine.URL.__to_string__ method is deprecated and will " "be removed in a future release. Please use the " ":meth:`_engine.URL.render_as_string` method.", ) def __to_string__(self, hide_password: bool = True) -> str: """Render this :class:`_engine.URL` object as a string. :param hide_password: Defaults to True. The password is not shown in the string unless this is set to False. """ return self.render_as_string(hide_password=hide_password) def render_as_string(self, hide_password: bool = True) -> str: """Render this :class:`_engine.URL` object as a string. This method is used when the ``__str__()`` or ``__repr__()`` methods are used. The method directly includes additional options. :param hide_password: Defaults to True. The password is not shown in the string unless this is set to False. """ s = self.drivername + "://" if self.username is not None: s += quote(self.username, safe=" +") if self.password is not None: s += ":" + ( "***" if hide_password else quote(str(self.password), safe=" +") ) s += "@" if self.host is not None: if ":" in self.host: s += f"[{self.host}]" else: s += self.host if self.port is not None: s += ":" + str(self.port) if self.database is not None: s += "/" + self.database if self.query: keys = list(self.query) keys.sort() s += "?" + "&".join( f"{quote_plus(k)}={quote_plus(element)}" for k in keys for element in util.to_list(self.query[k]) ) return s def __repr__(self) -> str: return self.render_as_string() def __copy__(self) -> URL: return self.__class__.create( self.drivername, self.username, self.password, self.host, self.port, self.database, # note this is an immutabledict of str-> str / tuple of str, # also fully immutable. does not require deepcopy self.query, ) def __deepcopy__(self, memo: Any) -> URL: return self.__copy__() def __hash__(self) -> int: return hash(str(self)) def __eq__(self, other: Any) -> bool: return ( isinstance(other, URL) and self.drivername == other.drivername and self.username == other.username and self.password == other.password and self.host == other.host and self.database == other.database and self.query == other.query and self.port == other.port ) def __ne__(self, other: Any) -> bool: return not self == other def get_backend_name(self) -> str: """Return the backend name. This is the name that corresponds to the database backend in use, and is the portion of the :attr:`_engine.URL.drivername` that is to the left of the plus sign. """ if "+" not in self.drivername: return self.drivername else: return self.drivername.split("+")[0] def get_driver_name(self) -> str: """Return the backend name. This is the name that corresponds to the DBAPI driver in use, and is the portion of the :attr:`_engine.URL.drivername` that is to the right of the plus sign. If the :attr:`_engine.URL.drivername` does not include a plus sign, then the default :class:`_engine.Dialect` for this :class:`_engine.URL` is imported in order to get the driver name. """ if "+" not in self.drivername: return self.get_dialect().driver else: return self.drivername.split("+")[1] def _instantiate_plugins( self, kwargs: Mapping[str, Any] ) -> Tuple[URL, List[Any], Dict[str, Any]]: plugin_names = util.to_list(self.query.get("plugin", ())) plugin_names += kwargs.get("plugins", []) kwargs = dict(kwargs) loaded_plugins = [ plugins.load(plugin_name)(self, kwargs) for plugin_name in plugin_names ] u = self.difference_update_query(["plugin", "plugins"]) for plugin in loaded_plugins: new_u = plugin.update_url(u) if new_u is not None: u = new_u kwargs.pop("plugins", None) return u, loaded_plugins, kwargs def _get_entrypoint(self) -> Type[Dialect]: """Return the "entry point" dialect class. This is normally the dialect itself except in the case when the returned class implements the get_dialect_cls() method. """ if "+" not in self.drivername: name = self.drivername else: name = self.drivername.replace("+", ".") cls = registry.load(name) # check for legacy dialects that # would return a module with 'dialect' as the # actual class if ( hasattr(cls, "dialect") and isinstance(cls.dialect, type) and issubclass(cls.dialect, Dialect) ): return cls.dialect else: return cast("Type[Dialect]", cls) def get_dialect(self, _is_async: bool = False) -> Type[Dialect]: """Return the SQLAlchemy :class:`_engine.Dialect` class corresponding to this URL's driver name. """ entrypoint = self._get_entrypoint() if _is_async: dialect_cls = entrypoint.get_async_dialect_cls(self) else: dialect_cls = entrypoint.get_dialect_cls(self) return dialect_cls def translate_connect_args( self, names: Optional[List[str]] = None, **kw: Any ) -> Dict[str, Any]: r"""Translate url attributes into a dictionary of connection arguments. Returns attributes of this url (`host`, `database`, `username`, `password`, `port`) as a plain dictionary. The attribute names are used as the keys by default. Unset or false attributes are omitted from the final dictionary. :param \**kw: Optional, alternate key names for url attributes. :param names: Deprecated. Same purpose as the keyword-based alternate names, but correlates the name to the original positionally. """ if names is not None: util.warn_deprecated( "The `URL.translate_connect_args.name`s parameter is " "deprecated. Please pass the " "alternate names as kw arguments.", "1.4", ) translated = {} attribute_names = ["host", "database", "username", "password", "port"] for sname in attribute_names: if names: name = names.pop(0) elif sname in kw: name = kw[sname] else: name = sname if name is not None and getattr(self, sname, False): if sname == "password": translated[name] = str(getattr(self, sname)) else: translated[name] = getattr(self, sname) return translated def make_url(name_or_url: Union[str, URL]) -> URL: """Given a string, produce a new URL instance. The format of the URL generally follows `RFC-1738 <https://www.ietf.org/rfc/rfc1738.txt>`_, with some exceptions, including that underscores, and not dashes or periods, are accepted within the "scheme" portion. If a :class:`.URL` object is passed, it is returned as is. .. seealso:: :ref:`database_urls` """ if isinstance(name_or_url, str): return _parse_url(name_or_url) elif not isinstance(name_or_url, URL) and not hasattr( name_or_url, "_sqla_is_testing_if_this_is_a_mock_object" ): raise exc.ArgumentError( f"Expected string or URL object, got {name_or_url!r}" ) else: return name_or_url def _parse_url(name: str) -> URL: pattern = re.compile( r""" (?P<name>[\w\+]+):// (?: (?P<username>[^:/]*) (?::(?P<password>[^@]*))? @)? (?: (?: \[(?P<ipv6host>[^/\?]+)\] | (?P<ipv4host>[^/:\?]+) )? (?::(?P<port>[^/\?]*))? )? (?:/(?P<database>[^\?]*))? (?:\?(?P<query>.*))? """, re.X, ) m = pattern.match(name) if m is not None: components = m.groupdict() query: Optional[Dict[str, Union[str, List[str]]]] if components["query"] is not None: query = {} for key, value in parse_qsl(components["query"]): if key in query: query[key] = util.to_list(query[key]) cast("List[str]", query[key]).append(value) else: query[key] = value else: query = None components["query"] = query if components["username"] is not None: components["username"] = unquote(components["username"]) if components["password"] is not None: components["password"] = unquote(components["password"]) ipv4host = components.pop("ipv4host") ipv6host = components.pop("ipv6host") components["host"] = ipv4host or ipv6host name = components.pop("name") if components["port"]: components["port"] = int(components["port"]) return URL.create(name, **components) # type: ignore else: raise exc.ArgumentError( "Could not parse SQLAlchemy URL from given URL string" ) sqlalchemy/engine/_py_util.py 0000755 00000004664 15125143220 0012361 0 ustar 00 # engine/_py_util.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php from __future__ import annotations import typing from typing import Any from typing import Mapping from typing import Optional from typing import Tuple from .. import exc if typing.TYPE_CHECKING: from .interfaces import _CoreAnyExecuteParams from .interfaces import _CoreMultiExecuteParams from .interfaces import _DBAPIAnyExecuteParams from .interfaces import _DBAPIMultiExecuteParams _no_tuple: Tuple[Any, ...] = () def _distill_params_20( params: Optional[_CoreAnyExecuteParams], ) -> _CoreMultiExecuteParams: if params is None: return _no_tuple # Assume list is more likely than tuple elif isinstance(params, list) or isinstance(params, tuple): # collections_abc.MutableSequence): # avoid abc.__instancecheck__ if params and not isinstance(params[0], (tuple, Mapping)): raise exc.ArgumentError( "List argument must consist only of tuples or dictionaries" ) return params elif isinstance(params, dict) or isinstance( # only do immutabledict or abc.__instancecheck__ for Mapping after # we've checked for plain dictionaries and would otherwise raise params, Mapping, ): return [params] else: raise exc.ArgumentError("mapping or list expected for parameters") def _distill_raw_params( params: Optional[_DBAPIAnyExecuteParams], ) -> _DBAPIMultiExecuteParams: if params is None: return _no_tuple elif isinstance(params, list): # collections_abc.MutableSequence): # avoid abc.__instancecheck__ if params and not isinstance(params[0], (tuple, Mapping)): raise exc.ArgumentError( "List argument must consist only of tuples or dictionaries" ) return params elif isinstance(params, (tuple, dict)) or isinstance( # only do abc.__instancecheck__ for Mapping after we've checked # for plain dictionaries and would otherwise raise params, Mapping, ): # cast("Union[List[Mapping[str, Any]], Tuple[Any, ...]]", [params]) return [params] # type: ignore else: raise exc.ArgumentError("mapping or sequence expected for parameters") sqlalchemy/engine/_py_processors.py 0000755 00000007240 15125143220 0013577 0 ustar 00 # engine/_py_processors.py # Copyright (C) 2010-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # Copyright (C) 2010 Gaetan de Menten gdementen@gmail.com # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """defines generic type conversion functions, as used in bind and result processors. They all share one common characteristic: None is passed through unchanged. """ from __future__ import annotations import datetime from datetime import date as date_cls from datetime import datetime as datetime_cls from datetime import time as time_cls from decimal import Decimal import typing from typing import Any from typing import Callable from typing import Optional from typing import Type from typing import TypeVar from typing import Union _DT = TypeVar( "_DT", bound=Union[datetime.datetime, datetime.time, datetime.date] ) def str_to_datetime_processor_factory( regexp: typing.Pattern[str], type_: Callable[..., _DT] ) -> Callable[[Optional[str]], Optional[_DT]]: rmatch = regexp.match # Even on python2.6 datetime.strptime is both slower than this code # and it does not support microseconds. has_named_groups = bool(regexp.groupindex) def process(value: Optional[str]) -> Optional[_DT]: if value is None: return None else: try: m = rmatch(value) except TypeError as err: raise ValueError( "Couldn't parse %s string '%r' " "- value is not a string." % (type_.__name__, value) ) from err if m is None: raise ValueError( "Couldn't parse %s string: " "'%s'" % (type_.__name__, value) ) if has_named_groups: groups = m.groupdict(0) return type_( **dict( list( zip( iter(groups.keys()), list(map(int, iter(groups.values()))), ) ) ) ) else: return type_(*list(map(int, m.groups(0)))) return process def to_decimal_processor_factory( target_class: Type[Decimal], scale: int ) -> Callable[[Optional[float]], Optional[Decimal]]: fstring = "%%.%df" % scale def process(value: Optional[float]) -> Optional[Decimal]: if value is None: return None else: return target_class(fstring % value) return process def to_float(value: Optional[Union[int, float]]) -> Optional[float]: if value is None: return None else: return float(value) def to_str(value: Optional[Any]) -> Optional[str]: if value is None: return None else: return str(value) def int_to_boolean(value: Optional[int]) -> Optional[bool]: if value is None: return None else: return bool(value) def str_to_datetime(value: Optional[str]) -> Optional[datetime.datetime]: if value is not None: dt_value = datetime_cls.fromisoformat(value) else: dt_value = None return dt_value def str_to_time(value: Optional[str]) -> Optional[datetime.time]: if value is not None: dt_value = time_cls.fromisoformat(value) else: dt_value = None return dt_value def str_to_date(value: Optional[str]) -> Optional[datetime.date]: if value is not None: dt_value = date_cls.fromisoformat(value) else: dt_value = None return dt_value sqlalchemy/engine/processors.py 0000755 00000004513 15125143220 0012730 0 ustar 00 # engine/processors.py # Copyright (C) 2010-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # Copyright (C) 2010 Gaetan de Menten gdementen@gmail.com # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """defines generic type conversion functions, as used in bind and result processors. They all share one common characteristic: None is passed through unchanged. """ from __future__ import annotations import typing from ._py_processors import str_to_datetime_processor_factory # noqa from ..util._has_cy import HAS_CYEXTENSION if typing.TYPE_CHECKING or not HAS_CYEXTENSION: from ._py_processors import int_to_boolean as int_to_boolean from ._py_processors import str_to_date as str_to_date from ._py_processors import str_to_datetime as str_to_datetime from ._py_processors import str_to_time as str_to_time from ._py_processors import ( to_decimal_processor_factory as to_decimal_processor_factory, ) from ._py_processors import to_float as to_float from ._py_processors import to_str as to_str else: from sqlalchemy.cyextension.processors import ( DecimalResultProcessor, ) from sqlalchemy.cyextension.processors import ( # noqa: F401 int_to_boolean as int_to_boolean, ) from sqlalchemy.cyextension.processors import ( # noqa: F401,E501 str_to_date as str_to_date, ) from sqlalchemy.cyextension.processors import ( # noqa: F401 str_to_datetime as str_to_datetime, ) from sqlalchemy.cyextension.processors import ( # noqa: F401,E501 str_to_time as str_to_time, ) from sqlalchemy.cyextension.processors import ( # noqa: F401,E501 to_float as to_float, ) from sqlalchemy.cyextension.processors import ( # noqa: F401,E501 to_str as to_str, ) def to_decimal_processor_factory(target_class, scale): # Note that the scale argument is not taken into account for integer # values in the C implementation while it is in the Python one. # For example, the Python implementation might return # Decimal('5.00000') whereas the C implementation will # return Decimal('5'). These are equivalent of course. return DecimalResultProcessor(target_class, "%%.%df" % scale).process sqlalchemy/engine/cursor.py 0000755 00000225311 15125143220 0012044 0 ustar 00 # engine/cursor.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: allow-untyped-defs, allow-untyped-calls """Define cursor-specific result set constructs including :class:`.CursorResult`.""" from __future__ import annotations import collections import functools import operator import typing from typing import Any from typing import cast from typing import ClassVar from typing import Dict from typing import Iterable from typing import Iterator from typing import List from typing import Mapping from typing import NoReturn from typing import Optional from typing import Sequence from typing import Tuple from typing import TYPE_CHECKING from typing import TypeVar from typing import Union from .result import IteratorResult from .result import MergedResult from .result import Result from .result import ResultMetaData from .result import SimpleResultMetaData from .result import tuplegetter from .row import Row from .. import exc from .. import util from ..sql import elements from ..sql import sqltypes from ..sql import util as sql_util from ..sql.base import _generative from ..sql.compiler import ResultColumnsEntry from ..sql.compiler import RM_NAME from ..sql.compiler import RM_OBJECTS from ..sql.compiler import RM_RENDERED_NAME from ..sql.compiler import RM_TYPE from ..sql.type_api import TypeEngine from ..util import compat from ..util.typing import Literal from ..util.typing import Self if typing.TYPE_CHECKING: from .base import Connection from .default import DefaultExecutionContext from .interfaces import _DBAPICursorDescription from .interfaces import DBAPICursor from .interfaces import Dialect from .interfaces import ExecutionContext from .result import _KeyIndexType from .result import _KeyMapRecType from .result import _KeyMapType from .result import _KeyType from .result import _ProcessorsType from .result import _TupleGetterType from ..sql.type_api import _ResultProcessorType _T = TypeVar("_T", bound=Any) # metadata entry tuple indexes. # using raw tuple is faster than namedtuple. # these match up to the positions in # _CursorKeyMapRecType MD_INDEX: Literal[0] = 0 """integer index in cursor.description """ MD_RESULT_MAP_INDEX: Literal[1] = 1 """integer index in compiled._result_columns""" MD_OBJECTS: Literal[2] = 2 """other string keys and ColumnElement obj that can match. This comes from compiler.RM_OBJECTS / compiler.ResultColumnsEntry.objects """ MD_LOOKUP_KEY: Literal[3] = 3 """string key we usually expect for key-based lookup this comes from compiler.RM_NAME / compiler.ResultColumnsEntry.name """ MD_RENDERED_NAME: Literal[4] = 4 """name that is usually in cursor.description this comes from compiler.RENDERED_NAME / compiler.ResultColumnsEntry.keyname """ MD_PROCESSOR: Literal[5] = 5 """callable to process a result value into a row""" MD_UNTRANSLATED: Literal[6] = 6 """raw name from cursor.description""" _CursorKeyMapRecType = Tuple[ Optional[int], # MD_INDEX, None means the record is ambiguously named int, # MD_RESULT_MAP_INDEX List[Any], # MD_OBJECTS str, # MD_LOOKUP_KEY str, # MD_RENDERED_NAME Optional["_ResultProcessorType[Any]"], # MD_PROCESSOR Optional[str], # MD_UNTRANSLATED ] _CursorKeyMapType = Mapping["_KeyType", _CursorKeyMapRecType] # same as _CursorKeyMapRecType except the MD_INDEX value is definitely # not None _NonAmbigCursorKeyMapRecType = Tuple[ int, int, List[Any], str, str, Optional["_ResultProcessorType[Any]"], str, ] class CursorResultMetaData(ResultMetaData): """Result metadata for DBAPI cursors.""" __slots__ = ( "_keymap", "_processors", "_keys", "_keymap_by_result_column_idx", "_tuplefilter", "_translated_indexes", "_safe_for_cache", "_unpickled", "_key_to_index", # don't need _unique_filters support here for now. Can be added # if a need arises. ) _keymap: _CursorKeyMapType _processors: _ProcessorsType _keymap_by_result_column_idx: Optional[Dict[int, _KeyMapRecType]] _unpickled: bool _safe_for_cache: bool _translated_indexes: Optional[List[int]] returns_rows: ClassVar[bool] = True def _has_key(self, key: Any) -> bool: return key in self._keymap def _for_freeze(self) -> ResultMetaData: return SimpleResultMetaData( self._keys, extra=[self._keymap[key][MD_OBJECTS] for key in self._keys], ) def _make_new_metadata( self, *, unpickled: bool, processors: _ProcessorsType, keys: Sequence[str], keymap: _KeyMapType, tuplefilter: Optional[_TupleGetterType], translated_indexes: Optional[List[int]], safe_for_cache: bool, keymap_by_result_column_idx: Any, ) -> CursorResultMetaData: new_obj = self.__class__.__new__(self.__class__) new_obj._unpickled = unpickled new_obj._processors = processors new_obj._keys = keys new_obj._keymap = keymap new_obj._tuplefilter = tuplefilter new_obj._translated_indexes = translated_indexes new_obj._safe_for_cache = safe_for_cache new_obj._keymap_by_result_column_idx = keymap_by_result_column_idx new_obj._key_to_index = self._make_key_to_index(keymap, MD_INDEX) return new_obj def _remove_processors(self) -> CursorResultMetaData: assert not self._tuplefilter return self._make_new_metadata( unpickled=self._unpickled, processors=[None] * len(self._processors), tuplefilter=None, translated_indexes=None, keymap={ key: value[0:5] + (None,) + value[6:] for key, value in self._keymap.items() }, keys=self._keys, safe_for_cache=self._safe_for_cache, keymap_by_result_column_idx=self._keymap_by_result_column_idx, ) def _splice_horizontally( self, other: CursorResultMetaData ) -> CursorResultMetaData: assert not self._tuplefilter keymap = dict(self._keymap) offset = len(self._keys) keymap.update( { key: ( # int index should be None for ambiguous key ( value[0] + offset if value[0] is not None and key not in keymap else None ), value[1] + offset, *value[2:], ) for key, value in other._keymap.items() } ) return self._make_new_metadata( unpickled=self._unpickled, processors=self._processors + other._processors, # type: ignore tuplefilter=None, translated_indexes=None, keys=self._keys + other._keys, # type: ignore keymap=keymap, safe_for_cache=self._safe_for_cache, keymap_by_result_column_idx={ metadata_entry[MD_RESULT_MAP_INDEX]: metadata_entry for metadata_entry in keymap.values() }, ) def _reduce(self, keys: Sequence[_KeyIndexType]) -> ResultMetaData: recs = list(self._metadata_for_keys(keys)) indexes = [rec[MD_INDEX] for rec in recs] new_keys: List[str] = [rec[MD_LOOKUP_KEY] for rec in recs] if self._translated_indexes: indexes = [self._translated_indexes[idx] for idx in indexes] tup = tuplegetter(*indexes) new_recs = [(index,) + rec[1:] for index, rec in enumerate(recs)] keymap = {rec[MD_LOOKUP_KEY]: rec for rec in new_recs} # TODO: need unit test for: # result = connection.execute("raw sql, no columns").scalars() # without the "or ()" it's failing because MD_OBJECTS is None keymap.update( (e, new_rec) for new_rec in new_recs for e in new_rec[MD_OBJECTS] or () ) return self._make_new_metadata( unpickled=self._unpickled, processors=self._processors, keys=new_keys, tuplefilter=tup, translated_indexes=indexes, keymap=keymap, # type: ignore[arg-type] safe_for_cache=self._safe_for_cache, keymap_by_result_column_idx=self._keymap_by_result_column_idx, ) def _adapt_to_context(self, context: ExecutionContext) -> ResultMetaData: """When using a cached Compiled construct that has a _result_map, for a new statement that used the cached Compiled, we need to ensure the keymap has the Column objects from our new statement as keys. So here we rewrite keymap with new entries for the new columns as matched to those of the cached statement. """ if not context.compiled or not context.compiled._result_columns: return self compiled_statement = context.compiled.statement invoked_statement = context.invoked_statement if TYPE_CHECKING: assert isinstance(invoked_statement, elements.ClauseElement) if compiled_statement is invoked_statement: return self assert invoked_statement is not None # this is the most common path for Core statements when # caching is used. In ORM use, this codepath is not really used # as the _result_disable_adapt_to_context execution option is # set by the ORM. # make a copy and add the columns from the invoked statement # to the result map. keymap_by_position = self._keymap_by_result_column_idx if keymap_by_position is None: # first retrival from cache, this map will not be set up yet, # initialize lazily keymap_by_position = self._keymap_by_result_column_idx = { metadata_entry[MD_RESULT_MAP_INDEX]: metadata_entry for metadata_entry in self._keymap.values() } assert not self._tuplefilter return self._make_new_metadata( keymap=compat.dict_union( self._keymap, { new: keymap_by_position[idx] for idx, new in enumerate( invoked_statement._all_selected_columns ) if idx in keymap_by_position }, ), unpickled=self._unpickled, processors=self._processors, tuplefilter=None, translated_indexes=None, keys=self._keys, safe_for_cache=self._safe_for_cache, keymap_by_result_column_idx=self._keymap_by_result_column_idx, ) def __init__( self, parent: CursorResult[Any], cursor_description: _DBAPICursorDescription, ): context = parent.context self._tuplefilter = None self._translated_indexes = None self._safe_for_cache = self._unpickled = False if context.result_column_struct: ( result_columns, cols_are_ordered, textual_ordered, ad_hoc_textual, loose_column_name_matching, ) = context.result_column_struct num_ctx_cols = len(result_columns) else: result_columns = cols_are_ordered = ( # type: ignore num_ctx_cols ) = ad_hoc_textual = loose_column_name_matching = ( textual_ordered ) = False # merge cursor.description with the column info # present in the compiled structure, if any raw = self._merge_cursor_description( context, cursor_description, result_columns, num_ctx_cols, cols_are_ordered, textual_ordered, ad_hoc_textual, loose_column_name_matching, ) # processors in key order which are used when building up # a row self._processors = [ metadata_entry[MD_PROCESSOR] for metadata_entry in raw ] # this is used when using this ResultMetaData in a Core-only cache # retrieval context. it's initialized on first cache retrieval # when the _result_disable_adapt_to_context execution option # (which the ORM generally sets) is not set. self._keymap_by_result_column_idx = None # for compiled SQL constructs, copy additional lookup keys into # the key lookup map, such as Column objects, labels, # column keys and other names if num_ctx_cols: # keymap by primary string... by_key = { metadata_entry[MD_LOOKUP_KEY]: metadata_entry for metadata_entry in raw } if len(by_key) != num_ctx_cols: # if by-primary-string dictionary smaller than # number of columns, assume we have dupes; (this check # is also in place if string dictionary is bigger, as # can occur when '*' was used as one of the compiled columns, # which may or may not be suggestive of dupes), rewrite # dupe records with "None" for index which results in # ambiguous column exception when accessed. # # this is considered to be the less common case as it is not # common to have dupe column keys in a SELECT statement. # # new in 1.4: get the complete set of all possible keys, # strings, objects, whatever, that are dupes across two # different records, first. index_by_key: Dict[Any, Any] = {} dupes = set() for metadata_entry in raw: for key in (metadata_entry[MD_RENDERED_NAME],) + ( metadata_entry[MD_OBJECTS] or () ): idx = metadata_entry[MD_INDEX] # if this key has been associated with more than one # positional index, it's a dupe if index_by_key.setdefault(key, idx) != idx: dupes.add(key) # then put everything we have into the keymap excluding only # those keys that are dupes. self._keymap = { obj_elem: metadata_entry for metadata_entry in raw if metadata_entry[MD_OBJECTS] for obj_elem in metadata_entry[MD_OBJECTS] if obj_elem not in dupes } # then for the dupe keys, put the "ambiguous column" # record into by_key. by_key.update( { key: (None, None, [], key, key, None, None) for key in dupes } ) else: # no dupes - copy secondary elements from compiled # columns into self._keymap. this is the most common # codepath for Core / ORM statement executions before the # result metadata is cached self._keymap = { obj_elem: metadata_entry for metadata_entry in raw if metadata_entry[MD_OBJECTS] for obj_elem in metadata_entry[MD_OBJECTS] } # update keymap with primary string names taking # precedence self._keymap.update(by_key) else: # no compiled objects to map, just create keymap by primary string self._keymap = { metadata_entry[MD_LOOKUP_KEY]: metadata_entry for metadata_entry in raw } # update keymap with "translated" names. In SQLAlchemy this is a # sqlite only thing, and in fact impacting only extremely old SQLite # versions unlikely to be present in modern Python versions. # however, the pyhive third party dialect is # also using this hook, which means others still might use it as well. # I dislike having this awkward hook here but as long as we need # to use names in cursor.description in some cases we need to have # some hook to accomplish this. if not num_ctx_cols and context._translate_colname: self._keymap.update( { metadata_entry[MD_UNTRANSLATED]: self._keymap[ metadata_entry[MD_LOOKUP_KEY] ] for metadata_entry in raw if metadata_entry[MD_UNTRANSLATED] } ) self._key_to_index = self._make_key_to_index(self._keymap, MD_INDEX) def _merge_cursor_description( self, context, cursor_description, result_columns, num_ctx_cols, cols_are_ordered, textual_ordered, ad_hoc_textual, loose_column_name_matching, ): """Merge a cursor.description with compiled result column information. There are at least four separate strategies used here, selected depending on the type of SQL construct used to start with. The most common case is that of the compiled SQL expression construct, which generated the column names present in the raw SQL string and which has the identical number of columns as were reported by cursor.description. In this case, we assume a 1-1 positional mapping between the entries in cursor.description and the compiled object. This is also the most performant case as we disregard extracting / decoding the column names present in cursor.description since we already have the desired name we generated in the compiled SQL construct. The next common case is that of the completely raw string SQL, such as passed to connection.execute(). In this case we have no compiled construct to work with, so we extract and decode the names from cursor.description and index those as the primary result row target keys. The remaining fairly common case is that of the textual SQL that includes at least partial column information; this is when we use a :class:`_expression.TextualSelect` construct. This construct may have unordered or ordered column information. In the ordered case, we merge the cursor.description and the compiled construct's information positionally, and warn if there are additional description names present, however we still decode the names in cursor.description as we don't have a guarantee that the names in the columns match on these. In the unordered case, we match names in cursor.description to that of the compiled construct based on name matching. In both of these cases, the cursor.description names and the column expression objects and names are indexed as result row target keys. The final case is much less common, where we have a compiled non-textual SQL expression construct, but the number of columns in cursor.description doesn't match what's in the compiled construct. We make the guess here that there might be textual column expressions in the compiled construct that themselves include a comma in them causing them to split. We do the same name-matching as with textual non-ordered columns. The name-matched system of merging is the same as that used by SQLAlchemy for all cases up through the 0.9 series. Positional matching for compiled SQL expressions was introduced in 1.0 as a major performance feature, and positional matching for textual :class:`_expression.TextualSelect` objects in 1.1. As name matching is no longer a common case, it was acceptable to factor it into smaller generator- oriented methods that are easier to understand, but incur slightly more performance overhead. """ if ( num_ctx_cols and cols_are_ordered and not textual_ordered and num_ctx_cols == len(cursor_description) ): self._keys = [elem[0] for elem in result_columns] # pure positional 1-1 case; doesn't need to read # the names from cursor.description # most common case for Core and ORM # this metadata is safe to cache because we are guaranteed # to have the columns in the same order for new executions self._safe_for_cache = True return [ ( idx, idx, rmap_entry[RM_OBJECTS], rmap_entry[RM_NAME], rmap_entry[RM_RENDERED_NAME], context.get_result_processor( rmap_entry[RM_TYPE], rmap_entry[RM_RENDERED_NAME], cursor_description[idx][1], ), None, ) for idx, rmap_entry in enumerate(result_columns) ] else: # name-based or text-positional cases, where we need # to read cursor.description names if textual_ordered or ( ad_hoc_textual and len(cursor_description) == num_ctx_cols ): self._safe_for_cache = True # textual positional case raw_iterator = self._merge_textual_cols_by_position( context, cursor_description, result_columns ) elif num_ctx_cols: # compiled SQL with a mismatch of description cols # vs. compiled cols, or textual w/ unordered columns # the order of columns can change if the query is # against a "select *", so not safe to cache self._safe_for_cache = False raw_iterator = self._merge_cols_by_name( context, cursor_description, result_columns, loose_column_name_matching, ) else: # no compiled SQL, just a raw string, order of columns # can change for "select *" self._safe_for_cache = False raw_iterator = self._merge_cols_by_none( context, cursor_description ) return [ ( idx, ridx, obj, cursor_colname, cursor_colname, context.get_result_processor( mapped_type, cursor_colname, coltype ), untranslated, ) for ( idx, ridx, cursor_colname, mapped_type, coltype, obj, untranslated, ) in raw_iterator ] def _colnames_from_description(self, context, cursor_description): """Extract column names and data types from a cursor.description. Applies unicode decoding, column translation, "normalization", and case sensitivity rules to the names based on the dialect. """ dialect = context.dialect translate_colname = context._translate_colname normalize_name = ( dialect.normalize_name if dialect.requires_name_normalize else None ) untranslated = None self._keys = [] for idx, rec in enumerate(cursor_description): colname = rec[0] coltype = rec[1] if translate_colname: colname, untranslated = translate_colname(colname) if normalize_name: colname = normalize_name(colname) self._keys.append(colname) yield idx, colname, untranslated, coltype def _merge_textual_cols_by_position( self, context, cursor_description, result_columns ): num_ctx_cols = len(result_columns) if num_ctx_cols > len(cursor_description): util.warn( "Number of columns in textual SQL (%d) is " "smaller than number of columns requested (%d)" % (num_ctx_cols, len(cursor_description)) ) seen = set() for ( idx, colname, untranslated, coltype, ) in self._colnames_from_description(context, cursor_description): if idx < num_ctx_cols: ctx_rec = result_columns[idx] obj = ctx_rec[RM_OBJECTS] ridx = idx mapped_type = ctx_rec[RM_TYPE] if obj[0] in seen: raise exc.InvalidRequestError( "Duplicate column expression requested " "in textual SQL: %r" % obj[0] ) seen.add(obj[0]) else: mapped_type = sqltypes.NULLTYPE obj = None ridx = None yield idx, ridx, colname, mapped_type, coltype, obj, untranslated def _merge_cols_by_name( self, context, cursor_description, result_columns, loose_column_name_matching, ): match_map = self._create_description_match_map( result_columns, loose_column_name_matching ) mapped_type: TypeEngine[Any] for ( idx, colname, untranslated, coltype, ) in self._colnames_from_description(context, cursor_description): try: ctx_rec = match_map[colname] except KeyError: mapped_type = sqltypes.NULLTYPE obj = None result_columns_idx = None else: obj = ctx_rec[1] mapped_type = ctx_rec[2] result_columns_idx = ctx_rec[3] yield ( idx, result_columns_idx, colname, mapped_type, coltype, obj, untranslated, ) @classmethod def _create_description_match_map( cls, result_columns: List[ResultColumnsEntry], loose_column_name_matching: bool = False, ) -> Dict[ Union[str, object], Tuple[str, Tuple[Any, ...], TypeEngine[Any], int] ]: """when matching cursor.description to a set of names that are present in a Compiled object, as is the case with TextualSelect, get all the names we expect might match those in cursor.description. """ d: Dict[ Union[str, object], Tuple[str, Tuple[Any, ...], TypeEngine[Any], int], ] = {} for ridx, elem in enumerate(result_columns): key = elem[RM_RENDERED_NAME] if key in d: # conflicting keyname - just add the column-linked objects # to the existing record. if there is a duplicate column # name in the cursor description, this will allow all of those # objects to raise an ambiguous column error e_name, e_obj, e_type, e_ridx = d[key] d[key] = e_name, e_obj + elem[RM_OBJECTS], e_type, ridx else: d[key] = (elem[RM_NAME], elem[RM_OBJECTS], elem[RM_TYPE], ridx) if loose_column_name_matching: # when using a textual statement with an unordered set # of columns that line up, we are expecting the user # to be using label names in the SQL that match to the column # expressions. Enable more liberal matching for this case; # duplicate keys that are ambiguous will be fixed later. for r_key in elem[RM_OBJECTS]: d.setdefault( r_key, (elem[RM_NAME], elem[RM_OBJECTS], elem[RM_TYPE], ridx), ) return d def _merge_cols_by_none(self, context, cursor_description): for ( idx, colname, untranslated, coltype, ) in self._colnames_from_description(context, cursor_description): yield ( idx, None, colname, sqltypes.NULLTYPE, coltype, None, untranslated, ) if not TYPE_CHECKING: def _key_fallback( self, key: Any, err: Optional[Exception], raiseerr: bool = True ) -> Optional[NoReturn]: if raiseerr: if self._unpickled and isinstance(key, elements.ColumnElement): raise exc.NoSuchColumnError( "Row was unpickled; lookup by ColumnElement " "is unsupported" ) from err else: raise exc.NoSuchColumnError( "Could not locate column in row for column '%s'" % util.string_or_unprintable(key) ) from err else: return None def _raise_for_ambiguous_column_name(self, rec): raise exc.InvalidRequestError( "Ambiguous column name '%s' in " "result set column descriptions" % rec[MD_LOOKUP_KEY] ) def _index_for_key(self, key: Any, raiseerr: bool = True) -> Optional[int]: # TODO: can consider pre-loading ints and negative ints # into _keymap - also no coverage here if isinstance(key, int): key = self._keys[key] try: rec = self._keymap[key] except KeyError as ke: x = self._key_fallback(key, ke, raiseerr) assert x is None return None index = rec[0] if index is None: self._raise_for_ambiguous_column_name(rec) return index def _indexes_for_keys(self, keys): try: return [self._keymap[key][0] for key in keys] except KeyError as ke: # ensure it raises CursorResultMetaData._key_fallback(self, ke.args[0], ke) def _metadata_for_keys( self, keys: Sequence[Any] ) -> Iterator[_NonAmbigCursorKeyMapRecType]: for key in keys: if int in key.__class__.__mro__: key = self._keys[key] try: rec = self._keymap[key] except KeyError as ke: # ensure it raises CursorResultMetaData._key_fallback(self, ke.args[0], ke) index = rec[MD_INDEX] if index is None: self._raise_for_ambiguous_column_name(rec) yield cast(_NonAmbigCursorKeyMapRecType, rec) def __getstate__(self): # TODO: consider serializing this as SimpleResultMetaData return { "_keymap": { key: ( rec[MD_INDEX], rec[MD_RESULT_MAP_INDEX], [], key, rec[MD_RENDERED_NAME], None, None, ) for key, rec in self._keymap.items() if isinstance(key, (str, int)) }, "_keys": self._keys, "_translated_indexes": self._translated_indexes, } def __setstate__(self, state): self._processors = [None for _ in range(len(state["_keys"]))] self._keymap = state["_keymap"] self._keymap_by_result_column_idx = None self._key_to_index = self._make_key_to_index(self._keymap, MD_INDEX) self._keys = state["_keys"] self._unpickled = True if state["_translated_indexes"]: self._translated_indexes = cast( "List[int]", state["_translated_indexes"] ) self._tuplefilter = tuplegetter(*self._translated_indexes) else: self._translated_indexes = self._tuplefilter = None class ResultFetchStrategy: """Define a fetching strategy for a result object. .. versionadded:: 1.4 """ __slots__ = () alternate_cursor_description: Optional[_DBAPICursorDescription] = None def soft_close( self, result: CursorResult[Any], dbapi_cursor: Optional[DBAPICursor] ) -> None: raise NotImplementedError() def hard_close( self, result: CursorResult[Any], dbapi_cursor: Optional[DBAPICursor] ) -> None: raise NotImplementedError() def yield_per( self, result: CursorResult[Any], dbapi_cursor: Optional[DBAPICursor], num: int, ) -> None: return def fetchone( self, result: CursorResult[Any], dbapi_cursor: DBAPICursor, hard_close: bool = False, ) -> Any: raise NotImplementedError() def fetchmany( self, result: CursorResult[Any], dbapi_cursor: DBAPICursor, size: Optional[int] = None, ) -> Any: raise NotImplementedError() def fetchall( self, result: CursorResult[Any], dbapi_cursor: DBAPICursor, ) -> Any: raise NotImplementedError() def handle_exception( self, result: CursorResult[Any], dbapi_cursor: Optional[DBAPICursor], err: BaseException, ) -> NoReturn: raise err class NoCursorFetchStrategy(ResultFetchStrategy): """Cursor strategy for a result that has no open cursor. There are two varieties of this strategy, one for DQL and one for DML (and also DDL), each of which represent a result that had a cursor but no longer has one. """ __slots__ = () def soft_close(self, result, dbapi_cursor): pass def hard_close(self, result, dbapi_cursor): pass def fetchone(self, result, dbapi_cursor, hard_close=False): return self._non_result(result, None) def fetchmany(self, result, dbapi_cursor, size=None): return self._non_result(result, []) def fetchall(self, result, dbapi_cursor): return self._non_result(result, []) def _non_result(self, result, default, err=None): raise NotImplementedError() class NoCursorDQLFetchStrategy(NoCursorFetchStrategy): """Cursor strategy for a DQL result that has no open cursor. This is a result set that can return rows, i.e. for a SELECT, or for an INSERT, UPDATE, DELETE that includes RETURNING. However it is in the state where the cursor is closed and no rows remain available. The owning result object may or may not be "hard closed", which determines if the fetch methods send empty results or raise for closed result. """ __slots__ = () def _non_result(self, result, default, err=None): if result.closed: raise exc.ResourceClosedError( "This result object is closed." ) from err else: return default _NO_CURSOR_DQL = NoCursorDQLFetchStrategy() class NoCursorDMLFetchStrategy(NoCursorFetchStrategy): """Cursor strategy for a DML result that has no open cursor. This is a result set that does not return rows, i.e. for an INSERT, UPDATE, DELETE that does not include RETURNING. """ __slots__ = () def _non_result(self, result, default, err=None): # we only expect to have a _NoResultMetaData() here right now. assert not result._metadata.returns_rows result._metadata._we_dont_return_rows(err) _NO_CURSOR_DML = NoCursorDMLFetchStrategy() class CursorFetchStrategy(ResultFetchStrategy): """Call fetch methods from a DBAPI cursor. Alternate versions of this class may instead buffer the rows from cursors or not use cursors at all. """ __slots__ = () def soft_close( self, result: CursorResult[Any], dbapi_cursor: Optional[DBAPICursor] ) -> None: result.cursor_strategy = _NO_CURSOR_DQL def hard_close( self, result: CursorResult[Any], dbapi_cursor: Optional[DBAPICursor] ) -> None: result.cursor_strategy = _NO_CURSOR_DQL def handle_exception( self, result: CursorResult[Any], dbapi_cursor: Optional[DBAPICursor], err: BaseException, ) -> NoReturn: result.connection._handle_dbapi_exception( err, None, None, dbapi_cursor, result.context ) def yield_per( self, result: CursorResult[Any], dbapi_cursor: Optional[DBAPICursor], num: int, ) -> None: result.cursor_strategy = BufferedRowCursorFetchStrategy( dbapi_cursor, {"max_row_buffer": num}, initial_buffer=collections.deque(), growth_factor=0, ) def fetchone( self, result: CursorResult[Any], dbapi_cursor: DBAPICursor, hard_close: bool = False, ) -> Any: try: row = dbapi_cursor.fetchone() if row is None: result._soft_close(hard=hard_close) return row except BaseException as e: self.handle_exception(result, dbapi_cursor, e) def fetchmany( self, result: CursorResult[Any], dbapi_cursor: DBAPICursor, size: Optional[int] = None, ) -> Any: try: if size is None: l = dbapi_cursor.fetchmany() else: l = dbapi_cursor.fetchmany(size) if not l: result._soft_close() return l except BaseException as e: self.handle_exception(result, dbapi_cursor, e) def fetchall( self, result: CursorResult[Any], dbapi_cursor: DBAPICursor, ) -> Any: try: rows = dbapi_cursor.fetchall() result._soft_close() return rows except BaseException as e: self.handle_exception(result, dbapi_cursor, e) _DEFAULT_FETCH = CursorFetchStrategy() class BufferedRowCursorFetchStrategy(CursorFetchStrategy): """A cursor fetch strategy with row buffering behavior. This strategy buffers the contents of a selection of rows before ``fetchone()`` is called. This is to allow the results of ``cursor.description`` to be available immediately, when interfacing with a DB-API that requires rows to be consumed before this information is available (currently psycopg2, when used with server-side cursors). The pre-fetching behavior fetches only one row initially, and then grows its buffer size by a fixed amount with each successive need for additional rows up the ``max_row_buffer`` size, which defaults to 1000:: with psycopg2_engine.connect() as conn: result = conn.execution_options( stream_results=True, max_row_buffer=50 ).execute(text("select * from table")) .. versionadded:: 1.4 ``max_row_buffer`` may now exceed 1000 rows. .. seealso:: :ref:`psycopg2_execution_options` """ __slots__ = ("_max_row_buffer", "_rowbuffer", "_bufsize", "_growth_factor") def __init__( self, dbapi_cursor, execution_options, growth_factor=5, initial_buffer=None, ): self._max_row_buffer = execution_options.get("max_row_buffer", 1000) if initial_buffer is not None: self._rowbuffer = initial_buffer else: self._rowbuffer = collections.deque(dbapi_cursor.fetchmany(1)) self._growth_factor = growth_factor if growth_factor: self._bufsize = min(self._max_row_buffer, self._growth_factor) else: self._bufsize = self._max_row_buffer @classmethod def create(cls, result): return BufferedRowCursorFetchStrategy( result.cursor, result.context.execution_options, ) def _buffer_rows(self, result, dbapi_cursor): """this is currently used only by fetchone().""" size = self._bufsize try: if size < 1: new_rows = dbapi_cursor.fetchall() else: new_rows = dbapi_cursor.fetchmany(size) except BaseException as e: self.handle_exception(result, dbapi_cursor, e) if not new_rows: return self._rowbuffer = collections.deque(new_rows) if self._growth_factor and size < self._max_row_buffer: self._bufsize = min( self._max_row_buffer, size * self._growth_factor ) def yield_per(self, result, dbapi_cursor, num): self._growth_factor = 0 self._max_row_buffer = self._bufsize = num def soft_close(self, result, dbapi_cursor): self._rowbuffer.clear() super().soft_close(result, dbapi_cursor) def hard_close(self, result, dbapi_cursor): self._rowbuffer.clear() super().hard_close(result, dbapi_cursor) def fetchone(self, result, dbapi_cursor, hard_close=False): if not self._rowbuffer: self._buffer_rows(result, dbapi_cursor) if not self._rowbuffer: try: result._soft_close(hard=hard_close) except BaseException as e: self.handle_exception(result, dbapi_cursor, e) return None return self._rowbuffer.popleft() def fetchmany(self, result, dbapi_cursor, size=None): if size is None: return self.fetchall(result, dbapi_cursor) rb = self._rowbuffer lb = len(rb) close = False if size > lb: try: new = dbapi_cursor.fetchmany(size - lb) except BaseException as e: self.handle_exception(result, dbapi_cursor, e) else: if not new: # defer closing since it may clear the row buffer close = True else: rb.extend(new) res = [rb.popleft() for _ in range(min(size, len(rb)))] if close: result._soft_close() return res def fetchall(self, result, dbapi_cursor): try: ret = list(self._rowbuffer) + list(dbapi_cursor.fetchall()) self._rowbuffer.clear() result._soft_close() return ret except BaseException as e: self.handle_exception(result, dbapi_cursor, e) class FullyBufferedCursorFetchStrategy(CursorFetchStrategy): """A cursor strategy that buffers rows fully upon creation. Used for operations where a result is to be delivered after the database conversation can not be continued, such as MSSQL INSERT...OUTPUT after an autocommit. """ __slots__ = ("_rowbuffer", "alternate_cursor_description") def __init__( self, dbapi_cursor: Optional[DBAPICursor], alternate_description: Optional[_DBAPICursorDescription] = None, initial_buffer: Optional[Iterable[Any]] = None, ): self.alternate_cursor_description = alternate_description if initial_buffer is not None: self._rowbuffer = collections.deque(initial_buffer) else: assert dbapi_cursor is not None self._rowbuffer = collections.deque(dbapi_cursor.fetchall()) def yield_per(self, result, dbapi_cursor, num): pass def soft_close(self, result, dbapi_cursor): self._rowbuffer.clear() super().soft_close(result, dbapi_cursor) def hard_close(self, result, dbapi_cursor): self._rowbuffer.clear() super().hard_close(result, dbapi_cursor) def fetchone(self, result, dbapi_cursor, hard_close=False): if self._rowbuffer: return self._rowbuffer.popleft() else: result._soft_close(hard=hard_close) return None def fetchmany(self, result, dbapi_cursor, size=None): if size is None: return self.fetchall(result, dbapi_cursor) rb = self._rowbuffer rows = [rb.popleft() for _ in range(min(size, len(rb)))] if not rows: result._soft_close() return rows def fetchall(self, result, dbapi_cursor): ret = self._rowbuffer self._rowbuffer = collections.deque() result._soft_close() return ret class _NoResultMetaData(ResultMetaData): __slots__ = () returns_rows = False def _we_dont_return_rows(self, err=None): raise exc.ResourceClosedError( "This result object does not return rows. " "It has been closed automatically." ) from err def _index_for_key(self, keys, raiseerr): self._we_dont_return_rows() def _metadata_for_keys(self, key): self._we_dont_return_rows() def _reduce(self, keys): self._we_dont_return_rows() @property def _keymap(self): self._we_dont_return_rows() @property def _key_to_index(self): self._we_dont_return_rows() @property def _processors(self): self._we_dont_return_rows() @property def keys(self): self._we_dont_return_rows() _NO_RESULT_METADATA = _NoResultMetaData() def null_dml_result() -> IteratorResult[Any]: it: IteratorResult[Any] = IteratorResult(_NoResultMetaData(), iter([])) it._soft_close() return it class CursorResult(Result[_T]): """A Result that is representing state from a DBAPI cursor. .. versionchanged:: 1.4 The :class:`.CursorResult`` class replaces the previous :class:`.ResultProxy` interface. This classes are based on the :class:`.Result` calling API which provides an updated usage model and calling facade for SQLAlchemy Core and SQLAlchemy ORM. Returns database rows via the :class:`.Row` class, which provides additional API features and behaviors on top of the raw data returned by the DBAPI. Through the use of filters such as the :meth:`.Result.scalars` method, other kinds of objects may also be returned. .. seealso:: :ref:`tutorial_selecting_data` - introductory material for accessing :class:`_engine.CursorResult` and :class:`.Row` objects. """ __slots__ = ( "context", "dialect", "cursor", "cursor_strategy", "_echo", "connection", ) _metadata: Union[CursorResultMetaData, _NoResultMetaData] _no_result_metadata = _NO_RESULT_METADATA _soft_closed: bool = False closed: bool = False _is_cursor = True context: DefaultExecutionContext dialect: Dialect cursor_strategy: ResultFetchStrategy connection: Connection def __init__( self, context: DefaultExecutionContext, cursor_strategy: ResultFetchStrategy, cursor_description: Optional[_DBAPICursorDescription], ): self.context = context self.dialect = context.dialect self.cursor = context.cursor self.cursor_strategy = cursor_strategy self.connection = context.root_connection self._echo = echo = ( self.connection._echo and context.engine._should_log_debug() ) if cursor_description is not None: # inline of Result._row_getter(), set up an initial row # getter assuming no transformations will be called as this # is the most common case metadata = self._init_metadata(context, cursor_description) _make_row: Any _make_row = functools.partial( Row, metadata, metadata._effective_processors, metadata._key_to_index, ) if context._num_sentinel_cols: sentinel_filter = operator.itemgetter( slice(-context._num_sentinel_cols) ) def _sliced_row(raw_data): return _make_row(sentinel_filter(raw_data)) sliced_row = _sliced_row else: sliced_row = _make_row if echo: log = self.context.connection._log_debug def _log_row(row): log("Row %r", sql_util._repr_row(row)) return row self._row_logging_fn = _log_row def _make_row_2(row): return _log_row(sliced_row(row)) make_row = _make_row_2 else: make_row = sliced_row self._set_memoized_attribute("_row_getter", make_row) else: assert context._num_sentinel_cols == 0 self._metadata = self._no_result_metadata def _init_metadata(self, context, cursor_description): if context.compiled: compiled = context.compiled if compiled._cached_metadata: metadata = compiled._cached_metadata else: metadata = CursorResultMetaData(self, cursor_description) if metadata._safe_for_cache: compiled._cached_metadata = metadata # result rewrite/ adapt step. this is to suit the case # when we are invoked against a cached Compiled object, we want # to rewrite the ResultMetaData to reflect the Column objects # that are in our current SQL statement object, not the one # that is associated with the cached Compiled object. # the Compiled object may also tell us to not # actually do this step; this is to support the ORM where # it is to produce a new Result object in any case, and will # be using the cached Column objects against this database result # so we don't want to rewrite them. # # Basically this step suits the use case where the end user # is using Core SQL expressions and is accessing columns in the # result row using row._mapping[table.c.column]. if ( not context.execution_options.get( "_result_disable_adapt_to_context", False ) and compiled._result_columns and context.cache_hit is context.dialect.CACHE_HIT and compiled.statement is not context.invoked_statement ): metadata = metadata._adapt_to_context(context) self._metadata = metadata else: self._metadata = metadata = CursorResultMetaData( self, cursor_description ) if self._echo: context.connection._log_debug( "Col %r", tuple(x[0] for x in cursor_description) ) return metadata def _soft_close(self, hard=False): """Soft close this :class:`_engine.CursorResult`. This releases all DBAPI cursor resources, but leaves the CursorResult "open" from a semantic perspective, meaning the fetchXXX() methods will continue to return empty results. This method is called automatically when: * all result rows are exhausted using the fetchXXX() methods. * cursor.description is None. This method is **not public**, but is documented in order to clarify the "autoclose" process used. .. seealso:: :meth:`_engine.CursorResult.close` """ if (not hard and self._soft_closed) or (hard and self.closed): return if hard: self.closed = True self.cursor_strategy.hard_close(self, self.cursor) else: self.cursor_strategy.soft_close(self, self.cursor) if not self._soft_closed: cursor = self.cursor self.cursor = None # type: ignore self.connection._safe_close_cursor(cursor) self._soft_closed = True @property def inserted_primary_key_rows(self): """Return the value of :attr:`_engine.CursorResult.inserted_primary_key` as a row contained within a list; some dialects may support a multiple row form as well. .. note:: As indicated below, in current SQLAlchemy versions this accessor is only useful beyond what's already supplied by :attr:`_engine.CursorResult.inserted_primary_key` when using the :ref:`postgresql_psycopg2` dialect. Future versions hope to generalize this feature to more dialects. This accessor is added to support dialects that offer the feature that is currently implemented by the :ref:`psycopg2_executemany_mode` feature, currently **only the psycopg2 dialect**, which provides for many rows to be INSERTed at once while still retaining the behavior of being able to return server-generated primary key values. * **When using the psycopg2 dialect, or other dialects that may support "fast executemany" style inserts in upcoming releases** : When invoking an INSERT statement while passing a list of rows as the second argument to :meth:`_engine.Connection.execute`, this accessor will then provide a list of rows, where each row contains the primary key value for each row that was INSERTed. * **When using all other dialects / backends that don't yet support this feature**: This accessor is only useful for **single row INSERT statements**, and returns the same information as that of the :attr:`_engine.CursorResult.inserted_primary_key` within a single-element list. When an INSERT statement is executed in conjunction with a list of rows to be INSERTed, the list will contain one row per row inserted in the statement, however it will contain ``None`` for any server-generated values. Future releases of SQLAlchemy will further generalize the "fast execution helper" feature of psycopg2 to suit other dialects, thus allowing this accessor to be of more general use. .. versionadded:: 1.4 .. seealso:: :attr:`_engine.CursorResult.inserted_primary_key` """ if not self.context.compiled: raise exc.InvalidRequestError( "Statement is not a compiled expression construct." ) elif not self.context.isinsert: raise exc.InvalidRequestError( "Statement is not an insert() expression construct." ) elif self.context._is_explicit_returning: raise exc.InvalidRequestError( "Can't call inserted_primary_key " "when returning() " "is used." ) return self.context.inserted_primary_key_rows @property def inserted_primary_key(self): """Return the primary key for the row just inserted. The return value is a :class:`_result.Row` object representing a named tuple of primary key values in the order in which the primary key columns are configured in the source :class:`_schema.Table`. .. versionchanged:: 1.4.8 - the :attr:`_engine.CursorResult.inserted_primary_key` value is now a named tuple via the :class:`_result.Row` class, rather than a plain tuple. This accessor only applies to single row :func:`_expression.insert` constructs which did not explicitly specify :meth:`_expression.Insert.returning`. Support for multirow inserts, while not yet available for most backends, would be accessed using the :attr:`_engine.CursorResult.inserted_primary_key_rows` accessor. Note that primary key columns which specify a server_default clause, or otherwise do not qualify as "autoincrement" columns (see the notes at :class:`_schema.Column`), and were generated using the database-side default, will appear in this list as ``None`` unless the backend supports "returning" and the insert statement executed with the "implicit returning" enabled. Raises :class:`~sqlalchemy.exc.InvalidRequestError` if the executed statement is not a compiled expression construct or is not an insert() construct. """ if self.context.executemany: raise exc.InvalidRequestError( "This statement was an executemany call; if primary key " "returning is supported, please " "use .inserted_primary_key_rows." ) ikp = self.inserted_primary_key_rows if ikp: return ikp[0] else: return None def last_updated_params(self): """Return the collection of updated parameters from this execution. Raises :class:`~sqlalchemy.exc.InvalidRequestError` if the executed statement is not a compiled expression construct or is not an update() construct. """ if not self.context.compiled: raise exc.InvalidRequestError( "Statement is not a compiled expression construct." ) elif not self.context.isupdate: raise exc.InvalidRequestError( "Statement is not an update() expression construct." ) elif self.context.executemany: return self.context.compiled_parameters else: return self.context.compiled_parameters[0] def last_inserted_params(self): """Return the collection of inserted parameters from this execution. Raises :class:`~sqlalchemy.exc.InvalidRequestError` if the executed statement is not a compiled expression construct or is not an insert() construct. """ if not self.context.compiled: raise exc.InvalidRequestError( "Statement is not a compiled expression construct." ) elif not self.context.isinsert: raise exc.InvalidRequestError( "Statement is not an insert() expression construct." ) elif self.context.executemany: return self.context.compiled_parameters else: return self.context.compiled_parameters[0] @property def returned_defaults_rows(self): """Return a list of rows each containing the values of default columns that were fetched using the :meth:`.ValuesBase.return_defaults` feature. The return value is a list of :class:`.Row` objects. .. versionadded:: 1.4 """ return self.context.returned_default_rows def splice_horizontally(self, other): """Return a new :class:`.CursorResult` that "horizontally splices" together the rows of this :class:`.CursorResult` with that of another :class:`.CursorResult`. .. tip:: This method is for the benefit of the SQLAlchemy ORM and is not intended for general use. "horizontally splices" means that for each row in the first and second result sets, a new row that concatenates the two rows together is produced, which then becomes the new row. The incoming :class:`.CursorResult` must have the identical number of rows. It is typically expected that the two result sets come from the same sort order as well, as the result rows are spliced together based on their position in the result. The expected use case here is so that multiple INSERT..RETURNING statements (which definitely need to be sorted) against different tables can produce a single result that looks like a JOIN of those two tables. E.g.:: r1 = connection.execute( users.insert().returning( users.c.user_name, users.c.user_id, sort_by_parameter_order=True ), user_values, ) r2 = connection.execute( addresses.insert().returning( addresses.c.address_id, addresses.c.address, addresses.c.user_id, sort_by_parameter_order=True, ), address_values, ) rows = r1.splice_horizontally(r2).all() assert rows == [ ("john", 1, 1, "foo@bar.com", 1), ("jack", 2, 2, "bar@bat.com", 2), ] .. versionadded:: 2.0 .. seealso:: :meth:`.CursorResult.splice_vertically` """ # noqa: E501 clone = self._generate() total_rows = [ tuple(r1) + tuple(r2) for r1, r2 in zip( list(self._raw_row_iterator()), list(other._raw_row_iterator()), ) ] clone._metadata = clone._metadata._splice_horizontally(other._metadata) clone.cursor_strategy = FullyBufferedCursorFetchStrategy( None, initial_buffer=total_rows, ) clone._reset_memoizations() return clone def splice_vertically(self, other): """Return a new :class:`.CursorResult` that "vertically splices", i.e. "extends", the rows of this :class:`.CursorResult` with that of another :class:`.CursorResult`. .. tip:: This method is for the benefit of the SQLAlchemy ORM and is not intended for general use. "vertically splices" means the rows of the given result are appended to the rows of this cursor result. The incoming :class:`.CursorResult` must have rows that represent the identical list of columns in the identical order as they are in this :class:`.CursorResult`. .. versionadded:: 2.0 .. seealso:: :meth:`.CursorResult.splice_horizontally` """ clone = self._generate() total_rows = list(self._raw_row_iterator()) + list( other._raw_row_iterator() ) clone.cursor_strategy = FullyBufferedCursorFetchStrategy( None, initial_buffer=total_rows, ) clone._reset_memoizations() return clone def _rewind(self, rows): """rewind this result back to the given rowset. this is used internally for the case where an :class:`.Insert` construct combines the use of :meth:`.Insert.return_defaults` along with the "supplemental columns" feature. """ if self._echo: self.context.connection._log_debug( "CursorResult rewound %d row(s)", len(rows) ) # the rows given are expected to be Row objects, so we # have to clear out processors which have already run on these # rows self._metadata = cast( CursorResultMetaData, self._metadata )._remove_processors() self.cursor_strategy = FullyBufferedCursorFetchStrategy( None, # TODO: if these are Row objects, can we save on not having to # re-make new Row objects out of them a second time? is that # what's actually happening right now? maybe look into this initial_buffer=rows, ) self._reset_memoizations() return self @property def returned_defaults(self): """Return the values of default columns that were fetched using the :meth:`.ValuesBase.return_defaults` feature. The value is an instance of :class:`.Row`, or ``None`` if :meth:`.ValuesBase.return_defaults` was not used or if the backend does not support RETURNING. .. seealso:: :meth:`.ValuesBase.return_defaults` """ if self.context.executemany: raise exc.InvalidRequestError( "This statement was an executemany call; if return defaults " "is supported, please use .returned_defaults_rows." ) rows = self.context.returned_default_rows if rows: return rows[0] else: return None def lastrow_has_defaults(self): """Return ``lastrow_has_defaults()`` from the underlying :class:`.ExecutionContext`. See :class:`.ExecutionContext` for details. """ return self.context.lastrow_has_defaults() def postfetch_cols(self): """Return ``postfetch_cols()`` from the underlying :class:`.ExecutionContext`. See :class:`.ExecutionContext` for details. Raises :class:`~sqlalchemy.exc.InvalidRequestError` if the executed statement is not a compiled expression construct or is not an insert() or update() construct. """ if not self.context.compiled: raise exc.InvalidRequestError( "Statement is not a compiled expression construct." ) elif not self.context.isinsert and not self.context.isupdate: raise exc.InvalidRequestError( "Statement is not an insert() or update() " "expression construct." ) return self.context.postfetch_cols def prefetch_cols(self): """Return ``prefetch_cols()`` from the underlying :class:`.ExecutionContext`. See :class:`.ExecutionContext` for details. Raises :class:`~sqlalchemy.exc.InvalidRequestError` if the executed statement is not a compiled expression construct or is not an insert() or update() construct. """ if not self.context.compiled: raise exc.InvalidRequestError( "Statement is not a compiled expression construct." ) elif not self.context.isinsert and not self.context.isupdate: raise exc.InvalidRequestError( "Statement is not an insert() or update() " "expression construct." ) return self.context.prefetch_cols def supports_sane_rowcount(self): """Return ``supports_sane_rowcount`` from the dialect. See :attr:`_engine.CursorResult.rowcount` for background. """ return self.dialect.supports_sane_rowcount def supports_sane_multi_rowcount(self): """Return ``supports_sane_multi_rowcount`` from the dialect. See :attr:`_engine.CursorResult.rowcount` for background. """ return self.dialect.supports_sane_multi_rowcount @util.memoized_property def rowcount(self) -> int: """Return the 'rowcount' for this result. The primary purpose of 'rowcount' is to report the number of rows matched by the WHERE criterion of an UPDATE or DELETE statement executed once (i.e. for a single parameter set), which may then be compared to the number of rows expected to be updated or deleted as a means of asserting data integrity. This attribute is transferred from the ``cursor.rowcount`` attribute of the DBAPI before the cursor is closed, to support DBAPIs that don't make this value available after cursor close. Some DBAPIs may offer meaningful values for other kinds of statements, such as INSERT and SELECT statements as well. In order to retrieve ``cursor.rowcount`` for these statements, set the :paramref:`.Connection.execution_options.preserve_rowcount` execution option to True, which will cause the ``cursor.rowcount`` value to be unconditionally memoized before any results are returned or the cursor is closed, regardless of statement type. For cases where the DBAPI does not support rowcount for a particular kind of statement and/or execution, the returned value will be ``-1``, which is delivered directly from the DBAPI and is part of :pep:`249`. All DBAPIs should support rowcount for single-parameter-set UPDATE and DELETE statements, however. .. note:: Notes regarding :attr:`_engine.CursorResult.rowcount`: * This attribute returns the number of rows *matched*, which is not necessarily the same as the number of rows that were actually *modified*. For example, an UPDATE statement may have no net change on a given row if the SET values given are the same as those present in the row already. Such a row would be matched but not modified. On backends that feature both styles, such as MySQL, rowcount is configured to return the match count in all cases. * :attr:`_engine.CursorResult.rowcount` in the default case is *only* useful in conjunction with an UPDATE or DELETE statement, and only with a single set of parameters. For other kinds of statements, SQLAlchemy will not attempt to pre-memoize the value unless the :paramref:`.Connection.execution_options.preserve_rowcount` execution option is used. Note that contrary to :pep:`249`, many DBAPIs do not support rowcount values for statements that are not UPDATE or DELETE, particularly when rows are being returned which are not fully pre-buffered. DBAPIs that dont support rowcount for a particular kind of statement should return the value ``-1`` for such statements. * :attr:`_engine.CursorResult.rowcount` may not be meaningful when executing a single statement with multiple parameter sets (i.e. an :term:`executemany`). Most DBAPIs do not sum "rowcount" values across multiple parameter sets and will return ``-1`` when accessed. * SQLAlchemy's :ref:`engine_insertmanyvalues` feature does support a correct population of :attr:`_engine.CursorResult.rowcount` when the :paramref:`.Connection.execution_options.preserve_rowcount` execution option is set to True. * Statements that use RETURNING may not support rowcount, returning a ``-1`` value instead. .. seealso:: :ref:`tutorial_update_delete_rowcount` - in the :ref:`unified_tutorial` :paramref:`.Connection.execution_options.preserve_rowcount` """ # noqa: E501 try: return self.context.rowcount except BaseException as e: self.cursor_strategy.handle_exception(self, self.cursor, e) raise # not called @property def lastrowid(self): """Return the 'lastrowid' accessor on the DBAPI cursor. This is a DBAPI specific method and is only functional for those backends which support it, for statements where it is appropriate. It's behavior is not consistent across backends. Usage of this method is normally unnecessary when using insert() expression constructs; the :attr:`~CursorResult.inserted_primary_key` attribute provides a tuple of primary key values for a newly inserted row, regardless of database backend. """ try: return self.context.get_lastrowid() except BaseException as e: self.cursor_strategy.handle_exception(self, self.cursor, e) @property def returns_rows(self): """True if this :class:`_engine.CursorResult` returns zero or more rows. I.e. if it is legal to call the methods :meth:`_engine.CursorResult.fetchone`, :meth:`_engine.CursorResult.fetchmany` :meth:`_engine.CursorResult.fetchall`. Overall, the value of :attr:`_engine.CursorResult.returns_rows` should always be synonymous with whether or not the DBAPI cursor had a ``.description`` attribute, indicating the presence of result columns, noting that a cursor that returns zero rows still has a ``.description`` if a row-returning statement was emitted. This attribute should be True for all results that are against SELECT statements, as well as for DML statements INSERT/UPDATE/DELETE that use RETURNING. For INSERT/UPDATE/DELETE statements that were not using RETURNING, the value will usually be False, however there are some dialect-specific exceptions to this, such as when using the MSSQL / pyodbc dialect a SELECT is emitted inline in order to retrieve an inserted primary key value. """ return self._metadata.returns_rows @property def is_insert(self): """True if this :class:`_engine.CursorResult` is the result of a executing an expression language compiled :func:`_expression.insert` construct. When True, this implies that the :attr:`inserted_primary_key` attribute is accessible, assuming the statement did not include a user defined "returning" construct. """ return self.context.isinsert def _fetchiter_impl(self): fetchone = self.cursor_strategy.fetchone while True: row = fetchone(self, self.cursor) if row is None: break yield row def _fetchone_impl(self, hard_close=False): return self.cursor_strategy.fetchone(self, self.cursor, hard_close) def _fetchall_impl(self): return self.cursor_strategy.fetchall(self, self.cursor) def _fetchmany_impl(self, size=None): return self.cursor_strategy.fetchmany(self, self.cursor, size) def _raw_row_iterator(self): return self._fetchiter_impl() def merge(self, *others: Result[Any]) -> MergedResult[Any]: merged_result = super().merge(*others) if self.context._has_rowcount: merged_result.rowcount = sum( cast("CursorResult[Any]", result).rowcount for result in (self,) + others ) return merged_result def close(self) -> Any: """Close this :class:`_engine.CursorResult`. This closes out the underlying DBAPI cursor corresponding to the statement execution, if one is still present. Note that the DBAPI cursor is automatically released when the :class:`_engine.CursorResult` exhausts all available rows. :meth:`_engine.CursorResult.close` is generally an optional method except in the case when discarding a :class:`_engine.CursorResult` that still has additional rows pending for fetch. After this method is called, it is no longer valid to call upon the fetch methods, which will raise a :class:`.ResourceClosedError` on subsequent use. .. seealso:: :ref:`connections_toplevel` """ self._soft_close(hard=True) @_generative def yield_per(self, num: int) -> Self: self._yield_per = num self.cursor_strategy.yield_per(self, self.cursor, num) return self ResultProxy = CursorResult sqlalchemy/engine/interfaces.py 0000755 00000335460 15125143220 0012661 0 ustar 00 # engine/interfaces.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """Define core interfaces used by the engine system.""" from __future__ import annotations from enum import Enum from types import ModuleType from typing import Any from typing import Awaitable from typing import Callable from typing import ClassVar from typing import Collection from typing import Dict from typing import Iterable from typing import Iterator from typing import List from typing import Mapping from typing import MutableMapping from typing import Optional from typing import Sequence from typing import Set from typing import Tuple from typing import Type from typing import TYPE_CHECKING from typing import TypeVar from typing import Union from .. import util from ..event import EventTarget from ..pool import Pool from ..pool import PoolProxiedConnection from ..sql.compiler import Compiled as Compiled from ..sql.compiler import Compiled # noqa from ..sql.compiler import TypeCompiler as TypeCompiler from ..sql.compiler import TypeCompiler # noqa from ..util import immutabledict from ..util.concurrency import await_only from ..util.typing import Literal from ..util.typing import NotRequired from ..util.typing import Protocol from ..util.typing import TypedDict if TYPE_CHECKING: from .base import Connection from .base import Engine from .cursor import CursorResult from .url import URL from ..event import _ListenerFnType from ..event import dispatcher from ..exc import StatementError from ..sql import Executable from ..sql.compiler import _InsertManyValuesBatch from ..sql.compiler import DDLCompiler from ..sql.compiler import IdentifierPreparer from ..sql.compiler import InsertmanyvaluesSentinelOpts from ..sql.compiler import Linting from ..sql.compiler import SQLCompiler from ..sql.elements import BindParameter from ..sql.elements import ClauseElement from ..sql.schema import Column from ..sql.schema import DefaultGenerator from ..sql.schema import SchemaItem from ..sql.schema import Sequence as Sequence_SchemaItem from ..sql.sqltypes import Integer from ..sql.type_api import _TypeMemoDict from ..sql.type_api import TypeEngine ConnectArgsType = Tuple[Sequence[str], MutableMapping[str, Any]] _T = TypeVar("_T", bound="Any") class CacheStats(Enum): CACHE_HIT = 0 CACHE_MISS = 1 CACHING_DISABLED = 2 NO_CACHE_KEY = 3 NO_DIALECT_SUPPORT = 4 class ExecuteStyle(Enum): """indicates the :term:`DBAPI` cursor method that will be used to invoke a statement.""" EXECUTE = 0 """indicates cursor.execute() will be used""" EXECUTEMANY = 1 """indicates cursor.executemany() will be used.""" INSERTMANYVALUES = 2 """indicates cursor.execute() will be used with an INSERT where the VALUES expression will be expanded to accommodate for multiple parameter sets .. seealso:: :ref:`engine_insertmanyvalues` """ class DBAPIConnection(Protocol): """protocol representing a :pep:`249` database connection. .. versionadded:: 2.0 .. seealso:: `Connection Objects <https://www.python.org/dev/peps/pep-0249/#connection-objects>`_ - in :pep:`249` """ # noqa: E501 def close(self) -> None: ... def commit(self) -> None: ... def cursor(self, *args: Any, **kwargs: Any) -> DBAPICursor: ... def rollback(self) -> None: ... autocommit: bool class DBAPIType(Protocol): """protocol representing a :pep:`249` database type. .. versionadded:: 2.0 .. seealso:: `Type Objects <https://www.python.org/dev/peps/pep-0249/#type-objects>`_ - in :pep:`249` """ # noqa: E501 class DBAPICursor(Protocol): """protocol representing a :pep:`249` database cursor. .. versionadded:: 2.0 .. seealso:: `Cursor Objects <https://www.python.org/dev/peps/pep-0249/#cursor-objects>`_ - in :pep:`249` """ # noqa: E501 @property def description( self, ) -> _DBAPICursorDescription: """The description attribute of the Cursor. .. seealso:: `cursor.description <https://www.python.org/dev/peps/pep-0249/#description>`_ - in :pep:`249` """ # noqa: E501 ... @property def rowcount(self) -> int: ... arraysize: int lastrowid: int def close(self) -> None: ... def execute( self, operation: Any, parameters: Optional[_DBAPISingleExecuteParams] = None, ) -> Any: ... def executemany( self, operation: Any, parameters: _DBAPIMultiExecuteParams, ) -> Any: ... def fetchone(self) -> Optional[Any]: ... def fetchmany(self, size: int = ...) -> Sequence[Any]: ... def fetchall(self) -> Sequence[Any]: ... def setinputsizes(self, sizes: Sequence[Any]) -> None: ... def setoutputsize(self, size: Any, column: Any) -> None: ... def callproc( self, procname: str, parameters: Sequence[Any] = ... ) -> Any: ... def nextset(self) -> Optional[bool]: ... def __getattr__(self, key: str) -> Any: ... _CoreSingleExecuteParams = Mapping[str, Any] _MutableCoreSingleExecuteParams = MutableMapping[str, Any] _CoreMultiExecuteParams = Sequence[_CoreSingleExecuteParams] _CoreAnyExecuteParams = Union[ _CoreMultiExecuteParams, _CoreSingleExecuteParams ] _DBAPISingleExecuteParams = Union[Sequence[Any], _CoreSingleExecuteParams] _DBAPIMultiExecuteParams = Union[ Sequence[Sequence[Any]], _CoreMultiExecuteParams ] _DBAPIAnyExecuteParams = Union[ _DBAPIMultiExecuteParams, _DBAPISingleExecuteParams ] _DBAPICursorDescription = Sequence[ Tuple[ str, "DBAPIType", Optional[int], Optional[int], Optional[int], Optional[int], Optional[bool], ] ] _AnySingleExecuteParams = _DBAPISingleExecuteParams _AnyMultiExecuteParams = _DBAPIMultiExecuteParams _AnyExecuteParams = _DBAPIAnyExecuteParams CompiledCacheType = MutableMapping[Any, "Compiled"] SchemaTranslateMapType = Mapping[Optional[str], Optional[str]] _ImmutableExecuteOptions = immutabledict[str, Any] _ParamStyle = Literal[ "qmark", "numeric", "named", "format", "pyformat", "numeric_dollar" ] _GenericSetInputSizesType = List[Tuple[str, Any, "TypeEngine[Any]"]] IsolationLevel = Literal[ "SERIALIZABLE", "REPEATABLE READ", "READ COMMITTED", "READ UNCOMMITTED", "AUTOCOMMIT", ] class _CoreKnownExecutionOptions(TypedDict, total=False): compiled_cache: Optional[CompiledCacheType] logging_token: str isolation_level: IsolationLevel no_parameters: bool stream_results: bool max_row_buffer: int yield_per: int insertmanyvalues_page_size: int schema_translate_map: Optional[SchemaTranslateMapType] preserve_rowcount: bool _ExecuteOptions = immutabledict[str, Any] CoreExecuteOptionsParameter = Union[ _CoreKnownExecutionOptions, Mapping[str, Any] ] class ReflectedIdentity(TypedDict): """represent the reflected IDENTITY structure of a column, corresponding to the :class:`_schema.Identity` construct. The :class:`.ReflectedIdentity` structure is part of the :class:`.ReflectedColumn` structure, which is returned by the :meth:`.Inspector.get_columns` method. """ always: bool """type of identity column""" on_null: bool """indicates ON NULL""" start: int """starting index of the sequence""" increment: int """increment value of the sequence""" minvalue: int """the minimum value of the sequence.""" maxvalue: int """the maximum value of the sequence.""" nominvalue: bool """no minimum value of the sequence.""" nomaxvalue: bool """no maximum value of the sequence.""" cycle: bool """allows the sequence to wrap around when the maxvalue or minvalue has been reached.""" cache: Optional[int] """number of future values in the sequence which are calculated in advance.""" order: bool """if true, renders the ORDER keyword.""" class ReflectedComputed(TypedDict): """Represent the reflected elements of a computed column, corresponding to the :class:`_schema.Computed` construct. The :class:`.ReflectedComputed` structure is part of the :class:`.ReflectedColumn` structure, which is returned by the :meth:`.Inspector.get_columns` method. """ sqltext: str """the expression used to generate this column returned as a string SQL expression""" persisted: NotRequired[bool] """indicates if the value is stored in the table or computed on demand""" class ReflectedColumn(TypedDict): """Dictionary representing the reflected elements corresponding to a :class:`_schema.Column` object. The :class:`.ReflectedColumn` structure is returned by the :class:`.Inspector.get_columns` method. """ name: str """column name""" type: TypeEngine[Any] """column type represented as a :class:`.TypeEngine` instance.""" nullable: bool """boolean flag if the column is NULL or NOT NULL""" default: Optional[str] """column default expression as a SQL string""" autoincrement: NotRequired[bool] """database-dependent autoincrement flag. This flag indicates if the column has a database-side "autoincrement" flag of some kind. Within SQLAlchemy, other kinds of columns may also act as an "autoincrement" column without necessarily having such a flag on them. See :paramref:`_schema.Column.autoincrement` for more background on "autoincrement". """ comment: NotRequired[Optional[str]] """comment for the column, if present. Only some dialects return this key """ computed: NotRequired[ReflectedComputed] """indicates that this column is computed by the database. Only some dialects return this key. .. versionadded:: 1.3.16 - added support for computed reflection. """ identity: NotRequired[ReflectedIdentity] """indicates this column is an IDENTITY column. Only some dialects return this key. .. versionadded:: 1.4 - added support for identity column reflection. """ dialect_options: NotRequired[Dict[str, Any]] """Additional dialect-specific options detected for this reflected object""" class ReflectedConstraint(TypedDict): """Dictionary representing the reflected elements corresponding to :class:`.Constraint` A base class for all constraints """ name: Optional[str] """constraint name""" comment: NotRequired[Optional[str]] """comment for the constraint, if present""" class ReflectedCheckConstraint(ReflectedConstraint): """Dictionary representing the reflected elements corresponding to :class:`.CheckConstraint`. The :class:`.ReflectedCheckConstraint` structure is returned by the :meth:`.Inspector.get_check_constraints` method. """ sqltext: str """the check constraint's SQL expression""" dialect_options: NotRequired[Dict[str, Any]] """Additional dialect-specific options detected for this check constraint .. versionadded:: 1.3.8 """ class ReflectedUniqueConstraint(ReflectedConstraint): """Dictionary representing the reflected elements corresponding to :class:`.UniqueConstraint`. The :class:`.ReflectedUniqueConstraint` structure is returned by the :meth:`.Inspector.get_unique_constraints` method. """ column_names: List[str] """column names which comprise the unique constraint""" duplicates_index: NotRequired[Optional[str]] "Indicates if this unique constraint duplicates an index with this name" dialect_options: NotRequired[Dict[str, Any]] """Additional dialect-specific options detected for this unique constraint""" class ReflectedPrimaryKeyConstraint(ReflectedConstraint): """Dictionary representing the reflected elements corresponding to :class:`.PrimaryKeyConstraint`. The :class:`.ReflectedPrimaryKeyConstraint` structure is returned by the :meth:`.Inspector.get_pk_constraint` method. """ constrained_columns: List[str] """column names which comprise the primary key""" dialect_options: NotRequired[Dict[str, Any]] """Additional dialect-specific options detected for this primary key""" class ReflectedForeignKeyConstraint(ReflectedConstraint): """Dictionary representing the reflected elements corresponding to :class:`.ForeignKeyConstraint`. The :class:`.ReflectedForeignKeyConstraint` structure is returned by the :meth:`.Inspector.get_foreign_keys` method. """ constrained_columns: List[str] """local column names which comprise the foreign key""" referred_schema: Optional[str] """schema name of the table being referred""" referred_table: str """name of the table being referred""" referred_columns: List[str] """referred column names that correspond to ``constrained_columns``""" options: NotRequired[Dict[str, Any]] """Additional options detected for this foreign key constraint""" class ReflectedIndex(TypedDict): """Dictionary representing the reflected elements corresponding to :class:`.Index`. The :class:`.ReflectedIndex` structure is returned by the :meth:`.Inspector.get_indexes` method. """ name: Optional[str] """index name""" column_names: List[Optional[str]] """column names which the index references. An element of this list is ``None`` if it's an expression and is returned in the ``expressions`` list. """ expressions: NotRequired[List[str]] """Expressions that compose the index. This list, when present, contains both plain column names (that are also in ``column_names``) and expressions (that are ``None`` in ``column_names``). """ unique: bool """whether or not the index has a unique flag""" duplicates_constraint: NotRequired[Optional[str]] "Indicates if this index mirrors a constraint with this name" include_columns: NotRequired[List[str]] """columns to include in the INCLUDE clause for supporting databases. .. deprecated:: 2.0 Legacy value, will be replaced with ``index_dict["dialect_options"]["<dialect name>_include"]`` """ column_sorting: NotRequired[Dict[str, Tuple[str]]] """optional dict mapping column names or expressions to tuple of sort keywords, which may include ``asc``, ``desc``, ``nulls_first``, ``nulls_last``. .. versionadded:: 1.3.5 """ dialect_options: NotRequired[Dict[str, Any]] """Additional dialect-specific options detected for this index""" class ReflectedTableComment(TypedDict): """Dictionary representing the reflected comment corresponding to the :attr:`_schema.Table.comment` attribute. The :class:`.ReflectedTableComment` structure is returned by the :meth:`.Inspector.get_table_comment` method. """ text: Optional[str] """text of the comment""" class BindTyping(Enum): """Define different methods of passing typing information for bound parameters in a statement to the database driver. .. versionadded:: 2.0 """ NONE = 1 """No steps are taken to pass typing information to the database driver. This is the default behavior for databases such as SQLite, MySQL / MariaDB, SQL Server. """ SETINPUTSIZES = 2 """Use the pep-249 setinputsizes method. This is only implemented for DBAPIs that support this method and for which the SQLAlchemy dialect has the appropriate infrastructure for that dialect set up. Current dialects include python-oracledb, cx_Oracle as well as optional support for SQL Server using pyodbc. When using setinputsizes, dialects also have a means of only using the method for certain datatypes using include/exclude lists. When SETINPUTSIZES is used, the :meth:`.Dialect.do_set_input_sizes` method is called for each statement executed which has bound parameters. """ RENDER_CASTS = 3 """Render casts or other directives in the SQL string. This method is used for all PostgreSQL dialects, including asyncpg, pg8000, psycopg, psycopg2. Dialects which implement this can choose which kinds of datatypes are explicitly cast in SQL statements and which aren't. When RENDER_CASTS is used, the compiler will invoke the :meth:`.SQLCompiler.render_bind_cast` method for the rendered string representation of each :class:`.BindParameter` object whose dialect-level type sets the :attr:`.TypeEngine.render_bind_cast` attribute. The :meth:`.SQLCompiler.render_bind_cast` is also used to render casts for one form of "insertmanyvalues" query, when both :attr:`.InsertmanyvaluesSentinelOpts.USE_INSERT_FROM_SELECT` and :attr:`.InsertmanyvaluesSentinelOpts.RENDER_SELECT_COL_CASTS` are set, where the casts are applied to the intermediary columns e.g. "INSERT INTO t (a, b, c) SELECT p0::TYP, p1::TYP, p2::TYP " "FROM (VALUES (?, ?), (?, ?), ...)". .. versionadded:: 2.0.10 - :meth:`.SQLCompiler.render_bind_cast` is now used within some elements of the "insertmanyvalues" implementation. """ VersionInfoType = Tuple[Union[int, str], ...] TableKey = Tuple[Optional[str], str] class Dialect(EventTarget): """Define the behavior of a specific database and DB-API combination. Any aspect of metadata definition, SQL query generation, execution, result-set handling, or anything else which varies between databases is defined under the general category of the Dialect. The Dialect acts as a factory for other database-specific object implementations including ExecutionContext, Compiled, DefaultGenerator, and TypeEngine. .. note:: Third party dialects should not subclass :class:`.Dialect` directly. Instead, subclass :class:`.default.DefaultDialect` or descendant class. """ CACHE_HIT = CacheStats.CACHE_HIT CACHE_MISS = CacheStats.CACHE_MISS CACHING_DISABLED = CacheStats.CACHING_DISABLED NO_CACHE_KEY = CacheStats.NO_CACHE_KEY NO_DIALECT_SUPPORT = CacheStats.NO_DIALECT_SUPPORT dispatch: dispatcher[Dialect] name: str """identifying name for the dialect from a DBAPI-neutral point of view (i.e. 'sqlite') """ driver: str """identifying name for the dialect's DBAPI""" dialect_description: str dbapi: Optional[ModuleType] """A reference to the DBAPI module object itself. SQLAlchemy dialects import DBAPI modules using the classmethod :meth:`.Dialect.import_dbapi`. The rationale is so that any dialect module can be imported and used to generate SQL statements without the need for the actual DBAPI driver to be installed. Only when an :class:`.Engine` is constructed using :func:`.create_engine` does the DBAPI get imported; at that point, the creation process will assign the DBAPI module to this attribute. Dialects should therefore implement :meth:`.Dialect.import_dbapi` which will import the necessary module and return it, and then refer to ``self.dbapi`` in dialect code in order to refer to the DBAPI module contents. .. versionchanged:: The :attr:`.Dialect.dbapi` attribute is exclusively used as the per-:class:`.Dialect`-instance reference to the DBAPI module. The previous not-fully-documented ``.Dialect.dbapi()`` classmethod is deprecated and replaced by :meth:`.Dialect.import_dbapi`. """ @util.non_memoized_property def loaded_dbapi(self) -> ModuleType: """same as .dbapi, but is never None; will raise an error if no DBAPI was set up. .. versionadded:: 2.0 """ raise NotImplementedError() positional: bool """True if the paramstyle for this Dialect is positional.""" paramstyle: str """the paramstyle to be used (some DB-APIs support multiple paramstyles). """ compiler_linting: Linting statement_compiler: Type[SQLCompiler] """a :class:`.Compiled` class used to compile SQL statements""" ddl_compiler: Type[DDLCompiler] """a :class:`.Compiled` class used to compile DDL statements""" type_compiler_cls: ClassVar[Type[TypeCompiler]] """a :class:`.Compiled` class used to compile SQL type objects .. versionadded:: 2.0 """ type_compiler_instance: TypeCompiler """instance of a :class:`.Compiled` class used to compile SQL type objects .. versionadded:: 2.0 """ type_compiler: Any """legacy; this is a TypeCompiler class at the class level, a TypeCompiler instance at the instance level. Refer to type_compiler_instance instead. """ preparer: Type[IdentifierPreparer] """a :class:`.IdentifierPreparer` class used to quote identifiers. """ identifier_preparer: IdentifierPreparer """This element will refer to an instance of :class:`.IdentifierPreparer` once a :class:`.DefaultDialect` has been constructed. """ server_version_info: Optional[Tuple[Any, ...]] """a tuple containing a version number for the DB backend in use. This value is only available for supporting dialects, and is typically populated during the initial connection to the database. """ default_schema_name: Optional[str] """the name of the default schema. This value is only available for supporting dialects, and is typically populated during the initial connection to the database. """ # NOTE: this does not take into effect engine-level isolation level. # not clear if this should be changed, seems like it should default_isolation_level: Optional[IsolationLevel] """the isolation that is implicitly present on new connections""" # create_engine() -> isolation_level currently goes here _on_connect_isolation_level: Optional[IsolationLevel] execution_ctx_cls: Type[ExecutionContext] """a :class:`.ExecutionContext` class used to handle statement execution""" execute_sequence_format: Union[ Type[Tuple[Any, ...]], Type[Tuple[List[Any]]] ] """either the 'tuple' or 'list' type, depending on what cursor.execute() accepts for the second argument (they vary).""" supports_alter: bool """``True`` if the database supports ``ALTER TABLE`` - used only for generating foreign key constraints in certain circumstances """ max_identifier_length: int """The maximum length of identifier names.""" max_index_name_length: Optional[int] """The maximum length of index names if different from ``max_identifier_length``.""" max_constraint_name_length: Optional[int] """The maximum length of constraint names if different from ``max_identifier_length``.""" supports_server_side_cursors: bool """indicates if the dialect supports server side cursors""" server_side_cursors: bool """deprecated; indicates if the dialect should attempt to use server side cursors by default""" supports_sane_rowcount: bool """Indicate whether the dialect properly implements rowcount for ``UPDATE`` and ``DELETE`` statements. """ supports_sane_multi_rowcount: bool """Indicate whether the dialect properly implements rowcount for ``UPDATE`` and ``DELETE`` statements when executed via executemany. """ supports_empty_insert: bool """dialect supports INSERT () VALUES (), i.e. a plain INSERT with no columns in it. This is not usually supported; an "empty" insert is typically suited using either "INSERT..DEFAULT VALUES" or "INSERT ... (col) VALUES (DEFAULT)". """ supports_default_values: bool """dialect supports INSERT... DEFAULT VALUES syntax""" supports_default_metavalue: bool """dialect supports INSERT...(col) VALUES (DEFAULT) syntax. Most databases support this in some way, e.g. SQLite supports it using ``VALUES (NULL)``. MS SQL Server supports the syntax also however is the only included dialect where we have this disabled, as MSSQL does not support the field for the IDENTITY column, which is usually where we like to make use of the feature. """ default_metavalue_token: str = "DEFAULT" """for INSERT... VALUES (DEFAULT) syntax, the token to put in the parenthesis. E.g. for SQLite this is the keyword "NULL". """ supports_multivalues_insert: bool """Target database supports INSERT...VALUES with multiple value sets, i.e. INSERT INTO table (cols) VALUES (...), (...), (...), ... """ insert_executemany_returning: bool """dialect / driver / database supports some means of providing INSERT...RETURNING support when dialect.do_executemany() is used. """ insert_executemany_returning_sort_by_parameter_order: bool """dialect / driver / database supports some means of providing INSERT...RETURNING support when dialect.do_executemany() is used along with the :paramref:`_dml.Insert.returning.sort_by_parameter_order` parameter being set. """ update_executemany_returning: bool """dialect supports UPDATE..RETURNING with executemany.""" delete_executemany_returning: bool """dialect supports DELETE..RETURNING with executemany.""" use_insertmanyvalues: bool """if True, indicates "insertmanyvalues" functionality should be used to allow for ``insert_executemany_returning`` behavior, if possible. In practice, setting this to True means: if ``supports_multivalues_insert``, ``insert_returning`` and ``use_insertmanyvalues`` are all True, the SQL compiler will produce an INSERT that will be interpreted by the :class:`.DefaultDialect` as an :attr:`.ExecuteStyle.INSERTMANYVALUES` execution that allows for INSERT of many rows with RETURNING by rewriting a single-row INSERT statement to have multiple VALUES clauses, also executing the statement multiple times for a series of batches when large numbers of rows are given. The parameter is False for the default dialect, and is set to True for SQLAlchemy internal dialects SQLite, MySQL/MariaDB, PostgreSQL, SQL Server. It remains at False for Oracle Database, which provides native "executemany with RETURNING" support and also does not support ``supports_multivalues_insert``. For MySQL/MariaDB, those MySQL dialects that don't support RETURNING will not report ``insert_executemany_returning`` as True. .. versionadded:: 2.0 .. seealso:: :ref:`engine_insertmanyvalues` """ use_insertmanyvalues_wo_returning: bool """if True, and use_insertmanyvalues is also True, INSERT statements that don't include RETURNING will also use "insertmanyvalues". .. versionadded:: 2.0 .. seealso:: :ref:`engine_insertmanyvalues` """ insertmanyvalues_implicit_sentinel: InsertmanyvaluesSentinelOpts """Options indicating the database supports a form of bulk INSERT where the autoincrement integer primary key can be reliably used as an ordering for INSERTed rows. .. versionadded:: 2.0.10 .. seealso:: :ref:`engine_insertmanyvalues_returning_order` """ insertmanyvalues_page_size: int """Number of rows to render into an individual INSERT..VALUES() statement for :attr:`.ExecuteStyle.INSERTMANYVALUES` executions. The default dialect defaults this to 1000. .. versionadded:: 2.0 .. seealso:: :paramref:`_engine.Connection.execution_options.insertmanyvalues_page_size` - execution option available on :class:`_engine.Connection`, statements """ # noqa: E501 insertmanyvalues_max_parameters: int """Alternate to insertmanyvalues_page_size, will additionally limit page size based on number of parameters total in the statement. """ preexecute_autoincrement_sequences: bool """True if 'implicit' primary key functions must be executed separately in order to get their value, if RETURNING is not used. This is currently oriented towards PostgreSQL when the ``implicit_returning=False`` parameter is used on a :class:`.Table` object. """ insert_returning: bool """if the dialect supports RETURNING with INSERT .. versionadded:: 2.0 """ update_returning: bool """if the dialect supports RETURNING with UPDATE .. versionadded:: 2.0 """ update_returning_multifrom: bool """if the dialect supports RETURNING with UPDATE..FROM .. versionadded:: 2.0 """ delete_returning: bool """if the dialect supports RETURNING with DELETE .. versionadded:: 2.0 """ delete_returning_multifrom: bool """if the dialect supports RETURNING with DELETE..FROM .. versionadded:: 2.0 """ favor_returning_over_lastrowid: bool """for backends that support both a lastrowid and a RETURNING insert strategy, favor RETURNING for simple single-int pk inserts. cursor.lastrowid tends to be more performant on most backends. """ supports_identity_columns: bool """target database supports IDENTITY""" cte_follows_insert: bool """target database, when given a CTE with an INSERT statement, needs the CTE to be below the INSERT""" colspecs: MutableMapping[Type[TypeEngine[Any]], Type[TypeEngine[Any]]] """A dictionary of TypeEngine classes from sqlalchemy.types mapped to subclasses that are specific to the dialect class. This dictionary is class-level only and is not accessed from the dialect instance itself. """ supports_sequences: bool """Indicates if the dialect supports CREATE SEQUENCE or similar.""" sequences_optional: bool """If True, indicates if the :paramref:`_schema.Sequence.optional` parameter on the :class:`_schema.Sequence` construct should signal to not generate a CREATE SEQUENCE. Applies only to dialects that support sequences. Currently used only to allow PostgreSQL SERIAL to be used on a column that specifies Sequence() for usage on other backends. """ default_sequence_base: int """the default value that will be rendered as the "START WITH" portion of a CREATE SEQUENCE DDL statement. """ supports_native_enum: bool """Indicates if the dialect supports a native ENUM construct. This will prevent :class:`_types.Enum` from generating a CHECK constraint when that type is used in "native" mode. """ supports_native_boolean: bool """Indicates if the dialect supports a native boolean construct. This will prevent :class:`_types.Boolean` from generating a CHECK constraint when that type is used. """ supports_native_decimal: bool """indicates if Decimal objects are handled and returned for precision numeric types, or if floats are returned""" supports_native_uuid: bool """indicates if Python UUID() objects are handled natively by the driver for SQL UUID datatypes. .. versionadded:: 2.0 """ returns_native_bytes: bool """indicates if Python bytes() objects are returned natively by the driver for SQL "binary" datatypes. .. versionadded:: 2.0.11 """ construct_arguments: Optional[ List[Tuple[Type[Union[SchemaItem, ClauseElement]], Mapping[str, Any]]] ] = None """Optional set of argument specifiers for various SQLAlchemy constructs, typically schema items. To implement, establish as a series of tuples, as in:: construct_arguments = [ (schema.Index, {"using": False, "where": None, "ops": None}), ] If the above construct is established on the PostgreSQL dialect, the :class:`.Index` construct will now accept the keyword arguments ``postgresql_using``, ``postgresql_where``, nad ``postgresql_ops``. Any other argument specified to the constructor of :class:`.Index` which is prefixed with ``postgresql_`` will raise :class:`.ArgumentError`. A dialect which does not include a ``construct_arguments`` member will not participate in the argument validation system. For such a dialect, any argument name is accepted by all participating constructs, within the namespace of arguments prefixed with that dialect name. The rationale here is so that third-party dialects that haven't yet implemented this feature continue to function in the old way. .. seealso:: :class:`.DialectKWArgs` - implementing base class which consumes :attr:`.DefaultDialect.construct_arguments` """ reflection_options: Sequence[str] = () """Sequence of string names indicating keyword arguments that can be established on a :class:`.Table` object which will be passed as "reflection options" when using :paramref:`.Table.autoload_with`. Current example is "oracle_resolve_synonyms" in the Oracle Database dialects. """ dbapi_exception_translation_map: Mapping[str, str] = util.EMPTY_DICT """A dictionary of names that will contain as values the names of pep-249 exceptions ("IntegrityError", "OperationalError", etc) keyed to alternate class names, to support the case where a DBAPI has exception classes that aren't named as they are referred to (e.g. IntegrityError = MyException). In the vast majority of cases this dictionary is empty. """ supports_comments: bool """Indicates the dialect supports comment DDL on tables and columns.""" inline_comments: bool """Indicates the dialect supports comment DDL that's inline with the definition of a Table or Column. If False, this implies that ALTER must be used to set table and column comments.""" supports_constraint_comments: bool """Indicates if the dialect supports comment DDL on constraints. .. versionadded:: 2.0 """ _has_events = False supports_statement_cache: bool = True """indicates if this dialect supports caching. All dialects that are compatible with statement caching should set this flag to True directly on each dialect class and subclass that supports it. SQLAlchemy tests that this flag is locally present on each dialect subclass before it will use statement caching. This is to provide safety for legacy or new dialects that are not yet fully tested to be compliant with SQL statement caching. .. versionadded:: 1.4.5 .. seealso:: :ref:`engine_thirdparty_caching` """ _supports_statement_cache: bool """internal evaluation for supports_statement_cache""" bind_typing = BindTyping.NONE """define a means of passing typing information to the database and/or driver for bound parameters. See :class:`.BindTyping` for values. .. versionadded:: 2.0 """ is_async: bool """Whether or not this dialect is intended for asyncio use.""" has_terminate: bool """Whether or not this dialect has a separate "terminate" implementation that does not block or require awaiting.""" engine_config_types: Mapping[str, Any] """a mapping of string keys that can be in an engine config linked to type conversion functions. """ label_length: Optional[int] """optional user-defined max length for SQL labels""" include_set_input_sizes: Optional[Set[Any]] """set of DBAPI type objects that should be included in automatic cursor.setinputsizes() calls. This is only used if bind_typing is BindTyping.SET_INPUT_SIZES """ exclude_set_input_sizes: Optional[Set[Any]] """set of DBAPI type objects that should be excluded in automatic cursor.setinputsizes() calls. This is only used if bind_typing is BindTyping.SET_INPUT_SIZES """ supports_simple_order_by_label: bool """target database supports ORDER BY <labelname>, where <labelname> refers to a label in the columns clause of the SELECT""" div_is_floordiv: bool """target database treats the / division operator as "floor division" """ tuple_in_values: bool """target database supports tuple IN, i.e. (x, y) IN ((q, p), (r, z))""" _bind_typing_render_casts: bool _type_memos: MutableMapping[TypeEngine[Any], _TypeMemoDict] def _builtin_onconnect(self) -> Optional[_ListenerFnType]: raise NotImplementedError() def create_connect_args(self, url: URL) -> ConnectArgsType: """Build DB-API compatible connection arguments. Given a :class:`.URL` object, returns a tuple consisting of a ``(*args, **kwargs)`` suitable to send directly to the dbapi's connect function. The arguments are sent to the :meth:`.Dialect.connect` method which then runs the DBAPI-level ``connect()`` function. The method typically makes use of the :meth:`.URL.translate_connect_args` method in order to generate a dictionary of options. The default implementation is:: def create_connect_args(self, url): opts = url.translate_connect_args() opts.update(url.query) return ([], opts) :param url: a :class:`.URL` object :return: a tuple of ``(*args, **kwargs)`` which will be passed to the :meth:`.Dialect.connect` method. .. seealso:: :meth:`.URL.translate_connect_args` """ raise NotImplementedError() @classmethod def import_dbapi(cls) -> ModuleType: """Import the DBAPI module that is used by this dialect. The Python module object returned here will be assigned as an instance variable to a constructed dialect under the name ``.dbapi``. .. versionchanged:: 2.0 The :meth:`.Dialect.import_dbapi` class method is renamed from the previous method ``.Dialect.dbapi()``, which would be replaced at dialect instantiation time by the DBAPI module itself, thus using the same name in two different ways. If a ``.Dialect.dbapi()`` classmethod is present on a third-party dialect, it will be used and a deprecation warning will be emitted. """ raise NotImplementedError() def type_descriptor(self, typeobj: TypeEngine[_T]) -> TypeEngine[_T]: """Transform a generic type to a dialect-specific type. Dialect classes will usually use the :func:`_types.adapt_type` function in the types module to accomplish this. The returned result is cached *per dialect class* so can contain no dialect-instance state. """ raise NotImplementedError() def initialize(self, connection: Connection) -> None: """Called during strategized creation of the dialect with a connection. Allows dialects to configure options based on server version info or other properties. The connection passed here is a SQLAlchemy Connection object, with full capabilities. The initialize() method of the base dialect should be called via super(). .. note:: as of SQLAlchemy 1.4, this method is called **before** any :meth:`_engine.Dialect.on_connect` hooks are called. """ if TYPE_CHECKING: def _overrides_default(self, method_name: str) -> bool: ... def get_columns( self, connection: Connection, table_name: str, schema: Optional[str] = None, **kw: Any, ) -> List[ReflectedColumn]: """Return information about columns in ``table_name``. Given a :class:`_engine.Connection`, a string ``table_name``, and an optional string ``schema``, return column information as a list of dictionaries corresponding to the :class:`.ReflectedColumn` dictionary. This is an internal dialect method. Applications should use :meth:`.Inspector.get_columns`. """ raise NotImplementedError() def get_multi_columns( self, connection: Connection, *, schema: Optional[str] = None, filter_names: Optional[Collection[str]] = None, **kw: Any, ) -> Iterable[Tuple[TableKey, List[ReflectedColumn]]]: """Return information about columns in all tables in the given ``schema``. This is an internal dialect method. Applications should use :meth:`.Inspector.get_multi_columns`. .. note:: The :class:`_engine.DefaultDialect` provides a default implementation that will call the single table method for each object returned by :meth:`Dialect.get_table_names`, :meth:`Dialect.get_view_names` or :meth:`Dialect.get_materialized_view_names` depending on the provided ``kind``. Dialects that want to support a faster implementation should implement this method. .. versionadded:: 2.0 """ raise NotImplementedError() def get_pk_constraint( self, connection: Connection, table_name: str, schema: Optional[str] = None, **kw: Any, ) -> ReflectedPrimaryKeyConstraint: """Return information about the primary key constraint on table_name`. Given a :class:`_engine.Connection`, a string ``table_name``, and an optional string ``schema``, return primary key information as a dictionary corresponding to the :class:`.ReflectedPrimaryKeyConstraint` dictionary. This is an internal dialect method. Applications should use :meth:`.Inspector.get_pk_constraint`. """ raise NotImplementedError() def get_multi_pk_constraint( self, connection: Connection, *, schema: Optional[str] = None, filter_names: Optional[Collection[str]] = None, **kw: Any, ) -> Iterable[Tuple[TableKey, ReflectedPrimaryKeyConstraint]]: """Return information about primary key constraints in all tables in the given ``schema``. This is an internal dialect method. Applications should use :meth:`.Inspector.get_multi_pk_constraint`. .. note:: The :class:`_engine.DefaultDialect` provides a default implementation that will call the single table method for each object returned by :meth:`Dialect.get_table_names`, :meth:`Dialect.get_view_names` or :meth:`Dialect.get_materialized_view_names` depending on the provided ``kind``. Dialects that want to support a faster implementation should implement this method. .. versionadded:: 2.0 """ raise NotImplementedError() def get_foreign_keys( self, connection: Connection, table_name: str, schema: Optional[str] = None, **kw: Any, ) -> List[ReflectedForeignKeyConstraint]: """Return information about foreign_keys in ``table_name``. Given a :class:`_engine.Connection`, a string ``table_name``, and an optional string ``schema``, return foreign key information as a list of dicts corresponding to the :class:`.ReflectedForeignKeyConstraint` dictionary. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.get_foreign_keys`. """ raise NotImplementedError() def get_multi_foreign_keys( self, connection: Connection, *, schema: Optional[str] = None, filter_names: Optional[Collection[str]] = None, **kw: Any, ) -> Iterable[Tuple[TableKey, List[ReflectedForeignKeyConstraint]]]: """Return information about foreign_keys in all tables in the given ``schema``. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.get_multi_foreign_keys`. .. note:: The :class:`_engine.DefaultDialect` provides a default implementation that will call the single table method for each object returned by :meth:`Dialect.get_table_names`, :meth:`Dialect.get_view_names` or :meth:`Dialect.get_materialized_view_names` depending on the provided ``kind``. Dialects that want to support a faster implementation should implement this method. .. versionadded:: 2.0 """ raise NotImplementedError() def get_table_names( self, connection: Connection, schema: Optional[str] = None, **kw: Any ) -> List[str]: """Return a list of table names for ``schema``. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.get_table_names`. """ raise NotImplementedError() def get_temp_table_names( self, connection: Connection, schema: Optional[str] = None, **kw: Any ) -> List[str]: """Return a list of temporary table names on the given connection, if supported by the underlying backend. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.get_temp_table_names`. """ raise NotImplementedError() def get_view_names( self, connection: Connection, schema: Optional[str] = None, **kw: Any ) -> List[str]: """Return a list of all non-materialized view names available in the database. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.get_view_names`. :param schema: schema name to query, if not the default schema. """ raise NotImplementedError() def get_materialized_view_names( self, connection: Connection, schema: Optional[str] = None, **kw: Any ) -> List[str]: """Return a list of all materialized view names available in the database. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.get_materialized_view_names`. :param schema: schema name to query, if not the default schema. .. versionadded:: 2.0 """ raise NotImplementedError() def get_sequence_names( self, connection: Connection, schema: Optional[str] = None, **kw: Any ) -> List[str]: """Return a list of all sequence names available in the database. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.get_sequence_names`. :param schema: schema name to query, if not the default schema. .. versionadded:: 1.4 """ raise NotImplementedError() def get_temp_view_names( self, connection: Connection, schema: Optional[str] = None, **kw: Any ) -> List[str]: """Return a list of temporary view names on the given connection, if supported by the underlying backend. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.get_temp_view_names`. """ raise NotImplementedError() def get_schema_names(self, connection: Connection, **kw: Any) -> List[str]: """Return a list of all schema names available in the database. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.get_schema_names`. """ raise NotImplementedError() def get_view_definition( self, connection: Connection, view_name: str, schema: Optional[str] = None, **kw: Any, ) -> str: """Return plain or materialized view definition. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.get_view_definition`. Given a :class:`_engine.Connection`, a string ``view_name``, and an optional string ``schema``, return the view definition. """ raise NotImplementedError() def get_indexes( self, connection: Connection, table_name: str, schema: Optional[str] = None, **kw: Any, ) -> List[ReflectedIndex]: """Return information about indexes in ``table_name``. Given a :class:`_engine.Connection`, a string ``table_name`` and an optional string ``schema``, return index information as a list of dictionaries corresponding to the :class:`.ReflectedIndex` dictionary. This is an internal dialect method. Applications should use :meth:`.Inspector.get_indexes`. """ raise NotImplementedError() def get_multi_indexes( self, connection: Connection, *, schema: Optional[str] = None, filter_names: Optional[Collection[str]] = None, **kw: Any, ) -> Iterable[Tuple[TableKey, List[ReflectedIndex]]]: """Return information about indexes in in all tables in the given ``schema``. This is an internal dialect method. Applications should use :meth:`.Inspector.get_multi_indexes`. .. note:: The :class:`_engine.DefaultDialect` provides a default implementation that will call the single table method for each object returned by :meth:`Dialect.get_table_names`, :meth:`Dialect.get_view_names` or :meth:`Dialect.get_materialized_view_names` depending on the provided ``kind``. Dialects that want to support a faster implementation should implement this method. .. versionadded:: 2.0 """ raise NotImplementedError() def get_unique_constraints( self, connection: Connection, table_name: str, schema: Optional[str] = None, **kw: Any, ) -> List[ReflectedUniqueConstraint]: r"""Return information about unique constraints in ``table_name``. Given a string ``table_name`` and an optional string ``schema``, return unique constraint information as a list of dicts corresponding to the :class:`.ReflectedUniqueConstraint` dictionary. This is an internal dialect method. Applications should use :meth:`.Inspector.get_unique_constraints`. """ raise NotImplementedError() def get_multi_unique_constraints( self, connection: Connection, *, schema: Optional[str] = None, filter_names: Optional[Collection[str]] = None, **kw: Any, ) -> Iterable[Tuple[TableKey, List[ReflectedUniqueConstraint]]]: """Return information about unique constraints in all tables in the given ``schema``. This is an internal dialect method. Applications should use :meth:`.Inspector.get_multi_unique_constraints`. .. note:: The :class:`_engine.DefaultDialect` provides a default implementation that will call the single table method for each object returned by :meth:`Dialect.get_table_names`, :meth:`Dialect.get_view_names` or :meth:`Dialect.get_materialized_view_names` depending on the provided ``kind``. Dialects that want to support a faster implementation should implement this method. .. versionadded:: 2.0 """ raise NotImplementedError() def get_check_constraints( self, connection: Connection, table_name: str, schema: Optional[str] = None, **kw: Any, ) -> List[ReflectedCheckConstraint]: r"""Return information about check constraints in ``table_name``. Given a string ``table_name`` and an optional string ``schema``, return check constraint information as a list of dicts corresponding to the :class:`.ReflectedCheckConstraint` dictionary. This is an internal dialect method. Applications should use :meth:`.Inspector.get_check_constraints`. """ raise NotImplementedError() def get_multi_check_constraints( self, connection: Connection, *, schema: Optional[str] = None, filter_names: Optional[Collection[str]] = None, **kw: Any, ) -> Iterable[Tuple[TableKey, List[ReflectedCheckConstraint]]]: """Return information about check constraints in all tables in the given ``schema``. This is an internal dialect method. Applications should use :meth:`.Inspector.get_multi_check_constraints`. .. note:: The :class:`_engine.DefaultDialect` provides a default implementation that will call the single table method for each object returned by :meth:`Dialect.get_table_names`, :meth:`Dialect.get_view_names` or :meth:`Dialect.get_materialized_view_names` depending on the provided ``kind``. Dialects that want to support a faster implementation should implement this method. .. versionadded:: 2.0 """ raise NotImplementedError() def get_table_options( self, connection: Connection, table_name: str, schema: Optional[str] = None, **kw: Any, ) -> Dict[str, Any]: """Return a dictionary of options specified when ``table_name`` was created. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.get_table_options`. """ raise NotImplementedError() def get_multi_table_options( self, connection: Connection, *, schema: Optional[str] = None, filter_names: Optional[Collection[str]] = None, **kw: Any, ) -> Iterable[Tuple[TableKey, Dict[str, Any]]]: """Return a dictionary of options specified when the tables in the given schema were created. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.get_multi_table_options`. .. note:: The :class:`_engine.DefaultDialect` provides a default implementation that will call the single table method for each object returned by :meth:`Dialect.get_table_names`, :meth:`Dialect.get_view_names` or :meth:`Dialect.get_materialized_view_names` depending on the provided ``kind``. Dialects that want to support a faster implementation should implement this method. .. versionadded:: 2.0 """ raise NotImplementedError() def get_table_comment( self, connection: Connection, table_name: str, schema: Optional[str] = None, **kw: Any, ) -> ReflectedTableComment: r"""Return the "comment" for the table identified by ``table_name``. Given a string ``table_name`` and an optional string ``schema``, return table comment information as a dictionary corresponding to the :class:`.ReflectedTableComment` dictionary. This is an internal dialect method. Applications should use :meth:`.Inspector.get_table_comment`. :raise: ``NotImplementedError`` for dialects that don't support comments. .. versionadded:: 1.2 """ raise NotImplementedError() def get_multi_table_comment( self, connection: Connection, *, schema: Optional[str] = None, filter_names: Optional[Collection[str]] = None, **kw: Any, ) -> Iterable[Tuple[TableKey, ReflectedTableComment]]: """Return information about the table comment in all tables in the given ``schema``. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.get_multi_table_comment`. .. note:: The :class:`_engine.DefaultDialect` provides a default implementation that will call the single table method for each object returned by :meth:`Dialect.get_table_names`, :meth:`Dialect.get_view_names` or :meth:`Dialect.get_materialized_view_names` depending on the provided ``kind``. Dialects that want to support a faster implementation should implement this method. .. versionadded:: 2.0 """ raise NotImplementedError() def normalize_name(self, name: str) -> str: """convert the given name to lowercase if it is detected as case insensitive. This method is only used if the dialect defines requires_name_normalize=True. """ raise NotImplementedError() def denormalize_name(self, name: str) -> str: """convert the given name to a case insensitive identifier for the backend if it is an all-lowercase name. This method is only used if the dialect defines requires_name_normalize=True. """ raise NotImplementedError() def has_table( self, connection: Connection, table_name: str, schema: Optional[str] = None, **kw: Any, ) -> bool: """For internal dialect use, check the existence of a particular table or view in the database. Given a :class:`_engine.Connection` object, a string table_name and optional schema name, return True if the given table exists in the database, False otherwise. This method serves as the underlying implementation of the public facing :meth:`.Inspector.has_table` method, and is also used internally to implement the "checkfirst" behavior for methods like :meth:`_schema.Table.create` and :meth:`_schema.MetaData.create_all`. .. note:: This method is used internally by SQLAlchemy, and is published so that third-party dialects may provide an implementation. It is **not** the public API for checking for table presence. Please use the :meth:`.Inspector.has_table` method. .. versionchanged:: 2.0:: :meth:`_engine.Dialect.has_table` now formally supports checking for additional table-like objects: * any type of views (plain or materialized) * temporary tables of any kind Previously, these two checks were not formally specified and different dialects would vary in their behavior. The dialect testing suite now includes tests for all of these object types, and dialects to the degree that the backing database supports views or temporary tables should seek to support locating these objects for full compliance. """ raise NotImplementedError() def has_index( self, connection: Connection, table_name: str, index_name: str, schema: Optional[str] = None, **kw: Any, ) -> bool: """Check the existence of a particular index name in the database. Given a :class:`_engine.Connection` object, a string ``table_name`` and string index name, return ``True`` if an index of the given name on the given table exists, ``False`` otherwise. The :class:`.DefaultDialect` implements this in terms of the :meth:`.Dialect.has_table` and :meth:`.Dialect.get_indexes` methods, however dialects can implement a more performant version. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.has_index`. .. versionadded:: 1.4 """ raise NotImplementedError() def has_sequence( self, connection: Connection, sequence_name: str, schema: Optional[str] = None, **kw: Any, ) -> bool: """Check the existence of a particular sequence in the database. Given a :class:`_engine.Connection` object and a string `sequence_name`, return ``True`` if the given sequence exists in the database, ``False`` otherwise. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.has_sequence`. """ raise NotImplementedError() def has_schema( self, connection: Connection, schema_name: str, **kw: Any ) -> bool: """Check the existence of a particular schema name in the database. Given a :class:`_engine.Connection` object, a string ``schema_name``, return ``True`` if a schema of the given exists, ``False`` otherwise. The :class:`.DefaultDialect` implements this by checking the presence of ``schema_name`` among the schemas returned by :meth:`.Dialect.get_schema_names`, however dialects can implement a more performant version. This is an internal dialect method. Applications should use :meth:`_engine.Inspector.has_schema`. .. versionadded:: 2.0 """ raise NotImplementedError() def _get_server_version_info(self, connection: Connection) -> Any: """Retrieve the server version info from the given connection. This is used by the default implementation to populate the "server_version_info" attribute and is called exactly once upon first connect. """ raise NotImplementedError() def _get_default_schema_name(self, connection: Connection) -> str: """Return the string name of the currently selected schema from the given connection. This is used by the default implementation to populate the "default_schema_name" attribute and is called exactly once upon first connect. """ raise NotImplementedError() def do_begin(self, dbapi_connection: PoolProxiedConnection) -> None: """Provide an implementation of ``connection.begin()``, given a DB-API connection. The DBAPI has no dedicated "begin" method and it is expected that transactions are implicit. This hook is provided for those DBAPIs that might need additional help in this area. :param dbapi_connection: a DBAPI connection, typically proxied within a :class:`.ConnectionFairy`. """ raise NotImplementedError() def do_rollback(self, dbapi_connection: PoolProxiedConnection) -> None: """Provide an implementation of ``connection.rollback()``, given a DB-API connection. :param dbapi_connection: a DBAPI connection, typically proxied within a :class:`.ConnectionFairy`. """ raise NotImplementedError() def do_commit(self, dbapi_connection: PoolProxiedConnection) -> None: """Provide an implementation of ``connection.commit()``, given a DB-API connection. :param dbapi_connection: a DBAPI connection, typically proxied within a :class:`.ConnectionFairy`. """ raise NotImplementedError() def do_terminate(self, dbapi_connection: DBAPIConnection) -> None: """Provide an implementation of ``connection.close()`` that tries as much as possible to not block, given a DBAPI connection. In the vast majority of cases this just calls .close(), however for some asyncio dialects may call upon different API features. This hook is called by the :class:`_pool.Pool` when a connection is being recycled or has been invalidated. .. versionadded:: 1.4.41 """ raise NotImplementedError() def do_close(self, dbapi_connection: DBAPIConnection) -> None: """Provide an implementation of ``connection.close()``, given a DBAPI connection. This hook is called by the :class:`_pool.Pool` when a connection has been detached from the pool, or is being returned beyond the normal capacity of the pool. """ raise NotImplementedError() def _do_ping_w_event(self, dbapi_connection: DBAPIConnection) -> bool: raise NotImplementedError() def do_ping(self, dbapi_connection: DBAPIConnection) -> bool: """ping the DBAPI connection and return True if the connection is usable.""" raise NotImplementedError() def do_set_input_sizes( self, cursor: DBAPICursor, list_of_tuples: _GenericSetInputSizesType, context: ExecutionContext, ) -> Any: """invoke the cursor.setinputsizes() method with appropriate arguments This hook is called if the :attr:`.Dialect.bind_typing` attribute is set to the :attr:`.BindTyping.SETINPUTSIZES` value. Parameter data is passed in a list of tuples (paramname, dbtype, sqltype), where ``paramname`` is the key of the parameter in the statement, ``dbtype`` is the DBAPI datatype and ``sqltype`` is the SQLAlchemy type. The order of tuples is in the correct parameter order. .. versionadded:: 1.4 .. versionchanged:: 2.0 - setinputsizes mode is now enabled by setting :attr:`.Dialect.bind_typing` to :attr:`.BindTyping.SETINPUTSIZES`. Dialects which accept a ``use_setinputsizes`` parameter should set this value appropriately. """ raise NotImplementedError() def create_xid(self) -> Any: """Create a two-phase transaction ID. This id will be passed to do_begin_twophase(), do_rollback_twophase(), do_commit_twophase(). Its format is unspecified. """ raise NotImplementedError() def do_savepoint(self, connection: Connection, name: str) -> None: """Create a savepoint with the given name. :param connection: a :class:`_engine.Connection`. :param name: savepoint name. """ raise NotImplementedError() def do_rollback_to_savepoint( self, connection: Connection, name: str ) -> None: """Rollback a connection to the named savepoint. :param connection: a :class:`_engine.Connection`. :param name: savepoint name. """ raise NotImplementedError() def do_release_savepoint(self, connection: Connection, name: str) -> None: """Release the named savepoint on a connection. :param connection: a :class:`_engine.Connection`. :param name: savepoint name. """ raise NotImplementedError() def do_begin_twophase(self, connection: Connection, xid: Any) -> None: """Begin a two phase transaction on the given connection. :param connection: a :class:`_engine.Connection`. :param xid: xid """ raise NotImplementedError() def do_prepare_twophase(self, connection: Connection, xid: Any) -> None: """Prepare a two phase transaction on the given connection. :param connection: a :class:`_engine.Connection`. :param xid: xid """ raise NotImplementedError() def do_rollback_twophase( self, connection: Connection, xid: Any, is_prepared: bool = True, recover: bool = False, ) -> None: """Rollback a two phase transaction on the given connection. :param connection: a :class:`_engine.Connection`. :param xid: xid :param is_prepared: whether or not :meth:`.TwoPhaseTransaction.prepare` was called. :param recover: if the recover flag was passed. """ raise NotImplementedError() def do_commit_twophase( self, connection: Connection, xid: Any, is_prepared: bool = True, recover: bool = False, ) -> None: """Commit a two phase transaction on the given connection. :param connection: a :class:`_engine.Connection`. :param xid: xid :param is_prepared: whether or not :meth:`.TwoPhaseTransaction.prepare` was called. :param recover: if the recover flag was passed. """ raise NotImplementedError() def do_recover_twophase(self, connection: Connection) -> List[Any]: """Recover list of uncommitted prepared two phase transaction identifiers on the given connection. :param connection: a :class:`_engine.Connection`. """ raise NotImplementedError() def _deliver_insertmanyvalues_batches( self, connection: Connection, cursor: DBAPICursor, statement: str, parameters: _DBAPIMultiExecuteParams, generic_setinputsizes: Optional[_GenericSetInputSizesType], context: ExecutionContext, ) -> Iterator[_InsertManyValuesBatch]: """convert executemany parameters for an INSERT into an iterator of statement/single execute values, used by the insertmanyvalues feature. """ raise NotImplementedError() def do_executemany( self, cursor: DBAPICursor, statement: str, parameters: _DBAPIMultiExecuteParams, context: Optional[ExecutionContext] = None, ) -> None: """Provide an implementation of ``cursor.executemany(statement, parameters)``.""" raise NotImplementedError() def do_execute( self, cursor: DBAPICursor, statement: str, parameters: Optional[_DBAPISingleExecuteParams], context: Optional[ExecutionContext] = None, ) -> None: """Provide an implementation of ``cursor.execute(statement, parameters)``.""" raise NotImplementedError() def do_execute_no_params( self, cursor: DBAPICursor, statement: str, context: Optional[ExecutionContext] = None, ) -> None: """Provide an implementation of ``cursor.execute(statement)``. The parameter collection should not be sent. """ raise NotImplementedError() def is_disconnect( self, e: Exception, connection: Optional[Union[PoolProxiedConnection, DBAPIConnection]], cursor: Optional[DBAPICursor], ) -> bool: """Return True if the given DB-API error indicates an invalid connection""" raise NotImplementedError() def connect(self, *cargs: Any, **cparams: Any) -> DBAPIConnection: r"""Establish a connection using this dialect's DBAPI. The default implementation of this method is:: def connect(self, *cargs, **cparams): return self.dbapi.connect(*cargs, **cparams) The ``*cargs, **cparams`` parameters are generated directly from this dialect's :meth:`.Dialect.create_connect_args` method. This method may be used for dialects that need to perform programmatic per-connection steps when a new connection is procured from the DBAPI. :param \*cargs: positional parameters returned from the :meth:`.Dialect.create_connect_args` method :param \*\*cparams: keyword parameters returned from the :meth:`.Dialect.create_connect_args` method. :return: a DBAPI connection, typically from the :pep:`249` module level ``.connect()`` function. .. seealso:: :meth:`.Dialect.create_connect_args` :meth:`.Dialect.on_connect` """ raise NotImplementedError() def on_connect_url(self, url: URL) -> Optional[Callable[[Any], Any]]: """return a callable which sets up a newly created DBAPI connection. This method is a new hook that supersedes the :meth:`_engine.Dialect.on_connect` method when implemented by a dialect. When not implemented by a dialect, it invokes the :meth:`_engine.Dialect.on_connect` method directly to maintain compatibility with existing dialects. There is no deprecation for :meth:`_engine.Dialect.on_connect` expected. The callable should accept a single argument "conn" which is the DBAPI connection itself. The inner callable has no return value. E.g.:: class MyDialect(default.DefaultDialect): # ... def on_connect_url(self, url): def do_on_connect(connection): connection.execute("SET SPECIAL FLAGS etc") return do_on_connect This is used to set dialect-wide per-connection options such as isolation modes, Unicode modes, etc. This method differs from :meth:`_engine.Dialect.on_connect` in that it is passed the :class:`_engine.URL` object that's relevant to the connect args. Normally the only way to get this is from the :meth:`_engine.Dialect.on_connect` hook is to look on the :class:`_engine.Engine` itself, however this URL object may have been replaced by plugins. .. note:: The default implementation of :meth:`_engine.Dialect.on_connect_url` is to invoke the :meth:`_engine.Dialect.on_connect` method. Therefore if a dialect implements this method, the :meth:`_engine.Dialect.on_connect` method **will not be called** unless the overriding dialect calls it directly from here. .. versionadded:: 1.4.3 added :meth:`_engine.Dialect.on_connect_url` which normally calls into :meth:`_engine.Dialect.on_connect`. :param url: a :class:`_engine.URL` object representing the :class:`_engine.URL` that was passed to the :meth:`_engine.Dialect.create_connect_args` method. :return: a callable that accepts a single DBAPI connection as an argument, or None. .. seealso:: :meth:`_engine.Dialect.on_connect` """ return self.on_connect() def on_connect(self) -> Optional[Callable[[Any], Any]]: """return a callable which sets up a newly created DBAPI connection. The callable should accept a single argument "conn" which is the DBAPI connection itself. The inner callable has no return value. E.g.:: class MyDialect(default.DefaultDialect): # ... def on_connect(self): def do_on_connect(connection): connection.execute("SET SPECIAL FLAGS etc") return do_on_connect This is used to set dialect-wide per-connection options such as isolation modes, Unicode modes, etc. The "do_on_connect" callable is invoked by using the :meth:`_events.PoolEvents.connect` event hook, then unwrapping the DBAPI connection and passing it into the callable. .. versionchanged:: 1.4 the on_connect hook is no longer called twice for the first connection of a dialect. The on_connect hook is still called before the :meth:`_engine.Dialect.initialize` method however. .. versionchanged:: 1.4.3 the on_connect hook is invoked from a new method on_connect_url that passes the URL that was used to create the connect args. Dialects can implement on_connect_url instead of on_connect if they need the URL object that was used for the connection in order to get additional context. If None is returned, no event listener is generated. :return: a callable that accepts a single DBAPI connection as an argument, or None. .. seealso:: :meth:`.Dialect.connect` - allows the DBAPI ``connect()`` sequence itself to be controlled. :meth:`.Dialect.on_connect_url` - supersedes :meth:`.Dialect.on_connect` to also receive the :class:`_engine.URL` object in context. """ return None def reset_isolation_level(self, dbapi_connection: DBAPIConnection) -> None: """Given a DBAPI connection, revert its isolation to the default. Note that this is a dialect-level method which is used as part of the implementation of the :class:`_engine.Connection` and :class:`_engine.Engine` isolation level facilities; these APIs should be preferred for most typical use cases. .. seealso:: :meth:`_engine.Connection.get_isolation_level` - view current level :attr:`_engine.Connection.default_isolation_level` - view default level :paramref:`.Connection.execution_options.isolation_level` - set per :class:`_engine.Connection` isolation level :paramref:`_sa.create_engine.isolation_level` - set per :class:`_engine.Engine` isolation level """ raise NotImplementedError() def set_isolation_level( self, dbapi_connection: DBAPIConnection, level: IsolationLevel ) -> None: """Given a DBAPI connection, set its isolation level. Note that this is a dialect-level method which is used as part of the implementation of the :class:`_engine.Connection` and :class:`_engine.Engine` isolation level facilities; these APIs should be preferred for most typical use cases. If the dialect also implements the :meth:`.Dialect.get_isolation_level_values` method, then the given level is guaranteed to be one of the string names within that sequence, and the method will not need to anticipate a lookup failure. .. seealso:: :meth:`_engine.Connection.get_isolation_level` - view current level :attr:`_engine.Connection.default_isolation_level` - view default level :paramref:`.Connection.execution_options.isolation_level` - set per :class:`_engine.Connection` isolation level :paramref:`_sa.create_engine.isolation_level` - set per :class:`_engine.Engine` isolation level """ raise NotImplementedError() def get_isolation_level( self, dbapi_connection: DBAPIConnection ) -> IsolationLevel: """Given a DBAPI connection, return its isolation level. When working with a :class:`_engine.Connection` object, the corresponding DBAPI connection may be procured using the :attr:`_engine.Connection.connection` accessor. Note that this is a dialect-level method which is used as part of the implementation of the :class:`_engine.Connection` and :class:`_engine.Engine` isolation level facilities; these APIs should be preferred for most typical use cases. .. seealso:: :meth:`_engine.Connection.get_isolation_level` - view current level :attr:`_engine.Connection.default_isolation_level` - view default level :paramref:`.Connection.execution_options.isolation_level` - set per :class:`_engine.Connection` isolation level :paramref:`_sa.create_engine.isolation_level` - set per :class:`_engine.Engine` isolation level """ raise NotImplementedError() def get_default_isolation_level( self, dbapi_conn: DBAPIConnection ) -> IsolationLevel: """Given a DBAPI connection, return its isolation level, or a default isolation level if one cannot be retrieved. This method may only raise NotImplementedError and **must not raise any other exception**, as it is used implicitly upon first connect. The method **must return a value** for a dialect that supports isolation level settings, as this level is what will be reverted towards when a per-connection isolation level change is made. The method defaults to using the :meth:`.Dialect.get_isolation_level` method unless overridden by a dialect. .. versionadded:: 1.3.22 """ raise NotImplementedError() def get_isolation_level_values( self, dbapi_conn: DBAPIConnection ) -> Sequence[IsolationLevel]: """return a sequence of string isolation level names that are accepted by this dialect. The available names should use the following conventions: * use UPPERCASE names. isolation level methods will accept lowercase names but these are normalized into UPPERCASE before being passed along to the dialect. * separate words should be separated by spaces, not underscores, e.g. ``REPEATABLE READ``. isolation level names will have underscores converted to spaces before being passed along to the dialect. * The names for the four standard isolation names to the extent that they are supported by the backend should be ``READ UNCOMMITTED``, ``READ COMMITTED``, ``REPEATABLE READ``, ``SERIALIZABLE`` * if the dialect supports an autocommit option it should be provided using the isolation level name ``AUTOCOMMIT``. * Other isolation modes may also be present, provided that they are named in UPPERCASE and use spaces not underscores. This function is used so that the default dialect can check that a given isolation level parameter is valid, else raises an :class:`_exc.ArgumentError`. A DBAPI connection is passed to the method, in the unlikely event that the dialect needs to interrogate the connection itself to determine this list, however it is expected that most backends will return a hardcoded list of values. If the dialect supports "AUTOCOMMIT", that value should also be present in the sequence returned. The method raises ``NotImplementedError`` by default. If a dialect does not implement this method, then the default dialect will not perform any checking on a given isolation level value before passing it onto the :meth:`.Dialect.set_isolation_level` method. This is to allow backwards-compatibility with third party dialects that may not yet be implementing this method. .. versionadded:: 2.0 """ raise NotImplementedError() def _assert_and_set_isolation_level( self, dbapi_conn: DBAPIConnection, level: IsolationLevel ) -> None: raise NotImplementedError() @classmethod def get_dialect_cls(cls, url: URL) -> Type[Dialect]: """Given a URL, return the :class:`.Dialect` that will be used. This is a hook that allows an external plugin to provide functionality around an existing dialect, by allowing the plugin to be loaded from the url based on an entrypoint, and then the plugin returns the actual dialect to be used. By default this just returns the cls. """ return cls @classmethod def get_async_dialect_cls(cls, url: URL) -> Type[Dialect]: """Given a URL, return the :class:`.Dialect` that will be used by an async engine. By default this is an alias of :meth:`.Dialect.get_dialect_cls` and just returns the cls. It may be used if a dialect provides both a sync and async version under the same name, like the ``psycopg`` driver. .. versionadded:: 2 .. seealso:: :meth:`.Dialect.get_dialect_cls` """ return cls.get_dialect_cls(url) @classmethod def load_provisioning(cls) -> None: """set up the provision.py module for this dialect. For dialects that include a provision.py module that sets up provisioning followers, this method should initiate that process. A typical implementation would be:: @classmethod def load_provisioning(cls): __import__("mydialect.provision") The default method assumes a module named ``provision.py`` inside the owning package of the current dialect, based on the ``__module__`` attribute:: @classmethod def load_provisioning(cls): package = ".".join(cls.__module__.split(".")[0:-1]) try: __import__(package + ".provision") except ImportError: pass .. versionadded:: 1.3.14 """ @classmethod def engine_created(cls, engine: Engine) -> None: """A convenience hook called before returning the final :class:`_engine.Engine`. If the dialect returned a different class from the :meth:`.get_dialect_cls` method, then the hook is called on both classes, first on the dialect class returned by the :meth:`.get_dialect_cls` method and then on the class on which the method was called. The hook should be used by dialects and/or wrappers to apply special events to the engine or its components. In particular, it allows a dialect-wrapping class to apply dialect-level events. """ def get_driver_connection(self, connection: DBAPIConnection) -> Any: """Returns the connection object as returned by the external driver package. For normal dialects that use a DBAPI compliant driver this call will just return the ``connection`` passed as argument. For dialects that instead adapt a non DBAPI compliant driver, like when adapting an asyncio driver, this call will return the connection-like object as returned by the driver. .. versionadded:: 1.4.24 """ raise NotImplementedError() def set_engine_execution_options( self, engine: Engine, opts: CoreExecuteOptionsParameter ) -> None: """Establish execution options for a given engine. This is implemented by :class:`.DefaultDialect` to establish event hooks for new :class:`.Connection` instances created by the given :class:`.Engine` which will then invoke the :meth:`.Dialect.set_connection_execution_options` method for that connection. """ raise NotImplementedError() def set_connection_execution_options( self, connection: Connection, opts: CoreExecuteOptionsParameter ) -> None: """Establish execution options for a given connection. This is implemented by :class:`.DefaultDialect` in order to implement the :paramref:`_engine.Connection.execution_options.isolation_level` execution option. Dialects can intercept various execution options which may need to modify state on a particular DBAPI connection. .. versionadded:: 1.4 """ raise NotImplementedError() def get_dialect_pool_class(self, url: URL) -> Type[Pool]: """return a Pool class to use for a given URL""" raise NotImplementedError() def validate_identifier(self, ident: str) -> None: """Validates an identifier name, raising an exception if invalid""" class CreateEnginePlugin: """A set of hooks intended to augment the construction of an :class:`_engine.Engine` object based on entrypoint names in a URL. The purpose of :class:`_engine.CreateEnginePlugin` is to allow third-party systems to apply engine, pool and dialect level event listeners without the need for the target application to be modified; instead, the plugin names can be added to the database URL. Target applications for :class:`_engine.CreateEnginePlugin` include: * connection and SQL performance tools, e.g. which use events to track number of checkouts and/or time spent with statements * connectivity plugins such as proxies A rudimentary :class:`_engine.CreateEnginePlugin` that attaches a logger to an :class:`_engine.Engine` object might look like:: import logging from sqlalchemy.engine import CreateEnginePlugin from sqlalchemy import event class LogCursorEventsPlugin(CreateEnginePlugin): def __init__(self, url, kwargs): # consume the parameter "log_cursor_logging_name" from the # URL query logging_name = url.query.get( "log_cursor_logging_name", "log_cursor" ) self.log = logging.getLogger(logging_name) def update_url(self, url): "update the URL to one that no longer includes our parameters" return url.difference_update_query(["log_cursor_logging_name"]) def engine_created(self, engine): "attach an event listener after the new Engine is constructed" event.listen(engine, "before_cursor_execute", self._log_event) def _log_event( self, conn, cursor, statement, parameters, context, executemany, ): self.log.info("Plugin logged cursor event: %s", statement) Plugins are registered using entry points in a similar way as that of dialects:: entry_points = { "sqlalchemy.plugins": [ "log_cursor_plugin = myapp.plugins:LogCursorEventsPlugin" ] } A plugin that uses the above names would be invoked from a database URL as in:: from sqlalchemy import create_engine engine = create_engine( "mysql+pymysql://scott:tiger@localhost/test?" "plugin=log_cursor_plugin&log_cursor_logging_name=mylogger" ) The ``plugin`` URL parameter supports multiple instances, so that a URL may specify multiple plugins; they are loaded in the order stated in the URL:: engine = create_engine( "mysql+pymysql://scott:tiger@localhost/test?" "plugin=plugin_one&plugin=plugin_twp&plugin=plugin_three" ) The plugin names may also be passed directly to :func:`_sa.create_engine` using the :paramref:`_sa.create_engine.plugins` argument:: engine = create_engine( "mysql+pymysql://scott:tiger@localhost/test", plugins=["myplugin"] ) .. versionadded:: 1.2.3 plugin names can also be specified to :func:`_sa.create_engine` as a list A plugin may consume plugin-specific arguments from the :class:`_engine.URL` object as well as the ``kwargs`` dictionary, which is the dictionary of arguments passed to the :func:`_sa.create_engine` call. "Consuming" these arguments includes that they must be removed when the plugin initializes, so that the arguments are not passed along to the :class:`_engine.Dialect` constructor, where they will raise an :class:`_exc.ArgumentError` because they are not known by the dialect. As of version 1.4 of SQLAlchemy, arguments should continue to be consumed from the ``kwargs`` dictionary directly, by removing the values with a method such as ``dict.pop``. Arguments from the :class:`_engine.URL` object should be consumed by implementing the :meth:`_engine.CreateEnginePlugin.update_url` method, returning a new copy of the :class:`_engine.URL` with plugin-specific parameters removed:: class MyPlugin(CreateEnginePlugin): def __init__(self, url, kwargs): self.my_argument_one = url.query["my_argument_one"] self.my_argument_two = url.query["my_argument_two"] self.my_argument_three = kwargs.pop("my_argument_three", None) def update_url(self, url): return url.difference_update_query( ["my_argument_one", "my_argument_two"] ) Arguments like those illustrated above would be consumed from a :func:`_sa.create_engine` call such as:: from sqlalchemy import create_engine engine = create_engine( "mysql+pymysql://scott:tiger@localhost/test?" "plugin=myplugin&my_argument_one=foo&my_argument_two=bar", my_argument_three="bat", ) .. versionchanged:: 1.4 The :class:`_engine.URL` object is now immutable; a :class:`_engine.CreateEnginePlugin` that needs to alter the :class:`_engine.URL` should implement the newly added :meth:`_engine.CreateEnginePlugin.update_url` method, which is invoked after the plugin is constructed. For migration, construct the plugin in the following way, checking for the existence of the :meth:`_engine.CreateEnginePlugin.update_url` method to detect which version is running:: class MyPlugin(CreateEnginePlugin): def __init__(self, url, kwargs): if hasattr(CreateEnginePlugin, "update_url"): # detect the 1.4 API self.my_argument_one = url.query["my_argument_one"] self.my_argument_two = url.query["my_argument_two"] else: # detect the 1.3 and earlier API - mutate the # URL directly self.my_argument_one = url.query.pop("my_argument_one") self.my_argument_two = url.query.pop("my_argument_two") self.my_argument_three = kwargs.pop("my_argument_three", None) def update_url(self, url): # this method is only called in the 1.4 version return url.difference_update_query( ["my_argument_one", "my_argument_two"] ) .. seealso:: :ref:`change_5526` - overview of the :class:`_engine.URL` change which also includes notes regarding :class:`_engine.CreateEnginePlugin`. When the engine creation process completes and produces the :class:`_engine.Engine` object, it is again passed to the plugin via the :meth:`_engine.CreateEnginePlugin.engine_created` hook. In this hook, additional changes can be made to the engine, most typically involving setup of events (e.g. those defined in :ref:`core_event_toplevel`). """ # noqa: E501 def __init__(self, url: URL, kwargs: Dict[str, Any]): """Construct a new :class:`.CreateEnginePlugin`. The plugin object is instantiated individually for each call to :func:`_sa.create_engine`. A single :class:`_engine. Engine` will be passed to the :meth:`.CreateEnginePlugin.engine_created` method corresponding to this URL. :param url: the :class:`_engine.URL` object. The plugin may inspect the :class:`_engine.URL` for arguments. Arguments used by the plugin should be removed, by returning an updated :class:`_engine.URL` from the :meth:`_engine.CreateEnginePlugin.update_url` method. .. versionchanged:: 1.4 The :class:`_engine.URL` object is now immutable, so a :class:`_engine.CreateEnginePlugin` that needs to alter the :class:`_engine.URL` object should implement the :meth:`_engine.CreateEnginePlugin.update_url` method. :param kwargs: The keyword arguments passed to :func:`_sa.create_engine`. """ self.url = url def update_url(self, url: URL) -> URL: """Update the :class:`_engine.URL`. A new :class:`_engine.URL` should be returned. This method is typically used to consume configuration arguments from the :class:`_engine.URL` which must be removed, as they will not be recognized by the dialect. The :meth:`_engine.URL.difference_update_query` method is available to remove these arguments. See the docstring at :class:`_engine.CreateEnginePlugin` for an example. .. versionadded:: 1.4 """ raise NotImplementedError() def handle_dialect_kwargs( self, dialect_cls: Type[Dialect], dialect_args: Dict[str, Any] ) -> None: """parse and modify dialect kwargs""" def handle_pool_kwargs( self, pool_cls: Type[Pool], pool_args: Dict[str, Any] ) -> None: """parse and modify pool kwargs""" def engine_created(self, engine: Engine) -> None: """Receive the :class:`_engine.Engine` object when it is fully constructed. The plugin may make additional changes to the engine, such as registering engine or connection pool events. """ class ExecutionContext: """A messenger object for a Dialect that corresponds to a single execution. """ engine: Engine """engine which the Connection is associated with""" connection: Connection """Connection object which can be freely used by default value generators to execute SQL. This Connection should reference the same underlying connection/transactional resources of root_connection.""" root_connection: Connection """Connection object which is the source of this ExecutionContext.""" dialect: Dialect """dialect which created this ExecutionContext.""" cursor: DBAPICursor """DB-API cursor procured from the connection""" compiled: Optional[Compiled] """if passed to constructor, sqlalchemy.engine.base.Compiled object being executed""" statement: str """string version of the statement to be executed. Is either passed to the constructor, or must be created from the sql.Compiled object by the time pre_exec() has completed.""" invoked_statement: Optional[Executable] """The Executable statement object that was given in the first place. This should be structurally equivalent to compiled.statement, but not necessarily the same object as in a caching scenario the compiled form will have been extracted from the cache. """ parameters: _AnyMultiExecuteParams """bind parameters passed to the execute() or exec_driver_sql() methods. These are always stored as a list of parameter entries. A single-element list corresponds to a ``cursor.execute()`` call and a multiple-element list corresponds to ``cursor.executemany()``, except in the case of :attr:`.ExecuteStyle.INSERTMANYVALUES` which will use ``cursor.execute()`` one or more times. """ no_parameters: bool """True if the execution style does not use parameters""" isinsert: bool """True if the statement is an INSERT.""" isupdate: bool """True if the statement is an UPDATE.""" execute_style: ExecuteStyle """the style of DBAPI cursor method that will be used to execute a statement. .. versionadded:: 2.0 """ executemany: bool """True if the context has a list of more than one parameter set. Historically this attribute links to whether ``cursor.execute()`` or ``cursor.executemany()`` will be used. It also can now mean that "insertmanyvalues" may be used which indicates one or more ``cursor.execute()`` calls. """ prefetch_cols: util.generic_fn_descriptor[Optional[Sequence[Column[Any]]]] """a list of Column objects for which a client-side default was fired off. Applies to inserts and updates.""" postfetch_cols: util.generic_fn_descriptor[Optional[Sequence[Column[Any]]]] """a list of Column objects for which a server-side default or inline SQL expression value was fired off. Applies to inserts and updates.""" execution_options: _ExecuteOptions """Execution options associated with the current statement execution""" @classmethod def _init_ddl( cls, dialect: Dialect, connection: Connection, dbapi_connection: PoolProxiedConnection, execution_options: _ExecuteOptions, compiled_ddl: DDLCompiler, ) -> ExecutionContext: raise NotImplementedError() @classmethod def _init_compiled( cls, dialect: Dialect, connection: Connection, dbapi_connection: PoolProxiedConnection, execution_options: _ExecuteOptions, compiled: SQLCompiler, parameters: _CoreMultiExecuteParams, invoked_statement: Executable, extracted_parameters: Optional[Sequence[BindParameter[Any]]], cache_hit: CacheStats = CacheStats.CACHING_DISABLED, ) -> ExecutionContext: raise NotImplementedError() @classmethod def _init_statement( cls, dialect: Dialect, connection: Connection, dbapi_connection: PoolProxiedConnection, execution_options: _ExecuteOptions, statement: str, parameters: _DBAPIMultiExecuteParams, ) -> ExecutionContext: raise NotImplementedError() @classmethod def _init_default( cls, dialect: Dialect, connection: Connection, dbapi_connection: PoolProxiedConnection, execution_options: _ExecuteOptions, ) -> ExecutionContext: raise NotImplementedError() def _exec_default( self, column: Optional[Column[Any]], default: DefaultGenerator, type_: Optional[TypeEngine[Any]], ) -> Any: raise NotImplementedError() def _prepare_set_input_sizes( self, ) -> Optional[List[Tuple[str, Any, TypeEngine[Any]]]]: raise NotImplementedError() def _get_cache_stats(self) -> str: raise NotImplementedError() def _setup_result_proxy(self) -> CursorResult[Any]: raise NotImplementedError() def fire_sequence(self, seq: Sequence_SchemaItem, type_: Integer) -> int: """given a :class:`.Sequence`, invoke it and return the next int value""" raise NotImplementedError() def create_cursor(self) -> DBAPICursor: """Return a new cursor generated from this ExecutionContext's connection. Some dialects may wish to change the behavior of connection.cursor(), such as postgresql which may return a PG "server side" cursor. """ raise NotImplementedError() def pre_exec(self) -> None: """Called before an execution of a compiled statement. If a compiled statement was passed to this ExecutionContext, the `statement` and `parameters` datamembers must be initialized after this statement is complete. """ raise NotImplementedError() def get_out_parameter_values( self, out_param_names: Sequence[str] ) -> Sequence[Any]: """Return a sequence of OUT parameter values from a cursor. For dialects that support OUT parameters, this method will be called when there is a :class:`.SQLCompiler` object which has the :attr:`.SQLCompiler.has_out_parameters` flag set. This flag in turn will be set to True if the statement itself has :class:`.BindParameter` objects that have the ``.isoutparam`` flag set which are consumed by the :meth:`.SQLCompiler.visit_bindparam` method. If the dialect compiler produces :class:`.BindParameter` objects with ``.isoutparam`` set which are not handled by :meth:`.SQLCompiler.visit_bindparam`, it should set this flag explicitly. The list of names that were rendered for each bound parameter is passed to the method. The method should then return a sequence of values corresponding to the list of parameter objects. Unlike in previous SQLAlchemy versions, the values can be the **raw values** from the DBAPI; the execution context will apply the appropriate type handler based on what's present in self.compiled.binds and update the values. The processed dictionary will then be made available via the ``.out_parameters`` collection on the result object. Note that SQLAlchemy 1.4 has multiple kinds of result object as part of the 2.0 transition. .. versionadded:: 1.4 - added :meth:`.ExecutionContext.get_out_parameter_values`, which is invoked automatically by the :class:`.DefaultExecutionContext` when there are :class:`.BindParameter` objects with the ``.isoutparam`` flag set. This replaces the practice of setting out parameters within the now-removed ``get_result_proxy()`` method. """ raise NotImplementedError() def post_exec(self) -> None: """Called after the execution of a compiled statement. If a compiled statement was passed to this ExecutionContext, the `last_insert_ids`, `last_inserted_params`, etc. datamembers should be available after this method completes. """ raise NotImplementedError() def handle_dbapi_exception(self, e: BaseException) -> None: """Receive a DBAPI exception which occurred upon execute, result fetch, etc.""" raise NotImplementedError() def lastrow_has_defaults(self) -> bool: """Return True if the last INSERT or UPDATE row contained inlined or database-side defaults. """ raise NotImplementedError() def get_rowcount(self) -> Optional[int]: """Return the DBAPI ``cursor.rowcount`` value, or in some cases an interpreted value. See :attr:`_engine.CursorResult.rowcount` for details on this. """ raise NotImplementedError() def fetchall_for_returning(self, cursor: DBAPICursor) -> Sequence[Any]: """For a RETURNING result, deliver cursor.fetchall() from the DBAPI cursor. This is a dialect-specific hook for dialects that have special considerations when calling upon the rows delivered for a "RETURNING" statement. Default implementation is ``cursor.fetchall()``. This hook is currently used only by the :term:`insertmanyvalues` feature. Dialects that don't set ``use_insertmanyvalues=True`` don't need to consider this hook. .. versionadded:: 2.0.10 """ raise NotImplementedError() class ConnectionEventsTarget(EventTarget): """An object which can accept events from :class:`.ConnectionEvents`. Includes :class:`_engine.Connection` and :class:`_engine.Engine`. .. versionadded:: 2.0 """ dispatch: dispatcher[ConnectionEventsTarget] Connectable = ConnectionEventsTarget class ExceptionContext: """Encapsulate information about an error condition in progress. This object exists solely to be passed to the :meth:`_events.DialectEvents.handle_error` event, supporting an interface that can be extended without backwards-incompatibility. """ __slots__ = () dialect: Dialect """The :class:`_engine.Dialect` in use. This member is present for all invocations of the event hook. .. versionadded:: 2.0 """ connection: Optional[Connection] """The :class:`_engine.Connection` in use during the exception. This member is present, except in the case of a failure when first connecting. .. seealso:: :attr:`.ExceptionContext.engine` """ engine: Optional[Engine] """The :class:`_engine.Engine` in use during the exception. This member is present in all cases except for when handling an error within the connection pool "pre-ping" process. """ cursor: Optional[DBAPICursor] """The DBAPI cursor object. May be None. """ statement: Optional[str] """String SQL statement that was emitted directly to the DBAPI. May be None. """ parameters: Optional[_DBAPIAnyExecuteParams] """Parameter collection that was emitted directly to the DBAPI. May be None. """ original_exception: BaseException """The exception object which was caught. This member is always present. """ sqlalchemy_exception: Optional[StatementError] """The :class:`sqlalchemy.exc.StatementError` which wraps the original, and will be raised if exception handling is not circumvented by the event. May be None, as not all exception types are wrapped by SQLAlchemy. For DBAPI-level exceptions that subclass the dbapi's Error class, this field will always be present. """ chained_exception: Optional[BaseException] """The exception that was returned by the previous handler in the exception chain, if any. If present, this exception will be the one ultimately raised by SQLAlchemy unless a subsequent handler replaces it. May be None. """ execution_context: Optional[ExecutionContext] """The :class:`.ExecutionContext` corresponding to the execution operation in progress. This is present for statement execution operations, but not for operations such as transaction begin/end. It also is not present when the exception was raised before the :class:`.ExecutionContext` could be constructed. Note that the :attr:`.ExceptionContext.statement` and :attr:`.ExceptionContext.parameters` members may represent a different value than that of the :class:`.ExecutionContext`, potentially in the case where a :meth:`_events.ConnectionEvents.before_cursor_execute` event or similar modified the statement/parameters to be sent. May be None. """ is_disconnect: bool """Represent whether the exception as occurred represents a "disconnect" condition. This flag will always be True or False within the scope of the :meth:`_events.DialectEvents.handle_error` handler. SQLAlchemy will defer to this flag in order to determine whether or not the connection should be invalidated subsequently. That is, by assigning to this flag, a "disconnect" event which then results in a connection and pool invalidation can be invoked or prevented by changing this flag. .. note:: The pool "pre_ping" handler enabled using the :paramref:`_sa.create_engine.pool_pre_ping` parameter does **not** consult this event before deciding if the "ping" returned false, as opposed to receiving an unhandled error. For this use case, the :ref:`legacy recipe based on engine_connect() may be used <pool_disconnects_pessimistic_custom>`. A future API allow more comprehensive customization of the "disconnect" detection mechanism across all functions. """ invalidate_pool_on_disconnect: bool """Represent whether all connections in the pool should be invalidated when a "disconnect" condition is in effect. Setting this flag to False within the scope of the :meth:`_events.DialectEvents.handle_error` event will have the effect such that the full collection of connections in the pool will not be invalidated during a disconnect; only the current connection that is the subject of the error will actually be invalidated. The purpose of this flag is for custom disconnect-handling schemes where the invalidation of other connections in the pool is to be performed based on other conditions, or even on a per-connection basis. """ is_pre_ping: bool """Indicates if this error is occurring within the "pre-ping" step performed when :paramref:`_sa.create_engine.pool_pre_ping` is set to ``True``. In this mode, the :attr:`.ExceptionContext.engine` attribute will be ``None``. The dialect in use is accessible via the :attr:`.ExceptionContext.dialect` attribute. .. versionadded:: 2.0.5 """ class AdaptedConnection: """Interface of an adapted connection object to support the DBAPI protocol. Used by asyncio dialects to provide a sync-style pep-249 facade on top of the asyncio connection/cursor API provided by the driver. .. versionadded:: 1.4.24 """ __slots__ = ("_connection",) _connection: Any @property def driver_connection(self) -> Any: """The connection object as returned by the driver after a connect.""" return self._connection def run_async(self, fn: Callable[[Any], Awaitable[_T]]) -> _T: """Run the awaitable returned by the given function, which is passed the raw asyncio driver connection. This is used to invoke awaitable-only methods on the driver connection within the context of a "synchronous" method, like a connection pool event handler. E.g.:: engine = create_async_engine(...) @event.listens_for(engine.sync_engine, "connect") def register_custom_types( dbapi_connection, # ... ): dbapi_connection.run_async( lambda connection: connection.set_type_codec( "MyCustomType", encoder, decoder, ... ) ) .. versionadded:: 1.4.30 .. seealso:: :ref:`asyncio_events_run_async` """ return await_only(fn(self._connection)) def __repr__(self) -> str: return "<AdaptedConnection %s>" % self._connection sqlalchemy/engine/result.py 0000755 00000227756 15125143220 0012064 0 ustar 00 # engine/result.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """Define generic result set constructs.""" from __future__ import annotations from enum import Enum import functools import itertools import operator import typing from typing import Any from typing import Callable from typing import cast from typing import Dict from typing import Generic from typing import Iterable from typing import Iterator from typing import List from typing import Mapping from typing import NoReturn from typing import Optional from typing import overload from typing import Sequence from typing import Set from typing import Tuple from typing import TYPE_CHECKING from typing import TypeVar from typing import Union from .row import Row from .row import RowMapping from .. import exc from .. import util from ..sql.base import _generative from ..sql.base import HasMemoized from ..sql.base import InPlaceGenerative from ..util import HasMemoized_ro_memoized_attribute from ..util import NONE_SET from ..util._has_cy import HAS_CYEXTENSION from ..util.typing import Literal from ..util.typing import Self if typing.TYPE_CHECKING or not HAS_CYEXTENSION: from ._py_row import tuplegetter as tuplegetter else: from sqlalchemy.cyextension.resultproxy import tuplegetter as tuplegetter if typing.TYPE_CHECKING: from ..sql.elements import SQLCoreOperations from ..sql.type_api import _ResultProcessorType _KeyType = Union[str, "SQLCoreOperations[Any]"] _KeyIndexType = Union[_KeyType, int] # is overridden in cursor using _CursorKeyMapRecType _KeyMapRecType = Any _KeyMapType = Mapping[_KeyType, _KeyMapRecType] _RowData = Union[Row[Any], RowMapping, Any] """A generic form of "row" that accommodates for the different kinds of "rows" that different result objects return, including row, row mapping, and scalar values""" _RawRowType = Tuple[Any, ...] """represents the kind of row we get from a DBAPI cursor""" _R = TypeVar("_R", bound=_RowData) _T = TypeVar("_T", bound=Any) _TP = TypeVar("_TP", bound=Tuple[Any, ...]) _InterimRowType = Union[_R, _RawRowType] """a catchall "anything" kind of return type that can be applied across all the result types """ _InterimSupportsScalarsRowType = Union[Row[Any], Any] _ProcessorsType = Sequence[Optional["_ResultProcessorType[Any]"]] _TupleGetterType = Callable[[Sequence[Any]], Sequence[Any]] _UniqueFilterType = Callable[[Any], Any] _UniqueFilterStateType = Tuple[Set[Any], Optional[_UniqueFilterType]] class ResultMetaData: """Base for metadata about result rows.""" __slots__ = () _tuplefilter: Optional[_TupleGetterType] = None _translated_indexes: Optional[Sequence[int]] = None _unique_filters: Optional[Sequence[Callable[[Any], Any]]] = None _keymap: _KeyMapType _keys: Sequence[str] _processors: Optional[_ProcessorsType] _key_to_index: Mapping[_KeyType, int] @property def keys(self) -> RMKeyView: return RMKeyView(self) def _has_key(self, key: object) -> bool: raise NotImplementedError() def _for_freeze(self) -> ResultMetaData: raise NotImplementedError() @overload def _key_fallback( self, key: Any, err: Optional[Exception], raiseerr: Literal[True] = ... ) -> NoReturn: ... @overload def _key_fallback( self, key: Any, err: Optional[Exception], raiseerr: Literal[False] = ..., ) -> None: ... @overload def _key_fallback( self, key: Any, err: Optional[Exception], raiseerr: bool = ... ) -> Optional[NoReturn]: ... def _key_fallback( self, key: Any, err: Optional[Exception], raiseerr: bool = True ) -> Optional[NoReturn]: assert raiseerr raise KeyError(key) from err def _raise_for_ambiguous_column_name( self, rec: _KeyMapRecType ) -> NoReturn: raise NotImplementedError( "ambiguous column name logic is implemented for " "CursorResultMetaData" ) def _index_for_key( self, key: _KeyIndexType, raiseerr: bool ) -> Optional[int]: raise NotImplementedError() def _indexes_for_keys( self, keys: Sequence[_KeyIndexType] ) -> Sequence[int]: raise NotImplementedError() def _metadata_for_keys( self, keys: Sequence[_KeyIndexType] ) -> Iterator[_KeyMapRecType]: raise NotImplementedError() def _reduce(self, keys: Sequence[_KeyIndexType]) -> ResultMetaData: raise NotImplementedError() def _getter( self, key: Any, raiseerr: bool = True ) -> Optional[Callable[[Row[Any]], Any]]: index = self._index_for_key(key, raiseerr) if index is not None: return operator.itemgetter(index) else: return None def _row_as_tuple_getter( self, keys: Sequence[_KeyIndexType] ) -> _TupleGetterType: indexes = self._indexes_for_keys(keys) return tuplegetter(*indexes) def _make_key_to_index( self, keymap: Mapping[_KeyType, Sequence[Any]], index: int ) -> Mapping[_KeyType, int]: return { key: rec[index] for key, rec in keymap.items() if rec[index] is not None } def _key_not_found(self, key: Any, attr_error: bool) -> NoReturn: if key in self._keymap: # the index must be none in this case self._raise_for_ambiguous_column_name(self._keymap[key]) else: # unknown key if attr_error: try: self._key_fallback(key, None) except KeyError as ke: raise AttributeError(ke.args[0]) from ke else: self._key_fallback(key, None) @property def _effective_processors(self) -> Optional[_ProcessorsType]: if not self._processors or NONE_SET.issuperset(self._processors): return None else: return self._processors class RMKeyView(typing.KeysView[Any]): __slots__ = ("_parent", "_keys") _parent: ResultMetaData _keys: Sequence[str] def __init__(self, parent: ResultMetaData): self._parent = parent self._keys = [k for k in parent._keys if k is not None] def __len__(self) -> int: return len(self._keys) def __repr__(self) -> str: return "{0.__class__.__name__}({0._keys!r})".format(self) def __iter__(self) -> Iterator[str]: return iter(self._keys) def __contains__(self, item: Any) -> bool: if isinstance(item, int): return False # note this also includes special key fallback behaviors # which also don't seem to be tested in test_resultset right now return self._parent._has_key(item) def __eq__(self, other: Any) -> bool: return list(other) == list(self) def __ne__(self, other: Any) -> bool: return list(other) != list(self) class SimpleResultMetaData(ResultMetaData): """result metadata for in-memory collections.""" __slots__ = ( "_keys", "_keymap", "_processors", "_tuplefilter", "_translated_indexes", "_unique_filters", "_key_to_index", ) _keys: Sequence[str] def __init__( self, keys: Sequence[str], extra: Optional[Sequence[Any]] = None, _processors: Optional[_ProcessorsType] = None, _tuplefilter: Optional[_TupleGetterType] = None, _translated_indexes: Optional[Sequence[int]] = None, _unique_filters: Optional[Sequence[Callable[[Any], Any]]] = None, ): self._keys = list(keys) self._tuplefilter = _tuplefilter self._translated_indexes = _translated_indexes self._unique_filters = _unique_filters if extra: recs_names = [ ( (name,) + (extras if extras else ()), (index, name, extras), ) for index, (name, extras) in enumerate(zip(self._keys, extra)) ] else: recs_names = [ ((name,), (index, name, ())) for index, name in enumerate(self._keys) ] self._keymap = {key: rec for keys, rec in recs_names for key in keys} self._processors = _processors self._key_to_index = self._make_key_to_index(self._keymap, 0) def _has_key(self, key: object) -> bool: return key in self._keymap def _for_freeze(self) -> ResultMetaData: unique_filters = self._unique_filters if unique_filters and self._tuplefilter: unique_filters = self._tuplefilter(unique_filters) # TODO: are we freezing the result with or without uniqueness # applied? return SimpleResultMetaData( self._keys, extra=[self._keymap[key][2] for key in self._keys], _unique_filters=unique_filters, ) def __getstate__(self) -> Dict[str, Any]: return { "_keys": self._keys, "_translated_indexes": self._translated_indexes, } def __setstate__(self, state: Dict[str, Any]) -> None: if state["_translated_indexes"]: _translated_indexes = state["_translated_indexes"] _tuplefilter = tuplegetter(*_translated_indexes) else: _translated_indexes = _tuplefilter = None self.__init__( # type: ignore state["_keys"], _translated_indexes=_translated_indexes, _tuplefilter=_tuplefilter, ) def _index_for_key(self, key: Any, raiseerr: bool = True) -> int: if int in key.__class__.__mro__: key = self._keys[key] try: rec = self._keymap[key] except KeyError as ke: rec = self._key_fallback(key, ke, raiseerr) return rec[0] # type: ignore[no-any-return] def _indexes_for_keys(self, keys: Sequence[Any]) -> Sequence[int]: return [self._keymap[key][0] for key in keys] def _metadata_for_keys( self, keys: Sequence[Any] ) -> Iterator[_KeyMapRecType]: for key in keys: if int in key.__class__.__mro__: key = self._keys[key] try: rec = self._keymap[key] except KeyError as ke: rec = self._key_fallback(key, ke, True) yield rec def _reduce(self, keys: Sequence[Any]) -> ResultMetaData: try: metadata_for_keys = [ self._keymap[ self._keys[key] if int in key.__class__.__mro__ else key ] for key in keys ] except KeyError as ke: self._key_fallback(ke.args[0], ke, True) indexes: Sequence[int] new_keys: Sequence[str] extra: Sequence[Any] indexes, new_keys, extra = zip(*metadata_for_keys) if self._translated_indexes: indexes = [self._translated_indexes[idx] for idx in indexes] tup = tuplegetter(*indexes) new_metadata = SimpleResultMetaData( new_keys, extra=extra, _tuplefilter=tup, _translated_indexes=indexes, _processors=self._processors, _unique_filters=self._unique_filters, ) return new_metadata def result_tuple( fields: Sequence[str], extra: Optional[Any] = None ) -> Callable[[Iterable[Any]], Row[Any]]: parent = SimpleResultMetaData(fields, extra) return functools.partial( Row, parent, parent._effective_processors, parent._key_to_index ) # a symbol that indicates to internal Result methods that # "no row is returned". We can't use None for those cases where a scalar # filter is applied to rows. class _NoRow(Enum): _NO_ROW = 0 _NO_ROW = _NoRow._NO_ROW class ResultInternal(InPlaceGenerative, Generic[_R]): __slots__ = () _real_result: Optional[Result[Any]] = None _generate_rows: bool = True _row_logging_fn: Optional[Callable[[Any], Any]] _unique_filter_state: Optional[_UniqueFilterStateType] = None _post_creational_filter: Optional[Callable[[Any], Any]] = None _is_cursor = False _metadata: ResultMetaData _source_supports_scalars: bool def _fetchiter_impl(self) -> Iterator[_InterimRowType[Row[Any]]]: raise NotImplementedError() def _fetchone_impl( self, hard_close: bool = False ) -> Optional[_InterimRowType[Row[Any]]]: raise NotImplementedError() def _fetchmany_impl( self, size: Optional[int] = None ) -> List[_InterimRowType[Row[Any]]]: raise NotImplementedError() def _fetchall_impl(self) -> List[_InterimRowType[Row[Any]]]: raise NotImplementedError() def _soft_close(self, hard: bool = False) -> None: raise NotImplementedError() @HasMemoized_ro_memoized_attribute def _row_getter(self) -> Optional[Callable[..., _R]]: real_result: Result[Any] = ( self._real_result if self._real_result else cast("Result[Any]", self) ) if real_result._source_supports_scalars: if not self._generate_rows: return None else: _proc = Row def process_row( metadata: ResultMetaData, processors: Optional[_ProcessorsType], key_to_index: Mapping[_KeyType, int], scalar_obj: Any, ) -> Row[Any]: return _proc( metadata, processors, key_to_index, (scalar_obj,) ) else: process_row = Row # type: ignore metadata = self._metadata key_to_index = metadata._key_to_index processors = metadata._effective_processors tf = metadata._tuplefilter if tf and not real_result._source_supports_scalars: if processors: processors = tf(processors) _make_row_orig: Callable[..., _R] = functools.partial( # type: ignore # noqa E501 process_row, metadata, processors, key_to_index ) fixed_tf = tf def make_row(row: _InterimRowType[Row[Any]]) -> _R: return _make_row_orig(fixed_tf(row)) else: make_row = functools.partial( # type: ignore process_row, metadata, processors, key_to_index ) if real_result._row_logging_fn: _log_row = real_result._row_logging_fn _make_row = make_row def make_row(row: _InterimRowType[Row[Any]]) -> _R: return _log_row(_make_row(row)) # type: ignore return make_row @HasMemoized_ro_memoized_attribute def _iterator_getter(self) -> Callable[..., Iterator[_R]]: make_row = self._row_getter post_creational_filter = self._post_creational_filter if self._unique_filter_state: uniques, strategy = self._unique_strategy def iterrows(self: Result[Any]) -> Iterator[_R]: for raw_row in self._fetchiter_impl(): obj: _InterimRowType[Any] = ( make_row(raw_row) if make_row else raw_row ) hashed = strategy(obj) if strategy else obj if hashed in uniques: continue uniques.add(hashed) if post_creational_filter: obj = post_creational_filter(obj) yield obj # type: ignore else: def iterrows(self: Result[Any]) -> Iterator[_R]: for raw_row in self._fetchiter_impl(): row: _InterimRowType[Any] = ( make_row(raw_row) if make_row else raw_row ) if post_creational_filter: row = post_creational_filter(row) yield row # type: ignore return iterrows def _raw_all_rows(self) -> List[_R]: make_row = self._row_getter assert make_row is not None rows = self._fetchall_impl() return [make_row(row) for row in rows] def _allrows(self) -> List[_R]: post_creational_filter = self._post_creational_filter make_row = self._row_getter rows = self._fetchall_impl() made_rows: List[_InterimRowType[_R]] if make_row: made_rows = [make_row(row) for row in rows] else: made_rows = rows # type: ignore interim_rows: List[_R] if self._unique_filter_state: uniques, strategy = self._unique_strategy interim_rows = [ made_row # type: ignore for made_row, sig_row in [ ( made_row, strategy(made_row) if strategy else made_row, ) for made_row in made_rows ] if sig_row not in uniques and not uniques.add(sig_row) # type: ignore # noqa: E501 ] else: interim_rows = made_rows # type: ignore if post_creational_filter: interim_rows = [ post_creational_filter(row) for row in interim_rows ] return interim_rows @HasMemoized_ro_memoized_attribute def _onerow_getter( self, ) -> Callable[..., Union[Literal[_NoRow._NO_ROW], _R]]: make_row = self._row_getter post_creational_filter = self._post_creational_filter if self._unique_filter_state: uniques, strategy = self._unique_strategy def onerow(self: Result[Any]) -> Union[_NoRow, _R]: _onerow = self._fetchone_impl while True: row = _onerow() if row is None: return _NO_ROW else: obj: _InterimRowType[Any] = ( make_row(row) if make_row else row ) hashed = strategy(obj) if strategy else obj if hashed in uniques: continue else: uniques.add(hashed) if post_creational_filter: obj = post_creational_filter(obj) return obj # type: ignore else: def onerow(self: Result[Any]) -> Union[_NoRow, _R]: row = self._fetchone_impl() if row is None: return _NO_ROW else: interim_row: _InterimRowType[Any] = ( make_row(row) if make_row else row ) if post_creational_filter: interim_row = post_creational_filter(interim_row) return interim_row # type: ignore return onerow @HasMemoized_ro_memoized_attribute def _manyrow_getter(self) -> Callable[..., List[_R]]: make_row = self._row_getter post_creational_filter = self._post_creational_filter if self._unique_filter_state: uniques, strategy = self._unique_strategy def filterrows( make_row: Optional[Callable[..., _R]], rows: List[Any], strategy: Optional[Callable[[List[Any]], Any]], uniques: Set[Any], ) -> List[_R]: if make_row: rows = [make_row(row) for row in rows] if strategy: made_rows = ( (made_row, strategy(made_row)) for made_row in rows ) else: made_rows = ((made_row, made_row) for made_row in rows) return [ made_row for made_row, sig_row in made_rows if sig_row not in uniques and not uniques.add(sig_row) # type: ignore # noqa: E501 ] def manyrows( self: ResultInternal[_R], num: Optional[int] ) -> List[_R]: collect: List[_R] = [] _manyrows = self._fetchmany_impl if num is None: # if None is passed, we don't know the default # manyrows number, DBAPI has this as cursor.arraysize # different DBAPIs / fetch strategies may be different. # do a fetch to find what the number is. if there are # only fewer rows left, then it doesn't matter. real_result = ( self._real_result if self._real_result else cast("Result[Any]", self) ) if real_result._yield_per: num_required = num = real_result._yield_per else: rows = _manyrows(num) num = len(rows) assert make_row is not None collect.extend( filterrows(make_row, rows, strategy, uniques) ) num_required = num - len(collect) else: num_required = num assert num is not None while num_required: rows = _manyrows(num_required) if not rows: break collect.extend( filterrows(make_row, rows, strategy, uniques) ) num_required = num - len(collect) if post_creational_filter: collect = [post_creational_filter(row) for row in collect] return collect else: def manyrows( self: ResultInternal[_R], num: Optional[int] ) -> List[_R]: if num is None: real_result = ( self._real_result if self._real_result else cast("Result[Any]", self) ) num = real_result._yield_per rows: List[_InterimRowType[Any]] = self._fetchmany_impl(num) if make_row: rows = [make_row(row) for row in rows] if post_creational_filter: rows = [post_creational_filter(row) for row in rows] return rows # type: ignore return manyrows @overload def _only_one_row( self: ResultInternal[Row[Any]], raise_for_second_row: bool, raise_for_none: bool, scalar: Literal[True], ) -> Any: ... @overload def _only_one_row( self, raise_for_second_row: bool, raise_for_none: Literal[True], scalar: bool, ) -> _R: ... @overload def _only_one_row( self, raise_for_second_row: bool, raise_for_none: bool, scalar: bool, ) -> Optional[_R]: ... def _only_one_row( self, raise_for_second_row: bool, raise_for_none: bool, scalar: bool, ) -> Optional[_R]: onerow = self._fetchone_impl row: Optional[_InterimRowType[Any]] = onerow(hard_close=True) if row is None: if raise_for_none: raise exc.NoResultFound( "No row was found when one was required" ) else: return None if scalar and self._source_supports_scalars: self._generate_rows = False make_row = None else: make_row = self._row_getter try: row = make_row(row) if make_row else row except: self._soft_close(hard=True) raise if raise_for_second_row: if self._unique_filter_state: # for no second row but uniqueness, need to essentially # consume the entire result :( uniques, strategy = self._unique_strategy existing_row_hash = strategy(row) if strategy else row while True: next_row: Any = onerow(hard_close=True) if next_row is None: next_row = _NO_ROW break try: next_row = make_row(next_row) if make_row else next_row if strategy: assert next_row is not _NO_ROW if existing_row_hash == strategy(next_row): continue elif row == next_row: continue # here, we have a row and it's different break except: self._soft_close(hard=True) raise else: next_row = onerow(hard_close=True) if next_row is None: next_row = _NO_ROW if next_row is not _NO_ROW: self._soft_close(hard=True) raise exc.MultipleResultsFound( "Multiple rows were found when exactly one was required" if raise_for_none else "Multiple rows were found when one or none " "was required" ) else: # if we checked for second row then that would have # closed us :) self._soft_close(hard=True) if not scalar: post_creational_filter = self._post_creational_filter if post_creational_filter: row = post_creational_filter(row) if scalar and make_row: return row[0] # type: ignore else: return row # type: ignore def _iter_impl(self) -> Iterator[_R]: return self._iterator_getter(self) def _next_impl(self) -> _R: row = self._onerow_getter(self) if row is _NO_ROW: raise StopIteration() else: return row @_generative def _column_slices(self, indexes: Sequence[_KeyIndexType]) -> Self: real_result = ( self._real_result if self._real_result else cast("Result[Any]", self) ) if not real_result._source_supports_scalars or len(indexes) != 1: self._metadata = self._metadata._reduce(indexes) assert self._generate_rows return self @HasMemoized.memoized_attribute def _unique_strategy(self) -> _UniqueFilterStateType: assert self._unique_filter_state is not None uniques, strategy = self._unique_filter_state real_result = ( self._real_result if self._real_result is not None else cast("Result[Any]", self) ) if not strategy and self._metadata._unique_filters: if ( real_result._source_supports_scalars and not self._generate_rows ): strategy = self._metadata._unique_filters[0] else: filters = self._metadata._unique_filters if self._metadata._tuplefilter: filters = self._metadata._tuplefilter(filters) strategy = operator.methodcaller("_filter_on_values", filters) return uniques, strategy class _WithKeys: __slots__ = () _metadata: ResultMetaData # used mainly to share documentation on the keys method. def keys(self) -> RMKeyView: """Return an iterable view which yields the string keys that would be represented by each :class:`_engine.Row`. The keys can represent the labels of the columns returned by a core statement or the names of the orm classes returned by an orm execution. The view also can be tested for key containment using the Python ``in`` operator, which will test both for the string keys represented in the view, as well as for alternate keys such as column objects. .. versionchanged:: 1.4 a key view object is returned rather than a plain list. """ return self._metadata.keys class Result(_WithKeys, ResultInternal[Row[_TP]]): """Represent a set of database results. .. versionadded:: 1.4 The :class:`_engine.Result` object provides a completely updated usage model and calling facade for SQLAlchemy Core and SQLAlchemy ORM. In Core, it forms the basis of the :class:`_engine.CursorResult` object which replaces the previous :class:`_engine.ResultProxy` interface. When using the ORM, a higher level object called :class:`_engine.ChunkedIteratorResult` is normally used. .. note:: In SQLAlchemy 1.4 and above, this object is used for ORM results returned by :meth:`_orm.Session.execute`, which can yield instances of ORM mapped objects either individually or within tuple-like rows. Note that the :class:`_engine.Result` object does not deduplicate instances or rows automatically as is the case with the legacy :class:`_orm.Query` object. For in-Python de-duplication of instances or rows, use the :meth:`_engine.Result.unique` modifier method. .. seealso:: :ref:`tutorial_fetching_rows` - in the :doc:`/tutorial/index` """ __slots__ = ("_metadata", "__dict__") _row_logging_fn: Optional[Callable[[Row[Any]], Row[Any]]] = None _source_supports_scalars: bool = False _yield_per: Optional[int] = None _attributes: util.immutabledict[Any, Any] = util.immutabledict() def __init__(self, cursor_metadata: ResultMetaData): self._metadata = cursor_metadata def __enter__(self) -> Self: return self def __exit__(self, type_: Any, value: Any, traceback: Any) -> None: self.close() def close(self) -> None: """close this :class:`_engine.Result`. The behavior of this method is implementation specific, and is not implemented by default. The method should generally end the resources in use by the result object and also cause any subsequent iteration or row fetching to raise :class:`.ResourceClosedError`. .. versionadded:: 1.4.27 - ``.close()`` was previously not generally available for all :class:`_engine.Result` classes, instead only being available on the :class:`_engine.CursorResult` returned for Core statement executions. As most other result objects, namely the ones used by the ORM, are proxying a :class:`_engine.CursorResult` in any case, this allows the underlying cursor result to be closed from the outside facade for the case when the ORM query is using the ``yield_per`` execution option where it does not immediately exhaust and autoclose the database cursor. """ self._soft_close(hard=True) @property def _soft_closed(self) -> bool: raise NotImplementedError() @property def closed(self) -> bool: """return ``True`` if this :class:`_engine.Result` reports .closed .. versionadded:: 1.4.43 """ raise NotImplementedError() @_generative def yield_per(self, num: int) -> Self: """Configure the row-fetching strategy to fetch ``num`` rows at a time. This impacts the underlying behavior of the result when iterating over the result object, or otherwise making use of methods such as :meth:`_engine.Result.fetchone` that return one row at a time. Data from the underlying cursor or other data source will be buffered up to this many rows in memory, and the buffered collection will then be yielded out one row at a time or as many rows are requested. Each time the buffer clears, it will be refreshed to this many rows or as many rows remain if fewer remain. The :meth:`_engine.Result.yield_per` method is generally used in conjunction with the :paramref:`_engine.Connection.execution_options.stream_results` execution option, which will allow the database dialect in use to make use of a server side cursor, if the DBAPI supports a specific "server side cursor" mode separate from its default mode of operation. .. tip:: Consider using the :paramref:`_engine.Connection.execution_options.yield_per` execution option, which will simultaneously set :paramref:`_engine.Connection.execution_options.stream_results` to ensure the use of server side cursors, as well as automatically invoke the :meth:`_engine.Result.yield_per` method to establish a fixed row buffer size at once. The :paramref:`_engine.Connection.execution_options.yield_per` execution option is available for ORM operations, with :class:`_orm.Session`-oriented use described at :ref:`orm_queryguide_yield_per`. The Core-only version which works with :class:`_engine.Connection` is new as of SQLAlchemy 1.4.40. .. versionadded:: 1.4 :param num: number of rows to fetch each time the buffer is refilled. If set to a value below 1, fetches all rows for the next buffer. .. seealso:: :ref:`engine_stream_results` - describes Core behavior for :meth:`_engine.Result.yield_per` :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel` """ self._yield_per = num return self @_generative def unique(self, strategy: Optional[_UniqueFilterType] = None) -> Self: """Apply unique filtering to the objects returned by this :class:`_engine.Result`. When this filter is applied with no arguments, the rows or objects returned will filtered such that each row is returned uniquely. The algorithm used to determine this uniqueness is by default the Python hashing identity of the whole tuple. In some cases a specialized per-entity hashing scheme may be used, such as when using the ORM, a scheme is applied which works against the primary key identity of returned objects. The unique filter is applied **after all other filters**, which means if the columns returned have been refined using a method such as the :meth:`_engine.Result.columns` or :meth:`_engine.Result.scalars` method, the uniquing is applied to **only the column or columns returned**. This occurs regardless of the order in which these methods have been called upon the :class:`_engine.Result` object. The unique filter also changes the calculus used for methods like :meth:`_engine.Result.fetchmany` and :meth:`_engine.Result.partitions`. When using :meth:`_engine.Result.unique`, these methods will continue to yield the number of rows or objects requested, after uniquing has been applied. However, this necessarily impacts the buffering behavior of the underlying cursor or datasource, such that multiple underlying calls to ``cursor.fetchmany()`` may be necessary in order to accumulate enough objects in order to provide a unique collection of the requested size. :param strategy: a callable that will be applied to rows or objects being iterated, which should return an object that represents the unique value of the row. A Python ``set()`` is used to store these identities. If not passed, a default uniqueness strategy is used which may have been assembled by the source of this :class:`_engine.Result` object. """ self._unique_filter_state = (set(), strategy) return self def columns(self, *col_expressions: _KeyIndexType) -> Self: r"""Establish the columns that should be returned in each row. This method may be used to limit the columns returned as well as to reorder them. The given list of expressions are normally a series of integers or string key names. They may also be appropriate :class:`.ColumnElement` objects which correspond to a given statement construct. .. versionchanged:: 2.0 Due to a bug in 1.4, the :meth:`_engine.Result.columns` method had an incorrect behavior where calling upon the method with just one index would cause the :class:`_engine.Result` object to yield scalar values rather than :class:`_engine.Row` objects. In version 2.0, this behavior has been corrected such that calling upon :meth:`_engine.Result.columns` with a single index will produce a :class:`_engine.Result` object that continues to yield :class:`_engine.Row` objects, which include only a single column. E.g.:: statement = select(table.c.x, table.c.y, table.c.z) result = connection.execute(statement) for z, y in result.columns("z", "y"): ... Example of using the column objects from the statement itself:: for z, y in result.columns( statement.selected_columns.c.z, statement.selected_columns.c.y ): ... .. versionadded:: 1.4 :param \*col_expressions: indicates columns to be returned. Elements may be integer row indexes, string column names, or appropriate :class:`.ColumnElement` objects corresponding to a select construct. :return: this :class:`_engine.Result` object with the modifications given. """ return self._column_slices(col_expressions) @overload def scalars(self: Result[Tuple[_T]]) -> ScalarResult[_T]: ... @overload def scalars( self: Result[Tuple[_T]], index: Literal[0] ) -> ScalarResult[_T]: ... @overload def scalars(self, index: _KeyIndexType = 0) -> ScalarResult[Any]: ... def scalars(self, index: _KeyIndexType = 0) -> ScalarResult[Any]: """Return a :class:`_engine.ScalarResult` filtering object which will return single elements rather than :class:`_row.Row` objects. E.g.:: >>> result = conn.execute(text("select int_id from table")) >>> result.scalars().all() [1, 2, 3] When results are fetched from the :class:`_engine.ScalarResult` filtering object, the single column-row that would be returned by the :class:`_engine.Result` is instead returned as the column's value. .. versionadded:: 1.4 :param index: integer or row key indicating the column to be fetched from each row, defaults to ``0`` indicating the first column. :return: a new :class:`_engine.ScalarResult` filtering object referring to this :class:`_engine.Result` object. """ return ScalarResult(self, index) def _getter( self, key: _KeyIndexType, raiseerr: bool = True ) -> Optional[Callable[[Row[Any]], Any]]: """return a callable that will retrieve the given key from a :class:`_engine.Row`. """ if self._source_supports_scalars: raise NotImplementedError( "can't use this function in 'only scalars' mode" ) return self._metadata._getter(key, raiseerr) def _tuple_getter(self, keys: Sequence[_KeyIndexType]) -> _TupleGetterType: """return a callable that will retrieve the given keys from a :class:`_engine.Row`. """ if self._source_supports_scalars: raise NotImplementedError( "can't use this function in 'only scalars' mode" ) return self._metadata._row_as_tuple_getter(keys) def mappings(self) -> MappingResult: """Apply a mappings filter to returned rows, returning an instance of :class:`_engine.MappingResult`. When this filter is applied, fetching rows will return :class:`_engine.RowMapping` objects instead of :class:`_engine.Row` objects. .. versionadded:: 1.4 :return: a new :class:`_engine.MappingResult` filtering object referring to this :class:`_engine.Result` object. """ return MappingResult(self) @property def t(self) -> TupleResult[_TP]: """Apply a "typed tuple" typing filter to returned rows. The :attr:`_engine.Result.t` attribute is a synonym for calling the :meth:`_engine.Result.tuples` method. .. versionadded:: 2.0 """ return self # type: ignore def tuples(self) -> TupleResult[_TP]: """Apply a "typed tuple" typing filter to returned rows. This method returns the same :class:`_engine.Result` object at runtime, however annotates as returning a :class:`_engine.TupleResult` object that will indicate to :pep:`484` typing tools that plain typed ``Tuple`` instances are returned rather than rows. This allows tuple unpacking and ``__getitem__`` access of :class:`_engine.Row` objects to by typed, for those cases where the statement invoked itself included typing information. .. versionadded:: 2.0 :return: the :class:`_engine.TupleResult` type at typing time. .. seealso:: :attr:`_engine.Result.t` - shorter synonym :attr:`_engine.Row._t` - :class:`_engine.Row` version """ return self # type: ignore def _raw_row_iterator(self) -> Iterator[_RowData]: """Return a safe iterator that yields raw row data. This is used by the :meth:`_engine.Result.merge` method to merge multiple compatible results together. """ raise NotImplementedError() def __iter__(self) -> Iterator[Row[_TP]]: return self._iter_impl() def __next__(self) -> Row[_TP]: return self._next_impl() def partitions( self, size: Optional[int] = None ) -> Iterator[Sequence[Row[_TP]]]: """Iterate through sub-lists of rows of the size given. Each list will be of the size given, excluding the last list to be yielded, which may have a small number of rows. No empty lists will be yielded. The result object is automatically closed when the iterator is fully consumed. Note that the backend driver will usually buffer the entire result ahead of time unless the :paramref:`.Connection.execution_options.stream_results` execution option is used indicating that the driver should not pre-buffer results, if possible. Not all drivers support this option and the option is silently ignored for those who do not. When using the ORM, the :meth:`_engine.Result.partitions` method is typically more effective from a memory perspective when it is combined with use of the :ref:`yield_per execution option <orm_queryguide_yield_per>`, which instructs both the DBAPI driver to use server side cursors, if available, as well as instructs the ORM loading internals to only build a certain amount of ORM objects from a result at a time before yielding them out. .. versionadded:: 1.4 :param size: indicate the maximum number of rows to be present in each list yielded. If None, makes use of the value set by the :meth:`_engine.Result.yield_per`, method, if it were called, or the :paramref:`_engine.Connection.execution_options.yield_per` execution option, which is equivalent in this regard. If yield_per weren't set, it makes use of the :meth:`_engine.Result.fetchmany` default, which may be backend specific and not well defined. :return: iterator of lists .. seealso:: :ref:`engine_stream_results` :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel` """ getter = self._manyrow_getter while True: partition = getter(self, size) if partition: yield partition else: break def fetchall(self) -> Sequence[Row[_TP]]: """A synonym for the :meth:`_engine.Result.all` method.""" return self._allrows() def fetchone(self) -> Optional[Row[_TP]]: """Fetch one row. When all rows are exhausted, returns None. This method is provided for backwards compatibility with SQLAlchemy 1.x.x. To fetch the first row of a result only, use the :meth:`_engine.Result.first` method. To iterate through all rows, iterate the :class:`_engine.Result` object directly. :return: a :class:`_engine.Row` object if no filters are applied, or ``None`` if no rows remain. """ row = self._onerow_getter(self) if row is _NO_ROW: return None else: return row def fetchmany(self, size: Optional[int] = None) -> Sequence[Row[_TP]]: """Fetch many rows. When all rows are exhausted, returns an empty sequence. This method is provided for backwards compatibility with SQLAlchemy 1.x.x. To fetch rows in groups, use the :meth:`_engine.Result.partitions` method. :return: a sequence of :class:`_engine.Row` objects. .. seealso:: :meth:`_engine.Result.partitions` """ return self._manyrow_getter(self, size) def all(self) -> Sequence[Row[_TP]]: """Return all rows in a sequence. Closes the result set after invocation. Subsequent invocations will return an empty sequence. .. versionadded:: 1.4 :return: a sequence of :class:`_engine.Row` objects. .. seealso:: :ref:`engine_stream_results` - How to stream a large result set without loading it completely in python. """ return self._allrows() def first(self) -> Optional[Row[_TP]]: """Fetch the first row or ``None`` if no row is present. Closes the result set and discards remaining rows. .. note:: This method returns one **row**, e.g. tuple, by default. To return exactly one single scalar value, that is, the first column of the first row, use the :meth:`_engine.Result.scalar` method, or combine :meth:`_engine.Result.scalars` and :meth:`_engine.Result.first`. Additionally, in contrast to the behavior of the legacy ORM :meth:`_orm.Query.first` method, **no limit is applied** to the SQL query which was invoked to produce this :class:`_engine.Result`; for a DBAPI driver that buffers results in memory before yielding rows, all rows will be sent to the Python process and all but the first row will be discarded. .. seealso:: :ref:`migration_20_unify_select` :return: a :class:`_engine.Row` object, or None if no rows remain. .. seealso:: :meth:`_engine.Result.scalar` :meth:`_engine.Result.one` """ return self._only_one_row( raise_for_second_row=False, raise_for_none=False, scalar=False ) def one_or_none(self) -> Optional[Row[_TP]]: """Return at most one result or raise an exception. Returns ``None`` if the result has no rows. Raises :class:`.MultipleResultsFound` if multiple rows are returned. .. versionadded:: 1.4 :return: The first :class:`_engine.Row` or ``None`` if no row is available. :raises: :class:`.MultipleResultsFound` .. seealso:: :meth:`_engine.Result.first` :meth:`_engine.Result.one` """ return self._only_one_row( raise_for_second_row=True, raise_for_none=False, scalar=False ) @overload def scalar_one(self: Result[Tuple[_T]]) -> _T: ... @overload def scalar_one(self) -> Any: ... def scalar_one(self) -> Any: """Return exactly one scalar result or raise an exception. This is equivalent to calling :meth:`_engine.Result.scalars` and then :meth:`_engine.ScalarResult.one`. .. seealso:: :meth:`_engine.ScalarResult.one` :meth:`_engine.Result.scalars` """ return self._only_one_row( raise_for_second_row=True, raise_for_none=True, scalar=True ) @overload def scalar_one_or_none(self: Result[Tuple[_T]]) -> Optional[_T]: ... @overload def scalar_one_or_none(self) -> Optional[Any]: ... def scalar_one_or_none(self) -> Optional[Any]: """Return exactly one scalar result or ``None``. This is equivalent to calling :meth:`_engine.Result.scalars` and then :meth:`_engine.ScalarResult.one_or_none`. .. seealso:: :meth:`_engine.ScalarResult.one_or_none` :meth:`_engine.Result.scalars` """ return self._only_one_row( raise_for_second_row=True, raise_for_none=False, scalar=True ) def one(self) -> Row[_TP]: """Return exactly one row or raise an exception. Raises :class:`_exc.NoResultFound` if the result returns no rows, or :class:`_exc.MultipleResultsFound` if multiple rows would be returned. .. note:: This method returns one **row**, e.g. tuple, by default. To return exactly one single scalar value, that is, the first column of the first row, use the :meth:`_engine.Result.scalar_one` method, or combine :meth:`_engine.Result.scalars` and :meth:`_engine.Result.one`. .. versionadded:: 1.4 :return: The first :class:`_engine.Row`. :raises: :class:`.MultipleResultsFound`, :class:`.NoResultFound` .. seealso:: :meth:`_engine.Result.first` :meth:`_engine.Result.one_or_none` :meth:`_engine.Result.scalar_one` """ return self._only_one_row( raise_for_second_row=True, raise_for_none=True, scalar=False ) @overload def scalar(self: Result[Tuple[_T]]) -> Optional[_T]: ... @overload def scalar(self) -> Any: ... def scalar(self) -> Any: """Fetch the first column of the first row, and close the result set. Returns ``None`` if there are no rows to fetch. No validation is performed to test if additional rows remain. After calling this method, the object is fully closed, e.g. the :meth:`_engine.CursorResult.close` method will have been called. :return: a Python scalar value, or ``None`` if no rows remain. """ return self._only_one_row( raise_for_second_row=False, raise_for_none=False, scalar=True ) def freeze(self) -> FrozenResult[_TP]: """Return a callable object that will produce copies of this :class:`_engine.Result` when invoked. The callable object returned is an instance of :class:`_engine.FrozenResult`. This is used for result set caching. The method must be called on the result when it has been unconsumed, and calling the method will consume the result fully. When the :class:`_engine.FrozenResult` is retrieved from a cache, it can be called any number of times where it will produce a new :class:`_engine.Result` object each time against its stored set of rows. .. seealso:: :ref:`do_orm_execute_re_executing` - example usage within the ORM to implement a result-set cache. """ return FrozenResult(self) def merge(self, *others: Result[Any]) -> MergedResult[_TP]: """Merge this :class:`_engine.Result` with other compatible result objects. The object returned is an instance of :class:`_engine.MergedResult`, which will be composed of iterators from the given result objects. The new result will use the metadata from this result object. The subsequent result objects must be against an identical set of result / cursor metadata, otherwise the behavior is undefined. """ return MergedResult(self._metadata, (self,) + others) class FilterResult(ResultInternal[_R]): """A wrapper for a :class:`_engine.Result` that returns objects other than :class:`_engine.Row` objects, such as dictionaries or scalar objects. :class:`_engine.FilterResult` is the common base for additional result APIs including :class:`_engine.MappingResult`, :class:`_engine.ScalarResult` and :class:`_engine.AsyncResult`. """ __slots__ = ( "_real_result", "_post_creational_filter", "_metadata", "_unique_filter_state", "__dict__", ) _post_creational_filter: Optional[Callable[[Any], Any]] _real_result: Result[Any] def __enter__(self) -> Self: return self def __exit__(self, type_: Any, value: Any, traceback: Any) -> None: self._real_result.__exit__(type_, value, traceback) @_generative def yield_per(self, num: int) -> Self: """Configure the row-fetching strategy to fetch ``num`` rows at a time. The :meth:`_engine.FilterResult.yield_per` method is a pass through to the :meth:`_engine.Result.yield_per` method. See that method's documentation for usage notes. .. versionadded:: 1.4.40 - added :meth:`_engine.FilterResult.yield_per` so that the method is available on all result set implementations .. seealso:: :ref:`engine_stream_results` - describes Core behavior for :meth:`_engine.Result.yield_per` :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel` """ self._real_result = self._real_result.yield_per(num) return self def _soft_close(self, hard: bool = False) -> None: self._real_result._soft_close(hard=hard) @property def _soft_closed(self) -> bool: return self._real_result._soft_closed @property def closed(self) -> bool: """Return ``True`` if the underlying :class:`_engine.Result` reports closed .. versionadded:: 1.4.43 """ return self._real_result.closed def close(self) -> None: """Close this :class:`_engine.FilterResult`. .. versionadded:: 1.4.43 """ self._real_result.close() @property def _attributes(self) -> Dict[Any, Any]: return self._real_result._attributes def _fetchiter_impl(self) -> Iterator[_InterimRowType[Row[Any]]]: return self._real_result._fetchiter_impl() def _fetchone_impl( self, hard_close: bool = False ) -> Optional[_InterimRowType[Row[Any]]]: return self._real_result._fetchone_impl(hard_close=hard_close) def _fetchall_impl(self) -> List[_InterimRowType[Row[Any]]]: return self._real_result._fetchall_impl() def _fetchmany_impl( self, size: Optional[int] = None ) -> List[_InterimRowType[Row[Any]]]: return self._real_result._fetchmany_impl(size=size) class ScalarResult(FilterResult[_R]): """A wrapper for a :class:`_engine.Result` that returns scalar values rather than :class:`_row.Row` values. The :class:`_engine.ScalarResult` object is acquired by calling the :meth:`_engine.Result.scalars` method. A special limitation of :class:`_engine.ScalarResult` is that it has no ``fetchone()`` method; since the semantics of ``fetchone()`` are that the ``None`` value indicates no more results, this is not compatible with :class:`_engine.ScalarResult` since there is no way to distinguish between ``None`` as a row value versus ``None`` as an indicator. Use ``next(result)`` to receive values individually. """ __slots__ = () _generate_rows = False _post_creational_filter: Optional[Callable[[Any], Any]] def __init__(self, real_result: Result[Any], index: _KeyIndexType): self._real_result = real_result if real_result._source_supports_scalars: self._metadata = real_result._metadata self._post_creational_filter = None else: self._metadata = real_result._metadata._reduce([index]) self._post_creational_filter = operator.itemgetter(0) self._unique_filter_state = real_result._unique_filter_state def unique(self, strategy: Optional[_UniqueFilterType] = None) -> Self: """Apply unique filtering to the objects returned by this :class:`_engine.ScalarResult`. See :meth:`_engine.Result.unique` for usage details. """ self._unique_filter_state = (set(), strategy) return self def partitions(self, size: Optional[int] = None) -> Iterator[Sequence[_R]]: """Iterate through sub-lists of elements of the size given. Equivalent to :meth:`_engine.Result.partitions` except that scalar values, rather than :class:`_engine.Row` objects, are returned. """ getter = self._manyrow_getter while True: partition = getter(self, size) if partition: yield partition else: break def fetchall(self) -> Sequence[_R]: """A synonym for the :meth:`_engine.ScalarResult.all` method.""" return self._allrows() def fetchmany(self, size: Optional[int] = None) -> Sequence[_R]: """Fetch many objects. Equivalent to :meth:`_engine.Result.fetchmany` except that scalar values, rather than :class:`_engine.Row` objects, are returned. """ return self._manyrow_getter(self, size) def all(self) -> Sequence[_R]: """Return all scalar values in a sequence. Equivalent to :meth:`_engine.Result.all` except that scalar values, rather than :class:`_engine.Row` objects, are returned. """ return self._allrows() def __iter__(self) -> Iterator[_R]: return self._iter_impl() def __next__(self) -> _R: return self._next_impl() def first(self) -> Optional[_R]: """Fetch the first object or ``None`` if no object is present. Equivalent to :meth:`_engine.Result.first` except that scalar values, rather than :class:`_engine.Row` objects, are returned. """ return self._only_one_row( raise_for_second_row=False, raise_for_none=False, scalar=False ) def one_or_none(self) -> Optional[_R]: """Return at most one object or raise an exception. Equivalent to :meth:`_engine.Result.one_or_none` except that scalar values, rather than :class:`_engine.Row` objects, are returned. """ return self._only_one_row( raise_for_second_row=True, raise_for_none=False, scalar=False ) def one(self) -> _R: """Return exactly one object or raise an exception. Equivalent to :meth:`_engine.Result.one` except that scalar values, rather than :class:`_engine.Row` objects, are returned. """ return self._only_one_row( raise_for_second_row=True, raise_for_none=True, scalar=False ) class TupleResult(FilterResult[_R], util.TypingOnly): """A :class:`_engine.Result` that's typed as returning plain Python tuples instead of rows. Since :class:`_engine.Row` acts like a tuple in every way already, this class is a typing only class, regular :class:`_engine.Result` is still used at runtime. """ __slots__ = () if TYPE_CHECKING: def partitions( self, size: Optional[int] = None ) -> Iterator[Sequence[_R]]: """Iterate through sub-lists of elements of the size given. Equivalent to :meth:`_engine.Result.partitions` except that tuple values, rather than :class:`_engine.Row` objects, are returned. """ ... def fetchone(self) -> Optional[_R]: """Fetch one tuple. Equivalent to :meth:`_engine.Result.fetchone` except that tuple values, rather than :class:`_engine.Row` objects, are returned. """ ... def fetchall(self) -> Sequence[_R]: """A synonym for the :meth:`_engine.ScalarResult.all` method.""" ... def fetchmany(self, size: Optional[int] = None) -> Sequence[_R]: """Fetch many objects. Equivalent to :meth:`_engine.Result.fetchmany` except that tuple values, rather than :class:`_engine.Row` objects, are returned. """ ... def all(self) -> Sequence[_R]: # noqa: A001 """Return all scalar values in a sequence. Equivalent to :meth:`_engine.Result.all` except that tuple values, rather than :class:`_engine.Row` objects, are returned. """ ... def __iter__(self) -> Iterator[_R]: ... def __next__(self) -> _R: ... def first(self) -> Optional[_R]: """Fetch the first object or ``None`` if no object is present. Equivalent to :meth:`_engine.Result.first` except that tuple values, rather than :class:`_engine.Row` objects, are returned. """ ... def one_or_none(self) -> Optional[_R]: """Return at most one object or raise an exception. Equivalent to :meth:`_engine.Result.one_or_none` except that tuple values, rather than :class:`_engine.Row` objects, are returned. """ ... def one(self) -> _R: """Return exactly one object or raise an exception. Equivalent to :meth:`_engine.Result.one` except that tuple values, rather than :class:`_engine.Row` objects, are returned. """ ... @overload def scalar_one(self: TupleResult[Tuple[_T]]) -> _T: ... @overload def scalar_one(self) -> Any: ... def scalar_one(self) -> Any: """Return exactly one scalar result or raise an exception. This is equivalent to calling :meth:`_engine.Result.scalars` and then :meth:`_engine.ScalarResult.one`. .. seealso:: :meth:`_engine.ScalarResult.one` :meth:`_engine.Result.scalars` """ ... @overload def scalar_one_or_none( self: TupleResult[Tuple[_T]], ) -> Optional[_T]: ... @overload def scalar_one_or_none(self) -> Optional[Any]: ... def scalar_one_or_none(self) -> Optional[Any]: """Return exactly one or no scalar result. This is equivalent to calling :meth:`_engine.Result.scalars` and then :meth:`_engine.ScalarResult.one_or_none`. .. seealso:: :meth:`_engine.ScalarResult.one_or_none` :meth:`_engine.Result.scalars` """ ... @overload def scalar(self: TupleResult[Tuple[_T]]) -> Optional[_T]: ... @overload def scalar(self) -> Any: ... def scalar(self) -> Any: """Fetch the first column of the first row, and close the result set. Returns ``None`` if there are no rows to fetch. No validation is performed to test if additional rows remain. After calling this method, the object is fully closed, e.g. the :meth:`_engine.CursorResult.close` method will have been called. :return: a Python scalar value , or ``None`` if no rows remain. """ ... class MappingResult(_WithKeys, FilterResult[RowMapping]): """A wrapper for a :class:`_engine.Result` that returns dictionary values rather than :class:`_engine.Row` values. The :class:`_engine.MappingResult` object is acquired by calling the :meth:`_engine.Result.mappings` method. """ __slots__ = () _generate_rows = True _post_creational_filter = operator.attrgetter("_mapping") def __init__(self, result: Result[Any]): self._real_result = result self._unique_filter_state = result._unique_filter_state self._metadata = result._metadata if result._source_supports_scalars: self._metadata = self._metadata._reduce([0]) def unique(self, strategy: Optional[_UniqueFilterType] = None) -> Self: """Apply unique filtering to the objects returned by this :class:`_engine.MappingResult`. See :meth:`_engine.Result.unique` for usage details. """ self._unique_filter_state = (set(), strategy) return self def columns(self, *col_expressions: _KeyIndexType) -> Self: r"""Establish the columns that should be returned in each row.""" return self._column_slices(col_expressions) def partitions( self, size: Optional[int] = None ) -> Iterator[Sequence[RowMapping]]: """Iterate through sub-lists of elements of the size given. Equivalent to :meth:`_engine.Result.partitions` except that :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. """ getter = self._manyrow_getter while True: partition = getter(self, size) if partition: yield partition else: break def fetchall(self) -> Sequence[RowMapping]: """A synonym for the :meth:`_engine.MappingResult.all` method.""" return self._allrows() def fetchone(self) -> Optional[RowMapping]: """Fetch one object. Equivalent to :meth:`_engine.Result.fetchone` except that :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. """ row = self._onerow_getter(self) if row is _NO_ROW: return None else: return row def fetchmany(self, size: Optional[int] = None) -> Sequence[RowMapping]: """Fetch many objects. Equivalent to :meth:`_engine.Result.fetchmany` except that :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. """ return self._manyrow_getter(self, size) def all(self) -> Sequence[RowMapping]: """Return all scalar values in a sequence. Equivalent to :meth:`_engine.Result.all` except that :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. """ return self._allrows() def __iter__(self) -> Iterator[RowMapping]: return self._iter_impl() def __next__(self) -> RowMapping: return self._next_impl() def first(self) -> Optional[RowMapping]: """Fetch the first object or ``None`` if no object is present. Equivalent to :meth:`_engine.Result.first` except that :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. """ return self._only_one_row( raise_for_second_row=False, raise_for_none=False, scalar=False ) def one_or_none(self) -> Optional[RowMapping]: """Return at most one object or raise an exception. Equivalent to :meth:`_engine.Result.one_or_none` except that :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. """ return self._only_one_row( raise_for_second_row=True, raise_for_none=False, scalar=False ) def one(self) -> RowMapping: """Return exactly one object or raise an exception. Equivalent to :meth:`_engine.Result.one` except that :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. """ return self._only_one_row( raise_for_second_row=True, raise_for_none=True, scalar=False ) class FrozenResult(Generic[_TP]): """Represents a :class:`_engine.Result` object in a "frozen" state suitable for caching. The :class:`_engine.FrozenResult` object is returned from the :meth:`_engine.Result.freeze` method of any :class:`_engine.Result` object. A new iterable :class:`_engine.Result` object is generated from a fixed set of data each time the :class:`_engine.FrozenResult` is invoked as a callable:: result = connection.execute(query) frozen = result.freeze() unfrozen_result_one = frozen() for row in unfrozen_result_one: print(row) unfrozen_result_two = frozen() rows = unfrozen_result_two.all() # ... etc .. versionadded:: 1.4 .. seealso:: :ref:`do_orm_execute_re_executing` - example usage within the ORM to implement a result-set cache. :func:`_orm.loading.merge_frozen_result` - ORM function to merge a frozen result back into a :class:`_orm.Session`. """ data: Sequence[Any] def __init__(self, result: Result[_TP]): self.metadata = result._metadata._for_freeze() self._source_supports_scalars = result._source_supports_scalars self._attributes = result._attributes if self._source_supports_scalars: self.data = list(result._raw_row_iterator()) else: self.data = result.fetchall() def rewrite_rows(self) -> Sequence[Sequence[Any]]: if self._source_supports_scalars: return [[elem] for elem in self.data] else: return [list(row) for row in self.data] def with_new_rows( self, tuple_data: Sequence[Row[_TP]] ) -> FrozenResult[_TP]: fr = FrozenResult.__new__(FrozenResult) fr.metadata = self.metadata fr._attributes = self._attributes fr._source_supports_scalars = self._source_supports_scalars if self._source_supports_scalars: fr.data = [d[0] for d in tuple_data] else: fr.data = tuple_data return fr def __call__(self) -> Result[_TP]: result: IteratorResult[_TP] = IteratorResult( self.metadata, iter(self.data) ) result._attributes = self._attributes result._source_supports_scalars = self._source_supports_scalars return result class IteratorResult(Result[_TP]): """A :class:`_engine.Result` that gets data from a Python iterator of :class:`_engine.Row` objects or similar row-like data. .. versionadded:: 1.4 """ _hard_closed = False _soft_closed = False def __init__( self, cursor_metadata: ResultMetaData, iterator: Iterator[_InterimSupportsScalarsRowType], raw: Optional[Result[Any]] = None, _source_supports_scalars: bool = False, ): self._metadata = cursor_metadata self.iterator = iterator self.raw = raw self._source_supports_scalars = _source_supports_scalars @property def closed(self) -> bool: """Return ``True`` if this :class:`_engine.IteratorResult` has been closed .. versionadded:: 1.4.43 """ return self._hard_closed def _soft_close(self, hard: bool = False, **kw: Any) -> None: if hard: self._hard_closed = True if self.raw is not None: self.raw._soft_close(hard=hard, **kw) self.iterator = iter([]) self._reset_memoizations() self._soft_closed = True def _raise_hard_closed(self) -> NoReturn: raise exc.ResourceClosedError("This result object is closed.") def _raw_row_iterator(self) -> Iterator[_RowData]: return self.iterator def _fetchiter_impl(self) -> Iterator[_InterimSupportsScalarsRowType]: if self._hard_closed: self._raise_hard_closed() return self.iterator def _fetchone_impl( self, hard_close: bool = False ) -> Optional[_InterimRowType[Row[Any]]]: if self._hard_closed: self._raise_hard_closed() row = next(self.iterator, _NO_ROW) if row is _NO_ROW: self._soft_close(hard=hard_close) return None else: return row def _fetchall_impl(self) -> List[_InterimRowType[Row[Any]]]: if self._hard_closed: self._raise_hard_closed() try: return list(self.iterator) finally: self._soft_close() def _fetchmany_impl( self, size: Optional[int] = None ) -> List[_InterimRowType[Row[Any]]]: if self._hard_closed: self._raise_hard_closed() return list(itertools.islice(self.iterator, 0, size)) def null_result() -> IteratorResult[Any]: return IteratorResult(SimpleResultMetaData([]), iter([])) class ChunkedIteratorResult(IteratorResult[_TP]): """An :class:`_engine.IteratorResult` that works from an iterator-producing callable. The given ``chunks`` argument is a function that is given a number of rows to return in each chunk, or ``None`` for all rows. The function should then return an un-consumed iterator of lists, each list of the requested size. The function can be called at any time again, in which case it should continue from the same result set but adjust the chunk size as given. .. versionadded:: 1.4 """ def __init__( self, cursor_metadata: ResultMetaData, chunks: Callable[ [Optional[int]], Iterator[Sequence[_InterimRowType[_R]]] ], source_supports_scalars: bool = False, raw: Optional[Result[Any]] = None, dynamic_yield_per: bool = False, ): self._metadata = cursor_metadata self.chunks = chunks self._source_supports_scalars = source_supports_scalars self.raw = raw self.iterator = itertools.chain.from_iterable(self.chunks(None)) self.dynamic_yield_per = dynamic_yield_per @_generative def yield_per(self, num: int) -> Self: # TODO: this throws away the iterator which may be holding # onto a chunk. the yield_per cannot be changed once any # rows have been fetched. either find a way to enforce this, # or we can't use itertools.chain and will instead have to # keep track. self._yield_per = num self.iterator = itertools.chain.from_iterable(self.chunks(num)) return self def _soft_close(self, hard: bool = False, **kw: Any) -> None: super()._soft_close(hard=hard, **kw) self.chunks = lambda size: [] # type: ignore def _fetchmany_impl( self, size: Optional[int] = None ) -> List[_InterimRowType[Row[Any]]]: if self.dynamic_yield_per: self.iterator = itertools.chain.from_iterable(self.chunks(size)) return super()._fetchmany_impl(size=size) class MergedResult(IteratorResult[_TP]): """A :class:`_engine.Result` that is merged from any number of :class:`_engine.Result` objects. Returned by the :meth:`_engine.Result.merge` method. .. versionadded:: 1.4 """ closed = False rowcount: Optional[int] def __init__( self, cursor_metadata: ResultMetaData, results: Sequence[Result[_TP]] ): self._results = results super().__init__( cursor_metadata, itertools.chain.from_iterable( r._raw_row_iterator() for r in results ), ) self._unique_filter_state = results[0]._unique_filter_state self._yield_per = results[0]._yield_per # going to try something w/ this in next rev self._source_supports_scalars = results[0]._source_supports_scalars self._attributes = self._attributes.merge_with( *[r._attributes for r in results] ) def _soft_close(self, hard: bool = False, **kw: Any) -> None: for r in self._results: r._soft_close(hard=hard, **kw) if hard: self.closed = True sqlalchemy/engine/__init__.py 0000755 00000005402 15125143220 0012263 0 ustar 00 # engine/__init__.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php """SQL connections, SQL execution and high-level DB-API interface. The engine package defines the basic components used to interface DB-API modules with higher-level statement construction, connection-management, execution and result contexts. The primary "entry point" class into this package is the Engine and its public constructor ``create_engine()``. """ from . import events as events from . import util as util from .base import Connection as Connection from .base import Engine as Engine from .base import NestedTransaction as NestedTransaction from .base import RootTransaction as RootTransaction from .base import Transaction as Transaction from .base import TwoPhaseTransaction as TwoPhaseTransaction from .create import create_engine as create_engine from .create import create_pool_from_url as create_pool_from_url from .create import engine_from_config as engine_from_config from .cursor import CursorResult as CursorResult from .cursor import ResultProxy as ResultProxy from .interfaces import AdaptedConnection as AdaptedConnection from .interfaces import BindTyping as BindTyping from .interfaces import Compiled as Compiled from .interfaces import Connectable as Connectable from .interfaces import ConnectArgsType as ConnectArgsType from .interfaces import ConnectionEventsTarget as ConnectionEventsTarget from .interfaces import CreateEnginePlugin as CreateEnginePlugin from .interfaces import Dialect as Dialect from .interfaces import ExceptionContext as ExceptionContext from .interfaces import ExecutionContext as ExecutionContext from .interfaces import TypeCompiler as TypeCompiler from .mock import create_mock_engine as create_mock_engine from .reflection import Inspector as Inspector from .reflection import ObjectKind as ObjectKind from .reflection import ObjectScope as ObjectScope from .result import ChunkedIteratorResult as ChunkedIteratorResult from .result import FilterResult as FilterResult from .result import FrozenResult as FrozenResult from .result import IteratorResult as IteratorResult from .result import MappingResult as MappingResult from .result import MergedResult as MergedResult from .result import Result as Result from .result import result_tuple as result_tuple from .result import ScalarResult as ScalarResult from .result import TupleResult as TupleResult from .row import BaseRow as BaseRow from .row import Row as Row from .row import RowMapping as RowMapping from .url import make_url as make_url from .url import URL as URL from .util import connection_memoize as connection_memoize from ..sql import ddl as ddl sqlalchemy/connectors/__pycache__/aioodbc.cpython-39.pyc 0000644 00000012147 15125143220 0017324 0 ustar 00 a ��Jh� � @ s d dl mZ d dlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddl m Z d d l m Z d d l m Z d d lmZ d d lmZ er�d dlmZ d dlmZ G dd� de�ZG dd� dee�ZG dd� de�ZG dd� dee�ZG dd� d�ZG dd� de �Zd S ) � )� annotations)� TYPE_CHECKING� )�AsyncAdapt_dbapi_connection)�AsyncAdapt_dbapi_cursor)�AsyncAdapt_dbapi_ss_cursor)�#AsyncAdaptFallback_dbapi_connection)�PyODBCConnector� )�pool)�util)�await_fallback)� await_only)�ConnectArgsType)�URLc @ s e Zd ZdZdd� ZdS )�AsyncAdapt_aioodbc_cursor� c G s | j jj|� S �N)Z_cursor�_impl� setinputsizes)�selfZ inputsizesr r �R/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/connectors/aioodbc.pyr s z'AsyncAdapt_aioodbc_cursor.setinputsizesN)�__name__� __module__� __qualname__� __slots__r r r r r r s r c @ s e Zd ZdZdS )� AsyncAdapt_aioodbc_ss_cursorr N�r r r r r r r r r ' s r c sh e Zd ZeZeZdZedd� �Z e j dd� �Z d� fdd� Z � fdd �Z � fd d �Z � fd d �Z� ZS )� AsyncAdapt_aioodbc_connectionr c C s | j jS r )� _connection� autocommit�r r r r r 2 s z(AsyncAdapt_aioodbc_connection.autocommitc C s || j j_d S r )r Z_connr )r �valuer r r r 6 s Fc s" | j jr| j�d��t� j|d�S )Nz#Attempt to use a closed connection.)� server_side)r �closedZdbapi�ProgrammingError�super�cursor)r r# �� __class__r r r' = s �z$AsyncAdapt_aioodbc_connection.cursorc s | j jst� �� d S r )r r$ r& �rollbackr! r( r r r* G s z&AsyncAdapt_aioodbc_connection.rollbackc s | j jst� �� d S r )r r$ r& �commitr! r( r r r+ M s z$AsyncAdapt_aioodbc_connection.commitc s | j jst� �� d S r )r r$ r& �closer! r( r r r, S s z#AsyncAdapt_aioodbc_connection.close)F)r r r r Z _cursor_clsr Z_ss_cursor_clsr �propertyr �setterr' r* r+ r, � __classcell__r r r( r r - s r c @ s e Zd ZdZdS )�%AsyncAdaptFallback_aioodbc_connectionr Nr r r r r r0 Z s r0 c @ s$ e Zd Zdd� Zdd� Zdd� ZdS )�AsyncAdapt_aioodbc_dbapic C s. || _ || _|j| _| �� t| _|j| _d S r )�aioodbc�pyodbcZ paramstyle�_init_dbapi_attributesr �Cursor�version)r r2 r3 r r r �__init__a s z!AsyncAdapt_aioodbc_dbapi.__init__c C s" dD ]}t | |t| j|�� qd S )N)�Warning�Error�InterfaceErrorZ DataErrorZ DatabaseErrorZOperationalErrorr: ZIntegrityErrorr% Z InternalErrorZNotSupportedError�NUMBER�STRINGZDATETIMEZBINARY�BinaryZ BinaryNullZ SQL_VARCHARZ SQL_WVARCHAR)�setattr�getattrr3 )r �namer r r r4 i s z/AsyncAdapt_aioodbc_dbapi._init_dbapi_attributesc O sZ |� dd�}|� d| jj�}t�|�r>t| t||i |����S t| t||i |����S d S )N�async_fallbackFZasync_creator_fn) �popr2 �connectr �asboolr0 r r r )r �arg�kwrA Z creator_fnr r r rC � s ��z AsyncAdapt_aioodbc_dbapi.connectN)r r r r7 r4 rC r r r r r1 ` s r1 c sP e Zd ZdZdZdZedd� �Zddd�� fdd� Zed d � �Z d d � Z � Z S ) �aiodbcConnectorTc C s t td�td��S )Nr2 r3 )r1 � __import__)�clsr r r � import_dbapi� s �z aiodbcConnector.import_dbapir r )�url�returnc s0 t � �|�\}}|r(|d r(|d |d< d|fS )Nr Zdsnr )r& �create_connect_args)r rK rE rF r( r r rM � s z#aiodbcConnector.create_connect_argsc C s( |j �dd�}t�|�r tjS tjS d S )NrA F)�query�getr rD r Z FallbackAsyncAdaptedQueuePoolZAsyncAdaptedQueuePool)rI rK rA r r r �get_pool_class� s z aiodbcConnector.get_pool_classc C s |j S r )r )r � connectionr r r �get_driver_connection� s z%aiodbcConnector.get_driver_connection) r r r �is_asyncZsupports_statement_cacheZ supports_server_side_cursors� classmethodrJ rM rP rR r/ r r r( r rG � s rG N)� __future__r �typingr �asyncior r r r r3 r � r r Zutil.concurrencyr r Zengine.interfacesr Z engine.urlr r r r r0 r1 rG r r r r �<module> s. �- �1 sqlalchemy/connectors/__pycache__/asyncio.cpython-39.pyc 0000644 00000017315 15125143220 0017373 0 ustar 00 a ��Jh� � @ s� d Z ddlmZ ddlZddlmZ ddlmZ ddlmZ ddlm Z G d d � d �Z G d d � d e �Z G d d� de�Z G dd� de �Z dS )z?generic asyncio-adapted versions of DBAPI connection and cursor� )� annotationsN� )�AdaptedConnection)�asyncio)�await_fallback)� await_onlyc @ s� e Zd ZdZdZdd� Zdd� Zedd� �Zed d � �Z ed d � �Z e j d d � �Z edd� �Z dd� Z d'dd�Zdd� Zdd� Zdd� Zdd � Zd d � Zd d � Zd!d"� Zd(d#d$�Zd%d&� ZdS ))�AsyncAdapt_dbapi_cursorF)�_adapt_connection� _connection�await_�_cursor�_rowsc C s@ || _ |j| _|j| _| j�� }| �|�| _| js<t�� | _ d S �N) r r r �cursor�_aenter_cursorr � server_side� collections�dequer ��selfZadapt_connectionr � r �R/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/connectors/asyncio.py�__init__ s z AsyncAdapt_dbapi_cursor.__init__c C s | � |�� �S r )r � __aenter__)r r r r r r * s z&AsyncAdapt_dbapi_cursor._aenter_cursorc C s | j jS r )r � description�r r r r r - s z#AsyncAdapt_dbapi_cursor.descriptionc C s | j jS r )r �rowcountr r r r r 1 s z AsyncAdapt_dbapi_cursor.rowcountc C s | j jS r �r � arraysizer r r r r 5 s z!AsyncAdapt_dbapi_cursor.arraysizec C s || j _d S r r �r �valuer r r r 9 s c C s | j jS r )r � lastrowidr r r r r! = s z!AsyncAdapt_dbapi_cursor.lastrowidc C s | j �� d S r )r �clearr r r r �closeA s z AsyncAdapt_dbapi_cursor.closeNc C s | � | �||��S r )r �_execute_async)r � operation� parametersr r r �executeF s z AsyncAdapt_dbapi_cursor.executec C s | � | �||��S r )r �_executemany_async�r r% Zseq_of_parametersr r r � executemanyI s �z#AsyncAdapt_dbapi_cursor.executemanyc � s� | j j4 I d H �X | j�||p d�I d H }| jjrP| jsPt�| j�� I d H �| _ |W d �I d H S 1 I d H st0 Y d S )Nr ) r �_execute_mutexr r' r r r r �fetchallr )r r% r& �resultr r r r$ N s z&AsyncAdapt_dbapi_cursor._execute_asyncc � sT | j j4 I d H �* | j�||�I d H W d �I d H S 1 I d H sF0 Y d S r )r r+ r r* r) r r r r( V s z*AsyncAdapt_dbapi_cursor._executemany_asyncc C s: | � | j�� � | jjr6| js6t�| � | j�� ��| _d S r ) r r �nextsetr r r r r, r r r r r r. Z s �z AsyncAdapt_dbapi_cursor.nextsetc G s | � | jj|� �S r )r r � setinputsizes)r Z inputsizesr r r r/ a s z%AsyncAdapt_dbapi_cursor.setinputsizesc c s | j r| j �� V q d S r �r �popleftr r r r �__iter__h s z AsyncAdapt_dbapi_cursor.__iter__c C s | j r| j �� S d S d S r r0 r r r r �fetchonel s z AsyncAdapt_dbapi_cursor.fetchonec s4 |d u r| j }| j� � fdd�tt|t� ���D �S )Nc s g | ] }� � � �qS r )r1 )�.0�_��rrr r � <listcomp>v � z5AsyncAdapt_dbapi_cursor.fetchmany.<locals>.<listcomp>)r r �range�min�len�r �sizer r6 r � fetchmanyr s z!AsyncAdapt_dbapi_cursor.fetchmanyc C s t | j�}| j�� |S r )�listr r" )r �retvalr r r r, x s z AsyncAdapt_dbapi_cursor.fetchall)N)N)�__name__� __module__� __qualname__r � __slots__r r �propertyr r r �setterr! r# r' r* r$ r( r. r/ r2 r3 r? r, r r r r r s2 r c @ sF e Zd ZdZdZdd� Zdd� Zdd� Zdd d �Zd d � Z dd� Z d S )�AsyncAdapt_dbapi_ss_cursorr Tc C s4 || _ |j| _|j| _| j�� }| �|�� �| _d S r )r r r r r r r r r r r � s z#AsyncAdapt_dbapi_ss_cursor.__init__c C s$ | j d ur | �| j �� � d | _ d S r )r r r# r r r r r# � s z AsyncAdapt_dbapi_ss_cursor.closec C s | � | j�� �S r )r r r3 r r r r r3 � s z#AsyncAdapt_dbapi_ss_cursor.fetchoneNc C s | � | jj|d��S )N)r> )r r r? r= r r r r? � s z$AsyncAdapt_dbapi_ss_cursor.fetchmanyc C s | � | j�� �S r )r r r, r r r r r, � s z#AsyncAdapt_dbapi_ss_cursor.fetchallc c s< | j �� }z| �|�� �V W q ty4 Y q8Y q 0 q d S r )r � __aiter__r � __anext__�StopAsyncIteration)r �iteratorr r r r2 � s z#AsyncAdapt_dbapi_ss_cursor.__iter__)N) rB rC rD rE r r r# r3 r? r, r2 r r r r rH ~ s rH c @ s| e Zd ZeZeZee�Z dZ dd� Z dd� Z dd� Z dd � Zed d � �Zejd d � �Zddd�Zdd� Zdd� Zdd� ZdS )�AsyncAdapt_dbapi_connection)�dbapir+ c C s || _ || _t�� | _d S r )rN r r �Lockr+ )r rN � connectionr r r r � s z$AsyncAdapt_dbapi_connection.__init__c C s | � | j�|��S r )r r �ping)r Z reconnectr r r rQ � s z AsyncAdapt_dbapi_connection.pingc O s | j j|i |�� d S r )r �add_output_converter)r �arg�kwr r r rR � s z0AsyncAdapt_dbapi_connection.add_output_converterc C s | j �� S r )r �character_set_namer r r r rU � s z.AsyncAdapt_dbapi_connection.character_set_namec C s | j jS r )r � autocommitr r r r rV � s z&AsyncAdapt_dbapi_connection.autocommitc C s || j j_d S r )r Z_connrV r r r r rV � s Fc C s |r| � | �S | �| �S d S r )�_ss_cursor_cls� _cursor_cls)r r r r r r � s z"AsyncAdapt_dbapi_connection.cursorc C s | � | j�� � d S r )r r �rollbackr r r r rY � s z$AsyncAdapt_dbapi_connection.rollbackc C s | � | j�� � d S r )r r �commitr r r r rZ � s z"AsyncAdapt_dbapi_connection.commitc C s | � | j�� � d S r )r r r# r r r r r# � s z!AsyncAdapt_dbapi_connection.closeN)F)rB rC rD r rX rH rW � staticmethodr r rE r rQ rR rU rF rV rG r rY rZ r# r r r r rM � s rM c @ s e Zd ZdZee�ZdS )�#AsyncAdaptFallback_dbapi_connectionr N)rB rC rD rE r[ r r r r r r r\ � s r\ )�__doc__� __future__r r Zenginer Zutil.concurrencyr r r r rH rM r\ r r r r �<module> s i$0 sqlalchemy/connectors/__pycache__/__init__.cpython-39.pyc 0000644 00000001044 15125143220 0017455 0 ustar 00 a ��Jh� � @ s d dl mZ G dd� de�ZdS )� )�Dialectc @ s e Zd ZdZdS )� Connectorz�Base class for dialect mixins, for DBAPIs that work across entirely different database backends. Currently the only such mixin is pyodbc. N)�__name__� __module__� __qualname__�__doc__� r r �S/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/connectors/__init__.pyr s r N)Zengine.interfacesr r r r r r �<module> s sqlalchemy/connectors/__pycache__/pyodbc.cpython-39.pyc 0000644 00000014723 15125143220 0017206 0 ustar 00 a ��Jh! � @ s d dl mZ d dlZd dlmZ d dlZd dlmZ d dlmZ d dlmZ d dlm Z d dlm Z d d lm Z d d l m Z d d lmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ ejr�d dlm Z G dd� de�Z dS )� )� annotationsN)� ModuleType)�Any)�Dict)�List)�Optional)�Tuple)�Union)� unquote_plus� )� Connector� )�ExecutionContext)�pool)�util)�ConnectArgsType)� Connection)� interfaces)�URL)� TypeEngine)�IsolationLevelc s� e Zd ZU dZdZdZdZdZdZdZ de d< de d < d8d d d �� fd d� Z e dd�dd��Z ddd�dd�Zdddd d�dd �Zd d�d d �Zd d d!�d"d#�Zd$d d%�d&d'�Zd(d)d*d+d,�d-d.�Zd/d0d1�� fd2d3� Zd/d4d+d5�� fd6d7� Z� ZS )9�PyODBCConnector�pyodbcTF�namedNz Optional[str]�pyodbc_driver_namer �dbapi�boolr )�use_setinputsizes�kwc s$ t � jf i |�� |r tjj| _d S �N)�super�__init__r Z BindTypingZ SETINPUTSIZESZ bind_typing)�selfr r �� __class__� �Q/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/connectors/pyodbc.pyr! 5 s zPyODBCConnector.__init__)�returnc C s t d�S )Nr )� __import__)�clsr% r% r& � import_dbapi: s z PyODBCConnector.import_dbapir r )�urlr' c s |j dd�}|�|j� |}|j}i }dD ] }||v r*t�|�|��||< q*d|v rht|�d��g}�n�ddd�dd�� � fd d �|�� D �}d |v p�d |v o�d |v}|r�d|�d d�p�|�d d� g}n�d} d|v r�d|vr�dt|�d�� } g }|�d| j �} | d u �r |�r t� d� n|� d| � |� d|�d d�| f d|�d d� g� |�dd �} | �r�|� d| � |�dd�} | �r�|� d| � n,|�dd �} | �r�|� d| � n |� d � d |v �r�|� d |�d � � |� d d � |�� D �� d!� |�f|fS )"N�user)�username)�ansiZunicode_results� autocommitZ odbc_connect�str)�tokenr' c S s. dt | �v st | ��d�r*d| �dd� } | S )N�;�{z{%s}�}z}})r0 � startswith�replace)r1 r% r% r& � check_quoteQ s z8PyODBCConnector.create_connect_args.<locals>.check_quotec s i | ]\}}|� |��qS r% r% ��.0�k�v�r7 r% r& � <dictcomp>V � z7PyODBCConnector.create_connect_args.<locals>.<dictcomp>Zdsn�hostZdatabasezdsn=%s� �portz,%d�driverzTNo driver name specified; this is expected by PyODBC when using DSN-less connectionsz DRIVER={%s}z Server=%s%sz Database=%szUID=%s�passwordzPWD=%s�authenticationzAuthentication=%szTrusted_Connection=YesZodbc_autotranslatezAutoTranslate=%sc S s g | ]\}}d ||f �qS )z%s=%sr% r8 r% r% r& � <listcomp>� r> z7PyODBCConnector.create_connect_args.<locals>.<listcomp>r2 )Ztranslate_connect_args�update�queryr Zasbool�popr �items�intr �warn�append�extend�join)r" r+ �opts�keysrG Z connect_args�paramZ connectorsZdsn_connectionrA rB r, �pwdrD r% r< r& �create_connect_args> sb ����� �z#PyODBCConnector.create_connect_args� ExceptionzGOptional[Union[pool.PoolProxiedConnection, interfaces.DBAPIConnection]]z Optional[interfaces.DBAPICursor])�e� connection�cursorr' c C s. t || jj�r&dt|�v p$dt|�v S dS d S )Nz(The cursor's connection has been closed.z#Attempt to use a closed connection.F)� isinstancer ZProgrammingErrorr0 )r" rU rV rW r% r% r& � is_disconnect� s � �z PyODBCConnector.is_disconnectzinterfaces.VersionInfoTypec C s | j s dS | �| j j�S )Nr% )r �_parse_dbapi_version�version)r" r% r% r& �_dbapi_version� s z PyODBCConnector._dbapi_versionr0 )�versr' c C sP t �d|�}|sdS tdd� |�d��d�D ��}|�d�rL||�d�f7 }|S )Nz (?:py.*-)?([\d\.]+)(?:-(\w+))?r% c S s g | ] }t |��qS r% )rJ )r9 �xr% r% r& rE � r> z8PyODBCConnector._parse_dbapi_version.<locals>.<listcomp>r �.r )�re�match�tuple�group�split)r" r] �mZ vers_tupler% r% r& rZ � s � z$PyODBCConnector._parse_dbapi_versionr )rV r' c C s^ |j j}d}t�d�}|�|�| jj��D ]*}z|t|�f7 }W q* t yR Y q*0 q*t |�S )Nr% z[.\-]) rV �dbapi_connectionr` �compilerd �getinfor Z SQL_DBMS_VERrJ � ValueErrorrb )r" rV Z dbapi_conr[ �r�nr% r% r& �_get_server_version_info� s z(PyODBCConnector._get_server_version_infozinterfaces.DBAPICursorz&List[Tuple[str, Any, TypeEngine[Any]]]r �None)rW �list_of_tuples�contextr' c C s0 |j tjju r| jrd S |�dd� |D �� d S )Nc S s* g | ]"\}}}t |t�s"|d d fn|�qS r )rX rb )r9 �keyZdbtypeZsqltyper% r% r& rE � s �� z6PyODBCConnector.do_set_input_sizes.<locals>.<listcomp>)Z execute_styler Z ExecuteStyleZ EXECUTEMANY�fast_executemanyZ setinputsizes)r" rW rn ro r% r% r& �do_set_input_sizes� s ����z"PyODBCConnector.do_set_input_sizeszinterfaces.DBAPIConnectionzList[IsolationLevel])� dbapi_connr' c s g t � �|��d�S )N� AUTOCOMMIT)r �get_isolation_level_values)r" rs r# r% r& ru � s z*PyODBCConnector.get_isolation_level_valuesr )rf �levelr' c s( |dkrd|_ nd|_ t� �||� d S )Nrt TF)r/ r �set_isolation_level)r" rf rv r# r% r& rw � s z#PyODBCConnector.set_isolation_level)F)�__name__� __module__� __qualname__rB Z supports_sane_rowcount_returningZ supports_sane_multi_rowcountZsupports_native_decimalZdefault_paramstylerq r �__annotations__r! � classmethodr* rS rY r\ rZ rl rr ru rw � __classcell__r% r% r# r& r # s& S %r ) � __future__r r` �typesr �typingr r r r r r � urllib.parser r@ r r r r Zenginer r r r Z sql.type_apir � TYPE_CHECKINGZengine.interfacesr r r% r% r% r& �<module> s, sqlalchemy/connectors/pyodbc.py 0000755 00000020423 15125143220 0012714 0 ustar 00 # connectors/pyodbc.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php from __future__ import annotations import re from types import ModuleType import typing from typing import Any from typing import Dict from typing import List from typing import Optional from typing import Tuple from typing import Union from urllib.parse import unquote_plus from . import Connector from .. import ExecutionContext from .. import pool from .. import util from ..engine import ConnectArgsType from ..engine import Connection from ..engine import interfaces from ..engine import URL from ..sql.type_api import TypeEngine if typing.TYPE_CHECKING: from ..engine.interfaces import IsolationLevel class PyODBCConnector(Connector): driver = "pyodbc" # this is no longer False for pyodbc in general supports_sane_rowcount_returning = True supports_sane_multi_rowcount = False supports_native_decimal = True default_paramstyle = "named" fast_executemany = False # for non-DSN connections, this *may* be used to # hold the desired driver name pyodbc_driver_name: Optional[str] = None dbapi: ModuleType def __init__(self, use_setinputsizes: bool = False, **kw: Any): super().__init__(**kw) if use_setinputsizes: self.bind_typing = interfaces.BindTyping.SETINPUTSIZES @classmethod def import_dbapi(cls) -> ModuleType: return __import__("pyodbc") def create_connect_args(self, url: URL) -> ConnectArgsType: opts = url.translate_connect_args(username="user") opts.update(url.query) keys = opts query = url.query connect_args: Dict[str, Any] = {} connectors: List[str] for param in ("ansi", "unicode_results", "autocommit"): if param in keys: connect_args[param] = util.asbool(keys.pop(param)) if "odbc_connect" in keys: connectors = [unquote_plus(keys.pop("odbc_connect"))] else: def check_quote(token: str) -> str: if ";" in str(token) or str(token).startswith("{"): token = "{%s}" % token.replace("}", "}}") return token keys = {k: check_quote(v) for k, v in keys.items()} dsn_connection = "dsn" in keys or ( "host" in keys and "database" not in keys ) if dsn_connection: connectors = [ "dsn=%s" % (keys.pop("host", "") or keys.pop("dsn", "")) ] else: port = "" if "port" in keys and "port" not in query: port = ",%d" % int(keys.pop("port")) connectors = [] driver = keys.pop("driver", self.pyodbc_driver_name) if driver is None and keys: # note if keys is empty, this is a totally blank URL util.warn( "No driver name specified; " "this is expected by PyODBC when using " "DSN-less connections" ) else: connectors.append("DRIVER={%s}" % driver) connectors.extend( [ "Server=%s%s" % (keys.pop("host", ""), port), "Database=%s" % keys.pop("database", ""), ] ) user = keys.pop("user", None) if user: connectors.append("UID=%s" % user) pwd = keys.pop("password", "") if pwd: connectors.append("PWD=%s" % pwd) else: authentication = keys.pop("authentication", None) if authentication: connectors.append("Authentication=%s" % authentication) else: connectors.append("Trusted_Connection=Yes") # if set to 'Yes', the ODBC layer will try to automagically # convert textual data from your database encoding to your # client encoding. This should obviously be set to 'No' if # you query a cp1253 encoded database from a latin1 client... if "odbc_autotranslate" in keys: connectors.append( "AutoTranslate=%s" % keys.pop("odbc_autotranslate") ) connectors.extend(["%s=%s" % (k, v) for k, v in keys.items()]) return ((";".join(connectors),), connect_args) def is_disconnect( self, e: Exception, connection: Optional[ Union[pool.PoolProxiedConnection, interfaces.DBAPIConnection] ], cursor: Optional[interfaces.DBAPICursor], ) -> bool: if isinstance(e, self.dbapi.ProgrammingError): return "The cursor's connection has been closed." in str( e ) or "Attempt to use a closed connection." in str(e) else: return False def _dbapi_version(self) -> interfaces.VersionInfoType: if not self.dbapi: return () return self._parse_dbapi_version(self.dbapi.version) def _parse_dbapi_version(self, vers: str) -> interfaces.VersionInfoType: m = re.match(r"(?:py.*-)?([\d\.]+)(?:-(\w+))?", vers) if not m: return () vers_tuple: interfaces.VersionInfoType = tuple( [int(x) for x in m.group(1).split(".")] ) if m.group(2): vers_tuple += (m.group(2),) return vers_tuple def _get_server_version_info( self, connection: Connection ) -> interfaces.VersionInfoType: # NOTE: this function is not reliable, particularly when # freetds is in use. Implement database-specific server version # queries. dbapi_con = connection.connection.dbapi_connection version: Tuple[Union[int, str], ...] = () r = re.compile(r"[.\-]") for n in r.split(dbapi_con.getinfo(self.dbapi.SQL_DBMS_VER)): # type: ignore[union-attr] # noqa: E501 try: version += (int(n),) except ValueError: pass return tuple(version) def do_set_input_sizes( self, cursor: interfaces.DBAPICursor, list_of_tuples: List[Tuple[str, Any, TypeEngine[Any]]], context: ExecutionContext, ) -> None: # the rules for these types seems a little strange, as you can pass # non-tuples as well as tuples, however it seems to assume "0" # for the subsequent values if you don't pass a tuple which fails # for types such as pyodbc.SQL_WLONGVARCHAR, which is the datatype # that ticket #5649 is targeting. # NOTE: as of #6058, this won't be called if the use_setinputsizes # parameter were not passed to the dialect, or if no types were # specified in list_of_tuples # as of #8177 for 2.0 we assume use_setinputsizes=True and only # omit the setinputsizes calls for .executemany() with # fast_executemany=True if ( context.execute_style is interfaces.ExecuteStyle.EXECUTEMANY and self.fast_executemany ): return cursor.setinputsizes( [ ( (dbtype, None, None) if not isinstance(dbtype, tuple) else dbtype ) for key, dbtype, sqltype in list_of_tuples ] ) def get_isolation_level_values( self, dbapi_conn: interfaces.DBAPIConnection ) -> List[IsolationLevel]: return [*super().get_isolation_level_values(dbapi_conn), "AUTOCOMMIT"] def set_isolation_level( self, dbapi_connection: interfaces.DBAPIConnection, level: IsolationLevel, ) -> None: # adjust for ConnectionFairy being present # allows attribute set e.g. "connection.autocommit = True" # to work properly if level == "AUTOCOMMIT": dbapi_connection.autocommit = True else: dbapi_connection.autocommit = False super().set_isolation_level(dbapi_connection, level) sqlalchemy/connectors/aioodbc.py 0000755 00000012250 15125143220 0013033 0 ustar 00 # connectors/aioodbc.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors from __future__ import annotations from typing import TYPE_CHECKING from .asyncio import AsyncAdapt_dbapi_connection from .asyncio import AsyncAdapt_dbapi_cursor from .asyncio import AsyncAdapt_dbapi_ss_cursor from .asyncio import AsyncAdaptFallback_dbapi_connection from .pyodbc import PyODBCConnector from .. import pool from .. import util from ..util.concurrency import await_fallback from ..util.concurrency import await_only if TYPE_CHECKING: from ..engine.interfaces import ConnectArgsType from ..engine.url import URL class AsyncAdapt_aioodbc_cursor(AsyncAdapt_dbapi_cursor): __slots__ = () def setinputsizes(self, *inputsizes): # see https://github.com/aio-libs/aioodbc/issues/451 return self._cursor._impl.setinputsizes(*inputsizes) # how it's supposed to work # return self.await_(self._cursor.setinputsizes(*inputsizes)) class AsyncAdapt_aioodbc_ss_cursor( AsyncAdapt_aioodbc_cursor, AsyncAdapt_dbapi_ss_cursor ): __slots__ = () class AsyncAdapt_aioodbc_connection(AsyncAdapt_dbapi_connection): _cursor_cls = AsyncAdapt_aioodbc_cursor _ss_cursor_cls = AsyncAdapt_aioodbc_ss_cursor __slots__ = () @property def autocommit(self): return self._connection.autocommit @autocommit.setter def autocommit(self, value): # https://github.com/aio-libs/aioodbc/issues/448 # self._connection.autocommit = value self._connection._conn.autocommit = value def cursor(self, server_side=False): # aioodbc sets connection=None when closed and just fails with # AttributeError here. Here we use the same ProgrammingError + # message that pyodbc uses, so it triggers is_disconnect() as well. if self._connection.closed: raise self.dbapi.ProgrammingError( "Attempt to use a closed connection." ) return super().cursor(server_side=server_side) def rollback(self): # aioodbc sets connection=None when closed and just fails with # AttributeError here. should be a no-op if not self._connection.closed: super().rollback() def commit(self): # aioodbc sets connection=None when closed and just fails with # AttributeError here. should be a no-op if not self._connection.closed: super().commit() def close(self): # aioodbc sets connection=None when closed and just fails with # AttributeError here. should be a no-op if not self._connection.closed: super().close() class AsyncAdaptFallback_aioodbc_connection( AsyncAdaptFallback_dbapi_connection, AsyncAdapt_aioodbc_connection ): __slots__ = () class AsyncAdapt_aioodbc_dbapi: def __init__(self, aioodbc, pyodbc): self.aioodbc = aioodbc self.pyodbc = pyodbc self.paramstyle = pyodbc.paramstyle self._init_dbapi_attributes() self.Cursor = AsyncAdapt_dbapi_cursor self.version = pyodbc.version def _init_dbapi_attributes(self): for name in ( "Warning", "Error", "InterfaceError", "DataError", "DatabaseError", "OperationalError", "InterfaceError", "IntegrityError", "ProgrammingError", "InternalError", "NotSupportedError", "NUMBER", "STRING", "DATETIME", "BINARY", "Binary", "BinaryNull", "SQL_VARCHAR", "SQL_WVARCHAR", ): setattr(self, name, getattr(self.pyodbc, name)) def connect(self, *arg, **kw): async_fallback = kw.pop("async_fallback", False) creator_fn = kw.pop("async_creator_fn", self.aioodbc.connect) if util.asbool(async_fallback): return AsyncAdaptFallback_aioodbc_connection( self, await_fallback(creator_fn(*arg, **kw)), ) else: return AsyncAdapt_aioodbc_connection( self, await_only(creator_fn(*arg, **kw)), ) class aiodbcConnector(PyODBCConnector): is_async = True supports_statement_cache = True supports_server_side_cursors = True @classmethod def import_dbapi(cls): return AsyncAdapt_aioodbc_dbapi( __import__("aioodbc"), __import__("pyodbc") ) def create_connect_args(self, url: URL) -> ConnectArgsType: arg, kw = super().create_connect_args(url) if arg and arg[0]: kw["dsn"] = arg[0] return (), kw @classmethod def get_pool_class(cls, url): async_fallback = url.query.get("async_fallback", False) if util.asbool(async_fallback): return pool.FallbackAsyncAdaptedQueuePool else: return pool.AsyncAdaptedQueuePool def get_driver_connection(self, connection): return connection._connection sqlalchemy/connectors/asyncio.py 0000755 00000013772 15125143220 0013112 0 ustar 00 # connectors/asyncio.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php # mypy: ignore-errors """generic asyncio-adapted versions of DBAPI connection and cursor""" from __future__ import annotations import collections from ..engine import AdaptedConnection from ..util.concurrency import asyncio from ..util.concurrency import await_fallback from ..util.concurrency import await_only class AsyncAdapt_dbapi_cursor: server_side = False __slots__ = ( "_adapt_connection", "_connection", "await_", "_cursor", "_rows", ) def __init__(self, adapt_connection): self._adapt_connection = adapt_connection self._connection = adapt_connection._connection self.await_ = adapt_connection.await_ cursor = self._connection.cursor() self._cursor = self._aenter_cursor(cursor) if not self.server_side: self._rows = collections.deque() def _aenter_cursor(self, cursor): return self.await_(cursor.__aenter__()) @property def description(self): return self._cursor.description @property def rowcount(self): return self._cursor.rowcount @property def arraysize(self): return self._cursor.arraysize @arraysize.setter def arraysize(self, value): self._cursor.arraysize = value @property def lastrowid(self): return self._cursor.lastrowid def close(self): # note we aren't actually closing the cursor here, # we are just letting GC do it. see notes in aiomysql dialect self._rows.clear() def execute(self, operation, parameters=None): return self.await_(self._execute_async(operation, parameters)) def executemany(self, operation, seq_of_parameters): return self.await_( self._executemany_async(operation, seq_of_parameters) ) async def _execute_async(self, operation, parameters): async with self._adapt_connection._execute_mutex: result = await self._cursor.execute(operation, parameters or ()) if self._cursor.description and not self.server_side: self._rows = collections.deque(await self._cursor.fetchall()) return result async def _executemany_async(self, operation, seq_of_parameters): async with self._adapt_connection._execute_mutex: return await self._cursor.executemany(operation, seq_of_parameters) def nextset(self): self.await_(self._cursor.nextset()) if self._cursor.description and not self.server_side: self._rows = collections.deque( self.await_(self._cursor.fetchall()) ) def setinputsizes(self, *inputsizes): # NOTE: this is overrridden in aioodbc due to # see https://github.com/aio-libs/aioodbc/issues/451 # right now return self.await_(self._cursor.setinputsizes(*inputsizes)) def __iter__(self): while self._rows: yield self._rows.popleft() def fetchone(self): if self._rows: return self._rows.popleft() else: return None def fetchmany(self, size=None): if size is None: size = self.arraysize rr = self._rows return [rr.popleft() for _ in range(min(size, len(rr)))] def fetchall(self): retval = list(self._rows) self._rows.clear() return retval class AsyncAdapt_dbapi_ss_cursor(AsyncAdapt_dbapi_cursor): __slots__ = () server_side = True def __init__(self, adapt_connection): self._adapt_connection = adapt_connection self._connection = adapt_connection._connection self.await_ = adapt_connection.await_ cursor = self._connection.cursor() self._cursor = self.await_(cursor.__aenter__()) def close(self): if self._cursor is not None: self.await_(self._cursor.close()) self._cursor = None def fetchone(self): return self.await_(self._cursor.fetchone()) def fetchmany(self, size=None): return self.await_(self._cursor.fetchmany(size=size)) def fetchall(self): return self.await_(self._cursor.fetchall()) def __iter__(self): iterator = self._cursor.__aiter__() while True: try: yield self.await_(iterator.__anext__()) except StopAsyncIteration: break class AsyncAdapt_dbapi_connection(AdaptedConnection): _cursor_cls = AsyncAdapt_dbapi_cursor _ss_cursor_cls = AsyncAdapt_dbapi_ss_cursor await_ = staticmethod(await_only) __slots__ = ("dbapi", "_execute_mutex") def __init__(self, dbapi, connection): self.dbapi = dbapi self._connection = connection self._execute_mutex = asyncio.Lock() def ping(self, reconnect): return self.await_(self._connection.ping(reconnect)) def add_output_converter(self, *arg, **kw): self._connection.add_output_converter(*arg, **kw) def character_set_name(self): return self._connection.character_set_name() @property def autocommit(self): return self._connection.autocommit @autocommit.setter def autocommit(self, value): # https://github.com/aio-libs/aioodbc/issues/448 # self._connection.autocommit = value self._connection._conn.autocommit = value def cursor(self, server_side=False): if server_side: return self._ss_cursor_cls(self) else: return self._cursor_cls(self) def rollback(self): self.await_(self._connection.rollback()) def commit(self): self.await_(self._connection.commit()) def close(self): self.await_(self._connection.close()) class AsyncAdaptFallback_dbapi_connection(AsyncAdapt_dbapi_connection): __slots__ = () await_ = staticmethod(await_fallback) sqlalchemy/connectors/__init__.py 0000755 00000000734 15125143220 0013176 0 ustar 00 # connectors/__init__.py # Copyright (C) 2005-2025 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php from ..engine.interfaces import Dialect class Connector(Dialect): """Base class for dialect mixins, for DBAPIs that work across entirely different database backends. Currently the only such mixin is pyodbc. """ sqlalchemy/cyextension/__pycache__/__init__.cpython-39.pyc 0000644 00000000257 15125143220 0017655 0 ustar 00 a ��Jh� � @ s d S )N� r r r �T/home/agenciai/.local/lib/python3.9/site-packages/sqlalchemy/cyextension/__init__.py�<module> � sqlalchemy/cyextension/processors.pyx 0000644 00000003400 15125143220 0014212 0 ustar 00 # cyextension/processors.pyx # Copyright (C) 2005-2024 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php import datetime from datetime import datetime as datetime_cls from datetime import time as time_cls from datetime import date as date_cls import re from cpython.object cimport PyObject_Str from cpython.unicode cimport PyUnicode_AsASCIIString, PyUnicode_Check, PyUnicode_Decode from libc.stdio cimport sscanf def int_to_boolean(value): if value is None: return None return True if value else False def to_str(value): return PyObject_Str(value) if value is not None else None def to_float(value): return float(value) if value is not None else None cdef inline bytes to_bytes(object value, str type_name): try: return PyUnicode_AsASCIIString(value) except Exception as e: raise ValueError( f"Couldn't parse {type_name} string '{value!r}' " "- value is not a string." ) from e def str_to_datetime(value): if value is not None: value = datetime_cls.fromisoformat(value) return value def str_to_time(value): if value is not None: value = time_cls.fromisoformat(value) return value def str_to_date(value): if value is not None: value = date_cls.fromisoformat(value) return value cdef class DecimalResultProcessor: cdef object type_ cdef str format_ def __cinit__(self, type_, format_): self.type_ = type_ self.format_ = format_ def process(self, object value): if value is None: return None else: return self.type_(self.format_ % value) sqlalchemy/cyextension/util.cpython-39-x86_64-linux-gnu.so 0000644 00003027040 15125143220 0017373 0 ustar 00 ELF > �F @ `% @ 8 @ # " �9 �9 @ @ @ �� �� 0 0 0 �/ �/ �g �w �w Pm P} P} � � 8 8 8 $ $ P�td XJ XJ XJ � � Q�td R�td �g �w �w GNU H�ҫ�uz���ryew��q � � @� � � ̣��������FY� � � 3 � 4 7 � � h � X i � } O � � b J _ � & * k 0 � < < � � � � � � 5 � � D � � � ] � d K � � � X � � t � B � t � � � - � � u � � � ~ � � G m � � � _ e W | a � * � � � � � � � � H � 5 � � � � ; � � 8 � � m X N R " � i y � � � U � � @ �( \ 9k __gmon_start__ _init _fini _ITM_deregisterTMCloneTable _ITM_registerTMCloneTable __cxa_finalize PyDict_Type _Py_NoneStruct PyDict_New PyExc_TypeError PyErr_Format PyExc_SystemError PyErr_SetString PyDict_Size PyObject_GetAttr PyMethod_New PyUnicode_InternFromString PyUnicode_FromString PyUnicode_FromFormat PyExc_DeprecationWarning PyErr_WarnFormat _Py_Dealloc PyArg_ValidateKeywordArguments PyDict_Next PyDict_SetItem PyType_Modified PyObject_HasAttr PyObject_CallMethodObjArgs PyObject_GC_UnTrack PyObject_ClearWeakRefs PyObject_GC_Del PyObject_GetAttrString PyDict_SetItemString PyExc_AttributeError PyErr_ExceptionMatches PyErr_Clear PyThreadState_Get PyInterpreterState_GetID PyExc_ImportError PyModule_NewObject PyModule_GetDict PyTuple_GetSlice PyTuple_GetItem PyMem_Malloc PyTuple_New PyMem_Free PyErr_NoMemory PyExc_RuntimeWarning PyErr_WarnEx PyDict_SetDefault PyCode_NewWithPosOnlyArgs PyList_New _PyObject_GC_New PyObject_GC_Track PyImport_ImportModuleLevelObject PyObject_RichCompareBool PyObject_IsSubclass PyObject_Call PyErr_SetObject PyTuple_Pack PyBaseObject_Type PyErr_GivenExceptionMatches memcmp PyObject_Hash PyCFunction_Type PyObject_VectorcallDict Py_EnterRecursiveCall Py_LeaveRecursiveCall PyErr_Occurred PyObject_GenericGetAttr _PyType_Lookup PyType_Ready _PyObject_GetDictPtr _PyDict_GetItem_KnownHash PyMethod_Type PyImport_GetModule PyImport_Import _Py_TrueStruct _Py_FalseStruct PyObject_IsTrue PyErr_Fetch PyErr_Restore PyModule_GetName PyUnicode_Concat PyLong_AsLong PyLong_Type PyExc_OverflowError _PyObject_GenericGetAttrWithDict _PyThreadState_UncheckedGet PyExc_NameError PyObject_Not PyFrame_New PyTraceBack_Here PyObject_SetAttr PyCode_NewEmpty PyUnicode_AsUTF8 PyMem_Realloc PyObject_VectorcallMethod PyLong_FromSsize_t PyObject_GetItem PyLong_FromLong PyUnicode_Type PyDict_GetItemWithError PyObject_Str PyTuple_Type PySequence_Contains PyUnicode_Format PyNumber_InPlaceAdd PyDict_Contains PyExc_KeyError PyList_Type PyObject_IsInstance PyUnicode_Split PyUnicode_New memset _PyUnicode_FastCopyCharacters memcpy _PyUnicode_Ready PyUnicode_FromOrdinal PyDict_DelItem PyExc_RuntimeError PyImport_AddModule PyObject_SetAttrString Py_GetVersion PyOS_snprintf PyBytes_FromStringAndSize PyUnicode_FromStringAndSize strrchr PyType_FromModuleAndSpec PyUnicode_Decode __pyx_module_is_main_sqlalchemy__cyextension__util PyImport_GetModuleDict PyDict_GetItemString PyInit_util PyModuleDef_Init libpthread.so.0 libc.so.6 GLIBC_2.14 GLIBC_2.2.5 � ��� � ui � �w l �w �k x x x HJ 0x H @x �D Px �B `x �E px hI �x J �x D �x hH �x FJ �x DJ �x BJ �x 8I �x pG y 0G y �G y �F 0y F @y �C Py �F `y G py �G �y `I �y J �y �I �y XI �y PG �y �F �y �I �y 8J z �I z ?J z 4J 0z (I @z I Pz <J `z �I pz �I �z XH �z �H �z 0J �z �E �z �I �z �C �z `C �z HI { �I { �I { (J 0{ J @{ �I P{ �I `{ J p{ �G �{ �F �{ @E �{ C �{ �G �{ HH �{ �H �{ �H �{ I | pF | 0F | �H 0| xI @| H P| �H `| �I p| �H �| �H �| �H �| �G �| xH �| PF �| �I �| 8H �| �I } pI } (H } J 0} �I �� 0A �� �� ȃ �t �o � �v �� u � pr � `� (� �� 8� �� H� �n `� �2 h� � �� �2 Ȅ �2 � �2 � �2 �� �2 �� @o �� r �� 3 �� @o �� r Ѕ 3 o � } �� 3 � o � } � #3 (� `l 0� �| H� 03 P� �l X� | p� :3 x� �l �� | �� C3 �� pl �� P3 Ȇ pl � \3 � �l � i3 � �l 8� u3 @� �l `� 3 h� �l �� �3 �� � �� �{ �� �3 �� � �� �{ ؇ �3 � �q � �z � �3 � �l � `z (� �3 0� � �� �2 �� � Ȉ � � �G � \X X� hA �� � � �� (� � h� �p � �1 � p� � �1 � � � �1 (� � @� �1 H� @ �� �A 8� l @� 0l h� � � �1 (� � @� �1 H� о `� �1 h� � �� 2 �� � �� H< ȍ `� � �1 � @ � �1 � � � �1 (� � @� �1 H� p� `� �1 h� � �� �1 �� о �� �1 �� � �� �1 Ȏ �� � 2 � `� ( 0 8 @ # H + P , X = ` @ h A p C x E � R � W � � � Z � \ � _ � d � g � i � l � o � r � v � z � � � � (� 0� 8� @� H� P� X� `� h� p� x� �� �� �� �� �� �� �� �� �� Ȁ Ѐ � � � �� ! � " � $ � % � & � ' (� ( 0� ) 8� * @� - H� . P� / X� 0 `� 1 h� 2 p� 3 x� 4 �� 5 �� 6 �� 7 �� 8 �� 9 �� : �� ; �� < �� > ȁ ? Ё A B � D � F � G �� H � I � J � K � L � M (� N 0� O 8� P @� Q H� S P� T X� U `� V h� X p� Y x� [ �� ] �� ^ �� ` �� a �� b �� c �� e �� f �� h Ȃ j Ђ k m � n � p � q �� s � t � u � w � x � y (� z 0� { 8� | @� } H� ~ P� X� � `� � h� � H��H�]? H��t� H��� �5�? �%�? @ �%�? h ����%�? h �����%�? h ����%�? h ����%�? h ����%�? h ����%�? h ����%�? h �p����%�? h �`����%�? h �P����%�? h �@����%�? h �0����%�? h � ����%z? h �����%r? h � ����%j? h ���%b? h ����%Z? h �����%R? h ����%J? h ����%B? h ����%:? h ����%2? h ����%*? h �p����%"? h �`����%? h �P����%? h �@����% ? h �0����%? h � ����%�> h �����%�> h � ����%�> h ���%�> h ����%�> h! �����%�> h" ����%�> h# ����%�> h$ ����%�> h% ����%�> h& ����%�> h' �p����%�> h( �`����%�> h) �P����%�> h* �@����%�> h+ �0����%�> h, � ����%z> h- �����%r> h. � ����%j> h/ ���%b> h0 ����%Z> h1 �����%R> h2 ����%J> h3 ����%B> h4 ����%:> h5 ����%2> h6 ����%*> h7 �p����%"> h8 �`����%> h9 �P����%> h: �@����% > h; �0����%> h< � ����%�= h= �����%�= h> � ����%�= h? ���%�= h@ ����%�= hA �����%�= hB ����%�= hC ����%�= hD ����%�= hE ����%�= hF ����%�= hG �p����%�= hH �`����%�= hI �P����%�= hJ �@����%�= hK �0����%�= hL � ����%z= hM �����%r= hN � ����%j= hO ���%b= hP ����%Z= hQ �����%R= hR ����%J= hS ����%B= hT ����%:= hU ����%2= hV ����%*= hW �p����%"= hX �`����%= hY �P����%= hZ �@����% = h[ �0����%= h\ � ����%�< h] �����%�< h^ � ����%�< h_ ���%�< h` ����%�< ha �����%�< hb ����%�< hc ����%�< hd ����%�< he ����%�< hf ����%�< hg �p����%�< hh �`����%�< hi �P����%�< hj �@���AVI��AUI��ATUH��QH�� �c���A�ą�uML�����H�5-L H���U�����t2H�5L H��E1�L��L��1�����H��H��t H�u �5����A��ZD��]A\A]A^�AVI��AUI��H��ATUSD�����H��t5H;�7 H��uE1��tH��L��L������A��H�M u)H������� H�8 A��H�8� �����t���E1�[D��]A\A]A^�AVAUI��ATUQ����H�x���H���t1H�; H���u H�r; �#H9�t H��7 H�5�� H�8���E1�� L�%�K M��t I�$�� H�5�� L�����I��H��t�H���)���I�H��uL��� ���H��t�H���\���I��H���� A� H� � H��L��H�� �����xkA� H� � L��L��H� � �����xHA� H� �� L��L��H��� �h�����x%E1�H� �� L��L��H��� �H�����xI���H�M ����H���P���ZL��]A\A]A^�QH�G��� �u H��H�5 � �1�H9W t H��H�58� H��5 H�81��G�����Z�AWAVAUI��ATE1�UH��H��SH��H��A�׃�H��A��H��(H�t$L�D$H�T$��H���� H�T$L�D$I��1�H�t$H9�~H� �H�I�L�H����L��L��L������I��H��t]H�F I��H��H��I����H��A��H����H����L��E ����A�� APSAUUPPATPPAPE1��!���H��PI��I�uL��� ���H��(L��[]A\A]A^A_�ATUSH��0�N���H���� H��H� ;G I��H��G H��G I��L��H��8 T H�$���H��E H���� H��G H� �F I��L��H�^G H��P > H�$�q���H��E H���b H� H H� MG I��L��H� G H��h N H�$H�G H�D$H�gF H�D$H�F H�D$H��G H�D$ H�H H�D$(���H�:E H���� H� �G H��G I��L��( F ( wG H�� U f��G f� �G )D$) $���H��D H���� (6G I��L��fl�F H� AG H�ZG H�� H��)$�R���H��D H���C �E �E I��L�� �F :F H��� 8 H��F H� �E f��)D$H��E f��) $H�D$ ���H�?D H���� H�F H� �E I��L��H��E H��� $ H�$H�vE H�D$H��F H�D$H�FF H�D$���H��C H���s H� F H�VF I��L��(�D ( F H�� W f�?F f� F )D$) $�&���H��C H��� (�E H��I��L��flpE H� �E H��E )$���H�ZC H���� %*E 3E H�� M I�� /E H��L��H�E H� +E H��E f��)D$f��H�D$ ) $�}���H��B H��tr5�D �D H��I�� �D H��D L��H� �D H�0E f��)D$f��H�D$ ) $�!���H��B H��tH�M A� u H�����H�M uH�����A��H��0D��[]A\�H��X� H�t$(��H�t$`H�|$ �D$ H�t$H�|$H��tH�WH�HH�H�H��X�AWA��AVI��AUM��ATUH��SL��H��H�=(A H�T$�>�H�T$H���5 fIn�fHn�D��� I��fl�H�@( H�@p @H��tH�E I�l$ I�D$@ I�D$H H�I�T$PI�D$X I�D$8 M�l$`I�E H��tH�A�FW�I�\$hI�D$x A�$� %� IDŽ$� A�$� ��t6��tK��uQH�y6 I�D$0�l=� t#=� u5H��5 I�D$0�PH��% I�D$0�BH�A5 I�D$0�4I�D$0 �)H��. H�5� H�8���I� $uL���+�E1��L����H��L��[]A\A]A^A_�AWAVAUATI��USH��H��(L�wH��. I9�� t �/ H���* I�� tL��L�����I��H��u�EL���P��y�� H� H�@��� u1L�� M��tH�� �� �D$ ��D$ E1�� �D$ E1�H�����H��tBH�8H��t:H�I�T$L��H�|$���H�|$H��H���� � �H�|$H�u� �|$ �� M��t H�SH��L��A��I�H��u:L������0L��M���� H�. I�VL��H�5�� H�81����� H���� H�E- H9EusH;]umL�}I�H�M uH���|�H�t$L��H� �H�D$ H�\$�5 I�I��u_L���G��UH� H�u�8�M��t�I�u�L���&�뀺 W�H�t$H��H��?)D$�4 H�M I��u H�����E1�H��(L��[]A\A]A^A_�AUH��I��ATUSH��(H��P u H�� H��u�H��(L��[]A\A]�F�I��P H���� I�� H�q� H9�~pH�D���� u%H�PH�8, H�5�� A��H�81����� H��u3H�� t)H�HH�, H�5�� A��I�UH�81��[�� H���H�=�> ��H��H��uH�=~> �A�H��H���� H�5�> H������I��H��tkH;�+ ����L;%�+ �����uL;%�+ t L�����I� $uL������~#H�5�= H���p���H��H��tH�u#�j�� ���uH�M uH���U�A���� I��� L�����I��� ����A�ą��� H�T$H�t$H�|$��H�5x= H����H��H��u A���u%H��t H�u���H�T$H�t$H�|$����@H�|$H��t H�u��H�|$H��t H�u��H�|$H��t H�u��A��H�M uH����H��(D��[]A\A]�ATI��UQH�5k= �>= H��H��u�A�E1�H��t'�L�� H����A�ą�x�H�M uH���"�D��Z]A\�AWAVI��AUATUSH��H�5�< � �H�-* H��u H�5�= H����H��H��u%� H�5n< H��H��E1����H9��� ��H�5V= L��� H�$H���m H9��� H�5!= H����H��H���] H�5= L��� H��H���L H9�uH�5�< L���&< I��H��tj�#H�5�< H�����A�Ņ�u�E1�1�E1��I H�5�< H��L���g���� I�� H�5�< �<�A�Ņ�u L���M��!y �� H9��� �V�H���� E1�H�5{< L���; H��H���J ��H�5c< L���k; I��H��t>H�5D< H��L�������xnI�� H�5/< ��A�Ņ�u L�����y�FH��tA���H��u7L�����\H�$ E1�1�E1�1��E1�E1�1��E1�1�E1��E1�1���H��u H��' I�VH�5K� H�81���A��H��t H� uH�����H�<$ u �+E1�1�E1�E1�H�$H� $H� H�D$H��H�uH����M��t I�uL���}�H��tH�M uH���j�M��t/I� $u)L���W�� H�5 ; H��E1������������� ���H��D��[]A\A]A^A_�AWAVAUATUSH��� H��; H��t)1�H9��� H��& H�5�� H�8����� H�H�=L; �/�H�H7 H���I H� H�={� �`�H��tH� H�)7 H���< H�=`� �<�H��tH� H� 7 H�=�: H���+ H��6 H�5=� �:����* H� 6 H��uP�Q�� 1Ҿ I��1�Hc�A� D�I�A�� w k� �D���H��HÀ�.u H�����u�H� �5 H��5 H��H��� �� ��u1���H�g6 H��u|� H�l$RH��H��H���� H��A� ��L� �� � RH�w� PH��� P1����H�� 1�� H���\���y�A� L�5�� A� 1��� 1�H�=K� � �H��5 H���< 1�H�=-� �r�H��5 H���8 L�=+) �. L�����H��tL�xL����I��H��� H�=�� 1���I��H���� H� H��� �H��H���3 L��H�����H��H��u�(�H��t � H� �Q1�H�5�( L����I��H���� H��L��H����H��H��tIH� H�PH�U I9�t&I�M uL���8�HcY( L��H�������x�*H�E H��u!H�����L��H�M �� H��1���I� $uL�����I�u/L������%A� L�5�� A� 1�H�i4 �C H�-]4 H���� H�-�# H�&6 L�%/ fHn�H� L�5�� fHn�fHn�L��`���fl�94 fHn�fl�)Q4 I�<$H��trA�D$ � t1�@t���6A�t$��Hc�$ t��1�I���G���`��A�t$��Hc���H���Y I�E H���)�H���D I��I��녿 �|�H��6 H��� �Z��b�H��6 H��� � �~�H�H��6 H���� ��C� �.�H��6 H���� ���A ��H��6 H���� �>�� ��H��6 H���� �D ;���H�y6 H���� ��I��H���i H�" �8 � �j�I��H���e H�5�� H�����H���( H�=w4 ��6 H�+6 H���N H� �5 H��5 � 1�H�5�5 ��H��2 H��� A�, A� � L�5�� H�=�5 tFH�=�1 t��tL��D��H�=�� D����8 H�=�5 H��t7H�H��5 u'�#�� ��H��uH�@! H�5�� H�8��1�H�=o5 ����� H��3 H�5�3 H�=P5 �S�������A�! A� � L�5�� �=���H� 5 H�5�� L���x��������A�& A� � L�5�� ����H� �4 H��4 � 1�H�5�4 �B�H�{1 H��������B����� H�. H�=', H�- - H�=�0 H� H�4 H�E0H�4, H��8 H�.- ����� H��0 H�53 H�=L4 �O���xlH�=�0 �����x\H�=t) H�}( H�=x0 u+H�E0H�-[* H��) H��8 H�~* ���x �9H�D H�UH�5�� H�81���A�2 A� � L�5o� ����H� 0 H�5<1 H�=�3 ����x�H�=�/ ���x�H�5�0 � 1�� �H��H���� H�=&1 H��� I��H���� H�M uH�����H�5}0 L����) H��H���/ H�5b0 H�=#/ H���{����� H�M uH����I�uL���x�H�5�0 � 1���I��H���D H�=*2 H���Z H��H���� I�uL���1�H�5�0 H���B) I��H���# H�5�0 H�=�. H�������� I� $uL������H�M uH������H�m. H�=>2 H� H�H�12 u���L� �. L�,. 1�H�=- H� |1 H��/ ���H��H���� H�5�/ H�=�- H���N����� H�M uH���X��L� �. L��- 1�H�=�, H� 1 H��/ ��H��H���G H�5�/ H�=�- H��������_ H�M uH�����L� 7. L�h- � H�=�+ H� �0 H�0 �-�H��H���� H�5�/ H�=w- H������� H�M uH�����L� �- L�- � H�=w+ H� P0 H��/ ���H��H���� H�5�/ H�=- H�������� H�M uH���,��L� }- L��, � H�=�* H� �/ H�T/ �c�H��H���o H�5�/ H�=�, H���=����x H�M uH������L� - L�9, � H�=m* H� �/ H��- ��H��H���' H�5 . H�=P, H��������+ H�M uH���b��L� �, L��+ � H�=�) H� !/ H�J- ��H��H���� H�5. H�=�+ H���s����� H�M uH�����L� f, L�o+ � H�=c) H� �. H��, �4�H��H���� H�5]. H�=�+ H�������� H�M uH�����L� , L� + � H�=�( H� W. H��, ���H��H���O H�5(. H�=!+ H�������; H�M uH���3��L� �+ L��* 1�H�=\( H� �- H��- �m�H��H��� H�5~- H�=o* H���������� H�M uH������L� R+ L�C* 1�H�=�' H� �- H�,- � �H��H���� H�5- H�= * H���e������ H�M uH���o������H��H���� H�5O- H�=�) H���(�����y H�M �5���H���.���(���E1�A�A L�5A� A� �Z M��A�F A� L�5 � �? E1�A�V L�5 � A� �$ M��A�X L�5�� A� � A�q L�5�� A� �� A�} L�5�� A�( �� A�� L�5�� A�4 � A�� L�5o� A� � A�� L�5W� A� � A�� L�5`� A�H �|A�� L�5K� A�T �gA�� L�5� A� �RA�� L�5 � A� �=A�� L�5�� A� �(A�� L�5�� A� �A�� L�5�� A� H�M uH������ M���'���I�� ����L������ ���1���A�� L�5�� A� 1����A�� L�5w� A� 1�����A�� L�5]� A� 1����A�� L�5C� A� 1����A� L�5)� A� 1����A� L�5� A� 1��i���A� L�5�� A� 1��O���A� L�5�� A� 1��5���A� A� � L�5�� ����A�$ A� � L�5�� ��A�* A� � L�5|� ���A�- A� � L�5_� ��A�? A� � L�5B� ��A�Q A� � L�5%� ��A�o A� � L�5� �j�A�{ A�( � L�5�� �M�A�� A�4 � L�5�� �0�A�� A� � L�5�� ��A�� A� � L�5s� ��A�� A�H � L�5w� ���A�� A�T � L�5Z� ��A�� A� � L�5 � ��A�� A� � L�5�� ��A�� A� � L�5�� �e�A�� A� � L�5�� �H�A�� A� � L�5�� �+�A� L�5�� A� 1���A�D A� � A�S A� M��L�5�� ���H��� []A\A]A^A_�H�=@ �k��f. � �H�=�# H��# H9�tH�� H��t �� � � � H�=y# H�5r# H)�H��H��?H��H�H�tH�- H��t��f D � � �=9# u/UH�= H��t H�=" �m���h����# ]� � � � �{���f. � �H�� H��� H��t�� 1�� D H�a H��� H��t H����1�H���1��ff. � f�H�GPH� � � H�G`H� � � H�� H� � @ H�GhH��tH� �f�H�� H� � @ H��� H��t H� � � H��H�|$� ��H��tH�|$H��� H� H���H�G@H��tH� �f�H��H�|$����H�|$H�G@H��tH� H���ff. � UH��H��SH��H��H�GL�H�@����tV$���� ���� H��H��H��[]A�� ��ukH���� L�FI���$ H�vH��H��[]A�� @ H���� L�F1�M��t�H�CH� 9� H�H� H�5;� H�81������ @ H�1 H�5P� H�8�"��H��1�[]�f � H��t�H��L� $H�T$�J��L� $H�t$H���`����)f D H��L� $H�T$� ��L� $H�t$H���#���H�CH� �� H�5 � H�H�� H�81��7���p���f�H��L� $H�T$����L� $H�t$H�������� H�CH� h� ��� � H�GH��� H��t��f D �#�� H��t �F��f D H�H��� � H�GHH��tH� �f�SH�GH��H�8� ��H�CHH��tH� [ÐH�GXH��tH� �f�SH�GH��H�xH��t����H�CXH��tH� [� H� H� [�ff. � H�wPH��1�H�=� ���ff. � UH�GH��H�P��� t3H�| H�Ѿ H��� H�81��[��A��H��E��u ]�f D H�Q H�5r� H�81����H�m t 1�]� D H���X��1��� @ ATI��H��H�� H�FH�D$ ��� tVH�@h1��PH�D$H��H��t&H�� L��H�5'� H�81��=��H�|$H�/t H�� A\� ����H�� A\� @ H�D$ H�t$�%����t�H�|$1�H�T$H�t$���H�L$H��SH��H�FH��H��H��uZ�C0 1�H��[� H��H��� E1�PH�2 L� d� H� u� H�5�� H�81����XZ�����H��[�f D H��H�$���I�������M��x��D$ t�H�$H�=/� H������D$ �t��� D ATSH��L��� M��tI�$H��L��[A\� D H��� H��H��tA��H��H��t�H�@L�g H��� H� L��� I�$H�/u����L��� � @ L�%q �ff. � @ H��t3L�GXH�H�wXM��tI�(t1�ÐH��L���4��1�H��� D H�5! ��ff. � @ SH��H�pH��tH�Cp H�/�A H�{ H��tH�C H�/� H�{@H��tH�C@ H�/�� H�{HH��tH�CH H�/�� H�{PH��tH�CP H�/�� H�{XH��tH�CX H�/�j H�{`H��tH�C` H�/�? H�{hH��tH�Ch H�/� H�{8H�C8 H��t H�/�� H��� H��tHǃ� H�/�� H��� H��tHǃ� H�/�� H��� H��tHǃ� H�/tZH��� H��tHǃ� H�/t-H�{xH��tH�Cx H�/t1�[�f��{��1�[� � �k����f � �[���f � �K���o���f D �;���>���f D �+��� ���f D ������f D � �����f D ������f D �����a���f D �����6���f D ����� ���f D ������f D ������f D UH������H�}( tH�����H���p���H��]��� � ATI��UH��SH��H�pH��t H��Յ��� H�{ H��t L��Յ��� H�{@H��t L��Յ��� H�{XH��t L��Յ�uH�{`H��t L��Յ�umH�{8H��t L��Յ�u[H��� H��t L��Յ�uFH��� H��t L��Յ�u1H��� H��t L��Յ�u H�{x1�H��t[L��H��]A\�� D []A\�ff. � H����� L�OH��?����t%H��upH�H��u6I�AH�6H����f � H��t{H���� H�>H��H���� D H�� I��I�H� �� H�5�� H�81��;��1�H��� @ H�y t�H� ƹ H�� I�H�5й H�81������ D H� D� �� � H�y �s���� AWAVI��AUATI��UH��SH��hL�G0M���� ��� ����t H�wH��hH��L��[]A\A]A^A_�����H�VL��� � ��I��H���� L��1��I��I��H���M L��L��H��H�����I�m I��tBH��hL��[]A\A]A^A_�L�~H�vH��u;H��hL��H��1�[]A\A]A^A_A��f. � L������f D E1�� H�BH�D$H��t�J�<8L�D$H���8��I��H���$ M��L�D$tWI�F I9��� I�G�H���� L��1�H��H�� �AoDAD H��H9�u�L��H��A��t I�T�I�T� H�|$L�D$�<��L�D$H��H�D$�� K�D� 1�A� L�|$ H��H�D$H�L$PL��H�D$XH�|$HL�l$0I��H�l$8I��H��I��H�D$H L�D$(�; � H�D$PH�L$H�PH#�� H�T$XH� H�J�D�H�D$J��I��L��H��L��L��������u�L�|$ L�D$(I��L�l$0H�l$8H���� H�L$L��L��H��A��I��H�\$H�H�D$ H��H��� H�\$H��~_L�d$1��f D H��H9�tGI�<�H�/u�������f D I�m t6H�� H�UPH�5� H�81�������� � L��������L������H������s���1�f. � I�T�I�T� H��I9�u��=����s��E1��I���L��E1�����9���H� H�5ʶ H�8�������H��H;5 tH��tH�F��� tAH�� 1�L��� H��� M��tI�(t 1�H���f D L��������f D H�� H�5B� H�8�J��������� UH��SH��H�� H9�tH��H��uSH��H�� � H�5]� H�8�U��H��� H�H��� H��tH�/t1�H��[]� � �3����H�F��� u�H�� H�5պ H�8���������f D UH��SH��H�� H9�tH��H��uSH��H� � H�5U� H�8���H��� H�H��� H��tH�/t1�H��[]� � �����H�F��� u�H�L H�5ͺ H�8� ��������f D H��H��t?H�F��� tZL�G@H�H�w@M��tI�(t 1�H��� @ L��� ����f D H�� H�5� H�8��������H��� � H�� H�5�� H�8�z�������� H��H��t?H�F��� t2L�GPH�H�wPM��tI�(t 1�H��� @ L�������f D H�Q H�5º H�8��������H��� � H��H��t?H�F��� t2L�GHH�H�wHM��tI�(t 1�H��� @ L��� ����f D H�� H�5�� H�8��������H��� � AUI��ATI��U�@��H��tKH�5T H��E1�L��L��H������H�m I��tL��]A\A]� D H�����L��]A\A]� � E1�]L��A\A]� @ AWAVAUM��ATUSH��H�G��� �� H�I��H��H��I��I��H��u�I D I�FI��H��t7H�8� L��������tn���uٸ����H��[]A\A]A^A_� D H��H9��� H�� L��H�8�����t܃�u�H�� L��L��H�5�� H�81����������f�I)�I��M�4$H��[]A\A]A^A_�f D H�Y L��H�5 � H�81����H�������[]A\A]A^A_Ð1��E���f � AUATI��UH�H��� H�� @H;5- �� H��H���� � ��( A��$� @� H���� L�nI��� � @t'M9�� L��L���������* H�EH��� � �� H�E 1�H��L������H�m I���� M���� I�M��� @�� L��L�����I�m uu]L��A\A]�[��� H�5Q� H��t!H�� ]A\A]H�8���� � H��t]L��A\A]�N���f D � �t)A��$� @t 1��/��H��H���D���]A\A]� D H�5a� � � ]L��A\A]��� H�� 1����H��� @ H��������� ���t�H��L��]A\A]��� H�Q� L��H�5�� H�81������� � H�GPH� � � L�VI��I��M���� 1��f � H��I9�tM9D�u� �f. � 1�f D I�T�H�B��� �tv��� @tmL9�t�I��X H��t,H�qH��~S1�� � H��H9�t?H;T�u��f D L�� D H�� H9��x���H��u�H;�� �f���f D H��I9��k���1��H�G��� ��� ��� @t~H�FH��� � �tt��� @tkH9�t.H��X H��t*H�JH��~A1�� D H��H9�t/H;t�u� �f�H�� H9�t�H��u�1�H;5� ���f�1�� D �c��� � t��t��� @ H�� H��� H��t H����1�H���1��ff. � f�H��� H��� H��t�� 1�� D AWAVAUATI��UH��SH��H��(L�wH�L$L�D$I����� H�E H���� I�L$0I��M�l$HH�L$�I�GI��H���� H� L9pu�L�@M;D$u�D�X A�T$ D�މ�@��@������@8�u�A�� �V H�x0H��HA��@HD��� �- L�\$��@MD�@��L��I���Y������q���H�D$I)�I��L�8� H��([]A\A]A^A_�f D H9��� M�l$0M�|$H� H��H9��� H�H� L;pu�L�@M;D$u�D�X A�T$ D�މ�@��@������@8�u�A�� �� H�xH�� �� ��@M��MD�@��L��I��蘾����u�H��� H�T$L��H�5�� H�81���������-���f. � H��(1�[]A\A]A^A_� � M�\$H����f D H�xH��� � H�x0H��HA��@HD��� �]���M�\$H�]���耿��I��H�������������f � ��� L�GH��?����t H�A�`�H��tH�>H��H��A�` @ H��H��� I�H� ^� H�5˪ H�81�����1�H���ff. � ��� H��?I��I��H��H�W����tL�WH�w8H�BL��L��� @ H��t#L�I��H�w8H��H�BL��L��� � H��H�� H�H� ƪ H�53� H�81��j���1�H��� H����� L�OH��?����t H��u`H�H��u'I�A1�H���� H��tsH��u~H�>H���� D H��� I��I�H� <� H�5H� H�81����1�H��� @ H�y t�H� v� H�[� I�H�5�� H�81�跾���� D H� � �� � H�y �w���� AUI��I��I��ATI��?UH��SH��H�� H�wM���� I��tCH9��� ��� �� H�F8H�D H���� H��H��1�L��[L��]A\A]�� @ H9��� H�=(� H9��� L��X M���� I�[H��~&1� @ I�L�H9��" H9�� H��H9�u�� �n���� �M���� H��H��1�L��[L��]A\A]� ��� D H9�� H�=�� H9�� L��X M���� I�[H��~&1� @ I�L�H9��� H9��� H��H9�u�� ���� H��� L�%j H���� H�=�� ������� 1�L��H���I���c���M���� H��L��[]A\A]� @ H�E0��� � H�� D H�� H9�t4H��u�H� x� H9�t#H��H�� H9�tH��u�H9��F���f D H�M�A��1���H�YE1� uL�eH�=˯ �F���1����� L���I��诺��M���L����q���I��H���� H�n� H�5�� H�8�_���� ���H�� � H�� H9�t4H��u�H� �� H9�t#H��H�� H9�tH��u�H9������f D H�M�A����M�)H�YE1� uL�eH�=� 胶����uL���;��� � E1���� � H�M�A����� @ H�M�A�u�����H��L��H��1�[]A\A]�����AWAVAUI��ATUH��SH��H�GH��� H��t ��I��M��t"H��L��[]A\A]A^A_��+���I��M��u� H��� H�8�ѷ����u H��� L��H�5"� H�81�袺����K���H���3���H��H��t�����H��H��t�H�5 H��诺��I��H��teL��H��蜺��I��H��tjH��� ���I�/H��t#I�.t'H�m t*H���p���I���3��� D L���ص����L���ε����H���ĵ����H�m �:���H��诵���-���1��f D ATSH��L��� M��tI�$H��L��[A\� D H��� H��H��tA��H��H��t�L�`H�@ L��� I�$H��� H� H�/u��5���L��� � @ L�%!� �ff. � @ ATUH��H��H�G��� �� H�L�eI�D$H��v2I���t|I��t^H���n���I��H�m t6H��L��]A\�f � M��t�HcE���I���Hc�HE�H�m I��u�H��膴��H��L��]A\� D�e �EI�� I �� � D�e �EI�� I �I��� D H�@`H��tGH��� H��t;��H��H��t1H�@H;F� u:��� � ���H�����I���4��� � 胶��H��tvI������ ���H�P��� t*H��� H�Ѿ H�� H�81��u�����u H�E�H�t� H�5�� H�81��ӷ��H�m u�H��I������}������H�A� H�56� H�8�����o���ff. � f�H�G��� t{H�GH�PH��vH���tOH��t1�ĵ�� @ H��tHcW���H���Hc�H��HE�� @ � � �G �WH�� H ��f. � �G �WH�� H �H��� � UH��H�@`H��tnH��� H��tb��H��H��tXH��� H9Eu � H���8���H�m t!H��]�H����H��H��u�H�������f�H��H�D$�S���H�D$���״��H��u�H� � H�5 � H�8�̲���f. � ATUH��H�G��� �� H�GH�PH��v2H����� H��tJ腴��Hc�A��H9��� H��D��]A\� E1�H��t�D�gD���H���DD�H��]D��A\� @ �G �WH�� H �Hc�A��H9�t�H�y� H�5�� A�����H�8� ����f. � �G �WH�� H �H��Hc�A��H9�u�H��D��]A\�f. � H���u�赳��H��t�A������?��� D H�@`H��t\H��� H��tP��H��H��tFH�� H9Eu' @ H�����H�m A����H���°�����H������H��H��u���6���H��u�H�j� H�5_� H�8�+����f���f D AUATUSH��L��� M��tI�$H��L��[]A\A]� � H����� u$L�% � I�$H�PI�$H��I�$L��� 뻿 H�-� �Ϯ��I��H��t�H�@H�E E1�1�1�L��H�(H�=� ����I�,$I���� M��tbI�EH��L��H��� H���� ��H��I�m tlH��t7H�U L��� M��tnH��H�U � ���H��聯��L��� � ��� D �[���H�-l� H�E H�PH�U �f D L���H����l��� L���8�������H���v���I�����H�GH��� H;�� u � 1��Ю��AVAUATUSH��H��t ��I��M��t%H��L��[]A\A]A^� D �[���I����f D �ۭ��H��H��� H�{XH�(H9��� H��t�H�EH��� � � H�W��� ��� ��� @�� � ��� ��� @�� H��X H���� H�JH���N���1�� � H��H9��6���H;l�u�H�khH�Ch f�L�k`CXH�/t`M��tI�m t[H�������H�m ��H���έ�����H���Q���������H�{Xf�L�k`H�khH�Ch CXH��u��葭���L��臭���L�mM�������1�� H��I9�t6H;|�u��K���H��H�� H9��8���H��u�H;-`� �&����P���E1�J�t�H9��k���H�|$��H�|$���T���I��M9�u�����ff. � @ AVAUI��ATUSH��H�=b� H�GH��� H;�� u.� 1�L��臬��I��H��� H��L��[]A\A]A^� L��H���< ��I��M��u�蝫��I��H��� I�|$XH�(H9��0 H���� H�EH��� � �S H�W��� ��� ��� @�� � ��� ��� @�� H��X H���3 H�JH��~d1�� H��H9�tWH;l�u�I�l$hf�M�t$`I�D$h AD$XH�/�� M��t I�.�� H��tH�m uH��薫��f D ����I��H��t E1����� H��� L��H�5J� H�81�蝯����� � �ۯ��I�����H���˫����t�I�|$Xf�M�t$`I�l$hI�D$h AD$XH���I����N��������D���L������F���L�uM���S���1�� H��I9�t6H;|�u����H��H�� H9�����H��u�H;-�� ��������1�H�t�H9��Y���H�|$��H�|$���B���H��I9�u�����ff. � AWAVAUI��ATA��UH��S��H��8�b���H�=� I��H���� H�@XM�~hI�Fh f�H�$I�F`AFXH�D$褭��H��H��� H�8H��� H9G�� L��� M���l I� H��� I9��K L;�� t L��L�D$�*���L�D$��� DE�I�(�V �~$I�~XM�V`M�FhM�~hD$AFXH��t H�/�5 M��t I�*�B M��t I�(�H E���� H�5�� H���� D�|� A��D�׃��� �V1�A9������A9��� H�H��H�D;x�� L� I�$H�Z� 1�L��L��� ���H��H���� �XlH���&���I�,$uL��觨��H�m H���� H��8[]A\A]A^A_�f. � H�5� E��A��H���Q D��� D�׃��B���Hc�H��D;|� ���(���1��f � �%����H9�������)ʉ�� ���Hc�H���TA9�}Љ��� @ I�,$�T���L��H��8[]A\A]A^A_�ק��L��L��H�T$�W���H�T$��tNH�zXf�L�B`L�bhBXH�Bh H��t H�/�� M��t I�(�� M��tI�,$uL���p����[��� H�A� H�5�� E1�H�=� �˩�����f D I�FXf�H�$I�F`AFXH�D$I�FhI�Fh H�D$E��� ��L��H��� ���I��M���� �~$I�~XH�D$M�n`D$I�nhAFXI�FhH��t H�/�� M��t I�m �� H��t H�m �� H�=�� E�������H���� �� �r�A���� Hc�H��D;|�� ���� 1�� D �� �MA9��� D��)ȉ�� ���Hc�H���DA9�}�A����I�FXf�H�$I�F`AFXH�D$I�FhI�Fh H�D$L��D��H�� 1�H�=ԕ 胤��I��H���� H���O���H��H���� ��H���ɪ��I�m I�������L��蓥������G1�f � A9������9��� Lc�I��I�E;z� 9�� �� Hc���H��H���oHc���H��H�� 9�|��E�zM�"�n� I�$�+���I�m u L����� D H� $H��tH�H�D$H��H��� H�\$H��tH�H�$H��H��� H�\$H������H�H��H�$H��H�����������9� � D�j@Ic�H��败��H��H�������LcՋ�� H��� I��D�-�� I�9�� ����r����L���2������L�D$L�$� ���L�D$L�$���L��L�$����L�$���L�������H�=x� H�5� H�GH��� H;�� �� � 1�荣��H��H���A���H�|$�'���H�|$���) L��� H�l� I� H�/�% I9�����I��E1�����I�FXf�A��H�$I�F`AFXH�D$I�FhI�Fh H�D$�+���H���/����n���H���"����C���H�������p���L�������S�������9���H�5"� H�L$H�V蔥��H�L$H��I���� H�L�q� H�@H�n� ����� �_���H������H�o� H��� H��� D�xL� I�$���Lc�I��I��K���H�J� H� I��H�/���H�D$L�D$�J���L�D$H�D$�r���I�:M�"I�$H�/�E����!����;���H�D$����L�D$H�L$�0���H���� ��H��H���;�������H��H�� L�bXL� M9�����M���T���I�@H��� � �� I�L$��� �����A��$� @������ ������A��� @�����I��$X H��t.H�q1��L;D������H��H9�������ѥ��H���D���M��$ M9��j���M��u�L;<� �X������M�P1��M;d��@���H��I9��1�I9��z���I�t�I9�� ���L��H�T$H�L$(L�T$ L�D$�P�H�T$�������H�L$(L�T$ L�D$H���L�D$蔠��L�D$���L��肠�����ff. � f�AWAVAUATUSH��(H� [� H9��: H�FH��H����� H��� H�5y� H�F��� �8 H�GI��H��� H;�� �E � 1��ɟ��H��H���� H�/�# I�D$H�5 � L��H��� H���� ��I��M���� I�$H�} �� H�mH�E fHn�H�=�� fIn�1�fl�H�t$H� �)D$���I�,$I���� H�m �� I�,$�� �� � M��tBI�m tcH�H��(H��[]A\A]A^A_� D H��� H�5j� H�8袟���� � H� �� H�=�� ��H��(1�[]A\A]A^A_� @ L���Ȟ���f D 軞������f D L��訞���Z��� H��蘞���?��� L��舞���$��� �� � �y���H��L�������tZI�|$Xf�M�l$`I�l$hAD$XI�D$h H��t H�/� M��t I�m � H��tH�m u H��� ��� D 蓠��H�������� � �� H��� H�5b� H�8�r����� � ���� H���� ��H��H��������Ĝ��I��H��� M�l$XH�(L9��'���M���x���H�EH��� � �f I�U��� ����A��� @����� �������� @����I��X H��t0H�JH������1��f D H��H9������H;l�u����M�� L9������M��u�H;-�� �s��������[���I������ �� � ����1��9���I��H��t H��H���v���I�m H��tZH�����I�$H��I�$t5H���� � I�$�e���L��t$ �T$�M����T$�t$ �H���L���8���I�$�L���*����賠��H���i����������L��� ������L�}M�����1�� H��I9�t L;l�u��|���E1�J�t�I9��k���L���U�����[���I��M9�u����ff. � @ AWH�g� AVI��AUATI��USH��XH�D$ H�D$@H�D$H H���� L�yH��M���� H���� H��tvH��H� � H�J� L� 3� AVA� H� ?� H�5g� H�81��� �H���XZf D H� !� �T ��E1�H�=8� ��H��XL��[]A\A]A^A_ÐH�H� H�D$ H�EN�,� L�\$@O� +��� �� H�D$ I�1�H�D$ I�L�T�L��H��u� H�PH��H���� L;u�I�T� L)�H�H�T H��I9�u�M�� J�|� �� H�\$ f�I�$Ic|$0�ћ��H��H���� H�V� H9G�� H�I��H�H���� L;%�� �# L��H��L��距�����8 I�} � A�D$0I�,$�{ H��A��1�f. � H�������E�������H�+� u�H���{�����f � H�D$8 H��� I9B�Y L��L��L��L�L$H�L$8L�R� L�\$L�$���L�$L�\$L�L$���� ����� H��� L��H�� H�5� �� H�81��'���H�|$ H������H�/�����ʘ������ D I���p���H� H�H�\$ �u���L��蝘��I�E A�D$0H������L��肘�����H��H�B� H� �� H�5�� AVL� a� A� H�d� H�81��� ����Y^�Q���L���0����x���I�D� H�T$8H�L$H� H������ �������H��L�\$L� $�T������� L� $E1�L�\$I�L��H��u2�I H��H� I��L)�H�D H�CH��H��� M9��[���H�0H��L�\$L� $�Ϝ��L� $L�\$H��u�L�\$L� $����L� $L�\$H��t��� �t����� f D H� q� �X ��E1�H�=�� ����p���H�<$�u���H�<$H��I��H��� H���� H�u�����L��L��L��L�L$H�L$8L��� L�\$L�$�U��L�L$L�\$L�$���H��� H�5�� �� H�8�G���I�m �L���L��듽� ��M9��?���H�D$( L�d$0H�\$(H�D$0 L�l$81�L��H��H��L�\$L� $轙�������L� $H�|$0L�\$I�L��H��t @ H;8t�H�BH��H��u�H�D$8 H�N� H9GuaL��L��L� � L��L�L$L� $�r��L� $L�L$���j������c���H��� H�L$0H�˅ H�5Έ H�81�����:���L��L��L��� L��L�L$L� $���L� $L�L$��� ����H���f��� @ AWH��� I��AVAUI��ATUSH��XH�D$ H�D$@H�D$H H���E L�IH��M���5 H���� H��tvH��H��� H�� L� � AUA� H� �� H�5'� H�81��� ����XZf D H� �� � ��E1�H�=0� �C�H��XL��[]A\A]A^A_ÐH�H� H�D$ H�EN�$� L�|$@O�4'��� � H�D$ I�1�H�D$ I�L�T�L��H��u� H�PH��H���� L;u�I��L)�H�H�T H��I9�u�M�� J�|� �4 H�l$ L�%�� H�EL9�t H;�� �[ L��H���X�H��H��� H�(�N I�$H�m �����H��蚓���� D H�D$8 H��� I9B�� L��H�L$8L��L��L��� L�\$L�L$L�$����L�$L�L$L�\$���� ����x H��� L��H�?� H�56� �� H�81��G���H�|$ H���9���H�/�/�������%��� D I������H�.H�E H�l$ ����H��H��� H� Ӂ H�5�� AUL� �� A� H��� H�81��� �Ɩ��Y^�x���I��H�T$8H�L$H� H���R����_������H��L�\$L� $詒������ I�E1�L� $L��L�\$H��u6�� D H��H� I��L)�H�D H��H�M9���H���� H�0H��L�\$L� $� ���L� $L�\$H��u�L�\$L� $�T���L� $L�\$H��t��� ���� H� �� � H�= � E1��,�����L��H�L$8L��L��L��� L�\$L�L$L�$����L�\$L�L$L�$� ���M9��:���H�D$( L�d$0H�\$(H�D$0 L�l$81�L��H��H��肔�����T���I�H�|$0L��H��t f. � H;8t�H�BH��H��u�H�D$8 H�� H9Gu}L�� L��L��L���C����t�����H�o� H�L$0H��� H�5�� H�81�������� D H�HH�=� H�5�� H��� H�81�蕔��� ���L�f� L��L��L�������� ����z��� � AWH�w� f�AVfHn�AUATI��H�HH��UH��SH�� )D$@fHn�fl�H�D$pH�D$P H�D$x )D$`M���� M�t$M���� H���k �N H��tH���� H�H� H�D$@I�D$L�,� L�T$`O�<*��� � H�D$@I�1�H�D$ I�M�\�L��H��u� H�PH��H��� L;u�I�T� L)�H�H�T@H��I9�u�H�\$@H��8H�|�@ �� H�EH��t"H�|�@ �� H��H��t H�|�@ �� H�|$HH�G��� �k H�oH�EH���� H����K H��� �o �GH�� H �H��L�t$P� ���I��H���f H�=�� H���d���A�Ņ��� I�,$�E E���M L�%�� H�=7� 1�H�t$`H� �I�$L�d$`H�\$h肑��I�,$H���� H���� L;5�� t2I�FH;�� �i H��L���V�H��H���� H�(�� H�E I��H�E H��� H�|$@H��t H�/� H�|$HH��t H�/� H�|$PH��� H�/� �W���� H���� H�FH� H�D$PH�FH� H�D$H���f � H�D$8 H�X� I9C�_ L��L��H�L$8L��L��� L�T$L�\$�r��L�\$L�T$���� ����� H��� L��H�}� H�5� �� H�81��ߐ��H�|$@H��t H�/�� H�|$HH��t H�/�� H�|$PH��t H�/�� H� c| � ��E1�H�=3� ���H�Ĉ L��[]A\A]A^A_ÐH��urH� H�~H�FH�H�\$@H�H�|$HH� H�D$P�?���H��H��H��� H� { H�53 UL� �z A� H��� H�81��� ���Y^����H��H�}� H�n� L� �z UA� H� �z H�5�~ H�81��� 軏��XZ��������H��H���������H��� H����������o �GH�� H �H����I�D� H�T$8H�L$H� H��� ���H�������HcG���H���Hc�HE�H���L����E�������� 螉��I��H���� H��� I�T$H� H�L�-�� ����I��H���� H�5 � E1�L��L��H��迍��I�.I���� I�$H��M���� I�$H���) H�5-� L���u��I��H���� H�8 �@ I�m �( H���܋��H��H���� H�=�� H��豎��I��H�E M���� H��H�E �? L��L��O ���I�m � H� �y � ��H�=�� �^��I�,$t=E1�����誉���B���蠉���$���薉������H��艉�����������L���r�����k�����L���^����e���L��L�T$謉����tsI�E1�L�T$L��H��u2� H��H� I��L)�H�D@H�CH��H���T M9������H�0L��L�T$�3���L�T$H��u�L�T$�o���L�T$H��t��� �,����ƈ������L��蹈������H��謈�����L��L��H�L$8L��L�Z� L�T$L�\$���L�T$L�\$����' A� I�,$t H� bx D���H�=7� �������L���=�����L���3�������H� .x � �h H�=�� ����U���L����������H��������L������c����� H� �w � H�=�� E1��e��H�E H������M9������H�D$( H�l$0H�\$(H�D$0 L�l$81�H��H��L��L�T$����������I�H�|$0L��L�T$H��t @ H;8t�H�BH��H��u�H�D$8 H�~� H9G�� L��L�� L��L��L�T$���L�T$���v������'���H��� H�L$0H��� H�5z H�81�������� �7 A� �W���I�m uL��豆��H� �v � �: H�=�� �4������ � �H ���H��H�E �� H� pv � �J H�=@� ��������� ���H�@`H��� H��� H��� ��I��H���� H�@H�-6� H9��4 ��� � I�l$H�EH��v/H���teH��tAL���u���H��I�,$�[���L��迅���N���H��t�IcD$���H���Hc�HE�H����A�l$ A�D$H�� H �I�,$�����A�l$ A�D$H�� H �H���H�HH�-� H�5�u H��u H�81�腉��� �[���L��L�� L��L��L�T$���L�T$�������� ���H� u � �2 H�=� ����5���H������o���H�@`H���� H��� H���� L���I��H���� H�@H9�us��� t]I�EH�PH��v7H����� H���� L������H��I�m �����L���_������1�H��t H��A�mu��Hc���L���*��H����H�P��� �� H�� H�Ѿ H�^v H�81��Ĉ������ I�E�K����~���H��tSI�,$�|���L���փ���o���H�P��� tFH��� H�Ѿ H��u H�81��d�����u�I�D$���H�_� H�5Ts H�8� ����H�G� H�5hv H�81�覇��I�,$������x���H� � H�5@v H�81��~���I�m �J���L���+����=���豅��H�������H�� H�5�r H�8袃�����H� �r � �% H�=�} ����$���A�m A�EH�� H ��U���A�m A�EH�� H �H���>���AWAVAUATUSH��H���) H��H���m H�5�� L�-� H�FI�E ��� �y H�CH��� H;G� �Q � 1�H������I��H���> L�=/� M9��G � �L���H��H���� I�$H��L��L�`�l���I��H���` H�m �� I�m �� H�=S� H��� H9G�j L�-�� M���� I�E � �Ӄ��H��H���� H�C� H� H�EH��� H� H�E L�}(I�蚃��H���� I�fIn�fHn�M��fl�H�J@I�L�p(I�U H���� L��H�$�%���H�$M���� H��[]A\A]A^A_�f � H��H���� ��I��M�����������H��H�� H�}XL� I9��� H���� I�D$H��� � �g H�W��� ��� ��� @�u � ��j A��$� @�[ H��X H���F H�JH��~^1�� f�H��H9�tOL;d�u�L�ehH�Eh f�L�u`EXH�/�[ M��t I�.�V M��tI�,$u L����� 胂��H���� L�=� I�H�=X� H��� H9G�� L�%�� M���� I�$� ���H��H���� H�C� H� H�EH��� H� H�E I�E L�m(螁��H���� I�u fIn�fHn�M��fl�H�V�@I�U H��� ���I�,$t4H��[]A\A]A^A_� D L������9��� H������ ��� L��H�$��~��H�$H��[]A\A]A^A_ÐH�] A� H�S��S H�U H���X I�m � H��t H�(�f D��H� �n ��M��H�=�y �+��I�H�P�1�I�H���;����@����H��H�5� E1�L� dm RH� tm H��n H�8H�5�q 1��{���XZ1�H��[]A\A]A^A_� � 1�H�y ����H�$�|���H��H�=Sn 説��H�$����H���x���I��H��������|��H��H�� H�}XL� I9��� H���K I�D$H��� � �: H�W��� ��B ��� @�5 � ��* A��$� @� H��X H���� H�JH���� 1�� @ H��H9��� L;d�u�L�ehH�Eh f�L�u`EXH�/�= M��t I�.�! M������I�,$�����L����|����f. � I�E A� �H H��I�E � ���L��H�D$D�$�|��D�$H�D$���� @ 1�� A� H�u M��H�V�H�U H�������E1�H��H�D$D�$�W|��M��D�$H�D$��������H��D�$�4|��D�$��� � � H� l H�=8w ���I�E H�P�1�I�U H��������� � H�-i� H�UH���~��I��H�K� L�%�� H�@H��� M��������}��H�����I��M�����M��� �t H� �k H�=�v ���I�E H�P�1�I�U H���%����*��� H�-�� H�UH���}��I��H��� L�-T� H�@H�Q� M���n���� }��H���#��I��M���Z���M��� �F �k��� D H�=q� ����I���<��� @ L��M��M���v A� ���� � H�=9� ���I��� � L�ແ A� M������H��H�� I9��K���H��u�L;%�� t+E1� �� �9�����~��I���[���L����z����t�H�}Xf�L�u`L�ehH�Eh EXH������� ���L���z����� ���H�}Xf�L�u`L�ehH�Eh EXH����������L����y��������y������y�����L���y������ H� �i �� H�=�t �/��I�E H�P�1�I�U H���D���L��H�$�ly��H�$�/���M�t$M��~�1�� H��I9�t]I;|�u�����M�t$M���:���1�� H��I9�tkI;|�u�����H��H�� I9�����H��u�L;%� ��������E1�M9��7���K�t�H9������H�<$�\���H�<$�������I����E1�K�t�H9������H�<$�0���H�<$�������I��M9�u����f D AWAVAUATUSH��H���� H��H���� Hc{0�z��I��H���� � �nz��I��H��� H�5s� L�`H�F��� �F H�CH��� H;� �� � 1�H���w��I��H���� H�ܵ H�$I9��� � �y��H��H���� I�E H��L��L�h�w��I��H�E M���� H��H�E � I�/�� H�=�� H��� H9G�E L�%�� M���� I�$� �vy��H��H���� H�C� H� H�EH�Z� H� H�E H�$H�E(H� �9y��H��H���u fIn�fHn�M��fl�@I�H�HI�L�r(I��I�H���= I�m �� H��L��[]A\A]A^A_�L��L���3w����tOH�}Xf�L�m`L�ehEXH�Eh H��t H�/�W M��t I�m �Q M��tI�,$uL���Pv����x��H���\ H�;� H� H�$H�=�� H�]� H9G�� L�%D� M���� I�$� �,x��H��H��� H�C� H� H�EH�� H� H�E I�L�}(��w��I��H���� fIn�fHn�L�,$fl�@I�H��I�H������L���u���U �L���xu����� H���hu������ H��H���M ��I��M���c����at��H��H�o� L�mXL� M9������M������I�D$H��� � �5 I�U��� ��H���A��� @�:���� ��/���A��$� @� ���I��X H���� H�JH���a���1�� D H��H9��K���L;d�u��� � I�$A�� � H��I�$�Y H�m uE1�H���Yt��M��t I�,$�i H� Id ��D��H�=�o ����M��urM���c���I�m �X���L���t���K���L��H�� I9��� H��u�L;5 � �� �t � E1�f � H� �c H�=*o M���Z��I�.�� E1��|��� � H��H�e� E1�E1�RL� �b H��c H�8H� �b H�5�f 1��w��XZ����E1�H�y ��������H��H�=�c ����x��� � E1�E1�A�e � I�,$����1�L��� s��H���������� @ L�,$M��� A�� f D L����r����� H���Xw��I��H��������q��H��H�� L�eXL�0M9��@ M�������I�FH��� � �� I�T$��� ��� A��$� @�� � ��� A��� @�� I��$X H���(���H�JH���@���1��f�H��H9�� L;t�u�L�mhH�Eh f�L�u`EXI�,$�� M��t I�.�� M�������I�m �����L���q���w���f � H� �a � �c E1�H�=�l �0������ H�=� ���I��M��� ����� � H� fa H�=�l �������f D A�� � ���� � H�E L�,$M��H��H�E �� A� � ����u��I�����M�� M9��K���M��u�L;%�� �9������ M��E1��7��� D �� � ����H��H�E �z M��E1� A�� �+��� @ H�-� H�UH���%s��I��H�� L�%�� H�@H��� M���E����;r��H���S��I��M���1���L�,$�� � �T��� @ H�-�� H�UH���r��I��H��� L�%<� H�@H�9� M���������q��H������I���Z��� I�,$����� H� �_ �� A� H�=k �B��I�/L�,$�������� � H�=� ���I���4���L��L���o�����{���L�eXf�L�u`L�mhH�Eh EXM���H����N���L���/o���P���L���"o���4����o�����L��� o�����M���t � ���I�NH��~�1�� H��H9�t3M;d�u�����M�t$M���t���1�� H��I9�tIM;l�u�� ���1�H9�~�I�t�I9��5���L��H�T$H� $����H� $H�T$������H����1�I�t�I9������L��H�$����������H�$H��I9�u����� A� ����M��� A�� ���� D AWH� � AVI��AUATI��USH��XH�D$ H�D$@H�D$H H��� L�yH��M���� H���� H��tvH��H�{� H� ^ L� �] AVA� H� �\ H�5�` H�81��� �q��XZf D H� �g �H ��E1�H�=(i ����H��XL��[]A\A]A^A_ÐH�H� H�D$ H�EN�,� L�\$@O� +��� �� H�D$ I�1�H�D$ I�L�T�L��H��u�k H�PH��H���W L;u�I�T� L)�H�H�T H��I9�u�M�� J�|� �� H�\$ f�L�-� H� B� I�$I�EI�E H�D$@ H�\$HH9��� H�=ƪ H9��� L��X M���c M�HM��~$1�f�I�t�H9��� H9��| H��I9�u�� �� H�@8I�D H���� 1�H�t$HL��H� ���I�m H���� H���� H�E��� �G L�mI�EH���m I����� I���� H���5n��I��I����� H�m � L���%m��H��H���� L�=b� M9��� H��L����j��A�ƅ�� H�m � A���� L����l��H��H���� H��L���Op��I��H���# H� H�m �* � �m��I��H���� L�pH�ۨ H� I�E I�,$� H��A��1� � H���T���E���K���H�+� u�H���j����f � H�D$8 H��� I9B�a L��L��L��L�L$H�L$8L��Z L�\$L�$�Ϋ��L�$L�\$L�L$���� ����q H�� L��H�sZ H�5&] �� H�81��7n��H�|$ H���y���H�/�o�����i���e��� D I������H� H�H�\$ ����H��H�z� H� �X H�5�\ AVL� �Y A� H��Y H�81��� �m��Y^�y���1�H�t$H� L���,l��I�m H���q���L���Fi���d���L���9i���t���I�$L����j��I��H��� fHn�H�=� fIn�1�fl�H�t$@H� �)D$@�kl��I�,$H���� I�m �� H���� H�EL9�t H;� �5 � ��j��I��H���� H�E H�hH�m� H� I�E H�m �����H���rh�����H���eh�����I�D� H�T$8H�L$H� H�����M�������HcE���I���Hc�HE�I�����H���h������D�m �EI�� I ��x���D�m �EI�� I �I���X���H��H�� H9�t.H��u�H�5� H9�t H��H�� H9�tH��u�H9������I�u�V���}���1�� L�vuI�mH�=G_ ��f����� H��H��A��H���)j��H���� I�m ���������H��L�\$L� $�g������ L� $E1�L�\$I�L��H��u5�P H��H� I��L)�H�D H�CH��H��� M9��3���H�0H��L�\$L� $�l��L� $L�\$H��u�L�\$L� $�Ki��L� $L�\$H��t��� ���I�u�V�������H9��j���I�E0�w���� i��H��uH�� H�5I^ H�8�g��I�m uL���Rf��A�M A�� f D D��D��E1�H� X` H�=�a �Ļ���T���L���f���@���L��� f���(���L��L��L��L�L$H�L$8L�QV L�\$L�$�]���L�L$L�\$L�$���H����e������A�N A�� �l����7h��H��uH�k� H�5`U H�8�,f���h��H���� I��������H�;� H�5 a A�� A�N H�8��e��H�m ����H���=e�����A�� A�N ��A�O A� ����M��A�Q A�0 I�.�����L���d�����A�O A� ��A�Q A�8 ���M9�����H�D$( L�d$0H�\$(H�D$0 L�l$81�L��H��H��L�\$L� $�h��������L� $H�|$0L�\$I�L��H��tH98t�H�BH��H��u�H�D$8 H��� H9G�; L��L��L��T L��L�L$L� $趥��L� $L�L$���j������_���H�ա H�L$0H�_T H�5W H�81��(h���6��� �kf��A� A�O H���v���H�EH��� �h H��� H�8��c���N���H� �] �R �G H�=V_ �!������H�@`H������H��� H�������H���I��H�������H�@L�-k� L9�uI��� �] M�nI�EH��vHI���tzI��tYL���e��I��I�.�p���L���b���c���L��� ���I��H���U���H�@�M��t�IcF���I���Hc�HE�I���E�n A�FI�� I �I�.� ����E�n A�FI�� I �I���A�� A�M �.���H�HH�C� H��R H�5�R A�; A�Q H�81��f������ 1��.g��I��H�����H��H� � H�8�Pb��I�.����L���b�����L��L��L�bR L��L�L$L� $�k���L� $L�L$���/������H�@`H��� H��� H��� L����I��H���� L9huUI�G��� �� I�GH�PH��vaH���� H���� L���d��I��I�/�L���L���Pa���?���H���s���I��H��u�I�.�����L���)a����� @ E1�H��t H��E�ouA��Mc��H�@`H���� H��� H���� L����H��H���� L9huxH�<$�y���H�<$I��H�/�V����`���L����9c��H���e���H�i� H�5^P H�8�*a���J���E�o A�GI�� I �����E�o A�GI�� I �I�����腎��H��H���w���I��������b��H��u�H��� H�5�O H�8�`����ff. � AWAVAUATUH��SH��(H;= � ��H;=Ν ���u H;=� � ��A� ��uH��(D��[]A\A]A^A_� H�EH; � �G H;X� �Z H�XpH��� H�{ �� 1�� a��I��H��� H��H��SI�,$H���� H���_ H�EH��� $u]H�=�� H�� H9G�� L�%�� M���> I�$L��H���_����I�$����o H��I�$�� ��� A� H�m ����H����^����� ��a��������H� �X � �� E1�H�=�Z �3������f D H�@hH��tWH�@H��tNH��1���H������ � H�} t1H�EH�(H�E ��� � H�} tH�mH�E ���� 1��_��I��H��t)H��H����^�����f � L���]��� ��� H� X � �� E1�H�= Z �p������ H�=A� H��� H9G�" L�%�� M���� I�$I�D$H�5'� L��H��� H���P ��I��I�$H��I�$M���� H���� H��� I9E�: H�� H�t$L��M��H� �H�D$ H�D$�ɢ��I��I�.�L A�4 A� M��t#1�L��A�9 A� 蕚��I�,$t8f D H� �V D��D��E1�H�=�X �\�������A� A� H��u�L���\���� @ L���\���3��� H���� I�$�� H� �V � H�=jX �����^��H���n���A� A� �f���f D L�-� I�UL����^��I��H��� L�%� H�@H�� M�������]��L������I��M�������� �h��� D H�=�� �ܮ��I���� � L���[����� L���[���J���L��t$ �[���t$ ����L�-�� I�UL���+^��I��H�� L�%Z� H�@H�W� M��������A]��L���Y���I��M�������A� A� �T����_��I�����H�=�� �#���I����M�}M�uI�I�I�m t=H��� H�t$� L��L�|$H�D$脠��I�/I�������L���Z�����L���Z���AWH�ǫ AVAUI��ATUSH��XH�D$ H�D$@H�D$H H���� L�qH��M���� H���� H��tyH��H� � H��J L� FJ AUA� H� RI H�5zM H�81��� �[^��XZf � H� 1T �( ��E1�H�=XV 蓯��H��XL��[]A\A]A^A_ÐH�H� H�D$ H�CJ�,� L�T$@M�<*��� �� H�D$ H�E1�H�D$f�I�N�\�L��H��u� H�PH��H���� L;u�J�T� L)�H�H�T I��M9�u�M�� J�|� �� L�l$ f�L;-9� � I�EH��� � �Y � ud� u]H�=�� H�� H9G�L H�-Ц H���� H�E H��L���Y����H�E ����� H��H�E �� ��� � �hW��I��H���� H�@I�E L�(�� H�D$8 H��� I9C�3 L��L��H�L$8L��L��H L�T$L�\$�ڙ��L�\$L�T$��� ����� H��� L��H��H H�56K �� H�81��G\��H�|$ H�����H�/������W������ D I���}���L�.I�E L�l$ ���L��������� I�E M��I�m �����L���W�����H�= � H��� H9G�� L�5u� M���p I�I�FH�5�� L��H��� H��� ��H��I�H��I�H���* H���� H�ʔ H9E� H�� H�t$HH��I��H� �H�D$@ H�D$H虜��I��I�,$�� A�1 �� M��t01�L��A�1 �� �f���I�.uL���V��� A�/ �X D��H� �P ��E1�H�=�R � �������H��H�@� H� �E H�5�I AUL� _F A� H��F H�81��� �}Z��Y^�/���J�D� H�T$8H�L$H� H�����L�%�� I�$�]���H���V���B���H�=m� � ���I��M���|���A�1 �s �9��� @ H��L�T$�#V����tzI�E1�L�T$L��H��u9�� � H��H� I��L)�H�D H�EH��H���� M9�����H�0H��L�T$�Z��L�T$H��u�L�T$��W��L�T$H��t��� �4���L��L��H�L$8L��L��E L�T$L�\$藑��L�T$L�\$����A�1 �u H���Y����?���A�, �/ �D���M9��~���H�D$( L�d$0H�l$(H�D$0 L�l$81�L��H��H��L�T$�X�����S���I�H�|$0L��L�T$H��t H98t�H�BH��H��u�H�D$8 H��� H9G�� L��L��D L��L��L�T$�ʕ��L�T$���w���������H�� H�L$0H��D H�5*G H�81��@X����� H��A�� H�E �� H� N � D��H�=�O �i����TV��H��� ���A�. �M ����L�%\� I�T$L���GV��H��H� � H�-f� H�@H�c� H��������]U��L���u���H��H���w���A�� �j���H�=�� �R���H����L���5S���U���L���(S�����H���S���2���L�}L�eI�I�$H�m �� H�� H�t$@� L��L�|$@H�D$H臘��I�/I�����L����R������H�-.� H�UH���ZU��I��H� � L�5�� H�@H��� M�������pT��H��舥��I�����L��L��B L��L��L�T$�֎��L�T$����������� ��V��H�����H���+R���,���f D AWH�7� AVAUI��ATUSH��XH�D$ H�D$@H�D$H H���� L�qH��M���� H���� H��tyH��H��� H�>B L� �A AUA� H� �@ H�5�D H�81��� ��U��XZf � H� �K � ��E1�H�=�M ����H��XL��[]A\A]A^A_ÐH�H� H�D$ H�CJ�,� L�T$@M�<*��� � H�D$ H�E1�H�D$f�I�N�\�L��H��u�; H�PH��H���' L;u�J�T� L)�H�H�T I��M9�u�M�� J�|� �� H�l$ f�H;-�� �! H�EH��� � �� � �� � uZH�=� H�E� H9G�0 L�5,� M���� I�L��H����P����I������ H��I��� ���% � ��N��I��H��t$H�@H�E H�(H�m �����H����O�����A�E A�# D��D��E1�H� �I H�=XL �c���뾐H�D$8 H��� I9C�@ L��L��H�L$8L��L�@ L�T$L�\$����L�\$L�T$���� ����� H�/� L��H��? H�5nB �� H�81��S��H�|$ H�������H�/������"O����� D I���E���H�.H�E H�l$ �L���H�=u� H��� H9G�� L�5�� M���� I�I�FH�5]� L��H��� H���� ��I��I�H��I�M���z H���� H�2� I9D$�� H�`� H�t$HL��M��H� �H�D$@ H�D$H� ���I��I�m �{ A�v A�% M���N���1�L��A�{ A�% �Nj��I�.�.���L���N���!���H�������� H�E I�����H��H��� H� �< H�5A AUL� �= A� H�;> H�81��� ��Q��Y^�_���J�D� H�T$8H�L$H� H�����L�%� I�$�n���H��A�7 A�" I��y����F���H�=ĝ �W���I��M���k���A�` A�% �K���f. � A�b A�% H���,������H��L�T$�YM����txI�E1�L�T$L��H��u7�' D H��H� I��L)�H�D H��H�E M9����H���� H�0H��L�T$��Q��L�T$H��u�L�T$�O��L�T$H��t��� �4���L���kL���=���L��L��H�L$8L��L��< L�T$L�\$���L�T$L�\$���L�%� I�T$L����N��I��H��� L�5ޙ H�@H�ۙ M���������M��L�����I��M�������A�5 A�" ��H�=�� �Ԟ��I����M9����H�D$( L�d$0H�l$(H�D$0 L�l$81�L��H��H��L�T$��N���������I�H�|$0L��L�T$H��t H;8t�H�BH��H��u�H�D$8 H��� H9G�� L��L��; L��L��L�T$誌��L�T$���w����������H�͈ H�L$0H�x; H�5 > H�81�� O���^��� A� A� ���L���J���x���L���J��� ���L��L�*; L��L��L�T$����L�T$�����t���M�|$M�l$I�I�E I�,$�� H�C� H�t$@� L��L�|$@H�D$H���I�/I�����L���*J�������N��I���k���L�%�� I�T$L���L��I��H�z� L�5�� H�@H��� M��� �����K��L�����I�����L����I���[���ff. � f�AWAVAUATUSH��(H� �� H9��� H�~ I��I��� H�nH�E H�E��� �� H�EH�PH���u H����� H���A H����K��Hc�A��H9��� A���� H�m �U I�D$E�u0H����� H��� H�59� H�F��� �p I�EH��� H;�� �� L�� 1��H��H��H���� H�/�� I�EH�5� L��H��� H���5 ��H��H���7 H�E I�|$�> M�d$ I�$fIn�H�=P� fHn�1�fl�H�t$H� �)D$�K��H�m I���� I�,$�� H�m t|M���S I�m �� H�H��(H��[]A\A]A^A_�f�H��t;�UA��A��H���DE���� D H���G����� I�/u L���G��f�E1��x��� � H���G���w��� L���xG���`��� H���hG���E��� L���XG���[��� �E �UH�� H �H��Hc�A��H9�����H�"� H�53@ H�8�G���I��H���� A��������f��E �UH�� H �Hc�A��H9�������f���F���3���f D H��� H�5�@ A� A�@ H�8�NG��D��D��H� �6 H�=ZC �5���H��(1�[]A\A]A^A_� @ 1�� H��I��H��t!H��L���FG��I�.H���� H������A� A�B �H�m A� A�D u�H���'F���t���f�A� A�R �a���L��L���F����tPH�}Xf�L�m`L�ehEXH�Eh H��t H�/�% M��t I�m � M��tI�,$u L���E����;H��H�������A� A�Y ����H����U����H��H���G����X��� H�9� H�5�> A� A�Y H�8��E�����f � L��H���� ��H��H���y����AD��H��H�O� L�mXL� M9�����M���N���I�D$H��� � �N I�U��� �����A��� @������ ������A��$� @�����I��X H��t+H�JH�����1���H��H9�����L;d�u��w���M�� M9��g���M��u�L;%{� �U��������H��H������ A� A�c ��� � � �E��I��H��t L��H����D��I�m I��tvM�������H�E H��H�E t"H��A� A�k H�E �"������ H���C��H�E ��f. � A� A�t �� � L���C���2���L���C��뀐H�@`H���C H��� H���3 H���I��H���" H�@L�5o� L9�u[f���� �P I�GH�PH��v]H����� H��tmL���E��Hc�A��H9��� I�/����L����B�����L���q��I��H�������H�@� D H������A�WA��A��H���DE�� A�G A�WH�� H �Hc�A��H9�t�H�� H�5�; H�8�C��I�/�S���L���fB���F����A�G A�WH�� H �H��Hc�A��H9��A������F��H�������D��H������H�� H�5�1 H�8�B����� � H����h����D��H���Z����k���H�@`H���� H��� H���y L����I��H���h L9pueI�@��� �� I�@H�PH��v`H����� H��tlL��L�$�D��L�$Hc�A��H9��� I�(�Y���L���OA���L���H���ro��I��H��u���� D E1�H��t�A�PA��A��H���DE��A�@ A�PH�� H �Hc�A��H9�t�H��~ H�5�9 L�$A��H�8�|A��L�$�r���A�@ A�PH�� H �H��Hc�A��H9��Q�����@������L���@������M�|$M������1�� H��I9�tZM;l�u��r���H���n�����B��L�$H���\���A�������B��H������H�~ H�5�/ H�8��@�����E1�K�t�I9�����L��蛀��������I��M9�u��E���H�@`H��tsH��� H��tgL��L�$��L�$H��H��tRL9pu6L�D$H�<$藍��H�<$L�D$A��H�/�@���L�$�?��L�$�.����m��L�$H��H��u��#���L�$� B��L�$H��� ���H�,} H�5!/ A��H�8��?��L�$����AWH��� I��AVAUI��ATUSH��XH�D$ H�D$@H�D$H H���E L�IH��M���5 H���� H��tvH��H��| H��. L� �. AUA� H� �- H�52 H�81��i ��B��XZf D H� �. � ��E1�H�=�; �#���H��XL��[]A\A]A^A_ÐH�H� H�D$ H�EN�$� L�|$@O�4'��� � H�D$ I�1�H�D$ I�L�T�L��H��u� H�PH��H���� L;u�I��L)�H�H�T H��I9�u�M�� J�|� �4 H�l$ L�%�{ H�EL9�t H;q{ �[ L��H����H��H��� H�(�N I�$H�m �����H���z=���� D H�D$8 H��{ I9B�� L��H�L$8L��L��L�c- L�\$L�L$L�$�~��L�$L�L$L�\$���� ����x H��z L��H� - H�50 �[ H�81��'A��H�|$ H���9���H�/�/�����<���%��� D I������H�.H�E H�l$ ����H��H�iz H� �+ H�5�/ AUL� �, A� H��, H�81��] �@��Y^�x���I��H�T$8H�L$H� H���R����?<�����H��L�\$L� $�<������ I�E1�L� $L��L�\$H��u6�� D H��H� I��L)�H�D H��H�M9���H���� H�0H��L�\$L� $� A��L� $L�\$H��u�L�\$L� $�4>��L� $L�\$H��t��[ ����� H� �+ � H�=|8 E1�� �������L��H�L$8L��L��L�t+ L�\$L�L$L�$�w��L�\$L�L$L�$� ���M9��:���H�D$( L�d$0H�\$(H�D$0 L�l$81�L��H��H���b>�����T���I�H�|$0L��H��t f. � H;8t�H�BH��H��u�H�D$8 H��x H9Gu}L��* L��L��L���#|����t�����H�Ox H�L$0H��* H�5�- H�81��>������ D H�HH� x H�5�* H�u* H�81��u>���� ���L�F* L��L��L���v����� ����z��� � AWH�W� f�AVfHn�AUATI��H�HH��UH��SH�� )D$@fHn�fl�H�D$pH�D$P H�D$x )D$`M���� M�t$M���� H���k �N H��tH���� H�H� H�D$@I�D$L�,� L�T$`O�<*��� � H�D$@I�1�H�D$ I�M�\�L��H��u� H�PH��H��� L;u�I�T� L)�H�H�T@H��I9�u�H�\$@H��8H�|�@ �� H�EH��t"H�|�@ �� H��H��t H�|�@ �� H�|$HH�G��� �k H�oH�EH���� H����K H��� �o �GH�� H �H��L�t$P�9��I��H���f H�=l� H���D9��A�Ņ��� I�,$�E E���M L�%ކ H�=� 1�H�t$`H� �I�$L�d$`H�\$h�b;��I�,$H���� H���� L;5�u t2I�FH;ou �i H��L����H��H���� H�(�� H�E I��H�E H��� H�|$@H��t H�/� H�|$HH��t H�/� H�|$PH��� H�/� �77��� H���� H�FH� H�D$PH�FH� H�D$H���f � H�D$8 H�8u I9C�_ L��L��H�L$8L��L�k' L�T$L�\$�Rx��L�\$L�T$���� ����� H�ot L��H�/' H�5�) �X H�81��:��H�|$@H��t H�/�� H�|$HH��t H�/�� H�|$PH��t H�/�� H� C& � ��E1�H�=s3 �Ƌ��H�Ĉ L��[]A\A]A^A_ÐH��urH� H�~H�FH�H�\$@H�H�|$HH� H�D$P�?���H��H��H��s H� �$ H�5) UL� �$ A� H�H& H�81��Z ��9��Y^����H��H�]s H� & L� �$ UA� H� �$ H�5�( H�81��l �9��XZ������7��H��H��������7��H��� H����������o �GH�� H �H����I�D� H�T$8H�L$H� H��� ���H�������HcG���H���Hc�HE�H���L����4��E�������� �~3��I��H���� H�{� I�T$H� H�L�-�� ��7��I��H���� H�5 � E1�L��L��H���7��I�.I���� I�$H��M���� I�$H���) H�5 � L���U}��I��H���� H�8 �@ I�m �( H���5��H��H���� H�=�� H���8��I��H�E M���� H��H�E �? L��L�� �sq��I�m � H� �# � ��H�=�0 �>���I�,$t=E1������3���B����3���$����v3������H���i3������_3����L���R3����K3����L���>3���e���L��L�T$�3����tsI�E1�L�T$L��H��u2� H��H� I��L)�H�D@H�CH��H���T M9������H�0L��L�T$�8��L�T$H��u�L�T$�O5��L�T$H��t��X �,����2������L���2������H���2�����L��L��H�L$8L��L� # L�T$L�\$��n��L�T$L�\$����� A� I�,$t H� B" D���H�=w/ �ʇ�����L��� 2����L���2������H� " � �� H�=>/ 葇���U���L����1������H����1�����L����1���c����� H� �! � H�=�. E1��E���H�E H������M9������H�D$( H�l$0H�\$(H�D$0 L�l$81�H��H��L��L�T$��4���������I�H�|$0L��L�T$H��t @ H;8t�H�BH��H��u�H�D$8 H�^o H9G�� L��L��! L��L��L�T$�r��L�T$���v������'���H��n H�L$0H�c! H�5�# H�81��4����� �� A� �W���I�m uL���0��H� � � �� H�=�- �������� � �� ���H��H�E �� H� P � �� H�=�- �Ӆ������g ���H�@`H��� H��� H��� ��I��H���� H�@H�-n H9��4 ��� � I�l$H�EH��v/H���teH��tAL���U2��H��I�,$�[���L���/���N���H��t�IcD$���H���Hc�HE�H����A�l$ A�D$H�� H �I�,$�����A�l$ A�D$H�� H �H���H�HH� m H�5r H�e H�81��e3���� �[���L��L�� L��L��L�T$�k��L�T$�������� ���H� � � �� H�= , �q����5���H����.���o���H�@`H���� H��� H���� L���I��H���� H�@H9�us��� t]I�EH�PH��v7H����� H���� L���0��H��I�m �����L���?.�����1�H��t H��A�mu��Hc���L��� y��H����H�P��� �� H��k H�Ѿ H�> H�81��2������ I�E�K����^0��H��tSI�,$�|���L���-���o���H�P��� tFH�ek H�Ѿ H�� H�81��D2����u�I�D$���H�?k H�54 H�8� .���H�'k H�5H H�81��1��I�,$������x���H��j H�5 H�81��^1��I�m �J���L��� -���=����/��H�������H��j H�5� H�8�-�����H� � � �� H�= * �`����$���A�m A�EH�� H ��U���A�m A�EH�� H �H���>���AWH�W} AVI��AUATI��USH�� H�D$P H�D$pH�D$x H��� L�yH��M���� H���� H��t{H��H��i H� B H�5j AVL� A� H� H�81��� �50��Y^ H� & �4 ��E1�H�=�) �s���H�Ę L��[]A\A]A^A_�f D H�H� H�D$PH�EN�,� L�\$pO� +��� �� H�D$PI�L�d$1�H�D$M��M��I��L�t$ L��M��f�H�U M�T�H��H��u�] D H�PH��H��tKL;u�I��L)�H�H�TPH��I9�u�L�d$L�t$ M�� J�|�P � H�l$P� � H�D$h H�(i I9B�� L��H�L$hH��L��L�� L�T$�Gl��L�T$���� ����o H�ih L��H�� H�5� �� H�81��.��H�|$PH���{���H�/�q����\*���g��� � I������H�.H�E H�l$PL�52h H�EL9�tH�jh H9��� I�$L9��< H�5�y � � H��L9�HD���,��I��H���� H�x�� H�@L�hI�E I�/�' I�EM9�t H;�g �� M9��< L��L��L�=�{ ��.��H��H���d H�H�PH�H�S��� � H�SH�JH���; H����� H���� H����+��HcЉD$H9��I �L$����� H�D�yMc�H��H�H��� L���*��H��H���� H��L��L���,������ H�+� M9�M��H�t$~D�D$LD=tx H��H�= ) I�Ic�D��H��Hi� ��Q�� H��%)�D��Dk�dD)�A��A�� D1�D)�A���H��f�E��u�1��� �T$D�D$��H�H��H)ȅ�y �A�-H��H��H��� HI�H���� Lc�H��� H�L$ L)�L�D$Hc�H�T$��,��I��H���� �@ H�T$L�D$H�L$ � � I�v0I�~H�@HE�H��~+� L�D$ H�L$H�T$��(��H�T$H�L$L�D$ H��M���� L�K�I���� I��H�41�I��� �oH��I9�u�I��I���L��I9��� M)�L)�I��vN� N� I��I��L�I9��� D� D� L�HM9�~oD�TL�HD�T0M9�~[D�TL�HD�T0M9�~GD�TL�HD�T0M9�~3D�TL�HD�T0M9�~ D�TD�T0H�pL9�} �DH��H�tv I�OL�|$pI�VL��$� H�D$xA�G H�T�@�� �� <�� <�: ��� H��H�T$�++��H��H��� H�������� �D$ H�T$�D$ H���� H���� �C����H���D��D$����H��H��c L� � A� AVH� � H�� �� H�8H�5 1��)��AYAZ�8���I��H�T$hH�L$H� H���p���L���%������� H��H�T$�W*��H��H���D �D$ H�T$H��������H���C � �W H�K0H�sH�@HD�H�L$H9��� L�T$pH��$� E1�H�l$ L�|$(H��I��L�t$8M��L�d$@M��L�l$0�7f�H�r0H�zH��@HD�;D$t]M��1�L��H����&��M�I��M9��- I�$�z �f L�jM��t�H��L)�L9�|9�J ������� u�H�rH;D$u��D$L��L��H��H��H|$��&���H�l$ L�|$(L�l$0L�t$8L�d$@H�8b H�5q" H�8��$��H�+�� I�.�m �� I�/A�= �J H� ) �= E1�1�H�=�! �y��I�m �� I�,$�� H��t H�+�� H�m ���H���#������H�HH�sa H� H�5� H�81���'��I�m �� H� � �9 �9 H�=8! �y��I�,$A� u�1�L���L#���r���H��H�T$H� "��H�T$H�������H�l$ L�|$(L�l$0L�t$8L�d$@����f D H��� #���5���L����"������H�CHH�D$���H����"������I�~H����H����"�����C �SH�� H �HcЉD$H9��y���H��` H�5� H�8�*#���%��H���u H��D$����E1�H���Y����C �SH�� H �H��HcЉD$H9�� ����H���;"�������D$ A� ������� H��H�T$��&��H��H������H��������?�D$ H�T$�D$ H�����H����4����_$��H���&����7����H��L�\$L�L$�"����tyL�L$E1�L�\$I�H��� L�d$L��M��L�L$�4 � L��H� I��H)�H�D4PI��I�$M9��� H���� H�0H���&��H��u���#��H��t̽� ���L�@H��H�JE1�H��^ �5�o L� H�� H�5~ H�81��,%��H�E H��H�E _AXH����������H� _ H�5� H�v H�81���$���2 H� � �9 H�=h �3v���+���L�|$(H�l$ L�l$0L�t$8I�/L�d$@uL���g ��I�.t"H��H��L���3$������ H�I���T���L���7 �����9�$��I��H���~����g ����4 �b���L��H�L$hH��L��L� L�T$�n\��L�T$�2���� �j!��H��H��t!H��L��� ��H�+I��� M�����I�/uL��� ��H� � �9 �6 H�=[ �&u��� ���L���t$�u ���t$�T����� ����H��] H� H�5U 1�H�81��#���; �F H� X H�=� E1��t���1����!��H���e L������< �U ��A�< �[ H�+I���$ D��H� E1�1�H�=� �gt�������> � �|���E1�1�H�4�Z���L�L$L�d$I��M9��|�L�d$`H�\$XM��M��H�D$X L�l$hH�D$` 1�L��H��H����!����� ���I�H�|$`L��H��tH98t�H�BH��H��u�H�D$h H�f\ H9G�� L�# L��L��L���_����t��������H��[ H�L$`H�� H�5� H�81��"�����f � L�d$��H��� ������; �H �c���L��� ��� ���L�� L��L��L���Y���������p���f. � H�B`H���O H��� H���? H���I��H���. H�@H;O[ uZ��� �+ I�GH�PH��vYH����� H��tgL��� ��HcЉD$H9�� I�/���L���� ����L����J��I��H���-���H�@�H���� A�W���H���DщT$�A�G A�WH�� H �HcЉD$H9�t�H�iZ H�5z H�8� ��I�/����L���P �����A�G A�WH�� H �H��HcЉD$H9��G����I�/t*H��D$ A� H����A�; �J ����L��������H�@`H���� H��� H���� L����I��H���� H��Y I9@upI�@��� �� I�@H�PH���Y H����� H���$ L��L�D$� ��L�D$HcЉD$H9��� I�(�m���L���G���`���L���jI��I��H��u������ ��H�������H��X H�5� H�8������� ��H���l���H��X H�5� H�8����Q���H���Y����\ ��H���K����\���L���t$1�����t$D��H� � H�=k E1��3p�����H���% H�uX H�5� L�D$H�8� ���D$����L�D$���A�@ A�PH�� H �HcЉD$H9�������D$ H������A�pH���t$������\$���H�@`H���� H��� H���� L��L�D$��L�D$H��H���� H��W H9G�� L�D$H�|$�g��H�|$L�D$�D$H�/�A���L�D$���L�D$�-���A�@ A�PH�� H �H��HcЉD$H9�� �������L�D$����L�D$H�������D$��������eG��L�D$H��H���c�����L�D$���L�D$H��u�H��V H�5� L�D$H�8����D$����L�D$��� H��H��� takes no arguments %.200s() %s (%zd given) takes exactly one argument Bad call flags for CyFunction takes no keyword arguments %.200s() %s <cyfunction %U at %p> exactly __init__ __loader__ loader __file__ origin __package__ parent __path__ submodule_search_locations needs an argument keywords must be strings cannot import name %S an integer is required name '%U' is not defined %s (%s:%d) <stringsource> __missing__ __setstate_cython__ tuple Expected %s, got %.200s __reduce_cython__ get_anon str _distill_raw_params _distill_params_20 __pyx_unpickle_cache_anon_map key split get builtins cython_runtime __builtins__ sqlalchemy.cyextension.util does not match _cython_3_1_0amsendbackport __reduce__ __module__ __dictoffset__ __vectorcalloffset__ __weaklistoffset__ func_doc __doc__ func_name __name__ __qualname__ func_dict __dict__ func_globals __globals__ func_closure __closure__ func_code __code__ func_defaults __defaults__ __kwdefaults__ __annotations__ _is_coroutine __int__ returned non-int (type %.200s). The ability to return an instance of a strict subclass of int is deprecated, and may be removed in a future version of Python. __int__ returned non-int (type %.200s) %s() got an unexpected keyword argument '%U' %.200s() takes %.8s %zd positional argument%.1s (%zd given) Interpreter change detected - this module can only be loaded into one interpreter per process. Shared Cython type %.200s is not a type object Shared Cython type %.200s has the wrong size, try recompiling unbound method %.200S() needs an argument __annotations__ must be set to a dict object __kwdefaults__ must be set to a dict object changes to cyfunction.__kwdefaults__ will not currently affect the values used in function calls __defaults__ must be set to a tuple object changes to cyfunction.__defaults__ will not currently affect the values used in function calls function's dictionary may not be deleted setting function's dictionary to a non-dict __qualname__ must be set to a string object __name__ must be set to a string object %.200s() keywords must be strings %s() got multiple values for keyword argument '%U' instance exception may not have a separate value calling %R should have returned an instance of BaseException, not %R raise: exception class must be a subclass of BaseException while calling a Python object NULL result without error in PyObject_Call '%.200s' object has no attribute '%U' base class '%.200s' is not a heap type extension type '%.200s' has no __dict__ slot, but base type '%.200s' has: either add 'cdef dict __dict__' to the extension type or add '__slots__ = [...]' to the base type value too large to convert to int lib/sqlalchemy/cyextension/util.c object of type 'NoneType' has no len() hasattr(): attribute name must be string sqlalchemy.cyextension.util.__pyx_unpickle_prefix_anon_map__set_state 'NoneType' object is not subscriptable lib/sqlalchemy/cyextension/util.pyx sqlalchemy.cyextension.util.cache_anon_map.__missing__ sqlalchemy.cyextension.util.prefix_anon_map.__setstate_cython__ __pyx_unpickle_prefix_anon_map sqlalchemy.cyextension.util.__pyx_unpickle_prefix_anon_map sqlalchemy.cyextension.util.prefix_anon_map.__reduce_cython__ sqlalchemy.cyextension.util.cache_anon_map.__reduce_cython__ 'NoneType' object is not iterable sqlalchemy.cyextension.util.cache_anon_map.get_anon sqlalchemy.cyextension.util._mapping_or_tuple sqlalchemy.cyextension.util._check_item sqlalchemy.cyextension.util._distill_raw_params sqlalchemy.cyextension.util._distill_params_20 sqlalchemy.cyextension.util.__pyx_unpickle_cache_anon_map__set_state sqlalchemy.cyextension.util.cache_anon_map.__setstate_cython__ sqlalchemy.cyextension.util.__pyx_unpickle_cache_anon_map Argument '%.200s' has incorrect type (expected %.200s, got %.200s)%s%U sqlalchemy.cyextension.util.prefix_anon_map.__missing__ 'NoneType' object has no attribute '%.30s' join() result is too long for a Python string Unable to initialize pickling for %.200s Module 'util' has already been imported. Re-initialisation is not supported. compile time Python version %d.%d of module '%.100s' %s runtime version %d.%d inheritance from PyVarObject types like '%.200s' not currently supported init sqlalchemy.cyextension.util _cython_3_1_0amsendbackport.cython_function_or_method sqlalchemy.cyextension.util.cache_anon_map sqlalchemy.cyextension.util.prefix_anon_map 00010203040506070809101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899 Incompatible checksums (0x%x vs (0xbe943c5, 0x57efb0a, 0x3ac5a10) = (_index)) prefix_anon_map.__setstate_cython__ mapping or sequence expected for parameters mapping or list expected for parameters cache_anon_map.__setstate_cython__ Note that Cython is deliberately stricter than PEP-484 and rejects subclasses of builtin types. If you need to pass subclasses then set the 'annotation_typing' directive to False. Incompatible checksums (0x%x vs (0xe3b0c44, 0xda39a3e, 0xd41d8cd) = ()) prefix_anon_map.__reduce_cython__ lib/sqlalchemy/cyextension/util.pyx List argument must consist only of tuples or dictionaries cache_anon_map.__reduce_cython__ __pyx_unpickle_prefix_anon_map sqlalchemy.cyextension.util __pyx_unpickle_cache_anon_map prefix_anon_map.__missing__ cache_anon_map.__missing__ cache_anon_map.get_anon _distill_raw_params cline_in_traceback asyncio.coroutines _distill_params_20 anonymous_counter __setstate_cython__ __pyx_PickleError prefix_anon_map collections.abc cache_anon_map __reduce_cython__ ArgumentError use_setstate <stringsource> __pyx_checksum _is_coroutine PickleError sqlalchemy __pyx_result self_dict __reduce_ex__ __pyx_state isenabled __setstate__ __set_name__ __qualname__ __pyx_type __getstate__ get_anon add_note __missing__ disable derived Mapping update __reduce__ pickle params __module__ idself enable _dict value state __test__ self __name__ __main__ id_ __func__ __dict__ None val pop obj __new__ key get exc id gc ? . _ @ ;� Q ���� ����� ���� ����� ��X &���� - ��0 E��d ���| ��� J��� � ��� ��� ��� � ��P �!��� �!��� "�� "�� ("��, 8"��@ X"��T �"��l �"��� x$��� �$��� �$��� �$�� 8%��, X%��@ �%��d �&��� 8'��� �'��, (��D �*��h �*��� �+��4 �,��p 0��� �0�� (1��4 �1��` X2��� �2��� 83��� �3�� �4��� �6��� �6�� �7�� h8��0 �8��H �8��\ ;��� x;��� <��� �<�� H@�� �A��l B��� �C��� E��� �F��8 H��t 8J��� �L��$ �V��� �[��� �a��` g��� xt��@ �~��� ���@ ���� x���� ���l x���� ��D (���� ���$ zR x � $ � FJ w� ?;*3$" D � �� X � ��# WH p � �� � � �� � � �� � � �� � � ��@ \ c � $ ��5 T ` @ � L ��� A�G�G0k GAF d DAG Z CAJ 4 � �� H � �� \ � ��/ Q�] x � ��E Q�c D L � !�� � !��| A�@ G b F ( � l!��� B�J0V BD I BE 4 � �!��� A�D ^ AD D(K0g(A I AG ( 4 h"��� B�A�D U DBF 4 ` ����} B�E�E �A(�D0a(D BBB � �"��A dN � �"��j A�� C H H � %��) A�c 8 � y���~ B�E�H �A(�A0�b(D BBB 8 , ����a B�B�E �A(�A0K(D BBB 4 h �$��� B�D�D �� GBG AAB � l%��� Dq K K E � ����B A@x � &��� B�B�E �B(�D0�D8�D�c 8G0A(B BBBF R 8D0A(B BBBA Q 8I0A(B BBBM X )��} DE G ( t x)��� A�D�D U AAH ( � �)��� A�D�D U AAH � `*��� Do E o I � �*��h Do E o +��h Do E o l , ^��� B�B�B �E(�D0�G8�X`�hApBxA�A�A�B�A�A�B�L`T8D0A(B BBB0 � ���� B�A�A �DP DAB � ���G D`BH � ���� B�E�E �E(�A0�D8�GPe8D0A(B BBB @ 4 h*��l B�E�D �s BBF L BBH DEB x x �*��' B�B�B �E(�A0�A8�D@_ 8A0A(B BBBF _ 8A0A(B BBBG _ 8F0A(B BBBB h � H+��� B�B�D �� EBH T BBP F EBK f BBF Q EBH t BBH ` �,�� t �,��� � �-��� � 0.��# WH � H.�� ` � T.��G B�B�B �B(�D0�D8�G`� 8A0A(B BBBG � 8C0A(B BBBH , @0��e |h D �0��� dh \ 1��� Do E C E p � �1��o B�K�F �D(�D0F (I DBBF u (I DBBJ � (D ABBE �(I ABB H � ����. B�B�B �B(�D0�A8�G` 8D0A(B BBB H @ n���m B�H�A �A(�DPZ (D ABBE +(D ABB H � 4��: B�B�B �E(�A0�D8�D@^ 8D0A(B BBBA ( � 5��� B�A�D U DBF 4 x5��� B�A�G F DBJ n DBD < 7��& ��D F AA @ ` 8��� B�A�D G DBD ] AEE _ DBK 8 � h9��_ B�B�A �A(�D0U (D ABBH @ � �:��! b�B�B �A(�A0�D@S 0D(A BBBF $ $ ����W B�D�A LAB@ L P<��� B�B�E �A(�A0�D@z 0D(A BBBD d � �>��� B�B�B �E(�D0�D8�Fp� 8A0A(B BBBK � 8A0A(B BBBE ` � $H��� B�B�B �B(�A0�A8�D`7 8D0A(B BBBF w 8C0A(B BBBE l \ �L��< B�I�E �B(�D0�A8�D�C�W�d�A�g 8D0A(B BBBB W�W�d�A� l � `R��8 B�L�B �E(�A0�A8�D�C�W�d�A�g 8D0A(B BBBB ��W�d�A� l < 0W��p B�M�G �B(�L0�D8�G�� 8D0A(B BBBB x�V�d�A�I�V�d�A� � � 0d��* B�B�B �B(�A0�A8�DP� 8A0A(B BBBJ � 8A0A(B BBBF t 8A0A(B BBBB tXR``XAPF 8A0A(B BBBI X P �m��k B�B�B �B(�A0�A8�DP� 8D0A(B BBBA XN`gXAP l � �w��� B�I�E �B(�D0�A8�D�C�W�d�A�g 8D0A(B BBBB ��W�d�A� H `���` B�B�B �B(�A0�D8�D`v 8D0A(B BBBD l h t���� B�I�B �E(�A0�A8�D�C�W�d�A�j 8D0A(B BBBB i�W�d�A� l � ����c B�I�B �E(�A0�A8�D�C�W�d�A�j 8D0A(B BBBB q�W�d�A� d H ����p B�B�B �B(�A0�A8�D`� 8D0A(B BBBC O 8C0A(B BBBE l � ����8 B�L�B �E(�A0�A8�D�C�W�d�A�g 8D0A(B BBBB ��W�d�A� l l���p B�M�G �B(�L0�D8�G�� 8D0A(B BBBB x�V�d�A�I�V�d�A� | � l���� B�I�E �B(�D0�A8�G�C�W�d�A�g 8D0A(B BBBG ��V�f�B���T�l�B�H b���� B�B�E �B(�A0�A8�DP�8D0A(B BBB \ \ ���� B�B�B �B(�A0�A8�G�T�i�H�H�K�)8A0A(B BBB � � �� l �k x HJ H ` �D H �B N �E : hI ` J D � hH ` FJ ` DJ BJ 8I pG ` 0G ` �G ` �F ` F ! ` �C # ` �F ` G ` �G ` `I ` J ` �I ` XI PG ` �F ` �I 8J ` �I ` ?J 4J ` (I ` I ` <J ` �I ` �I ` XH ` �H 0J ` �E $ �I ` �C ( `C , HI ` �I ` �I ` (J ` J ` �I ` �I ` J ` �G ` �F ` @E " ` C $ ` �G ` HH ` �H ` �H ` I ` pF ` 0F ` �H ` xI ` H ` �H ` �I ` �H ` �H ` �H ` �G ` xH ` PF ` �I ` 8H �I ` pI ` (H ` J ` �I ` y � @ �( �w �w ���o ` X � � � x/ H 0 ���o ���o �o ���o � P} 6@ F@ V@ f@ v@ �@ �@ �@ �@ �@ �@ �@ �@ A A &A 6A FA VA fA vA �A �A �A �A �A �A �A �A B B &B 6B FB VB fB vB �B �B �B �B �B �B �B �B C C &C 6C FC VC fC vC �C �C �C �C �C �C �C �C D D &D 6D FD VD fD vD �D �D �D �D �D �D �D �D E E &E 6E FE VE fE vE �E �E �E �E �E �E �E �E F F &F 6F FF VF fF vF �F �F �F �F �F �F �������� 0A � L �� 4 �t B �o 2 �v G u 3 pr @ `� H �� I �� 6 �n �2 � �2 �2 @ �2 0 �2 ( �2 @o r 3 @o r 3 o } 3 o } #3 `l �| 03 �l | :3 �l | C3 pl P3 pl \3 �l i3 �l u3 �l 3 �l �3 � �{ �3 � �{ �3 �q �z �3 �l `z �3 � �2 � � �G \X hA 8 D � �� � �p �1 p� � �1 � � �1 � � �1 @ � �A 0 D l 0l � �1 � � �1 о � �1 � � 2 � � H< `� � �1 @ � �1 � � �1 � � �1 p� � �1 � � �1 о � �1 � � �1 �� � 2 `� � GCC: (GNU) 10.2.1 20210130 (Red Hat 10.2.1-11) l �� �F } ]G ~ �G a <I B ~I �J �N G �N � tP . �R m U W fU � \X � 9k �� ly ) 0< �5 9�E $5 9� 9�+ $H 9�E $T 9� 9�O mint $n 9]J $z n E# �z � 9� $� � (� oc � � � 5 p� P�) T Py) T P � P� � � $ � O� G# f� <�- An 9XJ $8 B4 �n G �z 9�E i q � 0A � 1 H A4 3T F 75 �I i $� t! r� 9�2 9�5 ;9I 8� Q : n �0 ; n � r� � B $� \Z � �� � � �) � 8P �� G � � ( �� 0�3 �� 8E � @� �D H� �o PbI �{ X�5 �u `,* �{ h� �� p�< �� x� �x �� �{ ��. �8 � A �o �&+ �� �aL �5 � 7 � �]? �� �� � � �\ �� �+6 �� ��C �� ��B �� ��/ �� �8? �$ � B �y �A�D � A� �G AyC �� AvO �� 1� � 1 (1�, : 01& 81$ � @1< � H1� G P1R0 G X1I G `1�@ G h1�8 G p1�( � x1A= T �1 � �1= � ;� i� � k� � l� � �! m� $� 6s � t� > u� � v� 32 �2 8 2G G G � $G � �^ d 2G x G G m �� � 2G � G G G 4 �� � 2n � G � �� � 2� � G H �� � 2G G � �< � 2n 6 G � G 0 �B H 2n a G G G 5Q �m s 2n � G G d �� � 2n � G � T3 �� � 2n � G � � +A �� � T� � ' � T G �9 � $ 2G 8 G � %7 �^ � �P V 2n o G � G � �B � �2 �9 �� � 2� � G � �� � 2G � G G n < �2 �N �2 � �� �B �B �9 � ! 2G : � G G / �F L 2G ` � � 6� � �" � n � � � �` 6 � � ` � � � n J � n �% �T a& �� � 4 �� 4A �� ]fJ � ;'9 P 8� Ebuf 9 � Eobj :G Elen ;� J <� 7 > n �< ? n $,2 @ � (N< A� 0zD B� 8G- C� @�G D � H � �O E > G� � 2n � G � n � �E H� � T G � - J 2G 8 G 8 ) G M s o ! � tR HM uR ^A vR 1 wR Q xR � yx ( " z& 0LJ {& 8 G |& @D } � HJ4 ~& P R X�D �R `\ �R h�! �R p2 �R xO �& � � � ��2 �& � �R �RP �R ��E �R �F �R ��@ �x �� �R ��I �R �p+ �R ��@ �R �eH �R �f �R ��A �R ��C �R �A�& �R AS �& A� �R A P �R � �> 6P � � C � � � �R �� � �� � � � � (� � � 0R �a 8" �R @� �� H . �- 6 � � z? � � � �R � �6 �J �� 6 � 3 �> �& -@ �& � �& 6 � 6 � c � �� <E �� �% �? 3 ! � � c ; #� �4 $ �6 % �% &n �4 ( � ;� ($ ` � n 4 � �% n Edoc � ;� ( y ` Eget � Eset � Edoc �5 � * ^ �> f� �> gv � hj 4� o� 6� J+M �T J, �T JR- �T J� �T J�? �T 60U _ � �� g �� �< �� � �� � �_ ( + %E � 6H� � � �e b �� 0� � � 8 < �� @ _ �q t�� uany �� U�A �� UY0 �� U^0 � � � � 6P� + � � � �8 �� H =( � v L T 9c Q�% Qz QF QX6 � o ;W# U� � V "M W � 42B � %M -� $� �M .D � � 5 4Q8 o 4� 1o 4 � 6 � [ G ( 5 � 4� � 6( q � [ q WL � G $q XG @ 4! � V$ � 60 � � � 4 � � � � 2 q ( � � � 4FL � *' ^ G2 � � - 3 2G Q G 8 � G �% ] c 2G � G � 8 ) G * � 68 � � � �D � �- G x G 7' G (= 0 � �N � 6@ P) !� �M "� 8 t2 #� ;� ( ,n � -� � .s � /� �/ 0 G wG n � 1, ;�& =� �" > n ? � �& @� ;� h K< �A Ly � M (� N 0�H O� 8�H P� @�F Q < H�$ R� P�- S � X� T � ` � � U� 60 � � � �G G �- G 6' G = ( � N 4n � � 2G � G � �F � ;�F � * � � � n �) n � n � n �% n �# n $E n (7 G 0�D G 8�@ G @[7 G H� G PwP G Xc &� ` 'G hR% (G p O )G x + � �v ,G ��M 0 � � % <; �� =A �NA > n �� ?A � � 6 ^� A * �6 ! S \�= p"M � " ? "1/ �1 "7/ ;K "G (E "G 0 B "G 8� "q @� " q H�' " G P�D " � Xa " � Y� ""G `[ "$ n hs4 "* n l\H "+ n pg& ", � t , "-=/ xA9 ". h 4# # � G $k x_ts %1' P %4� � %5� � %6� �= %9Y �E %: n � %; � $�$ %= � %uJ %? n (� %D n ,� %E n 0* %G8 8�= %H8 @J %IG H/ %JG PB< %MG X %NG `� %OG h� %T� p3E %X� �`5 %ZG �( %\ n �� %^G �LF %_5 ��- %a n ��G %bG �- %{ � ��8 %| � �nG %~ n �, %�G �cE %�G �n3 %�G �� %�� �yid %�� `Q $3 z_is O %D J 2n h G Y n G ;� %"� E< %)G %)G � %)&G �> %+ � h ' %-h k ' � _ �I � �> � � 2n G G � � * 4jI &SG 4�0 &XG 4! &]G 4� &`G 4�D &aG 4 &bG 4&3 &kG 4c &mG 4�; &�G 4M &�G 9�5 <�M �� <�= �� < %G �� ~! ' n �% ( n �< ) �+ * 5 $ � . 9� � � V� 0�S )"5 �� V� 8�~ )"5 �� )U �n 0 K(? � )� @G )D Aq )P) E ) FG )YA G n <�N H~ <j � K�> � )P) E )J+ NG @)�= OG H) 2 PG P)�O QG X) RG `)4 SG h)�5 TG p)h XG x)�% Y n �)�F ZG �)! [G �)�I \2 �)� ]G �)z ^G � <�! _� < �� K� )� �! ) � n � <6 �� Ve �S )[ � n )�> � n )� �!S 0; G � ]�2 % n {p & � �B * G � � � 5 $� � , � HJ $$ - � FJ /$ . � DJ :$ / � BJ � ' 5 $ %1 0 ' ?J � 1 ' <J � j 5 $Z 2 j HN 3 j � � 5 $� � 4 � 8J - 5 � 4J �$ 6 � 0J � � 5 $� �> 7 � (J �B 8 � J � 9 � J �$ : � J � d 5 $T F ; d J � � 5 $� �F < � J H) = � �I � > � �I 9L ? � �I �$ @ � �I 7 A d �I VF B � �I � F 5 $6 @A C F �I �4 D F �I h E F �I � � 5 $� t F � �I n0 G � �I � � 5 $� � H � �I " I � �I � J � �I �. K � xI " L � pI ! M � hI �5 N � `I K7 O � XI � P j HI � Q � 8I v R � (I � �! 5 $�! 1 S �! I V' T � I Y> U �! �H � V �! �H E' W �! �H � }" 5 $m" �" X }" �H �& Y j �H � �" 5 $�" w Z �" �H H [ }" �H � \ �! �H �0 ] � xH 4M ^ j hH F _ �" XH � _# 5 $O# F ` _# HH � a _# 8H z b �! (H � �# 5 $ $�# �C c �# d �" H � �# 5 $�# � e �# H �, f _# �G � 5$ 5 $%$ �$ g 5$ �G 0 h 5$ �G �0 i �# �G � �$ 5 $$ �? j �$ �G � k �# pG � �$ 5 $�$ �( l �$ PG m �$ 0G �6 n �$ G =6 o �$ �F � C% 5 8 $3% p C% � e% 5 N $U% �1 q e% � �% 5 > $w% ( r �% � �% 5 $�% r> s �% �F � �% 5 $�% T t �% �F � & 5 M $�% |F u & � #& 5 $& �# v #& �F SO w & � \& 5 $L& -, x \& pF � y #& PF � �& 5 $�& z �& 0F � �& 5 T $�& P= { �& � �& 5 W $�& }: | �& � ' 5 $�& // } ' F � ;' 5 U $+' � ~ ;' � ]' 5 9 $M' 0G ]' �E � �' 5 # $y' � �' �E � �' 5 ! $�' � � �' @E � �' 5 G $�' �K � �' �D � ( 5 � $�' : � ( D � 9( 5 " $)( - � 9( �C � e( 5 ' $U( � e( �C � �( 5 + $�( T< � �( `C � � �' C #> � & �B |�� @* )� � G )� � G )�2 � G )�D � G )� � G )� � G ()�+ � � 0)! � G 8) � G @)� � � H)| � � P)# � � X) C � � �))Q � @* �)� � P* �1< � `* 1�D � G �1O � G �1P � G �1-4 � G �1� � G �1Z � G �1D � G �1 � � G P* 5 G `* 5 G p* 5 Q < N � �( 4 � p* � ' � !�* p* $�* jL } � � �* � � �� �J � � �� ;* �� �� �� `� k p� @� �# {� � g' +� � �* 1� � �3 �� �� �= $� �� � �+ 5 �B ��+ � ! �� �� � �+ 5 c (�+ � @� @� � 5, 5 �2 �%, � � \, 5 � #L, � 4 � �� K �, _s _n O >') [ > $[ >� %[ <�I &�, $�, - 5 $�, � '- �B �, .- 5 R $ - < (#.- x K��- >� �T >�, �T >�J �T >� �T >�% �T >) �T >�! �T <CD � J- ; � � � �- 5 � $�- � �!�- �A � ". 5 � $. � �!". !* �!' Q. 5 E }(A. �� * x. 5 X �(h. �� � �. 5 O �(�. `� � �. 5 L& w*�. �� � �*� �� 6 " %/ � " n / " n TM " n S "�. S � %/ M/ 5 #� $.P c/ � F� $F � #D G �/ G #� �G �/ G Wn ��/ G #a '5� �/ � ) #SC �7/ �/ n 0{ � 0 G 0a3 n 0 G #iD # n 20 Y #�! "8 Y W0 � 7/ G G ?� (�i0 � #i? (�G 0 � #�M )�G �0 G G C #5O �n �0 G G #� �0 G #& n �0 G G ?� ��0 � 0n Lq 1 G 0�K -G ,1 � G ?�9 &H1 G G G ?�1 &d1 q q q #-( *IG z1 G # *$G �1 G #�& �n �1 � #�O z 7/ 2 n n n n n n G G G G G G G G n G 0� gG -2 � #6) 'G M2 G G G #� �G m2 G m2 G � 0� +� �2 n ?�' (��2 � W�H �2 G ?� (��2 � 0p@ G �2 C ?Q, '6�2 � F3< &�G #7 '4� 3 ) #sN G -3 G � #E$ "G M3 G � � #�< �G c3 0F" G z3 #: *<G �3 G G G G n #�5 G �3 G G #� , n �3 G � 0v= &8n 4 � ) C F� -9 #�? *+G #4 0{. )Dn ?4 G G #�F &)n U4 G 01 n l4 G Wo ��4 G � G � � 0� �n �4 G 0x" �G �4 � � 0i# G �4 G G 0v3 )�G �4 G � 0y1 �G 5 � 0�2 fG @5 � #m +>� `5 � n ) #M3 +*� �5 � c ) 0�E IG �5 n 0�! ?G �5 G G � `6F .D#�/ .Cn �5 #�G �G �5 G 8 ) G #� �G 6 G `. &#�% "G 96 G G � 0� )G U6 G G 0�' )!G q6 G G # G �6 � #�I �G �6 G G #+ &(n �6 G G 0. TG �6 G G G n #b �G �6 G G F� %� � ? & !7 G G ?�6 &287 G G #�' )�G S7 G G # )�G s7 G G G #n. #G �7 � C 0, )Gn �7 G G #� G �7 z 0� )�n �7 G G #� �G �7 G 8 ) G 0�= �G 8 G G #�> G /8 � #� ,n P8 G � C #cF z f8 G #�< n �8 G � q q #b G �8 G G #`+ "n �8 G G #s- � �8 G #T+ <G �8 G G G #_ %n 9 G G #>B //n (9 G #�K �n H9 G G n #�< +A n h9 c c ) 0 � 9 G #0 &�G �9 G C FP &G FN> G #_2 n �9 G G G #�6 :n �9 G G #0 9G : G F�L *"G #g" �n :: G G G #6 �G U: � #I 0%G p: � #� G �: � #�5 �n �: G G #� G �: G ?TN & �: G # ? (G �: �: � C9 �1!G ; b �1<z �M �1 G C; x �1>G m �1u res �1 G �P �1G p; { �1?G �D �1� + |1n �; x |1:G O# }1n �M 1 n �; t 1:�; B 1Hq �K 1c� str 1G �, fP �0G �< 7 �0/�- ^7 �0q " �0G 5 �0G �0 ^ �0G �# �0G �N �0!G HO �0?G Q: �0SG =2 �0� s& �0G % 1�< i �0� b: �0� FO �0� �' l0 n #= � l055 �G l0O5 @& l0_n � m0< � s0#= � 3= 5 � � N05 �= y R05 8� �G T0 � U05 �K V05 %M W0T i X0 n % 60n �= err 60FG E< 60UG *M! &0 n 0� � �:@ E< &0=G �B &0QG l d 3i '0� � � 3n '0� / - � 3t .0G T R � }� }� /0 �> � y w � }� }� | � � � � � � � � � � �� �� /0 %? � � > < � c a :@ �� � 00f@ � � Y@ � � L@ � � �@ �� �� Z #0�@ � � �@ A D B A �� , �? A k g A � � /�@ 0 �@ �@ A /,A 0 IA >A � � sH 0n t@ err 0MG � 0\G � 0qG 4N 0n �@ cls 0<� a 0O� b 0`� mro 0G i 0� n 0� � 0G �) 0n ,A a 08� b 0I� mro 0G i 0� n 0� �8 �/ n UA a �/(� b �/9� : �/ G �A �/L8 1 �/? A �/5? TQ �/u MO �/; one �/ n � �/n -5 �.#8 �D x �.JG 1 �.? A �.5? TQ �.u %� �/%\ �/OB val �.8 tmp �.G �� �A Uv qB �. � A �. � �B �.�D �B �. 5 A �. 5 �B �. 5 A �. 5 �. 5 A �. 5 C �. 5 A �. 5 *C �. \ A �. \ LC / � A / � 'D /�D �C / z A / z �C / 5 A / 5 �C / z A / z �C &/ 5 A &/ 5 D // z A // z 8/ 5 A 8/ 5 bD B/ z LD A B/ z =\� P8 U�U �D E/ 8 A E/ 8 val J/8 ret K/ n one V/ n � V/n MO W/; � �P k. G >E k.<z 1 p.� A p.%� TQ t.u MO �.; one �. n � �.n q m-z H x m-:G 1 r-� A r-%� TQ v-u %� d.%\ `.�E val x-z tmp y-G �E �- � A �- � KF �-�D F �- 5 A �- 5 ,F �- 5 A �- 5 �- 5 A �- 5 mF �- 5 A �- 5 �F �- \ A �- \ �F �- � A �- � �G �-�D �F �- z A �- z G �- 5 A �- 5 )G �- z A �- z KG �- 5 A �- 5 mG �- z A �- z �- 5 A �- 5 �G �- z A �- z �G . 8 A . 8 val .z ret . n one . n � .n MO .; �) o,n ,K x o,8G 1 t,u A t,#u TQ x,u %� f-&\ b-�� �H val z, n tmp {,G �� H Uv �H �, � A �, � =I �,�D �H �, 5 A �, 5 I �, 5 A �, 5 �, 5 A �, 5 _I �, 5 A �, 5 �I �, \ A �, \ �I �, � A �, � ~J �,�D �I �, z A �, z �I �, 5 A �, 5 J �, z A �, z =J �, 5 A �, 5 _J �, z A �, z �, 5 A �, 5 �J �, z �J A �, z [� �9 �� P8 U�U �J - 8 A - 8 val - n ret - n one - n � -n MO -; ! (, G �K (,:n 1 -,u A -,#u TQ 1,u MO F,; one N, n � N,n }�7 �+ � � ��a 5 �+, � �+:n � a �+$n & " �+9 $ j> �+7/ � � �= �+Y 2L �+� � � c# �+G � � � �+G � � , �+ G � � 7bad �+�c H� P2 �+FX d x ^ d � � P2 +d 8 0 8d � � Ed m ] Rd / # _d � � 1� Q� Q� & �*mM f� � � Y� � � L� � � ?� ld 3 �M 8 �� `3 �* W < : J a _ `3 d � � �� 6 n� 6 " �� �� �* @N 0 � � X �� �� � f � � � �3 �*�N % = � �3 � K s o N� �/ s� � 4 �*%P �� � � �� � � �� % ! �� c _ 4 �� � � �� � � κ * $ � @4 �qO y u = � p4 � K � � a� �/ � �4 ��O � � = #� �4 � K ' # {� �/ -� 5 � a ] = 2� 05 � K � � �� �/ �d `5 X �d � � �� �� �5 �*!�W �� ? 9 �� � � �5 ¹ Ϲ � � �� }� `6 � {W �� - ) �� g c `6 ¹ � � Ϲ ܹ �� �6 � 'W �6 � � � ܺ �� 07 � oU � � G = �� � � 07 � � $ �= ҟ �7 jtT �= � � �= � � �= ҟ 8 60�= ( " �= w q � ҟ ҟ 80 ;R � � � � ҟ ҟ | � � � � � 7 5 � � � 80 �R � a _ � � � � � � � � �8 90 �R � � � � � � | � � � � " � H F � �� �� 90 MS � m k � � � � � � :@ � �8 :0^T f@ � � Y@ L@ Y U �@ � �8 #0�@ � � �@ � � �8 A ! ! A � ! T A E! A! A ~! |! /�@ G� 0 �@ �@ A /,A G� 0 IA >A �! �! �� �6 U| � �� �� g �T � �! �! � �! �! � " " #� o� o� x hB� ;" 9" 5� `" ^" O� �" �" Z� # �" �= �� �� % S �= &# $# �= K# I# �� 7 U| s� �8 � W �� r# n# �� r# n# �� r# n# �� �# �# �8 �� �# �# �� $$ $ κ s$ o$ ޙ 9 �EV �$ �$ = � P9 � K �$ �$ � �/ � �9 ��V !% % = � �9 � K [% W% �� �/ �� �� � �% �% = � � � K �% �% � �/ U| �� �6 �� }� �9 �� �% �% � & & �9 $� S& O& ?� �6 Ý �6 Q0R1 X � : �* �W f = �� P: �* �W K �& �& 6� �/ � 6 ٝ 0 U�� |� �0 ֗ 0 7X U�� 5� : c L� �: �+�Y /c �& �& �: <c ' ' Ic �' �' Wc L� �: $+*ic ( �' vc O( I( �: �c �( �( �c �( �( �c _� @; + MY �c �( �( �c 5) 1) �c o) k) @; �c �) �) �c * �) �c |* r* X �� �� +f �* �* ʘ p; �+�Y + + = ʘ �; � K R+ N+ ٘ �/ �Y U| H�� �/ ٘ ٘ �+[Z �+ �+ = ٘ ٘ � K �+ �+ 1� @� < �+ �Z f� �+ �+ Y� 6, 0, L� �, �, ?� �, �, �a k� `< �+~\ 3b C- ;- &b �- �- b . . b �. ~. `< @b / / Mb �/ �/ Zb �� �< �+�[ K0 G0 = ߛ = � K �0 �0 � �/ U} t� P= �+�[ �0 �0 = t� t� � K �0 �0 �� �/ U} �� �/ \ Uv T} Qs �� �2 J\ U |1 T} Q �: R| �� �/ b\ U} כ �/ Uv Qs s� �� �= �+ ^ �� �0 �0 �� _1 [1 �� �1 �1 �� �1 �1 �= �� 2 2 �� O2 K2 κ �2 �2 �� �= �T] �2 �2 = �� �= � K �2 �2 �� �/ �� > ��] 73 33 = Ś @> � K q3 m3 x� �/ U} К p> � �3 �3 = ՚ �> � K �3 �3 k� �/ Uv db � �> �+ �` b %4 4 rb �4 �4 �> �b 5 5 �b � �> d+�b �5 �5 �b c6 Y6 �b �6 �6 �> �b O7 K7 �b �7 �7 �b 8 8 �c �� @? >+ 7_ �c �8 �8 �c G9 A9 �c �9 �9 @? �c �9 �9 �c R: F: �c �: �: X j� j� V+l_ f h; f; c �? �_ c �; �; � �/ T } $ &4$ X �� �� :+ �_ f �; �; �b E� $ r` �b �; �; X K� K� B+ 3` f �; �; = P� P� C+ K $< "< _� �/ ў �2 U �� �? �+ �` K< G< = �� @ � K �< �< ^� �/ Us �� 0@ �+ Oa �< �< = �� `@ � K �< �< Q� �/ Us Ĝ Ĝ * �+ �a 9= 7= = Ҝ Ҝ � K `= ^= >� �6 �� 20 �a U~ T| R0 ʘ 0 Uv � �+7/ db 5 �+ �+'n �+n " �+& j> �+7/ 5 �+G 7bad �+ 8g$ X+ �b X+*n � X+Q ]+#�b 8�# ++ c ++E�b ++Un � ++| pos -+ n i -+n � .+!S c tmp @+% � G+ n 5 +$ Wc +?n +#�b { $+! � +$ �c +Z�b +jn � +! pos + n �@ �* n �c � �*BS [ �*On �*Zn , �* n mid �*n end �* n \M �* n �d 2L �*3� �*?n � �*G c# �*G � �*G , �* G � �*q �d � �* � 0� �* G (� M �*G =0 �*G )e ml �*4� �% �*<n #2 �*MG �5 �*1G �5 �*DG �*VG 4 �*iG op �*G �* n Ve �5 �*,G � �*�* *� S*G Ѕ � �Rg P) S*RG �= �= �$ S*i8 .> > J: S*v) �> �> � S*�G ?? 1? U* Rg �? �? 3cls V*� �@ t@ Z*� A A ? \*G yA uA �6 a* �A �A � Ѕ Z*_f � �B �B �n � ` c* "g o �B �B o C C �n fC ^C ` o �C �C �z 0� � �) �z D D �z ID ED � �z �D �D V� 9 T 0 R 1 R� >g Q�TX�R G(� Q�T# � *�" 1*G `� e �?i P) 1*KG �D �D �$ 1*b8 |E pE J: 1*o) F F � 1*�G RF FF 3* Rg �F �F 7*� ~G tG ? 9*G �G �G �6 >* /H )H � `� � 7*Lh � }H {H �n o� � @* i o �H �H o �H �H �n II AI � o �I �I �z �� � �) �z �I �I �z ,J (J � �z gJ eJ �� 9 T 0 R 1 R� +i T�TR�R G�� T�T# ~�G *G v � �l P) *;G �J �J �$ *R8 AK 7K J: *_) �K �K � *qG L �K * Rg �L �L *� {M uM ? *G �M �M �6 * 0N (N � v � *3j � �N �N �n v * �k o �N �N o fO ^O �n P �O o �P vP �n �v �v ) �)Ak o Q Q o ?Q =Q �n dQ bQ o �z �v �v " �) �z �Q �Q �z �Q �Q �z �Q �Q �v 9 T 0 �z �v �v �) �z R R �z 0R .R �z UR SR { `v `v % +* ,{ { {R yR { �R �R 9{ �R �R �v 9 T 0 R +0 *hK �)G `� � ��n P) �)@G S �R �$ �)W8 �S �S J: �)d) 8T 4T � �)vG �T qT �) Rg XU JU �)� V �U ? �)G �V �V �6 �) �V �V � `� � �)�l � ?W =W �n s� � �) Vn o pW bW o X X �n �X �X � o /Y #Y �n � � ) �) n o �Y �Y o �Y �Y �n Z Z o �z � � " �) �z 6Z 4Z �z dZ bZ �z �Z �Z � 9 T 0 �z � � �) �z �Z �Z �z �Z �Z �z [ [ { �� �� % * �n ,{ { ([ &[ { V[ T[ 9{ ~[ |[ Ն 9 T 0 R 0 G�� T0 > �)n )o �)XRg �)k� � �)|G ret �) n �6 �)G �o P) �):G �$ �)JG kw �)ZG { �)G �) Rg vc �) k@ �)� eG �)G ? �)G =C �) G p P) �)@G arg �)PG kw �)_G ? �)G { �)G *'D R)G 0m � ��r P) R)9G �[ �[ ? R)IG w\ c\ 5arg R)YG n] N] 5kw R)hG �^ �^ 3f \)�r ` ` �6 ]) �` �` �% ^) n �a �a A `)� �b �b ! q { �)G C? �)$G !c c G�m U�T { �m �m r) eq ,{ Gc Ec { lc jc { �c �c 9{ �c �c { �n ` �) �q ,{ �c �c S { +0 �{ d d ` 9{ 0d .d �m 9 T 0 �z cn cn & �)Pr �z Wd Ud �z �d �d �z �d �d �n 9 T 0 R d0 Rum sr U�TT�QQ�R �m �: �r T F0 &n �8 �r U�R Qn �8 �r U�R �n �8 U�R � *�L I)G �o �Gs 5op I)/Rg �d �d M K)G =�o �2 U �0 Q�U �; -) n }t m -)>Rg �? -)K� arg -)X� �s e 0) n �s 2 3)n a+u v T| �s 2 7)n :Au T| �s 2 9)n :Wu T| t 2 <)n !t 2 =)n 4t 2 @)n Gt 2 B)n Zt 2 C)n mt 2 D)n 2 E)n b�L () �t ) �2u 5m ()>Rg )e !e 2u �t � +) u @u �e �e �t �2 �t Uv u Lu u Uv = u �2 U�U �t �2 Uv 8P !) Lu m !)?Rg *q )n pr j �z 5m )0Rg �e �e ! �u � )G rf nf = �r @ )K �f �f �t �/ !p $v � )G �f �f = �r � )K g g �t �/ !� uv � )G Zg Vg = �r )K �g �g �t �/ !0 �v � )G �g �g = �r ` )K h h �t �/ !� w � )G Bh >h = �r � )K |h xh �t �/ !� hw � )G �h �h = s )K �h �h �t �/ !P �w � )G *i &i = 's � )K di `i ut �/ !� x � )G �i �i = Bs � )K �i �i et �/ ! �x 3cls )G j j Xs @ ) Lj Hj = ]s p � K �j �j Ut �/ !� �x � )G �j �j = ~s � )K �j �j Et �/ ! "y � )G 4k 0k = �s 0 )K nk jk 5t �/ !` sy � )G �k �k = �s � )K �k �k %t �/ !� �y � )G l l = �s � )K Vl Rl t �/ � )G �l �l = �s P )K �l �l t �/ RK �(G �z op �(@Rg ml �(Q� �% �(Yn #2 �(jG �5 �(2G �5 �(EG �(WG 4 �(jG cf �(�r I�N �(G �z m �(1Rg �$ �(>G { �(G 8�O b( { P) b(GRg � b(Y ` k( 8�C S( G{ P) S(QRg � S(c A S(w� ` \( 9 @(G �{ op @(;Rg n3 @(E� { A(G �- "(G �{ op "(ARg #( n %� :(�- %(G �5 %((G *< %(1G � %(<G *�I (G �l @ ��| 5op (:Rg �l �l n3 (D� *m &m { (G gm cm �| �l ` (�| �m �m ` �| �m �m X �l � (�| f @n <n �l �9 7 (G �| op (ARg { (G 9 �'n /} op �':Rg �'HG n3 �'U� tmp (G *� �'G �q � ��~ 5op �'9Rg ~n vn n3 �'C� �n �n { �'G �~ �q � �' do \o � �o �o X �q �q �'�} f Wp Up �� �q �q 4 �'Ɓ |p zp ҁ �p �p ߁ �p �p X �q �q �'r~ f q �p X �q �q �'�~ f &q $q = �q �q �'�~ K Kq Iq �q �/ :�q Us �'G ) op �'@Rg { �'G BI �'n q op �'9Rg �'GG n3 �'T� tmp �'G *S �'G � � �@� 5op �'7Rg vq nq n3 �'A� �q �q c{ �'G @� � �" �'R� \r Tr �" ^� �r �r X � � �'6� f Os Ms �� � � 4 �'Ɓ ts rs ҁ �s �s ߁ �s �s X 0� 0� �'�� f �s �s X <� <� �'� f t t = @� @� �',� K Ct At K� �/ :� Us �@ �'G l� op �'>Rg { �'G � �'n �� op �'7Rg �'EG n3 �'R� tmp �'G 0 �'n � op �'8Rg { �' n res �'G *78 �'G �l �h� Xop �'3Rg UYn3 �'=� T{ �'G jt ft X �l 0 �'f �t �t *\1 �'G �l �҂ Xop �'6Rg UYn3 �'@� TX �l �l �' f *� 'G pl �D� Xop '6Rg UYn3 '@� TX tl tl �'f �t �t �: k'n �� op k'3Rg k'AG n3 k'N� tmp z'G *� a'G �l 5 �I� 5op a'3Rg u �t n3 a'=� >u :u { d'G {u wu I� �l � f'[� �u �u X �l � ]':� f v v m �9 �) V'G h� op V':Rg �& G'n �� op G'7Rg G'EG n3 G'R� tmp Q'G A <'G � op <'7Rg n3 <'A� { ?'G ^ -'n 1� op -'3Rg -'AG n3 -'N� tmp 7'G *�) #'G o / �� 5op #'3Rg Gv Av n3 #'=� �v �v { %'G �v �v � o � (' � <w 6w X o � '߅ f �w �w 0o c3 � 'G � op ':Rg *�$ 'n r A � � 5op '2Rg �w �w '@G x x n3 'M� �x |x !0 � 3tmp 'G �x �x 1r � ' �x �x = 6r � � K 1y -y Lr �/ X %r 'f iy gy *Z% �&G @o E �� 5op �&2Rg �y �y �5 �&<� z z { �&G az ]z � @o '� �z �z X Io ` �&�� f { { X xo xo �& � f fo M3 ,J �&G � op �&9Rg 2 �& G r� P) �&JG vc �&e �$ �&z8 �&�) kw �&�G �? �&� N l&G X� P) l&?G vc l&Z �$ l&o8 l&|) kw l&�G res n&G � o&G �H p&q 9 q&q i r&� pos r&� j s& ) key t&G t&G � u&5 nkw z&� %�C �& *�5 b&G �n �1� P) b&/G W{ Q{ ? b&?G �{ �{ 5typ b&OG �{ �{ x o � e&� � I| G| X o o �f n| l| =�n �3 U�UT�T �1 &� ؊ �5 &>G � &Sm2 � &cG �5 &G �< &#G - &8G }< &JG 5 &\G n & n 5 & % E&7bad J& |4 �% n � �< �%-G ` &, � &+� � &� 0) �% G q� d �%BG key �%OG E �%^G @ �%<n �%G d�0 �%G � �%G � n �%/� Cva �% l �%G 7end �%i �%� arg �%G � �% G *�O y% n fU � �.� �J y%)G �| �| 3ret z% n } �| �. {%G H~ 6~ G |%G k }%G g W �. ~%G %� � %G � �� H/ �%G �� �� � �%G �� �� 7- �%G S� A� 1 �%G � � &_ �%�W &.? �%�W D�W [� �%� y� w� �W 9 T �? �� �V �5 �%ҍ ۔ �� �� ϔ ΄ ʄ �5 � � � � U� S� �V �0 �V �0 U~ �� W �5 �%I� ۔ |� z� ϔ �� �� �5 � � � � 2� 0� &W �0 5W �0 U~ �W �W �%Î Y� W� = �W �W � K ~� |� �W �/ Us �W �5 �%3� �� �� = �W �W � K � ߆ �W �/ U�� �W �W �%�� � � = �W �W � K -� +� X �/ U X X �%'� R� P� = X X � K w� u� X �/ Uv X X �%�� �� �� = X X � K �� �� )X �/ U| �U 1 �� U~ �U 1 ѐ Uv �U 1 � Uv �U �� � U~ �U 1 � Uv V �� 1� U~ :V �� I� U~ SV .� a� Us yV Y� � U~ Q �V �9 �V �� �� U~ �V 6 �V �� ɑ U~ W Y� � U~ Q| EW �9 RW �0 � U~ �W �9 =X .� Uv *@ i% n U W �Y� �6 i%2G � � ` i%BG +� !� 3ret j%n �� �� �H k% G �� � /U �. v%� X� T� = PU PU � K �� �� ^U �/ Uv "U �� ,� U�U /U 6 IU (9 Uv T| Q2 *J S% n �F } ��� 5tp S%3� �� �� 5k S%AG � � 5v S%NG ]� W� { T% n �� �� � U%G � � D G 2 r� �D `%G � � = AG AG b% L� K F� D� KG �/ 9G 0 Uv Q} R~ X0 �F �9 �� T~ Qv G �0 �� U} G �0 Uv � D% n � tp D%3� k D%AG { E% n � F%G *�& �$ n �R m �Z� 5t �$-� w� i� 3r �$ n � � � �$G T� L� DoS � � &O �$ n �� �� 3ret �$G � � �I �$G A� ;� 3gc �$G �� �� D]T � � Ltp %G ��Lv % G �@Ltb % G �H �T �T %|� � � = �T �T � K +� )� �T �/ �T �T %� P� N� = �T �T � K u� s� �T �/ �T �T %b� �� �� = �T �T � K �� �� �T �/ �T �T % � � = �T �T � K � � �T �/ qT H1 �� U��T�@Q�H �T !� � Uv �T ,1 p; �S �S 1 �$v� �; 0� ,� �; h� f� �S U4 U| = �S �S �$ �� K �� �� �S �/ U| = T T �$ � K �� �� T �/ = T T �$ J� K Տ +T �/ Uv = �T �T % �� K �� �� U �/ Uv {S z1 �S d1 �S !� ř Uv T !� ݙ Uv GT �1 U} Z� �R P �$ >� l� #� � -w� �R x� [� Y� �� �R � �$D� �� �� �� �� � � �� i� c� � �� �� �� ˛ $� � (֛ � כ �� �� � � � � �� � y� u� -S 9 T �9 (� 0 � �� �� (� ` � � � eS 9 T �9 =�R �1 U�U ? �$n �� t �$L� � �$G /: w$ n !� � w$3 �+ w$I� � w$_G i x$� n x$� b �$� b0 �$G � ^ �$ � �+ �$� ^ �$$� *� f$G tP . ��� 5obj f$7G Q� K� D f$FG �� �� g$G �� �� { g$ G '� � h$ n Ö �� 7bad q$�� tP � h$X� ڢ � �� ͢ i� Y� �� � � � � �� u� � � � � E� ?� � �� �� � � � %� �� �� 2� �� �� ?� � �� 'L� �Q X �P �P $ �� f g� e� X :Q :Q 6$ ܝ f �� �� 8 =Q 0 7$R� W �� �� J � � 0 d B� <� OQ 6 C� U��T| eQ 6 = eQ eQ >$ �� K �� �� tQ �/ U�� = �Q ` F$ ڞ K �� �� �Q �/ U s �Q �Q Y$� � � ٜ ל U� �Q �� V� �� �� X �Q �Q [$ o� f #� !� = �Q �Q \$ K H� F� R �/ Uv X ;R ;R 9$ � f m� k� = >R >R :$ 5� K �� �� HR �/ U�� HR HR ;$ �� Ν ̝ = MR MR � K � � ZR �/ U �P �� ͠ Us T| �P 1 � U~ T| �P �1 � U~ -Q �0 � Us .�Q 5� U Ts �Q 9 T �9 R| e� R � j$Ρ �� � � w� =� ;� � "�� ��)R �< U T��Q ���������+U� 0 = /R � k$ � K b� `� 9R �/ U �� \R � o$t� �� �� �� � "�� ��zR �< Uv T��Q ���������+U� 0 = �R p$K �� �� �R �/ Uv S $ n e� obj $/G ` $>G $Oq �H $G � $� tp $� 7 $G f $� �1 $q `5 $G �N $ n %83 W$�+ Z$G � $ G �� P) $DG arg $TG �$ $@* � $ G ̣ P) $CG arg $@* � �# n � � �#5� J �#� ^ �#� g/ v# n 5� � v#?m2 � v#S� � Q#n i� o Q#2G n Q#?G r R#G *1 )#G �� : ��� �5 )#-G ߞ Ϟ ` )#?G �� �� *#G "� � %�. D#!� � �N ,# � � � -#G J� @� %G .#G ġ �� ' /#G >� 4� {� P! E# �� �� �� = {� �! � K � � �� �/ U }� �! F# �� &� "� = }� �! � K `� \� �� �/ U~ �� " G# o� �� �� = �� �" � K � � �� �/ Y� Uv ы �/ Uv %� 6 -� �0 �� Uv :� M3 Q� �4 �� Uv d� �4 צ U~ T} t� z1 U �� �� � *#\� � <� 4� � �� �� � $� �� �� .Ɗ M� Uv T} � �6 �� ?4 � 9 T 61 Q} �L #G �� ` #)G �N #9G VM #Hn �5 #G = #G qF #G 7bad "# C �"G <� d �"1G key �">G �"G �$ �"G tA �" G {� o �"9G n �"FG d �"SG r �"G ME �"G �� d �"2G ,L �"� by �" 0p � �N� � �". .� "� WH �"GG �� �� Lkey �"G �`D�p 6 �� Lpos �"� �hX �p �p �" Y� f 5� 3� �p 9 �p f8 U�XT�hQ�`R0 � Ip Ip �"!ܩ � Z� X� � �� �� � �� �� = �p � �" � K Ц ̦ �p �/ .[p ,� U�TT0 �p 9 T �4 Q| H? j"G )� 2 j"2q U j"E� dN j"]� �H k"/� ! m"G $ n" n O n"n i o"� o"� [ p" � %b �"7bad �"+ |" n kN }"� b ~"� ( "G �+ " G � "=n cC "O� �5 "[� � "n� " � G " � end "� " g "� kN "� EP " n Q "n " n 1 !"u A !"#u TQ %"u �; 9" n � +� 5 I- �!G ͬ �!9n kN �!K� �5 �!Y� �� � �!ͬ 28 �!� �� � �!� \ "G T "G � "+G { "5G � ݬ 5 � � � 5 $ݬ � �!n � �!6n = �!G �� kN �!<� � �!Q �5 �!\n EP �!5n �5 �!H� ( �!G 29 �!� i �!� b �! � � y! G �� obj y!BG K [!G �� d [!8G key [!EG E [!TG \!G T4 !n 7� �& !, obj !@G � !� .= � n �� obj � )G � � <� ` � N @ � Xn � � � � � � �P � G � � n 8e5 � � �= � @ � n � � � � � � jA � � �& � � #; � �? � n �� WH � G 9 � 8 ^/ � �� a" � G 2 � q J5 � � �O � � � � �! � n w �@ z n ˰ WH { G 9 | 8 ^/ } �� a" ~ G 2 q J5 � � �O � � � � �! � n key � G ` � �� 7 � �� 7bad � %iC � pos � � �� � G � � ) cmp � n �� � G � G I}0 C n w� WH D G ^/ E �� a" F G 2 G q J5 H � � I ` K �� 7 L �� len M � 7bad w key R G S G g7 n >� WH G ^/ �� 2 q J5 � �O � � �! n ` �� 7 �� U) � 7bad @ key ! G " G �N # n 8�, � Ʋ WH � G ^/ � �� 7 � �� � � pos � � key � G ` � �� � � ) cmp � n � � n � key � G ^/ � �� 7 � �� � � � � � ) m6 � n �� key � G ^/ � �� 7 � �� � � � � � ` � �� %u � 7bad � %�- � �� cmp � n cmp � n �: x n `� key y G ^/ z �� 7 { �� � | � � } ` �� �9 � � 7bad � %�- � P� �N � G �N � G 9 m n �� s1 m ?G s2 m MG , n n len o � 4A s c :A t c IB X n 7� WH Y G ^/ Z �� 7 [ �� � \ ` ^ �� 7bad i key ` G �N a n 8�F � `� �= � % � G 8�, n � � n #G n 3G tb n DG �" n RG �O o G 7bad � � Y9 � G ܵ * � n �$ � G �� �" � G 2L � � �* � G � 5 G }� P) 5 FG �$ 5 ]8 5 j) �O 5 |G 6 � f V �9 % ö :9 KG tp ! � 4 + � ptr - Z- � G � P) � CG arg � SG ? � G { � G / � � G j� P) � >G arg � NG kw � ]G { � G � � x �" I G .� o I @G i I N� & I Un �L J Ln � K Ln ʷ n N � � n T � r V G mm [ � sm \ { � r ^ G key ^ G l f � wE 7 G �� o 7 FG i 7 T� �L 8 Un � 9 Un � ; � r @ G 7% % G � o % EG i % S� �L & Un � ' Un � ) � r . G | G � o 5G j BG r G �? �G c� ` �7G � �Jc� �cq { G � �8 �G �� ` �1G { �G �2 � G ܹ obj �KG $ �ZG { �G tp �� 8&. � �� ,L �� �H � G 1� obj �DG $ �SG tp �� 8�( �s� 2L �@� � �Sq �dq tb �vq 8$ uܺ 2L uB� � uTG udG tb uuG 1 �G � �G �* �&G H Wn #� 2L WM� err W_G { X n E< YG s% L n f� E< L8G �B LLG i M� n M� k: n �� %�" $ s � n � � �6�* ^ � G 7bad 7 �+�- ^7 � �� 7 �+�- ^7 � � 7 �+�- ^7 �� 7� 7 �+�- ^7 �$� W� 7 �+�- ^7 �@* w� 7 �+�- ^7 �4� �� 7 �+�- ^7 �$� �� 7 �+�- ^7 �$� 7 �+�- ^7 �@* �� 7 �+�- ^7 �4� 7 +�- ^7 4� G $� 5 G 4� 5 G D� 5 � n m� � �2�* %�" � _) � n �� � �8�* %�" � 27 � n �� � �7�* %�" � *� � n \X � ��� @Q �>G � � ? �n ~� p� � ��* � � f; � G d� ^� p; � G � �� z; � G F� � ~! �n � � �+ � �� �� �% �n � � %�" �&-F ^ !�9 +� �K $G �� �� �] : �] �9 � U| T k2 �^ �9 U| T k2 !`; |� 3tmp eG ± �� = �a �; eK � � �a �/ D<^ # ٿ � �G � � = V^ : �K 1� /� ]^ �/ X �X �X �� f V� T� X �X �X �C� f {� y� � �X �X �� � �� �� � β ̲ " �X �X �� 0 � � X �X �X � f � � �X 4 U F2 � �X �X �(� � =� ;� � k� i� " �X �X ��� 0 �� �� X �X �X � f �� �� �X 4 U O2 3= .Y 6 C� 6 (\= P6 ]= ܳ س j= � � w= Q� M� �= �� �� �= �� � ?Y 4 �< �Y �6 � �< [� W� �< �� �� �< ݵ �6 = 4� .� -= �Y Y "= ��} Z �3 �� U��}T�Q h@ R3X9Y k2 Z �3 U0T��}Q1 )e nZ �6 �� ;e �� �� �6 He �� �� 1� nZ 7 �*$P� '� #� ]� s� o� C� �� �� 7 j� � ط w� k� S� �� f� `� �� �� �� �� � � �� :� 8� �� d� ^� Ŋ 'Ί v[ q� �Z �7 "&�� � �Z �7 �% � �� �� �7 � ݺ ۺ " �Z �Z ��� 0 � � X �Z �Z � f '� %� �Z 4 U �2 � �Z 8 &&�� * N� J� �� �� λ Ȼ � �Z �Z �w� � � >� <� * c� a� �Z �9 X �Z �Z ��� f �� �� �Z �8 Us T~ � [ @8 6&� V� �� �� I� � � <� ?� ;� 1� y� u� @8 c� �� �� X *[ *[ �%]� f � �� "[ -2 Us T~ Q} = :[ :[ 9& �� K :� 8� H[ �/ U} = `[ `[ C& � K _� ]� q[ �/ Uv @ p8 K&b� �� �� = v[ p8 � K �� �� �[ �/ �[ �8 F&�� �� �� = �[ �[ � K � � �[ �/ U| = �[ �[ G&� K B� @� �[ �/ U~ �Z s2 7� U T. �Z M3 O� U �Z �: g� U| [ M2 �� U| T �� Q0 Z[ ؊ Uv T D� �[ �8 5� V� i� e� �8 c� �; /\ 9 �~� �; �� �� �; �; ڿ ֿ (�; 09 �; !� � J\ c3 i\ 2 U� R0 p\ :: �\ U: �\ h9 �\ �7 �� U1 �\ �7 �� U Z� �\ �7 �� U �~ ] �7 �� U �C� ] �7 � U ��A 6] �7 � U >�� P] �7 U D ; f� `] `9 q� `9 'x� �g e] �9 �� �] �] *�� �� �� }� '�� �g �] i� m� �] �9 , � � � � �9 �� �] s7 � U3 ._ s7 U3 �� K_ P: / d� � � � X q_ �: �Q f U� q_ �: 2�� g� G� C� �: t� �� �� �� � � �� :� 4� �� �� �� �� ̣ �_ �: � ,� ޣ �: � -�� ` �� !` 9 T �@ �_ � K� U �� �_ : �_ � �_ � �� U @� X` : h` � = �` �` C�� K �� �� �` �/ Uv = �` �` G2� K � � �` �/ Uv = �` �` H{� K .� ,� a �/ U~ = Ba Ba U�� K S� Q� Oa �/ U~ = �a �a Y � K x� v� �a �/ U| = �a �a ZV� K �� �� �a �/ Uv X �a 0; c� f �� �� = b b r�� K �� �� (b �/ Uv = |b |b ~� K � � �b �/ Uv = �b �b �Z� K 1� /� �b �/ Uv = Fc Fc ��� K V� T� Tc �/ Uv = �c �c ��� K {� y� �c �/ Uv = d d �5� K �� �� d �/ Uv = ud ud �~� K �� �� �d �/ Uv = �d �d ��� K �� �� �d �/ Uv = ?e ?e �� K � � Me �/ Uv = �e �e �Y� K 4� 2� �e �/ Uv = f f ��� K Y� W� f �/ Uv = @f @f ��� K ~� |� Rf �/ Uv �g �; �Y� �� �� = �g �g � K �� �� �g �/ Uv �g �; ��� �� �� = �g �g � K R� P� �g �/ U �X �: �� T @ �X �: �� U�U &Y �: � T ^2 �Y p: 5� U0 @Z U: Y� U �1 T0 ^Z :: }� U �1 T0 <^ �K �� U A T} Q| R~ d^ �9 ^ �: �� T A �^ : C_ 6( � +�� � ` n, � U1 �` 0 >� Tv +�� 0 �` i� V� U~ �` �9 n� Qv a n, �� U1 6a 0 �� T~ +�� 0 ^a i� �� Uv �a �9 �� Q| �a 5- �� U � T0+�d 0 b �9 � Qv Rb 5- B� U �� T0+�d 0 tb �9 Z� Qv �b 5- �� U �� T4+�d 0 �b Y� �� Qv c 5- �� U �� T4+�d 0 >c Y� �� Qv �c 5- � U `� T4+�d 0 �c Y� #� Qv �c 5- N� U @� T4+�d 0 d Y� f� Qv Kd 5- �� U � T4+�d 0 md Y� �� Qv �d 5- �� U � T4+�d 0 �d Y� �� Qv e 5- � U � T4+�d 0 7e Y� /� Qv we 5- Z� U �� T0+�d 0 �e �9 r� Qv �e 5- �� U �� T0+�d 0 �e �9 �� Qv f �9 8f �9 Qv *= �$G �G a �� � �AG {� u� 5def �T� �� �� �5 �G � � � � G n� j� � �)G �� �� 7bad �� �G � � �� � �� �� �� �G c/ �G M/ +H �: T 5 x ?H � �*� � � � X ?H ?H �f ?� =� = mH �g� K d� b� wH �/ U~ I @ ��� �� �� = I I � K �� �� 0I �/ Uv WH �/ �� U} T 3 gH o/ � U~ �H �: *� Uv �H !� g� U} T~ Q �0 R �0 X1 �H !� �� U} T~ Q �0 R �0 X1 �H !� �� U} T~ Q �0 R �0 X1 I !� U} T~ Q �0 R �0 X0 B *," � n ]G ~ �� � �BG �� �� � �RG � � � �g d� `� �J �~ �� �� * ��n �� �� �G t� n� { � n �� �� = �G �G � � K � � �G �/ Uv vG �/ @� U�UT�Q �G �9 d� U} T~ Qv �G ?4 �G 6 � � n �� �1 �P �� , �P #/ _G 9k ��� =Ek �: U �� �3 n � � A�* �K n 5� � A�* � n U� � =�* tM � n �� � �;�* f; � G ~! �n �+ � �% �n %�" � � � n �� � �A�* �C � n �� � �A�* � � n � � �=�* Ih n >� o UG �- " � Ia8 n �� o XG v e� a n� e n �$ � �H � n �� o �VG �- � � :Il U�U �( � n 6� o �YG v �f� a �o� e �n �$ �� G%l U�UT�TQ�Q *M &G � p �� L &�� }� 3� 01 &�G �� s� q ' G $� � f; ) G �� \� p; *n �� �� z; +n /� -� �; ,� a� S� �; -n � �� �& . G � �� �; / G F� *� �; 0 G �� i� �; 1 ) �� ~� ~! 2n �� �� �+ 3 �� �� �% 4n � �� %�" �&8H [�� &-F �0� !@� �� 4 o@* �� \� �� q;� � � = \� �� � K F� B� � �/ Uv = b� 0� rx� K �� |� � �/ U| = m� `� s�� K �� �� �� �/ Uv T� �7 T��Q ���������R0 .� �� � B�� c� �� �� V� H� B� K� H� B� @� �� �� � p� �� �� }� �� �� ~� L� J� X � � A f q� o� .� � @� 7 V� �� �� c� �� �� K� � � @� N� H� @� p� � � p� D �� � �� �� �� �� �� p� � &� � = !� �� " q� K s� o� � �/ U~ � U6 U| T~ � q6 U0 H � �� D�� &H �� �� �� 1H �� �� >H �� �� KH M� G� XH 'aH O� � � � y, Y� � �� �� � �� �� � �� �� �I �� �� �I � � �I 0� �� �I {� y� -�I �� �I �� �� ~J � !� �J �� �� �J � � �J �� �� �� �9 G� P8 Uv �I �� @� �I rH P� .� wH '� #� �H o� _� = �� � ~, �� K � � � �/ �� U �� �/ �� U � �/ U H @� @� },Z� &H _� Q� @� 1H � �� >H �� �� KH .� "� XH 'aH � �I �� M� �I � @� @� y, �� � �� �� � �� �� � � � �I � � �I 3� +� �I � �� �I �� �� -�I � # �I �� �� ~J P� d� �J �� �� �J �� O� �J � � �� �9 s� P8 U H � � o,�� &H C� A� 1H >H KH XH 'aH � � �: T �: (rH �� wH h� f� �H �� �� ; �� �� {,�� ; f� `� �� *; �� �� 5; �� �� s � � �1 y� � � &� $� .�� �� U > C; 8 �9 W �: T L1 H � 0� },� &H Y� I� 0� 1H � � >H }� u� KH �� �� XH 'aH � � � � y, y� � G� E� � o� m� � �� �� �I �� �� �I �� �� �I l �� �I F� D� -�I � # �I k� i� ~J �� C� �J �� �� �J ,� �J �� �� �9 P8 U�� �I P b� �I H � � ' o,�� &H �� �� � 1H >H KH XH 'aH � � �: T �: (rH 0� wH .� *� �H j� d� ; � p� {,�� ; �� �� p� *; � � 5; L� F� s � � �1 }� � � �� �� .� �� U�� � C; �9 7 �: T L1 = � �� ~, � K �� �� � �/ � H U�� = ~, K �� �� 1 �/ ; � � {, ; � � � *; X� T� 5; �� �� s .� .� �1 �� � � �� �� ."� �� Uv �� C; � U U� �9 t� �: T L1 H O� O� o,&H � � 1H >H KH XH 'aH O� e� �: T �: = `� `� E�� K E� A� � �/ Uv 5� �� �� Y�� R� �� {� G� � �� �� ]� 2� ,� � �� �� S# p� � }� {� � �� �� � � � �� �� P� X# � �� �� � �� V� B� P� ¹ Ϲ 8� 0� �� @� `� � � �� �� �� �� � � `� ¹ �� �� Ϲ ܹ Z� �� � e� �� � � � ܺ p� p� � �� � � Q� I� �� �� �� p� � � � � �= �� �� j�� �= �� �� �= � � �= �� P� 60�= � � �= W� Q� � �� �� 80 l� � �� �� � �� �� | � � � � � � � � � � �� �� 80 �� � A� ?� � i� g� � �� �� � �� �� 90 /� � �� �� � �� �� | � � � � � � � (� &� � � � 90 ~� � M� K� � u� s� � �� �� :@ � �� :0�� f@ �� �� Y@ � � L@ � � �@ � � L #0�@ H� F� �@ o� k� A �� �� A � + >� A � � A � � /�@ � 0 �@ �@ A /,A � 0 IA >A .� ,� |� �6 U} T| � �� �� g � � S� Q� � {� y� � �� �� #� � �� hB� � � 5� �� �� O� @ 8 Z� � � �= d d S �= � � �= � � u 7 U} s� �� � � V� �� % ! �� % ! �� % ! �� a ] � �� � � �� � � κ �� 0� �|� I E = �� `� � K � � �/ �� �� ��� � � = �� �� � K � � � �/ U} �� �� � / - = �� �� � K T R � �/ U| _� �6 �� @� �� �� { w � � � �� $� 0 * .N� �� U} H� �6 � �6 U} Q0R1 = � � \# #� K � | �� �/ 5� � � " Q#�� G� � � R� � � ]� 2� �: T ; � �9 �� � P� c�� � 9 5 � y o P� $� � � .�� � U} 5� �6 X � � f3� f < : .� � �� k:� c� e _ V� � � K� e _ @� �� p� � � � � � ? � � � � � � � }� � .� ~� % # X � � A f J H .� X� �� 7 V� q m c� � � K� � � @� ' ! �� p� � e� �� D #� � | v �� � � �� � = }� � " � K m i �� �/ U} u� U6 U| T} b� q6 U1 = }� �� ww� K � � (� �/ U} X �� �� ��� f � �� �� � � = >� � � K 0 . � P� �T� [ S = �� �� � K � � Y� �/ Uv �� � ��� � � = �� � � K �� �/ Uv j� �9 � �: � T �; � �K U @> T| Q} R �1 S �" �G � �> �sG ��G 3+ ��z 01 ��G && � G L � G q � G f; � G p; �n z; � G �; � ) ~! �n �+ � �% �n %�" %-F 4 �@* ZT %G � p � �> %eG g S c0 '8 X D ')� g 5 QH '@G � q , G E + 3+ -z d ^ 01 . G � � 3 2"8 � � 2 3 ��~! 4n � � �+ 5 � � �% 6n � � q 7 G � � &�G o &� k� &% m, & v, !0� / V/ C( ���8 D� _ O !� � �$ W� % !P �� 3i Y� l ` �� � � Z%� � � � . , ڮ . , ͮ T R �� z x � � � � � � � � 9 T �4 Q 2 R �0 X3Y �0 x Q�� � X �f ; 9 � ( 0 X - U� l ^ �� l ^ �� ! ! |� �! �! o� �" �" b� �# �# H� P$ B$ ;� % �$ .� W& I& � ( 0 � !� � �& �& � ' ' 0 � ;' 9' @�� ` � z � $� � � �� � ֯ ɯ �� ` 1� l' `' >� �' �' K� X� 'a� � j� P k� !( ( �� � � "�� ��~�� �( }( �� @ � �� �( �( x o � � '� �( �( X o � �f ) ) Ʋ � � � � *) &) �� v) r) � � �) �) ز �) �) s � � � x � � \* Z* � _: � U��~T��~Q R��~X 2 1 U��~T��~Q R��~X 2 (x� }� �* * x � P � %� �* �* X � ` �f �* �* 9 T �4 Q 2 � O � � U� �* �* �� �* �* ;� H+ @+ �� �+ �+ |� 3, -, o� �, |, b� �, �, H� >- 8- .� �- �- w� O � � ױ �- �- ʱ L. F. �� �. �. �� / �. �� i/ c/ �� �/ �/ �� 0 0 � � 0 w0 � �0 �0 �� }1 q1 � � � , � 2 2 "� +2 '2 /� g2 a2 X p ) f �2 �2 � �8 U| � �9 >� � P ; s� �2 �2 f� (3 $3 Y� v3 r3 L� �3 �3 P "�� ��~"�� ��~�� � � �� �3 �3 (�� � "�� ��~�� 44 04 Ʋ c � � � n4 j4 �� �4 �4 � �4 �4 � H5 D5 ز �5 �5 s c c � a � � �5 �5 � _: � T��~Q R} X 2 1 T��~Q R} X 2 � 9 T �4 Q 2 ' f8 U| Ts Qv R0 T 9 U| x \ � I� � �5 �5 X \ \ �f 6 6 x i � M� 56 36 X i i �f Z6 X6 >E � g PE �6 }6 [E 7 7 hE �7 �7 uE �8 �8 �E �E � � � w- � � J9 H9 � r9 p9 � �9 �9 �F � � �F �9 �9 �F � �F : : -�F X �F [: Y: �G , $ �G �: ~: 1 P8 �F � ! C �F >E \ ` m-PE �: �: ` [E hE uE �E �E (�E ` �E �: �: �E %; ; ; \ y-R ; �; �; *; �; �; 5; < �; s � � �1 ) � � u< s< C; � ` �1( U; �< �< ` b; �< �< � � � �1 � � #= != � K= I= � p= n= = : : �1� K �= �= � /8 T1Q �3 : 9 T x4 �9 � �: T L1 >E � � {-� PE �= �= � [E g> ]> hE �> �> uE h? ^? �E �E � � � w- � � �? �? � @ @ � ,@ *@ �F d �F U@ Q@ �F @ �F �@ �@ -�F " �F �@ �@ �G � � �G �@ �@ � P8 U| �F � � �F >E � ` m-PE A A ` [E hE uE �E �E (�E ` �E {A yA �E �A �A ; � � y-� ; �A �A � *; TB RB 5; �B wB s � � �1 � � � �B �B C; k �1� U; C C b; VC PC � o o �1 - � �C �C � �C �C � �C �C = b b �1v K D D u �/ U} � /8 � T1Q �3 b 9 T x4 .� � U| � �9 �: T L1 >E � P {- PE >D 8D P [E �D �D hE �D �D uE E E �E �E � � � w- � � ?E =E � gE eE � �E �E �F � �F �E �E �F � � �F �E �E -�F � �F 1F /F �G # B �G VF TF + P8 U} �F F i �F {F yF f ,C U} = . . |- K �F �F A �/ U} = � � |- K �F �F � �/ U| � �/ U| x y _m � G G X y �f 9G 7G x � @ a� � ^G \G X � � �f �G �G x � p c! � �G �G X � � �f �G �G C �9 !� � �2 p� �G �G � q �H �H = � K 4I (I � �/ �/ �/ !� O �2 z� �I �I � { TJ JJ = � K �J �J I �/ ! �/ 5 �/ � , � w /� RK <K V� jL TL I� _M KM <� � c� aN -N p� �P oP }� ]R GR �� �S HS �� OV AV �� RW *W �� �X �X �� �Y �Y � ![ [ � �\ �\ � '� � �D , �� �D ^ ^ �D Y^ G^ �D 8_ &_ E ` �_ 1 �7 Uv � = = � �` �` a a � Aa ;a $ �a �a L �7 T| = W 0 �F K �a �a � �/ U| X r ` �o f b �a �� � "�� �� � � �� 'b #b = � @ � K ab ]b B �/ U| � �7 T��Q ���������R0 s � � � K � � �b �b = � � �� K �b �b � �/ X � � � f �b �b � � /c c = � � � K d d . �/ U| � � n Nd >d = � � � K �d �d �/ Uv X � �� f 7e 5e �� � 0 �� �� \e Ze �� �e �e �� �e �e 0 ħ �e �e ѧ Lf Df ާ �f �f � � ##l Wg Sg = � � K �g �g � �/ U~ � �9 z3 U} Q~ R| X0 = / �� K �g �g m �/ U| X W W � f h h = W P �O K ,h &h � �/ U| = a � �� K yh uh � �/ U} �D l l �� �D �h �h �D �h �h �D ai Wi E �i �i t �7 Uv c � v ]j Sj = � @ � K �j �j � �/ ` U} � �/ Uv = � � �� K !k k � �/ Uv = � � �� K [k Wk � �/ U} � � R �k �k = 7 P � K �k �k c �/ U| �� 8 8 # �b� � 3l 1l � Xl Vl )� �l �l [ 9 T �1 Q �1 � 6� � Uv T~ � 8 � U1 K i� U} � �7 . Tv � �2 Z U| T} +�� 0+�� 0 � �K � U �> Tv Q6R �1 V �K � U �> Tv Q} R �1 � �K U �> T �Q7R �1 � �K 2 U �> Q9R �1 �K j U �> T �Q5R �1 M �K � U �> T �Q6R �1 � �K � U �> T �Q5R �1 � �K U �> T �Q4R �1 �� � P l� � �l �l � *m (m ڮ *m (m ͮ Pm Nm �� vm tm P � �m �m � �m �m % 9 T �4 Q 2 R �0 X3Y �0 Z �K U �> Tv Q1R �1 G 5 w ( 5 $ Z~7 �G � � �A- L ��A- "n �m 01 ��G p �o q � G eq aq f; �n �q �q p; �� �q �q z; �n cr Ur �; � G :s "s �; � G Ht 4t �& � G 0u u �; � G v v �; � ) �v �v ~! �n Mw ?w �+ � �w �w �% �n �x �x %�" &8H �M� &-F �� ! F � 4 �@* �� � `F � _y [y = � �F � K �y �y �� �/ U| = !� �F �Z K �y �y � �/ Uv = ,� G �� K z z آ �/ U| � �7 T��Q ���������R0 5� O� �@ �g) R� Mz Cz G� �z �z �@ ]� �{ �{ � O� O� S# W! � -| +| � U| S| � {| y| �� g� A X# �( �� �| �| �� } �| A ¹ Ϲ �} �} �� �� @A � �( �� ~ ~ �� b~ T~ @A ¹ Ϲ ܹ ף �A � R( �A � - % ܺ � B � �& � � � � �� � � B � � /� '� �= � �B j�% �= �� �� �= ̀ ǀ �= � �B 60�= � � �= X� R� � � � 80 S# � �� �� � � � | � ʁ ȁ � � � � � � � '� '� 80 �# � B� @� � j� h� � �� �� � 5� @C 90 $ � �� �� � 5� 5� | � ۂ ق � � � � )� '� � @� @� 90 e$ � N� L� � v� t� � �� �� :@ M� pC :0|% f@ �� Y@ � � L@ � � �@ M� M� Q #0�@ I� G� �@ p� l� A �� �� A Y� 0 %% A ф ̈́ A � � /�@ �� 0 �@ �@ A /,A �� 0 IA >A /� -� � �6 U} Tv � � � g �% � T� R� � |� z� � �� �� #� |� |� U hB� Dž Ņ 5� � � O� � � Z� a� _� �= �� �� S �= �� �� �= �� �� �� 7 U} s� � �C � C( �� ҆ Ά �� ҆ Ά �� ҆ Ά �� � � �C �� H� D� �� �� ~� κ �� �� @� �C �i' �� � = E� D � K 0� ,� j� �/ O� 0D ��' j� f� = T� `D � K �� �� w� �/ U} _� _� � ܈ ڈ = d� d� � K � �� s� �/ Uv ܣ �6 �� �� �D �� (� $� � f� ^� �D $� Ɖ ]� �6 �� �6 U| Q0R1 = �� �D \# �( K � �� Ţ �/ 5� �� �D Q#X) G� <� 8� R� y� u� �D ]� �� �: T ; }� �9 �� �� E ��) � �� �� � �� � E $� �� �� .�� �) U| �� �6 X ʡ ʡ �* f ԋ .� ϡ `E ��+ c� �� �� V� Q� K� K� Q� K� @� �� �� `E p� %� � }� ڡ �* ~� s� q� X ޡ ޡ A f �� �� .� Ф �E 7 V� �� �� c� �� �� K� 7� 3� @� u� o� �E p� � ڤ �E D �+ � ʎ Ď �� � � �E � n� h� = � �E " �+ K �� �� V� �/ U} � U6 Uv T} פ q6 U0 = F� PG �, K �� � �� �/ U} X M� M� 5, f ~� �G �, 1� +� = � �G � K ~� |� 3� �/ U| �� �G �, �� �� = �� �G � K ߐ ې H� �/ U| ~� �: - T �: �� �K U 8; R �1 6 j G 1. �> tG �G 3+ �z 01 �G && G L G q G f; G p; n z; G �; ) ~! n �+ �% n %�" �%-F � 4 e@* Z� �G `� p �2P �> �fG )� � c0 �8 � � �)� )� �� QH �@G Y� 3� � G � � 3+ �z &� � 01 � G �� q� 3 �"8 �� Z� 2 � ��~! �n w� a� �+ � y� c� �% �n �� �� q � G �� �� &�G �� &� �ȵ &% � � & � !a YC V/ �( ���8 �� !� � !pc 9 �$ �� � ɡ !0k �0 3i �� .� "� �� �� pk �%� �� �� � � � ڮ � � ͮ � � �� <� :� pk � j� h� � �� �� �� 9 T �4 Q H< R �0 X3Y �0 x � �d �)1 � ؤ ֤ X � � �f �� �� � � e � W8 U� .� � �� .� � �� إ ʥ |� �� �� o� e� O� b� Z� L� H� � � ;� ҩ �� .� � � � � f � !2 � �� �� � ث ֫ f � �� �� @�� @f � �4 � $� � � �� � ֯ ɯ �� @f 1� .� "� >� �� �� K� X� 'a� �� j� g z4 k� � ۬ �� �g 4 "�� ��~�� C� ?� �� h 3 �� {� y� x O� �h � '� �� �� X O� �h �f ŭ í Ʋ i� �h � � � � �� 8� 4� � � x� t� ز �� �� s i� i� � �3 � � � � �� _: �3 U��~T��~Q R��~X H< �� 1 U��~T��~Q R��~X H< (x� �h }� C� A� x c� 0i � %� h� f� X c� @i �f �� �� � 9 T �4 Q H< � /� pi � U� �� �� �� �� �� ;� � � �� �� �� |� �� � o� F� >� b� �� �� H� � �� .� Z� R� w� /� pi � ױ �� �� ʱ � � �� x� r� �� ɳ �� �� +� %� �� �� }� �� ݴ մ pi � A� 9� � �� �� �� ?� 3� � � �i V6 � ƶ Ķ "� � � /� )� #� X P� j ) 06 f w� u� �� �8 H6 U| �� �9 >� ѹ 0j ; ?8 s� �� �� f� � � Y� 8� 4� L� x� t� 0j "�� ��~"�� ��~�� `j 8 �� �� �� (�� �j "�� ��~�� �� � Ʋ C� �j � �7 � 0� ,� �� |� x� � �� �� � � � ز J� F� s C� C� � �7 � � �� �� n� _: �7 T��~Q R} X H< _� 1 T��~Q R} X H< �� 9 T �4 Q H< � f8 U| Ts Qv R0 4� 9 U| x <� �k ��8 � �� �� X <� <� �f Һ к x I� �k �� �� �� X I� I� �f � � >E �� l � IB PE I� ?� l [E һ » hE �� �� uE Z� J� �E �E � IJ IJ w- �9 � � � � 4� 2� � Y� W� �F �l : �F �� ~� �F �� �9 �F � ߾ -�F 8� �F � � �G � N: �G B� @� � P8 �F f� ! m: �F >E <� @l m-PE g� e� @l [E hE uE �E �E (�E @l �E �� �� �E � ݿ ; <� �l y-|< ; X� V� �l *; �� }� 5; � �� s g� g� �1 S; � � 7� 5� C; �� @m �1R< U; ^� Z� @m b; �� �� � �� �� �1 �; � � � � � � � 2� 0� = � � �1< K Y� W� ܽ /8 5< T1Q �3 � 9 T x4 _� �9 ~� �: T L1 >E {� pm {-�A PE �� |� pm [E )� � hE �� �� uE *� � �E �E � {� {� w- )= � �� �� � �� �� � �� �� �F n �= �F � � �F � j= �F S� Q� -�F � �F �� �� �G �� �= �G �� �� �� P8 U| �F ƻ �= �F >E �� @n m-PE �� �� @n [E hE uE �E �E (�E @n �E =� ;� �E f� `� ; �� �n y- @ ; �� �� �n *; � � 5; C� 9� s ϼ ϼ �1 �> � � �� �� C; K� o �1�? U; �� �� o b; � � � O� O� �1 W? � c� a� � �� �� � �� �� = B� B� �1�? K �� �� U� �/ U} |� /8 �? T1Q �3 B� 9 T x4 .ü �? U| �� �9 � �: T L1 >E ؼ 0o {-�A PE � �� 0o [E M� I� hE �� �� uE �� �� �E �E � ؼ ؼ w- �@ � � �� � )� '� � O� M� �F po 1A �F {� w� �F �� A �F �� �� -�F �� �F �� �� �G � lA �G � � � P8 U} �F &� �A �F =� ;� F� ,C U} = � � |- K b� `� !� �/ U} = �� �o |- K �� �� �� �/ /B U| �� �/ U| x Y� �o ��B � �� �� X Y� �o �f �� �� x j� p ��B � � � X j� j� �f E� C� x s� Pp �KC � j� h� X s� s� �f �� �� #� �9 !`{ �C �2 �� �� �� � �{ h� \� = � �{ � K �� �� ַ �/ � �/ � �/ !`z yD �2 � �� x� � �z � � = � { � K �� �� )� �/ � �/ � �/ G- � �p :O Y- � �� �- ,� � s- !� � f- �p �- #� �� �- [� 1� �- � � �- P� � �- � � �- � �� �- �� �� �- u� U� �- �� �� . {� [� . '. · �D � �r %�E �D �� �� �r �D � � �D �� �� E �� �� � �7 Uv � � � '3F �� �� �� �� � � �� $ P� L� ,� �7 T| = 7� s (pF K �� �� �� �/ U| X R� @s b�F f �� �� !. ps ;G "". �� �� �s gG �� �� = �� t � K #� � "� �/ U| ~� �7 T��Q ���������R0 s �� �� uG � � [� Y� = Ƴ `t ��G K �� ~� �� �/ X г �t ��G f �� �� Գ �t �6H �� �� = · �u � K �� �� � �/ U| Գ �u ��H � � = ׳ �v � K �� �� �� �/ Uv X �� �v 4�H f �� �� �� ȶ w 7�I �� � � �� F� B� �� ~� |� w ħ �� �� ѧ � � ާ y� k� � �� `w ##�I � � = �� �w � K S� O� �� �/ U~ Ͷ �9 � z3 U} Q~ R| X0 = � �w 9J K �� �� M� �/ U| X 7� 7� <<J f �� �� = 7� 0x >yJ K �� �� �� �/ U| = A� `x ?�J K ;� 7� |� �/ U} �D L� L� H&K �D s� q� �D �� �� �D #� � E �� �� T� �7 Uv C� �x ��K � � = �� y � K �� �� Ϻ �/ �K U} �� �/ Uv = � py L�K K �� �� Ը �/ Uv = �� �y NL K � � Ǹ �/ U} Ǹ �y �|L [� S� = � 0z � K �� �� C� �/ U| �� � � # b�L � �� �� � � � )� J� F� ;� 9 T �1 Q �1 �� - M Uv T~ �� 8 (M U1 +� i� @M U} o� �7 XM Tv �� �2 �M U| T} +�� 0+�� 0 · �K �M U h< Tv Q6R �1 6� �K �M U h< Tv Q} R �1 o� �K +N U h< T hQ7R �1 �� �K \N U h< Q9R �1 � �K �N U h< T :Q5R �1 -� �K �N U h< T JQ6R �1 �� �K O U h< T 2Q5R �1 �� �K U h< T %Q4R �1 �� ȵ 0| ��O � �� �� � �� �� ڮ �� �� ͮ � � �� 8� 6� 0| � f� d� � �� �� � 9 T �4 Q H< R �0 X3Y �0 :� �K U h< Tv Q1R �1 W ~G �P �E ~�� 01 ~�G q G f; � G ~! �n �+ � �% �n %�" �%-F � *� 2G @ 8 ��^ �E 2lG �� �� c0 48 �� �� 4)� �� �� QH 4@G u� Q� 01 9 G � � 3 ="8 � �� 2 > ��~! ?n � � �+ @ �� �� �% An Z� L� q B G � �� &�G l� &� h� &% j� & s� !P� �Z V/ N�^ ���8 O� h� `� !�� �Z �$ Z� � � !� &S 3i \� �� ~� �� � � ]%� �� �� � � � ڮ � � ͮ � � �� � � � � 3� 1� � [� W� 9 T �4 Q �1 R �0 X1Y �1 x �� T�S � �� �� X �f � � � ( � [ U� �� � �� �� � �� �� }� |� G� A� o� �� �� b� V J H� � � ;� � � .� � � � ( �� � !UT � j h � � � �� � � � @�� � � �V � $� � � �� � ֯ ɯ �� � 1� � � >� r p K� X� 'a� r j� �� �V k� � � �� P� gV "�� ���� � � �� � kU �� 5 3 x % 0� � '� Z X X % @� �f } Ʋ p� � � � � �� � � � � 2 . ز v n s � �U � � � � R _: /V U��~T Q~ R��X �1 A 1 U��~T Q~ R��X �1 (x� �� }� � � x � � � %� " X � � �f G E � 9 T �4 Q �1 � R � � U� p j �� p j ;� � � �� E ? |� � � o� � � b� : 4 H� � � .� � � w� R � � ױ N H ʱ � � �� �� 3 + �� � � �� � � �� G ? � � � � � �� � � � � p� �X � 0 . "� W S /� � � X � �� ) X f � � � �8 �X Uv � �9 >� ] � ; �Z s� f� T P Y� � � L� � � � "�� ��"�� ���� � cZ �� (�� @� "�� ���� ` \ Ʋ � �� � 9Z � � � �� � � � & " � t p ز � � s � � � �Y � � � � � _: Z T Q~ R} X �1 j 1 T Q~ R} X �1 9 T �4 Q �1 � f8 Uv Ts Q| R0 W 9 Uv x � 0� b� X � � �f < : !�� |[ �2 m� e _ � � n � � = � � � K � � � �/ !� �[ �2 w� � � x = � � � K �/ Uv �� � `� i�\ � R N � � � ڮ � � ͮ � � �� � � `� � � � � � 9 T �4 Q �1 R �0 X1Y �1 2P � � t �^ QP 4 0 DP r n � ^P � � kP 1 % xP � � �P > 4 �P � � '�P � '�P � s � p� � |] � � < : = � �� ��] K e a A �/ X � � ��] f �� ( ( # �`V^ � � � � � � )� � � K 9 T �1 Q �1 � 6� n^ Tv �K U �> QAR �1 � �K U �> Tv Q@R �1 w �^ 5 $�^ �7 MG '` �E M�� 7 N G W5 O G �8 Pn q Q G f; S G p; T G z; Un �; V G ~! Wn �+ X �% Yn %�" %�, �%-F �_ tmp �G �_ � �� ȏ �G �� � �� �� �G �� o ,G �` �E ,jG c0 .8 .)� QH .@G 3 6"8 q 7 G �8 C� �A �G <a �E ��� FK ��G �J � G �4 � G q � G f; � G p; � G ~! �n �+ � �% �n %�" %-F *�P |G � < �9r �E |dG A + c0 ~8 8 ( ~)� � � QH ~@G � � FK � G � � 3 �"8 v b 2 � ��~! �n � � �+ � K = �% �n � q � G � � &�G ��� &� �:� &% �P� & �P� ! H �k V/ ��^ ���8 �� ! � !�I Ck �$ �� �! �! !�P �c 3i �� �" �" �� � �P �%� �" �" � �" �" ڮ �" �" ͮ �" �" �� # # �P � 8# 6# � `# \# A� 9 T �4 Q �1 R �0 X1Y �1 x �� �J � d � �# �# X �� �� �f �# �# � Ȧ �J � U� �# �# �� �# �# �� �$ �$ |� R% F% o� �% �% b� �& �& H� 8' ,' ;� �' �' .� �( �( � Ȧ �K � !�d � �) �) � �) �) �K � �) �) @�� �K � �g � $� � � �� � ֯ ɯ �� �K 1� ** * >� �* �* K� X� 'a� r� j� �L [g k� �* �* �� PM �f "�� ���� ?+ ;+ �� �M �e �� w+ u+ x Z� 0N � '� �+ �+ X Z� @N �f �+ �+ Ʋ � pN � � �+ �+ �� 4, 0, � � t, p, ز �, �, s � � � f � � - - R� _: �f U��~T��~Q��R��X �1 �� 1 U��~T��~Q��R��X �1 (x� �N }� ?- =- x #� �N � %� d- b- X #� �N �f �- �- �� 9 T �4 Q �1 � �� O � U� �- �- �� �- �- ;� �- �- �� R. N. |� �. �. o� �. �. b� '/ #/ H� g/ c/ .� �/ �/ w� �� O � ױ �/ �/ ʱ 20 .0 �� ~0 z0 �� �0 �0 �� 1 1 �� G1 C1 �� �1 �1 O � �1 �1 � F2 @2 �� �2 �2 � � `O 7i � @3 >3 "� g3 c3 /� �3 �3 X �� �O ) i f �3 �3 � �8 )i Uv � �9 >� �� �� ; *k s� 4 4 f� D4 B4 Y� s4 q4 L� �4 �4 "�� ��"�� ���� �O k �� �4 �4 (�� P "�� ���� 5 5 Ʋ s� @P � �j � @5 <5 �� �5 �5 � �5 �5 � 6 6 ز Z6 V6 s s� s� � sj � � �6 �6 �� _: �j T��~Q��~R} X �1 �� 1 T��~Q��~R} X �1 ܫ 9 T �4 Q �1 3� f8 Uv Ts Q| R0 �� 9 Uv x ͨ �P �� �6 �6 X ͨ ͨ �f �6 �6 !PQ l �2 �� 7 7 x� �Q � [7 W7 = �� �� � K �7 �7 �� �/ Dͧ C �l �2 �� �7 �7 � �U � = � V � K � �/ Us �� :� Q �Ym � �7 �7 � 8 8 ڮ 8 8 ͮ 8 8 �� ?8 =8 Q � m8 k8 � �8 �8 x� 9 T �4 Q �1 R �0 X1Y �1 �` P� �Q � r �` �8 �8 �` �8 �8 �Q �` �9 �9 �` [: I: �` *; ; �` �; �; �` = �< a R> >> a @? ,? a <@ (@ )a '2a � X P� P� �Bn f A A ,K U� U� ��n >K ?A =A KK qA cA XK "B B eK �B �B _� �7 s k� k� ��n � � jC hC x |� �R �3o � �C �C X |� S �f �C �C = �� 0S �io K �C �C v� �/ X �� �� ��o f D D = �� pS ��o K :D 6D � �/ U} X § �S p f tD pD § �S fp �D �D = § @T � K �D �D �� �/ U} § pT �p :E 4E = § �T � K �E �E P� �/ U| n� �T q �E �E = n� U � K F F ٪ PU qq :F 8F = ٪ �U � K _F ]F �� �/ �� �9 �q U| Ts Q} M� �K �q U �; Tv QXR �; [� �5 �q U��~ ٪ �: T �; �� �K U �; Tv QTR �; �. �G Cs �E ��� + ��G < �8 �9 � G �4 � G q � G f; � G p; � G z; � G �; � ) �; �8 �& �n ~! �n �+ � �% �n %�" ]%-F c3s 4 �@* 4 4@* *c qG p� � ��� �E qaG �F �F c0 s8 �G G s)� qH CH QH s@G {J QJ + x G ML 5L 3 |"8 �M QM 2 } ��~! ~n +P P �+ �P �P �% �n �Q �Q q � G ?R 9R &�G ��� &� ��� &% ��� & ��� !@� �} V/ ��^ ���8 �� �R �R !�� D} �$ �� lS XS ! � �u 3i �� >T :T �� �� P� �%� vT tT � �T �T ڮ �T �T ͮ �T �T �� �T �T P� � �T �T � U U � 9 T �4 Q �1 R �0 X1Y �1 x C� Т �v � ]U [U X C� C� �f �U �U � X� � � U� �U �U �� �U �U �� ]V OV |� ?W 1W o� �W �W b� �X �X H� gY YY ;� #Z Z .� :[ $[ � X� � � !�v � #\ !\ � K\ I\ � � p\ n\ @�� 0� � �y � $� � � �� � ֯ ɯ �� 0� 1� �\ �\ >� +] )] K� X� 'a� b� j� � by k� V] N] �� �� y "�� ���� �] �] �� � �w �� �] �] x %� p� � '� ^ ^ X %� �� �f 8^ 6^ Ʋ � �� � � _^ [^ �� �^ �^ � � �^ �^ ز /_ '_ s � � � �x � � �_ �_ B� _: �x U��~T��~Q��R��X �1 �� 1 U��~T��~Q��R��X �1 (x� � }� �_ �_ x �� � � %� �_ �_ X �� 0� �f ` �_ �� 9 T �4 Q �1 � <� `� � U� )` #` �� )` #` ;� }` u` �� �` �` |� ha ba o� �a �a b� b b H� sb mb .� �b �b w� <� `� � ױ /c )c ʱ �c {c �� �c �c �� <d 4d �� �d �d �� �d �d �� Pe He `� � �e �e � "f f �� �f �f � � �� >{ � 9g 7g "� `g \g /� �g �g X h� � ) { f �g �g �� �8 0{ Uv �� �9 >� �� � ; +} s� h h f� ]h Yh Y� �h �h L� �h �h � "�� ��"�� ���� P� } �� %i !i (�� �� "�� ���� ii ei Ʋ +� � � �| � �i �i �� �i �i � /j +j � }j yj ز �j �j s +� +� � s| � � �j �j Z� _: �| T��~Q��~R} X �1 �� 1 T��~Q��~R} X �1 �� 9 T �4 Q �1 �� f8 Uv Ts Q| R0 A� 9 Uv x �� �� �� k k X �� �� �f Ek Ck !� ~ �2 �� nk hk � 0� � �k �k = �� �� � K �k �k �� �/ D�� @ �~ �2 �� l l �� � � = �� P� � K �� �/ Us �� �� �� �Z � Dl @l � |l zl ڮ |l zl ͮ |l zl �� �l �l �� � �l �l � �l �l � 9 T �4 Q �1 R �0 X1Y �1 9r �� `� � g� Xr *m "m Kr �m �m `� er Yn In rr o o r kp Yp �r @q *q �r �r *r �r Xv 6v �r �w �w �r 0z z �r �{ �{ �r �{ �{ �r e} ?} �r �~ s ր �� s s X �� �� �p� f k� i� s Ь Ą "%s �� � � �� �r� U� �� �� H� �� �� ;� �� ~� .� �� � �� b� `� R� t@ � `� = � �@ �@ � �� �@ :� 6� `� �@ t� p� �@ 3� - �� �@ �� �� �@ � � -�@ @� �@ � � M,A �� 0 �� IA >A 1� /� /t@ �� 0 �@ �@ �@ �@ /,A �� 0% IA >A V� T� o� �� �� p� {� y� }� �� � V т �� �� �� � �� � ؆ �� D� >� �� �� �� � `� `� ' � �� �� � � ߇ � � � :�� U} T��Q ���������R0 � �� � 5 K� ;� ;� H� /� +� U� {� w� .� �� �� � b� ö �� � > � � � ն � � � � P� N� �� y� s� � Ɖ r �� P� � ك � �� �� �� �5 �� U @9 .� � Uv Ts � �5 � �9 � �: T `9 $� �5 U} T��Q1R0 = �� �� �K )� !� :� �/ �� U} .� �/ U} X �� � �� f �� �� �A �� � �� �A �� �� � �A p� b� �A !� � �A ˌ �� B B � �� �� �. �� � i� g� � �� �� � �� �� LC � �� QC ߍ ۍ �C m� ۅ �C � � -^C �� cC W� U� 'D �� :� ,D |� z� �� P8 Uv *C <� $ Y� /C (B `� B �� �� -B �� � ; � � �.S� ; o� i� � *; �� �� 5; �� �� s 2� 2� �1 �� � � ]� [� �� �9 �� �: )� T L1 .&� =� Uv �� C; U~ �A B� p� �.�� �A �� �� p� �A �� �� �A T� N� �A �� �� B B � B� B� �. � � � � � � � � B� @� LC � e� QC k� g� �C �� A� �C �� �� -^C �� cC � � 'D i� �� ,D � � q� P8 U~ *C �� �� /C (B �� B -� +� -B X� P� ; �� 0� �.�� ; �� �� 0� *; � � 5; 0� (� s �� �� �1 c� � � �� �� .�� w� U~ =� C; �� U �� �9 �� �: T L1 �A �� �� �.t� �A �� �� �� �A � � �A \� V� �A �� �� B B � �� �� �. f� � �� �� � $� "� � I� G� LC в ˊ QC r� n� �C �� �� �C �� �� -^C � cC � � 'D � � ,D � � � P8 U *C `� -� /C 4� 2� (B � B [� W� -B �� �� ; z� @� �. � ; � � @� *; 5� 1� 5; u� o� s �� �� �1 ы � � �� �� .�� � U +� C; E� �9 `� �: T L1 = �� �� �. [� K � � �� �/ U��~ �� �A U��~ = � � �. K "� � 0� �/ U = t� �� �. K K� E� �� �/ �� U~ W� �/ U~ = �� � �M� K �� �� � �/ Uv UA � � ��� gA Й Ι tA � � �A � Қ �A �� �� � �7 U} 2 '� '� �3� ^ �� ~� Q �� �� D �� � j G� C� 2� �8 U| Tv = =� 0� �p� K �� }� h� �/ Uv UA R� R� � gA �� �� tA � ܝ �A �� v� �A � � Z� �7 U} �� f� `� �� � �� �� � G� A� `� � �� �� � f� �� �" � * �� � >� 8� �� �� X }� }� ��� f á �� � �� � �� � � � � * 2� 0� �� �9 q� �8 U| Tv � �� �� �" X� � \� Z� � �� �� � �� �� ,� � � -� آ Ң = `� `� �"�� K #� !� r� �/ U~ B� s7 Ґ U1 `� 7 T~ �� 7 Tv = �� P� :� K J� F� �� �/ Uv X �� �� g� f �� �� dՑ �� �� = �� �� � K � � � �/ Uv �� � e7� � � = �� � � K c� ]� G� �/ U| X L� L� /l� f �� �� UA Q� Q� 0ܒ gA ֤ Ԥ tA � �� �A �� �� �A 3� '� Y� �7 U} 3s � �� "4s �� �� �� 6T� �� �� = �� ж � K �� �� v� �/ U| = �� � 7�� K 3� /� i� �/ U} �� �7 T��Q ���������R0 s �� �� ; �� � � k� i� X �� �� I*� f �� �� X �� �� LW� f .� @� `Ŕ �� �� = v� v� � K 2� 0� �� �/ U~ 0� �� ^3� W� U� = 0� 0� � K |� z� C� �/ Uv �� � � ;P�� � �� �� � ƨ Ĩ � )� �� � 1� 9 T �1 Q �1 �� p: �� U2 �� p: ҕ U2 \� �K � U P= T R �; �� �9 0� �: 0� T (= �� �K U P= T GQRR �; -� �K U P= Tv QHR �; � G n ɖ �E G�� q Hn *�4 0 n �p � ��� �E 0[G 9� -� c0 0sG ͩ �� QH 0�G d� X� 1 � �� � c3 2"8 q 3n T� R� �8 =� |� x� �� �p �p @ �� �� �� �� �� ٫ �� q q 5 <$�� � � �� � :� 8� ڮ :� 8� ͮ `� ^� �� �� �� � �� �� � ڬ ج =q 9 T �4 Q �0 R �0 X0Y �0 \q �8 �� U�` �q �� U �0 T�` \, �G @� �E ��A- 01 ��G q G f; G ~! n �+ �% n %�" %-F *�/ �G � 8 �_� �E �mG � � c0 �8 � � �)� � Ϯ QH �@G ï �� 01 � G N� >� 3 �"8 � � 2 � ��~! �n <� .� �+ � � س �% �n �� �� q � G O� G� &�G �~� &� �z� &% ��� & ��� !0V �� V/ ��^ ���8 �� �� �� !pW 1� �$ �� $� � !�^ �� 3i �� ж ̶ �� �� �^ �%� � � � -� +� ڮ -� +� ͮ -� +� �� S� Q� �^ � �� � � �� �� �� 9 T �4 Q �1 R �0 X1Y �1 x � �X �� � � � X � � �f � � � � �X � U� C� 7� �� C� 7� �� ˸ |� �� �� o� � � b� �� �� H� D� 8� ;� � ػ .� � μ � � �Y � !� � �� �� � � �Y � � � @�� �Y � �� � $� � � �� � ֯ ɯ �� �Y 1� 6� *� >� �� �� K� X� 'a� R� j� �Z W� k� � � �� 0[ �� "�� ���� K� G� �� �[ �� �� �� �� x � \ � '� �� �� X � \ �f Ϳ ˿ Ʋ �� P\ � � � � �� @� <� � � �� |� ز � �� s �� �� � �� � � &� $� 2� _: �� U��~T Q~ R��X �1 !� 1 U��~T Q~ R��X �1 (x� �\ }� K� I� x b� �\ � %� p� n� X b� �\ �f �� �� y� 9 T �4 Q �1 � 2� ] � U� �� �� �� �� �� ;� � � �� �� �� |� �� �� o� &� � b� �� �� H� �� �� .� :� 2� w� 2� ] � ױ �� �� ʱ �� �� �� T� R� �� �� y� �� �� �� �� ;� 5� �� �� �� ] � �� �� � g� _� �� �� �� � � P] 3� � ~� |� "� �� �� /� �� �� X `� �] ) � f /� -� �� �8 %� Uv �� �9 >� =� �] ; � s� V� R� f� �� �� Y� �� �� L� 0� ,� �] "�� ��"�� ���� �] � �� j� f� (�� ^ "�� ���� �� �� Ʋ �� p^ � Ǣ � �� �� �� 4� 0� � t� p� � �� �� ز � �� s �� �� � h� � � >� <� Ͱ _: �� T Q~ R} X �1 J� 1 T Q~ R} X �1 �� 9 T �4 Q �1 n� f8 Uv Ts Q| R0 7� 9 Uv x �� _ �� e� c� X �� �� �f �� �� !�_ � �2 �� �� �� �� �_ � � �� = �� �� � K =� ;� �� �/ !�` �� �2 �� d� `� ӭ �` � = ӭ ӭ � K � �/ Uv �� z� @_ �G� � �� �� � �� �� ڮ �� �� ͮ �� �� �� �� �� @_ � ,� *� � R� P� �� 9 T �4 Q �1 R �0 X1Y �1 �� �� �_ � +� ߘ �� ~� Ҙ �� �� �_ � � �� �� � s� � � � � �� �� � � � '-� ٯ '6� ӭ s �� P` � � � �� �� = ĭ �` @� K �� �� !� �/ X έ έ m� f �� � � # `� � �� �� � � � )� B� >� +� 9 T �1 Q �1 �� - �� Tv � �K U < QAR �1 ݬ �K U < Tv Q@R �1 � �G �� �E ��A- 7 � G W5 � G �8 �n q � G f; � G p; �n z; � G �; � G ~! �n �+ � �% �n %�" �%�, 3%-F �;� tmp G o� � F� �� FG �� � t� �� tG �� c �G � �E �kG c0 �8 �)� QH �@G 3 �"8 q � G �8 �� u G �� �E �A- FK �G w G T. n �4 G �+ G q G f; G p; G z; n �; �; G ~! n �+ �% n %�" �%-F � *� � G � � �:� �E � eG �� y� c0 � 8 �� �� � )� n� D� QH � @G P� (� FK � G � �� 3 � "8 � �� 2 � ��~! � n �� y� �+ � d� R� �% � n R� @� q � G #� � &�G � &� � M &% � G & � G &�" � � &-F � %�> !� i� V/ � �^ ���8 � � �� �� !� � �$ � � �� y� !P" �� 3i � � �� �� �� � �" � %� � � � 7� 5� ڮ 7� 5� ͮ 7� 5� �� ]� [� �" � �� �� � �� �� � 9 T �4 Q �1 R �0 X1Y �1 x � � � � � �� �� X � � �f � � � � � U� O� A� �� O� A� �� �� �� |� �� �� o� �� �� b� �� �� H� `� R� ;� "� � .� �� w� � � � !ĭ � ^� \� � �� �� � �� �� @�� P � b� � $� � � �� � ֯ ɯ �� P 1� �� �� >� f� d� K� X� 'a� � j� 8� k� �� �� �� � ֯ "�� ���� �� �� �� @ ڮ �� )� '� x � � � '� N� L� X � � �f s� q� Ʋ � � � � �� �� �� �� �� � � &� "� ز j� b� s � � � d� � � �� �� � _: �� U��~T~ Qv R��X �1 �! 1 U��~T~ Qv R��X �1 (x� }� �� �� x N ` � %� � � X N p �f ;� 9� 9 T �4 Q �1 � � � � U� d� ^� �� d� ^� ;� �� �� �� u� o� |� �� �� o� 4� (� b� �� �� H� � � .� t� l� w� � � � ױ �� �� ʱ (� "� �� �� �� �� �� �� �� u� o� �� �� �� �� '� � � � �� �� � �� �� �� � �� � � � � � P� N� "� x� t� /� �� �� X ! ) � f � � @ �8 � Uv J �9 >� �" P! ; �� s� )� %� f� w� q� Y� � � L� $� � P! "�� ��"�� ���� �! ҳ �� ^� Z� (�� �! "�� ���� �� �� Ʋ [# " � �� � � � �� )� %� � i� e� � �� �� ز �� �� s [# [# � I� � � 5� 3� �# _: z� T~ Q R} X �1 $ 1 T~ Q R} X �1 �# 9 T �4 Q �1 (# f8 Uv Ts Q| R0 � 9 Uv x = �" � � \� Z� X = = �f �� � ! # � �2 � � �� �� � `# � �� �� = � K 4� 2� $ �/ !`5 P� �2 � Y� W� � `5 = � � � K ! 5 ɵ �2 � �� }� � 5 = � � � K � �/ Uv �� M �" � �� � �� �� � � � ڮ � � ͮ � � �� 2� 0� �" � `� ^� � �� �� � 9 T �4 Q �1 R �0 X1Y �1 s G �# � �� � � �� �� � g �# � V� -� � � � ;� � �# :� � �� G� ` X T� � � a� � l n� � � {� � �� ' � �� � � "�� ���� ! � �� � � ɩ � � ֩ � � � '� � X g g &� f � � �� � & 6�� �� � � �� �� � � �� n d & � � � � � - �� � 1 / � W U ڸ � ܸ ۸ } { X � � / f � � � �! `& 2 |� � � � �� `& � T N = �! �& " `� K � � �# �/ Us �! U6 U Ts �! q6 U1 = � �& 8ι K � � � �/ U s � � 9 � � � �� � ' H�� � < 6 խ � � ʭ � � ' � B 8 X d!�� f � � � �8 �� U| T} i" �9 H P' J�� &H � � P' 1H � � >H � � KH P @ XH 'aH � � y, s� � � * ( � O M �I @( ػ �I | t �I � �� �I � � -�I " �I ~J �( ;� �J . * �J � &� �J f d � �9 I P8 Us �I �( N� �I H � � o,�� &H � � 1H >H KH XH 'aH � � �: T �: (rH �' wH � � �H � � ; $ �( {,�� ; � � �( *; � � 5; #! ! s N$ N$ �1 c� � � �! �! .B$ w� Us �$ C; �� U �& �9 �& �: T L1 H [$ 0) },3� &H �! �! 0) 1H =" 3" >H �" �" KH ># 4# XH 'aH % � [$ [$ y, n� � �# �# � �# �# � $ $ �I �) Ӿ �I /$ '$ �I �$ �� �I �$ �$ -�I 5% $ �I �$ �$ ~J * 6� �J �$ �$ �J �& !� �J % % �& �9 �$ P8 U �I @* I� �I H % % o,�� &H ?% =% 1H >H KH XH 'aH % % �: T �: (rH p* wH d% b% �H �% �% ; �% �* {,�� ; f& `& �* *; �& �& 5; �& �& s �% �% �1 ^� � � ;' 9' .�% r� U F& C; X& �9 w& �: T L1 H �% + },�� &H n' ^' + 1H $( ( >H b( ^( KH �( �( XH 'aH ' � �% �% y, ^� � �( �( � ) �( � %) #) �I P+ � �I V) J) �I )' ! �� �I �) �) -�I �' , �I * * ~J �+ � �J >* :* �J �+ � �J x* t* +( �9 & P8 U��~ H ' �& - o,�� &H �* �* �+ 1H >H KH XH 'aH ' ' �: T �: �I J' , �� �I (rH , wH �* �* �H .+ (+ ; v' @, {,�� ; + y+ @, *; �+ �+ 5; , , s �' �' �1 V� � � q, o, .�' l� U��~ K( C; h( �9 �( �: T L1 = �' �, ~, �� K �, �, �' �/ �' H U��~ = '& '& ~, K �, �, 9& �/ = �$ �, ~, K �, �, �$ �/ o� U 0% �/ �� U �% �/ U = t - K�� K - - � �/ Us �D � � UL� �D T- R- �D �- �- �D �. �. E �/ �/ � �7 U = � �- \�� K �0 �0 � �/ Us �� � �- e�� �� �0 �0 x � . |! � 1 1 X � p. �f 01 .1 )� � �. g�� H� [1 S1 U� �1 �1 b� /2 '2 ;� �2 �2 �. "o� ��|� �2 �2 �� �3 �3 �� �4 �4 �� "5 5 �� d5 X5 �� �5 �5 ʫ `6 \6 �6 �6 � w7 c7 � m8 Y8 �� Y9 E9 � / � � 3: 1: � z p/ f" �� X� \: V: K� �: �: >� ; �: 1� g; a; $� �; �; p/ e� �; �; r� C< =< � �< �< �� x= v= � �4 �� T � t� T Q��~ S! �5 N� # �/ l�� m� �= �= �� K> E> z� �> �> `� ? ? �/ �� �? �? �� �� �@ �@ �� ƪ @A :A Ӫ �A �A '� 9 '� O � `0 ?� � B B � NB FB � �B �B � �B �B � l4 �� Us T~ R0X} � (� U~ ��~��$��~"Q } ��~��$ F �4 U��~ = O �0 �"|� K :C 6C E �/ Us 5 �4 �� U��~T �� �4 �� U��~ O �: �� T �? o �4 U��~T �� Y �0 �q� |C pC = Y `1 � K D D �! �/ [� U " �/ U~ _! �1 ��� `D PD = h @2 � K E E �# �/ �� U} �& �/ U � �2 �M� �E �E = � `3 � K VF RF � �/ U} � �3 ��� �F �F = � �3 � K �F �F 4 �/ U| � 4 �� G G = � @4 � K >G :G � �/ Us �� � � # 9N�� � vG tG � �G �G )� �G �G � 9 T �1 Q �1 = ! p4 o�� K H H ! �/ U = ! �4 p� K +H 'H I! �/ U~ X 5! �4 �+� f cH aH � �5 H� Uv Q1 � �9 l� U| T} Qs � �K �� U P? Q=R �; �K �� U P? T 9Q9R �; � �9 � 9 � T �? Q <2 � �K B� U P? Q9R �; -! �9 f� U| Tv Qs �! �K �� U P? T 6Q9R �; ?" 9 �� T �? Q B2 _" �K �� U P? R �; �" �K #� U P? R �; �& �K U P? T��~�R �; 7� Y 05 � � V� c� �H �H p� �H �H I� �H �H 05 }� �� I I �� >I <I �� kI iI � 9 T ? Q 82 Y �1 � �K U P? Tv Q4R �; �: � G `� �> � iG �9 � G q � G f; � n p; � G z; � G �; � G �; � G �& � ) ~! � n �+ � �% � n %-F � %�" � .� � s � �� s G �� P� �+ } G tmp � G 4 � @* *� � G �� � � � �> � [G �I �I c0 � 8 cJ SJ � )� ;K K QH � @G �L �L �9 � G XN @N 3 � "8 �O ]O 2 � ��~! � n �Q �Q �+ � QR CR �% � n S S q � G �S �S &�G � ~� &� � '� &% � @� & � @� !�� �� V/ � �^ ���8 � � 'T T ! � Y� �$ � � �T �T !`� �� 3i � � xU tU �� � �� � %� �U �U � �U �U ڮ �U �U ͮ �U �U �� �U �U �� � )V 'V � QV MV C� 9 T �4 Q �1 R �0 X1Y �1 x �� � � .� � �V �V X �� �� �f �V �V � �� @� � U� �V �V �� �V �V �� W sW |� CX 7X o� �X �X b� �Y }Y H� )Z Z ;� �Z �Z .� �[ �[ � �� @� � !� � m\ k\ � �\ �\ @� � �\ �\ @�� p� � �� � $� � � �� � ֯ ɯ �� p� 1� �\ �\ >� u] s] K� X� 'a� R� j� 0� {� k� �] �] �� �� � "�� ���� ^ �] �� P� � �� 8^ 6^ x O� �� � '� ]^ [^ X O� �� �f �^ �^ Ʋ � �� � � �^ �^ �� �^ �^ � � 5_ 1_ ز y_ q_ s � � � �� � � �_ �_ 6� _: �� U��~T��Q R��X �1 i� 1 U��~T��Q R��X �1 (x� � }� ` �_ x � `� � %� %` #` X � p� �f J` H` y� 9 T �4 Q �1 � �� �� � U� s` m` �� s` m` ;� �` �` �� Ha Ba |� �a �a o� b �a b� eb _b H� �b �b .� c c w� �� �� � ױ yc sc ʱ �c �c �� 5d /d �� �d ~d �� �d �d �� @e :e �� �e �e �� � �e �e � lf df �� �f �f � � �� W� � �g �g "� �g �g /� �g �g X �� 0� ) 1� f 4h 2h � �8 I� Us 1� �9 >� �� `� ; @� s� [h Wh f� �h �h Y� �h �h L� 5i 1i `� "�� ��"�� ���� �� � �� oi ki (�� �� "�� ���� �i �i Ʋ � � � �� � �i �i �� 9j 5j � yj uj � �j �j ز k k s � � � �� � � Ck Ak F� _: �� T��~Q R} X �1 *� 1 T��~Q R} X �1 �� 9 T �4 Q �1 �� f8 Us Tv Q| R0 �� 9 Us x �� �� � � jk hk X �� �� �f �k �k !0� 2� �2 � � �k �k e� p� � l l = �� �� � K Bl @l �� �/ !�� �� �2 � � il el �� �� � �l �l = �� �� � K �l �l �� �/ U} �� '� �� � � � �l �l � +m )m ڮ +m )m ͮ +m )m �� Qm Om �� � m }m � �m �m e� 9 T �4 Q �1 R �0 X1Y �1 :� @� �� � �� L� �m �m Y� �n �n �� f� "o o s� )p p �� �q �q �� Hs 2s �� Rt 2t �� �u �u �� #w w �� �w �w �� lx Zx �� Jy 8y �� �� � M� M� % �� � z z � :z 8z � `z ^z & c� � M � 8 �z �z � E �z �z R _ ({ { l L| <| y } �| � �} �} � �~ �~ � � � � c� c� � r� � 7 5 � _ ] � � � � j� j� � �� � � � � � � � � � � �� � � �� �� � � H� � � ;� K� I� .� y� w� �� U� �� �� x �� � |� � ր X �� �� �f �� �� � � � ��� ;� "� � H� P� N� .� ~� |� U� � 6 � i� U| �� 6 T| >� i� �� P� � w� �� �� = �� �� � K ߁ ہ e� �/ Uv = �� � � �� K � � � �/ Uv �� #4 �� U} Tv �� �K U �= T| Q>R �; X �� 0� Z (� f X �� �� 9 U� f �� `� �� � �� �� s �� H� Q� O� ;� � }� .� �� �� �� U� Ԃ Ђ x � �� � � � � X � � �f 1� /� � �� �� ��� ;� V� T� H� �� �� .� �� �� U� � 6 � i� Uv �� 6 Tv �� i� �� #� � u � � ك Ճ � � � � $� d� ^� .8� � U~ E� �6 = N� `� w P� K �� �� X� �/ U~ x� �� � �� � � = x� � � K � � �� �/ U~ s W� W� z �� � � 5� 3� P� P� �� "Q� �� �� �� � d� \� X� = �� � � K �� �� �� �/ U = �� 0� � �� K �� �� K� �/ U| �� �< �� Uv T��Q ���������+U� 0 �� �< U| T��Q2+U� 0 = �� �� � 3� K � � X m� m� h� f � � .� `� =� 3� @� <� X r� r� ~ �� f x� v� X v� v� �� f �� �� (@� �� A� Ć �� = {� �� � K �� �� U� �/ Uv �� 8 T� U1 �� h� l� U} �� �2 �� U~ T0+�� 0+�� 0 � �K �� U �= Tv R �; �� �9 �� �K U �= Tv Q(R �; h9 � G �� �> � gG �9 � }G q � G f; � n p; � n z; � G �; � G �; � G �& � G �; � ) ~! � n �+ � �% � n %-F � %8H %�" � %� : � � 5 � X� 5 G P� T� � ` � H� ` G @� v� �+ j G tmp m G 4 r @* *M( ~ G `� c �h� �> ~ ZG D� 4� c0 � 8 � �� � )� � �� QH � @G J� $� �9 � G �� ی 3 � "8 F� � 2 � ��~! � n ^� P� �+ � � �� �% � n ʒ �� q � G q� i� &�G � F� &� � �� &% � �� & � �� ! � �� V/ � �^ ���8 � � � Г !�� � �$ � � �� �� !�� �� 3i � � Y� U� �� �� � � %� �� �� � �� �� ڮ �� �� ͮ �� �� �� ܕ ڕ � � � � � 2� .� �� 9 T �4 Q 2 R �0 X1Y �1 x 3� �� � T� � x� v� X 3� 3� �f �� �� � H� �� � U� Ζ �� �� Ζ �� �� x� j� |� Z� L� o� � � b� ʙ �� H� �� t� ;� >� ,� .� Q� ?� � H� �� � !)� � � � � 6� 4� �� � [� Y� @�� � � �� � $� � � �� � ֯ ɯ �� � 1� �� �� >� � � K� X� 'a� � j� �� �� k� A� 9� �� `� ?� "�� ���� �� �� �� �� ?� �� ٞ מ x �� @� � '� �� �� X �� P� �f #� !� Ʋ �� �� � � J� F� �� �� �� � � ֟ ҟ ز � � s �� �� � �� � � |� z� �� _: � U��~T��Q R��X 2 >� 1 U��~T��Q R��X 2 (x� �� }� �� �� x �� �� � %� Ơ Ġ X �� � �f � � A� 9 T �4 Q 2 � �� 0� � U� � � �� � � ;� h� `� �� � � |� S� M� o� �� �� b� � � H� ^� X� .� �� �� w� �� 0� � ױ � � ʱ l� f� �� ֤ Ф �� '� � �� �� �� �� � ۥ �� ;� 3� 0� � �� �� � � � �� �� �� � � �� }� � $� "� "� K� G� /� �� �� X �� �� ) W� f ը Ө �� �8 o� Us �� �9 >� � �� ; f� s� �� �� f� H� D� Y� �� �� L� ֩ ҩ �� "�� ��"�� ���� � ?� �� � � (�� P� "�� ���� T� P� Ʋ ;� �� � � � �� �� �� ڪ ֪ � � � � h� d� ز �� �� s ;� ;� � �� � � � � f� _: �� T��~Q R} X 2 � 1 T��~Q R} X 2 �� 9 T �4 Q 2 � f8 Us Tv Q| R0 �� 9 Us x u� @� � � � � X u� u� �f 0� .� !�� X� �2 � � Y� S� �� �� � �� �� = O� O� � K � � ^� �/ !�� �� �2 � � � � }� �� � D� B� = }� }� � K k� i� �� �/ Uv �� �� p� � �� � �� �� � ̭ ʭ ڮ ̭ ʭ ͮ ̭ ʭ �� � � p� � � � � F� D� �� 9 T �4 Q 2 R �0 X1Y �1 � �� � � 4� � �� r� ,� L� B� � 9� ۯ ů F� ۰ Ű S� � �� `� �� i� m� �� �� z� ɶ �� �� 4� � �� �� }� �� �� � �� � �� �� ?� '� �� �� �� '�� W� � �� �� � � � E� C� � m� k� � �� �� � �� �� (� � �� �� � � � � � � �� �� / w� � +� )� � S� Q� � y� w� �� �� � � T� �� 5 �� H� �� �� ;� ̾ ʾ .� �� �� �� U� !� � x -� � 2� � Y� W� X -� -� �f ~� |� � �� �� ��� ;� �� �� H� ѿ Ͽ .� �� �� U� �� 6 �� i� U| a� 6 T| �� i� � P� � � &� "� = � �� � K _� ]� = J� �� 8 V� K �� �� � �/ U~ X q� � G w� f � P� � � o� �� ` �� H� �� �� ;� � � .� � � �� U� A� =� x �� �� 2� � y� w� X �� �� �f �� �� � �� �� ��� ;� � �� H� � � .� � � U� �� 6 �� i� U| |� 6 T| 9� i� �� �� � b 5� � F� B� � �� |� � $� �� �� .�� &� U~ `� �6 = �� P� d r� K � � � �/ U~ `� �� � � X� V� = `� �� � K }� {� {� �/ U~ s �� �� g � � � �� �� v� @� � "w� �� 3� �� t �� �� �� = H� �� � K � � V� �/ U = 3� � u � K )� %� �� �/ U} 0� �< �� U| T��Q ���������+U� 0 A� �< U} T��Q2+U� 0 = i� i� z U� K a� _� X �� �� �� f X � � � �� f �� �� T� P� �� Y� �� �� X � � k � f �� �� X � � l ;� f � � (f� �� g� 1� -� = � �� m K k� g� �� �/ U| <� #4 �� Uv T~ i� 8 �� U1 �� �K � U > T} R �; i� �2 � U~ T0+�� 0+�� 0 �� h� Uv � �K U > Tv QLR �; *6@ � n p� ` �& �9 � YG �� �� � � G �� �� � � n �� �� q � n �� �� f; � n 5� #� p; � G � �� z; � n f� \� �; � G � � �; � G �� �� �& � G 6� � �; � ) `� X� ~! � n �� �� �+ � x� j� �% � n *� � %�" ` &-F g �� !p� I � � x� G p� � �� �� ; H� �� �� ;� �� �� .� &� $� �� U� M� I� x �� � � � �� �� X �� �� �f �� �� � *� *� �% ;� �� �� H� �� �� .� +� )� U� /� 6 7� i� U} � 6 T} m� i� !P� & �+ ( G P� N� !�� � 3tmp + G u� s� = �� �� + K �� �� �� �/ U} X z� z� ) � f �� �� X ~� ~� * f �� �� !@� < 4 0 @* �� j� �� 2 � � � = �� � � K Y� W� �� �/ U = j� � 3 � K �� |� �� �/ U~ g� �< U} T��Q ���������+U� 0 �� �< U~ T��Q2+U� 0 p; p� �� � � �; �� �� �� �; � � �� U4 j� �� �� � G �� O� I� �� O� I� �� O� I� �� �� �� |� � �� s �� �� M � � �� �� � P� � � � � �� C� =� � �� � "� V� �� �� � q6 � U0 :� Uv T| :� Uv T0 � b� �� w S � �� �� �� � � �� � 3� -� = "� �� " 7 K �� |� �� �/ U| r� U6 Uv T| �� � � �� �� �� x .� P� P � �� �� X .� .� �f � � ʷ �� 3 Ϸ (� &� -ڷ G� ۷ N� L� X K� K� W f s� q� _� q6 U0 & 1� �� _ 8 �� �� �� E � � R _ ]� K� l h� X� y #� � � �� �� � �� �� � � � � 1� P� � � '� %� � O� M� P� � u� s� � �� s � O� л � e H� �� �� ;� �� �� .� �� �� л U� "� � x j� � � � Z� X� X j� j� �f � }� � �� �� �O ;� �� �� H� �� �� .� � �� U� �� 6 �� i� U} [� 6 T} �� i� �� @� � � '� #� = �� �� � K a� ]� �� �/ U| = �� � � K �� �� �� �/ U| z� #4 0 Uv T| #� �K U �= Q>R �; �� � h � �� �� = �� �� � K 9� 7� �� �/ Uv �� �� 0� 7 � `� \� � �� �� 0� $� �� �� .� ( U| Y� �6 = � p� " t K :� 6� �� �/ U| �� �� c � r� p� = �� � � K �� �� �� �/ U| s '� '� % � � �� �� = �� �� 8 E K �� �� �� �K } U �= T � QCR �; �� �K � U �= T � QDR �; �� �2 � U| T0+�� 0+�� 0 �� �K U �= T} Q~ R �; (� �9 ]B � n � �+ � _G q � n f; � n p; � n z; � G ~! � n �+ � �% � n %� � %�" � %-F � � � � h� � G `� �; �n 2 ^ �@G seq �PG eq �Yn { � n �< �n x ^ �<G `5 �LG eq �Vn { � n � � G � obj �7G �1 {n � i {:� n2 {H� dD1 % n % �"G � ` �J �5 �G �A �n 8 `5 �<G key �LG { �\q � !G r `5 CG ` SG res G �? � G � P) �IG eL <� � fn <) K {n � op {+G z# mn � m!� & m55 �% o5 8�! �" op �*G 8�L �= op �*G 8l �X op �G 8% �s op �)G e�: n � fob /� �� G� � ,�� l � �� � � �� \� V� �� �� �� �� -� l � �� �� ,�� 0l # �T �� :� 4� (�� �� �� �� ,�� `l �� S US΄ Tۄ �� �� X dl dl A'f �� �� ,�� �n �( � � � � |� t� $� �� �� R�n U�UT�T H�n �6 ,C; �o | �X U; (� � b; �� �� � �o �o �1 � � � � � 9� 7� � ^� \� = p p �1� K �� �� M= p �1 K (p �/ Uv �o /8 < T1Q �3 p 9 T x4 ,Gs u � �� Ys �� �� ds `� T� qs �� �� �s &u � �s ~� |� �s <u � �s �� �� �s Ru �s �� �� Gs _u p -) qs �� �� ds C� =� Ys �� �� �s hu � t �� �� amu v T| t zu � t �� �� :u T| !t �u � &t � � :�u T| 4t �u , 9t =� ;� :�u T| Gt �u c Lt b� `� :�u T| Zt �u � _t �� �� :�u T| (mt � "nt P��u �TT�Q ,؊ <I B �� � �� �� �� �� �� � k� c� � �� �� � <I p & � � �� �� � <I � | � � � � B� @� � � h� f� ؊ JI JI �% � � �� �� � �� �� �� �� �� � yI 9 ,)o �v � �� ;o R� ,� Ho � �� Uo �� �� ao no '� � {o �� �� �o w �)� �o I� C� �o �� �� �o � �� �o ;� 9� "�o ^=/w p U�UQ�TR�Q )o 0w @ �)M Uo i� _� Ho � � ;o �� �� @ ao � � no {o (�o @ �o S� O� �o �� �� �o $� � = |w � �) � K �� �� �w �/ U} = �y � �) � K � � �y �/ U} Aw -3 � U~ T1 Ww 3 U~ T0 tw p / Uv T~ Q} R| �y 9 T �5 � �w �)X� *� � K� � � >� �� n� 2� �� �� %� � � d� �� � r� �w p �& o �� g� ]� �� � � �� V� D� �� 4 0 �� z n p È Ј � ݈ ' � � � �� s k "� ��� � � "� ��"'� ��4� T N A� � � 'N� ]y X �x � �& � f X �x �x �& f 1 / = ]y � �&C K X T �y �/ Us = �y �y �& � K � � �y �/ �w �2 � U ��~ "3$ tx p: � U��~ %y f8 � U| T Qv R} gZy �� Uv T} Q R��~ �y �2 - U} -z �2 @z �2 R U} [z �: T 1 G�w U�UR0 ,�| `z } �L �| � � } R L } � � � rz rz ( � 7 5 � _ ] � � � " z (s 0 � � X z z � f � � } P � } � � �z � ( 5 1 = �z � � K o k �z �/ �| �z �z �'�| � � } � � } # �z �: T 6 ,) �z � �� ; h \ G � � T / ' X { � �'� f a ! b � � -{ P �' � � = 2{ � � K M{ �/ � P{ P{ �'p � A ? � i g � � � ) ]{ ]{ �'� ; � � G � � T s{ �: T @6 { �3 T p6 Q1 ,l� �{ � ��! ~� _ S �� � � �� & X �{ � �'^ f �� � � �� � � �{ �' � � = �{ P � K � �{ �/ � �{ �{ �' ! � 8 6 � ` ^ � � � l� �{ �{ �'�! ~� � � �� � � �� | �: T �6 �{ �3 T 7 Q1 ,D� | � �\# V� Z J b� o� � � � )| )| s' ;" � � � � � � � � � X 6| � x'd" f |� � �" }� 7 3 B| � z' q m = G| � K � � `| �/ D� �| �| k'@# V� � � b� " o� _ [ �| �: T �7 ~| �: T h7 ,h� �| h ��$ z� � � �� ; / �� � � � �| �| J' �# � _ ] � � � � � � X �| P O'$ f � � �� � �$ �� � � �| � Q' 8 4 = �| � � K r n �| �/ h� �| �| G'z� � � �� � � �� & " } �: T �7 ,� } h ��& �� k _ � � � � � � )} )} 0' �% � & $ � N L � t r X 6} 5'�% f � � !� P & "� � � B} � 7' � � = G} � � K 9 5 `} �/ � h} h} -'�� s o � � � � � � ~} �: T �7 ,�; ~I �6( �; , & < y u < � � !< ;< Y U H< � � U< � � Bb< Bo< |< �< \ X '�< fJ .< � � �< �I �' �< � � X �I �I �0 f � � = fJ fJ 1�' K sJ �/ U~ �I p: �' U�� J -2 ( U��T~ Q~ _J �1 R �X0 ,�� �J �n, �� / + '�� N S�� � � �� �J A �( �� "ɻ ���J �& U��� T��Xv N.< �J > !) ܻ "� �� K �& U�����T��Xv N.< �� K z o) �� " � ���K �& U⃠�� T��Xv � �K \ �) � ")� ���K �& U����� T��Xv 7� �K I * <� "I� ��,L �& Us T��Xv N.< W� <L n Y* \� "i� ���L �& U҃���T��Xv w� �L b �* |� "�� ���L �& U���T��Xv N.< �� M \ �* �� "�� ��XM �& U����� T��Xv �� hM ? H+ �� "ɼ ���M �& Us T��Xv N.< �M f �+ ܼ "� ��N �& Us T��Xv �� N \ �+ �� "� ��]N �& Us T��Xv = iN � , K g e }N �/ Uv = N N `, K � � �N �/ Uv �J �9 ,� �N G �5- �� � � C"�� ���� � � '�� �N O�� �� �N !- �� -ɋ �N "ʋ QX �N �% f �N 8 U1 ,�d �N � �0 �d S M �d � � �d � � �d 3 - e � e � � e )! #! O�d z O P �*�/ Vz u! s! }z �! �! pz �! �! cz �! �! Iz " " <z ]" [" 0z �" �" $z �" �" P �z �" �" " LO LO �(�. 0 o# m# X QO QO � f �# �# X lO lO �(�. f �# �# X �O �O �(/ f �# �# " �O �O �(|/ 0 $ $ X �O �O � f ,$ *$ = GP GP �( �/ K Q$ O$ UP �/ U| GP �: T F0 O i0 bP W0 U| ,�� �} l � 1 �� ~$ t$ �� % �$ ħ �% �% ѧ $& & Bާ � �� �& �& �} � ##�0 �& �& = �} � � K ' ' �} �/ Uv �} �9 �} z3 U| Qv R} X0 , � ~ ' ��2 2� T' D' ?� ( ( L� �( �( Y� �) r) f� E* 3* s� + + '�� �~ �� '�� �~ � ~ � �1 � �+ �+ � �+ �+ � �+ �+ �� P 2 �� , �+ ]~ (9 T Q2 �� � 92 �� M, I, �~ (9 T Q2 7� �~ �~ � �2 R� �, �, E� �, �, �~ 9 T H8 Q} R 9 T 8 Q} ,`� 0 � � 7 n� �, �, {� . �- �� �/ �/ '�� � O�� O�� � \ � y h3 � s0 o0 � �0 �0 � � �0 �0 � e � �3 � /1 +1 � e ` | � i1 e1 � ` � �1 �1 � p � � 4 � �1 �1 � #2 2 � � ]2 Y2 �� � O6 �� �2 �2 � � � � �4 � �2 �2 � 3 3 � 63 43 ɵ �4 ε ]3 Y3 � �7 U} T| (ܵ @ ݵ �3 �3 � � � � 5 � 4 4 � 64 44 � � \4 Z4 X � � � I5 f �4 �4 = � � � �5 K �4 �4 �/ Uv � � � � �5 � �4 �4 � 5 5 � 25 05 � S7 �5 U| Tv Q0 �� p: 6 U0 ǀ s7 ,6 U1Tv � 9 T �8 Q| � � �6 ]5 W5 = � P � K �5 �5 H%� �/ � 7 �6 U| T} HH� �: hb� 7 �6 T�U h�� 7 7 U�U =�� 7 T�T ,�= � � �_: �= �5 �5 �= 6 w6 � � � 80 �7 � �6 �6 � � � | � 7 7 � 07 .7 � V7 T7 � !� !� 80 !8 � �7 ~7 � �7 �7 � �7 �7 � *� *� 90 �8 � �7 �7 � *� *� | � 8 8 � A8 ?8 � g8 e8 � <� <� 90 �8 � �8 �8 � �8 �8 � �8 �8 :@ E� � :0�9 f@ 9 �8 Y@ <9 89 L@ |9 t9 �@ E� #0�@ �9 �9 �@ : : A �: �: A 0 �9 A �: �: A �: �: /�@ �� 0 �@ �@ A /,A �� 0 IA >A 3; 1; � �� �� ;0D: � X; V; � �; ~; � �; �; H�� �6 H�� �= ,�� � G ��< г �; �; ݳ �< �< � X= H= �� > > � v> n> � �> �> � Y? O? +� '4� �� =� ` {; B� �? �? `� z� � � =~� @ @ r� Z@ T@ � �� �@ �@ �� A A �� BA >A �� zA xA � �� P� < Q� �A �A `� I� P � ~� B B r� GB ?B P �� �B �B �� C C �� CC ?C �� {C yC �� �� 7� �� �� � z< R� �C �C E� �C �C ̄ 9 T H8 Q��R| @� h9 , � 0� o �,C .� D �C ;� FE ,E H� yF _F b� �G �G OU� � 8� @ 6 = � "H H o� � �= p� GH EH }� e� V �= �� rH jH �� �H �H �� KI II �� qI oI � n� p ' � �I �I � �I �I p � AJ ;J G�� U�UT�TQ�QR0 t@ �� � = ? �@ �@ �J �J �@ �J �J � �@ 0K ,K �@ ч / �> �@ jK fK �@ �K �K -�@ � �@ �K �K M,A Љ 0 �> IA >A �K �K /t@ � 0 �@ �@ �@ �@ /,A � 0% IA >A L L t@ 8� � 9 >@ �@ �@ 9L 5L �@ �L L � �@ �L �L �@ a� / �? �@ M M �@ HM FM -�@ p� �@ mM kM M,A � 0 �? IA >A �M �M /t@ 0� 0 �@ �@ �@ �@ /,A 0� 0% IA >A �M �M � �� d 5A C� �M �M 6� N N )� uN mN O� �N �N \� O O È �5 �@ U @9 gՈ s �@ Uv T| Q0 ݈ �5 �� �9 �� �: A T `9 =�� S7 U�UQ0 ö _� � : �A � ~O |O ն �O �O � � �O �O "�� \ � �O �O r c� c� � �A � P P z� �5 U @9 � "� � 5 C ;� ;� H� :P 6P U� uP sP .� �P �P � b� ö "� � > � �P �P ն �P �P � � Q Q �� 1Q -Q � iQ gQ r &� &� � �B � �Q �Q .�� �B U| �� �5 =� �5 U @9 =3� �5 U�UT�TR0 i>E p� � ��G PE �Q �Q [E hE uE �E �E (�E # �E 8R 0R �E �R �R ; p� p# y-�E ; /S #S p# *; �S �S 5; T �S � ~� ~� �1&D � uT sT � �T �T � �T �T x �� $ �1�D � �T �T X �� �� �f U U s W� W� �1 �D � � 3U 1U C; �� @$ �1�E U; XU VU @$ b; �U {U � �� �� �1 CE � �U �U � �U �U � V V = � �$ �1�E K @V >V � �/ Uv ˍ /8 �E T1Q �3 � 9 T x4 �� �9 � �: T L1 >E �� �$ {-[G PE mV cV �$ [E �V �V hE 7W 1W uE �W �W �E �E � �� % w- �F � �W �W � X X % � TX PX �F P% �F �F �X �X �F � �F �F �X �X -�F � �F Y Y �G �� 2G �G /Y -Y �� P8 Uv �F �% EG �F y� ,C Uv = �� �% |- K VY RY �� �/ Uv ,�A 0� & ��I �A �Y �Y j�A B�A B�A � 4� 4� �. H � �Y �Y � Z Z � EZ CZ LC �% �H QC pZ jZ �C �� `H �C �Z �Z -^C �� cC [ �Z 'D W� �H ",D P *C `� �H /C (B & B )[ #[ -B y[ s[ ; �� p& �.�I ; �[ �[ p& *; 1\ /\ 5; \\ T\ s �1 hI � � �\ �\ .Ԏ }I U�U � C; �I Uv 9� �9 T� �: T L1 = �� �& �. K �\ �\ -� �/ Uv iH `� � ��L &H (] ] j1H B>H BKH � k� k� y, �J � �] �] � ^ ^ � +^ )^ �I ' �J �I \^ P^ �I � �J �I �^ �^ -�I � �I _ _ ~J @' &K �J n_ j_ -�J P� �J �_ �_ �I �� EK �I H �� �� ( o,�K &H �_ �_ 1H >H KH XH 'aH �� � �: T �: (rH p' wH �_ �_ �H 0` ,` ; p� �' {,�L ; n` f` �' *; �` �` 5; a a s �� �� �1 ZL � � xa va ː C; rL Uv ڐ �9 �� �: T L1 = �� �' ~, K �a �a �� �/ Uv ,G{ � _ ��P Y{ �a �a e{ 3b 'b r{ �b �b G{ � ( @(�M Y{ Y{ e{ c c ( r{ x � ( L(� 7c 5c X � � �f ac _c �{ 3� P( F(PP �{ �{ �c �c P( �{ �c �c '�{ � �: <� �( =( �N ; Sd Qd x <� ) 2&kN � X <� <� � f x � P) 2 � X � � � f (�{ �) �{ {d wd �{ �d �d �{ �e ~e �{ �e �e X y� �) (( O f ]f [f = �� �) 3( UO K �f �f 8� �/ U| �� �� 0* 5( �O � �f �f � =g 3g 0* $� �g �g .ʑ �O U} Tv O� �6 = ͑ `* 6( P K h �g H� �/ U} q� 8 P U1 �� z3 @P T0Q0R| X0 � 6 x O� �* N(!�P � :h 8h X O� O� �f _h ]h = � �* K( K �h �h �� �/ Uv ,�� `� ! �`X �� �h �h �� Ji >i ¹ Ϲ �i �i �� �� �* � 9X �� j j �� �j �j �* ¹ k k Ϲ �� �� `+ ��Q � lk dk � �k �k `+ $� :l 8l .�� �Q U�UT�T �� �6 ܹ �� �+ � �+ � dl ^l ܺ ֒ �+ � xV � � �l �l �� m m �+ � � }m um � � � g �R � �m �m � n n � )n 'n �= �� p, j�U �= Rn Ln �= �n �n �= �� �, 60�= �n �n �= ?o 9o � �� �� 80 �S � �o �o � �� �� | � �o �o � �o �o � �o �o � � � 80 �S � 'p %p � Op Mp � tp rp � � �, 90 [T � �p �p � � � | � �p �p � �p �p � q q � #� #� 90 �T � 3q 1q � [q Yq � �q ~q :@ 0� - :0�U f@ �q �q Y@ �q �q L@ r r �@ 0� - #0�@ Yr Ur �@ �r �r - A �r �r A @� , cU A s s A @s >s /�@ $� 0 �@ �@ A /,A $� 0 IA >A es cs �� �6 Tv #� �� P- hB� �s �s 5� �s �s P- O� t �s Z� et at �= S� S� S �= �t �t �= �t �t f� 7 U�H s� l� �- � (X �� �t �t �� �t �t �� �t �t �� ;u 7u �- �� yu qu �� �u �u κ v v �� �- �NW Uv Qv = �� �- � K �v �v � �/ �� . ��W �v �v = �� P. � K w w �� �/ U} �� �� ! � Cw Aw = �� �� � K hw fw �� �/ Uv Œ �6 =�� �6 U�UT�TQ0R1 ,i� �� � �p` {� �w �w �� Lx Fx �� �� �. �` �� �x �x �� +y %y �. ¹ Ϲ zy ty �� � �. � �_ �� �y �y �� Cz ?z �. ¹ {z yz Ϲ �� � 0/ ��Y � �z �z � { { 0/ $� U{ Q{ .�� �Y T} 5� �6 ܹ �� `/ � `/ � �{ �{ ܺ � �/ � &^ � � �{ �{ �� H| @| �/ � � �| �| � '� '� g `Z � } } � 2} 0} � X} V} �= =� @0 j] �= �} {} �= �} �} �= =� P0 60�= ~ ~ �= n~ h~ � =� =� 80 F[ � �~ �~ � =� =� | � �~ �~ � � , * � N� N� 80 �[ � V T � ~ | � � � � [� �0 90 \ � � � � [� [� | � � � � � � � =� ;� � f� f� 90 X\ � b� `� � �� �� � �� �� :@ s� �0 :0i] f@ Ԁ Y@ � � L@ N� J� �@ s� �0 #0�@ �� �� �@ �� �0 A �� �� A �� ] A 6� 2� A o� m� /�@ �� 0 �@ �@ A /,A �� 0 IA >A �� �� E� �6 Tv #� �� 1 hB� �� �� 5� �� � 1 O� 3� +� Z� �� �� �= � � S �= ̃ ʃ �= � � �� 7 U�H s� �� P1 � �_ �� .� *� �� .� *� �� .� *� �� j� f� P1 �� �� �� �� � � κ J� F� �� �1 ��^ �� �� = �� �1 � K �� ~� �/ Ǖ �1 �^_ � �� = ̕ 2 � K :� 6� �� �/ U~ ֕ ֕ � r� p� = ە ە � K �� �� � �/ Uv � �6 ɔ �6 T} Q0R1 i� � � ( �b` {� �� �� �� #� 9 T c1 Q} �� �9 ,�� о * ��y �� � ߆ �� �� �� ̨ _� E� ٨ �� z� � �� �� B� � �� ~� _� � `| � �x q� ȍ �� `| ~� n� F� �� � �� �� ]� K� �� /� !� �� � ɓ �� ;� 3� ̧ ϖ �� ٧ � ژ � � ۚ � � ܛ � � � � � � X � ~ ��a f � � <� � 0~ ��p d� Y� � � N� �� z� 0~ o� � � � � �" hb � /� -� � W� U� � }� {� �� � @ �" �i �� �� �� �� � � @ ¹ Ϲ �� �� �� �� P � �i �� � � �� Z� N� P ¹ ޡ ܡ Ϲ �� �� � �jc � � � � ?� ;� � $� y� u� .�� [c Us .� �6 ܹ �� � � � � �� �� ܺ �� �� � �g � � G� ?� �� �� �� �� � � � � � � � g 3d � m� k� � �� �� � �� �� �= � 0� jRg �= � ޤ �= 3� -� �= � @� 60�= �� |� �= ѥ ˥ � � � 80 e � � � � � � | � A� ?� � i� g� � �� �� � � � 80 he � �� �� � � ߦ � � � � �� �� 90 �e � -� +� � �� �� | � R� P� � z� x� � �� �� � � � 90 +f � ŧ ç � � � � � � :@ � Ё :0<g f@ ;� 7� Y@ u� q� L@ �� �� �@ � � #0�@ � � �@ %� !� � A _� [� A !� �f A �� �� A ҩ Щ /�@ j� 0 �@ �@ A /,A j� 0 IA >A �� �� t� �6 T| #� @� � hB� � � 5� X� T� � O� �� �� Z� �� � �= �� �� S �= /� -� �= V� R� �� 7 U�� s� @� @� � �i �� �� �� �� �� �� �� �� �� �� � � @� �� 7� /� �� �� �� κ � � X� �� ��h =� 9� = X� Ђ � K {� w� �� �/ b� � �2i �� �� = g� 0� � K � � �� �/ U~ q� q� � +� )� = v� v� � K P� N� �� �/ U| �� �6 >� �6 Us Q0R1 <� �� `� �" �p d� Y� u� s� N� �� �� `� o� *� &� {� �� � �" �p �� � �� n� `� X �� �� �"�j f ܺ �� �� �" �n � � � � �� �� |� �� � � �� �� � �� �� g &k � p� n� � �� �� � �� �� �= �� P� jEn �= � � �= 6� 0� �= �� `� 60�= �� � �= Բ β � �� �� 80 l � � � � �� �� | � D� B� � l� j� � �� �� � �� �� 80 [l � �� �� � � � � � � � � �� 90 �l � 0� .� � � � | � U� S� � }� {� � �� �� � � � 90 m � ȴ ƴ � � � � � � :@ � � :0/n f@ >� :� Y@ x� t� L@ �� �� �@ � � #0�@ � � �@ (� $� � A b� ^� A +� ) �m A �� �� A ն Ӷ /�@ �� 0 �@ �@ A /,A �� 0 IA >A �� �� >� �6 T| #� � � hB� !� � 5� [� W� � O� �� �� Z� �� �� �= �� �� S �= 2� 0� �= Y� U� �� 7 U�� s� T� 0� �"�p �� �� �� �� �� �� �� �� �� �� � � 0� �� :� 2� �� �� �� κ � � l� �� ��o @� <� = l� �� � K ~� z� �� �/ v� � �%p �� �� = {� � � K �� � �� �/ U~ �� �� + � .� ,� = �� �� " � K S� Q� �� �/ U| �� �6 �� �6 Us �� �9 X p� p� q f x� v� = �� P� Cq K �� �� x� �/ Uv (� �� �q -� ۻ ջ = �� �� K (� $� h� �/ U} ;� �� �r � /� � F�r H� `� ^� ;� �� �� .� �� �� � U� � x ο @� Rr � � � X ο ο �f @� >� � `� `� ��r ;� e� c� H� �� �� .� �� �� U� e� 6 m� i� Uv ;� 6 Tv �� i� X � p� Js f � � X � � MIs f � � X � �� Pjs f X ;� Ј Y�s f 0� .� B� � � t _� S� = B� P� � K � � [� �/ �s U} � �/ U} _� 0� �ot w� o� = E� �� � K ؿ Կ �� �/ U| o� �� �u � �� � t�u H� � � ;� >� <� .� l� j� � U� �� �� x � @� *u � � � X � � �f � � � �� �� ��u ;� � � H� C� A� .� q� o� U� �� 6 �� i� Uv �� 6 Tv �� i� X � p� x�u f �� �� X �� �� {!v f �� �� X � � ~Vv f � � �� �� ��v � � = �� � � K A� =� )� �/ Uv )� `� �w � w� = �� �� � K �� �� �� �/ U} �� � �uw � � = �� P� � K �� |� L� �/ d� p: �w U1 �� 96 �w U} Tv ݿ p: �w U3 � p: �w U3 � p: �w U3 � p: x U2 �� �K 8x U �< Ts R �1 u� �K dx U �< R �1 � �K �x U �< R �1 �� �K U �< T �Q6R �1 '` � � 9 ,�y 9` F` `` S` �� �� m` z` �` �� � �� B$� � � � `� ^� ڮ `� ^� ͮ �� �� �� �� �� �� � �� �� � � �� E� 9 T �4 Q �1 R �0 X0Y �0 �� �� U �1 T�R ,'` � k �B� 9` b� ,� F` �� �� S` ?� 1� `` �� �� m` �� v� Bz` �` �� �� �^ #� �� F � �^ �� �� �� _ � �� _ � �� _ �� �� ,_ �� �� 9_ �� d� F_ �� �� S_ 2� &� `_ �� �� m_ �� h� z_ �� �� �_ � �� �_ �_ '�_ O� ,K #� #� c�{ >K H� D� KK �� �� XK �� �� eK -� '� ,� �7 <� Y� Џ t�� d� Y� �� y� N� �� �� Џ o� �� �� � Y� Y� �" B| � �� �� � �� �� � �� �� �� j� �� �" �� �� #� � �� z� l� �� ¹ Ϲ � � �� � �� � �� �� e� a� �� �� �� �� ¹ +� )� Ϲ ܹ :� `� � 1� `� � \� N� ܺ P� � � r� � � �� �� �� t� j� � � � �� �� �= y� �� j}� �= d� ^� �= �� �� �= y� � 60�= � �� �= S� M� � y� y� 80 >~ � �� �� � y� y� | � �� �� � �� �� � � � � �� �� 80 �~ � =� ;� � e� c� � �� �� � �� `� 90 � �� �� � �� �� | � �� �� � �� �� � $� "� � �� �� 90 P � I� G� � q� o� � �� �� :@ �� �� :0a� f@ �� �� Y@ �� �� L@ 5� 1� �@ �� �� #0�@ q� m� �@ �� �� �� A �� �� A �� 6 � A !� � A Z� X� /�@ �� 0 �@ �@ A /,A �� 0 IA >A � }� �� �6 U} T| � b� b� g ̀ � �� �� � �� �� � �� �� #� �� `� hB� � � 5� S� O� `� O� �� �� Z� � � �= � � S �= V� T� �= {� y� .� 7 U} s� �� Г � "� �� �� �� �� �� �� �� �� �� �� �� �� Г �� � � �� R� N� κ �� �� �� � �H� �� �� = � 0� � K � �� h� �/ � `� ��� :� 6� = � �� � K t� p� u� �/ U} � � � �� �� = !� !� � K �� �� 0� �/ U| ?� �6 �� � �� �� �� �� � 2� .� �� $� l� h� ..� �� Us ~� �6 �� �6 Us Q0R1 <� �� � �" �� d� Y� �� �� N� �� �� � o� N� B� {� �� �� �" �� �� �� �� �� �� X >� 0� �"X� f ܺ �� `� �" È � � h� ^� �� �� �� `� � � o� e� �= � � j· �= �� �� �= 3� -� �= � `� 60�= �� |� �= �� �� :@ <� �� :0 � f@ � � Y@ X� T� L@ �� �� �@ <� � #0�@ �� �� �@ � � � A B� >� M�@ x� 0� �@ �@ A /,A x� 0 IA >A z� x� -A M� ' A �� �� A �� �� � � � 80 �� � �� �� � � � | � $� "� � L� J� � r� p� � � � 80 � � �� �� � � � � � � � #� 0� 90 c� � � � � #� #� | � 5� 3� � ]� [� � �� �� � .� .� 90 �� � �� �� � � � � �� � � �6 U| T~ � �� �� g � � � � � D� B� � j� h� #� �� `� hB� �� �� 5� � � `� O� � � Z� �� �� �= �� �� S �= � � �= � � �� 7 U| s� t� �� �"z� �� � � �� � � �� � � �� V� R� �� �� �� �� �� �� �� κ 6� 2� �� � ��� p� l� = �� � � K �� �� ^� �/ U| �� P� �� � � = �� �� � K &� "� Q� �/ U~ �� �� * � ^� \� = �� �� ! � K �� �� �� �/ U} �� �6 �� �6 Us 5� �9 X �� �� �� f �� �� v� �� E� � � = � 0� � K L� D� '� �/ Uv = �� �� ��� K �� �� � �/ Uv �_ К �_ � � = �� К �K t� p� � �/ U �_ � *� � g� P� � � H� �� �� ;� � � .� � � P� U� /� +� x +� �� �� � g� e� X +� +� �f �� �� � �� �� �� ;� �� �� H� � � .� � � U� �� 6 �� i� Uv s� 6 Tv � i� X J� �� �S� f 2� 0� X ^� ^� ��� f W� U� X f� � ��� f X �� �� �ލ f |� z� O� � @� �� �� = �� М � K y m �� �/ U T� P� �� � = �� �� � K O K p� �/ U} �_ �� �� � �� � �� H� � � ;� � � .� � � � U� x u� P� ]� � B @ X u� u� �f g e � 0� 0� �ҏ ;� � � H� � � .� � � U� 5� 6 =� i� Uv � 6 Tv � i� X �� �� � � f X �� �� �T� f 2 0 X �� �� ��� f W U �� �� � ~ z = �� � � K � � v� �/ U| '� P� M� � � = ,� �� � K o i �� �/ U| B� p: d� U1 �� p: {� U1 �� 96 �� U Tv :� p: �� U3 w� p: Ǒ U3 �� p: ޑ U3 �� p: �� U2 O� �K -� U �< T Qs R �1 �� �K Y� U �< R �1 �� �K �� U �< T cQ5R �1 -� �K �� U �< R �1 �� �K U �< T �Q?R �1 '` �� �� @ , � 9` � � F` � � `` 6 2 S` u o m` z` �` �� �� � B$� � � � ڮ ͮ ? = �� e c � � � � � � � � 9 T �4 Q �1 R �0 X~ Y �0 C� �� U �1 T�R k � at least k#�!0123456789abcdef0123456789ABCDEF [m c [M3 C3 [�< �< 1�B �� �B 4 1�B ��1 1R�BUX YW 4 : ;9 I 1R�BUX YW 1R�BX YW U I : ;9 I ��1 1 : ; 9 I8 �� 1 4 : ;9 I�B 1R�BX YW 4 : ;9 I 4 1 .: ;9 'I 1U : ;9 I 4 : ;9 I : ;9 I�B 1 : ; 9 I 1 I I ! I/ ! U "4 1 #.?: ; 9 'I< $& I % : ;9 & : ;9 ' 1 ( 1U ) : ;9 I8 *.: ;9 'I@�B +�� 1�B ,.1@�B - 1 .�� / 1X YW 0.?: ;9 'I< 1 : ;9 I8 2'I 34 : ;9 I�B 44 : ; 9 I?< 5 : ;9 I�B 6 : ; 9 7 : ;9 8.: ;9 ' 9$ > :�� ; : ; 9 < : ;9 I =���B1 > : ;9 I 8 ?.?: ; 9 '< @ 1UX YW A : ; 9 I8 B4 1 C D E : ; 9 I8 F. ?: ; 9 'I< G���B H�� �B1 I.: ;9 'I J : ; 9 I 8 K : ;9 L4 : ;9 I M 1X YW N�� 1 O 1 P : ; I8 Q( R���B S 1 T' U : ; 9 I V : ;9 W.?: ;9 '< X : ;9 I Y : ;9 I Z.: ;9 'I@�B [. ?<n: ; \ : ; 9 ]4 : ;9 I?< ^ < _ : ;9 I8 `. ?: ; 9 '< a���B b.: ;9 '@�B c4 : ;9 I d. : ;9 'I e.: ; 9 'I f : ; 9 I g���B h���B1 i.1@�B j4 1 k6 l% U m$ > n o I p : ; q& r7 I s : ; 9 t : ; 9 u : ; 9 I v> I: ;9 w 'I x : ; 9 y : ; 9 I8 z < {4 G;9 | : ;9 }.: ;9 '@�B ~.: ;9 'I@ .?: ;9 'I@�B � : ; 9 I ����B�B �' � � lib/sqlalchemy/cyextension /opt/_internal/cpython-3.9.20/include/python3.9 /opt/_internal/cpython-3.9.20/include/python3.9/cpython /opt/rh/devtoolset-10/root/usr/lib/gcc/x86_64-redhat-linux/10/include /usr/include/bits /usr/include /usr/include/sys util.c object.h abstract.h stddef.h types.h stdarg.h <built-in> stdio.h types.h stdint.h pyport.h time.h object.h methodobject.h structmember.h descrobject.h unicodeobject.h unicodeobject.h longobject.h longintrepr.h boolobject.h tupleobject.h tupleobject.h listobject.h listobject.h dictobject.h dictobject.h methodobject.h moduleobject.h classobject.h code.h code.h pyframe.h frameobject.h traceback.h pystate.h pystate.h pyerrors.h pymem.h objimpl.h abstract.h import.h string.h warnings.h pylifecycle.h ceval.h modsupport.h bytesobject.h r l �-� X X.Yh � XY M . s.�!�%ҴJJ�� !;���JJ�� ������ [8J Y �� J �� 88u��J�� M�X%qu]��J�� !My� x� Y Y ���J�� !�~X%p J]��J�� ! y< w�X � [��J�� ! l�� lut �JK<< �3MJ<3< M zf X � O�JmJ< m t b � O- Z�} Kt� � jYt I� X � �} K"� Pt $X�} K^�f< � Y� XT �n �Z � ͼ�yJ��� ��%l J X�J�� ! y<v t<X L [�J�� ! ES.%g JX��J�� !Ey<+r t+ J Y X K`��J�� ! pJ��� �� ��% G ?�XG �o �G'!GI=K��� � X<t fX zt,w�� �� t . ��f�� �M�b�M�!LI���� �f <_yC Y�X f�� f �JX�� f uX � � KYӽXJ�� ��Z.6�y_N�`[ t f /X$wJ �! ��J<tb�^i t< x� � =, X XK& .T .[ L�/�%nL stu`��X�� �nf � Y�.=[LHu��J�� u�X�� �� nX�� tht�~[���� ��JJ%�� Jߵ Y� f�� ! ��J�� ��J<X�� !y�t� =J X � �� � �� J X � �� � �� J X � �� � �� J X � �� � �� J X � �� � �� J X � �� � �� J X � �� � �� J X � �� � �� K- � ر Y� ��� t X � �� � �� t X � �� � �� t X � �� f �� t X � �� f �� J X � �� f �� < ��<X�� < ���X�X�X�X�X�X�X�X�X�X�X�X�X�� � =Y v u��Bz X u �AJ X < . � � X � � X � t $(�XJ�XJ$�XJ�XJ�XJ�XJ K-X h ,t .������ 3IJ4� f��JX�� �3<`X � Lk u I �� _� ? =I K t �| <t<t ���ut �} t<t �t w�} t��^J�^jK �3� X OJ,TJf,�T.f J<XX = �� = �ݯ�� X =ӯ .�� ^ :J �yJ _��yJ<<�...J�y.� ������ <X �y�0KXJ=X� �=��!&, �!X2,X X�Y�Yj Y/f�Y (� X � _yXF z�� �� ��XJ �� ��J �� Z � qJ JX�XX� >�� X�J��� ��J Y��J nX� �� گ t �� ���y� X ���.� �� !�2,X X J �Y< ]= ;Y XY^�X^L �� �� J� �KX�� %5tt� Y� f �� / ���<X��� �<Z]R�K ]\<A��Z���� ��tJ%�� t�� Y� f �� /f ɳ�X< � �� J� Z[R�K [\<A��Zܳ�� ߳tJ%�� t�� Y� f �� /f ��X< � �� J� Z��L]�� �� J����� ��JJ%�� J� Y� f �� / ���<X��� �<Z Xn� �<ZT�L ��X �� J�Ĵ�� ǴJJ%�� J�� Y� f �� / ڴ�<X��� �<Z XZ�L ��X �� J��� �JJ%�� J�� Y� f �� / ��<X��� �<Z X�w��YXs� ���� X@˽ � �� .< J ��f��� J..f�<̽�� JJ �yX�E �: �E�:J � � � y QJ y Y � \ XYf..J tf J z � / KX �}tf� zX nJ+<J KX ..J*bt�t<v IYf vf �{� w � �IJv�6���I�6 ��Iq�6�I��6 � ��IJ v�6 u�#<� �I�Jt �6�I�6��GX�7 �H� �7X =�H f �7 ��IJ�6� ��H � |�8 �G �8< �GJ��7 s /X.t< R.O��I�64Xi <.i. A��Iq�6�It�6 � ��> R��i <.i.X� �Hf���7X$f iJa��0�HX�� �KXj � � J Y <t X� y� Y̤q �� J��� �� �o ]Y u Y K X � J Y� r� u �]2 0 J �>äq �� J����� �¤q � �� ��t �� �e ]Y u Y K X � J YtzX? �< u V]� � 3 }���� uX � �^ w fK v �� Jk� Xk<� ) l JJ l � > afKu Y e= -K I=<Y �K1 J<JX: �+X<J =X,f.J f�T�� > J n � h gIKu Y e= -K I=<Y���1 J<JX/K �~�� V� zJ4 .J������� X = 5�X����3�� 4� f��JX�� �3<X � L �X X � =I K ���} ��|J�tt<t �� "�3�� �fX�� �f<�� 4L�~3<X � L Jt< �~f X � = K sJ K t<�~��} ��|J�tt<t ���~�Ӭ�� 3pJ4 fάJX�� _3<`X ! L] g I MX _X = K t �| <�t �S�ut �} t<t �t w�} t�� �f��F. �9<=�F �9�FXX�9 �tI � f %J�F�9��J�5�� ( �mJ�m < mJf e�%�t� u � K X g Y J X�Z�J�5�<� F� @ F R��%�t� u � K X g Y J X�Z�J�5� =�� t �t� ���Y�� � ��� �%� u V]" ]� u V] �Z2�/t � � K �KI��4 �,��Y� l� ���&� u V]" ]� u V] �Z2�/t� x< � K �KI��4 �L��2;/t2/t ����~J�� .�~.XE �� � �qE�. �q � Y.<�"X��pX X<� � t � J b�Y � YX = Y� = Y� = X���� J ?�� � . �� �� � f �� �� � t�� � ���.���� �� � ���� XJ� �%nJ stu`˳X�� �nf � YT.=[LHu��X�� u�J�� �� nX�� tht� ��w��ʡJ�� � ���yJ� �� r���� > � i :� � �~�� t�� �~<�t �� X< ��� 6��� ��~J tu t�KXtY .CYϝJ �� � �wr���� $� X�wX ��WK��� � X � �wJf�,w�� |�� < ��tX�� �XM�y( ��J�� � > � i :� �A X ���~� tu �� � �̡�� M�z�XKXtY .CYϝ �� t� �z �ܥ t�� �f� �z X ���Xt�� XY;�u";v t�J�� � > � i :� X�� �~� � ��~� �������~ ���t �� f X X�~ � � ̡�� KXtY .CYϝ �� t� �u����� X =�� n�X �� � �u � t XYN�m�N �tU ��yX��� Jt<\�!� ���yt���� % ��y�� �� t W.<W uX = Y� �� �JX �� x�D���� X =� f �� Y �f K et �.< �� t �� �XJ�� % t YҲ J ���� Z!� ���yt��� �y����4 X<Xe � � � w� ce.q� Y.<XaJ X� k� t�t�]�N ��1 ��)äq �� J����� �¤q �� ��� �� �e ] u � K � � J �t �W� M�HKL�L � f�3�L Y� t�3�L �� ��X�� ��VI�J 8�HK K �L�L �tX.��3 dK �JJ Y � �)< u �]�W �< �)X. �V�J7��7� jt � ��<�� df c; �.< Y k� t�����N ��1 ��)äq �� J����� �¤q �� ��� �� �e ] u � K X J J Yt �W� YHY �h�L � ��3�L Y� ��3�L Y� |� �4 �� z� ([ X� �) ��VIJX 8�HY Y �h�L ��XX��3 dK �JJ Y � �)< u �]�W �. �)X. �V�JC� JC � �}X �t= �}��aL M�GKLVY� X=;� ��t�� ����� $�@��Y��� � ��� �aUKK K H��L Y� ��3�L Y� ��3�L Y� ��� !�~�t$ $e ��t�~< ef" fX� /�.J,<�=��X�� �l�=��� � |��� �� � `x<f�� �!�~��t$�~f$e � etf(f-<J �Ng 7 � %J � / %< � W���� � �<�� � ��.X �� � X�V ��KHK KL ��L Y� ��3�L Y� ��3�L Y� |��� Y : �=��� �� ��_MGKLVY MY � b���� �� ��_UK TK WKZ K�L Y� ��3�L Y� ��3�L Y� � �� �~ G!u� � �f g(�-<J �g 7 � %X � / %< � WX ��_MGKLVY MY � b � �� = ����� X=�� � n�X"�� ��9&�#���"�<� � t;K&� M :K =g��YX�� �� � |��� [��J Y� �� �� �� �� tJ� �� �� �� Dx<�� �� 6 � K#0;� > � 9 c u Et 9� ެ�XXJX�tX��X�� !t �at Jt �Xt<� �<� ��� �� t��tJ �� �� ��� �"h<<X ��_M� J�_<KLVY MY � bX �����XX�� �!����=g �� ��� 0X Y � !r u u" K$ =٬YX�� � ���� �� �� <�� ȭ<� �X��� % =" =ѬX �� ڬ �XX�XX� �1 c �.< � kX= tJ�<���N ��1 ��)äq �� X����� �¤q �� ��� �� �e ] � Y K . / � J ��W X� �( � �]�W � dK . / �J [. � �)X% �V�.. �LXX����& M�j� �t<?��� t�� J� �p��t �p t ��<� ��� ��& � �rX � t ;t �.<u�rx ��YX�& ��P�/ � K�JX �5k�q YsY-K�Y�YX�&X=�Z � f!�&�Y � �&�Y � �&! � Y�Y t�&�YJ�& sJ <���<Y<�Y�&�Y�%� ��Y�&/ E3 �Y��Xg�& �Y�����i�&X �6� ��V K�YHY Yh ��L Y� ��3�L Y� ��3�L Y� |��� 2Xw� �<Zg�c6�Y �� �p c �.< � kX= t�����N ��1 ��)äq �� J����� �¤q �� ��� �� �e ] u Y K � � J �� r u �]�W w X<���r �� Z�Y �K� �4X=�J .k�&n!��Y�&�Y � �f�&�Y � � �� x�f �.�4 X� �KXX��3 dK �JJ Y � ? �)X �V�J�l�z.jt &�9�[ � K <�� � X t <D �a. � X XD �a ! �` �= ��a �: � � XJ �f<�yJ�� Y �a� J � � �C�<;�Y��aX� <.� q z< ]*�.JJ� Y Y �H�y�=�B<J�#�7X0s3 JX(�b Y � t $ / �_ X � �4 � << �K? ��]�"t �e��y<�2��_<� �_ � � ����_� �_ � � 0n�_� �_� �_ � � �_ � � � t �! � �` !� ^� J�_X 6���= ��~�A\�> (� ��� t��a� X� �b X ! �` �� �X!� � r� �f<�yJ��YX �`j�J � 0n�_� �_� �_ � ��%� � \�a4� XX\�at �`��=Y �H�y�>%X�AXJ�%�7� �BXX�<<� � �~ X � G? X< ��B�=�B<J �= I#< Y l JJ l�� z� Y jX���bXXV� .� �;� �_� X5�t2< �_<5� )f�_ � L� J�_XX t�<(.�d�W�$�_� �_ � �XR� t� � ���'� uX < X�PzXX<�*X.JJ Y �d�A\�> �� !�t j"� < �C� �z.jt &�A�[ � K <�� �! X t <L �^. �!X XL �^ ! �c �= ��^ �: � � Xf �i<�yJ�� Y �e�J � �! �C�<;�Y��^X�!<.� q z< ]*�.JJ� Y K �H�y�=�B<J�#�7X0s3 JX(�^ Y � � $ 7 �` 8 � �`t J8 � !��<���c � � �bX� U!�c � ��!� � �! ��~�A\�> (� ��� t��^�!X� �^ X ! �c �� �X!� � r� �i<�yX��Y%zX �! d�^4�"XXd�^t�!K �H�y�>%X�AXJ�%�7� �BXX�<<� � �~ X � 9? ��B�=�B<J �= I#< Y J l <�� z� Y jX���_XX�2X /;YX � (.� � ���'� uX ��BzX *X.JJ Y �d�A\�> �J Y�t'��)v��]�c�� � � J �gXx. ptxJ.hXtJhJ �X p��L�[Y � Y � � �a<�yJ�� Y �]�"X � � �C�<;�Y��fX�<.� q z< ]*�.JJ� Y Y �H�y�=�B<J�#�7X0s3 JX(�f sX g /�0(J g /�0(J g � W�2 ��J�� � > � � < �?�L�5�J<X$ B �4 X<?�KB��g�=*�e��Z � �%8� u�Z�%�ZtX�%��ZX�%X=�[ � f �% � ��XJ�'���� ��Z ��%�Z�%�YJ�% �Z�%�Z�< � � �! �$ �[X Y� �^�$!�[X Y� �^�$!�[X �� �X^�$!XM � �aJ�yJ�� Y �aJ�yJ�� Y�� ��~�A\�> $� ��� t��f�X��f!�[X Y� �^�$!�[X Y� �^�$!�[X Y� �^�$! �: � ]Xi �a<�y�$L�[JJ�� Y �a�yJ�� Y �a�yJ�� Y vX%< � o�f3�XXo�ft � � <W �f. �X XW �f �4t X<?�KBC �B X�3J �.�eY �H�y�>%X�AXJ�%�7� �� �� �$ � �# ��Zt �%�ZXJ>�% �<� t�� ��t�� J@˽ � f�� ̽�� T�b �ZW�%� ��Z � �%Z ] ��Z�%�Z � �%�Z � �% �4 �A�KD ��p< �ZJs�% ��Z J� �%hVY�Z ��%� �Z � t �XXXXXX�XX��%�Z �.XX�X�<<X � �~ X L 9? �B�=�B<J �= I#< Y l JJ l�� z� Y �X���gXX �[XX��%�Z �X��<$���hX� f�Z � t�%u �Z�%�Z �X��%�Z�% �Z.� �%:�Z�%� �Z�%�Z �X��X�X��%#X �Z.�%<Y �Z�%�Z ���= � ���'� uX � X�BzX*X.JJ Y �d�A\�> � ��t%n�hX� ��Z � |��%� �Z[�$�� ��Z � J��%� �Z��$XX�2X �̡�� K�t� .C�ϝJ �� � �wr���� � > � i :� � �~�� �� �� � ��� ��� <.�f�)v��f!�Z��%� �� .�i� �Z�%�Z �X��� �̡�� K�t� XC�ϝJ �� X �wr���� � > � i :< � �~�� �� �� .<.� �WK��� � X �) XX �w�� ��?�$ �;XWK��� � X � �wJ��tb,w�� ��� ,w�� ���� X� X���E� �Z�%�Z�� X <u �AX?p��a�5 vt�et ��~JX� �'��� � �q � �X.<X< � �i�X �!�$ ��eX!� edJX@<C ��e � ��e �� �e�� �� �Q�yX� �!�$ ��dJ��dXJE� �J�dtJ<� �J�d ��dJJ�_!X$ � a �d �< � v<�dJ �JaL�d<!� eJ ;�d � �t���d���. �� c; �.< � k� t�t���N ��1 ��)äq �� J����� �¤q �� ��� �� �e ] u � K X f J Yt �W� M�HKL�L � ��3�L Y� ��3�L Y� |� �� Xs������ i�X 1 7�d� �( �Q�yX� �!�$ ��dJ��dXJE� �J�dtJ<� �J�dX!� eJ!X$ � a �d�J�~� �<�dJ�JaL �d � � � � t� �e<���t���.�f�d � J;� �df;�J�dX� � � ���d Y� ���d��<� �d � �t�d. �!$ � �t<ttk�b� �[J yf, .�& f <] �d �(� �= f�X= t�qt���N ��1 ��)äq �� J����� �¤q �� ��� �� �e ] u � K � � J �t�e�q M�HKL�L � ��3�L Y� ��3�L �� �f� � ;�J �d�J ��f �Z2.X�f�d � J <J� D�X��df �tX�;����d�/ �d � ���d.���t�t f� Z ��fhk���� <%�/ �d � ���d.Ȃ��t�t f� Z ��fhk��.<t$<�<;� <XP t;;<X�~f<X �� < u �]�e� �X� <�� X� �) ��e�qJJ��qHK K �L�L� �� ��VI�J 8�HK K �L�L� ��XXXX���d��d�� �d � ���d. �tX��d� �2 dY XJJ Y � dY �JJ Y � �)< u �]�W �< � �)X �V�J. = �)X �V�J�m�?p��a�5 �3 JX<<�L?�� <"� tt^J � �� J� � �q � ��< � �i�_ <!�$ ��^X!�! edJX@< �^JC�! ��^ J� �!�^ ��! �^�! �( �Q�yX� � !�$ ��]J�"�]XJE�" �J�]tJ<�" �J�] �"J�]JJ�"_!�$ � a � v<a��]<t!�" eJ �^<� � � � ��! �; ��V K�KHK KL ��L Y� ��3�L Y� ��3�L Y� |� �� Xs������ ŽJi�! 1 7�]�" �( �Q�yX� � !�$ ��]J�"�]XJE�" �J�]tJ<�" �J�]J!�" eJ!�$ � a �~� �Ja� �]� <J ���� �4 c; �.< � k� tJ�<���N ��1 ��)äq �� J����� �¤q �� ��� �� �e ] u � K � � J �.�F�] � ;�"Jf �]XJ� � � ���"�] Y� ��"u �]X�"�] �� ���� < u �]�e��`9XY �] � �<��!$ � �<tttk�b� � �b, <�& f <] �d �;9<���] � � 6��"�] �!�^J;�"<X �]�� �� �= f�X= t�qt���N ��1 ��)äq �� X����� �¤q �� ��� �� �e ] � � K � f J �t�e�q M�HKL�L � ��3�L Y� ��3�L �� �X�"�]�" ;� �]�"�]��!�gj��� ��]�"/ �]�;�!fX� ��] � �!J�^J <J;�"���X X� �( u �]�WJf�;�m���] � J �!�Z9<X� ��t�t f� Z ��mgj���� JR.�t�t f� Z �� �K� ��"�]�"f� �] � �!J�^J �"< �: ��e�q�J��qHK K �L�L� ���XXX��3<� dK XJJ Y � dY �JJ Y �0 Y �)X� �V�J. / �)XJ �V���;�oX�]�Z�!<X�{�z.jt &�6�[ � K <�� � X t <A �_. � X XA �_ ! �b �= ��_ �: � X. �h<�yJ�� Y �c� J � � �C�<;�Y��_X� <.� q z< ]*�.JJ� Y Y �H�y�=�B<J�#�7X0s3 JX(�` Y � t $ , �a � �t �Ht X � �a �7 �HJ X � � � �F �9 �% � t� u � K X K Y J X�Z�J�5�JY ( �X�H�7X<�g�b � �a f � �#�; ��J�� � > � � :< �8�C;��a � � �= �?�BB���m�=*�O��a � � ��a� �= �A�BD ��#�A �=��{J��>E�\ �a � � !�$ � aJ�`tJ� _J � �a� �a � � � t �! � �b !� ^� J�aX 6���= ��~�A\�> (� ��� t��_� X� �_ X ! �b �� �X!� � r� �h<�yJ��Y%zX � Y�_4� XXY�_t� <�H �7X<�f�b � �a n��� �`X� �= �A�BD �YsY-K�Y�`X� X=�a � f!� �` � � ��^J2�!! �a� !�$ ��`X � cJ�`tJ � `J �a � ����=Y �H�y�>%X�AXJ�%�7� � $ ���X�� �8�C�<X X �< u V]" ]� u V] �Z2�/t x� �I�K �4XK �KIf�4 ���Y��g�b � �a � �<<� � �~ X � G? X< ��B�=�B<J �= I#< Y l JJ l�� z� Y jX���`XX2�/t� %J�F�9 �JX ]X YX�g�b � �a |� � � �a� �a � � g;/ �a �X��X�<(.�C�XY� f�� � XYX<��;XJtu��� �a � ��� �a� �an� X�[.f�$</��a� �a � ��;� !'�'�a� �a!� � � ���'� uX < X�PzXX<�*X.JJ Y �d�A\�> � !�t%�G X_�"�e�� �>�� �� J ; ��X�\�a� �a� � �a �� X �̡�� K�t� XC�ϝJ �� � �z#r���� � > � i :� � �~ܥ �� �� � �z �J � .� � �ܥ ��� .{�C� ���`�� �)���` �#X � =����� ���<� f � �̡�� K�t� XC�ϝ �� f �z#r ��J�� � > � i :< � �~ܥ �� �� �< �z X ܥ ��8� �<�J<. � �̡�� K�t� XC�ϝ �� f �z ���� J =ܥ �XX�� X���z <u X �X< �z ��� XYi��&/ �� iղ�� ���<�� � �f� J�J �"�HJ�7 ��H �7 � K � �!t = ���J �4X=�J f`�c � �5 �o��o� �o�J� �"( �Q�yX�� >� �mJA���m J� � [� � � �mf� ���� X6�9� ��m� ;� �m� �4 R X J Y t<� _�P �/ u �Pt�yX��/� �P �/ u K�JX �5� ��Y ���K���m� ;� �m�� t �!� �Q�yX� � �!�^X �!t ;t �.<g�^ �m�j�J ��l � ��j � uI � ��m#� �l �"� # � YZ�Y�l ���m� �;� �mX��m��m��m � ���m� `�����n � d�J�mX��u [� _^X���f�"t�=t f� Z ��]QTk�人 �m��t� � �!t � t f� Z � �^Q T k��! X� �^ K K�lJ ��lJ ��l t �u� ��lX�J =�m � n�X��z.jt ��A�[ � K <�� �' X t <L �W. �(X XL �W ! �j �= ��X �: � X. �o<�yJ�� Y �k�J � �' �C�<;�Y��XX�'<<t q z< ]*�.JJ� Y Y �H�y�=�B<J�#�7X0s3 JX(�X Y � t $ 7 ��j ��'��z5 �o�u�o�u� �"� �Q�yX�� >� �mJA���m J� � [� ��i� �# ��h ��hJX"� e<� �& ��~�A\�> $� ��� t��X�'X� �X X ! �j �� �X!�� r� �o<�yX��YX� W�Z ��i��hX� � < �~!�j � ��!�X� � ( �Q�yJ� � � �cJ � t ;t �.<e�c �hth�< ��h � ��f� uI���h!��h � �! � YZ�Y�h f �:�� ��h� �;�X%�~ �' d�W4�(XXd�Wt�'Y �H�y�>%X�AXJ�%�7��X�i��itX� �iX���ORi�< �%<X � �~ X L 9? ��B�=�B<J �= I#< Y l JJ l�� z� Y �X���Y �&�$��[�h��h��h � ��h��|���& � ���'� uX � X�BzX�*X.JJ Y �d�A\�> � ��t%�U�n � d�J�mf��� [�_^X���z��"t�=t f� Z ��]QTk���X �m����KK�hJ��hX��h ��u���hX�J=�h � n�X�� t�t f� Z �X �� X�w X� �K�.z.jt ��@�[ � K <�� �* X t <K �U. �*X XK �U ! �l �= ��U �: � X. �r<�yJ�� Y �m�J � �* �C�<;�Y��UX�)<<t q z< ]*�.JJ� Y Y �H�y�=�B<J�#�7X0s3 JX(�V Y � t $ 6 ��l ����l� '��l�u� � � �Q�yJ��?� �j<B���j J� � ��k� �# Y�j ��jJX"� e< � �~!�l � ��!�X:�f� f�j� g;/< �( ��~�A\�> $� ��� t��U�*X� �V X ! �l �� �X!�� r� �r<�yX�� YX� � ( �Q�yJ� � � �aJ � t ;t �.<e�a �jth�< ��j � ��h� u�����j!��j � �! � �Z�Y�j � ��W�Z ��k��jX��%� �* c�U4�*XXc�Ut�)Y �H�y�>%X�AXJ�%�7��V�l��ktX��X�j � e�Jf�jf���ORi�f'J�j��j��j � �f�jf� �<<X � �~ X L 9? f�B�=�B<J �= I#< Y J l J�� z� Y �X���V� �l��<$��X� t�=t f� Z ��`QTk�f��X�( � ���'� uX � X�BzX�*X.JJ Y �d�A\�> � ��t%|�Xf �k����<� .�XYY�jJ��jX��j ��u���jX�J=�j � n�X�4 X��a� t�t f� Z �X �K��(�L �h�� ��t� � �P�/ g K�JX �5i�t�, �J�� � > � � :< ��/�R2��V � �) tXR<?���t�� J� � �p � ��<� ��� ��) � �uJ � t ;t �.<u�ux ��VX�) � �P�/ � Y�JX �5k�t YsY-K�Y�VX�)X=�V � f!�)�V � �)�V t �) ��V ��)�VJ�) sJ < �,�� ��x n�/�) �,� �������� ����Z/�Q3 2 X�-X �. ݩXg�) c�<Y� �V�)�V�)�V�)� E3 � � .XZ<Y �K� �4J=�J fi�)l��ff� .�V � i�)Xf�Vf. �i�)ff �3X ��V K�KHK KL ��L Y� ��3�L Y� ��3�L Y� |��� 2X� ���l �ff�g�f6�V �3� c; �.< � kX= tJ�<���N ��1 ��)äq �� J����� �¤q �� ��� �� �e ] u Y K � X J �� r u �]�W w X���uff � � Z�Y �K� �4X=�J .k�)n!��V�)�V � �f�)�V � � x��! �) �V ! �) t �V�X�<�� � ̡�� K�t� XC�ϝJ �� � �ur��� � > � i :� �� �~�� �� �� � �u �J � t� ����Z �~�� ��/�)�-f �] X��, X�" �v�� �~ � ̡�� K�t� XC�ϝ �� f �ur �J�� � > � i :� �. �~�� ��X �� �< �u � �� ����~ ����~ �XX��3 dY �JJ Y � �#Jt�~�� X�� �S< �)X �V�J� �" � ̡�� KXtY � ytC/ϝ �� fX �uJ ��XJ�� X =�� �X� �� X �u� t< �u t� J X��u�� J�Cz.jt &�A�[ � K <�� � X t <L �e. �X XL �e ! �] �= ��e �: � � Xf �b<�yJ�� Y �^�!J � � �C�<;�Y��eX�<.� q z< ]*�.JJ� Y K �H�y�=�B<J�#�7X0s3 JX(�e Y � � $ 7 �Y 8 �& �Yt J8 �&!��<���\ � �# �[X�$ U!�\ � ��!�#� � ��~�A\�> (� ��� t��e�X� �e X ! �] �� �X!�#� r� �b<�yX�� Y%zX � d�d4�XXd�dt�K �H�y�>%X�AXJ�%�7� �BXX�<<� � �~ X � 9? ��B�=�B<J �= I#< Y J l <�� z� Y jX���fXX�2X /;YX �(.� � ���'� uX ��BzX *X.JJ Y �d�A\�> �J Y�t'��)v��d�\��#� �J �jXx. ptxJ.hXtJhJ �X p��K�[Y � Y � � �^<�yJ��! Y �Z�%X � � �C�<;�Y��iX�<.� q z< ]*�.JJ� Y Y �H�y�=�B<J�#�7X0s3 JX(�i sX g /�0(J g /�0(J g � W�0 ��J�� � > � � < �?�O�2�M<X$ A �1 X<?�NB��d�=*�e��X � �'8� u�W�(�WtX�(��WX�(X=�X � f �( � ��UJ�*���� ��W ��(�W�(�WJ�( �W�(�W�< � � �! �' �XX Y� �^�'!�XX Y� �^�'!�XX �� �X^�'!XM � �^J�yJ��! Y �^J�yJ��! Y�� ��~�A\�> $� ��� t��i�X��i!�XX Y� �^�'!�XX Y� �^�'!�XX Y� �^�'! �: � ]Xi �^<�y�'L�XJJ��!Y �^�yJ��!Y �^�yJ��!Y vX%< � n�h3�XXn�ht � � <V �i. �X XV �i �1t X<?�NBC �B X�0J �.�eY �H�y�>%X�AXJ�%�7� �� �� �' � �# ��Wt �(�WXJ>�( �<�t�� ��t�� J@˽ � f�� ̽�� T�e �WW�(� ��W � �(Z ] ��W�(�W � �(�W � �( �1 �A�ND ��r< �WJu�( ��W J� �(hVY�W ��(� �W � t �XXXXXX�XX��(�W �.XX�X�<<X � �~ X L 9? �B�=�B<J �= I#< Y l JJ l�� z� Y �X���jXX �XXX��(�W �X��<$���kX� f�W � t�(u �W�(�W �X��(�W�( �W.� �(:�W�(� �W�(�W �X��X�X��(#X �W.�(<Y �W�(�W ���= � ���'� uX � X�BzX*X.JJ Y �d�A\�> � ��t%n�kX� ��W � |��(� �W[�'�� ��W � J��(� �W��&XX�0X �̡�� K�t� .C�ϝJ �� � �wr���� � > � i :� � �~�� �� �� � ��� ��� <.�f�)v��i!�W��(� �� .�l� �W�(�W �X��� �̡�� K�t� XC�ϝJ �� X �wr���� � > � i :< � �~�� �� �� .<.� �WK��� � X �) XX �w�� ��?�' �8XWK��� � X � �wJ��tb,w�� ��� ,w�� ���� X� X���H� �W�(�W�� X <u ��Xz.jt P�9�[ � K <�� �% t X <D �Z. �%X XD �Z ! �g �= X�Z �: � N� �m<�yJ�� Y �i�J � �% �C�<;�Y��ZX�%<mX.�� q zJ ]*�.JJX Y K �H�y�=�B<J�#�7X0s3 J�X(�Z Y � �% ��~�A\�> �X ��� t��Z�%X� �Z X ! �g �� �X!�� r� �m<�yX��Y $ �e � �et J � �eX �t�/ �fX� �,t�d<g� ��P�/ �J K�JX �5^�d�f � ��dJ0�! � �&�Yf�&t X=��@<t�?r�Y�< �J�� � > � � :< ��/�B2 �f�A�<J �f<J��f � � �� �HԿK����f � � �& �f�X �?X� �F�y �� ��J�9� �' h H�< � =5< .u 'vXX'pJ X't <= g K K N P�"�~�< @���~ ���~<Z X=� J% _��X# '� �f g� /� J Y e KX Y e KX Y e KX Y e KX Y� J Y� �YvGYI�Y�X���<�'� =j/=��� ��%�B �% \�Z(�%X\�Z��%K �H�y�>%X�AXJ�%�7� �B���'X�==�Ǟ?�/Z� � l� �< ^ � L � N Z f Z� = � g5J^<5<^X <�.�XXXZ�� ���f � � � � ���f� �;� �f � ���f � ���f Y� �� �~ !�g � ��!��&X�)v��Z� �f � ���f�� �f��f � �� � )�֞�� ����� � ��� �?� �@��� ����Z/�A32X �f�f�� � ��� �<X.�k =.j��� ��� �f<� � �~ X L U? X<< ��B�=�B<J �= I#< Y J l J� � � \XX��[� �& �Z��%<t%%)!�Y�g � �J��� �f�� X�f�u �fXX�X����f 6� ��f f � � ��f��fJ� �f�� ��� <X<Q�XT1��f�~�� �#֞�x �l<Y �K� �4J=�J f^�a� ��f � n���f��f��f�� �f �Xt���fX��Y� MJ3.�� �f�� ��f� �;Y �f �>X X�<Xb�YV� �g�� ���f� �;� �fV�X�&���}�< � ��<� w X'� ��BzX�*X.JJ Y �d�A\�> J Y�t+XX �C�X���<J t � � ̡�� K�t� XC�ϝJ �� � �ur��� � > � i :� �� �~�� �� �� � �u �J � .� ����Z �~�� ��/��<X ީf/� �f �� < ��f�i� �f���� � ̡�� K�t� XC�ϝ �� tf �ur �J�� � > � � :< �J �~�� ��X �� �< �u � � X�� X�� �vJ� ��t� �f.X��f� K;Y �f �� XJf� �~.�� �~ � o, � � ̡�� K�t� � y�Cgϝ �� t�X �u ���X�� X K�� �X��� J 7X.�~ � �X �u� �< �u �� X X�.�u� Q �F �� Qw. �tX= K� � K' � Y�� `X.(�� JXJ.�f �J=Y Y � , > < /� >�Q n� �-wG� KyX <�.Y! RY!6_� X�i t g u / Yt�� t Y �W�yJ��'Y!Y�Q��.<=�Q 6��.Y�� �K �K �K ���R � ���.�?�<��q?�� � �� J � <t. z. g<t�w?�.+ �u<t� < =rvJ ��Y.X Y��J< �� )V*<. �=] t.C��� ��� �� `��� � J �SX �Y�1�1ueK1/X�t��1u�K1/X�t��1u�@1/X�t��1h;1�h� Y1K/X�t��I1uIe1�+��K1/X�t��1,1u�1Y��1/X�t��1u�(1/X�t��1h;1�h� Y1K/X�t��I+s=1Ie1��K1/X�t���+�1��;+s=1;1u��X�XXY1K/X�t�[�+�=2�;t2u��X�XXY2K0X�t�Z�M �2J�Mf 6��2�M n� �2K��LVZY�Y K�� �� ��J �� < 9 � X �q [�|X ���&H�~M���� �� Y�J�� Z����<�� Y�&�Y��J�� �� Y�<�� zJ:Y��T��X �. �+ �. �*. �3. �0. �0Y�� n��� �|<� + �� J..S�s �S� �<K �X =Z� �*p'� ��< �� J � uX g֞�Xh�"<�"X< Yݺ< �� !ѽ!�=fY �� ߺ X `X�� � Y���� < = 6�.�� <�%�pX����� .� g K��< �� �� n��� � � ��X �� << � �� 6�.� �� ں< �� � `X �� �� Y� `��� � W =�Y ��X �� J<� �� 6�.�� y <�0� �m 0 x� � t X � �J� <�fZu � �t O X Z ] �Jtt� �J<*v X Z�Jtt2NJJ<2zXK<. � � > X! � = �� = \��=�= �� �f�� n��� K ! \�� `X.�� Y�� n��� �� � �> �= !�� Y� `X�� ZݹX Y� `X�� ܹX Y� `X�� ۹X Y� `X�� J �� n��� �H� HwtX=^Y�� �� ��<t�� �@ ��J� n��� X3=3t �tXf it� �< _ � .�`Jc� ��d<g ��^<a � Y !( r �% <\J;-)� �� �.=J�w� �.w� zu3 �0 X O� 4< ! � Y#!Y� �K �.=J�}� �.}� �K) X& X \F��;-:.2::.2;-Z;=. X Y� ��J Y� `��� ��� �� J J� `��� �� Y� `��� �� Y� n��� �� Y� n��� ^. R� .<X#���e<rtY0.�Y ��Q<�. yX6t9��Q<�."�U��| Y�<��*StV�"�U��| Y�<�&�*WtZs�.- ��.&t Y" �,"V =�P�/.%)�Jg =-K 0 J = Z Kv. J&t t$���Q%#t5t8�.� En*<EJ xJ 5.�Q�JD.� t%#�GtJ�'%�KtN� �#�w =/���G"#�� t��.X=�| ��<��� �=�� �=V X�� ���{<��� .=��z� � � �=Y��<��� < Z� n��� nڶ ��<� � ��� < �.X�� �� � n��� ֶ `�+�.�."�#.�"Wu��] �4vrZ�,f4�StZ��4� �, J Y X KKX//3f.;KH<�0X 148f. � � K � �KJ.��S �3t6�&$�BtE�&$�BtE�'%�DtG�'%�DtG�'%�DtG�'%�DtG��| ��R�-��{�t�3�6� �� ��HtK��} �= )'��t�4�}�r�4X�t� �Mt X �O �0< � �O 6X. �0 XY Z �~< �r��r[� Xb��xb`�4�5)'��t���}X� �|B9N(t^{Nyt�St9�,<Qt�S �,��|F ��}F � �}@ a�]�X��K� JM�tM�gXv � .�g`]K`su\�X �f&� 9�gC�l�CX�}��K�J��}B ��}F ��}F �MXP��[<^��P n� �/T W�X��P n� �/�P `� �/ IXL��V<Y��P `� �/P S�X��P n� �/�P n� �/ �Pt�/�Pt<G�/�P�/<t�P 6X�/8 �-��X��P n� �/ �-��X��P n� �/ �0��X��P n� �/�0��X��P n� �/�0��X��O n� �/ �0��X��O n� �/ �0��X��O n� �0�0��X��O n� �0�0��X��O n� �0�-��X��O n� �0 �-��X��O n� �0,�/�X��O ��u�/<.XlA�tXj<th>.vXw t� t� t� t� t� J� J� J� J� Ji J4�O � n��0�OX �� ��#�� t\�eU.y-tS.�.tR.S/tQ.e� t@.w� t�.}� t�.+� t�. � t� YK�z�K^�3t�3 X2�q�2Xg�_�g!Xc�M�c3X� ����� X� ����� X� ����� X� ����� X� ����� X� ��~���X� ��~���X� ��~���X� ��~���X� ��~���X� ��~���XF ��~�F�X.�~��.�.�OXn�.�p.���O4�1�X�~�| __Pyx_CachedCodeObjectType char_pos attr_name _PyObject_GenericGetAttrWithDict Py_tracefunc raise_overflow object_reduce_ex __Pyx_GetItemInt_Generic PyLong_FromLong message lenfunc PyModule_GetDict __pyx_d cython_runtime_dict _PyOpcache __pyx__find_code_object __pyx_nargs _dictkeysobject PyExc_KeyError PyDict_GetItemString tp_getattr __pyx_int_92207882 PyExc_TypeError __Pyx_CreateCodeObjects sq_item co_argcount __pyx_k_A_G1F_a_vWA_q_q_q_0_AWKwa_0_AWK utf8 nb_add ascii _Bool ob_refcnt __pyx_k_stringsource PyTuple_New PyTuple_Type sq_ass_item __pyx_umethod_PyDict_Type_get PyBaseObject_Type __Pyx_PyObject_GetMethod _Py_DECREF __pyx_k_reduce_ex sq_inplace_repeat __Pyx_CyFunction_Vectorcall_FASTCALL_KEYWORDS_METHOD tp_as_async nb_matrix_multiply expected_basicsize nb_lshift __pyx_k_ArgumentError sq_inplace_concat ma_used tp_is_gc co_firstlineno __pyx_pw_10sqlalchemy_11cyextension_4util_7__pyx_unpickle_cache_anon_map nb_power ignore __Pyx_CyFunction_set_defaults __pyx_k_pyx_result am_anext from_name __Pyx_PyList_Pack hex_digits sq_repeat curexc_value __Pyx_PyErr_GivenExceptionMatches tp_itemsize __Pyx_CyFunction_get_defaults __Pyx_CyFunction_clear sq_concat from_annotation_subclass __Pyx_modinit_global_init_code uint16_t __pyx_k_ entries __pyx_k_prefix_anon_map___reduce_cython initproc overflow_arg_area __pyx_mstate_global __Pyx_UnboundCMethod_Def __pyx_k_cache_anon_map___missing __pyx_pf_10sqlalchemy_11cyextension_4util_15prefix_anon_map___missing__ __Pyx__DelItemOnTypeDict PyGetSetDef reg_save_area tp_bases use_cline is_unicode ma_version_tag PyErr_SetObject __pyx_k_get __Pyx_UnicodeKeywordsEqual padding_uchar PyDict_GetItemWithError func_is_coroutine __pyx_obj_10sqlalchemy_11cyextension_4util_prefix_anon_map context_ver setattrofunc f_valuestack is_little __Pyx_check_single_interpreter tp_dealloc defaults_kwdict neg_one __Pyx_CyFunction_set_annotations _typeobject nb_floor_divide __pyx_k_get_anon PyMethodObject DIGIT_PAIRS_8 nb_inplace_lshift __pyx_k_id_2 __pyx_pf_10sqlalchemy_11cyextension_4util_15prefix_anon_map_2__reduce_cython__ __pyx_k_lib_sqlalchemy_cyextension_util __pyx_k_Note_that_Cython_is_deliberately __builtin_va_list invalid_keyword_type __Pyx_CheckUnicodeValue __Pyx_modinit_function_export_code __pyx_k_pop strrchr wrapped_i modname f_stacktop PyErr_WarnFormat __pyx_mdef_10sqlalchemy_11cyextension_4util_15prefix_anon_map_5__setstate_cython__ __pyx_int_228825662 _Py_Dealloc PyUnicode_1BYTE_KIND __pyx_ptype_10sqlalchemy_11cyextension_4util_prefix_anon_map func_annotations __pyx_int_222419149 PyLongObject __Pyx_CreateCodeObjectForTraceback __Pyx_PyLong_From_int __pyx_v_state default_value nb_index tp_richcompare __pyx_mdef_10sqlalchemy_11cyextension_4util_14cache_anon_map_3get_anon wstr __Pyx_get_runtime_version m_free __Pyx_NewRef __Pyx_PyObject_CallMethod0 __pyx_k_AV1 c_line PyThreadState __pyx_k_Mapping nb_remainder __Pyx_CyFunction_Vectorcall_CheckArgs visitproc PyMethod_Type __pyx_ptype_10sqlalchemy_11cyextension_4util_cache_anon_map __pyx_mstate __va_list_tag module_name _Py_TrueStruct __pyx_k_anonymous_counter __Pyx_PyObject_Call PyTupleObject allow_none __pyx_find_code_object PyVectorcall_NARGS PyCompactUnicodeObject co_weakreflist num_max was_sq_slice PyMemberDef intern interp __Pyx_PyObject_CallOneArg __Pyx_HasAttr ob_type __pyx_k_module __pyx_dict_version __pyx_k_A_a_1A_7_Q_9AYa_l_1_5 tp_free PyObject_IsSubclass is_safe_type PyExc_RuntimeWarning utf8_length get_item_ref_result PyType_FromModuleAndSpec co_opcache co_opcache_size PyModuleDef PyVarObject __pyx_L5_argtuple_error co_nlocals __Pyx_CyFunction_get_kwdefaults PyType_Slot PyImport_GetModule PyErr_Format __Pyx_PyUnicode_BuildFromAscii nb_and co_cell2arg _PyUnicode_FastCopyCharacters __pyx_k_exc _err_stackitem format_char PyDictObject kwnames ma_keys _PyUnicode_Ready tp_call async_exc __Pyx_CyFunction_get_name_locked __pyx_v___pyx_type gilstate_counter f_localsplus __pyx_k_pyx_checksum ob_item __pyx_pw_10sqlalchemy_11cyextension_4util_15prefix_anon_map_3__reduce_cython__ PyObject_GC_UnTrack tp_str _PyCFunctionFastWithKeywords PyUnicode_Decode was_sq_ass_slice PyExc_RuntimeError co_filename __Pyx_PyObject_IsTrue __Pyx_CyFunction_get_qualname PyDict_Update ternaryfunc __Pyx_RejectKeywords __Pyx_MatchKeywordArg __pyx_pw_10sqlalchemy_11cyextension_4util_15prefix_anon_map_1__missing__ ob_base PyTypeObject __pyx_L4_argument_unpacking_done PyTraceBack_Type __pyx_mstate_global_static __pyx_CyFunction_methods __pyx_tp_clear_10sqlalchemy_11cyextension_4util_cache_anon_map __pyx_obj_10sqlalchemy_11cyextension_4util_cache_anon_map __pyx_moduledef_slots __pyx_v_ret __pyx_k_mapping_or_list_expected_for_par current_id __Pyx_CyFunction_get_annotations_locked __PYX_GOOD __pyx_pf_10sqlalchemy_11cyextension_4util_4__pyx_unpickle_prefix_anon_map PyModule_GetName __pyx_k_set_name __pyx_pf_10sqlalchemy_11cyextension_4util_14cache_anon_map___init__ __pyx_dict_cached_value __Pyx_PyVectorcall_FastCallDict sq_contains __Pyx_CyFunction_set_name m_module padding __gnuc_va_list marker __Pyx_PyDict_GetItemStr __pyx_k_pickle tp_setattr PySequence_Contains __pyx_pw_10sqlalchemy_11cyextension_4util_3_distill_raw_params __Pyx_ErrRestoreInState __pyx_string_tab __pyx_f_10sqlalchemy_11cyextension_4util___pyx_unpickle_cache_anon_map__set_state __Pyx_PyObject_FastCallDict PyObject_GetAttrString richcmpfunc unsigned char mp_ass_subscript __pyx_k_add_note is_method __Pyx_InitConstants ptraceback __pyx_k_self PyModule_NewObject __pyx_pf_10sqlalchemy_11cyextension_4util_14cache_anon_map_8__setstate_cython__ __pyx_k_reduce_cython __pyx_pymod_exec_util tp_dictoffset PyObject_GC_Track PyNumberMethods code_line PyMethodDef tp_finalize __pyx_L6_skip __pyx_kwvalues target PyBytes_FromStringAndSize __pyx_pw_10sqlalchemy_11cyextension_4util_14cache_anon_map_3get_anon m_init function_name exc_type1 exc_type2 mp_subscript __pyx_string_tab_encodings f_gen tp_clear remaining func_globals __Pyx_CyFunction_get_kwdefaults_locked uint64_t __pyx_int_61626896 PyObject_GenericGetAttr __pyx_k_use_setstate _py_tmp num_min PyModuleDef_Base PyObject_VectorcallMethod use_tracing __pyx_b PyList_Type __pyx_f __pyx_pw_10sqlalchemy_11cyextension_4util_5__pyx_unpickle_prefix_anon_map __pyx_m nb_bool __pyx_v___pyx_result f_trace_opcodes __pyx_r __Pyx_cached_runtime_version keys_are_strings __pyx_pw_10sqlalchemy_11cyextension_4util_14cache_anon_map_9__setstate_cython__ co_freevars PyObject_Hash tp_init cyfunc __pyx_moduledef objobjargproc ob_size PyUnicode_2BYTE_KIND result_udata __pyx_k_dict_2 __pyx_v_derived PyInterpreterState_GetID chars tp_dict _PyThreadState_UncheckedGet tp_as_mapping __pyx_L6_bool_binop_done setattrfunc __Pyx_CyFunction_get_dict __pyx_k_asyncio_coroutines vret first_kw_arg method_name __Pyx__CyFunction_dealloc __Pyx_TypeName GNU C17 10.2.1 20210130 (Red Hat 10.2.1-11) -mtune=generic -march=x86-64 -g -O3 -fwrapv -fPIC PyObject_Str PyNumber_InPlaceAdd binaryfunc type_obj_name __pyx_k_pyx_unpickle_prefix_anon_map __Pyx_CodeObjectCacheEntry last_one_off b_name __Pyx_CodeObjectCache PyUnicode_AsUTF8 __pyx_k_id __pyx_k_prefix_anon_map___setstate_cytho tmp_value m_doc new_max obj_type_name __pyx_empty_unicode bf_getbuffer co_zombieframe line_table result_uval vectorcallfunc getiterfunc ssizeargfunc value_count PyMem_Realloc __pyx_pw_10sqlalchemy_11cyextension_4util_14cache_anon_map_7__reduce_cython__ exc_state __pyx_codeobj_tab raise_neg_overflow uint8_t __pyx_v_item descrsetfunc __pyx_CyFunction_init result_ukind tmp_type PyImport_ImportModuleLevelObject f_lasti __pyx_methods_10sqlalchemy_11cyextension_4util_cache_anon_map __pyx_CyFunctionType_spec __pyx_k_sqlalchemy_cyextension_util descrgetfunc index_found co_kwonlyargcount nb_inplace_add nb_reserved kw_name on_delete co_code __Pyx_PyType_HasMultipleInheritance __builtin_memset __pyx_k_enable PyThreadState_Get __Pyx_PyObject_CallNoArg __pyx_L3_bool_binop_done m_index PyErr_WarnEx PyUnicode_Type PyType_Modified reprfunc py_line __pyx_code_cache __pyx_type_10sqlalchemy_11cyextension_4util_cache_anon_map __pyx_CyFunction_members __Pyx_PyLong_As_long __Pyx_CyFunction_get_globals moddict __Pyx_PyUnicode_Unicode __pyx_empty_bytes curexc_traceback Py_UCS1 __Pyx_modinit_type_import_code PyLong_FromSsize_t /project first_line PyType_Spec exact __pyx_k_None PyTryBlock tuple_dedup_map _PyObject_GetDictPtr pvalue __Pyx_validate_extern_base DIGIT_PAIRS_10 __pyx_k_missing PyExc_NameError MAJOR_MINOR boundscheck overflowed Py_GetVersion PyDict_Type __pyx_type_10sqlalchemy_11cyextension_4util_prefix_anon_map __Pyx_PyErr_GivenExceptionMatchesTuple Py_hash_t __pyx_lineno PyUnicode_Split _Py_XDECREF ignore_unknown_kwargs PyFrame_New PyObject line_table_length __pyx_CyFunctionObject nb_xor __pyx_k_params __pyx_k_update nb_negative __Pyx_copy_spec_to_module PyUnicode_InternFromString kwds2 PyObject_SetAttr PyUnicode_New __Pyx_GetItemInt_Fast fixed_cause __pyx_k_isenabled __Pyx_CyFunction_Vectorcall_FASTCALL_KEYWORDS __pyx_L1_error slot __pyx_pf_10sqlalchemy_11cyextension_4util_6__pyx_unpickle_cache_anon_map __ssize_t is_true _longobject ptype PyUnicode_Concat PyType_HasFeature __pyx_k_prefix_anon_map___missing co_flags __pyx__insert_code_object code_obj __pyx_mdef_10sqlalchemy_11cyextension_4util_14cache_anon_map_5__missing__ __pyx_k__2 __pyx_k__3 __pyx_k__4 PyTuple_GetSlice PyDictKeysObject __pyx_insert_code_object __pyx_k_val m_traverse kwd_pos_args __pyx_k_collections_abc __Pyx_CyFunction_set_doc __pyx_k_key recursion_critical __pyx_k_name _Py_INCREF co_opcache_map __Pyx_PyImport_AddModuleRef __Pyx_GetItemInt_List_Fast co_name __Pyx_CyFunction_get_doc __Pyx_PyErr_ExceptionMatchesTuple PyCMethod __pyx_clineno PyBufferProcs _PyDict_GetItem_KnownHash PyUnicode_WCHAR_KIND co_stacksize ml_flags is_list tp_new feature PyDict_DelItem __pyx_v___pyx_PickleError allow_newer __pyx_CyFunctionType_slots f_executing varnames_tuple __Pyx_PyType_Ready __Pyx_CyFunction_set_qualname PyModuleDef_Slot num_expected nb_inplace_true_divide __pyx_t_6 __pyx_k_pyx_state _PyErr_StackItem full_name destructor PyCFunction im_weakreflist __pyx_k_setstate __pyx_k_pyx_type __pyx_mdef_10sqlalchemy_11cyextension_4util_14cache_anon_map_7__reduce_cython__ PyObject_CallObject __Pyx_check_binary_version f_trace PyObject_GetItem PyObject_GC_Del __pyx_k_wc_q_1HA_1A_q_1_q_c_q PyImport_Import PyUnicodeObject __pyx_pw_10sqlalchemy_11cyextension_4util_1_distill_params_20 __Pyx_ErrFetchInState __pyx_tp_traverse_10sqlalchemy_11cyextension_4util_prefix_anon_map tp_del __pyx_k_distill_params_20 lib/sqlalchemy/cyextension/util.c encoding __Pyx_PyDict_SetDefault __pyx_k_func extracted __Pyx_InitCachedConstants fp_offset tp_name __Pyx_PyLong_As_int gp_offset __Pyx_CyFunction_get_dict_locked __Pyx_IsSubtype co_posonlyargcount __Pyx_CyFunction_get_name is_subclass c_profilefunc DIGITS_HEX tp_as_sequence __pyx_mdef_10sqlalchemy_11cyextension_4util_15prefix_anon_map_3__reduce_cython__ tmp_tb __pyx_mdef_10sqlalchemy_11cyextension_4util_14cache_anon_map_9__setstate_cython__ __pyx_mdef_10sqlalchemy_11cyextension_4util_3_distill_raw_params tp_as_buffer __pyx_v___pyx_checksum func_dict _PyDict_Pop PyDict_Contains nb_inplace_and __pyx_v_obj __pyx_CyFunctionType __pyx_filename __pyx__function __pyx_v_value short unsigned int __Pyx_PyUnicode_From_int b_dictoffset async_gen_firstiter start f_blockstack __pyx_k_pyx_unpickle_cache_anon_map PyMem_Free __pyx_pf_10sqlalchemy_11cyextension_4util_15prefix_anon_map_4__setstate_cython__ __Pyx_Raise __pyx_L3 __Pyx_RejectUnknownKeyword num_posonly_args tp_alloc __pyx_k_cache_anon_map abi_module_dict __pyx_k_cache_anon_map___setstate_cython suboffsets compact __Pyx_PyObject_CallMethO PyDict_Size __Pyx_PyUnicode_FromOrdinal_Padded trash_delete_nesting im_self wchar_t arg_passed_twice m_clear __Pyx_CyFunction_get_is_coroutine_value PySequenceMethods PyErr_Clear __Pyx_PyObject_GetAttrStr_ClearAttributeError __pyx_v_anonymous_counter PyTuple_Pack PyObject_IsInstance object_reduce modbad __pyx_k_reduce tp_getattro __pyx_pf_10sqlalchemy_11cyextension_4util_14cache_anon_map_2get_anon b_handler allocfunc c_traceobj PyInit_util __pyx_k_cache_anon_map___reduce_cython __pyx_pyargnames __Pyx_fix_up_extension_type_from_spec m_copy __pyx_pw_10sqlalchemy_11cyextension_4util_15prefix_anon_map_5__setstate_cython__ Py_EnterRecursiveCall tp_methods __pyx_k_prefix_anon_map __Pyx_CyFunction_init_defaults __Pyx_CyFunction_New tp_mro ucs2 ucs4 __pyx_args __pyx_k_idself __Pyx_ParseKeywordDictToDict tz_dsttime __pyx_k_pyx_PickleError __Pyx_FetchSharedCythonABIModule __pyx_k_sqlalchemy PyExc_ImportError __pyx_k_getstate __Pyx_ImportFrom __pyx_k_gc __pyx_v___pyx_state __Pyx_init_co_variables __Pyx_CyFunction_get_closure PyUnicode_DecodeUTF8 __Pyx_FetchCommonTypeFromSpec __pyx_k_A_a_V1E_1A_IT_1_r_j_q f_code dictptr PyErr_Fetch main_interpreter_id __Pyx_is_valid_index nb_or ma_values func_qualname format unaryfunc var_count PyCFunctionWithKeywords PyDict_SetItem limit PyCMethodObject __pyx_temp __pyx_cython_runtime __pyx_methods PyUnicode_DecodeLatin1 __Pyx_PyObject_GetAttrStrNoError nb_float __pyx_module_is_main_sqlalchemy__cyextension__util PyExc_SystemError try_unpack __builtin_memcpy traverseproc PyObject_Not context PySequence_Repeat __Pyx_modinit_function_import_code __pyx_mdef_10sqlalchemy_11cyextension_4util_5__pyx_unpickle_prefix_anon_map tp_vectorcall_offset inquiry func_code __pyx_callargs __pyx_int_199836613 uint32_t nb_invert __Pyx_RaiseUnexpectedTypeError f_lineno __Pyx_VerifyCachedType ml_doc __pyx_v_self_dict ml_name __pyx_k_value __pyx_pw_10sqlalchemy_11cyextension_4util_14cache_anon_map_1__init__ py_object_name py_funcname __pyx_base __Pyx_PyLong_As_PY_LONG_LONG num_pos_args __pyx_v__dict __Pyx_RaiseArgtupleInvalid long double padding_char PyObject_SetAttrString clength func_closure abi_module tp_as_number __Pyx_PyMethod_New __pyx_k_derived PyAsyncMethods PyUnicode_FromStringAndSize tp_weaklistoffset __pyx_k_distill_raw_params PyUnicode_4BYTE_KIND __Pyx_MatchKeywordArg_nostr PyDict_SetItemString __pyx_k_cline_in_traceback PyFrameObject ml_meth __Pyx_CyFunction_CallAsMethod PyException_SetCause PyMem_Malloc readonly descr tp_doc getattrofunc __Pyx_InitCachedBuiltins __pyx_k_disable co_varnames __Pyx_ParseKeywordDict __pyx_f_10sqlalchemy_11cyextension_4util___pyx_unpickle_prefix_anon_map__set_state __Pyx_AddTraceback __pyx_pf_10sqlalchemy_11cyextension_4util_14cache_anon_map_6__reduce_cython__ cpos __Pyx_CyFunction_get_code _Py_FalseStruct __pyx_tp_traverse_10sqlalchemy_11cyextension_4util_cache_anon_map __Pyx_InBases __Pyx_GetBuiltinName __pyx_v_use_setstate on_delete_data __pyx_kwds_len tp_weaklist __Pyx_CyFunction_get_is_coroutine bufferinfo uoffset callable __Pyx_PyBool_FromLong instance_class __pyx_pf_10sqlalchemy_11cyextension_4util__distill_params_20 PyErr_Restore newfunc __pyx_v_id_ hashfunc key_hash getattrfunc __pyx_v_params __Pyx_PyVectorcall_Function __Pyx_PyLong_From_PY_LONG_LONG __Pyx_validate_bases_tuple nargsf line_table_bytes code_len __Pyx_InitGlobals __pyx_k_T_G1F_a_vWA_q_q_q_t1G_gQ_t1G_a __Pyx_CyFunction_set_dict __Pyx_MatchKeywordArg_str _Py_IS_TYPE __pyx_pf_10sqlalchemy_11cyextension_4util_2_distill_raw_params more_or_less __pyx_v_10sqlalchemy_11cyextension_4util__Empty_Tuple __pyx_t_1 __pyx_t_2 __pyx_t_3 __pyx_t_4 __pyx_t_5 PyExc_DeprecationWarning __pyx_t_7 __pyx_t_8 __pyx_t_9 __Pyx_CyFunction_traverse digit_pos __Pyx_PySequence_ContainsTF __pyx_v_idself wstr_length fromlist PyErr_NoMemory curexc_type shape __pyx_k_mapping_or_sequence_expected_for new_cached_type __pyx_cfilenm tp_hash __builtin_memcmp PyUnicode_FromString ndim ssizeobjargproc PyDict_Next __Pyx_PyDict_ContainsTF tp_vectorcall empty_dict __pyx_pymod_create __Pyx__ArgTypeTest tp_version_tag __pyx_k_wc_q_1HF_Zq_1A_q_1HF_Zq_q_c_q PyOS_snprintf c_tracefunc func_name __pyx_mdef_10sqlalchemy_11cyextension_4util_7__pyx_unpickle_cache_anon_map py_frame PyUnicode_Format __Pyx_compact_upylong getbufferproc __pyx_k_Incompatible_checksums_0x_x_vs_0_2 PyDict_New __pyx_k_qualname py_code __pyx_k_cache_anon_map_get_anon __pyx_self max_count __pyx_L7_cleaned_up setter previous_item am_await Py_UCS2 Py_UCS4 __pyx_k_new PyList_New f_back stringtab_initialized PyModuleDef_Init __PYX_BAD tp_members arg0 __Pyx_PyUnicode_Join tp_traverse _PyObject_GC_New mp_length ready kw_size __Pyx_ParseKeywords visit __pyx_k_setstate_cython __Pyx__GetModuleGlobalName PyImport_AddModule __Pyx_CyOrPyCFunction_GET_SELF __Pyx_setup_reduce_is_named am_aiter __pyx_f_10sqlalchemy_11cyextension_4util__check_item argc PyUnicode_FromFormat nb_inplace_xor tp_subclasses nb_inplace_power __Pyx_CyFunction_get_defaults_locked __pyx_bisect_code_objects co_names __Pyx_ParseKeywordsTuple const_zero tp_setattro freefunc data1 data2 __pyx_k_state co_opcache_flag nb_multiply num_found __Pyx_GetAttr3 __Pyx_PyDict_GetItemRef m_base __pyx_pf_10sqlalchemy_11cyextension_4util_14cache_anon_map_4__missing__ nb_true_divide latin1 tp_getset f_locals __Pyx_ValidateDuplicatePosArgs PyLong_Type PyArg_ValidateKeywordArguments __pyx_f_10sqlalchemy_11cyextension_4util__mapping_or_tuple __pyx_builtin_id __pyx_k_obj tp_iternext __pyx_methods_10sqlalchemy_11cyextension_4util_prefix_anon_map __Pyx_PyDict_GetItem sq_length __pyx_umethod_PyDict_Type_pop __Pyx_CyFunction_Call PyCode_NewEmpty width invalid_keyword tp_descr_get tp_iter __pyx_k_A_a_s_4q_Kq_q cleanup __Pyx_CyFunction_raise_argument_count_error __Pyx_modinit_variable_export_code nb_inplace_floor_divide __pyx_int_238750788 __Pyx_CyFunction_CallMethod __Pyx_PyCode_New_function_description PyTraceBack_Here strides PyExc_OverflowError setNameResult result_type_name m_ml tp_base nb_rshift f_trace_lines __pyx_int_1 __pyx_empty_tuple co_consts f_globals __pyx_CyFunction_getsets PyASCIIObject exc_info bf_releasebuffer __Pyx_GetAttr3Default async_gen_finalizer __Pyx_GetItemInt_Tuple_Fast long long unsigned int recursion_depth __pyx_v_self nb_inplace_multiply releasebufferproc PyUnicode_FromOrdinal __pyx_k_is_coroutine nb_inplace_remainder __pyx_L0 Py_LeaveRecursiveCall thread_id __pyx_k_test PyLong_AsLong empty_list __pyx_k_hk_A_1_qqsst_7_0_1B_PQ_1 __pyx_k_dict m_slots __Pyx_RaiseDoubleKeywordsError defaults_tuple PyCodeObject PyErr_ExceptionMatches dpos nb_absolute object_getstate module_dot __pyx_k_List_argument_must_consist_only PyListObject new_args coroutine_origin_tracking_depth im_func internal rt_version trash_delete_later PyObject_VectorcallDict __pyx_L3_error __Pyx_CyFunction_Vectorcall_O __pyx_k_self_dict __Pyx_PyErr_ExceptionMatchesInState __pyx_L4_bool_binop_done __pyx_kwds f_iblock nb_inplace_or __Pyx_inner_PyErr_GivenExceptionMatches2 __Pyx_PyObject_GetAttrStr max_char m_methods name_attr PyObject_ClearWeakRefs m_size newargs __pyx_tp_clear_10sqlalchemy_11cyextension_4util_prefix_anon_map timezone __Pyx_CyFunction_set_kwdefaults tp_repr PyExc_AttributeError tp_cache PyObject_GetAttr Py_ssize_t nb_inplace_rshift py_status defaults_getter __Pyx_CyFunction_get_annotations __Pyx_StringTabEntry c_profileobj __Pyx__SetItemOnTypeDict __Pyx_CyFunction_get_doc_locked nb_positive long long int _Py_NoneStruct stackcheck_counter type_obj num_kwonly_args __pyx_v_val PyMappingMethods to_name __pyx_mdef_10sqlalchemy_11cyextension_4util_15prefix_anon_map_1__missing__ _PyType_Check __Pyx_PyDict_GetItemDefault f_builtins __pyx_v_key __Pyx_CyFunction_Init __Pyx_CyFunction_Vectorcall_NOARGS __Pyx_modinit_variable_import_code PyObject_RichCompareBool _PyType_Lookup modules encoding_names factor __pyx_k_Incompatible_checksums_0x_x_vs_0 PyUnicode_Kind __pyx_tstate __pyx_k_main PyCFunction_Type allocated tp_flags __pyx_mdef_10sqlalchemy_11cyextension_4util_1_distill_params_20 __Pyx_CyFunction_dealloc __Pyx_Import PyImport_GetModuleDict _Py_XINCREF wraparound __Pyx_CyFunction_repr use_cline_obj ob_digit interned __pyx_k_PickleError nb_subtract b_level __Pyx_CLineForTraceback __Pyx_modinit_type_init_code __Pyx_PyNumber_Long co_extra __Pyx_compact_pylong sdigit PyObject_CallMethodObjArgs mm_class __Pyx_InitStrings __pyx_mstatetype __Pyx_PyVectorcall_FastCallDict_kw __Pyx_IsAnySubtype2 __pyx_k_QfA PyErr_SetString result_ulength PyTuple_GetItem PyCFunctionObject module_name_str meth_found __Pyx_CyFunction_reduce varnames_tuple_dedup from_list iternextfunc __Pyx_CachedCFunction co_lnotab nb_int kind_shift gc_was_enabled PyObject_HasAttr c_code_bytes __pyx_k_hk_A_1_kkmmn_1_7_1_2DNRS_1 tp_descr_set owned_instance Py_buffer __Pyx_CyFunction_raise_type_error func_doc short int PyCode_NewWithPosOnlyArgs num_kwargs __Pyx_setup_reduce prev PyErr_Occurred nb_inplace_matrix_multiply tp_basicsize prepend_sign nb_inplace_subtract __Pyx_PyCode_New co_cellvars __Pyx_PyLong_From_long __Pyx_PyNumber_LongWrongResultType extra_info __pyx_pw_10sqlalchemy_11cyextension_4util_14cache_anon_map_5__missing__ nb_divmod tz_minuteswest __pyx_tuple objobjproc __pyx_pyinit_module is_unsigned PyInterpreterState 0� `� U`� f� Xf� r� Ur� � X 0� `� T`� f� Yf� r� Tr� � Y 4� G� 0�G� `� Pf� r� Pr� � U 4� � Z }� � Q }� }� Q }� }� @K$� }� }� q }� }� q#� �� �� @J$� �� �� Q �� �� q� �� � Q �� � 0� �� � X �� � Q �� � X �� � R �� �� 0��� ʁ P �� ʁ T � P � =� U=� �� ]�� �� �U��� �� ]�� �� �U��� �� ]�� g� �U�g� �� ]�� F� �U�F� I� ]I� �� �U��� Ǟ ]Ǟ � �U�� E� ]E� d� �U�d� � ] � =� T=� � \� <� �T�<� �� \�� �� \�� :� �T�:� �� \g� ߛ \t� �� \F� �� �T��� � \� � �T�� I� \�� Ǟ \� E� \d� �� \�� :� �T�:� G� \G� � �T� � =� Q=� � S� �� �Q��� �� S�� �� �Q��� �� S�� � �Q�� I� SI� c� �Q�c� � S � =� R=� �� V�� �� �R��� �� V�� �� �R��� �� V�� g� �R�g� � V� t� �R�t� � V� F� �R�F� c� Vc� �� �R��� Ǟ VǞ � �R�� E� VE� d� �R�d� � V � �� 0��� � \�� �� 0��� �� \�� :� 0��� g� \� t� \�� �� 0�� F� \F� � 0�c� �� \�� Ǟ 0�Ǟ � \� E� 0�E� d� \d� � 0� � �� 0��� ɘ Pɘ � V�� �� 0��� � 0� H� U� PU� � ^�� �� ^�� � ^ L� P� PP� g� ��s� w� Pw� �� ��� F� ��%� )� P)� I� ��V� �� ��Ǟ � ��E� d� �� Z� ^� P^� g� ���� �� P�� F� ��3� 7� P7� �� ��Ǟ � ��E� d� �� k� t� Pt� g� ���� �� P�� F� ��D� I� PI� �� ��Ǟ � ��E� d� �� H� � \�� � �T�� � 0�� :� 0�F� S� \�� � \� � �T��� Ǟ \� E� \d� �� \�� :� �T�:� G� \G� � �T� H� U� PU� <� ^�� :� ^F� � ^�� Ǟ ^� E� ^d� � ^ �� X � ��� :� 0��� Ǟ X i� m� Pm� � ���� :� ��F� \� ���� � ���� Ǟ ��� E� ��d� � �� w� {� P{� � ���� :� ��F� X� ���� � ���� Ǟ ��� E� ��d� � �� w� <� _�� :� _F� � _�� Ǟ _� E� _d� � _ � �� P�� �� R�� �� P�� �� R�� �� R�� Ǟ ��d� }� ��}� �� R:� >� R Q� w� �L Q� w� ��L Q� w� ��L Q� U� PU� w� ^ �� �� T �� �� U �� �� Pd� m� Pm� }� �� �� �� X �� �� X � � X5� :� 0�F� M� X � � XF� M� X � <� _S� �� _ � � ��S� X� �� � � ��S� \� �� � <� ^S� �� ^ �� � US� `� U �� � ZS� `� Z`� o� �� � � XS� `� X`� o� �� � � US� `� U � � US� `� U � -� Zo� z� Z #� -� Zo� z� Z -� <� X�� �� X 2� <� X�� �� X Ɲ ϝ Pϝ ؝ U؝ � ��� 1� �� �� T}� �� T:� >� T �� U}� �� U:� >� U �� u}� �� u:� >� u }� �� T:� >� T }� �� U:� >� U �� �� U �� �� Q�� ���� �� P�� :� QG� �� Q �� �� Q�� �� ���� :� QG� ]� Qo� �� Q �� �� X�� :� XG� ]� Xo� �� X �� �� \�� :� \G� ]� q� o� � \ �� �� Xҟ :� XG� ]� X �� �� \ҟ :� \G� ]� q� �� �� Xҟ :� XG� ]� X �� �� \ҟ :� \G� ]� q� ҟ ҟ \ ҟ ҟ @K$� ҟ ҟ | ҟ ҟ |#� � � @J$� � � \ � � |� � � X � � @K$� � � x � � P �� �� @J$� �� �� X �� �� x� � :� XG� ]� X � :� 0�G� ]� 0� � :� \G� ]� q� � :� XG� ]� X � :� \G� ]� q� � :� RG� ]� R � !� 0�!� :� P � :� T G� ]� \ �� ǟ @F$� �� ǟ x ǟ ǟ P o� �� X o� � \ s� w� 0�w� �� P�� �� R�� � ��� � R s� �� Z �� �� T �� �� \ � 0�� � 0� � Q� � Q ƙ � U� � U Ι � X� � X� �� �� ҙ � \� � \ ޙ � U� � U � � U� � U � �� X�� �� X � �� X�� �� X �� � \ � � \ }� �� T:� >� T }� �� U:� >� U }� �� u:� >� u �� � U� 5� U L� k� Sk� �� _ � �� _ L� �� ؓ � � �� ؓ �:� F� ؓ �� �� ؓ �Ǟ � ؓ �E� d� ؓ � �� �� \ L� �� ؓ � � �� ؓ � L� k� Sk� �� _ � �� _ �� �� \ {� �� P _� k� Sk� {� _ � �� _ _� {� Z � �� Z _� {� T � �� T _� p� 0� � G� 0�G� �� R _� p� 0� � G� 0�G� a� Pa� p� 0�p� �� P _� e� z�e� {� U � #� z�#� �� U�� �� P �� �� \ ʘ ٘ \�� �� \ ʘ ٘ \�� �� \ ٘ � V ٘ � V :� k� �xL g� �� �xL � D� �xL :� k� �cL g� �� �cL � D� �cL :� k� �NL g� �� �NL � D� �NL :� k� ^g� �� ^� D� ^ k� �� V�� � Vt� �� VD� I� V k� �� S�� � St� �� SD� I� _ k� t� \t� �� 0��� ߛ \t� �� \D� I� 0� k� �� ]�� �� ]�� ě �U�ě ֛ Pt� �� PD� I� ] k� �� 0��� �� P�� ߛ 0�ߛ � P� � \t� �� 0�D� I� 0� k� �� 0��� �� 0��� �� P�� � ]t� �� ]D� I� 0� �� �� 0�ߛ � ] ߛ � ] t� �� ] t� �� ] �� � ��c� }� ��}� �� P�� �� �� �� � ��c� �� �� �� � ��c� �� �� �� � ^c� �� ^ �� �� U}� �� U �� � ]c� �� ] �� � Vc� �� V �� �� U}� �� U �� �� U}� �� U �� К ]p� }� ] Ś К ]p� }� ] К � Vc� p� V ՚ � Vc� p� V � g� \� t� \� F� \Ǟ � \E� d� \ � g� _� t� _� F� _Ǟ � _E� d� _ � g� ؓ �� t� ؓ �� F� ؓ �Ǟ � ؓ �E� d� ؓ � � g� ؓ �� t� ؓ �� F� ؓ �Ǟ � ؓ �E� d� ؓ � � g� \� t� \� F� \Ǟ � \E� d� \ � g� _� t� _� F� _Ǟ � _E� d� _ � '� VE� d� V @� J� RJ� V� r�V� Z� R3� F� Q � � Q � g� U� 3� U� � U� F� PǞ ̞ U̞ О � ў � P � � UE� H� UH� ^� � �� g� _� � _� � _ �� g� Q� � Q� � Q �� g� U� � U� � U �� +� 0�+� g� R� �� 0�� � 0� �� +� 0�+� B� VB� R� 0�R� g� V� �� 0�� � 0� � +� T+� b� Zb� g� V� �� T�� � Z� � T j� t� z � F� ] �� � p H� ^� U K� P� z P� ^� U �� �� ��V� c� S �� �� ��V� c� S �� Ĝ ��I� V� S �� Ĝ ��I� V� S Ĝ � �� Ҝ � �� Ѕ � U� � �U�� &� U&� (� �U�(� O� UO� ]� �U� Ѕ �� T�� � Y� � �T�� � T� '� Y'� (� �T#�(� L� TL� U� YU� ]� �T� Ѕ ۅ Qۅ ]� �Q� Ѕ � R� � X� � �R�� '� X'� (� �R�(� U� XU� ]� �R� Ѕ � U� � �U�� &� U&� (� �U�(� O� UO� ]� �U� Ѕ � u8� � �U#8� &� u8&� '� �U#8(� O� u8O� U� �U#8 � � Q� � R� '� R(� E� R � � Z� '� Z � �� q�� � P� #� q#� &� u#&� '� �U##(� >� q>� O� u#O� U� �U## Ѕ ۅ Qۅ � �Q� � � 0�� � 0�(� V� 0� � � R� � R(� E� R � � U� � U(� O� UO� V� �U� � � 0�� � 0�(� V� 0� (� V� 1 � (� O� UO� V� �U� (� >� q >� O� uO� U� �U# `� {� U{� � �U�� �� U�� �� �U��� �� U�� Ņ �U� `� ~� T~� � �T�� �� T�� �� �T#��� �� T�� Ņ �T� `� o� Qo� Ņ �Q� `� ~� R~� � �R�� �� R�� �� �R��� �� R�� Ņ �R� `� {� U{� � �U�� �� U�� �� �U��� �� U�� Ņ �U� o� ~� Q� �� Q�� �� q��� �� Q�� �� Q {� ~� U�� �� U o� ~� x� �� x�� �� x `� o� Q o� w� 0�� �� 0��� �� 0� o� w� Q� �� Q�� �� Q o� w� U� �� U�� �� U�� �� �U� o� w� 0�� �� 0��� �� 0� �� �� 1 � �� �� U�� �� �U� �� �� x v $v U$v 7v �U�7v Qv UQv �v �U��v �v U�v �v �U��v �v U v 1v T7v {v T�v �v T�v �v �T��v �v T v v Qv �v �Q� v 6v R6v 7v �R�7v tv Rtv �v �R��v �v R�v �v �R��v �v R�v �v �R��v �v R v $v U$v 7v �U�7v Qv UQv �v �U��v �v U�v �v �U��v �v U v $v �Q���������7v Yv �Q����������v �v �Q��������� $v 6v UQv ~v U v 6v y7v �v y�v �v y�v �v y v v Q v v R7v Nv R�v �v R�v �v �R��v �v R�v �v �R��v �v R v v �Q���������7v Nv �Q����������v �v �Q����������v �v �Q��������� v v U7v Nv U�v �v U�v �v �U��v �v U v v 0�7v Ev 0�Ev Nv 1��v �v 0��v �v 0��v �v 1� �v �v �Q��������� �v �v R �v �v U �v �v d0 � �v �v U �v �v y �v �v 1 � �v �v U �v �v y `v �v +0 � `v �v �U� `v �v y `� �� U�� �� �U��� �� U�� ܆ �U�܆ � U� � �U� � -� U `� �� T�� �� T�� �� t�܆ �� T�� � �T� � -� T `� s� Qs� -� �Q� `� �� R�� �� �R��� Ć RĆ ܆ �R�܆ � R� � �R� � � R� � �R�� -� R `� �� U�� �� �U��� �� U�� ܆ �U�܆ � U� � �U� � -� U s� �� �Q����������� �� �Q����������� �� q��� �� Q܆ -� �Q��������� �� �� U�� Ά U s� �� y�� Ԇ y܆ � y � -� y `� s� Q s� �� R�� �� R܆ � R� � �R� � � R� � �R�� -� R s� �� �Q����������� �� �Q���������܆ � �Q��������� � -� �Q��������� s� �� U�� �� U܆ � U� � �U� � -� U s� �� 0��� �� 0��� �� 1�܆ � 0� � � 0�� -� 1� � � �Q��������� � � R � � U � � d0 � � � U � � y � � 1 � � � U � � y �� Ն 0 � �� Ն �U� �� Ԇ y 0m mm Umm qm Sqm um �U�um �m S�m �m �U��m n Sn n �U�n �n S 0m 7m T7m rm Vrm tm Utm um �T�um �m V�m �m U�m �m �T��m n Vn n �T�n �n V 0m pm Qpm tm Ttm um �Q�um �m Q�m �m �Q��m �m Q�m �m �Q��m �m Q�m n �Q�n %n Q%n :n �X:n Pn QPn �n �X�n �n Q�n �n �X�n �n �Q� 0m tm Rtm um �R�um �m R�m �m �R��m �m R�m �m �R��m �m R�m n �R�n %n R%n :n �R�:n Pn RPn �n �R��n �n R�n �n �R� 0m mm Umm qm Sqm um �U�um �m S�m �m �U��m n Sn n �U�n �n S Gm tm Yum �m Y�m �m Y�m �m Yn %n Y%n :n �P:n Pn YPn �n �P�n �n Y�n �n �P Gm Jm pJm Mm PMm mm u#mm qm s#qm tm �U##um �m s#�m �m s#�m �m s#n %n s#:n Pn s#�n �n s# �m �m X�m �m X�n �n X �m �m t �m �m X �m �m 0 � �m �m S �m �m s �n �n X �n �n S �n �n s cn �n d0 � cn �n S cn �n s �o �o U�o �o Q�o �o �U� �t �t U�t u Vu u Uu u �U� �t u Vu u Uu u �U� pr xr Uxr �s S�s �s �U��s t St t �U� t �t S xr �r U�t �t U �r �r U�t �t U �r �r U�t �t U �r �r U�t �t U �r �r U�t �t U �r �r U�t �t U �r �r U�t �t U �r �r U�t �t U �r �r U�t �t U �r �r U�t �t U �r s Uzt �t U s s Uzt �t U s 1s Ujt tt U 's 1s Ujt tt U 5s Ls UZt dt U Bs Ls UZt dt U Ps gs UJt Tt U Xs gs UJt Tt U ]s gs UJt Tt U ns �s U:t Dt U ~s �s U:t Dt U �s �s U't 4t U �s �s U't 4t U �s �s Ut $t U �s �s Ut $t U �s �s U t t U �s �s U t t U �s t U �s �s U�s t U �l �l U�l �l �h �l �l T�l �l �T� �l �l P�l �l P �l �l U�l �l U�l �l �h �l �l P�l �l P�l �l P �l �l P�l �l P �q �q U�q �q �U��q �q U�q r S �q �q T�q �q �T��q �q T�q r �T�r r T �q �q U�q �q �U��q �q U�q r S �q �q \�q �q P�q �q \r r s�r r \r r s� �q �q \ �q �q S �q r 0� �q �q P�q �q U �q �q P �q �q \ �q �q U � � U� � �U�� � U� a� S � � T� � �T�� � T� T� �T�T� a� T � � U� � �U�� � U� a� S � � \� � P� %� \R� T� s�T� _� \_� a� s� � �� \ � K� S � T� 0� � )� P)� J� U 0� 5� \ <� @� P @� J� U �l �l P�l �l P �l �l P�l �l P tl xl P �l m U m %m �h �l m T m %m �T� �l �l P m m P �l �l U�l m U m m �h �l �l u� m m �h#@ o +o U+o >o S>o ?o �U� o /o T/o ?o �T� o o 0� o o P o =o 0�=o =o P o o U o +o U+o =o S o o u� 9o =o s� r Gr UGr Sr �U�Sr ar U r %r T%r Kr TSr _r T_r ar �T� r Kr QKr Sr �Q�Sr ar Q -r Kr X 1r <r X?r Kr X 6r <r X?r Kr X %r -r T @o \o U\o to Sto uo �U�uo �o S�o �o �U� @o eo Teo uo �T�uo �o T Mo No Pso so P @o Mo UNo \o U\o so Suo �o S�o �o �U� Io Mo u� oo so s� �n �n U�n �n �U��n o U �n �n T�n �n �T��n o T �n �n Q�n �n �Q��n o Q �n o U �n o U fU �U U�U YX ^YX \X �U� fU yV 0�yV �V P�V �V 0��V �V P�V �V 0��V W ]W %W P5W 7W 0�7W ;W P;W TW ]TW |W 0��W �W ���W �W ]�W �W 0�+X JX ] fU V 0�V V PV _V VgV �V VTW hW 0�hW rW PrW wW V|W �W V�W �W 0� fU �U 0��U �U 0��U �U P fU �U 0��U �U P�U �U 0��U �U P�U V STW fW ShW pW S�W �W S fU V 0� V +V P+V DV SDV RV PRV TW STW rW 0�rW |W P|W �W S�W �W 0�+X JX S fU �U 0��U �U P�U TW ��hW �W ���W �W P+X JX �� fU =V 0�=V DV PDV gV 0�gV xV PxV �V _�V �V P�V TW _TW |W 0�|W �W _�W �W 0�+X JX _ fU �V 0��V �V P�V TW VTW �W 0��W �W V�W �W 0�+X <X P<X JX V fU �V 0��V W PW ;W \;W DW PDW TW \TW �W 0��W �W \�W �W 0�+X JX 0� fU �U 0��U �U P�U �U P�U �U S �W �W ~ �V �V � �V �V ^�V �V ^ �V �V P�V �V ]�V �V P �V �V ~� W %W P� W 5W ^7W 7W ^ )W 4W P4W 5W ]7W 7W P W %W ~� �W �W S �W �W S �W �W ���W �W �� �W �W �� �W X _ �W X _ X X V X X V X )X \ X )X \ U !U U!U fU �U� U U T U *U \*U 9U �T�9U LU \LU fU �T� /U 9U 0�LU PU PPU ^U \ %U *U P*U 9U V9U HU PHU cU V /U 9U VPU ^U V PU ^U V �F �F U�F ZG ]ZG ]G �U� �F �F T�F \G ^\G ]G �T� �F �F Q�F VG VVG ]G �Q� G G P G QG \ �F �F u� <G JG PMG QG P AG JG P �R �R U�R �R ]�R �R U�R �R �U��R �R U�R U ]U U �U� UT pT PpT U \ �R ,S R2S ES RES dS }�jS zS R �S T S4T U S T T P�T �T P�T �T P �S �S P�S +T \4T UT \ oS ~S 0�~S �S P�S �S V�S �S P�S U V �T �T P �T �T P �T �T U �T �T U �T �T U �T �T U �T �T U �T �T U �S �S P�S �S \ �S �S S �S �S \ T T P T +T V �T U V �R �R U�R �R P �R �R p� �R ,S R2S ES RES dS }�jS oS R �R &S U&S ,S }�2S ^S U^S dS }�jS oS U �R ,S }2S dS }jS oS } �R �R 1��R S Q2S [S QjS oS Q �R S T S ,S r2S SS TSS dS }�#jS oS T S S P2S LS PLS [S q 3$}�"#jS oS P S S P2S LS PLS [S q 3$}�"#jS oS P S S pS ,S Q 7S 7S 0�7S LS p�LS [S q 3$}�"##� AS LS pLS dS R tP �P U�P �R S�R �R �U� tP �P T�P �P \�P �P T�P �P \�P �P T�P /R \/R ;R �T�;R �R \�R �R �T��R �R \�R �R �T� tP R 0�R ;R _;R \R 0�\R �R V�R �R 0� tP /R 0�/R 8R P8R ;R \;R �R 0��R �R P�R �R \�R �R 0� �Q �Q 0�R R 1� tP �Q �n� �Q R �n� ;R \R �n� tP �P T�P �P \�P �P T�P �P \�P �P T�P �Q \�Q R \;R \R \ tP �P U�P �Q S�Q R S;R \R S �P �P PeQ tQ 0��Q �Q P�Q �Q V�Q R V;R GR PGR \R V �Q �Q ~ �P �Q ^�Q R ^;R \R ^ �P �P P�P �P P�P �Q _�Q �Q V;R \R _ �P �P 0��P Q ]Q %Q 0�%Q �Q ];R \R ] -Q NQ P 5Q NQ UNQ tQ ��;R \R �� �P %Q 0�%Q �Q ���Q �Q ��;R \R �� �P �P P :Q =Q U =Q eQ \;R ;R \ =Q NQ UNQ eQ ��;R ;R �� ZQ dQ PdQ eQ V;R ;R P eQ tQ �� �Q �Q _ �Q �Q V �Q R _ �Q �Q _ �Q R V ;R >R P >R GR UGR HR �� HR \R _ MR \R _ R /R S R /R _ /R ;R _ \R �R V �R �R V �� Ŋ UŊ Ί VΊ � �U�� � U� � V� � �U� � =� V=� ڋ �U� �� Ŋ TŊ ۊ ]ۊ � �T�� � T� ڋ ] Ɋ Ί P� �� P�� � \� � 0� � {� \{� }� P�� �� S�� �� P�� �� Sы 0� ڋ \ � 0� 0�0� 9� P � =� 0�=� P� PP� }� V�� �� V ڋ V � T� 0�T� c� Pc� }� ^�� �� ^ ڋ ^ � g� 0�g� s� Ps� }� _�� �� _ ڋ P {� }� _�� �� _ {� }� _�� �� _ }� �� ^�� �� ^ }� �� ^�� �� ^ �� �� V�� �� V�� ы V �� �� V�� �� V�� ы V �� Ŋ TŊ Ɋ ]� � T� � ] �� Ŋ UŊ Ɋ V� � U� � V �� �� u 0p 8p U8p �p \�p �p �U��p �p \�p �p �U��p �p \ 0p Xp TXp Zp UZp �p �T��p �p T�p �p �X �p �p R Ip Ip @F$� Ip Ip P Ip Ip p� �p �p U�p �p U \X �X U�X �X �U��X �X U�X 9k �U� \X `] 0�`] ^ 1��^ �g 1�h �h 0��h �j 1��j �j 0��j k 1� \X �X 0��X 'k � � \X �X 0��X �X U�X 'k �U� \X ^ 0��^ �` 0��` �` P�` �` V�` �` 0��` �` P�` �` V�` 9a 0�9a Na PNa �a V�a �a 0��a b Pb (b V(b Ub 0�Ub sb Psb �b V�b �b 0��b �b P�b �b V�b c 0� c =c P=c Tc VTc �c 0��c �c P�c �c V�c �c 0��c d Pd d V d Nd 0�Nd ld Pld �d V�d �d 0��d �d P�d �d V�d e 0�e 6e P6e Me VMe ze 0�ze �e P�e �e V�e �e 0��e �e P�e f Vf f 0�f 7f P7f �g Vh Ni 0�Ni ki Pki �i 0��i �j P�j �j 0��j k P \X ^ 0��^ �` 0��` �` P�` a ^a a 0� a 5a P5a Oa ^Oa aa 0�aa a Pa �a \�a Wf 0�Wf rf Prf �f ^�f �f _�f �f P�f �f \�f �f _�f �g 0��g �g _h ki 0�ki �i P�i �j 0��j k ^ \X ^ 0��^ �g 0��g �g \h �j 0��j k 0� \X ^ 0��^ �g 0��g �g ^h �j 0��j k 0� \X ^ 0��^ �g 0��g �g ]h �j 0��j k 0� �] �] P�] ^ \�^ �^ \ _ -` \>` aa \Wf mf \rf �f \�h i Pi i \1i =i \Ni Zi \ki wi \�j k \ k k \ �a �a U �a �a U C^ \^ U V^ \^ U �X �X U �X �X P �X �X F2 � �X �X P �X �X P �X �X P �X �X O2 � �X �X P �X �X P �X �X P NY NY PNY �Y X NY NY 0�NY �Y S NY NY @D$�NY �Y T NY PY 0�PY eY PkY qY PyY �Y 0� NY NY 0�NY gY QgY kY q�kY �Y Q �Y �Y � ��Y Z � � �Y �Y 0��Y Z 0� �Y �Y P�Y �Y P�Y Z 8� �Y ^ ����^ h ���rh 'k ��� nZ �Z �� nZ ^ � ��^ h � ��h 'k � � nZ �[ �� �h h �� � nZ �[ 0�h h 0� nZ �Z �� nZ �Z 0��Z �Z P�Z �[ \�[ �[ 0�h h \ nZ �Z 0��Z �Z P�Z �Z V�Z �Z P�Z [ V [ ![ P![ H[ ]H[ `[ V`[ v[ ]v[ �[ V�[ �[ U�[ �[ V �Z �Z P�Z �[ Sh h S 5[ H[ V`[ s[ V �Z �Z P�Z �[ ^h h ^ �Z �Z 1� �Z �Z P�Z �[ _h h _ �Z �Z �2 � �Z �Z P �Z �Z P �Z �Z P �Z �Z �� �Z �Z �� �Z �Z ^�Z �Z ^ �Z �Z P�Z �Z S�Z �Z S �Z �Z S �Z �Z ^ �Z �Z �� �Z �Z P [ 5[ 1�s[ v[ 1� [ ![ P![ 5[ ]s[ v[ ] [ 5[ ^s[ v[ ^ [ 5[ Ss[ v[ S %[ -[ P-[ 5[ Vs[ v[ P *[ -[ P-[ 5[ V :[ H[ ] `[ s[ V v[ �[ V�[ �[ U v[ �[ V�[ �[ U �[ �[ \ �[ �[ \ �[ �[ ^ �[ `] � ��j �j � � /\ �\ \ /\ /\ � �/\ �\ ] J\ L\ Pi\ k\ Pp\ r\ P�\ �\ P �] �] � �i 1i � � �] ^ � � _ >_ � � K_ q_ � � q_ !` � �>` l` � � q_ h 0�Ni �j 0��j 'k 0� q_ !` 0�!` !` B�>` l` 0� q_ !` 0�!` !` �; �>` l` 0� q_ !` 0�!` !` ��>` l` 0� �` �` V �` �` V �` a ^ Ba Oa ^ �a �a \ �a �a V �a �a P b (b V |b �b V �b �b V Fc Tc V �c �c V d d V ud �d V �d �d V ?e Me V �e �e V f f V @f Wf V �g �g V �g �g V �g h _�j �j 0�k "k ^"k 'k _ �g h _ �G �G U�G 9I ]9I <I �U� �G �G T�G <I �T� �G +H 0�3H mH 0�mH vH PvH 0I V �H �H P�H 0I ^ ZH fH PfH �H ^ �G H PH H P ?H CH \ ?H CH \ mH wH ^ I 0I V I 0I V ]G uG UuG �G �U� ]G jG TjG �G ]�G �G �T� ]G uG QuG �G �Q� ]G uG RuG �G ^�G �G �R� ]G uG XuG �G S�G �G �X��G �G S�G �G �X� vG �G P�G �G V�G �G P vG �G 0��G �G \�G �G 0� �G �G V � � U� �� ]�� �� U�� $� ]$� �� �U��� � ]� -� �U�-� �� ]�� � U� �� �U��� � U� 6� ]6� >� �U�>� I� ]I� ^� �U�^� f� ]f� � �U�� $� ]$� 7� �U�7� L� ]L� M� UM� m� ]m� 0� �U�0� 4� U4� F� ]F� Q� �U�Q� e� ]e� � �U�� �� ]�� �� �U��� C� ]C� G� UG� � ]� �U� \ ]\ � �U�� @ ] � � T� � \ � �� �T��� � \� -� �T�-� �� \�� �� T�� �� �T��� � T� <� \<� >� �T�>� O� \O� ^� �T�^� l� \l� � �T�� *� \*� 7� �T�7� p� \p� 0� �T�0� L� \L� Q� �T�Q� }� \}� � �T�� �� \�� �� �T��� � \� �T� \ \\ � �T�� @ \ � �� 0��� @ 0� � � 0�� k� Vk� \� 0�\� b� Pb� �� ]�� � V� � ] � � P� -� ]-� �� V�� � 0��� '� 0�'� 0� V>� Q� V^� � 0�� � V � 2� 0�7� �� 0��� � 0�� � ]� �� 0��� C� VC� P� 0�P� � V� 0� \ V\ � 0�� @ V V� `� ^� � 0�e� e� ��� � �� �� �� 1� t� �� P�� � |^� q� P � *� |*� 1� �T#7� M� |C� G� | ~� �� p 1+���� � |1+���� �� 1� � *� |1+��*� 1� �T#1+��2� 2� ��7� M� |1+��C� G� |1+�� � � 0� � b� Vb� � 0� � � V � � 0��� Q� 0�^� 2� 0�7� Q� 0�Q� �� V�� � V� � 0�� �� 0��� �� V�� @ 0� � � 0� � t� Vt� � 0�� � V � � 0��� Q� 0�^� 2� 0�7� =� 0�=� �� V�� � V� � 0�� �� 0��� �� V�� @ 0� � $� 0�$� m� \m� �� 0��� � \ � � 0��� Q� 0�^� 2� 0�7� � 0�� �� \�� �� 0��� � 0�� @ 0� $� �� 0�� -� 0�� � 0� � � 0�� � <��� >� 0�>� Q� <�^� 2� 0�7� �� 0��� �� >��� � >�� � 0�� � >�� @ 0� � � 0�� � �1 ��� >� 0�>� Q� �1 �^� 2� 0�7� �� 0��� �� �1 ��� � �1 �� � 0�� � �1 �� @ 0� � � 0�� � @��� >� 0�>� Q� D�^� 2� 0�7� �� 0��� �� k��� � k�� � 0�� � t�� @ 0� \� b� V � � V \� b� V � � V b� m� \�� � \ m� t� V� �� V �� � 1��� '� 1�� �� 1� �� � 0��� '� 0�� �� 0� �� � T�� � T� '� \� �� \ �� � 0��� '� 0�� �� 0� � � V � � V �� '� 0�� �� 0� �� '� 1�� �� 1� �� '� 0�� �� 0� �� � T� '� \� �� \ � � P� '� ^� �� ^ � '� \� �� \ !� '� P� � P� �� V !� '� ^� �� ^ � V� V�� �� V� � V-� e� V~� �� V� � V�� � V � C� VP� � V \ V� @ V � �� ��>� � ���� @ �� � �� 0�>� � 0��� @ 0� � �� 0�>� � 0��� @ 0� � � @D$� � � P � � p� +� V� v�-� e� v�~� �� v�� � v� @� O� P �� �� P G� V� P� �� P � � 0� �� �� ^� � �� � � _>� �� _�� �� P�� � _ � C� _y� � _ \ _� @ _ �� �� _� � _ � � _>� �� _�� � _ � C� _y� � _ \ _� @ _ � � ��>� �� ���� C� ��y� � �� \ ��� @ �� � � 0�>� �� 0��� C� 0�y� � 0� \ 0�� @ 0� � � 0�>� �� 0��� C� 0�y� � 0� \ 0�� @ 0� >� >� @D$� >� >� >� >� p� [� �� �� � � � C� �y� �� � � � P 2� C� P s� �� Py� �� P y� �� 0� � � _ 6 ^ � X ��A K PK � X� � X * ��� � X� � ��� �� �� � _6 A _3 \ _ �� �� P �� � 0�� � P6 = P � � P � X ��K � X� � X * ��� � X� � ��� �� � 6 ��K � �� 3 ��� @ �� � 6 0�K � 0� 3 0�� @ 0� � 6 0�K � 0� 3 0�� @ 0� � � @D$� � � P � � p� � x� ��#�l � x�� � x� * ��#� { � P � � P P P * 0� � � X� � �� � � P� � ^ � � U� � �� P � � X� � ��� �� � � P� � x#` � � 0�� � P� � P � � P � � U 0 X �� >� V�� �� VP� y� V � � P� !� v#` �� %� 0�%� 2� P2� >� _�� �� _ .� 2� P O� e� V `� k� V�� � V �� � T � � T � 1� ȑ 7� M� TC� G� T �� � ]�� �� ]q� � �U� � $� ]$� 2� �U�7� L� ]L� M� UM� m� ]m� 0� �U�C� G� UG� P� ]� �U�\ � �U� � � P� � U�� �� U �� �� @H$� �� �� t �� �� t#� �� � T7� M� TC� G� T �� � ]q� � �U�7� L� ]L� M� UM� m� ]m� 0� �U�C� G� UG� P� ]� �U�\ � �U� �� � }7� L� }L� M� uC� G� u 7� M� TC� G� T q� � �U�7� L� ]L� M� UM� m� ]m� 0� �U�C� G� UG� P� ]� �U�\ � �U� Q� ^� U q� � Vb� i� Pi� 0� V� V\ � V q� |� Vp� � V� V\ � V q� |� \p� � \� \\ � \ q� |� ]p� � ] � � v� � ]\ � ] q� |� \�� � \ q� |� ]�� � ] � � v� q� |� \�� � \ q� |� ]�� � ] � � v� �� �� ] �� �� @K$� �� �� } �� �� }#� �� �� @J$� �� �� ] �� �� }� �� �� \ �� �� @K$� �� �� | �� �� P � � @J$� � � \ � � |� � � \ � � 0� � � ] � � v� � � \ � � ] � � v� � � Q � � 0�� � P � � R � � ] �� �� @F$� �� �� | �� �� P � \\ � \ � ]\ � ] � � 0�� P\ _ P_ � ^ � _\ � _ d t T d u ] �� � 0�� � 0� �� � V� � V �� �� U� � U �� � ]� � ] �� � \� � \ �� �� U� � U �� �� U� � U �� �� ]� � ] �� �� ]� � ] �� � \ �� � \ 7� M� TC� G� T 7� L� ]L� M� UM� Q� ]C� G� UG� P� ] 7� L� }L� M� uC� G� u � � U�� �� U � $� ]$� 2� �U� � � T � 1� ȑ � �� T0� 4� T � �� ]�� �� U�� � ]0� 4� U4� =� ] � �� }�� �� u0� 4� u � � V � $� 1�Q� � 1��� �� 1� � $� 0�Q� � 0��� �� 0� � � \ � $� �T�Q� }� \}� � �T��� �� �T� � $� 1�Q� � 1��� �� 1� � � | � � 1� � $� \ � $� \ Q� � 0��� �� 0� Q� � 1��� �� 1� Q� � 1��� �� 1� Q� }� \}� � �T��� �� �T� e� t� Pt� � ]�� �� ] e� }� \}� � �T��� �� �T� }� � P�� �� P�� �� \ }� � ]�� �� ] }� �� ] � -� ] � � 0�>� Q� V�� �� 0� >� Q� V � � 0�2� 7� 0��� �� V� � 0� �� �� V �� �� V�� � V �� �� V�� � V � M UM N �U�N w Uw o �U�o } U} � �U�� U G �U�G J UJ � �U� � M TM N �T�N w Tw o �T�o � T� � �T�� T G �T�G S TS � �T� � M QM � V� � v~�� N �Q�N w Qw � V� o �Q�o � Q� � V� � �Q�� � Q� V $ ��~$ j �Q�j � V� G �Q�G S QS � V� � �Q�� , V, � �Q�� � V� e �Q�e � V� � �Q� � � R� $ \$ N �R�N \ o �R�o 4 \4 X �R�X � \� G �R�G � \� � �R�� , \, � �R�� � \� \ �R�\ ~ \~ e �R�e � \� � �R� � � 0�� $ ��N 0�o , 0�, 0 ��X j ��j � 0�� � ��G � 0�� , 0�� � 0�\ z ��e � 0� $ $ V4 > V� � �� � , 0�, ^N Z 0�o � 0�� � ^� 0� ^: G ^G � 0�� � ^� , 0�, 7 ^r � ^� � ^� � 0�R 8 0�8 e ^e � 0�� � ^� � 0�� � ^� � 0� � M q 3$t "�M � v 3$�T"�� � v~3$�T"�� N �Q3$�T"�N w q 3$t "�w � v 3$�T"�� o �Q3$�T"�o � q 3$t "�� � v 3$�T"�� � �Q3$�T"�� � q 3$t "�� v 3$t "� v 3$�T"� $ ��~3$�T"�$ j �Q3$�T"�j � v 3$�T"�� G �Q3$�T"�G S q 3$t "�S � v 3$�T"�� � �Q3$�T"�� , v 3$�T"�, � �Q3$�T"�� � v 3$�T"�� e �Q3$�T"�e � v 3$�T"�� � �Q3$�T"� � 0� Z 1�o � 0�� � 1�� % 0�% , 1�, � 0�� 1� W 0�W \ 1�\ � 0� � 0� Z �1 �o � 0�� � �1 �� % 0�% , �1 �, � 0�� �1 � W 0�W \ �1 �\ � 0� � 0� Z Vo � 0�� � Z�� % 0�% , l�, � 0�� V W 0�W \ g�\ � 0� � 0�N Z 0�o 0�& 0 0�: � 0� � � ^N ^� � ^j � ^G � ^� , ^� � ^e � ^ ( M QM � V� � v~�� � �Q�w � V� �Q�� � V� � �Q�j � VG S QS � V� � �Q�� , V� � Ve � V � � V� � P� � V� � P� � V� � ��~ � � V� � ��~ � � 3� � � 1� � � 2 � � � 3� � � �B� � � �0 � P P ( � 0�w 0�j � 0�G � 0�� , 0�� � 0�e � 0� ( � 2 �w 2 �j � 2 �G � 2 �� , 2 �� � 2 �e � 2 � ( � ^w ^j � ^G � ^� , ^� � ^e � ^ ( M QM � Vw � V� �Q�j � VG S QS � V� � �Q�� , V� � Ve � V ( � ���w ���j � ���G � ���� , ���� � ���e � ��� ( � ���w ���j � ���G � ���� , ���� � ���e � ��� ( M q 3$t "�M � v 3$�T"�w � v 3$�T"�� �Q3$�T"�j � v 3$�T"�G S q 3$t "�S � v 3$�T"�� � �Q3$�T"�� , v 3$�T"�� � v 3$�T"�e � v 3$�T"� ( � \w \j � \G � \� , \� � \e � \ ( ( @F$� ( ( P ( ( p� X � [w � [� ��~j � ��~� [ , ��~ e � P M � Sw Sj � S� , S � � Pj o P o � P o } P o } P � � 2 �� , 2 � � � ��~�� , ��~� � � ���� , ��� � � [� � ��~� [ , ��~ � � [ � � Q � � Q � � Q O � 0�� � 0�e � 0� O S q 3$t "�S � v 3$�T"�� � v 3$�T"�e � v 3$�T"� O � 2 �� � 2 �e � 2 � O � ^� � ^e � ^ O S QS � V� � Ve � V O � ���� � ���e � ��� O � ���� � ���e � ��� O S US � \� � \e � \ O � 0�� � 0�e � 0� O � 2 �� � 2 �e � 2 � O � ^� � ^e � ^ O S QS � V� � Ve � V O � ���� � ���e � ��� O � ���� � ���e � ��� O S US � \� � \e � \ X p v 3$� "` �p � S� � S� � S O S q 3$� "` �S � v 3$� "` �� � v 3$� "` �e � v 3$� "` � O p 0�p { ]{ � }�� � ]� � ]� � ] � � T p � P� � P p w 0�w � 1�� � 0� p w P � � 2 �e � 2 � � � v 3$� "` �e � v 3$� "` � � � ���e � ��� � � \e � \ / D v 3$� "` �D Z Q � � P � P c � 2 �e 2 � c � ��~�e ��~� c � v 3$� "` �e v 3$� "` � c � ���e ��� c � ��~e ~ ��~ c c ��~ \ ` P \ ` P i m P i m P � $ ��, 0 ��X j ��� � ��\ z �� � N ��, j ��� � �� G ��� � ��, � ��� e ��� � �� � N 0�, j 0�� � 0� G 0�� � 0�, � 0�� e 0�� � 0� � N 0�, j 0�� � 0� G 0�� � 0�, � 0�� e 0�� � 0� � � @D$� � � P � � p� $ ��#�, 0 ��#�X j ��#� $ u � ����N$u� ����!� h j V 4 4 P \ z �� � � V " V� � �� � 8 \� � \ " \J z \� � \ \ z �� ` p Pp z u#` \ ~ 0�~ � P� � \� \" J \ � � P � \" J \ � � Q� � R" 9 Q � � @D$� � � P � � p� : J \ � � \� \" 8 \� � \ " \J z \� � \ � 8 ��� � �� " ��J z ��� � �� � 8 0�� � 0� " 0�J z 0�� � 0� � 8 0�� � 0� " 0�J z 0�� � 0� � � @D$� � � | � � p� � � |� 8 |� | � ����N$|� ����!� 6 8 V � � P � � \ " \J z \� � \ . F V � k ]u z 0�� � ] � � \k � \ " \J u \ � � P � � 0�� � P� � ]k � ]J u ] � � P k � ]J u ] o � Q� � RJ a Q o o @D$� o o P o o p� b u ] � . ]F k ]� � ] � k ��� � �� � k 0�� � 0� � k 0�� � 0� � � @D$� � � } � � }#� . }�� � }� � � } � ����N$}� ����!� � � V . . P Y ^ V . F ] � � \ " \� � \ y � S y � S � � U � � U � � P � � P 0� ) 1�) = 2�= Z 3�� � 2�� 1� 0� U ) U. = U� � U� � U U U ) U3 = U� � U� � U U 0� , 1�, I 2�I N 3� & 0�0 : 1� U , U1 H U U0 4 U U" , U: H U U0 4 U , �U�� � �U� �U�& 0 �U�: G �U�� � �U�, � �U�� R �U�8 e �U�� � �U�� � �U� , ^� � ^ ^: G ^� � ^, 7 ^r � ^� � ^8 e ^� � ^� � ^ , 0 U0 � V� w V, 1 Ve r V� � V� � V� V� � V� � V , 0�� W 0�W a Pa � \� � \ 0�& 0 \: G 0�� � 0�� � \, > 0�V c 0�e r 0�� � 0�� � \� � P� � \� � 0�� � 0�� � 0� 0� " \M R \8 e 0�� � 0�� � 0� , � 0�� V� � 0�� � 0� V& 0 0�: G 0�� � V� � 0�, > 0�V c 0�e r 0�� � 0�� � V� � V� � 0� " 0�M R 0�8 e V� � 0�� � 0� , � 0�� � V� � 0�& 0 0�: G 0�� � 0�, � 0�� R 0�8 e 0�� � 0�� � 0� , 4 0�4 K PK b \b � 0�� � P� � V� � 0�� � P� � \� � 0�� � P� < \< N 0�N a Pa a \a � 0�� � P� � ]: A PA G V� � P� � ]� � 0�� � ], > \[ c \e r \r r V� � 0�� � P� � \� � P� � \ " 0�8 e 0� W k p $0)��k � } $0)��� � p $0)��� � } $0)��: G } $0)��r � } $0)��� � } $0)�� , r 0�r � \� � 0�� 0� l ]l w 0�w � P� � V� � 0�: G \� � 0�� � V, > 0�[ c 0�e r ]r r 0�� � ]� � 0� " P8 e 0� � 0� 0�: G 0�� � 0�r � 0�� � 0�8 e 0� , � 0�� � 0�: G 0�� � 0�� � 6�� � 0�, 7 0�7 > ][ c ]e r 0�r r 7�� � 0�� � 0� " 0�8 [ 0�[ e 9� , � 0�� � 0�: G 0�� � 0�� � �1 �� � 0�, 7 0�7 > �1 �[ c �1 �e r 0�r r �1 �� � 0�� � 0� " 0�8 [ 0�[ e �1 � , � 0�� � 0�: G 0�� � 0�� � ��� � 0�, 7 0�7 > V[ c Ve r 0�r r ��� � 0�� � 0� " 0�8 [ 0�[ e �� , 0 U0 4 V , N ��� � �� G ��� � ��, � ��� R ��8 e ��� � ��� � �� , N 0�� � 0� G 0�� � 0�, � 0�� R 0�8 e 0�� � 0�� � 0� , N 0�� � 0� G 0�� � 0�, � 0�� R 0�8 e 0�� � 0�� � 0� = W 3�, 7 3� = K �� = K PK W \, 7 \ O W P, 7 P W b \� � \ r � \ � � \: G \ � � \: G \ � � ^ � � P� � P � � V � � 0�� � \& . \V V 0�� � 0�� � 0� 0�M R \� � 0�� � 0� � � \& . \ � V V. 0 0�V [ 0�� � 0�� � V� � 0�� � 0� � V V � � P � � 0� � \� � \ � ] � � 0� P� � P� � ] � � 0�� P ^� � ^ � � 0�& 0 0�� � 0�e r 0�� � 0�� R 0�� � 0� ^� � ^ ^� � ^ / < \e r \ W W P W a P� � P� � \ a l ]� � ] l w V l � ��& 0 ��� � �� R ��� � �� l � 0�& 0 0�� � 0� R 0�� � 0� l � 0�& 0 0�� � 0� R 0�� � 0� c c 0�r r 0�� � ]" 0 V� � V � � ]" 0 V� � V � � V� � V � � ]� � ] � � 0�7 > \[ c \[ e 0� 7 > \[ c \ 8 [ ^ 8 [ �1 � 8 C pC Z R � � Q� V $ ��~$ % �Q� � % 3� � % 1� � % 2 � � % 3� � % �0 � � �� U�� �� \�� �� U�� �� \�� c� �U�c� y� Uy� �� �U��� ʢ \ʢ �� �U��� � U� �� �U��� �� U�� �� �U��� ʣ Uʣ ߣ \ߣ �� �U��� �� U�� �� \�� X� �U�X� \� U\� e� \e� ѥ �U� � O� TO� ޡ Vޡ c� �T�c� v� Tv� �� �T��� ʢ Vʢ �� �T��� � T� � V� �� �T��� � V� �� �T��� � V� X� �T�X� e� Ve� ѥ �T� � M� 0�c� ѥ 0� Ţ ʢ 1� 5� S� PS� �� v�� � P�� �� v�� ʣ vX� \� v ?� S� p 0+��S� �� v0+��Ţ ʢ 1��� �� v0+���� �� ���� ʣ v0+��X� \� v0+�� � � 0�� !� P!� M� ]c� ~� 0��� �� ]�� ʢ 0�ʢ � ]� �� P�� �� ]�� �� 0��� � 0�@� ѥ 0� � ʡ 0�ʡ !� \!� ~� 0��� � 0�� �� \�� �� 0��� Ϥ 0�Ϥ � \@� X� \X� ѥ 0� � �� 0��� 7� \7� ~� 0��� ʢ 0�ʢ �� \�� �� 0��� �� 0��� � \@� X� \X� ѥ 0� � � 0�� ,� V,� ~� 0��� ݢ 0�ݢ �� V�� �� 0��� � 0�� �� V�� � 0�@� ѥ 0� � M� 0��� �� 0�ʢ �� 0� � ~� 0�~� ~� <��� �� 0��� �� 0��� � =�@� N� =�N� ѥ 0� � ~� 0�~� ~� �1 ��� �� 0��� �� 0��� � �1 �@� N� �1 �N� ѥ 0� � ~� 0�~� ~� ���� �� 0��� �� 0��� � ��@� N� ��N� ѥ 0� � !� \� �� \ � !� \� �� \ !� ,� Vݢ � V ,� 7� \ʢ ݢ \ O� �� T�� �� T�� �� ȑ �� ʣ TX� \� T O� �� U�� �� \�� Ţ \� �� �U��� �� U�� �� �U��� ʣ Uʣ ߣ \ߣ �� �U�X� \� U\� e� \e� ѥ �U� �� �� P�� �� U�� Ģ U O� O� @H$� O� O� t O� O� t#� g� �� T�� ʣ TX� \� T g� �� U�� �� \� s� �U��� ʣ Uʣ ߣ \ߣ �� �U�X� \� U\� e� \e� ѥ �U� g� �� u�� ʣ uX� \� u �� ʣ TX� \� T � s� �U��� ʣ Uʣ ߣ \ߣ �� �U�X� \� U\� e� \e� ѥ �U� Σ ۣ U � s� \ߣ � P� �� \e� ѥ \ � � \� �� \|� ѥ \ � � V� �� V|� ѥ V � � ]� �� ]�� �� |� |� ѥ ] � � V� �� V � � ]� �� ]�� �� |� � � V� �� V � � ]� �� ]�� �� |� � � ] � � @K$� � � } � � }#� '� '� @J$� '� '� ] '� '� }� 5� 5� V 5� 5� @K$� 5� 5� v 5� 5� P @� @� @J$� @� @� V @� @� v� M� �� V M� �� 0� M� �� ]�� �� |� M� �� V M� �� ]�� �� |� T� �� Q ]� j� 0�j� �� P ]� �� R �� �� ] � � @F$� � � v � � P |� ѥ V |� ѥ ] �� �� 0��� �� P�� ѥ ^ �� ѥ _ �� �� T �� �� ] � s� 0�e� |� 0� � s� \e� |� \ #� O� Ue� i� U ,� s� ]e� |� ] 1� s� Ve� |� V @� O� Ue� i� U E� O� Ue� i� U O� _� ]o� |� ] T� _� ]o� |� ] _� s� V d� s� V �� ʣ TX� \� T �� ʣ Uʣ Σ \X� \� U\� e� \ �� ʣ uX� \� u �� �� U�� Ģ U �� �� U�� �� �U� �� �� T�� �� ȑ �� �� T�� �� T �� �� \�� �� U�� �� \�� �� U�� �� \�� �� �U� �� �� |�� �� u�� �� u ʡ ϡ \ ϡ � 1�Ϥ � 1�N� X� 1� ϡ � 0�Ϥ � 0�N� X� 0� ϡ ޡ Vޡ � �T�Ϥ � V� � �T�N� X� �T� ϡ � 0�Ϥ � 0�N� X� 0� ޡ � V ޡ � V Ϥ � 0�N� X� 0� Ϥ � 1�N� X� 1� Ϥ � 0�N� X� 0� Ϥ � V� � �T�N� X� �T� ڤ � P� � ]N� X� ] ڤ � V� � �T�N� X� �T� � � PN� U� PU� X� V � � ]N� X� ] F� M� ]�� �� ] ~� �� 0��� �� 0� � @� \ � @� \ �� � \@� N� \ �� � \@� N� \ `� -� U-� .� �U�.� W� UW� O� �U�O� ]� U]� ȵ �U�ȵ �� U�� '� �U�'� *� U*� о �U� `� -� T-� .� �T�.� W� TW� O� �T�O� �� T�� ȵ �T�ȵ �� T�� '� �T�'� 3� T3� о �T� `� -� Q-� �� V�� �� v~��� .� �Q�.� W� QW� ״ V״ O� �Q�O� �� Q�� �� V�� ȵ �Q�ȵ ڵ Qڵ � V � � ��~� J� �Q�J� f� Vf� '� �Q�'� 3� Q3� �� V�� ٸ �Q�ٸ � V � ȹ �Q�ȹ �� V�� E� �Q�E� r� Vr� о �Q� `� � R� � \� .� �R�.� � \� O� �R�O� � \� 8� �R�8� �� \�� '� �R�'� �� \�� ٸ �R�ٸ � \ � ȹ �R�ȹ �� \�� <� �R�<� ^� \^� E� �R�E� r� \r� о �R� `� �� 0��� � ��.� � 0�O� � 0� � � ��8� J� ��J� f� 0�f� �� ��'� �� 0�ٸ � 0�ȹ �� 0�<� Z� ��E� r� 0� � � V� � V�� �� �� `� � 0� � � ^.� :� 0�O� �� 0��� ж ^ѷ � 0�� �� ^� '� ^'� �� 0��� �� ^ٸ � 0� � � ^R� t� ^�� ȹ ^ȹ �� 0�2� � 0�� E� ^E� r� 0�r� �� ^�� �� 0��� �� ^�� о 0� �� -� q 3$t "�-� �� v 3$�T"��� �� v~3$�T"��� .� �Q3$�T"�.� W� q 3$t "�W� ״ v 3$�T"�״ O� �Q3$�T"�O� �� q 3$t "��� �� v 3$�T"��� ȵ �Q3$�T"�ȵ ڵ q 3$t "�ڵ �� v 3$t "��� � v 3$�T"� � � ��~3$�T"�� J� �Q3$�T"�J� f� v 3$�T"�f� '� �Q3$�T"�'� 3� q 3$t "�3� �� v 3$�T"��� ٸ �Q3$�T"�ٸ � v 3$�T"� � ȹ �Q3$�T"�ȹ �� v 3$�T"��� E� �Q3$�T"�E� r� v 3$�T"�r� о �Q3$�T"� �� � 0�� :� 1�O� �� 0��� ȵ 1�ȵ � 0�� � 1� � ѷ 0�ѷ � 1�� 7� 0�7� <� 1�<� о 0� �� � 0�� :� �1 �O� �� 0��� ȵ �1 �ȵ � 0�� � �1 � � ѷ 0�ѷ � �1 �� 7� 0�7� <� �1 �<� о 0� �� � 0�� :� VO� �� 0��� ȵ ��ȵ � 0�� � �� � ѷ 0�ѷ � V� 7� 0�7� <� ��<� о 0� �� � 0�.� :� 0�O� �� 0�� � 0�� о 0� DZ �� ^.� � ^�� ȵ ^J� f� ^'� �� ^ٸ � ^ȹ �� ^E� r� ^ � -� Q-� �� V�� �� v~��� �� �Q�W� ״ V״ � �Q��� �� V�� ȵ �Q�J� f� V'� 3� Q3� �� V�� �� �Q�ٸ � Vȹ �� VE� r� V x� �� V�� �� P�� �� V�� �� P�� �� V�� �� ��~ �� �� V�� �� ��~ �� �� 3� �� �� 1� �� �� H< � �� �� 3� �� �� �B� �� �� �0 � � �� P � �� P � x� 0�W� � 0�J� f� 0�'� �� 0�ٸ � 0�ȹ �� 0�E� r� 0� � x� H< �W� � H< �J� f� H< �'� �� H< �ٸ � H< �ȹ �� H< �E� r� H< � � x� ^W� � ^J� f� ^'� �� ^ٸ � ^ȹ �� ^E� r� ^ � -� Q-� x� VW� ״ V״ � �Q�J� f� V'� 3� Q3� �� V�� �� �Q�ٸ � Vȹ �� VE� r� V � x� ���W� � ���J� f� ���'� �� ���ٸ � ���ȹ �� ���E� r� ��� � x� ���W� � ���J� f� ���'� �� ���ٸ � ���ȹ �� ���E� r� ��� � -� q 3$t "�-� x� v 3$�T"�W� ״ v 3$�T"�״ � �Q3$�T"�J� f� v 3$�T"�'� 3� q 3$t "�3� �� v 3$�T"��� �� �Q3$�T"�ٸ � v 3$�T"�ȹ �� v 3$�T"�E� r� v 3$�T"� � x� \W� � \J� f� \'� �� \ٸ � \ȹ �� \E� r� \ � � @F$� � � P � � p� 8� o� [W� �� [�� � ��~J� f� ��~ٸ �� [�� � ��~ E� f� P -� x� SW� � SJ� f� Sٸ � S �� �� PJ� O� P O� f� P O� ]� P O� ]� P i� �� H< �ٸ � H< � i� �� ��~�ٸ � ��~� i� �� ���ٸ � ��� i� �� [�� �� ��~ٸ �� [�� � ��~ i� i� [ c� o� Q c� j� Q c� j� Q /� �� 0�ȹ �� 0�E� r� 0� /� 3� q 3$t "�3� �� v 3$�T"�ȹ �� v 3$�T"�E� r� v 3$�T"� /� �� H< �ȹ �� H< �E� r� H< � /� �� ^ȹ �� ^E� r� ^ /� 3� Q3� �� Vȹ �� VE� r� V /� �� ���ȹ �� ���E� r� ��� /� �� ���ȹ �� ���E� r� ��� /� 3� U3� �� \ȹ �� \E� r� \ /� �� 0�ȹ �� 0�E� r� 0� /� �� H< �ȹ �� H< �E� r� H< � /� �� ^ȹ �� ^E� r� ^ /� 3� Q3� �� Vȹ �� VE� r� V /� �� ���ȹ �� ���E� r� ��� /� �� ���ȹ �� ���E� r� ��� /� 3� U3� �� \ȹ �� \E� r� \ 8� P� v 3$� "` �P� }� S�� �� Sȹ ѹ S /� 3� q 3$� "` �3� �� v 3$� "` �ȹ �� v 3$� "` �E� r� v 3$� "` � /� P� 0�P� [� ][� c� }�c� }� ]�� �� ]ȹ ѹ ] �� �� T P� c� P�� �� P P� W� 0�W� c� 1��� �� 0� P� W� P ѹ �� H< �E� r� H< � ѹ �� v 3$� "` �E� r� v 3$� "` � ѹ �� ���E� r� ��� ѹ �� \E� r� \ � $� v 3$� "` �$� :� Q n� �� P_� r� P C� n� H< �E� _� H< � C� n� ��~�E� _� ��~� C� n� v 3$� "` �E� _� v 3$� "` � C� n� ���E� _� ��� C� m� ��~E� ^� ��~ C� C� ��~ <� @� P <� @� P I� M� P I� M� P �� � �� � � ��8� J� ��f� �� ��<� Z� �� �� .� �� � J� ��f� ѷ ��� '� ���� ٸ �� � ȹ ���� E� ��r� о �� �� .� 0� � J� 0�f� ѷ 0�� '� 0��� ٸ 0� � ȹ 0��� E� 0�r� о 0� �� .� 0� � J� 0�f� ѷ 0�� '� 0��� ٸ 0� � ȹ 0��� E� 0�r� о 0� IJ IJ @D$� IJ IJ P IJ IJ p� � � ��#� � � ��#�8� J� ��#� �� � u � ����N$u� ����!� H� J� V � � P <� Z� �� �� ƻ V�� � V�� �� �� {� � \�� �� \� � \*� Z� \�� о \ <� Z� �� @� P� PP� Z� u#` <� ^� 0�^� k� Pk� {� \�� � \� *� \ g� k� P �� � \� *� \ �� ҽ Qҽ ۽ R� � Q �� �� @D$� �� �� P �� �� p� � *� \ {� �� \ƻ �� \� � \�� �� \� � \*� Z� \�� о \ {� � ���� �� ��� � ��*� Z� ���� о �� {� � 0��� �� 0�� � 0�*� Z� 0��� о 0� {� � 0��� �� 0�� � 0�*� Z� 0��� о 0� {� {� @D$� {� {� | {� {� p� �� �� |�� � |� � �� | � ����N$|� ����!� � � V �� �� P �� �� \� � \*� Z� \�� о \ � &� V ؼ K� ]U� Z� 0��� о ] �� ؼ \K� �� \� � \*� U� \ �� �� P �� Ƽ 0�Ƽ Ӽ PӼ ؼ ]K� �� ]*� U� ] ϼ Ӽ P K� �� ]*� U� ] O� r� Qr� {� R*� A� Q O� O� @D$� O� O� P O� O� p� B� U� ] ؼ � ]&� K� ]�� о ] ؼ K� ���� о �� ؼ K� 0��� о 0� ؼ K� 0��� о 0� ؼ ؼ @D$� ؼ ؼ } ؼ ؼ }#� � � }��� о }� �� �� } � ����N$}� ����!� ˾ о V � � P 9� >� V � &� ] �� ƻ \�� � \�� �� \ Y� e� S Y� e� S j� n� U j� n� U s� w� P s� w� P � �� 0��� � 1� � � 2� � :� 3�ѷ ۷ 2�۷ � 1�� � 0� � �� U�� � U� � Uѷ շ U۷ ߷ U� � U � �� U�� � U� � Uѷ շ U۷ ߷ U� � U � �� 0��� � 1� � )� 2�)� .� 3��� � 0�� � 1� � �� U�� � U� (� U�� � U� � U � �� U� � U� (� U�� � U� � U � � �U��� ѷ �U�� �� �U�� � �U�� '� �U��� ٸ �U� � ȹ �U��� 2� �U�� E� �U�r� �� �U��� �� �U� � � ^�� ж ^� �� ^� '� ^�� �� ^ � � ^R� t� ^�� ȹ ^� E� ^r� �� ^�� �� ^ � � U� �� V�� W� V � � VE� R� Vt� �� V�� �� V�� � Vr� �� V�� �� V � � 0��� 7� 0�7� A� PA� �� \· ɷ \� �� 0�� � \� '� 0��� �� 0��� ٸ \ � � 0�6� C� 0�E� R� 0�o� t� 0�t� �� \�� �� P�� �� \�� �� 0��� ȹ 0��� �� 0�� � 0�� � \-� 2� \� E� 0��� �� 0��� �� 0� � �� 0��� � V�� �� 0�· ѷ 0�� �� V� � 0�� '� 0��� �� V�� ٸ 0� � � 0�6� C� 0�E� R� 0�o� �� 0��� �� V�� ȹ V�� �� 0�� � 0�-� 2� 0�� E� V�� �� 0��� �� 0� � Գ 0�Գ ׳ V�� ѷ 0�� � 0�� '� 0��� ٸ 0� � ȹ 0��� 2� 0�� E� 0�r� �� 0��� �� 0� � � 0�� +� P+� B� \B� �� 0��� �� P�� �� V�� �� 0��� г P�� �� \�� �� 0��� �� P�� � \ � .� 0�.� A� PA� A� \A� r� 0�r� v� Pv� �� ]� !� P!� '� V�� �� P�� Ǹ ]Ǹ ̸ 0�̸ ٸ ] � � \;� C� \E� R� \R� R� Vt� �� 0��� �� P�� �� \�� �� P�� �� \� � 0�� E� 0� 7� K� p $0)��K� �� } $0)���� �� p $0)���� ȶ } $0)��� '� } $0)��R� t� } $0)��r� �� } $0)�� � R� 0�R� �� \�� ׳ 0��� �� 0��� L� ]L� W� 0�W� n� Pn� �� V�� �� 0�� '� \�� ̸ 0�̸ ٸ V � � 0�;� C� 0�E� R� ]R� R� 0�t� �� ]�� �� 0�� � P� E� 0� o� � 0�� �� 0�� '� 0��� �� 0�R� t� 0��� ȹ 0�� E� 0� � ׳ 0��� �� 0�� '� 0��� Ǹ 0�Ǹ ̸ 6�̸ ٸ 0� � � 0�� � ];� C� ]E� R� 0�R� R� 7�t� �� 0��� �� 0�� � 0�� ;� 0�;� E� 9� � ׳ 0��� �� 0�� '� 0��� Ǹ 0�Ǹ ̸ �1 �̸ ٸ 0� � � 0�� � �1 �;� C� �1 �E� R� 0�R� R� �1 �t� �� 0��� �� 0�� � 0�� ;� 0�;� E� �1 � � ׳ 0��� �� 0�� '� 0��� Ǹ 0�Ǹ ̸ O�̸ ٸ 0� � � 0�� � V;� C� VE� R� 0�R� R� h�t� �� 0��� �� 0�� � 0�� ;� 0�;� E� � � � U� � V � .� ���� ѷ ��� '� ���� ٸ �� � ȹ ���� 2� ��� E� ��r� �� ���� �� �� � .� 0��� ѷ 0�� '� 0��� ٸ 0� � ȹ 0��� 2� 0�� E� 0�r� �� 0��� �� 0� � .� 0��� ѷ 0�� '� 0��� ٸ 0� � ȹ 0��� 2� 0�� E� 0�r� �� 0��� �� 0� � 7� 3� � � 3� � +� �� � +� P+� 7� \ � � \ /� 7� P � � P 7� B� \�� �� \ R� o� \ �� �� \� '� \ �� �� \� '� \ �� �� ^ Ƴ г P�� �� P г Գ V Գ Գ 0�· ɷ \� � \6� 6� 0�o� o� 0��� �� 0�� � 0�-� 2� \�� �� 0��� �� 0� · ɷ \� � \ Գ � V� �� V� � 0�6� ;� 0�o� t� 0��� ȹ V�� �� 0��� �� 0� ׳ � V� �� V �� �� P ȶ ٶ 0� ȶ �� \�� �� \ ȶ �� ] ȶ ٶ 0��� �� P�� �� P�� �� ] ȶ ж 0�ж � P� �� ^�� �� ^ ȶ ɷ 0�� � 0��� ٸ 0�E� R� 0�t� �� 0��� 2� 0��� �� 0� �� �� ^�� �� ^ �� �� ^�� �� ^ � � \E� R� \ 7� 7� P 7� A� P�� �� P�� �� \ A� L� ]t� �� ] L� W� V L� ɷ ��� � ���� ٸ ��� 2� ���� �� �� L� ɷ 0�� � 0��� ٸ 0�� 2� 0��� �� 0� L� ɷ 0�� � 0��� ٸ 0�� 2� 0��� �� 0� C� C� 0�R� R� 0��� Ϻ ]� � V�� �� V �� Ϻ ]� � V�� �� V � �� V̸ ٸ V �� �� ]�� Ǹ ] Ǹ ̸ 0�� � \;� C� \;� E� 0� � � \;� C� \ � ;� ^ � ;� �1 � � #� p#� :� R ȵ ڵ Qڵ � V � � ��~� � �Q� ȵ � 3� ȵ � 1� ȵ � H< � ȵ � 3� ȵ � �0 � @ � U� � [� �U� M UM � �U�� � U� F �U�F I UI V [V { ��~{ x �U� @ � T� �T� M TM � �T�� � T� F �T�F V TV x �T� @ � Q� ] �Q� M QM � ]� � Q� F ]F V QV x ] @ � R� �R� M RM � V� �R� � V� � �R�� � R� V ! �R�! < V< F �R�F V RV � V� �R� # V# U �R�U x V @ � 0� � 0�� � �� < 0�F � 0� # 0�# J ��U x 0� d � q 3$t "�� � } 3$t "�� } 3$�T"� �Q3$�T"� M q 3$t "�M � } 3$�T"�� � q 3$t "�� F } 3$�T"�F V q 3$t "�V x } 3$�T"� d � 0�� � @� � 0�� � @�� 0� ! @�! x 0� d � 0�� � �1 � � 0�� � �1 �� 0� ! �1 �! x 0� d � 0�� � i� � 0�� � V� 0� ! ]�! x 0� d � 0� � 0�� \ x 0� � Y M YF V YV { ��~ ( M QM � ] � ]� < ]F V QV � ] # ]U x ] � � ]� ! ] � ] � 1� � �1 � � 1� � � �B� � �0 � P P ( � 0� � 0�! < 0�F � 0� # 0�U x 0� ( � �1 � � �1 �! < �1 �F � �1 � # �1 �U x �1 � ( M YF V YV { ��~ ( M QM � ] � ]! < ]F V QV � ] # ]U x ] ( � ��� � ���! < ���F � ��� # ���U x ��� ( � ��� � ���! < ���F � ��� # ���U x ��� ( M q 3$t "�M � } 3$�T"� � } 3$�T"�! < } 3$�T"�F V q 3$t "�V � } 3$�T"� # } 3$�T"�U x } 3$�T"� ( M RM � V � V� � �R�! < VF V RV � V� � �R� # VU x V ( ( @F$� ( ( P ( ( p� X � Z Q ZQ � ��~! < ��~ @ Z@ T ��~ e � P M � S � S! < S T S ` y P! % P % < P % 3 P % 3 P ` �1 � T �1 � ` ��� T ��� ` ��� T ��� Q ZQ ` ��~ @ Z@ T ��~ Z � � Q � � Q � � Q R � 0�T # 0�U x 0� R V q 3$t "�V � } 3$�T"�T # } 3$�T"�U x } 3$�T"� R � �1 �T # �1 �U x �1 � R { ��~ R V QV � ]T # ]U x ] R � ���T # ���U x ��� R � ���T # ���U x ��� R V UV � VT # VU x V R � 0�T # 0�U x 0� R � �1 �T # �1 �U x �1 � R { ��~ R V QV � ]T # ]U x ] R � ���T # ���U x ��� R � ���T # ���U x ��� R V UV � VT # VU x V _ { } 3$� "P �{ � S� � ST ] S R V q 3$� "P �V � } 3$� "P �T # } 3$� "P �U x } 3$� "P � R { 0�{ � \� � |�� � \� � \T ] \ � � T { � P� � P { � 0�� � 1�� � 0� { � P ] # �1 �U x �1 � ] # } 3$� "P �U x } 3$� "P � ] # ���U x ��� ] # VU x V � � } 3$� "P �� � Q � Pj x P � � �1 �U j �1 � � � ���U j ��� � � } 3$� "P �U j } 3$� "P � � � ���U j ��� � � ��U i �� � � �� � � V � � V � � 0�� � 0�� � 1� � � ��� � U � � U � 0� 1� � � Q� � ] � � 1� � � �1 � � � 1� � � �0 � � � ��# J �� � � [# J [ � � 0�� � \< F 0�� 0�# U 0� � � 0�� � P� � 0�< @ P� � P# U 0� � � 0�< F 0�� � 0�# K 0�K U A� � � 0�< F 0�� � 0�# K 0�K U �1 � � � 0�< F 0�� � 0�# K 0�K U �� � � �� � � P< @ P # J �� # K �1 � # 3 p3 J R � l� Ul� �� \�� �� �U��� � U� ԧ \ԧ � �U�� �� \�� ۨ Uۨ {� \{� ~� U~� � \ � i� Ti� �� �T��� � T� �� �T��� ۨ Tۨ {� �T�{� �� T�� � �T� � L� QL� �� ^�� �� �Q��� � Q� �� ^�� ۨ Qۨ {� ^{� �� Q�� � ^ � b� Rb� �� �R��� � R� N� VN� � �R�� �� V�� �� �R��� ۨ Rۨ � �R�� <� V<� U� �R�U� q� Vq� {� �R�{� �� R�� � V � �� �R��� �� V�� � �R�� � V� � �R� � �� 0��� N� 0�N� ^� ��� ۨ 0�� H� 0�U� q� 0�{� %� 0��� �� 0�� � 0� � L� q 3$t "�L� i� ~ 3$t "�i� �� ~ 3$�T"��� �� �Q3$�T"��� � q 3$t "�� �� ~ 3$�T"��� ۨ q 3$t "�ۨ {� ~ 3$�T"�{� �� q 3$t "��� � ~ 3$�T"� � x� 0�x� �� T��� �� 0��� �� T��� A� 0�A� H� T�H� � 0� � x� 0�x� �� �; ��� �� 0��� �� �; ��� A� 0�A� H� �; �H� � 0� � x� 0�x� z� ���� �� 0��� �� V�� A� 0�A� H� ��H� � 0� � �� 0��� ֧ 0�� � 0� � :� _�� N� _� �� _� H� _U� q� _{� %� _�� �� _� � _ Ȧ � Q� N� ^� �� ^� H� ^U� q� ^{� �� Q�� %� ^�� �� ^� � ^ 8� I� ^� H� ^ � A� ^ � A� 1� � A� �1 � � A� 1� � � �B� � A� �0 � �� �� P �� �� P Ȧ 8� 0�� �� 0�U� q� 0�{� %� 0��� �� 0�� � 0� Ȧ 8� �1 �� �� �1 �U� q� �1 �{� %� �1 ��� �� �1 �� � �1 � Ȧ 8� _� �� _U� q� _{� %� _�� �� _� � _ Ȧ � Q� 8� ^� �� ^U� q� ^{� �� Q�� %� ^�� �� ^� � ^ Ȧ 8� ���� �� ���U� q� ���{� %� ����� �� ���� � ��� Ȧ 8� ���� �� ���U� q� ���{� %� ����� �� ���� � ��� Ȧ � q 3$t "�� 8� ~ 3$�T"�� �� ~ 3$�T"�U� q� ~ 3$�T"�{� �� q 3$t "��� %� ~ 3$�T"��� �� ~ 3$�T"�� � ~ 3$�T"� Ȧ � R� 8� V� �� V�� �� �R�U� q� V{� �� R�� � V � %� �R��� �� V� � V Ȧ Ȧ @F$� Ȧ Ȧ P Ȧ Ȧ p� �� /� Z� Q� ZQ� �� ��~U� q� ��~�� �� Z�� �� ��~ � &� P � 8� S� �� SU� q� S�� �� S `� y� PU� Z� P Z� q� P Z� h� P Z� h� P � `� �1 ��� �� �1 � � `� ����� �� ��� � `� ����� �� ��� � Q� ZQ� `� ��~�� �� Z�� �� ��~ � � Z #� /� Q #� *� Q #� *� Q �� � 0�� � 0� �� �� q 3$t "��� � ~ 3$�T"�� � ~ 3$�T"� �� � �1 �� � �1 � �� � _� � _ �� �� Q�� � ^� � ^ �� � ���� � ��� �� � ���� � ��� �� �� U�� � V� � V �� � 0�� � 0� �� � �1 �� � �1 � �� � _� � _ �� �� Q�� � ^� � ^ �� � ���� � ��� �� � ���� � ��� �� �� U�� � V� � V �� �� ~ 3$� "P ��� ݩ S� � S� �� S �� �� q 3$� "P ��� � ~ 3$� "P �� � ~ 3$� "P � �� �� 0��� �� ]�� é }�é ݩ ]� � ]� �� ] � � T �� é P� � P �� �� 0��� é 1�� � 0� �� �� P �� � �1 � �� � ~ 3$� "P � �� � ��� �� � V ;� T� ~ 3$� "P �T� j� Q �� �� P�� � P s� �� �1 �� �� �1 � s� �� ���� �� ��� s� �� ~ 3$� "P �� �� ~ 3$� "P � s� �� ���� �� ��� s� �� ��� �� �� s� s� �� ͨ Ѩ S ͨ Ѩ S x� z� 0��� �� 0��� �� 1� x� z� ���� �� U �� �� U ֧ �� V :� L� QL� x� ^ :� x� 1� :� x� �1 � :� x� 1� :� x� �0 � N� ^� �� N� ԧ \ԧ ֧ �U�ۨ � \H� U� \q� {� \%� �� \�� � \� � \ N� �� 0��� § ]ۨ � ]q� {� 0�%� �� 0��� � 0�� � 0� N� U� 0�U� ԧ \ԧ � �U�ۨ � \H� U� \q� {� \%� �� \�� � \� � \ N� § 0�§ § ]ۨ � 0�� � ]q� {� 0�%� �� 0��� � 0�� � 0� N� b� 0�b� r� Pr� �� U�� § 0�ۨ � 0�%� *� PR� Z� UZ� n� ��~n� |� U�� ٪ 0�� � 0�� � ��~ N� � 0�� �� U�� �� ]�� § 0�ۨ � ]� � 0�q� {� ]%� *� 0�R� e� 0�e� h� Ph� n� ]n� |� 0��� ٪ ]� � ]� � ] N� § 0�ۨ � 0�q� {� 0�%� *� 0�R� n� 0�n� |� X��� ٪ 0�٪ ٪ X�� � 0�� � 0� N� § 0�ۨ � 0�q� {� 0�%� *� 0�R� n� 0�n� |� �; ��� ٪ 0�٪ ٪ �; �� � 0�� � 0� N� § 0�ۨ � 0�q� {� 0�%� *� 0�R� n� 0�n� |� ���� ٪ 0�٪ ٪ ��� � 0�� � 0� N� U� \ U� ^� |0 U� � ��ۨ � ��H� U� ��q� {� ��%� �� ���� � ��� � �� U� � 0�ۨ � 0�H� U� 0�q� {� 0�%� �� 0��� � 0�� � 0� U� � 0�ۨ � 0�H� U� 0�q� {� 0�%� �� 0��� � 0�� � 0� k� k� P |� � U |� � U �� �� Uq� u� U �� �� ] �� �� ]ۨ � ] § § ]� � ] § § ]� � ]M� R� 0� § § ]� � ] § ԧ \ԧ ֧ �U�H� U� \ § ԧ \ԧ ֧ �U�H� U� \ n� |� U٪ ٪ 0� n� |� U ٪ � ] ٪ � ] p� �� U�� -� \-� ?� �U�?� }� U}� �� \�� �� �U��� �� \�� �� U�� 0� \0� 3� U3� b� \ p� �� T�� ?� �T�?� }� T}� �� �T��� �� T�� 0� �T�0� @� T@� b� �T� p� �� Q�� -� ^-� ?� �Q�?� }� Q}� �� ^�� �� �Q��� �� ^�� �� Q�� 2� ^2� � �Q� � <� ^<� �� �Q��� �� ^�� 0� �Q�0� @� Q@� �� ^�� {� �Q�{� �� ^�� �� �Q��� �� ^�� w� �Q�w� �� ^�� b� �Q� p� �� R�� ?� �R�?� }� R}� �� V�� �� �R��� � V� �� �R��� �� R�� � V� � �R� � <� V<� 0� �R�0� @� R@� �� V�� {� �R�{� �� V�� �� �R��� �� V�� w� �R�w� �� V�� b� �R� p� -� 0�?� �� 0��� �� ���� � 0�� #� �� � <� 0��� �� ��0� �� 0��� �� ��{� �� 0��� �� 0�w� �� 0� �� �� q 3$t "��� �� ~ 3$t "��� -� ~ 3$�T"�-� ?� �Q3$�T"�?� }� q 3$t "�}� �� ~ 3$�T"��� �� �Q3$�T"��� �� ~ 3$�T"��� �� q 3$t "��� 2� ~ 3$�T"�2� � �Q3$�T"� � <� ~ 3$�T"�<� �� �Q3$�T"��� �� ~ 3$�T"��� 0� �Q3$�T"�0� @� q 3$t "�@� �� ~ 3$�T"��� {� �Q3$�T"�{� �� ~ 3$�T"��� �� �Q3$�T"��� �� ~ 3$�T"��� w� �Q3$�T"�w� �� ~ 3$�T"��� b� �Q3$�T"� �� � 0�� -� H�?� �� 0��� �� H��� � 0� � � H�� b� 0� �� � 0�� -� �; �?� �� 0��� �� �; ��� � 0� � � �; �� b� 0� �� � 0�� � ��?� �� 0��� �� V�� � 0� � � ��� b� 0� �� -� 0�?� �� 0��� b� 0� �� �� _?� �� _�� �� _�� � _ � <� _0� �� _{� �� _�� �� _w� �� _ X� }� Q}� �� ^�� �� ^�� � ^ � <� ^0� @� Q@� �� ^{� �� ^�� �� ^w� �� ^ �� �� ^�� � ^ �� � ^ �� � 1� �� � �1 � �� � 1� �� �� �B� �� � �0 � C� G� P C� G� P X� �� 0��� �� 0� � <� 0�0� �� 0�{� �� 0��� �� 0�w� �� 0� X� �� �1 ��� �� �1 � � <� �1 �0� �� �1 �{� �� �1 ��� �� �1 �w� �� �1 � X� �� _�� �� _ � <� _0� �� _{� �� _�� �� _w� �� _ X� }� Q}� �� ^�� �� ^ � <� ^0� @� Q@� �� ^{� �� ^�� �� ^w� �� ^ X� �� ����� �� ��� � <� ���0� �� ���{� �� ����� �� ���w� �� ��� X� �� ����� �� ��� � <� ���0� �� ���{� �� ����� �� ���w� �� ��� X� }� q 3$t "�}� �� ~ 3$�T"��� �� ~ 3$�T"� � <� ~ 3$�T"�0� @� q 3$t "�@� �� ~ 3$�T"�{� �� ~ 3$�T"��� �� ~ 3$�T"�w� �� ~ 3$�T"� X� }� R}� �� V�� � V� �� �R� � <� V0� @� R@� �� V�� �� �R�{� �� V�� �� Vw� �� V X� X� @F$� X� X� P X� X� p� �� �� Z�� A� ZA� �� ��~ � <� ��~{� �� Z�� �� ��~ �� �� P }� �� S�� �� S � <� S{� �� S P� i� P � %� P %� <� P %� 3� P %� 3� P � P� �1 �{� �� �1 � � P� ���{� �� ��� � P� ���{� �� ��� � A� ZA� P� ��~{� �� Z�� �� ��~ � � Z �� �� Q �� �� Q �� �� Q <� �� 0��� �� 0�w� �� 0� <� @� q 3$t "�@� �� ~ 3$�T"��� �� ~ 3$�T"�w� �� ~ 3$�T"� <� �� �1 ��� �� �1 �w� �� �1 � <� �� _�� �� _w� �� _ <� @� Q@� �� ^�� �� ^w� �� ^ <� �� ����� �� ���w� �� ��� <� �� ����� �� ���w� �� ��� <� @� U@� �� V�� �� Vw� �� V <� �� 0��� �� 0�w� �� 0� <� �� �1 ��� �� �1 �w� �� �1 � <� �� _�� �� _w� �� _ <� @� Q@� �� ^�� �� ^w� �� ^ <� �� ����� �� ���w� �� ��� <� �� ����� �� ���w� �� ��� <� @� U@� �� V�� �� Vw� �� V I� e� ~ 3$� "P �e� �� S�� �� S�� �� S <� @� q 3$� "P �@� �� ~ 3$� "P ��� �� ~ 3$� "P �w� �� ~ 3$� "P � <� e� 0�e� s� ]s� {� }�{� �� ]�� �� ]�� �� ] �� �� T e� {� P�� �� P e� o� 0�o� {� 1��� �� 0� e� o� P �� �� �1 �w� �� �1 � �� �� ~ 3$� "P �w� �� ~ 3$� "P � �� �� ���w� �� ��� �� �� Vw� �� V �� � ~ 3$� "P �� "� Q Z� {� P�� �� P +� Z� �1 �w� �� �1 � +� Z� ���w� �� ��� +� Z� ~ 3$� "P �w� �� ~ 3$� "P � +� Z� ���w� �� ��� +� Y� ��w� �� �� +� +� �� �� �� S �� �� S � � 0��� �� 0��� �� 1� � � ���� �� U �� �� U �� �� V �� �� Q�� � ^ �� � 1� �� � �1 � �� � 1� �� � �0 � �� �� ��� #� ���� �� ���� �� �� �� �� \�� �� �U�� � \<� 0� \�� {� \�� �� \�� w� \�� b� \ � �� ]L� \� ]`� m� ]�� �� ]� (� ]H� T� ]V� \� ]�� �� ] �� �� 0�� ?� 0�L� �� 0��� � V� � 0�<� 0� 0��� .� 0�\� {� 0��� C� 0�H� v� 0��� �� 0��� �� 0��� � V� w� 0��� b� 0� �� �� 0��� �� \�� �� �U�� � \<� 0� \�� {� \�� �� \�� w� \�� b� \ �� �� 0��� �� ]� ?� 0�L� �� 0��� � ]� � 0�<� 0� 0��� {� 0��� �� 0��� w� 0��� b� 0� �� �� 0��� �� P�� � V� � 0�� 1� P1� H� VH� ]� 0�]� p� Pp� �� V�� �� 0��� �� P�� �� ]�� �� 0�� ,� 0�,� 2� P2� ?� VL� �� 0��� �� P�� �� V�� �� 0��� �� P�� �� ]�� �� 0�� � V<� �� V�� � 0� � 0� V�� .� 0�a� n� Vn� u� Pu� {� V�� �� V�� �� P�� � V� � P� C� VH� V� VV� g� Pg� v� 0��� �� P�� �� V�� �� V�� �� T�� �� V� 6� V6� A� TA� w� V�� b� V �� �� 0�� ?� 0�L� \� 0�\� �� P�� �� ]�� �� 0�� � 0�<� 0� 0��� .� 0�a� {� ]�� C� 0�H� g� 0�g� v� P�� �� 0��� �� 0�� w� 0��� b� 0� �� �� 0��� �� ]�� �� 0��� �� P�� �� ^�� �� 0�� ?� ]L� L� 0�L� �� \�� �� 0�� � 0�<� �� 0��� 0� ]�� .� ].� .� 0�a� n� 0�n� {� \�� �� P�� �� ^�� C� 0�H� g� 0�g� v� \�� �� ^�� �� 0��� �� 0�� w� 0��� b� 0� �� �� 1�� ?� 1�L� e� 1�e� � 0�� � 1�<� 0� 1��� :� 1�a� {� 0��� 0� 1�H� �� 1��� �� 0��� �� 1��� � 0�� � 1�� 6� 0�6� w� 1��� b� 1� �� �� ]{� �� ]W� \� �� =� H� p $@L$)��H� t� ~ $@L$)��L� � ~ $@L$)��`� g� p $@L$)��g� m� ~ $@L$)��a� {� ~ $@L$)��V� j� ~ $@L$)���� �� ~ $@L$)���� � ~ $@L$)��� 6� ~ $@L$)�� �� �� 0�� ?� 0�L� �� 0�� � 0�<� 0� 0��� .� 0�.� .� M�a� {� 0��� 0� 0�0� 0� N�0� C� ]H� v� 0��� �� 0��� �� Q��� �� 0�� 1� 0�1� 6� Q�6� w� 0��� b� 0� �� �� 0�� ?� 0�L� �� 0�� � 0�<� 0� 0��� .� 0�.� .� �; �a� {� 0��� 0� 0�0� C� �; �H� v� 0��� �� 0��� �� �; ��� �� 0�� 1� 0�1� 6� �; �6� w� 0��� b� 0� �� �� 0�� ?� 0�L� �� 0�� � 0�<� 0� 0��� .� 0�.� .� ��a� {� 0��� 0� 0�0� 0� ��0� C� _H� v� 0��� �� 0��� �� 8��� �� 0�� 1� 0�1� 6� ;�6� w� 0��� b� 0� �� �� \ � �� 0�� ,� 0��� � 0��� � 0� � �� � �� ,� � ��� � � ��� � � � � �� ���� ,� ����� � ����� � ��� � �� ]� ,� ]�� � ]�� � ] � �� 1�� � 1�<� 0� 1��� {� 1��� �� 1��� w� 1��� b� 1� � `� R�� �� R � `� P�� �� P *� `� X�� �� X 7� >� 0�>� `� Q 7� `� Y E� `� T �� �� Q �� �� Q v� �� P `� v� ]�� �� ] `� q� Pq� v� }�� �� P�� �� } m� q� p8q� v� Pv� v� }#8 v� v� P `� `� � `� `� P `� `� p� �� � � ��� � � � �� � 0��� � 0� �� � ]�� � ] �� �� �� �� � ]�� � ] �� � V � � P� � V�� � V �� � ^�� � ^ �� �� ] �� �� ],� ?� ] � 0� ] � .� ] �� �� ] �� �� V<� `� Vm� {� V�� �� V�� �� V� �� V�� W� V\� b� V �� �� ��L� � ��<� �� ��a� {� ���� �� ���� w� ���� b� �� �� �� 0�L� � 0�<� �� 0�a� {� 0��� �� 0��� w� 0��� b� 0� �� �� 0�L� � 0�<� �� 0�a� {� 0��� �� 0��� w� 0��� b� 0� �� �� @D$� �� �� P �� �� p� �� �� v�m� �� v� m� {� v � ����N$v� ����!� �� �� ] �� �� P t� �� ]�� �� ]E� W� �� B� �� ^�� �� P�� �� ^�� W� ^\� b� ^ �� �� V� B� V�� �� V � � P� %� v#` � )� 0�)� 6� P6� B� ^�� �� ^ 2� 6� P B� t� ^�� �� ^�� �� ^�� E� ^\� b� ^ B� �� ���� �� ���� b� �� B� �� 0��� �� 0��� b� 0� B� �� 0��� �� 0��� b� 0� B� B� @D$� B� B� ~ B� B� p� ]� t� ~��� �� ~� �� �� ~ � ����N$~� ����!� �� �� ] t� t� P � 5� ] �� 5� _@� E� P\� �� _�� b� _ �� �� ^5� @� ^�� �� ^ �� �� P �� �� 0��� �� P5� <� P<� @� _ �� �� P �� � _\� �� _�� b� _ �� 5� ��\� �� ���� b� �� �� 5� 0�\� �� 0��� b� 0� �� 5� 0�\� �� 0��� b� 0� �� �� @D$� �� �� P �� �� p� �� � ��� &� � �� � � ����N$� ����!� !� &� ] � � P u� z� ] �� �� P�� �� ] �� �� U�� �� ��~.� 7� P z� �� _&� .� _@� b� _ ~� �� P�� �� #` z� �� 0��� �� P&� *� P �� �� P �� �� U�� �� ��~ � 5� _ t� �� ^�� �� ^E� W� ^ �� � V� � V � � ] � �� ��L� � ��`� m� ��a� {� ���� �� ��� 0� ��H� �� ���� � ��� w� �� � �� 0�L� � 0�`� m� 0�a� {� 0��� �� 0�� 0� 0�H� �� 0��� � 0�� w� 0� � �� 0�L� � 0�`� m� 0�a� {� 0��� �� 0�� 0� 0�H� �� 0��� � 0�� w� 0� '� =� 2�H� V� 2� '� =� \H� V� \ '� 1� P1� =� VH� V� V 5� =� PH� V� P =� H� V`� m� V R� ]� ] R� �� ���� �� ��V� g� ���� �� ���� �� ��6� w� �� R� �� 0��� �� 0�V� g� 0��� �� 0��� �� 0�6� w� 0� R� �� 0��� �� 0�V� g� 0��� �� 0��� �� 0�6� w� 0� f� p� Pp� �� V�� �� V�� �� T�� �� V6� A� TA� w� V f� �� \�� �� \6� w� \ t� �� P�� �� P�� �� ^6� E� ^ f� �� �� �� �� �� f� p� Pp� �� V�� �� V f� �� \�� �� \ }� �� P �� �� \ �� �� V �� �� �� �� �� @F$� �� �� v �� �� v#� E� X� PX� _� T_� w� ^ `� w� ^ �� �� V�� �� V �� �� 0��� � V\� a� 0��� � V �� � V �� �� \�� �� �U�?� L� \ �� �� \�� �� �U�?� L� \ L� Q� \ Q� \� ] Q� � ��a� {� ��g� v� ���� �� ���� � ��� 6� �� Q� � 0�a� {� 0�g� v� 0��� �� 0��� � 0�� 6� 0� Q� � 0�a� {� 0�g� v� 0��� �� 0��� � 0�� 6� 0� �� �� \n� {� \ �� �� \n� {� \ �� �� ]a� n� ] �� �� V �� �� V .� :� 0�C� H� 0�v� �� ^�� �� 0��� �� 0� v� �� ^ 0� C� V 0� C� V � 1� V � 1� �1 � � � p � 0� R �p �p U�p q Sq q �U�q 6q U6q Jq �U�Jq �q S �p �p T�p q �T�q 3q T3q Jq �T�Jq [q T[q �q �T� �p �p Q�p q �Q�q q Qq Jq �Q�Jq [q Q[q �q �` �p �p Pq q P q <q �PJq [q P �p �p 0� _q dq Pdq �q X �p �p S �p �p 0� q q P q <q �P q =q 0� q =q 1� q =q �0 � q =q 0� q =q �0 � � �� U�� �� [�� � �U�� -� U-� �� �U��� �� U�� &� �U�&� )� U)� 6� [6� [� ��~[� X� �U� � �� T�� � �T�� -� T-� �� �T��� �� T�� &� �T�&� 6� T6� X� �T� � �� Q�� � ]� � �Q�� -� Q-� �� ]�� �� Q�� &� ]&� 6� Q6� X� ] � �� R�� � �R�� -� R-� �� V�� � �R�� o� Vo� �� �R��� �� R�� �� V�� � �R�� � V � &� �R�&� 6� R6� ϯ Vϯ �� �R��� � V� 5� �R�5� X� V � ݬ 0�� �� 0��� �� ��� � 0�&� ԯ 0��� � 0�� *� ��5� X� 0� D� �� q 3$t "��� �� } 3$t "��� � } 3$�T"�� � �Q3$�T"�� -� q 3$t "�-� �� } 3$�T"��� �� q 3$t "��� &� } 3$�T"�&� 6� q 3$t "�6� X� } 3$�T"� D� �� 0��� ݬ @�� y� 0�y� �� @��� �� 0��� � @�� X� 0� D� �� 0��� ݬ �1 �� y� 0�y� �� �1 ��� �� 0��� � �1 �� X� 0� D� �� 0��� �� ��� y� 0�y� �� V�� �� 0��� � ��� X� 0� D� ݬ 0�� ӭ 0�ӭ � \� X� 0� _� z� Y� -� Y&� 6� Y6� [� ��~ � -� Q-� �� ]� �� ]�� � ]&� 6� Q6� ԯ ]�� � ]5� X� ] w� �� ]�� � ] �� �� ] �� �� 1� �� �� �1 � �� �� 1� �� �� �B� �� �� �0 � � �� P � �� P � w� 0�� y� 0�� � 0�&� ԯ 0��� � 0�5� X� 0� � w� �1 �� y� �1 �� � �1 �&� ԯ �1 ��� � �1 �5� X� �1 � � -� Y&� 6� Y6� [� ��~ � -� Q-� w� ]� y� ]� � ]&� 6� Q6� ԯ ]�� � ]5� X� ] � w� ���� y� ���� � ���&� ԯ ����� � ���5� X� ��� � w� ���� y� ���� � ���&� ԯ ����� � ���5� X� ��� � -� q 3$t "�-� w� } 3$�T"�� y� } 3$�T"�� � } 3$�T"�&� 6� q 3$t "�6� ԯ } 3$�T"��� � } 3$�T"�5� X� } 3$�T"� � -� R-� w� V� o� Vo� y� �R�� � V&� 6� R6� ϯ Vϯ ԯ �R��� � V5� X� V � � @F$� � � P � � p� 8� n� Z� 1� Z1� y� ��~� � ��~�� � Z � 4� ��~ E� e� P -� w� S� y� S� � S�� 4� S @� Y� P� � P � � P � � P � � P �� @� �1 ��� 4� �1 � �� @� ����� 4� ��� �� @� ����� 4� ��� �� 1� Z1� @� ��~�� � Z � 4� ��~ �� �� Z b� n� Q b� i� Q b� i� Q 2� ʯ 0�4� � 0�5� X� 0� 2� 6� q 3$t "�6� ʯ } 3$�T"�4� � } 3$�T"�5� X� } 3$�T"� 2� ʯ �1 �4� � �1 �5� X� �1 � 2� [� ��~ 2� 6� Q6� ʯ ]4� � ]5� X� ] 2� ʯ ���4� � ���5� X� ��� 2� ʯ ���4� � ���5� X� ��� 2� 6� U6� ʯ V4� � V5� X� V 2� ʯ 0�4� � 0�5� X� 0� 2� ʯ �1 �4� � �1 �5� X� �1 � 2� [� ��~ 2� 6� Q6� ʯ ]4� � ]5� X� ] 2� ʯ ���4� � ���5� X� ��� 2� ʯ ���4� � ���5� X� ��� 2� 6� U6� ʯ V4� � V5� X� V ?� [� } 3$� "P �[� �� S�� ʯ S4� =� S 2� 6� q 3$� "P �6� ʯ } 3$� "P �4� � } 3$� "P �5� X� } 3$� "P � 2� [� 0�[� k� \k� s� |�s� �� \�� ʯ \4� =� \ �� �� T [� s� P�� �� P [� g� 0�g� s� 1��� ʯ 0� [� g� P =� � �1 �5� X� �1 � =� � } 3$� "P �5� X� } 3$� "P � =� � ���5� X� ��� =� � V5� X� V v� �� } 3$� "P ��� �� Q Ͱ � PJ� X� P �� Ͱ �1 �5� J� �1 � �� Ͱ ���5� J� ��� �� Ͱ } 3$� "P �5� J� } 3$� "P � �� Ͱ ���5� J� ��� �� ̰ ��5� I� �� �� �� �� �� �� V �� �� V �� �� 0�~� �� 0��� �� 1� �� �� ��~� �� U �� �� U ӭ � 0�� � 1� z� �� Q�� �� ] z� �� 1� z� �� �1 � z� �� 1� z� �� �0 � �� �� ��� *� �� �� �� [� *� [ �� έ 0�ӭ ӭ \ � &� 0�ԯ �� 0�� 5� 0� �� �� 0��� έ Pέ ӭ 0� � � Pԯ ٯ P� 5� 0� �� ӭ 0� � &� 0�ԯ ٯ 0�� +� 0�+� 5� A� �� ӭ 0� � &� 0�ԯ ٯ 0�� +� 0�+� 5� �1 � �� ӭ 0� � &� 0�ԯ ٯ 0�� +� 0�+� 5� � �� �� �� ĭ έ P � � P � *� �� � +� �1 � � � p� *� R � U � \� � �U�� U m ��~m � �U�� ��~ ) �U�) G UG � �U�� � ��~� � �U�� � U� � \� O ��~O s! �U�s! �! ��~�! �" �U��" �" ��~�" �# �U��# �# ��~�# �( �U� � f Tf � �T�� T ) �T�) G TG � �T�� � T� �( �T� � | Q| � ^� � �Q�� Q m ^m � �Q�� ^ ) �Q�) G QG � �Q�� � ^� � �Q�� � Q� O ^O s! �Q�s! �! ^�! �" �Q��" # ^# �# �Q��# �# ^�# �( �Q� � _ R_ � �R�� R m ]m � �R�� ] ) �R�) G RG � �R�� � ]� � �R�� � R� O VO s! �R�s! �! ]�! �" �R��" �# V�# �# �R��# $ V$ �( �R� � � 0�� G 0�G � ��� � 0�� Y 0�Y � ��� � ��s! �! 0��" �# 0��# $ 0� f q 3$t "�f | q 3$�T"�| � ~ 3$�T"�� � �Q3$�T"�� q 3$t "� m ~ 3$�T"�m � �Q3$�T"�� ~ 3$�T"� ) �Q3$�T"�) G q 3$t "�G � �Q3$�T"�� � ~ 3$�T"�� � �Q3$�T"�� � q 3$t "�� O ~ 3$�T"�O s! �Q3$�T"�s! �! ~ 3$�T"��! �" �Q3$�T"��" # ~ 3$�T"�# �# �Q3$�T"��# �# ~ 3$�T"��# �( �Q3$�T"� � 0�� � 4�� 0� ) 4�) � 0�� � 4�� � 0�� � 0�� �( 0� � 0�� � �; �� 0� ) �; �) � 0�� � �; �� � 0�� � 0�� �( 0� � 0�� � � �� 0� ) V) � 0�� � � �� � 0�� � 0�� �( 0� � 0�� � 0�� � ^� � 0�� �( 0� 2 M _� _ r h \� \� � \� O _s! �! \�" �" _�# �# _ � Q m ^m � �Q�� ^ ) �Q�� � �Q�� � ^� � Q� O ^O Y �Q�s! �! ^�" # ^# �# �Q��# �# ^�# $ �Q� m ~ ^� � ^ � � ^ � � 1� � � �1 � � � 1� � � �B� � � �0 � � � P � � P � m 0�� 0�� � 0�� Y 0�s! �! 0��" �# 0��# $ 0� � m �1 �� �1 �� � �1 �� Y �1 �s! �! �1 ��" �# �1 ��# $ �1 � � _ h \� \� � \� O _s! �! \�" �" _�# �# _ � Q m ^� ^� � ^� � Q� O ^O Y �Q�s! �! ^�" # ^# �# �Q��# �# ^�# $ �Q� � m ���� ���� � ���� Y ���s! �! ����" �# ����# $ ��� � m ���� ���� � ���� Y ���s! �! ����" �# ����# $ ��� � q 3$t "� m ~ 3$�T"�� ~ 3$�T"�� � ~ 3$�T"�� � q 3$t "�� O ~ 3$�T"�O Y �Q3$�T"�s! �! ~ 3$�T"��" # ~ 3$�T"�# �# �Q3$�T"��# �# ~ 3$�T"��# $ �Q3$�T"� � R m ]� ]� � ]� � R� O VO Y �R�s! �! ]�" �# V�# $ V � � @F$� � � P � � p� ) Z Z� � Z� ��~� � ��~s! �! Z�! �! ��~ 3 Q P m S� S� � Ss! �! S � � P� � P � � P � � P � � P � � �1 �s! �! �1 � � � ���s! �! ��� � � ���s! �! ��� � � Z� � ��~s! �! Z�! �! ��~ � � Z N Z Q N U Q N U Q � O 0��" �# 0��# $ 0� � � q 3$t "�� O ~ 3$�T"��" # ~ 3$�T"�# �# �Q3$�T"��# �# ~ 3$�T"��# $ �Q3$�T"� � O �1 ��" �# �1 ��# $ �1 � � O _�" �" _�# �# _ � � Q� O ^�" # ^# �# �Q��# �# ^�# $ �Q� � O ����" �# ����# $ ��� � O ����" �# ����# $ ��� � � U� O V�" �# V�# $ V � O 0��" �# 0��# $ 0� � O �1 ��" �# �1 ��# $ �1 � � O _�" �" _�# �# _ � � Q� O ^�" # ^# �# �Q��# �# ^�# $ �Q� � O ����" �# ����# $ ��� � O ����" �# ����# $ ��� � � U� O V�" �# V�# $ V � ~ 3$� "` � O \�" �" \�# �# \ � � q 3$� "` �� O ~ 3$� "` ��" # ~ 3$� "` �# �# �Q3$� "` ��# �# ~ 3$� "` ��# $ �Q3$� "` � � 0� ] }� O ]�" �" ]�# �# ] 5 ? p P@ I P 0� 1�5 O 0� P �" �# �1 ��# $ �1 � �" # ~ 3$� "` �# �# �Q3$� "` ��# $ �Q3$� "` � �" �# ����# $ ��� �" �# V�# $ V 0# @# �Q3$� "` �@# R# Q �# �# P$ $ P [# �# �1 ��# $ �1 � [# �# ����# $ ��� [# �# �Q3$� "` ��# $ �Q3$� "` � [# �# ����# $ ��� [# �# ���# $ �� [# [# �� = B V = B V � � 0� $ 0�$ ) 1� � � �� # U # U � � 0� � � 0�� � 1� M | Q| � ��~� � ^ M � 1� M � �1 � M � 1� M � �0 � G R �� g � ��� � �� g � \� � \� 9 ��~� , \9 r ��~� = \J � \� � \� K! ��~K! s! \�! �! \" I" \d" �" \�" �" ��~�" �" \�# �# \$ �& \�& �( \ g � 0�� � ]� � 0�� � ]� 9 ��~Y h ]� � ]� � 0� , 0�9 r ��~� = ]J � ]� � 0�� � 0�� 9! ��~9! A! ]A! K! ��~K! _! ]i! s! 0��! �! 0��! �! 0��! " ]" I" ]_" �" ]�" �" ]�" �" ��~�" �" ]�# �# 0��# �# ]$ �& ]�& �( ] � ��~� � ��~K! _! ��~z" �" ��~ g l 0�l � \� � \� 9 ��~� , \9 r ��~� = \J � \� � \� K! ��~K! s! \�! �! \" I" \d" �" \�" �" ��~�" �" \�# �# \$ �& \�& �( \ g � 0�� h 0�� � 0�� � S� � 0� , 0�9 r 0�� � S� � 0�� � 0�� ! 0� ! A! SA! _! 0�i! s! 0��! �! 0��! " 0�" I" 0�_" d" Sd" �" 0��" �" 0��" �" S�" �" 0��# �# 0�$ �& 0��& �( 0� g � 0�� � 0�� � ^� , 0�9 r 0�� � ^� � 0�� 9! 0�9! A! SA! s! 0��! �" 0��# �# 0�$ �( 0� g � 0�� � P� � _� � 0�� h ^h � 0�� � _� ^ 9 ��~Y h ^� � 0�9 r ��~� � ^� = 0�J ] 0�] � ^� � 0�� � 0�� ! ��~ ! A! 0�A! K! ��~K! V! 0�V! _! Pi! s! P�! �! P�! �! _�! " ^" " ^ " I" 0�d" �" 0��" �" 0��# �# _�# �# 0�$ �& 0��& �( 0� g � 0�� � ]� 0� � S� � 0�� � P� � S� � 0�� h _h � S� � ]� * _* 9 ��~Y h _� � ]9 ^ _^ r ��~� � _� � S� � _� = SJ ] S] � _� � S� � 0�� � _� ! ��~! K! 0�K! _! _i! s! 0��! �! 0��! �! ]�! �! 0��! " _" " _ " I" 0�d" z" 0�z" �" P�" �" S�" �" 0��" �" _�# �# 0�$ �& S�& �( S Y t ��~� � ��0% 5% ��_% y% 0� g � 0�� h 0�� � 0�9 r 0�� � 0�� � 0�� ! 0�! ! S ! A! 0�A! K! SK! _! 0�i! s! 0��! �! 0��! " 0�" I" 0�d" �" 0��" �" 0��# �# 0�$ �& 0��& �( 0� g � 0�� Y 0�Y h =�� � 0�� � 9�9 r 0�� � 0�� � 0�� � 9�� _! 0�i! s! 0��! �! 0��! �! 9��! " =�" ?" 0�?" I" ;�d" �" 0��" �" 0��# �# 0�$ �& 0��& �( 0� g � 0�� Y 0�Y h �; �� � 0�� � �; �9 r 0�� � 0�� � 0�� � �; �� _! 0�i! s! 0��! �! 0��! �! �; ��! " �; �" ?" 0�?" I" �; �d" �" 0��" �" 0��# �# 0�$ �& 0��& �( 0� g � 0�� Y 0�Y h m�� � 0�� � 9�9 r 0�� � 0�� � 0�� � 2�� _! 0�i! s! 0��! �! 0��! �! 6��! " m�" ?" 0�?" I" F�d" �" 0��" �" 0��# �# 0�$ �& 0��& �( 0� g l \ � � 1��! �! 1��# �# 1� � � 0��! �! 0��# �# 0� � � P� � _�! �! P�! �! _�# �# _ � � 1��! �! 1��# �# 1� � � p � � 1� � � ] � � ] �! �! P�! �! S�# �# S �! �! _�# �# _ �! �! P�# �# P�# �# ] �! �! S�# �# S � � _� � _ � � ] � _d" z" _�# �# _ � ]d" z" ]�# �# ] � � U� \d" z" \�# �# \ � P Sd" h" Ph" u" S�# �# S S Y Sh � S� � S = SJ ] S� � S$ 0% S5% _% S�% �& S�& �( S � ��� � ��9 r ��� � ��� i! ���! " ��z" �" ��$ �( �� � 0�� � 0�9 r 0�� � 0�� i! 0��! " 0�z" �" 0�$ �( 0� � 0�� � 0�9 r 0�� � 0�� i! 0��! " 0�z" �" 0�$ �( 0� @D$� Q q� - Y s�� � s� = s�� � s� � � P + = P I Y P� � P � � 0� � � S �$ �$ ��~ % 0% �� [$ �$ _�$ �$ P�$ 0% _5% _% _�% |& _�& �& _�& �( _ $ [$ S�$ �$ S|& �& S $$ 4$ P4$ A$ q� $ E$ 0�E$ R$ PR$ [$ _�$ �$ _ N$ R$ P [$ �$ _�$ % _5% p% _�% |& _�& �& _�& �( _ [$ �$ ���$ y% ���% |& ���& �& ���& �( �� [$ �$ 0��$ y% 0��% |& 0��& �& 0��& �( 0� [$ �$ 0��$ y% 0��% |& 0��& �& 0��& �( 0� [$ [$ @D$� [$ [$ [$ [$ p� v$ �$ ��$ % �5% Y% ��& �& � �$ % P G% Y% P �$ �$ P�& �& P �& �& 0� % % _ '& >& ��~ �% & X& '& ��~I& S& P�& �& ��~)' �' X�' �' ��~�' !( X!( 9( ��~F( ^( ��~ �% �% _>& I& _S& |& _ �% �% P �% �% 0��% �% P�% �% X>& E& X �% �% P �% & X& '& ��~�& �& ��~)' �' X�' �' ��~�' !( X!( 9( ��~F( ^( ��~ �% >& ���& �( �� �% >& 0��& �( 0� �% >& 0��& �( 0� �% �% @D$� �% �% P �% �% p� �% & x�& '& ��~#��& �& ��~#�)' J' x��' !( x�!( 9( ��~#� 8' J' P ( !( P & '& P�& �& P �& �& 0�!( 9( 0� ' ' X' ' ��~ �' �' P�' �' ��~ �' �' U�' �' ��~V( ^( P v' �' X�' �' ��~F( V( ��~ z' �' P�' �' x#` v' �' 0��' �' P�' �' UF( J( U �' �' P �' �' U '& 8& X �$ �$ _ % 0% _ t � S� � S � � ��~�# $ &� � h ��� � ��9 r ��� � ��� � ��= J ��] � ��� i! ���! " ��z" �" ���" �" �� � h 0�� � 0�9 r 0�� � 0�� � 0�= J 0�] � 0�� i! 0��! " 0�z" �" 0��" �" 0� � h 0�� � 0�9 r 0�� � 0�� � 0�= J 0�] � 0�� i! 0��! " 0�z" �" 0��" �" 0� � � S� � S � � ]� � _ � � _ � � _ � � 0�� � 0�K! V! 0��" �" 0� � � �� � �K! V! ��" �" � � � d�� � d�K! V! d��" �" d� � � X� ��~K! V! ��~ � � R� r� = R= I r�I � R� � ��~� � ��~K! R! R � h ���� � ���9 r ���� � ���� � ���= J ���] � ���� i! ����! " ����" �" ��� � � �O� � � �O� K! V! �O� �" �" �O� 9 � PK! R! P 9 E PE E p�E U PU � UK! N! UN! R! p 0p 0*( � 9 � 0�� � 0�K! V! 0��" �" 0� � � 0� ( q $BO$,�� � X P b Xb � ��~� � ��~K! R! XR! V! ��~�" �" ��~ � h ��� � ��9 r ��� � ��� � ��= J ��] � ��� i! ���! " ���" �" �� � h 0�� � 0�9 r 0�� � 0�� � 0�= J 0�] � 0�� i! 0��! " 0��" �" 0� � h 0�� � 0�9 r 0�� � 0�� � 0�= J 0�] � 0�� i! 0��! " 0��" �" 0� ( Q z � �� � ��" �" � z � 0�� � 0��" �" 0� z � P� ; S� � S�" �" S z � R� � ��~� � ��~ z � U � � P� � ^� � ^�" �" ^ � Q� � ��~� � ��~ � 0�\ i Pi n Y} � Y� � Y� � Y� � Y� � T� � t��" �" 0� � � U # h 3�� Y 3�9 r 3�� � 3�= E 3�] � 3�� ! 3� # h �� �� T] � ��� # 4 ~"#�� ~"#�] n ~"#� # h ���� Y ���9 r ���� � ���= E ���] � ���� ! ��� 8 K PK h S , P, Y S9 r S� � S= E Sr � P� � S� ! S / Y ��~9 r ��~� � ��~= J ��~� K! ��~�" �" ��~ � 4 ^9 h ^� ! ^ N Y ��~9 r ��~= J ��~� K! ��~�" �" ��~ � � P� P � � ]� / ]/ 9 q� ! ] � � T� T � � Q9 E QE r ��~ O Y S= E S Y h ^� � 0�� � 0��! �! _�! " ^?" I" 0� Y h ^�! �! _�! " ^ h x _� ]_! i! _�! �! 0�" " _�" �" S�# �# ]�& �& _ h x _� ]�" �" S�# �# ]�& �& _ � � ] 0�� � ]� � 0�9! A! ]�! �! 0�_" d" ]�" �" ]�& �& ] � � ]� � ] � � \ 9 \ � � \ 9 \ � � Sr � S � � Sr � S � � ] � � �1 � � � p� � R ! ! _ ! ! ^A! K! ^ 5! 9! S Y � 82 � Y � 1� Y � �� Y o po � X Y � (� Y � 0� �� Y� UY� �� �U��� �� U�� �� �U��� �� U�� �� �U��� �� U�� Z� �U� �� V� TV� �� �T��� �� T�� �� �T��� �� T�� �� �T��� �� T�� Z� �T� �� 9� Q9� �� ]�� �� �Q��� �� Q�� >� ]>� �� �Q��� �� ]�� �� Q�� � �Q�� f� ]f� �� �Q��� �� Q�� x� ]x� �� �Q��� �� ]�� � �Q�� =� ]=� Z� �Q� �� O� RO� �� �R��� �� R�� >� S>� �� �R��� �� S�� �� R�� � �R�� f� Sf� �� �R��� �� R�� x� Sx� �� �R��� �� S�� � �R�� =� S=� Z� �R� �� �� 0��� >� 0�>� �� ���� �� 0��� �� ��� f� 0�f� w� ���� x� 0��� �� 0��� �� ��2� =� ��� =� 0� �� 9� q 3$t "�9� V� } 3$t "�V� �� } 3$�T"��� �� �Q3$�T"��� �� q 3$t "��� >� } 3$�T"�>� �� �Q3$�T"��� �� } 3$�T"��� �� q 3$t "��� � �Q3$�T"�� f� } 3$�T"�f� �� �Q3$�T"��� �� q 3$t "��� x� } 3$�T"�x� �� �Q3$�T"��� �� } 3$�T"��� � �Q3$�T"�� =� } 3$�T"�=� Z� �Q3$�T"� �� e� 0�e� �� (��� y� 0�y� �� (��� C� 0�C� J� (�J� Z� 0� �� e� 0�e� �� �; ��� y� 0�y� �� �; ��� C� 0�C� J� �; �J� Z� 0� �� e� 0�e� g� � ��� y� 0�y� �� V�� C� 0�C� J� � �J� Z� 0� �� �� 0��� �� 0��� �� \�� Z� 0� � '� ^�� >� ^�� �� ^� f� ^�� x� ^�� �� ^� =� ^ �� �� Q�� >� ]�� �� ]� f� ]�� �� Q�� x� ]�� �� ]� =� ] (� 9� ]� J� ] � C� ] � C� 1� � C� �1 � � C� 1� � � �B� � C� �0 � �� �� P �� �� P �� (� 0��� y� 0�J� f� 0��� x� 0��� �� 0�� =� 0� �� (� �1 ��� y� �1 �J� f� �1 ��� x� �1 ��� �� �1 �� =� �1 � �� (� ^�� y� ^J� f� ^�� x� ^�� �� ^� =� ^ �� �� Q�� (� ]�� y� ]J� f� ]�� �� Q�� x� ]�� �� ]� =� ] �� (� ����� y� ���J� f� ����� x� ����� �� ���� =� ��� �� (� ����� y� ���J� f� ����� x� ����� �� ���� =� ��� �� �� q 3$t "��� (� } 3$�T"��� y� } 3$�T"�J� f� } 3$�T"��� �� q 3$t "��� x� } 3$�T"��� �� } 3$�T"�� =� } 3$�T"� �� �� R�� (� S�� y� SJ� f� S�� �� R�� x� S�� �� S� =� S �� �� @F$� �� �� P �� �� p� �� � [�� 5� [5� y� ��~J� f� ��~E� h� [h� x� ��~ �� � P �� (� \�� y� \J� f� \E� x� \ @� Y� PJ� O� P O� f� P O� ]� P O� ]� P � @� �1 �E� x� �1 � � @� ���E� x� ��� � @� ���E� x� ��� � 5� [5� @� ��~E� h� [h� x� ��~ � � [ � � Q � � Q � � Q �� ;� 0��� �� 0�� =� 0� �� �� q 3$t "��� ;� } 3$�T"��� �� } 3$�T"�� =� } 3$�T"� �� ;� �1 ��� �� �1 �� =� �1 � �� ;� ^�� �� ^� =� ^ �� �� Q�� ;� ]�� �� ]� =� ] �� ;� ����� �� ���� =� ��� �� ;� ����� �� ���� =� ��� �� �� U�� ;� S�� �� S� =� S �� ;� 0��� �� 0�� =� 0� �� ;� �1 ��� �� �1 �� =� �1 � �� ;� ^�� �� ^� =� ^ �� �� Q�� ;� ]�� �� ]� =� ] �� ;� ����� �� ���� =� ��� �� ;� ����� �� ���� =� ��� �� �� U�� ;� S�� �� S� =� S �� �� } 3$� "P ��� � V� ;� V�� �� V �� �� q 3$� "P ��� ;� } 3$� "P ��� �� } 3$� "P �� =� } 3$� "P � �� �� 0��� �� \�� �� |��� � \� ;� \�� �� \ � � T �� �� P � 0� P �� �� 0��� �� 1�� ;� 0� �� �� P �� �� �1 �� =� �1 � �� �� } 3$� "P �� =� } 3$� "P � �� �� ���� =� ��� �� �� S� =� S �� �� } 3$� "P ��� � Q F� c� P*� =� P � F� �1 �� *� �1 � � F� ���� *� ��� � F� } 3$� "P �� *� } 3$� "P � � F� ���� *� ��� � E� ��� )� �� � � �� �� �� ] �� �� ] e� g� 0�~� �� 0��� �� 1� e� g� ��~� �� U �� �� U �� �� 0��� �� 1� �� �� �� �� �� �� '� 9� Q9� e� ] '� e� 1� '� e� �1 � '� e� 1� '� e� �0 � >� �� �U��� �� �U��� � �U�f� �� �U�x� �� �U��� � �U�=� Z� �U� >� �� ���� �� ��f� w� ���� �� ��2� =� �� >� �� 0��� �� \�� �� 0��� �� \�� � 0�f� r� 0�r� w� \w� �� 0�x� �� 0��� � 0�=� Z� 0� X� � p @E$0.��� �� }#�@E$0.���� �� S�� �� p @E$0.���� �� P�� �� S�� �� Sx� �� S�� �� P�� �� ���� �� }#�@E$0.��2� =� }#�@E$0.��C� ]� Sj� � S=� Z� S >� �� 0��� �� P�� �� \�� �� 0��� �� 0��� �� 0��� �� P�� �� ^�� �� Pf� �� 0�x� �� 0��� C� 0�C� P� ^P� �� 0��� �� P�� �� ^�� � 0�=� Z� 0� >� �� 0��� �� 0��� �� 0��� �� 0�f� �� 0�x� �� 0��� n� 0�n� �� _�� � 0�=� M� 0�M� Z� _ >� �� 0��� �� 0��� � 0�� W� ^W� �� 0��� �� 0�f� �� 0��� �� ^x� �� ^�� �� 0��� P� 0�P� ]� ^]� � 0�=� D� UD� M� ^M� Z� 0� >� �� 0��� �� 0��� ;� 0�;� �� V�� �� \�� �� 0�f� �� 0�x� �� 0��� C� 0�C� P� \P� ]� V]� j� 0�j� {� V{� �� \�� � 0�=� M� 0�M� Z� \ W� �� 1�j� �� 1��� �� 0�M� Z� 1� >� �� 0��� �� 0��� �� 0��� �� 0�f� �� 0�x� �� 1��� �� 0��� � 0�=� Z� 0� >� �� 0��� �� 0��� �� 0��� �� 0�f� �� 0�x� �� �; ��� �� 0��� � 0�=� Z� 0� >� �� 0��� �� 0��� �� 0��� �� 0�f� �� 0�x� �� u ��� �� 0��� � 0�=� Z� 0� M� X� @E$� M� X� } X� X� P c� �� ���� �� ��2� =� �� �� �� S�� �� �� c� j� p @I$0.��j� � p @F$0.��� �� }#�@F$0.���� �� P�� �� Sw� �� S�� �� S�� �� }#�@F$0.��2� =� }#�@F$0.��]� j� S c� �� 0��� �� Vw� �� V�� �� V�� � 0� � 2� V2� C� 0�]� j� V c� �� 0��� �� 0�w� �� 0�x� �� 0��� �� >��� ]� 0�]� j� >�j� � 0�=� Z� 0� c� �� 0��� �� 0�w� �� 0�x� �� 0��� �� �; ��� ]� 0�]� j� �; �j� � 0�=� Z� 0� c� �� 0�w� �� 0��� �� � ��� C� 0�]� j� � � c� c� @I$� c� c� } c� c� P j� j� @F$� j� j� } j� j� P �� � `� � �� � h� � �� � \ �� �� P�� � V �� �� V �� �� V � � h� � � � `� � � � \ �� �� V]� j� V �� �� V]� j� V �� �� Vw� �� V �� � �� � �� � �� � �� � V �� �� P�� � ^ � � ^ � � ^ �� � �� � �� � �� � �� � V #� 7� T=� D� T #� ;� ^=� D� UD� M� ^ #� -� P-� 7� ~=� D� u N� W� ^P� ]� ^ x� �� ^ x� �� ^ W� W� V �� �� 0��� �� _ �� �� _ �� �� \C� P� \ �� �� ^ m� r� \ r� �� \M� Z� \ r� v� _ v� {� \ {� �� VM� Z� V {� �� VM� Z� V `� �� U�� /� �U�/� n� Un� c� �U�c� �� U�� z� �U�z� }� U}� � �U� `� �� T�� /� �T�/� n� Tn� c� �T�c� �� T�� z� �T�z� �� T�� � �T� `� �� Q�� � ] � /� �Q�/� n� Qn� }� ]}� �� �Q��� �� ]�� �� �Q��� c� ]c� �� Q�� � ]� �� �Q��� � ]� -� �Q�-� K� ]K� V� �Q�V� f� ]f� z� �Q�z� �� Q�� �� ]�� �� �Q��� �� ]�� � �Q�� � ] � [� �Q�[� �� ]�� � �Q� `� �� R�� /� �R�/� n� Rn� �� S�� �� �R��� c� Sc� �� R�� �� �R��� �� S�� z� �R�z� �� R�� � S � � �R�� M� SM� �� �R��� �� S�� � �R�� � S � � �R� `� � 0�/� �� 0��� -� ���� �� 0��� �� ���� �� 0��� � ��z� � 0�� M� 0�M� `� ���� �� ���� �� 0�� � 0� �� �� q 3$t "��� �� } 3$t "��� � } 3$�T"� � /� �Q3$�T"�/� n� q 3$t "�n� }� } 3$�T"�}� �� �Q3$�T"��� �� } 3$�T"��� �� �Q3$�T"��� c� } 3$�T"�c� �� q 3$t "��� � } 3$�T"�� �� �Q3$�T"��� � } 3$�T"�� -� �Q3$�T"�-� K� } 3$�T"�K� V� �Q3$�T"�V� f� } 3$�T"�f� z� �Q3$�T"�z� �� q 3$t "��� �� } 3$�T"��� �� �Q3$�T"��� �� } 3$�T"��� � �Q3$�T"�� � } 3$�T"� � [� �Q3$�T"�[� �� } 3$�T"��� � �Q3$�T"� �� �� 0��� � L�/� A� 0�A� c� L�c� �� 0��� �� L��� � 0� �� �� 0��� � �; �/� A� 0�A� c� �; �c� �� 0��� �� �; ��� � 0� �� �� 0��� �� � �/� A� 0�A� c� Vc� �� 0��� �� � ��� � 0� �� � 0�/� }� 0�}� �� \�� � 0� �� �� ^/� �� ^�� c� ^�� �� ^z� � ^� M� ^�� �� ^� � ^ H� n� Qn� �� ]�� c� ]�� �� ]z� �� Q�� � ]� M� ]�� �� ]� � ] �� �� ]�� �� ] �� �� ] �� �� 1� �� �� 2 � �� �� 1� �� �� �B� �� �� �0 � 3� 7� P 3� 7� P H� �� 0��� A� 0��� �� 0�z� � 0�� M� 0��� �� 0�� � 0� H� �� 2 ��� A� 2 ��� �� 2 �z� � 2 �� M� 2 ��� �� 2 �� � 2 � H� �� ^�� A� ^�� �� ^z� � ^� M� ^�� �� ^� � ^ H� n� Qn� �� ]�� A� ]�� �� ]z� �� Q�� � ]� M� ]�� �� ]� � ] H� �� ����� A� ����� �� ���z� � ���� M� ����� �� ���� � ��� H� �� ����� A� ����� �� ���z� � ���� M� ����� �� ���� � ��� H� n� q 3$t "�n� �� } 3$�T"��� A� } 3$�T"��� �� } 3$�T"�z� �� q 3$t "��� � } 3$�T"�� M� } 3$�T"��� �� } 3$�T"�� � } 3$�T"� H� n� Rn� �� S�� A� S�� �� Sz� �� R�� � S� M� S�� �� S� � S H� H� @F$� H� H� P H� H� p� x� �� [�� �� [�� A� ��~�� �� ��~� =� [=� M� ��~ �� �� P n� �� \�� A� \�� �� \� M� \ � !� P�� �� P �� �� P �� �� P �� �� P �� � 2 �� M� 2 � �� � ���� M� ��� �� � ���� M� ��� �� �� [�� � ��~� =� [=� M� ��~ �� �� [ �� �� Q �� �� Q �� �� Q �� � 0��� �� 0�� � 0� �� �� q 3$t "��� � } 3$�T"��� �� } 3$�T"�� � } 3$�T"� �� � 2 ��� �� 2 �� � 2 � �� � ^�� �� ^� � ^ �� �� Q�� � ]�� �� ]� � ] �� � ����� �� ���� � ��� �� � ����� �� ���� � ��� �� �� U�� � S�� �� S� � S �� � 0��� �� 0�� � 0� �� � 2 ��� �� 2 �� � 2 � �� � ^�� �� ^� � ^ �� �� Q�� � ]�� �� ]� � ] �� � ����� �� ���� � ��� �� � ����� �� ���� � ��� �� �� U�� � S�� �� S� � S �� �� } 3$� "P ��� �� V�� � V�� � V �� �� q 3$� "P ��� � } 3$� "P ��� �� } 3$� "P �� � } 3$� "P � �� �� 0��� �� \�� �� |��� �� \�� � \�� � \ �� �� T �� �� P�� �� P �� �� 0��� �� 1��� � 0� �� �� P � �� 2 �� � 2 � � �� } 3$� "P �� � } 3$� "P � � �� ���� � ��� � �� S� � S � � } 3$� "P � � 2� Q f� �� P� � P ;� f� 2 �� � 2 � ;� f� ���� � ��� ;� f� } 3$� "P �� � } 3$� "P � ;� f� ���� � ��� ;� e� ��� � �� ;� ;� �� u� z� V u� z� V �� �� 0�F� ^� 0�^� c� 1� �� �� ��F� ]� U O� ]� U }� �� 0��� �� 1� }� �� �� }� �� �� �� �� Q�� �� ] �� �� 1� �� �� 2 � �� �� 1� �� �� �0 � �� }� �U��� �� �U��� �� �U��� z� �U� � � �U�M� �� �U��� � �U� � � �U� �� -� ���� �� ���� � ��M� `� ���� �� �� �� }� 0�}� }� \�� �� 0��� �� 0��� � 0� � � \� z� 0� � � 0�M� �� 0��� � 0� � � 0� �� � p @F$0.��� -� v#�@F$0.��W� _� S�� s� S�� �� P-� z� SM� `� v#�@F$0.���� �� v#�@F$0.���� �� P�� � S � � S �� �� p @E$0.���� �� p @F$0.���� � p @I$0.��� -� v#�@I$0.��>� A� PA� _� S�� �� S� z� S � � SM� `� v#�@I$0.���� �� v#�@I$0.���� � S � � S �� 1� 0�1� W� ^W� _� 0�l� u� Pu� }� \}� }� 0��� �� P�� 3� 0�3� 3� P3� s� ^�� �� 0��� � 0�� -� ^-� z� 0� � � ^M� �� 0��� �� ^�� �� 0��� �� 0��� � ^� � 0� � H� 0�H� U� PU� [� ^[� � 0� �� }� 0��� �� 0��� 3� 0�3� �� 0��� z� 0� � � 0�M� �� 0��� � 0� � � 0�� [� _[� �� 0��� � _ �� }� 0��� �� 0��� �� 0��� �� ^�� s� 0��� �� 0��� <� 0�<� z� ^ � � 0�M� �� 0��� � 0�� � ^ � [� 0�[� _� U_� h� ^h� � 0� �� }� 0��� �� 0��� �� 0��� 3� \3� >� ]>� �� 0��� z� 0� � � 0�M� �� 0��� �� 0��� � ]� � \ � � \� [� ][� �� 0��� � ] �� 3� 1� � � 1� � [� 0��� � 1� �� }� 0��� �� 0��� s� 0��� �� 0��� � 0�� -� "�-� V� 0�V� z� %� � � 0�M� �� 0��� � 0� � � 0� �� }� 0��� �� 0��� s� 0��� �� 0��� � 0�� -� �; �-� V� 0�V� z� �; � � � 0�M� �� 0��� � 0� � � 0� �� }� 0��� �� 0��� s� 0��� �� 0��� � 0�� -� 7 �-� V� 0�V� z� b � � � 0�M� �� 0��� � 0� � � 0� �� �� @E$� �� �� v �� �� P �� �� @F$� �� �� v �� �� P �� �� @I$� �� �� v �� �� P T� �� P� � T� �� X� � T� �� \ d� k� Pk� �� ^ -� 1� ^ -� 1� ^ �� �� X� � �� �� P� � �� �� \ � -� ^V� V� 0� � -� ^ J� W� ^ � � ^ o� �� @� � o� �� H� � o� �� \ � �� P�� �� ^ �� �� ^ �� �� ^ �� �� H� � �� �� @� � �� �� \ �� �� T[� _� T �� �� ^[� _� U_� h� ^ �� �� P�� �� ~[� _� u �� �� ^� � ^ V� z� ^ V� z� ^ �� �� \ 3� 3� 0�H� [� _ H� [� _ 3� >� ]�� � ] i� s� ^ � � \ � [� ]�� � ] � � _ � � ] � [� \�� � \ � � \�� � \ p� �� U�� �� V�� �� �U��� "� V"� �� �U��� �� U�� � V� � �U�� .� V.� 8� �U�8� K� VK� U� �U�U� w� Vw� �� �U� p� �� 0��� 1� 0�1� �� V�� �� 0��� w� 0�w� �� V�� �� 0��� �� V�� �� V�� �� 0��� �� V p� �� 1��� �� 1��� �� 1��� �� 0��� �� 0��� �� 1��� �� 0��� �� 1��� �� 0� �� �� \�� �� 0��� �� 0��� �� 0� �� �� P�� �� P�� �� S�� �� P�� �� S�� �� S#� B� ���� �� S�� �� S p� �� 0��� (� 0�(� 1� V1� �� 0��� �� 0��� �� 0��� j� 0�j� j� Pj� �� \�� �� 0��� �� 0��� �� \�� �� 0��� �� P�� �� \�� �� 0� �� �� s $0)���� �� s $0)���� �� s $0)���� �� s $0)���� �� s $0)�� p� �� 0��� �� 0��� �� 0��� �� 0��� j� 0�j� �� 0��� v� 0�v� �� _ p� �� 0��� �� 0��� �� 0��� �� 0��� �� 0��� '� \'� �� 0��� �� \�� �� 0��� �� \�� :� 0�:� T� \T� X� UX� a� \a� �� 0� p� �� 0��� �� 0��� �� 0��� �� 0��� � 0� � j� ]j� t� ^t� �� 0��� �� 0��� �� ^�� �� ]�� r� 0�r� �� ]�� �� ^ '� j� 1�r� �� 1��� �� 0��� �� 1� p� �� 0��� �� 0��� �� 0��� �� 0��� �� 0��� �� G��� �� 0� p� �� 0��� �� 0��� �� 0��� �� 0��� �� 0��� �� �; ��� �� 0� p� �� 0��� �� 0��� �� 0��� �� 0��� �� 0��� �� ��� �� 0� �� :� p� � �� :� x� � �� :� ] � � P� :� \ �� �� \ �� �� \ *� :� x� � *� :� p� � *� :� ] z� �� ^ �� �� ] �� �� ]�� �� ] z� ~� _ ~� �� ^ j� j� 0��� �� _ �� �� _ j� t� ^�� �� ^ p� �� U�� �� U�� �� V �� �� p ���� �� p �� �� (� 0��� w� 0��� �� 0� �� (� 1��� w� 1��� �� 1� �� "� V"� (� �U��� � V� � �U�� .� V.� 8� �U�8� K� VK� U� �U�U� w� V�� �� �U� �� �� V �� � S�� � S �� � p� �� �� p� �� � v#h � � P� � \ b� q� Pq� w� \ b� w� V "� (� P�� �� P�� �� V "� (� \�� �� \ � 8� 0� .� 3� V .� 3� V 8� U� 0� K� U� V K� P� V 1� �� Vw� �� V�� #� VB� �� V�� �� V �� �� S#� #� �� 1� 1� v#�@I$0.��1� j� v#�@F$0.��|� �� P�� �� Sw� �� S�� � SB� Z� v#�@F$0.���� �� v#�@F$0.���� �� S 1� o� 0�o� �� \w� �� \�� #� \B� �� 0��� �� \�� �� 0��� �� \ 1� �� 0�w� �� 0��� �� 0��� �� 0��� � >�B� �� 0��� �� >��� �� 0� 1� �� 0�w� �� 0��� �� 0��� �� 0��� � �; �B� �� 0��� �� �; ��� �� 0� 1� �� 0�w� �� 0��� � � �B� �� 0��� �� � � 1� 1� @I$� 1� 1� v 1� 1� v#� O� �� `� � O� �� h� � O� �� ] ^� e� Pe� �� \ j� o� \ j� o� \ �� �� h� � �� �� `� � �� �� ] �� � \�� �� \ �� � \�� �� \ �� �� \w� �� \ �� �� V�� �� 0��� �� 0��� �� V �� �� V �� � TT� X� T �� � \T� X� UX� a� \ �� �� P�� � |T� X� u � '� \�� �� \ �� �� \ �� �� \ '� '� ] �� �� \ l $l U$l %l �U�%l +l U l $l T$l %l �T�%l +l T l $l Q$l %l �Q�%l +l Q l $l P%l *l P 0l Hl UHl Pl �U�Pl Sl U >l Hl PPl Rl P hl il P dl hl P �n �n U�n �n �U��n �n U�n �n �U� �n �n T�n �n �T��n �n T�n �n �T� �n �n u�n �n u �o �o U�o �o V�o �o P�o p U p p Vp p �U�p ,p V �o �o Q�o �o R�o p Q �o �o @D$� �o �o P �o �o p� p p Vp p �U�p ,p V u !u U!u �u S�u �u �U��u �u S�u �u �U� u )u T)u �u V�u �u P�u �u �T��u �u V�u �u �T� u *u Q*u �u \�u �u T�u �u �Q��u �u \�u �u �Q� +u 3u P Au Iu P Wu _u P _u �u \�u �u T�u �u �Q� _u �u V�u �u P�u �u �T� _u �u S�u �u �U� mu qu P u �u P �u �u P �u �u P �u �u P �u �u P <I rI UrI ~I �U� <I TI TTI VI QVI hI ThI xI QxI ~I �T� <I MI QMI VI �Q�VI aI QaI ~I �Q� VI hI u <I <I U <I <I @K$� <I <I u <I <I u#� JI VI U JI MI QMI VI �Q� JI TI TTI VI Q �v .w U.w /w �U�/w 7w U7w ~w V~w �w �U��w �w U�w �w V�w �w U�w �w �U��w �w V�w �w U�w @y V@y �y ���y �y V�y �y ���y �y V�y z ��z Ez VEz `z �� �v w Tw (w ^(w .w Q.w /w �T�/w <w T<w Zw ^Zw �w �T��w �w T�w �w ^�w �w th��w �w �T��w �w ^�w �w �T��w �x ^�x z �T�z 0z ^0z 5z �T�5z ;z ^;z `z �T� �v w Q w .w R.w /w �Q�/w 4w Q4w ~w \~w �w �Q��w �w Q�w �w \�w �w �Q��w �w \�w �w Q�w �y \�y �y �Q��y �y \�y �y �Q��y `z \ �v .w U.w /w �U�/w 7w U7w ~w V~w �w �U��w �w U�w �w V�w �w U�w �w �U��w �w V�w �w U�w @y V@y �y ���y �y V�y �y ���y �y V�y z ��z Ez VEz `z �� �v .w X/w @w X�w �w X�w �w X�w �x ��~z 5z ��~ w w Q w .w R.w /w �Q� w w Tw (w ^(w .w Q.w /w �T� w .w U.w /w �U� w .w u /w 4w Q4w ~w \�w �w \�y �y \�y �y \ /w <w T<w Zw ^Zw ~w �T��w �w �T��w �w ^�y �y �T��y �y �T� /w 7w U7w ~w V�w �w V�y �y V�y �y V |w ~w P�w �w P�w �w ^ /w <w t<w @w Q Dw Vw PVw ~w ]�w �w ]�w �w P�y �y ]�y �y ] Zw sw Psw |w ^�y �y P�y �y ^�y �y P�y �y ^ |w ~w ]�w �w ] �y �y ]�y �y ] �w �w Q�w �w \�w �w �Q��w �w Q�w �y \�y �y �Q��y �y �Q��y `z \ �w �w _�w �w tx�w .y _.y jy ��z Ez _Ez `z �� �w �w T�w �w �T#��w �w T�w �x ~��x �y �T#��y �y �T#��y z �T#�z 0z ~�0z 5z �T#�5z ;z ~�;z `z �T#� �w �w X�w �w X�w �x ��~z 5z ��~ �w �w U�w �w V�w �w U�w �w �U��w �w U�w @y V@y �y ���y �y ���y z ��z Ez VEz `z �� �w �w P�w �y ��~�y �y ��~�y `z ��~ �w �w Q�w �y \�y �y �Q��y �y �Q��y `z \ �w .y _.y jy ��z Ez _Ez `z �� �w �w T�w �x ~��x �y �T#��y �y �T#��y z �T#�z 0z ~�0z 5z �T#�5z ;z ~�;z `z �T#� �w �x ��~z 5z ��~ �w @y V@y �y ���y �y ���y z ��z Ez VEz `z �� �w ]y 0�]y �y ^�y �y ^�y z ^z `z 0� �x �x P�x �y ��~�y �y ��~�y z ��~5z ?z P?z `z ��~ �w x Px ;y ];y �y ���y �y ���y z ��z (z ](z ,z P,z Ez ]Ez `z �� �x �x P�x �y ��~�y �y ��~�y z ��~Ez `z ��~ �x �x 0��x 6y ^wy �y 0��y �y V x 5x 0�[x ex Pex ex p�z z 0�z (z P �x �x @H$��x by SEz `z S �w �w P�w �y ��~�y �y ��~�y `z ��~ �x �x P �x y Q ]y wy ��~�y z S �y �y U `z �z U�z �z �U��z �z U�z �z �U��z �z U�z �z �U� `z �z T�z �z T�z �z �T� `z �z Q�z �z �Q��z �z Q�z �z �Q��z �z Q�z �z �Q� rz rz @I$� rz rz t rz rz t#� z �z T z �z T �z �z X�z �z X �z �z X�z �z X �z �z X�z �z X �z �z U�z �z �U� �z �z T�z �z �T� �z �z Q�z �z �Q� �z { U{ @{ V@{ A{ �U�A{ O{ VO{ n{ Un{ z{ V �z { TO{ z{ S �z { Q { O{ �Q�O{ r{ Qr{ z{ �Q� &{ 8{ UA{ L{ U -{ 8{ UA{ L{ U 2{ 8{ UA{ L{ U O{ O{ @I$� O{ O{ s O{ O{ s#� ]{ n{ Un{ s{ V ]{ s{ S ]{ r{ Qr{ s{ �Q� �{ �{ U�{ �{ V�{ �{ �U��{ �{ V�{ | U| | V �{ �{ T�{ | S �{ �{ Q�{ �{ �Q��{ | Q| | �Q� �{ �{ U�{ �{ U �{ �{ U�{ �{ U �{ �{ U�{ �{ U �{ �{ @F$� �{ �{ s �{ �{ s#� �{ | U| | V �{ | S �{ | Q| | �Q� | M| UM| T| �U�T| [| U[| b| �U�b| y| Uy| �| �U��| �| U�| �| �U� | M| TM| T| �T�T| _| T_| b| �T�b| v| Tv| �| �T��| �| T�| �| �T� | M| QM| T| �Q�T| _| Q_| b| �Q�b| }| Q}| �| �Q��| �| Q�| �| �Q� )| )| @I$� )| )| t )| )| t#� 6| >| T >| M| XT| _| X B| M| XT| _| X G| M| XT| _| X �| �| U�| �| �U� �| �| T�| �| �T� �| �| Q�| �| �Q� �| �| U�| �| �U��| �| U�| �| �U��| } U } } �U� �| �| T�| �| �T��| �| T�| �| �T��| } T} } �T� �| �| Q�| �| �Q��| �| Q�| �| �Q��| } Q } } �Q� �| �| @H$� �| �| t �| �| t#� �| �| T �| �| X�| �| X �| �| X�| �| X �| �| X�| �| X �| } U } } �U� �| } T} } �T� �| } Q } } �Q� } M} UM} T} �U�T} [} U[} b} �U�b} y} Uy} �} �U� } M} TM} T} �T�T} _} T_} b} �T�b} v} Tv} �} �T� } M} QM} T} �Q�T} _} Q_} b} �Q�b} }} Q}} �} �Q� )} )} @H$� )} )} t )} )} t#� 6} >} T >} M} XT} _} X B} M} XT} _} X G} M} XT} _} X b} y} Uy} ~} �U� b} v} Tv} ~} �T� b} }} Q}} ~} �Q� ~I �I U�I #J SfJ {J S ~I �I T�I �J �� ~I �I Q�I |J V|J �J �Q� ~I �I R�I �J ]�J �J �R� ~I �I X�I �J �� �I fJ 0�fJ sJ \ �I J 0�J J PJ fJ \ �I �I Q�I �J �� �I �I P�I sJ ^ ~I �J �.< � �I J P �I �I R fJ sJ ^ �J �J P�J �N V iN N V N �N V �N �N U�N �N �U� �N �N P �N �N 0��N �N 1� �N O UO qP ^qP tP �U� �N O TO sP _sP tP �T� �N O QO tP �� �N O RO kP VkP tP �R� �N O XO oP ]oP tP �X� �N O YO jP SjP tP �Y� UP XP 0�ZP aP baP bP \ O UP 0� O UP S O UP ] O UP V O �O ���O FP QFP UP �� O UP _ O UP ^ O �O P�O FP bFP UP \ O �O P�O FP bFP UP \ZP aP baP bP \ LO UO V QO UO V lO oO �� �O �O p� �O �O S �O �O S GP UP \ �} �} U�} �} \�} �} �U��} �} \�} �} �U� �} �} T�} �} ]�} �} �T��} �} ]�} �} �T��} �} ]�} �} �T� �} �} 0��} �} P�} �} \�} �} P�} �} 0� �} �} 0��} �} P�} �} V�} �} V�} �} P �} �} 0��} �} 0� �} �} V�} �} V �} �} V�} �} V ~ ;~ U;~ z~ _z~ {~ �U�{~ �~ _�~ �~ �U��~ U �U� ' _ ~ ;~ T;~ g~ Sg~ �~ �T��~ �~ S�~ �~ �T��~ T ' �T� ~ ;~ Q;~ r~ Vr~ {~ �Q�{~ �~ V�~ �~ �Q��~ �~ Q�~ �Q� ' V ~ ;~ R;~ t~ \t~ {~ �R�{~ �~ \�~ �~ �R��~ R �R� ' \ ~ ;~ X;~ v~ ]v~ {~ �X�{~ �~ ]�~ �~ �X��~ X ] �X� ' ] 1~ ;~ Q;~ g~ ^{~ �~ S�~ �~ ^ ' S ~ ~ @H$� ~ ~ u ~ ~ u#� ;~ D~ P]~ g~ P�~ �~ P {~ �~ P�~ �~ P �~ �~ _ �~ �~ ] 0 < U< � \� � \%� >� \>� H� �U�H� U� \b� z� \�� �� \�� �� U�� �� �U�݀ � \� � ]� � U 0 � T� � V� � ] � $� U%� /� T/� 4� VH� H� TH� U� 0�U� [� \[� a� Ta� b� �U�b� z� 0��� ʀ Vʀ ̀ �T�݀ � V� � T� �� �T��� � ] 0 � 0�� � P� � ] � $� U%� �� 0��� ̀ 0�̀ ׀ P׀ ݀ ]݀ �� 0��� � ] \ \ @J$�H� H� @J$� \ \ UH� H� | \ \ u�H� H� |#� e e \b� b� \ e e @K$�b� b� @K$� e e Pb� b� P p p @J$�o� o� @J$� p p \o� o� \ p p |�o� o� |� � 0�� � ]݀ � ] � � @J$� � � ] � � P � � P݀ � P � � V�� �� Pʀ ̀ P̀ ݀ V�� � V � � @F$� � � v � � v#� � � V � � V̀ ݀ V � � @J$� � � R � � r� � � ] � $� U� � ] � � ] � $� U � x� Ux� �� �U��� �� U�� �� �U��� �� U�� �� �U� � �� T�� �� �T��� �� T�� �� �T� � � U � � @K$� � � u � � u#� !� !� @J$� !� !� U !� !� u� *� 5� T *� 5� @K$� *� 5� t 5� 5� P <� <� @J$� <� <� T <� <� t� E� }� T~� �� T E� }� 0�~� �� 0� E� x� Ux� }� �U�~� �� �U��� �� U E� }� T~� �� T E� x� Ux� }� �U�~� �� �U��� �� U Q� x� Q~� �� Q Z� c� 0�c� x� P Z� x� R�� �� R ~� �� U �� �� @F$� �� �� t �� �� P � ?� U?� � \ � � �U�� � \� � �U�� ;� \;� ?� U?� W� \ � ?� T?� � S� � �T�� -� S-� � �T�� � S� ;� �T�;� W� S � ?� Q?� � V � � �Q�� � V� � �Q�� ;� V;� ?� Q?� W� V � ?� R?� ;� ��;� ?� R?� W� �� � ?� X?� ;� ��;� ?� X?� W� �� ?� `� V`� �� _� � S� � _� ;� S +� � ^� � ^� C� ^C� R� PR� W� ^ t� �� P�� p��� � P z� � \� � \ z� �� P�� p��� � P �� ރ t ��ރ � q ��� � t �� ~� � X� � X � U� � U ׃ � [ C� �� P�� �� s � � P � ;� s I� �� \� ;� \ I� �� P�� �� s � � P � ;� s o� �� t ���� �� q ��� ;� t �� M� �� X� ;� X �� �� U(� ;� U �� �� [ �� ̄ \ �� ̄ �� 0� e� Ue� �� V�� �� U�� �� �U��� �� U�� *� V*� 2� U2� 3� �U�3� H� UH� � V� � �U�� �� V�� �� U�� �� �U� 0� V� TV� �� Y�� �� �T��� 2� Y2� 3� �T�3� Y � �T�� y� Yy� Ɖ �T�Ɖ <� Y<� X� �T�X� �� Y�� �� �T� 0� R� QR� �� X�� �� �Q��� 2� X2� 3� �Q�3� X � �Q�� y� Xy� Ɖ �Q�Ɖ <� X<� X� �Q�X� �� X�� �� �Q� B� �� Z�� 2� Z3� Z� y� ZƉ <� ZX� �� Z 8� B� Q �� �� P e� �� V � � V�� �� V� � V e� n� vn� �� T � � T�� �� T� � v {� �� t8 �� �� P n� n� � � � ��� �� � n� n� T � � T�� �� T n� n� t� � � t��� �� t� �� � 0� Ɖ � 0� �� �� u�� � vƉ � v ȇ � [Ɖ � [ Շ ܇ 0�܇ � P Շ � S � � R Љ � P � � P 3� �� 0� � A� 0� 3� H� uH� �� v� A� v X� �� [� A� [ e� l� 0�l� �� P e� �� S u� �� R � !� P 0� A� P �� � 0��� �� 0� �� ؈ \�� �� \�� �� � �� � V�� �� V�� �� U�� �� �U� ؈ ܈ P܈ � \ �� � S�� �� S�� �� v#��� �� u#� _� �� 0� _� �� V n� �� \ c� �� S c� n� V "� <� X<� I� �Q� "� I� 0� "� I� V "� I� ] "� I� V 1� I� \ �� �� P�� �� \ &� I� S &� 1� V p� �� U�� 3� �U�3� N� UN� R� VR� #� �U� �� �� \� � Q� � \� � P �� �� U�� �� Vnj �� V� 3� Vd� �� V� � 0� p� �� U3� N� UN� R� VR� d� �U��� � �U�� #� �U� <� H� PH� N� u#` p� �� 0�3� R� 0�R� [� P[� d� V�� � V ~� ~� @D$� ~� ~� P ~� ~� p� �� �� U �� �� U W� [� P �� � V �� �� Q�� ʍ RՍ � Q �� �� @D$� �� �� P �� �� p� � � V �� �� U�� �� Vnj � V� 3� Vd� �� V �� �� ��nj 3� ��d� �� �� �� �� 0�nj 3� 0�d� �� 0� �� �� 0�nj 3� 0�d� �� 0� �� �� @D$�d� d� @D$� �� �� Pd� d� v �� �� p�d� d� p� �� �� v�� 3� v� � � v � ����N$v� ����!� 1� 3� \ �� �� P �� �� V� �� V 0� [� U[� \� �U�\� ӎ Uӎ V� �U� 4� 4� @D$� 4� 4� P 4� 4� p� K� [� u�[� \� �U#��� �� u� �� �� u � ����N$u� ����!� �� �� P �� �� P � ,� P,� 4� �h � �� V� � P � 4� V �� ӎ Uӎ � �U�� � �U�4� V� �U� �� ͎ P �� 0� � P� � V� � V P �� �� V � 4� V `� �� U�� �� �U��� �� U�� � �U�� F� UF� k� �U�k� �� U�� �� �U� k� k� @D$� k� k� P k� k� p� �� �� u��� �� �U#� �� u��� � �U#�� F� u�F� `� �U#� � �� P 0� B� PB� F� u � ����N$u� ����! � �� �� PF� Z� P F� `� 0� �� � �U� �� �� P�� Ð \ �� Ð Vΐ Ր P k� �� U�� �� �U�Ð ΐ �U�Ր �� �U� t� �� P�� �� u#` k� �� 0��� �� P�� �� VÐ ΐ V �� �� P �� Ð V � � U� )� �U�)� <� U<� _� S � � T� )� �T�)� O� TO� `� �T�`� p� Tp� _� �T� O� ^� \ݑ � VW� _� V � � �T� � � �U#� � � �U#� 3� <� U<� O� S`� ݑ S � W� S 3� <� u��8�<� O� s��8�`� p� s��8� <� O� 0� ͑ ݑ V=� J� V �� �� P�� ȑ ]ȑ ɑ Uɑ ݑ ] � *� ]*� 7� P7� J� ]J� N� UN� W� ] t� }� P}� ݑ \ � W� \ l� ȑ Vȑ ɑ Tɑ ͑ V*� =� VJ� N� TN� R� V y� �� V �� �� \*� =� \ �� ȑ Vȑ ɑ Tɑ ͑ VJ� N� TN� R� V �� ȑ ]ȑ ɑ Uɑ ͑ ]J� N� UN� W� ] �� ȑ }ȑ ɑ uJ� N� u ͑ ԑ ]=� J� ] O� W� \ O� W� \ � � V `� � U� �� �U��� �� U�� �� �U��� �� U�� �� �U� `� � T� �� �T��� �� T�� �� �T��� �� T�� �� �T� `� � u�� �� u �� �� T�� �� �T��� �� T�� �� �T��� �� �T� �� �� U�� �� �U��� �� U�� �� �U��� �� �U� �� �� \�� �� \�� �� \ �� �� T�� �� �T��� �� T�� �� �T� �� �� U�� �� �U��� �� U�� �� �U� �� �� u Ȓ ϒ Pϒ �� S�� �� S ֒ l� S�� �� S�� 9� SK� �� S ֒ l� V�� �� V�� 9� VK� �� V ֒ l� U�� �� U�� 9� UK� N� U � � @F$� � � v � � P �� l� V�� �� V!� 9� V �� l� U�� �� U!� 9� U �� l� V�� �� V!� 9� V �� l� U�� �� U!� 9� U �� �� U �� �� @K$� �� �� u �� �� u#� � � @J$� � � U � � u� � � V � � @K$� � � v � � P #� #� @J$� #� #� V #� #� v� 0� l� V!� 9� V 0� l� 0�!� 9� 0� 0� l� U!� 9� U 0� l� V!� 9� V 0� l� U!� 9� U 7� l� Q!� 9� Q D� Q� 0�Q� l� P D� l� R $� 9� P �� !� VK� �� V �� !� UK� N� U �� � 0� � !� PK� N� PN� �� ^ �� !� ]K� �� ] S� e� T S� e� Ue� f� �H l� �� 0�˓ �� 0� l� �� S˓ �� S l� �� s� �� �� s� ˓ � s� � � s� �� �� ]ӓ �� ] �� �� Vד �� V �� �� s� � � s� �� �� s� � � s� �� �� ]� �� ] �� �� ]� �� ] �� �� V �� �� V �� �� U�� � ]� � �U�� � ]� �� T�� (� ](� 4� T4� � ] ̔ Ք P� � 0�� (� 0� �� ̔ ]� � ]� �� T�� � ](� 4� T4� � ] �� Ȕ U� �� U(� 4� U �� Ȕ u� �� u(� 4� u � � ]� �� T�� � ](� 4� T4� � ] � �� U(� 4� U �� � \ � � ]� �� T�� �� ](� 4� T4� =� ] � �� U(� 4� U � �� u(� 4� u � � P � � \=� � \ � �� \=� E� \�� Ζ \� � \ � �� V=� E� V�� Ζ V� � V � �� U=� D� U�� Ζ U� � U '� 2� @F$� '� 2� v 2� 2� P =� �� V=� E� V�� Ζ V =� �� U=� D� U�� Ζ U =� �� V=� E� V�� Ζ V =� �� U=� D� U�� Ζ U =� =� U =� =� @K$� =� =� u =� =� u#� N� N� @J$� N� N� U N� N� u� [� [� V [� [� @K$� [� [� v [� [� P f� f� @J$� f� f� V f� f� v� s� �� V�� Ζ V s� �� 0��� Ζ 0� s� �� U�� Ζ U s� �� V�� Ζ V s� �� U�� Ζ U z� �� Q�� Ζ Q �� �� 0��� �� P �� �� R �� Ζ P �� �� V� � V �� �� U� � U �� �� 0��� �� P� � P� � S �� �� ^� � ^ � �� T � �� U�� �� �H �� � 0�N� �� 0� �� � \N� �� \ �� �� |� �� Ǖ |� N� k� |� y� }� |� �� � ^W� �� ^ �� � V\� �� V �� Ǖ |� y� }� |� �� Ǖ |� y� }� |� Ǖ ֕ ^�� �� ^ ̕ ֕ ^�� �� ^ ֕ � V ە � V � (� ] о 9� U9� O� SO� w� �U�w� E� SE� [� �U�[� }� S}� �� �U��� �� S�� � �U�� 7� U7� X� �U�X� �� S�� �� �U��� �� S�� U� �U�U� �� S�� �� �U��� �� S�� �� �U��� �� S о �� T�� � �T�� >� T>� X� �T�X� z� Tz� �� �T� о 6� Q6� w� �Q�w� �� Q�� � �Q�� 4� Q4� D� ��D� X� �Q�X� �� Q�� �� �Q��� �� Q�� )� �Q�)� -� Q-� �� �Q� о 4� R4� w� �R�w� �� R�� � �R�� -� R-� X� �R�X� �� R�� �� �R��� �� R�� )� �R�)� -� R-� �� �R� о �� q 3$t "��� 6� q 3$�T"�6� w� �Q3$�T"�w� �� q 3$�T"��� � �Q3$�T"�� 4� q 3$t "�4� >� ��3$t "�>� D� ��3$�T"�D� X� �Q3$�T"�X� z� q 3$t "�z� �� q 3$�T"��� �� �Q3$�T"��� �� q 3$�T"��� )� �Q3$�T"�)� -� q 3$�T"�-� �� �Q3$�T"� X� �� r � 9� U9� O� SO� w� �U�w� E� SE� L� �U�[� }� S}� �� �U��� �� S�� � �U��� �� S�� �� �U��� �� S�� U� �U�U� �� S�� �� �U��� �� S�� �� �U��� �� S � � 0� � �� ]�� B� ^B� r� ]w� L� ][� m� ^m� �� ]�� �� ^�� � ]�� �� ]�� � ]� )� ^U� b� ]u� �� ] � %� ]%� �� ^�� �� ]�� �� ^�� �� ]�� �� ] � J� 0�J� p� \w� �� 0�8� L� \[� �� \�� �� \�� � \�� �� 0��� )� \U� b� \u� �� \ � �� \�� �� \�� �� 0��� �� 0� �� O� 1��� E� 0��� �� 1��� �� 1��� �� 0�%� �� 1��� �� 0��� �� 1��� �� 0� � B� 0�B� O� Pw� 8� 0�8� E� P[� }� 0��� � 0��� �� 0� � J� 0�J� J� \J� g� 0�g� �� P�� �� V�� � 0�� � P� B� VB� O� 0�w� �� 0��� � 0�� � P� 8� V8� E� 0�[� m� 0�m� }� V�� �� V�� �� 0��� )� VU� b� P�� �� 0�%� �� 0��� �� P�� �� V�� �� 0��� �� V�� �� 0� � �� 0� �� E� 0��� �� 0��� �� 0��� �� 0� � �� 0��� �� P�� �� ^�� ӿ 0�ӿ /� ]/� 3� aB� O� 0�w� � 0�� 8� P8� E� 0�[� m� ^m� w� Pw� }� ^�� �� ]�� �� 0��� �� P�� �� ^�� � 0�U� b� 0��� �� 0�%� p� 0�p� |� ]�� �� 0��� �� P�� �� 0� � �� 0� � � 0�� B� PB� O� 0�w� � 0�� ,� \,� 0� a8� E� 0�[� }� 0��� �� 0��� �� 0��� �� 0��� � PU� b� 0��� �� 0��� �� \%� �� 0��� �� \�� �� P�� �� 0��� �� \�� �� P�� �� 0� � �� 0� � O� 0�w� E� 0�[� }� 0��� �� =��� �� 0��� �� 0��� � XU� b� 0��� �� 0�%� �� 0� � �� 0� � O� 0�w� E� 0�[� }� 0��� �� �1 ��� �� 0��� �� 0��� )� �1 �U� b� 0��� �� 0�%� �� 0� � �� 0� � O� 0�w� E� 0�[� }� 0��� �� S��� �� 0��� �� 0��� � SU� b� 0��� �� 0�%� �� 0� � �� 0� � � ] � =� Tw� �� T�� �� T)� -� T � 9� U9� J� Sw� �� S�� �� S�� �� S � �� S A� J� P � � @H$� � � t � � t#� � =� Tw� �� T)� -� T � 9� U9� A� Sw� �� S)� 6� Sl� �� S�� �� S@� �� S�� �� S � 9� u9� =� sw� �� s)� -� s w� �� T)� -� T w� �� S)� 6� Sl� �� S�� �� S@� �� S�� �� S �� �� \ w� �� T)� -� T w� �� S)� 6� S w� �� s)� -� s �� �� P�� �� Vl� �� V�� �� V@� �� V�� �� V �� @� Vl� t� V@� � V�� �� V �� @� \l� t� \@� � \�� �� \ �� @� Ul� s� U@� � U�� �� U � � @F$� � � | � � P � @� \l� t� \g� � \ � @� Ul� s� Ug� � U � @� \l� t� \g� � \ � @� Ul� s� Ug� � U � � U � � @K$� � � u � � u#� � � @J$� � � U � � u� �� �� \ �� �� @K$� �� �� | �� �� P � � @J$� � � \ � � |� � @� \g� � \ � @� 0�g� � 0� � @� Ug� � U � @� \g� � \ � @� Ug� � U � @� Qg� � Q %� .� 0�.� @� P %� @� R j� � P @� g� \�� �� \ @� g� U�� �� U E� R� 0�R� g� P�� �� P�� �� _ E� g� ^�� �� ^ �� �� T �� �� U�� �� �� @� �� 0��� �� 0��� �� 0� @� �� V�� �� V�� �� V @� X� v� X� b� v� �� �� v� �� �� v� T� �� ^�� �� ^�� �� ^ T� �� \�� �� \�� �� \ X� b� v� �� �� v� X� b� v� �� �� v� b� q� ^�� �� ^ g� q� ^�� �� ^ q� �� \ v� �� \ �� �� T �� �� S�� � S6� l� S�� �� S � @� S�� �� S �� �� P�� �� \ �� �� P�� �� V�� � V6� l� V�� �� V � @� V�� �� V �� T� V�� � V6� >� V � @� V�� �� V �� T� \�� � \6� >� \ � @� \�� �� \ �� T� U�� � U6� =� U � @� U�� �� U �� �� @F$� �� �� | �� �� P �� T� \�� � \6� >� \ �� T� U�� � U6� =� U �� T� \�� � \6� >� \ �� T� U�� � U6� =� U �� �� U �� �� @K$� �� �� u �� �� u#� �� �� @J$� �� �� U �� �� u� � � \ � � @K$� � � | � � P � � @J$� � � \ � � |� � T� \�� � \ � T� 0��� � 0� � T� U�� � U � T� \�� � \ � T� U�� � U "� T� Q�� � Q /� <� 0�<� T� P /� T� R �� � P � @� \�� �� \ � @� U�� �� U "� +� 0�+� @� P�� �� P�� �� _ "� @� ^�� �� ^ �� �� T �� �� U�� �� �� T� �� 0�F� l� 0��� �� 0� T� �� VF� l� V�� �� V T� l� v� l� v� v� F� ^� v� �� �� v� h� �� ^N� l� ^�� �� ^ h� �� \R� l� \�� �� \ l� v� v� �� �� v� l� v� v� �� �� v� v� �� ^�� �� ^ {� �� ^�� �� ^ �� �� \ �� �� \ p� u� \ �� �� Vm� }� V �� ſ ][� m� ]%� >� ] �� �� ][� m� ] /� p� �� � /� p� �� � /� p� V >� E� PE� p� ] ο ӿ ] ο ӿ ] `� p� �� � `� p� �� � `� p� V � �� P � � P ;� >� ] B� _� ]8� E� ]�� � ]u� �� ] � %� ]�� � ] B� _� ]8� E� ]�� � ]u� �� ] � %� ]�� � ] _� p� \E� L� \}� �� \� � 0� E� L� \}� �� \ �� �� �� � �� �� �� � �� �� V �� �� P�� �� \ � � \ � � \ �� �� �� � �� �� �� � �� �� V � � P �� � P � � ] �� �� V�� )� V �� �� V�� )� V �� �� ]�� �� ])� @� ]�� �� 0� �� �� ]�� �� ] �� �� P@� K� Pb� b� 0��� �� 0� �� �� P@� K� P � 4� Q4� D� ��D� E� �Q� � 4� Q4� D� ��D� E� �Q� � E� 0� � E� 1� � E� �1 � � E� 0� � E� �0 � � '� U'� �� S�� �� �U��� �� S�� �� �U��� � S� u� �U�u� �� S�� �� �U��� � U� � �U� � a� Sa� �� �U��� �� S�� �� �U��� C� SC� H� �U�H� t� St� y� �U�y� �� S�� �� �U��� �� S�� �� �U��� M� SM� X� �U�X� `� S`� k� �U� � +� T+� �� �T��� � T� � �T� � 7� T7� k� �T� � +� Q+� �� �Q��� � Q � � ��� � �Q� � B� QB� k� �Q� � +� R+� �� �R��� � R � � �R� � B� RB� k� �R� � +� q 3$t "�+� �� �Q3$�T"��� � q 3$t "� � � ��3$t "�� � ��3$�T"�� � �Q3$�T"� � 7� q 3$t "�7� B� q 3$�T"�B� k� �Q3$�T"� � B� r #� '� U'� �� S�� �� S�� �� �U��� � S� u� �U�u� �� S�� �� �U�H� a� Sa� �� �U��� �� S�� �� �U��� C� SC� H� �U�H� t� St� y� �U�y� �� S�� �� �U��� �� S�� �� �U��� M� SM� X� �U�X� `� S`� k� �U� #� Y� 0�Y� ]� P]� �� _�� �� ^�� �� _�� �� _�� � ^ � �� _�� � ^O� T� ^u� �� _�� �� ^H� a� 0�a� v� ^�� �� _�� �� 0��� � ^-� H� ^y� �� _�� �� ^�� �� _�� \� _\� �� ^�� H� _ #� �� 0��� �� ]�� M� 0��� �� ]�� � ] � �� 0��� � ]O� T� ]u� �� 0��� �� ]H� a� 0�a� v� ]�� �� 0��� �� 0��� � ]-� H� ]y� �� 0��� �� ]\� �� ] � H� 0� � �� 1�M� �� 0��� � 1��� �� 0��� � 1�2� H� 1�H� y� 0��� \� 0�\� �� 1��� � 0�H� X� 0� #� �� 0��� �� Q�� �� 0��� �� P�� �� ^�� T� 0�u� �� 0�H� k� 0� #� /� 0�/� A� PA� Y� \Y� �� 0��� �� P�� � ^� 0� 0�0� �� \�� �� 0��� �� 0��� �� P�� �� 0��� � ^ � �� 0��� � \u� �� 0�H� v� \�� �� 0��� � 0�� � \2� H� \y� �� 0��� �� 0��� �� 0��� H� 0� #� E� 0�E� Y� PY� �� 0��� �� ]�� �� 0��� �� P�� �� V�� =� 0�=� J� PJ� �� V�� �� 0��� M� 0�M� �� 0��� �� P�� �� V�� �� 0��� � 0� � � V � �� 0��� � Vu� �� 0�H� a� Pa� n� 0��� �� 0��� � 0�2� H� Py� �� 0��� �� P�� �� 0��� H� 0� M� �� 0��� �� 0�H� y� 0��� \� 0��� � 0�H� X� 0� #� z� 0�z� �� P�� �� Q�� �� 0��� z� 0�z� �� \�� �� 0��� � 0�u� �� 0�H� v� 0��� �� 0��� � 0�2� H� 0�y� �� 0��� �� 0��� @� 0�@� \� \\� �� 0��� H� 0� #� �� 0��� �� 0��� �� 0��� � =�u� �� 0�H� a� 0�a� n� S�� �� 0��� � 0�2� H� 0�y� �� 0��� �� 0��� �� 0��� H� 0� #� �� 0��� �� 0��� �� 0��� � �1 �u� �� 0�H� a� 0�a� v� �1 ��� �� 0��� � 0�2� H� 0�y� �� 0��� �� 0��� �� 0��� H� 0� #� �� 0��� �� 0��� �� 0��� � ��u� �� 0�H� a� 0�a� n� _�� �� 0��� � 0�2� H� 0�y� �� 0��� �� 0��� �� 0��� H� 0� #� '� u0'� +� s0 #� �� ���� �� ��H� k� �� #� �� 0��� �� 0�H� k� 0� #� �� 0��� �� 0�H� k� 0� Y� �� T � -� T�� �� Ty� }� T Y� �� S�� M� S � �� Su� �� S�� �� Sy� �� S � H� S �� �� P Y� Y� @H$� Y� Y� t Y� Y� t#� j� �� T � -� Ty� }� T j� �� S�� 0� S � �� Sy� �� Sc� z� S�� �� S� H� S j� �� s � -� sy� }� s � -� Ty� }� T �� 0� S � �� Sy� �� Sc� z� S�� �� S� H� S 1� M� ] �� 0� VB� I� PI� �� V�� �� Vc� z� V�� �� V� H� V �� �� VP� �� V�� �� V�� �� V� H� V �� �� \P� �� \�� �� \�� �� \� H� \ �� �� ]P� �� ]�� �� v� �� �� ]� H� ] �� �� \y� �� \�� �� \ �� �� ]y� �� ]�� �� v� �� �� \y� �� \�� �� \ �� �� ]y� �� ]�� �� v� y� y� ] y� y� @K$� y� y� } y� y� }#� �� �� @J$� �� �� ] �� �� }� �� �� \ �� �� @K$� �� �� | �� �� P �� �� @J$� �� �� \ �� �� |� �� �� \�� �� \ �� �� 0��� �� 0� �� �� ]�� �� v� �� �� \�� �� \ �� �� ]�� �� v� �� �� Q�� �� Q �� �� 0��� �� P �� �� R �� �� ] b� n� @F$� b� n� | n� n� P �� �� \� H� \ �� �� ]� H� ] �� �� 0��� �� P� � P� -� Q-� >� ��>� H� Q �� �� ^� H� ^ � -� T � .� ] �� 0� 0�c� z� 0� �� 0� Vc� z� V �� � Uc� g� U �� 0� ]c� z� ] �� 0� \c� z� \ �� � Uc� g� U � � Uc� g� U � � ]m� z� ] � � ]m� z� ] � 0� \ !� 0� \ � -� Ty� }� T � 1� Sy� �� S � -� sy� }� s �� �� T u� �� S�� �� S � c� Sz� �� S�� � S u� �� ]�� �� P�� x� ] � /� ]z� �� ]�� � ] u� �� V�� �� P�� �� V � c� Vz� �� V�� � V u� �� V�� t� V � � Vz� �� V�� � V u� �� ^�� t� ^ � � ^z� }� ^�� �� ^�� � ^ u� �� \�� t� \ � � \z� �� \�� � \ u� �� ^� t� ^ � � ^ u� �� \� t� \ � � \ u� �� ^� t� ^ � � ^ u� �� \� t� \ � � \ u� �� ^<� t� ^ u� �� 0�<� t� 0� u� �� \<� t� \ u� �� ^<� t� ^ u� �� \<� t� \ u� �� QD� t� Q x� �� P Q� ^� 0�^� t� P Q� t� R � � \ � � @K$� � � | � � |#� � � @J$� � � \ � � |� #� #� ^ #� #� @K$� #� #� ~ #� #� P .� .� @J$� .� .� ^ .� .� ~� �� �� @F$� �� �� ~ �� �� P �� �� ^�� � ^ �� �� \�� � \ �� �� 0��� �� P�� �� P�� �� Q�� � ��� � Q �� �� R�� �� R �� �� T �� �� \ t� �� 0�#� c� 0� t� �� V#� c� V t� �� v� �� �� v� #� ;� v� V� ]� v� �� �� ^+� c� ^ �� �� ]/� c� ] �� �� v� V� ]� v� �� �� v� V� ]� v� �� �� ^I� V� ^ �� �� ^I� V� ^ �� �� ] �� �� ] �� �� ] � '� Vv� �� VH� y� V�� �� VH� k� V � '� VH� y� V�� �� VH� k� V �� �� V � � V �� �� _�� � _�� � _�� � _2� >� _\� �� _ �� � _�� � _ g� �� �� � g� �� ȏ � g� �� V v� }� P}� �� \ +� 0� \ +� 0� \ �� �� ȏ � �� �� �� � �� �� V J� S� P ^� b� P �� �� _ �� �� _�� �� _O� T� ^�� �� ^�� �� 0�-� 2� ^�� �� ^�� �� _�� �� _ �� �� _�� �� _�� �� ^�� �� ^�� �� _�� �� _ �� �� ]T� u� ]�� �� 0� �� �� ]]� u� ] �� @� �� � �� @� �� � �� @� V � � P� @� \ u� z� \ u� z� \ 0� @� �� � 0� @� �� � 0� @� V �� �� P �� �� P �� �� _ �� � \a� v� \ �� � \a� v� \ '� 7� \�� �� \�� �� 0�� � 0��� �� \ ,� 7� \�� �� \�� �� \ �� � U� � �U� �� � T� � �T� �� � R � � �R� �� � Q � � ��� � �Q� �� � Q � � ��� � �Q� �� � 0� �� � 1� �� � �1 � �� � 0� �� � �0 � 0l Cl Gl Il �l �l �l �l �l �l �l �l �l �l �l �l �l �l m m �l �l m m �m �m �m �m �m �m �m �m �n �n o o o o o o !o =o o o 9o =o @o Mo Qo so xo �o Io Mo oo so �p �p �p �p �q �q �q �q �q r %r %r )r -r %r )r -r <r @r @r Dr Lr 1r <r @r @r Dr Lr 6r <r @r @r Dr Lr pr pr tr �r �t �t �r �r �t �t �r �r �t �t �r �r �t �t �r �r �t �t �r �r �t �t �r �r �t �t �r �r �t �t �r �r �t �t �r �r �t �t �r s �t �t s s �t �t s 1s pt �t 's 1s pt �t 1s Ls `t pt Bs Ls `t pt Ls gs Pt `t Xs gs Pt `t ]s gs Pt `t gs �s @t Pt ~s �s @t Pt �s �s 0t @t �s �s 0t @t �s �s t 0t �s �s t 0t �s �s t t �s �s t t �s �s t t �s �s t t �t u u u �G �G �G +H ?H ?H ?H CH gH jH mH wH I I I 0I _u �u �u �u �u �u �u �u �u �u �u �u v v v v v v v v @v Nv �v �v <I <I =I AI <I <I =I AI <I <I =I AI w w w w *w 0w 0w ~w �w �w �y �y �y �y tw yw |w ~w �w �w �y �y �y �y �w �w �w �w �w �w �w �y �y �y �y `z �w �w �w �y �y �y �y `z �x �x �x �x ]y wy �y z z z z �z �z �z �z �z �z �z �z �z �z �z �z �z { { "{ &{ { "{ &{ 8{ H{ P{ -{ 8{ H{ P{ 2{ 8{ H{ P{ �{ �{ �{ �{ �{ �{ �{ �{ �{ �{ �{ �{ �{ �{ �{ �{ �{ �{ 6| 6| :| >| 6| :| >| M| X| h| B| M| X| h| G| M| X| h| �| �| �| �| �| �| �| �| �| �| �| �| �| �| �| �| �| �| 6} 6} :} >} 6} :} >} M} X} h} B} M} X} h} G} M} X} h} iN mN sN N �N �N �N �N O LO LO UP UP XP �} �} �} �} �} �} �} �} �} �} �} �} �} �} ~ ~ ~ ~ @~ @~ D~ H~ M~ g~ �~ �~ �~ �~ �~ �~ < L \ \ P� P� e e e e h� h� h� h� e e h� h� p p o� o� � z� �� �� � �� � � � � � � � z� �� �� � �� � � � � � � � � � Ѐ � � � � � � (� � � � � � � � (� x� �� �� � �� �� �� � E� E� E� }� �� �� V� x� �� �� L� Q� T� `� d� h� q� � �� � L� Q� T� `� z� � �� � !� 4� =� �� � ;� !� 0� I� �� � ;� `� `� j� o� `� f� o� w� �� �� �� �� �� �� Ѕ Ѕ օ ۅ � � Ѕ օ � � � � 0� 0� 4� V� `� `� n� s� d� j� s� �� �� �� � -� 2� 5� 8� 8� =� B� e� e� e� �� �� �� �� �� �� �� � � �� �� �� � e� e� e� �� � � �� �� �� � n� n� � � �� �� �� � Ɖ � 8� �� � A� �� �� �� � �� Ɖ �� �� �� �� �� �� _� �� P� `� �� �� "� P� tP tP �P �Q �Q R ;R \R =Q eQ ;R ;R �Q �Q �Q �Q R )R ,R /R )R ,R /R ;R \R zR ~R �R zR ~R �R �R �R �R �R �R �R S #S SS WS oS �R S #S SS WS jS S S #S 2S 7S SS WS jS AS SS WS eS �� �� �� Ɋ � � � {� {� }� }� �� �� �� �� �� �� ы ڋ t� x� {� {� {� }� �� �� t� x� {� }� �� �� }� }� }� �� �� �� �� �� �� �� �� �� �� �� �� ы �� �� �� �� �� ы � � � �� � a� p� p� z� �� �� �� �� �� Ќ �� � #� p� p� z� �� �� �� 8� d� �� �� �� ύ Ս �� �� � � #� �� �� �� �� �� ύ Ս �� �� � � �� �� � �� �� Ќ � � � � 8� d� �� ύ Ս �� �� d� d� �� �� � 8� Ќ � � � �� �� � � � �� K� W� �� �� �� �� �� �� �� �� � V� �� �� �� �� �� � � � 4� V� �� �� � 4� �� �� � �� � ;� �� �� P� `� `� p� p� �� p� p� p� �� Ð ΐ Ր �� �� �� �� Ð � � � � 3� <� <� O� `� ّ � � � (� (� W� <� <� <� O� � � � (� (� 0� <� <� <� O� � � � (� `� ّ � � 0� W� y� y� }� �� �� �� �� �� 0� @� �� ͑ J� W� ͑ ԑ @� J� O� O� O� W� ّ ݑ � � �� �� �� �� �� �� �� � � 0� 0� �� �� �� �� �� �� �� �� �� �� � � 0� 0� �� ֒ �� �� � � 0� 0� l� �� �� �� 9� K� �� �� �� �� � � 0� 0� l� �� �� !� 9� � � � � 0� 0� 0� l� !� 9� �� !� K� �� l� �� Ǔ ˓ ˓ �� �� �� � � �� �� � � �� �� � �� �� �� � �� /U /U 2U 9U PU ^U �� ̔ � =� =� [� [� s� s� � 0� � � �� 0� =� �� =� =� [� [� s� s� � =� � � =� =� [� [� s� s� �� =� E� �� Ζ � � =� =� =� [� [� s� s� �� =� E� �� Ζ [� [� [� [� s� s� s� �� �� Ζ �� �� � � �� � I� N� N� �� �� Ǖ k� �� �� Ǖ y� �� Ǖ ֕ �� �� ̕ ֕ �� �� >� E� H� � � <� �� 5� F� � � � �� Ǟ � E� i� ҟ ҟ � � � � � �� �� �� Ǟ i� }� �� �� i� }� � � � � 5� 5� F� \� � � F� \� � <� \� �� � � \� o� � � \� o� � -� o� �� #� -� o� �� -� <� �� �� 2� <� �� �� �� � �� � � � � E� }� ҟ ҟ � � � � � �� � �� Ɲ }� ҟ ҟ � � � � � �� � }� ҟ ҟ � � � � � �� � �� ҟ ҟ � � � � :� G� � �� �� �� ҟ ҟ � � � � :� G� ]� o� � �� �� ҟ ҟ ҟ � � � � :� G� ]� �� �� ҟ � � � � :� G� ]� � � � � � � � :� G� ]� � � � ޙ � � �� � � � �� � �� �� � � �� �� � }� �� :� G� � � � �� � � �� � � � � E� E� \� _� �� � � � �� E� L� L� \� _� �� � � � �� _� {� � �� ʘ ʘ ʘ ٘ �� �� �� �� �� �� ʘ ٘ �� �� �� �� @� k� g� �� � � !� D� k� �� �� ߛ ߛ � t� t� t� �� D� I� �� �� כ ܛ ߛ ߛ ߛ � כ ܛ ߛ � t� t� t� �� �� � c� �� �� �� }� �� �� �� }� �� �� К p� }� Ś К p� }� К � c� p� ՚ � c� p� � g� � t� � F� � � Ǟ � E� i� �� g� � � 6� @� � � �� � !� (� ,� 3� �� �� V� c� �� �� V� c� �� Ĝ I� V� �� Ĝ I� V� O� �� �� Ţ � �� �� � � 5� 5� M� M� �� X� ѥ `� g� g� �� � x� �� � � 5� 5� M� M� �� X� ѥ � x� ף � � 5� 5� M� M� �� e� ѥ � � � � � 5� 5� M� M� �� |� ѥ � � � � � 5� 5� M� M� �� � � � 5� 5� M� M� �� 5� 5� 5� 5� M� M� M� �� � x� e� |� @� O� e� o� E� O� e� o� O� _� o� |� T� _� o� |� �� Σ X� e� �� �� �� Ţ �� �� �� �� �� �� �� �� �� �� ϡ ϡ ϡ � Ф � N� X� ڤ � N� X� � � � � N� X� � � � F� Т � � � � � � !� � � � � � !� � � !� ,� � � ,� 7� Т � F� M� �� �� ~� ~� �� �� � � � @� H� N� �� �� �� � @� H� � � � :� �� �� �� �� �� �� Ȧ � � #� #� *� *� P� � �� �� ͨ ͨ Ѩ Ѩ ۨ � H� U� Z� Z� h� h� q� {� �� �� %� �� �� � � +� :� �� �� �� �� �� �� Ȧ � � #� #� *� *� I� � �� � H� U� Z� Z� h� h� q� {� �� �� %� �� �� � � �� �� �� �� �� �� Ȧ � � #� #� *� *� 8� � �� �� �� U� Z� Z� h� h� q� {� �� �� � �� �� � � �� �� Ȧ Ȧ Ȧ Ѧ ަ � � #� #� *� *� 8� � �� �� �� U� Z� Z� h� h� q� �� �� ަ � � #� #� *� *� 8� � r� U� Z� Z� h� h� q� �� �� ަ � � � � r� U� Z� Z� h� h� q� �� �� ަ � � � U� Z� Z� h� h� l� Z� Z� Z� Z� d� h� � `� �� �� � #� #� *� *� /� #� #� #� #� &� *� {� �� �� � � � �� é ǩ ˩ ݩ � �� �� �� �� � � ;� � � � ?� D� j� � � � s� �� � �� 8� I� � H� � 7� <� A� ͨ ͨ ͨ Ѩ :� n� s� x� x� �� x� x� �� �� �� �� x� x� �� �� P� |� |� � � § § § § § § ͧ ۨ � � � � � H� U� q� {� %� M� R� n� n� �� �� ٪ ٪ ٪ ٪ � � � |� |� |� � � �� �� �� q� {� � � �� �� ۨ � § § � � � � § § § § � � � � M� M� § § � � § § § ͧ H� U� e� h� n� n� n� r� w� |� ٪ ٪ e� h� n� r� w� |� |� �� ٪ ٪ ٪ � |� �� ٪ � ͧ � � �� �� � � �� �� � "� )� D� z� � � � �� �� � � #� &� b� b� i� i� �� � y� �� �� �� �� �� � � � � � &� 2� 2� ԯ �� � 5� X� k� z� � � � �� �� � � #� &� b� b� i� i� �� � y� �� � � � � � &� 2� 2� ԯ �� � 5� X� � � � �� �� � � #� &� b� b� i� i� w� � j� o� y� � � � � � � &� 2� 2� ʯ �� � 5� X� �� � � � � � � #� &� b� b� i� i� w� � j� o� y� � � � � � � �� 4� � #� &� b� b� i� i� w� � R� � � � � � � �� 4� � #� (� 0� � R� � � � � � � �� 4� � #� (� 0� � � � � � � � � � � � � �� @� �� 4� ^� b� b� i� i� n� b� b� b� b� e� i� &� 2� 2� ʯ 4� � 5� X� `� w� �� ʯ `� `� c� g� =� � 5� X� Y� ^� v� � 5� X� Y� ^� y� ~� �� � 5� X� Y� ^� �� Ͱ 5� J� w� �� �� � �� � �� �� �� �� �� �� z� �� �� �� �� �� �� �� y� ~� ~� �� �� �� ~� �� �� ӭ � &� ԯ �� � +� +� 5� �� �� �� �� ĭ έ � &� ӭ ӭ ӭ � ӭ ӭ ӭ � b� i� o� t� {� �� �� �� �� � � �� �� � � #� &� c� c� j� j� � � � .� <� <� @� @� I� I� M� M� � P� Y� Y� e� e� j� j� n� n� s� s� w� w� ȵ � O� O� ]� ]� �� '� /� /� �� ٸ � ȹ �� 2� <� <� � E� r� �� �� �� �� �� о б � � �� �� � � #� &� c� c� j� j� x� }� �� .� <� <� @� @� I� I� M� M� � �� ȵ J� O� O� ]� ]� f� '� /� /� �� ٸ � ȹ �� E� r� � � � �� �� � � #� &� c� c� j� j� x� `� Ҵ ״ � J� O� O� ]� ]� f� '� /� /� �� ٸ � ȹ �� E� r� �� � � � � � � #� &� c� c� j� j� x� `� Ҵ ״ � J� O� O� ]� ]� f� ٸ � � #� &� c� c� j� j� x� `� �� J� O� O� ]� ]� f� ٸ � � #� (� 0� `� �� J� O� O� ]� ]� f� ٸ � � #� (� 0� J� O� O� ]� ]� a� O� O� O� O� Y� ]� i� �� ٸ � ^� c� c� j� j� o� c� c� c� c� f� j� '� /� /� �� ȹ �� E� r� P� c� g� k� }� �� P� P� S� W� ѹ �� E� r� � � � �� E� r� � � � � :� �� E� r� � � C� n� E� _� x� x� }� �� �� ȵ �� �� �� �� <� <� <� @� I� I� I� M� �� � � � 8� J� f� �� <� <� <� � �� �� �� �� �� �� �� о � � 8� J� <� <� <� {� �� � � *� Z� �� �� � � *� {� �� ƻ �� � � �� �� �� �� � � *� Z� �� о �� �� � �� � � �� �� �� �� � � *� Z� �� о �� �� �� ؼ K� �� � � *� U� K� �� *� U� ؼ � &� K� �� о � � �� о �� ƻ �� � �� �� Y� Y� Y� Y� a� e� j� j� j� n� s� s� s� w� � � � �� �� г г Գ Գ Գ Գ ׳ ׳ � �� �� �� �� �� · · ѷ � �� � � � '� �� Ǹ ̸ ٸ � � � 6� 6� 6� ;� C� C� R� R� o� o� o� t� �� �� �� �� ȹ �� �� �� � �� � � -� � ;� ;� E� r� �� �� �� �� �� �� �� �� �� � � � � 7� B� �� �� R� R� j� o� R� j� o� �� �� �� � '� R� R� ~� �� �� �� �� �� � '� ~� �� �� �� � '� Ƴ г �� �� г Գ Գ ׳ Գ Գ · · · ɷ � � 6� 6� o� o� �� �� � � -� -� �� �� �� �� · ɷ � � Գ Գ ׳ � ɷ ѷ � �� � � 6� 6� o� o� �� �� �� �� �� ȹ �� �� �� �� ׳ � ɷ ѷ � �� �� �� �� ȹ �� �� �� �� ȶ �� �� �� �� �� �� �� � �� �� �� �� �� �� �� � �� �� �� �� �� �� � � � E� R� 7� A� �� �� A� L� t� �� r� v� C� C� R� R� �� �� �� Ϻ � � � � �� �� r� v� �� Ϻ � � �� �� � �� ̸ ٸ �� �� �� Ǹ Ǹ Ǹ � � � � ;� C� ;� ;� � � ;� C� � .� �� � � � � �� �� � � )� �� � � � � �� � � � )� �� � � � � � ѷ � � �� �� � � � ѷ � � �� �� � � � ѷ � ȵ �� � � � �� �� ο ο ӿ ӿ B� B� h� �� � � �� �� � � �� �� � � � � 8� 8� L� `� �� �� �� �� �� �� � �� �� �� � � � � �� �� u� u� � � �� �� �� � � � � � � � J� �� � � �� �� � � �� �� �� �� � � � � �� �� � )� �� � �� � � � � � A� �� � � �� �� � � �� )� 6� l� �� �� �� @� �� �� �� �� �� )� 6� �� � � �� �� � � �� l� �� �� �� @� �� �� �� �� � � �� �� � � @� l� t� @� � �� �� � � � �� �� � � @� l� t� g� � �� �� �� �� � � � @� g� � @� g� �� �� @� �� |� �� �� �� �� �� X� b� �� �� �� �� X� b� �� �� b� q� �� �� g� q� �� �� �� �� �� �� �� � � � � �� �� � 6� l� �� �� � @� �� �� �� �� �� �� �� � � � � �� �� � 6� l� �� �� � @� �� �� �� �� �� � � � � T� �� � 6� >� � @� �� �� �� �� �� � � � � T� �� � 6� >� � � � � � � � T� �� � T� �� B� F� F� l� �� �� l� v� ^� l� �� �� l� v� �� �� v� �� �� �� {� �� �� �� �� �� p� �� �� �� `� p� �� ο ο ӿ (� p� �� �� ο ο ο ӿ /� p� ο ο ο ӿ � � � �� � � � � � "� 3� 7� ;� >� B� B� B� _� � � 0� 4� 8� 8� 8� E� �� �� �� �� �� �� �� � u� u� u� }� � �� � � � � � (� �� �� �� �� �� � B� _� � � 0� 4� 8� E� �� �� �� �� �� � u� }� � �� � � � (� �� �� �� � _� h� E� L� �� �� � � E� L� �� �� �� � � � �� �� �� �� � � � � �� �� � � � � � � � � �� �� �� �� �� �� �� �� �� �� �� )� �� �� �� �� �� �� �� )� �� �� �� �� �� �� )� @� �� �� �� �� �� �� �� �� �� �� @� X� b� b� �� �� �� �� @� X� � E� E� I� #� � � +� +� 0� 0� �� �� M� M� u� u� z� z� y� y� �� �� �� �� �� �� �� P� a� a� � � #� #� <� <� k� Y� �� �� M� � y� y� �� �� �� �� �� u� �� �� � � #� #� <� <� �� y� �� � H� j� �� �� 0� � y� y� �� �� �� �� �� y� �� c� z� �� �� � H� �� 0� :� y� y� �� �� �� �� �� �� �� c� z� �� �� � H� �� �� P� y� y� �� �� �� �� �� �� �� �� �� � H� �� �� y� y� y� �� �� �� �� �� �� �� �� �� y� �� �� �� �� �� �� �� �� �� �� �� �� �� �� �� �� �� �� 0� c� z� �� � c� m� � � c� m� � � m� z� � � m� z� � 1� y� �� >� M� u� �� �� � � #� #� <� <� �� � c� z� �� �� � >� M� u� �� �� � � #� #� <� <� �� � c� z� �� �� � >� I� I� M� u� �� �� � � #� #� <� <� t� � � z� �� �� � u� �� � � � #� #� <� <� t� � � u� �� � #� #� <� <� t� � � u� �� <� <� <� t� u� �� <� t� #� #� #� #� z� �� �� �� �� � t� �� � #� #� c� �� �� ;� I� V� c� �� �� V� c� �� �� I� V� �� �� I� V� �� �� � '� v� �� P� T� X� i� �� �� X� [� �� �� � '� P� T� X� i� �� �� X� [� �� �� � � �� � � � � +� +� 0� �� � `� �� +� +� +� 0� g� �� +� +� +� 0� J� J� O� S� f� j� n� r� �� �� �� � O� T� �� �� �� �� -� 8� �� �� �� �� �� �� �� �� �� �� �� � �� �� �� �� �� �� �� �� �� �� �� �� T� u� �� �� �� �� ]� u� M� u� u� z� �� @� �� � u� u� u� z� �� @� u� u� u� z� �� �� �� �� �� �� �� �� � � a� a� a� v� �� �� � � a� v� '� 7� �� �� �� �� �� �� � � �� �� ,� 7� �� �� �� �� �� �� �� � � � r� y� �� �� @� C� C� G� G� P� X� s� v� �� �� �� �� �� � �� �� �� �� �� �� � � %� %� 3� 3� <� 0� <� <� �� {� �� �� �� w� �� �� �� @� C� C� G� G� P� X� s� v� �� �� �� �� �� � �� �� � � %� %� 3� 3� <� 0� <� <� �� {� �� �� �� w� �� C� C� C� G� L� P� X� s� v� �� �� �� �� �� � z� � �� � %� %� 3� 3� <� 0� <� <� �� {� �� �� �� w� �� L� P� X� X� X� a� n� s� v� �� �� �� �� �� � z� � �� � %� %� 3� 3� <� {� �� n� s� v� �� �� �� �� �� � b� � %� %� 3� 3� <� {� �� n� s� x� �� � b� � %� %� 3� 3� <� {� �� n� s� x� �� � %� %� 3� 3� 7� %� %� %� %� /� 3� � P� {� �� �� �� �� �� �� �� �� �� �� �� �� �� 0� <� <� �� �� �� w� �� h� {� � �� �� �� h� h� k� o� �� �� w� �� �� �� �� �� w� �� �� �� �� � "� �� w� �� �� �� +� Z� w� �� �� �� �� � �� �� � � �� �� �� �� �� �� � � � � � � �� �� �� �� � � �� �� �� � � �� �� R� R� �� �� �� �� �� � ,� ,� �� �� �� �� �� �� � <� � � 0� �� �� �� � � .� .� .� .� \� a� {� �� 0� 0� C� C� C� H� v� v� v� v� �� �� �� �� �� �� �� �� �� �� �� � � � w� �� �� �� z� z� b� �� �� �� �� �� �� �� �� �� � � �� �� �� � ,� ,� ?� �� � � 0� �� �� �� � � .� .� @� �� �� �� �� � � � �� �� �� � $� )� ,� �� � �� �� �� � � `� �� �� `� �� �� �� �� �� �� �� `� v� �� �� �� �� �� � �� � �� �� �� �� �� �� �� �� $� )� ,� ?� � 0� � .� �� �� �� �� �� �� <� `� m� {� �� �� �� �� � � � �� �� �� �� W� `� z� z� b� �� �� m� {� �� �� �� �� � � � B� �� �� B� t� �� �� �� �� �� �� �� E� `� z� z� b� ]� i� �� �� �� �� �� �� �� �� 5� @� �� �� �� � `� z� z� �� �� b� �� � �� &� z� z� z� �� &� b� z� z� z� �� &� .� @� b� �� �� �� �� t� �� �� �� E� W� �� � � � =� H� `� m� f� �� �� �� �� �� 6� w� f� �� �� �� �� �� �� �� �� �� �� �� 6� w� �� �� �� �� �� �� �� �� �� � \� \� �� �� �� �� �� �� ?� L� e� �� �� �� a� {� �� �� �� �� �� �� �� �� �� �� n� {� �� �� �� �� n� {� �� �� a� n� .� .� C� C� v� v� v� �� �� �� �� �� 0� 0� 0� C� � � '� 1� �� �� �� �� �� � �� �� �� � p� p� �� �� �� �� �� �� �� (� �� � � .� .� 3� 3� @� @� �� �� �� �� � �� � � (� b� �� �� �� � � "� (� �� �� � � � .� .� 3� 3� @� .� .� .� 3� @� @� @� X� 1� 1� 1� j� j� o� o� �� �� �� �� �� �� #� H� �� �� �� 1� 1� 1� 5� B� j� j� o� H� �� �� �� j� j� j� o� O� �� j� j� j� o� |� �� �� �� �� �� � � �� �� |� �� �� �� � � �� �� �� �� �� �� �� �� �� �� �� �� �� �� �� �� �� �� �� :� a� r� �� �� �� �� �� :� �� �� �� �� �� �� �� � T� a� � � � '� �� �� � � �� �� �� �� �� �� � � �� �� �� �� 8� j� j� �� �� �� �� �� �� �� j� j� �� �� �� �� �� �� �� �� �� �� j� t� �� �� r� �� �� �� �� �� �� �� �� �� �� '� �� �� �� �� �� �� �� �� �� � � � � @� �� y� �� �� �� �� �� �� � O� O� ]� ]� f� �� �� �� x� �� �� � @� � '� �� �� �� �� �� �� �� �� �� � � � � 9� �� y� � O� O� ]� ]� f� �� �� �� x� �� �� � @� �� �� �� �� �� �� �� �� �� � � � � (� �� j� o� y� J� O� O� ]� ]� f� �� �� �� ;� E� x� �� �� � @� �� �� �� �� �� �� �� �� �� � � � � (� �� j� o� y� J� O� O� ]� ]� f� E� x� �� �� �� � � � � (� �� R� J� O� O� ]� ]� f� E� x� �� �� �� �� �� R� J� O� O� ]� ]� f� E� x� �� �� �� �� J� O� O� ]� ]� a� O� O� O� O� Y� ]� � @� E� x� � � � � � � � � � � � � �� �� �� ;� �� �� � @� �� �� �� �� � ;� �� �� �� �� �� �� � @� �� �� �� �� � @� �� �� �� �� � �� � @� �� �� � F� � *� (� 9� � J� � 9� >� C� �� �� �� �� '� [� `� e� e� p� e� e� y� ~� ~� �� e� e� ~� �� @� �� �� �� �� �� �� �� �� �� �� �� �� � � � � �� �� �� �� � f� f� f� �� x� x� x� x� x� x� x� �� �� �� �� �� �� � @� Z� c� �� �� �� �� �� w� �� �� �� �� �� �� C� ]� j� q� �� �� �� �� � 2� C� �� �� �� �� �� � �� �� �� �� �� �� �� �� �� �� �� �� ]� j� �� �� �� �� �� �� ]� j� �� �� w� �� �� �� �� �� �� � � � �� �� �� � � � � � �� � � � � � � � #� ;� @� M� ;� B� N� W� P� ]� B� E� �� �� x� x� x� x� �� �� B� E� �� �� x� x� �� �� h� �� �� �� C� P� �� �� �� �� �� �� �� �� �� �� �� �� �� �� �� �� �� �� C� P� j� �� M� Z� {� �� M� Z� �� �� �� �� �� �� �� �� b� i� �� �� 0� 3� 3� 7� 7� @� H� c� f� �� �� �� �� �� �� A� h� u� u� z� z� �� �� �� �� �� �� �� z� �� �� � � M� �� �� � � �� �� 0� 3� 3� 7� 7� @� H� c� f� �� �� �� �� �� �� A� �� �� �� �� �� �� z� �� �� � � M� �� �� � � 3� 3� 3� 7� <� @� H� c� f� �� �� �� �� �� �� 2� 7� A� �� �� �� �� �� �� z� �� �� � � M� �� �� � � <� @� H� H� H� Q� ^� c� f� �� �� �� �� �� �� 2� 7� A� �� �� �� �� �� �� � M� ^� c� f� �� �� �� �� �� �� � �� �� �� �� �� �� � M� ^� c� i� p� �� � �� �� �� �� �� �� � M� ^� c� i� p� �� �� �� �� �� �� �� �� �� �� �� �� �� � � M� �� �� �� �� �� �� �� �� �� �� �� �� z� �� �� � �� �� � � �� �� �� � �� �� �� �� � �� � � � � � �� � � � � � � 2� �� � � � � ;� f� � � �� �� �� �� �� �� �� �� u� u� u� z� �� �� �� �� �� � �� �� A� F� F� h� �� �� F� ^� �� -� -� 1� 1� _� _� }� �� �� �� �� �� �� �� �� �� 3� 3� �� �� �� �� �� �� � � `� `� `� `� `� `� z� � � M� �� �� � � H� H� � � -� -� 1� M� �� �� �� -� -� -� 1� T� �� -� -� -� 1� >� A� � � � � � -� `� `� >� A� � � � -� J� W� � � q� q� u� z� �� �� �� �� -� <� h� �� �� �� �� �� o� �� �� �� �� �� �� �� �� �� [� h� �� �� �� �� � � �� �� s� �� `� `� `� `� l� z� �� �� s� �� `� `� l� z� � 3� 3� S� �� � � H� H� [� 3� 3� A� E� H� H� H� [� A� E� H� [� 3� >� �� � � � �� � � � �� � }� }� }� �� }� }� }� �� � �� �� �� �� � � '� � �� � '� � �� � � !� '� � �� � V� �� �� � � � � 0� e� �� �� � � � � � � � C� P� �� �� � \ � � � @ +� ?� 0� O� �� �� ?� V� � � � � � � � � � � � C� P� �� �� � \ � � � @ � � �� �� � � � � @� �� �� � � C� �� �� �� � \ � � � @ � � �� � [� k� � � � C� k� �� �� �� �� �� �� � \ � � � @ �� �� �� � 6 A 3 \ � P � 3 � � � @ � l � � � * � � � � * 3 � � � @ � � � � � � � + / @ � � � � � � � @� �� �� P� �� `� k� �� � �� � �� �� q� � � 2� @� �� �� �� �� � � 0� C� P� � \ � �� � q� � @� �� �� �� �� � � 0� C� P� � \ � q� � Z� �� �� �� �� � � 0� � \ � q� |� p� �� �� �� �� � � � � \ � q� |� �� �� �� �� �� � � � q� |� �� �� �� � � � �� �� �� �� � � � � �� � � � �� �� � � �� �� � � �� �� � � �� �� � � @� Q� C� P� � � �� �� � � � � 0� @� � $� X� � �� � e� � �� � u� z� }� � �� � $� \� \� }� � � � � � � T� Y� \� \� \� b� � � T� Y� \� b� � � b� m� � � m� t� � � }� �� � 0� � � >� >� >� C� O� Q� �� �� >� C� O� Q� � � Q� `� 2� 2� �� �� �� �� �� � � � Q� `� �� �� �� � �� �� �� �� �� �� B I d � ( C F � � � � � � � � � � � % % 3 3 < F R R � ( U x � � ( C F � � � � � � � % % 3 3 < F R R � ( U x ( C F � � � � � � � � ! % % 3 3 < F R R � ( U x ( ( ( 1 > C F � � � � � � � � ! % % 3 3 < T > C F � � � � � r ! % % 3 3 < T > C H P r ! % % 3 3 < T > C H P ! % % 3 3 7 % % % % / 3 ` T ~ � � � � � � � � � � � F R R � T ( U x � � � � � � � � ] ( U x y ~ � ( U x y ~ � � � ( U x y ~ � � U j � � � ! � � � � � � � � � � � � � � � � � � � � � � � < F � ( K K U � � � � � � < F � � � � � � � � � � � � � � � ( C F � � � � $ ' , N \ \ ` ` i i m m p y y � � � � � � � � � � � , o o } } � G O O � � , � � R \ \ 8 e � � � � � � � � ( C F � � � � � � � N \ \ ` ` i i m m � � j o o } } � G O O � � , � � e � ( C F � � � � � � � � j o o } } � G O O � � , � � e � ( ( ( 1 > C F � � � � � � � � j o o } } � � , > C F � � � � � � � j o o } } � � , > C H P � � j o o } } � � , > C H P j o o } } � o o o o y } � � � , ~ � � � � � � � � � � � G O O � � � e � p � � � � � p p s w � � e � / � e � 2 7 Z � e � c � e � � � � � � � � � � \ \ \ ` i i i m � $ , 4 X j � � \ \ \ 8 � � � � � � � � $ X j \ \ \ � � " J z � � " J � � � " 8 � � � � " J z � � � � " 8 � � � � " J z � � � � � � k � " J u k � J u � . F k � � # � � � � " � � y y y y � � � � � � � � � � $ ' , � � � � � � � � � � � � � � & . : G � � � � , 7 7 V V V [ c c r r � � � � � � � � � � � � " " M 8 [ [ e � � � � � � � � � � $ ' , 4 W b � � r r � � r � � � � � : G r r � � � � � � : G � � � � : G � � � � � � � � � � � � � � & . V V � � � � M M � � � � � � & . � � � � � . . V V � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � & / < e r W a � � a l � � � � c c r r � � � � " " " 0 � � � � � � " 0 � � � � � � � � � � � � 7 7 7 > [ c [ [ 7 > [ c N & 0 : , 1 I & 0 : " , : I & 0 : = � ) . = � ) 3 = � � % � � M � � � � � � � � � N N U U 0 = = B B G � � � � � � � � � Y s! �! �" �# �# $ > M � � � � � � � � � N N U U ~ � � � � � � � � � � Y s! �! �" �# �# $ � � � � � � � � � N N U U m � � � � � � � � � � � � O s! �! �" �# �# $ � � � � � � � � � N N U U m � � � � � � � � � s! �! � � � N N U U m � � � � � � � � s! �! � � � � � � � � � � � s! �! � � � � � � � � � � � � � � � � � s! �! J N N U U Z N N N N Q U � � � O �" �# �# $ 5 O �" �# �# $ # # 0# �# �# $ # # 3# 8# R# �# �# $ # # [# �# �# $ m ~ � � � � � � = = = B M � � � � � � � 0 � � $ G G N R W ^ g � � � � � � Y Y x x � � � � � � � � � � � � � � � � 5! 5! 9! 9! s! �! �! �! �! �! �! �! �! �! ?" ?" I" I" _" d" �" �" �" �" �" �# �# $ $ $ �% �% �& �& �& �& v' v' �( � � �! �! �# �# �! �! �# �# �! �! �! �! �# �# � � � � � � � d" z" �# �# Y h � � � = J ] � � $ $ $ 0% 5% _% b% j% �% �% �% �& �& v' v' �( - A � � = A Y � � h � J ] $ $ $ [$ �$ �$ |& �& [$ �$ �$ % 5% Y% b% j% �% �% �% |& �& �& �& v' v' �( v$ �$ �$ % 5% Y% �$ �$ �& �& �$ �$ b% j% �% �% �% |& �& v' v' �( �% �% �% �% >& I& S& |& �% '& �& v' v' �( �% & )' J' �' &( & '& �& �& &( 9( �& ' ' )' v' v' v' �' 9( �( v' v' v' �' F( K( S( V( c( �( �' �' �' �' �$ �$ % 0% Y% _% �% �% f i p t t � � � _% b% j% y% � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � K! V! �" �" � $ ( - - 0 _ o o w z � � � �" �" # h � Y 9 x � � = E ] � � ! ! ! � � � 9 9 x O Y = E Y Y Y h � � � � �! �! �! �! �! " ?" ?" Y h �! �! �! " h x � _! i! �! �! " " �" �" �# �# �& �& �& �& h x � �" �" �# �# �& �& �& �& � � � � � � � � 9! 9! �! �! _" _" �" �" �& �& � � � � � � � � 9 � � 9 � � x � � � x � ! ! ! ! ! ! A! K! 5! 9! 9! A! � � � � Y e h � � � � � �V �V �V �V W 5W 7W 7W �W �W �W �W .Y NY PY �Y :Y NY PY �Y �Y �Y �Y Z nZ [ [ v[ v[ �[ �[ �[ �[ �[ h h nZ [ [ v[ v[ �[ �[ �[ h h �Z �Z �Z �Z �Z �Z �Z �Z �Z �Z �Z �Z �Z �Z �Z �Z [ 5[ s[ v[ v[ �[ �[ �[ �[ �[ �[ �[ �[ `] k 'k �[ \ /\ �\ �[ \ 8\ �\ `] `] `] q] �] �] �^ �^ _ _ �h i i i �] �] _ >_ H^ K^ V^ _^ K_ R_ g_ q_ g_ j_ q_ q_ R_ g_ q_ !` >` l` �_ �_ �_ �_ ` !` �a �a �a �a �a �a �a �a �a �a �a �a �g �g �g �g �g h �j �j k k l �( �F ]G ]G �G �G <I <I ~I ~I �J �J �N �N �N �N tP tP �R �R U U fU fU \X \X 9k 9k Ek 8 ` � X H x/ @ @ �F �( 0 XJ �L �w �w x P} � �� � � l K 0l # � `l � pl � �l � �l � �l @ �l 5 8 0m � T �n n �n � o / � @o E � �o � �o | � 0p � �p � G �q � g �F } � � � � r A � pr j � �t ) � ]G ~ � �G a �� ' �� / u � I v � g <I B ~ �v � � `z } � �z � � �{ � � | � �| h 3 } h M ~I j �J � �N G � �N � � `� � � Ѕ � % `� e S �} l l ~ ' � 0 � � � � 0� � � � � �� # S � � � G � 0� o � tP . � �R m �� : " � � @ p� � \ 0� & y `� � � � _ � `� ! � U W � �� � � � 0� ) (� C � � � � < � � 8 / `� p y о * � �� � �� � �� �� * � k x ȏ � �� � �� � �� � p� � � 0 p� ` e h� z `� � x� � p� � �� � �� �� 5 � k `� c � X� � P� � H� � @� � p Y @ 8 � � p � � � ; �A � J fU � ] \X � s 8� � �� � x 0 � �B � �� � @� � O � � �� � �� �� l `� � @� � P � � � � �� > �� � �� h � �� � � `� @ � �� � � �� � � HJ H �D H G �B N r �E : � hI � J � D � � hH � FJ � DJ BJ 8I & pG @ 0G [ �G r �F � F ! � �C # � �F G �G 6 `I F J S �I b XI r PG � �F � �I � 8J � �I � ?J � 4J � (I � I <J �I �I / XH D �H V 0J b �E $ � �I � �C ( � `C , � HI � �I �I (J ! J - �I < �I K J W �G o �F � @E " � C $ � �G � HH �H " �H 4 I E pF i 0F � �H � xI � H � �H � �I � �H � �H �H �G / xH B PF f �I t 8H � �I � pI � (H � J � �I � � � � 0 � � � 6 � � u � � Pk � �k � �k � � � �w � l � �w u � �_ � x $ P} - XJ @ � L � b w � � � � � � � � " > O e q | � � � � � � 7 D P c r � � � � �( � � � , t @ Q b w � � � � � � � $ 5 B U e y � � � � � � � 2 D X g z 9k � � � � � � � ! ! -! B! Q! a! p! �! �! �! �! �! � �! " " (" B" S" _" t" �" �" �" �" �" �" �" # # 9# G# V# g# t# �# �# �# �# �# �# $ $ %$ 2$ C$ " _$ @ e$ s$ �$ �$ �$ �$ �$ �$ �$ util.c __pyx_tp_traverse_10sqlalchemy_11cyextension_4util_prefix_anon_map __pyx_tp_clear_10sqlalchemy_11cyextension_4util_prefix_anon_map __Pyx_CyFunction_get_qualname __Pyx_CyFunction_get_globals __Pyx_CyFunction_get_closure __Pyx_CyFunction_get_code __Pyx_CyFunction_get_annotations __Pyx_CyFunction_get_dict __Pyx_CyFunction_CallMethod __Pyx_PyObject_GetAttrStr __Pyx_PyMethod_New __Pyx_CyFunction_get_name __Pyx_CyFunction_get_doc __Pyx_CyFunction_repr __Pyx_PyNumber_LongWrongResultType __Pyx_RejectKeywords __pyx_pw_10sqlalchemy_11cyextension_4util_14cache_anon_map_1__init__ __Pyx_CyFunction_get_kwdefaults __Pyx__SetItemOnTypeDict __pyx_mstate_global_static __Pyx_CyFunction_set_doc __Pyx_CyFunction_clear __Pyx_CyFunction_dealloc __Pyx_copy_spec_to_module __pyx_pymod_create main_interpreter_id.0 __pyx_m __Pyx_CyFunction_traverse __Pyx_CyFunction_Vectorcall_O __Pyx_VerifyCachedType __Pyx_CyFunction_CallAsMethod __Pyx_CyFunction_set_annotations __Pyx_CyFunction_set_kwdefaults __Pyx_CyFunction_set_defaults __Pyx_CyFunction_set_dict __Pyx_CyFunction_set_qualname __Pyx_CyFunction_set_name __Pyx_PyCode_New.constprop.0 __Pyx_CreateCodeObjects.constprop.0 __Pyx_PyList_Pack.constprop.0 __Pyx_CyFunction_New.constprop.0 __Pyx_CyFunction_Vectorcall_NOARGS __Pyx_CyFunction_Vectorcall_FASTCALL_KEYWORDS_METHOD __Pyx_CyFunction_Vectorcall_FASTCALL_KEYWORDS __Pyx_Import.constprop.0 __Pyx_MatchKeywordArg_nostr.constprop.0 __Pyx_Raise.constprop.0 __Pyx_CyFunction_reduce __Pyx_PyErr_GivenExceptionMatchesTuple __Pyx_PyErr_GivenExceptionMatches.part.0 __pyx_tp_clear_10sqlalchemy_11cyextension_4util_cache_anon_map __pyx_tp_traverse_10sqlalchemy_11cyextension_4util_cache_anon_map __Pyx_MatchKeywordArg_str.constprop.0 __Pyx_PyObject_FastCallDict.constprop.0 __Pyx_PyObject_CallMethod0 __Pyx_PyType_Ready __Pyx_ImportFrom __Pyx_CyFunction_get_defaults __Pyx_PyLong_As_long.part.0 __Pyx_PyLong_As_PY_LONG_LONG __Pyx_PyLong_As_int __Pyx_CyFunction_get_is_coroutine __Pyx_PyObject_GetAttrStrNoError __Pyx_setup_reduce_is_named __Pyx_GetBuiltinName __Pyx_AddTraceback __pyx_dict_version.2 __pyx_dict_cached_value.1 __pyx_f_10sqlalchemy_11cyextension_4util___pyx_unpickle_prefix_anon_map__set_state __pyx_pw_10sqlalchemy_11cyextension_4util_14cache_anon_map_5__missing__ __pyx_pw_10sqlalchemy_11cyextension_4util_15prefix_anon_map_5__setstate_cython__ __pyx_pw_10sqlalchemy_11cyextension_4util_5__pyx_unpickle_prefix_anon_map __pyx_pw_10sqlalchemy_11cyextension_4util_15prefix_anon_map_3__reduce_cython__ __pyx_dict_version.17 __pyx_dict_cached_value.16 __pyx_dict_version.15 __pyx_dict_cached_value.14 __pyx_pw_10sqlalchemy_11cyextension_4util_14cache_anon_map_7__reduce_cython__ __pyx_dict_version.21 __pyx_dict_cached_value.20 __pyx_dict_version.19 __pyx_dict_cached_value.18 __pyx_pw_10sqlalchemy_11cyextension_4util_14cache_anon_map_3get_anon __pyx_builtin_id __pyx_f_10sqlalchemy_11cyextension_4util__check_item __pyx_dict_version.9 __pyx_dict_cached_value.8 __pyx_dict_version.11 __pyx_dict_cached_value.10 __pyx_pw_10sqlalchemy_11cyextension_4util_3_distill_raw_params __pyx_dict_version.13 __pyx_dict_cached_value.12 __pyx_v_10sqlalchemy_11cyextension_4util__Empty_Tuple __pyx_pw_10sqlalchemy_11cyextension_4util_1_distill_params_20 __pyx_dict_version.7 __pyx_dict_cached_value.6 __pyx_dict_version.5 __pyx_dict_cached_value.4 __pyx_f_10sqlalchemy_11cyextension_4util___pyx_unpickle_cache_anon_map__set_state __pyx_pw_10sqlalchemy_11cyextension_4util_14cache_anon_map_9__setstate_cython__ __pyx_pw_10sqlalchemy_11cyextension_4util_7__pyx_unpickle_cache_anon_map __pyx_pw_10sqlalchemy_11cyextension_4util_15prefix_anon_map_1__missing__ DIGIT_PAIRS_10 __Pyx_setup_reduce __pyx_pymod_exec_util __Pyx_cached_runtime_version.3 __pyx_CyFunctionType_spec __pyx_string_tab __pyx_string_tab_encodings __pyx_type_10sqlalchemy_11cyextension_4util_prefix_anon_map __pyx_type_10sqlalchemy_11cyextension_4util_cache_anon_map __pyx_mdef_10sqlalchemy_11cyextension_4util_1_distill_params_20 __pyx_mdef_10sqlalchemy_11cyextension_4util_3_distill_raw_params __pyx_mdef_10sqlalchemy_11cyextension_4util_15prefix_anon_map_1__missing__ __pyx_mdef_10sqlalchemy_11cyextension_4util_15prefix_anon_map_3__reduce_cython__ __pyx_mdef_10sqlalchemy_11cyextension_4util_15prefix_anon_map_5__setstate_cython__ __pyx_mdef_10sqlalchemy_11cyextension_4util_14cache_anon_map_3get_anon __pyx_mdef_10sqlalchemy_11cyextension_4util_14cache_anon_map_5__missing__ __pyx_mdef_10sqlalchemy_11cyextension_4util_14cache_anon_map_7__reduce_cython__ __pyx_mdef_10sqlalchemy_11cyextension_4util_14cache_anon_map_9__setstate_cython__ __pyx_mdef_10sqlalchemy_11cyextension_4util_5__pyx_unpickle_prefix_anon_map __pyx_mdef_10sqlalchemy_11cyextension_4util_7__pyx_unpickle_cache_anon_map __pyx_moduledef __pyx_CyFunctionType_slots __pyx_CyFunction_methods __pyx_CyFunction_members __pyx_CyFunction_getsets __pyx_k_ __pyx_k_ArgumentError __pyx_k_Incompatible_checksums_0x_x_vs_0 __pyx_k_Incompatible_checksums_0x_x_vs_0_2 __pyx_k_List_argument_must_consist_only __pyx_k_Mapping __pyx_k_None __pyx_k_Note_that_Cython_is_deliberately __pyx_k_PickleError __pyx_k__2 __pyx_k__3 __pyx_k__4 __pyx_k_add_note __pyx_k_anonymous_counter __pyx_k_asyncio_coroutines __pyx_k_cache_anon_map __pyx_k_cache_anon_map___missing __pyx_k_cache_anon_map___reduce_cython __pyx_k_cache_anon_map___setstate_cython __pyx_k_cache_anon_map_get_anon __pyx_k_cline_in_traceback __pyx_k_collections_abc __pyx_k_derived __pyx_k_dict __pyx_k_dict_2 __pyx_k_disable __pyx_k_distill_params_20 __pyx_k_distill_raw_params __pyx_k_enable __pyx_k_exc __pyx_k_func __pyx_k_gc __pyx_k_get __pyx_k_get_anon __pyx_k_getstate __pyx_k_id __pyx_k_id_2 __pyx_k_idself __pyx_k_is_coroutine __pyx_k_isenabled __pyx_k_key __pyx_k_lib_sqlalchemy_cyextension_util __pyx_k_main __pyx_k_mapping_or_list_expected_for_par __pyx_k_mapping_or_sequence_expected_for __pyx_k_missing __pyx_k_module __pyx_k_name __pyx_k_new __pyx_k_obj __pyx_k_params __pyx_k_pickle __pyx_k_pop __pyx_k_prefix_anon_map __pyx_k_prefix_anon_map___missing __pyx_k_prefix_anon_map___reduce_cython __pyx_k_prefix_anon_map___setstate_cytho __pyx_k_pyx_PickleError __pyx_k_pyx_checksum __pyx_k_pyx_result __pyx_k_pyx_state __pyx_k_pyx_type __pyx_k_pyx_unpickle_cache_anon_map __pyx_k_pyx_unpickle_prefix_anon_map __pyx_k_qualname __pyx_k_reduce __pyx_k_reduce_cython __pyx_k_reduce_ex __pyx_k_self __pyx_k_self_dict __pyx_k_set_name __pyx_k_setstate __pyx_k_setstate_cython __pyx_k_sqlalchemy __pyx_k_sqlalchemy_cyextension_util __pyx_k_state __pyx_k_stringsource __pyx_k_test __pyx_k_update __pyx_k_use_setstate __pyx_k_val __pyx_k_value __pyx_methods __pyx_moduledef_slots __pyx_methods_10sqlalchemy_11cyextension_4util_cache_anon_map __pyx_methods_10sqlalchemy_11cyextension_4util_prefix_anon_map crtstuff.c deregister_tm_clones __do_global_dtors_aux completed.0 __do_global_dtors_aux_fini_array_entry frame_dummy __frame_dummy_init_array_entry __FRAME_END__ __dso_handle _DYNAMIC __GNU_EH_FRAME_HDR __TMC_END__ _GLOBAL_OFFSET_TABLE_ PyUnicode_FromFormat PyList_New _PyUnicode_Ready PyExc_SystemError PyDict_SetItemString PyDict_Size PyMethod_Type _ITM_deregisterTMCloneTable PyTuple_Type PyErr_Restore PyObject_ClearWeakRefs _PyThreadState_UncheckedGet PyModuleDef_Init Py_EnterRecursiveCall PyFrame_New PyMem_Free PyNumber_InPlaceAdd PyObject_GetAttrString PyObject_CallMethodObjArgs PyDict_Contains PyImport_AddModule PyBytes_FromStringAndSize _PyObject_GenericGetAttrWithDict PyObject_SetAttrString PyErr_WarnEx _Py_Dealloc PyModule_NewObject PyErr_NoMemory PyErr_SetObject PyObject_GC_Del PyObject_Str PyArg_ValidateKeywordArguments _fini PyImport_GetModuleDict PyObject_GC_Track PyExc_RuntimeError PyErr_GivenExceptionMatches PyErr_SetString PyObject_IsInstance _PyObject_GC_New PyObject_GetItem strrchr@@GLIBC_2.2.5 PyExc_DeprecationWarning PyExc_TypeError PyInterpreterState_GetID PySequence_Contains PyTuple_GetItem memset@@GLIBC_2.2.5 PyMem_Realloc PyErr_ExceptionMatches PyOS_snprintf PyTraceBack_Here PyObject_Not PyLong_FromSsize_t PyLong_FromLong memcmp@@GLIBC_2.2.5 PyObject_RichCompareBool PyModule_GetName PyErr_Clear PyExc_KeyError PyImport_GetModule _PyUnicode_FastCopyCharacters _Py_FalseStruct __gmon_start__ PyTuple_New PyObject_GenericGetAttr PyThreadState_Get PyExc_OverflowError PyDict_DelItem memcpy@@GLIBC_2.14 PyInit_util PyType_Modified PyObject_SetAttr PyErr_Occurred PyLong_AsLong _PyDict_GetItem_KnownHash Py_LeaveRecursiveCall PyObject_VectorcallDict PyTuple_GetSlice PyUnicode_Split PyDict_GetItemString _Py_NoneStruct PyObject_IsTrue _PyType_Lookup PyImport_ImportModuleLevelObject PyObject_Hash _Py_TrueStruct PyDict_SetDefault PyDict_New __pyx_module_is_main_sqlalchemy__cyextension__util PyDict_Type PyDict_Next PyBaseObject_Type PyObject_VectorcallMethod PyUnicode_AsUTF8 PyLong_Type _PyObject_GetDictPtr PyErr_Fetch PyUnicode_FromString PyUnicode_InternFromString PyExc_ImportError PyDict_SetItem PyObject_HasAttr PyExc_AttributeError PyObject_IsSubclass PyExc_RuntimeWarning PyType_FromModuleAndSpec PyObject_Call PyUnicode_Type PyUnicode_Decode PyErr_Format PyExc_NameError PyUnicode_FromStringAndSize PyModule_GetDict _ITM_registerTMCloneTable PyUnicode_FromOrdinal PyUnicode_Concat PyObject_GetAttr PyCFunction_Type PyUnicode_Format PyMem_Malloc PyErr_WarnFormat __cxa_finalize@@GLIBC_2.2.5 _init PyUnicode_New PyTuple_Pack PyCode_NewWithPosOnlyArgs Py_GetVersion PyCode_NewEmpty PyObject_GC_UnTrack PyDict_GetItemWithError PyList_Type PyImport_Import .symtab .strtab .shstrtab .note.gnu.build-id .gnu.hash .dynsym .dynstr .gnu.version .gnu.version_r .rela.dyn .rela.plt .init .text .fini .rodata .eh_frame_hdr .eh_frame .init_array .fini_array .data.rel.ro .dynamic .got .got.plt .data .bss .comment .debug_aranges .debug_info .debug_abbrev .debug_line .debug_str .debug_loc .debug_ranges 8 8 $ . ���o ` ` 4 8 � � � @ X X � H ���o U ���o 0 d H H 0 n B x/ x/ x @ @ s @ @ � ~ �F �F �� � �( �( � 0 0 X � XJ XJ � � �L �L � � �w �g � �w �g � x h P � P} Pm � � o � � � p p � �� �s � � � � 0 / � / ?� �� � x # M �' / 0 FD sQ : �� � E �� 0= �� 8% ! � % $ S sqlalchemy/cyextension/resultproxy.pyx 0000644 00000005245 15125143220 0014441 0 ustar 00 # cyextension/resultproxy.pyx # Copyright (C) 2005-2024 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php import operator cdef class BaseRow: cdef readonly object _parent cdef readonly dict _key_to_index cdef readonly tuple _data def __init__(self, object parent, object processors, dict key_to_index, object data): """Row objects are constructed by CursorResult objects.""" self._parent = parent self._key_to_index = key_to_index if processors: self._data = _apply_processors(processors, data) else: self._data = tuple(data) def __reduce__(self): return ( rowproxy_reconstructor, (self.__class__, self.__getstate__()), ) def __getstate__(self): return {"_parent": self._parent, "_data": self._data} def __setstate__(self, dict state): parent = state["_parent"] self._parent = parent self._data = state["_data"] self._key_to_index = parent._key_to_index def _values_impl(self): return list(self) def __iter__(self): return iter(self._data) def __len__(self): return len(self._data) def __hash__(self): return hash(self._data) def __getitem__(self, index): return self._data[index] def _get_by_key_impl_mapping(self, key): return self._get_by_key_impl(key, 0) cdef _get_by_key_impl(self, object key, int attr_err): index = self._key_to_index.get(key) if index is not None: return self._data[<int>index] self._parent._key_not_found(key, attr_err != 0) def __getattr__(self, name): return self._get_by_key_impl(name, 1) def _to_tuple_instance(self): return self._data cdef tuple _apply_processors(proc, data): res = [] for i in range(len(proc)): p = proc[i] if p is None: res.append(data[i]) else: res.append(p(data[i])) return tuple(res) def rowproxy_reconstructor(cls, state): obj = cls.__new__(cls) obj.__setstate__(state) return obj cdef int is_contiguous(tuple indexes): cdef int i for i in range(1, len(indexes)): if indexes[i-1] != indexes[i] -1: return 0 return 1 def tuplegetter(*indexes): if len(indexes) == 1 or is_contiguous(indexes) != 0: # slice form is faster but returns a list if input is list return operator.itemgetter(slice(indexes[0], indexes[-1] + 1)) else: return operator.itemgetter(*indexes) sqlalchemy/cyextension/immutabledict.pyx 0000644 00000006717 15125143220 0014651 0 ustar 00 # cyextension/immutabledict.pyx # Copyright (C) 2005-2024 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php from cpython.dict cimport PyDict_New, PyDict_Update, PyDict_Size def _readonly_fn(obj): raise TypeError( "%s object is immutable and/or readonly" % obj.__class__.__name__) def _immutable_fn(obj): raise TypeError( "%s object is immutable" % obj.__class__.__name__) class ReadOnlyContainer: __slots__ = () def _readonly(self, *a,**kw): _readonly_fn(self) __delitem__ = __setitem__ = __setattr__ = _readonly class ImmutableDictBase(dict): def _immutable(self, *a,**kw): _immutable_fn(self) @classmethod def __class_getitem__(cls, key): return cls __delitem__ = __setitem__ = __setattr__ = _immutable clear = pop = popitem = setdefault = update = _immutable cdef class immutabledict(dict): def __repr__(self): return f"immutabledict({dict.__repr__(self)})" @classmethod def __class_getitem__(cls, key): return cls def union(self, *args, **kw): cdef dict to_merge = None cdef immutabledict result cdef Py_ssize_t args_len = len(args) if args_len > 1: raise TypeError( f'union expected at most 1 argument, got {args_len}' ) if args_len == 1: attribute = args[0] if isinstance(attribute, dict): to_merge = <dict> attribute if to_merge is None: to_merge = dict(*args, **kw) if PyDict_Size(to_merge) == 0: return self # new + update is faster than immutabledict(self) result = immutabledict() PyDict_Update(result, self) PyDict_Update(result, to_merge) return result def merge_with(self, *other): cdef immutabledict result = None cdef object d cdef bint update = False if not other: return self for d in other: if d: if update == False: update = True # new + update is faster than immutabledict(self) result = immutabledict() PyDict_Update(result, self) PyDict_Update( result, <dict>(d if isinstance(d, dict) else dict(d)) ) return self if update == False else result def copy(self): return self def __reduce__(self): return immutabledict, (dict(self), ) def __delitem__(self, k): _immutable_fn(self) def __setitem__(self, k, v): _immutable_fn(self) def __setattr__(self, k, v): _immutable_fn(self) def clear(self, *args, **kw): _immutable_fn(self) def pop(self, *args, **kw): _immutable_fn(self) def popitem(self, *args, **kw): _immutable_fn(self) def setdefault(self, *args, **kw): _immutable_fn(self) def update(self, *args, **kw): _immutable_fn(self) # PEP 584 def __ior__(self, other): _immutable_fn(self) def __or__(self, other): return immutabledict(dict.__or__(self, other)) def __ror__(self, other): # NOTE: this is used only in cython 3.x; # version 0.x will call __or__ with args inversed return immutabledict(dict.__ror__(self, other)) sqlalchemy/cyextension/processors.cpython-39-x86_64-linux-gnu.so 0000644 00002040540 15125143220 0020617 0 ustar 00 ELF > �F @ �8 @ 8 @ # " 5 5 @ @ @ Q� Q� � � � % % P P) P) h @ @- @- � � 8 8 8 $ $ P�td � � � $ $ Q�td R�td P P) P) � � GNU ��%� c��>�` ���7� � � X� � � � f,¬������� � � � � � � ? M L _ � q � 5 t � � � + � � 9 d ) � @ � d � m � � � � � � J { � , � � a � & � 3 � � : w � � � Z � � � p � � Y � � a � � � : h ` q p I k ) � � 3 � � � � � � � O R � : H w � � . � 8 ) � H I R " � � � 5 � # � M �k � �< @ H� __gmon_start__ _init _fini _ITM_deregisterTMCloneTable _ITM_registerTMCloneTable __cxa_finalize _Py_NoneStruct PyDict_New PyExc_TypeError PyErr_Format PyExc_SystemError PyErr_SetString PyDict_Size PyObject_GetAttr PyMethod_New PyUnicode_InternFromString PyUnicode_FromString PyUnicode_FromFormat _Py_Dealloc PyObject_GC_UnTrack PyObject_GC_IsFinalized PyObject_CallFinalizerFromDealloc PyDict_SetItem PyType_Modified PyObject_HasAttr PyObject_CallMethodObjArgs PyExc_AttributeError PyErr_ExceptionMatches PyExc_ImportError PyErr_Clear PyModule_GetName PyUnicode_Concat PyImport_GetModule PyObject_ClearWeakRefs PyObject_GC_Del PyObject_GetAttrString PyDict_SetItemString PyThreadState_Get PyInterpreterState_GetID PyModule_NewObject PyModule_GetDict PyTuple_GetSlice PyTuple_GetItem PyMem_Malloc PyTuple_New PyDict_Next PyMem_Free PyErr_NoMemory PyExc_RuntimeWarning PyErr_WarnEx PyDict_SetDefault PyCode_NewWithPosOnlyArgs PyList_New PyImport_ImportModuleLevelObject _PyObject_GC_New PyObject_GC_Track PyObject_RichCompareBool PyBaseObject_Type PyErr_GivenExceptionMatches memcmp PyObject_Hash PyCFunction_Type PyObject_VectorcallDict Py_EnterRecursiveCall Py_LeaveRecursiveCall PyErr_Occurred PyObject_Call PyObject_GenericGetAttr _PyType_Lookup PyType_Ready _PyObject_GetDictPtr _PyDict_GetItem_KnownHash PyMethod_Type _PyObject_GenericGetAttrWithDict _PyThreadState_UncheckedGet _Py_TrueStruct _Py_FalseStruct PyObject_IsTrue PyOS_string_to_double PyFloat_FromString PyExc_NameError PyObject_Not PyFrame_New PyTraceBack_Here PyObject_SetAttr PyCode_NewEmpty PyUnicode_AsUTF8 PyMem_Realloc PyUnicode_Type PyUnicode_Format PyNumber_Remainder PyArg_ValidateKeywordArguments PyDict_GetItemWithError PyObject_IsSubclass PyErr_SetObject PyTuple_Pack PyFloat_Type PyLong_Type PyBytes_Type PyByteArray_Type _PyByteArray_empty_string PyFloat_FromDouble PyNumber_Float PyUnicode_AsUTF8AndSize PyLong_AsDouble _PyUnicode_IsWhitespace _Py_ascii_whitespace _PyUnicode_Ready PyObject_Str PyExc_RuntimeError PyImport_AddModule PyObject_SetAttrString Py_GetVersion PyOS_snprintf PyBytes_FromStringAndSize PyUnicode_FromStringAndSize strrchr PyType_FromModuleAndSpec PyDict_Type PyUnicode_Decode __pyx_module_is_main_sqlalchemy__cyextension__processors PyImport_GetModuleDict PyDict_GetItemString PyDict_DelItem PyImport_ImportModule PyExc_ValueError PyImport_Import PyErr_Fetch PyErr_Restore PyInit_processors PyModuleDef_Init libpthread.so.0 libc.so.6 GLIBC_2.2.5 � ui � P) �l X) Pl `) `) �) _ �) 0 �) p �) �) � �) P �) N �) * � * ] * � 0* � @* I P* � `* x p* � �* � �* � �* � �* X �* @ �* Z �* h �* � + + x + � 0+ �� @+ 0 P+ � `+ p+ `� �+ S �+ � �+ � �+ X �+ W �+ � �+ @ �+ � , , H , 8 0, @, P, � `, � p, � �, � �, � �, h �, �, � �, ( �, �, � - � - � - � �3 p� �3 �3 �3 Pt �3 �o �3 Pv �3 �t �3 �q �3 @4 4 �4 4 `5 (4 Po @4 b� H4 0~ �4 m� �4 x� �4 �� �4 �� `5 �� h5 �o p5 Pq �5 �� �5 �o �5 Pq �5 �� �5 po �5 �| �5 �� �5 po �5 �| 6 �� 6 �l 6 | (6 �� 06 Pm 86 �{ P6 �� X6 Pm `6 �{ x6 �� �6 �l �6 � �6 �l �6 � �6 �l �6 � �6 �l 7 %� 7 �l @7 /� H7 �l h7 8� p7 p x7 �z �7 F� �7 p �7 �z �7 S� �7 P� �7 Pz �7 b� �7 m �7 �y 8 r� 8 P� �8 �� �8 �< �8 �8 �8 ~H �8 �P 89 �� P9 �p �9 �l �9 �q : �: X: �� �: _� �: 0� �: �� �: � ; �� ; � @; �� H; � `; �� h; � �; _� �; 0� �; �� �; 0� �; �� �; @� �; �� �; P� < �� < `� < �� (< � @< �� H< � / / / (/ 0/ 8/ @/ H/ P/ & X/ + `/ - h/ � p/ > x/ ? �/ A �/ O �/ T �/ Y �/ [ �/ ] �/ b �/ e �/ g �/ j �/ n �/ q �/ t �/ w 0 0 (0 00 80 @0 H0 P0 X0 `0 h0 p0 x0 �0 �0 �0 �0 �0 �0 �0 �0 �0 �0 �0 �0 ! �0 " �0 # �0 $ �0 % 1 ' 1 ( 1 ) 1 * 1 , (1 . 01 / 81 0 @1 1 H1 2 P1 3 X1 4 `1 5 h1 6 p1 7 x1 8 �1 9 �1 : �1 ; �1 < �1 = �1 ? �1 @ �1 B �1 C �1 D �1 E �1 F �1 G �1 H �1 I �1 J 2 K 2 L 2 M 2 N 2 P (2 Q 02 R 82 S @2 U H2 V P2 W X2 X `2 Z h2 \ p2 ^ x2 _ �2 ` �2 a �2 c �2 d �2 f �2 h �2 i �2 k �2 l �2 m �2 o �2 p �2 r �2 s �2 u �2 v 3 w 3 x 3 y 3 z 3 { (3 | 03 } 83 ~ @3 H��H�m� H��t�; H��� �5�� �%�� @ �%�� h ����%�� h �����%�� h ����%�� h ����%�� h ����%�� h ����%�� h ����%�� h �p����%�� h �`����%�� h �P����%�� h �@����%�� h �0����%�� h � ����%z� h �����%r� h � ����%j� h ���%b� h ����%Z� h �����%R� h ����%J� h ����%B� h ����%:� h ����%2� h ����%*� h �p����%"� h �`����%� h �P����%� h �@����% � h �0����%� h � ����%�� h �����%�� h � ����%�� h ���%�� h ����%�� h! �����%�� h" ����%�� h# ����%�� h$ ����%�� h% ����%�� h& ����%�� h' �p����%�� h( �`����%�� h) �P����%�� h* �@����%�� h+ �0����%�� h, � ����%z� h- �����%r� h. � ����%j� h/ ���%b� h0 ����%Z� h1 �����%R� h2 ����%J� h3 ����%B� h4 ����%:� h5 ����%2� h6 ����%*� h7 �p����%"� h8 �`����%� h9 �P����%� h: �@����% � h; �0����%� h< � ����%�� h= �����%�� h> � ����%�� h? ���%�� h@ ����%�� hA �����%�� hB ����%�� hC ����%�� hD ����%�� hE ����%�� hF ����%�� hG �p����%�� hH �`����%�� hI �P����%�� hJ �@����%�� hK �0����%�� hL � ����%z� hM �����%r� hN � ����%j� hO ���%b� hP ����%Z� hQ �����%R� hR ����%J� hS ����%B� hT ����%:� hU ����%2� hV ����%*� hW �p����%"� hX �`����%� hY �P����%� hZ �@����% � h[ �0����%� h\ � ����%�� h] �����%�� h^ � ����%�� h_ ���%�� h` ����%�� ha �����%�� hb ����%�� hc ����%�� hd ����%�� he ���AVI��AUI��ATUH��QH�� �s���A�ą�uML�����H�5E� H���e�����t2H�52� H��E1�L��L��1�����H��H��t H�u �u����A��ZD��]A\A]A^�AWI��AVAUATUH��SQ� ( I��H���� H��� H�8�B�����u H�g� L��H�5N� H�81��3���� ����H�����H��H��t����H��H��t�H�55� H��1��+���I��H��t:L��H������I��H��tH�����I�M H��uL�����I� $uL�����H�M uH�����H���T���I��ZL��[]A\A]A^A_�AVI��AUI��H��ATUSD������H��t5H;c� H��uE1��tH��L��L��� ���A��H�M u)H��� ���� H�^� A��H�8������t���E1�[D��]A\A]A^�AVAUI��ATUQ���H�x���H���t1H��� H���u H��� �#H9�t H��� H�5ʪ H�8�B���E1�� L�%� M��t I�$�� H�5ө L�����I��H��t�H���v���I�H��uL���V���H��t�H�����I��H���� A� H� w� H��L��H�u� �����xkA� H� f� L��L��H�b� �����xHA� H� S� L��L��H�R� �h�����x%E1�H� F� L��L��H�B� �H�����xI���H�M ����H�����ZL��]A\A]A^�QH�G��� �u H��H�5�� �1�H9W t H��H�5� H�N� H�81��t�����Z�AWAVAUI��ATE1�UH��H��SH��H��A�׃�H��A��H��(H�t$L�D$H�T$���H���� H�T$L�D$I��1�H�t$H9�~H� �H�I�L�H����L��L��L�����I��H��t^H�e� A��H��H��fA����H��A��H����H����L�@� ����A�� APSAUUPPATPPAPE1�� ���H��PI��I�uL���Y���H��(L��[]A\A]A^A_�H��X� H�t$(����H�t$`H�|$ �D$ H�t$H�|$H��tH�WH�HH�H�H��X�AVI��AUI��ATE1�UQ����H��t,H�5n� H��E1�L��H��L�����H�M I��uH�����ZL��]A\A]A^�AWA��AVI��AUM��ATUH��SL��H��H�=I� H�T$�?���H�T$H���5 fIn�fHn�D��� I��fl�H�@( H�@p @H��tH�E I�l$ I�D$@ I�D$H H�I�T$PI�D$X I�D$8 M�l$`I�E H��tH�A�FW�I�\$hI�D$x A�$� %� IDŽ$� A�$� ��t6��tK��uQH�J6 I�D$0�l=� t#=� u5H��5 I�D$0�PH��( I�D$0�BH�5 I�D$0�4I�D$0 �)H��� H�5(� H�8���I� $uL���<�E1��L����H��L��[]A\A]A^A_�AWAVAUATI��USH��H��(L�wH�� I9�� t �! H���* I�� tL��L�����I��H��u�EL���1�����y�� H� H�@��� u1L�� M��tH�� �� �D$ ��D$ E1�� �D$ E1�H������H��tBH�8H��t:H�I�T$L��H�|$����H�|$H��H���� ���H�|$H�u� �|$ �� M��t H�SH��L��A��I�H��u:L������0L��M���� H�#� I�VL��H�5�� H�81����� H���� H�V� H9EusH;]umL�}I�H�M uH����H�t$L��H� �H�D$ H�\$��4 I�I��u_L���X��UH� H�u�I�M��t�I�u�L���7�뀺 W�H�t$H��H��?)D$�4 H�M I��u H�����E1�H��(L��[]A\A]A^A_�ATI��UQH�5!� �L8 H��H��u��E1�H��t'�L�� H���U�A�ą�x�H�M uH����D��Z]A\�AVI��AUATUV�X�H���� H�5(� H��I����7 H��H���� H�5b� H����7 I��H��uH�M u>H���<��4H;S� ��L;%)� ���u L;%3� u���L������t��M��tT1�I� $uL�����H��t?H�M uH�����I�M uL��������H��t��YL��]1�A\A]A^����h�ZL��]A\A]A^�AWAVAUATUSH�� H��� H��t)1�H9��� H�M� H�5V� H�8���� H�H�=�� ��H��� H���W H� H�=ʠ ���H��tH� H��� H���J H�=�� ��H��tH� H��� H�=.� H���9 H�v� H�5�� �����8 H� �� H��uP�y� 1Ҿ I��1�Hc�A� D�I�A�� w k� �D���H��HÀ�.u H�����u�H� �� H��� H��H��� �� ��u1��>�H��� H��u|�� H��H��H�l$0WH���� H��A� ��L� \� � RH�w� PH��� P1���H�� 1�� H�������y�A�� L�5s� A� 1��� 1�H�=�� �h�H�a� H���J 1�H�=�� ���H�K� H���F L�=�� �. L���F�H��tL�xL����I��H��� H�=#� 1����I��H���� H� H���t�H��H���A L��H��� �H��H��u�`�H��t � H� �Q1�H�5� L�����I��H���� H��L��H����H��H��tIH� H�PH�U I9�t&I�M uL����Hc�� L��H��� �����x�*H�E H��u!H�����L��H�M �� H��1��n�I� $uL���`�I�u/L���S��%A�� L�5� A� 1�H��� �H H�-�� H���� H�e� H� � �~.� fHn�H�� ���L�%�� fl�)�� H�;H���� �C � t/�@t�l��2�s��Hc�$ t��1�I����������s��Hc��H�H��uA� L�5&� A� 1�� H�E H���m�H��t�H��H���s�����H��H���' H�;� �8 �� ��I��H��� H�5j� H�����H���� H�=�� �E< H��� A� A� � L�5�� H�= � tFH�=b� t��tL��D��H�=�� D���> H�=�� H��t7H�H��� u'��� ���H��uH��� H�5T� H�8��1�H�=�� ����� H��� H�5�� H�=�� ��������A� A� � L�5ơ �=���H�Z� H�5[� L��������A� A� � L�5�� ����H�=g� �; H� � H��������I��H���f H��� H� �� H�\$0M��H��� H��H�� H�D$0�6�H��� H��� H��� H� o� M��H��H��� H�� H�D$0��H�O� H���� H�G� H� (� M��H��H�C� H�� H�D$0��H�� H���� H�� H� �� M��H��H�� H�� & H�D$0�y�H��� H���W H��� H� z� M��H��H��� H�� + H�D$0�:�H��� H��� H��� H� +� M��H��H��� H�� 1 H�D$0��H�s� H���� H��� H� �� M��H��H�G� H�� @ ! H�D$0H�!� H�D$8��H�0� H���� H�x� H� a� M��H��H��� H�� H�D$0�q�H��� H��tS(=� H� N� M��H��fl�� H�q� H�� )D$0�.�H��� H��tI� $u5L���c��+I� $uL���S�A� A� � L�5۞ �R���H��� H� � H��P �� H�� H��u�H�=�� �r�A��H�=8� E��y A�! A� � L�5{� ��H��� H�5(� ����x�L�5�� H�5�� L����L�-�� H��I��u H�5� L���k�I��H���� �H�5v� L���N�I9��� ��H�5�� L��� H�D$H���� I9�� H�5�� L����I��H���z H�5�� L���� H�D$H���n H�5~� I9�uH�5r� L���Z- I��H��u"�gH�|$���D$��u�E1�E1�E1��p H�51� H��L�������� I�� H�5� ���D$��u L�����)�� �!L;d$�� ��H���� �D$ H�5�� L���, I��H���� ��H�5�� L���, I��H��tCH�5�� H��L���/����� I�� H�5�� ���D$��u L�����xZ�M��tS�$�H��uIL�����uH�D$ E1�E1�E1�H�D$ �"H�D$ E1�E1��E1�E1�E1��E1�E1����H��u H�U� I�VH�5� H�81���H�|$ �D$����t"H�D$H�L$H� H�D$H��H�uH���.�H�|$ t5��D$ E1�E1�E1�H�D$H�L$H� H�D$H��H�uH�����M��t I�uL�����M��tI� $uL�����M��tI�M uL�����|$������H�=D� ��I��H���V H�5|� H����I��H���� H�@��� �u+H�W� H� M� H��� H�5� H�81��h�� M�M(I�E M��t I��� LL�I�I��o w1H��� A�p H� �� H��� H�5� H�81����) H=p vTRH� y� �� H��PA�p L��� 1�H�%� ���H��1�1���Y^���� �H�]� �� L�-Q� I� $uL���{�H�=4� ���I��H���p H�5 � H�=�� H�������� I�uL���8�H�5�� � 1����I��H���C H�=�� H��� �H��H���� I�uL�����H�5�� H����I��H���� H�5�� H�=X� H���p����s I�uL����H�M uH����H�5�� � 1��C�H��H���� H�=7� H���o�I��H���u H�M uH���U�H�5>� L�����H��H��� H�5+� H�=�� H��������� H�M uH����I�uL����H�5�� � 1���I��H���F H�=�� H�����H��H���� I�uL����H�5c� H���H�I��H���� H�5P� H�=!� H���9����t I�uL���t�H�M uH���f�H�=�� ���H��H���� H�5�� H�=�� H��������r H�M uH���"�L� #� L��� 1�H�=�� H� �� H� � �K�H��H���� H�5�� H�=n� H�������( H�M uH����L� �� L�B� 1�H�=Y� H� Z� H��� ���H��H���E H�5�� H�= � H���$����� H�M uH���^�L� o� L��� 1�H�=�� H� �� H�9� ��H��H��� H�5!� H�=�� H��������� H�M uH�����L� � L�~� 1�H�=U� H� �� H��� �%�H��H���� H�5�� H�=H� H���`����J H�M uH�����L� �� L� � 1�H�=�� H� 4� H�E� ���H��H���v H�5-� H�=�� H������� H�M uH���8��L� a� L��� 1�H�=Q� H� �� H��� �a�H��H���1 H�5�� H�=�� H�������� H�M uH������L� � L�X� � H�=�� H� m� H�&� ��H��H���� H�5�� H�=g� H�������i H�M uH���q��L� �� L��� � H�=G� H� � H��� ��H��H���� H�5�� H�=�� H�������� H�M uH��� ��L� M� L��� � H�=�� H� �� H�T� �2�H��H���Y H�5t� H�=U� H���m����� H�M uH��������H��H���9 H�5w� H�=� H���0����� H�M ���H���f�����A�0 A� �RA�< A� �DA�A A� �6A�Q A� �(A�S A� �A�` A� � A�e A� I�uL������L�5�� � H�����H�M � ���H���������I�M ����L�����H�n� I� $�\ L��A�" � A� ���L�5 � ��H�5� H��E1��v����%������H� Q� H���� H�=� H�q� L��� H9��� H�D���� u9H�PH��� H�5Ȗ A�! L�5�� A� � H�81�����H��uFH�� t<H�HH��� L��H�5�� A�! A� � H�81�L�5@� �����H���]���H�=� �R��I��H��uH�=k� �n�I��H���o�H�5{� L���6�I��H��uI� $�N�L���9���A�H;M� ��A��L;- � ��E���uL;-%� t L������A��I�M uL������E��~#H�5�� L����H��H��t�H�u����� A����u���H�=i� H� � ���H�%�� ����A��E���� H�t$(H�|$ H��� ��H�5Q� L���T�H��H��u A���u%H��t H�u�T��H�T$0H�t$(H�|$ �P���@H�|$ H��t H�u�*��H�|$(H��t H�u���H�|$0H��t H�u���A��I� $���L���������1��r�A�� L�5s� A� 1����A�� L�5Y� A� 1����A�� L�5?� A� 1���A�� L�5%� A� 1���A�� L�5 � A� 1��z�A�� L�5� A� 1��`�A�� L�5 A� 1��F�A�� L�5�� A� 1��,�A� A� � L�5�� ��A�. A� � L�5{� ���A�: A� � L�5^� ���A�L A� � L�5A� ��A�^ A� � L�5$� ��A�p A� � L�5� �~�A�| A� � L�5� �a�A�� A� � L�5͎ �D�A�� A� � L�5�� �'�A�� A�& � L�5�� � �A�� A�+ � L�5v� ���A�� A�1 � L�5Y� ���A�� A�@ � L�5<� ��A�� A� � L�5�� ��A�� A� � L�5�� �y�A�� A� � L�5� �\�A�" A� � L�5ȍ �?�A� A� � L�5�� �"�A�? L�5�� A� ����A�N L�5�� A� ���A�c L�5i� A� ����A�r L�5Q� A� ����A�~ L�59� A� ���A�� L�5!� A� ���A�� L�5 � A� ����A�� L�5� A�& �g���A�� L�5ٌ A�+ �O���A�� L�5�� A�1 �7���A�� L�5�� A�@ � ���A�� L�5&� A� ����A�� L�5� A� ���A�� L�5a� A� ����H�� []A\A]A^A_�H�=�� ���� � H�=y� H�r� H9�tH�&� H��t �� � � � H�=I� H�5B� H)�H��H��?H��H�H�tH��� H��t��f D � � �= � u/UH�=�� H��t H�=� ����h������ ]� � � � �{���f. � �H�H��H��H��t �� � 1�� D H�GPH� � � H�G`H� � � H��� H� � @ H�GhH��tH� �f�H��� H� � @ H��� H��t H� � � H��H�|$�j��H��tH�|$H��� H� H���H�G@H��tH� �f�H��H�|$�2��H�|$H�G@H��tH� H���ff. � UH��H��SH��H��H�GL�H�@����tV$���� ���� H��H��H��[]A�� ��ukH���� L�FI���$ H�vH��H��[]A�� @ H���� L�F1�M��t�H�CH� ف H�H�/� H�5ہ H�81��N��� @ H��� H�5� H�8���H��1�[]�f � H��t�H��L� $H�T$����L� $H�t$H���`����)f D H��L� $H�T$���L� $H�t$H���#���H�CH� �� H�5�� H�H��� H�81�����p���f�H��L� $H�T$�o��L� $H�t$H�������� H�CH� � ��� � H�GH��� H��t��f D ��� H��t ����f D H�H��� � H�GHH��tH� �f�SH�GH��H�8���H�CHH��tH� [ÐH�GXH��tH� �f�SH�GH��H�xH��t�:��H�CXH��tH� [� H��� H� [�ff. � H�wPH��1�H�=�� �+��ff. � ATSH��L��� M��tI�$H��L��[A\� D H��� H��H��tA��H��H��t�L�`H�@ L��� I�$H��� H� H�/u����L��� � @ L�%�� �ff. � @ UH�GH��H��� unH�����H�}H��tH�E H�/t?H�}H��tH�E H�/tH�EH��]H��@ �� � �k����f � �[���f � �����u�H�UH�l���H9B0�t���H���j�����d���]�H��t3L�GXH�H�wXM��tI�(t1�ÐH��L������1�H��� D H�5�� ��ff. � @ H�� L�GH� H�GM��tI�(t 1�� � H��L�����1�H��� D SH��H�pH��tH�Cp H�/�A H�{ H��tH�C H�/� H�{@H��tH�C@ H�/�� H�{HH��tH�CH H�/�� H�{PH��tH�CP H�/�� H�{XH��tH�CX H�/�j H�{`H��tH�C` H�/�? H�{hH��tH�Ch H�/� H�{8H�C8 H��t H�/�� H��� H��tHǃ� H�/�� H��� H��tHǃ� H�/�� H��� H��tHǃ� H�/tZH��� H��tHǃ� H�/t-H�{xH��tH�Cx H�/t1�[�f����1�[� � ������f � �����f � �����o���f D ����>���f D ���� ���f D ������f D ������f D �{�����f D �k���a���f D �[���6���f D �K��� ���f D �;�����f D �+�����f D UH�����H�}( tH���(��H���p���H��]�7�� � ATI��UH��SH��H�pH��t H��Յ��� H�{ H��t L��Յ��� H�{@H��t L��Յ��� H�{XH��t L��Յ�uH�{`H��t L��Յ�umH�{8H��t L��Յ�u[H��� H��t L��Յ�uFH��� H��t L��Յ�u1H��� H��t L��Յ�u H�{x1�H��t[L��H��]A\�� D []A\�ff. � H����� L�OH��?����t%H��upH�H��u6I�AH�6H����f � H��t{H���� H�>H��H���� D H��� I��I�H� Gz H�5(z H�81����1�H��� @ H�y t�H� Vz H�K� I�H�5`z H�81��g���� D H� �z �� � H�y �s���� AWAVI��AUATI��UH��SH��hL�G0M���� ��� ����t H�wH��hH��L��[]A\A]A^A_���H�VL��� �o��I��H���� L��1����I��H���M L��L��H��H�����I�m I��tBH��hL��[]A\A]A^A_�L�~H�vH��u;H��hL��H��1�[]A\A]A^A_A��f. � L���8���f D E1�� H�BH�D$H��t�J�<8L�D$H�����I��H���$ M��L�D$tWI�F I9��� I�G�H���� L��1�H��H�� �AoDAD H��H9�u�L��H��A��t I�T�I�T� H�|$L�D$�|��L�D$H��H�D$�� K�D� 1�A� L�|$ H��H�D$H�L$PL��H�D$XH�|$HL�l$0I��H�l$8I��H��I��H�D$H L�D$(�; � H�D$PH�L$H�PH#�� H�T$XH� H�J�D�H�D$J��I��L��H��L��L���+����u�L�|$ L�D$(I��L�l$0H�l$8H���� H�L$L��L��H��A��I��H�\$H�H�D$ H��H��� H�\$H��~_L�d$1��f D H��H9�tGI�<�H�/u��X����f D I�m t6H�2� H�UPH�5'{ H�81��M����� � L��������L��� ���H������s���1�f. � I�T�I�T� H��I9�u��=�������E1��I���L��E1��0���9���H��� H�5_w H�8�E�����H��H;5�� tH��tH�F��� tAH�� 1�L��� H��� M��tI�(t 1�H���f D L���H����f D H�)� H�5Rz H�8����������� UH��SH��H�(� H9�tH��H��uSH��H�I� � H�5mz H�8����H��� H�H��� H��tH�/t1�H��[]� � �����H�F��� u�H��� H�5�y H�8�-��������f D UH��SH��H��� H9�tH��H��uSH��H��� � H�5ez H�8�5��H��� H�H��� H��tH�/t1�H��[]� � �����H�F��� u�H�� H�5�y H�8���������f D H��H��t?H�F��� tZL�G@H�H�w@M��tI�(t 1�H��� @ L�������f D H��� H�5z H�8�"�������H��� � H�Y� H�5 z H�8��������� H��H��t?H�F��� t2L�GPH�H�wPM��tI�(t 1�H��� @ L�������f D H�� H�5�y H�8��������H��� � H��H��t?H�F��� t2L�GHH�H�wHM��tI�(t 1�H��� @ L�������f D H��� H�5�y H�8�"�������H��� � AWAVAUM��ATUSH��H�G��� �� H�I��H��H��I��I��H��u�I D I�FI��H��t7H�8� L�������tn���uٸ����H��[]A\A]A^A_� D H��H9��� H�� L��H�8�p����t܃�u�H��� L��L��H�5 y H�81�����������f�I)�I��M�4$H��[]A\A]A^A_�f D H�i� L��H�5�x H�81����H�������[]A\A]A^A_Ð1��E���f � H�GPH� � � H�G��� ��� ��� @�� H�FH��� � ��� ��� @�� H9�t*H��X H��t.H�JH��~v1�� �H��H9�thH;t�u� �f. � H�� H9�t�H��u�1�H;5ư ���f�H�� D H�� H9�t�H��u�H;�� t�f D I��M9�uG1�� @ ���� � t�L�VM��~�1�� @ H��I9�tH;|�u��c��� E1� D J�T�H�B��� �t���� @t�H9��4���H��X H���T���L�AM���o���1�� H��I9��[���H;T�u� �f D AWAVAUATI��UH��SH��H��(L�wH�L$L�D$I����� H�E H���� I�L$0I��M�l$HH�L$�I�GI��H���� H� L9pu�L�@M;D$u�D�X A�T$ D�މ�@��@������@8�u�A�� �V H�x0H��HA��@HD��� �- L�\$��@MD�@��L��I���Y�����q���H�D$I)�I��L�8� H��([]A\A]A^A_�f D H9��� M�l$0M�|$H� H��H9��� H�H� L;pu�L�@M;D$u�D�X A�T$ D�މ�@��@������@8�u�A�� �� H�xH�� �� ��@M��MD�@��L��I�������u�H��� H�T$L��H�5Vu H�81����������-���f. � H��(1�[]A\A]A^A_� � M�\$H����f D H�xH��� � H�x0H��HA��@HD��� �]���M�\$H�]������I��H�������������f � ��� L�GH��?����t H�A�`�H��tH�>H��H��A�` @ H��H� � I�H� �n H�5n H�81��"��1�H���ff. � ��� H��?I��I��H��H�W����tL�WH�w8H�BL��L��� @ H��t#L�I��H�w8H��H�BL��L��� � H��H�u� H�H� n H�5�m H�81����1�H��� H����� L�OH��?����t H��u`H�H��u'I�A1�H���� H��tsH��u~H�>H���� D H��� I��I�H� �l H�5�l H�81�� ��1�H��� @ H�y t�H� �l H��� I�H�5�l H�81������� D H� Im �� � H�y �w���� AUI��I��I��ATI��?UH��SH��H�.� H�wM���� I��tCH9��� ��� �� H�F8H�D H���� H��H��1�L��[L��]A\A]�� @ H9��� H�=x� H9��� L��X M���� I�[H��~&1� @ I�L�H9��" H9�� H��H9�u�� �n���� �M���� H��H��1�L��[L��]A\A]�-��� D H9�� H�=� H9�� L��X M���� I�[H��~&1� @ I�L�H9��� H9��� H��H9�u�� ���� H��� L�%�� H���� H�=�q �M������� 1�L��H���I���s���M���� H��L��[]A\A]� @ H�E0��� � H�� D H�� H9�t4H��u�H� ȩ H9�t#H��H�� H9�tH��u�H9��F���f D H�M�A��1���H�YE1� uL�eH�=�p 薺��1����� L���I��追��M���L����q���I��H���� H��� H�5�p H�8蟻��� ���H�� � H�� H9�t4H��u�H� � H9�t#H��H�� H9�tH��u�H9������f D H�M�A����M�)H�YE1� uL�eH�=p �ӹ����uL���;��� � E1���� � H�M�A����� @ H�M�A�u�����H��L��H��1�[]A\A]�����ATSH��L��� M��tI�$H��L��[A\� D H��� H��H��tA��H��H��t�H�@L�g H��� H� L��� I�$H�/u�赹��L��� � @ L�%�� �ff. � @ H�GH��� H;�� u � 1��0���AVAUATUSH��H��t ��I��M��t%H��L��[]A\A]A^� D 蛽��I����f D �[���H��H�i� H�{XH�(H9��� H��t�H�EH��� � � H�W��� ��� ��� @�� � ��� ��� @�� H��X H���� H�JH���N���1�� � H��H9��6���H;l�u�H�khH�Ch f�L�k`CXH�/t`M��tI�m t[H�������H�m ��H���>������H�����������H�{Xf�L�k`H�khH�Ch CXH��u�������L������L�mM�������1�� H��I9�t6H;|�u��K���H��H�� H9��8���H��u�H;-� �&����P���E1�J�t�H9��k���H�|$�Z�H�|$���T���I��M9�u�����ff. � @ AVH�AUATI��UH��SH��P��H���w�EH���H���v�< t� @ H��H��H9�v� �q�@��v� t�I��I)�M���� �P�L��� ����H�L H)����N�� �� ��9� ��/ ��.�y I�E�H��� L��f��f�H��H���fo=�x f��f��fDo�x H� D �o H��fAt�f��fo�fh�f`�fDo�fi�fo�fi�fDa�fa�fDo�fb�fDj�fA��fDo�fb�fDj�fA��f��fAo�fDb�fj�fD��fo�fj�fb�f��fD��fA��f��H9��e���fo�L��fs�H���f��fH~�A���z 1��| _H�J@��H�I9��_ 1��|_H�J@��H�I9��D 1��|_H�J@��H�I9��) 1��|_H�J@��H�I9�� 1��|_H�J@��H�I9��� 1��|_H�J@��H�I9��� 1��|_H�J@��H�I9��� 1��|_H�J@��H�I9��� 1��|_H�J @��H�I9��� 1��| _H�J @��H�I9�~p1��| _H�J @��H�I9�~Y1��| _H�J @��H�I9�~B1��| _H�J @��H�I9�~+1��| _H�J@��H�I9�~�|_����H�f D I9��8 H�t$1�H��踵��H9\$�� H��P[]A\A]A^À�it`��n�� H���� �Q��߀�A�� �Q��߀�N�� ��u <-t���u H��P[]A\A]A^� � ��IukH��~e�Q�y��߀�NA�����@��F��D!�H���� ���z �du <-�G����\u �:���� Wu f.��" D L���H���� 8u H��H���! H�(�@������D$� ����D$���H��'~mH�x�p���I��H��t�J�D- L��1�� I� � � �1 D M��I��D!� �D�ރ���_���H����H�H9��3 �U �JҀ�7v�1���L�D$ J�D- 1�� I� � � L���0 @ M��I��D!� �D�փ���_���H����H�H9��� �U �JҀ�7v�1���1�1��i����L$�����b����L$H������f(�����H��������q�y���@��I@�ƃ��@��N@��!��y���@��I@��!��y�I���@��T@�ǃ��!���Y��@���X������ ����K��� �� �=���H�t$1�L������A��� �� u(H�t$1�L�����L���D$走���D$����L��袰�����ff. � f�AUATUSH��L��� M��tI�$H��L��[]A\A]� � H����� u$L�%ݞ I�$H�PI�$H��I�$L��� 뻿 H�-̭ ����I��H��t�H�@H�E E1�1�1�L��H�(H�=*� �u���I�,$I���� M��tbI�EH��L��H��� H���� ��H��I�m tlH��t7H�U L��� M��tnH��H�U � ���H���!���L��� � ��� D �˱��H�-$� H�E H�PH�U �f D L������l��� L���د����1���H���v���I�����AVAUI��ATUSH��H�=B� H�GH��� H;�� u.� 1�L���G���I��H��� H��L��[]A\A]A^� L��H���< ��I��M��u��}���I��H��� I�|$XH�(H9��0 H���� H�EH��� � �S H�W��� ��� ��� @�� � ��� ��� @�� H��X H���3 H�JH��~d1�� H��H9�tWH;l�u�I�l$hf�M�t$`I�D$h AD$XH�/�� M��t I�.�� H��tH�m uH���f���f D 諰��I��H��t E1����� H��� L��H�5^ H�81��M������ � �{���I�����H��蛮����t�I�|$Xf�M�t$`I�l$hI�D$h AD$XH���I����N����ҭ���D���L���ŭ���F���L�uM���S���1�� H��I9�t6H;|�u����H��H�� H9�����H��u�H;-�� ��������1�H�t�H9��Y���H�|$�&�H�|$���B���H��I9�u�����ff. � AWAVAUI��ATA��UH��S��H��8�B���H�=�� I��H���� H�@XM�~hI�Fh f�H�$I�F`AFXH�D$�D���H��H��� H�8H�ާ H9G�� L�ŧ M���l I� H��� I9��K L;�� t L��L�D$�ʭ��L�D$��� DE�I�(�V �~$I�~XM�V`M�FhM�~hD$AFXH��t H�/�5 M��t I�*�B M��t I�(�H E���� H�54� H���� D� � A��D�׃��� �V1�A9������A9��� H�H��H�D;x�� L� I�$H�:� 1�L��L�����H��H���� �XlH��趬��I�,$uL���w���H�m H���� H��8[]A\A]A^A_�f. � H�5y� E��A��H���Q D�[� D�׃��B���Hc�H��D;|� ���(���1��f � �%����H9�������)ʉ�� ���Hc�H���TA9�}Љ��� @ I�,$�T���L��H��8[]A\A]A^A_駪��L��L��H�T$�'���H�T$��tNH�zXf�L�B`L�bhBXH�Bh H��t H�/�� M��t I�(�� M��tI�,$uL���@������ H�1� H�5Ҧ E1�H�=�� �[������f D I�FXf�H�$I�F`AFXH�D$I�FhI�Fh H�D$E��� ��L��H��蟮��I��M���� �~$I�~XH�D$M�n`D$I�nhAFXI�FhH��t H�/�� M��t I�m �� H��t H�m �� H�=�� E�������H���� �y� �r�A���� Hc�H��D;|�� ���� 1�� D �� �MA9��� D��)ȉ�� ���Hc�H���DA9�}�A����I�FXf�H�$I�F`AFXH�D$I�FhI�Fh H�D$L��D��H��^ 1�H�=�X �c���I��H���� H�����H��H���� ��H���I���I�m I�������L���c�������G1�f � A9������9��� Lc�I��I�E;z� 9O� �� Hc���H��H���oHc���H��H�� 9�|��E�zM�"�� I�$�+���I�m u L���ͧ�� D H� $H��tH�H�D$H��H��� H�\$H��tH�H�$H��H��� H�\$H������H�H��H�$H��H�����������9�� � D�j@Ic�H���D���H��H�������LcՋW� H�X� I��D�-I� I�9�� ����r����L���������L�D$L�$���L�D$L�$���L��L�$�զ��L�$���L���Ħ�����H�=X� H�5Y� H�GH��� H;�� �� � 1��M���H��H���A���H�|$�ǧ��H�|$���) L��� H�\� I� H�/�% I9�����I��E1�����I�FXf�A��H�$I�F`AFXH�D$I�FhI�Fh H�D$�+���H������n���H�����C���H������p���L���إ���S����Υ���9���H�5j� H�L$H�V�4���H�L$H��I���� H�L��� H�@H��� ����� ���H������H��g H��� H��� D�xL� I�$���Lc�I��I��K���H�:� H� I��H�/���H�D$L�D$����L�D$H�D$�r���I�:M�"I�$H�/�E������;���H�D$袦��L�D$H�L$�0���H���� ��H��H���;������H��H��� L�bXL� M9�����M���T���I�@H��� � �� I�L$��� �����A��$� @������ ������A��� @�����I��$X H��t.H�q1��L;D������H��H9�������q���H���D���M��$ M9��j���M��u�L; � �X������M�P1��M;d��@���H��I9��1�I9��z���I�t�I9�� ���L��H�T$H�L$(L�T$ L�D$�`�H�T$�������H�L$(L�T$ L�D$H���L�D$�d���L�D$���L���R������ff. � f�AWH�O� I��AVAUI��ATUSH��XH�D$ H�D$@H�D$H H���� L�QH��M���� H���� H��tvH��H�ː H��R L� �R AUA� H� �R H�5Y H�81��� �Ȧ��XZf D H� 9Y �@ ��E1�H�=XY �S���H��XL��[]A\A]A^A_ÐH�H� H�D$ H�EN�$� L�|$@O�4'��� �1 H�D$ I�1�H�D$ I�L�L�L��H��u�[ H�PH��H���G L; u�I��L)�H�H�T H��I9�u�M�� J�|� �� H�\$ H�� H9��_ I�kI�{H�E H9��U H�C��� t H;� �; H�����I��M���7 H� � H9E�C L�uL�}I�I�H�m �[ fIn�fIn�H�t$@L��fl�� )D$@��I�.I���6 I�,$�� I�/�� M��� H��A��1� � H���d���E���[���H�+� u�H���ˠ����f � H�D$8 H�� I9A�C L��H�L$8L��L��L��P L�\$L�T$L� $����L� $L�T$L�\$���� ����� H�G� L��H�<P H�5vV �� H�81��W���H�|$ H�������H�/���������u��� D I��� ���H� H�H�\$ �%���H��������L��������H��H��� H� �O H�5"V AUL� �O A� H��O H�81��� 轣��Y^�_���I��H�T$8H�L$H� H�����L���s����e���L���f����N���H�I���U���H���m���I�����H�m A�� �G H� �U �D D��E1�H�=�U �������H��L�\$L�$�`������� I�E1�L�$L��L�\$H��u6� @ H��H� I��L)�H�D H�CH��H���� M9�����H�0H��L�\$L�$臣��L�$L�\$H��u�L�\$L�$�ˠ��L�$L�\$H��t��� �,���L��H�L$8L��L��L�=N L�\$L�T$L� $����L�\$L�T$L� $���H�t$HH��L�d$HI��H� �H�D$@ �p�I������A�� ���H��������M9����H�D$( L�d$0H�\$(H�D$0 L�l$81�L��H��H��������1���I�H�|$0L��H��tf D H98t�H�BH��H��u�H�D$8 H��� H9GuKL�HM L��L��L�������t�������H�'� H�L$0H�M H�5TS H�81��:������L��L L��L��L��������A���� D AWAVAUATUH��SH��H��x��� �� 1���0 I��M���� L�5̊ H��� H�D$@ H�D$PH-0 L�{M�t$I�M�t$H�D$H H�D$XH�D$` H���� H���_���I��H���� I���3 I��� M���- H��H�� H�#L L� 6K AWA� H� L H�5gR H�81�A� ����XZH� �R �< D��H�=�R ��I�,$� E1�� � I��u�L�kH�k I�|$I�E H�E I�E H�/L�l$@H�l$H�? M�l$H�EH�E L9�t H;ȉ �� I�|$H�/�) I�l$1�I�m �u H�m �] ����[���H��xL��[]A\A]A^A_�H�C H� H�D$HH�CH� H�D$@H�EL�L$PO�,���� �5 H�D$@1�H�D$ I�U L�T�L��H��u � f. � H�PH��H��tsL;u�H�� L)�H�H�T@H��I9�u�I��"J�|�@ � I��I��t J�|�@ �� L�l$@I�|$H�l$HI�E H�/������F�������H�D$8 H��� I9B�/ L��L��H�L$8L��L�J L�\$L�L$L�$�N��L�$L�L$L�\$���� ����� H�LJ L��H��I H�5�O A�� H�81��֝��H�|$@H���� H�/H�l$H�� H�������H�m �����H���}������H��H�]� H� ]I H�5�O AWL� oH A� H�HI H�81�A�� �Y���Y^�|����-�������H�� H�T$8H�L$H� H���o��������f���H�(� H�5�� 1��8 I��� ���H���٘�����L���̘���~���L��还�����H��L�L$L� $� ������� I�E 1�L� $L��L�L$H��u6�� D H��H� H��L)�H�D@H��H�I9�����H���� H�0H��L�L$L�\$H� $�+���H� $L�\$H��L�L$u�L�L$L�\$H� $�e���H� $L�\$H��L�L$t�A�� �A���L��L��H�L$8L��L��G L�\$L�L$L�$�_��L�\$L�L$L�$����I9��"���H�D$( L�t$0H�\$(H�D$0 L�|$81�L��H��H��L� $�Κ�����t���I�E H�|$0L��L� $H��t�H;8t�H�BH��H��u�H�D$8 H��� H9GuWL��L�-G L��L��L� $�o��L� $�������������H�� H�L$0H��F H�5 M H�81���������L��L��F L��L��L� $�X��L� $���)����H�l$H����H�HH��� H�'G H�5�F H�81�謚��H�m t%H� M �> �; ��H�=�M �5�� ���H���X�����f D AWH��� AVAUI��ATUSH��XH�D$ H�D$@H�D$H H���� L�qH��M���� H���� H��tyH��H�ރ H�F L� �E AUA� H� �E H�5*L H�81��� �ۙ��XZf � H� �E � ��H�=�M �f�H��X1�[]A\A]A^A_� D H�H� H�D$ H�EN�$� L�T$@O�<"��� �� H�D$ I�1�H�D$ I�L�\�L��H��u� H�PH��H���� L;u�I��L)�H�H�T H��I9�u�M�� J�|� �O H�\$ L�%� H�-� I�|$H��� H�� @H;- �i H���J H���J H��� H�5�K H�8�(��� � H� �D � �� H�=�L �3�H��A��1�f. � H�������E�������H�+� u�H���+�����f � H�D$8 H�h� I9C�� L��L��H�L$8L��L�D L�T$L�\$�2��L�\$L�T$���� ����� H��� L��H��C H�5�I �� H�81�迗��H�|$ H�����H�/����肓������ D I���u���H� H�H�\$ �}���� ��: A��$� @�+ H��� L�mI��� � @t'M9��$ L��L��������, H�EH��� � � H�E 1�H��L���Ԗ��H�m I���� M���M���I�M��� @�� L��L�����I�m �&���L��螒������H��H�~� H� ~B H�5�H AUL� eB A� H��B H�81��� �{���Y^���L���|�������H��u� �t#A��$� @t1�����H��H��������'���H�� H�5�I H�8袒���}���I��H�T$8H�L$H� H�����H�� 1��s���H���H��L�T$�!�����txI�E1�L�T$L��H��u7�� D H��H� I��L)�H�D H�CH��H���� M9��z���H�0H��L�T$�S���L�T$H��u�L�T$蟓��L�T$H��t��� ���L��L��H�L$8L��L�GA L�T$L�\$���L�T$L�\$�0���H��� ����%���H��L��� ����k���M9����H�D$( L�d$0H�\$(H�D$0 L�l$81�L��H��H��L�T$������_���I�H�|$0L��L�T$H��t � H;8t�H�BH��H��u�H�D$8 H��~ H9G�� L��L�s@ L��L��L�T$���L�T$���s��������H�~ H�L$0H�:@ H�5BF H�81��(������ H��} L��H�5�G H�81������/�������W���H��L������G���L��L��? L��L��L�T$�=��L�T$�������f���f. � AUATUH�� H���� H��H���� L�%�� H�-�� I�|$H��� H�� @H;-`} �� H���� � ��> A��$� @�/ H��� L�mI��� � @t'M9��� L��L��������( H�EH��� � �� H�E 1�H��L��谒��H�m I���� M��tZI�M��� @�� L��L�����I�m u7L��肎���-H��t H�d| H�5�E H�8����� H��t;L��胎��H� �> � �Z H�=�F ��H�� 1�]A\A]�f. � � �t)A��$� @t 1����H��H��t��-���f. � H��{ H�5�E H�8�z���� � H��H��{ E1�L� �< RH� �= H��= H�8H�5D 1�軑��XZ1�H�� ]A\A]� D H�y �G�������H�D$ H�A��� �� H�@h1��PH�D$H��H��� ���H�,{ H�y= H�5^C H�81��D���H�|$H�/������������ H��L���-������ � H�� 1�聑��H������f � H���Ȍ������ ����d���H��L���܌���T��� � H��z L��H�5'D H�81�襐�����H�D$ H�L$�͌�����/���H�|$1�H�T$H�t$蟏��H�L$H�����AWH�O� AVAUI��ATUSH��XH�D$ H�D$@H�D$H H��� L�qH��M���� H���� H��tyH��H��y H�-< L� �; AUA� H� �; H�5B H�81��J �ˏ��XZf � H� 9B �1 ��E1�H�=HD �S��H��XL��[]A\A]A^A_ÐH�H� H�D$ H�EN�$� L�T$@O�<"��� �@ H�D$ I�1�H�D$ I�L�\�L��H��u�k H�PH��H���W L;u�I��L)�H�H�T H��I9�u�M���{ J�l� H��� H�E f D H��H;-�x H�E �� H�=<� H��� H9G�c L�%� M���� I�$I�D$H�5b� L��H��� H���� ��I��I�$H��I�$M���� H���l H��w I9E�t H�t$HL��H�l$HM��H� �H�D$@ �{��I��I�.� �� M���� H�m � I�$M��H�PI�$I�$H���k H�m �;���H��趉���.����H�D$8 H��w I9C�+ L��L��H�L$8L��L��9 L�T$L�\$����L�\$L�T$���� ����� H�?w L��H��9 H�5n? �< H�81��O���H�|$ H�������H�/�w��������m��� D I������H�.H�E H�l$ H��H�E � ���L���݈������L���Ј�����H���È������H��H��v H� �8 H�5? AUL� �8 A� H��8 H�81��> 蠌��Y^�J���I��H�T$8H�L$H� H���l���L���V�������� H��t3H� �> �3 I��E1�H�=�@ ���H�E H���F���I���/���L��t$�����t$�H��L�T$�U�����t|I�E1�L�T$L��H��u;� f � H��H� I��L)�H�D H�CH��H���U M9������H�0H��L�T$背��L�T$H��u�L�T$�ω��L�T$H��t��< �<���L��L��H�L$8L��L��7 L�T$L�\$����L�T$L�\$����L�-� I�UL��襉��I��H��� L�%d� H�@H�a� M���u���軈��L���3��I��M���a����� ����8���I���n���H�=�� ���I����M�}M�uI�I�I�m �4 fHn�fIn�H�t$@L��fl�� )D$@����I�/I���j���L���j����]���H�l$ H�E ���M9��e���H�D$( L�d$0H�\$(H�D$0 L�l$81�L��H��H��L�T$�h����������I�H�|$0L��L�T$H��t H98t�H�BH��H��u�H�D$8 H�.t H9GumL��L� 6 L��L��L�T$���L�T$���{������+���H��s H�L$0H��5 H�5�; H�81�蜉������ � L���h������L��L��5 L��L��L�T$����L�T$�������f � AWH�?� AVAUI��ATUSH��XH�D$ H�D$@H�D$H H��� L�qH��M���� H���� H��tyH��H��r H�)5 L� �4 AUA� H� �4 H�5 ; H�81��� 軈��XZf � H� ); �+ ��E1�H�=h= �C��H��XL��[]A\A]A^A_ÐH�H� H�D$ H�EN�$� L�T$@O�<"��� �@ H�D$ I�1�H�D$ I�L�\�L��H��u�k H�PH��H���W L;u�I��L)�H�H�T H��I9�u�M���{ J�l� H��� H�E f D H��H;-�q H�E �� H�=, H��~ H9G�c L�%�~ M���� I�$I�D$H�5R� L��H��� H���� ��I��I�$H��I�$M���� H���l H��p I9E�t H�t$HL��H�l$HM��H� �H�D$@ �k��I��I�.� �� M���� H�m � I�$M��H�PI�$I�$H���k H�m �;���H��覂���.����H�D$8 H��p I9C�+ L��L��H�L$8L��L��2 L�T$L�\$���L�\$L�T$���� ����� H�/p L��H��2 H�5^8 �v H�81��?���H�|$ H�������H�/�w��������m��� D I������H�.H�E H�l$ H��H�E � ���L���́������L��������H��賁������H��H��o H� �1 H�5�7 AUL� z1 A� H��1 H�81��x 萅��Y^�J���I��H�T$8H�L$H� H���l���L���F�������� H��t3H� �7 �- I��E1�H�=: ����H�E H���F���I���/���L��t$����t$�H��L�T$�E�����t|I�E1�L�T$L��H��u;� f � H��H� I��L)�H�D H�CH��H���U M9������H�0H��L�T$�s���L�T$H��u�L�T$迂��L�T$H��t��v �<���L��L��H�L$8L��L��0 L�T$L�\$�ǻ��L�T$L�\$����L�-~ I�UL��蕂��I��H��{ L�%D{ H�@H�A{ M���u���諁��L���#��I��M���a����� ����(���I���n���H�=�} ����I����M�}M�uI�I�I�m �4 fHn�fIn�H�t$@L��fl�� )D$@����I�/I���j���L���Z���]���H�l$ H�E ���M9��e���H�D$( L�d$0H�\$(H�D$0 L�l$81�L��H��H��L�T$�X����������I�H�|$0L��L�T$H��t H98t�H�BH��H��u�H�D$8 H� m H9GumL��L�/ L��L��L�T$���L�T$���{������+���H�yl H�L$0H��. H�5�4 H�81�茂������ � L���X~�����L��L��. L��L��L�T$�ɹ��L�T$�������f � AWH�/| AVAUI��ATUSH��XH�D$ H�D$@H�D$H H��� L�qH��M���� H���� H��tyH��H��k H�%. L� �- AUA� H� �- H�5�3 H�81��� 諁��XZf � H� 4 �& ��E1�H�=�6 �3��H��XL��[]A\A]A^A_ÐH�H� H�D$ H�EN�$� L�T$@O�<"��� �@ H�D$ I�1�H�D$ I�L�\�L��H��u�k H�PH��H���W L;u�I��L)�H�H�T H��I9�u�M���{ J�l� H��� H�E f D H��H;-�j H�E �� H�= x H��w H9G�c L�%�w M���� I�$I�D$H�5By L��H��� H���� ��I��I�$H��I�$M���� H���l H��i I9E�t H�t$HL��H�l$HM��H� �H�D$@ �[���I��I�.� � M���� H�m � I�$M��H�PI�$I�$H���k H�m �;���H���{���.����H�D$8 H��i I9C�+ L��L��H�L$8L��L��+ L�T$L�\$袹��L�\$L�T$���� ����� H� i L��H��+ H�5N1 �� H�81��/��H�|$ H�������H�/�w�����z���m��� D I������H�.H�E H�l$ H��H�E � ���L���z������L���z�����H���z������H��H��h H� �* H�5�0 AUL� j* A� H��* H�81��� �~��Y^�J���I��H�T$8H�L$H� H���l���L���6z������� H��t3H� �0 �( I��E1�H�=.3 ����H�E H���F���I���/���L��t$��y���t$�H��L�T$�5z����t|I�E1�L�T$L��H��u;� f � H��H� I��L)�H�D H�CH��H���U M9������H�0H��L�T$�c~��L�T$H��u�L�T$�{��L�T$H��t��� �<���L��L��H�L$8L��L��) L�T$L�\$跴��L�T$L�\$����L�-�u I�UL���{��I��H��t L�%$t H�@H�!t M���u����z��L�����I��M���a����� ����}��I���n���H�=qu ����I����M�}M�uI�I�I�m �4 fHn�fIn�H�t$@L��fl�� )D$@�Ϻ��I�/I���j���L���Jx���]���H�l$ H�E ���M9��e���H�D$( L�d$0H�\$(H�D$0 L�l$81�L��H��H��L�T$�H{���������I�H�|$0L��L�T$H��t H98t�H�BH��H��u�H�D$8 H�f H9GumL��L�( L��L��L�T$���L�T$���{������+���H�ie H�L$0H��' H�5�- H�81��|{������ � L���Hw�����L��L��' L��L��L�T$蹲��L�T$�������f � AWH� u AVAUI��ATUSH��xH�D$ H�D$@H�D$H H���� L�IH��M���� H���� H��tyH��H��d H�%' L� �& AUA� H� �& H�5�, H�81��2 �z��XZf � H� - � ��E1�H�=�/ �#��H��xL��[]A\A]A^A_ÐH�H� H�D$ H�EN�$� L�t$@O�<&��� �� H�D$ I�1�H�D$ I�L�\�L��H��u�K H�PH��H���7 L;u�I��L)�H�H�T H��I9�u�M�� J�|� �� H�\$ H; �c �� H�CH;@c �� H;�c �� H;�c � H;1c �1 H; c �� H�SH���� H�5c H���ҽ��� 27 f.�zu�mw��H��u�7 �kv��I��M��u*H� �+ � �\ E1�H�=@. �����H�I��H��A��1�H���t���E���k���H�+� u�H���t����f � H�D$8 H��b I9C�� L��H�L$8L��L��L��$ L�L$L�\$貲��L�\$L�L$���� ����� H�/b L��H��$ H�5^* �$ H�81��?x��H�|$ H�������H�/������t����� D I���5���H� H�H�\$ �=���H��H��a H� �# H�5$* AUL� �# A� H�,$ H�81��& �w��Y^�y���I��H�T$8H�L$H� H�����H�CH�PH���: f�H���N����SH���� f��*��4���H�s(����H��L�L$�s����tuI�E1�L�L$L��H��u4� f�H��H� I��L)�H�D H�CH��H���� M9��*���H�0H��L�L$��w��L�L$H��u�L�L$�u��L�L$H��t��$ ���L��H�L$8L��L��L�# L�L$L�\$����L�L$L�\$� ���H���Pr��I���`����C ��� �@�\ H�t$@H���Gv��H�T$@H��H������ 74 � ���H�SH�s H��躺��� 4 ���M9��K���H�D$( L�d$0H�\$(H�D$0 L�l$81�L��H��H���#u��������I�H�|$0L��H��t H98t�H�BH��H��u�H�D$8 H��_ H9GutL�" L��L��L���˯����t��������H�W_ H�L$0H��! H�5�' H�81��ju����� D ��f��*��!���H���9t��� )3 ��L��! L��L��L��藬��������� @ A��L�{L�cHA��E��A��� uL�cH1�A���� A��u �} D�D$�s��D�D$��tH��A�<���w�H�\^ �<8 u�I�W�H9�|;� � H�T$D�D$��r��D�D$H�T$���� H��H9��� A�<�L�jI�׃�w�H��] �<8 u�� H��] ���<8 t!H��A�<,@��y�D�D$�ir��D�D$��u�I�W�H9�| � f�H��] ���<8 t7H��H9�}1A�<L�jI��@��y�H�T$D�D$�r��D�D$H�T$��u�M��L��H)�H���L A���� A���� A�4�1�H�FՃ���H�D H)�A� ���N�� �� ��9� ��/w ��.�� H��'�� L9��� A���1 L�t$@� M��A���� A����.A�U @�ƃ�_��1� �_��@����I����� ���� H��I9�}����v A�E H�t$81�L���>p��� �0 L9l$8�q���f.��M �G �L$��p���L$H���- f(��>��� � ��D�D$�p��D�D$��t H��A�lf��w�H��[ �< u�I�W�H9�6� ��H�T$D�D$�np��D�D$H�T$���R���H��H9��H���A�TL�jI��f��w�H� �[ �< u��!��� ��i�� ��n�j H���` H�PA���F A���" A����߃�AA�D�����߃�N�* ���" ��-�� �u/ � ]/ �&���H���(l������ ����C ������I�� H���� H�PA���c A���? A� �A�T���߃�N����߃�F��!�H��u"��t ��-�� ��. � �. ���H��utH�HA���p A��� H�<� A� �A�D<��߃�N����߃�I��!�A�L<��߃�I��!�A�L< ��߃�T��!�!�A�D<��߃�Yu���h���� L. H���L$�Fq���L$H��H�������H�(�@����L$�D$�l���D$�L$����L��H)�H��~�A�4,1�H���+����H�D H)�A� �\���A�4l1�H���+f�����H�)H)�A� D�5�����- � �- �\���L��H)�H������&���A�T���f��AA�DT������A�TA�D��߀�A�����A�lf��.A�U @��f��_��1� �f��_��@����I�f��������������H��I9�}��(���L�t$@M��A�,��_A�U ����.��1� Ȁ�_D��@��D��I����l���D���c���H��I9�}�����H�zD�D$�o��D�D$H��H���6���L9�� I��A���� � A���p A����.A�U @�ƃ�_��E1� �_��A����MŃ��� ���� H��I9�}����� A�E H�t$81�H�|$�k��H�|$�D$�\i���D$�3�����+ � �+ ��A� TA�TT���f��N�����A�T��߀�NA�T�����H�< A� LA�D<���f��N�����f��I��!�A�L<���f��I��!�A�L<���f��T��!�!�A�D<���A�LA�|��߀�N�����@��I@��!�A�|���@��I@��!�A�|A�D���@��T@��!�!����A�lf��.A�U @��f��_��E1� �f��_��A����M�f��wS��uOH��I9�}����A�,��_A�U ����.��1� Ȁ�_D��@��D��I���xA��uH��I9�}��M�����g��� b* ���� D AWH�_f AVAUI��ATUSH��XH�D$ H�D$@H�D$H H���@ L�qH��M���0 H���� H��tyH��H��U H�n L� � AUA� H� � H�5* H�81��� ��k��XZf � H� I � ��E1�H�= ! �c���H��XL��[]A\A]A^A_ÐH�H� H�D$ H�EN�$� L�T$@O�<"��� � H�D$ I�1�H�D$ I�L�\�L��H��u� H�PH��H���� L;u�I��L)�H�H�T H��I9�u�M�� J�|� �? H�\$ H; �T �! f D H���g��I��H���3 H��A��1� H������E��� ���H�+� u�H���f����f � H�D$8 H��T I9C�� L��L��H�L$8L��L�� L�T$L�\$蒤��L�\$L�T$���� ����` H�T L��H�� H�5> �� H�81�� j��H�|$ H���A���H�/�7�����e���-��� D I������H� H�H; �S H�\$ ���H�I�����H��H��S H� � H�5� AUL� u A� H� H�81��� �i��Y^�e���I��H�T$8H�L$H� H���G���H��L�T$�e����trI�E1�L�T$L��H��u1�� H��H� I��L)�H�D H��H�M9�����H���� H�0H��L�T$��i��L�T$H��u�L�T$� g��L�T$H��t��� ���L��L��H�L$8L��L�. L�T$L�\$�(���L�T$L�\$�Q���H� " � �� H�=� �<������M9��e���H�D$( L�d$0H�\$(H�D$0 L�l$81�L��H��H��L�T$�xg�����Z���I�H�|$0L��L�T$H��t H;8t�H�BH��H��u�H�D$8 H�>R H9GuYL��L�] L��L��L�T$����L�T$���{��������H��Q H�L$0H�$ H�5� H�81��g�����L��L� L��L��L�T$���L�T$���"����ff. � f�AWH�_a AVAUI��ATUSH��XH�D$ H�D$@H�D$H H���` L�qH��M���P H���� H��tyH��H��P H�u L� � AUA� H� � H�5* H�81��� ��f��XZf � H� I � ��E1�H�=P �c���H��XL��[]A\A]A^A_ÐH�H� H�D$ H�EN�$� L�T$@O�<"��� �c H�D$ I�1�H�D$ I�L�\�L��H��u�� H�PH��H���� L;u�I��L)�H�H�T H��I9�u�M�� J�|� �� H�\$ H; �O �� H�-�O L�-�O H9���L9�t���" ����� I�E H��A��1�f � H����E�����H�+� u�H���ka����f � H�D$8 H��O I9C�� L��L��H�L$8L��L�� L�T$L�\$�r���L�\$L�T$���� ����� H��N L��H�� H�5 �� H�81��d��H�|$ H���!���H�/������`��� ��� D I�������H� H�H�\$ ���H�E I�����H���Xc��������H� � �9 E1�H�= �0������H��H�@N H� @ H�5� AUL� ' A� H�� H�81��� �=d��Y^�7���I��H�T$8H�L$H� H�����H�I���M���H��L�T$�B`����ttI�E1�L�T$L��H��u3� f D H��H� I��L)�H�D H��H�M9������H��tkH�0H��L�T$�xd��L�T$H��u�L�T$��a��L�T$H��t��� ���L��L��H�L$8L��L�� L�T$L�\$�̚��L�T$L�\$����M9��+���H�D$( L�d$0H�\$(H�D$0 L�l$81�L��H��H��L�T$�>b����t�I�H�|$0L��L�T$H��t D H;8t�H�BH��H��u�H�D$8 H�M H9GuUL��L�, L��L��L�T$�ޜ��L�T$��t�������H�eL H�L$0H�� H�5� H�81��xb�����L��L�� L��L��L�T$�ə��L�T$���(���� H��H��� takes no arguments %.200s() %s (%zd given) takes exactly one argument Bad call flags for CyFunction takes no keyword arguments %.200s() %s <cyfunction %U at %p> cannot import name %S __loader__ loader __file__ origin __package__ parent __path__ submodule_search_locations needs an argument keywords must be strings name '%U' is not defined %s (%s:%d) process exactly __cinit__ Expected %s, got %.200s __setstate_cython__ <stringsource> __reduce_cython__ str_to_date str_to_time str_to_datetime to_float to_str int_to_boolean builtins cython_runtime __builtins__ does not match _cython_3_1_0amsendbackport type __reduce__ __module__ __dictoffset__ __vectorcalloffset__ __weaklistoffset__ func_doc __doc__ func_name __name__ __qualname__ func_dict __dict__ func_globals __globals__ func_closure __closure__ func_code __code__ func_defaults __defaults__ __kwdefaults__ __annotations__ _is_coroutine processors Interpreter change detected - this module can only be loaded into one interpreter per process. Shared Cython type %.200s is not a type object Shared Cython type %.200s has the wrong size, try recompiling unbound method %.200S() needs an argument __annotations__ must be set to a dict object __kwdefaults__ must be set to a dict object changes to cyfunction.__kwdefaults__ will not currently affect the values used in function calls __defaults__ must be set to a tuple object changes to cyfunction.__defaults__ will not currently affect the values used in function calls function's dictionary may not be deleted setting function's dictionary to a non-dict __qualname__ must be set to a string object __name__ must be set to a string object %.200s() keywords must be strings %s() got multiple values for keyword argument '%U' while calling a Python object NULL result without error in PyObject_Call '%.200s' object has no attribute '%U' lib/sqlalchemy/cyextension/processors.c %s() got an unexpected keyword argument '%U' %.200s() takes %.8s %zd positional argument%.1s (%zd given) lib/sqlalchemy/cyextension/processors.pyx sqlalchemy.cyextension.processors.DecimalResultProcessor.process sqlalchemy.cyextension.processors.DecimalResultProcessor.__cinit__ instance exception may not have a separate value calling %R should have returned an instance of BaseException, not %R raise: exception class must be a subclass of BaseException sqlalchemy.cyextension.processors.DecimalResultProcessor.__setstate_cython__ sqlalchemy.cyextension.processors.DecimalResultProcessor.__reduce_cython__ sqlalchemy.cyextension.processors.str_to_date sqlalchemy.cyextension.processors.str_to_time sqlalchemy.cyextension.processors.str_to_datetime sqlalchemy.cyextension.processors.to_float sqlalchemy.cyextension.processors.to_str sqlalchemy.cyextension.processors.int_to_boolean Module 'processors' has already been imported. Re-initialisation is not supported. sqlalchemy.cyextension.processors compile time Python version %d.%d of module '%.100s' %s runtime version %d.%d base class '%.200s' is not a heap type extension type '%.200s' has no __dict__ slot, but base type '%.200s' has: either add 'cdef dict __dict__' to the extension type or add '__slots__ = [...]' to the base type Unable to initialize pickling for %.200s %.200s.%.200s is not a type object %.200s.%.200s size changed, may indicate binary incompatibility. Expected %zd from C header, got %zd from PyObject %s.%s size changed, may indicate binary incompatibility. Expected %zd from C header, got %zd from PyObject init sqlalchemy.cyextension.processors _cython_3_1_0amsendbackport.cython_function_or_method sqlalchemy.cyextension.processors.DecimalResultProcessor sqlalchemy.cyextension.processors no default __reduce__ due to non-trivial __cinit__ lib/sqlalchemy/cyextension/processors.pyx DecimalResultProcessor.__setstate_cython__ DecimalResultProcessor.__reduce_cython__ DecimalResultProcessor.process DecimalResultProcessor ' - value is not a string. cline_in_traceback asyncio.coroutines str_to_datetime __setstate_cython__ int_to_boolean Couldn't parse __reduce_cython__ fromisoformat <stringsource> _is_coroutine _initializing datetime_cls str_to_time str_to_date ValueError __reduce_ex__ __pyx_state isenabled TypeError to_float time_cls __setstate__ __set_name__ __qualname__ __getstate__ datetime date_cls process disable to_str string ' __reduce__ __module__ format_ enable value type_ time __test__ __spec__ self __name__ __main__ __func__ date None pop re gc ? . � � � �� � @ ________________;$ C `<��@ �B�� MC��p @D��� �D��4 F��� aF��4 iG��� �G��� H��� �I�� �K��� L��� M��� h��8 �h��h i��| i��� i��� 0i��� Pi��� �i��� �i��� pk��@ �k��T �k��h �k��� 0l��� Pl��� �l��� �m��@ �m��X n��� �p��� �p��p �q��� �r��� v��` �v��| 0w��� �w��� `x��� �x�� @y��@ pz��� �z��� |��� P~��H �~��` P��x ���� ����\ ���� P���@ ����� �� ���� p���� ����� `���d ���� p���$ ����� ���� ���t `��� `��T zR x � $ :��p FJ w� ?;*3$" D pf�� X |f�� l xf�� � tf�� � pf�� � |f��@ \ c � �f��5 T ` @ � �f��� A�G�G0k GAF d DAG Z CAJ (h�� 0 4h�� D @h��/ Q�] ` Th��E Q�c D L � �h�� ( � �h��� B�A�D U DBF � �h��� A�O P O 4 � �>��} B�E�E �A(�D0a(D BBB Hi��A dN 4 �i��; lN D L �>��� B�E�B �B(�A0�D8�A@�8D0A(B BBB � `i��j A�� C H H � �k��) A�c 8 � @?��~ B�E�H �A(�A0�b(D BBB 8 �?��a B�B�E �A(�A0K(D BBB 4 L Hk��� B�D�D �� GBG AAB � l��� Dq K K E � K@��B A@x � �l��� B�B�E �B(�D0�D8�D�c 8G0A(B BBBF R 8D0A(B BBBA Q 8I0A(B BBBM < �o��} DE G ( X p��� A�D�D U AAH ( � �p��� A�D�D U AAH � �p��� Do E o I � dq��h Do E o � �q��h Do E o l %?�� B�B�B �E(�D0�G8�X`�hApBxA�A�A�B�A�A�B�L`T8D0A(B BBB � �?��G D`B4 � �?��S B�E�E �D(�A0w(D BBB H � @��� B�E�E �E(�A0�D8�GPe8D0A(B BBB x �p��' B�B�B �E(�A0�A8�D@_ 8A0A(B BBBF _ 8A0A(B BBBG _ 8F0A(B BBBB � �q�� � �q��z ` � s��G B�B�B �B(�D0�D8�G`� 8A0A(B BBBG � 8C0A(B BBBH $ u��e |h < Xu��� dh T �u��� Do E C E p x |v��o B�K�F �D(�D0F (I DBBF u (I DBBJ � (D ABBE �(I ABB H � {?��. B�B�B �B(�D0�A8�G` 8D0A(B BBB ( 8 ,y��� B�A�D U DBF @ d �y��! b�B�B �A(�A0�D@S 0D(A BBBF $ � �@��W B�D�A LABH � A��� B�E�B �A(�A0� (D DBBE F(D BBB X {��3 B�E�B �D(�D0�D�2 0A(A BBBA P 0A(A BBBH 8 x ��_ B�B�A �A(�D0U (D ABBH @ � ���� B�B�E �A(�A0�D@z 0D(A BBBD d � \���� B�B�B �E(�D0�D8�Fp� 8A0A(B BBBK � 8A0A(B BBBE l ` ��K B�L�B �E(�A0�A8�D�C�W�d�A�g 8D0A(B BBBB ��W�d�A� l � ē��� B�B�B �B(�A0�D8�G���W�e�A�� 8D0A(B BBBA ��W�e�A� l @ �� B�I�B �E(�A0�A8�D�C�W�d�A�g 8C0A(B BBBF ��W�d�A� L � D���O B�B�A �D@U CBBK THRP`HA@F ABBF l D��� B�I�B �E(�A0�A8�D�C�W�d�A�j 8D0A(B BBBB ��W�d�A� l p �� B�I�B �E(�A0�A8�D�C�W�d�A�j 8D0A(B BBBB ��W�d�A� l � ���� B�I�B �E(�A0�A8�D�C�W�d�A�j 8D0A(B BBBB ��W�d�A� l P $���� B�I�B �E(�A0�A8�D�C�W�d�A�j 8D0A(B BBBB g�W�d�A� l � t��� B�I�B �E(�A0�A8�D�C�W�d�A�j 8D0A(B BBBB ��W�d�A� l 0 ��' B�I�B �E(�A0�A8�D�C�W�d�A�j 8D0A(B BBBB )�W�d�A� p � H<��� B�B�B �B(�A0�A8�G�[�b�H�H�K� �P�h�A�� 8A0A(B BBB �V�� �l Pl `) _ 0 p ` ) ` � + ` P ` N ` � ` ] � ` � ` I ` � ` x ` � ` � � � ` X ` @ ` Z h ` � ` ` x ` � �� * 0 ` � ` ` `� 3 S ` � ` � ` X ` W ` � ` @ ` � ` ` H ` 8 ` ` ` � " ` � ` � ` � ` � h ` � ` ( ` ` � ` � ` � ` � p � @ H� P) X) ���o ` � � � 0 � p+ � � ���o � ���o �o � ���o � @- 6@ F@ V@ f@ v@ �@ �@ �@ �@ �@ �@ �@ �@ A A &A 6A FA VA fA vA �A �A �A �A �A �A �A �A B B &B 6B FB VB fB vB �B �B �B �B �B �B �B �B C C &C 6C FC VC fC vC �C �C �C �C �C �C �C �C D D &D 6D FD VD fD vD �D �D �D �D �D �D �D �D E E &E 6E FE VE fE vE �E �E �E �E �E �E �E �E F F &F 6F FF VF fF vF �F �������� p� � L �3 4 Pt B �o 2 Pv G �t 3 �q @ @4 H �4 I `5 6 Po b� 0~ m� x� @ �� 0 �� ( �� �o Pq �� �o Pq �� po �| �� po �| �� �l | �� Pm �{ �� Pm �{ �� �l � �l � �l � �l %� �l /� �l 8� p �z F� p �z S� P� Pz b� m �y r� P� �� �< �8 ~H �P �� �p D �l �q �: �� _� 0� � �� � � �� � � �� � � �� � � _� 0� � �� 0� � �� @� � �� P� � �� `� � �� � � �� � � GCC: (GNU) 10.2.1 20210130 (Red Hat 10.2.1-11) �l �v �F } G � H ~ ~H a �I B !J )K G pK S �K � SM . �O W �O � �P � �k �� h 3 e � � �5 6i< !5 6 !A 6K% !M 6n< !Y 6 6G iint !s 6�A j� � � 6% !� } (� k� � � � 5 l� N # Y N�" Y N� � N � � 5 � ! � O� � f� =�' As 6�A �, �s � � � w 5 ' 6d< � m� � 0A l 1 M �, 3Y � 75 �@ i/ !� � r� 6�+ 6�- 8�? 8 �G : s j) ; s � n � B * ! X� � �� � �; �" � �G �� � � � ( A � 0 a, �� 8 . �3 @ � �e H � �� P #@ �� X . �� ` �# �� h � �� p R4 �� x $ �� � � �� � F( �Y � �8 �� � $ �� � �C �5 � �/ � � �6 �� � # � � � � �� � [. �� � �: �� � : � � �( �� � �6 �E � �9 �� �>�; �� >� �h >: � >�F � 52 � 5$ $ (5%& [ 05� 0 85� � @5 � H5( h P51) h X5@@ h `5i8 h h5}0 h p5K" x55 Y �5x �5�4 ) � 8� i � k� L l � m� ! 1s ; � t Q u� L v ,+ �S Y -h h h !h � � � -h � h h � �� � -h � h h h {, �� � -s � h l �� � -� h � � -h , h � �4 �8 > -s W h � h C �c i -s � h h h �G �� � -s � h h r �� � -s � h � , �� � -s � h � � 9 � R � �! �" ( R3 h �1 �? E -h Y h � �/ � �q w -s � h � h �c � �S �1 �� � -� � h �� � -h � h h s � �S F �S � �� � �c � �c V1 �< B -h [ h h r( �g m -h � � 1� � � � s � � � �� 1 � � � � � � s � � s � �Y � �� � y �� 0� � S�A 8�0 P 8� Bbuf 9 � Bobj :h Blen ;� � <� s/ > s �4 ? s $ f @ � ( 4 A� 0 |; B� 8 V& C� @ �> D � H � �F E' �5 G� � -s h s � �< H R) h v J5 ; -h Y h Y ) h n o o B � ts 'D us %9 vs ? ws �G xs 6 y� ( * zG 0 �A {G 8 �= |G @ � } � H �, ~G P � s X �; �s ` � �s h # �s p + �s x AF �G � � � � � �+ �G � � �s � �G �s � �< �s � �< �s � �8 �� � � �s � �@ �s � G$ �s � F8 �s � g? �s � � �s � Z9 �s � �: �s �>F! �s >� �G >� �s >iG �s R �_ 1P � � !: � � - �s � � k � � � � � �, ( 7 � � 0 , �� 8 �s @ 7 � H �' �N 1 � 7 � � � �s * �W B �� 1 � T �6 �G #8 �G � �G 0. �# 1 � � O �� ?< � � �` T B � � 8l #� 9- $ �. %. &s �, ( � 8 (E � O s o, � � s Bdoc � 8 ( � � Bget � Bset Bdoc �- � K * Y� 0g+ 18 � ; � � � � " � ( HF � 0 d � � Z 0\ 0o; 1( b � ; �4 � 1 � 1 �6 f� !n �6 g� > h� 0� o 1�� JD �Y J�< �Y Ja& �Y J� �Y J%7 �Y 10U H � � �� U4 �� � �� � �H ( ; (< �� 1H� � � �N �� 0 � � � 8 �3 �� @ � �Z p�� qany �� Ti9 �� T8) �� T=) �� � n 1P� � � � i0 �� H %" �� [C Y 9L C] C� CY C�. H W Z !L S= .!W u 8 U� � V; D W � 0�9 D -� �D .O � � 5 00 u 0� 1u 1 � �? � & � 0� 1 I � ; � I h Y 5 � % 1( � � ; � � �C � h !� '> e 0s � � 10 � � F � + � ( � � � 0xC �! @+ � � R X -h v h Y � h � � � -h � h Y ) h l * � 18 � �; 5' h R h �! h ( �4 ) 0 � �E � 1@ E �" ! �D " 8 x+ #! 8� ( ,� � - � .� { /� �( 0 h rh � � 1Q 8(! =� � > s � ? � (! @� 8@ h Ka S9 L� � M ( � N 0 �? O� 8 �? P @ e= Q a H � R� P �' S � X � T � ` � @ U� 10! � � ! �> !h 4' !h �! !h �4 !) ( � !s 0� ! � -h � h � |= " � 8|= �#O � # s # s D# # s � # s p # s r # s ? # s $ ' # s ( #h 0 �; # h 8 �8 # h @ �/ # h H � # h P �G # h X � #&� ` [ #'h h � #(h p 'F #)h x \ #+ � � � #,h � �D #0 � � ] #<` � % #=f � 9 #> s � 0 #?A � � #[ Y� A O �. $ x XM5 p%r � %; �6 %�+ �* %�+ AB %h ( < %h 0 �9 %h 8 %� @ � % � H " % h P �; % � X � % � Y %"h ` m %$ s h �, %* s l ^? %+ s p � %, � t �% %-�+ x>� %.I h 0 & l '� s_ts (1L UG (4� � (5� + (6� N5 (9~ {< (: s J (; � $ (= � % �A (? s ( M (D s , I (E s 0 �# (G] 8 55 (H] @ QA (Ih H |( (Jh P �3 (Mh X � (Nh ` - (Oh h � (T� p 6< (X� � &$ (Zh � � (\ s � T (^h � &= (_5 � ' (a s � �> (bh � ({ � _0 (| � � e> (~ s � �% (�h � P< (�h � 6, (�h � � (�� �tid (�� H 'X u_is F (i o -s � h ~ s h 8� ("� �3 ()h � ()h 0 ()&h w6 (+ � � o! (-� � L � � A � p6 -s 0 h h � K 0+@ )Sh 0�) )Xh 0� )Zh 0. )`h 0H )bh 0�+ )kh 0C )mh 0�+ )sh 0� )�h 6�- � )h �? � + s � , s D4 - % . 5 ! e 2 6� � \�- �n $� � $' � h $] � h K(� � $O �h $� �� $�" �. $� �h $ 9 � s =F �n [> Y \� C^1 C�5 C=> K�� � $�" �E $!$ �h @$A5 �h H$ + �h P$ G �h X$� �h `$�, �h h$�- �h p$ �h x$� � s �$m= �h �$L �h �$A �S �$ �h �$� �h � = �� = �� K� $� �! $b � s � =� �� \� �\ $:+ � s $S6 � s $~ �!\ = S�1 � s vo � �< � � h �9 � h �? � � 5 !� u � � _ � � 5 !� �< � � k � � ] � ' 5 ! �) � ' Z w8 � ' W � j 5 !Z � j � � 5 !| 5 � � S E � j � � 5 !� � � � N �6 � � I � 5 !� �" � @ *C � 0 0 � � � � � � 0= � � � � � � � 5 !� �4 � � � A- � � � � ! 5 !� A � ! � � -! 5 ! ! ^ � -! � � Y! 5 !I! T � Y! � 7( � Y! � | � � � � � ! � �/ � -! � 1F � -! � �" � � �2 � x � &" 5 !" �) � &" h :6 � &" X � � &" H �! � &" 8 � � ( � � � �" 5 !�" �A � �" � �" 5 !�" ^- � �" @ � � � � � � � 7# 5 !'# ]! � 7# � � c# 5 !S# % � c# � �: � �" � � Y! � U8 � 7# � z � 7# � 'A � &" � /4 � c# � �< � c# x � &$ 5 !$ � � &$ h R( � c# X � i$ 5 !Y$ � i$ @ � �$ 5 !�$ � � �$ 0 �% � &$ � �$ 5 ! !�$ ; � �$ M7 � j � �$ � � (% 5 !% C � (% � �. � (% � � k% 5 ![% � � k% � � �% 5 !�% �F � �% p � �% 5 !�% � � �% P � �% 5 ( !�% , � �% � & 5 * ! & �3 � & � � G& 5 ) !7& wE � G& �� � s& 5 2 !c& ~ � s& `� p9 � �$ � w�� w' $] � h $U � h $�+ � h $�; � h $ � h $# � h ($o$ 0$n 8$�0 h @$; H$+: � P$� w' x$� �' �5� # � h �' 5 h �' 5 : =E " �& $ 1 �' = � 7 !�' �' !�' � � @< �3 h � < � � � < <' � � �; � L� �; 9 � �; �7 f� �; 3D )� `; , z� @; � �( 5 � ,�( �: �0 D 9 � �( 5 �+ ��( �< � ) 5 l ) �8 3 # � `8 K �) ]s ]n T 9�" ` 9; ` 9$ ` =<A E) !�) �) 5 !�) !�) � �) �) 5 ; !�) � "#�) �) K��* 9v �Y 9& �Y 9 B �Y 9s �Y 9� �Y 9n �Y 9� �Y =I; � * � �� 0 �* 5 < $#�* `5 ) �* 5 � <#�* �4 � �* 5 ? Z#�* @4 � &+ 5 � %+ �3 u *% �3 1 % �+ M % s h( % s �D % s � %T+ x � �+ �+ 5 q# '.[ �+ � DP 'F � � h �+ h ^� ��+ h � *5� , � ) _: #��+ 3, s /� � J, h /), s a, h �# & s w, ~ � %8 ~ �, � �+ h h :� +��, � 7 +�h �, �D ,�h �, h h E bF �s �, h h /�D �h - h h /� ,�h 8- h � � / h T- h h � j- h �= ))s �- h � �h �- h 7 -.h �- � s �- h h :� ��- /� L� �- h /�B -h . h :H1 )-. h h h :�* )I. � � � " -Ih _. h � -$h u. h ! �s �. /[ Os �. h +�s �. h G #z �+ / s s s s s s h h h h h h h h s h / gh ?/ � �" 'h _/ h h h �h / h / h /� .� �/ s :�; +��/ � ^�? �/ h :�! +��/ � /18 h �/ E DO )�h �< / h 0 h � � /"h 70 h � � �4 �h M0 /P h d0 L -<h �0 h h h h s �6 0 h �0 � #. !h �0 h h � 1 s �0 h � /'5 )8s 1 � ) E De 29 �7 -+h #1 /m s :1 h w �h P1 h /�5 Ks g1 z C& *h }1 h :�% *6�1 � f/ *4� �1 ) T5 3 � �1 � h /7 � �1 h � / �s �1 h ]6 -h 2 � /� , h %2 h k4 \� ;2 h �@ �h V2 h h _�' ) "h ~2 h h � � )(s �2 h h /% Th �2 h h h s � �h �2 h h _= 4D�( 4Cs �2 �> �h 3 h Y ) h /s5 �h 93 h h /�A ,�h U3 h h D� (� � :U ) x3 h h :Q/ )2�3 h h �! ,�h �3 h h # ,�h �3 h h h ( /#h �3 � E /� ,Gs �3 h h �4 s "4 h � � � � h =4 h h 7$ "s X4 h h �& � n4 h +$ <h �4 h h h � %s �4 h h �9 5/s �4 h �B �s �4 h h s d4 .A s �4 ~ ~ ) /� � 5 h � )�h 25 h E DZG )h D/6 h X+ s j5 h h h �. :s �5 h h 9h �5 h D�C -"h q �s �5 h h h ?. �h �5 � � %h 6 � � / h 6 � �( �s =6 h h t h S6 h :gE ) j6 h �6 (h �6 �6 � #1 A+!h �6 b A+< g �*s �6 x �*:h � �*s �D N* s 7 t N*:7 � N*H� �B N*c� str P*h �) �G *h 8 |/ */�* �/ *� ^ *h r- *h k * � *h b *h �E *!h uF *?h 2 *Sh 6+ *� � *h " C*#�7 i *� +2 **� sF -*� �! �) s W8 k �)55 �> �)O5 � �)_s > �)< d �)W8 � g8 5 � � �)5 �8 � �)5 �< �> �) � �)5 C �)5 D �)Y i �) s � x)s �8 err x)Fh �3 x)Uh h) s O9 �3 h)=h � h)Qh i i)� n i)� t p)h u? a)s �9 err a)Mh � a)\h � a)qh GE Q)s �9 cls Q)< a Q)O b Q)` mro R)h i V)� n V)� � Y)h 4# B)s A: a B)8 b B)I mro C)h i G)� n G)� <0 :) s j: a :)( b :)9 x�/ p& @� � ��P r- p&, p&:s � u � q&$s : & ^ q&9 8 K6 r&�+ � � K5 s&~ ( #C t&� � � u&h � � u&h � � � u& h � � 3bad �&�R h� `, w&�F �R � r �R � � `, �R L D �R � � �R � q �R C 7 S � � �� q� q� & v%;< ޜ � � ќ � � Ĝ � � �� S 0- �< 5{ �� p- {% T{ P N G{ u s p- a{ � � �� ^2 �� V2 | Ô Ô ~% = -| � � U| ̔ ̔ � c| | � �- �%i= | 9 3 :| � �- � H| � � n� �+ � � . �%�> � � � � � � � 9 5 �� w s . ,� � � 9� � � F� > 8 | /� P. L?> | � � :| 4� �. � H| � � �� �+ | >� �. M�> | � :| C� �. � H| ; 7 �� �+ | M� / N| u q :| R� @/ � H| � � �� �+ ES p/ �F FS � � � �� 0 �%!:F -� S M � � � 0 :� G� � � � �� p0 � F -� A = � { w p0 :� � � G� T� �� �0 � �E �0 b� � � T� ʜ @1 } D f� f� [ Q s� � � @1 �� �� 8 0 �8 � �1 *C �8 � � �8 � � �8 � 02 x)�8 < 6 �8 � � �{ � � z) A �{ � � �{ � � | �{ � � �{ % # �{ K I �{ � � z) XA �{ u s �{ � � �{ � � �{ � �2 {) �A �{ � � �{ � � | �{ �{ 6 4 �{ \ Z �{ � � {) B �{ � �{ � � �{ � � O9 ,� �2 |)C {9 � � n9 1 - a9 m i �9 ,� �2 e): � � : � � �2 : )(: 9� ! �B ): Y U 4: � � AA: g� O) ^: S: � � ٖ ~2 U| �{ ܜ ܜ ' hC �{ � � �{ �{ * ( �� �� �� x (�� O M �� t r ǝ � � ҝ �8 �� �� % �8 : 8 �8 _ ] � �� U| � � 3 ~ �E � � � � � � � � � �� � � 3 ,� � � 9� 8 2 F� � � | �� 03 L�D | � � :| � `3 � H| � � � �+ | � �3 MEE | 5! 1! :| � �3 � H| o! k! � �+ | � � N| �! �! :| !� !� � H| �! �! 0� �+ U| �� U3 p� �� �3 ��� �! �! �� -" )" �3 �� g" c" _� ;2 � �2 Q0R1 U| � 4 �% [F c| :| � `4 �% �F H| �" �" V� �+ 5� V2 �� J, U�� �� �- �� J, �F U�� U� �5 �Q l� �4 y&'H �Q �" �" �4 �Q 4# (# �Q �# �# �Q l� �4 �%*R $ $ R c$ ]$ �4 (R �$ �$ 5R �$ �$ CR � P5 �% �G oR �$ �$ bR I% E% UR �% % P5 |R �% �% �R & & �R �& �& U| �� �� �%c| ' ' | � �5 �&�H | ,' (' :| � �5 � H| f' b' �� �+ �H U| Uɖ �+ | �� �� �& I | �' �' :| �� �� � H| �' �' �� `� 6 {& PI ޜ �' �' ќ J( D( Ĝ �( �( �� ) ) �P �� p6 |&#K �P W) O) �P �) �) �P !* * �P �* �* p6 �P 1+ #+ �P �+ �+ &�P | �� �6 j&%J | _, [, :| �� 07 � H| �, �, � �+ U} | �� `7 m&�J | �, �, :| �� �� � H| �, �, �� �+ U} �� , �J Uv T} Qs ͘ �/ �J U T� T} Q x� R| � 3, K U} �� , Uv Qs � �� �7 �& �L � - - � s- o- � �- �- �� �- �- �7 ,� ). %. 9� c. _. F� �. �. | ї �7 L�K | �. �. :| ֗ �7 � H| / / �� �+ | � 8 M[L | K/ G/ :| � P8 � H| �/ �/ �� �+ U} | � �8 N| �/ �/ :| �� �8 � H| �/ �/ �� �+ Uv Q � �8 �& 0O $Q 90 /0 Q �0 �0 �8 1Q +1 !1 EQ � �8 &SQ �1 �1 mQ w2 m2 `Q �2 �2 �8 zQ c3 _3 �Q �3 �3 �Q (4 4 CR � P9 �% �M oR 5 5 bR [5 U5 UR �5 �5 P9 |R �5 �5 �R f6 Z6 �R �6 �6 U| �� �� �%N c| |7 z7 �Q �9 HN �Q �7 �7 ,� �+ T } $ &4$ U| � � �% }N c| �7 �7 )�Q e� $ O �Q �7 �7 U| k� k� �% �N c| 8 8 :| p� p� �% H| 88 68 � �+ � �1 U | �� �9 �& �O | _8 [8 :| �� : � H| �8 �8 ~� �+ Us | ƙ @: �& �O | �8 �8 :| Й p: � H| 9 9 q� �+ Us | � � * �& ZP | M9 K9 :| � � � H| t9 r9 ^� U3 ӕ w, �P U~ T| R0 � a, Uv , ^&�+ Q r- _& _&'s � `&s ^ `&& K6 a&�+ o- b&h 3bad l& 4� �% ?Q b �%*s � �%Q � &#?Q # 4H �% �Q � �%E?Q b �%Us � �%| pos �% s i �%s ~ �%!\ #�Q tmp �%% �% s � �%$ �Q b �%?s � �%#?Q e �%! � �%$ CR � �%Z?Q b �%js � �%! pos �% s �8 �% s �R ~ �%B\ :+ �%Os b �%Zs " �% s mid �%s end �% s �D l% s US #C l%3� l%?s 1 m%h n%h � n%h � n% h � p%� #ES c {% � �< � {% h �< �C �%h ) ^%h �S ml ^%4 � ^%<s #+ ^%Mh �- _%1h � _%Dh � _%Vh �, _%ih op `%h >% s �S � >%,h � ?%�' (I �$h �� � ��U �" �$Rh �9 �9 � �$iY B: 0: 2 �$v) ; ; �$�h S; E; , �$ �U �; �; 2cls �$ �< �< aE %� -= %= � %h �= �= �. %. �= �= �{ �� � %U �{ �> �> �] �� 0 % �U �] �> �> �] )? #? �] z? r? 0 �] �? �? si � ` }$ �i -@ +@ �i ]@ Y@ ` �i �@ �@ � 5 T � R � L�� �U Q�TX�R G Q�T# � (� �$h � e ��W �" �$Kh �@ �@ � �$bY �A �A 2 �$o) !B B �$�h fB ZB , �$ �U �B �B aE �$� �C �C � �$h D D �. �$. CD =D �{ � ` �$�V �{ �D �D �] � � �$ �W �] �D �D �] E E �] ]E UE � �] �E �E si H� � }$ �i F F �i @F <F � �i {F yF n� 5 T � R � L/� �W T�TR�R GD� T�T# y�> �$h pu � ��Z �" �$;h �F �F � �$RY UG KG 2 �$_) �G �G �$qh H H , �$ �U �H �H aE �$� �I �I � �$h J J �. �$. DJ <J �{ pu �$�X �{ �J �J �] �u P �$ 3Z �] �J �J �] zK rK �] L L P �] �L �L �] v v ) x$�Y �] M M �] SM QM �] xM vM �] si v v " �$ �i �M �M �i �M �M �i �M �M )v 5 T � si 0v 0v }$ �i N N �i DN BN �i iN gN �i �u �u % �$ �i �i �N �N �i �N �N �i �N �N �u 5 T � R +� (�B �$h � � ��] �" �$@h O O � �$WY �O �O 2 �$d) LP HP �$vh �P �P , �$ �U lQ ^Q aE �$� R R � �$h �R �R �. �$. �R �R �{ � � �$�[ �{ SS QS �] #� � �$ �\ �] �S vS �] 'T T �] �T �T � �] CU 7U �] �� �� ) x$�\ �] �U �U �] V �U �] %V #V �] si �� �� " �$ �i JV HV �i xV vV �i �V �V �� 5 T � si �� �� }$ �i �V �V �i �V �V �i W W �i `� `� % �$ w] �i �i <W :W �i jW hW �i �W �W �� 5 T � R � GE� T0 L x$s �] , x$X�U aE x$k� x$|h ret z$ s 3/ M$h V^ �" M$:h � M$Jh kw M$Zh e N$h , O$ �U vc Q$) ,8 \$� 4> ]$h � ^$h I: B$ h �^ �" B$@h arg B$Ph kw B$_h � C$h e C$h (-; �#h �m � �a �" �#9h �W �W � �#Ih �X wX +arg �#Yh �Y bY +kw �#hh �Z �Z 2f $a /\ \ �. $. �\ �\ � $ s �] �] T $� �^ �^ � �_ e ($h �6 ($$h 5_ 3_ Gn U�T �i n n $ ` �i [_ Y_ �i �_ ~_ �i �_ �_ �i �_ �_ �i o 0 4$ ~` �i �_ �_ H�i +� ��i ` ` 0 �i D` B` Bn 5 T � si �n �n & >$�` �i k` i` �i �` �` �i �` �` �n 5 T � R d� L�m a U�TT�QQ�R ^n S6 7a T F� �n X4 Pa U�R �n X4 ia U�R o X4 U�R (�C �#h �o ��a +op �#/�U �` �` �C �#h ?p �/ U �� Q�U z3 �# s "c m �#>�U G7 �#K� arg �#X� #4b e �# s #Zb ^ �#s `�t v T| #}b ^ �#s ;�t T| #�b ^ �#s ;�t T| #�b ^ �#s #�b ^ �#s #�b ^ �#s #�b ^ �#s #�b ^ �#s #c ^ �#s ^ �#s a�C �# Pt ) ��c +m �#>�U =a 5a �c Yt � �#�c �c �a �a ht �/ �c Uv pt �c �c Uv ?yt �/ U�U Yt �/ Uv 4�G �# �c m �#?�U (( �#s �q j ��h +m �#0�U �a �a 0 xd � �#h �b �b :| �q p �#H| �b �b Et �+ � �d � �#h �b �b :| r � �#H| 4c 0c 5t �+ e � �#h nc jc :| +r 0 �#H| �c �c %t �+ ` ke � �#h �c �c :| Fr � �#H| d d t �+ � �e � �#h Vd Rd :| ar � �#H| �d �d t �+ f � �#h �d �d :| |r P �#H| e e �s �+ � ^f � �#h >e :e :| �r � �#H| xe te �s �+ � �f � �#h �e �e :| �r �#H| �e �e �s �+ @ %g 2cls �#h &f "f | �r p �# | `f \f :| �r � � H| �f �f �s �+ � vg � �#h �f �f :| �r �#H| g g �s �+ 0 �g � �#h Hg Dg :| s ` �#H| �g ~g �s �+ � h � �#h �g �g :| 0s � �#H| �g �g �s �+ � ih � �#h 0h ,h :| Ms �#H| jh fh �s �+ P � �#h �h �h :| ds � �#H| �h �h us �+ lB c#h <i op c#@�U ml c#Q � c#Ys #+ c#jh �- d#2h � d#Eh � d#Wh �, d#jh cf f#a M�E P#h si m P#1�U � P#>h e R#h 4�F # �i �" #G�U d #Y � # 4�: �" �i �" �"Q�U d �"c T �"w� � # �0 �"h %j op �";�U 6, �"E� e �"h �' �"h �j op �"A�U � �" s "? �" �' �"h � �"(h �3 �"1h � �"<h (v �"h m @ �`k +op �":�U i �h 6, �"D� >i :i e �"h {i wi `k m 0 �"rk �i �i 0 ~k j j U| m ` �"Pk c| Tj Pj 6m >5 � �"h �k op �"A�U e �"h v �"s �k op �":�U � �"Hh 6, �"U� tmp �"h ({ �"h P� � ��m +op �"9�U �j �j 6, �"C� �j �j e �"h �m P� �"�m xk pk �m �k �k U| c� c� �"�l c| kl il Yp �� �� 4 �"kp �l �l wp �l �l �p �l �l U| �� �� D"m c| m m U| �� �� F"Lm c| :m 8m :| �� �� O"�m H| _m ]m �� �+ ;�� Us � �"h �m op �"@�U e �"h @ |"s n op |"9�U � |"Gh 6, |"T� tmp �"h ( s"h p � ��o +op s"7�U �m �m 6, s"A� �m �m be t"h �o p ` w"�o pn hn ` p �n �n U| #p #p o"�n c| co ao Yp Gp Gp 4 i"kp �o �o wp �o �o �p �o �o U| `p `p D"Zo c| p p U| lp lp F"�o c| 2p 0p :| pp pp O"�o H| Wp Up {p �+ ;Ip Us �8 e"h p op e">�U e f"h F S"s Yp op S"7�U � S"Eh 6, S"R� tmp `"h �( ="s �p op ="8�U e >" s res ?"h (�/ 5"h �l � q Vop 5"3�U UW6, 5"=� Te 7"h ~p zp U| �l 9"c| �p �p (? -"h �l �wq Vop -"6�U UW6, -"@� TU| �l �l 1" c| (� &"h �l ��q Vop &"6�U UW6, &"@� TU| �l �l )"c| �p �p � "s 1r op "3�U � "Ah 6, "N� tmp !"h () "h Pm 5 ��r +op "3�U q q 6, "=� Rq Nq e "h �q �q �r Pm � " s �q �q U| Ym � "�r c| r r nm >5 # �!h s op �!:�U ! �!s Us op �!7�U � �!Eh 6, �!R� tmp �!h } �!h �s op �!7�U 6, �!A� e �!h 8 �!s �s op �!3�U � �!Ah 6, �!N� tmp �!h (W# �!h po / ��t +op �!3�U [r Ur 6, �!=� �r �r e �!h �r �r �t po � �!�t Ps Js U| yo � �!�t c| �s �s �o M0 m �!h �t op �!:�U ( �!s Pq A ��u +op �!2�U �s �s � �!@h 1t )t 6, �!M� �t �t � �u 2tmp �!h �t �t | aq � �!| u u :| fq � H| Eu Au |q �+ U| Uq ` �!c| }u {u (� �!h �o E ��v +op �!2�U �u �u �- �!<� %v v e �!h uv qv �v �o � �!�v �v �v U| �o 0 �!]v c| +w 'w U| �o �o �! �v c| �o 70 wA �!h �v op �!9�U N! h w �" N!Jh vc N!e) � N!zY aE N!�) kw N!�h +7 P!� $E !h �w �" !?h vc !Z) � !oY aE !|) kw !�h res !h !h �? !� � !� i !� pos !� j ! ) key !h � !h � !5 nkw !!� "�: G! ( . !h Po ��x �" !/h kw ew � !?h �w �w +typ !Oh x x �z `o ` !�x �z ]x [x U| `o `o �c| �x �x ?Zo �0 U�UT�T j* � }y � � >h � � S/ + � ch . � h #4 � #h .& � 8h 4 � Jh O- � \h X � s R- � " � 3bad � �, � s �y #4 � -h � � , � � +� � � � �" � h z d � Bh key � Oh } � ^h � � <s � � h cu) � h (�) i h G � ��| � i -h �x �x � i ?h *y $y � j h �y vy "0( � �| �E l z z � m h [z Uz �= n h �z �z �! o h �z �z | �G ` � N{ | G{ E{ :| �G � � H| l{ j{ �G �+ U} | �G � � �{ | �{ �{ :| �G �G � H| �{ �{ �G �+ U| | �G � *| | �{ �{ :| �G �G � H| | �{ �G �+ Uv gG V2 oG T- O| Uv |G 70 �G 8- t| Uv �G 8- �| U| T �G _. U} #G p� �| Uv T >G j- ]G 5 T �� Q � V h ^} n V /� Eva W # l X h 3end c i [ � arg \ h � _ h V$ ; h �} � ; 5h D ; Eh � = h � ? h �/ A h . h �} � . 6h D . Fh � / h � 0 h M 1 h j~ � ?h � Qh D ah i � {4 � >& h � h � h �~ � =h � h M� � h � � <h D � Lh :+ � d� � � h � %h sep � 4h T � � 3bad � �C � h w � � )h �E � 9h �D � Hs � � h �4 � h == � h 3bad � Y3 u � � u 7h � u K � u d T v ) 9 v ) � v J� e x h � y W8 � z � � { � 3bad � BG s B )h ret s "( h �= h S h M h - h $ h �! h U7 h �) h "� c "�6 Z � \ b (�7 s �O W �� �. 2h '| #| � Bh j| `| 2ret s �| �| �? h 7} /} | �O �" �� | �} �} :| �O �O � H| �} �} �O �+ Uv �O � ց U�U �O V2 �O �4 Uv T| Q2 (^A � s �F } �g� +tp � 3 �} �} +k � Ah J~ D~ +v � Nh �~ �~ e � s �~ �~ � � h $ " F�F 2 � �; � h M I :| �F �F � �� H| � � �F �+ �F �, Uv Q} R~ X0 �F J5 :� T~ Qv �F �- R� U} �F �, Uv � � s �� tp � 3 k � Ah e � s � � h � g s ;� t g - r o s + s h SF x s ret } h A } h gc ~ h tp � h v � h tb � h ] s h� t ] L + _ h �1 s � , 3 � I� + _h i � n � b b0 # h #� � + b � 6 � � B $b (� h SM . ��� +obj 7h � � � Fh � � � h � �� e h �� v� � s � � 3bad �� SM � 9� �� ^� X� �� Ƃ �� �� v� n� � ȋ � ҃ Ջ x� v� � �� �� � �� � �� n� d� � � ߅ � � � � _� W� %-� �N U| �M �M � �� c| Ć U| N N � �� c| � � 5{ N � 3� T{ � � G{ L� F� a{ �� �� .N ^2 $� U��T| DN V2 :| DN DN � ~� H| � � SN �+ U�� :| vN 0 � �� H| � � �N �+ U p| �N �N � �� �| �| 6� 4� )6� �N �� 7� [� Y� U| �N �N � P� c| �� ~� :| �N �N � H| �� �� �N �+ Uv U| O O � ˈ c| ʈ Ȉ :| O O � � H| � � 'O �+ U�� | 'O 'O � �� | +� )� :| ,O ,O � H| P� N� 9O �+ U �M p� �� Us T| �M �- ̉ U~ T| �M u. � U~ N �- �� Us <pN � U Ts �N 5 T P� R| F� �N ` �� e� u� s� X� �� �� ` r� ��O � U T��Q ���������,�� 0 :| O � � H| �� �� O �+ U �� ;O � U� �� � � � �� ��YO � Uv T��Q ���������,�� 0 :| `O � H| � � jO �+ Uv � s F� obj � /h � � >h � � O� �? � h , � b tp � |/ � h f � �* � � &$ � h �E � s "�+ � 4% � h 2 � h �� �" � Dh arg � Th � � �� h �� 5 b � h �� �" � Ch arg � �� �( V s � � V ?/ O V S 4� 0 /� � 0 . Y? 0 Gh key 1 h pos 5 � �, & s i� =! & , obj & @h , ( b e7 h �� � 7h i J�� � c� e h � 4�% E r� O E #h � E 3h tb E Dh � E Rh �F F h 3bad � #B� 91 Y h #2� ^* ] s � h h #U� � � h #C � � $ � h � h �� obj @h val � "j5 # (�* � � � 3 ��� +obj �?h B� ,� " �P :� &� �b� � � � � � �� �� 2i �� � � : �� i� g� v, � �� �� zend � � ��*� 0� 0% � . �g ��7.� p% �� Z� M� �� �� @� p% g� �� t� �� �� �� '�� �% �� V� L� �� � �1 T��Q0 �$ � . �� Ώ ȏ 7.� �$ ��� Z� M� � � @� �$ g� U� Q� t� �� �� �� '�� �$ �� � ߐ �� �� �1 � �1 U~ T��Q0 +� }1 � U~ >� }1 U~ �� (� �# � ,� Ē 3� /� �� W� W� � a� Ē k� i� ђ t� $ � ё � �� �� � _� Q� $ �� :� � � �� �� � ܗ ֗ %$� �� �� 0� 0� A �� �� N� L� ȓ s� q� )Փ L� % k� ֓ �� �� :| U� `$ � H| Ԙ Ҙ f� �+ 8� g1 U| H� �1 �� Uv T��Q0 ^� 25 � �s ђ ch �?� LB �� .� " �; �M� � � s � � � �A � s "� � H= � �� " �= $ �J� �]� % � s � � s i �� chr �� �) � s m �� � obj �5h � �h � �� 4�- � O� A5 � � � s � �� � �� 19 �� 9! �� ! � 37 p s ה Y? qh � rY �( sה k th + u� {- v� 7G w� � x � y s � �8 3 s �� Y? 4h � 5Y �( 6ה k 7h + 8� {- 9� 7G :� � ; � < s key >h � ?ה � @ה 3bad j"o: e pos A� #�� � Mh � P) cmp Qs #� � Sh � X h MM) � s �� Y? �h �( �ה k �h + � {- � � � ה � ה len � 3bad 0 key h � h �/ � s q� Y? �h �( �ה + �� {- �� 7G �� � � � � s � �ה � �ה �" �� 3bad � key �h � �h �E � s 4�% � �� Y? �h �( �ה � �ה � � pos �� key �h � �ה � �) cmp �s &0 �s M� key �h �( �ה � �ה � � M� � � ) �. t s � key uh �( vה � wה � x M� � y � {ה " �3bad �"�' �#� cmp s cmp � s �2 1 s �� key 2h �( 3ה � 4ה � 5 M� � 6 � 8ה �1 :� 3bad q"�' n#�� �E Ch �E Zh e &s � s1 &?h s2 &Mh �< ' s len (� 9 ,~ 9 -~ M�9 s j� Y? h �( ה � ה � � ה 3bad " key h �E s R h ˚ �" RFh � R]Y `E Rj) ;G R|h aE S� f s) �1 =%) � � =Kh tp > o, H� ptr J) �& h e� �" Ch arg Sh � h e h v( . h �� �" >h arg Nh kw ]h e h ' � 4�4 � � A5 � �h J0 �h � � �1h e �h �+ � h T� obj �Kh �Zh e �h tp � 4�' z p� C {� �? p h �� obj pDh pSh tp q 45" Q� #C Q@� O QS� � Qd� tb Qv� 4� 5T� #C 5B� O 5Th � 5dh tb 5uh Eh � Eh $ E&h /? s �� #C M� err _h e s �3 h � s ޝ �3 8h � Lh i � n � 42 � s �� "� � S � s L� � �6�' � � h 3bad �#O� |/ �+�* �/ �I #o� |/ �+�* �/ �I #�� |/ �+�* �/ �I #�� |/ �+�* �/ �I #Ϟ |/ �+�* �/ �I #� |/ �+�* �/ �I #� |/ �+�* �/ ��� #/� |/ �+�* �/ �I |/ �+�* �/ ��� � x s u� � x2�' "� ~ �" o s �� � o8�' �/ e s �� � e7�' "� j (� � s �P � ��� m. �Dh �� �� �6 �s o� a� � ��' � � 3 � h U� O� ! � h ښ �� E3 � h �� � � �s � � % � �� �� � �s � � "� �*= �U � *� �B h �� �� ;U �5 VU �5 � U| T �� eV j5 U| T �� F�U # �� � �h � �� :| �U �� �H| %� #� �U �+ U| Q Q ��� c| J� H� U| 9Q 9Q �� c| o� m� �z <Q <Q ��� �z �� �� �z ¤ �� | HQ HQ ��� -| � � U| MQ MQ � c| � � HQ 1 U � �z `Q `Q �(w� �z 1� /� �z _� ]� | lQ lQ �[� -| �� �� U| qQ qQ � c| �� �� lQ 1 U � g8 �Q p� �� p� '�8 �� �8 Х ̥ �8 � � �8 E� A� �8 �� ~� �8 � � �Q 1 8 R н �Ȥ 8 O� K� -8 �� �� 8 ѧ ˧ н :8 (� "� IG8 3R Y H8 ��}yR �0 �� U��}T�Q � R3X9Y �� �R �0 U0T��}Q1 �S �R � �� �S �� �� � �S �� �� �x �R p� @%$�x � � y g� c� �x �� �� p� y ֩ ̩ y _� G� )y Z� T� 6y �� �� Cy � ݫ Py .� ,� ]y X� R� &jy %sy �S z S о � �� �z S � � �z �� �� 0� �z Ѭ Ϭ | (S (S �i� -| �� � U| 1S 1S � c| � � %S 1 U A� �z HS `� � *� '{ B� >� { �� �� { �� U| jS jS ��� c| � � SS "4 � Us T~ `S 25 �y �S �� � � �y 4� 0� �y r� l� �y �� �� �y �� �� �� z 5� /� U| �S �S � �� c| �� ~� �S ?/ Us T~ Q} :| �S �S � +� H| �� �� �S �+ U} :| �S �S � t� H| ߯ ݯ �S �+ Uv 7| �� � Ũ | � � :| �S �� � H| @� <� T �+ | T � � 3� | x� v� :| T T � H| �� �� T �+ U| :| T T � |� H| ° �� T �+ U~ �R �/ �� U T. S 70 �� U <S =6 ʩ U| �S _/ � U| T �3 Q0 �S }y Uv T L� TT � � ^� � � � %k� |d �6 �T P� |�6 � � �6 �6 Q� M� '7 �� 7 �� �� �T M0 �T / �� R0 �T �5 �T �5 U �4 ޝ U � #� � %� |d U 25 �� _U `� q� �� � � `� &�� kU � �V � �� �V �V w J� � Y� U� � �� �� %&� Y )/� �V D � 4� A� ��}�V �� UсȀ�T��}X| @b7 )O� �V ? e� T� a� ��}*W �� Uс܀�T��}X| @b7 )o� :W ? �� t� �� ��}iW �� Uс耰T��}X| @b7 )�� yW ? � �� �� ��}�W �� Uс���T��}X| @b7 )�� �W ? ^� �� �� ��}�W �� Uс���T��}X| @b7 )Ϟ �W ? �� Ԟ � ��}&X �� Uсā�T��}X| @b7 )� 6X K � � � ��}qX �� U⁀��T��}X| @b7 )� �X ; W� � !� ��}�X �� Uс���T��}X| @b7 )/� �X C �� 0� =� ��}�X �� U⁌��T��}X| @b7 :| �X �X �� H| � � Y �+ U| :| Y Y �<� H| � � Y �+ U| �V >5 >� :Y �� !�� P� >� :� �� ]� �� �� j� Ƴ ³ w� � �� &�� �� HY 0� �ŵ �� 0� ȃ >� :� Ӄ |� t� O;� HY p 0� M� � � IX� HY Y� %� #� h� ?e �� t 6� �� R� J� �� �� �� z� E� ?� �� �� �� �� �� � ݶ '�� �� �� j� b� Ä ַ τ @� � Ԅ N� J� �e 5 T 0� '� p� � �� �� '� �� � � � �e 5 T X� )� �e � �� � (� &� � Q� K� �� �� �� � � �� :| %f %f � ̱ H| z� x� 7f �+ U| �6 <f <f 4 � "� �6 �� �� �6 ٺ mf #1 U} :| pf pf � k� H| �� �� ~f �+ U} :| �f �f � �� H| #� !� �f �+ )� �f � �� � ��}!� ��},� ��} | g g � T� | H� F� :| g g � H| m� k� g �+ | 7g 7g � dz | �� �� :| <g <g � H| �� �� Fg �+ | Kg Kg � :� | ܻ ڻ :| Pg Pg � H| � �� Zg �+ | _g _g � �� | &� $� :| dg dg � H| K� I� ng �+ �f -. Ӵ U��}T��}Qs �f � � U| 0g . :| rg rg � B� H| p� n� �g �+ U| �e _. f I. f � t� U| �f � �� U| �f u. U 9 nY u. U 9 � �Y �� ��� '� �� �� �� 4� � ͼ A� '� � N� � � [� D� 6� h� � ۿ u� � � �� s� ]� �� h� X� �� %� � �� �� �� %�� \ %�� �[ g� �Z � G � �� `� ^� y� �� �� � �� �� �� �� � � �Z �- �Z �- U~ g� i[ P� Q |� �� ?� =� y� n� j� P� �� �� �� �� �� �� |[ �- �[ �- U~ )Ȁ �[ �� ɀ � � \ 5 T � | \ \ 2 j :� | D� B� :| \ \ " � H| k� i� B\ �+ U��} | B\ �� k �� | �� �� :| ]\ ]\ " � H| �� �� \ �+ U��} | \ \ l $� | �� �� :| �\ �\ � H| � � �\ �+ U | �\ �\ m �� | A� ?� :| �\ �\ � H| f� d� �\ �+ U| | �\ �\ n � | �� �� :| �\ �\ � H| �� �� �\ �+ U} �Y �- 0� U~ �Y �- H� U} Z �- `� U} Z p� x� U~ BZ �- �� U} ]Z p� �� U~ �Z � �� U~ �Z ں U��} �Z � �� U~ Q [ 25 '[ � � U~ 8[ V2 G[ � B� U~ a[ � `� U~ Q} �[ 25 �[ �- �� U~ �[ 25 e U| �Y �5 �� �\ �� "y� �� �� �� �� � I� =� � �� �� � <� 4� '� �� �� &4� w �\ � �3�� � � � � T� P� � �� �� � �� �� � � � � Z� T� � � �� �� � ��}� � � � q� o� & � �{ �\ �\ � @� �{ �� �� �{ �\ �\ | �{ �� �� �{ �� �� �{ � � | �d � � �� | 3� 1� :| �d �d � H| X� V� �d �+ U} �\ �- ӽ U| T ]� (] 5 � T 8� Q � R ]� ] 5 L� T `� Q � R ]� X p �] �0 �� Us T�Q � R � X ]� Y p �] �0 U0Ts Q0 :| �] �] �� H| }� {� �] �+ U| | �d P� �\� | �� �� :| �d `� � H| �� �� �d �+ �\ �- U � :| +^ +^ 1¿ H| � � 8^ �+ U~ :| r^ r^ > � H| ;� 9� ^ �+ U~ :| �^ �^ BT� H| `� ^� �^ �+ U~ :| �^ �^ C�� H| �� �� �^ �+ Uv :| _ _ P� H| �� �� _ �+ Uv :| T_ T_ T/� H| �� �� b_ �+ Uv :| b_ b_ Ux� H| �� �� o_ �+ U~ :| �_ �_ b�� H| � � �_ �+ U~ :| �_ �_ f � H| >� <� �_ �+ U~ :| �_ �_ gS� H| c� a� ` �+ Uv :| @` @` s�� H| �� �� N` �+ Uv :| �` �` �� H| �� �� �` �+ Uv :| a a �.� H| �� �� a �+ Uv :| fa fa �w� H| �� �� ta �+ Uv :| �a �a ��� H| � � �a �+ Uv :| *b *b � � H| A� ?� 8b �+ Uv :| �b �b �R� H| f� d� �b �+ Uv :| �b �b ��� H| �� �� �b �+ Uv :| Vc Vc ��� H| �� �� dc �+ Uv :| �c �c �-� H| �� �� �c �+ Uv :| �c �c �v� H| �� �� d �+ Uv | od �� ��� | � � :| od od � H| D� B� |d �+ U~ | |d �� �R� | m� g� :| �d �d � H| �� �� �d �+ Uv Q S6 q� T `� )Q =6 �� U�U �Q 6 �� T %� "R 6 �� U0 �R �5 �� U ^� T0 �R �5 � U ^� T0 �U j: 9� U H� T} Q| R~ �U 25 �U S6 e� T H� *V �5 ^ �� �� ,}} 0 #^ J5 �� Q~ K^ V� �� U1 f^ � �� T~ ,9 0 �^ $z �� Uv �^ J5 � Q~ �^ V� � U1 _ � ?� Tv ,9 0 *_ $z W� U~ L_ J5 o� Qv �_ V� �� U1 �_ � �� T~ ,9 0 �_ $z �� Uv �_ J5 �� Q~ ` �� �� ,}} 0 8` J5 � Qv x` � 1� U @< T0,�S 0 �` J5 I� Qv �` � t� U < T0,�S 0 �` J5 �� Qv <a � �� U < T0,�S 0 ^a J5 �� Qv �a � �� U �; T0,�S 0 �a J5 � Qv b � =� U �; T0,�S 0 "b J5 U� Qv bb � �� U �; T0,�S 0 �b J5 �� Qv �b � �� U �; T4,�S 0 �b � �� Qv ,c � � U `; T4,�S 0 Nc J5 � Qv �c � I� U @; T4,�S 0 �c J5 a� Qv �c >5 �c J5 Qv (� �$h ~H a ��� � �Ah �� �� +def �T�� 2� .� � �h s� k� � h �� �� � �)h � � 3bad �+� ~H � � |� � T� I� E� �H �+ �H �+ �H S6 T �� �z �H ��� �z �� � U| �H �H �c| �� �� :| I @ �� H| �� �� I �+ U~ | �I p ��� | �� �� :| �I �I � H| � � �I �+ Uv �H �- �� U} T �� I �+ �� U~ 'I =6 �� Uv RI �� � U} T~ Q �� R �� X1 uI �� P� U} T~ Q �� R �� X1 �I �� �� U} T~ Q �� R �� X1 �I �� U} T~ Q �� R �� X0 g (6 � s H ~ �+� � �Bh <� 8� �Rh {� u� � �g �� �� +B �~ � � � ��s `� V� � �h �� �� e � s *� $� :| CH CH � �� H| w� u� QH �+ Uv H �- �� U�UT�Q @H j5 � U} T~ Qv fH j- oH V2 " p s b� �* q[ `3 � y[ {� Nh �k ��� ?�k j6 U `8 >, s �� � A�' �B � s �� � �A�' F � s >� � �=�' 3 � h � �s % � � �s "� � v � s �� � �;�' � �s % � � �s "� � �F � s �� � �A�' �: � s �� � �A�' M � s �� � �=�' (�) # s �q ; ��� +o #dh �� �� 2tmp $ h �� �� 2p %T�� � �� U| �q ` 'm� c| | �q � (| =� 9� :| �q � � H| w� s� �q �+ 5 (i& s �l �\� +o gh �� �� +v t� �� �� +a }� o� i� |e s 2p T�� �� �� d�l �TT�Q a� �p � ��� +o gh � �� 2p T�� �� �� � �� � h x� t� :| �p � H| �� �� q �+ C� � h �� �� :| �p 0 H| &� "� q �+ �p �/ [� Uv L�p p� U�U %q �. Fq �. Uv (�$ �h �� � �%� +t �l d� \� +a �yh �� �� +k ��h �� �� 2p �T�� x� n� 2o � h �� �� }bad ��� k � 0H �p� � �� u� � �� �� } �� �� 0H � C� -� � @� *� � 5� '� � �� �� � ��� N� 4� � �� g� � �� �� �� �� % �� %" :� %+ � %4 � = �I �� B ��O 0� &� \ @K � ] �� �� �z Q� @L ��� �z � � U| Q� Q� �c| C� A� �z ^� pL �� �z h� f� U| ^� ^� �c| �� �� O� g� �L � <� �� �� �� ɔ �� �� �� � � �� �� �� �� �� �� �� ]� U� {� �� �� n� =� 5� a� �� �� �{ g� g� {!�� �{ � � �{ +� )� �{ Q� O� 7ݔ `M |�� � W� J� =� 0� #� � �� � `M d� �� y� q� � � ~� &�� %�� �� �� N Y� �� :� 2� �� �N �� �� ��̕ �� �� ٕ O �� ޕ �� �� �z P� �O T'�z �� �� U| P� �O �c| � � �� 9� �O Q?� C� ?� 2� �� �� %� � �� �� � � � p| 9� 9� � �� �| �| u� s� r� ٝ �� U��~T��~Q} R��X o� �� � U��~T��~Q} R��X o� '�� �O �� �� �� �z ʦ 0P N%�z �� �� U| ʦ @P �c| �� �� �� 5 T �� Q o� O� ¨ pP p �� � � ɔ � � n� � � �� G� C� �� �� �� �� �� �� �� �� �� {� 4� 0� a� v� p� �� ¨ pP � � �� �� �� �� �� � I� G� � r� n� ֖ �� �� ɖ �� �� �� .� (� pP � � w� $� � � 1� ?� 3� &>� G� �P 5� H� � � U� � � b� +� %� U| � �P � � c| y� w� 5� "4 '� Uv [� 25 q� �� �� � � $� �� �� �� �� � � �� �� �� � #� !� �� ��~�� ��͗ Q �� Η J� F� 'ۗ @Q ܗ ��� �� �� �� +� �Q ��� ?� � � 2� � � %� T� P� � �� �� � � � p| +� +� � q� �| �| � � Q� ٝ �� T��~Q} R X o� �� � T��~Q} R X o� �� 5 T �� Q o� � �3 Uv Ts Q~ R0 Ǩ �4 Uv 'j �Q k G� C� � �� �Q �%'� � }� � �� �� � �� �� � � � � � � �Q 4� � � A� F� B� 7� 5 T � Q o� R g� X2Y �� �z �� R �b� �z �� �� U| �� 0R �c| �� �� �z ۥ `R ��� �z � � U| ۥ �R �c| �� �� � X4 Uv � :� �R �� '� � � � E� C� � E� C� � k� i� � �� �� �R 4� �� �� A� � � y� 5 T � Q o� R g� X2Y �� y S � ~ � � | y� pS | � �� :| ȧ �S � H| U� O� � �+ � Uv l� �+ � � 0T �� �� �� � � � � p� h� 0T � � $ * 1 � � > 8 . K � � %X � &a U| � �T ,�� c| 8 4 :| � U / � H| r n *� �+ U| � @U :5� c| � � p| � pU ; c� �| �| � � :| � �U >�� H| � � C� �+ /� �� �� # ;N� N� . , A� S Q [� � � 5 T y� Q �� | � �U Nr� | � � :| � �U � H| � � � �+ Uv � j: U �� T ;Q>R � � V :� � 6 . | � `V | � � :| � �V � H| � �� �+ #� Uv �� �+ U} �� j: U �� T} Q<R � U| � � ��� c| U| � W �&�� c| :| �� 0W ��� H| b ^ �� �+ U| <�� � U�UT0 ;�� Q0 A �h �� �< ���� 2* ��h � � h � �s % � � �s "� � (�5 {h � � �.� �< {{h � � B) }Y l \ [E })� H S? }@h � 2* �h � � � �"Y A + � I ��� �s � � % � B 4 � �s � b� � h *�> �֭ *X �w� *� ��� *� ��� `W �� �( �>� ��n0 �� � � �X �� � �� m [ 0` �� 2i �� , ( � `` �%'� d b � � � � � � � � � � � � `` 4� � � A� � 5 T � Q �� R g� X1Y ^� �z � �Y �V� �z K I U| � � �c| p n O� � Z � �� � � ɔ � � �� 3 ' �� � � �� � y �� = 1 {� � � n� � q a� } g �{ � [ {!+� �{ f d �{ � � [ �{ � � 7ݔ @[ |�� � W� J� =� 0� #� � �� � @[ d� � � q� n l ~� &�� %�� �� �� \ �� �� � � �� �\ A� �� ��̕ � � ٕ ] A� ޕ 1 / �z w� �] T'�z V T U| w� �] �c| { y �� Y� �] Q?� � � 2� � � %� � . * � r j p| Y� Y� � �� �| �| � � �� ٝ � U��~T��Q R��X �� Y� � U��~T��Q R��X �� '�� �] �� � � �z b� 0^ N%�z U| b� @^ �c| C A ѭ 5 T �� Q �� O� �� p^ p �� l f ɔ l f n� � � �� A ; �� � � �� � � �� ^ X {� � � a� �� �� p^ � � r l �� � � � .! (! � ! w! ֖ �! �! ɖ 9" 3" �� �" �" p^ � �" �" $� e# ]# 1� �# �# &>� G� �^ � H� |$ z$ U� �$ �$ b� �$ �$ U| Я _ � Y� c| -% +% � "4 q� Uv !� 25 q� �� 0_ � h� �� T% P% �� �% �% �� �% �% � .& *& 0_ �� ���� ��͗ `_ A� Η h& d& 'ۗ �_ ܗ ��� �& �& �� � �_ �� ?� �& �& 2� 2' .' %� r' n' � �' �' � ( �' p| � � � �� �| �| <( :( .� ٝ �� T��~Q R} X �� ñ � T��~Q R} X �� h� 5 T �� Q �� İ �3 Uv Ts Q| R0 �� �4 Uv �z � �` ��z c( a( U| � � �c| �( �( a Z� �+ �� �( �( | �� @a �| ) �( :| ߭ ߭ � H| ;) 9) � �+ F � C �� �+ �� b) ^) | � �e � | :| 2� f � H| E� �+ Us � w� �` ��� '� �) �) � �) �) � �) �) � �) �) � �) �) �` 4� )* '* A� O* M* �� 5 T � Q �� R g� X1Y ^� %� �� pa � �� 7� �* {* D� '+ + pa Q� �+ �+ ^� W, I, k� - �, x� �- �- %�� � �� �� 0b �� ލ ]. Q. � ]. Q. э �. �. č �/ �/ 0b �� �0 �0 &� �{ �� �b P �� �{ �1 �1 �{ �1 �1 �b �{ 2 2 | � 0c � /� | Z2 N2 :| �� �� � H| �2 �2 Ү �+ U} �{ � �c X �� �{ 3 3 �{ � d | �{ D3 @3 �{ d �{ �3 �3 �{ � 0d X �� �{ �3 �3 �{ �3 �3 0d �{ 84 44 � `d � � x4 r4 �{ :� :� Z G� �{ �4 �4 �{ �4 �4 �{ 5 5 � �d |� $� 85 45 \� �3 U} T| '2� �d 3� x5 n5 �{ o� Pe k �� �{ �5 �5 �{ 6 6 Pe �{ 76 56 U| z� z� l � c| a6 _6 :| �� �e s M� H| �6 �6 p� �+ Uv �{ �� �� w �� �{ �6 �6 �{ �6 �6 �{ 7 7 �� �3 �� U| Tv Q0 G� 6 � U0 �� �3 � U1Tv �� 5 T � Q| � S6 5� T � �� a3 S� U| T} $� a3 k� T| n� S6 �� T P� �� a3 �� U| Tv �� a3 U} Tv � j: U �� T �Q4R �� ګ j: U �� Tv Q3R �� � >� 5 !.� � Kh �� �< K��� � L h � Ns % O � Ps "� c F2 *h � �< *yh B) ,Y [E ,)� S? ,@h � 4"Y � 5 h n0 A� � �h � �< ���� =% ��h � � h 3 �s ! � h E3 � h O3 � h � � h p3 � ) � �s % � � �s "= "� #� -% �h tmp �h � ��� (�, gh 0� K �� �< goh H7 27 B) iY G8 78 [E i)� #9 �8 S? i@h �: �: =% n h �< {< � r"Y g= == + s I ��� ts �? �? % u k@ ]@ � vs -A A � w h �A �A *�> �>� *X ��� *� ��� *� ��� �: Q �( �>� ��n0 �� ;B 3B �; � � �� �B �B �B t� 2i �� @C <C � �� �B �%'� xC vC � �C �C � �C �C � �C �C � �C �C �B 4� �C �C A� D D ӡ 5 T � Q _� R g� X1Y ^� �z � �< �� �z _D ]D U| � � �c| �D �D O� � = � �� �D �D ɔ �D �D �� /E %E �� �E �E �� *F F �� �F �F {� QG GG n� �G �G a� �H �H �{ � > {!�� �{ �I �I �{ �I �I > �{ �I �I 7ݔ 0> |A� � W� J� =� 0� #� � �� � 0> d� J J q� �J �J ~� &�� %�� � �� �> � �� �J �J �� �? �� �� ��̕ %K !K ٕ @ �� ޕ ]K [K �z ޡ p@ T'�z �K �K U| ޡ �@ �c| �K �K �� �� �@ Q?� �K �K 2� L L %� � ZL VL � �L �L p| �� �� � C� �| �| M �L � ٝ }� U��~T Q~ R��X _� 5� � U��~T Q~ R��X _� '�� �@ �� %M #M �z r� A N%�z JM HM U| r� 0A �c| oM mM 9� 5 T �� Q _� O� k� `A p �� �M �M ɔ �M �M n� �M �M �� 8N 4N �� �N �N �� �N �N �� �N �N {� :O 6O a� |O vO �� k� `A � � �O �O �� P P � OP MP � zP tP ֖ �P �P ɖ Q Q �� IQ CQ `A � �Q �Q $� R R 1� yR mR &>� G� �A � H� S �R U� 'S #S b� cS ]S U| �� �A � � c| �S �S ٢ "4 � Uv �� 25 q� �� �� � � � H�� _� ��� �S �S �� T T � -T +T �� ���� ��͗ B � Η TT PT 'ۗ @B ܗ ��� �T �T �� � �B �� ?� �T �T 2� U U %� ^U ZU � �U �U � �U �U p| � � � 2 �| �| (V &V %� ٝ c T Q~ R} X _� p� � T Q~ R} X _� V� 5 T �� Q _� ʣ �3 Uv Ts Q| R0 p� �4 Uv �z m� C ��z OV MV U| m� m� �c| tV rV �C � �+ �� �V �V | Ȟ �C �| �V �V :| G� G� � H| 'W %W V� �+ Fp� @ L �+ �� NW JW | �� �G � | :| �� H � H| �� �+ Us � �� PC � '� �W �W � �W �W � �W �W � �W �W � �W �W PC 4� X X A� ;X 9X Ȟ 5 T � Q _� R g� X1Y ^� � �� D � � -� kX gX � �X �X D :� �X �X G� T� �Y rY a� �Z �Z n� +[ [ {� "\ \ �� �\ �\ �� l] `] �� ^ �] �� �^ �^ %�� p� %� x� U| �� E � c| L_ J_ �{ ʟ ʟ �V �{ q_ o_ �{ �_ �_ �{ �_ �_ p| � � � � �| �| �_ �_ � @E e � ` ` U| � � �� c| D` B` U| � � � c| i` g` '� pE � �` �` :| � pE �H| �` �` �� �+ Uv � �E � � ��| L� F �� | a a :| L� �F � H| Ta Pa �� �+ U~ :| R� �F � H| �a �a � �+ U| :| ]� �F �W H| �a �a �� �+ U E� � � U T��Q2,�� 0 p� � Uv T��Q ���������,�� 0 U| � � �� c| | +� G C | b �a :| +� �G � H| Rb Nb �� �+ Uv � 3 [ Ts #� 93 s Ts Z� j: U @� T| QDR � � j: U @� Tv Q@R � �@ s k �< ��� �h U �h � s 3 h � s % ! � "s "� M"= Q �# � s � �< �kh B) ��h S? ��h � h U � h [E � � � �"Y + � �� � �s % � � �s � �s "�> "X "� "� #y �( �� n0 �� � �� i �� #� �+ � �+ � � � 5 !� �* _h � � _ih =% _h � ` h 3 bs ! c h E3 d h O3 e h � f h p3 g ) � hs % i � js "� �"= �#� c �� �< � �h �< #� -% �h tmp �h #� � ��� tmp �h (�= h 0� �� � [h �b �b B) Y \c Lc [E )� :d d S? @h f �e =% h �g �g � "Y i �h + I ��� s zk lk % ! 'l l � "s �l �l � # h �m �m *�> MF� *X I�� *� K�� *� T�� �j . �( />� ��n0 0� �m �m l � � ;� �n }n ps ^ 2i =� =o 5o � �� �s >%'� �o �o � �o �o � �o �o � �o �o � �o �o �s 4� p p A� >p :p � 5 T � Q �� R g� X1Y ^� �z � m 5� �z �p �p U| � � �c| �p �p O� � Pm < �� �p �p ɔ �p �p �� lq `q �� 0r $r �� �r �r �� vs js {� t t n� �t �t a� �u �u �{ � Pn {!� �{ �v �v �{ �v �v Pn �{ �v �v 7ݔ �n |/ � W� J� =� 0� #� � �� � �n d� w w q� �w �w ~� &�� %�� � �� @o �� �w �w �� �o � �� ��̕ 2x .x ٕ `p � ޕ jx hx �z �� �p T'�z �x �x U| �� �p �c| �x �x �� ɷ q Q?� �x �x 2� 'y #y %� � gy cy � �y �y p| ɷ ɷ � - �| �| z z �� ٝ i U��~T��Q R��X �� )� � U��~T��Q R��X �� '�� 0q �� 2z 0z �z r� pq N%�z Wz Uz U| r� �q �c| |z zz A� 5 T �� Q �� O� v� �q p �� �z �z ɔ �z �z n� �z �z �� z{ t{ �� �{ �{ �� 5| -| �� �| �| {� �| �| a� I} A} �� v� �q � � �} �} �� �} �} � g~ a~ � �~ �~ ֖ ɖ r l �� � � �q � 0� (� $� �� �� 1� .� "� &>� G� r � H� �� �� U� ܁ b� � � U| �� @r � � c| f� d� ݹ "4 � Uv � 25 q� "� pr � � �� �� �� �� ق Ղ �� '� #� � g� c� pr �� ���� ��͗ �r � Η �� �� 'ۗ �r ܗ ��� � � �� �� 0s �y ?� � � 2� k� g� %� �� �� � �� �� � 9� 5� p| �� �� � �| �| u� s� �� ٝ I T��~Q R} X �� '� � T��~Q R} X �� � 5 T �� Q �� X� �3 Uv Ts Q| R0 {� �4 Uv �z u� �s C�z �� �� U| u� �s �c| �� �� Pt � �+ N� � � | ŵ �t O| :� 6� :| O� O� � H| t� r� ^� �+ @z ) �+ X� �� �� | �� pz Y | :| �� �� � H| �� �+ Uv � �� t J� '� ׆ ӆ � � � � � � � � � � 5� 3� t 4� c� a� A� �� �� ŵ 5 T � Q �� R g� X1Y ^� � �� �t U � � �� �� � K� =� �t � �� � � � �� �� NJ �� �� u� � Ȍ + �� � 8 e� W� E � � R ˏ �� &_ &h U| �� �u l� c| m� k� q v ( i� ?� pv � �� �� �� �� �� {� � � pv �� � � �z � �v � �z O� M� U| � � �c| t� r� i� p� p� �� �� �� �� Ǒ ő {� �� � �� u� V2 }� � U} K� ^2 T} �� � p� �� �v �� �� � � �� X� R� �v �� �� �� < � � U| �� ;2 :| #� w �� H| �� � �� �+ U| | � `w �1 | 0� ,� :| � �w � H| j� f� h� �+ U| p| ,� ,� � k �| �| �� �� � x } � ��| h� px �� | ɓ œ :| �� �x � H| � � � �+ U :| h� �x � H| )� %� �� �+ U~ e� � U U} T��Q ���������,�� 0 � � U~ T��Q2,�� 0 � y � � :| �� y � H| �� �+ Uv U| �� Py �� c| a� _� | �� �y �L | �� �� :| �� �y � H| �� � �+ U| | � � �� | �� �� � �y V � "� � U| �� �� �� c| Z� X� U| �� �� � c| � }� '� z � �� �� :| �� z �H| � ܕ � �+ U} G� j: U 0� Q3R � � j: U 0� Tv Q1R � ^% �h � � �hh =% �~h � � h 3 �s ! � h E3 � h O3 � h � � h p3 � ) � �s % � � �s "� �"= �#� c �� �< � �h �< #� -% �h tmp �h #� � ��� tmp �h (c Mh @� ��3 � MZh &� � B) OY � ږ [E O)� ȗ �� S? O@h �� � =% T h y� c� � X"Y �� i� + Y I ��� Zs � �� % [ �� �� � \s w� i� � ] h � � *�> �V� *X ��� *� ��� *� ��� �z 8+ �( i>� ��n0 j� v� h� | �* � u� � � p� h# 2i w� ˢ â � ¿ �� x%'� +� )� � P� N� � P� N� � P� N� � v� t� �� 4� �� �� A� ̣ ȣ � 5 T � Q �� R g� X1Y ^� �z � } o�# �z � � U| � � �c| 7� 5� O� (� P} v �� f� Z� ɔ f� Z� �� �� � �� �� �� �� P� @� �� � �� {� �� �� n� H� 8� a� D� .� �{ (� P~ {!�$ �{ -� +� �{ U� S� P~ �{ z� x� 7ݔ �~ |9' � W� J� =� 0� #� � �� � �~ d� �� �� q� 5� 3� ~� &�� %�� *� �� @ ' �� `� X� �� � �& �� ��̕ �� �� ٕ `� �% ޕ �� �� �z � �� T'�z � � U| � Ѐ �c| B� @� �� پ � Q?� i� e� 2� �� �� %� � �� � � 9� 1� p| پ پ � 7& �| �| �� �� � ٝ s& U��~T��Q R��X �� 9� � U��~T��Q R��X �� '�� 0� �� �� �� �z �� p� N%�z � � U| �� �� �c| � � Q� 5 T �� Q �� O� �� �� p �� 3� -� ɔ 3� -� n� �� � �� � � �� r� l� �� ï �� �� %� � {� }� w� a� װ ϰ �� �� �� � � 9� 3� �� �� �� � �� � � F� >� ֖ �� �� ɖ � �� �� Z� R� �� � �� �� $� ,� $� 1� �� �� &>� G� � �( H� C� A� U� j� f� b� �� �� U| �� @� � �( c| � � � "4 �( Uv � 25 q� 2� p� � �* �� � � �� g� c� �� �� �� � �� � p� �� ���� ��͗ �� �* Η /� +� 'ۗ � ܗ ��� s� o� �� �� 0� ��* ?� �� �� 2� �� �� %� 9� 5� � �� �� � Ǹ ø p| �� �� � * �| �| � � �� ٝ S* T��~Q R} X �� 7� � T��~Q R} X �� � 5 T �� Q �� h� �3 Uv Ts Q| R0 �� �4 Uv �z �� Ѓ }�z *� (� U| �� � �c| O� M� P� �+ �+ �� x� r� | ռ �� �| ȹ Ĺ :| _� _� � H| � � n� �+ @� 3, �+ �� )� %� | �� p� � | :| �� �� � H| ʾ �+ Uv � �� � ��, '� e� a� � �� �� � �� �� � �� �� � ú �� � 4� � � A� � � ռ 5 T � Q �� R g� X1Y ^� � �� �� � �3 � M� C� � ٻ ˻ �� � �� v� � K� 3� U� E� !� � ( p� V� 5 �� }� B � � O �� �� \ Y� K� &i &r U| �� Ѕ ��- c| �� �� { � 2/ i� O� p� �$/ �� "� � �� P� N� {� ~� |� p� �� �� �� �z �� �� �. �z �� �� U| �� �� �c| � � i� �� �� / �� '� %� �� U� S� {� �� �� �� �� V2 �� � U} [� ^2 T} �� � p� � � ��/ �� �� �� �� �� �� � �� 5� /� <� �/ U| �� ;2 :| 3� � ��/ H| �� �� �� �+ U| | /� `� �;0 | �� �� :| /� �� � H| �� �� x� �+ U| p| <� <� � u0 �| �| 0� .� � � �1 � ��| x� p� ��0 | W� S� :| � �� � H| �� �� � �+ U :| x� � �*1 H| �� �� �� �+ U~ u� � _1 U} T��Q ���������,�� 0 � � U~ T��Q2,�� 0 � � �1 � :| �� � � H| �� �+ Uv U| �� P� ��1 c| �� �� | �� �� �V2 | � � :| �� �� � H| P� L� *� �+ U| | /� /� ��2 | �� �� � � `3 � �� �� U| � � ��2 c| �� �� U| � � �3 c| � � '� � � 4� 0� :| � � �H| n� j� � �+ U} W� j: U `� Q-R � �� j: U `� Tv Q+R � I@ � h �4 � � lh =% � �h � � h 3 � s ! � h E3 � h O3 � h � � h p3 � ) � � s % � � � s "� ."= 5#�4 c � � �< � � h �< #�4 -% � h tmp h #�4 � �� tmp h (R" � h P� ��G � � ^h �� �� B) � Y x� h� [E � )� V� ,� S? � @h 7� � =% � h � �� � � "Y #� �� + � I ��� � s �� �� % � C� 5� � � s � �� � � h �� �� *�> � f� *X � �� *� � �� *� � �� �� B? �( � >� ��n0 � � � �� � �> � � � �� �� p� r7 2i � � Y� Q� � �� �� � %'� �� �� � �� �� � �� �� � �� �� � � � �� 4� 2� 0� A� Z� V� � 5 T � Q �� R g� X1Y ^� �z #� � � �7 �z �� �� U| #� #� �c| �� �� O� 8� P� � �� �� �� ɔ �� �� �� �� |� �� L� @� �� �� �� �� �� �� {� 2� &� n� �� �� a� �� �� �{ 8� P� {!�8 �{ �� �� �{ �� �� P� �{ � � 7ݔ �� |C; � W� J� =� 0� #� � �� � �� d� 9� -� q� �� �� ~� &�� %�� :� �� @� ; �� �� �� �� � �: �� ��̕ N� J� ٕ `� �9 ޕ �� �� �z � �� T'�z �� �� U| � А �c| �� �� �� �� � Q?� �� �� 2� C� ?� %� � �� � � �� �� p| �� �� � A: �| �| )� '� � ٝ }: U��~T��Q R��X �� I� � U��~T��Q R��X �� '�� 0� �� N� L� �z �� p� N%�z s� q� U| �� �� �c| �� �� a� 5 T �� Q �� O� �� �� p �� �� �� ɔ �� �� n� � � �� �� �� �� � �� �� Q� I� �� �� �� {� � � a� e� ]� �� �� �� � � �� �� �� � � � �� }� � �� �� ֖ 6� 0� ɖ �� �� �� �� �� �� � L� D� $� �� �� 1� J� >� &>� G� � �< H� �� �� U� �� �� b� 4� .� U| �� @� � �< c| �� �� �� "4 �< Uv � 25 q� B� p� � �> �� �� �� �� �� �� �� C� ?� � �� � p� �� ���� ��͗ �� �> Η �� �� 'ۗ � ܗ ��� � �� �� �� 0� ��> ?� ;� 7� 2� �� �� %� �� �� � � � � U� Q� p| �� �� � *> �| �| �� �� �� ٝ ]> T��~Q R} X �� G� � T��~Q R} X �� � 5 T �� Q �� x� �3 Uv Ts Q| R0 �� �4 Uv �z �� Г � �z �� �� U| �� � �c| �� �� P� �? �+ � � � � | �� �� � | V� R� :| o� o� � H| �� �� ~� �+ @� =@ �+ � � �� �� | �� p� � | :| �� �� � H| �� �+ Uv � �� � � A '� �� �� � +� )� � +� )� � +� )� � Q� O� � 4� � }� A� �� �� �� 5 T � Q �� R g� X1Y ^� �3 �� �� � �G �3 �� �� �3 g� Y� �� �3 � � �3 4 �� �� 4 �� �� %4 �� �� 24 �� �� ?4 � � L4 �� s� Y4 -� � f4 � � &s4 &|4 U| �� Е � �A c| �� �� �4 � <C i� _� p� � .C �� �� �� �� � � {� � � p� �� 3� /� �z � �� �B �z k� i� U| � � �c| �� �� i� �� �� C �� �� �� �� � � {� � � �� �� V2 �� � U} k� ^2 T} �� � p� � � � �C �� 8� 4� �� t� n� � �� � �� <+� �C U| �� ;2 :| C� � � �C H| � � �� �+ U| | ?� `� 1ED | L� H� :| ?� �� � H| �� �� �� �+ U| p| L� L� � D �| �| �� �� �4 � �E �4 ��| �� p� �D | � � :| � �� � H| � � &� �+ U :| �� � 4E H| E� A� �� �+ U~ �� � iE U} T��Q ���������,�� 0 � � U~ T��Q2,�� 0 �4 � �E �4 :| �� � H| �� �+ Uv U| �� P� !�E c| }� {� | �� �� 6`F | �� �� :| �� �� � H| � � :� �+ U| | ?� ?� /�F | � � �4 � jG �4 >� :� U| �� �� � �F c| v� t� U| �� �� G c| �� �� '�4 � �4 � �� :| �� � H| �� �� (� �+ U} g� j: U �� Q(R � � j: U �� Tv Q&R � �. G h iH � G eh =% G {h � H h 3 J h ! K s E3 L h � M s % N � O s "� q "= v ( � h `� � ��[ � � Wh B� 2� B) � Y � �� [E � )� � �� S? � @h 4 =% h � � "Y p : + I ��~� s l ^ % � s � � � h w *�> 5 V� *X 1 �� *� 3 �� *� < �� �� �R �( >� ��n0 � � � � ZR � # � T D @� �J 2i % � � � �� p� & %'� 8 6 � ] [ � ] [ � ] [ � � � p� 4� � � A� � � �� 5 T � Q �� R g� X1Y ^� �z 3� � 7K �z U| 3� 3� �c| D B O� H� � $ �� s g ɔ s g �� � �� � � �� �� � � {� t h n� a� � �{ H� � {! L �{ � � �{ % # � �{ J H 7ݔ P� |�N � W� J� =� 0� #� � �� � P� d� { o q� ~� &�� %�� *� �� � �N �� 0 ( �� �� N �� ��̕ � � ٕ 0� "M ޕ � � �z �� �� T'�z � � U| �� �� �c| �� �� Р Q?� 9 5 2� � � %� � � � � p| �� �� � �M �| �| k i � ٝ �M U��~T~ Q R��X �� �� � U��~T~ Q R��X �� '�� � �� � � �z �� @� N%�z � � U| �� P� �c| � � Q� 5 T �� Q �� O� =� �� p �� � ɔ � n� W O �� � � �� > < �� k c �� � � {� % a� w �� =� �� � � � � �� 3 - � � � � � � ֖ ( " ɖ � z �� � � �� � > 6 $� � � 1� < 0 &>� G� С \P H� � � U� � � b� & U| `� � � 6P c| t r �� "4 NP Uv �� 25 q� l� @� � AR �� � � �� � � �� 5 1 � u q @� �� ��~�� ��͗ p� R Η � � 'ۗ �� ܗ ��� � � �� �� � ��Q ?� - ) 2� y u %� � � � � G C p| �� �� � �Q �| �| � � �� ٝ �Q T~ Q R} X �� i� � T~ Q R} X �� &� 5 T �� Q �� �� �3 Uv Ts Q| R0 B� �4 Uv �z �� �� + �z � � U| �� �� �c| � � � 3S �+ 6 � � � | �� P� 7 | H! D! :| _� _� � H| �! �! n� �+ F�� 9 �S �+ @ � �! �! | �� �� A | :| �� � � H| �� �+ Us � �� У 2 pT '� �! �! � " " � " " � " " � B" @" У 4� p" n" A� �" �" �� 5 T � Q �� R g� X1Y ^� �G �� �� = c[ �G �" �" �G Z# J# �� �G $ $ H �$ �$ H "H 1% #% /H �% �% <H �& v& IH 6' (' %VH m� %_H �� p| �� �� \ QU �| �| �' �' r� �� P� \ [ �� ( �' P� �� �( �( %�� `� ,z "� � �U >z 2) .) � Kz n) l) Xz �) �) >� �� Us 7x � � OZ Ix �) �) )Vx � * �V Wx �) �) bx ��)� �1 kV Us T�� 9� �� Us qx x� P� � :Z �x P� �x %* * �x �* �* �x ���x + �* �x �+ �+ �x �- �- �x N. J. %�x ,� y �� �� � �W Py �. �. Cy �/ �/ 6y �0 �0 )y �1 �1 �� ]y i2 %2 jy b7 ,7 wy f: P: �y M; G; &�y �x � KX �x ��7�y @� �*X �y �y �y �; �; �y �y @� �y R< << �y 9= 5= &z 'z p� z u= o= z �= �= �� �1 U~ T��Q0 �� 5� �� � �X �� �� ȓ > > )Փ L� 1 �X ֓ A> => :| U� � � H| {> y> l� �+ :� g1 Us y � �Y y �> �> 7�y @� ��Y �y �y �y ? ? �y �y @� �y g? S? �y :@ 6@ &z 'z p� z v@ p@ z �@ �@ �� �1 t� �1 �Y U��~T��Q0 �� }1 �Y U��~ � }1 �� P1 �� P1 g� P1 �� P1 �� 25 � P1 b� P1 (� �1 Us fz F� F� �Z xz A A �z FA @A �z �A �A V� �� Us Ts S� 25 e� �1 � 2 �Z Us G� %2 Us U| �� �� a -[ c| �� j: U � T \ QKR � � j: U � Tv QJR � �2 � h 1\ � � ch =% � yh � � h 3 � h ! � s E3 � h � � s % � � � s "� � "= � (�$ i h � � ��i � i Uh �A �A B) k Y �B }B [E k )� _C AC S? k @h �D �D =% p h GF 7F � t "Y G �F + u I ��� v s �H �H % w �I }I � x s MJ ?J � y h �J �J *�> � v� *X � w� *� � �� *� � �� � �f �( � >� ��n0 � � ]K SK P� 3f � � � �K �K � �^ 2i � � sL oL � �� 0� � %'� �L �L � �L �L � �L �L � �L �L � �L �L 0� 4� $M "M A� LM HM � 5 T � Q �� R g� X1Y ^� �z �� @� � �^ �z �M �M U| �� �� �c| �M �M O� � p� � �� �M �M ɔ �M �M �� JN BN �� �N �N �� <O .O �� �O �O {� IP AP n� �P �P a� �Q �Q �{ � P� {!�_ �{ tR rR �{ �R �R P� �{ �R �R 7ݔ �� |vb � W� J� =� 0� #� � �� � �� d� �R �R q� |S zS ~� &�� %�� J� �� @� Lb �� �S �S �� � �a �� ��̕ T T ٕ `� �` ޕ ?T =T �z � �� T'�z dT bT U| � Ю �c| �T �T �� �� � Q?� �T �T 2� �T �T %� � <U 8U � �U xU p| �� �� � ta �| �| �U �U .� ٝ �a U��~T��Q R��X �� �� � U��~T��Q R��X �� '�� 0� �� V V �z b� p� N%�z ,V *V U| b� �� �c| QV OV q� 5 T �� Q �� O� /� �� p �� xV tV ɔ xV tV n� �V �V �� W W �� fW bW �� �W �W �� �W �W {� /X +X a� qX kX �� /� �� � � �X �X �� �X �X � FY BY � �Y |Y ֖ �Y �Y ɖ Z Z �� QZ KZ �� � �Z �Z $� [ [ 1� �[ u[ &>� G� � (d H� \ \ U� /\ +\ b� k\ e\ U| P� � � d c| �\ �\ �� "4 d Uv �� 25 q� � � � f H�� �� ��� �\ �\ �� ] ] � 5] 3] �� ���� ��͗ P� �e Η \] X] 'ۗ �� ܗ ��� �] �] �� �� �� ��e ?� �] �] 2� &^ "^ %� f^ b^ � �^ �^ � �^ �^ p| �� �� � ge �| �| 0_ ._ �� ٝ �e T��~Q R} X �� � � T��~Q R} X �� �� 5 T �� Q �� H� �3 Uv Ts Q| R0 4� �4 Uv �z �� `� � �z W_ U_ U| �� �� �c| |_ z_ б g �+ � � �_ �_ | �� � � | �_ �_ :| � � � H| /` -` �� �+ F�� < �g �+ � � V` R` | �� в � | �` �` :| �� � � H| �` �` �� �+ Us � w� �� � Yh '� �` �` � a a � a a � a a � 9a 7a �� 4� ga ea A� �a �a �� 5 T � Q �� R g� X1Y ^� �[ �� @� � {i �[ �a �a �[ ,b &b @� �[ }b ub �[ �b �b �[ �[ 8c .c �[ �c �c \ d d \ �d �d % \ �� %'\ �� U| �� �� � -i c| �� :1 Ei Us � j: U �� T � QHR � �� j: U �� Tv QGR � �& h <j � jh =% �h � h 3 s ! h � s % � s "= R "� N (7C � h � ' �7x � � ]h �d �d B) � Y �e �e [E � )� �f sf S? � @h �g �g =% � h :i *i � � "Y j �i + � I ��� � s �k �k % � Jl <l � � s m �l � � h �m �m *�> � �� *X � w� *� � �� *� � �� @� �t �( � >� ��n0 � � n n p� >t � � � �n �n � �l 2i � � o o � � P� � %'� Uo So � zo xo � zo xo � zo xo � �o �o P� 4� �o �o A� �o �o S� 5 T � Q �� R g� X1Y ^� �z �� `� � m �z <p :p U| �� �� �c| ap _p O� � �� � �� �p �p ɔ �p �p �� �p �p �� |q tq �� �q �q �� nr fr {� �r �r n� Rs Fs a� t t �{ � p� {!�m �{ �t �t �{ �t �t p� �{ $u "u 7ݔ �� |�p � W� J� =� 0� #� � �� � �� d� Uu Iu q� �u �u ~� &�� %�� j� �� `� Wp �� v v �� � �o �� ��̕ jv fv ٕ �� �n ޕ �v �v �z ^� � T'�z �v �v U| ^� � �c| �v �v �� � � Q?� w w 2� _w [w %� � �w �w � �w �w p| � � � o �| �| Ex Cx N� ٝ �o U��~T��Q R��X �� 4� � U��~T��Q R��X �� '�� P� �� jx hx �z b� �� N%�z �x �x U| b� �� �c| �x �x �� 5 T �� Q �� O� �� й p �� �x �x ɔ �x �x n� y y �� }y yy �� �y �y �� z �y �� Rz Nz {� �z �z a� �z �z �� �� й � � !{ { �� ]{ Y{ � �{ �{ � �{ �{ ֖ 2| .| ɖ r| n| �� �| �| й � } �| $� q} k} 1� �} �} &>� G� � 3r H� k~ i~ U� �~ �~ b� �~ �~ U| �� @� � r c| �� "4 %r Uv �� 25 q� L� L� � � %t H�� �� ��� A ? �� p n � � � �� ���� ��͗ p� �s Η � � 'ۗ �� ܗ ��� � � �� �� � ��s ?� =� 9� 2� �� �� %� ɀ ŀ � � � � W� S� p| �� �� � rs �| �| �� �� �� ٝ �s T��~Q R} X �� 7� � T��~Q R} X �� � 5 T �� Q �� �� �3 Uv Ts Q| R0 �� �4 Uv �z �� �� � �z �� �� U| �� �� �c| ߁ ݁ � u �+ � � � � | �� 0� � | X� T� :| �� �� � H| �� �� �� �+ F�� B �u �+ � �� �� | �� � | :| �� @� � H| � �+ Us � w� �� � Tv '� � � � ,� *� � ,� *� � ,� *� � R� P� �� 4� �� ~� A� �� �� �� 5 T � Q �� R g� X1Y ^� �i �� `� � x �i ҃ �i 0� *� `� �i �� � �i � � �i =� 5� j �� �� j � � j }� u� %)j �� %2j �� �6 �� м 9 Fw �6 � ߆ м �6 #� � �� #1 Us U| �� �� > sw c| U| �� �� ; �w c| U| u� u� % �w c| � j: U (� T 9 QER � �� j: U (� Tv QBR � �> � � qx obj �@h s � �� ( �� y obj �=h � � � v, � end � � " �� �� �< �z i0 �~ "� �#y . �g . �� �; R� �y i0 R=~ �< RGs " RX� Rj� � S s chr T n � U n �A V s "� � ^ ? ,z i0 ??~ �< ?Oz $ ?[� " ?n� end ?�� % @ s i A� "� O chr Dn �) E s � - � fz obj -Bh . � T /� � �z obj >h ! � T "� � � h �z obj �7h cF* & s l �"h �z � �J � �h ;9 �s 5{ &$ �<h key �Lh e �\� � !h o{ &$ Ch � Sh res h �7 � h �{ �" �Ih e� <� �{ fn <) 3B {s �{ op {+h 5 ms | O m! � m55 � o5 4v � | op �*h 4�C �:| op �*h 4 �U| op �h 4R �p| op �)h e�2 s �| fob /�| ~O G�| % .Us �l � } Hgs UHss T�s �� ~� U| �l �l �!c| �� �� .p� 0o �y} �� Ї ȇ �� :� 2� �� �� �� LBo k} U�UT�T UMo ;2 .�a �t � �� �a � ؈ b c� W� b �� � )4b �t �} 9b �� � )Zb �t ~ _b �� �� )}b �t 0~ �b ˊ Ɋ �a �t � �# b � � b F� @� �a �� �� )�b �t �~ �b ы ϋ `�t v T| )�b �t �~ �b �� � ;�t T| )�b �t �b � � ;u T| )�b u M �b @� >� ;u T| )�b &u � �b e� c� ;+u T| )�b ;u � c �� �� ;@u T| 'c � c Pd[u �TT�Q .}y �I B �� �y �� �� �y � � �y n� f� �y ҍ Ѝ �{ �I � � �� �{ �� �� �{ �I � | �{ � � �{ E� C� �{ k� i� }y �I �I � � �y �� �� �y �� �� �y �� �� �y J 5 .�] Pv � ��� �] U� /� �] � ߐ �] �� �� ^ ^ *� � ^ �� �� V^ �v 0 s$� �^ L� F� u^ �� �� h^ � �� 0 �^ >� <� �^ ^?�v �^ U�UQ�TR�Q �] �v p M$m� �] l� b� �] � ۗ �] �� �� p ^ � � ^ ^ ',^ p -^ V� R� :^ �� �� G^ '� � :| �v � q$ �� H| �� �� 8w �+ U} :| y j$ � H| � � ey �+ U} �v 0 � U~ T1 �v �/ %� U~ T0 �v �^ O� Uv T~ Q} R| Cy 5 T `� �v w 0 T$�v -� � �v � ޛ �v �� q� �v �� �� �v � � 0 w �� �� w _w � `! �� \w j� `� Ow � ߟ Bw Y� G� 6w 7� 3� )w }� q� � hw � � uw �� �� �w *� � �w �� � �w v� n� �w ���w ޤ Ԥ �w ���w ���w W� Q� �w �� �� %�w �x U| ex � 8! � c| � � U| nx nx 9! &� c| 4� 2� :| �x H!c� H| [� W� oy �+ Us :| y y J! �� H| �� �� y �+ hw �1 ą U ��~ "3$ �w 6 ޅ U��~ �x �3 � U| T Qv R} g�x ��5� Uv T} Q R��~ Xy }1 M� U} �y �/ �y }1 r� U} �y S6 T "� G&w U�UR0 .�k �y } �l� �k Ħ �� �k U� O� �k �� �� �{ �y �y �"9� �{ :� 8� �{ b� `� �{ �� �� | �y P �"�� -| �� �� U| �y �y � c| ר ը �k � � �k �� �� | z � �"| 8� 4� :| z � � H| r� n� (z �+ �k 0z 0z �"�k �� �� �k � � �k &� "� Fz S6 T �� .�m Pz � �� �m k� _� �m � � �m 2� *� U| �z �"ψ c| n @ A� n �� �� | �z � �"| ҫ Ϋ :| �z � � H| � � �z �+ �{ �z �z �"�� �{ D� B� �{ l� j� �{ �� �� �m �z �z |"�� �m �� �� �m �� � �m � � �z S6 T �� �z �0 T �� Q1 .p �z � �ʋ #p b� V� /p � � <p )� !� U| +{ � ^"~� c| Ip � Jp �� �� | ={ P `"| ɮ Ů :| B{ � � H| � �� ]{ �+ �{ `{ `{ W"?� �{ ;� 9� �{ c� a� �{ �� �� p m{ m{ S"�� #p �� �� /p � � <p � � �{ S6 T X� +{ �0 T �� Q1 .�q �{ � �|� �q ]� M� r !� � r � ձ �{ �{ �{ " [� �{ �� �� �{ ò �� �{ � � U| �{ � "�� c| � � !r � �� "r :� 6� | �{ !"| t� p� :| �{ P � H| �� �� �{ �+ �q | | "`� �q � � r %� !� r b� ^� | S6 T � �{ S6 T � . s | h �� s �� �� +s >� 2� 8s յ ɵ �{ )| )| �! � �{ b� `� �{ �� �� �{ �� �� U| 6| � �!6� c| ڶ ض Es � �� Fs � �� | B| � �!| ;� 7� :| G| � H| u� q� `| �+ s h| h| �! s �� �� +s � � 8s )� %� ~| S6 T H� .�s �| h ��� �s n� b� �s � �� �s �� �� �{ �| �| �! �� �{ )� '� �{ Q� O� �{ w� u� U| �| P �!ɏ c| �� �� �s � ;� �s Ⱥ ĺ | �| � �!| � �� :| �| � � H| <� 8� �| �+ �s �| �| �!�s v� r� �s �� �� �s � � �| S6 T x� . 7 !J �V� .7 /� )� ;7 |� x� H7 �� �� U7 � � o7 \� X� |7 �� �� �7 ս Ͻ P�7 P�7 �7 #� � �7 _� [� %�7 K b7 �� �� )�7 yJ �� �7 �� �� U| �J �J * c| � � :| K K I*�� H| � � K �+ U~ cJ 6 � U�� �J ?/ 9� U��T~ Q~ K �. R �X0 .�| )K G � � } 2� .� E} �� } m� k� %)} kK Q} )2} ]K � 3} �� �� I>} ]K ?} Q U| aK ] c| <K �0 U1 . pK S �� ҿ ̿ , $� � F v� p� S � �� P` &m 9 � � | �K P � � | 8� 6� :| �K � � H| ]� [� �K �+ Uv �K >5 �K d0 U} Qv R~ X| .US �K � �� gS �� �� sS � � �S (� $� �S f� `� �S �� �� �S � � �S \� V� Q�S �h �K � `%ǖ �h �� �� "i �� �� i �� �� i � � �h A� ;� �h �� �� �h �� �� �h �� �� � /i 1� '� | +L +L w#�� -| �� �� U| 0L 0L � c| �� �� U| KL KL |#ƕ c| �� �� U| jL jL �#�� c| � � | nL nL �#a� -| :� 8� U| sL sL � c| _� ]� :| &M &M �# �� H| �� �� 4M �+ U| &M S6 T F� �K �, AM �, U| .S� } ' ��� e� �� �� r� v� h� � $� � �� �� �� �� �� �� �� v� l� %�� �} &�� %Ř �} �{ } | �� �{ �� �� �{ � � �{ 5� 3� Θ 0 � Ә c� ]� ]} �4 T Q2 � � "� � �� �� �} �4 T Q2 �� �} �} ��� ӛ �� �� ƛ � � �} 5 T � Q} R ~ 5 T �� Q} .�8 @~ z �ٝ �8 :� 0� �8 �� �� �{ @~ @~ z) b� �{ � � �{ @~ @~ | �{ (� &� �{ P� N� �{ v� t� �{ Q~ Q~ z) �� �{ �� �� �{ �� �� �{ �� �� �{ ^~ ^~ {) 1� �{ � � �{ ^~ ^~ | �{ 9� 7� �{ a� _� �{ �� �� �{ t~ t~ {) �� �{ �� �� �{ �� �� �{ �� �� O9 �~ � |)\� {9 "� � n9 \� X� a9 �� �� �9 �~ � e): �� �� : � � � : L� H� (: -� ): �� �� 4: �� �� AA: �~ O) ^: S: �� �� �8 ' @ ~)|� 9 � � 9 E� A� @ +9 �� {� 69 �� �� 'A9 � B9 � � O9 s � r)�� {9 X� T� n9 �� �� a9 �� �� �9 s e): � � : B� >� : |� x� OA: �~ O) {� ^: S: �� �� I(: � ( ): �� �� 4: � � �{ ] ] q) .� �{ 9� 7� �{ ] ] | �{ ^� \� �{ �� �� �{ �� �� �{ j j q) �{ �� �� �{ �� �� �{ #� !� �{ })˝ �{ J� H� �{ r� p� �{ �� �� U ~2 .� � G �� � �� �� � �� y� � J� :� *� � �� 7� h� `� D� �� �� Q� K� A� &^� %g� \� p� 0 �� u� �� �� �� *� � E=�� � � �� L� F� � �� �� �� ʙ �� �� י 4� 0� � l� j� �� �� �� � �� �� �� �� �� �� ]�� �� �� �� 9� 1� �� �� �� ʙ �� �� י 5� 1� � m� k� X� �� �� \� \� o� ӛ �� �� ƛ �� �� |� 5 T � Q��R| � �4 .j� � o ��� |� �� �� �� 8� � �� k� Q� �� �� �� Q�� �{ � S�� �{ � � �� P Z� �� 9� 7� ˚ � � s 5� ݚ d� \� � � �� �� �� =� ;� � c� a� �{ � @ D �{ �� �� �{ �� �� @ �{ 3� -� GT� U�UT�TQ�QR0 �9 X� � Z �� �9 �9 �� �� �9 �� �� � �9 "� � )�9 �� / �� �9 \� X� �9 �� �� I�9 �� �9 �� �� OA: �� _) -� ^: S: �� �� A�9 �� Q) �9 �9 �9 �9 AA: �� _)% ^: S: � � �9 � � V �� �9 �9 +� '� �9 w� q� � �9 �� �� )�9 � / ,� �9 � �� �9 :� 8� I�9 � �9 _� ]� OA: �� _) \� ^: S: �� �� A�9 � Q) �9 �9 �9 �9 AA: � _)% ^: S: �� �� e� ^� � ��� �� �� �� �� � � w� g� _� � �� �� �� �� � � s� �2 8� U � g�� s Z� Uv T| Q0 �� �2 O� 25 q� S6 �� T � ?O� �3 U�UQ0 � � P W\� 0� p� n� #� �� �� P =� �� �� J� \W� �� �� o{ � � ?� �{ � � *� �2 U � j� ҆ � R �� �� �� �� ,� (� �� g� e� |� �� �� � �� � ҆ � [0� �� �� #� �� �� � =� �� �� J� #� � W� [� Y� o{ ֆ ֆ D� �{ �� ~� <9� X� U| A� �2 � �2 U � ?� �2 U�UT�TR0 .� � ! ��� � �� �� -� F� :� :� G� �� �� � � ` � ҭ -� � � � �� �� ` :� � � G� p� � � ��� �� h� `� �� �� �� � �� 6� 4� <� �� U�UT�T 5� ;2 T� @� � b� `� Z� T� V� ` } � f� f� �� �� s� � � ` �� �� y� q� �{ d� d� ' t� �{ �� �� �{ �� �� �{ %� #� �8 z� � *j� �8 N� H� �8 �� �� �8 z� � x)�8 �� �� �8 ;� 5� �{ z� z� z) Z� �{ �� �� �{ z� z� | �{ �� �� �{ �� �� �{ �� �� �{ �� �� z) �� �{ #� !� �{ K� I� �{ p� n� �{ �� P! {) � �{ �� �� �{ �� �� | �{ �� �� �{ �� �� �{ � � �{ �� �� {) l� �{ /� -� �{ W� U� �{ |� z� O9 �� �! |)T� {9 �� �� n9 �� �� a9 � � �9 �� �! e): U� Q� : �� �� �! : � � )(: �� , %� ): � �� 4: <� :� AA: �� O) ^: S: a� _� ?� ~2 Tv �� {� �! (�� �� �� �� � �� �! ǝ � �� ҝ a� ]� �8 Ӊ Ӊ �8 �� �� �8 �� �� � �� U�H � � �! ~ �� � �� �� � �� �� � �� �� �� 7� 3� �! ,� u� m� 9� � � F� � � | � 0" L� | Q� M� :| � `" � H| �� �� o� �+ | � �" MI� | � � :| � �" � H| � � y� �+ U} | � � ! N| ?� =� :| � � � H| d� b� 2� �+ Uv E� U3 ? � �2 U�UT�TQ0R1 .^} �O � �.� p} �� �� �} %� � Q}} j~ �O 0# = �� |~ �� �� 0# �~ � � �O _. U~ �} `# �� �} �� � )�} P p � �} v� n� :| &P &P C � H| � � 4P �+ Uv �6 6P 6P . B c� �6 �� �� �6 3� 1� dP #1 U| | jP jP F ݯ | ]� [� :| qP qP � H| �� �� P �+ U| P � Uv :| �P �P L ;� H| �� �� �P �+ Uv :| �P �P M �� H| � � �P �+ U} P � �� U} �P V2 �} �P �# R � �} � � �} � � �# �} �} ]?�P � U�UT0,9 0 �P 25 �P V2 .�i P� _ �;� �i o� g� j � � j k� e� �i f� & �"� �i �i j �� �� & j �z f� & �"�z � � U| f� f� �c| %j �� 0& �"�� 7j 7j 8 0 0& Cj � � %Pj `� �6 �� �& �" � �6 � � �z �� ' B+&² �z U| �� �� � c| �z e� 0' B+ �z U| e� e� � c| 'Yj `' Zj " gj j X tj + % �j � t U| ɐ �' �" o� c| :| � �' �" �� H| + ' �� �+ U| p� �� ( �" � �� k a �� � � ( �� Y S <� � U} Tv �� ;2 :| � @( �" Y� H| � � �� �+ U} �� �0 p� U1 � d0 �� T0Q0R| X0 e� V2 �z �� p( �"!� �z � � U| �� �� �c| :| 9� �( �" H| + ) O� �+ Uv .� �� � �"� � ^ N � � Ƒ �( ��� -� f Z � � � �( :� G� = 7 � � �( � �� -� � � � �( :� > < G� p� � @) �r� �� k a �� � � @) �� <� c� T} U� ;2 T� � p) � p) b� V P T� 5� �) } غ f� f� � � s� �) �� �� o g �{ G� G� ' ;� �{ � � �{ � � �{ �8 ]� P* *1� �8 D > �8 � � �8 ]� `* x)�8 � � �8 1 + �{ ]� ]� z) !� �{ | z �{ ]� ]� | �{ � � �{ � � �{ � � �{ n� n� z) p� �{ �{ A ? �{ f d �{ {� �* {) � �{ � � �{ {� {� | �{ � � �{ � � �{ � �{ �� �� {) 3� �{ % # �{ M K �{ r p O9 �� �* |)� {9 � � n9 � � a9 �9 �� + e): K G : � � + : � � )(: �� � ): � � 4: 2 0 AA: ٓ O) ^: S: W U e� ~2 Tv �� �� 0+ (�� ~ z �� � � 0+ ǝ � � ҝ W S �8 � � �8 � � �8 � � � �� U�H � �� `+ ~ �� � � � � � � � � � �� - ) `+ ,� k c 9� � � F� | ݒ �+ L�� | G C :| ݒ �+ � H| � � �� �+ | � , M� | � � :| � 0, � H| � � �� �+ U~ | �� �� N| 5 3 :| �� �� � H| Z X � �+ Uv #� U3 � �2 T} Q0R1 � (� (� ( �� � } � C� 5 T ;� Q} � 25 .�� � O ��� �� � � �� 0 � � � � � � � [ / P� � � � C� �� 0f D �� U� 0f b� _ Y o� � � |� �� � � %�� � �� � �f Y�� ލ � � � � � э Q ? č �f �� � � &� �{ .� �g P �� �{ � � �{ ! ! �g �{ A! =! �{ 7� �g X � �{ �! ~! �{ 7� h | �{ �! �! �{ h �{ �! �! �{ B� Ph X ]� �{ 6" 2" �{ v" r" Ph �{ �" �" � �h �� � �" �" �{ ^� ^� Z ƿ �{ <# :# �{ d# b# �{ �# �# � �h �� $� �# �# �� �3 U} T| '2� i 3� �# �# �{ �� Pi k Z� �{ a$ _$ �{ �$ �$ Pi �{ �$ �$ U| �� �� l �� c| �$ �$ :| �� �i s � H| % �$ �� �+ Uv �{ Dz Dz w � �{ 8% 6% �{ `% ^% �{ �% �% �� �3 >� U| Tv Q0 i� 6 U� U0 �� �3 r� U1Tv � 5 T � Q| | ߲ �i � � | �% �% :| ߲ ߲ � H| ?& =& � �+ U} ߲ a3 !� U| T} � S6 @� T � � a3 X� T| �� S6 w� T P� s� a3 �� U| Tv Ĵ a3 U} Tv :� j: U � T ZQ2R �� �� �� �� 7 *� �� f& b& �� �& �& � �& �& � ' ' � � � � �� @j @$'� s' m' � �' �' � �' �' � �' �' � ( ( @j 4� =( ;( A� c( a( ճ 5 T � Q �� R g� X0Y �� � �� pj C&�� �( �( � �( �( pj � �P �{ � � 2 !�� �{ E) C) �{ m) k) �{ �) �) :| Q� Q� > �� H| �) �) `� �+ ) � � : k� � �X U| &� &� 8 7� c| �) �) � �4 !� �3 U�HT�XQ�PR0 < � ~� T0 L� 5 T �� Q �� � at least �d4 Z4 1�B �� �B 4 1�B 4 : ;9 I ��1 1R�BUX YW I : ;9 I : ; 9 I8 1R�BUX YW 1 1R�BX YW U ��1 �� 1 4 : ;9 I�B .: ;9 'I 4 : ;9 I 1R�BX YW 4 : ;9 I : ; 9 I 1U I : ;9 I : ;9 I�B 4 1 .?: ; 9 'I< 4 1 U I ! I/ !& I " : ;9 # $ : ;9 I8 % 1 & 1 ' 1U (.: ;9 'I@�B ) 1 * : ;9 + : ;9 I�B ,�� 1�B -'I ..1@�B /.?: ;9 'I< 04 : ; 9 I?< 1 : ; 9 24 : ;9 I�B 3 : ;9 4.: ;9 ' 5 : ;9 I8 6$ > 7 1UX YW 8 : ; 9 9 : ;9 I 8 :.?: ; 9 '< ;�� <�� = : ;9 I > : ; 9 I8 ?���B1 @�� 1 A 1X YW B : ; 9 I8 C( D. ?: ; 9 'I< E F G���B H 1 I 1 J : ; 9 I 8 K : ;9 L���B M.: ;9 'I N : ; I8 O 1X YW P4 1 Q 1 R' S4 : ;9 I?< T : ; 9 I U�� �B1 V : ;9 I W : ;9 I X : ; 9 Y < Z! [> I: ;9 \ : ;9 ] : ;9 I8 ^.?: ;9 '< _. ?: ; 9 '< `���B a.: ;9 '@�B b4 : ;9 I c. : ;9 'I d���B�B e.: ; 9 'I f : ; 9 I g���B h% U i$ > j k I l : ; m& n7 I o : ; 9 p : ; 9 q : ; 9 I r 'I s : ; 9 t : ; 9 I8 u < v4 G;9 w : ;9 x.: ;9 '@�B y.: ;9 'I@ z4 : ;9 I {.?: ;9 'I@�B |4 : ;9 I } : ;9 ~ : ; 9 I 6 �. ?<n: ; �� � lib/sqlalchemy/cyextension /opt/_internal/cpython-3.9.20/include/python3.9 /opt/_internal/cpython-3.9.20/include/python3.9/cpython /opt/rh/devtoolset-10/root/usr/lib/gcc/x86_64-redhat-linux/10/include /usr/include/bits /usr/include /usr/include/sys processors.c object.h abstract.h stddef.h types.h stdarg.h <built-in> stdio.h types.h stdint.h pyport.h time.h object.h methodobject.h structmember.h descrobject.h bytearrayobject.h bytearrayobject.h bytesobject.h bytesobject.h unicodeobject.h unicodeobject.h longobject.h longintrepr.h boolobject.h floatobject.h tupleobject.h listobject.h dictobject.h dictobject.h methodobject.h moduleobject.h classobject.h code.h code.h pyframe.h frameobject.h traceback.h pystate.h pystate.h pyerrors.h pymem.h objimpl.h abstract.h import.h string.h tupleobject.h listobject.h warnings.h pylifecycle.h pystrtod.h ceval.h modsupport.h � �l �$�yJmY �.� f%��JJ� !;��JJ�� ����� [8J Y ھ J �� 88uھJ�� M�X%qu]J�� !My� x� Y Y �J�� !�~X%p J]��J� ! y< w�X � [��J� ! l�� lut �JK<< �3MJ<3< M zf X � O�JmJ< m t b � O- Z�} Kt� � jYt I� X � �} K"� Pt $X�} K^�f< � Y� XT Po �Z � �G�yJ��8��%l J XͿJ�� ! y<v t<X L [ͿJ�� ! ES.%g JX�J�� !Ey<+r t+ J Y X K`�J�� ! pJ��� �� ��% G ?�XJ p �|%nJ stu`��X� �nf � YT.=[LHuϾX�� u;J�� ξ nX�� thtj�_j#jG?��J X � �_ f � J X � �_ f � { y �_�X�X�� � � XK J �� � [߿�� �JJ%�� J�@ Y� f�� ! ��J�� ��J<X�� !y�tg�` sK�^ �!JJ�^�!�_ Y� f�! �_�g� �_J<X� �"� =J X � � � �� J X � � � �� J X � � � �� J X � � � �� J X � � � �� J X � � � �� J X � � � �� J X � � � �� K- � �� Y� ��� t X � ܻ � �� t X � ۻ � �� t X � ڻ f �� t X � ٻ f �� J X � ػ f �� < �<X�� < ��X�X�X�X�X�X�X�X�X�X�X�X�X�� � =Y v u��Bz X �t �AJ X < . � � X � � X � t $(�XJ�XJ$�XJ�XJ�XJ�XJ K-X h ,t .������ 3IJ4� f��JX�� �3<`X � Lk u I �� _� ? =I K t �| <t<t ���ut �} t<t �t w�} t��^J�^jK �3� X OJ,TJf,�T.f J<XX = �� = ����� X =�� .�� ^ :J �yJ _��yJ<<�...J�y.� �@���� <X �y�0KXJ=X� �=��!&, �!X2,X X�Y�Yj Y/f�Y (� X � _yXF z�@ �?�@XJ �?�@J �?Z � qJ JX�XX� >�@ X�J��?��J Y�@J nX� �� �� t �� ���y� X �@�.� �>!�2,X X J �Y< ]= ;Y XY^�X^L �Ŀ �� J��� �KX�� %5tt�� Y� f �� / ���<X��� �<Z]R�K ]\<A��Z��� ��tJ%� t� Y� f � /f ���X< � �� J� Z[R�K [\<A��Z��� ��tJ%� t�� Y� f �� /f ˾�X< � �?J� Z��L]�@ �?J���� ��JJ%�� JͿ Y� f �� / ���<X�� �<Z Xn� �<ZT�L �@X �>J���� ��JJ%� J�� Y� f � / ���<X��� �<Z XZ�L �AX �>J���� ��JJ%� J�@ Y� f �� / Ϳ�<X��� �<Z X �o��Q �- �R�.J � � � y QJ y Y � \ XYf..J tf J z � / KX �{tf� zX nJ+<J KX ..J*bt�t<v IYf vf� ���q �� J���� ���q � �� �� �� �e ]Y u Y K X X J Ytz?X �� u V]� ~ u V]2 � JX^ 3t }��� u jK X�J Y � � Y��q �� J��� �� �o ]� u � K � t J �ztX? �_t w fK v �� Jk� Xk<� ) l JJ l � > afKu Y e= -K I=<Y �K1 J<JX: �+X<J =X,f.J f�T�� > J n � h gIKu Y e= -K I=<Y���1 J<JX/K �|�� V� zJ4 .J������� X = 5�X��3�� 4� fٶJX�� �3<X � L �X X � =I K ���} ��|J�tt<t �� "��3�� ÷fX�� öf<�� 4L�~3<X � L Jt< �~f X � = K sJ K t<�~��} ��|J�tt<t ���~����� 3pJ4 f��JX�� _3<`X ! L] g I MX _X = K t �| <�t �S�ut �} t<t �t w�} t�� �g��O. �0<=�O �0�OXX�0 �tI � f %J�P�/��T�+�� ( �mJ�m < mJf e�!�t� u � K X g Y J X�]�T�+�<� F� @ F R��!�t� u � K X g Y J X�]�T�+� =�� t �t� ���Y�� � ��� �!� u V]" ]� u V] �^2�/t � � K �UI��* �,��Y� l� ���"� u V]" ]� u V] �^2�/t� x< � K �UI��* �L��2;/t2/t ����~J�� .�~.XL P� �%nL stu`��X�� �nf � Y�.=[LHuϾJ�� u;X�� ξ nX� thte�g � � w� ce.q� Y.<XaJ X� k� t�t�]�X ��' ��&��q �� J���� ���q �� �� �� �e ] u � K � � J �t �Z� M�HKL�W � f�)�W Y� t�)�W �� ��X�� ��YI�J 8�HK K �L�W �tX.��( dK �JJ Y � �&< u �]�Z �< �&X. �Y�Jj� �1j9u j ,�x<( C Y,K Ix( CX�< JD X v< ( <� g�J# >#:g � =<&Jj%�"�7 J " 7 [7,0,t0J"J<7�0,t0J"J<7�0,t0J"J<7�0,t0J"J<7�0,t0J"J<7�0,t0J"J<7�0,t0J"J<7�0,t0J"J<7�0,t0J"J<7�0,t0J"J<7X0,t0J"J<7X0,t0J"J<7X0,t0J"J<7X0,t0J"J<7X0"�<g ��X��.�< � �)v)�u �,� <X J�� X g)KI� � 5x1�5x�� 7j� / ��N�1J Y�M �X� �2 l5 J � � �<-+]3i< + g; /<N< =z � K+�.� ��-+]� �+��3i< + g; /<N< =z � K+�. � /t f8 f5 X� I� �) KI��)+�),KI<�=)-g�_/ -=/f � ��X/ -=/. � �; gX� �N� N �tU �C�yX��<Jt<\�!� ��yt���<% �C�y�� �<t W.<W uX = YĽ �� ǽJX �� x�Dͽ��� X =ý f �� Y �g K et �.< ��� t �� ȽXJ�� % t Y�� J ���� Z!� ��yt��� �y����) X<X7"�7� jt � ��<�� df c; �.< Y k� t�����X ��' ��&��q �� J���� ���q �� �� �� �e ] u � K X J J Yt �Z� YHY �h�W � ��)�W Y� ��)�W Y� |� �) �� z� ([ X� �& ��YIJX 8�HY Y �h�W ��XX��( dK �JJ Y � �&< u �]�Z �. �&X. �Y�JC� JC � �}X �t= �}��aL M�GKLVY� X=;� ��t� ����� $�@��Y�ڸ � ��� �aUKK K H��W Y� ��)�W Y� ��)�W Y� ��� !�~�t$ $e ��t�~< ef" fX� /�.J,<�=طX�� �l�=�۶ � |��� ڶ � `x<f�� �!�~��t$�~f$e � etf(f-<J �Ng 7 � %J � / %< � W��۶ � �<�� � ��.X �� � X�Y ��KHK KL ��W Y� ��)�W Y� ��)�W Y� |��� Y : �=�ڸ �� ��_MGKLVY MY � b���� �� ��_UK TK WKZ K�W Y� ��)�W Y� ��)�W Y� � �� �~ G!u� � �f g(�-<J �g 7 � %X � / %< � WX ��_MGKLVY MY � b � �� = ������ X=�� � n�X"�� ��9&�#���"�<� � t;K&� M :K =g��YX�� �� � |��� [�J Y� �� �� � �� tJ� �� � �� Dx<�� �� 6 � K#0;� > � 9 c u Et 9� ���XXJX�tX��X�� !t �at Jt �Xt<� �<� ��� �� t��tJ �� �� ��� �"h<<X ��_M� J�_<KLVY MY � bX ˶����XX�� �!����=g �� ��� 0X Y � !r u u" K$ =��YX�� � ���� �� �� <�� ��<� �X��� % =" =��X �� �� �XX�XX� �& c �.< � kX= tJ�<���X ��' ��&��q �� X���� ���q �� �� �� �e ] � Y K . / � J ��Z X� �% � �]�Z � dK . / �J [. � �&X% �Y�.. �WXX��� z.jt &�5�[ � K <�� � X t <@ �l. �X X@ �l ! �b �1 ��l �: � X. �h<�yJ�� Y �c� J � � �O�/;�Y��lX�<.� q z< ]*�.JJ� Y K �T�y�1�N<J�#�+X0s3 JX(�l Y � � $ + ��b� �aJ� �aJX� �c��|� �S<V ��_� KK�aJ� �aJ� �a �� ��KWY�aX� J=�a � f!� �a � � �a � � � ��b� t! � �b !� ^� J�aX 6.�1 ��~�M\�2 (� ��� t��l�X� �l X ! �b �� �X!� � r� �h<�yJ��YX �b��X%� � X�k4�XXX�kt�K �T�y�1%X�NXJ�%�+� �N��� �b� �aJ� =X�%��a� �a� �a � m� X�aff� �a� �;�X �<� � �~ X � 9? ��O�0�O<J �0 I#< Y l JJ l�� z� Y jX���mX �X(.�n�Y����a!� X�a� �a� �a!� � �a��0 � ���'� uX ��BzX�*X.JJ Y �d�M\�2 �J Y�t j"J ��p��yC� .f@� �{tt r�z� �JX�_� �_� J&X�_� �{ �7�Z6���� � B�j4�fXB�j!�c^� !�c�1.^�j! �t � �_ � � < �{�i �iJ�y� J0�bXX��y�� JY �i�y��Y$ - �b � $�b f� X�b�}�JX� �`0� X�&�bX �� Y 4 B!�c � �^� !�c � �� � �{ �iJ�yJ�� Y �iJ�yJ�� Y � �O �/J;�Y�mX.� q zJ ]*f.JJX Y � �T�y�1�N<J�#�+X0s3 JX(�k g /�0(J g � -XTXW$ - �bX � $�b �Xf�1 ��~�M\�2 (� ��� t��k�f��k!�cX �� � J�cXf^� !�c �� ��X%� � Z�j4�fXZ�jt �cXX�1� �T�y�1%X�NXJ�%�+� �NXX� �f<�_X����0� � �~ X � G1t <�O�0�O<J �0 I#< Y J l <' z< Y �X.��l ��(.� � ���'� uX � X�PzX�*X.JJ Y �d�M\�2 �� ��t j"� ��lXX��)v��f�c � t� ;� �bX� �z.jt ��A�[ � K <�� � X t <L �n. �X XL �n ! �` �1 ��n � XX �f<�yJ�� Y �a� J � � �O�/;�Y��nX�<.� q z< ]*�.JJ� Y K �T�y�1�N<J�#�+X0s3 JX(�n Y � � $ 7 t �t �LX v �3���L�3 � �Z� �J�5��j � \�`� t! � �` !� ^� J�_X 6.�1 ��~�M\�2 $� ��� t��n�X� �n X ! �` �� �X!� � r� �f<�yJ��YX ��Lq�3�L��3 � ��LJ v�3 u�#� �L�Jt �3�L�3��JX�5 �J� �5X =�J f �5 ��KJ�4� ��J � ��%� � d�n4�XXd�nt���J �4X�L�3 `�Lq�3�Lt�3 �t B�X Z*�J�0XK �T�y�1%X�NXJ�%�+�� . �z<X � �~ X L 9? f�O�0�O<J �0 I#< Y l JJ l�� z� Y �X���oX �X$��P�X�5��J�/X � ���'� uX � X�BzX<*X.JJ Y �d�M\�2 � ��t%��Xd�$��J �/X� �n�?p��a�5t �t �LXv<�3f��L�3 ��Lq�3�L��3 � ��LJ v�3 u�#<� �L�Jt �3�L�3��JX�5 �J� �5X =�J f �5 Z�KJ�4� ��J � |��5 Y��� �J �4X�L�34X<Y�J�5�i � _ �X�Lq�3�Lt�3 �t BX� ��*�J� �$ � �t<ttk�m��m. y �&f ��!�JJ�5 �f <_yC ���HX �X��5<��J�4� �J����5�$��J�5��X � � � �Y�HXJ�7�cfz.jt ��9�[ � K <�� � X t <D �i. �X XD �i ! �e �1 ��i �: � X. �k<�yJ�� Y �f�J � � �O�/;�Y��iX�<.� q z< ]*�.JJ� Y K �T�y�1�N<J�#�+X0s3 JX(�i � X/�(�d� � $ / �d �J �dt J � f �( �O�yX� � � �rX � t ;t �.<e�r �d�h�J ��d � ��a� �Y����d!��d � �! X ��d �� �d��c� J�c<�� �d � �! � �e � ��!�f � ��~�M\�2 $� ��� t��i�X� �i X ! �e �� �X!�� r� �j<�y�J�dX���X �d���%� � \�i4�XX\�it�K �T�y�1%X�NXJ�%�+� �N�� �d��d��d � ��dXX� �d� �c� � <;� �cȊt��0<X � �~ X L 9? ��O�0�O<J �0 I#< Y l JJ l�� z� Y �X���jX �X$��k�t�=t f� Z ��dTWn�� � X��r�XKK�dJ��dJ��d ����KWY�dX�J=�d � n�X�X�d��0 � ���'� uX � X�BzX�*X.JJ Y �d�M\�2 �� ��t) �O��/� �i�z.jt ��9�[ � K <�� � X t <D �g. �X XD �g ! �f �1 ��g �: � X. �l<�yJ�� Y �h�J � � �O�/;�Y��hX�<.� q z< ]*�.JJ� Y K �T�y�1�N<J�#�+X0s3 JX(�h � X/�(�f� � $ / �e �J �et J � f � ( �O�yX� � ��pX �t ;t �.<e�p �e�h�J ��e � ��c� �Y����f!��e � �! X ��e ���f��e�J�e<�� �e � �! � �f � ��!�f � ��~�M\�2 $� ��� t��h�X� �h X ! �f �� �X!�� r� �l<�y�J�fX���X �f���%� � \�g4�XX\�gt�K �T�y�1%X�NXJ�%�+� �N���e��e��e � ��eXX��e� �e� �<;� �eȊt��0<X � �~ X L 9? ��O�0�O<J �0 I#< Y l JJ l�� z� Y �X���iX �X$��j� t�=t f� Z ��cTWn��� X��p�XKK�eJ��eJ��e ����KWY�eX�J=�f � n�X�X�f��0 � ���'� uX � X�BzX�*X.JJ Y �d�M\�2 �� ��t) �O��/� �g�z.jt ��=�[ � K <�� � X t <H �f. �X XH �f ! �h �1 ��f �: � X. �n<�yJ�� Y �i�J � � �O�/;�Y��fX�<.� q z< ]*�.JJ� Y K �T�y�1�N<J�#�+X0s3 JX(�f � X/�(�g� � $ 3 �g �J �gt J � f � ( �O�yX� � ��oX �t ;t �.<e�o �g�h�J ��g � ��e� �Y����g!��g � �! X ��g ���g��f�J�f<�� �g � �! � �h � ��!�f � ��~�M\�2 $� ��� t��f�X� �f X ! �h �� �X!�� r� �m<�y�J�gX���X �g���%� � `�f4�XX`�ft�K �T�y�1%X�NXJ�%�+� �N���g��g��g � ��gXX��g� �f� �<;� �fȊt��0<X � �~ X L 9? ��O�0�O<J �0 I#< Y l JJ l�� z� Y �X���gX �X$��h� t�=t f� Z ��aX[r��� X��o�XKK�gJ��gJ��g ����KWY�gX�J=�g � n�X�X�g��0 � ���'� uX � X�BzX�*X.JJ Y �d�M\�2 �� ��t) �O��/� �d�z.jt ��6�[ � K <�� � X t <A �c. � X XA �c ! �k �1 ��c �: � X. �q<�yJ�� Y �l�J � � �O�/;�Y��cX� <.� q z< ]*�.JJ� Y K �T�y�1�N<J�#�+X0s3 JX(�c Y � � $ , �k � ��hJ� � ��J�5 ��J�5 ��J�5 ��J�5 � �X= ���' �X\� X<6�b9PX�j��j� ;�l<�jJ� < G�k�t! . �k !� ^�J�jX 6.�1 ��~�M\�2 $� ��� t��c� X� �c X ! �k �� �X!�� r� �q<�yJ��Y%zX � Y�c4� XXY�ct� K �T�y�1%X�NXJ�%�+� � � � �<�Xf� �%<X � �~ X L 9? <�O�0�O<J �0 I#< Y l JJ l�� z� Y �X���dX �X$���< zX �Y J� � � � =X� �& �X yJ Q���% � ���'� uX ��BzX�*X.JJ Y �d�M\�2 �J Y�t' �. ��� �}J ��[N;KIJu� f Y X � I �� J "� X J"� � X t . g I <� J �"t . fJ"X �"� X �A g�@��K# 0#: �Y = J&:����Y � K+=+I�+,0 � = = � � y J X� Y � � � �8X5X� f � � I ��"� J"� � fKJ $ �J� �%Jg%W =%= ,�J � � ��� � �v J� �%K%W< g%< � �15s�� � � �X g �%zLX��� ! Y%=� �&��Z��% Y �= g�N�1J Y�M (X� gDX#Y 09/#< YY = �#Y 09/#< uK = , �J- g� NX%Xu%e =W%g%e< gX d Y+K+I�+,0 � = = � � y J� � Y+=+I�+,0 � K = � � y J�5� � Y � = �f�� � K+=+I�+:0 � = = � � y J X� Y � W gX�5J F%Y%e< uW%�%e =] K%zZf��" = y�%dh��0g%e< �X M Y+K+I�+:0 � = = g K y J � Y+=+I�+,0 � K = K Y y J� � Y� z.jt ��4�[ � K <�� � X t <? �b. � X X? �b ! �l �1 ��b �: � X. �r<�yJ�� Y �m�J � � �O�/;�Y��bX� <.� q z< ]*�.JJ� Y K �T�y�1�N<J�#�+X0s3 JX(�b Y �X$ * �l�/.�1 � G�l�t! X �l !� ^�J�kX 6.�1 ��~�M\�2 $� ��� t��b� X� �b X ! �l �� �X!�� r� �r<�yJ��PtY$ * �l�l�kJ�<X%D � W�a4� XXW�at� K �T�y�1%X�NXJ�%�+� �<X � �~ X L 9? �O�0�O<J �0 I#< Y J l <�� z� Y �X���cX � X$�H�d�l��l��X� � ���'� uX � X�BzX�*X.JJ Y �d�M\�2 �� ��t j"� �b�z.jt ��<�[ � K <�� � X t <G �`. � X XG �` ! �m �1 ��` �: � X. �s<�yJ�� Y �o�J � � �O�/;�Y��aX� <.� q z< ]*�.JJ� Y K �T�y�1�N<J�#�+X0s3 JX(�a Y � � $ 2 ��m��?usg�<�@��lX� ��m�t! � �m !� ^�J�mX 6.�1 ��~�M\�2 $� ��� t��a� X� �a X ! �m �� �X!�� r� �s<�yJ�� YX� �lX� �?��5�@8T��m� ;�X%� � _�`4� XX_�`t� K �T�y�1%X�NXJ�%�+��a�m��lJ� =X � <X � �~ X L 9? t�O�0�O<J �0 I#< Y J l <�_ z� Y �X���bX � X$�� � ���'� uX � XLBzX *X.JJ Y �d�M\�2 �� ��t j"� Q �F �=Qw. �tX= K� � K' � Y�E `X.(�:JXJ.E� EX= � t � Jb�Y � YX = Y = Y� = X�B��=J ?�B � 6��=�B � n��=�B � n��=���e �J=Y Y � , > < /� >�\ n� �#wG� KyX <�.Y! RY!6_� X�i t g u / Yt�� t Y �b�yJ�� Y!Y�\��#<=�[ 6��#Y�� �K �K �K ���\ � ���$�?�<�Cq?�< �C �<J � <t. z. g<t�w?�.+ �u<t� < =rvJ ��Y.X Y��J< �� )V*<. �=] t<C���� ���� Ԯ `��� � J�lXLVZY�Y K�B �=�BJ �=< 9 �~X�;2YXs� �C�<J@�D � 6��<�.� �q [�|X ���&H�~M��� � Y�J�� Z����<�� Y�&�Y��J�� Y�<�� zJ:Y��T��X �. �+ �. �*. �3. �0. �0Y�� n��� �|<� + �� J..S�q �S� �<K �X =Z� �*p'� ��G< �8 J � uX g֞�Xh�"<�"X< Y�G< �8!�J!�=fY �5�G X `X�8� Y�G��8< =�G 6�.�8<�%�pX�E��:.� g K�G< �8�G n��8 � � �HX �7<< � �G 6�.� �5 �G< �8�G `X �8�H Y� `��8 � W =�Y �HX �7J<� �G 6�.�8 y <�H��HwtX=^Y�E �:�E<t�: �@ �EJ� n��:X�<IX -SfZ.� �X = � � =Y�B n��� ���< 0��k j�C u� n��= \�B n��=�B n� �=X Y[\#] #<] #.]fX Y �.�f rtY0.�Y ��[<�$ yX6t9��[<�$"�_��| Y�<�� StV�"�_��| Y�<�&� WtZs�.3 ��+&t Y" �,"V =�T�+.%)�Jg =-K 0 J = Z Kv. J&t t$���T%#t5t8�+� E*< xJEn xJ 5.�T�JD.� t%#�GtJ�'%�KtN� �"�w =/���G"�F#�:t�F.X=�| ��<��:�=��E �=Y X�:�E��{<��: .=��x� � � �=Y�A<��>< Z�A n��> n�A ��<� � ��>< �A.X�>�B � n��>�A `�+�$�."�#.�"Wu��] �4�)"4�Vt� �) < � < KKX//3J.;KH<�0X 148J. � X.�S�.. �-X K � ZKJX�S ��\�#��|�t�3�6� �� � X�[3�}�t�3 X�t� �Mt X �Y �&< � �Y 6X. �& XY Z �~< �r��r[� Xh��xh`�� �VtY��}�= �} � ��1u#Y1/X�t��1u�Y1/X�t��1u�Y1/X�t��1u�Y1/X�t��1u�Y1/X�t��1u�Y1/X�t��1u�1/X�t��1u�Y1/X�t�[I1uI�1��Y1/X�t�Z�W n�.�(�W n�2�$q�2X��}B ��}F ��}F � �}@\� � w � t X �h�ytC�Xl�CX�}�.K3 �t_y<C.f i t� � ��`Xc� ��d<g ��^Xa �( t Y !(r�%J\J;;)� �� �.KJ�w� �.w� z�3�0X O� 4� ! � Y#!Y� �� �.KJ�}� �.}� �K)X&X \F��;;:��:Z;;Z;=< X Y� �E �� X X� `��;�E�� =� X X� `��;�E Y� `��;�E Y� n��;�E Y� n��;�f�� �}BA�D���=��Eq J�: �&[IK Y� < �t%Z ��� ��1�f+�1xX+|�] n��$�}F ��}F �X�[�X��Z `� �% NXQ��T<W��Z `� �%U X�X��Z `� �%�Z n� �% JXM��T<W��Z n� �%Q T�X��Z n� �%�Z `� �% JXM��T<W��Z `� �%Q T�X��Z `� �%�Z n� �% R�U�X��Z n� �% �-��X��Z n� �% �-��X��Z n� �% �-��X��Z n� �% �-��X��Y n� �% �-��X��Y n� �& �-��X��Y n� �& �0��X��Y n� �&�0��X��Y n� �&�0��X��Y n� �&,�/�X��Y ��m�%n �q�k�m�n �m����Z � `��&�Z� �� ���<�D � ��1�"+��] � �E�$<kfEX �[fXE�$ �� R� .<X��~u��t O� X �t � ] �JttC�kl. �X<*v X Z�Jt<tC�kl��X<C�k.�t2^XK<X � � > X!� = �� = Y�F ���9��K�K �� �g�F n��9 Y ! \�F `X.�9 �yt� Z �> �! !��F Y� `X�9Z�FX Y� `X�:�FX Y� `X�:�FX Y� `X�:J �E ��#�>t\�fU.y-tS.�.tR.S/tQ.e� t@.w� t�.}� t�.+� t�.K� tz�K^�r_�r!Xh �S�h-Xd�A�d?X���d� Xl���l� X� ����� X� ����� X� ��~���X� ��~���X� ��~���X� ��~���X� ��~���X� ��~���X� ��~���XF ��~�F�XE�~�k�EX l���X�Z �$o1�ntktgts tk tm tt tp t t� tr tt ti t6�ZX�&�| __Pyx_CachedCodeObjectType attr_name _PyObject_GenericGetAttrWithDict Py_tracefunc object_reduce_ex message lenfunc PyModule_GetDict cython_runtime_dict _PyOpcache __pyx__find_code_object PyExc_ModuleNotFoundError ob_alloc imported_module _dictkeysobject __Pyx_CyFunction_set_dict PyDict_GetItemString tp_getattr alignment PyExc_TypeError __Pyx_CreateCodeObjects sq_item co_argcount __Pyx_PyObject_FastCallDict utf8 nb_add sign ascii _Bool ob_refcnt __pyx_k_stringsource PyTuple_New sq_ass_item PyBaseObject_Type __Pyx_PyObject_GetMethod _Py_DECREF __pyx_k_reduce_ex sq_inplace_repeat __Pyx_CyFunction_Vectorcall_FASTCALL_KEYWORDS_METHOD __pyx_k_no_default___reduce___due_to_non tp_as_async __Pyx__ImportDottedModule_Lookup nb_matrix_multiply expected_basicsize nb_lshift sq_inplace_concat ma_used tp_is_gc co_firstlineno nb_power ignore __Pyx_CyFunction_set_defaults PyByteArrayObject __Pyx_CyFunction_get_annotations am_anext from_name __Pyx_PyList_Pack sq_repeat curexc_value __Pyx_PyErr_GivenExceptionMatches tp_itemsize __Pyx_CyFunction_get_defaults __pyx_v_type_ sq_concat PyImport_ImportModule __Pyx_modinit_global_init_code uint16_t __pyx_k_ entries initproc overflow_arg_area __pyx_mstate_global __Pyx_UnboundCMethod_Def __pyx_k_DecimalResultProcessor_process __Pyx__DelItemOnTypeDict PyGetSetDef reg_save_area tp_bases use_cline is_unicode ma_version_tag PyErr_SetObject __Pyx_UnicodeKeywordsEqual PyDict_GetItemWithError __pyx_pymod_exec_processors fallback func_is_coroutine PyFloat_Type __Pyx__PyBytes_AsDouble_IsSpace context_ver setattrofunc f_valuestack __Pyx_check_single_interpreter tp_dealloc defaults_kwdict _PyByteArray_empty_string __Pyx_CyFunction_set_annotations _typeobject nb_floor_divide __Pyx__ImportDottedModule_Error PyMethodObject nb_inplace_lshift __builtin_va_list invalid_keyword_type __Pyx__ImportDottedModule __pyx_k_pop __pyx_pf_10sqlalchemy_11cyextension_10processors_22DecimalResultProcessor_6__setstate_cython__ strrchr matches modname f_stacktop __pyx_pymod_create __pyx_self _Py_Dealloc PyUnicode_1BYTE_KIND func_annotations __pyx_k_5_6 PyLongObject __Pyx_CreateCodeObjectForTraceback PyErr_NoMemory __Pyx__PyUnicode_AsDouble_Copy default_value nb_index tp_richcompare __pyx_k_time wstr __Pyx_get_runtime_version PyBytesObject m_free __Pyx_NewRef __Pyx_PyObject_CallMethod0 c_line PyThreadState __Pyx_CyFunction_set_qualname nb_remainder __Pyx_CyFunction_Vectorcall_CheckArgs visitproc __pyx_k_string PyMethod_Type __pyx_mstate __va_list_tag module_name __pyx_k_time_cls _Py_TrueStruct __pyx_mdef_10sqlalchemy_11cyextension_10processors_5to_float __Pyx_PyObject_Call ob_sval __pyx_mdef_10sqlalchemy_11cyextension_10processors_11str_to_date __pyx_k_str_to_time PyTupleObject allow_none __pyx_find_code_object PyVectorcall_NARGS PyCompactUnicodeObject co_weakreflist num_max was_sq_slice PyMemberDef as_c_string intern interp __Pyx_PyObject_CallOneArg ob_type __pyx_k_module __pyx_dict_version _Py_XDECREF tp_free __pyx_mdef_10sqlalchemy_11cyextension_10processors_9str_to_time PyObject_IsSubclass is_safe_type PyExc_RuntimeWarning utf8_length PyType_FromModuleAndSpec co_opcache co_opcache_size PyModuleDef PyVarObject __pyx_L5_argtuple_error co_nlocals __Pyx_CyFunction_get_kwdefaults PyType_Slot PyImport_GetModule PyErr_Format nb_and co_cell2arg _err_stackitem PyDictObject partial_name kwnames ma_keys _PyUnicode_Ready tp_call __pyx_k_DecimalResultProcessor___reduce async_exc __pyx_k_format __Pyx_CyFunction_get_name_locked __pyx_k_spec gilstate_counter f_localsplus ob_item PyInit_processors __pyx_k_Couldn_t_parse tp_str _PyCFunctionFastWithKeywords PyUnicode_Decode PyObject_GC_IsFinalized was_sq_ass_slice PyExc_RuntimeError co_filename __Pyx_PyObject_IsTrue __Pyx_CyFunction_get_qualname PyDict_Update ternaryfunc __Pyx_RejectKeywords ob_bytes submodule ob_base PyTypeObject __pyx_L4_argument_unpacking_done PyTraceBack_Type __pyx_mstate_global_static __pyx_CyFunction_methods get_item_ref_result __pyx_moduledef_slots current_id __Pyx_CyFunction_get_annotations_locked __PYX_GOOD PyModule_GetName __pyx_k_set_name PyObject_GC_Track __pyx_dict_cached_value __Pyx_PyVectorcall_FastCallDict sq_contains __Pyx_CyFunction_set_name m_module PyObject_CallFinalizerFromDealloc __gnuc_va_list marker __Pyx_PyDict_GetItemStr tp_setattr __Pyx_ErrRestoreInState __pyx_string_tab __pyx_callargs check_size PyObject_GetAttrString richcmpfunc unsigned char mp_ass_subscript __pyx_ptype_10sqlalchemy_11cyextension_10processors_DecimalResultProcessor is_method __Pyx_InitConstants ptraceback __pyx_k_self PyModule_NewObject __pyx_methods_10sqlalchemy_11cyextension_10processors_DecimalResultProcessor __pyx_k_reduce_cython tp_dictoffset __pyx_k_TypeError PyNumberMethods code_line PyMethodDef tp_finalize __pyx_L6_skip __pyx_kwvalues target PyBytes_FromStringAndSize m_init function_name exc_type1 exc_type2 __pyx_t_5 mp_subscript __pyx_string_tab_encodings f_gen tp_clear __pyx_mdef_10sqlalchemy_11cyextension_10processors_22DecimalResultProcessor_7__setstate_cython__ func_globals __Pyx_CyFunction_get_kwdefaults_locked uint64_t __pyx_k_ValueError PyObject_GenericGetAttr num_min PyModuleDef_Base __pyx_pw_10sqlalchemy_11cyextension_10processors_5to_float use_tracing __pyx_b __pyx_d __pyx_f __Pyx_SlowPyString_AsDouble PySequence_GetSlice __pyx_m nb_bool f_trace_opcodes __pyx_r __Pyx_cached_runtime_version keys_are_strings co_freevars PyObject_Hash __Pyx_PyBytes_AsDouble tp_init cyfunc __pyx_moduledef objobjargproc ob_size PyUnicode_2BYTE_KIND __pyx_ptype_7cpython_4type_type tp_dict _PyThreadState_UncheckedGet tp_as_mapping __pyx_pf_10sqlalchemy_11cyextension_10processors_22DecimalResultProcessor_4__reduce_cython__ setattrfunc __Pyx_CyFunction_get_dict __pyx_k_asyncio_coroutines vret __pyx_pw_10sqlalchemy_11cyextension_10processors_9str_to_time __pyx_tp_dealloc_10sqlalchemy_11cyextension_10processors_DecimalResultProcessor first_kw_arg method_name __Pyx_TypeName GNU C17 10.2.1 20210130 (Red Hat 10.2.1-11) -mtune=generic -march=x86-64 -g -O3 -fwrapv -fPIC PyObject_Str binaryfunc type_obj_name __Pyx_CodeObjectCacheEntry b_name __Pyx_CodeObjectCache PyUnicode_AsUTF8 b_dictoffset tmp_value m_doc new_max __pyx_k_str_to_datetime __pyx_empty_unicode PyUnicode_AsUTF8AndSize bf_getbuffer co_zombieframe line_table vectorcallfunc __Pyx_PyByteArray_AsDouble callable getiterfunc ssizeargfunc PyMem_Realloc exc_state __pyx_codeobj_tab _py_tmp uint8_t descrsetfunc __pyx_CyFunction_init tmp_type __Pyx_PyUnicode_AsDouble_WithSpaces PyImport_ImportModuleLevelObject f_lasti __pyx_CyFunctionType_spec __pyx_k_None descrgetfunc index_found warning class_name parse_failure co_kwonlyargcount nb_inplace_add nb_reserved kw_name on_delete co_code __Pyx_PyType_HasMultipleInheritance __pyx_k_enable PyThreadState_Get __Pyx_PyObject_CallNoArg m_index PyErr_WarnEx PyUnicode_Type PyType_Modified reprfunc py_line __pyx_code_cache __pyx_CyFunction_members float_value __Pyx_CyFunction_get_globals moddict __pyx_empty_bytes curexc_traceback Py_UCS1 __Pyx_modinit_type_import_code /project first_line PyType_Spec exact __pyx_builtin_ValueError PyTryBlock tuple_dedup_map _PyObject_GetDictPtr pvalue __pyx_pf_10sqlalchemy_11cyextension_10processors_22DecimalResultProcessor_2process PyExc_NameError MAJOR_MINOR overflowed __pyx_v_format_ Py_GetVersion PyDict_Type __Pyx_PyErr_GivenExceptionMatchesTuple Py_hash_t parse_error_found __pyx_lineno ignore_unknown_kwargs PyFrame_New PyObject line_table_length __pyx_CyFunctionObject nb_xor nb_negative __Pyx_copy_spec_to_module PyUnicode_InternFromString kwds2 PyObject_SetAttr __pyx_k_to_float fixed_cause __pyx_k_isenabled __Pyx_CyFunction_Vectorcall_FASTCALL_KEYWORDS __pyx_L1_error slot __ssize_t is_true _longobject ptype PyUnicode_Concat __Pyx_CyFunction_clear co_flags __pyx__insert_code_object code_obj __pyx_k__2 __Pyx_modinit_type_init_code PyTuple_GetSlice PyDictKeysObject __pyx_insert_code_object m_traverse kwd_pos_args __pyx_k_value_is_not_a_string __Pyx_CyFunction_set_doc recursion_critical __pyx_k_name _Py_ascii_whitespace _Py_INCREF co_opcache_map __Pyx_PyImport_AddModuleRef co_name __pyx_k_to_str __Pyx_CyFunction_get_doc __Pyx_PyErr_ExceptionMatchesTuple PyCMethod __pyx_clineno PyBufferProcs _PyDict_GetItem_KnownHash __pyx_mdef_10sqlalchemy_11cyextension_10processors_1int_to_boolean PyUnicode_WCHAR_KIND co_stacksize ml_flags tp_new feature PyDict_DelItem allow_newer __pyx_CyFunctionType_slots f_executing varnames_tuple __Pyx__PyNumber_Float __Pyx_PyType_Ready __pyx_t_2 more_or_less PyModuleDef_Slot num_expected nb_inplace_true_divide __pyx_k_pyx_state _PyErr_StackItem full_name destructor PyCFunction im_weakreflist PyObject_GC_UnTrack __pyx_k_setstate PyObject_CallObject __Pyx_check_binary_version f_trace ob_start PyImport_Import PyUnicodeObject __Pyx_ErrFetchInState tp_del __pyx_pw_10sqlalchemy_11cyextension_10processors_7str_to_datetime encoding __Pyx_PyDict_SetDefault __pyx_k_func extracted __Pyx_InitCachedConstants fp_offset tp_name __pyx_k_date_cls gp_offset __Pyx_CyFunction_get_dict_locked __Pyx_IsSubtype co_posonlyargcount __Pyx_CyFunction_get_name PyInterpreterState_GetID c_profilefunc __pyx_pw_10sqlalchemy_11cyextension_10processors_22DecimalResultProcessor_1__cinit__ tp_as_sequence PyTraceBack_Here tmp_tb tp_as_buffer func_dict _PyDict_Pop PyDict_Contains nb_inplace_and __Pyx_ImportDottedModule __pyx_CyFunctionType __pyx_tp_new_10sqlalchemy_11cyextension_10processors_DecimalResultProcessor __pyx_pw_10sqlalchemy_11cyextension_10processors_3to_str __pyx_filename last_was_punctuation __pyx__function __pyx_v_value short unsigned int __pyx_pf_10sqlalchemy_11cyextension_10processors_8str_to_time async_gen_firstiter __pyx_k_int_to_boolean f_blockstack PyMem_Free __Pyx_Raise __Pyx_RejectUnknownKeyword PyFloatObject num_posonly_args tp_alloc abi_module_dict part PyFloat_FromString suboffsets compact __pyx_tp_traverse_10sqlalchemy_11cyextension_10processors_DecimalResultProcessor __Pyx_PyObject_CallMethO PyDict_Size __pyx_pf_10sqlalchemy_11cyextension_10processors_int_to_boolean trash_delete_nesting im_self __pyx_mdef_10sqlalchemy_11cyextension_10processors_7str_to_datetime wchar_t arg_passed_twice m_clear __Pyx_CyFunction_get_is_coroutine_value PySequenceMethods PyErr_Clear __Pyx_PyObject_GetAttrStr_ClearAttributeError PyTuple_Pack object_reduce modbad __pyx_k_reduce tp_getattro __pyx_k_fromisoformat b_handler allocfunc c_traceobj PyObject_SetAttrString __pyx_pyargnames __Pyx_fix_up_extension_type_from_spec m_copy Py_EnterRecursiveCall tp_methods __Pyx_CyFunction_init_defaults __Pyx_CyFunction_New tp_mro ucs2 ucs4 __pyx_args __Pyx_ParseKeywordDictToDict tz_dsttime __Pyx_FetchSharedCythonABIModule PyExc_ImportError __pyx_k_getstate __Pyx_ImportFrom is_punctuation __pyx_k_gc __pyx_tp_clear_10sqlalchemy_11cyextension_10processors_DecimalResultProcessor __pyx_v___pyx_state __Pyx_init_co_variables is_subclass __Pyx_FetchCommonTypeFromSpec __Pyx__PyBytes_AsDouble f_code dictptr PyErr_Fetch main_interpreter_id __pyx_pf_10sqlalchemy_11cyextension_10processors_10str_to_date nb_or ma_values func_qualname unaryfunc var_count PyCFunctionWithKeywords PyDict_SetItem PyByteArray_Type PyCMethodObject __pyx_temp __pyx_cython_runtime __pyx_methods __Pyx_PyObject_GetAttrStrNoError nb_float PyExc_SystemError try_unpack PyExc_ValueError obj_type_name traverseproc PyObject_Not context __Pyx_modinit_function_import_code tp_vectorcall_offset last inquiry func_code uint32_t nb_invert __Pyx_RaiseUnexpectedTypeError f_lineno __Pyx_VerifyCachedType ml_doc __pyx_pw_10sqlalchemy_11cyextension_10processors_22DecimalResultProcessor_3process ml_name __pyx_k_value py_object_name __pyx_k_vWA_aq_1 py_funcname num_pos_args __Pyx_RaiseArgtupleInvalid long double __pyx_obj_10sqlalchemy_11cyextension_10processors_DecimalResultProcessor func_closure abi_module tp_as_number __Pyx_PyMethod_New PyAsyncMethods PyUnicode_FromStringAndSize tp_weaklistoffset __pyx_pyinit_module PyUnicode_4BYTE_KIND __Pyx_MatchKeywordArg_nostr PyDict_SetItemString __pyx_k_cline_in_traceback PyFrameObject ml_meth __pyx_pf_10sqlalchemy_11cyextension_10processors_4to_float __Pyx_CyFunction_CallAsMethod PyException_SetCause PyMem_Malloc readonly descr tp_doc getattrofunc __Pyx_InitCachedBuiltins __pyx_k_disable co_varnames __Pyx_ParseKeywordDict unsafe __Pyx_AddTraceback __Pyx_CyFunction_get_code _Py_FalseStruct __Pyx_MatchKeywordArg __Pyx_InBases __Pyx_GetBuiltinName on_delete_data __pyx_kwds_len tp_weaklist __Pyx_CyFunction_get_is_coroutine bufferinfo __pyx_type_10sqlalchemy_11cyextension_10processors_DecimalResultProcessor __Pyx_ImportDottedModule_WalkParts __Pyx_PyBool_FromLong instance_class PyErr_Restore newfunc __Pyx_ImportType_CheckSize_Error_3_1_0 hashfunc __pyx_module_is_main_sqlalchemy__cyextension__processors key_hash getattrfunc __Pyx_PyVectorcall_Function __Pyx_validate_bases_tuple nargsf line_table_bytes code_len __Pyx_InitGlobals __pyx_pw_10sqlalchemy_11cyextension_10processors_22DecimalResultProcessor_5__reduce_cython__ __pyx_k_datetime __Pyx_MatchKeywordArg_str _Py_IS_TYPE __pyx_pf_10sqlalchemy_11cyextension_10processors_2to_str __pyx_t_1 lib/sqlalchemy/cyextension/processors.c __pyx_t_3 __pyx_t_4 __Pyx_ImportType_3_1_0 __pyx_t_6 __Pyx_CyFunction_traverse wstr_length fromlist __pyx_k_DecimalResultProcessor___setstat curexc_type __pyx_mdef_10sqlalchemy_11cyextension_10processors_3to_str shape new_cached_type __pyx_k_initializing __pyx_cfilenm tp_hash __builtin_memcmp PyLong_AsDouble nparts PyUnicode_FromString ndim ssizeobjargproc ob_shash PyDict_Next tp_vectorcall empty_dict __pyx_k_type __Pyx_RaiseDoubleKeywordsError tp_version_tag PyType_HasFeature PyOS_snprintf c_tracefunc func_name py_frame PyOS_string_to_double no_error PyUnicode_Format __Pyx_ImportType_CheckSize_Warn_3_1_0 _PyUnicode_IsWhitespace getbufferproc __pyx_pw_10sqlalchemy_11cyextension_10processors_22DecimalResultProcessor_7__setstate_cython__ PyDict_New __pyx_k_qualname py_code max_count PyFloat_FromDouble setter previous_item am_await Py_UCS2 Py_UCS4 PyList_New __pyx_k_date f_back stringtab_initialized PyModuleDef_Init __PYX_BAD tp_members arg0 tp_traverse _PyObject_GC_New mp_length ready kw_size __Pyx_ParseKeywords visit __pyx_k_setstate_cython __Pyx__GetModuleGlobalName PyImport_AddModule __Pyx_CyOrPyCFunction_GET_SELF __Pyx_setup_reduce_is_named __pyx_mdef_10sqlalchemy_11cyextension_10processors_22DecimalResultProcessor_3process am_aiter argc PyUnicode_FromFormat nb_inplace_xor __pyx_k_str_to_date tp_subclasses __pyx_k_re nb_inplace_power __Pyx_CyFunction_get_defaults_locked __pyx_bisect_code_objects co_names __Pyx_ParseKeywordsTuple tp_setattro freefunc data1 data2 co_opcache_flag nb_multiply num_found __Pyx_PyDict_GetItemRef m_base nb_true_divide latin1 __pyx_k_sqlalchemy_cyextension_processor tp_getset f_locals __Pyx_ValidateDuplicatePosArgs __pyx_builtin_TypeError PyLong_Type PyArg_ValidateKeywordArguments tp_iternext digits sq_length __pyx_umethod_PyDict_Type_pop __Pyx_CyFunction_Call PyCode_NewEmpty invalid_keyword tp_descr_get __pyx_k_vWA_N_1_1 tp_iter cleanup __Pyx_CyFunction_raise_argument_count_error __Pyx_modinit_variable_export_code nb_inplace_floor_divide __pyx_k_A_6_A_1_4vQd_2Q __Pyx_CyFunction_CallMethod __Pyx_PyCode_New_function_description PyBytes_Type strides setNameResult m_ml tp_base nb_rshift f_trace_lines __Pyx__PyUnicode_AsDouble_inf_nan PyObject_GC_Del __pyx_empty_tuple co_consts f_globals __pyx_CyFunction_getsets PyASCIIObject exc_info bf_releasebuffer async_gen_finalizer long long unsigned int recursion_depth __pyx_v_self nb_inplace_multiply PyTuple_GetItem releasebufferproc kind __pyx_k_is_coroutine nb_inplace_remainder __pyx_k_Q __pyx_L0 Py_LeaveRecursiveCall thread_id __pyx_k_test empty_list __Pyx__PyBytes_AsDouble_Copy m_slots defaults_tuple PyCodeObject PyErr_ExceptionMatches nb_absolute __pyx_pw_10sqlalchemy_11cyextension_10processors_11str_to_date object_getstate module_dot __Pyx_ImportType_CheckSize_3_1_0 PyListObject new_args __Pyx_ImportType_CheckSize_Ignore_3_1_0 coroutine_origin_tracking_depth __Pyx_PyUnicode_AsDouble im_func internal rt_version trash_delete_later PyObject_VectorcallDict __pyx_L3_error __Pyx_CyFunction_Vectorcall_O __Pyx_CyFunction_get_closure __Pyx_PyErr_ExceptionMatchesInState __pyx_kwds f_iblock nb_inplace_or __Pyx_inner_PyErr_GivenExceptionMatches2 __Pyx_PyObject_GetAttrStr m_methods name_attr PyObject_ClearWeakRefs m_size newargs ob_fval timezone __Pyx_CyFunction_set_kwdefaults tp_repr PyExc_AttributeError tp_cache __pyx_pf_10sqlalchemy_11cyextension_10processors_6str_to_datetime PyObject_GetAttr Py_ssize_t __pyx_pf_10sqlalchemy_11cyextension_10processors_22DecimalResultProcessor___cinit__ nb_inplace_rshift py_status defaults_getter __pyx_k_datetime_cls __Pyx_StringTabEntry c_profileobj __Pyx__SetItemOnTypeDict __Pyx_CyFunction_get_doc_locked nb_positive PyNumber_Remainder long long int is_signed _Py_NoneStruct __pyx_k_vS_q_8_a stackcheck_counter type_obj num_kwonly_args PyMappingMethods to_name _PyType_Check f_builtins __Pyx__PyBytes_AsDouble_inf_nan __Pyx_CyFunction_Init __Pyx_CyFunction_Vectorcall_NOARGS __Pyx_modinit_variable_import_code PyObject_RichCompareBool _PyType_Lookup modules encoding_names factor PyUnicode_Kind __pyx_tstate __pyx_k_main __pyx_pw_10sqlalchemy_11cyextension_10processors_1int_to_boolean PyCFunction_Type allocated tp_flags __Pyx_CyFunction_dealloc __Pyx_Import PyImport_GetModuleDict _Py_XINCREF __Pyx_CyFunction_repr use_cline_obj ob_digit interned parts_tuple nb_subtract __pyx_mdef_10sqlalchemy_11cyextension_10processors_22DecimalResultProcessor_5__reduce_cython__ b_level PyUnicode_Join __Pyx_CLineForTraceback co_extra sdigit PyObject_CallMethodObjArgs mm_class __Pyx_InitStrings __pyx_k_q_z __pyx_mstatetype __Pyx_PyVectorcall_FastCallDict_kw __Pyx_IsAnySubtype2 __pyx_nargs PyErr_SetString __pyx_k_lib_sqlalchemy_cyextension_proce PyCFunctionObject module_name_str meth_found __Pyx_CyFunction_reduce varnames_tuple_dedup from_list iternextfunc __Pyx_CachedCFunction co_lnotab __pyx_k_process nb_int ob_exports gc_was_enabled PyObject_HasAttr c_code_bytes __pyx_k_DecimalResultProcessor tp_descr_set owned_instance __Pyx_modinit_function_export_code Py_buffer __Pyx_CyFunction_raise_type_error func_doc short int PyCode_NewWithPosOnlyArgs num_kwargs __Pyx_setup_reduce prev PyErr_Occurred nb_inplace_matrix_multiply tp_basicsize nb_inplace_subtract __Pyx_PyCode_New co_cellvars __Pyx__CyFunction_dealloc nb_divmod tz_minuteswest objobjproc PyInterpreterState @� ]� U]� �� ]�� � �U�� �� ]�� ɖ �U�ɖ �� ]�� �� �U��� И ]И f� �U�f� i� ]i� �� �U��� � ]� /� �U�/� e� ]e� �� �U��� #� ] @� ]� T]� � \� \� �T�\� �� \� �� \ɖ Z� �T�Z� �� \�� �� \�� �� \f� �� �T��� 1� \1� 6� �T�6� i� \�� � \/� e� \�� ǜ \ǜ Z� �T�Z� g� \g� #� �T� @� ]� Q]� � S� � �Q�� �� S�� ɖ �Q�ɖ �� S�� � �Q�� i� Si� �� �Q��� #� S @� ]� R]� �� V�� � �R�� �� V�� ɖ �R�ɖ ȗ Vȗ �� �R��� � V� �� �R��� � V� f� �R�f� �� V�� �� �R��� � V� /� �R�/� e� Ve� �� �R��� #� V @� �� 0��� � \� �� 0��� �� \ɖ Z� 0��� �� \� �� \�� �� 0�� f� \f� 6� 0��� �� \�� � 0�� /� \/� e� 0�e� �� \�� #� 0� @� ֕ 0�֕ � P� � V� �� 0�ɖ #� 0� h� u� Pu� � ^� ^ɖ #� ^ l� p� Pp� �� ���� �� P�� י ��� f� ��E� I� PI� i� ��v� �� ��� /� ��e� �� �� z� ~� P~� �� ���� �� P�� f� ��S� W� PW� �� ��� /� ��e� �� �� �� �� P�� �� ���� �� P�� f� ��d� i� Pi� �� ��� /� ��e� �� �� h� � \ɖ 5� �T�5� 5� 0�5� Z� 0�f� s� \�� 1� \1� 6� �T��� � \/� e� \�� ǜ \ǜ Z� �T�Z� g� \g� #� �T� h� u� Pu� \� ^ɖ Z� ^f� 6� ^�� � ^/� e� ^�� #� ^ Ô �� X�� � ��5� Z� 0�כ � X �� �� P�� >� ��ɖ Z� ��f� |� ���� 6� ���� � ��/� e� ���� #� �� �� �� P�� >� ��ɖ Z� ��f� x� ���� 6� ���� � ��/� e� ���� #� �� �� \� _ɖ Z� _f� 6� _�� � _/� e� _�� #� _ �� �� P�� Ô R�� Ú PÚ ܚ R�� �� R�� � ���� �� ���� �� RZ� ^� R q� �� ��; q� �� �; q� �� �; q� u� Pu� �� ^ �� �� T �� �� U Ǜ ͛ P�� �� P�� �� �� Ô ה X ̔ ה X � � XU� Z� 0�f� m� X � � Xf� m� X � \� _s� �� _ � >� ��s� x� �� � >� ��s� |� �� � \� ^s� �� ^ � >� Us� �� U � >� Zs� �� Z�� �� �� !� >� Xs� �� X�� �� �� /� >� Us� �� U 4� >� Us� �� U >� M� Z�� �� Z C� M� Z�� �� Z M� \� X�� �� X R� \� X�� �� X � � P� �� U�� +� ��/� Q� �� �� � T�� �� TZ� ^� T �� � U�� �� UZ� ^� U �� � u�� �� uZ� ^� u �� �� TZ� ^� T �� �� UZ� ^� U �� �� U ɖ ؖ Qؖ � ���� Ü PÜ Z� Qg� �� Q ɖ ؖ Qؖ ٖ ��ʜ Z� Qg� }� Q�� �� Q ɖ ؖ Xʜ Z� Xg� }� X�� �� X ɖ ٖ \ʜ Z� \g� }� q� �� � \ ɖ ؖ X� Z� Xg� }� X ɖ ٖ \� Z� \g� }� q� ɖ ؖ X� Z� Xg� }� X ɖ ٖ \� Z� \g� }� q� � � \ � � @K$� � � | � � |#� � � @J$� � � \ � � |� � � X � � @K$� � � x � � P � � @J$� � � X � � x� ,� Z� Xg� }� X ,� Z� 0�g� }� 0� ,� Z� \g� }� q� ,� Z� Xg� }� X ,� Z� \g� }� q� 4� Z� Rg� }� R =� A� 0�A� Z� P =� Z� T g� }� \ ܜ � @F$� ܜ � x � � P �� �� X �� � \ �� �� 0��� �� P�� ߝ Rߝ � �� � � R �� �� Z �� ߝ T �� � \ � 0� 0�� #� 0� � � Q� � Q � � U� � U � � X� � X � � �� � 0� \� #� \ �� � U� � U � � U� � U � � X� � X � � X� � X � 0� \ !� 0� \ �� �� TZ� ^� T �� �� UZ� ^� U �� �� uZ� ^� u � "� U:� U� U l� �� S�� �� _-� �� _ l� � �? �-� ɖ �? �Z� f� �? �6� �� �? �� /� �? �e� �� �? � �� �� \ l� �� �? �-� �� �? � l� �� S�� �� _-� �� _ �� �� \ �� �� P � �� S�� �� _=� �� _ � �� Z=� �� Z � �� T=� �� T � �� 0�=� g� 0�g� �� R � �� 0�=� g� 0�g� �� P�� �� 0��� �� P � �� z��� �� U=� C� z�C� �� U�� �� P �� �� \ � �� \�� �� \ � �� \�� �� \ �� � V �� � V Z� �� �F; �� �� �F; 6� d� �F; Z� �� �1; �� �� �1; 6� d� �1; Z� �� � ; �� �� � ; 6� d� � ; Z� �� ^�� �� ^6� d� ^ �� �� V�� � V�� �� Vd� i� V �� �� S�� � S�� �� Sd� i� _ �� �� \�� �� 0��� �� \�� �� \d� i� 0� �� �� ]�� И ]И � �U�� �� P�� �� Pd� i� ] �� �� 0��� �� P�� �� 0��� � P � � \�� �� 0�d� i� 0� �� �� 0��� И 0�И � P� � ]�� �� ]d� i� 0� �� �� 0��� � ] �� � ] �� �� ] �� �� ] �� � ���� �� ���� �� P�� �� �� �� � ���� �� �� �� � ���� �� �� �� � ^�� �� ^ �� � U�� �� U �� � ]�� �� ] ȗ � V�� �� V ї � U�� �� U ֗ � U�� �� U � � ]�� �� ] � � ]�� �� ] � � V�� �� V �� � V�� �� V � �� \� �� \� f� \� /� \e� �� \ � �� _� �� _� f� _� /� _e� �� _ � �� �? �� �� �? �� f� �? �� /� �? �e� �� �? � � �� �? �� �� �? �� f� �? �� /� �? �e� �� �? � � �� \� �� \� f� \� /� \e� �� \ � �� _� �� _� f� _� /� _e� �� _ +� G� Ve� �� V `� j� Rj� v� r�v� z� RS� f� Q � /� Q � �� U� S� U� +� U/� f� P� � U� � �? � � P � /� Ue� h� Uh� ~� �? � �� _� +� _� � _ � �� Q� +� Q� � Q � �� U� +� U� � U � K� 0�K� �� R� � 0�� � 0� � K� 0�K� b� Vb� r� 0�r� �� V� � 0�� � 0� %� K� TK� �� Z�� �� V� � T� +� Z� � T �� �� z � f� ] � � p h� ~� U k� p� z p� ~� U �� ƙ ��v� �� S �� ƙ ��v� �� S ƙ � ��i� v� S Й � ��i� v� S � � �� � � �� �� �� U�� �� �U��� ւ Uւ �U� �� U�� � �U� �� �� T�� �� Y�� �� �T��� Ă TĂ ׂ Yׂ �T#� �� T�� � Y� � �T� �� �� Q�� � �Q� �� �� R�� �� X�� �� �R��� ׂ Xׂ �R� � X� � �R� �� �� U�� �� �U��� ւ Uւ �U� �� U�� � �U� �� �� u8�� �� �U#8�� ւ u8ւ ׂ �U#8 �� u8�� � �U#8 �� �� Q�� �� R�� ׂ R �� R �� �� Z�� ׂ Z �� �� q�� �� P�� ӂ qӂ ւ u#ւ ׂ �U## � q� �� u#�� � �U## �� �� Q�� �� �Q� �� �� 0��� �� 0� � 0� �� �� R�� �� R �� R �� �� U�� �� U �� U�� � �U� �� �� 0��� �� 0� � 0� � � � �� U�� � �U� � q � �� u�� � �U# � +� U+� /� �U�/� 8� U8� D� �U�D� g� Ug� u� �U� � .� T.� /� �T�/� C� TC� D� �T#�D� d� Td� u� �T� � � Q � u� �Q� � .� R.� /� �R�/� C� RC� D� �R�D� ]� R]� u� �R� � +� U+� /� �U�/� 8� U8� D� �U�D� g� Ug� u� �U� � .� Q/� <� Q<� @� q�@� C� QD� V� Q +� .� U8� C� U � .� x/� C� xD� m� x � � Q � '� 0�/� 5� 0�D� n� 0� � '� Q/� 5� QD� V� Q � '� U/� 5� UD� g� Ug� n� �U� � '� 0�/� 5� 0�D� n� 0� D� n� � � D� g� Ug� n� �U� D� m� x pu �u U�u �u �U��u �u U�u �u �U��u "v U"v +v �U�+v Mv U pu �u T�u �u T�u v T v +v �T�+v Mv T pu �u Q�u Mv �Q� pu �u R�u �u �R��u �u R�u �u �R��u v Rv +v �R�+v 7v R7v 9v �R�9v Mv R pu �u U�u �u �U��u �u U�u �u �U��u "v U"v +v �U�+v Mv U �u �u �Q����������u �u �Q����������u Mv �Q��������� �u �u U�u �u U �u �u y�u �u y�u (v y+v Mv y pu �u Q �u �u R�u �u R�u v Rv )v �R�+v 7v R7v 9v �R�9v Mv R �u �u �Q����������u �u �Q����������u )v �Q���������+v Mv �Q��������� �u �u U�u �u U�u "v U"v )v �U�+v Mv U �u �u 0��u �u 0��u �u 1��u v 0�+v 9v 0�9v Mv 1� v v �Q��������� v v R v v U v v d� � v v U v v y +v 9v � � +v 9v U +v 9v y �u �u +� � �u �u �U� �u �u y � 4� U4� E� �U�E� U� UU� �� �U��� �� U�� �� �U��� ݃ U � 4� TE� U� TU� [� t��� �� T�� �� �T��� ݃ T � #� Q#� ݃ �Q� � D� RD� E� �R�E� t� Rt� �� �R��� �� R�� �� �R��� ǃ Rǃ Ƀ �R�Ƀ ݃ R � 4� U4� E� �U�E� U� UU� �� �U��� �� U�� �� �U��� ݃ U #� 4� �Q���������E� U� �Q���������U� Y� q�Y� [� Q�� ݃ �Q��������� 4� D� UU� ~� U #� D� yE� �� y�� �� y�� ݃ y � #� Q #� 0� RE� R� R�� �� R�� �� �R��� ǃ Rǃ Ƀ �R�Ƀ ݃ R #� 0� �Q���������E� R� �Q����������� �� �Q����������� ݃ �Q��������� #� 0� UE� R� U�� �� U�� �� �U��� ݃ U #� 0� 0�E� M� 0�M� R� 1��� �� 0��� Ƀ 0�Ƀ ݃ 1� �� �� �Q��������� �� �� R �� �� U �� �� d� � �� �� U �� �� y �� Ƀ � � �� Ƀ U �� Ƀ y [� �� � � [� �� �U� [� �� y �m �m U�m �m S�m �m �U��m n S n n �U�n en Sen gn �U�gn (o S �m �m T�m �m V�m �m U�m �m �T��m n Vn n Un n �T�n fn Vfn gn �T�gn (o V �m �m Q�m �m T�m �m �Q��m �m Q�m n �Q�n n Qn Dn �Q�Dn ]n Q]n gn �Q�gn �n Q�n �n �X�n �n Q�n �n �X�n o Q o o �Xo (o �Q� �m �m R�m �m �R��m �m R�m n �R�n n Rn Dn �R�Dn ]n R]n gn �R�gn �n R�n �n �R��n �n R�n �n �R��n o R o (o �R� �m �m U�m �m S�m �m �U��m n S n n �U�n en Sen gn �U�gn (o S �m �m Y�m �m Yn n YDn ]n Ygn �n Y�n �n �P�n �n Y�n �n �P�n o Y o o �P �m �m p�m �m P�m �m u#�m �m s#�m �m �U##�m �m s#n n s#Dn ]n s#gn �n s#�n �n s#�n o s# �m �m Xn An Xo (o X �m �m t n 'n X n 'n � � n 'n S n 'n s o (o X o (o S o (o s �n �n d� � �n �n S �n �n s �o p U p p Qp p �U� Pt Xt UXt tt Vtt xt Uxt yt �U� Yt tt Vtt xt Uxt yt �U� �q �q U�q ms Sms ns �U�ns xs Sxs ys �U�ys Jt S �q �q U:t Dt U �q �q U:t Dt U r r U*t 4t U r r U*t 4t U r 5r Ut $t U +r 5r Ut $t U 9r Pr U t t U Fr Pr U t t U Tr kr U�s t U ar kr U�s t U or �r U�s �s U |r �r U�s �s U �r �r U�s �s U �r �r U�s �s U �r �r U�s �s U �r �r U�s �s U �r �r U�s �s U �r �r U�s �s U �r �r U�s �s U �r �r U�s �s U �r �r U�s �s U �r s U�s �s U s s U�s �s U s 6s U�s �s U 0s 6s U�s �s U =s Ss Uys �s U Ms Ss Uys �s U Ws ts U ds js Uns ts U m 5m U5m Pm �h m 5m T5m Pm �T� m !m PKm Km P m m U!m 5m U5m Km �h m m P!m 5m P6m Km P m m PGm Km P P� c� Uc� s� �U�s� �� U�� ч S P� c� Tc� s� �T�s� �� T�� ć �T�ć ч T P� c� Uc� s� �U�s� �� U�� ч S ^� r� \r� s� Ps� �� \ ć s�ć χ \χ ч s� c� h� \ �� �� S �� ć 0� �� �� P�� �� U �� �� P �� �� \ �� �� U p #p U#p 3p �U�3p Gp UGp �p S p #p T#p 3p �T�3p Hp THp �p �T��p �p T p #p U#p 3p �U�3p Gp UGp �p S p 2p \2p 3p P3p Up \�p �p s��p �p \�p �p s� #p (p \ Gp {p S Gp �p 0� Lp Yp PYp zp U `p ep \ lp pp P pp zp U �l �l Pm m P �l �l Pm m P �l �l P Pm mm Umm �m �h Pm mm Tmm �m �T� ]m ^m P�m �m P Pm ]m U^m mm Umm �m �h Ym ]m u� |m �m �h#@ po �o U�o �o S�o �o �U� po �o T�o �o �T� po }o 0�}o ~o P~o �o 0��o �o P po }o U~o �o U�o �o S yo }o u� �o �o s� Pq wq Uwq �q �U��q �q U Pq Uq TUq {q T�q �q T�q �q �T� Pq {q Q{q �q �Q��q �q Q ]q {q X aq lq Xoq {q X fq lq Xoq {q X Uq ]q T �o �o U�o �o S�o �o �U��o �o S�o �o �U� �o �o T�o �o �T��o �o T �o �o P�o �o P �o �o U�o �o U�o �o S�o �o S�o �o �U� �o �o u� �o �o s� Po Yo UYo Zo �U�Zo ho U Po Yo TYo Zo �T�Zo ho T Po Yo QYo Zo �Q�Zo ho Q Zo do U Zo do U G "G U"G BG VBG bG �U�bG G VG H �U� G "G T"G �G _�G H �T� &G 6G P6G BG ^BG bG 0�bG �G ^�G �G P�G �G S�G �G S bG rG 0�rG {G P bG G 0�G �G P�G �G V bG �G 0��G �G P�G �G \ bG �G 0��G �G P�G �G ] �G �G ] �G �G ] �G �G \ �G �G \ �G �G V �G �G V �O �O U�O �O �U� �O �O T�O �O \�O �O �T��O �O \�O �O �T� �O �O 0��O �O P�O �O \ �O �O P�O �O V�O �O P�O �O V �O �O V�O �O V �O �O V �F �F U�F G ] G G �U� �F �F T�F G ^ G G �T� �F �F Q�F G VG G �Q� �F �F P�F G \ �F �F u� �F �F P�F G P �F �F P SM M UM wO SwO �O �U� SM M TM �M \�M �M T�M �M \�M �M T�M O \O O �T�O `O \`O lO �T�lO oO \oO �O �T� SM �N 0��N O _O ;O 0�;O jO VlO oO 0� SM O 0�O O PO O \O `O 0�`O iO PiO jO \lO oO 0� �N �N 0��N �N 1� SM �N �O� �N �N �O� O ;O �O� SM M TM �M \�M �M T�M �M \�M �M T�M �N \�N �N \O ;O \ SM M UM �N S�N �N SO ;O S �M �M PDN SN 0�vN N PN �N V�N �N VO &O P&O ;O V �N �N ~ kM �N ^�N �N ^O ;O ^ �M �M P�M �M P�M �N _�N �N VO ;O _ kM �M 0��M �M ]�M N 0�N �N ]O ;O ] N -N P N -N U-N SN ��O ;O �� kM N 0�N cN ���N �N ��O ;O �� �M �M P N N U N DN \O O \ N -N U-N DN ��O O �� 9N CN PCN DN VO O P DN SN �� vN �N _ �N �N V �N �N _ �N �N _ �N �N V O O P O &O U&O 'O �� 'O ;O _ ,O ;O _ �N O S �N O _ O O _ ;O `O V `O jO V � C� UC� [� \[� `� �U�`� Ӎ UӍ q� \q� {� U{� � \� � U� D� \D� M� UM� C� \ � 0� T0� 0� V0� 8� v�8� H� V`� �� V�� � Vq� �� V� � VD� M� Vv� � V � � Q� k� �Q�k� ]� ]`� �� ]�� C� ] H� S� a� +� aM� ]� a� � a&� *� a*� 6� �� �� �� Q�� � R � *� r� �� *� P � O� QO� S� S`� �� S�� +� Sq� �� S� � SD� m� Sv� � S� � S� 6� S6� C� 0� � D� S� � S � � T4� B� T � � U4� D� U� � u t !� � !� Q!� %� v %� 4� v8� D� Q� � v �� �� P�� � ^� C� ^ �� � S� � S �� �� TԎ � T �� �� UԎ � U� � u t !� �� �� Q�� ˎ s ؎ � Q (� (� P8� 8� P W� W� R t� �� ]�� � T`� �� T�� � } pU� $0)� �D� M� Tv� �� T�� � } pU� $0)� � t� �� V�� � R`� �� R�� � pU� $0)�v "�D� M� Rv� �� R�� � pU� $0)�v "� t� S� 1�`� x� 1�x� x� r� ��A)��x� �� r� ��A)r� ��N)���� ˍ 1�ˍ � r� ��N)��� �� q ��� +� 1�q� m� 1�v� �� q ���� �� r� ��I)q ���� �� " r� ��I)r� ��N)q ���� �� 0 r� ��I)r� ��N)r� ��I)q ���� �� > r� ��I)r� ��N)r� ��I)r� ��T)q ���� �� L r� ��I)r� ��N)r� ��I)r� ��T)r� ��Y)q ���� �� x pU� $0)�v "#� ��I)pU� $0)�v "#� ��N)pU� $0)�v "#� ��I)u ��T)r ��Y)q ���� Ǐ � pU� $0)�v "#� ��I)pU� $0)�v "#� ��N)pU� $0)�v "#� ��I)pU� $0)�v "#� ��T)r ��Y)q ��Ǐ � � pU� $0)�v "#� ��I)pU� $0)�v "#� ��N)pU� $0)�v "#� ��I)pU� $0)�v "#� ��T)pU� $0)�v "#� ��Y)q ��� C� 1� t� �� P`� � Pv� � P �� �� pU� $0)��`� � pU� $0)��v� � pU� $0)�� +� q� \ C� e� P U� e� ae� q� �� U� e� P �P Q U Q Q �U�Q (Q U(Q �k �U� �P U 0�U �U 1�V |d 1��d �g 1��g `h 0�`h ^j 1�jj �k 1� �P $Q 0�$Q �k = � �P Q 0�Q (Q U(Q �k �U� �P �U 0�V ^ 0�^ "^ P"^ 8^ ^8^ N^ 0�N^ e^ Pe^ ^ ^^ �^ 0��^ �^ P�^ �^ ^�^ _ 0�_ _ P_ o_ ^o_ �_ 0��_ �_ P�_ �_ ^�_ �_ 0��_ �_ P�_ �_ ^�_ d 0�d |d ^�d }h 0�}h �h P�h �h 0��h �h P�h ^j 0�jj �j P�j �k 0� �P �U 0�V i^ 0�i^ ~^ P~^ �^ V�^ �^ 0��^ _ P _ _ V_ -_ 0�-_ K_ PK_ b_ Vb_ �_ 0��_ �_ P�_ ` V ` ` 0�` 7` P7` N` VN` {` 0�{` �` P�` �` V�` �` 0��` �` P�` a Va ?a 0�?a ]a P]a ta Vta �a 0��a �a P�a �a V�a b 0�b !b P!b 8b V8b eb 0�eb �b P�b �b V�b �b 0��b �b P�b �b V�b /c 0�/c Mc PMc dc Vdc �c 0��c �c P�c �c V�c �c 0��c �c P�c d Vd d 0� d +d P+d 9d V9d Gd PGd Ud VUd cd Pcd |d V�d �h 0��h �h P�h �h 0��h 0j P0j ^j 0�jj �k V �P �U 0�V od 0�od |d \�d ^j 0�jj �k 0� �P �U 0�V od 0�od |d � ��d ^j 0�jj �k 0� �P �U 0�V od 0�od |d ]�d ^j 0�jj �k 0� >U UU PUU �U \OV yV \�V �V \`h }h P �U �U U �U �U U Q Q U 9Q <Q P <Q PQ � � HQ PQ P HQ PQ P MQ PQ P `Q tQ � � lQ tQ P lQ tQ P qQ tQ P �Q �Q P�Q R X �Q �Q 0��Q R S �Q �Q @D$��Q R T �Q �Q 0��Q �Q P�Q �Q P�Q �Q 0� �Q �Q 0��Q �Q Q�Q �Q q��Q R Q R R � �3R �R � � R R 0�3R �R 0� R R P3R :R P:R xR �< R �U ���V �g ����g �k ��� �R �R �? �R �U = �V �g = �Fh �k = � �R T �3 ��g �g �3 � �R T 0��g �g 0� �R �R �? �R 4S 0�4S ;S P;S T \ T DT 0��g �g \ �R VS 0�VS _S P_S jS VjS oS PoS �S V�S �S P�S �S ]�S �S V�S �S ]�S �S V�S T UT T V ?S RS PRS T S�g �g S �S �S V�S �S V S $S P$S T ^�g �g ^ mS oS 1� �R S PS T _�g �g _ S 4S A� � (S 4S P (S 4S P 1S 4S P HS `S �R� jS mS �R� HS `S ^jS mS ^ HS RS PRS `S SjS mS S jS mS P �S �S 1��S �S 1� �S �S P�S �S ]�S �S ] �S �S ^�S �S ^ �S �S S�S �S S �S �S P�S �S V�S �S P �S �S P�S �S V �S �S ] �S �S V �S �S V�S T U �S �S V�S T U T T \ T T \ T T ^ TT U = � �T �T S�T U S �T �T �= ��T U V �T �T P�T �T P�T �T P�T �T P�T U P _U �U = ��V �V = � �V Y = �Y Y = � �V �V P�V Y \Y Y \ �X Y \ Y Y \ :Y �\ = ��d �g = � :Y �\ 0��d �g 0� :Y �\ 0��d �g 0� :Y �\ 0��d �g 0� �f �f P�f �g ] e �e R�e �e R�e �e p: �e �e R HY HY 9 �HY bY P HY ]Y p� ?e �e R�e �e R�e �e p: �e �e R ?e �e U�e �e @: �e �e U�e �e @: �e �e U ?e �e X�e �e X�e �e X ?e Ze Q�e �e Q�e �e Q ?e he The �e r�e �e T�e �e p: #�e �e T Me ae P�e �e P�e �e q 3$p: "#�e �e P Me ae P�e �e P�e �e q 3$p: "#�e �e P Ve ae pae �e Q �e �e 0��e �e p��e �e q 3$p: "##� �e �e p�e �e R pf �g ^ �f �f Pg g P2g Eg P f %f P%f <f ]<f Ff PFf �f ] �e �e 0��e f Pf f \f f P f �g \ %f <f \ <f Ff PFf pf ] Xf pf ^ pf ~f ] �f �f P g g P g g P 7g Eg U <g Eg U Kg Yg U Pg Yg U _g mg U dg mg U rg �g \ �Y �\ ^�d e ^ �Y �Z 0��Z �Z P�Z �Z 0��Z �Z ��}�Z [ 0�[ a[ ��}a[ {[ P�[ �[ 0��[ �[ ��}�[ �[ 0�\ \ �� \ B\ ��}L\ ]\ 0��d e ��} �Y EZ 0�EZ \Z P\Z �Z \�Z *[ \�[ �[ 0��[ �[ P�[ �[ \�[ �[ \L\ ]\ 0� �Y �Y 0��Y Z 0�Z Z P �Y �Y 0��Y �Y P�Y Z 0� Z Z PZ EZ \�[ �[ \L\ Z\ \ �Y bZ 0�bZ wZ PwZ �Z ��}�Z �Z P�Z �[ ��}�[ �[ 0��[ �[ P�[ B\ ��}L\ ]\ 0��d e ��} �Y !Z 0�!Z AZ PAZ �[ ��}�[ B\ ��}L\ ]\ P�d e ��} �Y �Z 0��Z �Z P�Z �Z 0��Z �Z P�Z �Z _�Z [ P[ �[ _�[ �[ 0��[ B\ _L\ ]\ 0��d e _ �Y *[ 0�*[ 7[ P7[ �[ \�[ �[ 0��[ B\ \L\ ]\ 0��d e P e e \ �Y J[ 0�J[ `[ P`[ �[ ]�[ �[ P�[ �[ ]�[ �[ 0��[ B\ ]L\ ]\ 0��d e 0� �Y �Y 0��Y �Y P�Y �Y \�Y Z PZ Z \ �Z �Z �> �Z �Z ^�Z �Z ^ �Z �Z P�Z �Z ��}�Z �Z P �Z �Z ~� i[ {[ ? i[ �[ ^�[ �[ ^ �[ �[ P�[ �[ ��}�[ �[ P i[ {[ ~� �[ \ ~ \ B\ ��} \ B\ ��} B\ L\ ��}]\ \ ��} ]\ \ ��} \ �\ _ �\ �\ _ �\ �\ \ �\ �\ \ �\ �\ ] �\ �\ ] �\ �] = ��d �d = �0j Mj = � �\ �\ 0��\ �\ P�\ �] \�d �d \�d �d U0j <j \ �\ |d 0��d �d 0�}h 0j 0�jj �k 0� �\ |d 0��d �d 0�}h 0j 0�jj �k 0� �\ |d 0��d �d 0�}h 0j 0�jj �k 0� �\ �] � ��d �d � � �\ �] ]� ��d �d ]� � �\ �] p��d �d p� �\ �] 8��d �d 8� �\ �] 1��d �d 1� �\ �\ P�\ �] \�d �d \ �\ �\ 0��\ �\ P�\ �] ]�d �d ] 5] Z] PZ] ~] } �] �] P�] �] ��} 5] J] Y �\ �\ P �\ �\ @K$� �\ �\ p �\ �\ p#� �d �d ] �d �d ] �] �] \ �d �d \�d �d U �d �d \�d �d U +^ 8^ ^ r^ ^ ^ �^ �^ ^ �^ �^ V _ _ V T_ b_ V b_ o_ ^ �_ �_ ^ �_ �_ ^ �_ ` V @` N` V �` �` V a a V fa ta V �a �a V *b 8b V �b �b V �b �b V Vc dc V �c �c V �c d V od |d ^ od |d ^ |d �d V^j jj 0��k �k V �d �d V ~H �H U�H �I ]�I �I �U� ~H �H T�H �I �T� ~H �H 0��H I 0�I I PI �I V *I QI PQI �I ^ �H I P I *I ^ �H �H P�H �H P �H �H \ �H �H \ I I ^ �I �I V �I �I V H H UH ~H �U� H H T H {H ]{H ~H �T� H H QH ~H �Q� H H RH }H ^}H ~H �R� H H XH 0H S0H SH �X�SH rH SrH ~H �X� H ?H P?H SH VSH ZH P H CH 0�CH SH \SH rH 0� CH SH V �q �q U�q �q �U� �q �q X �q �q U�q �q �U� �q �q X�q �q X �q �q X�q �q X �l �l U�l �l �U� �l �l T�l �l P�l �l �T��l �l P�l �l �T� �l �l Q�l �l �Q��l �l Q �l �l U�l �l �U� �p �p U�p �p V�p �p U�p �p �U��p q Vq $q U$q Oq VOq Pq �U� �p �p U�p �p V�p �p U�p �p �U��p q Vq $q U$q Oq VOq Pq �U� �p �p Uq q U �p �p Uq q U �p �p U�p q U �p �p U�p q U �� �� U�� q� �U�q� �� U�� � �U� �� �� T�� {� S{� �� �T��� � S� M� �T�M� �� S�� q� �T�q� �� S�� �� �T��� ܨ Sܨ � �T� �� �� Q�� {� V{� �� �Q��� �� V�� M� �Q�M� � V� /� �Q�/� ѧ Vѧ �� �Q��� >� V>� H� �Q�H� g� Vg� q� �Q�q� �� Q�� �� V�� �� �Q��� �� V�� � �Q� �� ä Pä �� \�� ;� \M� q� \�� � \ �� ä Pä �� \�� ;� \M� q� \�� �� P�� � \ � {� V{� �� �Q��� �� V�� 2� �Q�M� � V� /� �Q�/� ѧ Vѧ �� �Q��� >� V>� H� �Q�H� g� Vg� q� �Q��� �� �Q��� �� V�� � �Q� � {� S{� �� �T��� � S� 2� �T�M� �� S�� q� �T��� �� �T��� ܨ Sܨ � �T� � �� \�� 2� \M� q� \�� �� \�� � \ � �� 0��� � 0�� 2� ]M� � 0�� /� ]/� >� 0�>� H� ]H� q� 0��� �� ]�� �� 0��� � ] � �� 0��� � 0�� 2� VM� � 0�� /� V/� >� 0�>� H� VH� q� 0��� �� V�� �� 0��� � V � {� _�� � _M� �� _�� � �/� �� _H� g� _�� �� _ � �� 0��� ;� 0�M� q� 0��� � 0� � y� 0�y� �� <��� ;� 0�M� �� 0��� �� <��� 7� 0�7� >� <�>� g� 0�g� q� <��� �� 0��� �� 0��� �� <��� � 0� � y� 0�y� �� � ��� ;� 0�M� �� 0��� �� � ��� 7� 0�7� >� � �>� g� 0�g� q� � ��� �� 0��� �� 0��� �� � ��� � 0� � y� 0�y� {� ��� 2� 0�M� �� 0��� �� ]�� 7� 0�7� >� ��>� g� 0�g� q� ]�� �� 0��� �� 0��� �� ]�� � 0� � 2� S�� �� S � :� PM� Q� PQ� �� [�� ƨ [ƨ � ��~ g� �� _�� � �/� �� _H� g� _�� �� _ Q� U� P Q� U� P ^� b� P ^� b� P g� ߦ 0�/� �� 0�H� g� 0��� �� 0� g� ߦ o� �/� �� o� �H� g� o� ��� �� o� � g� �� [�� ƨ [ƨ � ��~ g� ߦ _/� �� _H� g� _�� �� _ g� ߦ ���/� �� ���H� g� ����� �� ��� g� ߦ ���/� �� ���H� g� ����� �� ��� g� ߦ 0�/� �� 0�H� g� 0��� �� 0� g� ߦ V/� �� VH� g� V�� �� V g� g� @F$� g� g� v g� g� v#� �� ֦ Z/� q� Zq� �� ��~H� g� ��~y� �� Z�� �� ��~ �� ͦ P �� ߦ S/� �� SH� g� Sy� �� S �� �� PH� P� P P� g� P P� ^� P P� ^� P 9� �� o� �y� �� o� � 9� �� ���y� �� ��� 9� �� ���y� �� ��� 9� q� Zq� �� ��~y� �� Z�� �� ��~ 9� 9� Z ʦ ֦ Q ʦ Ѧ Q ʦ Ѧ Q ¨ n� 0��� �� 0� ¨ n� o� ��� �� o� � ¨ � ��~ ¨ n� _�� �� _ ¨ n� ����� �� ��� ¨ n� ����� �� ��� ¨ ƨ Uƨ n� V�� �� V ¨ n� 0��� �� 0� ¨ n� o� ��� �� o� � ¨ � ��~ ¨ n� _�� �� _ ¨ n� ����� �� ��� ¨ n� ����� �� ��� ¨ ƨ Uƨ n� V�� �� V Ϩ � 3$� "` �� � S0� n� S�� �� S ¨ n� 3$� "` ��� �� 3$� "` � ¨ � 0�� � ��~� � R0� 4� R4� V� ��~�� �� R 0� 4� T � � P5� Z� P � �� 0��� � 1�0� n� 0� � �� P �� �� o� � �� �� 3$� "` � �� �� ��� �� �� V �� � 3$� "` �� "� Q Q� m� P�� �� P +� Q� o� ��� �� o� � +� Q� ����� �� ��� +� Q� 3$� "` ��� �� 3$� "` � +� Q� ����� �� ��� +� P� ���� �� �� +� +� �� ߦ � _�� >� _ �� 7� _ �� 7� 2� �� 7� 1� �� 7� o� � �� 7� 2� �� �� �� �� 7� g� � �� ȥ ] �� ȥ ] ۥ ۥ V ۥ ۥ V :� y� _ :� y� 2� :� y� 1� :� y� o� � :� y� 2� :� y� g� � y� y� 0�y� {� 1�{� �� 2��� ק 0�ק �� 1�g� q� 0��� �� 0� y� y� ��y� {� ���� ק Uק � ��g� k� U�� �� U ȧ ק U� � ��g� k� U � � V� /� V>� H� V�� � V � � ]� /� ]>� H� ]�� � ] � � \� /� \>� H� \�� � \ � � 0� � � S � � �� � � 0�� � V� � 0�� /� 0�>� H� V�� � V � � 0�� /� 0�>� H� 0��� � 0�� � >� � � 0�� /� 0�>� H� 0��� � 0�� � � � � � 0�� /� 0�>� H� 0��� � 0�� � ;� � � ]� � ] � � U� )� U � � V � � V � � U>� B� U �� � V �� � �� � �� ̪ p̪ � R � � V� � V � � V� � V � '� 0�'� 2� 1��� �� 1��� �� 0� � '� ]'� 2� V�� �� V�� �� ] � '� ]'� 2� V�� �� V�� �� ] �� �� \�� �� \ � �� U�� � �U�� -� U-� � �U�� � U� �� �U��� �� U�� ֱ �U� � �� T�� � �T�� -� T-� � �T�� � T� �� �T��� �� T�� ֱ �T� � �� Q�� ګ ]ګ � �Q�� -� Q-� � ]� G� �Q�G� � ]� � Q� :� ]:� �Q� J� ]J� X� �Q�X� �� ]�� �� �Q��� �� Q�� h� ]h� �� �Q��� m� ]m� �� �Q��� ֱ ] � �� R�� � �R�� -� R-� �� V�� G� �R�G� ǭ Vǭ � �R�� � R� �R� � V� s� �R�s� �� V�� �� �R��� �� R�� 0� V0� 5� �R�5� h� Vh� �� �R��� m� Vm� �� �R��� ֱ V � ګ 0�� �� 0��� � ��G� � 0�� [� �� � 0� � #� ��)� F� ��X� m� ��s� �� 0��� h� 0�u� � ���� m� 0��� ֱ 0� A� �� q 3$t "��� �� } 3$t "��� ګ } 3$�T"�ګ � �Q3$�T"�� -� q 3$t "�-� � } 3$�T"�� G� �Q3$�T"�G� � } 3$�T"�� � q 3$t "�� :� } 3$�T"�:� �Q3$�T"� J� } 3$�T"�J� X� �Q3$�T"�X� �� } 3$�T"��� �� �Q3$�T"��� �� q 3$t "��� h� } 3$�T"�h� �� �Q3$�T"��� m� } 3$�T"�m� �� �Q3$�T"��� ֱ } 3$�T"� A� �� 0��� ګ 3�� ѭ 0�ѭ � 3�� � 0�� � 3� � ֱ 0� A� �� 0��� ګ �� �� ѭ 0�ѭ � �� �� � 0�� � �� � � ֱ 0� A� �� 0��� �� ��� ѭ 0�ѭ � V� � 0�� � �� � ֱ 0� \� w� ^� �� ^G� � ^ � ^s� �� ^�� h� ^�� m� ^�� ֱ ^ � -� Q-� �� ]G� � ] � ]s� �� ]�� �� Q�� h� ]�� m� ]�� ֱ ] w� �� ] � ] � ] � 1� � �� � � 1� �� � g� � � �� P � �� P � w� 0�G� ѭ 0�s� �� 0��� h� 0��� m� 0��� ֱ 0� � w� �� �G� ѭ �� �s� �� �� ��� h� �� ��� m� �� ��� ֱ �� � � w� ^G� ѭ ^s� �� ^�� h� ^�� m� ^�� ֱ ^ � -� Q-� w� ]G� ѭ ]s� �� ]�� �� Q�� h� ]�� m� ]�� ֱ ] � w� ���G� ѭ ���s� �� ����� h� ����� m� ����� ֱ ��� � w� ���G� ѭ ���s� �� ����� h� ����� m� ����� ֱ ��� � -� q 3$t "�-� w� } 3$�T"�G� ѭ } 3$�T"�s� �� } 3$�T"��� �� q 3$t "��� h� } 3$�T"��� m� } 3$�T"��� ֱ } 3$�T"� � -� R-� w� VG� ǭ Vǭ ѭ �R�s� �� V�� �� R�� 0� V0� 5� �R�5� h� V�� m� V�� ֱ V � � @F$� � � P � � p� 8� n� [G� �� [�� ѭ ��~s� �� ��~5� X� [X� h� ��~ E� e� P -� w� SG� ѭ Ss� �� S5� h� S �� �� Ps� w� P w� �� P w� �� P w� �� P Y� �� �� �5� h� �� � Y� �� ���5� h� ��� Y� �� ���5� h� ��� Y� �� [�� �� ��~5� X� [X� h� ��~ Y� Y� [ b� n� Q b� i� Q b� i� Q �� +� 0��� m� 0��� ֱ 0� �� �� q 3$t "��� +� } 3$�T"��� m� } 3$�T"��� ֱ } 3$�T"� �� +� �� ��� m� �� ��� ֱ �� � �� +� ^�� m� ^�� ֱ ^ �� �� Q�� +� ]�� m� ]�� ֱ ] �� +� ����� m� ����� ֱ ��� �� +� ����� m� ����� ֱ ��� �� �� U�� +� V�� m� V�� ֱ V �� +� 0��� m� 0��� ֱ 0� �� +� �� ��� m� �� ��� ֱ �� � �� +� ^�� m� ^�� ֱ ^ �� �� Q�� +� ]�� m� ]�� ֱ ] �� +� ����� m� ����� ֱ ��� �� +� ����� m� ����� ֱ ��� �� �� U�� +� V�� m� V�� ֱ V �� ˯ } 3$� "P �˯ �� S� +� S�� �� S �� �� q 3$� "P ��� +� } 3$� "P ��� m� } 3$� "P ��� ֱ } 3$� "P � �� ˯ 0�˯ ۯ \ۯ � |�� �� \� +� \�� �� \ � � T ˯ � P � � P ˯ ׯ 0�ׯ � 1�� +� 0� ˯ ׯ P �� m� �� ��� ֱ �� � �� m� } 3$� "P ��� ֱ } 3$� "P � �� m� ����� ֱ ��� �� m� V�� ֱ V ̰ � } 3$� "P �� �� Q .� K� Pñ ֱ P � .� �� ��� ñ �� � � .� ����� ñ ��� � .� } 3$� "P ��� ñ } 3$� "P � � .� ����� ñ ��� � -� ���� ± �� � � �� � � S � � S �� �� 0�֭ � 0�� � 1� �� �� ��֭ � U ߭ � U � � 0�� ;� V w� �� Q�� �� ] w� �� 1� w� �� �� � w� �� 1� w� �� g� � �� � �U�� �U� � s� �U��� �� �U�h� �� �U�m� �� �U� �� � ��� [� �� � #� ��)� F� ��X� m� ��u� � �� �� G� 0�� 0� � s� 0��� �� 0�h� �� 0�m� �� 0� �� � 0�� G� 4�� 0� � s� 0��� �� 0�h� �� 0�m� �� 0� �� � 0�� G� �� �� 0� � s� 0��� �� 0�h� �� 0�m� �� 0� �� � 0�� G� ��� 0� � s� 0��� �� 0�h� �� 0�m� �� 0� �� � 0�� 0� � s� 0��� �� 0�h� �� 0�m� �� 0� �� � V� � V�� ] � )� \)� )� V)� @� 0��� �� Vu� �� Vm� �� ]�� �� V �� � \� o� \�� �� \ � #� U)� @� \X� s� \u� �� \�� �� \�� �� ] �� � 0�� �� 0��� �� P�� ] � s� 0��� �� 0�h� o� Po� u� ]u� �� 0�m� �� ]�� �� 0� �� �� @J$�)� )� @J$� �� �� U)� )� | �� �� u�)� )� |#� � � 0��� ]$� )� 0�n� s� 0��� �� 0��� �� 0� �� ] � � \.� .� \ � � @K$�.� .� @K$� � � P.� .� P � � @J$�5� 5� @J$� � � \5� 5� \ � � |�5� 5� |� -� H� 0�H� o� ]�� �� ] :� A� @J$� :� A� ] A� A� P \� h� P�� �� P � VJ� X� P�� �� Ph� u� Vm� �� V o� o� @F$� o� o� v o� o� v#� z� � V �� �� Vh� u� V �� �� @J$� �� �� R �� �� r� 0� �� U�� Ǟ [Ǟ �� �U��� =� U=� [� �U�[� {� U{� _� �U�_� b� Ub� o� [o� �� ��~�� {� �U� 0� �� T�� �� �T��� =� T=� [� �T�[� {� T{� _� �T�_� o� To� {� �T� 0� �� Q�� � ]� �� �Q��� =� Q=� L� ]L� �� �Q��� [� ][� {� Q{� �� ]�� �� �Q��� �� ]�� � �Q�� � ]� � �Q�� <� ]<� _� �Q�_� o� Qo� s� ]s� �� �Q��� {� ] 0� �� R�� �� �R��� =� R=� �� V�� �� �R��� /� V/� [� �R�[� {� R{� �� �R��� Ρ VΡ ڡ �R�ڡ �� V�� _� �R�_� o� Ro� � V� � �R� � H� VH� �� �R��� {� V 0� � 0��� �� 0��� � ���� {� 0��� �� 0�� "� ��_� H� 0��� {� 0� T� �� q 3$t "��� �� } 3$t "��� � } 3$�T"�� �� �Q3$�T"��� =� q 3$t "�=� L� } 3$�T"�L� �� �Q3$�T"��� [� } 3$�T"�[� {� q 3$t "�{� �� } 3$�T"��� �� �Q3$�T"��� �� } 3$�T"��� � �Q3$�T"�� � } 3$�T"�� � �Q3$�T"�� <� } 3$�T"�<� _� �Q3$�T"�_� o� q 3$t "�o� s� } 3$�T"�s� �� �Q3$�T"��� {� } 3$�T"� T� Ȟ 0�Ȟ � @��� 9� 0�9� [� @�[� ӡ 0�ӡ ڡ @�ڡ {� 0� T� Ȟ 0�Ȟ � � ��� 9� 0�9� [� � �[� ӡ 0�ӡ ڡ � �ڡ {� 0� T� Ȟ 0�Ȟ ʞ ���� 9� 0�9� [� V[� ӡ 0�ӡ ڡ ��ڡ {� 0� T� � 0��� p� 0�p� �� ]�� {� 0� o� �� Z�� =� Z_� o� Zo� �� ��~ � =� Q=� �� ]�� [� ]�� �� ]_� o� Qo� H� ]�� {� ] �� �� ]�� ڡ ] �� ӡ ] �� ӡ 1� �� ӡ _� � �� ӡ 1� �� �� �� �� ӡ g� � � � P � � P � �� 0��� 9� 0�ڡ �� 0�_� H� 0��� {� 0� � �� _� ��� 9� _� �ڡ �� _� �_� H� _� ��� {� _� � � =� Z_� o� Zo� �� ��~ � =� Q=� �� ]�� 9� ]ڡ �� ]_� o� Qo� H� ]�� {� ] � �� ����� 9� ���ڡ �� ���_� H� ����� {� ��� � �� ����� 9� ���ڡ �� ���_� H� ����� {� ��� � =� q 3$t "�=� �� } 3$�T"��� 9� } 3$�T"�ڡ �� } 3$�T"�_� o� q 3$t "�o� H� } 3$�T"��� {� } 3$�T"� � =� R=� �� V�� /� V/� 9� �R�ڡ �� V_� o� Ro� � V� � �R� � H� V�� {� V � � @F$� � � P � � p� H� ~� Y�� � Y� 9� ��~ڡ �� ��~ � 4� Y4� H� ��~ U� u� P =� �� S�� 9� Sڡ �� S � H� S � � Pڡ ޡ P ޡ �� P ޡ � P ޡ � P �� � _� � � H� _� � �� � ��� � H� ��� �� � ��� � H� ��� �� � Y� � ��~ � 4� Y4� H� ��~ �� �� Y r� ~� Q r� y� Q r� y� Q k� � 0��� {� 0� k� o� q 3$t "�o� � } 3$�T"��� {� } 3$�T"� k� � _� ��� {� _� � k� �� ��~ k� o� Qo� � ]�� {� ] k� � ����� {� ��� k� � ����� {� ��� k� o� Uo� � V�� {� V k� � 0��� {� 0� k� � _� ��� {� _� � k� �� ��~ k� o� Qo� � ]�� {� ] k� � ����� {� ��� k� � ����� {� ��� k� o� Uo� � V�� {� V x� �� } 3$� "P ��� Ţ SԢ � S�� �� S k� o� q 3$� "P �o� � } 3$� "P ��� {� } 3$� "P � k� �� 0��� �� \�� �� |��� Ţ \Ԣ � \�� �� \ Ԣ آ T �� �� P٢ � P �� �� 0��� �� 1�Ԣ � 0� �� �� P �� {� } 3$� "P � �� {� ��� �� {� V ң � } 3$� "P �� �� Q %� 9� Pp� {� P � %� _� �[� p� _� � � %� ���[� p� ��� � %� } 3$� "P �[� p� } 3$� "P � � %� ���[� p� ��� � $� ��[� o� �� � � �� m� q� S m� q� S Ȟ ʞ 0�>� V� 0�V� [� 1� Ȟ ʞ ��>� U� U G� U� U p� y� 0�y� �� V �� �� Q�� Ȟ ] �� Ȟ 1� �� Ȟ _� � �� Ȟ 1� �� Ȟ g� � �� � ��� "� �� �� � [� "� [ �� p� 0�p� p� ]{� �� 0��� � 0�� _� 0�H� �� 0� �� L� 0�L� R� PR� p� ]{� �� 0��� �� P�� �� ]�� � ]� _� 0�H� s� 0�s� x� Px� x� ]x� �� 0� �� � 0� � R� ^R� p� 0�{� �� ^�� _� 0�H� �� 0� �� �� 0��� � V� g� _g� p� 0�{� �� _�� � _� � 0�� <� VH� x� Vx� �� 0��� �� V �� � 0�� ]� \]� p� 0�{� �� \�� � 0�� � \� _� 0�H� x� \x� �� 0� � � 1� � R� 0�{� �� 1��� �� 0�H� x� 1� �� p� 0�{� �� 0��� +� 0�+� _� D�H� x� 0�x� �� D� �� p� 0�{� �� 0��� +� 0�+� _� � �H� x� 0�x� �� � � �� p� 0�{� �� 0��� +� 0�+� <� ��H� x� 0�x� �� ���� �� �� �� �� V ʟ ʟ @H$� ʟ ʟ P ʟ ʟ p� � � V � R� _{� �� _ � � ^ � � _ � R� V{� �� V � � V{� �� V L� R� ^�� �� ^s� x� 0� L� R� ^�� �� ^ R� ]� \� � \ ]� g� _�� � _ +� <� Vx� �� 0��� �� V +� <� V�� �� V 0� �� U�� �� �U��� =� U=� c� �U�c� �� U�� n� �U�n� q� Uq� 7� �U� 0� �� T�� �� �T��� =� T=� c� �T�c� �� T�� n� �T�n� z� Tz� 7� �T� 0� �� Q�� � ]� �� �Q��� =� Q=� � ]� �� �Q��� c� ]c� �� Q�� �� �Q��� � ]� T� �Q�T� \� ]\� n� �Q�n� z� Qz� ?� ]?� �� �Q��� �� ]�� � �Q� � �� ]�� � �Q� � 7� ] 0� �� R�� �� �R��� =� R=� �� V�� �� �R��� 7� V7� c� �R�c� �� R�� �� �R��� � V� n� �R�n� z� Rz� � V � � �R�� 8� V8� � �R� � � V� � �R�� �� V�� � �R� � 7� V 0� � 0��� �� 0��� � ���� �� 0��� � 0�T� \� ��n� 8� 0�8� J� ���� �� �� � �� 0� � 7� 0� Q� �� q 3$t "��� �� } 3$t "��� � } 3$�T"�� �� �Q3$�T"��� =� q 3$t "�=� � } 3$�T"�� �� �Q3$�T"��� c� } 3$�T"�c� �� q 3$t "��� �� �Q3$�T"��� � } 3$�T"�� T� �Q3$�T"�T� \� } 3$�T"�\� n� �Q3$�T"�n� z� q 3$t "�z� ?� } 3$�T"�?� �� �Q3$�T"��� �� } 3$�T"��� � �Q3$�T"� � �� } 3$�T"��� � �Q3$�T"� � 7� } 3$�T"� Q� ŵ 0�ŵ � 1��� A� 0�A� c� 1�c� � 0�� �� 1��� 7� 0� Q� ŵ 0�ŵ � � ��� A� 0�A� c� � �c� � 0�� �� � ��� 7� 0� Q� ŵ 0�ŵ ǵ J��� A� 0�A� c� Vc� � 0�� �� >��� 7� 0� Q� � 0��� �� 0��� 7� 0� l� �� ^�� �� ^�� c� ^�� � ^n� 8� ^ � �� ^ � 7� ^ � =� Q=� �� ]�� c� ]�� � ]n� z� Qz� 8� ] � �� ] � 7� ] �� �� ]�� �� }��� �� ] � � ] �� � ] �� � 1� �� � �� � �� � 1� �� �� �� �� � g� � � � P � � P � �� 0��� A� 0��� � 0�n� 8� 0�� �� 0� � 7� 0� � �� �� ��� A� �� ��� � �� �n� 8� �� �� �� �� � � 7� �� � � �� ^�� A� ^�� � ^n� 8� ^� �� ^ � 7� ^ � =� Q=� �� ]�� A� ]�� � ]n� z� Qz� 8� ]� �� ] � 7� ] � �� ����� A� ����� � ���n� 8� ���� �� ��� � 7� ��� � �� ����� A� ����� � ���n� 8� ���� �� ��� � 7� ��� � =� q 3$t "�=� �� } 3$�T"��� A� } 3$�T"��� � } 3$�T"�n� z� q 3$t "�z� 8� } 3$�T"�� �� } 3$�T"� � 7� } 3$�T"� � =� R=� �� V�� 7� V7� A� �R��� � Vn� z� Rz� � V � � �R�� 8� V� �� V � 7� V � � @F$� � � P � � p� H� ~� [�� �� [�� A� ��~�� � ��~� (� [(� 8� ��~ U� u� P =� �� S�� A� S�� � S� 8� S � !� P�� �� P �� � P �� � P �� � P ɷ � �� �� 8� �� � ɷ � ���� 8� ��� ɷ � ���� 8� ��� ɷ �� [�� � ��~� (� [(� 8� ��~ ɷ ɷ [ r� ~� Q r� y� Q r� y� Q v� �� 0�� �� 0� � 7� 0� v� z� q 3$t "�z� �� } 3$�T"�� �� } 3$�T"� � 7� } 3$�T"� v� �� �� �� �� �� � � 7� �� � v� �� ^� �� ^ � 7� ^ v� z� Qz� �� ]� �� ] � 7� ] v� �� ���� �� ��� � 7� ��� v� �� ���� �� ��� � 7� ��� v� z� Uz� �� V� �� V � 7� V v� �� 0�� �� 0� � 7� 0� v� �� �� �� �� �� � � 7� �� � v� �� ^� �� ^ � 7� ^ v� z� Qz� �� ]� �� ] � 7� ] v� �� ���� �� ��� � 7� ��� v� �� ���� �� ��� � 7� ��� v� z� Uz� �� V� �� V � 7� V � �� } 3$� "P ��� Sع �� S� "� S v� z� q 3$� "P �z� �� } 3$� "P �� �� } 3$� "P � � 7� } 3$� "P � v� �� 0��� �� \�� �� |��� \ع �� \� "� \ ع ܹ T �� �� Pݹ � P �� �� 0��� �� 1�ع �� 0� �� �� P "� �� �� � � 7� �� � "� �� } 3$� "P � � 7� } 3$� "P � "� �� ��� � 7� ��� "� �� V � 7� V `� u� } 3$� "P �u� �� Q �� P'� 7� P �� �� �� � � '� �� � �� �� ��� � '� ��� �� �� } 3$� "P � � '� } 3$� "P � �� �� ��� � '� ��� �� �� �� � &� �� �� �� �� u� �� V u� �� V ŵ ǵ 0�F� ^� 0�^� c� 1� ŵ ǵ ��F� ]� U O� ]� U �� �� 0��� �� 1� �� �� Q�� ŵ ] �� ŵ 1� �� ŵ �� � �� ŵ 1� �� ŵ g� � �� �� �U��� �� �U�� n� �U�8� � �U��� � �U� �� � ���� �� \�� �� \� � \T� \� ��8� J� ���� �� �� �� �� 0��� �� \�� �� ]�� �� 0�� � ] � n� 0�8� � 0��� � 0� �� h� 0�h� h� Ph� �� \�� �� \�� �� 0��� �� \ � )� 0�T� n� 0�8� �� 0��� � P� � \�� � 0� �� h� 0�h� �� 0��� �� 0� � )� 0�T� n� 0�8� �� 0��� � _�� � _ �� � 0�� ,� \,� �� 0��� �� 0��� �� \�� �� 0� � )� \T� \� 0�\� n� \8� �� 0��� �� \�� �� U�� �� \�� � 0��� � 0� �� � 0�� h� ]h� r� ^r� �� 0��� �� ^�� �� ]�� �� 0� � )� 0�T� n� 0�8� �� 0��� �� ]�� � ^�� � ^ ,� h� 1��� ̺ 1�̺ � 0��� � 1� �� �� 0��� �� 0� � )� 3�T� \� 0�\� n� 3�8� � 0��� � 0� �� �� 0��� �� 0� � )� � �T� \� 0�\� n� � �8� � 0��� � 0� �� �� 0��� �� 0� � )� ��T� \� 0�\� n� ��8� � 0��� � 0� �� �� �� ?� �� �< � ?� �� �< � ?� �� ] N� U� PU� �� \ � � \ � � \ p� �� �< � p� �� �< � p� �� ] �� � T�� �� T �� � \�� �� U�� �� \ �� � P � � |�� �� u #� ,� \�� �� \ � )� \\� n� \ � )� \\� n� \ ,� ,� ] h� h� 0��� � _ �� � _ h� r� ^�� �� ^ �� �� \ �� �� \� � \ �� �� \� � \ � � 0� �� � ^�� � ^ �� �� _ �� �� ^ �� � ]�� � ] �� ̺ ]�� � ] @� ɼ Uɼ � �U�� M� UM� s� �U�s� �� U�� ~� �U�~� �� U�� G� �U� @� Ƽ TƼ � �T�� M� TM� s� �T�s� �� T�� ~� �T�~� �� T�� G� �T� @� �� Q�� � ]� � �Q�� M� QM� �� ]�� Ͼ �Q�Ͼ s� ]s� �� Q�� ¿ �Q�¿ "� ]"� d� �Q�d� l� ]l� ~� �Q�~� �� Q�� O� ]O� �� �Q��� �� ]�� � �Q�� � ] � � �Q� � G� ] @� �� R�� � �R�� M� RM� �� V�� Ͼ �R�Ͼ G� VG� s� �R�s� �� R�� � �R�� "� V"� ~� �R�~� �� R�� � V� � �R�� H� VH� � �R�� � V � )� �R�)� � V � � �R� � G� V @� �� 0�� �� 0��� �� ��Ͼ �� 0�¿ "� 0�d� l� ��~� H� 0�H� Z� ���� �� ��� � 0� � G� 0� a� �� q 3$t "��� Ƽ } 3$t "�Ƽ � } 3$�T"�� � �Q3$�T"�� M� q 3$t "�M� �� } 3$�T"��� Ͼ �Q3$�T"�Ͼ s� } 3$�T"�s� �� q 3$t "��� ¿ �Q3$�T"�¿ "� } 3$�T"�"� d� �Q3$�T"�d� l� } 3$�T"�l� ~� �Q3$�T"�~� �� q 3$t "��� O� } 3$�T"�O� �� �Q3$�T"��� �� } 3$�T"��� � �Q3$�T"�� � } 3$�T"� � � �Q3$�T"� � G� } 3$�T"� a� ռ 0�ռ �� +�� Q� 0�Q� s� +�s� � 0� � � +�� G� 0� a� ռ 0�ռ �� � �� Q� 0�Q� s� � �s� � 0� � � � �� G� 0� a� ռ 0�ռ ��� Q� 0�Q� s� Vs� � 0� � � x�� G� 0� a� �� 0�� �� 0�Ͼ G� 0� |� �� ^� �� ^Ͼ s� ^¿ "� ^~� H� ^� � ^ � G� ^ (� M� QM� �� ]Ͼ s� ]¿ "� ]~� �� Q�� H� ]� � ] � G� ] �� �� ]�� �� }�¿ � ]� )� ] ¿ � ] ¿ � 1� ¿ � �� � ¿ � 1� ¿ ¿ �� ¿ � g� � � � P � � P (� �� 0�Ͼ Q� 0�� "� 0�~� H� 0�)� � 0� � G� 0� (� �� �� �Ͼ Q� �� �� "� �� �~� H� �� �)� � �� � � G� �� � (� �� ^Ͼ Q� ^� "� ^~� H� ^)� � ^ � G� ^ (� M� QM� �� ]Ͼ Q� ]� "� ]~� �� Q�� H� ])� � ] � G� ] (� �� ���Ͼ Q� ���� "� ���~� H� ���)� � ��� � G� ��� (� �� ���Ͼ Q� ���� "� ���~� H� ���)� � ��� � G� ��� (� M� q 3$t "�M� �� } 3$�T"�Ͼ Q� } 3$�T"�� "� } 3$�T"�~� �� q 3$t "��� H� } 3$�T"�)� � } 3$�T"� � G� } 3$�T"� (� M� RM� �� VϾ G� VG� Q� �R�� "� V~� �� R�� � V� � �R�� H� V)� � V � G� V (� (� @F$� (� (� P (� (� p� X� �� [Ͼ � [ � Q� ��~� "� ��~� 8� [8� H� ��~ e� �� P M� �� SϾ Q� S� "� S� H� S � 1� P� � P � "� P � � P � � P پ � �� �� H� �� � پ � ���� H� ��� پ � ���� H� ��� پ � [ � � ��~� 8� [8� H� ��~ پ پ [ �� �� Q �� �� Q �� �� Q �� � 0�)� � 0� � G� 0� �� �� q 3$t "��� � } 3$�T"�)� � } 3$�T"� � G� } 3$�T"� �� � �� �)� � �� � � G� �� � �� � ^)� � ^ � G� ^ �� �� Q�� � ])� � ] � G� ] �� � ���)� � ��� � G� ��� �� � ���)� � ��� � G� ��� �� �� U�� � V)� � V � G� V �� � 0�)� � 0� � G� 0� �� � �� �)� � �� � � G� �� � �� � ^)� � ^ � G� ^ �� �� Q�� � ])� � ] � G� ] �� � ���)� � ��� � G� ��� �� � ���)� � ��� � G� ��� �� �� U�� � V)� � V � G� V �� �� } 3$� "P ��� � S� � S)� 2� S �� �� q 3$� "P ��� � } 3$� "P �)� � } 3$� "P � � G� } 3$� "P � �� �� 0��� �� \�� � |�� � \� � \)� 2� \ � � T �� � P� � P �� �� 0��� � 1�� � 0� �� �� P 2� � �� � � G� �� � 2� � } 3$� "P � � G� } 3$� "P � 2� � ��� � G� ��� 2� � V � G� V p� �� } 3$� "P ��� �� Q �� �� P7� G� P �� �� �� � � 7� �� � �� �� ��� � 7� ��� �� �� } 3$� "P � � 7� } 3$� "P � �� �� ��� � 7� ��� �� �� �� � 6� �� �� �� �� �� �� V �� �� V ռ 0�V� n� 0�n� s� 1� ռ ��V� m� U _� m� U �� ʾ 0�ʾ ʾ 1� �� �� Q�� ռ ] �� ռ 1� �� ռ �� � �� ռ 1� �� ռ g� � �� �� �U��� ¿ �U�"� ~� �U�H� � �U� � � �U� �� �� ���� �� \�� ¿ \"� /� \d� l� ��H� Z� ���� �� �� �� �� 0��� �� \�� �� ]�� ¿ 0�"� /� ]/� ~� 0�H� � 0� � � 0� �� x� 0�x� x� Px� �� \�� �� \�� �� 0��� ¿ \/� 9� 0�d� ~� 0�H� � 0�� � P� � \ � � 0� �� x� 0�x� �� 0��� ¿ 0�/� 9� 0�d� ~� 0�H� � 0�� � _ � � _ �� �� 0��� <� \<� �� 0��� �� 0��� �� \�� ¿ 0�/� 9� \d� l� 0�l� ~� \H� �� 0��� �� \�� �� U�� �� \�� � 0� � � 0� �� � 0� � x� ]x� �� ^�� �� 0��� �� ^�� �� ]�� ¿ 0�/� 9� 0�d� ~� 0�H� �� 0��� � ]� � ^ � � ^ <� x� 1��� � 1�� � 0� � � 1� �� �� 0��� ¿ 0�/� 9� -�d� l� 0�l� ~� -�H� � 0� � � 0� �� �� 0��� ¿ 0�/� 9� � �d� l� 0�l� ~� � �H� � 0� � � 0� �� �� 0��� ¿ 0�/� 9� ��d� l� 0�l� ~� ��H� � 0� � � 0� �� ǽ �� O� �� �< � O� �� �< � O� �� ] ^� e� Pe� �� \ �� �� \ �� �� \ �� �� �< � �� �� �< � �� �� ] � � T�� �� T � � \�� �� U�� �� \ � � P� � |�� �� u 3� <� \�� �� \ /� 9� \l� ~� \ /� 9� \l� ~� \ <� <� ] x� x� 0�� � _ � � _ x� �� ^�� �� ^ �� �� \ �� �� \"� /� \ �� �� \"� /� \ /� /� 0� � � ^ � � ^ � � _ � � ^ � � ] � � ] � � ] � � ] P� �� U�� � �U� � ]� U]� �� �U��� �� U�� �� �U��� �� U�� W� �U� P� �� T�� � �T� � ]� T]� �� �T��� �� T�� �� �T��� �� T�� W� �T� P� �� Q�� � ]� � �Q� � ]� Q]� � ]� �� �Q��� �� ]�� �� Q�� �� �Q��� 2� ]2� t� �Q�t� |� ]|� �� �Q��� �� Q�� _� ]_� �� �Q��� �� ]�� +� �Q�+� � ]� -� �Q�-� W� ] P� �� R�� � �R� � ]� R]� �� V�� �� �R��� W� VW� �� �R��� �� R�� � �R�� 2� V2� �� �R��� �� R�� � V � %� �R�%� X� VX� +� �R�+� 0� V0� 9� �R�9� � V� -� �R�-� W� V P� � 0� � �� 0��� � ���� �� 0��� 2� 0�t� |� ���� X� 0�X� j� ���� �� ��+� � 0�-� W� 0� q� �� q 3$t "��� �� } 3$t "��� � } 3$�T"�� � �Q3$�T"� � ]� q 3$t "�]� � } 3$�T"�� �� �Q3$�T"��� �� } 3$�T"��� �� q 3$t "��� �� �Q3$�T"��� 2� } 3$�T"�2� t� �Q3$�T"�t� |� } 3$�T"�|� �� �Q3$�T"��� �� q 3$t "��� _� } 3$�T"�_� �� �Q3$�T"��� �� } 3$�T"��� +� �Q3$�T"�+� � } 3$�T"�� -� �Q3$�T"�-� W� } 3$�T"� q� �� 0��� � &� � a� 0�a� �� &��� � 0�� � &�� W� 0� q� �� 0��� � � � � a� 0�a� �� � ��� � 0�� � � �� W� 0� q� �� 0��� �� � � � a� 0�a� �� V�� � 0�� � � �� W� 0� q� � 0� � �� 0��� W� 0� �� �� ^ � �� ^�� �� ^�� 2� ^�� X� ^+� � ^-� W� ^ 8� ]� Q]� �� ]�� �� ]�� 2� ]�� �� Q�� X� ]+� � ]-� W� ] �� �� ]�� �� }��� � ]+� 9� ] �� � ] �� � 1� �� � �� � �� � 1� �� �� �� �� � g� � #� '� P #� '� P 8� �� 0��� a� 0�� 2� 0��� X� 0�9� � 0�-� W� 0� 8� �� �� ��� a� �� �� 2� �� ��� X� �� �9� � �� �-� W� �� � 8� �� ^�� a� ^� 2� ^�� X� ^9� � ^-� W� ^ 8� ]� Q]� �� ]�� a� ]� 2� ]�� �� Q�� X� ]9� � ]-� W� ] 8� �� ����� a� ���� 2� ����� X� ���9� � ���-� W� ��� 8� �� ����� a� ���� 2� ����� X� ���9� � ���-� W� ��� 8� ]� q 3$t "�]� �� } 3$�T"��� a� } 3$�T"�� 2� } 3$�T"��� �� q 3$t "��� X� } 3$�T"�9� � } 3$�T"�-� W� } 3$�T"� 8� ]� R]� �� V�� W� VW� a� �R�� 2� V�� �� R�� � V � %� �R�%� X� V9� � V-� W� V 8� 8� @F$� 8� 8� P 8� 8� p� h� �� [�� � [ � a� ��~� 2� ��~%� H� [H� X� ��~ u� �� P ]� �� S�� a� S� 2� S%� X� S (� A� P� � P � 2� P � )� P � )� P �� (� �� �%� X� �� � �� (� ���%� X� ��� �� (� ���%� X� ��� �� � [ � (� ��~%� H� [H� X� ��~ �� �� [ �� �� Q �� �� Q �� �� Q �� � 0�9� � 0�-� W� 0� �� �� q 3$t "��� � } 3$�T"�9� � } 3$�T"�-� W� } 3$�T"� �� � �� �9� � �� �-� W� �� � �� � ^9� � ^-� W� ^ �� �� Q�� � ]9� � ]-� W� ] �� � ���9� � ���-� W� ��� �� � ���9� � ���-� W� ��� �� �� U�� � V9� � V-� W� V �� � 0�9� � 0�-� W� 0� �� � �� �9� � �� �-� W� �� � �� � ^9� � ^-� W� ^ �� �� Q�� � ]9� � ]-� W� ] �� � ���9� � ���-� W� ��� �� � ���9� � ���-� W� ��� �� �� U�� � V9� � V-� W� V �� �� } 3$� "P ��� �� S�� � S9� B� S �� �� q 3$� "P ��� � } 3$� "P �9� � } 3$� "P �-� W� } 3$� "P � �� �� 0��� �� \�� �� |��� �� \�� � \9� B� \ �� �� T �� �� P�� � P �� �� 0��� �� 1��� � 0� �� �� P B� � �� �-� W� �� � B� � } 3$� "P �-� W� } 3$� "P � B� � ���-� W� ��� B� � V-� W� V �� �� } 3$� "P ��� �� Q �� �� PG� W� P �� �� �� �-� G� �� � �� �� ���-� G� ��� �� �� } 3$� "P �-� G� } 3$� "P � �� �� ���-� G� ��� �� �� ��-� F� �� �� �� �� �� �� V �� �� V �� �� 0�f� ~� 0�~� �� 1� �� �� ��f� }� U o� }� U �� �� 0��� �� 1� �� �� Q�� �� ] �� �� 1� �� �� �� � �� �� 1� �� �� g� � �� �� �U��� �� �U�2� �� �U�X� +� �U�� -� �U� �� � ���� �� \�� �� \2� ?� \t� |� ��X� j� ���� �� �� �� �� 0��� �� \�� �� ]�� �� 0�2� ?� ]?� �� 0�X� +� 0�� -� 0� �� �� 0��� �� P�� �� \�� �� \�� �� 0��� �� \?� I� 0�t� �� 0�X� � 0�� %� P%� +� \� -� 0� �� �� 0��� �� 0��� �� 0�?� I� 0�t� �� 0�X� �� 0��� +� _� -� _ �� � 0� � L� \L� �� 0��� �� 0��� �� \�� �� 0�?� I� \t� |� 0�|� �� \X� �� 0��� �� \�� �� U�� �� \�� +� 0�� -� 0� �� .� 0�.� �� ]�� �� ^�� �� 0��� �� ^�� �� ]�� �� 0�?� I� 0�t� �� 0�X� �� 0��� �� ]�� +� ^� -� ^ L� �� 1��� �� 1��� +� 0�� -� 1� �� �� 0��� �� 0�?� I� (�t� |� 0�|� �� (�X� +� 0�� -� 0� �� �� 0��� �� 0�?� I� � �t� |� 0�|� �� � �X� +� 0�� -� 0� �� �� 0��� �� 0�?� I� � �t� |� 0�|� �� � �X� +� 0�� -� 0� �� �� �� _� �� �< � _� �� �< � _� �� ] n� u� Pu� �� \ � � \ � � \ �� �� �< � �� �� �< � �� �� ] � *� T�� �� T � .� \�� �� U�� �� \ � � P � *� |�� �� u C� L� \�� �� \ ?� I� \|� �� \ ?� I� \|� �� \ L� L� ] �� �� 0�� +� _ � +� _ �� �� ^�� �� ^ �� �� \ �� �� \2� ?� \ �� �� \2� ?� \ ?� ?� 0� �� +� ^� -� ^ �� �� _ �� �� ^ �� +� ]� -� ] �� �� ]� -� ] `� �� U�� /� �U�/� m� Um� s� �U�s� �� U�� 5� �U�5� 8� U8� � �U� `� �� T�� /� �T�/� m� Tm� s� �T�s� �� T�� 5� �T�5� A� TA� � �T� `� �� Q�� � ]� /� �Q�/� m� Qm� F� ]F� �� �Q��� �� ]�� �� �Q��� s� ]s� �� Q�� 5� ]5� A� QA� � ]� � �Q�� �� ]�� @� �Q�@� ~� ]~� � �Q�� P� ]P� � �Q� � :� ]:� }� �Q�}� �� ]�� �� �Q��� �� ]�� � �Q� `� �� R�� /� �R�/� m� Rm� �� V�� �� �R��� G� VG� s� �R�s� �� R�� �� V�� �� �R��� �� V�� 5� �R�5� A� RA� �� V�� �� �R��� �� V�� c� �R�c� +� V+� T� �R�T� t� Vt� � �R� `� � 0�/� �� 0��� =� ��~�� �� ��~�� �� 0��� 5� ��~5� �� 0��� �� ��~� � ��~F� U� ��~c� +� 0�+� F� ��~T� t� 0� � '� ��~ �� �� q 3$t "��� �� } 3$t "��� � } 3$�T"�� /� �Q3$�T"�/� m� q 3$t "�m� F� } 3$�T"�F� �� �Q3$�T"��� �� } 3$�T"��� �� �Q3$�T"��� s� } 3$�T"�s� �� q 3$t "��� 5� } 3$�T"�5� A� q 3$t "�A� � } 3$�T"�� � �Q3$�T"�� �� } 3$�T"��� @� �Q3$�T"�@� ~� } 3$�T"�~� � �Q3$�T"�� P� } 3$�T"�P� � �Q3$�T"� � :� } 3$�T"�:� }� �Q3$�T"�}� �� } 3$�T"��� �� �Q3$�T"��� �� } 3$�T"��� � �Q3$�T"� �� �� 0��� � J�/� Q� 0�Q� s� J�s� �� 0��� �� J��� � 0� �� �� 0��� � � �/� Q� 0�Q� s� � �s� �� 0��� �� � ��� � 0� �� �� 0��� �� 2 �/� Q� 0�Q� s� Vs� �� 0��� �� & ��� � 0� �� � 0�/� �� 0��� �� ]�� � 0� �� �� Y/� m� Y5� A� YA� ^� ��~ H� m� Qm� �� ]�� s� ]�� �� ]5� A� QA� �� ]c� +� ]T� t� ] �� �� ]�� �� ] �� �� ] �� �� 1� �� �� �� � �� �� 1� �� �� �� �� �� g� � 3� 7� P 3� 7� P H� �� 0��� Q� 0��� �� 0�5� �� 0�c� +� 0�T� t� 0� H� �� �� ��� Q� �� ��� �� �� �5� �� �� �c� +� �� �T� t� �� � H� m� Y5� A� YA� ^� ��~ H� m� Qm� �� ]�� Q� ]�� �� ]5� A� QA� �� ]c� +� ]T� t� ] H� �� ��~��� Q� ��~��� �� ��~�5� �� ��~�c� +� ��~�T� t� ��~� H� �� ����� Q� ����� �� ���5� �� ���c� +� ���T� t� ��� H� m� q 3$t "�m� �� } 3$�T"��� Q� } 3$�T"��� �� } 3$�T"�5� A� q 3$t "�A� �� } 3$�T"�c� +� } 3$�T"�T� t� } 3$�T"� H� m� Rm� �� V�� G� VG� Q� �R��� �� V5� A� RA� �� V�� �� �R��� �� Vc� +� VT� t� V H� H� @F$� H� H� P H� H� p� x� �� [�� � [ � Q� ��~�� �� ��~�� �� [�� �� ��~ �� �� P m� �� S�� Q� S�� �� S�� �� S � 1� P�� �� P �� �� P �� �� P �� �� P �� � �� ��� �� �� � �� � ����� �� ��� �� � ����� �� ��� �� � [ � � ��~�� �� [�� �� ��~ �� �� [ �� �� Q �� �� Q �� �� Q =� �� 0�c� +� 0�T� t� 0� =� A� q 3$t "�A� �� } 3$�T"�c� +� } 3$�T"�T� t� } 3$�T"� =� �� �� �c� +� �� �T� t� �� � =� ^� ��~ =� A� QA� �� ]c� +� ]T� t� ] =� �� ��~�c� +� ��~�T� t� ��~� =� �� ���c� +� ���T� t� ��� =� A� UA� �� Vc� +� VT� t� V =� �� 0�c� +� 0�T� t� 0� =� �� �� �c� +� �� �T� t� �� � =� ^� ��~ =� A� QA� �� ]c� +� ]T� t� ] =� �� ��~�c� +� ��~�T� t� ��~� =� �� ���c� +� ���T� t� ��� =� A� UA� �� Vc� +� VT� t� V F� ^� } 3$� "p �^� �� S�� �� Sc� l� S =� A� q 3$� "p �A� �� } 3$� "p �c� +� } 3$� "p �T� t� } 3$� "p � =� ^� 0�^� k� \k� s� |�s� �� \�� �� \c� l� \ �� �� T ^� s� P�� �� P ^� g� 0�g� s� 1��� �� 0� ^� g� P l� +� �� �T� t� �� � l� +� } 3$� "p �T� t� } 3$� "p � l� +� ���T� t� ��� l� +� VT� t� V �� �� } 3$� "p ��� �� Q �� � Pi� t� P �� �� �� �T� i� �� � �� �� ���T� i� ��� �� �� } 3$� "p �T� i� } 3$� "p � �� �� ���T� i� ��� �� �� ��T� h� �� �� �� �� �� �� S �� �� S �� �� 0�V� n� 0�n� s� 1� �� �� ��~V� m� U _� m� U �� �� 0��� �� V �� �� Q�� �� ] �� �� 1� �� �� �� � �� �� 1� �� �� g� � �� �� �U��� 5� �U��� c� �U�+� T� �U�t� � �U� �� =� ��~�� �� ��~�� 5� ��~�� �� ��~� � ��~F� U� ��~+� F� ��~ � '� ��~ �� �� 0��� �� ]�� 5� 0��� c� 0�+� T� 0�t� � 0� �� �� 0��� 5� 0��� c� 0�+� T� 0�t� � 0� �� h� 0�h� m� ]�� �� 0��� 5� 0��� c� 0�+� T� 0�t� � 0� �� m� 0�m� �� K��� �� 0��� 5� 0��� c� 0�+� T� 0�t� � 0� �� m� 0�m� �� � ��� �� 0��� 5� 0��� c� 0�+� T� 0�t� � 0� �� m� 0�m� �� \ ��� �� 0��� 5� 0��� c� 0�+� T� 0�t� � 0� �� �� ��~ �� =� ��~�� 5� ��~�� �� ��~� � ��~F� U� ��~+� F� ��~ � '� ��~ >� N� aN� `� � �`� d� aV� c� aG� T� a "� =� ��~,� 5� ��~ 6� =� T 6� =� Q � � ��~ � '� ��~ 4� 8� P 0� �� � �� �� a2� � � � �� a�� �� ��~�� � � �� �� ]c� �� ] �� �� 0��� d� V� � V:� �� V�� $� V}� 2� V~� �� V�� � V�� �� V � �� _�� � ]� � Q� � q�)� @� ]@� ~� _~� �� ]�� �� Q�� �� q��� �� ]�� d� Q� P� _P� t� ]t� x� Qx� �� q��� �� ]�� �� Q:� Q� Q}� �� _�� �� Q�� �� _�� �� Q~� �� Q�� �� Q �� �� X�� � ~ 7�:� �� ~ 7��� � ~ 7� �� � \:� � \ �� � Q� 0� U�� � U:� �� U�� �� U�� �� Q�� �� U�� �� Q�� �� U�� 2� U�� �� U.� :� U �� � V� 0� P�� �� P�� �� q�:� �� P�� �� P�� �� V�� �� P�� �� V�� �� P�� � P� � q�� $� P�� �� P.� o� P �� 0� X�� � X:� �� X�� $� X�� �� X�� 2� X�� �� X �� 0� \�� � \:� �� \�� $� \�� �� \�� 2� \�� �� \ �� �� 1��� �� 1��� �� r ���� �� p � $�O$)r ��:� w� 1�w� w� r ���� �� q ���� �� q ���� �� | u "� � $�O$)q ���� �� . | u "� � $�O$)| u "#� � $�O$)q ���� � C | u "� � $�O$)| u "#� � $�O$)| u "#� � $�O$)q ��� � q ��� � p � $�O$)q ���� �� 1��� � 1�� � r ��� -� 1�-� 2� r ��2� �� 1��� �� 1��� �� r ���� �� 1��� �� r ���� �� q ���� �� | u "� � ��I)q ���� �� , | u "� � ��I)| u "#� � ��N)q ���� #� @ | u "� � ��I)| u "#� � ��N)| u "#� � ��I)q ��#� .� q ��.� .� | r "� ��I)q ��.� .� * | r "� ��I)| p "#� ��N)q ��.� 4� = | r "� ��I)| p "#� ��N)| p "#� ��I)q ��4� o� ? | p "#� ��I)| p "#� ��N)| p "#� ��I)q ��~� �� q ���� � 1� �� �� q 2$| "�� �� Pe� n� q 2$| "n� q� Rq� w� p2$| "w� z� Q�� �� r 2$| "�� �� | u "#�� �� | u "#�� � | u "# � � P�� � q 1$| "� ���� $� | p "#���$� '� q ���� �� q 1$| "� ����� �� r ����� �� p1$| "� ����� �� | p "#����� �� r 1$| "� ����� �� | u "#� ����� �� | u "#� ����� .� | u "#� ���.� .� | p "#���.� .� | p "#���.� .� | p "#���.� o� | p "#���o� r� u �� �� d� T�� � T:� $� T�� �� P�� �� T�� �� P�� �� T�� 2� T~� �� T�� �� T�� �� T �� � tU � $0)���� �� tU ��0)���� �� tU �0$0)�� :� d� ���d� �� ]2� ~� ]~� �� ����� �� ] :� d� 1�d� �� R�� �� T�� �� R2� [� R[� p� Tp� ~� R~� �� 1��� �� X�� �� R�� �� X :� �� V2� �� V h� �� Q7� ~� q ����� �� q �� �� �� R[� ~� R�� �� X F� k� P U� k� ak� }� ��~ U� k� P �� � P� s� Us� �� ��~�� � U �� � P� c� ]�� � ] �� � 1�� 9� R9� M� TM� V� R�� �� R�� �� T�� �� R�� �� X�� �� R�� � X �� c� V�� � V � V� Q�� �� q ����� � q �� 9� V� R�� �� R�� � X F� U� ��~ F� N� s �N� U� TU� V� s � F� U� s � �� U�� �� �U��� -� U-� �� �U��� �� U�� '� �U�'� *� U*� � �U� � �� T�� �� �T��� -� T-� �� �T��� �� T�� '� �T�'� 3� T3� � �T� � �� Q�� �� ]�� �� �Q��� -� Q-� �� ]�� �� �Q��� �� ]�� �� Q�� �� ]�� �� �Q��� '� ]'� 3� Q3� �� ]�� � �Q� � � ] � �� R�� �� �R��� -� R-� �� V�� �� �R��� g� Vg� �� �R��� �� R�� �� �R��� � V � � �R� � '� V'� 3� R3� �� V�� �� �R��� �� V�� � �R� � � V � �� 0��� �� 0��� �� S�� �� 0��� �� S�� �� 0��� � S � � 0� A� �� q 3$t "��� �� } 3$t "��� �� } 3$�T"��� �� �Q3$�T"��� -� q 3$t "�-� �� } 3$�T"��� �� �Q3$�T"��� �� } 3$�T"��� �� q 3$t "��� �� } 3$�T"��� �� �Q3$�T"��� '� } 3$�T"�'� 3� q 3$t "�3� �� } 3$�T"��� � �Q3$�T"� � � } 3$�T"� A� �� 0��� �� G��� q� 0�q� �� G��� � 0�� � G� � � 0� A� �� 0��� �� � ��� q� 0�q� �� � ��� � 0�� � � � � � 0� A� �� 0��� �� � ��� q� 0�q� �� V�� � 0�� � � � � � 0� A� �� 0��� �� 0��� �� ]�� � 0� \� w� ^�� �� ^�� �� ^�� �� ^ � � ^ � -� Q-� �� ]�� �� ]�� '� ]'� 3� Q3� �� ] � � ] w� �� ]�� � ] �� � ] �� � 1� �� � �� � �� � 1� �� �� �� �� � g� � �� �� P �� �� P � w� 0��� q� 0� � �� 0� � � 0� � w� �� ��� q� �� � � �� �� � � � �� � � w� ^�� q� ^ � �� ^ � � ^ � -� Q-� w� ]�� q� ] � '� ]'� 3� Q3� �� ] � � ] � w� ����� q� ��� � �� ��� � � ��� � w� ����� q� ��� � �� ��� � � ��� � -� q 3$t "�-� w� } 3$�T"��� q� } 3$�T"� � '� } 3$�T"�'� 3� q 3$t "�3� �� } 3$�T"� � � } 3$�T"� � -� R-� w� V�� g� Vg� q� �R� � '� V'� 3� R3� �� V�� �� �R��� �� V � � V � � @F$� � � P � � p� 8� n� [�� -� [-� q� ��~ � '� ��~�� �� [�� �� ��~ E� e� P -� w� S�� q� S � '� S�� �� S 8� Q� P � � P � '� P � � P � � P �� 8� �� ��� �� �� � �� 8� ����� �� ��� �� 8� ����� �� ��� �� -� [-� 8� ��~�� �� [�� �� ��~ �� �� [ b� n� Q b� i� Q b� i� Q /� �� 0� � � 0� /� 3� q 3$t "�3� �� } 3$�T"� � � } 3$�T"� /� �� �� � � � �� � /� �� ^ � � ^ /� 3� Q3� �� ] � � ] /� �� ��� � � ��� /� �� ��� � � ��� /� 3� U3� �� V � � V /� �� 0� � � 0� /� �� �� � � � �� � /� �� ^ � � ^ /� 3� Q3� �� ] � � ] /� �� ��� � � ��� /� �� ��� � � ��� /� 3� U3� �� V � � V 8� P� } 3$� "P �P� |� S�� �� S � � S /� 3� q 3$� "P �3� �� } 3$� "P � � � } 3$� "P � /� P� 0�P� [� \[� c� |�c� |� \�� �� \ � � \ �� �� T P� c� P�� �� P P� W� 0�W� c� 1��� �� 0� P� W� P � � } 3$� "P � � � ��� � � V P� e� } 3$� "P �e� z� Q �� �� P� � P �� �� �� ��� � �� � �� �� ����� � ��� �� �� } 3$� "P ��� � } 3$� "P � �� �� ����� � ��� �� �� ���� � �� �� �� �� �� �� S �� �� S �� �� 0�v� �� 0��� �� 1� �� �� ��v� �� U � �� U �� �� 0��� �� V �� �� S �� �� S w� �� Q�� �� ] w� �� 1� w� �� �� � w� �� 1� w� �� g� � �� �� �U��� �� U�� �� �U��� � �U� �� �� S�� �� S�� � S �� �� 0��� �� ]�� �� 0��� � 0� �� �� 0��� �� 0��� � 0� �� �� 0��� �� P�� �� 0��� � P� � ] �� �� 0��� �� 0��� �� 0��� � H� �� �� 0��� �� 0��� �� 0��� � � � �� �� 0��� �� 0��� �� 0��� � � � � �� U�� �� �U��� -� U-� �� �U��� �� U�� �� �U��� �� U�� G� �U� � �� T�� �� �T��� -� T-� �� �T��� �� T�� �� �T��� �� T�� G� �T� � �� Q�� �� ]�� �� �Q��� -� Q-� �� ]�� � �Q�� �� ]�� �� Q�� � �Q�� |� ]|� �� �Q��� �� Q�� G� ] � �� R�� �� �R��� -� R-� �� V�� � �R�� �� V�� �� �R��� �� R�� � �R�� N� VN� Z� �R�Z� u� Vu� �� �R��� �� R�� � V � � �R�� G� V � �� 0��� �� 0��� �� ��� �� 0��� �� ��� u� 0�u� �� ���� G� 0� A� �� q 3$t "��� �� } 3$t "��� �� } 3$�T"��� �� �Q3$�T"��� -� q 3$t "�-� �� } 3$�T"��� � �Q3$�T"�� �� } 3$�T"��� �� q 3$t "��� � �Q3$�T"�� |� } 3$�T"�|� �� �Q3$�T"��� �� q 3$t "��� G� } 3$�T"� A� �� 0��� �� B��� �� 0��� �� B��� S� 0�S� Z� B�Z� G� 0� A� �� 0��� �� � ��� �� 0��� �� � ��� S� 0�S� Z� � �Z� G� 0� A� �� 0��� �� � ��� �� 0��� �� V�� S� 0�S� Z� � �Z� G� 0� A� �� 0��� �� 0��� � ]� G� 0� \� w� ^�� �� ^� �� ^� u� ^�� G� ^ � -� Q-� �� ]� �� ]� u� ]�� �� Q�� G� ] w� �� ]� Z� ] � S� ] � S� 1� � S� �� � � S� 1� � � �� � S� g� � �� �� P �� �� P � w� 0�� �� 0�Z� u� 0��� G� 0� � w� �� �� �� �� �Z� u� �� ��� G� �� � � w� ^� �� ^Z� u� ^�� G� ^ � -� Q-� w� ]� �� ]Z� u� ]�� �� Q�� G� ] � w� ���� �� ���Z� u� ����� G� ��� � w� ���� �� ���Z� u� ����� G� ��� � -� q 3$t "�-� w� } 3$�T"�� �� } 3$�T"�Z� u� } 3$�T"��� �� q 3$t "��� G� } 3$�T"� � -� R-� w� V� �� V�� �� �R�Z� u� V�� �� R�� � V � � �R�� G� V � � @F$� � � P � � p� 8� n� [� M� [M� �� ��~Z� u� ��~� 3� [3� C� ��~ E� e� P -� w� S� �� SZ� u� S� C� S X� q� PZ� ^� P ^� u� P ^� l� P ^� l� P � X� �� �� C� �� � � X� ���� C� ��� � X� ���� C� ��� � M� [M� X� ��~� 3� [3� C� ��~ � � [ b� n� Q b� i� Q b� i� Q �� � 0�C� G� 0� �� �� q 3$t "��� � } 3$�T"�C� G� } 3$�T"� �� � �� �C� G� �� � �� � ^C� G� ^ �� �� Q�� � ]C� G� ] �� � ���C� G� ��� �� � ���C� G� ��� �� �� U�� � VC� G� V �� � 0�C� G� 0� �� � �� �C� G� �� � �� � ^C� G� ^ �� �� Q�� � ]C� G� ] �� � ���C� G� ��� �� � ���C� G� ��� �� �� U�� � VC� G� V �� �� } 3$� "P ��� �� S�� � SC� L� S �� �� q 3$� "P ��� � } 3$� "P �C� G� } 3$� "P � �� �� 0��� �� \�� �� |��� �� \�� � \C� L� \ �� �� T �� �� P�� �� P �� �� 0��� �� 1��� � 0� �� �� P L� G� } 3$� "P � L� G� ��� L� G� V �� �� } 3$� "P ��� �� Q �� �� P7� G� P �� �� �� � � 7� �� � �� �� ��� � 7� ��� �� �� } 3$� "P � � 7� } 3$� "P � �� �� ��� � 7� ��� �� �� �� � 6� �� �� �� �� �� �� S �� �� S �� �� 0��� �� 0��� �� 1� �� �� ���� �� U �� �� U �� �� 0��� �� V w� �� Q�� �� ] w� �� 1� w� �� �� � w� �� 1� w� �� g� � �� �� �U��� � �U�u� �� �U� �� �� ���� �� ��u� �� �� �� �� 0��� �� ]�� � 0�u� u� 0� �� �� P�� �� P�� � P �� �� 0��� �� 0��� � 0�u� �� 0� �� �� 0��� �� 0��� � E�u� �� 0� �� �� 0��� �� 0��� � � �u� �� 0� �� �� 0��� �� 0��� � 9 �u� �� 0� �� �� ���� �� �� �� �� p ���� �� p ���� �� s v )�� �l �l P �l �l P 0o Ao UAo Bo �U�Bo Lo ULo Mo �U� 0o Ao TAo Bo �T�Bo Lo TLo Mo �T� 0o Ao uBo Lo u �t �t U�t Pu SPu [u �U�[u au Sau eu �U� �t �t T�t Wu VWu Zu PZu [u �T�[u bu Vbu eu �T� �t �t Q�t Yu \Yu Zu TZu [u �Q�[u du \du eu �Q� �t �t P �t �t P �t �t P �t Yu \Yu Zu TZu [u �Q� �t Wu VWu Zu PZu [u �T� �t Pu SPu [u �U� �t �t P �t �t P u u P u u P +u /u P @u Du P �I J UJ !J �U� �I �I T�I �I Q�I J T J J QJ !J �T� �I �I Q�I �I �Q��I J QJ !J �Q� �I J u �I �I U �I �I @K$� �I �I u �I �I u#� �I �I U �I �I Q�I �I �Q� �I �I T�I �I Q Pv �v U�v �v �U��v �v U�v �v V�v w �U� w w Uw w Vw %w U%w &w �U�&w Ew VEw Zw UZw �x V�x y ��y Hy VHy ]y ��]y gy Vgy ty ��ty �y V�y �y �� Pv �v T�v �v ^�v �v Q�v �v �T��v �v T�v �v ^�v w �T� w w Tw !w ^!w %w th�%w :w �T�:w Cw ^Cw Ew �T�Ew x ^x ty �T�ty �y ^�y �y �T��y �y ^�y �y �T� Pv �v Q�v �v R�v �v �Q��v �v Q�v �v \�v w �Q� w w Qw w \ w &w �Q�&w Ew \Ew gw Qgw �x \�x y �Q�y Hy \Hy ]y �Q�]y �y \ Pv �v U�v �v �U��v �v U�v �v V�v w �U� w w Uw w Vw %w U%w &w �U�&w Ew VEw Zw UZw �x V�x y ��y Hy VHy ]y ��]y gy Vgy ty ��ty �y V�y �y �� kv �v X�v �v X w %w XEw gw Xgw �w ��~ty �y ��~ �v �v Q�v �v R�v �v �Q� �v �v T�v �v ^�v �v Q�v �v �T� �v �v U�v �v �U� �v �v u �v �v Q�v �v \&w Cw \y Hy \]y gy \ �v �v T�v �v ^�v �v �T�&w :w �T�:w Cw ^y Hy �T�]y gy �T� �v �v U�v �v V&w Cw Vy Hy V]y gy V �v �v P&w 7w P7w :w ^ �v �v t�v �v Q �v �v P�v �v ]&w :w ]:w Cw Py Hy ]]y gy ] �v �v P�v �v ^y 'y P'y Hy ^]y dy Pdy gy ^ �v �v ]&w :w ] y 'y ]]y gy ] w w Qw w \ w &w �Q�Ew gw Qgw �x \�x y �Q�Hy ]y �Q�gy �y \ w #w _#w %w txEw �x _�x �x ��ty �y _�y �y �� w %w T%w &w �T#�Ew gw Tgw x ~�x y �T#�Hy ]y �T#�gy ty �T#�ty �y ~��y �y �T#��y �y ~��y �y �T#� w %w XEw gw Xgw �w ��~ty �y ��~ w w Uw w Vw %w U%w &w �U�Ew Zw UZw �x V�x y ��Hy ]y ��gy ty ��ty �y V�y �y �� Qw gw Pgw y ��~Hy ]y ��~gy �y ��~ _w gw Qgw �x \�x y �Q�Hy Xy �Q�gy �y \ _w �x _�x �x ��ty �y _�y �y �� _w gw Tgw x ~�x y �T#�Hy Xy �T#�gy ty �T#�ty �y ~��y �y �T#��y �y ~��y �y �T#� _w �w ��~ty �y ��~ _w �x V�x y ��Hy Xy ��gy ty ��ty �y V�y �y �� _w �x 0��x y ^Hy Xy ^gy ty ^ty �y 0� �w �w P�w y ��~Hy Xy ��~gy ty ��~�y �y P�y �y ��~ kw �w P�w �x ]�x y ��Hy Xy ��gy ty ��ty �y ]�y �y P�y �y ]�y �y �� x Ix PIx y ��~Hy Xy ��~gy ty ��~�y �y ��~ x Ix 0�Ix �x ^�x �x 0��x y V tw �w 0��w �w P�w �w p�ty vy 0�vy �y P Bx Ix @H$�Ix �x S�y �y S _w gw Pgw y ��~Hy Xy ��~gy �y ��~ ex nx P nx rx Q �x �x ��~gy ty S y y U �y z Uz z �U�z #z U#z *z �U�*z Az UAz Mz �U� �y �y T*z >z T>z Mz �T� �y z Qz z �Q�z 'z Q'z *z �Q�*z Ez QEz Mz �Q� �y �y @I$� �y �y t �y �y t#� �y �y T �y �y T z z Xz 'z X z z Xz 'z X z z Xz 'z X *z Az UAz Fz �U� *z >z T>z Fz �T� *z Ez QEz Fz �Q� Pz �z U�z �z V�z �z �U��z �z V�z �z U�z �z V Pz pz T�z �z S Pz |z Q|z �z �Q��z �z Q�z �z �Q� �z �z U�z �z U �z �z U�z �z U �z �z U�z �z U �z �z @I$� �z �z s �z �z s#� �z �z U�z �z V �z �z S �z �z Q�z �z �Q� �z &{ U&{ P{ VP{ Q{ �U�Q{ _{ V_{ ~{ U~{ �{ V �z { T_{ �{ S �z { Q { _{ �Q�_{ �{ Q�{ �{ �Q� 6{ H{ UQ{ \{ U ={ H{ UQ{ \{ U B{ H{ UQ{ \{ U _{ _{ @F$� _{ _{ s _{ _{ s#� m{ ~{ U~{ �{ V m{ �{ S m{ �{ Q�{ �{ �Q� �{ �{ U�{ �{ �U��{ �{ U�{ �{ �U��{ �{ U�{ �{ �U��{ | U| | �U� �{ �{ T�{ �{ �T��{ �{ T�{ �{ �T��{ �{ T�{ �{ �T��{ | T| | �T� �{ �{ Q�{ �{ �Q��{ �{ Q�{ �{ �Q��{ �{ Q�{ �{ �Q��{ | Q| | �Q� �{ �{ @I$� �{ �{ t �{ �{ t#� �{ �{ T �{ �{ X�{ �{ X �{ �{ X�{ �{ X �{ �{ X�{ �{ X �{ | U| | �U� �{ | T| | �T� �{ | Q| | �Q� | M| UM| T| �U�T| [| U[| b| �U�b| y| Uy| �| �U� | M| TM| T| �T�T| _| T_| b| �T�b| v| Tv| �| �T� | M| QM| T| �Q�T| _| Q_| b| �Q�b| }| Q}| �| �Q� )| )| @H$� )| )| t )| )| t#� 6| >| T >| M| XT| _| X B| M| XT| _| X G| M| XT| _| X b| y| Uy| ~| �U� b| v| Tv| ~| �T� b| }| Q}| ~| �Q� �| �| U�| �| �U��| �| U�| �| �U��| �| U�| �| �U� �| �| T�| �| �T��| �| T�| �| �T��| �| T�| �| �T� �| �| Q�| �| �Q��| �| Q�| �| �Q��| �| Q�| �| �Q� �| �| @H$� �| �| t �| �| t#� �| �| T �| �| X�| �| X �| �| X�| �| X �| �| X�| �| X �| �| U�| �| �U� �| �| T�| �| �T� �| �| Q�| �| �Q� !J >J U>J �J S K K S !J bJ TbJ )K �� !J 6J Q6J K V K )K �Q� !J bJ RbJ $K ]$K )K �R� !J bJ XbJ )K �� KJ K 0� K K \ KJ �J 0��J �J P�J K \ KJ bJ QbJ )K �� cJ {J P{J K ^ !J )K �b7 � �J �J P �J �J R K K ^ )K 2K U2K pK �U� <