diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 07ee2888..c63161e0 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,15 +60,9 @@ 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 @@ -58,15 +87,16 @@ jobs: uses: actions/upload-artifact@v4 with: name: Linux_${{ matrix.platform }}_wheels - path: dist + path: dist/*.whl - build_non_linux_wheels: + 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: [windows-latest, macos-latest] - python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13'] + os: [macos-latest] + python-version: ['3.9', '3.10', '3.11', '3.12', '3.13'] arch: ['x86', ''] exclude: - os: macos-latest @@ -96,9 +126,44 @@ jobs: name: python-oracledb-${{ matrix.os }}-${{ matrix.python-version }}-${{ matrix.arch }} path: dist/*.whl + 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] + python-version: ['3.9', '3.10', '3.11', '3.12', '3.13'] + arch: ['x86', ''] + + 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 + 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/.gitignore b/.gitignore index d672f61d..8c791a41 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,10 @@ build/ dist/ doc/build src/oracledb/*.c +src/oracledb/interchange/*.c tests/ext/config.ini .ipynb_checkpoints/ +.venv*/ +.idea samples/sample.csv +samples/sample.parquet diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index d8110b62..8d193308 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -14,3 +14,4 @@ repos: rev: v0.0.291 hooks: - id: ruff + exclude: ^samples/tutorial/ diff --git a/LICENSE.txt b/LICENSE.txt index a2c0651a..38fd1483 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,4 +1,4 @@ -Copyright (c) 2016, 2024 Oracle and/or its affiliates. +Copyright (c) 2016, 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 diff --git a/MANIFEST.in b/MANIFEST.in index 431af34d..5bdd1ca4 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -5,6 +5,7 @@ include *.txt recursive-include src/oracledb *.pxd recursive-include src/oracledb *.pxi recursive-include src/oracledb *.pyx +recursive-include src/oracledb/plugins *.py recursive-include src/oracledb/impl/thick/odpi *.c recursive-include src/oracledb/impl/thick/odpi *.h prune src/oracledb/impl/thick/odpi/test diff --git a/README.md b/README.md index b2b48dd7..f867079f 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,66 @@ # 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. +Python-oracledb is an open-source [Python][python] extension module allowing +Python programs to connect to [Oracle Database][oracledb]. 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]. It 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]. +Python-oracledb is used for executing SQL and PL/SQL; for calling NoSQL-style +document APIs; for working with data frames; for receiving database +notifications and messages; and for starting and stopping the database. It has +features for high availability and security. It is used by many Python +Frameworks, SQL Generators, ORMs, and libraries. -Synchronous and [concurrent][concurrent] coding styles are supported. +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 [python-oracledb Installation][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" +cs = "localhost/orclpdb" +# 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.13. - 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 +70,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 11.2 through 23ai. - Oracle Database @@ -51,14 +87,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 +129,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 5cd97ac0..15d44264 100644 --- a/THIRD_PARTY_LICENSES.txt +++ b/THIRD_PARTY_LICENSES.txt @@ -1,3 +1,8 @@ +------------------------------------------------------------------------------- +------------------------------------------------------------------------------- + +Cython + The following attribution text was taken from Component Cython Version 0.24.1 Apache License @@ -178,6 +183,9 @@ The following attribution text was taken from Component Cython Version 0.24.1 END OF TERMS AND CONDITIONS ------------------------------------------------------------------------------- +------------------------------------------------------------------------------- + +Cryptography LICENSE: https://github.com/pyca/cryptography/blob/3.4.x/LICENSE This software is made available under the terms of *either* of the licenses @@ -453,3 +461,11995 @@ 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. + +------------------------------------------------------------------------------- +------------------------------------------------------------------------------- + +Apache Arrow nanoarrow +Copyright 2023 The Apache Software Foundation + +This product includes software developed at +The Apache Software Foundation (http://www.apache.org/). + +---------- + + + +Apache nanoarrow 0.6.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 + + 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. + +---------- + +Copyright 2015-2023 Mikkel F. Jørgensen, dvide.com +Copyright (c) 2016 Mikkel Fahnøe Jørgensen, dvide.com +Copyright (c) 2005-2016 Paul Hsieh +Copyright (c) 2024 Mikkel Fahnøe Jørgensen, dvide.com + +---------- + +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you 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. + +------------------------------------------------------------------------------- +------------------------------------------------------------------------------- + +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) + +Copyright (c) Microsoft Corporation. +All rights reserved. + +This code is licensed under 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. + +----------------------------------------------------------------------------------------------------------------------------- +cryptography + +This software is made available under the terms of *either* of the licenses +found in LICENSE.APACHE or LICENSE.BSD. Contributions to cryptography are made +under the terms of *both* these licenses. + + -- Apache License + + + 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 + + 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. + +--BSD License + +Copyright (c) Individual 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 of PyCA Cryptography 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. + +----------------------------------------------------------------------------------------------------------------------------- + +cffi + +Except when otherwise stated (look for LICENSE files in directories or +information at the beginning of each file) all software and +documentation is licensed as follows: + + 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. + +----------------------------------------------------------------------------------------------------------------------------- +pycparser +pycparser -- A C parser in Python + +Copyright (c) 2008-2022, Eli Bendersky +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. +----------------------------------------------------------------------------------------------------------------------------- + +PyJWT + +The MIT License (MIT) + +Copyright (c) 2015-2022 José Padilla + +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. + +----------------------------------------------------------------------------------------------------------------------------- + +certifi + +This package contains a modified version of ca-bundle.crt: + +ca-bundle.crt -- Bundle of CA Root Certificates + +This is a bundle of X.509 certificates of public Certificate Authorities +(CA). These were automatically extracted from Mozilla's root certificates +file (certdata.txt). This file can be found in the mozilla source tree: +https://hg.mozilla.org/mozilla-central/file/tip/security/nss/lib/ckfw/builtins/certdata.txt +It contains the certificates in PEM format and therefore +can be directly used with curl / libcurl / php_curl, or with +an Apache+mod_ssl webserver for SSL client authentication. +Just configure this file as the SSLCACertificateFile.# + +***** BEGIN LICENSE BLOCK ***** +This Source Code Form is subject to the terms of the Mozilla Public License, +v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain +one at http://mozilla.org/MPL/2.0/. + +***** END LICENSE BLOCK ***** +@(#) $RCSfile: certdata.txt,v $ $Revision: 1.80 $ $Date: 2011/11/03 15:11:58 $ + + +--Mozilla Public License + +Mozilla Public License
Version 2.0 +1. Definitions +1.1. “Contributor” +means each individual or legal entity that creates, contributes to the creation of, or owns Covered Software. +1.2. “Contributor Version” +means the combination of the Contributions of others (if any) used by a Contributor and that particular Contributor’s Contribution. +1.3. “Contribution” +means Covered Software of a particular Contributor. +1.4. “Covered Software” +means Source Code Form to which the initial Contributor has attached the notice in Exhibit A, the Executable Form of such Source Code Form, and Modifications of such Source Code Form, in each case including portions thereof. +1.5. “Incompatible With Secondary Licenses” +means +* that the initial Contributor has attached the notice described in Exhibit B to the Covered Software; or +* that the Covered Software was made available under the terms of version 1.1 or earlier of the License, but not also under the terms of a Secondary License. +1.6. “Executable Form” +means any form of the work other than Source Code Form. +1.7. “Larger Work” +means a work that combines Covered Software with other material, in a separate file or files, that is not Covered Software. +1.8. “License” +means this document. +1.9. “Licensable” +means having the right to grant, to the maximum extent possible, whether at the time of the initial grant or subsequently, any and all of the rights conveyed by this License. +1.10. “Modifications” +means any of the following: +* any file in Source Code Form that results from an addition to, deletion from, or modification of the contents of Covered Software; or +* any new file in Source Code Form that contains any Covered Software. +1.11. “Patent Claims” of a Contributor +means any patent claim(s), including without limitation, method, process, and apparatus claims, in any patent Licensable by such Contributor that would be infringed, but for the grant of the License, by the making, using, selling, offering for sale, having made, import, or transfer of either its Contributions or its Contributor Version. +1.12. “Secondary License” +means either the GNU General Public License, Version 2.0, the GNU Lesser General Public License, Version 2.1, the GNU Affero General Public License, Version 3.0, or any later versions of those licenses. +1.13. “Source Code Form” +means the form of the work preferred for making modifications. +1.14. “You” (or “Your”) +means an individual or a legal entity exercising rights under this License. For legal entities, “You” includes any entity that controls, is controlled by, or is under common control with You. For purposes of this definition, “control” means (a) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (b) ownership of more than fifty percent (50%) of the outstanding shares or beneficial ownership of such entity. +2. License Grants and Conditions +2.1. Grants +Each Contributor hereby grants You a world-wide, royalty-free, non-exclusive license: +* under intellectual property rights (other than patent or trademark) Licensable by such Contributor to use, reproduce, make available, modify, display, perform, distribute, and otherwise exploit its Contributions, either on an unmodified basis, with Modifications, or as part of a Larger Work; and +* under Patent Claims of such Contributor to make, use, sell, offer for sale, have made, import, and otherwise transfer either its Contributions or its Contributor Version. +2.2. Effective Date +The licenses granted in Section 2.1 with respect to any Contribution become effective for each Contribution on the date the Contributor first distributes such Contribution. +2.3. Limitations on Grant Scope +The licenses granted in this Section 2 are the only rights granted under this License. No additional rights or licenses will be implied from the distribution or licensing of Covered Software under this License. Notwithstanding Section 2.1(b) above, no patent license is granted by a Contributor: +* for any code that a Contributor has removed from Covered Software; or +* for infringements caused by: (i) Your and any other third party’s modifications of Covered Software, or (ii) the combination of its Contributions with other software (except as part of its Contributor Version); or +* under Patent Claims infringed by Covered Software in the absence of its Contributions. +This License does not grant any rights in the trademarks, service marks, or logos of any Contributor (except as may be necessary to comply with the notice requirements in Section 3.4). +2.4. Subsequent Licenses +No Contributor makes additional grants as a result of Your choice to distribute the Covered Software under a subsequent version of this License (see Section 10.2) or under the terms of a Secondary License (if permitted under the terms of Section 3.3). +2.5. Representation +Each Contributor represents that the Contributor believes its Contributions are its original creation(s) or it has sufficient rights to grant the rights to its Contributions conveyed by this License. +2.6. Fair Use +This License is not intended to limit any rights You have under applicable copyright doctrines of fair use, fair dealing, or other equivalents. +2.7. Conditions +Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted in Section 2.1. +3. Responsibilities +3.1. Distribution of Source Form +All distribution of Covered Software in Source Code Form, including any Modifications that You create or to which You contribute, must be under the terms of this License. You must inform recipients that the Source Code Form of the Covered Software is governed by the terms of this License, and how they can obtain a copy of this License. You may not attempt to alter or restrict the recipients’ rights in the Source Code Form. +3.2. Distribution of Executable Form +If You distribute Covered Software in Executable Form then: +* such Covered Software must also be made available in Source Code Form, as described in Section 3.1, and You must inform recipients of the Executable Form how they can obtain a copy of such Source Code Form by reasonable means in a timely manner, at a charge no more than the cost of distribution to the recipient; and +* You may distribute such Executable Form under the terms of this License, or sublicense it under different terms, provided that the license for the Executable Form does not attempt to limit or alter the recipients’ rights in the Source Code Form under this License. +3.3. Distribution of a Larger Work +You may create and distribute a Larger Work under terms of Your choice, provided that You also comply with the requirements of this License for the Covered Software. If the Larger Work is a combination of Covered Software with a work governed by one or more Secondary Licenses, and the Covered Software is not Incompatible With Secondary Licenses, this License permits You to additionally distribute such Covered Software under the terms of such Secondary License(s), so that the recipient of the Larger Work may, at their option, further distribute the Covered Software under the terms of either this License or such Secondary License(s). +3.4. Notices +You may not remove or alter the substance of any license notices (including copyright notices, patent notices, disclaimers of warranty, or limitations of liability) contained within the Source Code Form of the Covered Software, except that You may alter any license notices to the extent required to remedy known factual inaccuracies. +3.5. Application of Additional Terms +You may choose to offer, and to charge a fee for, warranty, support, indemnity or liability obligations to one or more recipients of Covered Software. However, You may do so only on Your own behalf, and not on behalf of any Contributor. You must make it absolutely clear that any such warranty, support, indemnity, or liability obligation is offered by You alone, and You hereby agree to indemnify every Contributor for any liability incurred by such Contributor as a result of warranty, support, indemnity or liability terms You offer. You may include additional disclaimers of warranty and limitations of liability specific to any jurisdiction. +4. Inability to Comply Due to Statute or Regulation +If it is impossible for You to comply with any of the terms of this License with respect to some or all of the Covered Software due to statute, judicial order, or regulation then You must: (a) comply with the terms of this License to the maximum extent possible; and (b) describe the limitations and the code they affect. Such description must be placed in a text file included with all distributions of the Covered Software under this License. Except to the extent prohibited by statute or regulation, such description must be sufficiently detailed for a recipient of ordinary skill to be able to understand it. +5. Termination +5.1. The rights granted under this License will terminate automatically if You fail to comply with any of its terms. However, if You become compliant, then the rights granted under this License from a particular Contributor are reinstated (a) provisionally, unless and until such Contributor explicitly and finally terminates Your grants, and (b) on an ongoing basis, if such Contributor fails to notify You of the non-compliance by some reasonable means prior to 60 days after You have come back into compliance. Moreover, Your grants from a particular Contributor are reinstated on an ongoing basis if such Contributor notifies You of the non-compliance by some reasonable means, this is the first time You have received notice of non-compliance with this License from such Contributor, and You become compliant prior to 30 days after Your receipt of the notice. +5.2. If You initiate litigation against any entity by asserting a patent infringement claim (excluding declaratory judgment actions, counter-claims, and cross-claims) alleging that a Contributor Version directly or indirectly infringes any patent, then the rights granted to You by any and all Contributors for the Covered Software under Section 2.1 of this License shall terminate. +5.3. In the event of termination under Sections 5.1 or 5.2 above, all end user license agreements (excluding distributors and resellers) which have been validly granted by You or Your distributors under this License prior to termination shall survive termination. +6. Disclaimer of Warranty +Covered Software is provided under this License on an “as is” basis, without warranty of any kind, either expressed, implied, or statutory, including, without limitation, warranties that the Covered Software is free of defects, merchantable, fit for a particular purpose or non-infringing. The entire risk as to the quality and performance of the Covered Software is with You. Should any Covered Software prove defective in any respect, You (not any Contributor) assume the cost of any necessary servicing, repair, or correction. This disclaimer of warranty constitutes an essential part of this License. No use of any Covered Software is authorized under this License except under this disclaimer. +7. Limitation of Liability +Under no circumstances and under no legal theory, whether tort (including negligence), contract, or otherwise, shall any Contributor, or anyone who distributes Covered Software as permitted above, be liable to You for any direct, indirect, special, incidental, or consequential damages of any character including, without limitation, damages for lost profits, loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses, even if such party shall have been informed of the possibility of such damages. This limitation of liability shall not apply to liability for death or personal injury resulting from such party’s negligence to the extent applicable law prohibits such limitation. Some jurisdictions do not allow the exclusion or limitation of incidental or consequential damages, so this exclusion and limitation may not apply to You. +8. Litigation +Any litigation relating to this License may be brought only in the courts of a jurisdiction where the defendant maintains its principal place of business and such litigation shall be governed by laws of that jurisdiction, without reference to its conflict-of-law provisions. Nothing in this Section shall prevent a party’s ability to bring cross-claims or counter-claims. +9. Miscellaneous +This License represents the complete agreement concerning the subject matter hereof. If any provision of this License is held to be unenforceable, such provision shall be reformed only to the extent necessary to make it enforceable. Any law or regulation which provides that the language of a contract shall be construed against the drafter shall not be used to construe this License against a Contributor. +10. Versions of the License +10.1. New Versions +Mozilla Foundation is the license steward. Except as provided in Section 10.3, no one other than the license steward has the right to modify or publish new versions of this License. Each version will be given a distinguishing version number. +10.2. Effect of New Versions +You may distribute the Covered Software under the terms of the version of the License under which You originally received the Covered Software, or under the terms of any subsequent version published by the license steward. +10.3. Modified Versions +If you create software not governed by this License, and you want to create a new license for such software, you may create and use a modified version of this License if you rename the license and remove any references to the name of the license steward (except to note that such modified license differs from this License). +10.4. Distributing Source Code Form that is Incompatible With Secondary Licenses +If You choose to distribute Source Code Form that is Incompatible With Secondary Licenses under the terms of this version of the License, the notice described in Exhibit B of this License must be attached. +Exhibit A - Source Code Form License Notice +This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/. +If it is not possible or desirable to put the notice in a particular file, then You may include the notice in a location (such as a LICENSE file in a relevant directory) where a recipient would be likely to look for such a notice. +You may add additional accurate notices of copyright ownership. +Exhibit B - “Incompatible With Secondary Licenses” Notice +This Source Code Form is “Incompatible With Secondary Licenses”, as defined by the Mozilla Public License, v. 2.0. + + +----------------------------------------------------------------------------------------------------------------------------- + +charset-normalizer + +MIT License + +Copyright (c) 2019 TAHRI Ahmed R. + +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. + +----------------------------------------------------------------------------------------------------------------------------- +idna +BSD 3-Clause License + +Copyright (c) 2013-2024, Kim Davies 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 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. +--------------------------------------------------------- +urllib + +MIT License + +Copyright (c) 2008-2020 Andrey Petrov 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. + +----------------------------------------------------------------------------------------------------------------------------- + +requests + +Copyright 2019 Kenneth Reitz + + 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. + +------------------------------------------------------------------------------- +------------------------------------------------------------------------------- + +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/src/.static/custom.css b/doc/src/.static/custom.css index b6b3ac57..17a42f2d 100644 --- a/doc/src/.static/custom.css +++ b/doc/src/.static/custom.css @@ -1,4 +1,7 @@ -/* Added code to display tables without horizontal scrollbars */ +/* Added code to display tables without horizontal scrollbars +add an extra line between two paragraphs and define the line +spacing in tables */ .wy-table-responsive table td, .wy-table-responsive table th { - white-space: normal; + white-space: pre-wrap; + line-height: 10pt; } 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 dcbe14d5..6235f866 100644 --- a/doc/src/api_manual/aq.rst +++ b/doc/src/api_manual/aq.rst @@ -6,10 +6,6 @@ API: Advanced Queuing (AQ) See :ref:`aqusermanual` for more information about using AQ in python-oracledb. -.. note:: - - All of these objects are extensions to the DB API. - .. _queue: Queue Objects @@ -18,14 +14,16 @@ Queue Objects 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) +.. method:: Queue.deqmany(max_num_messages) 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. + :ref:`message property ` object. 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 @@ -34,8 +32,8 @@ Queue Methods .. 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. + will be a :ref:`message property ` object; otherwise, it will + be the value *None*. 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 @@ -50,12 +48,14 @@ Queue Methods .. 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. + 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. For consistency and compliance with the PEP 8 naming style, the name of the method was changed from `enqMany()`. The old name will continue @@ -85,7 +85,7 @@ Queue Attributes ` that will be used when dequeuing messages from the queue. For consistency and compliance with the PEP 8 naming style, the name of - the attribute was changed from `deqOptions`. The old name will continue + the attribute was changed from ``deqOptions``. The old name will continue to work for a period of time. .. attribute:: Queue.enqoptions @@ -94,7 +94,7 @@ Queue Attributes ` that will be used when enqueuing messages into the queue. For consistency and compliance with the PEP 8 naming style, the name of - the attribute was changed from `enqOptions`. The old name will continue + the attribute was changed from ``enqOptions``. The old name will continue to work for a period of time. .. attribute:: Queue.name @@ -105,10 +105,10 @@ Queue Attributes 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``. + ``"JSON"``. If using a raw queue, this returns the value *None*. For consistency and compliance with the PEP 8 naming style, the name of - the attribute was changed from `payloadType`. The old name will + the attribute was changed from ``payloadType``. The old name will continue to work for a period of time. @@ -117,12 +117,10 @@ Queue Attributes 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`. +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`. +.. dbapiobjectextension:: .. attribute:: DeqOptions.condition @@ -212,12 +210,10 @@ Dequeue Options 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`. +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`. +.. dbapiobjectextension:: .. attribute:: EnqOptions.deliverymode @@ -247,14 +243,13 @@ Enqueue Options Message Properties ================== -.. note:: - - These objects are 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()`. +These objects are 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()`. +.. dbapiobjectextension:: .. attribute:: MessageProperties.attempts @@ -311,7 +306,7 @@ Message Properties 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`. + dequeued or enqueued, the value will be *None*. .. attribute:: MessageProperties.payload @@ -327,7 +322,7 @@ Message Properties 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 zero. + negative numbers. The default value is *0*. .. attribute:: 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..a6df9d6c --- /dev/null +++ b/doc/src/api_manual/async_aq.rst @@ -0,0 +1,118 @@ +.. _asyncaq: + +******************************** +API: Async Advanced Queuing (AQ) +******************************** + +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 Objects +================== + +These objects are created using the :meth:`AsyncConnection.queue()` method and +are used to enqueue and dequeue messages. + +AsyncQueue Methods +------------------ + +.. method:: AsyncQueue.deqmany(max_num_messages) + + 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. + +.. method:: AsyncQueue.deqone() + + Dequeues at most one message from the queue. If a message is dequeued, it + will be a :ref:`message property ` object; otherwise, + the value *None* will be returned. + +.. method:: AsyncQueue.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. + +.. method:: AsyncQueue.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. + +AsyncQueue Attributes +--------------------- + +.. attribute:: AsyncQueue.connection + + This read-only attribute returns a reference to the connection object on + which the queue was created. + +.. attribute:: AsyncQueue.deqoptions + + This read-only attribute returns a reference to the :ref:`options + ` that will be used when dequeuing messages from the queue. + +.. attribute:: AsyncQueue.enqoptions + + This read-only attribute returns a reference to the :ref:`options + ` that will be used when enqueuing messages into the queue. + +.. attribute:: AsyncQueue.name + + This read-only attribute returns the name of the queue. + +.. attribute:: AsyncQueue.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*. + +.. _asyncdeqoptions: + +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:`AsyncQueue.deqoptions`. + +See :ref:`deqoptions` for information on the supported attributes. + +.. _asyncenqoptions: + +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:`AsyncQueue.enqoptions`. + +See :ref:`enqoptions` for information on the supported attributes. + +.. _asyncmsgproperties: + +Message Properties +================== + +.. note:: + + These objects are 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 3ef001ba..1bf156dc 100644 --- a/doc/src/api_manual/async_connection.rst +++ b/doc/src/api_manual/async_connection.rst @@ -8,8 +8,9 @@ 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. +methods should be used with ``await``. + +.. dbapiobjectextension:: .. versionadded:: 2.0.0 @@ -124,6 +125,61 @@ AsyncConnection Methods This is a shortcut for calling :meth:`AsyncConnection.cursor()`, :meth:`AsyncCursor.executemany()`, and then :meth:`AsyncCursor.close()`. +.. method:: AsyncConnection.fetch_df_all(statement, parameters=None, \ + arraysize=None) + + 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. + + 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 ``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. + + See :ref:`dataframeformat` for the supported data types and examples. + + .. note:: + + The data frame support in python-oracledb 3.2 is a pre-release and may + change in a future version. + + .. 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. + + See :ref:`dataframeformat` for the supported data types and examples. + + .. note:: + + The data frame support in python-oracledb 3.2 is a pre-release and may + change in a future version. + + .. versionadded:: 3.0.0 + .. method:: AsyncConnection.fetchall(statement, parameters=None, \ arraysize=None, rowfactory=None) @@ -160,10 +216,10 @@ AsyncConnection Methods rowfactory=None) Executes a query and returns the first row of the result set if one exists - (or None if no rows exist). + (or *None* if no rows exist). Internally, this method's :attr:`Cursor.prefetchrows` and - :attr:`Cursor.arraysize` sizes will be set to 1. + :attr:`Cursor.arraysize` sizes will be set to *1*. 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 @@ -191,17 +247,43 @@ AsyncConnection Methods 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. + 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.msgproperties(payload, correlation, delay, exceptionq, expiration, priority) + + Creates and returns a message properties object that contains the + properties of messages used in advanced queuing. See + :ref:`asyncmsgproperties` for more information. + + Each of the parameters are optional. If specified, they act as a shortcut + for setting each of the equivalently named properties. + + .. versionadded:: 3.1.0 + .. method:: AsyncConnection.ping() Pings the database to verify if the connection is valid. +.. method:: AsyncConnection.queue(name, payload_type=None) + + Creates a :ref:`queue ` which is used to enqueue and dequeue + messages in Advanced Queuing. + + The ``name`` parameter is expected to be a string identifying the queue in + which messages are to be enqueued or dequeued. + + 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. + + .. versionadded:: 3.1.0 + .. method:: AsyncConnection.rollback() Rolls back any pending transaction. @@ -214,19 +296,16 @@ AsyncConnection Methods 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 + *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. + 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*. See :ref:`pipelining` for more information. .. note:: - In this release, pipelining support is experimental and subject to - change. - True pipelining requires Oracle Database 23ai. When you connect to an older database, operations are sequentially @@ -258,7 +337,7 @@ AsyncConnection Methods 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. + :meth:`AsyncConnection.tpc_begin()`.The default is *0* seconds. The following code sample demonstrates the ``tpc_begin()`` function:: @@ -284,8 +363,8 @@ AsyncConnection Methods 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 + 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 @@ -356,8 +435,8 @@ AsyncConnection Methods ``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.xid()` function. If an ``xid`` parameter is not passed, + then the transaction identifier used by the previous :meth:`~AsyncConnection.tpc_begin()` is used. The following code sample demonstrates the ``tpc_prepare()`` function:: @@ -417,7 +496,7 @@ 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 + is a string attribute but the value *None* is accepted and treated as an empty string. .. attribute:: AsyncConnection.autocommit @@ -430,10 +509,10 @@ AsyncConnection Attributes 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. + 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 + 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 @@ -498,9 +577,10 @@ AsyncConnection Attributes 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. + 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. .. attribute:: AsyncConnection.instance_name @@ -522,8 +602,7 @@ AsyncConnection Attributes .. note: - This attribute is only available when Oracle Database 12.1 or later is - in use + This attribute is only available with Oracle Database 12.1 or later. .. attribute:: AsyncConnection.max_identifier_length @@ -545,15 +624,15 @@ AsyncConnection Attributes 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. + will get ``ORA-24960``. .. attribute:: AsyncConnection.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 + 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. See :ref:`outputtypehandlers`. @@ -569,20 +648,18 @@ AsyncConnection Attributes 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. + ``SELECT SERIAL# FROM V$SESSION``. - .. versionadded:: 2.5.0 + It is available only in python-oracledb Thin mode. - .. note:: + 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. - This attribute is an extension to the DB API definition. + .. dbapiattributeextension:: - 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. + .. versionadded:: 2.5.0 .. attribute:: AsyncConnection.service_name @@ -594,20 +671,19 @@ AsyncConnection Attributes 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. + ``SELECT SID FROM V$SESSION``. - .. versionadded:: 2.5.0 + It is available only in python-oracledb Thin mode. - .. note:: + 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. - This attribute is an extension to the DB API definition. + .. dbapiattributeextension:: - 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. + .. versionadded:: 2.5.0 .. attribute:: AsyncConnection.stmtcachesize @@ -615,15 +691,15 @@ AsyncConnection Attributes 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. + The default value is *20*. 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). + established with the python-oracledb Thin mode (*True*) or python-oracledb + Thick mode (*False*). .. attribute:: AsyncConnection.transaction_in_progress diff --git a/doc/src/api_manual/async_connection_pool.rst b/doc/src/api_manual/async_connection_pool.rst index f4e5368e..ad3effad 100644 --- a/doc/src/api_manual/async_connection_pool.rst +++ b/doc/src/api_manual/async_connection_pool.rst @@ -5,8 +5,9 @@ API: AsyncConnectionPool Objects ******************************** An AsyncConnectionPool object can be created with -:meth:`oracledb.create_pool_async()`. This object is an extension to the DB -API. +:meth:`oracledb.create_pool_async()`. + +.. dbapiobjectextension:: .. versionadded:: 2.0.0 @@ -119,14 +120,14 @@ AsyncConnectionPool Attributes .. attribute:: AsyncConnectionPool.max_lifetime_session - This read-write attribute returns the maximum length of time (in seconds) - that a pooled connection may exist. Connections that are in use will not be - closed. They become candidates for termination only when they are released - back to the pool and have existed for longer than max_lifetime_session - seconds. Note that termination only occurs when the pool is accessed. A - value of 0 means that there is no maximum length of time that a pooled - connection may exist. This attribute is only available in Oracle Database - 12.1 or later. + 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. .. attribute:: AsyncConnectionPool.max_sessions_per_shard @@ -158,12 +159,10 @@ AsyncConnectionPool Attributes ` 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 + ``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 @@ -175,24 +174,26 @@ AsyncConnectionPool Attributes 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. + setting the ``stmtcachesize`` attribute on the connection itself. 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 + 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. + 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-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. + 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 diff --git a/doc/src/api_manual/async_cursor.rst b/doc/src/api_manual/async_cursor.rst index 253e6a2a..35283468 100644 --- a/doc/src/api_manual/async_cursor.rst +++ b/doc/src/api_manual/async_cursor.rst @@ -6,7 +6,9 @@ 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. +with ``await``. + +.. dbapiobjectextension:: .. versionadded:: 2.0.0 @@ -126,8 +128,8 @@ AsyncCursor Methods 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 + 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 @@ -136,13 +138,13 @@ AsyncCursor Methods 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 + 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. + cursor); otherwise, *None* is returned. .. method:: AsyncCursor.executemany(statement, parameters, batcherrors=False, \ arraydmlrowcounts=False) @@ -163,9 +165,9 @@ AsyncCursor Methods 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. + 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 @@ -182,7 +184,7 @@ AsyncCursor Methods 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 + 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. @@ -216,7 +218,7 @@ AsyncCursor Methods .. method:: AsyncCursor.fetchone() Fetches the next row of a query result set, returning a single tuple or - None when no more data is available. + *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 @@ -225,7 +227,7 @@ AsyncCursor Methods .. method:: AsyncCursor.getarraydmlrowcounts() A synchronous method that retrieves the DML row counts after a call to - :meth:`AsyncCursor.executemany()` with arraydmlrowcounts enabled. This + :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()`. @@ -237,8 +239,8 @@ AsyncCursor Methods .. method:: AsyncCursor.getbatcherrors() 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 + 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. @@ -277,14 +279,14 @@ AsyncCursor Methods 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 + 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 + 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 + 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. @@ -302,7 +304,7 @@ AsyncCursor Methods 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 + 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 @@ -326,6 +328,20 @@ AsyncCursor Methods :meth:`AsyncCursor.callfunc()`, the first parameter in the list refers to the return value of the PL/SQL function. +.. method:: AsyncCursor.scroll(value=0, mode="relative") + + 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. + .. method:: AsyncCursor.setoutputsize(size, [column]) This method does nothing and is retained solely for compatibility with the @@ -378,10 +394,10 @@ AsyncCursor Methods 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 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 + 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. @@ -408,7 +424,7 @@ AsyncCursor Methods 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 + 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. @@ -432,8 +448,8 @@ AsyncCursor Attributes 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. + Due to the performance benefits, the default ``Cursor.arraysize`` is *100* + instead of the *1* that the Python DB API recommends. See :ref:`Tuning Fetch Performance ` for more information. @@ -448,8 +464,8 @@ AsyncCursor Attributes .. attribute:: 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 + 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. .. attribute:: AsyncCursor.fetchvars @@ -465,23 +481,23 @@ AsyncCursor Attributes 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 + 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. + 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 + :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. See :ref:`outputtypehandlers`. @@ -491,7 +507,7 @@ AsyncCursor Attributes 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 + 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 @@ -504,8 +520,8 @@ AsyncCursor Attributes 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 zero. If the - cursor or connection is closed, the value returned is -1. + statements). For all other statements the value is always *0*. If the + cursor or connection is closed, the value returned is *-1*. .. attribute:: AsyncCursor.rowfactory diff --git a/doc/src/api_manual/async_lob.rst b/doc/src/api_manual/async_lob.rst index 05b7b736..1194f8ba 100644 --- a/doc/src/api_manual/async_lob.rst +++ b/doc/src/api_manual/async_lob.rst @@ -6,7 +6,9 @@ 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. +:data:`BFILE` columns are fetched. + +.. dbapiobjectextension:: See :ref:`lobdata` for more information about using LOBs. diff --git a/doc/src/api_manual/connect_params.rst b/doc/src/api_manual/connect_params.rst index e824a9cc..ad09094b 100644 --- a/doc/src/api_manual/connect_params.rst +++ b/doc/src/api_manual/connect_params.rst @@ -4,12 +4,10 @@ API: ConnectParams Objects ************************** -.. note:: +The ConnectParams objects are created by :meth:`oracledb.ConnectParams()`. +See :ref:`usingconnparams` for more information. - This object is an extension to the DB API. - -These objects are created by :meth:`oracledb.ConnectParams()`. See -:ref:`usingconnparams` for more information. +.. dbapiobjectextension:: .. _connparamsmeth: @@ -44,16 +42,16 @@ ConnectParams Methods 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``. + *None*. .. 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, 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, \ + 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, \ @@ -62,11 +60,22 @@ ConnectParams Methods 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, handle=None) + driver_name=oracledb.defaults.driver_name, use_sni=None, \ + thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \ + extra_auth_params=None, pool_Name=None, handle=None) Sets the values for one or more of the parameters of a ConnectParams object. + .. versionchanged:: 3.2.0 + + The ``pool_name`` parameter was added. + + .. versionchanged:: 3.0.0 + + The ``use_sni``, ``thick_mode_dsn_passthrough``, ``extra_auth_params`` + and ``instance_name`` parameters were added. + .. versionchanged:: 2.5.0 The ``program``, ``machine``, ``terminal``, ``osuser``, and @@ -138,13 +147,8 @@ ConnectParams Attributes .. attribute:: ConnectParams.config_dir This read-only attribute is a string that identifies the directory in which - the configuration files such as tnsnames.ora are found. The default is the - value of :attr:`defaults.config_dir`. - - This attribute is only supported in python-oracledb Thin mode. - - For python-oracledb Thick mode, use the ``config_dir`` parameter of - :meth:`oracledb.init_oracle_client()`. + the :ref:`optional configuration files ` are found. The + default is the value of :attr:`defaults.config_dir`. .. attribute:: ConnectParams.connection_id_prefix @@ -174,8 +178,8 @@ ConnectParams Attributes .. 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. + 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. @@ -209,7 +213,7 @@ ConnectParams Attributes mode should be enabled. This attribute is needed for continuous query notification (CQN) and high - availability event notifications. The default value is False. + availability event notifications. The default value is *False*. This attribute is only supported in python-oracledb Thick mode. @@ -218,7 +222,7 @@ ConnectParams Attributes 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 + The default value is *0*. If this attribute is set to a value greater than zero, it enables keepalive. This attribute is supported in both python-oracledb Thin and Thick modes. @@ -226,15 +230,26 @@ ConnectParams Attributes .. attribute:: ConnectParams.externalauth This read-only attribute is a boolean that specifies whether external - authentication should be used. The default value is False. + authentication should be used. 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. + *True*, which may aid code auditing. 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. + + 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 @@ -252,10 +267,19 @@ ConnectParams Attributes .. 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. + communicate with the proxy host. The default value is *0*. + + 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. This attribute is supported in both python-oracledb Thin and Thick modes. + .. versionadded:: 3.0.0 + .. attribute:: ConnectParams.machine This read-only attribute is a string that specifies the machine name of @@ -271,7 +295,8 @@ ConnectParams Attributes .. attribute:: 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. + used when acquiring a connection from the pool. The default value is + *False*. This attribute is only supported in python-oracledb Thick mode. @@ -296,13 +321,13 @@ ConnectParams Attributes .. attribute:: ConnectParams.pool_boundary - This read-only attribute is one of the strings "statement" or "transaction" + 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 + 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 + *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 @@ -312,10 +337,20 @@ ConnectParams Attributes .. versionadded:: 2.1.0 +.. attribute:: ConnectParams.pool_name + + This read-only attribute is a string that specifies the name of the pool + when using multiple DRCP pools with Oracle Database 23.4 or later. See + :ref:`DRCP Pool Names `. + + This attribute is supported in both python-oracledb Thin and Thick modes. + + .. versionadded:: 3.2.0 + .. attribute:: ConnectParams.port This read-only attribute is an integer that returns the port number on - which the database listener is listening. The default value is 1521. + which the database listener is listening. The default value is *1521*. This attribute is supported in both python-oracledb Thin and Thick modes. @@ -336,7 +371,7 @@ ConnectParams Attributes 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". + the value *tcp* or *tcps*. The default value is *tcp*. This attribute is supported in both python-oracledb Thin and Thick modes. @@ -363,20 +398,20 @@ ConnectParams Attributes 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. + terminated. The default value is *0*. 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. + to wait before making a new connection attempt. The default value is *1*. This attribute is supported in both python-oracledb Thin and Thick modes. .. versionchanged:: 2.3.0 - The default value of this attribute was changed from 0 seconds to 1 + The default value of this attribute was changed from *0* seconds to *1* second. .. attribute:: ConnectParams.sdu @@ -387,7 +422,7 @@ ConnectParams Attributes 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. @@ -399,7 +434,7 @@ ConnectParams Attributes 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`. + *dedicated*, *shared*, or *pooled*. This attribute is supported in both python-oracledb Thin and Thick modes. @@ -445,7 +480,7 @@ ConnectParams Attributes 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`. + attribute is not set to the value *True*. This attribute is supported in both python-oracledb Thin and Thick modes. @@ -454,7 +489,7 @@ ConnectParams Attributes 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. + *True*. Note that if the :attr:`~ConnectParams.ssl_server_cert_dn` attribute is not specified, then host name matching is performed instead. @@ -463,8 +498,8 @@ ConnectParams Attributes .. 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 + 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. @@ -499,14 +534,24 @@ ConnectParams Attributes 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. + The default value is *20.0*. This attribute is supported in both python-oracledb Thin and Thick modes. .. versionchanged:: 2.3.0 - The default value of this attribute was changed from 60.0 seconds to - 20.0 seconds. + 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 @@ -520,6 +565,18 @@ ConnectParams Attributes .. versionadded:: 2.5.0 +.. attribute:: ConnectParams.thick_mode_dsn_passthrough + + 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 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 @@ -528,7 +585,7 @@ ConnectParams Attributes adbsb/adbsb-overview.html#GUID-A7435462-9D74-44B4-8240-4A6F06E92348>`__ 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. + with certain versions of ADB-S. The default value is *False*. 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 0faaa491..2d70fef2 100644 --- a/doc/src/api_manual/connection.rst +++ b/doc/src/api_manual/connection.rst @@ -20,18 +20,14 @@ Connection Methods The entry point for the connection as a context manager. It returns itself. - .. note:: - - This method is an extension to the DB API definition. + .. dbapimethodextension:: .. method:: Connection.__exit__() The exit point for the connection as a context manager. This will close the connection and roll back any uncommitted transaction. - .. note:: - - This method is an extension to the DB API definition. + .. dbapimethodextension:: .. method:: Connection.begin([formatId, transactionId, branchId]) @@ -48,26 +44,20 @@ Connection Methods Use the method :meth:`Connection.tpc_begin()` instead. - .. note:: - - This method is an extension to the DB API definition. + .. dbapimethodextension:: .. method:: Connection.cancel() Breaks a long-running statement. - .. note:: - - This method is an extension to the DB API definition. + .. dbapimethodextension:: .. method:: Connection.changepassword(oldpassword, newpassword) Changes the password for the user to which the connection is connected. - .. note:: - - This method is an extension to the DB API definition. + .. dbapimethodextension:: .. method:: Connection.close() @@ -102,9 +92,7 @@ Connection Methods The parameter ``data`` was added. - .. note:: - - This method is an extension to the DB API definition. + .. dbapimethodextension:: .. method:: Connection.cursor(scrollable=False) @@ -112,23 +100,85 @@ Connection Methods .. 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. + 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. .. versionadded:: 2.1.0 .. method:: Connection.encode_oson(value) - Encodes a Python value into `OSON-encoded - `__ + 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 +.. method:: Connection.fetch_df_all(statement, parameters=None, \ + arraysize=None) + + 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. + + 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 ``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. + + Any LOB fetched must be less than 1 GB. + + See :ref:`dataframeformat` for the supported data types and examples. + + .. note:: + + The data frame support in python-oracledb 3.2 is a pre-release and may + change in a future version. + + .. dbapimethodextension:: + + .. 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. + + 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. + + Any LOB fetched must be less than 1 GB. + + See :ref:`dataframeformat` for the supported data types and examples. + + .. note:: + + The data frame support in python-oracledb 3.2 is a pre-release and may + change in a future version. + + .. dbapimethodextension:: + + .. versionadded:: 3.0.0 + .. method:: Connection.getSodaDatabase() Returns a :ref:`SodaDatabase ` object for Simple Oracle Document @@ -138,27 +188,24 @@ Connection Methods ctx=dblatest&id=GUID-BE42F8D3-B86B-43B4-B2A3-5760A4DF79FB>`__ for additional information on SODA. - .. note:: - - This method is an extension to the DB API definition. + .. dbapimethodextension:: .. 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 + 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. + .. dbapimethodextension:: .. method:: Connection.is_healthy() - This function returns a boolean indicating the health status of a connection. + This function 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. + 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 :ref:`standalone connections `. For pooled @@ -166,12 +213,14 @@ Connection Methods performs this check before returning a connection to the application, see :ref:`poolhealth`. - If this function returns False, the connection should be not be used by the - application and a new connection should be established instead. + 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:`Connection.ping()` which performs a round-trip to the database. + .. dbapimethodextension:: + .. method:: Connection.msgproperties(payload, correlation, delay, exceptionq, expiration, priority) Returns an object specifying the properties of messages used in advanced @@ -180,13 +229,13 @@ Connection Methods Each of the parameters are optional. If specified, they act as a shortcut for setting each of the equivalently named properties. - .. note:: - - This method is an extension to the DB API definition. + .. dbapimethodextension:: .. method:: Connection.ping() - Pings the database to verify if the connection is valid. + Pings the database to verify if the connection is valid. An exception is + thrown if it is not, in which case the connection should not be used by the + application and a new connection should be established instead. This function performs a :ref:`round-trip ` to the database, so it should not be used unnecessarily. @@ -194,23 +243,21 @@ Connection Methods Note connection pools will perform the same health check automatically, based on configuration settings. See :ref:`poolhealth`. - .. note:: + Also, see :meth:`Connection.is_healthy()` for a lightweight alternative. - This method is an extension to the DB API definition. + .. dbapimethodextension:: .. method:: Connection.prepare() - Prepares the distributed (global) transaction for commit. Return a boolean + 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). + error ``ORA-24756 (transaction does not exist)``. .. deprecated:: python-oracledb 1.0 Use the method :meth:`Connection.tpc_prepare()` instead. - .. note:: - - This method is an extension to the DB API definition. + .. dbapimethodextension:: .. method:: Connection.queue(name, payload_type=None) @@ -226,12 +273,10 @@ Connection Methods dequeued. If not specified, RAW data is enqueued and dequeued. For consistency and compliance with the PEP 8 naming style, the - parameter `payloadType` was renamed to `payload_type`. The old name + parameter ``payloadType`` was renamed to ``payload_type``. The old name will continue to work as a keyword parameter for a period of time. - .. note:: - - This method is an extension to the DB API definition. + .. dbapimethodextension:: .. method:: Connection.rollback() @@ -239,9 +284,10 @@ Connection Methods .. method:: Connection.shutdown([mode]) - 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`. + 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: :: @@ -255,21 +301,19 @@ Connection Methods cursor.execute("alter database dismount") connection.shutdown(mode = oracledb.DBSHUTDOWN_FINAL) - .. note:: - - This method is an extension to the DB API definition. + .. dbapimethodextension:: .. 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. + 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). + 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: @@ -285,9 +329,7 @@ Connection Methods cursor.execute("alter database mount") cursor.execute("alter database open") - .. note:: - - This method is an extension to the DB API definition. + .. dbapimethodextension:: .. method:: Connection.subscribe(namespace=oracledb.SUBSCR_NAMESPACE_DBCHANGE, \ protocol=oracledb.SUBSCR_PROTO_OCI, callback=None, timeout=0, \ @@ -299,39 +341,40 @@ Connection Methods 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 + 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 ``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 ``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 ``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 ``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 ``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: + 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 + 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. @@ -340,12 +383,12 @@ Connection Methods 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`. + ``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 + 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 @@ -360,16 +403,14 @@ Connection Methods 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 + 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. - .. note:: - - This method is an extension to the DB API definition. + .. dbapimethodextension:: .. note:: @@ -384,21 +425,23 @@ Connection Methods 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 ``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 ``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. + 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. The following code sample demonstrates the ``tpc_begin()`` function:: @@ -409,22 +452,25 @@ Connection Methods .. 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. + 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. + 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. The following code sample demonstrates the ``tpc_commit()`` function:: @@ -435,15 +481,17 @@ Connection Methods .. method:: Connection.tpc_end(xid, flags) - Ends or suspends work on a global transaction. This function is only intended - for use by transaction managers. + 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. + 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`. + 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 @@ -458,11 +506,11 @@ Connection Methods .. 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. + 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. + The ``xid`` parameter is mandatory and should be an object should be + returned by the :meth:`~Connection.xid()` function. The following code sample demonstrates the ``tpc_forget()`` function:: @@ -478,13 +526,14 @@ Connection Methods :meth:`~Connection.tpc_commit()` or :meth:`~Connection.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``. + 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. + 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. The following code sample demonstrates the ``tpc_prepare()`` function:: @@ -495,13 +544,14 @@ Connection Methods .. 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. + 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 view ``DBA_PENDING_TRANSACTIONS`` and requires ``SELECT`` - privilege on that view. + This function queries the DBA_PENDING_TRANSACTIONS view and requires + "SELECT" privilege on that view. The following code sample demonstrates the ``tpc_recover()`` function:: @@ -514,12 +564,13 @@ Connection Methods 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 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. + :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. The following code sample demonstrates the ``tpc_rollback()`` function:: @@ -545,13 +596,15 @@ Connection Methods 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 ``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. + 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. The following code sample demonstrates the ``xid()`` function:: @@ -567,12 +620,10 @@ Connection Attributes .. attribute:: 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 + is a string attribute but the value *None* is accepted and treated as an empty string. - .. note:: - - This attribute is an extension to the DB API definition. + .. dbapiattributeextension:: .. attribute:: Connection.autocommit @@ -580,47 +631,41 @@ Connection Attributes When autocommit mode is on, all statements are committed as soon as they have completed executing. - .. note:: - - This attribute is an extension to the DB API definition. + .. dbapiattributeextension:: .. attribute:: Connection.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. + occur. A value of *0* means that no timeout will take place. + + In python-oracledb Thick mode, this attribute is only available in Oracle + Client 18c or later. - If a timeout occurs, the error *DPI-1067* will be returned if the - connection is still usable. Alternatively the error *DPI-1080* will be + 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. 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 + 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. - .. note:: - - 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 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. + .. dbapiattributeextension:: .. 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. + .. dbapiattributeextension:: .. attribute:: Connection.current_schema @@ -630,9 +675,7 @@ Connection Attributes 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. + .. dbapiattributeextension:: .. attribute:: Connection.db_domain @@ -640,11 +683,9 @@ Connection Attributes associated with the connection. It is the same value returned by the SQL ``SELECT value FROM V$PARAMETER WHERE NAME = 'db_domain'``. - .. versionadded:: 2.0.0 + .. dbapiattributeextension:: - .. note:: - - This attribute is an extension to the DB API definition. + .. versionadded:: 2.0.0 .. attribute:: Connection.db_name @@ -652,11 +693,9 @@ Connection Attributes the connection. It is the same value returned by the SQL ``SELECT NAME FROM V$DATABASE``. - .. versionadded:: 2.0.0 + .. dbapiattributeextension:: - .. note:: - - This attribute is an extension to the DB API definition. + .. versionadded:: 2.0.0 .. attribute:: Connection.dbop @@ -664,18 +703,14 @@ Connection Attributes 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. + .. dbapiattributeextension:: .. attribute:: Connection.dsn 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. + .. dbapiattributeextension:: .. attribute:: Connection.econtext_id @@ -688,18 +723,14 @@ Connection Attributes 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. + .. dbapiattributeextension:: .. attribute:: Connection.external_name This read-write attribute specifies the external name that is used by the connection when logging distributed transactions. - .. note:: - - This attribute is an extension to the DB API definition. + .. dbapiattributeextension:: .. attribute:: Connection.handle @@ -709,24 +740,21 @@ Connection Attributes This property is only relevant in the python-oracledb Thick mode. - .. note:: - - This attribute is an extension to the DB API definition. + .. dbapiattributeextension:: .. attribute:: Connection.inputtypehandler 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. + 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. See :ref:`inputtypehandlers`. - .. note:: - - This attribute is an extension to the DB API definition. + .. dbapiattributeextension:: .. attribute:: Connection.instance_name @@ -734,33 +762,33 @@ Connection Attributes associated with the connection. It is the same value as the SQL expression ``sys_context('userenv', 'instance_name')``. - .. versionadded:: 1.4.0 + .. dbapiattributeextension:: - .. note:: - - This attribute is an extension to the DB API definition. + .. versionadded:: 1.4.0 .. attribute:: Connection.internal_name This read-write attribute specifies the internal name that is used by the connection when logging distributed transactions. - .. note:: - - This attribute is an extension to the DB API definition. + .. dbapiattributeextension:: .. attribute:: Connection.ltxid 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. + ensuring that transactions are not duplicated. See :ref:`tg` for more + information. + + This is only available with Oracle Database 12.1 or later. In + python-oracledb Thick mode, it also requires Oracle Client libraries 12.1 + or later. + + .. dbapiattributeextension:: - .. note: + .. versionchanged:: 3.0.0 - This attribute is an extension to the DB API definition. It is only - available when Oracle Database 12.1 or higher is in use on both the - server and the client. + This attribute was added to python-oracledb Thin mode. .. attribute:: Connection.max_identifier_length @@ -769,7 +797,7 @@ Connection Attributes established. See `Database Object Naming Rules `__. The value may be - ``None``, 30, or 128. The value ``None`` indicates the size cannot 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. @@ -780,32 +808,29 @@ Connection Attributes 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'``. + SQL ``SELECT VALUE FROM V$PARAMETER WHERE NAME = 'open_cursors'``. When + using python-oracledb Thick mode, Oracle Client libraries 12.1 (or later) + are required. - .. versionadded:: 2.0.0 - - .. note:: + .. dbapiattributeextension:: - This attribute is an extension to the DB API definition. + .. versionadded:: 2.0.0 .. attribute:: Connection.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. - - .. note: - - This attribute is an extension to the DB API definition. + will get ``ORA-24960``. + .. dbapiattributeextension:: .. 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 + 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. See :ref:`outputtypehandlers`. @@ -816,20 +841,16 @@ 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 This read-only attribute returns the name of the user which was used as a proxy when creating the connection to the database. - .. versionadded:: 2.0.0 - - .. note:: + .. dbapiattributeextension:: - This attribute is an extension to the DB API definition. + .. versionadded:: 2.0.0 .. attribute:: Connection.sdu @@ -839,11 +860,9 @@ Connection Attributes network configuration. It is available only in the python-oracledb Thin mode. - .. versionadded:: 2.0.0 + .. dbapiattributeextension:: - .. note:: - - This attribute is an extension to the DB API definition. + .. versionadded:: 2.0.0 .. attribute:: Connection.serial_num @@ -852,17 +871,15 @@ Connection Attributes ``SELECT SERIAL# FROM V$SESSION WHERE SID=SYS_CONTEXT('USERENV', 'SID')``. It is available only in python-oracledb Thin mode. - .. versionadded:: 2.5.0 - .. note:: + 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. - This attribute is an extension to the DB API definition. + .. dbapiattributeextension:: - 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. + .. versionadded:: 2.5.0 .. attribute:: Connection.service_name @@ -870,11 +887,9 @@ Connection Attributes associated with the connection. This is the same value returned by the SQL ``SELECT SYS_CONTEXT('USERENV', 'SERVICE_NAME') FROM DUAL``. - .. versionadded:: 2.0.0 + .. dbapiattributeextension:: - .. note:: - - This attribute is an extension to the DB API definition. + .. versionadded:: 2.0.0 .. attribute:: Connection.session_id @@ -883,17 +898,14 @@ Connection Attributes ``SELECT SYS_CONTEXT('USERENV', 'SID') FROM DUAL``. It is available only in python-oracledb Thin mode. - .. versionadded:: 2.5.0 - - .. note:: + 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. - This attribute is an extension to the DB API definition. + .. dbapiattributeextension:: - 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. + .. versionadded:: 2.5.0 .. attribute:: Connection.stmtcachesize @@ -901,75 +913,64 @@ Connection Attributes 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. + The default value is *20*. See :ref:`Statement Caching ` for more information. - .. note:: - - This attribute is an extension to the DB API definition. + .. dbapiattributeextension:: .. 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". + 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". - 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()`. + 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()`. - .. note:: - - This attribute is an extension to the DB API definition. + .. dbapiattributeextension:: .. attribute:: Connection.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). + established with the python-oracledb Thin mode (*True*) or python-oracledb + Thick mode (*False*). - .. note:: - - This attribute is an extension to the DB API definition. + .. dbapiattributeextension:: .. attribute:: Connection.transaction_in_progress This read-only attribute specifies whether a transaction is currently in progress on the database associated with the connection. - .. versionadded:: 2.0.0 - - .. note:: + .. dbapiattributeextension:: - This attribute is an extension to the DB API definition. + .. versionadded:: 2.0.0 .. attribute:: 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 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). + 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). .. attribute:: Connection.warning @@ -994,10 +995,8 @@ Connection Attributes connection creations, in which case those connection warnings will be returned. - If no warning was generated the value ``None`` is returned. + If no warning was generated the value *None* is returned. - .. versionadded:: 2.0.0 - - .. note:: + .. dbapiattributeextension:: - This attribute is an extension to the DB API definition. + .. versionadded:: 2.0.0 diff --git a/doc/src/api_manual/connection_pool.rst b/doc/src/api_manual/connection_pool.rst index 6b53999b..2de1ad9b 100644 --- a/doc/src/api_manual/connection_pool.rst +++ b/doc/src/api_manual/connection_pool.rst @@ -4,10 +4,6 @@ API: ConnectionPool Objects *************************** -.. note:: - - This object is an extension to the DB API. - 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 @@ -16,11 +12,13 @@ lookup?ctx=dblatest&id=GUID-F9662FFB-EAEF-495C-96FC-49C6D1D9625C>`__. This implementation is only used in the python-oracledb Thick mode and is not available in the 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 @@ -66,7 +64,7 @@ ConnectionPool Methods 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 + 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 @@ -75,8 +73,8 @@ ConnectionPool Methods 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`. + database shard to connect to. The key values can be strings, numbers, + bytes, or dates. See :ref:`connsharding`. When using the :ref:`connection pool cache `, calling :meth:`oracledb.connect()` with a ``pool_alias`` parameter is the same as @@ -88,7 +86,7 @@ ConnectionPool Methods 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. + this method will fail unless the ``force`` parameter is set to *True*. .. method:: ConnectionPool.drop(connection) @@ -163,11 +161,11 @@ ConnectionPool Methods 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 + 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. + parameter are not *None*, the connection will be retagged when it is + released back to the pool. .. _connpoolattr: @@ -216,14 +214,18 @@ ConnectionPool Attributes .. attribute:: ConnectionPool.max_lifetime_session - This read-write attribute returns the maximum length of time (in seconds) - that a pooled connection may exist. Connections that are in use will not be - closed. They become candidates for termination only when they are released - back to the pool and have existed for longer than max_lifetime_session - seconds. Note that termination only occurs when the pool is accessed. A - value of 0 means that there is no maximum length of time that a pooled - connection may exist. This attribute is only available in Oracle Database - 12.1 or later. + 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. + + .. versionchanged:: 3.0.0 + + This attribute was added to python-oracledb Thin mode. .. attribute:: ConnectionPool.max_sessions_per_shard @@ -231,7 +233,7 @@ ConnectionPool Attributes 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 zero will not set any maximum number + 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. @@ -259,17 +261,17 @@ ConnectionPool Attributes ` 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. + a negative value disables pinging. Setting it to *0* forces a ping for + every :meth:`ConnectionPool.acquire()` and is not recommended. - Prior to cx_Oracle 8.2, the ping interval was fixed at 60 seconds. + 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 + 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. @@ -279,23 +281,23 @@ ConnectionPool Attributes 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. + setting the ``stmtcachesize`` attribute on the connection itself. 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 + 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. + 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 + 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. diff --git a/doc/src/api_manual/cursor.rst b/doc/src/api_manual/cursor.rst index e9372ac2..3ebf2782 100644 --- a/doc/src/api_manual/cursor.rst +++ b/doc/src/api_manual/cursor.rst @@ -13,27 +13,19 @@ Cursor Methods The entry point for the cursor as a context manager. It returns itself. - .. note:: - - This method is an extension to the DB API definition. - + .. dbapimethodextension:: .. method:: Cursor.__exit__() The exit point for the cursor as a context manager. It closes the cursor. - .. note:: - - This method is an extension to the DB API definition. + .. dbapimethodextension:: .. method:: Cursor.__iter__() Returns the cursor itself to be used as an iterator. - .. note:: - - 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]) @@ -53,18 +45,14 @@ Cursor Methods `example `__ needs to be used. - .. note:: - - The DB API definition does not define this method. + .. dbapimethodextension:: .. method:: Cursor.bindnames() Returns the list of bind variable names bound to the statement. Note that a statement must have been prepared first. - .. note:: - - The DB API definition does not define this method. + .. dbapimethodextension:: .. method:: Cursor.callfunc(name, return_type, parameters=[], \ keyword_parameters={}) @@ -88,9 +76,7 @@ Cursor Methods ``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:: @@ -152,8 +138,8 @@ Cursor Methods 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 + 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 @@ -162,13 +148,13 @@ Cursor Methods 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 + 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. + cursor); otherwise, *None* is returned. .. note:: @@ -193,27 +179,27 @@ Cursor Methods 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. + 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 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()`. + 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()`. - When True, the ``arraydmlrowcounts`` parameter enables DML row counts to be - retrieved from Oracle after the method has completed. The row counts can + 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()`. Both the ``batcherrors`` parameter and the ``arraydmlrowcounts`` parameter - can only be True when executing an insert, update, delete or merge + 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:`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 + *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() @@ -236,9 +222,9 @@ Cursor Methods 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. + 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. @@ -247,8 +233,8 @@ Cursor Methods .. method:: Cursor.fetchone() - Fetches the next row of a query result set, returning a single tuple or None - when no more data is available. + 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. @@ -258,25 +244,22 @@ Cursor Methods .. 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 + 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:: + This method is only available for Oracle Database 12.1 and later. - 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 + :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:: - - The DB API definition does not define this method. + .. dbapimethodextension:: .. method:: Cursor.getimplicitresults() @@ -292,12 +275,12 @@ Cursor Methods python-oracledb :ref:`Thick ` mode, Oracle Client 12.1 (or later) is additionally required. - .. note:: + .. dbapimethodextension:: - 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. + 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) @@ -305,9 +288,7 @@ Cursor Methods (parsing step is done automatically by Oracle when a statement is :meth:`executed `). - .. note:: - - The DB API definition does not define this method. + .. dbapimethodextension:: .. note:: @@ -321,40 +302,35 @@ Cursor Methods :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. + 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 + 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 + 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. See :ref:`Statement Caching ` for more information. - .. note:: - - The DB API definition does not define this method. + .. dbapimethodextension:: .. method:: Cursor.scroll(value=0, mode="relative") 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 + 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 + An error is raised if the mode is *relative* or *absolute* and the scroll operation would position the cursor outside of the result set. - .. note:: - - 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.setinputsizes(*args, **keywordArgs) @@ -367,7 +343,7 @@ Cursor Methods 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 + 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 @@ -442,10 +418,10 @@ Cursor Methods 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 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 + 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. @@ -464,15 +440,15 @@ Cursor Methods function. The ``bypass_decode`` parameter, if specified, should be passed as a - boolean value. Passing a `True` value causes values of database types + 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`, + :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 + 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. @@ -485,9 +461,7 @@ Cursor Methods The ``convert_nulls`` parameter was added. - .. note:: - - The DB API definition does not define this method. + .. dbapimethodextension:: Cursor Attributes ================= @@ -506,8 +480,8 @@ Cursor Attributes 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. + Due to the performance benefits, the default ``Cursor.arraysize`` is *100* + instead of the *1* that the Python DB API recommends. See :ref:`Tuning Fetch Performance ` for more information. @@ -519,25 +493,20 @@ Cursor Attributes 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. + .. dbapiattributeextension:: .. attribute:: Cursor.connection This read-only attribute returns a reference to the connection object on which the cursor was created. - .. note:: - - This attribute 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. .. attribute:: Cursor.description 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 + 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. @@ -554,9 +523,7 @@ Cursor Attributes referencing this attribute. In particular, elements should not be removed or replaced. - .. note:: - - The DB API definition does not define this attribute. + .. dbapiattributeextension:: .. attribute:: Cursor.inputtypehandler @@ -564,50 +531,47 @@ Cursor Attributes 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 + 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. See :ref:`inputtypehandlers`. - .. note:: - - This attribute is an extension to the DB API definition. + .. dbapiattributeextension:: .. 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. + 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 + :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. 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. + 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. @@ -617,17 +581,15 @@ Cursor Attributes See :ref:`Tuning Fetch Performance ` for more information. - .. note:: - - The DB API definition does not define this method. + .. dbapimethodextension:: .. 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 zero. If the - cursor or connection is closed, the value returned is -1. + 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*. .. attribute:: Cursor.rowfactory @@ -639,9 +601,7 @@ Cursor Attributes See :ref:`rowfactories`. - .. note:: - - The DB API definition does not define this attribute. + .. dbapiattributeextension:: .. attribute:: Cursor.scrollable @@ -651,9 +611,7 @@ Cursor Attributes attribute is checked and the corresponding mode set in Oracle when calling the method :meth:`Cursor.execute()`. - .. note:: - - The DB API definition does not define this attribute. + .. dbapiattributeextension:: .. attribute:: Cursor.statement @@ -661,9 +619,7 @@ Cursor Attributes prepared with :meth:`Cursor.prepare()` or executed with :meth:`Cursor.execute()`. - .. note:: - - The DB API definition does not define this attribute. + .. dbapiattributeextension:: .. attribute:: Cursor.warning @@ -673,12 +629,10 @@ Cursor Attributes :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. + *None* is returned. 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 new file mode 100644 index 00000000..8cd01dcf --- /dev/null +++ b/doc/src/api_manual/dataframe.rst @@ -0,0 +1,228 @@ +.. _oracledataframe: + +**************** +API: Data Frames +**************** + +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 +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.2 is a pre-release and may + change in a future 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. + +.. dbapiobjectextension:: + +.. 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. + +.. method:: OracleDataFrame.get_chunks(n_chunks) + + Returns itself, since python-oracledb only uses one chunk. + +.. method:: OracleDataFrame.get_column(i) + + Returns an :ref:`OracleColumn ` object for the column + at the given index ``i``. + +.. method:: OracleDataFrame.get_column_by_name(name) + + Returns an :ref:`OracleColumn ` object for the column + with the given name ``name``. + +.. method:: OracleDataFrame.get_columns() + + 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() + + Returns the number of columns in the data frame. + +.. method:: OracleDataFrame.num_rows() + + Returns the number of rows in the data frame. + +.. _oracledataframeattr: + +OracleDataFrame Attributes +-------------------------- + +.. attribute:: OracleDataFrame.metadata + + 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. + +.. _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 + +.. _oraclecolumnbufferattr: + +OracleColumnBuffer Attributes +----------------------------- + +.. attribute:: OracleColumnBuffer.bufsize + + This read-only property returns the buffer size in bytes. + +.. attribute:: OracleColumnBuffer.ptr + + This read-only attribute specifies the pointer to the start of the buffer + as an integer. diff --git a/doc/src/api_manual/dbobject_type.rst b/doc/src/api_manual/dbobject_type.rst index 123ec699..5743e25c 100644 --- a/doc/src/api_manual/dbobject_type.rst +++ b/doc/src/api_manual/dbobject_type.rst @@ -4,11 +4,11 @@ API: DbObjectType Objects ************************* -.. note:: +The DbObjectType object is returned by the :meth:`Connection.gettype()` call +and is available as the :data:`Variable.type` for variables containing Oracle +Database objects. - 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. +.. dbapiobjectextension:: DbObjectType Methods ==================== @@ -38,8 +38,8 @@ DbObjectType Attributes .. attribute:: DbObjectType.element_type 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 + 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 `. @@ -58,7 +58,7 @@ DbObjectType Attributes .. attribute:: DbObjectType.package_name 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`). + refers to a PL/SQL type (otherwise, it returns the value *None*). .. attribute:: DbObjectType.schema @@ -70,12 +70,11 @@ DbObjectType Attributes DbObject Objects ================ -.. note:: +The DbObject object 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. - 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. +.. dbapiobjectextension:: DbObject Methods ++++++++++++++++ @@ -115,8 +114,8 @@ DbObject Methods .. method:: DbObject.exists(index) - Returns True or False indicating if an element exists in the collection at - the specified index. + Returns *True* or *False* indicating if an element exists in the collection + at the specified index. .. method:: DbObject.extend(sequence) @@ -129,7 +128,7 @@ DbObject Methods .. method:: DbObject.first() Returns the index of the first element in the collection. If the collection - is empty, None is returned. + is empty, *None* is returned. .. method:: DbObject.getelement(index) @@ -141,21 +140,21 @@ DbObject Methods .. method:: DbObject.last() Returns the index of the last element in the collection. If the collection - is empty, None is returned. + is empty, *None* is returned. .. method:: DbObject.next(index) 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. + specified index, *None* is returned. .. method:: DbObject.prev(index) 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. + specified index, *None* is returned. .. method:: DbObject.setelement(index, value) @@ -186,11 +185,9 @@ DbObject Attributes DbObjectAttribute Objects ========================= -.. note:: - - 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 @@ -199,7 +196,7 @@ DbObjectAttribute Objects :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`. + *None*. .. versionadded:: 3.0.0 @@ -213,7 +210,7 @@ DbObjectAttribute Objects 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`. + the value returned is *None*. .. versionadded:: 3.0.0 @@ -222,7 +219,7 @@ DbObjectAttribute Objects 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`. + the value returned is *None*. .. versionadded:: 3.0.0 diff --git a/doc/src/api_manual/defaults.rst b/doc/src/api_manual/defaults.rst index 938e52d1..4174e881 100644 --- a/doc/src/api_manual/defaults.rst +++ b/doc/src/api_manual/defaults.rst @@ -25,25 +25,42 @@ Defaults Attributes 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. + This attribute has an initial value of *100*. .. attribute:: defaults.config_dir - The directory in which optional configuration files such as - ``tnsnames.ora`` will be read in python-oracledb Thin mode. This attribute - takes its initial value from the environment variable ``TNS_ADMIN``. + The directory in which the optional configuration file ``tnsnames.ora`` + will be read in python-oracledb Thin mode. - This attribute is not used by the python-oracledb Thick mode: the usual - Oracle Client search path behavior for configuration files is followed, see + At time of ``import oracledb`` the value of + ``oracledb.defaults.config_dir`` will be set to (first one wins): + + - 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`. + .. 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 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 + 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 @@ -52,7 +69,7 @@ Defaults Attributes 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 + 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`. @@ -66,36 +83,34 @@ Defaults Attributes 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 + An output type handler such as previously required in the obsolete + cx_Oracle driver 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. + 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`. + 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`. - 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. + An output type handler such as the one previously required in the obsolete + cx_Oracle driver 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. The value of ``oracledb.defaults.fetch_lobs`` does not affect LOBs returned as OUT binds. - This attribute has an initial value of True. + This attribute has an initial value of *True*. .. attribute:: defaults.machine @@ -127,7 +142,11 @@ Defaults Attributes The default value for :attr:`Cursor.prefetchrows`. This is a query tuning attribute, see :ref:`Tuning Fetch Performance `. - This attribute has an initial value of 2. + 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*. .. attribute:: defaults.program @@ -148,7 +167,7 @@ Defaults Attributes :attr:`ConnectionPool.stmtcachesize`. This is a tuning attribute, see :ref:`stmtcache`. - This attribute has an initial value of 20. + This attribute has an initial value of *20*. .. attribute:: defaults.terminal @@ -156,8 +175,57 @@ Defaults Attributes connection originates. This is the value used in the TERMINAL column of the V$SESSION view. - This attribute has an initial value of "unknown". + This attribute has an initial value of *unknown*. This attribute is only used in python-oracledb Thin mode. .. 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. + + 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. + + When ``thick_mode_dsn_passthrough`` is `False`, python-oracledb Thick mode + behaves similarly to Thin mode, which can be helpful for applications that + may be run in either mode: + + - The search path used to locate and read any optional :ref:`tnsnames.ora + ` file is handled in the python-oracledb driver. Different + :ref:`tnsnames.ora ` files can be used by each + connection. Note loading of optional Thick mode files such as + ``sqlnet.ora`` and ``oraaccess.xml`` is always handled by Oracle Client + libraries regardless of the value of ``thick_mode_dsn_passthrough`` + because it is those libraries that use these files. + + - All connect strings will be parsed by the python-oracledb driver and a + generated connect descriptor is sent to the database. Parameters + unrecognized by python-oracledb in :ref:`Easy Connect strings + ` are discarded. In :ref:`full connect descriptors + ` passed explicitly as the ``dsn`` parameter value or + stored in a :ref:`tnsnames.ora ` file, any parameters that + are unrecognized by python-oracledb in the ``DESCRIPTION``, + ``CONNECT_DATA`` and ``SECURITY`` sections will be passed through to the + database unchanged, while unrecognized parameters in other sections are + discarded. + + - If a :ref:`Centralized Configuration Provider ` + 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..92bb3dc3 100644 --- a/doc/src/api_manual/deprecations.rst +++ b/doc/src/api_manual/deprecations.rst @@ -11,8 +11,9 @@ 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.0 :header-rows: 1 @@ -23,7 +24,8 @@ 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 diff --git a/doc/src/api_manual/fetch_info.rst b/doc/src/api_manual/fetch_info.rst index 61bb2ed5..9522560a 100644 --- a/doc/src/api_manual/fetch_info.rst +++ b/doc/src/api_manual/fetch_info.rst @@ -12,11 +12,9 @@ behaves as a 7-tuple containing the values for the attributes ``name``, 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``. -.. versionadded:: 1.4.0 - -.. note:: +.. dbapiobjectextension:: - This object is an extension the DB API. +.. versionadded:: 1.4.0 FetchInfo Attributes ==================== @@ -26,7 +24,7 @@ FetchInfo Attributes 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 + 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. @@ -42,7 +40,7 @@ FetchInfo Attributes 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 + 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. @@ -54,7 +52,7 @@ FetchInfo Attributes 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 + 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. @@ -69,17 +67,16 @@ FetchInfo Attributes .. 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 - ``oracledb.DB_TYPE_JSON`` as well as when an "IS JSON" constraint is + 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. + binary encoded `OSON `__ data. This will be *True* + when an "IS JSON FORMAT OSON" check constraint is enabled on BLOB columns. .. versionadded:: 2.1.0 @@ -121,7 +118,7 @@ FetchInfo Attributes 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``. + number of dimensions, the value returned is *None*. .. versionadded:: 2.2.0 @@ -140,6 +137,17 @@ FetchInfo Attributes floating-point numbers If the column is not a VECTOR column or allows for any type of storage, - the value returned is ``None``. + the value returned is *None*. .. 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``. + + .. versionadded:: 3.0.0 diff --git a/doc/src/api_manual/lob.rst b/doc/src/api_manual/lob.rst index 21b5ddf5..5fcdceb9 100644 --- a/doc/src/api_manual/lob.rst +++ b/doc/src/api_manual/lob.rst @@ -7,10 +7,10 @@ API: LOB Objects A LOB object can be created with :meth:`Connection.createlob()`. See :ref:`lobdata` for more information about using LOBs. -.. note:: +This object is returned by default whenever Oracle :data:`CLOB`, :data:`BLOB` +and :data:`BFILE` columns are fetched. - This object is an extension the DB API. It is returned whenever Oracle - :data:`CLOB`, :data:`BLOB` and :data:`BFILE` columns are fetched. +.. dbapiobjectextension:: LOB Methods =========== diff --git a/doc/src/api_manual/module.rst b/doc/src/api_manual/module.rst index 10593163..1bad3c95 100644 --- a/doc/src/api_manual/module.rst +++ b/doc/src/api_manual/module.rst @@ -22,37 +22,32 @@ Oracledb Methods values are the major version, minor version, update number, patch number, and port update number. - .. 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:: + This function can only be called when python-oracledb is in Thick + mode. Using it in Thin mode will throw an exception. See + :ref:`enablingthick`. - This method is an extension to the DB API definition. + .. dbapimethodextension:: .. 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, 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, \ + 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, handle=0) + driver_name=oracledb.defaults.driver_name, use_sni=False, \ + thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \ + extra_auth_params=None, pool_name=None, handle=0) Constructor for creating a connection to the database. Returns a :ref:`Connection Object `. All parameters are optional and can be @@ -147,12 +142,13 @@ Oracledb Methods 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. + 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 + 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 @@ -162,20 +158,24 @@ Oracledb Methods 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 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 + 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 @@ -194,34 +194,34 @@ Oracledb Methods 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. + 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. + 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. + 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. + 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. + 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 + 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 @@ -235,15 +235,15 @@ Oracledb Methods 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. + 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 + 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. + attribute to *True*, which may aid code auditing. If the ``mode`` parameter is specified, it must be one of the :ref:`connection authorization modes ` @@ -254,7 +254,7 @@ Oracledb Methods 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. + 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 @@ -274,13 +274,11 @@ Oracledb Methods 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. + mode. The default value is *False*. The ``config_dir`` parameter is expected to be a string that indicates the - directory in which configuration files (tnsnames.ora) are found. This value - is only used in python-oracledb Thin mode. The default is the value of - :attr:`defaults.config_dir`. For python-oracledb Thick mode, use the - ``config_dir`` parameter of :func:`oracledb.init_oracle_client()`. + 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 @@ -320,20 +318,20 @@ Oracledb Methods 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. + 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 ` + *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 + *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 + 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 @@ -349,18 +347,27 @@ Oracledb Methods 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 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 + *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 + *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 `Database Net + Services 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 @@ -386,18 +393,46 @@ Oracledb Methods 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 ``pool_name`` parameter is expected to be a string which specifies the + name of the pool when using multiple DRCP pools with Oracle Database 23.4 + or later. This value is used in both python-oracledb Thin and Thick modes. + See :ref:`DRCP Pool Names `. + 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. + default value is *0*. + + .. versionchanged:: 3.2.0 + + The ``pool_name`` parameter was added. .. versionchanged:: 3.0.0 - The ``pool_alias`` parameter was added. The ``pool`` parameter was - deprecated. Use :meth:`ConnectionPool.acquire()` instead. + The ``pool_alias``, ``instance_name``, ``use_sni``, + ``thick_mode_dsn_passthrough``, and ``extra_auth_params`` parameters + were added. The ``pool`` parameter was deprecated: use + :meth:`ConnectionPool.acquire()` instead. .. versionchanged:: 2.5.0 @@ -428,10 +463,10 @@ Oracledb Methods 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, 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, \ + 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, \ @@ -442,7 +477,9 @@ Oracledb Methods 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, handle=0) + driver_name=oracledb.defaults.driver_name, use_sni=False, \ + thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \ + extra_auth_params=None, pool_name=None, handle=0) Constructor for creating a connection to the database. Returns an :ref:`AsyncConnection Object `. All parameters are optional @@ -525,11 +562,12 @@ Oracledb Methods 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. + 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 ``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 @@ -537,17 +575,20 @@ Oracledb Methods 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 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`. + 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`. @@ -562,31 +603,31 @@ Oracledb Methods 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. + 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. + 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. + 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. + 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. + *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. + 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 @@ -605,7 +646,7 @@ Oracledb Methods 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. + *False*. The ``stmtcachesize`` parameter is expected to be an integer which specifies the initial size of the statement cache. The default is the @@ -616,8 +657,8 @@ Oracledb Methods 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 configuration files (tnsnames.ora) are found. The - default is the value of :attr:`defaults.config_dir`. + 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 @@ -647,19 +688,19 @@ Oracledb Methods 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. + 77949C8A2B04>`__ 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 ` + *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 + *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 + 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 @@ -675,18 +716,27 @@ Oracledb Methods 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 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 + *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 + *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 `Database Net + Services 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 @@ -712,12 +762,31 @@ Oracledb Methods is used in both the python-oracledb Thin and Thick modes. The default is the value of :attr:`defaults.driver_name`. - The ``handle`` parameter is ignored in the python-oracledb Thin mode. + 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 ``pool_name`` parameter is expected to be a string which specifies the + name of the pool when using multiple DRCP pools with Oracle Database 23.4 + or later. This value is used in both python-oracledb Thin and Thick modes. + See :ref:`DRCP Pool Names `. + + The ``thick_mode_dsn_passthrough`` and ``handle`` parameters are ignored in + python-oracledb Thin mode. + + .. versionchanged:: 3.2.0 + + The ``pool_name`` parameter was added. .. versionchanged:: 3.0.0 - The ``pool_alias`` parameter was added. The ``pool`` parameter was - deprecated. Use :meth:`AsyncConnectionPool.acquire()` instead. + The ``pool_alias``, ``instance_name``, ``use_sni``, + ``thick_mode_dsn_passthrough``, and ``extra_auth_params`` parameters + were added. The ``pool`` parameter was deprecated: use + :meth:`AsyncConnectionPool.acquire()` instead. .. versionchanged:: 2.5.0 @@ -747,20 +816,22 @@ Oracledb Methods .. 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, 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, \ + 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, handle=0) + driver_name=oracledb.defaults.driver_name, use_sni=False, \ + thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \ + extra_auth_params=None, pool_name=None, handle=0) Contains all the parameters that can be used to establish a connection to the database. @@ -811,12 +882,13 @@ Oracledb Methods 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. + 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 + 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 @@ -826,20 +898,24 @@ Oracledb Methods 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 + 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 + 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 @@ -858,34 +934,34 @@ Oracledb Methods 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. + 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. + 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. + 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. + 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. + 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 + 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 @@ -899,14 +975,14 @@ Oracledb Methods 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. + 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 + 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 + 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 @@ -917,7 +993,7 @@ Oracledb Methods 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. + 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 @@ -936,13 +1012,11 @@ Oracledb Methods 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. + 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 configuration files (tnsnames.ora) are found. This value - is only used in python-oracledb Thin mode. The default is the value of - :attr:`defaults.config_dir`. For python-oracledb Thick mode, use - the ``config_dir`` parameter of :func:`oracledb.init_oracle_client()`. + 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 @@ -982,20 +1056,20 @@ Oracledb Methods 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. + 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 ` + *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 + *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 + 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 @@ -1011,18 +1085,27 @@ Oracledb Methods 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 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 + *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 + 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 `Database Net + Services 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 @@ -1048,10 +1131,41 @@ Oracledb Methods 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 ``pool_name`` parameter is expected to be a string which specifies the + name of the pool when using multiple DRCP pools with Oracle Database 23.4 + or later. This value is used in both python-oracledb Thin and Thick modes. + See :ref:`DRCP Pool Names `. + 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. + default value is *0*. + + .. versionchanged:: 3.2.0 + + The ``pool_name`` parameter was added. + + .. versionchanged:: 3.0.0 + + The ``instance_name``, ``use_sni``, ``thick_mode_dsn_passthrough`` and + ``extra_auth_params`` parameters were added. .. versionchanged:: 2.5.0 @@ -1083,11 +1197,6 @@ Oracledb Methods Creates a :ref:`pipeline object ` which can be used to process a set of operations against a database. - .. note:: - - In this release, pipelining support is experimental and subject to - change. - .. versionadded:: 2.4.0 .. function:: create_pool(dsn=None, pool_class=oracledb.ConnectionPool, \ @@ -1099,20 +1208,22 @@ Oracledb Methods 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, 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, \ + 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, handle=0) + driver_name=oracledb.defaults.driver_name, use_sni=False, \ + thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \ + extra_auth_params=None, pool_name=None, handle=0) Creates a connection pool with the supplied parameters and returns the :ref:`ConnectionPool object ` for the pool. See :ref:`Connection @@ -1180,12 +1291,12 @@ Oracledb Methods :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 + ``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 + ``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. + of the ``max`` parameter is *2*. If the ``connectiontype`` parameter is specified, all calls to :meth:`ConnectionPool.acquire()` will create connection objects of that @@ -1200,23 +1311,27 @@ Oracledb Methods The ``homogeneous`` parameter is a boolean that indicates whether the connections are homogeneous (same user) or heterogeneous (multiple - users). The default value is True. + 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 + 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. If the value of this parameter - is 0, then the connections are never terminated. The default value is 0. + 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. + value is *0* milliseconds. The ``max_lifetime_session`` parameter is the length of time (in seconds) - that connections can remain in the pool. If the value of this parameter is - 0, then the connections may remain in the pool indefinitely. The default - value is 0. + 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 @@ -1225,12 +1340,12 @@ Oracledb Methods 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. + 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. + 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 @@ -1238,7 +1353,7 @@ Oracledb Methods 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. + value is *60* seconds. The ``ping_timeout`` parameter is the maximum length of time (in milliseconds) that :meth:`ConnectionPool.acquire()` waits for a connection @@ -1246,7 +1361,7 @@ Oracledb Methods 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. + 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 @@ -1281,12 +1396,13 @@ Oracledb Methods 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. + 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 + 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 @@ -1296,20 +1412,24 @@ Oracledb Methods 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 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 + 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 @@ -1326,34 +1446,34 @@ Oracledb Methods 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. + 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. + 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. + 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. + 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. + 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 + 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 @@ -1367,14 +1487,14 @@ Oracledb Methods 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. + 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 + 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`. + parameter to *False*. See :ref:`extauth`. If the ``mode`` parameter is specified, it must be one of the :ref:`connection authorization modes ` @@ -1385,7 +1505,7 @@ Oracledb Methods 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. + 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 @@ -1405,13 +1525,11 @@ Oracledb Methods 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. + mode. The default value is *False*. The ``config_dir`` parameter is expected to be a string that indicates the - directory in which configuration files (tnsnames.ora) are found. This value - is only used in python-oracledb Thin mode. The default is the value of - :attr:`defaults.config_dir`. For python-oracledb Thick mode, use - the ``config_dir`` parameter of :func:`oracledb.init_oracle_client()`. + 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 @@ -1451,20 +1569,20 @@ Oracledb Methods 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. + 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 ` + *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 + *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 + 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 @@ -1480,18 +1598,27 @@ Oracledb Methods 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 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 + *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 + 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 `Database Net + Services 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 @@ -1517,17 +1644,45 @@ Oracledb Methods 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`. + + The ``pool_name`` parameter is expected to be a string which specifies the + name of the pool when using multiple DRCP pools with Oracle Database 23.4 + or later. This value is used in both python-oracledb Thin and Thick modes. + See :ref:`DRCP Pool Names `. + 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. + default value is *0*. + + .. versionchanged:: 3.2.0 + + The ``pool_name`` parameter was added. .. versionchanged:: 3.0.0 - The ``pool_alias`` parameter was added. + The ``pool_alias``, ``instance_name``, ``use_sni``, + ``thick_mode_dsn_passthrough``, and ``extra_auth_params`` parameters + were added. .. versionchanged:: 2.5.0 @@ -1537,9 +1692,9 @@ Oracledb Methods .. 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 + 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 @@ -1564,20 +1719,22 @@ Oracledb Methods 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, 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, \ + 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, handle=0) + driver_name=oracledb.defaults.driver_name, use_sni=False, \ + thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \ + extra_auth_params=None, pool_name=None, handle=0) Creates a connection pool with the supplied parameters and returns the :ref:`AsyncConnectionPool object ` for the pool. @@ -1626,12 +1783,12 @@ Oracledb Methods :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 + ``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 + ``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. + of the ``max`` parameter is *2*. If the ``connectiontype`` parameter is specified, all calls to :meth:`AsyncConnectionPool.acquire()` will create connection objects of @@ -1646,23 +1803,27 @@ Oracledb Methods The ``homogeneous`` parameter is a boolean that indicates whether the connections are homogeneous (same user) or heterogeneous (multiple - users). The default value is True. + 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 + 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. If the value of this parameter - is 0, then the connections are never terminated. The default value is 0. + 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. + value is *0* milliseconds. The ``max_lifetime_session`` parameter is the length of time (in seconds) - that connections can remain in the pool. If the value of this parameter is - 0, then the connections may remain in the pool indefinitely. The default - value is 0. + 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 @@ -1680,7 +1841,7 @@ Oracledb Methods 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. + 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 @@ -1688,7 +1849,7 @@ Oracledb Methods 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. + 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 @@ -1717,11 +1878,12 @@ Oracledb Methods 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. + 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 ``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 @@ -1729,17 +1891,20 @@ Oracledb Methods 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 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`. + 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`. @@ -1752,31 +1917,31 @@ Oracledb Methods 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. + 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. + 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. + 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. + 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. + *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. + 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 @@ -1795,7 +1960,7 @@ Oracledb Methods 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. + is *False*. The ``stmtcachesize`` parameter is expected to be an integer which specifies the initial size of the statement cache. The default is the @@ -1806,8 +1971,8 @@ Oracledb Methods 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 configuration files (tnsnames.ora) are found. The - default is the value of :attr:`defaults.config_dir`. + 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 @@ -1837,19 +2002,19 @@ Oracledb Methods 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. + 77949C8A2B04>`__ 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 ` + *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 + *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 + 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 @@ -1865,18 +2030,27 @@ Oracledb Methods 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 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 + *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 + *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 `Database Net + Services 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 @@ -1902,11 +2076,30 @@ Oracledb Methods is used in both the python-oracledb Thin and Thick modes. The default is the value of :attr:`defaults.driver_name`. - The ``handle`` parameter is ignored in the python-oracledb Thin mode. + 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 ``pool_name`` parameter is expected to be a string which specifies the + name of the pool when using multiple DRCP pools with Oracle Database 23.4 + or later. This value is used in both python-oracledb Thin and Thick modes. + See :ref:`DRCP Pool Names `. + + The ``handle`` and ``thick_mode_dsn_passthrough`` parameters are ignored in + python-oracledb Thin mode. + + .. versionchanged:: 3.2.0 + + The ``pool_name`` parameter was added. .. versionchanged:: 3.0.0 - The ``pool_alias`` parameter was added. + The ``pool_alias``, ``instance_name``, ``use_sni``, + ``thick_mode_dsn_passthrough``, and ``extra_auth_params`` parameters + were added. .. versionchanged:: 2.5.0 @@ -1938,10 +2131,7 @@ Oracledb Methods 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. - + .. dbapimethodextension:: .. function:: Date(year, month, day) @@ -1980,7 +2170,7 @@ Oracledb Methods ``pool_alias`` value to :meth:`oracledb.create_pool()` or :meth:`oracledb.create_pool_async()`. - If a pool with the given name does not exist, None is returned. + If a pool with the given name does not exist, *None* is returned. See :ref:`connpoolcache` for more information. @@ -1990,16 +2180,18 @@ Oracledb Methods error_url=None, driver_name=None) Enables python-oracledb Thick mode by initializing the Oracle Client - library, see :ref:`enablingthick`. The method must be called before any - standalone connection or pool is created. If a connection or pool is first - created in Thin mode, then ``init_oracle_client()`` will raise an exception - and Thick mode cannot be enabled. + 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. - See :ref:`initialization` for more information. - 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 @@ -2045,13 +2237,38 @@ Oracledb Methods 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 + the value of this attribute is *None*, then the default value in python-oracledb Thick mode is like "python-oracledb thk : ". See :ref:`otherinit`. - .. note:: + 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. - This method is an extension to the DB API definition. + - 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). + + .. dbapimethodextension:: + + .. versionchanged:: 3.0.0 + + At completion of the method, the value of :attr:`defaults.config_dir` + may get changed by python-oracledb. .. versionchanged:: 2.5.0 @@ -2062,13 +2279,12 @@ 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. Immediately after python-oracledb is imported, this function will return - True indicating that python-oracledb defaults to Thin mode. If + *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 @@ -2077,11 +2293,10 @@ Oracledb Methods ``is_thin_mode()`` will never change for the lifetime of the process. The attribute :attr:`Connection.thin` can be used to check a connection's - mode. + 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 @@ -2091,15 +2306,14 @@ Oracledb Methods 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. + are defined by the Oracle names server or defined in the ``tnsnames.ora`` + file. .. deprecated:: python-oracledb 1.0 Use the :meth:`oracledb.ConnectParams()` method instead. - .. note:: - - This method is an extension to the DB API definition. + .. dbapimethodextension:: .. function:: PoolParams(min=1, max=2, increment=1, connectiontype=None, \ getmode=oracledb.POOL_GETMODE_WAIT, homogeneous=True, timeout=0, \ @@ -2108,10 +2322,10 @@ Oracledb Methods 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, 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, \ + 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, \ @@ -2122,7 +2336,9 @@ Oracledb Methods 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, handle=0) + driver_name=oracledb.defaults.driver_name, use_sni=False, \ + thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \ + extra_auth_params=None, pool_name=None, handle=0) Creates and returns a :ref:`PoolParams Object `. The object can be passed to :meth:`oracledb.create_pool()`. @@ -2130,14 +2346,14 @@ Oracledb Methods All the parameters are optional. The ``min`` parameter is the minimum number of connections that the pool - should contain. The default value is 1. + 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. + 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. + 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 @@ -2152,23 +2368,27 @@ Oracledb Methods 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 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 + 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 minimim size. If the value of this parameter - is 0, then the connections are never terminated. The default value is 0. + 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. + value is *0* milliseconds. The ``max_lifetime_session`` parameter is the length of time (in seconds) - that connections can remain in the pool. If the value of this parameter is - 0, then the connections may remain in the pool indefinitely. The default - value is 0. + 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 @@ -2176,11 +2396,11 @@ Oracledb Methods 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. + 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. + *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 @@ -2188,7 +2408,7 @@ Oracledb Methods 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. + value is *60* seconds. The ``ping_timeout`` parameter is the maximum length of time (in milliseconds) that :meth:`ConnectionPool.acquire()` waits for a connection @@ -2196,7 +2416,7 @@ Oracledb Methods 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. + 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 @@ -2239,12 +2459,13 @@ Oracledb Methods 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. + 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 + 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 @@ -2254,20 +2475,24 @@ Oracledb Methods 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 + 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 + 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 @@ -2284,34 +2509,34 @@ Oracledb Methods 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. + 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. + 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. + 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. + 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. + 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 + 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 @@ -2323,13 +2548,13 @@ Oracledb Methods 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. + 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. + 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 @@ -2339,7 +2564,7 @@ Oracledb Methods 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. + 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 @@ -2358,13 +2583,11 @@ Oracledb Methods 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. + 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 configuration files (tnsnames.ora) are found. This value - is only used in python-oracledb Thin mode. The default is the value of - :attr:`defaults.config_dir`. For python-oracledb Thick mode, use the - ``config_dir`` parameter of :func:`oracledb.init_oracle_client()`. + 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 @@ -2404,20 +2627,20 @@ Oracledb Methods 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. + 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 ` + *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 + *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 + 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 @@ -2433,18 +2656,27 @@ Oracledb Methods 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 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 + *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 + 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 `Database Net + Services 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 @@ -2470,10 +2702,41 @@ Oracledb Methods 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`. + + The ``pool_name`` parameter is expected to be a string which specifies the + name of the pool when using multiple DRCP pools with Oracle Database 23.4 + or later. This value is used in both python-oracledb Thin and Thick modes. + See :ref:`DRCP Pool Names `. + 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. + default value is *0*. + + .. 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 @@ -2483,9 +2746,9 @@ Oracledb Methods .. 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 + 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 @@ -2500,10 +2763,44 @@ Oracledb Methods 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. + + To unregister a user function, use :meth:`oracledb.unregister_params_hook`. + + See :ref:`registerparamshook`. + + .. dbapimethodextension:: + + .. versionadded:: 3.0.0 .. function:: register_password_type(password_type, hook_function) - Registers a user hook function that will be called internally by + 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 @@ -2515,20 +2812,18 @@ Oracledb Methods 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 + ``hook_function`` parameter set to *None* will result in a previously registered user function being removed and the default behavior restored. 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 hook function that will be called internally by + 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 @@ -2586,14 +2881,12 @@ Oracledb Methods invalid protocol``. Calling :meth:`~oracledb.register_protocol()` with the ``hook_function`` - parameter set to None will result in a previously registered user function + parameter set to *None* will result in a previously registered user function being removed and the default behavior restored. - See :ref:`connectionhook` for more information. + See :ref:`registerprotocolhook` for more information. - .. note:: - - This method is an extension to the DB API definition. + .. dbapimethodextension:: .. versionadded:: 2.5.0 @@ -2603,8 +2896,8 @@ Oracledb Methods .. note:: - The time only data type is not supported by Oracle. Calling this - function will raise a NotSupportedError exception. + A time-only data type is not supported by Oracle Database. Calling this + function raises a NotSupportedError exception. .. function:: TimeFromTicks(ticks) @@ -2615,8 +2908,8 @@ Oracledb Methods .. note:: - The time only data type is not supported by Oracle. Calling this - function will raise a NotSupportedError exception. + A time-only data type is not supported by Oracle Database. Calling this + function raises a NotSupportedError exception. .. function:: Timestamp(year, month, day, hour, minute, second) @@ -2628,6 +2921,15 @@ Oracledb Methods (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()`. + + .. dbapimethodextension:: + + .. versionadded:: 3.0.0 + .. _interval_ym: @@ -2664,9 +2966,7 @@ Oracledb __future__ Object Special object that contains attributes which control the behavior of python-oracledb, allowing for opting in for new features. -.. note:: - - This method is an extension to the DB API definition. +.. dbapimethodextension:: .. _constants: @@ -2700,33 +3000,41 @@ General String constant stating the version of the module. Currently '|release|'. - .. note:: - - This attribute is an extension to the DB API definition. + .. dbapiattributeextension:: 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. - +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_BUFFERED - This constant is used to specify that enqueue/dequeue operations should - enqueue or dequeue buffered messages. + This constant is used to specify that enqueue or dequeue operations should + enqueue or dequeue buffered messages, respectively. For multi-consumer + queues, a `subscriber `__ with buffered delivery + mode needs to be created prior to enqueuing buffered messages. + This mode is not supported for bulk array operations in python-oracledb + Thick mode. .. data:: MSG_PERSISTENT @@ -2743,11 +3051,13 @@ methods. 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. +parameter for the :meth:`Queue.deqone()`, :meth:`Queue.deqmany()`, +:meth:`AsyncQueue.deqone()`, or :meth:`AsyncQueue.deqmany()` methods. +.. dbapiconstantextension:: .. data:: DEQ_BROWSE @@ -2778,11 +3088,13 @@ parameter for the :meth:`Queue.deqone()` or :meth:`Queue.deqmany()` methods. 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. +parameter for the :meth:`Queue.deqone()`, :meth:`Queue.deqmany()`, +:meth:`AsyncQueue.deqone()`, or :meth:`AsyncQueue.deqmany()` methods. +.. dbapiconstantextension:: .. data:: DEQ_FIRST_MSG @@ -2811,11 +3123,13 @@ parameter for the :meth:`Queue.deqone()` or :meth:`Queue.deqmany()` methods. 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. +parameter for the :meth:`Queue.deqone()`, :meth:`Queue.deqmany()`, +:meth:`AsyncQueue.deqone()`, or :meth:`AsyncQueue.deqmany()` methods. +.. dbapiconstantextension:: .. data:: DEQ_IMMEDIATE @@ -2832,11 +3146,13 @@ parameter for the :meth:`Queue.deqone()` or :meth:`Queue.deqmany()` methods. 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. +parameter for the :meth:`Queue.deqone()`, :meth:`Queue.deqmany()`, +:meth:`AsyncQueue.deqone()`, or :meth:`AsyncQueue.deqmany()` methods. +.. dbapiconstantextension:: .. data:: DEQ_NO_WAIT @@ -2853,17 +3169,22 @@ parameter for the :meth:`Queue.deqone()` or :meth:`Queue.deqmany()` methods. 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. +parameter for the :meth:`Queue.enqone()`, :meth:`Queue.enqmany()`, +:meth:`AsyncQueue.enqone()`, or :meth:`AsyncQueue.enqmany()` methods. +.. dbapiconstantextension:: .. data:: ENQ_IMMEDIATE This constant is used to specify that enqueue should perform its work as part of an independent transaction. + The use of this constant with :ref:`bulk enqueuing ` is only + supported in python-oracledb :ref:`Thick mode `. + .. data:: ENQ_ON_COMMIT @@ -2874,13 +3195,16 @@ parameter for the :meth:`Queue.enqone()` or :meth:`Queue.enqmany()` methods. 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 @@ -2905,12 +3229,12 @@ methods. reached. -Advanced Queuing: Other ------------------------ +Advanced Queuing: Other Constants +--------------------------------- -These constants are extensions to the DB API definition. They are special -constants used in advanced queuing. +This section contains other constants that are used for Advanced Queueing. +.. dbapiconstantextension:: .. data:: MSG_NO_DELAY @@ -2939,12 +3263,14 @@ constants used in advanced queuing. 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 @@ -2956,158 +3282,129 @@ definition. 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:: + It can be used for standalone and pooled connections in python-oracledb + Thin mode, and for standalone connections in Thick mode. - This constant can be used for standalone and pooled connections in the - python-oracledb Thin mode, and for standalone connections in the Thick - mode. + Its enumerated value can also be identified by + ``oracledb.AuthMode.DEFAULT``. - This constant deprecates the ``DEFAULT_AUTH`` constant that was used in - cx_Oracle 8.3, and was the default ``mode`` value. + This constant deprecates the ``DEFAULT_AUTH`` constant that was used in the + obsolete cx_Oracle driver, 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:: + It can only be used in python-oracledb Thick mode for standalone + connections. - This constant can only be used in the python-oracledb Thick mode for - standalone connections. + Its enumerated value can also be identified by + ``oracledb.AuthMode.PRELIM``. - This constant deprecates the ``PRELIM_AUTH`` constant that was used in - cx_Oracle 8.3. + This constant deprecates the ``PRELIM_AUTH`` constant that was used in the + obsolete cx_Oracle driver. .. 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``. + It can be used for standalone and pooled connections in python-oracledb + Thin mode, and for standalone connections in Thick mode. - .. 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. + Its enumerated value can also be identified by + ``oracledb.AuthMode.SYSASM``. - This constant deprecates the ``SYSASM`` constant that was used in - cx_Oracle 8.3. + This constant deprecates the ``SYSASM`` constant that was used in the + obsolete cx_Oracle driver. .. 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:: + It can be used for standalone and pooled connections in python-oracledb + Thin mode, and for standalone connections in Thick mode. - This constant can be used for standalone and pooled connections in the - python-oracledb Thin mode, and for standalone connections in the Thick - mode. + Its enumerated value can also be identified by + ``oracledb.AuthMode.SYSBKP``. - This constant deprecates the ``SYSBKP`` constant that was used in - cx_Oracle 8.3. + This constant deprecates the ``SYSBKP`` constant that was used in the + obsolete cx_Oracle driver. .. 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:: + It can be used for standalone and pooled connections in python-oracledb + Thin mode, and for standalone connections in Thick mode. - This constant can be used for standalone and pooled connections in the - python-oracledb Thin mode, and for standalone connections in the Thick - mode. + Its enumerated value can also be identified by + ``oracledb.AuthMode.SYSDBA``. - This constant deprecates the ``SYSDBA`` constant that was used in - cx_Oracle 8.3. + This constant deprecates the ``SYSDBA`` constant that was used in the + obsolete cx_Oracle driver. .. data:: AUTH_MODE_SYSDGD This constant is used to specify that SYSDG access is to be acquired. - This enumerated value can also be identified by - ``oracledb.AuthMode.SYSDGD``. + It can be used for standalone and pooled connections in python-oracledb + Thin mode, and for standalone connections in Thick mode. - .. 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. + Its enumerated value can also be identified by + ``oracledb.AuthMode.SYSDGD``. - This constant deprecates the ``SYSDGD`` constant that was used in - cx_Oracle 8.3. + This constant deprecates the ``SYSDGD`` constant that was used in the + obsolete cx_Oracle driver. .. 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:: + It can be used for standalone and pooled connections in python-oracledb + Thin mode, and for standalone connections in Thick mode. - This constant can be used for standalone and pooled connections in the - python-oracledb Thin mode, and for standalone connections in the Thick - mode. + Its enumerated value can also be identified by + ``oracledb.AuthMode.SYSKMT``. - This constant deprecates the ``SYSKMT`` constant that was used in - cx_Oracle 8.3. + This constant deprecates the ``SYSKMT`` constant that was used in the + obsolete cx_Oracle driver. .. 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:: + It can be used for standalone and pooled connections in python-oracledb + Thin mode, and for standalone connections in Thick mode. - This constant can be used for standalone and pooled connections in the - python-oracledb Thin mode, and for standalone connections in the Thick - mode. + Its enumerated value can also be identified by + ``oracledb.AuthMode.SYSOPER``. - This constant deprecates the ``SYSOPER`` constant that was used in - cx_Oracle 8.3. + This constant deprecates the ``SYSOPER`` constant that was used in the + obsolete cx_Oracle driver. .. 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:: + It can be used for standalone and pooled connections in python-oracledb + Thin mode, and for standalone connections in Thick mode. - This constant can be used for standalone and pooled connections in the - python-oracledb Thin mode, and for standalone connections in the Thick - mode. + Its enumerated value can also be identified by + ``oracledb.AuthMode.SYSRAC``. - This constant deprecates the ``SYSRAC`` constant that was used in - cx_Oracle 8.3. + This constant deprecates the ``SYSRAC`` constant that was used in the + obsolete cx_Oracle driver. .. _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. - -.. note:: - - In this release, pipelining support is experimental and subject to change. +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 @@ -3179,9 +3476,10 @@ added. They are possible values for the :attr:`PipelineOp.op_type` attribute. 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. +The Database Shutdown mode constants are possible values for the ``mode`` +parameter of the :meth:`Connection.shutdown()` method. +.. dbapiconstantextension:: .. data:: DBSHUTDOWN_ABORT @@ -3222,10 +3520,11 @@ values for the ``mode`` parameter of the :meth:`Connection.shutdown()` method. 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. +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. +.. dbapiconstantextension:: .. data:: EVENT_AQ @@ -3280,12 +3579,13 @@ for subscriptions created by the :meth:`Connection.subscribe()` method. 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. +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. +.. dbapiconstantextension:: .. data:: OPCODE_ALLOPS @@ -3335,12 +3635,14 @@ also used by the :attr:`MessageTable.operation` or 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 @@ -3363,7 +3665,7 @@ extensions to the DB API definition ``oracledb.PoolGetMode.FORCEGET``. This constant deprecates the ``SPOOL_ATTRVAL_FORCEGET`` constant that was - used in cx_Oracle 8.3. + used in the obsolete cx_Oracle driver. .. data:: POOL_GETMODE_NOWAIT @@ -3378,7 +3680,8 @@ extensions to the DB API definition ``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. + used in the obsolete cx_Oracle driver, and was the default ``getmode`` + value. .. data:: POOL_GETMODE_WAIT @@ -3390,8 +3693,8 @@ extensions to the DB API definition 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. + This constant deprecates the ``SPOOL_ATTRVAL_WAIT`` constant that was used + in the obsolete cx_Oracle driver. .. data:: POOL_GETMODE_TIMEDWAIT @@ -3405,19 +3708,21 @@ extensions to the DB API definition ``oracledb.PoolGetMode.TIMEDWAIT``. This constant deprecates the ``SPOOL_ATTRVAL_TIMEDWAIT`` constant that was - used in cx_Oracle 8.3. + used in the obsolete cx_Oracle driver. .. _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 @@ -3434,7 +3739,7 @@ DB API definition. ``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. + in the obsolete cx_Oracle driver, and was the default ``purity`` value. .. data:: PURITY_NEW @@ -3444,7 +3749,7 @@ DB API definition. 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. + the obsolete cx_Oracle driver. .. data:: PURITY_SELF @@ -3455,14 +3760,15 @@ DB API definition. 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. + the obsolete cx_Oracle driver. 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. + +.. dbapiconstantextension:: .. data:: SUBSCR_GROUPING_CLASS_TIME @@ -3473,9 +3779,10 @@ method. 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. +The Subscription Grouping Type constants are possible values for the +``groupingType`` parameter of the :meth:`Connection.subscribe()` method. + +.. dbapiconstantextension:: .. data:: SUBSCR_GROUPING_TYPE_SUMMARY @@ -3495,9 +3802,10 @@ method. 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. + +.. dbapiconstantextension:: .. data:: SUBSCR_NAMESPACE_AQ @@ -3515,9 +3823,10 @@ method. 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. +The Subscription Protocol constants are possible values for the ``protocol`` +parameter of the :meth:`Connection.subscribe()` method. + +.. dbapiconstantextension:: .. data:: SUBSCR_PROTO_CALLBACK @@ -3563,9 +3872,11 @@ method. 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. + +.. dbapiconstantextension:: .. data:: SUBSCR_QOS_BEST_EFFORT @@ -4223,5 +4534,116 @@ See :ref:`exception` for usage information. .. attribute:: _Error.isrecoverable Boolean attribute representing whether the error is recoverable or not. - This is False in all cases unless both Oracle Database 12.1 (or later) and - Oracle Client 12.1 (or later) are being used. + This requires Oracle Database 12.1 (or later). If python-oracledb Thick + mode is used, then Oracle Client 12.1 (or later) is also required. + + See :ref:`tg` for more information. + +.. _oracledbplugins: + +Oracledb Plugins +================ + +The `namespace package `__ +``oracledb.plugins`` can contain plugins to extend the capability of +python-oracledb. See :ref:`customplugins`. Note that the namespace +``oracledb.plugins.ldap_support`` is reserved for future use by the +python-oracledb project. + +To use the python-oracledb plugins in your application, import using +``import oracledb.plugins.``, for example:: + + import oracledb.plugins.oci_config_provider + +.. versionadded:: 3.0.0 + +.. _configociplugin: + +Oracle Cloud Infrastructure (OCI) Object Storage Configuration Provider Plugin +------------------------------------------------------------------------------ + +``oci_config_provider`` is a plugin that can be imported to provide access to +database connection credentials and application configuration information +stored in the :ref:`OCI Object Storage configuration provider +`. + +This plugin is implemented as a :ref:`connection protocol hook function +` to handle connection strings which have the prefix +``config-ociobject``, see :ref:`OCI Object Storage connection strings +`. The plugin parses these connection strings and gets the +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 +:meth:`ConnectParams.parse_connect_string()`, see :ref:`usingconnparams`. + +See :ref:`ociobjstorageprovider` for more information. + +.. versionadded:: 3.0.0 + +.. _configazureplugin: + +Azure App Configuration Provider Plugin +--------------------------------------- + +``azure_config_provider`` is a plugin that can be imported to provide access to +database connection credentials and application configuration information +stored in the :ref:`Azure App Configuration provider +`. + +This plugin is implemented as a :ref:`connection protocol hook function +` to handle connection strings which have the prefix +``config-azure``, see :ref:`Azure App Configuration connection strings +`. The plugin parses these connection strings and gets the +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 +:meth:`ConnectParams.parse_connect_string()`, see :ref:`usingconnparams`. + +See :ref:`azureappstorageprovider` for more information. + +.. versionadded:: 3.0.0 + +.. _ocicloudnativeauthplugin: + +Oracle Cloud Infrastructure (OCI) Cloud Native Authentication Plugin +-------------------------------------------------------------------- + +``oci_tokens`` is a plugin that can be imported to use the `Oracle Cloud +Infrastructure (OCI) Software Development Kit (SDK) +`__ for +generating access tokens when authenticating with OCI Identity and Access +Management (IAM) token-based authentication. + +This plugin is implemented as a :ref:`parameter hook function +` which uses the ``extra_auth_params`` parameter values of +your connection and pool creation calls to generate OCI IAM access tokens. +Python-oracledb then uses these tokens to connect to Oracle Database. + +See :ref:`cloudnativeauthoci` for more information. + +.. versionadded:: 3.0.0 + +.. _azurecloudnativeauthplugin: + +Azure Cloud Native Authentication Plugin +---------------------------------------- + +``azure_tokens`` is a plugin that can be imported to use the `Microsoft +Authentication Library (MSAL) +`__ +for generating access tokens when authenticating with OAuth 2.0 token-based +authentication. + +This plugin is implemented as a :ref:`parameter hook function +` which uses the ``extra_auth_params`` parameter values of +your connection and pool creation calls to generate OAuth2 access tokens. +Python-oracledb then uses these tokens to connect to Oracle Database. + +See :ref:`cloudnativeauthoauth` for more information. + +.. versionadded:: 3.0.0 diff --git a/doc/src/api_manual/pipeline.rst b/doc/src/api_manual/pipeline.rst index 93dd02e9..326fe95b 100644 --- a/doc/src/api_manual/pipeline.rst +++ b/doc/src/api_manual/pipeline.rst @@ -4,10 +4,6 @@ API: Pipeline Objects ********************* -.. note:: - - In this release, pipelining support is experimental and subject to change. - Pipelining is only supported in python-oracledb Thin mode with :ref:`asyncio `. See :ref:`pipelining` for more information about pipelining. @@ -173,7 +169,7 @@ PipelineOp Attributes 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. + For all other operations, the value returned is *0*. .. attribute:: PipelineOp.keyword_parameters @@ -189,7 +185,7 @@ PipelineOp Attributes 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. + the value returned is *0*. .. attribute:: PipelineOp.op_type @@ -232,7 +228,7 @@ 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 + objects. This attribute will be *None* for operations that do not return rows. .. versionadded:: 2.5.0 @@ -240,7 +236,7 @@ PipelineOpResult Attributes .. 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. + operation. If no error occurred, then the value *None* is returned. .. attribute:: PipelineOpResult.operation @@ -260,7 +256,8 @@ PipelineOpResult Attributes .. attribute:: PipelineOpResult.warning 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 `. + running this operation. If no warning was encountered, then the value + *None* is returned. See :ref:`PL/SQL Compilation Warnings + `. .. versionadded:: 2.5.0 diff --git a/doc/src/api_manual/pool_params.rst b/doc/src/api_manual/pool_params.rst index 9b998b47..76d3168d 100644 --- a/doc/src/api_manual/pool_params.rst +++ b/doc/src/api_manual/pool_params.rst @@ -18,19 +18,19 @@ PoolParams Methods .. method:: PoolParams.copy() - Creates a copy of the parameters and returns it. + Creates a copy of the parameters and returns it. .. method:: PoolParams.get_connect_string() - Returns the connection string associated with the PoolParams instance. + Returns the connection string associated with the PoolParams instance. .. method:: PoolParams.parse_connect_string(connect_string) - Parses the connect string into its components and stores the parameters. + Parses the connect string into its components and stores the parameters. - 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 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. .. method:: PoolParams.set(min=None, max=None, increment=None, \ connectiontype=None, getmode=None, homogeneous=None, timeout=None, \ @@ -39,35 +39,46 @@ PoolParams Methods 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, 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, \ + 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, handle=None) + driver_name=oracledb.defaults.driver_name, use_sni=None, \ + thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \ + extra_auth_params=None, pool_name=None, handle=None) - Sets one or more of the parameters. + Sets one or more of the parameters. - .. 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: @@ -76,127 +87,132 @@ PoolParams Attributes .. attribute:: PoolParams.connectiontype - 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``. + 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``. - This attribute is supported in both python-oracledb Thin and Thick modes. + 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`. + 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`. - This attribute is supported in both python-oracledb Thin and Thick modes. + 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. + 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*. - This attribute is only supported in python-oracledb Thick mode. The - python-oracledb Thin mode supports only homogeneous modes. + 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. + 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*. - This attribute is supported in both python-oracledb Thin and Thick modes. + 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. + This read-only attribute is an integer that specifies the minimum number + of connections that the pool should contain. The default value is *1*. - This attribute is supported in both python-oracledb Thin and Thick modes. + 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. + This read-only attribute specifies the maximum number of connections that + the pool should contain. The default value is *2*. - This attribute is supported in both python-oracledb Thin and Thick modes. + This attribute is supported in both python-oracledb Thin and Thick modes. .. attribute:: PoolParams.max_lifetime_session - This read-only attribute is an integer that determines the length of time - (in seconds) that connections can remain in the pool. If the value of this - attribute is 0, then the connections may remain in the pool indefinitely. - The default value is 0 seconds. - - This attribute is only supported in python-oracledb Thick mode. + 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 + ``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. + 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*. - This attribute is only supported in python-oracledb Thick mode. + 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 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. .. attribute:: PoolParams.ping_timeout - 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. + 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. - This attribute is supported in both python-oracledb Thin and Thick modes. + This attribute is supported in both python-oracledb Thin and Thick modes. .. versionadded:: 2.3.0 .. attribute:: PoolParams.session_callback - 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. + 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. - This attribute is supported in both python-oracledb Thin and Thick modes. + 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. + This read-only attribute is a boolean that indicates whether SODA + metadata cache should be enabled or not. The default value is *False*. - This attribute is only supported in python-oracledb Thick mode. + This attribute is only supported in python-oracledb Thick mode. .. attribute:: 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. If the value of this attribute is 0, then the connections are - never terminated. The default value is 0 seconds. + 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 attribute is only supported in python-oracledb Thick mode. + 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. + 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. - This attribute is supported in both python-oracledb Thin and Thick modes. + 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 0fc1e620..8a7cb4cb 100644 --- a/doc/src/api_manual/soda.rst +++ b/doc/src/api_manual/soda.rst @@ -80,9 +80,10 @@ the specification in the collection metadata``. SodaDatabase Objects ==================== -The SODA Database object is an extension to the DB API. It is returned by the -method :meth:`Connection.getSodaDatabase()`. +SODA Database objects are returned by the method +:meth:`Connection.getSodaDatabase()`. +.. dbapiobjectextension:: SodaDatabase Methods -------------------- @@ -106,9 +107,10 @@ SodaDatabase Methods lookup?ctx=dblatest&id=GUID-49EFF3D3-9FAB-4DA6-BDE2-2650383566A3>`__ 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. + 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") @@ -117,7 +119,8 @@ SodaDatabase Methods 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 - 'createdOn', 'lastModified' and 'version' will be None. + :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 @@ -152,18 +155,19 @@ SodaDatabase Methods 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. + does not exist, *None* is returned. .. _sodacoll: SodaCollection Objects ====================== -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 +SODA Collection objects are used to represent SODA collections and is created +by methods :meth:`SodaDatabase.createCollection()` and :meth:`SodaDatabase.openCollection()`. +.. dbapiobjectextension:: + SodaCollection Methods ---------------------- @@ -183,8 +187,8 @@ SodaCollection Methods .. method:: SodaCollection.drop() Drops the collection from the database, if it exists. Note that if the - collection was created with mapMode set to True the underlying table will - not be dropped. + collection was created with the ``mapMode`` parameter set to *True* the + underlying table will not be dropped. A boolean value is returned indicating if the collection was actually dropped. @@ -194,12 +198,12 @@ SodaCollection Methods Drops the index with the specified name, if it exists. - The ``force`` parameter, if set to True, can be used to force the dropping of - an index that the underlying Oracle Database domain index doesn't normally - permit. This is only applicable to spatial and JSON search indexes. - See `here `__ - for more information. + 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. A boolean value is returned indicating if the index was actually dropped. @@ -220,7 +224,7 @@ SodaCollection Methods 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. + no documents in the collection, *None* is returned. .. method:: SodaCollection.insertMany(docs) @@ -244,8 +248,8 @@ SodaCollection Methods 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 + ``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 `__ @@ -258,7 +262,8 @@ SodaCollection Methods - This method requires Oracle Client 18.5 and higher. - - Use of the ``hint`` parameter requires Oracle Client 21.3 or higher (or Oracle Client 19 from 19.11). + - Use of the ``hint`` parameter requires Oracle Client 21.3 or higher + (or Oracle Client 19 from 19.11). .. method:: SodaCollection.insertOne(doc) @@ -277,8 +282,8 @@ SodaCollection Methods 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 + ``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 `__ @@ -289,7 +294,8 @@ SodaCollection Methods .. note:: - Use of the ``hint`` parameter requires Oracle Client 21.3 or higher (or Oracle Client 19 from 19.11). + Use of the ``hint`` parameter requires Oracle Client 21.3 or higher + (or Oracle Client 19 from 19.11). .. method:: SodaCollection.listIndexes() @@ -321,8 +327,8 @@ SodaCollection Methods 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 + ``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 `__ @@ -336,7 +342,8 @@ SodaCollection Methods .. note:: - Use of the ``hint`` parameter requires Oracle Client 21.3 or higher (or Oracle Client 19 from 19.11). + Use of the ``hint`` parameter requires Oracle Client 21.3 or higher + (or Oracle Client 19 from 19.11). .. method:: SodaCollection.truncate() @@ -351,9 +358,8 @@ SodaCollection Attributes 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. + `__ for more information. .. attribute:: SodaCollection.name @@ -366,11 +372,13 @@ SodaCollection Attributes 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 +SODA Document objects are returned by the methods +:meth:`SodaDatabase.createDocument()`, :meth:`SodaOperation.getDocuments()` and +:meth:`SodaOperation.getOne()` as well as by iterating over :ref:`SODA document cursors `. +.. dbapiobjectextension:: + SodaDoc Methods --------------- @@ -378,20 +386,20 @@ SodaDoc Methods 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 + this is not the case. If there is no content, however, *None* will be returned. .. method:: SodaDoc.getContentAsBytes() Returns the content of the document as a bytes object. If there is no - content, however, None will be returned. + content, however, *None* will be returned. .. method:: SodaDoc.getContentAsString() 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 + is not known, UTF-8 will be used. If there is no content, however, *None* will be returned. SodaDoc Attributes @@ -403,13 +411,13 @@ SodaDoc Attributes `ISO 8601 `__ format. Documents created by :meth:`SodaDatabase.createDocument()` or fetched from collections where this attribute is not stored will return - None. + *None*. .. attribute:: SodaDoc.key 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. + value assigned to them and return *None*. .. attribute:: SodaDoc.lastModified @@ -418,7 +426,7 @@ SodaDoc Attributes `ISO 8601 `__ format. Documents created by :meth:`SodaDatabase.createDocument()` or fetched from collections where this attribute is not stored will return - None. + *None*. .. attribute:: SodaDoc.mediaType @@ -435,7 +443,7 @@ SodaDoc Attributes 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. + from collections where this attribute is not stored will return *None*. .. _sodadoccur: @@ -443,10 +451,11 @@ SodaDoc Attributes 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 -`. +SODA Document Cursor objects are returned by the method +:meth:`SodaOperation.getCursor()` and implements the iterator protocol. Each +iteration will return a :ref:`SODA document object `. + +.. dbapiobjectextension:: SodaDocCursor Methods --------------------- @@ -463,9 +472,11 @@ SodaDocCursor Methods SodaOperation Objects ===================== -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()`. +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 the +method :meth:`SodaCollection.find()`. + +.. dbapiobjectextension:: SodaOperation Methods --------------------- @@ -483,8 +494,9 @@ SodaOperation Methods 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. + 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. @@ -529,13 +541,13 @@ SodaOperation Methods 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. + 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. As a convenience, the SodaOperation object is returned so that further criteria can be specified by chaining methods together. diff --git a/doc/src/api_manual/sparse_vector.rst b/doc/src/api_manual/sparse_vector.rst new file mode 100644 index 00000000..c597372c --- /dev/null +++ b/doc/src/api_manual/sparse_vector.rst @@ -0,0 +1,30 @@ +.. _sparsevectorsobj: + +************************* +API: SparseVector Objects +************************* + +A SparseVector Object stores information about a sparse vector. This object +can be created with :meth:`oracledb.SparseVector()`. + +See :ref:`sparsevectors` for more information. + +.. versionadded:: 3.0.0 + +SparseVector Attributes +======================= + +.. attribute:: SparseVector.indices + + This read-only attribute is an array that returns the indices (zero-based) + of non-zero values in the vector. + +.. attribute:: SparseVector.num_dimensions + + This read-only attribute is an integer that returns the number of + dimensions of the vector. + +.. attribute:: SparseVector.values + + This read-only attribute is an array that returns the non-zero values + stored in the vector. diff --git a/doc/src/api_manual/subscription.rst b/doc/src/api_manual/subscription.rst index 1c44bc6a..f4e639bf 100644 --- a/doc/src/api_manual/subscription.rst +++ b/doc/src/api_manual/subscription.rst @@ -4,9 +4,7 @@ API: Subscription Objects ************************* -.. note:: - - This object is an extension the DB API. +.. dbapiobjectextension:: Subscription Methods ==================== @@ -14,11 +12,11 @@ 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. + 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 ======================= @@ -37,20 +35,20 @@ Subscription Attributes .. attribute:: Subscription.id - This read-only attribute returns the value of ``REGID`` found in the - database view ``USER_CHANGE_NOTIFICATION_REGS`` or the value of ``REG_ID`` - found in the database view ``USER_SUBSCR_REGISTRATIONS``. For AQ - subscriptions, the value is 0. + 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*. .. attribute:: Subscription.ip_address 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. + this value is *None*. For consistency and compliance with the PEP 8 naming style, the - attribute `ipAddress` was renamed to `ip_address`. The old name will + attribute ``ipAddress`` was renamed to ``ip_address``. The old name will continue to work for a period of time. @@ -77,7 +75,7 @@ Subscription Attributes This read-only attribute returns the port used for callback notifications from the database server. If not set during construction, this value is - zero. + *0*. .. attribute:: Subscription.protocol @@ -95,7 +93,7 @@ Subscription Attributes .. 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 + specified when the subscription was created. A value of *0* indicates that there is no timeout. @@ -104,10 +102,8 @@ Subscription Attributes Message Objects --------------- -.. note:: - - This object is created internally when notification is received and passed - to the callback procedure specified when a subscription is created. +Message objects are created when a notification is received. They are passed to +the callback procedure specified when a subscription is created. .. attribute:: Message.consumer_name @@ -117,7 +113,7 @@ Message Objects multiple consumer queue. For consistency and compliance with the PEP 8 naming style, the - attribute `consumerName` was renamed to `consumer_name`. The old name + attribute ``consumerName`` was renamed to ``consumer_name``. The old name will continue to work for a period of time. @@ -148,7 +144,7 @@ Message Objects with the namespace :data:`oracledb.SUBSCR_NAMESPACE_AQ`. For consistency and compliance with the PEP 8 naming style, the - attribute `queueName` was renamed to `queue_name`. The old name will + attribute ``queueName`` was renamed to ``queue_name``. The old name will continue to work for a period of time. @@ -190,11 +186,9 @@ Message Objects MessageTable Objects -------------------- -.. note:: - - 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. +MessageTable objects are 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.name @@ -219,11 +213,9 @@ MessageTable Objects 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 - table objects. +MessageRow objects are created when a notification is received for each row +changed in a table. They are found in the rows attribute of message table +objects. .. attribute:: MessageRow.operation @@ -240,18 +232,16 @@ MessageRow Objects 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. +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. .. attribute:: MessageQuery.id 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 - Subscription.registerquery when the related query was registered. + :meth:`Subscription.registerquery()` when the related query was registered. .. attribute:: MessageQuery.operation diff --git a/doc/src/api_manual/variable.rst b/doc/src/api_manual/variable.rst index 11cfb2ee..0a14e611 100644 --- a/doc/src/api_manual/variable.rst +++ b/doc/src/api_manual/variable.rst @@ -7,9 +7,7 @@ API: Variable Objects Variable objects are created with :meth:`Cursor.var()` or :func:`Cursor.arrayvar()`. -.. note:: - - The DB API definition does not define this object. +.. dbapiobjectextension:: Variable Methods ================= @@ -39,7 +37,7 @@ Variable Attributes identical to the attribute :attr:`~Variable.numElements`. For consistency and compliance with the PEP 8 naming style, the - attribute `actualElements` was renamed to `actual_elements`. The old + attribute ``actualElements`` was renamed to ``actual_elements``. The old name will continue to work for a period of time. @@ -49,7 +47,7 @@ Variable Attributes element in bytes. For consistency and compliance with the PEP 8 naming style, the - attribute `bufferSize` was renamed to `buffer_size`. The old + attribute ``bufferSize`` was renamed to ``buffer_size``. The old name will continue to work for a period of time. @@ -65,7 +63,7 @@ Variable Attributes 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. + attribute is *None*, the value is bound directly without any conversion. .. attribute:: Variable.num_elements @@ -75,8 +73,8 @@ Variable Attributes or bound to the variable. 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. + attribute ``numElements`` was renamed to ``num_elements``. The old name + will continue to work for a period of time. .. attribute:: Variable.outconverter @@ -84,7 +82,7 @@ Variable Attributes 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 is *None*, the value is returned directly without any conversion. .. attribute:: Variable.size diff --git a/doc/src/conf.py b/doc/src/conf.py index 1520c93b..534ccf3a 100644 --- a/doc/src/conf.py +++ b/doc/src/conf.py @@ -22,7 +22,12 @@ # 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", +] # Add any paths that contain templates here, relative to this directory. templates_path = [".templates"] @@ -36,7 +41,7 @@ # General substitutions. project = "python-oracledb" copyright = ( - "2016, 2024, Oracle and/or its affiliates. All rights reserved. " + "2016, 2025, Oracle and/or its affiliates. All rights reserved. " "Portions Copyright © 2007-2015, Anthony Tuininga. All rights reserved. " "Portions Copyright © 2001-2007, Computronix (Canada) Ltd., " "Edmonton, Alberta, Canada. All rights reserved" diff --git a/doc/src/index.rst b/doc/src/index.rst index 9a3898cf..43ed1d5a 100644 --- a/doc/src/index.rst +++ b/doc/src/index.rst @@ -2,7 +2,9 @@ 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 new name for the cx_Oracle driver. +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. You can use assistive technology products, such as screen readers, while you work with the python-oracledb documentation. You can also use the keyboard @@ -29,20 +31,23 @@ 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 user_guide/troubleshooting.rst user_guide/appendix_a.rst user_guide/appendix_b.rst user_guide/appendix_c.rst + user_guide/appendix_d.rst API Manual ========== @@ -58,17 +63,20 @@ API Manual api_manual/connection_pool.rst api_manual/pool_params.rst api_manual/cursor.rst + api_manual/dataframe.rst api_manual/fetch_info.rst api_manual/variable.rst api_manual/subscription.rst api_manual/lob.rst api_manual/dbobject_type.rst + api_manual/sparse_vector.rst api_manual/aq.rst api_manual/soda.rst api_manual/async_connection.rst 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/license.rst b/doc/src/license.rst index 48d2f928..b81cfd3d 100644 --- a/doc/src/license.rst +++ b/doc/src/license.rst @@ -10,7 +10,7 @@ License .. centered:: **LICENSE AGREEMENT FOR python-oracledb** -Copyright |copy| 2016, 2024 Oracle and/or its affiliates. +Copyright |copy| 2016, 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 diff --git a/doc/src/release_notes.rst b/doc/src/release_notes.rst index a77855e5..dcc4c593 100644 --- a/doc/src/release_notes.rst +++ b/doc/src/release_notes.rst @@ -11,12 +11,223 @@ 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 (TBD) +oracledb 3.2.0 (TBD) -------------------- 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 databases prior to Oracle + Database 23ai + (`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 data frame. + +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. + +Common Changes +++++++++++++++ + +#) Added Instance Principal authentication support when using + :ref:`OCI Cloud Native Authentication `. +#) Improvements to :ref:`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 parameter ``pool_name`` to connection and pool creation methods to + support Oracle Database 23ai 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:`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:`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 ++++++++++++++++++ + +#) Added :ref:`Oracle Advanced Queuing ` support for single + enqueue and dequeue of RAW and Oracle object payload types. +#) Added namespace package :ref:`oracledb.plugins ` for plugins that + can be used to extend the capability of python-oracledb. +#) Added support for property :attr:`ConnectionPool.max_lifetime_session` + (`issue 410 `__). +#) Added parameter :data:`ConnectParams.use_sni` to specify that the TLS SNI + extension should be used to reduce the number of TLS negotiations that are + needed to connect to the database. +#) Added parameter :data:`ConnectParams.instance_name` to specify the instance + name to use when connecting to the database. Added support for setting the + instance name in :ref:`Easy Connect strings `. +#) Added support for Transaction Guard by adding support to get the values of + :attr:`Connection.ltxid` and :attr:`oracledb._Error.isrecoverable`. +#) Improved support for planned database maintenance by internally sending + explicit request boundaries when using python-oracledb connection pools. #) Perform TLS server matching in python-oracledb instead of the Python SSL library to allow alternate names to be checked (`issue 415 `__). @@ -26,8 +237,18 @@ Thin Mode Changes #) The thread that closes connection pools on interpreter shutdown is now only started when the first pool is created and not at module import (`issue 426 `__). +#) Support for :ref:`Pipelining ` is no longer considered a + pre-release. #) Fixed hang when attempting to use pipelining against a database that doesn't support the end of response flag. +#) Fixed hang when using asyncio and a connection is unexpectedly closed by + the database. +#) Fixed bug when using :ref:`asyncio ` and calling a + stored procedure with data that exceeds 32767 bytes in length + (`issue 441 `__). +#) Fixed bug when attempting to fetch a database object stored in a LOB. The + fetch will still fail but with an unsupported error exception instead of a + hang. #) Error ``DPY-6002: The distinguished name (DN) on the server certificate does not match the expected value: "{expected_dn}"`` now shows the expected value. @@ -40,6 +261,14 @@ Thin Mode Changes #) Error ``DPY-3001: bequeath is only supported in python-oracledb thick mode`` is now raised when attempting to connect to the database without a connect string. +#) Error ``DPY-3001: Native Network Encryption and Data Integrity is only + supported in python-oracledb thick mode`` is now the secondary error + message returned when Oracle Net NNE or checksumming is required by the + database. Previously, the error ``DPY-4011: the database or network closed + the connection`` was raised. +#) Optimization: the connect descriptor sent to the database does not include + the RETRY_DELAY parameter unless the RETRY_COUNT parameter is also + specified. #) Internal change: improve low-level encoding and decoding routines. #) Internal change: send buffer length for bind variables without unneeded adjustment. @@ -47,28 +276,95 @@ Thin Mode Changes 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. +#) 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. +#) Fixed bug that caused :attr:`oracledb._Error.isrecoverable` to always be + `False`. + Common Changes ++++++++++++++ +#) Added new methods :meth:`Connection.fetch_df_all()`, + :meth:`Connection.fetch_df_batches()`, + :meth:`AsyncConnection.fetch_df_all()`, and + :meth:`AsyncConnection.fetch_df_batches()` to fetch data as + :ref:`OracleDataFrame objects ` that expose an Apache + Arrow PyCapsule interface for efficient data exchange with external + libraries. See :ref:`dataframeformat`. +#) Added support for Oracle Database 23.7 + :ref:`SPARSE vectors `. #) Added support for :ref:`naming and caching connection pools ` during creation, and retrieving them later from the python-oracledb pool cache with :meth:`oracledb.get_pool()`. -#) Added Centralized Configuration Provider support for :ref:`file-based - configurations `. +#) Added :ref:`Centralized Configuration Provider ` + support for Oracle Cloud Infrastructure Object Storage, Microsoft Azure App + Configuration, and file-based configurations. #) Added :meth:`oracledb.register_password_type()` to allow users to register a function that will be called when a password is supplied as a dictionary containing the key "type". +#) Added :ref:`cloud native authentication ` support through the + integration of Oracle Cloud Infrastructure (OCI) SDK and Azure SDK. +#) Added parameter ``extra_auth_params`` to :meth:`oracledb.connect()`, + :meth:`oracledb.connect_async()`, :meth:`oracledb.create_pool()`, + and :meth:`oracledb.create_pool_async()` which is used to specify the + configuration parameters required for cloud native authentication. +#) Added :meth:`oracledb.register_params_hook()` and + :meth:`oracledb.unregister_params_hook()` which allow users to register or + unregister a function that manipulates the parameters used for creating + pools or standalone connections. See + :ref:`oci_tokens ` and + :ref:`azure_tokens ` plugins which make use of + this functionality. #) Added attributes :attr:`DbObjectAttribute.precision`, :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. +#) 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 + unchanged to the Oracle Client library to parse. Parameters unrecognized by + the driver in :ref:`Easy Connect strings ` are now ignored. + Parameters unrecognized by the driver in the ``DESCRIPTION``, + ``CONNECT_DATA`` and ``SECURITY`` sections of a + :ref:`full connect descriptor ` are passed through + unchanged. All other parameters in other sections of a full connect + descriptor that are unrecognized by the driver are ignored. #) Fixed bug where some :ref:`DbObject ` attributes for database objects defined using ANSI names (including FLOAT and REAL) may have shown as integers. +#) All Oracle errors that result in the connection no longer being usable will + be raised as ``DPY-4011: the database or network closed the connection`` + with the underlying reason being included in the error message. +#) Fix typing issue with :meth:`oracledb.connect()`, + :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` + (`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 + (`issue 448 `__). #) Error ``DPY-2056: registered handler for protocol "{protocol}" failed for arg "{arg}"`` is now raised when an exception occurs when calling the registered handler for a protocol. +#) Added a sample Dockerfile that can be used to create a container for + developing and deploying python-oracledb applications. #) Internal change: improve handling of metadata. +#) Internal build tool change: bumped minimum Cython version to 3.0.10 to + avoid bug in earlier versions. +#) Improved test suite and documentation. oracledb 2.5.1 (December 2024) @@ -138,7 +434,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 `__). @@ -273,8 +569,8 @@ 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) @@ -361,7 +657,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 @@ -693,14 +989,12 @@ 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 23ai. If using + python-oracledb Thick mode, Oracle Client 23ai 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 @@ -727,7 +1021,7 @@ Common Changes #) 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 `__). @@ -778,8 +1072,8 @@ Common Changes (`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`. @@ -874,7 +1168,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. @@ -977,7 +1271,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 @@ -1019,7 +1313,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. @@ -1044,22 +1338,22 @@ 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. @@ -1221,7 +1515,7 @@ 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 @@ -1236,8 +1530,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. @@ -1273,8 +1567,8 @@ 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 `__). @@ -1340,7 +1634,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 @@ -1376,16 +1670,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. +#) 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 @@ -1507,15 +1801,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, @@ -1992,8 +2286,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 `__). @@ -2036,7 +2330,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 @@ -2093,8 +2387,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 @@ -2160,8 +2454,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 @@ -2278,7 +2572,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 @@ -2351,11 +2645,11 @@ 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 @@ -2579,9 +2873,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). @@ -2657,10 +2951,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) diff --git a/doc/src/user_guide/appendix_a.rst b/doc/src/user_guide/appendix_a.rst index faf96cd2..350987ae 100644 --- a/doc/src/user_guide/appendix_a.rst +++ b/doc/src/user_guide/appendix_a.rst @@ -9,27 +9,24 @@ Oracle Database. This mode does not need Oracle Client libraries. However, some additional functionality is available when python-oracledb uses them. Python-oracledb is said to be in 'Thick' mode when Oracle Client libraries are used. Both modes have comprehensive functionality supporting the Python -Database API v2.0 Specification. See :ref:`initialization` for how to enable -Thick mode. +Database API v2.0 Specification `PEP 249 +`__. See :ref:`initialization` for how to +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 - python-oracledb Thick Mode - cx_Oracle 8.3 - * - Python Database API Support (see `PEP 249 `__) - - Yes - a couple of features are not feasible. Many extensions. - - Yes - a couple of features are not feasible. Many extensions. - - Yes - a couple of features are not feasible. Many extensions. * - Oracle Client version - Not applicable - Release 11.2 and later @@ -150,6 +147,10 @@ see :ref:`driverdiff` and :ref:`compatibility`. - Yes - mostly supported. Unknown settings are ignored and not passed to Oracle Database. - Yes - Yes + * - Centralized Configuration Providers (see :ref:`configurationproviders`) + - Yes + - Yes + - No * - One-way TLS connections (see :ref:`onewaytls`) - Yes - Yes @@ -250,16 +251,16 @@ see :ref:`driverdiff` and :ref:`compatibility`. - No - Yes - Yes - * - Advanced Queuing (AQ) (see :ref:`aqusermanual`) - - No - - Yes - must use new API introduced in cx_Oracle 7.2 + * - Oracle Transactional Event Queues and Advanced Queuing (AQ) (see :ref:`aqusermanual`) + - Yes - only "Classic" queues are supported (RAW, named Oracle object, and JSON payloads) + - Yes - Yes * - Call timeouts (see :attr:`Connection.call_timeout`) - Yes - Yes - Yes * - Scrollable cursors (see :ref:`scrollablecursors`) - - No + - Yes - Yes - Yes * - Oracle Database startup and shutdown (see :ref:`startup`) @@ -287,7 +288,7 @@ see :ref:`driverdiff` and :ref:`compatibility`. - Yes - no callback - Yes - no callback * - Transaction Guard (TG) (see :ref:`tg`) - - No + - Yes - Yes - Yes * - Data Guard (DG) and Active Data Guard (ADG) @@ -320,7 +321,7 @@ see :ref:`driverdiff` and :ref:`compatibility`. - Yes * - Two-phase Commit (TPC) (see :ref:`tpc`) - Yes - - Yes - improved support + - Yes - Yes - limited support * - REF CURSORs and Nested Cursors - Yes @@ -368,137 +369,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 + - No relevant notes * - BOOLEAN (PL/SQL and Oracle Database 23ai SQL) - :data:`~oracledb.DB_TYPE_BOOLEAN` - - No relevant notes - 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 60ecd3da..f2725fea 100644 --- a/doc/src/user_guide/appendix_b.rst +++ b/doc/src/user_guide/appendix_b.rst @@ -39,10 +39,10 @@ mode. However, only one of these modes can be used in each Python process: .. note:: The parameters of connection and pool creation functions - :func:`oracledb.connect()` and :func:`oracledb.create_pool()` are now - keyword and not positional in both Thin and Thick modes. This change makes - the python-oracledb driver compliant with the Python Database API - specification PEP 249. The old usage will cause an error, see + :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 the obsolete cx_Oracle driver will cause an error, see :ref:`connerrors`. Connections to a Local Database @@ -73,107 +73,6 @@ In the python-oracledb Thin mode: See :ref:`optnetfiles` and :ref:`optclientfiles` for more information. -.. _diffconnstr: - -Connection Strings ------------------- - -Python-oracledb Thin mode accepts :ref:`Oracle Net Services connection strings -` in the same formats as the Oracle Client libraries used by Thick -mode does, but not all keywords will be supported. - -The following table lists the parameters that are recognized in Thin mode -either in :ref:`Easy Connect ` strings or in :ref:`Connect -Descriptors ` that are either explicitly passed, or are in a -``tnsnames.ora`` file. All unrecognized parameters are ignored. The -connection parameters shown can be used in :meth:`oracledb.connect()`, -:meth:`oracledb.create_pool()`, :meth:`oracledb.connect_async()`, -:meth:`oracledb.create_pool_async()`, :meth:`oracledb.ConnectParams()`, and -:meth:`oracledb.PoolParams()`. - -.. list-table-with-summary:: Oracle Net Keywords Supported in the python-oracledb Thin Mode - :header-rows: 1 - :class: wy-table-responsive - :align: center - :summary: The first column displays the keyword. The second column displays the equivalent oracledb.connect(), oracledb.create_pool(), oracledb.ConnectParams(), or oracledb.PoolParams() parameters. The third column displays the notes. - - * - Oracle Net Keyword - - Equivalent Connection Parameter - - Notes - * - SSL_SERVER_CERT_DN - - ssl_server_cert_dn - - If specified, this value is used for any verification. Otherwise, the hostname will be used. - * - SSL_SERVER_DN_MATCH - - ssl_server_dn_match - - In Thin mode parsing the parameter supports case insensitive on/yes/true values similar to the Thick mode. Any other value is treated as disabling it. - * - WALLET_LOCATION - - wallet_location - - Used in Easy Connect Strings. It is same as ``MY_WALLET_DIRECTORY`` in a connect descriptor. - * - MY_WALLET_DIRECTORY - - wallet_location - - No relevant notes - * - EXPIRE_TIME - - expire_time - - No relevant notes - * - HTTPS_PROXY - - https_proxy - - No relevant notes - * - HTTPS_PROXY_PORT - - https_proxy_port - - No relevant notes - * - RETRY_COUNT - - retry_count - - No relevant notes - * - RETRY_DELAY - - retry_delay - - No relevant notes - * - TRANSPORT_CONNECT_TIMEOUT - - tcp_connect_timeout - - No relevant notes - * - POOL_CONNECTION_CLASS - - cclass - - No relevant notes - * - POOL_PURITY - - purity - - No relevant notes - * - SERVICE_NAME - - service_name - - No relevant notes - * - SID - - sid - - No relevant notes - * - PORT - - port - - No relevant notes - * - PROTOCOL - - protocol - - No relevant notes - -In python-oracledb Thin mode, using the ``POOL_CONNECTION_CLASS`` or -``POOL_PURITY`` parameters in a connection string is similar to setting the -equivalent attributes when creating a connection or connection pool. - -In python-oracledb Thick mode, the ``POOL_CONNECTION_CLASS`` or ``POOL_PURITY`` -values will only work when connected to Oracle Database 21c, or later. Note if -``POOL_PURITY=SELF`` is used in a connect string, then python-oracledb Thick -mode applications will ignore the action to drop the session when attempting to -remove an unusable connections from a pool in some uncommon error cases. It is -recommended to avoid using ``POOL_PURITY=SELF`` in a connect string with -python-oracledb Thick mode. Instead, code the python-oracledb Thick mode -application to explicitly specify the purity and connection class as -attributes. - -The ``ENABLE=BROKEN`` connect descriptor option is not supported in -python-oracledb Thin mode. Use ``expire_time`` instead. - -If a name is given as a connect string, then the python-oracledb Thin mode will -consider it as a Net Service Name and not as the minimal Easy Connect string of -a hostname. The given connect string will be looked up in a ``tnsnames.ora`` -file. This is different from the python-oracledb Thick mode. If supporting a -bare name as a hostname is important to you in the python-oracledb Thin mode, -then you can alter the connection string to include a port number such as -``hostname:1521`` or a protocol such as ``tcp://hostname``. - Token Based Authentication -------------------------- @@ -187,7 +86,7 @@ In the python-oracledb Thin mode: - :ref:`Open Authorization (OAuth 2.0) token based authentication connection strings ` and :ref:`Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) token based authentication connection strings - ` are not supported. Use ``access_token`` parameter of + ` are not supported. Use the ``access_token`` parameter of :func:`oracledb.ConnectParams()` instead. See :ref:`tokenauth`. Transport Layer Security (TLS) Support @@ -206,15 +105,21 @@ Native Network Encryption and Checksumming ------------------------------------------ The python-oracledb Thin mode does not support connections using Oracle -Database native network encryption or checksumming. You can enable -TLS instead of using native network encryption. If native network encryption -or checksumming are required, then use python-oracledb in the Thick mode. -See :ref:`enablingthick`. +Database Native Network Encryption (NNE) or checksumming. You can `enable TLS +`__ instead of using native network encryption. If +native network encryption or checksumming are required, then use +python-oracledb in Thick mode. See :ref:`enablingthick`. + +For example, if you use python-oracledb Thin mode and try to connect to an +Oracle Cloud Infrastructure (OCI) Oracle Base Database (where Native Network +Encryption is set to *REQUIRED* by default in the database ``sqlnet.ora`` +file), the connection will fail with an error like:: + + DPY-3001: Native Network Encryption and Data Integrity is only + supported in python-oracledb thick mode -For example, if you use python-oracledb Thin mode and try to connect to the -Oracle Cloud Infrastructure (OCI) Oracle Base Database where by default native -network encryption is set to REQUIRED in the ``sqlnet.ora`` file of the OCI -Oracle Base Database server, the connection will fail with an error like:: +or:: DPY-4011: the database or network closed the connection @@ -223,6 +128,8 @@ or:: DPY-6000: cannot connect to database. Listener refused connection. (Similar to ORA-12660) +See :ref:`Troubleshooting DPY-3001 ` for more information. + Connection Pooling Differences between Thin and Thick Modes =========================================================== @@ -239,10 +146,9 @@ differs from the python-oracledb Thick mode in the following ways: 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``, ``config_dir``, and - ``debug_jdwp`` parameters. + 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 @@ -254,13 +160,13 @@ 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 the 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` @@ -271,11 +177,10 @@ differs from the python-oracledb Thick mode in the following ways: 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`. @@ -283,14 +188,12 @@ differs from the python-oracledb Thick mode in the following ways: * In python-oracledb Thin mode, the connection pool supports all the :ref:`connection mode privileges `. - The python-oracledb Thick mode only supports the :data:`~oracledb.AUTH_MODE_SYSDBA` - privilege. - Supported Database Data Types in Thin and Thick Modes ===================================================== -The python-oracledb Thin and Thick modes support different Oracle database data -types. See :ref:`supporteddbtypes`. +The python-oracledb Thin and Thick mode support for the UROWID, REF, and +XMLType database data types has some small differences. See +:ref:`supporteddbtypes`. .. _querymetadatadiff: diff --git a/doc/src/user_guide/appendix_c.rst b/doc/src/user_guide/appendix_c.rst index 0ef6fb27..0d8fa3d8 100644 --- a/doc/src/user_guide/appendix_c.rst +++ b/doc/src/user_guide/appendix_c.rst @@ -1,409 +1,63 @@ -.. _upgradecomparison: - ***************************************************** 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`. - -.. _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. Note that AQ is only available in python-oracledb Thick mode. - -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 +8.3. 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`. + + Examples can be found in the `GitHub samples directory + `__. A basic + example is: -- 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:: + .. code-block:: python - python -m pip install oracledb + 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 @@ -411,40 +65,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. - - Only python-oracledb Thick mode will read :ref:`sqlnet.ora ` - files. The Thin mode lets equivalent properties be set in the application - when connecting. + connection = oracledb.connect("scott", pw, "localhost/orclpdb") - 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: @@ -499,7 +137,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 `_. @@ -532,19 +170,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``. @@ -555,55 +192,177 @@ 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. + + python-oracledb Thin mode Error:: -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`. + DPY-1001: not connected to database -9. Review the following sections to see if your application requirements are - satisfied by the python-oracledb Thin mode: + python-oracledb Thick mode Error:: - - :ref:`featuresummary` - - :ref:`driverdiff` + DPY-1001: not connected to database - If your application requirements are not supported by the Thin mode, then - use the python-oracledb Thick mode. + cx_Oracle Error:: -10. Review :ref:`compatibility`. + not connected - If your code base uses an older cx_Oracle version, review the previous - :ref:`release notes ` for additional changes to modernize - the code. + * Scenario 2: The database side of the connection was terminated while the + connection was being used. -11. Modernize code as needed or desired. See :ref:`deprecations` for the list - of deprecations in python-oracledb. + 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 - desired value or set the ``config_dir`` parameter when connecting. For - example: + desired value or set the ``config_dir`` parameter in your connection or pool + creation method call. For example: .. code-block:: python oracledb.defaults.config_dir = "/opt/oracle/config" + or + + .. code-block:: python + + connection = oracledb.connect(user="hr", password=userpwd, dsn="orclpdb", + config_dir="/opt/oracle/config") + + Also, see :ref:`sqlnetclientconfig`. 3. If the ``driver_name`` parameter of :func:`~oracledb.init_oracle_client` had @@ -618,19 +377,38 @@ 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 the 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:`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 @@ -641,37 +419,77 @@ 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`. +.. _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`: +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. -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. +- 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. - 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. In python-oracledb, - ``init_oracle_client()`` can be called multiple times in a Python process - as long as 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 ------------------------------------------ @@ -684,8 +502,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: @@ -714,9 +532,9 @@ 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 : 1.0.0 + python-oracledb thn : 3.0.0 You can customize ``oracledb_upgrade.py`` to your needs. For example, if your connection and pool creation calls always use keyword parameters, you can @@ -743,165 +561,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..b9e113e4 --- /dev/null +++ b/doc/src/user_guide/appendix_d.rst @@ -0,0 +1,294 @@ +.. _frameworks: + +******************************************************* +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 10ababd0..123de2c5 100644 --- a/doc/src/user_guide/aq.rst +++ b/doc/src/user_guide/aq.rst @@ -1,40 +1,85 @@ .. _aqusermanual: -*********************************** -Using Oracle Advanced Queuing (AQ) -*********************************** - -`Oracle Advanced Queuing -`__ is a highly -configurable and scalable messaging feature of Oracle Database. It has -interfaces in various languages, letting you integrate multiple tools in your -architecture. +************************************************************ +Using Oracle Transactional Event Queues and Advanced Queuing +************************************************************ + +`Oracle Transactional Event Queues and Advanced Queuing +`__ are highly +configurable and scalable messaging features of Oracle Database allowing +data-driven and event-driven applications to stream events and communicate with +each other. They have interfaces in various languages, letting you integrate +multiple tools in your architecture. Both Oracle Transactional Event Queues +(TxEventQ) and Advanced Queuing (AQ) "Classic" queues support sending and +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:: - Oracle Advanced Queuing is only supported in the python-oracledb Thick - mode. See :ref:`enablingthick`. - -Python-oracledb uses the updated interface for Oracle Advanced Queuing that -was first introduced in cx_Oracle 7.2. - -Starting from Oracle Database 21c, Advanced Queuing also supports the JSON -payload type. To use the JSON payload type, the Oracle Client libraries must -be version 21 or later. - -There are Advanced Queuing examples in the `GitHub examples + 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 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. + - 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. + * - JMS + - Supported + - Supported for single and array message enqueuing and dequeuing when using Oracle Client 19c (or later) and Oracle Database 23ai. + +**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 `. + +Transactional Event Queues do not support :attr:`EnqOptions.transformation`, +:attr:`DeqOptions.transformation`, or :ref:`Recipient Lists `. + +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. - Creating a Queue ================ -Before being used, queues need to be created in the database. +Before being used in applications, queues need to be created in the database. + +To experiment with queueing, you can grant yourself privileges, for example in +SQL*Plus as a DBA user: + +.. code-block:: sql + + grant aq_administrator_role, aq_user_role to &&username; + grant execute on dbms_aq to &&username; -**Using RAW Payloads** +**Creating RAW Payload Queues** -Queues can be created using the RAW payload type, for example in -SQL*Plus: +To use SQL*Plus to create a Classic Queue for the RAW payload which is suitable +for sending string or bytes messages: .. code-block:: sql @@ -45,13 +90,20 @@ SQL*Plus: end; / -This example creates a RAW queue suitable for sending string or bytes -messages. +To create a Transactional Event Queue for RAW payloads: + +.. code-block:: sql -**Using JSON Payloads** + begin + dbms_aqadm.create_sharded_queue('RAW_SHQ', queue_payload_type=>'RAW'); + dbms_aqadm.start_queue('RAW_SHQ'); + end; + / -Also, queues can be created using the JSON payload type. For example, -in SQL*Plus: +**Creating JSON Payload Queues** + +Queues can also be created for JSON payloads. For example, to create a Classic +Queue in SQL*Plus: .. code-block:: sql @@ -62,26 +114,24 @@ in SQL*Plus: end; / -This example creates a JSON queue suitable for sending JSON data -messages. - Enqueuing Messages ================== To send messages in Python, you connect and get a :ref:`queue `. The -queue can be used for enqueuing, dequeuing, or both as needed. +queue can then be used for enqueuing, dequeuing, or for both. -**Using RAW Payloads** +**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 @@ -94,21 +144,27 @@ messages: queue.enqone(connection.msgproperties(payload=data)) connection.commit() -Since the queue sending the messages is a RAW queue, the strings in this -example will be internally encoded to bytes using ``message.encode()`` +Since the queue is a RAW queue, strings are internally encoded to bytes using +`encode() `__ before being enqueued. -**Using JSON Payloads** +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") - # The second argument (JSON) indicates that the queue is of JSON payload type. -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 @@ -130,10 +186,14 @@ 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. +Dequeuing is performed similarly as shown in the examples below. This returns a +:ref:`MessageProperties ` object containing the message payload +and related attributes. -**Using RAW Payload Type** +**Dequeuing RAW Payloads** + +To dequeue a message, call the method :meth:`Queue.deqone()` or +:meth:`AsyncQueue.deqone()`. For example: .. code-block:: python @@ -142,10 +202,25 @@ Dequeuing is performed similarly. To dequeue a message call the method connection.commit() print(message.payload.decode()) -Note that if the message is expected to be a string, the bytes must -be decoded using ``message.payload.decode()``, as shown. +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()` or +:meth:`AsyncQueue.deqone()` will wait for one to be enqueued. This default +behavior can be altered, see :ref:`aqoptions`. -**Using JSON Payload Type** +Various :ref:`message properties ` can be accessed. For example +to show the :attr:`~MessageProperties.msgid` of a dequeued message: + +.. code-block:: python + + print(message.msgid.hex()) + +**Dequeuing JSON Payloads** + +To dequeue a message, call the method :meth:`Queue.deqone()` or +:meth:`AsyncQueue.deqone()`, for example: .. code-block:: python @@ -179,7 +254,8 @@ And a queue that accepts this type: end; / -You can queue messages: +You can enqueue messages using :meth:`Queue.enqone()` or +:meth:`AsyncQueue.enqone()`, for example: .. code-block:: python @@ -194,7 +270,8 @@ You can queue messages: queue.enqone(connection.msgproperties(payload=book)) connection.commit() -Dequeuing is done like this: +Dequeuing can be done with :meth:`Queue.deqone()` or +:meth:`AsyncQueue.deqone()`, for example: .. code-block:: python @@ -205,18 +282,20 @@ Dequeuing is done like this: connection.commit() print(message.payload.TITLE) # will print Quick Brown Fox +.. _reciplists: Using Recipient Lists ===================== -A list of recipient names can be associated with a message at the time -a message is enqueued. 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. +Classic Queues support Recipient Lists. A list of recipient names can be +associated with a message at the time a message is enqueued. 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. Transactional Event Queues do not support Recipient Lists. -To dequeue a message, the ``consumername`` attribute can be set to -one of the recipient names. The original message recipient list is +To dequeue a message, the :attr:`~DeqOptions.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. @@ -237,6 +316,8 @@ messages intended for that recipient using the ``consumername`` attribute:: queue.deqoptions.consumername = "sub3" m = queue.deqone() +.. _aqoptions: + Changing Queue and Message Options ================================== @@ -245,8 +326,8 @@ Refer to the :ref:`python-oracledb AQ API ` and `__ for details on all of the enqueue and dequeue options available. -Enqueue options can be set. For example, to make it so that an explicit -call to :meth:`~Connection.commit()` on the connection is not needed to commit +Enqueue options can be set. For example, to make it so that an explicit call +to :meth:`~Connection.commit()` on the connection is not needed to send messages: .. code-block:: python @@ -269,18 +350,20 @@ expiration of 60 seconds on a message: queue.enqone(connection.msgproperties(payload="Message", expiration=60)) -This means that if no dequeue operation occurs within 60 seconds that the +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. -:meth:`~Queue.enqmany()` 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 @@ -295,16 +378,18 @@ 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. 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. - -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 f8055652..c806c1d1 100644 --- a/doc/src/user_guide/asyncio.rst +++ b/doc/src/user_guide/asyncio.rst @@ -24,9 +24,9 @@ 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 `, @@ -171,7 +171,9 @@ You can also use shortcut methods on the :ref:`asyncconnobj` object such as :meth:`AsyncConnection.execute()` or :meth:`AsyncConnection.executemany()`. Rows can be fetched using one of the shortcut methods :meth:`AsyncConnection.fetchone()`, -:meth:`AsyncConnection.fetchmany()`, or :meth:`AsyncConnection.fetchall()`. +:meth:`AsyncConnection.fetchmany()`, :meth:`AsyncConnection.fetchall()`, +:meth:`AsyncConnection.fetch_df_all()`, or +:meth:`AsyncConnection.fetch_df_batches()`. An example of using :meth:`AsyncConnection.fetchall()`: @@ -300,10 +302,6 @@ and can destroy transactional consistency. Pipelining Database Operations ============================== -.. note:: - - In this release, pipelining support is experimental and subject to change. - Pipelining allows an application to send multiple, independent statements to Oracle Database with one call. The database can be kept busy without waiting for the application to receive a result set and send the next statement. While diff --git a/doc/src/user_guide/batch_statement.rst b/doc/src/user_guide/batch_statement.rst index 3d0061dd..17a2831a 100644 --- a/doc/src/user_guide/batch_statement.rst +++ b/doc/src/user_guide/batch_statement.rst @@ -1,8 +1,11 @@ .. _batchstmnt: -******************************************* -Executing Batch Statements and Bulk Loading -******************************************* +**************************************** +Batch Statement and Bulk Copy Operations +**************************************** + +Batch Statement Execution +========================= Inserting, updating or deleting multiple rows can be performed efficiently with :meth:`Cursor.executemany()`, making it easy to work with large data sets with @@ -36,7 +39,7 @@ The following tables will be used in the samples that follow: Batch Execution of SQL -====================== +---------------------- The following example inserts five rows into the table ``ParentTable``: @@ -156,7 +159,7 @@ With named bind variables, use named parameters when calling .. _batchplsql: Batch Execution of PL/SQL -========================= +------------------------- Using :meth:`~Cursor.executemany()` can improve performance when PL/SQL functions, procedures, or anonymous blocks need to be called multiple times. @@ -285,7 +288,7 @@ The equivalent code using named binds is: .. _batcherrors: Handling Data Errors -==================== +-------------------- Large datasets may contain some invalid data. When using batch execution as discussed above, the entire batch will be discarded if a single error is @@ -331,7 +334,7 @@ committing. Identifying Affected Rows -========================= +------------------------- When executing a DML statement using :meth:`~Cursor.execute()`, the number of rows affected can be examined by looking at the attribute @@ -361,7 +364,7 @@ is as follows:: DML RETURNING -============= +------------- DML statements like INSERT, UPDATE, DELETE, and MERGE can return values by using the DML RETURNING syntax. A bind variable can be created to accept this data. @@ -396,8 +399,18 @@ arraysize large enough to hold data for each row that is processed. Also, the call to :meth:`Cursor.setinputsizes()` binds this variable immediately so that it does not have to be passed in each row of data. +Bulk Copy Operations +==================== + +Bulk copy operations are facilitated with the use of +:meth:`Cursor.executemany()`, the use of appropriate SQL statements, and the +use of Python modules. + +Also, see :ref:`dataframeformat` and :ref:`Oracle Database Pipelining +`. + Loading CSV Files into Oracle Database -====================================== +-------------------------------------- The :meth:`Cursor.executemany()` method and Python's `csv module `__ can be used to @@ -461,15 +474,38 @@ Depending on data sizes and business requirements, database changes such as temporarily disabling redo logging on the table, or disabling indexes may also be beneficial. -See `load_csv.py `__ for a runnable example. +Creating CSV Files from Oracle Database +--------------------------------------- + +Python's `csv module `__ +can be used to efficiently create CSV (Comma Separated Values) files. For +example: + +.. code-block:: python + + cursor.arraysize = 1000 # tune this for large queries + print(f"Writing to {FILE_NAME}") + with open(FILE_NAME, "w") as f: + writer = csv.writer( + f, lineterminator="\n", quoting=csv.QUOTE_NONNUMERIC + ) + cursor.execute("""select rownum, sysdate, mycol from BigTab""") + writer.writerow(info.name for info in cursor.description) + writer.writerows(cursor) + + +See `samples/write_csv.py `__ for a runnable example. -Copying Data between Databases -============================== -The :meth:`Cursor.executemany()` function is useful for efficiently copying -data from one database to another: +Bulk Copying Data between Databases +----------------------------------- + +The :meth:`Cursor.executemany()` function is useful for copying data from one +database to another: .. code-block:: python @@ -498,7 +534,16 @@ Tune the :attr:`~Cursor.arraysize` value according to notes in :ref:`tuningfetch`. Use ``setinputsizes()`` according to `Predefining Memory Areas`_. -Note that it may be preferable to create a `database link -`__ -between the databases and use an INSERT INTO SELECT statement so that data is -not copied to, and back from, the Python process. +Note that when copying data to another table in the same database, it may be +preferable to use INSERT INTO SELECT or CREATE AS SELECT to avoid the overhead +of copying data to, and back from, the Python process. This also avoids any +data type changes. For example to create a complete copy of a table: + +.. code-block:: python + + cursor.execute("create table new_table as select * from old_table") + +Similarly, when copying to a different database, consider creating a `database +link `__ between the databases and using +INSERT INTO SELECT or CREATE AS SELECT. diff --git a/doc/src/user_guide/bind.rst b/doc/src/user_guide/bind.rst index 806b00b5..fe5394d6 100644 --- a/doc/src/user_guide/bind.rst +++ b/doc/src/user_guide/bind.rst @@ -29,7 +29,7 @@ more than once with different data values. If you do not use bind variables, Oracle must reparse and cache multiple statements. When using bind variables, Oracle Database may be able to reuse the statement execution plan and context. -.. note:: +.. warning:: Never concatenate or interpolate user data into SQL statements: @@ -639,9 +639,9 @@ This produces the output:: Note the use of :meth:`Object.aslist()` which returns the collection element values in index order as a simple Python list. The indices themselves are lost -in this approach. Starting from cx_Oracle 7.0, the associative array can be -turned into a Python dictionary using :meth:`Object.asdict()`. If that value -was printed in the previous example instead, the output would be:: +in this approach. The associative array can be turned into a Python dictionary +using :meth:`Object.asdict()`. If that value was printed in the previous +example instead, the output would be:: {-1048576: 'First element', -576: 'Second element', 284: 'Third element', 8388608: 'Fourth element'} @@ -823,16 +823,16 @@ will accept them but there will be no processing benefit. It is not uncommon for SQL statements to have low hundreds of versions. Sometimes this is expected and not a result of any issue. To determine the reason, find the SQL identifier of the statement and then query -the Oracle Database view `V$SQL_SHARED_CURSOR `__. +the Oracle Database view `V$SQL_SHARED_CURSOR `__. The SQL identifier of a statement can be found in Oracle Database views like -`V$SQLAREA `__ after you have run a statement, or you can find it -*before* you execute the statement by using the `DBMS_SQL_TRANSLATOR.SQL_ID() -`__ function. Make sure to pass in exactly the same SQL -text, including the same whitespace: +`V$SQLAREA `__ after you have run a statement, or you +can find it *before* you execute the statement by using the +`DBMS_SQL_TRANSLATOR.SQL_ID() `__ function. Make sure +to pass in exactly the same SQL text, including the same whitespace: .. code-block:: python diff --git a/doc/src/user_guide/connection_handling.rst b/doc/src/user_guide/connection_handling.rst index c69bd65a..4d2bc68a 100644 --- a/doc/src/user_guide/connection_handling.rst +++ b/doc/src/user_guide/connection_handling.rst @@ -32,38 +32,28 @@ Oracle Client and Oracle Database communicate. There are two ways to create a connection to Oracle Database using python-oracledb: -* **Standalone connections**: :ref:`Standalone connections ` - are useful when the application needs a single connection to a database. - Connections are created by calling :meth:`oracledb.connect()`. - -* **Pooled connections**: :ref:`Connection pooling ` is important for - performance when applications frequently connect and disconnect from the database. - Pools support Oracle's :ref:`high availability ` features and are - recommended for applications that must be reliable. Small pools can also be - useful for applications that want a few connections available for infrequent - use. Pools are created with :meth:`oracledb.create_pool()` at application - initialization time, and then :meth:`ConnectionPool.acquire()` can be called to - obtain a connection from a pool. +* **Standalone connections**: :ref:`Standalone connections + ` are useful when the application needs a single + connection to a database. Connections are created by calling + :meth:`oracledb.connect()`. For :ref:`asyncio `, use + :meth:`oracledb.connect_async()` instead, see :ref:`connasync`. + +* **Pooled connections**: :ref:`Connection pooling ` is important + for performance when applications frequently connect and disconnect from the + database. Pools support Oracle's :ref:`high availability ` + features and are recommended for applications that must be reliable. Small + pools can also be useful for applications that want a few connections + available for infrequent use. Pools are created with + :meth:`oracledb.create_pool()` at application initialization time, and then + :meth:`ConnectionPool.acquire()` can be called to obtain a connection from a + pool. For :ref:`asyncio `, use :meth:`oracledb.create_pool_async()` + and :meth:`AsyncConnectionPool.acquire()` instead, see :ref:`asyncconnpool`. Many connection behaviors can be controlled by python-oracledb connection options. Other settings can be configured in :ref:`optnetfiles` or in :ref:`optclientfiles`. These include limiting the amount of time that opening a connection can take, or enabling :ref:`network encryption `. -.. note:: - - Creating a connection in python-oracledb Thin mode always requires a - connection string, or the database host name and service name, to be - specified. The Thin mode cannot use "bequeath" connections and does not - reference Oracle environment variables ``ORACLE_SID``, ``TWO_TASK``, - or ``LOCAL``. - -.. note:: - - When using python-oracledb in Thin mode, the ``tnsnames.ora`` file will not - be automatically located. The file's directory must explicitly be passed - to the application, see :ref:`optnetfiles`. - .. _standaloneconnection: Standalone Connections @@ -120,28 +110,8 @@ listener port can also be passed: connection = oracledb.connect(user="hr", password=userpwd, host="localhost", port=1521, service_name="orclpdb") -If you like to encapsulate values, parameters can be passed using a -:ref:`ConnectParams Object `: - -.. code-block:: python - - params = oracledb.ConnectParams(host="my_host", port=my_port, service_name="my_service_name") - conn = oracledb.connect(user="my_user", password="my_password", params=params) - -Some values such as the database host name can be specified as ``connect()`` -parameters, as part of the connect string, and in the ``params`` object. If a -``dsn`` is passed, the python-oracledb :ref:`Thick ` mode will -use the ``dsn`` 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`` object. Similar precedence rules also apply to -other values. - A single, combined connection string can be passed to ``connect()`` but this -may cause complications if the password contains '@' or '/' characters: +may cause complications if the password contains "@" or "/" characters: .. code-block:: python @@ -154,6 +124,21 @@ may cause complications if the password contains '@' or '/' characters: dsn = f'{username}/{userpwd}@{host}:{port}/{service_name}' connection = oracledb.connect(dsn) +If you like to encapsulate values, parameters can be passed using a +:ref:`ConnectParams Object `: + +.. code-block:: python + + params = oracledb.ConnectParams(host="my_host", port=my_port, service_name="my_service_name") + conn = oracledb.connect(user="my_user", password="my_password", params=params) + +Some values such as the database host name can be specified as ``connect()`` +parameters, as part of the ``dsn`` connection string, and in the ``params`` +object. A final connection string is internally constructed from any ``dsn``, +individual parameters, and ``params`` object values. The precedence is that +values in a ``dsn`` parameter override values passed as individual parameters, +which themselves override values set in the ``params`` object. + Closing Connections +++++++++++++++++++ @@ -286,14 +271,10 @@ of Oracle Database's naming methods: * An Oracle :ref:`Easy Connect ` string * A :ref:`Connect Descriptor ` -* A :ref:`TNS Alias ` mapping to a Connect Descriptor in a +* A :ref:`TNS Alias ` mapping to a Connect Descriptor stored in a :ref:`tnsnames.ora ` file * An :ref:`LDAP URL ` - -The ``dsn`` can additionally refer to a :ref:`Centralized Configuration -Provider `. The following providers are supported: - -* :ref:`File Configuration Provider ` +* A :ref:`Configuration Provider URL ` Connection strings used for JDBC and Oracle SQL Developer need to be altered to be usable as the ``dsn`` value, see :ref:`jdbcconnstring`. @@ -302,6 +283,14 @@ For more information about naming methods, see the `Database Net Services Administrator's Guide `__. +.. note:: + + Creating a connection in python-oracledb Thin mode always requires a + connection string, or the database host name and service name, to be + specified. The Thin mode cannot use "bequeath" connections and does not + reference Oracle environment variables ``ORACLE_SID``, ``TWO_TASK``, + or ``LOCAL``. + .. _easyconnect: Easy Connect Syntax for Connection Strings @@ -310,9 +299,22 @@ Easy Connect Syntax for Connection Strings An `Easy Connect `__ string is often the simplest connection string to use in the data source name parameter ``dsn`` of -connection functions such as :meth:`oracledb.connect()` and -:meth:`oracledb.create_pool()`. This method does not need configuration files -such as :ref:`tnsnames.ora `. +connection functions such as :meth:`oracledb.connect()`, +:meth:`oracledb.create_pool()`, :meth:`oracledb.connect_async()`, and +:meth:`oracledb.create_pool_async()`. + +Using Easy Connect strings means that an external :ref:`tnsnames.ora +` configuration file is not needed. + +The Easy Connect syntax in python-oracledb is:: + + [[protocol:]//]host1{,host12}[:port1]{,host2:port2}{;host1{,host12}[:port1]}[/[service_name][:server][/instance_name]][?parameter_name=value{¶meter_name=value}] + +See the `Database Net Services Administrator's Guide +`__ +and the technical brief `Oracle Database Easy Connect Plus +`__ for more details. For example, to connect to the Oracle Database service ``orclpdb`` that is running on the host ``dbhost.example.com`` with the default Oracle @@ -333,26 +335,38 @@ If the database is using a non-default port, it must be specified: The Easy Connect syntax supports Oracle Database service names. It cannot be used with the older System Identifiers (SID). -The latest `Easy Connect `__ syntax allows the use of -multiple hosts or ports, along with optional entries for the wallet location, -the distinguished name of the database server, and allows some network -configuration options such as the connection timeout and keep-alive values to -be set. This means that a :ref:`sqlnet.ora ` file is not needed -for some common connection scenarios. See the technical brief `Oracle Database -Easy Connect Plus `__ for more information. - -In python-oracledb Thin mode, any unknown Easy Connect options are ignored and -are not passed to the database. See :ref:`Connection String Differences -` for more information. - -In python-oracledb Thick mode, it is the Oracle Client libraries that parse the -Easy Connect string. Check the Easy Connect Naming method in `Oracle Net -Service Administrator's Guide +**Oracle Net Settings in Easy Connect Strings** + +The Easy Connect syntax allows some `Oracle Network and database `__ for the syntax to use in your -version of the Oracle Client libraries. +id=GUID-8C85D289-6AF3-41BC-848B-BF39D32648BA>`__ configuration options to be +set. This means that a :ref:`sqlnet.ora ` file is not needed for +common connection scenarios. + +For example, to set a connection timeout and keep-alive value: + +.. code-block:: python + + connection = oracledb.connect(user="hr", password=userpwd, + dsn="dbhost.example.com/orclpdb?transport_connect_timeout=10&expire_time=2") + + +For more information, see :ref:`connectdesckeywords`. Any Easy Connect +parameters that are not known to python-oracledb are ignored and not passed to +the database. + +**Python-oracledb Settings in Easy Connect Strings** + +Many python-oracledb connection method API arguments can alternatively be +passed as Easy Connect parameters with a "pyo." prefix. For example, to set +the statement cache size used by connections: + +.. code-block:: python + + connection = oracledb.connect(user="hr", password=userpwd, + dsn="dbhost.example.com/orclpdb?pyo.stmtcachesize=50") + +See :ref:`pyoparams` for the usable attributes. .. _conndescriptor: @@ -388,7 +402,14 @@ For example: This prints:: - (DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=tcp)(HOST=dbhost.example.com)(PORT=1521)))(CONNECT_DATA=(SERVICE_NAME=orclpdb))(SECURITY=(SSL_SERVER_DN_MATCH=True))) + (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=dbhost.example.com)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=orclpdb))) + +Syntax is shown in the `Database Net Services Reference +`__. + +Any ``DESCRIPTION``, ``CONNECT_DATA`` and ``SECURITY`` parameters of a full +connect descriptor that are unrecognized by python-oracledb are passed to the +database unchanged. .. _netservice: @@ -398,8 +419,10 @@ TNS Aliases for Connection Strings :ref:`Connect Descriptors ` are commonly stored in a :ref:`tnsnames.ora ` file and associated with a TNS Alias. This alias can be used directly for the data source name parameter ``dsn`` of -:meth:`oracledb.connect()` and :meth:`oracledb.create_pool()`. For example, -given a file ``/opt/oracle/config/tnsnames.ora`` with the following contents:: +:meth:`oracledb.connect()`, :meth:`oracledb.create_pool()`, +:meth:`oracledb.connect_async()`, and :meth:`oracledb.create_pool_async()`. +For example, given a file ``/opt/oracle/config/tnsnames.ora`` with the +following contents:: ORCLPDB = (DESCRIPTION = @@ -410,18 +433,24 @@ given a file ``/opt/oracle/config/tnsnames.ora`` with the following contents:: ) ) -Then you could connect in python-oracledb Thin mode by passing the TNS Alias -"ORCLPDB" (case insensitive) as the ``dsn`` value: +Then you could connect by passing the TNS Alias "ORCLPDB" (case insensitive) as +the ``dsn`` value: .. code-block:: python connection = oracledb.connect(user="hr", password=userpwd, dsn="orclpdb", config_dir="/opt/oracle/config") -More options for how python-oracledb locates ``tnsnames.ora`` files are -detailed in :ref:`optnetfiles`. Note that in python-oracledb Thick mode, the -configuration directory must be set during initialization, not at connection -time. +In python-oracledb Thick mode, the configuration directory can also be set +during library initialization: + +.. code-block:: python + + oracledb.init_oracle_client(config_dir="/opt/oracle/config") + connection = oracledb.connect(user="hr", password=userpwd, dsn="orclpdb") + +More options for how python-oracledb locates :ref:`tnsnames.ora ` +files are detailed in :ref:`usingconfigfiles`. TNS Aliases may also be resolved by :ref:`LDAP `. @@ -434,20 +463,80 @@ Reference `__. For example, python-oracledb Thick mode applications using Oracle -Client 23ai could connect using: +The python-oracledb connection string can be an LDAP URL like: .. code-block:: python ldapurl = "ldaps://ldapserver.example.com/cn=orcl,cn=OracleContext,dc=example,dc=com" connection = oracledb.connect(user="scott", password=pw, dsn=ldapurl) -This syntax is also usable in python-oracledb Thin mode via a :ref:`connection -hook function `, see :ref:`ldapconnections`. +This syntax removes the need for external LDAP and ``sqlnet.ora`` configuration +files. See the technical brief `Oracle Client 23ai LDAP URL Syntax +`__. + +In python-oracledb Thin mode, an additional :ref:`connection protocol hook +function ` is required to handle this connection +protocol, see :ref:`ldapconnections`. A connection protocol hook function is +also required in python-oracledb Thick mode if +:attr:`defaults.thick_mode_dsn_passthrough` is *False*. + +To use LDAP URLs in python-oracledb Thick mode applications when +:attr:`defaults.thick_mode_dsn_passthrough` is *True*, the Oracle Client +libraries must be 23.4, or later. + + +.. _configproviderurl: + +Centralized Configuration Provider URL Connection Strings +--------------------------------------------------------- + +A :ref:`Centralized Configuration Provider ` URL +connection string allows python-oracledb configuration information to be stored +centrally in OCI Object Storage, in Azure App Configuration, or in a local +file. Given a provider URL, python-oracledb will access the information stored +in the configuration provider and use it to connect to Oracle Database. + +The database connect descriptor and any database credentials stored in a +configuration provider will be used by any language driver that accesses the +configuration. Other driver-specific sections can exist. Python-oracledb will +take settings that are in a section with the prefix "pyo", and will ignore +other sections. + +For example, to use connection configuration stored in a local file +``/opt/oracle/my-config.json``: + +.. code-block:: json + + { + "connect_descriptor": "localhost/orclpdb", + "pyo": { + "min": 5, + "max": 10, + "increment": 2 + "stmtcachesize": 4 + } + } + +You could use this to create a connection pool by specifying the ``dsn`` +connection string parameter as: + +.. code-block:: python + + pool = oracledb.create_pool(user="hr", password=userpwd, + dsn="config-file:///opt/oracle/my-config.json") + + +The pool will be created using the pool settings from the configuration. + +The Centralized Configuration Provider URL must begin with +"config-://" where the configuration-provider value can +be set to *ociobject*, *azure*, or *file*, depending on the location of your +configuration information. + +See :ref:`configurationproviders` for more information, particularly regarding +using python-oracledb Thick mode. + +The valid keys for the "pyo" object are shown in :ref:`pyoparams`. .. _jdbcconnstring: @@ -507,91 +596,453 @@ This can be referenced in python-oracledb: connection = oracledb.connect(user="hr", password=userpwd, dsn="finance") -.. _builtinconfigproviders: +.. _connectdesckeywords: -Centralized Configuration Providers -=================================== +Oracle Net Connect Descriptor and Easy Connect Keywords +------------------------------------------------------- -Oracle Database Centralized Configuration Providers allow the storage and -management of database connection credentials and application configuration -information in a central location. +Easy Connect syntax is described in :ref:`easyconnect`. -A configuration provider is used by setting the ``dsn`` parameter of connection -and pool creation methods to specify where the configuration is located. For -example to use connection configuration stored in a local file -``/opt/oracle/my-config.json``: +Connect Descriptor keywords are shown in the `Database Net Services Reference +`__. + +**Notes on specific keywords** + +The ``POOL_CONNECTION_CLASS`` or ``POOL_PURITY`` values will only work when +connected to Oracle Database 21c, or later. Note if ``POOL_PURITY=SELF`` is +used in a connect string, then python-oracledb Thick mode applications will +ignore the action to drop the session when attempting to remove an unusable +connections from a pool in some uncommon error cases. It is recommended to +avoid using ``POOL_PURITY=SELF`` in a connect string with python-oracledb Thick +mode. Instead, code python-oracledb Thick mode applications to explicitly +specify the purity and connection class as attributes. + +The ``ENABLE=BROKEN`` connect descriptor option is not supported by +python-oracledb Thin mode. Use ``EXPIRE_TIME`` instead. + +If a name is given as a connect string, then python-oracledb will consider it +as a Net Service Name and not as the minimal Easy Connect string of a hostname. +The given connect string will be looked up in a :ref:`tnsnames.ora +` file. If supporting a bare name as a hostname is important to +you in python-oracledb, then you can alter the connection string to include a +protocol such as ``tcp://hostname``, or a port number such as +``hostname:1521``. + +In python-oracledb Thick mode, when :attr:`defaults.thick_mode_dsn_passthrough` +is *False*, any ``DESCRIPTION``, ``CONNECT_DATA`` and ``SECURITY`` parameters +of a full connect descriptor that are unrecognized by python-oracledb are +passed to the database unchanged. Any Easy Connect parameters that are not +known to python-oracledb are discarded and not passed to the database. + +.. _pyoparams: + +Python-oracledb Parameters Settable in Easy Connect Strings or Centralized Configuration Providers +-------------------------------------------------------------------------------------------------- + +Some python-oracledb connection and pool creation parameters can be set in +:ref:`Easy Connect strings ` or via a :ref:`Centralized +Configuration Provider `. This is an alternative to +passing explicit arguments to :meth:`oracledb.connect()`, +:meth:`oracledb.create_pool()`, :meth:`oracledb.connect_async()`, or +:meth:`oracledb.create_pool_async()`. This allows application behavior to be +changed without needing application code to be updated. + +The parameters are shown below in :ref:`this table +`. Parameters have a "pyo." prefix or are under a +"pyo" key. Each of these parameters that is defined in an Easy Connect string +or via a Centralized Configuration Provider will take precedence over the value +passed as the equivalent python-oracledb API parameter. + +Parameters that apply to :ref:`pool creation ` will be ignored if +they are used in the context of :ref:`standalone connections +`. Parameters with unknown names will be ignored in both +cases. + +**Python-oracledb Parameters in Easy Connect Strings** + +The Easy Connect parameter names are similar to the python-oracledb method +argument names, but have a "pyo." prefix. For example: .. code-block:: python - connection = oracledb.connect(user="hr", password=userpwd, - dsn="config-file:///opt/oracle/my-config.json") + cs = "host.example.com:1522/orclpdb?pyo.stmtcachesize=30&pyo.mode=SYSDBA" + connection = oracledb.connect(user="hr", password=userpwd, dsn=cs) -The following providers are supported by python-oracledb: +is the same as: -* :ref:`File Configuration Provider ` +.. code-block:: python + + cs = "host.example.com:1522/orclpdb" + connection = oracledb.connect(user="hr", password=userpwd, dsn=cs, + stmtcachesize=30, mode=oracledb.AuthMode.SYSDBA) + +If a parameter is specified multiple times in an Easy Connect string, then the +last value of that parameter is used. For example, in +"localhost/orclpdb?pyo.sdu=10&pyo.sdu=20" the SDU is set to 20. + +Note some Oracle Net parameters can also be prefixed with "pyo.". + +Parameters with the prefix "pyo." can only be used in Easy Connect strings and +not in :ref:`Connect Descriptors `. + +**Python-oracledb Parameters in Configuration Providers** + +With the :ref:`File Centralized Configuration Provider ` or +:ref:`OCI Object Storage Centralized Configuration Provider +`, the settable python-oracledb driver attributes should +be in the JSON file under the key "pyo". An example is: + +.. code-block:: json + + { + "connect_descriptor": "localhost/orclpdb", + "pyo": { + "min": 5, + "max": 10, + "increment": 2 + "stmtcachesize": 4 + } + } + +With :ref:`Azure App Configuration `, values are set +using a key such as "/pyo/". This is similar to how `Oracle +Call Interface `__ settings use the key "/oci/" as shown in +`Oracle Net Service Administrator’s Guide `__. + +.. _params_ez_config_provider: + +**Parameter Names** + +When used in Easy Connect Strings, the parameter names should be prefixed with +"pyo.". When used in a Centralized Configuration Provider, the parameter +names are used to form the key names under a parent "pyo" key or with a "pyo/" +prefix. The names are case insensitive. + +.. list-table-with-summary:: Python-oracledb parameters usable in Easy Connect Strings or Centralized Configuration Providers + :header-rows: 1 + :class: wy-table-responsive + :align: center + :name: _params_ez_config_provider_table + :summary: The first column displays the base parameter name. The second column displays the type of the parameter. The third column displays the equivalent API parameter name. The fourth column contains notes. + + * - Base Parameter Name + - Type/Value + - Equivalent python-oracledb Connection Parameter Name + - Notes + * - ``CCLASS`` + - String + - ``cclass`` + - No relevant notes + * - ``CONNECTION_ID_PREFIX`` + - String + - ``connection_id_prefix`` + - No relevant notes + * - ``DISABLE_OOB`` + - String representing a boolean. Values may be one of *on* or *off*, *true* or *false*, *yes* or *no* (case insensitive). + - ``disable_oob`` + - No relevant notes + * - ``DRIVER_NAME`` + - String + - ``driver_name`` + - No relevant notes + * - ``EDITION`` + - String + - ``edition`` + - No relevant notes + * - ``EVENTS`` + - String representing a boolean. Values may be one of *on* or *off*, *true* or *false*, *yes* or *no* (case insensitive). + - ``events`` + - No relevant notes + * - ``EXPIRE_TIME`` + - Integer + - ``expire_time`` + - No relevant notes + * - ``EXTERNALAUTH`` + - String representing a boolean. Values may be one of *on* or *off*, *true* or *false*, *yes* or *no* (case insensitive). + - ``externalauth`` + - No relevant notes + * - ``EXTRA_AUTH_PARAMS`` + - A dictionary containing the configuration parameters necessary for Oracle Database authentication using :ref:`OCI ` or :ref:`Azure ` cloud native authentication plugins. + - ``extra_auth_params`` + - For use by Centralized Configuration Providers only + * - ``GETMODE`` + - String, values may be one of *FORCEGET*, *NOWAIT*, *WAIT*, or *TIMEDWAIT* mapping to :ref:`connpoolmodes`. + - ``getmode`` + - Pool creation only + * - ``HOMOGENEOUS`` + - String representing a boolean. Values may be one of *on* or *off*, *true* or *false*, *yes* or *no* (case insensitive). + - ``homogeneous`` + - Pool creation only + * - ``HTTPS_PROXY`` + - String + - ``https_proxy`` + - No relevant notes + * - ``HTTPS_PROXY_PORT`` + - Integer + - ``https_proxy_port`` + - No relevant notes + * - ``INCREMENT`` + - Integer + - ``increment`` + - Pool creation only + * - ``MACHINE`` + - String + - ``machine`` + - No relevant notes + * - ``MAX`` + - Integer + - ``max`` + - Pool creation only + * - ``MAX_LIFETIME_SESSION`` + - Integer + - ``max_lifetime_session`` + - Pool creation only + * - ``MAX_SESSIONS_PER_SHARD`` + - Integer + - ``max_sessions_per_shard`` + - Pool creation only + * - ``MIN`` + - Integer + - ``min`` + - Pool creation only + * - ``MODE`` + - String, values may be one of *DEFAULT*, *PRELIM*, *SYSASM*, *SYSBKP*, *SYSDBA*, *SYSDGD*, *SYSKMT*, *SYSOPER*, or *SYSRAC* mapping to :ref:`connection-authorization-modes`. + - ``mode`` + - No relevant notes + * - ``OSUSER`` + - String + - ``osuser`` + - No relevant notes + * - ``PING_INTERVAL`` + - Integer + - ``ping_interval`` + - Pool creation only + * - ``PING_TIMEOUT`` + - Integer + - ``ping_timeout`` + - Pool creation only + * - ``POOL_BOUNDARY`` + - String + - ``pool_boundary`` + - No relevant notes + * - ``PROGRAM`` + - String + - ``program`` + - No relevant notes + * - ``PURITY`` + - String, values may be one of *DEFAULT*, *NEW*, or *SELF* mapping to :ref:`drcppurityconsts`. + - ``purity`` + - No relevant notes + * - ``RETRY_COUNT`` + - Integer + - ``retry_count`` + - No relevant notes + * - ``RETRY_DELAY`` + - Integer + - ``retry_delay`` + - No relevant notes + * - ``SDU`` + - Integer + - ``sdu`` + - No relevant notes + * - ``SODA_METADATA_CACHE`` + - String representing a boolean. Values may be one of *on* or *off*, *true* or *false*, *yes* or *no* (case insensitive). + - ``soda_metadata_cache`` + - Pool creation only + * - ``SSL_SERVER_CERT_DN`` + - String + - ``ssl_server_cert_dn`` + - No relevant notes + * - ``SSL_SERVER_DN_MATCH`` + - String representing a boolean. Values may be one of *on* or *off*, *true* or *false*, *yes* or *no* (case insensitive). + - ``ssl_server_dn_match`` + - No relevant notes + * - ``STMTCACHESIZE`` + - Integer + - ``stmtcachesize`` + - No relevant notes + * - ``TCP_CONNECT_TIMEOUT`` + - Integer + - ``tcp_connect_timeout`` + - No relevant notes + * - ``TERMINAL`` + - String + - ``terminal`` + - No relevant notes + * - ``TIMEOUT`` + - Integer + - ``timeout`` + - Pool creation only + * - ``USE_TCP_FAST_OPEN`` + - String representing a boolean. Values may be one of *on* or *off*, *true* or *false*, *yes* or *no* (case insensitive). + - ``use_tcp_fast_open`` + - No relevant notes + * - ``USE_SNI`` + - String representing a boolean. Values may be one of *on* or *off*, *true* or *false*, *yes* or *no* (case insensitive). + - ``use_sni`` + - No relevant notes + * - ``WAIT_TIMEOUT`` + - Integer + - ``wait_timeout`` + - Pool creation only + * - ``WALLET_LOCATION`` + - String + - ``wallet_location`` + - Not recommended for use in Configuration Providers because the path name may not be valid on any particular application host. + +.. _configurationproviders: + +Centralized Configuration Providers +=================================== + +`Centralized Configuration Providers `__ allow the storage +and management of database connection credentials and application configuration +information in a central location. Providers allow you to separately store +configuration information from the code of your application. The values that +can be stored includes the database connection string, database credentials, a +cache time, and python-oracledb specific attributes such as connection pool +settings. Python-oracledb can use the centrally stored information to connect +to Oracle Database with :meth:`oracledb.connect()`, +:meth:`oracledb.create_pool()`, :meth:`oracledb.connect_async()`, and +:meth:`oracledb.create_pool_async()`. + +The following configuration providers are supported by python-oracledb: + +- :ref:`File Centralized Configuration Provider ` +- :ref:`Oracle Cloud Infrastructure (OCI) Object Storage Centralized + Configuration Provider ` +- :ref:`Microsoft Azure App Centralized Configuration Provider + ` + +To use python-oracledb :ref:`Centralized Configuration Provider +` functionality in Thick mode, you should set +:attr:`defaults.thick_mode_dsn_passthrough` to *False*. Alternatively use +:meth:`ConnectParams.parse_connect_string()`, see :ref:`usingconnparams`. + +Note: In Thick mode, when :attr:`defaults.thick_mode_dsn_passthrough` is +*True*, it is the Oracle Client libraries that access the configuration +provider when python-oracledb connection or pool creation methods are +invoked. Any python-oracledb parameter section will be ignored. Any Oracle +Client Interface parameter section should be *removed* from the configuration +because its values may be different to those that python-oracledb assumes, and +will cause undefined behavior. + +**Precedence of Attributes** + +Defining attributes in multiple places is not recommended. However, if +you have defined the values of ``user`` and ``password`` in both the +application and the configuration provider, then the values defined in the +application will have the higher precedence. If the ``externalauth`` parameter +is set to *True*, then the ``user`` and ``password`` values specified in the +configuration provider are ignored. + +If other python-oracledb connection attributes have been defined in both the +application and the configuration provider, then the values defined in the +configuration provider will have higher precedence. + +If you are using Thick mode, and have defined python-oracledb attributes in an +``oraaccess.xml`` file (see :ref:`optclientfiles`), the configuration provider, +and the application, then the values defined in the configuration provider will +have the higher precedence followed by the ``oraaccess.xml`` file settings, and +then application settings. .. _fileconfigprovider: -Connecting Using the File Configuration Provider ------------------------------------------------- +Using a File Centralized Configuration Provider +----------------------------------------------- + +The File Centralized Configuration Provider enables the storage and management +of Oracle Database connection information using local files. -The file configuration provider enables the storage and management of Oracle -Database connection information as JSON in a file on your local file system. +To use a File Centralized Configuration Provider, you must: -When a connection or pool creation method is called with the prefix -``config-file://`` for its ``dsn`` parameter, a built-in :ref:`connection hook -function ` is internally invoked. This function parses the DSN -and loads the configuration information which is stored in the specified file -as JSON. The hook function sets the connection information in its -``connect_params`` parameter. This :ref:`ConnectParams ` object is -used by python-oracledb to establish a connection to Oracle Database. +1. Store the connection information in a JSON file on your local file system. -The configuration file must contain at least the database connection -string. Optionally, you can add the database user name, password, and -python-oracledb specific properties. The JSON properties that can be added to -the file are listed in the table below. +2. Set the path to the file in the ``dsn`` parameter of connection and pool + creation methods. -.. list-table-with-summary:: JSON properties for the File Configuration Provider +**File Centralized Configuration Provider JSON File Syntax** + +The configuration file must contain at least a ``connect_descriptor`` key to +specify the database connection string. Optionally, you can store the database +user name, password, a cache time, and :ref:`python-oracledb settings +`. The keys that can be stored in the file are: + +.. list-table-with-summary:: JSON keys for the File Configuration Provider :header-rows: 1 :class: wy-table-responsive :widths: 15 25 15 :name: _file_configuration_provider - :summary: The first column displays the name of the property. The second column displays its description. The third column displays whether the sub-object is required or optional. + :summary: The first column displays the name of the key. The second column displays its description. The third column displays whether the key is required or optional. - * - Sub-object + * - Key - Description - Required or Optional * - ``user`` - The database user name. - Optional * - ``password`` - - The password of the database user, or a dictionary containing the key "type" and password type-specific properties. + - The password of the database user as a dictionary containing the key "type" and password type-specific keys. + + .. warning:: + + Storing passwords in the configuration file should only ever be used in development or test environments. + - Optional * - ``connect_descriptor`` - - The database :ref:`connection string `. The file must contain this property. + - The database :ref:`connection string `. - Required + * - ``config_time_to_live`` + - The number of seconds the configuration is cached for. Defaults to 86,400 seconds (24 hours). + - Optional + * - ``config_time_to_live_grace_period`` + - The number of seconds an expired configuration can still be used if a new configuration cannot be obtained. Defaults to 1,800 seconds (30 minutes). + - Optional * - ``pyo`` - - Python-oracledb specific settings. + - See :ref:`pyoparams`. - Optional See the `Oracle Net Service Administrator’s Guide `__ for -more information on these sub-objects. +more information on the generic provider sub-objects usable in JSON files. + +Multiple configurations can be defined by specifying the above keys under +user-chosen, top-level keys, see the example further below. + +**File Centralized Configuration Provider DSN Syntax** -.. warning:: +To use a file provider, specify the ``dsn`` parameter of +:meth:`oracledb.connect()`, :meth:`oracledb.create_pool()`, +:meth:`oracledb.connect_async()`, or :meth:`oracledb.create_pool_async()` using +the following format:: - Storing passwords in the configuration file should only ever be used in - development or test environments. + config-file://[?key=] - When using the password type handler for "base64", a warning message will - be generated: "base64 encoded passwords are insecure". +The elements of the ``dsn`` parameter are detailed in the table below. +.. list-table-with-summary:: Connection String Parameters for File Configuration Provider + :header-rows: 1 + :class: wy-table-responsive + :widths: 20 60 + :name: _connection_string_for_file_configuration_provider + :summary: The first column displays the name of the connection string parameter. The second column displays the description of the connection string parameter. -**Sample File Configuration Provider syntax** + * - Parameter + - Description + * - ``config-file`` + - Indicates that the centralized configuration provider is a file in your local system. + * - + - The file path and name of the JSON file that contains the configuration information. For relative paths, python-oracledb will use the connection or pool creation ``config_dir`` parameter, or :attr:`defaults.config_dir` value, to create an absolute path. + * - ``key`` + - The connection key name used to identify a specific configuration. If this parameter is specified, the file is assumed to contain multiple configurations that are indexed by the key value. If not specified, the file is assumed to contain a single configuration. See the example further below. -.. _singlefileconfiguration: +**File Configuration Provider Examples** -The following sample is an example of the File Configuration Provider syntax:: +An example of File Configuration Provider file syntax is:: { "user": "scott", @@ -607,10 +1058,21 @@ The following sample is an example of the File Configuration Provider syntax:: } } -.. _multiplefileconfigurations: +This encodes the password as base64. See :ref:`ociobjstorageprovider` for +other password examples. Plaintext passwords are not supported. -Multiple configurations can be defined by using keys as shown in the example -below. The key values are user-chosen:: +Note that python-oracledb caches configurations by default, see +:ref:`conncaching`. + +If you have this configuration file in ``/opt/oracle/my-config1.json``, you +could use it like: + +.. code-block:: python + + connection = oracledb.connect(dsn="config-file:///opt/oracle/my-config1.json") + +Multiple configurations can be defined by specifying user-chosen top-level +keys:: { "production": { @@ -626,50 +1088,457 @@ below. The key values are user-chosen:: } } -**Sample Using a File Configuration Provider** +If you have this configuration file in ``/opt/oracle/my-config2.json``, you +could use it like: -To use a provider file, specify the ``dsn`` parameter of -:meth:`oracledb.connect()`, :meth:`oracledb.create_pool()`, -:meth:`oracledb.connect_async()`, or :meth:`oracledb.create_pool_async()` using -the following format:: +.. code-block:: python - config-file://[?key=] + connection = oracledb.connect(user="hr", password=userpwd, + dsn="config-file:///opt/oracle/my-config2.json?key=production") -The parameters of the ``dsn`` parameter are detailed in the table below. -.. list-table-with-summary:: Connection String Parameters for File Configuration Provider +.. _ociobjstorageprovider: + +Using an OCI Object Storage Centralized Configuration Provider +-------------------------------------------------------------- + +The Oracle Cloud Infrastructure (OCI) `Object Storage configuration provider +`__ enables the storage and management of Oracle +Database connection information as JSON in `OCI Object Storage `__. + +To use an OCI Object Storage Centralized Configuration Provider, you must: + +1. Upload a JSON file that contains the connection information into an OCI + Object Storage Bucket. See `Uploading an Object Storage Object to a Bucket + `__ and the `Oracle Net Service + Administrator’s Guide `__ for the steps. + See :ref:`OCI Object Storage Centralized Configuration Provider Parameters + ` for the configuration information that can be added. + +2. Install the Python `OCI `__ module, see + :ref:`ociccpmodules`. + +3. Import the :ref:`oracledb.plugins.oci_config_provider ` + plugin in your application. + +4. :ref:`Use an OCI Object Storage connection string URL ` + in the ``dsn`` parameter of connection and pool creation methods. + +.. _ociconfigparams: + +**OCI Object Storage Centralized Configuration Provider JSON File Syntax** + +The stored JSON configuration file must contain a ``connect_descriptor`` key. +Optionally, you can specify the database user name, password, a cache time, and +python-oracledb attributes. The database password can also be stored securely +using `OCI Vault `__ or `Azure Key Vault +`__. The +keys that can be in the JSON file are listed below. + +.. list-table-with-summary:: JSON Keys for OCI Object Storage Configuration Provider :header-rows: 1 :class: wy-table-responsive - :widths: 20 60 - :name: _connection_string_for_file_configuration_provider - :summary: The first column displays the name of the connection string parameter. The second column displays the description of the connection string parameter. + :widths: 15 25 15 + :name: _oci_object_storage_sub-objects + :summary: The first column displays the name of the key. The second column displays the description of the key. The third column displays whether the key is required or optional. + + * - Key + - Description + - Required or Optional + * - ``user`` + - The database user name. + - Optional + * - ``password`` + - The password of the database user as a dictionary containing the key "type" and password type-specific keys. + - Optional + * - ``connect_descriptor`` + - The database :ref:`connection string `. + - Required + * - ``config_time_to_live`` + - The number of seconds the configuration is cached for. Defaults to 86,400 seconds (24 hours). + - Optional + * - ``config_time_to_live_grace_period`` + - The number of seconds an expired configuration can still be used if a new configuration cannot be obtained. Defaults to 1,800 seconds (30 minutes). + - Optional + * - ``pyo`` + - See :ref:`pyoparams`. + - Optional + +.. _connstringoci: + +**OCI Object Storage Centralized Configuration Provider DSN Syntax** + +The ``dsn`` parameter for :meth:`oracledb.connect()`, +:meth:`oracledb.create_pool()`, :meth:`oracledb.connect_async()`, or +:meth:`oracledb.create_pool_async()` calls should use a connection string URL +in the format:: + + config-ociobject:/n/{namespaceName}/b/{bucketName}/o/ + [/c/][?=&=...] + +The elements of the connection string are detailed in the table below. + +.. list-table-with-summary:: Connection String Parameters for OCI Object Storage + :header-rows: 1 + :class: wy-table-responsive + :widths: 15 25 15 + :name: _connection_string_for_oci_object_storage + :summary: The first row displays the name of the connection string parameter. The second row displays the description of the connection string parameter. The third row displays whether the connection string parameter is required or optional. * - Parameter - Description - * - ``config-file`` - - Indicates that the centralized configuration provider is a file in your local system. - * - - - The file path (absolute or relative path) and name of the JSON file that contains the configuration information. For relative paths, python-oracledb will use the ``config_dir`` value to create an absolute path. - * - ``key`` - - The connection key name used to identify a specific configuration. If this parameter is specified, the file is assumed to contain multiple configurations that are indexed by the key. If not specified, the file is assumed to contain a single configuration. + - Required or Optional + * - ``config-ociobject`` + - Indicates that the configuration provider is OCI Object Storage. + - Required + * - + - The URL of OCI Object Storage endpoint. + - Required + * - + - The OCI Object Storage namespace where the JSON file is stored. + - Required + * - + - The OCI Object Storage bucket name where the JSON file is stored. + - Required + * - + - The JSON file name. + - Required + * - + - The network service name or alias if the JSON file contains one or more network service names. + - Optional + * -