diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 28be75c9..c5dddef3 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -23,8 +23,13 @@ Use Markdown syntax, see https://docs.github.com/github/writing-on-github/gettin diff --git a/.github/ISSUE_TEMPLATE/general-questions-and-runtime-problems.md b/.github/ISSUE_TEMPLATE/general-questions-and-runtime-problems.md deleted file mode 100644 index 78d92d70..00000000 --- a/.github/ISSUE_TEMPLATE/general-questions-and-runtime-problems.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -name: Questions and Runtime Problems -about: For general python-oracledb questions -title: '' -labels: question -assignees: '' - ---- - - diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 07ee2888..d75527f8 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -1,22 +1,57 @@ -name: build +name: Build python-oracledb packages on: push: tags: - v* workflow_dispatch: + inputs: + tgt: + description: List of package targets to build + default: 'Linux, macOS, Windows, Source' + required: false jobs: + build_source_package: + name: Build source package + if: contains(inputs.tgt, 'Source') || inputs.tgt == '' + runs-on: ubuntu-latest + steps: + + - uses: actions/checkout@v4 + with: + submodules: true + + - uses: actions/setup-python@v5 + with: + cache: 'pip' + python-version: 3.13 + + - name: Ensure build package is present + run: python -m pip install setuptools + + - name: Build wheel for Python ${{ matrix.python-version }} + run: python setup.py sdist + + - name: Upload the artifact + uses: actions/upload-artifact@v4 + with: + name: python-oracledb-source + path: dist + build_linux_wheels: name: Build wheels for Linux - runs-on: ubuntu-latest + if: contains(inputs.tgt, 'Linux') || inputs.tgt == '' + runs-on: ${{ matrix.os }} strategy: matrix: include: - - platform: amd64 + - os: ubuntu-24.04 + platform: amd64 container: quay.io/pypa/manylinux_2_28_x86_64 - - platform: arm64 + - os: ubuntu-24.04-arm + platform: arm64 container: quay.io/pypa/manylinux_2_28_aarch64 steps: @@ -25,20 +60,15 @@ jobs: with: submodules: true - - name: Set up QEMU - uses: docker/setup-qemu-action@v3 - with: - platforms: ${{ matrix.platform }} - - name: Generate script run: | echo export PYO_COMPILE_ARGS=-g0 > build.sh - echo /opt/python/cp38-cp38/bin/python3.8 -m build >> build.sh echo /opt/python/cp39-cp39/bin/python3.9 -m build >> build.sh echo /opt/python/cp310-cp310/bin/python3.10 -m build >> build.sh echo /opt/python/cp311-cp311/bin/python3.11 -m build >> build.sh echo /opt/python/cp312-cp312/bin/python3.12 -m build >> build.sh echo /opt/python/cp313-cp313/bin/python3.13 -m build >> build.sh + echo /opt/python/cp314-cp314/bin/python3.14 -m build >> build.sh echo cd dist >> build.sh echo auditwheel repair *.whl >> build.sh echo rm *.whl >> build.sh @@ -58,19 +88,51 @@ jobs: uses: actions/upload-artifact@v4 with: name: Linux_${{ matrix.platform }}_wheels - path: dist + path: dist/*.whl + + build_macos_wheels: + name: Build wheels for ${{ matrix.os }} Python-${{ matrix.python-version}}-${{ matrix.arch }} + if: contains(inputs.tgt, 'macOS') || inputs.tgt == '' + runs-on: ${{ matrix.os }} + strategy: + matrix: + os: [macos-latest] + python-version: ['3.9', '3.10', '3.11', '3.12', '3.13', '3.14'] + arch: [''] + + steps: + - uses: actions/checkout@v4 + with: + submodules: true + + - uses: actions/setup-python@v5 + with: + cache: 'pip' + python-version: ${{ matrix.python-version }} + architecture: ${{ matrix.arch }} + allow-prereleases: true + + - name: Ensure build package is present + run: python -m pip install build + + - name: Build wheel for Python ${{ matrix.python-version }} + run: python -m build + + - name: Upload the artifact + uses: actions/upload-artifact@v4 + with: + name: python-oracledb-${{ matrix.os }}-${{ matrix.python-version }}-${{ matrix.arch }} + path: dist/*.whl - build_non_linux_wheels: + build_windows_wheels: name: Build wheels for ${{ matrix.os }} Python-${{ matrix.python-version}}-${{ matrix.arch }} + if: contains(inputs.tgt, 'Windows') || inputs.tgt == '' runs-on: ${{ matrix.os }} strategy: matrix: - os: [windows-latest, macos-latest] - python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13'] + os: [windows-latest] + python-version: ['3.9', '3.10', '3.11', '3.12', '3.13.5', '3.14'] arch: ['x86', ''] - exclude: - - os: macos-latest - arch: x86 steps: - uses: actions/checkout@v4 @@ -98,7 +160,8 @@ jobs: combine_artifacts: name: Combine artifacts into single artifact - needs: [build_linux_wheels, build_non_linux_wheels] + if: ${{ always() }} + needs: [build_source_package, build_linux_wheels, build_macos_wheels, build_windows_wheels] runs-on: ubuntu-latest steps: diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index d8110b62..80da1bc9 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -7,10 +7,11 @@ repos: - id: check-yaml - id: check-added-large-files - repo: https://github.com/psf/black-pre-commit-mirror - rev: 24.4.2 + rev: 25.1.0 hooks: - id: black - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.0.291 hooks: - id: ruff + exclude: ^samples/tutorial/ diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 8ecaf936..1a6c05d2 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -6,6 +6,11 @@ build: tools: python: "3.9" +# ensure that the submodules are included +submodules: + include: all + recursive: true + # Build documentation in the doc/src directory with Sphinx sphinx: configuration: doc/src/conf.py @@ -14,3 +19,5 @@ sphinx: python: install: - requirements: doc/requirements.txt + - method: pip + path: . diff --git a/NOTICE.txt b/NOTICE.txt index bc88e116..4cd6fb08 100644 --- a/NOTICE.txt +++ b/NOTICE.txt @@ -1 +1 @@ -Copyright (c) 2016, 2024, Oracle and/or its affiliates. +Copyright (c) 2016, 2025, Oracle and/or its affiliates. diff --git a/README.md b/README.md index b2b48dd7..41358be8 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,71 @@ # python-oracledb -python-oracledb is a [Python programming language][python] extension module -allowing Python programs to connect to [Oracle Database][oracledb]. -Python-oracledb is the new name for Oracle's popular cx_Oracle driver. +The python-oracledb driver is the widely used, open-source [Python][python] +extension module allowing Python programs to connect directly to [Oracle +Database][oracledb] with no extra libraries needed. The module is built with +Cython for safety and speed. It is lightweight and high-performance. It is +stable, well tested, and has comprehensive [documentation][documentation]. The +module is maintained by Oracle. The module conforms to the [Python Database API 2.0 specification][pep249] with a considerable number of additions and a couple of minor exclusions, see the -[feature list][features]. +[feature list][features]. It is used by many Python frameworks, SQL generators, +ORMs, and libraries. -Synchronous and [concurrent][concurrent] coding styles are supported. +Python-oracledb has a rich feature set which is easy to use. It gives you +control over SQL and PL/SQL statement execution; for working with data frames; +for fast data ingestion; for calling NoSQL-style document APIs; for message +queueing; for receiving database notifications; and for starting and stopping +the database. It also has high availability and security features. Synchronous +and [concurrent][concurrent] coding styles are supported. Database operations +can optionally be [pipelined][pipelining]. -## Installation +Python-oracledb is the successor to the now obsolete cx_Oracle driver. -Run `python -m pip install oracledb` +## Python-oracledb Installation -See [python-oracledb Installation][installation]. +Run: + +``` +python -m pip install oracledb --upgrade +``` + +See [Installing python-oracledb][installation] for details. + +## Samples + +Examples can be found in the [/samples][samples] directory and the +[Python and Oracle Database Tutorial][tutorial]. + +A basic example: + +``` +import oracledb +import getpass + +un = "scott" # Sample database username +cs = "localhost/orclpdb" # Sample database connection string +# cs = "localhost/freepdb1" # For Oracle Database Free users +# cs = "localhost/orclpdb1" # Some databases may have this service +pw = getpass.getpass(f"Enter password for {un}@{cs}: ") + +with oracledb.connect(user=un, password=pw, dsn=cs) as connection: + with connection.cursor() as cursor: + sql = "select sysdate from dual" + for r in cursor.execute(sql): + print(r) +``` ## Dependencies and Interoperability -- Python versions 3.8 through 3.13. +- Python versions 3.9 through 3.14. - Prebuilt packages are available for these Python versions on Windows, on - macOS and on Linux. + Pre-built packages are available on [PyPI][pypi] and other repositories. Source code is also available. + Previous versions of python-oracledb supported older Python versions. + - Oracle Client libraries are *optional*. **Thin mode**: By default python-oracledb runs in a 'Thin' mode which @@ -34,7 +75,7 @@ See [python-oracledb Installation][installation]. available when optional Oracle Client libraries are loaded by python-oracledb. Libraries are available in the free [Oracle Instant Client][instantclient] packages. Python-oracledb can use Oracle Client - libraries 11.2 through 21c. + libraries versions 11.2 through 23, inclusive. - Oracle Database @@ -43,7 +84,7 @@ See [python-oracledb Installation][installation]. **Thick mode**: Oracle Database 9.2 (or later) is required, depending on the Oracle Client library version. Oracle Database's standard client-server version interoperability allows connection to both older and newer - databases. For example when python-oracledb uses Oracle Client 19c libraries, + databases. For example when python-oracledb uses Oracle Client 19 libraries, then it can connect to Oracle Database 11.2 or later. ## Documentation @@ -51,14 +92,9 @@ See [python-oracledb Installation][installation]. See the [python-oracledb Documentation][documentation] and [Release Notes][relnotes]. -## Samples - -Examples can be found in the [/samples][samples] directory and the -[Python and Oracle Database Tutorial][tutorial]. - ## Help -Questions can be asked in [Github Discussions][ghdiscussions]. +Questions can be asked in [GitHub Discussions][ghdiscussions]. Problem reports can be raised in [GitHub Issues][ghissues]. @@ -98,3 +134,5 @@ See [LICENSE][license], [THIRD_PARTY_LICENSES][tplicense], and [installation]: https://python-oracledb.readthedocs.io/en/latest/user_guide/installation.html [features]: https://oracle.github.io/python-oracledb/#features [concurrent]: https://python-oracledb.readthedocs.io/en/latest/user_guide/asyncio.html +[pipelining]: https://python-oracledb.readthedocs.io/en/latest/user_guide/asyncio.html#pipelining-database-operations +[pypi]: https://pypi.org/project/oracledb diff --git a/THIRD_PARTY_LICENSES.txt b/THIRD_PARTY_LICENSES.txt index 15d44264..0f8f1a9a 100644 --- a/THIRD_PARTY_LICENSES.txt +++ b/THIRD_PARTY_LICENSES.txt @@ -710,33 +710,6 @@ under the License. ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- -Python dataframe interchange protocol - -MIT License - -Copyright (c) 2020 Consortium for Python Data API Standards 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. - -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- - Microsoft Authentication Library (MSAL) for Python The MIT License (MIT) @@ -1484,10972 +1457,3 @@ Copyright 2019 Kenneth Reitz ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- - -Pandas license - -BSD 3-Clause License - -Copyright (c) 2008-2011, AQR Capital Management, LLC, Lambda Foundry, Inc. and PyData Development Team -All rights reserved. - -Copyright (c) 2011-2023, Open source contributors. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -* Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -* Neither the name of the copyright holder nor the names of its - contributors may be used to endorse or promote products derived from - this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - ----- Dependency licenses - -numpy - -package_name: numpy -license_type: BSD License -license_text: -Copyright (c) 2005-2024, NumPy Developers. -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - - * Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following - disclaimer in the documentation and/or other materials provided - with the distribution. - - * Neither the name of the NumPy Developers nor the names of any - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ----- ------------------------------------------------------------------------------------ -LICENSES_bundled.txt ------------------------------------------------------------------------------------ - -The NumPy repository and source distributions bundle several libraries that are -compatibly licensed. We list these here. - -Name: lapack-lite -Files: numpy/linalg/lapack_lite/* -License: BSD-3-Clause - Copyright (c) 1992-2013 The University of Tennessee and The University - of Tennessee Research Foundation. All rights - reserved. -Copyright (c) 2000-2013 The University of California Berkeley. All - rights reserved. -Copyright (c) 2006-2013 The University of Colorado Denver. All rights - reserved. - -$COPYRIGHT$ - -Additional copyrights may follow - -$HEADER$ - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -- Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - -- Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer listed - in this license in the documentation and/or other materials - provided with the distribution. - -- Neither the name of the copyright holders nor the names of its - contributors may be used to endorse or promote products derived from - this software without specific prior written permission. - -The copyright holders provide no reassurances that the source code -provided does not infringe any patent, copyright, or any other -intellectual property rights of third parties. The copyright holders -disclaim any liability to any recipient for claims brought against -recipient by any third party for infringement of that parties -intellectual property rights. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ----------------------------------------------------------------------------- -Name: dragon4 -Files: numpy/_core/src/multiarray/dragon4.c -License: MIT - /* - * Copyright (c) 2014 Ryan Juckett - * - * 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. - */ - -/* - * This file contains a modified version of Ryan Juckett's Dragon4 - * implementation, obtained from https://www.ryanjuckett.com, - * which has been ported from C++ to C and which has - * modifications specific to printing floats in numpy. - * - * Ryan Juckett's original code was under the Zlib license; he gave numpy - * permission to include it under the MIT license instead. - */ - - ----------------------------------------------------------------------------- -Name: libdivide -Files: numpy/_core/include/numpy/libdivide/* -License: Zlib - zlib License - ------------ - - Copyright (C) 2010 - 2019 ridiculous_fish, - Copyright (C) 2016 - 2019 Kim Walisch, - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. - ----------------------------------------------------------------------------- -Note that the following files are vendored in the repository and sdist but not -installed in built numpy packages: - -Name: Meson -Files: vendored-meson/meson/* -License: Apache 2.0 - -# Copyright 2016 The Meson development team - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - ----------------------------------------------------------------------------- -Name: spin -Files: .spin/cmds.py -License: BSD-3 - BSD 3-Clause License - -Copyright (c) 2021--2022, Scientific Python project -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -1. Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -3. Neither the name of the copyright holder nor the names of its - contributors may be used to endorse or promote products derived from - this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ---------------------------------------------------------------------------------- -LICENSES_bundled in different directories: ------------------------------------------------------------------------------------ - -The NumPy repository and source distributions bundle several libraries that are -compatibly licensed. We list these here. - -Name: SPLITMIX64 -Files: /numpy/blob/numpy/random/src/splitmix64/* -License: Sebastiano Vigna © 2005–2019 NumPy Developers, Licensed under the 3-clause BSD License. -For details, see /numpy/blob/numpy/random/src/splitmix64/LICENSE.md - -Name: SFC64 -Files: /numpy/blob/numpy/random/src/sfc64/* -License: MIT -For details, see /numpy/blob/numpy/random/src/sfc64/LICENSE.md - -Name: PHILOX -Files: /numpy/blob/numpy/random/src/philox/* -License: D. E. Shaw Research -For license text, see /numpy/blob/numpy/random/src/philox/LICENSE.md - -Name: PCG64 -Files: /numpy/blob/numpy/random/src/pcg64/* -License: MIT -For license text, see/numpy/blob/numpy/random/src/pcg64/LICENSE.md - -Name: MT19937 -Files: /numpy/blob/numpy/random/src/mt19937/* -License: MIT -For license text, see/numpy/blob/numpy/random/src/mt19937/LICENSE.md - -Name: Julia -Files: /numpy/blob/numpy/random/src/distributions/* -License: Jeff Bezanson, Stefan Karpinski, Viral B. Shah, and other contributors -For license text, see/numpy/blob/numpy/random/src/distributions/LICENSE.md - -Name: Random -Files: /numpy/blob/numpy/random/* -License: dual-licensed under the The University of Illinois/NCSA Open Source License (NCSA) and The 3-Clause BSD License -For license text, see/numpy/blob/numpy/random/LICENSE.md - -Name: numpy.core.ma -Files: /numpy/blob/numpy/ma/* -License: University of Georgia and Pierre G.F. Gerard-Marchant -For license text, see /numpy/blob/numpy/ma/LICENSE - ---------------- RECURSIVE LICENSE Mentioned in LICENSES_bundled in different directories (list above) -------------------- -------------------------------------------------------------------------------------------------------------------------------------- - -Name: SPLITMIX64 - -Written in 2015 by Sebastiano Vigna (vigna@acm.org) - -To the extent possible under law, the author has dedicated all copyright and related and neighboring rights to this software to the public domain worldwide. This software is distributed without any warranty. - -See http://creativecommons.org/publicdomain/zero/1.0/. - -------------------------------------------------------------------------------------------------------------------------------------- - -Name: SFC64 - -© 2005–2019 NumPy Developers, Licensed under the 3-clause BSD License. - -The MIT License - -Adapted from a C++ implementation of Chris Doty-Humphrey's SFC PRNG. - -https://gist.github.com/imneme/f1f7821f07cf76504a97f6537c818083 - -Copyright (c) 2018 Melissa E. O'Neill - -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. - -------------------------------------------------------------------------------------------------------------------------------------- -Name: PHILOX - -Copyright 2010-2012, D. E. Shaw Research. All rights reserved. - -Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - - - Redistributions of source code must retain the above copyright notice, this list of conditions, and the following disclaimer. - - - Redistributions in binary form must reproduce the above copyright notice, this list of conditions, and the following disclaimer in the documentation and/or other materials provided with the distribution. - - - Neither the name of D. E. Shaw Research nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -------------------------------------------------------------------------------------------------------------------------------------- -Name: PCG64 - -The MIT License - -PCG Random Number Generation for C. - -Copyright 2014 Melissa O'Neill oneill@pcg-random.org - -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. - -------------------------------------------------------------------------------------------------------------------------------------- - -Name: MT19937 - -Copyright (c) 2003-2005, Jean-Sebastien Roy (js@jeannot.org) - -The rk_random and rk_seed functions algorithms and the original design of the Mersenne Twister RNG: - -Copyright (C) 1997 - 2002, Makoto Matsumoto and Takuji Nishimura, All rights reserved. - -Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - - - Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. - - - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. - - - The names of its contributors may not be used to endorse or promote products derived from this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -Original algorithm for the implementation of rk_interval function from Richard J. Wagner's implementation of the Mersenne Twister RNG, optimised by Magnus Jonsson. - -Constants used in the rk_double implementation by Isaku Wada. - -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. - -------------------------------------------------------------------------------------------------------------------------------------- - -Name: Julia - -The ziggurat methods were derived from Julia. - -Copyright (c) 2009-2019: Jeff Bezanson, Stefan Karpinski, Viral B. Shah, and other contributors: - -https://github.com/JuliaLang/julia/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. - -------------------------------------------------------------------------------------------------------------------------------------- - -Name: Random - -NCSA Open Source License - -Copyright (c) 2019 Kevin Sheppard. All rights reserved. - -Developed by: Kevin Sheppard (kevin.sheppard@economics.ox.ac.uk, kevin.k.sheppard@gmail.com) http://www.kevinsheppard.com - -Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal with 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: - -Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimers. - -Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimers in the documentation and/or other materials provided with the distribution. - -Neither the names of Kevin Sheppard, nor the names of any contributors may be used to endorse or promote products derived from this Software without specific prior written permission. - -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 CONTRIBUTORS 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 WITH THE SOFTWARE. - -3-Clause BSD License - -Copyright (c) 2019 Kevin Sheppard. All rights reserved. - -Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - - - Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. - - - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. - - - Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -Components - -Many parts of this module have been derived from original sources, often the algorithm's designer. Component licenses are located with the component code. - -------------------------------------------------------------------------------------------------------------------------------------- - -Name: numpy.core.ma - -Copyright (c) 2006, University of Georgia and Pierre G.F. Gerard-Marchant -All rights reserved. -Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - * Neither the name of the University of Georgia nor the - names of its contributors may be used to endorse or promote products - derived from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY - EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED - WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY - DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; - LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND - ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS - SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ------------------------------------------------------------------------------------ - - -This distribution of NumPy also bundles the following software: - -Name: OpenBLAS -Files: numpy/.dylibs/libscipy_openblas*.so -Description: bundled as a dynamically linked library -Availability: https://github.com/OpenMathLib/OpenBLAS/ -License: BSD-3-Clause - Copyright (c) 2011-2014, The OpenBLAS Project - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are - met: - - 1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - - 2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - 3. Neither the name of the OpenBLAS project nor the names of - its contributors may be used to endorse or promote products - derived from this software without specific prior written - permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" - AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE - LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER - CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, - OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE - USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - -Name: LAPACK -Files: numpy/.dylibs/libscipy_openblas*.so -Description: bundled in OpenBLAS -Availability: https://github.com/OpenMathLib/OpenBLAS/ -License: BSD-3-Clause-Attribution - Copyright (c) 1992-2013 The University of Tennessee and The University - of Tennessee Research Foundation. All rights - reserved. - Copyright (c) 2000-2013 The University of California Berkeley. All - rights reserved. - Copyright (c) 2006-2013 The University of Colorado Denver. All rights - reserved. - - $COPYRIGHT$ - - Additional copyrights may follow - - $HEADER$ - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are - met: - - - Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - - - Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer listed - in this license in the documentation and/or other materials - provided with the distribution. - - - Neither the name of the copyright holders nor the names of its - contributors may be used to endorse or promote products derived from - this software without specific prior written permission. - - The copyright holders provide no reassurances that the source code - provided does not infringe any patent, copyright, or any other - intellectual property rights of third parties. The copyright holders - disclaim any liability to any recipient for claims brought against - recipient by any third party for infringement of that parties - intellectual property rights. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - -Name: libquadmath -Files: numpy/.dylibs/libquadmath*.so -License: LGPL-2.1-or-later - - GCC Quad-Precision Math Library - Copyright (C) 2010-2019 Free Software Foundation, Inc. - Written by Francois-Xavier Coudert - - This file is part of the libquadmath library. - Libquadmath is free software; you can redistribute it and/or - modify it under the terms of the GNU Library General Public - License as published by the Free Software Foundation; either - version 2.1 of the License, or (at your option) any later version. - - Libquadmath is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html -———————————————————————————————————————————————————————————————————————————————————— ----- -python-dateutil - -Copyright 2017- Paul Ganssle -Copyright 2017- dateutil contributors (see AUTHORS file) - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - -The above license applies to all contributions after 2017-12-01, as well as -all contributions that have been re-licensed (see AUTHORS file for the list of -contributors who have re-licensed their code). - -The full text of the Apache License here: - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - --------------------------------------------------------------------------------- -dateutil - Extensions to the standard Python datetime module. - -Copyright (c) 2003-2011 - Gustavo Niemeyer -Copyright (c) 2012-2014 - Tomi Pieviläinen -Copyright (c) 2014-2016 - Yaron de Leeuw -Copyright (c) 2015- - Paul Ganssle -Copyright (c) 2015- - dateutil contributors (see AUTHORS file) - -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - - * Redistributions of source code must retain the above copyright notice, - this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - * Neither the name of the copyright holder nor the names of its - contributors may be used to endorse or promote products derived from - this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR -CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, -EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, -PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR -PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF -LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING -NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -The above BSD License Applies to all code, even that also covered by Apache 2.0. ----- - -six - -Copyright (c) 2010-2020 Benjamin Peterson - -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. ----- - -pytz - -Copyright (c) 2003-2019 Stuart Bishop - -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. ----- - -tzdata - -Apache Software License 2.0 - -Copyright (c) 2020, Paul Ganssle (Google) - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - -http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. ----- - -Vendored dependencies ---------------------- - -Pyperclip - BSD license -======================= - -Copyright (c) 2010, Albert Sweigart -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - * Neither the name of the pyperclip nor the - names of its contributors may be used to endorse or promote products - derived from this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY Albert Sweigart "AS IS" AND ANY -EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL Albert Sweigart BE LIABLE FOR ANY -DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND -ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -===================================================================================== - -klib - -The MIT License - -Copyright (c) 2008- Attractive Chaos - -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. ----- - -SAS7BDAT - MIT License -======================= - -Copyright (c) 2015 Jared Hobbs - -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. - -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- - -PyArrow - -Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - --------------------------------------------------------------------------------- - -src/arrow/util (some portions): Apache 2.0, and 3-clause BSD - -Some portions of this module are derived from code in the Chromium project, -copyright (c) Google inc and (c) The Chromium Authors and licensed under the -Apache 2.0 License or the under the 3-clause BSD license: - - Copyright (c) 2013 The Chromium Authors. All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are - met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following disclaimer - in the documentation and/or other materials provided with the - distribution. - * Neither the name of Google Inc. nor the names of its - contributors may be used to endorse or promote products derived from - this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - --------------------------------------------------------------------------------- - -This project includes code from Daniel Lemire's FrameOfReference project. - -https://github.com/lemire/FrameOfReference/blob/6ccaf9e97160f9a3b299e23a8ef739e711ef0c71/src/bpacking.cpp -https://github.com/lemire/FrameOfReference/blob/146948b6058a976bc7767262ad3a2ce201486b93/scripts/turbopacking64.py - -Copyright: 2013 Daniel Lemire -Home page: http://lemire.me/en/ -Project page: https://github.com/lemire/FrameOfReference -License: Apache License Version 2.0 http://www.apache.org/licenses/LICENSE-2.0 - --------------------------------------------------------------------------------- - -This project includes code from the TensorFlow project - -Copyright 2015 The TensorFlow Authors. All Rights Reserved. - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. - --------------------------------------------------------------------------------- - -This project includes code from the NumPy project. - -https://github.com/numpy/numpy/blob/e1f191c46f2eebd6cb892a4bfe14d9dd43a06c4e/numpy/core/src/multiarray/multiarraymodule.c#L2910 - -https://github.com/numpy/numpy/blob/68fd82271b9ea5a9e50d4e761061dfcca851382a/numpy/core/src/multiarray/datetime.c - -Copyright (c) 2005-2017, NumPy Developers. -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - - * Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following - disclaimer in the documentation and/or other materials provided - with the distribution. - - * Neither the name of the NumPy Developers nor the names of any - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - --------------------------------------------------------------------------------- - -This project includes code from the Boost project - -Boost Software License - Version 1.0 - August 17th, 2003 - -Permission is hereby granted, free of charge, to any person or organization -obtaining a copy of the software and accompanying documentation covered by -this license (the "Software") to use, reproduce, display, distribute, -execute, and transmit the Software, and to prepare derivative works of the -Software, and to permit third-parties to whom the Software is furnished to -do so, all subject to the following: - -The copyright notices in the Software and this entire statement, including -the above license grant, this restriction and the following disclaimer, -must be included in all copies of the Software, in whole or in part, and -all derivative works of the Software, unless such copies or derivative -works are solely in the form of machine-executable object code generated by -a source language processor. - -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, TITLE AND NON-INFRINGEMENT. IN NO EVENT -SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE -FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, -ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER -DEALINGS IN THE SOFTWARE. - --------------------------------------------------------------------------------- - -This project includes code from the FlatBuffers project - -Copyright 2014 Google Inc. - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. - --------------------------------------------------------------------------------- - -This project includes code from the tslib project - -Copyright 2015 Microsoft Corporation. All rights reserved. - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. - --------------------------------------------------------------------------------- - -This project includes code from the jemalloc project - -https://github.com/jemalloc/jemalloc - -Copyright (C) 2002-2017 Jason Evans . -All rights reserved. -Copyright (C) 2007-2012 Mozilla Foundation. All rights reserved. -Copyright (C) 2009-2017 Facebook, Inc. All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: -1. Redistributions of source code must retain the above copyright notice(s), - this list of conditions and the following disclaimer. -2. Redistributions in binary form must reproduce the above copyright notice(s), - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY EXPRESS -OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO -EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY DIRECT, INDIRECT, -INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR -PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF -LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE -OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF -ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. --------------------------------------------------------------------------------- - -This project includes code from the Go project, BSD 3-clause license + PATENTS -weak patent termination clause -(https://github.com/golang/go/blob/master/PATENTS). - -Copyright (c) 2009 The Go Authors. All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - - * Redistributions of source code must retain the above copyright -notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above -copyright notice, this list of conditions and the following disclaimer -in the documentation and/or other materials provided with the -distribution. - * Neither the name of Google Inc. nor the names of its -contributors may be used to endorse or promote products derived from -this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - --------------------------------------------------------------------------------- - -This project includes code from the hs2client - -https://github.com/cloudera/hs2client - -Copyright 2016 Cloudera Inc. - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - -http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. - --------------------------------------------------------------------------------- - -The script ci/scripts/util_wait_for_it.sh has the following license - -Copyright (c) 2016 Giles Hall - -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. - --------------------------------------------------------------------------------- - -The script r/configure has the following license (MIT) - -Copyright (c) 2017, Jeroen Ooms and Jim Hester - -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. - --------------------------------------------------------------------------------- - -cpp/src/arrow/util/logging.cc, cpp/src/arrow/util/logging.h and -cpp/src/arrow/util/logging-test.cc are adapted from -Ray Project (https://github.com/ray-project/ray) (Apache 2.0). - -Copyright (c) 2016 Ray Project (https://github.com/ray-project/ray) - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. - --------------------------------------------------------------------------------- -The files cpp/src/arrow/vendored/datetime/date.h, cpp/src/arrow/vendored/datetime/tz.h, -cpp/src/arrow/vendored/datetime/tz_private.h, cpp/src/arrow/vendored/datetime/ios.h, -cpp/src/arrow/vendored/datetime/ios.mm, -cpp/src/arrow/vendored/datetime/tz.cpp are adapted from -Howard Hinnant's date library (https://github.com/HowardHinnant/date) -It is licensed under MIT license. - -The MIT License (MIT) -Copyright (c) 2015, 2016, 2017 Howard Hinnant -Copyright (c) 2016 Adrian Colomitchi -Copyright (c) 2017 Florian Dang -Copyright (c) 2017 Paul Thompson -Copyright (c) 2018 Tomasz Kamiński - -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. - --------------------------------------------------------------------------------- - -The file cpp/src/arrow/util/utf8.h includes code adapted from the page - https://bjoern.hoehrmann.de/utf-8/decoder/dfa/ -with the following license (MIT) - -Copyright (c) 2008-2009 Bjoern Hoehrmann - -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. - --------------------------------------------------------------------------------- - -The files in cpp/src/arrow/vendored/xxhash/ have the following license -(BSD 2-Clause License) - -xxHash Library -Copyright (c) 2012-2014, Yann Collet -All rights reserved. - -Redistribution and use in source and binary forms, with or without modification, -are permitted provided that the following conditions are met: - -* Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright notice, this - list of conditions and the following disclaimer in the documentation and/or - other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND -ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR -ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON -ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -You can contact the author at : -- xxHash homepage: http://www.xxhash.com -- xxHash source repository : https://github.com/Cyan4973/xxHash - --------------------------------------------------------------------------------- - -The files in cpp/src/arrow/vendored/double-conversion/ have the following license -(BSD 3-Clause License) - -Copyright 2006-2011, the V8 project authors. All rights reserved. -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following - disclaimer in the documentation and/or other materials provided - with the distribution. - * Neither the name of Google Inc. nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - --------------------------------------------------------------------------------- - -The files in cpp/src/arrow/vendored/uriparser/ have the following license -(BSD 3-Clause License) - -uriparser - RFC 3986 URI parsing library - -Copyright (C) 2007, Weijia Song -Copyright (C) 2007, Sebastian Pipping -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions -are met: - - * Redistributions of source code must retain the above - copyright notice, this list of conditions and the following - disclaimer. - - * Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following - disclaimer in the documentation and/or other materials - provided with the distribution. - - * Neither the name of the nor the names of its - contributors may be used to endorse or promote products - derived from this software without specific prior written - permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS -FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE -COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, -INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, -STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) -ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED -OF THE POSSIBILITY OF SUCH DAMAGE. - --------------------------------------------------------------------------------- - -The files under dev/tasks/conda-recipes have the following license - -BSD 3-clause license -Copyright (c) 2015-2018, conda-forge -All rights reserved. - -Redistribution and use in source and binary forms, with or without modification, -are permitted provided that the following conditions are met: - -1. Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -3. Neither the name of the copyright holder nor the names of its contributors - may be used to endorse or promote products derived from this software without - specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND -ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR -TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF -THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - --------------------------------------------------------------------------------- - -The files in cpp/src/arrow/vendored/utfcpp/ have the following license - -Copyright 2006-2018 Nemanja Trifunovic - -Permission is hereby granted, free of charge, to any person or organization -obtaining a copy of the software and accompanying documentation covered by -this license (the "Software") to use, reproduce, display, distribute, -execute, and transmit the Software, and to prepare derivative works of the -Software, and to permit third-parties to whom the Software is furnished to -do so, all subject to the following: - -The copyright notices in the Software and this entire statement, including -the above license grant, this restriction and the following disclaimer, -must be included in all copies of the Software, in whole or in part, and -all derivative works of the Software, unless such copies or derivative -works are solely in the form of machine-executable object code generated by -a source language processor. - -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, TITLE AND NON-INFRINGEMENT. IN NO EVENT -SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE -FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, -ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER -DEALINGS IN THE SOFTWARE. - --------------------------------------------------------------------------------- - -This project includes code from Apache Kudu. - - * cpp/cmake_modules/CompilerInfo.cmake is based on Kudu's cmake_modules/CompilerInfo.cmake - -Copyright: 2016 The Apache Software Foundation. -Home page: https://kudu.apache.org/ -License: http://www.apache.org/licenses/LICENSE-2.0 - --------------------------------------------------------------------------------- - -This project includes code from Apache Impala (incubating), formerly -Impala. The Impala code and rights were donated to the ASF as part of the -Incubator process after the initial code imports into Apache Parquet. - -Copyright: 2012 Cloudera, Inc. -Copyright: 2016 The Apache Software Foundation. -Home page: http://impala.apache.org/ -License: http://www.apache.org/licenses/LICENSE-2.0 - --------------------------------------------------------------------------------- - -This project includes code from Apache Aurora. - -* dev/release/{release,changelog,release-candidate} are based on the scripts from - Apache Aurora - -Copyright: 2016 The Apache Software Foundation. -Home page: https://aurora.apache.org/ -License: http://www.apache.org/licenses/LICENSE-2.0 - --------------------------------------------------------------------------------- - -This project includes code from the Google styleguide. - -* cpp/build-support/cpplint.py is based on the scripts from the Google styleguide. - -Copyright: 2009 Google Inc. All rights reserved. -Homepage: https://github.com/google/styleguide -License: 3-clause BSD - --------------------------------------------------------------------------------- - -This project includes code from Snappy. - -* cpp/cmake_modules/{SnappyCMakeLists.txt,SnappyConfig.h} are based on code - from Google's Snappy project. - -Copyright: 2009 Google Inc. All rights reserved. -Homepage: https://github.com/google/snappy -License: 3-clause BSD - --------------------------------------------------------------------------------- - -This project includes code from the manylinux project. - -* python/manylinux1/scripts/{build_python.sh,python-tag-abi-tag.py, - requirements.txt} are based on code from the manylinux project. - -Copyright: 2016 manylinux -Homepage: https://github.com/pypa/manylinux -License: The MIT License (MIT) - --------------------------------------------------------------------------------- - -This project includes code from the cymove project: - -* python/pyarrow/includes/common.pxd includes code from the cymove project - -The MIT License (MIT) -Copyright (c) 2019 Omer Ozarslan - -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. - --------------------------------------------------------------------------------- - -The projects includes code from the Ursabot project under the dev/archery -directory. - -License: BSD 2-Clause - -Copyright 2019 RStudio, Inc. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -1. Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND -ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - --------------------------------------------------------------------------------- - -This project include code from mingw-w64. - -* cpp/src/arrow/util/cpu-info.cc has a polyfill for mingw-w64 < 5 - -Copyright (c) 2009 - 2013 by the mingw-w64 project -Homepage: https://mingw-w64.org -License: Zope Public License (ZPL) Version 2.1. - ---------------------------------------------------------------------------------- - -This project include code from Google's Asylo project. - -* cpp/src/arrow/result.h is based on status_or.h - -Copyright (c) Copyright 2017 Asylo authors -Homepage: https://asylo.dev/ -License: Apache 2.0 - --------------------------------------------------------------------------------- - -This project includes code from Google's protobuf project - -* cpp/src/arrow/result.h ARROW_ASSIGN_OR_RAISE is based off ASSIGN_OR_RETURN -* cpp/src/arrow/util/bit_stream_utils.h contains code from wire_format_lite.h - -Copyright 2008 Google Inc. All rights reserved. -Homepage: https://developers.google.com/protocol-buffers/ -License: - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - - * Redistributions of source code must retain the above copyright -notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above -copyright notice, this list of conditions and the following disclaimer -in the documentation and/or other materials provided with the -distribution. - * Neither the name of Google Inc. nor the names of its -contributors may be used to endorse or promote products derived from -this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -Code generated by the Protocol Buffer compiler is owned by the owner -of the input file used when generating it. This code is not -standalone and requires a support library to be linked with it. This -support library is itself covered by the above license. - --------------------------------------------------------------------------------- - -3rdparty dependency LLVM is statically linked in certain binary distributions. -Additionally some sections of source code have been derived from sources in LLVM -and have been clearly labeled as such. LLVM has the following license: - -============================================================================== -The LLVM Project is under the Apache License v2.0 with LLVM Exceptions: -============================================================================== - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - ----- LLVM Exceptions to the Apache 2.0 License ---- - -As an exception, if, as a result of your compiling your source code, portions -of this Software are embedded into an Object form of such source code, you -may redistribute such embedded portions in such Object form without complying -with the conditions of Sections 4(a), 4(b) and 4(d) of the License. - -In addition, if you combine or link compiled forms of this Software with -software that is licensed under the GPLv2 ("Combined Software") and if a -court of competent jurisdiction determines that the patent provision (Section -3), the indemnity provision (Section 9) or other Section of the License -conflicts with the conditions of the GPLv2, you may retroactively and -prospectively choose to deem waived or otherwise exclude such Section(s) of -the License, but only in their entirety and only with respect to the Combined -Software. - -============================================================================== -Software from third parties included in the LLVM Project: -============================================================================== -The LLVM Project contains third party software which is under different license -terms. All such code will be identified clearly using at least one of two -mechanisms: -1) It will be in a separate directory tree with its own `LICENSE.txt` or - `LICENSE` file at the top containing the specific license and restrictions - which apply to that software, or -2) It will contain specific license and restriction terms at the top of every - file. - --------------------------------------------------------------------------------- - -3rdparty dependency gRPC is statically linked in certain binary -distributions, like the python wheels. gRPC has the following license: - -Copyright 2014 gRPC authors. - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. - --------------------------------------------------------------------------------- - -3rdparty dependency Apache Thrift is statically linked in certain binary -distributions, like the python wheels. Apache Thrift has the following license: - -Apache Thrift -Copyright (C) 2006 - 2019, The Apache Software Foundation - -This product includes software developed at -The Apache Software Foundation (http://www.apache.org/). - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. - --------------------------------------------------------------------------------- - -3rdparty dependency Apache ORC is statically linked in certain binary -distributions, like the python wheels. Apache ORC has the following license: - -Apache ORC -Copyright 2013-2019 The Apache Software Foundation - -This product includes software developed by The Apache Software -Foundation (http://www.apache.org/). - -This product includes software developed by Hewlett-Packard: -(c) Copyright [2014-2015] Hewlett-Packard Development Company, L.P - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. - --------------------------------------------------------------------------------- - -3rdparty dependency zstd is statically linked in certain binary -distributions, like the python wheels. ZSTD has the following license: - -BSD License - -For Zstandard software - -Copyright (c) 2016-present, Facebook, Inc. All rights reserved. - -Redistribution and use in source and binary forms, with or without modification, -are permitted provided that the following conditions are met: - - * Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - - * Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - - * Neither the name Facebook nor the names of its contributors may be used to - endorse or promote products derived from this software without specific - prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND -ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR -ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON -ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - --------------------------------------------------------------------------------- - -3rdparty dependency lz4 is statically linked in certain binary -distributions, like the python wheels. lz4 has the following license: - -LZ4 Library -Copyright (c) 2011-2016, Yann Collet -All rights reserved. - -Redistribution and use in source and binary forms, with or without modification, -are permitted provided that the following conditions are met: - -* Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright notice, this - list of conditions and the following disclaimer in the documentation and/or - other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND -ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR -ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON -ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - --------------------------------------------------------------------------------- - -3rdparty dependency Brotli is statically linked in certain binary -distributions, like the python wheels. Brotli has the following license: - -Copyright (c) 2009, 2010, 2013-2016 by the Brotli Authors. - -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. - --------------------------------------------------------------------------------- - -3rdparty dependency rapidjson is statically linked in certain binary -distributions, like the python wheels. rapidjson and its dependencies have the -following licenses: - -Tencent is pleased to support the open source community by making RapidJSON -available. - -Copyright (C) 2015 THL A29 Limited, a Tencent company, and Milo Yip. -All rights reserved. - -If you have downloaded a copy of the RapidJSON binary from Tencent, please note -that the RapidJSON binary is licensed under the MIT License. -If you have downloaded a copy of the RapidJSON source code from Tencent, please -note that RapidJSON source code is licensed under the MIT License, except for -the third-party components listed below which are subject to different license -terms. Your integration of RapidJSON into your own projects may require -compliance with the MIT License, as well as the other licenses applicable to -the third-party components included within RapidJSON. To avoid the problematic -JSON license in your own projects, it's sufficient to exclude the -bin/jsonchecker/ directory, as it's the only code under the JSON license. -A copy of the MIT License is included in this file. - -Other dependencies and licenses: - - Open Source Software Licensed Under the BSD License: - -------------------------------------------------------------------- - - The msinttypes r29 - Copyright (c) 2006-2013 Alexander Chemeris - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are met: - - * Redistributions of source code must retain the above copyright notice, - this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - * Neither the name of copyright holder nor the names of its contributors - may be used to endorse or promote products derived from this software - without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY - EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED - WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR - ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER - CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH - DAMAGE. - - Terms of the MIT License: - -------------------------------------------------------------------- - - 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. - --------------------------------------------------------------------------------- - -3rdparty dependency snappy is statically linked in certain binary -distributions, like the python wheels. snappy has the following license: - -Copyright 2011, Google Inc. -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - - * Redistributions of source code must retain the above copyright notice, - this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - * Neither the name of Google Inc. nor the names of its contributors may be - used to endorse or promote products derived from this software without - specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - -Some of the benchmark data in testdata/ is licensed differently: - - - fireworks.jpeg is Copyright 2013 Steinar H. Gunderson, and - is licensed under the Creative Commons Attribution 3.0 license - (CC-BY-3.0). See https://creativecommons.org/licenses/by/3.0/ - for more information. - - - kppkn.gtb is taken from the Gaviota chess tablebase set, and - is licensed under the MIT License. See - https://sites.google.com/site/gaviotachessengine/Home/endgame-tablebases-1 - for more information. - - - paper-100k.pdf is an excerpt (bytes 92160 to 194560) from the paper - “Combinatorial Modeling of Chromatin Features Quantitatively Predicts DNA - Replication Timing in _Drosophila_” by Federico Comoglio and Renato Paro, - which is licensed under the CC-BY license. See - http://www.ploscompbiol.org/static/license for more ifnormation. - - - alice29.txt, asyoulik.txt, plrabn12.txt and lcet10.txt are from Project - Gutenberg. The first three have expired copyrights and are in the public - domain; the latter does not have expired copyright, but is still in the - public domain according to the license information - (http://www.gutenberg.org/ebooks/53). - --------------------------------------------------------------------------------- - -3rdparty dependency gflags is statically linked in certain binary -distributions, like the python wheels. gflags has the following license: - -Copyright (c) 2006, Google Inc. -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - - * Redistributions of source code must retain the above copyright -notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above -copyright notice, this list of conditions and the following disclaimer -in the documentation and/or other materials provided with the -distribution. - * Neither the name of Google Inc. nor the names of its -contributors may be used to endorse or promote products derived from -this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - --------------------------------------------------------------------------------- - -3rdparty dependency glog is statically linked in certain binary -distributions, like the python wheels. glog has the following license: - -Copyright (c) 2008, Google Inc. -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - - * Redistributions of source code must retain the above copyright -notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above -copyright notice, this list of conditions and the following disclaimer -in the documentation and/or other materials provided with the -distribution. - * Neither the name of Google Inc. nor the names of its -contributors may be used to endorse or promote products derived from -this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - -A function gettimeofday in utilities.cc is based on - -http://www.google.com/codesearch/p?hl=en#dR3YEbitojA/COPYING&q=GetSystemTimeAsFileTime%20license:bsd - -The license of this code is: - -Copyright (c) 2003-2008, Jouni Malinen and contributors -All Rights Reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -3. Neither the name(s) of the above-listed copyright holder(s) nor the - names of its contributors may be used to endorse or promote products - derived from this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - --------------------------------------------------------------------------------- - -3rdparty dependency re2 is statically linked in certain binary -distributions, like the python wheels. re2 has the following license: - -Copyright (c) 2009 The RE2 Authors. All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following - disclaimer in the documentation and/or other materials provided - with the distribution. - * Neither the name of Google Inc. nor the names of its contributors - may be used to endorse or promote products derived from this - software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - --------------------------------------------------------------------------------- - -3rdparty dependency c-ares is statically linked in certain binary -distributions, like the python wheels. c-ares has the following license: - -# c-ares license - -Copyright (c) 2007 - 2018, Daniel Stenberg with many contributors, see AUTHORS -file. - -Copyright 1998 by the Massachusetts Institute of Technology. - -Permission to use, copy, modify, and distribute this software and its -documentation for any purpose and without fee is hereby granted, provided that -the above copyright notice appear in all copies and that both that copyright -notice and this permission notice appear in supporting documentation, and that -the name of M.I.T. not be used in advertising or publicity pertaining to -distribution of the software without specific, written prior permission. -M.I.T. makes no representations about the suitability of this software for any -purpose. It is provided "as is" without express or implied warranty. - --------------------------------------------------------------------------------- - -3rdparty dependency zlib is redistributed as a dynamically linked shared -library in certain binary distributions, like the python wheels. In the future -this will likely change to static linkage. zlib has the following license: - -zlib.h -- interface of the 'zlib' general purpose compression library - version 1.2.11, January 15th, 2017 - - Copyright (C) 1995-2017 Jean-loup Gailly and Mark Adler - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. - - Jean-loup Gailly Mark Adler - jloup@gzip.org madler@alumni.caltech.edu - --------------------------------------------------------------------------------- - -3rdparty dependency openssl is redistributed as a dynamically linked shared -library in certain binary distributions, like the python wheels. openssl -preceding version 3 has the following license: - - LICENSE ISSUES - ============== - - The OpenSSL toolkit stays under a double license, i.e. both the conditions of - the OpenSSL License and the original SSLeay license apply to the toolkit. - See below for the actual license texts. - - OpenSSL License - --------------- - -/* ==================================================================== - * Copyright (c) 1998-2019 The OpenSSL Project. All rights reserved. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions - * are met: - * - * 1. Redistributions of source code must retain the above copyright - * notice, this list of conditions and the following disclaimer. - * - * 2. Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in - * the documentation and/or other materials provided with the - * distribution. - * - * 3. All advertising materials mentioning features or use of this - * software must display the following acknowledgment: - * "This product includes software developed by the OpenSSL Project - * for use in the OpenSSL Toolkit. (http://www.openssl.org/)" - * - * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to - * endorse or promote products derived from this software without - * prior written permission. For written permission, please contact - * openssl-core@openssl.org. - * - * 5. Products derived from this software may not be called "OpenSSL" - * nor may "OpenSSL" appear in their names without prior written - * permission of the OpenSSL Project. - * - * 6. Redistributions of any form whatsoever must retain the following - * acknowledgment: - * "This product includes software developed by the OpenSSL Project - * for use in the OpenSSL Toolkit (http://www.openssl.org/)" - * - * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY - * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR - * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR - * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT - * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; - * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) - * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED - * OF THE POSSIBILITY OF SUCH DAMAGE. - * ==================================================================== - * - * This product includes cryptographic software written by Eric Young - * (eay@cryptsoft.com). This product includes software written by Tim - * Hudson (tjh@cryptsoft.com). - * - */ - - Original SSLeay License - ----------------------- - -/* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com) - * All rights reserved. - * - * This package is an SSL implementation written - * by Eric Young (eay@cryptsoft.com). - * The implementation was written so as to conform with Netscapes SSL. - * - * This library is free for commercial and non-commercial use as long as - * the following conditions are aheared to. The following conditions - * apply to all code found in this distribution, be it the RC4, RSA, - * lhash, DES, etc., code; not just the SSL code. The SSL documentation - * included with this distribution is covered by the same copyright terms - * except that the holder is Tim Hudson (tjh@cryptsoft.com). - * - * Copyright remains Eric Young's, and as such any Copyright notices in - * the code are not to be removed. - * If this package is used in a product, Eric Young should be given attribution - * as the author of the parts of the library used. - * This can be in the form of a textual message at program startup or - * in documentation (online or textual) provided with the package. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions - * are met: - * 1. Redistributions of source code must retain the copyright - * notice, this list of conditions and the following disclaimer. - * 2. Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in the - * documentation and/or other materials provided with the distribution. - * 3. All advertising materials mentioning features or use of this software - * must display the following acknowledgement: - * "This product includes cryptographic software written by - * Eric Young (eay@cryptsoft.com)" - * The word 'cryptographic' can be left out if the rouines from the library - * being used are not cryptographic related :-). - * 4. If you include any Windows specific code (or a derivative thereof) from - * the apps directory (application code) you must include an acknowledgement: - * "This product includes software written by Tim Hudson (tjh@cryptsoft.com)" - * - * THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND - * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE - * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - * SUCH DAMAGE. - * - * The licence and distribution terms for any publically available version or - * derivative of this code cannot be changed. i.e. this code cannot simply be - * copied and put under another distribution licence - * [including the GNU Public Licence.] - */ - --------------------------------------------------------------------------------- - -This project includes code from the rtools-backports project. - -* ci/scripts/PKGBUILD and ci/scripts/r_windows_build.sh are based on code - from the rtools-backports project. - -Copyright: Copyright (c) 2013 - 2019, Алексей and Jeroen Ooms. -All rights reserved. -Homepage: https://github.com/r-windows/rtools-backports -License: 3-clause BSD - --------------------------------------------------------------------------------- - -Some code from pandas has been adapted for the pyarrow codebase. pandas is -available under the 3-clause BSD license, which follows: - -pandas license -============== - -Copyright (c) 2011-2012, Lambda Foundry, Inc. and PyData Development Team -All rights reserved. - -Copyright (c) 2008-2011 AQR Capital Management, LLC -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - - * Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following - disclaimer in the documentation and/or other materials provided - with the distribution. - - * Neither the name of the copyright holder nor the names of any - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - --------------------------------------------------------------------------------- - -Some bits from DyND, in particular aspects of the build system, have been -adapted from libdynd and dynd-python under the terms of the BSD 2-clause -license - -The BSD 2-Clause License - - Copyright (C) 2011-12, Dynamic NDArray Developers - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are - met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - - * Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following - disclaimer in the documentation and/or other materials provided - with the distribution. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -Dynamic NDArray Developers list: - - * Mark Wiebe - * Continuum Analytics - --------------------------------------------------------------------------------- - -Some source code from Ibis (https://github.com/cloudera/ibis) has been adapted -for PyArrow. Ibis is released under the Apache License, Version 2.0. - --------------------------------------------------------------------------------- - -dev/tasks/homebrew-formulae/apache-arrow.rb has the following license: - -BSD 2-Clause License - -Copyright (c) 2009-present, Homebrew contributors -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -* Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ----------------------------------------------------------------------- - -cpp/src/arrow/vendored/base64.cpp has the following license - -ZLIB License - -Copyright (C) 2004-2017 René Nyffenegger - -This source code is provided 'as-is', without any express or implied -warranty. In no event will the author be held liable for any damages arising -from the use of this software. - -Permission is granted to anyone to use this software for any purpose, including -commercial applications, and to alter it and redistribute it freely, subject to -the following restrictions: - -1. The origin of this source code must not be misrepresented; you must not - claim that you wrote the original source code. If you use this source code - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - -2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original source code. - -3. This notice may not be removed or altered from any source distribution. - -René Nyffenegger rene.nyffenegger@adp-gmbh.ch - --------------------------------------------------------------------------------- - -This project includes code from Folly. - - * cpp/src/arrow/vendored/ProducerConsumerQueue.h - -is based on Folly's - - * folly/Portability.h - * folly/lang/Align.h - * folly/ProducerConsumerQueue.h - -Copyright: Copyright (c) Facebook, Inc. and its affiliates. -Home page: https://github.com/facebook/folly -License: http://www.apache.org/licenses/LICENSE-2.0 - --------------------------------------------------------------------------------- - -The file cpp/src/arrow/vendored/musl/strptime.c has the following license - -Copyright © 2005-2020 Rich Felker, et al. - -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. - --------------------------------------------------------------------------------- - -The file cpp/cmake_modules/BuildUtils.cmake contains code from - -https://gist.github.com/cristianadam/ef920342939a89fae3e8a85ca9459b49 - -which is made available under the MIT license - -Copyright (c) 2019 Cristian Adam - -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. - --------------------------------------------------------------------------------- - -The files in cpp/src/arrow/vendored/portable-snippets/ contain code from - -https://github.com/nemequ/portable-snippets - -and have the following copyright notice: - -Each source file contains a preamble explaining the license situation -for that file, which takes priority over this file. With the -exception of some code pulled in from other repositories (such as -µnit, an MIT-licensed project which is used for testing), the code is -public domain, released using the CC0 1.0 Universal dedication (*). - -(*) https://creativecommons.org/publicdomain/zero/1.0/legalcode - --------------------------------------------------------------------------------- - -The files in cpp/src/arrow/vendored/fast_float/ contain code from - -https://github.com/lemire/fast_float - -which is made available under the Apache License 2.0. - --------------------------------------------------------------------------------- - -The file python/pyarrow/vendored/docscrape.py contains code from - -https://github.com/numpy/numpydoc/ - -which is made available under the BSD 2-clause license. - --------------------------------------------------------------------------------- - -The file python/pyarrow/vendored/version.py contains code from - -https://github.com/pypa/packaging/ - -which is made available under both the Apache license v2.0 and the -BSD 2-clause license. - --------------------------------------------------------------------------------- - -The files in cpp/src/arrow/vendored/pcg contain code from - -https://github.com/imneme/pcg-cpp - -and have the following copyright notice: - -Copyright 2014-2019 Melissa O'Neill , - and the PCG Project contributors. - -SPDX-License-Identifier: (Apache-2.0 OR MIT) - -Licensed under the Apache License, Version 2.0 (provided in -LICENSE-APACHE.txt and at http://www.apache.org/licenses/LICENSE-2.0) -or under the MIT license (provided in LICENSE-MIT.txt and at -http://opensource.org/licenses/MIT), at your option. This file may not -be copied, modified, or distributed except according to those terms. - -Distributed on an "AS IS" BASIS, WITHOUT WARRANTY OF ANY KIND, either -express or implied. See your chosen license for details. - --------------------------------------------------------------------------------- -r/R/dplyr-count-tally.R (some portions) - -Some portions of this file are derived from code from - -https://github.com/tidyverse/dplyr/ - -which is made available under the MIT license - -Copyright (c) 2013-2019 RStudio and others. - -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. - --------------------------------------------------------------------------------- - -The file src/arrow/util/io_util.cc contains code from the CPython project -which is made available under the Python Software Foundation License Version 2. - --------------------------------------------------------------------------------- - -3rdparty dependency opentelemetry-cpp is statically linked in certain binary -distributions. opentelemetry-cpp is made available under the Apache License 2.0. - -Copyright The OpenTelemetry Authors -SPDX-License-Identifier: Apache-2.0 - --------------------------------------------------------------------------------- - -ci/conan/ is based on code from Conan Package and Dependency Manager. - -Copyright (c) 2019 Conan.io - -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. - --------------------------------------------------------------------------------- - -3rdparty dependency UCX is redistributed as a dynamically linked shared -library in certain binary distributions. UCX has the following license: - -Copyright (c) 2014-2015 UT-Battelle, LLC. All rights reserved. -Copyright (C) 2014-2020 Mellanox Technologies Ltd. All rights reserved. -Copyright (C) 2014-2015 The University of Houston System. All rights reserved. -Copyright (C) 2015 The University of Tennessee and The University - of Tennessee Research Foundation. All rights reserved. -Copyright (C) 2016-2020 ARM Ltd. All rights reserved. -Copyright (c) 2016 Los Alamos National Security, LLC. All rights reserved. -Copyright (C) 2016-2020 Advanced Micro Devices, Inc. All rights reserved. -Copyright (C) 2019 UChicago Argonne, LLC. All rights reserved. -Copyright (c) 2018-2020 NVIDIA CORPORATION. All rights reserved. -Copyright (C) 2020 Huawei Technologies Co., Ltd. All rights reserved. -Copyright (C) 2016-2020 Stony Brook University. All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions -are met: - -1. Redistributions of source code must retain the above copyright -notice, this list of conditions and the following disclaimer. -2. Redistributions in binary form must reproduce the above copyright -notice, this list of conditions and the following disclaimer in the -documentation and/or other materials provided with the distribution. -3. Neither the name of the copyright holder nor the names of its -contributors may be used to endorse or promote products derived from -this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED -TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR -PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF -LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING -NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - --------------------------------------------------------------------------------- - -The file dev/tasks/r/github.packages.yml contains code from - -https://github.com/ursa-labs/arrow-r-nightly - -which is made available under the Apache License 2.0. - --------------------------------------------------------------------------------- -.github/actions/sync-nightlies/action.yml (some portions) - -Some portions of this file are derived from code from - -https://github.com/JoshPiper/rsync-docker - -which is made available under the MIT license - -Copyright (c) 2020 Joshua Piper - -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. - --------------------------------------------------------------------------------- -.github/actions/sync-nightlies/action.yml (some portions) - -Some portions of this file are derived from code from - -https://github.com/burnett01/rsync-deployments - -which is made available under the MIT license - -Copyright (c) 2019-2022 Contention -Copyright (c) 2019-2022 Burnett01 - -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. - --------------------------------------------------------------------------------- -java/vector/src/main/java/org/apache/arrow/vector/util/IntObjectHashMap.java -java/vector/src/main/java/org/apache/arrow/vector/util/IntObjectMap.java - -These file are derived from code from Netty, which is made available under the -Apache License 2.0. - -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- - -Polars - -Copyright (c) 2020 Ritchie Vink -Some portions Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved. - -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. - -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- - -NumPy - -Copyright: NumPy Developers -License: BSD 3-Clause - - ./.spin/LICENSE - -BSD 3-Clause License - -Copyright (c) 2021--2022, Scientific Python project -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -1. Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -3. Neither the name of the copyright holder nor the names of its - contributors may be used to endorse or promote products derived from - this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - --------------- Separator -------------- - - ./LICENSE.txt - -Copyright (c) 2005-2024, NumPy Developers. -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - - * Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following - disclaimer in the documentation and/or other materials provided - with the distribution. - - * Neither the name of the NumPy Developers nor the names of any - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - --------------- Separator -------------- - - ./LICENSES_bundled.txt - -The NumPy repository and source distributions bundle several libraries that are -compatibly licensed. We list these here. - -Name: lapack-lite -Files: numpy/linalg/lapack_lite/* -License: BSD-3-Clause - For details, see numpy/linalg/lapack_lite/LICENSE.txt - -Name: dragon4 -Files: numpy/_core/src/multiarray/dragon4.c -License: MIT - For license text, see numpy/_core/src/multiarray/dragon4.c - -Name: libdivide -Files: numpy/_core/include/numpy/libdivide/* -License: Zlib - For license text, see numpy/_core/include/numpy/libdivide/LICENSE.txt - - -Note that the following files are vendored in the repository and sdist but not -installed in built numpy packages: - -Name: Meson -Files: vendored-meson/meson/* -License: Apache 2.0 - For license text, see vendored-meson/meson/COPYING - -Name: spin -Files: .spin/cmds.py -License: BSD-3 - For license text, see .spin/LICENSE - -Name: tempita -Files: numpy/_build_utils/tempita/* -License: MIT - For details, see numpy/_build_utils/tempita/LICENCE.txt - --------------- Separator -------------- - - ./numpy/_build_utils/tempita/LICENSE.txt - -Copyright (c) 2008 Ian Bicking 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. - --------------- Separator -------------- - - ./numpy/_core/include/numpy/libdivide/LICENSE.txt - - zlib License - ------------ - - Copyright (C) 2010 - 2019 ridiculous_fish, - Copyright (C) 2016 - 2019 Kim Walisch, - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. - --------------- Separator -------------- - - ./numpy/core/src/multiarray/dragon4.c - -/* - * Copyright (c) 2014 Ryan Juckett - * - * 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. - */ --------------- Separator -------------- - - ./numpy/core/src/multiarray/dragon4.c - -MIT ( same as top-level ) --------------- Separator -------------- - - ./numpy/linalg/lapack_lite/LICENSE.txt - -Copyright (c) 1992-2013 The University of Tennessee and The University - of Tennessee Research Foundation. All rights - reserved. -Copyright (c) 2000-2013 The University of California Berkeley. All - rights reserved. -Copyright (c) 2006-2013 The University of Colorado Denver. All rights - reserved. - -$COPYRIGHT$ - -Additional copyrights may follow - -$HEADER$ - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -- Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - -- Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer listed - in this license in the documentation and/or other materials - provided with the distribution. - -- Neither the name of the copyright holders nor the names of its - contributors may be used to endorse or promote products derived from - this software without specific prior written permission. - -The copyright holders provide no reassurances that the source code -provided does not infringe any patent, copyright, or any other -intellectual property rights of third parties. The copyright holders -disclaim any liability to any recipient for claims brought against -recipient by any third party for infringement of that parties -intellectual property rights. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - --------------- Separator -------------- - - ./numpy/ma/LICENSE - -* Copyright (c) 2006, University of Georgia and Pierre G.F. Gerard-Marchant -* All rights reserved. -* Redistribution and use in source and binary forms, with or without -* modification, are permitted provided that the following conditions are met: -* -* * Redistributions of source code must retain the above copyright -* notice, this list of conditions and the following disclaimer. -* * Redistributions in binary form must reproduce the above copyright -* notice, this list of conditions and the following disclaimer in the -* documentation and/or other materials provided with the distribution. -* * Neither the name of the University of Georgia nor the -* names of its contributors may be used to endorse or promote products -* derived from this software without specific prior written permission. -* -* THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY -* EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -* WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -* DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY -* DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND -* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - --------------- Separator -------------- - - ./numpy/random/LICENSE.md - -**This software is dual-licensed under the The University of Illinois/NCSA -Open Source License (NCSA) and The 3-Clause BSD License** - -# NCSA Open Source License -**Copyright (c) 2019 Kevin Sheppard. All rights reserved.** - -Developed by: Kevin Sheppard (, -) -[http://www.kevinsheppard.com](http://www.kevinsheppard.com) - -Permission is hereby granted, free of charge, to any person obtaining a copy of -this software and associated documentation files (the "Software"), to deal with -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: - -Redistributions of source code must retain the above copyright notice, this -list of conditions and the following disclaimers. - -Redistributions in binary form must reproduce the above copyright notice, this -list of conditions and the following disclaimers in the documentation and/or -other materials provided with the distribution. - -Neither the names of Kevin Sheppard, nor the names of any contributors may be -used to endorse or promote products derived from this Software without specific -prior written permission. - -**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 -CONTRIBUTORS 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 WITH -THE SOFTWARE.** - - -# 3-Clause BSD License -**Copyright (c) 2019 Kevin Sheppard. All rights reserved.** - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -1. Redistributions of source code must retain the above copyright notice, - this list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -3. Neither the name of the copyright holder nor the names of its contributors - may be used to endorse or promote products derived from this software - without specific prior written permission. - -**THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE -LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR -CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF -SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS -INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN -CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) -ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF -THE POSSIBILITY OF SUCH DAMAGE.** - -# Components - -Many parts of this module have been derived from original sources, -often the algorithm's designer. Component licenses are located with -the component code. - --------------- Separator -------------- - - ./numpy/random/src/distributions/LICENSE.md - -## NumPy - -Copyright (c) 2005-2017, NumPy Developers. -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -* Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following - disclaimer in the documentation and/or other materials provided - with the distribution. - -* Neither the name of the NumPy Developers nor the names of any - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - -## Julia - -The ziggurat methods were derived from Julia. - -Copyright (c) 2009-2019: Jeff Bezanson, Stefan Karpinski, Viral B. Shah, -and other contributors: - -https://github.com/JuliaLang/julia/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. - --------------- Separator -------------- - - ./numpy/random/src/mt19937/LICENSE.md - -# MT19937 - -Copyright (c) 2003-2005, Jean-Sebastien Roy (js@jeannot.org) - -The rk_random and rk_seed functions algorithms and the original design of -the Mersenne Twister RNG: - - Copyright (C) 1997 - 2002, Makoto Matsumoto and Takuji Nishimura, - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - - 2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - - 3. The names of its contributors may not be used to endorse or promote - products derived from this software without specific prior written - permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER -OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, -EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, -PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR -PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF -LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING -NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -Original algorithm for the implementation of rk_interval function from -Richard J. Wagner's implementation of the Mersenne Twister RNG, optimised by -Magnus Jonsson. - -Constants used in the rk_double implementation by Isaku Wada. - -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. - --------------- Separator -------------- - - ./numpy/random/src/pcg64/LICENSE.md - -# PCG64 - -## The MIT License - -PCG Random Number Generation for C. - -Copyright 2014 Melissa O'Neill - -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. - --------------- Separator -------------- - - ./numpy/random/src/philox/LICENSE.md - -# PHILOX - -Copyright 2010-2012, D. E. Shaw Research. -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -* Redistributions of source code must retain the above copyright - notice, this list of conditions, and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright - notice, this list of conditions, and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -* Neither the name of D. E. Shaw Research nor the names of its - contributors may be used to endorse or promote products derived from - this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - --------------- Separator -------------- - - ./numpy/random/src/sfc64/LICENSE.md - -# SFC64 - -## The MIT License - -Adapted from a C++ implementation of Chris Doty-Humphrey's SFC PRNG. - -https://gist.github.com/imneme/f1f7821f07cf76504a97f6537c818083 - -Copyright (c) 2018 Melissa E. O'Neill - -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. - --------------- Separator -------------- - - ./numpy/random/src/splitmix64/LICENSE.md - -# SPLITMIX64 - -Written in 2015 by Sebastiano Vigna (vigna@acm.org) - -To the extent possible under law, the author has dedicated all copyright -and related and neighboring rights to this software to the public domain -worldwide. This software is distributed without any warranty. - -See . - --------------- Separator -------------- - - ./vendored-meson/meson/COPYING - - Apache License - Version 2.0, January 2004 - https://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - --------------- Separator -------------- - - -This binary distribution of NumPy also bundles the following software: - - -Name: OpenBLAS -Files: .libs/libopenb*.so -Description: bundled as a dynamically linked library -Availability: https://github.com/xianyi/OpenBLAS/ -License: 3-clause BSD - Copyright (c) 2011-2014, The OpenBLAS Project - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are - met: - - 1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - - 2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - 3. Neither the name of the OpenBLAS project nor the names of - its contributors may be used to endorse or promote products - derived from this software without specific prior written - permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" - AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE - LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER - CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, - OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE - USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. --------------- Separator -------------- - -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- - -PyTorch - -Third-party public licences / copyright notices -################################################ - -From PyTorch: - -Copyright (c) 2016- Facebook, Inc (Adam Paszke) -Copyright (c) 2014- Facebook, Inc (Soumith Chintala) -Copyright (c) 2011-2014 Idiap Research Institute (Ronan Collobert) -Copyright (c) 2012-2014 Deepmind Technologies (Koray Kavukcuoglu) -Copyright (c) 2011-2012 NEC Laboratories America (Koray Kavukcuoglu) -Copyright (c) 2011-2013 NYU (Clement Farabet) -Copyright (c) 2006-2010 NEC Laboratories America (Ronan Collobert, Leon Bottou, Iain Melvin, Jason Weston) -Copyright (c) 2006 Idiap Research Institute (Samy Bengio) -Copyright (c) 2001-2004 Idiap Research Institute (Ronan Collobert, Samy Bengio, Johnny Mariethoz) - -From Caffe2: - -Copyright (c) 2016-present, Facebook Inc. All rights reserved. - -All contributions by Facebook: -Copyright (c) 2016 Facebook Inc. - -All contributions by Google: -Copyright (c) 2015 Google Inc. -All rights reserved. - -All contributions by Yangqing Jia: -Copyright (c) 2015 Yangqing Jia -All rights reserved. - -All contributions by Kakao Brain: -Copyright 2019-2020 Kakao Brain - -All contributions by Cruise LLC: -Copyright (c) 2022 Cruise LLC. -All rights reserved. - -All contributions from Caffe: -Copyright(c) 2013, 2014, 2015, the respective contributors -All rights reserved. - -All other contributions: -Copyright(c) 2015, 2016 the respective contributors -All rights reserved. - -Caffe2 uses a copyright model similar to Caffe: each contributor holds -copyright over their contributions to Caffe2. The project versioning records -all such contribution and copyright details. If a contributor wants to further -mark their specific copyright on a particular contribution, they should -indicate their copyright solely in the commit message of the change when it is -committed. - -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -3. Neither the names of Facebook, Deepmind Technologies, NYU, NEC Laboratories America - and IDIAP Research Institute nor the names of its contributors may be - used to endorse or promote products derived from this software without - specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE -LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR -CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF -SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS -INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN -CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) -ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE -POSSIBILITY OF SUCH DAMAGE. - -======================================================================= -Software under third_party -======================================================================= -Software libraries under third_party are provided as github submodule -links, and their content is not part of the Caffe2 codebase. Their -licences can be found under the respective software repositories. - -======================================================================= -Earlier BSD License -======================================================================= -Early development of Caffe2 in 2015 and early 2016 is licensed under the -BSD license. The license is attached below: - -All contributions by Facebook: -Copyright (c) 2016 Facebook Inc. - -All contributions by Google: -Copyright (c) 2015 Google Inc. -All rights reserved. - -All contributions by Yangqing Jia: -Copyright (c) 2015 Yangqing Jia -All rights reserved. - -All contributions by Kakao Brain: -Copyright 2019-2020 Kakao Brain - -All other contributions: -Copyright(c) 2015, 2016 the respective contributors -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -1. Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. -2. Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND -ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR -ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND -ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - -======================================================================= -Caffe's BSD License -======================================================================= -Some parts of the caffe2 code is derived from the original Caffe code, which is -created by Yangqing Jia and is now a BSD-licensed open-source project. The Caffe -license is as follows: - -COPYRIGHT - -All contributions by the University of California: -Copyright (c) 2014, The Regents of the University of California (Regents) -All rights reserved. - -All other contributions: -Copyright (c) 2014, the respective contributors -All rights reserved. - -Caffe uses a shared copyright model: each contributor holds copyright over -their contributions to Caffe. The project versioning records all such -contribution and copyright details. If a contributor wants to further mark -their specific copyright on a particular contribution, they should indicate -their copyright solely in the commit message of the change when it is -committed. - -LICENSE - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -1. Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. -2. Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND -ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR -ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND -ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -CONTRIBUTION AGREEMENT - -By contributing to the BVLC/caffe repository through pull-request, comment, -or otherwise, the contributor releases their content to the -license and copyright terms herein. - -======================================================================= -Caffe2's Apache License -======================================================================= - -This repo contains Caffe2 code, which was previously licensed under -Apache License Version 2.0: - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - -======================================================================= -Cephes's 3-Clause BSD License -======================================================================= - -Code derived from implementations in the Cephes Math Library should mention -its derivation and reference the following license: - - 3-Clause BSD License for the Cephes Math Library - Copyright (c) 2018, Steven Moshier - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - - * Neither the name of the nor the - names of its contributors may be used to endorse or promote products - derived from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND - ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED - WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL Steven Moshier BE LIABLE FOR ANY - DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; - LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND - ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS - SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - -======================================================================= -SciPy's 3-Clause BSD License -======================================================================= - -Code derived from implementations in SciPy should mention its derivation -and reference the following license: - - Copyright (c) 2001-2002 Enthought, Inc. 2003-2019, SciPy Developers. - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - - 2. Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following - disclaimer in the documentation and/or other materials provided - with the distribution. - - 3. Neither the name of the copyright holder nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -======================================================================= -Boost's 1.0 Software License -======================================================================= - -Code derived from implementations in Boost 1.0 should mention its -derivation and reference the following license: - - Boost Software License - Version 1.0 - August 17th, 2003 - - Permission is hereby granted, free of charge, to any person or organization - obtaining a copy of the software and accompanying documentation covered by - this license (the "Software") to use, reproduce, display, distribute, - execute, and transmit the Software, and to prepare derivative works of the - Software, and to permit third-parties to whom the Software is furnished to - do so, all subject to the following: - - The copyright notices in the Software and this entire statement, including - the above license grant, this restriction and the following disclaimer, - must be included in all copies of the Software, in whole or in part, and - all derivative works of the Software, unless such copies or derivative - works are solely in the form of machine-executable object code generated by - a source language processor. - - 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, TITLE AND NON-INFRINGEMENT. IN NO EVENT - SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE - FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, - ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER - DEALINGS IN THE SOFTWARE. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - -======================================================================= -PILLOW-SIMD Software License -======================================================================= - -Code derived from implementations in PILLOW-SIMD should mention its derivation -and reference the following license: - - The Python Imaging Library (PIL) is - - Copyright © 1997-2011 by Secret Labs AB - Copyright © 1995-2011 by Fredrik Lundh - - Pillow is the friendly PIL fork. It is - - Copyright © 2010-2022 by Alex Clark and contributors - - Like PIL, Pillow is licensed under the open source HPND License: - - By obtaining, using, and/or copying this software and/or its associated - documentation, you agree that you have read, understood, and will comply - with the following terms and conditions: - - Permission to use, copy, modify, and distribute this software and its - associated documentation for any purpose and without fee is hereby granted, - provided that the above copyright notice appears in all copies, and that - both that copyright notice and this permission notice appear in supporting - documentation, and that the name of Secret Labs AB or the author not be - used in advertising or publicity pertaining to distribution of the software - without specific, written prior permission. - - SECRET LABS AB AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS - SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. - IN NO EVENT SHALL SECRET LABS AB OR THE AUTHOR BE LIABLE FOR ANY SPECIAL, - INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR - PERFORMANCE OF THIS SOFTWARE. - - - - -Fourth-party public licences / copyright notices -################################################ - - -Name: DCGM -License: Apache-2.0 -Files: third_party/kineto/libkineto/third_party/dynolog/third_party/DCGM - -Copyright (c) 2022, NVIDIA CORPORATION. All rights reserved. - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. - ---------------------------------------------------------- - -Name: FP16 -License: MIT -Files: third_party/FP16 - -The MIT License (MIT) - -Copyright (c) 2017 Facebook Inc. -Copyright (c) 2017 Georgia Institute of Technology -Copyright 2019 Google LLC - -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. - ---------------------------------------------------------- - -Name: FXdiv -License: MIT -Files: third_party/FXdiv - -The MIT License (MIT) - -Copyright (c) 2017 Facebook Inc. -Copyright (c) 2016-2017 Marat Dukhan - -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. - ---------------------------------------------------------- - -Name: NNPACK -License: BSD-2-Clause -Files: third_party/NNPACK - -Copyright (c) 2017 Facebook Inc. -Copyright (c) 2015-2017, Georgia Institute of Technology -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -* Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ---------------------------------------------------------- - -Name: VulkanMemoryAllocator -License: MIT -Files: third_party/VulkanMemoryAllocator - -Copyright (c) 2017-2022 Advanced Micro Devices, Inc. All rights reserved. - -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. - ---------------------------------------------------------- - -Name: XNNPACK -License: BSD-3-Clause -Files: third_party/XNNPACK - -BSD License - -For XNNPACK software - -Copyright (c) Facebook, Inc. and its affiliates. All rights reserved. -Copyright 2019 Google LLC - -Redistribution and use in source and binary forms, with or without modification, -are permitted provided that the following conditions are met: - - * Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - - * Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - - * Neither the name Facebook nor the names of its contributors may be used to - endorse or promote products derived from this software without specific - prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND -ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR -ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON -ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ---------------------------------------------------------- - -Name: benchmark -License: Apache-2.0 -Files: third_party/benchmark, - third_party/onnx/third_party/benchmark, - third_party/onnx-tensorrt/third_party/onnx/third_party/benchmark, - third_party/protobuf/third_party/benchmark, - third_party/opentelemetry-cpp/third_party/benchmark - - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - ---------------------------------------------------------- - -Name: boost-vcpkg-helpers -License: MIT -Files: third_party/opentelemetry-cpp/tools/vcpkg/ports/boost-vcpkg-helpers - -Copyright (c) Microsoft Corporation - -All rights reserved. - -MIT License - -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. - ---------------------------------------------------------- - -Name: cJSON -License: MIT -Files: third_party/opentelemetry-cpp/third_party/prometheus-cpp/3rdparty/civetweb/examples/rest/cJSON - -Copyright (c) 2009-2017 Dave Gamble and cJSON 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. - ---------------------------------------------------------- - -Name: catch2 -License: BSL-1.0 -Files: third_party/opentelemetry-cpp/third_party/opentracing-cpp/3rd_party/include/opentracing/catch2 - -Boost Software License - Version 1.0 - August 17th, 2003 - -Permission is hereby granted, free of charge, to any person or organization -obtaining a copy of the software and accompanying documentation covered by -this license (the "Software") to use, reproduce, display, distribute, -execute, and transmit the Software, and to prepare derivative works of the -Software, and to permit third-parties to whom the Software is furnished to -do so, all subject to the following: - -The copyright notices in the Software and this entire statement, including -the above license grant, this restriction and the following disclaimer, -must be included in all copies of the Software, in whole or in part, and -all derivative works of the Software, unless such copies or derivative -works are solely in the form of machine-executable object code generated by -a source language processor. - -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, TITLE AND NON-INFRINGEMENT. IN NO EVENT -SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE -FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, -ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER -DEALINGS IN THE SOFTWARE. - ---------------------------------------------------------- - -Name: clog -License: BSD-2-Clause -Files: third_party/cpuinfo/deps/clog - -Copyright (C) 2018 Marat Dukhan -Copyright (c) 2017-2018 Facebook Inc. -Copyright (c) 2017 Georgia Institute of Technology - -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -* Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ---------------------------------------------------------- - -Name: colorama -License: BSD-3-Clause -Files: third_party/kineto/libkineto/third_party/dynolog/third_party/DCGM/testing/python3/libs_3rdparty/colorama - -Copyright (c) 2010 Jonathan Hartley - -Released under the New BSD license (reproduced below), or alternatively you may -use this software under any OSI approved open source license such as those at -http://opensource.org/licenses/alphabetical - -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -* Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -* Neither the name(s) of the copyright holders, nor those of its contributors - may be used to endorse or promote products derived from this software without - specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND -ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ---------------------------------------------------------- - -Name: cpp-httplib -License: MIT -Files: third_party/cpp-httplib - -The MIT License (MIT) - -Copyright (c) 2017 yhirose - -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. - ---------------------------------------------------------- - -Name: cpplint -License: BSD-3-Clause -Files: third_party/kineto/libkineto/third_party/dynolog/third_party/json/third_party/cpplint, - third_party/nlohmann/tools/cpplint - -cpplint.py and its corresponding unit tests are Copyright (C) 2009 Google Inc. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - - * Redistributions of source code must retain the above copyright -notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above -copyright notice, this list of conditions and the following disclaimer -in the documentation and/or other materials provided with the -distribution. - * Neither the name of Google Inc. nor the names of its -contributors may be used to endorse or promote products derived from -this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ---------------------------------------------------------- - -Name: cpr -License: MIT -Files: third_party/kineto/libkineto/third_party/dynolog/third_party/cpr - -This license applies to everything except the contents of the "test" -directory and its subdirectories. - -MIT License - -Copyright (c) 2017-2021 Huu Nguyen -Copyright (c) 2022 libcpr and many other 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. - ---------------------------------------------------------- - -Name: cpuinfo -License: BSD-2-Clause -Files: third_party/cpuinfo, - third_party/fbgemm/third_party/cpuinfo - -Copyright (c) 2019 Google LLC -Copyright (c) 2017-2018 Facebook Inc. -Copyright (C) 2012-2017 Georgia Institute of Technology -Copyright (C) 2010-2012 Marat Dukhan - -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -* Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ---------------------------------------------------------- - -Name: cudnn_frontend -License: MIT -Files: third_party/cudnn_frontend - -/* - * Copyright (c) 2020, NVIDIA CORPORATION. All rights reserved. - * - * 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. - */ - ---------------------------------------------------------- - -Name: cutlass -License: BSD-3-Clause -Files: third_party/cutlass, - third_party/fbgemm/third_party/cutlass - -Copyright (c) 2017 - 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -SPDX-License-Identifier: BSD-3-Clause - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -1. Redistributions of source code must retain the above copyright notice, this -list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright notice, -this list of conditions and the following disclaimer in the documentation -and/or other materials provided with the distribution. - -3. Neither the name of the copyright holder nor the names of its -contributors may be used to endorse or promote products derived from -this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ---------------------------------------------------------- - -Name: dart -License: Apache-2.0 -Files: third_party/flatbuffers/dart - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright 2014 Google Inc. - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - ---------------------------------------------------------- - -Name: duktape-1.5.2 -License: MIT -Files: third_party/opentelemetry-cpp/third_party/prometheus-cpp/3rdparty/civetweb/src/third_party/duktape-1.5.2 - -=============== -Duktape license -=============== - -(http://opensource.org/licenses/MIT) - -Copyright (c) 2013-2016 by Duktape authors (see AUTHORS.rst) - -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. - ---------------------------------------------------------- - -Name: duktape-1.8.0 -License: MIT -Files: third_party/opentelemetry-cpp/third_party/prometheus-cpp/3rdparty/civetweb/src/third_party/duktape-1.8.0 - -=============== -Duktape license -=============== - -(http://opensource.org/licenses/MIT) - -Copyright (c) 2013-2017 by Duktape authors (see AUTHORS.rst) - -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. - ---------------------------------------------------------- - -Name: dynolog -License: MIT -Files: third_party/kineto/libkineto/third_party/dynolog - -MIT License - -Copyright (c) Facebook, Inc. and its affiliates. - -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. - ---------------------------------------------------------- - -Name: eigen -License: BSD-3-Clause -Files: third_party/eigen - -/* - Copyright (c) 2011, Intel Corporation. All rights reserved. - - Redistribution and use in source and binary forms, with or without modification, - are permitted provided that the following conditions are met: - - * Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - * Neither the name of Intel Corporation nor the names of its contributors may - be used to endorse or promote products derived from this software without - specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND - ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED - WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR - ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; - LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON - ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS - SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -*/ - ---------------------------------------------------------- - -Name: etw -License: MIT -Files: third_party/opentelemetry-cpp/exporters/etw/include/opentelemetry/exporters/etw - -TraceLogging Dynamic for Windows - -Copyright (c) Microsoft Corporation. All rights reserved. - -MIT License - -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. - ---------------------------------------------------------- - -Name: expected -License: MIT -Files: third_party/opentelemetry-cpp/third_party/opentracing-cpp/3rd_party/include/opentracing/expected - -The MIT License (MIT) - -Copyright (c) 2015 Martin Moene -Copyright (c) 2015 Microsoft Corporation. All rights reserved. - -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. - ---------------------------------------------------------- - -Name: fbgemm -License: BSD-3-Clause -Files: third_party/fbgemm - -BSD License - -For FBGEMM software - -Copyright (c) Meta Platforms, Inc. and affiliates. All rights reserved. - -Redistribution and use in source and binary forms, with or without modification, -are permitted provided that the following conditions are met: - - * Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - - * Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - - * Neither the name Facebook nor the names of its contributors may be used to - endorse or promote products derived from this software without specific - prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND -ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR -ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON -ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ---------------------------------------------------------- - -Name: ffnvcodec -License: MIT with exception -Files: third_party/opentelemetry-cpp/tools/vcpkg/ports/ffnvcodec - -GNU LESSER GENERAL PUBLIC LICENSE -Version 2.1, February 1999 - -Copyright (C) 1991, 1999 Free Software Foundation, Inc. -51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. - -[This is the first released version of the Lesser GPL. It also counts - as the successor of the GNU Library Public License, version 2, hence - the version number 2.1.] -Preamble -The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public Licenses are intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. - -This license, the Lesser General Public License, applies to some specially designated software packages--typically libraries--of the Free Software Foundation and other authors who decide to use it. You can use it too, but we suggest you first think carefully about whether this license or the ordinary General Public License is the better strategy to use in any particular case, based on the explanations below. - -When we speak of free software, we are referring to freedom of use, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish); that you receive source code or can get it if you want it; that you can change the software and use pieces of it in new free programs; and that you are informed that you can do these things. - -To protect your rights, we need to make restrictions that forbid distributors to deny you these rights or to ask you to surrender these rights. These restrictions translate to certain responsibilities for you if you distribute copies of the library or if you modify it. - -For example, if you distribute copies of the library, whether gratis or for a fee, you must give the recipients all the rights that we gave you. You must make sure that they, too, receive or can get the source code. If you link other code with the library, you must provide complete object files to the recipients, so that they can relink them with the library after making changes to the library and recompiling it. And you must show them these terms so they know their rights. - -We protect your rights with a two-step method: (1) we copyright the library, and (2) we offer you this license, which gives you legal permission to copy, distribute and/or modify the library. - -To protect each distributor, we want to make it very clear that there is no warranty for the free library. Also, if the library is modified by someone else and passed on, the recipients should know that what they have is not the original version, so that the original author's reputation will not be affected by problems that might be introduced by others. - -Finally, software patents pose a constant threat to the existence of any free program. We wish to make sure that a company cannot effectively restrict the users of a free program by obtaining a restrictive license from a patent holder. Therefore, we insist that any patent license obtained for a version of the library must be consistent with the full freedom of use specified in this license. - -Most GNU software, including some libraries, is covered by the ordinary GNU General Public License. This license, the GNU Lesser General Public License, applies to certain designated libraries, and is quite different from the ordinary General Public License. We use this license for certain libraries in order to permit linking those libraries into non-free programs. - -When a program is linked with a library, whether statically or using a shared library, the combination of the two is legally speaking a combined work, a derivative of the original library. The ordinary General Public License therefore permits such linking only if the entire combination fits its criteria of freedom. The Lesser General Public License permits more lax criteria for linking other code with the library. - -We call this license the "Lesser" General Public License because it does Less to protect the user's freedom than the ordinary General Public License. It also provides other free software developers Less of an advantage over competing non-free programs. These disadvantages are the reason we use the ordinary General Public License for many libraries. However, the Lesser license provides advantages in certain special circumstances. - -For example, on rare occasions, there may be a special need to encourage the widest possible use of a certain library, so that it becomes a de-facto standard. To achieve this, non-free programs must be allowed to use the library. A more frequent case is that a free library does the same job as widely used non-free libraries. In this case, there is little to gain by limiting the free library to free software only, so we use the Lesser General Public License. - -In other cases, permission to use a particular library in non-free programs enables a greater number of people to use a large body of free software. For example, permission to use the GNU C Library in non-free programs enables many more people to use the whole GNU operating system, as well as its variant, the GNU/Linux operating system. - -Although the Lesser General Public License is Less protective of the users' freedom, it does ensure that the user of a program that is linked with the Library has the freedom and the wherewithal to run that program using a modified version of the Library. - -The precise terms and conditions for copying, distribution and modification follow. Pay close attention to the difference between a "work based on the library" and a "work that uses the library". The former contains code derived from the library, whereas the latter must be combined with the library in order to run. - -TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION -0. This License Agreement applies to any software library or other program which contains a notice placed by the copyright holder or other authorized party saying it may be distributed under the terms of this Lesser General Public License (also called "this License"). Each licensee is addressed as "you". - -A "library" means a collection of software functions and/or data prepared so as to be conveniently linked with application programs (which use some of those functions and data) to form executables. - -The "Library", below, refers to any such software library or work which has been distributed under these terms. A "work based on the Library" means either the Library or any derivative work under copyright law: that is to say, a work containing the Library or a portion of it, either verbatim or with modifications and/or translated straightforwardly into another language. (Hereinafter, translation is included without limitation in the term "modification".) - -"Source code" for a work means the preferred form of the work for making modifications to it. For a library, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the library. - -Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running a program using the Library is not restricted, and output from such a program is covered only if its contents constitute a work based on the Library (independent of the use of the Library in a tool for writing it). Whether that is true depends on what the Library does and what the program that uses the Library does. - -1. You may copy and distribute verbatim copies of the Library's complete source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and distribute a copy of this License along with the Library. - -You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. - -2. You may modify your copy or copies of the Library or any portion of it, thus forming a work based on the Library, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions: - -a) The modified work must itself be a software library. -b) You must cause the files modified to carry prominent notices stating that you changed the files and the date of any change. -c) You must cause the whole of the work to be licensed at no charge to all third parties under the terms of this License. -d) If a facility in the modified Library refers to a function or a table of data to be supplied by an application program that uses the facility, other than as an argument passed when the facility is invoked, then you must make a good faith effort to ensure that, in the event an application does not supply such function or table, the facility still operates, and performs whatever part of its purpose remains meaningful. -(For example, a function in a library to compute square roots has a purpose that is entirely well-defined independent of the application. Therefore, Subsection 2d requires that any application-supplied function or table used by this function must be optional: if the application does not supply it, the square root function must still compute square roots.) - -These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Library, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Library, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. - -Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Library. - -In addition, mere aggregation of another work not based on the Library with the Library (or with a work based on the Library) on a volume of a storage or distribution medium does not bring the other work under the scope of this License. - -3. You may opt to apply the terms of the ordinary GNU General Public License instead of this License to a given copy of the Library. To do this, you must alter all the notices that refer to this License, so that they refer to the ordinary GNU General Public License, version 2, instead of to this License. (If a newer version than version 2 of the ordinary GNU General Public License has appeared, then you can specify that version instead if you wish.) Do not make any other change in these notices. - -Once this change is made in a given copy, it is irreversible for that copy, so the ordinary GNU General Public License applies to all subsequent copies and derivative works made from that copy. - -This option is useful when you wish to copy part of the code of the Library into a program that is not a library. - -4. You may copy and distribute the Library (or a portion or derivative of it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange. - -If distribution of object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place satisfies the requirement to distribute the source code, even though third parties are not compelled to copy the source along with the object code. - -5. A program that contains no derivative of any portion of the Library, but is designed to work with the Library by being compiled or linked with it, is called a "work that uses the Library". Such a work, in isolation, is not a derivative work of the Library, and therefore falls outside the scope of this License. - -However, linking a "work that uses the Library" with the Library creates an executable that is a derivative of the Library (because it contains portions of the Library), rather than a "work that uses the library". The executable is therefore covered by this License. Section 6 states terms for distribution of such executables. - -When a "work that uses the Library" uses material from a header file that is part of the Library, the object code for the work may be a derivative work of the Library even though the source code is not. Whether this is true is especially significant if the work can be linked without the Library, or if the work is itself a library. The threshold for this to be true is not precisely defined by law. - -If such an object file uses only numerical parameters, data structure layouts and accessors, and small macros and small inline functions (ten lines or less in length), then the use of the object file is unrestricted, regardless of whether it is legally a derivative work. (Executables containing this object code plus portions of the Library will still fall under Section 6.) - -Otherwise, if the work is a derivative of the Library, you may distribute the object code for the work under the terms of Section 6. Any executables containing that work also fall under Section 6, whether or not they are linked directly with the Library itself. - -6. As an exception to the Sections above, you may also combine or link a "work that uses the Library" with the Library to produce a work containing portions of the Library, and distribute that work under terms of your choice, provided that the terms permit modification of the work for the customer's own use and reverse engineering for debugging such modifications. - -You must give prominent notice with each copy of the work that the Library is used in it and that the Library and its use are covered by this License. You must supply a copy of this License. If the work during execution displays copyright notices, you must include the copyright notice for the Library among them, as well as a reference directing the user to the copy of this License. Also, you must do one of these things: - -a) Accompany the work with the complete corresponding machine-readable source code for the Library including whatever changes were used in the work (which must be distributed under Sections 1 and 2 above); and, if the work is an executable linked with the Library, with the complete machine-readable "work that uses the Library", as object code and/or source code, so that the user can modify the Library and then relink to produce a modified executable containing the modified Library. (It is understood that the user who changes the contents of definitions files in the Library will not necessarily be able to recompile the application to use the modified definitions.) -b) Use a suitable shared library mechanism for linking with the Library. A suitable mechanism is one that (1) uses at run time a copy of the library already present on the user's computer system, rather than copying library functions into the executable, and (2) will operate properly with a modified version of the library, if the user installs one, as long as the modified version is interface-compatible with the version that the work was made with. -c) Accompany the work with a written offer, valid for at least three years, to give the same user the materials specified in Subsection 6a, above, for a charge no more than the cost of performing this distribution. -d) If distribution of the work is made by offering access to copy from a designated place, offer equivalent access to copy the above specified materials from the same place. -e) Verify that the user has already received a copy of these materials or that you have already sent this user a copy. -For an executable, the required form of the "work that uses the Library" must include any data and utility programs needed for reproducing the executable from it. However, as a special exception, the materials to be distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. - -It may happen that this requirement contradicts the license restrictions of other proprietary libraries that do not normally accompany the operating system. Such a contradiction means you cannot use both them and the Library together in an executable that you distribute. - -7. You may place library facilities that are a work based on the Library side-by-side in a single library together with other library facilities not covered by this License, and distribute such a combined library, provided that the separate distribution of the work based on the Library and of the other library facilities is otherwise permitted, and provided that you do these two things: - -a) Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities. This must be distributed under the terms of the Sections above. -b) Give prominent notice with the combined library of the fact that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work. -8. You may not copy, modify, sublicense, link with, or distribute the Library except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, link with, or distribute the Library is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. - -9. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Library or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Library (or any work based on the Library), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Library or works based on it. - -10. Each time you redistribute the Library (or any work based on the Library), the recipient automatically receives a license from the original licensor to copy, distribute, link with or modify the Library subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties with this License. - -11. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Library at all. For example, if a patent license would not permit royalty-free redistribution of the Library by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Library. - -If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply, and the section as a whole is intended to apply in other circumstances. - -It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. - -This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. - -12. If the distribution and/or use of the Library is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Library under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License. - -13. The Free Software Foundation may publish revised and/or new versions of the Lesser General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. - -Each version is given a distinguishing version number. If the Library specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Library does not specify a license version number, you may choose any version ever published by the Free Software Foundation. - -14. If you wish to incorporate parts of the Library into other free programs whose distribution conditions are incompatible with these, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. - -NO WARRANTY - -15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. - -16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -END OF TERMS AND CONDITIONS -How to Apply These Terms to Your New Libraries -If you develop a new library, and you want it to be of the greatest possible use to the public, we recommend making it free software that everyone can redistribute and change. You can do so by permitting redistribution under these terms (or, alternatively, under the terms of the ordinary General Public License). - -To apply these terms, attach the following notices to the library. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. - -one line to give the library's name and an idea of what it does. -Copyright (C) year name of author - -This library is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either -version 2.1 of the License, or (at your option) any later version. - -This library is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Lesser General Public License for more details. - -You should have received a copy of the GNU Lesser General Public -License along with this library; if not, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -Also add information on how to contact you by electronic and paper mail. - -You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the library, if necessary. Here is a sample; alter the names: - -Yoyodyne, Inc., hereby disclaims all copyright interest in -the library `Frob' (a library for tweaking knobs) written -by James Random Hacker. - -signature of Ty Coon, 1 April 1990 -Ty Coon, President of Vice -That's all there is to it! - ---------------------------------------------------------- - -Name: flatbuffers -License: Apache-2.0 -Files: third_party/flatbuffers - - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - ---------------------------------------------------------- - -Name: fmt -License: MIT with exception -Files: third_party/fmt - -Copyright (c) 2012 - present, Victor Zverovich and {fmt} 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. - ---- Optional exception to the license --- - -As an exception, if, as a result of your compiling your source code, portions -of this Software are embedded into a machine-executable object form of such -source code, you may redistribute such embedded portions in such object form -without including the above copyright and permission notices. - ---------------------------------------------------------- - -Name: foxi -License: MIT -Files: third_party/foxi - -MIT License - -Copyright (c) 2019 Lu Fang - -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. - ---------------------------------------------------------- - -Name: gemmlowp -License: Apache-2.0 -Files: third_party/gemmlowp/gemmlowp - - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - ---------------------------------------------------------- - -Name: generator -License: Apache-2.0 -Files: third_party/fbgemm/third_party/googletest/googlemock/scripts/generator, - third_party/googletest/googlemock/scripts/generator, - third_party/kineto/libkineto/third_party/googletest/googlemock/scripts/generator, - third_party/protobuf/third_party/googletest/googlemock/scripts/generator, - third_party/tensorpipe/third_party/googletest/googlemock/scripts/generator, - third_party/opentelemetry-cpp/third_party/prometheus-cpp/3rdparty/googletest/googlemock/scripts/generator - - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [2007] Neal Norwitz - Portions Copyright [2007] Google Inc. - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - ---------------------------------------------------------- - -Name: gettimeofday -License: Apache-2.0 -Files: third_party/opentelemetry-cpp/tools/vcpkg/ports/gettimeofday - -/* - * Copied from PostgreSQL source: - * http://doxygen.postgresql.org/gettimeofday_8c_source.html - * - */ - -/* - * gettimeofday.c - * Win32 gettimeofday() replacement - * - * src/port/gettimeofday.c - * - * Copyright (c) 2003 SRA, Inc. - * Copyright (c) 2003 SKC, Inc. - * - * Permission to use, copy, modify, and distribute this software and - * its documentation for any purpose, without fee, and without a - * written agreement is hereby granted, provided that the above - * copyright notice and this paragraph and the following two - * paragraphs appear in all copies. - * - * IN NO EVENT SHALL THE AUTHOR BE LIABLE TO ANY PARTY FOR DIRECT, - * INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING - * LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS - * DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED - * OF THE POSSIBILITY OF SUCH DAMAGE. - * - * THE AUTHOR SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT - * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - * A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS - * IS" BASIS, AND THE AUTHOR HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, - * SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. - */ - ---------------------------------------------------------- - -Name: gloo -License: BSD-3-Clause -Files: third_party/gloo - -BSD License - -For Gloo software - -Copyright (c) 2017-present, Facebook, Inc. All rights reserved. - -Redistribution and use in source and binary forms, with or without modification, -are permitted provided that the following conditions are met: - - * Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - - * Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - - * Neither the name Facebook nor the names of its contributors may be used to - endorse or promote products derived from this software without specific - prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND -ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR -ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON -ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ---------------------------------------------------------- - -Name: googlemock -License: BSD-3-Clause -Files: third_party/fbgemm/third_party/googletest/googlemock, - third_party/kineto/libkineto/third_party/googletest/googlemock, - third_party/protobuf/third_party/googletest/googlemock, - third_party/tensorpipe/third_party/googletest/googlemock - -Copyright 2008, Google Inc. -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - - * Redistributions of source code must retain the above copyright -notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above -copyright notice, this list of conditions and the following disclaimer -in the documentation and/or other materials provided with the -distribution. - * Neither the name of Google Inc. nor the names of its -contributors may be used to endorse or promote products derived from -this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ---------------------------------------------------------- - -Name: googletest -License: BSD-3-Clause -Files: third_party/fbgemm/third_party/googletest, - third_party/fbgemm/third_party/googletest/googletest, - third_party/googletest, - third_party/kineto/libkineto/third_party/dynolog/third_party/googletest, - third_party/kineto/libkineto/third_party/googletest, - third_party/kineto/libkineto/third_party/googletest/googletest, - third_party/protobuf/third_party/googletest, - third_party/protobuf/third_party/googletest/googletest, - third_party/tensorpipe/third_party/googletest, - third_party/tensorpipe/third_party/googletest/googletest, - third_party/opentelemetry-cpp/third_party/googletest, - third_party/opentelemetry-cpp/third_party/prometheus-cpp/3rdparty/googletest - -Copyright 2008, Google Inc. -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - - * Redistributions of source code must retain the above copyright -notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above -copyright notice, this list of conditions and the following disclaimer -in the documentation and/or other materials provided with the -distribution. - * Neither the name of Google Inc. nor the names of its -contributors may be used to endorse or promote products derived from -this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ---------------------------------------------------------- - -Name: gtest -License: BSD-3-Clause -Files: third_party/ideep/mkl-dnn/tests/gtests/gtest - -Copyright 2008, Google Inc. -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - - * Redistributions of source code must retain the above copyright -notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above -copyright notice, this list of conditions and the following disclaimer -in the documentation and/or other materials provided with the -distribution. - * Neither the name of Google Inc. nor the names of its -contributors may be used to endorse or promote products derived from -this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ---------------------------------------------------------- - -Name: hipify_torch -License: MIT -Files: third_party/fbgemm/third_party/hipify_torch - -MIT License - -Copyright (c) 2017 AMD Compute Libraries - -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. - ---------------------------------------------------------- - -Name: hungarian -License: Apache-2.0 -Files: third_party/opentelemetry-cpp/tools/vcpkg/ports/hungarian - -/******************************************************************** - ******************************************************************** - ** - ** libhungarian by Cyrill Stachniss, 2004 - ** - ** - ** Solving the Minimum Assignment Problem using the - ** Hungarian Method. - ** - ** ** This file may be freely copied and distributed! ** - ** - ** Parts of the used code was originally provided by the - ** "Stanford GraphGase", but I made changes to this code. - ** As asked by the copyright node of the "Stanford GraphGase", - ** I hereby proclaim that this file are *NOT* part of the - ** "Stanford GraphGase" distrubition! - ** - ** This file is distributed in the hope that it will be useful, - ** but WITHOUT ANY WARRANTY; without even the implied - ** warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR - ** PURPOSE. - ** - ******************************************************************** - ********************************************************************/ - ---------------------------------------------------------- - -Name: ideep -License: MIT -Files: third_party/ideep - -Copyright (c) 2018 Intel Corporation. - -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. - ---------------------------------------------------------- - -Name: irrlicht -License: MIT -Files: third_party/opentelemetry-cpp/tools/vcpkg/ports/irrlicht - -The Irrlicht Engine License -=========================== - -Copyright (C) 2002-2015 Nikolaus Gebhardt - -This software is provided 'as-is', without any express or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgement in the product documentation would be - appreciated but is not required. -2. Altered source versions must be clearly marked as such, and must not be - misrepresented as being the original software. -3. This notice may not be removed or altered from any source distribution. - ---------------------------------------------------------- - -Name: json -License: MIT -Files: third_party/nlohmann/json - -MIT License - -Copyright (c) 2013-2022 Niels Lohmann - -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. - ---------------------------------------------------------- - -Name: kineto -License: BSD-3-Clause -Files: third_party/kineto - -BSD License - -For Kineto software - -Copyright (c) Meta Platforms, Inc. and affiliates. - -All contributions by Microsoft: -Copyright (c) Microsoft Corporation. (The Azure AI Platform team) - -Redistribution and use in source and binary forms, with or without modification, -are permitted provided that the following conditions are met: - - * Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - - * Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - - * Neither the name Meta nor the names of its contributors may be used to - endorse or promote products derived from this software without specific - prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND -ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR -ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON -ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ---------------------------------------------------------- - -Name: libnop -License: Apache-2.0 -Files: third_party/tensorpipe/third_party/libnop - -Copyright 2017 The Native Object Protocols Authors - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - https://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. - ---------------------------------------------------------- - -Name: libstemmer -License: BSD-3-Clause -Files: third_party/opentelemetry-cpp/tools/vcpkg/ports/libstemmer - -Snowball - License -Except where explicitly noted, all the software given out on this Snowball site is covered by the 3-clause BSD License: - -Copyright (c) 2001, Dr Martin Porter, -Copyright (c) 2002, Richard Boulton. -All rights reserved. - -Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - -1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. - -3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -Essentially, all this means is that you can do what you like with the code, except claim another Copyright for it, or claim that it is issued under a different license. The software is also issued without warranties, which means that if anyone suffers through its use, they cannot come back and sue you. You also have to alert anyone to whom you give the Snowball software to the fact that it is covered by the BSD license. - -We have not bothered to insert the licensing arrangement into the text of the Snowball software. - ---------------------------------------------------------- - -Name: libuv -License: MIT -Files: third_party/tensorpipe/third_party/libuv - -libuv is licensed for use as follows: - -==== -Copyright (c) 2015-present libuv project 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. -==== - -This license applies to parts of libuv originating from the -https://github.com/joyent/libuv repository: - -==== - -Copyright Joyent, Inc. and other Node contributors. All rights reserved. -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. - -==== - -This license applies to all parts of libuv that are not externally -maintained libraries. - -The externally maintained libraries used by libuv are: - - - tree.h (from FreeBSD), copyright Niels Provos. Two clause BSD license. - - - inet_pton and inet_ntop implementations, contained in src/inet.c, are - copyright the Internet Systems Consortium, Inc., and licensed under the ISC - license. - - - stdint-msvc2008.h (from msinttypes), copyright Alexander Chemeris. Three - clause BSD license. - - - pthread-fixes.c, copyright Google Inc. and Sony Mobile Communications AB. - Three clause BSD license. - - - android-ifaddrs.h, android-ifaddrs.c, copyright Berkeley Software Design - Inc, Kenneth MacKay and Emergya (Cloud4all, FP7/2007-2013, grant agreement - n° 289016). Three clause BSD license. - ---------------------------------------------------------- - -Name: miniz-2.1.0 -License: MIT -Files: third_party/miniz-2.1.0 - -Copyright 2013-2014 RAD Game Tools and Valve Software -Copyright 2010-2014 Rich Geldreich and Tenacious Software LLC - -All Rights Reserved. - -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. - ---------------------------------------------------------- - -Name: mimalloc -License: MIT -Files: third_party/mimalloc - -MIT License - -Copyright (c) 2018-2021 Microsoft Corporation, Daan Leijen - -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. - ---------------------------------------------------------- - -Name: mkl-dnn -License: Apache-2.0 -Files: third_party/ideep/mkl-dnn - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - ============================================================================ - - Copyright 2016-2023 Intel Corporation - Copyright 2018 YANDEX LLC - Copyright 2019-2023 FUJITSU LIMITED - Copyright 2020-2023 Arm Ltd. and affiliates - Copyright 2020-2022 Codeplay Software Limited - Copyright 2021 Alanna Tempest - Copyright 2022-2023 IBM Corporation - Copyright 2023 KNS Group LLC (YADRO) - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - This distribution includes third party software ("third party programs"). - This third party software, even if included with the distribution of - the Intel software, may be governed by separate license terms, including - without limitation, third party license terms, other Intel software license - terms, and open source software license terms. These separate license terms - govern your use of the third party programs as set forth in the - "THIRD-PARTY-PROGRAMS" file. - ---------------------------------------------------------- - -Name: ms-gsl -License: MIT -Files: third_party/opentelemetry-cpp/third_party/ms-gsl - -Copyright (c) 2015 Microsoft Corporation. All rights reserved. - -This code is licensed under the MIT License (MIT). - -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. - ---------------------------------------------------------- - -Name: nccl -License: BSD-3-Clause -Files: third_party/nccl/nccl - - - Copyright (c) 2015-2020, NVIDIA CORPORATION. All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - * Neither the name of NVIDIA CORPORATION, Lawrence Berkeley National - Laboratory, the U.S. Department of Energy, nor the names of their - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS'' AND ANY - EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR - PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR - CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, - EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, - PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR - PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY - OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - The U.S. Department of Energy funded the development of this software - under subcontract 7078610 with Lawrence Berkeley National Laboratory. - - -This code also includes files from the NVIDIA Tools Extension SDK project. - -See: - - https://github.com/NVIDIA/NVTX - -for more information and license details. - ---------------------------------------------------------- - -Name: onnx -License: Apache-2.0 -Files: third_party/onnx - - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - ---------------------------------------------------------- - -Name: OpenBLAS -License: 3-clause BSD -Files: .libs/libopenb*.so - -Copyright (c) 2011-2014, The OpenBLAS Project -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - - 1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - - 2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - 3. Neither the name of the OpenBLAS project nor the names of - its contributors may be used to endorse or promote products - derived from this software without specific prior written - permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE -LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE -USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - ---------------------------------------------------------- - -Name: opentelemetry-cpp -License: Apache-2.0 -Files: third_party/opentelemetry-cpp - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - ---------------------------------------------------------- - -Name: opentelemetry-proto -License: Apache-2.0 -Files: third_party/opentelemetry-cpp/third_party/opentelemetry-proto - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - ---------------------------------------------------------- - -Name: opentracing-cpp -License: Apache-2.0 -Files: third_party/opentelemetry-cpp/third_party/opentracing-cpp - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "{}" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright The OpenTracing Authors - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - ---------------------------------------------------------- - -Name: pdcurses -License: Apache-2.0 -Files: third_party/opentelemetry-cpp/tools/vcpkg/ports/pdcurses - -The core package is in the public domain, but small portions of PDCurses are subject to copyright under various licenses. - -The win32 files are released to the public domain. - -If you use PDCurses in an application, an acknowledgement would be appreciated, but is not mandatory. If you make corrections or enhancements to PDCurses, please forward them to the current maintainer for the benefit of other users. - -This software is provided AS IS with NO WARRANTY whatsoever. - ---------------------------------------------------------- - -Name: pfs -License: Apache-2.0 -Files: third_party/kineto/libkineto/third_party/dynolog/third_party/pfs - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - Copyright 2020-present Daniel Trugman - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - ---------------------------------------------------------- - -Name: physac -License: MIT -Files: third_party/opentelemetry-cpp/tools/vcpkg/ports/physac - -MIT License - -Copyright (c) 2022 Víctor Fisac - -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. - ---------------------------------------------------------- - -Name: pocketfft -License: BSD-3-Clause -Files: third_party/pocketfft - -Copyright (C) 2010-2018 Max-Planck-Society -All rights reserved. - -Redistribution and use in source and binary forms, with or without modification, -are permitted provided that the following conditions are met: - -* Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. -* Redistributions in binary form must reproduce the above copyright notice, this - list of conditions and the following disclaimer in the documentation and/or - other materials provided with the distribution. -* Neither the name of the copyright holder nor the names of its contributors may - be used to endorse or promote products derived from this software without - specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND -ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR -ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON -ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ---------------------------------------------------------- - -Name: pqp -License: Apache-2.0 -Files: third_party/opentelemetry-cpp/tools/vcpkg/ports/pqp - -Copyright 1999 University of North Carolina at Chapel Hill. -All rights reserved. - -Permission to use, copy, modify, and distribute this software and its -documentation for educational, research, and non-profit purposes, without fee, -and without a written agreement is hereby granted, provided that the above -copyright notice and the following three paragraphs appear in all copies. - -IN NO EVENT SHALL THE UNIVERSITY OF NORTH CAROLINA AT CHAPEL HILL BE LIABLE TO -ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, -INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS -DOCUMENTATION, EVEN IF THE UNIVERSITY OF NORTH CAROLINA AT CHAPEL HILL HAS -BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -THE UNIVERSITY OF NORTH CAROLINA AT CHAPEL HILL SPECIFICALLY DISCLAIMS ANY -WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED -HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF NORTH CAROLINA AT -CHAPEL HILL HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, -ENHANCEMENTS, OR MODIFICATIONS. - -The authors may be contacted via: - -US Mail: Eric Larsen, Stefan Gottschalk - Department of Computer Science - Sitterson Hall, CB #3175 - University of North Carolina - Chapel Hill, NC 27599-3175 - -Phone: (919) 962-1749 - -Email: geom@cs.unc.edu - ---------------------------------------------------------- - -Name: prometheus-cpp -License: MIT -Files: third_party/opentelemetry-cpp/third_party/prometheus-cpp - -MIT License - -Copyright (c) 2016-2021 Jupp Mueller -Copyright (c) 2017-2022 Gregor Jasny - -And many contributors, see -https://github.com/jupp0r/prometheus-cpp/graphs/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. - ---------------------------------------------------------- - -Name: protobuf -License: BSD-3-Clause -Files: third_party/protobuf - -Copyright 2008 Google Inc. All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - - * Redistributions of source code must retain the above copyright -notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above -copyright notice, this list of conditions and the following disclaimer -in the documentation and/or other materials provided with the -distribution. - * Neither the name of Google Inc. nor the names of its -contributors may be used to endorse or promote products derived from -this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -Code generated by the Protocol Buffer compiler is owned by the owner -of the input file used when generating it. This code is not -standalone and requires a support library to be linked with it. This -support library is itself covered by the above license. - ---------------------------------------------------------- - -Name: psimd -License: MIT -Files: third_party/psimd - -The MIT License (MIT) - -Copyright (c) 2017 Facebook Inc. -Copyright (c) 2014-2017 Georgia Institute of Technology -Copyright 2019 Google LLC - -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. - ---------------------------------------------------------- - -Name: pthreadpool -License: BSD-2-Clause -Files: third_party/pthreadpool - -Copyright 2019 Google LLC -Copyright (c) 2017 Facebook Inc. -Copyright (c) 2015-2017 Georgia Institute of Technology -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -* Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ---------------------------------------------------------- - -Name: pybind11 -License: BSD-3-Clause -Files: third_party/onnx/third_party/pybind11, - third_party/onnx-tensorrt/third_party/onnx/third_party/pybind11, - third_party/pybind11, - third_party/tensorpipe/third_party/pybind11 - -Copyright (c) 2016 Wenzel Jakob , All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -1. Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -3. Neither the name of the copyright holder nor the names of its contributors - may be used to endorse or promote products derived from this software - without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND -ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -Please also refer to the file .github/CONTRIBUTING.md, which clarifies licensing of -external contributions to this project including patches, pull requests, etc. - ---------------------------------------------------------- - -Name: python -License: BSD-3-Clause -Files: third_party/cutlass/python - -Copyright (c) 2017 - 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -SPDX-License-Identifier: BSD-3-Clause - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -1. Redistributions of source code must retain the above copyright notice, this -list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright notice, -this list of conditions and the following disclaimer in the documentation -and/or other materials provided with the distribution. - -3. Neither the name of the copyright holder nor the names of its -contributors may be used to endorse or promote products derived from -this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ---------------------------------------------------------- - -Name: python-peachpy -License: BSD-2-Clause -Files: third_party/python-peachpy - -============================== -PeachPy license (2-clause BSD) -============================== - -Copyright (c) 2017, Facebook Inc. -Copyright (c) 2013-2017, Georgia Institute of Technology -All rights reserved. - -Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - -1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ---------------------------------------------------------- - -Name: sigslot -License: Apache-2.0 -Files: third_party/opentelemetry-cpp/tools/vcpkg/ports/sigslot - -License -The sigslot library has been placed in the public domain. This means that you are free to use it however you like. - -The author takes no responsibility or liability of any kind for any use that you may make of this library. - -If you screw up, it's your fault. - -If the library screws up, you got it for free, so you should have tested it better - it's still your responsibility. - ---------------------------------------------------------- - -Name: sleef -License: BSL-1.0 -Files: third_party/sleef - For details, see: third_party/sleef/LICENSE.txt - -Boost Software License - Version 1.0 - August 17th, 2003 - -Permission is hereby granted, free of charge, to any person or organization -obtaining a copy of the software and accompanying documentation covered by -this license (the "Software") to use, reproduce, display, distribute, -execute, and transmit the Software, and to prepare derivative works of the -Software, and to permit third-parties to whom the Software is furnished to -do so, all subject to the following: - -The copyright notices in the Software and this entire statement, including -the above license grant, this restriction and the following disclaimer, -must be included in all copies of the Software, in whole or in part, and -all derivative works of the Software, unless such copies or derivative -works are solely in the form of machine-executable object code generated by -a source language processor. - -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, TITLE AND NON-INFRINGEMENT. IN NO EVENT -SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE -FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, -ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER -DEALINGS IN THE SOFTWARE. - ---------------------------------------------------------- - -Name: swift -License: Apache-2.0 -Files: third_party/flatbuffers/swift - - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - ---------------------------------------------------------- - -Name: tb_plugin -License: BSD-3-Clause -Files: third_party/kineto/tb_plugin - -BSD License - -For Kineto software - -Copyright (c) Facebook, Inc. and its affiliates. All rights reserved. - -All contributions by Microsoft: -Copyright (c) Microsoft Corporation. (The Azure AI Platform team) - -Redistribution and use in source and binary forms, with or without modification, -are permitted provided that the following conditions are met: - - * Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - - * Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - - * Neither the name Facebook nor the names of its contributors may be used to - endorse or promote products derived from this software without specific - prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND -ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR -ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON -ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ---------------------------------------------------------- - -Name: tensorflow-common -License: MIT -Files: third_party/opentelemetry-cpp/tools/vcpkg/ports/tensorflow-common - -Copyright (c) Microsoft Corporation - -All rights reserved. - -MIT License - -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. - ---------------------------------------------------------- - -Name: tensorpipe -License: BSD-3-Clause -Files: third_party/tensorpipe - -BSD License - -For TensorPipe software - -Copyright (c) Meta Platforms, Inc. and affiliates. All rights reserved. - -Redistribution and use in source and binary forms, with or without modification, -are permitted provided that the following conditions are met: - - * Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - - * Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - - * Neither the name Meta nor the names of its contributors may be used to - endorse or promote products derived from this software without specific - prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND -ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR -ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON -ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ---------------------------------------------------------- - -Name: test -License: MIT with exception -Files: third_party/kineto/libkineto/third_party/dynolog/third_party/cpr/test - -This license applies to everything inside this directory and all -subdirectories. - - GNU GENERAL PUBLIC LICENSE - Version 3, 29 June 2007 - - Copyright (C) 2007 Free Software Foundation, Inc. - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - Preamble - - The GNU General Public License is a free, copyleft license for -software and other kinds of works. - - The licenses for most software and other practical works are designed -to take away your freedom to share and change the works. By contrast, -the GNU General Public License is intended to guarantee your freedom to -share and change all versions of a program--to make sure it remains free -software for all its users. We, the Free Software Foundation, use the -GNU General Public License for most of our software; it applies also to -any other work released this way by its authors. You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -them if you wish), that you receive source code or can get it if you -want it, that you can change the software or use pieces of it in new -free programs, and that you know you can do these things. - - To protect your rights, we need to prevent others from denying you -these rights or asking you to surrender the rights. Therefore, you have -certain responsibilities if you distribute copies of the software, or if -you modify it: responsibilities to respect the freedom of others. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must pass on to the recipients the same -freedoms that you received. You must make sure that they, too, receive -or can get the source code. And you must show them these terms so they -know their rights. - - Developers that use the GNU GPL protect your rights with two steps: -(1) assert copyright on the software, and (2) offer you this License -giving you legal permission to copy, distribute and/or modify it. - - For the developers' and authors' protection, the GPL clearly explains -that there is no warranty for this free software. For both users' and -authors' sake, the GPL requires that modified versions be marked as -changed, so that their problems will not be attributed erroneously to -authors of previous versions. - - Some devices are designed to deny users access to install or run -modified versions of the software inside them, although the manufacturer -can do so. This is fundamentally incompatible with the aim of -protecting users' freedom to change the software. The systematic -pattern of such abuse occurs in the area of products for individuals to -use, which is precisely where it is most unacceptable. Therefore, we -have designed this version of the GPL to prohibit the practice for those -products. If such problems arise substantially in other domains, we -stand ready to extend this provision to those domains in future versions -of the GPL, as needed to protect the freedom of users. - - Finally, every program is threatened constantly by software patents. -States should not allow patents to restrict development and use of -software on general-purpose computers, but in those that do, we wish to -avoid the special danger that patents applied to a free program could -make it effectively proprietary. To prevent this, the GPL assures that -patents cannot be used to render the program non-free. - - The precise terms and conditions for copying, distribution and -modification follow. - - TERMS AND CONDITIONS - - 0. Definitions. - - "This License" refers to version 3 of the GNU General Public License. - - "Copyright" also means copyright-like laws that apply to other kinds of -works, such as semiconductor masks. - - "The Program" refers to any copyrightable work licensed under this -License. Each licensee is addressed as "you". "Licensees" and -"recipients" may be individuals or organizations. - - To "modify" a work means to copy from or adapt all or part of the work -in a fashion requiring copyright permission, other than the making of an -exact copy. The resulting work is called a "modified version" of the -earlier work or a work "based on" the earlier work. - - A "covered work" means either the unmodified Program or a work based -on the Program. - - To "propagate" a work means to do anything with it that, without -permission, would make you directly or secondarily liable for -infringement under applicable copyright law, except executing it on a -computer or modifying a private copy. Propagation includes copying, -distribution (with or without modification), making available to the -public, and in some countries other activities as well. - - To "convey" a work means any kind of propagation that enables other -parties to make or receive copies. Mere interaction with a user through -a computer network, with no transfer of a copy, is not conveying. - - An interactive user interface displays "Appropriate Legal Notices" -to the extent that it includes a convenient and prominently visible -feature that (1) displays an appropriate copyright notice, and (2) -tells the user that there is no warranty for the work (except to the -extent that warranties are provided), that licensees may convey the -work under this License, and how to view a copy of this License. If -the interface presents a list of user commands or options, such as a -menu, a prominent item in the list meets this criterion. - - 1. Source Code. - - The "source code" for a work means the preferred form of the work -for making modifications to it. "Object code" means any non-source -form of a work. - - A "Standard Interface" means an interface that either is an official -standard defined by a recognized standards body, or, in the case of -interfaces specified for a particular programming language, one that -is widely used among developers working in that language. - - The "System Libraries" of an executable work include anything, other -than the work as a whole, that (a) is included in the normal form of -packaging a Major Component, but which is not part of that Major -Component, and (b) serves only to enable use of the work with that -Major Component, or to implement a Standard Interface for which an -implementation is available to the public in source code form. A -"Major Component", in this context, means a major essential component -(kernel, window system, and so on) of the specific operating system -(if any) on which the executable work runs, or a compiler used to -produce the work, or an object code interpreter used to run it. - - The "Corresponding Source" for a work in object code form means all -the source code needed to generate, install, and (for an executable -work) run the object code and to modify the work, including scripts to -control those activities. However, it does not include the work's -System Libraries, or general-purpose tools or generally available free -programs which are used unmodified in performing those activities but -which are not part of the work. For example, Corresponding Source -includes interface definition files associated with source files for -the work, and the source code for shared libraries and dynamically -linked subprograms that the work is specifically designed to require, -such as by intimate data communication or control flow between those -subprograms and other parts of the work. - - The Corresponding Source need not include anything that users -can regenerate automatically from other parts of the Corresponding -Source. - - The Corresponding Source for a work in source code form is that -same work. - - 2. Basic Permissions. - - All rights granted under this License are granted for the term of -copyright on the Program, and are irrevocable provided the stated -conditions are met. This License explicitly affirms your unlimited -permission to run the unmodified Program. The output from running a -covered work is covered by this License only if the output, given its -content, constitutes a covered work. This License acknowledges your -rights of fair use or other equivalent, as provided by copyright law. - - You may make, run and propagate covered works that you do not -convey, without conditions so long as your license otherwise remains -in force. You may convey covered works to others for the sole purpose -of having them make modifications exclusively for you, or provide you -with facilities for running those works, provided that you comply with -the terms of this License in conveying all material for which you do -not control copyright. Those thus making or running the covered works -for you must do so exclusively on your behalf, under your direction -and control, on terms that prohibit them from making any copies of -your copyrighted material outside their relationship with you. - - Conveying under any other circumstances is permitted solely under -the conditions stated below. Sublicensing is not allowed; section 10 -makes it unnecessary. - - 3. Protecting Users' Legal Rights From Anti-Circumvention Law. - - No covered work shall be deemed part of an effective technological -measure under any applicable law fulfilling obligations under article -11 of the WIPO copyright treaty adopted on 20 December 1996, or -similar laws prohibiting or restricting circumvention of such -measures. - - When you convey a covered work, you waive any legal power to forbid -circumvention of technological measures to the extent such circumvention -is effected by exercising rights under this License with respect to -the covered work, and you disclaim any intention to limit operation or -modification of the work as a means of enforcing, against the work's -users, your or third parties' legal rights to forbid circumvention of -technological measures. - - 4. Conveying Verbatim Copies. - - You may convey verbatim copies of the Program's source code as you -receive it, in any medium, provided that you conspicuously and -appropriately publish on each copy an appropriate copyright notice; -keep intact all notices stating that this License and any -non-permissive terms added in accord with section 7 apply to the code; -keep intact all notices of the absence of any warranty; and give all -recipients a copy of this License along with the Program. - - You may charge any price or no price for each copy that you convey, -and you may offer support or warranty protection for a fee. - - 5. Conveying Modified Source Versions. - - You may convey a work based on the Program, or the modifications to -produce it from the Program, in the form of source code under the -terms of section 4, provided that you also meet all of these conditions: - - a) The work must carry prominent notices stating that you modified - it, and giving a relevant date. - - b) The work must carry prominent notices stating that it is - released under this License and any conditions added under section - 7. This requirement modifies the requirement in section 4 to - "keep intact all notices". - - c) You must license the entire work, as a whole, under this - License to anyone who comes into possession of a copy. This - License will therefore apply, along with any applicable section 7 - additional terms, to the whole of the work, and all its parts, - regardless of how they are packaged. This License gives no - permission to license the work in any other way, but it does not - invalidate such permission if you have separately received it. - - d) If the work has interactive user interfaces, each must display - Appropriate Legal Notices; however, if the Program has interactive - interfaces that do not display Appropriate Legal Notices, your - work need not make them do so. - - A compilation of a covered work with other separate and independent -works, which are not by their nature extensions of the covered work, -and which are not combined with it such as to form a larger program, -in or on a volume of a storage or distribution medium, is called an -"aggregate" if the compilation and its resulting copyright are not -used to limit the access or legal rights of the compilation's users -beyond what the individual works permit. Inclusion of a covered work -in an aggregate does not cause this License to apply to the other -parts of the aggregate. - - 6. Conveying Non-Source Forms. - - You may convey a covered work in object code form under the terms -of sections 4 and 5, provided that you also convey the -machine-readable Corresponding Source under the terms of this License, -in one of these ways: - - a) Convey the object code in, or embodied in, a physical product - (including a physical distribution medium), accompanied by the - Corresponding Source fixed on a durable physical medium - customarily used for software interchange. - - b) Convey the object code in, or embodied in, a physical product - (including a physical distribution medium), accompanied by a - written offer, valid for at least three years and valid for as - long as you offer spare parts or customer support for that product - model, to give anyone who possesses the object code either (1) a - copy of the Corresponding Source for all the software in the - product that is covered by this License, on a durable physical - medium customarily used for software interchange, for a price no - more than your reasonable cost of physically performing this - conveying of source, or (2) access to copy the - Corresponding Source from a network server at no charge. - - c) Convey individual copies of the object code with a copy of the - written offer to provide the Corresponding Source. This - alternative is allowed only occasionally and noncommercially, and - only if you received the object code with such an offer, in accord - with subsection 6b. - - d) Convey the object code by offering access from a designated - place (gratis or for a charge), and offer equivalent access to the - Corresponding Source in the same way through the same place at no - further charge. You need not require recipients to copy the - Corresponding Source along with the object code. If the place to - copy the object code is a network server, the Corresponding Source - may be on a different server (operated by you or a third party) - that supports equivalent copying facilities, provided you maintain - clear directions next to the object code saying where to find the - Corresponding Source. Regardless of what server hosts the - Corresponding Source, you remain obligated to ensure that it is - available for as long as needed to satisfy these requirements. - - e) Convey the object code using peer-to-peer transmission, provided - you inform other peers where the object code and Corresponding - Source of the work are being offered to the general public at no - charge under subsection 6d. - - A separable portion of the object code, whose source code is excluded -from the Corresponding Source as a System Library, need not be -included in conveying the object code work. - - A "User Product" is either (1) a "consumer product", which means any -tangible personal property which is normally used for personal, family, -or household purposes, or (2) anything designed or sold for incorporation -into a dwelling. In determining whether a product is a consumer product, -doubtful cases shall be resolved in favor of coverage. For a particular -product received by a particular user, "normally used" refers to a -typical or common use of that class of product, regardless of the status -of the particular user or of the way in which the particular user -actually uses, or expects or is expected to use, the product. A product -is a consumer product regardless of whether the product has substantial -commercial, industrial or non-consumer uses, unless such uses represent -the only significant mode of use of the product. - - "Installation Information" for a User Product means any methods, -procedures, authorization keys, or other information required to install -and execute modified versions of a covered work in that User Product from -a modified version of its Corresponding Source. The information must -suffice to ensure that the continued functioning of the modified object -code is in no case prevented or interfered with solely because -modification has been made. - - If you convey an object code work under this section in, or with, or -specifically for use in, a User Product, and the conveying occurs as -part of a transaction in which the right of possession and use of the -User Product is transferred to the recipient in perpetuity or for a -fixed term (regardless of how the transaction is characterized), the -Corresponding Source conveyed under this section must be accompanied -by the Installation Information. But this requirement does not apply -if neither you nor any third party retains the ability to install -modified object code on the User Product (for example, the work has -been installed in ROM). - - The requirement to provide Installation Information does not include a -requirement to continue to provide support service, warranty, or updates -for a work that has been modified or installed by the recipient, or for -the User Product in which it has been modified or installed. Access to a -network may be denied when the modification itself materially and -adversely affects the operation of the network or violates the rules and -protocols for communication across the network. - - Corresponding Source conveyed, and Installation Information provided, -in accord with this section must be in a format that is publicly -documented (and with an implementation available to the public in -source code form), and must require no special password or key for -unpacking, reading or copying. - - 7. Additional Terms. - - "Additional permissions" are terms that supplement the terms of this -License by making exceptions from one or more of its conditions. -Additional permissions that are applicable to the entire Program shall -be treated as though they were included in this License, to the extent -that they are valid under applicable law. If additional permissions -apply only to part of the Program, that part may be used separately -under those permissions, but the entire Program remains governed by -this License without regard to the additional permissions. - - When you convey a copy of a covered work, you may at your option -remove any additional permissions from that copy, or from any part of -it. (Additional permissions may be written to require their own -removal in certain cases when you modify the work.) You may place -additional permissions on material, added by you to a covered work, -for which you have or can give appropriate copyright permission. - - Notwithstanding any other provision of this License, for material you -add to a covered work, you may (if authorized by the copyright holders of -that material) supplement the terms of this License with terms: - - a) Disclaiming warranty or limiting liability differently from the - terms of sections 15 and 16 of this License; or - - b) Requiring preservation of specified reasonable legal notices or - author attributions in that material or in the Appropriate Legal - Notices displayed by works containing it; or - - c) Prohibiting misrepresentation of the origin of that material, or - requiring that modified versions of such material be marked in - reasonable ways as different from the original version; or - - d) Limiting the use for publicity purposes of names of licensors or - authors of the material; or - - e) Declining to grant rights under trademark law for use of some - trade names, trademarks, or service marks; or - - f) Requiring indemnification of licensors and authors of that - material by anyone who conveys the material (or modified versions of - it) with contractual assumptions of liability to the recipient, for - any liability that these contractual assumptions directly impose on - those licensors and authors. - - All other non-permissive additional terms are considered "further -restrictions" within the meaning of section 10. If the Program as you -received it, or any part of it, contains a notice stating that it is -governed by this License along with a term that is a further -restriction, you may remove that term. If a license document contains -a further restriction but permits relicensing or conveying under this -License, you may add to a covered work material governed by the terms -of that license document, provided that the further restriction does -not survive such relicensing or conveying. - - If you add terms to a covered work in accord with this section, you -must place, in the relevant source files, a statement of the -additional terms that apply to those files, or a notice indicating -where to find the applicable terms. - - Additional terms, permissive or non-permissive, may be stated in the -form of a separately written license, or stated as exceptions; -the above requirements apply either way. - - 8. Termination. - - You may not propagate or modify a covered work except as expressly -provided under this License. Any attempt otherwise to propagate or -modify it is void, and will automatically terminate your rights under -this License (including any patent licenses granted under the third -paragraph of section 11). - - However, if you cease all violation of this License, then your -license from a particular copyright holder is reinstated (a) -provisionally, unless and until the copyright holder explicitly and -finally terminates your license, and (b) permanently, if the copyright -holder fails to notify you of the violation by some reasonable means -prior to 60 days after the cessation. - - Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - - Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, you do not qualify to receive new licenses for the same -material under section 10. - - 9. Acceptance Not Required for Having Copies. - - You are not required to accept this License in order to receive or -run a copy of the Program. Ancillary propagation of a covered work -occurring solely as a consequence of using peer-to-peer transmission -to receive a copy likewise does not require acceptance. However, -nothing other than this License grants you permission to propagate or -modify any covered work. These actions infringe copyright if you do -not accept this License. Therefore, by modifying or propagating a -covered work, you indicate your acceptance of this License to do so. - - 10. Automatic Licensing of Downstream Recipients. - - Each time you convey a covered work, the recipient automatically -receives a license from the original licensors, to run, modify and -propagate that work, subject to this License. You are not responsible -for enforcing compliance by third parties with this License. - - An "entity transaction" is a transaction transferring control of an -organization, or substantially all assets of one, or subdividing an -organization, or merging organizations. If propagation of a covered -work results from an entity transaction, each party to that -transaction who receives a copy of the work also receives whatever -licenses to the work the party's predecessor in interest had or could -give under the previous paragraph, plus a right to possession of the -Corresponding Source of the work from the predecessor in interest, if -the predecessor has it or can get it with reasonable efforts. - - You may not impose any further restrictions on the exercise of the -rights granted or affirmed under this License. For example, you may -not impose a license fee, royalty, or other charge for exercise of -rights granted under this License, and you may not initiate litigation -(including a cross-claim or counterclaim in a lawsuit) alleging that -any patent claim is infringed by making, using, selling, offering for -sale, or importing the Program or any portion of it. - - 11. Patents. - - A "contributor" is a copyright holder who authorizes use under this -License of the Program or a work on which the Program is based. The -work thus licensed is called the contributor's "contributor version". - - A contributor's "essential patent claims" are all patent claims -owned or controlled by the contributor, whether already acquired or -hereafter acquired, that would be infringed by some manner, permitted -by this License, of making, using, or selling its contributor version, -but do not include claims that would be infringed only as a -consequence of further modification of the contributor version. For -purposes of this definition, "control" includes the right to grant -patent sublicenses in a manner consistent with the requirements of -this License. - - Each contributor grants you a non-exclusive, worldwide, royalty-free -patent license under the contributor's essential patent claims, to -make, use, sell, offer for sale, import and otherwise run, modify and -propagate the contents of its contributor version. - - In the following three paragraphs, a "patent license" is any express -agreement or commitment, however denominated, not to enforce a patent -(such as an express permission to practice a patent or covenant not to -sue for patent infringement). To "grant" such a patent license to a -party means to make such an agreement or commitment not to enforce a -patent against the party. - - If you convey a covered work, knowingly relying on a patent license, -and the Corresponding Source of the work is not available for anyone -to copy, free of charge and under the terms of this License, through a -publicly available network server or other readily accessible means, -then you must either (1) cause the Corresponding Source to be so -available, or (2) arrange to deprive yourself of the benefit of the -patent license for this particular work, or (3) arrange, in a manner -consistent with the requirements of this License, to extend the patent -license to downstream recipients. "Knowingly relying" means you have -actual knowledge that, but for the patent license, your conveying the -covered work in a country, or your recipient's use of the covered work -in a country, would infringe one or more identifiable patents in that -country that you have reason to believe are valid. - - If, pursuant to or in connection with a single transaction or -arrangement, you convey, or propagate by procuring conveyance of, a -covered work, and grant a patent license to some of the parties -receiving the covered work authorizing them to use, propagate, modify -or convey a specific copy of the covered work, then the patent license -you grant is automatically extended to all recipients of the covered -work and works based on it. - - A patent license is "discriminatory" if it does not include within -the scope of its coverage, prohibits the exercise of, or is -conditioned on the non-exercise of one or more of the rights that are -specifically granted under this License. You may not convey a covered -work if you are a party to an arrangement with a third party that is -in the business of distributing software, under which you make payment -to the third party based on the extent of your activity of conveying -the work, and under which the third party grants, to any of the -parties who would receive the covered work from you, a discriminatory -patent license (a) in connection with copies of the covered work -conveyed by you (or copies made from those copies), or (b) primarily -for and in connection with specific products or compilations that -contain the covered work, unless you entered into that arrangement, -or that patent license was granted, prior to 28 March 2007. - - Nothing in this License shall be construed as excluding or limiting -any implied license or other defenses to infringement that may -otherwise be available to you under applicable patent law. - - 12. No Surrender of Others' Freedom. - - If conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot convey a -covered work so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you may -not convey it at all. For example, if you agree to terms that obligate you -to collect a royalty for further conveying from those to whom you convey -the Program, the only way you could satisfy both those terms and this -License would be to refrain entirely from conveying the Program. - - 13. Use with the GNU Affero General Public License. - - Notwithstanding any other provision of this License, you have -permission to link or combine any covered work with a work licensed -under version 3 of the GNU Affero General Public License into a single -combined work, and to convey the resulting work. The terms of this -License will continue to apply to the part which is the covered work, -but the special requirements of the GNU Affero General Public License, -section 13, concerning interaction through a network will apply to the -combination as such. - - 14. Revised Versions of this License. - - The Free Software Foundation may publish revised and/or new versions of -the GNU General Public License from time to time. Such new versions will -be similar in spirit to the present version, but may differ in detail to -address new problems or concerns. - - Each version is given a distinguishing version number. If the -Program specifies that a certain numbered version of the GNU General -Public License "or any later version" applies to it, you have the -option of following the terms and conditions either of that numbered -version or of any later version published by the Free Software -Foundation. If the Program does not specify a version number of the -GNU General Public License, you may choose any version ever published -by the Free Software Foundation. - - If the Program specifies that a proxy can decide which future -versions of the GNU General Public License can be used, that proxy's -public statement of acceptance of a version permanently authorizes you -to choose that version for the Program. - - Later license versions may give you additional or different -permissions. However, no additional obligations are imposed on any -author or copyright holder as a result of your choosing to follow a -later version. - - 15. Disclaimer of Warranty. - - THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY -APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT -HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY -OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, -THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM -IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF -ALL NECESSARY SERVICING, REPAIR OR CORRECTION. - - 16. Limitation of Liability. - - IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS -THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY -GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE -USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF -DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD -PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), -EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF -SUCH DAMAGES. - - 17. Interpretation of Sections 15 and 16. - - If the disclaimer of warranty and limitation of liability provided -above cannot be given local legal effect according to their terms, -reviewing courts shall apply local law that most closely approximates -an absolute waiver of all civil liability in connection with the -Program, unless a warranty or assumption of liability accompanies a -copy of the Program in return for a fee. - - END OF TERMS AND CONDITIONS - - How to Apply These Terms to Your New Programs - - If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -state the exclusion of warranty; and each file should have at least -the "copyright" line and a pointer to where the full notice is found. - - - Copyright (C) - - This program is free software: you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation, either version 3 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . - -Also add information on how to contact you by electronic and paper mail. - - If the program does terminal interaction, make it output a short -notice like this when it starts in an interactive mode: - - Copyright (C) - This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. - This is free software, and you are welcome to redistribute it - under certain conditions; type `show c' for details. - -The hypothetical commands `show w' and `show c' should show the appropriate -parts of the General Public License. Of course, your program's commands -might be different; for a GUI interface, you would use an "about box". - - You should also get your employer (if you work as a programmer) or school, -if any, to sign a "copyright disclaimer" for the program, if necessary. -For more information on this, and how to apply and follow the GNU GPL, see -. - - The GNU General Public License does not permit incorporating your program -into proprietary programs. If your program is a subroutine library, you -may consider it more useful to permit linking proprietary applications with -the library. If this is what you want to do, use the GNU Lesser General -Public License instead of this License. But first, please read -. - ---------------------------------------------------------- - -Name: variant -License: BSD-3-Clause -Files: third_party/opentelemetry-cpp/third_party/opentracing-cpp/3rd_party/include/opentracing/variant - -Copyright (c) MapBox -All rights reserved. - -Redistribution and use in source and binary forms, with or without modification, -are permitted provided that the following conditions are met: - -- Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. -- Redistributions in binary form must reproduce the above copyright notice, this - list of conditions and the following disclaimer in the documentation and/or - other materials provided with the distribution. -- Neither the name "MapBox" nor the names of its contributors may be - used to endorse or promote products derived from this software without - specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND -ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR -ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON -ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ---------------------------------------------------------- - -Name: vcpkg -License: MIT -Files: third_party/opentelemetry-cpp/tools/vcpkg - -MIT License - -Copyright (c) Microsoft Corporation - -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. - ---------------------------------------------------------- - -Name: vulkan -License: Apache-2.0 with exception -Files: third_party/opentelemetry-cpp/tools/vcpkg/ports/vulkan - -/* -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - - -Apache License -Version 2.0, January 2004 -http://www.apache.org/licenses/ - -TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - -1. Definitions. - -"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. - -"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. - -"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. - -"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. - -"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. - -"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. - -"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). - -"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. - -"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." - -"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. - -2. Grant of Copyright License. - -Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. - -3. Grant of Patent License. - -Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. - -4. Redistribution. - -You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: - -You must give any other recipients of the Work or Derivative Works a copy of this License; and -You must cause any modified files to carry prominent notices stating that You changed the files; and -You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and -If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. -You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. - -5. Submission of Contributions. - -Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. - -6. Trademarks. - -This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. - -7. Disclaimer of Warranty. - -Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. - -8. Limitation of Liability. - -In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. - -9. Accepting Warranty or Additional Liability. - -While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. - -END OF TERMS AND CONDITIONS - -=============================================================================================================================================== - -/Copyright (C) 2012 LunarG, Inc. -//All rights reserved. -// -//Redistribution and use in source and binary forms, with or without -//modification, are permitted provided that the following conditions -//are met: -// -// Redistributions of source code must retain the above copyright -// notice, this list of conditions and the following disclaimer. -// -// Redistributions in binary form must reproduce the above -// copyright notice, this list of conditions and the following -// disclaimer in the documentation and/or other materials provided -// with the distribution. -// -// Neither the name of LunarG Inc. nor the names of its -// contributors may be used to endorse or promote products derived -// from this software without specific prior written permission. -// -//THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -//"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -//LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS -//FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE -//COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, -//INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, -//BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -//LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -//CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -//LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN -//ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE -//POSSIBILITY OF SUCH DAMAGE. - -=============================================================================================================================================== - -#============================================================================= -# Copyright 2007-2009 Kitware, Inc. -# Copyright 2007-2008 Miguel A. Figueroa-Villanueva -# -# Distributed under the OSI-approved BSD License (the "License"); -# see accompanying file Copyright_cmake.txt for details. -# -# This software is distributed WITHOUT ANY WARRANTY; without even the -# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. -# See the License for more information. -#============================================================================= -# (To distributed this file outside of CMake, substitute the full -# License text for the above reference.) - - -============================================================================================================================================== - -// -// Copyright (C) 2015-2018 Google, Inc. -// Copyright (C) -// -// All rights reserved. -// -// Redistribution and use in source and binary forms, with or without -// modification, are permitted provided that the following conditions -// are met: -// -// Redistributions of source code must retain the above copyright -// notice, this list of conditions and the following disclaimer. -// -// Redistributions in binary form must reproduce the above -// copyright notice, this list of conditions and the following -// disclaimer in the documentation and/or other materials provided -// with the distribution. -// -// Neither the name of 3Dlabs Inc. Ltd. nor the names of its -// contributors may be used to endorse or promote products derived -// from this software without specific prior written permission. -// -// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS -// FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE -// COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, -// INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, -// BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -// LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN -// ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE -// POSSIBILITY OF SUCH DAMAGE. -// - -========================================================================================================================================== - -Note: This license has also been called the "New BSD License" or "Modified BSD License". See also the 2-clause BSD License. -Copyright -Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: -1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. -2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. -3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - -========================================================================================================================================== - -/* -* xxHash - Fast Hash algorithm -* Copyright (C) 2012-2016, Yann Collet -* -* BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php) -* -* Redistribution and use in source and binary forms, with or without -* modification, are permitted provided that the following conditions are -* met: -* -* * Redistributions of source code must retain the above copyright -* notice, this list of conditions and the following disclaimer. -* * Redistributions in binary form must reproduce the above -* copyright notice, this list of conditions and the following disclaimer -* in the documentation and/or other materials provided with the -* distribution. -* -* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -* -* You can contact the author at : -* - xxHash homepage: http://www.xxhash.com -* - xxHash source repository : https://github.com/Cyan4973/xxHash -*/ - - -=========================================================================================================================================== - -# Copyright (C) 2018 Google, Inc. -# -# All rights reserved. -# -# Redistribution and use in source and binary forms, with or without -# modification, are permitted provided that the following conditions -# are met: -# -# Redistributions of source code must retain the above copyright -# notice, this list of conditions and the following disclaimer. -# -# Redistributions in binary form must reproduce the above -# copyright notice, this list of conditions and the following -# disclaimer in the documentation and/or other materials provided -# with the distribution. -# -# Neither the name of Google Inc. nor the names of its -# contributors may be used to endorse or promote products derived -# from this software without specific prior written permission. -# -# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS -# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE -# COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, -# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, -# BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN -# ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE -# POSSIBILITY OF SUCH DAMAGE. - -========================================================================================================================================== - -/* A Bison parser, made by GNU Bison 3.0.4. */ - -/* Bison implementation for Yacc-like parsers in C -Copyright (C) 1984, 1989-1990, 2000-2015 Free Software Foundation, Inc. -This program is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. -You should have received a copy of the GNU General Public License -along with this program. If not, see . */ - -/* As a special exception, you may create a larger work that contains -part or all of the Bison parser skeleton and distribute that work -under terms of your choice, so long as that work isn't itself a -parser generator using the skeleton or a modified version thereof -as a parser skeleton. Alternatively, if you modify or redistribute -the parser skeleton itself, you may (at your option) remove this -special exception, which will cause the skeleton and the resulting -Bison output files to be licensed under the GNU General Public -License without this special exception. -This special exception was added by the Free Software Foundation in -version 2.2 of Bison. */ - -/* C LALR(1) parser skeleton written by Richard Stallman, by -simplifying the original so-called "semantic" parser. */ - -/* All symbols defined below should begin with yy or YY, to avoid -infringing on user name space. This should be done even for local -variables, as they might otherwise be expanded by user macros. -There are some unavoidable exceptions within include files to -define necessary library symbols; they are noted "INFRINGES ON -USER NAME SPACE" below. */ - -============================================================================================================================================== - -copyright : [ -Copyright (c) 2017 The Khronos Group Inc., -, -Permission is hereby granted, free of charge, to any person obtaining a copy, -of this software and/or associated documentation files (the \Materials\"),", -to deal in the Materials without restriction, including without limitation, -the rights to use, copy, modify, merge, publish, distribute, sublicense,, -and/or sell copies of the Materials, and to permit persons to whom the, -Materials are 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 Materials., -, -MODIFICATIONS TO THIS FILE MAY MEAN IT NO LONGER ACCURATELY REFLECTS KHRONOS, -STANDARDS. THE UNMODIFIED, NORMATIVE VERSIONS OF KHRONOS SPECIFICATIONS AND, -HEADER INFORMATION ARE LOCATED AT https://www.khronos.org/registry/ , -, -THE MATERIALS ARE 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 MATERIALS OR THE USE OR OTHER DEALINGS, -IN THE MATERIALS. - -============================================================================================================================================= - -CMake - Cross Platform Makefile Generator -Copyright 2000-2009 Kitware, Inc., Insight Software Consortium -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions -are met: - -* Redistributions of source code must retain the above copyright -notice, this list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright -notice, this list of conditions and the following disclaimer in the -documentation and/or other materials provided with the distribution. - -* Neither the names of Kitware, Inc., the Insight Software Consortium, -nor the names of their contributors may be used to endorse or promote -products derived from this software without specific prior written -permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -AS IS AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - ------------------------------------------------------------------------------- - -The above copyright and license notice applies to distributions of -CMake in source and binary form. Some source files contain additional -notices of original copyright by their contributors; see each source -for details. Third-party software packages supplied with CMake under -compatible licenses provide their own copyright notices documented in -corresponding subdirectories. - ------------------------------------------------------------------------------- - -CMake was initially developed by Kitware with the following sponsorship: - -* National Library of Medicine at the National Institutes of Health -as part of the Insight Segmentation and Registration Toolkit (ITK). - -* US National Labs (Los Alamos, Livermore, Sandia) ASC Parallel -Visualization Initiative. - -* National Alliance for Medical Image Computing (NAMIC) is funded by the -National Institutes of Health through the NIH Roadmap for Medical Research, -Grant U54 EB005149. - -* Kitware, Inc. - -======================================================================================================================================== - -The authors of this software are Rob Pike and Ken Thompson. -* Copyright (c) 2002 by Lucent Technologies. -* Permission to use, copy, modify, and distribute this software for any -* purpose without fee is hereby granted, provided that this entire notice -* is included in all copies of any software which is or includes a copy -* or modification of this software and in all copies of the supporting -* documentation for such software. -* THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED -* WARRANTY. IN PARTICULAR, NEITHER THE AUTHORS NOR LUCENT TECHNOLOGIES MAKE ANY -* REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY -* OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE. - - -======================================================================================================================================== - -Copyright (c) 2015-2018 Baldur Karlsson - -Copyright (c) 2014 Crytek - -Copyright (c) 1998-2018 Third party code and tools - -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. - -========================================================================================================================================= - -/* -Copyright (c) 2009 Dave Gamble -Copyright (c) 2015-2016 The Khronos Group Inc. -Copyright (c) 2015-2016 Valve Corporation -Copyright (c) 2015-2016 LunarG, Inc. - -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. -*/ - -=========================================================================================================================================== - -Copyright (c) 2005 - 2017 G-Truc Creation - -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 JsonCpp library's source code, including accompanying documentation, -tests and demonstration applications, are licensed under the following -conditions... -The author (Baptiste Lepilleur) explicitly disclaims copyright in all -jurisdictions which recognize such a disclaimer. In such jurisdictions, -this software is released into the Public Domain. -In jurisdictions which do not recognize Public Domain property (e.g. Germany as of -2010), this software is Copyright (c) 2007-2010 by Baptiste Lepilleur, and is -released under the terms of the MIT License (see below). -In jurisdictions which recognize Public Domain property, the user of this -software may choose to accept it either as 1) Public Domain, 2) under the -conditions of the MIT License (see below), or 3) under the terms of dual -Public Domain/MIT License conditions described here, as they choose. -The MIT License is about as close to Public Domain as a license can get, and is -described in clear, concise terms at: -http://en.wikipedia.org/wiki/MIT_License - -The full text of the MIT License follows: - -Copyright (c) 2007-2010 Baptiste Lepilleur -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. - -========================================================================================================================================== - -/** -* `murmurhash.h' - murmurhash -* -* copyright (c) 2014 joseph werle -* Copyright (c) 2015-2016 The Khronos Group Inc. -* Copyright (c) 2015-2016 Valve Corporation -* Copyright (c) 2015-2016 LunarG, Inc. -* -* Permission is hereby granted, free of charge, to any person obtaining a copy -* of this software and/or associated documentation files (the "Materials"), to -* deal in the Materials without restriction, including without limitation the -* rights to use, copy, modify, merge, publish, distribute, sublicense, and/or -* sell copies of the Materials, and to permit persons to whom the Materials are -* furnished to do so, subject to the following conditions: -* -* The above copyright notice(s) and this permission notice shall be included in -* all copies or substantial portions of the Materials. -* -* THE MATERIALS ARE 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 MATERIALS OR THE -* USE OR OTHER DEALINGS IN THE MATERIALS. -*/ - -========================================================================================================================================= - -Licenced as X11: http://www.kryogenix.org/code/browser/licence.html -This basically means: do what you want with it. - -========================================================================================================================================= - -/////////////////////////////////////////////////////////////////////////////////// -/// OpenGL Mathematics (glm.g-truc.net) -/// -/// Copyright (c) 2005 - 2014 G-Truc Creation (www.g-truc.net) -/// 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. -/// -/// @ref core -/// @file glm/common.hpp -/// @date 2013-12-24 / 2013-12-24 -/// @author Christophe Riccio -/////////////////////////////////////////////////////////////////////////////////// - - -========================================================================================================================================== - -// LICENSE -// -// This software is in the public domain. Where that dedication is not -// recognized, you are granted a perpetual, irrevocable license to copy, -// distribute, and modify this file as you see fit. -// - -========================================================================================================================================== - -Simple DirectMedia Layer -Copyright (C) 1997-2018 Sam Lantinga - -This software is provided 'as-is', without any express or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -1. The origin of this software must not be misrepresented; you must not -claim that you wrote the original software. If you use this software -in a product, an acknowledgment in the product documentation would be -appreciated but is not required. -2. Altered source versions must be plainly marked as such, and must not be -misrepresented as being the original software. -3. This notice may not be removed or altered from any source distribution. - -========================================================================================================================================= - -/****************************************************************************\ -Copyright (c) 2002, NVIDIA Corporation. - -NVIDIA Corporation("NVIDIA") supplies this software to you in -consideration of your agreement to the following terms, and your use, -installation, modification or redistribution of this NVIDIA software -constitutes acceptance of these terms. If you do not agree with these -terms, please do not use, install, modify or redistribute this NVIDIA -software. - -In consideration of your agreement to abide by the following terms, and -subject to these terms, NVIDIA grants you a personal, non-exclusive -license, under NVIDIA's copyrights in this original NVIDIA software (the -NVIDIA Software), to use, reproduce, modify and redistribute the -NVIDIA Software, with or without modifications, in source and/or binary -forms; provided that if you redistribute the NVIDIA Software, you must -retain the copyright notice of NVIDIA, this notice and the following -text and disclaimers in all such redistributions of the NVIDIA Software. -Neither the name, trademarks, service marks nor logos of NVIDIA -Corporation may be used to endorse or promote products derived from the -NVIDIA Software without specific prior written permission from NVIDIA. -Except as expressly stated in this notice, no other rights or licenses -express or implied, are granted by NVIDIA herein, including but not -limited to any patent rights that may be infringed by your derivative -works or by other works in which the NVIDIA Software may be -incorporated. No hardware is licensed hereunder. - -THE NVIDIA SOFTWARE IS BEING PROVIDED ON AN "AS IS" BASIS, WITHOUT -WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED, -INCLUDING WITHOUT LIMITATION, WARRANTIES OR CONDITIONS OF TITLE, -NON-INFRINGEMENT, MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR -ITS USE AND OPERATION EITHER ALONE OR IN COMBINATION WITH OTHER -PRODUCTS. - -IN NO EVENT SHALL NVIDIA BE LIABLE FOR ANY SPECIAL, INDIRECT, -INCIDENTAL, EXEMPLARY, CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED -TO, LOST PROFITS; PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF -USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) OR ARISING IN ANY WAY -OUT OF THE USE, REPRODUCTION, MODIFICATION AND/OR DISTRIBUTION OF THE -NVIDIA SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF CONTRACT, -TORT (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF -NVIDIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -\****************************************************************************/ - -================================================================================================================================================== - -This software is provided 'as-is', without any express or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. -3. This notice may not be removed or altered from any source distribution. - - -================================================================================================================================================== - -GNU LESSER GENERAL PUBLIC LICENSE -Version 3, 29 June 2007 - -Copyright (C) 2007 Free Software Foundation, Inc. - -Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. - -This version of the GNU Lesser General Public License incorporates the terms and conditions of version 3 of the GNU General Public License, supplemented by the additional permissions listed below. - -0. Additional Definitions. - -As used herein, "this License" refers to version 3 of the GNU Lesser General Public License, and the "GNU GPL" refers to version 3 of the GNU General Public License. - -"The Library" refers to a covered work governed by this License, other than an Application or a Combined Work as defined below. - -An "Application" is any work that makes use of an interface provided by the Library, but which is not otherwise based on the Library. Defining a subclass of a class defined by the Library is deemed a mode of using an interface provided by the Library. - -A "Combined Work" is a work produced by combining or linking an Application with the Library. The particular version of the Library with which the Combined Work was made is also called the "Linked Version". - -The "Minimal Corresponding Source" for a Combined Work means the Corresponding Source for the Combined Work, excluding any source code for portions of the Combined Work that, considered in isolation, are based on the Application, and not on the Linked Version. - -The "Corresponding Application Code" for a Combined Work means the object code and/or source code for the Application, including any data and utility programs needed for reproducing the Combined Work from the Application, but excluding the System Libraries of the Combined Work. - -1. Exception to Section 3 of the GNU GPL. - -You may convey a covered work under sections 3 and 4 of this License without being bound by section 3 of the GNU GPL. - -2. Conveying Modified Versions. - -If you modify a copy of the Library, and, in your modifications, a facility refers to a function or data to be supplied by an Application that uses the facility (other than as an argument passed when the facility is invoked), then you may convey a copy of the modified version: - -a) under this License, provided that you make a good faith effort to ensure that, in the event an Application does not supply the function or data, the facility still operates, and performs whatever part of its purpose remains meaningful, or -b) under the GNU GPL, with none of the additional permissions of this License applicable to that copy. -3. Object Code Incorporating Material from Library Header Files. - -The object code form of an Application may incorporate material from a header file that is part of the Library. You may convey such object code under terms of your choice, provided that, if the incorporated material is not limited to numerical parameters, data structure layouts and accessors, or small macros, inline functions and templates (ten or fewer lines in length), you do both of the following: - -a) Give prominent notice with each copy of the object code that the Library is used in it and that the Library and its use are covered by this License. -b) Accompany the object code with a copy of the GNU GPL and this license document. -4. Combined Works. - -You may convey a Combined Work under terms of your choice that, taken together, effectively do not restrict modification of the portions of the Library contained in the Combined Work and reverse engineering for debugging such modifications, if you also do each of the following: - -a) Give prominent notice with each copy of the Combined Work that the Library is used in it and that the Library and its use are covered by this License. -b) Accompany the Combined Work with a copy of the GNU GPL and this license document. -c) For a Combined Work that displays copyright notices during execution, include the copyright notice for the Library among these notices, as well as a reference directing the user to the copies of the GNU GPL and this license document. -d) Do one of the following: -0) Convey the Minimal Corresponding Source under the terms of this License, and the Corresponding Application Code in a form suitable for, and under terms that permit, the user to recombine or relink the Application with a modified version of the Linked Version to produce a modified Combined Work, in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source. -1) Use a suitable shared library mechanism for linking with the Library. A suitable mechanism is one that (a) uses at run time a copy of the Library already present on the user's computer system, and (b) will operate properly with a modified version of the Library that is interface-compatible with the Linked Version. -e) Provide Installation Information, but only if you would otherwise be required to provide such information under section 6 of the GNU GPL, and only to the extent that such information is necessary to install and execute a modified version of the Combined Work produced by recombining or relinking the Application with a modified version of the Linked Version. (If you use option 4d0, the Installation Information must accompany the Minimal Corresponding Source and Corresponding Application Code. If you use option 4d1, you must provide the Installation Information in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source.) -5. Combined Libraries. - -You may place library facilities that are a work based on the Library side by side in a single library together with other library facilities that are not Applications and are not covered by this License, and convey such a combined library under terms of your choice, if you do both of the following: - -a) Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities, conveyed under the terms of this License. -b) Give prominent notice with the combined library that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work. -6. Revised Versions of the GNU Lesser General Public License. - -The Free Software Foundation may publish revised and/or new versions of the GNU Lesser General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. - -Each version is given a distinguishing version number. If the Library as you received it specifies that a certain numbered version of the GNU Lesser General Public License "or any later version" applies to it, you have the option of following the terms and conditions either of that published version or of any later version published by the Free Software Foundation. If the Library as you received it does not specify a version number of the GNU Lesser General Public License, you may choose any version of the GNU Lesser General Public License ever published by the Free Software Foundation. - -If the Library as you received it specifies that a proxy can decide whether future versions of the GNU Lesser General Public License shall apply, that proxy's public statement of acceptance of any version is permanent authorization for you to choose that version for the Library. - -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- diff --git a/doc/README.md b/doc/README.md index e65f3f0d..fb9635fd 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,34 +1,41 @@ -Sphinx is used to generate the HTML for the python-oracledb documentation. +# python-oracledb Documentation Source -The generated python-oracledb documentation is at -https://python-oracledb.readthedocs.io/ +This directory contains the python-oracledb documentation source. It is written +using reST (re-Structured Text). The source files are processed using +[Sphinx](http://www.sphinx-doc.org) and can be turned into HTML, PDF or ePub +documentation. -This directory contains the documentation source. It is written using reST -(re-Structured Text). The source files are processed using Sphinx and can be -turned into HTML, PDF or ePub documentation. +**Visit https://python-oracledb.readthedocs.io/ for pre-built production and +development python-oracledb documentation** -If you wish to build documentation yourself, install Sphinx and the Read the -Docs theme. Sphinx is available on many Linux distributions as a pre-built -package. You can also install Sphinx and the Read the Docs theme using the -Python package manager "pip", for example:: +## Building Documentation Locally - python -m pip install -r requirements.txt +To build the documentation locally: -For more information on Sphinx, please visit this page: +1. Install Sphinx and the Read the Docs theme using the Python package manager + ``pip``, for example: -http://www.sphinx-doc.org + python -m pip install --upgrade -r requirements.txt -Once Sphinx is installed, the supplied Makefile can be used to build the -different targets, for example to build the HTML documentation, run:: + You can alternatively install these from pre-built packages for your + operating system. - make +2. The "oracledb" module must be built and importable. This is needed for the + "autodoc" extension to create function signature documentation. -To make ePub documentation, run:: +3. Once Sphinx is installed, and "oracledb" can be imported by Python, use the + Makefile to build your desired documentation format. - make epub + To build the HTML documentation: -To make PDF documentation, run:: + make - make pdf + To make ePub documentation: -The program ``latexmk`` may be required by Sphinx to generate PDF output. + make epub + + To make PDF documentation: + + make pdf + + The program ``latexmk`` may be required by Sphinx to generate PDF output. diff --git a/doc/src/_ext/dbapi_extension.py b/doc/src/_ext/dbapi_extension.py new file mode 100644 index 00000000..43440c9d --- /dev/null +++ b/doc/src/_ext/dbapi_extension.py @@ -0,0 +1,64 @@ +# ----------------------------------------------------------------------------- +# Copyright (c) 2025, Oracle and/or its affiliates. +# +# This software is dual-licensed to you under the Universal Permissive License +# (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License +# 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose +# either license. +# +# If you elect to accept the software under the Apache License, Version 2.0, +# the following applies: +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ----------------------------------------------------------------------------- + +# ----------------------------------------------------------------------------- +# dbapi_extension.py +# +# Used to document functionality that is an extension to the DB API definition. +# ----------------------------------------------------------------------------- + +from docutils import nodes +from docutils.parsers.rst import Directive + + +class DbApiExtension(Directive): + has_content = True + + def run(self): + text = f"{self.prefix} {' '.join(self.content)}" + result = [nodes.emphasis(text=text), nodes.paragraph()] + return result + + +class DbApiMethodExtension(DbApiExtension): + prefix = "This method is an extension to the DB API definition." + + +class DbApiAttributeExtension(DbApiExtension): + prefix = "This attribute is an extension to the DB API definition." + + +class DbApiConstantExtension(DbApiExtension): + prefix = "These constants are extensions to the DB API definition." + + +class DbApiObjectExtension(DbApiExtension): + prefix = "This object is an extension to the DB API definition." + + +def setup(app): + app.add_directive("dbapimethodextension", DbApiMethodExtension) + app.add_directive("dbapiattributeextension", DbApiAttributeExtension) + app.add_directive("dbapiconstantextension", DbApiConstantExtension) + app.add_directive("dbapiobjectextension", DbApiObjectExtension) diff --git a/doc/src/api_manual/aq.rst b/doc/src/api_manual/aq.rst index e171668f..5d662480 100644 --- a/doc/src/api_manual/aq.rst +++ b/doc/src/api_manual/aq.rst @@ -1,71 +1,47 @@ .. _aq: -*************************** +************************** API: Advanced Queuing (AQ) -*************************** +************************** + +.. currentmodule:: oracledb See :ref:`aqusermanual` for more information about using AQ in python-oracledb. -.. note:: +.. _queue: - All of these objects are extensions to the DB API. +Queue Class +=========== -.. _queue: +.. autoclass:: Queue -Queue Objects -============= + A Queue object should be created using :meth:`Connection.queue()` and is + used to enqueue and dequeue messages. -These objects are created using the :meth:`Connection.queue()` method and are -used to enqueue and dequeue messages. + .. dbapiobjectextension:: Queue Methods ------------- -.. method:: Queue.deqmany(maxMessages) - - Dequeues up to the specified number of messages from the queue and returns - a list of these messages. Each element of the returned list is a - :ref:`message property ` object. +.. automethod:: Queue.deqmany For consistency and compliance with the PEP 8 naming style, the name of the method was changed from `deqMany()`. The old name will continue to work for a period of time. -.. method:: Queue.deqone() - - Dequeues at most one message from the queue. If a message is dequeued, it - will be a :ref:`message property ` object; otherwise, it will - be the value *None*. +.. automethod:: Queue.deqone For consistency and compliance with the PEP 8 naming style, the name of the method was changed from `deqOne()`. The old name will continue to work for a period of time. -.. method:: Queue.enqmany(messages) - - Enqueues multiple messages into the queue. The ``messages`` parameter must - be a sequence containing :ref:`message property ` objects - which have all had their payload attribute set to a value that the queue - supports. - - .. warning:: - - Prior to Oracle Database 21c, calling this function in parallel on - different connections acquired from the same pool may fail due to - Oracle bug 29928074. Either ensure that this function is not run in - parallel, use standalone connections or connections from different - pools, or make multiple calls to :meth:`Queue.enqone()` instead. The - function :meth:`Queue.deqmany()` call is not affected. +.. automethod:: Queue.enqmany For consistency and compliance with the PEP 8 naming style, the name of the method was changed from `enqMany()`. The old name will continue to work for a period of time. -.. method:: Queue.enqone(message) - - Enqueues a single message into the queue. The message must be a - :ref:`message property` object which has had its payload - attribute set to a value that the queue supports. +.. automethod:: Queue.enqone For consistency and compliance with the PEP 8 naming style, the name of the method was changed from `enqOne()`. The old name will continue @@ -74,278 +50,124 @@ Queue Methods Queue Attributes ---------------- -.. attribute:: Queue.connection - - This read-only attribute returns a reference to the connection object on - which the queue was created. +.. autoproperty:: Queue.connection -.. attribute:: Queue.deqoptions - - This read-only attribute returns a reference to the :ref:`options - ` that will be used when dequeuing messages from the queue. +.. autoproperty:: Queue.deqoptions For consistency and compliance with the PEP 8 naming style, the name of the attribute was changed from ``deqOptions``. The old name will continue to work for a period of time. -.. attribute:: Queue.enqoptions - - This read-only attribute returns a reference to the :ref:`options - ` that will be used when enqueuing messages into the queue. +.. autoproperty:: Queue.enqoptions For consistency and compliance with the PEP 8 naming style, the name of the attribute was changed from ``enqOptions``. The old name will continue to work for a period of time. -.. attribute:: Queue.name +.. autoproperty:: Queue.name - This read-only attribute returns the name of the queue. - -.. attribute:: Queue.payload_type - - This read-only attribute returns the object type for payloads that can be - enqueued and dequeued. If using a JSON queue, this returns the value - ``"JSON"``. If using a raw queue, this returns the value *None*. +.. autoproperty:: Queue.payload_type For consistency and compliance with the PEP 8 naming style, the name of the attribute was changed from ``payloadType``. The old name will continue to work for a period of time. - .. _deqoptions: -Dequeue Options -=============== - -.. note:: - - These objects are used to configure how messages are dequeued from queues. - An instance of this object is found in the attribute - :attr:`Queue.deqOptions`. - - -.. attribute:: DeqOptions.condition - - This read-write attribute specifies a boolean expression similar to the where - clause of a SQL query. The boolean expression can include conditions on message - properties, user data properties and PL/SQL or SQL functions. The default - is to have no condition specified. - - -.. attribute:: DeqOptions.consumername - - This read-write attribute specifies the name of the consumer. Only messages - matching the consumer name will be accessed. If the queue is not set up for - multiple consumers this attribute should not be set. The default is to have - no consumer name specified. - - -.. attribute:: DeqOptions.correlation - - This read-write attribute specifies the correlation identifier of the message - to be dequeued. Special pattern-matching characters, such as the percent sign (%) - and the underscore (_), can be used. If multiple messages satisfy the - pattern, the order of dequeuing is indeterminate. The default is to have no - correlation specified. - - -.. attribute:: DeqOptions.deliverymode - - This write-only attribute specifies what types of messages should be - dequeued. It should be one of the values :data:`~oracledb.MSG_PERSISTENT` - (default), :data:`~oracledb.MSG_BUFFERED` or - :data:`~oracledb.MSG_PERSISTENT_OR_BUFFERED`. - - -.. attribute:: DeqOptions.mode +DeqOptions Class +================ - This read-write attribute specifies the locking behaviour associated - with the dequeue operation. It should be one of the values - :data:`~oracledb.DEQ_BROWSE`, - :data:`~oracledb.DEQ_LOCKED`, - :data:`~oracledb.DEQ_REMOVE` (default), or - :data:`~oracledb.DEQ_REMOVE_NODATA`. +.. autoclass:: DeqOptions + A DeqOptions object is used to configure how messages are dequeued + from queues. An instance of this object is found in the attribute + :attr:`Queue.deqoptions`. -.. attribute:: DeqOptions.msgid + .. dbapiobjectextension:: - This read-write attribute specifies the identifier of the message to be - dequeued. The default is to have no message identifier specified. +DeqOptions Attributes +--------------------- +.. autoproperty:: DeqOptions.condition -.. attribute:: DeqOptions.navigation +.. autoproperty:: DeqOptions.consumername - This read-write attribute specifies the position of the message that - is retrieved. It should be one of the values :data:`~oracledb.DEQ_FIRST_MSG`, - :data:`~oracledb.DEQ_NEXT_MSG` (default), or - :data:`~oracledb.DEQ_NEXT_TRANSACTION`. +.. autoproperty:: DeqOptions.correlation +.. autoproperty:: DeqOptions.deliverymode -.. attribute:: DeqOptions.transformation +.. autoproperty:: DeqOptions.mode - This read-write attribute specifies the name of the transformation that must - be applied after the message is dequeued from the database but before it is - returned to the calling application. The transformation must be created - using dbms_transform. The default is to have no transformation specified. +.. autoproperty:: DeqOptions.msgid +.. autoproperty:: DeqOptions.navigation -.. attribute:: DeqOptions.visibility +.. autoproperty:: DeqOptions.transformation - This read-write attribute specifies the transactional behavior of the dequeue - request. It should be one of the values :data:`~oracledb.DEQ_ON_COMMIT` (default) - or :data:`~oracledb.DEQ_IMMEDIATE`. This attribute is ignored when using - the :data:`~oracledb.DEQ_BROWSE` mode. Note the value of - :attr:`~Connection.autocommit` is always ignored. - - -.. attribute:: DeqOptions.wait - - This read-write attribute specifies the time to wait, in seconds, for a message - matching the search criteria to become available for dequeuing. One of the - values :data:`~oracledb.DEQ_NO_WAIT` or - :data:`~oracledb.DEQ_WAIT_FOREVER` can also be used. The default is - :data:`~oracledb.DEQ_WAIT_FOREVER`. +.. autoproperty:: DeqOptions.visibility +.. autoproperty:: DeqOptions.wait .. _enqoptions: -Enqueue Options -=============== - -.. note:: - - These objects are used to configure how messages are enqueued into queues. - An instance of this object is found in the attribute - :attr:`Queue.enqOptions`. - - -.. attribute:: EnqOptions.deliverymode - - This write-only attribute specifies what type of messages should be - enqueued. It should be one of the values :data:`~oracledb.MSG_PERSISTENT` - (default) or :data:`~oracledb.MSG_BUFFERED`. +EnqOptions Class +================ +.. autoclass:: EnqOptions -.. attribute:: EnqOptions.transformation + An EnqOptions object is used to configure how messages are enqueued into + queues. An instance of this object is found in the attribute + :attr:`Queue.enqoptions`. - This read-write attribute specifies the name of the transformation that - must be applied before the message is enqueued into the database. The - transformation must be created using dbms_transform. The default is to have - no transformation specified. + .. dbapiobjectextension:: +EnqOptions Attributes +--------------------- -.. attribute:: EnqOptions.visibility +.. autoproperty:: EnqOptions.deliverymode - This read-write attribute specifies the transactional behavior of the enqueue - request. It should be one of the values :data:`~oracledb.ENQ_ON_COMMIT` (default) - or :data:`~oracledb.ENQ_IMMEDIATE`. Note the value of - :attr:`~Connection.autocommit` is ignored. +.. autoproperty:: EnqOptions.transformation +.. autoproperty:: EnqOptions.visibility .. _msgproperties: -Message Properties -================== +MessageProperties Class +======================= -.. note:: +.. autoclass:: MessageProperties - These objects are used to identify the properties of messages that are - enqueued and dequeued in queues. They are created by the method + A MessageProperties object is used to identify the properties of messages + that are enqueued and dequeued in queues. They are created by the method :meth:`Connection.msgproperties()`. They are used by the methods - :meth:`Queue.enqone()` and :meth:`Queue.enqmany()` and - returned by the methods :meth:`Queue.deqone()` and :meth:`Queue.deqmany()`. - - -.. attribute:: MessageProperties.attempts - - This read-only attribute specifies the number of attempts that have been - made to dequeue the message. - - -.. attribute:: MessageProperties.correlation - - This read-write attribute specifies the correlation used when the message - was enqueued. - - -.. attribute:: MessageProperties.delay - - This read-write attribute specifies the number of seconds to delay an - enqueued message. Any integer is acceptable but the constant - :data:`~oracledb.MSG_NO_DELAY` can also be used indicating that the - message is available for immediate dequeuing. - - -.. attribute:: MessageProperties.deliverymode - - This read-only attribute specifies the type of message that was dequeued. - It will be one of the values :data:`~oracledb.MSG_PERSISTENT` or - :data:`~oracledb.MSG_BUFFERED`. - - -.. attribute:: MessageProperties.enqtime - - This read-only attribute specifies the time that the message was enqueued. - - -.. attribute:: MessageProperties.exceptionq - - This read-write attribute specifies the name of the queue to which the message - is moved if it cannot be processed successfully. Messages are moved if the - number of unsuccessful dequeue attempts has exceeded the maximum number of - retries or if the message has expired. All messages in the exception queue - are in the :data:`~oracledb.MSG_EXPIRED` state. The default value is the - name of the exception queue associated with the queue table. - - -.. attribute:: MessageProperties.expiration - - This read-write attribute specifies, in seconds, how long the message is - available for dequeuing. This attribute is an offset from the delay attribute. - Expiration processing requires the queue monitor to be running. Any integer is - accepted but the constant :data:`~oracledb.MSG_NO_EXPIRATION` can also be - used indicating that the message never expires. - + :meth:`Queue.enqone()` and :meth:`Queue.enqmany()` and returned by the + methods :meth:`Queue.deqone()` and :meth:`Queue.deqmany()`. -.. attribute:: MessageProperties.msgid + .. dbapiobjectextension:: - This read-only attribute specifies the id of the message in the last queue - that enqueued or dequeued the message. If the message has never been - dequeued or enqueued, the value will be *None*. +MessageProperties Attributes +---------------------------- +.. autoproperty:: MessageProperties.attempts -.. attribute:: MessageProperties.payload +.. autoproperty:: MessageProperties.correlation - This read-write attribute identifies the payload that will be enqueued or the - payload that was dequeued when using a :ref:`queue `. When enqueuing, - the value is checked to ensure that it conforms to the type expected by that - queue. For RAW queues, the value can be a bytes object or a string. If the - value is a string it will first be converted to bytes in the encoding UTF-8. +.. autoproperty:: MessageProperties.delay +.. autoproperty:: MessageProperties.deliverymode -.. attribute:: MessageProperties.priority +.. autoproperty:: MessageProperties.enqtime - This read-write attribute specifies the priority of the message. A smaller - number indicates a higher priority. The priority can be any integer, including - negative numbers. The default value is *0*. +.. autoproperty:: MessageProperties.exceptionq +.. autoproperty:: MessageProperties.expiration -.. attribute:: MessageProperties.state +.. autoproperty:: MessageProperties.msgid - This read-only attribute specifies the state of the message at the time of - the dequeue. It will be one of the values :data:`~oracledb.MSG_WAITING`, - :data:`~oracledb.MSG_READY`, :data:`~oracledb.MSG_PROCESSED` or - :data:`~oracledb.MSG_EXPIRED`. +.. autoproperty:: MessageProperties.payload -.. attribute:: MessageProperties.recipients +.. autoproperty:: MessageProperties.priority - This read-write attribute specifies a list of recipient names that can be - associated with a message at the time of enqueuing the message. This allows a - limited set of recipients to dequeue each message. The recipient list associated - with the message overrides the queue subscriber list, if there is one. The - recipient names need not be in the subscriber list but can be, if desired. +.. autoproperty:: MessageProperties.recipients - To dequeue a message, the consumername attribute can be set to one of - the recipient names. The original message recipient list is not - available on dequeued messages. All recipients have to dequeue a - message before it gets removed from the queue. +.. autoproperty:: MessageProperties.state diff --git a/doc/src/api_manual/async_aq.rst b/doc/src/api_manual/async_aq.rst new file mode 100644 index 00000000..058433dd --- /dev/null +++ b/doc/src/api_manual/async_aq.rst @@ -0,0 +1,85 @@ +.. _asyncaq: + +******************************** +API: Async Advanced Queuing (AQ) +******************************** + +.. currentmodule:: oracledb + +See :ref:`aqusermanual` for more information about using AQ in python-oracledb. + +.. versionadded:: 3.1.0 + +.. note:: + + AsyncQueue objects are only supported in python-oracledb Thin mode. + +.. _asyncqueue: + +AsyncQueue Class +================ + +.. autoclass:: AsyncQueue + + An AsyncQueue object should be created using + :meth:`AsyncConnection.queue()` and is used to enqueue and dequeue + messages. + +AsyncQueue Methods +------------------ + +.. automethod:: AsyncQueue.deqmany + +.. automethod:: AsyncQueue.deqone + +.. automethod:: AsyncQueue.enqmany + +.. automethod:: AsyncQueue.enqone + +AsyncQueue Attributes +--------------------- + +.. autoproperty:: AsyncQueue.connection + +.. autoproperty:: AsyncQueue.deqoptions + +.. autoproperty:: AsyncQueue.enqoptions + +.. autoproperty:: AsyncQueue.name + +.. autoproperty:: AsyncQueue.payload_type + +.. _asyncdeqoptions: + +DeqOptions Class +================ + +A DeqOptions object is used to configure how messages are dequeued from +queues. An instance of this object is found in the attribute +:attr:`AsyncQueue.deqoptions`. + +See :ref:`deqoptions` for information on the supported attributes. + +.. _asyncenqoptions: + +EnqOptions Class +================ + +An EnqOptions object is used to configure how messages are enqueued into +queues. An instance of this object is found in the attribute +:attr:`AsyncQueue.enqoptions`. + +See :ref:`enqoptions` for information on the supported attributes. + +.. _asyncmsgproperties: + +MessageProperties Class +======================= + +A MessageProperties object is used to identify the properties of messages +that are enqueued and dequeued in queues. They are created by the method +:meth:`AsyncConnection.msgproperties()`. They are used by the method +:meth:`AsyncQueue.enqone()` and returned by the method +:meth:`AsyncQueue.deqone()`. + +See :ref:`msgproperties` for information on the supported attributes. diff --git a/doc/src/api_manual/async_connection.rst b/doc/src/api_manual/async_connection.rst index f08e31da..c31cab3b 100644 --- a/doc/src/api_manual/async_connection.rst +++ b/doc/src/api_manual/async_connection.rst @@ -4,282 +4,162 @@ API: AsyncConnection Objects **************************** -An AsyncConnection object can be created with :meth:`oracledb.connect_async()` -or with :meth:`AsyncConnectionPool.acquire()`. AsyncConnections support use of -concurrent programming with `asyncio `__. Unless explicitly noted as synchronous, the AsyncConnection -methods should be used with ``await``. This object is an extension to the DB -API. +.. currentmodule:: oracledb -.. versionadded:: 2.0.0 +AsyncConnection Class +===================== -.. note:: +.. autoclass:: AsyncConnection - AsyncConnection objects are only supported in the python-oracledb Thin - mode. + An AsyncConnection object should be created with + :meth:`oracledb.connect_async()` or with + :meth:`AsyncConnectionPool.acquire()`. AsyncConnections support use of + concurrent programming with + `asyncio `__. -.. note:: + .. dbapiobjectextension:: - Any outstanding database transaction will be rolled back when the - connection object is destroyed or closed. You must perform a - :meth:`commit ` first if you want data to - persist in the database, see :ref:`txnasync`. + .. versionadded:: 2.0.0 -.. _asyncconnmeth: - -AsyncConnection Methods -======================= - -.. method:: AsyncConnection.__aenter__() - - The entry point for the asynchronous connection as a context manager. It - returns itself. - -.. method:: AsyncConnection.__aexit__() + .. note:: - The exit point for the asynchronous connection as a context manager. This - will close the connection and roll back any uncommitted transaction. + AsyncConnection objects are only supported in python-oracledb Thin + mode. -.. method:: AsyncConnection.callfunc(name, return_type, parameters=None, \ - keyword_parameters=None) + .. note:: - Calls a PL/SQL function with the given name. + Any outstanding database transaction will be rolled back when the + connection object is destroyed or closed. You must perform a + :meth:`commit ` first if you want data to persist in the + database, see :ref:`txnasync`. - This is a shortcut for calling :meth:`AsyncConnection.cursor()`, - :meth:`AsyncCursor.callfunc()`, and then :meth:`AsyncCursor.close()`. +.. _asyncconnmeth: -.. method:: AsyncConnection.callproc(name, parameters=None, \ - keyword_parameters=None) +AsyncConnection Methods +======================= - Calls a PL/SQL procedure with the given name. +.. automethod:: AsyncConnection.__aenter__ - This is a shortcut for calling :meth:`AsyncConnection.cursor()`, - :meth:`AsyncCursor.callproc()`, and then :meth:`AsyncCursor.close()`. +.. automethod:: AsyncConnection.__aexit__ -.. method:: AsyncConnection.cancel() +.. automethod:: AsyncConnection.begin_sessionless_transaction - A synchronous method that breaks a long-running statement. + See :ref:`sessionlesstxns`. -.. method:: AsyncConnection.changepassword(old_password, new_password) + .. versionadded:: 3.3.0 - Changes the password for the user to which the connection is connected. +.. automethod:: AsyncConnection.callfunc -.. method:: AsyncConnection.close() +.. automethod:: AsyncConnection.callproc - Closes the connection. +.. automethod:: AsyncConnection.cancel -.. method:: AsyncConnection.commit() +.. automethod:: AsyncConnection.changepassword - Commits any pending transaction to the database. +.. automethod:: AsyncConnection.close -.. method:: AsyncConnection.createlob(lob_type) + .. note:: - Creates and returns a new temporary LOB of the specified type. + Asynchronous connections are not automatically closed at the end of + scope. This is different to synchronous connection + behavior. Asynchronous connections should either be explicitly closed, + or have been initially created via a `context manager + `__ + ``with`` block. -.. method:: AsyncConnection.cursor(scrollable=False) +.. automethod:: AsyncConnection.commit - A synchronous method that returns an :ref:`AsyncCursor object - ` associated with the connection. +.. automethod:: AsyncConnection.createlob -.. method:: AsyncConnection.decode_oson(data) +.. automethod:: AsyncConnection.cursor - A synchronous method that decodes `OSON-encoded - `__ - bytes and returns the object encoded in those bytes. This is useful for - fetching columns which have the check constraint ``IS JSON FORMAT OSON`` - enabled. +.. automethod:: AsyncConnection.decode_oson .. versionadded:: 2.1.0 -.. method:: AsyncConnection.encode_oson(value) - - A synchronous method that encodes a Python value into `OSON-encoded - `__ - bytes and returns them. This is useful for inserting into columns which - have the check constraint ``IS JSON FORMAT OSON`` enabled. - - .. versionadded:: 2.1.0 +.. automethod:: AsyncConnection.direct_path_load -.. method:: AsyncConnection.execute(statement, parameters=None) + See :ref:`directpathloads`. - Executes a statement against the database. + .. versionadded:: 3.4.0 - This is a shortcut for calling :meth:`AsyncConnection.cursor()`, - :meth:`AsyncCursor.execute()`, and then :meth:`AsyncCursor.close()` + .. dbapimethodextension:: -.. method:: AsyncConnection.executemany(statement, parameters) +.. automethod:: AsyncConnection.encode_oson - Executes a SQL statement once using all bind value mappings or sequences - found in the sequence parameters. This can be used to insert, update, or - delete multiple rows in a table with a single python-oracledb call. It can - also invoke a PL/SQL procedure multiple times. + .. versionadded:: 2.1.0 - The ``parameters`` parameter can be a list of tuples, where each tuple item - maps to one bind variable placeholder in ``statement``. It can also be a - list of dictionaries, where the keys match the bind variable placeholder - names in ``statement``. If there are no bind values, or values have - previously been bound, the ``parameters`` value can be an integer - specifying the number of iterations. +.. automethod:: AsyncConnection.execute - This is a shortcut for calling :meth:`AsyncConnection.cursor()`, - :meth:`AsyncCursor.executemany()`, and then :meth:`AsyncCursor.close()`. +.. automethod:: AsyncConnection.executemany -.. method:: AsyncConnection.fetch_df_all(statement, parameters=None, \ - arraysize=None) +.. automethod:: AsyncConnection.fetchall - Fetches all rows of the SQL query ``statement``, returning them in an - :ref:`OracleDataFrame ` object. An empty - OracleDataFrame is returned if there are no rows available. + .. versionchanged:: 3.4.0 - The ``parameters`` parameter can be a list of tuples, where each tuple item - maps to one :ref:`bind variable placeholder ` in ``statement``. It - can also be a list of dictionaries, where the keys match the bind variable - placeholder names in ``statement``. + The ``fetch_lobs`` and ``fetch_decimals`` parameters were added. - The ``arraysize`` parameter can be specified to tune performance of fetching - data across the network. It defaults to :attr:`defaults.arraysize`. - Internally, the ``fetch_df_all()``'s :attr:`Cursor.prefetchrows` size is - always set to the value of the explicit or default ``arraysize`` parameter - value. +.. automethod:: AsyncConnection.fetch_df_all See :ref:`dataframeformat` for the supported data types and examples. - .. note:: + .. versionchanged:: 3.4.0 - The data frame support in python-oracledb 3.0.0 is a pre-release and - may change in the next version. + The ``fetch_decimals`` and ``requested_schema`` parameters were added. .. versionadded:: 3.0.0 -.. method:: AsyncConnection.fetch_df_batches(statement, parameters=None, \ - size=None) - - This returns an iterator yielding the next ``size`` rows of the SQL query - ``statement`` in each iteration as an :ref:`OracleDataFrame - ` object. An empty OracleDataFrame is returned if there - are no rows available. - - The ``parameters`` parameter can be a list of tuples, where each tuple item - maps to one :ref:`bind variable placeholder ` in ``statement``. It - can also be a list of dictionaries, where the keys match the bind variable - placeholder names in ``statement``. - - The ``size`` parameter controls the number of records fetched in each - batch. It defaults to :attr:`defaults.arraysize`. Internally, the - ``fetch_df_batches()``'s :attr:`Cursor.arraysize` and - :attr:`Cursor.prefetchrows` sizes are always set to the value of the - explicit or default ``size`` parameter value. +.. automethod:: AsyncConnection.fetch_df_batches See :ref:`dataframeformat` for the supported data types and examples. - .. note:: + .. versionchanged:: 3.4.0 - The data frame support in python-oracledb 3.0.0 is a pre-release and - may change in the next version. + The ``fetch_decimals`` and ``requested_schema`` parameters were added. .. versionadded:: 3.0.0 -.. method:: AsyncConnection.fetchall(statement, parameters=None, \ - arraysize=None, rowfactory=None) - - Executes a query and returns all of the rows. - - The default value for ``arraysize`` is :attr:`defaults.arraysize`. +.. automethod:: AsyncConnection.fetchmany - Internally, this method's :attr:`Cursor.prefetchrows` size is set to the - value of the explicit or default ``arraysize`` parameter value. + .. versionchanged:: 3.4.0 - This is a shortcut for calling :meth:`AsyncConnection.cursor()`, - :meth:`AsyncCursor.fetchall()`, and then :meth:`AsyncCursor.close()`. + The ``fetch_lobs`` and ``fetch_decimals`` parameters were added. -.. method:: AsyncConnection.fetchmany(statement, parameters=None, \ - num_rows=None, rowfactory=None) +.. automethod:: AsyncConnection.fetchone - Executes a query and returns up to the specified number of rows. + .. versionchanged:: 3.4.0 - The default value for ``num_rows`` is the value of - :attr:`defaults.arraysize`. + The ``fetch_lobs`` and ``fetch_decimals`` parameters were added. - Internally, this method's :attr:`Cursor.prefetchrows` size is set to the - value of the explicit or default ``num_rows`` parameter, allowing all rows - to be fetched in one :ref:`round-trip ` +.. automethod:: AsyncConnection.gettype - Since only one fetch is performed for a query, consider adding a ``FETCH - NEXT`` clause to the statement to prevent the database processing rows that - will never be fetched, see :ref:`rowlimit`. +.. automethod:: AsyncConnection.is_healthy - This a shortcut for calling :meth:`AsyncConnection.cursor()`, - :meth:`AsyncCursor.fetchmany()`, and then :meth:`AsyncCursor.close()`. +.. automethod:: AsyncConnection.msgproperties -.. method:: AsyncConnection.fetchone(statement, parameters=None, \ - rowfactory=None) + .. versionadded:: 3.1.0 - Executes a query and returns the first row of the result set if one exists - (or *None* if no rows exist). +.. automethod:: AsyncConnection.ping() - Internally, this method's :attr:`Cursor.prefetchrows` and - :attr:`Cursor.arraysize` sizes will be set to *1*. +.. automethod:: AsyncConnection.queue - Since only one fetch is performed for a query, consider adding a ``WHERE`` - condition or using a ``FETCH NEXT`` clause in the statement to prevent the - database processing rows that will never be fetched, see :ref:`rowlimit`. + .. versionadded:: 3.1.0 - This a shortcut for calling :meth:`AsyncConnection.cursor()`, - :meth:`AsyncCursor.fetchone()`, and then :meth:`AsyncCursor.close()`. +.. automethod:: AsyncConnection.resume_sessionless_transaction -.. method:: AsyncConnection.gettype(name) + See :ref:`sessionlesstxns`. - Returns a :ref:`type object ` given its name. This can then - be used to create objects which can be bound to cursors created by this - connection. + .. versionadded:: 3.3.0 -.. method:: AsyncConnection.is_healthy() +.. automethod:: AsyncConnection.rollback - A synchronous method that returns a boolean indicating the health status - of a connection. - - Connections may become unusable in several cases, such as, if the network - socket is broken, if an Oracle error indicates the connection is unusable, - or after receiving a planned down notification from the database. - - This function is best used before starting a new database request on an - existing standalone connection. Pooled connections internally perform this - check before returning a connection to the application. - - If this function returns *False*, the connection should be not be used by - the application and a new connection should be established instead. - - This function performs a local check. To fully check a connection's health, - use :meth:`AsyncConnection.ping()` which performs a :ref:`round-trip - ` to the database. - -.. method:: AsyncConnection.ping() - - Pings the database to verify if the connection is valid. - -.. method:: AsyncConnection.rollback() - - Rolls back any pending transaction. - -.. method:: AsyncConnection.run_pipeline(pipeline, continue_on_error=False) - - Runs all of the operations in the :ref:`pipeline ` and returns - a list of :ref:`PipelineOpResult Objects `, each - entry corresponding to an operation executed in the pipeline. - - The ``continue_on_error`` parameter determines whether operations should - continue to run after an error has occurred. If this parameter is set to - *True*, then the :attr:`PipelineOpResult.error` attribute will be populated - with an :ref:`_Error ` instance which identifies the error - that occurred. If this parameter is set to *False*, then an exception will - be raised as soon as an error is detected and all subsequent operations - will be terminated. The default value is *False*. +.. automethod:: AsyncConnection.run_pipeline See :ref:`pipelining` for more information. .. note:: - True pipelining requires Oracle Database 23ai. + True pipelining requires Oracle Database version 23, or later. When you connect to an older database, operations are sequentially executed by python-oracledb. Each operation concludes before the next @@ -289,28 +169,13 @@ AsyncConnection Methods .. versionadded:: 2.4.0 -.. method:: AsyncConnection.tpc_begin(xid, flags, timeout) - - Begins a Two-Phase Commit (TPC) on a global transaction using the specified - transaction identifier (xid). +.. automethod:: AsyncConnection.suspend_sessionless_transaction - The ``xid`` parameter should be an object returned by the - :meth:`~Connection.xid()` method. + See :ref:`sessionlesstxns`. - The ``flags`` parameter is one of the constants - :data:`oracledb.TPC_BEGIN_JOIN`, :data:`oracledb.TPC_BEGIN_NEW`, - :data:`oracledb.TPC_BEGIN_PROMOTE`, or :data:`oracledb.TPC_BEGIN_RESUME`. - The default is :data:`oracledb.TPC_BEGIN_NEW`. + .. versionadded:: 3.3.0 - The ``timeout`` parameter is the number of seconds to wait for a - transaction to become available for resumption when - :data:`~oracledb.TPC_BEGIN_RESUME` is specified in the ``flags`` parameter. - When :data:`~oracledb.TPC_BEGIN_NEW` is specified in the ``flags`` - parameter, the ``timeout`` parameter indicates the number of seconds the - transaction can be inactive before it is automatically terminated by the - system. A transaction is inactive between the time it is detached with - :meth:`AsyncConnection.tpc_end()` and the time it is resumed with - :meth:`AsyncConnection.tpc_begin()`.The default is *0* seconds. +.. automethod:: AsyncConnection.tpc_begin The following code sample demonstrates the ``tpc_begin()`` function:: @@ -321,27 +186,7 @@ AsyncConnection Methods .. versionadded:: 2.3.0 -.. method:: AsyncConnection.tpc_commit(xid, one_phase) - - Commits a global transaction. When called with no arguments, this method - commits a transaction previously prepared with - :meth:`~AsyncConnection.tpc_begin()` and optionally prepared with - :meth:`~AsyncConnection.tpc_prepare()`. If - :meth:`~AsyncConnection.tpc_prepare()` is not called, a single phase commit - is performed. A transaction manager may choose to do this if only a single - resource is participating in the global transaction. - - If an ``xid`` parameter is passed, then an object should be returned by the - :meth:`~Connection.xid()` function. This form should be called outside of a - transaction and is intended for use in recovery. - - The ``one_phase`` parameter is a boolean identifying whether to perform a - one-phase or two-phase commit. If ``one_phase`` parameter is *True*, a - single-phase commit is performed. The default value is *False*. This - parameter is only examined if a value is provided for the ``xid`` - parameter. Otherwise, the driver already knows whether - :meth:`~AsyncConnection.tpc_prepare()` was called for the transaction and - whether a one-phase or two-phase commit is required. +.. automethod:: AsyncConnection.tpc_commit The following code sample demonstrates the ``tpc_commit()`` function:: @@ -352,23 +197,7 @@ AsyncConnection Methods .. versionadded:: 2.3.0 -.. method:: AsyncConnection.tpc_end(xid, flags) - - Ends or suspends work on a global transaction. This function is only - intended for use by transaction managers. - - If an ``xid`` parameter is passed, then an object should be returned by the - :meth:`~Connection.xid()` function. If no xid parameter is passed, then the - transaction identifier used by the previous :meth:`~Connection.tpc_begin()` - is used. - - The ``flags`` parameter is one of the constants - :data:`oracledb.TPC_END_NORMAL` or :data:`oracledb.TPC_END_SUSPEND`. The - default is :data:`oracledb.TPC_END_NORMAL`. - - If the flag is :data:`oracledb.TPC_END_SUSPEND` then the transaction may be - resumed later by calling :meth:`AsyncConnection.tpc_begin()` with the flag - :data:`oracledb.TPC_BEGIN_RESUME`. +.. automethod:: AsyncConnection.tpc_end The following code sample demonstrates the ``tpc_end()`` function:: @@ -379,13 +208,7 @@ AsyncConnection Methods .. versionadded:: 2.3.0 -.. method:: AsyncConnection.tpc_forget(xid) - - Causes the database to forget a heuristically completed TPC transaction. - This function is only intended to be called by transaction managers. - - The ``xid`` parameter is mandatory and should be an object should be - returned by the :meth:`~Connection.xid()` function. +.. automethod:: AsyncConnection.tpc_forget The following code sample demonstrates the ``tpc_forget()`` function:: @@ -396,21 +219,7 @@ AsyncConnection Methods .. versionadded:: 2.3.0 -.. method:: AsyncConnection.tpc_prepare(xid) - - Prepares a two-phase transaction for commit. After this function is called, - no further activity should take place on this connection until either - :meth:`~AsyncConnection.tpc_commit()` or - :meth:`~AsyncConnection.tpc_rollback()` have been called. - - Returns a boolean indicating whether a commit is needed or not. If you - attempt to commit when not needed, then it results in the error - ``ORA-24756: transaction does not exist``. - - If an ``xid`` parameter is passed, then an object should be returned by the - :meth:`~Connection.xid()` function. If an ``xid`` parameter is not passed, - then the transaction identifier used by the previous - :meth:`~AsyncConnection.tpc_begin()` is used. +.. automethod:: AsyncConnection.tpc_prepare The following code sample demonstrates the ``tpc_prepare()`` function:: @@ -421,16 +230,7 @@ AsyncConnection Methods .. versionadded:: 2.3.0 -.. method:: AsyncConnection.tpc_recover() - - Returns a list of pending transaction identifiers that require recovery. - Objects of type ``Xid`` (as returned by the :meth:`~Connection.xid()` - function) are returned and these can be passed to - :meth:`~AsyncConnection.tpc_commit()` or - :meth:`~AsyncConnection.tpc_rollback()` as needed. - - This function queries the view ``DBA_PENDING_TRANSACTIONS`` and requires - ``SELECT`` privilege on that view. +.. automethod:: AsyncConnection.tpc_recover The following code sample demonstrates the ``tpc_recover()`` function:: @@ -440,17 +240,7 @@ AsyncConnection Methods .. versionadded:: 2.3.0 -.. method:: AsyncConnection.tpc_rollback(xid) - - Rolls back a global transaction. - - If an ``xid`` parameter is not passed, then it rolls back the transaction - that was previously started with :meth:`~AsyncConnection.tpc_begin()`. - - If an ``xid`` parameter is passed, then an object should be returned by - :meth:`~Connection.xid()` and the specified transaction is rolled back. - This form should be called outside of a transaction and is intended for use - in recovery. +.. automethod:: AsyncConnection.tpc_rollback The following code sample demonstrates the ``tpc_rollback()`` function:: @@ -461,233 +251,79 @@ AsyncConnection Methods .. versionadded:: 2.3.0 +.. automethod:: AsyncConnection.xid + .. _asynconnattr: AsyncConnection Attributes ========================== -.. attribute:: AsyncConnection.action - - This write-only attribute sets the ACTION column in the V$SESSION view. It - is a string attribute but the value *None* is accepted and treated as an - empty string. - -.. attribute:: AsyncConnection.autocommit - - This read-write attribute determines whether autocommit mode is on or off. - When autocommit mode is on, all statements are committed as soon as they - have completed executing. - -.. attribute:: AsyncConnection.call_timeout - - This read-write attribute specifies the amount of time (in milliseconds) - that a single round-trip to the database may take before a timeout will - occur. A value of *0* means that no timeout will take place. - - If a timeout occurs, the error ``DPI-1067`` will be returned if the - connection is still usable. Alternatively, the error ``DPI-1080`` will be - returned if the connection has become invalid and can no longer be used. - -.. attribute:: AsyncConnection.client_identifier - - This write-only attribute sets the CLIENT_IDENTIFIER column in the - V$SESSION view. - -.. attribute:: AsyncConnection.clientinfo - - This write-only attribute sets the CLIENT_INFO column in the V$SESSION - view. - -.. attribute:: AsyncConnection.current_schema - - This read-write attribute sets the current schema attribute for the - session. Setting this value is the same as executing the SQL statement - ``ALTER SESSION SET CURRENT_SCHEMA``. The attribute is set (and verified) on - the next call that does a round trip to the server. The value is placed - before unqualified database objects in SQL statements you then execute. - -.. attribute:: AsyncConnection.db_domain - - This read-only attribute specifies the Oracle Database domain name - associated with the connection. It is the same value returned by the SQL - ``SELECT value FROM V$PARAMETER WHERE NAME = 'db_domain'``. - -.. attribute:: AsyncConnection.db_name - - This read-only attribute specifies the Oracle Database name associated with - the connection. It is the same value returned by the SQL - ``SELECT NAME FROM V$DATABASE``. - -.. attribute:: AsyncConnection.dbop - - This write-only attribute sets the database operation that is to be - monitored. This can be viewed in the DBOP_NAME column of the - V$SQL_MONITOR view. +.. autoproperty:: AsyncConnection.action -.. attribute:: AsyncConnection.dsn +.. autoproperty:: AsyncConnection.autocommit - This read-only attribute returns the TNS entry of the database to which a - connection has been established. +.. autoproperty:: AsyncConnection.call_timeout -.. attribute:: AsyncConnection.econtext_id +.. autoproperty:: AsyncConnection.client_identifier - This write-only attribute specifies the execution context id. This value - can be found as the ECID column in the V$SESSION view and ECONTEXT_ID in - the auditing tables. The maximum length is 64 bytes. +.. autoproperty:: AsyncConnection.clientinfo -.. attribute:: AsyncConnection.edition +.. autoproperty:: AsyncConnection.current_schema - This read-only attribute gets the session edition and is only available - with Oracle Database 11.2, or later. +.. autoproperty:: AsyncConnection.db_domain -.. attribute:: AsyncConnection.external_name +.. autoproperty:: AsyncConnection.db_name - This read-write attribute specifies the external name that is used by the - connection when logging distributed transactions. +.. autoproperty:: AsyncConnection.dbop -.. attribute:: AsyncConnection.inputtypehandler +.. autoproperty:: AsyncConnection.dsn - This read-write attribute specifies a method called for each value that is - bound to a statement executed on any cursor associated with this - connection. The method signature is handler(cursor, value, arraysize) and - the return value is expected to be a variable object or *None* in which - case a default variable object will be created. If this attribute is - *None*, the default behavior will take place for all values bound to - statements. +.. autoproperty:: AsyncConnection.econtext_id -.. attribute:: AsyncConnection.instance_name +.. autoproperty:: AsyncConnection.edition - This read-only attribute specifies the Oracle Database instance name - associated with the connection. It is the same value as the SQL expression - ``sys_context('userenv', 'instance_name')``. +.. autoproperty:: AsyncConnection.external_name -.. attribute:: AsyncConnection.internal_name +.. autoproperty:: AsyncConnection.inputtypehandler - This read-write attribute specifies the internal name that is used by the - connection when logging distributed transactions. +.. autoproperty:: AsyncConnection.instance_name -.. attribute:: AsyncConnection.ltxid +.. autoproperty:: AsyncConnection.internal_name - This read-only attribute returns the logical transaction id for the - connection. It is used within Oracle Transaction Guard as a means of - ensuring that transactions are not duplicated. See the Oracle documentation - and the provided sample for more information. +.. autoproperty:: AsyncConnection.ltxid - .. note: - - This attribute is only available with Oracle Database 12.1 or later. - -.. attribute:: AsyncConnection.max_identifier_length - - This read-only attribute specifies the maximum database identifier length - in bytes supported by the database to which the connection has been - established. See `Database Object Naming Rules - `__. +.. autoproperty:: AsyncConnection.max_identifier_length .. versionadded:: 2.5.0 -.. attribute:: AsyncConnection.max_open_cursors - - This read-only attribute specifies the maximum number of cursors that the - database can have open concurrently. It is the same value returned by the - SQL ``SELECT VALUE FROM V$PARAMETER WHERE NAME = 'open_cursors'``. - -.. attribute:: AsyncConnection.module - - This write-only attribute sets the MODULE column in the V$SESSION view. - The maximum length for this string is 48 and if you exceed this length you - will get ``ORA-24960``. +.. autoproperty:: AsyncConnection.max_open_cursors -.. attribute:: AsyncConnection.outputtypehandler +.. autoproperty:: AsyncConnection.module - This read-write attribute specifies a method called for each column that is - going to be fetched from any cursor associated with this connection. The - method signature is ``handler(cursor, metadata)`` and the return value is - expected to be a :ref:`variable object ` or *None* in which case a - default variable object will be created. If this attribute is *None*, the - default behavior will take place for all columns fetched from cursors. +.. autoproperty:: AsyncConnection.outputtypehandler See :ref:`outputtypehandlers`. -.. attribute:: AsyncConnection.sdu +.. autoproperty:: AsyncConnection.sdu - This read-only attribute specifies the size of the Session Data Unit (SDU) - that is being used by the connection. The value will be the lesser of the - requested python-oracledb size and the maximum size allowed by the database - network configuration. - -.. attribute:: AsyncConnection.serial_num - - This read-only attribute specifies the session serial number associated with - the connection. It is the same value returned by the SQL - ``SELECT SERIAL# FROM V$SESSION``. It is available only in python-oracledb - Thin mode. +.. autoproperty:: AsyncConnection.serial_num .. versionadded:: 2.5.0 - .. note:: - - This attribute is an extension to the DB API definition. - - For applications using :ref:`drcp`, the ``serial_num`` attribute may - not contain the current session state until a round-trip is made to the - database after acquiring a session. It is recommended to not use this - attribute if your application uses DRCP but may not perform a - round-trip. - -.. attribute:: AsyncConnection.service_name +.. autoproperty:: AsyncConnection.service_name - This read-only attribute specifies the Oracle Database service name - associated with the connection. This is the same value returned by the SQL - ``SELECT SYS_CONTEXT('USERENV', 'SERVICE_NAME') FROM DUAL``. - -.. attribute:: AsyncConnection.session_id - - This read-only attribute specifies the session identifier associated with - the connection. It is the same value returned by the SQL - ``SELECT SID FROM V$SESSION``. It is available only in python-oracledb - Thin mode. +.. autoproperty:: AsyncConnection.session_id .. versionadded:: 2.5.0 - .. note:: - - This attribute is an extension to the DB API definition. - - For applications using :ref:`drcp`, the ``session_id`` attribute may - not contain the current session state until a round-trip is made to the - database after acquiring a session. It is recommended to not use this - attribute if your application uses DRCP but may not perform a - round-trip. - -.. attribute:: AsyncConnection.stmtcachesize - - This read-write attribute specifies the size of the statement cache. This - value can make a significant difference in performance if you have a small - number of statements that you execute repeatedly. - - The default value is *20*. +.. autoproperty:: AsyncConnection.stmtcachesize See :ref:`Statement Caching ` for more information. -.. attribute:: AsyncConnection.thin - - This read-only attribute returns a boolean indicating if the connection was - established with the python-oracledb Thin mode (*True*) or python-oracledb - Thick mode (*False*). - -.. attribute:: AsyncConnection.transaction_in_progress - - This read-only attribute specifies whether a transaction is currently in - progress on the database associated with the connection. - -.. attribute:: AsyncConnection.username +.. autoproperty:: AsyncConnection.thin - This read-only attribute returns the name of the user which established the - connection to the database. +.. autoproperty:: AsyncConnection.transaction_in_progress -.. attribute:: AsyncConnection.version +.. autoproperty:: AsyncConnection.username - This read-only attribute returns the version of the database to which a - connection has been established. +.. autoproperty:: AsyncConnection.version diff --git a/doc/src/api_manual/async_connection_pool.rst b/doc/src/api_manual/async_connection_pool.rst index db819d1f..064dc14d 100644 --- a/doc/src/api_manual/async_connection_pool.rst +++ b/doc/src/api_manual/async_connection_pool.rst @@ -4,207 +4,86 @@ API: AsyncConnectionPool Objects ******************************** -An AsyncConnectionPool object can be created with -:meth:`oracledb.create_pool_async()`. This object is an extension to the DB -API. +.. currentmodule:: oracledb -.. versionadded:: 2.0.0 +AsyncConnectionPool Class +========================= -.. note:: +.. autoclass:: AsyncConnectionPool - AsyncConnectionPool objects are only supported in the python-oracledb Thin - mode. + An AsyncConnectionPool object should be created with + :meth:`oracledb.create_pool_async()`. -.. _asynconnpoolmeth: - -AsyncConnectionPool Methods -=========================== - -.. method:: AsyncConnectionPool.acquire(user=None, password=None, cclass=None, \ - purity=oracledb.PURITY_DEFAULT, tag=None, matchanytag=False, \ - shardingkey=[], supershardingkey=[]) - - Acquires a connection from the pool and returns an - :ref:`asynchronous connection object `. - - If the pool is :ref:`homogeneous `, the ``user`` and - ``password`` parameters cannot be specified. If they are, an exception will - be raised. - - The ``cclass`` parameter, if specified, should be a string corresponding to - the connection class for :ref:`drcp`. + .. dbapiobjectextension:: - The ``purity`` parameter is expected to be one of - :data:`~oracledb.PURITY_NEW`, :data:`~oracledb.PURITY_SELF`, or - :data:`~oracledb.PURITY_DEFAULT`. + .. versionadded:: 2.0.0 - The ``tag``, ``matchanytag``, ``shardingkey``, and ``supershardingkey`` - parameters are ignored in python-oracledb Thin mode. + .. note:: -.. method:: AsyncConnectionPool.close(force=False) + AsyncConnectionPool objects are only supported in python-oracledb Thin + mode. - Closes the pool now, rather than when the last reference to it is - released, which makes it unusable for further work. +.. _asynconnpoolmeth: - If any connections have been acquired and not released back to the pool, - this method will fail unless the ``force`` parameter is set to *True*. +AsyncConnectionPool Methods +=========================== -.. method:: AsyncConnectionPool.drop(connection) +.. automethod:: AsyncConnectionPool.acquire - Drops the connection from the pool which is useful if the connection is no - longer usable (such as when the session is killed). +.. automethod:: AsyncConnectionPool.close -.. method:: AsyncConnectionPool.release(connection, tag=None) +.. automethod:: AsyncConnectionPool.drop - Releases the connection back to the pool now, rather than whenever - ``__del__`` is called. The connection will be unusable from this point - forward; an Error exception will be raised if any operation is attempted - with the connection. Any cursors or LOBs created by the connection will - also be marked unusable and an Error exception will be raised if any - operation is attempted with them. +.. automethod:: AsyncConnectionPool.release - Internally, references to the connection are held by cursor objects, - LOB objects, and so on. Once all of these references are released, the - connection itself will be released back to the pool automatically. Either - control references to these related objects carefully or explicitly - release connections back to the pool in order to ensure sufficient - resources are available. + .. note:: - The ``tag`` parameter is ignored in python-oracledb Thin mode. + Asynchronous connections are not automatically closed at the end of + scope. This is different to synchronous connection + behavior. Asynchronous connections should either be explicitly + released, or have been initially created via a `context manager + `__ + ``with`` statement. .. _asyncconnpoolattr: AsyncConnectionPool Attributes ============================== -.. attribute:: AsyncConnectionPool.busy - - This read-only attribute returns the number of connections currently - acquired. - -.. attribute:: AsyncConnectionPool.dsn - - This read-only attribute returns the TNS entry of the database to which a - connection has been established. - -.. attribute:: AsyncConnectionPool.getmode +.. autoproperty:: AsyncConnectionPool.busy - This read-write attribute determines how connections are returned from the - pool. If :data:`~oracledb.POOL_GETMODE_FORCEGET` is specified, a new - connection will be returned even if there are no free connections in the - pool. :data:`~oracledb.POOL_GETMODE_NOWAIT` will raise an exception if - there are no free connections are available in the pool. If - :data:`~oracledb.POOL_GETMODE_WAIT` is specified and there are no free - connections in the pool, the caller will wait until a free connection is - available. :data:`~oracledb.POOL_GETMODE_TIMEDWAIT` uses the value of - :data:`~ConnectionPool.wait_timeout` to determine how long the caller - should wait for a connection to become available before returning an error. +.. autoproperty:: AsyncConnectionPool.dsn -.. attribute:: AsyncConnectionPool.homogeneous +.. autoproperty:: AsyncConnectionPool.getmode - This read-only boolean attribute indicates whether the pool is considered - :ref:`homogeneous ` or not. If the pool is not homogeneous, - different authentication can be used for each connection acquired from the - pool. +.. autoproperty:: AsyncConnectionPool.homogeneous -.. attribute:: AsyncConnectionPool.increment +.. autoproperty:: AsyncConnectionPool.increment - This read-only attribute returns the number of connections that will be - established when additional connections need to be created. +.. autoproperty:: AsyncConnectionPool.max -.. attribute:: AsyncConnectionPool.max +.. autoproperty:: AsyncConnectionPool.max_lifetime_session - This read-only attribute returns the maximum number of connections that the - pool can control. +.. autoproperty:: AsyncConnectionPool.max_sessions_per_shard -.. attribute:: AsyncConnectionPool.max_lifetime_session +.. autoproperty:: AsyncConnectionPool.min - This read-write attribute is the maximum length of time (in seconds) that a - pooled connection may exist since first being created. A value of *0* means - there is no limit. Connections become candidates for termination when they - are acquired or released back to the pool, and have existed for longer than - ``max_lifetime_session`` seconds. Connections that are in active use will - not be closed. In python-oracledb Thick mode, Oracle Client libraries 12.1 - or later must be used and, prior to Oracle Client 21, cleanup only occurs - when the pool is accessed. +.. autoproperty:: AsyncConnectionPool.name -.. attribute:: AsyncConnectionPool.max_sessions_per_shard +.. autoproperty:: AsyncConnectionPool.opened - This read-write attribute returns the number of sessions that can be - created per shard in the pool. This attribute cannot be used in - python-oracledb Thin mode. +.. autoproperty:: AsyncConnectionPool.ping_interval -.. attribute:: AsyncConnectionPool.min +.. autoproperty:: AsyncConnectionPool.soda_metadata_cache - This read-only attribute returns the number of connections with which the - connection pool was created and the minimum number of connections that will - be controlled by the connection pool. - -.. attribute:: AsyncConnectionPool.name - - This read-only attribute returns the name assigned to the pool by Oracle. - -.. attribute:: AsyncConnectionPool.opened - - This read-only attribute returns the number of connections currently opened - by the pool. - -.. attribute:: AsyncConnectionPool.ping_interval - - This read-write integer attribute specifies the pool ping interval in - seconds. When a connection is acquired from the pool, a check is first made - to see how long it has been since the connection was put into the pool. If - this idle time exceeds ``ping_interval``, then a :ref:`round-trip - ` ping to the database is performed. If the connection is - unusable, it is discarded and a different connection is selected to be - returned by :meth:`AsyncConnectionPool.acquire()`. Setting - ``ping_interval`` to a negative value disables pinging. Setting it to *0* - forces a ping for every :meth:`AsyncConnectionPool.acquire()` and is not - recommended. - - Prior to cx_Oracle 8.2, the ping interval was fixed at *60* seconds. - -.. attribute:: AsyncConnectionPool.soda_metadata_cache - - This read-write boolean attribute returns whether the SODA metadata cache - is enabled or not. This attribute cannot be used in python-oracledb Thin - mode. - -.. attribute:: AsyncConnectionPool.stmtcachesize - - This read-write attribute specifies the size of the statement cache that - will be used for connections obtained from the pool. Once a connection is - created, that connection’s statement cache size can only be changed by - setting the ``stmtcachesize`` attribute on the connection itself. +.. autoproperty:: AsyncConnectionPool.stmtcachesize See :ref:`Statement Caching ` for more information. -.. attribute:: AsyncConnectionPool.thin - - This attribute returns a boolean which indicates the python-oracledb mode - in which the pool was created. If the value of this attribute is *True*, it - indicates that the pool was created in the python-oracledb Thin mode. If - the value of this attribute is *False*, it indicates that the pool was - created in the python-oracledb Thick mode. - -.. attribute:: AsyncConnectionPool.timeout - - This read-only attribute is an integer that specifies the length of time - (in seconds) that a connection may remain idle in the pool before it is - terminated. This applies only when the pool has more than ``min`` - connections open, allowing it to shrink to the specified minimum size. The - default value is *0* seconds. A value of *0* means that there is no maximum - time. - -.. attribute:: AsyncConnectionPool.username +.. autoproperty:: AsyncConnectionPool.thin - This read-only attribute returns the name of the user which established the - connection to the database. +.. autoproperty:: AsyncConnectionPool.timeout -.. attribute:: AsyncConnectionPool.wait_timeout +.. autoproperty:: AsyncConnectionPool.username - This read-write attribute specifies the time (in milliseconds) that the - caller should wait for a connection to become available in the pool before - returning with an error. This value is only used if the ``getmode`` - parameter to :meth:`oracledb.create_pool_async()` was the value - :data:`oracledb.POOL_GETMODE_TIMEDWAIT`. +.. autoproperty:: AsyncConnectionPool.wait_timeout diff --git a/doc/src/api_manual/async_cursor.rst b/doc/src/api_manual/async_cursor.rst index 6733bcd6..88bb2415 100644 --- a/doc/src/api_manual/async_cursor.rst +++ b/doc/src/api_manual/async_cursor.rst @@ -4,317 +4,119 @@ API: AsyncCursor Objects ************************ -An AsyncCursor object can be created with :meth:`AsyncConnection.cursor()`. -Unless explicitly noted as synchronous, the AsyncCursor methods should be used -with ``await``. This object is an extension to the DB API. +.. currentmodule:: oracledb -.. versionadded:: 2.0.0 +AsyncCursor Class +================= -.. note:: +.. autoclass:: AsyncCursor - AsyncCursor objects are only supported in the python-oracledb Thin mode. + An AsyncCursor object should be created with + :meth:`AsyncConnection.cursor()`. + + .. dbapiobjectextension:: + + .. versionadded:: 2.0.0 + + .. note:: + + AsyncCursor objects are only supported in python-oracledb Thin mode. .. _asynccursormeth: AsyncCursor Methods =================== -.. method:: AsyncCursor.__aiter__() +.. automethod:: AsyncCursor.__aiter__ - Returns the cursor itself to be used as an asynchronous iterator. +.. automethod:: AsyncCursor.__aenter__ -.. method:: AsyncCursor.__enter__() +.. automethod:: AsyncCursor.__aexit__ - The entry point for the cursor as a context manager. It returns itself. +.. automethod:: AsyncCursor.arrayvar -.. method:: AsyncCursor.__exit__() +.. automethod:: AsyncCursor.bindnames - The exit point for the cursor as a context manager. It closes the cursor. +.. automethod:: AsyncCursor.callfunc -.. method:: AsyncCursor.arrayvar(typ, value, [size]) - - A synchronous method that creates an array variable associated with the - cursor of the given type and size and returns a - :ref:`variable object `. The value is either an integer specifying - the number of elements to allocate or it is a list and the number of - elements allocated is drawn from the size of the list. If the value is a - list, the variable is also set with the contents of the list. If the size - is not specified and the type is a string or binary, 4000 bytes is - allocated. This is needed for passing arrays to PL/SQL (in cases where - the list might be empty and the type cannot be determined automatically) or - returning arrays from PL/SQL. - - Array variables can only be used for PL/SQL associative arrays with - contiguous keys. For PL/SQL associative arrays with sparsely populated keys - or for varrays and nested tables, the approach shown in this - `example `__ needs to be used. + See :ref:`plsqlfunc` for examples. -.. method:: AsyncCursor.bindnames() + .. note:: - A synchronous method that returns the list of bind variable names bound to - the statement. Note that a statement must have been prepared first. + In line with the Python DB API, it is not recommended to call + :meth:`setinputsizes()` prior to calling this function. + Use :meth:`AsyncCursor.var()` instead. In existing code that calls + :meth:`~AsyncCursor.setinputsizes()`, the first item in the + :meth:`~AsyncCursor.setinputsizes()` parameter list refers to the + return value of the PL/SQL function. -.. method:: AsyncCursor.callfunc(name, return_type, parameters=None, \ - keyword_parameters=None) +.. automethod:: AsyncCursor.callproc - Calls a PL/SQL function with the given name and returns its value. + See :ref:`plsqlproc` for an example. - The ``return_type`` parameter for :meth:`~AsyncCursor.callfunc()` is - expected to be a Python type, one of the :ref:`oracledb types ` or - an :ref:`Object Type `. +.. automethod:: AsyncCursor.close - The sequence of parameters must contain one entry for each parameter that - the PL/SQL function expects. Any keyword parameters will be included after - the positional parameters. + .. note:: - Use :meth:`AsyncCursor.var()` to define any OUT or IN OUT parameters, if - necessary. + Asynchronous cursors are not automatically closed at the end of + scope. This is different to synchronous cursor behavior. Asynchronous + cursors should either be explicitly closed, or have been initially + created via a `context manager + `__ + ``with`` block. - See :ref:`plsqlfunc` for examples. +.. automethod:: AsyncCursor.execute - .. note:: + .. versionchanged:: 3.4.0 - In line with the Python DB API, it is not recommended to call - :meth:`AsyncCursor.setinputsizes()` prior to calling - :meth:`~AsyncCursor.callfunc()`. Use :meth:`AsyncCursor.var()` instead. - In existing code that calls :meth:`~AsyncCursor.setinputsizes()`, the - first item in the :meth:`~AsyncCursor.setinputsizes()` parameter list - refers to the return value of the PL/SQL function. + The ``fetch_lobs`` and ``fetch_decimals`` parameters were added. -.. method:: AsyncCursor.callproc(name, parameters=None, keyword_parameters=None) + .. versionchanged:: 3.3.0 - Calls a PL/SQL procedure with the given name. + The ``suspend_on_success`` parameter was added. - The sequence of parameters must contain one entry for each parameter that - the procedure expects. The result of the call is a modified copy of the - input sequence. Input parameters are left untouched; output and - input/output parameters are replaced with possibly new values. Keyword - parameters will be included after the positional parameters and are not - returned as part of the output sequence. +.. automethod:: AsyncCursor.executemany - Use :meth:`AsyncCursor.var()` to define any OUT or IN OUT parameters if - necessary. + .. versionchanged:: 3.4.0 - No query result set is returned by :meth:`~AsyncCursor.callproc()`. - Instead, use :ref:`REF CURSOR ` parameters or :ref:`Implicit - Results `. + The ``batch_size`` parameter was added. - See :ref:`plsqlproc` for an example. + .. versionchanged:: 3.3.0 -.. method:: AsyncCursor.close() - - A synchronous method that closes the cursor now, rather than whenever - ``__del__`` is called. The cursor will be unusable from this point - forward; an Error exception will be raised if any operation is attempted - with the cursor. - -.. method:: AsyncCursor.execute(statement, parameters=None, ** keyword_parameters) - - Executes a statement against the database. See :ref:`sqlexecution`. - - Parameters may be passed as a dictionary or sequence or as keyword - parameters. If the parameters are a dictionary, the values will be bound by - name and if the parameters are a sequence the values will be bound by - position. Note that if the values are bound by position, the order of the - variables is from left to right as they are encountered in the statement - and SQL statements are processed differently than PL/SQL statements. For - this reason, it is generally recommended to bind parameters by name instead - of by position. - - Parameters passed as a dictionary are name and value pairs. The name maps - to the bind variable name used by the statement and the value maps to the - Python value you wish bound to that bind variable. - - A reference to the statement will be retained by the cursor. If *None* or - the same string object is passed in again, the cursor will execute that - statement again without performing a prepare or rebinding and redefining. - This is most effective for algorithms where the same statement is used, but - different parameters are bound to it (many times). Note that parameters - that are not passed in during subsequent executions will retain the value - passed in during the last execution that contained them. - - For maximum efficiency when reusing a statement, it is best to use the - :meth:`AsyncCursor.setinputsizes()` method to specify the parameter types and - sizes ahead of time; in particular, *None* is assumed to be a string of - length 1 so any values that are later bound as numbers or dates will raise - a TypeError exception. - - If the statement is a query, the cursor is returned as a convenience to the - caller (so it can be used directly as an iterator over the rows in the - cursor); otherwise, *None* is returned. - -.. method:: AsyncCursor.executemany(statement, parameters, batcherrors=False, \ - arraydmlrowcounts=False) - - Executes a SQL statement once using all bind value mappings or sequences - found in the sequence parameters. This can be used to insert, update, or - delete multiple rows in a table with a single python-oracledb call. It can - also invoke a PL/SQL procedure multiple times. See :ref:`batchstmnt`. - - The ``statement`` parameter is managed in the same way as the - :meth:`AsyncCursor.execute()` method manages it. - - The ``parameters`` parameter can be a list of tuples, where each tuple item - maps to one bind variable placeholder in ``statement``. It can also be a - list of dictionaries, where the keys match the bind variable placeholder - names in ``statement``. If there are no bind values, or values have - previously been bound, the ``parameters`` value can be an integer - specifying the number of iterations. - - In python-oracledb Thick mode, if the size of the buffers allocated for any - of the parameters exceeds 2 GB, you will receive the error ``DPI-1015: - array size of is too large``. If you receive this error, decrease the - number of rows being inserted. - - When True, the ``batcherrors`` parameter enables batch error support within - Oracle and ensures that the call succeeds even if an exception takes place - in one or more of the sequence of parameters. The errors can then be - retrieved using :meth:`AsyncCursor.getbatcherrors()`. - - When True, the ``arraydmlrowcounts`` parameter enables DML row counts to be - retrieved from Oracle after the method has completed. The row counts can - then be retrieved using :meth:`AsyncCursor.getarraydmlrowcounts()`. - - Both the ``batcherrors`` parameter and the ``arraydmlrowcounts`` parameter - can only be True when executing an insert, update, delete, or merge - statement. In all other cases, an error will be raised. - - For maximum efficiency, it is best to use the - :meth:`AsyncCursor.setinputsizes()` method to specify the parameter types - and sizes ahead of time. In particular, the value *None* is assumed to be a - string of length 1 so any values that are later bound as numbers or dates - will raise a TypeError exception. - -.. method:: AsyncCursor.fetchall() - - Fetches all (remaining) rows of a query result, returning them as a list of - tuples. An empty list is returned if no more rows are available. Note that - the cursor's ``arraysize`` attribute can affect the performance of this - operation, as internally reads from the database are done in batches - corresponding to ``arraysize``. - - An exception is raised if the previous call to - :meth:`AsyncCursor.execute()` did not produce any result set or no call - was issued yet. - -.. method:: AsyncCursor.fetchmany(size=cursor.arraysize) - - Fetches the next set of rows of a query result, returning a list of tuples. - An empty list is returned if no more rows are available. Note that the - cursor's arraysize attribute can affect the performance of this operation. - - The number of rows to fetch is specified by the parameter. If it is not - given, the cursor's arraysize attribute determines the number of rows to be - fetched. If the number of rows available to be fetched is fewer than the - amount requested, fewer rows will be returned. - - An exception is raised if the previous call to - :meth:`AsyncCursor.execute()` did not produce any result set or no call - was issued yet. - -.. method:: AsyncCursor.fetchone() - - Fetches the next row of a query result set, returning a single tuple or - *None* when no more data is available. - - An exception is raised if the previous call to - :meth:`AsyncCursor.execute()` did not produce any result set or no call - was issued yet. - -.. method:: AsyncCursor.getarraydmlrowcounts() - - A synchronous method that retrieves the DML row counts after a call to - :meth:`AsyncCursor.executemany()` with ``arraydmlrowcounts`` enabled. This - will return a list of integers corresponding to the number of rows - affected by the DML statement for each element of the array passed to - :meth:`AsyncCursor.executemany()`. + Added support for passing data frames in the ``parameters`` parameter. + The ``suspend_on_success`` parameter was added. - .. note:: +.. automethod:: AsyncCursor.fetchall - This method is only available for Oracle 12.1 and later. +.. automethod:: AsyncCursor.fetchmany -.. method:: AsyncCursor.getbatcherrors() +.. automethod:: AsyncCursor.fetchone - A synchronous method that retrieves the exceptions that took place after a - call to :meth:`AsyncCursor.executemany()` with ``batcherrors`` enabled. - This will return a list of Error objects, one error for each iteration that - failed. The offset can be determined by looking at the offset attribute of - the error object. +.. automethod:: AsyncCursor.getarraydmlrowcounts -.. method:: AsyncCursor.getimplicitresults() +.. automethod:: AsyncCursor.getbatcherrors - A synchronous method that returns a list of cursors which correspond to - implicit results made available from a PL/SQL block or procedure without - the use of OUT ref cursor parameters. The PL/SQL block or procedure opens - the cursors and marks them for return to the driver using the procedure - dbms_sql.return_result. Cursors returned in this fashion should not be - closed. They will be closed automatically by the parent cursor when it is - closed. Closing the parent cursor will invalidate the cursors returned by - this method. +.. automethod:: AsyncCursor.getimplicitresults .. note:: - This method is only available with Oracle Database 12.1 or later. It is - most like the DB API method nextset(), but unlike that method (which - requires that the next result set overwrite the current result set), - this method returns cursors which can be fetched independently of each - other. - -.. method:: AsyncCursor.parse(statement) + It is most like the DB API method nextset(), but unlike that method + (which requires that the next result set overwrite the current result + set), this method returns cursors which can be fetched independently of + each other. - This can be used to parse a statement without actually executing it - (parsing step is done automatically by Oracle when a statement is - :meth:`executed `). +.. automethod:: AsyncCursor.parse .. note:: You can parse any DML or DDL statement. DDL statements are executed immediately and an implied commit takes place. -.. method:: AsyncCursor.prepare(statement, tag, cache_statement=True) - - A synchronous method that can be used before a call to - :meth:`AsyncCursor.execute()` to define the statement that will be - executed. When this is done, the prepare phase will not be performed when - the call to :meth:`AsyncCursor.execute()` is made with *None* or the same - string object as the statement. - - If the ``tag`` parameter is specified and the ``cache_statement`` parameter - is *True*, the statement will be returned to the statement cache with the - given tag. - - If the ``cache_statement`` parameter is *False*, the statement will be - removed from the statement cache (if it was found there) or will simply not - be cached. +.. automethod:: AsyncCursor.prepare See :ref:`Statement Caching ` for more information. -.. method:: AsyncCursor.setinputsizes(*args, **keywordArgs) - - A synchronous method that can be used before a call to - :meth:`AsyncCursor.execute()` and :meth:`AsyncCursor.executemany()` to - predefine memory areas for the operation's parameters. Each parameter - should be a type object corresponding to the data that will be used for a - :ref:`bind variable placeholder ` in the SQL or PL/SQL statement. - Alternatively, it can be an integer specifying the maximum length of a - string bind variable value. - - Use keyword parameters when :ref:`binding by name `. Use - positional parameters when :ref:`binding by position `. The - parameter value can be *None* to indicate that python-oracledb should - determine the required space from the data value provided. - - The parameters or keyword names correspond to the bind variable - placeholders used in the SQL or PL/SQL statement. Note this means that for - use with :meth:`AsyncCursor.executemany()` it does not correspond to the - number of bind value mappings or sequences being passed. - - When repeated calls to :meth:`AsyncCursor.execute()` or - :meth:`AsyncCursor.executemany()` are made binding different string data - lengths, using :meth:`~AsyncCursor.setinputsizes()` can help reduce the - database's SQL "version count" for the statement. See :ref:`Reducing the - SQL Version Count `. +.. automethod:: AsyncCursor.setinputsizes .. note:: @@ -326,201 +128,45 @@ AsyncCursor Methods :meth:`AsyncCursor.callfunc()`, the first parameter in the list refers to the return value of the PL/SQL function. -.. method:: AsyncCursor.setoutputsize(size, [column]) - - This method does nothing and is retained solely for compatibility with the - DB API. Python-oracledb automatically allocates as much space as needed to - fetch LONG and LONG RAW columns, and also to fetch CLOB as string and BLOB - as bytes. - -.. method:: AsyncCursor.var(typ, [size, arraysize, inconverter, outconverter, \ - typename, encoding_errors, bypass_decode, convert_nulls]) - - A synchronous method that creates a :ref:`variable object ` with - the specified characteristics. This method can be used for binding to - PL/SQL IN and OUT parameters where the length or type cannot be determined - automatically from the Python variable being bound. It can also be used in - :ref:`input ` and :ref:`output ` - type handlers. - - The ``typ`` parameter specifies the type of data that should be stored in the - variable. This should be one of the :ref:`database type constants - `, :ref:`DB API constants `, an object type returned from - the method :meth:`AsyncConnection.gettype()` or one of the following Python - types: - - .. list-table-with-summary:: - :header-rows: 1 - :class: wy-table-responsive - :align: center - :summary: The first column is the Python Type. The second column is the corresponding Database Type. - - * - Python Type - - Database Type - * - bool - - :attr:`oracledb.DB_TYPE_BOOLEAN` - * - bytes - - :attr:`oracledb.DB_TYPE_RAW` - * - datetime.date - - :attr:`oracledb.DB_TYPE_DATE` - * - datetime.datetime - - :attr:`oracledb.DB_TYPE_DATE` - * - datetime.timedelta - - :attr:`oracledb.DB_TYPE_INTERVAL_DS` - * - decimal.Decimal - - :attr:`oracledb.DB_TYPE_NUMBER` - * - float - - :attr:`oracledb.DB_TYPE_NUMBER` - * - int - - :attr:`oracledb.DB_TYPE_NUMBER` - * - str - - :attr:`oracledb.DB_TYPE_VARCHAR` - - The ``size`` parameter specifies the length of string and raw variables and is - ignored in all other cases. If not specified for string and raw variables, - the value *4000* is used. - - The ``arraysize`` parameter specifies the number of elements the variable will - have. If not specified the bind array size (usually *1*) is used. When a - variable is created in an output type handler this parameter should be set - to the cursor's array size. - - The ``inconverter`` and ``outconverter`` parameters specify methods used for - converting values to/from the database. More information can be found in - the section on :ref:`variable objects`. - - The ``typename`` parameter specifies the name of a SQL object type and must be - specified when using type :data:`oracledb.OBJECT` unless the type object - was passed directly as the first parameter. - - The ``encoding_errors`` parameter specifies what should happen when decoding - byte strings fetched from the database into strings. It should be one of - the values noted in the builtin - `decode `__ - function. - - The ``bypass_decode`` parameter, if specified, should be passed as a - boolean value. Passing a `True` value causes values of database types - :data:`~oracledb.DB_TYPE_VARCHAR`, :data:`~oracledb.DB_TYPE_CHAR`, - :data:`~oracledb.DB_TYPE_NVARCHAR`, :data:`~oracledb.DB_TYPE_NCHAR` and - :data:`~oracledb.DB_TYPE_LONG` to be returned as `bytes` instead of `str`, - meaning that python-oracledb does not do any decoding. See :ref:`Fetching raw - data ` for more information. - - The ``convert_nulls`` parameter, if specified, should be passed as a boolean - value. Passing the value *True* causes the ``outconverter`` to be called - when a null value is fetched from the database; otherwise, the - ``outconverter`` is only called when non-null values are fetched from the - database. +.. automethod:: AsyncCursor.scroll + +.. automethod:: AsyncCursor.setoutputsize + +.. automethod:: AsyncCursor.var .. _asynccursorattr: AsyncCursor Attributes ====================== -.. attribute:: AsyncCursor.arraysize - - This read-write attribute can be used to tune the number of rows internally - fetched and buffered by internal calls to the database when fetching rows - from SELECT statements and REF CURSORS. The value can drastically affect - the performance of a query since it directly affects the number of network - round trips between Python and the database. For methods like - :meth:`AsyncCursor.fetchone()` and :meth:`AsyncCursor.fetchall()` it - does not change how many rows are returned to the application. For - :meth:`AsyncCursor.fetchmany()` it is the default number of rows to fetch. - - The attribute is only used for tuning row and SODA document fetches from - the database. It does not affect data inserts. - - Due to the performance benefits, the default ``Cursor.arraysize`` is *100* - instead of the *1* that the Python DB API recommends. +.. autoproperty:: AsyncCursor.arraysize See :ref:`Tuning Fetch Performance ` for more information. -.. attribute:: AsyncCursor.bindvars +.. autoproperty:: AsyncCursor.bindvars - This read-only attribute provides the bind variables used for the last - execute. The value will be either a list or a dictionary depending on - whether binding was done by position or name. Care should be taken when - referencing this attribute. In particular, elements should not be removed - or replaced. +.. autoproperty:: AsyncCursor.connection -.. attribute:: AsyncCursor.description +.. autoproperty:: AsyncCursor.description - This read-only attribute is a sequence of :ref:`FetchInfo` - objects. This attribute will be *None* for operations that do not return - rows or if the cursor has not had an operation invoked via the - :meth:`AsyncCursor.execute()` method yet. +.. autoproperty:: AsyncCursor.fetchvars -.. attribute:: AsyncCursor.fetchvars +.. autoproperty:: AsyncCursor.inputtypehandler - This read-only attribute specifies the list of variables created for the - last query that was executed on the cursor. Care should be taken when - referencing this attribute. In particular, elements should not be removed - or replaced. +.. autoproperty:: AsyncCursor.lastrowid -.. attribute:: AsyncCursor.inputtypehandler - - This read-write attribute specifies a method called for each value that is - bound to a statement executed on the cursor and overrides the attribute - with the same name on the connection if specified. The method signature is - handler(cursor, value, arraysize) and the return value is expected to be a - variable object or *None* in which case a default variable object will be - created. If this attribute is *None*, the default behavior will take place - for all values bound to the statements. - -.. attribute:: AsyncCursor.lastrowid - - This read-only attribute returns the rowid of the last row modified by the - cursor. If no row was modified by the last operation performed on the - cursor, the value *None* is returned. - -.. attribute:: AsyncCursor.outputtypehandler - - This read-write attribute specifies a method called for each column that is - to be fetched from this cursor. The method signature is - handler(cursor, metadata) and the return value is expected to be a - :ref:`variable object` or *None* in which case a default variable - object will be created. If this attribute is *None*, then the default - behavior will take place for all columns fetched from this cursor. +.. autoproperty:: AsyncCursor.outputtypehandler See :ref:`outputtypehandlers`. -.. attribute:: AsyncCursor.prefetchrows - - This read-write attribute can be used to tune the number of rows that the - python-oracledb fetches when a SELECT statement is executed. This value can - reduce the number of round-trips to the database that are required to fetch - rows but at the cost of additional memory. Setting this value to *0* can be - useful when the timing of fetches must be explicitly controlled. - - The attribute is only used for tuning row fetches from the database. It - does not affect data inserts. +.. autoproperty:: AsyncCursor.prefetchrows See :ref:`Tuning Fetch Performance ` for more information. -.. attribute:: AsyncCursor.rowcount - - This read-only attribute specifies the number of rows that have currently - been fetched from the cursor (for select statements) or that have been - affected by the operation (for insert, update, delete and merge - statements). For all other statements the value is always *0*. If the - cursor or connection is closed, the value returned is *-1*. +.. autoproperty:: AsyncCursor.rowcount -.. attribute:: AsyncCursor.rowfactory - - This read-write attribute specifies a method to call for each row that is - retrieved from the database. Ordinarily, a tuple is returned for each row - but if this attribute is set, the method is called with the tuple that - would normally be returned, and the result of the method is returned - instead. +.. autoproperty:: AsyncCursor.rowfactory See :ref:`rowfactories`. -.. attribute:: AsyncCursor.scrollable - - This read-write boolean attribute specifies whether the cursor can be - scrolled or not. By default, cursors are not scrollable, as the server - resources and response times are greater than nonscrollable cursors. This - attribute is checked and the corresponding mode set in Oracle when calling - the method :meth:`AsyncCursor.execute()`. +.. autoproperty:: AsyncCursor.scrollable diff --git a/doc/src/api_manual/async_lob.rst b/doc/src/api_manual/async_lob.rst index 05b7b736..983cf879 100644 --- a/doc/src/api_manual/async_lob.rst +++ b/doc/src/api_manual/async_lob.rst @@ -4,94 +4,57 @@ API: AsyncLOB Objects ********************* -An AsyncLOB object can be created with :meth:`AsyncConnection.createlob()`. -Also, this object is returned whenever Oracle :data:`CLOB`, :data:`BLOB` and -:data:`BFILE` columns are fetched. This object is an extension to the DB API. +.. currentmodule:: oracledb -See :ref:`lobdata` for more information about using LOBs. +AsyncLOB Class +============== -.. note:: +.. autoclass:: AsyncLOB - AsyncLOB objects are only supported in the python-oracledb Thin mode. + An AsyncLOB object can be created with + :meth:`AsyncConnection.createlob()`. Also, this object is returned whenever + Oracle :data:`CLOB`, :data:`BLOB` and :data:`BFILE` columns are fetched. -.. _asynclobmeth: - -AsyncLOB Methods -================ - -.. method:: AsyncLOB.close() - - Closes the LOB. Call this when writing is completed so that the indexes - associated with the LOB can be updated -- but only if :meth:`~AsyncLOB.open()` - was called first. - -.. method:: AsyncLOB.fileexists() + .. dbapiobjectextension:: - Returns a boolean indicating if the file referenced by the BFILE type LOB - exists. + See :ref:`lobdata` for more information about using LOBs. -.. method:: AsyncLOB.getchunksize() + .. note:: - Returns the chunk size for the internal LOB. Reading and writing to the LOB - in chunks of multiples of this size will improve performance. + AsyncLOB objects are only supported in python-oracledb Thin mode. -.. method:: AsyncLOB.getfilename() - - Returns a two-tuple consisting of the directory alias and file name for a - BFILE type LOB. - -.. method:: AsyncLOB.isopen() - - Returns a boolean indicating if the LOB has been opened using the method - :meth:`~AsyncLOB.open()`. +.. _asynclobmeth: -.. method:: AsyncLOB.open() +AsyncLOB Methods +================ - Opens the LOB for writing. This will improve performance when writing to a - LOB in chunks and there are functional or extensible indexes associated - with the LOB. If this method is not called, each write will perform an open - internally followed by a close after the write has been completed. +.. automethod:: AsyncLOB.close -.. method:: AsyncLOB.read([offset=1, [amount]]) +.. automethod:: AsyncLOB.fileexists - Returns a portion (or all) of the data in the LOB object. Note that the - amount and offset are in bytes for BLOB and BFILE type LOBs and in UCS-2 - code points for CLOB and NCLOB type LOBs. UCS-2 code points are equivalent - to characters for all but supplemental characters. If supplemental - characters are in the LOB, the offset and amount will have to be chosen - carefully to avoid splitting a character. +.. automethod:: AsyncLOB.getchunksize -.. method:: AsyncLOB.setfilename(dir_alias, name) +.. automethod:: AsyncLOB.getfilename - Sets the directory alias and name of the BFILE type LOB. +.. automethod:: AsyncLOB.isopen -.. method:: AsyncLOB.size() +.. automethod:: AsyncLOB.open - Returns the size of the data in the LOB object. For BLOB and BFILE type - LOBs, this is the number of bytes. For CLOB and NCLOB type LOBs, this is the - number of UCS-2 code points. UCS-2 code points are equivalent to characters - for all but supplemental characters. +.. automethod:: AsyncLOB.read -.. method:: AsyncLOB.trim(new_size=0) +.. automethod:: AsyncLOB.setfilename - Trims the LOB to the new size. +.. automethod:: AsyncLOB.size -.. method:: AsyncLOB.write(data, offset=1) +.. automethod:: AsyncLOB.trim - Writes the data to the LOB object at the given offset. The offset is in - bytes for BLOB type LOBs and in UCS-2 code points for CLOB and NCLOB type - LOBs. UCS-2 code points are equivalent to characters for all but - supplemental characters. If supplemental characters are in the LOB, the - offset will have to be chosen carefully to avoid splitting a character. - Note that if you want to make the LOB value smaller, you must use the - :meth:`~AsyncLOB.trim()` function. +.. automethod:: AsyncLOB.write .. _asynclobattr: AsyncLOB Attributes =================== -.. attribute:: AsyncLOB.type +.. autoproperty:: AsyncLOB.type - This read-only attribute returns the type of the LOB as one of the - :ref:`database type constants `. + See :ref:`database type constants `. diff --git a/doc/src/api_manual/connect_params.rst b/doc/src/api_manual/connect_params.rst index 6e51f1a8..6d58b339 100644 --- a/doc/src/api_manual/connect_params.rst +++ b/doc/src/api_manual/connect_params.rst @@ -4,70 +4,74 @@ API: ConnectParams Objects ************************** -.. note:: +.. currentmodule:: oracledb - This object is an extension to the DB API. +ConnectParams Class +=================== -These objects are created by :meth:`oracledb.ConnectParams()`. See -:ref:`usingconnparams` for more information. +.. autoclass:: ConnectParams -.. _connparamsmeth: + See :ref:`usingconnparams` for more information. -ConnectParams Methods -===================== + .. dbapiobjectextension:: + + .. versionchanged:: 3.2.0 + + The ``pool_name`` parameter was added. + + .. versionchanged:: 3.0.0 -.. method:: ConnectParams.copy() + The ``instance_name``, ``use_sni``, ``thick_mode_dsn_passthrough`` and + ``extra_auth_params`` parameters were added. - Creates a copy of the ConnectParams instance and returns it. + .. versionchanged:: 2.5.0 -.. method:: ConnectParams.get_connect_string() + The ``program``, ``machine``, ``terminal``, ``osuser``, and + ``driver_name`` parameters were added. Support for ``edition`` and + ``appcontext`` was added to python-oracledb Thin mode. - Returns the connection string associated with the ConnectParams instance. + .. versionchanged:: 2.3.0 -.. method:: ConnectParams.get_network_service_names() + The default value of the ``retry_delay`` parameter was changed from 0 + seconds to 1 second. The default value of the ``tcp_connect_timeout`` + parameter was changed from 60.0 seconds to 20.0 seconds. The + ``ssl_version`` parameter was added. - Returns a list of the network service names found in the - :ref:`tnsnames.ora ` file which is inside the directory - that can be identified by the attribute :attr:`~ConnectParams.config_dir`. - If a tnsnames.ora file does not exist, then an exception is raised. + .. versionchanged:: 2.1.0 -.. method:: ConnectParams.parse_connect_string(connect_string) + The ``pool_boundary`` and ``use_tcp_fast_open`` parameters were added. - Parses the connect string into its components and stores the parameters. + .. versionchanged:: 2.0.0 + + The ``ssl_context`` and ``sdu`` parameters were added. + + .. versionchanged:: 1.4.0 + + The ``connection_id_prefix`` parameter was added. + + +.. _connparamsmeth: + +ConnectParams Methods +===================== - The ``connect string`` parameter can be an Easy Connect string, name-value - pairs, or a simple alias which is looked up in ``tnsnames.ora``. Parameters - that are found in the connect string override any currently stored values. +.. automethod:: ConnectParams.copy -.. method:: ConnectParams.parse_dsn_with_credentials(dsn) +.. automethod:: ConnectParams.get_connect_string - Parses a DSN in the form /@ or in the form - / and returns a 3-tuple containing the parsed user, - password and connect string. Empty strings are returned as the value - *None*. +.. automethod:: ConnectParams.get_network_service_names + +.. automethod:: ConnectParams.parse_connect_string + +.. automethod:: ConnectParams.parse_dsn_with_credentials .. versionadded:: 1.3.0 -.. method:: ConnectParams.set(user=None, proxy_user=None, password=None, \ - newpassword=None, wallet_password=None, access_token=None, host=None, \ - port=None, protocol=None, https_proxy=None, https_proxy_port=None, \ - service_name=None, instance_name=None, sid=None, server_type=None, \ - cclass=None, purity=None, expire_time=None, retry_count=None, \ - retry_delay=None, tcp_connect_timeout=None, ssl_server_dn_match=None, \ - ssl_server_cert_dn=None, wallet_location=None, events=None, \ - externalauth=None, mode=None, disable_oob=None, stmtcachesize=None, \ - edition=None, tag=None, matchanytag=None, config_dir=None, \ - appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, \ - connection_id_prefix=None, ssl_context=None, sdu=None, \ - pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \ - program=oracledb.defaults.program, machine=oracledb.defaults.machine, \ - terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \ - driver_name=oracledb.defaults.driver_name, use_sni=None, \ - thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \ - extra_auth_params=None, handle=None) - - Sets the values for one or more of the parameters of a ConnectParams - object. +.. automethod:: ConnectParams.set + + .. versionchanged:: 3.2.0 + + The ``pool_name`` parameter was added. .. versionchanged:: 3.0.0 @@ -96,29 +100,7 @@ ConnectParams Methods The ``connection_id_prefix`` parameter was added. -.. method:: ConnectParams.set_from_config(config) - - Sets the property values based on the specified configuration. This method - is intended for use with Centralized Configuration Providers. - - The ``config`` parameter is a dictionary which consists of the following - optional keys: "connect_descriptor", "user", "password", and "pyo". - - If the key "connect_descriptor" is specified, it is expected to be a - string, which will be parsed and the properties found within it are stored - in the ConnectParams instance. - - If the keys "user" or "password" are specified, and the parameters do not - already have a user or password set, these values will be stored; - otherwise, they will be ignored. The key "user" is expected to be a - string. The "key" password may be a string or it may be a dictionary which - will be examined by a :ref:`registered password type handler - ` to determine the actual password. - - If the key "pyo" is specified, it is expected to be a dictionary containing - keys corresponding to property names. Any property names accepted by the - ConnectParams class will be stored in the ConnectParams instance; all other - values will be ignored. +.. automethod:: ConnectParams.set_from_config .. versionadded:: 3.0.0 @@ -127,108 +109,56 @@ ConnectParams Methods ConnectParams Attributes ======================== -.. attribute:: ConnectParams.appcontext +All properties are read only. - This read-only attribute is a list that specifies the application context - used by the connection. It is a list of 3-tuples that includes the - namespace, name, and value. Each entry in the tuple is a string. +.. autoproperty:: ConnectParams.appcontext This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: ConnectParams.cclass - - This read-only attribute is a string that specifies the connection class - to use for :ref:`drcp`. +.. autoproperty:: ConnectParams.cclass This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: ConnectParams.config_dir +.. autoproperty:: ConnectParams.config_dir - This read-only attribute is a string that identifies the directory in which - the :ref:`optional configuration files ` are found. The - default is the value of :attr:`defaults.config_dir`. - -.. attribute:: ConnectParams.connection_id_prefix - - This read-only attribute is a string that is added to the beginning of the - generated ``connection_id`` that is sent to the database for - `tracing `__. +.. autoproperty:: ConnectParams.connection_id_prefix This attribute is only supported in python-oracledb Thin mode. .. versionadded:: 1.4.0 -.. attribute:: ConnectParams.debug_jdwp - - This read-only attribute is a string with the format - "host=;port=" that specifies the host and port of the PL/SQL - debugger. This allows the Java Debug Wire Protocol (JDWP) to debug the - PL/SQL code invoked by the python-oracledb driver. The default value is the - value of the environment variable ``ORA_DEBUG_JDWP``. +.. autoproperty:: ConnectParams.debug_jdwp - This attribute is only supported in python-oracledb Thin mode. - - For python-oracledb Thick mode, set the ``ORA_DEBUG_JDWP`` environment - variable which has the same syntax. See :ref:`applntracing` for more - information. + See :ref:`applntracing` for more information. -.. attribute:: ConnectParams.disable_oob - - This read-only attribute is a boolean that indicates whether out-of-band - breaks should be disabled. The default value is *False*. Note that this - value has no effect on Windows, which does not support this functionality. - - This attribute is only supported in python-oracledb Thin mode. +.. autoproperty:: ConnectParams.disable_oob For python-oracledb Thick mode, set the equivalent option in a ``sqlnet.ora`` file. -.. attribute:: ConnectParams.driver_name +.. autoproperty:: ConnectParams.driver_name - This read-only attribute is a string that specifies the driver used by the - client to connect to Oracle Database. This is an arbitrary value set by the - user in the :meth:`oracledb.ConnectParams()` method or the - :attr:`defaults.driver_name` attribute which is the default value. This is - the value shown in the CLIENT_DRIVER column of the - V$SESSION_CONNECT_INFO view. + This is an arbitrary value set by the user in the + :meth:`oracledb.ConnectParams()` method or the + :attr:`oracledb.defaults.driver_name ` attribute + which is the default value. This is the value shown in the CLIENT_DRIVER + column of the V$SESSION_CONNECT_INFO view. This attribute is supported in both python-oracledb Thin and Thick modes. .. versionadded:: 2.5.0 -.. attribute:: ConnectParams.edition - - This read-only attribute is a string that specifies the edition to use - for the connection. This attribute cannot be used simultaneously with the - :attr:`ConnectParams.cclass` attribute. +.. autoproperty:: ConnectParams.edition This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: ConnectParams.events - - This read-only attribute is a boolean that specifies whether the events - mode should be enabled. +.. autoproperty:: ConnectParams.events - This attribute is needed for continuous query notification (CQN) and high - availability event notifications. The default value is *False*. - - This attribute is only supported in python-oracledb Thick mode. - -.. attribute:: ConnectParams.expire_time - - This read-only attribute is an integer that returns the number of minutes - between the sending of keepalive probes. - - The default value is *0*. If this attribute is set to a value greater than - zero, it enables keepalive. +.. autoproperty:: ConnectParams.expire_time This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: ConnectParams.externalauth - - This read-only attribute is a boolean that specifies whether external - authentication should be used. The default value is *False*. +.. autoproperty:: ConnectParams.externalauth For standalone connections, external authentication occurs when the ``user`` and ``password`` attributes are not used. If these attributes, @@ -237,163 +167,122 @@ ConnectParams Attributes This attribute is only supported in python-oracledb Thick mode. -.. attribute:: ConnectParams.extra_auth_params - - This read-only attribute is a dictionary containing the configuration - parameters necessary for Oracle Database authentication using - :ref:`Azure ` or - :ref:` ` cloud native authentication plugins. +.. autoproperty:: ConnectParams.extra_auth_params This attribute is supported in both python-oracledb Thin and Thick modes. .. versionadded:: 3.0.0 -.. attribute:: ConnectParams.host - - This read-only attribute is a string that returns the name or IP address of - the machine hosting the database. +.. autoproperty:: ConnectParams.host This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: ConnectParams.https_proxy - - This read-only attribute is a string that returns the name or IP address of - a proxy host that is to be used for tunneling secure connections. +.. autoproperty:: ConnectParams.https_proxy This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: ConnectParams.https_proxy_port - - This read-only attribute is an integer that returns the port to be used to - communicate with the proxy host. The default value is *0*. +.. autoproperty:: ConnectParams.https_proxy_port This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: ConnectParams.instance_name - - This read-only attribute is a string that returns the instance name of the - database. +.. autoproperty:: ConnectParams.instance_name This attribute is supported in both python-oracledb Thin and Thick modes. .. versionadded:: 3.0.0 -.. attribute:: ConnectParams.machine +.. autoproperty:: ConnectParams.machine - This read-only attribute is a string that specifies the machine name of - the client connecting to Oracle Database. This is an arbitrary value set - by the user in the :meth:`oracledb.ConnectParams()` method or the - :attr:`defaults.machine` attribute which is the default value. This is the - value shown in the MACHINE column of the V$SESSION view. + This is an arbitrary value set by the user in the + :meth:`oracledb.ConnectParams()` method or the + :attr:`oracledb.defaults.machine ` attribute which is the + default value. This is the value shown in the MACHINE column of the + V$SESSION view. This attribute is only supported in python-oracledb Thin mode. .. versionadded:: 2.5.0 -.. attribute:: ConnectParams.matchanytag +.. autoproperty:: ConnectParams.matchanytag - This read-only attribute is a boolean that specifies whether any tag can be - used when acquiring a connection from the pool. The default value is - *False*. - - This attribute is only supported in python-oracledb Thick mode. - -.. attribute:: ConnectParams.mode - - This read-only attribute is an integer that specifies the authorization mode - to use. The default value is :data:`~oracledb.AUTH_MODE_DEFAULT`. +.. autoproperty:: ConnectParams.mode This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: ConnectParams.osuser +.. autoproperty:: ConnectParams.osuser - This read-only attribute is a string that represents the operating system - user that initiates the database connection. This is an arbitrary value - set by the user in the :meth:`oracledb.ConnectParams()` method or the - :attr:`defaults.osuser` attribute which is the default value. This is the - value shown in the OSUSER column of the V$SESSION view. + This is an arbitrary value set by the user in the + :meth:`oracledb.ConnectParams()` method or the + :attr:`oracledb.defaults.osuser ` attribute which is the + default value. This is the value shown in the OSUSER column of the + V$SESSION view. This attribute is only supported in python-oracledb Thin mode. .. versionadded:: 2.5.0 -.. attribute:: ConnectParams.pool_boundary +.. autoproperty:: ConnectParams.pool_boundary - This read-only attribute is one of the strings *statement* or *transaction* - which indicates when pooled :ref:`DRCP ` or PRCP connections can be - returned to the pool. If the value is *statement*, then pooled DRCP or PRCP - connections are implicitly released back to the DRCP or PRCP pool when the - connection is stateless (that is, there are no active cursors, active - transactions, temporary tables, or temporary LOBs). If the value is - *transaction*, then pooled DRCP or PRCP connections are implicitly released - back to the DRCP or PRCP pool when either one of the methods - :meth:`Connection.commit()` or :meth:`Connection.rollback()` are called. - This attribute requires the use of DRCP or PRCP with Oracle Database 23ai - (or later). See :ref:`implicitconnpool` for more information. + If the value is *statement*, then pooled DRCP or PRCP connections are + implicitly released back to the DRCP or PRCP pool when the connection is + stateless (that is, there are no active cursors, active transactions, + temporary tables, or temporary LOBs). If the value is *transaction*, then + pooled DRCP or PRCP connections are implicitly released back to the DRCP or + PRCP pool when either one of the methods :meth:`Connection.commit()` or + :meth:`Connection.rollback()` are called. This attribute requires the use + of DRCP or PRCP with Oracle Database version 23, or later. See + :ref:`implicitconnpool` for more information. This attribute is supported in both python-oracledb Thin and Thick modes. .. versionadded:: 2.1.0 -.. attribute:: ConnectParams.port +.. autoproperty:: ConnectParams.pool_name + + See :ref:`DRCP Pool Names `. + + This attribute is supported in both python-oracledb Thin and Thick modes. + + .. versionadded:: 3.2.0 - This read-only attribute is an integer that returns the port number on - which the database listener is listening. The default value is *1521*. +.. autoproperty:: ConnectParams.port This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: ConnectParams.program +.. autoproperty:: ConnectParams.program - This read-only attribute is a string that specifies the name of the - executable program or application connected to Oracle Database. This is an - arbitrary value set by the user in the :meth:`oracledb.ConnectParams()` - method or the :attr:`defaults.program` attribute which is the default - value. This is the value shown in the PROGRAM column of the + This is an arbitrary value set by the user in the + :meth:`oracledb.ConnectParams()` method or the + :attr:`oracledb.defaults.program ` attribute which is the + default value. This is the value shown in the PROGRAM column of the V$SESSION view. This attribute is supported in python-oracledb Thin mode. .. versionadded:: 2.5.0 -.. attribute:: ConnectParams.protocol - - This read-only attribute is a string that indicates whether unencrypted - network traffic or encrypted network traffic (TLS) is used and it can have - the value *tcp* or *tcps*. The default value is *tcp*. +.. autoproperty:: ConnectParams.protocol This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: ConnectParams.proxy_user - - This read-only attribute is a string that specifies the name of the proxy - user to connect to. If this value is not specified, then it will be parsed - out of the user if the user attribute is in the form "user[proxy_user]". +.. autoproperty:: ConnectParams.proxy_user This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: ConnectParams.purity +.. autoproperty:: ConnectParams.purity - This read-only attribute is an integer that returns the purity used for - :ref:`drcp`. When the value of this attribute is - :attr:`oracledb.PURITY_DEFAULT`, then any standalone connection will use - :attr:`oracledb.PURITY_NEW` and any pooled connection will use - :attr:`oracledb.PURITY_SELF`. The default value is - :data:`~oracledb.PURITY_DEFAULT`. + When the value of this attribute is :attr:`oracledb.PURITY_DEFAULT`, then + any standalone connection will use :attr:`oracledb.PURITY_NEW` and any + pooled connection will use :attr:`oracledb.PURITY_SELF`. The default value + is :data:`~oracledb.PURITY_DEFAULT`. This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: ConnectParams.retry_count - - This read-only attribute is an integer that returns the number of times - that a connection attempt should be retried before the attempt is - terminated. The default value is *0*. +.. autoproperty:: ConnectParams.retry_count This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: ConnectParams.retry_delay - - This read-only attribute is an integer that returns the number of seconds - to wait before making a new connection attempt. The default value is *1*. +.. autoproperty:: ConnectParams.retry_delay This attribute is supported in both python-oracledb Thin and Thick modes. @@ -402,15 +291,9 @@ ConnectParams Attributes The default value of this attribute was changed from *0* seconds to *1* second. -.. attribute:: ConnectParams.sdu +.. autoproperty:: ConnectParams.sdu - This read-only attribute is an integer that returns the requested size of - the Session Data Unit (SDU), in bytes. The value tunes internal buffers - used for communication to the database. Bigger values can increase - throughput for large queries or bulk data loads, but at the cost of higher - memory use. The SDU size that will actually be used is negotiated down to - the lower of this value and the database network SDU configuration value. - See the `SQL*Net documentation + See the `Database Net Services documentation `__ for more details. @@ -418,111 +301,51 @@ ConnectParams Attributes .. versionadded:: 2.0.0 -.. attribute:: ConnectParams.server_type - - This read-only attribute is a string that returns the type of server - connection that should be established. If specified, it should be one of - *dedicated*, *shared*, or *pooled*. +.. autoproperty:: ConnectParams.server_type This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: ConnectParams.service_name - - This read-only attribute is a string that returns the service name of the - database. +.. autoproperty:: ConnectParams.service_name This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: ConnectParams.shardingkey - - This read-only attribute is a list that specifies a sequence of strings, - numbers, bytes, or dates that identify the database shard to connect to. - See :ref:`connsharding`. - - This attribute is only supported in python-oracledb Thick mode. - -.. attribute:: ConnectParams.sid +.. autoproperty:: ConnectParams.shardingkey - This read-only attribute is a string that returns the SID of the database. - It is recommended to use the :attr:`ConnectParams.service_name` instead. +.. autoproperty:: ConnectParams.sid This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: ConnectParams.ssl_context - - This read-only attribute is an `SSLContext object - `__ which is used - for connecting to the database using TLS. This SSL context will be modified - to include the private key or any certificates found in a separately - supplied wallet. This parameter should only be specified if the default - SSLContext object cannot be used. +.. autoproperty:: ConnectParams.ssl_context This attribute is only supported in python-oracledb Thin mode. .. versionadded:: 2.0.0 -.. attribute:: ConnectParams.ssl_server_cert_dn - - This read-only attribute is a string that returns the distinguished name - (DN), which should be matched with the server. If this value is specified, - then it is used for any verification. Otherwise, the hostname will be used. - - This value is ignored if the :attr:`~ConnectParams.ssl_server_dn_match` - attribute is not set to the value *True*. +.. autoproperty:: ConnectParams.ssl_server_cert_dn This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: ConnectParams.ssl_server_dn_match - - This read-only attribute is a boolean that indicates whether the server - certificate distinguished name (DN) should be matched in addition to the - regular certificate verification that is performed. The default value is - *True*. - - Note that if the :attr:`~ConnectParams.ssl_server_cert_dn` attribute is not - specified, then host name matching is performed instead. +.. autoproperty:: ConnectParams.ssl_server_dn_match This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: ConnectParams.ssl_version - - This read-only attribute is one of the constants *ssl.TLSVersion.TLSv1_2* - or *ssl.TLSVersion.TLSv1_3* which identifies the TLS protocol version - used. These constants are defined in the Python `ssl `__ module. +.. autoproperty:: ConnectParams.ssl_version This attribute is supported in both python-oracledb Thin and Thick modes. .. versionadded:: 2.3.0 -.. attribute:: ConnectParams.stmtcachesize - - This read-only attribute is an integer that identifies the initial size of - the statement cache. The default is the value of - :attr:`defaults.stmtcachesize`. +.. autoproperty:: ConnectParams.stmtcachesize This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: ConnectParams.supershardingkey +.. autoproperty:: ConnectParams.supershardingkey - This read-only attribute is a list that specifies a sequence of strings, - numbers, bytes, or dates that identify the database shard to connect to. - See :ref:`connsharding`. +.. autoproperty:: ConnectParams.tag This attribute is only supported in python-oracledb Thick mode. -.. attribute:: ConnectParams.tag - - This read-only attribute is a string that identifies the type of connection - that should be returned from a pool. - - This attribute is only supported in python-oracledb Thick mode. - -.. attribute:: ConnectParams.tcp_connect_timeout - - This read-only attribute is a float that indicates the maximum number of - seconds to wait for a connection to be established to the database host. - The default value is *20.0*. +.. autoproperty:: ConnectParams.tcp_connect_timeout This attribute is supported in both python-oracledb Thin and Thick modes. @@ -531,68 +354,40 @@ ConnectParams Attributes The default value of this attribute was changed from *60.0* seconds to *20.0* seconds. -.. attribute:: ConnectParams.use_sni - - This read-only attribute is a boolean which indicates whether to use the - TLS Server Name Indicator (SNI) extension to bypass the second TLS - negotiation that would otherwise be required. - - This attribute is supported in both python-oracledb Thin and Thick modes. - - .. versionadded:: 3.0.0 - -.. attribute:: ConnectParams.terminal +.. autoproperty:: ConnectParams.terminal - This read-only attribute is a string that specifies the terminal - identifier from which the connection originates. This is an arbitrary value - set by the user in the :meth:`oracledb.ConnectParams()` method or the - :attr:`defaults.terminal` attribute which is the default value. This is the - value shown in the TERMINAL column of the V$SESSION view. + This is an arbitrary value set by the user in the + :meth:`oracledb.ConnectParams()` method or the + :attr:`oracledb.defaults.terminal ` attribute which is + the default value. This is the value shown in the TERMINAL column of the + V$SESSION view. This attribute is only supported in python-oracledb Thin mode. .. versionadded:: 2.5.0 -.. attribute:: ConnectParams.thick_mode_dsn_passthrough +.. autoproperty:: ConnectParams.use_sni - This read-only attribute is a boolean which indicates whether the connect - string should be passed unchanged to Oracle Client libraries for parsing or - if python-oracledb should parse the connect string itself when using Thick - mode. The default value is the value of - :attr:`defaults.thick_mode_dsn_passthrough`. + This attribute is supported in both python-oracledb Thin and Thick modes. + + .. versionadded:: 3.0.0 + +.. autoproperty:: ConnectParams.thick_mode_dsn_passthrough This attribute is only supported in python-oracledb Thick mode. .. versionadded:: 3.0.0 -.. attribute:: ConnectParams.use_tcp_fast_open - - This read-only attribute is a boolean which indicates whether to use an - an `Oracle Autonomous Database Serverless (ADB-S) - `__ - specific feature that can reduce the latency in round-trips to the database - after a connection has been established. This feature is only available - with certain versions of ADB-S. The default value is *False*. +.. autoproperty:: ConnectParams.use_tcp_fast_open This attribute is supported in both python-oracledb Thin and Thick modes. .. versionadded:: 2.1.0 -.. attribute:: ConnectParams.user - - This read-only attribute is a string that specifies the name of the user to - connect to. +.. autoproperty:: ConnectParams.user This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: ConnectParams.wallet_location - - This read-only attribute is a string that specifies the directory where the - wallet can be found. - - In python-oracledb Thin mode, this attribute is the directory containing - the PEM-encoded wallet file, ewallet.pem. In python-oracledb Thick mode, - this attribute is the directory containing the file, cwallet.sso. +.. autoproperty:: ConnectParams.wallet_location This attribute is supported in both python-oracledb Thin and Thick modes. diff --git a/doc/src/api_manual/connection.rst b/doc/src/api_manual/connection.rst index b962d875..7df813d4 100644 --- a/doc/src/api_manual/connection.rst +++ b/doc/src/api_manual/connection.rst @@ -4,460 +4,184 @@ API: Connection Objects *********************** -A Connection object can be created with :meth:`oracledb.connect()` or with -:meth:`ConnectionPool.acquire()`. +.. currentmodule:: oracledb -.. note:: +Connection Class +================ - Any outstanding database transaction will be rolled back when the - connection object is destroyed or closed. You must perform a commit first - if you want data to persist in the database, see :ref:`txnmgmnt`. +.. autoclass:: Connection -Connection Methods -================== - -.. method:: Connection.__enter__() - - The entry point for the connection as a context manager. It returns itself. + A connection object should be created with :meth:`oracledb.connect()` or + with :meth:`ConnectionPool.acquire()`. .. note:: - This method is an extension to the DB API definition. + Any outstanding database transaction will be rolled back when the + connection object is destroyed or closed. You must perform a commit + first if you want data to persist in the database, see :ref:`txnmgmnt`. -.. method:: Connection.__exit__() +Connection Methods +================== - The exit point for the connection as a context manager. This will close - the connection and roll back any uncommitted transaction. +.. automethod:: Connection.__enter__ - .. note:: + .. dbapimethodextension:: - This method is an extension to the DB API definition. +.. automethod:: Connection.__exit__ -.. method:: Connection.begin([formatId, transactionId, branchId]) + .. dbapimethodextension:: - Explicitly begins a new transaction. Without parameters, this explicitly - begins a local transaction; otherwise, this explicitly begins a distributed - (global) transaction with the given parameters. See the Oracle - documentation for more details. - - Note that in order to make use of global (distributed) transactions, the - :attr:`~Connection.internal_name` and :attr:`~Connection.external_name` - attributes must be set. +.. automethod:: Connection.begin .. deprecated:: 1.0 - Use the method :meth:`Connection.tpc_begin()` instead. - - .. note:: - - This method is an extension to the DB API definition. + Use the method :meth:`tpc_begin()` instead. -.. method:: Connection.cancel() + .. dbapimethodextension:: - Breaks a long-running statement. +.. automethod:: Connection.begin_sessionless_transaction - .. note:: + See :ref:`sessionlesstxns`. - This method is an extension to the DB API definition. + .. versionadded:: 3.3.0 -.. method:: Connection.changepassword(oldpassword, newpassword) +.. automethod:: Connection.cancel - Changes the password for the user to which the connection is - connected. + .. dbapimethodextension:: - .. note:: +.. automethod:: Connection.changepassword - This method is an extension to the DB API definition. + .. dbapimethodextension:: -.. method:: Connection.close() +.. automethod:: Connection.close - Closes the connection now and makes it unusable for further operations. - An Error exception will be raised if any operation is attempted with this - connection after this method is completed successfully. +.. automethod:: Connection.commit - All open cursors and LOBs created by the connection will be closed and will - also no longer be usable. - - Internally, references to the connection are held by cursor objects, - LOB objects, subscription objects, etc. Once all of these references are - released, the connection itself will be closed automatically. Either - control references to these related objects carefully or explicitly close - connections in order to ensure sufficient resources are available. - -.. method:: Connection.commit() - - Commits any pending transactions to the database. - -.. method:: Connection.createlob(lob_type, data=None) - - Creates and returns a new temporary :ref:`LOB object ` of the - specified type. The ``lob_type`` parameter should be one of - :data:`oracledb.DB_TYPE_CLOB`, :data:`oracledb.DB_TYPE_BLOB`, or - :data:`oracledb.DB_TYPE_NCLOB`. - - If data is supplied, it will be written to the temporary LOB before it is - returned. +.. automethod:: Connection.createlob .. versionchanged:: 2.0 The parameter ``data`` was added. - .. note:: - - This method is an extension to the DB API definition. - -.. method:: Connection.cursor(scrollable=False) + .. dbapimethodextension:: - Returns a new :ref:`cursor object ` using the connection. +.. automethod:: Connection.cursor -.. method:: Connection.decode_oson(data) - - Decodes `OSON-encoded `__ bytes and returns the - object encoded in those bytes. This is useful for fetching columns which - have the check constraint ``IS JSON FORMAT OSON`` enabled. +.. automethod:: Connection.decode_oson .. versionadded:: 2.1.0 -.. method:: Connection.encode_oson(value) - - Encodes a Python value into `OSON-encoded `__ - bytes and returns them. This is useful for inserting into columns which - have the check constraint ``IS JSON FORMAT OSON`` enabled. + .. dbapimethodextension:: - .. versionadded:: 2.1.0 +.. automethod:: Connection.direct_path_load -.. method:: Connection.fetch_df_all(statement, parameters=None, \ - arraysize=None) + See :ref:`directpathloads`. - Fetches all rows of the SQL query ``statement``, returning them in an - :ref:`OracleDataFrame ` object. An empty - OracleDataFrame is returned if there are no rows available. + .. versionadded:: 3.4.0 - The ``parameters`` parameter can be a list of tuples, where each tuple item - maps to one :ref:`bind variable placeholder ` in ``statement``. It - can also be a list of dictionaries, where the keys match the bind variable - placeholder names in ``statement``. + .. dbapimethodextension:: - The ``arraysize`` parameter can be specified to tune performance of - fetching data across the network. It defaults to - :attr:`defaults.arraysize`. Internally, the ``fetch_df_all()``'s - :attr:`Cursor.prefetchrows` size is always set to the value of the explicit - or default ``arraysize`` parameter value. +.. automethod:: Connection.encode_oson - See :ref:`dataframeformat` for the supported data types and examples. - - .. note:: - - The data frame support in python-oracledb 3.0.0 is a pre-release and - may change in the next version. - - .. versionadded:: 3.0.0 - -.. method:: Connection.fetch_df_batches(statement, parameters=None, \ - size=None) - - This returns an iterator yielding the next ``size`` rows of the SQL query - ``statement`` in each iteration as an :ref:`OracleDataFrame - ` object. An empty OracleDataFrame is returned if there - are no rows available. + .. versionadded:: 2.1.0 - The ``parameters`` parameter can be a list of tuples, where each tuple item - maps to one :ref:`bind variable placeholder ` in ``statement``. It - can also be a list of dictionaries, where the keys match the bind variable - placeholder names in ``statement``. + .. dbapimethodextension:: - The ``size`` parameter controls the number of records fetched in each - batch. It defaults to :attr:`defaults.arraysize`. Internally, the - ``fetch_df_batches()``'s :attr:`Cursor.arraysize` and - :attr:`Cursor.prefetchrows` sizes are always set to the value of the - explicit or default ``size`` parameter value. +.. automethod:: Connection.fetch_df_all See :ref:`dataframeformat` for the supported data types and examples. - .. note:: - - The data frame support in python-oracledb 3.0.0 is a pre-release and - may change in the next version. - - .. versionadded:: 3.0.0 - -.. method:: Connection.getSodaDatabase() - - Returns a :ref:`SodaDatabase ` object for Simple Oracle Document - Access (SODA). All SODA operations are performed either on the returned - SodaDatabase object or from objects created by the returned SodaDatabase - object. See `here `__ for - additional information on SODA. - - .. note:: - - This method is an extension to the DB API definition. - -.. method:: Connection.gettype(name) - - Returns a :ref:`type object ` given its name. This can then - be used to create objects which can be bound to cursors created by this - connection. - - .. note:: - - This method is an extension to the DB API definition. - -.. method:: Connection.is_healthy() + .. dbapimethodextension:: - This function returns a boolean indicating the health status of a - connection. + .. versionchanged:: 3.4.0 - Connections may become unusable in several cases, such as, if the network - socket is broken, if an Oracle error indicates the connection is unusable, - or, after receiving a planned down notification from the database. + The ``fetch_decimals`` and ``requested_schema`` parameters were added. - This function is best used before starting a new database request on an - existing :ref:`standalone connections `. For pooled - connections, the :meth:`ConnectionPool.acquire()` method internally - performs this check before returning a connection to the application, see - :ref:`poolhealth`. + .. versionadded:: 3.0.0 - If this function returns *False*, the connection should be not be used by - the application and a new connection should be established instead. +.. automethod:: Connection.fetch_df_batches - This function performs a local check. To fully check a connection's health, - use :meth:`Connection.ping()` which performs a round-trip to the database. + See :ref:`dataframeformat` for the supported data types and examples. -.. method:: Connection.msgproperties(payload, correlation, delay, exceptionq, expiration, priority) + .. dbapimethodextension:: - Returns an object specifying the properties of messages used in advanced - queuing. See :ref:`msgproperties` for more information. + .. versionchanged:: 3.4.0 - Each of the parameters are optional. If specified, they act as a shortcut - for setting each of the equivalently named properties. + The ``fetch_decimals`` and ``requested_schema`` parameters were added. - .. note:: + .. versionadded:: 3.0.0 - This method is an extension to the DB API definition. +.. automethod:: Connection.getSodaDatabase -.. method:: Connection.ping() + .. dbapimethodextension:: - Pings the database to verify if the connection is valid. +.. automethod:: Connection.gettype - This function performs a :ref:`round-trip ` to the database, so - it should not be used unnecessarily. + .. dbapimethodextension:: - Note connection pools will perform the same health check automatically, - based on configuration settings. See :ref:`poolhealth`. +.. automethod:: Connection.is_healthy - .. note:: + .. dbapimethodextension:: - This method is an extension to the DB API definition. +.. automethod:: Connection.msgproperties -.. method:: Connection.prepare() + .. dbapimethodextension:: - Prepares the distributed (global) transaction for commit. Returns a boolean - indicating if a transaction was actually prepared in order to avoid the - error ``ORA-24756 (transaction does not exist)``. +.. automethod:: Connection.ping - .. deprecated:: python-oracledb 1.0 + .. dbapimethodextension:: - Use the method :meth:`Connection.tpc_prepare()` instead. +.. automethod:: Connection.prepare - .. note:: + .. deprecated:: 1.0. Use the method :meth:`tpc_prepare()` instead. - This method is an extension to the DB API definition. + .. dbapimethodextension:: -.. method:: Connection.queue(name, payload_type=None) +.. automethod:: Connection.queue - Creates a :ref:`queue ` which is used to enqueue and dequeue - messages in Advanced Queuing. + .. dbapimethodextension:: - The ``name`` parameter is expected to be a string identifying the queue in - which messages are to be enqueued or dequeued. +.. automethod:: Connection.resume_sessionless_transaction - The ``payload_type`` parameter, if specified, is expected to be an - :ref:`object type ` that identifies the type of payload the - queue expects. If the string "JSON" is specified, JSON data is enqueued and - dequeued. If not specified, RAW data is enqueued and dequeued. + See :ref:`sessionlesstxns`. - For consistency and compliance with the PEP 8 naming style, the - parameter ``payloadType`` was renamed to ``payload_type``. The old name - will continue to work as a keyword parameter for a period of time. + .. versionadded:: 3.3.0 - .. note:: +.. automethod:: Connection.rollback - This method is an extension to the DB API definition. +.. automethod:: Connection.shutdown -.. method:: Connection.rollback() + See :ref:`startup`. - Rolls back any pending transactions. + .. dbapimethodextension:: -.. method:: Connection.shutdown([mode]) +.. automethod:: Connection.startup - Shuts down the database. In order to do this the connection must be - connected as :data:`~oracledb.SYSDBA` or :data:`~oracledb.SYSOPER`. Two - calls must be made unless the mode specified is - :data:`~oracledb.DBSHUTDOWN_ABORT`. - An example is shown below: + See :ref:`startup`. - :: + .. dbapimethodextension:: - import oracledb +.. automethod:: Connection.subscribe - connection = oracledb.connect(mode = oracledb.SYSDBA) - connection.shutdown(mode = oracledb.DBSHUTDOWN_IMMEDIATE) - cursor = connection.cursor() - cursor.execute("alter database close normal") - cursor.execute("alter database dismount") - connection.shutdown(mode = oracledb.DBSHUTDOWN_FINAL) + .. dbapimethodextension:: .. note:: - This method is an extension to the DB API definition. - - -.. method:: Connection.startup(force=False, restrict=False, pfile=None) - - Starts up the database. This is equivalent to the SQL\*Plus command - ``startup nomount``. The connection must be connected as - :data:`~oracledb.SYSDBA` or :data:`~oracledb.SYSOPER` with the - :data:`~oracledb.PRELIM_AUTH` option specified for this to work. - - The ``pfile`` parameter, if specified, is expected to be a string - identifying the location of the parameter file (PFILE) which will be used - instead of the stored parameter file (SPFILE). - - An example is shown below: - - :: - - import oracledb - - connection = oracledb.connect( - mode=oracledb.SYSDBA | oracledb.PRELIM_AUTH) - connection.startup() - connection = oracledb.connect(mode=oracledb.SYSDBA) - cursor = connection.cursor() - cursor.execute("alter database mount") - cursor.execute("alter database open") - - .. note:: + The subscription can be deregistered in the database by calling the + function :meth:`unsubscribe()`. If this method is not called and the + connection that was used to create the subscription is explicitly + closed using the function :meth:`close()`, the subscription will not be + deregistered in the database. - This method is an extension to the DB API definition. - -.. method:: Connection.subscribe(namespace=oracledb.SUBSCR_NAMESPACE_DBCHANGE, \ - protocol=oracledb.SUBSCR_PROTO_OCI, callback=None, timeout=0, \ - operations=OPCODE_ALLOPS, port=0, qos=0, ip_address=None, grouping_class=0, \ - grouping_value=0, grouping_type=oracledb.SUBSCR_GROUPING_TYPE_SUMMARY, \ - name=None, client_initiated=False) - - Returns a new :ref:`subscription object ` that receives - notifications for events that take place in the database that match the - given parameters. - - The ``namespace`` parameter specifies the namespace the subscription uses. - It can be one of :data:`oracledb.SUBSCR_NAMESPACE_DBCHANGE` or - :data:`oracledb.SUBSCR_NAMESPACE_AQ`. - - The ``protocol`` parameter specifies the protocol to use when notifications - are sent. Currently the only valid value is - :data:`oracledb.SUBSCR_PROTO_OCI`. - - The ``callback`` is expected to be a callable that accepts a single - parameter. A :ref:`message object ` is passed to this callback - whenever a notification is received. - - The ``timeout`` value specifies that the subscription expires after the - given time in seconds. The default value of *0* indicates that the - subscription never expires. - - The ``operations`` parameter enables filtering of the messages that are - sent (insert, update, delete). The default value will send notifications - for all operations. This parameter is only used when the namespace is set - to :data:`oracledb.SUBSCR_NAMESPACE_DBCHANGE`. - - The ``port`` parameter specifies the listening port for callback - notifications from the database server. If not specified, an unused port - will be selected by the Oracle Client libraries. - - The ``qos`` parameter specifies quality of service options. It should be - one or more of the following flags, OR'ed together: - :data:`oracledb.SUBSCR_QOS_RELIABLE`, - :data:`oracledb.SUBSCR_QOS_DEREG_NFY`, - :data:`oracledb.SUBSCR_QOS_ROWIDS`, - :data:`oracledb.SUBSCR_QOS_QUERY`, - :data:`oracledb.SUBSCR_QOS_BEST_EFFORT`. - - The ``ip_address`` parameter specifies the IP address (*IPv4* or *IPv6*) in - standard string notation to bind for callback notifications from the - database server. If not specified, the client IP address will be determined - by the Oracle Client libraries. - - The ``grouping_class`` parameter specifies what type of grouping of - notifications should take place. Currently, if set, this value can only be - set to the value :data:`oracledb.SUBSCR_GROUPING_CLASS_TIME`, which - will group notifications by the number of seconds specified in the - ``grouping_value`` parameter. The ``grouping_type`` parameter should be one - of the values :data:`oracledb.SUBSCR_GROUPING_TYPE_SUMMARY` (the default) - or :data:`oracledb.SUBSCR_GROUPING_TYPE_LAST`. - - The ``name`` parameter is used to identify the subscription and is - specific to the selected namespace. If the namespace parameter is - :data:`oracledb.SUBSCR_NAMESPACE_DBCHANGE` then the name is optional and - can be any value. If the namespace parameter is - :data:`oracledb.SUBSCR_NAMESPACE_AQ`, however, the name must be in the - format '' for single consumer queues and - ':' for multiple consumer queues, and identifies - the queue that will be monitored for messages. The queue name may include - the schema, if needed. - - The ``client_initiated`` parameter is used to determine if client initiated - connections or server initiated connections (the default) will be - established. Client initiated connections are only available in Oracle - Client 19.4 and Oracle Database 19.4 and higher. - - For consistency and compliance with the PEP 8 naming style, the - parameter ``ipAddress`` was renamed to ``ip_address``, the parameter - ``groupingClass`` was renamed to ``grouping_class``, the parameter - ``groupingValue`` was renamed to ``grouping_value``, the parameter - ``groupingType`` was renamed to ``grouping_type`` and the parameter - ``clientInitiated`` was renamed to ``client_initiated``. The old names will - continue to work as keyword parameters for a period of time. +.. automethod:: Connection.suspend_sessionless_transaction - .. note:: + See :ref:`sessionlesstxns`. - This method is an extension to the DB API definition. + .. versionadded:: 3.3.0 - .. note:: + .. dbapimethodextension:: - The subscription can be deregistered in the database by calling the - function :meth:`~Connection.unsubscribe()`. If this method is not - called and the connection that was used to create the subscription is - explicitly closed using the function :meth:`~Connection.close()`, the - subscription will not be deregistered in the database. - -.. method:: Connection.tpc_begin(xid, flags, timeout) - - Begins a Two-Phase Commit (TPC) on a global transaction using the specified - transaction identifier (xid). - - The ``xid`` parameter should be an object returned by the - :meth:`~Connection.xid()` method. - - The ``flags`` parameter is one of the constants - :data:`oracledb.TPC_BEGIN_JOIN`, :data:`oracledb.TPC_BEGIN_NEW`, - :data:`oracledb.TPC_BEGIN_PROMOTE`, or :data:`oracledb.TPC_BEGIN_RESUME`. - The default is :data:`oracledb.TPC_BEGIN_NEW`. - - The ``timeout`` parameter is the number of seconds to wait for a - transaction to become available for resumption when - :data:`~oracledb.TPC_BEGIN_RESUME` is specified in the ``flags`` parameter. - When :data:`~oracledb.TPC_BEGIN_NEW` is specified in the ``flags`` - parameter, the ``timeout`` parameter indicates the number of seconds the - transaction can be inactive before it is automatically terminated by the - system. A transaction is inactive between the time it is detached with - :meth:`Connection.tpc_end()` and the time it is resumed with - :meth:`Connection.tpc_begin()`.The default is *0* seconds. +.. automethod:: Connection.tpc_begin The following code sample demonstrates the ``tpc_begin()`` function:: @@ -466,27 +190,7 @@ Connection Methods See :ref:`tpc` for information on TPC. -.. method:: Connection.tpc_commit(xid, one_phase) - - Commits a global transaction. When called with no arguments, this method - commits a transaction previously prepared with - :meth:`~Connection.tpc_begin()` and optionally prepared with - :meth:`~Connection.tpc_prepare()`. If :meth:`~Connection.tpc_prepare()` - is not called, a single phase commit is performed. A transaction manager - may choose to do this if only a single resource is participating in the - global transaction. - - If an ``xid`` parameter is passed, then an object should be returned by the - :meth:`~Connection.xid()` function. This form should be called outside of a - transaction and is intended for use in recovery. - - The ``one_phase`` parameter is a boolean identifying whether to perform a - one-phase or two-phase commit. If ``one_phase`` parameter is *True*, a - single-phase commit is performed. The default value is *False*. This - parameter is only examined if a value is provided for the ``xid`` - parameter. Otherwise, the driver already knows whether - :meth:`~Connection.tpc_prepare()` was called for the transaction and - whether a one-phase or two-phase commit is required. +.. automethod:: Connection.tpc_commit The following code sample demonstrates the ``tpc_commit()`` function:: @@ -495,23 +199,7 @@ Connection Methods See :ref:`tpc` for information on TPC. -.. method:: Connection.tpc_end(xid, flags) - - Ends or suspends work on a global transaction. This function is only - intended for use by transaction managers. - - If an ``xid`` parameter is passed, then an object should be returned by the - :meth:`~Connection.xid()` function. If no xid parameter is passed, then the - transaction identifier used by the previous :meth:`~Connection.tpc_begin()` - is used. - - The ``flags`` parameter is one of the constants - :data:`oracledb.TPC_END_NORMAL` or :data:`oracledb.TPC_END_SUSPEND`. The - default is :data:`oracledb.TPC_END_NORMAL`. - - If the flag is :data:`oracledb.TPC_END_SUSPEND` then the transaction may be - resumed later by calling :meth:`Connection.tpc_begin()` with the flag - :data:`oracledb.TPC_BEGIN_RESUME`. +.. automethod:: Connection.tpc_end The following code sample demonstrates the ``tpc_end()`` function:: @@ -520,13 +208,9 @@ Connection Methods See :ref:`tpc` for information on TPC. -.. method:: Connection.tpc_forget(xid) - - Causes the database to forget a heuristically completed TPC transaction. - This function is only intended to be called by transaction managers. + .. dbapimethodextension:: - The ``xid`` parameter is mandatory and should be an object should be - returned by the :meth:`~Connection.xid()` function. +.. automethod:: Connection.tpc_forget The following code sample demonstrates the ``tpc_forget()`` function:: @@ -535,21 +219,9 @@ Connection Methods See :ref:`tpc` for information on TPC. -.. method:: Connection.tpc_prepare(xid) - - Prepares a two-phase transaction for commit. After this function is called, - no further activity should take place on this connection until either - :meth:`~Connection.tpc_commit()` or :meth:`~Connection.tpc_rollback()` have - been called. + .. dbapimethodextension:: - Returns a boolean indicating whether a commit is needed or not. If you - attempt to commit when not needed, then it results in the error - ``ORA-24756: transaction does not exist``. - - If an ``xid`` parameter is passed, then an object should be returned by - the :meth:`~Connection.xid()` function. If an ``xid`` parameter is not - passed, then the transaction identifier used by the previous - :meth:`~Connection.tpc_begin()` is used. +.. automethod:: Connection.tpc_prepare The following code sample demonstrates the ``tpc_prepare()`` function:: @@ -558,35 +230,15 @@ Connection Methods See :ref:`tpc` for information on TPC. -.. method:: Connection.tpc_recover() - - Returns a list of pending transaction identifiers that require recovery. - Objects of type ``Xid`` (as returned by the :meth:`~Connection.xid()` - function) are returned and these can be passed to - :meth:`~Connection.tpc_commit()` or :meth:`~Connection.tpc_rollback()` as - needed. - - This function queries the DBA_PENDING_TRANSACTIONS view and requires - "SELECT" privilege on that view. +.. automethod:: Connection.tpc_recover The following code sample demonstrates the ``tpc_recover()`` function:: connection.tpc_recover() - See :ref:`tpc` for information on TPC. -.. method:: Connection.tpc_rollback(xid) - - Rolls back a global transaction. - - If an ``xid`` parameter is not passed, then it rolls back the transaction - that was previously started with :meth:`~Connection.tpc_begin()`. - - If an ``xid`` parameter is passed, then an object should be returned by - :meth:`~Connection.xid()` and the specified transaction is rolled back. - This form should be called outside of a transaction and is intended for - use in recovery. +.. automethod:: Connection.tpc_rollback The following code sample demonstrates the ``tpc_rollback()`` function:: @@ -595,32 +247,11 @@ Connection Methods See :ref:`tpc` for information on TPC. -.. method:: Connection.unsubscribe(subscr) - - Unsubscribe from events in the database that were originally subscribed to - using :meth:`~Connection.subscribe()`. The connection used to unsubscribe - should be the same one used to create the subscription, or should access - the same database and be connected as the same user name. - -.. method:: Connection.xid (format_id, global_transaction_id, branch_qualifier) +.. automethod:: Connection.unsubscribe - Returns a global transaction identifier (xid) that can be used with the - Two-Phase Commit (TPC) functions. + .. dbapimethodextension:: - The ``xid`` contains a format identifier, a global transaction identifier, and - a branch identifier. There are no checks performed at the Python level. The - values are checked by ODPI-C when they are passed to the relevant functions. - .. When this functionality is also supported in the thin driver the checks will be performed at the Python level as well. - - The ``format_id`` parameter should be a positive 32-bit integer. This - value identifies the format of the ``global_transaction_id`` and - ``branch_qualifier`` parameters and the value is determined by the - Transaction Manager (TM), if one is in use. - - The ``global_transaction_id`` and ``branch_qualifier`` parameters should - be of type bytes or string. If a value of type string is passed, then - this value will be UTF-8 encoded to bytes. The values cannot exceed 64 - bytes in length. +.. automethod:: Connection.xid The following code sample demonstrates the ``xid()`` function:: @@ -628,255 +259,114 @@ Connection Methods See :ref:`tpc` for information on TPC. + .. dbapimethodextension:: + .. _connattrs: Connection Attributes ===================== -.. attribute:: Connection.action +.. autoproperty:: Connection.action - This write-only attribute sets the ACTION column in the V$SESSION view. It - is a string attribute but the value *None* is accepted and treated as an - empty string. + .. dbapiattributeextension:: - .. note:: - - This attribute is an extension to the DB API definition. - -.. attribute:: Connection.autocommit +.. autoproperty:: Connection.autocommit - This read-write attribute determines whether autocommit mode is on or off. - When autocommit mode is on, all statements are committed as soon as they - have completed executing. + .. dbapiattributeextension:: - .. note:: +.. autoproperty:: Connection.call_timeout - This attribute is an extension to the DB API definition. + .. dbapiattributeextension:: -.. attribute:: Connection.call_timeout +.. autoproperty:: Connection.client_identifier - This read-write attribute specifies the amount of time (in milliseconds) - that a single round-trip to the database may take before a timeout will - occur. A value of *0* means that no timeout will take place. + .. dbapiattributeextension:: - If a timeout occurs, the error ``DPI-1067`` will be returned if the - connection is still usable. Alternatively the error ``DPI-1080`` will be - returned if the connection has become invalid and can no longer be used. +.. autoproperty:: Connection.clientinfo - For consistency and compliance with the PEP 8 naming style, the - attribute ``callTimeout`` was renamed to ``call_timeout``. The old name - will continue to work for a period of time. The error ``DPI-1080`` was - also introduced in this release. + .. dbapiattributeextension:: - .. note:: +.. autoproperty:: Connection.current_schema - This attribute is an extension to the DB API definition and is only - available in Oracle Client 18c and higher. + .. dbapiattributeextension:: -.. attribute:: Connection.client_identifier +.. autoproperty:: Connection.db_domain - This write-only attribute sets the CLIENT_IDENTIFIER column in the - V$SESSION view. - - .. note:: - - This attribute is an extension to the DB API definition. - -.. attribute:: Connection.clientinfo - - This write-only attribute sets the CLIENT_INFO column in the V$SESSION - view. - - .. note:: - - This attribute is an extension to the DB API definition. - -.. attribute:: Connection.current_schema - - This read-write attribute sets the current schema attribute for the - session. Setting this value is the same as executing the SQL statement - ``ALTER SESSION SET CURRENT_SCHEMA``. The attribute is set (and verified) on - the next call that does a round trip to the server. The value is placed - before unqualified database objects in SQL statements you then execute. - - .. note:: - - This attribute is an extension to the DB API definition. - -.. attribute:: Connection.db_domain - - This read-only attribute specifies the Oracle Database domain name - associated with the connection. It is the same value returned by the SQL - ``SELECT value FROM V$PARAMETER WHERE NAME = 'db_domain'``. + .. dbapiattributeextension:: .. versionadded:: 2.0.0 - .. note:: - - This attribute is an extension to the DB API definition. - -.. attribute:: Connection.db_name +.. autoproperty:: Connection.db_name - This read-only attribute specifies the Oracle Database name associated with - the connection. It is the same value returned by the SQL - ``SELECT NAME FROM V$DATABASE``. + .. dbapiattributeextension:: .. versionadded:: 2.0.0 - .. note:: - - This attribute is an extension to the DB API definition. - -.. attribute:: Connection.dbop - - This write-only attribute sets the database operation that is to be - monitored. This can be viewed in the DBOP_NAME column of the - V$SQL_MONITOR view. - - .. note:: - - This attribute is an extension to the DB API definition. +.. autoproperty:: Connection.dbop -.. attribute:: Connection.dsn + .. dbapiattributeextension:: - This read-only attribute returns the TNS entry of the database to which a - connection has been established. - - .. note:: - - This attribute is an extension to the DB API definition. - -.. attribute:: Connection.econtext_id - - This write-only attribute specifies the execution context id. This value - can be found as the ECID column in the V$SESSION view and ECONTEXT_ID in - the auditing tables. The maximum length is 64 bytes. - -.. attribute:: Connection.edition - - This read-only attribute gets the session edition and is only available - with Oracle Database 11.2, or later. - - .. note:: - - This attribute is an extension to the DB API definition. - -.. attribute:: Connection.external_name +.. autoproperty:: Connection.dsn - This read-write attribute specifies the external name that is used by the - connection when logging distributed transactions. + .. dbapiattributeextension:: - .. note:: +.. autoproperty:: Connection.econtext_id - This attribute is an extension to the DB API definition. + .. dbapiattributeextension:: -.. attribute:: Connection.handle +.. autoproperty:: Connection.edition - This read-only attribute returns the Oracle Call Interface (OCI) service - context handle for the connection. It is primarily provided to facilitate - testing the creation of a connection using the OCI service context handle. + .. dbapiattributeextension:: - This property is only relevant in the python-oracledb Thick mode. +.. autoproperty:: Connection.external_name - .. note:: + .. dbapiattributeextension:: - This attribute is an extension to the DB API definition. +.. autoproperty:: Connection.handle -.. attribute:: Connection.inputtypehandler + .. dbapiattributeextension:: - This read-write attribute specifies a method called for each value that is - bound to a statement executed on any cursor associated with this - connection. The method signature is handler(cursor, value, arraysize) and - the return value is expected to be a variable object or *None* in which - case a default variable object will be created. If this attribute is - *None*, the default behavior will take place for all values bound to - statements. +.. autoproperty:: Connection.inputtypehandler See :ref:`inputtypehandlers`. - .. note:: - - This attribute is an extension to the DB API definition. + .. dbapiattributeextension:: -.. attribute:: Connection.instance_name +.. autoproperty:: Connection.instance_name - This read-only attribute specifies the Oracle Database instance name - associated with the connection. It is the same value as the SQL expression - ``sys_context('userenv', 'instance_name')``. + .. dbapiattributeextension:: .. versionadded:: 1.4.0 - .. note:: - - This attribute is an extension to the DB API definition. +.. autoproperty:: Connection.internal_name -.. attribute:: Connection.internal_name + .. dbapiattributeextension:: - This read-write attribute specifies the internal name that is used by the - connection when logging distributed transactions. +.. autoproperty:: Connection.ltxid - .. note:: - - This attribute is an extension to the DB API definition. - -.. attribute:: Connection.ltxid + .. dbapiattributeextension:: - This read-only attribute returns the logical transaction id for the - connection. It is used within Oracle Transaction Guard as a means of - ensuring that transactions are not duplicated. See the Oracle documentation - and the provided sample for more information. + .. versionchanged:: 3.0.0 - .. note: + This attribute was added to python-oracledb Thin mode. - This attribute is an extension to the DB API definition. It is only - available with Oracle Database 12.1 or higher. In python-oracledb Thick - mode, it also requires Oracle Client libraries 12.1 or higer. +.. autoproperty:: Connection.max_identifier_length -.. attribute:: Connection.max_identifier_length - - This read-only attribute specifies the maximum database identifier length - in bytes supported by the database to which the connection has been - established. See `Database Object Naming Rules - `__. The value may be - *None*, *30*, or *128*. The value *None* indicates the size cannot be - reliably determined by python-oracledb, which occurs when using Thick mode - with Oracle Client libraries 12.1 (or older) to connect to Oracle Database - 12.2, or later. + .. dbapiattributeextension:: .. versionadded:: 2.5.0 -.. attribute:: Connection.max_open_cursors +.. autoproperty:: Connection.max_open_cursors - This read-only attribute specifies the maximum number of cursors that the - database can have open concurrently. It is the same value returned by the - SQL ``SELECT VALUE FROM V$PARAMETER WHERE NAME = 'open_cursors'``. + .. dbapiattributeextension:: .. versionadded:: 2.0.0 - .. note:: - - This attribute is an extension to the DB API definition. +.. autoproperty:: Connection.module -.. attribute:: Connection.module + .. dbapiattributeextension:: - This write-only attribute sets the MODULE column in the V$SESSION view. - The maximum length for this string is 48 and if you exceed this length you - will get ``ORA-24960``. - - .. note: - - This attribute is an extension to the DB API definition. - - -.. attribute:: Connection.outputtypehandler - - This read-write attribute specifies a method called for each column that is - going to be fetched from any cursor associated with this connection. The - method signature is ``handler(cursor, metadata)`` and the return value is - expected to be a :ref:`variable object` or *None* in which case a - default variable object will be created. If this attribute is *None*, the - default behavior will take place for all columns fetched from cursors. +.. autoproperty:: Connection.outputtypehandler See :ref:`outputtypehandlers`. @@ -886,188 +376,83 @@ Connection Attributes ``handler(cursor, name, default_type, length, precision, scale)`` will still work but is deprecated and will be removed in a future version. - .. note:: - - This attribute is an extension to the DB API definition. + .. dbapiattributeextension:: -.. attribute:: Connection.proxy_user +.. autoproperty:: Connection.proxy_user - This read-only attribute returns the name of the user which was used as a - proxy when creating the connection to the database. + .. dbapiattributeextension:: .. versionadded:: 2.0.0 - .. note:: - - This attribute is an extension to the DB API definition. +.. autoproperty:: Connection.sdu -.. attribute:: Connection.sdu - - This read-only attribute specifies the size of the Session Data Unit (SDU) - that is being used by the connection. The value will be the lesser of the - requested python-oracledb size and the maximum size allowed by the database - network configuration. It is available only in the python-oracledb Thin - mode. + .. dbapiattributeextension:: .. versionadded:: 2.0.0 - .. note:: - - This attribute is an extension to the DB API definition. +.. autoproperty:: Connection.serial_num -.. attribute:: Connection.serial_num - - This read-only attribute specifies the session serial number associated - with the connection. It is the same value returned by the SQL - ``SELECT SERIAL# FROM V$SESSION WHERE SID=SYS_CONTEXT('USERENV', 'SID')``. - It is available only in python-oracledb Thin mode. + .. dbapiattributeextension:: .. versionadded:: 2.5.0 - .. note:: - - This attribute is an extension to the DB API definition. +.. autoproperty:: Connection.service_name - For applications using :ref:`drcp`, the ``serial_num`` attribute may - not contain the current session state until a round-trip is made to the - database after acquiring a session. It is recommended to not use this - attribute if your application uses DRCP but may not perform a - round-trip. - -.. attribute:: Connection.service_name - - This read-only attribute specifies the Oracle Database service name - associated with the connection. This is the same value returned by the SQL - ``SELECT SYS_CONTEXT('USERENV', 'SERVICE_NAME') FROM DUAL``. + .. dbapiattributeextension:: .. versionadded:: 2.0.0 - .. note:: - - This attribute is an extension to the DB API definition. - -.. attribute:: Connection.session_id +.. autoproperty:: Connection.session_id - This read-only attribute specifies the session identifier associated with - the connection. It is the same value returned by the SQL - ``SELECT SYS_CONTEXT('USERENV', 'SID') FROM DUAL``. It is available - only in python-oracledb Thin mode. + .. dbapiattributeextension:: .. versionadded:: 2.5.0 - .. note:: - - This attribute is an extension to the DB API definition. - - For applications using :ref:`drcp`, the ``session_id`` attribute may - not contain the current session state until a round-trip is made to the - database after acquiring a session. It is recommended to not use this - attribute if your application uses DRCP but may not perform a - round-trip. - -.. attribute:: Connection.stmtcachesize - - This read-write attribute specifies the size of the statement cache. This - value can make a significant difference in performance if you have a small - number of statements that you execute repeatedly. - - The default value is *20*. +.. autoproperty:: Connection.stmtcachesize See :ref:`Statement Caching ` for more information. - .. note:: - - This attribute is an extension to the DB API definition. - -.. attribute:: Connection.tag - - This read-write attribute initially contains the actual tag of the session - that was acquired from a pool by :meth:`ConnectionPool.acquire()`. If the - connection was not acquired from a pool or no tagging parameters were - specified (``tag`` and ``matchanytag``) when the connection was acquired - from the pool, this value will be None. If the value is changed, it must - be a string containing name=value pairs like "k1=v1;k2=v2". + .. dbapiattributeextension:: - If this value is not *None* when the connection is released back to the - pool it will be used to retag the session. This value can be overridden in - the call to :meth:`ConnectionPool.release()`. +.. autoproperty:: Connection.tag - .. note:: - - This attribute is an extension to the DB API definition. - -.. attribute:: Connection.thin + .. dbapiattributeextension:: - This read-only attribute returns a boolean indicating if the connection was - established with the python-oracledb Thin mode (*True*) or python-oracledb - Thick mode (*False*). +.. autoproperty:: Connection.thin - .. note:: + See :ref:`vsessconinfo`. - This attribute is an extension to the DB API definition. + .. dbapiattributeextension:: -.. attribute:: Connection.transaction_in_progress +.. autoproperty:: Connection.transaction_in_progress - This read-only attribute specifies whether a transaction is currently in - progress on the database associated with the connection. + .. dbapiattributeextension:: .. versionadded:: 2.0.0 - .. note:: - - This attribute is an extension to the DB API definition. - -.. attribute:: Connection.username +.. autoproperty:: Connection.username This read-only attribute returns the name of the user which established the connection to the database. - .. note:: - - This attribute is an extension to the DB API definition. + .. dbapiattributeextension:: -.. attribute:: Connection.version +.. autoproperty:: Connection.version This read-only attribute returns the version of the database to which a connection has been established. - .. note:: - - This attribute is an extension to the DB API definition. + .. dbapiattributeextension:: .. note:: - If you connect to Oracle Database 18 or higher using Oracle Client - libraries 12.2 or lower you will only receive the base version (such as - 18.0.0.0.0) instead of the full version (such as 18.3.0.0.0). - -.. attribute:: Connection.warning + If you connect to Oracle Database 18 (or higher) in python-oracledb + Thick mode using Oracle Client libraries 12.2 (or lower) you will only + receive the base version (such as 18.0.0.0.0) instead of the full + version (such as 18.3.0.0.0). - This read-only attribute provides an :ref:`oracledb._Error` - object giving information about any database warnings (such as the password - being in the grace period, or the pool being created with a smaller than - requested size due to database resource restrictions) that were generated - during connection establishment or by :meth:`oracledb.create_pool()`. The - attribute will be present if there was a warning, but creation otherwise - completed successfully. The connection will be usable despite the warning. +.. autoproperty:: Connection.warning - For :ref:`standalone connections `, - ``Connection.warning`` will be present for the lifetime of the connection. - - For :ref:`pooled connections `, ``Connection.warning`` will be - cleared when a connection is released to the pool such as with - :meth:`ConnectionPool.release()`. - - In python-oracledb Thick mode, warnings may be generated during pool - creation itself. These warnings will be placed on new connections created - by the pool, provided no warnings were generated by the individual - connection creations, in which case those connection warnings will be - returned. - - If no warning was generated the value *None* is returned. + .. dbapiattributeextension:: .. versionadded:: 2.0.0 - - .. note:: - - This attribute is an extension to the DB API definition. diff --git a/doc/src/api_manual/connection_pool.rst b/doc/src/api_manual/connection_pool.rst index dc8c39d4..13e58123 100644 --- a/doc/src/api_manual/connection_pool.rst +++ b/doc/src/api_manual/connection_pool.rst @@ -4,23 +4,29 @@ API: ConnectionPool Objects *************************** -.. note:: +.. currentmodule:: oracledb - This object is an extension to the DB API. +ConnectionPool Class +==================== -The new ConnectionPool class is synonymous with SessionPool. The SessionPool -class is deprecated in python-oracledb. The preferred function to create pools -is now :meth:`oracledb.create_pool()`. (The name SessionPool came from the -`Oracle Call Interface (OCI) session pool `__. This -implementation is only used in the python-oracledb Thick mode and is not -available in the Thin mode). +.. autoclass:: ConnectionPool -In python-oracledb, the type `pool` will show the class `oracledb.ConnectionPool`. -This only affects the name. + The new ConnectionPool class is synonymous with SessionPool. The + SessionPool class is deprecated in python-oracledb. The preferred function + to create pools is now :meth:`oracledb.create_pool()`. (The name + SessionPool came from the `Oracle Call Interface (OCI) session pool + `__. This + implementation is only used in python-oracledb Thick mode and is not + available in Thin mode). + + .. dbapiobjectextension:: + +In python-oracledb, the type `pool` will show the class +`oracledb.ConnectionPool`. This only affects the name. The following code will continue to work providing backward compatibility with -cx_Oracle: +the obsolete cx_Oracle driver: .. code-block:: python @@ -45,59 +51,13 @@ deprecated in python-oracledb 1.0 and has been deprecated by the function ConnectionPool Methods ====================== -.. method:: ConnectionPool.acquire(user=None, password=None, cclass=None, \ - purity=oracledb.PURITY_DEFAULT, tag=None, matchanytag=False, \ - shardingkey=[], supershardingkey=[]) - - Acquires a connection from the session pool and returns a - :ref:`connection object `. - - If the pool is :ref:`homogeneous `, the ``user`` and - ``password`` parameters cannot be specified. If they are, an exception will - be raised. - - The ``cclass`` parameter, if specified, should be a string corresponding to - the connection class for :ref:`drcp`. - - The ``purity`` parameter is expected to be one of - :data:`~oracledb.PURITY_NEW`, :data:`~oracledb.PURITY_SELF`, or - :data:`~oracledb.PURITY_DEFAULT`. - - The ``tag`` parameter, if specified, is expected to be a string with - name=value pairs like "k1=v1;k2=v2" and will limit the connections that can - be returned from a connection pool unless the ``matchanytag`` parameter is - set to *True*. In that case, connections with the specified tag will be - preferred over others, but if no such connections are available, then a - connection with a different tag may be returned instead. In any case, - untagged connections will always be returned if no connections with the - specified tag are available. Connections are tagged when they are - :meth:`released ` back to the pool. - - The ``shardingkey`` and ``supershardingkey`` parameters, if specified, are - expected to be a sequence of values which will be used to identify the - database shard to connect to. The key values can be strings, numbers, - bytes, or dates. See :ref:`connsharding`. +.. automethod:: ConnectionPool.acquire - When using the :ref:`connection pool cache `, calling - :meth:`oracledb.connect()` with a ``pool_alias`` parameter is the same as - calling ``pool.acquire()``. +.. automethod:: ConnectionPool.close -.. method:: ConnectionPool.close(force=False) +.. automethod:: ConnectionPool.drop - Closes the pool now, rather than when the last reference to it is - released, which makes it unusable for further work. - - If any connections have been acquired and not released back to the pool, - this method will fail unless the ``force`` parameter is set to *True*. - -.. method:: ConnectionPool.drop(connection) - - Drops the connection from the pool which is useful if the connection is no - longer usable (such as when the session is killed). - -.. method:: ConnectionPool.reconfigure([min, max, increment, getmode, \ - timeout, wait_timeout, max_lifetime_session, max_sessions_per_shard, \ - soda_metadata_cache, stmtcachesize, ping_interval]) +.. automethod:: ConnectionPool.reconfigure Reconfigures various parameters of a connection pool. The pool size can be altered with ``reconfigure()`` by passing values for @@ -147,168 +107,55 @@ ConnectionPool Methods See :ref:`Connection Pool Reconfiguration `. -.. method:: ConnectionPool.release(connection, tag=None) - - Releases the connection back to the pool now, rather than whenever __del__ - is called. The connection will be unusable from this point forward; an - Error exception will be raised if any operation is attempted with the - connection. Any cursors or LOBs created by the connection will also be - marked unusable and an Error exception will be raised if any operation is - attempted with them. - - Internally, references to the connection are held by cursor objects, - LOB objects, etc. Once all of these references are released, the connection - itself will be released back to the pool automatically. Either control - references to these related objects carefully or explicitly release - connections back to the pool in order to ensure sufficient resources are - available. - - If the tag is not *None*, it is expected to be a string with name=value - pairs like "k1=v1;k2=v2" and will override the value in the property - :attr:`Connection.tag`. If either :attr:`Connection.tag` or the tag - parameter are not *None*, the connection will be retagged when it is - released back to the pool. +.. automethod:: ConnectionPool.release .. _connpoolattr: ConnectionPool Attributes ========================= -.. attribute:: ConnectionPool.busy - - This read-only attribute returns the number of connections currently - acquired. +.. autoproperty:: ConnectionPool.busy -.. attribute:: ConnectionPool.dsn +.. autoproperty:: ConnectionPool.dsn - This read-only attribute returns the TNS entry of the database to which a - connection has been established. +.. autoproperty:: ConnectionPool.getmode -.. attribute:: ConnectionPool.getmode +.. autoproperty:: ConnectionPool.homogeneous - This read-write attribute determines how connections are returned from the - pool. If :data:`~oracledb.POOL_GETMODE_FORCEGET` is specified, a new - connection will be returned even if there are no free connections in the - pool. :data:`~oracledb.POOL_GETMODE_NOWAIT` will raise an exception if - there are no free connections are available in the pool. If - :data:`~oracledb.POOL_GETMODE_WAIT` is specified and there are no free - connections in the pool, the caller will wait until a free connection is - available. :data:`~oracledb.POOL_GETMODE_TIMEDWAIT` uses the value of - :data:`~ConnectionPool.wait_timeout` to determine how long the caller - should wait for a connection to become available before returning an error. +.. autoproperty:: ConnectionPool.increment -.. attribute:: ConnectionPool.homogeneous +.. autoproperty:: ConnectionPool.max - This read-only boolean attribute indicates whether the pool is considered - :ref:`homogeneous ` or not. If the pool is not homogeneous, - different authentication can be used for each connection acquired from the - pool. +.. autoproperty:: ConnectionPool.max_lifetime_session -.. attribute:: ConnectionPool.increment + .. versionchanged:: 3.0.0 - This read-only attribute returns the number of connections that will be - established when additional connections need to be created. + This attribute was added to python-oracledb Thin mode. -.. attribute:: ConnectionPool.max +.. autoproperty:: ConnectionPool.max_sessions_per_shard - This read-only attribute returns the maximum number of connections that the - pool can control. +.. autoproperty:: ConnectionPool.min -.. attribute:: ConnectionPool.max_lifetime_session +.. autoproperty:: ConnectionPool.name - This read-write attribute is the maximum length of time (in seconds) that a - pooled connection may exist since first being created. A value of *0* means - there is no limit. Connections become candidates for termination when they - are acquired or released back to the pool, and have existed for longer than - ``max_lifetime_session`` seconds. Connections that are in active use will - not be closed. In python-oracledb Thick mode, Oracle Client libraries 12.1 - or later must be used and, prior to Oracle Client 21, cleanup only occurs - when the pool is accessed. +.. autoproperty:: ConnectionPool.opened -.. attribute:: ConnectionPool.max_sessions_per_shard - - This read-write attribute returns the number of sessions that can be - created per shard in the pool. Setting this attribute greater than zero - specifies the maximum number of sessions in the pool that can be used for - any given shard in a sharded database. This lets connections in the pool be - balanced across the shards. A value of *0* will not set any maximum number - of sessions for each shard. This attribute is only available in Oracle - Client 18.3 and higher. - -.. attribute:: ConnectionPool.min - - This read-only attribute returns the number of connections with which the - connection pool was created and the minimum number of connections that will - be controlled by the connection pool. - -.. attribute:: ConnectionPool.name - - This read-only attribute returns the name assigned to the pool by Oracle. - -.. attribute:: ConnectionPool.opened - - This read-only attribute returns the number of connections currently opened - by the pool. - -.. attribute:: ConnectionPool.ping_interval - - This read-write integer attribute specifies the pool ping interval in - seconds. When a connection is acquired from the pool, a check is first made - to see how long it has been since the connection was put into the pool. If - this idle time exceeds ``ping_interval``, then a :ref:`round-trip - ` ping to the database is performed. If the connection is - unusable, it is discarded and a different connection is selected to be - returned by :meth:`ConnectionPool.acquire()`. Setting ``ping_interval`` to - a negative value disables pinging. Setting it to *0* forces a ping for - every :meth:`ConnectionPool.acquire()` and is not recommended. +.. autoproperty:: ConnectionPool.ping_interval Prior to cx_Oracle 8.2, the ping interval was fixed at *60* seconds. -.. attribute:: ConnectionPool.soda_metadata_cache - - This read-write boolean attribute returns whether the SODA metadata cache - is enabled or not. Enabling the cache significantly improves the - performance of methods :meth:`SodaDatabase.createCollection()` (when not - specifying a value for the ``metadata`` parameter) and - :meth:`SodaDatabase.openCollection()`. Note that the cache can become out - of date if changes to the metadata of cached collections are made - externally. +.. autoproperty:: ConnectionPool.soda_metadata_cache -.. attribute:: ConnectionPool.stmtcachesize - - This read-write attribute specifies the size of the statement cache that - will be used for connections obtained from the pool. Once a connection is - created, that connection’s statement cache size can only be changed by - setting the ``stmtcachesize`` attribute on the connection itself. +.. autoproperty:: ConnectionPool.stmtcachesize See :ref:`Statement Caching ` for more information. -.. attribute:: ConnectionPool.thin - - This attribute returns a boolean which indicates the python-oracledb mode - in which the pool was created. If the value of this attribute is *True*, it - indicates that the pool was created in the python-oracledb Thin mode. If - the value of this attribute is *False*, it indicates that the pool was - created in the python-oracledb Thick mode. - -.. attribute:: ConnectionPool.timeout - - This read-write attribute specifies the time (in seconds) after which idle - connections will be terminated in order to maintain an optimum number of - open connections. A value of *0* means that no idle connections are - terminated. Note that in python-oracledb Thick mode with older Oracle - Client Libraries, the termination only occurs when the pool is accessed. - +.. autoproperty:: ConnectionPool.thin -.. attribute:: ConnectionPool.username + See :ref:`vsessconinfo`. - This read-only attribute returns the name of the user which established the - connection to the database. +.. autoproperty:: ConnectionPool.timeout -.. attribute:: ConnectionPool.wait_timeout +.. autoproperty:: ConnectionPool.username - This read-write attribute specifies the time (in milliseconds) that the - caller should wait for a connection to become available in the pool before - returning with an error. This value is only used if the ``getmode`` - parameter to :meth:`oracledb.create_pool()` was the value - :data:`oracledb.POOL_GETMODE_TIMEDWAIT`. +.. autoproperty:: ConnectionPool.wait_timeout diff --git a/doc/src/api_manual/cursor.rst b/doc/src/api_manual/cursor.rst index a2b4d14d..ac8669a2 100644 --- a/doc/src/api_manual/cursor.rst +++ b/doc/src/api_manual/cursor.rst @@ -4,48 +4,32 @@ API: Cursor Objects ******************* -A cursor object can be created with :meth:`Connection.cursor()`. +.. currentmodule:: oracledb -Cursor Methods -============== - -.. method:: Cursor.__enter__() - - The entry point for the cursor as a context manager. It returns itself. - - .. note:: - - This method is an extension to the DB API definition. +Cursor Class +============ +.. autoclass:: Cursor -.. method:: Cursor.__exit__() + A cursor object should be created with :meth:`Connection.cursor()`. - The exit point for the cursor as a context manager. It closes the cursor. +Cursor Methods +============== - .. note:: +.. automethod:: Cursor.__enter__ - This method is an extension to the DB API definition. + .. dbapimethodextension:: -.. method:: Cursor.__iter__() +.. automethod:: Cursor.__exit__ - Returns the cursor itself to be used as an iterator. + .. dbapimethodextension:: - .. note:: +.. automethod:: Cursor.__iter__ - This method is an extension to the DB API definition but it is - mentioned in PEP 249 as an optional extension. + .. dbapimethodextension:: + It is mentioned in PEP 249 as an optional extension. -.. method:: Cursor.arrayvar(typ, value, [size]) - - Creates an array variable associated with the cursor of the given type and - size and returns a :ref:`variable object `. The value is either an - integer specifying the number of elements to allocate or it is a list and - the number of elements allocated is drawn from the size of the list. If the - value is a list, the variable is also set with the contents of the list. If - the size is not specified and the type is a string or binary, 4000 bytes - is allocated. This is needed for passing arrays to PL/SQL (in cases where - the list might be empty and the type cannot be determined automatically) or - returning arrays from PL/SQL. +.. automethod:: Cursor.arrayvar Array variables can only be used for PL/SQL associative arrays with contiguous keys. For PL/SQL associative arrays with sparsely populated keys @@ -53,261 +37,93 @@ Cursor Methods `example `__ needs to be used. - .. note:: - - The DB API definition does not define this method. + .. dbapimethodextension:: -.. method:: Cursor.bindnames() +.. automethod:: Cursor.bindnames - Returns the list of bind variable names bound to the statement. Note that a - statement must have been prepared first. + .. dbapimethodextension:: - .. note:: - - The DB API definition does not define this method. - -.. method:: Cursor.callfunc(name, return_type, parameters=[], \ - keyword_parameters={}) - - Calls a PL/SQL function with the given name and returns its value. - - The ``return_type`` parameter for :meth:`~Cursor.callfunc()` is expected to - be a Python type, one of the :ref:`oracledb types ` or an - :ref:`Object Type `. - - The sequence of parameters must contain one entry for each parameter that - the PL/SQL function expects. Any keyword parameters will be included after - the positional parameters. - - Use :meth:`Cursor.var()` to define any OUT or IN OUT parameters, if - necessary. +.. automethod:: Cursor.callfunc See :ref:`plsqlfunc` for examples. - For consistency and compliance with the PEP 8 naming style, the parameter - ``keywordParameters`` was renamed to ``keyword_parameters``. The old name - will continue to work for a period of time. - - .. note:: - - The DB API definition does not define this method. + .. dbapimethodextension:: .. note:: In line with the Python DB API, it is not recommended to call - :meth:`Cursor.setinputsizes()` prior to calling - :meth:`~Cursor.callfunc()`. Use :meth:`Cursor.var()` instead. In - existing code that calls :meth:`~Cursor.setinputsizes()`, the first - item in the :meth:`~Cursor.setinputsizes()` parameter list refers to - the return value of the PL/SQL function. - -.. method:: Cursor.callproc(name, parameters=[], keyword_parameters={}) - - Calls a PL/SQL procedure with the given name. - - The sequence of parameters must contain one entry for each parameter that - the procedure expects. The result of the call is a modified copy of the - input sequence. Input parameters are left untouched; output and - input/output parameters are replaced with possibly new values. Keyword - parameters will be included after the positional parameters and are not - returned as part of the output sequence. - - Use :meth:`Cursor.var()` to define any OUT or IN OUT parameters if - necessary. + :meth:`setinputsizes()` prior to calling this function. Use + :meth:`var()` instead. In existing code that calls + :meth:`setinputsizes()`, the first item in the :meth:`setinputsizes()` + parameter list refers to the return value of the PL/SQL function. - No query result set is returned by :meth:`~Cursor.callproc()`. Instead, use - :ref:`REF CURSOR ` parameters or :ref:`Implicit Results - `. +.. automethod:: Cursor.callproc See :ref:`plsqlproc` for an example. - For consistency and compliance with the PEP 8 naming style, the parameter - ``keywordParameters`` was renamed to ``keyword_parameters``. The old name - will continue to work for a period of time. - .. note:: The DB API definition does not allow for keyword parameters. -.. method:: Cursor.close() - - Closes the cursor now, rather than whenever __del__ is called. The cursor - will be unusable from this point forward; an Error exception will be raised - if any operation is attempted with the cursor. - -.. method:: Cursor.execute(statement, parameters=[], ** keyword_parameters) - - Executes a statement against the database. See :ref:`sqlexecution`. +.. automethod:: Cursor.close - Parameters may be passed as a dictionary or sequence or as keyword - parameters. If the parameters are a dictionary, the values will be bound by - name and if the parameters are a sequence the values will be bound by - position. Note that if the values are bound by position, the order of the - variables is from left to right as they are encountered in the statement - and SQL statements are processed differently than PL/SQL statements. For - this reason, it is generally recommended to bind parameters by name instead - of by position. +.. automethod:: Cursor.execute - Parameters passed as a dictionary are name and value pairs. The name maps - to the bind variable name used by the statement and the value maps to the - Python value you wish bound to that bind variable. + .. versionchanged:: 3.4.0 - A reference to the statement will be retained by the cursor. If *None* or - the same string object is passed in again, the cursor will execute that - statement again without performing a prepare or rebinding and redefining. - This is most effective for algorithms where the same statement is used, but - different parameters are bound to it (many times). Note that parameters - that are not passed in during subsequent executions will retain the value - passed in during the last execution that contained them. + The ``fetch_lobs`` and ``fetch_decimals`` parameters were added. - For maximum efficiency when reusing a statement, it is best to use the - :meth:`Cursor.setinputsizes()` method to specify the parameter types and - sizes ahead of time; in particular, *None* is assumed to be a string of - length 1 so any values that are later bound as numbers or dates will raise - a TypeError exception. + .. versionchanged:: 3.3.0 - If the statement is a query, the cursor is returned as a convenience to the - caller (so it can be used directly as an iterator over the rows in the - cursor); otherwise, *None* is returned. + The ``suspend_on_success`` parameter was added. .. note:: The DB API definition does not define the return value of this method. -.. method:: Cursor.executemany(statement, parameters, batcherrors=False, \ - arraydmlrowcounts=False) - - Executes a SQL statement once using all bind value mappings or sequences - found in the sequence parameters. This can be used to insert, update, or - delete multiple rows in a table with a single python-oracledb call. It can - also invoke a PL/SQL procedure multiple times. See :ref:`batchstmnt`. - - The ``statement`` parameter is managed in the same way as the - :meth:`Cursor.execute()` method manages it. - - The ``parameters`` parameter can be a list of tuples, where each tuple item - maps to one bind variable placeholder in ``statement``. It can also be a - list of dictionaries, where the keys match the bind variable placeholder - names in ``statement``. If there are no bind values, or values have - previously been bound, the ``parameters`` value can be an integer - specifying the number of iterations. +.. automethod:: Cursor.executemany - In python-oracledb Thick mode, if the size of the buffers allocated for any - of the parameters exceeds 2 GB, you will receive the error ``DPI-1015: - array size of is too large``. If you receive this error, decrease the - number of rows being inserted. + .. versionchanged:: 3.4.0 - When *True*, the ``batcherrors`` parameter enables batch error support - within Oracle Database and ensures that the call succeeds even if an - exception takes place in one or more of the sequence of bind values. The - errors can then be retrieved using :meth:`Cursor.getbatcherrors()`. + The ``batch_size`` parameter was added. - When *True*, the ``arraydmlrowcounts`` parameter enables DML row counts to - be retrieved from Oracle after the method has completed. The row counts can - then be retrieved using :meth:`Cursor.getarraydmlrowcounts()`. + .. versionchanged:: 3.3.0 - Both the ``batcherrors`` parameter and the ``arraydmlrowcounts`` parameter - can only be *True* when executing an insert, update, delete, or merge - statement; in all other cases an error will be raised. + Added support for passing data frames in the ``parameters`` parameter. + The ``suspend_on_success`` parameter was added. - For maximum efficiency, it is best to use the - :meth:`Cursor.setinputsizes()` method to specify the bind value types and - sizes. In particular, if the type is not explicitly specified, the value - *None* is assumed to be a string of length 1 so any values that are later - bound as numbers or dates will raise a TypeError exception. - -.. method:: Cursor.fetchall() - - Fetches all (remaining) rows of a query result, returning them as a list of - tuples. An empty list is returned if no more rows are available. Note that - the cursor's arraysize attribute can affect the performance of this - operation, as internally reads from the database are done in batches - corresponding to the arraysize. - - An exception is raised if the previous call to :meth:`Cursor.execute()` - did not produce any result set or no call was issued yet. +.. automethod:: Cursor.fetchall See :ref:`fetching` for an example. -.. method:: Cursor.fetchmany(size=cursor.arraysize) - - Fetches the next set of rows of a query result, returning a list of tuples. - An empty list is returned if no more rows are available. Note that the - cursor's arraysize attribute can affect the performance of this operation. - - The number of rows to fetch is specified by the parameter. If it is not - given, the cursor's ``arraysize`` attribute determines the number of rows - to be fetched. If the number of rows available to be fetched is fewer than - the amount requested, fewer rows will be returned. - - An exception is raised if the previous call to :meth:`Cursor.execute()` - did not produce any result set or no call was issued yet. +.. automethod:: Cursor.fetchmany See :ref:`fetching` for an example. -.. method:: Cursor.fetchone() - - Fetches the next row of a query result set, returning a single tuple or - *None* when no more data is available. - - An exception is raised if the previous call to :meth:`Cursor.execute()` - did not produce any result set or no call was issued yet. +.. automethod:: Cursor.fetchone See :ref:`fetching` for an example. -.. method:: Cursor.getarraydmlrowcounts() - - Retrieves the DML row counts after a call to :meth:`Cursor.executemany()` - with ``arraydmlrowcounts`` enabled. This will return a list of integers - corresponding to the number of rows affected by the DML statement for each - element of the array passed to :meth:`Cursor.executemany()`. - - .. note:: +.. automethod:: Cursor.getarraydmlrowcounts - The DB API definition does not define this method and it is only - available for Oracle 12.1 and later. + .. dbapimethodextension:: -.. method:: Cursor.getbatcherrors() - - Retrieves the exceptions that took place after a call to - :meth:`Cursor.executemany()` with ``batcherrors`` enabled. This will return a - list of Error objects, one error for each iteration that failed. The offset - can be determined by looking at the offset attribute of the error object. - - .. note:: +.. automethod:: Cursor.getbatcherrors - The DB API definition does not define this method. + .. dbapimethodextension:: -.. method:: Cursor.getimplicitresults() +.. automethod:: Cursor.getimplicitresults - Returns a list of cursors which correspond to implicit results made - available from a PL/SQL block or procedure without the use of OUT ref - cursor parameters. The PL/SQL block or procedure opens the cursors and - marks them for return to the client using the procedure - dbms_sql.return_result. In python-oracledb Thick mode, closing the parent - cursor will result in the automatic closure of the implicit result set - cursors. See :ref:`implicitresults`. + .. dbapimethodextension:: - This method is only available for Oracle Database 12.1 (or later). For - python-oracledb :ref:`Thick ` mode, Oracle Client 12.1 (or - later) is additionally required. + It is most like the DB API method nextset(), but unlike that method + (which requires that the next result set overwrite the current result + set), this method returns cursors which can be fetched independently of + each other. - .. note:: - - The DB API definition does not define this method. It is most like the - DB API method nextset(), but unlike that method (which requires that - the next result set overwrite the current result set), this method - returns cursors which can be fetched independently of each other. - -.. method:: Cursor.parse(statement) - - This can be used to parse a statement without actually executing it - (parsing step is done automatically by Oracle when a statement is - :meth:`executed `). - - .. note:: +.. automethod:: Cursor.parse - The DB API definition does not define this method. + .. dbapimethodextension:: .. note:: @@ -315,231 +131,54 @@ Cursor Methods immediately and an implied commit takes place. You can also parse PL/SQL statements. -.. method:: Cursor.prepare(statement, tag, cache_statement=True) - - This can be used before a call to :meth:`Cursor.execute()` or - :meth:`Cursor.executemany()` to define the statement that will be - executed. When this is done, the prepare phase will not be performed when - the call to :meth:`Cursor.execute()` or :meth:`Cursor.executemany()` is - made with *None* or the same string object as the statement. - - If the ``tag`` parameter is specified and the ``cache_statement`` parameter - is *True*, the statement will be returned to the statement cache with the - given tag. - - If the ``cache_statement`` parameter is *False*, the statement will be - removed from the statement cache (if it was found there) or will simply not - be cached. +.. automethod:: Cursor.prepare See :ref:`Statement Caching ` for more information. - .. note:: + .. dbapimethodextension:: - The DB API definition does not define this method. +.. automethod:: Cursor.scroll -.. method:: Cursor.scroll(value=0, mode="relative") + .. dbapimethodextension:: + It is mentioned in PEP 249 as an optional extension. - Scrolls the cursor in the result set to a new position according to the - mode. - - If mode is *relative* (the default value), the value is taken as an offset - to the current position in the result set. If set to *absolute*, value - states an absolute target position. If set to *first*, the cursor is - positioned at the first row and if set to *last*, the cursor is set to the - last row in the result set. - - An error is raised if the mode is *relative* or *absolute* and the scroll - operation would position the cursor outside of the result set. +.. automethod:: Cursor.setinputsizes .. note:: - This method is an extension to the DB API definition but it is - mentioned in PEP 249 as an optional extension. - -.. method:: Cursor.setinputsizes(*args, **keywordArgs) + This function should not be used for bind variables passed to + :meth:`callfunc()` or :meth:`callproc()`. Instead, use :meth:`var()`. - This can be used before calls to :meth:`Cursor.execute()` or - :meth:`Cursor.executemany()` to predefine memory areas used for - :ref:`bind variables `. Each parameter should be a type object - corresponding to the data that will be used for a bind variable placeholder - in the SQL or PL/SQL statement. Alternatively, it can be an integer - specifying the maximum length of a string bind variable value. + If this function is used with :meth:`callfunc()`, the first parameter + in the list refers to the return value of the PL/SQL function. - Use keyword parameters when :ref:`binding by name `. Use - positional parameters when :ref:`binding by position `. The - parameter value can be *None* to indicate that python-oracledb should - determine the required space from the data value provided. +.. automethod:: Cursor.setoutputsize - The parameters or keyword names correspond to the bind variable - placeholders used in the SQL or PL/SQL statement. Note this means that for - use with :meth:`Cursor.executemany()` it does not correspond to the number - of bind value mappings or sequences being passed. - - When repeated calls to :meth:`Cursor.execute()` or - :meth:`Cursor.executemany()` are made binding different string data - lengths, using :meth:`~Cursor.setinputsizes()` can help reduce the - database's SQL "version count" for the statement. See :ref:`Reducing the - SQL Version Count `. - - .. note:: - - :meth:`Cursor.setinputsizes()` should not be used for bind variables - passed to :meth:`Cursor.callfunc()` or - :meth:`Cursor.callproc()`. Instead, use :meth:`Cursor.var()`. - - If :meth:`Cursor.setinputsizes()` is used with - :meth:`Cursor.callfunc()`, the first parameter in the list refers to - the return value of the PL/SQL function. - -.. method:: Cursor.setoutputsize(size, [column]) - - This method does nothing and is retained solely for compatibility with the - DB API. Python-oracledb automatically allocates as much space as needed to - fetch LONG and LONG RAW columns, and also to fetch CLOB as string and BLOB - as bytes. - -.. method:: Cursor.var(typ, [size, arraysize, inconverter, outconverter, \ - typename, encoding_errors, bypass_decode, convert_nulls]) - - Creates a :ref:`variable object ` with the specified - characteristics. This method can be used for binding to PL/SQL IN and OUT - parameters where the length or type cannot be determined automatically from - the Python variable being bound. It can also be used in :ref:`input - ` and :ref:`output ` type handlers. - - The ``typ`` parameter specifies the type of data that should be stored in the - variable. This should be one of the :ref:`database type constants - `, :ref:`DB API constants `, an object type returned from - the method :meth:`Connection.gettype()` or one of the following Python - types: - - .. list-table-with-summary:: - :header-rows: 1 - :class: wy-table-responsive - :align: center - :summary: The first column is the Python Type. The second column is the corresponding Database Type. - - * - Python Type - - Database Type - * - bool - - :attr:`oracledb.DB_TYPE_BOOLEAN` - * - bytes - - :attr:`oracledb.DB_TYPE_RAW` - * - datetime.date - - :attr:`oracledb.DB_TYPE_DATE` - * - datetime.datetime - - :attr:`oracledb.DB_TYPE_DATE` - * - datetime.timedelta - - :attr:`oracledb.DB_TYPE_INTERVAL_DS` - * - decimal.Decimal - - :attr:`oracledb.DB_TYPE_NUMBER` - * - float - - :attr:`oracledb.DB_TYPE_NUMBER` - * - int - - :attr:`oracledb.DB_TYPE_NUMBER` - * - str - - :attr:`oracledb.DB_TYPE_VARCHAR` - - The ``size`` parameter specifies the length of string and raw variables and is - ignored in all other cases. If not specified for string and raw variables, - the value *4000* is used. - - The ``arraysize`` parameter specifies the number of elements the variable will - have. If not specified the bind array size (usually *1*) is used. When a - variable is created in an output type handler this parameter should be set - to the cursor's array size. - - The ``inconverter`` and ``outconverter`` parameters specify methods used for - converting values to/from the database. More information can be found in - the section on :ref:`variable objects`. - - The ``typename`` parameter specifies the name of a SQL object type and must be - specified when using type :data:`oracledb.OBJECT` unless the type object - was passed directly as the first parameter. - - The ``encoding_errors`` parameter specifies what should happen when decoding - byte strings fetched from the database into strings. It should be one of - the values noted in the builtin - `decode `__ - function. - - The ``bypass_decode`` parameter, if specified, should be passed as a - boolean value. Passing a *True* value causes values of database types - :data:`~oracledb.DB_TYPE_VARCHAR`, :data:`~oracledb.DB_TYPE_CHAR`, - :data:`~oracledb.DB_TYPE_NVARCHAR`, :data:`~oracledb.DB_TYPE_NCHAR` and - :data:`~oracledb.DB_TYPE_LONG` to be returned as bytes instead of str, - meaning that python-oracledb does not do any decoding. See :ref:`Fetching raw - data ` for more information. - - The ``convert_nulls`` parameter, if specified, should be passed as a boolean - value. Passing the value *True* causes the ``outconverter`` to be called - when a null value is fetched from the database; otherwise, the - ``outconverter`` is only called when non-null values are fetched from the - database. - - For consistency and compliance with the PEP 8 naming style, the parameter - ``encodingErrors`` was renamed to ``encoding_errors``. The old name will - continue to work as a keyword parameter for a period of time. +.. automethod:: Cursor.var .. versionchanged:: 1.4.0 The ``convert_nulls`` parameter was added. - .. note:: - - The DB API definition does not define this method. + .. dbapimethodextension:: Cursor Attributes ================= -.. attribute:: Cursor.arraysize - - This read-write attribute can be used to tune the number of rows internally - fetched and buffered by internal calls to the database when fetching rows - from SELECT statements and REF CURSORS. The value can drastically affect - the performance of a query since it directly affects the number of network - round trips between Python and the database. For methods like - :meth:`Cursor.fetchone()` and :meth:`Cursor.fetchall()` it does not change - how many rows are returned to the application. For - :meth:`Cursor.fetchmany()` it is the default number of rows to fetch. - - The attribute is only used for tuning row and SODA document fetches from - the database. It does not affect data inserts. - - Due to the performance benefits, the default ``Cursor.arraysize`` is *100* - instead of the *1* that the Python DB API recommends. +.. autoproperty:: Cursor.arraysize See :ref:`Tuning Fetch Performance ` for more information. -.. attribute:: Cursor.bindvars - - This read-only attribute provides the bind variables used for the last - statement that was executed on the cursor. The value will be either a list - or a dictionary, depending on whether binding was done by position or - name. Care should be taken when referencing this attribute. In particular, - elements should not be removed or replaced. - - .. note:: - - The DB API definition does not define this attribute. - -.. attribute:: Cursor.connection +.. autoproperty:: Cursor.bindvars - This read-only attribute returns a reference to the connection object on - which the cursor was created. + .. dbapiattributeextension:: - .. note:: - - This attribute is an extension to the DB API definition but it is - mentioned in PEP 249 as an optional extension. +.. autoproperty:: Cursor.connection -.. attribute:: Cursor.description + .. dbapimethodextension:: + It is mentioned in PEP 249 as an optional extension. - This read-only attribute contains information about the columns used in a - query. It is a sequence of :ref:`FetchInfo ` objects, one per - column. This attribute will be *None* for statements that are not SELECT or - WITH statements, or if the cursor has not had :meth:`Cursor.execute()` - invoked yet. +.. autoproperty:: Cursor.description .. versionchanged:: 1.4.0 @@ -547,139 +186,56 @@ Cursor Attributes tuples contained information describing one query column: "(name, type, display_size, internal_size, precision, scale, null_ok)". -.. attribute:: Cursor.fetchvars +.. autoproperty:: Cursor.fetchvars - This read-only attribute specifies the list of variables created for the - last query that was executed on the cursor. Care should be taken when - referencing this attribute. In particular, elements should not be removed - or replaced. - - .. note:: + .. dbapiattributeextension:: - The DB API definition does not define this attribute. - -.. attribute:: Cursor.inputtypehandler - - This read-write attribute specifies a method called for each value that is - bound to a statement executed on the cursor and overrides the attribute - with the same name on the connection if specified. The method signature is - handler(cursor, value, arraysize) and the return value is expected to be a - variable object or *None* in which case a default variable object will be - created. If this attribute is *None*, the default behavior will take place - for all values bound to the statements. +.. autoproperty:: Cursor.inputtypehandler See :ref:`inputtypehandlers`. - .. note:: + .. dbapiattributeextension:: - This attribute is an extension to the DB API definition. +.. autoproperty:: Cursor.lastrowid -.. attribute:: Cursor.lastrowid - - This read-only attribute returns the rowid of the last row modified by the - cursor. If no row was modified by the last operation performed on the - cursor, the value *None* is returned. - -.. attribute:: Cursor.outputtypehandler - - This read-write attribute specifies a method called for each column that is - to be fetched from this cursor. The method signature is - handler(cursor, metadata) and the return value is expected to be a - :ref:`variable object ` or *None* in which case a default variable - object will be created. If this attribute is *None*, then the default - behavior will take place for all columns fetched from this cursor. +.. autoproperty:: Cursor.outputtypehandler See :ref:`outputtypehandlers`. + .. dbapiattributeextension:: + .. versionchanged:: 1.4.0 The method signature was changed. The previous signature handler(cursor, name, default_type, length, precision, scale) will still work but is deprecated and will be removed in a future version. - .. note:: - - This attribute is an extension to the DB API definition. - -.. attribute:: Cursor.prefetchrows - - This read-write attribute can be used to tune the number of rows that the - Oracle Client library fetches when a SELECT statement is executed. This - value can reduce the number of round-trips to the database that are - required to fetch rows but at the cost of additional memory. Setting this - value to *0* can be useful when the timing of fetches must be explicitly - controlled. - - The attribute is only used for tuning row fetches from the database. It - does not affect data inserts. - - Queries that return LOBs and similar types will never prefetch rows, so the - ``prefetchrows`` value is ignored in those cases. +.. autoproperty:: Cursor.prefetchrows See :ref:`Tuning Fetch Performance ` for more information. - .. note:: - - The DB API definition does not define this method. - -.. attribute:: Cursor.rowcount - - This read-only attribute specifies the number of rows that have currently - been fetched from the cursor (for select statements) or that have been - affected by the operation (for insert, update, delete, and merge - statements). For all other statements the value is always *0*. If the - cursor or connection is closed, the value returned is *-1*. + .. dbapimethodextension:: -.. attribute:: Cursor.rowfactory +.. autoproperty:: Cursor.rowcount - This read-write attribute specifies a method to call for each row that is - retrieved from the database. Ordinarily, a tuple is returned for each row - but if this attribute is set, the method is called with the tuple that - would normally be returned, and the result of the method is returned - instead. +.. autoproperty:: Cursor.rowfactory See :ref:`rowfactories`. - .. note:: - - The DB API definition does not define this attribute. + .. dbapiattributeextension:: -.. attribute:: Cursor.scrollable +.. autoproperty:: Cursor.scrollable - This read-write boolean attribute specifies whether the cursor can be - scrolled or not. By default, cursors are not scrollable, as the server - resources and response times are greater than nonscrollable cursors. This - attribute is checked and the corresponding mode set in Oracle when calling - the method :meth:`Cursor.execute()`. - - .. note:: + .. dbapiattributeextension:: - The DB API definition does not define this attribute. +.. autoproperty:: Cursor.statement -.. attribute:: Cursor.statement - - This read-only attribute provides the string object that was previously - prepared with :meth:`Cursor.prepare()` or executed with - :meth:`Cursor.execute()`. - - .. note:: + .. dbapiattributeextension:: - The DB API definition does not define this attribute. - -.. attribute:: Cursor.warning - - This read-only attribute provides an :ref:`oracledb._Error` - object giving information about any database warnings (such as PL/SQL - compilation warnings) that were generated during the last call to - :meth:`Cursor.execute()` or :meth:`Cursor.executemany()`. This value is - automatically cleared on the next call to :meth:`Cursor.execute()` or - :meth:`Cursor.executemany()`. If no warning was generated the value - *None* is returned. +.. autoproperty:: Cursor.warning See :ref:`plsqlwarning` for more information. - .. versionadded:: 2.0.0 - - .. note:: + .. dbapiattributeextension:: - The DB API definition does not define this attribute. + .. versionadded:: 2.0.0 diff --git a/doc/src/api_manual/dataframe.rst b/doc/src/api_manual/dataframe.rst index 4ba8b647..d981bf1e 100644 --- a/doc/src/api_manual/dataframe.rst +++ b/doc/src/api_manual/dataframe.rst @@ -1,8 +1,10 @@ .. _oracledataframe: -**************** -API: Data Frames -**************** +********************** +API: DataFrame Objects +********************** + +.. currentmodule:: oracledb Python-oracledb can fetch directly to data frames that expose an Apache Arrow PyCapsule Interface. These can be used by many numerical and data analysis @@ -11,218 +13,64 @@ libraries. See :ref:`dataframeformat` for more information, including the type mapping from Oracle Database types to Arrow data types. -.. note:: - - The data frame support in python-oracledb 3.0.0 is a pre-release and may - change in the next version. - .. _oracledataframeobj: -OracleDataFrame Objects -======================= - -OracleDataFrame objects are returned from the methods -:meth:`Connection.fetch_df_all()` and :meth:`Connection.fetch_df_batches()`. - -Each column in OracleDataFrame exposes an `Apache Arrow PyCapsule -`__ -interface, giving access to the underlying Arrow array. - -The OracleDataFrame object is an extension to the DB API. - -.. versionadded:: 3.0.0 - -.. _oracledataframemeth: - -OracleDataFrame Methods ------------------------ - -The object implements the Python DataFrame Interchange Protocol `DataFrame API -Interface `__ - -.. method:: OracleDataFrame.column_arrays() - - Returns a list of :ref:`OracleArrowArray ` objects, - each containing a select list column. - - This is an extension to the DataFrame Interchange Protocol. - -.. method:: OracleDataFrame.column_names() - - Returns a list of the column names in the data frame. +DataFrame Class +=============== -.. method:: OracleDataFrame.get_chunks(n_chunks) +.. autoclass:: DataFrame - Returns itself, since python-oracledb only uses one chunk. + A DataFrame object is returned by the methods + :meth:`Connection.fetch_df_all()`, + :meth:`Connection.fetch_df_batches()`, + :meth:`AsyncConnection.fetch_df_all()`, or + :meth:`AsyncConnection.fetch_df_batches()`. -.. method:: OracleDataFrame.get_column(i) + Each column in a DataFrame exposes an `Apache Arrow PyCapsule + `__ interface, giving access to the underlying + Apache Arrow array. - Returns an :ref:`OracleColumn ` object for the column - at the given index ``i``. + .. dbapiobjectextension:: -.. method:: OracleDataFrame.get_column_by_name(name) + .. versionchanged:: 3.3.0 - Returns an :ref:`OracleColumn ` object for the column - with the given name ``name``. + Removed the prefix "Oracle" from the class name. -.. method:: OracleDataFrame.get_columns() + .. versionadded:: 3.0.0 - Returns a list of :ref:`OracleColumn ` objects, one - object for each column in the data frame. - -.. method:: OracleDataFrame.num_chunks() - - Return the number of chunks the data frame consists of. - - This always returns 1. - -.. method:: OracleDataFrame.num_columns() +.. _oracledataframemeth: - Returns the number of columns in the data frame. +DataFrame Methods +----------------- -.. method:: OracleDataFrame.num_rows() +.. automethod:: DataFrame.column_arrays - Returns the number of rows in the data frame. +.. automethod:: DataFrame.column_names -.. _oracledataframeattr: +.. automethod:: DataFrame.get_column -OracleDataFrame Attributes --------------------------- +.. automethod:: DataFrame.get_column_by_name -.. attribute:: OracleDataFrame.metadata +.. automethod:: DataFrame.num_columns - This read-only attribute returns the metadata for the data frame as a - dictionary with keys ``num_columns``, ``num_rows``, and ``num_chunks``, - showing the number of columns, rows, and chunks, respectively. The number - of chunks is always 1 in python-oracledb. +.. automethod:: DataFrame.num_rows .. _oraclearrowarrayobj: -OracleArrowArray Objects -======================== - -OracleArrowArray objects are returned by -:meth:`OracleDataFrame.column_arrays()`. - -These are used for conversion to `PyArrow Tables -`__, see -:ref:`dataframeformat`. - -.. versionadded:: 3.0.0 - -.. _oraclecolumnobj: - -OracleColumn Objects -==================== - -OracleColumn objects are returned by :meth:`OracleDataFrame.get_column()`, -:meth:`OracleDataFrame.get_column_by_name()`, and -:meth:`OracleDataFrame.get_columns()`. - -.. versionadded:: 3.0.0 - -.. _oraclecolumnmeth: - -OracleColumn Methods --------------------- - -.. method:: OracleColumn.get_buffers() - - Returns a dictionary containing the underlying buffers. - - The returned dictionary contains the ``data``, ``validity``, and ``offset`` - keys. - - The ``data`` attribute is a two-element tuple whose first element is a - buffer containing the data and whose second element is the data buffer's - associated dtype. - - The ``validity`` attribute is a a two-element tuple whose first element - is a buffer containing mask values indicating missing data and whose - second element is the mask value buffer's associated dtype. The value of - this attribute is *None* if the null representation is not a bit or byte - mask. - - The ``offset`` attribute is a two-element tuple whose first element is a - buffer containing the offset values for variable-size binary data (for - example, variable-length strings) and whose second element is the offsets - buffer's associated dtype. The value of this attribute is *None* if the - data buffer does not have an associated offsets buffer. - -.. method:: OracleColumn.get_chunks(n_chunks) - - Returns itself, since python-oracledb only uses one chunk. - -.. method:: OracleColumn.num_chunks() - - Returns the number of chunks the column consists of. - - This always returns 1. - -.. method:: OracleColumn.size() - - Returns the number of rows in the column. - -.. _oraclecolumnattr: - -OracleColumn Attributes ------------------------ - -.. attribute:: OracleColumn.describe_null - - This read-only property returns the description of the null representation - that the column uses. - -.. attribute:: OracleColumn.dtype - - This read-only attribute returns the Dtype description as a tuple - containing the values for the attributes ``kind``, ``bit-width``, - ``format string``, and ``endianess``. - - The ``kind`` attribute specifies the type of the data. - - The ``bit-width`` attribute specifies the number of bits as an integer. - - The ``format string`` attribute specifies the data type description format - string in Apache Arrow C Data Interface format. - - The ``endianess`` attribute specifies the byte order of the data type. - Currently, only native endianess is supported. - -.. attribute:: OracleColumn.metadata - - This read-only attribute returns the metadata for the column as a - dictionary with string keys. - -.. attribute:: OracleColumn.null_count - - This read-only attribute returns the number of null row values, if known. - -.. attribute:: OracleColumn.offset - - This read-only attribute specifies the offset of the first row. - -.. _oraclecolumnbufferobj: - -OracleColumnBuffer Objects -========================== - -A buffer object backed by an ArrowArray consisting of a single chunk. - -This is an internal class used for conversion to third party data frames. - -.. versionadded:: 3.0.0 +ArrowArray Objects +================== -.. _oraclecolumnbufferattr: +.. autoclass:: ArrowArray -OracleColumnBuffer Attributes ------------------------------ + ArrowArray objects are returned by :meth:`DataFrame.column_arrays()`. -.. attribute:: OracleColumnBuffer.bufsize + These are used for conversion to `PyArrow Tables + `__, see + :ref:`dataframeformat`. - This read-only property returns the buffer size in bytes. + .. versionchanged:: 3.3.0 -.. attribute:: OracleColumnBuffer.ptr + Removed the prefix "Oracle" from the class name. - This read-only attribute specifies the pointer to the start of the buffer - as an integer. + .. versionadded:: 3.0.0 diff --git a/doc/src/api_manual/dbobject_type.rst b/doc/src/api_manual/dbobject_type.rst index 1591a657..0420d4df 100644 --- a/doc/src/api_manual/dbobject_type.rst +++ b/doc/src/api_manual/dbobject_type.rst @@ -4,232 +4,123 @@ API: DbObjectType Objects ************************* -.. note:: +.. currentmodule:: oracledb - This object is an extension to the DB API. It is returned by the - :meth:`Connection.gettype()` call and is available as the - :data:`Variable.type` for variables containing Oracle Database objects. - -DbObjectType Methods -==================== - -.. method:: DbObjectType([sequence]) - - The object type may be called directly and serves as an alternative way of - calling :meth:`~DbObjectType.newobject()`. - -.. method:: DbObjectType.newobject([sequence]) - - Returns a new Oracle object of the given type. This object can then be - modified by setting its attributes and then bound to a cursor for - interaction with Oracle. If the object type refers to a collection, a - sequence may be passed and the collection will be initialized with the - items in that sequence. - -DbObjectType Attributes -======================= - -.. attribute:: DbObjectType.attributes - - This read-only attribute returns a list of the :ref:`attributes - ` that make up the object type. +DbObjectType Class +================== +.. autoclass:: DbObjectType -.. attribute:: DbObjectType.element_type + A DbObjectType object is returned with :meth:`Connection.gettype()` call + and is available as the :data:`Var.type` for variables containing Oracle + Database objects. - This read-only attribute returns the type of elements found in collections - of this type, if :attr:`~DbObjectType.iscollection` is *True*; otherwise, - it returns *None*. If the collection contains objects, this will be - another object type; otherwise, it will be one of the - :ref:`database type constants `. + .. dbapiobjectextension:: +DbObjectType Methods +-------------------- -.. attribute:: DbObjectType.iscollection - - This read-only attribute returns a boolean indicating if the object type - refers to a collection or not. +.. automethod:: DbObjectType.__call__ +.. automethod:: DbObjectType.newobject -.. attribute:: DbObjectType.name +DbObjectType Attributes +----------------------- - This read-only attribute returns the name of the type. +.. autoproperty:: DbObjectType.attributes +.. autoproperty:: DbObjectType.element_type -.. attribute:: DbObjectType.package_name + See :ref:`database type constants `. - This read-only attribute returns the name of the package, if the type - refers to a PL/SQL type (otherwise, it returns the value *None*). +.. autoproperty:: DbObjectType.iscollection +.. autoproperty:: DbObjectType.name -.. attribute:: DbObjectType.schema +.. autoproperty:: DbObjectType.package_name - This read-only attribute returns the name of the schema that owns the type. +.. autoproperty:: DbObjectType.schema .. _dbobject: -DbObject Objects +DbObject Class ================ -.. note:: - - This object is an extension to the DB API. It is returned by the - :meth:`DbObjectType.newobject()` call and can be bound to variables of - type :data:`~oracledb.OBJECT`. Attributes can be retrieved and set - directly. - -DbObject Methods -++++++++++++++++ - -.. method:: DbObject.append(element) - - Appends an element to the collection object. If no elements exist in the - collection, this creates an element at index 0; otherwise, it creates an - element immediately following the highest index available in the - collection. - - -.. method:: DbObject.asdict() - - Returns a dictionary where the collection's indexes are the keys and the - elements are its values. - - -.. method:: DbObject.aslist() - - Returns a list of each of the collection's elements in index order. - - -.. method:: DbObject.copy() +.. autoclass:: DbObject - Creates a copy of the object and returns it. + A DbObject object is returned by the :meth:`DbObjectType.newobject()` call + and can be bound to variables of type :data:`~oracledb.DB_TYPE_OBJECT`. + Attributes can be retrieved and set directly. + .. dbapiobjectextension:: -.. method:: DbObject.delete(index) - - Deletes the element at the specified index of the collection. If the - element does not exist or is otherwise invalid, an error is raised. Note - that the indices of the remaining elements in the collection are not - changed. In other words, the delete operation creates holes in the - collection. - - -.. method:: DbObject.exists(index) - - Returns *True* or *False* indicating if an element exists in the collection - at the specified index. - - -.. method:: DbObject.extend(sequence) - - Appends all of the elements in the sequence to the collection. This is - the equivalent of performing :meth:`~DbObject.append()` for each element - found in the sequence. - - -.. method:: DbObject.first() - - Returns the index of the first element in the collection. If the collection - is empty, *None* is returned. - - -.. method:: DbObject.getelement(index) - - Returns the element at the specified index of the collection. If no element - exists at that index, an exception is raised. - - -.. method:: DbObject.last() - - Returns the index of the last element in the collection. If the collection - is empty, *None* is returned. +DbObject Methods +---------------- +.. automethod:: DbObject.append -.. method:: DbObject.next(index) +.. automethod:: DbObject.asdict - Returns the index of the next element in the collection following the - specified index. If there are no elements in the collection following the - specified index, *None* is returned. +.. automethod:: DbObject.aslist +.. automethod:: DbObject.copy -.. method:: DbObject.prev(index) +.. automethod:: DbObject.delete - Returns the index of the element in the collection preceding the specified - index. If there are no elements in the collection preceding the - specified index, *None* is returned. +.. automethod:: DbObject.exists +.. automethod:: DbObject.extend -.. method:: DbObject.setelement(index, value) +.. automethod:: DbObject.first - Sets the value in the collection at the specified index to the given value. +.. automethod:: DbObject.getelement +.. automethod:: DbObject.last -.. method:: DbObject.size() +.. automethod:: DbObject.next - Returns the number of elements in the collection. +.. automethod:: DbObject.prev +.. automethod:: DbObject.setelement -.. method:: DbObject.trim(num) +.. automethod:: DbObject.size - Removes the specified number of elements from the end of the collection. +.. automethod:: DbObject.trim DbObject Attributes -+++++++++++++++++++ - -.. attribute:: DbObject.Type - - This read-only attribute returns an ObjectType corresponding to the type - of object. +------------------- +.. autoproperty:: DbObject.type .. _dbobjectattr: -DbObjectAttribute Objects -========================= +DbObjectAttribute Class +======================= -.. note:: +.. autoclass:: DbObjectAttr - This object is an extension to the DB API. The elements of - :attr:`DbObjectType.attributes` are instances of this type. + The elements of :attr:`DbObjectType.attributes` are instances of this + type. + .. dbapiobjectextension:: -.. attribute:: DbObjectAttribute.max_size +DbObjectAttr Attributes +----------------------- - This read-only attribute returns the maximum size (in bytes) of the - attribute when the attribute's type is one of - :data:`oracledb.DB_TYPE_CHAR`, :data:`oracledb.DB_TYPE_NCHAR`, - :data:`oracledb.DB_TYPE_NVARCHAR`, :data:`oracledb.DB_TYPE_RAW`, or - :data:`oracledb.DB_TYPE_VARCHAR`. For all other types the value returned is - *None*. +.. autoproperty:: DbObjectAttr.max_size .. versionadded:: 3.0.0 +.. autoproperty:: DbObjectAttr.name -.. attribute:: DbObjectAttribute.name - - This read-only attribute returns the name of the attribute. - - -.. attribute:: DbObjectAttribute.precision - - This read-only attribute returns the precision of the attribute when the - attribute's type is :data:`oracledb.DB_TYPE_NUMBER`. For all other types - the value returned is *None*. +.. autoproperty:: DbObjectAttr.precision .. versionadded:: 3.0.0 - -.. attribute:: DbObjectAttribute.scale - - This read-only attribute returns the scale of the attribute when the - attribute's type is :data:`oracledb.DB_TYPE_NUMBER`. For all other types - the value returned is *None*. +.. autoproperty:: DbObjectAttr.scale .. versionadded:: 3.0.0 +.. autoproperty:: DbObjectAttr.type -.. attribute:: DbObjectAttribute.type - - This read-only attribute returns the type of the attribute. This will be an - :ref:`Oracle Object Type ` if the variable binds - Oracle objects; otherwise, it will be one of the - :ref:`database type constants `. + See :ref:`database type constants `. diff --git a/doc/src/api_manual/defaults.rst b/doc/src/api_manual/defaults.rst index 03464fb5..20e56603 100644 --- a/doc/src/api_manual/defaults.rst +++ b/doc/src/api_manual/defaults.rst @@ -4,199 +4,87 @@ API: Defaults Object ******************** -This object contains attributes that can be used to adjust the behavior of the -python-oracledb driver. +.. currentmodule:: oracledb -All attributes are supported in Thin and Thick modes, subject to noted details. +Defaults Class +============== -An example of changing a default value is: +.. autoclass:: Defaults -.. code-block:: python + See :ref:`settingdefaults`. - import oracledb - - oracledb.defaults.fetch_lobs = False # return LOBs directly as strings or bytes +.. _defaultsattributes: Defaults Attributes =================== -.. attribute:: defaults.arraysize - - The default value for :attr:`Cursor.arraysize`. This is a query tuning - attribute, see :ref:`Tuning Fetch Performance `. - - This attribute has an initial value of *100*. - -.. attribute:: defaults.config_dir +.. autoproperty:: Defaults.arraysize - The directory in which the optional configuration file ``tnsnames.ora`` - will be read in python-oracledb Thin mode. + See :ref:`Tuning Fetch Performance `. - At time of ``import oracledb`` the value of - ``oracledb.defaults.config_dir`` will be set to (first one wins): +.. autoproperty:: Defaults.config_dir - - the value of ``$TNS_ADMIN``, if ``TNS_ADMIN`` is set. - - - ``$ORACLE_HOME/network/admin``, if ``$ORACLE_HOME`` is set. - - Otherwise, ``oracledb.defaults.config_dir`` will not be set. - - This attribute is used in python-oracledb Thin mode. It is also used in - Thick mode if :attr:`defaults.thick_mode_dsn_passthrough` is *False*, see - :ref:`optnetfiles`. + See :ref:`optnetfiles`. .. versionchanged:: 3.0.0 The directory ``$ORACLE_HOME/network/admin`` was added to the heuristic. - At completion of a call to :meth:`oracledb.init_oracle_client()` in - Thick mode, the value of :attr:`defaults.config_dir` may get changed - by python-oracledb. - -.. attribute:: defaults.driver_name +.. autoproperty:: Defaults.driver_name - The default value that represents the driver used by the client to connect - to Oracle Database. This is the value used in the CLIENT_DRIVER column - of the V$SESSION_CONNECT_INFO view. - - This attribute has an initial value of *None*. It is used as required in - python-oracledb Thick and Thin mode. - - In python-oracledb Thick mode, this attribute is used if the - ``driver_name`` parameter is not specified in - :meth:`oracledb.init_oracle_client()`. In Thin mode, this attribute is - used if the ``driver_name`` parameter is not specified in - :meth:`oracledb.connect()`, :meth:`oracledb.connect_async()`, - :meth:`oracledb.create_pool()`, or :meth:`oracledb.create_pool_async()`. - If the value of this attribute is *None*, the value set when connecting in - python-oracledb Thick mode is like "python-oracledb thk : " and - in Thin mode is like "python-oracledb thn : ". See - :ref:`otherinit`. + See :ref:`otherinit` and :ref:`dbviews`. .. versionadded:: 2.5.0 -.. attribute:: defaults.fetch_decimals - - Identifies whether numbers should be fetched as `decimal.Decimal - `__ values. - This can help avoid issues with converting numbers from Oracle Database's - decimal format to Python's binary format. - - An output type handler such as previously required in cx_Oracle (see - `return_numbers_as_decimals.py `__) can alternatively be - used to adjust the returned type. If a type handler exists and returns a - variable (that is, ``cursor.var(...)``), then that return variable is used. - If the type handler returns *None*, then the value of - ``oracledb.defaults.fetch_decimals`` is used to determine whether to return - ``decimal.Decimal`` values. - - This attribute has an initial value of *False*. - -.. attribute:: defaults.fetch_lobs - - When the value of this attribute is *True*, then queries to LOB columns - return LOB locators. When the value of this attribute is *False*, then - CLOBs and NCLOBs are fetched as strings, and BLOBs are fetched as bytes. If - LOBs are larger than 1 GB, then this attribute should be set to *True* and - the LOBs should be streamed. See :ref:`lobdata`. +.. autoproperty:: Defaults.fetch_decimals - An output type handler such as the one previously required in cx_Oracle - (see `return_lobs_as_strings.py `__) can - alternatively be used to adjust the returned type. If a type handler - exists and returns a variable (that is, `cursor.var(...)`), then that - return variable is used. If the type handler returns *None*, then the value - of ``oracledb.defaults.fetch_lobs`` is used. + See `decimal.Decimal `__. - The value of ``oracledb.defaults.fetch_lobs`` does not affect LOBs returned - as OUT binds. +.. autoproperty:: Defaults.fetch_lobs - This attribute has an initial value of *True*. + See :ref:`lobdata`. -.. attribute:: defaults.machine +.. autoproperty:: Defaults.machine - The default value that represents the machine name of the client - connecting to Oracle Database. This is the value used in the - MACHINE column of the V$SESSION view. - - This attribute takes the host name where the application is running as its - initial value. - - This attribute is only used in python-oracledb Thin mode. + See :ref:`dbviews`. .. versionadded:: 2.5.0 -.. attribute:: defaults.osuser - - The default value that represents the operating system user that initiates - the database connection. This is the value used in the OSUSER - column of the V$SESSION view. - - This attribute takes the login name of the user as its initial value. +.. autoproperty:: Defaults.osuser - This attribute is only used in python-oracledb Thin mode. + See :ref:`dbviews`. .. versionadded:: 2.5.0 -.. attribute:: defaults.prefetchrows - - The default value for :attr:`Cursor.prefetchrows`. This is a query tuning - attribute, see :ref:`Tuning Fetch Performance `. - - This attribute is ignored when using :meth:`Connection.fetch_df_all()` or - :meth:`Connection.fetch_df_batches()` since these methods always set the - internal prefetch size to the relevant arraysize or size value. - - This attribute has an initial value of *2*. +.. autoproperty:: Defaults.prefetchrows -.. attribute:: defaults.program + See :ref:`tuningfetch`. - The default value that represents the program name connected to the - database. This is the value used in the PROGRAM column of the - V$SESSION view. +.. autoproperty:: Defaults.program - This attribute has an initial value that is populated by `sys.executable - `__. - - This attribute is only used in python-oracledb Thin mode. + See :ref:`dbviews`. .. versionadded:: 2.5.0 -.. attribute:: defaults.stmtcachesize - - The default value for :attr:`Connection.stmtcachesize` and - :attr:`ConnectionPool.stmtcachesize`. This is a tuning attribute, see - :ref:`stmtcache`. - - This attribute has an initial value of *20*. - -.. attribute:: defaults.terminal +.. autoproperty:: Defaults.stmtcachesize - The default value that represents the terminal identifier from which the - connection originates. This is the value used in the TERMINAL - column of the V$SESSION view. + See :ref:`stmtcache`. - This attribute has an initial value of *unknown*. +.. autoproperty:: Defaults.terminal - This attribute is only used in python-oracledb Thin mode. + See :ref:`dbviews`. .. versionadded:: 2.5.0 -.. attribute:: defaults.thick_mode_dsn_passthrough - - The value that determines whether :ref:`connection strings ` - passed as the ``dsn`` parameter to :meth:`oracledb.connect()`, - :meth:`oracledb.create_pool()`, :meth:`oracledb.connect_async()`, and - :meth:`oracledb.create_pool_async()` in python-oracledb Thick mode will be - parsed by Oracle Client libraries or by python-oracledb itself. +.. autoproperty:: Defaults.thick_mode_dsn_passthrough When ``thick_mode_dsn_passthrough`` is the default value `True`, the - behavior of python-oracledb 2.5 and earlier versions occurs: Thick mode - passes connect strings unchanged to the Oracle Client libraries to - handle. Those libraries have their own heuristics for locating the optional - :ref:`tnsnames.ora `, if used. + behavior of python-oracledb 2.5 and earlier versions occurs: + python-oracledb Thick mode passes connect strings unchanged to the Oracle + Client libraries to handle. Those libraries have their own heuristics for + locating the optional :ref:`tnsnames.ora `, if used. When ``thick_mode_dsn_passthrough`` is `False`, python-oracledb Thick mode behaves similarly to Thin mode, which can be helpful for applications that @@ -225,10 +113,4 @@ Defaults Attributes is used for connection configuration, any :ref:`python-oracledb parameter values ` in the configuration will be used. - The value of ``thick_mode_dsn_passthrough`` is ignored in python-oracledb - Thin mode, which always parses all connect strings (including reading a - :ref:`tnsnames.ora ` file, if required). - - This attribute has an initial value of *True*. - .. versionadded:: 3.0.0 diff --git a/doc/src/api_manual/deprecations.rst b/doc/src/api_manual/deprecations.rst index bdaa44d0..ba55373e 100644 --- a/doc/src/api_manual/deprecations.rst +++ b/doc/src/api_manual/deprecations.rst @@ -11,8 +11,22 @@ and is no longer available in python-oracledb. The most recent deprecated and desupported features are listed first. The previous cx_Oracle deprecation announcements remain in force for -python-oracledb. The relevant functionality may be removed in a future version -of python-oracledb. +python-oracledb. The relevant functionality may be removed in a future version +of python-oracledb. The cx_Oracle driver itself is obsolete and should not be +used for new development. + +.. list-table-with-summary:: Deprecated in python-oracledb 3.4 + :header-rows: 1 + :class: wy-table-responsive + :summary: The first column, Name, displays the deprecated feature. The second column, Comments, includes information about the deprecation and the replacement to use, if applicable. + :name: _deprecations_3_4 + + * - Name + - Comments + * - The x86_64 macOS and 32-bit Windows platforms are deprecated. They will be desupported before, or when, the `cryptography `__ package desupports them. See the `cryptography deprecation announcement `__. + - Use arm64 macOS or 64-bit Windows instead. + * - Connectivity and interoperability with Oracle Database and Oracle Client libraries older than version 19 is deprecated and will be removed in a future version of python-oracledb. Production use, and availability of database and client software, is detailed in `Release Schedule of Current Database Releases `__. + - Upgrade the database and client library versions. .. list-table-with-summary:: Deprecated in python-oracledb 3.0 :header-rows: 1 @@ -23,7 +37,7 @@ of python-oracledb. * - Name - Comments * - Parameter ``pool`` of :meth:`oracledb.connect()` and :meth:`oracledb.connect_async()` - - Use :meth:`ConnectionPool.acquire()` instead + - Use :meth:`ConnectionPool.acquire()`, or make use of the :ref:`connection pool cache ` instead .. list-table-with-summary:: Desupported in python-oracledb 2.0 :header-rows: 1 @@ -34,33 +48,21 @@ of python-oracledb. * - Name - Comments * - ``oracledb.__future__.old_json_col_as_obj`` - - VARCHAR2 and LOB columns created with the ``IS JSON`` check constraint - are now always fetched as JSON. Use an :ref:`output type handler - ` if the old behavior is required. - * - Parameters ``encoding`` and ``nencoding`` of :func:`oracledb.connect()` - and :func:`oracledb.create_pool()`, and the related attributes on the - objects created - - The driver encodings are always UTF-8. Remove uses of ``encoding`` and - ``nencoding`` from your code. - * - Parameter ``threaded`` of :func:`oracledb.connect()` and - :func:`oracledb.create_pool()` + - VARCHAR2 and LOB columns created with the ``IS JSON`` check constraint are now always fetched as JSON. Use an :ref:`output type handler ` if the old behavior is required. + * - Parameters ``encoding`` and ``nencoding`` of :func:`oracledb.connect()` and :func:`oracledb.create_pool()`, and the related attributes on the objects created + - The driver encodings are always UTF-8. Remove uses of ``encoding`` and ``nencoding`` from your code. + * - Parameter ``threaded`` of :func:`oracledb.connect()` and :func:`oracledb.create_pool()` - Threading is always used. Remove uses of ``threaded`` from your code. - * - Parameter ``waitTimeout`` of :func:`oracledb.create_pool()` and - ``oracledb.SessionPool()`` + * - Parameter ``waitTimeout`` of :func:`oracledb.create_pool()` and ``oracledb.SessionPool()`` - Replace with parameter ``wait_timeout`` - * - Parameter ``maxLifetimeSession`` of :func:`oracledb.create_pool()` and - ``oracledb.SessionPool()`` + * - Parameter ``maxLifetimeSession`` of :func:`oracledb.create_pool()` and ``oracledb.SessionPool()`` - Replace with parameter ``max_lifetime_session`` - * - Parameter ``sessionCallback`` of :func:`oracledb.create_pool()` and - ``oracledb.SessionPool()`` + * - Parameter ``sessionCallback`` of :func:`oracledb.create_pool()` and ``oracledb.SessionPool()`` - Replace with parameter ``session_callback`` - * - Parameter ``maxSessionsPerShard`` of :func:`oracledb.create_pool()` and - ``oracledb.SessionPool()`` + * - Parameter ``maxSessionsPerShard`` of :func:`oracledb.create_pool()` and ``oracledb.SessionPool()`` - Replace with parameter ``max_sessions_per_shard`` - * - Attribute ``maxBytesPerCharacter`` of the :ref:`Connection object - ` - - The driver encodings are always UTF-8 so this attribute can be replaced by - the constant value 4 + * - Attribute ``maxBytesPerCharacter`` of the :ref:`Connection object ` + - The driver encodings are always UTF-8 so this attribute can be replaced by the constant value 4 * - ``Connection.tnsentry`` - Replace with :attr:`Connection.dsn` * - ``SessionPool.tnsentry`` @@ -74,16 +76,11 @@ of python-oracledb. * - Name - Comments - * - Calling :meth:`Variable.setvalue()` with a string value when the - variable type is one of :data:`oracledb.DB_TYPE_BLOB`, + * - Calling :meth:`Variable.setvalue()` with a string value when the variable type is one of :data:`oracledb.DB_TYPE_BLOB`, :data:`oracledb.DB_TYPE_CLOB` or :data:`oracledb.DB_TYPE_NCLOB`. - - Call :meth:`Connection.createlob()` with the value instead and pass the - result to :meth:`Variable.setvalue()`. - * - Setting an attribute of type :data:`oracledb.DB_TYPE_BLOB`, - :data:`oracledb.DB_TYPE_CLOB` or :data:`oracledb.DB_TYPE_NCLOB` on a - database object to a string value. - - Call :meth:`Connection.createlob()` with the value instead and set the - attribute with the result. + - Call :meth:`Connection.createlob()` with the value instead and pass the result to :meth:`Variable.setvalue()`. + * - Setting an attribute of type :data:`oracledb.DB_TYPE_BLOB`, :data:`oracledb.DB_TYPE_CLOB` or :data:`oracledb.DB_TYPE_NCLOB` on a database object to a string value. + - Call :meth:`Connection.createlob()` with the value instead and set the attribute with the result. .. list-table-with-summary:: Deprecated in python-oracledb 1.4 :header-rows: 1 @@ -93,10 +90,8 @@ of python-oracledb. * - Name - Comments - * - Output type handler with arguments - ``handler(cursor, name, default_type, length, precision, scale)`` - - Replace with ``handler(cursor, metadata)``. See - :ref:`outputtypehandlers`. + * - Output type handler with arguments ``handler(cursor, name, default_type, length, precision, scale)`` + - Replace with ``handler(cursor, metadata)``. See :ref:`outputtypehandlers`. .. list-table-with-summary:: Deprecated in python-oracledb 1.0 :header-rows: 1 @@ -178,7 +173,7 @@ of python-oracledb. * - ``Cursor.executemanyprepared()`` - Use :meth:`Cursor.executemany()` instead. * - Previously deprecated Advanced Queuing (AQ) API - - Use the new :ref:`AQ API ` instead. AQ is only available in the python-oracledb Thick mode. + - Use the new :ref:`AQ API ` instead. AQ is only available in python-oracledb Thick mode. * - ``Connection.deq()`` - Replace with :meth:`Queue.deqone()` or :meth:`Queue.deqmany()` * - ``Connection.deqoptions()`` diff --git a/doc/src/api_manual/fetch_info.rst b/doc/src/api_manual/fetch_info.rst index 69b45c3b..adce4dda 100644 --- a/doc/src/api_manual/fetch_info.rst +++ b/doc/src/api_manual/fetch_info.rst @@ -4,152 +4,71 @@ API: FetchInfo Objects ********************** -FetchInfo objects are created internally when a query is executed. They are found -in the sequence :data:`Cursor.description`. There is one FetchInfo object for -each column. For compatibility with the Python Database API, this object -behaves as a 7-tuple containing the values for the attributes ``name``, -``type_code``, ``display_size``, ``internal_size``, ``precision``, ``scale``, -and ``null_ok`` in that order. For example, if ``fetch_info`` is of type -FetchInfo, then ``fetch_info[2]`` is the same as ``fetch_info.display_size``. +.. currentmodule:: oracledb -.. versionadded:: 1.4.0 +FetchInfo Class +=============== -.. note:: +.. autoclass:: FetchInfo - This object is an extension the DB API. + A FetchInfo object is created internally when a query is executed. They + are found in the sequence :data:`Cursor.description`. There is one + FetchInfo object for each column. For compatibility with the Python + Database API, this object behaves as a 7-tuple containing the values for + the attributes ``name``, ``type_code``, ``display_size``, + ``internal_size``, ``precision``, ``scale``, and ``null_ok`` in that order. + For example, if ``fetch_info`` is of type FetchInfo, then ``fetch_info[2]`` + is the same as ``fetch_info.display_size``. + + .. dbapiobjectextension:: + + .. versionadded:: 1.4.0 FetchInfo Attributes ==================== -.. attribute:: FetchInfo.annotations - - This read-only attribute returns a dictionary containing the `annotations - `__ associated with the fetched column. If - there are no annotations, the value *None* is returned. Annotations - require Oracle Database 23ai. If using python-oracledb Thick mode, Oracle - Client 23ai is also required. +.. autoproperty:: FetchInfo.annotations .. versionadded:: 2.0.0 -.. attribute:: FetchInfo.display_size +.. autoproperty:: FetchInfo.display_size - This read-only attribute returns the display size of the column as mandated - by the Python Database API. - -.. attribute:: FetchInfo.domain_name - - This read-only attribute returns the name of the `data use case domain - `__ associated with the fetched column. If - there is no data use case domain, the value *None* is returned. `Data - use case domains `__ require Oracle Database 23ai. - If using python-oracledb Thick mode, Oracle Client 23ai is also required. +.. autoproperty:: FetchInfo.domain_name .. versionadded:: 2.0.0 -.. attribute:: FetchInfo.domain_schema - - This read-only attribute returns the schema of the `data use case domain - `__ associated with the fetched column. If - there is no data use case domain, the value *None* is returned. `Data - use case domains `__ require Oracle Database 23ai. - If using python-oracledb Thick mode, Oracle Client 23ai is also required. +.. autoproperty:: FetchInfo.domain_schema .. versionadded:: 2.0.0 -.. attribute:: FetchInfo.internal_size +.. autoproperty:: FetchInfo.internal_size - This read-only attribute returns the internal size of the column as - mandated by the Python Database API. +.. autoproperty:: FetchInfo.is_json -.. attribute:: FetchInfo.is_json - - This read-only attribute returns whether the column is known to contain - JSON data. This will be *True* when the type code is - :data:`oracledb.DB_TYPE_JSON` as well as when an "IS JSON" constraint is - enabled on LOB and VARCHAR2 columns. - -.. attribute:: FetchInfo.is_oson - - This read-only attribute returns whether the column is known to contain - binary encoded `OSON `__ data. This will be *True* - when an "IS JSON FORMAT OSON" check constraint is enabled on BLOB columns. +.. autoproperty:: FetchInfo.is_oson .. versionadded:: 2.1.0 -.. attribute:: FetchInfo.name - - This read-only attribute returns the name of the column as mandated by the - Python Database API. - -.. attribute:: FetchInfo.null_ok +.. autoproperty:: FetchInfo.name - This read-only attribute returns whether nulls are allowed in the column as - mandated by the Python Database API. +.. autoproperty:: FetchInfo.null_ok -.. attribute:: FetchInfo.precision +.. autoproperty:: FetchInfo.precision - This read-only attribute returns the precision of the column as mandated by - the Python Database API. +.. autoproperty:: FetchInfo.scale -.. attribute:: FetchInfo.scale +.. autoproperty:: FetchInfo.type - This read-only attribute returns the scale of the column as mandated by - the Python Database API. +.. autoproperty:: FetchInfo.type_code -.. attribute:: FetchInfo.type - - This read-only attribute returns the type of the column. This will be an - :ref:`Oracle Object Type ` if the column contains Oracle - objects; otherwise, it will be one of the :ref:`database type constants - ` defined at the module level. - - -.. attribute:: FetchInfo.type_code - - This read-only attribute returns the type of the column as mandated by the - Python Database API. The type will be one of the :ref:`database type - constants ` defined at the module level. - -.. attribute:: FetchInfo.vector_dimensions - - This read-only attribute returns the number of dimensions required by - VECTOR columns. If the column is not a VECTOR column or allows for any - number of dimensions, the value returned is *None*. +.. autoproperty:: FetchInfo.vector_dimensions .. versionadded:: 2.2.0 -.. attribute:: FetchInfo.vector_format - - This read-only attribute returns the storage format used by VECTOR - columns. The value of this attribute can be: - - - :data:`oracledb.VECTOR_FORMAT_BINARY` which represents 8-bit unsigned - integers - - :data:`oracledb.VECTOR_FORMAT_INT8` which represents 8-bit signed - integers - - :data:`oracledb.VECTOR_FORMAT_FLOAT32` which represents 32-bit - floating-point numbers - - :data:`oracledb.VECTOR_FORMAT_FLOAT64` which represents 64-bit - floating-point numbers - - If the column is not a VECTOR column or allows for any type of storage, - the value returned is *None*. +.. autoproperty:: FetchInfo.vector_format .. versionadded:: 2.2.0 -.. attribute:: FetchInfo.vector_is_sparse - - This read-only attribute returns a boolean that indicates whether the - vector is sparse or not. - - If the column contains vectors that are SPARSE, the value returned is - True. If the column contains vectors that are DENSE, the value returned is - False. If the column is not a VECTOR column, the value returned is ``None``. +.. autoproperty:: FetchInfo.vector_is_sparse .. versionadded:: 3.0.0 diff --git a/doc/src/api_manual/lob.rst b/doc/src/api_manual/lob.rst index 21b5ddf5..8fe6bb59 100644 --- a/doc/src/api_manual/lob.rst +++ b/doc/src/api_manual/lob.rst @@ -4,88 +4,54 @@ API: LOB Objects **************** -A LOB object can be created with :meth:`Connection.createlob()`. See -:ref:`lobdata` for more information about using LOBs. +.. currentmodule:: oracledb -.. note:: +LOB Class +========= - This object is an extension the DB API. It is returned whenever Oracle - :data:`CLOB`, :data:`BLOB` and :data:`BFILE` columns are fetched. +.. autoclass:: LOB -LOB Methods -=========== - -.. method:: LOB.close() - - Closes the LOB. Call this when writing is completed so that the indexes - associated with the LOB can be updated -- but only if :meth:`~LOB.open()` - was called first. - -.. method:: LOB.fileexists() + A LOB object should be created with :meth:`Connection.createlob()`. - Returns a boolean indicating if the file referenced by the BFILE type LOB - exists. + This object is returned by default whenever Oracle :data:`CLOB`, + :data:`BLOB`, and :data:`BFILE` columns are fetched. -.. method:: LOB.getchunksize() + This type object is the Python type of :data:`DB_TYPE_BLOB`, + :data:`DB_TYPE_BFILE`, :data:`DB_TYPE_CLOB` and :data:`DB_TYPE_NCLOB` data + that is returned from cursors. - Returns the chunk size for the internal LOB. Reading and writing to the LOB - in chunks of multiples of this size will improve performance. + .. dbapiobjectextension:: -.. method:: LOB.getfilename() + See :ref:`lobdata` for more information about using LOBs. - Returns a two-tuple consisting of the directory alias and file name for a - BFILE type LOB. - -.. method:: LOB.isopen() - - Returns a boolean indicating if the LOB has been opened using the method - :meth:`~LOB.open()`. - -.. method:: LOB.open() +LOB Methods +=========== - Opens the LOB for writing. This will improve performance when writing to a - LOB in chunks and there are functional or extensible indexes associated - with the LOB. If this method is not called, each write will perform an open - internally followed by a close after the write has been completed. +.. automethod:: LOB.close -.. method:: LOB.read([offset=1, [amount]]) +.. automethod:: LOB.fileexists - Returns a portion (or all) of the data in the LOB object. Note that the - amount and offset are in bytes for BLOB and BFILE type LOBs and in UCS-2 - code points for CLOB and NCLOB type LOBs. UCS-2 code points are equivalent - to characters for all but supplemental characters. If supplemental - characters are in the LOB, the offset and amount will have to be chosen - carefully to avoid splitting a character. +.. automethod:: LOB.getchunksize -.. method:: LOB.setfilename(dir_alias, name) +.. automethod:: LOB.getfilename - Sets the directory alias and name of the BFILE type LOB. +.. automethod:: LOB.isopen -.. method:: LOB.size() +.. automethod:: LOB.open - Returns the size of the data in the LOB object. For BLOB and BFILE type - LOBs, this is the number of bytes. For CLOB and NCLOB type LOBs, this is the - number of UCS-2 code points. UCS-2 code points are equivalent to characters - for all but supplemental characters. +.. automethod:: LOB.read -.. method:: LOB.trim(new_size=0) +.. automethod:: LOB.setfilename - Trims the LOB to the new size. +.. automethod:: LOB.size -.. method:: LOB.write(data, offset=1) +.. automethod:: LOB.trim - Writes the data to the LOB object at the given offset. The offset is in - bytes for BLOB type LOBs and in UCS-2 code points for CLOB and NCLOB type - LOBs. UCS-2 code points are equivalent to characters for all but - supplemental characters. If supplemental characters are in the LOB, the - offset will have to be chosen carefully to avoid splitting a character. - Note that if you want to make the LOB value smaller, you must use the - :meth:`~LOB.trim()` function. +.. automethod:: LOB.write LOB Attributes ============== -.. attribute:: LOB.type +.. autoproperty:: LOB.type - This read-only attribute returns the type of the LOB as one of the - :ref:`database type constants `. + See :ref:`database type constants `. diff --git a/doc/src/api_manual/module.rst b/doc/src/api_manual/module.rst index 042f7e54..52f89c9d 100644 --- a/doc/src/api_manual/module.rst +++ b/doc/src/api_manual/module.rst @@ -11,418 +11,19 @@ API: python-oracledb Module Oracledb Methods ================ -.. function:: Binary(string) +.. autofunction:: Binary - Constructs an object holding a binary (long) string value. +.. autofunction:: clientversion + See :ref:`enablingthick`. -.. function:: clientversion() + .. dbapimethodextension:: - Returns the version of the client library being used as a 5-tuple. The five - values are the major version, minor version, update number, patch number, - and port update number. +.. autofunction:: connect - .. note:: - - This function can only be called when python-oracledb is in Thick - mode. See :ref:`enablingthick`. - - If ``clientversion()`` is called when in python-oracledb Thin mode, that - is, if :func:`oracledb.init_oracle_client()` is not called first, then an - exception will be thrown. - - .. note:: + .. versionchanged:: 3.2.0 - This method is an extension to the DB API definition. - -.. function:: connect(dsn=None, pool=None, pool_alias=None, conn_class=None, \ - params=None, user=None, proxy_user=None, password=None, \ - newpassword=None, wallet_password=None, access_token=None, host=None, \ - port=1521, protocol="tcp", https_proxy=None, https_proxy_port=0, \ - service_name=None, instance_name=None, sid=None, server_type=None, \ - cclass=None, purity=oracledb.PURITY_DEFAULT, expire_time=0, \ - retry_count=0, retry_delay=1, tcp_connect_timeout=20.0, \ - ssl_server_dn_match=True, ssl_server_cert_dn=None, \ - wallet_location=None, events=False, externalauth=False, \ - mode=oracledb.AUTH_MODE_DEFAULT, disable_oob=False, \ - stmtcachesize=oracledb.defaults.stmtcachesize, edition=None, \ - tag=None, matchanytag=False, config_dir=oracledb.defaults.config_dir, \ - appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, \ - connection_id_prefix=None, ssl_context=None, sdu=8192, \ - pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \ - program=oracledb.defaults.program, machine=oracledb.defaults.machine, \ - terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \ - driver_name=oracledb.defaults.driver_name, use_sni=False, \ - thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \ - extra_auth_params=None, handle=0) - - Constructor for creating a connection to the database. Returns a - :ref:`Connection Object `. All parameters are optional and can be - specified as keyword parameters. See :ref:`standaloneconnection` - information about connections. - - Not all parameters apply to both python-oracledb Thin and :ref:`Thick - ` modes. - - Some values, such as the database host name, can be specified as - parameters, as part of the connect string, and in the params object. If a - ``dsn`` (data source name) parameter is passed, the python-oracledb Thick - mode will use the string to connect, otherwise a connection string is - internally constructed from the individual parameters and params object - values, with the individual parameters having precedence. In - python-oracledb's default Thin mode, a connection string is internally used - that contains all relevant values specified. The precedence in Thin mode - is that values in any ``dsn`` parameter override values passed as - individual parameters, which themselves override values set in the - ``params`` parameter object. Similar precedence rules also apply to other - values. - - The ``dsn`` (data source name) parameter is an :ref:`Oracle Net Services - Connection String `. It can also be a string in the format - ``user/password@connect_string``. - - The ``pool`` parameter is expected to be a pool object. This parameter - was deprecated in python-oracledb 3.0.0. Use - :meth:`ConnectionPool.acquire()` instead since the use of this parameter - is the equivalent of calling this method. - - The ``pool_alias`` parameter is expected to be a string which indicates the - name of the previously created pool in the :ref:`connection pool cache - ` from which to acquire the connection. This is identical to - calling :meth:`ConnectionPool.acquire()`. When ``pool_alias`` is used, - ``connect()`` supports the same parameters as - :meth:`~ConnectionPool.acquire()` and has the same behavior. - - The ``conn_class`` parameter is expected to be Connection or a subclass of - Connection. - - The ``params`` parameter is expected to be of type :ref:`ConnectParams - ` and contains connection parameters that will be used when - establishing the connection. If this parameter is not specified, the - additional keyword parameters will be used to internally create an instance - of ConnectParams. If both the params parameter and additional keyword - parameters are specified, the values in the keyword parameters have - precedence. Note that if a ``dsn`` is also supplied in python-oracledb Thin - mode, then the values of the parameters specified (if any) within the - ``dsn`` will override the values passed as additional keyword parameters, - which themselves override the values set in the ``params`` parameter - object. - - The ``user`` parameter is expected to be a string which indicates the name - of the user to connect to. This value is used in both the python-oracledb - Thin and Thick modes. - - The ``proxy_user`` parameter is expected to be a string which indicates the - name of the proxy user to connect to. If this value is not specified, it - will be parsed out of user if user is in the form "user[proxy_user]". This - value is used in both the python-oracledb Thin and Thick modes. - - The ``password`` parameter expected to be a string which indicates the - password for the user. This value is used in both the python-oracledb Thin - and Thick modes. - - The ``newpassword`` parameter is expected to be a string which indicates - the new password for the user. The new password will take effect - immediately upon a successful connection to the database. This value is - used in both the python-oracledb Thin and Thick modes. - - The ``wallet_password`` parameter is expected to be a string which - indicates the password to use to decrypt the PEM-encoded wallet, if it is - encrypted. This value is only used in python-oracledb Thin mode. The - ``wallet_password`` parameter is not needed for cwallet.sso files that are - used in the python-oracledb Thick mode. - - The ``access_token`` parameter is expected to be a string or a 2-tuple or - a callable. If it is a string, it specifies an Azure AD OAuth2 token used - for Open Authorization (OAuth 2.0) token based authentication. If it is a - 2-tuple, it specifies the token and private key strings used for Oracle - Cloud Infrastructure (OCI) Identity and Access Management (IAM) token based - authentication. If it is a callable, it returns either a string or a - 2-tuple used for OAuth 2.0 or OCI IAM token based authentication and is - useful when the pool needs to expand and create new connections but the - current authentication token has expired. This value is used in both the - python-oracledb Thin and Thick modes. - - The ``host`` parameter is expected to be a string which specifies the name - or IP address of the machine hosting the listener, which handles the - initial connection to the database. This value is used in both the - python-oracledb Thin and Thick modes. - - The ``port`` parameter is expected to be an integer which indicates the - port number on which the listener is listening. The default value is - *1521*. This value is used in both the python-oracledb Thin and Thick - modes. - - The ``protocol`` parameter is expected to be one of the strings *tcp* or - *tcps* which indicates whether to use unencrypted network traffic or - encrypted network traffic (TLS). The default value is *tcp*. This value is - used in both the python-oracledb Thin and Thick modes. - - The ``https_proxy`` parameter is expected to be a string which indicates - the name or IP address of a proxy host to use for tunneling secure - connections. This value is used in both the python-oracledb Thin and Thick - modes. - - The ``https_proxy_port`` parameter is expected to be an integer which - indicates the port that is to be used to communicate with the proxy host. - The default value is *0*. This value is used in both the python-oracledb - Thin and Thick modes. - - The ``service_name`` parameter is expected to be a string which indicates - the service name of the database. This value is used in both the - python-oracledb Thin and Thick modes. - - The ``instance_name`` parameter is expected to be a string which indicates - the instance name of the database. This value is used in both the - python-oracledb Thin and Thick modes. - - The ``sid`` parameter is expected to be a string which indicates the SID of - the database. It is recommended to use ``service_name`` instead. This value - is used in both the python-oracledb Thin and Thick modes. - - The ``server_type`` parameter is expected to be a string that indicates the - type of server connection that should be established. If specified, it - should be one of *dedicated*, *shared*, or *pooled*. This value is used in - both the python-oracledb Thin and Thick modes. - - The ``cclass`` parameter is expected to be a string that identifies the - connection class to use for :ref:`drcp`. This value is used in both the - python-oracledb Thin and Thick modes. - - The ``purity`` parameter is expected to be one of the - :ref:`oracledb.PURITY_* ` constants that identifies the - purity to use for DRCP. This value is used in both the python-oracledb Thin - and Thick modes. The purity will internally default to - :data:`~oracledb.PURITY_SELF` for pooled connections. For standalone - connections, the purity will internally default to - :data:`~oracledb.PURITY_NEW`. - - The ``expire_time`` parameter is expected to be an integer which indicates - the number of minutes between the sending of keepalive probes. If this - parameter is set to a value greater than zero it enables keepalive. This - value is used in both the python-oracledb Thin and Thick modes. The default - value is *0*. - - The ``retry_count`` parameter is expected to be an integer that identifies - the number of times that a connection attempt should be retried before the - attempt is terminated. This value is used in both the python-oracledb Thin - and Thick modes. The default value is *0*. - - The ``retry_delay`` parameter is expected to be an integer that identifies - the number of seconds to wait before making a new connection attempt. This - value is used in both the python-oracledb Thin and Thick modes. The default - value is *1*. - - The ``tcp_connect_timeout`` parameter is expected to be a float that - indicates the maximum number of seconds to wait for establishing a - connection to the database host. This value is used in both the - python-oracledb Thin and Thick modes. The default value is *20.0*. - - The ``ssl_server_dn_match`` parameter is expected to be a boolean that - indicates whether the server certificate distinguished name (DN) should be - matched in addition to the regular certificate verification that is - performed. Note that if the ``ssl_server_cert_dn`` parameter is not - provided, host name matching is performed instead. This value is used in - both the python-oracledb Thin and Thick modes. The default value is *True*. - - The ``ssl_server_cert_dn`` parameter is expected to be a string that - indicates the distinguished name (DN) which should be matched with the - server. This value is ignored if the ``ssl_server_dn_match`` parameter is - not set to the value *True*. This value is used in both the python-oracledb - Thin and Thick modes. - - The ``wallet_location`` parameter is expected to be a string that - identifies the directory where the wallet can be found. In python-oracledb - Thin mode, this must be the directory of the PEM-encoded wallet file, - ewallet.pem. In python-oracledb Thick mode, this must be the directory of - the file, cwallet.sso. This value is used in both the python-oracledb Thin - and Thick modes. - - The ``events`` parameter is expected to be a boolean that specifies whether - the events mode should be enabled. This value is only used in the - python-oracledb Thick mode and is ignored in the Thin mode. This parameter - is needed for continuous query notification and high availability event - notifications. The default value is *False*. - - The ``externalauth`` parameter is a boolean that specifies whether external - authentication should be used. This value is only used in the - python-oracledb Thick mode and is ignored in the Thin mode. The default - value is *False*. For standalone connections, external authentication - occurs when the ``user`` and ``password`` attributes are not used. If these - attributes are not used, you can optionally set the ``externalauth`` - attribute to *True*, which may aid code auditing. - - If the ``mode`` parameter is specified, it must be one of the - :ref:`connection authorization modes ` - which are defined at the module level. This value is used in both the - python-oracledb Thin and Thick modes. The default value is - :data:`oracledb.AUTH_MODE_DEFAULT`. - - The ``disable_oob`` parameter is expected to be a boolean that indicates - whether out-of-band breaks should be disabled. This value is only used - in the python-oracledb Thin mode and has no effect on Windows which - does not support this functionality. The default value is *False*. - - The ``stmtcachesize`` parameter is expected to be an integer which - specifies the initial size of the statement cache. This value is used in - both the python-oracledb Thin and Thick modes. The default is the value of - :attr:`defaults.stmtcachesize`. - - The ``edition`` parameter is expected to be a string that indicates the - edition to use for the connection. It requires Oracle Database 11.2, or - later. This parameter cannot be used simultaneously with the ``cclass`` - parameter. - - The ``tag`` parameter is expected to be a string that identifies the type - of connection that should be returned from a pool. This value is only used - in the python-oracledb Thick mode and is ignored in the Thin mode. - - The ``matchanytag`` parameter is expected to be a boolean specifying - whether any tag can be used when acquiring a connection from the pool. This - value is only used in the python-oracledb Thick mode when acquiring a - connection from a pool. This value is ignored in the python-oracledb Thin - mode. The default value is *False*. - - The ``config_dir`` parameter is expected to be a string that indicates the - directory in which :ref:`optional configuration files ` are - found. The default is the value of :attr:`defaults.config_dir`. - - The ``appcontext`` parameter is expected to be a list of 3-tuples that - identifies the application context used by the connection. This parameter - should contain namespace, name, and value and each entry in the tuple - should be a string. - - The ``shardingkey`` parameter and ``supershardingkey`` parameters, if - specified, are expected to be a sequence of values which identifies the - database shard to connect to. The key values can be a list of strings, - numbers, bytes, or dates. These values are only used in the - python-oracledb Thick mode and are ignored in the Thin mode. See - :ref:`connsharding`. - - The ``debug_jdwp`` parameter is expected to be a string with the format - `host=;port=` that specifies the host and port of the PL/SQL - debugger. This allows using the Java Debug Wire Protocol (JDWP) to debug - PL/SQL code called by python-oracledb. This value is only used in the - python-oracledb Thin mode. For python-oracledb Thick mode, set the - ``ORA_DEBUG_JDWP`` environment variable which has the same syntax. For more - information, see :ref:`applntracing`. - - The ``connection_id_prefix`` parameter is expected to be a string and is - added to the beginning of the generated ``connection_id`` that is sent to - the database for `tracing `__. This value - is only used in the python-oracledb Thin mode. - - The ``ssl_context`` parameter is expected to be an `SSLContext object - `__ which is used - for connecting to the database using TLS. This SSL context will be - modified to include the private key or any certificates found in a - separately supplied wallet. This parameter should only be specified if - the default SSLContext object cannot be used. This value is only used in - the python-oracledb Thin mode. - - The ``sdu`` parameter is expected to be an integer that returns the - requested size of the Session Data Unit (SDU), in bytes. The value tunes - internal buffers used for communication to the database. Bigger values can - increase throughput for large queries or bulk data loads, but at the cost - of higher memory use. The SDU size that will actually be used is - negotiated down to the lower of this value and the database network SDU - configuration value. See the `SQL*Net documentation `__ for more details. This value is used in both the - python-oracledb Thin and Thick modes. The default value is *8192* bytes. - - The ``pool_boundary`` parameter is expected to be one of the strings - *statement* or *transaction* which indicates when pooled :ref:`DRCP ` - or PRCP connections can be returned to the pool. If the value is - *statement*, then pooled DRCP or PRCP connections are implicitly released - back to the DRCP or PRCP pool when the connection is stateless (that is, - there are no active cursors, active transactions, temporary tables, or - temporary LOBs). If the value is *transaction*, then pooled DRCP or PRCP - connections are implicitly released back to the DRCP or PRCP pool when - either one of the methods :meth:`Connection.commit()` or - :meth:`Connection.rollback()` are called. This parameter requires the use - of DRCP or PRCP with Oracle Database 23ai (or later). See - :ref:`implicitconnpool` for more information. This value is used in both - the python-oracledb Thin and Thick modes. - - The ``use_tcp_fast_open`` parameter is expected to be a boolean which - indicates whether to use TCP Fast Open which is an `Oracle Autonomous - Database Serverless (ADB-S) `__ specific feature that can - reduce the latency in round-trips to the database after a connection has - been established. This feature is only available with certain versions of - ADB-S. This value is used in both python-oracledb Thin and Thick modes. - The default value is *False*. - - The ``ssl_version`` parameter is expected to be one of the constants - *ssl.TLSVersion.TLSv1_2* or *ssl.TLSVersion.TLSv1_3* which identifies the - TLS protocol version used. These constants are defined in the Python - `ssl `__ module. This - parameter can be specified when establishing connections with the protocol - *tcps*. This value is used in both python-oracledb Thin and Thick modes. - The value *ssl.TLSVersion.TLSv1_3* requires Oracle Database 23ai. If you - are using python-oracledb Thick mode, Oracle Client 23ai is additionally - required. - - The ``use_sni`` parameter is expected to be a boolean which indicates - whether to use the TLS Server Name Indication (SNI) extension to bypass the - second TLS negotiation that would otherwise be required. This parameter is - used in both python-oracledb Thin and Thick modes. This parameter requires - Oracle Database 23.7. The default value is *False*. See the `SQL*Net - documentation `__ for more details. - - The ``program`` parameter is expected to be a string which specifies the - name of the executable program or application connected to Oracle - Database. This value is only used in the python-oracledb Thin mode. The - default is the value of :attr:`defaults.program`. - - The ``machine`` parameter is expected to be a string which specifies the - machine name of the client connecting to Oracle Database. This value is - only used in the python-oracledb Thin mode. The default is the value of - :attr:`defaults.machine`. - - The ``terminal`` parameter is expected to be a string which specifies the - terminal identifier from which the connection originates. This value is - only used in the python-oracledb Thin mode. The default is the value of - :attr:`defaults.terminal`. - - The ``osuser`` parameter is expected to be a string which specifies the - operating system user that initiates the database connection. This value - is only used in the python-oracledb Thin mode. The default value is the - value of :attr:`defaults.osuser`. - - The ``driver_name`` parameter is expected to be a string which specifies - the driver used by the client to connect to Oracle Database. This value - is used in both the python-oracledb Thin and Thick modes. The default is - the value of :attr:`defaults.driver_name`. - - The ``thick_mode_dsn_passthrough`` parameter is expected to be a boolean - which indicates whether the connect string should be passed unchanged to - the Oracle Client libraries for parsing when using python-oracledb Thick - mode. If this parameter is set to *False* in Thick mode, connect strings - are parsed by python-oracledb itself and a generated connect descriptor is - sent to the Oracle Client libraries. This value is only used in the - python-oracledb Thick mode. The default value is the value of - :attr:`defaults.thick_mode_dsn_passthrough`. For more information, see - :ref:`usingconfigfiles`. - - The ``extra_auth_params`` parameter is expected to be a dictionary - containing the configuration parameters necessary for Oracle Database - authentication using :ref:`OCI ` or :ref:`Azure - ` cloud native authentication plugins. This value is - used in both the python-oracledb Thin and Thick modes. See - :ref:`tokenauth`. - - If the ``handle`` parameter is specified, it must be of type OCISvcCtx\* - and is only of use when embedding Python in an application (like - PowerBuilder) which has already made the connection. The connection thus - created should *never* be used after the source handle has been closed or - destroyed. This value is only used in the python-oracledb Thick mode and - is ignored in the Thin mode. It should be used with extreme caution. The - default value is *0*. + The ``pool_name`` parameter was added. .. versionchanged:: 3.0.0 @@ -456,317 +57,11 @@ Oracledb Methods The ``connection_id_prefix`` parameter was added. -.. function:: connect_async(dsn=None, pool=None, pool_alias=None, \ - conn_class=None, params=None, user=None, proxy_user=None, \ - password=None, newpassword=None, wallet_password=None, \ - access_token=None, host=None, port=1521, protocol="tcp", \ - https_proxy=None, https_proxy_port=0, service_name=None, \ - instance_name=None, sid=None, server_type=None, cclass=None, \ - purity=oracledb.PURITY_DEFAULT, expire_time=0, retry_count=0, \ - retry_delay=1, tcp_connect_timeout=20.0, ssl_server_dn_match=True, \ - ssl_server_cert_dn=None, wallet_location=None, events=False, \ - externalauth=False, mode=oracledb.AUTH_MODE_DEFAULT, \ - disable_oob=False, stmtcachesize=oracledb.defaults.stmtcachesize, \ - edition=None, tag=None, matchanytag=False, \ - config_dir=oracledb.defaults.config_dir, appcontext=[], \ - shardingkey=[], supershardingkey=[], debug_jdwp=None, \ - connection_id_prefix=None, ssl_context=None, sdu=8192, \ - pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \ - program=oracledb.defaults.program, machine=oracledb.defaults.machine, \ - terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \ - driver_name=oracledb.defaults.driver_name, use_sni=False, \ - thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \ - extra_auth_params=None, handle=0) - - Constructor for creating a connection to the database. Returns an - :ref:`AsyncConnection Object `. All parameters are optional - and can be specified as keyword parameters. See - :ref:`standaloneconnection` information about connections. - - This method can only be used in python-oracledb Thin mode. - - When connecting to Oracle Autonomous Database, use Python 3.11, or later. +.. autofunction:: connect_async - .. versionadded:: 2.0.0 + .. versionchanged:: 3.2.0 - Some values, such as the database host name, can be specified as - parameters, as part of the connect string, and in the params object. - The precedence is that values in the ``dsn`` parameter override values - passed as individual parameters, which themselves override values set in - the ``params`` parameter object. Similar precedence rules also apply to - other values. - - The ``dsn`` (data source name) parameter is an :ref:`Oracle Net Services - Connection String `. It can also be a string in the format - ``user/password@connect_string``. - - The ``pool`` parameter is expected to be an AsyncConnectionPool object. - This parameter was deprecated in python-oracledb 3.0.0. Use - :meth:`AsyncConnectionPool.acquire()` instead since the - use of this parameter is the equivalent of calling this method. - - The ``pool_alias`` parameter is expected to be a string which indicates the - name of the previously created pool in the :ref:`connection pool cache - ` from which to acquire the connection. This is identical to - calling :meth:`AsyncConnectionPool.acquire()`. When ``pool_alias`` is used, - ``connect_async()`` supports the same parameters as - :meth:`~AsyncConnectionPool.acquire()` and has the same behavior. - - The ``conn_class`` parameter is expected to be AsyncConnection or a - subclass of AsyncConnection. - - The ``params`` parameter is expected to be of type :ref:`ConnectParams - ` and contains connection parameters that will be used when - establishing the connection. If this parameter is not specified, the - additional keyword parameters will be used to create an instance of - ConnectParams. If both the params parameter and additional keyword - parameters are specified, the values in the keyword parameters have - precedence. Note that if a ``dsn`` is also supplied, then the values of the - parameters specified (if any) within the ``dsn`` will override the values - passed as additional keyword parameters, which themselves override the - values set in the ``params`` parameter object. - - The ``user`` parameter is expected to be a string which indicates the name - of the user to connect to. - - The ``proxy_user`` parameter is expected to be a string which indicates the - name of the proxy user to connect to. If this value is not specified, it - will be parsed out of user if user is in the form "user[proxy_user]". - - The ``password`` parameter expected to be a string which indicates the - password for the user. - - The ``newpassword`` parameter is expected to be a string which indicates - the new password for the user. The new password will take effect - immediately upon a successful connection to the database. - - The ``wallet_password`` parameter is expected to be a string which - indicates the password to use to decrypt the PEM-encoded wallet, if it is - encrypted. - - The ``access_token`` parameter is expected to be a string or a 2-tuple or - a callable. If it is a string, it specifies an Azure AD OAuth2 token used - for Open Authorization (OAuth 2.0) token based authentication. If it is a - 2-tuple, it specifies the token and private key strings used for Oracle - Cloud Infrastructure (OCI) Identity and Access Management (IAM) token based - authentication. If it is a callable, it returns either a string or a - 2-tuple used for OAuth 2.0 or OCI IAM token based authentication and is - useful when the pool needs to expand and create new connections but the - current authentication token has expired. - - The ``host`` parameter is expected to be a string which specifies the name - or IP address of the machine hosting the listener, which handles the - initial connection to the database. - - The ``port`` parameter is expected to be an integer which indicates the - port number on which the listener is listening. The default value is - *1521*. - - The ``protocol`` parameter is expected to be one of the strings *tcp* or - *tcps* which indicates whether to use unencrypted network traffic or - encrypted network traffic (TLS). The default value is *tcp*. - - The ``https_proxy`` parameter is expected to be a string which indicates - the name or IP address of a proxy host to use for tunneling secure - connections. - - The ``https_proxy_port`` parameter is expected to be an integer which - indicates the port that is to be used to communicate with the proxy host. - The default value is *0*. - - The ``service_name`` parameter is expected to be a string which indicates - the service name of the database. - - The ``instance_name`` parameter is expected to be a string which indicates - the instance name of the database. - - The ``sid`` parameter is expected to be a string which indicates the SID of - the database. It is recommended to use ``service_name`` instead. - - The ``server_type`` parameter is expected to be a string that indicates the - type of server connection that should be established. If specified, it - should be one of *dedicated*, *shared*, or *pooled*. - - The ``cclass`` parameter is expected to be a string that identifies the - connection class to use for :ref:`drcp`. - - The ``purity`` parameter is expected to be one of the - :ref:`oracledb.PURITY_* ` constants that identifies the - purity to use for DRCP. The purity will internally default to - :data:`~oracledb.PURITY_SELF` for pooled connections. For standalone - connections, the purity will internally default to - :data:`~oracledb.PURITY_NEW`. - - The ``expire_time`` parameter is expected to be an integer which indicates - the number of minutes between the sending of keepalive probes. If this - parameter is set to a value greater than zero it enables keepalive. The - default value is *0*. - - The ``retry_count`` parameter is expected to be an integer that identifies - the number of times that a connection attempt should be retried before the - attempt is terminated. The default value is *0*. - - The ``retry_delay`` parameter is expected to be an integer that identifies - the number of seconds to wait before making a new connection attempt. The - default value is *1*. - - The ``tcp_connect_timeout`` parameter is expected to be a float that - indicates the maximum number of seconds to wait for establishing a - connection to the database host. The default value is *20.0*. - - The ``ssl_server_dn_match`` parameter is expected to be a boolean that - indicates whether the server certificate distinguished name (DN) should be - matched in addition to the regular certificate verification that is - performed. Note that if the ``ssl_server_cert_dn`` parameter is not - provided, host name matching is performed instead. The default value is - *True*. - - The ``ssl_server_cert_dn`` parameter is expected to be a string that - indicates the distinguished name (DN) which should be matched with the - server. This value is ignored if the ``ssl_server_dn_match`` parameter is - not set to the value *True*. - - The ``wallet_location`` parameter is expected to be a string that - identifies the directory where the wallet can be found. In python-oracledb - Thin mode, this must be the directory of the PEM-encoded wallet file, - ewallet.pem. - - The ``events`` parameter is ignored in the python-oracledb Thin mode. - - The ``externalauth`` parameter is ignored in the python-oracledb Thin mode. - - If the ``mode`` parameter is specified, it must be one of the - :ref:`connection authorization modes ` - which are defined at the module level. The default value is - :data:`oracledb.AUTH_MODE_DEFAULT`. - - The ``disable_oob`` parameter is expected to be a boolean that indicates - whether out-of-band breaks should be disabled. This value has no effect on - Windows which does not support this functionality. The default value is - *False*. - - The ``stmtcachesize`` parameter is expected to be an integer which - specifies the initial size of the statement cache. The default is the - value of :attr:`defaults.stmtcachesize`. - - The ``tag`` parameter is ignored in the python-oracledb Thin mode. - - The ``matchanytag`` parameter is ignored in the python-oracledb Thin mode. - - The ``config_dir`` parameter is expected to be a string that indicates the - directory in which :ref:`optional configuration files ` are - found. The default is the value of :attr:`defaults.config_dir`. - - The ``appcontext`` parameter is expected to be a list of 3-tuples that - identifies the application context used by the connection. This parameter - should contain namespace, name, and value and each entry in the tuple - should be a string. - - The ``shardingkey`` parameter and ``supershardingkey`` parameters are - ignored in the python-oracledb Thin mode. - - The ``debug_jdwp`` parameter is expected to be a string with the format - `host=;port=` that specifies the host and port of the PL/SQL - debugger. This allows using the Java Debug Wire Protocol (JDWP) to debug - PL/SQL code called by python-oracledb. - - The ``connection_id_prefix`` parameter is expected to be a string and is - added to the beginning of the generated ``connection_id`` that is sent to - the database for `tracing `__. - - The ``ssl_context`` parameter is expected to be an SSLContext object used - for connecting to the database using TLS. This SSL context will be - modified to include the private key or any certificates found in a - separately supplied wallet. This parameter should only be specified if - the default SSLContext object cannot be used. - - The ``sdu`` parameter is expected to be an integer that returns the - requested size of the Session Data Unit (SDU), in bytes. The value tunes - internal buffers used for communication to the database. Bigger values can - increase throughput for large queries or bulk data loads, but at the cost - of higher memory use. The SDU size that will actually be used is - negotiated down to the lower of this value and the database network SDU - configuration value. See the `SQL*Net documentation `__ for more details. The default value is *8192* bytes. - - The ``pool_boundary`` parameter is expected to be one of the strings - *statement* or *transaction* which indicates when pooled :ref:`DRCP ` - or PRCP connections can be returned to the pool. If the value is - *statement*, then pooled DRCP or PRCP connections are implicitly released - back to the DRCP or PRCP pool when the connection is stateless (that is, - there are no active cursors, active transactions, temporary tables, or - temporary LOBs). If the value is *transaction*, then pooled DRCP or PRCP - connections are implicitly released back to the DRCP or PRCP pool when - either one of the methods :meth:`AsyncConnection.commit()` or - :meth:`AsyncConnection.rollback()` are called. This parameter requires the - use of DRCP or PRCP with Oracle Database 23ai (or later). See - :ref:`implicitconnpool` for more information. This value is used in both - the python-oracledb Thin and Thick modes. - - The ``use_tcp_fast_open`` parameter is expected to be a boolean which - indicates whether to use TCP Fast Open which is an `Oracle Autonomous - Database Serverless (ADB-S) `__ specific feature that can - reduce the latency in round-trips to the database after a connection has - been established. This feature is only available with certain versions of - ADB-S. This value is used in both python-oracledb Thin and Thick modes. - The default value is *False*. - - The ``ssl_version`` parameter is expected to be one of the constants - *ssl.TLSVersion.TLSv1_2* or *ssl.TLSVersion.TLSv1_3* which identifies the - TLS protocol version used. These constants are defined in the Python - `ssl `__ module. This - parameter can be specified when establishing connections with the protocol - *tcps*. This value is used in both python-oracledb Thin and Thick modes. - The value *ssl.TLSVersion.TLSv1_3* requires Oracle Database 23ai. If you - are using python-oracledb Thick mode, Oracle Client 23ai is additionally - required. - - The ``use_sni`` parameter is expected to be a boolean which indicates - whether to use the TLS Server Name Indication (SNI) extension to bypass the - second TLS negotiation that would otherwise be required. This parameter is - used in both python-oracledb Thin and Thick modes. This parameter requires - Oracle Database 23.7. The default value is *False*. See the `SQL*Net - documentation `__ for more details. - - The ``program`` parameter is expected to be a string which specifies the - name of the executable program or application connected to Oracle - Database. This value is only used in the python-oracledb Thin mode. The - default is the value of :attr:`defaults.program`. - - The ``machine`` parameter is expected to be a string which specifies the - machine name of the client connecting to Oracle Database. This value is - only used in the python-oracledb Thin mode. The default is the value of - :attr:`defaults.machine`. - - The ``terminal`` parameter is expected to be a string which specifies the - terminal identifier from which the connection originates. This value is - only used in the python-oracledb Thin mode. The default is the value of - :attr:`defaults.terminal`. - - The ``osuser`` parameter is expected to be a string which specifies the - operating system user that initiates the database connection. This value - is only used in the python-oracledb Thin mode. The default value is the - value of :attr:`defaults.osuser`. - - The ``driver_name`` parameter is expected to be a string which specifies - the driver used by the client to connect to Oracle Database. This value - is used in both the python-oracledb Thin and Thick modes. The default is - the value of :attr:`defaults.driver_name`. - - The ``extra_auth_params`` parameter is expected to be a dictionary - containing the configuration parameters necessary for Oracle Database - authentication using :ref:`OCI ` or :ref:`Azure - ` cloud native authentication plugins. - This value is used in both the python-oracledb Thin and Thick modes. See - :ref:`tokenauth`. - - The ``thick_mode_dsn_passthrough`` and ``handle`` parameters are ignored in - python-oracledb Thin mode. + The ``pool_name`` parameter was added. .. versionchanged:: 3.0.0 @@ -800,850 +95,15 @@ Oracledb Methods The ``connection_id_prefix`` parameter was added. -.. function:: ConnectParams(user=None, proxy_user=None, password=None, \ - newpassword=None, wallet_password=None, access_token=None, host=None, \ - port=1521, protocol="tcp", https_proxy=None, https_proxy_port=0, \ - service_name=None, instance_name=None, sid=None, server_type=None, \ - cclass=None, purity=oracledb.PURITY_DEFAULT, expire_time=0, \ - retry_count=0, retry_delay=1, tcp_connect_timeout=20.0, \ - ssl_server_dn_match=True, ssl_server_cert_dn=None, \ - wallet_location=None, events=False, externalauth=False, \ - mode=oracledb.AUTH_MODE_DEFAULT, disable_oob=False, \ - stmtcachesize=oracledb.defaults.stmtcachesize, edition=None, \ - tag=None, matchanytag=False, config_dir=oracledb.defaults.config_dir, \ - appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, \ - connection_id_prefix=None, ssl_context=None, sdu=8192, \ - pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \ - program=oracledb.defaults.program, machine=oracledb.defaults.machine, \ - terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \ - driver_name=oracledb.defaults.driver_name, use_sni=False, \ - thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \ - extra_auth_params=None, handle=0) - - Contains all the parameters that can be used to establish a connection to - the database. - - Creates and returns a :ref:`ConnectParams Object `. The object - can be passed to :meth:`oracledb.connect()`. - - All the parameters are optional. - - The ``user`` parameter is expected to be a string which indicates the name - of the user to connect to. This value is used in both the python-oracledb - Thin and :ref:`Thick ` modes. - - The ``proxy_user`` parameter is expected to be a string which indicates the - name of the proxy user to connect to. If this value is not specified, it - will be parsed out of user if user is in the form "user[proxy_user]". This - value is used in both the python-oracledb Thin and Thick modes. - - The ``password`` parameter expected to be a string which indicates the - password for the user. This value is used in both the python-oracledb Thin - and Thick modes. - - The ``newpassword`` parameter is expected to be a string which indicates - the new password for the user. The new password will take effect - immediately upon a successful connection to the database. This value is - used in both the python-oracledb Thin and Thick modes. - - The ``wallet_password`` parameter is expected to be a string which - indicates the password to use to decrypt the PEM-encoded wallet, if it is - encrypted. This value is only used in python-oracledb Thin mode. The - ``wallet_password`` parameter is not needed for cwallet.sso files that are - used in the python-oracledb Thick mode. - - The ``access_token`` parameter is expected to be a string or a 2-tuple or - a callable. If it is a string, it specifies an Azure AD OAuth2 token used - for Open Authorization (OAuth 2.0) token based authentication. If it is a - 2-tuple, it specifies the token and private key strings used for Oracle - Cloud Infrastructure (OCI) Identity and Access Management (IAM) token based - authentication. If it is a callable, it returns either a string or a - 2-tuple used for OAuth 2.0 or OCI IAM token based authentication and is - useful when the pool needs to expand and create new connections but the - current authentication token has expired. This value is used in both the - python-oracledb Thin and Thick modes. - - The ``host`` parameter is expected to be a string which specifies the name - or IP address of the machine hosting the listener, which handles the - initial connection to the database. This value is used in both the - python-oracledb Thin and Thick modes. - - The ``port`` parameter is expected to be an integer which indicates the - port number on which the listener is listening. The default value is - *1521*. This value is used in both the python-oracledb Thin and Thick - modes. - - The ``protocol`` parameter is expected to be one of the strings *tcp* or - *tcps* which indicates whether to use unencrypted network traffic or - encrypted network traffic (TLS). The default value is *tcp*. This value is - used in both the python-oracledb Thin and Thick modes. - - The ``https_proxy`` parameter is expected to be a string which indicates - the name or IP address of a proxy host to use for tunneling secure - connections. This value is used in both the python-oracledb Thin and Thick - modes. - - The ``https_proxy_port`` parameter is expected to be an integer which - indicates the port that is to be used to communicate with the proxy host. - The default value is *0*. This value is used in both the python-oracledb Thin - and Thick modes. - - The ``service_name`` parameter is expected to be a string which indicates - the service name of the database. This value is used in both the - python-oracledb Thin and Thick modes. - - The ``instance_name`` parameter is expected to be a string which indicates - the instance name of the database. This value is used in both the - python-oracledb Thin and Thick modes. - - The ``sid`` parameter is expected to be a string which indicates the SID of - the database. It is recommended to use ``service_name`` instead. This value - is used in both the python-oracledb Thin and Thick modes. - - The ``server_type`` parameter is expected to be a string that indicates the - type of server connection that should be established. If specified, it - should be one of *dedicated*, *shared*, or *pooled*. This value is used in - both the python-oracledb Thin and Thick modes. - - The ``cclass`` parameter is expected to be a string that identifies the - connection class to use for :ref:`drcp`. This value is used in both the - python-oracledb Thin and Thick modes. - - The ``purity`` parameter is expected to be one of the - :ref:`oracledb.PURITY_* ` constants that identifies the - purity to use for DRCP. This value is used in both the python-oracledb Thin - and Thick modes. The purity will internally default to - :data:`~oracledb.PURITY_SELF` for pooled connections . For standalone - connections, the purity will internally default to - :data:`~oracledb.PURITY_NEW`. - - The ``expire_time`` parameter is expected to be an integer which indicates - the number of minutes between the sending of keepalive probes. If this - parameter is set to a value greater than zero it enables keepalive. This - value is used in both the python-oracledb Thin and Thick modes. The default - value is *0*. - - The ``retry_count`` parameter is expected to be an integer that identifies - the number of times that a connection attempt should be retried before the - attempt is terminated. This value is used in both the python-oracledb Thin - and Thick modes. The default value is *0*. - - The ``retry_delay`` parameter is expected to be an integer that identifies - the number of seconds to wait before making a new connection attempt. This - value is used in both the python-oracledb Thin and Thick modes. The default - value is *1*. - - The ``tcp_connect_timeout`` parameter is expected to be a float that - indicates the maximum number of seconds to wait for establishing a - connection to the database host. This value is used in both the - python-oracledb Thin and Thick modes. The default value is *20.0*. - - The ``ssl_server_dn_match`` parameter is expected to be a boolean that - indicates whether the server certificate distinguished name (DN) should be - matched in addition to the regular certificate verification that is - performed. Note that if the ``ssl_server_cert_dn`` parameter is not - provided, host name matching is performed instead. This value is used in - both the python-oracledb Thin and Thick modes. The default value is *True*. - - The ``ssl_server_cert_dn`` parameter is expected to be a string that - indicates the distinguished name (DN) which should be matched with the - server. This value is ignored if the ``ssl_server_dn_match`` parameter is - not set to the value *True*. This value is used in both the python-oracledb - Thin and Thick modes. - - The ``wallet_location`` parameter is expected to be a string that - identifies the directory where the wallet can be found. In python-oracledb - Thin mode, this must be the directory of the PEM-encoded wallet file, - ewallet.pem. In python-oracledb Thick mode, this must be the directory of - the file, cwallet.sso. This value is used in both the python-oracledb Thin - and Thick modes. - - The ``events`` parameter is expected to be a boolean that specifies whether - the events mode should be enabled. This value is only used in the - python-oracledb Thick mode. This parameter is needed for continuous - query notification and high availability event notifications. The default - value is *False*. - - The ``externalauth`` parameter is a boolean that specifies whether external - authentication should be used. This value is only used in the - python-oracledb Thick mode. The default value is *False*. For standalone - connections, external authentication occurs when the ``user`` and - ``password`` attributes are not used. If these attributes are not used, you - can optionally set the ``externalauth`` attribute to *True*, which may aid - code auditing. - - The ``mode`` parameter is expected to be an integer that identifies the - authorization mode to use. This value is used in both the python-oracledb - Thin and Thick modes.The default value is - :data:`oracledb.AUTH_MODE_DEFAULT`. - - The ``disable_oob`` parameter is expected to be a boolean that indicates - whether out-of-band breaks should be disabled. This value is only used - in the python-oracledb Thin mode and has no effect on Windows which - does not support this functionality. The default value is *False*. - - The ``stmtcachesize`` parameter is expected to be an integer that - identifies the initial size of the statement cache. This value is used in - both the python-oracledb Thin and Thick modes. The default is the value of - :attr:`defaults.stmtcachesize`. - - The ``edition`` parameter is expected to be a string that indicates the - edition to use for the connection. It requires Oracle Database 11.2, or - later. This parameter cannot be used simultaneously with the ``cclass`` - parameter. - - The ``tag`` parameter is expected to be a string that identifies the type of - connection that should be returned from a pool. This value is only used - in the python-oracledb Thick mode. - - The ``matchanytag`` parameter is expected to be a boolean specifying - whether any tag can be used when acquiring a connection from the pool. This - value is only used in the python-oracledb Thick mode when acquiring a - connection from a pool. The default value is *False*. - - The ``config_dir`` parameter is expected to be a string that indicates the - directory in which the :ref:`tnsnames.ora ` configuration file - is located. - - The ``appcontext`` parameter is expected to be a list of 3-tuples that - identifies the application context used by the connection. This parameter - should contain namespace, name, and value and each entry in the tuple - should be a string. - - The ``shardingkey`` parameter and ``supershardingkey`` parameters, if - specified, are expected to be a sequence of values which identifies the - database shard to connect to. The key values can be a list of strings, - numbers, bytes, or dates. These values are only used in the - python-oracledb Thick mode and are ignored in the Thin mode. See - :ref:`connsharding`. - - The ``debug_jdwp`` parameter is expected to be a string with the format - `host=;port=` that specifies the host and port of the PL/SQL - debugger. This allows using the Java Debug Wire Protocol (JDWP) to debug - PL/SQL code invoked by python-oracledb. This value is only used in the - python-oracledb Thin mode. For python-oracledb Thick mode, set the - ``ORA_DEBUG_JDWP`` environment variable which has the same syntax. For more - information, see :ref:`applntracing`. - - The ``connection_id_prefix`` parameter is expected to be a string and is - added to the beginning of the generated ``connection_id`` that is sent to - the database for `tracing `__. This value - is only used in the python-oracledb Thin mode. - - The ``ssl_context`` parameter is expected to be an `SSLContext object - `__ which is used - for connecting to the database using TLS. This SSL context will be - modified to include the private key or any certificates found in a - separately supplied wallet. This parameter should only be specified if - the default SSLContext object cannot be used. This value is only used in - the python-oracledb Thin mode. - - The ``sdu`` parameter is expected to be an integer that returns the - requested size of the Session Data Unit (SDU), in bytes. The value tunes - internal buffers used for communication to the database. Bigger values can - increase throughput for large queries or bulk data loads, but at the cost - of higher memory use. The SDU size that will actually be used is - negotiated down to the lower of this value and the database network SDU - configuration value. See the `SQL*Net documentation `__ for more details. This value is used in both the - python-oracledb Thin and Thick modes. The default value is *8192* bytes. - - The ``pool_boundary`` parameter is expected to be one of the strings - *statement* or *transaction* which indicates when pooled :ref:`DRCP ` - or PRCP connections can be returned to the pool. If the value is - *statement*, then pooled DRCP or PRCP connections are implicitly released - back to the DRCP or PRCP pool when the connection is stateless (that is, - there are no active cursors, active transactions, temporary tables, or - temporary LOBs). If the value is *transaction*, then pooled DRCP or PRCP - connections are implicitly released back to the DRCP or PRCP pool when - either one of the methods :meth:`Connection.commit()` or - :meth:`Connection.rollback()` are called. This parameter requires the use - of DRCP or PRCP with Oracle Database 23ai (or later). See - :ref:`implicitconnpool` for more information. This value is used in both - the python-oracledb Thin and Thick modes. - - The ``use_tcp_fast_open`` parameter is expected to be a boolean which - indicates whether to use TCP Fast Open which is an `Oracle Autonomous - Database Serverless (ADB-S) `__ specific feature that can - reduce the latency in round-trips to the database after a connection has - been established. This feature is only available with certain versions of - ADB-S. This value is used in both python-oracledb Thin and Thick modes. - The default value is *False*. - - The ``ssl_version`` parameter is expected to be one of the constants - *ssl.TLSVersion.TLSv1_2* or *ssl.TLSVersion.TLSv1_3* which identifies the - TLS protocol version used. These constants are defined in the Python - `ssl `__ module. This - parameter can be specified when establishing connections with the protocol - "tcps". This value is used in both python-oracledb Thin and Thick modes. - The value *ssl.TLSVersion.TLSv1_3* requires Oracle Database 23ai. If you - are using python-oracledb Thick mode, Oracle Client 23ai is additionally - required. - - The ``use_sni`` parameter is expected to be a boolean which indicates - whether to use the TLS Server Name Indication (SNI) extension to bypass the - second TLS negotiation that would otherwise be required. This parameter is - used in both python-oracledb Thin and Thick modes. This parameter requires - Oracle Database 23.7. The default value is *False*. See the `SQL*Net - documentation `__ for more details. - - The ``program`` parameter is expected to be a string which specifies the - name of the executable program or application connected to Oracle - Database. This value is only used in the python-oracledb Thin mode. The - default is the value of :attr:`defaults.program`. - - The ``machine`` parameter is expected to be a string which specifies the - machine name of the client connecting to Oracle Database. This value is - only used in the python-oracledb Thin mode. The default is the value of - :attr:`defaults.machine`. - - The ``terminal`` parameter is expected to be a string which specifies the - terminal identifier from which the connection originates. This value is - only used in the python-oracledb Thin mode. The default is the value of - :attr:`defaults.terminal`. - - The ``osuser`` parameter is expected to be a string which specifies the - operating system user that initiates the database connection. This value - is only used in the python-oracledb Thin mode. The default value is the - value of :attr:`defaults.osuser`. - - The ``driver_name`` parameter is expected to be a string which specifies - the driver used by the client to connect to Oracle Database. This value - is used in both the python-oracledb Thin and Thick modes. The default is - the value of :attr:`defaults.driver_name`. - - The ``thick_mode_dsn_passthrough`` parameter is expected to be a boolean - which indicates whether the connect string should be passed unchanged to - the Oracle Client libraries for parsing when using python-oracledb Thick - mode. If this parameter is set to *False* in Thick mode, connect strings - are parsed by python-oracledb itself and a generated connect descriptor is - sent to the Oracle Client libraries. This value is only used in the - python-oracledb Thick mode. The default value is the value of - :attr:`defaults.thick_mode_dsn_passthrough`. For more information, see - :ref:`usingconfigfiles`. - - The ``extra_auth_params`` parameter is expected to be a dictionary - containing the configuration parameters necessary for Oracle Database - authentication using :ref:`OCI ` or :ref:`Azure - ` cloud native authentication plugins. This value is - used in both the python-oracledb Thin and Thick modes. See - :ref:`tokenauth`. - - The ``handle`` parameter is expected to be an integer which represents a - pointer to a valid service context handle. This value is only used in the - python-oracledb Thick mode. It should be used with extreme caution. The - default value is *0*. - - .. versionchanged:: 3.0.0 - - The ``instance_name``, ``use_sni``, ``thick_mode_dsn_passthrough`` and - ``extra_auth_params`` parameters were added. - - .. versionchanged:: 2.5.0 - - The ``program``, ``machine``, ``terminal``, ``osuser``, and - ``driver_name`` parameters were added. Support for ``edition`` and - ``appcontext`` was added to python-oracledb Thin mode. - - .. versionchanged:: 2.3.0 - - The default value of the ``retry_delay`` parameter was changed from 0 - seconds to 1 second. The default value of the ``tcp_connect_timeout`` - parameter was changed from 60.0 seconds to 20.0 seconds. The - ``ssl_version`` parameter was added. - - .. versionchanged:: 2.1.0 - - The ``pool_boundary`` and ``use_tcp_fast_open`` parameters were added. - - .. versionchanged:: 2.0.0 - - The ``ssl_context`` and ``sdu`` parameters were added. - - .. versionchanged:: 1.4.0 +.. autofunction:: create_pipeline - The ``connection_id_prefix`` parameter was added. - -.. function:: create_pipeline() + .. versionadded:: 2.4.0 - Creates a :ref:`pipeline object ` which can be used to - process a set of operations against a database. +.. autofunction:: create_pool - .. versionadded:: 2.4.0 + .. versionchanged:: 3.2.0 -.. function:: create_pool(dsn=None, pool_class=oracledb.ConnectionPool, \ - pool_alias=None, params=None, min=1, max=2, increment=1, \ - connectiontype=oracledb.Connection, \ - getmode=oracledb.POOL_GETMODE_WAIT, homogeneous=True, timeout=0, \ - wait_timeout=0, max_lifetime_session=0, session_callback=None, \ - max_sessions_per_shard=0, soda_metadata_cache=False, ping_interval=60, \ - ping_timeout=5000, user=None, proxy_user=None, password=None, \ - newpassword=None, wallet_password=None, access_token=None, host=None, \ - port=1521, protocol="tcp", https_proxy=None, https_proxy_port=0, \ - service_name=None, instance_name=None, sid=None, server_type=None, \ - cclass=None, purity=oracledb.PURITY_DEFAULT, expire_time=0, \ - retry_count=0, retry_delay=1, tcp_connect_timeout=20.0, \ - ssl_server_dn_match=True, ssl_server_cert_dn=None, \ - wallet_location=None, events=False, externalauth=False, \ - mode=oracledb.AUTH_MODE_DEFAULT, disable_oob=False, \ - stmtcachesize=oracledb.defaults.stmtcachesize, edition=None, \ - tag=None, matchanytag=False, config_dir=oracledb.defaults.config_dir, \ - appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, \ - connection_id_prefix=None, ssl_context=None, sdu=8192, \ - pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \ - program=oracledb.defaults.program, machine=oracledb.defaults.machine, \ - terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \ - driver_name=oracledb.defaults.driver_name, use_sni=False, \ - thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \ - extra_auth_params=None, handle=0) - - Creates a connection pool with the supplied parameters and returns the - :ref:`ConnectionPool object ` for the pool. See :ref:`Connection - pooling ` for more information. - - This function is the equivalent of the ``cx_Oracle.SessionPool()`` - function. The use of ``SessionPool()`` has been deprecated in - python-oracledb. - - Not all parameters apply to both python-oracledb Thin and :ref:`Thick - ` modes. - - Some values, such as the database host name, can be specified as - parameters, as part of the connect string, and in the params object. If a - ``dsn`` (data source name) parameter is passed, the python-oracledb Thick - mode will use the string to connect, otherwise a connection string is - internally constructed from the individual parameters and params object - values, with the individual parameters having precedence. In - python-oracledb's default Thin mode, a connection string is internally used - that contains all relevant values specified. The precedence in Thin mode - is that values in any ``dsn`` parameter override values passed as - individual parameters, which themselves override values set in the - ``params`` parameter object. Similar precedence rules also apply to other - values. - - Python-oracledb connection pools must be created, used and closed within - the same process. Sharing pools or connections across processes has - unpredictable behavior. Using connection pools in multi-threaded - architectures is supported. Multi-process architectures that cannot be - converted to threading may get some benefit from :ref:`drcp`. - - In python-oracledb Thick mode, connection pooling is handled by Oracle's - `Session pooling `__ technology. - This allows python-oracledb applications to support features like - `Application Continuity `__. - - The ``user``, ``password``, and ``dsn`` parameters are the same as for - :meth:`oracledb.connect()`. - - The ``pool_class`` parameter is expected to be a - :ref:`ConnectionPool Object ` or a subclass of ConnectionPool. - - The ``pool_alias`` parameter is expected to be a string representing the - name used to store and reference the pool in the python-oracledb connection - pool cache. If this parameter is not specified, then the pool will not be - added to the cache. The value of this parameter can be used with the - :meth:`oracledb.get_pool()` and :meth:`oracledb.connect()` methods to - access the pool. See :ref:`connpoolcache`. - - The ``params`` parameter is expected to be of type :ref:`PoolParams - ` and contains parameters that are used to create the pool. - If this parameter is not specified, the additional keyword parameters will - be used to create an instance of PoolParams. If both the params parameter - and additional keyword parameters are specified, the values in the keyword - parameters have precedence. Note that if a ``dsn`` is also supplied, then - in the python-oracledb Thin mode, the values of the parameters specified - (if any) within the ``dsn`` will override the values passed as additional - keyword parameters, which themselves override the values set in the - ``params`` parameter object. - - The ``min``, ``max`` and ``increment`` parameters control pool growth - behavior. A fixed pool size where ``min`` equals ``max`` is - :ref:`recommended ` to help prevent connection storms and to - help overall system stability. The ``min`` parameter is the number of - connections opened when the pool is created. The default value of the - ``min`` parameter is *1*. The ``increment`` parameter is the number of - connections that are opened whenever a connection request exceeds the - number of currently open connections. The default value of the - ``increment`` parameter is *1*. The ``max`` parameter is the maximum number - of connections that can be open in the connection pool. The default value - of the ``max`` parameter is *2*. - - If the ``connectiontype`` parameter is specified, all calls to - :meth:`ConnectionPool.acquire()` will create connection objects of that - type, rather than the base type defined at the module level. - - The ``getmode`` parameter determines the behavior of - :meth:`ConnectionPool.acquire()`. One of the constants - :data:`oracledb.POOL_GETMODE_WAIT`, :data:`oracledb.POOL_GETMODE_NOWAIT`, - :data:`oracledb.POOL_GETMODE_FORCEGET`, or - :data:`oracledb.POOL_GETMODE_TIMEDWAIT`. The default value is - :data:`oracledb.POOL_GETMODE_WAIT`. - - The ``homogeneous`` parameter is a boolean that indicates whether the - connections are homogeneous (same user) or heterogeneous (multiple - users). The default value is *True*. - - The ``timeout`` parameter is the length of time (in seconds) that a - connection may remain idle in the pool before it is terminated. This - applies only when the pool has more than ``min`` connections open, allowing - it to shrink to the specified minimum size. The default value is *0* - seconds. A value of *0* means there is no limit. - - The ``wait_timeout`` parameter is the length of time (in milliseconds) that - a caller should wait when acquiring a connection from the pool with - ``getmode`` set to :data:`oracledb.POOL_GETMODE_TIMEDWAIT`. The default - value is *0* milliseconds. - - The ``max_lifetime_session`` parameter is the length of time (in seconds) - that a pooled connection may exist since first being created. The default - value is *0*. A value of *0* means that there is no limit. Connections - become candidates for termination when they are acquired or released back - to the pool and have existed for longer than ``max_lifetime_session`` - seconds. In python-oracledb Thick mode, Oracle Client libraries 12.1 or - later must be used and, prior to Oracle Client 21, cleanup only occurs when - the pool is accessed. - - The ``session_callback`` parameter is a callable that is invoked when a - connection is returned from the pool for the first time, or when the - connection tag differs from the one requested. - - The ``max_sessions_per_shard`` parameter is the maximum number of - connections that may be associated with a particular shard. This value is - only used in the python-oracledb Thick mode and is ignored in the - python-oracledb Thin mode. The default value is *0*. - - The ``soda_metadata_cache`` parameter is a boolean that indicates whether - or not the SODA metadata cache should be enabled. This value is only used - in the python-oracledb Thick mode and is ignored in the python-oracledb - Thin mode. The default value is *False*. - - The ``ping_interval`` parameter is the length of time (in seconds) after - which an unused connection in the pool will be a candidate for pinging when - :meth:`ConnectionPool.acquire()` is called. If the ping to the database - indicates the connection is not alive a replacement connection will be - returned by :meth:`~ConnectionPool.acquire()`. If ``ping_interval`` is a - negative value, then the ping functionality will be disabled. The default - value is *60* seconds. - - The ``ping_timeout`` parameter is the maximum length of time (in - milliseconds) that :meth:`ConnectionPool.acquire()` waits for a connection - to respond to any internal ping to the database. If the ping does not - respond within the specified time, then the connection is destroyed and - :meth:`~ConnectionPool.acquire()` returns a different connection. This - value is used in both the python-oracledb Thin and Thick modes. The default - value is *5000* milliseconds. - - The ``proxy_user`` parameter is expected to be a string which indicates the - name of the proxy user to connect to. If this value is not specified, it - will be parsed out of user if user is in the form "user[proxy_user]". This - value is used in both the python-oracledb Thin and Thick modes. - - The ``newpassword`` parameter is expected to be a string which indicates - the new password for the user. The new password will take effect - immediately upon a successful connection to the database. This value is - used in both the python-oracledb Thin and Thick modes. - - The ``wallet_password`` parameter is expected to be a string which - indicates the password to use to decrypt the PEM-encoded wallet, if it is - encrypted. This value is only used in python-oracledb Thin mode. The - ``wallet_password`` parameter is not needed for cwallet.sso files that are - used in the python-oracledb Thick mode. - - The ``access_token`` parameter is expected to be a string or a 2-tuple or - a callable. If it is a string, it specifies an Azure AD OAuth2 token used - for Open Authorization (OAuth 2.0) token based authentication. If it is a - 2-tuple, it specifies the token and private key strings used for Oracle - Cloud Infrastructure (OCI) Identity and Access Management (IAM) token based - authentication. If it is a callable, it returns either a string or a - 2-tuple used for OAuth 2.0 or OCI IAM token based authentication and is - useful when the pool needs to expand and create new connections but the - current authentication token has expired. This value is used in both the - python-oracledb Thin and Thick modes. - - The ``host`` parameter is expected to be a string which specifies the name - or IP address of the machine hosting the listener, which handles the - initial connection to the database. This value is used in both the - python-oracledb Thin and Thick modes. - - The ``port`` parameter is expected to be an integer which indicates the - port number on which the listener is listening. The default value is - *1521*. This value is used in both the python-oracledb Thin and Thick - modes. - - The ``protocol`` parameter is expected to be one of the strings *tcp* or - *tcps* which indicates whether to use unencrypted network traffic or - encrypted network traffic (TLS). The default value is *tcp*. This value is - used in both the python-oracledb Thin and Thick modes. - - The ``https_proxy`` parameter is expected to be a string which indicates - the name or IP address of a proxy host to use for tunneling secure - connections. This value is used in both the python-oracledb Thin and Thick - modes. - - The ``https_proxy_port`` parameter is expected to be an integer which - indicates the port that is to be used to communicate with the proxy host. - The default value is *0*. This value is used in both the python-oracledb - Thin and Thick modes. - - The ``service_name`` parameter is expected to be a string which indicates - the service name of the database. This value is used in both the - python-oracledb Thin and Thick modes. - - The ``instance_name`` parameter is expected to be a string which indicates - the instance name of the database. This value is used in both the - python-oracledb Thin and Thick modes. - - The ``sid`` parameter is expected to be a string which indicates the SID of - the database. It is recommended to use ``service_name`` instead. This value - is used in both the python-oracledb Thin and Thick modes. - - The ``server_type`` parameter is expected to be a string that indicates the - type of server connection that should be established. If specified, it - should be one of *dedicated*, *shared*, or *pooled*. This value is used in - both the python-oracledb Thin and Thick modes. - - The ``cclass`` parameter is expected to be a string that identifies the - connection class to use for :ref:`drcp`. This value is used in both the - python-oracledb Thin and Thick modes. - - The ``purity`` parameter is expected to be one of the - :ref:`oracledb.PURITY_* ` constants that identifies the - purity to use for DRCP. This value is used in both the python-oracledb Thin - and Thick modes. The purity will internally default to - :data:`~oracledb.PURITY_SELF` for pooled connections. - - The ``expire_time`` parameter is expected to be an integer which indicates - the number of minutes between the sending of keepalive probes. If this - parameter is set to a value greater than zero it enables keepalive. This - value is used in both the python-oracledb Thin and Thick modes. The default - value is *0* minutes. - - The ``retry_count`` parameter is expected to be an integer that identifies - the number of times that a connection attempt should be retried before the - attempt is terminated. This value is used in both the python-oracledb Thin - and Thick modes. The default value is *0*. - - The ``retry_delay`` parameter is expected to be an integer that identifies - the number of seconds to wait before making a new connection attempt. This - value is used in both the python-oracledb Thin and Thick modes. The default - value is *1* seconds. - - The ``tcp_connect_timeout`` parameter is expected to be a float that - indicates the maximum number of seconds to wait for establishing a - connection to the database host. This value is used in both the - python-oracledb Thin and Thick modes. The default value is *20.0* seconds. - - The ``ssl_server_dn_match`` parameter is expected to be a boolean that - indicates whether the server certificate distinguished name (DN) should be - matched in addition to the regular certificate verification that is - performed. Note that if the ``ssl_server_cert_dn`` parameter is not - provided, host name matching is performed instead. This value is used in - both the python-oracledb Thin and Thick modes. The default value is *True*. - - The ``ssl_server_cert_dn`` parameter is expected to be a string that - indicates the distinguished name (DN) which should be matched with the - server. This value is ignored if the ``ssl_server_dn_match`` parameter is - not set to the value *True*. This value is used in both the python-oracledb - Thin and Thick modes. - - The ``wallet_location`` parameter is expected to be a string that - identifies the directory where the wallet can be found. In python-oracledb - Thin mode, this must be the directory of the PEM-encoded wallet file, - ewallet.pem. In python-oracledb Thick mode, this must be the directory of - the file, cwallet.sso. This value is used in both the python-oracledb Thin - and Thick modes. - - The ``events`` parameter is expected to be a boolean that specifies whether - the events mode should be enabled. This value is only used in the - python-oracledb Thick mode and is ignored in the Thin mode. This parameter - is needed for continuous query notification and high availability event - notifications. The default value is *False*. - - The ``externalauth`` parameter is a boolean that determines whether to use - external authentication. This value is only used in python-oracledb Thick - mode and is ignored in Thin mode. The default value is *False*. For pooled - connections in Thick mode, external authentication requires the use of a - heterogeneous pool. For this reason, you must set the ``homogeneous`` - parameter to *False*. See :ref:`extauth`. - - If the ``mode`` parameter is specified, it must be one of the - :ref:`connection authorization modes ` - which are defined at the module level. This value is used in both the - python-oracledb Thin and Thick modes.The default value is - :data:`oracledb.AUTH_MODE_DEFAULT`. - - The ``disable_oob`` parameter is expected to be a boolean that indicates - whether out-of-band breaks should be disabled. This value is only used - in the python-oracledb Thin mode and has no effect on Windows which - does not support this functionality. The default value is *False*. - - The ``stmtcachesize`` parameter is expected to be an integer which - specifies the initial size of the statement cache. This value is used in - both the python-oracledb Thin and Thick modes. The default is the value of - :attr:`defaults.stmtcachesize`. - - The ``edition`` parameter is expected to be a string that indicates the - edition to use for the connection. It requires Oracle Database 11.2, or - later. This parameter cannot be used simultaneously with the ``cclass`` - parameter. - - The ``tag`` parameter is expected to be a string that identifies the type - of connection that should be returned from a pool. This value is only used - in the python-oracledb Thick mode and is ignored in the Thin mode. - - The ``matchanytag`` parameter is expected to be a boolean specifying - whether any tag can be used when acquiring a connection from the pool. This - value is only used in the python-oracledb Thick mode when acquiring a - connection from a pool. This value is ignored in the python-oracledb Thin - mode. The default value is *False*. - - The ``config_dir`` parameter is expected to be a string that indicates the - directory in which the :ref:`tnsnames.ora ` configuration file - is located. The default is the value of :attr:`defaults.config_dir`. - - The ``appcontext`` parameter is expected to be a list of 3-tuples that - identifies the application context used by the connection. This parameter - should contain namespace, name, and value and each entry in the tuple - should be a string. - - The ``shardingkey`` parameter and ``supershardingkey`` parameters, if - specified, are expected to be a sequence of values which identifies the - database shard to connect to. The key values can be a list of strings, - numbers, bytes, or dates. These values are only used in the - python-oracledb Thick mode and are ignored in the Thin mode. See - :ref:`connsharding`. - - The ``debug_jdwp`` parameter is expected to be a string with the format - `host=;port=` that specifies the host and port of the PL/SQL - debugger. This allows using the Java Debug Wire Protocol (JDWP) to debug - PL/SQL code invoked by python-oracledb. This value is only used in the - python-oracledb Thin mode. For python-oracledb Thick mode, set the - ``ORA_DEBUG_JDWP`` environment variable which has the same syntax. For more - information, see :ref:`applntracing`. - - The ``connection_id_prefix`` parameter is expected to be a string and is - added to the beginning of the generated ``connection_id`` that is sent to - the database for `tracing `__. This value - is only used in the python-oracledb Thin mode. - - The ``ssl_context`` parameter is expected to be an `SSLContext object - `__ which is used - for connecting to the database using TLS. This SSL context will be - modified to include the private key or any certificates found in a - separately supplied wallet. This parameter should only be specified if - the default SSLContext object cannot be used. This value is only used in - the python-oracledb Thin mode. - - The ``sdu`` parameter is expected to be an integer that returns the - requested size of the Session Data Unit (SDU), in bytes. The value tunes - internal buffers used for communication to the database. Bigger values can - increase throughput for large queries or bulk data loads, but at the cost - of higher memory use. The SDU size that will actually be used is - negotiated down to the lower of this value and the database network SDU - configuration value. See the `SQL*Net documentation `__ for more details. This value is used in both the - python-oracledb Thin and Thick modes. The default value is *8192* bytes. - - The ``pool_boundary`` parameter is expected to be one of the strings - *statement* or *transaction* which indicates when pooled :ref:`DRCP ` - or PRCP connections can be returned to the pool. If the value is - *statement*, then pooled DRCP or PRCP connections are implicitly released - back to the DRCP or PRCP pool when the connection is stateless (that is, - there are no active cursors, active transactions, temporary tables, or - temporary LOBs). If the value is *transaction*, then pooled DRCP or PRCP - connections are implicitly released back to the DRCP or PRCP pool when - either one of the methods :meth:`Connection.commit()` or - :meth:`Connection.rollback()` are called. This parameter requires the use - of DRCP or PRCP with Oracle Database 23ai (or later). See - :ref:`implicitconnpool` for more information. This value is used in both - the python-oracledb Thin and Thick modes. - - The ``use_tcp_fast_open`` parameter is expected to be a boolean which - indicates whether to use TCP Fast Open which is an `Oracle Autonomous - Database Serverless (ADB-S) `__ specific feature that can - reduce the latency in round-trips to the database after a connection has - been established. This feature is only available with certain versions of - ADB-S. This value is used in both python-oracledb Thin and Thick modes. - The default value is *False*. - - The ``ssl_version`` parameter is expected to be one of the constants - *ssl.TLSVersion.TLSv1_2* or *ssl.TLSVersion.TLSv1_3* which identifies the - TLS protocol version used. These constants are defined in the Python - `ssl `__ module. This - parameter can be specified when establishing connections with the protocol - "tcps". This value is used in both python-oracledb Thin and Thick modes. - The value *ssl.TLSVersion.TLSv1_3* requires Oracle Database 23ai. If you - are using python-oracledb Thick mode, Oracle Client 23ai is additionally - required. - - The ``use_sni`` parameter is expected to be a boolean which indicates - whether to use the TLS Server Name Indication (SNI) extension to bypass the - second TLS negotiation that would otherwise be required. This parameter is - used in both python-oracledb Thin and Thick modes. This parameter requires - Oracle Database 23.7. The default value is *False*. See the `SQL*Net - documentation `__ for more details. - - The ``program`` parameter is expected to be a string which specifies the - name of the executable program or application connected to Oracle - Database. This value is only used in the python-oracledb Thin mode. The - default is the value of :attr:`defaults.program`. - - The ``machine`` parameter is expected to be a string which specifies the - machine name of the client connecting to Oracle Database. This value is - only used in the python-oracledb Thin mode. The default is the value of - :attr:`defaults.machine`. - - The ``terminal`` parameter is expected to be a string which specifies the - terminal identifier from which the connection originates. This value is - only used in the python-oracledb Thin mode. The default is the value of - :attr:`defaults.terminal`. - - The ``osuser`` parameter is expected to be a string which specifies the - operating system user that initiates the database connection. This value - is only used in the python-oracledb Thin mode. The default value is the - value of :attr:`defaults.osuser`. - - The ``driver_name`` parameter is expected to be a string which specifies - the driver used by the client to connect to Oracle Database. This value - is used in both the python-oracledb Thin and Thick modes. The default is - the value of :attr:`defaults.driver_name`. - - The ``thick_mode_dsn_passthrough`` parameter is expected to be a boolean - which indicates whether the connect string should be passed unchanged to - the Oracle Client libraries for parsing when using python-oracledb Thick - mode. If this parameter is set to *False* in Thick mode, connect strings - are parsed by python-oracledb itself and a generated connect descriptor is - sent to the Oracle Client libraries. This value is only used in the - python-oracledb Thick mode. The default value is - :attr:`defaults.thick_mode_dsn_passthrough`. For more information, see - :ref:`usingconfigfiles`. - - The ``extra_auth_params`` parameter is expected to be a dictionary - containing the configuration parameters necessary for Oracle Database - authentication using :ref:`OCI ` or :ref:`Azure - ` cloud native authentication plugins. This value is - used in both the python-oracledb Thin and Thick modes. See - :ref:`tokenauth`. - - If the ``handle`` parameter is specified, it must be of type OCISvcCtx\* - and is only of use when embedding Python in an application (like - PowerBuilder) which has already made the connection. The connection thus - created should *never* be used after the source handle has been closed or - destroyed. This value is only used in the python-oracledb Thick mode and - is ignored in the Thin mode. It should be used with extreme caution. The - default value is *0*. + The ``pool_name`` parameter was added. .. versionchanged:: 3.0.0 @@ -1676,381 +136,11 @@ Oracledb Methods The ``connection_id_prefix`` parameter was added. -.. function:: create_pool_async(dsn=None, \ - pool_class=oracledb.AsyncConnectionPool, pool_alias=None, \ - params=None, min=1, max=2, increment=1, \ - connectiontype=oracledb.AsyncConnection, \ - getmode=oracledb.POOL_GETMODE_WAIT, homogeneous=True, timeout=0, \ - wait_timeout=0, max_lifetime_session=0, session_callback=None, \ - max_sessions_per_shard=0, soda_metadata_cache=False, ping_interval=60, \ - ping_timeout=5000, user=None, proxy_user=None, password=None, \ - newpassword=None, wallet_password=None, access_token=None, host=None, \ - port=1521, protocol="tcp", https_proxy=None, https_proxy_port=0, \ - service_name=None, instance_name=None, sid=None, server_type=None, \ - cclass=None, purity=oracledb.PURITY_DEFAULT, expire_time=0, \ - retry_count=0, retry_delay=1, tcp_connect_timeout=20.0, \ - ssl_server_dn_match=True, ssl_server_cert_dn=None, \ - wallet_location=None, events=False, externalauth=False, \ - mode=oracledb.AUTH_MODE_DEFAULT, disable_oob=False, \ - stmtcachesize=oracledb.defaults.stmtcachesize, edition=None, \ - tag=None, matchanytag=False, config_dir=oracledb.defaults.config_dir, \ - appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, \ - connection_id_prefix=None, ssl_context=None, sdu=8192, \ - pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \ - program=oracledb.defaults.program, machine=oracledb.defaults.machine, \ - terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \ - driver_name=oracledb.defaults.driver_name, use_sni=False, \ - thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \ - extra_auth_params=None, handle=0) - - Creates a connection pool with the supplied parameters and returns the - :ref:`AsyncConnectionPool object ` for the pool. - ``create_pool_async()`` is a synchronous method. See - :ref:`Connection pooling ` for more information. - - This method can only be used in python-oracledb Thin mode. - - When connecting to Oracle Autonomous Database, use Python 3.11, or later. +.. autofunction:: create_pool_async - .. versionadded:: 2.0.0 + .. versionchanged:: 3.2.0 - Some values, such as the database host name, can be specified as - parameters, as part of the connect string, and in the params object. - The precedence is that values in the ``dsn`` parameter override values - passed as individual parameters, which themselves override values set in - the ``params`` parameter object. Similar precedence rules also apply to - other values. - - The ``user``, ``password``, and ``dsn`` parameters are the same as for - :meth:`oracledb.connect()`. - - The ``pool_class`` parameter is expected to be an - :ref:`AsyncConnectionPool Object ` or a subclass of - AsyncConnectionPool. - - The ``pool_alias`` parameter is expected to be a string representing the - name used to store and reference the pool in the python-oracledb connection - pool cache. If this parameter is not specified, then the pool will not be - added to the cache. The value of this parameter can be used with the - :meth:`oracledb.get_pool()` and :meth:`oracledb.connect_async()` methods to - access the pool. See :ref:`connpoolcache`. - - The ``params`` parameter is expected to be of type :ref:`PoolParams - ` and contains parameters that are used to create the pool. - If this parameter is not specified, the additional keyword parameters will - be used to create an instance of PoolParams. If both the params parameter - and additional keyword parameters are specified, the values in the keyword - parameters have precedence. Note that if a ``dsn`` is also supplied, then - the values of the parameters specified (if any) within the ``dsn`` will - override the values passed as additional keyword parameters, which - themselves override the values set in the ``params`` parameter object. - - The ``min``, ``max`` and ``increment`` parameters control pool growth - behavior. A fixed pool size where ``min`` equals ``max`` is - :ref:`recommended ` to help prevent connection storms and to - help overall system stability. The ``min`` parameter is the number of - connections opened when the pool is created. The default value of the - ``min`` parameter is *1*. The ``increment`` parameter is the number of - connections that are opened whenever a connection request exceeds the - number of currently open connections. The default value of the - ``increment`` parameter is *1*. The ``max`` parameter is the maximum number - of connections that can be open in the connection pool. The default value - of the ``max`` parameter is *2*. - - If the ``connectiontype`` parameter is specified, all calls to - :meth:`AsyncConnectionPool.acquire()` will create connection objects of - that type, rather than the base type defined at the module level. - - The ``getmode`` parameter determines the behavior of - :meth:`AsyncConnectionPool.acquire()`. One of the constants - :data:`oracledb.POOL_GETMODE_WAIT`, :data:`oracledb.POOL_GETMODE_NOWAIT`, - :data:`oracledb.POOL_GETMODE_FORCEGET`, or - :data:`oracledb.POOL_GETMODE_TIMEDWAIT`. The default value is - :data:`oracledb.POOL_GETMODE_WAIT`. - - The ``homogeneous`` parameter is a boolean that indicates whether the - connections are homogeneous (same user) or heterogeneous (multiple - users). The default value is *True*. - - The ``timeout`` parameter is the length of time (in seconds) that a - connection may remain idle in the pool before it is terminated. This - applies only when the pool has more than ``min`` connections open, allowing - it to shrink to the specified minimum size. The default value is *0* - seconds. A value of *0* means there is no limit. - - The ``wait_timeout`` parameter is the length of time (in milliseconds) that - a caller should wait when acquiring a connection from the pool with - ``getmode`` set to :data:`oracledb.POOL_GETMODE_TIMEDWAIT`. The default - value is *0* milliseconds. - - The ``max_lifetime_session`` parameter is the length of time (in seconds) - that a pooled connection may exist since first being created. The default - value is *0*. A value of *0* means that there is no limit. Connections - become candidates for termination when they are acquired or released back - to the pool and have existed for longer than ``max_lifetime_session`` - seconds. In python-oracledb Thick mode, Oracle Client libraries 12.1 or - later must be used and, prior to Oracle Client 21, cleanup only occurs when - the pool is accessed. - - The ``session_callback`` parameter is a callable that is invoked when a - connection is returned from the pool for the first time, or when the - connection tag differs from the one requested. - - The ``max_sessions_per_shard`` parameter is ignored in the python-oracledb - Thin mode. - - The ``soda_metadata_cache`` parameter is ignored in the python-oracledb - Thin mode. - - The ``ping_interval`` parameter is the length of time (in seconds) after - which an unused connection in the pool will be a candidate for pinging when - :meth:`AsyncConnectionPool.acquire()` is called. If the ping to the - database indicates the connection is not alive a replacement connection - will be returned by :meth:`~AsyncConnectionPool.acquire()`. If - ``ping_interval`` is a negative value, then the ping functionality will be - disabled. The default value is *60* seconds. - - The ``ping_timeout`` parameter is the maximum length of time (in - milliseconds) that :meth:`AsyncConnectionPool.acquire()` waits for a - connection to respond to any internal ping to the database. If the ping - does not respond within the specified time, then the connection is - destroyed and :meth:`~AsyncConnectionPool.acquire()` returns a different - connection. This value is used in both the python-oracledb Thin and Thick - modes. The default value is *5000* milliseconds. - - The ``proxy_user`` parameter is expected to be a string which indicates the - name of the proxy user to connect to. If this value is not specified, it - will be parsed out of user if user is in the form "user[proxy_user]". - - The ``newpassword`` parameter is expected to be a string which indicates - the new password for the user. The new password will take effect - immediately upon a successful connection to the database. - - The ``wallet_password`` parameter is expected to be a string which - indicates the password to use to decrypt the PEM-encoded wallet, if it is - encrypted. - - The ``access_token`` parameter is expected to be a string or a 2-tuple or - a callable. If it is a string, it specifies an Azure AD OAuth2 token used - for Open Authorization (OAuth 2.0) token based authentication. If it is a - 2-tuple, it specifies the token and private key strings used for Oracle - Cloud Infrastructure (OCI) Identity and Access Management (IAM) token based - authentication. If it is a callable, it returns either a string or a - 2-tuple used for OAuth 2.0 or OCI IAM token based authentication and is - useful when the pool needs to expand and create new connections but the - current authentication token has expired. - - The ``host`` parameter is expected to be a string which specifies the name - or IP address of the machine hosting the listener, which handles the - initial connection to the database. - - The ``port`` parameter is expected to be an integer which indicates the - port number on which the listener is listening. The default value is - *1521*. - - The ``protocol`` parameter is expected to be one of the strings *tcp* or - *tcps* which indicates whether to use unencrypted network traffic or - encrypted network traffic (TLS). The default value is *tcp*. - - The ``https_proxy`` parameter is expected to be a string which indicates - the name or IP address of a proxy host to use for tunneling secure - connections. - - The ``https_proxy_port`` parameter is expected to be an integer which - indicates the port that is to be used to communicate with the proxy host. - The default value is *0*. - - The ``service_name`` parameter is expected to be a string which indicates - the service name of the database. - - The ``instance_name`` parameter is expected to be a string which indicates - the instance name of the database. - - The ``sid`` parameter is expected to be a string which indicates the SID of - the database. It is recommended to use ``service_name`` instead. - - The ``server_type`` parameter is expected to be a string that indicates the - type of server connection that should be established. If specified, it - should be one of *dedicated*, *shared*, or *pooled*. - - The ``cclass`` parameter is expected to be a string that identifies the - connection class to use for :ref:`drcp`. - - The ``purity`` parameter is expected to be one of the - :ref:`oracledb.PURITY_* ` constants that identifies the - purity to use for DRCP. The purity will internally default to - :data:`~oracledb.PURITY_SELF` for pooled connections. - - The ``expire_time`` parameter is expected to be an integer which indicates - the number of minutes between the sending of keepalive probes. If this - parameter is set to a value greater than zero it enables keepalive. The - default value is *0* minutes. - - The ``retry_count`` parameter is expected to be an integer that identifies - the number of times that a connection attempt should be retried before the - attempt is terminated. The default value is *0*. - - The ``retry_delay`` parameter is expected to be an integer that identifies - the number of seconds to wait before making a new connection attempt. The - default value is *1* seconds. - - The ``tcp_connect_timeout`` parameter is expected to be a float that - indicates the maximum number of seconds to wait for establishing a - connection to the database host. The default value is *20.0* seconds. - - The ``ssl_server_dn_match`` parameter is expected to be a boolean that - indicates whether the server certificate distinguished name (DN) should be - matched in addition to the regular certificate verification that is - performed. Note that if the ``ssl_server_cert_dn`` parameter is not - provided, host name matching is performed instead. The default value is - *True*. - - The ``ssl_server_cert_dn`` parameter is expected to be a string that - indicates the distinguished name (DN) which should be matched with the - server. This value is ignored if the ``ssl_server_dn_match`` parameter is - not set to the value *True*. - - The ``wallet_location`` parameter is expected to be a string that - identifies the directory where the wallet can be found. In python-oracledb - Thin mode, this must be the directory of the PEM-encoded wallet file, - ewallet.pem. - - The ``events`` parameter is ignored in the python-oracledb Thin mode. - - The ``externalauth`` parameter is ignored in the python-oracledb Thin mode. - - If the ``mode`` parameter is specified, it must be one of the - :ref:`connection authorization modes ` - which are defined at the module level. The default value is - :data:`oracledb.AUTH_MODE_DEFAULT`. - - The ``disable_oob`` parameter is expected to be a boolean that indicates - whether out-of-band breaks should be disabled. This value has no effect - on Windows which does not support this functionality. The default value - is *False*. - - The ``stmtcachesize`` parameter is expected to be an integer which - specifies the initial size of the statement cache. The default is the - value of :attr:`defaults.stmtcachesize`. - - The ``tag`` parameter is ignored in the python-oracledb Thin mode. - - The ``matchanytag`` parameter is ignored in the python-oracledb Thin mode. - - The ``config_dir`` parameter is expected to be a string that indicates the - directory in which the :ref:`tnsnames.ora ` configuration file - is located. - - The ``appcontext`` parameter is expected to be a list of 3-tuples that - identifies the application context used by the connection. This parameter - should contain namespace, name, and value and each entry in the tuple - should be a string. - - The ``shardingkey`` parameter and ``supershardingkey`` parameters are - ignored in the python-oracledb Thin mode. - - The ``debug_jdwp`` parameter is expected to be a string with the format - `host=;port=` that specifies the host and port of the PL/SQL - debugger. This allows using the Java Debug Wire Protocol (JDWP) to debug - PL/SQL code invoked by python-oracledb. - - The ``connection_id_prefix`` parameter is expected to be a string and is - added to the beginning of the generated ``connection_id`` that is sent to - the database for `tracing `__. - - The ``ssl_context`` parameter is expected to be an SSLContext object used - for connecting to the database using TLS. This SSL context will be - modified to include the private key or any certificates found in a - separately supplied wallet. This parameter should only be specified if - the default SSLContext object cannot be used. - - The ``sdu`` parameter is expected to be an integer that returns the - requested size of the Session Data Unit (SDU), in bytes. The value tunes - internal buffers used for communication to the database. Bigger values can - increase throughput for large queries or bulk data loads, but at the cost - of higher memory use. The SDU size that will actually be used is - negotiated down to the lower of this value and the database network SDU - configuration value. See the `SQL*Net documentation `__ for more details. The default value is *8192* bytes. - - The ``pool_boundary`` parameter is expected to be one of the strings - *statement* or *transaction* which indicates when pooled :ref:`DRCP ` - or PRCP connections can be returned to the pool. If the value is - *statement*, then pooled DRCP or PRCP connections are implicitly released - back to the DRCP or PRCP pool when the connection is stateless (that is, - there are no active cursors, active transactions, temporary tables, or - temporary LOBs). If the value is *transaction*, then pooled DRCP or PRCP - connections are implicitly released back to the DRCP or PRCP pool when - either one of the methods :meth:`AsyncConnection.commit()` or - :meth:`AsyncConnection.rollback()` are called. This parameter requires the - use of DRCP or PRCP with Oracle Database 23ai (or later). See - :ref:`implicitconnpool` for more information. This value is used in both - the python-oracledb Thin and Thick modes. - - The ``use_tcp_fast_open`` parameter is expected to be a boolean which - indicates whether to use TCP Fast Open which is an `Oracle Autonomous - Database Serverless (ADB-S) `__ specific feature that can - reduce the latency in round-trips to the database after a connection has - been established. This feature is only available with certain versions of - ADB-S. This value is used in both python-oracledb Thin and Thick modes. - The default value is *False*. - - The ``ssl_version`` parameter is expected to be one of the constants - *ssl.TLSVersion.TLSv1_2* or *ssl.TLSVersion.TLSv1_3* which identifies the - TLS protocol version used. These constants are defined in the Python - `ssl `__ module. This - parameter can be specified when establishing connections with the protocol - *tcps*. This value is used in both python-oracledb Thin and Thick modes. - The value *ssl.TLSVersion.TLSv1_3* requires Oracle Database 23ai. If you - are using python-oracledb Thick mode, Oracle Client 23ai is additionally - required. - - The ``use_sni`` parameter is expected to be a boolean which indicates - whether to use the TLS Server Name Indication (SNI) extension to bypass the - second TLS negotiation that would otherwise be required. This parameter is - used in both python-oracledb Thin and Thick modes. This parameter requires - Oracle Database 23.7. The default value is *False*. See the `SQL*Net - documentation `__ for more details. - - The ``program`` parameter is expected to be a string which specifies the - name of the executable program or application connected to Oracle - Database. This value is only used in the python-oracledb Thin mode. The - default is the value of :attr:`defaults.program`. - - The ``machine`` parameter is expected to be a string which specifies the - machine name of the client connecting to Oracle Database. This value is - only used in the python-oracledb Thin mode. The default is the value of - :attr:`defaults.machine`. - - The ``terminal`` parameter is expected to be a string which specifies the - terminal identifier from which the connection originates. This value is - only used in the python-oracledb Thin mode. The default is the value of - :attr:`defaults.terminal`. - - The ``osuser`` parameter is expected to be a string which specifies the - operating system user that initiates the database connection. This value - is only used in the python-oracledb Thin mode. The default value is the - value of :attr:`defaults.osuser`. - - The ``driver_name`` parameter is expected to be a string which specifies - the driver used by the client to connect to Oracle Database. This value - is used in both the python-oracledb Thin and Thick modes. The default is - the value of :attr:`defaults.driver_name`. - - The ``extra_auth_params`` parameter is expected to be a dictionary - containing the configuration parameters necessary for Oracle Database - authentication using :ref:`OCI ` or :ref:`Azure - ` cloud native authentication plugins. This value is - used in both the python-oracledb Thin and Thick modes. See - :ref:`tokenauth`. - - The ``handle`` and ``thick_mode_dsn_passthrough`` parameters are ignored in - python-oracledb Thin mode. + The ``pool_name`` parameter was added. .. versionchanged:: 3.0.0 @@ -2083,154 +173,35 @@ Oracledb Methods The ``connection_id_prefix`` parameter was added. -.. function:: Cursor(connection) - - Constructor for creating a cursor. Returns a new - :ref:`cursor object ` using the connection. - - .. note:: - - This method is an extension to the DB API definition. - - -.. function:: Date(year, month, day) - - Constructs an object holding a date value. - - -.. function:: DateFromTicks(ticks) - - Constructs an object holding a date value from the given ticks value - (number of seconds since the epoch; see the documentation of the standard - Python time module for details). - +.. autofunction:: Date -.. function:: enable_thin_mode() +.. autofunction:: DateFromTicks - Makes python-oracledb be in Thin mode. After this method is called, Thick - mode cannot be enabled. If python-oracledb is already in Thick mode, then - calling ``enable_thin_mode()`` will fail. If Thin mode connections have - already been opened, or a connection pool created in Thin mode, then - calling ``enable_thin_mode()`` is a no-op. - - Since python-oracledb defaults to Thin mode, almost all applications do not - need to call this method. However, because it bypasses python-oracledb's - internal mode-determination heuristic, it may be useful for applications - with multiple threads that concurrently create :ref:`standalone connections - ` when the application starts. +.. autofunction:: enable_thin_mode See :ref:`enablingthin` for more information. .. versionadded:: 2.5.0 -.. function:: get_pool(pool_alias) +.. autofunction:: from_arrow - Returns a :ref:`ConnectionPool object ` from the python-oracledb - pool cache. The pool must have been previously created by passing the same - ``pool_alias`` value to :meth:`oracledb.create_pool()` or - :meth:`oracledb.create_pool_async()`. + .. versionadded:: 3.3.0 - If a pool with the given name does not exist, *None* is returned. +.. autofunction:: get_pool See :ref:`connpoolcache` for more information. .. versionadded:: 3.0.0 -.. function:: init_oracle_client(lib_dir=None, config_dir=None, \ - error_url=None, driver_name=None) - - Enables python-oracledb Thick mode by initializing the Oracle Client - library, see :ref:`enablingthick`. If a standalone connection or pool has - already been created in Thin mode, ``init_oracle_client()`` will raise an - exception and python-oracledb will remain in Thin mode. - - If a standalone connection or pool has *not* already been created in Thin - mode, but ``init_oracle_client()`` raises an exception, python-oracledb - will remain in Thin mode but further calls to ``init_oracle_client()`` can - be made, if desired. - - The ``init_oracle_client()`` method can be called multiple times in each - Python process as long as the arguments are the same each time. - - The ``lib_dir`` parameter is a string or a bytes object that specifies the - directory containing Oracle Client libraries. If the ``lib_dir`` parameter - is set, then the specified directory is the only one searched for the - Oracle Client libraries; otherwise, the operating system library search - path is used to locate the Oracle Client library. If you are using Python - 3.11 and later, then the value specified in this parameter is encoded - using `locale.getencoding() `__. For all other Python versions, the encoding - "utf-8" is used. If a bytes object is specified in this parameter, then - this value will be used as is without any encoding. - - The ``config_dir`` parameter is a string or a bytes object that specifies - the directory in which the - :ref:`Optional Oracle Net Configuration ` and - :ref:`Optional Oracle Client Configuration ` files reside. - If the ``config_dir`` parameter is set, then the specified directory is - used to find Oracle Client library configuration files. This is - equivalent to setting the environment variable ``TNS_ADMIN`` and overrides - any value already set in ``TNS_ADMIN``. If this parameter is not set, the - :ref:`Oracle standard ` way of locating Oracle Client - library configuration files is used. If you are using Python 3.11 and - later, then the value specified in this parameter is encoded using - `locale.getencoding() `__. For all other Python versions, the encoding - "utf-8" is used. If a bytes object is specified in this parameter, then - this value will be used as is without any encoding. - - The ``error_url`` parameter is a string that specifies the URL which is - included in the python-oracledb exception message if the Oracle Client - libraries cannot be loaded. If the ``error_url`` parameter is set, then - the specified value is included in the message of the exception raised - when the Oracle Client library cannot be loaded; otherwise, the - :ref:`installation` URL is included. This parameter lets your application - display custom installation instructions. - - The ``driver_name`` parameter is a string that specifies the driver name - value. If the ``driver_name`` parameter is set, then the specified value - can be found in database views that give information about connections. - For example, it is in the CLIENT_DRIVER column of the - V$SESSION_CONNECT_INFO view. From Oracle Database 12.2, the name displayed - can be 30 characters. The standard is to set this value to ``" : - version>"``, where is the name of the driver and is its - version. There should be a single space character before and after the - colon. If this parameter is not set, then the value specified in - :attr:`oracledb.defaults.driver_name ` is used. If - the value of this attribute is *None*, then the default value in - python-oracledb Thick mode is like "python-oracledb thk : ". See - :ref:`otherinit`. - - At successful completion of a call to ``oracledb.init_oracle_client()``, - the attribute :attr:`defaults.config_dir` will be set as determined below - (first one wins): - - - the value of the ``oracledb.init_oracle_client()`` parameter - ``config_dir``, if one was passed. - - - the value of :attr:`defaults.config_dir` if it has one. I.e. - :attr:`defaults.config_dir` remains unchanged after - ``oracledb.init_oracle_client()`` completes. - - - the value of the environment variable ``$TNS_ADMIN``, if it is set. - - - the value of ``$ORACLE_HOME/network/admin`` if the environment variable - ``$ORACLE_HOME`` is set. - - - the directory of the loaded Oracle Client library, appended with - ``network/admin``. Note this directory is not determinable on AIX. - - - otherwise the value *None* is used. (Leaving :attr:`defaults.config_dir` - unchanged). - - .. note:: +.. autofunction:: init_oracle_client - This method is an extension to the DB API definition. + .. dbapimethodextension:: .. versionchanged:: 3.0.0 - At completion of the method, the value of :attr:`defaults.config_dir` - may get changed by python-oracledb. + At completion of the method, the value of + :attr:`oracledb.defaults.config_dir ` may get + changed by python-oracledb. .. versionchanged:: 2.5.0 @@ -2241,1368 +212,392 @@ Oracledb Methods "utf-8" is used. These values may also be supplied as a ``bytes`` object, in which case they will be used as is. -.. function:: is_thin_mode() - - Returns a boolean indicating if Thin mode is in use. +.. autofunction:: is_thin_mode - Immediately after python-oracledb is imported, this function will return - *True* indicating that python-oracledb defaults to Thin mode. If - :func:`oracledb.init_oracle_client()` is called, then a subsequent call to - ``is_thin_mode()`` will return False indicating that Thick mode is - enabled. Once the first standalone connection or connection pool is - created, or a call to ``oracledb.init_oracle_client()`` is made, then - python-oracledb’s mode is fixed and the value returned by - ``is_thin_mode()`` will never change for the lifetime of the process. + See :ref:`vsessconinfo`. - The attribute :attr:`Connection.thin` can be used to check a connection's - mode. The attribute :attr:`ConnectionPool.thin` can be used to check a - pool's mode. - - .. note:: - - This method is an extension to the DB API definition. + .. dbapimethodextension:: .. versionadded:: 1.1.0 - -.. function:: makedsn(host, port, sid=None, service_name=None, region=None, \ - sharding_key=None, super_sharding_key=None) - - Returns a string suitable for use as the ``dsn`` parameter for - :meth:`~oracledb.connect()`. This string is identical to the strings that - are defined by the Oracle names server or defined in the ``tnsnames.ora`` - file. +.. autofunction:: makedsn .. deprecated:: python-oracledb 1.0 Use the :meth:`oracledb.ConnectParams()` method instead. - .. note:: - - This method is an extension to the DB API definition. - -.. function:: PoolParams(min=1, max=2, increment=1, connectiontype=None, \ - getmode=oracledb.POOL_GETMODE_WAIT, homogeneous=True, timeout=0, \ - wait_timeout=0, max_lifetime_session=0, session_callback=None, \ - max_sessions_per_shard=0, soda_metadata_cache=False, \ - ping_interval=60, ping_timeout=5000, user=None, proxy_user=Nonde, \ - password=None, newpassword=None, wallet_password=None, \ - access_token=None, host=None, port=1521, protocol="tcp", \ - https_proxy=None, https_proxy_port=0, service_name=None, \ - instance_name=None, sid=None, server_type=None, cclass=None, \ - purity=oracledb.PURITY_DEFAULT, expire_time=0, retry_count=0, \ - retry_delay=1, tcp_connect_timeout=20.0, ssl_server_dn_match=True, \ - ssl_server_cert_dn=None, wallet_location=None, events=False, \ - externalauth=False, mode=oracledb.AUTH_MODE_DEFAULT, \ - disable_oob=False, stmtcachesize=oracledb.defaults.stmtcachesize, \ - edition=None, tag=None, matchanytag=False, \ - config_dir=oracledb.defaults.config_dir, appcontext=[], \ - shardingkey=[], supershardingkey=[], debug_jdwp=None, \ - connection_id_prefix=None, ssl_context=None, sdu=8192, \ - pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \ - program=oracledb.defaults.program, machine=oracledb.defaults.machine, \ - terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \ - driver_name=oracledb.defaults.driver_name, use_sni=False, \ - thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \ - extra_auth_params=None, handle=0) - - Creates and returns a :ref:`PoolParams Object `. The object - can be passed to :meth:`oracledb.create_pool()`. - - All the parameters are optional. - - The ``min`` parameter is the minimum number of connections that the pool - should contain. The default value is *1*. - - The ``max`` parameter is the maximum number of connections that the pool - should contain. The default value is *2*. - - The ``increment`` parameter is the number of connections that should be - added to the pool whenever a new connection needs to be created. The - default value is *1*. - - The ``connectiontype`` parameter is the class of the connection that should - be returned during calls to :meth:`ConnectionPool.acquire()`. It must be a - Connection or a subclass of Connection. - - The ``getmode`` parameter determines the behavior of - :meth:`ConnectionPool.acquire()`. One of the constants - :data:`oracledb.POOL_GETMODE_WAIT`, :data:`oracledb.POOL_GETMODE_NOWAIT`, - :data:`oracledb.POOL_GETMODE_FORCEGET`, or - :data:`oracledb.POOL_GETMODE_TIMEDWAIT`. The default value is - :data:`oracledb.POOL_GETMODE_WAIT`. - - The ``homogeneous`` parameter is a boolean that indicates whether the - connections are homogeneous (same user) or heterogeneous (multiple users). - The default value is *True*. - - The ``timeout`` parameter is the length of time (in seconds) that a - connection may remain idle in the pool before it is terminated. This - applies only when the pool has more than ``min`` connections open, allowing - it to shrink to the specified minimum size. The default value is *0* - seconds. A value of *0* means there is no limit. - - The ``wait_timeout`` parameter is the length of time (in milliseconds) that - a caller should wait when acquiring a connection from the pool with - ``getmode`` set to :data:`oracledb.POOL_GETMODE_TIMEDWAIT`. The default - value is *0* milliseconds. - - The ``max_lifetime_session`` parameter is the length of time (in seconds) - that a pooled connection may exist since first being created. The default - value is *0*. A value of *0* means that there is no limit. Connections - become candidates for termination when they are acquired or released back - to the pool and have existed for longer than ``max_lifetime_session`` - seconds. In python-oracledb Thick mode, Oracle Client libraries 12.1 or - later must be used and, prior to Oracle Client 21, cleanup only occurs when - the pool is accessed. - - The ``session_callback`` parameter is a callable that is invoked when a - connection is returned from the pool for the first time, or when the - connection tag differs from the one requested. - - The ``max_sessions_per_shard`` parameter is the maximum number of - connections that may be associated with a particular shard. The default - value is *0*. - - The ``soda_metadata_cache`` parameter is a boolean that indicates whether - or not the SODA metadata cache should be enabled. The default value is - *False*. - - The ``ping_interval`` parameter is the length of time (in seconds) after - which an unused connection in the pool will be a candidate for pinging when - :meth:`ConnectionPool.acquire()` is called. If the ping to the database - indicates the connection is not alive a replacement connection will be - returned by :meth:`ConnectionPool.acquire()`. If ping_interval is a - negative value, then the ping functionality will be disabled. The default - value is *60* seconds. - - The ``ping_timeout`` parameter is the maximum length of time (in - milliseconds) that :meth:`ConnectionPool.acquire()` waits for a connection - to respond to any internal ping to the database. If the ping does not - respond within the specified time, then the connection is destroyed and - :meth:`~ConnectionPool.acquire()` returns a different connection. This - value is used in both the python-oracledb Thin and Thick modes. The default - value is *5000* milliseconds. - - The ``user`` parameter is expected to be a string which indicates the name - of the user to connect to. This value is used in both the python-oracledb - Thin and Thick modes. - - The ``proxy_user`` parameter is expected to be a string which indicates the - name of the proxy user to connect to. If this value is not specified, it - will be parsed out of user if user is in the form "user[proxy_user]". This - value is used in both the python-oracledb Thin and Thick modes. - - The ``password`` parameter expected to be a string which indicates the - password for the user. This value is used in both the python-oracledb Thin - and Thick modes. - - The ``newpassword`` parameter is expected to be a string which indicates - the new password for the user. The new password will take effect - immediately upon a successful connection to the database. This value is - used in both the python-oracledb Thin and Thick modes. - - The ``wallet_password`` parameter is expected to be a string which - indicates the password to use to decrypt the PEM-encoded wallet, if it is - encrypted. This value is only used in python-oracledb Thin mode. The - ``wallet_password`` parameter is not needed for cwallet.sso files that are - used in the python-oracledb Thick mode. - - The ``access_token`` parameter is expected to be a string or a 2-tuple or - a callable. If it is a string, it specifies an Azure AD OAuth2 token used - for Open Authorization (OAuth 2.0) token based authentication. If it is a - 2-tuple, it specifies the token and private key strings used for Oracle - Cloud Infrastructure (OCI) Identity and Access Management (IAM) token based - authentication. If it is a callable, it returns either a string or a - 2-tuple used for OAuth 2.0 or OCI IAM token based authentication and is - useful when the pool needs to expand and create new connections but the - current authentication token has expired. This value is used in both the - python-oracledb Thin and Thick modes. - - The ``host`` parameter is expected to be a string which specifies the name - or IP address of the machine hosting the listener, which handles the - initial connection to the database. This value is used in both the - python-oracledb Thin and Thick modes. - - The ``port`` parameter is expected to be an integer which indicates the - port number on which the listener is listening. The default value is - *1521*. This value is used in both the python-oracledb Thin and Thick - modes. - - The ``protocol`` parameter is expected to be one of the strings *tcp* or - *tcps* which indicates whether to use unencrypted network traffic or - encrypted network traffic (TLS). The default value is *tcp*. This value is - used in both the python-oracledb Thin and Thick modes. - - The ``https_proxy`` parameter is expected to be a string which indicates - the name or IP address of a proxy host to use for tunneling secure - connections. This value is used in both the python-oracledb Thin and Thick - modes. - - The ``https_proxy_port`` parameter is expected to be an integer which - indicates the port that is to be used to communicate with the proxy host. - The default value is *0*. This value is used in both the python-oracledb Thin - and Thick modes. - - The ``service_name`` parameter is expected to be a string which indicates - the service name of the database. This value is used in both the - python-oracledb Thin and Thick modes. - - The ``instance_name`` parameter is expected to be a string which indicates - the instance name of the database. This value is used in both the - python-oracledb Thin and Thick modes. - - The ``sid`` parameter is expected to be a string which indicates the SID of - the database. It is recommended to use ``service_name`` instead. This value - is used in both the python-oracledb Thin and Thick modes. - - The ``server_type`` parameter is expected to be a string that indicates the - type of server connection that should be established. If specified, it - should be one of *dedicated*, *shared*, or *pooled*. This value is used in - both the python-oracledb Thin and Thick modes. - - The ``cclass`` parameter is expected to be a string that identifies the - connection class to use for :ref:`drcp`. This value is used in both the - python-oracledb Thin and Thick modes. - - The ``purity`` parameter is expected to be one of the - :ref:`oracledb.PURITY_* ` constants that identifies the - purity to use for DRCP. This value is used in both the python-oracledb Thin - and Thick modes. Internally pooled connections will default to a purity of - :data:`~oracledb.PURITY_SELF`. - - The ``expire_time`` parameter is expected to be an integer which indicates - the number of minutes between the sending of keepalive probes. If this - parameter is set to a value greater than zero it enables keepalive. This - value is used in both the python-oracledb Thin and Thick modes. The default - value is *0* minutes. - - The ``retry_count`` parameter is expected to be an integer that identifies - the number of times that a connection attempt should be retried before the - attempt is terminated. This value is used in both the python-oracledb Thin - and Thick modes. The default value is *0*. - - The ``retry_delay`` parameter is expected to be an integer that identifies - the number of seconds to wait before making a new connection attempt. This - value is used in both the python-oracledb Thin and Thick modes. The default - value is *1* seconds. - - The ``tcp_connect_timeout`` parameter is expected to be a float that - indicates the maximum number of seconds to wait for establishing a - connection to the database host. This value is used in both the - python-oracledb Thin and Thick modes. The default value is *20.0* seconds. - - The ``ssl_server_dn_match`` parameter is expected to be a boolean that - indicates whether the server certificate distinguished name (DN) should be - matched in addition to the regular certificate verification that is - performed. Note that if the ssl_server_cert_dn parameter is not provided, - host name matching is performed instead. This value is used in both the - python-oracledb Thin and Thick modes. The default value is *True*. - - The ``ssl_server_cert_dn`` parameter is expected to be a string that - indicates the distinguished name (DN) which should be matched with the - server. This value is ignored if the ssl_server_dn_match parameter is not - set to the value *True*. This value is used in both the python-oracledb Thin - and Thick modes. - - The ``wallet_location`` parameter is expected to be a string that - identifies the directory where the wallet can be found. In python-oracledb - Thin mode, this must be the directory of the PEM-encoded wallet file, - ewallet.pem. In python-oracledb Thick mode, this must be the directory of - the file, cwallet.sso. This value is used in both the python-oracledb Thin - and Thick modes. - - The ``externalauth`` parameter is a boolean that determines whether to use - external authentication. This value is only used in the python-oracledb - Thick mode. The default value is *False*. - - The ``events`` parameter is expected to be a boolean that specifies whether - the events mode should be enabled. This value is only used in the - python-oracledb Thick mode. This parameter is needed for continuous - query notification and high availability event notifications. The default - value is *False*. - - The ``mode`` parameter is expected to be an integer that identifies the - authorization mode to use. This value is used in both the python-oracledb - Thin and Thick modes.The default value is - :data:`oracledb.AUTH_MODE_DEFAULT`. - - The ``disable_oob`` parameter is expected to be a boolean that indicates - whether out-of-band breaks should be disabled. This value is only used - in the python-oracledb Thin mode and has no effect on Windows which - does not support this functionality. The default value is *False*. - - The ``stmtcachesize`` parameter is expected to be an integer that - identifies the initial size of the statement cache. This value is used in - both the python-oracledb Thin and Thick modes. The default is the value of - :attr:`defaults.stmtcachesize`. - - The ``edition`` parameter is expected to be a string that indicates the - edition to use for the connection. It requires Oracle Database 11.2, or - later. This parameter cannot be used simultaneously with the ``cclass`` - parameter. - - The ``tag`` parameter is expected to be a string that identifies the type - of connection that should be returned from a pool. This value is only used - in the python-oracledb Thick mode. - - The ``matchanytag`` parameter is expected to be a boolean specifying - whether any tag can be used when acquiring a connection from the pool. This - value is only used in the python-oracledb Thick mode when acquiring a - connection from a pool. The default value is *False*. - - The ``config_dir`` parameter is expected to be a string that indicates the - directory in which the :ref:`tnsnames.ora ` configuration file - is located. - - The ``appcontext`` parameter is expected to be a list of 3-tuples that - identifies the application context used by the connection. This parameter - should contain namespace, name, and value and each entry in the tuple - should be a string. - - The ``shardingkey`` parameter and ``supershardingkey`` parameters, if - specified, are expected to be a sequence of values which identifies the - database shard to connect to. The key values can be a list of strings, - numbers, bytes, or dates. These values are only used in the - python-oracledb Thick mode and are ignored in the Thin mode. See - :ref:`connsharding`. - - The ``debug_jdwp`` parameter is expected to be a string with the format - `host=;port=` that specifies the host and port of the PL/SQL - debugger. This allows using the Java Debug Wire Protocol (JDWP) to debug - PL/SQL code invoked by python-oracledb. This value is only used in the - python-oracledb Thin mode. For python-oracledb Thick mode, set the - ``ORA_DEBUG_JDWP`` environment variable which has the same syntax. For more - information, see :ref:`jdwp`. - - The ``connection_id_prefix`` parameter is expected to be a string and is - added to the beginning of the generated ``connection_id`` that is sent to - the database for `tracing `__. This value - is only used in the python-oracledb Thin mode. - - The ``ssl_context`` parameter is expected to be an `SSLContext object - `__ which is used - for connecting to the database using TLS. This SSL context will be - modified to include the private key or any certificates found in a - separately supplied wallet. This parameter should only be specified if - the default SSLContext object cannot be used. This value is only used in - the python-oracledb Thin mode. - - The ``sdu`` parameter is expected to be an integer that returns the - requested size of the Session Data Unit (SDU), in bytes. The value tunes - internal buffers used for communication to the database. Bigger values can - increase throughput for large queries or bulk data loads, but at the cost - of higher memory use. The SDU size that will actually be used is - negotiated down to the lower of this value and the database network SDU - configuration value. See the `SQL*Net documentation `__ for more details. This value is used in both the - python-oracledb Thin and Thick modes. The default value is *8192* bytes. - - The ``pool_boundary`` parameter is expected to be one of the strings - *statement* or *transaction* which indicates when pooled :ref:`DRCP ` - or PRCP connections can be returned to the pool. If the value is - *statement*, then pooled DRCP or PRCP connections are implicitly released - back to the DRCP or PRCP pool when the connection is stateless (that is, - there are no active cursors, active transactions, temporary tables, or - temporary LOBs). If the value is *transaction*, then pooled DRCP or PRCP - connections are implicitly released back to the DRCP or PRCP pool when - either one of the methods :meth:`Connection.commit()` or - :meth:`Connection.rollback()` are called. This parameter requires the use - of DRCP or PRCP with Oracle Database 23ai (or later). See - :ref:`implicitconnpool` for more information. This value is used in both - the python-oracledb Thin and Thick modes. - - The ``use_tcp_fast_open`` parameter is expected to be a boolean which - indicates whether to use TCP Fast Open which is an `Oracle Autonomous - Database Serverless (ADB-S) `__ specific feature that can - reduce the latency in round-trips to the database after a connection has - been established. This feature is only available with certain versions of - ADB-S. This value is used in both python-oracledb Thin and Thick modes. - The default value is *False*. - - The ``ssl_version`` parameter is expected to be one of the constants - *ssl.TLSVersion.TLSv1_2* or *ssl.TLSVersion.TLSv1_3* which identifies the - TLS protocol version used. These constants are defined in the Python - `ssl `__ module. This - parameter can be specified when establishing connections with the protocol - "tcps". This value is used in both python-oracledb Thin and Thick modes. - The value *ssl.TLSVersion.TLSv1_3* requires Oracle Database 23ai. If you - are using python-oracledb Thick mode, Oracle Client 23ai is additionally - required. - - The ``use_sni`` parameter is expected to be a boolean which indicates - whether to use the TLS Server Name Indication (SNI) extension to bypass the - second TLS negotiation that would otherwise be required. This parameter is - used in both python-oracledb Thin and Thick modes. This parameter requires - Oracle Database 23.7. The default value is *False*. See the `SQL*Net - documentation `__ for more details. - - The ``program`` parameter is expected to be a string which specifies the - name of the executable program or application connected to Oracle - Database. This value is only used in the python-oracledb Thin mode. The - default is the value of :attr:`defaults.program`. - - The ``machine`` parameter is expected to be a string which specifies the - machine name of the client connecting to Oracle Database. This value is - only used in the python-oracledb Thin mode. The default is the value of - :attr:`defaults.machine`. - - The ``terminal`` parameter is expected to be a string which specifies the - terminal identifier from which the connection originates. This value is - only used in the python-oracledb Thin mode. The default is the value of - :attr:`defaults.terminal`. - - The ``osuser`` parameter is expected to be a string which specifies the - operating system user that initiates the database connection. This value - is only used in the python-oracledb Thin mode. The default value is the - value of :attr:`defaults.osuser`. - - The ``driver_name`` parameter is expected to be a string which specifies - the driver used by the client to connect to Oracle Database. This value - is used in both the python-oracledb Thin and Thick modes. The default is - the value of :attr:`defaults.driver_name`. - - The ``thick_mode_dsn_passthrough`` parameter is expected to be a boolean - which indicates whether the connect string should be passed unchanged to - the Oracle Client libraries for parsing when using python-oracledb Thick - mode. If this parameter is set to *False* in Thick mode, connect strings - are parsed by python-oracledb itself and a generated connect descriptor is - sent to the Oracle Client libraries. This value is only used in the - python-oracledb Thick mode. The default value is - :attr:`defualts.thick_mode_dsn_passthrough`. For more information, see - :ref:`usingconfigfiles`. - - The ``extra_auth_params`` parameter is expected to be a dictionary - containing the configuration parameters necessary for Oracle Database - authentication using :ref:`OCI ` or :ref:`Azure - ` cloud native authentication plugins. This value is - used in both the python-oracledb Thin and Thick modes. See - :ref:`tokenauth`. - - The ``handle`` parameter is expected to be an integer which represents a - pointer to a valid service context handle. This value is only used in the - python-oracledb Thick mode. It should be used with extreme caution. The - default value is *0*. + .. dbapimethodextension:: - .. versionchanged:: 3.0.0 - - The ``use_sni``, ``instance_name``, ``thick_mode_dsn_passthrough``, - ``extra_auth_params``, and ``instance_name`` parameters were added. - - .. versionchanged:: 2.5.0 - - The ``program``, ``machine``, ``terminal``, ``osuser``, and - ``driver_name`` parameters were added. Support for ``edition`` and - ``appcontext`` was added to python-oracledb Thin mode. - - .. versionchanged:: 2.3.0 - - The default value of the ``retry_delay`` parameter was changed from *0* - seconds to *1* second. The default value of the ``tcp_connect_timeout`` - parameter was changed from *60.0* seconds to *20.0* seconds. The - ``ping_timeout`` and ``ssl_version`` parameters were added. - - .. versionchanged:: 2.1.0 - - The ``pool_boundary`` and ``use_tcp_fast_open`` parameters were added. - - .. versionchanged:: 2.0.0 - - The ``ssl_context`` and ``sdu`` parameters were added. - - .. versionchanged:: 1.4.0 - - The ``connection_id_prefix`` parameter was added. - -.. function:: SparseVector(num_dimensions, indices, values) - - Creates and returns a :ref:`SparseVector object `. - - The ``num_dimensions`` parameter is the number of dimensions contained in - the vector. - - The ``indices`` parameter is the indices (zero-based) of non-zero values - in the vector. - - The ``values`` parameter is the non-zero values stored in the vector. - - .. versionadded:: 3.0.0 - -.. function:: register_params_hook(hook_function) - - Registers a user parameter hook function that will be called internally by - python-oracledb prior to connection or pool creation. The hook function - accepts a copy of the parameters that will be used to create the pool or - standalone connection and may modify them. For example, the cloud native - authentication plugins modify the "access_token" parameter with a function - that will acquire the token using information found in the - "extra_auth_parms" parameter. - - Multiple hooks may be registered. They will be invoked in order of - registration. +.. autofunction:: register_params_hook To unregister a user function, use :meth:`oracledb.unregister_params_hook`. See :ref:`registerparamshook`. - .. note:: - - This method is an extension to the DB API definition. + .. dbapimethodextension:: .. versionadded:: 3.0.0 -.. function:: register_password_type(password_type, hook_function) - - Registers a user password hook function that will be called internally by - python-oracledb when a password is supplied as a dictionary containing the - given ``password_type`` as the key "type". The hook function is called for - passwords specified as the ``password``, ``newpassword`` and - ``wallet_parameter`` parameters in calls to :meth:`oracledb.connect()`, - :meth:`oracledb.create_pool()`, :meth:`oracledb.connect_async()`, and - :meth:`oracledb.create_pool_async()`. - - Your hook function is expected to accept the dictionary supplied by the - application and return the valid password. - - Calling :meth:`~oracledb.register_password_type()` with the - ``hook_function`` parameter set to *None* will result in a previously - registered user function being removed and the default behavior restored. +.. autofunction:: register_password_type See :ref:`registerpasswordtype`. - .. note:: - - This method is an extension to the DB API definition. + .. dbapimethodextension:: .. versionadded:: 3.0.0 -.. function:: register_protocol(protocol, hook_function) - - Registers a user protocol hook function that will be called internally by - python-oracledb Thin mode prior to connection or pool creation. The hook - function will be invoked when :func:`oracledb.connect`, - :func:`oracledb.create_pool`, :meth:`oracledb.connect_async()`, or - :meth:`oracledb.create_pool_async()` are called with a ``dsn`` parameter - value prefixed with the specified protocol. The user function will also be - invoked when :meth:`ConnectParams.parse_connect_string()` is called in Thin - or Thick modes with a similar ``connect_string`` parameter value. - - Your hook function is expected to construct valid connection details. For - example, if a hook function is registered for the "ldaps" protocol, then - calling :func:`oracledb.connect` with a connection string prefixed with - "ldaps://" will invoke the function. The function can then perform LDAP - lookup to retrieve and set the actual database information that will be - used internally by python-oracledb to complete the connection creation. - - The ``protocol`` parameter is a string that will be matched against the - prefix appearing before "://" in connection strings. - - The ``hook_function`` parameter should be a function with the signature:: - - hook_function(protocol, protocol_arg, params) - - The hook function will be called with the following arguments: - - - The ``protocol`` parameter is the value that was registered. - - - The ``protocol_arg`` parameter is the section after "://" in the - connection string used in the connection or pool creation call, or passed - to :meth:`~ConnectParams.parse_connect_string()`. - - - The ``params`` parameter is an instance of :ref:`ConnectParams - `. - - When your hook function is invoked internally prior to connection or pool - creation, ``params`` will be the ConnectParams instance originally passed - to the :func:`oracledb.connect`, :func:`oracledb.create_pool`, - :meth:`oracledb.connect_async()`, or :meth:`oracledb.create_pool_async()` - call, if such an instance was passed. Otherwise it will be a new - ConnectParams instance. The hook function should parse ``protocol`` and - ``protocol_arg`` and take any desired action to update ``params`` - :ref:`attributes ` with appropriate connection - parameters. Attributes can be set using :meth:`ConnectParams.set()` or - :meth:`ConnectParams.parse_connect_string()`. The ConnectParams instance - will then be used to complete the connection or pool creation. - - When your hook function is invoked by - :meth:`ConnectParams.parse_connect_string()`, then ``params`` will be the - invoking ConnectParams instance that you can update using - :meth:`ConnectParams.set()` or - :meth:`ConnectParams.parse_connect_string()`. - - Internal hook functions for the "tcp" and "tcps" protocols are - pre-registered but can be overridden if needed. If any other protocol has - not been registered, then connecting will result in the error ``DPY-4021: - invalid protocol``. - - Calling :meth:`~oracledb.register_protocol()` with the ``hook_function`` - parameter set to *None* will result in a previously registered user function - being removed and the default behavior restored. +.. autofunction:: register_protocol See :ref:`registerprotocolhook` for more information. - .. note:: - - This method is an extension to the DB API definition. + .. dbapimethodextension:: .. versionadded:: 2.5.0 -.. function:: Time(hour, minute, second) - - Constructs an object holding a time value. +.. autofunction:: Time - .. note:: - - The time only data type is not supported by Oracle. Calling this - function will raise a NotSupportedError exception. +.. autofunction:: TimeFromTicks +.. autofunction:: Timestamp -.. function:: TimeFromTicks(ticks) +.. autofunction:: TimestampFromTicks - Constructs an object holding a time value from the given ticks value - (number of seconds since the epoch; see the documentation of the standard - Python time module for details). - - .. note:: +.. autofunction:: unregister_params_hook - The time only data type is not supported by Oracle. Calling this - function will raise a NotSupportedError exception. - -.. function:: Timestamp(year, month, day, hour, minute, second) - - Constructs an object holding a time stamp value. - -.. function:: TimestampFromTicks(ticks) - - Constructs an object holding a time stamp value from the given ticks value - (number of seconds since the epoch; see the documentation of the standard - Python time module for details). - -.. function:: unregister_params_hook(hook_function) - - Unregisters a user parameter function that was earlier registered with a - call to :meth:`oracledb.register_params_hook()`. - - .. note:: - - This method is an extension to the DB API definition. + .. dbapimethodextension:: .. versionadded:: 3.0.0 -.. _interval_ym: - -Oracledb IntervalYM Class -========================= - -Objects of this class are returned for columns of type INTERVAL YEAR TO MONTH -and can be passed to variables of type :data:`oracledb.DB_TYPE_INTERVAL_YM` -The class is a `collections.namedtuple() -`__ -class with two integer attributes, ``years`` and ``months``. - -.. versionadded:: 2.2.0 - - -.. _jsonid: +.. _moduleattributes: -Oracledb JsonId Class -===================== +Oracledb Attributes +=================== -Objects of this class are returned by :ref:`SODA ` in the ``_id`` -attribute of documents stored in native collections when using Oracle Database -23.4 (and later). It is a subclass of the `bytes `__ class. +.. autodata:: apilevel -.. versionadded:: 2.1.0 +.. autodata:: defaults + :no-value: + See :ref:`settingdefaults`. -.. _futureobj: + .. dbapiattributeextension:: -Oracledb __future__ Object -========================== +.. autodata:: paramstyle -Special object that contains attributes which control the behavior of -python-oracledb, allowing for opting in for new features. +.. autodata:: threadsafety -.. note:: +.. autodata:: __version__ - This method is an extension to the DB API definition. + .. dbapiattributeextension:: .. _constants: Oracledb Constants ================== -General -------- - -.. data:: apilevel - - String constant stating the supported DB API level. Currently '2.0'. - - -.. data:: paramstyle - - String constant stating the type of parameter marker formatting expected by - the interface. Currently 'named' as in 'where name = :name'. - - -.. data:: threadsafety - - Integer constant stating the level of thread safety that the interface - supports. Currently 2, which means that threads may share the module and - connections, but not cursors. Sharing means that a thread may use a - resource without wrapping it using a mutex semaphore to implement resource - locking. - -.. data:: version -.. data:: __version__ - - String constant stating the version of the module. Currently '|release|'. - - .. note:: - - This attribute is an extension to the DB API definition. - - Advanced Queuing: Delivery Modes -------------------------------- -These constants are extensions to the DB API definition. They are possible -values for the :attr:`~DeqOptions.deliverymode` attribute of the +The AQ Delivery mode constants are possible values for the +:attr:`~DeqOptions.deliverymode` attribute of the :ref:`dequeue options object ` passed as the ``options`` parameter -to the :meth:`Queue.deqone()` or :meth:`Queue.deqmany()` methods as well as the -:attr:`~EnqOptions.deliverymode` attribute of the +to the :meth:`Queue.deqone()`, :meth:`Queue.deqmany()`, +:meth:`AsyncQueue.deqone()`, and :meth:`AsyncQueue.deqmany()` methods as well +as the :attr:`~EnqOptions.deliverymode` attribute of the :ref:`enqueue options object ` passed as the ``options`` parameter -to the :meth:`Queue.enqone()` or :meth:`Queue.enqmany()` methods. They are also -possible values for the :attr:`~MessageProperties.deliverymode` attribute of -the :ref:`message properties object ` passed as the -``msgproperties`` parameter to the :meth:`Queue.deqone()` or -:meth:`Queue.deqmany()` and :meth:`Queue.enqone()` or :meth:`Queue.enqmany()` -methods. - - -.. data:: MSG_BUFFERED - - This constant is used to specify that enqueue/dequeue operations should - enqueue or dequeue buffered messages. +to the :meth:`Queue.enqone()`, :meth:`Queue.enqmany()`, +:meth:`AsyncQueue.enqone()`, and :meth:`AsyncQueue.enqmany()` methods. They are +also possible values for the :attr:`~MessageProperties.deliverymode` attribute +of the :ref:`message properties object ` passed as the +``msgproperties`` parameter to the :meth:`Queue.deqone()`, +:meth:`Queue.deqmany()`, :meth:`AsyncQueue.deqone()`, or +:meth:`AsyncQueue.deqmany()`, and :meth:`Queue.enqone()`, +:meth:`Queue.enqmany()`, :meth:`AsyncQueue.enqone()`, or +:meth:`AsyncQueue.enqmany()` methods. +.. dbapiconstantextension:: -.. data:: MSG_PERSISTENT +.. autodata:: MSG_BUFFERED - This constant is used to specify that enqueue/dequeue operations should - enqueue or dequeue persistent messages. This is the default value. +.. autodata:: MSG_PERSISTENT - -.. data:: MSG_PERSISTENT_OR_BUFFERED - - This constant is used to specify that dequeue operations should dequeue - either persistent or buffered messages. +.. autodata:: MSG_PERSISTENT_OR_BUFFERED Advanced Queuing: Dequeue Modes ------------------------------- -These constants are extensions to the DB API definition. They are possible -values for the :attr:`~DeqOptions.mode` attribute of the +The AQ Dequeue mode constants are possible values for the +:attr:`~DeqOptions.mode` attribute of the :ref:`dequeue options object `. This object is the ``options`` -parameter for the :meth:`Queue.deqone()` or :meth:`Queue.deqmany()` methods. - - -.. data:: DEQ_BROWSE - - This constant is used to specify that dequeue should read the message - without acquiring any lock on the message (equivalent to a select - statement). - - -.. data:: DEQ_LOCKED - - This constant is used to specify that dequeue should read and obtain a - write lock on the message for the duration of the transaction (equivalent - to a select for update statement). +parameter for the :meth:`Queue.deqone()`, :meth:`Queue.deqmany()`, +:meth:`AsyncQueue.deqone()`, or :meth:`AsyncQueue.deqmany()` methods. +.. dbapiconstantextension:: -.. data:: DEQ_REMOVE +.. autodata:: DEQ_BROWSE - This constant is used to specify that dequeue should read the message and - update or delete it. This is the default value. +.. autodata:: DEQ_LOCKED +.. autodata:: DEQ_REMOVE -.. data:: DEQ_REMOVE_NODATA - - This constant is used to specify that dequeue should confirm receipt of the - message but not deliver the actual message content. +.. autodata:: DEQ_REMOVE_NODATA Advanced Queuing: Dequeue Navigation Modes ------------------------------------------ -These constants are extensions to the DB API definition. They are possible -values for the :attr:`~DeqOptions.navigation` attribute of the +The AQ Dequeue Navigation mode constants are possible values for the +:attr:`~DeqOptions.navigation` attribute of the :ref:`dequeue options object `. This object is the ``options`` -parameter for the :meth:`Queue.deqone()` or :meth:`Queue.deqmany()` methods. - - -.. data:: DEQ_FIRST_MSG - - This constant is used to specify that dequeue should retrieve the first - available message that matches the search criteria. This resets the - position to the beginning of the queue. +parameter for the :meth:`Queue.deqone()`, :meth:`Queue.deqmany()`, +:meth:`AsyncQueue.deqone()`, or :meth:`AsyncQueue.deqmany()` methods. +.. dbapiconstantextension:: -.. data:: DEQ_NEXT_MSG +.. autodata:: DEQ_FIRST_MSG - This constant is used to specify that dequeue should retrieve the next - available message that matches the search criteria. If the previous message - belongs to a message group, AQ retrieves the next available message that - matches the search criteria and belongs to the message group. This is the - default. +.. autodata:: DEQ_NEXT_MSG - -.. data:: DEQ_NEXT_TRANSACTION - - This constant is used to specify that dequeue should skip the remainder of - the transaction group and retrieve the first message of the next - transaction group. This option can only be used if message grouping is - enabled for the current queue. +.. autodata:: DEQ_NEXT_TRANSACTION Advanced Queuing: Dequeue Visibility Modes ------------------------------------------ -These constants are extensions to the DB API definition. They are possible -values for the :attr:`~DeqOptions.visibility` attribute of the +The AQ Dequeue Visibility mode constants are possible values for the +:attr:`~DeqOptions.visibility` attribute of the :ref:`dequeue options object `. This object is the ``options`` -parameter for the :meth:`Queue.deqone()` or :meth:`Queue.deqmany()` methods. - - -.. data:: DEQ_IMMEDIATE +parameter for the :meth:`Queue.deqone()`, :meth:`Queue.deqmany()`, +:meth:`AsyncQueue.deqone()`, or :meth:`AsyncQueue.deqmany()` methods. - This constant is used to specify that dequeue should perform its work as - part of an independent transaction. +.. dbapiconstantextension:: +.. autodata:: DEQ_IMMEDIATE -.. data:: DEQ_ON_COMMIT - - This constant is used to specify that dequeue should be part of the current - transaction. This is the default value. +.. autodata:: DEQ_ON_COMMIT Advanced Queuing: Dequeue Wait Modes ------------------------------------ -These constants are extensions to the DB API definition. They are possible -values for the :attr:`~DeqOptions.wait` attribute of the +The AQ Dequeue Wait mode constants are possible values for the +:attr:`~DeqOptions.wait` attribute of the :ref:`dequeue options object `. This object is the ``options`` -parameter for the :meth:`Queue.deqone()` or :meth:`Queue.deqmany()` methods. - - -.. data:: DEQ_NO_WAIT - - This constant is used to specify that dequeue not wait for messages to be - available for dequeuing. +parameter for the :meth:`Queue.deqone()`, :meth:`Queue.deqmany()`, +:meth:`AsyncQueue.deqone()`, or :meth:`AsyncQueue.deqmany()` methods. +.. dbapiconstantextension:: -.. data:: DEQ_WAIT_FOREVER - - This constant is used to specify that dequeue should wait forever for - messages to be available for dequeuing. This is the default value. +.. autodata:: DEQ_NO_WAIT +.. autodata:: DEQ_WAIT_FOREVER Advanced Queuing: Enqueue Visibility Modes ------------------------------------------ -These constants are extensions to the DB API definition. They are possible -values for the :attr:`~EnqOptions.visibility` attribute of the +The AQ Enqueue Visibility mode constants are possible values for the +:attr:`~EnqOptions.visibility` attribute of the :ref:`enqueue options object `. This object is the ``options`` -parameter for the :meth:`Queue.enqone()` or :meth:`Queue.enqmany()` methods. - - -.. data:: ENQ_IMMEDIATE +parameter for the :meth:`Queue.enqone()`, :meth:`Queue.enqmany()`, +:meth:`AsyncQueue.enqone()`, or :meth:`AsyncQueue.enqmany()` methods. - This constant is used to specify that enqueue should perform its work as - part of an independent transaction. +.. dbapiconstantextension:: +.. autodata:: ENQ_IMMEDIATE -.. data:: ENQ_ON_COMMIT + .. seealso:: - This constant is used to specify that enqueue should be part of the current - transaction. This is the default value. + :ref:`Bulk Enqueuing `. +.. autodata:: ENQ_ON_COMMIT Advanced Queuing: Message States -------------------------------- -These constants are extensions to the DB API definition. They are possible -values for the :attr:`~MessageProperties.state` attribute of the +The AQ Message state constants are possible values for the +:attr:`~MessageProperties.state` attribute of the :ref:`message properties object `. This object is the -``msgproperties`` parameter for the :meth:`Queue.deqone()` or -:meth:`Queue.deqmany()`, and :meth:`Queue.enqone()` or :meth:`Queue.enqmany()` -methods. +``msgproperties`` parameter for the :meth:`Queue.deqone()`, +:meth:`Queue.deqmany()`, :meth:`AsyncQueue.deqone()` or +:meth:`AsyncQueue.deqmany()` and :meth:`Queue.enqone()`, +:meth:`Queue.enqmany()`, :meth:`AsyncQueue.enqone()`, or +:meth:`AsyncQueue.enqmany()` methods. +.. dbapiconstantextension:: -.. data:: MSG_EXPIRED +.. autodata:: MSG_EXPIRED - This constant is used to specify that the message has been moved to the - exception queue. +.. autodata:: MSG_PROCESSED +.. autodata:: MSG_READY -.. data:: MSG_PROCESSED +.. autodata:: MSG_WAITING - This constant is used to specify that the message has been processed and - has been retained. - - -.. data:: MSG_READY - - This constant is used to specify that the message is ready to be processed. - - -.. data:: MSG_WAITING - - This constant is used to specify that the message delay has not yet been - reached. - - -Advanced Queuing: Other ------------------------ - -These constants are extensions to the DB API definition. They are special -constants used in advanced queuing. - - -.. data:: MSG_NO_DELAY - - This constant is a possible value for the :attr:`~MessageProperties.delay` - attribute of the :ref:`message properties object ` passed - as the ``msgproperties`` parameter to the :meth:`Queue.deqone()` or - :meth:`Queue.deqmany()` and :meth:`Queue.enqone()` or - :meth:`Queue.enqmany()` methods. It specifies that no delay should be - imposed and the message should be immediately available for dequeuing. This - is also the default value. +Advanced Queuing: Other Constants +--------------------------------- +This section contains other constants that are used for Advanced Queueing. -.. data:: MSG_NO_EXPIRATION +.. dbapiconstantextension:: - This constant is a possible value for the - :attr:`~MessageProperties.expiration` attribute of the - :ref:`message properties object ` passed as the - ``msgproperties`` parameter to the :meth:`Queue.deqone()` or - :meth:`Queue.deqmany()` and :meth:`Queue.enqone()` or - :meth:`Queue.enqmany()` methods. It specifies that the message never - expires. This is also the default value. +.. autodata:: MSG_NO_DELAY +.. autodata:: MSG_NO_EXPIRATION .. _connection-authorization-modes: Connection Authorization Modes ------------------------------ -These constants belong to the enumeration called ``AuthMode``. They are -possible values for the ``mode`` parameters of :meth:`oracledb.connect()`, -:meth:`oracledb.create_pool()`, :meth:`oracledb.connect_async()`, and -:meth:`oracledb.create_pool_async()`. They have deprecated the authorization -modes used in cx_Oracle 8.3. The constants are extensions to the DB API -definition. +The Connection Authorization mode constants belong to the enumeration called +``AuthMode``. They are possible values for the ``mode`` parameters of +:meth:`oracledb.connect()`, :meth:`oracledb.create_pool()`, +:meth:`oracledb.connect_async()`, and :meth:`oracledb.create_pool_async()`. +These constants have deprecated the authorization modes used in the obsolete +cx_Oracle driver. + +.. dbapiconstantextension:: .. versionchanged:: 2.3.0 The integer constants for the connection authorization modes were replaced with the enumeration ``AuthMode``. -.. data:: AUTH_MODE_DEFAULT - - This constant is used to specify that default authentication is to take - place. This is the default value if no mode is passed at all. - - This enumerated value can also be identified by - ``oracledb.AuthMode.DEFAULT``. - - .. note:: - - This constant can be used for standalone and pooled connections in the - python-oracledb Thin mode, and for standalone connections in the Thick - mode. - - This constant deprecates the ``DEFAULT_AUTH`` constant that was used in - cx_Oracle 8.3, and was the default ``mode`` value. - -.. data:: AUTH_MODE_PRELIM - - This constant is used to specify that preliminary authentication is to be - used. This is needed for performing database startup and shutdown. - - This enumerated value can also be identified by - ``oracledb.AuthMode.PRELIM``. - - .. note:: - - This constant can only be used in the python-oracledb Thick mode for - standalone connections. - - This constant deprecates the ``PRELIM_AUTH`` constant that was used in - cx_Oracle 8.3. - -.. data:: AUTH_MODE_SYSASM - - This constant is used to specify that SYSASM access is to be acquired. - - This enumerated value can also be identified by - ``oracledb.AuthMode.SYSASM``. +.. autodata:: AUTH_MODE_DEFAULT - .. note:: - - This constant can be used for standalone and pooled connections in the - python-oracledb Thin mode, and for standalone connections in the Thick - mode. - - This constant deprecates the ``SYSASM`` constant that was used in - cx_Oracle 8.3. - -.. data:: AUTH_MODE_SYSBKP - - This constant is used to specify that SYSBACKUP access is to be acquired. - - This enumerated value can also be identified by - ``oracledb.AuthMode.SYSBKP``. - - .. note:: - - This constant can be used for standalone and pooled connections in the - python-oracledb Thin mode, and for standalone connections in the Thick - mode. - - This constant deprecates the ``SYSBKP`` constant that was used in - cx_Oracle 8.3. - -.. data:: AUTH_MODE_SYSDBA - - This constant is used to specify that SYSDBA access is to be acquired. - - This enumerated value can also be identified by - ``oracledb.AuthMode.SYSDBA``. - - .. note:: - - This constant can be used for standalone and pooled connections in the - python-oracledb Thin mode, and for standalone connections in the Thick - mode. +.. autodata:: AUTH_MODE_PRELIM - This constant deprecates the ``SYSDBA`` constant that was used in - cx_Oracle 8.3. +.. autodata:: AUTH_MODE_SYSASM -.. data:: AUTH_MODE_SYSDGD +.. autodata:: AUTH_MODE_SYSBKP - This constant is used to specify that SYSDG access is to be acquired. +.. autodata:: AUTH_MODE_SYSDBA - This enumerated value can also be identified by - ``oracledb.AuthMode.SYSDGD``. +.. autodata:: AUTH_MODE_SYSDGD - .. note:: - - This constant can be used for standalone and pooled connections in the - python-oracledb Thin mode, and for standalone connections in the Thick - mode. - - This constant deprecates the ``SYSDGD`` constant that was used in - cx_Oracle 8.3. - -.. data:: AUTH_MODE_SYSKMT - - This constant is used to specify that SYSKM access is to be acquired. - - This enumerated value can also be identified by - ``oracledb.AuthMode.SYSKMT``. - - .. note:: - - This constant can be used for standalone and pooled connections in the - python-oracledb Thin mode, and for standalone connections in the Thick - mode. - - This constant deprecates the ``SYSKMT`` constant that was used in - cx_Oracle 8.3. - -.. data:: AUTH_MODE_SYSOPER - - This constant is used to specify that SYSOPER access is to be acquired. - - This enumerated value can also be identified by - ``oracledb.AuthMode.SYSOPER``. - - .. note:: +.. autodata:: AUTH_MODE_SYSKMT - This constant can be used for standalone and pooled connections in the - python-oracledb Thin mode, and for standalone connections in the Thick - mode. +.. autodata:: AUTH_MODE_SYSOPER - This constant deprecates the ``SYSOPER`` constant that was used in - cx_Oracle 8.3. +.. autodata:: AUTH_MODE_SYSRAC -.. data:: AUTH_MODE_SYSRAC - - This constant is used to specify that SYSRAC access is to be acquired. - - This enumerated value can also be identified by - ``oracledb.AuthMode.SYSRAC``. - - .. note:: - - This constant can be used for standalone and pooled connections in the - python-oracledb Thin mode, and for standalone connections in the Thick - mode. - - This constant deprecates the ``SYSRAC`` constant that was used in - cx_Oracle 8.3. .. _pipeline-operation-types: Pipeline Operation Types ------------------------ -These constants belong to the enumeration called ``PipelineOpType``. The -pipelining constants listed below are used to identify the type of operation -added. They are possible values for the :attr:`PipelineOp.op_type` attribute. +The Pipeline Operation type constants belong to the enumeration called +``PipelineOpType``. The pipelining constants listed below are used to identify +the type of operation added. They are possible values for the +:attr:`PipelineOp.op_type` attribute. .. versionadded:: 2.4.0 -.. data:: oracledb.PIPELINE_OP_TYPE_CALL_FUNC - - This constant identifies the type of operation as the calling of a stored - function. - - This enumerated value can also be identified by - ``oracledb.PipelineOpType.CALL_FUNC``. - -.. data:: oracledb.PIPELINE_OP_TYPE_CALL_PROC - - This constant identifies the type of operation as the calling of a stored - procedure. - - This enumerated value can also be identified by - ``oracledb.PipelineOpType.CALL_PROC``. - -.. data:: oracledb.PIPELINE_OP_TYPE_COMMIT - - This constant identifies the type of operation as the performing of a - commit. - - This enumerated value can also be identified by - ``oracledb.PipelineOpType.COMMIT``. - -.. data:: oracledb.PIPELINE_OP_TYPE_EXECUTE - - This constant identifies the type of operation as the executing of a - statement. +.. autodata:: oracledb.PIPELINE_OP_TYPE_CALL_FUNC - This enumerated value can also be identified by - ``oracledb.PipelineOpType.EXECUTE``. +.. autodata:: oracledb.PIPELINE_OP_TYPE_CALL_PROC -.. data:: oracledb.PIPELINE_OP_TYPE_EXECUTE_MANY +.. autodata:: oracledb.PIPELINE_OP_TYPE_COMMIT - This constant identifies the type of operations as the executing of a - statement multiple times. +.. autodata:: oracledb.PIPELINE_OP_TYPE_EXECUTE - This enumerated value can also be identified by - ``oracledb.PipelineOpType.EXECUTE_MANY``. +.. autodata:: oracledb.PIPELINE_OP_TYPE_EXECUTE_MANY -.. data:: oracledb.PIPELINE_OP_TYPE_FETCH_ALL +.. autodata:: oracledb.PIPELINE_OP_TYPE_FETCH_ALL - This constant identifies the type of operation as the executing of a - query and returning all of the rows from the result set. +.. autodata:: oracledb.PIPELINE_OP_TYPE_FETCH_MANY - This enumerated value can also be identified by - ``oracledb.PipelineOpType.FETCH_ALL``. +.. autodata:: oracledb.PIPELINE_OP_TYPE_FETCH_ONE -.. data:: oracledb.PIPELINE_OP_TYPE_FETCH_MANY - - This constant identifies the type of operation as the executing of a - query and returning up to the specified number of rows from the result - set. - - This enumerated value can also be identified by - ``oracledb.PipelineOpType.FETCH_MANY``. - -.. data:: oracledb.PIPELINE_OP_TYPE_FETCH_ONE - - This constant identifies the type of operation as the executing of a query - and returning the first row of the result set. - - This enumerated value can also be identified by - ``oracledb.PipelineOpType.FETCH_ONE``. Database Shutdown Modes ----------------------- -These constants are extensions to the DB API definition. They are possible -values for the ``mode`` parameter of the :meth:`Connection.shutdown()` method. - - -.. data:: DBSHUTDOWN_ABORT - - This constant is used to specify that the caller should not wait for - current processing to complete or for users to disconnect from the - database. This should only be used in unusual circumstances since database - recovery may be necessary upon next startup. +The Database Shutdown mode constants are possible values for the ``mode`` +parameter of the :meth:`Connection.shutdown()` method. +.. dbapiconstantextension:: -.. data:: DBSHUTDOWN_FINAL +.. autodata:: DBSHUTDOWN_ABORT - This constant is used to specify that the instance can be truly halted. - This should only be done after the database has been shutdown with one of - the other modes (except abort) and the database has been closed and - dismounted using the appropriate SQL commands. +.. autodata:: DBSHUTDOWN_FINAL +.. autodata:: DBSHUTDOWN_IMMEDIATE -.. data:: DBSHUTDOWN_IMMEDIATE +.. autodata:: DBSHUTDOWN_TRANSACTIONAL - This constant is used to specify that all uncommitted transactions should - be rolled back and any connected users should be disconnected. - - -.. data:: DBSHUTDOWN_TRANSACTIONAL - - This constant is used to specify that further connections to the database - should be prohibited and no new transactions should be allowed. It then - waits for all active transactions to complete. - - -.. data:: DBSHUTDOWN_TRANSACTIONAL_LOCAL - - This constant is used to specify that further connections to the database - should be prohibited and no new transactions should be allowed. It then - waits for only local active transactions to complete. +.. autodata:: DBSHUTDOWN_TRANSACTIONAL_LOCAL +.. _eventtypes: Event Types ----------- -These constants are extensions to the DB API definition. They are possible -values for the :attr:`Message.type` attribute of the messages that are sent -for subscriptions created by the :meth:`Connection.subscribe()` method. - - -.. data:: EVENT_AQ +The Event type constants are possible values for the :attr:`Message.type` +attribute of the messages that are sent for subscriptions created by the +:meth:`Connection.subscribe()` method. - This constant is used to specify that one or more messages are available - for dequeuing on the queue specified when the subscription was created. +.. dbapiconstantextension:: +.. autodata:: EVENT_AQ -.. data:: EVENT_DEREG +.. autodata:: EVENT_DEREG - This constant is used to specify that the subscription has been - deregistered and no further notifications will be sent. +.. autodata:: EVENT_NONE +.. autodata:: EVENT_OBJCHANGE -.. data:: EVENT_NONE +.. autodata:: EVENT_QUERYCHANGE - This constant is used to specify no information is available about the - event. +.. autodata:: EVENT_SHUTDOWN +.. autodata:: EVENT_SHUTDOWN_ANY -.. data:: EVENT_OBJCHANGE - - This constant is used to specify that a database change has taken place on - a table registered with the :meth:`Subscription.registerquery()` method. - - -.. data:: EVENT_QUERYCHANGE - - This constant is used to specify that the result set of a query registered - with the :meth:`Subscription.registerquery()` method has been changed. - - -.. data:: EVENT_SHUTDOWN - - This constant is used to specify that the instance is in the process of - being shut down. - - -.. data:: EVENT_SHUTDOWN_ANY - - This constant is used to specify that any instance (when running RAC) is in - the process of being shut down. - - -.. data:: EVENT_STARTUP - - This constant is used to specify that the instance is in the process of - being started up. - +.. autodata:: EVENT_STARTUP .. _cqn-operation-codes: Operation Codes --------------- -These constants are extensions to the DB API definition. They are possible -values for the ``operations`` parameter for the :meth:`Connection.subscribe()` -method. One or more of these values can be OR'ed together. These values are -also used by the :attr:`MessageTable.operation` or -:attr:`MessageQuery.operation` attributes of the messages that are sent. - - -.. data:: OPCODE_ALLOPS +The Operation code constants are possible values for the ``operations`` +parameter for the :meth:`Connection.subscribe()` method. One or more of these +values can be OR'ed together. These values are also used by the +:attr:`MessageTable.operation` or :attr:`MessageQuery.operation` attributes of +the messages that are sent. - This constant is used to specify that messages should be sent for all - operations. +.. dbapiconstantextension:: +.. autodata:: OPCODE_ALLOPS -.. data:: OPCODE_ALLROWS +.. autodata:: OPCODE_ALLROWS - This constant is used to specify that the table or query has been - completely invalidated. +.. autodata:: OPCODE_ALTER +.. autodata:: OPCODE_DELETE -.. data:: OPCODE_ALTER +.. autodata:: OPCODE_DROP - This constant is used to specify that messages should be sent when a - registered table has been altered in some fashion by DDL, or that the - message identifies a table that has been altered. +.. autodata:: OPCODE_INSERT - -.. data:: OPCODE_DELETE - - This constant is used to specify that messages should be sent when data is - deleted, or that the message identifies a row that has been deleted. - - -.. data:: OPCODE_DROP - - This constant is used to specify that messages should be sent when a - registered table has been dropped, or that the message identifies a table - that has been dropped. - - -.. data:: OPCODE_INSERT - - This constant is used to specify that messages should be sent when data is - inserted, or that the message identifies a row that has been inserted. - - -.. data:: OPCODE_UPDATE - - This constant is used to specify that messages should be sent when data is - updated, or that the message identifies a row that has been updated. +.. autodata:: OPCODE_UPDATE .. _connpoolmodes: Connection Pool Get Modes ------------------------- -These constants belong to the enumeration called ``PoolGetMode``. They are -possible values for the ``getmode`` parameters of +The Connection Pool Get mode constants belong to the enumeration called +``PoolGetMode``. They are possible values for the ``getmode`` parameters of :meth:`oracledb.create_pool()`, :meth:`oracledb.create_pool_async()`, -:meth:`PoolParams.set()`, and for related attributes. They have deprecated the -Session Pool mode constants that were used in cx_Oracle 8.3. The constants are -extensions to the DB API definition +:meth:`PoolParams.set()`, and for related attributes. These constants have +deprecated the Session Pool mode constants that were used in the obsolete +cx_Oracle driver. + +.. dbapiconstantextension:: .. versionchanged:: 2.3.0 @@ -3610,255 +605,119 @@ extensions to the DB API definition and acquisition ``getmode`` parameters were replaced with the enumeration ``PoolGetMode``. -.. data:: POOL_GETMODE_FORCEGET - - This constant is used to specify that a new connection should be created - and returned by :meth:`ConnectionPool.acquire()` if there are no free - connections available in the pool and the pool is already at its maximum - size. - - When a connection acquired in this mode is eventually released back to the - pool, it will be dropped and not added to the pool if the pool is still at - its maximum size. - - This enumerated value can also be identified by - ``oracledb.PoolGetMode.FORCEGET``. +.. autodata:: POOL_GETMODE_FORCEGET - This constant deprecates the ``SPOOL_ATTRVAL_FORCEGET`` constant that was - used in cx_Oracle 8.3. +.. autodata:: POOL_GETMODE_NOWAIT +.. autodata:: POOL_GETMODE_TIMEDWAIT -.. data:: POOL_GETMODE_NOWAIT +.. autodata:: POOL_GETMODE_WAIT - This constant is used to specify that an exception should be raised by - :meth:`ConnectionPool.acquire()` when all currently created connections are - already in use and so :meth:`~ConnectionPool.acquire()` cannot immediately - return a connection. Note the exception may occur even if the pool is - smaller than its maximum size. - - This enumerated value can also be identified by - ``oracledb.PoolGetMode.NOWAIT``. - - This constant deprecates the ``SPOOL_ATTRVAL_NOWAIT`` constant that was - used in cx_Oracle 8.3, and was the default ``getmode`` value. - - -.. data:: POOL_GETMODE_WAIT - - This constant is used to specify that :meth:`ConnectionPool.acquire()` - should wait until a connection is available if there are currently no free - connections available in the pool. This is the default value. - - This enumerated value can also be identified by - ``oracledb.PoolGetMode.WAIT``. - - This constant deprecates the ``SPOOL_ATTRVAL_WAIT`` constant that was - used in cx_Oracle 8.3. - - -.. data:: POOL_GETMODE_TIMEDWAIT - - This constant is used to specify that :meth:`ConnectionPool.acquire()` - should wait for a period of time (defined by the ``wait_timeout`` - parameter) for a connection to become available before returning with an - error. - - This enumerated value can also be identified by - ``oracledb.PoolGetMode.TIMEDWAIT``. - - This constant deprecates the ``SPOOL_ATTRVAL_TIMEDWAIT`` constant that was - used in cx_Oracle 8.3. .. _drcppurityconsts: Connection Pool Purity Constants -------------------------------- -These constants belong to the enumeration called ``Purity``. They are possible -values for the :ref:`drcp` ``purity`` parameter of -:meth:`oracledb.create_pool()`, :meth:`ConnectionPool.acquire()`, and -:meth:`oracledb.connect()`. They have deprecated the Session Pool purity -constants that were used in cx_Oracle 8.3. The constants are extensions to the -DB API definition. +The Connection Pool Purity constants belong to the enumeration called +``Purity``. They are possible values for the :ref:`drcp` ``purity`` parameter +of :meth:`oracledb.create_pool()`, :meth:`ConnectionPool.acquire()`, +:meth:`oracledb.connect()`, :meth:`oracledb.create_pool_async()`, and +:meth:`oracledb.connect_async()`. These constants have deprecated the Session +Pool purity constants that were used in the obsolete cx_Oracle driver. + +.. dbapiconstantextension:: .. versionchanged:: 2.3.0 The integer constants for the connection pool get modes were replaced with the enumeration ``Purity``. -.. data:: PURITY_DEFAULT - - This constant is used to specify that the purity of the session is the - default value identified by Oracle (see Oracle's documentation for more - information). This is the default value. - - This enumerated value can also be identified by - ``oracledb.Purity.DEFAULT``. - - This constant deprecates the ``ATTR_PURITY_DEFAULT`` constant that was used - in cx_Oracle 8.3, and was the default ``purity`` value. +.. autodata:: PURITY_DEFAULT -.. data:: PURITY_NEW +.. autodata:: PURITY_NEW - This constant is used to specify that the session acquired from the pool - should be new and not have any prior session state. +.. autodata:: PURITY_SELF - This enumerated value can also be identified by ``oracledb.Purity.NEW``. - - This constant deprecates the ``ATTR_PURITY_NEW`` constant that was used in - cx_Oracle 8.3. - - -.. data:: PURITY_SELF - - This constant is used to specify that the session acquired from the pool - need not be new and may have prior session state. - - This enumerated value can also be identified by ``oracledb.Purity.SELF``. - - This constant deprecates the ``ATTR_PURITY_SELF`` constant that was used in - cx_Oracle 8.3. Subscription Grouping Classes ----------------------------- -These constants are extensions to the DB API definition. They are possible -values for the ``groupingClass`` parameter of the :meth:`Connection.subscribe()` -method. +The Subscription Grouping Class constants are possible values for the +``groupingClass`` parameter of the :meth:`Connection.subscribe()` method. -.. data:: SUBSCR_GROUPING_CLASS_TIME +.. dbapiconstantextension:: - This constant is used to specify that events are to be grouped by the - period of time in which they are received. +.. autodata:: SUBSCR_GROUPING_CLASS_NONE +.. autodata:: SUBSCR_GROUPING_CLASS_TIME Subscription Grouping Types --------------------------- -These constants are extensions to the DB API definition. They are possible -values for the ``groupingType`` parameter of the :meth:`Connection.subscribe()` -method. - -.. data:: SUBSCR_GROUPING_TYPE_SUMMARY - - This constant is used to specify that when events are grouped a summary of - the events should be sent instead of the individual events. This is the - default value. +The Subscription Grouping Type constants are possible values for the +``groupingType`` parameter of the :meth:`Connection.subscribe()` method. -.. data:: SUBSCR_GROUPING_TYPE_LAST +.. dbapiconstantextension:: - This constant is used to specify that when events are grouped the last - event that makes up the group should be sent instead of the individual - events. +.. autodata:: SUBSCR_GROUPING_TYPE_SUMMARY +.. autodata:: SUBSCR_GROUPING_TYPE_LAST .. _subscr-namespaces: Subscription Namespaces ----------------------- -These constants are extensions to the DB API definition. They are possible -values for the ``namespace`` parameter of the :meth:`Connection.subscribe()` -method. +The Subscription Namespace constants are possible values for the ``namespace`` +parameter of the :meth:`Connection.subscribe()` method. -.. data:: SUBSCR_NAMESPACE_AQ +.. dbapiconstantextension:: - This constant is used to specify that notifications should be sent when a - queue has messages available to dequeue. - -.. data:: SUBSCR_NAMESPACE_DBCHANGE - - This constant is used to specify that database change notification or query - change notification messages are to be sent. This is the default value. +.. autodata:: SUBSCR_NAMESPACE_AQ +.. autodata:: SUBSCR_NAMESPACE_DBCHANGE .. _subscr-protocols: Subscription Protocols ---------------------- -These constants are extensions to the DB API definition. They are possible -values for the ``protocol`` parameter of the :meth:`Connection.subscribe()` -method. - -.. data:: SUBSCR_PROTO_CALLBACK - - This constant is used to specify that notifications will be sent to the - callback routine identified when the subscription was created. It is the - default value and the only value currently supported. - - -.. data:: SUBSCR_PROTO_HTTP - - This constant is used to specify that notifications will be sent to an - HTTP URL when a message is generated. This value is currently not - supported. +The Subscription Protocol constants are possible values for the ``protocol`` +parameter of the :meth:`Connection.subscribe()` method. +.. dbapiconstantextension:: -.. data:: SUBSCR_PROTO_MAIL +.. autodata:: SUBSCR_PROTO_CALLBACK - This constant is used to specify that notifications will be sent to an - e-mail address when a message is generated. This value is currently not - supported. +.. autodata:: SUBSCR_PROTO_HTTP +.. autodata:: SUBSCR_PROTO_MAIL -.. data:: SUBSCR_PROTO_OCI - - This constant is used to specify that notifications will be sent to the - callback routine identified when the subscription was created. It is the - default value and the only value currently supported. - - .. deprecated:: python-oracledb 1.0 - - Use :data:`~oracledb.SUBSCR_PROTO_CALLBACK` instead. - - -.. data:: SUBSCR_PROTO_SERVER - - This constant is used to specify that notifications will be sent to a - PL/SQL procedure when a message is generated. This value is currently not - supported. - +.. autodata:: SUBSCR_PROTO_SERVER .. _subscr-qos: Subscription Quality of Service ------------------------------- -These constants are extensions to the DB API definition. They are possible -values for the ``qos`` parameter of the :meth:`Connection.subscribe()` method. -One or more of these values can be OR'ed together. +The Subscription Quality of Service constants are possible values for the +``qos`` parameter of the :meth:`Connection.subscribe()` method. One or more of +these values can be OR'ed together. -.. data:: SUBSCR_QOS_BEST_EFFORT +.. dbapiconstantextension:: - This constant is used to specify that best effort filtering for query - result set changes is acceptable. False positive notifications may be - received. This behaviour may be suitable for caching applications. +.. autodata:: SUBSCR_QOS_BEST_EFFORT +.. autodata:: SUBSCR_QOS_DEFAULT -.. data:: SUBSCR_QOS_DEREG_NFY +.. autodata:: SUBSCR_QOS_DEREG_NFY - This constant is used to specify that the subscription should be - automatically unregistered after the first notification is received. +.. autodata:: SUBSCR_QOS_QUERY +.. autodata:: SUBSCR_QOS_RELIABLE -.. data:: SUBSCR_QOS_QUERY - - This constant is used to specify that notifications should be sent if the - result set of the registered query changes. By default, no false positive - notifications will be generated. - - -.. data:: SUBSCR_QOS_RELIABLE - - This constant is used to specify that notifications should not be lost in - the event of database failure. - - -.. data:: SUBSCR_QOS_ROWIDS - - This constant is used to specify that the rowids of the inserted, updated - or deleted rows should be included in the message objects that are sent. +.. autodata:: SUBSCR_QOS_ROWIDS .. _types: @@ -3866,48 +725,24 @@ One or more of these values can be OR'ed together. DB API Types ------------ -.. data:: BINARY - - This type object is used to describe columns in a database that contain - binary data. The database types :data:`DB_TYPE_RAW` and - :data:`DB_TYPE_LONG_RAW` will compare equal to this value. If a variable is - created with this type, the database type :data:`DB_TYPE_RAW` will be used. +.. autoclass:: ApiType + This type object is the Python type of the database API type constants. -.. data:: DATETIME +.. autodata:: BINARY + :no-value: - This type object is used to describe columns in a database that are dates. - The database types :data:`DB_TYPE_DATE`, :data:`DB_TYPE_TIMESTAMP`, - :data:`DB_TYPE_TIMESTAMP_LTZ` and :data:`DB_TYPE_TIMESTAMP_TZ` will all - compare equal to this value. If a variable is created with this - type, the database type :data:`DB_TYPE_DATE` will be used. +.. autodata:: DATETIME + :no-value: +.. autodata:: NUMBER + :no-value: -.. data:: NUMBER +.. autodata:: ROWID + :no-value: - This type object is used to describe columns in a database that are - numbers. The database types :data:`DB_TYPE_BINARY_DOUBLE`, - :data:`DB_TYPE_BINARY_FLOAT`, :data:`DB_TYPE_BINARY_INTEGER` and - :data:`DB_TYPE_NUMBER` will all compare equal to this value. If a variable - is created with this type, the database type :data:`DB_TYPE_NUMBER` will be - used. - - -.. data:: ROWID - - This type object is used to describe the pseudo column "rowid". The - database types :data:`DB_TYPE_ROWID` and :data:`DB_TYPE_UROWID` will - compare equal to this value. If a variable is created with this type, the - database type :data:`DB_TYPE_VARCHAR` will be used. - - -.. data:: STRING - - This type object is used to describe columns in a database that are - strings. The database types :data:`DB_TYPE_CHAR`, :data:`DB_TYPE_LONG`, - :data:`DB_TYPE_NCHAR`, :data:`DB_TYPE_NVARCHAR` and :data:`DB_TYPE_VARCHAR` - will all compare equal to this value. If a variable is created with this - type, the database type :data:`DB_TYPE_VARCHAR` will be used. +.. autodata:: STRING + :no-value: .. _dbtypes: @@ -3915,195 +750,98 @@ DB API Types Database Types -------------- -All of these types are extensions to the DB API definition. They are found in -query and object metadata. They can also be used to specify the database type -when binding data. - -Also see the table :ref:`supporteddbtypes`. - -.. data:: DB_TYPE_BFILE - - Describes columns, attributes or array elements in a database that are of - type BFILE. It will compare equal to the DB API type :data:`BINARY`. - - -.. data:: DB_TYPE_BINARY_DOUBLE - - Describes columns, attributes or array elements in a database that are of - type BINARY_DOUBLE. It will compare equal to the DB API type - :data:`NUMBER`. - - -.. data:: DB_TYPE_BINARY_FLOAT - - Describes columns, attributes or array elements in a database that are - of type BINARY_FLOAT. It will compare equal to the DB API type - :data:`NUMBER`. +.. autoclass:: DbType + This type object is the Python type of the database type constants. All of + these types are extensions to the DB API definition. They are found in + query and object metadata. They can also be used to specify the database + type when binding data. -.. data:: DB_TYPE_BINARY_INTEGER + Also see the table :ref:`supporteddbtypes`. - Describes attributes or array elements in a database that are of type - BINARY_INTEGER. It will compare equal to the DB API type :data:`NUMBER`. +.. autodata:: DB_TYPE_BFILE + :no-value: +.. autodata:: DB_TYPE_BINARY_DOUBLE + :no-value: -.. data:: DB_TYPE_BLOB +.. autodata:: DB_TYPE_BINARY_FLOAT + :no-value: - Describes columns, attributes or array elements in a database that are of - type BLOB. It will compare equal to the DB API type :data:`BINARY`. +.. autodata:: DB_TYPE_BINARY_INTEGER + :no-value: +.. autodata:: DB_TYPE_BLOB + :no-value: -.. data:: DB_TYPE_BOOLEAN +.. autodata:: DB_TYPE_BOOLEAN + :no-value: - Describes attributes or array elements in a database that are of type - BOOLEAN. It is only available in Oracle 12.1 and higher and only within - PL/SQL. +.. autodata:: DB_TYPE_CHAR + :no-value: +.. autodata:: DB_TYPE_CLOB + :no-value: -.. data:: DB_TYPE_CHAR +.. autodata:: DB_TYPE_CURSOR + :no-value: - Describes columns, attributes or array elements in a database that are of - type CHAR. It will compare equal to the DB API type :data:`STRING`. +.. autodata:: DB_TYPE_DATE + :no-value: - Note that these are fixed length string values and behave differently from - VARCHAR2. +.. autodata:: DB_TYPE_INTERVAL_DS + :no-value: +.. autodata:: DB_TYPE_INTERVAL_YM + :no-value: -.. data:: DB_TYPE_CLOB +.. autodata:: DB_TYPE_JSON + :no-value: - Describes columns, attributes or array elements in a database that are of - type CLOB. It will compare equal to the DB API type :data:`STRING`. +.. autodata:: DB_TYPE_LONG + :no-value: +.. autodata:: DB_TYPE_LONG_NVARCHAR + :no-value: -.. data:: DB_TYPE_CURSOR +.. autodata:: DB_TYPE_LONG_RAW + :no-value: - Describes columns in a database that are of type CURSOR. In PL/SQL, these - are known as REF CURSOR. +.. autodata:: DB_TYPE_NCHAR + :no-value: +.. autodata:: DB_TYPE_NCLOB + :no-value: -.. data:: DB_TYPE_DATE +.. autodata:: DB_TYPE_NUMBER + :no-value: - Describes columns, attributes or array elements in a database that are of - type DATE. It will compare equal to the DB API type :data:`DATETIME`. +.. autodata:: DB_TYPE_NVARCHAR + :no-value: +.. autodata:: DB_TYPE_OBJECT + :no-value: -.. data:: DB_TYPE_INTERVAL_DS +.. autodata:: DB_TYPE_RAW + :no-value: - Describes columns, attributes or array elements in a database that are of - type INTERVAL DAY TO SECOND. +.. autodata:: DB_TYPE_ROWID + :no-value: +.. autodata:: DB_TYPE_TIMESTAMP + :no-value: -.. data:: DB_TYPE_INTERVAL_YM +.. autodata:: DB_TYPE_TIMESTAMP_LTZ + :no-value: - Describes columns, attributes or array elements in a database that are of - type INTERVAL YEAR TO MONTH. +.. autodata:: DB_TYPE_TIMESTAMP_TZ + :no-value: +.. autodata:: DB_TYPE_UNKNOWN + :no-value: -.. data:: DB_TYPE_JSON - - Describes columns in a database that are of type JSON (with Oracle Database - 21 or later). - -.. data:: DB_TYPE_LONG - - Describes columns, attributes or array elements in a database that are of - type LONG. It will compare equal to the DB API type :data:`STRING`. - - -.. data:: DB_TYPE_LONG_RAW - - Describes columns, attributes or array elements in a database that are of - type LONG RAW. It will compare equal to the DB API type :data:`BINARY`. - - -.. data:: DB_TYPE_LONG_NVARCHAR - - This constant can be used in output type handlers when fetching NCLOB - columns as a string. (Note a type handler is not needed if - :ref:`oracledb.defaults.fetch_lobs ` is set to False). For IN - binds, this constant can be used to create a bind variable in - :meth:`Cursor.var()` or via :meth:`Cursor.setinputsizes()`. The - ``DB_TYPE_LONG_NVARCHAR`` value won't be shown in query metadata since it - is not a database type. - - It will compare equal to the DB API type :data:`STRING`. - -.. data:: DB_TYPE_NCHAR - - Describes columns, attributes or array elements in a database that are of - type NCHAR. It will compare equal to the DB API type :data:`STRING`. - - Note that these are fixed length string values and behave differently from - NVARCHAR2. - - -.. data:: DB_TYPE_NCLOB - - Describes columns, attributes or array elements in a database that are of - type NCLOB. It will compare equal to the DB API type :data:`STRING`. - - -.. data:: DB_TYPE_NUMBER - - Describes columns, attributes or array elements in a database that are of - type NUMBER. It will compare equal to the DB API type :data:`NUMBER`. - - -.. data:: DB_TYPE_NVARCHAR - - Describes columns, attributes or array elements in a database that are of - type NVARCHAR2. It will compare equal to the DB API type :data:`STRING`. - - -.. data:: DB_TYPE_OBJECT - - Describes columns, attributes or array elements in a database that are an - instance of a named SQL or PL/SQL type. - - -.. data:: DB_TYPE_RAW - - Describes columns, attributes or array elements in a database that are of - type RAW. It will compare equal to the DB API type :data:`BINARY`. - - -.. data:: DB_TYPE_ROWID - - Describes columns, attributes or array elements in a database that are of - type ROWID or UROWID. It will compare equal to the DB API type - :data:`ROWID`. - - -.. data:: DB_TYPE_TIMESTAMP - - Describes columns, attributes or array elements in a database that are of - type TIMESTAMP. It will compare equal to the DB API type :data:`DATETIME`. - - -.. data:: DB_TYPE_TIMESTAMP_LTZ - - Describes columns, attributes or array elements in a database that are of - type TIMESTAMP WITH LOCAL TIME ZONE. It will compare equal to the DB API - type :data:`DATETIME`. - - -.. data:: DB_TYPE_TIMESTAMP_TZ - - Describes columns, attributes or array elements in a database that are of - type TIMESTAMP WITH TIME ZONE. It will compare equal to the DB API type - :data:`DATETIME`. - - -.. data:: DB_TYPE_UNKNOWN - - Describes columns, attributes or array elements in a database that are - of an unknown type. - - -.. data:: DB_TYPE_UROWID - - Describes columns, attributes or array elements in a database that are of - type UROWID. It will compare equal to the DB API type :data:`ROWID`. +.. autodata:: DB_TYPE_UROWID + :no-value: .. note:: @@ -4111,24 +849,17 @@ Also see the table :ref:`supporteddbtypes`. See :ref:`querymetadatadiff`. -.. data:: DB_TYPE_VARCHAR - - Describes columns, attributes or array elements in a database that are of - type VARCHAR2. It will compare equal to the DB API type :data:`STRING`. +.. autodata:: DB_TYPE_VARCHAR + :no-value: - -.. data:: DB_TYPE_VECTOR - - Describes columns, attributes or array elements in a database that are of - type VECTOR. +.. autodata:: DB_TYPE_VECTOR + :no-value: .. versionadded:: 2.2.0 -.. data:: DB_TYPE_XMLTYPE - - Describes columns, attributes or array elements in a database that are of - type SYS.XMLTYPE. +.. autodata:: DB_TYPE_XMLTYPE + :no-value: .. versionadded:: 2.0.0 @@ -4252,30 +983,6 @@ version of python-oracledb. .. deprecated:: cx_Oracle 8.0 -Other Types ------------ - -All of these types are extensions to the DB API definition. - -.. data:: ApiType - - This type object is the Python type of the database API type constants - :data:`BINARY`, :data:`DATETIME`, :data:`NUMBER`, :data:`ROWID` and - :data:`STRING`. - - -.. data:: DbType - - This type object is the Python type of the - :ref:`database type constants `. - - -.. data:: LOB - - This type object is the Python type of :data:`DB_TYPE_BLOB`, - :data:`DB_TYPE_BFILE`, :data:`DB_TYPE_CLOB` and :data:`DB_TYPE_NCLOB` data - that is returned from cursors. - .. _tpcconstants: Two-Phase Commit (TPC) Constants @@ -4285,29 +992,17 @@ The constants for the two-phase commit (TPC) functions :meth:`~Connection.tpc_begin()` and :meth:`~Connection.tpc_end()` are listed below. -.. data:: TPC_BEGIN_JOIN - - Joins an existing TPC transaction. +.. autodata:: TPC_BEGIN_JOIN -.. data:: TPC_BEGIN_NEW +.. autodata:: TPC_BEGIN_NEW - Creates a new TPC transaction. +.. autodata:: TPC_BEGIN_PROMOTE -.. data:: TPC_BEGIN_PROMOTE +.. autodata:: TPC_BEGIN_RESUME - Promotes a local transaction to a TPC transaction. +.. autodata:: TPC_END_NORMAL -.. data:: TPC_BEGIN_RESUME - - Resumes an existing TPC transaction. - -.. data:: TPC_END_NORMAL - - Ends the TPC transaction participation normally. - -.. data:: TPC_END_SUSPEND - - Suspends the TPC transaction. +.. autodata:: TPC_END_SUSPEND .. _vectorformatconstants: @@ -4324,39 +1019,16 @@ possible values for the :attr:`FetchInfo.vector_format` attribute. The integer constants for the vector format constants were replaced with the enumeration ``VectorFormat``. -.. data:: VECTOR_FORMAT_BINARY - - This constant is used to represent the storage format of VECTOR columns - using 8-bit unsigned integers. - - This enumerated value can also be identified by - ``oracledb.VectorFormat.BINARY``. +.. autodata:: VECTOR_FORMAT_BINARY .. versionadded:: 2.3.0 -.. data:: VECTOR_FORMAT_FLOAT32 - - This constant is used to represent the storage format of VECTOR columns - using 32-bit floating point numbers. +.. autodata:: VECTOR_FORMAT_FLOAT32 - This enumerated value can also be identified by - ``oracledb.VectorFormat.FLOAT32``. +.. autodata:: VECTOR_FORMAT_FLOAT64 -.. data:: VECTOR_FORMAT_FLOAT64 +.. autodata:: VECTOR_FORMAT_INT8 - This constant is used to represent the storage format of VECTOR columns - using 64-bit floating point numbers. - - This enumerated value can also be identified by - ``oracledb.VectorFormat.FLOAT64``. - -.. data:: VECTOR_FORMAT_INT8 - - This constant is used to represent the storage format of VECTOR columns - using 8-bit signed integers. - - This enumerated value can also be identified by - ``oracledb.VectorFormat.INT8``. .. _exceptions: @@ -4365,80 +1037,26 @@ Oracledb Exceptions See :ref:`exception` for usage information. -.. exception:: Warning - - Exception raised for important warnings and defined by the DB API but not - actually used by python-oracledb. - -.. exception:: Error - - Exception that is the base class of all other exceptions defined by - python-oracledb and is a subclass of the Python StandardError exception - (defined in the module exceptions). - -.. exception:: InterfaceError +.. autoexception:: Warning - Exception raised for errors that are related to the database interface - rather than the database itself. It is a subclass of Error. +.. autoexception:: Error - Exception messages of this class will have the prefix DPY and an error - number in the range 1000 - 1999. +.. autoexception:: DataError -.. exception:: DatabaseError +.. autoexception:: DatabaseError - Exception raised for errors that are related to the database. It is a - subclass of Error. +.. autoexception:: IntegrityError - Exception messages of this class will have the prefix DPY and an error - number in the range 4000 - 4999. +.. autoexception:: InterfaceError -.. exception:: DataError +.. autoexception:: InternalError - Exception raised for errors that are due to problems with the processed - data. It is a subclass of DatabaseError. +.. autoexception:: NotSupportedError - Exception messages of this class are generated by the database and will - have a prefix such as ORA +.. autoexception:: OperationalError -.. exception:: OperationalError +.. autoexception:: ProgrammingError - Exception raised for errors that are related to the operation of the - database but are not necessarily under the control of the programmer. It is - a subclass of DatabaseError. - - Exception messages of this class will have the prefix DPY and an error - number in the range 6000 - 6999. - -.. exception:: IntegrityError - - Exception raised when the relational integrity of the database is affected. - It is a subclass of DatabaseError. - - Exception messages of this class are generated by the database and will - have a prefix such as ORA - -.. exception:: InternalError - - Exception raised when the database encounters an internal error. It is a - subclass of DatabaseError. - - Exception messages of this class will have the prefix DPY and an error - number in the range 5000 - 5999. - -.. exception:: ProgrammingError - - Exception raised for programming errors. It is a subclass of DatabaseError. - - Exception messages of this class will have the prefix DPY and an error - number in the range 2000 - 2999. - -.. exception:: NotSupportedError - - Exception raised when a method or database API was used which is not - supported by the database. It is a subclass of DatabaseError. - - Exception messages of this class will have the prefix DPY and an error - number in the range 3000 - 3999. .. _exchandling: @@ -4490,6 +1108,14 @@ See :ref:`exception` for usage information. See :ref:`tg` for more information. +.. _futureobj: + +Oracledb __future__ Object +========================== + +A special object that contains attributes which control the behavior of +python-oracledb, allowing for opting in for new features. + .. _oracledbplugins: Oracledb Plugins @@ -4527,7 +1153,8 @@ stored configuration information. Python-oracledb then uses this information to connect to Oracle Database. To use this plugin in python-oracledb Thick mode, you must set -:attr:`defaults.thick_mode_dsn_passthrough` to *False*. Alternatively use +:attr:`oracledb.defaults.thick_mode_dsn_passthrough +` to *False*. Alternatively use :meth:`ConnectParams.parse_connect_string()`, see :ref:`usingconnparams`. See :ref:`ociobjstorageprovider` for more information. @@ -4552,7 +1179,8 @@ stored configuration information. Python-oracledb then uses this information to connect to Oracle Database. To use this plugin in python-oracledb Thick mode, you must set -:attr:`defaults.thick_mode_dsn_passthrough` to *False*. Alternatively use +:attr:`oracledb.defaults.thick_mode_dsn_passthrough +` to *False*. Alternatively use :meth:`ConnectParams.parse_connect_string()`, see :ref:`usingconnparams`. See :ref:`azureappstorageprovider` for more information. @@ -4598,3 +1226,30 @@ Python-oracledb then uses these tokens to connect to Oracle Database. See :ref:`cloudnativeauthoauth` for more information. .. versionadded:: 3.0.0 + +.. _interval_ym: + +Oracledb IntervalYM Class +========================= + +Objects of this class are returned for columns of type INTERVAL YEAR TO MONTH +and can be passed to variables of type :data:`oracledb.DB_TYPE_INTERVAL_YM` +The class is a `collections.namedtuple() +`__ +class with two integer attributes, ``years`` and ``months``. + +.. versionadded:: 2.2.0 + +.. _jsonid: + +Oracledb JsonId Class +===================== + +Objects of this class are returned by :ref:`SODA ` in the ``_id`` +attribute of documents stored in native collections when using Oracle Database +23.4 (and later). It is a subclass of the `bytes `__ class. + +.. versionadded:: 2.1.0 + +.. dbapimethodextension:: diff --git a/doc/src/api_manual/pipeline.rst b/doc/src/api_manual/pipeline.rst index 326fe95b..f1b6e096 100644 --- a/doc/src/api_manual/pipeline.rst +++ b/doc/src/api_manual/pipeline.rst @@ -4,260 +4,157 @@ API: Pipeline Objects ********************* +.. currentmodule:: oracledb + Pipelining is only supported in python-oracledb Thin mode with :ref:`asyncio `. See :ref:`pipelining` for more information about pipelining. .. note:: - True pipelining is only available when connected to Oracle Database 23ai. + True pipelining is only available when connected to Oracle Database version + 23, or later. .. versionadded:: 2.4.0 .. _pipelineobjs: -Pipeline Objects -================ +Pipeline Class +============== -Pipeline objects represent a pipeline used to execute multiple database -operations. A Pipeline object is created by calling -:meth:`oracledb.create_pipeline()`. +.. autoclass:: Pipeline + + Pipeline objects represent a pipeline used to execute multiple database + operations. A Pipeline object is created by calling + :meth:`oracledb.create_pipeline()`. .. _pipelinemethods: Pipeline Methods ---------------- -.. method:: Pipeline.add_callfunc(name, return_type, parameters=None, keyword_parameters=None) - - Adds an operation to the pipeline that calls a stored PL/SQL function with - the given parameters and return type. The created - :ref:`PipelineOp object ` is also returned from this - function. :ref:`pipelineopattrs` can be used to examine the operation, if - needed. - - When the Pipeline is executed, the - :ref:`PipelineOpResult object ` that is returned for - this operation will have the :attr:`~PipelineOpResult.return_value` - attribute populated with the return value of the PL/SQL function if the - call completes successfully. - -.. method:: Pipeline.add_callproc(name, parameters=None, keyword_parameters=None) - - Adds an operation that calls a stored procedure with the given parameters. - The created :ref:`PipelineOp object ` is also returned - from this function. :ref:`pipelineopattrs` can be used to examine the - operation, if needed. - -.. method:: Pipeline.add_commit() - - Adds an operation that performs a commit. - -.. method:: Pipeline.add_execute(statement, parameters=None) - - Adds an operation that executes a statement with the given parameters. - The created :ref:`PipelineOp object ` is also returned - from this function. :ref:`pipelineopattrs` can be used to examine the - operation, if needed. - - Do not use this for queries that return rows. Instead use - :meth:`Pipeline.add_fetchall()`, :meth:`Pipeline.add_fetchmany()`, or - :meth:`Pipeline.add_fetchone()`. - -.. method:: Pipeline.add_executemany(statement, parameters) +.. automethod:: Pipeline.add_callfunc - Adds an operation that executes a SQL statement once using all bind value - mappings or sequences found in the sequence parameters. This can be used to - insert, update, or delete multiple rows in a table. It can also invoke a - PL/SQL procedure multiple times. See :ref:`batchstmnt`. +.. automethod:: Pipeline.add_callproc - The created :ref:`PipelineOp object ` is also returned from - this function. :ref:`pipelineopattrs` can be used to examine the operation, - if needed. +.. automethod:: Pipeline.add_commit - The ``parameters`` parameter can be a list of tuples, where each tuple item - maps to one bind variable placeholder in ``statement``. It can also be a - list of dictionaries, where the keys match the bind variable placeholder - names in ``statement``. If there are no bind values, or values have - previously been bound, the ``parameters`` value can be an integer - specifying the number of iterations. +.. automethod:: Pipeline.add_execute -.. method:: Pipeline.add_fetchall(statement, parameters=None, arraysize=None, rowfactory=None) +.. automethod:: Pipeline.add_executemany - Adds an operation that executes a query and returns all of the rows from - the result set. The created :ref:`PipelineOp object ` is - also returned from this function. :ref:`pipelineopattrs` can be used to - examine the operation, if needed. + .. seealso:: - When the Pipeline is executed, the :ref:`PipelineOpResult - object ` that is returned for this operation will - have the :attr:`~PipelineOpResult.rows` attribute populated with the list - of rows returned by the query. + :ref:`batchstmnt` - The default value for ``arraysize`` is :attr:`defaults.arraysize`. +.. automethod:: Pipeline.add_fetchall - Internally, this operation's :attr:`Cursor.prefetchrows` size is set to the - value of the explicit or default ``arraysize`` parameter value. + .. versionchanged:: 3.4.0 -.. method:: Pipeline.add_fetchmany(statement, parameters=None, num_rows=None, rowfactory=None) + The ``fetch_lobs`` and ``fetch_decimals`` parameters were added. - Adds an operation that executes a query and returns up to the specified - number of rows from the result set. The created - :ref:`PipelineOp object ` is also returned from this - function. :ref:`pipelineopattrs` can be used to examine the operation, if - needed. +.. automethod:: Pipeline.add_fetchmany - When the Pipeline is executed, the - :ref:`PipelineOpResult object ` that is returned for - this operation will have the :attr:`~PipelineOpResult.rows` attribute - populated with the list of rows returned by the query. + .. versionchanged:: 3.4.0 - The default value for ``num_rows`` is the value of - :attr:`defaults.arraysize`. + The ``fetch_lobs`` and ``fetch_decimals`` parameters were added. - Internally, this operation's :attr:`Cursor.prefetchrows` size is set to the - value of the explicit or default ``num_rows`` parameter, allowing all rows - to be fetched in one :ref:`round-trip ` + .. seealso:: - Since only one fetch is performed for a query operation, consider adding a - ``FETCH NEXT`` clause to the statement to prevent the database processing - rows that will never be fetched, see :ref:`rowlimit`. + :ref:`roundtrips`, and :ref:`rowlimit` -.. method:: Pipeline.add_fetchone(statement, parameters=None, rowfactory=None) +.. automethod:: Pipeline.add_fetchone - Adds an operation that executes a query and returns the first row of the - result set if one exists. The created - :ref:`PipelineOp object ` is also returned from this - function. :ref:`pipelineopattrs` can be used to examine the operation, if - needed. + .. versionchanged:: 3.4.0 - When the Pipeline is executed, the - :ref:`PipelineOpResult object ` that is returned for - this operation will have the :attr:`~PipelineOpResult.rows` attribute - populated with this row if the query is performed successfully. + The ``fetch_lobs`` and ``fetch_decimals`` parameters were added. - Internally, this operation's :attr:`Cursor.prefetchrows` and - :attr:`Cursor.arraysize` sizes will be set to 1. + .. seealso:: - Since only one fetch is performed for a query operation, consider adding a - ``WHERE`` condition or using a ``FETCH NEXT`` clause in the statement to - prevent the database processing rows that will never be fetched, see - :ref:`rowlimit`. + :ref:`rowlimit` Pipeline Attributes ------------------- -.. attribute:: Pipeline.operations - - This read-only attribute returns the list of operations associated with - the pipeline. +.. autoproperty:: Pipeline.operations .. _pipelineopobjs: -PipelineOp Objects -================== +PipelineOp Class +================ + +.. autoclass:: PipelineOp -PipelineOp objects are created by calling the methods in the -:ref:`Pipeline class `. + A PipelineOp object should be created by calling the methods in the + :ref:`Pipeline class `. .. _pipelineopattrs: PipelineOp Attributes --------------------- -.. attribute:: PipelineOp.arraysize +.. autoproperty:: PipelineOp.arraysize - This read-only attribute returns the :ref:`array size ` that - will be used when fetching query rows with :meth:`Pipeline.add_fetchall()`. - For all other operations, the value returned is *0*. + .. seealso:: -.. attribute:: PipelineOp.keyword_parameters + :ref:`tuningfetch` - This read-only attribute returns the keyword parameters to the stored - procedure or function being called by the operation, if applicable. +.. autoproperty:: PipelineOp.fetch_decimals -.. attribute:: PipelineOp.name + .. versionadded:: 3.4.0 - This read-only attribute returns the name of the stored procedure or - function being called by the operation, if applicable. +.. autoproperty:: PipelineOp.fetch_lobs -.. attribute:: PipelineOp.num_rows + .. versionadded:: 3.4.0 - This read-only attribute returns the number of rows to fetch when - performing a query of a specific number of rows. For all other operations, - the value returned is *0*. +.. autoproperty:: PipelineOp.keyword_parameters -.. attribute:: PipelineOp.op_type +.. autoproperty:: PipelineOp.name - This read-only attribute returns the type of operation that is taking - place. See :ref:`pipeline-operation-types` for types of operations. +.. autoproperty:: PipelineOp.num_rows -.. attribute:: PipelineOp.parameters +.. autoproperty:: PipelineOp.op_type - This read-only attribute returns the parameters to the stored procedure or - function or the parameters bound to the statement being executed by the - operation, if applicable. + See :ref:`pipeline-operation-types` for types of operations. -.. attribute:: PipelineOp.return_type +.. autoproperty:: PipelineOp.parameters - This read-only attribute returns the return type of the stored function - being called by the operation, if applicable. +.. autoproperty:: PipelineOp.return_type -.. attribute:: PipelineOp.rowfactory +.. autoproperty:: PipelineOp.rowfactory - This read-only attribute returns the row factory callable function to be - used in a query executed by the operation, if applicable. - -.. attribute:: PipelineOp.statement - - This read-only attribute returns the statement being executed by the - operation, if applicable. +.. autoproperty:: PipelineOp.statement .. _pipelineopresultobjs: PipelineOpResult Objects ======================== -When :meth:`AsyncConnection.run_pipeline()` is called, it returns a list of -PipelineOpResult objects. These objects contain the results of the executed -:ref:`PipelineOp objects ` operations. +.. autoclass:: PipelineOpResult + + When :meth:`AsyncConnection.run_pipeline()` is called, it returns a list of + PipelineOpResult objects. These objects contain the results of the executed + :ref:`PipelineOp objects ` operations. PipelineOpResult Attributes --------------------------- -.. attribute:: PipelineOpResult.columns - - This read-only attribute is a list of :ref:`FetchInfo` - objects. This attribute will be *None* for operations that do not return - rows. +.. autoproperty:: PipelineOpResult.columns .. versionadded:: 2.5.0 -.. attribute:: PipelineOpResult.error - - This read-only attribute returns the error that occurred when running this - operation. If no error occurred, then the value *None* is returned. - -.. attribute:: PipelineOpResult.operation +.. autoproperty:: PipelineOpResult.error - This read-only attribute returns the :ref:`PipelineOp ` - operation object that generated the result. +.. autoproperty:: PipelineOpResult.operation -.. attribute:: PipelineOpResult.return_value +.. autoproperty:: PipelineOpResult.return_value - This read-only attribute returns the return value of the called PL/SQL - function, if a function was called for the operation. +.. autoproperty:: PipelineOpResult.rows -.. attribute:: PipelineOpResult.rows +.. autoproperty:: PipelineOpResult.warning - This read-only attribute returns the rows that were fetched by the - operation, if a query was executed. - -.. attribute:: PipelineOpResult.warning + .. versionadded:: 2.5.0 - This read-only attribute returns any warning that was encountered when - running this operation. If no warning was encountered, then the value - *None* is returned. See :ref:`PL/SQL Compilation Warnings - `. + .. seealso:: - .. versionadded:: 2.5.0 + :ref:`PL/SQL Compilation Warnings ` diff --git a/doc/src/api_manual/pool_params.rst b/doc/src/api_manual/pool_params.rst index 5a802522..bdebeb3c 100644 --- a/doc/src/api_manual/pool_params.rst +++ b/doc/src/api_manual/pool_params.rst @@ -4,211 +4,162 @@ API: PoolParams Objects *********************** -A PoolParams object can be created with :meth:`oracledb.PoolParams()`. The -PoolParams class is a subclass of the :ref:`ConnectParams Class `. -In addition to the parameters and attributes of the ConnectParams class, the -PoolParams class also contains new parameters and attributes. +.. currentmodule:: oracledb -See :ref:`usingpoolparams` for more information. +PoolParams Class +================ -.. _poolparamsmeth: +.. autoclass:: PoolParams -PoolParams Methods -================== + The PoolParams class is a subclass of the :ref:`ConnectParams Class + `. In addition to the parameters and attributes of the + ConnectParams class, the PoolParams class also contains new parameters and + attributes. + + See :ref:`usingpoolparams` for more information. + + .. versionchanged:: 3.2.0 + + The ``pool_name`` parameter was added. + + .. versionchanged:: 3.0.0 + + The ``use_sni``, ``instance_name``, ``thick_mode_dsn_passthrough``, + ``extra_auth_params``, and ``instance_name`` parameters were added. + + .. versionchanged:: 2.5.0 -.. method:: PoolParams.copy() + The ``program``, ``machine``, ``terminal``, ``osuser``, and + ``driver_name`` parameters were added. Support for ``edition`` and + ``appcontext`` was added to python-oracledb Thin mode. - Creates a copy of the parameters and returns it. + .. versionchanged:: 2.3.0 -.. method:: PoolParams.get_connect_string() + The default value of the ``retry_delay`` parameter was changed from *0* + seconds to *1* second. The default value of the ``tcp_connect_timeout`` + parameter was changed from *60.0* seconds to *20.0* seconds. The + ``ping_timeout`` and ``ssl_version`` parameters were added. - Returns the connection string associated with the PoolParams instance. + .. versionchanged:: 2.1.0 -.. method:: PoolParams.parse_connect_string(connect_string) + The ``pool_boundary`` and ``use_tcp_fast_open`` parameters were added. - Parses the connect string into its components and stores the parameters. + .. versionchanged:: 2.0.0 - The connect string can be an Easy Connect string, name-value pairs, or a - simple alias which is looked up in ``tnsnames.ora``. Parameters that are - found in the connect string override any currently stored values. + The ``ssl_context`` and ``sdu`` parameters were added. + + .. versionchanged:: 1.4.0 + + The ``connection_id_prefix`` parameter was added. + + +.. _poolparamsmeth: + +PoolParams Methods +================== -.. method:: PoolParams.set(min=None, max=None, increment=None, \ - connectiontype=None, getmode=None, homogeneous=None, timeout=None, \ - wait_timeout=None, max_lifetime_session=None, session_callback=None, \ - max_sessions_per_shard=None, soda_metadata_cache=None, \ - ping_interval=None, ping_timeout=None, user=None, proxy_user=None, \ - password=None, newpassword=None, wallet_password=None, \ - access_token=None, host=None, port=None, protocol=None, \ - https_proxy=None, https_proxy_port=None, service_name=None, \ - instance_name=None, sid=None, server_type=None, cclass=None, \ - purity=None, expire_time=None, retry_count=None, retry_delay=None, \ - tcp_connect_timeout=None, ssl_server_dn_match=None, \ - ssl_server_cert_dn=None, wallet_location=None, events=None, \ - externalauth=None, mode=None, disable_oob=None, stmtcachesize=None, \ - edition=None, tag=None, matchanytag=None, config_dir=None, \ - appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, \ - connection_id_prefix=None, ssl_context=None, sdu=None, \ - pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \ - program=oracledb.defaults.program, machine=oracledb.defaults.machine, \ - terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \ - driver_name=oracledb.defaults.driver_name, use_sni=None, \ - thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \ - extra_auth_params=None, handle=None) +.. automethod:: PoolParams.copy - Sets one or more of the parameters. +.. automethod:: PoolParams.get_connect_string - .. versionchanged:: 3.0.0 +.. automethod:: PoolParams.parse_connect_string - The ``use_sni``, ``thick_mode_dsn_passthrough``, - ``extra_auth_params`` and ``instance_name`` parameters were added. +.. automethod:: PoolParams.set - .. versionchanged:: 2.5.0 + .. versionchanged:: 3.2.0 - The ``program``, ``machine``, ``terminal``, ``osuser``, and - ``driver_name`` parameters were added. Support for ``edition`` and - ``appcontext`` was added to python-oracledb Thin mode. + The ``pool_name`` parameter was added. - .. versionchanged:: 2.3.0 + .. versionchanged:: 3.0.0 - The ``ping_timeout`` and ``ssl_version`` parameters were added. + The ``use_sni``, ``thick_mode_dsn_passthrough``, + ``extra_auth_params`` and ``instance_name`` parameters were added. - .. versionchanged:: 2.1.0 + .. versionchanged:: 2.5.0 - The ``pool_boundary`` and ``use_tcp_fast_open`` parameters were added. + The ``program``, ``machine``, ``terminal``, ``osuser``, and + ``driver_name`` parameters were added. Support for ``edition`` and + ``appcontext`` was added to python-oracledb Thin mode. + + .. versionchanged:: 2.3.0 + + The ``ping_timeout`` and ``ssl_version`` parameters were added. + + .. versionchanged:: 2.1.0 + + The ``pool_boundary`` and ``use_tcp_fast_open`` parameters were added. .. _poolparamsattr: PoolParams Attributes ===================== -.. attribute:: PoolParams.connectiontype +All properties are read only. - This read-only attribute specifies the class of the connection that should - be returned during calls to :meth:`ConnectionPool.acquire()`. It must be - Connection or a subclass of Connection. This attribute is of type - Type["oracledb.connection"]. The default value is ``oracledb.Connection``. +.. autoproperty:: PoolParams.connectiontype This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: PoolParams.getmode - - This read-write attribute is an integer that determines the behavior of - :meth:`ConnectionPool.acquire()`. The value of this attribute can be one of - the constants :data:`oracledb.POOL_GETMODE_WAIT`, - :data:`oracledb.POOL_GETMODE_NOWAIT`, :data:`oracledb.POOL_GETMODE_FORCEGET`, - or :data:`oracledb.POOL_GETMODE_TIMEDWAIT`. The default value is - :data:`oracledb.POOL_GETMODE_WAIT`. +.. autoproperty:: PoolParams.getmode This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: PoolParams.homogeneous - - This read-only attribute is a boolean which indicates whether the - connections are :ref:`homogeneous ` (same user) or - heterogeneous (multiple users). The default value is *True*. +.. autoproperty:: PoolParams.homogeneous This attribute is only supported in python-oracledb Thick mode. The python-oracledb Thin mode supports only homogeneous modes. -.. attribute:: PoolParams.increment - - This read-only attribute specifies the number of connections that should - be added to the pool whenever a new connection needs to be created. The - default value is *1*. +.. autoproperty:: PoolParams.increment This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: PoolParams.min - - This read-only attribute is an integer that specifies the minimum number - of connections that the pool should contain. The default value is *1*. +.. autoproperty:: PoolParams.min This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: PoolParams.max - - This read-only attribute specifies the maximum number of connections that - the pool should contain. The default value is *2*. +.. autoproperty:: PoolParams.max This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: PoolParams.max_lifetime_session +.. autoproperty:: PoolParams.max_lifetime_session - This read-only attribute is the maximum length of time (in seconds) that a - pooled connection may exist since first being created. A value of *0* means - there is no limit. Connections become candidates for termination when they - are acquired or released back to the pool, and have existed for longer than + Connections become candidates for termination when they are acquired or + released back to the pool, and have existed for longer than ``max_lifetime_session`` seconds. Connections that are in active use will not be closed. In python-oracledb Thick mode, Oracle Client libraries 12.1 or later must be used and, prior to Oracle Client 21, cleanup only occurs when the pool is accessed. -.. attribute:: PoolParams.max_sessions_per_shard - - This read-only attribute is an integer that determines the maximum number - of connections that may be associated with a particular shard. The default - value is *0*. +.. autoproperty:: PoolParams.max_sessions_per_shard This attribute is only supported in python-oracledb Thick mode. -.. attribute:: PoolParams.ping_interval - - This read-only attribute is an integer that specifies the length of time - (in seconds) after which an unused connection in the pool will be a - candidate for pinging when :meth:`ConnectionPool.acquire()` is called. - If the ping to the database indicates that the connection is not alive, - then a replacement connection will be returned by - :meth:`ConnectionPool.acquire()`. If the ``ping_interval`` is a negative - value, then the ping functionality will be disabled. The default value is - *60* seconds. - - This attribute is supported in both python-oracledb Thin and Thick modes. +.. autoproperty:: PoolParams.ping_interval -.. attribute:: PoolParams.ping_timeout + This attribute is supported in both python-oracledb Thin and Thick modes. - This read-only attribute is an integer that specifies the maximum length of - time (in milliseconds) that :meth:`ConnectionPool.acquire()` waits for a - connection to respond to any internal ping to the database. If the ping - does not respond within the specified time, then the connection is - destroyed and :meth:`~ConnectionPool.acquire()` returns a different - connection. The default value is *5000* milliseconds. +.. autoproperty:: PoolParams.ping_timeout This attribute is supported in both python-oracledb Thin and Thick modes. - .. versionadded:: 2.3.0 - -.. attribute:: PoolParams.session_callback + .. versionadded:: 2.3.0 - This read-only attribute specifies a callback that is invoked when a - connection is returned from the pool for the first time, or when the - connection tag differs from the one requested. +.. autoproperty:: PoolParams.session_callback This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: PoolParams.soda_metadata_cache - - This read-only attribute is a boolean that indicates whether SODA - metadata cache should be enabled or not. The default value is *False*. +.. autoproperty:: PoolParams.soda_metadata_cache This attribute is only supported in python-oracledb Thick mode. -.. attribute:: PoolParams.timeout +.. autoproperty:: PoolParams.timeout - This read-only attribute is an integer that specifies the length of time - (in seconds) that a connection may remain idle in the pool before it is - terminated. This applies only when the pool has more than ``min`` - connections open, allowing it to shrink to the specified minimum size. The - default value is *0* seconds. A value of *0* means that there is no maximum - time. + This applies only when the pool has more than ``min`` connections open, + allowing it to shrink to the specified minimum size. The default value is + *0* seconds. A value of *0* means that there is no maximum time. This attribute is supported in both python-oracledb Thin and Thick modes. -.. attribute:: PoolParams.wait_timeout - - This read-only attribute is an integer that specifies the length of time - (in milliseconds) that a caller should wait when acquiring a connection - from the pool with :attr:`~PoolParams.getmode` set to - :data:`~oracledb.POOLGETMODE_TIMEDWAIT`. The default value is *0* - milliseconds. +.. autoproperty:: PoolParams.wait_timeout This attribute is supported in both python-oracledb Thin and Thick modes. diff --git a/doc/src/api_manual/soda.rst b/doc/src/api_manual/soda.rst index 719e8c4e..8c2841db 100644 --- a/doc/src/api_manual/soda.rst +++ b/doc/src/api_manual/soda.rst @@ -4,15 +4,17 @@ API: SODA ********** +.. currentmodule:: oracledb + `Oracle Database Simple Oracle Document Access (SODA) `__ allows documents to be inserted, queried, and retrieved from Oracle Database -using a set of NoSQL-style python-oracledb methods. By default, documents are JSON -strings. See the :ref:`user manual ` for examples. +using a set of NoSQL-style python-oracledb methods. By default, documents are +JSON strings. See the :ref:`user manual ` for examples. .. note:: - SODA is only supported in the python-oracledb Thick mode. See + SODA is only supported in python-oracledb Thick mode. See :ref:`enablingthick`. .. _sodarequirements: @@ -28,17 +30,16 @@ DBA: SQL> grant soda_app, create table to myuser; -Advanced users who are using Oracle sequences for keys will also need the CREATE -SEQUENCE privilege. +Advanced users who are using Oracle sequences for keys will also need the +CREATE SEQUENCE privilege. SODA requires Oracle Client 18.3 or higher and Oracle Database 18.1 and higher. .. note:: - SODA APIs are only supported in the python-oracledb Thick mode. See + SODA APIs are only supported in python-oracledb Thick mode. See :ref:`enablingthick`. - If you are using Oracle Database 21c (or later) and create new collections you need to do one of the following: @@ -77,576 +78,281 @@ the specification in the collection metadata``. .. _sodadb: -SodaDatabase Objects -==================== +SodaDatabase Class +================== -The SODA Database object is an extension to the DB API. It is returned by the -method :meth:`Connection.getSodaDatabase()`. +.. autoclass:: SodaDatabase + A SodaDatabase object is returned by :meth:`Connection.getSodaDatabase()`. + + .. dbapiobjectextension:: SodaDatabase Methods -------------------- -.. method:: SodaDatabase.createCollection(name, metadata=None, mapMode=False) - - Creates a SODA collection with the given name and returns a new - :ref:`SODA collection object `. If you try to create a - collection, and a collection with the same name and metadata already - exists, then that existing collection is opened without error. - - If ``metadata`` is specified, it is expected to be a string containing - valid JSON or a dictionary that will be transformed into a JSON - string. This JSON permits you to specify the configuration of the - collection including storage options; specifying the presence or absence of - columns for creation timestamp, last modified timestamp and version; - whether the collection can store only JSON documents; and methods of key - and version generation. The default metadata creates a collection that only - supports JSON documents and uses system generated keys. See this - `collection metadata reference `__ for - more information. - - If the ``mapMode`` parameter is set to *True*, the new collection is mapped - to an existing table instead of creating a table. If a collection is - created in this way, dropping the collection will not drop the existing - table either. - - -.. method:: SodaDatabase.createDocument(content, key=None, mediaType="application/json") - - Creates a :ref:`SODA document ` usable for SODA write operations. - You only need to use this method if your collection requires - client-assigned keys or has non-JSON content; otherwise, you can pass your - content directly to SODA write operations. SodaDocument attributes - :attr:`~SodaDoc.createdOn`, :attr:`~SodaDoc.lastModified`, and - :attr:`~SodaDoc.version` will be *None*. - - The ``content`` parameter can be a dictionary or list which will be - transformed into a JSON string and then UTF-8 encoded. It can also be a - string which will be UTF-8 encoded or it can be a bytes object which will - be stored unchanged. If a bytes object is provided and the content is - expected to be JSON, note that SODA only supports UTF-8, UTF-16LE and - UTF-16BE encodings. +.. automethod:: SodaDatabase.createCollection - The ``key`` parameter should only be supplied if the collection in which the - document is to be placed requires client-assigned keys. + .. seealso:: - The ``mediaType`` parameter should only be supplied if the collection in which - the document is to be placed supports non-JSON documents and the content - for this document is non-JSON. Using a standard MIME type for this value is - recommended but any string will be accepted. + :ref:`SODA collection object ` and `Oracle Database SODA + Collection Metadata Reference `__ +.. automethod:: SodaDatabase.createDocument -.. method:: SodaDatabase.getCollectionNames(startName=None, limit=0) +.. automethod:: SodaDatabase.getCollectionNames - Returns a list of the names of collections in the database that match the - criteria, in alphabetical order. +.. automethod:: SodaDatabase.openCollection - If the ``startName`` parameter is specified, the list of names returned will - start with this value and also contain any names that fall after this value - in alphabetical order. - - If the ``limit`` parameter is specified and is non-zero, the number of - collection names returned will be limited to this value. - - -.. method:: SodaDatabase.openCollection(name) +.. _sodacoll: - Opens an existing collection with the given name and returns a new - :ref:`SODA collection object `. If a collection with that name - does not exist, *None* is returned. +SodaCollection Class +==================== -.. _sodacoll: +.. autoclass:: SodaCollection -SodaCollection Objects -====================== + A SODA Collection object is used to represent SODA collections and is + created by :meth:`SodaDatabase.createCollection()` and + :meth:`SodaDatabase.openCollection()`. -The SODA Collection object is an extension to the DB API. It is used to -represent SODA collections and is created by methods -:meth:`SodaDatabase.createCollection()` and -:meth:`SodaDatabase.openCollection()`. + .. dbapiobjectextension:: SodaCollection Methods ---------------------- -.. method:: SodaCollection.createIndex(spec) - - Creates an index on a SODA collection. The spec is expected to be a - dictionary or a JSON-encoded string. See this `overview - `__ - for information on indexes in SODA. - - .. note:: - - A commit should be performed before attempting to create an index. - +.. automethod:: SodaCollection.createIndex -.. method:: SodaCollection.drop() + .. seealso:: - Drops the collection from the database, if it exists. Note that if the - collection was created with the ``mapMode`` parameter set to *True* the - underlying table will not be dropped. + `Overview of SODA Indexing `__ - A boolean value is returned indicating if the collection was actually - dropped. +.. automethod:: SodaCollection.drop +.. automethod:: SodaCollection.dropIndex -.. method:: SodaCollection.dropIndex(name, force=False) + .. seealso:: - Drops the index with the specified name, if it exists. + `DROP INDEX statement `__ - The ``force`` parameter, if set to *True*, can be used to force the - dropping of an index that the underlying Oracle Database domain index - does not normally permit. This is only applicable to spatial and JSON - search indexes. See `here `__ for more - information. +.. automethod:: SodaCollection.find - A boolean value is returned indicating if the index was actually dropped. + .. seealso:: + :ref:`SodaOperation object ` -.. method:: SodaCollection.find() +.. automethod:: SodaCollection.getDataGuide - This method is used to begin an operation that will act upon documents in - the collection. It creates and returns a - :ref:`SodaOperation object ` which is used to specify the criteria - and the operation that will be performed on the documents that match that - criteria. + .. seealso:: + :ref:`SODA document object ` -.. method:: SodaCollection.getDataGuide() +.. automethod:: SodaCollection.insertMany - Returns a :ref:`SODA document object ` containing property names, - data types and lengths inferred from the JSON documents in the collection. - It can be useful for exploring the schema of a collection. Note that this - method is only supported for JSON-only collections where a JSON search - index has been created with the 'dataguide' option enabled. If there are - no documents in the collection, *None* is returned. + .. seealso:: -.. method:: SodaCollection.insertMany(docs) + :ref:`SODA document object `. - Inserts a list of documents into the collection at one time. Each of the - input documents can be a dictionary or list or an existing :ref:`SODA - document object `. +.. automethod:: SodaCollection.insertManyAndGet - .. note:: + .. seealso:: - This method requires Oracle Client 18.5 and higher and is available - only as a preview. + :ref:`SODA Document objects `, `MONITOR and NO_MONITOR Hints + `__, and `Monitoring Database Operations + `__ +.. automethod:: SodaCollection.insertOne -.. method:: SodaCollection.insertManyAndGet(docs, hint=None) + .. seealso:: - Similarly to :meth:`~SodaCollection.insertMany()` this method inserts a - list of documents into the collection at one time. The only difference is - that it returns a list of :ref:`SODA Document objects `. Note that - for performance reasons the returned documents do not contain the content. + :ref:`SODA document object ` - The ``hint`` parameter, if specified, supplies a hint to the database when - processing the SODA operation. This is expected to be a string in the same - format as a SQL hint but without any comment characters, for example - ``hint="MONITOR"``. Pass only the hint "MONITOR" (turn on monitoring) - or "NO_MONITOR" (turn off monitoring). See the Oracle Database SQL - Tuning Guide documentation `MONITOR and NO_MONITOR Hints - `__ - and `Monitoring Database Operations - `__ - for more information. +.. automethod:: SodaCollection.insertOneAndGet - .. note:: + .. seealso:: - - This method requires Oracle Client 18.5 and higher. + :ref:`SODA Document object `, `MONITOR and NO_MONITOR Hints + `__, and `Monitoring Database Operations + `__ - - Use of the ``hint`` parameter requires Oracle Client 21.3 or higher - (or Oracle Client 19 from 19.11). - - -.. method:: SodaCollection.insertOne(doc) - - Inserts a given document into the collection. The input document can be a - dictionary or list or an existing :ref:`SODA document object `. - - -.. method:: SodaCollection.insertOneAndGet(doc, hint=None) - - Similarly to :meth:`~SodaCollection.insertOne()` this method inserts a - given document into the collection. The only difference is that it - returns a :ref:`SODA Document object `. Note that for performance - reasons the returned document does not contain the content. - - The ``hint`` parameter, if specified, supplies a hint to the database when - processing the SODA operation. This is expected to be a string in the same - format as a SQL hint but without any comment characters, for example - ``hint="MONITOR"``. Pass only the hint "MONITOR" (turn on monitoring) - or "NO_MONITOR" (turn off monitoring). See the Oracle Database SQL - Tuning Guide documentation `MONITOR and NO_MONITOR Hints - `__ - and `Monitoring Database Operations - `__ - for more information. - - .. note:: - - Use of the ``hint`` parameter requires Oracle Client 21.3 or higher - (or Oracle Client 19 from 19.11). - -.. method:: SodaCollection.listIndexes() - - Returns a list of specifications for the indexes found on the collection. - - This method requires Oracle Client 21.3 or later (or Oracle Client 19 from - 19.13). +.. automethod:: SodaCollection.listIndexes .. versionadded:: 1.4.0 -.. method:: SodaCollection.save(doc) - - Saves a document into the collection. This method is equivalent to - :meth:`~SodaCollection.insertOne()` except that if client-assigned keys are - used, and the document with the specified key already exists in the - collection, it will be replaced with the input document. - - This method requires Oracle Client 19.9 or higher in addition to the usual - SODA requirements. - - -.. method:: SodaCollection.saveAndGet(doc, hint=None) +.. automethod:: SodaCollection.save - Saves a document into the collection. This method is equivalent to - :meth:`~SodaCollection.insertOneAndGet()` except that if client-assigned - keys are used, and the document with the specified key already exists in - the collection, it will be replaced with the input document. +.. automethod:: SodaCollection.saveAndGet - The ``hint`` parameter, if specified, supplies a hint to the database when - processing the SODA operation. This is expected to be a string in the same - format as a SQL hint but without any comment characters, for example - ``hint="MONITOR"``. Pass only the hint "MONITOR" (turn on monitoring) - or "NO_MONITOR" (turn off monitoring). See the Oracle Database SQL - Tuning Guide documentation `MONITOR and NO_MONITOR Hints - `__ - and `Monitoring Database Operations - `__ - for more information. + .. seealso:: - This method requires Oracle Client 19.9 or higher in addition to the usual - SODA requirements. + `MONITOR and NO_MONITOR Hints `__ and + `Monitoring Database Operations `__ - .. note:: - - Use of the ``hint`` parameter requires Oracle Client 21.3 or higher - (or Oracle Client 19 from 19.11). - - -.. method:: SodaCollection.truncate() - - Removes all of the documents in the collection, similarly to what is done - for rows in a table by the TRUNCATE TABLE statement. +.. automethod:: SodaCollection.truncate SodaCollection Attributes ------------------------- -.. attribute:: SodaCollection.metadata - - This read-only attribute returns a dictionary containing the metadata that - was used to create the collection. See this `collection metadata reference - `__ for more information. +.. autoproperty:: SodaCollection.metadata + .. seealso:: -.. attribute:: SodaCollection.name - - This read-only attribute returns the name of the collection. + `Oracle Database SODA Collection Metadata Reference `__ +.. autoproperty:: SodaCollection.name .. _sodadoc: -SodaDoc Objects -=============== - -The SODA Document object is an extension to the DB API. It is returned by the -methods :meth:`SodaDatabase.createDocument()`, -:meth:`SodaOperation.getDocuments()` and :meth:`SodaOperation.getOne()` as -well as by iterating over :ref:`SODA document cursors `. - -SodaDoc Methods ---------------- - -.. method:: SodaDoc.getContent() - - Returns the content of the document as a dictionary or list. This method - assumes that the content is application/json and will raise an exception if - this is not the case. If there is no content, however, *None* will be - returned. - +SodaDocument Class +================== -.. method:: SodaDoc.getContentAsBytes() +.. autoclass:: SodaDocument - Returns the content of the document as a bytes object. If there is no - content, however, *None* will be returned. + A SODA Document object is returned by + :meth:`SodaDatabase.createDocument()`, + :meth:`SodaOperation.getDocuments()`, and + :meth:`SodaOperation.getOne()` as well as by iterating over + :ref:`SODA document cursors `. + .. dbapiobjectextension:: -.. method:: SodaDoc.getContentAsString() +SodaDocument Methods +-------------------- - Returns the content of the document as a string. If the document encoding - is not known, UTF-8 will be used. If there is no content, however, *None* - will be returned. +.. automethod:: SodaDocument.getContent -SodaDoc Attributes ------------------- +.. automethod:: SodaDocument.getContentAsBytes -.. attribute:: SodaDoc.createdOn +.. automethod:: SodaDocument.getContentAsString - This read-only attribute returns the creation time of the document in - `ISO 8601 `__ - format. Documents created by :meth:`SodaDatabase.createDocument()` or - fetched from collections where this attribute is not stored will return - *None*. +SodaDocument Attributes +----------------------- -.. attribute:: SodaDoc.key +.. autoproperty:: SodaDocument.createdOn - This read-only attribute returns the unique key assigned to this document. - Documents created by :meth:`SodaDatabase.createDocument()` may not have a - value assigned to them and return *None*. + .. seealso:: + `ISO 8601 `__ -.. attribute:: SodaDoc.lastModified +.. autoproperty:: SodaDocument.key - This read-only attribute returns the last modified time of the document in - `ISO 8601 `__ - format. Documents created by :meth:`SodaDatabase.createDocument()` or - fetched from collections where this attribute is not stored will return - *None*. +.. autoproperty:: SodaDocument.lastModified + .. seealso:: -.. attribute:: SodaDoc.mediaType + `ISO 8601 `__ - This read-only attribute returns the media type assigned to the document. - By convention this is expected to be a MIME type but no checks are - performed on this value. If a value is not specified when calling - :meth:`SodaDatabase.createDocument()` or the document is fetched from a - collection where this component is not stored, the string - "application/json" is returned. +.. autoproperty:: SodaDocument.mediaType +.. autoproperty:: SodaDocument.version -.. attribute:: SodaDoc.version +.. _sodadoccur: - This read-only attribute returns the version assigned to this document. - Documents created by :meth:`SodaDatabase.createDocument()` or fetched - from collections where this attribute is not stored will return *None*. +SodaDocCursor Class +=================== +.. autoclass:: SodaDocCursor -.. _sodadoccur: + A SodaDocCursor object is returned by :meth:`SodaOperation.getCursor()` + and implements the iterator protocol. Each iteration will return a + :ref:`SODA document object `. -SodaDocCursor Objects -===================== - -The SODA Document Cursor object is an extension to the DB API. It is returned -by the method :meth:`SodaOperation.getCursor()` and implements the iterator -protocol. Each iteration will return a :ref:`SODA document object -`. + .. dbapiobjectextension:: SodaDocCursor Methods --------------------- -.. method:: SodaDocCursor.close() +.. automethod:: SodaDocCursor.close - Closes the cursor now, rather than whenever __del__ is called. The cursor - will be unusable from this point forward; an Error exception will be raised - if any operation is attempted with the cursor. +.. _sodaop: +SodaOperation Class +=================== -.. _sodaop: +.. autoclass:: SodaOperation -SodaOperation Objects -===================== + A SODA Operation object represents an operation that will be performed on + all or some of the documents in a SODA collection. This object is created + by :meth:`SodaCollection.find()`. -The SODA Operation Object is an extension to the DB API. It represents an -operation that will be performed on all or some of the documents in a SODA -collection. It is created by the method :meth:`SodaCollection.find()`. + .. dbapiobjectextension:: SodaOperation Methods --------------------- -.. method:: SodaOperation.count() - - Returns a count of the number of documents in the collection that match - the criteria. If :meth:`~SodaOperation.skip()` or - :meth:`~SodaOperation.limit()` were called on this object, an exception is - raised. - - -.. method:: SodaOperation.fetchArraySize(value) - - This is a tuning method to specify the number of documents that are - internally fetched in batches by calls to :meth:`~SodaOperation.getCursor()` - and :meth:`~SodaOperation.getDocuments()`. It does not affect how many - documents are returned to the application. A value of *0* will use the - default value (*100*). This method is only available in Oracle Client 19.5 - and higher. - - As a convenience, the SodaOperation object is returned so that further - criteria can be specified by chaining methods together. - - -.. method:: SodaOperation.filter(value) - - Sets a filter specification for complex document queries and ordering of - JSON documents. Filter specifications must be provided as a dictionary or - JSON-encoded string and can include comparisons, regular expressions, - logical and spatial operators, among others. See the - `overview of SODA filter specifications - `__ - for more information. - - As a convenience, the SodaOperation object is returned so that further - criteria can be specified by chaining methods together. +.. automethod:: SodaOperation.count +.. automethod:: SodaOperation.fetchArraySize -.. method:: SodaOperation.getCursor() +.. automethod:: SodaOperation.filter - Returns a :ref:`SODA Document Cursor object ` that can be used - to iterate over the documents that match the criteria. + .. seealso:: + `Overview of SODA filter specifications `__ -.. method:: SodaOperation.getDocuments() +.. automethod:: SodaOperation.getCursor - Returns a list of :ref:`SODA Document objects ` that match the - criteria. + .. seealso:: + :ref:`SODA Document Cursor object ` -.. method:: SodaOperation.getOne() +.. automethod:: SodaOperation.getDocuments - Returns a single :ref:`SODA Document object ` that matches the - criteria. Note that if multiple documents match the criteria only the first - one is returned. + .. seealso:: + :ref:`SODA Document objects ` -.. method:: SodaOperation.hint(value) +.. automethod:: SodaOperation.getOne - Specifies a hint that will be provided to the SODA operation when it is - performed. This is expected to be a string in the same format as a SQL hint - but without any comment characters, for example ``hint("MONITOR")``. Pass - only the hint "MONITOR" (turn on monitoring) or "NO_MONITOR" (turn off - monitoring). See the Oracle Database SQL Tuning Guide documentation - `MONITOR and NO_MONITOR Hints `__ and - `Monitoring Database Operations `__ for more - information. + .. seealso:: - As a convenience, the SodaOperation object is returned so that further - criteria can be specified by chaining methods together. + :ref:`SODA Document object ` - Use of this method requires Oracle Client 21.3 or higher (or Oracle Client - 19 from 19.11). +.. automethod:: SodaOperation.hint -.. method:: SodaOperation.key(value) + .. seealso:: - Specifies that the document with the specified key should be returned. - This causes any previous calls made to this method and - :meth:`~SodaOperation.keys()` to be ignored. + Oracle Database SQL Tuning Guide documentation `MONITOR and NO_MONITOR + Hints `__ and `Monitoring Database + Operations `__ - As a convenience, the SodaOperation object is returned so that further - criteria can be specified by chaining methods together. +.. automethod:: SodaOperation.key +.. automethod:: SodaOperation.keys -.. method:: SodaOperation.keys(seq) +.. automethod:: SodaOperation.limit - Specifies that documents that match the keys found in the supplied sequence - should be returned. This causes any previous calls made to this method and - :meth:`~SodaOperation.key()` to be ignored. - - As a convenience, the SodaOperation object is returned so that further - criteria can be specified by chaining methods together. - - -.. method:: SodaOperation.limit(value) - - Specifies that only the specified number of documents should be returned. - This method is only usable for read operations such as - :meth:`~SodaOperation.getCursor()` and - :meth:`~SodaOperation.getDocuments()`. For write operations, any value set - using this method is ignored. - - As a convenience, the SodaOperation object is returned so that further - criteria can be specified by chaining methods together. - - -.. method:: SodaOperation.lock() - - Specifies whether the documents fetched from the collection should be - locked (equivalent to SQL "select for update"). - - The next commit or rollback on the connection made after the operation is - performed will "unlock" the documents. Ensure that the connection is not in - autocommit mode or the documents will be unlocked immediately after the - operation is complete. - - This method should only be used with read operations (other than - :func:`~SodaOperation.count()`) and should not be used in - conjunction with non-terminal methods :meth:`~SodaOperation.skip()` and - :meth:`~SodaOperation.limit()`. - - If this method is specified in conjunction with a write operation this - method is ignored. - - This method is only supported in Oracle Client 21.3 or later (or - Oracle Client 19 from 19.11). +.. automethod:: SodaOperation.lock .. versionadded:: 1.4.0 -.. method:: SodaOperation.remove() - - Removes all of the documents in the collection that match the criteria. The - number of documents that have been removed is returned. - - -.. method:: SodaOperation.replaceOne(doc) - - Replaces a single document in the collection with the specified document. - The input document can be a dictionary or list or an existing - :ref:`SODA document object `. A boolean indicating if a document - was replaced or not is returned. - - Currently the method :meth:`~SodaOperation.key()` must be called before - this method can be called. - - -.. method:: SodaOperation.replaceOneAndGet(doc) - - Similarly to :meth:`~SodaOperation.replaceOne()`, this method replaces a - single document in the collection with the specified document. The only - difference is that it returns a :ref:`SODA document object `. - Note that for performance reasons the returned document does not contain - the content. +.. automethod:: SodaOperation.remove +.. automethod:: SodaOperation.replaceOne -.. method:: SodaOperation.skip(value) + .. seealso:: - Specifies the number of documents that match the other criteria that will - be skipped. This method is only usable for read operations such as - :meth:`~SodaOperation.getOne()`, :meth:`~SodaOperation.getCursor()`, and - :meth:`~SodaOperation.getDocuments()`. For write operations, any value set - using this method is ignored. + :ref:`SODA document object ` - As a convenience, the SodaOperation object is returned so that further - criteria can be specified by chaining methods together. +.. automethod:: SodaOperation.replaceOneAndGet + .. seealso:: -.. method:: SodaOperation.version(value) + :ref:`SODA document object ` - Specifies that documents with the specified version should be returned. - Typically this is used with :meth:`~SodaOperation.key()` to implement - optimistic locking, so that the write operation called later does not - affect a document that someone else has modified. +.. automethod:: SodaOperation.skip - As a convenience, the SodaOperation object is returned so that further - criteria can be specified by chaining methods together. +.. automethod:: SodaOperation.version diff --git a/doc/src/api_manual/sparse_vector.rst b/doc/src/api_manual/sparse_vector.rst index c597372c..de75bc93 100644 --- a/doc/src/api_manual/sparse_vector.rst +++ b/doc/src/api_manual/sparse_vector.rst @@ -4,27 +4,22 @@ API: SparseVector Objects ************************* -A SparseVector Object stores information about a sparse vector. This object -can be created with :meth:`oracledb.SparseVector()`. +.. currentmodule:: oracledb -See :ref:`sparsevectors` for more information. +SparseVector Class +================== -.. versionadded:: 3.0.0 +.. autoclass:: SparseVector -SparseVector Attributes -======================= - -.. attribute:: SparseVector.indices + See :ref:`sparsevectors` for more information. - This read-only attribute is an array that returns the indices (zero-based) - of non-zero values in the vector. + .. versionadded:: 3.0.0 -.. attribute:: SparseVector.num_dimensions +SparseVector Attributes +======================= - This read-only attribute is an integer that returns the number of - dimensions of the vector. +.. autoproperty:: SparseVector.indices -.. attribute:: SparseVector.values +.. autoproperty:: SparseVector.num_dimensions - This read-only attribute is an array that returns the non-zero values - stored in the vector. +.. autoproperty:: SparseVector.values diff --git a/doc/src/api_manual/subscription.rst b/doc/src/api_manual/subscription.rst index de9b5b9c..5371de7d 100644 --- a/doc/src/api_manual/subscription.rst +++ b/doc/src/api_manual/subscription.rst @@ -4,265 +4,137 @@ API: Subscription Objects ************************* -.. note:: +.. currentmodule:: oracledb - This object is an extension the DB API. +.. dbapiobjectextension:: -Subscription Methods -==================== - -.. method:: Subscription.registerquery(statement, [args]) - - Registers the query for subsequent notification when tables referenced by - the query are changed. This behaves similarly to :meth:`Cursor.execute()` - but only queries are permitted and the ``args`` parameter must be a - sequence or dictionary. If the ``qos`` parameter included the flag - :data:`oracledb.SUBSCR_QOS_QUERY` when the subscription was created, then - the ID for the registered query is returned; otherwise, *None* is returned. - -Subscription Attributes -======================= - -.. attribute:: Subscription.callback +Subscription Class +================== - This read-only attribute returns the callback that was registered when the - subscription was created. +.. autoclass:: Subscription + A Subscription object should be created using + :meth:`Connection.subscribe()`. See :ref:`cqn` for more information. -.. attribute:: Subscription.connection - - This read-only attribute returns the connection that was used to register - the subscription when it was created. +Subscription Methods +-------------------- +.. automethod:: Subscription.registerquery -.. attribute:: Subscription.id +Subscription Attributes +----------------------- - This read-only attribute returns the value of the REGID column found in the - database view USER_CHANGE_NOTIFICATION_REGS or the value of the REG_ID - column found in the database view USER_SUBSCR_REGISTRATIONS. For AQ - subscriptions, the value is *0*. +.. autoproperty:: Subscription.callback +.. autoproperty:: Subscription.connection -.. attribute:: Subscription.ip_address +.. autoproperty:: Subscription.id - This read-only attribute returns the IP address used for callback - notifications from the database server. If not set during construction, - this value is *None*. +.. autoproperty:: Subscription.ip_address For consistency and compliance with the PEP 8 naming style, the attribute ``ipAddress`` was renamed to ``ip_address``. The old name will continue to work for a period of time. +.. autoproperty:: Subscription.name -.. attribute:: Subscription.name - - This read-only attribute returns the name used to register the subscription - when it was created. - - -.. attribute:: Subscription.namespace - - This read-only attribute returns the namespace used to register the - subscription when it was created. - - -.. attribute:: Subscription.operations +.. autoproperty:: Subscription.namespace - This read-only attribute returns the operations that will send - notifications for each table or query that is registered using this - subscription. +.. autoproperty:: Subscription.operations +.. autoproperty:: Subscription.port -.. attribute:: Subscription.port +.. autoproperty:: Subscription.protocol - This read-only attribute returns the port used for callback notifications - from the database server. If not set during construction, this value is - *0*. - - -.. attribute:: Subscription.protocol - - This read-only attribute returns the protocol used to register the - subscription when it was created. - - -.. attribute:: Subscription.qos - - This read-only attribute returns the quality of service flags used to - register the subscription when it was created. - - -.. attribute:: Subscription.timeout - - This read-only attribute returns the timeout (in seconds) that was - specified when the subscription was created. A value of *0* indicates that - there is no timeout. +.. autoproperty:: Subscription.qos +.. autoproperty:: Subscription.timeout .. _msgobjects: -Message Objects ---------------- +Message Class +============= -.. note:: +.. autoclass:: Message - This object is created internally when notification is received and passed - to the callback procedure specified when a subscription is created. + A Message object is created when a notification is received. They are + passed to the callback procedure specified when a subscription is created. -.. attribute:: Message.consumer_name +Message Attributes +------------------ - This read-only attribute returns the name of the consumer which generated - the notification. It will be populated if the subscription was created with - the namespace :data:`oracledb.SUBSCR_NAMESPACE_AQ` and the queue is a - multiple consumer queue. +.. autoproperty:: Message.consumer_name For consistency and compliance with the PEP 8 naming style, the attribute ``consumerName`` was renamed to ``consumer_name``. The old name will continue to work for a period of time. +.. autoproperty:: Message.dbname -.. attribute:: Message.dbname - - This read-only attribute returns the name of the database that generated - the notification. - -.. attribute:: Message.msgid - - This read-only attribute returns the message id of the AQ message which - generated the notification. It will only be populated if the subscription - was created with the namespace :data:`oracledb.SUBSCR_NAMESPACE_AQ`. - -.. attribute:: Message.queries - - This read-only attribute returns a list of message query objects that give - information about query result sets changed for this notification. This - attribute will be an empty list if the ``qos`` parameter did not include - the flag :data:`~oracledb.SUBSCR_QOS_QUERY` when the subscription was - created. +.. autoproperty:: Message.msgid +.. autoproperty:: Message.queries -.. attribute:: Message.queue_name - - This read-only attribute returns the name of the queue which generated the - notification. It will only be populated if the subscription was created - with the namespace :data:`oracledb.SUBSCR_NAMESPACE_AQ`. +.. autoproperty:: Message.queue_name For consistency and compliance with the PEP 8 naming style, the attribute ``queueName`` was renamed to ``queue_name``. The old name will continue to work for a period of time. +.. autoproperty:: Message.registered -.. attribute:: Message.registered - - This read-only attribute returns whether the subscription which generated - this notification is still registered with the database. The subscription - is automatically deregistered with the database when the subscription - timeout value is reached or when the first notification is sent (when the - quality of service flag :data:`oracledb.SUBSCR_QOS_DEREG_NFY` is used). - - -.. attribute:: Message.subscription - - This read-only attribute returns the subscription object for which this - notification was generated. - - -.. attribute:: Message.tables - - This read-only attribute returns a list of message table objects that give - information about the tables changed for this notification. This - attribute will be an empty list if the ``qos`` parameter included the flag - :data:`~oracledb.SUBSCR_QOS_QUERY` when the subscription was created. +.. autoproperty:: Message.subscription +.. autoproperty:: Message.tables -.. attribute:: Message.txid - - This read-only attribute returns the id of the transaction that generated - the notification. - - -.. attribute:: Message.type - - This read-only attribute returns the type of message that has been sent. - See the constants section on event types for additional information. - - -MessageTable Objects --------------------- - -.. note:: +.. autoproperty:: Message.txid - This object is created internally for each table changed when notification - is received and is found in the tables attribute of message objects, and - the tables attribute of message query objects. +.. autoproperty:: Message.type + See the constants section on :ref:`eventtypes` for additional information. -.. attribute:: MessageTable.name +MessageTable Class +================== - This read-only attribute returns the name of the table that was changed. +.. autoclass:: MessageTable + A MessageTable object is created when a notification is received for each + table change. They are accessed in the tables attribute of message + objects, and the tables attribute of message query objects. -.. attribute:: MessageTable.operation +.. autoproperty:: MessageTable.name - This read-only attribute returns the operation that took place on the table - that was changed. +.. autoproperty:: MessageTable.operation +.. autoproperty:: MessageTable.rows -.. attribute:: MessageTable.rows +MessageRow Class +================ - This read-only attribute returns a list of message row objects that give - information about the rows changed on the table. This value is only filled - in if the ``qos`` parameter to the :meth:`Connection.subscribe()` method - included the flag :data:`~oracledb.SUBSCR_QOS_ROWIDS`. +.. autoclass:: MessageRow - -MessageRow Objects ------------------- - -.. note:: - - This object is created internally for each row changed on a table when - notification is received and is found in the rows attribute of message + A MessageRow object is created when a notification is received for each + row changed in a table. They are found in the rows attribute of message table objects. +MessageRow Attributes +--------------------- -.. attribute:: MessageRow.operation - - This read-only attribute returns the operation that took place on the row - that was changed. - - -.. attribute:: MessageRow.rowid - - This read-only attribute returns the rowid of the row that was changed. - - -MessageQuery Objects --------------------- - -.. note:: - - This object is created internally for each query result set changed when - notification is received and is found in the queries attribute of message - objects. - - -.. attribute:: MessageQuery.id +.. autoproperty:: MessageRow.operation - This read-only attribute returns the query id of the query for which the - result set changed. The value will match the value returned by - :meth:`Subscription.registerquery()` when the related query was registered. +.. autoproperty:: MessageRow.rowid +MessageQuery Class +================== -.. attribute:: MessageQuery.operation +.. autoclass:: MessageQuery - This read-only attribute returns the operation that took place on the query - result set that was changed. Valid values for this attribute are - :data:`~oracledb.EVENT_DEREG` and :data:`~oracledb.EVENT_QUERYCHANGE`. + A MessageQuery object is created when a notification is received for a + query result set change. This object is found in the queries attribute of + message objects. +.. autoproperty:: MessageQuery.id -.. attribute:: MessageQuery.tables +.. autoproperty:: MessageQuery.operation - This read-only attribute returns a list of message table objects that give - information about the table changes that caused the query result set to - change for this notification. +.. autoproperty:: MessageQuery.tables diff --git a/doc/src/api_manual/variable.rst b/doc/src/api_manual/variable.rst index d6453ac5..dec5f024 100644 --- a/doc/src/api_manual/variable.rst +++ b/doc/src/api_manual/variable.rst @@ -4,110 +4,56 @@ API: Variable Objects ********************* -Variable objects are created with :meth:`Cursor.var()` or -:func:`Cursor.arrayvar()`. +.. currentmodule:: oracledb -.. note:: +Variable Class +============== - The DB API definition does not define this object. +.. autoclass:: Var -Variable Methods -================= + A Var object should be created with :meth:`Cursor.var()` or + :meth:`Cursor.arrayvar()`. -.. method:: Variable.getvalue([pos=0]) + .. dbapiobjectextension:: - Returns the value at the given position in the variable. For variables - created using the method :func:`Cursor.arrayvar()` the value returned will - be a list of each of the values in the PL/SQL index-by table. For variables - bound to DML returning statements, the value returned will also be a list - corresponding to the returned data for the given execution of the statement - (as identified by the ``pos`` parameter). +Variable Methods +================= -.. method:: Variable.setvalue(pos, value) +.. automethod:: Var.getvalue - Set the value at the given position in the variable. +.. automethod:: Var.setvalue Variable Attributes =================== -.. attribute:: Variable.actual_elements - - This read-only attribute returns the actual number of elements in the - variable. This corresponds to the number of elements in a PL/SQL index-by - table for variables that are created using the method - :func:`Cursor.arrayvar()`. For all other variables this value will be - identical to the attribute :attr:`~Variable.numElements`. +.. autoproperty:: Var.actual_elements For consistency and compliance with the PEP 8 naming style, the attribute ``actualElements`` was renamed to ``actual_elements``. The old name will continue to work for a period of time. - -.. attribute:: Variable.buffer_size - - This read-only attribute returns the size of the buffer allocated for each - element in bytes. +.. autoproperty:: Var.buffer_size For consistency and compliance with the PEP 8 naming style, the attribute ``bufferSize`` was renamed to ``buffer_size``. The old name will continue to work for a period of time. - -.. attribute:: Variable.convert_nulls - - This read-only attribute returns whether the :attr:`~Variable.outconverter` - method is called when null values are fetched from the database. +.. autoproperty:: Var.convert_nulls .. versionadded:: 1.4.0 -.. attribute:: Variable.inconverter - - This read-only attribute specifies the method used to convert data from - Python to the Oracle database. The method signature is converter(value) - and the expected return value is the value to bind to the database. If this - attribute is *None*, the value is bound directly without any conversion. - +.. autoproperty:: Var.inconverter -.. attribute:: Variable.num_elements - - This read-only attribute returns the number of elements allocated in an - array, or the number of scalar items that can be fetched into the variable - or bound to the variable. +.. autoproperty:: Var.num_elements For consistency and compliance with the PEP 8 naming style, the attribute ``numElements`` was renamed to ``num_elements``. The old name will continue to work for a period of time. +.. autoproperty:: Var.outconverter -.. attribute:: Variable.outconverter - - This read-only attribute specifies the method used to convert data from - the Oracle database to Python. The method signature is converter(value) - and the expected return value is the value to return to Python. If this - attribute is *None*, the value is returned directly without any conversion. - - -.. attribute:: Variable.size - - This read-only attribute returns the size of the variable. For strings this - value is the size in characters. For all others, this is same value as the - attribute bufferSize. - - -.. attribute:: Variable.type - - This read-only attribute returns the type of the variable. This will be an - :ref:`Oracle Object Type ` if the variable binds - Oracle objects; otherwise, it will be one of the - :ref:`database type constants `. - - Database type constants are now used when the variable is not used for - binding Oracle objects. - +.. autoproperty:: Var.size -.. attribute:: Variable.values +.. autoproperty:: Var.type - This read-only attribute returns a copy of the value of all actual - positions in the variable as a list. This is the equivalent of calling - :meth:`~Variable.getvalue()` for each valid position and the length will - correspond to the value of the :attr:`~Variable.actualElements` attribute. +.. autoproperty:: Var.values diff --git a/doc/src/conf.py b/doc/src/conf.py index 4b36b77b..ebb643d7 100644 --- a/doc/src/conf.py +++ b/doc/src/conf.py @@ -12,23 +12,39 @@ # serve to show the default value. import os +import pathlib import sys # If your extensions are in another directory, add it here. sys.path.append(os.path.abspath("_ext")) +# include the path of the source so that autodoc will function +sys.path.insert(0, str(pathlib.Path("..", "src").resolve())) + # General configuration # --------------------- # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ["table_with_summary", "oracle_deprecated", "sphinx_rtd_theme"] +extensions = [ + "table_with_summary", + "oracle_deprecated", + "dbapi_extension", + "sphinx_rtd_theme", + "sphinx.ext.autodoc", +] + +# preserve defaults in function signatures +autodoc_preserve_defaults = True + +# ensure that the constructor documentation is used in class documentation +autoclass_content = "init" # Add any paths that contain templates here, relative to this directory. templates_path = [".templates"] # The suffix of source filenames. -source_suffix = ".rst" +source_suffix = {".rst": "restructuredtext"} # The root toctree document. root_doc = master_doc = "index" diff --git a/doc/src/index.rst b/doc/src/index.rst index cd2c9c28..2f590eb8 100644 --- a/doc/src/index.rst +++ b/doc/src/index.rst @@ -2,9 +2,10 @@ Welcome to python-oracledb's documentation ========================================== The python-oracledb driver is an open source Python module that enables access -to Oracle Database. Python-oracledb is the renamed, major version successor to -cx_Oracle 8.3. The cx_Oracle driver is obsolete and should not be used for new -development. +to Oracle Database with no extra libraries needed. The module is built with +Cython for safety and speed. It is lightweight and high-performance. It is +stable, well tested, and has comprehensive documentation. The module is +maintained by Oracle. You can use assistive technology products, such as screen readers, while you work with the python-oracledb documentation. You can also use the keyboard @@ -21,6 +22,7 @@ User Guide user_guide/installation.rst user_guide/initialization.rst user_guide/connection_handling.rst + user_guide/authentication_methods.rst user_guide/sql_execution.rst user_guide/plsql_execution.rst user_guide/bind.rst @@ -31,14 +33,15 @@ User Guide user_guide/json_data_type.rst user_guide/xml_data_type.rst user_guide/vector_data_type.rst + user_guide/dataframes.rst user_guide/soda.rst user_guide/aq.rst user_guide/cqn.rst user_guide/two_phase_commit.rst user_guide/startup.rst user_guide/ha.rst - user_guide/globalization.rst user_guide/asyncio.rst + user_guide/globalization.rst user_guide/exception_handling.rst user_guide/tracing.rst user_guide/extending.rst @@ -46,6 +49,7 @@ User Guide user_guide/appendix_a.rst user_guide/appendix_b.rst user_guide/appendix_c.rst + user_guide/appendix_d.rst API Manual ========== @@ -74,6 +78,7 @@ API Manual api_manual/async_connection_pool.rst api_manual/async_cursor.rst api_manual/async_lob.rst + api_manual/async_aq.rst api_manual/pipeline.rst api_manual/deprecations.rst diff --git a/doc/src/release_notes.rst b/doc/src/release_notes.rst index 2193817a..72fb74d0 100644 --- a/doc/src/release_notes.rst +++ b/doc/src/release_notes.rst @@ -2,6 +2,8 @@ .. _releasenotes: +.. currentmodule:: oracledb + python-oracledb Release Notes ============================= @@ -11,8 +13,426 @@ Release changes are listed as affecting Thin Mode (the default runtime behavior of python-oracledb), as affecting the optional :ref:`Thick Mode `, or as being 'Common' for changes that impact both modes. -oracledb 3.0.0 (March 2025) ---------------------------- +oracledb `3.5.0 `__ (TBD) +-------------------------------------------------------------------------------------------- + +Thin Mode Changes ++++++++++++++++++ + +#) Fixed bug when using bind variables with scrollable cursors. + +Thick Mode Changes +++++++++++++++++++ + +#) Fixed segfault on some platforms when trying to execute queries returning + vector columns + (`ODPI-C `__ dependency update). + +Common Changes +++++++++++++++ + +#) Added Session Token-based authentication support when using + :ref:`OCI Cloud Native Authentication ` + (`issue 527 `__). +#) Fixed bug that caused ``ORA-03137: malformed TTC packet from client + rejected`` exception to be raised when attempting to call + :meth:`Cursor.parse()` on a scrollable cursor. +#) Updated the `Jupyter notebook samples `__ to cover recent + python-oracledb features. + + +oracledb `3.4.0 `__ (October 2025) +----------------------------------------------------------------------------------------------------- + +Thin Mode Changes ++++++++++++++++++ + +#) Added support for Oracle Database's :ref:`Direct Path Load + ` functionality which is very efficient for loading large + datasets into a database. Data may be a list of sequences or a DataFrame + object. +#) Fixed bug when setting values of type ``datetime.date`` on variables (such + as created by :meth:`Cursor.var()` or implicitly by + :meth:`Cursor.setinputsizes()`) of types + :attr:`oracledb.DB_TYPE_TIMESTAMP`, :attr:`oracledb.DB_TYPE_TIMESTAMP_TZ` + and :attr:`oracledb.DB_TYPE_TIMESTAMP_LTZ`. +#) Fixed bug validating the database host during connection. +#) Fixed bug causing hang due to blocked task cancellation during + :ref:`asyncio ` loop shutdown. +#) Internal change: refactor encoding of Oracle data types. +#) Internal change: small performance improvement sending bytes on the + network transport. + +Thick Mode Changes +++++++++++++++++++ + +#) Fixed bug with error wrapping which could result in garbage characters + being introduced. Fixed potential bug when truncation could occur with very + large error messages. +#) Executed statements are normalized by removing leading and trailing spaces + before being sent to Oracle Database. + +Common Changes +++++++++++++++ + +#) Changes to :ref:`data frame ` support: + + - Support for data frames is no longer considered a pre-release. + - Added parameter ``requested_schema`` to :meth:`Connection.fetch_df_all()` + and :meth:`Connection.fetch_df_batches()` to support type mapping when + querying + (`issue 494 `__). + - The Apache Arrow data type "large" variants that have 64-bit offsets are + now used by default for strings and binary values in order to avoid the + limits imposed by using 32-bit offsets. Use ``requested_schema`` if the + smaller offset size is desired + (`issue 536 `__). + - Added support for all of the signed and unsigned fixed width integer + types when ingesting data frames supporting the Arrow PyCapsule + interface. Previously only ``int64`` was supported. + - Added support for types ``date32`` and ``date64`` when ingesting data + frames supporting the Arrow PyCapsule interface as requested + (`issue 535 `__). + - Ingesting data frames with multiple chunks is now supported. + - Error ``DPY-8002: Apach Arrow C Data structure overflow detected. A + larger structure is needed.`` is now raised when an overflow is detected + (`issue 536 `__). + - Fixed bug when fetching NCHAR and NVARCHAR2 column data. + - Fixed bug when attempting to convert an integer that cannot be + represented as a native C ``int`` value to an Arrow data frame + (`issue 537 `__). + +#) Added a ``batch_size`` parameter to :meth:`Cursor.executemany()` and + :meth:`AsyncCursor.executemany()` to let these methods operate on data in + batches. +#) Added ``fetch_lobs`` and ``fetch_decimals`` parameters where applicable to + the methods used for fetching rows or data frames from the database. Note + that for the creation of pipeline operations, if these parameters are not + specified then the values of + :attr:`oracledb.defaults.fetch_lobs ` and + :attr:`oracledb.defaults.fetch_decimals ` are now + stored with the operation and used during pipeline execution + (`issue 19 `__). +#) Added optional dependencies `[oci_config]`, `[azure_config]`, + `[oci_auth]`, and `[azure_auth]` to simplify installation of required + packages for :ref:`Centralized Configuration Provider + ` support and :ref:`Cloud Native Authentication + ` support + (`issue 512 `__). +#) The x86_64 macOS and 32-bit Windows platforms are :ref:`deprecated + `. They will be desupported in a future release before, or + when, the `cryptography `__ package + desupports them. See the `cryptography deprecation announcement + `__. +#) Connectivity and interoperability with Oracle Database and Oracle Client + libraries older than version 19 is deprecated and will be removed in a + future version of python-oracledb. Production use, and availability of + database and client software, is detailed in `Release Schedule of Current + Database Releases `__. +#) Pin Cython to 3.1.x instead of 3.1.0 as requested + (`issue 530 `__). +#) Fixed bug when attempting to execute an empty statement + (`issue 525 `__). +#) Fixed bug when attempting to append an element to a + :ref:`DbObject ` which is not actually a collection. +#) API documentation is now generated from the source code. +#) The test suite now uses `pytest `__. +#) Internal change: the value of ``__module__`` for all classes is now left + untouched to avoid issues with ``inspect.getsource()`` but ``__repr__()`` + now consistently shows the module as ``oracledb``. +#) Internal change: `typing_extensions `__ is now a dependency. + + +oracledb `3.3.0 `__ (July 2025) +-------------------------------------------------------------------------------------------------- + +Thin Mode Changes ++++++++++++++++++ + +#) Error ``DPY-3001: session tagging is only supported in python-oracledb + thick mode`` is now raised when attempting to use session tagging with a + connection pool. Previously a ``NotImplementedError`` exception was raised + instead. +#) Fixed bug in the calculation of attribute + :attr:`MessageProperties.deliverymode`. Previously it was being set to the + value of the attribute :attr:`DeqOptions.deliverymode`. +#) Fixed bug with detection of when a connection has been closed by the + database without notification. +#) Fixed bug with execution of a PL/SQL block containing at least one output + bind variable immediately following a query that returned multiple + duplicate rows. +#) Fixed bug with connect strings containing ``SOURCE_ROUTE=YES`` where the + second host is unresolvable by the host running python-oracledb. + +Thick Mode Changes +++++++++++++++++++ + +#) Fixed regression resulting in cursor leak + (`issue 513 `__). + + +Common Changes +++++++++++++++ + +#) Pre-built binaries are now being created for Python 3.14. Note this Python + version is currently in release candidate phase. +#) Added support for Oracle Database 23.6 :ref:`Sessionless Transactions + `. +#) Changes to :ref:`data frame ` support: + + - Added support for binding data frames to :meth:`Cursor.executemany()` and + :meth:`AsyncCursor.executemany()` for fast data ingestion. See + :ref:`dfinsert`. + - Added internal support for the ArrowArrayStream PyCapsule interface to + simplify :ref:`DataFrame ` use. + - Removed use of the DataFrame Interchange Protocol in python-oracledb + :ref:`DataFrame ` objects. + - Removed the prefix "Oracle" from the data frame object names. They are + now called :ref:`DataFrame ` and :ref:`ArrowArray + `. + - Documentation on methods and attributes of the :ref:`DataFrame + ` and :ref:`ArrowArray ` objects + is now available when using IDE introspection. + - Upgraded Arrow C Data (nanoarrow) API version to 0.7.0. + - Ensured that the `Python GIL + `__ + is held when releasing references to :ref:`ArrowArray + ` objects when exported Arrow buffers are released + by the consumer. This avoids a segfault seen in some circumstances. + - Fixed bug when deciding Arrow datatype for numeric expressions. + (`issue 510 `__) + - Fixed bug when fetching numeric data that has no decimal point but the + Arrow array has scale > 0. + - Fixed bug when fetching dates that are in the year 2038 or later. + - Fixed bug when fetching numeric data with precision that exceeds 38 as + decimal data. + - Fixed bug when fetching large amounts of data in one round-trip when + using asyncio with Oracle Database 21c and earlier. + + Note the data frame support in python-oracledb 3.3 is a pre-release, and + may change in a future version. +#) Internal change: migrated build configuration completely to pyproject.toml, + which allows for optional dependencies for the test suite on the numpy, + pandas and pyarrow modules. + + +oracledb `3.2.0 `__ (June 2025) +-------------------------------------------------------------------------------------------------- + +Thin Mode Changes ++++++++++++++++++ + +#) Added support for :ref:`recipient lists ` in Oracle Advanced + Queuing. +#) Emulate support for :meth:`Queue.deqmany()` with JSON payloads when using + Oracle Database 21c by internally calling :meth:`Queue.deqone()` as many + times as needed. +#) Pooled connections that are no longer needed are now closed normally if + possible instead of simply having the socket disconnected + (`issue 393 `__). +#) Fixed bug when a connection pool internally makes an attempt to ping a + closed connection + (`issue 482 `__). +#) Fixed bug when connecting with asyncio using the parameter ``https_proxy``. +#) Fixed bug when fetching LOBs with asyncio from Oracle Database 21c and + earlier + (`issue 500 `__). +#) Fixed regression when connecting where only the host specified by the + ``https_proxy`` parameter can successfully perform name resolution. +#) Fixed bug resulting in explicit request boundaries to aid planned database + maintenance not being sent when using connection pools with asyncio. +#) Fixed bug populating :attr:`MessageProperties.deliverymode` after dequeue, + which is set using :attr:`DeqOptions.deliverymode`. +#) Fixed bug resulting in ``TypeError`` when using + :attr:`DeqOptions.correlation` for buffered delivery mode. +#) Fixed bug when fetching multiple consecutive null values into a :ref:`data + frame `. +#) Fixed bug using :ref:`Oracle Advanced Queuing ` when + attempting to dequeue using an invalid :attr:`DeqOptions.msgid`. +#) Fixed bug resulting in an exception when :meth:`Cursor.executemany()` is + called with SQL containing bind variables and an empty parameter set + (`issue 508 `__). + +Thick Mode Changes +++++++++++++++++++ + +#) Fixed a bug resulting in error ``DPI-1046: parameter value cannot be a NULL + pointer`` when the attributes :attr:`DeqOptions.condition`, + :attr:`DeqOptions.consumername`, :attr:`DeqOptions.correlation`, + :attr:`DeqOptions.msgid`, :attr:`DeqOptions.transformation`, + :attr:`EnqOptions.transformation`, :attr:`MessageProperties.correlation`, + or :attr:`MessageProperties.exceptionq` are set to *None*. +#) Fixed a bug resulting in a ``ValueError`` exception when getting attribute + :attr:`MessageProperties.enqtime` if the value is not available or + *None*. +#) Fixed a memory leak when enqueuing to JSON queues with + :ref:`Oracle Advanced Queuing `. + +Common Changes +++++++++++++++ + +#) Added Instance Principal authentication support when using + :ref:`OCI Cloud Native Authentication `. +#) Improvements to :ref:`data frame ` support: + + - Added support for VECTOR columns when fetching data frames. + - Fixed date handling to match PyArrow's and avoid localization issues + (`issue 499 `__). + - Fixed bug on Windows when fetching dates prior to 1970 and after 2038 + (`issue 483 `__). + - Added support for the NCHAR, NVARCHAR and NCLOB data types + (`issue 505 `__). + +#) Added parameter ``pool_name`` to connection and pool creation methods to + support Oracle Database 23.4 multi-pool :ref:`drcp`. +#) :ref:`GitHub Action ` workflow updates: + + - Use GitHub Arm Linux runner for builds. Supplied by wojiushixiaobai + (`PR 496 `__). + - Allow the GitHub build action to build a user-chosen subset of packages. + - Fix bug with GitHub build action merge artifacts step + (`issue 495 `__). + +#) Error ``DPY-2064: parameter 'max' should be greater than or equal to + parameter 'min'`` is now raised when a call to + :meth:`oracledb.create_pool()`, :meth:`oracledb.create_pool_async()` + or :meth:`oracledb.PoolParams()` is made with parameter ``max`` less than + the parameter ``min``. Previously python-oracledb Thin mode did not raise + an error and python-oracledb Thick mode raised the exception + ``ORA-24413: Invalid number of sessions specified``. +#) Improved the test suite and documentation. + + +oracledb `3.1.1 `__ (May 2025) +------------------------------------------------------------------------------------------------- + +Thin Mode Changes ++++++++++++++++++ + +#) Fixed bug with :meth:`Connection.is_healthy()` after a session is killed, + such as by a DBA running ALTER SYSTEM KILL SESSION. Previously, in some + databases, it could incorrectly return *True*, while in other cases it + could hang. + +Common Changes +++++++++++++++ + +#) Added support for using the Cython 3.1 release + (`issue 493 `__). +#) Improvements to data frame fetching with :meth:`Connection.fetch_df_all()` + and :meth:`Connection.fetch_df_batches()`: + + - Added support for converting an :ref:`OracleDataFrame + ` object to a foreign data frame object more than + once + (`issue 470 `__). + - Fixed a bug resulting in a segfault when attempting to use an + :ref:`output type handler ` while fetching data frames + (`issue 486 `__). + - Fixed memory corruption in data frame queries + (`issue 489 `__). + +#) Fixed parsing of the connection string in the + :ref:`Azure App Centralized Configuration Provider + `. +#) Miscellaneous grammar and spelling fixes by John Bampton + (`PR 479 `__). + + +oracledb `3.1.0 `__ (April 2025) +--------------------------------------------------------------------------------------------------- + +Thin Mode Changes ++++++++++++++++++ + +#) Added support for :ref:`scrollable cursors `. +#) Improved support for :ref:`Oracle Advanced Queuing `: + + - Added support for JSON payloads + - Added support for bulk enqueuing and dequeuing + - Added support for using AQ with asyncio + +#) Improved error message when the cryptography package cannot be imported + (`issue 455 `__). +#) Fixed decoding of nested PL/SQL records + (`issue 456 `__). +#) Fixed wildcard matching of domains in Subject Alternative Names + (`issue 462 `__). +#) Fixed bug when binding a temporary LOB IN/OUT to a PL/SQL procedure + (`issue 468 `__). +#) Fixed bug when an error is reported by the server in the middle of a + response to a client request + (`issue 472 `__). +#) Fixed bug when connecting to an AC-enabled service + (`issue 476 `__). +#) Fixed bug when using temporary LOBs with implicit pooling. +#) Fixed bug when fetching nested cursors. + +Thick Mode Changes +++++++++++++++++++ + +#) Fixed bug resulting in a segfault when unable to load the Oracle Client + libraries + (`ODPI-C `__ dependency update). +#) Fixed bug which resulted in error ``ORA-24328: illegal attribute value`` + when calling :meth:`Connection.gettype()` with Oracle Client 11.2 + libraries + (`ODPI-C `__ dependency update). +#) Improved error message when getting :attr:`Connection.max_open_cursors` + when using Oracle Client 11.2 libraries + (`ODPI-C `__ dependency update). +#) Improved error message when attempting to work with sparse vectors using + Oracle Client 23.6 (or earlier) libraries + (`ODPI-C `__ dependency update). + +Common Changes +++++++++++++++ + +#) Dropped support for Python 3.8. +#) Improvements to data frame fetching with :meth:`Connection.fetch_df_all()` + and :meth:`Connection.fetch_df_batches()`: + + - Added support for CLOB, BLOB, and RAW data types + - Fixed support for BOOLEAN data type + - Fixed bug when NUMBER data is fetched that does not have a precision or + scale specified and + :attr:`oracledb.defaults.fetch_decimals ` is set + to *True*. + - More efficient processing when a significant amount of data is duplicated + from one row to the next + - Avoid memory allocation/free cycles for decimal data + - Eliminated memory leak if OracleDataFrame is not converted to an external + data frame + - Eliminated small memory leak with production of each data frame + +#) Made the :ref:`Azure App Centralized Configuration Provider + ` connection string suffix ".azconfig.io" + optional. +#) Fixed bug when binding a variable that was previously bound as an output + variable in a DML RETURNING statement. +#) Fixed bug when multiple rows containing LOBs and DbObjects are returned in + a DML RETURNING statement. +#) An error message that links to :ref:`documentation ` on + setting up a protocol hook function is now returned by default for LDAP and + LDAPS URL connection strings in python-oracledb Thin mode, or when + :attr:`oracledb.defaults.thick_mode_dsn_passthrough + ` is *False*. +#) Error ``DPY-2062: payload cannot be enqueued since it does not match the + payload type supported by the queue`` is now raised when the payload of a + message being enqueued is not supported by the queue. Previously, + python-oracledb Thick mode raised the error ``DPI-1071: payload type in + message properties must match the payload type of the queue`` and Thin mode + raised an internal error. +#) Improved the test suite and documentation. + + +oracledb `3.0.0 `__ (March 2025) +--------------------------------------------------------------------------------------------------- Thin Mode Changes +++++++++++++++++ @@ -82,14 +502,16 @@ Thick Mode Changes ++++++++++++++++++ #) At successful completion of a call to :meth:`oracledb.init_oracle_client()`, - the value of :attr:`defaults.config_dir` may get set by python-oracledb in - some cases. For example it might be set to the configuration directory that - is relative to the loaded Oracle Client libraries. + the value of :attr:`oracledb.defaults.config_dir ` may + get set by python-oracledb in some cases. For example it might be set to + the configuration directory that is relative to the loaded Oracle Client + libraries. #) Connect string parsing and :ref:`tnsnames.ora ` file handling can be configured with the new parameter - :attr:`defaults.thick_mode_dsn_passthrough` which can be helpful for - application portability. When it is `False`, python-oracledb Thick mode - behaves similarly to Thin mode. + :attr:`oracledb.defaults.thick_mode_dsn_passthrough + ` which can be helpful for application + portability. When it is `False`, python-oracledb Thick mode behaves + similarly to Thin mode. #) Fixed bug that caused :attr:`oracledb._Error.isrecoverable` to always be `False`. @@ -131,9 +553,9 @@ Common Changes :attr:`DbObjectAttribute.scale`, and :attr:`DbObjectAttribute.max_size` that provide additional metadata about :ref:`database object attributes `. -#) The attribute :attr:`defaults.config_dir` is now set to - ``$ORACLE_HOME/network/admin`` if the environment variable ``ORACLE_HOME`` - is set and ``TNS_ADMIN`` is *not* set. +#) The attribute :attr:`oracledb.defaults.config_dir ` is + now set to ``$ORACLE_HOME/network/admin`` if the environment variable + ``ORACLE_HOME`` is set and ``TNS_ADMIN`` is *not* set. #) All connect strings are parsed by the driver if the new parameter ``thick_mode_dsn_passthrough`` is set to *True*. Previously, only Thin mode parsed all connect strings and Thick mode passed the connect string @@ -154,12 +576,13 @@ Common Changes :meth:`oracledb.connect_async()`, :meth:`oracledb.create_pool()` and :meth:`oracledb.create_pool_async()` (`issue 438 `__). -#) Fix typing issues with setters for :attr:`defaults.fetch_lobs` and - :attr:`defaults.fetch_decimals` +#) Fix typing issues with setters for + :attr:`oracledb.defaults.fetch_lobs ` and + :attr:`oracledb.defaults.fetch_decimals ` (`issue 458 `__). #) Error ``DPY-2053: python-oracledb thin mode cannot be used because thick mode has already been enabled`` is now raised when attempting to use - asyncio in thick mode + asyncio in Thick mode (`issue 448 `__). #) Error ``DPY-2056: registered handler for protocol "{protocol}" failed for arg "{arg}"`` is now raised when an exception occurs when calling the @@ -172,8 +595,8 @@ Common Changes #) Improved test suite and documentation. -oracledb 2.5.1 (December 2024) ------------------------------- +oracledb `2.5.1 `__ (December 2024) +------------------------------------------------------------------------------------------------------ Thin Mode Changes +++++++++++++++++ @@ -198,7 +621,7 @@ Thick Mode Changes #) Fixed bug calculating property :data:`Connection.max_identifier_length` when using Oracle Client libraries 12.1, or older. The returned value may - now be ``None`` when the size cannot be reliably determined by + now be *None* when the size cannot be reliably determined by python-oracledb, which occurs when using Oracle Client libraries 12.1 (or older) to connect to Oracle Database 12.2, or later. (`ODPI-C `__ dependency update). @@ -213,8 +636,8 @@ Common Changes (`issue 429 `__). -oracledb 2.5.0 (November 2024) ------------------------------- +oracledb `2.5.0 `__ (November 2024) +------------------------------------------------------------------------------------------------------ Thin Mode Changes +++++++++++++++++ @@ -223,11 +646,11 @@ Thin Mode Changes :attr:`Connection.serial_num` that provide information about the session identifier and session serial number associated with a connection. #) Added attributes - :attr:`oracledb.defaults.driver_name `, - :attr:`oracledb.defaults.machine `, - :attr:`oracledb.defaults.osuser `, - :attr:`oracledb.defaults.program `, and - :attr:`oracledb.defaults.terminal ` to set + :attr:`oracledb.defaults.driver_name `, + :attr:`oracledb.defaults.machine `, + :attr:`oracledb.defaults.osuser `, + :attr:`oracledb.defaults.program `, and + :attr:`oracledb.defaults.terminal ` to set information about the driver name, machine name, operating system user, program name, and terminal name respectively. The ``driver_name``, ``machine``, ``osuser``, ``program``, and ``terminal`` parameters were also @@ -239,7 +662,7 @@ Thin Mode Changes connection string. #) Added :meth:`oracledb.enable_thin_mode()` as a means of enabling python-oracledb Thin mode without waiting for an initial connection to be - succesfully established. Since python-oracledb defaults to Thin mode, this + successfully established. Since python-oracledb defaults to Thin mode, this method is mostly useful for applications with multiple threads concurrently creating connections to databases when the application starts (`issue 408 `__). @@ -303,7 +726,7 @@ Common Changes #) The variables saved with :meth:`Cursor.setinputsizes()` are now forgotten when an exception is raised (`issue 411 `__). -#) Fixed bug when calling :meth:`ConnectParams.set()` with a value of ``None`` +#) Fixed bug when calling :meth:`ConnectParams.set()` with a value of *None* for the ``connectiontype`` and ``session_callback`` parameters. Previously, any values set earlier would be improperly cleared and now they are retained @@ -311,8 +734,8 @@ Common Changes #) Improved test suite and documentation. -oracledb 2.4.1 (August 2024) ----------------------------- +oracledb `2.4.1 `__ (August 2024) +---------------------------------------------------------------------------------------------------- Thin Mode Changes +++++++++++++++++ @@ -322,19 +745,19 @@ Thin Mode Changes (`issue 383 `__). -oracledb 2.4.0 (August 2024) ----------------------------- +oracledb `2.4.0 `__ (August 2024) +---------------------------------------------------------------------------------------------------- Thin Mode Changes +++++++++++++++++ -#) Added support for Oracle Database 23ai :ref:`statement pipelining +#) Added support for Oracle Database 23.4 :ref:`statement pipelining `. #) Fixed bug resulting in a segfault when a closed cursor is bound as a REF CURSOR (`issue 368 `__). -#) Fixed bug resulting in an inability to connect to Oracle Database 23ai - instances which have fast authentication disabled. +#) Fixed bug resulting in an inability to connect to Oracle Database version + 23 instances which have fast authentication disabled. #) Fixed error message when idle time is exceeded by a connection. The error ``DPY-4033: the database closed the connection because the connection's idle time has been exceeded`` is now raised when this situation is @@ -374,12 +797,12 @@ Common Changes different connection. Previously, the attempt may have succeeded or may have failed with a number of different unexpected exceptions. #) Error ``DPY-1006: cursor is not open`` is now raised consistently when - attempting to bind a closed cursor. Previously, thin mode would result in a - segfault and thick mode would result in unusual errors. + attempting to bind a closed cursor. Previously, Thin mode would result in a + segfault and Thick mode would result in unusual errors. -oracledb 2.3.0 (July 2024) --------------------------- +oracledb `2.3.0 `__ (July 2024) +-------------------------------------------------------------------------------------------------- Thin Mode Changes +++++++++++++++++ @@ -410,7 +833,7 @@ Thick Mode Changes Common Changes ++++++++++++++ -#) Added support for Oracle Database 23ai +#) Added support for Oracle Database 23.5 :ref:`BINARY vector format `. #) Replaced integer constants for :ref:`connection authorization modes `, @@ -462,7 +885,7 @@ Common Changes :data:`oracledb.POOL_GETMODE_TIMEDWAIT` and the timeout expires. Previously ``asyncio.TimeoutError`` was being raised when using :ref:`asyncio ` and ``ORA-24457: OCISessionGet() could not find a - free session in the specified timeout period`` was being raised in thick + free session in the specified timeout period`` was being raised in Thick mode. #) If both the ``sid`` and ``service_name`` parameters are specified to :meth:`oracledb.makedsn()`, now only the ``service_name`` parameter is @@ -474,8 +897,8 @@ Common Changes #) Internal changes to ensure that no circular imports occur. -oracledb 2.2.1 (May 2024) -------------------------- +oracledb `2.2.1 `__ (May 2024) +------------------------------------------------------------------------------------------------- Thin Mode Changes +++++++++++++++++ @@ -496,8 +919,8 @@ Thin Mode Changes potential hangs in some configurations under some circumstances. -oracledb 2.2.0 (May 2024) -------------------------- +oracledb `2.2.0 `__ (May 2024) +------------------------------------------------------------------------------------------------- Thin Mode Changes +++++++++++++++++ @@ -511,12 +934,12 @@ Thin Mode Changes #) Fixed bug that would cause an internal error to be raised when attempting to close a connection that has been forcibly closed by the database. #) Internal change: further efforts to tighten code looking for the end of a - database request made to Oracle Database 23ai. + database request made to Oracle Database version 23. Common Changes ++++++++++++++ -#) Added support for Oracle Database 23ai columns of type :ref:`VECTOR +#) Added support for Oracle Database 23.4 columns of type :ref:`VECTOR `. #) Added support for columns of type INTERVAL YEAR TO MONTH which can be represented in Python by instances of the new @@ -538,8 +961,8 @@ Common Changes ``DPY-4030: invalid DRCP pool boundary {boundary}``. -oracledb 2.1.2 (April 2024) ---------------------------- +oracledb `2.1.2 `__ (April 2024) +--------------------------------------------------------------------------------------------------- Thin Mode Changes +++++++++++++++++ @@ -556,8 +979,8 @@ Common Changes containing the ``/`` character. -oracledb 2.1.1 (March 2024) ---------------------------- +oracledb `2.1.1 `__ (March 2024) +--------------------------------------------------------------------------------------------------- Thin Mode Changes +++++++++++++++++ @@ -579,13 +1002,13 @@ Thin Mode Changes losing output due to buffering when multiple threads are running. -oracledb 2.1.0 (March 2024) ---------------------------- +oracledb `2.1.0 `__ (March 2024) +--------------------------------------------------------------------------------------------------- Thin Mode Changes +++++++++++++++++ -#) Oracle Database 23ai feature support: +#) Oracle Database version 23 feature support: - Added support for :ref:`implicit connection pooling with DRCP and PRCP `, @@ -633,8 +1056,8 @@ Thin Mode Changes Thick Mode Changes ++++++++++++++++++ -#) Added support for internal use of JSON in SODA with Oracle Client 23. This - allows for seamless transfer of extended data types. +#) Added support for internal use of JSON in SODA with Oracle Client version + 23. This allows for seamless transfer of extended data types. #) Fixed bug when calling :meth:`SodaDoc.getContent()` for SODA documents that do not contain JSON. #) Corrected support for Oracle Sharding. @@ -654,7 +1077,7 @@ Common Changes returned by SODA in Oracle Database 23.4 and later in the ``_id`` attribute of documents stored in native collections. #) Added support for columns of type VECTOR usable with a limited - availability release of Oracle Database 23. + availability release of Oracle Database version 23. #) Errors raised when calling :meth:`Cursor.executemany()` with PL/SQL now have the :data:`oracledb._Error.offset` attribute populated with the last iteration that succeeded @@ -668,12 +1091,12 @@ Common Changes #) Error ``DPY-2016: variable array size of %d is too small (should be at least %d)`` is now raised when :meth:`Cursor.executemany()` is called with an integer number of iterations that is too large for the existing bind - variables. Previously, the python-oracledb Thin mode raised ``IndexError`` + variables. Previously, python-oracledb Thin mode raised ``IndexError`` and python-oracledb Thick mode raised ``DPI-1018: array size of %d is too small``. #) Error ``DPY-1001: not connected to database`` is now raised when an attempt is made to perform an operation on a LOB using a closed connection. - Previously, the python-oracledb Thin mode raised an ``AttributeError`` + Previously, python-oracledb Thin mode raised an ``AttributeError`` exception and python-oracledb Thick mode raised ``DPI-1040: LOB was already closed``. #) Fixed bug in :meth:`ConnectParams.get_connect_string()` when a value for @@ -689,11 +1112,11 @@ Common Changes #) Fixed bug in the calculation of :data:`Cursor.rowcount` under some circumstances. #) Connection parameters that are strings now treat an empty string in the - same way as the value ``None``. + same way as the value *None*. -oracledb 2.0.1 (January 2024) ------------------------------ +oracledb `2.0.1 `__ (January 2024) +----------------------------------------------------------------------------------------------------- Thin Mode Changes +++++++++++++++++ @@ -734,8 +1157,8 @@ Common Changes #) Bumped minimum requirement of Cython to 3.0. -oracledb 2.0.0 (December 2023) ------------------------------- +oracledb `2.0.0 `__ (December 2023) +------------------------------------------------------------------------------------------------------ Thin Mode Changes +++++++++++++++++ @@ -749,8 +1172,8 @@ Thin Mode Changes #) Added parameter :data:`ConnectParams.ssl_context` to modify the SSL context used when connecting via TLS (`issue 259 `__). -#) Added support for an Oracle Database 23ai JSON feature allowing field names - with more than 255 UTF-8 encoded bytes. +#) Added support for an Oracle Database version 23 JSON feature allowing + fieldnames with more than 255 UTF-8 encoded bytes. #) Added support for the ``FAILOVER`` clause in full connect descriptors. #) Fixed bug in detecting the current time zone (`issue 257 `__). @@ -760,8 +1183,8 @@ Thin Mode Changes multiple line comments with multiple asterisks before the closing slash. #) A more meaningful error is raised when the wrong type of data is passed to :meth:`LOB.write()`. -#) Internal change to support an Oracle Database 23ai JSON feature improving - JSON storage usage. +#) Internal change to support an Oracle Database version 23 JSON feature + improving JSON storage usage. #) Internal change to ensure that all connections in a pool have been closed gracefully before the pool is closed. #) Internal changes to improve handling of the network protocol between @@ -794,14 +1217,13 @@ Common Changes `__). #) Added properties :data:`FetchInfo.domain_schema`, :data:`FetchInfo.domain_name` and :data:`FetchInfo.annotations` for the - `SQL domain `__ - and `annotations `__ - associated with columns that are being fetched. SQL domains and annotations - require Oracle Database 23ai. If using python-oracledb Thick mode, Oracle - Client 23ai is also required. + `SQL domain `__ and `annotations + `__ associated with columns that are being + fetched. SQL domains and annotations require Oracle Database version 23, + or later. If using python-oracledb Thick mode, Oracle Client version 23, + or later, is also required. #) Added parameter ``data`` to :meth:`Connection.createlob()` to allow data to be written at LOB creation time. #) Added type :data:`~oracledb.DB_TYPE_XMLTYPE` to represent data of type @@ -821,22 +1243,22 @@ Common Changes #) Errors that have entries in the :ref:`troubleshooting documentation ` now have links to that documentation shown in the message text. -#) Fixed bug with binding boolean values with Oracle Database 23ai +#) Fixed bug with binding boolean values with Oracle Database version 23 (`issue 263 `__). #) Fixed bug with getting unknown attributes from :ref:`Oracle Object ` instances. #) Error ``DPY-4029: errors in array DML exceed 65535`` is now raised when the number of batch errors exceeds 65535 when calling :meth:`Cursor.executemany()` with the parameter ``batcherrors`` set to the - value ``True``. Note that in thick mode this error is not raised unless the + value *True*. Note that in Thick mode this error is not raised unless the number of batch errors is a multiple of 65536; instead, the number of batch errors returned is modulo 65536 (`issue 262 `__). #) Black is now used to format Python code and ruff to lint Python code. -oracledb 1.4.2 (October 2023) ------------------------------ +oracledb `1.4.2 `__ (October 2023) +----------------------------------------------------------------------------------------------------- Thick Changes +++++++++++++ @@ -851,8 +1273,8 @@ Common Changes (`issue 237 `__). -oracledb 1.4.1 (September 2023) -------------------------------- +oracledb `1.4.1 `__ (September 2023) +------------------------------------------------------------------------------------------------------- Thin Mode Changes +++++++++++++++++ @@ -875,25 +1297,25 @@ Common Changes #) Fixed bug when calling :meth:`Cursor.execute()` or :meth:`Cursor.executemany()` with missing bind data after calling :meth:`Cursor.setinputsizes()` with at least one of the values supplied as - ``None`` + *None* (`issue 217 `__). #) SQL statement parsing now raises ``DPY-2041: missing ending quote (') in string`` or ``DPY-2042: missing ending quote (") in identifier`` for - statements with the noted invalid syntax. Previously, thick mode gave - ``ORA-1756`` or ``ORA-1740``, respectively, while thin mode did not throw + statements with the noted invalid syntax. Previously, Thick mode gave + ``ORA-1756`` or ``ORA-1740``, respectively, while Thin mode did not throw an error. #) Added missing ">" to ``repr()`` of :ref:`sodadb`. -oracledb 1.4.0 (August 2023) ----------------------------- +oracledb `1.4.0 `__ (August 2023) +---------------------------------------------------------------------------------------------------- Thin Mode Changes +++++++++++++++++ -#) Added support for an Oracle Database 23ai feature that can improve the - performance of connection creation by reducing the number of round trips - required to create the second and subsequent connections to the same +#) Added support for an Oracle Database version 23 feature that can improve + the performance of connection creation by reducing the number of round + trips required to create the second and subsequent connections to the same database. #) Added support for shrinking the connection pool back to the specified minimum size when the pool is idle for :data:`ConnectionPool.timeout` @@ -905,13 +1327,13 @@ Thin Mode Changes created. The default connection class will be of the form ``DPY:`` followed by a 16-byte unique identifier converted to base64 encoding. #) Changed internal connection feature negotiation for more accurate Oracle - Database 23ai support. + Database version 23 support. #) Added support for sending a generated connection identifier to the database used for tracing. An application specific prefix is prepended to this value if specified via a new ``connection_id_prefix`` parameter when creating standalone connections or connection pools. #) Added URL to the Oracle Database Error Help Portal in Oracle Database - error messages similar to when Thick mode uses Oracle Client 23ai. + error messages similar to when Thick mode uses Oracle Client version 23. #) Added support for the ``ORA_SDTZ`` environment variable used to set the session time zone used by the database. #) Fixed bug when a dynamically sized connection pool is created with an @@ -942,12 +1364,13 @@ Thick Mode Changes :meth:`~SodaOperation.lock()` was added which requires Oracle Client 21.3 or higher (or Oracle Client 19 from 19.11). #) Relaxed restriction for end-to-end tracing string connection - attributes. These values can now be set to the value ``None`` which will be + attributes. These values can now be set to the value *None* which will be treated the same as an empty string. #) Fixed bug when using external authentication with an Easy Connect connection string. #) Fixed memory leak when accessing objects embedded within other objects. + Common Changes ++++++++++++++ @@ -975,7 +1398,7 @@ Common Changes #) Added support for fetching VARCHAR2 and LOB columns which contain JSON (and have the "IS JSON" check constraint enabled) in the same way as columns of type JSON (which requires Oracle Database 21c or higher) are fetched. In - thick mode this requires Oracle Client 19c or higher. The attribute + Thick mode this requires Oracle Client 19c or higher. The attribute ``oracledb.__future__.old_json_col_as_obj`` must be set to the value ``True`` for this behavior to occur. In version 2.0 this will become the normal behavior and setting this attribute will no longer be needed. @@ -984,8 +1407,8 @@ Common Changes same value as the SQL expression ``sys_context('userenv', 'instance_name')``. #) Added support for relational queries on the underlying tables of SODA - collections created in Oracle Database 23ai if they contain JSON documents - with embedded OIDs. + collections created in Oracle Database version 23 if they contain JSON + documents with embedded OIDs. #) Automatically retry a query if the error ``ORA-00932: inconsistent data types`` is raised (which can occur if a table or view is recreated with a data type that is incompatible with the column's previous data type). @@ -998,8 +1421,8 @@ Common Changes (`issue 204 `__). #) Improved test suite and documentation. -oracledb 1.3.2 (June 2023) --------------------------- +oracledb `1.3.2 `__ (June 2023) +-------------------------------------------------------------------------------------------------- Thin Mode Changes +++++++++++++++++ @@ -1016,7 +1439,7 @@ Thin Mode Changes #) Fixed bug which could cause a redirect loop with improperly configured listener redirects. #) Fixed bug when executing PL/SQL with a large number of binds. -#) Fixed bug when using DRCP with Oracle Database 23ai. +#) Fixed bug when using DRCP with Oracle Database version 23 Thick Mode Changes ++++++++++++++++++ @@ -1036,17 +1459,17 @@ Common Changes consistency between Thin and Thick modes. -oracledb 1.3.1 (April 2023) ---------------------------- +oracledb `1.3.1 `__ (April 2023) +--------------------------------------------------------------------------------------------------- Thin Mode Changes +++++++++++++++++ #) Improved performance of regular expressions used for parsing SQL (`issue 172 `__). -#) Fixed bug with Oracle Database 23ai when SQL is executed after first being - parsed. -#) Fixed bug when :data:`ConnectionPool.timeout` is not `None` when creating a +#) Fixed bug with Oracle Database version 23 when SQL is executed after first + being parsed. +#) Fixed bug when :data:`ConnectionPool.timeout` is not *None* when creating a connection pool (`issue 166 `__). #) Fixed bug when a query is re-executed after an underlying table is dropped @@ -1061,8 +1484,8 @@ Common Changes #) Improved test suite and samples. -oracledb 1.3.0 (March 2023) ---------------------------- +oracledb `1.3.0 `__ (March 2023) +--------------------------------------------------------------------------------------------------- Thin Mode Changes +++++++++++++++++ @@ -1078,7 +1501,7 @@ Thin Mode Changes #) Added support for connecting to databases that accept passwords longer than 30 UTF-8 encoded bytes. #) Detect the time zone on the OS and set the session timezone using this - value to be consistent with thick mode + value to be consistent with Thick mode (`issue 144 `__). #) Improved BOOLEAN handling. #) Error ``DPY-6005: cannot connect to database`` is now raised for all @@ -1120,7 +1543,7 @@ Thin Mode Changes of times any session callback must be invoked, and allow connections to be timed out. - Removed packet for negotiating network services which are not supported - in thin mode. + in Thin mode. - Removed unneeded packet for changing the password of the connected user. @@ -1145,29 +1568,29 @@ Common Changes #) Added method :meth:`ConnectParams.parse_dsn_with_credentials()` for parsing a DSN that contains credentials. #) Error ``DPY-2038: element at index {index} does not exist`` is now raised - whenever an element in a database collection is missing. Previously, thick - mode raised ``DPI-1024: element at index {index} does not exist`` and thin + whenever an element in a database collection is missing. Previously, Thick + mode raised ``DPI-1024: element at index {index} does not exist`` and Thin mode raised ``KeyError`` or ``IndexError``. #) Error ``DPY-2039: given index {index} must be in the range of {min_index} to {max_index}`` is now raised whenever an element in a database collection - is set outside the bounds of the collection. Previously, thick mode raised + is set outside the bounds of the collection. Previously, Thick mode raised ``OCI-22165: given index [{index}] must be in the range of [{min_index}] to - [{max_index}]`` and thin mode raised ``IndexError``. + [{max_index}]`` and Thin mode raised ``IndexError``. #) Error ``DPY-2040: parameters "batcherrors" and "arraydmlrowcounts" may only be true when used with insert, update, delete and merge statements`` is now - raised when either of the parameters `batcherrors` and `arraydmlrowcounts` - is set to the value `True` when calling :meth:`Cursor.executemany()`. - Previously, thick mode raised ``DPI-1063: modes DPI_MODE_EXEC_BATCH_ERRORS - and DPI_MODE_EXEC_ARRAY_DML_ROWCOUNTS can only be used with insert, update, - delete and merge statements`` and thin mode raised - ``ORA-03137: malformed TTC packet from client rejected`` + raised when either of the parameters ``batcherrors`` and + ``arraydmlrowcounts`` is set to the value `True` when calling + :meth:`Cursor.executemany()`. Previously, Thick mode raised ``DPI-1063: + modes DPI_MODE_EXEC_BATCH_ERRORS and DPI_MODE_EXEC_ARRAY_DML_ROWCOUNTS can + only be used with insert, update, delete and merge statements`` and Thin + mode raised ``ORA-03137: malformed TTC packet from client rejected`` (`issue 128 `__). #) Internal changes to ensure that errors taking place while raising exceptions are handled more gracefully. -oracledb 1.2.2 (January 2023) ------------------------------ +oracledb `1.2.2 `__ (January 2023) +----------------------------------------------------------------------------------------------------- Thin Mode Changes +++++++++++++++++ @@ -1197,8 +1620,8 @@ Common Changes elements. -oracledb 1.2.1 (December 2022) ------------------------------- +oracledb `1.2.1 `__ (December 2022) +------------------------------------------------------------------------------------------------------ Thin Mode Changes +++++++++++++++++ @@ -1219,7 +1642,7 @@ Thick Mode Changes allowing it to be closed automatically when it goes out of scope). #) Fixed bug when calling :meth:`Subscription.registerquery()` with bind values. -#) Fixed bug that caused :data:`Message.dbname` to always be the value `None`. +#) Fixed bug that caused :data:`Message.dbname` to always be the value *None*. Common Changes ++++++++++++++ @@ -1228,8 +1651,8 @@ Common Changes instead of a hard-coded ``oracledb``. -oracledb 1.2.0 (November 2022) ------------------------------- +oracledb `1.2.0 `__ (November 2022) +------------------------------------------------------------------------------------------------------ Thin Mode Changes +++++++++++++++++ @@ -1275,13 +1698,13 @@ Common Changes #) Added support for Python 3.11. #) Added attribute :attr:`DbObjectType.package_name` which contains the name - of the package if the type is a PL/SQL type (otherwise, it will be `None`). + of the package if the type is a PL/SQL type (otherwise, it will be *None*). #) Added sample for loading data from a CSV file. #) Improved test suite and documentation. -oracledb 1.1.1 (September 2022) -------------------------------- +oracledb `1.1.1 `__ (September 2022) +------------------------------------------------------------------------------------------------------- Thin Mode Changes +++++++++++++++++ @@ -1314,15 +1737,15 @@ Common Changes #) Improved test suite and documentation. -oracledb 1.1.0 (September 2022) -------------------------------- +oracledb `1.1.0 `__ (September 2022) +------------------------------------------------------------------------------------------------------- Thin Mode Changes +++++++++++++++++ #) Added support for getting the LOB chunk size (`issue 14 `__). -#) The error `DPY-2030: LOB offset must be greater than zero` is now raised +#) The error ``DPY-2030: LOB offset must be greater than zero`` is now raised when the offset parameter to :func:`LOB.read()` is zero or negative (`issue 13 `__). #) Internally, before a connection is returned from a pool, check for control @@ -1337,8 +1760,8 @@ Thin Mode Changes when connecting to a database that the listener configuration file states exists but actually doesn't (`issue 51 `__). -#) The error `DPY-3016: python-oracledb thin mode cannot be used because the - cryptography package is not installed` is now raised when the cryptography +#) The error ``DPY-3016: python-oracledb thin mode cannot be used because the + cryptography package is not installed`` is now raised when the cryptography package is not installed, instead of an ImportError. This allows platforms that are not capable of building the cryptography package to still use Thick mode. @@ -1368,21 +1791,22 @@ Common Changes #) Improved samples and documentation. -oracledb 1.0.3 (August 2022) ----------------------------- +oracledb `1.0.3 `__ (August 2022) +---------------------------------------------------------------------------------------------------- Thin Mode Changes +++++++++++++++++ -#) The error `DPY-3015: password verifier type is not supported by - python-oracledb in thin mode` is now raised when +#) The error ``DPY-3015: password verifier type is not supported by + python-oracledb in thin mode`` is now raised when the database sends a password challenge with a verifier type that is not recognized, instead of `ORA-01017: invalid username/password` (`issue 26 `__). #) Fixed bug with handling of redirect data returned by some SCAN listeners (`issue 39 `__). #) Fixed bug with re-execution of SQL that requires a define, such as occurs - when setting `oracledb.defaults.fetch_lobs` to the value `False` + when setting :attr:`oracledb.defaults.fetch_lobs ` to + the value `False` (`issue 41 `__). #) Fixed bug that prevented cursors from implicit results sets from being closed. @@ -1395,8 +1819,8 @@ Common Changes (`issue 35 `__). -oracledb 1.0.2 (July 2022) --------------------------- +oracledb `1.0.2 `__ (July 2022) +-------------------------------------------------------------------------------------------------- Thin Mode Changes +++++++++++++++++ @@ -1430,8 +1854,8 @@ Common Changes #) Improved samples and documentation. -oracledb 1.0.1 (June 2022) --------------------------- +oracledb `1.0.1 `__ (June 2022) +-------------------------------------------------------------------------------------------------- Thin Mode Changes +++++++++++++++++ @@ -1441,7 +1865,7 @@ Thin Mode Changes #) Fixed connection retry count handling to work in cases where the database listener is running but the service is down (`issue 3 `__). -#) Return the same value for TIMESTAMP WITH TIME ZONE columns as thick mode +#) Return the same value for TIMESTAMP WITH TIME ZONE columns as Thick mode (`issue 7 `__). #) Fixed order in which bind data is sent to the server when LONG and non-LONG column data is interspersed @@ -1477,16 +1901,16 @@ Common Changes oracledb 1.0.0 (May 2022) ------------------------- -#) Renamed cx_Oracle to python-oracledb. See :ref:`upgradecomparison`. +#) Renamed cx_Oracle to python-oracledb. See :ref:`upgrading83`. #) Python-oracledb is a 'Thin' driver by default that connects directly to Oracle Database. Optional use of Oracle Client libraries enables a :ref:`'Thick' mode ` with some additional functionality. Both modes support the Python Database API v2.0 Specification. #) Added a :attr:`Connection.thin` attribute which shows whether the - connection was established in the python-oracledb Thin mode or Thick mode. -#) Creating connections or connection pools now requires :ref:`keyword - parameters ` be passed. This brings python-oracledb into - compliance with the Python Database API specification PEP 249. + connection was established in python-oracledb Thin mode or Thick mode. +#) Creating connections or connection pools now requires keyword parameters be + passed. This brings python-oracledb into compliance with the Python + Database API specification PEP 249. #) Threaded mode is now always enabled for standalone connections (Thick mode). #) The function :func:`oracledb.init_oracle_client()` must now always be @@ -1608,15 +2032,15 @@ cx_Oracle 8.2 (May 2021) Initial work was done in `PR 549 `__. #) Enhanced dead connection detection. If an Oracle Database error indicates - that a connection is no longer usable, the error `DPI-1080: connection was - closed by ORA-%d` is now returned. The `%d` will be the Oracle error + that a connection is no longer usable, the error ``DPI-1080: connection was + closed by ORA-%d`` is now returned. The `%d` will be the Oracle error causing the connection to be closed. Using the connection after this will - give `DPI-1010: not connected`. This behavior also applies for + give ``DPI-1010: not connected``. This behavior also applies for :data:`Connection.call_timeout` errors that result in an unusable connection. #) Eliminated a memory leak when calling :meth:`SodaOperation.filter()` with a dictionary. -#) The distributed transaction handle assosciated with the connection is now +#) The distributed transaction handle associated with the connection is now cleared on commit or rollback (`issue 530 `__). #) Added a check to ensure that when setting variables or object attributes, @@ -1692,7 +2116,7 @@ cx_Oracle 8.0 (June 2020) API. - The variable attribute :data:`~Variable.type` now refers to one of the new database type constants if the variable does not contain objects - (previously it was None in that case). + (previously it was *None* in that case). - The attribute :data:`~LOB.type` was added to LOB values. - The attribute ``type`` was added to attributes of object types. - The attribute ``element_type`` was added to object types. @@ -1755,7 +2179,7 @@ cx_Oracle 7.3 (December 2019) to the database (as opposed to the default server initiated connections) created by calling :meth:`Connection.subscribe()`. #) Added :attr:`support ` for returning the rowid of the - last row modified by an operation on a cursor (or None if no row was + last row modified by an operation on a cursor (or *None* if no row was modified). #) Added support for setting the ``maxSessionsPerShard`` attribute when creating connection pools. @@ -1789,7 +2213,7 @@ cx_Oracle 7.3 (December 2019) ``DPI-1012: proxy authentication is not possible with homogeneous pools`` instead of a ``ProgrammingError`` exception with the message ``pool is homogeneous. Proxy authentication is not possible.`` since this - check is done by ODPI-C. An empty string (or None) for the user name will + check is done by ODPI-C. An empty string (or *None*) for the user name will no longer generate an exception. #) Exception ``InterfaceError: not connected`` is now always raised when an operation is attempted with a closed connection. Previously, a number of @@ -1977,7 +2401,7 @@ cx_Oracle 7.1 (February 2019) Note that this support is limited to the size of VARCHAR2 columns in the database (either 4000 or 32767 bytes). #) Added support for allowing the typename parameter in method - :meth:`Cursor.var()` to be None or a valid object type created by the + :meth:`Cursor.var()` to be *None* or a valid object type created by the method :meth:`Connection.gettype()`, as requested (`issue 231 `__). #) Added support for getting and setting attributes of type RAW on Oracle @@ -1995,8 +2419,8 @@ cx_Oracle 7.1 (February 2019) decimal value is automatically returned instead. #) Corrected handling of multiple calls to method :meth:`Cursor.executemany()` where all of the values in one of the columns - passed to the first call are all None and a subsequent call has a value - other than None in the same column + passed to the first call are all *None* and a subsequent call has a value + other than *None* in the same column (`issue 236 `__). #) Added additional check for calling :meth:`Cursor.setinputsizes()` with an empty dictionary in order to avoid the error "cx_Oracle.ProgrammingError: @@ -2093,8 +2517,8 @@ cx_Oracle 6.4.1 (July 2018) Oracle number format (`ODPI-C issue 67 `__). -#) Prevent error "cx_Oracle.ProgrammingError: positional and named binds - cannot be intermixed" when calling cursor.setinputsizes() without any +#) Prevent error ``cx_Oracle.ProgrammingError: positional and named binds + cannot be intermixed`` when calling cursor.setinputsizes() without any parameters and then calling cursor.execute() with named bind parameters (`issue 199 `__). @@ -2137,7 +2561,7 @@ cx_Oracle 6.4 (July 2018) (`issue 193 `__). - If the statement should be deleted from the statement cache, first check to see that there is a statement cache currently being used; otherwise, - the error "ORA-24300: bad value for mode" will be raised under certain + the error ``ORA-24300: bad value for mode`` will be raised under certain conditions. #) Added support for using the cursor as a context manager @@ -2194,8 +2618,8 @@ cx_Oracle 6.3 (April 2018) - Fixed binding of LONG data (values exceeding 32KB) when using the function :meth:`Cursor.executemany()`. - Added code to verify that a CQN subscription is open before permitting it - to be used. Error "DPI-1060: subscription was already closed" will now be - raised if an attempt is made to use a subscription that was closed + to be used. Error ``DPI-1060: subscription was already closed`` will now + be raised if an attempt is made to use a subscription that was closed earlier. - Stopped attempting to unregister a CQN subscription before it was completely registered. This prevents errors encountered during @@ -2261,8 +2685,8 @@ cx_Oracle 6.2 (March 2018) `__. - - eliminate error "DPI-1054: connection cannot be closed when open - statements or LOBs exist" (`issue 138 + - eliminate error ``DPI-1054: connection cannot be closed when open + statements or LOBs exist`` (`issue 138 `__). - avoid a round trip to the database when a connection is released back to the pool by preventing a rollback from being called when no transaction @@ -2379,7 +2803,7 @@ cx_Oracle 6.0.3 (November 2017) - Prevent use of uninitialized data in certain cases (`issue 77 `__). - Attempting to ping a database earlier than 10g results in error - "ORA-1010: invalid OCI operation", but that implies a response from the + ``ORA-1010: invalid OCI operation``, but that implies a response from the database and therefore a successful ping, so treat it that way! - Correct handling of conversion of some numbers to NATIVE_FLOAT. - Prevent use of NaN with Oracle numbers since it produces corrupt data @@ -2452,17 +2876,17 @@ cx_Oracle 6.0 (August 2017) #version-2-0-august-14-2017>`__. - Prevent closing the connection when there are any open statements or - LOBs and add new error "DPI-1054: connection cannot be closed when open - statements or LOBs exist" when this situation is detected; this is - needed to prevent crashes under certain conditions when statements or - LOBs are being acted upon while at the same time (in another thread) a - connection is being closed; it also prevents leaks of statements and + LOBs and add new error ``DPI-1054: connection cannot be closed when + open statements or LOBs exist`` when this situation is detected; this + is needed to prevent crashes under certain conditions when statements + or LOBs are being acted upon while at the same time (in another thread) + a connection is being closed; it also prevents leaks of statements and LOBs when a connection is returned to a session pool. - On platforms other than Windows, if the regular method for loading the Oracle Client libraries fails, try using $ORACLE_HOME/lib/libclntsh.so (`ODPI-C issue 20 `__). - - Use the environment variable ``DPI_DEBUG_LEVEL`` at runtime, not compile - time. + - Use the environment variable ``DPI_DEBUG_LEVEL`` at runtime, not + compile time. - Added support for DPI_DEBUG_LEVEL_ERRORS (reports errors and has the value 8) and DPI_DEBUG_LEVEL_SQL (reports prepared SQL statement text and has the value 16) in order to further improve the ability to debug @@ -2471,9 +2895,9 @@ cx_Oracle 6.0 (August 2017) #) Delay initialization of the ODPI-C library until the first standalone connection or session pool is created so that manipulation of the - environment variable ``NLS_LANG`` can be performed after the module has been - imported; this also has the added benefit of reducing the number of errors - that can take place when the module is imported. + environment variable ``NLS_LANG`` can be performed after the module has + been imported; this also has the added benefit of reducing the number of + errors that can take place when the module is imported. #) Prevent binding of null values from generating the exception "ORA-24816: Expanded non LONG bind data supplied after actual LONG or LOB column" in certain circumstances @@ -2591,12 +3015,8 @@ cx_Oracle 6.0 beta 1 (April 2017) to the ``SessionPool.release`` method in order to support session tagging. #) Added parameter edition to the ``cx_Oracle.SessionPool()`` method. -#) Added support for - `universal rowids `__. -#) Added support for `DML Returning of multiple rows - `__. +#) Added support for universal rowids. +#) Added support for DML Returning of multiple rows. #) Added attributes :attr:`Variable.actualElements` and :attr:`Variable.values` to variables. #) Added parameters region, sharding_key and super_sharding_key to the @@ -2605,7 +3025,7 @@ cx_Oracle 6.0 beta 1 (April 2017) #) Added support for smallint and float data types in Oracle objects, as `requested `__. #) An exception is no longer raised when a collection is empty for methods - :meth:`Object.first()` and :meth:`Object.last()`. Instead, the value None + :meth:`Object.first()` and :meth:`Object.last()`. Instead, the value *None* is returned to be consistent with the methods :meth:`Object.next()` and :meth:`Object.prev()`. #) If the environment variables NLS_LANG and NLS_NCHAR are being used, they @@ -2624,20 +3044,14 @@ cx_Oracle 6.0 beta 1 (April 2017) to the application. #) Dropped deprecated parameters action, module and clientinfo from the ``cx_Oracle.connect()`` method. The appcontext parameter should be used - instead as shown in this `sample `__. + instead. #) Dropped deprecated attribute numbersAsString from - :ref:`cursor objects `. Use an output type handler instead as - shown in this `sample `__. + :ref:`cursor objects `. Use an output type handler instead. #) Dropped deprecated attributes cqqos and rowids from - :ref:`subscription objects `. Use the qos attribute instead as - shown in this `sample `__. + :ref:`subscription objects `. Use the qos attribute instead. #) Dropped deprecated parameters cqqos and rowids from the :meth:`Connection.subscribe()` method. Use the qos parameter instead as - shown in this `sample `__. + shown in the cx_Oracle sample cqn.py. cx_Oracle 5.3 (March 2017) @@ -2669,7 +3083,7 @@ cx_Oracle 5.3 (March 2017) :meth:`creating a connection ` and added support for setting these when creating a session pool. These can now be used instead of setting the environment variables ``NLS_LANG`` and ``NLS_NCHAR``. -#) Use None instead of 0 for items in the :attr:`Cursor.description` attribute +#) Use *None* instead of *0* for items in the :attr:`Cursor.description` attribute that do not have any validity. #) Changed driver name to match informal driver name standard used by Oracle for other drivers. @@ -2680,9 +3094,9 @@ cx_Oracle 5.3 (March 2017) versions of the gcc compiler for Cygwin. #) Simplified test suite by combining Python 2 and 3 scripts into one script and separated out 12.1 features into a single script. -#) Updated samples to use code that works on both Python 2 and 3 +#) Updated samples to use code that works on both Python 2 and 3. #) Added support for pickling/unpickling error objects - (`Issue #23 `__) + (Bitbucket Issue #23). #) Dropped support for callbacks on OCI functions. #) Removed deprecated types UNICODE, FIXED_UNICODE and LONG_UNICODE (use NCHAR, FIXED_NCHAR and LONG_NCHAR instead). @@ -2758,10 +3172,10 @@ cx_Oracle 5.2 (June 2015) #) Removed remaining remnants of support Oracle 9i. #) Added __version__ attribute to conform with PEP 396. #) Ensure that sessions are released to the pool when calling - connection.close() - (`Issue #2 `__) + connection.close(). + (Bitbucket Issue #2). #) Fixed handling of datetime intervals - (`Issue #7 `__) + (Bitbucket Issue #7). cx_Oracle 5.1.3 (May 2014) @@ -3276,13 +3690,13 @@ cx_Oracle 4.1 beta 1 (September 2004) #) The cursor method arrayvar() will now accept the actual list so that it is not necessary to call cursor.arrayvar() followed immediately by var.setvalue(). -#) Fixed bug where attempts to execute the statement "None" with bind +#) Fixed bug where attempts to execute the statement *None* with bind variables would cause a segmentation fault. #) Added support for binding by position (paramstyle = "numeric"). #) Removed memory leak created by calls to OCIParamGet() which were not mirrored by calls to OCIDescriptorFree(). Thanks to Mihai Ibanescu for pointing this out and providing a patch. -#) Added support for calling cursor.executemany() with statement None +#) Added support for calling cursor.executemany() with statement *None* implying that the previously prepared statement ought to be executed. Thanks to Mihai Ibanescu for providing a patch. #) Added support for rebinding variables when a subsequent call to @@ -3400,18 +3814,18 @@ cx_Oracle 3.1 (August 2003) cx_Oracle 3.0a (June 2003) -------------------------- -#) Fixed bug where zero length PL/SQL arrays were being mishandled +#) Fixed bug where zero length PL/SQL arrays were being mishandled. #) Fixed support for the data type "float" in Oracle; added one to the display size to allow for the sign of the number, if necessary; changed the display size of unconstrained numbers to 127, which is the largest - number that Oracle can handle + number that Oracle can handle. #) Added support for retrieving the description of a bound cursor before - fetching it -#) Fixed a couple of build issues on Mac OS X, AIX and Solaris (64-bit) -#) Modified documentation slightly based on comments from several people -#) Included files in MANIFEST that are needed to generate the binaries + fetching it. +#) Fixed a couple of build issues on Mac OS X, AIX and Solaris (64-bit). +#) Modified documentation slightly based on comments from several people. +#) Included files in MANIFEST that are needed to generate the binaries. #) Modified test suite to work within the test environment at Computronix - as well as within the packages that are distributed + as well as within the packages that are distributed. cx_Oracle 3.0 (March 2003) @@ -3419,44 +3833,44 @@ cx_Oracle 3.0 (March 2003) #) Removed support for connection to Oracle7 databases; it is entirely possible that it will still work but I no longer have any way of testing - and Oracle has dropped any meaningful support for Oracle7 anyway + and Oracle has dropped any meaningful support for Oracle7 anyway. #) Fetching of strings is now done with predefined memory areas rather than dynamic memory areas; dynamic fetching of strings was causing problems with Oracle 9i in some instances and databases using a different character - set other than US ASCII + set other than US ASCII. #) Fixed bug where segfault would occur if the '/' character preceded the '@' - character in a connect string + character in a connect string. #) Added two new cursor methods var() and arrayvar() in order to eliminate the need for setinputsizes() when defining PL/SQL arrays and as a generic - method of acquiring bind variables directly when needed + method of acquiring bind variables directly when needed. #) Fixed support for binding cursors and added support for fetching cursors (these are known as ref cursors in PL/SQL). #) Eliminated discrepancy between the array size used internally and the array size specified by the interface user; this was done earlier to avoid bus errors on 64-bit platforms but another way has been found to get around that issue and a number of people were getting confused because of - the discrepancy + the discrepancy. #) Added support for the attribute "connection" on cursors, an optional - DB API extension + DB API extension. #) Added support for passing a dictionary as the second parameter for the cursor.execute() method in order to comply with the DB API more closely; the method of passing parameters with keyword parameters is still supported - and is in fact preferred + and is in fact preferred. #) Added support for the attribute "statement" on cursors which is a - reference to the last SQL statement prepared or executed + reference to the last SQL statement prepared or executed. #) Added support for passing any sequence to callproc() rather than just - lists as before + lists as before. #) Fixed bug where segfault would occur if the array size was changed after - the cursor was executed but before it was fetched + the cursor was executed but before it was fetched. #) Ignore array size when performing executemany() and use the length of the - list of parameters instead + list of parameters instead. #) Rollback when connection is closed or destroyed to follow DB API rather - than use the Oracle default (which is commit) -#) Added check for array size too large causing an integer overflow -#) Added support for iterators for Python 2.2 and above -#) Added test suite based on PyUnitTest + than use the Oracle default (which is commit). +#) Added check for array size too large causing an integer overflow. +#) Added support for iterators for Python 2.2 and above. +#) Added test suite based on PyUnitTest. #) Added documentation in HTML format similar to the documentation for the - core Python library + core Python library. cx_Oracle 2.5a (August 2002) @@ -3465,7 +3879,7 @@ cx_Oracle 2.5a (August 2002) #) Fix problem with Oracle 9i and retrieving strings; it seems that Oracle 9i uses the correct method for dynamic callback but Oracle 8i will not work with that method so an #ifdef was added to check for the existence of an - Oracle 9i feature; thanks to Paul Denize for discovering this problem + Oracle 9i feature; thanks to Paul Denize for discovering this problem. cx_Oracle 2.5 (July 2002) @@ -3473,19 +3887,19 @@ cx_Oracle 2.5 (July 2002) #) Added flag OPT_NoOracle7 which, if set, assumes that connections are being made to Oracle8 or higher databases; this allows for eliminating the - overhead in performing this check at connect time + overhead in performing this check at connect time. #) Added flag OPT_NumbersAsStrings which, if set, returns all numbers as strings rather than integers or floats; this flag is used when defined - variables are created (during select statements only) + variables are created (during select statements only). #) Added flag OPT_Threading which, if set, uses OCI threading mode; there is a significant performance degradation in this mode (about 15-20%) but it does allow threads to share connections (threadsafety level 2 according to the Python Database API 2.0); note that in order to support this, Oracle 8i or - higher is now required + higher is now required. #) Added Py_BEGIN_ALLOW_THREADS and Py_END_ALLOW_THREADS pairs where - applicable to support threading during blocking OCI calls + applicable to support threading during blocking OCI calls. #) Added global method attach() to cx_Oracle to support attaching to an - existing database handle (as provided by PowerBuilder, for example) + existing database handle (as provided by PowerBuilder, for example). #) Eliminated the cursor method fetchbinds() which was used for returning the list of bind variables after execution to get the values of out variables; the cursor method setinputsizes() was modified to return the list of bind @@ -3494,30 +3908,30 @@ cx_Oracle 2.5 (July 2002) these variables have three methods available to them: getvalue([]) to get the value of a variable, setvalue(, ) to set its value and copy(, , ) to copy the value from a variable in a - more efficient manner than setvalue(getvalue()) + more efficient manner than setvalue(getvalue()). #) Implemented cursor method executemany() which expects a list of - dictionaries for the parameters -#) Implemented cursor method callproc() + dictionaries for the parameters. +#) Implemented cursor method callproc(). #) Added cursor method prepare() which parses (prepares) the statement for - execution; subsequent execute() or executemany() calls can pass None as the - statement which will imply use of the previously prepared statement; used - for high performance only + execution; subsequent execute() or executemany() calls can pass *None* as + the statement which will imply use of the previously prepared statement; + used for high performance only. #) Added cursor method fetchraw() which will perform a raw fetch of the cursor returning the number of rows thus fetched; this is used to avoid the - overhead of generating result sets; used for high performance only + overhead of generating result sets; used for high performance only. #) Added cursor method executemanyprepared() which is identical to the method executemany() except that it takes a single parameter which is the number of times to execute a previously prepared statement and it assumes that the bind variables already have their values set; used for high performance - only -#) Added support for rowid being returned in a select statement -#) Added support for comparing dates returned by cx_Oracle + only. +#) Added support for rowid being returned in a select statement. +#) Added support for comparing dates returned by cx_Oracle. #) Integrated patch from Andre Reitz to set the null ok flag in the - description attribute of the cursor + description attribute of the cursor. #) Integrated patch from Andre Reitz to setup.py to support compilation with - Python 1.5 + Python 1.5. #) Integrated patch from Benjamin Kearns to setup.py to support compilation - on Cygwin + on Cygwin. cx_Oracle 2.4 (January 2002) @@ -3547,7 +3961,7 @@ cx_Oracle 2.3 (October 2001) ---------------------------- #) Incremental performance enhancements (dealing with reusing cursors and - bind handles) + bind handles). #) Ensured that arrays of integers with a single float in them are all treated as floats, as suggested by Martin Koch. #) Fixed code dealing with scale and precision for both defining a numeric @@ -3566,7 +3980,7 @@ cx_Oracle 2.2 (July 2001) Brad Powell. #) Added function write(Value, [Offset]) to LOB variables as requested by Matthias Kirst. -#) Procedure execute() on Cursor objects now permits a value None for the +#) Procedure execute() on Cursor objects now permits a value *None* for the statement which means that the previously prepared statement will be executed and any input sizes set earlier will be retained. This was done to improve the performance of scripts that execute one statement many times. diff --git a/doc/src/user_guide/appendix_a.rst b/doc/src/user_guide/appendix_a.rst index 6f65dfee..cfce9f18 100644 --- a/doc/src/user_guide/appendix_a.rst +++ b/doc/src/user_guide/appendix_a.rst @@ -1,5 +1,7 @@ .. _featuresummary: +.. currentmodule:: oracledb + ***************************************************************** Appendix A: Oracle Database Features Supported by python-oracledb ***************************************************************** @@ -14,14 +16,14 @@ Database API v2.0 Specification `PEP 249 enable Thick mode. The following table summarizes the Oracle Database features supported by -python-oracledb Thin and Thick modes, and by cx_Oracle 8.3. For more details -see :ref:`driverdiff` and :ref:`compatibility`. +python-oracledb Thin and Thick modes, and by the obsolete cx_Oracle driver. +For more details see :ref:`driverdiff` and :ref:`upgrading83`. .. list-table-with-summary:: Features Supported by python-oracledb and cx_Oracle 8.3 :header-rows: 1 :class: wy-table-responsive :align: center - :summary: The first column displays the Oracle feature. The second column indicates whether the feature is supported in the python-oracledb Thin mode. The third column indicates whether the feature is supported in the python-oracledb Thick mode. The fourth column indicates if the feature is supported in cx_Oracle 8.3. + :summary: The first column displays the Oracle feature. The second column indicates whether the feature is supported in python-oracledb Thin mode. The third column indicates whether the feature is supported in python-oracledb Thick mode. The fourth column indicates if the feature is supported in the obsolete cx_Oracle driver. * - Oracle Feature - python-oracledb Thin Mode @@ -51,7 +53,7 @@ see :ref:`driverdiff` and :ref:`compatibility`. - Yes - Yes - Yes - * - Connection Pool Runtime Load Balancing (RLB) (see `Runtime Connection Load Balancing `__) + * - Connection Pool Runtime Load Balancing (RLB) (see `Runtime Connection Load Balancing `__) - No - Yes - Yes @@ -167,7 +169,7 @@ see :ref:`driverdiff` and :ref:`compatibility`. - Yes - Yes - Yes - * - Oracle Database 23ai Implicit Connection Pooling with :ref:`DRCP ` and PRCP (see :ref:`implicitconnpool`) + * - Oracle Database version 23 Implicit Connection Pooling with :ref:`DRCP ` and PRCP (see :ref:`implicitconnpool`) - Yes - Yes - No @@ -243,7 +245,11 @@ see :ref:`driverdiff` and :ref:`compatibility`. - No - Yes - Yes - * - Oracle Database 23ai JSON-Relational Duality Views (see :ref:`jsondualityviews`) + * - Direct Path Loads (see :ref:`directpathloads`) + - Yes + - No + - No + * - Oracle Database version 23 JSON-Relational Duality Views (see :ref:`jsondualityviews`) - Yes - Yes - No @@ -252,7 +258,7 @@ see :ref:`driverdiff` and :ref:`compatibility`. - Yes - Yes * - Oracle Transactional Event Queues and Advanced Queuing (AQ) (see :ref:`aqusermanual`) - - Yes - RAW and named Oracle object payloads + - Yes - only "Classic" queues are supported (RAW, named Oracle object, and JSON payloads) - Yes - Yes * - Call timeouts (see :attr:`Connection.call_timeout`) @@ -260,7 +266,7 @@ see :ref:`driverdiff` and :ref:`compatibility`. - Yes - Yes * - Scrollable cursors (see :ref:`scrollablecursors`) - - No + - Yes - Yes - Yes * - Oracle Database startup and shutdown (see :ref:`startup`) @@ -303,7 +309,7 @@ see :ref:`driverdiff` and :ref:`compatibility`. - Yes - No - No - * - Oracle Database 23ai Pipelining (see :ref:`pipelining`) + * - Oracle Database version 23 Pipelining (see :ref:`pipelining`) - Yes - No - No @@ -319,6 +325,10 @@ see :ref:`driverdiff` and :ref:`compatibility`. - Yes - Yes - Yes + * - Oracle Database version 23 Sessionless Transactions (see :ref:`sessionlesstxns`) + - Yes + - Yes + - No * - Two-phase Commit (TPC) (see :ref:`tpc`) - Yes - Yes @@ -369,137 +379,140 @@ example when binding numeric values. :header-rows: 1 :class: wy-table-responsive :align: center - :summary: The first column displays the database data type. The second column displays the python-oracledb constant Name. The third column contains notes. The fourth column shows Python types that can be used. + :summary: The first column displays the database data type. The second column displays the python-oracledb constant Name. The third column shows Python types that can be used. The fourth column contains notes. * - Oracle Database Type - python-oracledb Constant Name - - Notes - Supported Python Types + - Notes * - VARCHAR2 - :data:`~oracledb.DB_TYPE_VARCHAR` - - No relevant notes - bytes, str + - No relevant notes * - NVARCHAR2 - :data:`~oracledb.DB_TYPE_NVARCHAR` - - No relevant notes - bytes, str + - No relevant notes * - NUMBER, FLOAT - :data:`~oracledb.DB_TYPE_NUMBER` - - No relevant notes - bool, int, float, decimal.Decimal + - No relevant notes * - DATE - :data:`~oracledb.DB_TYPE_DATE` - - No relevant notes - datetime.date, datetime.datetime - * - BOOLEAN (PL/SQL and Oracle Database 23ai SQL) - - :data:`~oracledb.DB_TYPE_BOOLEAN` - No relevant notes + * - BOOLEAN (PL/SQL and Oracle Database version 23 SQL) + - :data:`~oracledb.DB_TYPE_BOOLEAN` - Any type convertible to bool + - No relevant notes * - BINARY_DOUBLE - :data:`~oracledb.DB_TYPE_BINARY_DOUBLE` - - No relevant notes - bool, int, float, decimal.Decimal + - No relevant notes * - BINARY_FLOAT - :data:`~oracledb.DB_TYPE_BINARY_FLOAT` - - No relevant notes - bool, int, float, decimal.Decimal + - No relevant notes * - TIMESTAMP - :data:`~oracledb.DB_TYPE_TIMESTAMP` - - No relevant notes - datetime.date, datetime.datetime + - No relevant notes * - TIMESTAMP WITH TIME ZONE - :data:`~oracledb.DB_TYPE_TIMESTAMP_TZ` - - No relevant notes - datetime.date, datetime.datetime + - No relevant notes * - TIMESTAMP WITH LOCAL TIME ZONE - :data:`~oracledb.DB_TYPE_TIMESTAMP_LTZ` - - No relevant notes - datetime.date, datetime.datetime + - No relevant notes * - INTERVAL YEAR TO MONTH - :data:`~oracledb.DB_TYPE_INTERVAL_YM` - - No relevant notes - :ref:`oracledb.IntervalYM ` + - No relevant notes * - INTERVAL DAY TO SECOND - :data:`~oracledb.DB_TYPE_INTERVAL_DS` - - No relevant notes - datetime.timedelta + - No relevant notes * - RAW - :data:`~oracledb.DB_TYPE_RAW` - - No relevant notes - bytes, str + - No relevant notes * - LONG - :data:`~oracledb.DB_TYPE_LONG` - - No relevant notes - bytes, str + - No relevant notes * - LONG RAW - :data:`~oracledb.DB_TYPE_LONG_RAW` - - No relevant notes - bytes, str + - No relevant notes * - ROWID - :data:`~oracledb.DB_TYPE_ROWID` - - No relevant notes - bytes, str + - No relevant notes * - UROWID - :data:`~oracledb.DB_TYPE_ROWID`, :data:`~oracledb.DB_TYPE_UROWID` (only supported in python-oracledb Thin mode) - - May show :data:`~oracledb.DB_TYPE_UROWID` in metadata. See :ref:`Query Metadata Differences `. - bytes, str + - May show :data:`~oracledb.DB_TYPE_UROWID` in metadata. See :ref:`Query Metadata Differences `. * - CHAR - :data:`~oracledb.DB_TYPE_CHAR` - - No relevant notes - bytes, str + - No relevant notes * - BLOB - :data:`~oracledb.DB_TYPE_BLOB` - - No relevant notes - :ref:`oracledb.LOB `, bytes, str + - No relevant notes * - CLOB - :data:`~oracledb.DB_TYPE_CLOB` - - No relevant notes - :ref:`oracledb.LOB `, bytes, str + - No relevant notes * - NCHAR - :data:`~oracledb.DB_TYPE_NCHAR` - - No relevant notes - bytes, str + - No relevant notes * - NCLOB - :data:`~oracledb.DB_TYPE_NCLOB`, :data:`~oracledb.DB_TYPE_LONG_NVARCHAR` (if fetching NCLOB as a string) - - No relevant notes - :ref:`oracledb.LOB `, bytes, str + - No relevant notes * - BFILE - :data:`~oracledb.DB_TYPE_BFILE` - - Can fetch a BFILE object and insert that object in a table. Cannot create BFILE objects. - :ref:`oracledb.LOB `, bytes + - Can fetch a BFILE object and insert that object in a table. Cannot create BFILE objects. * - JSON - :data:`~oracledb.DB_TYPE_JSON` - - No relevant notes - Any type convertible to Oracle JSON + - No relevant notes * - REF CURSOR (PL/SQL OR nested cursor) - :data:`~oracledb.DB_TYPE_CURSOR` - - No relevant notes - :ref:`oracledb.Cursor ` + - No relevant notes * - PLS_INTEGER - :data:`~oracledb.DB_TYPE_BINARY_INTEGER` - - No relevant notes - bool, int, float, decimal.Decimal + - No relevant notes * - BINARY_INTEGER - :data:`~oracledb.DB_TYPE_BINARY_INTEGER` - - No relevant notes - bool, int, float, decimal.Decimal + - No relevant notes * - REF - n/a - - Not supported in python-oracledb Thin mode - n/a + - Not supported in python-oracledb Thin mode * - XMLType - :data:`~oracledb.DB_TYPE_XMLTYPE` - - May need to use ``xmltype.getclobval()`` to fetch in python-oracledb Thick mode. See :ref:`xmldatatype` - bytes, str + - May need to use ``xmltype.getclobval()`` to fetch in python-oracledb Thick mode. See :ref:`xmldatatype` * - User-defined types (object type, VARRAY, records, collections, SDO_*types) - :data:`~oracledb.DB_TYPE_OBJECT` - - No relevant notes - OBJECT of specific type + - No relevant notes * - VECTOR - :data:`~oracledb.DB_TYPE_VECTOR` - - No relevant notes - array.array + - No relevant notes Binding of contiguous PL/SQL Index-by BINARY_INTEGER arrays of string, number, and date are supported in python-oracledb Thin and Thick modes. Use :meth:`Cursor.arrayvar()` to build these arrays. + +When fetching :ref:`data frames `, see :ref:`Data Frame Type +Mapping ` for type information. diff --git a/doc/src/user_guide/appendix_b.rst b/doc/src/user_guide/appendix_b.rst index c1e2ae51..5c69ae37 100644 --- a/doc/src/user_guide/appendix_b.rst +++ b/doc/src/user_guide/appendix_b.rst @@ -1,5 +1,7 @@ .. _driverdiff: +.. currentmodule:: oracledb + ******************************************************************** Appendix B: Differences between python-oracledb Thin and Thick Modes ******************************************************************** @@ -42,7 +44,8 @@ mode. However, only one of these modes can be used in each Python process: :func:`oracledb.connect()` and :func:`oracledb.create_pool()` are keyword and not positional. This makes the python-oracledb driver compliant with the Python Database API specification PEP 249. The old positional usage - possible in cx_Oracle will cause an error, see :ref:`connerrors`. + possible in the obsolete cx_Oracle driver will cause an error, see + :ref:`connerrors`. Connections to a Local Database ------------------------------- @@ -58,7 +61,7 @@ equivalent, must always be used. Oracle Net Services and Client Configuration Files -------------------------------------------------- -In the python-oracledb Thin mode: +In python-oracledb Thin mode: - The location of any ``tnsnames.ora`` files must explicitly be passed to the application. @@ -75,7 +78,7 @@ See :ref:`optnetfiles` and :ref:`optclientfiles` for more information. Token Based Authentication -------------------------- -In the python-oracledb Thin mode: +In python-oracledb Thin mode: - When connecting to Oracle Cloud Database with mutual TLS (mTLS) using OAuth2 tokens, you need to explicitly set the ``config_dir``, ``wallet_location``, @@ -95,10 +98,10 @@ When connecting with mutual TLS (mTLS) also known as two-way TLS, for example to Oracle Autonomous Database in Oracle Cloud using a wallet, the certificate must be in the correct format. -For the python-oracledb Thin mode, the certificate must be in a Privacy -Enhanced Mail (PEM) ``ewallet.pem`` file. In python-oracledb Thick mode the -certificate must be in a ``cwallet.sso`` file. See :ref:`autonomousdb` for -more information. +For python-oracledb Thin mode, the certificate must be in a Privacy Enhanced +Mail (PEM) ``ewallet.pem`` file. In python-oracledb Thick mode the certificate +must be in a ``cwallet.sso`` file. See :ref:`autonomousdb` for more +information. Native Network Encryption and Checksumming ------------------------------------------ @@ -137,17 +140,17 @@ replace ``SessionPool``. A new :func:`oracledb.create_pool()` method is now the recommended way to create a connection pool. The use of the equivalent ``SessionPool()`` constructor is :ref:`deprecated `. -The :func:`~oracledb.create_pool()` method in the python-oracledb Thin mode -differs from the python-oracledb Thick mode in the following ways: +The :func:`~oracledb.create_pool()` method in python-oracledb Thin mode differs +from python-oracledb Thick mode in the following ways: * Not all the parameters of the :func:`oracledb.create_pool()` method are applicable to both python-oracledb modes. Each mode ignores unrecognized parameters. The parameters that are ignored in Thin mode include ``events``, ``tag``, ``matchanytag``, ``shardingkey``, ``supershardingkey``, and - ``handle`` parameters. The parameters that are ignored in the Thick mode - include ``wallet_password``, ``disable_oob``, and ``debug_jdwp`` parameters. + ``handle`` parameters. The parameters that are ignored in Thick mode include + ``wallet_password``, ``disable_oob``, and ``debug_jdwp`` parameters. -* The python-oracledb Thin mode only suppports :ref:`homogeneous +* The python-oracledb Thin mode only supports :ref:`homogeneous ` pools. * The python-oracledb Thin mode creates connections in a daemon thread and so @@ -159,34 +162,41 @@ differs from the python-oracledb Thick mode in the following ways: established. Note that this behavior may also be true of recent versions of the Oracle Call Interface (OCI) Session Pool used in the Thin mode. - If the new ``getmode`` default value of :data:`~oracledb.POOL_GETMODE_WAIT` is - used, then this behavior will not be an issue. With this new default value, any - immediate :meth:`ConnectionPool.acquire()` calls will wait for the connections - to be created by the daemon thread. This improves the application start up time - when compared to the python-oracledb Thick mode and cx_Oracle 8.3 driver, where - :func:`oracledb.create_pool()` will not return control to the application until - all ``pool.min`` connections have been created. + If the new ``getmode`` default value of :data:`~oracledb.POOL_GETMODE_WAIT` + is used, then this behavior will not be an issue. With this new default + value, any immediate :meth:`ConnectionPool.acquire()` calls will wait for the + connections to be created by the daemon thread. This improves application + start up time when compared to python-oracledb Thick mode, where + :func:`oracledb.create_pool()` will not return control to the application + until all ``pool.min`` connections have been created. - If the old default value ``POOL_GETMODE_NOWAIT`` is required, then the application - could check if :attr:`ConnectionPool.opened` has reached :attr:`ConnectionPool.min` - and then continue with application start up. + If the old default value ``POOL_GETMODE_NOWAIT`` is required, then the + application could check if :attr:`ConnectionPool.opened` has reached + :attr:`ConnectionPool.min` and then continue with application start up. * In python-oracledb Thick mode, when you close a connection pool with the parameter ``force=True``, the underlying Oracle Client libraries wait for the current SQL executions to complete before closing the connections. All of the connections are then dropped from the pool and the pool is closed. Closing the pool in python-oracledb Thick mode could stop responding indefinitely, - depending on the network and Oracle Net Services timeout parameters. This is - also applicable to the cx_Oracle 8.3 driver. In python-oracledb Thin mode, - the parameter ``force=True`` disconnects each connection's socket using a - background thread, leaving the database to clean up its end of the - connections. + depending on the network and Oracle Net Services timeout parameters. In + python-oracledb Thin mode, the parameter ``force=True`` disconnects each + connection's socket using a background thread, leaving the database to clean + up its end of the connections. * In python-oracledb Thin mode, the ``cclass`` parameter value is not used to - tag connections in the application connection pool. It is only used for :ref:`drcp`. + tag connections in the application connection pool. It is only used for + :ref:`drcp`. + +* In python-oracledb Thin mode, the connection pool supports all the + :ref:`connection mode privileges `. -* In python-oracledb Thin mode, the connection pool supports all the :ref:`connection - mode privileges `. +* In python-oracledb Thick mode, when the ``thick_mode_dsn_passthrough`` value + in effect is *True*, the ``pool_name`` parameter can be used to specify a + DRCP pool name only if the ``dsn`` parameter is not set. If both of these + parameters are specified, then the ``pool_name`` parameter is ignored. In + python-oracledb Thin mode, both of these parameters can be set and the value + defined in the ``pool_name`` parameter will be used as the DRCP pool name. Supported Database Data Types in Thin and Thick Modes ===================================================== @@ -200,15 +210,15 @@ XMLType database data types has some small differences. See Query Metadata in Thin and Thick Modes ====================================== -In python-oracledb Thin mode, :data:`Cursor.description` metadata can distinguish -the ROWID and UROWID database types. The UROWID database type shows the new value -``DB_TYPE_UROWID`` and the database type ROWID uses the existing value -``DB_TYPE_ROWID``. +In python-oracledb Thin mode, :data:`Cursor.description` metadata can +distinguish the ROWID and UROWID database types. The UROWID database type shows +the new value ``DB_TYPE_UROWID`` and the database type ROWID uses the existing +value ``DB_TYPE_ROWID``. -In python-oracledb Thick mode, the value ``DB_TYPE_ROWID`` is shown for both ROWID -and UROWID database types. In python-oracledb Thick and Thin modes, comparison with -the type ``oracledb.ROWID`` (defined in the Python DB API) will match both ROWID and -UROWID database types. +In python-oracledb Thick mode, the value ``DB_TYPE_ROWID`` is shown for both +ROWID and UROWID database types. In python-oracledb Thick and Thin modes, +comparison with the type ``oracledb.ROWID`` (defined in the Python DB API) will +match both ROWID and UROWID database types. .. _implicitresultsdiff: @@ -231,32 +241,42 @@ cursors are independently handled in Thin mode. Statement Caching in Thin and Thick Modes ========================================= -The :ref:`statement cache ` implemented in the python-oracledb Thin -mode is capable of determining when different database data types are used for -the same bind variables when a statement is re-executed. This capability is -not supported in the Oracle Client libraries that are used in python-oracledb -Thick mode. Note changing the type of bind variables for the same SQL text is +The :ref:`statement cache ` implemented in python-oracledb Thin mode +is capable of determining when different database data types are used for the +same bind variables when a statement is re-executed. This capability is not +supported in the Oracle Client libraries that are used in python-oracledb Thick +mode. Note changing the type of bind variables for the same SQL text is inappropriate and gives indeterminate results in both modes. +Duplicate SQL Bind Variable Placeholders in Thin and Thick Modes +================================================================ + +To use python-oracledb Thin mode when you have duplicate bind variable +placeholder names in a SQL statement and are :ref:`binding by position +`, then supply a value for each use of the placeholders, see +:ref:`dupbindplaceholders`. + +This does not apply to PL/SQL blocks. + Error Handling in Thin and Thick Modes ====================================== -The python-oracledb Thin and Thick modes handle some errors differently. See +Python-oracledb Thin and Thick modes handle some errors differently. See :ref:`errorhandling`. Globalization in Thin and Thick Modes ===================================== All NLS environment variables, and the ``ORA_TZFILE`` environment variable, are -ignored by the python-oracledb Thin mode. Use Python's capabilities instead. +ignored by python-oracledb Thin mode. Use Python's capabilities instead. -The python-oracledb Thin mode can only use NCHAR, NVARCHAR2, and NCLOB data -when Oracle Database's secondary character set is AL16UTF16. +Python-oracledb Thin mode can only use NCHAR, NVARCHAR2, and NCLOB data when +Oracle Database's secondary character set is AL16UTF16. See :ref:`globalization`. Tracing in Thin and Thick Modes =============================== -In the python-oracledb Thin mode, low level tracing is different because there -are no Oracle Client libraries. See :ref:`tracingsql`. +In python-oracledb Thin mode, low level tracing is different because there are +no Oracle Client libraries. See :ref:`tracingsql`. diff --git a/doc/src/user_guide/appendix_c.rst b/doc/src/user_guide/appendix_c.rst index 79fa7925..ca40428e 100644 --- a/doc/src/user_guide/appendix_c.rst +++ b/doc/src/user_guide/appendix_c.rst @@ -1,410 +1,65 @@ -.. _upgradecomparison: +.. currentmodule:: oracledb ***************************************************** Appendix C: The python-oracledb and cx_Oracle Drivers ***************************************************** -The python-oracledb driver is the renamed, major version successor to cx_Oracle -8.3. As a major release, the python-oracledb driver has :ref:`new features -` and some :ref:`deprecations`. Also see :ref:`upgrading83`. -The cx_Oracle driver is obsolete and should not be used for new development. - -.. _compatibility: - -Differences between the python-oracledb and cx_Oracle Drivers -============================================================= - -The differences between the cx_Oracle 8.3 and python-oracledb drivers are -listed here. - -Mode differences from cx_Oracle -------------------------------- - -By default, python-oracledb runs in a 'Thin' mode which connects directly to -Oracle Database. This mode does not need Oracle Client libraries. However, -some :ref:`additional functionality ` is available when -python-oracledb uses them. Python-oracledb is said to be in 'Thick' mode when -Oracle Client libraries are used. See :ref:`enablingthick`. Both modes have -comprehensive functionality supporting the Python Database API v2.0 -Specification. - -cx_Oracle always runs in a Thick mode using Oracle Client libraries. The -features in python-oracledb Thick mode and cx_Oracle 8.3 are the same, subject -to the :ref:`new features `, some :ref:`deprecations -`, and to other changes noted in this section. - -Oracle Client Library Loading Differences from cx_Oracle --------------------------------------------------------- - -Oracle Client libraries are now only loaded if -:func:`oracledb.init_oracle_client()` is called in your application. This -changes python-oracledb to Thick mode. The ``init_oracle_client()`` method must -be called before any :ref:`standalone connection ` or -:ref:`connection pool ` is created. If a connection or pool is -created first in the default Thin mode, then Thick mode cannot be enabled. - -See :ref:`enablingthick` for more information. - -Calling the ``init_oracle_client()`` method immediately loads Oracle Client -libraries. To emulate the cx_Oracle behavior of deferring library loading -until the creation of the first connection (in the case when -``init_oracle_client()`` is not called), your application will need to -explicitly defer calling ``init_oracle_client()`` as appropriate. - -In python-oracledb, ``init_oracle_client()`` can now be called multiple times -in the one Python process as long as its arguments are the same each time. - -oracledb.clientversion() -++++++++++++++++++++++++ - -The :func:`oracledb.clientversion()` method shows the version of the Oracle -Client libraries being used. There is no Oracle Client used in the -python-oracledb Thin mode so this function can only be called in -python-oracledb Thick mode. If this function is called before -:func:`oracledb.init_oracle_client()`, an exception is thrown. - -Connection Differences from cx_Oracle -------------------------------------- - -.. _connectdiffs: - -oracledb.connect() Differences -++++++++++++++++++++++++++++++ - -The :func:`oracledb.connect()` function in the python-oracledb driver differs -from cx_Oracle: - -- Keyword parameters **must** be used in calls to :func:`oracledb.connect()`. - This change makes the driver compliant with the Python Database API - specification PEP 249. See - :ref:`Standalone Connections ` and :ref:`connerrors`. - -- New optional keyword arguments can be passed to :func:`~oracledb.connect()`. - For example you can pass the hostname, port and servicename as separate - parameters instead of using an Easy Connect connection string. In - python-oracledb Thin mode, some of the new arguments replace :ref:`sqlnet.ora - ` settings. - -- A new optional parameter ``params`` of type :ref:`ConnectParams ` - can be used to encapsulate connection properties. See :ref:`usingconnparams` - for more information. - -- The following parameters are desupported: - - - ``encoding`` and ``nencoding``: The encodings in use are always UTF-8. - - - ``threaded``: Threaded Oracle Call Interface (OCI) is now always enabled - in Thick mode. This option is not relevant to the Thin mode. - - See :ref:`deprecations` for more information. - -The use of the class constructor method ``oracledb.Connection()`` to create -connections is no longer recommended for creating connections. Use -:func:`~oracledb.connect()` instead. - -The :meth:`oracledb.makedsn()` method for creating the ``dsn`` value has been -deprecated. New code should use :meth:`oracledb.ConnectParams()` or use the -new keyword arguments in :func:`oracledb.connect()`. - - -Connection Object Differences -+++++++++++++++++++++++++++++ - -The :ref:`Connection object ` differences between the python-oracledb -and cx_Oracle drivers are: - -- The attribute :attr:`Connection.maxBytesPerCharacter` is deprecated. This - will return a constant value of 4 since encodings are always UTF-8. - -- A new boolean attribute, :attr:`Connection.thin` is available. This - attribute is True if the connection was established in the Thin mode. In - Thick mode, the value of this attribute is False. - -- The new method signature of :attr:`Connection.outputtypehandler` is - ``handler(cursor, metadata)``. The old signature ``handler(cursor, name, - default_type, length, precision, scale)`` was deprecated in python-oracledb - 1.4 but will still work and will be removed in a future version. - -See :ref:`connattrs` for more information. - -Pooling Differences from cx_Oracle ----------------------------------- - -It is recommended to use the new :ref:`ConnectionPool Object ` -instead of the equivalent SessionPool object, which is deprecated. To create a -connection pool, use :meth:`oracledb.create_pool()`, which is equivalent to -calling ``cx_Oracle.SessionPool()``. - -For more information, see :ref:`connpooling`. - -oracledb.SessionPool() Differences -++++++++++++++++++++++++++++++++++ - -The python-oracledb ``oracledb.SessionPool()`` method (which is an alias of -:func:`oracledb.create_pool()`) differs from ``cx_Oracle.SessionPool()`` as -follows: - -- Keyword parameters **must** be used in calls. This change makes the driver - compliant with the Python Database API specification PEP 249. See - :ref:`Connection pooling ` and :ref:`connerrors`. - -- Passing a value to the ``dsn`` parameter that contains the user name and - password is now supported in the same way as :func:`oracledb.connect()`. For - example ``dsn="un/pw@cs"`` can be used. - -- New optional keyword arguments can be passed to - :func:`~oracledb.create_pool()`. For example you can pass the hostname, port - and servicename as separate parameters instead of using an Easy Connect - connection string. In python-oracledb Thin mode, some of the new arguments - replace :ref:`sqlnet.ora ` settings. - -- A new optional parameter ``params`` of type :ref:`PoolParams ` - can be used to encapsulate connection properties. See :ref:`usingconnparams` - for more information. - -- The default mode is :data:`~oracledb.POOL_GETMODE_WAIT` instead of - :data:`~oracledb.POOL_GETMODE_NOWAIT`. If the mode - :data:`~oracledb.POOL_GETMODE_NOWAIT` is truly desired, modify any pool - creation code to specify this value instead. Note the namespace of - constants has been improved. Old names like ``SPOOL_ATTRVAL_NOWAIT`` can be - used but are now deprecated. - -- The ``encoding`` and ``nenecoding`` parameters are deprecated and - ignored. The encodings in use are always UTF-8. - -- New keyword arguments that are used internally to create a :ref:`PoolParams - object ` before creating the connection. - -The :meth:`oracledb.makedsn()` method for creating the ``dsn`` value has been -deprecated. New code should use :meth:`oracledb.ConnectParams()` or use the -new keyword arguments to :func:`oracledb.create_pool()`. - -SessionPool Object Differences -++++++++++++++++++++++++++++++ - -The SessionPool object (which is an alias for the :ref:`ConnectionPool object -`) differences between the python-oracledb and cx_Oracle drivers are: - -- A Python type() will show the class as ``oracledb.ConnectionPool`` instead - of ``cx_Oracle.SessionPool``. - -- A new boolean attribute, ``SessionPool.thin`` (see - :attr:`ConnectionPool.thin`) is available. This attribute is True if the - connection was established in the Thin mode. In Thick mode, the value of - this attribute is False. - -Cursor Object Differences from cx_Oracle ----------------------------------------- - -The differences between the :ref:`Cursor object ` in -python-oracledb and cx_Oracle drivers are: - -- :meth:`Cursor.fetchmany()`: The name of the size argument of ``fetchmany()`` - is ``size``. This change was done to comply with `PEP 249 - `_. The previous keyword argument name, - ``numRows`` is deprecated. - -- ``Cursor.fetchraw()``: This method was previously deprecated in cx_Oracle - 8.2 and has been removed in python-oracledb. Instead, use one of the other - fetch methods such as :meth:`Cursor.fetchmany()`. - -- ``Cursor.executemanyprepared()``: This method was previously deprecated in - cx_Oracle 6.4 and has been removed in python-oracledb. Instead, use - :meth:`Cursor.executemany()`, by passing None for the statement argument and - an integer for the parameters argument. - -- ``Cursor.bindarraysize``: This attribute is desupported and removed in - python-oracledb. It is not needed in the application code. - -- :attr:`Cursor.rowcount`: After :meth:`Cursor.execute()` or - :meth:`Cursor.executemany()` with PL/SQL statements, ``Cursor.rowcount`` - will return 0. If the cursor or connection are not open, then the value -1 - will be returned as required by the Python Database API. - -- :attr:`Cursor.description`: This attribute was previously a sequence of - 7-item sequences in cx_Oracle and python-oracledb. Each of these sequences - contained information describing one result column, that is, (name, type, - display_size, internal_size, precision, scale, null_ok). In - python-oracledb 1.4, this attribute was changed to a sequence of - :ref:`FetchInfo ` objects. Each FetchInfo object describes one - result column and can behave as a 7-tuple like before, but contains - additional information that may be helpful when using - :ref:`output type handlers `. - -- :attr:`Cursor.outputtypehandler`: The new method signature of this attribute - is ``handler(cursor, metadata)``. The old signature ``handler(cursor, name, - default_type, length, precision, scale)`` was deprecated in python-oracledb - 1.4 but will still work and will be removed in a future version. - -.. _fetchisjson: - -Fetching IS JSON Column Differences from cx_Oracle --------------------------------------------------- - -In python-oracledb, VARCHAR2 and LOB columns that have the ``IS JSON`` -constraint enabled are fetched as Python objects. These columns are fetched in -the same way that :ref:`JSON type columns ` are fetched when -using Oracle Database 21c (or later). The returned value varies depending on -the JSON data. If the JSON data is an object, then a dictionary is returned. -If it is an array, then a list is returned. If it is a scalar value, then that -particular scalar value is returned. - -In cx_Oracle, VARCHAR2 and LOB columns that have the ``IS JSON`` constraint -enabled are fetched as strings and LOB objects respectively. To enable this -same fetch behavior in python-oracledb, you must use an -:ref:`output type handler ` as shown below. - -.. code-block:: python - - def type_handler(cursor, fetch_info): - if fetch_info.is_json: - return cursor.var(fetch_info.type_code, cursor.arraysize) - -Advanced Queuing (AQ) Differences from cx_Oracle ------------------------------------------------- - -Use the new :ref:`Advanced Queuing (AQ) ` API instead of the -older API which was deprecated in cx_Oracle 7.2 and is not available in -python-oracledb. - -Replace: - -- ``Connection.deq()`` with :meth:`Queue.deqone()` or :meth:`Queue.deqmany()` -- ``Connection.deqoptions()`` with attribute :attr:`Queue.deqoptions` -- ``Connection.enq()`` with :meth:`Queue.enqone()` or :meth:`Queue.enqmany()` -- ``Connection.enqoptions()`` with attribute :attr:`Queue.enqoptions` - -The AQ support in python-oracledb has the following enhancements from -cx_Oracle: - -- AQ messages can be enqueued and dequeued as a JSON payload type -- Recipient lists can be enqueued and dequeued -- Enqueue options, dequeue options, and message properties can be set - -See :ref:`Oracle Advanced Queuing (AQ) `. - -.. _errordiff: - -Error Handling Differences from cx_Oracle ------------------------------------------ - -In python-oracledb Thick mode, error messages generated by the Oracle Client -libraries and the `ODPI-C `_ layer used by -cx_Oracle and python-oracledb in Thick mode are mostly returned unchanged from -cx_Oracle 8.3. Some exceptions shown below. - -Note that the python-oracledb driver error messages can also vary between Thin -and Thick modes. See :ref:`errorhandling`. - -ConnectionPool.acquire() Message Differences -++++++++++++++++++++++++++++++++++++++++++++ - -:meth:`ConnectionPool.acquire()` ORA errors will be mapped to DPY errors. For -example:: - - DPY-4005: timed out waiting for the connection pool to return a connection - -replaces the cx_Oracle 8.3 error:: - - ORA-24459: OCISessionGet() timed out waiting for pool to create new connections - -Dead Connection Detection and Timeout Message Differences -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -Application code which detects connection failures or statement execution -timeouts will need to check for new errors, ``DPY-4011`` and ``DPY-4024`` -respectively. The error ``DPY-1001`` is returned if an already dead connection -is attempted to be used. - -The new Error object attribute :attr:`~oracledb._Error.full_code` may be -useful for checking the error code. - -Example error messages are: - -* Scenario 1: An already closed or dead connection was attempted to be used. - - python-oracledb Thin Error:: - - DPY-1001: not connected to database - - python-oracledb Thick Error:: - - DPY-1001: not connected to database - - cx_Oracle Error:: - - not connected - -* Scenario 2: The database side of the connection was terminated while the - connection was being used. - - python-oracledb Thin Error:: - - DPY-4011: the database or network closed the connection - - python-oracledb Thick Error:: - - DPY-4011: the database or network closed the connection - DPI-1080: connection was closed by ORA-%d - - cx_Oracle Error:: - - DPI-1080: connection was closed by ORA-%d - -* Scenario 3: Statement execution exceeded the :attr:`connection.call_timeout` - value. - - python-oracledb Thin Error:: - - DPY-4024: call timeout of {timeout} ms exceeded - - python-oracledb Thick Error:: - - DPY-4024: call timeout of {timeout} ms exceeded - DPI-1067: call timeout of %u ms exceeded with ORA-%d - - cx_Oracle Error:: - - DPI-1067: call timeout of %u ms exceeded with ORA-%d +The python-oracledb driver is the renamed, successor to cx_Oracle. The +python-oracledb driver has many :ref:`new features ` and some +:ref:`deprecations` compared with cx_Oracle. The cx_Oracle driver is obsolete +and should not be used for new development. .. _upgrading83: Upgrading from cx_Oracle 8.3 to python-oracledb =============================================== -This section provides the detailed steps needed to upgrade from cx_Oracle 8.3 -to python-oracledb. - -Things to Know Before the Upgrade ---------------------------------- - Below is a list of some useful things to know before upgrading from cx_Oracle to python-oracledb: - You can have both cx_Oracle and python-oracledb installed, and can use both - in the same application. + in the same application. Install python-oracledb like:: + + python -m pip install oracledb --upgrade + + See :ref:`installation` for details. + +- By default, python-oracledb runs in a 'Thin' mode which connects directly to + Oracle Database. This mode does not need Oracle Client libraries. However, + some :ref:`additional functionality ` is available when + python-oracledb uses them. Python-oracledb is said to be in 'Thick' mode + when Oracle Client libraries are used. See :ref:`enablingthick`. Both modes + have comprehensive functionality supporting the Python Database API v2.0 + Specification. The Thick mode is equivalent to cx_Oracle. + + cx_Oracle always runs in a Thick mode using Oracle Client libraries. The + features in python-oracledb Thick mode and cx_Oracle 8.3 are the same, subject + to the :ref:`new features `, some :ref:`deprecations + `, and to other changes noted in the documentation. + +- python-oracledb Thin and Thick modes have the same level of support for the + `Python Database API specification `_ and + can be used to connect to on-premises databases and Oracle Cloud + databases. See :ref:`driverdiff`. -- If you only want to use the python-oracledb driver in Thin mode, then you do - not need Oracle Client libraries such as from Oracle Instant Client. You - only need to :ref:`install ` the driver itself:: + Examples can be found in the `GitHub samples directory + `__. A basic + example is: - python -m pip install oracledb + .. code-block:: python + + import oracledb + import getpass - See :ref:`driverdiff`. + pw = getpass.getpass(f"Enter password for hr@localhost/orclpdb: ") -- The python-oracledb Thin and Thick modes have the same level of support for - the `Python Database API specification `_ - and can be used to connect to on-premises databases and Oracle Cloud - databases. However, the python-oracledb Thin mode does not support some of - the advanced Oracle Database features such as Application Continuity (AC), - Advanced Queuing (AQ), Continuous Query Notification (CQN), and Sharding. - See :ref:`Features Supported ` for details. + with oracledb.connect(user="hr", password=userpwd, dsn="localhost/orclpdb") as connection: + with connection.cursor() as cursor: + for r in cursor.execute("select sysdate from dual"): + print(r) - python-oracledb can be used in SQLAlchemy, Django, Pandas, Superset and other - frameworks and Object-relational Mappers (ORMs). To use python-oracledb in - versions of these libraries that don't have native support for the new name, - you can override the use of cx_Oracle with a few lines of code. See - :ref:`frameworks`. + frameworks and Object-relational Mappers (ORMs). See :ref:`frameworks`. - python-oracledb connection and pool creation calls require keyword arguments to conform with the Python Database API specification. For example you must @@ -412,40 +67,24 @@ to python-oracledb: .. code-block:: python - oracledb.connect(user="scott", password=pw, dsn="localhost/orclpdb") + connection = oracledb.connect(user="scott", password=pw, dsn="localhost/orclpdb") This no longer works: .. code-block:: python - oracledb.connect("scott", pw, "localhost/orclpdb") - -- The python-oracledb Thin mode ignores all NLS environment variables. It - also ignores the ``ORA_TZFILE`` environment variable. Thick mode does use - these variables. See :ref:`globalization` for alternatives. - -- To use a ``tnsnames.ora`` file in the python-oracledb Thin mode, you must - explicitly set the environment variable ``TNS_ADMIN`` to the directory - containing the file, or set :attr:`defaults.config_dir`, or set the - ``config_dir`` parameter when connecting. + connection = oracledb.connect("scott", pw, "localhost/orclpdb") - Only python-oracledb Thick mode will read :ref:`sqlnet.ora ` - files. The Thin mode lets equivalent properties be set in the application - when connecting. - - Configuration files in a "default" location such as the Instant Client - ``network/admin/`` subdirectory, in ``$ORACLE_HOME/network/admin/``, or in - ``$ORACLE_BASE/homes/XYZ/network/admin/`` (in a read-only Oracle Database - home) are not automatically loaded in Thin mode. Default locations are - only automatically searched in Thick mode. +- New optional keyword arguments can be passed to connection and pool creation + functions. For example you can pass the hostname, port and servicename as + separate parameters instead of using an Easy Connect connection string. In + python-oracledb Thin mode, some of the new arguments replace :ref:`sqlnet.ora + ` settings. -- To use the python-oracledb Thin mode in an ORACLE_HOME database installation - environment, you must use an explicit connection string since the - ``ORACLE_SID``, ``TWO_TASK``, and ``LOCAL`` environment variables are not - used. They are used in Thick mode. +- Some previously deprecated features are no longer available. See + :ref:`deprecations`. -- This is a major release so some previously deprecated features are no longer - available. See :ref:`deprecations`. +- There are many new features, see the :ref:`release notes `. .. _commonupgrade: @@ -460,7 +99,7 @@ following steps: 1. Install the new python-oracledb module:: - python -m pip install oracledb + python -m pip install oracledb --upgrade See :ref:`installation` for more details. @@ -500,7 +139,7 @@ following steps: You **must** replace positional parameters with keyword parameters, unless only one parameter is being passed. Python-oracledb uses keyword parameters exclusively unless a DSN containing the user, password, and connect string - combined, for example ``un/pw@cs``, is used. This change makes the driver + combined, for example ``"un/pw@cs"``, is used. This change makes the driver compliant with the Python Database API specification `PEP 249 `_. @@ -533,19 +172,18 @@ following steps: parameter was already ignored in ``oracledb.SessionPool()`` from cx_Oracle 8.2. -5. Remove all references to :meth:`Cursor.fetchraw()` as this method was - deprecated in cx_Oracle 8.2 and has been removed in python-oracledb. - Instead, use one of the other fetch methods such as - :meth:`Cursor.fetchmany()`. +5. Remove all references to ``Cursor.fetchraw()`` as this method was deprecated + in cx_Oracle 8.2 and has been removed in python-oracledb. Instead, use one + of the other fetch methods such as :meth:`Cursor.fetchmany()`. -6. The default value of the ``oracledb.SessionPool()`` parameter - :attr:`~Connection.getmode` now waits for an available connection. That - is, the default is now :data:`~oracledb.POOL_GETMODE_WAIT` instead of +6. The default value of the ``oracledb.SessionPool()`` parameter ``getmode`` + now waits for an available connection. That is, the default is now + :data:`~oracledb.POOL_GETMODE_WAIT` instead of :data:`~oracledb.POOL_GETMODE_NOWAIT`. The new default value improves the behavior for most applications. If the pool is in the middle of growing, the new value prevents transient connection creation errors from occurring - when using the Thin mode, or when using the Thick mode with recent Oracle - Client libraries. + when using python-oracledb Thin mode, or when using Thick mode with recent + Oracle Client libraries. If the old default value is required, modify any pool creation code to explicitly specify ``getmode=oracledb.POOL_GETMODE_NOWAIT``. @@ -556,48 +194,163 @@ following steps: as :data:`~oracledb.POOL_GETMODE_NOWAIT` and :data:`~oracledb.PURITY_SELF` are now preferred. The old namespaces still work. -7. The method signature of the :ref:`output type handler ` - which can be specified on a - :attr:`connection ` or on a - :attr:`cursor ` is ``handler(cursor, metadata)``. - The old signature ``handler(cursor, name, default_type, length, precision, - scale)`` was deprecated in python-oracledb 1.4 but will still work and will - be removed in a future version. +7. A Python `type() `__ + will show the class of a connection pool as ``oracledb.ConnectionPool`` + instead of ``cx_Oracle.SessionPool``. Update code as needed. + +8. Use the new :ref:`Advanced Queuing (AQ) ` API instead of the + older API which was deprecated in cx_Oracle 7.2 and is not available in + python-oracledb. + + Replace: + + - ``Connection.deq()`` with :meth:`Queue.deqone()` or :meth:`Queue.deqmany()` + - ``Connection.deqoptions()`` with attribute :attr:`Queue.deqoptions` + - ``Connection.enq()`` with :meth:`Queue.enqone()` or :meth:`Queue.enqmany()` + - ``Connection.enqoptions()`` with attribute :attr:`Queue.enqoptions` + + See :ref:`aqusermanual`. + +9. Remove calls to ``Cursor.executemanyprepared()``. This method was previously + deprecated in cx_Oracle 6.4 and has been removed in + python-oracledb. Instead, use :meth:`Cursor.executemany()` by passing *None* + for the statement argument and an integer for the ``parameters`` argument. + +10. Remove the use of the ``Cursor.bindarraysize``. It is desupported and not + needed in the application code. + +11. In python-oracledb, VARCHAR2 and LOB columns that have the ``IS JSON`` + constraint enabled are fetched by default as Python objects. These columns + are fetched in the same way that :ref:`JSON type columns ` are + fetched when using Oracle Database 21c (or later). The returned value + varies depending on the JSON data. If the JSON data is an object, then a + dictionary is returned. If it is an array, then a list is returned. If it + is a scalar value, then that particular scalar value is returned. + + In cx_Oracle, VARCHAR2 and LOB columns that have the ``IS JSON`` constraint + enabled are fetched by default as strings and LOB objects respectively. To + enable this same fetch behavior in python-oracledb, you can use an + :ref:`output type handler ` as shown below. + + .. code-block:: python + + def type_handler(cursor, fetch_info): + if fetch_info.is_json: + return cursor.var(fetch_info.type_code, cursor.arraysize) + +12. Review uses of :attr:`Cursor.rowcount`. After :meth:`Cursor.execute()` or + :meth:`Cursor.executemany()` with PL/SQL statements, :attr:`Cursor.rowcount` + will return *0*. If the cursor or connection are not open, then the value + *-1* will be returned as required by the Python Database API. + +13. In python-oracledb Thick mode, error messages generated by the Oracle + Client libraries and the `ODPI-C `_ layer + used by cx_Oracle and python-oracledb in Thick mode are mostly returned + unchanged from cx_Oracle 8.3. Some exceptions shown below. + + Note that the python-oracledb driver error messages can also vary between + Thin and Thick modes. See :ref:`errorhandling`. + + **ConnectionPool.acquire() Message Differences** + + :meth:`ConnectionPool.acquire()` ORA errors will be mapped to DPY errors. + For example:: + + DPY-4005: timed out waiting for the connection pool to return a connection + + replaces the cx_Oracle 8.3 error:: + + ORA-24459: OCISessionGet() timed out waiting for pool to create new connections + + **Dead Connection Detection and Timeout Message Differences** + + Application code which detects connection failures or statement execution + timeouts will need to check for new errors, ``DPY-4011`` and ``DPY-4024`` + respectively. The error ``DPY-1001`` is returned if an already dead connection + is attempted to be used. + + The new Error object attribute :attr:`~oracledb._Error.full_code` may be + useful for checking the error code. + + Example error messages are: + + * Scenario 1: An already closed or dead connection was attempted to be used. -8. VARCHAR2 and LOB columns that have the ``IS JSON`` constraint enabled are - fetched by default as Python objects in python-oracledb. In cx_Oracle, - VARCHAR2 and LOB columns that contain JSON data are fetched by default as - strings and LOB objects respectively. See :ref:`fetchisjson`. + python-oracledb Thin mode Error:: -9. Review the following sections to see if your application requirements are - satisfied by the python-oracledb Thin mode: + DPY-1001: not connected to database - - :ref:`featuresummary` - - :ref:`driverdiff` + python-oracledb Thick mode Error:: - If your application requirements are not supported by the Thin mode, then - use the python-oracledb Thick mode. + DPY-1001: not connected to database -10. Review :ref:`compatibility`. + cx_Oracle Error:: - If your code base uses an older cx_Oracle version, review the previous - :ref:`release notes ` for additional changes to modernize - the code. + not connected -11. Modernize code as needed or desired. See :ref:`deprecations` for the list - of deprecations in python-oracledb. + * Scenario 2: The database side of the connection was terminated while the + connection was being used. + + python-oracledb Thin mode Error:: + + DPY-4011: the database or network closed the connection + + python-oracledb Thick mode Error:: + + DPY-4011: the database or network closed the connection + DPI-1080: connection was closed by ORA-%d + + cx_Oracle Error:: + + DPI-1080: connection was closed by ORA-%d + + * Scenario 3: Statement execution exceeded the :attr:`connection.call_timeout` + value. + + python-oracledb Thin mode Error:: + + DPY-4024: call timeout of {timeout} ms exceeded + + python-oracledb Thick mode Error:: + + DPY-4024: call timeout of {timeout} ms exceeded + DPI-1067: call timeout of %u ms exceeded with ORA-%d + + cx_Oracle Error:: + + DPI-1067: call timeout of %u ms exceeded with ORA-%d + +14. If your code base uses an older cx_Oracle version, review + :ref:`deprecations` for additional changes that may be necessary. + +15. Modernize code to take advantage of new features, if desired. See the + :ref:`release notes `. + +16. Review the following sections to see if your application requirements are + satisfied by python-oracledb Thin mode: + + - :ref:`featuresummary` + - :ref:`driverdiff` + + If so, then follow :ref:`upgradethin`. + + If your application requirements are not supported by python-oracledb Thin + mode, then use Thick mode, see :ref:`upgradethick`. + +.. _upgradethin: Additional Upgrade Steps to use python-oracledb Thin Mode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -To use python-oracledb Thin mode, the following changes need to be made in -addition to the common :ref:`commonupgrade`: +To upgrade from cx_Oracle to python-oracledb Thin mode, the following changes +need to be made in addition to the common :ref:`commonupgrade`: 1. Remove calls to :func:`~oracledb.init_oracle_client` since this turns on - the python-oracledb Thick mode. + python-oracledb Thick mode. 2. If the ``config_dir`` parameter of :func:`~oracledb.init_oracle_client` had - been used, then set the new :attr:`defaults.config_dir` attribute to the + been used, then set the new + :attr:`oracledb.defaults.config_dir ` attribute to the desired value or set the ``config_dir`` parameter in your connection or pool creation method call. For example: @@ -616,8 +369,9 @@ addition to the common :ref:`commonupgrade`: Also, see :ref:`sqlnetclientconfig`. 3. If the ``driver_name`` parameter of :func:`~oracledb.init_oracle_client` had - been used, then set the new :attr:`defaults.driver_name` attribute to the - desired value or set the ``driver_name`` parameter when connecting. The + been used, then set the new + :attr:`oracledb.defaults.driver_name ` attribute to + the desired value or set the ``driver_name`` parameter when connecting. The convention for this parameter is to separate the product name from the product version by a colon and single blank characters. For example: @@ -627,19 +381,39 @@ addition to the common :ref:`commonupgrade`: See :ref:`otherinit`. -4. If the application is connecting using a :ref:`TNS Alias ` from - a ``tnsnames.ora`` file located in a "default" location such as the Instant - Client ``network/admin/`` subdirectory, in ``$ORACLE_HOME/network/admin/``, - or in ``$ORACLE_BASE/homes/XYZ/network/admin/`` (in a read-only Oracle - Database home), then the configuration file directory must now explicitly be - set as shown in Step 2. - -5. Remove calls to :func:`oracledb.clientversion()` which is only available in - the python-oracledb Thick mode. Oracle Client libraries are not available - in Thin mode. - -6. Ensure that any assumptions about when connections are created in the - connection pool are eliminated. The python-oracledb Thin mode creates +4. Remove calls to :func:`oracledb.clientversion()`. + + The :func:`oracledb.clientversion()` function shows the version of the + Oracle Client libraries being used. Since Oracle Client libraries are not + used in python-oracledb Thin mode, this function cannot be called. If it is + called before calling :func:`oracledb.init_oracle_client()`, an exception is + thrown. + +5. To connect using a :ref:`TNS Alias ` from a ``tnsnames.ora`` + file (see :ref:`optnetfiles`) in python-oracledb Thin mode, you should + explicitly set the environment variable ``TNS_ADMIN`` to the directory + containing the file, or set + :attr:`oracledb.defaults.config_dir `, or set the + ``config_dir`` parameter when connecting. + + A ``tnsnames.ora`` file in a "default" location such as the Instant Client + ``network/admin/`` subdirectory may not be automatically loaded in Thin mode + on some platforms. A ``tnsnames.ora`` file identified by the Windows + registry, or in ``$ORACLE_BASE/homes/XYZ/network/admin/`` (in a read-only + Oracle Database home) will never be automatically located by python-oracledb + Thin mode. + + Only python-oracledb Thick mode will read :ref:`sqlnet.ora ` and + :ref:`oraaccess.xml ` files. The Thin mode lets equivalent + properties be set in the application when connecting. + +6. To use python-oracledb Thin mode in an ``ORACLE_HOME`` database installation + environment, you must use an explicit connection string since the + ``ORACLE_SID``, ``TWO_TASK``, and ``LOCAL`` environment variables are not + used. They are used in Thick mode. + +7. Ensure that any assumptions about when connections are created in the + connection pool are eliminated. Python-oracledb Thin mode creates connections in a daemon thread and so the attribute :attr:`ConnectionPool.opened` will change over time and will not be equal to :attr:`ConnectionPool.min` immediately after the pool is created. Note @@ -650,38 +424,81 @@ addition to the common :ref:`commonupgrade`: :meth:`ConnectionPool.acquire()` until sufficient time has passed for connections in the pool to be created. -7. Review error handling improvements. See :ref:`errorhandling`. +8. Review locale and globalization usage. Python-oracledb Thin mode ignores + all NLS environment variables. It also ignores the ``ORA_TZFILE`` + environment variable. Thick mode does use these variables. See + :ref:`globalization`. -8. Review locale and globalization usage. See :ref:`globalization`. +9. If SQL statements contain repeated bind variable placeholder names, and you + are :ref:`binding by position `, then make sure that a value + is passed for each use of the placeholder, see :ref:`dupbindplaceholders`. + +.. _upgradethick: Additional Upgrade Steps to use python-oracledb Thick Mode ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -To use python-oracledb Thick mode, the following changes need to be made in -addition to the common :ref:`commonupgrade`: - -1. The function :func:`oracledb.init_oracle_client()` *must* be called. It - can be called anywhere before the first call to :func:`~oracledb.connect()`, - ``oracledb.Connection()``, and ``oracledb.SessionPool()``. This enables the - Thick mode. See :ref:`enablingthick` for more details. +To upgrade from cx_Oracle to python-oracledb Thick mode, in addition to the +common :ref:`commonupgrade`, the function :func:`oracledb.init_oracle_client()` +*must* be called to enable the Thick mode. It can be called anywhere before +the first call to :func:`oracledb.connect()`, ``oracledb.Connection()``, or +``oracledb.SessionPool()``. If a connection or pool is created first in the +default Thin mode, then Thick mode cannot be enabled. See +:ref:`enablingthick` for more details. + +The requirement to call :func:`~oracledb.init_oracle_client()` means that +Oracle Client library loading is not automatically deferred until the driver +is first used, such as when a connection is opened. To emulate the cx_Oracle +behavior of deferring library loading until the creation of the first +connection (in the case when :func:`~oracledb.init_oracle_client()` is not +called), your application will need to explicitly defer calling +:func:`~oracledb.init_oracle_client()` as appropriate. + +In python-oracledb, :func:`~oracledb.init_oracle_client()` can be called +multiple times in a Python process as long as the arguments are the same. + +Note that on Linux and related operating systems, the +:func:`~oracledb.init_oracle_client()` parameter ``lib_dir`` should not be +passed. Instead, set the system library search path with ``ldconfig`` or +``LD_LIBRARY_PATH`` prior to running Python. + +Modernizing Code +---------------- + +Many significant new features have been added to python-oracledb. You may want +to take advantage of them when upgrading from cx_Oracle. See the rest of the +documentation, the :ref:`release notes `, and +:ref:`featuresummary`. + +The following points summarize some of the smaller changes that you may find +interesting: + +- The :meth:`oracledb.makedsn()` method for creating the ``dsn`` value has been + deprecated. New code should use keyword arguments when creating connections + or connection pools, or make use of a ``params`` object described below. - The requirement to call ``init_oracle_client()`` means that Oracle Client - library loading is not automatically deferred until the driver is first - used, such as when a connection is opened. The application must explicitly - manage this if deferral is required. +- A new optional parameter ``params`` of type :ref:`ConnectParams ` + can be used to encapsulate connection properties. Similarly a new optional + parameter ``params`` of type :ref:`PoolParams ` can be used to + encapsulate pool creation properties. See :ref:`usingconnparams` for more + information. - In python-oracledb, ``init_oracle_client()`` can be called multiple times in - a Python process as long as the arguments are the same. +- The use of the class constructor method ``oracledb.Connection()`` to create + connections is no longer recommended for creating connections. Use + :func:`~oracledb.connect()` instead. - Note that on Linux and related operating systems, the - ``init_oracle_client()`` parameter ``lib_dir`` should not be - passed. Instead, set the system library search path with ``ldconfig`` or - ``LD_LIBRARY_PATH`` prior to running Python. +- The new method signature of :attr:`Connection.outputtypehandler` is + ``handler(cursor, metadata)``. The old signature ``handler(cursor, name, + default_type, length, precision, scale)`` was deprecated in python-oracledb + 1.4 but will still work and will be removed in a future version. -2. Replace all usages of the deprecated Advanced Queuing API with the new API - originally introduced in cx_Oracle 7.2, see :ref:`aqusermanual`. +- The attribute :attr:`Connection.maxBytesPerCharacter` is deprecated. This + will return a constant value of *4* since encodings are always UTF-8. -3. Review error handling improvements. See :ref:`errorhandling`. +- In python-oracledb, the name of the size argument of + :meth:`Cursor.fetchmany()` is ``size``. This change was done to comply with + `PEP 249 `_. The previous keyword + argument name, ``numRows`` is deprecated. Code to Aid the Upgrade to python-oracledb ------------------------------------------ @@ -694,8 +511,8 @@ Toggling between Drivers The sample `oracledb_upgrade.py `__ shows a way to toggle applications between cx_Oracle and the two python-oracledb modes. Note this script cannot -map some functionality such as :ref:`obsolete cx_Oracle ` -features or error message changes. +map some functionality such as obsolete cx_Oracle features or error message +changes. An example application showing this module in use is: @@ -724,7 +541,7 @@ You can then choose what mode is in use by setting the environment variable export ORA_PYTHON_DRIVER_TYPE=thin python test.py -Output shows the python-oracledb Thin mode was used:: +Output shows that python-oracledb Thin mode was used:: python-oracledb thn : 3.0.0 @@ -753,165 +570,3 @@ similar to: Another method that can be used to check which driver is in use is to query the view V$SESSION_CONNECT_INFO, see :ref:`vsessconinfo`. - -.. _frameworks: - -Python Frameworks, SQL Generators, and ORMs -------------------------------------------- - -Python-oracledb's Thin and :ref:`Thick ` modes cover the feature -needs of frameworks that depend upon the Python Database API. - -For versions of SQLAlchemy, Django, Superset, other frameworks, -object-relational mappers (ORMs), and libraries that do not have native support -for python-oracledb, you can add code like this to use python-oracledb instead -of cx_Oracle: - -.. code-block:: python - - import sys - import oracledb - oracledb.version = "8.3.0" - sys.modules["cx_Oracle"] = oracledb - -.. note:: - - This must occur before any import of cx_Oracle by your code or the library. - -To use Thick mode, for example if you need to connect to Oracle Database 11gR2, -also add a call to :meth:`oracledb.init_oracle_client()` with the appropriate -parameters for your environment, see :ref:`enablingthick`. - -SQLAlchemy 2 and Django 5 have native support for python-oracledb so the above -code snippet is not needed in those versions. - -Connecting with SQLAlchemy -++++++++++++++++++++++++++ - -**SQLAlchemy 1.4** - -.. code-block:: python - - # Using python-oracledb in SQLAlchemy 1.4 - - import os - import getpass - import oracledb - from sqlalchemy import create_engine - from sqlalchemy import text - - import sys - oracledb.version = "8.3.0" - sys.modules["cx_Oracle"] = oracledb - - # Uncomment to use python-oracledb Thick mode - # Review the doc for the appropriate parameters - #oracledb.init_oracle_client() - - un = os.environ.get("PYTHON_USERNAME") - cs = os.environ.get("PYTHON_CONNECTSTRING") - pw = getpass.getpass(f'Enter password for {un}@{cs}: ') - - # Note the first argument is different for SQLAlchemy 1.4 and 2 - engine = create_engine('oracle://@', - connect_args={ - # Pass any python-oracledb connect() parameters - "user": un, - "password": pw, - "dsn": cs - } - ) - - with engine.connect() as connection: - print(connection.scalar(text( - """select unique client_driver - from v$session_connect_info - where sid = sys_context('userenv', 'sid')"""))) - - -Note that the ``create_engine()`` argument driver declaration uses -``oracle://`` for SQLAlchemy 1.4 and ``oracle+oracledb://`` for SQLAlchemy 2. - -The ``connect_args`` dictionary can use any appropriate -:meth:`oracledb.connect()` parameter. - -**SQLAlchemy 2** - -.. code-block:: python - - # Using python-oracledb in SQLAlchemy 2 - - import os - import getpass - import oracledb - from sqlalchemy import create_engine - from sqlalchemy import text - - # Uncomment to use python-oracledb Thick mode - # Review the doc for the appropriate parameters - #oracledb.init_oracle_client() - - un = os.environ.get("PYTHON_USERNAME") - cs = os.environ.get("PYTHON_CONNECTSTRING") - pw = getpass.getpass(f'Enter password for {un}@{cs}: ') - - # Note the first argument is different for SQLAlchemy 1.4 and 2 - engine = create_engine('oracle+oracledb://@', - connect_args={ - # Pass any python-oracledb connect() parameters - "user": un, - "password": pw, - "dsn": cs - } - ) - - with engine.connect() as connection: - print(connection.scalar(text( - """select unique client_driver - from v$session_connect_info - where sid = sys_context('userenv', 'sid')"""))) - - -Note that the ``create_engine()`` argument driver declaration uses -``oracle://`` for SQLAlchemy 1.4 and ``oracle+oracledb://`` for SQLAlchemy 2. - -The ``connect_args`` dictionary can use any appropriate -:meth:`oracledb.connect()` parameter. - -**SQLAlchemy Connection Pools** - -Most multi-user applications should use a :ref:`connection pool `. -The python-oracledb pool is preferred because of its high availability support. -For example: - -.. code-block:: python - - # Using python-oracledb in SQLAlchemy 2 - - import os, platform - import getpass - 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 doc for the appropriate parameters - #oracledb.init_oracle_client() - - un = os.environ.get("PYTHON_USERNAME") - cs = os.environ.get("PYTHON_CONNECTSTRING") - pw = getpass.getpass(f'Enter password for {un}@{cs}: ') - - pool = oracledb.create_pool(user=un, password=pw, dsn=cs, - min=4, max=4, increment=0) - engine = create_engine("oracle+oracledb://", creator=pool.acquire, poolclass=NullPool) - - with engine.connect() as connection: - print(connection.scalar(text("""select unique client_driver - from v$session_connect_info - where sid = sys_context('userenv', 'sid')"""))) - - -You can also use python-oracledb connection pooling with SQLAlchemy 1.4. Use -the appropriate name mapping code and first argument to ``create_engine()``. diff --git a/doc/src/user_guide/appendix_d.rst b/doc/src/user_guide/appendix_d.rst new file mode 100644 index 00000000..e2172f3c --- /dev/null +++ b/doc/src/user_guide/appendix_d.rst @@ -0,0 +1,296 @@ +.. _frameworks: + +.. currentmodule:: oracledb + +******************************************************* +Appendix D: Python Frameworks, SQL Generators, and ORMs +******************************************************* + +Python-oracledb's Thin and :ref:`Thick ` modes cover the feature +needs of frameworks that depend upon the Python Database API. + +Using python-oracledb with Data Frame Libraries +=============================================== + +Python-oracledb can fetch directly to data frames that expose an Apache Arrow +PyCapsule interface. This is an efficient way to work with data using Python +libraries such as `Apache PyArrow +`__, `Pandas +`__, `Polars `__, `NumPy +`__, `PyTorch `__, or to write files +in `Apache Parquet `__ format. + +See :ref:`dataframeformat` for more information. + +.. _flask: + +Connecting with Flask +===================== + +The Flask web application framework works well with python-oracledb, either +directly or by using a library such as :ref:`SQLAlchemy `. + +Examples using python-oracledb directly are available in `connection_pool.py +`__, `drcp_pool.py `__, and `session_callback.py +`__. + +.. _sqlalchemy: + +Connecting with SQLAlchemy +========================== + +`SQLAlchemy `__, and libraries such as `Pandas +`__ that internally use SQLAlchemy, can connect +easily in python-oracledb as shown in this section. + +Also, see `SQLAlchemy documentation on connecting `__ and +`SQLAlchemy general documentation about Oracle Database +`__. + +Connecting with SQLAlchemy 2 +---------------------------- + +SQLAlchemy 2 supports python-oracledb directly. + +Standalone Connections in SQLAlchemy +++++++++++++++++++++++++++++++++++++ + +An example of creating a standalone connection in SQLAlchemy 2 is: + +.. code-block:: python + + # Using python-oracledb in SQLAlchemy 2 + + import os + import getpass + import oracledb + from sqlalchemy import create_engine + from sqlalchemy import text + + # Uncomment to use python-oracledb Thick mode + # Review the doc for the appropriate parameters + #oracledb.init_oracle_client() + + un = os.environ.get("PYTHON_USERNAME") + cs = os.environ.get("PYTHON_CONNECTSTRING") + pw = getpass.getpass(f'Enter password for {un}@{cs}: ') + + # Note the first argument is different for SQLAlchemy 1.4 and 2 + engine = create_engine('oracle+oracledb://@', + connect_args={ + # Pass any python-oracledb connect() parameters + "user": un, + "password": pw, + "dsn": cs + } + ) + + with engine.connect() as connection: + print(connection.scalar(text( + """select unique client_driver + from v$session_connect_info + where sid = sys_context('userenv', 'sid')"""))) + + +Note that the ``create_engine()`` argument driver declaration uses +``oracle+oracledb://`` for SQLAlchemy 2 but ``oracle://`` for SQLAlchemy 1.4. + +The ``connect_args`` dictionary can use any appropriate +:meth:`oracledb.connect()` parameter. + +.. _sqlalchemy2conpool: + +Pooled Connections in SQLAlchemy +++++++++++++++++++++++++++++++++ + +Most multi-user applications should use a :ref:`connection pool `. +The python-oracledb pool is preferred because of its high availability +support. Some single-user applications may also benfit from these availability +features. + +To use a python-oracledb connection pool in SQLAlchemy: + +.. code-block:: python + + # Using python-oracledb in SQLAlchemy 2 + + import os, platform + import getpass + 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 doc for the appropriate parameters + #oracledb.init_oracle_client() + + un = os.environ.get("PYTHON_USERNAME") + cs = os.environ.get("PYTHON_CONNECTSTRING") + pw = getpass.getpass(f'Enter password for {un}@{cs}: ') + + pool = oracledb.create_pool(user=un, password=pw, dsn=cs, + min=4, max=4, increment=0) + engine = create_engine("oracle+oracledb://", creator=pool.acquire, poolclass=NullPool) + + with engine.connect() as connection: + print(connection.scalar(text("""select unique client_driver + from v$session_connect_info + where sid = sys_context('userenv', 'sid')"""))) + + +.. _sqlalchemy1: + +Connecting with SQLAlchemy 1.4 +------------------------------ + +SQLAlchemy 1.4 can use python-oracledb with the help of the module name mapping +code shown in :ref:`boilerplatemapping`. An example is: + +.. code-block:: python + + # Using python-oracledb in SQLAlchemy 1.4 + + import os + import getpass + import oracledb + from sqlalchemy import create_engine + from sqlalchemy import text + + import sys + oracledb.version = "8.3.0" + sys.modules["cx_Oracle"] = oracledb + + # Uncomment to use python-oracledb Thick mode + # Review the doc for the appropriate parameters + #oracledb.init_oracle_client() + + un = os.environ.get("PYTHON_USERNAME") + cs = os.environ.get("PYTHON_CONNECTSTRING") + pw = getpass.getpass(f'Enter password for {un}@{cs}: ') + + # Note the first argument is different for SQLAlchemy 1.4 and 2 + engine = create_engine('oracle://@', + connect_args={ + # Pass any python-oracledb connect() parameters + "user": un, + "password": pw, + "dsn": cs + } + ) + + with engine.connect() as connection: + print(connection.scalar(text( + """select unique client_driver + from v$session_connect_info + where sid = sys_context('userenv', 'sid')"""))) + + +Note that the ``create_engine()`` argument driver declaration uses +``oracle://`` for SQLAlchemy 1.4 but ``oracle+oracledb://`` for SQLAlchemy 2. + +The ``connect_args`` dictionary can use any appropriate +:meth:`oracledb.connect()` parameter. + +You can also use python-oracledb connection pooling with SQLAlchemy 1.4. This +is similar to :ref:`pooled connections in SQLAlchemy 2 ` +but use the appropriate :ref:`name mapping code ` and first +argument to ``create_engine()``. + +.. _django: + +Connecting with Django +====================== + +Django 5 supports python-oracledb directly. Earlier versions should use +:ref:`name mapping code `. + +See `Django 5.2 documentation for Oracle Database +`__. + +Standalone Connections +---------------------- + +To connect in Django 5, an example settings.py file is: + +.. code-block:: python + + DATABASES = { + "default": { + "ENGINE": "django.db.backends.oracle", + "NAME": "example.com:1521/orclpdb", + "USER": "hr", + "PASSWORD": "the-hr-password" + } + } + +Pooled Connections +------------------ + +Django 5.2 supports python-oracledb :ref:`connection pools `. +Most multi-user applications should use a connection pool. The python-oracledb +pool is preferred because of its high availability support. Some single-user +applications may also benfit from these availability features. + +.. _djangoconpool: + +To use a connection pool in Django 5.2, an example settings.py file is: + +.. code-block:: python + + DATABASES = { + "default": { + "ENGINE": "django.db.backends.oracle", + "NAME": "example.com:1521/orclpdb", + "USER": "hr", + "PASSWORD": "the-hr-password" + "OPTIONS": { + "pool": { + "min": 0, + "max": 4, + "increment": 1, + # Additional python-oracledb pool parameters can be added here + } + } + }, + } + +.. _boilerplatemapping: + +Older Versions of Python Frameworks, SQL Generators, and ORMs +============================================================= + +For versions of SQLAlchemy, Django, Superset, other frameworks, +object-relational mappers (ORMs), and libraries that support the obsolete +cx_Oracle driver but do not have native support for python-oracledb, you can +add code like this to use python-oracledb: + +.. code-block:: python + + import sys + import oracledb + oracledb.version = "8.3.0" + sys.modules["cx_Oracle"] = oracledb + +.. note:: + + This must occur before any import of cx_Oracle by your code or the library. + +See :ref:`sqlalchemy1` for an example. + +To use Thick mode, for example, if you need to connect to Oracle Database +11gR2, add a call to :meth:`oracledb.init_oracle_client()` with the appropriate +parameters for your environment, see :ref:`enablingthick`. + +SQLAlchemy 2 and Django 5 have native support for python-oracledb so the above +code snippet is not needed in those versions. Check your preferred library for +which Oracle Database driver it requires. + +For details on using Superset with python-oracledb, refer to the blog post +`Steps to use Apache Superset and Oracle Database +`__. diff --git a/doc/src/user_guide/aq.rst b/doc/src/user_guide/aq.rst index 5d06e7fc..1bd838e6 100644 --- a/doc/src/user_guide/aq.rst +++ b/doc/src/user_guide/aq.rst @@ -1,5 +1,7 @@ .. _aqusermanual: +.. currentmodule:: oracledb + ************************************************************ Using Oracle Transactional Event Queues and Advanced Queuing ************************************************************ @@ -15,44 +17,58 @@ receiving of various payloads, such as RAW values, JSON, JMS, and objects. Transactional Event Queues use a highly optimized implementation of Advanced Queuing. They were previously called AQ Sharded Queues. +.. note:: + + Transactional Event Queues are only supported in python-oracledb + :ref:`Thick mode `. Python-oracledb API calls are the same for Transactional Event Queues and Classic Queues, however there are differences in support for some payload -types. - -**Classic Queue Support** - -- RAW, named Oracle objects, and JMS payloads are supported. +types which are detailed below. + +.. list-table-with-summary:: Payload Differences Between Classic Queues and Transactional Event Queues + :header-rows: 1 + :class: wy-table-responsive + :widths: 10 20 20 + :summary: The first column displays the payload type. The second column displays whether the payload type is supported in Classic Queues. The third column displays whether the payload type is supported in Transactional Event Queues. + + * - Payload Type + - Classic Queues + - Transactional Event Queues + * - RAW + - Supported + - Supported for single and array message enqueuing and dequeuing when using Oracle Client 19c (or later) and connected to Oracle Database 19c (or later). + * - Named Oracle Objects + - Supported + - Supported for single and array message enqueuing and dequeuing when using Oracle Client 19c (or later) and connected to Oracle Database 19c (or later). + * - JSON + - Supported when using Oracle Database 21c (or later). In python-oracle Thick mode, Oracle Client libraries 21c (or later) are also needed. + + Buffered messaging using the :data:`~oracledb.MSG_BUFFERED` delivery mode is not supported for JSON payloads. + - Supported for single message enqueuing and dequeuing when using Oracle Client libraries 21c (or later) and Oracle Database 21c (or later). + + Array enqueuing and dequeuing is not supported for JSON payloads. + + Buffered messaging using the :data:`~oracledb.MSG_BUFFERED` delivery mode is not supported for JSON payloads. + * - JMS + - Supported + - Supported for single and array message enqueuing and dequeuing when using Oracle Client 19 (or later) and Oracle Database version 23 (or later). + +**Usage Notes** + +For classic queues, the use of :data:`oracledb.ENQ_IMMEDIATE` with bulk +enqueuing, and JMS payloads are only supported in python-oracledb +:ref:`Thick mode `. -- The JSON payload requires Oracle Client libraries 21c (or later) and Oracle - Database 21c (or later). +Transactional Event Queues do not support :attr:`EnqOptions.transformation`, +:attr:`DeqOptions.transformation`, or :ref:`Recipient Lists `. -JSON and JMS payloads, array message queuing and dequeuing operations, and -:ref:`Recipient Lists ` are only supported in python-oracledb -:ref:`Thick mode `. +The delivery mode :data:`oracledb.MSG_BUFFERED` is not supported for bulk array +operations in python-oracledb Thick mode. There are examples of AQ Classic Queues in the `GitHub samples `__ directory. -**Transactional Event Queue Support** - -Transactional Event Queues are only supported in python-oracledb :ref:`Thick -mode `. - -- RAW and named Oracle object payloads are supported for single and array - message enqueuing and dequeuing when using Oracle Client 19c (or later) and - connected to Oracle Database 19c (or later). - -- JMS payloads are supported for single and array message enqueuing and - dequeuing when using Oracle Client 19c (or later) and Oracle Database 23ai. - -- JSON payloads are supported for single message enqueuing and dequeuing when - using Oracle Client libraries 21c (or later) and Oracle Database 21c (or - later). Array enqueuing and dequeuing is not supported for JSON payloads. - -Transactional Event Queues do not support :attr:`EnqOptions.transformation`, -:attr:`DeqOptions.transformation`, or :ref:`Recipient Lists `. - Creating a Queue ================ @@ -113,14 +129,15 @@ queue can then be used for enqueuing, dequeuing, or for both. **Enqueuing RAW Payloads** You can connect to the database and get the queue that was created with RAW -payload type by using: +payload type by using :meth:`Connection.queue()` or +:meth:`AsyncConnection.queue()`. For example: .. code-block:: python queue = connection.queue("DEMO_RAW_QUEUE") -Now messages can be queued using :meth:`~Queue.enqone()`. To send three -messages: +Now messages can be queued using :meth:`Queue.enqone()` or +:meth:`AsyncQueue.enqone()`. For example, to send three messages: .. code-block:: python @@ -137,21 +154,23 @@ Since the queue is a RAW queue, strings are internally encoded to bytes using `encode() `__ before being enqueued. -The use of :meth:`~Connection.commit()` allows messages to be sent only when -any database transaction related to them is committed. This default behavior -can be altered, see :ref:`aqoptions`. +The use of :meth:`Connection.commit()` or :meth:`AsyncConnection.commit()` +allows messages to be sent only when any database transaction related to them +is committed. This default behavior can be altered, see :ref:`aqoptions`. **Enqueuing JSON Payloads** You can connect to the database and get the queue that was created with JSON -payload type by using: +payload type by using :meth:`Connection.queue()` or +:meth:`AsyncConnection.queue()`. For example: .. code-block:: python # The argument "JSON" indicates the queue is of JSON payload type queue = connection.queue("DEMO_JSON_QUEUE", "JSON") -Now the message can be enqueued using :meth:`~Queue.enqone()`. +Now the message can be enqueued using :meth:`Queue.enqone()` or +:meth:`AsyncQueue.enqone()`, for example: .. code-block:: python @@ -173,13 +192,15 @@ Now the message can be enqueued using :meth:`~Queue.enqone()`. Dequeuing Messages ================== -Dequeuing is performed similarly. To dequeue a message call the method -:meth:`~Queue.deqone()` as shown in the examples below. This returns a +Dequeuing is performed similarly as shown in the examples below. This returns a :ref:`MessageProperties ` object containing the message payload and related attributes. **Dequeuing RAW Payloads** +To dequeue a message, call the method :meth:`Queue.deqone()` or +:meth:`AsyncQueue.deqone()`. For example: + .. code-block:: python queue = connection.queue("DEMO_RAW_QUEUE") @@ -191,9 +212,9 @@ Note that if the message is expected to be a string, the bytes must be decoded by the application using `decode() `__, as shown. -If there are no messages in the queue, :meth:`~Queue.deqone()` will wait for -one to be enqueued. This default behavior can be altered, see -:ref:`aqoptions`. +If there are no messages in the queue, :meth:`Queue.deqone()` or +:meth:`AsyncQueue.deqone()` will wait for one to be enqueued. This default +behavior can be altered, see :ref:`aqoptions`. Various :ref:`message properties ` can be accessed. For example to show the :attr:`~MessageProperties.msgid` of a dequeued message: @@ -204,6 +225,9 @@ to show the :attr:`~MessageProperties.msgid` of a dequeued message: **Dequeuing JSON Payloads** +To dequeue a message, call the method :meth:`Queue.deqone()` or +:meth:`AsyncQueue.deqone()`, for example: + .. code-block:: python queue = connection.queue("DEMO_JSON_QUEUE", "JSON") @@ -236,7 +260,8 @@ And a queue that accepts this type: end; / -You can enqueue messages: +You can enqueue messages using :meth:`Queue.enqone()` or +:meth:`AsyncQueue.enqone()`, for example: .. code-block:: python @@ -251,7 +276,8 @@ You can enqueue messages: queue.enqone(connection.msgproperties(payload=book)) connection.commit() -Dequeuing can be done like this: +Dequeuing can be done with :meth:`Queue.deqone()` or +:meth:`AsyncQueue.deqone()`, for example: .. code-block:: python @@ -333,15 +359,17 @@ expiration of 60 seconds on a message: This means that if no dequeue operation occurs within 60 seconds then the message will be dropped from the queue. +.. _bulkenqdeq: Bulk Enqueue and Dequeue ======================== -The :meth:`~Queue.enqmany()` and :meth:`~Queue.deqmany()` methods can be used -for efficient bulk message handling. +The :meth:`Queue.enqmany()`, :meth:`Queue.deqmany()`, +:meth:`AsyncQueue.enqmany()`, and :meth:`AsyncQueue.deqmany()` methods can be +used for efficient bulk message handling. -The :meth:`~Queue.enqmany()` method is similar to :meth:`~Queue.enqone()` but -accepts an array of messages: +The bulk enqmany methods are similar to single message enqueue methods but +accept an array of messages, for example: .. code-block:: python @@ -356,16 +384,18 @@ accepts an array of messages: .. warning:: - Calling :meth:`~Queue.enqmany()` in parallel on different connections - acquired from the same pool may fail due to Oracle bug 29928074. To avoid - this, ensure that :meth:`~Queue.enqmany()` is not run in parallel, use - standalone connections or connections from different pools, or make - multiple calls to :meth:`~Queue.enqone()` instead. The function - :meth:`~Queue.deqmany()` call is not affected. - -To dequeue multiple messages at one time, use :meth:`~Queue.deqmany()`. This -takes an argument specifying the maximum number of messages to dequeue at one -time: + In python-oracledb Thick mode using Oracle Client libraries prior to 21c, + calling :meth:`Queue.enqmany()` in parallel on different connections + acquired from the same connection pool may fail due to Oracle + bug 29928074. To avoid this, do one of: upgrade the client libraries, + ensure that :meth:`Queue.enqmany()` is not run in parallel, use standalone + connections or connections from different pools, or make multiple calls to + :meth:`Queue.enqone()`. The function :meth:`Queue.deqmany()` call is not + affected. + +To dequeue multiple messages at one time, use :meth:`Queue.deqmany()` or +:meth:`AsyncQueue.deqmany()`. These take an argument specifying the maximum +number of messages to dequeue at one time, for example: .. code-block:: python diff --git a/doc/src/user_guide/asyncio.rst b/doc/src/user_guide/asyncio.rst index 76c220c8..1bb6633c 100644 --- a/doc/src/user_guide/asyncio.rst +++ b/doc/src/user_guide/asyncio.rst @@ -1,5 +1,7 @@ .. _asyncio: +.. currentmodule:: oracledb + ************************************************** Concurrent Programming with asyncio and Pipelining ************************************************** @@ -24,14 +26,21 @@ useful tips. The python-oracledb asynchronous API is a part of the standard python-oracledb module. All the synchronous methods that require a round-trip to the database -now have corresponding asynchronous counterparts. You can choose whether to -use the synchronous API or the asynchronous API in your code. It is -recommended to *not* use both at the same time in your application. +have corresponding asynchronous counterparts. You can choose whether to use the +synchronous API or the asynchronous API in your code. It is recommended to +*not* use both at the same time in your application. The asynchronous API classes are :ref:`AsyncConnection `, :ref:`AsyncConnectionPool `, :ref:`AsyncCursor `, and :ref:`AsyncLOB `. +Unlike their synchronous counterparts, asynchronous connections and cursors are +not automatically closed at the end of scope. These asynchronous resources +should either be explicitly closed, or have been initially created via a +`context manager +`__ +``with`` block. + .. note:: Concurrent programming with asyncio is only supported in @@ -105,6 +114,8 @@ when they are no longer needed, for example: cursor.close() await connection.close() +Note asynchronous connections are not automatically closed at the end of +scope. This is different to synchronous connection behavior. .. _asyncconnpool: @@ -165,7 +176,12 @@ executed using the asynchronous methods :meth:`AsyncCursor.execute()` or :meth:`AsyncCursor.executemany()`. Rows can be iterated over, or fetched using one of the methods :meth:`AsyncCursor.fetchone()`, :meth:`AsyncCursor.fetchone()`, :meth:`AsyncCursor.fetchmany()`, or -:meth:`AsyncCursor.fetchall()`. +:meth:`AsyncCursor.fetchall()`. Note that explicitly opened asynchronous +cursors are not automatically closed at the end of scope. This is different to +synchronous behavior. Asynchronous cursors should either be explicitly closed, +or have been initially created via a `context manager +`__ +``with`` block. You can also use shortcut methods on the :ref:`asyncconnobj` object such as :meth:`AsyncConnection.execute()` or @@ -297,6 +313,40 @@ is recommended to use autocommit mode only for the last DML statement in the sequence of operations. Unnecessarily committing causes extra database load, and can destroy transactional consistency. +.. _sessionlesstxnasync: + +Managing Sessionless Transactions Using Asynchronous Methods +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +When :meth:`AsyncConnection.begin_sessionless_transaction()` is executed using +a user-chosen or python-oracledb generated transaction identifier, a +sessionless transaction is started. Once started, all the SQL statements are +executed as a part of that sessionless transaction. Use +:meth:`AsyncConnection.suspend_sessionless_transaction()` to explicitly +suspend an active transaction once the database operations have been executed. +This releases the connection which can be used by another user while the +transaction remains open and can be resumed later by a connection using +:meth:`AsyncConnection.resume_sessionless_transaction()`. The methods +:meth:`AsyncConnection.commit()` and :meth:`AsyncConnection.rollback()` can be +used to explicitly commit or roll back a transaction. For example: + +.. code-block:: python + + async def main(): + txn_id = b"new_sessionless_txn" + # Begin and suspend a sessionless transaction in a connection + async with oracledb.connect_async(user="hr", password=userpwd, + dsn="localhost/orclpdb") as connection1: + await connection1.begin_sessionless_transaction(transaction_id=txn_id, timeout=120) + await connection1.execute("INSERT INTO mytab (name) VALUES ('John')") + await connection1.suspend_sessionless_transaction() + + # Resume the sessionless transaction in another connection + async with oracledb.connect_async(user="hr", password=userpwd, + dsn="localhost/orclpdb") as connection2: + await connection2.resume_sessionless_transaction(transaction_id=txn_id) + await connection2.commit() + .. _pipelining: Pipelining Database Operations @@ -331,7 +381,8 @@ about Oracle Database Pipelining. .. note:: - True pipelining only occurs when you are connected to Oracle Database 23ai. + True pipelining only occurs when you are connected to Oracle Database + version 23, or later. When you connect to an older database, operations are sequentially executed by python-oracledb. Each operation concludes before the next is @@ -395,7 +446,8 @@ To limit the time for a pipeline, use an `asyncio timeout from Python 3.11. To tune fetching of rows with :meth:`Pipeline.add_fetchall()`, set -:attr:`defaults.arraysize` or pass the ``arraysize`` parameter. +:attr:`oracledb.defaults.arraysize ` or pass the +``arraysize`` parameter. Pipelining Examples +++++++++++++++++++ diff --git a/doc/src/user_guide/authentication_methods.rst b/doc/src/user_guide/authentication_methods.rst new file mode 100644 index 00000000..17c76a4d --- /dev/null +++ b/doc/src/user_guide/authentication_methods.rst @@ -0,0 +1,1583 @@ +.. _authenticationmethods: + +.. currentmodule:: oracledb + +********************** +Authentication Options +********************** + +Authentication allows only authorized users to access Oracle Database after +successful verification of their identity. This section details the various +Oracle Database authentication options supported in python-oracledb. + +The Oracle Client libraries used by python-oracledb Thick mode may support +additional authentication options that are configured independently of the +driver. + +.. _dbauthentication: + +Database Authentication +======================= + +Database Authentication is the most basic authentication method that allows +users to connect to Oracle Database by using a valid database username and +their associated password. Oracle Database verifies the username and password +specified in the python-oracledb connection method with the information stored +in the database. See `Database Authentication of Users `__ +for more information. + +:ref:`Standalone connections ` and +:ref:`pooled connections ` can be created in python-oracledb Thin +and Thick modes using database authentication. This can be done by specifying +the database username and the associated password in the ``user`` and +``password`` parameters of :meth:`oracledb.connect()`, +:meth:`oracledb.create_pool()`, :meth:`oracledb.connect_async()`, or +:meth:`oracledb.create_pool_async()`. An example is: + +.. code-block:: python + + import oracledb + import getpass + + userpwd = getpass.getpass("Enter password: ") + + connection = oracledb.connect(user="hr", password=userpwd, + dsn="dbhost.example.com/orclpdb") + +.. _proxyauth: + +Proxy Authentication +==================== + +Proxy authentication allows a user (the "session user") to connect to Oracle +Database using the credentials of a "proxy user". Statements will run as the +session user. Proxy authentication is generally used in three-tier +applications where one user owns the schema while multiple end-users access +the data. For more information about proxy authentication, see the `Oracle +documentation `__. + +An alternative to using proxy users is to set +:attr:`Connection.client_identifier` after connecting and use its value in +statements and in the database, for example for :ref:`monitoring +`. + +The following proxy examples use these schemas. The ``mysessionuser`` schema +is granted access to use the password of ``myproxyuser``: + +.. code-block:: sql + + CREATE USER myproxyuser IDENTIFIED BY myproxyuserpw; + GRANT CREATE SESSION TO myproxyuser; + + CREATE USER mysessionuser IDENTIFIED BY itdoesntmatter; + GRANT CREATE SESSION TO mysessionuser; + + ALTER USER mysessionuser GRANT CONNECT THROUGH myproxyuser; + +After connecting to the database, the following query can be used to show the +session and proxy users: + +.. code-block:: sql + + SELECT SYS_CONTEXT('USERENV', 'PROXY_USER'), + SYS_CONTEXT('USERENV', 'SESSION_USER') + FROM DUAL; + +Standalone connection examples: + +.. code-block:: python + + # Basic Authentication without a proxy + connection = oracledb.connect(user="myproxyuser", password="myproxyuserpw", + dsn="dbhost.example.com/orclpdb") + # PROXY_USER: None + # SESSION_USER: MYPROXYUSER + + # Basic Authentication with a proxy + connection = oracledb.connect(user="myproxyuser[mysessionuser]", password="myproxyuserpw", + dsn="dbhost.example.com/orclpdb") + # PROXY_USER: MYPROXYUSER + # SESSION_USER: MYSESSIONUSER + +Pooled connection examples: + +.. code-block:: python + + # Basic Authentication without a proxy + pool = oracledb.create_pool(user="myproxyuser", password="myproxyuserpw", + dsn="dbhost.example.com/orclpdb") + connection = pool.acquire() + # PROXY_USER: None + # SESSION_USER: MYPROXYUSER + + # Basic Authentication with proxy + pool = oracledb.create_pool(user="myproxyuser[mysessionuser]", password="myproxyuserpw", + dsn="dbhost.example.com/orclpdb", + homogeneous=False) + + connection = pool.acquire() + # PROXY_USER: MYPROXYUSER + # SESSION_USER: MYSESSIONUSER + +Note the use of a :ref:`heterogeneous ` pool in the example +above. This is required in this scenario. + +.. _extauth: + +External Authentication +======================= + +Instead of storing the database username and password in Python scripts or +environment variables, database access can be authenticated by an outside +system. External Authentication allows applications to validate user access +with an external password store (such as an +:ref:`Oracle Wallet `), with the +:ref:`operating system `, or with an external authentication +service. + +.. note:: + + Connecting to Oracle Database using external authentication is only + supported in python-oracledb Thick mode. See :ref:`enablingthick`. + +.. _extauthwithwallet: + +Using an Oracle Wallet for External Authentication +-------------------------------------------------- + +The following steps give an overview of using an Oracle Wallet. Wallets should +be kept securely. Wallets can be managed with `Oracle Wallet Manager +`__. + +In this example the wallet is created for the ``myuser`` schema in the +directory ``/home/oracle/wallet_dir``. The ``mkstore`` command is available +from a full Oracle Client or Oracle Database installation. If you have been +given wallet by your DBA, skip to step 3. + +1. First create a new wallet as the ``oracle`` user:: + + mkstore -wrl "/home/oracle/wallet_dir" -create + + This will prompt for a new password for the wallet. + +2. Create the entry for the database user name and password that are currently + hardcoded in your Python scripts. Use either of the methods shown below. + They will prompt for the wallet password that was set in the first step. + + **Method 1 - Using an Easy Connect string**:: + + mkstore -wrl "/home/oracle/wallet_dir" -createCredential dbhost.example.com/orclpdb myuser myuserpw + + **Method 2 - Using a connect name identifier**:: + + mkstore -wrl "/home/oracle/wallet_dir" -createCredential mynetalias myuser myuserpw + + The alias key ``mynetalias`` immediately following the + ``-createCredential`` option will be the connect name to be used in Python + scripts. If your application connects with multiple different database + users, you could create a wallet entry with different connect names for + each. + + You can see the newly created credential with:: + + mkstore -wrl "/home/oracle/wallet_dir" -listCredential + +3. Skip this step if the wallet was created using an Easy Connect String. + Otherwise, add an entry in :ref:`tnsnames.ora ` for the + connect name as follows:: + + mynetalias = + (DESCRIPTION = + (ADDRESS = (PROTOCOL = TCP)(HOST = dbhost.example.com)(PORT = 1521)) + (CONNECT_DATA = + (SERVER = DEDICATED) + (SERVICE_NAME = orclpdb) + ) + ) + + The file uses the description for your existing database and sets the + connect name alias to ``mynetalias``, which is the identifier used when + adding the wallet entry. + +4. Add the following wallet location entry in the :ref:`sqlnet.ora + ` file, using the ``DIRECTORY`` you created the wallet in:: + + WALLET_LOCATION = + (SOURCE = + (METHOD = FILE) + (METHOD_DATA = + (DIRECTORY = /home/oracle/wallet_dir) + ) + ) + SQLNET.WALLET_OVERRIDE = TRUE + + Examine the Oracle documentation for full settings and values. + +5. Ensure the configuration files are in a default location or TNS_ADMIN is + set to the directory containing them. See :ref:`optnetfiles`. + +With an Oracle wallet configured, and readable by you, your scripts +can connect to Oracle Database with: + +- Standalone connections by setting the ``externalauth`` parameter to *True* + in :meth:`oracledb.connect()`: + + .. code-block:: python + + connection = oracledb.connect(externalauth=True, dsn="mynetalias") + +- Or pooled connections by setting the ``externalauth`` parameter to *True* + in :meth:`oracledb.create_pool()`. Additionally in python-oracledb Thick + mode, you must set the ``homogeneous`` parameter to *False* as shown below + since heterogeneous pools can only be used with external authentication: + + .. code-block:: python + + pool = oracledb.create_pool(externalauth=True, homogeneous=False, + dsn="mynetalias") + pool.acquire() + +The ``dsn`` used in :meth:`oracledb.connect()` and +:meth:`oracledb.create_pool()` must match the one used in the wallet. + +After connecting, the query:: + + SELECT SYS_CONTEXT('USERENV', 'SESSION_USER') FROM DUAL; + +will show:: + + MYUSER + +.. note:: + + Wallets are also used to configure Transport Layer Security (TLS) connections. + If you are using a wallet like this, you may need a database username and password + in :meth:`oracledb.connect()` and :meth:`oracledb.create_pool()` calls. + +**External Authentication and Proxy Authentication** + +The following examples show external wallet authentication combined with +:ref:`proxy authentication `. These examples use the wallet +configuration from above, with the addition of a grant to another user:: + + ALTER USER mysessionuser GRANT CONNECT THROUGH myuser; + +After connection, you can check who the session user is with: + +.. code-block:: sql + + SELECT SYS_CONTEXT('USERENV', 'PROXY_USER'), + SYS_CONTEXT('USERENV', 'SESSION_USER') + FROM DUAL; + +Standalone connection example: + +.. code-block:: python + + # External Authentication with proxy + connection = oracledb.connect(user="[mysessionuser]", dsn="mynetalias") + # PROXY_USER: MYUSER + # SESSION_USER: MYSESSIONUSER + +You can also set the ``externalauth`` parameter to *True* in standalone +connections: + +.. code-block:: python + + # External Authentication with proxy when externalauth is set to True + connection = oracledb.connect(user="[mysessionuser]", dsn="mynetalias", + externalauth=True) + # PROXY_USER: MYUSER + # SESSION_USER: MYSESSIONUSER + +A connection pool example is: + +.. code-block:: python + + # External Authentication with proxy + pool = oracledb.create_pool(externalauth=True, homogeneous=False, + dsn="mynetalias") + pool.acquire(user="[mysessionuser]") + # PROXY_USER: MYUSER + # SESSION_USER: MYSESSIONUSER + +The following usage is not supported: + +.. code-block:: python + + pool = oracledb.create_pool(user="[mysessionuser]", externalauth=True, + homogeneous=False, dsn="mynetalias") + pool.acquire() + +.. _opsysauth: + +Operating System Authentication +------------------------------- + +With `Operating System `__ authentication, Oracle allows +user authentication to be performed by the operating system. The following +steps give an overview of how to implement OS Authentication on Linux. + +1. Log in to your computer. The commands used in these steps assume the + operating system user name is "oracle". + +2. Log in to SQL*Plus as the SYSTEM user and verify the value for the + ``OS_AUTHENT_PREFIX`` parameter:: + + SQL> SHOW PARAMETER os_authent_prefix + + NAME TYPE VALUE + ------------------------------------ ----------- ------------------------------ + os_authent_prefix string ops$ + +3. Create an Oracle database user using the ``os_authent_prefix`` determined in + step 2, and the operating system user name: + + .. code-block:: sql + + CREATE USER ops$oracle IDENTIFIED EXTERNALLY; + GRANT CONNECT, RESOURCE TO ops$oracle; + +In Python, connect using the following code: + +.. code-block:: python + + connection = oracledb.connect(dsn="mynetalias") + +Your session user will be ``OPS$ORACLE``. + +If your database is not on the same computer as Python, you can perform testing +by setting the database configuration parameter ``remote_os_authent=true``. +Beware of security concerns because this is insecure. + +See `Oracle Database Security Guide +`__ for more information about +Operating System Authentication. + +.. _tokenauth: + +Token-Based Authentication +========================== + +Token-Based Authentication allows users to connect to a database by using an +encrypted authentication token without having to enter a database username and +password. The authentication token must be valid and not expired for the +connection to be successful. Users already connected will be able to continue +work after their token has expired but they will not be able to reconnect +without getting a new token. + +The two authentication methods supported by python-oracledb are +:ref:`Open Authorization (OAuth 2.0) ` and :ref:`Oracle +Cloud Infrastructure (OCI) Identity and Access Management (IAM) `. +These authentication methods can use Cloud Native Authentication with the +support of the Azure SDK or OCI SDK to generate access tokens and connect to +Oracle Database. Alternatively, these methods can use a Python script that +contains a class to generate access tokens to connect to Oracle Database. + +.. _iamauth: + +OCI IAM Token-Based Authentication +---------------------------------- + +Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) provides +its users with a centralized database authentication and authorization system. +Using this authentication method, users can use the database access token +issued by OCI IAM to authenticate to the Oracle Autonomous Database. Both Thin +and Thick modes of the python-oracledb driver support OCI IAM token-based +authentication. + +When using python-oracledb in Thick mode, Oracle Client libraries 19.14 (or +later), or 21.5 (or later) are needed. + +Standalone connections and pooled connections can be created in python-oracledb +Thick and Thin modes using OCI IAM token-based authentication. This can be done +by using a class like the sample :ref:`TokenHandlerIAM class ` or +by using python-oracledb's :ref:`OCI Cloud Native Authentication Plugin +(oci_tokens) `. Tokens can be specified using the +connection parameter introduced in python-oracledb 1.1. Users of earlier +python-oracledb versions can alternatively use :ref:`OCI IAM Token-Based +Authentication Connection Strings `. + +OCI IAM Token Generation and Extraction ++++++++++++++++++++++++++++++++++++++++ + +Authentication tokens can be generated using python-oracledb's +:ref:`oci_tokens ` plugin. + +Alternatively, authentication tokens can be generated through execution of an +Oracle Cloud Infrastructure command line interface (OCI-CLI) command :: + + oci iam db-token get + +On Linux, a folder ``.oci/db-token`` will be created in your home directory. +It will contain the token and private key files needed by python-oracledb. + +.. _iamhandler: + +**Example of Generating an IAM Token** + +Here, as an example, we are using a Python script to automate the process of +generating and reading OCI IAM tokens. + +.. code:: python + + import os + + import oracledb + + class TokenHandlerIAM: + + def __init__(self, + dir_name="dir_name", + command="oci iam db-token get"): + self.dir_name = dir_name + self.command = command + self.token = None + self.private_key = None + + def __call__(self, refresh): + if refresh: + if os.system(self.command) != 0: + raise Exception("token command failed!") + if self.token is None or refresh: + self.read_token_info() + return (self.token, self.private_key) + + def read_token_info(self): + token_file_name = os.path.join(self.dir_name, "token") + pkey_file_name = os.path.join(self.dir_name, "oci_db_key.pem") + with open(token_file_name) as f: + self.token = f.read().strip() + with open(pkey_file_name) as f: + if oracledb.is_thin_mode(): + self.private_key = f.read().strip() + else: + lines = [s for s in f.read().strip().split("\n") + if s not in ('-----BEGIN PRIVATE KEY-----', + '-----END PRIVATE KEY-----')] + self.private_key = "".join(lines) + +The TokenHandlerIAM class uses a callable to generate and read OCI IAM tokens. +When the callable in the TokenHandlerIAM class is invoked for the first time +to create a standalone connection or pool, the ``refresh`` parameter is +*False* which allows the callable to return a cached token, if desired. The +expiry date is then extracted from this token and compared with the current +date. If the token has not expired, then it will be used directly. If the token +has expired, the callable is invoked the second time with the ``refresh`` +parameter set to *True*. + +The TokenHandlerIAM class defined here is used in the examples shown in +:ref:`conncreationociiam`. + +.. _conncreationociiam: + +Connection Creation with OCI IAM Access Tokens +++++++++++++++++++++++++++++++++++++++++++++++ + +For OCI IAM Token-Based Authentication with a class such as the sample +:ref:`TokenHandlerIAM class `, the ``access_token`` connection +parameter must be specified. This parameter should be a 2-tuple (or a callable +that returns a 2-tuple) containing the token and private key. In the examples +used below, the ``access_token`` parameter is set to a callable. + +The examples used in the subsequent sections use the +:ref:`TokenHandlerIAM class ` to generate OCI IAM tokens to connect +to Oracle Autonomous Database with mutual TLS (mTLS). See :ref:`autonomousdb`. + +**Standalone Connections in Thin Mode Using OCI IAM Tokens** + +When using a class such as the :ref:`TokenHandlerIAM class ` to +generate OCI IAM tokens to connect to Oracle Autonomous Database in Thin mode, +you need to explicitly set the ``access_token`` parameter of +:func:`~oracledb.connect`, and also any desired ``config_dir``, +``wallet_location``, and ``wallet_password`` parameters. For example: + +.. code:: python + + connection = oracledb.connect( + access_token=TokenHandlerIAM(), + dsn=mydb_low, + config_dir="path_to_unzipped_wallet", + wallet_location="location_of_pem_file", + wallet_password=wp) + +**Connection Pools in Thin Mode Using OCI IAM Tokens** + +When using a class such as :ref:`TokenHandlerIAM class ` to +generate OCI IAM tokens to connect to Oracle Autonomous Database in Thin mode, +you need to explicitly set the ``access_token`` parameter of +:func:`~oracledb.create_pool`, and also any desired ``config_dir``, +``wallet_location``, and ``wallet_password`` parameters. The ``homogeneous`` +parameter must be *True* (its default value). For example: + +.. code:: python + + connection = oracledb.create_pool( + access_token=TokenHandlerIAM(), + homogeneous=True, # must always be True for connection pools + dsn=mydb_low, + config_dir="path_to_unzipped_wallet", + wallet_location="location_of_pem_file", + wallet_password=wp + min=1, max=5, increment=2) + +Note that the ``access_token`` parameter should be set to a callable. This is +useful when the connection pool needs to expand and create new connections but +the current token has expired. In such a case, the callable should return a +string specifying the new, valid access token. + +**Standalone Connections in Thick Mode Using OCI IAM Tokens** + +When using a class such as :ref:`TokenHandlerIAM class ` to +generate OCI IAM tokens to connect to Oracle Autonomous Database in Thick mode, +you need to explicitly set the ``access_token`` and ``externalAuth`` parameters +of :func:`~oracledb.connect`. For example: + +.. code:: python + + connection = oracledb.connect( + access_token=TokenHandlerIAM(), + externalauth=True, # must always be True in Thick mode + dsn=mydb_low) + +**Connection Pools in Thick Mode Using OCI IAM Tokens** + +When using a class such as :ref:`TokenHandlerIAM class ` to +generate OCI IAM tokens to connect to Oracle Autonomous Database in Thick mode, +you need to explicitly set the ``access_token`` and ``externalauth`` parameters +of :func:`oracledb.create_pool`. The ``homogeneous`` parameter must be *True* +(its default value). For example: + +.. code:: python + + pool = oracledb.create_pool( + access_token=TokenHandlerIAM(), + externalauth=True, # must always be True in Thick mode + homogeneous=True, # must always be True for connection pools + dsn=mydb_low, min=1, max=5, increment=2) + +Note that the ``access_token`` parameter should be set to a callable. This is +useful when the connection pool needs to expand and create new connections but +the current token has expired. In such a case, the callable should return a +string specifying the new, valid access token. + +.. _iamauthconnstr: + +OCI IAM Token-Based Authentication Connection Strings ++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The connection string used by python-oracledb can specify the directory where +the token and private key files are located. This syntax is usable with older +versions of python-oracledb. However, it is recommended to use connection +parameters introduced in python-oracledb 1.1 instead. See +:ref:`OCI IAM Token-Based Authentication`. + +.. note:: + + OCI IAM Token-Based Authentication Connection Strings is only supported in + python-oracledb Thick mode. See :ref:`enablingthick`. + +The Oracle Cloud Infrastructure command line interface (OCI-CLI) can be used +externally to get tokens and private keys from OCI IAM, for example with the +OCI-CLI ``oci iam db-token get`` command. + +The Oracle Net parameter ``TOKEN_AUTH`` must be set when you are using the +connection string syntax. Also, the ``PROTOCOL`` parameter must be ``tcps`` +and ``SSL_SERVER_DN_MATCH`` should be ``ON``. + +You can set ``TOKEN_AUTH=OCI_TOKEN`` in a ``sqlnet.ora`` file. Alternatively, +you can specify it in a :ref:`Connect Descriptor `, for example +when using a :ref:`tnsnames.ora ` file:: + + db_alias = + (DESCRIPTION = + (ADDRESS=(PROTOCOL=TCPS)(PORT=1522)(HOST=xxx.oraclecloud.com)) + (CONNECT_DATA=(SERVICE_NAME=xxx.adb.oraclecloud.com)) + (SECURITY = + (SSL_SERVER_CERT_DN="CN=xxx.oraclecloud.com, \ + O=Oracle Corporation,L=Redwood City,ST=California,C=US") + (TOKEN_AUTH=OCI_TOKEN) + ) + ) + +The default location for the token and private key is the same default location +that the OCI-CLI tool writes to. For example ``~/.oci/db-token/`` on Linux. + +If the token and private key files are not in the default location then their +directory must be specified with the ``TOKEN_LOCATION`` parameter in a +:ref:`sqlnet.ora ` file or in a :ref:`Connect Descriptor +`, for example when using a :ref:`tnsnames.ora ` +file:: + + db_alias = + (DESCRIPTION = + (ADDRESS=(PROTOCOL=TCPS)(PORT=1522)(HOST=xxx.oraclecloud.com)) + (CONNECT_DATA=(SERVICE_NAME=xxx.adb.oraclecloud.com)) + (SECURITY = + (SSL_SERVER_CERT_DN="CN=xxx.oraclecloud.com, \ + O=Oracle Corporation,L=Redwood City,ST=California,C=US") + (TOKEN_AUTH=OCI_TOKEN) + (TOKEN_LOCATION="/path/to/token/folder") + ) + ) + +The ``TOKEN_AUTH`` and ``TOKEN_LOCATION`` values in a connection string take +precedence over the ``sqlnet.ora`` settings. + +Standalone connection example: + +.. code-block:: python + + connection = oracledb.connect(dsn=db_alias, externalauth=True) + +Connection pool example: + +.. code-block:: python + + pool = oracledb.create_pool(dsn=db_alias, externalauth=True, + homogeneous=False, min=1, max=2, increment=1) + + connection = pool.acquire() + +.. _cloudnativeauthoci: + +OCI Cloud Native Authentication with the oci_tokens Plugin +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +With Cloud Native Authentication, python-oracledb's :ref:`oci_tokens +` plugin can automatically generate and refresh OCI +IAM tokens when required with the support of the `Oracle Cloud Infrastructure +(OCI) Software Development Kit (SDK) +`__. + +The :ref:`oci_tokens ` plugin can be imported +like: + +.. code-block:: python + + import oracledb.plugins.oci_tokens + +The plugin has a Python package dependency which needs to be installed +separately before the plugin can be used, see :ref:`ocitokenmodules`. + +The ``oci_tokens`` plugin defines and registers a :ref:`parameter hook +` function which uses the connection parameter +``extra_auth_params`` passed to :meth:`oracledb.connect()`, +:meth:`oracledb.create_pool()`, :meth:`oracledb.connect_async()`, or +:meth:`oracledb.create_pool_async()`. Using this parameter's values, the hook +function sets the ``access_token`` parameter of a :ref:`ConnectParams object +` to a callable which generates an OCI IAM token. Python-oracledb +then acquires and uses a token to transparently complete connection or pool +creation calls. + +For OCI Cloud Native Authentication connection and pool creation, the +``extra_auth_params`` parameter should be a dictionary with keys as shown in +the following table. + +.. list-table-with-summary:: OCI Cloud Native Authentication Configuration Keys + :header-rows: 1 + :class: wy-table-responsive + :widths: 10 25 15 + :name: _oci_configuration_parameters + :summary: The first column displays the name of the dictionary key. The second column displays its description. The third column displays whether the attribute is required or optional. + + * - Key + - Description + - Required or Optional + * - ``auth_type`` + - The authentication type. The value should be the string "ConfigFileAuthentication", "InstancePrincipal", "SecurityToken", "SecurityTokenSimple" or "SimpleAuthentication". + + With Configuration File Authentication, the location of a configuration file containing the necessary information must be provided. By default, this file is located at */home/username/.oci/config*, unless a custom location is specified during OCI IAM setup. + + With Instance Principal Authentication, OCI compute instances can be authorized to access services on Oracle Cloud such as Oracle Autonomous Database. Python-oracledb applications running on such a compute instance are automatically authenticated, eliminating the need to provide database user credentials. This authentication method will only work on compute instances where internal network endpoints are reachable. See :ref:`instanceprincipalauth`. + + With Security Token authentication or Session Token-based authentication, the authentication happens using *security_token_file* parameter present in the configuration file. By default, this file is located at */home/username/.oci/config*, unless a custom location is specified during OCI IAM setup. You also need to specify the *profile* which contains the *security_token_file* parameter. + + With Security Token Simple authentication or Session Token-based Simple authentication, the authentication happens using *security_token_file* parameter. The individual configuration parameters can be provided at runtime. + + With Simple Authentication, the individual configuration parameters can be provided at runtime. + + See `OCI SDK Authentication Methods `__ for more information. + - Required + * - ``user`` + - The Oracle Cloud Identifier (OCID) of the user invoking the API. For example, *ocid1.user.oc1..*. + + This parameter can be specified when the value of the ``auth_type`` key is "SimpleAuthentication". This is not required when ``auth_type`` is "SecurityToken" or "SecurityTokenSimple" + - Required + * - ``key_file`` + - The full path and filename of the private key. + + This parameter can be specified when the value of the ``auth_type`` key is "SimpleAuthentication". + - Required + * - ``fingerprint`` + - The fingerprint associated with the public key that has been added to this user. + + This parameter can be specified when the value of the ``auth_type`` key is "SimpleAuthentication". + - Required + * - ``tenancy`` + - The OCID of your tenancy. For example, *ocid1.tenancy.oc1..*. + + This parameter can be specified when the value of the ``auth_type`` key is "SimpleAuthentication". + - Required + * - ``region`` + - The Oracle Cloud Infrastructure region. For example, *ap-mumbai-1*. + + This parameter can be specified when the value of the ``auth_type`` key is "SimpleAuthentication". + - Required + * - ``profile`` + - The configuration profile name to load. + + Multiple profiles can be created, each with distinct values for necessary parameters. If not specified, the DEFAULT profile is used. + + This parameter can be specified when the value of the ``auth_type`` key is "SimpleAuthentication" or "ConfigFileAuthentication". If it is not specified when using "ConfigFileAuthentication", the default value is taken. + - Required + * - ``file_location`` + - The configuration file location. The default value is *~/.oci/config*. + + This parameter can be specified when the value of the ``auth_type`` key is "ConfigFileAuthentication". + - Optional + * - ``scope`` + - This parameter identifies all databases in the cloud tenancy of the authenticated user. The default value is *urn:oracle:db::id::**. + + A scope that authorizes access to all databases within a compartment has the format *urn:oracle:db::id::*, for example, urn:oracle:db::id::ocid1.compartment.oc1..xxxxxxxx. + + A scope that authorizes access to a single database within a compartment has the format *urn:oracle:db::id::::*, for example, urn:oracle:db::id::ocid1.compartment.oc1..xxxxxx::ocid1.autonomousdatabase.oc1.phx.xxxxxx. + + This parameter can be specified when the value of the ``auth_type`` key is "SimpleAuthentication", "ConfigFileAuthentication", or "InstancePrincipal". + - Optional + +All keys and values other than ``auth_type`` are used by the `OCI SDK +`__ API +calls in the plugin. The plugin implementation can be seen in +`plugins/oci_tokens.py +`__. + +For information on the OCI specific configuration parameters, see `OCI SDK +`__. + +The examples in the subsequent sections use the :ref:`oci_tokens +` plugin to generate OCI IAM tokens to connect to +Oracle Autonomous Database with mutual TLS (mTLS). See :ref:`autonomousdb`. + +**Standalone Connections in Thin Mode Using OCI IAM Tokens** + +When using the :ref:`oci_tokens ` plugin to generate +OCI IAM tokens to connect to Oracle Autonomous Database in Thin mode, you need +to explicitly set the ``extra_auth_params`` parameter of +:func:`~oracledb.connect`, and also any desired ``config_dir``, +``wallet_location``, and ``wallet_password`` parameters. For example: + +.. code:: python + + import oracledb.plugins.oci_tokens + + token_based_auth = { # OCI specific configuration + "auth_type": "ConfigFileAuthentication", # parameters to be set when using + "profile": , # the oci_tokens plugin with + "file_location": , # configuration file authentication + } + + connection = oracledb.connect( + dsn=mydb_low, + config_dir="path_to_unzipped_wallet", + wallet_location="location_of_pem_file", + wallet_password=wp, + extra_auth_params=token_based_auth) + +**Connection Pools in Thin Mode Using OCI IAM Tokens** + +When using the :ref:`oci_tokens ` plugin to generate +OCI IAM tokens to connect to Oracle Autonomous Database in Thin mode, you need +to explicitly set the ``extra_auth_params`` parameter of +:func:`~oracledb.create_pool`, and also any desired ``config_dir``, +``wallet_location``, and ``wallet_password`` parameters. The ``homogeneous`` +parameter must be *True* (its default value). For example: + +.. code:: python + + import oracledb.plugins.oci_tokens + + token_based_auth = { + "auth_type": "SimpleAuthentication", # OCI specific configuration + "user": , # parameters to be set when using + "key_file": , # the oci_tokens plugin with + "fingerprint": , # simple authentication + "tenancy": , + "region": , + "profile": + } + + connection = oracledb.create_pool( + dsn=mydb_low, + config_dir="path_to_unzipped_wallet", + homogeneous=true, # must always be True for connection pools + wallet_location="location_of_pem_file", + wallet_password=wp, + extra_auth_params=token_based_auth) + +**Standalone Connections in Thick Mode Using OCI IAM Tokens** + +When using the :ref:`oci_tokens ` plugin to generate +OCI IAM tokens to connect to Oracle Autonomous Database in Thick mode, you need +to explicitly set the ``externalauth`` and ``extra_auth_params`` parameters of +:func:`oracledb.connect`. For example: + +.. code:: python + + import oracledb.plugins.oci_tokens + + token_based_auth = { + "auth_type": "SimpleAuthentication", # OCI specific configuration + "user": , # parameters to be set when using + "key_file": , # the oci_tokens plugin with + "fingerprint": , # simple authentication + "tenancy": , + "region": , + "profile": + } + connection = oracledb.connect( + externalauth=True, + dsn=mydb_low, + extra_auth_params=token_based_auth) + +**Connection Pools in Thick Mode Using OCI IAM Tokens** + +When using the :ref:`oci_tokens ` plugin to generate +OCI IAM tokens to connect to Oracle Autonomous Database in Thick mode, you need +to explicitly set the ``extra_auth_params`` and ``externalauth`` parameters of +:func:`~oracledb.create_pool`. The ``homogeneous`` parameter must be *True* +(its default value). For example: + +.. code:: python + + import oracledb.plugins.oci_tokens + + token_based_auth = { # OCI specific configuration + "auth_type": "ConfigFileAuthentication", # parameters to be set when using + "profile": , # the oci_tokens plugin with + "file_location": , # configuration file authentication + } + + connection = oracledb.create_pool( + externalauth=True, # must always be True in Thick mode + homogeneous=True, # must always be True for connection pools + dsn=mydb_low, + extra_auth_params=token_based_auth) + +.. _oauth2: + +OAuth 2.0 Token-Based Authentication +------------------------------------ + +Oracle Cloud Infrastructure (OCI) users can be centrally managed in a Microsoft +Entra ID (formerly Microsoft Azure Active Directory) service. Open +Authorization (OAuth 2.0) token-based authentication allows users to +authenticate to Oracle Database using Entra ID OAuth2 tokens. Ensure that you +have a Microsoft Azure account and your Oracle Database is registered with +Microsoft Entra ID. See `Configuring the Oracle Database for Microsoft Entra +ID Integration `_ for more information. Both Thin +and Thick modes of the python-oracledb driver support OAuth 2.0 token-based +authentication. + +When using python-oracledb in Thick mode, Oracle Client libraries 19.15 (or +later), or 21.7 (or later) are needed. + +Standalone connections and pooled connections can be created in python-oracledb +Thick and Thin modes using OAuth 2.0 token-based authentication. This can be +done or by using a class such as the example :ref:`TokenHandlerOAuth Class +` or by using python-oracledb's :ref:`Azure Cloud Native +Authentication Plugin (azure_tokens) `. Tokens can be +specified using the connection parameter introduced in python-oracledb 1.1. +Users of earlier python-oracledb versions can alternatively use :ref:`OAuth 2.0 +Token-Based Authentication Connection Strings `. + +OAuth2 Token Generation And Extraction +++++++++++++++++++++++++++++++++++++++ + +There are different ways to retrieve Entra ID OAuth2 tokens. You can use +python-oracledb's :ref:`azure_tokens ` plugin to generate +tokens. Some of the other ways to retrieve OAuth2 tokens are detailed in +`Examples of Retrieving Entra ID OAuth2 Tokens `_. You +can also retrieve Entra ID OAuth2 tokens by using `Azure Identity client +library for Python `_. + +.. _oauthhandler: + +**Example of Generating an OAuth2 Token** + +An example of automating the process of generating and reading Entra ID OAuth2 +tokens is: + +.. code:: python + + import json + import os + + import oracledb + import requests + + class TokenHandlerOAuth: + + def __init__(self, + file_name="cached_token_file_name", + api_key="api_key", + client_id="client_id", + client_secret="client_secret"): + self.token = None + self.file_name = file_name + self.url = \ + f"https://login.microsoftonline.com/{api_key}/oauth2/v2.0/token" + self.scope = \ + f"https://oracledevelopment.onmicrosoft.com/{client_id}/.default" + if os.path.exists(file_name): + with open(file_name) as f: + self.token = f.read().strip() + self.api_key = api_key + self.client_id = client_id + self.client_secret = client_secret + + def __call__(self, refresh): + if self.token is None or refresh: + post_data = dict(client_id=self.client_id, + grant_type="client_credentials", + scope=self.scope, + client_secret=self.client_secret) + r = requests.post(url=self.url, data=post_data) + result = json.loads(r.text) + self.token = result["access_token"] + with open(self.file_name, "w") as f: + f.write(self.token) + return self.token + +The TokenHandlerOAuth class uses a callable to generate and read OAuth2 +tokens. When the callable in the TokenHandlerOAuth class is invoked for the +first time to create a standalone connection or pool, the ``refresh`` parameter +is *False* which allows the callable to return a cached token, if desired. The +expiry date is then extracted from this token and compared with the current +date. If the token has not expired, then it will be used directly. If the token +has expired, the callable is invoked the second time with the ``refresh`` +parameter set to *True*. + +The TokenHandlerOAuth class defined here is used in the examples shown in +:ref:`conncreationoauth2`. + +**Example of Using a Curl Command** + +See using a :ref:`curl ` command for an alternative way to generate the +tokens. + +.. _conncreationoauth2: + +Connection Creation with OAuth2 Access Tokens ++++++++++++++++++++++++++++++++++++++++++++++ + +For OAuth 2.0 Token-Based Authentication using a class such as the sample +:ref:`TokenHandlerOAuth class `, the ``access_token`` connection +parameter must be specified. This parameter should be a string (or a callable +that returns a string) specifying an Entra ID OAuth2 token. In the examples +used below, the ``access_token`` parameter is set to a callable. + +The examples used in the subsequent sections use the +:ref:`TokenHandlerOAuth class ` to generate OAuth2 tokens to +connect to Oracle Autonomous Database with mutual TLS (mTLS). See +:ref:`autonomousdb`. + +**Standalone Connections in Thin Mode Using OAuth2 Tokens** + +When using a class such as the :ref:`TokenHandlerOAuth class ` to +generate OAuth2 tokens to connect to Oracle Autonomous Database in Thin mode, +you need to explicitly set the ``access_token``, and also any desired +``config_dir``, ``wallet_location``, and ``wallet_password`` parameters of +:func:`~oracledb.connect`. For example: + +.. code:: python + + connection = oracledb.connect( + access_token=TokenHandlerOAuth(), + dsn=mydb_low, + config_dir="path_to_unzipped_wallet", + wallet_location="location_of_pem_file", + wallet_password=wp) + +**Connection Pools in Thin Mode Using OAuth2 Tokens** + +When using a class such as the :ref:`TokenHandlerOAuth class ` to +generate OAuth2 tokens to connect to Oracle Autonomous Database in Thin mode, +you need to explicitly set the ``access_token`` parameter of +:func:`~oracledb.create_pool`, and also any desired ``config_dir``, +``wallet_location``, and ``wallet_password`` parameters. The ``homogeneous`` +parameter must be *True* (its default value). For example: + +.. code:: python + + connection = oracledb.create_pool( + access_token=TokenHandlerOAuth(), + homogeneous=True, # must always be True for connection pools + dsn=mydb_low, + config_dir="path_to_unzipped_wallet", + wallet_location="location_of_pem_file", + wallet_password=wp + min=1, max=5, increment=2) + +Note that the ``access_token`` parameter should be set to a callable. This is +useful when the connection pool needs to expand and create new connections but +the current token has expired. In such a case, the callable should return a +string specifying the new, valid Entra ID OAuth2 token. + +**Standalone Connections Thick Mode Using OAuth2 Tokens** + +When using a class such as the :ref:`TokenHandlerOAuth class ` +to generate OAuth2 tokens to connect to Oracle Autonomous Database in Thick +mode, you need to explicitly set the ``access_token`` and ``externalAuth`` +parameters of :func:`~oracledb.connect`. For example: + +.. code:: python + + connection = oracledb.connect( + access_token=TokenHandlerOAuth(), + externalauth=True, # must always be True in Thick mode + dsn=mydb_low) + +**Connection Pools in Thick Mode Using OAuth2 Tokens** + +When using a class such as the :ref:`TokenHandlerOAuth class ` to +generate OAuth2 tokens to connect to Oracle Autonomous Database in Thick mode, +you need to explicitly set the ``access_token`` and ``externalauth`` parameters +of :func:`~oracledb.create_pool`. The ``homogeneous`` parameter must be *True* +(which is its default value). For example: + +.. code:: python + + pool = oracledb.create_pool( + access_token=TokenHandlerOAuth(), + externalauth=True, # must always be True in Thick mode + homogeneous=True, # must always be True for connection pools + dsn=mydb_low, min=1, max=5, increment=2) + +Note that the ``access_token`` parameter should be set to a callable. This is +useful when the connection pool needs to expand and create new connections but +the current token has expired. In such a case, the callable should return a +string specifying the new, valid Entra ID OAuth2 token. + +.. _oauth2connstr: + +OAuth 2.0 Token-Based Authentication Connection Strings ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The connection string used by python-oracledb can specify the directory where +the token file is located. This syntax is usable with older versions of +python-oracledb. However, it is recommended to use connection parameters +introduced in python-oracledb 1.1 instead. See +:ref:`OAuth 2.0 Token-Based Authentication`. + +.. note:: + + OAuth 2.0 Token-Based Authentication Connection Strings is only supported + in python-oracledb Thick mode. See :ref:`enablingthick`. + +There are different ways to retrieve Entra ID OAuth2 tokens. Some of the ways to +retrieve OAuth2 tokens are detailed in `Examples of Retrieving Entra ID OAuth2 +Tokens `_. You can also retrieve Entra ID OAuth2 +tokens by using `Azure Identity client library for Python +`_. + +.. _curl: + +**Example of Using a Curl Command** + +Here, as an example, we are using Curl with a Resource Owner +Password Credential (ROPC) Flow, that is, a ``curl`` command is used against +the Entra ID API to get the Entra ID OAuth2 token:: + + curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' + https://login.microsoftonline.com/your_tenant_id/oauth2/v2.0/token + -d 'client_id=your_client_id' + -d 'grant_type=client_credentials' + -d 'scope=https://oracledevelopment.onmicrosoft.com/your_client_id/.default' + -d 'client_secret=your_client_secret' + +This command generates a JSON response with token type, expiration, and access +token values. The JSON response needs to be parsed so that only the access +token is written and stored in a file. You can save the value of +``access_token`` generated to a file and set ``TOKEN_LOCATION`` to the location +of token file. See :ref:`TokenHandlerOAuth class ` for an example +of generating tokens. + +The Oracle Net parameters ``TOKEN_AUTH`` and ``TOKEN_LOCATION`` must be set when +you are using the connection string syntax. Also, the ``PROTOCOL`` +parameter must be ``tcps`` and ``SSL_SERVER_DN_MATCH`` should be ``ON``. + +You can set ``TOKEN_AUTH=OAUTH``. There is no default location set in this +case, so you must set ``TOKEN_LOCATION`` to either of the following: + +* A directory, in which case, you must create a file named ``token`` which + contains the token value +* A fully qualified file name, in which case, you must specify the entire path + of the file which contains the token value + +You can either set ``TOKEN_AUTH`` and ``TOKEN_LOCATION`` in a :ref:`sqlnet.ora +` file or alternatively, you can specify it inside a :ref:`Connect +Descriptor `, for example when using a :ref:`tnsnames.ora +` file:: + + db_alias = + (DESCRIPTION = + (ADDRESS=(PROTOCOL=TCPS)(PORT=1522)(HOST=xxx.oraclecloud.com)) + (CONNECT_DATA=(SERVICE_NAME=xxx.adb.oraclecloud.com)) + (SECURITY = + (SSL_SERVER_CERT_DN="CN=xxx.oraclecloud.com, \ + O=Oracle Corporation,L=Redwood City,ST=California,C=US") + (TOKEN_AUTH=OAUTH) + (TOKEN_LOCATION="/home/user1/mytokens/oauthtoken") + ) + ) + +The ``TOKEN_AUTH`` and ``TOKEN_LOCATION`` values in a connection string take +precedence over the ``sqlnet.ora`` settings. + +Standalone connection example: + +.. code-block:: python + + connection = oracledb.connect(dsn=db_alias, externalauth=True) + +Connection pool example: + +.. code-block:: python + + pool = oracledb.create_pool(dsn=db_alias, externalauth=True, + homogeneous=False, min=1, max=2, increment=1) + + connection = pool.acquire() + +.. _cloudnativeauthoauth: + +Azure Cloud Native Authentication with the azure_tokens Plugin +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +With Cloud Native Authentication, python-oracledb's :ref:`azure_tokens +` plugin can automatically generate and refresh +OAuth2 tokens when required with the support of the `Microsoft Authentication +Library (MSAL) `__. + +The :ref:`azure_tokens ` plugin can be imported +like: + +.. code-block:: python + + import oracledb.plugins.azure_tokens + +The plugin has a Python package dependency which needs to be installed +separately before the plugin can be used, see :ref:`azuretokenmodules`. + +The ``azure_tokens`` plugin defines and registers a :ref:`parameter hook +` function which uses the connection parameter +``extra_auth_params`` passed to :meth:`oracledb.connect()`, +:meth:`oracledb.create_pool()`, :meth:`oracledb.connect_async()`, or +:meth:`oracledb.create_pool_async()`. Using this parameter's values, the hook +function sets the ``access_token`` parameter of a :ref:`ConnectParams object +` to a callable which generates an OAuth2 token. Python-oracledb +then acquires and uses a token to transparently complete connection or pool +creation calls. + +For OAuth 2.0 Token-Based Authentication connection and pool creation, the +``extra_auth_params`` parameter should be a dictionary with keys as shown in +the following table. + +.. list-table-with-summary:: Azure Cloud Native Authentication Configuration Keys + :header-rows: 1 + :class: wy-table-responsive + :widths: 10 30 10 + :name: _azure_configuration_parameters + :summary: The first column displays the dictionary key. The second column displays the description of the key. The third column displays whether the parameter is required or optional. + + * - Key + - Description + - Required or Optional + * - ``auth_type`` + - The authentication type. + + This must be the string "AzureServicePrincipal". This type makes the plugin acquire Azure service principal access tokens through a client credential flow. + - Required + * - ``authority`` + - This parameter must be set as a string in the URI format with the tenant ID, for example ``https://{identity provider instance}/{tenantId}``. + + The tenantId is the directory tenant against which the application operates, in either GUID or domain-name format. + - Required + * - ``client_id`` + - The application ID that is assigned to your application. + + This information can be found in the portal where the application was registered. + - Required + * - ``client_credential`` + - The client secret that was generated for your application in the application registration portal. + - Required + * - ``scopes`` + - This parameter represents the value of the scope for the request. + + It should be the resource identifier (application ID URI) of the desired resource, with the suffix ".default". For example, ``https://{uri}/clientID/.default``. + - Required + +All keys and values other than ``auth_type`` are used by the `Microsoft +Authentication Library (MSAL) `__ API calls in the plugin. The plugin +implementation can be seen in `plugins/azure_tokens.py +`__. + +For information on the Azure specific configuration parameters, see `MSAL +`__. + +The examples in the subsequent sections use the :ref:`azure_tokens +` plugin to generate OAuth2 tokens to connect to +Oracle Autonomous Database with mutual TLS (mTLS). See :ref:`autonomousdb`. + +**Standalone Connections in Thin Mode Using OAuth2 Tokens** + +When using the :ref:`azure_tokens ` plugin to +generate OAuth2 tokens to connect to Oracle Autonomous Database in Thin mode, +you need to explicitly set the ``extra_auth_params`` parameter, and also any +required ``config_dir``, ``wallet_location``, and ``wallet_password`` +parameters of :func:`~oracledb.connect`. For example: + +.. code:: python + + import oracledb.plugins.azure_tokens + + token_based_auth = { + "auth_type": "AzureServicePrincipal", # Azure specific configuration + "authority": , # parameters to be set when using + "client_id": , # the azure_tokens plugin + "client_credential": , + "scopes": + } + + connection = oracledb.connect( + dsn=mydb_low, + config_dir="path_to_unzipped_wallet", + wallet_location="location_of_pem_file", + wallet_password=wp, + extra_auth_params=token_based_auth) + +**Connection Pools in Thin Mode Using OAuth2 Tokens** + +When using the :ref:`azure_tokens ` plugin to +generate OAuth2 tokens to connect to Oracle Autonomous Database in Thin mode, +you need to explicitly set the ``extra_auth_params`` parameter of +:func:`~oracledb.create_pool`, and also any desired ``config_dir``, +``wallet_location``, and ``wallet_password`` parameters. The ``homogeneous`` +parameter must be *True* (its default value). For example: + +.. code:: python + + import oracledb.plugins.azure_tokens + + token_based_auth = { + "auth_type": "AzureServicePrincipal", # Azure specific configuration + "authority": , # parameters to be set when using + "client_id": , # the azure_tokens plugin + "client_credential": , + "scopes": + } + + connection = oracledb.create_pool( + dsn=mydb_low, + config_dir="path_to_unzipped_wallet", + homogeneous=true, # must always be True for connection pools + wallet_location="location_of_pem_file", + wallet_password=wp, + extra_auth_params=token_based_auth) + +**Standalone Connections Thick Mode Using OAuth2 Tokens** + +When using the :ref:`azure_tokens ` plugin to +generate OAuth2 tokens to connect to Oracle Autonomous Database in Thick mode, +you need to explicitly set the ``extra_auth_params`` and ``externalauth`` +parameters of :func:`~oracledb.connect`. For example: + +.. code:: python + + import oracledb.plugins.azure_tokens + + token_based_auth = { + "auth_type": "AzureServicePrincipal", # Azure specific configuration + "authority": , # parameters to be set when using + "client_id": , # the azure_tokens plugin + "client_credential": , + "scopes": + } + + connection = oracledb.connect( + externalauth=True, # must always be True in Thick mode + dsn=mydb_low, + extra_auth_params=token_based_auth) + +**Connection Pools in Thick Mode Using OAuth2 Tokens** + +When using the :ref:`azure_tokens ` plugin to +generate OAuth2 tokens to connect to Oracle Autonomous Database in Thick mode, +you need to explicitly set the ``extra_auth_params`` and ``externalauth`` +parameters of :func:`~oracledb.create_pool`. The ``homogeneous`` parameter must +be *True* (its default value). For example: + +.. code:: python + + import oracledb.plugins.azure_tokens + + token_based_auth = { + "auth_type": "AzureServicePrincipal", # Azure specific configuration + "authority": , # parameters to be set when using + "client_id": , # the azure_tokens plugin + "client_credential": , + "scopes": + } + + connection = oracledb.create_pool( + externalauth=True, # must always be True in Thick mode + homogeneous=True, # must always be True for connection pools + dsn=mydb_low, + extra_auth_params=token_based_auth) + +.. _instanceprincipalauth: + +Instance Principal Authentication +================================= + +With Instance Principal Authentication, Oracle Cloud Infrastructure (OCI) +compute instances can be authorized to access services on Oracle Cloud such as +Oracle Autonomous Database. Python-oracledb applications running on such a +compute instance do not need to provide database user credentials. + +Each compute instance behaves as a distinct type of Identity and Access +Management (IAM) Principal, that is, each compute instance has a unique +identity in the form of a digital certificate which is managed by OCI. When +using Instance Principal Authentication, a compute instance authenticates with +OCI IAM using this identity and obtains a short-lived token. This token is +then used to access Oracle Cloud services without storing or managing any +secrets in your application. + +The example below demonstrates how to connect to Oracle Autonomous +Database using Instance Principal authentication. To enable this, use +python-oracledb's :ref:`oci_tokens ` plugin which +is pre-installed with the ``oracledb`` module. + +**Step 1: Create an OCI Compute Instance** + +An `OCI compute instance `__ is a virtual machine running +within OCI that provides compute resources for your application. This compute +instance will be used to authenticate access to Oracle Cloud services when +using Instance Principal Authentication. + +To create an OCI compute instance, see the steps in `Creating an Instance +`__ section of the Oracle Cloud Infrastructure +documentation. + +For more information on OCI compute instances, see `Calling Services from a +Compute Instance `__. + +**Step 2: Install the OCI CLI on your compute instance** + +The `OCI Command Line Interface (CLI) `__ that can be used on its own or with +the Oracle Cloud console to complete OCI tasks. + +To install the OCI CLI on your compute instance, see the installation +instructions in the `Installing the CLI `__ section of Oracle Cloud Infrastructure +documentation. + +**Step 3: Create a Dynamic Group** + +A Dynamic Group is used to define rules to group the compute instances that +require access. + +To create a dynamic group using the Oracle Cloud console, see the steps in the +`To create a dynamic group `__ section of the Oracle Cloud +Infrastructure documentation. + +**Step 4: Create an IAM Policy** + +An IAM Policy is used to grant a dynamic group permission to access the +required OCI services such as Oracle Autonomous Database. If the scope is not +set, the policy should be for the specified tenancy. + +To create an IAM policy using Oracle Cloud console, see the steps in the +`Create an IAM Policy `__ section of the Oracle Cloud +Infrastructure documentation. + +**Step 5: Map an Instance Principal to an Oracle Database User** + +You must map the Instance Principal to an Oracle Database user. For more +information, see `Accessing the Database Using an Instance Principal +`__. + +Also, make sure that external authentication is enabled on Oracle ADB and +Oracle Database parameter ``IDENTITY_PROVIDER_TYPE`` is set to *OCI_IAM*. For +the steps, see `Enable IAM Authentication on ADB `__. + +**Step 6: Deploy your application on the Compute Instance** + +To use Instance Principal authentication, set ``extra_auth_params`` when +creating a standalone connection or a connection pool. The defined IAM policy +must allow access according to the specified scope. For information on the +keys of the ``extra_auth_params`` parameter, see +:ref:`_oci_configuration_parameters`. + +An example of connecting using Instance Principal: + +.. code-block:: python + + import oracledb + import oracledb.plugins.oci_tokens + + token_based_auth = { + "auth_type": "InstancePrincipal" + } + + connection = oracledb.connect( + dsn=mydb_low, + extra_auth_params=token_based_auth + ) + +.. _configproviderauthmethods: + +Authentication Methods for Centralized Configuration Providers +============================================================== + +You may need to provide authentication methods to access a centralized +configuration provider. The authentication methods for the following +centralized configuration providers are detailed in this section: + +- :ref:`OCI Object Storage Centralized Configuration Provider + ` + +- :ref:`Azure App Centralized Configuration Provider ` + +.. _ociobjectstorageauthmethods: + +OCI Object Storage Configuration Provider Authentication Methods +---------------------------------------------------------------- + +An Oracle Cloud Infrastructure (OCI) authentication method can be used to +access the OCI Object Storage centralized configuration provider. The +authentication methood can be set in the ``